spec-execution

name: spec-execution description: Execute specs/*.md plans through working checkpoints. Use when the user says "execute this spec", "implement this plan", "run the spec", or points at a spec file. metadata: author: epicenter version: '1.0'

Spec Execution

When handed a specification document (a specs/*.md file), execute it methodically in waves. A wave is an implementation checkpoint: after it lands, the repo should build, relevant tests should pass, and the spec should describe what is now true.

Commits should follow the shape of the work. Commit after a wave when that wave is a natural review unit. Combine waves into one larger commit when the changes are tightly coupled. Break a large wave into smaller commits when that makes the history easier to audit. The goal is working checkpoints first, readable git history second.

When to Apply This Skill

Use this pattern when you need to:

• Implement a specs/*.md plan end-to-end in structured waves.
• Decide which spec tasks run in parallel vs sequentially.
• Update spec checkboxes and implementation notes after each wave.
• Commit code changes together with spec progress at sensible review boundaries.
• Finish execution by running post-implementation-review, setting spec status, and adding a review section.

The Execution Loop

PREFLIGHT SPEC
    |
    v
READ ACTIVE PATH
    |
    v
PLAN WAVES (which tasks are parallel vs sequential?)
    |
    v
WAVE N
  1. Execute tasks (sub-agents when useful)
  2. Verify (type-check, tests if applicable)
  3. Update spec (check off items, add notes)
  4. Commit or checkpoint, based on review shape
    |
    v
REPEAT until spec is complete
    |
    v
FINAL REVIEW (run post-implementation-review, update spec status, add review section)

Default to continuing. After a wave passes verification, move to the next unchecked item until the spec is complete. Ask the user only when continuing requires a product decision, destructive action, broad reshape, or resolving a conflict with current code.

Phase 0: Preflight the Spec

Before planning waves, make sure the spec has a current execution path.

Check:

• Status: Draft, In Progress, Implemented, Superseded, or Retrospective.
• Supersession: whether the top of the spec points to a newer spec.
• One Sentence: what the spec is actually about.
• Current State and Target Shape: enough concrete code, routes, types, or file paths to start.
• Implementation Plan: actionable tasks or waves.
• Verification: commands, smoke tests, or grep checks that prove the work.
• Open Questions: anything that blocks implementation.

Large specs are fine. Do not split or reject a spec because it is long. Only stop to refresh the spec when the active path is unclear, stale, or mixed with unrelated reader jobs.

If a spec is long but usable, write a short wave plan and proceed. If it is long and confusing, first add or update a "How to read this spec" or "Active execution path" section. That update is part of the work.

Phase 1: Read and Understand

Before touching any code:

1. Read the active path first: understand what is current before reading appendices, prompts, or historical notes
2. Identify the implementation phases from the spec's Implementation Plan section
3. Map dependencies: which tasks block others? Which are independent?
4. Check the spec's Open Questions: resolve what you can, flag what needs human input
5. Scan the rest of the spec for constraints: read decisions, rejected alternatives, and edge cases that could affect the implementation

If the spec has unresolved Open Questions that block implementation, surface them immediately. Don't guess on architectural decisions.

Phase 2: Plan Waves

Break the spec's implementation plan into execution waves. A wave is a set of changes that can land together while leaving the repo working.

Breaking API changes are allowed inside a wave. The boundary matters: by the end of the wave, update affected consumers, migrations, tests, or documentation so the repo is coherent again.

Deciding Parallel vs Sequential

Use sub-agents whenever the runtime permits and the task has a clean ownership boundary. The question is whether each task is small, bounded, and non-overlapping enough to delegate safely, and whether delegated tasks should run concurrently or sequentially.

Wave Planning Checklist

Before executing, write out your wave plan:

Wave 1: [Foundation, types and interfaces]
  - Task 1.1 (parallel with 1.2)
  - Task 1.2 (parallel with 1.1)
  - Checkpoint: verify and update spec
  - Commit: optional, if this is a reviewable unit

Wave 2: [Core logic, depends on Wave 1 types]
  - Task 2.1 (sequential, modifies shared module)
  - Task 2.2 (after 2.1, uses its exports)
  - Checkpoint: verify and update spec
  - Commit: likely, because this changes behavior

Wave 3: [Integration, consumers of Wave 2]
  - Task 3.1 (parallel with 3.2)
  - Task 3.2 (parallel with 3.1)
  - Checkpoint: verify and update spec
  - Commit: combine with Wave 2 if the API and consumers should be reviewed together

Proceed after planning. Ask first only for product choices, destructive actions, broad reshape risk, or conflicts with current code.

Phase 3: Execute Waves

For each wave:

1. Execute Tasks

Use sub-agents for owned implementation work when they are available. They are strongest when each agent owns a bounded task, a clear file set, and a non-overlapping write surface. The primary agent still owns orchestration, integration, verification, spec updates, and final review.

• Independent tasks: Launch sub-agents in parallel when write sets do not overlap. Each gets a focused prompt with only the context it needs: the relevant spec section, the files it owns, and the patterns to follow.
• Dependent tasks: Launch sub-agents sequentially when one task imports from another task's output or modifies the same files. Wait for one to complete before launching the next. The second agent gets the output/context from the first.
• Local tasks: Keep work local when the task is tightly coupled, urgent, too ambiguous to delegate, or likely to block the next orchestration step.
• Keep changes coherent: Treat the spec as the execution spine, not a file whitelist. Implement the spec first; fix grounded correctness, verification, API, and serious clarity issues you uncover; record meaningful deviations.

2. Verify the Wave

After all tasks in a wave complete:

bun typecheck                 # repo-standard type-check
bun test                       # if tests exist for changed code

If verification fails, fix issues before proceeding. Don't carry broken state into the next wave.

3. Update the Spec

Check off completed items in the spec's Implementation Plan:

- [x] **1.1** Add IconDefinition type
- [x] **1.2** Add CoverDefinition type
- [ ] **2.1** Update factory functions

If implementation deviated from the spec (it often does), add a note:

- [x] **1.1** Add IconDefinition type
  > **Note**: Used discriminated union instead of enum as originally planned.
  > Rationale: better type narrowing in consumers.

If you discovered something during implementation, add it to the spec's Research Findings or Edge Cases section.

4. Commit or Checkpoint the Wave

Each committed unit should include BOTH the code changes AND the spec updates that describe those changes. This keeps history honest: each commit shows what was planned, what changed, and what was actually built.

You do not have to create one commit per wave. Use the commit shape that best fits the review:

Follow git and incremental-commits skill conventions:

feat(scope): wave description, what this wave accomplishes

- Completed spec items 1.1, 1.2
- [Any notable deviations or discoveries]

Stage specific files. Never git add . or git add -A.

Phase 4: Final Review

After all waves complete:

1. Run post-implementation-review against the files touched by the spec. Use the findings to clean up stale abstractions, dead paths, invariant drift, naming issues, and missing verification before handoff.
2. Update spec status from "In Progress" to "Implemented"
3. Add a Review section at the bottom of the spec:

## Review

**Completed**: [Date]
**Branch**: [branch-name]

### What Landed

[2-3 sentences on what was built and how it differs from the original plan]

### Deviations and Discoveries

- [What changed and why]

### Follow-up Work

- [Anything discovered during implementation that should be a future spec]

4. Final commit or final amend/squash with the review section included, matching the commit strategy chosen earlier

This review section is spec bookkeeping, not the pull request body. When writing the PR, load git and follow the PR narrative guidance there.

Sub-Agent Prompts

The primary agent orchestrates: it plans waves, launches sub-agents when useful, verifies results, updates the spec, and commits. It may implement tightly coupled or blocking work directly when delegation would add coordination cost or risk.

When spinning up sub-agents, each agent needs:

• The specific spec section it's implementing (not the whole spec)
• The files it should read before making changes
• The primary files it owns
• The patterns to follow (reference relevant skills)
• Questions that need the user: product decisions, destructive actions, broad reshaping, or current-code conflicts

Keep sub-agent prompts focused. A sub-agent that knows too much will try to do too much.

When Things Go Wrong

Anti-Patterns

Execute Without Planning

"Let me just start implementing..."

No. Read the spec, plan waves, then execute. Planning should start the work, not become a reason to stop.

Giant Wave

Wave 1: Implement everything in the spec

If a wave touches more than 5-8 files, ask whether it still represents one coherent working checkpoint. Sometimes a broad breaking change needs to happen together, but default to smaller waves when reviewability or verification would improve.

Spec Drift

Code diverges from spec but spec is never updated

The spec is a living document. Every commit should leave the spec accurate to what was actually built.

Length Panic

This spec is long, so split it before reading it

No. Length is not the failure mode. Confusing reader jobs are the failure mode. A long spec with a clear first screen, current path, decisions, and verification can be easier to execute than five scattered short specs.

Over-Parallel

Wave 1: 12 sub-agents all running at once

More than 3-4 parallel sub-agents gets chaotic. Group related tasks and keep parallelism manageable.

Quick Reference

Before starting:

• Preflight status, supersession, and active path
• Read active sections first
• Identify phases and dependencies
• Plan waves (parallel vs sequential)
• Surface decisions that need user input

For each wave:

• Execute tasks (sub-agents when useful)
• Verify (type-check, tests)
• Update spec (check items, add notes)
• Commit if this wave is a logical review unit, or checkpoint and continue

After all waves:

• Run post-implementation-review on touched files
• Update spec status to Implemented
• Add Review section
• Finalize commits using the chosen strategy