Skip to content
Skills Library
Programming · Building & coding

bdd-coder

/bdd-coder

BDD-style implementation agent. Use when the user gives ANY coding instruction — natural-language, explicit Task ID, or custom task list. Always spawns checklist-builder first to generate a checklist, then runs BDD implementation. Examples: "implement X", "add function Y", "create Z", "write code for W", "implement task T01-02", "run bdd-coder", "start BDD implementation". Do NOT commit or push — implementation only, no git operations. Do NOT implement multiple tasks in one invocation — one task per call.

Repository
deckrd ↗
Licence
MIT
Last repository change
23.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
18
Scripts
1
HTML comments
3
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 23.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.
  • SKILL.md zawiera komentarze HTML (3). Nie widać ich w podglądzie Markdown, a model je czyta.

Scripts: assets/templates/shell-header.tpl.sh

What it does and when to use it

BDD-style implementation agent. Use when the user gives ANY coding instruction — natural-language, explicit Task ID, or custom task list. Always spawns checklist-builder first to generate a checklist, then runs BDD implementation. Examples: "implement X", "add function Y", "create Z", "write code for W", "implement task T01-02", "run bdd-coder", "start BDD implementation". Do NOT commit or push — implementation only, no git operations. Do NOT implement multiple tasks in one invocation — one task per call.

Triggers from the description

implement Xadd function Ycreate Zwrite code for Wimplement task T01-02run bdd-coderstart BDD implementation
Original author description

BDD-style implementation agent. Use when the user gives ANY coding instruction — natural-language, explicit Task ID, or custom task list. Always spawns checklist-builder first to generate a checklist, then runs BDD implementation. Examples: "implement X", "add function Y", "create Z", "write code for W", "implement task T01-02", "run bdd-coder", "start BDD implementation". Do NOT commit or push — implementation only, no git operations. Do NOT implement multiple tasks in one invocation — one task per call.

How it works

  1. Skill Announcement (REQUIRED)
  2. Before You Begin (REQUIRED)
  3. Execution Flow
  4. References
Original SKILL.md headings · 229 lines, 1,605 words
SKILL.md preview
---
name: bdd-coder
description: >
  BDD-style implementation agent. Use when the user gives ANY coding instruction —
  natural-language, explicit Task ID, or custom task list.
  Always spawns checklist-builder first to generate a checklist, then runs BDD implementation.
  Examples: "implement X", "add function Y", "create Z", "write code for W",
  "implement task T01-02", "run bdd-coder", "start BDD implementation".
  Do NOT commit or push — implementation only, no git operations.
  Do NOT implement multiple tasks in one invocation — one task per call.
metadata:
  author: aglabo
  version: 0.6.0
  license: MIT
---

<!-- textlint-disable
  ja-technical-writing/sentence-length -->

# bdd-coder

Implements tasks using strict BDD: Red → Green → Refactor.
Always generates a checklist first via checklist-builder, then delegates BDD implementation to bdd-coder.

## Skill Announcement (REQUIRED)

Before every phase, YOU MUST output:

> "I am executing /bdd-coder:bdd-coder [TASK_ID] — Phase [N]: [Phase Name]."

No announcement = violation. Restart with announcement.

## Before You Begin (REQUIRED)

Raise ALL questions before writing any code. Ask NOW if any of the following are unclear:

- Task scope or acceptance criteria
- Ambiguous specs
- Implementation approach or dependencies

Once Phase 1 (Checklist Build) starts, stop asking scope questions.

## Execution Flow

bdd-coder is an orchestration layer with the following fixed phase order:

| Phase | Name               | Agent                     | What happens                                                                   |
| ----- | ------------------ | ------------------------- | ------------------------------------------------------------------------------ |
| 0     | Environment        | explore-agent             | Detect language, test framework, lint, type-check setup                        |
| 1     | Checklist Build    | checklist-builder         | Generate checklist from instruction or Task ID                                 |
| 2     | Dependency Map     | bdd-coder                 | Classify checklist tasks into serial / parallel groups                         |
| 3     | bdd-coder Dispatch | bdd-coder                 | Spawn bdd-coder per task; collect status reports                               |
| 4     | Quality Gate       | bdd-coder + code-reviewer | Global lint + type-check + all tests pass, then code review                    |
| 5     | Done Check         | bdd-coder                 | Confirm all checklist items complete; check off tasks.md and write back status |
| 6     | Session End        | bdd-coder                 | Reset state; remind user to commit manually                                    |

Gate Rule: phases must run in order. No skipping.

All tests MUST pass at Phase 4. No exceptions.
Do NOT commit after completion — user commits manually.

### Phase 1: Checklist Build

Always spawn **checklist-builder** with the user's instruction or Task ID.

| Input type            | checklist-builder behavior                                    |
| --------------------- | ------------------------------------------------------------- |
| Natural-language      | Analyze instruction, decompose into BDD tasks, generate file  |
| Task ID (e.g. T01-02) | Read tasks.md entry, expand into BDD checklist, generate file |
| `--checklist <path>`  | Skip checklist-builder, use the specified existing file       |

Output: `.local/deckrd/temp/tasks/<slug>-<adjective>-checklist.md`

If checklist-builder reports `BLOCKED` (a Task ID's Case lists more than one input):

1. Do NOT proceed to Phase 2 — no checklist was written.
2. Report the `BLOCKED` line to the user verbatim, with the remediation:
   split the Case in tasks.md via `/deckrd tasks`, then re-run bdd-coder with the Task ID.
3. End the session (Phase 6). Do NOT expand the inputs yourself or fall back to a natural-language checklist.

### Phase 3: bdd-coder Dispatch

Pass the following context to each bdd-coder instance:

| Item              | Content                             |
| ----------------- | ----------------------------------- |
| Task ID           | e.g. `T-01-02-01`                   |
| Task description  | Full Given/When/Then from checklist |
| Quality gate cmds | Commands table from ENV PROFILE     |
| Checklist path    | Path to generated checklist file    |

Do NOT pass: session-wide context, other tasks' info, or session.json.

If bdd-coder reports `BLOCKED`:

1. Collect the blocking issues from the bdd-coder report.
2. Report to the user with the exact CRITICAL findings and the affected task ID.
3. Wait for one of the following user instructions:
   - Fix and retry: user provides guidance → re-run bdd-coder Phase 3–7 for the same task.
   - Skip task: user decides to defer → mark task as `SKIPPED` and continue with the next task.
   - Abort session: user stops work → end the session and summarize open blockers.

Do NOT proceed to the next task while any task remains `BLOCKED`.

### Phase 4: Quality Gate

Run the global gates, then the code review. Both must be satisfied before Phase 5.

| Gate       | Must pass                                            |
| ---------- | ---------------------------------------------------- |
| Lint       | 0 errors                                             |
| Type check | 0 errors                                             |
| Tests      | ALL PASS (with coverage)                             |
| Review     | code-reviewer returns `PASS` or `PASS_WITH_WARNINGS` |

After the first three gates pass, spawn **code-reviewer ONCE** for the whole session — an
aggregate review over every file changed in Phase 3, not one invocation per task.

| Input           | Value                                                                          |
| --------------- | ------------------------------------------------------------------------------ |
| `task_id`       | The Task ID of this invocation, or `N/A` for multiple tasks                    |
| `changed_files` | Implementation files from the session scope resolved below                     |
| `test_files`    | Test files from that same scope, split by the ENV PROFILE test-file convention |
| `env_profile`   | `.local/deckrd/temp/deckrd-work/env-profile.md` (Phase 0 output)               |
| `coverage_cmd`  | Coverage command from ENV PROFILE                                              |

**Session scope**, in this order:

1. The union of the `CHANGED_FILES` lists that Phase 3 collected from each bdd-coder.
2. If those lists are unavailable, every working-tree change minus the SESSION BASELINE
   captured in Phase 0.

Never send the raw working-tree diff.
理由と "every working-tree change" の定義: [workflow.md](references/workflow.md) — Phase 4。

The per-task CRAP gate and the Phase 4 CRAP gate are intentionally separate.
Do not remove either as a duplicate. 理由: [workflow.md](references/workflow.md) — Phase 4。

Checklist items, CRAP thresholds, and failure handling: [workflow.md](references/workflow.md) — Phase 4.
Agent definition: [agents/code-reviewer.md](../../agents/code-reviewer.md).

The same review is available on demand as `/bdd-coder:bdd-coder-review`; inside this flow it runs here.

#### Where review findings go

| Verdict              | Handling                                                                                                                                                                                            |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PASS`               | Proceed to Phase 5                                                                                                                                                                                  |
| `PASS_WITH_WARNINGS` | Proceed to Phase 5 and include the findings in the Step 5 report block. Do NOT retroactively rewrite Phase 3 statuses or `tasks.md` checkboxes — Phase 5's source of truth stays the Phase 3 report |
| `BLOCKED`            | Do NOT proceed to Phase 5. Present the CRITICAL findings and follow the Phase 3 `BLOCKED` handling (fix and retry / skip / abort)                                                                   |

### Phase 5: Done Check — Task Status Write-back

After all bdd-coder instances in Phase 3 report `DONE` or `DONE_WITH_CONCERNS`,
and Phase 4 quality gate passes, write the implementation status back to the task files.

#### Step 1: Determine per-case completion status

The source of truth is the **Phase 3 status report table** — not the checkbox state of
any file. 理由: [workflow.md](references/workflow.md) — Phase 5。

| Phase 3 status                 | Case result                 |
| ------------------------------ | --------------------------- |
| `DONE` / `DONE_WITH_CONCERNS`  | completed — check it        |
| `BLOCKED` / `SKIPPED` / absent | not completed — leave as is |

Checklist-file items (`[T-XX-YY-ZZ-R]`, `-G`, `-F`) may be read as corroboration,
but MUST NOT override the Phase 3 report: a case reported `DONE` is checked even when
the checklist file still shows `[ ]`.

#### Step 2: Check case checkboxes in tasks.md (Task ID input only)

If the session was started with a Task ID (e.g. `T01-02`), update the `tasks.md`
resolved in Phase 1 (`docs/.deckrd/<namespace>/<module>/tasks/tasks.md`):

1. For each completed case ID from Step 1, normalize it to the canonical
   `T-XX-YY-ZZ` form, then locate its line
   `- [ ] **T-XX-YY-ZZ**: <description>`.
   An invocation-form ID (`T01-02`) names a Scenario, not a case: it covers every
   case line under `T-01-02`.
2. Replace the checkbox marker only: `- [ ]` becomes `- [x]`.
   Leave the description and the `Target` / `Scenario` / `Expected` lines untouched.
3. A line already marked `- [x]` stays as is — the write-back is idempotent.
4. If a completed case ID has no matching line in `tasks.md`, skip it and report it in Step 5.

書式: [write-back-format.md](references/write-back-format.md) — Step 2。

#### Step 3: Recalculate Task Summary from the checkboxes

Update the **Task Summary** table at the top of `tasks.md` for the Test Targets
implemented in this invocation ONLY. Leave every other row untouched — a row set by
hand, or one another session is working on, MUST NOT be recomputed.

For each such Test Target `T-XX`, count its case lines `**T-XX-YY-ZZ**` in `tasks.md`:

| Checked cases | Status                                                    |
| ------------- | --------------------------------------------------------- |
| all           | `done`                                                    |
| some          | `in progress`                                             |
| none          | leave the current Status unchanged (do not write it back) |

書式と `none` 行の意味: [write-back-format.md](references/write-back-format.md) — Step 3、
[workflow.md](references/workflow.md) — Phase 5。

Do NOT modify any part of `tasks.md` other than the case checkbox markers (Step 2)
and the Status column of the affected Test Targets (Step 3).

#### Step 4: Write back to checklist file (all inputs)

Regardless of input type, also update the checklist file:

1. Open `.local/deckrd/temp/tasks/<slug>-<adjective>-checklist.md`
2. For every case reported `DONE` / `DONE_WITH_CONCERNS` in Phase 3, confirm its
   `-R` / `-G` / `-F` items are `[x]`. Check any the bdd-coder instance left behind,
   and list them in the Step 5 report so the gap is visible.
3. Check the Scenario and Target refactor items — these belong to this phase, not to
   the bdd-coder instances, which each see only one Case:
   - `[T-XX-YY-TF]` — when every Case under Scenario `T-XX-YY` has `-R` / `-G` / `-F` at `[x]`
   - `[T-XX-CF]` — when every Scenario under Target `T-XX` has its `-TF` at `[x]`
   - A gate that does not hold yet is normal, not an error: leave the item unchecked
4. In the frontmatter, set `status` of the corresponding Test Target:
   - If the file has a per-target status field, update it
   - If not, add a comment line below the target heading:
     `<!-- status: done -->` or `<!-- status: in-progress -->`

#### Step 5: Report to user

After all write-backs complete, output the STATUS WRITE-BACK and CHECKLIST BACKFILL blocks.

書式: [write-back-format.md](references/write-back-format.md) — Step 5。

## References

- Usage and invocation examples: [workflow.md](references/workflow.md) — Usage
- Full phase details: [workflow.md](references/workflow.md)
- Write-back formats: [write-back-format.md](references/write-back-format.md)
- Error recovery: [troubleshooting.md](references/troubleshooting.md)
- Q&A: [faq.md](references/faq.md)
- BDD sub-agent: [agents/bdd-coder.md](../../agents/bdd-coder.md)
- Code reviewer: [agents/code-reviewer.md](../../agents/code-reviewer.md)
- On-demand review command: [bdd-coder-review/SKILL.md](../bdd-coder-review/SKILL.md)
- Checklist builder: [agents/checklist-builder.md](../../agents/checklist-builder.md)
- Checklist template: [assets/templates/implementation-checklist.tpl.md](assets/templates/implementation-checklist.tpl.md)
Files in this package (18)
  • README.md 4 KB
  • SKILL.md 13 KB
  • assets/dic 1 KB
  • assets/pressure-scenarios.md 4 KB
  • assets/test-quality.md 7 KB
  • assets/testing-anti-patterns.md 8 KB
  • assets/languages/go.md 2 KB
  • assets/languages/rust.md 3 KB
  • assets/languages/shell.md 4 KB
  • assets/languages/typescript.md 3 KB
  • assets/templates/implementation-checklist.tpl.md 7 KB
  • assets/templates/shell-header.tpl.sh 1 KB
  • references/faq.md 4 KB
  • references/implementation.md 1 KB
  • references/troubleshooting.md 24 KB
  • references/workflow.md 16 KB
  • references/write-back-format.md 1 KB
  • scripts/libs 1 KB

Versions

The database has no other skills named bdd-coder.

Database snapshot: 13.11.2026 · package version 2b64f532848a (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100bdd-coder-review
    Run an independent code review on already-implemented code by spawning the code-reviewer agent. Computes CC / CRAP scores per function and gets a codex second opinion on correctness, test quality, and design. Use when the user says "review the code", "コードレビューして", "review what…
  • 91bdd
    [UDS] 引導行為驅動開發(BDD)流程,使用 Given-When-Then 格式撰寫場景
  • 100bdd-patterns
    Use when applying Behavior-Driven Development patterns including Given-When-Then structure, feature files, and acceptance criteria. Use when writing BDD-style tests and specifications.
  • 100playwright-bdd-configuration
    Use when configuring Playwright BDD projects, setting up defineBddConfig(), configuring feature and step file paths, and integrating with Playwright config.
  • 100bdd
    Behavior-Driven Development as a collaboration and specification practice, with pytest-bdd and behave as the bundled automation references. Use when defining behavior through concrete examples or acceptance criteria, writing or reviewing Gherkin .feature files, wiring pytest-bdd…
  • 90behave-skill
    Plan, implement, or review behave bdd work in an existing codebase with compatibility, security, and verification controls. Use when the user explicitly requests behave bdd work.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.