@workit-dev/opencode 0.0.0-stage → 1.0.0

package/assets/skills/workit-fanout/references/orchestration.md

@@ -0,0 +1,169 @@
+# Running a fanout
+
+How the lead picks models, keeps workers flowing, retries, races, verifies
+and fans in. Workit records and checks; the host's own subagents run the work.
+
+## TIER to model
+
+TIER is a field of each slice and of its brief. Role models come from the
+workspace (`models.roles`; `fanout.tierModels` still feeds the implementer
+tiers) and, on Claude Code, built-in defaults: the brief has a `model:` line
+(with `effort:` when set) under TIER and a `verifier:` line; `workit fanout
+status` names the model next to each spawnable slice; `workit models show
+[--role r] [--host h] --json` lists every role (decider, implementer tiers,
+verifier, reviewer, explore, babysit). Pass exactly that `model` (and `effort`
+where the host's spawn call takes one) on the spawn call: a subagent that
+passes none inherits your model. Scouting and PR babysitting use the `explore`
+and `babysit` roles. A role with no model (other hosts without config) runs
+on the host's model, and TIER only sizes the timebox and decides whether to
+race. Claude Code's built-in defaults, when nothing is configured:
+
+| Role or TIER | `model` on the Agent call |
+| --- | --- |
+| decider | `fable`, effort `high` |
+| hard | `opus` |
+| standard | `sonnet` |
+| mundane | `haiku` |
+| verifier | `sonnet` |
+| reviewer | `opus` |
+| explore, babysit | `haiku` |
+
+Claude Code and OpenCode also get the role's model set on the spawn by
+Workit; a configured one beats a `model` you pass unless
+`models.allowLeadOverride` is true. A general spawn takes
+`models.roles.default`, or the role its prompt's `ROLE: <role>` line names.
+`models.lead` (your own model) is advisory. `workit models show` marks each
+role `enforced` or `advisory` per host: on advisory, pass the model.
+
+## Rolling window
+
+Keep 4-6 workers in flight on Claude Code; elsewhere as many as the host runs
+in the background, never more than 6. Do not wait for a whole wave: when one
+worker finishes (its notification, or a new head or PR in `workit fanout
+status`), verify it, then spawn the next slice from `spawnable` in the same
+status output. A slice whose dependencies landed, or a stacked child whose
+parent is verified, appears there by itself.
+
+## Retry, then escalate
+
+A slice is retried when it is STUCK, its worker exits without meeting
+ACCEPTANCE, or its verdict fails. Stop the worker and observe that it exited.
+Release its worktree: `workit fanout worktree release <slice>` (it records
+`git status` first), and create it again for the retry. Then spawn one fresh
+worker with `workit fanout brief <slice> --mode resume`: same branch, and the
+brief points at its head and its ledger rows (last report, verdicts,
+rulings). If the retry fails too, escalate instead of a third worker:
+re-slice it smaller (`workit fanout plan` again), take it over yourself, or
+report the gap to the user.
+
+## Stuck calls: the decider
+
+A failed review gets one fix round and one recheck (the changed hunks only).
+If the recheck fails, or a worker and a reviewer disagree, spawn a decider
+instead of a third round. A decider is a fresh read-only agent, not the author
+or the reviewer. It returns three things: the options, a pick by
+reversibility (the option cheapest to undo wins a tie), and the exact change
+list. The fixer applies that list once, then one focused recheck follows.
+
+- Hard call (shared contract, security, migration): two deciders on different
+  models (Claude Code, OpenCode, Cursor: the `decider` role model and a
+  different `model` on the spawn, kept on a configured decider role only with
+  `models.allowLeadOverride`; Codex and Pi: one decider). If they disagree, you take the
+  more reversible option.
+- Record it: `workit ledger decision "<pick>" --by decider --why "<why it is
+  the more reversible>" --view "<decider A: view>" --view "<decider B: view>"`.
+  The row is listed as a decider call; it is never the user's answer to a
+  product choice and never a verdict.
+- A product choice, or authority nobody here has, is not a decider's call:
+  ask the user with your recommendation.
+
+## Race a hard slice
+
+When a hard slice has an uncertain approach and a cheap VERIFY, run 2-3
+attempts at once instead of retrying in series. `workit fanout brief <slice>
+--attempt <n>` gives each attempt its own branch (`<branch>-try<n>`), session
+and scratch dir. Each attempt needs its own worktree, and `fanout worktree
+create` makes only the slice's own one, so run the attempts one after another
+there on every host.
+Verify every attempt, keep the one with the best verdict (accepted first,
+then the fewest changed files, then the earliest), point the slice branch at
+it (`git branch <branch> <winner>`), have the verifier record the verdict on
+`<branch>` (same head), and delete the losing attempt branches.
+
+## Verification
+
+Follow the workspace `verification` setting (`workit grant show`); the
+worker never records a verdict on its own work.
+
+- `self` (the default): a verifier that wrote none of the slices records the
+  verdicts. A lead that authored none of the slices may record them in its
+  own session.
+- `independent`, and any slice at high risk: a separate verifier session
+  records them, never the lead's own; at high risk one verifier per slice,
+  plus a review panel (below). This is doctrine, not enforced: the ledger
+  only tells a branch's authors from everyone else, and a lead that wrote
+  none of it counts as independent.
+
+Which session id a verdict carries, per host:
+
+- Claude Code: subagents inherit your `WORKIT_SESSION_ID`, so the
+  SubagentStart hook names each `verifier` and `reviewer` its own session
+  (`<lead>:<agent id>`) and a token only that subagent sees, passed exactly as
+  `--session` and `--token`: the hook records the ids it issues, and only
+  those, with their token, are accepted. An `implementer` is issued
+  none: it keeps your id in its env for its workit commands and commits.
+- Codex: the `workit-verifier` and `workit-reviewer` agents get the same
+  issued `--session` and `--token` from SubagentStart; any other verifier passes
+  `--as verifier`.
+- OpenCode: a child session's shell already has
+  `WORKIT_SESSION_ID=<lead>:<child>`; Pi: a supervised worker's shell has
+  `<lead>:<worker session>`. Set nothing for a verifier there.
+- Cursor (no session id in the shell): the brief sets the verifier's
+  `WORKIT_SESSION_ID=<lead>:verifier-<random hex>`, a fresh suffix per
+  verifier. Cursor cannot check it: it is declared, not derived.
+- A worker's commits: on Claude Code the lead's `WORKIT_SESSION_ID` already in
+  its env (SubagentStart issues no implementer id; no export, so the
+  lead authored those commits: a verifier or reviewer records the verdict, not
+  the lead); on OpenCode, Pi and Codex the id the host already
+  puts in its shell; on Cursor, CI and a plain terminal the brief's
+  `export WORKIT_SESSION_ID=<lead>-w-<slice>` (see `brief.md`, "Identity and
+  git rules per host"). A verdict under an id you made up (`<lead>-v1`,
+  `<lead>:v1`) is refused as `forged_session` on Claude Code, Codex,
+  OpenCode and Pi.
+
+A batch verifier takes several slices on one surface in one session: for
+each branch it checks out the head, runs that slice's VERIFY, and records its
+own `workit ledger verdict <result> --branch <b> --how "<evidence>"`. Every
+verdict is keyed to that branch's head SHA; a slice whose head moves after
+it needs a new one. Batch at most what fits one context, about 4 slices.
+
+## Review panel (high risk only)
+
+At risk=high only, 2-3 fresh reviewers (call the skill tool with `workit-review`), each on a model
+other than the author's (Claude Code: a different `model`), each records
+`workit ledger verdict <result> --kind review --branch <b> --how "<findings>"`.
+Land only when every panel verdict passes. Below high risk a panel costs
+more than it finds.
+
+## Integration-branch fan-in (one PR)
+
+Only when the user wants one PR for the whole fanout:
+
+1. Cut the integration branch (`workit git branch <integration> --base
+   <trunk>`) and plan with `"fanIn": "integration"` and `--trunk
+   <integration>`. Planning refuses integration mode on origin's default
+   branch.
+2. Every brief then tells the worker to merge the integration tip into its
+   branch before reporting (the fast-forward rule). That merge is the only
+   one a worker makes, and only in this mode.
+3. Land each verified slice with `git merge --ff-only <slice-branch>` in the
+   integration checkout. Not a fast-forward (the tip moved since the worker
+   merged)? Resume the worker to merge again; never a merge commit of your own.
+4. `workit fanout check` gates against the integration branch; a slice whose
+   tip is on it reads as landed. When all have landed, ship the integration
+   branch as one PR (call the skill tool with `workit-ship`).
+
+## Stacks
+
+For stacked slices (`dependsOn` one parent): `workit stack plan <bottom> …
+<top>` once, then `workit stack sync` and `workit stack land`.

package/assets/skills/workit-implement/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: workit-implement
+description: Build a requested change in small verified steps - follow local patterns, run real checks with workit check, prove it on the running app, hand verification to a non-author. Use for implement, build, add a feature, make the change, code it.
+---
+
+# Implement and prove it works
+
+## Steps
+
+1. Read before writing: the files you will touch, their callers, and one
+   neighbour that already does something similar. Copy its patterns, names and
+   error handling. Repo rules (AGENTS.md, CLAUDE.md, lint config) win.
+2. On the default branch? Branch first: `workit git branch --kind feature --slug <s>` (host note: a Claude Code host-isolated worktree uses plain `git switch -c`).
+   Tracking it? Judge once: `workit policy assess --judge risk=normal behavior=yes
+   product-choice=no plan=no` (trivial and no for a mechanical fix). Already
+   judged? Cite the plan with `--ref <path>` or record the decision; don't re-judge.
+3. Small steps that each leave the tree green. Behavior change: write the
+   acceptance as Given/When/Then and see a test fail first (call the skill tool with `workit-bdd`).
+   Mechanical change: the existing checks are enough. No tautological tests:
+   a test must fail if the behavior breaks, never restate the implementation.
+4. Run the real checks, local-first: the targeted test or check for the file
+   you touched while you work, then the full configured set once at the end
+   (`workit check test`, plus `lint` and `typecheck` when the repo has them),
+   not after every edit. Heavy work runs under one machine-wide lease: an ad-hoc
+   suite is `workit check --heavy -- <cmd>`, never a hand-made flock; a busy
+   lease waits and names its holder (`workit lock status`). A tool warning is a finding: fix it in this PR in the right layer, or record the false positive with evidence; pre-existing ones get their own PR.
+5. Prove the feature on its real surface with the project's `verify-<app>`
+   skill; none yet? Write one (call the skill tool with `workit-verify-app`). Tests show branch behavior,
+   not that the feature works. The report carries what you observed: a UI
+   change a screenshot or console/network check (chrome devtools or
+   agent-browser), an API a quoted real response. App not runnable? Say so
+   plainly, never claim success.
+6. Commit: `workit git commit -m "<type>: <what>" -- <paths>` (or `--all`); Co-Authored-By goes in with `--trailer "Co-Authored-By: <name> <email>"`. Host note: a Workit worktree (`workit fanout worktree create`) takes `workit git --cwd <worktree> …`; a Claude Code host-isolated one (`.claude/worktrees/agent-<id>`) takes plain git (its SubagentStart text: isolation refuses a git wrapper). One file holding two changes: stage one change's hunks with `workit git stage --patch <file>` (a `git diff -- <file>` cut to them), then `workit git commit -m "<msg>" --staged` (exactly the index); a path staged in part commits only its staged hunks (`--whole` takes the file).
+   No endpoint named? Stop here and state the next command. Hand delivery to
+   ship, which pushes and opens the PR with its body shape (call the skill tool with `workit-ship`), only
+   when that was requested, or the request implies delivery and the effective
+   endpoint in `workit grant show` is `pr`, `green` or `merged`; `green` and
+   `merged` keep babysitting. Otherwise it is `commit`.
+7. Verify as far as the review lane asks (`workit policy assess`, `workit pr
+   status`). Lane none: no verdict. Lane self: after `workit check test` passes,
+   record `workit ledger verdict tests-verified --self --how "<what you ran>"`;
+   it reads self-reviewed, never verified, and is enough. Focused, full, high
+   risk or `verification: self|independent` merges: one fresh verifier per PR after the last push, its own host-derived session (Claude Code: the `verifier` agent with the `model` (and `effort`) of `workit models show --role verifier`; Codex:
+   the `verifier` agent; OpenCode: a child session; Pi: a supervised worker),
+   never a hand-minted id. Before saying done, reconcile
+   every named deliverable against the target checkout and observe it (for a push:
+   `workit verify-delivery push`).
+
+Independent slices that could run in parallel: fan them out (call the skill tool with `workit-fanout`).
+One `implementer` slice: `workit fanout worktree create <slice>` before spawning,
+then `workit fanout brief <slice>`; no host isolation (Workit's hooks confine it).
+
+Stay inline by default (workspace `delegation: inline-first`). Hand work off
+only past the thresholds: an explorer after about 3 tool calls or 10k tokens
+of searching, parallel writers for 2 or more disjoint units of about 100+
+lines each.
+
+## Example
+
+Bad: "Done - added the --since flag, tests pass." (no check ran this turn; the
+flag was never invoked)
+
+Good: "Added `--since`. measured: `workit check test` exit 0;
+`mytool log --since 2d` printed 3 entries against the fixture repo. inferred:
+the GitLab path behaves the same (not run). Handed to the verifier agent."
+
+## Check
+
+```sh
+workit check test   # then, when the endpoint was a push or beyond: workit verify-delivery push
+```

package/assets/skills/workit-retro/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: workit-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, failed/self verdicts, handoffs,
+     check runs, CI reruns, `skill.loaded` rows (skipped skills: routing).
+   - `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.** Friction a workit skill, verb or hook caused, or a rule for
+   agent behaviour, becomes an issue or PR on BrainerVirus/workit, not a host
+   memory (one host reads it). Never fork a local copy. Use a minimal synthetic
+   repro: no private repo name, path, code, ledger text, PR, thread or transcript.
+   Show the exact draft; once approved: `workit issue create --repo BrainerVirus/workit`.
+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** (save it under `workit dir retros`):
+   Accepted (proposed), Backlog, Dropped, each with its citations, enforcer
+   and reason. Each approved item becomes a slice to build (call the skill tool with `workit-implement`)
+   and ship (call the skill tool with `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/assets/skills/workit-retro/agents/openai.yaml

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

package/assets/skills/workit-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/assets/skills/workit-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/assets/skills/workit-review/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: workit-review
+description: Independent review of a diff, branch or PR - intent fidelity and standards as separate axes, test quality, blast radius - recorded as a non-author verdict. Use for review, code review, check this PR or MR, is this safe, blast radius.
+---
+
+# Review independently
+
+Review the candidate, never the author's summary of it. A session that wrote a
+commit on the branch cannot record a passing verdict: if that is you, hand the
+review to a fresh agent with its own host-derived session: Claude Code and
+Codex, the `reviewer` or `verifier` agent (`--session` and `--token` from SubagentStart);
+OpenCode, a child session; Pi, a supervised worker. On Claude Code pass the
+`model` and `effort` of `workit models show --role <verifier|reviewer>`. Never hand-mint one such
+as `<lead>-v1`: it is refused as `forged_session`.
+An author's `--self` verdict reads self-reviewed and never counts as
+independent; `type-check-only` never proves a behavior change.
+Depth follows the review lane in `workit pr status`: focused reads the diff and
+runs its tests; full also drives the real surface (verify-<app>). Review once
+per PR after its last push; a second pass on an unchanged head is waste.
+A stale verdict showing `reverify: focused (<files>)` in `workit pr status`: re-check only
+those files since the judged head and reuse green CI there (no fresh install, no full suite).
+
+1. Pin the candidate: `git rev-parse HEAD`, the base, `git diff <base>...HEAD`;
+   for a PR, `workit pr status --json` (checks, unresolved threads).
+2. Find the intent: acceptance criteria, spec, PR body, and the recorded
+   choices (`workit ledger list --type decision`).
+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 (`CODING_STANDARDS.md` when present),
+     then a smell baseline (unclear name, long function, duplicated logic,
+     leaky abstraction). Judgment only; lint owns nits.
+4. **Tests:** run suites under the heavy-check lease (`workit check test`,
+   `workit check --heavy -- <cmd>`); `workit test-audit --diff`. Would each new test fail if the
+   behavior broke? Triage the findings (call the skill tool with `workit-test-audit`). Every configured check (`packaging`
+   too) needs a run or green CI on the head, or `verified` is refused: see `pr status`.
+5. **Blast radius:** for each touched contract, caller, config or migration,
+   state the one fact it is safe because of and run the proof. Anything
+   unproven is labeled UNPROVEN, never assumed safe: `references/impact.md`.
+6. Each finding: file:line, severity (blocker, major, minor, nit), evidence
+   (hunk, test or command output), concrete fix. Introduced issues get fixed;
+   pre-existing ones become follow-ups; inconclusive ones escalate.
+7. Record the verdict:
+   `workit ledger verdict verified|failed|blocked --kind review --branch <b> --how "<what you ran and read>"`
+   under your own session (the one the lead or the hook gave you).
+8. **Bound the loop.** A failed verdict gets one fix round and one recheck of
+   the changed hunks. Still failing, or stuck: no third round; the lead spawns
+   a decider (call the skill tool with `workit-fanout`). A product choice goes to the user.
+9. **Harness note** (optional): friction caused by the repo or harness, not
+   the change (a flaky fixture, a missing check, a misleading doc or skill
+   line), goes on its own `Harness note:` line in the report and any PR
+   comment, never as a finding or in the verdict, so a later retro finds it.
+
+## Example
+
+Bad: "Error handling could be improved." (no place, no consequence, no proof)
+
+Good: "blocker - src/pay.ts:88: `catch {}` swallows the gateway's 402, so the
+order is marked paid. Repro: `workit check -- bun test pay.test.ts -t declined`
+fails with this diff. Fix: rethrow `PaymentDeclined`."
+
+## Check
+
+```sh
+workit ledger check --pr <n>   # accepted only when current, passing and independent
+```

package/assets/skills/workit-review/references/impact.md

@@ -0,0 +1,24 @@
+# Blast radius beyond the diff
+
+A small diff is not a small risk. For every surface the change touches, name
+the one fact it is safe because of and run the proof.
+
+1. List what the change touches: exported symbols and every caller
+   (`git grep -nw <symbol>`), shared state, wire or file formats, config keys,
+   migrations, CLI flags and outputs, public types.
+2. For each: the fact it is safe because of (a type boundary, an existing test
+   that covers the path, an unreachable branch, a version gate) and the command
+   that proves it.
+3. Run the proofs with `workit check -- <cmd>` so the result is observed.
+4. Anything you could not prove is a finding labeled UNPROVEN with what would
+   prove it. Never fold it into "looks safe".
+5. A fix belongs at the shared root (one guard that every caller passes
+   through), not copied per caller.
+
+Example note:
+
+| Surface | Safe because | Proof |
+| --- | --- | --- |
+| `parseRange()` (4 callers) | callers pass validated input; new branch only for `--since` | `workit check -- bun test range.test.ts` exit 0 |
+| `config.json` `since` key | additive, old readers ignore unknown keys | `workit check -- bun test config-compat.test.ts` exit 0 |
+| GitLab adapter | UNPROVEN - no fixture for relative dates | add a `gitlab/relative-since.json` fixture |

package/assets/skills/workit-shape/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: workit-shape
+description: Shape work before building - brainstorm, grill open choices with a recommended answer, challenge weak premises, slice into PRs, propose a spec/ADR only when it pays. Use for brainstorm, plan, spec, design, options, should we, grill me.
+---
+
+# Shape the work
+
+You own the facts; the user owns the choices. Read, run or prototype anything
+observable before you ask. Skip all of this for a precise, settled request.
+
+## 1. Classify out loud
+
+- **Spike** (can we / how does it work): answer with evidence. No files.
+- **Bounded** (change to an existing flow): a short design in chat, then build.
+- **Architectural** (new subsystem or interface, cross-repo, hard to reverse):
+  grill, then propose a record. Start light; escalate when a trigger fires.
+
+## 2. Challenge gently, first
+
+Challenge an unverified premise first; grill on the next turn, once it
+settles. Say you will check, then check. Right? Say so. Wrong? Name what makes
+sense in the idea, explain why it fails with evidence, and show the better way
+with an example. At most one high-stakes assumption per turn: ask that one
+question, then stop and wait. If you were wrong, say so with the proof. The
+teaching tone stays in chat; code, commits and docs stay plain.
+
+## 3. Diverge, then grill
+
+Several viable approaches? Lay out two or three genuinely different ones (no
+strawmen) with benefit, cost or risk, when each fits, and the smallest check
+that settles it; recommend one. Then ask the whole frontier of open decisions
+(every one whose prerequisites are settled), numbered, each with your answer:
+`Q1 - <title>: <question>. Recommended: <answer>, because <evidence>.`
+Dependent questions wait for the next round. If an authorized, reversible
+default works, state it and proceed. Done when the frontier is empty and
+nothing was silently assumed.
+
+## 4. Durable knowledge only when it pays
+
+Propose a record (never create one silently) when a trigger fires or the user
+asks: a spec for multi-slice, cross-repo or open-product-choice work; an ADR for
+a choice that is hard to reverse, surprising and a real trade-off; a glossary
+entry for a term you had to resolve; `.out-of-scope/<concept>.md` for a rejected
+request that will come back. A one-file mechanical fix gets none. Formats and
+triggers: `references/knowledge.md`. Record each settled choice once:
+`workit ledger decision "<what>" --why "<why>"`; cite a plan: `workit policy assess --ref <path>`.
+
+## 5. Slice as tracer bullets
+
+Each slice is a thin path through every layer, verifiable alone, one PR, one
+context window. Acceptance is Given/When/Then; make it tests (call the skill tool with `workit-bdd`).
+Dependent slices stack (`workit stack plan <bottom> ... <top>`); fan out
+independent ones (call the skill tool with `workit-fanout`). Plans record decisions, not code, in a file
+under `workit dir plans` (`references/slicing.md`). Diagrams and UI sketches
+only when they settle a choice: `references/diagrams.md`, `references/mockups.md`.
+
+Authorized to build? Continue into the build (call the skill tool with `workit-implement`). Do not ask
+for a separate plan approval or repeat "continue?".
+
+## Example
+
+Bad: "Should the cache use Redis or Postgres?" (the agent never looked).
+Good: "Q1 - Cache store: the stack already runs Postgres 16 (compose.yml) and
+peak load is ~50 rps (measured: last week's metrics export). Recommended: a
+Postgres table with a TTL column, because it adds no new service."
+
+## Check
+
+```sh
+workit ledger list --type decision   # every settled choice is recorded
+```

package/assets/skills/workit-shape/references/diagrams.md

@@ -0,0 +1,17 @@
+# Diagrams: only when one argues a decision
+
+Tables first, ASCII trees second, Mermaid only when a flow or architecture
+needs it. Flowchart, sequence, state or ER only. No renderer, no network.
+
+## Mermaid rules (v11)
+
+- Fence as ```` ```mermaid ```` with no prose inside the fence.
+- Quote labels containing punctuation: `A["input (x, y)"]`.
+- One direction per diagram (`TD` or `LR`); under twelve nodes.
+- Name actors exactly as the code names them.
+
+## Verify by reading
+
+Balanced quotes and brackets, every node reachable, labels match the spec's
+terms. If it cannot be verified by reading, delete it. One diagram that argues
+a decision, or none; never a diagram suite.

package/assets/skills/workit-shape/references/knowledge.md

@@ -0,0 +1,61 @@
+# Durable knowledge: when and how
+
+Default: nothing durable. Conversation, the ledger (`workit ledger`) and the
+code carry most work. Propose a record only when a trigger below fires or the
+user asks for one, say which trigger fired, and let the user decline.
+
+| Record | Trigger | Where |
+| --- | --- | --- |
+| Spec | more than one slice, crosses repos, or an open product choice a future reader must know | `docs/<topic>/spec.md` |
+| 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, found by 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)
+
+```md
+# <Topic> - spec
+## Problem        (what hurts, for whom, with evidence)
+## Decisions      (table: # | decision | why; link ledger rows)
+## Behavior       (Given/When/Then, one line each; these become test names)
+## Out of scope
+```
+Add `## Design` only for architectural work, and a diagram only when it argues
+a decision.
+
+## Plan
+
+Decisions, not code: per slice the branch, what it touches, its acceptance
+lines, how it is verified, and what it depends on. A plan several times longer
+than its spec is a transcript; cut it.
+
+## ADR
+
+```md
+# NNNN <decision in a few words>
+Status: accepted (YYYY-MM-DD)
+<1-3 sentences: the context, the choice, the trade-off accepted.>
+Considered: <option> - <why not>.
+```
+
+## Glossary entry
+
+```md
+**Verdict** - an independent pass/fail judgment on a branch head, recorded in the ledger.
+_Avoid_: approval, sign-off.
+```
+One or two sentences, project terms only, no implementation detail.
+
+## Out of scope
+
+One file per concept: the request, why it was declined, what would change the
+answer, links to the issues that asked for it. Check this directory before
+grilling a request that sounds familiar.

package/assets/skills/workit-shape/references/mockups.md

@@ -0,0 +1,15 @@
+# ASCII mockups before UI code
+
+Sketch, don't build. At most three genuinely different layout hypotheses,
+ASCII only, no code.
+
+1. Fix a legend (`┌─┐ │ └─┘ ░ ≈ [ ] ( )`); keep sketches 60-80 columns and
+   8-20 rows.
+2. Per hypothesis: regions, which existing components are reused (by their
+   real names) and which are new, the empty/loading/populated/error states,
+   and where navigation goes.
+3. Recommend one. Ask at most one question, then stop. Say when ASCII cannot
+   settle it (density, motion, brand) and a hi-fi prototype is needed.
+
+The sketch and the chosen option go into the spec only if a spec exists;
+otherwise they stay in the conversation.