mirror-magi-meta-agent/docs/guides/AI_TO_STRUCTURED_PLAN_GUIDE.md

AI-powered development planning and execution system with Supabase integration

# 🤖➡️📋 AI-Generated to Structured Plan Workflow

*Streamlined workflow: Generate with AI → Structure externally → Validate → Execute*

---

## 🎯 Overview

The **streamlined workflow** allows you to:
1. **Generate plans** with any AI tool (ChatGPT, Claude, etc.)
2. **Structure them** externally into proper JSON format
3. **Validate structure** with our tool to ensure correctness
4. **Execute step-by-step** with specific Claude Code Max commands

This approach gives you full control over plan creation while ensuring perfect execution.

---

## 🚀 Step 1: Generate Comprehensive Plan with AI

### Use Any AI Assistant

Choose your preferred AI tool:
- ChatGPT
- Claude
- Gemini
- Perplexity
- Any other AI assistant

### Essential AI Prompt Template

```
I need a comprehensive development plan for: [YOUR PROJECT GOAL]

Please provide a detailed plan that includes:

1. PROJECT OVERVIEW
   - Clear goal statement
   - Key requirements and features needed
   - Technical approach/stack
   - User requirements (mobile-friendly, accessibility, etc.)

2. DEVELOPMENT PHASES
   For each phase, provide:
   - Phase name and purpose
   - Detailed description of what gets accomplished
   - List of specific tasks/components to build
   - Dependencies between tasks

3. SPECIFIC TASKS
   For each task, include:
   - Exact component/file names to create
   - Specific functionality to implement
   - Technical details (props, types, API endpoints)
   - Files that need to be created or modified
   - Dependencies on other tasks

4. VALIDATION & SUCCESS CRITERIA
   - How to test each component/feature
   - What success looks like for each task
   - Integration points to verify

Make this plan specific enough that a developer could implement it step-by-step without guessing about details.
```

### Tips for Better AI Plans

- **Be specific**: Include your exact tech stack (React 18, TypeScript 5, etc.)
- **Request file paths**: "Where should each file be created?"
- **Ask for order**: "What's the optimal implementation order?"
- **Include testing**: "How should each component be tested?"

---

## 📝 Step 2: Structure Your Plan Externally

### Convert AI Output to Required JSON Format

Take the AI-generated plan and structure it into this exact format:

```json
{
  "id": "plan_[timestamp]",
  "goal": "[Copy exact goal from AI plan]",
  "status": "ready",
  "created": "[Current ISO date]",
  "phases": [
    {
      "id": "phase_[timestamp]_1",
      "name": "[Phase name from AI]",
      "description": "[Phase description from AI]",
      "tasks": [
        {
          "id": "task_[timestamp]_001",
          "description": "[Specific task from AI]",
          "type": "[task_type]",
          "dependencies": [],
          "specifics": {
            "componentName": "[If component]",
            "filePath": "[Exact file path]",
            "additionalDetails": "[Any specifics]"
          }
        }
      ]
    }
  ]
}
```

### Required Fields Checklist

✅ **Plan Level**:
- `id` - Unique plan identifier (e.g., `plan_1703089234567`)
- `goal` - Clear project goal statement
- `phases` - Array of development phases

✅ **Phase Level**:
- `id` - Unique phase identifier
- `name` - Phase name
- `description` - What this phase accomplishes
- `tasks` - Array of tasks

✅ **Task Level**:
- `id` - Unique task identifier
- `description` - Specific task description
- `type` - Task type (see types below)
- `dependencies` - Array of task IDs (can be empty: `[]`)
- `specifics` - Object with implementation details (can be empty: `{}`)

### Valid Task Types

- `component_creation` - Building UI components
- `api_integration` - API connections and data fetching
- `configuration` - Config files, routing, build setup
- `testing_implementation` - Tests, validation, error handling
- `feature_development` - General functionality
- `styling_implementation` - CSS, design system
- `data_modeling` - Types, interfaces, data structures

---

## ✅ Step 3: Validate Your Plan

### Run the Validator

```bash
npm run plan:validate
```

### Validation Process

1. **Choose option 1**: "Validate new plan"
2. **Paste your JSON plan**
3. **Type "END"** on a new line to finish
4. **Review results**:
   - ✅ **VALID**: Ready for execution
   - ❌ **ERRORS**: Must fix before proceeding
   - ⚠️ **WARNINGS**: Recommended improvements

### Common Validation Errors

**Missing Required Fields**:
```json
// ❌ Wrong
{
  "description": "Build dashboard"
  // Missing: id, type, dependencies, specifics
}

// ✅ Correct
{
  "id": "task_123",
  "description": "Build dashboard",
  "type": "component_creation",
  "dependencies": [],
  "specifics": {}
}
```

**Invalid Dependencies**:
```json
// ❌ Wrong - references non-existent task
{
  "dependencies": ["task_does_not_exist"]
}

// ✅ Correct - references actual task ID
{
  "dependencies": ["task_123"]
}
```

---

## 🚀 Step 4: Execute with Claude Code Max

### Start Execution

Once validation passes:

```bash
npm run plan:continue
```

### Execution Loop

```bash
# 1. Get specific command
npm run plan:continue
# Copy the generated Claude Code Max command

# 2. Implement in Claude Code Max
# Paste command and let Claude implement

# 3. Mark task complete
node plan-project.js complete [task_id]

# 4. Get next command
npm run plan:continue

# Repeat until all tasks complete
```

### What You Get

Each command includes:
- Exact file names and paths
- Component structures
- Implementation details
- Validation steps
- Success criteria

No placeholders, no guessing - just specific instructions.

---

## 📊 Complete Example

### AI-Generated Plan (from ChatGPT)

```
PROJECT: User Dashboard with Analytics

PHASE 1: Foundation Setup
- Create main dashboard component
- Set up routing
- Basic layout structure

PHASE 2: Data Integration  
- Connect to analytics API
- Create data models
- Implement state management

PHASE 3: UI Components
- Build charts component
- Create settings panel
- Add notifications display
```

### Your Structured Version

```json
{
  "id": "plan_1703089234567",
  "goal": "Create a user dashboard with analytics charts, settings panel, and real-time notifications",
  "status": "ready",
  "created": "2024-12-20T14:30:00.000Z",
  "phases": [
    {
      "id": "phase_1703089234567_1",
      "name": "Foundation Setup",
      "description": "Create basic dashboard structure and routing",
      "tasks": [
        {
          "id": "task_1703089234567_001",
          "description": "Create UserDashboard main component with responsive layout",
          "type": "component_creation",
          "dependencies": [],
          "specifics": {
            "componentName": "UserDashboard",
            "filePath": "src/components/UserDashboard.tsx",
            "props": {
              "user": "User",
              "analytics": "AnalyticsData"
            }
          }
        },
        {
          "id": "task_1703089234567_002", 
          "description": "Setup routing for /dashboard path",
          "type": "configuration",
          "dependencies": ["task_1703089234567_001"],
          "specifics": {
            "configFiles": ["src/App.tsx", "src/router/index.ts"],
            "routePath": "/dashboard"
          }
        }
      ]
    }
  ]
}
```

### Validation & Execution

```bash
# Validate
npm run plan:validate
# Paste JSON, type END
# ✅ PLAN IS VALID

# Execute
npm run plan:continue
# Get specific command for UserDashboard component
# Implement → Mark complete → Continue
```

---

## 💡 Best Practices

### For AI Generation
1. **Be specific** about tech stack and requirements
2. **Request file paths** for every component
3. **Ask for dependencies** between tasks
4. **Include testing criteria**

### For Structuring
1. **Use consistent IDs**: `task_timestamp_sequence`
2. **Keep descriptions actionable**: "Create X component with Y features"
3. **Group related tasks** in logical phases
4. **Specify all dependencies** explicitly

### For Validation
1. **Always validate** before starting execution
2. **Fix all errors** - warnings are optional
3. **Check task order** makes logical sense
4. **Ensure specifics** are detailed enough

### For Execution
1. **Complete tasks in order** - respect dependencies
2. **Test after each task** - use validation steps
3. **Mark complete immediately** - maintain progress
4. **Review generated commands** before implementing

---

## 🔧 Quick Reference

### Workflow Commands
```bash
npm run plan:validate    # Validate structure
npm run plan:continue    # Get next command
npm run plan:progress    # Check status
npm run plan:view        # See full plan
```

### Structure Template
```json
{
  "id": "plan_[timestamp]",
  "goal": "[project goal]",
  "status": "ready",
  "phases": [{
    "id": "phase_[timestamp]_[num]",
    "name": "[name]",
    "description": "[description]",
    "tasks": [{
      "id": "task_[timestamp]_[num]",
      "description": "[description]",
      "type": "[type]",
      "dependencies": [],
      "specifics": {}
    }]
  }]
}
```

---

## 🚀 Start Now

1. **Copy the AI prompt** above
2. **Generate your plan** with any AI
3. **Structure as JSON** using the template
4. **Validate** with `npm run plan:validate`
5. **Execute** with `npm run plan:continue`

---

*This streamlined workflow gives you the best of both worlds: AI creativity with structured execution.*