solo-build

Execute implementation plan tasks with TDD workflow, auto-commit, and phase gates. Use when user says "build it", "start building", "execute plan", "implement tasks", "ship it", or references a track ID. Do NOT use for planning (use /plan) or scaffolding (use /scaffold).

# /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`

## 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

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.

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

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

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.

### JS/TS-Specific Quality Tools

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 + ts