---
slug: solo-build
name: solo-build
version: "2.2.1"
displayName: Build
summary: "用TDD工作流执行实施计划任务,自动提交与阶段门禁"
  gates. Use when user ...
license: MIT
description: |-
  Execute implementation plan tasks with TDD workflow, auto-commit, and
  phase gates。Use when user。Use when 需要项目管理、任务规划、进度跟踪、团队协作时使用。不适用于实际人员绩效评估。适用于独立开发者、企业团队和自动化工作流场景。
tags: '[''Automation'']'
tools:
  - read
  - exec
# Build
pricing_tier: "L4"
pricing_model: "monthly"
suggested_price: 99.9
---

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`

## MCP 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 MCP 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 MCP available)
```text
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. `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).

## Resumption
If a task is marked `[~]` in plan.md:

```text
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 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.

### 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):**

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

### 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
```text
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:

```text
<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:

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

## 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(Claude Code / Cursor / Codex / Gemini CLI等)
- **操作系统**: Windows / macOS / Linux

### 依赖说明
| 依赖项 | 类型 | 是否必需 | 获取方式 |
|:-------|:-----|:---------|:---------|
| LLM API | API | 必需 | 由Agent内置LLM提供 |

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

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

## 核心能力
```text
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环境无法使用
- 复杂场景可能需要人工辅助判断
- 性能取决于底层模型能力