@devshop/crew 0.10.0 → 0.10.1

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [0.10.1](https://github.com/devshop-software/crew/compare/v0.10.0...v0.10.1) (2026-05-09)
+
+
+### Bug Fixes
+
+* **skills:** close per-feature .feature ban loophole; mandate Gherkin Impact ([46eb47b](https://github.com/devshop-software/crew/commit/46eb47b932b6a4be90547c76f2b72324c2f0f09a)), closes [#53](https://github.com/devshop-software/crew/issues/53)
+
 # [0.10.0](https://github.com/devshop-software/crew/compare/v0.9.1...v0.10.0) (2026-05-07)
 
 

package/package.json

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

package/skills/qa-engineer/SKILL.md

@@ -48,11 +48,13 @@ Activate when called from the `/qa` command. Otherwise ignore.
 
 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 *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.
+1. **Read `01-spec.md`** — extract the acceptance criteria *and* the "Gherkin Impact" section. ACs are the contract; Gherkin Impact tells you which `.feature` files spec-writer expects you to extend or create. **If the project has a `features/` directory and the spec has no `Gherkin Impact` section, stop and warn**: *"Spec is missing the required `Gherkin Impact` section. Spec-writer must emit Gherkin Impact when `features/` exists. Re-run `/spec` (edit mode) to add it before QA can proceed."* Resume only when the spec is updated.
 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).
+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 at all**, 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 `features/` exists but the capability under test has no `.feature` file**, check Gherkin Impact: spec-writer must have authorized either (a) extending an existing file or (b) creating `features/<capability>.feature` with a "New file justification". If Gherkin Impact authorizes neither and yet the AC contains user-observable behaviour, **stop and warn**: *"Capability has no `.feature` file and Gherkin Impact does not authorize creating one. Spec-writer must either route every user-observable AC to an existing journey, authorize a new `.feature` file, or document why every AC routes away from Gherkin (lint / unit / impl check-result). Re-run `/spec` (edit mode) to fix Gherkin Impact."* Falling back to a bare `.spec.ts` is **not** an option.
 
 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?"
 
@@ -116,7 +118,8 @@ For each AC routed to a Gherkin scenario, decide *how* to land it. The order mat
 
 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.
+3. **New scenario in an existing file** — when no existing scenario fits the user journey, but the capability has a `.feature` file that anchors it. Justify in the QA report's coverage table with a one-line reason.
+4. **New `.feature` file** — *only when Gherkin Impact authorized it.* Create `features/<capability>.feature` matching the project's existing `.feature` style (tags, scenario-ID prefixes, Background patterns). The QA report's `.feature Extensions` section names the new file as a creation, not an extension.
 
 **Conventions (match existing project usage exactly):**
 
@@ -205,16 +208,21 @@ Create `03-qa.md` (or `03-qa-N.md` for re-runs) in the workflow folder:
 
 > 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
+## .feature Extensions and Creations
 
-For each `.feature` file affected, list what was added:
+For each `.feature` file affected, list what was added (or what the file is, if newly created):
 
-### `features/<file>.feature`
+### `features/<file>.feature` *(EXISTING)*
 
 - **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>
 
+### `features/<new-capability>.feature` *(NEW — created this run, authorized by Gherkin Impact)*
+
+- **Reason for new file:** <quote spec-writer's "New file justification" — capability has no existing journey AND is genuinely user-observable; closest existing capability and why it didn't fit>
+- **Initial scenarios:** `<HP-N> - <title>`, `<ER-N> - <title>`, etc.
+
 ## Scenarios Deliberately Not Added
 
 <List ACs that *could* have been e2e but were intentionally not, with one-line reasons. Example:>
@@ -288,7 +296,7 @@ Present:
 **DO:**
 - 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
+- Prefer extending existing scenarios over adding new ones: `Scenario Outline` rows first, `And`-step extensions second, new scenarios in existing files third, and a new `.feature` file *only* when Gherkin Impact authorized it (capability has no existing journey)
 - 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
@@ -309,6 +317,7 @@ Present:
 - 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
+- Create a `.spec.ts` (or framework equivalent) without a sibling `.feature` it implements — every runner maps 1:1 to a `.feature` file. Net-new `.spec.ts` outside the runner pattern is not allowed; if no `.feature` covers the capability, create one (when Gherkin Impact authorized it) or route the AC to a non-Gherkin venue
 - 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
 
@@ -323,6 +332,9 @@ If you catch yourself thinking any of these, stop:
 - "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.
+- "This single flow reads more naturally as plain Playwright than as Gherkin / Scenario Outline" — STOP. That's the rationalization pattern. If the AC is user-observable, it lands in a `.feature` file. "Naturalness" is not a sanctioned venue. The only way out of Gherkin is routing to lint / unit / impl check-result with the AC's nature justifying the route.
+- "I'll write a `.spec.ts` and skip the `.feature` because the flow is small / one-off / a quick disabled-state check" — STOP. Runner-without-feature is not allowed. Either extend an existing `.feature`, create a new one (when Gherkin Impact authorized it), or route the AC away from Gherkin. There is no fourth option.
+- "The capability has no `.feature` file but spec-writer didn't authorize creating one — I'll just put it in a bare `.spec.ts`" — STOP. Stop and warn the user; spec-writer must update Gherkin Impact. Do not paper over a missing authorization with a bare runner.
 - "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:`.

package/skills/spec-writer/SKILL.md

@@ -98,16 +98,17 @@ Do not prescribe a fixed search strategy. Every codebase is shaped differently.
 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:
+2. **Identify affected files.** For the feature being spec'd, name the `.feature` file(s) that cover the capability it touches. A feature usually extends one (sometimes two) existing `.feature` files. **A new `.feature` file is correct only when the capability under test has no existing journey in `features/` AND is genuinely user-observable** — otherwise extension is the right shape.
+3. **Determine the extension shape.** For each affected file, decide how the spec extends it (extension is preferred over creation):
    - **`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.
+   - **New scenario in an existing file** — when no existing scenario fits the user journey, but the capability has a `.feature` file that anchors it.
+   - **New `.feature` file** — *only* when no existing file covers the capability. Name it `features/<capability>.feature`. Justify in Gherkin Impact why no existing journey is the right anchor.
 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.
+> **A new `.feature` file is the wrong shape when it duplicates or fragments an existing capability's journey.** It is the right shape when the capability under test has no existing journey and is genuinely user-observable. Per-ticket `.feature` proliferation (one file per feature ticket) is what we are preventing — not legitimate net-new capability journeys.
 
 ---
 
@@ -203,15 +204,19 @@ What to replicate from the template and what differs for this feature.
 
 ## Gherkin Impact
 
-(Skip if the project has no `features/` directory; flag a bootstrap need instead.)
+(**Required** when the project has a `features/` directory. If the project has no `features/`, flag a bootstrap need and skip this section.)
 
 **Affected `.feature` files:**
-- `features/<file>.feature` — <one-line capability summary>
+- `features/<file>.feature` — <one-line capability summary>  *(EXISTING — extension)*
+- `features/<new-capability>.feature` — <one-line capability summary>  *(NEW FILE — see "New file justification" below)*
 
 **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>
+- **New scenarios in existing files** (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>
+
+**New file justification** (required if any `.feature` file is being created):
+- `features/<new-capability>.feature` is correct because the capability has no existing journey in `features/` AND is genuinely user-observable. Closest existing capability: `<existing-file>.feature` covers `<X>`, which is a different journey because `<reason>`. Initial scenarios: `<HP-N>`, `<ER-N>`, etc.
 
 **Prune candidates** (capability being retired):
 - `<scenario title>` in `<file>.feature` — likely obsolete because <reason>. Human decides removal.
@@ -280,7 +285,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
+- Create a `.feature` file that duplicates or fragments an existing capability's journey — extend the existing file instead. Net-new `.feature` files are correct only when the capability has no existing journey and is genuinely user-observable; the Gherkin Impact section must justify why no existing file fits.
+- Skip the `Gherkin Impact` section when `features/` exists — it is required, not optional. Downstream qa-engineer refuses to proceed without it.
 - 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
 
 ---
@@ -294,5 +300,6 @@ 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.
+- "This feature deserves its own `.feature` file because it's *kinda* different" — STOP. A new `.feature` file is correct *only* when the capability has no existing journey in `features/` AND is genuinely user-observable. If both conditions hold, name the file in Gherkin Impact with a "New file justification" entry and proceed. If either fails, extend the closest existing file.
+- "The capability has no existing `.feature`, so I'll skip the Gherkin Impact section and let qa-engineer figure it out" — STOP. When `features/` exists, Gherkin Impact is required. Either authorize a new file (with justification) or document why every AC routes away from Gherkin (lint / unit / impl check-result). Silent omission is not allowed.
 - "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.