execute

Philosophy: Each bead is a self-contained work package. The agent loads surgical context, designs the implementation from codebase patterns, implements, verifies, and commits — then resets context and moves to the next bead. Beads carry intent, not implementation. The agent writes code by understanding the codebase, not by copying from the bead. Execution is autonomous — the agent runs until all beads are complete or a genuine blocker requires human input.

Duration targets: BRIEF ~15-30 minutes (3-6 simple beads), STANDARD ~1-3 hours (typical feature), COMPREHENSIVE ~3-8 hours (multi-service, high-risk). These vary widely with feature complexity — the key signal is whether individual beads are completing smoothly, not total elapsed time.

Why This Matters

A well-written bead tells the agent what to build and how to verify it. But execution is where the value is delivered — turning intent into working, tested code. The execution loop must be:

• Autonomous — the agent completes beads without unnecessary interruption
• Verifiable — every change is tested before committing
• Recoverable — failures are handled gracefully with rollback and retry
• Resumable — interrupted execution can pick up where it left off
• Context-clean — each bead starts with fresh context, preventing drift from accumulated state

---

Trigger Conditions

Run this skill when:

• Beads exist (/beads completed — beads are a mechanical decomposition of an approved plan, not separately user-approved)
• User says "start implementation", "execute", "run beads"
• Ready beads exist in the issue tracker

Stage Gates — AskUserQuestion

At every PAUSE point in this skill, call the AskUserQuestion tool to present structured options to the user. Do not present options as plain markdown text — use the tool. The YAML blocks at each PAUSE point show the exact parameters to pass.

For pattern details and examples: ../_shared/references/stage-gates.md

Fallback: Only if AskUserQuestion is not available as a tool (check your tool list), fall back to presenting options as markdown text and waiting for freeform response.

Shared References

Before starting execution, load these shared reference files when applicable:

• Multi-agent execution: ../_shared/references/multi-agent-execution.md — load when other agents are active on the same branch
• Execution manifest template: ../_shared/references/execution-manifest.md — load when writing the manifest in Phase 4

---

Mode Selection

| Mode | When | Behaviour | |------|------|-----------| | BRIEF | 3-6 simple beads | Execute all, commit per bead, report at end | | STANDARD | Typical feature | Execute all, self-review per bead, upstream verification, report at end | | COMPREHENSIVE | Multi-service, high-risk | Execute with per-bead user check-in for high-risk beads, full upstream verification |

In COMPREHENSIVE mode, beads tagged as high-risk in the plan get a user check-in after implementation and before committing. Present the implementation summary and use AskUserQuestion (Decision Gate — Pattern 1) with options: "Approve & commit", "Modify", "Escalate". All other beads execute autonomously.

---

Collaborative Model

Phase 1: Verify Baseline
Phase 2: Execute Beads (loop until all complete)
  ├─ Orient → Load → Design → Implement → Verify → Commit → Push → Reset
  └─ (if blocker) PAUSE: "Blocker encountered. How to proceed?"
Phase 3: Blocker Handling (as needed)
Phase 4: Feature Completion — write execution manifest, close epic

---

Prerequisites

Before starting, verify:

• Beads exist for the feature (/beads completed — the plan approval is the approval, beads are not separately user-approved)
• All beads assessed as "Ready" during /beads self-assessment
• Tests pass before starting (run project build and test commands)
• Build succeeds
• If no beads exist, run /beads first

Bead source: Read bead descriptions from br show bd-{id} --json — the .description field is the execution contract populated by /beads. This is the primary source because hive's BeadsAdapter uses the same path. Fall back to docs/plans/{feature}/beads.md if the br description is empty (legacy bead sets created before description push was standard). The beads.md file is the human-readable authoritative record but br is the machine-readable execution contract.

---

Execution Loop

┌─────────────────────────────────────────────────────────────┐
│                    BEAD EXECUTION CYCLE                      │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  1. ORIENT                                                   │
│     └─ Read bead: objective, criteria, context refs          │
│     └─ Check progress for prior state                        │
│                                                              │
│  2. LOAD CONTEXT (surgical)                                  │
│     └─ Read ONLY files listed in "Context to Load"           │
│     └─ Understand patterns from referenced code              │
│     └─ DO NOT load entire plan or design docs                │
│     └─ DO NOT carry forward previous bead's context          │
│                                                              │
│  3. DESIGN (on-the-fly)                                      │
│     └─ Plan implementation based on loaded context           │
│     └─ Choose the pattern to follow from referenced code     │
│     └─ If uncertain → ASK user, don't guess                  │
│                                                              │
│  4. IMPLEMENT                                                │
│     └─ Write tests that verify success criteria              │
│     └─ Write code following codebase patterns                │
│     └─ Apply project standards (CLAUDE.md)                   │
│     └─ Run build after each file change (fail fast)          │
│                                                              │
│  5. VERIFY                                                   │
│     └─ Run bead's verification commands                      │
│     └─ Run full test suite (no regressions)                  │
│     └─ Self-review against success/failure criteria          │
│                                                              │
│  6. COMMIT                                                   │
│     └─ Stage specific files (not git add -A)                 │
│     └─ Commit with message from bead                         │
│     └─ Close bead in issue tracker                           │
│                                                              │
│  7. SUMMARISE & RESET                                        │
│     └─ Record what was done for this bead                    │
│     └─ Update progress tracking                              │
│     └─ Clear mental model of previous bead                   │
│     └─ Check execution health                                │
│     └─ Start next bead fresh                                 │
│                                                              │
└─────────────────────────────────────────────────────────────┘

---

Critical Sequence

Phase 1: Verify Baseline

Step 1.1 — Identify Available Work:

Query the issue tracker for ready beads and the feature's dependency tree. Produce a flat execution plan:

## Execution Plan: {feature}

**Ready now (no unmet dependencies):**
- bd-{id}: {title}
- bd-{id}: {title}

**Blocked (will unlock as above complete):**
- bd-{id}: {title} — blocked by: bd-{parent}
- bd-{id}: {title} — blocked by: bd-{parent1}, bd-{parent2}

**Other modules (not this session):**
- bd-{id}: {title} — different module, skip

Filter to YOUR module's beads only. Epic dependency trees often include beads from other modules — identify and exclude them upfront so you don't waste time tracing irrelevant dependencies.

Pre-scan for completed work: Before creating beads in the tracker, check whether the work already exists:

1. Scan git log --oneline for commit messages matching bead titles
2. For each bead, spot-check whether the target files already satisfy the success criteria — not just bead status. A bead marked "closed" may have no actual work done (stale state from a prior session).
3. If ALL beads would hit the verification-only fast path (zero code changes), skip tracker creation entirely — verify inline and close the epic with a comment

Batch-verify mode (>70% verification-only): When pre-scan reveals most beads are already implemented, switch to batch-verify mode:

• Group verification-only beads and check them in batches (3-5 at a time) rather than full orient→load→design→implement→verify→commit→reset per bead
• Only run the full execution cycle for beads that need actual code changes
• Collapse verification gates (UC gates, module gate) into a single pass if they all check existing code
• This saves significant time — Portal had 12/15 beads verification-only, each with unnecessary per-bead ceremony

Stale bead descriptions: If beads.md says "17 new tests needed" but the test files already have full coverage, flag the discrepancy. Proceed with verification-only mode rather than treating stale descriptions as authoritative. Close with a comment noting the discrepancy (e.g., "Verified — code has 14 items, bead said 13, extra is valid Translation Keys addition").

Step 1.2 — Verify Baseline:

Run the project's build and test commands. If baseline fails, assess severity before proceeding:

• Build failure: Fix before proceeding. Do not start executing beads on a broken codebase.
• Isolated test failures (1-10 tests, single module): Fix if related to the feature being executed, otherwise note and proceed.
• Systemic test failures (>10 tests across multiple modules): STOP. Do not claim any beads. Report the systemic issue to the user with failure count, affected modules, and suspected root cause. Systemic failures indicate a codebase-level problem (broken migration, missing dependency, config issue) that will block every bead — fixing it first prevents wasted work across the entire session.

Use AskUserQuestion if systemic failures are found:

AskUserQuestion:
  question: "{N} tests failing across {M} modules. This is a systemic blocker. How should we proceed?"
  header: "Baseline"
  multiSelect: false
  options:
    - label: "Fix blockers first (Recommended)"
      description: "Diagnose and fix the systemic issue before claiming any beads."
    - label: "Investigate only"
      description: "Diagnose the root cause and report without fixing."
    - label: "Proceed anyway"
      description: "Claim beads despite failing baseline (risky — failures may cascade)."

Step 1.3 — Initialise Progress Tracking:

Track overall progress so you (and the user) can see what's been completed and what remains. Use whatever progress mechanism is available (TodoWrite, comments, etc.).

---

Phase 2: Execute Beads

Loop until all beads are complete.

When multiple beads are ready simultaneously (no dependency between them), they can be executed in any order. Prefer: data model beads before service beads, service beads before integration beads. Execute each bead fully before starting the next.

Multi-Agent Concurrent Execution

When multiple agents execute on the same branch simultaneously, expect build collisions, file reverts, and test interference. Full guidance: ../_shared/references/multi-agent-execution.md

Key rules:

• Use file reservation (macro_file_reservation_cycle) by default when agent-mail is available
• Use module-scoped tests per bead; defer full suite to test gate
• After each commit, verify with git show --stat HEAD — other agents can steal staged files
• Do NOT fix other agents' files

Test gate beads: When the next bead is a test gate (tagged test), run the verification commands specified in the gate bead. If all pass, close the gate and proceed. If any fail, fix the failing implementation beads before continuing.

Review/simplify gate beads (legacy): If you encounter /review or /simplify gate beads (from older bead sets), do NOT launch full /review or /simplify agents. Instead:

• If preceding beads changed <5 files total: Self-review is sufficient. Run the self-review checklist from Step 2.7, close the gate, proceed. Launching review agents for 1-2 file changes is pure overhead.
• If preceding beads changed 8+ files or touched cross-cutting concerns: Run a targeted self-review against design docs. Still do not launch full agents — /review-execute at the end covers this.
• Close the gate bead with a comment: "Self-reviewed — /review-execute handles deep review post-execution."

E2E / Aspire beads: If a bead requires a different execution context (e.g., Aspire AppHost, browser automation, Docker compose), skip it with a comment: "Requires {context} — deferred to separate session." Do not block on beads that can't run in the current environment. Close as "deferred" not "completed."

Frontend test gate health check: Before claiming any frontend test bead, run a single small test to verify the test runner works. If the runner hangs, can't resolve path aliases, or produces unparseable output, note it as a blocker immediately — don't spend 10 minutes discovering this at the end of execution.

UC verification gates: When the next bead is a UC verification gate (verify({module}): UC-{ID}), trace the use case's main scenario steps through the implemented code:

1. Read the UC document referenced by the gate
2. For each main scenario step, confirm the endpoint/component exists and handles it
3. For each extension/alternative flow, confirm error handling exists
4. Run the gate's verification commands If any step can't be traced through code, flag as a blocker.

Module completion gates: When the next bead is a module completion gate (verify({module}): module complete), run the full test suite for the module and verify all UC gates passed.

For Each Bead:

Step 2.1 — Verify Module is Unblocked:

Before starting any bead, check if its module epic has upstream dependencies:

br dep tree bd-{module-epic}  # Check if upstream epics are closed

If the module epic depends on unclosed upstream epics, do NOT start work on this module. Pick a bead from an unblocked module instead.

The dependency map at docs/plans/dependency-map.md shows the tier ordering.

Step 2.1a — Claim Bead:

Mark the next available bead as in-progress to track state.

Step 2.2 — Orient (Read Bead):

Read the full bead description from br show bd-{id} --json (primary — the .description field is the execution contract). Fall back to docs/plans/{feature}/beads.md if the br description is empty. Parse:

• Objective — what to achieve
• Success Criteria — how to know it's done
• Failure Criteria — what to avoid
• Context to Load — files to read
• Approach — guidance on implementation
• Verification — how to test
• In/Out of Scope — boundaries to respect

Step 2.3 — Load Surgical Context:

Read ONLY the files specified in the bead's "Context to Load" section. Understand the patterns. Do NOT load:

• Entire plan or design documents (unless specifically referenced)
• Files from previous beads
• Unrelated services or modules

Well-scoped beads typically load 3-5 files. If a bead references significantly more, it may be too coarse — flag as a potential splitting candidate before proceeding.

Step 2.3a — Load Module Specs (first bead in module only):

When starting the FIRST bead in a module, load the module's key design documents. Use the doc map from docs/plans/{feature}/beads.md (if it contains one) or discover paths using the project's doc structure:

1. Design overview — technical design for the module
2. Data model — entity specifications (if exists)
3. API surface — endpoint specs for the feature being implemented (if referenced by bead)
4. PRD — requirements (skim for referenced FRs and UCs)
5. Use cases — UC documents referenced by beads in this module

Common path patterns (vary by project):

docs/designs/{module}/           — technical design (source of truth for HOW)
docs/prd/{module}/               — requirements (source of truth for WHAT)
docs/use-cases/ or docs/prd/{module}/use-cases/  — UC scenarios
docs/adr/                        — architectural decisions (source of truth for WHY)
docs/patterns/                   — coding patterns (source of truth for STYLE)
docs/architecture/               — system architecture (source of truth for CONSTRAINTS)

For subsequent beads in the same module, module specs persist until context compaction — don't re-read every bead.

Step 2.4 — Design Implementation:

Based on loaded context:

1. Identify the specific changes needed
2. Choose the pattern to follow (from referenced code)
3. Plan where to add or modify code
4. Design the test that will verify success criteria

If uncertain about anything:

• ASK the user for clarification
• Explain what's unclear and what options you see
• Do NOT guess or improvise beyond the bead's objective

Step 2.5 — Implement:

Write tests first:

• Tests should verify the success criteria
• Tests should check failure criteria aren't violated
• Use project test patterns and conventions (see project CLAUDE.md)

Then implement:

• Minimal code to make tests pass
• Follow existing patterns exactly
• No additional features beyond the bead's objective
• Run the build after each file change to catch errors early

Step 2.5a — Checkpoint (for large beads):

If a bead involves modifying more than 8 files, checkpoint periodically:

git stash push -m "checkpoint: bd-{id} - {description}"

This prevents total work loss on crash. After all files are done, pop the stashes and make a single clean commit.

Most beads modify 1-8 files — skip checkpointing for these. The per-file stash overhead isn't worth it for small beads.

Step 2.6 — Verify:

Solo execution: Run the full test suite, not filtered tests. Filtered tests miss cross-module regressions.

Concurrent execution (other agents active): Use module-scoped tests per bead (e.g., test filter for your module name). The full suite is unreliable when other agents have broken code or shared test infrastructure collisions cause batch failures. If module-scoped tests ALSO fail due to concurrent interference, fall back to per-class execution. Defer the full suite to the test gate bead when your module is complete and concurrent activity has settled.

In both cases: if the suite is slow (>5 minutes), run bead-specific verification commands first as a fast check.

Rationalization Prevention (Iron Law): Every completion claim requires FRESH verification evidence. Common rationalizations to catch:

• "It should work now" → RUN the tests. "Should" is not evidence.
• "I'm confident this is correct" → Confidence is not evidence. Run verification.
• "This is the same pattern as the last bead" → The last bead's tests don't verify this bead. Run tests.
• "I only changed one line" → One-line changes cause regressions. Run tests.

Step 2.7 — Self-Review:

Before committing, run a lightweight self-review. This is a fast sanity check — deep adversarial verification is done by /review-execute after all beads complete.

Proportionality: For verification beads (checking existing code matches design) and test-only beads, the self-review can skip pattern/style/slop checks — focus only on: objective achieved, success criteria met, tests pass.

Per-Bead Self-Review (lightweight):
- [ ] Re-read bead objective — does the implementation achieve it?
- [ ] Each success criterion met (check specifically)
- [ ] No failure criterion violated (check specifically — failure criteria often encode
      design decisions like "Do NOT use SaveRequest" per command-pattern.md; verify
      against the referenced decision doc, not just as arbitrary rules)
- [ ] No scope creep (nothing added beyond the objective)
- [ ] Implementation follows the referenced pattern doc
- [ ] Code style matches existing codebase
- [ ] Tests verify application logic, not framework guarantees
- [ ] Run tests before committing (full suite solo, module-scoped if concurrent — see Multi-Agent section)
- [ ] Staged specific files (not git add -A)
- [ ] No AI slop: unnecessary abstractions for single-use logic
- [ ] No AI slop: docstrings/comments on obvious methods
- [ ] No AI slop: defensive coding against impossible internal states
- [ ] No AI slop: premature generalization (config for one value, wrapper class with no added behavior)

If any item fails, fix the issue, re-run tests, then re-review.

Note: Deep design/spec alignment (api-surface match, data-model match, ADR compliance, FR acceptance criteria, UC scenario coverage) is verified by /review-execute post-execution. The self-review catches obvious mismatches but does not replace adversarial review.

Step 2.8 — Commit:

Verification-only fast path: Does the existing code already satisfy this bead's objective? If YES (all checks pass, zero code changes needed):

1. Skip commit and push — no empty commits
2. Close the bead with comment: "Verified — no changes needed"
3. Proceed to next bead

This is the correct path for verification beads where the codebase already matches the design.

If code was changed: Track which files you created or modified. Stage ONLY those files — NEVER use git add -A or git add .. Minimize the stage-to-commit window — other agents running git add -A can steal your staged files during the pre-commit hook. Stage and commit in a single shell command when possible, or use git stash before staging to protect your changes. Close the bead in the issue tracker.

Step 2.8a — Push (if committed):

git push

Push after each bead that produces a commit. Do NOT accumulate unpushed commits. This prevents work loss on crash.

Step 2.9 — Summarise & Reset:

Append a per-bead entry to the manifest (see ../_shared/references/execution-manifest.md for full template). For verification-only beads, use: Status: Verified — no changes needed.

Update progress tracking. Then reset implementation context:

• Clear the implementation details (code written, errors fixed, design choices made)
• Do NOT carry forward files loaded for the previous bead
• Module specs persist (design overview, data model, PRD) until context compaction — don't re-read every bead
• Start the next bead fresh — re-read from Step 2.1

Auto-Recovery

Handle issues automatically before asking the user. Different errors need different strategies.

Build Failure:

1. Read the error message carefully
2. Fix the specific error (missing import, type mismatch, etc.)
3. Re-run build
4. If same error persists after 2 fixes → re-read context files for correct pattern

Test Failure:

1. Read the failing test and the assertion message
2. Compare expected vs actual — is the test wrong or the implementation?
3. Fix whichever is incorrect
4. Re-run tests

Regression (Other Tests Break):

1. Identify which test(s) broke and why
2. If your change accidentally broke existing behaviour → fix to preserve it
3. If the change intentionally alters behaviour → the bead should have mentioned this
4. If the bead didn't mention it → ask the user before proceeding

Implementation Doesn't Work:

1. Re-read the bead objective and success criteria
2. Re-read context files for the correct pattern

<!-- Content truncated for initial SEO render. Open the source file tab for the full file. -->