Back to Details

dev-story

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Dev Story

开发故事

This skill bridges planning and code. It reads a story file in full, assembles all the context a programmer needs, routes to the correct specialist agent, and drives implementation to completion — including writing the test.
The loop for every story:
/qa-plan sprint           ← define test requirements before sprint begins
/story-readiness [path]   ← validate before starting
/dev-story [path]         ← implement it  (this skill)
/code-review [files]      ← review it
/story-done [path]        ← verify and close it
After all sprint stories are done: run 
/team-qa sprint
to execute the full QA cycle and get a sign-off verdict before advancing the project stage.
Output: Source code + test file in the project's 
src/
and 
tests/
directories.
该技能衔接规划与代码实现。它完整读取故事文件，整合程序员所需的全部上下文，将任务路由至对应领域的专业Agent，并推动实现至完成——包括编写测试用例。
每个故事的执行循环：
/qa-plan sprint           ←  sprint开始前定义测试需求
/story-readiness [path]   ←  启动前验证准备状态
/dev-story [path]         ←  执行实现（本技能）
/code-review [files]      ←  代码评审
/story-done [path]        ←  验证并关闭故事
所有sprint故事完成后： 运行
/team-qa sprint
执行完整QA周期，在推进项目阶段前获取签署确认结论。
输出： 源代码与测试文件将生成在项目的
src/
和
tests/
目录下。

Phase 1: Find the Story

阶段1：查找故事

If a path is provided: read that file directly.
If no argument: check 
production/session-state/active.md
for the active story. If found, confirm: "Continuing work on [story title] — is that correct?" If not found, ask: "Which story are we implementing?" Glob 
production/epics/**/*.md
and list stories with Status: Ready.
若提供路径：直接读取该文件。
若无参数：检查
production/session-state/active.md
中的活跃故事。若找到，确认："继续处理[故事标题]——是否正确？"若未找到，询问："我们要实现哪个故事？"遍历
production/epics/**/*.md
并列出状态为Ready的故事。

Phase 2: Load Full Context

阶段2：加载完整上下文

Before loading any context, verify required files exist. Extract the ADR path from the story's 
ADR Governing Implementation
field, then check:
FilePathIf missing
TR registry
docs/architecture/tr-registry.yaml
STOP — "TR registry not found at 
docs/architecture/tr-registry.yaml
. Run 
/architecture-review
to bootstrap the registry from your GDDs and ADRs."
Governing ADRpath from story's ADR fieldSTOP — "ADR file [path] not found. Run 
/architecture-decision
to create it, or correct the filename in the story's ADR field."
Control manifest
docs/architecture/control-manifest.md
WARN and continue — "Control manifest not found — layer rules cannot be checked. Run 
/create-control-manifest
."
If the TR registry or governing ADR is missing, set the story status to BLOCKED in the session state and do not spawn any programmer agent.
Read all of the following simultaneously — these are independent reads. Do not start implementation until all context is loaded:
加载任何上下文前，先验证所需文件是否存在。 从故事的
ADR Governing Implementation
字段提取ADR路径，然后检查：
文件路径缺失时处理
TR registry
docs/architecture/tr-registry.yaml
终止 — "未在
docs/architecture/tr-registry.yaml
找到TR注册表。运行
/architecture-review
从GDD和ADR引导生成注册表。"
Governing ADR故事ADR字段中的路径终止 — "未找到ADR文件[路径]。运行
/architecture-decision
创建该文件，或修正故事ADR字段中的文件名。"
Control manifest
docs/architecture/control-manifest.md
警告并继续 — "未找到控制清单——无法检查层级规则。运行
/create-control-manifest
。"
若TR注册表或Governing ADR缺失，将会话状态中的故事状态设置为BLOCKED，且不启动任何程序员Agent。
同时读取以下所有内容——这些读取操作相互独立。需等所有上下文加载完成后再启动实现：

The story file

故事文件

Extract and hold:
  • Story title, ID, layer, type (Logic / Integration / Visual/Feel / UI / Config/Data)
  • TR-ID — the GDD requirement identifier
  • Governing ADR reference
  • Manifest Version embedded in story header
  • Acceptance Criteria — every checkbox item, verbatim
  • Implementation Notes — the ADR guidance section in the story
  • Out of Scope boundaries
  • Test Evidence — the required test file path
  • Dependencies — what must be DONE before this story
提取并保存：
  • 故事标题、ID、层级、类型（Logic / Integration / Visual/Feel / UI / Config/Data）
  • TR-ID — GDD需求标识符
  • Governing ADR 引用
  • Manifest Version 故事头部嵌入的版本
  • Acceptance Criteria — 每个复选框项，原文保留
  • Implementation Notes — 故事中的ADR指导部分
  • Out of Scope 边界范围
  • Test Evidence — 所需测试文件路径
  • Dependencies — 本故事完成前必须完成的内容

The TR registry

TR registry

Read 
docs/architecture/tr-registry.yaml
. Look up the story's TR-ID. Read the current 
requirement
text — this is the source of truth for what the GDD requires now. Do not rely on any inline text in the story file (may be stale).
读取
docs/architecture/tr-registry.yaml
。查找故事的TR-ID。读取当前
requirement
文本——这是GDD当前需求的唯一可信来源。请勿依赖故事文件中的任何内联文本（可能已过期）。

The governing ADR

Governing ADR

Read 
docs/architecture/[adr-file].md
. Extract:
  • The full Decision section
  • The Implementation Guidelines section (this is what the programmer follows)
  • The Engine Compatibility section (post-cutoff APIs, known risks)
  • The ADR Dependencies section
读取
docs/architecture/[adr-file].md
。提取：
  • 完整的Decision章节
  • Implementation Guidelines章节（程序员需遵循的内容）
  • Engine Compatibility章节（ cutoff后API、已知风险）
  • ADR Dependencies章节

The control manifest

Control manifest

Read 
docs/architecture/control-manifest.md
. Extract the rules for this story's layer:
  • Required patterns
  • Forbidden patterns
  • Performance guardrails
Check: does the story's embedded Manifest Version match the current manifest header date? If they differ, use 
AskUserQuestion
before proceeding:
  • Prompt: "Story was written against manifest v[story-date]. Current manifest is v[current-date]. New rules may apply. How do you want to proceed?"
  • Options: 
    • [A] Update story manifest version and implement with current rules (Recommended)
    • [B] Implement with old rules — I accept the risk of non-compliance
    • [C] Stop here — I want to review the manifest diff first
If [A]: edit the story file's 
Manifest Version:
field to the current manifest date before spawning the programmer. Then read the manifest carefully for new rules. If [B]: edit the story file's 
Manifest Version:
field to the current manifest date AND add a 
Manifest-Note: Proceeded with old manifest rules on [date] — non-compliance risk accepted.
line to the story header. Read the manifest for new rules anyway. Note the decision in the Phase 6 summary under "Deviations". 
/story-done
will include the Manifest-Note in its deviations section without re-checking staleness. If [C]: stop. Do not spawn any agent. Let the user review and re-run 
/dev-story
.
读取
docs/architecture/control-manifest.md
。提取本故事层级的规则：
  • 必填模式
  • 禁用模式
  • 性能防护规则
检查：故事中嵌入的Manifest Version是否与当前清单头部日期匹配？ 若不匹配，在继续前使用
AskUserQuestion
：
  • 提示："故事基于清单v[故事日期]编写。当前清单为v[当前日期]。可能适用新规则。您希望如何处理？"
  • 选项： 
    • [A] 更新故事清单版本并按当前规则实现（推荐）
    • [B] 按旧规则实现——我接受不合规风险
    • [C] 在此终止——我想先查看清单差异
若选[A]：在启动程序员Agent前，将故事文件的
Manifest Version:
字段修改为当前清单日期。然后仔细读取清单中的新规则。 若选[B]：将故事文件的
Manifest Version:
字段修改为当前清单日期，并在故事头部添加一行
Manifest-Note: Proceeded with old manifest rules on [date] — non-compliance risk accepted.
。仍需读取清单中的新规则。在阶段6总结的"Deviations"部分记录该决策。
/story-done
将在其偏差部分包含该Manifest-Note，无需重新检查过期情况。 若选[C]：终止操作。不启动任何Agent。让用户完成评审后重新运行
/dev-story
。

Dependency validation

依赖验证

After extracting the Dependencies list from the story file, validate each:
  1. Glob 
    production/epics/**/*.md
    to find each dependency story file.
  2. Read its 
    Status:
    field.
  3. If any dependency has Status other than 
    Complete
    or 
    Done
    :
    • Use 
      AskUserQuestion
      :
      • Prompt: "Story '[current story]' depends on '[dependency title]' which is currently [status], not Complete. How do you want to proceed?"
      • Options: 
        • [A] Proceed anyway — I accept the dependency risk
        • [B] Stop — I'll complete the dependency first
        • [C] The dependency is done but status wasn't updated — mark it Complete and continue
    • If [B]: set story status to BLOCKED in session state and stop. Do not spawn any programmer agent.
    • If [C]: ask "May I update [dependency path] Status to Complete?" before continuing.
    • If [A]: note in Phase 6 summary under "Deviations": "Implemented with incomplete dependency: [dependency title] — [status]."
If a dependency file cannot be found: warn "Dependency story not found: [path]. Verify the path or create the story file."
从故事文件提取Dependencies列表后，逐一验证：
  1. 遍历
    production/epics/**/*.md
    查找每个依赖故事文件。
  2. 读取其
    Status:
    字段。
  3. 若任何依赖的状态不是
    Complete
    或
    Done
    ：
    • 使用
      AskUserQuestion
      ：
      • 提示："故事'[当前故事]'依赖'[依赖故事标题]'，其当前状态为[status]，未完成。您希望如何处理？"
      • 选项： 
        • [A] 继续执行——我接受依赖风险
        • [B] 终止——我先完成依赖项
        • [C] 依赖项已完成但状态未更新——标记为Complete并继续
    • 若选[B]：将会话状态中的故事状态设置为BLOCKED并终止。不启动任何程序员Agent。
    • 若选[C]：在继续前询问"是否允许我将[依赖路径]的状态更新为Complete？"
    • 若选[A]：在阶段6总结的"Deviations"部分记录："在依赖项未完成的情况下实现：[依赖故事标题] — [status]。"
若无法找到依赖文件：警告"未找到依赖故事：[path]。请验证路径或创建该故事文件。"

Engine reference

引擎参考

Read 
.claude/docs/technical-preferences.md
:
  • Engine:
    value — determines which programmer agents to use
  • Naming conventions (class names, file names, signal/event names)
  • Performance budgets (frame budget, memory ceiling)
  • Forbidden patterns
读取
.claude/docs/technical-preferences.md
：
  • Engine:
    值——决定使用哪些程序员Agent
  • 命名规范（类名、文件名、信号/事件名）
  • 性能预算（帧预算、内存上限）
  • 禁用模式

Mark Story In Progress

标记故事为进行中

Silently update two things before spawning any agent:
  1. production/sprint-status.yaml
     (if it exists): find the entry matching this story's file path and set 
    status: in_progress
    . Update the top-level 
    updated
    field to today's date. If the file does not exist, skip silently.
  2. The story file itself: edit the 
    Last Updated:
    field in the story header to today's date (format: 
    YYYY-MM-DD
    ). If the field does not exist in the story header, add it after the 
    Status:
    line. This enables sprint-status staleness detection for this story.
在启动任何Agent前，静默更新两项内容：
  1. production/sprint-status.yaml
    （若存在）：找到匹配本故事文件路径的条目，设置
    status: in_progress
    。将顶层
    updated
    字段更新为今日日期。若文件不存在，静默跳过。
  2. 故事文件本身：将故事头部的
    Last Updated:
    字段修改为今日日期（格式：
    YYYY-MM-DD
    ）。若故事头部无此字段，在
    Status:
    行后添加。这将启用本故事的sprint状态过期检测。

Phase 3: Route to the Right Programmer

阶段3：路由至对应程序员

Based on the story's Layer, Type, and system name, determine which specialist to spawn via Task.
Config/Data stories — skip agent spawning entirely: If the story's Type is 
Config/Data
, no programmer agent or engine specialist is needed. Jump directly to Phase 4 (Config/Data note). The implementation is a data file edit — no routing table evaluation, no engine specialist.
根据故事的Layer、Type和系统名称，通过Task确定启动哪个领域的专业Agent。
Config/Data故事——完全跳过Agent启动： 若故事类型为
Config/Data
，无需程序员Agent或引擎专家。直接跳转至阶段4（Config/Data说明）。实现仅为数据文件编辑——无需评估路由表，无需引擎专家。

Primary agent routing table

主Agent路由表

Story contextPrimary agent
Foundation layer — any type
engine-programmer
Any layer — Type: UI
ui-programmer
Any layer — Type: Visual/Feel
gameplay-programmer
(implements)
Core or Feature — gameplay mechanics
gameplay-programmer
Core or Feature — AI behaviour, pathfinding
ai-programmer
Core or Feature — networking, replication
network-programmer
Config/Data — no codeNo agent needed (see Phase 4 Config note)
故事上下文主Agent
Foundation层——任意类型
engine-programmer
任意层——类型：UI
ui-programmer
任意层——类型：Visual/Feel
gameplay-programmer
（负责实现）
Core或Feature——游戏玩法机制
gameplay-programmer
Core或Feature——AI行为、寻路
ai-programmer
Core或Feature——网络、复制
network-programmer
Config/Data——无需代码无需Agent（见阶段4 Config说明）

Engine specialist — always spawn as secondary for code stories

引擎专家——代码故事需始终启动为辅助Agent

Read the 
Engine Specialists
section of 
.claude/docs/technical-preferences.md
to get the configured primary specialist. Spawn them alongside the primary agent when the story involves engine-specific APIs, patterns, or the ADR has HIGH engine risk.
EngineSpecialist agents available
Godot 4
godot-specialist
, 
godot-gdscript-specialist
, 
godot-shader-specialist
Unity
unity-specialist
, 
unity-ui-specialist
, 
unity-shader-specialist
Unreal Engine
unreal-specialist
, 
ue-gas-specialist
, 
ue-blueprint-specialist
, 
ue-umg-specialist
, 
ue-replication-specialist
When engine risk is HIGH (from the ADR or VERSION.md): always spawn the engine specialist, even for non-engine-facing stories. High risk means the ADR records assumptions about post-cutoff engine APIs that need expert verification.
读取
.claude/docs/technical-preferences.md
的
Engine Specialists
部分，获取配置的主专家。当故事涉及引擎特定API、模式，或ADR存在HIGH引擎风险时，与主Agent一同启动引擎专家。
引擎可用专家Agent
Godot 4
godot-specialist
, 
godot-gdscript-specialist
, 
godot-shader-specialist
Unity
unity-specialist
, 
unity-ui-specialist
, 
unity-shader-specialist
Unreal Engine
unreal-specialist
, 
ue-gas-specialist
, 
ue-blueprint-specialist
, 
ue-umg-specialist
, 
ue-replication-specialist
当引擎风险为HIGH（来自ADR或VERSION.md）：无论故事是否面向引擎，始终启动引擎专家。高风险意味着ADR记录了对cutoff后引擎API的假设，需要专家验证。

Phase 4: Implement

阶段4：执行实现

Spawn the chosen programmer agent(s) via Task with the full context package:
Brief the agent with file paths and targeted reading instructions — do not serialize document content into the Task prompt. The agent reads what it needs directly:
  1. Story file: 
    [story-path]
    — read in full
  2. GDD requirement: look up TR-ID 
    [TR-XXX-NNN]
    in 
    docs/architecture/tr-registry.yaml
    — use the 
    requirement
    field as source of truth
  3. ADR: 
    docs/architecture/[adr-file].md
    — read the Decision and Implementation Guidelines sections only
  4. Control manifest: 
    docs/architecture/control-manifest.md
    — read rules for the [layer] layer only
  5. Engine preferences: 
    .claude/docs/technical-preferences.md
    — read naming conventions and performance budgets
  6. Test file path: 
    [path from story's Test Evidence section]
    — this file must be created as part of implementation
  7. Test requirement (Logic and Integration stories only): The test file MUST be created at 
    [path from the story's Test Evidence section]
    . Write the test alongside the implementation — do not defer it. The story cannot be closed via 
    /story-done
    without this file present. Each acceptance criterion must have at least one test function covering it. Test file naming: 
    [system]_[feature]_test.[ext]
    . Function naming: 
    test_[scenario]_[expected_outcome]
    . No random seeds, no time-dependent assertions, no external I/O.
  8. Explicit instruction: implement this story following the ADR guidelines, respect the manifest rules, stay within the story's Out of Scope boundaries. Write clean, doc-commented public APIs.
The agent should:
  • Create or modify files in 
    src/
    following the ADR guidelines
  • Respect all Required and Forbidden patterns from the control manifest
  • Stay within the story's Out of Scope boundaries (do not touch unrelated files)
  • Write clean, doc-commented public APIs
通过Task启动选定的程序员Agent，并提供完整上下文包：
向Agent提供文件路径和定向读取指令——请勿将文档内容序列化到Task提示中。Agent将直接读取所需内容：
  1. 故事文件：
    [story-path]
    — 完整读取
  2. GDD需求：在
    docs/architecture/tr-registry.yaml
    中查找TR-ID 
    [TR-XXX-NNN]
    — 使用
    requirement
    字段作为可信来源
  3. ADR：
    docs/architecture/[adr-file].md
    — 仅读取Decision和Implementation Guidelines章节
  4. Control manifest：
    docs/architecture/control-manifest.md
    — 仅读取**[layer]**层的规则
  5. 引擎偏好：
    .claude/docs/technical-preferences.md
    — 读取命名规范和性能预算
  6. 测试文件路径：
    [故事Test Evidence部分的路径]
    — 该文件必须作为实现的一部分创建
  7. 测试需求（仅Logic和Integration故事）：测试文件必须创建在
    [故事Test Evidence部分的路径]
    。与实现同步编写测试——不得延迟。未创建该文件的故事无法通过
    /story-done
    关闭。每个验收标准必须至少有一个测试函数覆盖。测试文件命名：
    [system]_[feature]_test.[ext]
    。函数命名：
    test_[scenario]_[expected_outcome]
    。禁止随机种子、依赖时间的断言、外部I/O。
  8. 明确指令：遵循ADR指南实现本故事，遵守清单规则，不超出故事的Out of Scope边界。编写清晰、带文档注释的公共API。
Agent应：
  • 遵循ADR指南在
    src/
    目录下创建或修改文件
  • 遵守Control manifest中的所有必填和禁用模式
  • 不超出故事的Out of Scope边界（不修改无关文件）
  • 编写清晰、带文档注释的公共API

Config/Data stories (no agent needed)

Config/Data故事（无需Agent）

For Type: Config/Data stories, no programmer agent is required. The implementation is editing a data file. Read the story's acceptance criteria and make the specified changes to the data file directly. Note which values were changed and what they changed from/to.
对于Type: Config/Data故事，无需程序员Agent。实现仅为编辑数据文件。读取故事的验收标准，直接对数据文件进行指定修改。记录修改的字段值及变更前后内容。

Visual/Feel stories

Visual/Feel故事

Spawn 
gameplay-programmer
to implement the code/animation calls. Note that Visual/Feel acceptance criteria cannot be auto-verified — the "does it feel right?" check happens in 
/story-done
via manual confirmation.
启动
gameplay-programmer
实现代码/动画调用。注意Visual/Feel验收标准无法自动验证——"体验是否符合预期？"的检查将在
/story-done
中通过人工确认完成。

Phase 5: Test Evidence Requirements

阶段5：测试证据要求

The test requirement was included in the Phase 4 programmer agent brief (item 7). This phase summarizes what evidence each story type requires — used when collecting the Phase 6 summary.
Story TypeRequired EvidenceNotes
LogicAutomated unit test at path from story's Test Evidence sectionBLOCKING — included in Phase 4 agent brief
IntegrationIntegration test OR documented playtest recordBLOCKING — included in Phase 4 agent brief
Visual/FeelEvidence doc at 
production/qa/evidence/[slug]-evidence.md
ADVISORY — note in Phase 6 summary
UIManual walkthrough doc or interaction testADVISORY — note in Phase 6 summary
Config/DataNone — smoke check serves as evidenceN/A
For Visual/Feel and UI stories, include in the Phase 6 summary: "Manual evidence required at 
production/qa/evidence/[slug]-evidence.md
before this story can be fully closed."
测试需求已包含在阶段4程序员Agent的指令中（第7项）。本阶段总结每种故事类型所需的证据——用于收集阶段6总结时。
故事类型所需证据说明
Logic故事Test Evidence部分路径下的自动化单元测试阻塞性要求——已包含在阶段4Agent指令中
Integration集成测试或文档化的 playtest 记录阻塞性要求——已包含在阶段4Agent指令中
Visual/Feel
production/qa/evidence/[slug]-evidence.md
路径下的证据文档		建议性要求——在阶段6总结中记录
UI人工走查文档或交互测试建议性要求——在阶段6总结中记录
Config/Data无——冒烟测试可作为证据不适用
对于Visual/Feel和UI故事，在阶段6总结中包含："本故事完全关闭前，需在
production/qa/evidence/[slug]-evidence.md
提供人工验证证据。"

Phase 6: Collect and Summarise

阶段6：收集与总结

After the programmer agent(s) complete, collect:
  • Files created or modified (with paths)
  • Test file created (path and number of test functions written)
  • Any deviations from the story's Out of Scope boundary (flag these)
  • Any questions or blockers the agent surfaced
  • Any engine-specific risks the specialist flagged
Present a concise implementation summary:
undefined
程序员Agent完成后，收集：
  • 创建或修改的文件（含路径）
  • 创建的测试文件（路径及编写的测试函数数量）
  • 任何超出故事Out of Scope边界的偏差（标记这些内容）
  • Agent提出的任何问题或阻塞
  • 专家标记的任何引擎特定风险
呈现简洁的实现总结：
undefined

Implementation Complete: [Story Title]

实现完成：[故事标题]

Files changed:
  • src/[path]
    — created / modified ([brief description])
  • tests/[path]
    — test file ([N] test functions)
Acceptance criteria covered:
  • [criterion] — implemented in [file:function]
  • [criterion] — covered by test [test_name]
  • [criterion] — DEFERRED: requires playtest (Visual/Feel)
Deviations from scope: [None] or [list files touched outside story boundary] Engine risks flagged: [None] or [specialist finding] Blockers: [None] or [describe]
Before running 
/story-done
: run your test suite locally and confirm the tests you wrote pass. 
/story-done
will re-run them automatically, but a failing test discovered there means returning to implementation context.
Ready for: 
/code-review [file1] [file2]
then 
/story-done [story-path]

---
修改的文件:
  • src/[path]
    — 创建 / 修改（[简要描述]）
  • tests/[path]
    — 测试文件（[N]个测试函数）
覆盖的验收标准:
  • [标准内容] — 在[文件:函数]中实现
  • [标准内容] — 由测试[test_name]覆盖
  • [标准内容] — 延迟：需playtest（Visual/Feel）
范围偏差: [无] 或 [列出超出故事边界的文件] 标记的引擎风险: [无] 或 [专家发现] 阻塞项: [无] 或 [描述]
运行/story-done前: 本地运行测试套件，确认编写的测试通过。/story-done将自动重新运行测试，但如果在此处发现测试失败，需返回实现环节。
下一步：
/code-review [file1] [file2]
然后 
/story-done [story-path]

---

Phase 7: Update Session State

阶段7：更新会话状态

Silently append to 
production/session-state/active.md
:
undefined
静默追加内容至
production/session-state/active.md
：
undefined

Session Extract — /dev-story [date]

会话提取 — /dev-story [日期]

  • Story: [story-path] — [story title]
  • Files changed: [comma-separated list]
  • Test written: [path, or "None — Visual/Feel/Config story"]
  • Blockers: [None, or description]
  • Next: /code-review [files] then /story-done [story-path]

Create `active.md` if it does not exist. Confirm: "Session state updated."

---
  • 故事: [story-path] — [故事标题]
  • 修改的文件: [逗号分隔列表]
  • 编写的测试: [路径，或"无——Visual/Feel/Config故事"]
  • 阻塞项: [无，或描述]
  • 下一步: /code-review [files] 然后 /story-done [story-path]

若`active.md`不存在则创建。确认："会话状态已更新。"

---

Error Recovery Protocol

错误恢复协议

If any spawned agent (via Task) returns BLOCKED, errors, or cannot complete:
  1. Surface immediately: Report "[AgentName]: BLOCKED — [reason]" to the user before continuing to dependent phases
  2. Assess dependencies: Check whether the blocked agent's output is required by subsequent phases. If yes, do not proceed past that dependency point without user input.
  3. Offer options via AskUserQuestion with choices:
    • Skip this agent and note the gap in the final report
    • Retry with narrower scope
    • Stop here and resolve the blocker first
  4. Always produce a partial report — output whatever was completed. Never discard work because one agent blocked.
Common blockers:
  • Input file missing (story not found, GDD absent) → redirect to the skill that creates it
  • ADR status is Proposed → do not implement; run 
    /architecture-decision
    first
  • Scope too large → split into two stories via 
    /create-stories
  • Conflicting instructions between ADR and story → surface the conflict, do not guess
  • Manifest version mismatch → show diff to user, ask whether to proceed with old rules or update story first
若任何通过Task启动的Agent返回BLOCKED、错误或无法完成：
  1. 立即反馈：在继续后续依赖阶段前，向用户报告"[AgentName]: BLOCKED — [原因]"
  2. 评估依赖：检查被阻塞Agent的输出是否为后续阶段所需。若是，无用户输入则不得越过该依赖点继续。
  3. 通过AskUserQuestion提供选项：
    • 跳过该Agent并在最终报告中记录缺口
    • 缩小范围重试
    • 在此终止并先解决阻塞
  4. 始终生成部分报告——输出已完成的所有内容。不得因单个Agent阻塞而丢弃工作成果。
常见阻塞项：
  • 输入文件缺失（未找到故事、GDD不存在）→ 重定向至创建该文件的技能
  • ADR状态为Proposed → 不得实现；先运行
    /architecture-decision
  • 范围过大 → 通过
    /create-stories
    拆分为两个故事
  • ADR与故事存在冲突指令 → 反馈冲突，不得自行猜测
  • 清单版本不匹配 → 向用户展示差异，询问是按旧规则继续还是先更新故事

Collaborative Protocol

协作协议

  • File writes are delegated — all source code, test files, and evidence docs are written by sub-agents spawned via Task. Each sub-agent enforces the "May I write to [path]?" protocol individually. This orchestrator does not write files directly.
  • Load before implementing — do not start coding until all context is loaded (story, TR-ID, ADR, manifest, engine prefs). Incomplete context produces code that drifts from design.
  • The ADR is the law — implementation must follow the ADR's Implementation Guidelines. If the guidelines conflict with what seems "better," flag it in the summary rather than silently deviating.
  • Stay in scope — the Out of Scope section is a contract. If implementing the story requires touching an out-of-scope file, stop and surface it: "Implementing [criterion] requires modifying [file], which is out of scope. Shall I proceed or create a separate story?"
  • Test is not optional for Logic/Integration — do not mark implementation complete without the test file existing
  • Visual/Feel criteria are deferred, not skipped — mark them as DEFERRED in the summary; they will be manually verified in 
    /story-done
  • Ask before large structural decisions — if the story requires an architectural pattern not covered by the ADR, surface it before implementing: "The ADR doesn't specify how to handle [case]. My plan is [X]. Proceed?"
  • 文件写入委托——所有源代码、测试文件和证据文档均由通过Task启动的子Agent编写。每个子Agent需单独执行"是否允许我写入[path]？"协议。本编排器不直接写入文件。
  • 先加载再实现——所有上下文（故事、TR-ID、ADR、清单、引擎偏好）加载完成前不得启动编码。上下文不完整会导致代码偏离设计。
  • ADR为准则——实现必须遵循ADR的Implementation Guidelines。若指南与看似"更优"的方案冲突，需在总结中标记，不得静默偏离。
  • 不超出范围——Out of Scope部分是约定。若实现故事需修改超出范围的文件，需终止并反馈："实现[标准]需修改[文件]，该文件超出范围。是否继续执行或创建单独故事？"
  • Logic/Integration故事的测试为必填项——未创建测试文件不得标记实现完成
  • Visual/Feel标准延迟处理，不得跳过——在总结中标记为DEFERRED；将在
    /story-done
    中人工验证
  • 重大结构决策前需询问——若故事需要ADR未覆盖的架构模式，需在实现前反馈："ADR未指定如何处理[场景]。我的计划是[X]。是否继续？"

Recommended Next Steps

推荐下一步

  • Run 
    /code-review [file1] [file2]
    to review the implementation before closing the story
  • Run 
    /story-done [story-path]
    to verify acceptance criteria and mark the story complete
  • After all sprint stories are done: run 
    /team-qa sprint
    for the full QA cycle before advancing the project stage
  • 运行
    /code-review [file1] [file2]
    在关闭故事前评审实现
  • 运行
    /story-done [story-path]
    验证验收标准并标记故事完成
  • 所有sprint故事完成后：运行
    /team-qa sprint
    执行完整QA周期，再推进项目阶段