--- name: superbuild description: Use when executing implementation plans phase-by-phase with strict enforcement of quality gates, tests, and Definition of Done. Triggers on "build this plan", "execute plan", "implement phases", or when user provides a plan document to execute. metadata: version: "1.0.0" author: skulto compatibility: Requires plan document in superplan format. Works with any codebase with quality tools configured. --- # 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 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ (): Files changed: - path/to/file1.ts (CREATE) - path/to/file2.ts (MODIFY) - path/to/file3.ts (DELETE)