apply

Implement code based on the change artifacts. Supports three modes:

• Gherkin-driven (default): feature files drive implementation and testing
• Proposal-driven: when gherkin is skipped (technical changes), proposal drives testing
• Fix-from-verify: the open findings in verify.md are the task list (see step 4)

<decision_boundary>

Use for:

• Implementing code for a Beat change that has spec artifacts (gherkin or proposal) done
• TDD implementation driven by feature files or proposal risk points
• Resuming implementation of a partially completed change
• Fixing the open findings of the last /beat:verify run ("fix the verify findings", fix-from-verify)

NOT for:

• Creating spec artifacts like proposal, gherkin, or design.md (use /beat:design)
• Breaking down tasks or creating execution plans (use /beat:plan)
• Verifying implementation completeness (use /beat:verify)
• Exploring ideas or investigating a problem (use /beat:explore)

Trigger examples:

• "Implement the change" / "Start coding" / "Apply the plan" / "TDD the scenarios"
• Should NOT trigger: "design a feature" / "break down tasks" / "verify the implementation"

</decision_boundary>

Apply NEVER pushes. Commits stay on the local branch until /beat:archive has run; pushing and opening the PR belong to finishing-a-development-branch after archive. If the user asks to push now, say that archive must be the last commit on the branch, confirm once, and if they insist push — never push on your own initiative.

Code on a prototype/<node-id> branch is NEVER merged, cherry-picked or copied into the change. It existed to let a human judge a variant. Rewrite the behaviour from the gherkin under TDD. </HARD-GATE>

Prerequisites (invoke before proceeding)

Invoke in order: worktrees first (verify isolation), then TDD (discipline). Debugging and subagent are conditional — only invoke when triggered. If a superpower is unavailable (skill not installed), skip and continue.

Unattended mode

When the run carries a stage-result nonce (see references/handoff-report.md), nobody is watching: follow references/unattended-mode.md. Every AskUserQuestion in this skill becomes a default (recorded in beat/changes/<name>/decisions/assumed.md), a decision brief (references/decision-brief.md, blocked-on: decision), or an environmental stop (blocked-on: env). The per-skill table in that reference says which. For apply specifically: an unclear scenario takes the reading the gherkin most plainly supports (assumed) unless the ambiguity changes behaviour (brief); a design issue that reverses a Key Decision is a brief, anything smaller updates design.md and is noted; e2e failures and blockers are env. TDD and the no-push rule do not change.

Rationalization Prevention

Red Flags — STOP if you catch yourself:

• Writing implementation code before invoking using-git-worktrees
• Writing implementation code before writing a failing test (in TDD mode)
• Thinking "I'll set up the worktree after this first file"
• Skipping TDD because "the test would be trivial"
• Moving to the next scenario without a clean lint-features.mjs run
• Skipping e2e test creation because "the e2e framework is complex to set up"
• Writing a test skeleton instead of an executable test
• Dispatching a single subagent for multiple tasks to "save time"
• Creating a new test file for a scenario that already has @covered-by pointing to an existing test
• Modifying scenario steps without updating the corresponding e2e test
• Running git push before /beat:archive has committed
• Reading a prototype/ branch for anything other than the stories and the approved-variant note
• Finishing a minimal/technical change without checking the diff against preset_upgrade thresholds

Mid-Implementation Triggers (mandatory)

Living-doc paths (glossary, ADRs, architecture hub) are listed in references/project-layout.md.

• ADR — hard-to-reverse + surprising + real-trade-off decision not in design.md → write ADR (references/adr-format.md). Before writing: apply rules.adr from the beat/config.yaml you read in step 3, and use the project's docs/adr/TEMPLATE.md if it exists (otherwise Beat's front-matter template, source: beat/changes/<name>). Commit the ADR (and any project ADR index) in the same commit as the code that forced the decision.
• README — module public-interface change → update module README (references/architecture-format.md)
• New module — creating a new module (new top-level directory with its own concerns) → offer to scaffold its README (references/architecture-format.md)

Run inline as conditions arise. Don't batch.

Process Flow

digraph apply {
    "Select change, read artifacts" [shape=box];
    "Invoke using-git-worktrees" [shape=box, style=bold];
    "testing.required false?" [shape=diamond];
    "No-test mode" [shape=box];
    "Invoke test-driven-development" [shape=box, style=bold];
    "Gherkin done?" [shape=diamond];
    "Gherkin-driven" [shape=box];
    "Proposal-driven" [shape=box];
    "fix-from-verify?" [shape=diamond];
    "Open findings in verify.md\nare the task list" [shape=box];
    "tasks.md exists?" [shape=diamond];
    "Has Task N headings?" [shape=diamond];
    "Executor mode\nfollow tasks exactly" [shape=box];
    "Planner mode\nextract scenarios/criteria" [shape=box];
    "Implementation loop" [shape=box];
    "Preset minimal/technical?" [shape=diamond];
    "Diff over preset_upgrade\nthresholds?" [shape=diamond];
    "Upgrade preset to standard" [shape=box, style=bold];
    "All tasks complete\n(no push)" [shape=doublecircle];

    "Select change, read artifacts" -> "Invoke using-git-worktrees";
    "Invoke using-git-worktrees" -> "testing.required false?";
    "testing.required false?" -> "No-test mode" [label="yes"];
    "testing.required false?" -> "Invoke test-driven-development" [label="no"];
    "No-test mode" -> "Gherkin done?";
    "Invoke test-driven-development" -> "Gherkin done?";
    "Gherkin done?" -> "Gherkin-driven" [label="yes"];
    "Gherkin done?" -> "Proposal-driven" [label="gherkin skipped"];
    "Gherkin-driven" -> "fix-from-verify?";
    "Proposal-driven" -> "fix-from-verify?";
    "fix-from-verify?" -> "Open findings in verify.md\nare the task list" [label="yes"];
    "fix-from-verify?" -> "tasks.md exists?" [label="no"];
    "Open findings in verify.md\nare the task list" -> "Implementation loop";
    "tasks.md exists?" -> "Has Task N headings?" [label="yes"];
    "tasks.md exists?" -> "Planner mode\nextract scenarios/criteria" [label="no"];
    "Has Task N headings?" -> "Executor mode\nfollow tasks exactly" [label="yes"];
    "Has Task N headings?" -> "Planner mode\nextract scenarios/criteria" [label="no"];
    "Executor mode\nfollow tasks exactly" -> "Implementation loop";
    "Planner mode\nextract scenarios/criteria" -> "Implementation loop";
    "Implementation loop" -> "Preset minimal/technical?" [label="after each task"];
    "Preset minimal/technical?" -> "Diff over preset_upgrade\nthresholds?" [label="yes"];
    "Preset minimal/technical?" -> "All tasks complete\n(no push)" [label="no"];
    "Diff over preset_upgrade\nthresholds?" -> "Upgrade preset to standard" [label="yes"];
    "Diff over preset_upgrade\nthresholds?" -> "All tasks complete\n(no push)" [label="no"];
    "Upgrade preset to standard" -> "All tasks complete\n(no push)";
}

Input: Optionally specify a change name. If omitted, infer from context or prompt. If the input contains fix-from-verify, or the user asks to fix the findings of the last verify run, enter fix-from-verify mode (step 4).

Steps

1. Select the change

   If no name provided:

   • Look for beat/changes/ directories (excluding archive/)
   • If only one exists, use it (announce: "Using change: <name>")
   • If multiple exist, use AskUserQuestion tool to let user select

   Read preset from status.yaml (schema: references/status-schema.md) and keep it at hand — step 6 checks minimal/technical changes against the upgrade thresholds.

2. Read status.yaml and verify readiness (schema: references/status-schema.md)

   Check that either:

   • gherkin has status: done → Gherkin-driven mode
   • gherkin has status: skipped AND proposal has status: done → Proposal-driven mode

   If neither condition is met: "Features or proposal are required before implementation. Run /beat:design first." STOP.

   If status.yaml has source: distill: warn — "This is a distill change; its features describe behavior the code already has, so there is nothing to implement. The intended flow is /beat:verify → /beat:archive." Use AskUserQuestion tool to confirm before proceeding.

3. Read all artifacts and determine testing mode

   Read in order:

   • proposal.md (if exists) -- business context and risk points
   • features/*.feature (all files, if gherkin is done) -- implementation targets
   • design.md (if exists) -- technical decisions
   • tasks.md (if exists) -- implementation checklist

   Read beat/config.yaml (if exists, schema: references/config-schema.md). Besides testing, keep language, context, and rules.adr at hand — the mid-implementation ADR trigger uses them.

   Determine testing mode:

   • If testing.required: false → no-test mode: skip TDD cycles for all scenarios, write implementation only
   • If testing.behavior is set → use that framework for @behavior scenarios (skip auto-detection)
   • If testing.e2e is set → use that framework for @e2e scenarios (skip auto-detection)
   • If testing.framework is set (legacy) → treat as testing.behavior
   • If testing is absent or testing.required: true → TDD mode (default): require tests for all scenarios

   Determine BDD feature paths (for running e2e tests):

   • Base: beat/features/ (unchanged features; .feature.orig files are invisible to BDD runners)
   • If beat/changes/<name>/features/ contains feature files: add it (new + modified features)
   • Combine both paths when invoking BDD runner (e.g., npx cucumber-js beat/features beat/changes/<name>/features)

4. Determine implementation strategy

   If tasks.md exists: Use it as the implementation checklist.

   • Detailed format (contains ### Task N: headings with Steps): Enter executor mode — follow each step exactly as written, don't re-plan.
   • Simple format (only - [ ] checkboxes): Enter planner mode — plan each task's implementation yourself (existing behavior).

   If no tasks.md and Gherkin-driven: Extract each Scenario from feature files as a unit of work (planner mode).

   If no tasks.md and Proposal-driven: Extract success criteria and risk points from proposal.md as units of work (planner mode).

   Fix-from-verify mode (overrides the above): read beat/changes/<name>/verify.md (format: references/verify-findings.md). If it is missing or has no front matter, stop: "No verify findings to fix — run /beat:verify <name> first." The unit-of-work list is the open findings worth doing: by default every status: open CRITICAL plus every open WARNING with reach: reachable; fix-from-verify F3 F7 takes explicit ids of any severity; fix-from-verify all takes every open finding — say how many speculative and SUGGESTION items that includes before starting, because chasing those is what turns verify into a loop. Never widen the list on your own, and never leave a CRITICAL out. Each finding's scenario, file and fix are the task description; the TDD rules below still apply (a CRITICAL in dimension 1B means a missing test — write it first). Do not re-plan the whole change; do not touch findings marked wontfix. After each fix, rewrite that finding's line to status: fixed — never delete lines.

5. Show implementation overview

   ## Implementing: <change-name>
   
   ### Drive mode: gherkin-driven / proposal-driven
   ### Execution mode: executor / planner
   ### Tasks/Scenarios to implement:
   1. [source] <name>
   2. [source] <name>
   ...

6. Implement (loop)

   For each task (from tasks.md) or scenario (from features) or risk point (from proposal):

   a. Announce: "Working on: <description>"

   b. Write automated test first (TDD mode only):

   • Skip this step if no-test mode
   • The test framework: use testing.behavior or testing.e2e from config (depending on scenario tag), or detect from codebase

   Generate vs Update (see references/testing-conventions.md for details):

   • @covered-by present + test file exists → Update: modify the existing test to reflect new scenario steps
   • @covered-by present + test file missing → Generate + WARNING (stale annotation)
   • @covered-by absent → Generate: create new test (existing flow)

   For @e2e scenarios (Gherkin-driven):

   • Generate (or update) e2e test or step definitions using testing.e2e framework from config, or auto-detect from codebase
   • If the project uses a BDD runner (Cucumber, pytest-bdd, etc.), generate step definitions that bind to the .feature file
   • If no BDD runner, generate a regular e2e test with @feature/@scenario annotations (same as @behavior)

   For @behavior scenarios (Gherkin-driven):

   • Generate a test file (using testing.behavior from config, or auto-detect) with annotation comments:

     @feature: <feature-filename>.feature
     @scenario: <exact scenario name>

     (Use the project language's comment syntax: // for JS/TS/Java/C#, # for Python/Ruby, etc.)
   • After writing the test, update the .feature file with a @covered-by annotation (placed between the tag and the scenario line):

     @behavior @happy-path
     # @covered-by: <relative path to test file>
     Scenario: <name>

   For proposal-driven units:

   • Generate test files covering the risk point using the project's test framework
   • No annotation conventions needed (no features to link to) For pytest-bdd projects: the @scenario decorator serves as the annotation — no separate # @feature / # @scenario comments needed (see references/testing-conventions.md).

   Follow the conventions in references/testing-conventions.md for annotation format, e2e test style, and Generate vs Update path.

   c. Write implementation code:

   • Follow design.md decisions if available
   • Keep changes minimal and focused on the scenario
   • In no-test mode: still write implementation, just without preceding test

   d. If using tasks.md: Mark task complete - [ ] -> - [x]. In fix-from-verify mode: mark the finding status: fixed in verify.md.

   d2. Preset upgrade check (only when preset is minimal or technical): run git diff --stat <base>..HEAD and count, tests excluded, the source files touched, the net lines added, and the top-level modules touched (directories under src/, packages/, apps/, or the repo root). Compare against preset_upgrade in beat/config.yaml (thresholds and defaults: references/config-schema.md). If any threshold is exceeded: set preset: standard and write preset_upgrade: { from: <old>, by: /beat:apply, date: <today>, reason: "<which threshold, with numbers>" } in status.yaml, announce it in one line, and continue — the next /beat:verify runs at standard strength. Do this check once per task, not once at the end.

   d3. Sensitivity check (unattended mode only, once after the last task): run git diff --name-only <base>..HEAD and compare the touched paths and what they implement against sensitive in beat/config.yaml (schema: references/config-schema.md). Read beat/changes/<name>/decisions/sensitive.md: if it already says yes, repeat it. If it says no and the diff now matches, update the file (yes, what matched, apply) and report sensitive=yes — this does not stop the run; archive lists it in the PR body. If the diff shows the change needs a second PR (a second module, a migration that must land first), stop with a scope brief per references/unattended-mode.md instead of continuing.

   e. Continue to next

   f. Scenario completion check (before moving to the next scenario):

   Run node <skill-dir>/scripts/lint-features.mjs --require-covered-by beat/changes/<name>/features/*.feature (see references/lint-tools.md). It checks the @covered-by annotation, its position, that the test file exists and carries the @scenario: annotation, and the layer tag. Fix every error it lists; rerun until it exits 0. In no-test mode run it without --require-covered-by.

   Then confirm by hand what lint cannot see:

   • The test is executable, not a skeleton (run it)
   • Implementation code handles the scenario's behavior
   • Task checkbox marked complete (if using tasks.md)

   Do NOT move to the next scenario until lint is clean and all items are checked.

   Pause if:

   • Task/scenario is unclear -> ask for clarification (unattended: brief if behaviour-changing, else assumed)
   • Implementation reveals design issue -> suggest updating artifacts (unattended: brief if it reverses a Key Decision)
   • Error or blocker -> report and wait (unattended: blocked-on: env)

7. E2E regression check (after all scenarios implemented)

   If @e2e scenarios exist and testing.e2e is configured (or auto-detected):

   • Run the full e2e test suite using the combined BDD feature paths
   • If any failures → report and pause. Do NOT advance to verify phase.
   • All passing → continue to completion.

   Skip if no @e2e scenarios or no-test mode.

8. On completion or pause, show status

   If all done: update status.yaml phase to verify, then run node <skill-dir>/scripts/validate-beat.mjs --file beat/changes/<name>/status.yaml and fix anything it reports.

   ## Implementation Complete
   
   **Change:** <name>
   **Scenarios:** N/N implemented with tests
   **Preset:** <preset> (or "upgraded minimal → standard: <reason>")
   
   Suggested next steps:
   - `/beat:verify` -- validate implementation against artifacts
   - `/beat:archive` -- sync features and archive the change (run before opening the PR; archive is the last commit on the branch)

   In fix-from-verify mode, report fixed/open counts instead of scenarios and suggest /beat:verify <name> (verify decides between incremental and full, and the round it is on).

   Then end with the handoff block from references/handoff-report.md (next: /beat:verify <name>, or the blocker that paused the run). The suffix carries sensitive from step d3 and blocked-on as none, decision (brief printed above the block) or env. Do not push.

Testing Rule: Conditional TDD

In TDD mode (default when testing.required is true or unset):

• For every Scenario in every .feature file: there MUST be a corresponding automated test
• @e2e scenarios → e2e test or step definitions (using project's e2e framework)
• @behavior scenarios → test with @feature/@scenario annotations + @covered-by comment in .feature
• The test MUST be executable (not just a skeleton)
• The test framework: testing.behavior (for @behavior) or testing.e2e (for @e2e) from config, or auto-detect from codebase
• If the project has a BDD runner (Cucumber, pytest-bdd, etc.), generate step definitions that bind directly to .feature files

In proposal-driven mode (gherkin skipped):

• Tests are driven by proposal.md success criteria and risk points
• Each risk point should have corresponding test coverage
• No annotation conventions (no features to link to)

In no-test mode (testing.required: false):

• Tests are not required. Implementation code is written directly.
• Developers may still write tests voluntarily using testing.behavior/testing.e2e if specified.

Guardrails

• Never implement without reading artifacts first (features in gherkin-driven, proposal in proposal-driven)
• In TDD mode: always write test before implementation
• For @behavior scenarios: always add @covered-by annotation to .feature after writing the test
• For @behavior scenarios: always add @feature/@scenario annotations in the test file
• Keep each change scoped to one scenario/task
• Update task checkbox immediately after completing each task
• Pause on errors, blockers, or unclear requirements -- don't guess
• If implementation reveals issues with features/design, suggest updating artifacts
• Never push; archive is the last commit on the branch
• On minimal/technical changes, check preset_upgrade thresholds after every task