work-kit-cli 0.2.8 → 0.4.0

package/skills/resume-kit/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: resume-kit
+description: "Resume a paused or abandoned work-kit session and continue where it left off. Usage: /resume-kit"
+user-invocable: true
+allowed-tools: Bash, Read, Agent, Write, Edit, Glob, Grep
+---
+
+You are resuming a work-kit session. The user typically runs Claude Code from the **main repo root**, not from inside a worktree, so you must discover resumable sessions across all worktrees of the current repo and let the user pick one. Both `paused` and `in-progress` sessions are listed, since a crashed terminal leaves state as `in-progress`.
+
+## Steps
+
+1. From the main repo root, run:
+   ```bash
+   work-kit resume
+   ```
+   This scans every worktree of the current git repo for `.work-kit/tracker.json` files in `paused` or `in-progress` state and returns one of:
+
+   - `action: "error"` — no resumable sessions in this repo. Tell the user and stop.
+   - `action: "select_session"` — one or more sessions found. The `sessions` array is sorted by most-recently-updated first and contains entries like:
+     ```json
+     {
+       "slug": "item-count-badge",
+       "branch": "feat/item-count-badge",
+       "worktreeRoot": "/abs/path/to/worktree",
+       "status": "paused",
+       "pausedAt": "2026-04-06T18:42:11.000Z",
+       "currentPhase": "build",
+       "currentStep": "implement",
+       "lastUpdatedAgoMs": 7320000
+     }
+     ```
+   - `action: "resumed"` — only happens if you passed `--worktree-root` directly (not the default flow).
+
+2. **Show the list to the user.** Format it as a numbered list with: slug, status, current phase/step, **last updated time** (humanized from `lastUpdatedAgoMs`), and branch. The last-updated column is critical — it lets the user spot a session that was "closed by mistake" (high age + `in-progress` = likely a crashed terminal). Example:
+   ```
+   Found 3 resumable sessions (most recent first):
+     1. fix-csv-export        in-progress  (test/e2e,        updated 30s ago)   ← still running elsewhere?
+     2. item-count-badge      paused       (build/implement, updated 2h ago)    feat/item-count-badge
+     3. dark-mode-toggle      in-progress  (plan/clarify,    updated 3d ago)    ← likely abandoned
+   Which one do you want to resume? (number or slug)
+   ```
+   When you see an `in-progress` session with a recent `lastUpdatedAgoMs` (< a few minutes), warn the user that another Claude instance may still be working on it. When you see one with a large age, hint that it was probably closed without pausing.
+   Wait for the user to reply.
+
+3. Once the user picks one, resolve it to a slug and run:
+   ```bash
+   work-kit resume --slug <slug>
+   ```
+   The result will be `action: "resumed"` with `worktreeRoot`, `phase`, and `step` populated.
+
+4. **`cd` into the returned `worktreeRoot`.** All subsequent commands must run from there, not from the main repo root.
+
+5. Continue the orchestrator loop (same as `/full-kit` / `/auto-kit`):
+   ```bash
+   work-kit next
+   ```
+   Then follow the action returned (`spawn_agent`, `spawn_parallel_agents`, `wait_for_user`, etc.) using the Agent tool. Keep looping `work-kit next` until you hit `wait_for_user`, `complete`, or `error`.
+
+## Notes
+
+- `work-kit resume` (no args) is read-only — it just lists paused sessions, it doesn't flip any state. State changes only happen on `--slug`.
+- `work-kit resume --slug <slug>` is idempotent: if the matched session is already in-progress, it returns `action: "resumed"` without re-writing the tracker.
+- A paused session keeps all state — phases, steps, loopbacks, timing — exactly as they were.
+- If the user invokes `/resume-kit <slug>` (passing a slug directly), skip the listing step and call `work-kit resume --slug <slug>` immediately.

package/skills/wk-bootstrap/SKILL.md

@@ -7,13 +7,19 @@ allowed-tools: Bash, Read
 
 # Session Bootstrap
 
-Run `npx work-kit-cli bootstrap` to detect work-kit state.
+Run `work-kit bootstrap` to detect work-kit state.
 
 ## If active work exists
 
-- Report current state to the user: slug, phase, sub-stage, status
+- Report current state to the user: slug, phase, step, status
+- **If `knowledge` is present in the bootstrap output**, surface it to the agent and the user:
+  - `knowledge.lessons` — project-specific learnings from prior sessions
+  - `knowledge.conventions` — codified rules this project follows
+  - `knowledge.risks` — fragile or dangerous areas to handle with care
+  - Read each of these silently into your working context — they're prior knowledge you should respect when planning and building. Briefly mention to the user that prior knowledge was loaded (one line; do not dump the full text into the chat).
+  - `workflow.md` is intentionally NOT loaded — it's a write-only artifact for human curators.
 - If recovery is suggested: follow the recovery instruction
-- Otherwise: run `npx work-kit-cli next` to continue the workflow
+- Otherwise: run `work-kit next` to continue the workflow
 
 ## If no active work
 
@@ -24,6 +30,6 @@ Run `npx work-kit-cli bootstrap` to detect work-kit state.
 ## If session is stale
 
 - Report the staleness warning to the user
-- Run `npx work-kit-cli status` to get full diagnostics
-- If the state is recoverable, run `npx work-kit-cli next` to resume
+- Run `work-kit status` to get full diagnostics
+- If the state is recoverable, run `work-kit next` to resume
 - If the state is corrupted, suggest starting fresh

package/skills/wk-build/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: build
-description: "Run the Build phase — 8 sub-stages from Setup to Commit. Follows the Blueprint from Plan."
+description: "Run the Build phase — 8 steps from Setup to Commit. Follows the Blueprint from Plan."
 user-invocable: false
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 ---
 
 You are the **Lead Developer**. Execute the implementation plan from the Blueprint precisely.
 
-## Sub-stages (in order)
+## Steps (in order)
 
 1. **Setup** — Create branch, install deps, scaffold
 2. **Migration** — Database schema changes
@@ -20,12 +20,12 @@ You are the **Lead Developer**. Execute the implementation plan from the Bluepri
 
 ## Execution
 
-For each sub-stage:
-1. Read the sub-stage file (e.g., `.claude/skills/wk-build/stages/setup.md`)
+For each step:
+1. Read the step file (e.g., `.claude/skills/wk-build/steps/setup.md`)
 2. Reference the Blueprint in `.work-kit/state.md` — follow its steps for this layer
 3. Write actual code, run actual commands
 4. Update `.work-kit/state.md` with outputs
-5. Proceed to the next sub-stage
+5. Proceed to the next step
 
 ## Key Principle
 
@@ -33,18 +33,19 @@ For each sub-stage:
 
 ## Recording
 
-Throughout every sub-stage, capture three things in the shared state.md sections:
+Throughout every step, capture these things in the shared state.md sections:
 
 - **`## Decisions`** — Whenever you choose between real alternatives, append: `**<context>**: chose <X> over <Y> — <why>`. Skip obvious choices.
 - **`## Deviations`** — Whenever you diverge from the Blueprint, append: `**<Blueprint step>**: <what changed> — <why>`. Every deviation needs a reason.
+- **`## Observations`** — Whenever you notice a project convention, a fragile area, a learning, or feedback about the work-kit workflow itself, append a typed bullet: `- [lesson|convention|risk|workflow] text` (workflow tag may include `:phase/step`). At `wrap-up/knowledge` these are routed to `.work-kit-knowledge/` so future sessions benefit.
 
-These feed into the final work-kit log summary. If you don't record them here, they're lost.
+These feed into the final work-kit log summary and the project knowledge files. If you don't record them here, they're lost.
 
 ## Boundaries
 
 ### Always
 - Follow the Blueprint step order unless a dependency requires reordering
-- Run the test suite after every sub-stage that changes code
+- Run the test suite after every step that changes code
 - Record every deviation from the Blueprint in the ## Deviations section
 - Match existing codebase patterns found during Plan/Investigate
 - Commit .work-kit/ files separately from feature code
@@ -53,7 +54,7 @@ These feed into the final work-kit log summary. If you don't record them here, t
 - Redesigning any part of the Blueprint (adapt minimally, don't redesign)
 - Adding dependencies not specified in the Blueprint
 - Changing the data model beyond what Architecture specified
-- Skipping the Red (failing tests) sub-stage
+- Skipping the Red (failing tests) step
 
 ### Never
 - Write implementation code before writing failing tests (Red comes before Core)
@@ -78,11 +79,11 @@ This phase runs as a **fresh agent**. Read only these sections from `.work-kit/s
 - `## Criteria` — what "done" looks like
 - `## Description` — original request for context
 
-Do NOT read the Plan sub-stage working notes (Clarify, Investigate, Sketch, etc.) — they're consumed by Plan: Final.
+Do NOT read the Plan step working notes (Clarify, Investigate, Sketch, etc.) — they're consumed by Plan: Final.
 
 ## Final Output
 
-After all sub-stages are done, append a `### Build: Final` section to state.md. This is the **only section the Test agent reads**.
+After all steps are done, append a `### Build: Final` section to state.md. This is the **only section the Test agent reads**.
 
 ```markdown
 ### Build: Final

package/skills/wk-build/{stages → steps}/commit.md

@@ -1,5 +1,5 @@
 ---
-description: "Build sub-stage: Create clean commits, push branch, create PR."
+description: "Build step: Create clean commits, push branch, create PR."
 ---
 
 # Commit

package/skills/wk-build/{stages → steps}/core.md

@@ -1,5 +1,5 @@
 ---
-description: "Build sub-stage: Make failing tests pass — service layer, API, business logic (TDD green phase)."
+description: "Build step: Make failing tests pass — service layer, API, business logic (TDD green phase)."
 ---
 
 # Core — Make Tests Pass
@@ -42,8 +42,8 @@ description: "Build sub-stage: Make failing tests pass — service layer, API, b
 ## Rules
 
 - Write the **minimum** code to pass tests — no gold-plating
-- Don't refactor yet — that's the Refactor sub-stage
-- Don't build UI yet — that's the UI sub-stage
+- Don't refactor yet — that's the Refactor step
+- Don't build UI yet — that's the UI step
 - If a test expectation seems wrong, fix the test only if the Blueprint supports it
 - Match existing code patterns exactly — naming, file structure, error handling
 

package/skills/wk-build/{stages → steps}/integration.md

@@ -1,5 +1,5 @@
 ---
-description: "Build sub-stage: Wire everything together, verify full data flow end-to-end."
+description: "Build step: Wire everything together, verify full data flow end-to-end."
 ---
 
 # Integration
@@ -49,4 +49,4 @@ description: "Build sub-stage: Wire everything together, verify full data flow e
 |--------|---------|
 | "Unit tests passing means integration is fine" | Unit tests mock boundaries. Integration failures live at the boundaries — where your code meets the database, API, or UI layer. |
 | "I already verified data flow during Core" | Core verified that individual pieces work. Integration verifies they work together. A function that passes its unit test can still send the wrong data shape to the next function. |
-| "Integration testing is the Test phase's job" | The Test phase runs automated suites. This sub-stage verifies that the pieces you just built actually connect. Finding a wiring bug here takes 5 minutes; finding it in Test takes 30. |
+| "Integration testing is the Test phase's job" | The Test phase runs automated suites. This step verifies that the pieces you just built actually connect. Finding a wiring bug here takes 5 minutes; finding it in Test takes 30. |

package/skills/wk-build/{stages → steps}/migration.md

@@ -1,5 +1,5 @@
 ---
-description: "Build sub-stage: Generate and verify database schema changes."
+description: "Build step: Generate and verify database schema changes."
 ---
 
 # Migration

package/skills/wk-build/{stages → steps}/red.md

@@ -1,5 +1,5 @@
 ---
-description: "Build sub-stage: Write failing tests BEFORE implementation (TDD red phase)."
+description: "Build step: Write failing tests BEFORE implementation (TDD red phase)."
 ---
 
 # Red — Write Failing Tests

package/skills/wk-build/{stages → steps}/refactor.md

@@ -1,5 +1,5 @@
 ---
-description: "Build sub-stage: Improve code quality while keeping all tests green (TDD refactor phase)."
+description: "Build step: Improve code quality while keeping all tests green (TDD refactor phase)."
 ---
 
 # Refactor

package/skills/wk-build/{stages → steps}/setup.md

@@ -1,5 +1,5 @@
 ---
-description: "Build sub-stage: Branch creation, dependency installation, scaffolding."
+description: "Build step: Branch creation, dependency installation, scaffolding."
 ---
 
 # Setup

package/skills/wk-build/{stages → steps}/ui.md

@@ -1,5 +1,5 @@
 ---
-description: "Build sub-stage: Implement UI components, pages, and interactions."
+description: "Build step: Implement UI components, pages, and interactions."
 ---
 
 # UI

package/skills/wk-deploy/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: deploy
-description: "Run the Deploy phase (optional) — 3 sub-stages: Merge, Monitor, Remediate."
+description: "Run the Deploy phase (optional) — 3 steps: Merge, Monitor, Remediate."
 user-invocable: false
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 ---
 
 You are the **Release Engineer**. Get this PR merged and deployed safely.
 
-## Sub-stages (in order)
+## Steps (in order)
 
 1. **Merge** — Get the PR merged safely
 2. **Monitor** — Watch for deployment issues
@@ -15,11 +15,11 @@ You are the **Release Engineer**. Get this PR merged and deployed safely.
 
 ## Execution
 
-For each sub-stage:
-1. Read the sub-stage file (e.g., `.claude/skills/wk-deploy/stages/merge.md`)
+For each step:
+1. Read the step file (e.g., `.claude/skills/wk-deploy/steps/merge.md`)
 2. Follow its instructions
 3. Update `.work-kit/state.md` with outputs
-4. Proceed to next sub-stage
+4. Proceed to next step
 
 ## Key Principle
 
@@ -30,6 +30,7 @@ For each sub-stage:
 Update the shared state.md sections:
 
 - **`## Decisions`** — Record merge method choice, any rollback decisions.
+- **`## Observations`** — Whenever you notice deploy fragility, a missing convention, or feedback about the deploy phase itself, append: `- [lesson|convention|risk|workflow] text` (workflow tag may include `:phase/step`). At `wrap-up/knowledge` these are routed to `.work-kit-knowledge/` so future sessions benefit.
 
 ## This phase is optional
 
@@ -63,7 +64,7 @@ This phase runs as a **fresh agent**. Read only these sections from `.work-kit/s
 
 ## Final Output
 
-After all sub-stages are done, append a `### Deploy: Final` section to state.md. This is what **Wrap-up reads**.
+After all steps are done, append a `### Deploy: Final` section to state.md. This is what **Wrap-up reads**.
 
 ```markdown
 ### Deploy: Final

package/skills/wk-deploy/{stages → steps}/merge.md

@@ -1,5 +1,5 @@
 ---
-description: "Deploy sub-stage: Get the PR merged safely."
+description: "Deploy step: Get the PR merged safely."
 ---
 
 # Merge

package/skills/wk-deploy/{stages → steps}/monitor.md

@@ -1,5 +1,5 @@
 ---
-description: "Deploy sub-stage: Monitor deployment after merge."
+description: "Deploy step: Monitor deployment after merge."
 ---
 
 # Monitor

package/skills/wk-deploy/{stages → steps}/remediate.md

@@ -1,5 +1,5 @@
 ---
-description: "Deploy sub-stage: Handle deployment outcome — confirm success or manage failure."
+description: "Deploy step: Handle deployment outcome — confirm success or manage failure."
 ---
 
 # Remediate

package/skills/wk-plan/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: plan
-description: "Run the Plan phase — 8 sub-stages from Clarify to Audit."
+description: "Run the Plan phase — 8 steps from Clarify to Audit."
 user-invocable: false
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 ---
 
-You are the **Planning Lead**. Work through 8 focused sub-stages to produce a complete, executable Blueprint.
+You are the **Planning Lead**. Work through 8 focused steps to produce a complete, executable Blueprint.
 
-## Sub-stages (in order)
+## Steps (in order)
 
 1. **Clarify** — Understand the request, define acceptance criteria, clarify requirements
 2. **Investigate** — Read codebase, trace paths, map blast radius
@@ -20,24 +20,25 @@ You are the **Planning Lead**. Work through 8 focused sub-stages to produce a co
 
 ## Execution
 
-For each sub-stage:
-1. Read the sub-stage file (e.g., `.claude/skills/wk-plan/stages/clarify.md`)
+For each step:
+1. Read the step file (e.g., `.claude/skills/wk-plan/steps/clarify.md`)
 2. Follow its instructions completely
-3. Write outputs to `.work-kit/state.md` under a section for that sub-stage
-4. Update `**Phase:** plan` and `**Sub-stage:** <current>` in state.md
-5. Proceed to the next sub-stage
+3. Write outputs to `.work-kit/state.md` under a section for that step
+4. Update `**Phase:** plan` and `**Step:** <current>` in state.md
+5. Proceed to the next step
 
 ## Continuity
 
-Maintain context across all sub-stages — each builds on the previous. Reference prior outputs explicitly. Don't re-discover what you already found.
+Maintain context across all steps — each builds on the previous. Reference prior outputs explicitly. Don't re-discover what you already found.
 
 ## Recording
 
-Throughout every sub-stage, capture two things in the shared state.md sections:
+Throughout every step, capture these things in the shared state.md sections:
 
 - **`## Decisions`** — Whenever you choose between real alternatives, append: `**<context>**: chose <X> over <Y> — <why>`. Skip obvious choices.
+- **`## Observations`** — Whenever you notice a project convention, a fragile area, a learning, or feedback about the work-kit workflow itself, append a typed bullet: `- [lesson|convention|risk|workflow] text` (workflow tag may include `:phase/step`). At `wrap-up/knowledge` these are routed to `.work-kit-knowledge/` so future sessions benefit.
 
-These feed into the final work-kit log summary. If you don't record decisions here, they're lost.
+These feed into the final work-kit log summary and the project knowledge files. If you don't record them here, they're lost.
 
 ## Loop-back
 
@@ -49,7 +50,7 @@ If **Audit** returns "revise":
 
 ## Final Output
 
-After all sub-stages are done, append a `### Plan: Final` section to state.md. This is the **only section the Build agent reads** — it must be self-contained.
+After all steps are done, append a `### Plan: Final` section to state.md. This is the **only section the Build agent reads** — it must be self-contained.
 
 ```markdown
 ### Plan: Final
@@ -57,10 +58,10 @@ After all sub-stages are done, append a `### Plan: Final` section to state.md. T
 **Verdict:** ready | revised_with_caveats
 
 **Blueprint:**
-<the full ordered implementation plan from Blueprint sub-stage — copy it here>
+<the full ordered implementation plan from Blueprint step — copy it here>
 
 **Architecture:**
-<data model, API surface, components, service layer — from Architecture sub-stage>
+<data model, API surface, components, service layer — from Architecture step>
 
 **Criteria:**
 <reference to ## Criteria section>

package/skills/wk-plan/{stages → steps}/architecture.md

@@ -1,5 +1,5 @@
 ---
-description: "Plan sub-stage: Define technical design — data model, API surface, component structure."
+description: "Plan step: Define technical design — data model, API surface, component structure."
 ---
 
 # Architecture

package/skills/wk-plan/{stages → steps}/audit.md

@@ -1,5 +1,5 @@
 ---
-description: "Plan sub-stage: Audit the Blueprint for gaps, contradictions, and coverage."
+description: "Plan step: Audit the Blueprint for gaps, contradictions, and coverage."
 ---
 
 # Audit
@@ -9,7 +9,7 @@ description: "Plan sub-stage: Audit the Blueprint for gaps, contradictions, and
 
 ## Instructions
 
-1. Re-read ALL prior sub-stage outputs (Clarify through Blueprint)
+1. Re-read ALL prior step outputs (Clarify through Blueprint)
 2. Check for:
    - **Gaps:** Steps missing that are needed to satisfy criteria
    - **Contradictions:** Blueprint says X but Architecture says Y

package/skills/wk-plan/{stages → steps}/blueprint.md

@@ -1,5 +1,5 @@
 ---
-description: "Plan sub-stage: Produce a full ordered step-by-step implementation plan."
+description: "Plan step: Produce a full ordered step-by-step implementation plan."
 ---
 
 # Blueprint
@@ -9,7 +9,7 @@ description: "Plan sub-stage: Produce a full ordered step-by-step implementation
 
 ## Instructions
 
-1. Synthesize ALL prior sub-stage outputs (Clarify → Architecture) into one executable plan
+1. Synthesize ALL prior step outputs (Clarify → Architecture) into one executable plan
 2. Order steps by dependency — what must be done first
 3. Each step must specify:
    - What to do (create file, modify function, run command)

package/skills/wk-plan/{stages → steps}/clarify.md

@@ -1,5 +1,5 @@
 ---
-description: "Plan sub-stage: Understand the request, define acceptance criteria, and clarify requirements."
+description: "Plan step: Understand the request, define acceptance criteria, and clarify requirements."
 ---
 
 # Clarify

package/skills/wk-plan/{stages → steps}/investigate.md

@@ -1,5 +1,5 @@
 ---
-description: "Plan sub-stage: Read codebase systematically, trace paths, map blast radius."
+description: "Plan step: Read codebase systematically, trace paths, map blast radius."
 ---
 
 # Investigate

package/skills/wk-plan/{stages → steps}/scope.md

@@ -1,5 +1,5 @@
 ---
-description: "Plan sub-stage: Define in/out scope, estimate complexity, refine criteria."
+description: "Plan step: Define in/out scope, estimate complexity, refine criteria."
 ---
 
 # Scope

package/skills/wk-plan/{stages → steps}/sketch.md

@@ -1,5 +1,5 @@
 ---
-description: "Plan sub-stage: Produce a rough directional plan based on investigation findings."
+description: "Plan step: Produce a rough directional plan based on investigation findings."
 ---
 
 # Sketch

package/skills/wk-plan/{stages → steps}/ux-flow.md

@@ -1,5 +1,5 @@
 ---
-description: "Plan sub-stage: Define user-facing flows, screens, interactions, edge cases."
+description: "Plan step: Define user-facing flows, screens, interactions, edge cases."
 ---
 
 # UX Flow

package/skills/wk-review/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: review
-description: "Run the Review phase — 5 sub-stages: Self-Review, Security, Performance, Compliance, Handoff."
+description: "Run the Review phase — 5 steps: Self-Review, Security, Performance, Compliance, Handoff."
 user-invocable: false
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Agent
 ---
 
 You are the **Senior Reviewer**. Perform multi-dimensional code review before the feature ships.
 
-## Sub-stages (in order)
+## Steps (in order)
 
 1. **Self-Review** — Check your own diff for obvious issues
 2. **Security** — OWASP top 10 security review
@@ -17,11 +17,11 @@ You are the **Senior Reviewer**. Perform multi-dimensional code review before th
 
 ## Execution
 
-For each sub-stage:
-1. Read the sub-stage file (e.g., `.claude/skills/wk-review/stages/self-review.md`)
+For each step:
+1. Read the step file (e.g., `.claude/skills/wk-review/steps/self-review.md`)
 2. Follow its instructions — fix issues directly when possible
 3. Update `.work-kit/state.md` with findings
-4. Proceed to next sub-stage
+4. Proceed to next step
 
 ## Key Principle
 
@@ -29,10 +29,11 @@ For each sub-stage:
 
 ## Recording
 
-Throughout every sub-stage, update the shared state.md sections:
+Throughout every step, update the shared state.md sections:
 
 - **`## Decisions`** — If you make judgment calls during review (e.g., "accepted this deviation because..."), record them.
-- **`## Deviations`** — Compliance sub-stage will audit these. If you fix a deviation during review, note that it was resolved.
+- **`## Deviations`** — Compliance step will audit these. If you fix a deviation during review, note that it was resolved.
+- **`## Observations`** — Whenever you spot a fragile area, a missing convention, or feedback about the review phase itself, append: `- [lesson|convention|risk|workflow] text` (workflow tag may include `:phase/step`). At `wrap-up/knowledge` these are routed to `.work-kit-knowledge/` so future sessions benefit.
 
 Review findings feed directly into the Handoff decision and the final work-kit log.
 
@@ -58,9 +59,9 @@ Agent: Compliance   ──┘
 Each sub-agent receives:
 - The git diff (`git diff main...HEAD`)
 - The relevant Context Input sections
-- Its sub-stage skill file instructions
+- Its step skill file instructions
 
-Each writes its own `### Review: <sub-stage>` section to state.md.
+Each writes its own `### Review: <step>` section to state.md.
 
 **Handoff agent** reads all 4 review sections + Test: Final → makes the ship decision.
 
@@ -83,7 +84,7 @@ Each writes its own `### Review: <sub-stage>` section to state.md.
 - Approve without checking acceptance criteria status
 - Rubber-stamp without reading the diff ("looks good" is not a review)
 - Make changes_requested without specifying exactly what needs to change
-- Skip any of the 4 parallel review sub-stages
+- Skip any of the 4 parallel review steps
 
 ## Final Output
 

package/skills/wk-review/{stages → steps}/compliance.md

@@ -1,5 +1,5 @@
 ---
-description: "Review sub-stage: Compare final code against Blueprint."
+description: "Review step: Compare final code against Blueprint."
 ---
 
 # Compliance Review

package/skills/wk-review/{stages → steps}/handoff.md

@@ -1,5 +1,5 @@
 ---
-description: "Review sub-stage: Finalize PR, make ship/no-ship decision."
+description: "Review step: Finalize PR, make ship/no-ship decision."
 ---
 
 # Handoff
@@ -14,7 +14,7 @@ description: "Review sub-stage: Finalize PR, make ship/no-ship decision."
    - How to test it
    - Screenshots if applicable
    - Any concerns or known limitations
-2. Review all findings from prior review sub-stages
+2. Review all findings from prior review steps
 3. Check acceptance criteria status from Test/Validate
 4. Make the decision: **approved**, **changes_requested**, or **rejected**
 

package/skills/wk-review/{stages → steps}/performance.md

@@ -1,5 +1,5 @@
 ---
-description: "Review sub-stage: Check for performance issues."
+description: "Review step: Check for performance issues."
 ---
 
 # Performance Review

package/skills/wk-review/{stages → steps}/security.md

@@ -1,5 +1,5 @@
 ---
-description: "Review sub-stage: OWASP top 10 security review."
+description: "Review step: OWASP top 10 security review."
 ---
 
 # Security Review

package/skills/wk-review/{stages → steps}/self-review.md

@@ -1,5 +1,5 @@
 ---
-description: "Review sub-stage: Review your own diff for obvious issues."
+description: "Review step: Review your own diff for obvious issues."
 ---
 
 # Self-Review