superbuild

What this skill does

# Superbuild: Plan Execution Engine

Execute implementation plans one phase at a time with strict quality enforcement, test verification, and conventional commit generation.

## Overview

Superbuild is a **rigid execution engine** for implementation plans. It enforces:
- Phase-by-phase execution (no skipping ahead)
- Definition of Done verification before phase completion
- Test presence and passing verification
- Linter/formatter/typechecker enforcement
- Conventional commit message generation per phase

**This is NOT a planning skill.** Use `superplan` to create plans, then `superbuild` to execute them.

## Critical Workflow

```
┌─────────────────────────────────────────────────────────────────────┐
│                      SUPERBUILD EXECUTION FLOW                       │
│                     (REPEAT FOR EACH PHASE)                          │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  1. INGEST PLAN    │  User provides plan document path              │
│         ↓          │  NO PLAN = EXIT (ask user, then exit if none)  │
│  2. READ PHASES    │  Output ALL phases with estimates              │
│         ↓          │  IF context high → suggest compact first       │
│  3. EXECUTE PHASE  │  One phase at a time (or parallel if marked)   │
│         ↓          │  USE SUB-AGENTS for parallel phases            │
│  4. ENFORCE DOD    │  Tests exist? Tests pass? Linter? Formatter?   │
│         ↓          │  ALL must pass → continue. ANY fail → STOP     │
│  5. UPDATE PLAN    │  Check off tasks, update status in plan file   │
│         ↓          │  ⚠️  THIS HAPPENS AFTER EVERY PHASE            │
│  6. COMMIT MSG     │  Generate conventional commit (NEVER git ops)  │
│         ↓          │  User handles all git operations               │
│  7. FUNCTIONAL TEST│  Explain how to test. Offer integration script │
│         ↓          │  NEVER auto-create scripts. ALWAYS ask first   │
│  8. STOP           │  Full stop. Suggest compact. Wait for user.    │
│                    │  OVERRIDE: --build-all flag continues          │
│                                                                     │
│  ════════════════════════════════════════════════════════════════   │
│  Steps 3-8 repeat for EACH PHASE. Plan updates after EVERY phase.  │
│  ════════════════════════════════════════════════════════════════   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

## Step 1: Ingest Plan

**REQUIRED: Plan document must be provided.**

```
I'll help you execute your implementation plan.

Please provide the plan document:
1. Path to plan file (e.g., docs/feature-plan.md)
2. Paste the plan content directly

Which would you prefer?
```

**If no plan provided after asking:** EXIT immediately.

```
I cannot execute without a plan document.

To create a plan, use the `superplan` skill first:
  /superplan

Then come back with the completed plan.

[EXIT - No further action]
```

**NO EXCEPTIONS.** Do not improvise. Do not create plans on the fly. Do not proceed without a plan document.

## Step 2: Read All Phases

After ingesting the plan:

1. **Output all phases** with their estimates and dependencies
2. **Check context usage** - if high, suggest compacting first

```
PLAN LOADED: [Feature Name]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

| Phase | Name | Est. | Depends On | Parallel With | Status |
|-------|------|------|------------|---------------|--------|
| 0 | Bootstrap | 5 | - | - | ⬜ |
| 1 | Setup | 3 | 0 | - | ⬜ |
| 2A | Backend | 8 | 1 | 2B, 2C | ⬜ |
| 2B | Frontend | 5 | 1 | 2A, 2C | ⬜ |
| 2C | Tests | 3 | 1 | 2A, 2B | ⬜ |
| 3 | Integration | 5 | 2A,2B,2C | - | ⬜ |

Total: 29 points | Parallel phases: 2A, 2B, 2C

⚠️  Context Usage Advisory
If context is high, consider compacting before continuing.
Large plans consume significant context per phase.

Ready to execute Phase 0?
```

## Step 3: Execute Phase

### Sequential Phases

Execute one at a time. Do not proceed to next phase until current is COMPLETE.

### Parallel Phases

For phases marked "Parallel With", **MUST use sub-agents or parallel Task tool calls**.

```
EXECUTING PARALLEL PHASES: 2A, 2B, 2C
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Launching 3 parallel sub-agents...

[Sub-agent 2A: Backend implementation]
[Sub-agent 2B: Frontend implementation]
[Sub-agent 2C: Test implementation]

Each sub-agent MUST return:
- Implementation status
- Definition of Done checklist status
- Conventional commit message
```

**CRITICAL:** Each sub-agent returns its commit message. Main agent MUST bubble up ALL commit messages to user.

## Step 4: Enforce Definition of Done

**EVERY phase must pass ALL quality gates before completion.**

### Quality Gate Checklist

```
DEFINITION OF DONE - Phase [X]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[ ] Tests exist for new code
[ ] All tests pass (new AND existing)
[ ] Linter passes ([detected linter])
[ ] Formatter passes ([detected formatter])
[ ] Type checker passes ([detected checker])
[ ] No new warnings introduced
[ ] Plan document updated (checkboxes, status)  ← BEFORE commit message
```

### Enforcement Rules

| Check | If PASS | If FAIL |
|-------|---------|---------|
| Tests exist | Continue | **STOP** - Point out missing tests |
| Tests pass | Continue | **STOP** - Ask user to fix |
| Linter | Continue | **STOP** - Ask user to fix |
| Formatter | Continue | **STOP** - Ask user to fix |
| Type checker | Continue | **STOP** - Ask user to fix |
| Plan updated | Generate commit | **STOP** - Update plan first |

**STOP means STOP.** Do not proceed. Do not offer to fix automatically. Ask user to fix and re-run.

### Failure Output Format

When any check fails, output:

```
⛔ DEFINITION OF DONE FAILED
━━━━━━━━━━━━━━━━━━━━━━━━━━━
Issue: [Missing tests | Tests failing | Linter errors | etc.]
[Details of what failed]
Please fix, then tell me to continue.
[EXECUTION HALTED]
```

**See `references/ENFORCEMENT-GUIDE.md`** for detailed failure message templates and output parsing patterns.

## Step 5: Update Plan Document (EVERY PHASE)

**⚠️ MANDATORY: This step executes after EVERY phase, not just at the end.**

After ALL quality gates pass, BEFORE generating commit message, UPDATE THE PLAN FILE:

1. **Check off completed tasks** (`- [ ]` → `- [x]`)
2. **Update phase status** in overview table (`⬜` → `✅`)
3. **Mark DoD items complete** (`- [ ]` → `- [x]`)

```
PLAN DOCUMENT UPDATED - Phase [X]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

File: [plan-file-path]

Updates applied:
- Tasks: X/X items checked [x]
- DoD: X/X items checked [x]
- Status: ⬜ → ✅

The plan now reflects Phase [X] completion.
```

**See `references/PLAN-UPDATES.md` for detailed patterns and error handling.**

**WHY EVERY PHASE:**
- Plan survives context compaction (conversation may not)
- Progress visible to anyone reading the plan
- Enables clean handoff between sessions
- Creates audit trail in git history

**DO NOT SKIP THIS STEP.** If you find yourself generating a commit message without updating the plan first, STOP and update the plan.

## Step 6: Generate Conventional Commit

**After Definition of Done passes, generate commit message.**

**CRITICAL: OUTPUT ONLY. NEVER run git commands.**

```
PHASE [X] COMPLETE - Conventional Commit Message
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

<type>(<scope>): <short summary>

<body - detailed description of changes>

Files changed:
- path/to/file1.ts (CREATE)
- path/to/file2.ts (MODIFY)
- path/to/file3.ts (DELETE)

<footer - issue refs, breaking changes>

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⚠️  DO NOT COMMIT - Copy this message and run:
    git add . && git commit -m "..."

User handles all git operations.
```

### Commit Types

| Type | When |
|------|------|
| `feat` | New feature |
| `fix` | Bug fix |
| `refactor` | Code restructure (no behavior change) |
| `te