work-kit-cli 0.2.8 → 0.3.0

package/cli/src/utils/json.ts

@@ -0,0 +1,20 @@
+import * as fs from "node:fs";
+
+/**
+ * Read and parse a JSON file. Returns null when the file is missing,
+ * unreadable, or contains invalid JSON. Use only when null is a meaningful
+ * "no config" answer; use direct fs/JSON for hard-required files.
+ */
+export function readJsonFile<T>(filePath: string): T | null {
+  let raw: string;
+  try {
+    raw = fs.readFileSync(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    return null;
+  }
+}

package/cli/src/utils/time.ts

@@ -0,0 +1,27 @@
+/** Difference in ms between two ISO timestamps; 0 on missing/invalid input. */
+export function durationMs(start?: string, end?: string): number {
+  if (!start || !end) return 0;
+  const a = new Date(start).getTime();
+  const b = new Date(end).getTime();
+  if (isNaN(a) || isNaN(b)) return 0;
+  return Math.max(0, b - a);
+}
+
+/** Human-readable duration: "12s", "5m", "2h30m", or "—" for non-positive. */
+export function formatDurationMs(ms: number): string {
+  if (ms <= 0) return "—";
+  const sec = Math.round(ms / 1000);
+  if (sec < 60) return `${sec}s`;
+  const min = Math.round(sec / 60);
+  if (min < 60) return `${min}m`;
+  const hr = Math.floor(min / 60);
+  const rem = min % 60;
+  return rem > 0 ? `${hr}h${rem}m` : `${hr}h`;
+}
+
+/** Elapsed since `start` formatted with `formatDurationMs`. Returns "" on bad input. */
+export function formatDurationSince(start: string): string {
+  const startMs = new Date(start).getTime();
+  if (isNaN(startMs)) return "";
+  return formatDurationMs(Date.now() - startMs);
+}

package/cli/src/{engine → workflow}/loopbacks.test.ts

@@ -6,7 +6,7 @@ describe("checkLoopback", () => {
   it("plan/audit with 'revise' loops back to plan/blueprint", () => {
     const result = checkLoopback("plan", "audit", "revise");
     assert.notEqual(result, null);
-    assert.deepStrictEqual(result!.to, { phase: "plan", subStage: "blueprint" });
+    assert.deepStrictEqual(result!.to, { phase: "plan", step: "blueprint" });
     assert.ok(result!.reason.length > 0);
   });
 
@@ -18,7 +18,7 @@ describe("checkLoopback", () => {
   it("review/handoff with 'changes_requested' loops back to build/core", () => {
     const result = checkLoopback("review", "handoff", "changes_requested");
     assert.notEqual(result, null);
-    assert.deepStrictEqual(result!.to, { phase: "build", subStage: "core" });
+    assert.deepStrictEqual(result!.to, { phase: "build", step: "core" });
   });
 
   it("build/core with 'done' returns null", () => {

package/cli/src/workflow/loopbacks.ts

@@ -0,0 +1,42 @@
+import { PhaseName, Location, LoopbackRecord, StepOutcome } from "../state/schema.js";
+import { LOOPBACK_ROUTES } from "../config/loopback-routes.js";
+
+interface LoopbackResult {
+  to: Location;
+  reason: string;
+}
+
+/**
+ * Count how many times a specific loopback route has been taken.
+ */
+export function countLoopbacksForRoute(loopbacks: LoopbackRecord[], from: Location, to: Location): number {
+  return loopbacks.filter(
+    (lb) => lb.from.phase === from.phase && lb.from.step === from.step
+      && lb.to.phase === to.phase && lb.to.step === to.step
+  ).length;
+}
+
+/**
+ * Check if completing a step with a given outcome should trigger a loop-back.
+ */
+export function checkLoopback(
+  phase: PhaseName,
+  step: string,
+  outcome?: StepOutcome
+): LoopbackResult | null {
+  if (!outcome) return null;
+
+  const route = LOOPBACK_ROUTES.find(
+    (r) =>
+      r.from.phase === phase &&
+      r.from.step === step &&
+      r.triggerOutcome === outcome
+  );
+
+  if (!route) return null;
+
+  return {
+    to: route.to,
+    reason: route.reason,
+  };
+}

package/cli/src/workflow/parallel.ts

@@ -0,0 +1,64 @@
+import type { PhaseName, WorkKitState } from "../state/schema.js";
+import { loadProjectConfig } from "../config/project-config.js";
+
+/**
+ * Defines which steps run in parallel and which runs sequentially after.
+ */
+export interface ParallelGroup {
+  parallel: string[];          // steps that run concurrently
+  thenSequential?: string;     // step that runs after all parallel complete
+}
+
+/**
+ * Default parallel groups per phase. Most projects should not need to override
+ * these — the defaults reflect the canonical work-kit pipeline.
+ */
+export const DEFAULT_PARALLEL_GROUPS: Record<string, ParallelGroup> = {
+  test: {
+    parallel: ["verify", "e2e"],
+    thenSequential: "validate",
+  },
+  review: {
+    parallel: ["self-review", "security", "performance", "compliance"],
+    thenSequential: "handoff",
+  },
+};
+
+/**
+ * Resolve parallel groups for a project, merging defaults with optional
+ * project config overrides at `<mainRepoRoot>/.work-kit-config.json`.
+ */
+export function resolveParallelGroups(mainRepoRoot?: string): Record<string, ParallelGroup> {
+  if (!mainRepoRoot) return DEFAULT_PARALLEL_GROUPS;
+  const config = loadProjectConfig(mainRepoRoot);
+  if (!config.parallel || Object.keys(config.parallel).length === 0) {
+    return DEFAULT_PARALLEL_GROUPS;
+  }
+  return { ...DEFAULT_PARALLEL_GROUPS, ...config.parallel };
+}
+
+/**
+ * Check if a step triggers a parallel group.
+ * Triggers on the first non-skipped, non-completed parallel member.
+ */
+export function getParallelGroup(phase: PhaseName, step: string, state?: WorkKitState): ParallelGroup | null {
+  const groups = resolveParallelGroups(state?.metadata?.mainRepoRoot);
+  const group = groups[phase];
+  if (!group) return null;
+
+  if (!group.parallel.includes(step)) return null;
+
+  if (state) {
+    const phaseState = state.phases[phase];
+    const firstActive = group.parallel.find((s) => {
+      const sState = phaseState?.steps[s];
+      return sState && sState.status !== "skipped" && sState.status !== "completed";
+    });
+    if (firstActive !== step) return null;
+  } else {
+    if (group.parallel[0] !== step) return null;
+  }
+
+  return group;
+}
+

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.3.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

@@ -6,7 +6,7 @@ argument-hint: "[--gated] [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           |
@@ -95,34 +95,34 @@ The table is a guide, not a rigid rule. Adjust based on the actual request:
    ```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>
    ```
    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`
+2. Show the workflow to the user: `work-kit workflow`
+3. User can adjust: `work-kit workflow --add review/security` or `work-kit workflow --remove test/e2e`
 4. **Wait for approval** — user can add/remove steps before proceeding
 5. 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 +177,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. 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. Wait for all to complete. Then spawn `thenSequential` if provided. 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