README
¶
Roady — the plan-of-record for AI coding agents
Spec, plan, and drift detection that survive context resets. File-based, git-versioned, MCP-native.
"With multiple Claude agents running in parallel, I'd lose track of specs, dependencies, and history." — verbatim from a 2026 Show HN thread.
You pair with Claude Code, Codex, Cursor, or Gemini on a multi-day feature. Three days in, the agent forgets what was decided, rewrites the wrong thing, or quietly drifts off-spec. Roady is the durable layer that holds the answer to what are we building, what's next, and where did reality diverge from the plan? — readable by you and writable by your agent.
See it in 60 seconds
brew install felixgeelhaar/tap/roady # or: go install github.com/felixgeelhaar/roady/cmd/roady@latest
roady demo # scaffolds a sample project + shows drift
The demo creates a roady-demo/ directory with a deliberately drifted
spec/plan, runs roady drift detect, and prints the next steps. Zero
prerequisites, zero AI keys, zero signup.
The actual workflow
# 1. Hook your agent to Roady (one command per supported tool)
roady setup claude-code # or claude-desktop, opencode, openai, gemini
# 2. Initialise + import your existing docs
roady init my-project
roady spec analyze docs/ # parses markdown, captures source citations
# 3. Generate a plan (heuristic by default; --ai for richer decomposition)
roady plan generate
roady plan approve
# 4. Drive execution from inside your AI editor
/roady-task # agent picks the next ready task
# ...agent implements, commits with [roady:task-id] marker...
roady git sync # state moves forward automatically
# 5. Ask the question that matters
roady drift detect # has reality diverged from intent?
Status, drift, and progress all show in roady status — including a
from doc:line citation for every task so the AI's choices stay
auditable.
What Roady is, and is not
| Roady is... | Roady is not... |
|---|---|
| The plan-of-record for an AI-paired feature | A Jira / Linear replacement |
Memory that survives /clear and session resets |
A chat history layer |
| File-based, git-friendly, local-first | A hosted SaaS (today) |
| MCP-native — every operation is a tool | A code-search or context-stuffing tool |
See docs/positioning.md for the full positioning,
ICP, and category claim.
How it compares
docs/vs.md — opinionated comparison vs Cursor rules,
Claude.md, spec-kit, Backlog.md, Linear, GitHub Projects.
Everything else
The headline workflow is intentionally short. Roady supports billing
rates, debt scoring, dependency graphs, multi-project org dashboards,
plugin syncers, fsnotify watch mode, web dashboards, D3 visualisations,
realtime SSE streaming, webhook + Slack notifications, and more — see
docs/advanced.md for the full catalogue grouped by
audience (solo dev / small team / org).
Roadmap
ROADMAP.md sketches what's next, including the planned
Roady Cloud open-core boundary (hosted MCP, multi-repo org
dashboard, audit retention, SOC2).
Contributing & license
Contributions welcome — open an issue or PR. MIT License, see LICENSE.
Maintainers: see docs/maintainer-setup.md
for the one-time GitHub repo settings the release pipeline depends on
(HOMEBREW_TAP_TOKEN secret, GitHub Pages source).
Built with cobra, bubbletea, mcp-go, fortify. Domain-driven Go
with pkg/domain / pkg/application / internal/infrastructure.
Architecture notes in the DDD docs (docs/ddd-insights.md,
docs/ddd-refactor-spec.md).
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
roady
command
|
|
|
roady-plugin-asana
command
|
|
|
roady-plugin-github
command
|
|
|
roady-plugin-jira
command
|
|
|
roady-plugin-linear
command
|
|
|
roady-plugin-mock
command
|
|
|
roady-plugin-notion
command
|
|
|
roady-plugin-trello
command
|
|
|
examples
|
|
|
sdk
command
Package main demonstrates how to use Roady as an SDK.
|
Package main demonstrates how to use Roady as an SDK. |
|
internal
|
|
|
infrastructure/messaging
Package messaging provides pluggable messaging adapter implementations.
|
Package messaging provides pluggable messaging adapter implementations. |
|
infrastructure/sse
Package sse provides Server-Sent Events streaming for roady events.
|
Package sse provides Server-Sent Events streaming for roady events. |
|
infrastructure/watch
Package watch provides filesystem watching with debounce support.
|
Package watch provides filesystem watching with debounce support. |
|
infrastructure/webhook
Package webhook provides outgoing webhook notification delivery.
|
Package webhook provides outgoing webhook notification delivery. |
|
pkg
|
|
|
application
Package application provides application services.
|
Package application provides application services. |
|
domain/analytics
Package analytics provides velocity and forecasting analytics for project planning.
|
Package analytics provides velocity and forecasting analytics for project planning. |
|
domain/debt
Package debt provides types for tracking and analyzing planning debt.
|
Package debt provides types for tracking and analyzing planning debt. |
|
domain/events
Package events defines domain events for event sourcing.
|
Package events defines domain events for event sourcing. |
|
domain/messaging
Package messaging defines the pluggable messaging adapter interface.
|
Package messaging defines the pluggable messaging adapter interface. |
|
domain/org
Package org provides organizational multi-project domain types.
|
Package org provides organizational multi-project domain types. |
|
domain/project
Package project provides aggregate coordination for Plan and ExecutionState.
|
Package project provides aggregate coordination for Plan and ExecutionState. |
|
infrastructure/dashboard
Package dashboard provides a web-based UI for Roady project management.
|
Package dashboard provides a web-based UI for Roady project management. |
|
infrastructure/webhook
Package webhook provides HTTP webhook server for receiving events from external systems.
|
Package webhook provides HTTP webhook server for receiving events from external systems. |
|
plugin
Package plugin provides plugin communication infrastructure.
|
Package plugin provides plugin communication infrastructure. |
|
plugin/contract
Package contract provides contract test assertions for Roady syncer plugins.
|
Package contract provides contract test assertions for Roady syncer plugins. |
|
sdk
Package sdk provides a typed Go client for the Roady MCP server.
|
Package sdk provides a typed Go client for the Roady MCP server. |