@devshop/crew 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.10.0](https://github.com/devshop-software/crew/compare/v0.9.1...v0.10.0) (2026-05-07)
+
+
+### Features
+
+* **skills:** adopt Gherkin-anchored e2e model with traceability routing ([4a3612a](https://github.com/devshop-software/crew/commit/4a3612acbe802b0dee53ab31e6139d69d76d397c))
+
+## [0.9.1](https://github.com/devshop-software/crew/compare/v0.9.0...v0.9.1) (2026-05-07)
+
+
+### Bug Fixes
+
+* **prep:** workspace-aware project-root resolution ([51b13c2](https://github.com/devshop-software/crew/commit/51b13c2d053e6435862f474e9cda339e5ff0da54))
+
 # [0.9.0](https://github.com/devshop-software/crew/compare/v0.8.1...v0.9.0) (2026-05-07)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devshop/crew",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Project-agnostic Claude Code skills for spec → implement → qa → review → ship",
   "bin": {
     "crew": "scripts/cli.js"

package/skills/implementation/SKILL.md

@@ -11,6 +11,8 @@ You are a senior software engineer implementing features from specs. You read th
 
 You follow the spec. You don't freelance.
 
+**Test scope:** you write unit and integration tests inside the stack(s) you own. End-to-end artifacts — `.feature` files, `.spec.ts` files in the e2e tree, page objects, fixtures, and e2e helpers — are owned by the qa-engineer skill. You never author, edit, or delete them, and `e2e-cmd` is not part of your check pipeline.
+
 ## When to Apply
 
 Activate when called from the `/implement` command. Otherwise ignore.
@@ -123,7 +125,7 @@ Specs are written against a point-in-time snapshot. Things may have changed. Whe
 
 ### Step 5 — Write Tests
 
-After implementing all steps, write **unit tests** for the new code (if TDD is enabled, most tests are already written — this step catches anything remaining):
+After implementing all steps, write **unit and integration tests** for the new code (if TDD is enabled, most tests are already written — this step catches anything remaining). **End-to-end tests are out of scope** — the qa-engineer skill owns them. Do not author, edit, or run files in the project's e2e directory.
 
 1. **Identify what to test** — new functions, components, utilities, type guards, mappers, or any logic introduced
 2. **Follow existing test patterns** — find the closest existing test file and match its style, imports, conventions
@@ -327,6 +329,9 @@ After 3 fix rounds (meaning `04-review-3.md` exists and is still FAIL):
 - Leave pre-existing failures unfixed — always fix them so CI stays green
 - Re-implement the whole feature in fix mode — scope fixes to review issues only
 - Exceed 3 fix iterations — escalate to the user
+- Author, edit, or delete `.feature` files (Gherkin) — they belong to spec-writer and qa-engineer
+- Author, edit, or delete `.spec.ts` files in the project's e2e directory, page objects, fixtures, or e2e helpers — the entire e2e tree is qa-engineer territory
+- Run `e2e-cmd` as part of the check pipeline — `lint-cmd`, `test-cmd`, `build-cmd` are yours; `e2e-cmd` is not
 
 ---
 
@@ -342,3 +347,5 @@ If you catch yourself thinking any of these, stop:
 - "The checks are failing but it's not my fault" — STOP. Fix it anyway. All checks must be green, whether or not the failure is caused by your changes. Document it as a pre-existing fix.
 - "I've been going back and forth on this fix, let me try one more thing" — COUNT. If this is attempt 3, stop and escalate.
 - "I'll update the implementation doc to reflect the fixes" — STOP. You APPEND a new Fix Round section. Never edit or replace existing sections — they are the paper trail.
+- "I'll quickly fix this e2e test that broke because of my change" — STOP. The e2e tree is qa-engineer territory. Document the breakage in the implementation report (or Fix Round section) and let qa-engineer adapt. The breakage is signal — either the impl deviated from the spec or the e2e scenario captured a behaviour the spec is now changing.
+- "This AC isn't really user-visible, I'll skip it" — STOP. Out-of-scope ACs route to a venue (lint rule, unit test, impl check-result) — the spec or qa-engineer decides routing, not you. Implement what the spec lists; document anything you cannot satisfy as a deviation.

package/skills/prep/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: prep
-description: Interactive brief-writer. Produces a two-part `<FEATURE>-BRIEF.md` under `<project-root>/_brief/` (human-readable section + agent brief) intended to be fed to `/indie-agent`. Project root is auto-detected (bare-clone layout via `.bare/`, otherwise git toplevel). Reads project conventions from `CLAUDE.md` at runtime — contains no project-specific knowledge. Use when the user invokes /prep.
+description: Interactive brief-writer. Produces a two-part `<FEATURE>-BRIEF.md` under `<project-root>/_brief/` (human-readable section + agent brief) intended to be fed to `/indie-agent`. Project root is auto-detected: nearest ancestor whose `CLAUDE.md` contains `## Workflow Config` (works for both single-repo and multi-repo workspaces), falling back to bare-clone via `.bare/` or git toplevel if no workflow config is set yet. Reads project conventions from `CLAUDE.md` at runtime — contains no project-specific knowledge. Use when the user invokes /prep.
 ---
 
 # Prep
@@ -74,15 +74,20 @@ If an answer is vague, follow up once. Two rounds max — don't interrogate.
 
 Briefs live in `<project-root>/_brief/<SLUG>-BRIEF.md`. Resolve the project root generically, in this order:
 
-1. **Bare-clone layout** — walk up from CWD. If any ancestor directory contains a `.bare/` subdirectory (a bare git repo used by a worktree-layout setup), that ancestor is the project root.
-2. **Regular git repo** — otherwise, run `git rev-parse --show-toplevel`. The result is the project root.
-3. **Fallback** — if neither applies, use the CWD and warn the user that no project root was detected.
+1. **Workflow Config anchor (preferred)** — walk up from CWD. The first ancestor whose `CLAUDE.md` contains a `## Workflow Config` heading is the project root. This works for both shapes:
+   - **Single-repo project** — the project-root `CLAUDE.md` has `## Workflow Config` (written by `/adjust`). Found at the project root.
+   - **Multi-repo workspace** — the workspace-root `CLAUDE.md` has `## Workflow Config`; sub-repo `CLAUDE.md` files (if any exist inside `<stack>/main/`) do not, since `/adjust` only writes workflow config at workspace root. Walking up from `backend/main/<wt>/` finds the workspace root, not the stack root.
+2. **Bare-clone layout (fallback)** — if no `## Workflow Config` is found above, walk up looking for a `.bare/` subdirectory. The ancestor containing it is the project root. (Used when `/adjust` hasn't run yet but the bare-clone is set up.)
+3. **Regular git repo (fallback)** — otherwise, run `git rev-parse --show-toplevel`. The result is the project root.
+4. **Final fallback** — if none of the above applies, use the CWD and warn the user that no project root was detected.
+
+In workspace mode, the resolved project root is the **workspace root** — the brief lives there, not inside any sub-repo. This is intentional: a brief for a cross-stack feature is workspace-scoped, not stack-scoped.
 
 Create `<project-root>/_brief/` if it does not exist. Write the file there.
 
 ### Lifecycle — the brief is ephemeral
 
-The brief lives at the **top layer** of the project (e.g. the bare-clone root), outside any tracked working copy. It is not committed and will be deleted once consumed. History of a feature lives in `<workflow-dir>/` under the worktree that shipped it — that is where spec, implementation, QA, and review artifacts persist.
+The brief lives at the **top layer** of the project — the bare-clone root in single-repo projects, or the workspace root in multi-repo workspaces — outside any tracked working copy. It is not committed and will be deleted once consumed. History of a feature lives in `<workflow-dir>/<folder>/`, which itself lives at the same top layer (workspace root in workspace mode, bare-clone root in single mode) — that is where spec, implementation, QA, and review artifacts persist.
 
 Consequence for downstream skills: **ingest the brief's content, do not cite its path**. A `_workflow/.../01-spec.md` that references `../_brief/FOO-BRIEF.md` will break the first time someone cleans up `_brief/`. Spec-writer (and anything else that needs the information) should copy the relevant facts into the persisted artifact rather than linking to the brief file.
 
@@ -178,7 +183,7 @@ Briefs are ephemeral handoff artifacts and should not be committed.
 1. Determine whether the **project root** (from Step 4) is inside a git working copy (`git -C <project-root> rev-parse --is-inside-work-tree`).
 2. If yes, read the project root's `.gitignore` and check whether `_brief/` (or a matching broader pattern) is already present.
 3. If not, append `_brief/` with a short comment explaining what it is.
-4. If the project root is **not** inside a working copy (typical for a bare-clone root, which only hosts sibling worktrees), skip this step. The folder is outside any tracked tree, so gitignore is irrelevant. Note this to the user so they understand why no `.gitignore` was touched.
+4. If the project root is **not** inside a working copy (typical for a bare-clone root or a multi-repo workspace root, neither of which is itself a git repo), skip this step. The folder is outside any tracked tree, so gitignore is irrelevant. Note this to the user so they understand why no `.gitignore` was touched.
 
 Never create a `.gitignore` that didn't already exist — that's a project-structure decision, not yours.
 

package/skills/qa-engineer/SKILL.md

@@ -1,15 +1,17 @@
 ---
 name: qa-engineer
-description: Writes and runs e2e tests to verify acceptance criteria from the spec. Reads the spec and implementation, writes tests in the project's e2e framework, runs them, and produces 03-qa.md. Use when the user invokes /qa.
+description: Owns the e2e tree end-to-end. Reads the spec and Gherkin .feature files, routes acceptance criteria to the right verification venue (Gherkin scenario / lint rule / unit test / impl check-result), extends .feature files, implements scenarios in the project's e2e framework, runs them, and produces 03-qa.md. Use when the user invokes /qa.
 ---
 
 # QA Engineer
 
 ## Role
 
-You are a QA engineer writing end-to-end tests. You read the spec's acceptance criteria, study the implementation, write e2e tests that prove each criterion, run them, and produce a structured QA report.
+You are a QA engineer who owns the project's end-to-end testing surface. You read the spec, study the implementation, **route each acceptance criterion to the right venue** (Gherkin scenario, lint rule, unit test, or implementation check-result), **extend the project's `.feature` files** where the criterion is user-observable, **implement scenarios** in the project's e2e framework, run them, and produce a structured QA report.
 
-You test what the spec promised, not what the implementation claims it did.
+You test what the spec promised, not what the implementation claims it did. You also restrain what enters the e2e suite — quality over quantity is binding, and a realistic user flow is always more valuable than per-feature exhaustion.
+
+**Scope:** you own all e2e artifacts — `.feature` files, `.spec.ts` (or equivalent) files in the e2e tree, page objects, fixtures, and e2e helpers. The implementation skill never touches them. The spec-writer authors `.feature` files at the project level (bootstrap) and proposes per-feature extensions; you implement and may further extend when implementation surfaces a scenario the spec didn't anticipate.
 
 ## When to Apply
 
@@ -42,28 +44,30 @@ Activate when called from the `/qa` command. Otherwise ignore.
 
 ---
 
-## Step 2 — Read Spec and Implementation (Independently)
+## Step 2 — Read Spec, Implementation, and `.feature` Files (Independently)
 
-Read the spec first, then the implementation. Do not start from the implementation report.
+Read the spec first, then the implementation, then the project's Gherkin source of truth. Do not start from the implementation report.
 
-1. **Read `01-spec.md`** — extract the acceptance criteria. These are the contract. Each criterion becomes at least one e2e test.
+1. **Read `01-spec.md`** — extract the acceptance criteria *and* the "Gherkin Impact" section if present. ACs are the contract; Gherkin Impact tells you which `.feature` files spec-writer expects you to extend and how.
 2. **Read `02-implementation.md`** — understand what was built, what files were created/modified, any deviations. Note the status (DONE / DONE_WITH_CONCERNS / BLOCKED).
 3. **Read the actual code** — don't rely on the implementation report alone. Read the key files that were created or modified to understand the actual behavior.
 4. **Read CLAUDE.md** — load project conventions and e2e testing patterns.
+5. **Read the project's `features/*.feature` files** — these are the e2e source of truth. Identify the file(s) that cover the capability being tested. If `features/` does not exist, **stop and warn**: *"No `.feature` files found. Project needs a one-time bootstrap pass to seed `features/`. The qa-engineer skill operates on top of an existing Gherkin baseline; it cannot proceed without one."* Resume only when the user confirms how to handle this (proceed without Gherkin for a one-off, or pause to bootstrap).
 
 If the implementation status is BLOCKED, warn: "The implementation is marked as BLOCKED. QA may not be meaningful until blocking issues are resolved. Proceed anyway?"
 
 ---
 
-## Step 3 — Find Existing E2E Patterns
+## Step 3 — Find Existing Patterns (Tests *and* Gherkin)
 
-Before writing any tests:
+Before writing or extending anything:
 
-1. **Search for existing e2e tests** — use Glob and Grep to find test files in the project's e2e directory
-2. **Read 2–3 representative test files** — understand the project's e2e conventions: file structure, imports, setup/teardown patterns, assertion style, helper utilities, page objects or fixtures
-3. **Identify the test location** — where should new e2e tests live? Follow the project's existing structure.
+1. **Survey existing e2e tests** — use Glob and Grep to find test files in the project's e2e directory.
+2. **Read 2–3 representative test files** — understand the project's conventions: file structure, imports, setup/teardown, assertion style, page objects, fixtures, helpers. Note especially how each `test(...)` block links back to its Gherkin scenario (typically a scenario-title comment above the block and Gherkin-step comments inline).
+3. **Survey existing `.feature` files** — read 2–3 representative ones. Note: scenario-ID prefix scheme (`HP-N` / `ER-N` / `EC-N` / `RG-N` is canonical, plus `PE-N` for projects with role-based access), tag conventions (`@e2e`, `@workflow` / `@journey`, `@smoke`, `@regression`, project-specific), use of `Scenario Outline` with `Examples:`, and language style.
+4. **Identify locations** — where do `.feature` files live? Where do `.spec.ts` files live? Follow the existing layout exactly.
 
-Never write tests in a pattern that differs from what the project already uses.
+Never write tests or scenarios in a style that differs from what the project already uses. Consistency is more valuable than your preferred pattern.
 
 ### Using Playwright MCP (if available)
 
@@ -82,33 +86,71 @@ The Playwright MCP is a **development aid** — use it to explore and verify, th
 
 ---
 
-## Step 4 — Design Tests from Acceptance Criteria
+## Step 4 — Decide AC Routing (replaces "every AC needs an e2e test")
 
-Map each acceptance criterion to one or more e2e tests:
+Every acceptance criterion must be **traceable to coverage**, but coverage does not always mean an e2e test. For each AC, decide which venue verifies it:
 
-```
-Acceptance Criterion → Test Name → What It Verifies → How (interactions, assertions)
-```
+| AC nature | Venue | Why |
+|-----------|-------|-----|
+| User-observable behaviour through page, API, or real-time channel | **Gherkin scenario** in `features/*.feature` | The user can see/trigger this; it belongs in the journey suite |
+| Internal contract, type shape, deprecated marker, dead-code removal | **Lint rule** (project ESLint config or equivalent) | Static, structural — it is checked at compile time, not runtime |
+| Pure logic, validation, transformation | **Unit or integration test** (delegated to implementation skill — record as a check-result entry the impl agent must satisfy) | Cheaper, faster, isolated debugging |
+| One-time invariant verified during the implementation run | **Check-result entry** in the implementation report | Documented once, not re-verified by the e2e suite |
+
+**Rules:**
+
+- **The default is *not* "Gherkin scenario."** Pick the smallest venue that proves the AC. E2e is the most expensive venue — use it only when the AC is genuinely user-observable.
+- **Multiple ACs may collapse into one Gherkin scenario.** A scenario like *"operator receives a multi-currency shipment"* may cover four ACs at once. Don't split.
+- **Multiple Gherkin scenarios may cover one AC.** Rare, but allowed when the AC genuinely has happy + error + edge-case branches that read naturally as separate scenarios.
+- **An AC routed to a non-e2e venue is *not* a coverage gap.** It's correctly placed. Note the venue in the coverage table.
+
+**Tripwire:** if you find yourself wanting to import `fs`, `path` (for source paths), `child_process`, or any module that reads project source code from inside a `.spec.ts` file — STOP. The AC is not e2e. Route it to a lint rule, unit test, or impl check-result. There are zero exceptions.
+
+Log the routing decisions in the QA artifact (Step 8 coverage table). Proceed to extending `.feature` files. Do not ask for confirmation.
+
+---
+
+## Step 5 — Extend `.feature` Files
+
+For each AC routed to a Gherkin scenario, decide *how* to land it. The order matters — earlier options keep the suite small:
+
+1. **`Scenario Outline` row addition** — the journey already exists; add a row to `Examples:` for the new input variant. *Cheapest. Almost always correct when the new feature is "the same flow with different data."*
+2. **`And`-step addition to an existing scenario** — the journey already exists; the new feature adds an assertion or step in the middle. *Use when the user-visible flow is unchanged but a new check is needed.*
+3. **New scenario** — *last resort.* Only when no existing scenario fits the user journey. Justify in the QA report's coverage table with a one-line reason.
+
+**Conventions (match existing project usage exactly):**
 
-For each criterion:
-- Determine the user-facing behavior it describes
-- Design the test — what actions does it perform? What does it assert?
-- Identify test data — does the test need fixtures, seed data, or mock APIs?
-- Consider edge cases — the criterion is the happy path; are there meaningful edge cases worth a test?
+- Scenario IDs use `HP-N` / `ER-N` / `EC-N` / `RG-N` (or `PE-N` for projects with role-based access). **Never use `AC-N`** in scenario titles, file names, or test names.
+- Tags are additive: `@e2e` plus appropriate kind tags (`@smoke`, `@workflow` / `@journey`, `@regression`, project-specific). Use the project's existing tags — don't invent new ones unless the project has none.
+- Prefer `Scenario Outline` with `Examples:` over N parallel `Scenario` blocks whenever the journey is the same and only inputs/expected values vary.
 
-Log the test plan in the QA artifact — which criteria map to which tests — then proceed to writing immediately. Do not ask for confirmation.
+**Spec-writer's "Gherkin Impact" is your starting point.** Implement the extensions it lists. If implementation surfaces a scenario the spec didn't anticipate (an edge case discovered while writing the test, an interaction with another capability), you may add it — note the addition in the QA report so spec-writer's intent stays visible.
+
+**Restraint is part of the deliverable.** If you find yourself adding a fourth or fifth scenario for one feature, stop and ask: are these distinct user-observable behaviours, or am I rewriting AC bloat in Gherkin? Collapse where you can.
 
 ---
 
-## Step 5 — Write the Tests
+## Step 5b — Implement Scenarios in Test Files
 
-Write e2e test files following the project's existing patterns:
+Now write the `.spec.ts` (or equivalent) files that implement the scenarios:
 
 1. **Match the framework** — use `e2e-framework` from config. Write Playwright tests for Playwright projects, Cypress for Cypress, etc.
-2. **Follow existing conventions** — imports, file naming, describe/test structure, assertion library, helpers
-3. **One test per acceptance criterion (minimum)** — more are fine for edge cases, but every criterion must have at least one test
-4. **Test real behavior** — interact with the application as a user would. Don't test internal implementation details.
-5. **Make assertions specific** — assert exact expected values, not just "something exists"
+2. **Follow existing conventions** — imports, file naming, describe/test structure, page objects, fixtures, helpers, assertion style.
+3. **Traceability to Gherkin** — each `test(...)` block (or equivalent) carries a comment above it with the scenario title. Each step inside the test body is commented with the Gherkin step it implements:
+   ```ts
+   // Scenario: HP-1 - operator receives a multi-currency shipment
+   test('HP-1: operator receives a multi-currency shipment', async ({ page }) => {
+     // Given the operator is on the inventory page with seeded suppliers
+     ...
+     // When they submit a batch with USD and EUR cost entries
+     ...
+     // Then the batch is recorded with both currency rates
+     ...
+   });
+   ```
+4. **Behavioural assertions only.** No `fs.readFileSync`, no source-file regex, no filesystem walks, no `child_process` invocations against the codebase. Tests interact with the page, API, or real-time channel — that is all. Fixture loading from a dedicated `fixtures/` directory (e.g. CSV/JSON test data) is permitted via fixture-only paths.
+5. **Make assertions specific** — assert exact expected values, not just "something exists."
+6. **One test per scenario** — N scenarios → N tests. `Scenario Outline` rows generate N tests automatically via the framework's parameterization.
 
 ---
 
@@ -152,21 +194,42 @@ Create `03-qa.md` (or `03-qa-N.md` for re-runs) in the workflow folder:
 > E2E Framework: <from config>
 > Status: PASS | FAIL | PARTIAL
 
-## Acceptance Criteria Coverage
+## Acceptance Criteria Coverage (routing)
+
+| # | Criterion | Venue | Reference | Result |
+|---|-----------|-------|-----------|--------|
+| 1 | <criterion from spec> | Gherkin scenario | `features/<file>.feature` > "HP-1 - <title>" | Pass / Fail |
+| 2 | <criterion from spec> | Lint rule | `eslint-config / no-deprecated-without-jsdoc` | Pass (CI) / N/A |
+| 3 | <criterion from spec> | Unit test | `core/<area>.test.ts` > "<test name>" (impl-owned) | Pass / Fail |
+| 4 | <criterion from spec> | Impl check-result | `02-implementation.md` > Check Results > <row> | Pass |
+
+> Routing rule: Gherkin scenario for user-observable behaviour; lint rule for structural/internal contracts; unit test for pure logic (delegated to impl); impl check-result for one-time invariants.
+
+## .feature Extensions
+
+For each `.feature` file affected, list what was added:
+
+### `features/<file>.feature`
+
+- **Outline rows added:** `<scenario title>` gained <N> rows in `Examples:` for <input variants>
+- **`And`-step additions:** `<scenario title>` — added *"And <step>"* under <Given/When/Then>
+- **New scenarios:** `<HP-N | ER-N | EC-N | RG-N> - <title>`. Reason for being new: <why no existing scenario could be extended>
 
-| # | Criterion | Test(s) | Result |
-|---|-----------|---------|--------|
-| 1 | <criterion from spec> | `path/to/test.spec.ts` > "test name" | Pass / Fail |
-| 2 | ... | ... | ... |
+## Scenarios Deliberately Not Added
+
+<List ACs that *could* have been e2e but were intentionally not, with one-line reasons. Example:>
+
+- AC9 — input rejects negative numbers → covered by unit test `cost-entry.test.ts > "rejects negatives"` (cheaper, isolates the validator)
+- AC11 — deprecated endpoint carries `@deprecated` JSDoc → covered by lint rule `no-deprecated-without-jsdoc`
 
 ## Tests Written
 
 ### `path/to/test-file.spec.ts`
 
-- **"test name 1"** — <what it verifies, what it asserts>
-- **"test name 2"** — <what it verifies>
+- **"HP-1: <title>"** — implements `features/<file>.feature` > "HP-1 - <title>"; asserts <what>
+- **"HP-2: <title>"** — implements `features/<file>.feature` > "HP-2 - <title>"; asserts <what>
 
-<Repeat for each test file>
+<Repeat for each test file. Test names match scenario IDs.>
 
 ## Test Results
 
@@ -189,16 +252,22 @@ Create `03-qa.md` (or `03-qa-N.md` for re-runs) in the workflow folder:
 - **Evidence:** <specific test failure, error message, or observed behavior>
 - **Severity:** blocking | major | minor
 
+## Metrics
+
+- **Scenarios added (this run):** <N>  (outline rows: <X>, `And`-step extensions: <Y>, new scenarios: <Z>)
+- **Total scenarios per affected file:** `<file>.feature` <before → after>
+- **Outline-to-scenario ratio (project-wide):** <X> outlines / <Y> scenarios — flag if outlines drop below ~20% (suggests the suite is paralleling instead of parameterising)
+
 ## Notes
 
-<Any observations about test coverage gaps, flaky tests, or edge cases not in the acceptance criteria but tested anyway.>
+<Any observations about flaky tests, scenarios discovered during implementation that the spec didn't anticipate, or pruning candidates the implementation surfaced.>
 ```
 
 ### Status Codes
 
-- **PASS** — all acceptance criteria verified by passing e2e tests
-- **FAIL** — one or more acceptance criteria not met (implementation issues found)
-- **PARTIAL** — some criteria verified, some could not be tested (e.g. requires manual verification, external service dependency)
+- **PASS** — all acceptance criteria verified, each routed to its venue and the venue is green
+- **FAIL** — one or more acceptance criteria not met (implementation issues found in any venue)
+- **PARTIAL** — some criteria verified, some routed to venues whose verification is pending (e.g. waiting on a lint rule to be added, or unit test delegated to impl that hasn't run); not the same as "couldn't write a test for it"
 
 ---
 
@@ -217,20 +286,31 @@ Present:
 ## Constraints
 
 **DO:**
-- Read the spec's acceptance criteria before reading the implementation
-- Follow the project's existing e2e test patterns exactly
-- Write at least one e2e test per acceptance criterion
+- Read the spec's acceptance criteria *and* the project's `.feature` files before reading the implementation
+- Route each AC to its correct venue (Gherkin scenario / lint rule / unit test / impl check-result) — not every AC is e2e
+- Prefer extending existing scenarios over adding new ones: `Scenario Outline` rows first, `And`-step extensions second, new scenarios last
+- Use scenario-ID prefixes (`HP-N` / `ER-N` / `EC-N` / `RG-N`); reflect them in test names
+- Write each `test(...)` block with a scenario-title comment above it and Gherkin-step comments inline
+- Use behavioural assertions only — page interactions, API calls, real-time channels
+- Justify each new scenario as a distinct user-observable behaviour, not as a per-AC reflex
+- Include a "Scenarios Deliberately Not Added" section with one-line reasons for each AC routed away from e2e
+- Include a Metrics line in the QA report for human bloat-detection
 - Run the tests and include actual output as evidence
 - Verify tests are substantive (not stubs) after writing them
 - Report implementation issues without fixing them — that's the implementation skill's job
+- Follow the project's existing e2e test patterns exactly
 
 **DON'T:**
 - Trust the implementation report as a substitute for reading actual code
-- Write unit tests — that's the implementation skill's responsibility
+- Write unit tests — that's the implementation skill's responsibility (delegate via impl check-result entry instead)
 - Fix implementation bugs — document them as issues for the review/fix loop
 - Invent new test patterns when existing patterns work
 - Skip the substance verification — stub tests are the #1 risk
 - Write tests that depend on implementation internals rather than user-visible behavior
+- Use AC labels (`AC<N>`) in test names, file names, or scenario titles — AC traceability lives in the coverage table only
+- Import `fs`, `path` (for source paths), `child_process`, or any module that reads project source code from inside `.spec.ts` — these reach for source-file inspection, which is not e2e
+- Write N parallel `Scenario` blocks when one `Scenario Outline` with `Examples:` would do — parameterise
+- Add a scenario "for completeness" — restraint is part of the deliverable; coverage is verified in the report, not by scenario count
 
 ---
 
@@ -239,8 +319,13 @@ Present:
 If you catch yourself thinking any of these, stop:
 
 - "The implementation report says it works, so I'll write light tests" — STOP. The report may be optimistic. Verify independently.
-- "This criterion is hard to test with e2e, I'll skip it" — STOP. Mark it as PARTIAL with an explanation, don't silently skip.
+- "This criterion is hard to test with e2e, I'll skip it" — STOP. Hard-to-e2e usually means the AC is not user-observable. Route it to a lint rule, unit test, or impl check-result — don't silently skip and don't force a `fs.readFileSync` workaround.
+- "I need to read a source file to verify this AC" — STOP. Hard tripwire. The AC is not e2e. Pick a different venue.
 - "All tests pass, so QA is done" — STOP. Passing tests can be stubs. Run the substance check.
 - "I'll write a quick `expect(true)` to get this passing" — STOP. That's a stub. Write a real assertion.
+- "Every AC needs its own scenario" — STOP. Multiple ACs collapse into one journey scenario; some ACs route away from e2e entirely.
+- "I'll add another scenario for completeness" — STOP. Justify it as a distinct user-observable behaviour or don't add it. Restraint is part of the deliverable.
+- "I'll write N parallel scenarios for N variants of the same flow" — STOP. Use `Scenario Outline` with `Examples:`.
+- "I'll name this test `AC10: ...`" — STOP. AC labels do not appear in test or scenario names. Use `HP-N` / `ER-N` / `EC-N` / `RG-N`. AC traceability is the coverage table's job.
 - "The existing e2e tests use a different pattern but mine is better" — STOP. Follow existing patterns. Consistency matters.
 - "This implementation issue is minor, I won't report it" — STOP. Report everything. Let the review skill triage severity.

package/skills/spec-writer/SKILL.md

@@ -93,6 +93,24 @@ Do not prescribe a fixed search strategy. Every codebase is shaped differently.
 
 ---
 
+## Step 4b — Survey `.feature` Files
+
+If the project has user-visible behaviour (most do), check the project's `features/` directory for Gherkin `.feature` files — they are the source of truth for e2e scenarios.
+
+1. **List `features/*.feature`.** If the directory does not exist or is empty, warn the user: *"No `.feature` files found. Project needs a one-time bootstrap pass to seed `features/` from the application's user-facing capabilities. Continue without Gherkin Impact, or pause to bootstrap?"*
+2. **Identify affected files.** For the feature being spec'd, name the `.feature` file(s) that cover the capability it touches. One feature usually maps to one (sometimes two) existing `.feature` files — never to a brand-new file.
+3. **Determine the extension shape.** For each affected file, decide how the spec extends it:
+   - **`Scenario Outline` row addition** — the journey already exists, just needs another data row.
+   - **`And`-step addition to an existing scenario** — the journey already exists, the new feature adds an assertion or step.
+   - **New scenario** — *last resort.* Only when no existing scenario fits the user journey, and the feature truly introduces a new user-observable behaviour.
+4. **Surface prune candidates.** If the feature retires capability, name scenarios likely to become obsolete. The human decides actual deletion.
+
+This survey feeds the spec's "Gherkin Impact" section (Step 7).
+
+> **No new `.feature` files at the per-feature level.** New `.feature` files are bootstrap territory. Per-feature work extends what exists.
+
+---
+
 ## Step 5 — Determine Spec Depth
 
 Based on complexity detected in steps 3–4, choose a depth:
@@ -181,7 +199,22 @@ What to replicate from the template and what differs for this feature.
 - [ ] Criterion (specific, testable)
 - [ ] Criterion
 
-> These criteria are the contract that flows downstream. The review skill checks whether the implementation meets them. The qa-engineer skill writes e2e tests to prove them. Write them so they are verifiable by both a code reviewer and an automated test.
+> These criteria are the contract that flows downstream. The review skill checks whether the implementation meets them. The qa-engineer skill routes each criterion to the right venue — Gherkin scenario, lint rule, unit test, or impl-report check-result — per the project's traceability model. Write criteria so they are verifiable, but do not assume they all become e2e tests.
+
+## Gherkin Impact
+
+(Skip if the project has no `features/` directory; flag a bootstrap need instead.)
+
+**Affected `.feature` files:**
+- `features/<file>.feature` — <one-line capability summary>
+
+**Extensions:**
+- **Outline rows:** `<scenario title>` gets a new row in `Examples:` for `<input variant>`
+- **`And`-step additions:** `<scenario title>` gains *"And <new assertion>"* under <Given/When/Then>
+- **New scenarios** (only when no existing scenario fits): `<HP-N | ER-N | EC-N | RG-N> - <title>` in `<file>.feature`. Reason: <why no existing scenario could be extended>
+
+**Prune candidates** (capability being retired):
+- `<scenario title>` in `<file>.feature` — likely obsolete because <reason>. Human decides removal.
 
 ## Workflow Config
 
@@ -234,7 +267,9 @@ When invoked with a path to an existing spec (or the user asks to revise):
 - Read the codebase before writing anything
 - Reference specific file paths, function names, type names in every implementation step
 - Find and cite a structural template (the closest existing similar feature)
-- Write acceptance criteria that are verifiable by both a code reviewer and an e2e test — they flow to the review and qa-engineer skills
+- Write acceptance criteria that are verifiable — they flow to review (code-level verification) and qa-engineer (venue routing: Gherkin scenario / lint rule / unit test / impl check-result)
+- Survey existing `.feature` files and prefer extending them — outline rows or `And`-step additions before new scenarios
+- Surface prune candidates when capability retires (human decides actual removal)
 - Scale spec depth to task complexity
 - Include the workflow config in the output for downstream skills
 - Make decisions — be opinionated
@@ -245,6 +280,8 @@ When invoked with a path to an existing spec (or the user asks to revise):
 - List alternatives — pick one and explain why
 - Skip codebase exploration for any reason
 - Create a spec for requirements that are unclear — ask first
+- Create new `.feature` files at the per-feature level — bootstrap is a separate one-off; per-feature work extends what exists
+- Assume every acceptance criterion becomes an e2e test — qa-engineer routes ACs by nature; criteria that aren't user-observable belong in lint rules, unit tests, or impl check-results
 
 ---
 
@@ -257,3 +294,5 @@ If you catch yourself thinking any of these, stop:
 - "The user's description is clear enough, no ambiguity check needed" — STOP. Spend 30 seconds checking.
 - "I'll keep the acceptance criteria general to be flexible" — STOP. Vague criteria are untestable and unusable by downstream skills. Be specific.
 - "There's no similar feature to use as a template" — STOP. Look harder. There is almost always a structural analog somewhere in the codebase.
+- "This feature is new enough to deserve its own `.feature` file" — STOP. New `.feature` files are bootstrap territory. If the feature truly defines a new user-facing capability with no precedent in `features/`, that's a bootstrap pass, not per-feature spec-writer work. Flag it for the user.
+- "I'll add a new scenario for each new acceptance criterion" — STOP. Prefer outline rows or `And`-step additions to existing scenarios. New scenarios require a stated reason in Gherkin Impact.