@devshop/crew 0.10.1 → 0.11.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [0.11.1](https://github.com/devshop-software/crew/compare/v0.11.0...v0.11.1) (2026-05-09)
+
+
+### Bug Fixes
+
+* **indie-agent:** timestamp workflow folders, commit progress log on run-done ([c9c8c35](https://github.com/devshop-software/crew/commit/c9c8c35c00c080f363c33c62595d6440b446547e))
+
+# [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)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devshop/crew",
-  "version": "0.10.1",
+  "version": "0.11.1",
   "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."
@@ -72,14 +58,15 @@ The input may include a breakpoint instruction. Parse and strip it before passin
 
 ## Step 1W — Worktree Setup (new features only)
 
-1. **Derive the folder name:** Short, scannable kebab-case name (2–5 words) derived from the input. No timestamp prefix in the directory name. Example: `dark-mode`, `auth-refactor`, `db-seed-script`
-2. **Derive the branch name:** `<branch-prefix>YYYYMMDD-HHMM-<folder-name>` using the current timestamp. Example: `feature/20260413-1423-dark-mode`. The timestamp lives in the branch name, not the directory.
-3. **Determine the worktree path:** `../../wt/<folder-name>` — inside the `wt/` subdirectory at the project root. Example: if you're running from `~/projects/rival.sale/main`, the worktree goes to `~/projects/rival.sale/wt/dark-mode`.
+1. **Derive the folder name:** `YYYYMMDD-HHMM-<kebab>` using the current local timestamp + a short kebab-case description (2–5 words) derived from the input. Example: `20260509-1932-competitor-monitoring-toggle`. The timestamped form is the single name used for the workflow folder, the worktree directory, and the branch suffix — folders sort chronologically when listed.
+2. **Derive the branch name:** `<branch-prefix><folder-name>`. Example: `feature/20260509-1932-competitor-monitoring-toggle`.
+3. **Determine the worktree path:** `../../wt/<folder-name>` — inside the `wt/` subdirectory at the project root. Example: if you're running from `~/projects/rival.sale/main`, the worktree goes to `~/projects/rival.sale/wt/20260509-1932-competitor-monitoring-toggle`.
 4. **Create the worktree:** `mkdir -p ../../wt && git worktree add <worktree-path> -b <branch-name> <base-branch>`
 5. **Copy local environment files:** Copy `.env` (and `.env.local` if it exists) from the current worktree into the new worktree. These are gitignored and won't exist in the fresh checkout.
 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,9 +444,13 @@ 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
+
+1. Append a final `[orchestrator] <ISO-8601 UTC> — run done` line to `<workflow-dir>/<folder-name>/_progress.log`.
+2. Stage both the summary and the progress log: `git add <workflow-dir>/<folder-name>/05-indie-summary.md <workflow-dir>/<folder-name>/_progress.log`
+3. Commit: `docs: add indie agent run summary for <feature-name>`
+4. Push to the same branch
+
+Why both files: ship's own log lines (commit, push, PR creation) are written *after* ship's commit and never make it into the PR otherwise. This step is the catch-all that ensures the full run is recorded in git.
 
 Present the final report to the user: PR URL, check status, iteration counts, and worktree path. Remind: "After merge, clean up with: `git worktree remove <path> && rm -rf <path>`"
 
@@ -470,16 +459,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)
+- Timestamp the workflow folder, worktree directory, and branch with the same `YYYYMMDD-HHMM-<kebab>` form so workflows sort chronologically
 - 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 +477,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,13 +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. 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.
+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 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.
+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?"
 
@@ -129,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
@@ -319,7 +311,6 @@ Present:
 - 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
 
 ---
 
@@ -336,7 +327,6 @@ If you catch yourself thinking any of these, stop:
 - "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,22 +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. 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 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.
+- **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`.
 
-> **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.
+This feeds Gherkin Impact (Step 7).
 
 ---
 
@@ -117,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
@@ -124,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
@@ -166,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
@@ -204,38 +185,40 @@ What to replicate from the template and what differs for this feature.
 
 ## Gherkin Impact
 
-(**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>  *(EXISTING — extension)*
-- `features/<new-capability>.feature` — <one-line capability summary>  *(NEW FILE — see "New file justification" below)*
+
+- `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>
+- **`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   | ...   |
 ```
 
 ---
@@ -269,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)
@@ -280,13 +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 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.
+- 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
 
 ---
@@ -300,6 +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 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.
+- "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.