Back to Details

spec-coding

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Spec-Coding

Spec-Coding

You are executing the Spec-Coding workflow — a structured pre-development pipeline for large-scale, complex tasks.
Complete all preparation Phases before any implementation begins.
If a specific tool mentioned here is unavailable, use the closest equivalent available in your environment.
你正在执行Spec-Coding工作流——这是面向大规模复杂任务的结构化预开发流水线。
在开始任何实现工作前，请先完成所有准备阶段的内容。
如果这里提到的特定工具不可用，请使用你环境中最接近的等效工具替代。

Behavioral Rules

行为规则

  1. COMPASS.md is your memory. New conversation = read COMPASS.md first, non-negotiable.
  2. Never skip phases. Even for small projects, produce lightweight versions of each phase's outputs.
  3. Confirm at phase boundaries. Every phase transition is a checkpoint.
  4. Stop before you spiral. Two failures or one constraint conflict → Blocked Protocol. Immediately.
  5. Archive is not optional. When all Tasks are done, always archive. Do not leave stale artifacts.
  6. .spec/
    is always gitignored.     Verify at the start of every fresh session.
  7. No code before approval. No code, scaffolding, or pseudo-code until the user approves the plan at Phase 4.
  8. Give opinions directly. Take a position on architectural choices. State your recommendation and the evidence that would change it.
  9. No placeholders in approved plans. A plan with placeholders is not approvable.
  1. COMPASS.md 是你的记忆载体。 新会话启动必须首先读取COMPASS.md，没有商量余地。
  2. 绝不跳过阶段。 即使是小型项目，也要输出每个阶段产出物的轻量版本。
  3. 阶段边界需确认。 每一次阶段切换都是检查点。
  4. 陷入循环前及时停止。 两次失败或一次约束冲突 → 立即触发阻塞协议。
  5. 归档不是可选项。 所有任务完成后必须进行归档，不要留下过时的产物。
  6. .spec/
    始终要加入gitignore。     每次新会话启动时都要验证这一点。
  7. 审批通过前不要写代码。 在用户在第4阶段批准计划前，不要编写任何代码、脚手架或伪代码。
  8. 直接给出观点。 对架构选择要明确立场，说明你的推荐方案以及会让你改变方案的依据。
  9. 已批准的计划中不能有占位符。 包含占位符的计划不可审批通过。

Directory Structure

目录结构

All spec-coding artifacts live under 
.spec/
. This directory is never committed to version control.
.spec/
├── COMPASS.md                    # Main control file — always read this first
├── analysis/
│   ├── architecture.md
│   ├── module-map.md
│   └── risk-register.md
├── plan/
│   ├── task-breakdown.md         # Includes Mermaid dependency graph
│   └── milestones.md
├── progress/
│   └── task-N-<short-name>.md  	  # One file per Task
└── archived/
    └── YYYY-MM-DD-NN/            # Completed development cycles
Templates for all files above are in the skill directory at 
assets/templates/
.
所有spec-coding产物都存放在
.spec/
目录下，该目录永远不会提交到版本控制。
.spec/
├── COMPASS.md                    # 主控制文件 —— 始终优先读取
├── analysis/
│   ├── architecture.md
│   ├── module-map.md
│   └── risk-register.md
├── plan/
│   ├── task-breakdown.md         # 包含Mermaid依赖图
│   └── milestones.md
├── progress/
│   └── task-N-<short-name>.md  	  # 每个任务对应一个文件
└── archived/
    └── YYYY-MM-DD-NN/            # 已完成的开发周期
上述所有文件的模板都存放在skill目录的
assets/templates/
路径下。

Continuity Check

连续性检查

Before starting any phase, check whether 
.spec/COMPASS.md
exists.
  • Exists: Read it immediately. You are resuming a session. Identify the current phase or task, what was completed, and continue from exactly where the previous conversation ended. Do NOT restart from Phase 0.
  • Does not exist: Treat this as a fresh start. Verify 
    .spec/
    is in 
    .gitignore
    — add it if not. Then proceed to Phase 0.
After loading state from COMPASS.md, populate TaskCreate with the active phase's pending items.
开始任何阶段前，先检查
.spec/COMPASS.md
是否存在。
  • 存在：立即读取该文件，你正在恢复之前的会话。确认当前所处的阶段或任务、已完成的内容，从上次会话结束的地方继续推进，不要从第0阶段重新开始。
  • 不存在：视为全新启动的项目。验证
    .spec/
    是否已加入
    .gitignore
    ，如果没有就添加进去，然后进入第0阶段。
从COMPASS.md加载状态后，将当前阶段待处理项填充到TaskCreate中。

Phase 0: Intent Recognition & Confirmation

阶段0：意图识别与确认

Stage 0: Quick Scan

步骤0：快速扫描

This exists to help you orient and make your questions grounded.
  • Read 
    README.md
    , 
    CLAUDE.md
    , 
    AGENTS.md
    , etc.
  • Scan the top-level directory structure
  • Identify technology stack signals: 
    package.json
    , 
    Cargo.toml
    , 
    pyproject.toml
    , 
    go.mod
    , etc.
If the directory is empty or unfamiliar, note that — it means Stage 1 questions must be more open-ended.
该步骤帮助你明确方向，让你提出的问题更贴合实际。
  • 读取
    README.md
    、
    CLAUDE.md
    、
    AGENTS.md
    等文件
  • 扫描顶层目录结构
  • 识别技术栈信号：
    package.json
    、
    Cargo.toml
    、
    pyproject.toml
    、
    go.mod
    等
如果目录为空或你不熟悉，请记录该情况——这意味着步骤1的问题需要更开放。

Stage 1: Natural Conversation

步骤1：自然对话

Open with a short summary of what you already understand from Stage 0 and the user's initial message — project type, tech stack, your interpretation of the request. Then ask follow-up questions in plain conversational text.
Do not use 
AskUserQuestion
here. Keep to 1–2 questions at a time. Build shared context through dialogue, not forms.
Continue until you have a working understanding of scope, target state, and hard constraints.
首先简短总结你从步骤0和用户初始消息中了解到的内容：项目类型、技术栈、你对需求的理解。然后用平实的对话文本提出跟进问题。
此处不要使用
AskUserQuestion
，每次只提1-2个问题。通过对话建立共识上下文，而不是用表单的形式提问。
持续对话直到你对范围、目标状态和硬性约束有了可行的理解。

Stage 2: Targeted Confirmation

步骤2：定向确认

Once natural conversation has established sufficient context, use 
AskUserQuestion
to nail down remaining specific unknowns. One call per unresolved question — do not batch them.
Confirm at minimum: scope, hard constraints (backward compatibility, libraries, deployment targets), and priority (performance vs. maintainability vs. speed of delivery).
自然对话建立了足够的上下文后，使用
AskUserQuestion
确认剩余的具体未知项。每个未解决问题单独调用一次，不要批量提问。
至少要确认：范围、硬性约束（向后兼容性、依赖库、部署目标）、优先级（性能 vs 可维护性 vs 交付速度）。

Confirmation

确认环节

Summarize your complete understanding and get explicit user confirmation before proceeding.
Phase 0 output: Create 
.spec/COMPASS.md
from 
assets/templates/
. Fill in only:
  • Task Definition
  • Assumptions & Constraints
Leave all other sections as-is. Do not fill in what you do not yet know.
总结你对需求的完整理解，获得用户明确确认后再推进。
阶段0产出：基于
assets/templates/
模板创建
.spec/COMPASS.md
，仅填写以下内容：
  • 任务定义
  • 假设与约束
其他部分保持原样，不要填写你还不确定的内容。

Phase 1: Deep Project Analysis

阶段1：项目深度分析

Goal: Build a comprehensive, factual understanding of the current codebase. No opinions, no suggestions — only what exists.
目标：对当前代码库建立全面、 factual的理解。不要输出观点、不要提建议——仅记录已存在的内容。

Before You Begin

开始前准备

Create 
architecture.md
module-map.md
risk-register.md
from 
assets/templates/analysis
.
基于
assets/templates/analysis
下的模板创建
architecture.md
、
module-map.md
、
risk-register.md
。

Dispatch 
Explore

调度
Explore

Read 
references/subagents.md
— Explore section — for the prompt template. Adapt it for each subagent you dispatch.
If the project is small (roughly 20 files or fewer), a single Explore pass is sufficient.
Otherwise, split the work by architectural boundary, not by file count. One agent per logical area is more effective than one agent per directory. Examples:
  • Core domain logic + data models
  • Infrastructure layer (DB, external APIs, file I/O)
  • Entry points, routing, public API surface
Dispatch all agents in parallel. After 
Explore
subagents report findings back to you, write 
.spec/analysis/*
and consolidate all findings into the three output files.
读取
references/subagents.md
的Explore部分获取提示词模板，为你调度的每个子Agent适配模板。
如果是小型项目（大致20个文件以内），单次Explore扫描就足够了。
否则，按照架构边界拆分工作，不要按文件数量拆分。每个逻辑领域分配一个Agent比每个目录分配一个Agent效率更高，示例：
  • 核心领域逻辑 + 数据模型
  • 基础设施层（数据库、外部API、文件I/O）
  • 入口点、路由、公开API面
并行调度所有Agent。
Explore
子Agent返回结果后，编写
.spec/analysis/*
下的文件，将所有结果整合到三个输出文件中。

Output: 
.spec/analysis/

产出：
.spec/analysis/

Each file must be fully filled in before Phase 2 begins. Incomplete sections must be explicitly marked as "not found" — do not leave template placeholders.
  • architecture.md: tech stack, all entry points, build/run/test/lint commands, high-level architecture (2–5 paragraphs), patterns observed with file evidence, external integrations
  • module-map.md: every significant module with responsibility, public API, internal deps, external deps, size, complexity rating
  • risk-register.md: every risk that could affect the plan — complexity, coupling, missing tests, external constraints; hotspot summary (the 2–3 areas most likely to cause problems)
阶段2开始前必须填完所有文件的内容，不完整的部分必须明确标记为“未找到”——不要保留模板占位符。
  • architecture.md：技术栈、所有入口点、构建/运行/测试/ lint命令、高层架构（2-5段文字）、观察到的模式及对应文件证据、外部集成
  • module-map.md：每个重要模块的职责、公开API、内部依赖、外部依赖、规模、复杂度评级
  • risk-register.md：所有可能影响计划的风险——复杂度、耦合度、缺失的测试、外部约束；热点总结（最可能出问题的2-3个领域）

Phase Boundary

阶段边界

Phase 1 is complete when all three files are filled and contain no template placeholders. Proceed to Phase 2 immediately.
当三个文件全部填写完成且没有模板占位符时，阶段1完成，立即进入阶段2。

Phase 2: Analysis Review

阶段2：分析评审

Goal: Present findings, propose architectural options, test the recommendation, reach a confirmed direction.
目标：展示分析结果、提出架构选项、验证推荐方案、达成确定的开发方向。

Step 1: Present the Analysis

步骤1：展示分析结果

Summarize for the user — do not dump the full documents. Cover:
  1. Project overview: what this is, tech stack, approximate scale
  2. Key findings: important modules, dependencies, patterns relevant to the task
  3. Risk highlights: top 2–3 risks and why they matter
Keep to one focused message.
为用户总结内容——不要直接抛出完整文档。涵盖以下内容：
  1. 项目概览：项目是什么、技术栈、大致规模
  2. 关键发现：和任务相关的重要模块、依赖、模式
  3. 风险亮点：排名前2-3的风险及影响
保持内容聚焦、简洁。

Step 2: Propose Architectural Options

步骤2：提出架构选项

Propose 2–3 options. Always include one minimal option.
For each option:
FieldContent
SummaryOne sentence: what this approach does
EffortSmall/Medium/High
RiskWhat could go wrong
Builds onWhich existing code or patterns it leverages
State your recommendation explicitly. Do not hedge — pick one and say why.
提出2-3个选项，必须包含一个最小成本选项。
每个选项的说明如下：
字段内容
概要一句话说明该方案的内容
工作量小/中/大
风险可能出现的问题
基于该方案复用了哪些现有代码或模式
明确说明你的推荐方案，不要模棱两可——选择一个方案并说明理由。

Step 3: Adversarial Test the Recommendation

步骤3：对抗性测试推荐方案

Before presenting, attack your own recommendation internally:
  1. What would make this fail? Identify the single most likely failure mode.
  2. If the attack holds: Deform the design to survive it. Present the deformed version, noting what changed and why.
  3. If the attack shatters the approach entirely: Discard it, tell the user why, promote the second-best option and repeat.
Present the hardened recommendation — not your original unexamined first choice.
在展示方案前，先在内部对你的推荐方案发起挑战：
  1. 什么情况会导致该方案失败？ 找出最可能出现的单一失败模式。
  2. 如果挑战成立：调整设计以解决该问题，展示调整后的版本，说明修改内容和原因。
  3. 如果挑战完全推翻了该方案：废弃该方案，向用户说明原因，推荐次优方案并重复上述测试流程。
展示经过验证的加固方案——而不是你最初未经过检验的第一选择。

Step 4: User Confirmation

步骤4：用户确认

Ask the user to confirm the direction. Do not proceed to Phase 3 until they do.
If the user pushes back: minor adjustments inline and confirm again; different option preferred — re-run adversarial test on that option; new option not yet proposed — explore, assess, test, present.
请用户确认开发方向，用户确认前不要进入阶段3。
如果用户提出异议：小调整可以直接修改后再次确认；用户偏好其他选项——对该选项重新进行对抗性测试；用户提出了未涉及的新选项——调研、评估、测试后再展示。

Phase Boundary

阶段边界

Phase 2 is complete when the user confirms an architectural direction.
Update COMPASS.md: fill in Architecture direction confirmed (one sentence: which option and why) and add links to all three analysis documents.
Proceed to Phase 3.
当用户确认了架构方向后，阶段2完成。
更新COMPASS.md：填写已确认的架构方向（一句话说明选择的方案及理由），添加三个分析文档的链接。
进入阶段3。

Phase 3: Task Decomposition

阶段3：任务拆解

Goal: Break the confirmed approach into concrete, trackable Tasks with no placeholders and clear acceptance criteria.
目标：将确认的方案拆分为具体、可跟踪的任务，没有占位符，有明确的验收标准。

Before You Begin

开始前准备

Confirm 
COMPASS.md
has a confirmed architecture direction — if not, Phase 2 was not completed.
Create 
task-breakdown.md
milestones.md
from 
assets/templates/plan
.
确认
COMPASS.md
中已有确认的架构方向——如果没有，说明阶段2未完成。
基于
assets/templates/plan
下的模板创建
task-breakdown.md
、
milestones.md
。

Dispatch 
Plan

调度
Plan

Read 
references/subagents.md
— Plan section — for the prompt template. Fill in:
  • The task definition from 
    COMPASS.md
  • The confirmed architecture direction from 
    COMPASS.md
  • The full Assumptions & Constraints from 
    COMPASS.md
Dispatch Plan after the template is filled.
读取
references/subagents.md
的Plan部分获取提示词模板，填写以下内容：
  • COMPASS.md
    中的任务定义
  • COMPASS.md
    中已确认的架构方向
  • COMPASS.md
    中的全部假设与约束
模板填写完成后调度Plan。

Placeholder Enforcement

占位符校验

When Plan returns, scan both output files for forbidden patterns before accepting the output:
Forbidden: TBD, TODO, "implement later", "similar to Task N", "details to be determined", "to be specified", blank acceptance criteria fields, blank effort fields.
If any found: send Plan back with a list of every occurrence and the instruction to resolve each one. Do not proceed to Phase 4 with an incomplete plan.
Plan返回结果后，先扫描两个输出文件是否存在禁用模式，再接受输出：
禁用内容：TBD、TODO、“后续实现”、“类似任务N”、“待确定细节”、“待指定”、空的验收标准字段、空的工作量字段。
如果发现上述内容：将所有问题点列表返回给Plan，要求逐个解决。不要带着不完整的计划进入阶段4。

Output: 
.spec/plan/

产出：
.spec/plan/

  • task-breakdown.md: every Task with description, priority (P1/P2/P3), effort (Small/Medium/High), dependencies, subtasks, acceptance criteria; Mermaid dependency graph; Tasks ordered by dependency.
  • milestones.md: 3–5 milestones, each an end-to-end working state or retired risk, with explicit demonstrable target criteria.
  • task-breakdown.md：每个任务的描述、优先级（P1/P2/P3）、工作量（小/中/大）、依赖项、子任务、验收标准；Mermaid依赖图；按依赖顺序排列的任务列表
  • milestones.md：3-5个里程碑，每个都是端到端可用状态或已解决的风险，有明确可验证的目标标准

Phase Boundary

阶段边界

Phase 3 is complete when both plan files are filled and contain no forbidden patterns. Proceed to Phase 4 immediately.
当两个计划文件全部填写完成且没有禁用模式时，阶段3完成，立即进入阶段4。

Phase 4: Plan Review & Approval

阶段4：计划评审与审批

Goal: Get explicit user approval before any implementation begins. No code, scaffolding, or pseudo-code until the user approves.
目标：在开始任何实现工作前获得用户明确批准。用户批准前不要编写任何代码、脚手架或伪代码。

Step 1: Present the Plan

步骤1：展示计划

Present a readable summary — do not paste the raw files. Cover:
  1. Task overview: all Tasks with names, priorities, effort estimates, and dependencies (a table works well)
  2. Milestone overview: all milestones and their target criteria
  3. Total scope: rough overall effort, number of Tasks
  4. Key risks addressed: tie back to the risk register — how does the plan handle the top risks?
展示可读性强的总结——不要直接粘贴原始文件内容。涵盖以下内容：
  1. 任务概览：所有任务的名称、优先级、工作量预估、依赖关系（用表格展示效果更好）
  2. 里程碑概览：所有里程碑及对应的目标标准
  3. 总范围：大致的总工作量、任务数量
  4. 已解决的关键风险：关联风险登记册，说明计划如何应对最高优先级的风险

Step 2: Invite Scrutiny

步骤2：邀请用户审核

Explicitly ask the user to check:
  • Are all the right things included?
  • Is anything scoped too broadly or too narrowly?
  • Do the priorities look right?
  • Are the acceptance criteria strong enough?
明确请用户检查以下内容：
  • 是否包含了所有需要的内容？
  • 有没有范围定得太宽或太窄的内容？
  • 优先级是否合理？
  • 验收标准是否足够明确？

Step 3: Handle Feedback

步骤3：处理反馈

Diagnose the root cause before acting:
Feedback typeRoot causeAction
Task description unclear, wrong granularity, missing functionalityPlan output incompleteReturn to Phase 3: re-dispatch Plan with corrected instructions
Analysis missed a module, factual gapPhase 1 analysis wrongReturn to Phase 1: targeted Explore, update analysis file, re-run Phase 3
Architecture direction wrongPhase 2 decision wrongReturn to Phase 2: re-present options, new confirmation, re-run Phase 3
Scope or constraints changedPhase 0 assumptions outdatedUpdate COMPASS.md, return to Phase 2 or 3 as appropriate
Minor wording fix, small reprioritizationSurface fix onlyEdit plan file directly, no phase return needed
State the diagnosis to the user before acting. Confirm with the user before returning to a prior phase.
采取行动前先诊断根本原因：
反馈类型根本原因处理方式
任务描述不清晰、粒度不合理、缺失功能计划输出不完整回到阶段3：带着修正指令重新调度Plan
分析遗漏了某个模块、存在事实错误阶段1分析错误回到阶段1：定向Explore，更新分析文件，重新执行阶段3
架构方向错误阶段2决策错误回到阶段2：重新展示选项、获得新的确认，重新执行阶段3
范围或约束发生变化阶段0的假设已经过时更新COMPASS.md，根据情况回到阶段2或3
minor的文字修正、小的优先级调整仅需表层修改直接编辑计划文件，不需要回到之前的阶段
采取行动前先向用户说明诊断结果，回到之前的阶段前需要获得用户确认。

Phase Boundary

阶段边界

Phase 4 is complete when the user explicitly approves the plan (e.g., "looks good", "approved", "proceed").
Update 
COMPASS.md
: add links to both plan documents, fill in the Task Overview table (all Tasks, initial 
[ ]
), fill in the Milestones table (all milestones, initial 
[ ]
).
Proceed to Phase 5.
当用户明确批准计划后（例如“看起来不错”、“批准”、“继续”），阶段4完成。
更新
COMPASS.md
：添加两个计划文档的链接，填写任务概览表格（所有任务，初始状态为
[ ]
），填写里程碑表格（所有里程碑，初始状态为
[ ]
）。
进入阶段5。

Phase 5: Progress Tracking Setup

阶段5：进度跟踪配置

Goal: Create per-Task progress files and complete COMPASS.md so a fresh agent can orient in under 30 seconds.
目标：创建每个任务对应的进度文件，补全COMPASS.md，让新的Agent可以在30秒内明确当前状态。

Step 1: Create Progress Files

步骤1：创建进度文件

For each Task in 
task-breakdown.md
, create 
task-N-<short-name>.md
from 
assets/templates/progress/task.md
.
For each file:
  • Copy the subtasks and acceptance criteria from 
    task-breakdown.md
  • Set Current to the first subtask of that Task (e.g., 
    1.1
    ); leave other tasks' Current blank until active
  • Leave the Notes section empty
Naming example: Task 3 "Refactor authentication layer" → 
task-3-refactor-auth.md
对于
task-breakdown.md
中的每个任务，基于
assets/templates/progress/task.md
模板创建
task-N-<short-name>.md
。
每个文件的填写规则：
  • 从
    task-breakdown.md
    中复制子任务和验收标准
  • 将Current设置为该任务的第一个子任务（例如
    1.1
    ）；其他任务的Current留空，直到任务被激活
  • 备注部分留空
命名示例：任务3“重构认证层” → 
task-3-refactor-auth.md

Step 2: Complete COMPASS.md

步骤2：补全COMPASS.md

Fill in the two remaining sections:
Current Status: "Phase 5 complete. Ready to begin Task 1: 
<name>
."
Next Steps:
  • Read 
    .spec/plan/task-breakdown.md
    to understand the full scope
  • Open 
    .spec/progress/task-1-<name>.md
    and begin the first subtask
  • Re-read Assumptions & Constraints before touching any code
填写剩余的两个部分：
当前状态：“阶段5完成。准备开始任务1：
<name>
。”
下一步：
  • 读取
    .spec/plan/task-breakdown.md
    了解完整范围
  • 打开
    .spec/progress/task-1-<name>.md
    开始第一个子任务
  • 编写代码前重新阅读假设与约束

Phase Boundary

阶段边界

Phase 5 is complete when progress files exist and 
COMPASS.md
's Current Status and Next Steps are filled. Proceed to Phase 6.
当所有进度文件已创建，且
COMPASS.md
的当前状态和下一步已填写完成时，阶段5完成。进入阶段6。

Phase 6: Sub-skill Generation

阶段6：子技能生成

Goal: Generate a project-scoped sub-skill that encodes this project's implementation standards and continuity protocol.
Install at project scope only: 
./.claude/skills/
.
Name it 
spec-coding-<project-name>
. It is removed when the Archive Phase runs.
Delegate creation to 
skill-creator
. Provide it the task context from 
COMPASS.md
, the sub-skill name, and the content outline below.
If 
skill-creator
is not installed: Tell the user it is required and instruct them to install it with 
npx skills add anthropics/skills --skill skill-creator
. Do not install it on their behalf. Once installed, return to this phase.
目标：生成项目范围的子技能，内置该项目的实现规范和连续性协议。
仅安装到项目范围：
./.claude/skills/
。
命名为
spec-coding-<project-name>
，归档阶段运行时会自动删除该子技能。
将创建工作委托给
skill-creator
，向其提供
COMPASS.md
中的任务上下文、子技能名称和下方的内容大纲。
如果未安装
skill-creator
：告知用户需要安装该工具，指导用户执行
npx skills add anthropics/skills --skill skill-creator
安装，不要替用户安装。安装完成后回到该阶段。

Required Sub-skill Content

子技能必填内容

The generated sub-skill must instruct the agent to do the following.
Session Startup (every conversation, non-negotiable):
  1. Read 
    .spec/COMPASS.md
    first — before any other file, before any action
  2. Identify the active Task from the Task Overview table
  3. Open that Task's progress file in 
    .spec/progress/
  4. Populate 
    TaskCreate
    with all unchecked subtasks.
  5. Re-read Assumptions & Constraints before touching any code
During Implementation:
  • Before each implementation decision, check it against Assumptions & Constraints — if it conflicts, stop and invoke the Blocked Protocol.
  • After completing a subtask: check its box 
    [x]
    in the progress file, update Current to the next subtask, use 
    TaskUpdate
    to mark the item as completed.
  • Record decisions, surprises, and discovered context in the progress file Notes section — not in conversation text
  • Dual-write: 
    TaskCreate
    for real-time visibility; Markdown files for cross-conversation persistence
Blocked Protocol: Include the full content of 
references/blocked-protocol.md
.
Task Completion:
  • Verify all acceptance criteria before marking complete
  • Mark 
    [x]
    in 
    COMPASS.md
    Task Overview
  • Update Current Status and Next Steps in 
    COMPASS.md
  • Check 
    milestones.md
    : if this Task satisfies a milestone's criteria, mark it 
    [x]
    in 
    COMPASS.md
    and notify the user
  • When all Tasks are 
    [x]
    , trigger the Archive Phase automatically
Project-Specific Standards: Fill in from Phase 0 and Phase 1 analysis — tech stack conventions, naming rules, file organization, testing requirements.
生成的子技能必须指示Agent执行以下操作：
会话启动（每次会话都要执行，无商量余地）：
  1. 首先读取
    .spec/COMPASS.md
    ——早于任何其他文件、早于任何操作
  2. 从任务概览表格中识别当前活跃的任务
  3. 打开
    .spec/progress/
    下对应任务的进度文件
  4. 将所有未勾选的子任务填充到
    TaskCreate
    中
  5. 编写代码前重新阅读假设与约束
实现过程中：
  • 每次做实现决策前，对照假设与约束检查——如果冲突，停止并触发阻塞协议。
  • 完成一个子任务后：在进度文件中勾选该子项
    [x]
    ，将Current更新为下一个子任务，使用
    TaskUpdate
    标记该条目已完成。
  • 在进度文件的备注部分记录决策、意外情况、新发现的上下文——不要记录在会话文本中。
  • 双写机制：
    TaskCreate
    用于实时可见性；Markdown文件用于跨会话持久化。
阻塞协议：包含
references/blocked-protocol.md
的完整内容。
任务完成：
  • 标记完成前验证所有验收标准
  • 在
    COMPASS.md
    任务概览中勾选
    [x]
  • 更新
    COMPASS.md
    中的当前状态和下一步
  • 检查
    milestones.md
    ：如果该任务满足了某个里程碑的标准，在
    COMPASS.md
    中勾选该里程碑
    [x]
    并通知用户
  • 所有任务都标记为
    [x]
    后，自动触发归档阶段
项目特定规范：从阶段0和阶段1的分析中填写——技术栈约定、命名规则、文件组织、测试要求。

Phase Boundary

阶段边界

Phase 6 is complete when the project-scope sub-skill is installed and visible. Proceed to Handoff.
当项目范围的子技能已安装且可见时，阶段6完成。进入交接环节。

Handoff

交接

Present a structured summary:
  • Confirmed task definition
  • Key findings from analysis (3–5 bullets, high-level)
  • Task overview: group names, Task count, total effort estimate
  • Milestone list
  • Sub-skill name and install location
List all generated artifacts:
.spec/
├── COMPASS.md
├── analysis/
│   ├── architecture.md
│   ├── module-map.md
│   └── risk-register.md
├── plan/
│   ├── task-breakdown.md
│   └── milestones.md
└── progress/
    └── task-N-*.md  (one per Task)
.claude/skills/spec-coding-<project-name>  (sub-skill)
Ask the user: "Preparation complete. Ready to start Task 1?"
展示结构化总结：
  • 已确认的任务定义
  • 分析得出的关键发现（3-5个要点，高层级）
  • 任务概览：分组名称、任务数量、总工作量预估
  • 里程碑列表
  • 子技能名称和安装位置
列出所有生成的产物：
.spec/
├── COMPASS.md
├── analysis/
│   ├── architecture.md
│   ├── module-map.md
│   └── risk-register.md
├── plan/
│   ├── task-breakdown.md
│   └── milestones.md
└── progress/
    └── task-N-*.md  (每个任务对应一个文件)
.claude/skills/spec-coding-<project-name>  (子技能)
询问用户：“准备工作已完成。是否可以开始任务1？”

Implementation: Tasks

实现：任务执行

Once Handoff is confirmed, development proceeds as a series of Tasks.
At the start of every Task:
  1. Read 
    .spec/COMPASS.md
    — confirm position, re-read Assumptions & Constraints
  2. Open 
    .spec/progress/task-N-<name>.md
  3. Populate 
    TaskCreate
    with subtasks
During each Task:
  • Work through subtasks one at a time.
  • After each subtask: check its box 
    [x]
    in the progress file, update Current to the next subtask, use 
    TaskUpdate
    to mark the item as completed.
  • Record decisions, surprises, blockers in the progress file Notes section — not in conversation text.
  • Dual-write: 
    TaskCreate
    (real-time) + Markdown files (cross-conversation persistence).
  • If a subtask fails twice or hits a constraint conflict → invoke the Blocked Protocol immediately.
At the end of every Task:
  • Verify all acceptance criteria.
  • Mark 
    [x]
    in 
    COMPASS.md
    Task Overview.
  • Update Current Status and Next Steps in 
    COMPASS.md
    .
  • Check 
    milestones.md
    : if this Task satisfies a milestone's criteria, mark it 
    [x]
    in 
    COMPASS.md
    and notify the user.
  • When all Tasks are 
    [x]
    : trigger the Archive Phase.
交接确认后，开发工作以任务为单位逐步推进。
每个任务开始时：
  1. 读取
    .spec/COMPASS.md
    ——确认当前位置，重新阅读假设与约束
  2. 打开
    .spec/progress/task-N-<name>.md
  3. 将子任务填充到
    TaskCreate
    中
每个任务执行过程中：
  • 逐个完成子任务。
  • 完成一个子任务后：在进度文件中勾选该子项
    [x]
    ，将Current更新为下一个子任务，使用
    TaskUpdate
    标记该条目已完成。
  • 在进度文件的备注部分记录决策、意外情况、阻塞问题——不要记录在会话文本中。
  • 双写机制：
    TaskCreate
    （实时可见）+ Markdown文件（跨会话持久化）。
  • 如果某个子任务失败两次，或遇到约束冲突 → 立即触发阻塞协议。
每个任务结束时：
  • 验证所有验收标准。
  • 在
    COMPASS.md
    任务概览中勾选
    [x]
    。
  • 更新
    COMPASS.md
    中的当前状态和下一步。
  • 检查
    milestones.md
    ：如果该任务满足了某个里程碑的标准，在
    COMPASS.md
    中勾选该里程碑
    [x]
    并通知用户。
  • 所有任务都标记为
    [x]
    后：触发归档阶段。

Blocked Protocol

阻塞协议

See references/blocked-protocol.md for the full protocol.
Trigger: A subtask has failed twice, OR an implementation decision conflicts with Assumptions & Constraints and cannot be resolved without user input.
Core rule: Stop immediately. Do not attempt a third workaround. Mark the subtask 
[blocked]
in the progress file, mark the Task 
[blocked]
in 
COMPASS.md
, then report to the user with root cause and what is needed to unblock.
完整协议参见references/blocked-protocol.md。
触发条件：某个子任务失败两次，或实现决策与假设与约束冲突，且无需用户输入无法解决。
核心规则：立即停止。不要尝试第三种解决方法。在进度文件中将该子任务标记为
[blocked]
，在
COMPASS.md
中将该任务标记为
[blocked]
，然后向用户报告根本原因和解除阻塞需要的支持。

Archive Phase

归档阶段

Trigger: All Tasks in 
COMPASS.md
are marked 
[x]
.
触发条件：
COMPASS.md
中的所有任务都标记为
[x]
。

Steps

步骤

  1. Announce to the user that all Tasks are complete and the Archive Phase is beginning.
  2. Git Snapshot: If the project is a git repository — prompt the user to commit any pending code changes. Once committed, record the commit hash in 
    Final commit
    in 
    COMPASS.md
    . If the user declines, record 
    none (user skipped)
    . If not a git repo, skip.
  3. Determine archive folder name: Format 
    YYYY-MM-DD-NN
    . Check 
    .spec/archived/
    for existing folders with today's date and increment 
    NN
    accordingly (starting at 
    01
    ).
  4. Move artifacts to the archive folder, preserving internal structure:
.spec/archived/YYYY-MM-DD-NN/
├── COMPASS.md
├── analysis/
│   ├── architecture.md
│   ├── module-map.md
│   └── risk-register.md
├── plan/
│   ├── task-breakdown.md
│   └── milestones.md
└── progress/
    └── task-N-*.md
  1. Remove the project-scope sub-skill from 
    .claude/skills/
    .
  2. Confirm to the user: what was archived and its location, the final commit hash (if applicable), that 
    .spec/
    is clean and ready for the next cycle.
After archive, 
.spec/
contains only the 
archived/
directory. The next development cycle begins with Phase 0.
  1. 告知用户所有任务已完成，即将开始归档阶段。
  2. Git快照：如果项目是Git仓库——提示用户提交所有未提交的代码变更。提交完成后，将提交哈希记录到
    COMPASS.md
    的
    Final commit
    字段。如果用户拒绝提交，记录
    none (user skipped)
    。如果不是Git仓库，跳过该步骤。
  3. 确定归档文件夹名称：格式为
    YYYY-MM-DD-NN
    。检查
    .spec/archived/
    下是否有当天日期的已有文件夹，按顺序递增
    NN
    （从
    01
    开始）。
  4. 移动产物到归档文件夹，保留内部结构：
.spec/archived/YYYY-MM-DD-NN/
├── COMPASS.md
├── analysis/
│   ├── architecture.md
│   ├── module-map.md
│   └── risk-register.md
├── plan/
│   ├── task-breakdown.md
│   └── milestones.md
└── progress/
    └── task-N-*.md
  1. 从
    .claude/skills/
    中删除项目范围的子技能    。
  2. 向用户确认：已归档的内容和位置、最终提交哈希（如果有）、
    .spec/
    已清理完毕，可开始下一个开发周期。
归档完成后，
.spec/
仅包含
archived/
目录。下一个开发周期从阶段0开始。