work-kit-cli 0.2.8 → 0.4.0

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,10 +27,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:
 
 - **`## 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.
+- **`## Observations`** — Whenever you notice a fragile area, a missing test pattern, or feedback about the test 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.
 
 The criteria checklist is copied directly into the final work-kit log. Make it accurate.
 
@@ -51,7 +52,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 +75,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/steps/e2e.md

@@ -0,0 +1,56 @@
+---
+description: "Test step: Test user flows end-to-end."
+---
+
+# E2E
+
+**Role:** End-to-End Tester
+**Goal:** Test the feature as a user would experience it.
+
+## Instructions
+
+1. **Verify Playwright is installed.** Run `npx playwright --version`. If it fails or `@playwright/test` is missing from `package.json`, STOP and tell the user to run `work-kit setup` (which installs Playwright + Chromium and scaffolds a config).
+2. Review the UX Flow from the Plan phase.
+3. For each user flow defined:
+   - Write a Playwright test under the project's configured `testDir` (see `playwright.config.*`).
+   - Test the happy path.
+   - Test key edge cases (empty state, error state, boundary values).
+4. Run the tests with `npx playwright test`. All flows must pass before marking this step done.
+5. Capture screenshots at key states using Playwright's `page.screenshot()` or the `--trace on` flag.
+6. Focus on the most important flows — don't test every permutation.
+
+## Output (append to state.md)
+
+```markdown
+### Test: E2E
+
+**Verdict:** pass | fail
+**Tests Written:**
+- `<test file>`: <flow description>
+
+**Flows Verified:**
+- <flow 1>: pass | fail (<details>)
+- <flow 2>: pass | fail (<details>)
+
+**Screenshots:**
+- <description>: <path or "not applicable">
+
+**Notes:**
+- <edge cases tested, issues found>
+```
+
+## Rules
+
+- Playwright is the required E2E framework. Manual verification does NOT satisfy this step.
+- If Playwright is missing, halt and direct the user to `work-kit setup` — do not fall back to curl, manual steps, or another framework.
+- Focus on user-visible behavior, not internal implementation.
+- Screenshots are evidence — capture them for key states.
+- If a flow fails, fix the implementation (not the test) unless the test expectation is wrong.
+
+## Anti-Rationalization
+
+| Excuse | Reality |
+|--------|---------|
+| "Manual verification counts as E2E testing" | It does not. The E2E step requires automated Playwright tests. If Playwright is unavailable, halt and ask the user to run `work-kit setup`. |
+| "Unit tests already cover this flow" | Unit tests mock boundaries. E2E tests verify the real flow across boundaries — database, API, UI. A function can pass its unit test and still fail in the real pipeline. |
+| "E2E tests are slow and fragile, not worth the effort" | Slow tests that catch real bugs are more valuable than fast tests that miss them. Write focused E2E tests for critical paths, not exhaustive ones for every edge case. |

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,32 @@ 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 **two steps** (in order):
+
+1. **`wrap-up/summary`** — distill state.md into a useful summary for future developers. See `.claude/skills/wk-wrap-up/steps/summary.md`.
+2. **`wrap-up/knowledge`** — harvest learnings from this session into the project's `.work-kit-knowledge/` files so the next session benefits. See `.claude/skills/wk-wrap-up/steps/knowledge.md`.
+
+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`. After summary completes, the `knowledge` step runs `work-kit extract` and (optionally) one or more `work-kit learn` calls.
 
-> **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
 
+### Step 1: summary
 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`
+
+### Step 2: knowledge
+5. **Run `work-kit extract`** — mechanically routes Observations / Decisions / Deviations / loopbacks into `.work-kit-knowledge/` files
+6. **Review the summary you just wrote** for subjective additions the parser would miss. For each, call `work-kit learn --type <lesson|convention|risk|workflow> --text "..."`.
+7. **Run** `work-kit complete wrap-up/knowledge --outcome done`
+
+### Cleanup
+8. **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/knowledge.md

@@ -0,0 +1,76 @@
+# Step: Knowledge
+
+**Phase:** Wrap-up
+**Role:** Knowledge Harvester
+**Goal:** Route this session's learnings into the project's `.work-kit-knowledge/` files so the next session — and the next developer — starts smarter.
+
+## When this step runs
+
+After `wrap-up/summary`. By now you've just re-read the full `state.md` and distilled it into a summary, so your working memory of this session is at its peak. This is the right moment to capture observations the parser would miss.
+
+## Workflow
+
+1. **Run mechanical extraction:**
+   ```bash
+   work-kit extract
+   ```
+   This parses `.work-kit/state.md` and `.work-kit/tracker.json` and routes entries to `.work-kit-knowledge/{lessons,conventions,risks,workflow}.md`. It pulls from:
+   - `## Observations` typed bullets (`- [lesson|convention|risk|workflow] text`)
+   - `## Decisions` → conventions
+   - `## Deviations` → workflow feedback
+   - `tracker.json.loopbacks[]` → workflow feedback
+   - Skipped/failed steps → workflow feedback
+
+   The output JSON tells you how many entries were `written` vs `duplicates`. Re-running is idempotent.
+
+2. **Read your `.work-kit/summary.md`** (the one you just wrote). For each non-obvious thing in it that the parser would NOT have captured automatically, call `work-kit learn`:
+
+   ```bash
+   work-kit learn --type lesson --text "Discovered that the test fixtures must be reset between Playwright suites, otherwise auth state leaks."
+   work-kit learn --type risk --text "src/payment/webhook.ts has no integration test coverage for retries."
+   work-kit learn --type convention --text "All new API endpoints must register a Zod schema in src/schemas/."
+   work-kit learn --type workflow --text "The wk-test/e2e step doesn't tell agents to start the dev server before running Playwright."
+   ```
+
+   Each call appends one entry to the appropriate `.md` file under a lockfile, with secret redaction applied automatically.
+
+3. **Mark the step complete:**
+   ```bash
+   work-kit complete wrap-up/knowledge --outcome done
+   ```
+
+## What goes where
+
+| Type | File | What belongs here |
+|---|---|---|
+| `lesson` | lessons.md | Project-specific learnings — facts about *this* codebase. |
+| `convention` | conventions.md | Codified rules this project follows. Future sessions should respect these. |
+| `risk` | risks.md | Fragile or dangerous areas. Touch with care. |
+| `workflow` | workflow.md | Feedback about the work-kit kit itself — skill quality, step skips, loopbacks, failure modes. **Mined manually across projects to improve work-kit upstream.** |
+
+## Boundaries
+
+### Always
+- Run `work-kit extract` first, then add manual `learn` calls.
+- Keep `learn --text` entries to one sentence — they're for humans skimming a list.
+- Use `workflow` type only for feedback about the work-kit *itself*, not for project facts.
+
+### Never
+- Edit the `## Manual` section of any knowledge file. That's human-curated and tooling never touches it.
+- Use `workflow.md` for project-specific facts. Use `lessons.md` instead.
+- Paste large code blocks, file contents, or stack traces into `--text`. Distill into one sentence.
+- Skip extraction. Even if you have nothing to add manually, `work-kit extract` still routes loopbacks and deviations.
+
+### Failure mode
+- Non-fatal. If extract or learn fails, the summary step has already succeeded — the session isn't lost. Report the error to the user; they can retry manually or run `work-kit complete wrap-up/knowledge --outcome done` anyway.
+
+## Output
+
+No file output for this step — entries land in `.work-kit-knowledge/*.md`. Optionally append a one-line note to `.work-kit/state.md` describing what you captured, e.g.:
+
+```markdown
+### Wrap-up: Knowledge
+
+**Extracted:** 4 entries (2 conventions, 1 risk, 1 workflow)
+**Manual additions:** 2 lessons, 1 workflow feedback
+```

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");
-  });
-});

package/skills/wk-test/stages/e2e.md

@@ -1,53 +0,0 @@
----
-description: "Test sub-stage: Test user flows end-to-end."
----
-
-# E2E
-
-**Role:** End-to-End Tester
-**Goal:** Test the feature as a user would experience it.
-
-## Instructions
-
-1. Review the UX Flow from the Plan phase
-2. For each user flow defined:
-   - Write an E2E test (Playwright, Cypress, or manual verification)
-   - Test the happy path
-   - Test key edge cases (empty state, error state, boundary values)
-3. Take screenshots at key states if the test framework supports it
-4. Focus on the most important flows — don't test every permutation
-
-## Output (append to state.md)
-
-```markdown
-### Test: E2E
-
-**Verdict:** pass | fail
-**Tests Written:**
-- `<test file>`: <flow description>
-
-**Flows Verified:**
-- <flow 1>: pass | fail (<details>)
-- <flow 2>: pass | fail (<details>)
-
-**Screenshots:**
-- <description>: <path or "not applicable">
-
-**Notes:**
-- <edge cases tested, issues found>
-```
-
-## Rules
-
-- If the project has no E2E framework, test manually and document the steps
-- Focus on user-visible behavior, not internal implementation
-- Screenshots are evidence — capture them for key states
-- If a flow fails, fix the implementation (not the test) unless the test expectation is wrong
-
-## Anti-Rationalization
-
-| Excuse | Reality |
-|--------|---------|
-| "Manual verification counts as E2E testing" | Manual verification is not repeatable, not documented, and not run in CI. If you cannot automate it, at minimum document the exact manual steps with expected results. |
-| "Unit tests already cover this flow" | Unit tests mock boundaries. E2E tests verify the real flow across boundaries — database, API, UI. A function can pass its unit test and still fail in the real pipeline. |
-| "E2E tests are slow and fragile, not worth the effort" | Slow tests that catch real bugs are more valuable than fast tests that miss them. Write focused E2E tests for critical paths, not exhaustive ones for every edge case. |