roady

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 trust klarlabs-studio/tap        # first time only
brew install --cask klarlabs-studio/tap/roady     # or: go install github.com/felixgeelhaar/roady/cmd/roady@latest
roady demo                               # scaffolds a sample project + shows drift

Homebrew refuses to load a cask from a third-party tap it has not been told to trust, so the first install of anything from this tap needs brew trust klarlabs-studio/tap once — per machine, not per tool.

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 (deterministic by default; --ai emits a prompt for
#    your own model to run, then write the tasks back)
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.

Keeping people informed — without a UI

Two jobs a tracker normally does with an app, Roady does with generated artifacts and push notifications.

Coordination — who is on what:

roady task assign <task-id> alice
roady task mine                   # your tasks (ROADY_USER, git user.name, or USER)
roady task assigned alice         # someone else's
roady task unassigned             # work nobody owns

Add guardrails in .roady/policy.yaml:

max_wip_per_owner: 2       # cap in-progress work per person, not just per project
enforce_team_roles: true   # a viewer in team.yaml can no longer move tasks

Stakeholder reporting — a document, not a dashboard:

roady report                                # Markdown to stdout
roady report --since 7d                     # just this week's changes
roady report --format html -o status.html   # ~5KB, no scripts, no requests
roady report --format json | jq .risks      # machine-readable

The report carries progress, a forecast with its confidence interval, a risk register built from drift plus sticky debt, who is on what, and what changed. Commit it, email it, attach it to a PR, or publish it to a static host — nothing to install and nothing to log into. A completion estimate is withheld until there is enough velocity data to justify one.

Push it on a schedule:

roady notify add team-chat slack https://hooks.slack.com/services/...
roady notify digest --since 7d --dry-run    # preview
roady notify digest --since 7d              # send

One chat-sized summary instead of a message per task transition. Run it from cron or CI.

Gate CI on drift:

roady drift detect --fail-on high    # exits non-zero only for high + critical

Everything found is still printed; the threshold changes only the exit code. See docs/spec-to-pr.md for pull-request gating and opening follow-up issues after merge.

Audit — proving what happened:

roady audit trail task-42                          # evidence trail for one task
roady audit trail --agent claude-code --since 30d  # everything one agent did
roady audit trail --session <id>                   # everything one run did

Every event records the agent and session behind it, so "which agent worked on this, and what proves it?" has an answer. A trail reports hash-chain integrity, findings (a task marked done with no evidence, entries with no agent recorded), the task's doc:line citation back to the spec, and every recorded event. It exits non-zero when the chain fails verification, so it can gate CI.

Roady attests to a complete, tamper-evident record of what was asserted — not to who acted, since actor and agent are caller-supplied and never authenticated. See docs/audit-grc.md before quoting a trail to an auditor.

Roady runs no inference

Roady does not call language models. It assembles the context one needs and hands it back — you or your agent already has a model:

roady query "what is left to do?"        # prompt on stdout, pipeable
roady plan generate --ai --json          # the request as JSON for an agent

Requests that produce data Roady stores name the tool that accepts it (decompose_spec → roady_plan_update). No API key is needed for anything. See docs/prompts.md.

Nested sub-projects

One repository can host many Roady projects in parallel:

repo/
  .roady/                          # root project
  .roady/projects/feature-auth/    # named sub-project
  .roady/projects/feature-payments/

roady -P feature-auth init --template minimal
roady -P feature-auth task ready
ROADY_PROJECT=feature-auth roady status

Tasks, spec, plan, and state are namespaced per project. Coding agents switch context by passing --project / -P <name> (CLI) or project (MCP). Existing flat .roady/ repos stay unchanged. See docs/rfcs/0001-nested-projects.md.

What Roady is, and is not

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, cross-project org views, plugin syncers, fsnotify watch mode, an interactive TUI (roady dashboard), inline MCP App UIs rendered by your agent, 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).