work-kit-cli 0.2.8 → 0.4.0

package/cli/src/workflow/transitions.test.ts

@@ -0,0 +1,129 @@
+import { describe, it } from "node:test";
+import * as assert from "node:assert/strict";
+import { nextStepInPhase, isPhaseComplete, determineNextStep } from "./transitions.js";
+import type { WorkKitState, PhaseName, PhaseState, StepState } from "../state/schema.js";
+import { PHASE_NAMES, STEPS_BY_PHASE } from "../state/schema.js";
+
+function makeState(): WorkKitState {
+  const phases = {} as Record<PhaseName, PhaseState>;
+  for (const phase of PHASE_NAMES) {
+    const steps: Record<string, StepState> = {};
+    for (const s of STEPS_BY_PHASE[phase]) {
+      steps[s] = { status: "pending" };
+    }
+    phases[phase] = { status: "pending", steps };
+  }
+  return {
+    version: 2,
+    slug: "test",
+    branch: "feature/test",
+    started: "2026-01-01",
+    mode: "full-kit",
+    status: "in-progress",
+    currentPhase: "plan",
+    currentStep: "clarify",
+    phases,
+    loopbacks: [],
+    metadata: { worktreeRoot: "/tmp/test", mainRepoRoot: "/tmp/test" },
+  };
+}
+
+describe("nextStepInPhase", () => {
+  it("returns first pending step", () => {
+    const state = makeState();
+    const result = nextStepInPhase(state, "plan");
+    assert.equal(result, "clarify");
+  });
+
+  it("returns null when all complete or skipped", () => {
+    const state = makeState();
+    for (const s of Object.values(state.phases.plan.steps)) {
+      s.status = "completed";
+    }
+    const result = nextStepInPhase(state, "plan");
+    assert.equal(result, null);
+  });
+
+  it("skips completed steps and returns next pending", () => {
+    const state = makeState();
+    state.phases.plan.steps.clarify.status = "completed";
+    state.phases.plan.steps.investigate.status = "completed";
+    const result = nextStepInPhase(state, "plan");
+    assert.equal(result, "sketch");
+  });
+});
+
+describe("isPhaseComplete", () => {
+  it("returns true when all complete or skipped", () => {
+    const state = makeState();
+    for (const s of Object.values(state.phases.plan.steps)) {
+      s.status = "completed";
+    }
+    assert.equal(isPhaseComplete(state, "plan"), true);
+  });
+
+  it("returns true with mix of completed and skipped", () => {
+    const state = makeState();
+    let first = true;
+    for (const s of Object.values(state.phases.plan.steps)) {
+      s.status = first ? "skipped" : "completed";
+      first = false;
+    }
+    assert.equal(isPhaseComplete(state, "plan"), true);
+  });
+
+  it("returns false when some steps are pending", () => {
+    const state = makeState();
+    assert.equal(isPhaseComplete(state, "plan"), false);
+  });
+});
+
+describe("determineNextStep", () => {
+  it("returns complete when state is completed", () => {
+    const state = makeState();
+    state.status = "completed";
+    const result = determineNextStep(state);
+    assert.equal(result.type, "complete");
+  });
+
+  it("returns phase-boundary when no current phase", () => {
+    const state = makeState();
+    state.currentPhase = null;
+    const result = determineNextStep(state);
+    assert.equal(result.type, "phase-boundary");
+    assert.equal(result.phase, "plan");
+  });
+
+  it("returns step for current phase with pending work", () => {
+    const state = makeState();
+    state.currentPhase = "plan";
+    state.phases.plan.status = "in-progress";
+    const result = determineNextStep(state);
+    assert.equal(result.type, "step");
+    assert.equal(result.phase, "plan");
+    assert.equal(result.step, "clarify");
+  });
+
+  it("auto-proceeds to next phase by default when current phase is complete", () => {
+    const state = makeState();
+    state.currentPhase = "plan";
+    for (const s of Object.values(state.phases.plan.steps)) {
+      s.status = "completed";
+    }
+    const result = determineNextStep(state);
+    assert.equal(result.type, "phase-boundary");
+    assert.equal(result.phase, "build");
+  });
+
+  it("returns wait-for-user when gated and current phase is complete", () => {
+    const state = makeState();
+    state.gated = true;
+    state.currentPhase = "plan";
+    for (const s of Object.values(state.phases.plan.steps)) {
+      s.status = "completed";
+    }
+    const result = determineNextStep(state);
+    assert.equal(result.type, "wait-for-user");
+    assert.equal(result.phase, "build");
+  });
+});

package/cli/src/{engine → workflow}/transitions.ts

@@ -1,36 +1,36 @@
-import { WorkKitState, PhaseName, SUBSTAGES_BY_PHASE } from "../state/schema.js";
-import { PHASE_ORDER } from "../config/phases.js";
+import { WorkKitState, PhaseName, STEPS_BY_PHASE } from "../state/schema.js";
+import { PHASE_ORDER } from "../config/workflow.js";
 
 export interface NextStep {
-  type: "sub-stage" | "phase-boundary" | "complete" | "wait-for-user";
+  type: "step" | "phase-boundary" | "complete" | "wait-for-user";
   phase?: PhaseName;
-  subStage?: string;
+  step?: string;
   message?: string;
 }
 
 /**
- * Find the next pending sub-stage within a phase.
+ * Find the next pending step within a phase.
  */
-export function nextSubStageInPhase(state: WorkKitState, phase: PhaseName): string | null {
+export function nextStepInPhase(state: WorkKitState, phase: PhaseName): string | null {
   const phaseState = state.phases[phase];
-  const subStages = SUBSTAGES_BY_PHASE[phase];
+  const steps = STEPS_BY_PHASE[phase];
 
-  for (const ss of subStages) {
-    const ssState = phaseState.subStages[ss];
-    if (ssState && (ssState.status === "pending" || ssState.status === "in-progress" || ssState.status === "waiting")) {
-      return ss;
+  for (const step of steps) {
+    const stepState = phaseState.steps[step];
+    if (stepState && (stepState.status === "pending" || stepState.status === "in-progress" || stepState.status === "waiting")) {
+      return step;
     }
   }
   return null;
 }
 
 /**
- * Check if all non-skipped sub-stages in a phase are completed.
+ * Check if all non-skipped steps in a phase are completed.
  */
 export function isPhaseComplete(state: WorkKitState, phase: PhaseName): boolean {
   const phaseState = state.phases[phase];
-  return Object.values(phaseState.subStages).every(
-    (ss) => ss.status === "completed" || ss.status === "skipped"
+  return Object.values(phaseState.steps).every(
+    (s) => s.status === "completed" || s.status === "skipped"
   );
 }
 
@@ -58,7 +58,6 @@ export function determineNextStep(state: WorkKitState): NextStep {
   const currentPhase = state.currentPhase;
 
   if (!currentPhase) {
-    // Find the next phase
     const next = nextPhase(state);
     if (!next) {
       return { type: "complete", message: "All phases complete" };
@@ -68,7 +67,6 @@ export function determineNextStep(state: WorkKitState): NextStep {
 
   // Check if current phase is complete
   if (isPhaseComplete(state, currentPhase)) {
-    // Find next phase
     const phaseIndex = PHASE_ORDER.indexOf(currentPhase);
     const remainingPhases = PHASE_ORDER.slice(phaseIndex + 1);
 
@@ -76,14 +74,12 @@ export function determineNextStep(state: WorkKitState): NextStep {
       const ps = state.phases[phase];
       if (ps.status !== "skipped") {
         if (state.gated) {
-          // Gated mode — wait for user confirmation before crossing
           return {
             type: "wait-for-user",
             phase,
             message: `${currentPhase} phase complete. Ready to start ${phase}. Proceed?`,
           };
         }
-        // Default — auto-proceed to next phase
         return { type: "phase-boundary", phase, message: `${currentPhase} complete → starting ${phase}` };
       }
     }
@@ -91,10 +87,10 @@ export function determineNextStep(state: WorkKitState): NextStep {
     return { type: "complete", message: "All phases complete" };
   }
 
-  // Find next sub-stage within current phase
-  const nextSS = nextSubStageInPhase(state, currentPhase);
-  if (nextSS) {
-    return { type: "sub-stage", phase: currentPhase, subStage: nextSS };
+  // Find next step within current phase
+  const next = nextStepInPhase(state, currentPhase);
+  if (next) {
+    return { type: "step", phase: currentPhase, step: next };
   }
 
   return { type: "complete", message: `${currentPhase} phase complete` };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "work-kit-cli",
-  "version": "0.2.8",
-  "description": "Structured development workflow for Claude Code. Two modes, 6 phases, 27 sub-stages.",
+  "version": "0.4.0",
+  "description": "Structured development workflow for Claude Code. Two modes, 6 phases, 27 steps.",
   "type": "module",
   "bin": {
     "work-kit": "cli/bin/work-kit.mjs",

package/skills/auto-kit/SKILL.md

@@ -2,11 +2,11 @@
 name: auto-kit
 description: "Smart pipeline that analyzes the request and builds a dynamic workflow. Usage: /auto-kit <description> to start, /auto-kit to continue."
 user-invocable: true
-argument-hint: "[--gated] [description]"
+argument-hint: "[--gated] [--opus|--sonnet|--haiku|--inherit] [description]"
 allowed-tools: Agent, Bash, Read, Write, Edit, Glob, Grep
 ---
 
-You are the **Work Orchestrator (Auto Mode)**. You analyze the request first, then build a tailored workflow with only the phases and sub-stages that are actually needed.
+You are the **Work Orchestrator (Auto Mode)**. You analyze the request first, then build a tailored workflow with only the phases and steps that are actually needed.
 
 Best for: bug fixes, small changes, refactors, or well-understood tasks.
 
@@ -14,7 +14,7 @@ Best for: bug fixes, small changes, refactors, or well-understood tasks.
 
 Before starting, verify the CLI is installed:
 ```bash
-npx work-kit-cli doctor
+work-kit doctor
 ```
 
 If `work-kit` is not found, ask the user to install it:
@@ -22,7 +22,7 @@ If `work-kit` is not found, ask the user to install it:
 
 Do not proceed until `doctor` reports all checks passed.
 
-## All Available Sub-stages
+## All Available Steps
 
 These are the building blocks you pick from:
 
@@ -47,13 +47,13 @@ Before creating the worktree, perform a quick analysis:
    - **feature** — new capability (small to medium scope)
    - **large-feature** — new capability (large scope, multiple systems)
 3. **Scan the codebase** — quick look at affected areas (not a full investigation)
-4. **Build the workflow** — select only the sub-stages needed
+4. **Build the workflow** — select only the steps needed
 
 ### Step 2: Build Dynamic Workflow
 
-Based on the classification, select sub-stages. Use this table as a starting point, then adjust based on the specific request:
+Based on the classification, select steps. Use this table as a starting point, then adjust based on the specific request:
 
-| Sub-stage              | bug-fix | small-change | refactor | feature | large-feature |
+| Step              | bug-fix | small-change | refactor | feature | large-feature |
 |------------------------|---------|--------------|----------|---------|---------------|
 | **Plan: Clarify**      | YES     | YES          | YES      | YES     | YES           |
 | **Plan: Investigate**  | YES     | skip         | YES      | YES     | YES           |
@@ -91,38 +91,55 @@ The table is a guide, not a rigid rule. Adjust based on the actual request:
 
 ### Step 3: Initialize
 
-1. Create a git worktree and initialize state with the CLI:
+1. Parse flags out of the user's input before building the init command:
+   - `--gated` → append `--gated`
+   - `--opus` → append `--model-policy opus`
+   - `--sonnet` → append `--model-policy sonnet`
+   - `--haiku` → append `--model-policy haiku`
+   - `--inherit` → append `--model-policy inherit` (no model override; lets Claude Code's default pick)
+   - No model flag → omit `--model-policy` (defaults to `auto` = work-kit step-level routing)
+
+   Strip recognized flags from the description text. Only one model flag at a time — if the user passes more than one, report the conflict and stop.
+
+2. Create a git worktree and initialize state with the CLI:
    ```bash
    git worktree add worktrees/<slug> -b feature/<slug>
    cd worktrees/<slug>
-   npx work-kit-cli init --mode auto --description "<description>" --classification <classification>
+   work-kit init --mode auto --description "<description>" --classification <classification> [--gated] [--model-policy <value>]
+   ```
+
+   Examples:
+   ```
+   /auto-kit fix login bug             → work-kit init --mode auto --description "fix login bug" --classification bug-fix
+   /auto-kit --inherit fix the typo    → work-kit init --mode auto --description "fix the typo" --classification small-change --model-policy inherit
+   /auto-kit --haiku tweak copy        → work-kit init --mode auto --description "tweak copy" --classification small-change --model-policy haiku
    ```
-   If the user passed `--gated` (e.g., `/auto-kit --gated fix login bug`), add `--gated` to the init command. Strip `--gated` from the description text.
-2. Show the workflow to the user: `npx work-kit-cli workflow`
-3. User can adjust: `npx work-kit-cli workflow --add review/security` or `npx work-kit-cli workflow --remove test/e2e`
-4. **Wait for approval** — user can add/remove steps before proceeding
-5. Once approved, start the execution loop
+
+3. Show the workflow to the user: `work-kit workflow` (output now includes the resolved model per step and the active policy; review it before approving)
+4. User can adjust: `work-kit workflow --add review/security` or `work-kit workflow --remove test/e2e`
+5. **Wait for approval** — user can add/remove steps before proceeding
+6. Once approved, start the execution loop
 
 ## Continuing Work (`/auto-kit` with no args)
 
-1. Run `npx work-kit-cli bootstrap` to detect session state
+1. Run `work-kit bootstrap` to detect session state
 2. Parse the JSON response:
    - If `active: false` — no session found, ask the user for a description and start new work
    - If `recovery` is set — report the recovery suggestion to the user before continuing
-   - If `active: true` — report current state (slug, phase, sub-stage) to the user
+   - If `active: true` — report current state (slug, phase, step) to the user
 3. `cd` into the worktree directory
-4. Run `npx work-kit-cli next` to get the next action
+4. Run `work-kit next` to get the next action
 5. Follow the execution loop below
 
 ## Step Validation
 
 All validation is handled by the CLI. The `next` command enforces order, phase boundaries, and prerequisites automatically.
 
-To add/remove steps mid-work: `npx work-kit-cli workflow --add <phase/sub-stage>` or `--remove <phase/sub-stage>`. Completed steps cannot be removed.
+To add/remove steps mid-work: `work-kit workflow --add <phase/step>` or `--remove <phase/step>`. Completed steps cannot be removed.
 
 ## Agent Architecture
 
-Same as full-kit: each phase runs as a **fresh agent** to keep context focused. The difference is that each agent only runs the sub-stages in the `## Workflow` checklist.
+Same as full-kit: each phase runs as a **fresh agent** to keep context focused. The difference is that each agent only runs the steps in the `## Workflow` checklist.
 
 ```
 Orchestrator (main agent — you)
@@ -177,23 +194,23 @@ Orchestrator (main agent — you)
 
 Each phase writes a `### <Phase>: Final` section — a self-contained summary. The next agent reads **only** the Final sections it needs.
 
-If a phase has fewer sub-stages in the workflow, the Final section still covers the same output — just with less detail where sub-stages were skipped.
+If a phase has fewer steps in the workflow, the Final section still covers the same output — just with less detail where steps were skipped.
 
 ## Execution Loop
 
 The CLI manages all state transitions, prerequisites, and loopbacks. Follow this loop:
 
-1. Run `npx work-kit-cli next` to get the next action
+1. Run `work-kit next` to get the next action
 2. Parse the JSON response
 3. Follow the action type:
-   - **`spawn_agent`**: Use the Agent tool with the provided `agentPrompt`. Pass `skillFile` path for reference. After the agent completes: `npx work-kit-cli complete <phase>/<sub-stage> --outcome <outcome>`
-   - **`spawn_parallel_agents`**: Spawn all agents in the `agents` array in parallel using the Agent tool. Wait for all to complete. Then spawn `thenSequential` if provided. After all complete: `npx work-kit-cli complete <onComplete target>`
-   - **`wait_for_user`**: Report the message to the user and stop. Wait for them to say "proceed" before running `npx work-kit-cli next` again.
-   - **`loopback`**: Report the loopback to the user, then run `npx work-kit-cli next` to continue from the target.
+   - **`spawn_agent`**: Use the Agent tool with the provided `agentPrompt`. Pass `skillFile` path for reference. **If the action includes a `model` field, pass it as the Agent tool's `model` parameter; if the field is absent, do not set `model` (let Claude Code's default pick).** After the agent completes: `work-kit complete <phase>/<step> --outcome <outcome>`
+   - **`spawn_parallel_agents`**: Spawn all agents in the `agents` array in parallel using the Agent tool. **For each agent, pass its `model` field as the Agent tool's `model` parameter when present; omit when absent.** Wait for all to complete. Then spawn `thenSequential` if provided (same rule for its `model` field). After all complete: `work-kit complete <onComplete target>`
+   - **`wait_for_user`**: Report the message to the user and stop. Wait for them to say "proceed" before running `work-kit next` again.
+   - **`loopback`**: Report the loopback to the user, then run `work-kit next` to continue from the target.
    - **`complete`**: Done — run wrap-up if not already done.
    - **`error`**: Report the error and suggestion to the user. Stop.
-4. After each agent completes: `npx work-kit-cli complete <phase>/<sub-stage> --outcome <outcome>`
-5. Then `npx work-kit-cli next` again to continue
+4. After each agent completes: `work-kit complete <phase>/<step> --outcome <outcome>`
+5. Then `work-kit next` again to continue
 
 ## Loop-Back Rules
 

package/skills/cancel-kit/SKILL.md

@@ -13,7 +13,7 @@ Cancels the active work-kit session and cleans up all artifacts.
 
 1. Finds the active work-kit session (via `bootstrap`)
 2. Confirms with the user before proceeding
-3. Runs `npx work-kit-cli cancel` to:
+3. Runs `work-kit cancel` to:
    - Remove `.work-kit/` state directory
    - Remove the git worktree
    - Delete the feature branch
@@ -21,14 +21,14 @@ Cancels the active work-kit session and cleans up all artifacts.
 
 ## Instructions
 
-1. Run `npx work-kit-cli bootstrap` to detect the active session
+1. Run `work-kit bootstrap` to detect the active session
 2. If no active session: tell the user there's nothing to cancel
 3. If active: show the user what will be cancelled:
    - Slug and branch name
-   - Current phase and sub-stage
+   - Current phase and step
    - Any uncommitted work in the worktree will be lost
 4. **Ask the user to confirm** — do not proceed without explicit confirmation
 5. `cd` into the worktree directory
-6. Run `npx work-kit-cli cancel`
+6. Run `work-kit cancel`
 7. `cd` back to the main repo root
 8. Report the result to the user

package/skills/full-kit/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: full-kit
-description: "Full pipeline for feature development. Runs all phases and sub-stages in order. Usage: /full-kit <description> to start, /full-kit to continue."
+description: "Full pipeline for feature development. Runs all phases and steps in order. Usage: /full-kit <description> to start, /full-kit to continue."
 user-invocable: true
-argument-hint: "[--gated] [description]"
+argument-hint: "[--gated] [--opus|--sonnet|--haiku|--inherit] [description]"
 allowed-tools: Agent, Bash, Read, Write, Edit, Glob, Grep
 ---
 
-You are the **Work Orchestrator (Full Mode)**. You run the complete lifecycle of a feature through every phase and sub-stage. No shortcuts.
+You are the **Work Orchestrator (Full Mode)**. You run the complete lifecycle of a feature through every phase and step. No shortcuts.
 
 Best for: large features, new systems, or when you want maximum rigor.
 
@@ -14,7 +14,7 @@ Best for: large features, new systems, or when you want maximum rigor.
 
 Before starting, verify the CLI is installed:
 ```bash
-npx work-kit-cli doctor
+work-kit doctor
 ```
 
 If `work-kit` is not found, ask the user to install it:
@@ -33,46 +33,63 @@ Do not proceed until `doctor` reports all checks passed.
 
 ## Starting New Work (`/full-kit <description>`)
 
-1. Create a git worktree and initialize state:
+1. Parse flags out of the user's input before building the init command:
+   - `--gated` → append `--gated` to init
+   - `--opus` → append `--model-policy opus`
+   - `--sonnet` → append `--model-policy sonnet`
+   - `--haiku` → append `--model-policy haiku`
+   - `--inherit` → append `--model-policy inherit` (no model override; lets Claude Code's default pick)
+   - No model flag → omit `--model-policy` (defaults to `auto` = work-kit step-level routing)
+
+   Strip any recognized flags from the description text before passing it through. Only one model flag may be set at a time — if the user passes more than one, report the conflict and stop.
+
+2. Create a git worktree and initialize state:
    ```bash
    git worktree add worktrees/<slug> -b feature/<slug>
    cd worktrees/<slug>
-   npx work-kit-cli init --mode full --description "<description>"
+   work-kit init --mode full --description "<description>" [--gated] [--model-policy <value>]
+   ```
+
+   Examples:
+   ```
+   /full-kit add user avatar              → work-kit init --mode full --description "add user avatar"
+   /full-kit --opus add user avatar       → work-kit init --mode full --description "add user avatar" --model-policy opus
+   /full-kit --gated --inherit fix login  → work-kit init --mode full --description "fix login" --gated --model-policy inherit
    ```
-   If the user passed `--gated` (e.g., `/full-kit --gated add user avatar`), add `--gated` to the init command. Strip `--gated` from the description text.
-2. Parse the JSON response and follow the action
-3. Continue with the execution loop below
+
+3. Parse the JSON response and follow the action
+4. Continue with the execution loop below
 
 ## Continuing Work (`/full-kit` with no args)
 
-1. Run `npx work-kit-cli bootstrap` to detect session state
+1. Run `work-kit bootstrap` to detect session state
 2. Parse the JSON response:
    - If `active: false` — no session found, ask the user for a description and start new work
    - If `recovery` is set — report the recovery suggestion to the user before continuing
-   - If `active: true` — report current state (slug, phase, sub-stage) to the user
+   - If `active: true` — report current state (slug, phase, step) to the user
 3. `cd` into the worktree directory
-4. Run `npx work-kit-cli next` to get the next action
+4. Run `work-kit next` to get the next action
 5. Follow the execution loop below
 
 ## Execution Loop
 
 The CLI manages all state transitions, prerequisites, and loopbacks. Follow this loop:
 
-1. Run `npx work-kit-cli next` to get the next action
+1. Run `work-kit next` to get the next action
 2. Parse the JSON response
 3. Follow the action type:
-   - **`spawn_agent`**: Use the Agent tool with the provided `agentPrompt`. Pass `skillFile` path for reference. After the agent completes: `npx work-kit-cli complete <phase>/<sub-stage> --outcome <outcome>`
-   - **`spawn_parallel_agents`**: Spawn all agents in the `agents` array in parallel using the Agent tool. Wait for all to complete. Then spawn `thenSequential` if provided. After all complete: `npx work-kit-cli complete <onComplete target>`
-   - **`wait_for_user`**: Report the message to the user and stop. Wait for them to say "proceed" before running `npx work-kit-cli next` again. (Only appears in `--gated` mode.)
-   - **`loopback`**: Report the loopback to the user, then run `npx work-kit-cli next` to continue from the target.
+   - **`spawn_agent`**: Use the Agent tool with the provided `agentPrompt`. Pass `skillFile` path for reference. **If the action includes a `model` field, pass it as the Agent tool's `model` parameter; if the field is absent, do not set `model` (let Claude Code's default pick).** After the agent completes: `work-kit complete <phase>/<step> --outcome <outcome>`
+   - **`spawn_parallel_agents`**: Spawn all agents in the `agents` array in parallel using the Agent tool. **For each agent, pass its `model` field as the Agent tool's `model` parameter when present; omit when absent.** Wait for all to complete. Then spawn `thenSequential` if provided (same rule for its `model` field). After all complete: `work-kit complete <onComplete target>`
+   - **`wait_for_user`**: Report the message to the user and stop. Wait for them to say "proceed" before running `work-kit next` again. (Only appears in `--gated` mode.)
+   - **`loopback`**: Report the loopback to the user, then run `work-kit next` to continue from the target.
    - **`complete`**: Done — run wrap-up if not already done.
    - **`error`**: Report the error and suggestion to the user. Stop.
-4. After each agent completes: `npx work-kit-cli complete <phase>/<sub-stage> --outcome <outcome>`
-5. Then `npx work-kit-cli next` again to continue
+4. After each agent completes: `work-kit complete <phase>/<step> --outcome <outcome>`
+5. Then `work-kit next` again to continue
 
 ## Phase Prerequisites
 
-Prerequisites are enforced by the CLI (`npx work-kit-cli validate <phase>`). You don't need to check manually — the `next` command handles it.
+Prerequisites are enforced by the CLI (`work-kit validate <phase>`). You don't need to check manually — the `next` command handles it.
 
 | Phase    | Requires                          |
 |----------|-----------------------------------|
@@ -90,12 +107,12 @@ Each phase runs as a **fresh agent** (sub-agent spawned by the orchestrator). Th
 ```
 Orchestrator (main agent — you)
 │
-├── Agent: Plan (single agent, all 8 sub-stages)
+├── Agent: Plan (single agent, all 8 steps)
 │   ├── reads: ## Description, ## Criteria, codebase
 │   ├── runs: Clarify → Investigate → ... → Audit
 │   └── writes: ### Plan: Final (Blueprint, Architecture, Scope, Constraints)
 │
-├── Agent: Build (single agent, all 8 sub-stages)
+├── Agent: Build (single agent, all 8 steps)
 │   ├── reads: ### Plan: Final, ## Criteria
 │   ├── runs: Setup → Migration → ... → Commit
 │   └── writes: ### Build: Final (PR, files changed, test status, deviations)
@@ -116,7 +133,7 @@ Orchestrator (main agent — you)
 │   ├── then: Handoff (reads all 4 results → ship decision)
 │   └── writes: ### Review: Final (decision, issues, concerns)
 │
-├── Agent: Deploy (single agent, all 3 sub-stages)
+├── Agent: Deploy (single agent, all 3 steps)
 │   ├── reads: ### Review: Final, ### Build: Final
 │   ├── runs: Merge → Monitor → Remediate
 │   └── writes: ### Deploy: Final (merge/deploy status)
@@ -145,7 +162,7 @@ Orchestrator (main agent — you)
 
 ### Phase Handoff via Final Sections
 
-Each phase writes a `### <Phase>: Final` section — a self-contained summary of that phase's output. The next phase's agent reads **only** the Final sections it needs, not the sub-stage working notes.
+Each phase writes a `### <Phase>: Final` section — a self-contained summary of that phase's output. The next phase's agent reads **only** the Final sections it needs, not the step working notes.
 
 ```
 state.md grows like this:
@@ -168,14 +185,14 @@ state.md grows like this:
 For each phase:
 1. **Check prerequisites** — verify the required prior phase is marked complete in state.md
 2. **Spawn a fresh agent** for the phase — pass it the phase skill file and the relevant Final sections from state.md
-3. The agent reads each sub-stage file when directed (e.g., `.claude/skills/wk-plan/stages/clarify.md`)
-4. The agent updates `.work-kit/state.md` after each sub-stage completes
+3. The agent reads each step file when directed (e.g., `.claude/skills/wk-plan/steps/clarify.md`)
+4. The agent updates `.work-kit/state.md` after each step completes
 5. The agent writes the `### <Phase>: Final` section before exiting
 6. After the agent completes, summarize results to the user and wait for confirmation
 
 ## Loop-Back Rules
 
-Some sub-stages can route backwards based on their outcome:
+Some steps can route backwards based on their outcome:
 
 - **Plan Audit** → "revise" → re-run Blueprint
 - **Build Refactor** → "broken" → re-run Core
@@ -183,7 +200,7 @@ Some sub-stages can route backwards based on their outcome:
 - **Deploy Merge** → "fix_needed" → re-run Build (from Core)
 - **Deploy Remediate** → "fix_and_redeploy" → re-run Build (from Core)
 
-On loop-back: add a `## Loop-back context` section to state.md with what needs to change and why, then resume at the target sub-stage.
+On loop-back: add a `## Loop-back context` section to state.md with what needs to change and why, then resume at the target step.
 
 ## Completion
 

package/skills/pause-kit/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: pause-kit
+description: "Pause the active work-kit session. Use when stepping away mid-flight. Usage: /pause-kit [reason]"
+user-invocable: true
+argument-hint: "[reason]"
+allowed-tools: Bash, Read
+---
+
+You are pausing the active work-kit session so it can be resumed cleanly later.
+
+## Steps
+
+1. Run `work-kit bootstrap` to confirm a session is active. If no session is active, tell the user there is nothing to pause and stop.
+2. `cd` into the worktree path reported by bootstrap.
+3. Run:
+   ```bash
+   work-kit pause${ARGUMENTS:+ --reason "$ARGUMENTS"}
+   ```
+4. Parse the JSON response.
+5. Report the message to the user. Tell them they can run `/resume-kit` (or `work-kit resume`) when ready.
+
+## Notes
+
+- Pausing only flips state to `paused` and records `pausedAt` — no files are deleted, no git operations happen.
+- The orchestrator (`/full-kit`, `/auto-kit`) refuses to advance a paused session until it is resumed.