A plugin for Claude Code and Codex · GitLab or GitHub
From rough ideas to merged, reviewed code. One sprint at a time.
Compasso turns what you have into a product brief, a backlog, an architecture and a roadmap. Then it builds each sprint story by story: failing tests first, scripts that stop bad work, review and security review, and a pull request on your tracker. You make the decisions; the agents do the work in between.
next sprint, with the roadmap re-placed at real velocity
Spec-driven planning
Every story is written before it is built: acceptance in Given/When/Then and the commands that verify it. A script checks sizes, dependencies and capacity before anything reaches the tracker.
Test-driven building
A tester agent writes failing tests first. The builder makes them pass with the smallest change and can never edit a test: the files are hashed.
Sprint-paced delivery
Only the next sprint gets stories. Each close measures what was done and re-places what is ahead, MVP first. The tracker always shows the truth.
Walkthrough
One product, from ideas to its first sprint
Meet Clinic Booking, a sample: a physiotherapy clinic with 6 therapists books every appointment by phone. Everything below was produced by Compasso's own scripts from the sample's files. Where a script stopped, you see it stop.
1
Start from what you have
/compasso:start
No sprint goal needed. Bring loose notes, a document, issues already on the tracker, or a running prototype. /compasso:start says where the product stands and runs the next step.
The clinic brings an interview with the owner and reception, three issues the owner opened, and a clickable prototype of the booking screens.
Interview, owner + reception
- ~70 appointments a day, all by phone
- reception: 3h a day on calls
- 1 in 8 patients just doesn't show up
- "we want online booking before the
January campaign"
github.com/example/clinic-booking · Issues
Patients should book online #1
Remind patients the day before #2
Waiting list for full days #3
2
Discover: the product brief
/compasso:discover
The planner asks questions in the conversation, then writes the brief: problem, users, measurable outcomes, what the MVP must prove, constraints and risks.
Security reads it first and gives its view of the data and access involved. Here it flagged that the appointment reason may hold health details.
You decide the answers and approve the brief. It reaches the default branch through a pull request, with a decision record.
.compasso/product/brief.md
## Outcomes
- At least 60% of appointments booked online
within 3 months.
- Missed appointments down from 12% to under 5%.
- Reception time on the phone cut by half.
## The MVP must prove
- Patients book a real free slot online, without
calling, and never into a double booking.
- A reminder email the day before reduces
missed appointments.
.compasso/records/product/discover.md
## Findings
- security: The appointment reason is free text
and may hold health details
→ Optional, staff-only, every read logged
- security: Booking without a confirmed email lets
anyone fill the calendar
→ A held booking expires after 15 minutes## Decisions
- Email reminders in the MVP, SMS after it (@rita)
- Data stays in an EU region (assumed)
3
Backlog: features and the MVP line
/compasso:backlog
The brief becomes features of at most half a sprint, with rough hours, dependencies and an explicit MVP line. A new repository starts with a walking skeleton, F-0.
A script checks every feature is complete and sized, that dependencies exist and form no cycle, and that the MVP depends only on MVP features. Features become tracker issues in no sprint.
backlog-check
note F-1 is sensitive: security writes its abuse cases when it is planned
note F-2 is sensitive: security writes its abuse cases when it is planned
note F-3 is sensitive: security writes its abuse cases when it is planned
MVP: 6 of 9 features, 136h (about 2 sprint(s) at 80h)
Everything: 200h
Feature
Hours
After
F-0 Walking skeleton
16
–
F-1 Staff sign-in and working hours
24
F-0
F-2 Book an appointment
32
F-1
F-3 Staff calendar
24
F-2
F-4 Email reminders
16
F-2
F-5 Cancel and reschedule
24
F-2
MVP line
F-6 SMS reminders
16
F-4
F-7 Waiting list
24
F-5
F-8 Owner's monthly report
24
F-3
4
Architect: the technical solution
/compasso:architect
Stack, components (each serving backlog features), integrations, data and its retention, observability, environments, and every decision with the alternatives it beat.
Gate The first draft of this sample stored patient data with no security control naming it. The check refused it; one line fixed it.
You decide after security's review: approve, or send it back.
architecture-check
ERROR personal data is stored but no security control covers it
$# concern: Personal and health data of patients
architecture-check: valid (4 components, 2 decisions)
.compasso/product/architecture.yaml
decisions:
- title: Double booking
choice: A unique constraint in Postgres
alternatives: [A lock in the app]
why: The database guarantees it even when
two requests arrive together
security:
- concern: Personal and health data of patients
control: Stored in the EU, encrypted at rest;
the reason visible to staff only; every
staff read logged (GDPR)
5
Roadmap: features into sprints
/compasso:roadmap
Features are placed by dependency and capacity, MVP first, one goal per sprint. The sprint that completes the MVP is marked; work after the line never enters it.
Later sprints stay as features. They are re-placed at every sprint close with the velocity the team really reached.
roadmap.sh propose
S1 · 72h of 80
F-0 Walking skeleton · 16h
F-1 Staff sign-in and working hours · 24h
F-2 Book an appointment · 32h
S2 (MVP) · 64h of 80
F-3 Staff calendar · 24h
F-4 Email reminders · 16h
F-5 Cancel and reschedule · 24h
S3 · 64h of 80
F-6 SMS reminders · 16h · after MVP
F-7 Waiting list · 24h · after MVP
F-8 Owner's monthly report · 24h · after MVP
6
Plan: the next sprint in one-day stories
/compasso:plan
The planner splits the sprint goal into an epic, features and stories of at most 8 hours. Each story has acceptance, the commands that verify it, the paths it touches, its dependencies and its owner.
Anything outside the plan a story waits for becomes a blocker, assigned to a person with step-by-step instructions: here, the email provider's token.
Gateplan-check refused the first plan: two stories without unit tests. Then it computes the waves that can run in parallel and the critical path.
You decide after security reviews the plan. It is merged as a pull request and pushed to the tracker: milestone, epic, features, sub-issues, estimates.
plan-check · first run
Errors:
- S-2: tests must include unit
- S-9: tests must include unit
key: S-7
title: Book a slot
as: a patient
want: to book a free slot with my name and email
so_that: my appointment is held for me
acceptance:
- Given a free slot, When I book it,
Then it is held for 15 minutes until I confirm
- Given two bookings of the same slot at once,
When both are saved, Then one succeeds and the
other is told the slot was just taken
verify: ["npm test -- booking"]
tests: [unit, e2e]
touches: ["app/api/bookings/**", "db/migrations/**"]
depends_on: [S-6]
estimate_h: 8
7
Build: every story, the same loop
/compasso:sprint
The sprint builds everything that can run now, in dependency order, side by side in separate worktrees when their paths don't overlap. A story waits until what it depends on is merged. Each story goes through the same seven steps. Here is S-7, Book a slot:
tester
Failing tests first. Unit and e2e from the acceptance, including two real transactions booking the same slot. The test files are hashed.
✗ holds a free slot for 15 minutes
✗ a second booking of the same slot gets 409
✗ a held slot is not offered
3 failing
builder
The smallest change that passes. A migration with a unique index on (therapist, start). The builder may never edit a test; a changed hash stops the run.
verify
Verify gate. Tests, lint, typecheck, build and the story's own npm test -- booking. All pass, or nothing goes to review.
coverage
Changed-line coverage: 91% (minimum 80%). Below it is a warning, never a block.
review
Review and security review, with a fix loop. Round 1: security found the 409 response leaked the other patient's booking id; the reviewer found local time in the hold expiry. Each fix goes tests-first. Round 2: clean. At most 3 rounds, then a person takes over.
record
Decision record and metrics committed with the story: findings, decisions, takeaways, tokens and minutes per agent.
ship
The pull request, closing the issue. A person merges by default; with risk-based approval, low-risk changes merge on their own. Nothing merges with an open security finding.
Pull request #31 · Book a slot
Closes #19
## Changes
- A free slot is held for 15 minutes on booking
- A second booking of the same slot gets 409
"This time was just taken"
- Held and booked slots are no longer offered
## How to test
1. `npm test -- booking`
## Review
- Reviewer: 1 finding fixed
- Security: 1 major fixed (round 2): the 409 no
longer includes another patient's booking id
- Coverage: 91% of changed lines (min 80%)
.compasso/records/S1/S-7.md
# S-7 · Book a slot · 2026-11-06
Run by @ana · Pull request #31
## Findings
- security: major: the 409 response included the
other patient's booking id
→ fixed in round 2: the response says only
that the slot was taken
- reviewer: minor: hold expiry used the server's
local time → fixed: UTC everywhere## Takeaways
- Test concurrent bookings with two real
transactions, not mocks
8
Close: what was done, and what is ahead
/compasso:sprint
When a feature's stories are merged, the tester writes e2e tests for its acceptance; failures become bugs under the feature. When every feature is done, the sprint closes:
a regression pass and a security pass over everything the sprint changed;
the test guide for business testers, whose results come back as bugs;
the sprint report: delivery, flow and waiting, quality, agent effort;
the roadmap re-placed with the velocity reached, then the next plan.
Sprint 1 delivered 50 hours of stories. At that pace the MVP needs one more sprint than planned, and Compasso says so on day one of sprint 2, not at the deadline.
You decide the capacity to plan with (the measured average is proposed), and the next sprint's goal.
roadmap.sh propose --start 2 --capacity 50
S2 · 40h of 50
F-3 Staff calendar · 24h
F-4 Email reminders · 16h
S3 (MVP) · 24h of 50
F-5 Cancel and reschedule · 24hS4 · 40h of 50
F-6 SMS reminders · 16h · after MVP
F-7 Waiting list · 24h · after MVPS5 · 24h of 50
F-8 Owner's monthly report · 24h · after MVP
One self-contained HTML page of the whole solution for the people who fund, use or approve it: the problem and goals, the functional and technical solution, observability, security, the decisions, the sprints and the next sprint's user stories with links to the tracker. Regenerate it whenever the plan changes.
The sprint loop is the beat of the product. The team loop is how several agents and the people around them share it without stepping on each other.
The sprint loop
Plan one-day stories, checked
Build stories in parallel, by dependency; each one: tests ✗ → code → verify → review ⟲ fix → PR
Finish features e2e on the acceptance
Close report · test guide
Refine roadmap at real velocity, then plan again
Only the next sprint has stories; the rest stays as features.
A story never builds on another's unmerged branch.
Bugs from e2e and testers join the sprint as work, not as surprises.
After the MVP sprint, /compasso:harden is offered: mutation, property-based, flaky and test-smell checks.
The team loop
A tech lead agent and developer agents, each in its own long-running session with its own tracker account, polling on a schedule. People answer questions and approve what needs a person.
Tech lead
Plans sprint 2. Every story names its developer: dev: ana, dev: ben.
You
Approve the plan and who gets what.
ana · every 60 min
Claims S-10 with a comment, so no other session builds it. Builds, opens pull request #41 with its findings, stops.
ben · every 60 min
Can't go on with S-12: writes one question of at most 250 characters, labels it needs::lead, moves to its next story.
Tech lead · every 30 min
Shows the question with a proposed answer, the bugs with no developer, and each developer's load.
You
Decide the answer. Ben picks it up at its next poll.
Tech lead · every 15 min
Reads #41: up to date, pipeline green, risk low. The approver agent checks it; it merges. A pull request that conflicts or fails goes back to its developer.
You
Approve or request changes on what got needs::approval: in production, migrations, sensitive paths, API contracts, low coverage.
Issue #24 · S-12 Move an appointment
benneeds::lead
Moving within 24h is refused by F-5. Should reception be allowed to move inside 24h on a patient's call?
tech leadproposed
Yes for reception, never for patients: reception handles the call and the rule stays for self-service.
