BDD Beads Planner

A rigorous methodology skill for behavior-driven development specification authoring and Beads issue management.

What This Skill Does

1. BDD Specification Engine - Generate Gherkin scenarios from ideas or convert existing requirements
2. 5-Question Refinement - Enforced completeness-focused review at epic, feature, story, and design levels
3. Beads Integration - Create issues with BDD acceptance criteria, manage dependencies, batch process large epics
4. Template Library - Composable atomic scenarios for auth, CRUD, APIs, forms, and error handling

Quick Start Menu

When this skill triggers, present these options:

BDD Beads Planner - What would you like to do?

1. [NEW EPIC] Start a new epic with 5-question refinement
2. [CONVERT] Convert existing requirements/PRD to BDD specs
3. [TEMPLATES] Browse and compose from template library
4. [BEADS] Create Beads issues from existing specs
5. [RESUME] Continue a previous refinement session

---

Core Methodology: 5-Question Refinement

STRICT ENFORCEMENT: Every epic, feature, and story MUST go through 5 completeness-focused questions before BDD specs are generated.

Question Categories (Completeness-Focused)

Category	Purpose	Example
Missing Requirements	What's not specified?	"What happens if the user is already logged in?"
Edge Cases	Boundary conditions?	"What's the maximum file size allowed?"
Stakeholders	Who's affected?	"Should admins see different behavior?"
Technical Constraints	System limitations?	"Are there rate limits or timeouts?"
Business Constraints	Rules or compliance?	"Are there regulatory requirements?"

Workflow

Epic Description
    ↓
5 Questions (explain reasoning for each)
    ↓
User Answers
    ↓
Refined Epic → Features
    ↓
5 Questions per Feature
    ↓
User Answers
    ↓
Features → Stories with BDD
    ↓
5 Questions per Story
    ↓
Final BDD Specs + Beads Issues

See REFINEMENT.md for detailed question templates.

---

BDD Spec Generation

Output Format

All specs use standard Gherkin syntax:

Feature: [Feature Name]
  As a [role]
  I want [capability]
  So that [benefit]

  Background:
    Given [common precondition]

  Scenario: [Specific behavior being tested]
    Given [initial context]
    When [action is performed]
    Then [expected outcome]
    And [additional assertions]

  Scenario Outline: [Parameterized test]
    Given [context with <variable>]
    When [action with <input>]
    Then [outcome with <expected>]

    Examples:
      | variable | input | expected |
      | value1   | in1   | out1     |
      | value2   | in2   | out2     |

Spec Quality Rules

1. One behavior per scenario - Don't test multiple things
2. Independent scenarios - No dependencies between scenarios
3. Declarative, not imperative - Describe WHAT, not HOW
4. User-focused language - Avoid technical jargon
5. Complete coverage - Happy path + edge cases + errors

Implementation Hints (Optional)

When requested, add implementation hints as comments:

Scenario: User logs in successfully
  # Implementation: Use JWT with 24h expiry
  # Endpoint: POST /api/auth/login
  Given a registered user with valid credentials
  When they submit the login form
  Then they should be authenticated
  And redirected to the dashboard

---

Beads Integration

Creating Issues from Specs

Each BDD feature becomes a Beads issue with:

• title: Feature name
• description: As a/I want/So that
• acceptance_criteria: Gherkin scenarios
• design: Implementation hints (if any)
• issue_type: epic | feature | task

Dependency Management

Epic (parent)
├── Feature 1 (blocks Feature 2)
│   ├── Story 1.1
│   └── Story 1.2
└── Feature 2 (blocked by Feature 1)
    └── Story 2.1

Batch Processing

For epics with 20+ stories:

1. Process in batches of 5
2. Show progress summary after each batch
3. Allow pause/resume (state saved to mem0)

---

State Management (mem0)

The skill persists state across conversations:

What's Stored

Key	Content
project_context	Tech stack, conventions, team
current_session	Active refinement level, iteration count
decisions	All 5-question answers and resolutions
preferences	Output format, verbosity settings

Session Resume

Previous session detected:
- Epic: "User Authentication System"
- Level: Feature refinement (3/5 features complete)
- Last activity: 2 hours ago

Continue from where you left off? [Yes/No/Start fresh]

---

Template Library

Composable templates in two tiers:

Atomic Scenarios (Individual Behaviors)

• auth-scenarios.md - Login, logout, registration, MFA
• crud-scenarios.md - Create, read, update, delete
• api-scenarios.md - REST endpoints, pagination
• form-scenarios.md - Validation, submission
• error-scenarios.md - Network, timeout, recovery

Feature Composers (Combined Templates)

• templates/features/ - Pre-composed feature sets

---

Verbosity

This skill uses DETAILED WITH REASONING mode:

• Every question includes WHY it's being asked
• Decisions are explained before being applied
• Conflicts are explicitly flagged with resolution options

---

Conflict Handling

When ambiguities or conflicts are detected:

⚠️ CONFLICT DETECTED

Requirement A says: "Users must verify email before login"
Requirement B says: "Users can login immediately after registration"

These conflict. Please clarify:
1. Email verification required before first login
2. Email verification optional, can login immediately
3. Grace period (e.g., 24h to verify, can login meanwhile)

Resolution is documented and stored.

---

Output Options

Chat Display (Default)

BDD specs shown in conversation, formatted as code blocks.

File Export (On Request)

Save to .feature files:

save-specs → project/features/auth.feature
           → project/features/crud.feature

---

Advanced Topics

• workflows/epic-refinement.md - Full epic workflow
• workflows/batch-processing.md - Large epic handling
• examples/this-session.md - This planning session as example

---

Quick Reference

Start New Epic

"I want to plan a new feature for [description]"

Convert Requirements

"Convert this PRD/user story to BDD: [paste content]"

Use Templates

"Show me auth scenarios" or "Compose a user registration feature"

Create Beads Issues

"Create Beads issues from these specs"

Resume Session

"Continue my previous planning session"