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.

When to use

After /plan has created a track with spec.md + plan.md. This is the execution engine.

Pipeline: /plan → /build → /deploy → /review

协议 Tools (use if available)

• 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 协议 tools are not available, fall back to Glob + Grep + Read.

Pre-flight Checks

详细内容已移至 references/detail.md

Track Selection

If $ARGUMENTS contains a track ID:

• Validate: {plan_root}/{argument}/plan.md exists (check docs/plan/).
• If not found: search docs/plan/*/plan.md for partial matches, suggest corrections.

If $ARGUMENTS contains --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."

Context Loading

Step 1 — Architecture overview (if 协议 available)

codegraph_explain(project="{project name}")

Returns: stack, languages, directory layers, key patterns, top dependencies, hub files — one call instead of exploring the tree manually.

Step 2 — Essential docs (parallel reads)

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. .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).

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.

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:

1. Find Next Task

Parse plan.md for first line matching - [ ] Task X.Y: (or - [~] Task X.Y: if resuming).

2. Start Task

• Update plan.md: [ ] → [~] for current task.
• Announce: "Starting Task X.Y: {description}"

3. Research (smart, before coding)

Do NOT grep the entire project or read all source files. Load only what this specific task needs.

If 协议 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 协议 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.

Python-Specific Quality Tools

详细内容已移至 references/detail.md

JS/TS-Specific Quality Tools

详细内容已移至 references/detail.md

iOS/Android-Specific Quality Tools

When the project uses a mobile stack:

iOS (Swift):

swiftlint lint --strict
swift-format format --in-place --recursive Sources/

Android (Kotlin):

./gradlew detekt
./gradlew ktlintCheck

Both use lefthook for pre-commit hooks (language-agnostic, no Node.js required).

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

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)

• 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.

5.5. Integration Testing (CLI-First)

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.

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

详细内容已移至 references/detail.md

6. Complete Task

详细内容已移至 references/detail.md

7. Phase Completion Check

详细内容已移至 references/detail.md

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.

Track Completion

When all phases and tasks are [x]:

1. Final Verification

• 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.

2. Update plan.md header

Change **Status:** [ ] Not Started → **Status:** [x] Complete at the top of plan.md.

3. Signal completion

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.

4. Summary

详细代码示例已移至 references/detail.md

Reverting Work

详细内容已移至 references/detail.md

Progress Tracking (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.

Rationalizations Catalog

These thoughts mean STOP — you're about to cut corners:

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".

Common Issues

"No plans found"

Cause: No plan.md exists in docs/plan/. Fix: Run /plan "your feature" first to create a track.

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.

依赖说明

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent( Code / Cursor / Codex / CLI等)
• 操作系统: Windows / macOS / Linux

依赖说明

API Key 配置

• 本Skill基于Markdown指令,无需额外API Key(除内容中明确标注的外部API)

可用性分类

• 分类: MD+execute(纯Markdown指令,部分功能需要exec命令行执行能力)
• 说明: 基于Markdown的AI Skill,通过自然语言指令驱动Agent执行任务

核心能力

codegraph_explain(project="{project name}")

Returns: stack, languages, directory layers, key patterns, top dependencies, hub files — one call instead of exploring the tree manually.

适用场景

不适用于：需要人工判断的复杂决策场景

使用流程

1. 确认运行环境满足依赖说明中的要求
2. 根据适用场景选择合适的使用方式
3. 执行操作并检查输出结果
4. 如遇错误，参考错误处理章节

示例

示例1：基础用法

输入: 用户请求
处理: 根据使用流程执行
输出: 处理结果

错误处理

常见问题

Q1: 如何开始使用Build？

A: 请先阅读使用流程章节，确认环境满足依赖说明中的要求。

Q2: 遇到错误怎么办？

A: 请参考错误处理章节，按照表格中的处理方式操作。

Q3: Build有什么限制？

A: 请参考已知限制章节了解具体限制。

已知限制

• 需要LLM支持，无LLM环境无法使用
• 复杂场景可能需要人工辅助判断
• 性能取决于底层模型能力