Back to Details

solo-build

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

/build

/build

This skill is self-contained — follow the task loop, TDD rules, and completion flow below instead of delegating to external build/execution skills (superpowers, etc.).
Execute tasks from an implementation plan. Finds 
plan.md
(in 
docs/plan/
), picks the next unchecked task, implements it with TDD workflow, commits, and updates progress.
该Skill是独立的——请遵循下方的任务循环、TDD规则和完成流程，而非委托给外部的构建/执行Skill（如超级能力等）。
执行实施计划中的任务。查找
docs/plan/
目录下的
plan.md
文件，选择下一个未完成的任务，采用TDD工作流实现该任务，提交代码并更新进度。

When to use

使用时机

After 
/plan
has created a track with 
spec.md
+ 
plan.md
. This is the execution engine.
Pipeline: 
/plan
→ 
/build
 → 
/deploy
→ 
/review
在
/plan
已创建包含
spec.md
和
plan.md
的跟踪任务之后使用。这是执行引擎。
流程：
/plan
→ 
/build
 → 
/deploy
→ 
/review

MCP Tools (use if available)

MCP工具（如有可用请使用）

  • session_search(query)
    — find how similar problems were solved before
  • project_code_search(query, project)
    — find reusable code across projects
  • codegraph_query(query)
    — check file dependencies, imports, callers
If MCP tools are not available, fall back to Glob + Grep + Read.
  • session_search(query)
    — 查找之前类似问题的解决方案
  • project_code_search(query, project)
    — 在跨项目中查找可复用代码
  • codegraph_query(query)
    — 检查文件依赖、导入项、调用方
如果MCP工具不可用，回退使用Glob + Grep + Read。

Pre-flight Checks

预检查

  1. Detect context — find where plan files live:
    • Check 
      docs/plan/*/plan.md
      — standard location
    • Use whichever exists.
    • DO NOT search for 
      conductor/
      or any other directory — only 
      docs/plan/
      .
  2. Load workflow config from 
    docs/workflow.md
    (if exists):
    • TDD strictness (strict / moderate / none)
    • Commit strategy (conventional commits format)
    • Verification checkpoint rules
    • Integration Testing section — if present, run the specified CLI commands after completing tasks that touch the listed paths If 
      docs/workflow.md
      missing: use defaults (moderate TDD, conventional commits).
  3. Verify git hooks are installed:
    Read the stack YAML (
    templates/stacks/{stack}.yaml
    ) — the 
    pre_commit
    field tells you which system and what it runs:
    • husky + lint-staged
      → JS/TS stacks (eslint + prettier + tsc)
    • pre-commit
      → Python stacks (ruff + ruff-format + ty)
    • lefthook
      → mobile stacks (swiftlint/detekt + formatter)
    Then verify the hook system is active:
    bash
    # husky
[ -f .husky/pre-commit ] && git config core.hooksPath | grep -q husky && echo "OK" || echo "NOT ACTIVE"
# pre-commit (Python)
[ -f .pre-commit-config.yaml ] && [ -f .git/hooks/pre-commit ] && echo "OK" || echo "NOT ACTIVE"
# lefthook
[ -f lefthook.yml ] && lefthook version >/dev/null 2>&1 && echo "OK" || echo "NOT ACTIVE"
    If not active — install before first commit:
    • husky: 
      pnpm prepare
      (or 
      npm run prepare
      )
    • pre-commit: 
      uv run pre-commit install
    • lefthook: 
      lefthook install
    Don't use 
    --no-verify
    on commits — if hooks fail, fix the issue and commit again.
  1. 检测上下文 — 查找计划文件的位置：
    • 检查
      docs/plan/*/plan.md
      — 标准位置
    • 使用任何存在的该文件。
    • 请勿搜索
      conductor/
      或任何其他目录 — 仅搜索
      docs/plan/
      。
  2. 从
    docs/workflow.md
    加载工作流配置（如果存在）：
    • TDD严格程度（strict / moderate / none）
    • 提交策略（约定式提交格式）
    • 验证检查点规则
    • 集成测试部分 — 如果存在，在完成涉及列出路径的任务后运行指定的CLI命令 如果
      docs/workflow.md
      缺失：使用默认设置（中等严格TDD，约定式提交）。
  3. 验证git钩子已安装：
    读取栈YAML文件（
    templates/stacks/{stack}.yaml
    ）——
    pre_commit
    字段会告知你使用的系统及其运行内容：
    • husky + lint-staged
      → JS/TS栈（eslint + prettier + tsc）
    • pre-commit
      → Python栈（ruff + ruff-format + ty）
    • lefthook
      → 移动栈（swiftlint/detekt + 格式化工具）
    然后验证钩子系统是否激活：
    bash
    # husky
[ -f .husky/pre-commit ] && git config core.hooksPath | grep -q husky && echo "OK" || echo "NOT ACTIVE"
# pre-commit (Python)
[ -f .pre-commit-config.yaml ] && [ -f .git/hooks/pre-commit ] && echo "OK" || echo "NOT ACTIVE"
# lefthook
[ -f lefthook.yml ] && lefthook version >/dev/null 2>&1 && echo "OK" || echo "NOT ACTIVE"
    如果未激活 — 在首次提交前安装：
    • husky: 
      pnpm prepare
      （或
      npm run prepare
      ）
    • pre-commit: 
      uv run pre-commit install
    • lefthook: 
      lefthook install
    提交时请勿使用
    --no-verify
    — 如果钩子检查失败，修复问题后再提交。

Track Selection

跟踪任务选择

If 
$ARGUMENTS
contains a track ID:

如果
$ARGUMENTS
包含跟踪ID：

  • Validate: 
    {plan_root}/{argument}/plan.md
    exists (check 
    docs/plan/
    ).
  • If not found: search 
    docs/plan/*/plan.md
    for partial matches, suggest corrections.
  • 验证：
    {plan_root}/{argument}/plan.md
    是否存在（检查
    docs/plan/
    目录）。
  • 如果未找到：在
    docs/plan/*/plan.md
    中搜索部分匹配项，建议修正方案。

If 
$ARGUMENTS
contains 
--task X.Y
:

如果
$ARGUMENTS
包含
--task X.Y
：

  • Jump directly to that task in the active track.
  • 直接跳转到当前跟踪任务中的该任务。

If no argument:

如果无参数：

  1. Search for 
    plan.md
    files in 
    docs/plan/
    .
  2. Read each 
    plan.md
    , find tracks with uncompleted tasks.
  3. If multiple, ask via AskUserQuestion.
  4. If zero tracks: "No plans found. Run 
    /plan
    first."
  1. 在
    docs/plan/
    目录中搜索
    plan.md
    文件。
  2. 读取每个
    plan.md
    ，找到包含未完成任务的跟踪任务。
  3. 如果有多个，通过AskUserQuestion询问用户。
  4. 如果没有跟踪任务：“未找到计划，请先运行/plan命令。”

Context Loading

上下文加载

Step 1 — Architecture overview (if MCP available)

步骤1 — 架构概述（如果MCP可用）

codegraph_explain(project="{project name}")
Returns: stack, languages, directory layers, key patterns, top dependencies, hub files — one call instead of exploring the tree manually.
codegraph_explain(project="{project name}")
返回内容：栈信息、编程语言、目录层级、核心模式、主要依赖、枢纽文件 — 一次调用即可替代手动探索目录树。

Step 2 — Essential docs (parallel reads)

步骤2 — 核心文档（并行读取）

  1. docs/plan/{trackId}/plan.md
    — task list (REQUIRED)
  2. docs/plan/{trackId}/spec.md
    — acceptance criteria (REQUIRED)
  3. docs/workflow.md
    — TDD policy, commit strategy (if exists)
  4. CLAUDE.md
    — architecture, Do/Don't
  5. .solo/pipelines/progress.md
    — running docs from previous iterations (if exists, pipeline-specific). Contains what was done in prior pipeline sessions: stages completed, commit SHAs, last output lines. Use this to avoid repeating completed work.
Do NOT read source code files at this stage. Only docs. Source files are loaded per-task in the execution loop (step 3 below).
  1. docs/plan/{trackId}/plan.md
    — 任务列表（必填）
  2. docs/plan/{trackId}/spec.md
    — 验收标准（必填）
  3. docs/workflow.md
    — TDD策略、提交策略（如果存在）
  4. CLAUDE.md
    — 架构规范、注意事项
  5. .solo/pipelines/progress.md
    — 之前迭代的运行文档（如果存在，特定于流水线）。包含之前流水线会话中已完成的工作：已完成的阶段、提交SHA、最后输出内容。使用此文档避免重复已完成的工作。
**此阶段请勿读取源代码文件。**仅读取文档。源代码文件会在执行循环的步骤3中按任务加载。

Resumption

任务恢复

If a task is marked 
[~]
in plan.md:
Resuming: {track title}
Last task: Task {X.Y}: {description} [in progress]

1. Continue from where we left off
2. Restart current task
3. Show progress summary first
Ask via AskUserQuestion, then proceed.
如果
plan.md
中某个任务标记为
[~]
：
恢复任务：{跟踪任务标题}
最后执行的任务：任务X.Y：{描述} [进行中]

1. 从上次中断处继续
2. 重启当前任务
3. 先显示进度摘要
通过AskUserQuestion询问用户，然后继续执行。

Task Execution Loop

任务执行循环

Makefile convention: If 
Makefile
exists in project root, always prefer 
make
targets over raw commands. Use 
make test
instead of 
pnpm test
, 
make lint
instead of 
pnpm lint
, 
make build
instead of 
pnpm build
, etc. Run 
make help
(or read Makefile) to discover available targets. If a 
make integration
or similar target exists, use it for integration testing after pipeline-related tasks.
IMPORTANT — All-done check: Before entering the loop, scan plan.md for ANY 
- [ ]
or 
- [~]
tasks. If ALL tasks are 
[x]
— skip the loop entirely and jump to Completion section below to run final verification and output 
<solo:done/>
.
For each incomplete task in plan.md (marked 
[ ]
), in order:
**Makefile约定：**如果项目根目录存在
Makefile
，始终优先使用
make
目标而非原始命令。使用
make test
替代
pnpm test
，
make lint
替代
pnpm lint
，
make build
替代
pnpm build
等。运行
make help
（或读取Makefile）以查看可用的目标。如果存在
make integration
或类似目标，在完成流水线相关任务后使用它进行集成测试。
重要 — 全部完成检查：进入循环前，扫描
plan.md
中所有
- [ ]
或
- [~]
任务。如果所有任务均为
[x]
— 完全跳过循环，直接跳转到下方的完成部分，运行最终验证并输出
<solo:done/>
。
对于
plan.md
中每个未完成的任务（标记为
[ ]
），按顺序执行：

1. Find Next Task

1. 查找下一个任务

Parse plan.md for first line matching 
- [ ] Task X.Y:
(or 
- [~] Task X.Y:
if resuming).
解析
plan.md
，找到第一个匹配
- [ ] Task X.Y:
（或恢复时的
- [~] Task X.Y:
）的行。

2. Start Task

2. 启动任务

  • Update plan.md: 
    [ ]
    → 
    [~]
    for current task.
  • Announce: "Starting Task X.Y: {description}"
  • 更新
    plan.md
    ：将
    [ ]
    改为
    [~]
    标记当前任务为进行中。
  • 通知：“开始执行任务X.Y：{描述}”

3. Research (smart, before coding)

3. 调研（编码前的智能操作）

Do NOT grep the entire project or read all source files. Load only what this specific task needs.
If MCP available (preferred):
  1. project_code_search(query="{task keywords}", project="{name}")
    — find relevant code in the project. Read only the top 2-3 results.
  2. session_search("{task keywords}")
    — check if you solved this before.
  3. codegraph_query("MATCH (f:File {project: '{name}'})-[:IMPORTS]->(dep) WHERE f.path CONTAINS '{module}' RETURN dep.path")
    — check imports/dependencies of files you'll modify.
If MCP unavailable (fallback):
  1. Read ONLY the files explicitly mentioned in the task description (file paths).
  2. Glob for the specific module directory the task targets (e.g., 
    src/auth/**/*.ts
    ), not the entire project.
  3. If the task doesn't mention files, use Grep with a narrow pattern on 
    src/
    or 
    app/
    — never 
    **/*
    .
Never do: 
Grep "keyword" .
across the whole project. This dumps hundreds of lines into context for no reason. Be surgical.
请勿 grep整个项目或读取所有源代码文件。仅加载当前任务所需的内容。
如果MCP可用（优先使用）：
  1. project_code_search(query="{任务关键词}", project="{项目名}")
    — 在项目中查找相关代码。仅读取前2-3个结果。
  2. session_search("{任务关键词}")
    — 检查之前是否解决过此类问题。
  3. codegraph_query("MATCH (f:File {project: '{name}'})-[:IMPORTS]->(dep) WHERE f.path CONTAINS '{module}' RETURN dep.path")
    — 检查你将修改的文件的导入项/依赖。
如果MCP不可用（回退方案）：
  1. 仅读取任务描述中明确提及的文件（文件路径）。
  2. 仅对任务目标的特定模块目录使用Glob（例如
    src/auth/**/*.ts
    ），而非整个项目。
  3. 如果任务未提及文件，在
    src/
    或
    app/
    目录下使用Grep并设置窄匹配模式 — 绝不要使用
    **/*
    。
**禁止操作：**在整个项目中运行
Grep "keyword" .
。这会将数百行无关内容加载到上下文中。请精准操作。

Python-Specific Quality Tools

Python专属质量工具

When the project uses a Python stack (detected by 
pyproject.toml
or stack YAML), run the full Astral toolchain:
  1. Ruff — linting + formatting (always):
    bash
    uv run ruff check --fix .
uv run ruff format .
  2. ty — type-checking (if 
    ty
    in dev dependencies or stack YAML):
    bash
    uv run ty check .
    ty is Astral's type-checker (extremely fast, replaces mypy/pyright). Fix type errors before committing.
  3. Hypothesis — property-based testing (if 
    hypothesis
    in dependencies):
    • Use 
      @given(st.from_type(MyModel))
      to auto-generate Pydantic model inputs.
    • Use 
      @given(st.text(), st.integers())
      for edge-case coverage on parsers/validators.
    • Hypothesis tests go in the same test files alongside regular pytest tests.
  4. Pre-commit — run all hooks before committing:
    bash
    uv run pre-commit run --all-files
Run these checks after each task implementation, before 
git commit
. If any fail, fix before proceeding.
当项目使用Python栈（通过
pyproject.toml
或栈YAML检测），运行完整的Astral工具链：
  1. Ruff — 代码检查+格式化（必须执行）：
    bash
    uv run ruff check --fix .
uv run ruff format .
  2. ty — 类型检查（如果
    ty
    在开发依赖或栈YAML中）：
    bash
    uv run ty check .
    ty是Astral的类型检查器（速度极快，替代mypy/pyright）。提交前修复所有类型错误。
  3. Hypothesis — 属性化测试（如果
    hypothesis
    在依赖中）：
    • 使用
      @given(st.from_type(MyModel))
      自动生成Pydantic模型输入。
    • 使用
      @given(st.text(), st.integers())
      为解析器/验证器提供边界用例覆盖。
    • Hypothesis测试与常规pytest测试放在同一测试文件中。
  4. Pre-commit — 提交前运行所有钩子：
    bash
    uv run pre-commit run --all-files
在每个任务实现后、
git commit
前运行这些检查。如果任何检查失败，修复后再继续。

JS/TS-Specific Quality Tools

JS/TS专属质量工具

When the project uses a JS/TS stack (detected by 
package.json
or stack YAML):
  1. ESLint — linting (always):
    bash
    pnpm lint --fix
  2. Prettier — formatting (always):
    bash
    pnpm format
  3. tsc --noEmit — type-checking (strict mode):
    bash
    pnpm tsc --noEmit
    Fix type errors before committing. Strict mode should be on in tsconfig.json.
  4. Knip — dead code detection (if in devDependencies, run periodically):
    bash
    pnpm knip
    Finds unused files, exports, and dependencies. Run after significant refactors.
  5. Pre-commit — husky + lint-staged runs ESLint + Prettier + tsc on staged files.
当项目使用JS/TS栈（通过
package.json
或栈YAML检测）：
  1. ESLint — 代码检查（必须执行）：
    bash
    pnpm lint --fix
  2. Prettier — 格式化（必须执行）：
    bash
    pnpm format
  3. tsc --noEmit — 类型检查（严格模式）：
    bash
    pnpm tsc --noEmit
    提交前修复类型错误。tsconfig.json中应启用严格模式。
  4. Knip — 死代码检测（如果在devDependencies中，定期运行）：
    bash
    pnpm knip
    查找未使用的文件、导出项和依赖。在重大重构后运行。
  5. Pre-commit — husky + lint-staged会对暂存文件运行ESLint + Prettier + tsc。

iOS/Android-Specific Quality Tools

iOS/Android专属质量工具

When the project uses a mobile stack:
iOS (Swift):
bash
swiftlint lint --strict
swift-format format --in-place --recursive Sources/
Android (Kotlin):
bash
./gradlew detekt
./gradlew ktlintCheck
Both use lefthook for pre-commit hooks (language-agnostic, no Node.js required).
当项目使用移动栈：
iOS (Swift)：
bash
swiftlint lint --strict
swift-format format --in-place --recursive Sources/
Android (Kotlin)：
bash
./gradlew detekt
./gradlew ktlintCheck
两者均使用lefthook作为提交前钩子（与语言无关，无需Node.js）。

4. TDD Workflow (if TDD enabled in workflow.md)

4. TDD工作流（如果workflow.md中启用TDD）

Red — write failing test:
  • Create/update test file for the task functionality.
  • Run tests to confirm they fail.
Green — implement:
  • Write minimum code to make the test pass.
  • Run tests to confirm pass.
Refactor:
  • Clean up while tests stay green.
  • Run tests one final time.
红 — 编写失败的测试：
  • 为任务功能创建/更新测试文件。
  • 运行测试确认测试失败。
绿 — 实现功能：
  • 编写最少代码使测试通过。
  • 运行测试确认测试通过。
重构：
  • 在保持测试通过的前提下清理代码。
  • 最后再运行一次测试。

5. Non-TDD Workflow (if TDD is "none" or "moderate" and task is simple)

5. 非TDD工作流（如果TDD设置为“none”或“moderate”且任务简单）

  • Implement the task directly.
  • Run existing tests to check nothing broke.
  • For "moderate": write tests for business logic and API routes, skip for UI/config.
  • 直接实现任务。
  • 运行现有测试检查是否破坏了原有功能。
  • 对于“moderate”模式：为业务逻辑和API路由编写测试，跳过UI/配置相关的测试。

5.5. Integration Testing (CLI-First)

5.5. 集成测试（CLI优先）

If the task touches core business logic (pipeline, algorithms, agent tools), run 
make integration
(or the integration command from 
docs/workflow.md
). The CLI exercises the same code paths as the UI without requiring a browser. If 
make integration
fails, fix before committing.
如果任务涉及核心业务逻辑（流水线、算法、Agent工具），运行
make integration
（或
docs/workflow.md
中指定的集成命令）。CLI会模拟UI的代码路径，无需浏览器。如果
make integration
失败，修复后再提交。

5.6. Visual Verification (if browser/simulator/emulator available)

5.6. 视觉验证（如果浏览器/模拟器/模拟器可用）

After implementation, run a quick visual smoke test if tools are available:
Web projects (Playwright MCP or browser tools): If you have Playwright MCP tools or browser tools available:
  1. Start the dev server if not already running (check stack YAML for 
    dev_server.command
    )
  2. Navigate to the page affected by the current task
  3. Check the browser console for errors (hydration mismatches, uncaught exceptions, 404s)
  4. Take a screenshot to verify the visual output matches expectations
  5. If the task affects responsive layout, resize to mobile viewport (375px) and check
iOS projects (simulator): If instructed to use iOS Simulator in the pipeline prompt:
  1. Build for simulator: 
    xcodebuild -scheme {Name} -sdk iphonesimulator build
  2. Install on booted simulator: 
    xcrun simctl install booted {app-path}
  3. Launch and take screenshot: 
    xcrun simctl io booted screenshot /tmp/sim-screenshot.png
  4. Check simulator logs: 
    xcrun simctl spawn booted log stream --style compact --timeout 10
Android projects (emulator): If instructed to use Android Emulator in the pipeline prompt:
  1. Build debug APK: 
    ./gradlew assembleDebug
  2. Install: 
    adb install -r app/build/outputs/apk/debug/app-debug.apk
  3. Take screenshot: 
    adb exec-out screencap -p > /tmp/emu-screenshot.png
  4. Check logcat: 
    adb logcat '*:E' --format=time -d 2>&1 | tail -20
Graceful degradation: If browser/simulator/emulator tools are not available or fail — skip visual checks entirely. Visual testing is a bonus, never a blocker. Log that it was skipped and continue with the task.
实现完成后，如果工具可用，运行快速视觉冒烟测试：
Web项目（Playwright MCP或浏览器工具）： 如果有Playwright MCP工具或浏览器工具可用：
  1. 如果开发服务器未运行则启动（检查栈YAML中的
    dev_server.command
    ）
  2. 导航到当前任务影响的页面
  3. 检查浏览器控制台是否有错误（ hydration不匹配、未捕获异常、404错误）
  4. 截图以验证视觉输出符合预期
  5. 如果任务影响响应式布局，调整为移动端视口（375px）并检查
iOS项目（模拟器）： 如果流水线提示中要求使用iOS模拟器：
  1. 为模拟器构建：
    xcodebuild -scheme {Name} -sdk iphonesimulator build
  2. 安装到已启动的模拟器：
    xcrun simctl install booted {app-path}
  3. 启动并截图：
    xcrun simctl io booted screenshot /tmp/sim-screenshot.png
  4. 检查模拟器日志：
    xcrun simctl spawn booted log stream --style compact --timeout 10
Android项目（模拟器）： 如果流水线提示中要求使用Android模拟器：
  1. 构建调试APK：
    ./gradlew assembleDebug
  2. 安装：
    adb install -r app/build/outputs/apk/debug/app-debug.apk
  3. 截图：
    adb exec-out screencap -p > /tmp/emu-screenshot.png
  4. 检查logcat：
    adb logcat '*:E' --format=time -d 2>&1 | tail -20
**优雅降级：**如果浏览器/模拟器/模拟器工具不可用或失败 — 完全跳过视觉检查。视觉测试是附加项，绝不能成为阻塞项。记录已跳过视觉检查并继续执行任务。

6. Complete Task

6. 完成任务

Commit (following commit strategy):
bash
git add {specific files changed}
git commit -m "<type>(<scope>): <description>"
Types: 
feat
, 
fix
, 
refactor
, 
test
, 
docs
, 
chore
, 
perf
, 
style
Capture SHA after commit:
bash
git rev-parse --short HEAD
SHA annotation in plan.md. After every task commit:
  1. Mark task done: 
    [~]
    → 
    [x]
  2. Append commit SHA inline: 
    - [x] Task X.Y: description <!-- sha:abc1234 -->
Without a SHA, there's no traceability and no revert capability. If a task required multiple commits, record the last one.
提交代码（遵循提交策略）：
bash
git add {修改的特定文件}
git commit -m "<type>(<scope>): <description>"
提交类型：
feat
, 
fix
, 
refactor
, 
test
, 
docs
, 
chore
, 
perf
, 
style
提交后捕获SHA：
bash
git rev-parse --short HEAD
**在plan.md中添加SHA注释。**每次任务提交后：
  1. 标记任务完成：
    [~]
    → 
    [x]
  2. 内联追加提交SHA：
    - [x] Task X.Y: description <!-- sha:abc1234 -->
如果没有SHA，就没有可追溯性和回滚能力。如果一个任务需要多次提交，记录最后一次提交的SHA。

7. Phase Completion Check

7. 阶段完成检查

After each task, check if all tasks in current phase are 
[x]
.
If phase complete:
  1. SHA audit — scan all 
    [x]
    tasks in this phase. If any are missing 
    <!-- sha:... -->
    , capture their SHA now from git log and add it. Every 
    [x]
    task MUST have a SHA.
  2. Run verification steps listed under 
    ### Verification
    for the phase.
  3. Run full test suite.
  4. Run linter.
  5. Mark verification checkboxes in plan.md: 
    - [ ]
    → 
    - [x]
    .
  6. Commit plan.md progress: 
    git commit -m "chore(plan): complete phase {N}"
    .
  7. Capture checkpoint SHA and append to phase heading in plan.md: 
    ## Phase N: Title <!-- checkpoint:abc1234 -->
    .
  8. Report results and continue:
Phase {N} complete! <!-- checkpoint:abc1234 -->

  Tasks:  {M}/{M}
  Tests:  {pass/fail}
  Linter: {pass/fail}
  Verification:
    - [x] {check 1}
    - [x] {check 2}

  Revert this phase: git revert abc1234..HEAD
Proceed to the next phase automatically. No approval needed.
每个任务完成后，检查当前阶段的所有任务是否都标记为
[x]
。
如果阶段完成：
  1. SHA审计 — 扫描此阶段中所有
    [x]
    任务。如果任何任务缺少
    <!-- sha:... -->
    注释，现在从git log中捕获其SHA并添加。每个
    [x]
    任务必须有SHA。
  2. 运行该阶段
    ### Verification
    部分列出的验证步骤。
  3. 运行完整测试套件。
  4. 运行代码检查工具。
  5. 在plan.md中标记验证复选框：
    - [ ]
    → 
    - [x]
    。
  6. 提交plan.md的进度更新：
    git commit -m "chore(plan): complete phase {N}"
    。
  7. 捕获检查点SHA并追加到阶段标题中： 
    ## Phase N: Title <!-- checkpoint:abc1234 -->
    .
  8. 报告结果并继续：
阶段{N}完成！ <!-- checkpoint:abc1234 -->

  任务完成情况:  {M}/{M}
  测试结果:  {通过/失败}
  代码检查: {通过/失败}
  验证情况:
    - [x] {检查项1}
    - [x] {检查项2}

  回滚此阶段: git revert abc1234..HEAD
自动进入下一阶段，无需审批。

Error Handling

错误处理

Test Failure

测试失败

Tests failing after Task X.Y:
  {failure details}

1. Attempt to fix
2. Rollback task changes (git checkout)
3. Pause for manual intervention
Ask via AskUserQuestion. Do NOT automatically continue past failures.
任务X.Y完成后测试失败:
  {失败详情}

1. 尝试修复
2. 回滚任务变更（git checkout）
3. 暂停等待人工干预
通过AskUserQuestion询问用户。请勿自动跳过失败继续执行。

Track Completion

跟踪任务完成

When all phases and tasks are 
[x]
:
当所有阶段和任务都标记为
[x]
：

1. Final Verification

1. 最终验证

  • Run local build — must pass before deploy:
    • Next.js: 
      pnpm build
    • Python: 
      uv build
      or 
      uv run python -m py_compile src/**/*.py
    • Astro: 
      pnpm build
    • Cloudflare: 
      pnpm build
    • iOS: 
      xcodebuild -scheme {Name} -sdk iphonesimulator build
    • Android: 
      ./gradlew assembleDebug
  • Run full test suite.
  • Run linter + type-checker.
  • Visual smoke test (if tools available):
    • Web: start dev server, navigate to main page, check console for errors, take screenshot
    • iOS: build + install on simulator, launch, take screenshot, check logs
    • Android: build APK + install on emulator, launch, take screenshot, check logcat
    • Skip if tools unavailable — not a blocker for completion
  • Check acceptance criteria from spec.md.
  • 运行本地构建 — 部署前必须通过：
    • Next.js: 
      pnpm build
    • Python: 
      uv build
      或 
      uv run python -m py_compile src/**/*.py
    • Astro: 
      pnpm build
    • Cloudflare: 
      pnpm build
    • iOS: 
      xcodebuild -scheme {Name} -sdk iphonesimulator build
    • Android: 
      ./gradlew assembleDebug
  • 运行完整测试套件。
  • 运行代码检查工具+类型检查器。
  • 视觉冒烟测试（如果工具可用）：
    • Web: 启动开发服务器，导航到主页面，检查控制台是否有错误，截图
    • iOS: 构建+安装到模拟器，启动，截图，检查日志
    • Android: 构建APK+安装到模拟器，启动，截图，检查logcat
    • 如果工具不可用则跳过 — 不是完成任务的阻塞项
  • 检查spec.md中的验收标准。

2. Update plan.md header

2. 更新plan.md头部

Change 
**Status:** [ ] Not Started
→ 
**Status:** [x] Complete
at the top of plan.md.
将plan.md顶部的
**Status:** [ ] Not Started
改为
**Status:** [x] Complete
。

3. Signal completion

3. 标记完成

Output pipeline signal ONLY if pipeline state directory (
.solo/states/
) exists:
<solo:done/>
Do NOT repeat the signal tag elsewhere in the response. One occurrence only.
仅当流水线状态目录（
.solo/states/
）存在时，输出流水线信号：
<solo:done/>
**请勿在响应的其他位置重复此信号标签。**仅出现一次。

4. Summary

4. 摘要

Track complete: {title} ({trackId})

  Phases: {N}/{N}
  Tasks:  {M}/{M}
  Tests:  All passing

  Phase checkpoints:
    Phase 1: abc1234
    Phase 2: def5678
    Phase 3: ghi9012

  Revert entire track: git revert abc1234..HEAD

Next:
  /build {next-track-id}  — continue with next track
  /plan "next feature"    — plan something new
跟踪任务完成: {标题} ({trackId})

  阶段完成情况: {N}/{N}
  任务完成情况:  {M}/{M}
  测试结果:  全部通过

  阶段检查点:
    阶段1: abc1234
    阶段2: def5678
    阶段3: ghi9012

  回滚整个跟踪任务: git revert abc1234..HEAD
后续操作建议: /build {next-track-id} — 继续执行下一个跟踪任务 /plan "next feature" — 规划新功能

Reverting Work

回滚工作

SHA comments in plan.md enable surgical reverts:
Revert a single task:
bash
undefined
plan.md中的SHA注释支持精准回滚：
回滚单个任务:
bash
undefined

Find SHA from plan.md: - [x] Task 2.3: ... <!-- sha:abc1234 -->

从plan.md中查找SHA: - [x] Task 2.3: ... <!-- sha:abc1234 -->

git revert abc1234
Then update plan.md: `[x]` → `[ ]` for that task.

**Revert an entire phase:**
```bash
git revert abc1234
然后更新plan.md: 将该任务的`[x]`改回`[ ]`。

**回滚整个阶段:**
```bash

Find checkpoint from phase heading: ## Phase 2: ... <!-- checkpoint:def5678 -->

从阶段标题中查找检查点SHA: ## Phase 2: ... <!-- checkpoint:def5678 -->

Find previous checkpoint: ## Phase 1: ... <!-- checkpoint:abc1234 -->

查找上一阶段的检查点SHA: ## Phase 1: ... <!-- checkpoint:abc1234 -->

git revert abc1234..def5678
Then update plan.md: all tasks in that phase `[x]` → `[ ]`.

**Never use `git reset --hard`** — always `git revert` to preserve history.
git revert abc1234..def5678
然后更新plan.md: 将该阶段的所有任务从`[x]`改回`[ ]`。

**绝不要使用`git reset --hard`** — 始终使用`git revert`以保留历史记录。

Progress Tracking (TodoWrite)

进度跟踪（TodoWrite）

At the start of a build session, create a task list from plan.md so progress is visible:
  1. On session start: Read plan.md, find all incomplete tasks (
    [ ]
    and 
    [~]
    ).
  2. Create TaskCreate for each phase with its tasks as description.
  3. TaskUpdate as you work: 
    in_progress
    when starting a task, 
    completed
    when done.
  4. This gives the user (and pipeline) real-time visibility into progress.
在构建会话开始时，从plan.md创建任务列表，以便实时查看进度：
  1. 会话开始时: 读取plan.md，找到所有未完成的任务（
    [ ]
    和
    [~]
    ）。
  2. 为每个阶段创建TaskCreate，将该阶段的任务作为描述。
  3. 工作时更新TaskUpdate: 启动任务时标记为
    in_progress
    ，完成时标记为
    completed
    。
  4. 这能让用户（和流水线）实时查看进度。

Rationalizations Catalog

错误想法对照表

These thoughts mean STOP — you're about to cut corners:
ThoughtReality
"This is too simple to test"Simple code breaks too. Write the test.
"I'll add tests later"Tests written after pass immediately — they prove nothing.
"I already tested it manually"Manual tests don't persist. Automated tests do.
"The test framework isn't set up"Set it up. That's part of the task.
"This is just a config change"Config changes break builds. Verify.
"I'm confident this works"Confidence without evidence is guessing. Run the command.
"Let me just try changing X"Stop. Investigate root cause first.
"Tests are passing, ship it"Tests passing ≠ acceptance criteria met. Check spec.md.
"I'll fix the lint later"Fix it now. Tech debt compounds.
"It works on my machine"Run the build. Verify in the actual environment.
如果你有以下想法，请立即停止 — 你正在试图走捷径:
想法实际情况
"这个功能太简单了，不需要测试"简单代码也会出错。请编写测试。
"我之后再补测试"事后编写的测试会直接通过 — 它们无法证明任何问题。
"我已经手动测试过了"手动测试无法持久保存。自动化测试可以。
"测试框架还没搭建好"搭建测试框架是任务的一部分。
"这只是个配置变更"配置变更会破坏构建。请验证。
"我确信这个功能能正常工作"没有证据的自信只是猜测。请运行命令验证。
"我试试修改X看看"停止。先调查根本原因。
"测试通过了，可以发布了"测试通过≠满足验收标准。请检查spec.md。
"我之后再修复代码检查问题"现在就修复。技术债务会不断累积。
"在我机器上能正常运行"运行构建命令，在实际环境中验证。

Critical Rules

核心规则

  1. Run phase checkpoints — verify tests + linter pass before moving to next phase.
  2. STOP on failure — do not continue past test failures or errors.
  3. Keep plan.md updated — task status must reflect actual progress at all times.
  4. Commit after each task — atomic commits with conventional format.
  5. Research before coding — 30 seconds of search saves 30 minutes of reimplementation.
  6. One task at a time — finish current task before starting next.
  7. Keep test output concise — when running tests, pipe through 
    head -50
    or use 
    --reporter=dot
    / 
    -q
    flag. Thousands of test lines pollute context. Only show failures in detail.
  8. Verify before claiming done — run the actual command, read the full output, confirm success BEFORE marking a task complete. Never say "should work now".
  1. 运行阶段检查点 — 进入下一阶段前，必须验证测试+代码检查通过。
  2. 失败即停止 — 不要跳过测试失败或错误继续执行。
  3. 保持plan.md更新 — 任务状态必须始终反映实际进度。
  4. 每个任务完成后提交 — 原子提交，采用约定式提交格式。
  5. 编码前先调研 — 30秒的搜索能节省30分钟的重复实现。
  6. 一次处理一个任务 — 完成当前任务后再开始下一个。
  7. 精简测试输出 — 运行测试时，通过
    head -50
    或使用
    --reporter=dot
    / 
    -q
    参数过滤输出。数千行测试输出会污染上下文。仅详细显示失败内容。
  8. 验证后再标记完成 — 运行实际命令，读取完整输出，确认成功后再标记任务完成。绝不要说“应该能正常工作了”。

Common Issues

常见问题

"No plans found"

"未找到计划"

Cause: No 
plan.md
exists in 
docs/plan/
. Fix: Run 
/plan "your feature"
first to create a track.
原因: 
docs/plan/
目录下不存在
plan.md
文件。 解决方法: 先运行
/plan "your feature"
创建跟踪任务。

Tests failing after task

任务完成后测试失败

Cause: Implementation broke existing functionality. Fix: Use the error handling flow — attempt fix, rollback if needed, pause for user input. Never skip failing tests.
原因: 实现代码破坏了原有功能。 解决方法: 使用错误处理流程 — 尝试修复，必要时回滚，暂停等待用户输入。绝不要跳过失败的测试。

Phase checkpoint failed

阶段检查点失败

Cause: Tests or linter failed at phase boundary. Fix: Fix failures before proceeding. Re-run verification for that phase.
原因: 在阶段边界处测试或代码检查失败。 解决方法: 修复失败后再继续。重新运行该阶段的验证步骤。