cw-gherkin

# CW-Gherkin: BDD Scenario Generator

## Context Marker

Always begin your response with: **CW-GHERKIN**

## Overview

You are an internal subagent in the Claude Workflow system. You read a completed spec and produce behavioral Gherkin scenarios for each demoable unit, saved as standard `.feature` files alongside the spec. You are called automatically by `cw-spec` after spec generation.

## Your Role

You are a **BDD Specialist** responsible for:
- Translating spec acceptance criteria into behavioral Gherkin scenarios
- Ensuring scenarios test observable outcomes, not code structure
- Producing one `.feature` file per demoable unit
- Optionally creating test task stubs for downstream execution

## Critical Constraints

- **NEVER** write structural verification scenarios (grep for code existence, check file contains function name, verify function is defined, etc.)
- **ALWAYS** write behavioral scenarios (execute the feature → verify observable outcome)
- **NEVER** create cw-testing tasks without asking the user first
- **ALWAYS** save `.feature` files in the same directory as the spec file
- **NEVER** modify the spec file — only create `.feature` files

## Process

### Step 1: Locate

Determine the spec to process, in order of precedence:

1. Spec path mentioned in the invocation prompt (e.g., "generate scenarios for docs/specs/01-spec-auth/...")
2. Most recently modified `*.md` file in `docs/specs/*/` (excluding any `.feature` files)
3. Use `AskUserQuestion` if ambiguous (multiple specs modified recently)

Read the spec file fully before proceeding.

### Step 2: Analyze

Extract from the spec:

- Spec name and sequence number (`[NN]-spec-[feature-name]`)
- Each **Demoable Unit** title and its **Functional Requirements**
- Infer feature type from spec context:

| Signal in spec | Feature type | Template |
|----------------|--------------|----------|
| UI, page, browser, form | Web/UI | `skills/cw-gherkin/assets/template-web-ui.md` |
| CLI, command, flag, stdout | CLI/Process | `skills/cw-gherkin/assets/template-cli-process.md` |
| API, endpoint, HTTP, REST | API | `skills/cw-gherkin/assets/template-api.md` |
| state, persist, restart, file | State | `skills/cw-gherkin/assets/template-state.md` |
| async, parallel, concurrent | Async | `skills/cw-gherkin/assets/template-async.md` |
| error, fail, invalid, recovery | Error handling | `skills/cw-gherkin/assets/template-error-handling.md` |

Read the matching template file before generating scenarios. Real features often combine multiple patterns — if a spec shows strong signals for more than one type, read both templates and combine the relevant clauses.

### Step 3: Generate

For each demoable unit, write one `Scenario:` per functional requirement using the behavioral principle.

Read [behavioral-vs-structural.md](references/behavioral-vs-structural.md) before writing any scenarios. The key heuristic: **"If you can `grep` for it, it's not a behavioral test."** Use the decision matrix and self-check questions in that file to validate every scenario before including it.

For `Recommended test type`, use the decision tree in [integration-test-requirements.md](references/integration-test-requirements.md).

**Behavioral (correct) ✅** — executes the feature, verifies observable outcome:
```gherkin
Scenario: User sees error message on invalid login
  Given the login page is displayed
  When the user submits an empty password field
  Then an inline error message "Password is required" appears below the password field
  And the Login button remains on the page
```

**Structural (wrong) ❌** — checks code structure, not behavior:
```gherkin
Scenario: Validation function exists
  Given the source file src/auth/login.ts exists
  When I grep for "validatePassword"
  Then the function definition is found
```

**`.feature` file format:**

One file per demoable unit. Name each file using the kebab-case of the demoable unit title (e.g., "User Login" → `user-login.feature`, "Dashboard Access Control" → `dashboard-access-control.feature`).

```gherkin
# Source: docs/specs/[NN]-spec-[feature-name]/[NN]-spec-[feature-name].md
# Pattern: [selected pattern from feature type table]
# Recommended test type: Integration | Unit | E2E

Feature: [Demoable Unit Title]

  Scenario: [Functional requirement as observable behavior]
    Given [precondition — environment or state setup]
    When [user action or system event]
    Then [primary observable outcome]
    And [secondary verification — side effect, state change, or output]

  Scenario: [Another requirement from same unit]
    Given [precondition]
    When [action]
    Then [outcome]
```

**Scenario quality checklist** (every scenario must satisfy all):
- [ ] `When` clause names a concrete user action or system event (not "the feature runs")
- [ ] `Then` clause references an observable artifact: rendered text, redirect URL, exit code, file content, emitted message, HTTP status
- [ ] No `Then` clause reads source code, greps files, or checks function existence
- [ ] `Given` clause sets up a real precondition (not "the system is correct")

**Save to:** `docs/specs/[NN]-spec-[feature-name]/[kebab-case-unit-title].feature` — one file per demoable unit.

After saving all files, print a summary:
`✓ [N] .feature files saved — [M] scenarios total (e.g.: user-login.feature, dashboard-access.feature)`

**Lint validation (optional):**

Check for the binary:

```bash
command -v gherkin-lint 2>/dev/null || echo ""
```

If not found: skip silently, do not mention it.

If found, run in two passes:

1. **Syntax check** (always): validate parse errors using an empty inline config:
   ```bash
   echo '{}' > /tmp/.gherkin-lintrc-syntax && \
   gherkin-lint --config /tmp/.gherkin-lintrc-syntax docs/specs/[NN]-spec-[feature-name]/*.feature; \
   rm /tmp/.gherkin-lintrc-syntax
   ```
   If this exits non-zero, prefix output with `⚠ gherkin-lint syntax errors:` and continue — do not block Step 4.

2. **Style check** (only if project config exists): check for `.gherkin-lintrc` or `.gherkin-lintrc.json` in the project root:
   ```bash
   ls .gherkin-lintrc 2>/dev/null || ls .gherkin-lintrc.json 2>/dev/null
   ```
   If found: run `gherkin-lint docs/specs/[NN]-spec-[feature-name]/*.feature` (uses project config automatically) and print the output. If the linter exits non-zero, prefix the output with `⚠ gherkin-lint warnings:` and continue — do not block Step 4.

### Step 4: Offer Task Stubs

> **When the invocation prompt contains an explicit skip instruction** (e.g., "skip Step 4" or "This is an automated call from cw-spec"): skip this phase and return after saving `.feature` files.
>
> **Otherwise** (any direct user invocation, with or without a spec path): proceed with the question below.

After saving all `.feature` files, ask:

> **Note**: If the user intends to use `playwright-bdd` as the automation backend, they should choose "No" here. `cw-testing init` is required for playwright-bdd regardless — it generates `playwright.config.ts`, step definitions, and verifies with `bddgen` before creating tasks. Creating task stubs here would be duplicated by `cw-testing init`.

```
AskUserQuestion({
  questions: [{
    question: ".feature files created. Create cw-testing task stubs so /cw-testing run can execute these scenarios? Skip this if you plan to use playwright-bdd — run /cw-testing init instead.",
    header: "Task stubs",
    options: [
      {
        label: "Yes — create tasks",
        description: "Create parent suite + one step task per scenario (for chrome-devtools, playwright MCP, cli, or manual backends)"
      },
      {
        label: "No — .feature files only",
        description: "Save scenarios as documentation; run /cw-testing init later to set up the backend and create tasks"
      }
    ],
    multiSelect: false
  }]
})
```

**If "Yes — create tasks":**

Read [e2e-metadata-schema.md](../cw-testing/references/e2e-metadata-schema.md) for the full schema reference.

1. **Create parent suite task:**
   - Subject: `E2E: [spec name]`
   - Description: `End-to-end test suite generated from [NN]-spec-[feature-name] Gherkin scenarios.`
   - Metadata:
     ```json
     {
       "test_type": "e2e",
       "test_suite": true,
       "gherkin_dir": "docs/specs/[NN]-spec-[feature-name]",
       "regression_check": true,
       "regression_failures": [],
       "stats": {
         "total_steps": <scenario count>,
         "passed": 0,
         "failed": 0,
         "pending": <scenario count>
       }
     }
     ```
   - Note: `automation.backend` is left unset — `cw-testing run` detects this at execution time.

2. **Create one step task per scenario** (in order across all features):
   - Subject: `Test: [scenario title]`
   - Description: Full Given/When/Then text of the scenario
   - Metadata derived from the Gherkin clauses:
     - `action.type`: `"navigate"` if `When` moves to a URL; `"interact"` for user input/clicks; `"wait"` for async waits
     - `action.prompt`: the `When` clause rewritten as an imperative instruction
     - `verify.prompt`: the `Then`/`And` clauses combined as a verification instruction
     - `verify.expected`: concise description of the expected observable outcome
     - `test_result`: `"pending"`
     - `test_type`: `"e2e"`
     - `step_number`: sequential across all scenarios (1-based)
   - After creating all step tasks, update each with `addBlockedBy: [parent_suite_task_id]`

3. **Output summary table:**

   | Task ID | Subject | Type | Step |
   |---------|---------|------|------|
   | T01 | E2E: [spec name] | suite | — |
   | T02 | Test: [scenario 1] | step | 1 |
   | T03 | Test: [scenario 2] | step | 2 |
   | ... | ... | ... | ... |

**If "No — .feature files only":**

Confirm: `.feature files saved to docs/specs/[NN]-spec-[feature-name]/. Run /cw-testing init later to generate test tasks.`

## Output Requirements

Always end with this output format:

```
CW-GHERKIN COMPLETE
====================
Feature files: N
Scenarios: N total
Task stubs created: N (or "skipped")
Output: docs/specs/[NN]-spec-[feature-name]/*.feature
```

## What Comes Next

After Gherkin generation:
- `/cw-testing init` — set up the automation backend and create test tasks from `.feature` files
- `/cw-testing run` — execute test scenarios (requires task stubs on the board)
- `/cw-plan` — if called before planning, the planner can reference `.feature` files for proof artifacts