This skill NEVER reads files outside docs/specs/.
No access to src/, app/, lib/, or any application directory.
If information is missing, ASK the user — never infer it from code.

undefined

The **Endpoint map** section is the most important: it explicitly maps scenarios → interface, forcing the dev to declare the contract instead of letting the skill deduce it from code.

---

docs/
  specs/
    package.json              ← cucumber.js (+ playwright if needed)
    cucumber.js               ← cucumber config
    CONVENTIONS.md
    SPEC-INTERFACE.md         ← interface contract (only source of system info)
    features/
      <domain>/<feature>.feature
    step-definitions/
      <domain>/<feature>.steps.js
    support/
      hooks.js                ← Before/After setup and teardown
      world.js                ← shared state across steps
    .env.test.example         ← required env vars, no secrets

SPEC-INTERFACE.md exists?
├── YES → read the file
│         ↓
│    all necessary information present?
│    ├── YES → proceed to Phase 2
│    └── NO → ask only the missing gaps, update the file
│
└── NO → enter interview mode
          generate SPEC-INTERFACE.md at the end
          proceed to Phase 2

Found 3 scenarios without step definitions:
  - auth/login.feature: "login with expired token"
  - payments/checkout.feature: "checkout with empty cart" (new)
  - payments/checkout.feature: "duplicate order submission" (new)
Generating...

// Scenario: <scenario name from .feature>
Given('a registered user exists with email {string}', async function(email) {
  // TODO: adjust to your seed/fixture mechanism
  this.user = await createTestUser({ email });
});

When('they attempt login with incorrect credentials', async function() {
  // URL from SPEC-INTERFACE.md endpoint map
  this.response = await fetch(`${process.env.BASE_URL}/auth/login`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email: this.user.email, password: 'wrong' })
  });
});

Then('the operation fails with an authentication error', async function() {
  assert.strictEqual(this.response.status, 401);
});

// Scenario: <scenario name from .feature>
Given('a registered user exists', async function() {
  // TODO: adjust to your seed/fixture mechanism
  this.user = await createTestUser();
});

When('they attempt login with incorrect credentials', async function() {
  // Path from SPEC-INTERFACE.md web entry points
  await this.page.goto(`${process.env.WEB_URL}/login`);
  await this.page.fill('[data-testid="login-email"]', this.user.email);
  await this.page.fill('[data-testid="login-password"]', 'wrong');
  await this.page.click('[data-testid="login-submit"]');
});

Then('the operation fails with an authentication error', async function() {
  await expect(this.page.locator('[data-testid="login-error"]')).toBeVisible();
});

// Scenario: <scenario name from .feature>
When('they run the export command', async function() {
  this.cliOutput = await exec(`node cli.js export --user=${this.user.id}`);
});

Then('the export succeeds', async function() {
  assert.strictEqual(this.cliOutput.exitCode, 0);
});

{
  "name": "specs",
  "private": true,
  "scripts": {
    "test": "cucumber-js",
    "test:tag": "cucumber-js --tags"
  },
  "dependencies": {
    "@cucumber/cucumber": "^10.0.0",
    "node-fetch": "^3.0.0"
  }
}

module.exports = {
  default: {
    paths: ['features/**/*.feature'],
    require: ['step-definitions/**/*.steps.js', 'support/**/*.js'],
    format: ['progress-bar', 'html:reports/cucumber-report.html'],
    parallel: 2
  }
}

BASE_URL=http://localhost:3000

6. Add to the project root `package.json` (if it exists):
```json
"test:bdd": "cd docs/specs && npm test"

CI red for 404 / element not found
   → dev updates SPEC-INTERFACE.md
   → /groundwork verify <feature>   (regenerates step definitions)
   → CI green

Generated:
  docs/specs/step-definitions/auth/login.steps.js        (3 scenarios)
  docs/specs/step-definitions/payments/checkout.steps.js  (2 scenarios)

Stubs (pending):
  docs/specs/step-definitions/auth/login.steps.js        → "login with biometric" (@pending)

Skipped:
  payments/checkout.feature → "guest checkout" (@out-of-scope)

Obsolete (no matching scenario — not deleted):
  docs/specs/step-definitions/auth/register.steps.js     → "register with invite code"

Next steps:
  1. Copy docs/specs/.env.test.example → docs/specs/.env.test and fill in values
  2. Review // TODO: comments in generated files
  3. Add the required selectors (see prompt below)
  4. cd docs/specs && npm install && npm test

---
The following data-testid attributes are required by the BDD step definitions.
Add them to the corresponding UI elements in the application code.

Page: /login
  - data-testid="login-email"       → email input field
  - data-testid="login-password"    → password input field
  - data-testid="login-submit"      → submit button
  - data-testid="login-error"       → error message container (visible on auth failure)

Page: /checkout
  - data-testid="checkout-card"     → credit card input
  - data-testid="checkout-submit"   → place order button
  - data-testid="checkout-success"  → order confirmation message
---