Skill: Gherkin Generator (BDD)

Transforms functional requirements → automated iteration → production-ready .feature files.

Quick Input Checklist

Before invoking agents, confirm the user has provided:

• Functional requirements (numbered list, prose, or document)
• Business context (actors, systems, workflows involved)
• Feature/module name (to use in the Feature header)
• (Optional) Example data for realistic test cases

If ANY are missing, ask explicitly. Do not guess or invent.

Execution Flow

User provides requirements
        │
        ├─► Validate inputs (ask if missing)
        │
        ├─► For each iteration (1–5):
        │   ├─ Invoke gherkin-generator-agent
        │   │  (generates/modifies .feature from feedback)
        │   │
        │   └─ Invoke gherkin-reviewer-agent
        │      (validates coverage, syntax, clarity)
        │
        ├─► Approved OR score ≥85?
        │   YES → Deliver .feature file
        │   NO  → Loop: pass feedback to generator
        │
        └─► Max iterations reached?
            YES → Deliver best version + warning
            NO  → Continue loop

Agent Roles

gherkin-generator-agent

Task: Generate or improve a .feature file from requirements and reviewer feedback.

Receives:

• Functional requirements
• Business context
• Previous reviewer feedback (if improving)
• Iteration number

Returns:

• A valid Gherkin code block (.feature format)
• No explanations, only the code

Full instructions: Read agents/generator-agent.md

gherkin-reviewer-agent

Task: Validate Gherkin against requirements, structure, and best practices.

Receives:

• The .feature file to review
• Original functional requirements
• Iteration number

Returns:

• JSON: {approved, score, issues, suggestions, annotated_gherkin}
• severity levels: BLOCKING, MAJOR, MINOR, INFO
• annotation comments on problematic lines

Full instructions: Read agents/reviewer-agent.md

What Gets Approved?

The reviewer approves (approved: true) when:

Approval threshold: approved: true OR score >= 85 (no BLOCKING issues)

Detailed Reference Guides

• Workflow implementation: See references/workflow-implementation.md

  • Step-by-step process for invoking agents
  • Configuration options
  • Delivery format

• Gherkin structure & rules: See references/gherkin-rules.md

  • Feature header, Scenario, Background, Scenario Outline structure
  • Given/When/Then semantics
  • Data realism and examples
  • Tags, language consistency
  • Common anti-patterns to avoid
  • Approval checklist

• Generator agent instructions: See agents/generator-agent.md

  • Input format and fields
  • Output requirements (Gherkin-only block)
  • Generation rules and best practices
  • Handling iterator feedback

• Reviewer agent instructions: See agents/reviewer-agent.md

  • Review dimensions and scoring rubric
  • Severity levels (BLOCKING, MAJOR, MINOR, INFO)
  • Approval criteria
  • Annotation format

Typical Execution

1. User: "Generate Gherkin for our payment validation feature. Here are the requirements..."

2. You:
   - Confirm you have: requirements, context, feature name
   - Ask if anything is vague
   - Invoke gherkin-generator-agent with i=1

3. gherkin-generator-agent returns:
   Feature: Payment Validation
     ...
     [Scenario 1, Scenario 2, etc.]

4. You invoke gherkin-reviewer-agent with that Gherkin

5. gherkin-reviewer-agent returns:
   {
     "approved": false,
     "score": 78,
     "issues": [
       {
         "severity": "BLOCKING",
         "category": "coverage",
         "description": "Refund workflow (FR-05) is not covered",
         "suggestion": "Add a Scenario Outline for refund variations: full, partial, failed"
       },
       ...
     ]
   }

6. You pass feedback to gherkin-generator-agent again (i=2)
   - Generator fixes the gaps and refines steps

7. Reviewer approves (score ≥85, no BLOCKINGs)

8. You deliver:
   - Final .feature file (syntax-highlighted)
   - Score & summary from reviewer
   - Number of iterations
   - Offer to save or refine further

Key Design Principles

• Two-agent separation: Generator creates; Reviewer validates independently
• Automated iteration: No manual back-and-forth; agents loop until approved
• 100% coverage requirement: Every functional requirement must have at least one scenario
• Clear semantics: Given/When/Then roles respected; no UI coupling; no implementation leakage
• Realistic examples: Test data resembles real-world values
• Language consistency: All text in the requirements language
• Independence: Each scenario is self-contained and executable alone
• Maximum safety: 5-iteration limit prevents infinite loops

Common Refinement Requests

After delivery, users may ask for:

• More edge cases: Re-invoke with updated requirements and a note to expand error scenarios
• Different language: Change requirements to target language; re-run from iteration 1
• Tag reorganization: Reviewer can adjust tags in next iteration if coverage logic unchanged
• Background consolidation: If 3+ scenarios share setup, suggest adding Background in next iteration
• Scenario Outline conversion: If similar scenarios exist, suggest using Outline with Examples

Example Input (Functional Requirements)

Module: User Registration

Requirements:
1. Users can register with email and password
2. Email validation: must be in format user@domain.com
3. Password must be at least 8 characters
4. Duplicate emails are rejected with an error message
5. After successful registration, a confirmation email is sent
6. Users receive an error if they submit empty fields

Business Context:
- Actor: New user (unauthenticated)
- System: User management service
- Integrations: Email service for confirmation

Example Output (Approved .feature File)

Feature: User Registration
  As a new user
  I want to create an account with email and password
  So that I can access the system

  @happy-path @smoke
  Scenario: User successfully registers with valid email and password
    Given I am on the registration page
    When I enter the email "alice@example.com"
    And I enter the password "SecurePass123"
    And I submit the form
    Then the account for "alice@example.com" is created
    And a confirmation email is sent to "alice@example.com"

  @error-handling
  Scenario: Registration fails when email already exists
    Given a user with email "bob@example.com" is already registered
    When I enter the email "bob@example.com"
    And I enter the password "SecurePass123"
    And I submit the form
    Then I see the error "Email is already registered"
    And no new account is created

  @edge-case
  Scenario Outline: Validation errors for invalid inputs
    Given I am on the registration page
    When I enter the email "<email>"
    And I enter the password "<password>"
    And I submit the form
    Then I see the error "<error_message>"

    Examples:
      | email              | password | error_message                    |
      |                    | Pass123! | Email is required                |
      | invalid-email      | Pass123! | Email format is invalid          |
      | test@example.com   |          | Password is required             |
      | test@example.com   | short    | Password must be at least 8 characters |

Session Notes

• Track iterations performed (helps explain delays)

• Note any assumption you made about requirements (build with user for next iteration)

• If max iterations reached without approval, deliver best version and offer to refine specific dimensions

• references/gherkin-best-practices.md