# Apply
> Use when implementing a Beat change — requires gherkin or proposal artifact to be done first
- Skill: `kirkchen/apply` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add kirkchen/apply`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kirkchen/apply/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kirkchen (https://skillmd.com/u/kirkchen)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kirkchen/apply
---
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
**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"
Before any code changes: you MUST invoke superpowers:using-git-worktrees to verify isolation
(should already exist from design/plan; creates one if not).
In TDD mode: you MUST invoke superpowers:test-driven-development.
Invoke in order: worktrees first (verify), then TDD (discipline).
If a prerequisite skill is unavailable (not installed), continue without it — but NEVER skip
because you judged it unnecessary.
**Prerequisites** (invoke before proceeding)
| Superpower | When | Priority |
|-----------|------|----------|
| using-git-worktrees | Verify isolation (should exist from design/plan; creates if not) | MUST |
| test-driven-development | At start, in TDD mode | MUST |
| systematic-debugging | When stuck (3 failed attempts) | SHOULD |
| subagent-driven-development | When tasks.md has multiple independent tasks | SHOULD |
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
| Thought | Reality |
|---------|---------|
| "The change is small, I don't need a worktree" | Worktrees protect against contamination. The worktree should already exist from design/plan — verify, don't skip. |
| "I'll write the test after the implementation, same result" | TDD is about design feedback, not just test coverage. Writing tests after loses the design signal. |
| "This is a refactor, TDD doesn't apply" | Refactors need tests most — they prove behavior is preserved. If testing.required is false, TDD is already skipped. |
| "I'll add @covered-by annotations at the end for all scenarios" | Annotations must be added per-scenario immediately after writing the test. Batching them leads to forgetting. |
| "The e2e test setup is too complex, I'll write a unit test instead" | The scenario is tagged @e2e for a reason. If e2e setup is genuinely blocked, announce the blocker and ask — don't silently downgrade. |
| "This @behavior test is obvious, a skeleton is enough" | Every test must be executable. A skeleton that doesn't run is not a test. |
| "These tasks are small, I'll combine them for efficiency" | Each task is bounded for a reason. Merging recreates the oversized-output problem that decomposition solved. One task = one subagent dispatch. |
| "The existing test is roughly correct, no need to update it" | If scenario steps changed, the test must reflect those changes. An old test passing does not mean the new behavior is correct. |
| "I'll create a new test file, it's faster" | If @covered-by already points to an existing test, creating a new file breaks traceability. Update the existing test. |
## 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
```dot
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//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//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:
### Drive mode: gherkin-driven / proposal-driven
### Execution mode: executor / planner
### Tasks/Scenarios to implement:
1. [source]
2. [source]
...
```
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
@scenario:
```
(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):
```gherkin
@behavior @happy-path
# @covered-by:
Scenario:
```
**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: ` 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: ` 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:**
**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