🎯 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 →

🔄 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

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

⚡ Quick Start (5 minutes)

1. Install & Setup

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 📝✅

{
  "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"
      }
    }]
  }]
}

npm run plan:validate  # Paste JSON, type END

4. Execute Step-by-Step 🎯

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 📝

{
  "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 🎯

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 - Detailed setup guide
• Core Scripts - Complete command reference
• Project Structure - File organization
• Supabase Integration - Database operations
• Git Integration - Commit automation
• Planning 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 ✨