golden-hoop-spell-opencode 0.1.0

package/src/prompts/context-codegraph.ts

@@ -0,0 +1,65 @@
+// LLM-facing dispatch instruction for the `ghs-context-haiku` subagent —
+// CODEGRAPH path.
+//
+// `ghs-plan-start` (s3-feat-006) probes `detectCodegraph(projectDir)`
+// (s3-feat-002). When `.codegraph/` is present, the dispatcher selects THIS
+// prompt: it tells the main AI to dispatch `ghs-context-haiku` via the Task
+// tool with codegraph-first instructions. The subagent prefers the
+// `codegraph_*` MCP tools (sub-second symbol/edge/flow queries) over manual
+// `grep`+`read` crawling, falling back to file reads only for specific
+// implementation details the graph doesn't surface.
+//
+// This constant is the dispatch directive the main chat AI reads from the
+// `ghs-plan-start` tool result (plan §3.5 / §3.7 step: Task:
+// ghs-context-haiku). It is NOT the verbatim prompt body baked into the
+// subagent template (that lives in `shared/agents/ghs-context-haiku.md.template`,
+// s3-feat-001) — it is the tighter, command-style steering text consumed in
+// the tool result.
+//
+// The snapshot output is wrapped in the
+// `<<<CONTEXT_SNAPSHOT_START>>>` / `<<<CONTEXT_SNAPSHOT_END>>>` delimiters
+// (plan §3.3) so `parse-delimited-output.ts` (s3-feat-003) can extract it in
+// the subsequent `ghs-plan-review(snapshot)` call.
+//
+// Language policy (per CLAUDE.md): human-readable prose is 中文, code
+// identifiers / field names / delimiter tokens stay English.
+
+/**
+ * Dispatch instruction for the context-haiku subagent when codegraph is
+ * available.
+ *
+ * Returned by `ghs-plan-start` when `detectCodegraph()` returns `true`. It
+ * steers the subagent to prefer graph queries (`codegraph_explore`,
+ * `codegraph_callers`, ...) over brute-force grep, and to emit the snapshot
+ * inside the snapshot delimiters.
+ *
+ * Kept to ~600-1200 chars. For the human-readable snapshot format reference,
+ * see `shared/references/context-snapshot-guide.md`.
+ */
+export const CONTEXT_CODEGRAPH_PROMPT = `检测到 \`.codegraph/\` 已初始化 —— 本轮 plan 走 codegraph 路径。请用 Task tool 派发 \`ghs-context-haiku\` subagent 收集项目上下文快照。subagent 应优先用 codegraph MCP 工具查询符号/调用图/数据流，仅在 graph 未覆盖具体实现细节时才补读源文件。详见 shared/references/context-snapshot-guide.md。
+
+输入给 subagent（拼在 Task 派发的 prompt 里）：
+- 需求描述（用于做 relevance filter —— 只收录与需求可能相关的代码）
+- project_dir（若与当前工作目录不同）
+
+推荐的 codegraph 查询顺序（subagent 应遵循）：
+1. \`codegraph_status\` —— 确认索引健康（文件数/节点数/边数），判断是否值得信赖
+2. \`codegraph_explore "<需求关键词 + 模块名>"\` —— 一次性取回相关符号的源码（PRIMARY，多数情况这一个调用就够）
+3. \`codegraph_callers\` / \`codegraph_callees\` / \`codegraph_impact\` —— 查调用路径 / 影响面（用于关键流程与重构边界）
+4. 仅当 graph 未覆盖某个具体实现时，才用 \`read\` / \`glob\` / \`grep\` 补读个别文件
+
+快照内容（subagent 须产出，压缩到原始源码的 50-70%）：
+- 技术栈（语言/版本、运行时/框架、关键依赖、构建系统、测试框架）
+- 目录结构（关键文件一行注释）
+- 架构摘要（入口点、模块职责、数据模型、关键模式）
+- 与需求相关的代码摘录（函数签名、schema、路由、类型定义 —— 不要整文件粘贴）
+
+分隔标记契约（硬性，parser 据此提取 snapshot）：
+- snapshot 全文必须放在 \`<<<CONTEXT_SNAPSHOT_START>>>\` 与 \`<<<CONTEXT_SNAPSHOT_END>>>\` 之间，两个标记各占独立一行
+- 不要把标记或内容包进 markdown 代码围栏（不要用三反引号包裹）
+- 不要翻译/改写标记：禁止 \`《《CONTEXT_SNAPSHOT_START》》\`、\`<<CONTEXT_SNAPSHOT_START>>\`、\`<<< CONTEXT_SNAPSHOT_START >>>\` 等变体
+- 使用字面 ASCII 字符 \`<\`、\`>\`、\`_\`
+
+输出语言策略（与 CLAUDE.md 一致）：快照正文/模块描述/注释用中文；代码标识符、字段名、文件路径、类型名用英文。
+
+收到 subagent 的分隔标记输出后，请把整段（含标记）原样作为 \`snapshot\` 参数调用 \`ghs-plan-review\` 进入 snapshot 模式，parser 会提取快照并派发下一步 designer。`;

package/src/prompts/context-grep.ts

@@ -0,0 +1,68 @@
+// LLM-facing dispatch instruction for the `ghs-context-haiku` subagent —
+// GREP FALLBACK path.
+//
+// `ghs-plan-start` (s3-feat-006) probes `detectCodegraph(projectDir)`
+// (s3-feat-002). When `.codegraph/` is ABSENT (or the probe fails
+// defensively), the dispatcher selects THIS prompt: it tells the main AI to
+// dispatch `ghs-context-haiku` via the Task tool with grep/glob/read-first
+// instructions. There are no codegraph MCP tools available, so the subagent
+// builds the snapshot by manual traversal — dependency manifest → directory
+// tree → entry point → config → requirement-relevant files.
+//
+// This constant is the dispatch directive the main chat AI reads from the
+// `ghs-plan-start` tool result (plan §3.5 / §3.7 step: Task:
+// ghs-context-haiku). It is NOT the verbatim prompt body baked into the
+// subagent template (that lives in
+// `shared/agents/ghs-context-haiku.md.template`, s3-feat-001) — it is the
+// tighter, command-style steering text consumed in the tool result.
+//
+// The snapshot output is wrapped in the
+// `<<<CONTEXT_SNAPSHOT_START>>>` / `<<<CONTEXT_SNAPSHOT_END>>>` delimiters
+// (plan §3.3) so `parse-delimited-output.ts` (s3-feat-003) can extract it in
+// the subsequent `ghs-plan-review(snapshot)` call.
+//
+// Language policy (per CLAUDE.md): human-readable prose is 中文, code
+// identifiers / field names / delimiter tokens stay English.
+
+/**
+ * Dispatch instruction for the context-haiku subagent when codegraph is NOT
+ * available.
+ *
+ * Returned by `ghs-plan-start` when `detectCodegraph()` returns `false`. It
+ * steers the subagent to build the snapshot via `read` / `glob` / `grep`
+ * (read-only `bash`) following the extraction order in
+ * `shared/references/context-snapshot-guide.md`, and to emit the snapshot
+ * inside the snapshot delimiters.
+ *
+ * Kept to ~600-1200 chars. For the human-readable snapshot format reference,
+ * see `shared/references/context-snapshot-guide.md`.
+ */
+export const CONTEXT_GREP_PROMPT = `未检测到 \`.codegraph/\` —— 本轮 plan 走 grep 回退路径（无 codegraph MCP 工具可用）。请用 Task tool 派发 \`ghs-context-haiku\` subagent 收集项目上下文快照。subagent 用 \`read\` / \`glob\` / \`grep\`（read-only \`bash\`）手动遍历代码库构建快照。详见 shared/references/context-snapshot-guide.md。
+
+输入给 subagent（拼在 Task 派发的 prompt 里）：
+- 需求描述（用于做 relevance filter —— 只收录与需求可能相关的代码）
+- project_dir（若与当前工作目录不同）
+
+推荐的提取顺序（subagent 应遵循，参照 context-snapshot-guide.md 的 Extraction Process）：
+1. 读依赖清单：\`package.json\` / \`requirements.txt\` / \`Cargo.toml\` 等
+2. 取目录结构：\`glob\` 或 \`find\`（排除 node_modules、.git、build 产物）
+3. 读入口点：\`src/index.ts\` / \`main.py\` / \`src/lib.rs\` 等
+4. 读配置文件：\`.env.example\`、config 模块、数据库初始化
+5. 读与需求相关的文件：需求所属目录下的关键源文件
+6. 汇总压缩：把发现压缩成快照格式（目标 50-70% 压缩比，不要整文件粘贴）
+
+快照内容（subagent 须产出）：
+- 技术栈（语言/版本、运行时/框架、关键依赖、构建系统、测试框架）
+- 目录结构（关键文件一行注释）
+- 架构摘要（入口点、模块职责、数据模型、关键模式）
+- 与需求相关的代码摘录（函数签名、schema、路由、类型定义 —— 只收录可能相关的，排除无关模块）
+
+分隔标记契约（硬性，parser 据此提取 snapshot）：
+- snapshot 全文必须放在 \`<<<CONTEXT_SNAPSHOT_START>>>\` 与 \`<<<CONTEXT_SNAPSHOT_END>>>\` 之间，两个标记各占独立一行
+- 不要把标记或内容包进 markdown 代码围栏（不要用三反引号包裹）
+- 不要翻译/改写标记：禁止 \`《《CONTEXT_SNAPSHOT_START》》\`、\`<<CONTEXT_SNAPSHOT_START>>\`、\`<<< CONTEXT_SNAPSHOT_START >>>\` 等变体
+- 使用字面 ASCII 字符 \`<\`、\`>\`、\`_\`
+
+输出语言策略（与 CLAUDE.md 一致）：快照正文/模块描述/注释用中文；代码标识符、字段名、文件路径、类型名用英文。
+
+收到 subagent 的分隔标记输出后，请把整段（含标记）原样作为 \`snapshot\` 参数调用 \`ghs-plan-review\` 进入 snapshot 模式，parser 会提取快照并派发下一步 designer。`;

package/src/prompts/feature-impl.ts

@@ -0,0 +1,78 @@
+// LLM-facing dispatch prompt for the coding subagent that implements a single
+// feature.
+//
+// This constant is the dispatch text the main AI consumes after it selects a
+// ready feature via the `ghs-code` tool (plan §3.5 / §3.7 step 5: code). It
+// tells the main AI to use the Task tool to spawn an isolated coding subagent
+// that implements ONE feature end-to-end (context-reset → read features.json →
+// implement + verify AC → single commit → return EXACTLY ONE completion
+// signal). The subagent's return signal is then parsed by
+// `parse-completion-signal.ts` (s4-feat-001).
+//
+// It is NOT a verbatim copy of `shared/references/coding-agent.md` — that file
+// is the human-readable reference doc (session protocol, parallel mode,
+// testing requirements). This constant is the tight, command-style dispatch
+// template the main chat AI reads from the `ghs-code` tool result and hands to
+// the subagent. It distills coding-agent.md §Implementation Process +
+// §Session Protocol + the §Critical Rules into the smallest prompt that
+// reliably drives a single-feature implementation.
+//
+// Two placeholders MUST be substituted by the `ghs-code` tool before the main
+// AI dispatches the subagent:
+//   - `<PROJECT_DIR>`  → absolute project root (from `resolveProjectDir`)
+//   - `<feature_id>`   → the selected feature's `id` (e.g. `s4-feat-004`)
+// The prompt deliberately contains NO inline feature details — the subagent
+// reads them from `.ghs/features.json` per Task step 1 (single source of
+// truth). It also needs no `<sprint_id>` placeholder: the subagent locates its
+// feature by `id == "<feature_id>"` across `sprints[].features[]`.
+//
+// Language policy (per CLAUDE.md): human-readable prose is 中文, code
+// identifiers / field names / signal tokens / git commands stay English. The
+// subagent is told to follow the same policy when it writes its commit message
+// and any docs.
+
+/**
+ * Dispatch prompt template for the single-feature coding subagent.
+ *
+ * Returned as part of the `ghs-code` tool's output text so the main AI can
+ * hand it (with `<PROJECT_DIR>` and `<feature_id>` substituted) to the Task
+ * tool to spawn the implementer.
+ *
+ * Kept to ~900-1600 chars: enough to pin the context-reset stance, the
+ * features.json-first feature lookup, the implement-and-verify loop, the
+ * single-commit contract (explicit `git add` paths, no `.ghs/` writes), and
+ * the hard completion-signal protocol; short enough to land in a tool result
+ * without crowding it. For the full human-readable reference, see
+ * `shared/references/coding-agent.md`.
+ */
+export const FEATURE_IMPL_PROMPT = `实现本项目的一个 feature。用 Task tool 派发一个隔离的 coding subagent 完成端到端实现，返回的完成信号由 parse-completion-signal 解析。详见 shared/references/coding-agent.md。
+
+派发前请替换两个占位符（ghs-code tool 已注入）：\`<PROJECT_DIR>\`（项目根绝对路径）与 \`<feature_id>\`（所选 feature 的 id）。prompt 内不含任何 inline feature 细节——subagent 自己从 features.json 读取。
+
+subagent prompt 正文（原样交给 Task tool）：
+
+---
+Implement ONE feature for this project.
+
+## CONTEXT RESET - READ THIS FIRST
+This is an isolated task. Disregard prior context, assume nothing, read files fresh, start clean.
+
+## Your Task
+1. 打开 \`<PROJECT_DIR>/.ghs/features.json\`，在 \`sprints[].features[]\` 中按 \`id == "<feature_id>"\` 找到你的 feature。读取它的 \`description\`/\`acceptance_criteria\`/\`technical_notes\`/\`files_affected\`——这些是你的唯一事实来源，不是 title。
+2. 若所属 sprint 含 \`plan_ref\` 字段，打开该 plan 文件（相对项目根）并读取 \`technical_notes\` 引用的章节（例如 "参考 plan §3.3 ..." 即读 §3.3）。若 \`plan_ref\` 缺失或文件不存在，记一行 warning 后照 \`technical_notes\` 原文执行。
+3. 读 \`<PROJECT_DIR>/.ghs/progress.md\` 了解近期项目上下文。
+4. 按 coding-agent.md 工作流实现 feature，并验证全部 \`acceptance_criteria\` 已满足。
+5. 运行 lint/build，然后做**恰好一次** commit：显式 \`git add <每个修改过的实现文件路径>\`（不要 \`git add -A\`/\`git add .\`，不要提交任何 \`.ghs/*\` 文件），commit message 为 \`feat(<scope>): <简述> (Feature: <feature_id>)\`。
+
+## Feature ID
+<feature_id>
+
+## Critical Rules
+- 不要修改任何 \`.ghs/\` 文件。可以 READ features.json，但 MUST NOT write。
+- 只聚焦本 feature，不要 scope-creep 到其它 feature。
+- 结尾输出 EXACTLY ONE 信号，独占一行：\`FEATURE COMPLETE: <feature_id>\` 或 \`FEATURE BLOCKED: <feature_id> - <原因>\`。禁止小写、禁止 "FEATURE COMPLETED"、禁止自然语言、禁止中文变体（如 "特性完成"）。
+---
+
+语言策略（与 CLAUDE.md 一致）：commit message 与任何文档用中文正文；代码标识符、字段名、枚举值、文件路径、日志/错误信息、完成信号 token 用英文。
+
+收到 subagent 返回后，把原始输出按 Verification Phase 交给 parse-completion-signal 解析（\`status: completed | blocked | unknown\`），据此更新 features.json 与 progress.md。unknown 时走 Format Recovery 重试，耗尽后用 AskUserQuestion 让用户裁决。`;

package/src/prompts/plan-designer.ts

@@ -0,0 +1,59 @@
+// LLM-facing dispatch instruction for the `ghs-plan-designer` subagent.
+//
+// This constant is the dispatch text the main AI consumes after it returns a
+// snapshot via `ghs-plan-review(snapshot)` (plan §3.5 / §3.7 step: Task:
+// ghs-plan-designer). It tells the main AI to use the Task tool to dispatch
+// the `ghs-plan-designer` subagent, what input to feed it (the context
+// snapshot + the requirement), and the hard delimiter protocol the designer
+// must obey so `parse-delimited-output.ts` (s3-feat-003) can extract its
+// output in the subsequent `ghs-plan-review(plan)` call.
+//
+// It is NOT a verbatim copy of `shared/references/plan-designer.md` — that
+// file is the human-readable reference doc baked into the designer
+// subagent's own prompt body (s3-feat-001 template). This constant is the
+// tight, command-style dispatch directive the main chat AI reads from the
+// tool result to drive the plan loop forward.
+//
+// Language policy (per CLAUDE.md): human-readable prose is 中文, code
+// identifiers / field names / delimiter tokens stay English.
+
+/**
+ * Dispatch instruction for the plan-designer subagent.
+ *
+ * Returned as part of a plan tool's output text so the main AI immediately
+ * knows how to spawn `ghs-plan-designer` via the Task tool and what output
+ * contract to enforce.
+ *
+ * Kept to ~600-1200 chars: enough to pin the delimiter protocol, the
+ * snapshot-first working approach, the completion signal, and the language
+ * policy; short enough to land in a tool result without crowding it. For the
+ * full human-readable reference, see `shared/references/plan-designer.md`.
+ */
+export const PLAN_DESIGNER_PROMPT = `接下来请用 Task tool 派发 \`ghs-plan-designer\` subagent 设计技术方案。subagent 收到的是 context snapshot + 需求描述，产出一份可执行的技术 plan。详见 shared/references/plan-designer.md。
+
+输入给 subagent（拼在 Task 派发的 prompt 里）：
+- 需求描述（用户原始需求 + 任何已澄清的约束）
+- context snapshot 路径或全文（上一轮 ghs-context-haiku 的产物）
+
+工作方式（务必让 subagent 遵守）：
+- 先读 context snapshot，再按需补读个别源文件；snapshot 已覆盖架构概览/模块职责/数据模型时不要再全文复读
+- 方案须与现有架构一致、分阶段可执行、可回滚、可测试
+- 若需要用户澄清无法从代码/需求推断的事项，首行输出 \`QUESTION: <问题>\`
+
+分隔标记契约（硬性，parser 据此提取 plan）：
+- plan 全文必须放在 \`<<<PLAN_START>>>\` 与 \`<<<PLAN_END>>>\` 之间，两个标记各占独立一行
+- 不要把标记或内容包进 markdown 代码围栏（不要用三反引号包裹）
+- 不要翻译/改写标记：禁止 \`《《PLAN_START》》\`、\`<<PLAN_START>>\`、\`<<< PLAN_START >>>\` 等变体
+- 使用字面 ASCII 字符 \`<\`、\`>\`、\`_\`
+- 正确示例：
+    <<<PLAN_START>>>
+    # 方案标题
+    ...正文...
+    <<<PLAN_END>>>
+    PLAN DESIGN COMPLETE
+
+完成信号：设计完成输出 \`PLAN DESIGN COMPLETE\`；需用户澄清输出 \`QUESTION: <具体问题>\`（不要用 QUESTION 替代你自己的技术判断）。
+
+输出语言策略（与 CLAUDE.md 一致）：方案正文/章节标题/风险描述用中文；代码标识符、字段名、枚举值、文件路径、日志/错误信息用英文。
+
+收到 subagent 的分隔标记输出后，请把整段（含标记）原样作为 \`plan\` 参数调用 \`ghs-plan-review\` 进入 plan 模式评审。`;

package/src/prompts/plan-reviewer.ts

@@ -0,0 +1,61 @@
+// LLM-facing dispatch instruction for the `ghs-plan-reviewer` subagent.
+//
+// This constant is the dispatch text the main AI consumes after it returns a
+// plan via `ghs-plan-review(plan)` (plan §3.5 / §3.7 step: Task:
+// ghs-plan-reviewer). It tells the main AI to use the Task tool to dispatch
+// the `ghs-plan-reviewer` subagent, what input to feed it (the plan + the
+// context snapshot), and the hard delimiter protocol + verdict line the
+// reviewer must obey so `parse-delimited-output.ts` (s3-feat-003) can extract
+// its output and the dispatcher can read PASS/FAIL in the subsequent
+// `ghs-plan-review(review)` call.
+//
+// It is NOT a verbatim copy of `shared/references/plan-reviewer.md` — that
+// file is the human-readable reference doc baked into the reviewer
+// subagent's own prompt body (s3-feat-001 template). This constant is the
+// tight, command-style dispatch directive the main chat AI reads from the
+// tool result.
+//
+// Language policy (per CLAUDE.md): human-readable prose is 中文, code
+// identifiers / field names / delimiter tokens stay English.
+
+/**
+ * Dispatch instruction for the plan-reviewer subagent.
+ *
+ * Returned as part of a plan tool's output text so the main AI immediately
+ * knows how to spawn `ghs-plan-reviewer` via the Task tool and what output
+ * contract to enforce (delimiter + verdict line).
+ *
+ * Kept to ~600-1300 chars: enough to pin the delimiter protocol, the
+ * verdict line format, the severity taxonomy, the snapshot-first review
+ * approach, and the language policy. For the full human-readable reference,
+ * see `shared/references/plan-reviewer.md`.
+ */
+export const PLAN_REVIEWER_PROMPT = `接下来请用 Task tool 派发 \`ghs-plan-reviewer\` subagent 评审技术方案。subagent 从架构师视角审查 plan 的可行性/完整性/可执行性，产出带严重度分级的评审报告。详见 shared/references/plan-reviewer.md。
+
+输入给 subagent（拼在 Task 派发的 prompt 里）：
+- 待评审的 plan 全文（上一轮 ghs-plan-designer 的产物）
+- context snapshot 路径或全文（用于核对 plan 与现有架构的一致性）
+
+工作方式（务必让 subagent 遵守）：
+- 先读 context snapshot 建立架构基线，再读 plan，按架构上下文逐条评估
+- 只在需要核对 plan 中某条具体断言时才补读源文件
+- 每条反馈必须带严重度：Severe（会导致 bug/数据丢失/安全漏洞/逻辑不自洽）/ Medium（方向对但实现路径有问题）/ Optimization（不影响实现但能提质）
+- 你是 guardian 不是 grader：反馈要帮 designer 改进方案，但真正的架构缺陷绝不能放过
+
+分隔标记契约（硬性，parser 据此提取 review）：
+- review 报告全文必须放在 \`<<<REVIEW_START>>>\` 与 \`<<<REVIEW_END>>>\` 之间，两个标记各占独立一行
+- 不要把标记或内容包进 markdown 代码围栏（不要用三反引号包裹）
+- 不要翻译/改写标记：禁止 \`《《REVIEW_START》》\`、\`<<REVIEW_START>>\`、\`<<< REVIEW_START >>>\` 等变体
+- 使用字面 ASCII 字符 \`<\`、\`>\`、\`_\`
+
+裁决行（硬性，dispatcher 据此读 PASS/FAIL）：
+- 紧跟 \`<<<REVIEW_END>>>\` 之后，独占一行输出：
+  \`REVIEW COMPLETE | Verdict: PASS|FAIL | Severe: X Medium: Y Optimization: Z\`
+- PASS = 仅 Optimization 项、无 Severe/Medium；FAIL = 存在任一 Severe/Medium
+- 缺失或格式错误的裁决行会被 dispatcher 重试
+
+完成信号：评审完成输出上述裁决行；需用户澄清（真·业务抉择）输出 \`QUESTION: <具体问题>\`。
+
+输出语言策略（与 CLAUDE.md 一致）：评审报告正文/章节标题/问题描述用中文；代码标识符、字段名、严重度枚举（Severe/Medium/Optimization）、Verdict 值（PASS/FAIL）用英文。
+
+收到 subagent 的分隔标记输出后，请把整段（含标记 + 裁决行）原样作为 \`review\` 参数调用 \`ghs-plan-review\` 进入 review 模式判定。PASS 则推进到 \`ghs-plan-finalize\`；FAIL 则触发 designer 修订（附评审报告）。`;

package/src/prompts/sprint-planning.ts

@@ -0,0 +1,47 @@
+// LLM-facing instruction returned by the `ghs-sprint` tool after it writes a
+// new sprint skeleton to features.json.
+//
+// This prompt is NOT a verbatim copy of shared/references/sprint-agent.md —
+// that file is a human-readable reference doc. This constant is the
+// command-style instruction the AI consumes to decompose requirements into
+// atomic features (s2-feat-002). It distills the source's Steps 2-5
+// (Create Atomic Features / Categorize and Prioritize / Define Acceptance
+// Criteria / Order by Dependencies) into the tightest form that reliably
+// steers feature decomposition.
+//
+// Language policy (per CLAUDE.md): human-readable prose is 中文, code
+// identifiers / field names / enum values stay English. The AI is told to
+// follow the same policy when writing features.
+
+/**
+ * The sprint-planning instruction. Returned as part of the `ghs-sprint`
+ * tool's output text so the AI immediately knows how to break the sprint
+ * goal into atomic features and append them via `update-feature-status`.
+ *
+ * Length is kept ~500-1500 chars: enough to specify the feature schema,
+ * atomic-feature criteria, AC format, dependency ordering, and complexity
+ * estimation; short enough to land in the tool result without crowding it.
+ * For the full human-readable reference, see
+ * shared/references/sprint-agent.md.
+ */
+export const SPRINT_PLANNING_PROMPT = `Sprint 骨架已写入 features.json。接下来请把 sprint goal 拆成 atomic features，逐个用 update-feature-status 追加（status 初始为 pending）。详见 shared/references/sprint-agent.md。
+
+拆分原则（每个 feature 必须同时满足）：
+- 原子性：单个 session 可完成（< 4 小时）
+- 独立性：依赖最少，可单独验证
+- 可测：有明确、可执行的验收标准
+- 有价值：交付可感知的用户/系统价值
+
+feature schema（字段名用英文）：
+{ id, category, priority, title, description, acceptance_criteria[], technical_notes, status, dependencies[], estimated_complexity, files_affected[] }
+- id：s{N}-feat-{NNN}（N = 当前 sprint 编号，NNN 零填充 3 位，sprint 内顺序递增）
+- category：core | ui | api | auth | data | infra
+- priority：high（sprint 阻塞项/核心）| medium（重要不阻塞）| low（可推迟）
+- status：pending | in_progress | completed | blocked（blocked 必须带 blocked_reason）
+- estimated_complexity：small（<2h）| medium（2-4h）| large（4h+，必须继续拆分）
+
+acceptance_criteria 写法（Given/When/Then）：用可验证的条件描述，避免主观措辞。示例：Given features.json 存在，when 调 appendSprint，then 新 sprint 出现在 sprints 末尾且原对象不被修改。
+
+依赖排序：基础设施先行 → 核心功能 → 支撑功能 → UI；有 dependencies 的 feature 必须排在被依赖项之后。在 progress.md 记录实现顺序与理由。
+
+语言策略（与 CLAUDE.md 一致）：description / acceptance_criteria / technical_notes 等人类可读字段用中文；代码标识符、字段名、枚举值、日志/错误信息用英文。`;

package/src/tools/archive.ts

@@ -0,0 +1,278 @@
+// `ghs-archive` tool — archive completed sprints (or preview / list them).
+//
+// Three modes (mutually exclusive; `list` wins, then `dry_run`, then the
+// default `archive`):
+//   - `list:    true`  → print all completed sprints without archiving.
+//   - `dry_run: true`  → preview what would be archived; write no files.
+//   - (neither)        → actually move completed sprints to `.ghs/archived/`.
+//
+// The dry-run path ALSO writes a nonce file (`.ghs/.force-archive-nonce`)
+// when there are any *incomplete* sprints remaining. This is the gate the
+// `ghs-force-archive` tool reads back: the user is expected to transcribe
+// the nonce to confirm a subsequent force-archive call. The nonce persists
+// across calls on disk (simpler than threading per-invocation state through
+// the tool protocol — see the feature's technical_notes).
+//
+// Output text mirrors the Python `archive_sprint.py` script byte-for-byte
+// (verified by `test/equivalence/archive.test.ts`); we append a short
+// nonce section to the dry-run output when one is issued.
+
+import { tool } from "@opencode-ai/plugin";
+import type { ToolContext } from "@opencode-ai/plugin/tool";
+import { existsSync } from "node:fs";
+import { readFile, writeFile, unlink } from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+import {
+  archiveSprints,
+  getAllSprints,
+  getCompletedSprints,
+  formatArchiveReport,
+  formatListReport,
+  type ArchivedSprintInfo,
+} from "../lib/scripts/archive-sprint.ts";
+import { generateNonce } from "../lib/nonce.ts";
+import { resolveProjectDir } from "../lib/project.ts";
+
+/** Path of the per-project nonce file used by `ghs-force-archive`. */
+function nonceFilePath(projectDir: string): string {
+  return join(resolve(projectDir), ".ghs", ".force-archive-nonce");
+}
+
+/**
+ * Write the issued nonce to disk so `ghs-force-archive` can read it back.
+ * Truncated on each call so stale nonces from a prior run can't be reused.
+ */
+async function writeNonce(projectDir: string, nonce: string): Promise<void> {
+  await writeFile(nonceFilePath(projectDir), nonce, "utf8");
+}
+
+/**
+ * Read (and delete) the nonce file. Deleting on read means a captured nonce
+ * can only be transcribed once — a stale `ghs-force-archive` call after the
+ * nonce has been consumed will fail the gate.
+ *
+ * Returns the nonce string, or null when the file is absent. If `consume`
+ * is false the file is left in place (used by `ghs-force-archive`'s own
+ * pre-flight check; the actual consume happens after the gate passes).
+ */
+async function readNonce(
+  projectDir: string,
+  consume: boolean,
+): Promise<string | null> {
+  const path = nonceFilePath(projectDir);
+  if (!existsSync(path)) {
+    return null;
+  }
+  const nonce = (await readFile(path, "utf8")).trim();
+  if (consume) {
+    try {
+      await unlink(path);
+    } catch {
+      // Nonce file may already be gone (concurrent call) — non-fatal.
+    }
+  }
+  return nonce;
+}
+
+/**
+ * Count sprints that are NOT completed (i.e. could still be force-archived).
+ * Used to decide whether the nonce gate is even relevant for this project.
+ */
+function countIncompleteSprints(featuresData: Record<string, unknown>): number {
+  const all = getAllSprints(featuresData);
+  return all.filter((s) => s.status !== "completed").length;
+}
+
+/** Load features.json from `<projectDir>/.ghs/features.json`. Returns null if missing. */
+async function loadFeaturesData(
+  projectDir: string,
+): Promise<Record<string, unknown> | null> {
+  const path = join(resolve(projectDir), ".ghs", "features.json");
+  if (!existsSync(path)) {
+    return null;
+  }
+  const text = await readFile(path, "utf8");
+  return JSON.parse(text) as Record<string, unknown>;
+}
+
+// Exported for `ghs-force-archive` to read + consume the nonce file.
+export { readNonce, writeNonce, nonceFilePath };
+
+/**
+ * The `ghs-archive` tool definition. Registered under the `ghs-archive` key.
+ */
+export const archiveTool = tool({
+  description:
+    "Archive completed sprints to `.ghs/archived/` and remove them from features.json. " +
+    "Three modes: `list: true` lists completed sprints without changing anything; " +
+    "`dry_run: true` previews what would be archived without writing files; " +
+    "neither flag actually moves completed sprints to `.ghs/archived/`. " +
+    "Only sprints with status 'completed' are archived — use `ghs-force-archive` to archive incomplete sprints.",
+  args: {
+    dry_run: tool.schema
+      .boolean()
+      .optional()
+      .describe(
+        "When true, preview what would be archived without modifying any files.",
+      ),
+    list: tool.schema
+      .boolean()
+      .optional()
+      .describe(
+        "When true, list completed sprints without archiving. Takes precedence over `dry_run`.",
+      ),
+    project_dir: tool.schema
+      .string()
+      .optional()
+      .describe(
+        "Absolute path of the project root. Defaults to the opencode session's worktree/directory.",
+      ),
+  },
+  async execute(
+    args: { dry_run?: boolean; list?: boolean; project_dir?: string },
+    ctx: ToolContext,
+  ): Promise<string> {
+    const projectDir = args.project_dir
+      ? resolve(args.project_dir)
+      : resolveProjectDir(ctx);
+
+    const listMode = args.list === true;
+    const dryRunMode = !listMode && args.dry_run === true;
+    const archiveMode = !listMode && !dryRunMode;
+
+    // ----- list mode -----
+    if (listMode) {
+      const features = await loadFeaturesData(projectDir);
+      if (!features) {
+        return [
+          "=== Sprint Archiver ===",
+          "",
+          `Project directory: ${projectDir}`,
+          "",
+          "❌ features.json not found. Run `ghs-init` first.",
+        ].join("\n") + "\n";
+      }
+      const completed = getCompletedSprints(features);
+      return formatListReport({
+        projectDir,
+        force: false,
+        sprints: completed,
+      });
+    }
+
+    // ----- dry-run + archive modes both go through archiveSprints -----
+    // We call archiveSprints twice for the archive path: once with
+    // dryRun=true to get the preview info, then once with dryRun=false to
+    // actually move the files. This keeps the report identical to Python's
+    // (which prints the per-sprint "Archiving sprint:" line *before* the
+    // move) without reaching into archiveSprintFiles' internals.
+    //
+    // For dry-run, the single dryRun=true call is enough.
+    const preview = await archiveSprints({
+      projectDir,
+      dryRun: true,
+      force: false,
+    });
+
+    // Pre-load the features data — we need it to compute remainingCount and
+    // to decide whether to issue a force-archive nonce below.
+    const featuresBefore = await loadFeaturesData(projectDir);
+
+    if (preview.length === 0) {
+      // Nothing completed to archive. But if there are *incomplete* sprints,
+      // we still want to issue a nonce so the user can `ghs-force-archive`
+      // them. Short-circuit the normal report and append a nonce hint.
+      const report = formatArchiveReport({
+        projectDir,
+        mode: dryRunMode ? "dry-run" : "archive",
+        force: false,
+        sprintsConsidered: [],
+        archived: [],
+        remainingCount: featuresBefore ? getAllSprints(featuresBefore).length : 0,
+        resetProgress: false,
+      });
+      return maybeAppendNonce(projectDir, report, featuresBefore);
+    }
+
+    let archived: ArchivedSprintInfo[];
+    let featuresAfter: Record<string, unknown> | null = null;
+    if (dryRunMode) {
+      archived = preview;
+    } else {
+      // archiveMode: actually archive.
+      archived = await archiveSprints({
+        projectDir,
+        dryRun: false,
+        force: false,
+      });
+      featuresAfter = await loadFeaturesData(projectDir);
+    }
+
+    // Compute remainingCount + resetProgress for the report.
+    const featuresForReport = featuresAfter ?? (await loadFeaturesData(projectDir));
+    const remainingSprints: Record<string, unknown>[] = featuresForReport
+      ? getAllSprints(featuresForReport)
+      : [];
+    const remainingCount = remainingSprints.length;
+    const resetProgress = archived.length > 0 && remainingCount === 0;
+
+    // sprintsConsidered for the report: the preview (completed sprints).
+    // `formatArchiveReport` accepts `sprintsConsidered: Sprint[]` where
+    // `Sprint` is `Record<string, unknown>` internally — so the mapped
+    // object literal matches without a cast.
+    const sprintsConsidered = preview.map((info) => ({
+      id: info.sprint_id,
+      name: info.sprint_name,
+      status: info.sprint_status,
+    }));
+
+    const report = formatArchiveReport({
+      projectDir,
+      mode: archiveMode ? "archive" : "dry-run",
+      force: false,
+      sprintsConsidered,
+      archived,
+      remainingCount,
+      resetProgress,
+    });
+
+    // ----- nonce gate hook -----
+    return maybeAppendNonce(projectDir, report, featuresForReport);
+  },
+});
+
+/**
+ * Append a force-archive nonce hint to the report when there are any
+ * incomplete sprints remaining. Issues a fresh nonce and writes it to
+ * `.ghs/.force-archive-nonce`. When there are no incomplete sprints,
+ * returns `report` unchanged.
+ *
+ * The features data is passed in (rather than re-loaded) so callers that
+ * already have a recent copy can avoid a redundant disk read.
+ */
+async function maybeAppendNonce(
+  projectDir: string,
+  report: string,
+  features: Record<string, unknown> | null,
+): Promise<string> {
+  if (!features) {
+    return report;
+  }
+  const incomplete = countIncompleteSprints(features);
+  if (incomplete === 0) {
+    return report;
+  }
+  const nonce = generateNonce();
+  await writeNonce(projectDir, nonce);
+  return (
+    report +
+    [
+      "",
+      "⚠️  Incomplete sprints remain and can only be removed with `ghs-force-archive`.",
+      `   To confirm a force-archive, transcribe this token back: ${nonce}`,
+      "   (Call `ghs-force-archive` with `transcription: \"<token>\"`.)",
+    ].join("\n") +
+    "\n"
+  );
+}