A tool for managing project roadmaps, phases, and tasks as git-tracked markdown files — designed to be driven by your LLM coding assistant.

Work with your assistant to plan and implement large changes in a structured, repeatable way. You only need to allowlist a single CLI tool or MCP server. Plans are stored in a separate repo to keep your codebase free of planning artifacts.

rdm offers CLI, MCP, and REST interfaces.

Installation

# Quick install (Linux x86_64, macOS aarch64) — downloads a signed release binary
curl -fsSL https://github.com/edpaget/rdm/releases/latest/download/install.sh | sh

# Pin a specific release
curl -fsSL https://github.com/edpaget/rdm/releases/download/v0.6.2/install.sh | sh

# Homebrew (macOS)
brew install edpaget/rdm/rdm-cli

# npm / npx (macOS x64/arm64, Linux x64/arm64) — downloads the matching release binary on install
npx -y @edpaget/rdm mcp           # start the MCP server (default entry point for MCP clients)
npx -y @edpaget/rdm --help        # run any rdm CLI command without installing globally
npm install -g @edpaget/rdm       # or install globally so `rdm` is on PATH

# From source
cargo install --path rdm-cli

Open your coding assistant and ask it to run rdm --help and initialize the tool. Tell it whether you want to use the CLI or MCP server so it installs the correct prompts and configuration.

Manual Initialization

Initialize your plan repo:

rdm init

By default, rdm stores data in ~/.local/share/rdm (the XDG data directory). To use a custom location, pass --root:

rdm --root ~/Projects/my-plans init

Quick Start

If you initialized using your coding assistant, it should have prompted you to create a project. The examples below show what happens under the hood — you typically won't need to run these manually.

# Create a project
rdm project create fbm --title "Fantasy Baseball Manager"

# Create a roadmap with phases
rdm roadmap create two-way-players --project fbm --title "Two-Way Player Identity"
rdm phase create two-way-players/core-valuation --project fbm --title "Core valuation layer"
rdm phase create two-way-players/keeper-service --project fbm --title "Keeper service threading"

# Track progress
rdm phase update two-way-players/core-valuation --project fbm --status done
rdm roadmap show two-way-players --project fbm

# One-off work items
rdm task create fix-barrel-nulls --project fbm --title "Fix barrel column NULL for 2024" --priority high
rdm task update fix-barrel-nulls --project fbm --status done

AI Agent Integration

rdm is designed to work with AI coding agents. Instead of granting filesystem access to your plan repo, you allowlist the rdm binary or MCP server and the agent reads and writes roadmaps through the CLI.

CLI Agent Config

Generate instructions and skill definitions for your agent:

# Generate CLAUDE.md instructions for a target project
rdm agent-config claude --project fbm > ~/Projects/fbm/.claude/rdm.md

# Generate Claude Code skill definitions
rdm agent-config claude --skills --project fbm --out ~/Projects/fbm/.claude/skills/

rdm ships with Claude Code skills covering the full lifecycle: planning (rdm-roadmap), implementation (rdm-implement), task management (rdm-tasks), review (rdm-review), and documentation generation (rdm-document).

MCP Server

For agents that support Model Context Protocol, rdm exposes all operations as MCP tools — projects, roadmaps, phases, tasks, and search:

# Start the MCP server (stdio transport)
rdm mcp

# Generate MCP-oriented agent instructions (references MCP tool names instead of CLI commands)
rdm agent-config --mcp --project fbm --out ~/Projects/fbm

# Generate MCP-aware Claude Code skills + .mcp.json
rdm agent-config claude --mcp --skills --project fbm --out ~/Projects/fbm/.claude/skills/

Claude Code / Cursor / MCP Registry

Register rdm with Claude Code (uses the published npm package):

# User-scoped (available in every project)
claude mcp add rdm -- npx -y @edpaget/rdm mcp

# Or project-scoped (writes to .mcp.json in the current repo)
claude mcp add --scope project rdm -- npx -y @edpaget/rdm mcp

For Cursor, add the following to ~/.cursor/mcp.json (or the project-scoped .cursor/mcp.json):

{
  "mcpServers": {
    "rdm": {
      "command": "npx",
      "args": ["-y", "@edpaget/rdm", "mcp"]
    }
  }
}

rdm is also published to the MCP Registry under the canonical name io.github.edpaget/rdm.

Claude Code web sandbox

Run Claude Code web sessions against your plan repo from a source-repo sandbox. A session-start hook installs rdm, clones the plan repo into the sandbox, and points rdm's global config at it. Drop the template into your source repo:

# From a checkout of the rdm repo:
scripts/install-claude-code-web-template.sh /path/to/your/source-repo

See docs/claude-code-web.md for the full setup, required env vars, and troubleshooting.

Core Workflow: Plan, Implement, Done

rdm is built around a three-step cycle for shipping work incrementally.

Plan

Break work into roadmaps, each containing ordered phases. Phase bodies typically include context, implementation steps, and acceptance criteria — everything someone (or an AI agent) needs to start working.

rdm roadmap create search-feature --project fbm --title "Full-Text Search"
rdm phase create search-feature/indexing --project fbm --title "Build search index"
rdm phase create search-feature/query-api --project fbm --title "Query API endpoint"

For one-off work that doesn't warrant a full roadmap, create a task:

rdm task create fix-edge-case --project fbm --title "Handle empty query gracefully"

Implement

Work through phases in order. Read the spec, mark it in-progress, and build:

rdm phase show search-feature/indexing --project fbm
rdm phase update search-feature/indexing --project fbm --status in-progress

If you discover bugs or side-work during implementation, capture them as tasks rather than fixing inline:

rdm task create unicode-tokenizer --project fbm --title "Tokenizer breaks on CJK characters"

Done

When you commit the implementation, include a Done: line in the commit message:

feat(search): build inverted index for full-text search

Done: search-feature/indexing

Install the git hooks in your plan repo and they will automatically mark the phase done and record the commit SHA:

rdm hook install

The hooks parse Done: directives for both phases (Done: <roadmap>/<phase>) and tasks (Done: task/<slug>). This creates a traceable link from every completed item back to the commit that shipped it.

REST API

For programmatic integrations beyond the CLI, rdm serve starts a REST API that mirrors the CLI commands. See docs/rest-api.md for endpoints, content negotiation, and error format.

rdm serve --port 8400

Documentation

• File Formats — plan repo structure, YAML frontmatter reference, and field descriptions
• Architecture — crate layout, Store trait, and design overview
• Architectural Principles — the full set of design principles governing the codebase
• REST API — endpoint reference, content negotiation, and error format
• Bootstrap & Init — detailed guide to initializing and configuring a plan repo

Contributing

rdm uses Conventional Commits, TDD, and cargo nextest run for testing. See CLAUDE.md for development practices and build instructions.

Release prerequisites

The release workflow publishes the @edpaget/rdm npm package via npm trusted publishing (OIDC), so no long-lived NPM_TOKEN secret is required. Setup is one-time per package:

1. Create the @edpaget scope on npmjs.com (only needed once for the whole org).
2. Bootstrap the package: npm requires a Trusted Publisher to point at an existing package, so the very first release of @edpaget/rdm has to be published manually (npm publish --access public ...) or via a one-off token. Subsequent versions go through OIDC.
3. On the @edpaget/rdm package settings page → Trusted Publishers, add a publisher pointing at edpaget/rdm with workflow file release.yml, environment left blank.

Once that's in place, tagging a release triggers .github/workflows/release.yml, which dispatches to .github/workflows/publish-npm-oidc.yml and publishes with npm publish --provenance using the GitHub-issued OIDC token. The publish workflow also injects mcpName: io.github.edpaget/rdm into the published package.json so the MCP Registry can verify ownership.

Submitting to the MCP Registry

The first release that ships with mcpName in package.json unlocks the MCP Registry submission. This is a manual, one-time step (subsequent releases only need to be re-pushed to the registry if server.json changes):

1. Install the publisher CLI:

   brew install mcp-publisher

2. Bump server.json so its version (and the matching packages[].version) tracks the released npm version.
3. Authenticate with GitHub (interactive OAuth — claims the io.github.edpaget namespace):

   mcp-publisher login github

4. From the repo root, push server.json to the registry:

   mcp-publisher publish

License

This project is licensed under the GNU General Public License v3.0.