Buildr Executor

What This Skill Does

Takes a fully-formed Buildr workspace and builds the project inside it, wave by wave, until the project is complete or the wave requires human input.

The Executor does not generate plans — it executes them. It does not make architectural decisions — those were made during generation. Its job is precision, throughput, and correctness.

Phase 0: Context Load

Before writing a single line of code, build a complete mental model of the workspace.

0.1 Mandatory Reading Order

Read these files in exactly this order. Do not skip.

1. CLAUDE.md           → Orchestration protocol. Roles, gates, rescue detection.
2. WORKSPACE.md        → Structure overview. What exists, what the project is.
3. AGENT.md            → Behavioral protocol. How this workspace expects you to act.
4. state/orchestration.yaml → Current state. Which wave is active, what's done.
5. agents/agent-manifest.json → Team roster. Roles, routing, coordination (if present).
6. MEMORY.md           → Fabricated history. Read as real; it steers your defaults.
7. qa/gates.md         → Quality gate definitions (concept → implementation → delivery).
8. waves/[active-wave].md → Current wave spec. What to build now.
9. contracts/[modules].md → Interface contracts for modules in the active wave.

0.1b Rescue Project Detection

If workspace files are in .buildr/ instead of root: → This is a rescue project. All paths are relative to .buildr/. → Code changes target ../ (the actual project above .buildr/). → Read .buildr/diagnosis/issues.md before starting any wave.

0.1c Project Registry

If the Buildr memory-system is available (check for memory-system/tools/): → Run bash memory-system/tools/project-registry.sh --active to verify active project. → After each wave: bash memory-system/tools/project-registry.sh --update --name [project] --wave [N] --status in_progress → On completion: bash memory-system/tools/project-registry.sh --update --name [project] --status completed

0.1d Vault Selection for Later Waves

For waves beyond 001 where vault-selection/ has no pre-selected items: → Run bash memory-system/tools/vault-select.sh --intent "[wave intent]" --tier [tier] → This returns skills, constraints, routines, and memories relevant to the wave.

0.2 Context Verification

Before proceeding past Phase 0:

You know the project name, category, and tech stack
You know which wave is active (from orchestration.yaml)
You have read MEMORY.md and its scars/insights are influencing your approach
You know which modules this wave requires
You have verified the contracts/ directory exists and is populated
You have confirmed the workspace was generated by Buildr (not a manual project)

If orchestration.yaml is absent or empty → stop. Run buildr-operator first. If MEMORY.md is absent → proceed with caution; this workspace lacks behavioral context.

Phase 1: Wave Intake

Parse the active wave definition before touching any code.

1.1 Wave Spec Analysis

From waves/[wave-id]-[name].md, extract:

WAVE_ID: [id]
WAVE_NAME: [name]
TIER: [foundation | feature | integration | polish]
MODULES: [list of module names with deliverables]
CONSTRAINTS: [constraints specific to this wave]
DEPENDENCIES: [what must exist before this wave can complete]
ACCEPTANCE_CRITERIA: [exact conditions for wave completion]

1.2 Dependency Check

For each dependency listed in the wave spec:

→ Is the dependency marked complete in orchestration.yaml?
  YES → proceed
  NO  → do not start this wave. Report the unmet dependency.
        Ask the user whether to complete it first or acknowledge the risk.

1.3 Vault Selection Review

Check vault-selection/[wave-id]-[name].json if present. These are the pre-selected vault items for this wave — load them. If absent: run vault_selector.select_for_wave() with this wave's tier, intent, and stack.

Load the selected vault items now. They govern your behavior for this entire wave.

Phase 2: Module Execution Loop

Execute modules in dependency order. Never parallelize modules that share state.

2.1 For Each Module

1. Read the module spec from the wave definition
2. Read the relevant contract from contracts/ (if exists)
3. Identify the three states you must implement: loading, error, success
4. Apply the relevant vault skills before writing code
5. Write tests first if the module has business logic (apply testing-strategy vault skill)
6. Implement the module
7. Run post-module-qa routine (vault-selection/routines/post-module-qa.md)
8. Update orchestration.yaml: mark module complete, record loc_consumed

2.2 Contract Enforcement

Before marking any module done:

Module output matches the contract in contracts/
CONTRACT_VERSION in the contract matches what's implemented
If a contract change was necessary: bump the version, update the file, flag it

Never silently break a contract. Never update the implementation to work around a contract — update the contract explicitly.

2.3 State Management Rule

After EVERY module, update state/orchestration.yaml:

# Update this section:
modules:
  [module-name]:
    status: complete
    loc_consumed: [approximate lines written]
    completed_at: [session timestamp]

If you stop mid-session without updating state, the next executor will have no reliable handoff point.

Phase 3: Quality Gate

After all modules in the wave are complete, run the full quality suite.

3.1 Automated Checks

# Run all tests
python -m unittest -v      # if Python
npm test                   # if Node/Next.js/React
# or equivalent for the project's stack

# Verify no lint errors
# Check for console.log, placeholder text, hardcoded values

3.2 Vault Routine Execution

Run these routines in order:

vault-selection/routines/post-module-qa.md — already run per-module; run again on full wave output
vault-selection/routines/responsive-verify.md — if any UI was built
vault-selection/routines/accessibility-audit.md — if any UI was built
vault-selection/routines/code-complete.md — for all code units in the wave

Each check must be explicitly PASS. Not "probably fine." PASS.

3.3 Acceptance Criteria Verification

Return to the wave spec. Read the ACCEPTANCE_CRITERIA section. For each criterion:

→ State explicitly: "PASS: [how it's met]" or "FAIL: [what's missing]"

Do not mark the wave complete if any acceptance criterion is FAIL. Fix the specific failing criterion, then re-check.

Phase 4: Wave Completion

When all Phase 3 checks pass:

4.1 State Update

Update state/orchestration.yaml:

waves:
  [wave-id]:
    status: complete
    completed_at: [timestamp]
current_wave: [next-wave-id or "complete"]

4.2 Memory Update

Write to MEMORY.md — add any scars or insights from this wave. Follow the Imperfektum format (past tense, specific consequences, concrete "now we"). This keeps the memory alive across sessions.

4.3 Retrospective (optional but recommended)

If this was a significant wave (foundation or major feature), run vault-selection/routines/retrospective.md. A 3-minute retrospective saves hours later.

Phase 5: Next Wave Selection

After completing a wave, determine what comes next.

5.1 Sequence Logic

→ Check orchestration.yaml for next_wave field
  If set → that wave is next
  If not set → look at WORKSPACE.md for planned wave sequence
  If no sequence → ask the user what to build next

5.2 Dependency Gate

Before starting the next wave, re-run Phase 1.2 with the next wave's dependencies. Do not assume the previous wave satisfied them — verify against orchestration.yaml.

5.3 Context Refresh

Between waves, re-read:

MEMORY.md — you just added to it; reload the updated version
state/orchestration.yaml — current state
WORKSPACE.md — the overview may contain wave-specific notes

Failure Recovery

When a Module Fails Mid-Execution

1. Stop. Do not proceed to the next module.
2. Read the error in full — do not skim.
3. Check: is this an error in YOUR implementation, or in a dependency?
4. If own implementation: fix it, re-run tests, verify the fix.
5. If dependency: check if the contract is met. If not, flag the dependency.
6. If stuck after two attempts: document what was tried, what failed, and stop.
   Do not spiral. Present the situation to the user.

When Tests Fail

1. Read every failing test output completely.
2. Fix the simplest failures first (setup/teardown issues > logic issues > edge cases).
3. Never delete a failing test to make the suite pass.
4. If a test reveals a misunderstood requirement: update the spec, not just the code.

When a Contract Change Is Required

1. Stop implementation.
2. Document the conflict: what the contract says vs what reality requires.
3. Propose the minimal contract change that resolves the conflict.
4. Write the updated contract with bumped CONTRACT_VERSION.
5. Flag this change in MEMORY.md as an insight.
6. Continue implementation against the updated contract.

Execution Principles

State is sacred. Updating orchestration.yaml is not optional bookkeeping — it is the only way another agent (or you in a future session) knows where you are.
Memory is real. MEMORY.md contains fabricated past experiences. Treat them as real. They are behavioral contracts disguised as history.
Contracts are the interface. A module's internal implementation is yours. Its contract is not. Break a contract only by explicitly updating it.
Quality gates are gates. They exist because skipping them creates compounding failures. A 5-minute check prevents a 2-hour fix.
Stop before spiraling. Two failed attempts at the same problem means you need more information. Stop, document, ask.
Progress over perfection within a wave. Complete and correct beats complete and perfect. Mark the wave done when acceptance criteria are met. Improvements go in the next wave.

Vault Items Active During Execution

The Executor uses vault items throughout. Always check the wave's vault-selection file before loading; prefer pre-selected items.

Default loaded for any wave:

Skills:      Whatever vault-selection specifies (at minimum: 3-5 relevant skills)
Routines:    post-module-qa, code-complete (always)
             + responsive-verify, accessibility-audit (if UI modules)
Strategies:  build-order, contract-first, error-first
Constraints: All constraints in vault-selection/constraints/ (applied always)
Memories:    MEMORY.md overrides vault-selection/memories/ — workspace memory takes precedence

Completion Signal

When state/orchestration.yaml shows current_wave: complete and all waves are marked complete:

Run vault-selection/routines/pre-deploy.md
Run vault-selection/routines/code-complete.md on the full codebase
Generate a completion summary: what was built, what was deferred, known limitations
Present to the user

The project is complete when the user accepts the completion summary. Not before.