# Bdd

> Behavior-first feature development — use when building new capabilities, continuing feature work, or when work introduces new state or multiple user flows. Discovers desired behavior through examples and scenarios before implementation. Do NOT use for bug fixes, typos, or small isolated changes.

- Skill: `arcadeai/bdd-2` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add arcadeai/bdd-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/arcadeai/bdd-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ArcadeAI (https://skillmd.com/u/arcadeai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/arcadeai/bdd-2

---


# BDD Orchestrator

Behavior-first development for features. Discovery → Scenarios → Implementation.

Define the behavior before implementing it. When unsure whether work is a feature, default to a task (TDD directly) — the user can `$safeword:bdd` to override.

## Phase Tracking

Features progress through phases. Track in ticket frontmatter:

```yaml
---
type: feature
phase: implement # intake | define-behavior | scenario-gate | plan-implementation | implement | verify | done
---
```

**Phase meanings:**

| Phase                 | What happens                                      | Details                                                     |
| --------------------- | ------------------------------------------------- | ----------------------------------------------------------- |
| `intake`              | Context check, discovery                          | [DISCOVERY.md](references/DISCOVERY.md)                     |
| `define-behavior`     | Writing Given/When/Then                           | [SCENARIOS.md](references/SCENARIOS.md)                     |
| `scenario-gate`       | Validating scenarios                              | [SCENARIOS.md](references/SCENARIOS.md)                     |
| `plan-implementation` | Implementation design record                      | [PLAN_IMPLEMENTATION.md](references/PLAN_IMPLEMENTATION.md) |
| `implement`           | Outside-in TDD                                    | [TDD.md](references/TDD.md)                                 |
| `verify`              | Evidence gate: $safeword:verify + $safeword:audit | [VERIFY.md](references/VERIFY.md)                           |
| `done`                | Close ticket                                      | [DONE.md](references/DONE.md)                               |

**Update phase when:**

- Completing a BDD phase → set next phase
- Scenario-gate complete → offer the optional `$safeword:spike` checkpoint only for an eligible build-only kill-risk, then set `plan-implementation` (impl-plan authoring, proof plan + sequencing live there)
- Plan reviewed (impl-plan.md valid, status planned) → set `implement`
- All scenarios pass → set `verify`
- $safeword:verify + $safeword:audit complete (verify.md exists) → set `done`

### Phase-exit review (Tier 2)

The **scenario-gate exit requires** `review-spec` in Review mode. That skill owns
the scenario targets, project context, coordinator protocol, verdict, and review
stamp. This orchestrator owns only routing and the phase transition; do not
restate or independently invoke the scenario-review protocol here.

All BDD review exits share one lifecycle rule: `REVIEW_PENDING` is a live
review, not a verdict. Keep its `review_id`, collect it through the returned
typed `nextActions` until terminal, and never start a replacement review or
advance/stamp while it is pending. `REVIEW_STALE` means rerun against the
current artifacts. Only a terminal verdict may advance the phase.

The plan-implementation exit applies the same discipline to the implementation plan (see [PLAN_IMPLEMENTATION.md](references/PLAN_IMPLEMENTATION.md)'s exit). Other phase exits don't need an independent review by default — they carry their
own guards (intake's user sub-phase gates, implement's tests, the done-gate's
evidence checks). When the **review gate** is enabled (`reviewGate` in
`.safeword/config.json` — e.g. autonomous runs where user gates auto-confirm,
ticket 2VCSZY), every phase advance requires a stamp, or a logged skip reason
(`… --phase <phase> --skip "<why no independent review is needed>"`).

---

## Resume Logic

**Resuming** means reconstruct where the ticket left off and continue. The ticket's `phase:` and the first unchecked ledger item tell you _where_; the last work-log entry tells you _what_. Announce where you're resuming, then continue.

**Resume by phase:**

| Phase                 | Resume action                                                                                  |
| --------------------- | ---------------------------------------------------------------------------------------------- |
| `intake`              | Start understanding (propose-and-converge)                                                     |
| `define-behavior`     | Continue drafting scenarios                                                                    |
| `scenario-gate`       | Continue validating scenarios                                                                  |
| `plan-implementation` | Continue the implementation plan ([PLAN_IMPLEMENTATION.md](references/PLAN_IMPLEMENTATION.md)) |
| `implement`           | Find first unchecked scenario, run TDD                                                         |
| `verify`              | Run $safeword:verify and $safeword:audit, write verify.md                                      |
| `done`                | Close ticket (verify.md must exist)                                                            |

---

## Current Behavior

Understand first and size internally (see SAFEWORD.md "Understanding" and "Sizing") — state the scope read inside your proposal, not as a separate announcement. If the user references an iteration/story/phase from a spec, resume its child ticket at the current phase, or create one and run full BDD if none exists; if a ticket already exists, read its phase and resume there.

**Artifact-first:** before doing a phase's work, create or verify its artifact — intake → `<namespace-root>/tickets/{ID}-{slug}/ticket.md`; define-behavior → the feature source at `features/<slug>.feature` (or the configured `paths.features` directory) plus the R/G/R ledger at `<namespace-root>/tickets/{ID}-{slug}/test-definitions.md`. Then execute the phase using its phase file, and update `phase:` on transition.

---

## Phase Files

Load the appropriate file based on current phase:

| Phase                 | File                                                        |
| --------------------- | ----------------------------------------------------------- |
| `intake`              | [DISCOVERY.md](references/DISCOVERY.md)                     |
| `define-behavior`     | [SCENARIOS.md](references/SCENARIOS.md)                     |
| `scenario-gate`       | [SCENARIOS.md](references/SCENARIOS.md)                     |
| `plan-implementation` | [PLAN_IMPLEMENTATION.md](references/PLAN_IMPLEMENTATION.md) |
| `implement`           | [TDD.md](references/TDD.md)                                 |
| `verify`              | [VERIFY.md](references/VERIFY.md)                           |
| `done`                | [DONE.md](references/DONE.md)                               |

For splitting large features, see [SPLITTING.md](references/SPLITTING.md).