work-kit-cli 0.2.8 → 0.3.0

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,10 @@ 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.
 
 Review findings feed directly into the Handoff decision and the final work-kit log.
 
@@ -58,9 +58,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 +83,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

package/skills/wk-test/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: test
-description: "Run the Test phase — 3 sub-stages: Verify, E2E, Validate."
+description: "Run the Test phase — 3 steps: Verify, E2E, Validate."
 user-invocable: false
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Agent
 ---
 
 You are the **QA Lead**. Validate the implementation against the Blueprint and acceptance criteria.
 
-## Sub-stages (in order)
+## Steps (in order)
 
 1. **Verify** — Run existing test suite, check for regressions
 2. **E2E** — Test user flows end-to-end
@@ -15,11 +15,11 @@ You are the **QA Lead**. Validate the implementation against the Blueprint and a
 
 ## Execution
 
-For each sub-stage:
-1. Read the sub-stage file (e.g., `.claude/skills/wk-test/stages/verify.md`)
+For each step:
+1. Read the step file (e.g., `.claude/skills/wk-test/steps/verify.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
 
@@ -27,7 +27,7 @@ For each sub-stage:
 
 ## Recording
 
-Throughout every sub-stage, update the shared state.md sections:
+Throughout every step, update the shared state.md sections:
 
 - **`## Criteria`** — Check off criteria as they're verified. Add evidence inline: `- [x] <criterion> — verified by <test name / screenshot / manual check>`.
 - **`## Decisions`** — If you discover a criterion is untestable or needs reinterpretation, record the decision and why.
@@ -51,7 +51,7 @@ Agent: Verify  ──┐
 Agent: E2E    ──┘
 ```
 
-Each sub-agent reads the same Context Input sections and writes its own `### Test: <sub-stage>` section to state.md.
+Each sub-agent reads the same Context Input sections and writes its own `### Test: <step>` section to state.md.
 
 ## Boundaries
 
@@ -74,7 +74,7 @@ Each sub-agent reads the same Context Input sections and writes its own `### Tes
 
 ## Final Output
 
-After all sub-stages are done, append a `### Test: Final` section to state.md. This is what **Review agents read**.
+After all steps are done, append a `### Test: Final` section to state.md. This is what **Review agents read**.
 
 ```markdown
 ### Test: Final

package/skills/wk-test/{stages → steps}/e2e.md

@@ -1,5 +1,5 @@
 ---
-description: "Test sub-stage: Test user flows end-to-end."
+description: "Test step: Test user flows end-to-end."
 ---
 
 # E2E

package/skills/wk-test/{stages → steps}/validate.md

@@ -1,5 +1,5 @@
 ---
-description: "Test sub-stage: Verify every acceptance criterion is satisfied with evidence."
+description: "Test step: Verify every acceptance criterion is satisfied with evidence."
 ---
 
 # Validate

package/skills/wk-test/{stages → steps}/verify.md

@@ -1,5 +1,5 @@
 ---
-description: "Test sub-stage: Run existing test suite, check for regressions."
+description: "Test step: Run existing test suite, check for regressions."
 ---
 
 # Verify

package/skills/wk-wrap-up/SKILL.md

@@ -10,18 +10,19 @@ allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 **Role:** Work Historian
 **Goal:** Produce a concise, useful summary of what was built and why — then clean up.
 
-## Instructions
+This phase has **one step**: `wrap-up/summary`. See `.claude/skills/wk-wrap-up/steps/summary.md` for the canonical instructions. The summary you write goes into `.work-kit/summary.md`; the CLI archives it into `.work-kit-tracker/archive/<slug>-<date>/` when you call `work-kit complete wrap-up/summary --outcome done`.
 
-> **Note:** The CLI automatically archives `state.md`, `tracker.json`, and a placeholder `summary.md` into `.work-kit-tracker/archive/<slug>-<date>/` when the last sub-stage completes. It also appends a row to `.work-kit-tracker/index.md`. Your job is to **replace the placeholder summary.md** with a real distilled summary.
+## Instructions
 
 1. **Read the full `.work-kit/state.md`** — every phase output from Plan through the last completed phase
 2. **Synthesize the summary** — not a copy-paste of state, but a distilled record that a future developer (or agent) would find useful
-3. **Overwrite the summary file** at `.work-kit-tracker/archive/<slug>-<date>/summary.md` on the **main branch** (not the worktree)
-4. **Ask the user** if they want the worktree and branch removed
+3. **Write `.work-kit/summary.md`** in the format described in the step file
+4. **Run** `work-kit complete wrap-up/summary --outcome done`
+5. **Ask the user** if they want the worktree and branch removed
 
 ## Summary File Format
 
-Overwrite `.work-kit-tracker/archive/<slug>-<date>/summary.md`:
+Overwrite `.work-kit/summary.md`:
 
 ```markdown
 ---

package/skills/wk-wrap-up/steps/summary.md

@@ -0,0 +1,86 @@
+# Step: Summary
+
+**Phase:** Wrap-up
+**Role:** Work Historian
+**Goal:** Distill the full state.md into a useful summary for future developers, then clean up.
+
+## Workflow
+
+The CLI archives `state.md`, `tracker.json`, and (if you wrote one) `summary.md` into
+`.work-kit-tracker/archive/<slug>-<date>/` automatically when the wrap-up step completes.
+It also appends a row to `.work-kit-tracker/index.md`.
+
+**Your job:** write a real `summary.md` to `.work-kit/summary.md` *before* calling
+`work-kit complete wrap-up/summary`. The CLI will pick it up and place it in the archive.
+
+## Instructions
+
+1. **Read the full `.work-kit/state.md`** — every phase output from Plan through Deploy.
+2. **Synthesize the summary** — not a copy-paste; a distillation a future developer can use.
+3. **Write `.work-kit/summary.md`** with the format below.
+4. **Run** `work-kit complete wrap-up/summary --outcome done`.
+5. **Ask the user** if they want the worktree and feature branch removed (use `work-kit cancel` only if no merge happened; otherwise prefer `git worktree remove`).
+
+## Summary File Format
+
+Write to `.work-kit/summary.md`:
+
+```markdown
+---
+slug: <slug>
+branch: feature/<slug>
+pr: <#number or n/a>
+started: <YYYY-MM-DD>
+completed: <YYYY-MM-DD>
+status: <completed | partial | rolled-back>
+---
+
+## Summary
+<2-3 sentences: what was built, why it was needed, and the end state>
+
+## Criteria
+<copy the final criteria checklist from state.md — checked and unchecked>
+
+## Key Decisions
+<only the non-obvious ones — decisions where the alternative was reasonable>
+- <decision>: <what was chosen> — <why, in one line>
+
+## Deviations from Plan
+<anything that changed between Blueprint and final implementation — skip if none>
+- <what changed and why>
+```
+
+## Include vs. Exclude
+
+**Include:**
+- Decisions where you chose between real alternatives
+- Deviations from the Blueprint (and why)
+- Anything a future developer would need to understand the "why" behind the code
+- Criteria status — what was met, what wasn't
+
+**Exclude:**
+- Artifact lists (files, PRs, migrations) — derivable from git
+- Routine implementation details ("created file X, modified file Y")
+- Full phase outputs — distill, don't dump
+- Internal process notes ("ran tests 3 times before they passed")
+
+## Boundaries
+
+### Always
+- Read the full state.md before writing the summary
+- Include every non-obvious decision in Key Decisions
+- Include every deviation from the Blueprint in Deviations
+
+### Never
+- Copy-paste full phase outputs into the summary
+- Skip the criteria checklist
+
+## After Completion
+
+When you call `work-kit complete wrap-up/summary --outcome done`, the CLI:
+
+1. Creates `.work-kit-tracker/archive/<slug>-<date>/`
+2. Copies `state.md`, `tracker.json`, and `summary.md` into it
+3. Appends a row to `.work-kit-tracker/index.md`
+
+You may then commit the archive to the main branch and remove the worktree.

package/cli/src/engine/loopbacks.ts

@@ -1,32 +0,0 @@
-import { PhaseName, Location } from "../state/schema.js";
-import { LOOPBACK_ROUTES } from "../config/loopback-routes.js";
-
-interface LoopbackResult {
-  to: Location;
-  reason: string;
-}
-
-/**
- * Check if completing a sub-stage with a given outcome should trigger a loop-back.
- */
-export function checkLoopback(
-  phase: PhaseName,
-  subStage: string,
-  outcome?: string
-): LoopbackResult | null {
-  if (!outcome) return null;
-
-  const route = LOOPBACK_ROUTES.find(
-    (r) =>
-      r.from.phase === phase &&
-      r.from.subStage === subStage &&
-      r.triggerOutcome === outcome
-  );
-
-  if (!route) return null;
-
-  return {
-    to: route.to,
-    reason: route.reason,
-  };
-}

package/cli/src/engine/parallel.ts

@@ -1,60 +0,0 @@
-import type { PhaseName, WorkKitState } from "../state/schema.js";
-
-/**
- * Defines which sub-stages run in parallel and which runs sequentially after.
- */
-export interface ParallelGroup {
-  parallel: string[];          // sub-stages that run concurrently
-  thenSequential?: string;     // sub-stage that runs after all parallel complete
-}
-
-/**
- * Parallel group definitions per phase.
- */
-const PARALLEL_GROUPS: Record<string, ParallelGroup> = {
-  test: {
-    parallel: ["verify", "e2e"],
-    thenSequential: "validate",
-  },
-  review: {
-    parallel: ["self-review", "security", "performance", "compliance"],
-    thenSequential: "handoff",
-  },
-};
-
-/**
- * Check if a sub-stage triggers a parallel group.
- * Triggers on any parallel member that is the first non-skipped one in the group.
- * Returns null if the sub-stage is not a parallel trigger or the group doesn't apply.
- */
-export function getParallelGroup(phase: PhaseName, subStage: string, state?: WorkKitState): ParallelGroup | null {
-  const group = PARALLEL_GROUPS[phase];
-  if (!group) return null;
-
-  if (!group.parallel.includes(subStage)) return null;
-
-  // Find the first non-skipped parallel member
-  if (state) {
-    const phaseState = state.phases[phase];
-    const firstActive = group.parallel.find((ss) => {
-      const ssState = phaseState?.subStages[ss];
-      return ssState && ssState.status !== "skipped" && ssState.status !== "completed";
-    });
-    // Only trigger if this sub-stage is the first active parallel member
-    if (firstActive !== subStage) return null;
-  } else {
-    // No state provided — fall back to first-member trigger
-    if (group.parallel[0] !== subStage) return null;
-  }
-
-  return group;
-}
-
-/**
- * Check if a sub-stage is a parallel member (part of a group, not necessarily trigger).
- */
-export function isParallelMember(phase: PhaseName, subStage: string): boolean {
-  const group = PARALLEL_GROUPS[phase];
-  if (!group) return false;
-  return group.parallel.includes(subStage);
-}

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

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