mirror-magi-meta-agent/docs/GETTING_STARTED.md

AI-powered development planning and execution system with Supabase integration

# 🚀 Getting Started

*From AI plan to working code with clean git history in 5 minutes*

---

## 1️⃣ Installation

```bash
# Global install
npm install -g mirror-magi

# Or clone repo
git clone https://github.com/your-username/mirror-magi.git
cd mirror-magi/meta-agent
npm install
```

---

## 2️⃣ Setup

```bash
cd your-project
npm run setup

# Configure git integration (optional)
npm run plan:config autoCommit true  # Auto-commit on completion
npm run plan:config interactive true  # Review commits before applying
```

Creates configuration and directory structure.

---

## 3️⃣ Create Your Plan

### AI Prompt Template
```
I need a development plan for: [YOUR PROJECT]

Include for each task:
- Exact file names and paths
- Component/function names
- Dependencies between tasks
- How to test/validate

Tech stack: [React, TypeScript, etc.]
```

### Structure as JSON
```json
{
  "id": "plan_[timestamp]",
  "goal": "Project goal",
  "status": "ready",
  "phases": [{
    "id": "phase_1",
    "name": "Phase name",
    "description": "What this does",
    "tasks": [{
      "id": "task_1",
      "description": "Specific task",
      "type": "component_creation",
      "dependencies": [],
      "specifics": {
        "componentName": "Component",
        "filePath": "src/components/Component.tsx"
      }
    }]
  }]
}
```

---

## 4️⃣ Validate

```bash
npm run plan:validate
# Choose option 1
# Paste JSON
# Type END
```

Fix any errors shown, then re-validate.

---

## 5️⃣ Execute with Git Integration

```bash
# Get first command
npm run plan:continue

# Copy to Claude Code Max
# Let Claude implement
# Claude responds: "I've successfully created..."

# Save Claude's response for meaningful commits
npm run plan:save-response task_1 "I've successfully created the TodoList component with add, delete, and mark complete functionality. The component uses React hooks for state management and includes error handling."

# Complete task with auto-commit
npm run plan:complete task_1 --commit
# → Creates commit: "feat(ui): Created the TodoList component with add, delete, and mark complete functionality (task_1)"

# Continue to next task
npm run plan:continue
```

### Quick Workflow (Auto-commit enabled)
```bash
# If auto-commit is enabled
npm run plan:config autoCommit true

# Then just:
npm run plan:continue                    # Get task
npm run plan:save-response task_1 "..."  # Save Claude's summary
npm run plan:complete task_1             # Complete & auto-commit
```

---

## 📋 Required Fields

### Plan
- `id` - Unique identifier
- `goal` - Project goal
- `phases` - Array of phases

### Phase
- `id` - Unique identifier
- `name` - Phase name
- `description` - What it does
- `tasks` - Array of tasks

### Task
- `id` - Unique identifier
- `description` - Task description
- `type` - Task type (see below)
- `dependencies` - Array of task IDs
- `specifics` - Implementation details

---

## 🏷️ Task Types

- `component_creation` - UI components
- `api_integration` - API connections
- `configuration` - Config files
- `testing_implementation` - Tests
- `feature_development` - General features
- `supabase_migration` - Database migrations
- `supabase_rls` - Row Level Security
- `styling_implementation` - CSS/styling

---

## 🔄 Git Integration Features

### Save Claude's Response
```bash
# From text
npm run plan:save-response task_1 "Claude's response..."

# From file
npm run plan:save-response task_1 --file response.txt
```

### Commit Options
```bash
# Auto-commit with Claude's summary
npm run plan:complete task_1 --commit

# Custom message
npm run plan:complete task_1 --commit --message "feat: Custom message"

# Skip commit (if auto-commit enabled)
npm run plan:complete task_1 --no-commit
```

### Configuration
```bash
# View settings
npm run plan:config

# Enable auto-commit
npm run plan:config autoCommit true

# Disable interactive mode for faster workflow
npm run plan:config interactive false
```

---

## 💡 Tips

1. **Be specific** - Include exact file paths
2. **Add details** - More specifics = better commands
3. **Check dependencies** - Ensure logical order
4. **Validate first** - Always validate before executing
5. **Save Claude's responses** - For meaningful commit messages
6. **Use auto-commit** - For faster workflow

---

## 🎯 Complete Example

### AI Input
```
Create a todo list component with add/delete functionality
```

### Structured Plan
```json
{
  "id": "plan_todo",
  "goal": "Create todo list component",
  "phases": [{
    "id": "phase_1",
    "name": "Todo Component",
    "tasks": [{
      "id": "task_1",
      "description": "Create TodoList component",
      "type": "component_creation",
      "dependencies": [],
      "specifics": {
        "componentName": "TodoList",
        "filePath": "src/components/TodoList.tsx",
        "features": ["add items", "delete items", "mark complete"]
      }
    }]
  }]
}
```

### Execution with Git
```bash
# Validate
npm run plan:validate

# Execute
npm run plan:continue
# → Copy command to Claude

# Save Claude's response
npm run plan:save-response task_1 "I've successfully created the TodoList component with full CRUD functionality, state management using React hooks, and TypeScript interfaces for type safety."

# Complete with commit
npm run plan:complete task_1 --commit
# → Commits: "feat(ui): Created the TodoList component with full CRUD functionality (task_1)"
```

---

## 🚀 Next Steps

- Read [Core Scripts](./CORE_SCRIPTS.md) for all commands
- Check [Claude Commit Integration](./guides/CLAUDE_COMMIT_INTEGRATION.md) for git details
- Review [Planning Guides](./guides/) for detailed info
- Start building with `npm run plan:continue`

---

*Transform your AI plans into working code with clean git history!* ✨