mirror-magi-meta-agent

# 🎯 Mirror Magi Meta-Agent *AI-powered development planning and execution system for Claude Code Max* --- ## 🚀 The Magic Workflow ``` 🤖 AI ASSISTANT 📝 YOU ✅ VALIDATOR 🎯 CLAUDE CODE MAX │ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ Generate│ │Structure│ │Validate │ │ Execute │ │ Plan │ ➜ │as JSON │ ➜ │Structure│ ➜ │Step-by- │ │ │ │ │ │ │ │ Step │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ │ │ "Create a { ✅ PLAN IS 💻 Implementation dashboard with "id": "plan_123", VALID! Commands charts using "goal": "dashboard", │ │ React & TS" "phases": [...] 📁 Saved! 🔄 Progress │ } │ │ │ │ │ │ └─────────────────────┼──────────────────────┼──────────────────────┘ │ │ 🎨 CREATIVE 🔧 PRECISE Human Control AI Execution ``` **The workflow is simple:** 1. 🤖 **Generate** - Use any AI (ChatGPT, Claude, etc.) to create comprehensive plans 2. 📝 **Structure** - Format as JSON with exact file paths and details 3. ✅ **Validate** - Ensure perfect structure before execution 4. 🎯 **Execute** - Get specific Claude Code Max commands with no placeholders --- ## 🗄️ NEW: Supabase Integration Mirror Magi now includes **intelligent Supabase support** with: ### Pre-flight Checks - ✅ Automatic Supabase CLI detection - ✅ Project connection validation - ✅ Environment variable checking - ✅ Migration safety verification ### Supabase Task Types - `supabase_migration` - Database schema changes - `supabase_function` - Edge Functions - `supabase_rls` - Row Level Security policies ### Safety Features - 🛡️ Local vs remote database detection - 🔄 Automatic rollback SQL generation - ⚠️ Uncommitted migration warnings - 📋 Step-by-step validation [Learn more about Supabase integration →](./docs/guides/SUPABASE_INTEGRATION_GUIDE.md) --- ## 🔄 NEW: Git Integration with Claude Summaries Mirror Magi now features **intelligent Git commit automation** that uses Claude's implementation summaries: ### Smart Commit Messages - 🤖 Uses Claude's "I've successfully..." summaries - 📝 Conventional commit format (feat, fix, chore, etc.) - 🏷️ Automatic task ID tracking - 📄 Detailed commit bodies with file changes ### Key Features ```bash # Save Claude's response for better commits npm run plan:save-response task_001 "Claude's implementation summary..." # Complete task with auto-commit npm run plan:complete task_001 --commit # Configure preferences npm run plan:config autoCommit true ``` ### Workflow Benefits - ✨ **Meaningful Commits** - Claude's summaries are descriptive - ⏱️ **Time Saving** - No manual commit messages - 🔍 **Traceability** - Task IDs link commits to plan - 🎯 **Consistency** - All commits follow same format [Learn more about Git integration →](./docs/guides/CLAUDE_COMMIT_INTEGRATION.md) --- ## ⚡ Quick Start (5 minutes) ### 1. Install & Setup ```bash npm install -g mirror-magi cd your-project npm run setup ``` ### 2. Generate Plan with AI 🤖 Use this prompt with **any AI assistant**: ``` I need a comprehensive development plan for: [YOUR PROJECT] Include: - Clear phases and tasks - Exact file names and paths - Component details and dependencies - Validation criteria Tech stack: [React, TypeScript, etc.] ``` ### 3. Structure & Validate 📝✅ ```json { "id": "plan_123", "goal": "Your project goal", "phases": [{ "id": "phase_1", "name": "Setup", "description": "Initial setup", "tasks": [{ "id": "task_1", "description": "Create component", "type": "component_creation", "dependencies": [], "specifics": { "componentName": "MyComponent", "filePath": "src/components/MyComponent.tsx" } }] }] } ``` ```bash npm run plan:validate # Paste JSON, type END ``` ### 4. Execute Step-by-Step 🎯 ```bash npm run plan:continue # Get Claude Code Max command # → Implement with Claude npm run plan:save-response task_1 "Claude's response" # Save for commits npm run plan:complete task_1 --commit # Complete & commit npm run plan:progress # Check progress ``` --- ## 🛠️ Core Commands | Command | What It Does | When To Use | |---------|-------------|-------------| | `npm run plan:validate` | 📋 Validate plan structure | After creating JSON plan | | `npm run plan:view` | 👁️ View complete plan | Check plan details | | `npm run plan:continue` | ▶️ Get next command | Ready to implement | | `npm run plan:complete [id]` | ✅ Mark task complete | After implementing | | `npm run plan:complete [id] --commit` | ✅ Complete & commit | With git integration | | `npm run plan:save-response [id] "..."` | 💾 Save Claude's response | For better commits | | `npm run plan:config [setting] [value]` | ⚙️ Configure preferences | Customize workflow | | `npm run plan:progress` | 📊 Check progress | Track completion | --- ## 🎯 Live Example ### AI Input 🤖 ``` "Create a todo list app with add/delete functionality using React and TypeScript" ``` ### Structured Plan 📝 ```json { "id": "plan_todo_app", "goal": "Create todo list app with add/delete functionality", "phases": [{ "id": "phase_1", "name": "Todo Component Setup", "tasks": [{ "id": "task_1", "description": "Create TodoList component with add/delete functionality", "type": "component_creation", "dependencies": [], "specifics": { "componentName": "TodoList", "filePath": "src/components/TodoList.tsx", "features": ["add items", "delete items", "mark complete"] } }] }] } ``` ### Execute 🎯 ```bash npm run plan:validate # ✅ PLAN IS VALID npm run plan:continue # Get: "Create TodoList component at src/components/TodoList.tsx with..." # → Paste into Claude Code Max # Claude responds: "I've successfully created the TodoList component..." npm run plan:save-response task_1 "I've successfully created the TodoList component with add, delete, and mark complete functionality" npm run plan:complete task_1 --commit # ✅ Committed: "feat(ui): Created the TodoList component with add, delete, and mark complete functionality (task_1)" ``` --- ## 🌟 Why Mirror Magi? | Feature | Benefit | |---------|---------| | 🤖 **AI Integration** | Works with **any** AI assistant | | 📝 **No Placeholders** | Specific file names & paths | | ✅ **Structure Validation** | Catches errors before execution | | 🎯 **Precise Commands** | Exact Claude Code Max instructions | | 📊 **Progress Tracking** | Always know where you are | | 🗄️ **Supabase Ready** | Intelligent database operations | | 🔄 **Git Automation** | Claude's summaries become commits | | 🚀 **4-Step Workflow** | Simple yet powerful | --- ## 📚 Documentation - **[Getting Started](./docs/GETTING_STARTED.md)** - Detailed setup guide - **[Core Scripts](./docs/CORE_SCRIPTS.md)** - Complete command reference - **[Project Structure](./docs/PROJECT_STRUCTURE.md)** - File organization - **[Supabase Integration](./docs/guides/SUPABASE_INTEGRATION_GUIDE.md)** - Database operations - **[Git Integration](./docs/guides/CLAUDE_COMMIT_INTEGRATION.md)** - Commit automation - **[Planning Guides](./docs/guides/)** - In-depth documentation --- ## 🎨 The Perfect Balance ``` 🎨 HUMAN CREATIVITY 🤖 AI PRECISION │ │ ┌─────────┐ ┌─────────┐ │ Strategic│ │Execution│ │Planning │ + │Details │ │ Vision │ │& Speed │ └─────────┘ └─────────┘ │ │ └──────────┬─────────────────┘ │ ✨ MIRROR MAGI ✨ Best of Both! ``` --- ## 🤝 Contributing Love the project? Contributions welcome! --- ## 📄 License MIT License - Transform your AI plans into working code! --- *Where AI creativity meets structured execution* ✨