@nicolasmirson/plan-mode-claude/README.md

Structured planning workflow for AI assistants with MCP integration

# Plan Mode Claude

A structured planning workflow for AI assistants with MCP (Model Context Protocol) integration. Design better software by planning first.

## Quick Start

1. **Install globally:**
   ```bash
   npm install -g @nicolasmirson/plan-mode-claude
   ```

2. **Add to your MCP configuration** (`.cursor/mcp.json`):
   ```json
   {
     "servers": {
       "plan-mode-claude": {
         "command": "plan-mode-claude"
       }
     }
   }
   ```

3. **Restart your editor** (Cursor/VS Code) to load the MCP server

4. **Start planning** with your AI assistant:
   ```
   "Enter plan mode and help me build a user authentication system"
   ```

## What is Plan Mode?

Plan Mode transforms how AI assistants work by requiring **structured planning before execution**:

1. 🧠 **Enter Plan Mode** - Switch to planning state
2. 📋 **Create Plan** - Define title and description
3. ➕ **Add Steps** - Break down into manageable tasks with priorities
4. ✅ **Review & Approve** - Present complete plan for approval
5. 🚀 **Execute** - Track progress through each step

## MCP Integration

Plan Mode Claude integrates seamlessly with editors through MCP:

### Available Tools

| Tool | Purpose | Usage |
|------|---------|-------|
| `enter_plan_mode` | Start planning session | AI automatically enters planning state |
| `create_plan` | Define plan title/description | `create_plan(title, description)` |
| `add_plan_step` | Add step with priority/dependencies | `add_plan_step(content, priority, deps)` |
| `exit_plan_mode` | Present plan for approval | Returns formatted plan for review |
| `update_step_status` | Track progress | `update_step_status(stepId, status)` |
| `get_plan_status` | Check current state | Shows plan overview and progress |

### MCP Configuration

#### Cursor Setup

Add to `.cursor/mcp.json`:
```json
{
  "servers": {
    "plan-mode-claude": {
      "command": "plan-mode-claude"
    }
  }
}
```

#### VS Code Setup

Add to your VS Code MCP configuration:
```json
{
  "mcp": {
    "servers": {
      "plan-mode-claude": {
        "command": "plan-mode-claude"
      }
    }
  }
}
```

#### Manual Configuration

If you need custom paths:
```json
{
  "servers": {
    "plan-mode-claude": {
      "command": "node",
      "args": ["/path/to/global/node_modules/@nicolasmirson/plan-mode-claude/bin/plan-mode-claude"]
    }
  }
}
```

## Example Workflow

Here's how a typical planning session works:

```
👤 User: "Enter plan mode and help me build a user authentication system"

🤖 AI: I've entered plan mode. Let me create a structured plan for building a user authentication system.

📋 Plan: "Build User Authentication System"
   Description: Implement secure login/signup with JWT tokens and password hashing

📝 Steps:
   1. [HIGH] Set up database schema for users
   2. [HIGH] Create password hashing utilities  
   3. [HIGH] Build signup endpoint with validation
   4. [HIGH] Build login endpoint with JWT generation
   5. [MEDIUM] Add JWT middleware for protected routes
   6. [MEDIUM] Create logout functionality
   7. [LOW] Add password reset flow

👤 User: "Looks good, let's proceed"

🤖 AI: Perfect! I'll start with step 1...
```

## Cursor Rules Integration

Plan Mode Claude automatically creates Cursor rules to optimize your AI assistant's behavior. After installation, you'll find enhanced planning prompts in `.cursor/rules/plan-mode-claude.mdc`.

## Programming API

For advanced users who want to integrate Plan Mode into their own applications:

```typescript
import { PlanManager } from '@nicolasmirson/plan-mode-claude';

const planManager = new PlanManager();

// Enter plan mode
planManager.enterPlanMode();

// Create a plan
const plan = planManager.createPlan(
  'Build User Authentication',
  'Implement secure login system with JWT tokens'
);

// Add steps with priorities and dependencies
const step1 = planManager.addStep('Set up database schema', 'high');
const step2 = planManager.addStep('Create login endpoint', 'high', [step1.id]);

// Handle approval workflow
planManager.setApprovalCallback(async (request) => {
  console.log('📋 Plan ready for review:');
  console.log(request.markdown);
  return { approved: true };
});

// Execute and track progress
const approval = await planManager.exitPlanMode();
if (approval.approved) {
  planManager.updateStepStatus(step1.id, 'in_progress');
  // ... implement step ...
  planManager.updateStepStatus(step1.id, 'completed');
}
```

## Core Features

- 🎯 **Structured Planning**: Break complex tasks into manageable steps
- ✅ **Approval Workflow**: Review plans before execution  
- 🔄 **Progress Tracking**: Monitor step completion in real-time
- 🔗 **Dependency Management**: Handle step dependencies with cycle detection
- 📊 **Priority Support**: Organize steps by priority (high/medium/low)
- 🎨 **Markdown Export**: Convert plans to readable format
- 🔌 **MCP Integration**: Native editor integration (Cursor, VS Code)
- 📝 **Cursor Rules**: Automatic setup of optimized AI prompts

## TypeScript Support

Full TypeScript support with comprehensive types:

```typescript
interface Plan {
  id: string;
  title: string;
  description: string;
  steps: PlanStep[];
  status: 'draft' | 'approved' | 'executing' | 'completed';
}

interface PlanStep {
  id: string;
  content: string;
  status: 'pending' | 'in_progress' | 'completed';
  priority: 'high' | 'medium' | 'low';
  dependencies?: string[];
}
```

## Troubleshooting

### MCP Server Not Loading

1. **Check global installation:**
   ```bash
   which plan-mode-claude
   # Should return: /usr/local/bin/plan-mode-claude or similar
   ```

2. **Verify MCP configuration:**
   - Ensure `.cursor/mcp.json` exists
   - Check JSON syntax is valid
   - Restart your editor after changes

3. **Test server manually:**
   ```bash
   plan-mode-claude
   # Should start without errors
   ```

### Tools Not Available

1. **Restart your editor** after installing
2. **Check MCP status** in your editor's MCP panel
3. **Verify permissions** - ensure the binary is executable

## License

MIT