Fable Auto-Build

gistfile1.txt

---
name: auto-build
description: Orchestrate a large task on a clean feature branch by planning it with a strong model, splitting it into subtasks executed by composer-2.5 subagents in parallel, verifying each result with a gpt-5.5 reviewer that loops fixes until they pass, committing per subtask, and opening a PR. Use when the user runs /auto-build or asks to auto-build, orchestrate, or fan out a multi-step task across subagents.
disable-model-invocation: true
---

# Auto Build

Run as an **orchestrator**: plan a task, fan it out to executor subagents, and gate every result through a reviewer subagent before accepting it. You (the current agent) are the orchestrator. You do not write the implementation yourself — you plan, delegate, review, and integrate.

## Roles and models

| Role                   | Who                    | Model                                                             | How to run                        |
| ---------------------- | ---------------------- | ----------------------------------------------------------------- | --------------------------------- |
| Orchestrator (planner) | You, the current agent | `claude-fable-5-thinking-high` or `claude-opus-4-8-thinking-high` | See "Planner model" below         |
| Executor               | `Task` subagent        | `composer-2.5`                                                    | `subagent_type: "generalPurpose"` |
| Reviewer               | `Task` subagent        | `gpt-5.5-medium`                                                  | `subagent_type: "generalPurpose"` |

### Planner model

This skill assumes the orchestrator is a strong planning model. If the current session is **not** running on `claude-fable-5-thinking-high` or `claude-opus-4-8-thinking-high`, tell the user once:

> For best planning results, run /auto-build on Fable or Opus 4.8. I'll proceed on the current model.

Then continue regardless.

## Workflow

Copy this checklist into your first response and keep it updated:

```
Auto Build Progress:
- [ ] 1. Prep git: assess state, get onto a clean feature branch
- [ ] 2. Plan: break the task into subtasks
- [ ] 3. Confirm the plan with the user (unless told to proceed)
- [ ] 4. Execute subtasks via composer-2.5 subagents
- [ ] 5. Review each result via a gpt-5.5 subagent (loop until pass)
- [ ] 6. Commit each passing subtask
- [ ] 7. Integrate, verify, and open a PR
```

### 1. Prep git branch

Establish a clean, isolated feature branch **before** any planning or execution. The whole task's work should land on one branch and become one PR.

First assess state:

```bash
git rev-parse --abbrev-ref HEAD   # current branch
git status --porcelain            # empty output = clean tree
git symbolic-ref refs/remotes/origin/HEAD  # default branch (fallback: main/master)
```

Then decide based on the **decision matrix** (base it on whether the tree is dirty, not just the branch name):

| Working tree | Current branch                             | Action                                                                 |
| ------------ | ------------------------------------------ | ---------------------------------------------------------------------- |
| Clean        | A feature branch (not the default)         | Use it — assume it was created for this task.                          |
| Clean        | Default branch (`main`/`master`/`develop`) | Create a new feature branch: `git switch -c <type>/<short-task-slug>`. |
| **Dirty**    | Any                                        | **Stop and ask.** Do not guess.                                        |

On a **dirty tree**, ask the user (via `AskQuestion`) how to proceed:

- **Baseline** — the existing changes are part of this task: commit them as a starting checkpoint on the feature branch (create the branch first if on default), then continue.
- **Stash** — the changes are unrelated: `git stash push -u` them aside, then create/continue on a clean feature branch.
- **Abort** — let the user sort it out first.

Never mix unrelated uncommitted work into this task's commits or PR.

### 2. Plan

Analyze the task and split it into the smallest set of **independently verifiable** subtasks. For each subtask write:

- **Goal**: one sentence of what "done" means.
- **Scope**: files/dirs the executor may touch; call out anything off-limits.
- **Dependencies**: which other subtasks must finish first (empty = independent).
- **Acceptance criteria**: concrete checks the reviewer will use (build passes, tests pass, behavior X works).

Prefer 2–6 subtasks. If you'd produce more than ~8, group them.

Because parallel subtasks share one working tree, subtasks in the same wave **must have disjoint file scopes** — that's what makes their commits cleanly separable.

### 3. Confirm

Present the plan (subtasks + dependency order) to the user before spawning subagents, unless the user already said to proceed autonomously. Use `AskQuestion` only if a real decision is blocked; otherwise a short plan summary is enough.

### 4. Execute

Group subtasks into **waves** by dependency. Within a wave, subtasks are independent and MUST be launched **in parallel** — send one message with multiple `Task` tool calls. Run waves sequentially so dependent subtasks see prior results.

Launch each executor as:

- `subagent_type: "generalPurpose"`
- `model: "composer-2.5"`
- `run_in_background: false` (so you can await the wave), unless the user is in Multitask Mode
- `description`: 3–5 word title for the subtask

Give each executor a **self-contained** prompt — subagents do not see this conversation. Use this template:

```
You are an executor subagent. Complete ONLY the task below.

## Task
<subtask goal>

## Context
<repo path, relevant files, prior subtask outputs, conventions from AGENTS.md>

## Scope / constraints
<files you may edit; what NOT to touch; follow existing code standards; run `pnpm dlx ultracite fix` after edits>
Do NOT run any git commands (no add/commit/branch/stash/push). The orchestrator owns all git operations. Just edit files and report.

## Acceptance criteria
<the concrete checks that must pass>

## Report back
- What you changed (files + summary)
- Commands you ran and their results
- Anything you could not do and why
```

### 5. Review (loop)

After each subtask's executor returns, launch a reviewer subagent:

- `subagent_type: "generalPurpose"`
- `model: "gpt-5.5-medium"`
- `readonly: true`
- `description`: e.g. "Review <subtask>"

Reviewer prompt template:

```
You are a strict reviewer. Assess whether the task was completed correctly. Do not fix it yourself.

## Task that was assigned
<subtask goal>

## Acceptance criteria
<criteria>

## What the executor reported
<executor's report>

## Your job
Independently verify against the criteria (read the changed files, run/inspect build & tests as needed).
Return EXACTLY:
- VERDICT: PASS or FAIL
- REASONS: bullet points
- REQUIRED FIXES: (only if FAIL) specific, actionable items
```

Loop policy:

- **PASS** → accept the subtask, then commit it (step 6).
- **FAIL** → launch a **fresh** executor subagent (`composer-2.5`) with the original task plus the reviewer's REQUIRED FIXES, then re-review. Repeat up to **3 attempts** per subtask.
- After 3 failed attempts, stop that subtask and report the blocker to the user instead of looping further.

### 6. Commit the passing subtask

The **orchestrator** — never the executors — commits. Commit once per subtask, immediately after it passes review, scoped to that subtask's files so the history stays clean even when execution was parallel:

```bash
git add <subtask's paths>        # scope to this subtask only, not `git add -A`
git commit -m "<type>(<scope>): <what the subtask did>"
```

Each commit is a checkpoint: if a later subtask fails permanently, you can reset/revert to the last good commit. Follow the repo's existing commit style. Never commit files that may hold secrets (`.env`, credentials); warn the user if such a file appears.

### 7. Integrate, verify, and open a PR

Once all subtasks are committed, verify the whole works together (build/tests/lint at the repo root). Fix any integration issues via one more executor+review loop, then commit.

Then push the branch and open a PR:

```bash
git push -u origin HEAD
gh pr create --title "<task title>" --body "<summary of subtasks, review verdicts, test plan>"
```

Safe git only: no force-push, no `git config` changes, no skipping hooks. Finally, give the user a concise summary — what each subtask did, review verdicts, attempts needed, the commit list, the PR URL, and anything left open.

## Adding specialized executors later

To route certain subtask kinds to a different model, add a row to the roles table and pick the `model` per subtask when launching (e.g. `gpt-5.3-codex-high-fast` for a specific concern). Only use model slugs available to the `Task` tool; if a requested model isn't available, tell the user rather than substituting.

## Advanced: worktrees for overlapping parallel work

The default model (orchestrator owns git, one scoped commit per reviewed subtask) assumes parallel subtasks touch disjoint files. When you genuinely need parallel executors editing overlapping code, isolate each with its own git worktree + branch instead of sharing one tree: use the `best-of-n-runner` subagent (it runs a task in an isolated worktree), then have the orchestrator merge the branches in dependency order and resolve conflicts. This is heavier — only reach for it when scopes can't be made disjoint.

## Rules

- Never do a subtask's implementation yourself; always delegate to an executor subagent.
- Independent subtasks in a wave are launched in parallel (one message, multiple `Task` calls) and must have disjoint file scopes.
- **Only the orchestrator runs git.** Executors and reviewers never run git commands.
- Start on a clean feature branch; on a dirty tree, stop and ask before doing anything.
- One focused commit per subtask after it passes review; scope with `git add <paths>`, never `git add -A`.
- Every accepted subtask must have a PASS from the reviewer.
- Executor and reviewer prompts must be fully self-contained (subagents lack this conversation's context).
- Respect project standards in `AGENTS.md` and `docs/code-standards.md`; have executors run `pnpm dlx ultracite fix`.
- Safe git only: no force-push, no `git config` changes, no hook skipping; never commit secrets.