@devshop/crew 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.11.0](https://github.com/devshop-software/crew/compare/v0.10.1...v0.11.0) (2026-05-09)
+
+
+### Features
+
+* **skills:** qa-v2 — journey-scope coverage map, leaner skill text ([d6342a0](https://github.com/devshop-software/crew/commit/d6342a066579047921041829cf75e45cbdb840fb))
+
+## [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.11.0",
   "description": "Project-agnostic Claude Code skills for spec → implement → qa → review → ship",
   "bin": {
     "crew": "scripts/cli.js"

package/skills/adjust/SKILL.md

@@ -19,11 +19,7 @@ Activate when called from the `/adjust` command. Otherwise ignore.
 
 ## Input Handling
 
-`$ARGUMENTS` may be:
-
-- **Empty** (most common) — scan the current project and set up config
-- **`update`** — re-scan and update an existing Workflow Config
-- **A specific key** (e.g. `test-cmd`) — update just that config value
+Take whatever was passed and infer the scope: full project scan (default), a re-scan of the existing config, or an update to a single config key.
 
 ---
 
@@ -166,7 +162,7 @@ This step converts a standard git clone into a bare-clone worktree layout, or va
   .claude/            ← real dir at root (not a symlink)
   .mcp.json           ← shared across worktrees
   main/               ← worktree for the base branch
-  wt/                 ← feature worktrees (created by /indie)
+  wt/                 ← feature worktrees (created by /indie-agent)
     <feature-name>/   ← short, scannable names
 ```
 
@@ -245,7 +241,7 @@ This project uses a **bare-clone worktree layout**. The repo root is not a worki
   .claude/            ← real dir at root (not a symlink)
   .mcp.json           ← shared across worktrees
   main/               ← worktree for the main branch (primary working copy)
-  wt/                 ← feature worktrees created by /indie
+  wt/                 ← feature worktrees created by /indie-agent
     <feature-name>/   ← short, scannable names
 \`\`\`
 

package/skills/codebase-review/SKILL.md

@@ -19,11 +19,7 @@ Activate when called from the `/audit` command. Otherwise ignore.
 
 ## Input Handling
 
-`$ARGUMENTS` may be:
-
-- **Empty** (most common) — full codebase audit across all five dimensions
-- **A dimension name** (e.g. `security`, `testing`, `infrastructure`, `code-health`, `dependencies`) — audit only that dimension
-- **A path** to a directory — scope the audit to a specific area of the codebase
+Take whatever was passed: empty for a full audit across all five dimensions, a dimension name (`security`, `testing`, `infrastructure`, `code-health`, `dependencies`) for one slice, or a directory path to scope to part of the codebase.
 
 ---
 

package/skills/docs/SKILL.md

@@ -17,13 +17,7 @@ Activate when called from the `/docs` command. Otherwise ignore.
 
 ## Input Handling
 
-`$ARGUMENTS` may be:
-
-- **Empty** or `all` — regenerate all five managed files
-- **A folder name** — `operational` or `technical`. Regenerate the files in that folder only.
-- **A file name** — `architecture`, `first-time-setup`, `ci-cd`, `best-practices`, or `patterns`. Regenerate only that file.
-
-Record which files are in scope for this run before proceeding.
+Take whatever was passed: empty regenerates all five managed files, a folder name (`operational` or `technical`) scopes to that folder, a file name scopes to that single file. Record which files are in scope before proceeding.
 
 ---
 

package/skills/implementation/SKILL.md

@@ -21,11 +21,7 @@ Activate when called from the `/implement` command. Otherwise ignore.
 
 ## Input Handling
 
-`$ARGUMENTS` may be:
-
-- A **folder name** (e.g. `20260413-1423-dark-mode`)
-- A **path** to the workflow folder or spec file
-- **Empty** — auto-detect: scan the workflow directory for folders that have `01-spec.md` but no `02-implementation.md`. If exactly one exists, use it. If multiple, list them and ask. If none, tell the user there are no unimplemented specs.
+Take whatever was passed — workflow folder name, path to the folder or spec file, or empty to auto-detect (one folder with `01-spec.md` and no `02-implementation.md`; ask if multiple).
 
 ---
 

package/skills/indie-agent/SKILL.md

@@ -11,8 +11,6 @@ You are a lightweight workflow orchestrator. You drive the full development chai
 
 You are a conductor, not a player. You never write code, write tests, or perform reviews yourself. You read skill files from disk, construct agent prompts, dispatch them, then read the resulting artifacts to decide what comes next.
 
-**Key difference from the `indie` skill:** Each phase runs in a fresh subagent with its own context window. This means every phase gets full context budget for codebase exploration, and the orchestrator stays lean regardless of how many fix loop iterations occur.
-
 Each feature runs in its own git worktree, enabling multiple `/indie-agent` invocations to run in parallel across separate terminals.
 
 By default you run fully autonomously. The user provides input once, you deliver a PR with green CI. If the user sets a breakpoint, you pause after that phase and wait for re-invocation to continue.
@@ -25,28 +23,16 @@ Activate when called from the `/indie-agent` command. Otherwise ignore.
 
 ## Input Handling
 
-`$ARGUMENTS` may be:
-
-- A **GitHub issue URL** (e.g. `https://github.com/org/repo/issues/42`) — passed to the spec phase as input
-- **Free text** — a feature description, passed to the spec phase as input
-- A **workflow folder reference** (folder name or path) — resume an existing workflow from wherever it left off
-- **Empty** — auto-detect: scan the workflow directory for incomplete workflows (folders missing later artifacts). If exactly one exists, resume it. If multiple, list and ask. If none, tell the user to provide a feature description.
+Take whatever was passed: a feature brief, GitHub issue URL, workflow folder reference (resume), or empty to auto-detect (one incomplete workflow if exactly one exists; ask if multiple).
 
 ### Breakpoints
 
-The input may include a breakpoint instruction. Parse and strip it before passing the remainder as the feature description.
-
-**Syntax:** `--stop-after <phase>`, `stop after <phase>`, `pause after <phase>`, or `break after <phase>` anywhere in the input.
+The input may include a natural-language breakpoint instruction like "stop after spec", "pause after review", or "break after implement" anywhere in the message. Parse and strip it before passing the remainder as the feature description.
 
 **Recognized phases:** `spec`, `implement`, `qa`, `review`, `ship`
 
-**Examples:**
-- `/indie-agent https://github.com/org/repo/issues/42 --stop-after spec`
-- `/indie-agent add user avatars, stop after review`
-- `/indie-agent dark-mode --stop-after implement`
-- `/indie-agent https://github.com/org/repo/issues/42` — no breakpoint, fully autonomous
-
 **At a breakpoint:**
+
 1. Complete the phase normally (let the subagent finish)
 2. Verify the output artifact exists
 3. Report: "Paused after `<phase>`. Artifact: `<path>`. Worktree: `<worktree-path>`. Review it, then re-invoke `/indie-agent <folder>` to continue."
@@ -80,6 +66,7 @@ The input may include a breakpoint instruction. Parse and strip it before passin
 6. **Switch context:** all subsequent steps run inside the worktree directory
 
 Present a one-line plan:
+
 - **No breakpoint:** "Starting autonomous workflow for: `<feature summary>` in worktree `<path>`. Will run: spec → implement → qa → review → ship → monitor CI. I'll report back when done or if I hit a blocker."
 - **With breakpoint:** "Starting workflow for: `<feature summary>` in worktree `<path>`. Will run through `<phase>` and pause for your review."
 - **Resuming:** "Resuming workflow `<folder>` from `<next phase>`."
@@ -90,17 +77,17 @@ Present a one-line plan:
 
 Read the workflow folder and determine the current state from existing artifacts:
 
-| State | Artifacts Present | Next Action |
-|-------|-------------------|-------------|
-| Nothing | No workflow folder | Dispatch spec agent (Step 2) |
-| Spec done | `01-spec.md` only | Dispatch implementation agent (Step 3) |
-| Implementation done | `+ 02-implementation.md` | Dispatch QA agent (Step 4) |
-| QA done | `+ 03-qa*.md` (latest) | Dispatch review agent (Step 5) |
-| Review FAIL | `+ 04-review*.md` with FAIL verdict | Dispatch implementation fix agent (Step 5F) |
-| Review PASS | `+ 04-review*.md` with PASS verdict | Dispatch ship agent (Step 6) |
-| PR created | PR exists on remote branch | Monitor CI (Step 7) |
-| CI passing | All checks green | Write summary (Step 8) |
-| CI failing | Checks red | CI fix loop (Step 7F) |
+| State               | Artifacts Present                   | Next Action                                 |
+| ------------------- | ----------------------------------- | ------------------------------------------- |
+| Nothing             | No workflow folder                  | Dispatch spec agent (Step 2)                |
+| Spec done           | `01-spec.md` only                   | Dispatch implementation agent (Step 3)      |
+| Implementation done | `+ 02-implementation.md`            | Dispatch QA agent (Step 4)                  |
+| QA done             | `+ 03-qa*.md` (latest)              | Dispatch review agent (Step 5)              |
+| Review FAIL         | `+ 04-review*.md` with FAIL verdict | Dispatch implementation fix agent (Step 5F) |
+| Review PASS         | `+ 04-review*.md` with PASS verdict | Dispatch ship agent (Step 6)                |
+| PR created          | PR exists on remote branch          | Monitor CI (Step 7)                         |
+| CI passing          | All checks green                    | Write summary (Step 8)                      |
+| CI failing          | Checks red                          | CI fix loop (Step 7F)                       |
 
 **To detect "PR created":** Check if the current branch exists on the remote (`git ls-remote --heads origin <branch-name>`). If it does, find the PR with `gh pr list --head <branch-name>`.
 
@@ -113,9 +100,8 @@ Every phase (Steps 2–6) follows the same dispatch pattern:
 ### Before dispatching:
 
 1. **Read the skill file** from disk: `.claude/skills/<skill-name>/SKILL.md`
-2. **Pre-seed the TaskList** — call `TaskCreate` once per subtask of this phase (see per-phase seed lists in Steps 2–6). Capture the returned task IDs; they go into the agent prompt.
-3. **Construct the agent prompt** (see template below) — it MUST embed the progress-log path and the seeded task IDs
-4. **Dispatch** via the Agent tool. For long phases (implementation, QA, fix loops) use `run_in_background: true` so the orchestrator stays responsive to user status queries. For short phases (spec, review, ship) foreground is fine.
+2. **Construct the agent prompt** (see template below) — it MUST embed the progress-log path
+3. **Dispatch** via the Agent tool. For long phases (implementation, QA, fix loops) use `run_in_background: true` so the orchestrator stays responsive to user status queries. For short phases (spec, review, ship) foreground is fine.
 
 ### Agent prompt template:
 
@@ -133,28 +119,28 @@ You are running as part of an autonomous workflow orchestrator. Your working dir
 - Workflow Config:
   <key-value pairs from CLAUDE.md>
 
-## Progress Reporting (MANDATORY)
+## Progress Log (MANDATORY)
+
+You MUST update the progress log as you work. The orchestrator reads it in real time to answer the user's status queries while you run. The progress log is the only signal — there is no task list, no other channel.
+
+**Log path:** `<worktree-path>/<workflow-dir>/<folder-name>/_progress.log`
+
+**Format (one line per milestone):** `[<phase>] <ISO-8601 UTC timestamp> — <event>`
+Example: `[implementation] 2026-04-20T21:14:03Z — step 4/13: FIFO allocator service — starting`
 
-You MUST report progress as you work. The orchestrator reads these signals in real time to answer the user's status queries while you run.
+**You MUST append at least:**
 
-1. **Progress log.** Append to: `<worktree-path>/<workflow-dir>/<folder-name>/_progress.log`
-   Format (one line per milestone): `[<phase>] <ISO-8601 UTC timestamp> — <event>`
-   Example: `[implementation] 2026-04-20T21:14:03Z — step 4/13: FIFO allocator service — starting`
-   Append AT LEAST:
-   - ONE line when the phase starts
-   - ONE line when you begin each subtask (with "<name> — starting")
-   - ONE line when you finish each subtask (with "<name> — done" or "<name> — failed: <short reason>")
-   - ONE line when the phase finishes (success or failure)
-   Use shell append (`>>`), not overwrite. Never delete or truncate the file. Never batch-log at the end — log BEFORE and AFTER each subtask, as you go.
+- ONE line when the phase starts (`[<phase>] <ts> — phase start`)
+- ONE line when you begin each subtask (`<name> — starting`)
+- ONE line when you finish each subtask (`<name> — done` or `<name> — failed: <short reason>`)
+- ONE line when the phase finishes (`[<phase>] <ts> — phase done` or `phase failed: <reason>`)
 
-2. **Task list.** The orchestrator pre-seeded these TaskList IDs for your phase:
-   <task-id-list>
-   Flip each one via `TaskUpdate`:
-   - `status: "in_progress"` when you start working it
-   - `status: "completed"` when it's done
-   Do NOT TaskCreate new tasks unless you discover genuinely new work the orchestrator did not plan. Do NOT delete or re-subject seeded tasks.
+**Discipline:**
 
-3. **Discipline.** If a step fails or you hit a blocker, log it immediately with the `— failed:` form AND flip the task to `in_progress` (not completed). Do not stay silent.
+- Use shell append (`echo ... >> _progress.log`), never overwrite. Never delete or truncate the file.
+- Log BEFORE and AFTER each subtask, as you go. Never batch-log at the end.
+- If a step fails or you hit a blocker, log it immediately with the `— failed:` form. Do not stay silent.
+- Phase-end line is non-negotiable. The orchestrator uses it to detect completion.
 
 ## Skill Instructions
 Follow the skill instructions below. They define your role, steps, constraints, and red flags.
@@ -168,16 +154,15 @@ Where the skill says to ask the user or wait for confirmation, the overrides abo
 
 1. **Verify the output artifact** exists (read the file)
 2. **Read the artifact** to extract status/verdict
-3. **Reconcile the TaskList** — mark any still-`in_progress` tasks `completed` if the artifact shows they're done, or leave them in-progress and note the gap
+3. **Verify the progress log was updated** — `tail _progress.log` and confirm a phase-end line exists. If missing, log it as a gap but proceed with the artifact.
 4. **Check breakpoint** — if the current phase matches, pause
 5. **Decide next step** based on the artifact state
 
 ### When the user asks "status" / "what's up" while a subagent is running
 
 1. `tail` the last ~30 lines of `<workflow-dir>/<folder-name>/_progress.log`
-2. Call `TaskList` and read which seeded tasks are `pending` / `in_progress` / `completed`
-3. Report concisely: phase, step N of M, most recent log event, time since the last log line. If the last log line is more than ~5 minutes old, note that the agent may be in a long tool call or stuck.
-4. Do NOT dispatch another agent, do NOT mutate files. Answering the user is read-only.
+2. Report concisely: phase, most recent log event, time since the last log line. If the last log line is more than ~5 minutes old, note that the agent may be in a long tool call or stuck.
+3. Do NOT dispatch another agent, do NOT mutate files. Answering the user is read-only.
 
 ---
 
@@ -185,15 +170,10 @@ Where the skill says to ask the user or wait for confirmation, the overrides abo
 
 **Skill file:** `.claude/skills/spec-writer/SKILL.md`
 
-**Pre-seed TaskList (call TaskCreate once each, capture IDs):**
-- `[spec] Read inputs and project config`
-- `[spec] Explore codebase / pick structural template`
-- `[spec] Draft 01-spec.md`
-- `[spec] Verify acceptance criteria are testable`
-
 **Dispatch mode:** foreground (spec runs are bounded — usually 5–15 min).
 
 **Task instructions:**
+
 ```
 Write a spec for this feature.
 
@@ -202,9 +182,12 @@ Input: <issue URL or free text description>
 Create the workflow folder: <workflow-dir>/<folder-name>/
 Write the spec as: <workflow-dir>/<folder-name>/01-spec.md
 DO NOT modify files outside the workflow folder. Writing the spec is the ONLY deliverable — no code, no migrations, no src/ changes.
+
+Update the progress log at every milestone (see "Progress Log (MANDATORY)" above). At minimum: phase start, before/after each subtask, phase done. The phase-end line is required.
 ```
 
 **Autonomous overrides:**
+
 - Skip the ambiguity check's user questions — make reasonable decisions and document assumptions in the spec
 - Skip Step 8 ("Present and Refine") — write the spec and finish
 - If requirements are genuinely too vague to plan (no identifiable feature, contradictory requirements), write a message explaining why and stop
@@ -217,23 +200,25 @@ DO NOT modify files outside the workflow folder. Writing the spec is the ONLY de
 
 **Skill file:** `.claude/skills/implementation/SKILL.md`
 
-**Pre-seed TaskList:** First read `01-spec.md` in the orchestrator and parse the `## Implementation Steps` section to count `### Step N — <title>` entries. Then TaskCreate one task per spec step — subject: `[impl] Step N — <title>`. Add one trailing task: `[impl] Run lint / test / build and write 02-implementation.md`.
-
 **Dispatch mode:** **background** (`run_in_background: true`). Implementation is the longest phase; staying responsive matters.
 
 **Task instructions:**
+
 ```
 Implement the feature specified in the spec.
 
 Workflow folder: <workflow-dir>/<folder-name>/
 Read 01-spec.md for the implementation plan.
 Write the implementation report as 02-implementation.md in the same folder.
+
+Update the progress log at every milestone (see "Progress Log (MANDATORY)" above). Implementation is long — log BEFORE and AFTER each Implementation Step from the spec. Phase-end line is required when 02-implementation.md is written.
 ```
 
 **Autonomous overrides:**
+
 - Skip Step 3 ("Present Summary and Get Confirmation") — begin implementing immediately after reading the spec
 
-**Gate:** After the completion notification fires, verify `02-implementation.md` exists and has a Status line. Reconcile the TaskList (any step left `in_progress` = the agent didn't finish it; read the artifact to confirm). If breakpoint is `implement`, pause here.
+**Gate:** After the completion notification fires, verify `02-implementation.md` exists and has a Status line. Verify a phase-end line exists in `_progress.log`. If breakpoint is `implement`, pause here.
 
 ---
 
@@ -241,11 +226,10 @@ Write the implementation report as 02-implementation.md in the same folder.
 
 **Skill file:** `.claude/skills/qa-engineer/SKILL.md`
 
-**Pre-seed TaskList:** Read the spec's `## Acceptance Criteria` section and count criteria. TaskCreate one task per criterion — subject: `[qa] AC N — <short paraphrase>`. Add: `[qa] Run e2e suite` and `[qa] Write 03-qa*.md`.
-
 **Dispatch mode:** **background** (`run_in_background: true`). Playwright runs can be slow.
 
 **Task instructions:**
+
 ```
 Write and run e2e tests for the implemented feature.
 
@@ -253,11 +237,14 @@ Workflow folder: <workflow-dir>/<folder-name>/
 Read 01-spec.md for acceptance criteria.
 Read 02-implementation.md for what was built.
 Write the QA report as <03-qa.md or 03-qa-N.md> in the same folder.
+
+Update the progress log at every milestone (see "Progress Log (MANDATORY)" above). At minimum: phase start, log before/after writing each scenario, before/after running the suite, phase done. The phase-end line is required.
 ```
 
 **Autonomous overrides:** None — the QA skill already runs without confirmation.
 
 **Gate:** After the agent returns, verify the QA artifact exists. If breakpoint is `qa`, pause here. Otherwise read its status:
+
 - **PASS** → proceed to review
 - **FAIL** → log it, proceed to review (the review will catch the implementation issue)
 - **PARTIAL** → proceed to review
@@ -268,16 +255,10 @@ Write the QA report as <03-qa.md or 03-qa-N.md> in the same folder.
 
 **Skill file:** `.claude/skills/review/SKILL.md`
 
-**Pre-seed TaskList:**
-- `[review] Read spec / implementation / QA artifacts`
-- `[review] Read the actual code (diff vs base branch)`
-- `[review] Check acceptance criteria coverage`
-- `[review] Check code quality / security / scope`
-- `[review] Write 04-review*.md with verdict`
-
 **Dispatch mode:** foreground (review is read-heavy but bounded).
 
 **Task instructions:**
+
 ```
 Review the implementation against the spec and QA results.
 
@@ -285,11 +266,14 @@ Workflow folder: <workflow-dir>/<folder-name>/
 Read all artifacts: 01-spec.md, 02-implementation.md, latest 03-qa*.md, any prior reviews.
 Read the actual code — do not trust the implementation report.
 Write the review as <04-review.md or 04-review-N.md> in the same folder.
+
+Update the progress log at every milestone (see "Progress Log (MANDATORY)" above). At minimum: phase start, before/after each review dimension (spec compliance, code quality, QA assessment), phase done. The phase-end line is required.
 ```
 
 **Autonomous overrides:** None. The review skill's adversarial stance is non-negotiable. Never soften review criteria to avoid fix loops.
 
 **Gate:** After the agent returns, read the review artifact and extract the verdict. If breakpoint is `review`, pause here (regardless of PASS or FAIL). Otherwise:
+
 - **PASS** → proceed to Step 6 (ship)
 - **FAIL** → enter the fix loop (Step 5F)
 
@@ -299,14 +283,14 @@ Write the review as <04-review.md or 04-review-N.md> in the same folder.
 
 When review returns FAIL:
 
-1. **Check iteration count** — count `04-review*.md` files in the workflow folder. If 10 exist, escalate: "Feature has failed review 10 times. Escalating for human judgment. Review history: [list all review files with their verdicts and key issues]."
+1. **Check iteration count** — count `04-review*.md` files in the workflow folder. If 3 exist, escalate: "Feature has failed review 3 times. Escalating for human judgment. Review history: [list all review files with their verdicts and key issues]."
 
 2. **Dispatch implementation agent in fix mode** — the implementation skill detects the FAIL review on startup. It reads the flagged issues, addresses only those issues, appends a "Fix Round N" section to `02-implementation.md`.
 
    Use the same dispatch pattern as Step 3, but:
-   - **Pre-seed TaskList** by parsing the latest `04-review*.md` "Summary for Fix Mode" section; one task per flagged issue — subject: `[impl-fix-N] <issue title>`. Add a trailing `[impl-fix-N] Run checks + append Fix Round to 02-implementation.md`.
    - **Dispatch mode:** background (`run_in_background: true`).
    - Task instructions:
+
    ```
    The latest review has FAILED. Enter fix mode.
 
@@ -315,11 +299,13 @@ When review returns FAIL:
    Read 02-implementation.md for current state.
    Address only the issues the review flagged.
    Append a Fix Round section to 02-implementation.md — do NOT overwrite existing content.
+
+   Update the progress log at every milestone (see "Progress Log (MANDATORY)" above). Log before/after each flagged issue. The phase-end line is required.
    ```
 
-3. **Dispatch QA agent** — re-runs QA, producing `03-qa-N.md`. Same dispatch (and pre-seed pattern) as Step 4.
+3. **Dispatch QA agent** — re-runs QA, producing `03-qa-N.md`. Same dispatch as Step 4.
 
-4. **Dispatch review agent** — re-runs review, producing `04-review-N.md`. Same dispatch (and pre-seed pattern) as Step 5.
+4. **Dispatch review agent** — re-runs review, producing `04-review-N.md`. Same dispatch as Step 5.
 
 5. **Read verdict:**
    - **PASS** → proceed to Step 6
@@ -331,15 +317,10 @@ When review returns FAIL:
 
 **Skill file:** `.claude/skills/ship/SKILL.md`
 
-**Pre-seed TaskList:**
-- `[ship] Stage changes`
-- `[ship] Commit`
-- `[ship] Push to remote`
-- `[ship] Open PR with assembled body`
-
 **Dispatch mode:** foreground (ship is quick).
 
 **Task instructions:**
+
 ```
 Ship the feature — commit, push, and create a PR.
 
@@ -347,9 +328,12 @@ Workflow folder: <workflow-dir>/<folder-name>/
 The branch already exists (created with the worktree). Use the current branch: <branch-name>
 The base branch is: <base-branch>
 Read all workflow artifacts to assemble the PR body.
+
+Update the progress log at every milestone (see "Progress Log (MANDATORY)" above). At minimum: phase start, before/after staging, committing, pushing, opening PR, phase done with PR URL.
 ```
 
 **Autonomous overrides:**
+
 - Skip Step 4's confirmation gate — execute the full pipeline (stage → commit → push → PR) without stopping. The review PASS verdict is the authorization.
 
 **Gate:** After the agent returns, verify the PR was created. Extract the PR URL and number from the agent's response. If breakpoint is `ship`, pause here.
@@ -374,13 +358,14 @@ CI monitoring is lightweight polling — no codebase exploration needed. This ru
 
 When CI checks fail, dispatch a focused fix agent:
 
-1. **Check iteration count** — if 10 CI fix attempts have already been made, escalate.
+1. **Check iteration count** — if 3 CI fix attempts have already been made, escalate.
 
 2. **Read failure logs** in the orchestrator — `gh run view <run-id> --log-failed --repo <owner>/<repo>` to get the failed job output. Extract the relevant error.
 
 3. **Dispatch a CI fix agent:**
 
    No skill file — this is a focused, self-contained prompt:
+
    ```
    You are a CI fix agent. A CI check has failed on a pull request. Your job is to make the minimal code change to fix the failure.
 
@@ -430,14 +415,14 @@ Write `05-indie-summary.md` in the workflow folder:
 
 ## Phases Completed
 
-| Phase | Artifact | Status | Iterations |
-|-------|----------|--------|------------|
-| Spec | 01-spec.md | Done | 1 |
-| Implementation | 02-implementation.md | Done | 1 (+ N fix rounds) |
-| QA | 03-qa.md — 03-qa-N.md | PASS | N |
-| Review | 04-review.md — 04-review-N.md | PASS | N |
-| Ship | PR #<number> | Created | 1 |
-| CI | <check names> | Pass | N attempts |
+| Phase          | Artifact                      | Status  | Iterations         |
+| -------------- | ----------------------------- | ------- | ------------------ |
+| Spec           | 01-spec.md                    | Done    | 1                  |
+| Implementation | 02-implementation.md          | Done    | 1 (+ N fix rounds) |
+| QA             | 03-qa.md — 03-qa-N.md         | PASS    | N                  |
+| Review         | 04-review.md — 04-review-N.md | PASS    | N                  |
+| Ship           | PR #<number>                  | Created | 1                  |
+| CI             | <check names>                 | Pass    | N attempts         |
 
 ## Review Loop Summary
 
@@ -459,6 +444,7 @@ Write `05-indie-summary.md` in the workflow folder:
 ```
 
 After writing the summary:
+
 1. Stage `05-indie-summary.md`: `git add <workflow-dir>/<folder-name>/05-indie-summary.md`
 2. Commit: `docs: add indie agent run summary for <feature-name>`
 3. Push to the same branch
@@ -470,16 +456,17 @@ Present the final report to the user: PR URL, check status, iteration counts, an
 ## Constraints
 
 **DO:**
+
 - Dispatch every phase to a subagent — never write code, tests, or reviews in the orchestrator
 - Read the skill file from disk before each dispatch — always use the latest version
-- Pre-seed a TaskList for every phase and embed the task IDs + progress-log path in the agent prompt
 - Dispatch implementation, QA, and fix-loop phases with `run_in_background: true` so the orchestrator stays responsive
 - Verify the output artifact after every agent returns before proceeding
 - Create a dedicated worktree for each new feature
 - Use short, scannable folder names in `wt/` (timestamp goes in the branch name, not the directory)
 - Check artifact state before each phase — never re-run completed phases
-- On "status" queries from the user while a subagent is running, read `_progress.log` + TaskList — never peek into the subagent's thinking (you can't)
-- Respect the 10-iteration cap on both the review loop and the CI fix loop
+- On "status" queries from the user while a subagent is running, read `_progress.log` — never peek into the subagent's thinking (you can't)
+- Reinforce the progress-log mandate in every phase's task instructions — the log is the only signal the orchestrator has
+- Respect the 3-iteration cap on both the review loop and the CI fix loop
 - Escalate with full context when hitting a cap or an unrecoverable error
 - Keep CI fixes minimal and scoped — fix only what CI flagged
 - Preserve the full audit trail — all review files, QA re-runs, and fix rounds are kept
@@ -487,11 +474,12 @@ Present the final report to the user: PR URL, check status, iteration counts, an
 - Run CI monitoring directly in the orchestrator (it's just polling)
 
 **DON'T:**
+
 - Perform skill work in the orchestrator — no code writing, no test writing, no reviewing
 - Ask the user anything during execution — the only interaction points are the initial input, breakpoints (if set), and the final report (or escalation)
 - Modify the review or QA skills' behavior — their independence is the quality gate
 - Skip phases — every phase runs, even if the code "looks fine"
-- Continue after 10 review FAILs or 10 CI fix failures — escalate, don't loop forever
+- Continue after 3 review FAILs or 3 CI fix failures — escalate, don't loop forever
 - Re-run completed phases on resume — read existing artifacts and pick up where you left off
 - Make large code changes during CI fixes — if the fix is architectural, escalate
 - Rewrite the spec after it's written — review issues are addressed in implementation fix mode

package/skills/patterns-refactor/SKILL.md

@@ -17,13 +17,7 @@ Activate when called from the `/refactor` command. Otherwise ignore.
 
 ## Input Handling
 
-`$ARGUMENTS` may be:
-
-- **Empty** — enter analyze mode: scan the codebase for bad patterns and produce a report
-- **`analyze`** — same as empty, explicit analyze mode
-- **`analyze <path>`** — analyze mode scoped to a directory
-- **A pattern description** (free text) — enter refactor mode: find all instances of this pattern and fix them. Example: `"API calls use raw fetch with try/catch instead of a wrapper function"`
-- **A reference to an analysis report entry** — enter refactor mode for a specific finding. Example: `"#3 from codebase patterns report"` or a path to a report file
+Take whatever was passed and infer the mode: empty or a directory path runs analyze mode (scan the codebase for bad patterns and write a report); a pattern description or a reference to an analysis report entry runs refactor mode (find all instances and fix them).
 
 ---
 

package/skills/qa-engineer/SKILL.md

@@ -9,9 +9,9 @@ description: Owns the e2e tree end-to-end. Reads the spec and Gherkin .feature f
 
 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 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.
+You test what the spec promised, not what the implementation claims it did.
 
-**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.
+**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. Spec-writer walks the project's Gherkin coverage map and authorizes `.feature` files (extension or new) in Gherkin Impact; you implement them and may further extend when implementation surfaces a scenario the spec didn't anticipate.
 
 ## When to Apply
 
@@ -21,11 +21,7 @@ Activate when called from the `/qa` command. Otherwise ignore.
 
 ## Input Handling
 
-`$ARGUMENTS` may be:
-
-- A **folder name** (e.g. `20260413-1423-dark-mode`)
-- A **path** to the workflow folder
-- **Empty** — auto-detect: scan the workflow directory for folders that have `02-implementation.md` but no `03-qa.md`, or where the latest review is FAIL (QA needs to re-run after fix mode). If exactly one exists, use it. If multiple, list and ask. If none, tell the user there are no implementations ready for QA.
+Take whatever was passed — workflow folder name, path, or empty to auto-detect (one folder with `02-implementation.md` and no `03-qa.md`, or where the latest review is FAIL; ask if multiple).
 
 ---
 
@@ -48,11 +44,11 @@ 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 spec has no `Gherkin Impact` section, stop and warn**: *"Spec is missing the required `Gherkin Impact` section. 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. List what's there and identify the file(s) that cover the capability being tested. If `features/` doesn't exist or the capability has no `.feature` file, that's normal — Gherkin Impact tells you whether to extend, create, or route away. If Gherkin Impact authorizes neither extension nor creation 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 the 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 +112,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):**
 
@@ -126,8 +123,6 @@ For each AC routed to a Gherkin scenario, decide *how* to land it. The order mat
 
 **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 5b — Implement Scenarios in Test Files
@@ -205,16 +200,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 +288,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,8 +309,8 @@ 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,8 +323,10 @@ 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:`.
 - "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.

package/skills/review/SKILL.md

@@ -19,11 +19,7 @@ Activate when called from the `/review` command. Otherwise ignore.
 
 ## Input Handling
 
-`$ARGUMENTS` may be:
-
-- A **folder name** (e.g. `20260413-1423-dark-mode`)
-- A **path** to the workflow folder
-- **Empty** — auto-detect: scan the workflow directory for folders that have `02-implementation.md` and (ideally) `03-qa.md` but no `04-review.md`. If exactly one exists, use it. If multiple, list and ask. If none, tell the user there are no implementations ready for review.
+Take whatever was passed — workflow folder name, path, or empty to auto-detect (one folder with `02-implementation.md` and ideally `03-qa.md` but no `04-review.md`; ask if multiple).
 
 ---
 

package/skills/ship/SKILL.md

@@ -19,11 +19,7 @@ Activate when called from the `/ship` command. Otherwise ignore.
 
 ## Input Handling
 
-`$ARGUMENTS` may be:
-
-- A **folder name** (e.g. `20260413-1423-dark-mode`)
-- A **path** to the workflow folder
-- **Empty** — auto-detect: scan the workflow directory for folders that have a PASS review (latest `04-review*.md` with PASS verdict) but no PR yet created. If exactly one exists, use it. If multiple, list and ask.
+Take whatever was passed — workflow folder name, path, or empty to auto-detect (one folder with a PASS review and no PR yet; ask if multiple).
 
 ---
 

package/skills/spec-writer/SKILL.md

@@ -7,7 +7,7 @@ description: Analyzes requirements and explores the codebase to produce an imple
 
 ## Role
 
-You are a senior software architect producing implementation specs. You analyze requirements, explore the codebase, and write detailed, actionable specs that another agent (or human) can follow to implement a feature end-to-end.
+You are a world class, senior software architect that produces specification documents. You analyze requirements, explore the codebase, and write detailed, actionable specs that another agent can follow to implement a feature end-to-end.
 
 You are concise but thorough. You make decisions — you don't list alternatives.
 
@@ -17,28 +17,9 @@ Activate when called from the `/spec` command. Otherwise ignore.
 
 ---
 
-## Input Handling
+## Step 1 — Read the Input
 
-`$ARGUMENTS` may be:
-
-- A **GitHub issue URL** (e.g. `https://github.com/org/repo/issues/42`)
-- **Free text** describing what to build or fix
-- A **path to an existing spec** (e.g. `_workflow/20260413-1423-dark-mode/01-spec.md`) — enters **edit mode**
-- **Empty** — ask the user: "What would you like me to spec? Describe a feature or paste a GitHub issue URL."
-
----
-
-## Step 1 — Parse Input
-
-**If a GitHub issue URL:**
-1. Extract org, repo, and issue number from the URL
-2. Fetch the issue: `gh issue view <number> --repo <org>/<repo>`
-3. Fetch comments: `gh issue view <number> --repo <org>/<repo> --comments`
-4. Use the title + body + comments as the requirements source
-
-**If free text:** Use it directly as the requirements source.
-
-**If a path to an existing spec:** Enter edit mode (see Edit Mode section below).
+Take whatever was passed as the requirements source: a brief, a free-text description, a GitHub issue URL, or a path to an existing spec. If a GitHub issue URL, fetch it (`gh issue view <number> --repo <org>/<repo> --comments`) and use title + body + comments. If a path to an existing spec, enter edit mode (see Edit Mode section below). If nothing was passed, ask once.
 
 ---
 
@@ -47,17 +28,17 @@ Activate when called from the `/spec` command. Otherwise ignore.
 1. Read the project's `CLAUDE.md`
 2. Find the `## Workflow Config` section and parse the key-value table:
 
-| Key | Used by |
-|-----|---------|
-| `workflow-dir` | spec-writer, all skills |
-| `test-cmd` | implementation, ship |
-| `lint-cmd` | implementation, ship |
-| `build-cmd` | implementation, ship |
-| `e2e-cmd` | qa-engineer |
-| `e2e-framework` | qa-engineer |
-| `tdd` | implementation |
-| `branch-prefix` | ship |
-| `base-branch` | ship |
+| Key             | Used by                 |
+| --------------- | ----------------------- |
+| `workflow-dir`  | spec-writer, all skills |
+| `test-cmd`      | implementation, ship    |
+| `lint-cmd`      | implementation, ship    |
+| `build-cmd`     | implementation, ship    |
+| `e2e-cmd`       | qa-engineer             |
+| `e2e-framework` | qa-engineer             |
+| `tdd`           | implementation          |
+| `branch-prefix` | ship                    |
+| `base-branch`   | ship                    |
 
 3. If the `## Workflow Config` section doesn't exist, **stop and warn the user**: "No Workflow Config found in CLAUDE.md. Run `/adjust` to set up the project for this workflow."
 
@@ -73,7 +54,7 @@ Before exploring the codebase, spend 30 seconds on a sanity check:
 - Are there obvious unknowns — missing info, ambiguous scope, contradictory requirements?
 - What is the likely complexity? (Bug fix / small feature / large feature)
 
-**If there are blockers:** Surface 1–3 targeted questions to the user. Do not proceed until the requirements are clear enough to explore the right areas of the codebase.
+**If there are blockers:** Make a reasonable decision for each one and document the assumption in the spec's Decisions section. Don't pause and ask — record the call clearly so the user can correct it on review.
 
 **If requirements are clear:** Move on. This is a brief gate, not a discussion phase.
 
@@ -93,21 +74,17 @@ Do not prescribe a fixed search strategy. Every codebase is shaped differently.
 
 ---
 
-## Step 4b — Survey `.feature` Files
+## Step 4b — Cover the User Journey
 
-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.
+`.feature` files are user journeys. Read `features/*.feature` and find the journey this PR touches.
 
-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.
+- **Journey already there** → extend its `.feature`. Preference: `Scenario Outline` row > `And`-step > new scenario in the same file.
+- **Journey not there yet** → think from a user perspective. What journey does this code serve? Add `features/<journey>.feature` and authorize it in Gherkin Impact.
+- **No user-observable surface** (dependency bump, internal refactor) → route the AC to lint / unit / impl check-result.
 
-This survey feeds the spec's "Gherkin Impact" section (Step 7).
+**Venue set (closed):** `{Gherkin scenario, lint rule, unit test, impl check-result}`. Plain Playwright `.spec.ts` outside `features/` is not a venue. Every `.spec.ts` has a sibling `.feature`.
 
-> **No new `.feature` files at the per-feature level.** New `.feature` files are bootstrap territory. Per-feature work extends what exists.
+This feeds Gherkin Impact (Step 7).
 
 ---
 
@@ -116,6 +93,7 @@ This survey feeds the spec's "Gherkin Impact" section (Step 7).
 Based on complexity detected in steps 3–4, choose a depth:
 
 ### Lightweight (bug fixes, small changes — touches 1–3 files)
+
 - Context: 2–3 sentences
 - Current State: brief, just the affected files
 - Implementation Steps: 1–3 steps, can be terse
@@ -123,9 +101,11 @@ Based on complexity detected in steps 3–4, choose a depth:
 - Skip Patterns to Follow
 
 ### Standard (typical features — touches 4–10 files)
+
 - Full format (see Step 7)
 
 ### Deep (large features, new subsystems — touches 10+ files or creates new patterns)
+
 - Full format + High-Level Approach section before Implementation Steps
 - More detailed Current State documenting relevant architecture
 - Acceptance criteria grouped by area
@@ -165,10 +145,12 @@ Why this is needed. 2–3 sentences. Include relevant discussion from issue comm
 ## Requirements
 
 What must be true when this is done:
+
 - Requirement 1
 - Requirement 2
 
 **Out of scope:**
+
 - What this explicitly does NOT cover
 
 ## Current State
@@ -203,34 +185,40 @@ 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.)
-
 **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>
+- **`And`-step additions:** `<scenario title>` gains _"And <new assertion>"_ under <Given/When/Then>
+- **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.
 
 ## Workflow Config
 
 (Copied from CLAUDE.md — downstream skills read this instead of re-parsing CLAUDE.md)
 
-| Key | Value |
-|-----|-------|
-| workflow-dir | ... |
-| test-cmd | ... |
-| lint-cmd | ... |
-| build-cmd | ... |
-| e2e-cmd | ... |
-| e2e-framework | ... |
-| tdd | ... |
-| branch-prefix | ... |
-| base-branch | ... |
+| Key           | Value |
+| ------------- | ----- |
+| workflow-dir  | ...   |
+| test-cmd      | ...   |
+| lint-cmd      | ...   |
+| build-cmd     | ...   |
+| e2e-cmd       | ...   |
+| e2e-framework | ...   |
+| tdd           | ...   |
+| branch-prefix | ...   |
+| base-branch   | ...   |
 ```
 
 ---
@@ -264,6 +252,7 @@ When invoked with a path to an existing spec (or the user asks to revise):
 ## Constraints
 
 **DO:**
+
 - 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)
@@ -275,12 +264,14 @@ When invoked with a path to an existing spec (or the user asks to revise):
 - Make decisions — be opinionated
 
 **DON'T:**
+
 - Write implementation code in the spec — describe what to build, not the code itself
 - Propose new patterns when existing patterns in the codebase work
 - 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 — 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 +285,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. Gherkin Impact is required. Either authorize a new file 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.