@brainervirus/workit-claude-code 7.2.0 → 7.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-claude-code",
-  "version": "7.2.0",
+  "version": "7.4.0",
   "private": false,
   "description": "Workit Claude Code plugin — session and per-turn task context, branch policy on git shell commands, workit method skills, and verifier/reviewer/implementer agents",
   "keywords": [
@@ -39,8 +39,8 @@
     "build": "bun scripts/build.ts"
   },
   "devDependencies": {
-    "@brainervirus/workit-cli": "^7.2.0",
-    "@brainervirus/workit-core": "^7.2.0"
+    "@brainervirus/workit-cli": "^7.4.0",
+    "@brainervirus/workit-core": "^7.4.0"
   },
   "engines": {
     "node": ">=24"

package/skills/fanout/SKILL.md

@@ -10,41 +10,49 @@ verifiable alone. Code-coupled work stays with one owner, who fans out after
 the blocking part lands. A worker whose whole job is re-running one command is
 ceremony; do it yourself.
 
-1. **Slice** (workit-shape): each slice gets a branch, a file-scope manifest
-   (the globs it may write) and, if it depends on another, its stack parent.
-2. **Check disjointness.** No two manifests overlap. Shared files (lockfile,
-   registry, barrel exports) belong to one slice, or to you after fan-in.
-3. **Brief each worker** with the fixed template and refuse to spawn while a
-   field is empty: GOAL, SCOPE (the manifest), CONTEXT (pointers, not pasted
-   text), ACCEPTANCE (Given/When/Then), VERIFY (exact commands), TIMEBOX,
-   FORBIDDEN, REPORT, STANDING. STANDING is every standing order and user
-   directive so far, pasted verbatim into each spawn and respawn, because
-   directives decay across resumes. Template: `references/brief.md`.
-4. **Spawn all workers in one message**, in the background, each in its own
+1. **Plan the slices** (workit-shape) in a plan file (`references/brief.md`):
+   per slice an id, branch, TIER, the file-scope manifest (SCOPE globs),
+   `owns` for shared files (lockfile, registry, barrels), `dependsOn` only for
+   a real dependency (independent PRs off trunk are the default), and the
+   brief fields. `workit fanout plan <plan.json>` refuses an empty brief field
+   (exit 2) and two slices that may write one file (exit 3) with a fix: an
+   owner for a shared file, or a dependency that serializes them. Apply it and
+   re-run: refuse to spawn while a field is empty or the plan is refused.
+   Its `waves` say which slices may run together; keep 4-6 in flight.
+2. **Brief each worker** from its slice with the fixed template: GOAL, SCOPE,
+   CONTEXT (pointers, not pasted text), ACCEPTANCE (Given/When/Then), VERIFY
+   (exact commands), TIER, TIMEBOX, FORBIDDEN, REPORT, STANDING. STANDING is
+   every standing order and user directive so far, pasted verbatim into each
+   spawn and respawn, because directives decay across resumes.
+3. **Spawn all workers in one message**, in the background, each in its own
    worktree (Claude Code: the `implementer` agent; elsewhere
    `git worktree add --detach ../<repo>-wt/<slug> origin/<base>`). The first
    command a worker runs is `workit git branch <branch> --base <base>`.
-5. **Judge liveness by side effects only:** new commits and pushes
+4. **Judge liveness by side effects only:** new commits and pushes
    (`git log <branch>`), PR and check changes (`workit pr status --branch <b>`).
    No progress past the timebox means stuck. Stop the old worker and observe
    that it exited (a timeout is not proof). `git worktree remove --force`
    drops its uncommitted changes, so first record `git -C <wt> status --short`
-   in the ledger or your report; only then remove the worktree. Respawn with the brief in
-   `MODE: resume` (consolidated: original, later directives, its last report):
+   in the ledger or your report; only then remove the worktree. Respawn with
+   the brief in `MODE: resume` (original, later directives, its last report):
    the new worker runs `git switch <branch>` in its fresh worktree instead of
    `workit git branch`. Never two live workers on one branch. Replace at most
    twice, then re-slice or report the gap. Never chain resumes.
-6. **Verify each slice independently.** A fresh agent that did not write it
+5. **Verify each slice independently.** A fresh agent that did not write it
    (Claude Code: the `verifier` agent) runs VERIFY and verify-<app>, then
    `workit ledger verdict <result> --branch <b> --how "<evidence>"` under the
    session you started it with (`WORKIT_SESSION_ID=<lead>-v<n>`, set by you,
    never chosen by the author; Claude Code: the hook names one).
    A worker's report is a pointer, never evidence.
-7. **Fan in.** Compare `git diff --name-only <base>...<b>` with the slice's
-   SCOPE: any file outside it stops the fan-in with a report. Then
-   `workit ledger check --branch <b>` for each slice; restack
-   stacked slices with `workit stack sync`. Only you touch topology: workers
-   never rebase, retarget or merge. Then workit-ship.
+6. **Fan in** with `workit fanout check`: out-of-scope files (any file outside
+   it stops the fan-in), and `git merge-tree` conflicts with trunk and between
+   siblings, charged to the slice that lands later. Fix what it names (an
+   out-of-scope edit becomes a follow-up slice) until it exits 0. A landed
+   slice reads as not found: re-plan without it and drop it from dependents'
+   `dependsOn`. Then `workit ledger check --branch <b>` per slice; land in its
+   order. Stacked slices: `workit stack plan <bottom> … <top>` once, then
+   `workit stack sync` and `land`. Only you touch topology: workers never
+   rebase, retarget or merge. Then workit-ship.
 
 ## Example
 
@@ -58,5 +66,6 @@ counts; SCOPE: `src/routes/usage.ts`, `test/usage.test.ts`; VERIFY:
 ## Check
 
 ```sh
+workit fanout check                # exit 0: in scope, no conflicts, landing order printed
 workit ledger check --branch <b>   # per slice: accepted (current, passing, independent)
 ```

package/skills/fanout/references/brief.md

@@ -12,6 +12,7 @@ CONTEXT: <pointers: spec section, ledger decisions, the neighbour file to imitat
 ACCEPTANCE:
   - Given <state>, When <action>, Then <observable result>
 VERIFY: <exact commands, e.g. `workit check test`, the verify-<app> feature to drive>
+TIER: <mundane | standard | hard: how much model the slice needs>
 TIMEBOX: <wall clock or turn budget; past it without a new commit you will be replaced>
 FORBIDDEN: <no edits outside SCOPE; no rebase, retarget, merge or force-push; no new dependencies; ...>
 REPORT: branch, head SHA, files changed, each VERIFY command with its exit code,
@@ -34,12 +35,56 @@ ACCEPTANCE:
   - Given 3 runs today and 1 yesterday, When GET /v1/usage, Then the last two entries are {"runs":1} and {"runs":3}
   - Given no auth header, When GET /v1/usage, Then the status is 401
 VERIFY: `workit check test`; verify-api feature "usage"
+TIER: standard
 TIMEBOX: 45 minutes
 FORBIDDEN: no edits outside SCOPE; no schema migration; no rebase or force-push; no new packages
 REPORT: as in the template
 STANDING: conventional commits; no comments that restate code; ask nothing, record rulings instead
 ```
 
+## Plan file
+
+`workit fanout plan <plan.json>` records the slices before any spawn. Each
+slice carries the brief fields the plan checks (goal, scope, acceptance,
+verify, forbidden must be filled; tier is mundane, standard or hard). `base`
+defaults to the trunk, or to the branch of a single `dependsOn` slice (a
+stack); `worktree` defaults to `../<repo>-wt/<id>`. `owns` claims a shared
+file another slice's glob also matches. Globs that match no file yet are compared
+through a sample path. Escape literal brackets: `"app/\\[id\\]/page.tsx"`.
+
+```json
+{
+  "name": "usage",
+  "trunk": "main",
+  "slices": [
+    {
+      "id": "usage-endpoint",
+      "branch": "feature/usage-endpoint",
+      "tier": "standard",
+      "scope": ["src/routes/usage.ts", "src/queries/usage.ts", "test/usage.test.ts"],
+      "owns": ["package.json"],
+      "goal": "GET /v1/usage returns the run count per UTC day for the last 7 days",
+      "acceptance": ["Given no auth header, When GET /v1/usage, Then the status is 401"],
+      "verify": ["workit check test"],
+      "forbidden": ["no edits outside SCOPE", "no rebase or force-push"],
+      "context": "docs/usage/spec.md Behavior",
+      "timebox": "45 minutes"
+    },
+    {
+      "id": "usage-docs",
+      "branch": "docs/usage",
+      "tier": "mundane",
+      "dependsOn": ["usage-endpoint"],
+      "scope": ["docs/usage/**"],
+      "goal": "The API guide documents GET /v1/usage",
+      "acceptance": ["Given the guide, When a reader looks up usage, Then the response shape is shown"],
+      "verify": ["workit check docs"],
+      "forbidden": ["no edits outside SCOPE"]
+    }
+  ]
+}
+```
+
 ## Worker rules (paste into the brief when the host has no implementer agent)
 
 1. First command. `MODE: new`: `workit git branch <branch> --base <base>` (the

package/skills/retro/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: retro
+description: Find repeated friction in recent sessions; propose cited fixes ranked by enforcer strength, never applied. Use for retro.
+disable-model-invocation: true
+---
+
+# Retro: turn repeated friction into enforcers
+
+User-invoked: offer it, never start it yourself. Run it after a session, PR,
+stack or fan-in, including ones that went well; a smooth session still shows
+where agents searched too long, worked around a tool or re-ran a check. Retro
+proposes and stops. Nothing changes until the user approves.
+
+1. **Scope.** Default: this repository's work since the last retro (its
+   `retro:` row in `workit ledger list --type decision`), else the last ~10
+   sessions. State the window in one line.
+2. **Read through workit, cheapest first.** Every finding cites these:
+   - `workit ledger list --last 200`: rulings (ambiguities the agent had to
+     settle), failed or self verdicts, handoffs, check runs, CI reruns.
+   - `workit pr status --pr <n>` for each recent PR: threads, failing checks.
+   - `git log --oneline -50`, plus reverts and fixups after review.
+   - `workit knowledge lint`: today's AGENTS.md and need-based files.
+   - Session transcripts **only if the user opts in**, and only this
+     workspace's (`references/sources.md`). Never read other projects.
+
+   Cite by location (ledger row, PR, commit, session file and line). Never
+   copy secrets, tokens or personal data from any source into the report.
+3. **Group into classes.** Navigation cost (many searches before the right
+   file, a stale doc followed), repeated mistakes, workarounds (a hand-run
+   command where a verb exists, a skipped step), unstable checks (the same
+   `workit check <name>` red then green with no change). A class needs **2 or
+   more cited occurrences**; a one-off is not a learning.
+4. **Name the strongest enforcer that works**, strongest first: architecture
+   or types (the mistake cannot be written) > lint rule > configured check
+   (`workit.checks.json`, `workit check <name>`) or CI job > test >
+   `CODING_STANDARDS.md` (judgment the reviewer reads) > AGENTS.md pointer
+   (navigation only). A mechanical rule gets a check, not prose: a check can
+   fail, a sentence cannot. From types to test, the proof is that the new
+   enforcer fails on the cited past mistake. A rule whose mistake can no
+   longer happen is deleted.
+5. **Upstream.** When a workit skill, verb or hook caused the friction,
+   propose an issue or PR on BrainerVirus/workit. Never fork a local copy.
+   The issue shows the workit behavior in a minimal synthetic reproduction:
+   no private repo name, path, code, ledger text, PR or thread quote, or
+   transcript. Show the exact draft body; file it only after the user approves.
+6. **Bloat guards.** AGENTS.md stays within 8 KB: each addition names what it
+   removes. Create `CODING_STANDARDS.md` or `GLOSSARY.md` only in the same
+   edit as its first real entry, never as a scaffold. Edit steering text by
+   `references/steering.md`; `workit knowledge lint` passes after the slice.
+7. **Report one ranked list, then stop:** Accepted (proposed), Backlog,
+   Dropped, each with its citations, enforcer and reason. Each approved item
+   becomes a normal slice (workit-implement, then workit-ship), a tracker
+   issue, or `.out-of-scope/<concept>.md` when rejected and likely to return.
+   Record the user's answer so the next retro starts there:
+   `workit ledger decision "retro: <accepted ids>" --why "<window>"`.
+
+## Example
+
+Bad: "Agents seem lost in the build. Added 'read the build docs carefully' to
+AGENTS.md." One vague occurrence, no citation, a no-op line, auto-applied.
+
+Good: "Navigation, 3 occurrences (rulings 12, 19; PR #88 thread): agents sought
+check names in package.json, missing `workit.checks.json`. Enforcer: AGENTS.md
+pointer, +74 bytes, minus the stale Commands paragraph (-210). Unstable check,
+2 occurrences (ledger rows 31, 44: `e2e` red then green on one SHA): a debug
+slice to fix the check. Approve?"
+
+## Check
+
+```sh
+workit knowledge lint   # exit 0 before and after each approved slice
+```

package/skills/retro/agents/openai.yaml

@@ -0,0 +1,3 @@
+# Codex: user-invoked only (the counterpart of disable-model-invocation).
+policy:
+  allow_implicit_invocation: false

package/skills/retro/references/sources.md

@@ -0,0 +1,35 @@
+# Session transcripts (opt-in, this workspace only)
+
+Transcripts are the most expensive source and can hold private material. Read
+them only after the user says yes to a question such as "Also read the last 10
+session transcripts for this workspace? (local files, read-only)". The default
+is no: the ledger, `pr status` and git are enough for most retros.
+
+## Where they live
+
+Typical locations; confirm each exists. Resolve the path from this workspace's
+absolute path, never with a wildcard across projects. If a host's layout
+differs from the one below, say so and skip it rather than search wider.
+
+| Host | Location |
+| --- | --- |
+| Claude Code | `~/.claude/projects/<folder>/*.jsonl`, one folder per path from `git worktree list`: the absolute path with every `/` and `.` replaced by `-`. Compute each folder name; never glob for it |
+| Codex | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`. To filter, parse only line 1 (`session_meta`) and read only its `cwd` field; skip files whose `cwd` is not this workspace without reading or reporting anything else from them |
+| Cursor | `~/.cursor/projects/<workspace slug>/agent-transcripts/` |
+| Pi | `~/.pi/agent/sessions/--<workspace path, / replaced by ->--/*.jsonl` |
+| OpenCode | this project's sessions from `opencode session list`, read with `opencode export <id>` |
+
+Linked worktrees of the same repository count as this workspace; other
+repositories never do.
+
+## How to read them
+
+- Newest first, at most the agreed number of sessions.
+- On a host with subagents, one read-only analyst per lens, each returning
+  only cited occurrences (session file plus line or message index):
+  - navigation: searches and reads before the right file was found, stale docs
+    followed;
+  - tool economy: hand-run commands where a `workit` verb exists, repeated
+    reads of the same file, long outputs nobody used;
+  - repeated work: the same fix or check redone, a step undone later;
+  - request conflicts: instructions the agent had to reconcile or ask about.

package/skills/retro/references/steering.md

@@ -0,0 +1,39 @@
+# Editing steering text (AGENTS.md, CODING_STANDARDS.md, skills)
+
+Steering text is paid for on every session that reads it. Each line must
+change what an agent does; everything else is cost.
+
+## Write
+
+- **Point, do not copy.** Link the file or name the command; never paste its
+  content. A pointer says when to follow it: "Read before editing a hook:
+  `docs/agents/hosts.md`".
+- **Say what done looks like.** "Run `bun run check`; it must exit 0" beats
+  "make sure everything works".
+- **Concrete over adjectives.** A command, a path, a number. Prefer the action
+  to take over a list of things to avoid.
+- **One rule, one home.** A rule with an enforcer (type, lint, check, test)
+  appears in steering text at most as a pointer to that enforcer. The same
+  sentence in AGENTS.md and CODING_STANDARDS.md is a defect
+  (`duplicate-rule`).
+- **Judgment goes to CODING_STANDARDS.md**, which the reviewer reads; only
+  navigation goes to AGENTS.md.
+
+## Cut
+
+- **No-ops.** Delete lines that would not change any behavior if removed:
+  "be thorough", "write clean code", "keep it concise", "follow best
+  practices".
+- **Session residue.** No notes about one session, no implementation detail
+  the code already shows, no `path:line` references (they go stale).
+- **Dead rules.** A rule whose mistake can no longer happen (a type or check
+  now prevents it) is deleted, not kept "for context".
+
+## Budget
+
+- AGENTS.md stays within 8 KB (`workit knowledge lint`, rule
+  `agents-budget`). A proposal that adds text names what it removes, or shows
+  the byte count still holds.
+- A need-based file (`CODING_STANDARDS.md`, `GLOSSARY.md`) is created in the
+  same edit as its first real entry. Headers-only or "TBD" files fail the lint
+  (`scaffold-file`).

package/skills/review/SKILL.md

@@ -18,8 +18,9 @@ independent; `type-check-only` never proves a behavior change.
 3. Judge two axes separately, never merged or re-ranked:
    - **Spec:** does the diff do what the acceptance says? Missing, creep or
      wrong; quote the line.
-   - **Standards:** repo rules first, then a smell baseline (unclear name, long
-     function, duplicated logic, leaky abstraction). Judgment only; lint owns nits.
+   - **Standards:** repo rules first (`CODING_STANDARDS.md` when present),
+     then a smell baseline (unclear name, long function, duplicated logic,
+     leaky abstraction). Judgment only; lint owns nits.
 4. **Tests:** `workit test-audit --diff`. Would each new test fail if the
    behavior broke? Triage with workit-test-audit.
 5. **Blast radius:** for each touched contract, caller, config or migration,

package/skills/shape/references/knowledge.md

@@ -10,11 +10,14 @@ user asks for one, say which trigger fired, and let the user decline.
 | Plan | more than one slice with dependencies, or work that will be resumed by someone else | `docs/<topic>/plan.md`, next to the spec |
 | ADR | the choice is hard to reverse **and** surprising **and** a real trade-off (all three) | `docs/adr/NNNN-<slug>.md` |
 | Glossary entry | a project term was ambiguous and you resolved it | `GLOSSARY.md` (create lazily) |
+| Coding standard | a judgment-call rule a reviewer must check, recurring twice (workit-retro); a mechanical rule gets a check instead | `CODING_STANDARDS.md` (create lazily) |
 | Out of scope | a request was rejected and is likely to come back | `.out-of-scope/<concept>.md` |
 
 Never: a spec for a one-file mechanical fix, a plan that restates the spec,
 file paths or line numbers in a spec (they go stale), a glossary entry for a
 general programming term.
+Create a lazy file only in the same edit as its first real entry, never as a
+headers-only or TBD scaffold (`workit knowledge lint` flags one).
 
 ## Spec (scaled to the work)
 

package/skills/ship/SKILL.md

@@ -53,7 +53,8 @@ the base keeps moving, or after 3 failed fix attempts on the same check.
 6. **Verified.** After the last push a non-author records a verdict
    (workit-review); `pr status` showing self-reviewed is not verified. Land only when granted: `workit stack land` (the
    contiguous verified run from the root) or `workit pr merge`.
-7. **Observe it landed:** `workit verify-delivery pr` or `merge`.
+7. **Observe it landed:** `workit verify-delivery pr` or `merge`. At any endpoint
+   (stack land, fan-in too), after a failed verdict or a check red 3+ times: offer `/wk-retro`.
 
 ## Example