spec-grill — 规格驱动 + 深度拷问的全端对话式开发流

> 本 Skill 内部调用 OpenSpec CLI，严格遵循 Init → Grill → Propose → Apply → Archive 流程。
> 核心增强：在 Propose 之前强制插入 Grill 阶段——4 阶段结构化面试，沿决策树逐条下行，把每个决策分支问透，澄清结论直接成为 proposal/design 的种子。
> 端自适应：前端、后端、小程序、全栈通用。Grill 阶段 1 确认目标端与技术栈后，各阶段按当前端的约定执行（产物形态、工程规范、接口契约生成方式随端切换，见各 reference）。
> 用户不需要记忆或输入任何 openspec 命令——只需像和同事聊需求一样说话，AI 会在后台执行对应命令并维护产物。

标准流程 vs OpenSpec CLI 命令映射

> 说明：OpenSpec 资料中的 openspec explore / openspec propose 等说法对应 CodeBuddy 的 /opsx: 命令。本 Skill 始终基于 OpenSpec CLI 内核驱动，运行时探测实际可用命令，保证跨工具、跨版本通用。Grill 阶段对应原 OpenSpec 的 Explore，但用 grill-me 方法论强化为强制结构化面试。

何时激活（触发条件）

满足以下任一即激活本 Skill（本 Skill 是处理「业务需求」的默认入口，无论是分析还是实现、做的是哪一端）：

1. 需求实现类：「实现需求 / 帮我实现需求 / 开发需求 / 做一个需求 / 按流程开发 / 走流程」。
2. 需求分析/澄清类（易漏，重点补充）：「看看这个需求 / 分析这个需求 / 需求拆解 / 需求分析 / 梳理这个需求 / 需求评审 / 这个需求怎么落地 / 帮我理解这个需求」。这类请求进入 Grill 阶段——只澄清、只总结要点，不写代码、不生成产物。
3. 深度拷问类（grill-me 血脉）：「grill me / 拷问我 / 压力测试方案 / 设计评审 / 帮我 stress-test 这个设计 / 把方案问透 / 把决策问清楚」。这类请求正是 Grill 阶段的核心入口。
4. 链接+意图类：用户粘贴 TAPD 需求链接（tapd.cn/.../story/... 或 tapd_fe/.../story/detail/...）或 墨刀/摹客/Figma/Axure 原型链接，并表达看/分析/实现/拆解等意图。
5. 缺陷修复类（独立分支）：「TAPD 缺陷修复 / 修复 bug / tapd bugfix / 需求关联缺陷 / 批量修 bug」→ 直接走 references/tapd-bugfix.md，不进入主流程。
6. 活文档类（可选替代分支）：「开发计划活文档 / dev_spec / 需求开发计划 / 原型转活文档」→ 走 references/living-doc.md（默认与 OpenSpec 二选一，见该文件第九章关联模式）。
7. 接口契约类：「根据 Swagger / open.json 生成接口定义 / 接口文档转代码 / openapi 生成类型或 Controller」→ 走 references/api-contract.md（主流程内则作为 Apply 阶段的接口任务协议）。
8. 命令/方法论类：用户提到「openspec / spec-driven / 规格驱动 / 走流程 / grill / explore / propose / apply / archive」。
9. 习惯类：「不要敲 openspec 命令 / 用聊天方式 / 直接帮我做 / 先把我问透再动手」。

强约束：只要用户围绕一个业务需求提出请求（无论是「看看/分析」还是「实现/开发」），就必须激活本 Skill 并进入对应阶段；绝不允许脱离 OpenSpec 直接写代码，也绝不允许跳过 Grill 直接生成 Propose 产物（即使只是「看看需求」，也应先走 Grill 的澄清与要点总结，而不是闷头读一通代码或直接写 proposal）。

核心原则

• 真 OpenSpec：proposal / specs(增量) / design / tasks 四类产物，全部由 openspec instructions 输出的 schema 规则驱动生成；校验用 openspec validate；归档用 openspec archive。
• Grill 不可跳过：Propose 之前必须走完 Grill 的 4 阶段面试（目标对齐 → 架构决策 → 边界与风险 → 实现细节），除非用户显式说「跳过拷问/直接写规格」。Grill 的决策摘要是 proposal/design 的种子。
• 端自适应：Grill 阶段 1（目标对齐）必须确认目标端与技术栈（前端 Web/H5、小程序、后端服务、全栈等）。确认后：需求提取随输入源走 references/requirement-intake.md；接口契约生成走 references/api-contract.md 对应端章节；Apply 的代码规范以当前项目既有约定 + 当前端已装技能为准（如 Java 后端项目遵循 java-development-manual 技能），本 Skill 不内联任何单一端的工程规范。
• 输入源统一接入：TAPD 需求、Figma/墨刀/摹客/Axure 原型、.md 需求文档、Swagger 契约，统一经 references/requirement-intake.md 提取为结构化需求清单，喂给 Grill；取完信息必须回到主流程。
• 先探索再追问：Grill 每个问题前，先穷尽代码库和历史记忆；能从代码找到答案就直接告知发现，只有涉及意图、权衡、未实现部分的问题才问用户。
• 标准流程优先：阶段命名、产物意义、执行顺序以 OpenSpec 标准流程为准（Init → Grill → Propose → Apply → Archive），Grill 是 Explore 的强化版。
• 不重新发明格式：不要自己编造 spec.md/plan.md 之类的结构。严格按 openspec instructions --json 给出的 template + instruction + rules 写文件。
• 用户零命令：用户只聊天；所有 openspec ... 都由 AI 在 Bash 中执行。
• 面向 schema，不硬编码：构建顺序、产物名称、路径一律从 openspec status --json 读取，支持非默认 workflow。

铁律（防作弊，违反即视为流程失败）

> 以下规则是硬约束。任何一条被违反，本次执行都算"没走完 spec-grill 流程"。

1. 任务勾选必须对应真实代码：tasks.md 里的 - [x] 只有在对应代码已真正写入/修改并落盘后才允许打勾。严禁：未写任何代码就勾选、一次性把全部任务预先勾完、或把"规划/探索/读代码"当成"实现完成"。若本次会话无法把实现做完，保持未勾选，并明确告知用户「规划已完成，实现待续」——绝不允许把未实现的任务标记为已完成。
2. 流程对用户可见、关键节点须确认：每生成一个产物，用几句话向用户展示要点；Grill 决策摘要、proposal 写完后、tasks 写完后分别取得用户确认再继续。不要让流程在"后台静默"跑完。
3. 流程必须跑到归档或用户主动叫停：apply → validate → archive 是必需环节。写出规划产物 不等于 完成需求；严禁在未真正写代码、未校验、未归档时声称"已完成/干完了"。
4. 禁止大规模前置探索：不要为"理解项目"去启动大型 code-explorer 子代理或海量 grep。Grill 阶段只读少量关键文件/问澄清问题；真正的代码阅读放在 Apply 阶段按任务进行。探索永远不能替代产物生成，也不能排在向用户展示规划产物之前。
5. Grill 不可跳过（本 Skill 独有）：Propose 前必须完成 Grill 4 阶段或取得用户「跳过拷问」的明确同意。跳过 Grill 直接写 proposal 视为流程失败。
6. 用 TaskCreate 跟踪 6 个文档阶段（Init → Grill → Propose → Apply → Archive + Grill 内部 4 子阶段决策树），让"跳过"在过程里就暴露。
7. 敏感操作先确认：git 提交/推送、删除文件、整文件覆盖、批量替换、TAPD 写操作（发评论/改状态）、安装/构建/部署等有副作用命令，执行前必须向用户说明「要做什么、影响哪些文件/对象、是否可逆」并取得确认。

Phase 0 — Init（初始化与命令探测）

本步骤保证：无论运行环境是否已装 OpenSpec、装的是哪个版本，本 Skill 都能进入流程；装不上才停下来问用户。

# 1) 确认 CLI 可用；缺失则自动安装（用户无需手动操作）
if ! command -v openspec >/dev/null 2>&1; then
  echo "OpenSpec CLI 未安装，正在通过 npm 自动安装..."
  npm install -g @fission-ai/openspec@latest
fi

# 2) 再次确认；仍不可用 → 明确告知并停止，绝不退化为自行模仿或直接写代码
if ! command -v openspec >/dev/null 2>&1; then
  echo "无法自动安装 OpenSpec CLI（可能无网络或 npm 不可用）。" \
       "请手动执行：npm install -g @fission-ai/openspec@latest 后再试。" >&2
  # 此处停止本流程，不要跳过流程直接写代码
else
  openspec --version
fi

# 3) 确认当前项目已初始化 OpenSpec；缺失则在【项目根目录】初始化
test -f openspec/config.yaml || openspec init --tools none --force

0.1 命令能力探测（跨版本 / 跨工具兼容）

# 直接探测各「语义动作」对应的命令是否真实可用（不要只靠顶层 --help 的文本匹配）
openspec new change --help >/dev/null 2>&1 && HAS_NEW_CHANGE=yes || HAS_NEW_CHANGE=no
openspec propose --help    >/dev/null 2>&1 && HAS_PROPOSE=yes    || HAS_PROPOSE=no
openspec instructions --help >/dev/null 2>&1 && HAS_INSTRUCTIONS=yes || HAS_INSTRUCTIONS=no
echo "new_change=$HAS_NEW_CHANGE propose=$HAS_PROPOSE instructions=$HAS_INSTRUCTIONS"

按探测结果选择命令（优先命令不可用才回退）：

> 若探测发现 openspec new change 与 openspec instructions 均不可用，但存在 openspec propose 等旧版命令，则按 references/command-compat.md 的兼容矩阵调整；若所有关键命令都缺失，停止并提示运行环境 OpenSpec 安装异常。

• 初始化后生成的 openspec/config.yaml 是 AI 的「入职培训手册」。在每次需求开始时必须读取它（技术栈与端信息通常在这里，见 references/config-context.md）。
• 若项目已有 openspec/ 但结构旧，可用 openspec init --force 升级。

Phase 1 — Grill（深度拷问 / 结构化面试）

> 对应原 OpenSpec 的 explore 阶段，但用 grill-me 方法论强化为强制 4 阶段结构化面试。
> 本阶段只思考、只读、只问，不写代码，不生成 OpenSpec 产物。
> 「帮我看看这个需求」「分析一下这个需求」「grill me」「拷问我」等请求，正是进入本阶段的正确入口。

1.0 预热（自动，无需用户参与）

在追问开始前，并行执行以下探索：

并行探索清单：
├─ Agent(subagent_type="Explore") → 全面扫描相关模块和代码上下文
├─ Grep/Glob                     → 特定模式、文件结构
├─ Read                          → 关键文件的具体实现
└─ conversation_search            → 过往决策、项目经验（本地记忆）

判断规则：
- 能从代码或历史记忆中找到答案 → 直接告知发现，跳过该问题
- 只有涉及意图、权衡、未实现部分的问题才问用户

同时读取项目上下文与需求输入：
- 读 openspec/config.yaml。
- 若项目有 docs/PROJECT_SPECIFICATION.md、docs/PROJECT_BUSINESS.md，按需读取。
- 输入源接入（端无关）：用户输入含 TAPD 需求链接 / Figma、墨刀、摹客、Axure 原型链接 / .md 需求文档 / Swagger 契约时，先 Read references/requirement-intake.md 按对应章节提取结构化需求清单（TAPD 连通性探针、workspace_id 提取、原型获取、.md 解析映射、严禁猜测协议均在其中）。
- 协作边界：TAPD/原型/文档接入只负责「取需求信息」，取完必须回到本流程，不准取完信息就直接写代码。缺陷修复意图转 references/tapd-bugfix.md 独立分支。

用 TaskCreate 初始化决策树顶层：

TaskCreate(subject="Grill-阶段1: 目标对齐（含端/技术栈确认）")
TaskCreate(subject="Grill-阶段2: 架构决策")
TaskCreate(subject="Grill-阶段3: 边界与风险")
TaskCreate(subject="Grill-阶段4: 实现细节")

如果发现历史决策与当前讨论冲突，主动提醒用户。

1.1 交互式提问格式

每次用 AskUserQuestion 工具发起提问，利用原生交互式 UI。

格式规则：
- header：阶段名（12 字以内），如 "目标对齐"、"架构决策"
- options：2-4 个选项，每个含 label 和 description
- 推荐选项 label 加 (Recommended) 标记，description 中说明理由
- 一次只问一个问题，等用户回答后再继续
- 选项描述控制在 1-2 句，聚焦影响和权衡

示例工具调用：

{
  "questions": [{
    "question": "存储方案选什么？",
    "header": "架构决策",
    "options": [
      {"label": "PostgreSQL (Recommended)", "description": "团队最熟悉，生态成熟，满足当前规模需求"},
      {"label": "MongoDB", "description": "Schema 灵活，适合快速迭代但运维成本较高"},
      {"label": "SQLite + Litestream", "description": "零运维，适合单机部署但并发上限低"}
    ]
  }]
}

详细的 4 阶段问题库、决策树模式、Mermaid 模板见 references/grill-playbook.md。

1.2 四阶段面试流程

由粗到细，逐层深入。每个阶段至少 1 个问题，简单决策可合并。

阶段 1：目标对齐

确认方案要解决什么，不解决什么。
- 核心问题是什么？成功标准是什么？
- 目标端与技术栈是什么？（前端 Web/H5、小程序、后端服务、全栈；能从 openspec/config.yaml 或项目结构推断的直接告知确认，不问开放式问题）
- 有哪些硬性约束或不可妥协的点？
- 哪些是明确的 non-goal（不在范围内）？

阶段 2：架构决策

整体结构和关键选型。
- 技术选型（语言/框架/中间件）
- 模块划分与职责边界
- 数据流方向和集成方式
- 与现有系统的交互模式

必须生成 Mermaid 图来可视化讨论中的架构关系（仅用基础 graph 语法，不加 style/classDef/fill）：

graph TB
    A[模块A] --> B[模块B]
    B --> C{决策点}
    C -->|方案1| D[路径1]
    C -->|方案2| E[路径2]

阶段 3：边界与风险

异常情况和失败场景。
- 错误处理与降级策略
- 并发、竞态、超时场景
- 向后兼容性与迁移路径
- 安全性与权限边界

阶段 4：实现细节

落地层面的关键选择。
- 核心算法或数据结构
- API 设计与接口契约（输入含 Swagger 时，契约事实以 references/api-contract.md 的解析为准，不臆造）
- 配置管理与环境差异
- 测试策略（单元/集成/端到端）

1.3 决策树追踪

用 TaskCreate / TaskUpdate 实时追踪所有决策分支状态：

TaskCreate(subject="阶段1: 确认核心问题范围")
TaskCreate(subject="阶段2: 选定存储方案")
TaskCreate(subject="阶段2: 确定 API 协议")
TaskCreate(subject="阶段3: 并发控制策略")
TaskCreate(subject="阶段4: 错误重试次数")

TaskUpdate(taskId="1", status="completed")  ← 已解决
TaskUpdate(taskId="2", status="in_progress") ← 正在讨论
TaskUpdate(taskId="3", status="pending")     ← 待讨论

规则：
- 阶段 0 初始化时创建顶层决策项
- 每个决策解决后立即 TaskUpdate(status="completed")
- 用户可随时通过 TaskList 看到哪些已决定、哪些待讨论

1.4 追问策略

• 深度优先：沿最关键的分支深挖到底，再回溯到下一个分支
• 依赖优先：先解决其他决策依赖的前置问题
• 分歧优先：用户有疑虑或提出新想法时，优先展开讨论
• 如果某阶段的代码库中已有明确实现，跳过该阶段并告知用户

1.5 终止条件

满足以下任一条件时停止 Grill：

1. 全部解决 — 四个阶段的决策 Task 都已标记 completed
2. 用户终止 — 用户明确表示"够了/可以了/停止/跳过拷问/直接写规格"
3. 无实质分歧 — 连续 3 个问题用户都选择推荐选项且无补充

1.6 Grill 终止后必做动作

1. 输出决策摘要（喂给 Propose）

## Grill 决策摘要

### 目标
[一句话描述方案目标]  → 直接成为 proposal.md 的 Why

### 端与技术栈
[Grill 阶段 1 确认的目标端与技术栈]  → 约束 Apply 的工程规范与 api-contract 产出形态

### 架构总览
[Mermaid 图 — 最终确认的架构/流程图]  → 直接成为 design.md 的 Context

### 关键决策
- [决策1]: [选定方案] — [理由]  → 直接成为 design.md 的 Decisions
- [决策2]: [选定方案] — [理由]

### Capabilities 拆分
- [capability1]: [职责]  → 直接成为 proposal.md 的 Capabilities + specs 文件
- [capability2]: [职责]

### 遗留风险
- [风险1]: [缓解措施或待定原因]  → 直接成为 design.md 的 Risks

### 任务拆分预览
1. [任务组1]  → 直接成为 tasks.md 的分组
2. [任务组2]

展示决策摘要并取得用户确认（用 AskUserQuestion 或等待用户回复），确认后才进入 Propose。

2. 持久化决策记忆

把关键决策写入项目级长期记忆（{项目根}/.workbuddy/memory/MEMORY.md），内容包括：
- 方案标题、目标端和核心决策
- 关键选型理由
- 遗留风险和约束

这样下次讨论相关方案时，可以直接引用，避免重复决策。

Phase 2 — Propose（提案 / 生成规划产物）

> 对应标准流程的 propose 阶段。本阶段真实执行：openspec new change + 循环 openspec instructions 生成 proposal / specs / design / tasks。
> 关键：Grill 决策摘要是产物的种子——proposal 的 Why/Capabilities 来自摘要，design 的 Decisions/Risks 来自摘要，tasks 的分组来自摘要的任务拆分预览。

2.1 创建 change

1. 从 Grill 决策摘要推导一个 kebab-case 变更名（如「考试支持AI批阅」→ exam-ai-grading）。
2. 在项目根目录创建 change：
   bash openspec new change "<change-name>"

2.2 生成产物

用 status 决定构建顺序，逐个产物调用 instructions：

# 取构建图：artifacts[] 状态、applyRequires、artifactPaths、changeRoot、planningHome
openspec status --change "<change-name>" --json

循环直到 applyRequires 中的产物全部 done：

1. 取第一个 status: "ready" 的产物 id。
2. 取该产物的权威指引：
   bash openspec instructions <artifact-id> --change "<change-name>" --json
   解析 JSON 关键字段：
   - template：输出文件的结构骨架（照此填充）
   - instruction：该产物类型的写法说明（务必遵守）
   - resolvedOutputPath：写入路径（glob 产物如 specs/**/*.md 需按 instruction 选具体路径 specs/<capability>/spec.md）
   - dependencies：需先读取的已完成产物（提供上下文）
   - context / rules：约束你的写作，禁止原样抄进产物文件
3. 读取依赖产物 + Grill 决策摘要 → 按 template + instruction 写文件到 resolvedOutputPath。
4. 写后确认文件已落盘，再进入下一个产物。
5. 每写完一个产物，向用户展示要点并简要说明。特别在 proposal 与 tasks 写完后，分别取得用户确认再继续。
6. 重新 openspec status --change "<name>" --json，直到 applyRequires 全 done。

> 各产物要点（spec-driven）：
> - proposal.md：Why（来自 Grill 目标）/ What Changes / Capabilities（来自 Grill 拆分）/ Impact。
> - specs/\<capability\>/spec.md：增量 spec，用 ## ADDED/MODIFIED/REMOVED/RENAMED Requirements；每个 Requirement 至少 1 个 #### Scenario:（WHEN/THEN）。场景必须用 4 个 #。
> - design.md：Context（来自 Grill 架构图）/ Goals-Non-Goals / Decisions（来自 Grill 关键决策）/ Risks（来自 Grill 遗留风险）。仅当跨模块、引入新依赖/数据模型、有安全/性能/迁移复杂度或存在歧义时才创建——但 Grill 阶段 2/3 有产出时通常需要 design。
> - tasks.md：用 - [ ] X.Y 描述 复选框分组（分组来自 Grill 任务拆分预览），apply 阶段靠它追踪进度。

Phase 3 — Apply（实施 / 逐任务实现）

> 对应标准流程的 apply 阶段。本阶段真实执行：openspec instructions apply --json，然后 AI 按 tasks.md 真实改代码。

openspec instructions apply --change "<change-name>" --json

• 解析：state(blocked/all_done/ready)、contextFiles（proposal/specs/design/tasks 路径）、progress、tasks。
• 若 state: "blocked"（产物不全）→ 回到 Phase 2 继续生成。
• 若 state: "all_done" → 跳到 Phase 4 校验。
• 否则按 tasks.md 顺序真实实现：
• 读取 contextFiles 全部文件 → 每个任务先写出/修改对应的真实代码文件，确认文件已变更落盘后，才把该任务的 - [ ] 改为 - [x]。
• 绝不允许预先把所有任务勾成 [x]，也不允许"读了代码/探索完"就当作实现完成。
• 若本次会话无法把全部任务实现完，只勾已完成真实代码的任务，剩余保持 - [ ]，并明确告知用户「实现进行到 X/Y，剩余待续」，然后停止（不要擅自归档或声称完成）。
• 端自适应实现约定：按 Grill 确认的端执行——工程规范以项目既有约定与当前端已装技能为准（如 Java 后端遵循 java-development-manual；前端遵循项目前端规范）；接口契约类任务（Swagger→接口定义）按 references/api-contract.md 执行；安全硬约束（输入校验、敏感信息不硬编码、XSS/SQL 注入防护）任何端均须遵守。
• 暂停条件：任务不清 → 问用户；实现暴露设计问题 → 建议走 update 更新产物；报错/阻塞 → 报告并等指示。改动保持最小、限定在变更范围内。

Phase 4 — Archive（校验 + 归档）

> 对应标准流程的 archive 阶段。必须先 validate 通过，再与用户确认，最后 archive。

4.1 校验

openspec validate "<change-name>"      # 校验单个 change
# openspec validate --all             # 可选：校验全部 changes + specs

• 必须修复到无 ERROR（常见：缺 #### Scenario、specs 无 delta、Requirement 缺场景）。
• 代码完整性自检（铁律 1 的硬校验）：openspec validate 只校验产物结构，不校验代码。归档前必须额外确认：
• tasks.md 中每一个 [x] 都对应真实落盘的代码改动（可用 git status / git diff --stat 核对变更文件）。
• 若存在 [x] 却无对应代码改动，或仍有未实现的 - [ ] 任务，禁止归档，先回到 Phase 3 补齐或向用户说明。

4.2 归档

1. 先用 openspec status --change "<name>" 确认产物与任务完成度。
2. 归档前置闸门（铁律 1+3）：只有同时满足才允许归档——
   - openspec validate "<name>" 无 ERROR；
   - tasks.md 全部任务为 [x]，且每个 [x] 都有真实代码改动（git status 可核对）；
   - 与用户确认归档（归档会移动 change 目录，用 AskUserQuestion）。
   任一不满足（尤其"任务标完却没代码"）禁止归档，回到 Phase 3 补齐或向用户说明现状。
3. 确认后执行（增量 spec 会同步进 openspec/specs/）：
   bash openspec archive "<change-name>" -y
   （-y 跳过交互确认；若想先看同步摘要可去掉 -y。纯基础设施/文档变更可用 --skip-specs。）

独立分支与可选模式

以下能力不进入 Init → Grill → Propose → Apply → Archive 主流程，命中后 Read 对应 reference 按其内部阶段执行：

继续已有 change

openspec list --json        # 列出活跃 change，选最近的继续

• 继续规划：openspec status --json + openspec instructions <id> --json（同 Phase 2 循环）
• 继续实现：openspec instructions apply --json（同 Phase 3）
• 修订已写产物（不改代码）：读取后按 openspec instructions <id> --json 的规则改写，保持产物间一致
• 归档：同上 Phase 4

> 若用户中途回来继续一个 change，且 Grill 决策摘要已持久化到 memory，优先读取摘要恢复上下文，不必重新拷问。

命令速查（OpenSpec CLI）

完整参数见 references/command-cheatsheet.md。

护栏 / 熔断

• Grill 不可跳过（铁律 5）：Propose 前必须走完 Grill 4 阶段或取得用户「跳过拷问」的明确同意。
• 规划与实现分离：Grill / Propose 阶段绝不写实现代码；只有 Apply 阶段才改代码。
• 禁止大规模前置探索（铁律 4）：Grill 阶段只读少量关键文件/问澄清问题；真正的代码阅读放在 Apply 阶段按任务进行。
• 先探索再追问：Grill 每个问题前先穷尽代码库和历史记忆，能自查的不问用户。
• 任务勾选纪律（铁律 1）：- [x] 必须对应真实落盘代码；未写代码绝不勾选，做不完保持未勾选并如实告知。
• 流程可见与确认（铁律 2）：每个产物向用户展示要点；Grill 决策摘要、proposal、tasks 写完后分别确认。
• 跑到归档或叫停（铁律 3）：apply→validate→archive 缺一不可；未实现/未校验/未归档不得声称完成。
• 阶段不可跳过（铁律 6）：用 TaskCreate 跟踪 Init→Grill→Propose→Apply→Archive，缺失任一环节视为流程未完成。
• 敏感操作先确认（铁律 7）：TAPD 写操作、git 提交、删除/覆盖文件、安装/构建/部署等，说明影响并取得确认后执行。
• 先读上下文：每个 change 开始时读 openspec/config.yaml 与 openspec/specs/ 现有规范，再写产物。
• 限定范围：变更通过 change 名 + Capabilities 界定范围，不要改动无关文件/全局重构。
• 归档前必确认：openspec archive 会移动目录，且须通过 Phase 4 的归档前置闸门。
• 变更不漂移：实现中发现需求变化，先回到 Grill 重新澄清受影响决策，再更新对应产物，不让代码与计划静默脱节。
• 路径/产物名来自 status：永远从 openspec status --json 取 artifactPaths/artifacts，不要硬编码产物文件名。
• 该问就问：信息关键且含糊、或遇到阻塞/报错时暂停询问；非关键信息优先合理决策以保持节奏。
• 产物须落盘校验：每写一个产物文件，写后确认文件存在再进入下一步。
• 严禁猜测需求（来自 references/requirement-intake.md）：接口契约 / 业务规则 / 字段含义未知时停止询问，以 ⚠️ 待确认 标记，绝不臆造。

复杂度自适应

• 简单需求：仍走完整 5 阶段；Grill 可精简为每阶段 1 个问题（共 4 问），proposal/specs 可精简，design 视情况省略，tasks 可很短。但 apply 与 archive 仍执行。
• 复杂需求：完整 Grill 4 阶段深挖 + 完整 proposal + specs + design + tasks；可在 tasks 中标注测试任务（TDD 可选，但推荐对核心逻辑补测试）。
• 任何复杂度、任何端都不跳过 Grill，也不跳过 OpenSpec 流程——差别只在问题数量与产物详尽程度。

章节索引（懒加载指针）

命中对应分支/阶段时，先 Read 该文件再执行：

• Grill 方法论详解（4 阶段问题库 / 决策树 / Mermaid 模板）→ references/grill-playbook.md
• 需求输入统一接入（TAPD 需求 / Figma、墨刀、摹客、Axure 原型 / .md 文档 / Swagger 契约 → 结构化需求清单；严禁猜测协议）→ references/requirement-intake.md
• TAPD 缺陷修复（独立分支，端自适应）→ references/tapd-bugfix.md（工具参数见 references/tapd-tool-params.md；workspace_id 提取用 scripts/extract_workspace_id.py）
• 开发计划活文档（dev_spec，OpenSpec 可选替代 + 关联镜像模式）→ references/living-doc.md（同步脚本 scripts/sync-livingdoc-openspec.cjs）
• 接口契约生成（Swagger/OpenAPI → 前端 API 函数+类型 / 后端 Controller+DTO）→ references/api-contract.md
• config.yaml 填充指南（项目「入职培训手册」）→ references/config-context.md
• OpenSpec CLI 参数速查 → references/command-cheatsheet.md
• 跨版本/跨工具命令兼容矩阵 → references/command-compat.md
• 端到端示例 → examples/dark-mode-example.md