@workit-dev/cursor 0.0.1 → 1.0.0

package/skills/workit-architecture/agents/openai.yaml

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

package/skills/workit-architecture/references/instruction-files.md

@@ -0,0 +1,52 @@
+# Instruction-files mode (AGENTS.md, CLAUDE.md)
+
+Instruction files are paid for in every session that reads them. Restructure
+them in three escalating passes. Each pass is its own commit in one PR, in
+this order, so the user can keep pass 1 and drop pass 3. Run
+`workit knowledge lint` before pass 1 and after every commit: no commit adds
+a finding, and the lint exits 0 after the last pass, or the report lists the
+findings that remain and why.
+
+After each commit, run `workit check test`. A sentence a test pins stays,
+unless the user approves changing that test. Commit each pass with
+`workit git commit -m "<type>: <pass>" -- <paths>`, then open the PR
+(read the `workit-ship` skill's SKILL.md and follow it).
+
+Before pass 1, report the current byte counts and the plan for each pass, then
+wait for approval. A pass with nothing to do is skipped and said so, not
+padded.
+
+## Pass 1: remove no-ops
+
+Delete lines that would change no behavior if removed: "be thorough", "write
+clean code", "follow best practices", restated defaults of the host, notes
+about one past session, `path:line` references, and rules whose mistake a type,
+lint or check now prevents. Nothing moves in this pass; it only deletes.
+
+## Pass 2: progressive disclosure
+
+Keep the root file to what every session needs: commands, workflow, and
+"Read before <task>: <file>" pointers. Move topic detail (testing, release,
+hosts, architecture) into topic files under an existing docs folder, one file
+per topic, each opened by when to read it. Move text verbatim first; rewording
+belongs in pass 1 or a later change. Every pointer from AGENTS.md or
+CLAUDE.md must resolve (the lint's `broken-link` rule). The lint does not read
+topic files: check their own links and content by hand.
+
+## Pass 3: standards and checks
+
+- A judgment rule a reviewer must weigh goes to `CODING_STANDARDS.md`; the
+  root file keeps one pointer to it.
+- A mechanical rule (a forbidden import, a naming pattern, a file that must
+  exist) becomes a check instead of prose: a lint rule, a test, or a
+  configured `workit check <name>`. Show the check failing on a planted
+  violation, then delete the sentence.
+- No rule lives in two files (`duplicate-rule`).
+
+## Never
+
+- Create a file without its first real entry in the same commit. The lint
+  flags a scaffolded `CODING_STANDARDS.md` or `GLOSSARY.md` (`scaffold-file`);
+  for a topic file, that check is yours.
+- Squash the passes into one commit, or mix a behavior change into them.
+- Grow the root file past the lint's byte budget (`agents-budget`).

package/skills/workit-architecture/references/vocabulary.md

@@ -0,0 +1,53 @@
+# Deepening vocabulary
+
+Use these words exactly in every candidate. Do not drift into "component",
+"service", "API" or "boundary".
+
+| Term | Meaning |
+| --- | --- |
+| Module | Anything with an interface and an implementation: a function, a file, a package, a slice across tiers |
+| Interface | Everything a caller must know: types, invariants, ordering, error modes, configuration, cost |
+| Depth | Behavior a caller or test reaches per unit of interface learned. Deep: much behind little. Shallow: the interface is nearly as complex as the implementation |
+| Seam | Where behavior can change without editing that place; where an interface lives |
+| Adapter | A concrete thing that fills a seam (production, in-memory, fake) |
+| Leverage | What callers gain from depth: one implementation pays back across many call sites and tests |
+| Locality | What maintainers gain: change, bugs and verification concentrate in one place |
+
+## Tests to run on a suspect
+
+- **Deletion test.** Imagine deleting the module. Complexity vanishes: it was
+  a pass-through, so inline it. Complexity reappears across callers: it earns
+  its keep. A deepening concentrates complexity; it does not just move it.
+- **Interface is the test surface.** Tests that must reach past the interface
+  mean the module has the wrong shape.
+- **One adapter is a hypothetical seam; two are a real one.** Do not add a
+  port unless something varies across it (production and test count).
+
+## What the explorer looks for
+
+- One concept that needs a hop through many small modules to understand.
+- Shallow modules: wide interface, thin implementation.
+- Pure helpers extracted only for tests while the bugs live in how they are
+  called (no locality).
+- Coupled modules leaking through their seams: one fix edits both (churn shows
+  them changing together).
+- Code that is untested, or hard to test through its current interface.
+
+The explorer is read-only (on Claude Code, the Explore agent). It reads code,
+git history, `workit ledger list` and `workit test-audit` output only: never
+session transcripts and never another workspace. It copies no secret, token
+or personal data into its findings. It returns only cited findings (file,
+commit, ledger row), never a refactor.
+
+## Dependency categories (how the deeper module is tested)
+
+1. In-process (pure, in-memory): merge and test through the new interface.
+2. Local stand-in exists (temp dir, in-memory store): test with the stand-in;
+   the seam stays internal.
+3. Owned but remote (your own service): a port at the seam, an in-memory
+   adapter in tests.
+4. Third party: an injected port, a fake adapter in tests.
+
+Replace, do not layer. An old test on a shallow module is deleted only after
+naming the break it catches and showing that a test at the deeper interface
+fails on that planted break (read the `workit-test-audit` skill's SKILL.md and follow it). Until then it stays.

package/skills/workit-bdd/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: workit-bdd
+description: Turn requirements into Given/When/Then scenarios, agree the test seam, and work test-first in vertical RED/GREEN slices. Use for BDD, TDD, acceptance criteria, scenarios, Given/When/Then, write a test first.
+---
+
+# Behavior first: Given/When/Then
+
+1. **Write the scenarios.** One behavior each, in the caller's words:
+   `Given <state>, When <action>, Then <observable result>`. Include the
+   unhappy paths callers depend on (denied, empty, invalid, timeout).
+2. **Agree the seam.** The highest stable interface the scenario can be
+   observed through: a CLI verb, a public function, an HTTP route; ideally one
+   per feature. Do not test at a seam nobody agreed to. Note what each seam
+   catches and misses (a unit seam misses wiring; a CLI seam misses nothing
+   the user sees but runs slower) and cover each miss once, elsewhere.
+3. **Name tests after scenarios.** The name is the Given/When/Then sentence;
+   the body is arrange, act, assert. Expected values come from the scenario (a
+   literal from a worked example, the spec, an external contract), never from
+   the code under test. No tautological tests: a test must fail if the
+   behavior breaks, never restate the implementation.
+4. **Build in vertical slices, never horizontal ones** (every test first,
+   then every implementation: tests written ahead of any code assert guessed
+   internals). Write one vertical RED slice that fails for
+   the missing behavior and run it through the CLI so the failure is observed:
+   `workit check test`. Make the smallest change, run the same check GREEN,
+   then take the next scenario. Any edit makes the observation stale; re-run
+   before you claim it. A recorded "tests pass" is a note, and an ad-hoc
+   `workit check -- <cmd>` never satisfies the gate: only the configured
+   `test` check does. No `test` detected? Create `.workit/checks.json`, copying
+   in every check the repo already runs: once it exists it replaces the
+   detected defaults.
+5. **Mock only at system boundaries:** network, clock, randomness, other
+   processes, sometimes the filesystem. Never the unit or its own
+   collaborators; use the real thing or an in-memory adapter behind a port.
+6. **Gherkin only where the repo already uses it** (`.feature` files with
+   playwright-bdd, cucumber, jest-cucumber). Otherwise test names carry it.
+
+Reject noise: version-pin assertions, tests that mirror private structure,
+assertions inside a possibly-empty loop, smoke-only renders, duplicates. If a
+test still passes when every imported function returns `undefined`, rewrite it;
+the audit finds these (read the `workit-test-audit` skill's SKILL.md and follow it).
+
+## Example
+
+Bad: `test("calculateTotal works", () => expect(calculateTotal(items)).toBe(items.reduce((s, i) => s + i.price, 0)))`
+
+Good: `test("Given two items of 5 and 10, When totalled, Then the total is 15", () => expect(calculateTotal([{ price: 5 }, { price: 10 }])).toBe(15))`
+
+## Check
+
+```sh
+workit test-audit --diff && workit check test
+```

package/skills/workit-continue/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: workit-continue
+description: Keep work on track across interruptions and sessions - sort new input, checkpoint, hand off with a resume brief, and pick up by verifying inherited claims. Use for resume, pick up, handoff, new session, interruption, change of direction.
+---
+
+# Continue without losing the thread
+
+## New input mid-task
+
+- **Quick question:** answer it; change nothing else.
+- **Same-task adjustment:** update the affected constraint and next step, then
+  keep going.
+- **Separate request:** do not silently resume an old objective, and do not
+  drop the current one. Checkpoint it (below) if it must continue later, then
+  start the new work. Held items stay parked with their resume condition until
+  the user resumes them.
+
+## Checkpoint and hand off
+
+```sh
+workit git commit -m "wip: <state>" --all   # nothing lives only in your context
+workit handoff --note "<state in one line>" --next "<next command>" --record
+```
+
+The brief carries the branch, HEAD, dirty state, check freshness, verdict,
+rulings and the next command. Add only what it cannot know: choices still
+open, approaches that failed and why. Work spanning repos gets one brief per
+checkout, each with its branch and delivery endpoint. Notes too long for
+`--note` go in a file under `workit dir handoffs`; name its path in the note.
+
+## Pick up
+
+1. In the checkout: `workit handoff`, then `workit ledger list` and
+   `git log --oneline -10`.
+2. Trust the trail, verify the claims: re-run the checks the brief calls
+   stale, and confirm each "done" item against the goal on the real artifact
+   (a pushed SHA, a PR state, a running feature). Do not re-derive settled
+   decisions.
+3. Continue to the recorded endpoint with the brief's next command.
+
+## Example
+
+Bad: a new session re-reads the whole codebase, re-asks the user which
+approach to take, and redoes a finished slice.
+
+Good: "`workit handoff`: feature/usage at 4be1, `test` stale, verdict none,
+next `workit check test`. Re-ran it: exit 0. The brief says PR #42 is open:
+`workit pr status` confirms, CI pending. Continuing to ship (read the `workit-ship` skill's SKILL.md and follow it)."
+
+## Check
+
+```sh
+workit handoff   # read: "next command" is set and no check is listed as stale
+```

package/skills/workit-debug/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: workit-debug
+description: Find a root cause before patching - start from a red-capable deterministic repro, rank hypotheses, bisect regressions, fix at the root with a regression test. Use for bug, broken, failing, flaky, regression, error, why does.
+---
+
+# Debug from a red loop
+
+## Steps
+
+1. **Build the loop before any hypothesis.** One command that is red for the
+   user's exact symptom, deterministic, fast and runnable by you:
+   `workit check -- <repro>`. Shrink it until it fails in seconds. If the
+   symptom only shows on the running app, drive it with the project's
+   verify-<app> skill. No loop yet? Building it is the task; do not guess-patch.
+2. **Read the failure, not the summary:** the full error, the failing value,
+   and every caller on its path.
+3. **Rank three to five falsifiable hypotheses**, likeliest first. Test one at
+   a time with the loop or a tagged log line (`[DEBUG-<id>]`, removed at the
+   end with one grep). Keep a short hypothesis log so a dead idea stays dead.
+4. **Regression? Bisect it:** `git bisect start <bad> <good>` then
+   `git bisect run <repro>`. The first bad commit names the cause.
+5. **Fix at the root**, the one place every failing caller passes through.
+   Add a regression test at a seam that exercises the real bug pattern; if no
+   such seam exists, report that as a finding.
+6. **Stop rule:** after three dead hypotheses, write down what is measured and
+   what is inferred, widen the loop, or ask for the one fact only the user has.
+
+Every shipped line traces to evidence from the loop. A "might help" retry or
+guard is a hypothesis, not a fix.
+
+## Example
+
+Bad: "Probably a race; added a retry." (no repro, nothing measured)
+
+Good: "Repro: `workit check -- bun test lock.test.ts -t stale` red 10/10.
+H1 dead pid not reclaimed - confirmed: `kill(pid, 0)` throws EPERM for another
+user's pid and we treated it as dead. Fix: EPERM means alive. Loop green 10/10;
+regression test pins the EPERM case."
+
+## Check
+
+```sh
+workit check -- <repro>   # red before the fix, green after
+workit check test
+```

package/skills/workit-deslop/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: workit-deslop
+description: Remove AI slop before a PR - dead code, comments that restate the code, filler prose - with a minimal diff and identical behavior. Use for deslop, clean up, slop, tidy before PR, remove dead code, trim the PR body.
+---
+
+# Deslop code and prose
+
+Deslop removes; it never changes behavior. Its depth follows the review lane.
+
+1. **Scan first, no agent:** `workit deslop scan --diff [<base>] --json`. It
+   classes each added comment `narration`, `marker` (TODO, FIXME, HACK),
+   `suppression` (a lint or type disable with no reason), `debug` (stray logs,
+   `debugger`, `[DEBUG-` tags) or `allowed`, runs `test-audit` on changed
+   tests, and prints the lane and its passes. A marker or a lint/type
+   suppression raises `self` to `focused`.
+2. **Run the lane's passes** (each lane adds to the one below):
+   - `none` (docs only): prose. Cut filler and hedging from the PR body and
+     docs; keep real symbol names and before-to-after numbers.
+   - `self`: delete every narration, marker and debug finding, plus dead code
+     from the repo's tools (`knip`, `ts-prune`, `vulture`, unused-lint rules).
+   - `focused`: a fresh-eyes no-comments pass and a test-quality lens. Hand
+     the diff, never your verdict, to a fresh reviewer: Claude Code and Codex,
+     the `reviewer` agent; OpenCode, a child session; Cursor, a Task subagent
+     marked `ROLE: reviewer`; Pi, a supervised worker. It deletes every added
+     comment off the keep list and triages `workit test-audit --diff`
+     (read the `workit-test-audit` skill's SKILL.md and follow it).
+   - `full`: also `workit test-audit --mutate --diff` and one architect
+     sketch of the simpler shape, reported, not applied.
+3. **The keep list** (everything else goes): a licence header, an external
+   quirk (a library, OS or spec behaving oddly), `prettier-ignore` and other
+   tool directives, a lint suppression with its reason (`-- <why>`), public
+   API docs, an issue or RFC link.
+4. **No workaround comments for our own code.** Fix the root in a separate
+   `refactor:` commit, or open an issue that carries the explanation and
+   delete the comment. A "do not remove" note becomes a test, a type or a
+   lint rule.
+5. **Record one line per PR** when checks pass again:
+   `workit deslop result --removed <n> --reshapes <n> --open <n>` writes
+   `deslop: lane focused, -42 lines, 3 reshapes, 1 open` to the ledger.
+   Nothing to clean is a valid result (`--removed 0`). When a tracked task
+   lists a `pre-pr-cleanup` requirement (≤6.x tasks), this is its evidence.
+
+## Example
+
+Bad: keeping `// increment the counter` above `count += 1`, or deleting
+`// eslint-disable-next-line no-await-in-loop -- the API rate-limits parallel calls`.
+
+Good: the scan lists 6 narration, 1 marker and 1 bare `oxlint-disable`; the
+lane rises to focused; narration and the marker go, the disable gains its
+reason, a fresh reviewer drops two more comments, and a call-order assertion
+on an internal mock becomes a result assertion:
+`deslop: lane focused, -42 lines, 1 reshapes, 0 open`.
+
+## Check
+
+```sh
+workit deslop scan --diff && workit check test && workit deslop result --removed <n>
+```

package/skills/workit-fanout/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: workit-fanout
+description: Run independent slices in parallel - one worker per isolated worktree with a fixed brief and file-scope manifest, a non-author verifier per slice, results in the ledger. Use for fan out, parallelize, parallel agents, split the work, delegate, swarm.
+---
+
+# Fan out parallel workers
+
+Inline-first (workspace `delegation`): fan out only past a threshold, named as
+each slice's `reason` (explore, parallel, backstop, high-risk-verify): an
+explorer past ~3 tool calls or 10k tokens; parallel writers only for 2+ disjoint
+units of ~100+ lines each. Coupled work stays with one owner. Workit never spawns.
+
+1. **Plan the slices** (read the `workit-shape` skill's SKILL.md and follow it) in a plan file under `workit dir plans`
+   (`references/brief.md`): per slice an id, branch, REASON, TIER, SCOPE globs,
+   `owns` for shared files, `dependsOn` only for a real dependency, and the brief
+   fields. `workit fanout plan <plan.json>` refuses an empty or placeholder brief
+   field (exit 2) and two slices that may write one file (exit 3) with a fix; apply it and re-run:
+   refuse to spawn while a field is empty or the plan is refused. One PR per
+   slice is the default; `"fanIn": "integration"` only when the user wants one
+   PR (`references/orchestration.md`).
+2. **Record standing orders** (`workit ledger standing add "<order>"`): every
+   user directive all workers share. Directives decay across resumes.
+3. **Brief each worker verbatim**: `workit fanout worktree create <slice>`
+   (every host), then `workit fanout brief <slice>` (WORKTREE, SCRATCH, rules).
+   Never hand-edit it; change the plan or the standing orders and render again.
+4. **Spawn in a rolling window**, in the background, each in its own worktree:
+   keep 4-6 in flight and refill from `spawnable` in `workit fanout status` as
+   each one finishes. Assign before spawn (OpenCode: `workit worker assign`); each prompt carries
+   the brief, or a pointer: its `WORKER`, `TIER`, `TIMEBOX` and `WORKTREE` lines plus "run `workit fanout brief <slice>` and follow it"
+   (budget and model hooks read those lines), so batched OpenCode launches each bind their worker.
+   Model: the brief's `model:` and `effort:` lines (`workit models show`), else TIER (`references/orchestration.md`).
+   Claude Code: the `implementer` agent; its spawn hook drops `isolation` and refuses a prompt without a WORKTREE line.
+5. **Judge liveness by side effects only:** `workit fanout status` (head age,
+   PR, CI, verdict, landed; STUCK past the TIMEBOX). Stop a stuck worker and
+   observe that it exited (a timeout is not proof); stop a finished one when its
+   report arrives (Claude Code: TaskStop). Never two live workers on one branch.
+   Removing a worktree drops its uncommitted changes: `workit fanout worktree
+   release <slice>` records `git status` in the ledger and refuses without `--force`.
+6. **Retry once, then escalate.** A stuck or failed slice gets one retry with
+   a fresh brief (`workit fanout brief <slice> --mode resume`, same branch);
+   if that fails too, re-slice it, take it over, or report the gap. Never
+   chain resumes. A fix round and recheck that both fail: a decider, not a
+   third round; product choices go to the user (`references/orchestration.md`).
+7. **Verify by the workspace `verification` setting** (`workit grant show`).
+   A report is a pointer, never evidence. `proportional` (default): each slice's lane (`workit pr status`) decides; none needs no verdict, self the author's `--self`, focused and full a verifier (Claude Code: the `model` and `effort` of `workit models show --role verifier`) after the last push; one verdict at a stack's top covers its unchanged lower PRs, and a stale one with `reverify: focused` re-checks only the new diff, reusing green CI. `self`: a verifier that wrote none
+   of the slices, or you if you wrote none. `independent` or high risk: a
+   separate verifier session, never yours (doctrine: the ledger only refuses
+   authors). One verifier may take a batch of slices, one verdict per branch
+   (`workit ledger verdict <result> --branch <b> --how "<evidence>"`), in a
+   session never chosen by the author. Spawn it with the brief's `verifier:` model (`workit models show --role verifier`). A review panel on separate models only at high risk.
+8. **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. Fix what it names until it exits 0; a merged slice reads as
+   landed. Then `workit ledger check --branch <b>` per slice, land in `fanout
+   status` order, release the worktrees you made, and `workit ledger standing
+   clear`. Only you touch topology: workers never rebase, retarget or merge,
+   except the integration-tip merge in integration mode. Then ship
+   (read the `workit-ship` skill's SKILL.md and follow it) up to `defaultEndpoint` from `workit grant show`.
+
+## Example
+
+Bad brief: "Do the API part and add tests." (no scope, acceptance or verify command: nobody can tell when it is done)
+
+Good brief: the output of `workit fanout brief usage-endpoint` (`references/brief.md` shows one).
+
+## 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/workit-fanout/references/brief.md

@@ -0,0 +1,141 @@
+# Worker brief template
+
+`workit fanout brief <slice>` renders this brief from the plan, the standing
+orders in force (`workit ledger standing list`) and the slice's scratch dir;
+pass its output verbatim. The template below is what it fills in. Every field
+is required. A brief with an empty field is not spawned. Point to files and
+ledger rows instead of pasting their content. Size the slice so the worker
+finishes it in about 150k tokens of context; split a larger one first.
+
+```md
+MODE: <new | resume (a replacement continuing a branch with commits)>
+WORKER: <slice id: a spawn prompt that names it binds that worker on OpenCode>
+GOAL: <one observable outcome, in the user's terms>
+SCOPE: <file-scope manifest: the globs this worker may write; everything else is read-only>
+  branch: <type>/<slug>   base: <trunk or parent branch>
+CONTEXT: <pointers: spec section, ledger decisions, the neighbour file to imitate>
+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, N tool calls (hard: 180, else 120) and the call by which the full gates ran (60%); past it without a new commit you will be replaced>
+SCRATCH: <your own temp dir: the one `fanout worktree create` printed, else `mktemp -d`; never a shared path>
+FORBIDDEN: <no edits outside SCOPE; no new dependencies; ...>
+FAN-IN: <one PR per slice: no rebase, retarget, merge or force-push | integration: merge the integration tip before reporting, nothing else>
+REPORT: branch, head SHA, files changed, each VERIFY command with its exit code,
+  each ACCEPTANCE line met / not met, rulings you made (`workit ledger ruling`),
+  anything out of scope as a follow-up, not a diff.
+STANDING: <the standing orders, verbatim: `workit ledger standing add` records each one>
+WORKTREE: <the path `workit fanout worktree create <slice>` made; the worker runs `workit <verb> --cwd <it> …` there>
+  <identity line, per the lead's host: see "Identity and git rules per host" below>
+```
+
+## Worked example
+
+```md
+MODE: new
+WORKER: usage-endpoint
+GOAL: `GET /v1/usage` returns the workspace's run count per UTC day for the last 7 days.
+SCOPE: src/routes/usage.ts, src/queries/usage.ts, test/usage.test.ts
+  branch: feature/usage-endpoint   base: main
+CONTEXT: spec docs/usage/spec.md "Behavior"; ledger decision "counts are per UTC day";
+  imitate src/routes/runs.ts for auth and error shape.
+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, 120 tool calls (run your full VERIFY gates by call 72)
+SCRATCH: ~/.local/state/workit/worktrees/app/usage-endpoint/.workit-scratch
+FORBIDDEN: no edits outside SCOPE; no schema migration; no new packages
+FAN-IN: one PR per slice. Never rebase, retarget, merge or force-push: the lead owns topology.
+REPORT: as in the template
+STANDING: conventional commits; no comments that restate code; ask nothing, record rulings instead
+WORKTREE: ~/.local/state/workit/worktrees/app/usage-endpoint  (made by `workit fanout worktree create usage-endpoint`; yours alone)
+```
+
+## Plan file
+
+`workit fanout plan <plan.json>` (keep it in `workit dir plans`) 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 `<state>/worktrees/<repo>/<id>` (`workit dir state`). `owns` claims a shared
+file another slice's glob also matches. Globs that match no file yet are compared
+through a sample path. Use `/` as the separator; a backslash only escapes
+literal brackets: `"app/\\[id\\]/page.tsx"`. A `reason` (`explore`, `parallel`, `backstop` or `high-risk-verify`) is rendered as the brief's `REASON:` line and is
+required unless the workspace sets `delegation` to `lead-orchestrates`. A `timebox` such as `45 minutes`
+is the slice's STUCK threshold in `workit fanout status`. `"fanIn":
+"integration"` (with an integration branch as `trunk`) is the one-PR mode in
+`orchestration.md`; the default `"prs"` lands one PR per slice.
+
+```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"],
+      "reason": "parallel",
+      "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"]
+    }
+  ]
+}
+```
+
+## Identity and git rules per host
+
+`workit fanout brief` renders the identity line, the model lines and RULES 1
+and 3 for the worker's host: `--host <host>` (claude_code, codex, opencode,
+cursor, pi), else the lead's (`WORKIT_HOST`, or the host's own session
+variable). With no known host it warns on stderr and names the valid ones.
+RULE 3 carries the host's concrete Co-Authored-By line as a `--trailer`.
+
+| Lead's host | Identity line | RULES 1 and 3 |
+| --- | --- | --- |
+| Claude Code | `Session: your env already has WORKIT_SESSION_ID (the lead's id)`; no `export`, no hand-minted id (SubagentStart issues `<lead>:<agent id>` only to verifiers and reviewers, never to an implementer, so the worker's commits carry the lead's id) | `workit git branch <branch> --base <base>`, `workit git commit -m <msg> -- <paths in SCOPE>` in the Workit worktree (the spawn hook drops `isolation`); only a host-isolated `.claude/worktrees/agent-<id>` takes plain git, as its SubagentStart text says, since that isolation refuses a git wrapper |
+| OpenCode, Pi, Codex | `Session: your host already sets WORKIT_SESSION_ID in your shell`; export nothing (the host derives the id and an export cannot replace it) | `workit git branch <branch> --base <base>`, `workit git commit -m <msg> -- <paths in SCOPE>` |
+| Cursor, CI, a plain terminal | `export WORKIT_SESSION_ID=<lead>-w-<slice>` (`+try<n>` for a race attempt): declared, not checked | the same `workit git` forms |
+
+Once `workit fanout worktree create <slice>` made the worktree, the brief's
+WORKTREE line names it and RULES 1 and 3 run against it on every host:
+`workit git --cwd <worktree> commit …`, `workit check --cwd <worktree> <name>`,
+one verb per call. The worktree is already on the branch (MODE new or resume),
+so no branch command comes first. Without one, `MODE: resume` is
+`git switch <branch>` (the branch exists), then continue from its head. A race
+attempt (`--attempt <n>`) follows its host's row with the branch
+`<branch>-try<n>`.
+
+## Worker rules (`workit fanout brief` appends them as RULES)
+
+1. Work only in WORKTREE, already on the branch, one verb per call against it
+   (`workit <verb> --cwd <worktree> …`); Workit's hooks deny an implementer's change
+   outside it. With no worktree made yet: create the branch (`MODE: new`) or
+   `git switch` to it (`MODE: resume`), as the table above says.
+2. Decide ambiguities yourself and record them:
+   `workit ledger ruling "<what>" --why "<why>" --cost-if-wrong "<cost>"`.
+   Stop only for an irreversible action, a security-sensitive one, or a side
+   effect outside the worktree.
+3. Commit with `workit git --cwd <worktree> commit -m "<msg>" --trailer "<host's Co-Authored-By>" -- <paths in SCOPE>`;
+   push only if the brief says so.
+4. Never record a verdict on your own work.