spec-manager 0.1.0

package/skill/SKILL.md

@@ -0,0 +1,90 @@
+---
+description: "Spec-driven project iteration workflow — L1 PRD → L2 Design → L3 Impl → Agent Task → Deploy, with human review gates at each layer. Pure local markdown storage, no MCP, no network. Use when the user invokes /spec-manager or asks for: new feature/PRD, technical design, implementation spec, agent task, iteration plan, test plan, release notes, runbook, postmortem, or ADR."
+argument-hint: "<需求描述> | run <taskId>"
+---
+
+# spec-manager — 本地项目迭代全链路
+
+PRD → Design → Spec → Agent Task → 部署。**纯本地**，所有数据落 markdown + git。
+
+## 用法
+
+- `/spec-manager <需求>` — 从需求开始走完整链路
+- `/spec-manager run <taskId>` — 执行已有 Agent Task
+
+## 入口路由
+
+收到 `/spec-manager <用户输入>` 时，按下表匹配子 skill；不确定时用当前工具的用户提问能力澄清。关键词重叠按 # 小者优先。
+
+| # | 关键词 | 子 skill | 产出 |
+|---|---|---|---|
+| 1 | 修 typo / 改一行 / 改 log level | [subskills/quick.md](subskills/quick.md) | quick |
+| 2 | 查 / 看 / 列 / 统计 / 搜索 | [subskills/research.md](subskills/research.md) | (只读) |
+| 3 | 需求 / 新功能 / 痛点 / 用户故事 | [subskills/prd.md](subskills/prd.md) | L1 |
+| 4 | 技术方案 / 架构 / 接口设计 | [subskills/design.md](subskills/design.md) | L2 |
+| 5 | 实施 / 编码 / planJson | [subskills/impl.md](subskills/impl.md) | L3 |
+| 6 | 计划 / 里程碑 / 排期 | [subskills/plan.md](subskills/plan.md) | plan |
+| 7 | 测试方案 / QA / 测试用例 | [subskills/testplan.md](subskills/testplan.md) | testplan |
+| 8 | 发布 / changelog / release | [subskills/release.md](subskills/release.md) | release |
+| 9 | 运维手册 / oncall | [subskills/runbook.md](subskills/runbook.md) | runbook |
+| 10 | 复盘 / postmortem / RCA | [subskills/postmortem.md](subskills/postmortem.md) | postmortem |
+| 11 | ADR / 为什么选 X | [subskills/adr.md](subskills/adr.md) | decision |
+| 12 | delta / change / 增量 | [subskills/change.md](subskills/change.md) | change |
+
+**消歧规则**: 关键词重叠时小 # 优先；看不懂意图不要猜，先问用户；2 次仍无法定位则停止走 /spec-manager。
+
+## 方法论
+
+| 层 | 产物 | 核心约束 |
+|---|---|---|
+| L1 PRD | 需求文档 | 新功能必须先写 |
+| L2 Design | 技术设计 | confirmed 才能进实施 |
+| L3 Impl | 实施规格 | ≤20 步，frozen 后建 Task |
+
+## 规则（24 条，按 applies_to 过滤）
+
+| 主题 | 规则 | 文件 |
+|---|---|---|
+| 流程控制 | R1-R4 停下审核/状态归用户/frozen 才建 Task | [rules/flow-control.md](rules/flow-control.md) |
+| 质量门禁 | R5/R6/R10/R15/R18 不跳步/planJson 校验 | [rules/quality-gate.md](rules/quality-gate.md) |
+| 文档治理 | R7/R11/R13/R14/R16-R22 层级绑定/aiSummary | [rules/doc-governance.md](rules/doc-governance.md) |
+| 代码纪律 | R8/R9/R12 改代码前自检 | [rules/code-discipline.md](rules/code-discipline.md) |
+| 代码调查 | R23 Spec 前必须基于实际代码 | [rules/codebase-survey.md](rules/codebase-survey.md) |
+| Delta | R24 delta 必须含 proposal | [rules/delta.md](rules/delta.md) |
+
+## Spec 状态流
+
+```
+draft → confirmed → frozen → implemented
+ AI agent 用户      用户     task_complete
+```
+
+## CLI 概要
+
+`spec-manager <command> --help` 查看完整用法。主要命令组：
+
+- `project init|status` — 初始化/总览
+- `spec new|list|show|update|confirm|freeze|implement|validate|add-relation` — Spec CRUD
+- `task create|start|step|complete|fail|wait|show|list` — Agent Task
+- `decision create|list|show|update|set-partial|supersede` — 决策卡片
+- `change new|archive|list|show` — Delta spec
+- `incident new|list` — 事故记录
+- `audit hit|report|show` — 规则审计
+
+## 数据布局
+
+```
+<project>/
+├── .spec-manager/                # config + audit + incidents
+├── specs/<topic>/                # spec 平铺（点分编号自文档化层级）
+│   ├── <L1-code>-<date>.md
+│   ├── <L2-code>-<date>.md
+│   ├── <L3-code>[-desc]-<date>.md
+│   ├── decisions/               # 决策卡片（topic 级别）
+│   └── tasks/                   # Agent Task（topic 级别）
+│       └── <specCode>-<taskId>.json
+├── changes/<name>/              # delta 提案
+└── archive/<name>/              # 已合并 change
+```
+
+违反任一规则视为流程事故，参照 `.spec-manager/incidents/_TEMPLATE.md` 记录。

package/skill/subskills/adr.md

@@ -0,0 +1,73 @@
+# ADR 子 skill — 架构决策记录
+
+## 用途
+
+**优先用 `decision create` 命令**（结构化 what/why/affectedCriteria + topic 查询），非必要不新增 adr 文档。
+
+## Decision vs ADR 的选择
+
+| 维度 | Decision Card（推荐） | ADR 文档 |
+|------|----------------------|----------|
+| 存储 | `specs/<topic>/decisions/DC-NNN.md`（topic 级别） | `adrs/NNNN-title.md` |
+| 字段 | what/why/affectedCriteria | 全文 Markdown |
+| 状态机 | active/superseded/partial | N/A（顺序追加） |
+| 查询 | `decision list --topic X` | 扫文件 |
+| 强制 | R18 强制 L1 implemented 后建 | 不强制 |
+
+## Decision 创建流程
+
+1. 触发条件：L1 spec 走到 `implemented`
+2. 必走：
+
+```bash
+spec-manager decision create 2026-06-04-a1b2c3 \
+  --topic auth \
+  --what "采用 JWT 而非 session" \
+  --why "无状态扩展，便于多服务共享身份" \
+  --criteria "AC-1,AC-2"
+```
+
+3. supersede：
+
+```bash
+# 旧决策被新决策取代
+spec-manager decision supersede DC-001 --by DC-002
+```
+
+## ADR 创建流程（少数情况）
+
+如果决策需要：
+- 大段背景 / 备选方案对比 / 详细 trade-off
+- 多人评审记录
+
+则走 ADR：
+
+```bash
+mkdir -p adrs
+cat > adrs/0007-use-paseto.md <<'EOF'
+# 7. 用 PASETO 替代 JWT
+
+## 背景
+JWT 有 alg=none 等已知攻击面...
+
+## 候选方案
+1. 继续 JWT + 严格校验 alg
+2. PASETO（平台无关安全 token）
+3. 自研 session
+
+## 决定
+方案 2
+
+## 影响
+- 库替换：jose → paseto
+- 决策卡片：DC-002
+
+## 关联
+- spec: 2026-06-04-a1b2c3
+- decision: DC-002
+EOF
+```
+
+## 关联规则
+
+- R18 L1 implemented 后必须建决策卡片（ADR 不替代）

package/skill/subskills/change.md

@@ -0,0 +1,118 @@
+# Change 子 skill — Delta Spec 提案（OpenSpec 风格）
+
+## 用途
+
+当需要**修改已存在的 spec** 时（不是新建一个 L1/L2/L3），用 change 提案：
+- 比"改 spec 文件 + git diff"更结构化
+- archive 时机 = 知识合并点（带 proposal + delta spec 的完整审计轨迹）
+- 比"另起一个 v2 spec"更轻量
+
+## 流程
+
+1. 创建 change 目录：
+
+```bash
+spec-manager change new add-2fa --description "新增 2FA 双因素认证"
+```
+
+输出：
+```
+changes/add-2fa/
+├── README.md
+├── proposal.md          ← 填写 why/scope/risk
+├── deltas/              ← 在这里创建 <spec-code>.md
+└── specs/auth/          ← ADDED 时放新 spec 占位
+```
+
+2. 写 `proposal.md` frontmatter（why + scope 必填）：
+
+```yaml
+---
+name: add-2fa
+why: 高频账号被盗事件
+scope: auth L1 加 2FA 需求
+risk: 用户登录多一步
+rollback: 移除 2FA 强制，保留可选
+affectedCriteria:
+  - AC-1
+  - AC-2
+---
+```
+
+3. 写 delta spec 文件 `deltas/<code>.md`：
+
+```markdown
+---
+code: 2026-06-04-a1b2c3
+---
+
+## MODIFIED Requirements
+
+### Requirement: 2026-06-04-a1b2c3
+## 2FA 强制
+
+登录成功后系统 **SHALL** 要求 TOTP 二次校验。
+**SHALL NOT** 仅靠密码判定身份。
+
+## 范围边界
+- 邮箱 + 密码
+- TOTP
+- 备份码
+
+## 验收标准
+1. **AC-1-2fa**: **Given** 用户登录成功 **When** 系统检测未配置 2FA **Then** **SHALL** 引导用户设置
+2. **AC-2-2fa**: **Given** 用户已配置 2FA **When** 登录 **Then** **SHALL** 要求 TOTP
+```
+
+支持 4 种 op：
+- `## ADDED Requirements` — 新增 spec
+- `## MODIFIED Requirements` — 修改 spec
+- `## REMOVED Requirements` — 删除 spec
+- `## RENAMED Requirements` — 改名 spec（`- FROM: X TO: Y`）
+
+4. ADDED 时需要 `changes/<name>/specs/<topic>/<code>/<code>.md` 占位文件（含 frontmatter level/title/parentCode）—— 占位文件按 `<code>/<code>.md` 嵌套存放（仅限 changes/ 目录），archive 时由 `archiveChange` 根据 `parentCode` 创建到主 specs 平铺目录：
+
+```bash
+mkdir -p changes/add-2fa/specs/auth/auth-L2.1
+cat > changes/add-2fa/specs/auth/auth-L2.1/auth-L2.1.md <<'EOF'
+---
+code: auth-L2.1
+level: L2
+title: 2FA 后端设计
+topic: auth
+parentCode: auth-L1
+status: draft
+project: 1
+---
+# 占位
+EOF
+```
+
+5. 应用：
+
+```bash
+spec-manager change archive add-2fa
+```
+
+输出（按 RENAMED→REMOVED→MODIFIED→ADDED 顺序）：
+```
+✓ Change add-2fa archived
+  applied: 2
+    [MODIFIED] 2026-06-04-a1b2c3
+    [ADDED] 2026-06-05-d4e5f6
+  archived to: archive/add-2fa
+```
+
+archive 会自动：
+- 把 deltas/ 内容追加到主 spec 的 `## Delta (<name>)` 段
+- 创建 ADDED 的新 spec
+- REMOVED 把主 spec 移到 archive/
+- RENAMED 改文件路径 + frontmatter code
+- 整个 changes/<name>/ 目录移到 archive/<name>/
+- 写 audit hit R24
+
+## 关联规则
+
+- R14 跨层引用用 code 不是复述
+- R24 delta change 必须含 proposal + delta spec
+- R18 L1 implemented 后必须建决策卡片（改动 L1 时同步建/改 decision）

package/skill/subskills/design.md

@@ -0,0 +1,53 @@
+# Sub-skill: Design (L2)
+
+## 路由自检
+
+✓ 走本 skill 的信号：用户说"技术方案/架构/选型/接口设计/数据模型/可选方案"
+✗ 不走的信号：用户说"业务需求"（→ prd.md）或"实施"（→ impl.md）或"typo"（→ quick.md）
+
+## 模板
+
+- [templates/L2-design.md](../templates/L2-design.md)
+
+## 流程
+
+### L2 Spec 创建
+
+1. **确认父 L1**：`spec-manager spec show <L1 code>`（默认 narrow 视图读 aiSummary）
+   > 🔍 **R19 自检**: 研究/跨层是否只读 aiSummary？→ `spec-manager audit hit R19`
+2. **L2 全文读父**（R19 跨层设计强制）：写 L2 正文前必须 `spec show <L1 code> --include-content` 读父 L1 全文
+3. **Level 2 代码调查**（R23）：Read ≥3 个源文件了解模块
+4. **创建 L2**：
+   ```bash
+   spec-manager spec new L2 --topic <topic> --title "..." --parent <L1 code>  # --code 不传则自动生成
+   ```
+   > 🔍 **R7 自检**: L2 是否绑定了父 L1？→ `spec-manager audit hit R7`
+5. **写正文**：
+   ```bash
+   spec-manager spec update <code> --content ./draft.md --ai-summary "..." --change-summary "..."
+   ```
+   L2 必填段：方案概述 / 受影响模块 / 接口契约 / L3 裂变计划
+6. 🛑 **等用户审核**（R1）
+7. 用户批准 → `spec-manager spec confirm <code>`（R2）
+
+## L2 是架构拆解（R17）
+
+- L1:L2 比例 1:1 或 1:2
+- 按模块边界拆，不是功能点
+- L2 裂变计划表格列出所有 L3
+
+## 与主 SKILL.md 关系
+
+L2 confirmed 后，路由到 `subskills/impl.md` 继续 L3。
+
+## 适用规则
+
+R1 / R2 / R4 / R7 / R13 / R14 / R17 / R19 / R22 / R23
+
+## 相关规则（按需加载）
+
+| 规则 ID | 文件 | 适用场景 |
+|---|---|---|
+| R7/R14/R17 | [rules/doc-governance.md](../rules/doc-governance.md) | 层级绑定 / 跨层引用 / 架构拆解 |
+| R19 | [rules/doc-governance.md](../rules/doc-governance.md) | 写 L2 前必读父 L1 全文 |
+| R23 | [rules/codebase-survey.md](../rules/codebase-survey.md) | Level 2 模块深潜（≥3 源文件） |

package/skill/subskills/impl.md

@@ -0,0 +1,100 @@
+# Sub-skill: Impl (L3 + Agent Task)
+
+## 路由自检
+
+✓ 走本 skill 的信号：用户说"实施/实现/编码/写代码/具体文件/planJson"
+✗ 不走的信号：用户说"业务需求"（→ prd.md）或"架构设计"（→ design.md）或"typo"（→ quick.md）
+
+## 模板
+
+- [templates/L3-impl.md](../templates/L3-impl.md)
+- [templates/agent-plan.json](../templates/agent-plan.json)（planJson 字段名 stepNo/stepType/name）
+
+## 流程
+
+### L3 Spec 创建
+
+1. **确认父 L2**：`spec-manager spec show <L2 code>`
+   > ☑ **R7**: L3 必须绑父 L2（违反时 CLI 自动 audit hit,见 `audit show`）
+2. **L3 全文读父**（R19 跨层设计强制）：`spec show <L2 code> --include-content`
+3. **文件级分析（Level 3）**（R23）：
+   - 读 L2"受影响模块"中的每个文件，确认存在
+   - 追踪 import/依赖：`grep -rn "functionName" <module-dir>`
+   - 识别测试文件：`find <module-dir>/../test -name "*Test*"`
+   > ☑ **R23** / **R12** / **R8** — 流程规则,人工把关
+4. **创建 L3**：
+   ```bash
+   spec-manager spec new L3 --topic <topic> --title "..." --parent <L2 code>  # --code 不传则自动生成
+   ```
+   > ☑ **R20** — 流程规则:scope-split L2 时所有子 L3 一次建齐
+5. **写正文**：
+   ```bash
+   spec-manager spec update <code> --content ./draft.md --ai-summary "..." --change-summary "..."
+   ```
+   L3 必填段：目标 / 实施步骤 / 验证命令
+   planJson ≤ 20 步（用户授权 ≤10 — R11），Step 1 上下文收集，末步验证（R10）
+   ```bash
+   spec-manager spec validate-plan ./plan.json  # R10/R11 校验,违反时自动 audit hit
+   ```
+   > ☑ **R11** / **R10** — `validate-plan` 违反时自动 audit hit
+   > ☑ **R13** / **R21** — `--ai-summary` ≤300 字符（CLI 截断,>300 自动 warn）
+   > ☑ **R14** / **R22** — 流程规则,人工把关
+6. 🛑 **等用户审核**（R1）— 流程规则,停下等用户信号
+7. 用户批准 → `spec-manager spec confirm <code>` → 用户再批准 → `spec-manager spec freeze <code>`
+   > ☑ **R2** / **R4** — 流程规则:状态由用户推进,每层独立审核
+   > CLI 在 `confirm`/`freeze` 之前会校验 R22（contentTemplate 非空）
+
+### Agent Task 执行
+
+8. **查历史任务**（连续性层）：
+   ```bash
+   spec-manager task list --topic <topic>
+   ```
+   了解同主题已有实现模式，复用成功的步骤顺序，避免重复踩坑。
+9. **frozen 才可建 Task**（R3）：
+   ```bash
+   spec-manager task create <L3 code> --plan ./plan.json --auto-confirm
+   ```
+   > ☑ **R3** — 非 frozen 时 CLI 拒绝并 audit hit
+10. `spec-manager task start <task-id>`
+11. 逐步 `spec-manager task step <task-id> --no N --type T --name S --status ok --output-json J --latency L`
+    - 禁跳步（R5）
+    - outputJson 必含 summary（R15）
+    - step_report 必须在工作完成后才报（R15）
+    > ☑ **R5** — `task complete` 时仍有 pending/running 步会拒绝并报错
+    > ☑ **R15** — outputJson 缺 summary 时 warning 落 warn 数组
+12. `spec-manager task complete <task-id>`
+    > 完成后看 `cascadedL1Specs`,对每个 L1 用 `decision list --doc-code <L1>` 查是否已建决策卡
+    > ☑ **R6** — 流程规则:确认 cascade 后再标 implemented
+13. 若仍 frozen,手动 `spec-manager spec implement <L3 code>`
+14. L1 implemented 后必须 ≥1 张决策卡片（R18）
+    > ☑ **R18** — task complete 触发 L1 cascade 时 CLI 自动 audit hit,提示待建决策卡
+15. 规则审计合规检查：
+    ```bash
+    spec-manager audit show
+    ```
+    确认最低合规基线通过（R1≥1, R4≥1, R13≥1, R22≥1）
+
+## 与主 SKILL.md 关系
+
+L2 confirmed 后进入本 skill。Agent Task 完成后走 `/deploy` skill 部署。
+
+## 适用规则
+
+R1 / R2 / R3 / R4 / R5 / R6 / R7 / R8 / R10 / R11 / R12 / R13 / R14 / R15 / R18 / R20 / R22 / R23
+
+## 相关规则（按需加载）
+
+| 规则 ID | 文件 | 适用场景 | 类型 |
+|---|---|---|---|
+| R1/R2/R4 | [rules/flow-control.md](../rules/flow-control.md) | 停下审核 / 状态归用户 / 每层独立 | 流程 |
+| R3/R5/R6 | [rules/flow-control.md](../rules/flow-control.md) + [rules/quality-gate.md](../rules/quality-gate.md) | frozen 才建 Task / 不跳步 / task 后校验 | 流程 + 代码 |
+| R7/R11/R13/R14/R22 | [rules/doc-governance.md](../rules/doc-governance.md) | 层级绑定 / 粒度 / aiSummary / 跨层引用 / 创建即写正文 | 代码 + 流程 |
+| R8/R12 | [rules/code-discipline.md](../rules/code-discipline.md) | 改代码前自检 / 禁凭记忆 | 流程 |
+| R10/R15/R18 | [rules/quality-gate.md](../rules/quality-gate.md) | planJson 必含验证 / step 必含 summary / 决策卡片 | 代码 |
+| R20 | [rules/doc-governance.md](../rules/doc-governance.md) | scope-split 批量建齐 | 流程 |
+| R23 | [rules/codebase-survey.md](../rules/codebase-survey.md) | Level 3 文件级分析 | 流程 |
+
+**类型说明**:
+- **代码**:违反时 CLI 自动抛错或 audit hit
+- **流程**:无自动审计,人工把关

package/skill/subskills/plan.md

@@ -0,0 +1,46 @@
+# Plan 子 skill — 实施计划（不是 L2 架构设计）
+
+## 用途
+
+为已确认的 L2 spec 写"实施计划"（plan.md）：
+- **不是 L2 的架构设计**（L2 是"为什么这么做 / 怎么拆模块"）
+- plan.md 是"接下来几周按什么顺序做什么"，可被任意角色读取
+- 与 Agent Task 的关系：plan.md 是 task 的上游，task 是 plan 的执行
+
+## 流程
+
+1. 读父 L2 spec
+2. 用 `spec new L3` 创建 L3 spec（已有则跳过）
+3. 写 `plan.md`：
+
+```bash
+spec-manager spec show 2026-06-04-b2c3d4 --include-content
+```
+
+4. `plan.md` 结构：
+
+```markdown
+# <L2 title> 实施计划
+
+## 阶段拆分
+- 阶段 1（M1）：<一句话目标>
+- 阶段 2（M2）：<一句话目标>
+- ...
+
+## 每个阶段交付
+- M1：L3 spec 列表 + 预期工时
+- M2：...
+
+## 风险
+- ...
+
+## 里程碑 Spec
+- M1: <link to L3 spec>
+```
+
+5. 写完用 `spec update` 把它存到 spec 的 frontmatter `changeSummary` 或专门建一个 plan/ 目录
+
+## 关联规则
+
+- R17 L2 是架构拆解不是 todolist（plan.md 才是 todolist）
+- R20 scope-split 批量建齐子 L3

package/skill/subskills/postmortem.md

@@ -0,0 +1,77 @@
+# Postmortem 子 skill — Blameless 复盘
+
+## 用途
+
+故障复盘（Blameless 风格）：
+- 不指责个人，关注系统和流程
+- 5 Whys 找根因
+- 输出 action items → 改 spec / 改 runbook / 改规则
+
+## 流程
+
+1. 找到对应 incident：
+
+```bash
+spec-manager incident list --status resolved
+```
+
+2. 创建 postmortem：
+
+```bash
+mkdir -p postmortems
+cat > postmortems/INC-20260604-001-postmortem.md <<'EOF'
+# INC-20260604-001 复盘 — R15 step outputJson 缺 summary
+
+## 时间线
+- 10:41 任务开始
+- 10:42 step 3 重试时漏掉 summary
+- 10:45 发现并补 summary
+- 10:50 task complete
+
+## 5 Whys
+1. 为什么 outputJson 缺 summary？—— Agent 模板里只在 happy path 加了
+2. 为什么模板不一致？—— 模板没强制 summary
+3. 为什么没强校验？—— CLI 没把 R15 warning 转 throw
+4. 为什么没早发现？—— task show 不显示 warning
+5. 为什么？—— R15 是软约束
+
+## 根因
+R15 是软约束（warning），缺乏 hard fail 机制
+
+## Action Items
+- [ ] spec-manager task step 校验 R15，缺 summary 时 hard fail（PR #123）
+- [ ] skill impl.md 写明"outputJson 必含 summary"红线
+- [ ] decision：升 R15 为 hard constraint？DC-003 待评估
+
+## 关联
+- incident: INC-20260604-001
+- spec: 2026-06-04-c3d4e5
+- 规则: R15
+EOF
+```
+
+3. 同步更新 runbook / decision / spec
+
+## 决策错误的复盘
+
+如果事故根因追溯到一张「错」的决策卡片（DC-XXX），复盘要补两件事：
+
+```bash
+# 1) 标记该决策为 partial（部分被取代/作废）
+spec-manager decision set-partial DC-001 --reason "INC-20260604-001 复盘:AC-3 设计假设不成立"
+
+# 2) 用新决策 supersede 旧的
+spec-manager decision create <L1 code> \
+  --topic <topic> \
+  --what "改用 X 而非 Y" \
+  --why "INC-20260604-001:旧决策 AC-3 在 <场景> 下不成立" \
+  --criteria AC-3
+
+spec-manager decision supersede DC-001 --by DC-002
+```
+
+这样多轮迭代后,`decision list --criteria AC-3` 能返回完整历史(active / superseded / partial)。
+
+## 关联规则
+
+- 关联 R18 决策卡片（重大改动的决策落库）

package/skill/subskills/prd.md

@@ -0,0 +1,72 @@
+# Sub-skill: PRD (L1)
+
+## 路由自检
+
+✓ 走本 skill 的信号：用户说"需求/想做 X/新功能/痛点/用户故事/商业价值"
+✗ 不走的信号：用户说"实施/编码"（→ impl.md）或"技术方案"（→ design.md）或"typo"（→ quick.md）
+
+## 模板
+
+- [templates/L1-prd.md](../templates/L1-prd.md)
+- skill 内 Read 该文件获取完整模板
+
+## 流程
+
+### L1 Spec 创建
+
+1. **Q4 历史决策查询**（必做）：
+   ```bash
+   spec-manager decision list --topic <topic>
+   ```
+   若返回非空 → 向用户展示决策摘要,让用户确认新 L1 是否与历史一致或有意覆盖。
+   > ☑ **R18** — 流程规则:新 L1 创建前查历史决策,避免与已实现 L1 的决策冲突
+2. **PRE-WRITE Q1-Q3**（必做）：用当前工具的用户提问能力一次性问 3 个问题
+   - Q1 核心痛点（量化）
+   - Q2 范围边界（做/不做/推迟）
+   - Q3 成功指标（基线 + 目标 + 测量方式）
+3. **L1 去重搜索**（R16）：
+   ```bash
+   spec-manager spec list --level L1 --topic <topic>
+   ```
+   若发现同 topic L1 存在,**复用**而非新建。
+   > ☑ **R16** — 流程规则:查重确认无重复 L1
+4. **创建 L1**：
+   ```bash
+   spec-manager spec new L1 --topic <topic> --title "..."  # --code 不传则自动生成 <YYYY-MM-DD>-<shortId>
+   ```
+5. **写正文**：把 L1-prd.md 模板填好后写到文件
+   ```bash
+   spec-manager spec update <code> --content ./draft.md --ai-summary "..." --change-summary "初始 L1"
+   ```
+   `spec update` 自动跑必填段校验（warning-only）。
+   > ☑ **R13** / **R21** — `--ai-summary` ≤300 字符（CLI 截断,>300 自动 warn）
+   > ☑ **R22** — 流程规则:创建后立即写正文,通知审核前自检 contentTemplate 非空（CLI 在 `confirm` 时强制校验）
+6. 🛑 **等用户审核**（R1）
+   > ☑ **R1** — 流程规则:停下等用户审核,不自行推进
+7. 用户批准 → 调本 skill（不要凭上下文）：
+   ```bash
+   spec-manager spec confirm <code>
+   ```
+   > ☑ **R2** — 流程规则:状态变更由用户触发
+   > ☑ **R4** — 流程规则:L1 审核独立,不连带假设 L2
+
+## 与主 SKILL.md 关系
+
+L1 confirmed 后,路由到 `subskills/design.md` 继续 L2。
+
+## 适用规则
+
+R1 / R2 / R4 / R7 / R13 / R14 / R16 / R17 / R19 / R22 / R23
+
+## 相关规则（按需加载）
+
+| 规则 ID | 文件 | 适用场景 | 类型 |
+|---|---|---|---|
+| R1/R2/R4 | [rules/flow-control.md](../rules/flow-control.md) | 停下审核 / 状态归用户 / 每层独立 | 流程 |
+| R7 | [rules/doc-governance.md](../rules/doc-governance.md) | 层级绑定（虽 L1 无父,但确认子层要绑） | 代码 |
+| R13/R21 | [rules/doc-governance.md](../rules/doc-governance.md) | aiSummary 必传 + ≤300 字符 | 代码 |
+| R14 | [rules/doc-governance.md](../rules/doc-governance.md) | 跨层引用 — L1 不复述上层 | 流程 |
+| R16 | [rules/doc-governance.md](../rules/doc-governance.md) | L1 去重搜索 | 流程 |
+| R19 | [rules/doc-governance.md](../rules/doc-governance.md) | 研究期读 aiSummary 而非全文 | 流程 |
+| R22 | [rules/doc-governance.md](../rules/doc-governance.md) | 创建后立即写正文 | 代码（CLI 在 `confirm` 时强制） |
+| R23 | [rules/codebase-survey.md](../rules/codebase-survey.md) | 写 L1 前 Level 1 架构概览 | 流程 |

package/skill/subskills/quick.md

@@ -0,0 +1,25 @@
+# Sub-skill: Quick (≤5 步微调)
+
+## 路由自检
+
+✓ 走本 skill 的信号：用户说"修 typo / 改一行注释 / 调一个字符串 / 改 log level"
+✗ 不走的信号：用户说"新功能"（→ prd.md）或"重构"（→ design.md + impl.md）
+
+## 流程
+
+1. **直接 Edit 源码**：用 `Read` 找到目标行，`Edit` 改一行
+2. **验证**（如有）：`Bash` 跑相关测试
+3. **报告**：告诉用户改了哪个文件的哪一行
+4. **无需建任何 spec** — quick 不走完整 L1→L2→L3 流程
+
+## 限制
+
+- 步数 ≤ 5
+- 单一文件
+- 不涉及 schema 变更
+- 不涉及 API 契约变更
+- 不跨模块
+
+超限则跳到 `prd.md` 走完整流程。
+
+`git diff` 本身就是审计追踪。