Build Execution Framework (BEF) — A deterministic, repeatable framework for decomposing full-stack application requirements into executable phases and tasks. Includes an integrated bug management subsystem. Triggers on any /bef slash command. Commands: /bef:help, /bef:init, /bef:adopt, /bef:prd, /bef:arch, /bef:phases, /bef:deep-dive [phase#], /bef:sync [phase#], /bef:execute [phase#] [task#] (supports --agent-teams for wave-based parallel execution), /bef:status, /bef:replan, /bef:add-phase, /bef:amend [phase#], /bef:bug-detail [desc], /bef:bug-triage [source], /bef:bug-execute [phase], /bef:bug-status. Use this skill for any structured project planning, decomposition, execution workflow, or bug management. Also triggers when user mentions BEF, build execution framework, project decomposition, phase planning, bug triage, bug investigation, or references the /bef command.
BEF is a deterministic, repeatable framework for taking a software project from idea to execution through progressive decomposition. Every project follows the same pipeline, produces the same artifact types in the same structure, and is tracked through a single state file.
The pipeline:
PRD → Architecture → Phase Plan → Phase Deep Dive → Linear Sync → Execute
Each stage has a clear input, an interaction pattern, and a clear output.
Always read PROJECT_STATE.md first. Every command begins by reading the state file
to understand where the project is. If it doesn't exist, instruct the user to run /bef:init.
Never skip stages. Stages 1-3 are strictly sequential. Stage 4 (deep-dive) requires all dependency phases to be deep-dived first. Stage 5 (execute) requires deep-dive + sync.
Files are source of truth. Planning artifacts in the docs directory are authoritative. Linear mirrors execution status but specs live in files.
Interview, don't assume. At PRD and deep-dive stages, use structured interviews. Ask one focused question at a time. Summarize periodically. Never produce the final document until the user signals they're done.
Update state after every action. Every command that changes project state must update PROJECT_STATE.md before completing.
Task sizing. One task = one Claude Code session of focused work. Examples: one database migration, one API endpoint with tests, one UI component with integration, one auth flow end-to-end. Not "add a field" (too small) and not "build the entire API layer" (too big).
Every BEF project uses this exact structure:
docs/bef/
PROJECT_STATE.md ← Living state tracker (read first, always)
00-prd/
PRD.md ← Business requirements, user stories, constraints
01-architecture/
TECH_STACK.md ← Languages, frameworks, services, rationale
DATA_MODEL.md ← Entities, relationships, schema, constraints
SYSTEM_ARCHITECTURE.md ← Component boundaries, APIs, auth, state mgmt
INTEGRATION_MAP.md ← External services, APIs, webhooks, failure modes
02-phase-plan/
PHASE_PLAN.md ← Master build order with dependencies
03-phases/
phase-01-[name]/
PHASE_SPEC.md ← Detailed requirements, approach, edge cases
TASKS.md ← Atomic, ordered work items
phase-02-[name]/
PHASE_SPEC.md
TASKS.md
...
Templates for each artifact are located in the skill's templates/ directory. When
creating any artifact, read the corresponding template first and follow its structure exactly.
The templates are:
templates/PROJECT_STATE.md — State trackertemplates/PRD.md — Product Requirements Documenttemplates/TECH_STACK.md — Technology stack decisionstemplates/DATA_MODEL.md — Data model specificationtemplates/SYSTEM_ARCHITECTURE.md — System architecturetemplates/INTEGRATION_MAP.md — External integrationstemplates/PHASE_PLAN.md — Phase plan with dependenciestemplates/PHASE_SPEC.md — Per-phase detailed specificationtemplates/TASKS.md — Per-phase task breakdowntemplates/BUG_REPORT.md — Individual bug investigation reporttemplates/BUG_EXECUTION_PLAN.md — Triage execution plantemplates/BUG_INDEX.md — Bug index file (BUGS.md)For detailed specifications that extend the core framework, read the corresponding module file. Commands reference which modules they require.
modules/bug-management.md — Bug investigation, triage, and execution commandsmodules/parallel-orchestration.md — Shared worktree dispatch pattern (used by
execute --agent-teams and bug-execute)/bef:helpPrint the command reference and a brief explanation of the workflow. Use this format:
BUILD EXECUTION FRAMEWORK (BEF)
================================
A deterministic framework for decomposing full-stack projects into
executable phases and tasks through progressive refinement.
Pipeline: PRD → Architecture → Phase Plan → Deep Dive → Execute
COMMANDS:
/bef:help Show this guide
/bef:init Bootstrap a new project
/bef:adopt Plug framework into an existing project
/bef:prd Start/resume PRD interview
/bef:arch Generate & review architecture docs
/bef:phases Generate & review phase plan
/bef:deep-dive [phase#] Interview-based phase spec + task breakdown
/bef:sync [phase#] Push phase tasks to Linear
/bef:execute [phase#] [task#] Build a task (add --agent-teams for parallel phase execution)
/bef:status Show current project state
/bef:replan Post-phase checkpoint & adjustment
/bef:add-phase Add a new phase to the plan
/bef:amend [phase#] Revise an existing phase spec
BUG MANAGEMENT:
/bef:bug-detail [desc] Investigate a bug with Playwright
/bef:bug-triage [source] Triage bugs with 3-agent team
/bef:bug-execute [phase] Fix bugs in parallel with agent teams
/bef:bug-status Show bug tracking summary
RULES:
• Stages 1-3 (PRD → Arch → Phases) are sequential
• Deep dives require dependency phases to be deep-dived first
• Execute requires deep-dive + sync for that phase
• --agent-teams flag enables wave-based parallel execution with worktree isolation
• Bug commands require /bef:init but not pipeline stages 1-3
• Bug subsystem artifacts live in docs/bef/04-bugs/
• Run replan after completing each phase
• PROJECT_STATE.md is read before every command
/bef:initPurpose: Bootstrap a new BEF project.
Behavior:
docs/bef/, including 04-bugs/ and 04-bugs/reports/.templates/PROJECT_STATE.md template and create the initial PROJECT_STATE.md
with the project name, description, all stages marked as not started, and the Bug Tracking
section with empty defaults./bef:prd next.Output: Directory structure + PROJECT_STATE.md
/bef:adoptPurpose: Plug BEF into a project that's already in progress.
Behavior:
docs/bef/04-bugs/ and populate the Bug Tracking section.Output: Full directory structure + migrated artifacts + accurate PROJECT_STATE.md
/bef:prdPurpose: Create the Product Requirements Document through structured interview.
Gate: /bef:init or /bef:adopt must have been run.
Interview Protocol:
Conduct the interview one topic at a time. For each topic, ask focused questions, listen, and summarize what you've heard before moving on. The topics are:
After completing all topics, ask: "Is there anything else I should know that we haven't covered?"
When the user signals they're done, produce the final PRD.md using the template. Present it for review. Iterate if needed. When approved, mark Stage 1 complete in PROJECT_STATE.md.
Output: docs/bef/00-prd/PRD.md
/bef:archPurpose: Generate the four architecture documents based on the PRD.
Gate: Stage 1 (PRD) must be complete.
Behavior:
Important: For the DATA_MODEL.md, be thorough about relationships, indexes, and constraints. This document directly informs the schema migration phase. For TECH_STACK.md, include specific version numbers and rationale for each choice.
Output: Four files in docs/bef/01-architecture/
/bef:phasesPurpose: Generate the master Phase Plan.
Gate: Stage 2 (Architecture) must be complete.
Behavior:
Guidelines for phase decomposition:
Output: docs/bef/02-phase-plan/PHASE_PLAN.md + updated PROJECT_STATE.md
/bef:deep-dive [phase-number]Purpose: Create the detailed Phase Spec and Task Breakdown for a specific phase.
Gate: Stage 3 (Phase Plan) must be complete. All dependency phases for the target phase must already have their deep-dives complete.
Behavior:
Read: PROJECT_STATE.md, PHASE_PLAN.md, all architecture docs, and any completed PHASE_SPEC.md files for dependency phases.
Announce: "Starting deep dive for Phase [N]: [Name]. I'm going to interview you on five areas."
Interview one area at a time:
a. Functional Requirements — "Let's get specific about what this phase builds. Walk me through each piece of functionality." Probe for details, confirm understanding.
b. Technical Approach — "Here's how I'd approach building this technically. Does this align with your thinking?" Propose an approach, discuss alternatives.
c. Edge Cases & Error Handling — "Here are the edge cases I see. What am I missing?" List the ones you can identify, ask for others. Cover: invalid inputs, race conditions, failure modes, empty states, permission boundaries.
d. Integration Points — "This phase touches [X, Y, Z] from prior phases. Let me confirm the contracts." Verify API contracts, data shapes, auth flows.
e. Acceptance Criteria — "How do we know this phase is done? Here's what I'd test." Propose criteria, refine together.
After the interview, produce:
Present both for review. Iterate until approved.
Create the phase directory under 03-phases/ and save both files.
Update PROJECT_STATE.md: mark the phase's Spec and Tasks columns as complete.
Output: docs/bef/03-phases/phase-[NN]-[name]/PHASE_SPEC.md + TASKS.md
/bef:sync [phase-number]Purpose: Push tasks from a phase's TASKS.md to Linear as a milestone with linked issues.
Gate: The phase must have a completed TASKS.md.
Behavior:
linear_id field for each task,
so there's a two-way reference.Linear tool usage: Use the Linear MCP tools to create milestones and issues. Specifically:
list_teams to identify the correct team if not already known.list_projects to find the correct project.save_milestone to create the phase milestone.save_issue to create each task as an issue.Output: Linear milestone + issues created, TASKS.md updated with Linear IDs.
/bef:execute [phase-number] [task-number]Purpose: Execute a specific task — write the actual code.
Gate: The phase must be deep-dived and synced. The task's dependency tasks must be complete.
Behavior:
Output: Working code + updated state files.
Trigger: /bef:execute [phase#] --agent-teams
When the --agent-teams flag is present, the execute command enters orchestration mode.
Instead of executing a single task, it analyzes all remaining tasks in the phase, groups
them into parallelizable waves, and dispatches agent teams to execute tasks simultaneously
using worktree isolation.
The orchestrator (this session) manages the full lifecycle: analysis → dispatch → merge → verify → state update.
Critical rule: Worker agents only write code and commit. They never touch TASKS.md,
PROJECT_STATE.md, or any docs/bef/ tracking files. Only the orchestrator updates state.
Step 1: Analyze Ready Tasks
Step 2: Detect File Overlaps & Form Waves
For each ready task, extract the files it will likely touch from:
Build a conflict graph: two tasks conflict if they are likely to modify the same file(s).
Form parallel groups (waves):
If ALL ready tasks conflict with each other: recommend sequential execution instead of agent teams. Ask the user if they want to proceed sequentially or override.
Step 3: Present Execution Plan
Display the wave plan for user approval:
## Phase [N] Agent Teams Execution Plan
**Ready tasks (dependencies met):** [count]
### Wave 1
| Task | Title | Complexity | Touches |
|------|-------|-----------|---------|
| 3 | [title] | S | src/api/users.ts, prisma/migrations/ |
| 5 | [title] | M | src/components/dashboard/ |
**File overlap check:** No conflicts detected ✓
### Wave 2 (after Wave 1 merges)
| Task | Title | Complexity | Why deferred |
|------|-------|-----------|-------------|
| 4 | [title] | M | Shares src/api/routes.ts with Task 3 |
| 6 | [title] | S | Depends on Task 3 (newly unblocked) |
### Still Blocked
| Task | Waiting On |
|------|-----------|
| 8 | Tasks 6, 7 |
**Estimated waves:** 2 parallel + 0 sequential
**Proceed with Wave 1?** (Y / modify / switch to sequential)
Wait for user confirmation before dispatching.
Step 4: Dispatch Agent Team for Current Wave
For each task in the current wave, spawn an agent using the Agent tool with
isolation: "worktree" and run_in_background: true.
Agent prompt template:
You are executing a specific task from a BEF phase plan. Build exactly what the
task specifies, following the acceptance criteria precisely.
## Task Details
[Full task block from TASKS.md — scope, acceptance criteria, implementation notes]
## Phase Context
[PHASE_SPEC.md contents]
## Architecture Context
[Only the relevant architecture docs — DATA_MODEL.md for schema work,
SYSTEM_ARCHITECTURE.md for API work, INTEGRATION_MAP.md for external services, etc.
Do NOT include all docs — select based on the task's domain.]
## Rules
1. Build ONLY what this task specifies. Do not work on other tasks.
2. Follow the acceptance criteria exactly — each criterion must be met.
3. Do NOT modify TASKS.md, PROJECT_STATE.md, or any docs/bef/ tracking files.
4. Commit your work with message: `feat(phase-N/task-M): <short description>`
5. If the task is already done (functionality exists), report this — don't duplicate.
6. If the task is more complex than expected (would require changes beyond task scope),
stop and report this rather than attempting a risky implementation.
7. Run relevant tests/typechecks after implementation to verify changes work.
Dispatch ALL agents in the wave simultaneously (single message, multiple Agent tool calls).
Step 5: Process Wave Results
As each agent completes, categorize the result:
Wait for ALL agents in the wave to complete, then present a wave report:
## Wave [W] Results
### Completed (X/Y tasks)
| Task | Commit | Summary |
|------|--------|---------|
| 3 | abc1234 | Built user API endpoint with validation |
| 5 | def5678 | Dashboard component with data fetching |
### Needs Manual Execution (if any)
| Task | Reason |
|------|--------|
| 7 | Too complex — requires auth middleware refactor |
### Failed (if any)
| Task | Error |
|------|-------|
| 9 | TypeScript compilation failed |
Offer the user four options:
Step 6: Cherry-pick, Verify, and Update State
When the user approves merging:
Cherry-pick each completed agent's commit(s) onto the working branch, sequentially. If a cherry-pick conflict occurs, pause and ask the user to resolve it.
Verify — run the project's test/typecheck commands. If verification fails, diagnose and fix integration issues between changes that were developed in isolation. Common causes: shared imports modified by multiple tasks, index files both tasks updated.
Update TASKS.md — for each completed task:
Update PROJECT_STATE.md — update the execution progress count (e.g., "5/8 done").
Update Linear — if Linear MCP tools are available, update issue statuses.
Clean up — remove worktrees and branches for completed agents.
Step 7: Advance to Next Wave
After the current wave is merged and verified:
/bef:replan.This creates a natural "wave" execution pattern:
Wave 1: Tasks 3, 5 (parallel) → merge → verify
Wave 2: Tasks 4, 6, 7 (parallel, newly unblocked) → merge → verify
Wave 3: Task 8 (single, execute directly) → verify
Phase complete ✓
/bef:statusPurpose: Print the current project state.
Behavior:
docs/bef/04-bugs/BUGS.md exists, include the Bug Tracking summary
(open/fixed counts by severity, active bug phase).Output: Formatted state summary (not a file, just console output).
/bef:replanPurpose: Post-phase checkpoint. Review what was built against the plan and adjust.
Behavior:
docs/bef/04-bugs/BUGS.md? Do any block future phases?After final phase completion: Run a full PRD audit. Compare everything built across all phases against every requirement in the PRD. Flag gaps, drift, and any missing functionality. Propose remediation phases if needed.
Output: Updated PHASE_PLAN.md + PROJECT_STATE.md with replan log entry.
/bef:add-phasePurpose: Add a new phase to the project (post-initial-planning or during replan).
Behavior:
/bef:deep-dive [N] when ready to spec it out.Output: Updated PHASE_PLAN.md + PROJECT_STATE.md
/bef:amend [phase-number]Purpose: Revise an existing phase spec due to scope changes or new requirements.
Behavior:
/bef:sync [phase#] to update Linear.Output: Updated PHASE_SPEC.md + TASKS.md + PROJECT_STATE.md
PROJECT_STATE.md is the single source of truth for project progress. Every command reads it first and updates it when done.
State transitions are explicit. A stage is only marked complete when the user has reviewed and approved the output.
Idempotent operations. Running a command twice doesn't create duplicates. If a sync has already been run, re-running it updates existing Linear issues rather than creating new ones.
Replan log is append-only. Never delete replan log entries. They form the project's decision history.
Phase numbering is sequential and permanent. Phase 3 is always Phase 3, even if its scope changes. New phases get the next available number. This prevents confusion from renumbering.
For /bef:prd and /bef:deep-dive: