COMPASS · THE ENGINEERS
Not a chatbot. A fully-fledged engineer.
A Compass Manager works the way a good engineer works — on the practices a team already trusts, not a chat window bolted to a compiler. The habits that make software correct and reviewable are wired into every Manager from the first turn. Here is the whole set, and how each one is used.
HOW WORK SHIPS
Version control built for a fleet
Many Managers touch many repos at once. The version-control model has to keep that parallel work small, reviewable, and reversible — which is why Compass runs on Jujutsu, not plain git.
- Stacked pull requests
- The headline reason. A Manager lands a mountain of work as a stack of small, dependent pull requests instead of one wall of diff. You review each link in the chain on its own, and the stack merges bottom-up. Jujutsu makes stacking first-class, so a Manager keeps shipping up the stack without waiting on the review below it.
- A workspace per worker
- Every Manager works in its own colocated clone, and each worker it spawns gets its own Jujutsu workspace on top. Most agent dev environments hand an agent a single git worktree, scoped to one branch — a tree working in parallel needs many independent working copies at once. Jujutsu snapshots each one automatically, so nothing collides and nothing is lost to a missed commit.
- A clean, linear history
- Every change is a focused commit with a Conventional Commits subject and its issue reference on a trailer. History stays readable, and your tracker links the work back to the ticket without anyone wiring it up by hand.
- You decide what ships
- Managers open, review, and drive pull requests all the way to ready — but nothing lands until you approve it. You are the last word on every change the tree makes, always.
BEFORE IT REACHES YOU
Nothing merge-ready is unproven
Trust comes from gates a Manager cannot skip. Each one runs on every change before it is ever called ready for your merge.
- A mandated review loop
- Every pull request passes an adversarial review pass and CI before a Manager calls it merge-ready. The Manager fixes what the review finds and re-runs it — the loop closes itself, so nothing reaches you unreviewed.
- Behavior-driven, then test-driven
- Work starts by writing the behavior down as BDD scenarios (Given, When, Then) so the acceptance criteria are executable before any code exists. Underneath, each unit is test-driven red-green: a failing test first, then the change that turns it green. A bug fix ships with the regression test that proves it, written to fail before the fix and pass after.
DECIDE, THEN BUILD
The thinking is written down
Agents drift when the intent lives only in a chat log. Compass keeps the decision and the current behavior as durable, reviewable records.
- Design-doc-first
- Non-trivial work starts as a design doc pull request you review and merge. The merge freezes it, and the implementation executes against that frozen record — so you decide the shape of the work before a line of it is written.
- Living specs
- A behavior change updates its spec in the same pull request, OpenSpec-style, so the source of truth never drifts from the code. The next change diffs against a spec that is actually true.
- The right model for each phase
- A frozen design doc changes the economics of the whole cycle. Once the shape of the work is written down and merged, an implementer can compact its context to almost nothing and still stay on track — it is just following the record. That splits the cycle by cost: an expensive, high-reasoning model does the design and review, and cheaper models do the implementation against the frozen doc — scaled to the difficulty of the slice. You pick the model and thinking level for the Manager, the implementer, and the reviewer independently, so the spend lands where the judgment is.
None of this is a setting you turn on. It is how a Manager works before you ask.
RUNNING LEAN
Cheap to run
A tree of agents is only worth running if it stays cheap while it works. Two practices keep the cost down over a long night of building.
- Tight compaction
- Managers compact their context aggressively while their workers run. The work lives in the ephemeral subagents rather than the Manager's history, so a long-lived tree stays cheap. Built on oh-my-pi.
- Cheap coordination
- Agents talking to each other can burn more tokens than the work itself. Compass makes coordination cheap: a thread lock serializes the writers on a channel so no one re-reads a conversation that moved on, and a message-cost gate keeps a Manager from paying to say nothing. The comms layer is built to be talked over all night.
THE TOOLING FOUNDATION
Every repo, the same ground to stand on
An agent is only as reliable as the environment it runs in. A setup agent gives every repo a reproducible devenv/Nix environment — the foundation every Manager and worker builds, tests, and runs on.
- The same toolchain, pinned
- Compilers, language runtimes, linters, formatters, and every project binary are pinned to exact versions. A worker on one machine and a Manager on another resolve the identical toolchain — no "works on my box," no drift between the tree and you.
- Services and tasks, declared
- The environment carries more than binaries: databases and background services an agent can start, scripts and test tasks it can run, and git hooks that gate a push. An agent that enters a repo already has everything the work needs, wired and ready.
- One command in, reproducible out
- The environment loads on entry and is defined entirely in the repo, so it is versioned alongside the code it supports. Change the toolchain in a pull request and the whole tree picks it up — the reproducibility is itself reviewable.
Built the way you'd build it
The practices are the point. A Manager that stacks its PRs, proves its tests, and writes down its decisions is one you can actually hand the work to. Every practice on this page runs live in the Compass repo — the design docs, the specs, and the stacked pull requests are all there to read.