soroban

Soroban is a coding-agent extension and skillset — installable into Pi, Claude Code, Codex, or any Agent Skills-compatible harness — that teaches the agent a disciplined Beads (br) + Jujutsu (jj) workflow instead of leaving it to improvise one from scratch every session.

A soroban is also a Japanese abacus: beads on wires, slid one at a time, each movement doing exactly one unit of work before the next is allowed. Coding agents have no such discipline built in. Left to their own devices they either try to hold an entire problem in their head at once and blur the details, or plough through it fast and unreviewed. Soroban is the discipline imposed from outside: work broken into single beads, each one moved deliberately, tracked in Beads (br) and moved through review with Jujutsu (jj).

The problem this solves is laid out at length in Taming Jagged Intelligence with Beads and jj: agents are strikingly good at some things and strikingly bad at neighboring things in the very same breath, and no amount of clever prompting evens that out. What does work is packaging effort into pieces small enough that an agent's rough edges stop mattering, and keeping a human genuinely in the loop of review rather than rubber-stamping whatever comes back. That post describes the shape of the workflow; Soroban is what makes the workflow actually repeatable, so that shape doesn't have to be re-explained to every fresh agent session from scratch. Install soroban in your preferred coding agent:

• Pi (recommended): install the repository root as a Pi package. Pi discovers the skills plus TypeScript hooks, slash commands, and prompt templates that enforce and automate the workflow — the only host with hook-based enforcement, not just the skills.
• Claude Code or Codex: install every directory under skills/ into the host's Agent Skills. The same planning, hack, slip, workspace, and per-bead procedures work there through SKILL.md instructions, without loading any Pi-specific code.

The short, always-on machine rules live one level up, in /etc/nixos/home-manager/server/llms/global-core.md. The longer procedures live here, as skills loaded lazily on demand, so there is exactly one source of truth for the workflow no matter which agent is reading it.

Get started

Soroban teaches a workflow built on two external tools. Both are required on the machine that runs the agent, no matter which coding agent you install soroban into:

1. Install Beads (br). Soroban tracks every unit of work as a br issue — nothing here works without the br CLI on PATH.
2. Install Jujutsu (jj). Soroban moves work through review with jj, not raw git — the jj CLI must also be on PATH.
3. Install soroban in your preferred coding agent. Pi is recommended — it's the only host that also gains Pi's hook-based enforcement, on top of the same skills: Install in Pi. Claude Code and Codex get the same workflow through skills alone: Install in Claude Code or Codex.
4. Install every skill directory together, not a subset. Each first-level directory under skills/ is an independent Agent Skill, but soroban-hack and soroban-slip both depend on soroban-workflow, jj-workspaces, caveman, and the Beads planning/quality skills.

No package.json and no runtime npm install are required anywhere.

Install in Pi (recommended)

Add the absolute repository path to packages in ~/.pi/agent/settings.json:

"packages": ["/absolute/path/to/soroban"]

Local package sources load in place, and pi update skips them, so edits to this repository are not silently reset the way a git: package source would be. Run pi list afterward and confirm Soroban's extensions, skills, and prompts show up.

Install in Claude Code or Codex

Link each skill directory separately. Do not link the skills/ parent as a single skill, and do not point Claude Code or Codex at the repository root — those hosts should see the portable skills only, never Pi's extensions/ or prompts/.

Claude Code and Codex

Both discover user skills as symlinked directories — Claude Code under ~/.claude/skills/, Codex under ~/.agents/skills/. Point dest at whichever your host uses and link every skill directory in one shot:

soroban_dir=/absolute/path/to/soroban
dest=~/.claude/skills   # Codex: ~/.agents/skills
mkdir -p "$dest"
ln -s "$soroban_dir"/skills/*/ "$dest"/

If a destination already exists, inspect it before overwriting it — someone may have put it there on purpose. After installing, restart the host if its skill picker hasn't refreshed. Verify the install with:

test -r ~/.claude/skills/soroban-workflow/SKILL.md   # Claude Code
test -r ~/.agents/skills/soroban-workflow/SKILL.md  # Codex

Then open the host's skill picker (/skills where supported), explicitly select soroban-workflow, and ask it to describe the claim → work → close → squash sequence. Codex also accepts an explicit $soroban-workflow mention. Either way, the host should load the skill and describe the workflow without ever exposing extensions/ or prompts/ as skills of their own.

Vocabulary

Term	Meaning here
bead	One br issue — the smallest unit of trackable work
slip	Work exactly one bead, then stop and hand it back for review
hack	Work through the whole ready queue, bead after bead, without pausing

hack and slip are both ordinary English words that show up constantly in unrelated conversation, so Pi's trigger matching is deliberately stricter than a plain substring search — it looks for the workflow intent, not just the word.

Pi constraints

These are load-bearing rules for extensions/; they do not imply equivalent hooks exist in Claude Code or Codex.

• Never mutate systemPrompt. Doing so invalidates prefix prompt caching on Anthropic, DeepSeek, and OpenAI alike. Context injection goes through Pi's dedicated context hook instead.
• Keep tool_call cheap. Handlers run sequentially before every single tool call, so use regex there and nothing heavier — no subprocesses, no file I/O.
• Shell out only through pi.exec. It is not a shell, and it does not reject on a non-zero exit, so always inspect result.code yourself.
• Never install npm dependencies at runtime. No native addons, no ambient package-manager writes.
• Warn, don't block. Enforcement reports problems; it never silently rewrites a user's command out from under them.
• Use br, not bd. This installation currently uses the br CLI.

Issue tracking

Soroban uses the Beads prefix sor. It does not maintain a tracked Beads export: br owns everything under .beads/, that directory is gitignored, and no br mutation ever produces a file worth committing. Pi serializes its own br calls behind an advisory lock, so two Pi sessions working the same repository can't erase each other's writes — but it never reads or writes Beads data on its own behalf.

Note that the br CLI referenced throughout is the beads_rust fork, not gastownhall/beads. Though many of these skills are probably compatible with the upstream, they haven't been tested. Check beads_rust's own docs/help for anything not covered here.