rota
Coding agents write fast. rota makes sure what they merge works.
Capture work as issues. rota hands them to Claude Code, Codex or OpenCode, reviews every branch and merges only what passes your tests, one issue at a time or a round in parallel. Lessons and decisions stay in the repo, so the next session starts ahead.
Website · Features · Quick start · How it works · Skills · Docs
⚡ Features
- Issues where you already keep them: BACKLOG.md, GitHub, GitLab, Jira, Linear
- Design before code: brainstorm, plan, spike
- Small, verified commits
- Every branch reviewed against its spec
- A merge gate: only green merges land
- Parallel rounds: an orchestrator plus workers, each in its own worktree
- Mix agents: Claude Code, Codex, OpenCode
- In your terminal: herdr or tmux, or subagents
- Several accounts, balanced
- Autonomy you choose: off, roundtrip, auto
- Memory that stays in the repo: knowledge, decisions, handoff notes
🚀 Quick start
One agent, one item at a time. You need git and Claude Code or Codex. No herdr, tmux, gh or second account. The steps below are written for Claude Code. In Codex, type $rota-capture where it says /rota-capture; see skills in Codex.
brew install l4ci/tap/rota # or: curl -fsSL https://raw.githubusercontent.com/l4ci/rota/main/install.sh | sh
rota skills install # adds the /rota-* skills to Claude Code and Codex
cd your-project && rota setup
rota setup asks the main config questions (backlog, isolation, merge strategy, autonomy, review and QA gates) and creates .rota/. Commit it. For scripts and CI, rota init does the same without asking and writes the defaults. Then, in Claude Code:
/rota-capture fix the login redirect loop; add a dark mode toggle
/rota-work # picks the next item, plans it, builds it in small commits
/rota-ship # reviews the branch, then opens a PR or merges
Install lists every way to get the binary (the script checks the sha256 and, if minisign is installed, the signature). Getting started walks through setup and the loop.
How each install route updates:
| Route | Update with |
|---|
| Claude Code plugin | claude plugin update rota@rota |
rota skills install | rota skills update |
npx skills add l4ci/rota | run it again |
| Homebrew or install script | rota update prints the command |
🔄 How it works
rota has two parts: skills, slash commands like /rota-work that tell the agent how to do a job well, and the rota CLI, which the skills call to do the bookkeeping and enforce the rules (who holds which issue, what may merge).
There are two ways to use it. The quick start above is the first; move to the second when several issues are ready at once.
1. One agent, one item at a time. You stay in the conversation.
/rota-capture → /rota-work → /rota-ship
write it down build it review, then PR or merge
2. A round: several agents in parallel. You stay available for questions.
┌─► worker ben ─► PR ─┐
issues ─► orchestrator ─┼─► worker dana ─► PR ─┼─► gate ─► main
└─► worker nia ─► PR ─┘
- Orchestrator: one agent that picks the next issues, hands them out, answers workers' questions, and merges. It asks you only for product decisions.
- Workers: agents that each take one issue in their own git worktree and terminal tab, build it, and open a PR. They never merge.
- Gate: the only merge path. It checks the PR is current and properly signed off, runs your full test suite on a scratch merge of the PR and the base, and merges only on a pass. A red result sends the PR back to its worker. With
test.fullWhere ci the suite runs in CI instead.
Both ways share a memory in .rota/: what the project has learned (KNOWLEDGE.md), the lines it must not cross (DECISIONS.md), and handoff notes, so a fresh session picks up where the last one stopped.
🧰 Skills
In the order you'd usually reach for them:
| When | Skill | What it does |
|---|
| Something to do | /rota-capture | Record bugs, features and tasks in the backlog without starting work |
| Not sure how | /rota-brainstorm, /rota-spike | Negotiate the design of one Major item before planning it; Try one risky idea on a throwaway branch and keep only the finding |
| Ready to build | /rota-plan, /rota-work | Write a signed-off implementation plan with verifiable tasks; Build the next item in small commits, one verified task at a time |
| Something broke | /rota-debug | Find the root cause of one bug, fix it atomically and prove it |
| Done | /rota-review, /rota-ship | Review a branch against its spec and conventions before it leaves; Review, then open the PR or merge, linking items by ID |
| Docs drifted | /rota-docs | Scaffold, update or reorganize the public docs |
| Many issues at once | /rota-orchestrate, /rota-answer | Run a parallel round: pick the slate, watch workers, merge their PRs; Answer every decision a round is waiting on, one question at a time |
| Worth remembering | /rota-learn, /rota-decide | Save the session's durable lessons to KNOWLEDGE.md; Record a hard-boundary decision with explicit forbids and permits |
| Fresh project | /rota-init | Suggest config values from the repo and write the ones you confirm |
| rota itself misbehaved | /rota-bugreport | File rota's own mistakes upstream, after your explicit yes |
| Out of context | /rota-pause | Stop cleanly and leave a handoff note for the next session |
| Bigger picture | /rota-vision, /rota-refactor, /rota-qa, /rota-release | Turn an idea into milestones with dependencies and ready/blocked status; Review the architecture and file refactor issues; --map drafts the map; Run product-level QA against the built artifact and score it; Cut a release: checklist, version bump, notes, tag, publish |
Every skill: skills. Settings: configuration.
⚖ How rota compares
See how rota compares to GSD, Superpowers, OpenSpec, ralph, Conductor, Orca, Vibe Kanban, Claude Squad, Gas Town, Octo and a bare Claude Code session.
📚 Docs
🤝 Contributing
Issues and PRs welcome; SCOPE.md says what rota does and how issues are judged. Run python3 test/validate-skills.py, bash test/doclint.sh and bash test/smoke.sh before a PR; add a smoke assertion when you touch a verb. Running a round on rota itself: contributing: rounds.
License
MIT
