@brainervirus/workit Core

Workit

Workflow rails for agentic coding. The agent decides what to do; the workit CLI does the how (branch, commit, push, PR, CI, stack, merge) and records proof of what it observed. You stay in the loop for product judgment, not for checking whether the tests really ran or the push really landed.

One shared core ships as native integrations for Claude Code, OpenCode, Cursor, Codex CLI/desktop and Pi, plus a standalone CLI.

• Observed, not claimed. workit check runs your real test command and records the exit code, HEAD and tree. An agent saying "tests pass" is a note, not evidence.
• Author ≠ verifier. Verdicts are recorded per session in a SHA-keyed ledger; the session that wrote the code can never verify it.
• Bounded autonomy. Per-workspace grants decide how far an agent may go (push, PR, merge) without asking. Your host's permission prompts still win.
• No bookkeeping. Every branch is its own implicit task. Agents never manage ids.

Contents

• Quickstart
• Core concepts
• Daily workflow
• Skills
• CLI reference
• Upgrading
• Troubleshooting
• Contributing

Quickstart

Requires Node.js 24+. The setup wizard detects your hosts, installs the ones you pick with their native commands, and writes your global config:

npx @brainervirus/workit-cli init
workit doctor          # after a global install (npm i -g @brainervirus/workit-cli)
workit setup           # optional: let agents run Workit's delivery verbs without a prompt

workit setup shows the exact diff, asks once (--yes for a script, --dry-run to only look) and writes a Workit-owned block into each host's own permission config: enumerated workit git|pr|ci|stack|release|task|ledger|… verbs only, never workit check -- …, workit lock run -- … or workit grant. Run it in your own terminal, not from an agent session (it refuses there). workit uninstall removes exactly what it added, and workit doctor reports drift. Per-host details are in the hosts guide.

Or install a single host by hand:

claude plugin marketplace add BrainerVirus/workit
claude plugin install workit@workit
# update later with `workit upgrade`; the native fallback (Claude Code does not
# auto-update plugins by default):
claude plugin marketplace update workit && claude plugin update workit@workit

Pin to a local checkout instead (sources run with Bun, edits apply without a rebuild; disable the marketplace copy with claude plugin disable workit@workit):

bun install
bun packages/workit-claude-code/scripts/build.ts --skills-only
claude --plugin-dir "$PWD/packages/workit-claude-code"

Skills appear as /workit:<name>, plus verifier, reviewer and implementer agents. See the Claude Code guide.

{
  "$schema": "https://opencode.ai/config.json",
  "plugins": ["@brainervirus/workit-opencode"]
}

Update later with workit upgrade, which runs opencode plugin update @brainervirus/workit-opencode (only Workit; other plugins stay as they are; run it yourself as the fallback). OpenCode 2.x loads the new version live, with no restart.

Local pin: build once with bun packages/workit-opencode/scripts/build.ts, then use "plugins": ["file:///path/to/workit/packages/workit-opencode"].

Run npx @brainervirus/workit-cli init and select Cursor: it installs the plugin (MCP server, session hook, contract rule, skills). workit upgrade updates it, and reinstalls its plugin files when they are missing. Manual MCP setup is in the hosts guide.

codex plugin marketplace add https://github.com/BrainerVirus/workit.git
codex plugin add workit@workflow-toolkit

Update later with workit upgrade (it stops and restarts the Codex app-server daemon around the update and refreshes the Codex agent files). Skills are invoked as $workit-<name> or from the /skills picker.

pi install npm:@brainervirus/workit-pi
pi install ./packages/workit-pi -l --approve   # local checkout

Update later with workit upgrade (fallback: pi update --extension npm:@brainervirus/workit-pi).

npm i -g @brainervirus/workit-cli
workit help

Every verb works without a host; hosts just put workit and the skills in front of the agent.

Core concepts

Implicit task per branch. The first note, check, ledger record or commit on a branch creates its task; every task command without an id applies to it. State lives in the git common directory (.git/workit/, shared by all worktrees) as an append-only event log. workit task status shows it; workit handoff prints a resume brief.

Observed evidence (workit check). workit check test runs the configured command (from .workit/checks.json, else detected defaults such as <pm> run test, go test ./..., cargo test, pytest) and records exit code, HEAD and tree. Gates accept only a fresh passing run of a configured check; a check is stale once the worktree changes. Ad-hoc workit check -- <cmd> runs are recorded but never satisfy a gate.

Ledger verdicts (author ≠ verifier). workit ledger verdict records a result (verified, tests-verified, type-check-only, blocked, failed) for a branch head under the acting session. A verdict from the session that authored the commits is never accepted. Verdicts carry across rebases when the patch-id and diff are unchanged, and across docs-only follow-up pushes; one verdict at the top of a stack covers its unchanged lower PRs (carry-over). workit ledger check answers "is this head independently verified?".

Autonomy grants. Per-workspace grants in ~/.config/workit/workspaces.json set the ceiling: push, pr and rerun are allowed by default; merge needs true or verified, and both merge only with the verdict the PR's review lane asks for (an accepted independent one outside verification: proportional; true also allows a ledger-recorded --unverified --reason bypass); defaultEndpoint is where an unnamed delivery request stops: commit (default), pr (push and open the PR), green (open the PR, then babysit CI, review threads and required rebases until it is merge-ready, never merging) or merged (green, then workit pr merge; it acts as green until the workspace has the merge grant). Without the push or pr grant any of them acts as commit; workit grant show reports the effective endpoint. Raising a grant or the endpoint needs you at a terminal; agents can only lower them. See grants. workit workspace list|add|set adds or adjusts one entry without the wizard and never raises a grant (configuration).

Policy. Judge tracked work in four calls (workit policy assess --judge risk=trivial|normal|high behavior=yes|no product-choice=yes|no plan=yes|no, or the flat workit_policy tool fields) and Workit derives what it needs: nothing for trivial work, an observed workit check test and the verdict the change's review lane asks for, an independent live verdict and a plan for high risk. Under the default verification: "proportional" the lane comes from the diff: none (docs, comments, formatting, generated copies) needs no verdict, self (a small change off risk paths) the author's own --self verdict, focused and full (risk paths such as hooks, auth, release, migrations or the repo's own .workit/risk-paths, a lockfile, or a large diff) a non-author verdict, at task close, the Stop hook and the merge gate alike; when unsure, a file counts as a behavior change. workit pr status and workit policy assess show it. An open product choice or a needed plan blocks code edits until recorded, on every host with a pre-write hook (advisory on Codex). See verification. Host permissions (allow/ask/deny, sandbox) always stay authoritative; Workit adds no consent prompts of its own.

Release tracks. A repository with several release lines (say nun-develop -> nun-master and develop -> master) lists them under the workspace's releaseTracks; branch bases, PR targets, merge-back hints and protected branches then follow the line each branch belongs to. See release tracks.

Stacks. workit stack manages plain base-branch PR chains on GitHub and GitLab (no Graphite or gh stack needed): plan, restack after a merge, and land the contiguous verified run from the root. See delivery and stacks.

Daily workflow

shape  →  implement  →  review  →  ship
 │          │             │          └─ push, PR, CI green, land when granted
 │          │             └─ non-author verdict in the ledger
 │          └─ small steps, `workit check`, prove it on the running app
 └─ brainstorm, grill open choices, slice into PRs

1. Shape (/wk-shape, /workit:shape): agree what to build and how to slice it. A spec or ADR is proposed only when it pays off.
2. Implement: build in small steps; run workit check <name>; commit with workit git commit.
3. Review: a different session (the verifier/reviewer agent, or a reviewer started with its own WORKIT_SESSION_ID) records workit ledger verdict.
4. Ship: workit git push, workit pr create --issue <#n|ID> (links the issue on GitHub, GitLab or YouTrack), workit ci wait, workit pr status; workit pr merge only when the PR is READY, verified and the merge grant allows it, and then deletes the merged head branch (workspace deleteBranch, --keep-branch to opt out; never a protected, fork, stack-parent or foreign-author branch). workit verify-delivery confirms it landed.

For independent slices, fanout runs one worker per isolated worktree with a fixed brief and file-scope manifest, and a non-author verifier per slice. workit fanout plan refuses incomplete briefs and overlapping scopes before any spawn, workit fanout brief renders each worker's brief with the lead's standing orders (workit ledger standing; workers already running get each change on their next tool call, and standing add --stop tells them to stop and report), workit fanout status flags stuck workers and suggests a landing order, workit fanout worktree create|release gives each worker its own worktree on every host (with node_modules linked so its tests import its own code; Workit's hooks keep an implementer inside it), and workit fanout check gates fan-in. See parallel slices.

Skills

Skills load automatically when the task fits, or explicitly: /wk-<name> (OpenCode, Cursor, Pi), /workit:<name> (Claude Code), $workit-<name> (Codex).

CLI reference

workit help <command> [<subcommand>], or -h/--help anywhere after a command (before a bare --), prints its usage, flags and examples and runs nothing. A bare -- ends any command's options: after it -h is an ordinary value, and a command that takes no positional arguments refuses anything there (exit 2) before it runs. A value that starts with - goes as --flag=value (workit git commit --message=-h); -h right after a flag that takes a value is refused as ambiguous. A --flag a command does not take fails with exit 2 and an unblock naming the closest valid flag (or the right form: workit status points at workit task status, pr create --head at switching branches). Alternate spellings work: --fanout and --name both select a fanout plan, ledger verdict --sha <sha> is --head <sha> (the sha must be the head being judged), and task list --status all lists every task. Global flags: --json (envelope {"ok","code","data","error"?,"unblock"?}), --cwd <dir>, --version. Exit codes: 0 ok, 1 failed, 2 usage, 3 blocked, 4 busy/pending, 5 unavailable.

Upgrading

Upgrade every host together: newer store records are refused by older runtimes. workit upgrade shows a per-host plan, asks once, applies with a backup, and ends with a per-host table and doctor's verdict; --preview changes nothing, --yes skips the question.

Details and the skill rename table: migration guide.

Troubleshooting

More: configuration and storage.

Documentation

• Guides: Claude Code · Other hosts · Verification · Delivery and stacks · Grants · Configuration · Migration
• Design record: docs/workit-next/
• Release qualification: docs/qualification/
• History: docs/archive/ · CHANGELOG

Contributing

See CONTRIBUTING.md. Agent and maintainer conventions for this repository live in AGENTS.md, docs/agents/ and CODING_STANDARDS.md.

License

MIT