rota

rota documentation

Public user guide for rota, a dev workflow for Claude Code and Codex, with OpenCode as a round worker: skills plus a single-binary CLI. Start with one agent: capture an item, build it, ship it. When you have several issues ready, an orchestrator agent hands them to worker agents and a gate checks every merge.

Contents

🚀 Getting started

  • Install: Homebrew, the install script, release binaries, the Claude Code plugin, upgrading, uninstalling
  • Getting started: install and run your first cycle
  • How it works: the two ways to use rota (orchestrator, workers, gate), plus how each skill connects to the artifacts it touches
  • Where coding agents go wrong: seven common mistakes, enforced checks, written rules and remaining gaps

Walkthroughs

🔄 Rounds

🧰 Skills

  • All skills: when to use each skill, and how they chain
  • /rota-capture: Record bugs, features and tasks in the backlog without starting work
  • /rota-brainstorm: Negotiate the design of one Major item before planning it
  • /rota-spike: Try one risky idea on a throwaway branch and keep only the finding
  • /rota-plan: Write a signed-off implementation plan with verifiable tasks
  • /rota-work: Build the next item in small commits, one verified task at a time
  • /rota-debug: Find the root cause of one bug, fix it atomically and prove it
  • /rota-review: Review a branch against its spec and conventions before it leaves
  • /rota-ship: Review, then open the PR or merge, linking items by ID
  • /rota-docs: Scaffold, update or reorganize the public docs
  • /rota-orchestrate: Run a parallel round: pick the slate, watch workers, merge their PRs
  • /rota-answer: Answer every decision a round is waiting on, one question at a time
  • /rota-learn: Save the session’s durable lessons to KNOWLEDGE.md
  • /rota-decide: Record a hard-boundary decision with explicit forbids and permits
  • /rota-init: Suggest config values from the repo and write the ones you confirm
  • /rota-bugreport: File rota’s own mistakes upstream, after your explicit yes
  • /rota-pause: Stop cleanly and leave a handoff note for the next session
  • /rota-vision: Turn an idea into milestones with dependencies and ready/blocked status
  • /rota-refactor: Review the architecture and file refactor issues; –map drafts the map
  • /rota-qa: Run product-level QA against the built artifact and score it
  • /rota-release: Cut a release: checklist, version bump, notes, tag, publish

📥 Capture and backlog

  • Capturing work: /rota-capture, mixed input, related links, detail files
  • Picking work: /rota-work (no argument), /rota-work --preview
  • Removing work: /rota-capture --remove, dry-run preview, batch removal, safety semantics

🔨 Execution

📦 Shipping

  • Review and ship: /rota-review single-pass review and /rota-ship gates (second-opinion, QA)
  • Product QA: /rota-qa per-target strategy files and the ship.qa gate
  • Rolling back a cycle: /rota-ship --undo guided rollback, dry-run preview, manual confirmation
  • Learning: /rota-learn and KNOWLEDGE.md, including --term <name> for the project Glossary
  • External knowledge: a shared git repo of platform and technology learnings, read and written by every project
  • Decisions: /rota-decide and hard-boundary commitments in DECISIONS.md

Vision and planning

⚙ Configuration

  • Configuration: every key in .rota/config.json and what it does
  • Autonomy levels: how off, roundtrip and auto change skill chaining
  • Issue backend: backlog on GitHub/GitLab issues, setup, labels, milestones, rota migrate issues
  • Umbrella mode: coordinator at umbrella, work in sub-repos (M02 V1)

📖 Reference

🤝 Contributing

⚖ Compare

Other

  • FAQ: common questions

Edit this page on GitHub