ost-support-workflow

name	ost-support-workflow
description	Use when creating or updating an open_supports support package end-to-end, especially when coordinating repo summary, install script, setup skill, clarification, resume, or optional install verification.
argument-hint	GitHub owner/repo, e.g. colbymchenry/codegraph

open_supports 支持包工作流

When to Use

• 为 open_supports/ 新增一个开源库支持包
• 更新已有支持包的摘要、安装脚本或安装 Skill
• 从 .ost-workflow-state/ 恢复中断的支持包工作流

Pre-read

主 workflow 执行前只允许预读 workflow-level 轻量材料：

1. open_supports/README.md
2. 目标状态文件 open_supports/.ost-workflow-state/{OwnerName}_{RepoName}.json（如存在）
3. 目标支持包目录和 .ost-refs/ 的文件列表；只在判断恢复、存在性或短本地约定时读取必要短内容
4. 本 workflow 自身的状态脚本用法：open_supports/.copilot-skills/ost-support-workflow/scripts/state.sh --help

主 workflow 不得预读：

• open_supports/workflow-quickstart.md 等设计/教程文档
• 任何阶段 Skill 全文，例如 .copilot-skills/ost-repo-readme-summary/SKILL.md
• 官方 README、官方文档长文、npm package metadata、API 文档长文
• 阶段产物草稿的完整内容，除非用于最终轻量审查

阶段 Skill 只在派发给该阶段子代理的 prompt contract 中引用。主 workflow 不得为了“熟悉阶段要求”提前读取所有阶段 Skill。

External Skill Interference

本任务显式指定 ost-support-workflow 时，它是主流程。 workflow 主代理严禁主动执行 superpowers:using-superpowers skill 或其他外部流程 Skill 来扩大预读范围、替子代理读取阶段材料，或改变本 workflow 的状态/派发纪律。

If this workflow is explicitly selected, the workflow agent must not use external process skills such as superpowers:using-superpowers skill to expand pre-read scope, preload stage materials, or bypass this workflow's dispatch and state rules.

子代理在各自环境中遵循其可见规则，但主 workflow 不得因此替子代理预读阶段 Skill、官方文档或长上下文。

Subagent Tool Discovery

三个核心阶段和用户同意后的 optional_usage_examples 必须优先由子代理串行执行。

开始派发前，主 workflow 必须确认子代理能力：

1. 如果当前可见工具列表中已经有可用的子代理 / multi-agent / spawn-agent 工具，使用该工具串行派发阶段。
2. 如果当前工具列表没有可见子代理工具，必须先通过 tool_search 搜索 multi-agent、subagent 或 spawn agent 能力。
3. 如果搜索到可用工具，必须使用它串行派发阶段；generic subagent 可作为 workaround，但状态摘要必须注明 generic-agent workaround。
4. 只有在工具不存在、tool_search 确认不可用、工具 schema 不满足最低调度要求、用户明确要求不用子代理，或子代理连续失败后用户明确同意 inline 接管时，才允许 inline fallback。
5. fallback 原因必须具体写入状态，不能写成泛泛的 tool unavailable。

GitHub Source Policy

阶段子代理获取 GitHub 仓库事实、README、目录、release、issue、PR 或文件内容时，必须遵循以下来源优先级：

1. 本地支持包文件和 .ost-refs/
2. GitHub connector / GitHub app tools
3. gh CLI 或 GitHub 官方 API
4. 官方文档网站
5. curl / raw GitHub URL，仅作为记录原因的 fallback

curl 不是禁止项：官方安装文档明确给出的 curl | sh、release asset 下载、验证本地 HTTP 服务，或 GitHub connector / gh / 官方 API 不可用且需要降级时可以使用。除官方安装命令本身外，使用 curl 获取 GitHub 信息必须在阶段结果的 fallbacks 中说明原因。

主 workflow 不得为了审计来源而预读官方 README 或长文档。主 workflow 只把本 policy 放入 dispatch contract，并检查阶段子代理返回的 sources_used / fallbacks 摘要是否存在且合理。

Workflow

按顺序执行五个阶段：

1. repo_readme_summary：串行派发阶段子代理，在 contract 中引用 .copilot-skills/ost-repo-readme-summary/SKILL.md，产出 repo_readme_summary.md
2. install_script：串行派发阶段子代理，在 contract 中引用 .copilot-skills/ost-install-script/SKILL.md，产出 scripts_for_install/install.*
3. skill_for_setup：串行派发阶段子代理，在 contract 中引用 .copilot-skills/ost-skill-for-setup/SKILL.md，产出 skill_for_setup/README.md 和 skill_for_setup/ost_*_install/SKILL.md
4. optional_usage_examples：按 checklist 判断是否建议生成；用户同意后串行派发阶段子代理，在 contract 中引用 .copilot-skills/ost-usage-examples/SKILL.md，产出 usage_examples.md
5. optional_test_install：询问用户是否测试运行安装脚本并验证安装成功

不要假设客户端支持嵌套调用 Skill；本 Skill 的职责是编排、状态管理、澄清和恢复。阶段细节以对应阶段 Skill 为准。

三个核心产出阶段和可选 optional_usage_examples 阶段默认使用子代理执行，但必须串行执行，不能并行。optional_test_install 默认由主 workflow 控制，因为它可能真实修改本机 CLI / Agent 配置。

Stage Subagents

主 workflow 是唯一状态管理者和唯一用户交互者。阶段子代理只执行一个阶段，不直接询问用户，不直接写 .ost-workflow-state/*.json。

派发阶段子代理前：

1. 使用状态脚本将阶段设为 in_progress
2. 构造并持久化 dispatch contract 摘要
3. 给子代理提供目标阶段、目标支持包目录、对应阶段 Skill 路径、必要的上一阶段产物路径、已有用户澄清答案
4. 明确要求子代理只返回结构化结果

最小 dispatch contract：

{
  "stage": "install_script",
  "package_dir": "open_supports/ost_owner_repo",
  "stage_skill_path": "open_supports/.copilot-skills/ost-install-script/SKILL.md",
  "required_inputs": [
    "repo_readme_summary.md"
  ],
  "clarification_answers": [],
  "allowed_outputs": [
    "DONE",
    "NEEDS_CLARIFICATION",
    "FAILED"
  ],
  "tool_policy": {
    "github_source_priority": [
      "local package files and .ost-refs",
      "GitHub connector / GitHub app tools",
      "gh CLI or GitHub official API",
      "official documentation website",
      "curl/raw GitHub URLs only as recorded fallback"
    ],
    "curl_boundary": "Allowed for official install commands and explicit fallback only; not the default for repository fact gathering.",
    "fallback_reporting": "Return sources_used and fallbacks when lower-priority tools are used."
  },
  "context_hygiene": {
    "do_not_return": [
      "long official docs excerpts",
      "full README",
      "full generated files",
      "step-by-step private reasoning"
    ]
  }
}

派发前用状态脚本保存可审计 contract 摘要：

sh open_supports/.copilot-skills/ost-support-workflow/scripts/state.sh contract OWNER/REPO install_script open_supports/ost_owner_repo open_supports/.copilot-skills/ost-install-script/SKILL.md repo_readme_summary.md DONE,NEEDS_CLARIFICATION,FAILED

阶段子代理只能返回：

• DONE
• NEEDS_CLARIFICATION
• FAILED

收到 DONE：主 workflow 审查产物路径，使用状态脚本记录 agent-run ... DONE ...，再将阶段设为 done。

收到 NEEDS_CLARIFICATION：主 workflow 使用状态脚本记录 agent-run ... NEEDS_CLARIFICATION ...，再用 block ... 写入阻塞问题，然后只向用户提出该问题。

收到 FAILED：主 workflow 使用状态脚本记录 agent-run ... FAILED ...，将阶段标记为 failed，再询问用户下一步。

optional_usage_examples 被用户同意后，按普通阶段子代理处理；用户拒绝或 checklist 未命中时不派发子代理，直接标记为 skipped。

如果允许 inline fallback，不能使用 agent-run 伪装成子代理结果；必须使用：

sh open_supports/.copilot-skills/ost-support-workflow/scripts/state.sh inline-run OWNER/REPO STAGE STATUS SUMMARY "specific fallback reason"

最终报告必须说明是否使用过 fallback，以及每次 fallback 的具体原因。

Context Hygiene

主 workflow 必须尽可能保持上下文干净、节省。阶段子代理用于隔离重上下文，避免把官方 README、长文档、详细推理过程或完整中间草稿回灌给主 workflow。

阶段子代理只返回满足编排所需的最小关键信息：

• status: DONE、NEEDS_CLARIFICATION 或 FAILED
• stage: 当前阶段名
• summary: 1-3 条结果摘要
• files_changed: 产物文件路径列表
• verification: 已执行的轻量检查及结果
• sources_used: 来源类别和关键路径摘要，例如 github_connector: fetch_file owner/repo README.md 或 local: open_supports/ost_owner_repo/.ost-refs/install.md
• fallbacks: 降级或保留 direct HTTP 的原因摘要；没有降级时返回空数组
• clarification: 仅当 NEEDS_CLARIFICATION 时返回，包含 reason、question、suggested_default
• failure: 仅当 FAILED 时返回，包含失败命令、退出码和关键输出摘要

阶段子代理不要返回：

• 大段官方文档摘录
• 完整 README 或完整安装文档
• 详细逐步推理过程
• 与当前阶段无关的发现
• 可从产物文件直接读取的完整内容

主 workflow 若需要审查产物，应读取目标文件本身，而不是要求子代理复制文件内容。状态文件只保存恢复和决策所需信息，不保存长文档或冗余中间过程。

State Management

状态目录：

open_supports/.ost-workflow-state/

状态文件：

open_supports/.ost-workflow-state/{OwnerName}_{RepoName}.json

状态 JSON 包含阶段状态和可选用法示例决策，例如：

{
  "stages": {
    "repo_readme_summary": "pending",
    "install_script": "pending",
    "skill_for_setup": "pending",
    "optional_usage_examples": "pending",
    "optional_test_install": "pending"
  },
  "usage_examples": {
    "offered": false,
    "decision": "pending",
    "matched_criteria": [],
    "result": null
  },
  "execution": {
    "mode": "subagent_preferred",
    "fallback": "inline",
    "current_agent_stage": null,
    "dispatch_contracts": [],
    "agent_runs": [],
    "inline_runs": []
  }
}

状态 JSON 默认不提交 Git。恢复工作流时，先读取对应状态文件：

• 若存在 blocked 或 waiting_user，先复述当前断点和唯一待回答问题
• 用户回答后，把回答写入状态，再回到下一阶段检测
• 若不存在状态文件，创建新状态并从 PreparePackage 开始

状态读写必须优先通过内部脚本完成：

open_supports/.copilot-skills/ost-support-workflow/scripts/state.sh

该脚本使用 sh + jq，只负责 JSON 状态机械读写，不负责 workflow 决策。只有主 workflow 可以调用该脚本；阶段子代理不能直接调用。

所有 state.sh 写操作必须串行执行。主 workflow 不得用 multi_tool_use.parallel 或其他并行机制同时调用 set-stage、contract、agent-run、inline-run、usage-examples、test-result、complete 等写命令。每次写入后，如阶段推进或恢复依赖状态文件，先确认状态 JSON 仍可被 jq 解析。

常用命令：

sh open_supports/.copilot-skills/ost-support-workflow/scripts/state.sh init OWNER/REPO
sh open_supports/.copilot-skills/ost-support-workflow/scripts/state.sh show OWNER/REPO
sh open_supports/.copilot-skills/ost-support-workflow/scripts/state.sh set-stage OWNER/REPO STAGE STATUS
sh open_supports/.copilot-skills/ost-support-workflow/scripts/state.sh block OWNER/REPO STAGE REASON QUESTION [SUGGESTED_DEFAULT]
sh open_supports/.copilot-skills/ost-support-workflow/scripts/state.sh answer OWNER/REPO ANSWER
sh open_supports/.copilot-skills/ost-support-workflow/scripts/state.sh contract OWNER/REPO STAGE PACKAGE_DIR STAGE_SKILL_PATH REQUIRED_INPUTS ALLOWED_OUTPUTS
sh open_supports/.copilot-skills/ost-support-workflow/scripts/state.sh agent-run OWNER/REPO STAGE STATUS SUMMARY
sh open_supports/.copilot-skills/ost-support-workflow/scripts/state.sh inline-run OWNER/REPO STAGE STATUS SUMMARY FALLBACK_REASON
sh open_supports/.copilot-skills/ost-support-workflow/scripts/state.sh offer-usage-examples OWNER/REPO MATCHED_CRITERIA
sh open_supports/.copilot-skills/ost-support-workflow/scripts/state.sh usage-examples OWNER/REPO DECISION MATCHED_CRITERIA [RESULT]
sh open_supports/.copilot-skills/ost-support-workflow/scripts/state.sh test-result OWNER/REPO RESULT COMMAND EXIT_CODE SUMMARY
sh open_supports/.copilot-skills/ost-support-workflow/scripts/state.sh complete OWNER/REPO

RESULT 可省略；省略时 accepted 默认 pending，declined / not_applicable 默认 skipped。

阶段状态只使用：

pending
in_progress
done
blocked
waiting_user
skipped
failed

Package Preparation

目标支持包目录不存在时，可以自动创建最小目录结构：

ost_{OwnerName}_{RepoName}/
ost_{OwnerName}_{RepoName}/scripts_for_install/
ost_{OwnerName}_{RepoName}/skill_for_setup/
ost_{OwnerName}_{RepoName}/skill_for_setup/ost_{OwnerName}_{RepoName}_install/

可以创建缺失目录，但不要自动覆盖已有文件。目标产物已存在时，进入对应阶段的更新或确认逻辑。

Clarification / Blocking

任何阶段遇到关键行为无法从官方文档、现有支持包文件或 .ost-refs/ 可靠判断时：

1. 不要猜测关键行为
2. 将当前阶段标记为 blocked
3. 记录一个澄清项：
   • stage
   • reason
   • question
   • suggested_default（如有）
4. 将 workflow_status 标记为 blocked
5. 向用户提出这个问题，等待回答

最小恢复策略：只处理当前唯一 open clarification，不维护多问题队列。

Optional Usage Examples

三个核心产出阶段完成后，先按以下 checklist 判断是否建议生成 usage_examples.md：

• 官方文档包含 CLI 或可执行命令示例
• 官方文档包含项目初始化流程
• 支持包涉及配置文件或状态目录
• 支持包涉及 Agent、MCP、IDE、Copilot、Claude 或 Codex 接入
• 安装后存在常见工作流或后续操作
• 官方文档提供多个用法场景
• .ost-refs/ 中存在本地约定、项目约定或推荐实践

命中 2 项或以上才询问用户是否生成用法示例。未命中时：

• 将 optional_usage_examples 标记为 skipped
• 将 usage_examples.decision 记为 not_applicable
• 将 usage_examples.offered 记为 false
• 将 usage_examples.matched_criteria 记为 []
• 将 usage_examples.result 记为 skipped
• 继续进入 optional_test_install

命中 2 项或以上时，询问用户：

提问前必须先持久化等待决策状态：

sh open_supports/.copilot-skills/ost-support-workflow/scripts/state.sh offer-usage-examples OWNER/REPO "CLI, Agent integration"

这会记录 usage_examples.offered = true、usage_examples.decision = "pending"、命中的 usage_examples.matched_criteria、usage_examples.result = "pending"，并将 optional_usage_examples 标记为 waiting_user、workflow_status 标记为 blocked，以便断点恢复。

检测到该支持包适合生成 usage_examples.md，命中原因：
- CLI, Agent integration

是否要派发 ost-usage-examples 阶段子代理生成安装后的用法示例？这不影响核心支持包完成。
回复“是”则生成，回复“否”则跳过并继续 optional_test_install。

主 workflow 在 checklist 判断或用户回答后，必须使用状态脚本记录 usage_examples.decision、usage_examples.matched_criteria 和 usage_examples.result：

sh open_supports/.copilot-skills/ost-support-workflow/scripts/state.sh usage-examples OWNER/REPO DECISION MATCHED_CRITERIA [RESULT]

MATCHED_CRITERIA 是 checklist 命中摘要字串，状态中以单元素数组保存；不要求 shell 解析多值列表。

用户拒绝：

• 将 optional_usage_examples 标记为 skipped
• 将 usage_examples.offered 记为 true
• 将 usage_examples.decision 记为 declined
• 可保存传入的 checklist 命中摘要到 usage_examples.matched_criteria
• 将 usage_examples.result 记为 skipped
• 继续进入 optional_test_install

用户同意：

• 将 usage_examples.offered 记为 true，记录命中的 usage_examples.matched_criteria
• 将 usage_examples.decision 记为 accepted
• 先将 usage_examples.result 记为 pending
• 将 optional_usage_examples 标记为 in_progress
• 串行派发阶段子代理，在 contract 中引用 .copilot-skills/ost-usage-examples/SKILL.md
• 子代理产出 usage_examples.md
• 主 workflow 审查产物后，记录 agent-run ... DONE ...，再使用状态脚本将 usage_examples.result 记为 generated，并将 optional_usage_examples 标记为 done

推荐调用顺序：

sh open_supports/.copilot-skills/ost-support-workflow/scripts/state.sh offer-usage-examples OWNER/REPO "CLI, Agent integration"
# 用户同意后：
sh open_supports/.copilot-skills/ost-support-workflow/scripts/state.sh usage-examples OWNER/REPO accepted "CLI, Agent integration" pending
# 子代理 DONE 且主 workflow 审查 usage_examples.md 后：
sh open_supports/.copilot-skills/ost-support-workflow/scripts/state.sh usage-examples OWNER/REPO accepted "CLI, Agent integration" generated

Optional Test Install

三个核心产出阶段和 optional_usage_examples 完成或跳过后，必须询问用户：

是否要测试运行 scripts_for_install/install.* 并验证安装是否成功？
这可能会修改本机 CLI / Agent 配置。回复“是”则执行，回复“否”则跳过并完成工作流。

用户拒绝：

• 将 optional_test_install 标记为 skipped
• 将 test_install.offered 记为 true
• 将 test_install.decision 记为 declined
• 将 test_install.result 记为 skipped
• 使用 test-result OWNER/REPO skipped ... 记录拒绝测试；workflow_status 保持 in_progress
• 之后由 complete OWNER/REPO 统一验证并完成工作流

用户同意：

• 将 optional_test_install 标记为 in_progress
• 运行安装脚本
• 运行验证命令
• 记录执行命令、结果和关键输出摘要

验证命令优先来自 repo_readme_summary.md 第 2 部分，其次来自安装脚本或 setup Skill；仍不能判断时进入澄清。

Test Failure

测试安装失败后不要自动修复。保存失败状态并暂停：

• optional_test_install 标记为 failed
• workflow_status 标记为 blocked
• 记录失败命令、退出码和关键输出摘要
• 询问用户下一步：修复支持包文件、跳过测试并完成，或停在失败状态稍后恢复

Completion

完成时确认：

• 必须调用 complete OWNER/REPO
• complete 会验证 repo_readme_summary、install_script、skill_for_setup 都为 done
• complete 会验证 optional_usage_examples 为 done 或 skipped；legacy state 缺少该 stage 时会补为 skipped
• complete 会验证 optional_test_install 为 skipped，或 test_install.result 为 passed 且 stage 状态为 done
• workflow_status 为 done