roady

Roady

Roady is a planning-first system of record for software work. It acts as a durable, high-integrity memory layer between intent (what you want to build), plans (how you'll build it), and execution (the actual work).

Designed for individuals, teams, and AI agents, Roady ensures that your development roadmap never drifts from your original intent.

Key Features

• Spec-Driven Inference: Automatically derive functional specifications from multiple markdown documents (roady spec analyze).
• Adaptive AI Planning: Decompose high-level features into granular task graphs using OpenAI or local Ollama models (roady plan generate --ai).
• Deterministic Drift Detection: Instantly catch misalignments between docs, plans, and code reality (roady drift detect).
• Organizational Intelligence: Discover projects across your machine (roady discover) and get unified progress views (roady org status).
• AI Governance: Enforce policy-based token limits to control agentic spending.
• Immutable Audit Trails: Every action is cryptographically signed in a verifiable hash chain (roady audit verify).
• Continuous Automation: Watch documents for changes and sync task statuses via Git commit markers ([roady:task-id]).
• Interactive TUI: Real-time visibility into your project's health and velocity (roady dashboard).
• MCP First: Seamlessly expose planning capabilities to AI agents via the Model Context Protocol.

Quick Start

1. Installation

Homebrew (macOS/Linux):

brew install felixgeelhaar/tap/roady

Alternative (Go):

go install github.com/felixgeelhaar/roady/cmd/roady@latest

2. Initialize

roady init my-awesome-project

3. Plan your Intent

Put your PRDs or feature docs in docs/, then:

roady spec analyze docs/ --reconcile
roady plan generate --ai

4. Drive Execution

roady task start <task-id>
# Or automate via Git:
git commit -m "Implement core engine [roady:task-core-engine]"
roady git sync

5. Check Health & Forecast

roady status
roady drift detect
roady forecast

Governance & Policy

Configure project guardrails in .roady/policy.yaml:

max_wip: 3            # Limit concurrent tasks
allow_ai: true        # Enable AI planning
ai_provider: openai   # Use OpenAI or Ollama
ai_model: gpt-4o      # Your preferred model
token_limit: 50000    # Hard budget for AI operations

AI Integration (MCP)

Roady is a first-class MCP server. Add it to your claude_desktop_config.json:

{
  "mcpServers": {
    "roady": {
      "command": "roady",
      "args": ["mcp"]
    }
  }
}

Architecture

Roady is built on clean Domain-Driven Design (DDD) principles:

• Domain: Pure business logic for Specs, Plans, Drift, and Policy.
• Infrastructure: Modern Go stack using cobra, bubbletea, mcp-go, and fortify.
• Storage: Git-friendly YAML/JSON artifacts in .roady/.

License

MIT License. See LICENSE for details.