# Auto Build

> Auto-Build: Autonomous Multi-Agent Build Pipeline

- Skill: `pablovallejo/auto-build` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add pablovallejo/auto-build`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pablovallejo/auto-build/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: PabloVallejo (https://skillmd.com/u/pablovallejo)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/pablovallejo/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

```bash
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 | Mode | Agent | Input | Output |
|-------|------|-------|-------|--------|
| 1. Spec Gathering | Interactive | Main | User conversation | `requirements.json` |
| 2. Workspace Setup | Main agent | Main | requirements.json | Branch + worktree |
| 3. Context Discovery | Autonomous | Task subagent | Codebase | `context.json` |
| 4. Spec Writing | Autonomous | Task subagent | requirements + context | `spec.md` |
| 5. Planning | Autonomous | Task subagent | spec.md + context | `implementation_plan.json` |
| 6. Implementation | Autonomous | Task subagent(s) | plan phases | Code commits |
| 7. QA Review | Autonomous | Task subagent | All artifacts + diff | `qa_report.md` |
| 8. Completion | Interactive | Main | QA report | Merge offer |

---

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

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

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

Create an isolated workspace for this build:

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

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

```bash
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:
```bash
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.