asteroid-belt-llc/superbuild

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.

---

Reference Index - MUST READ When Needed

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

| When | Reference | What You Get | |------|-----------|--------------| | Step 3: Executing tasks | [superplan/references/TASK-MICROSTRUCTURE.md] | 5-step TDD format per task | | Step 3: Executing tasks | [superplan/references/TDD-DISCIPLINE.md] | TDD rules, rationalizations, red flags | | Step 4: Any check fails | references/ENFORCEMENT-GUIDE.md | Failure templates, output parsing, stack commands | | Step 5: Updating plan | references/PLAN-UPDATES.md | Checkbox patterns, status updates | | Step 6: Commit message | references/COMMIT-FORMAT.md | CLI-safe chars, HEREDOC format | | Steps 7-8: Stop/Resume | references/EXECUTION-CONTROL.md | Output templates, compaction behavior | | Step 9: AUTO-COMPACT | references/EXECUTION-CONTROL.md | CHECKPOINT parsing, auto-compact workflow |

DO NOT SKIP REFERENCES. They contain exact templates and patterns that are NOT duplicated here.

---

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       │
│  2.5 PLAN REVIEW   │  Check for ambiguity, missing deps, test gaps  │
│         ↓          │  IF concerns → PAUSE and ask user              │
│  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          │
│  9. AUTO-COMPACT   │  BUILD-ALL ONLY: Run /compact at CHECKPOINT    │
│                    │  Parse focus from CHECKPOINT, compact, continue│
│                                                                     │
│  ════════════════════════════════════════════════════════════════   │
│  Steps 3-8 repeat for EACH PHASE. Plan updates after EVERY phase.  │
│  BUILD-ALL: Steps 3-9 repeat automatically with auto-compact.       │
│  ════════════════════════════════════════════════════════════════   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Step 1: Ingest Plan

REQUIRED: Plan document must be provided.

Plan Header Recognition

Plans created by superplan include this header:

> **For Claude:** Execute this plan using `/superbuild` skill.

This confirms the plan is in the expected format with:

• Parallelizable phases with poker estimates
• Definition of Done per phase
• 5-step TDD micro-structure per task

I'll help you execute your implementation plan.

Please provide the plan document:
1. Path to plan file (e.g., docs/plans/001-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 2.5: Critical Plan Review

Before executing, review the plan for concerns:

1. Ambiguous tasks - Any task unclear about what to do?
2. Missing dependencies - Are required files/APIs/packages identified?
3. Test gaps - Does each task have testable acceptance criteria?
4. Risky changes - Any destructive operations or breaking changes?

If Concerns Exist

⚠️  PLAN REVIEW - Concerns Identified
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. [Concern 1 - what and why]
2. [Concern 2 - what and why]

Please clarify before I proceed.
[EXECUTION PAUSED]

If No Concerns

Proceed to Step 3 (Execute Phase).

Step 3: Execute Phase

TDD Micro-Structure Enforcement

Plans created by superplan use a 5-step TDD micro-structure per task:

1. Write failing test
2. Run test, verify failure (MANDATORY - must see it fail)
3. Write minimal implementation
4. Run test, verify pass (MANDATORY - must see it pass)
5. Stage for commit

STOP. Read superplan/references/TASK-MICROSTRUCTURE.md and superplan/references/TDD-DISCIPLINE.md NOW before executing any task.

TDD Enforcement Rules

When executing tasks, enforce this order STRICTLY:

| Rule | Enforcement | |------|-------------| | Test before code | STOP if implementation exists without test | | Verify RED | STOP if test passes immediately (testing existing behavior) | | Minimal code | STOP if adding features beyond current test | | Verify GREEN | STOP if test not run after implementation | | No regressions | STOP if other tests now fail |

If test passes immediately: The test is wrong. It tests existing behavior, not new behavior. Fix the test or you are not doing TDD.

If you cannot explain why the test failed: You do not understand what you are testing. Stop and clarify requirements.

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.

Sub-Agent Result Verification

CRITICAL: Do NOT trust sub-agent claims without independent verification.

When parallel phases complete:

1. Collect all sub-agent results
2. For EACH sub-agent claiming success:
   • Run npm test (or equivalent) to verify tests pass
   • Run npm run lint to verify linter passes
   • Verify plan file was actually updated
3. Only after independent verification, output commit messages

Sub-agent reports are CLAIMS, not EVIDENCE. Fresh verification required.

Step 4: Enforce Definition of Done

EVERY phase must pass ALL quality gates before completion.

Fresh Verification Requirement

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE.

The Verification Gate (run for EVERY check):

1. IDENTIFY - Which command proves this claim?
2. RUN - Execute the command NOW (not from memory)
3. READ - Examine FULL output, count failures/errors
4. VERIFY - Does output match the claim?
5. THEN CLAIM - Only state success after steps 1-4

Invalid Evidence:

• Previous run output (even from 2 minutes ago)
• Assumptions based on code changes
• Partial verification ("linter passed so types probably pass")
• Agent/sub-agent reports without independent verification

Red Flag Language - HALT Immediately

If you find yourself using these words about verification:

| Red Flag | Meaning | Required Action | |----------|---------|-----------------| | "should pass" | Uncertainty | RUN the check, don't assume | | "probably works" | Uncertainty | RUN the check, don't assume | | "seems to be fine" | Uncertainty | RUN the check, don't assume | | "I believe it passes" | No evidence | RUN the check, get evidence | | "based on my changes" | Inference, not verification | RUN the check |

Any hedging language = missing verification. Stop and run the actual check.

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]

STOP. Read ENFORCEMENT-GUIDE.md NOW when any check fails - contains failure templates and stack-specific commands.

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.

Read PLAN-UPDATES.md for checkbox 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.

| Type | When | |------|------| | feat | New feature | | fix | Bug fix | | refactor | Code restructure (no behavior change) | | test | Adding/updating tests | | docs | Documentation | | chore | Build, config, dependencies |

Read COMMIT-FORMAT.md for CLI-safe characters and HEREDOC patterns.

Read EXECUTION-CONTROL.md for parallel phase commit output format.

Step 7: Functional Testing Instructions

After commit message, explain how to functionally test the phase.

Provide step-by-step manual verification instructions. Offer integration test script only if applicable - ALWAYS ask, NEVER auto-create.

Read EXECUTION-CONTROL.md for output format and script offer template.

Step 8: Stop Execution

FULL STOP after each phase (unless --build-all override).

1. Output phase completion summary
2. Show progress table
3. Suggest context compaction
4. Wait for explicit "Continue to Phase X" instruction

Post-compaction behavior: Complete in-progress phase only, then STOP. Todo list is NOT authorization to continue.

Build-all override: Only if user explicitly requests. Warn about risks first.

Read EXECUTION-CONTROL.md for output templates and compaction behavior.

---

Step 9: Auto-Compact in BUILD-ALL Mode

CRITICAL: In BUILD-ALL mode, automatic context compaction is MANDATORY.

When running with --build-all flag, execute /compact automatically after each phase CHECKPOINT to preserve context for remaining phases.

Auto-Compact Trigger

Plans created by superplan include CHECKPOINT markers at the end of each phase:

- [ ] **CHECKPOINT: Run `/compact focus on: Phase N complete, [key artifacts], Phase N+1 goals`**

BUILD-ALL Auto-Compact Workflow

┌─────────────────────────────────────────────────────────────────────┐
│                    BUILD-ALL MODE: AUTO-COMPACT                      │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  1. COMPLETE PHASE   │  Execute all tasks, pass quality gates       │
│          ↓           │                                              │
│  2. UPDATE PLAN      │  Check off tasks, mark CHECKPOINT done       │
│          ↓           │                                              │
│  3. GENERATE COMMIT  │  Output conventional commit message          │
│          ↓           │                                              │
│  4. DETECT CHECKPOINT│  Find CHECKPOINT task in completed phase     │
│          ↓           │                                              │
│  5. EXTRACT FOCUS    │  Parse focus directive from CHECKPOINT       │
│          ↓           │                                              │
│  6. RUN /COMPACT     │  Execute: /compact focus on: [extracted]     │
│          ↓           │  ⚠️  NO USER INTERVENTION REQUIRED           │
│  7. CONTINUE         │  Proceed to next phase automatically         │
│                                                                     │
│  ════════════════════════════════════════════════════════════════   │
│  Steps 1-7 repeat for EACH PHASE until plan complete.               │
│  ════════════════════════════════════════════════════════════════   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

CHECKPOINT Parsing

Extract the focus directive from the CHECKPOINT task:

Input:  - [ ] **CHECKPOINT: Run `/compact focus on: Phase 1 complete, auth models created, Phase 2 needs endpoints`**

Parsed: focus on: Phase 1 complete, auth models created, Phase 2 needs endpoints

Auto-Compact Execution

Execute /compact with the parsed focus directive:

AUTO-COMPACT TRIGGERED - Phase [X] Complete
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Running: /compact focus on: [parsed focus directive]

Preserving:
- Phase [X] completion status
- Key artifacts: [list from focus]
- Phase [X+1] goals: [from focus]

[compact executes]

Context refreshed. Continuing to Phase [X+1]...

No CHECKPOINT Found

If a phase lacks a CHECKPOINT (legacy plan or manual creation):

⚠️  NO CHECKPOINT FOUND - Phase [X]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

This phase has no CHECKPOINT marker for auto-compact.

Options:
1. Continue without compact (risk context exhaustion)
2. Pause for manual /compact
3. Add CHECKPOINT to plan and retry

Recommendation: Option 2 for safety

[EXECUTION PAUSED - Awaiting instruction]

Read EXECUTION-CONTROL.md for detailed auto-compact patterns.

Rationalizations to Reject

| Excuse | Reality | |--------|---------| | "Let me just do the next phase too" | NO. Stop after each phase. | | "The tests are mostly there" | NO. Tests must exist for ALL new code. | | "It's just a small linting error" | NO. All quality gates must pass. | | "I'll commit later" | NO. Generate commit message NOW. | | "This phase doesn't need tests" | NO. Every phase with code needs tests. | | "Let me skip to the important part" | NO. Execute phases in dependency order. | | "I can fix the formatter later" | NO. Formatter must pass before completion. | | "The user wants to move fast" | NO. Quality enforcement is non-negotiable. | | "I'm confident this works" | NO. Confidence ≠ evidence. Run the check. | | "I just ran it a moment ago" | NO. Run it again. Fresh evidence required. | | "The code is correct, so tests will pass" | NO. Run the tests. Code review ≠ testing. | | "This is a minor change" | NO. All changes require verification. | | "Too simple to need a test" | NO. Simple code breaks. Write the test. | | "I'll add tests after the code works" | NO. Tests-after pass immediately. No proof of value. | | "I already manually tested it" | NO. Ad-hoc testing is not systematic. TDD required. | | "The test passed immediately, so it works" | NO. Immediate pass = testing existing behavior. Fix test. |

Red Flags - STOP Immediately

If you catch yourself thinking any of these, STOP:

• "This is taking too long, let me skip ahead"
• "The user seems impatient, let me batch phases"
• "Tests can come after the feature works"
• "Linting is just style, not critical"
• "I'll generate all commit messages at the end"
• "The plan doesn't explicitly require tests"
• "The sub-agent confirmed it passes"
• "I already verified this earlier"
• "This is obviously correct"
• "I wrote the code first, but I'll test it now"
• "The test passed on the first try"
• "This feature is too simple for TDD"
• "Let me just get it working, then add tests"

All of these = violation of superbuild protocol.

Quality Commands by Stack

Read ENFORCEMENT-GUIDE.md for stack-specific commands (JS/TS, Python, Go, Rust).

Summary: The Iron Rules

1. No plan = No execution - Exit if plan not provided
2. One phase at a time - Unless parallel phases (use sub-agents)
3. All quality gates must pass - No exceptions
4. Update plan after EVERY phase - Check off tasks, update status
5. Generate commit message - Never run git commands
6. Explain functional testing - Ask before writing scripts
7. Full stop after phase - Unless --build-all override
8. Suggest compact - Context management is critical
9. Fresh verification required - Run checks NOW, not from memory
10. Auto-compact in BUILD-ALL - Parse CHECKPOINT, run /compact, continue automatically

Superbuild is rigid by design. The enforcement protects code quality. Do not rationalize around it.