Auto Build

Auto-Build: Autonomous Multi-Agent Build Pipeline

Autonomous pipeline that plans, builds, and validates software. User describes a task, answers a few questions, then agents handle everything: context discovery, spec writing, planning, implementation, and QA -- all in an isolated git worktree.

Trigger on: "auto-build", "auto build", "build this autonomously", "autonomous build".

Prerequisites

Before starting, verify ALL of the following:

1. Git repo initialized -- run git rev-parse --git-dir and confirm it succeeds
2. At least one commit -- run git log --oneline -1 (worktrees require commit history)
3. Clean working tree -- run git status --porcelain. Warn user if there are uncommitted changes (worktree creation still works, but it's risky)
4. Identify main branch -- run git branch --show-current to get the base branch name

If any prerequisite fails, tell the user what's wrong and stop.

Directory Structure

All auto-build artifacts live in .auto-build/ (gitignored). Create it if it doesn't exist:

.auto-build/
├── specs/
│   └── XXX-slug/
│       ├── requirements.json
│       ├── context.json
│       ├── spec.md
│       ├── implementation_plan.json
│       ├── qa_report.md
│       └── QA_FIX_REQUEST.md
└── worktrees/
    └── XXX-slug/              # git worktree checkout

Determine Next Spec Number

ls .auto-build/specs/ 2>/dev/null | sort -n | tail -1

If empty, start at 001. Otherwise increment the highest number. Format: 3-digit zero-padded (001, 002, ...).

Pipeline Overview

Stage 1: Spec Gathering (Interactive)

This is the ONLY interactive stage. You run this directly (not via Task subagent).

Read the prompt file at .cursor/skills/auto-build/prompts/spec-gatherer.md and follow its instructions to gather requirements from the user.

After gathering, create the spec directory and save requirements.json:

mkdir -p .auto-build/specs/XXX-slug

Write requirements.json to .auto-build/specs/XXX-slug/requirements.json.

Gate: Do NOT proceed until requirements.json exists and is valid JSON.

Stage 2: Workspace Setup

Ensure .auto-build/ is gitignored (idempotent):

grep -qxF '.auto-build/' .gitignore 2>/dev/null || echo '.auto-build/' >> .gitignore

Create an isolated workspace for this build:

# Create the branch (from current HEAD)
BRANCH_NAME="auto-build/XXX-slug"
git branch "$BRANCH_NAME"

# Create worktree
mkdir -p .auto-build/worktrees
git worktree add ".auto-build/worktrees/XXX-slug" "$BRANCH_NAME"

Verify the worktree was created:

git worktree list
ls .auto-build/worktrees/XXX-slug

Store key paths for subsequent stages:

• SPEC_DIR = absolute path to .auto-build/specs/XXX-slug
• WORKTREE_DIR = absolute path to .auto-build/worktrees/XXX-slug
• BASE_BRANCH = the branch you were on before creating the worktree
• BUILD_BRANCH = auto-build/XXX-slug

Tell the user:

Workspace ready. Building in isolated worktree on branch auto-build/XXX-slug. Your {BASE_BRANCH} branch is untouched. Starting autonomous pipeline...

Stage 3: Context Discovery (Autonomous)

1. Read the prompt file: .cursor/skills/auto-build/prompts/context-discovery.md

2. Spawn a Task subagent with:

   • description: "Context discovery for spec XXX"
   • subagent_type: "generalPurpose"
   • prompt: The contents of context-discovery.md, prepended with:

     CONTEXT FOR THIS RUN:
     - Project root: {absolute path to main repo}
     - Spec directory: {SPEC_DIR}
     - Read {SPEC_DIR}/requirements.json first to understand the task.
     - Write your output to {SPEC_DIR}/context.json
     

3. After the subagent returns, verify context.json exists:

   test -f {SPEC_DIR}/context.json && echo "OK" || echo "MISSING"
   

Gate: Do NOT proceed if context.json is missing. Retry once, then fail with error.

Stage 4: Spec Writing (Autonomous)

1. Read the prompt file: .cursor/skills/auto-build/prompts/spec-writer.md

2. Spawn a Task subagent with:

   • description: "Spec writing for spec XXX"
   • subagent_type: "generalPurpose"
   • prompt: The contents of spec-writer.md, prepended with:

     CONTEXT FOR THIS RUN:
     - Spec directory: {SPEC_DIR}
     - Read these input files:
       1. {SPEC_DIR}/requirements.json
       2. {SPEC_DIR}/context.json
     - Write your output to {SPEC_DIR}/spec.md
     

3. Verify spec.md exists and has content (at least 20 lines).

Gate: Do NOT proceed if spec.md is missing or too short. Retry once.

Stage 5: Planning (Autonomous)

1. Read the prompt file: .cursor/skills/auto-build/prompts/planner.md

2. Spawn a Task subagent with:

   • description: "Planning for spec XXX"
   • subagent_type: "generalPurpose"
   • prompt: The contents of planner.md, prepended with:

     CONTEXT FOR THIS RUN:
     - Project root: {absolute path to main repo}
     - Spec directory: {SPEC_DIR}
     - Worktree directory: {WORKTREE_DIR}
     - Read these input files:
       1. {SPEC_DIR}/spec.md
       2. {SPEC_DIR}/context.json
     - Write your output to {SPEC_DIR}/implementation_plan.json
     - Do NOT implement any code. Planning only.
     

3. Verify implementation_plan.json exists and is valid JSON.

4. Read it and report to the user:

   Planning complete. {N} phases, {M} subtasks across {services}. Starting implementation...

Gate: Do NOT proceed if implementation_plan.json is missing or invalid.

Stage 6: Implementation (Autonomous)

Read {SPEC_DIR}/implementation_plan.json and extract the phases.

For EACH phase, in dependency order:

1. Check depends_on -- skip if dependencies aren't complete

2. Read the prompt file: .cursor/skills/auto-build/prompts/coder.md

3. Spawn a Task subagent with:

   • description: "Implement phase: {phase_name}"
   • subagent_type: "generalPurpose"
   • prompt: The contents of coder.md, prepended with:

     CONTEXT FOR THIS RUN:
     - Worktree directory: {WORKTREE_DIR} (make ALL code changes here)
     - Spec directory: {SPEC_DIR}
     - Base branch: {BASE_BRANCH}
     - Implementation plan: {SPEC_DIR}/implementation_plan.json
     
     YOUR ASSIGNED PHASE:
     Phase ID: {phase.id}
     Phase name: {phase.name}
     Subtasks: {JSON of phase.subtasks}
     
     After completing each subtask:
     1. Verify it works (run the verification command)
     2. Commit the changes in the worktree with a descriptive message
     3. Report back what you completed and any issues
     
     IMPORTANT: Work ONLY in {WORKTREE_DIR}. Do NOT modify the main repo.
     

   • working_directory: The worktree directory path (WORKTREE_DIR). CRITICAL: This is how Task subagents operate in the isolated worktree.

4. After each phase subagent returns, update the phase status in implementation_plan.json

5. Report progress to user: > Phase {N}/{total} complete: {phase_name}

Parallel Phases

If two phases have the same depends_on and parallel_safe: true, you MAY spawn them concurrently (up to 2 parallel Task subagents). Otherwise, run sequentially.

Gate: All phases must be complete before proceeding to QA.

Stage 7: QA Review (Autonomous Loop)

This stage loops up to 3 times: Review → Fix → Review → Fix → Review.

7a: QA Review

1. Read the prompt file: .cursor/skills/auto-build/prompts/qa-reviewer.md

2. Spawn a Task subagent with:

   • description: "QA review for spec XXX"
   • subagent_type: "generalPurpose"
   • prompt: The contents of qa-reviewer.md, prepended with:

     CONTEXT FOR THIS RUN:
     - Worktree directory: {WORKTREE_DIR}
     - Spec directory: {SPEC_DIR}
     - Base branch: {BASE_BRANCH}
     - Build branch: {BUILD_BRANCH}
     
     Read these files:
     1. {SPEC_DIR}/spec.md (requirements and acceptance criteria)
     2. {SPEC_DIR}/implementation_plan.json (what was planned)
     
     Run `git diff {BASE_BRANCH}...HEAD` in the worktree to see all changes.
     Run any test commands you find in the codebase.
     
     Write your report to {SPEC_DIR}/qa_report.md
     If rejecting, also write {SPEC_DIR}/QA_FIX_REQUEST.md
     
     Return EXACTLY one of these as your final line:
     VERDICT: APPROVED
     VERDICT: REJECTED
     

   • working_directory: WORKTREE_DIR

3. Check the verdict in the subagent's response.

7b: If REJECTED

1. Read {SPEC_DIR}/QA_FIX_REQUEST.md

2. Read the coder prompt again: .cursor/skills/auto-build/prompts/coder.md

3. Spawn a Task subagent with:

   • description: "QA fixes for spec XXX (attempt N)"
   • subagent_type: "generalPurpose"
   • prompt: The coder prompt, prepended with:

     CONTEXT FOR THIS RUN:
     - Worktree directory: {WORKTREE_DIR}
     - Spec directory: {SPEC_DIR}
     
     You are fixing QA issues. Read the fix request:
     {SPEC_DIR}/QA_FIX_REQUEST.md
     
     Fix ALL critical and major issues listed.
     Commit each fix with message: "fix: {description} (qa-requested)"
     Work ONLY in {WORKTREE_DIR}.
     

   • working_directory: WORKTREE_DIR

4. After fixes, loop back to 7a (re-run QA review).

7c: If APPROVED or Max Iterations Reached

If approved, proceed to Stage 8. If max iterations (3) reached without approval, tell the user:

QA could not fully approve after 3 attempts. Review the report at {SPEC_DIR}/qa_report.md. The worktree is at {WORKTREE_DIR} on branch {BUILD_BRANCH} for manual review.

Stage 8: Completion

Show the user a summary:

BUILD COMPLETE

Spec:     XXX-slug
Branch:   auto-build/XXX-slug
Worktree: .auto-build/worktrees/XXX-slug
QA:       APPROVED / REJECTED (after N attempts)

Changes:  {number of files changed, insertions, deletions from git diff --stat}
Commits:  {number of commits on build branch}

Then ask:

Would you like me to merge auto-build/XXX-slug into {BASE_BRANCH}?

Options:

1. Merge -- merge branch and clean up worktree
2. Review first -- I'll show you the full diff
3. Leave it -- keep the worktree for manual review

If Merge

cd {MAIN_REPO}
git merge auto-build/XXX-slug --no-ff -m "feat: {task description} (auto-build XXX)"
git worktree remove .auto-build/worktrees/XXX-slug
git branch -d auto-build/XXX-slug

If Review First

cd {WORKTREE_DIR}
git diff {BASE_BRANCH}...HEAD --stat
git log {BASE_BRANCH}..HEAD --oneline

Show the output, then ask again about merging.

If Leave It

Tell the user:

Worktree preserved at .auto-build/worktrees/XXX-slug on branch auto-build/XXX-slug. To merge later: git merge auto-build/XXX-slug To discard: git worktree remove .auto-build/worktrees/XXX-slug && git branch -D auto-build/XXX-slug

Error Handling

Stage Failure

If any autonomous stage fails (subagent error, missing output file after retry):

1. Tell the user which stage failed and why
2. Preserve the worktree and all artifacts
3. Suggest: "You can inspect the artifacts in {SPEC_DIR}/ and the worktree at {WORKTREE_DIR}."

Worktree Cleanup

If the user wants to abort at any point:

git worktree remove .auto-build/worktrees/XXX-slug --force
git branch -D auto-build/XXX-slug
rm -rf .auto-build/specs/XXX-slug

Progress Communication

At each stage transition, update the user with a brief status line:

• [1/8] Gathering requirements... (interactive)
• [2/8] Setting up isolated workspace...
• [3/8] Scanning codebase for context...
• [4/8] Writing specification...
• [5/8] Creating implementation plan...
• [6/8] Implementing phase N/M: {name}...
• [7/8] Running QA review...
• [8/8] Build complete.

This keeps the user informed without being verbose.