apply

Imported from kirkchen/beat (skills/apply/SKILL.md). Install upstream with npx skills add kirkchen/beat --skill apply. Copyright stays with the author.

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

• Gherkin-driven (default): feature files drive implementation and testing
• Proposal-driven: when gherkin is skipped (technical changes), proposal drives testing

<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

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>

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.

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 adding @covered-by to the .feature file
• Skipping e2e test creation because "the e2e framework is complex to set up"
• Writing a test skeleton instead of an executable test
• Thinking "I'll add the annotations at the end after all scenarios are done"
• 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

Mid-Implementation Triggers (mandatory)

• ADR — hard-to-reverse + surprising + real-trade-off decision not in design.md → write ADR (references/adr-format.md)
• 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];
    "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];
    "All tasks complete" [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" -> "tasks.md exists?";
    "Proposal-driven" -> "tasks.md exists?";
    "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" -> "All tasks complete";
}

Input: Optionally specify a change name. If omitted, infer from context or prompt.

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: ")
   • If multiple exist, use AskUserQuestion tool to let user select

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).

   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).

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: "

   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]

   e. Continue to next

   f. Scenario completion checklist (verify before moving to next scenario):

   For @e2e scenarios (TDD mode):

   • E2e test or step definition exists and is executable
   • Test references the scenario (@feature/@scenario annotations or BDD binding)
   • # @covered-by: <path> annotation added to .feature file (between tag and Scenario line)

   For @behavior scenarios (TDD mode):

   • Test file exists with @feature and @scenario comments
   • # @covered-by: <path> annotation added to .feature file (between tag and Scenario line)
   • Test is executable (not a skeleton)

   For all scenarios:

   • Implementation code handles the scenario's behavior
   • Task checkbox marked complete (if using tasks.md)

   Do NOT move to the next scenario until all applicable items are checked.

   Pause if:

   • Task/scenario is unclear -> ask for clarification
   • Implementation reveals design issue -> suggest updating artifacts
   • Error or blocker -> report and wait

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

   ## Implementation Complete
   
   **Change:** <name>
   **Scenarios:** N/N implemented with tests
   
   Suggested next steps:
   - `/beat:verify` -- validate implementation against artifacts
   - `/beat:archive` -- sync features and archive the change
   

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