spec-manager 0.1.0

package/skill/subskills/release.md

@@ -0,0 +1,50 @@
+# Release 子 skill — 发布说明 / changelog
+
+## 用途
+
+为每个版本写 release notes（`releases/vX.Y.Z-release.md`）：
+- 用户可见的变更
+- 关联的 L1/L2/L3 spec
+- 回滚说明
+
+## 流程
+
+1. 列出当前活跃 L1/L2/L3
+
+```bash
+spec-manager spec list --status implemented
+spec-manager change list
+```
+
+2. 选本次发布的 spec 范围（按 milestone 过滤）
+
+3. 写 release notes：
+
+```bash
+mkdir -p releases
+cat > releases/v1.2.0-release.md <<'EOF'
+# v1.2.0 — <主题>
+
+## 新增
+- 2FA 强制登录（2026-06-04-a1b2c3 MODIFIED）
+
+## 修复
+- JWT 过期返回 401 而非 500（2026-06-04-c3d4e5 bugfix）
+
+## 变更
+- 数据库 schema: users 表加 mfa_secret 字段（migration 2026_05_11）
+
+## 回滚
+- 关闭 2FA 强制开关（`AUTH_REQUIRE_2FA=false`）
+- DB 回滚：down migration
+
+## 关联决策
+- DC-002：改用 PASETO（影响 AC-1）
+EOF
+```
+
+4. 同步到 git tag + GitHub release（如需）
+
+## 关联规则
+
+- 关联到 R14 跨层引用用 code 不是复述

package/skill/subskills/research.md

@@ -0,0 +1,35 @@
+# Sub-skill: Research（只读）
+
+> 🛑 **硬红线**：本 skill 全程**只读**。如果用户意图是改文档/建 spec/写代码,必须先切到 prd/design/impl/quick 等子 skill。
+> 以下工具/子命令**严禁**调用：
+>
+> | 类别 | 禁用的 CLI 子命令 |
+> |---|---|
+> | 写 spec | `spec new` / `spec update` / `spec confirm` / `spec freeze` / `spec implement` / `spec add-relation` / `spec delete` |
+> | 写决策 | `decision create` / `decision update` / `decision set-partial` / `decision supersede` / `decision delete` |
+> | 写 task | `task create` / `task start` / `task step` / `task complete` / `task fail` / `task wait` |
+> | 写 change | `change new` / `change archive` |
+> | 写 incident | `incident new` / `incident update` |
+> | 写 audit | `audit hit` / `audit report` / `audit session` |
+> | 项目级写 | `project init` / `dict register` |
+>
+> 若用户要"查完后顺手改一下",**先停下来切到对应写 skill**,不要在本 skill 里偷偷调 write 子命令。
+
+## 路由自检
+
+✓ 走本 skill 的信号：用户说"查 / 看 / 列 / 统计 / 了解 / 搜索 X"
+✗ 不走的信号：用户说"新功能"（→ prd.md）等任何意图要改文档
+
+## 流程
+
+1. **仅用只读命令**：
+   ```bash
+   spec-manager spec list [--level L1] [--topic X] [--status draft]
+   spec-manager spec show <code>                    # 默认 narrow 视图（R19）
+   spec-manager spec show <code> --include-content  # 仅当 aiSummary 不够时
+   spec-manager decision list --topic X
+   spec-manager project status
+   spec-manager audit show [--rule R1]
+   ```
+2. **禁止**：任何 `new` / `update` / `confirm` / `freeze` / `implement` / `add-relation` / `delete`
+3. **R19 优先**：默认读 aiSummary 而非全文

package/skill/subskills/runbook.md

@@ -0,0 +1,44 @@
+# Runbook 子 skill — 运维手册 / oncall 应急
+
+## 用途
+
+长期档案，存放 oncall 应急手册、部署手册、故障排查清单。
+
+## 流程
+
+1. 新建 runbook：
+
+```bash
+mkdir -p runbooks
+cat > runbooks/auth-service-down.md <<'EOF'
+# Auth Service 宕机应急
+
+## 现象
+- 监控：auth-service 5xx 比例 > 50% 持续 5 分钟
+- 用户：登录按钮转圈无响应
+
+## 第一步：止血
+- 查看日志：`docker logs auth-service --tail 200`
+- 重启：`docker compose restart auth-service`
+
+## 第二步：根因
+- 查 PostgreSQL 连接数：`SELECT count(*) FROM pg_stat_activity;`
+- 如果 > 80%：kill 慢查询
+- 如果 JWT secret 轮换：检查 `JWT_SECRET` env 是否同步
+
+## 第三步：回滚
+- 切回上一版本：`docker compose up -d --scale auth-service=0 && git checkout v1.1.0 && docker compose up -d`
+
+## 关联
+- 关联 spec：2026-06-04-a1b2c3
+- 历史 incident：INC-20260513-001
+EOF
+```
+
+2. 关联到 incident 模板（写 incident 时引用 runbook）
+
+3. 长期维护：每次重大故障后写 incident → 复盘 → 更新 runbook
+
+## 关联规则
+
+- 关联到 R18 L1 implemented 后必须建决策卡片（重大运维决策也算）

package/skill/subskills/testplan.md

@@ -0,0 +1,48 @@
+# TestPlan 子 skill — 测试方案
+
+## 用途
+
+为 L3 spec 写"测试方案"（testplan.md）：
+- 描述本 L3 实施时需要的测试类型 + 用例
+- 与 plan.md 互补：plan = 时间维度，testplan = 质量维度
+
+## 流程
+
+1. 读 L3 spec + 父 L2
+
+```bash
+spec-manager spec show 2026-06-04-c3d4e5 --include-content
+```
+
+2. 创建 testplan：
+
+```bash
+# 用 git 直接写，或：
+mkdir -p testplans/auth
+cat > testplans/auth/2026-06-04-c3d4e5-testplan.md <<'EOF'
+# <L3 title> 测试方案
+
+## 单元测试
+- 覆盖函数：
+  - signJwt()：正常 + 异常（key 缺失 / 过期）
+  - verifyJwt()：合法 / 过期 / 篡改签名
+
+## 集成测试
+- 登录成功 → 拿到 token → 调 /me 拿到 user
+- token 过期 → 401
+- 篡改 token → 401
+
+## 端到端
+- Playwright：注册 → 登录 → 访问受保护页
+
+## 验证命令
+- pnpm test
+- pnpm test:integration
+EOF
+```
+
+3. 写完同样用 `spec update --ai-summary` 记一句
+
+## 关联规则
+
+- R10 planJson 最后一步必须是验证（testplan 是 plan 的姊妹）

package/templates/L0-prd.md

@@ -0,0 +1,43 @@
+<!-- ========== Stage Charter: L0 Vision ==========
+Value: 长期方向档案 — 回答"3-5 年后这个产品要变成什么"
+Time horizon: 极长期(3-5 年,只在大方向变化时更新)
+Target reader: 高层/投资人/产品负责人、未来 AI agent 在评估某 L1 是否符合产品方向时的参照
+Must NOT have:
+  - 用户故事 / 验收标准 → 下到 L1
+  - 模块 / 接口 / 数据模型 → 下到 L2
+  - 实施步骤 / 验证命令 → 下到 L3
+Soft boundary: 路线图按里程碑划分,每个里程碑对应 1-N 个 L1 spec(用 code 引用,不复述)
+
+L0 ↔ L1 ↔ L2 ↔ L3 关系:
+  L0 = 愿景(1 个项目通常 1 个 L0)
+  L1 = 需求(每个 L0 里程碑下挂多个 L1)
+  L2 = 设计(每个 L1 下挂多个 L2)
+  L3 = 实施(每个 L2 下挂多个 L3)
+
+Expert guidelines:
+  - 愿景 1-2 段,不要写产品功能清单(那是 L1)
+  - 路线图按"里程碑"划分而非"季度",每段 1-2 句话
+  - 路线图每阶段必须标 milestone 编号(对齐 schema 的 milestone 字段,如 v1.0/v1.1)
+  - 不量化目标(那是 L1 度量指标)
+  - L0 改动频率极低,不要在 L0 里写"持续优化"这种不会过时的废话
+========== -->
+
+# {{title}} — 愿景
+
+## 愿景
+
+<1-2 段话回答:这个产品/系统 3-5 年后要变成什么?为什么世界需要它?禁止"打造一流/持续优化"等空话。>
+
+## 路线图
+
+<按里程碑划分,每段 1-2 句话,标 milestone 编号(v1.0/v1.1/...)。每个 milestone 对应 1-N 个 L1 spec,用 code 引用(写完 L1 后回头补全)>。
+
+| 里程碑 | 方向 | L1 关联 |
+|---|---|---|
+| v1.0 | <一句话:这一里程碑的核心交付> | <L1 code, 写完 L1 后填> |
+| v1.1 | <一句话> | - |
+| v2.0 | <一句话> | - |
+
+## 关联
+
+<parentCode: 无(L0 是顶层)。若有前序 L0,列 based_on/supersedes 关系。>

package/templates/L1-prd.md

@@ -0,0 +1,130 @@
+<!-- ========== Stage Charter: L1 PRD ==========
+Value: 业务档案馆 — 回答"为什么做这个功能"
+Time horizon: 长期(≥1 年,功能下线前都有效)
+Target reader: 产品/业务方、未来 AI agent 在做类似需求时的参照
+Must NOT have:
+  - 文件路径 / DDL / planJson / bash 命令 → 下到 L3
+  - 具体技术选型 / API 签名 / 函数名 → 下到 L2
+  - 实施步骤 / 步骤验证 → 下到 L3
+Soft boundary: 可引用上层 plan/PRD id,不复述(见 rules/doc-governance.md#R14)
+
+Expert guidelines:
+  - 背景必须有数据/证据支撑(事故次数/耗时/成本),不接受"大家都觉得"式论述
+  - 用户故事按 MoSCoW 分级(Must/Should/Could/Won't),Must 3-5 条
+  - 验收标准必须可判定(能回答 yes/no),禁止"改善/提升/优化"等模糊词
+  - 范围边界的"不做"同等重要,必须列出至少 2 条显式排除
+  - 度量指标必须有基线值和目标值,无基线则标注"待测量"
+  - 设计原则是给 L2 的约束,每条附带"违反判断标准"
+  - 问题归类先于用户故事,确保需求来源可追溯
+
+PRE-WRITE INTERACTION (mandatory):
+  在写 L1 正文之前,AI agent 必须先用当前工具的用户提问能力向用户确认以下 3 个问题。
+  Q4 历史决策查询（执行于 Q1-Q3 之前）: AI agent 必须先调 `spec-manager decision list --topic <topic>`。
+    若存在 active 决策卡片,将决策摘要展示给用户。
+    让用户确认新 L1 是否与历史决策一致或有意覆盖。
+========== -->
+
+# {{title}} — 需求文档
+
+## 背景
+
+<痛点/数据/业务动机。说明为什么此刻要做、不做会怎样。必须包含量化证据(事故次数/耗时/成本)。禁止技术方案描述>
+
+## 问题归类
+
+<将背景中的问题按根因分类,标注优先级。帮助后续 L2 按类别拆分而非按事件堆砌>
+
+| 类别 | 问题描述 | 优先级 | 证据来源 |
+|---|---|---|---|
+| ... | ... | P1/P2/P3 | <incident/数据/用户反馈> |
+
+## 用户故事
+
+<As a <角色>, I want <能力>, so that <价值>。按 MoSCoW 分级>
+
+### Must have
+
+- As a ..., I want ..., so that ...
+
+### Should have
+
+- As a ..., I want ..., so that ...
+
+### Could have
+
+- As a ..., I want ..., so that ...
+
+## 功能目标
+
+<"能做什么"对比表。现状列必须真实可验证,目标列禁止"更好/更快"等模糊词>
+
+| 能力 | 现状(量化) | 目标(量化) |
+|---|---|---|
+| ... | ... | ... |
+
+## 验收标准
+
+<用户视角的成功判据。每条必须是 given/when/then 格式,可直接作为测试用例。禁止 grep/curl 等技术手段>
+
+> **RFC 2119 关键字指引**: 验收标准中使用以下关键字标注约束级别：
+> - **SHALL** (必须) — 硬性要求,不满足则验收不通过
+> - **MUST** (应当) — 强烈建议,例外需说明理由
+> - **SHOULD** (推荐) — 最佳实践,可酌情调整
+> - **MAY** (可选) — 完全可选
+>
+> 示例: `**AC-1**: **Given** X, **When** Y, **Then** 系统 **SHALL** 返回 Z`
+
+1. **AC-1**: **Given** ..., **When** ..., **Then** ... **SHALL** ...
+2. **AC-2**: **Given** ..., **When** ..., **Then** ... **MUST** ...
+
+## 度量指标
+
+<上线后如何衡量成功。每个指标必须有基线、目标、测量方式>
+
+| 指标 | 基线 | 目标 | 测量方式 |
+|---|---|---|---|
+| ... | <当前值/待测量> | ... | <数据源/查询方式> |
+
+## 范围边界
+
+- **做**:...
+- **不做**(显式排除,至少 2 条):
+  - ...
+  - ...
+- **推迟**(后续版本考虑):...
+
+## 设计原则
+
+<指导后续 L2 技术决策的约束条件。每条原则附带"违反判断标准">
+
+1. **原则名** — 一句话描述。违反判断:<怎么判断违反了这条原则>
+2. ...
+
+## 里程碑
+
+<按交付阶段划分,每阶段标注核心交付物和前置依赖。无需精确到天>
+
+| 阶段 | 交付内容 | 前置依赖 | 优先级 |
+|---|---|---|---|
+| Phase 1 | ... | 无 | P1 |
+| Phase 2 | ... | Phase 1 完成 | P2 |
+
+## 交付物分解
+
+<模块/领域粒度的交付物清单。用于预估 L2 个数。禁止文件级。每个交付物标注归属阶段>
+
+| 交付物 | 归属阶段 | 预估 L2 个数 |
+|---|---|---|
+| ... | Phase 1 | 1-2 |
+
+## 风险与依赖
+
+<业务层面的风险和外部依赖。技术风险下到 L2>
+
+| 风险/依赖 | 影响 | 缓解措施 |
+|---|---|---|
+| ... | ... | ... |
+
+## 关联
+
+<parentCode: PLAN-xxx-001 的 specCode。若有前序 L1,列 based_on/supersedes 关系。若基于 PRD,标注 PRD 编号>

package/templates/L2-design.md

@@ -0,0 +1,135 @@
+<!-- ========== Stage Charter: L2 Design ==========
+Value: 技术契约 — 回答"用什么方案、改哪些模块、API 长什么样"
+Time horizon: 中期(模块演进前有效)
+Target reader: L3 写作者、代码审核者
+Must NOT have:
+  - 业务背景论证 / 用户故事 → 上到 L1
+  - 具体文件路径 / 函数签名 / planJson → 下到 L3
+  - 实施步骤 / 步骤验证 → 下到 L3
+Soft boundary: 可引用父 L1 code + 一句话定位,不复述(见 rules/doc-governance.md#R14)
+
+Expert guidelines:
+  - 关键技术决策必须用表格,每行含"用户选定 + 选定理由",不允许空泛叙述
+  - 接口契约必须精确到请求/响应/错误码
+  - L3 裂变计划按模块边界拆,不是按功能点(R17)
+========== -->
+
+# {{title}} — 技术设计
+
+## 方案概述
+
+<一段话 + ASCII 架构图(可选)>
+
+```
+[组件 A] ──HTTP──> [组件 B]
+   │
+   └──> [DB]
+```
+
+## 关键技术决策
+
+<关键选型的"问题/选项/选择/理由"表。空选项或"随便选"会被审计拦截>
+
+| 问题 | 候选选项 | 用户选择 | 选定理由 |
+|---|---|---|---|
+| ... | A:..., B:... | A | ... |
+| ... | A:..., B:... | B | ... |
+
+## 受影响模块
+
+<按模块/目录组织。每行标注变更类型/范围/测试策略>
+
+| 模块/路径 | 变更类型 | 范围 | 测试策略 |
+|---|---|---|---|
+| ... | 新增/修改/删除 | 函数级 | 单元/集成 |
+
+## 数据模型
+
+<实体/字段/类型/变更/默认值/向后兼容。Schema 变更同步登记到 dict>
+
+| 实体 | 字段 | 类型 | 变更 | 默认值 | 向后兼容 |
+|---|---|---|---|---|---|
+| ... | ... | ... | 新增/修改 | ... | 是/否 |
+
+## 接口契约
+
+<每个端点: 请求 / 成功响应 / 错误响应表>
+
+### POST /api/example
+
+**请求**:
+```json
+{ "field": "value" }
+```
+
+**成功响应 (200)**:
+```json
+{ "id": 123, "status": "ok" }
+```
+
+**错误响应**:
+
+| 状态码 | 错误码 | 触发条件 |
+|---|---|---|
+| 400 | INVALID_INPUT | 参数校验失败 |
+| 401 | UNAUTHORIZED | 未登录 |
+| 403 | FORBIDDEN | 权限不足 |
+| 409 | DUPLICATE | 资源已存在 |
+
+## 容错与降级
+
+<故障场景/影响/降级策略/恢复>
+
+| 场景 | 影响 | 降级策略 | 恢复方式 |
+|---|---|---|---|
+| 依赖 X 不可用 | ... | ... | ... |
+
+## 向后兼容
+
+<API/数据/迁移计划>
+
+- **API**: ...
+- **数据**: ...
+- **迁移**: ...
+
+## 关键交互流程
+
+<时序图(可选 ASCII)+ 异常分支>
+
+```
+用户 → API → Service → DB
+  │      │       │       │
+  │      │       │       └─ 写记录
+  │      │       └─ 计算 X
+  │      └─ 返回 200
+  └─ 收到响应
+```
+
+## 可观测性
+
+<日志/指标/告警>
+
+- **日志**: ...
+- **指标**: ...
+- **告警**: ...
+
+## 复用清单
+
+<必须引用具体文件路径和类/函数名,不允许"用现有的 X"这种泛化>
+
+| 工具类/基类 | 路径 | 类/函数 | 用途 |
+|---|---|---|---|
+| ... | src/.../X.java | Y | ... |
+
+## L3 裂变计划
+
+<本 L2 拆成几个 L3 执行,按模块边界而非功能点。R17: 1:1 或 1:2>
+
+| L3 code | 范围 | 前置依赖 |
+|---|---|---|
+| 2026-06-06-c3d4e5 | ... | 无 |
+| 2026-06-07-d4e5f6 | ... | 2026-06-06-c3d4e5 implemented |
+
+## 关联
+
+<引用父 L1 的 code + 一句话定位,不展开复述>

package/templates/L3-impl.md

@@ -0,0 +1,125 @@
+<!-- ========== Stage Charter: L3 Impl ==========
+Value: 执行日志 — 回答"具体改哪些文件/函数,怎么验证"
+Time horizon: 短期(实施完成即沉淀,后续仅供审计)
+Target reader: Agent Task 执行者(AI agent)、代码审核者
+Must NOT have:
+  - 业务背景论证 / 用户故事 → 上到 L1
+  - 架构选型对比 / 多方案比较 → 上到 L2
+  - 成功标准(用户视角) → 上到 L1
+  - 重复方案概述 → 引用 L2 code 即可
+Soft boundary: 可引用父 L2 code + 一句话定位,不复述(见 rules/doc-governance.md#R14)
+
+Expert guidelines:
+  - 每步实施必须精确到函数/方法级别,禁止"修改相关代码"等模糊表述
+  - planJson 字段名必须从 templates/agent-plan.json 读取,禁止凭记忆(R12/INC-005)
+  - step_report 每步必须携带 outputJson(R15),格式见下方模板
+  - coveredSpecs: 若本 Task 实际覆盖多条 L3,必须在 planJson 中声明
+  - 验证命令必须可直接粘贴执行,含预期输出的精确匹配串
+  - 回滚方案不是可选项,每个 L3 必须说明"改坏了怎么恢复"
+  - 写 L3 前必须执行 Level 3 文件级分析(R23,见 rules/codebase-survey.md)
+  - 注: optimization-L1 P0 — 本模板不再含"变更文件清单"表格,文件变更由 git 管理
+========== -->
+
+# {{title}} — 实施规格
+
+## 目标
+
+<一句话 + 引用父 L2 的 deliverable 编号。形如"实施 2026-06-05-b2c3d4 的 deliverables 1/2/3">
+
+**前置依赖**:<前序 L3 specCode 已 implemented 声明,若无则"无">
+
+## 实施步骤
+
+> **RFC 2119 关键字指引**: 实施步骤中使用以下关键字标注约束级别：
+> - **SHALL** (必须) — 硬性要求,不执行则任务不可完成
+> - **MUST** (应当) — 强烈建议,例外需说明理由
+> - **SHOULD** (推荐) — 最佳实践,可酌情调整
+> - **MAY** (可选) — 完全可选
+
+### Step 1 — 上下文收集
+
+- `spec-manager spec show <本 L3 code> --include-content` + `spec-manager spec show <父 L2 code> --include-content`
+- 执行 Level 3 文件级分析(R23):
+  - 查架构基线获取文件清单
+  - Read L2"受影响模块"中的每个文件,确认存在
+  - 追踪 import/依赖关系
+  - 识别测试文件
+  - 验证变更清单中所有路径
+- `Read templates/agent-plan.json` 确认 planJson 字段名(R12)
+
+### Step 2 — <具体动作>
+
+- <精确到 Edit/Write/Bash,含 old_string 锚点>
+- 完成后 step_report outputJson:
+  ```json
+  {"summary": "<完成内容>", "files": ["<变更文件>"]}
+  ```
+
+### Step N-1 — 部署(若涉及后端)
+
+### Step N — 验证
+
+<必须有正向验证(正常输入) + 反向验证(错误/边界输入)>
+
+## 验证命令
+
+```bash
+# 正向验证: 正常场景
+# 命令 + 预期输出(精确匹配串)
+...
+
+# 反向验证: 错误/边界场景
+# 命令 + 预期错误码/消息
+...
+```
+
+## step_report 模板
+
+<每步完成后调用 `spec-manager task step` 时使用此格式。必须在工作完成后调用,不得预报>
+
+```json
+{
+  "taskId": "<task id>",
+  "stepNo": 1,
+  "stepType": "mcp_tool",
+  "status": "succeeded",
+  "toolName": "<实际调用的工具名>",
+  "latencyMs": "<实际耗时>",
+  "outputJson": "{\"summary\":\"<完成内容>\",\"files\":[\"<变更文件>\"]}"
+}
+```
+
+## planJson (final)
+
+<⚠️ 字段名必须与 templates/agent-plan.json 一致: stepNo / stepType / name。禁止凭记忆拼写>
+
+```json
+{
+  "coveredSpecs": ["<若覆盖多条 L3,列出所有 specCode;单条则省略此字段>"],
+  "steps": [
+    {"stepNo": 1, "stepType": "mcp_tool", "name": "上下文收集: spec-manager spec show(L3 + 父 L2)"},
+    {"stepNo": 2, "stepType": "mcp_tool", "name": "<动词+宾语+文件>"},
+    {"stepNo": "N-1", "stepType": "mcp_tool", "name": "部署(若涉及后端)"},
+    {"stepNo": "N", "stepType": "mcp_tool", "name": "验证: <命令 + 预期输出>"}
+  ]
+}
+```
+
+<autoConfirm 取值 + 理由>
+
+## 回滚方案
+
+<改坏了怎么恢复。必填>
+
+| 场景 | 回滚操作 | 预估耗时 |
+|---|---|---|
+| 代码问题 | `git revert <commit>` + 重新部署 | < 5 min |
+| 数据问题 | <SQL 回滚脚本/备份恢复> | ... |
+
+## 执行风险
+
+<这一步卡住怎么办。禁架构风险(上到 L2)>
+
+| 风险 | 应对 |
+|---|---|
+| ... | ... |

package/templates/agent-plan.json

@@ -0,0 +1,17 @@
+{
+  "_comment": "agent planJson 模板。字段名 stepNo / stepType / name,禁止用 no / type / desc (INC-005)。",
+  "_constraints": [
+    "step 1 必须是上下文收集(读 L3 spec + 父 L2 + 历史任务)",
+    "末步必须是可执行的验证命令(R10)",
+    "单 Agent Task = 单 L3 spec,步数 ≤ 20(R11);超 16 步必拆 L3",
+    "每步 name 必须含 verb+object+file,禁止'优化/改进/处理'等模糊动词",
+    "stepType 仅限 llm_call / mcp_tool / human_gate"
+  ],
+  "coveredSpecs": ["2026-06-04-c3d4e5"],
+  "steps": [
+    {"stepNo": 1, "stepType": "mcp_tool", "name": "上下文收集: spec-manager spec show L3 + 父 L2 + 读 templates/agent-plan.json"},
+    {"stepNo": 2, "stepType": "mcp_tool", "name": "编辑 <ServiceName>.java 新增方法 <verb>"},
+    {"stepNo": "N-1", "stepType": "mcp_tool", "name": "部署后端 JAR (如涉及)"},
+    {"stepNo": "N", "stepType": "mcp_tool", "name": "验证: curl http://... 返回 200 + 预期 body"}
+  ]
+}

package/templates/agents/AGENTS.md

@@ -0,0 +1,27 @@
+# spec-manager Workflow Capsule
+
+This file is the spec-manager skill-like entrypoint for Codex, OpenCode, and other `AGENTS.md`-compatible tools. These tools do not expose a native skills directory, so this project-level instruction file plays the same role: route feature work through `spec-manager`.
+
+This project uses `spec-manager` for local-first spec-driven development. Specs, tasks, decisions, changes, and audit data are stored as markdown/JSON files in the repository.
+
+## Mandatory Workflow
+
+- Feature work MUST go through `spec-manager`; do not jump directly from a user request to implementation code.
+- New or non-trivial work follows L1 PRD -> L2 Design -> L3 Impl -> Agent Task.
+- Never write implementation code unless the relevant L3 spec is `frozen`.
+- `draft -> confirmed` and `confirmed -> frozen` are user review actions. After writing spec content, stop and wait for explicit user approval.
+- Before creating a new spec, inspect existing specs and decisions with `spec-manager spec list` and `spec-manager decision list --topic <topic>`.
+- Before code edits, read the relevant frozen L3 spec and create/start an Agent Task.
+- Record execution with `spec-manager task step`; finish with `spec-manager task complete`.
+
+## Common Commands
+
+```bash
+spec-manager project status
+spec-manager spec list
+spec-manager spec show <code> --include-content
+spec-manager decision list --topic <topic>
+spec-manager task list --topic <topic>
+```
+
+When the user asks for `/spec-manager <request>` or asks to use spec-manager, treat it as a request to follow this workflow.

package/templates/agents/CLAUDE.md

@@ -0,0 +1,11 @@
+# Spec-Driven Development
+
+This project uses `spec-manager` via the `/spec-manager` skill.
+
+- All feature work MUST go through `/spec-manager`; no direct code changes for non-trivial work.
+- Never write implementation code without a frozen L3 spec.
+- Never skip human review gates. L1, L2, and L3 each require explicit user approval.
+- Status transitions (`confirm` and `freeze`) are user actions, not AI actions.
+- For research, prefer `spec-manager spec show` metadata first, then `--include-content` when full context is required.
+
+Use the installed `.claude/skills/spec-manager/` skill when the user invokes `/spec-manager` or approves the next spec-manager step.