autobuild

What this skill does

# Autobuild: Autonomous Plan Execution Engine

Execute entire implementation plans in a single pass with zero user intervention. Each phase runs in its own sub-agent, writing state to the filesystem. Context never exhausts because sub-agents are isolated.

## Overview

Autobuild is an **autonomous execution engine** for superplan implementation plans. Unlike `superbuild` which stops after each phase for user confirmation, autobuild runs everything to completion.

**Key Differences from superbuild:**

| Aspect | superbuild | autobuild |
|--------|------------|-----------|
| Execution | Phase-by-phase with stops | Continuous until complete |
| User intervention | Required after each phase | None (fully autonomous) |
| Context management | Manual compaction | Sub-agents isolate context |
| State persistence | In conversation | Filesystem (.autobuild/) |
| Resume capability | Manual | Automatic from state files |

---

## Reference Index - MUST READ When Needed

**References contain detailed templates and patterns. Read BEFORE you need them.**

| When | Reference | What You Get |
|------|-----------|--------------|
| **Step 1: Initialize** | [STATE-FILES.md](references/STATE-FILES.md) | State file format, directory structure |
| **Step 3: Execute phases** | [PHASE-EXECUTION.md](references/PHASE-EXECUTION.md) | Phase ordering, parallel detection, retry logic |
| **Step 3: Launch sub-agents** | [SUBAGENT-PROMPTS.md](references/SUBAGENT-PROMPTS.md) | Exact prompts for phase sub-agents |
| **Step 4: Verify and commit** | [VERIFICATION.md](references/VERIFICATION.md) | Fresh verification, commit handling |
| **Step 5: Handle failures** | [FAILURE-HANDLING.md](references/FAILURE-HANDLING.md) | Retry logic, error recovery |
| **Overall flow** | [ORCHESTRATION.md](references/ORCHESTRATION.md) | Main orchestration loop, completion handling |

**Also reference superplan documents:**
- `superplan/references/TASK-MICROSTRUCTURE.md` - TDD 5-step format per task
- `superplan/references/TDD-DISCIPLINE.md` - TDD enforcement rules
- `superbuild/references/ENFORCEMENT-GUIDE.md` - Quality gate commands by stack

**DO NOT SKIP REFERENCES.** They contain exact prompts, templates, and formats that are NOT duplicated here.

---

## CLI Arguments

```
/autobuild <plan-path> [options]

Arguments:
  plan-path           Path to superplan document (required)

Options:
  --commit=<mode>     Git commit behavior (required before execution)
                      - auto: Auto-commit after each phase passes
                      - message-only: Generate messages, user handles git
                      - single: One combined commit at the end

  --resume            Resume from existing state (default if .autobuild/ exists)
  --fresh             Ignore existing state, start from scratch
  --dry-run           Validate plan and show execution order without running
```

**Example invocations:**
```bash
/autobuild docs/feature-plan.md --commit=auto
/autobuild docs/feature-plan.md --commit=message-only --resume
/autobuild docs/feature-plan.md --commit=single --fresh
```

---

## Critical Workflow

```
+-----------------------------------------------------------------------+
|                      AUTOBUILD EXECUTION FLOW                          |
+-----------------------------------------------------------------------+
|                                                                       |
|  1. INITIALIZE       |  Parse args, create .autobuild/, detect stack  |
|         |            |  NO PLAN = EXIT (ask user, then exit if none)  |
|         v            |  NO --commit = STOP (require commit mode)      |
|  2. LOAD STATE       |  Read existing state files if --resume         |
|         |            |  Identify completed phases, pending phases     |
|         v                                                             |
|  3. EXECUTE PHASES   |  For each pending phase (or parallel group):   |
|     |                |                                                |
|     |  3a. Launch sub-agent(s) for phase(s)                           |
|     |      - Sequential phases: one sub-agent at a time               |
|     |      - Parallel phases (2a,2b,2c): concurrent sub-agents        |
|     |                                                                 |
|     |  3b. Sub-agent executes:                                        |
|     |      - Read plan section for its phase                          |
|     |      - Follow TDD micro-structure per task                      |
|     |      - Run quality gates (lint, test, typecheck)                |
|     |      - Update plan checkboxes                                   |
|     |      - Return: status, commit message, files changed            |
|     |                                                                 |
|     |  3c. Write state file for phase                                 |
|         |                                                             |
|         v                                                             |
|  4. VERIFY + COMMIT  |  Re-run quality gates fresh (trust but verify) |
|         |            |  Handle git based on --commit mode              |
|         v                                                             |
|  5. ON FAILURE       |  Retry once, then halt with state preserved    |
|         |            |  Parallel siblings may continue before halt    |
|         v                                                             |
|  6. COMPLETION       |  All phases done, output summary               |
|                      |  State files preserved for audit               |
|                                                                       |
|  =====================================================================|
|  Sub-agents are ISOLATED. Context never exhausts. State is on disk.   |
|  =====================================================================|
|                                                                       |
+-----------------------------------------------------------------------+
```

---

## Step 1: Initialize

**REQUIRED: Plan document and commit mode must be provided.**

### Argument Validation

```
AUTOBUILD INITIALIZATION
=========================

Plan: [path]
Commit Mode: [auto|message-only|single]

Validating...
```

**If no plan provided:**
```
ERROR: No plan document provided.

Usage: /autobuild <plan-path> --commit=<mode>

Example: /autobuild docs/feature-plan.md --commit=auto

[EXIT - Cannot proceed without plan]
```

**If no --commit mode specified:**
```
COMMIT MODE REQUIRED
====================

Before I can execute this plan, I need to know how to handle git commits.

Please specify one of:
  --commit=auto         Auto-commit after each successful phase
  --commit=message-only Generate messages, you handle git (recommended)
  --commit=single       One combined commit after all phases complete

Example: /autobuild docs/feature-plan.md --commit=message-only

[WAITING FOR COMMIT MODE]
```

**NO EXCEPTIONS.** Do not proceed without explicit commit mode.

### Directory Setup

Create `.autobuild/` directory structure:

```
.autobuild/
  config.json           # Execution configuration
  phases/
    phase-0.json        # State file per phase
    phase-1.json
    phase-2a.json
    phase-2b.json
    ...
  logs/
    execution.log       # Overall execution log
    phase-0.log         # Per-phase logs (truncated sub-agent output)
    ...
```

> **STOP. Read [STATE-FILES.md](references/STATE-FILES.md) NOW** for complete state file format.

### Stack Detection

Detect technology stack to determine quality commands:

```
STACK DETECTION
===============

Detected:
- Language: TypeScript
- Framework: Express
- Package Manager: pnpm
- Test Framework: Jest
- Linter: ESLint
- Formatter: Prettier

Quality Commands:
- Lint: pnpm run lint
- Format: pnpm run format:check
- Typecheck: pnpm run typecheck
- Test: pnpm test

Stack saved to .autobuild/config.json
```

---

## Ste