Workit

Multi-platform Workit workflow support for Cursor, OpenCode, Codex CLI/desktop, Pi, and the CLI. The hosts share one task contract and eight operation families while adapting authority and lifecycle behavior to the native surfaces each host documents.

Compact task continuity surfaces the newest decisions with bounded, redacted choice summaries; full records remain available through explicit inspection. For substantial work across repositories, keep each unfinished item's checkout, branch, requested deliverables and delivery endpoint in a concise checkpoint. Verify named deliverables and the requested destination result before reporting completion; a local commit does not prove a remote push.

Package	Purpose
OpenCode	Native plugin with fourteen method skills, ten tools (eight shared families plus read-only context and init apply), and provider-safe schemas
Cursor	MCP transport, one native hook dispatcher, one contract rule, and fourteen skills
Codex	Native plugin manifest, shared MCP transport, documented lifecycle hooks, and fourteen skills
Pi	Native npm extension with nine tools (eight shared families plus external action), fourteen skills, and session continuity
Shared MCP	Low-level transport for the eight core operation families
Shared core	Task, policy, evidence, finding, decision, worker, writer, and continuity state
CLI	Setup wizard (workit)

Install

Requires Node.js 24 or newer. The wizard detects your hosts, configures the OpenCode, Cursor, Codex and Pi installations you pick, and writes your global config and optional project files:

npx @brainervirus/workit-cli init

workit init is an interactive TTY wizard with a short basic path and optional advanced setup. Detected hosts are selected initially; unavailable hosts are disabled. Select all available, clear all, or pick individual hosts. Installation uses native package/plugin commands and shows the changes before applying them; it does not install the host applications or reload your running sessions.

Advanced setup edits workspace hosting and issue tracking independently, branch and commit policies, profiles/default profiles, and named release tracks. Narrow workspace globs override broader matches regardless of file order; equal-specificity ambiguity is reported. Choose inheritance to remove an override. Existing workspace choices and custom fields survive edits, including when changing the default tracker for new workspaces. GitHub and GitLab can both link YouTrack; GitHub Issues requires GitHub hosting.

GitHub and GitLab use gh auth login / glab auth login; Workit does not create or read separate VCS token files. YouTrack retains its permanent token. Existing VCS token files and templates stay untouched. Project setup defaults to No: press n to skip adding files when configuring from a parent folder containing multiple repositories. Press y only to add hygiene files and gitignore entries to the displayed directory. Locale keeps its existing selection until changed. workit doctor checks the configured installation.

YouTrack is optional and everything organization-specific comes from youtrack.json; there are no built-in hosts, issues or wording:

• baseUrl is required. Without it the token-create link is unavailable and the error names the config file.
• meetingIssue / meetingIssues choose the meeting issue(s); meetings mode asks for one when none is configured. Meeting time uses each entry's workItemText, else a global meetingWorkItemText, else Meetings.
• Work-item dates are a calendar day sent as that day's UTC midnight. "auto" means today in the process timezone (honouring TZ); an IANA timezone in youtrack.json overrides it. YouTrack context reports the effective zone as workTimezone: { timezone, source } (source is youtrack.json or process). Resolved youtrack.update / youtrack.meeting / youtrack.time actions (and workit action --preview) report workDate: { localDate, timezone, timezoneSource } beside the approval descriptor, never inside it, so an approval matches in any process timezone. An explicit epoch dateMs is labelled with its UTC day.
• Workit adds no greeting or @mention to comments. The text comes from the editable issue-update template (templates/issue-update.md in the config directory overrides the bundled neutral one); placeholders Workit does not fill, such as a legacy {{greetingSection}}, render empty.

Older configs load unchanged: a timezone in the global config.json, and defaultMention, greetings or greetingCutoff in youtrack.json, are ignored.

workit cutover is for migrating legacy installations.

Manual setup per tool:

OpenCode — native plugin

Run the wizard and select OpenCode, or add the plugin to opencode.json:

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

workit init writes that same npm package pin for published installs. A checkout/dev install may pin file://…/packages/workit-opencode/… instead. Do not pin into pnpm dlx or _npx cache paths — those break when the cache is cleared.

Requires OpenCode 1.18.30+ and Node.js 24+. One dual-entry artifact carries server() for V1 and setup() for OpenCode 2.0.3 with the same ten native tools, fourteen method skills and wk-* commands, question receipts, and direct-child delegation. The published plugin is a self-contained Node bundle (no runtime @opencode-ai/plugin or @opencode/plugin dependency).

Cursor — plugin, MCP transport, and hooks

Run the wizard and select Cursor: it registers the plugin, the MCP server, the session hook, the contract rule, and the fourteen skills.

Or add the published launcher to the Cursor MCP config:

{
  "mcpServers": {
    "workit": {
      "command": "npx",
      "args": [
        "-y",
        "--prefer-online",
        "--min-release-age=0",
        "--package=@brainervirus/workit-cursor@latest",
        "workit-cursor-mcp",
        "${workspaceFolder}"
      ]
    }
  }
}

@latest, --prefer-online, and --min-release-age=0 are intentional: the runtime resolves from npm at launch despite npm/cli#9765, where npx ignores scoped min-release-age-exclude settings. The wizard also copies the plugin into ~/.cursor/plugins/local/workit as a real directory (not a symlink into pnpm dlx/_npx caches). Requires Node.js 24+ and network access on first run. Plugin metadata lives under .cursor-plugin/ and is submission-ready for the Cursor Marketplace; it is not published there.

Codex CLI / desktop — plugin manifest and shared MCP

Select Codex in the wizard, or use its native marketplace installer:

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

The marketplace references the built npm package, so installation does not depend on unbuilt Git checkout artifacts. The plugin includes hooks and the shared MCP server. Native Codex permission and sandbox settings remain authoritative.

Reads run over MCP; mutations run CLI-driven because caller-unattested MCP cannot attest effects:

node_modules/.bin/workit <family> <action> --json --confirm
workit writer acquire --actor <session-id>   # bind a writer to this session

Requires Node.js 24+ and Codex CLI or desktop. The hook honors exactly the bound session and nothing else.

Pi — native extension

Install the package alongside the Pi peer dependency (Pi 0.85.1):

pi install npm:@brainervirus/workit-pi         # published package
pi install ./packages/workit-pi -l --approve   # this checkout (local development)

Pi discovers the extension and skills through the pi manifest section of the package (./dist/workit.js plus ./skills); see the Pi documentation for how your setup resolves extension packages. Requires Node.js 24+.

CLI — setup, task control, and diagnostics

npm i -g @brainervirus/workit-cli
# or run without installing:
npx @brainervirus/workit-cli init

workit init              # basic / advanced setup wizard
workit upgrade           # read-only package and config upgrade preview
workit upgrade --apply --confirm  # apply a reviewed preview
workit upgrade --cli --apply --confirm  # also update an existing global CLI
workit launch pi --auto-upgrade --  # update before starting Pi
workit doctor            # offline installation health report (--json for machines)
workit doctor --fix-lock # clear a stale .workit metadata lock (WORKFLOW_WORKSPACE_ROOT or cwd)
workit doctor --fix-lock --force [--yes]  # clear a lock whose owner cannot be verified
workit <family> <action> [--payload <json|@file|->] [--task <id>] [--confirm] [--json]
workit action <operation> --payload <JSON> [--preview] [--confirm] [--json]
workit handoff --task <id> [--json]
workit uninstall         # remove host registrations (keeps ~/.config/workit)

The packed CLI is a self-contained Node bundle; Node.js 24+ is required.

Upgrading a legacy install

workit doctor reports stale_install when a legacy selector or a local-dist install is behind the current runtime, or when OpenCode's frozen @latest package cache lags published workit-opencode, with the exact repair step; Cursor canonical @latest installs never fail on version metadata.

workit cutover preview [--hosts <hosts>] [--json]
workit cutover apply   [--hosts <hosts>] [--resolution k=v] [--confirm]
workit cutover rollback preview|apply <backupId> [--json] [--confirm]

Upgrades

workit upgrade checks the selected Workit registrations, queries npm, and previews targeted updates and supported configuration migrations. Use --hosts=opencode,cursor,codex,pi to limit the hosts. Applying requires --apply --confirm, backs up affected configuration under ~/.local/state/workit/upgrades/, rejects changed configuration, and verifies the requested installed version. Local checkout sources and intentional version pins remain unchanged. OpenCode JSONC configuration requires native inspection before an automatic update. --cli updates an existing global npm CLI install (--hosts=none targets only the CLI); for an ephemeral install, run npx @brainervirus/workit-cli@latest instead.

OpenCode 2.0.21 cannot target a server plugin with its plugin update command (verified in the official Docker image). Workit reports that limitation and preserves the OpenCode registration; it never falls back to updating every plugin or deleting caches. OpenCode package resolution remains host-owned. Cursor, Codex and Pi use their supported scoped update paths.

Automatic updates are opt-in: workit launch <host> --auto-upgrade -- <args> updates before starting that host. Stop other instances of the selected host first; Workit refuses to replace loaded plugins. A registry outage starts the unchanged installation with a visible warning; an installation or verification failure stops the launch. Native startup hooks do not run competing installers. This does not migrate task history, change host permissions, or change package pins. Re-run the preview after resolving a failure rather than blindly retrying.

What it provides

• Eight shared workit_* operation families: task, policy, evidence, finding, decision, worker, writer, and state.
• Fourteen canonical method skills: behavioral TDD, challenge, debug, handoff, implement, plan, review, babysit, blast-radius, deslop (policy-gated before pull requests), diagram, mockup, green-run, and steer.
• A <workit-contract> bootstrap marker carrying shared invariants.
• Host-native capability reporting that never fabricates authority, receipts, delegation tokens, or cross-process identity.

Mechanical tasks with a self-review requirement accept the lead's own fresh review evidence, with reviewContext matching the recording session. Independent review requirements still need a session distinct from the task creator and other evidence recorders.

task.list defaults to the 20 most recently updated active or paused tasks and returns a compact projection. Use status: "closed" or status: "all" with a limit of 1-50 for bounded history, then task.inspect for one task's details; omitting its view selects summary. Closed inspection uses the candidate captured at closure and never projects the checkout's current writer onto history.

Skills are reachable two ways: model-invoked automatically when the task fits, or explicitly via the available wk-* aliases (/wk-challenge, /wk-babysit, /wk-implement, /wk-plan, /wk-debug, and the rest) on OpenCode, Cursor, and Pi. On OpenCode, each alias asks the model to load its matching method skill; it does not chain to another alias, and a user skill with the same ID suppresses that Workit alias. Codex CLI has no slash path: invoke skills explicitly as $workit-<name> or from the /skills picker. Creating a PR does not auto-start babysit; babysit:true opts into PR-ready follow-up and does not authorize merge or release. A PR URL from a route Workit did not enforce can be babysat when the user asks, without claiming enforcement. Raw branch naming checks run only for direct, unquoted literal forms of git switch -c|--create|-C|--force-create, git checkout -b|-B, and git branch <name>. A recognized target that violates the current workspace policy is denied with a correction; compliant commands pass to the host. PR, worktree, compound, quoted, variable-expanded, wrapped, and other shell forms remain host-governed. Workit is not an OS sandbox, so use repository or provider controls when policy must cover unsupported shell forms.

Host surfaces

Each adapter maps the shared contract to what the host can actually attest.

Cursor

Cursor uses the shared MCP transport and one bounded native hook executable. AskQuestion is policy-only (agent_guided); session start and compaction are non-blocking; arbitrary shell writes, Tab edits, and stable subagent-stop identity are unavailable. Reviewer and investigator native delegation is read-only. Implementer delegation is unavailable because Cursor cannot attest writer identity or safely release a child writer. Cursor ships only rules/workit-contract.mdc, which documents the shared contract, exact workspace/session scope, read-only native delegation, and the surfaces Cursor cannot attest or block.

Codex CLI / desktop

Codex CLI and desktop use the same shared transport and native hook bundle; their surface qualification remains separate. Codex hooks provide bounded known-write guardrails and read-only/agent-guided subagent observations, but no native arbitrary-question receipt or attested writer delegation.

Pi

Pi loads @brainervirus/workit-pi through its native package manager and reads the package's pi.extensions and pi.skills manifest entries. The extension uses Pi's native session identity, confirmation UI, and known write/edit tool boundary with the shared core. Headless required decisions return needs_input; arbitrary shell writes remain agent-guided because Pi extensions are not an OS sandbox. Its bundled coordinator can launch fresh stock-Pi reviewer/investigator processes and explicitly scoped implementers; writer ownership is acquired only after native process observation, and cancellation timeouts remain uncertain until an exit is observed. Pi also exposes one child-disabled workit_worker_control host-orchestration tool for launch/cancel/reconcile; the shared core surface remains the eight workit_* operation families (the orchestration tool is adapter-owned, not a ninth family).

Worker dispatch

Hosts that can observe their own launch surface durably claim a worker's launch slot (persisted state dispatching) before spawning it, through the host-only core methods prepareWorkerDispatch and commitWorkerDispatch. Only the live reservation settles the claim exactly once: either the observed child session binds the worker as running, or the host attests that no child was ever created and the worker is recorded as stopped with no session. Ambiguous assignments, generic cancellation text, unsettled claims, and claims lost to a restart stay unresolved — blocking replacement, closure, and resume instead of being guessed — and a fresh managed launch without an attributable worker is denied before spawn. Assignment provenance identifies the current coordinator after a session resumes; the task creator's historical session is not an execution gate.

Configuration and boundaries

Host setup stays in the selected platform's native configuration. The shared MCP provider keeps read-only inspection usable without an attested caller and returns capability_unavailable for authority-sensitive mutations when the host cannot prove the caller boundary.

On Pi and the CLI, optional Git, hosting, YouTrack, and documentation effects use one-time approved action reservations and host-observed settlement on the existing host-owned effect surfaces. A concrete call must match the exact canonical operation/target/payload approved by the native host; prose or substring matches never authorize it. Missing credentials leave unrelated core work usable, while an uncertain remote outcome blocks blind retry. Pi uses native approval receipts; the CLI workit action route shows the exact descriptor and requires an interactive TTY confirmation. A headless CLI call (including --confirm without a TTY) returns needs_input, while the caller-unattested MCP surface keeps optional mutations unavailable. Time entries require a duration supplied or confirmed by the user.

For routine authorized branch and commit work, use native host Git/shell tools when managed coordination or outcome reconciliation is unnecessary. Inspect the target checkout's conventions first; native permissions apply. There is no need to start a Workit task just to commit, and a local commit does not require PR readiness or task-closure paperwork. Never switch execution paths to evade a denial or retry an uncertain managed effect. OpenCode V1 and V2 use native host tools for mutations; Workit exposes read-only workit_context and shared coordination tools, with no managed external-action executor. See the action reliability specification. Newly assessed bounded behavior changes keep behavioral checks and self-review. Security, data, public-contract and operational consequences, the thorough preference, and explicit project requirements still require stronger review; existing stored policies are not silently changed.

The task directory holds coordination state; it need not be a Git repository. Git and hosting actions accept cwd in their payload to select any existing checkout for that action, with no prior registration or shared parent required. The canonical target, relevant Git/remote state, and effective gh/glab account are checked again before a remote effect. The coordinator owns the Workit writer; an independently held writer in the target checkout remains a real conflict, and managed actions hold that checkout's Workit metadata lock through effect settlement so a writer cannot acquire mid-action. A metadata lock whose owner is gone (dead or reused pid) is reclaimed by the next write. A lock records its host plus, on Linux, its pid namespace and boot id; a lock from another host, container namespace, boot, or an older Workit version cannot be checked against this process table and is reclaimed only after a 10-minute TTL (a lock from the same host and pid namespace but an earlier boot is reclaimed at once). workit doctor warns when such an unverifiable lock has blocked writes for over 30 s and prints workit doctor --fix-lock --force --yes. A write that meets a live holder retries briefly (250 ms inside host plugins and the MCP server, 2 s in the CLI) and then returns the retryable busy code, never recovery_required. workit doctor warns about a stale lock and workit doctor --fix-lock clears it under the same reclaim guard writers use; --force (with --yes or an interactive confirmation) is the explicit escape hatch for a lock whose owner cannot be verified. New branch setup shows both the existing local base SHA and remote base SHA in its approval, rechecks them, and creates only from an approved commit. Workit does not reject Git-valid branch names or user commit messages on formatting grounds. OS tasks can run from non-Git directories; Git-only actions report unavailable when no checkout is selected.

Hosted merge rechecks the approved target immediately before the gh/glab merge call. Those APIs condition on the PR/MR source SHA but do not support an atomic target-branch condition, so a retarget after the recheck can still redirect the merge.

Workit's hosted hosting.pull_request action pre-binds the approved source SHA and verifies the provider PR head before reporting success. The provider create APIs accept a branch name, so a concurrent push could still create a request from a newer commit between the pre-check and the create call; that residual non-atomic source-SHA race is accepted (decision ae03c569).

hosting.delete_branch deletes a remote branch only when its live tip exactly matches the head of a merged PR/MR. It binds the branch, remote and merged PR to an approved action and uses Git's server-side --force-with-lease to refuse a changed tip even after the last read; it never guesses from Git ancestry after a squash merge.

Examples:

• context.read with { "kind": "release", "range": "HEAD~1...HEAD" }
• comment-only youtrack.update with { "issueId": "ABC-1", "markdown": "..." }
• changelog.apply with { "entries": [{ "category": "Added", "text": "..." }] }

OpenCode exposes the read-only workit_context tool with a flat payload. Pi and the CLI expose the read-only context.read operation for git, pr, youtrack, github_issue, gitlab_issue, changelog, release, and affected context. The tracker kinds return the same title/body/state triple through authenticated gh and glab (GitLab subgroups kept); they fail closed when the CLI is unavailable or not logged in. Release context includes a deterministic Markdown draft derived from the selected commits and changed files. Affected context identifies documentation files; an actual edit still uses the existing native editor (for example changelog.apply) with writer checks and host-observed evidence. The CLI can identify affected files but does not claim to edit them without its native action route. Context reads require no approval or writer and never change the checkout or Workit metadata. Cursor and Codex receive the same contexts as read-only MCP resources under workit://context/{kind}; the workspace always comes from the host-owned session context.

Candidate snapshots in Git workspaces use Git's ignore-aware file inventory, so ignored dependency/build trees are not recursively scanned; non-Git folders retain recursive inventory behavior.

Auto-approval (opt-in per workspace)

Branch, commit, push, PR, and merge approvals can run without questions once a workspace opts in. Add autoApprove (action classes, or true for all five) and vcs.account (required for push) to the workspace entry in ~/.config/workit/workspaces.json — absent means manual as before:

{ "name": "personal", "glob": "/home/you/projects/personal/**",
  "vcs": { "provider": "github", "account": "you" },
  "autoApprove": ["branch", "commit", "push", "pr", "merge"] }

When workspace globs overlap, Workit selects the match with the most literal path components. Equally specific matches require an explicit workspace name.

Each auto action still records a reservation with the exact binding; the standing rule is re-read live, so removing the flag restores questions immediately. A git.commit plan list (plan_steps/plan_branch) also records with no question and returns its commit count. Guardrails are code, not prose: protected branches never push, open PRs, or merge sources; push identity must match the area account; publish/release stay gated. Product decisions, waivers, and close outcomes still require a human.

Plan lists accept commit-message strings plus typed { "branch": "name" } and { "pr": true } steps. A later commit with the same message or push of the same branch resolves its current Git target and is a new effect; retries of an uncertain local Git action reconcile the repository state before running again.

Development

bun run build
bun run check
bun run test:acceptance
bun run verify:release-candidate
bun run validate:cursor-marketplace

Release qualification uses frozen CA/E fixtures (test/acceptance/), a generated host capability matrix (docs/workit-v1/capabilities.md), and a stable gate that blocks publication on missing deterministic or live evidence. The 90-run live batch requires explicit authorization; see docs/workit-v1/qualification.md.

Published bundles are built with Bun and run on Node. The Cursor, OpenCode, Codex, and Pi package builds copy the fourteen canonical skills from packages/workit-core; no host-specific skill forks are maintained.

Repository layout

workit/
├── packages/
│   ├── workit-core/        # shared core, skills, and contract template
│   ├── workit-mcp/         # shared MCP transport
│   ├── workit-opencode/    # OpenCode plugin
│   ├── workit-cursor/      # Cursor MCP, hooks, rule, and skills
│   ├── workit-codex/       # Codex CLI/desktop MCP, hooks, and skills
│   ├── workit-pi/          # Pi native extension, bundled core, and skills
│   └── workit-cli/         # CLI setup wizard
├── .cursor-plugin/         # Marketplace metadata
└── test/                   # repository verification