rmplan Usage Guide

rmplan is an AI-powered project planning and execution system. It generates detailed plans from issues, executes them with automated agents, and tracks progress through complex multi-phase projects.

Core Concepts

Plans are YAML files with:

• Metadata (title, goal, priority, status, dependencies)
• Tasks with descriptions
• Research findings and implementation notes
• Progress tracking

Plan lifecycle: pending → in_progress → done (or cancelled/deferred)

MCP Integration

The rmplan MCP server provides tools and prompts for plan management. When the MCP server is available, use these capabilities:

MCP Prompts

Use prompts to initiate plan workflows:

Prompt	Purpose
generate-plan	Full workflow: research → collaborate → generate tasks
generate-plan-simple	Skip research, go directly to task generation
plan-questions	Collaborate with user to refine a plan
load-plan	Display plan and wait for user instructions
compact-plan	Summarize completed plan for archival

Using generate-plan prompt:

1. Load the prompt with a plan ID
2. Research the codebase relevant to the plan goal
3. Add findings to the plan's ## Implementation Guide section
4. Collaborate with the user by asking clarifying questions
5. Use update-plan-tasks tool to save generated tasks

MCP Tools

Tool	Purpose
get-plan	Retrieve plan details by ID or path
create-plan	Create a new plan file
update-plan-tasks	Update plan with generated tasks and details
update-plan-details	Update the generated section content
manage-plan-task	Add, update, or remove individual tasks
list-ready-plans	Find plans ready to execute

MCP Resources

Browse plan data via resources:

• rmplan://plans/list - All plans
• rmplan://plans/{planId} - Specific plan details
• rmplan://plans/ready - Ready-to-execute plans

CLI Commands

When MCP is not available, use the CLI:

Viewing Plans

# Show plan details
rmplan show 123
rmplan show 123 --short      # Brief summary
rmplan show 123 --full       # All progress notes

# List ready plans (dependencies satisfied)
rmplan ready
rmplan ready --priority high
rmplan ready --format json

Creating Plans

# Create stub for later generation
rmplan add "Feature title" --priority high

# Create with relationships
rmplan add "Subtask" --parent 100
rmplan add "Blocked task" --depends-on 101,102

# Create from GitHub issue
rmplan generate --issue 123 -- src/**/*.ts

Generating Plan Content

# Generate with research (default)
rmplan generate 123 -- src/**/*.ts

# Simple mode (skip research)
rmplan generate 123 --simple -- src/**/*.ts

# Print prompt to stdout (for manual use)
rmplan prompts generate-plan 123
rmplan prompts generate-plan-simple 123

Executing Plans

# Execute with automated agent
rmplan agent 123
rmplan agent 123 --executor claude-code

# Execute next ready plan
rmplan agent --next

# With workspace isolation
rmplan agent 123 --auto-workspace

Managing Tasks

# Add task
rmplan add-task 123 --title "Task title" --description "Details"

# Mark complete
rmplan done 123 --commit

# Update metadata
rmplan set 123 --status in_progress --priority high

Plan File Structure

Plans are stored in the configured tasks directory (default: tasks/):

---
id: 123
title: Implement feature
goal: Add capability X
status: pending
priority: high
parent: 100           # Parent plan ID
dependencies: [101]   # Blocking plan IDs
tasks:
  - title: Task 1
    description: Details
    done: false
---

<!-- rmplan-generated-start -->
## Implementation Guide

Research findings and implementation notes...
<!-- rmplan-generated-end -->

Workflow Patterns

Standard Plan Generation

1. Create stub: rmplan add "Feature" --issue https://github.com/...
2. Generate plan: Use generate-plan MCP prompt or rmplan generate
3. Research codebase and add findings
4. Collaborate on task breakdown
5. Save tasks with update-plan-tasks

Breaking Down Large Plans

When a plan is too large, create child plans:

• Use create-plan with parent field set
• Split by feature areas, not architectural layers
• Each child plan should deliver complete, testable functionality

CLI Prompts for External Tools

Print MCP prompt content to stdout for use with other tools:

# Print generate-plan prompt
rmplan prompts generate-plan 123

# Print simple generation prompt
rmplan prompts generate-plan-simple --plan 123

# Available prompts
rmplan prompts  # List all available prompts

Additional Resources

For detailed information, consult:

• references/mcp-tools.md - Complete MCP tool parameters and examples
• references/cli-commands.md - Full CLI command reference

For configuration and advanced features, see the main rmplan README.