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

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:

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

   uv run ruff check --fix .
   uv run ruff format .

2. ty — type-checking (if ty in dev dependencies or stack YAML):

   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:

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

   pnpm lint --fix

2. Prettier — formatting (always):

   pnpm format

3. tsc --noEmit — type-checking (strict mode):

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

   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.

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)

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.