solo-build

/build

此技能是自包含的——请遵循以下任务循环、TDD 规则和完成流程，不要委托给外部构建／执行技能（superpowers 等）。

根据实施计划执行任务。查找 plan.md（位于 docs/plan/），选取下一个未勾选的任务，使用 TDD 工作流完成实现、提交，并更新进度。

实时上下文

• 分支：!git branch --show-current 2>/dev/null
• 状态：!git status --short 2>/dev/null | head -10
• 最近提交：!git log --oneline -3 2>/dev/null

适用场景

在 /plan 创建了包含 spec.md 和 plan.md 的跟踪项后使用。这是执行引擎。

流程：/plan → /build → /deploy → /review

MCP 工具（如可用）

• session_search(query) — 查找以往类似问题的解决方法
• project_code_search(query, project) — 跨项目查找可复用代码
• codegraph_query(query) — 检查文件依赖、导入和调用方

如果 MCP 工具不可用，请改用 Glob + Grep + Read。

准备检查

1. 检测上下文 — 查找计划文件的位置：

   • 检查 docs/plan/*/plan.md — 标准位置
   • 使用实际存在的路径。
   • 不要搜索 conductor/ 或任何其他目录——只搜索 docs/plan/。

2. 从 docs/workflow.md 加载工作流配置（如果存在）：

   • TDD 严格程度（strict / moderate / none）
   • 提交策略（conventional commits 格式）
   • 验证检查点规则
   • 集成测试部分——如果存在，完成涉及所列路径的任务后，运行指定的 CLI 命令 如果缺少 docs/workflow.md：使用默认值（moderate TDD、conventional commits）。

3. 确认已安装 Git hooks：

   读取栈 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 + formatter）

   然后确认 hook 系统已启用：

   # 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——如果 hooks 执行失败，请修复问题后重新提交。

选择跟踪项

如果 $ARGUMENTS 包含跟踪项 ID：

• 验证：{plan_root}/{argument}/plan.md 存在（检查 docs/plan/）。
• 如果未找到：在 docs/plan/*/plan.md 中搜索部分匹配项，并建议修正。

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

• 直接跳转到当前跟踪项中的该任务。

如果没有参数：

1. 在 docs/plan/ 中搜索 plan.md 文件。
2. 读取每个 plan.md，查找包含未完成任务的跟踪项。
3. 如果有多个，通过 AskUserQuestion 询问。
4. 如果没有跟踪项：No plans found. Run /plan first.

加载上下文

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

codegraph_explain(project="{project name}")

返回：技术栈、语言、目录层次、关键模式、主要依赖项和枢纽文件。

步骤 1.5——获取 RepoMap（如 MCP 可用）

codegraph_repomap(project="{project name}")

返回顶层文件及其导出类／函数的 YAML 映射。使用它来了解全局结构。

步骤 2 — 必要文档（并行读取）

1. docs/plan/{trackId}/plan.md — 任务列表（必读）。先阅读 ## Context Handoff 部分——其中简要总结了意图、关键文件、决策和风险。这是你了解情况的主要依据。
2. docs/plan/{trackId}/spec.md — 验收标准（必读）
3. docs/workflow.md — TDD 政策、提交策略（如果存在）
4. CLAUDE.md — 架构、该做与不该做的事项
5. .solo/pipelines/progress.md — 之前迭代的运行文档（如果存在，且与特定流水线相关）。其中包含之前流水线会话完成的工作：已完成的阶段、提交 SHA、最后的输出行。利用这些信息，避免重复已完成的工作。

此阶段不要读取源代码文件。 源文件会在执行循环中按任务加载（见下方步骤 3）。

恢复执行

如果 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

通过 AskUserQuestion 提问，然后继续。

上下文工程规则

阅读 references/context-engineering.md，了解关于观察屏蔽、注意力定位和计划复述的完整规则。要点：

• 观察屏蔽： 大型输出（>50 行）→ 写入 scratch/，仅保留 5-10 行摘要
• 注意力定位： 错误放在开头，历史放在中间，后续步骤放在结尾
• 计划复述： 每项任务开始时重新阅读 plan.md，防止偏离计划

任务执行循环

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. 查找下一个任务

解析 plan.md，查找首个匹配 - [ ] Task X.Y: 的行（如果是恢复执行，则查找 - [~] Task X.Y:）。

2. 开始任务

• 更新 plan.md：将当前任务的 [ ] 改为 [~]。
• 宣布："开始任务 X.Y：{description}"

3. 调研（编码前，按需进行）

不要检索整个项目或读取所有源文件。 只加载此任务所需的内容。

如果 MCP 可用（优先）：

1. project_code_search(query="{task keywords}", project="{name}") — 在项目中查找相关代码。只阅读排名靠前的 2-3 个结果。
2. session_search("{task keywords}") — 检查你之前是否解决过此问题。
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" .。这会无谓地将数百行内容载入上下文。

特定平台的质量工具

完整的各技术栈命令请参阅 references/quality-tools.md。快速参考：

技术栈	Lint	格式化	类型检查	提交前检查
Python	uv run ruff check --fix .	uv run ruff format .	uv run ty check .	uv run pre-commit run --all-files
JS/TS	pnpm lint --fix	pnpm format	pnpm tsc --noEmit	husky + lint-staged
iOS	swiftlint lint --strict	swift-format	—	lefthook
Android	./gradlew detekt	./gradlew ktlintCheck	—	lefthook

每完成一项任务的实现后、执行 git commit 前运行这些检查。如果有任何检查失败，先修复再继续。

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

**先确认测试边界：**说清楚本任务的测试将观察哪个公共接口，并在编写测试前与用户确认。未经确认的边界不得编写测试。

红 — 编写失败的测试：

• 为任务功能创建或更新测试文件。
• 运行测试，确认测试失败。从未失败过的测试无法证明任何问题。

绿 — 实现：

• 编写使测试通过的最少代码。
• 运行测试，确认测试通过。

重构：

• 在测试保持通过的前提下清理代码。
• 最后再运行一次测试。

一个测试 → 一个实现 → 重复（垂直切片）。先写完所有测试再写完所有实现，验证的是想象出来的行为，而非真实行为。

在功能的第一个测试之前阅读 references/tdd-seams.md——其中介绍了测试边界的位置、垂直切片与水平切片，以及测试说谎的四种方式（与实现耦合、旁路、同义反复、不敏感）。

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

• 直接实现任务。
• 运行现有测试，确认没有引入问题。
• 对于“moderate”：为业务逻辑和 API 路由编写测试；UI/配置则跳过。

5.5. 集成测试（CLI 优先）

如果任务涉及核心业务逻辑（管线、算法、Agent 工具），运行 make integration（或 docs/workflow.md 中的集成命令）。CLI 执行的代码路径与 UI 相同，且无需浏览器。如果 make integration 失败，先修复再提交。

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

实现完成后，如果有可用工具，快速进行视觉冒烟测试：

Web 项目（Playwright MCP 或浏览器工具）： 如果有 Playwright MCP 工具或浏览器工具可用：

1. 如果开发服务器尚未运行，则启动它（检查栈 YAML 中的 dev_server.command）
2. 导航到当前任务影响的页面
3. 检查浏览器控制台是否有错误（水合不匹配、未捕获异常、404）
4. 截取屏幕截图，确认视觉输出符合预期
5. 如果任务影响响应式布局，将视口调整为移动设备尺寸（375px）并检查

iOS 项目（模拟器）： 如果管线提示词要求使用 iOS Simulator：

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 Emulator：

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. 完成任务

提交（遵循提交策略）：

git add {specific files changed}
git commit -m "<type>(<scope>): <description>"

类型：feat、fix、refactor、test、docs、chore、perf、style

提交后记录 SHA：

git rev-parse --short HEAD

在 plan.md 中标注 SHA。 每次任务提交后：

1. 将任务标记为完成：[~] → [x]
2. 在行内追加提交 SHA：- [x] Task X.Y: description

没有 SHA，就无法追踪，也无法回滚。如果一个任务需要多次提交，请记录最后一次提交。

7. 阶段完成检查

每完成一项任务，检查当前阶段中的所有任务是否都已标记为 [x]。

如果阶段已完成：

1. SHA 审计——扫描此阶段中所有标记为 [x] 的任务。如果有任何任务缺少 ``，现在从 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，并将其追加到 plan.md 中的阶段标题： ## Phase N: Title 。
8. 汇报结果并继续：

Phase {N} complete! 

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

  Revert this phase: git revert abc1234..HEAD

自动进入下一阶段，无需批准。

错误处理

测试失败

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

1. Attempt to fix
2. Rollback task changes (git checkout)
3. Pause for manual intervention

通过 AskUserQuestion 提问。失败后不得自动继续。

跟踪完成情况

当所有阶段和任务都标记为 [x] 时：

1. 最终验证

• 运行本地构建——部署前必须通过：
  • 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 中的验收标准进行检查：
  • 对于每一项 - [ ] 标准：验证其是否满足（搜索代码，或运行指定命令）。
  • 如果标准中包含可运行的命令（make task、cargo test、基准测试、passes N/N）→ 运行该命令。 不要以“无法验证”为由跳过。
  • 将 spec.md 中已验证标准的复选框更新为：- [ ] → - [x]。
  • 如果有任何标准未通过 → 不要将计划标记为完成。修复问题或记录失败。
  • 提交 spec 更新：git add docs/plan/*/spec.md && git commit -m "docs: update spec checkboxes (verified by build)"

构建失败升级处理

如果相同的构建/测试错误连续出现 3 次或以上，请停止重试。改为：

1. 清楚地输出错误消息。
2. 建议修复方案（例如 cargo clean、rm -rf node_modules、检查磁盘空间）。
3. 输出 <solo:redo/>，交由审核处理。 不要在相同失败上浪费迭代次数。

2. 更新 plan.md 标题

在 plan.md 顶部将 **Status:** [ ] Not Started 改为 **Status:** [x] Complete。

3. 发出完成信号

仅当流水线状态目录（.solo/states/）存在时，才输出流水线信号：

<solo:done/>

请勿在回复中的其他位置重复信号标签。 只出现一次。

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

回滚工作

plan.md 中的 SHA 注释支持精确回滚：

回滚单项任务：

# Find SHA from plan.md: - [x] Task 2.3: ... 
git revert abc1234

然后更新 plan.md：将该任务的 [x] 改为 [ ]。

回滚整个阶段：

# Find checkpoint from phase heading: ## Phase 2: ... 
# Find previous checkpoint: ## Phase 1: ... 
git revert abc1234..def5678

然后更新 plan.md：将该阶段所有任务的 [x] 改为 [ ]。

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

进度跟踪（TodoWrite）

在构建会话开始时，根据 plan.md 创建任务列表，让进度一目了然：

1. 会话开始时： 阅读 plan.md，查找所有未完成的任务（[ ] 和 [~]）。
2. 为每个阶段创建一个 TaskCreate，并将该阶段的任务作为描述。
3. 工作期间使用 TaskUpdate 更新状态：开始任务时设为 in_progress，完成后设为 completed。
4. 这样用户（以及流水线）就能实时了解进度。

合理化借口目录

出现以下想法时，立即停下——你正准备走捷径：

想法	事实
“这太简单了，不用测试”	简单的代码也会出错。编写测试。
“我稍后再补测试”	通过后才写的测试毫无证明力。
“我已经手动测试过了”	手动测试无法留存。自动化测试可以。
“测试框架还没配置好”	配置好它。这也是任务的一部分。
“这只是改一下配置”	配置改动也会导致构建失败。验证。
“我确信这样能行”	没有证据的确信就是猜测。运行命令。
“我先试着改一下 X”	停下。先调查根本原因。
“测试都通过了，交付吧”	测试通过 ≠ 满足验收标准。检查 spec.md。
“我稍后再修 lint”	现在就修。技术债会不断累积。
“在我的机器上能运行”	运行构建。在实际环境中验证。

危险信号——一旦发现自己有以下想法，立即停下：

• “这次我就跳过测试”——不行。编写测试。
• “我先留着旧代码作参考”——删除就是删除。你会改造旧代码，而不是从头编写。没有例外。
• “我遵循了规则的精神，而不是字面要求”——违反规则的字面要求，就是违背其精神。
• “这次情况不同，因为……”——并非如此。遵循流程。
• “提交前再快速改一下”——提交现有内容。范围蔓延会毁掉任务。
• “计划要求 X，但 Y 会更好”——遵循计划。如果计划确实有问题，先更新 plan.md，再开始实施。

根本原则： 如果你不会在未经检查的情况下批量删除生产数据，就不要在没有证据证明测试无必要时跳过测试。

关键规则

1. 运行阶段检查点——进入下一阶段前，确认测试和 linter 均通过。
2. 失败时立即停止——测试失败或出现错误时，不要继续。
3. 保持 plan.md 更新——任务状态必须始终反映实际进度。
4. 每完成一项任务就提交——使用符合规范的格式进行原子提交。
5. 编码前先研究——花 30 秒搜索，可以省下 30 分钟的重复实现。
6. 一次只做一项任务——完成当前任务后再开始下一项。
7. 保持测试输出简洁——运行测试时，通过 head -50 管道传递输出，或使用 --reporter=dot / -q 标志。数千行测试输出会污染上下文。仅详细显示失败信息。如果输出过多，使用观察遮蔽（写入 scratch/，仅保留摘要）。
8. 声称完成前先验证——运行实际命令，阅读完整输出，并确认成功后再将任务标记为完成。绝不要说“现在应该可以了”。
9. 复述计划——每项任务开始时重新阅读 plan.md。不要依赖对后续工作的记忆。

常见问题

“未找到计划”

原因： docs/plan/ 中不存在 plan.md。 解决方法： 先运行 /plan "your feature" 创建任务轨道。

任务完成后测试失败

原因： 实现破坏了现有功能。 解决方法： 使用错误处理流程——尝试修复，必要时回滚，并暂停以等待用户输入。绝不要跳过失败的测试。

阶段检查点未通过

原因： 阶段边界处的测试或 linter 未通过。 解决方法： 继续之前先修复问题。重新运行该阶段的验证。