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

AI-powered development planning and execution system with Supabase integration

# 📋 Planning Workflow

*Streamlined workflow: AI generates → You structure → Validate → Execute → Git commits*

---

## 🎯 Overview

The meta-agent uses a **streamlined planning workflow** where you:
1. **Generate plans with AI** (ChatGPT, Claude, etc.)
2. **Structure them externally** into proper JSON format
3. **Validate structure** with our tool
4. **Execute step-by-step** with Claude Code Max
5. **Auto-commit changes** with meaningful messages from Claude

This workflow gives you the creative power of AI planning with the precision of structured execution and clean git history.

---

## 🚀 Step 1: Generate Plan with AI

### Use Any AI Assistant
- ChatGPT, Claude, Gemini, or any AI tool
- Generate comprehensive development plans
- Get detailed phases, tasks, and implementation specifics

### 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

2. DEVELOPMENT PHASES
   For each phase, provide:
   - Phase name and purpose
   - Detailed description
   - List of specific tasks/components

3. SPECIFIC TASKS
   For each task, include:
   - Exact component/file names
   - Specific functionality
   - Technical details (props, types, APIs)
   - Dependencies on other tasks

4. VALIDATION & SUCCESS CRITERIA
   - How to test each component
   - What success looks like
   - Integration points
```

---

## 📝 Step 2: Structure Your Plan

### Convert AI Output to JSON
Take the AI-generated plan and structure it into the required JSON format:

```json
{
  "id": "plan_[timestamp]",
  "goal": "[your project goal]",
  "status": "ready",
  "created": "[ISO date]",
  "phases": [
    {
      "id": "phase_[timestamp]_1",
      "name": "Phase Name",
      "description": "What this phase does",
      "tasks": [
        {
          "id": "task_[timestamp]_001",
          "description": "Specific task description",
          "type": "component_creation",
          "dependencies": [],
          "specifics": {
            "componentName": "MyComponent",
            "filePath": "src/components/MyComponent.tsx"
          }
        }
      ]
    }
  ]
}
```

### Required Fields
- **Plan**: `id`, `goal`, `phases`
- **Phase**: `id`, `name`, `description`, `tasks`
- **Task**: `id`, `description`, `type`, `dependencies`, `specifics`

---

## ✅ 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 validation results
5. Fix any errors externally and re-validate

### What Gets Validated
- ✅ Required fields present
- ✅ Proper JSON syntax
- ✅ Valid task types
- ✅ Dependencies exist
- ✅ No duplicate IDs
- ✅ Proper structure throughout

---

## 🚀 Step 4: Execute Step-by-Step with Git Integration

### Initial Setup (Optional)
```bash
# Configure git preferences
npm run plan:config autoCommit true      # Enable auto-commit
npm run plan:config interactive false    # Skip prompts for speed
```

### Once Validation Passes
```bash
npm run plan:continue   # Get first Claude Code Max command
```

### Enhanced Execution Loop
1. **Get command** - `npm run plan:continue`
2. **Implement** - Paste into Claude Code Max
3. **Save Claude's response** - `npm run plan:save-response [task_id] "Claude's summary..."`
4. **Complete & commit** - `npm run plan:complete [task_id] --commit`
5. **Continue** - Next task loads automatically
6. **Repeat** - Until all tasks are complete

### Example Execution
```bash
# Get task
npm run plan:continue

# After Claude implements:
# Claude: "I've successfully created the dashboard component..."

# Save the response
npm run plan:save-response task_001 "I've successfully created the dashboard component with Chart.js integration and responsive layout"

# Complete with auto-commit
npm run plan:complete task_001 --commit
# → Commits: "feat(ui): Created the dashboard component with Chart.js integration (task_001)"
```

### Track Progress
```bash
npm run plan:progress   # See completion status & git info
npm run plan:view       # View complete plan details
git log --oneline      # Review commit history
```

---

## 🛠️ Command Reference

### Planning Commands
| Command | Purpose |
|---------|---------|
| `npm run plan:validate` | Validate AI-generated plan structure |
| `npm run plan:view` | View complete plan with all details |

### Execution Commands
| Command | Purpose |
|---------|---------|
| `npm run plan:continue` | Get next Claude Code Max command |
| `npm run plan:save-response [id] "..."` | Save Claude's implementation summary |
| `npm run plan:complete [id]` | Mark task complete (auto-commits if enabled) |
| `npm run plan:complete [id] --commit` | Complete with explicit commit |
| `npm run plan:complete [id] --no-commit` | Complete without commit |
| `npm run plan:progress` | Check completion status |

### Git Configuration
| Command | Purpose |
|---------|---------|
| `npm run plan:config` | View current settings |
| `npm run plan:config autoCommit true/false` | Enable/disable auto-commit |
| `npm run plan:config interactive true/false` | Enable/disable prompts |
| `npm run plan:config includeTaskId true/false` | Include task ID in commits |

---

## 💡 Best Practices

### AI Plan Generation
- Be specific about your tech stack
- Request exact file names and paths
- Ask for implementation order
- Include validation criteria

### Plan Structuring
- Use consistent ID patterns
- Keep descriptions actionable
- Group related tasks in phases
- Specify all dependencies

### Validation
- Always validate before execution
- Fix all errors (not just warnings)
- Check task specificity ratio
- Ensure logical task order

### Execution with Git
- Save Claude's responses immediately
- Use auto-commit for efficiency
- Review git log periodically
- One task = one commit for clarity

---

## 🔄 Complete Example Workflow

1. **Generate with AI**:
   - "Create a user dashboard with analytics"
   - AI provides detailed plan

2. **Structure as JSON**:
   ```json
   {
     "id": "plan_1703089234567",
     "goal": "Create user dashboard with analytics",
     "phases": [...]
   }
   ```

3. **Configure Git** (optional):
   ```bash
   npm run plan:config autoCommit true
   ```

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

5. **Execute with Git**:
   ```bash
   # Get command
   npm run plan:continue
   
   # Implement with Claude
   # Claude: "I've successfully created..."
   
   # Save response
   npm run plan:save-response task_001 "Claude's summary"
   
   # Complete & commit
   npm run plan:complete task_001
   
   # Continue
   npm run plan:continue
   ```

6. **Review History**:
   ```bash
   git log --oneline
   # feat(ui): Created dashboard component (task_001)
   # feat(api): Implemented user stats endpoint (task_002)
   # ...
   ```

---

## 🎯 Why This Workflow?

### Benefits
- **AI Creativity**: Use any AI for comprehensive planning
- **Structure Safety**: Validation ensures perfect execution
- **Clear Commands**: Get specific Claude Code Max instructions
- **Progress Tracking**: Always know where you are
- **Git Integration**: Automatic meaningful commits
- **Clean History**: Each task = one atomic commit

### Key Features
- External AI integration
- Comprehensive validation
- Step-by-step execution
- Progress monitoring
- Automatic git commits
- Claude response integration

---

*From AI idea to working code with validated structure, precise execution, and clean git history.* ✨