Bdd Driven Development

BDD-Driven Development

Overview

Drive feature development from BDD acceptance criteria using the complete artifact chain produced by upstream skills. The walking skeleton and project architecture already exist; this skill focuses purely on implementing business features one at a time using BDD-guided TDD.

Two-phase workflow:

1. Planning phase (Step 0 ~ Step 1) — Read all artifacts, generate a prioritized execution plan document in docs/plans/
2. Development phase (Step 2 ~ Step 9) — Implement features one by one based on the execution plan, PRD, and BDD JSON files

Each feature follows the cycle: BDD-to-test translation (RED) → minimal implementation (GREEN) → refactor → BDD verification → git commit → next feature.

Core principle: BDD scenarios define WHAT to verify; TDD discipline ensures HOW code is written. Never write production code without a failing test derived from a BDD scenario.

Technology-stack agnostic: This skill contains zero hardcoded technology choices. All tech-specific details (build commands, test frameworks, directory structure, assertion libraries, mock tools) are read from the architecture document and tech-stack document at the start of each session.

Announce at start: "I'm using the bdd-driven-development skill to implement features from BDD acceptance criteria."

Prerequisites

Before using this skill, verify ALL of the following artifacts exist (produced by upstream skills in order):

1. PRD document — docs/requirements/*-prd.md (from requirement-analysis)
2. BDD JSON files — docs/requirements/*-bdd/*.json (from requirement-analysis)
3. Tech stack document — docs/architecture/*-tech-stack.md (from tech-stack-confirmation)
4. Architecture design document — docs/architecture/architecture.md (from project-architecture-init)
   • Contains module mapping (PRD feature → module → package/directory path)
   • Contains dependency rules (layering and module boundaries)
   • Contains test architecture (test pyramid, frameworks, coverage targets)
5. Walking skeleton — Project compiles, health check passes, baseline tests pass (from project-architecture-init)
6. Coding rules — .claude/rules/*.md (from rules-generation, if completed)

If any prerequisite is missing, stop and inform the user which upstream skill needs to run first.

Input Artifacts

BDD JSON Format

Each BDD file contains one feature with multiple scenarios:

[
  {
    "category": "functional",
    "feature": "F-001 Feature Name",
    "description": "Feature description",
    "overallPass": false,
    "bdd": [
      {
        "scenario": "Scenario name",
        "description": "Scenario description",
        "steps": {
          "given": ["Precondition 1", "Precondition 2"],
          "when": ["Action to perform"],
          "then": ["Expected result 1", "Expected result 2"]
        },
        "passes": false
      }
    ]
  }
]

Architecture Document as Runtime Config

The architecture document (docs/architecture/architecture.md) serves as the runtime configuration for this skill. Read it at the start of every session to extract:

Never assume tech-specific defaults. Always read from the architecture document.

The Process

Step 0: Set Up Isolated Workspace

REQUIRED SUB-SKILL: Use superpowers:using-git-worktrees

Create a worktree for the development session. Branch naming convention:

feature/<prd-basename>-impl

Example: PRD file 2026-02-12-market-api-prd.md → branch feature/market-api-impl

After worktree is ready, verify baseline:

<build-command>   # Must succeed
<test-command>    # Must pass

If baseline fails, report and stop — do not proceed with failing baseline.

Step 0.5: Read Project Context

Before implementing any feature, read the architecture document and tech-stack document to establish the working context for this session:

1. Read docs/architecture/architecture.md — extract:

   • Directory structure (source root, test root, module paths)
   • Dependency/layering rules
   • Feature → module mapping table
   • Test pyramid (unit / integration / e2e classification)
   • Test frameworks and mock/stub tools
   • Coverage targets per layer
   • Architecture fitness function tools

2. Read docs/architecture/*-tech-stack.md — extract:

   • Language and framework
   • Build tool and commands
   • Test runner and assertion library
   • HTTP mock/stub tool (if applicable)
   • Coverage tool

3. Read .claude/rules/*.md (if exists) — note coding standards to follow

4. Establish command cheat sheet for the session:

Build:          <detected-build-command>
Test (all):     <detected-full-test-command>
Test (single):  <detected-single-test-command>
Test (e2e):     <detected-e2e-test-command>
Coverage:       <detected-coverage-command>
Source root:    <detected-source-root>
Test root:      <detected-test-root>

5. Identify E2E test environment requirements

   Determine whether E2E smoke tests require any environment preparation that the user must handle before tests can run. Common requirements include:

   • External service credentials or API keys (environment variables)
   • Docker containers or test databases that must be running
   • Network access to test endpoints
   • Special build profiles or test profiles to activate
   • Port availability for the test server

   If E2E tests require environment preparation, inform the user immediately before writing any E2E test code. Present a clear checklist of what needs to be set up:

   E2E smoke tests require the following environment setup:
   - [ ] <env-var-1>: <purpose>
   - [ ] <service>: <how to start>
   - [ ] <config>: <what to configure>
   
   Please confirm these are available before I proceed with E2E test implementation.
   

   If E2E tests can run self-contained (e.g., using embedded servers and HTTP stubs only), note this and proceed without user confirmation.

This step ensures all subsequent steps use project-appropriate commands and paths, not hardcoded defaults.

Step 1: Generate Execution Plan Document

This step produces a persistent execution plan document at docs/plans/bdd-execution-plan.md. This document becomes the single source of truth for development ordering and progress tracking throughout the entire BDD development cycle.

Step 1.1: Load and analyze all BDD features

1. Read ALL BDD JSON files from the BDD directory
2. Read the PRD Feature List to get MoSCoW priority per feature
3. Read the architecture module mapping to associate features with modules
4. Filter features where overallPass is false
5. Sort by priority using PRD MoSCoW:

Within the same priority level, follow feature ID order (F-001, F-002, ...).

Step 1.2: Review BDD scenarios critically

Before generating the plan, perform a thorough review:

• Cross-check each scenario against the PRD — flag contradictions
• Identify ambiguous given/when/then items that may block test writing
• Verify feature dependencies (does F-002 depend on F-001's output?)
• Identify walking skeleton features that need verification (e.g., auth already implemented)
• Note enum values, data format conventions, and API-specific constraints
• If blocking concerns exist: raise them with user before generating the plan

Step 1.3: Scan walking skeleton status

Inspect the existing codebase to determine:

• Which infrastructure components are already implemented
• Which module directories exist (empty vs. populated)
• Which tests already exist
• Git repository initialization status

Step 1.4: Write the execution plan document

Create the file docs/plans/bdd-execution-plan.md using the template defined in the references/execution-plan-template.md file of this skill. The plan must contain ALL of the following sections:

1. Document header — Generation date, PRD/Architecture/Tech-Stack file references
2. Project Context table — Language, framework, build tool, test framework, mock tool, coverage tool
3. Command Cheat Sheet — All detected build/test/coverage commands
4. Walking Skeleton Status — Checklist of implemented vs. pending infrastructure
5. Feature Execution Order — Phased tables (Phase 0: infra verification, Phase 1: Must, Phase 2: Should, Phase 3: Could) with feature name, module, MCP tool name, scenario count, and status column
6. Feature Dependencies — ASCII diagram showing execution flow and cross-feature dependencies
7. BDD Review Notes — Per-feature technical notes (enum conventions, API constraints, cache behavior, etc.)
8. Per-Feature Development Cycle — RED → GREEN → REFACTOR → VERIFY → COMMIT → REPORT
9. Layered Implementation Order — core → infrastructure → api (read from architecture doc)
10. Test Classification Rules — BDD pattern → test type → test location mapping
11. Coverage Targets — Per-module thresholds from architecture doc
12. Progress Log — Empty append-only table for tracking feature status changes during development
13. Final Verification Checklist — All quality gates that must pass before completion

Step 1.5: Present plan and wait for user confirmation

After writing the plan document, present a summary to the user:

Execution plan generated: docs/plans/bdd-execution-plan.md

Summary:
- Total: N features, M BDD scenarios
- Phase 0 (Infra Verification): X features
- Phase 1 (Must): Y features
- Phase 2 (Should): Z features
- Phase 3 (Could): W features
- Key dependencies: <list critical dependencies>
- BDD review concerns: <list any flagged issues, or "None">

Starting with <first-feature>. Ready to proceed?

Wait for user confirmation before proceeding to Step 2.

If the user requests changes to the plan (reorder, skip features, add notes), update the plan document accordingly and re-present.

Step 1.6: Resume from Existing Plan

If docs/plans/bdd-execution-plan.md already exists when the skill is invoked:

1. Read the existing plan document
2. Check the Status column of each feature in the execution order tables
3. Read the Progress Log section to review the development history
4. Identify the next Pending feature
5. Present a resume summary:

Existing execution plan found: docs/plans/bdd-execution-plan.md

Progress:
- Completed: N/M features
- Next: <feature-id> <feature-name> (module: <module>, N scenarios)

Resume from <feature-id>?

4. On confirmation, skip to Step 2 with the next pending feature
5. The plan document is the source of truth — do NOT re-read all BDD files to determine progress

Step 2: BDD-to-Test Translation (RED Phase)

For the current feature (as determined by the execution plan), translate each BDD scenario into a test case.

Before starting: Update the feature's Status in docs/plans/bdd-execution-plan.md from Pending to In Progress. Also append a row to the Progress Log section: | <feature-id> <feature-name> | Pending | In Progress | Starting RED phase |

Step 2.1: Determine test type per scenario

Use the test pyramid from the architecture document to classify each scenario:

Three test levels explained:

• Unit test — Tests business logic in isolation with mocked dependencies. Fast, no framework context.
• Integration test — Tests the feature's internal dependency chain (e.g., Tool → Service → Client) with stubbed external APIs. May use @SpringBootTest or equivalent, but often excludes the protocol/entry-point layer for speed.
• E2E smoke test — Tests the full application stack including the protocol/entry-point layer (MCP Server, REST controller, gRPC service, CLI dispatcher, etc.). Verifies that features are actually discoverable and invocable by external clients through the real protocol. Must NOT exclude any auto-configuration or framework wiring.

Why E2E smoke tests are critical: Integration tests that exclude the protocol layer (e.g., @EnableAutoConfiguration(exclude = {McpServerAutoConfiguration.class})) can pass even when features are completely invisible to real clients. E2E smoke tests catch registration failures, routing issues, serialization bugs, and configuration problems that only manifest in the full stack.

The specific test framework, mock tool, and assertion library come from the architecture document — do not assume.

Step 2.2: Write test files

Place tests in the architecture-specified test directory. The directory structure and file naming conventions are defined in the architecture document's test section.

Translation rules:

Test naming: Derive descriptive names from the scenario field. Use the naming convention appropriate to the project's language:

• Java/Kotlin: camelCase method names
• Python: snake_case function names
• TypeScript/JavaScript: camelCase or descriptive strings
• Go: TestCamelCase function names
• Rust: snake_case function names

Rules for writing tests:

• One test per BDD scenario
• Test name must clearly describe the scenario
• Unit tests: mock external dependencies, test business logic in isolation
• Integration tests: use the project's HTTP mock/stub tool, test full request flow
• E2E smoke tests: start the full application with ALL auto-configuration enabled, test through the real protocol layer
• Each test must be independently runnable
• Follow the project's existing test patterns and coding rules (.claude/rules/)

Write ALL tests for the current feature before writing any production code.

Step 2.3: Record BDD-to-test mapping

Maintain a mapping record for the current feature to streamline verification in Step 5:

Feature: F-001 Feature Name
  Scenario: "scenario name" → TestClass#testMethodName (unit)
  Scenario: "scenario name" → TestClass#testMethodName (integration)
  ...

This mapping avoids redundant re-discovery during BDD verification and ensures every scenario has a corresponding test.

Step 2.4: Write E2E smoke test (REQUIRED for the first feature; extend for subsequent features)

For the first feature in the execution plan, write at least one E2E smoke test that validates the full protocol stack. For subsequent features, extend the E2E test to cover the new feature's endpoint/tool.

E2E smoke test requirements:

1. Start the full application — Use the project's integration test infrastructure but do NOT exclude any auto-configuration. The entire application stack must be active, including the protocol/entry-point layer (MCP server, REST controllers, gRPC services, etc.).
2. Verify feature discoverability — Confirm the feature is visible to external clients through the protocol layer (e.g., MCP tools/list returns the expected tool, REST endpoint responds to OPTIONS/GET, gRPC reflection lists the service).
3. Invoke through the protocol — Make a real protocol-level request (e.g., MCP tools/call, HTTP request to the actual endpoint) and verify the response.
4. Use real external API stubs — Stub external dependencies (e.g., Binance API) via the same HTTP mock tool used in integration tests, but let all internal wiring remain real.

E2E smoke test anti-patterns to avoid:

• Excluding auto-configuration classes (e.g., @EnableAutoConfiguration(exclude = {...})) — this defeats the purpose
• Directly injecting and calling Tool/Service beans instead of going through the protocol layer
• Skipping E2E because "integration tests already cover it" — they may not cover the protocol registration layer

Technology-agnostic guidance:

• For MCP servers: verify tools/list returns expected tools, then call a tool and assert the response
• For REST APIs: send an HTTP request to the actual endpoint path and assert the response
• For CLI tools: invoke the CLI command and assert stdout/exit code
• For gRPC services: use a gRPC test client to call the service method

The E2E smoke test is the final safety net. If a feature passes unit tests and integration tests but fails the E2E smoke test, it means the wiring between the protocol layer and the business logic is broken. This is exactly the class of bug that E2E tests are designed to catch.

After writing tests, run them:

<single-test-command> <test-file-or-class>

Verify RED:

• All new tests MUST fail
• Failure reason must be "feature not implemented" (class/module/function not found), NOT syntax errors or typos
• If a test passes immediately, it is testing existing behavior — remove or rewrite it
• Compilation/import errors are acceptable at RED phase ONLY if caused by missing production code that will be created in GREEN phase

Step 3: Implement Minimal Code (GREEN Phase)

For each failing test, write the minimum production code to make it pass.

Layered implementation order (per architecture dependency rules):

Read the layering rules from the architecture document. Typical order:

1. Inner/core layer first — Domain models, service interfaces, business logic (pure, no framework dependencies)
2. Infrastructure layer second — External API clients, data access implementations
3. Outer/API layer last — Request handlers, tool definitions, wiring

Rules:

• Implement one scenario at a time (smallest passing increment)
• Run tests after each implementation change
• Do NOT add features, abstractions, or "improvements" beyond what the current test requires
• Do NOT refactor during GREEN phase
• Follow coding rules in .claude/rules/ if they exist
• When all tests for the current feature pass, proceed to REFACTOR

<single-test-command> <test-file-or-class>

If a test fails unexpectedly:

• Use superpowers:systematic-debugging to investigate
• Fix the production code, not the test (unless the test has a genuine defect)

Step 4: Refactor (REFACTOR Phase)

After GREEN, clean up while keeping all tests passing:

• Remove duplication between scenarios' implementations
• Improve naming to match domain terminology from PRD
• Extract shared logic if warranted by actual repetition
• Ensure code follows project coding standards (.claude/rules/)
• Verify layering rules are not violated (as defined in architecture document)

# Verify feature tests still pass
<single-test-command> <test-file-or-class>

# Run full test suite to catch regressions
<full-test-command>

If any test fails after refactoring: Undo the refactoring change and retry with a smaller change.

Step 5: Verify Feature BDD Scenarios

After all scenarios for the current feature pass via automated tests, perform explicit BDD verification to confirm test coverage matches BDD intent.

passes field rule: Do NOT update passes or overallPass in BDD JSON at this step. Only record verification results. Batch update happens in Step 8 after all features pass final verification. This prevents inconsistent state if later features cause regressions.

Step 5.1: Verify using the BDD-to-test mapping from Step 2.3

For each scenario in the BDD JSON, use the mapping record to:

1. Confirm the mapped test method/function exists and is runnable
2. Run the test and record pass/fail
3. Verify assertions cover ALL items in then

Step 5.2: Choose verification method by test type

E2E verification is mandatory. If the feature has no E2E smoke test, verification is incomplete. At minimum, confirm the feature is discoverable through the protocol layer (e.g., appears in tools/list, responds at its endpoint path).

Step 5.3: Record and report

Record verification results per scenario (pass/fail + output summary). Do NOT update BDD JSON yet.

• If all scenarios verified: Mark the feature task as completed, proceed to Step 6
• If any scenario fails: Stop and report the gap/failure with details, ask for guidance, do NOT proceed

Step 6: Commit Feature and Update Plan

After the feature's BDD verification passes (Step 5):

Note: Do NOT include BDD JSON files in this commit. The passes fields are updated in Step 8 after final verification.

# Stage source + tests only (specific files, never git add -A)
git add <source-files> <test-files>

# Commit with descriptive message
git commit -m "$(cat <<'EOF'
feat(<module>): implement <feature-id> <feature-name>

- <N> BDD scenarios implemented and verified
- Unit tests: <count>, Integration tests: <count>, E2E tests: <count>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"

After committing, update the execution plan document:

1. Update the feature's Status in docs/plans/bdd-execution-plan.md from In Progress to Done.
2. Append a row to the Progress Log section: | <feature-id> <feature-name> | In Progress | Done | N/N scenarios, commit <short-hash> |

Commit rules:

• One commit per completed feature
• Commit message uses conventional format: feat(<module>): <description>
• Only commit when ALL tests pass (both feature tests and full suite)
• Stage specific files, never git add -A
• BDD JSON updates are committed separately in Step 8

Step 7: Report and Loop

After committing the feature:

Feature "<feature-id> <feature-name>" complete.
- Module: <module>
- Scenarios: N/N passing
- Tests: X unit + Y integration + Z e2e
- Files changed: <list>
- Commit: <short-hash>
- Verification output:
  ✓ scenario-1: PASS (test method: TestClass#method)
  ✓ scenario-2: PASS (test method: TestClass#method)

Remaining features: M
Next: "<feature-id> <feature-name>" (module: <module>, N scenarios)

Ready for feedback before continuing.

Wait for user feedback. Then return to Step 2 with the next feature from the execution plan.

Step 8: Final Verification and Batch Update BDD Status

After ALL features in the execution plan are implemented:

1. Run the full project test suite (including architecture fitness function tests if configured):

<full-test-command>

2. Run E2E smoke tests to verify all features are discoverable and invocable through the protocol layer:

<e2e-test-command>

E2E verification is a hard gate. If E2E smoke tests fail, the application is not usable by real clients regardless of how many unit/integration tests pass. Fix E2E failures before proceeding.

4. Re-run all feature tests to catch cross-feature regressions:

# Run each feature's tests to confirm no regressions
<single-test-command> <feature-1-test>
<single-test-command> <feature-2-test>
...

5. If all tests pass — batch update BDD JSON files:

For each implemented feature, update its BDD JSON file:

• Set each bdd[].passes to true for verified scenarios
• Set overallPass to true for the feature
• Use Write tool to update the entire file atomically

This is the ONLY step where passes fields are updated. This ensures BDD JSON always reflects the true verified state after all features are complete.

6. Commit the BDD JSON updates:

git add docs/requirements/*-bdd/*.json
git commit -m "$(cat <<'EOF'
docs(bdd): mark all implemented features as passing

- Batch update after final verification
- All feature tests and full suite passing

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"

7. Verify all BDD JSON files are complete:

grep -r '"passes": false' docs/requirements/*-bdd/ && echo "FAIL: Some scenarios not passing" || echo "OK: All scenarios passing"
grep -r '"overallPass": false' docs/requirements/*-bdd/ && echo "FAIL: Some features not complete" || echo "OK: All features complete"

8. Verify coverage meets architecture targets (if coverage tool configured):

<coverage-command>
# Compare results against thresholds defined in architecture document

9. Update execution plan: Mark all features as Done in docs/plans/bdd-execution-plan.md. Add a final summary section at the bottom of the plan with total test counts, coverage results, and completion timestamp.

If any verification fails: Fix before proceeding. Do NOT update passes for features with failing tests.

Step 9: Complete Development

REQUIRED SUB-SKILL: Use superpowers:finishing-a-development-branch

Follow that skill to present options (merge, PR, keep, discard) and clean up the worktree.

Priority Decision Table

When to Stop and Ask

STOP immediately when:

• BDD scenario contradicts PRD specification
• Cannot determine correct mock/stub setup from scenario description
• Implementation requires a new module not defined in architecture document
• Architecture dependency rules would be violated by the implementation approach
• Existing tests break and the cause is unclear
• A project dependency is missing from the build configuration

Ask for clarification rather than guessing.

When to Revisit Earlier Steps

Common Mistakes

Writing production code before tests

• Problem: Violates TDD discipline, tests become verification-after-the-fact
• Fix: Delete production code, start with failing test

Updating passes before final verification

• Problem: BDD JSON becomes inconsistent if later features cause regressions on earlier features
• Fix: Never update passes during Step 5. Only batch update in Step 8 after all features pass final verification

Implementing multiple features in one cycle

• Problem: Hard to isolate failures, messy commits, unclear git history
• Fix: One feature per cycle, one commit per feature

Skipping RED verification

• Problem: Test may pass immediately (testing existing behavior, not new feature)
• Fix: Always run tests and confirm they fail before implementing

Over-engineering during GREEN phase

• Problem: Adding abstractions, patterns, or features not required by current test
• Fix: Write the minimum code to pass the failing test, refactor after GREEN

Violating architecture layering

• Problem: Inner layer imports from outer layer; modules reference each other's internals
• Fix: Follow dependency rules from architecture document; architecture fitness function tests will catch violations

Putting all tests as integration tests

• Problem: Slow test suite, violates test pyramid
• Fix: Unit-test core logic with mocks; integration-test only when running server or external stubs are needed

Excluding protocol layer in integration tests (no E2E coverage)

• Problem: Integration tests that exclude auto-configuration (e.g., @EnableAutoConfiguration(exclude = {McpServerAutoConfiguration.class})) test only the inner dependency chain (Tool → Service → Client), but never verify that features are registered and reachable through the actual protocol layer. All tests pass, but the application exposes zero features to real clients.
• Fix: Write at least one E2E smoke test per feature that starts the full application stack (no auto-configuration exclusions), verifies the feature is discoverable through the protocol (e.g., tools/list, endpoint routing), and invocable end-to-end. The E2E smoke test is the only test that catches wiring/registration failures between the protocol layer and business logic.

Hardcoding tech-specific commands

• Problem: Skill becomes tied to a single tech stack
• Fix: Always read build/test/coverage commands from architecture document and build config at session start

Not updating execution plan status

• Problem: Plan document becomes stale, cannot resume sessions reliably
• Fix: Always update Status column in plan when starting (In Progress) and finishing (Done) a feature. Always append a row to the Progress Log at each status change

Integration

Upstream skills (must complete before this skill, in order):

1. requirement-analysis — Produces PRD and BDD JSON files
2. tech-stack-confirmation — Technology decisions, ADRs
3. project-architecture-init — Architecture document, walking skeleton, fitness function tests, CI pipeline
4. rules-generation (optional) — Project coding rules in .claude/rules/

Sub-skills used during execution:

• superpowers:using-git-worktrees — REQUIRED: Set up isolated workspace (Step 0)
• superpowers:test-driven-development — Core TDD discipline for Steps 2-4
• superpowers:systematic-debugging — When tests fail unexpectedly
• superpowers:verification-before-completion — Before claiming features complete (Step 5, 8)
• superpowers:finishing-a-development-branch — REQUIRED: Complete development (Step 9)

Artifact locations:

• PRD: docs/requirements/*-prd.md
• BDD: docs/requirements/*-bdd/<feature-name>.json (updated in-place at Step 8 only)
• Architecture: docs/architecture/architecture.md (read-only runtime config)
• Tech stack: docs/architecture/*-tech-stack.md (read-only runtime config)
• Execution plan: docs/plans/bdd-execution-plan.md (generated at Step 1, updated throughout)
• Source and test paths: determined from architecture document at session start