Implement

/implement

Load plan, dispatch subagents per task in wave order, verify completion.

Guiding Principles

• No Plan Mode — this skill operates in normal mode. EnterPlanMode/ExitPlanMode restrict Write/Edit tools and break the workflow.
• Session metadata is the source of truth — the session-start hook injects a metadata block with epic-id, epic-slug, feature-id, feature-name, feature-slug, parent artifacts, and output-target. Use these values verbatim — do NOT re-derive, re-extract, or generate alternatives.
• Wave ordering drives sequencing — foundation before consumers; parallel-safe waves dispatch all tasks concurrently; reviews run sequentially after all implementations complete
• Model escalation — start cheap (haiku), escalate on failure (sonnet, then opus). See Reference > Model Escalation.
• Working directory isolation — the CLI provides the working directory; skills don't manage worktrees; each phase commits to the feature branch at checkpoint; merge happens only at /release
• Subagent safety — one agent per task; parallel-safe waves dispatch all tasks simultaneously, non-parallel-safe waves dispatch sequentially; agents commit per task via git add + git commit; agents must NOT read the plan file, modify files outside their task's file list, or push/switch branches

Phase 1: Execute

Dispatch taskplanner, loop over waves dispatching implementers and reviewers.

1. Dispatch Taskplanner

Spawn the taskplanner agent to produce the .tasks.md:

1. Build the prompt — see Reference > Agent Dispatch Templates > Taskplanner
2. Spawn: Agent(subagent_type="beastmode:implement-taskplanner", model="opus", prompt=)

2. Parse Waves

Extract wave numbers and dependencies from the .tasks.md:

1. For each task, extract **Wave:** and **Depends on:** fields
2. Group tasks by wave number (default wave = 1 if omitted)
3. Within each wave, build dependency order from Depends on field

3. Wave Loop

For each wave (ascending order):

3a. Identify Runnable Tasks

From the wave map, select tasks where:

• Task belongs to current wave
• All dependencies are completed (or no dependencies)
• Task is not already completed (all checkboxes - [x] in .tasks.md)

3b. Dispatch Implementers

1. Determine mode: Parallel if wave has **Parallel-safe:** true on its first task AND 2+ runnable tasks. Otherwise sequential.
2. Spawn one beastmode:implement-dev agent per task at the current model tier. Pass the task's file list for the agent to read. See Reference > Agent Dispatch Templates > Implementer.

• Parallel mode: all agents in a single message (parallel tool calls).
• Sequential mode: one agent at a time; run steps 3c–3d after each before dispatching the next.

1. Collect all agent status reports.

3c. Handle Status

Process each implementer's reported status:

| Status | Action | |---|---| | DONE | Proceed to review pipeline (3d) | | DONEWITHCONCERNS | Correctness/scope issue → re-dispatch with fix instructions (max 2 retries). Observation only → note concern, proceed to 3d | | NEEDS_CONTEXT | Provide missing context, re-dispatch same task (max 2 retries). After max → BLOCKED | | BLOCKED | Re-dispatch with context or smaller split. Track retries against current tier budget (2 per tier). Escalate on tier exhaustion — see Reference > Model Escalation |

Never force retry without changes.

3d. Review Pipeline

Two-stage ordered review after implementer reports DONE (or observation-only concerns):

1. Spec compliance — spawn beastmode:implement-qa. See Reference > Agent Dispatch Templates > Spec Reviewer.

• PASS: proceed to quality review.
• FAIL: re-dispatch implementer with reviewer's issue list, re-run spec review. Max 2 cycles. After max → BLOCKED.

1. Code quality — spawn beastmode:implement-auditor. See Reference > Agent Dispatch Templates > Quality Reviewer.

• APPROVED: task complete.
• NOT_APPROVED (Critical/Important): re-dispatch implementer with issue list, re-run quality review. Max 2 cycles at current tier. After max → escalate model tier, re-run full pipeline (spec + quality). See Reference > Model Escalation.
• NOT_APPROVED (Minor only): treat as approved — minor issues don't block.

3e. Update Persistence

After each task completes (or is blocked):

1. Update .beastmode/artifacts/implement/YYYY-MM-DD---.tasks.md:

• Toggle completed steps from - [ ] to - [x]
• If task is blocked, add **Status: BLOCKED** after the task header

3f. Wave Checkpoint

After ALL tasks in the current wave complete:

1. Run the project test suite (command from .beastmode/context/implement/testing.md)
2. If tests fail: identify likely responsible task, re-dispatch with failure context. After 2 retries → mark wave blocked, report to user.
3. If tests pass: proceed to next wave.

If a blocked task has dependents in later waves, report: "Task N is blocked. Tasks [X, Y] in Wave M depend on it." Investigate if resolvable; otherwise skip dependents and log.

4. Completion

When all waves complete:

• Report: "Implementation complete. N tasks done, M review cycles."
• Proceed to validate phase.

Phase 2: Validate

BDD verification first (the feature-level acceptance gate), then quality checks.

1. BDD Verification Loop

If Task 0 was dispatched during Execute, run the feature's integration test. If no Task 0 → skip to step 2.

1a. Locate Integration Test

Find the integration test created by Task 0:

1. File naming: .integration.test.ts or .feature in test directories
2. Tags: @ tag on Gherkin features
3. Describe blocks: feature name in describe/feature blocks

If not found → skip BDD verification, proceed to step 2.

1b. Run and Retry

1. Run the integration test in isolation.
2. GREEN: BDD verification passed. Proceed to step 2.
3. RED: Enter retry loop (budget: 6 retries, 2 per tier — see Reference > BDD Verification Escalation):

• Analyze failure — examine assertions, stack traces, error messages
• Identify responsible task — map failure to task by file references, acceptance criteria, behavior area
• Re-dispatch responsible task through implementer (3b) + review pipeline (3d)
• Re-run integration test
• GREEN: stop, proceed to step 2
• RED: increment retry counter, escalate tier if budget exhausted at current tier

1. All retries exhausted → mark feature failed, report:

`` BDD verification failed after 6 retries (2x haiku, 2x sonnet, 2x opus). Last failure: [test name] — [assertion message] Responsible task: Task N — [description] ``

2. Run Tests

# Run project test command (from .beastmode/context/implement/testing.md) npm test # or appropriate command

Capture output and exit code.

3. Run Build (if applicable)

npm run build # or appropriate command

4. Run Lint (if applicable)

npm run lint # or appropriate command

5. Fix Loop

If any check fails:

1. Analyze the failure — identify root cause
2. Attempt a targeted fix (scope to the failing area)
3. Re-run the failing check
4. If fixed: continue to next check
5. If still failing after 2 attempts: report to user with actionable detail

Do NOT just "stop and report" on first failure. Attempt a fix first.

If any check still fails after fix loop: attempt additional investigation and targeted fixes. After exhausting options, log failures and proceed to checkpoint with a warning. Do NOT proceed to next phase if critical tests fail.

6. Status Summary

Print the accumulated status log from the execute phase:

### Status Summary

Tasks: N completed, M blocked Review cycles: N (spec: X, quality: Y)

Concerns noted:

• Task 3: File growing beyond plan's intent
• Task 5: Naming uncertainty on helper function

Blocked tasks:

• Task 7: [blocker description]

Total: N tasks, M review cycles, K concerns

Escalations: N tasks escalated (X to sonnet, Y to opus)

BDD verification: [passed | passed after K retries | failed after K retries | skipped] BDD retries: K total (X× haiku, Y× sonnet, Z× opus)

Omit the Escalations line if no tasks escalated. Omit the BDD retries line if BDD verification passed on first run or was skipped.

If all tasks completed with no concerns: "All tasks completed cleanly — no concerns or blockers."

Phase 3: Checkpoint

1. Save Implementation Report

Save to the path specified by output-target in the session metadata block.

IMPORTANT: The filename MUST match the output-target exactly — no extra suffixes like -deviations. The stop hook derives the output.json filename from this basename, and the watch loop matches on the epic/feature slug convention. Any extra suffix breaks the match and the watch loop never sees completion.

The artifact MUST begin with YAML frontmatter:

---
phase: implement
epic-id: 
epic-slug: 
feature-id: 
feature-name: 
feature-slug: 
status: completed
---

Set status to completed if all tasks passed, error if any task is blocked.

Report body:

# Implementation Report:

Date: YYYY-MM-DD Feature Plan: .beastmode/artifacts/plan/YYYY-MM-DD---.md Tasks completed: N/M Review cycles: N (spec: X, quality: Y) Concerns: N BDD verification: [passed | passed after K retries | failed after K retries | skipped]

## Completed Tasks

• Task N: () — [clean | with concerns | escalated from : ]

## Concerns

• Task N:

## Blocked Tasks

• Task N:

## BDD Verification

• Result: [passed | passed after K retries | failed after K retries | skipped]
• Retries: N (haiku: X, sonnet: Y, opus: Z)
• Last failure: [test name — assertion message] (if applicable)
• Responsible task: Task N (if retries occurred)

If BDD verification passed on first run: "BDD verification passed — integration test GREEN after all tasks completed." If skipped: "BDD verification skipped — no Integration Test Scenarios in feature plan."

If all tasks completed with no concerns, still write this file with "Concerns: 0" and empty sections. This file MUST always be written — the stop hook reads its frontmatter to generate output.json, which the watch loop uses to detect completion.

2. Commit and Handoff

Commit the implementation report on the feature branch:

git add .beastmode/artifacts/implement/
git commit -m "implement(--): checkpoint"

Print:

Next: beastmode validate 

STOP. No additional output.

Reference

Model Escalation

The controller maintains per-task escalation state:

• Model ladder: ["haiku", "sonnet", "opus"]
• Current tier index: starts at 0 (haiku) for each new task
• Tier retry counter: starts at 0 for each new task, resets on escalation

When a task begins, reset both to zero. The tier index selects the model passed to the Agent tool's model parameter for implementer dispatch. Reviewer agents (spec-reviewer, quality-reviewer) do not receive a model parameter — they use the default model.

Escalation triggers:

• Implementer BLOCKED after 2 retries at current tier → escalate
• Quality review NOT_APPROVED (Critical/Important) after 2 review-fix cycles at current tier → escalate

Non-triggers (no escalation):

• NEEDS_CONTEXT — context problem, not model capability. Re-dispatch at same tier.
• Spec review FAIL — requirement misunderstanding. Re-dispatch at same tier.
• Quality review NOT_APPROVED with only Minor issues — treated as approved.

Budget: 2 retries per tier × 3 tiers = 6 total attempts. After opus exhausted → BLOCKED.

BDD Verification Escalation

The BDD verification loop uses an independent escalation state, separate from per-task escalation:

• Model ladder: ["haiku", "sonnet", "opus"] (same ladder)
• Budget: 6 total retries (2 per tier)
• Independence: A task that completed at haiku during initial dispatch may be re-dispatched at sonnet during BDD verification if the integration test keeps failing.
• Reset: BDD escalation resets to tier 0 (haiku) when the BDD retry loop begins. Does NOT carry over from per-task escalation.

Agent Dispatch Templates

Taskplanner

Build the prompt:

• Append: feature plan text (from conversation context — hook-injected)
• Append: epic-slug, feature-slug (from session metadata)
• Append: output path — .beastmode/artifacts/implement/YYYY-MM-DD---.tasks.md

Spawn: Agent(subagent_type="beastmode:implement-taskplanner", model="opus", prompt=)

Implementer

Build the prompt:

• Append: full task text (all steps, files, verification)
• Append: project conventions from .beastmode/context/IMPLEMENT.md

Spawn: Agent(subagent_type="beastmode:implement-dev", model=, prompt=)

Spec Reviewer

Build the prompt:

• Append: the task requirements (from .tasks.md)
• Append: the implementer's status report
• Append: the task's file list

Spawn: Agent(subagent_type="beastmode:implement-qa", prompt=)

Quality Reviewer

Build the prompt:

• Append: the task requirements (for context)
• Append: the implementer's status report
• Append: the task's file list

Spawn: Agent(subagent_type="beastmode:implement-auditor", prompt=)

Implementation Report Format

Accumulated during execution, saved at checkpoint:

## Completed Tasks

• Task 0: Implementer agent (haiku) — clean
• Task 1: Implementer agent (sonnet) — clean (escalated from haiku: BLOCKED)
• Task 3: Implementer agent (opus) — with concerns (escalated from sonnet: quality NOT_APPROVED)

## Concerns

• Task 3: SKILL.md grew significantly during controller rewrite

## Blocked Tasks None

Summary: 4 tasks completed (1 with concerns), 0 blocked, 6 review cycles, 2 escalations

## BDD Verification

• Result: passed after 3 retries
• Retries: 3 (haiku: 2, sonnet: 1, opus: 0)
• Last failure: auth-flow.integration.test.ts — "Expected token to be valid"
• Responsible task: Task 3

If no concerns or blocks: "All tasks completed cleanly — no concerns or blockers."

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: BugRoger
• Source: BugRoger/beastmode
• License: MIT

Install and usage instructions live in the source repository linked above.