work-kit-cli 0.3.0 → 0.4.1

package/skills/auto-kit/SKILL.md

@@ -2,7 +2,7 @@
 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
 ---
 
@@ -91,17 +91,34 @@ 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>
-   work-kit 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: `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
+
+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)
 
@@ -186,8 +203,8 @@ The CLI manages all state transitions, prerequisites, and loopbacks. Follow this
 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: `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>`
+   - **`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.

package/skills/full-kit/SKILL.md

@@ -2,7 +2,7 @@
 name: full-kit
 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
 ---
 
@@ -33,15 +33,32 @@ 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>
-   work-kit 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)
 
@@ -61,8 +78,8 @@ The CLI manages all state transitions, prerequisites, and loopbacks. Follow this
 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: `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>`
+   - **`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.

package/skills/resume-kit/SKILL.md

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

package/skills/wk-bootstrap/SKILL.md

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

package/skills/wk-build/SKILL.md

@@ -33,12 +33,13 @@ For each step:
 
 ## Recording
 
-Throughout every step, capture three things in the shared state.md sections:
+Throughout every step, capture these things in the shared state.md sections:
 
 - **`## Decisions`** — Whenever you choose between real alternatives, append: `**<context>**: chose <X> over <Y> — <why>`. Skip obvious choices.
 - **`## Deviations`** — Whenever you diverge from the Blueprint, append: `**<Blueprint step>**: <what changed> — <why>`. Every deviation needs a reason.
+- **`## Observations`** — Whenever you notice a project convention, a fragile area, a learning, or feedback about the work-kit workflow itself, append a typed bullet: `- [lesson|convention|risk|workflow] text` (workflow tag may include `:phase/step`). At `wrap-up/knowledge` these are routed to `.work-kit-knowledge/` so future sessions benefit.
 
-These feed into the final work-kit log summary. If you don't record them here, they're lost.
+These feed into the final work-kit log summary and the project knowledge files. If you don't record them here, they're lost.
 
 ## Boundaries
 

package/skills/wk-deploy/SKILL.md

@@ -30,6 +30,7 @@ For each step:
 Update the shared state.md sections:
 
 - **`## Decisions`** — Record merge method choice, any rollback decisions.
+- **`## Observations`** — Whenever you notice deploy fragility, a missing convention, or feedback about the deploy phase itself, append: `- [lesson|convention|risk|workflow] text` (workflow tag may include `:phase/step`). At `wrap-up/knowledge` these are routed to `.work-kit-knowledge/` so future sessions benefit.
 
 ## This phase is optional
 

package/skills/wk-plan/SKILL.md

@@ -33,11 +33,12 @@ Maintain context across all steps — each builds on the previous. Reference pri
 
 ## Recording
 
-Throughout every step, capture two things in the shared state.md sections:
+Throughout every step, capture these things in the shared state.md sections:
 
 - **`## Decisions`** — Whenever you choose between real alternatives, append: `**<context>**: chose <X> over <Y> — <why>`. Skip obvious choices.
+- **`## Observations`** — Whenever you notice a project convention, a fragile area, a learning, or feedback about the work-kit workflow itself, append a typed bullet: `- [lesson|convention|risk|workflow] text` (workflow tag may include `:phase/step`). At `wrap-up/knowledge` these are routed to `.work-kit-knowledge/` so future sessions benefit.
 
-These feed into the final work-kit log summary. If you don't record decisions here, they're lost.
+These feed into the final work-kit log summary and the project knowledge files. If you don't record them here, they're lost.
 
 ## Loop-back
 

package/skills/wk-review/SKILL.md

@@ -33,6 +33,7 @@ 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 step will audit these. If you fix a deviation during review, note that it was resolved.
+- **`## Observations`** — Whenever you spot a fragile area, a missing convention, or feedback about the review phase itself, append: `- [lesson|convention|risk|workflow] text` (workflow tag may include `:phase/step`). At `wrap-up/knowledge` these are routed to `.work-kit-knowledge/` so future sessions benefit.
 
 Review findings feed directly into the Handoff decision and the final work-kit log.
 

package/skills/wk-test/SKILL.md

@@ -31,6 +31,7 @@ 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.
 

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

@@ -9,13 +9,15 @@ description: "Test step: Test user flows end-to-end."
 
 ## 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
+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)
 
@@ -39,15 +41,16 @@ description: "Test step: Test user flows end-to-end."
 
 ## 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
+- 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" | 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. |
+| "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-wrap-up/SKILL.md

@@ -10,15 +10,28 @@ 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.
 
-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`.
+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.
 
 ## 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. **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
+
+### Step 2: knowledge
+5. **Run `work-kit extract`** — routes typed `## Observations` bullets and tracker loopbacks/skipped/failed steps into `.work-kit-knowledge/` files. `## Decisions` and `## Deviations` are not auto-harvested (they're scratch space).
+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
 

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`) — the only section that is auto-harvested
+   - `tracker.json.loopbacks[]` → workflow feedback
+   - Skipped/failed steps → workflow feedback
+
+   `## Decisions` and `## Deviations` are **not** auto-harvested — they're agent scratch space and routinely contain test plans and review notes. If something in there is worth preserving, restate it as a typed bullet under `## Observations` (or call `work-kit learn` directly in step 2).
+
+   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
+```