ayeo

Compass, from ayeo

Enough process for the work at hand. No more.

Spec-driven development gives every change the same process. Changing a label on a website gets the same spec, plan and review as moving to a new payments provider.

Compass is an open-source plugin for Claude Code. It assesses each change by risk, familiarity, size and goal, then picks an approach to match: what to write, what to check, and when to ask a human.

Install Compass Read the code on GitHub

Compass 7.0.0, released 20 October 2026. Free and open source under the Apache 2.0 licence.

One change, read four ways

Illustrative assessment, in the words Compass uses. RP-SHAPE-005 is the ID of the policy rule that picks the approach.

What engineering leaders can rely on

Compass gives a team one set of rules for how agents work. The rules live in the repository, next to the code they govern.

A person signs off on the irreversible
Work that is hard to undo, such as auth, payments, personal data and migrations, waits for a named person to approve it. This guardrail is locked: no setting or unlock removes it.
The same change gets the same process
The process comes from your policy, not from the agent. Each repository can extend a shared policy, and compass policy diff shows what a policy change allows or refuses.
Every change can be audited
Each change keeps its documents, approvals and test evidence in the repository. An approval records who approved, in what role and when.
Try it before you enforce it
With adoption: advisory, a failed check is reported but does not block, so a team can try Compass without slowing delivery. autonomy sets how often a session stops for a person.

1

Compass reads the change before it plans the work

Before Compass does anything else, it asks four questions about the change. What happens if this goes wrong? Is the affected code understood? How much delivery work is involved? What outcome is wanted?

The answers are words, not numbers. Risk runs from trivial to critical. Familiarity says whether the code is new, or existing code with or without scenarios: Given/When/Then tests that describe what it does now. Size runs from atomic to product. Goal is delivery or exploration.

This is the only place judgement enters. A person, or the agent, answers the four questions. Everything after that is computed, and the answers are written into the record so anyone can see what the process was built from.

The four dimensions and their words

Risk and size are ordered: a higher word means a tighter process. Familiarity and goal are plain choices.

2

A typo and an auth change get different processes

Put size along one axis and risk along the other and every change is a point. The shipped policy divides that plane into three approaches. Small and contained is a quick fix. Medium is regular, the default approach. Large work is full.

Some rules set a minimum approach, whatever the size. Compass calls them floors. A critical risk forces full. So does a label like auth, payments or migrations: domain risk overrides size, and a one-line auth change is not small.

A hotfix and a spike sit outside this plane. A live defect that is small enough gets reproduced and fixed first. Exploration gets a time box and ships nothing directly.

Size against risk, with the shipped approaches

Two of the four dimensions. Familiarity adds a floor of its own: on a medium or larger change to existing code with no scenarios, Compass writes the scenarios before the code changes.

3

The same stages every time, at a different depth

Every change goes through the same eight stages: assess, define, refine, plan, breakdown, implement, verify, ship. What the approach changes is how deep each stage goes. A stage can be thorough, lightweight or collapsed, which cuts it to one line, such as a plan that names the file to edit. Breakdown either splits the work across agents (multiagent) or is skipped.

A quick fix collapses refine and plan, skips breakdown and keeps verify light: one acceptance criterion, a focused change, and evidence that it works. A full approach runs every stage thoroughly and may split the work across several agents in parallel.

The stages stay recognisable whatever the depth, so a reviewer always knows where a piece of work is and what comes next.

How deep each stage goes

Depths from the shipped default policy in Compass 7.0.0. Your policy can change them, and compass approach evaluate --verbose prints the ones in force.

4

Hard rules stop the work. Good practice guides it.

Compass separates two things that process frameworks often confuse. Guardrails are few, hard and checkable. A guardrail is cleared only with evidence, and a breach stops the work. Strategies are strong defaults, like BDD, TDD and decision records, that apply when they add value and never block on their own.

The five default guardrails
G1 Tested before it lands. G2 Acceptance defined before it is built. G3 Traceability holds. G4 Evidence, not assertion. G5 A human signs off on the irreversible.
Strategies
Behaviour specs in Gherkin, red-then-green tests, architecture decision records, visual architecture models. Assessed at verify. They never block.
A change travelling to ship

Solid lines block until evidence opens them. Dotted lines guide and are assessed at verify.

5

Your team sets the rules, in one file

A payments team and an early-stage startup need different processes. The shipped default is a starting point. A team changes it in one file, compass.yml, and Compass shows whether each change makes the rules stricter or weaker.

Everything after the assessment is computed, not judged. The same four answers under the same policy produce the same approach, every time. So when a change gets a heavier process than you expected, you argue with the policy, not with the agent.

Some guardrails are locked. A team can add to them and can tighten them, but loosening one needs a recorded waiver, and human sign-off on the irreversible cannot be switched off at all.

One line in compass.yml, and what it does to the plane

compass policy diff compares two configurations and lists what one accepts that the other does not.

6

Anyone can see what was done and why

As the stages run, Compass writes the issue's documents into docs/compass/ and its manifest and evidence into .compass/work/. The record holds the decision, the approach including what was left out and why, only the documents the work justified, and the evidence behind each check.

That record is enough for another session, or another person, to pick the work up without the chat history. compass board render shows every issue on one page, with a lane for each stage.

Compass is built with Compass. Every pull request to it must pass compass ci, as its contributing guide says, and its architecture decision records are public.

The record growing as the stages pass

File names from the rate-limit example in the Compass repository. Open it to read the real documents.

Install it in Claude Code

Run these two commands inside Claude Code. You need Python 3.10 or later. The default guardrails work straight away; project setup is optional.

Compass does nothing in a repository until someone runs a Compass command there. It works on your machine and reaches the network only when you ask it to.

/plugin marketplace add ayeo-io/compass
/plugin install compass@compass

Then describe the work:

/compass:assess "Add rate limiting to the public API"

Compass answers the four questions, then computes the approach from the policy:

first approach  : regular  <- RP-SHAPE-005 (The default working shape.)
FINAL APPROACH  : regular
policy rules fired: none
parallel subtasks: up to 2 (a ceiling - breakdown sets the orchestration once the distribution map exists)
per-stage weight:
  assess     : thorough
  define     : thorough
  refine     : lightweight
  plan       : thorough
  breakdown  : multiagent
  implement  : thorough
  verify     : thorough
  ship       : thorough
gate set        : verify.correctness, verify.governance, verify.traceability, verify.regression, verify.clarity, verify.security

Real output of compass approach evaluate --verbose from Compass 7.0.0, for the assessment in the hero figure. The lines that repeat the assessment and name the policy file are left out.

Prefer source? Clone and install from GitHub. Compass sits alongside your CI. It doesn't replace your tests, linting or security scanning.

News and plans

All news

Before we build anything, we write the announcement and the FAQ as if it had already shipped. When we commit to one, it goes up here with its status, so you can see what's coming and tell us early if we've got it wrong.

Try it on your next change

Install Compass Read the docs