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

AI-powered development planning and execution system with Supabase integration

# ✅ AI Plan Validation & Execution

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

---

## 🎯 Simplified Workflow

### Your Process:
1. **Generate plan with AI** (ChatGPT, Claude, etc.)
2. **Structure it externally** (copy/paste into JSON format)
3. **Validate with our tool** (ensure exact correct structure)
4. **Execute step-by-step** (get Claude Code Max commands)

---

## ✅ Plan Validation

### Quick Validation Command
```bash
npm run plan:validate
```

### Options:
1. **Validate new plan** - Paste your JSON plan for validation
2. **Validate existing plan** - Check saved plan file
3. **Show structure requirements** - See exact JSON format needed

---

## 📋 Required Structure

Your AI-generated plan must have this exact JSON structure:

```json
{
  "id": "plan_1703089234567",
  "goal": "Clear project goal statement",
  "status": "ready",
  "created": "2024-12-20T14:30:00.000Z",
  "phases": [
    {
      "id": "phase_1703089234567_1",
      "name": "Phase Name",
      "description": "What this phase accomplishes",
      "tasks": [
        {
          "id": "task_1703089234567_001",
          "description": "Specific task description",
          "type": "component_creation",
          "dependencies": [],
          "specifics": {
            "componentName": "MyComponent",
            "filePath": "src/components/MyComponent.tsx"
          }
        }
      ]
    }
  ]
}
```

## ✅ Required Fields Checklist

**Plan Level:**
- ✅ `id` - Unique plan identifier
- ✅ `goal` - Clear project goal
- ✅ `phases` - Array of phases

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

**Task Level:**
- ✅ `id` - Unique task identifier
- ✅ `description` - Task description
- ✅ `type` - Task type (see valid types below)
- ✅ `dependencies` - Array of task IDs (can be empty: `[]`)
- ✅ `specifics` - Object with 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 and validation
- `feature_development` - General functionality
- `styling_implementation` - CSS and design
- `data_modeling` - Types and data structures

---

## 🔍 Validation Process

### Step 1: Run Validator
```bash
npm run plan:validate
```

### Step 2: Choose Option 1
- Paste your JSON plan
- End with line containing just "END"

### Step 3: Review Results
- ✅ **VALID**: Plan ready for execution
- ❌ **ERRORS**: Must fix before execution
- ⚠️ **WARNINGS**: Recommended improvements

### Step 4: Save & Execute
If valid:
- Plan saves to `state/master-plan.json`
- Ready for execution with `npm run plan:continue`

---

## 🚀 Execution Commands

After validation passes:

```bash
npm run plan:continue   # Get first Claude Code Max command
# → Copy command to Claude Code Max
# → Let Claude implement the task
node plan-project.js complete [task_id]  # Mark task complete
npm run plan:continue   # Get next command
# → Repeat until all tasks done
```

## 📊 Other Useful Commands

```bash
npm run plan:view       # See complete plan with all details
npm run plan:progress   # Check completion status
npm run plan:edit       # Make manual edits (optional)
```

---

## ⚠️ Common Validation Errors

### Missing Required Fields
```json
// ❌ Missing required fields
{
  "description": "Build something"
  // Missing: id, type, dependencies, specifics
}

// ✅ All required fields present
{
  "id": "task_123_001",
  "description": "Build something",
  "type": "component_creation",
  "dependencies": [],
  "specifics": {}
}
```

### Invalid Dependencies
```json
// ❌ Reference to non-existent task
{
  "dependencies": ["task_does_not_exist"]
}

// ✅ Valid dependency reference
{
  "dependencies": ["task_123_001"]  // This task must exist in plan
}
```

### Duplicate IDs
```json
// ❌ Same ID used twice
{
  "tasks": [
    {"id": "task_1", "description": "Task A"},
    {"id": "task_1", "description": "Task B"}  // Duplicate!
  ]
}
```

---

## 💡 Pro Tips

### Better Structure:
- Use consistent ID patterns: `task_timestamp_001`
- Keep task descriptions specific and actionable
- Group related tasks in logical phases
- Ensure dependencies make chronological sense

### Task Specifics:
- Add file paths for component tasks
- Include API endpoints for integration tasks
- Specify config files for configuration tasks
- The more specific, the better Claude Code Max commands

### Validation First:
- Always validate before execution
- Fix all errors (not just warnings)
- Check that first task preview makes sense
- Ensure total task count seems reasonable

---

## 🎯 Example Valid Task

```json
{
  "id": "task_1703089234567_001",
  "description": "Create UserDashboard component with responsive layout and analytics props",
  "type": "component_creation",
  "dependencies": [],
  "specifics": {
    "componentName": "UserDashboard",
    "filePath": "src/components/UserDashboard.tsx",
    "props": {
      "user": "User",
      "analytics": "AnalyticsData"
    }
  }
}
```

This will generate a specific Claude Code Max command like:
> "Create a UserDashboard component in src/components/UserDashboard.tsx with props for user and analytics..."

---

*Perfect structure = Perfect execution commands*