# 🎯 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* ✨