mirror-magi-meta-agent

# 📋 Plan Structure & Validation Guide *Everything you need to know about structuring and validating AI-generated plans* ## 🎯 Overview The meta-agent uses a **streamlined validation workflow**: 1. **Generate plans** with any AI tool 2. **Structure them** in proper JSON format 3. **Validate structure** before execution 4. **Execute step-by-step** with Claude Code Max This guide explains the exact structure requirements and validation process. --- ## 📋 1. Required Plan Structure ### Complete JSON Template ```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", "props": {"prop1": "Type1"} } } ] } ] } ``` ### Required Fields by Level **Plan Level** (all required): - `id`: Unique plan identifier - `goal`: Clear project goal statement - `phases`: Array of development phases **Phase Level** (all required): - `id`: Unique phase identifier - `name`: Phase name - `description`: What this phase accomplishes - `tasks`: Array of tasks (can be empty initially) **Task Level** (all required): - `id`: Unique task identifier - `description`: What this task accomplishes - `type`: Task type (see valid types below) - `dependencies`: Array of task IDs this depends on - `specifics`: Object with implementation details ### Valid Task Types The system recognizes these task types: - `component_creation`: Creating UI components - `api_integration`: Integrating with APIs - `configuration`: Setting up configs - `testing_implementation`: Adding tests - `feature_development`: General development work - `styling_implementation`: CSS and styling - `data_modeling`: Types and data structures --- ## ✅ 2. Plan Validation ### Quick Validation ```bash npm run plan:validate ``` **Options**: 1. **Validate new plan** - Paste your JSON 2. **Validate existing plan** - Check saved file 3. **Show structure requirements** - See templates ### Validation Process 1. **Choose option 1**: "Validate new plan" 2. **Paste your JSON plan** 3. **Type "END"** on a new line 4. **Review results**: - ✅ Errors (must fix) - ⚠️ Warnings (recommended) - 📊 Statistics ### What Gets Validated **Structure Checks**: - ✅ All required fields present - ✅ Proper JSON syntax - ✅ Valid field types (arrays, objects, strings) - ✅ No empty required fields **Integrity Checks**: - ✅ All task dependencies exist - ✅ No duplicate IDs - ✅ Valid task types - ✅ Logical phase structure **Quality Checks**: - ✅ Descriptive task names - ✅ Tasks have specifics - ✅ Dependencies make sense --- ## 🔧 3. Common Validation Errors ### Missing Required Fields ```json // ❌ WRONG - Missing required fields { "description": "Build something" // Missing: id, type, dependencies, specifics } // ✅ CORRECT - All fields present { "id": "task_123_001", "description": "Build something", "type": "component_creation", "dependencies": [], "specifics": {} } ``` ### Invalid Dependencies ```json // ❌ WRONG - References non-existent task { "id": "task_2", "dependencies": ["task_that_does_not_exist"] } // ✅ CORRECT - References actual task { "id": "task_2", "dependencies": ["task_1"] // task_1 exists in plan } ``` ### Duplicate IDs ```json // ❌ WRONG - Same ID used twice "tasks": [ {"id": "task_1", "description": "Task A"}, {"id": "task_1", "description": "Task B"} // Duplicate! ] // ✅ CORRECT - Unique IDs "tasks": [ {"id": "task_1", "description": "Task A"}, {"id": "task_2", "description": "Task B"} ] ``` ### Empty Required Arrays ```json // ❌ WRONG - phases must have content { "phases": [] // Must have at least one phase } // ✅ CORRECT - At least one phase { "phases": [ {"id": "phase_1", "name": "Setup", "tasks": []} ] } ``` --- ## 💡 4. Task Specifics Examples ### Component Creation ```json { "type": "component_creation", "specifics": { "componentName": "UserDashboard", "filePath": "src/components/UserDashboard.tsx", "props": { "user": "User", "analytics": "AnalyticsData" }, "features": ["responsive", "real-time updates"] } } ``` ### API Integration ```json { "type": "api_integration", "specifics": { "endpoints": [ "/api/users", "/api/analytics" ], "methods": ["GET", "POST"], "authentication": "JWT" } } ``` ### Configuration ```json { "type": "configuration", "specifics": { "configFiles": [ "src/config/routes.ts", "webpack.config.js" ], "settings": { "environment": "production", "features": ["hot-reload", "minification"] } } } ``` --- ## 🚀 5. Execution After Validation ### When Validation Passes ```bash # Save plan and prepare for execution Save plan and prepare for execution? (y/n): y 🎉 Plan saved and ready for execution! 📁 Location: state/master-plan.json 💡 Next steps: • Start execution: npm run plan:continue • View complete plan: npm run plan:view • Check progress: npm run plan:progress ``` ### First Task Preview After saving, you'll see: ``` 👀 FIRST TASK PREVIEW: ─────────────────────── 📝 Create UserDashboard component with layout 🏷️ Type: component_creation 🆔 ID: task_1703089234567_001 📋 Specifics: componentName: UserDashboard filePath: src/components/UserDashboard.tsx 🚀 Run "npm run plan:continue" to get the full Claude Code Max command ``` --- ## 📊 6. Validation Statistics The validator provides helpful statistics: ``` 📊 PLAN STATISTICS: Phases: 4 Tasks: 12 Tasks with specifics: 10/12 (83.3%) Task types: component_creation: 5 api_integration: 3 configuration: 2 testing_implementation: 2 ``` This helps you understand: - Plan complexity - Task distribution - Specificity level --- ## 🛠️ 7. Best Practices ### Structure IDs Consistently ```json // Good pattern: type_timestamp_sequence "id": "plan_1703089234567" "id": "phase_1703089234567_1" "id": "task_1703089234567_001" ``` ### Write Clear Descriptions ```json // ❌ Vague "description": "Build UI" // ✅ Specific "description": "Create UserDashboard component with responsive grid layout for analytics widgets" ``` ### Include Implementation Details ```json // ❌ Empty specifics "specifics": {} // ✅ Detailed specifics "specifics": { "componentName": "AnalyticsChart", "chartType": "line", "dataSource": "/api/analytics", "refreshInterval": 5000 } ``` ### Order Dependencies Logically ```json // Tasks in execution order "tasks": [ {"id": "setup_1", "dependencies": []}, {"id": "component_1", "dependencies": ["setup_1"]}, {"id": "integration_1", "dependencies": ["component_1"]} ] ``` --- ## 🔄 8. Complete Workflow 1. **Generate with AI**: Get comprehensive plan 2. **Structure as JSON**: Use required format 3. **Validate structure**: ```bash npm run plan:validate ``` 4. **Fix any errors**: Update JSON externally 5. **Re-validate**: Ensure all errors resolved 6. **Save and execute**: Start implementation --- ## ⚡ 9. Quick Reference ### Required Structure ``` Plan ├── id (string) ├── goal (string) ├── status (string) ├── created (ISO date) └── phases (array) └── Phase ├── id (string) ├── name (string) ├── description (string) └── tasks (array) └── Task ├── id (string) ├── description (string) ├── type (string) ├── dependencies (array) └── specifics (object) ``` ### Validation Commands ```bash npm run plan:validate # Validate structure npm run plan:view # View with validation npm run plan:continue # Start execution (after valid) ``` ### Common Fixes - Missing field? Add it with empty value - Wrong type? Convert (e.g., string to array) - Duplicate ID? Add unique suffix - Bad dependency? Check task exists --- *Perfect structure = Perfect execution. Validate before you execute!*