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

AI-powered development planning and execution system with Supabase integration

# 🎯 Mirror Magi Meta-Agent Core Scripts & Entry Points

*Complete reference for all ways to interact with the meta-agent system*

## 🌍 Global CLI Commands

After installing globally with `npm install -g mirror-magi-meta-agent`:

### **Primary Commands**
```bash
mirror-magi init         # Initialize meta-agent in any project
mirror-magi setup        # Set up configuration files from templates
mirror-magi test         # Test the meta-agent with sample tasks
mirror-magi validate     # Validate configuration files
mirror-magi customize    # Get customization guidance
mirror-magi help         # Show all available commands
```

### **Usage Examples**
```bash
# Start a new project
cd my-awesome-app
mirror-magi init
cd meta-agent
npm install
npm run setup

# Test your setup
mirror-magi test

# Get help customizing
mirror-magi customize
```

---

## 📋 NPM Scripts (Local Project)

When working inside a `meta-agent/` directory:

### **Core Scripts**
```bash
npm test                 # Run the main test suite with sample tasks
npm run setup           # Initialize configuration from templates
npm run validate        # Validate project configuration
npm run plan            # Quick plan creation (uses defaults)
npm run plan:interactive # Interactive collaborative planning session
npm run plan:edit       # Edit existing plans
npm run plan:continue   # Continue executing existing plan
npm run plan:progress   # Show plan progress
npm run plan:demo       # Demo of enhanced planning system
```

### **Usage Examples**
```bash
cd meta-agent
npm run setup           # Creates config files from templates
npm test                # Shows demo of 7 sample tasks
npm run validate        # Checks if everything is configured correctly
```

---

## 🔧 Direct Node Scripts

### **Main Entry Points**

#### **1. Primary Demo & Testing**
```bash
node test-agent.js      # Main demo - shows full meta-agent capabilities
```
**What it does:** 
- Runs 7 sample tasks through the full pipeline
- Shows classification, risk assessment, and command generation
- Perfect for understanding how the system works

**Example Output:**
```
🎯 TASK: "Create a new React component for user profiles"
📋 CLASSIFICATION: component_creation (1/5)
🚀 GENERATED COMMAND: [Full Claude Code Max command]
```

#### **2. Single Command Generation**
```bash
node generate-command.js "your task description"
```
**What it does:**
- Takes one task and generates a complete Claude Code Max command
- Shows classification and outputs the full command text
- Perfect for real development work

**Examples:**
```bash
node generate-command.js "Create a login form with validation"
node generate-command.js "Add API endpoint for user authentication"
node generate-command.js "Implement real-time notifications"
```

#### **3. Programmatic API Entry Point**
```bash
node index.js           # Exports core classes for programmatic use
```
**What it exports:**
- `TemplateEngine`: Generate commands from task specifications
- `TaskClassifier`: Classify tasks by type, complexity, domains
- `setup`: Setup function for initialization
- `validate`: Validation function for configuration

#### **4. Enhanced Development Planning Mode (NEW)**
```bash
cd meta-agent
node demo-specific-planning.js              # See the enhanced system demo
node plan-project.js "Create user dashboard with analytics"  # Create master plan
node plan-project.js continue               # Get specific, actionable commands
```
**Perfect for:**
- Real development work with specific requirements
- Sequential development where tasks build on each other
- Projects that need systematic planning and execution
- Getting commands with actual file paths, component names, and implementation details

**Key Features:**
- **No Placeholders**: Commands contain actual file names, component names, and specific requirements
- **Sequential Tasks**: Each command builds on previous work and maintains context
- **Progress Tracking**: Always know where you are in the development plan
- **Specific Validation**: Validation steps reference actual files and components you're building

#### **5. Interactive Planning & Editing (LATEST)**
```bash
cd meta-agent
node interactive-planner.js                 # Collaborative planning session
node edit-plan.js                          # Edit existing plans
```
**Perfect for:**
- **Collaborative Planning**: Full control over plan creation with discussion and refinement
- **Plan Iteration**: Modify plans as requirements evolve
- **Detailed Planning**: Add specific tasks, dependencies, and time estimates before committing

**Key Features:**
- **No Commitment Until Finalized**: Review and refine everything before starting
- **Complete Plan Control**: Edit goals, phases, tasks, context, and requirements
- **Interactive Workflow**: Guided questions and options for every aspect
- **Change Tracking**: See exactly what changed before saving
- **Backup Protection**: Keep original plan safe while editing

---

## ⚙️ Setup & Configuration Scripts

### **Initialization**
```bash
node scripts/setup.js                 # Initialize config from templates
node scripts/setup-verification.sh    # Verify setup completed correctly
```

### **Configuration Management**
```bash
node scripts/validate-config.js       # Validate project configuration
```
**What it checks:**
- JSON syntax validity
- Required fields presence
- Template placeholders removal
- Tech stack consistency

---

## 🔍 Validation Scripts

### **Run All Validations**
```bash
node scripts/run-all-validations.sh   # Run comprehensive validation suite
```

### **Specific Validations**
```bash
node scripts/validate-typescript.sh   # TypeScript-specific checks
node scripts/validate-security.sh     # Security vulnerability checks  
node scripts/validate-tests.sh        # Test coverage and quality
node scripts/validate-performance.sh  # Performance checks
node scripts/validate-supabase.sh     # Supabase-specific validation
```

### **Validation Testing**
```bash
node scripts/test-validation-system.sh # Test the validation system itself
```

---

## 🚀 Interactive Modes

### **1. Demo Mode (Recommended Starting Point)**
```bash
cd meta-agent
npm test
```
**Perfect for:**
- Understanding how the meta-agent works
- Seeing examples of different task types
- Learning the classification system
- Getting sample commands

### **2. Single Task Mode**
```bash
cd meta-agent
node generate-command.js "Create a user dashboard component"
```
**Perfect for:**
- Real development work
- Getting specific commands for your tasks
- Quick command generation

### **3. Setup Mode**
```bash
mirror-magi setup
# or
npm run setup
```
**Perfect for:**
- Initial project configuration
- Creating config files from templates
- Getting started quickly

---

## 💻 Programmatic Usage

### **Basic Usage**
```javascript
const { TemplateEngine, TaskClassifier } = require('mirror-magi-meta-agent');

// Load your config
const config = require('./config/project-config.json');
const projectState = require('./state/project-state.json');

// Initialize
const classifier = new TaskClassifier();
const templateEngine = new TemplateEngine(config, projectState);

// Use
const classification = classifier.classifyTask("Add user authentication");
const command = await templateEngine.generateCommand({
  description: "Add user authentication",
  type: classification.primaryType,
  complexity: classification.complexity,
  domains: classification.domains
});

console.log(command.command); // Full Claude Code Max command
```

### **Advanced Usage**
```javascript
// Custom task specification
const taskSpec = {
  description: "Create advanced data visualization",
  type: "feature_development",
  complexity: 4,
  domains: ["frontend", "data_visualization", "performance"],
  customContext: {
    framework: "D3.js",
    dataSize: "large",
    realTime: true
  }
};

const result = await templateEngine.generateCommand(taskSpec);
```

---

## 📊 Advanced Scripts

### **Session Management**
```bash
node scripts/session-manager.sh       # Manage development sessions
```
**Features:**
- Track development sessions
- Manage context across multiple tasks
- Session history and analytics

---

## 🎯 Quick Reference

### **First Time Setup**
```bash
npm install -g mirror-magi-meta-agent
cd your-project
mirror-magi init
cd meta-agent
npm install
npm run setup
npm test
```

### **Daily Usage**
```bash
# Interactive Planning Workflow (Recommended)
npm run plan:interactive # Create plan collaboratively
npm run plan:edit        # Edit plan if needed
npm run plan:continue    # Execute step-by-step

# Quick Command Generation (Single Tasks)
node generate-command.js "your task here"

# Progress Tracking
npm run plan:progress    # Check development progress
npm run validate         # Validate configuration
```

### **Troubleshooting**
```bash
# Check configuration
npm run validate

# Re-setup if needed
npm run setup

# Run all validations
node scripts/run-all-validations.sh
```

---

## 🔧 File Structure Overview

```
meta-agent/
├── bin/cli.js                    # Global CLI commands
├── index.js                     # Programmatic API exports
├── test-agent.js                # Main demo script
├── generate-command.js           # Single command generator
├── core/                        # Core engines
│   ├── template-engine.js       # Command generation
│   ├── task-classifier.js       # Task classification
│   └── context-builder.js       # Context building
├── scripts/                     # Utility scripts
│   ├── setup.js                 # Configuration setup
│   ├── validate-config.js       # Configuration validation
│   ├── run-all-validations.sh   # Complete validation suite
│   └── [other validation scripts]
├── config/                      # Configuration files
│   ├── project-config.json      # Main project configuration
│   ├── agent-persona.md         # Agent persona/context
│   └── [template files]
└── state/                       # Project state
    └── project-state.json       # Current project state
```

---

## 🌟 Best Practices

### **For Development**
1. **Start with demo**: `npm test` to understand capabilities
2. **Use single command generator**: `node generate-command.js` for real tasks
3. **Validate regularly**: `npm run validate` to catch issues early

### **For Configuration**
1. **Customize first**: Update `config/project-config.json` for your tech stack
2. **Test after changes**: Run `npm test` after configuration updates
3. **Use validation**: Run validation scripts to ensure everything works

### **For Automation**
1. **Use programmatic API**: Import classes for custom integrations
2. **Chain validations**: Use `run-all-validations.sh` in CI/CD
3. **Session management**: Use session manager for complex workflows

---

## 📚 Related Documentation

- **[README.md](./README.md)** - Overview and main documentation
- **[GETTING_STARTED.md](./GETTING_STARTED.md)** - Installation and setup guide  
- **[CUSTOMIZATION_GUIDE.md](./CUSTOMIZATION_GUIDE.md)** - Comprehensive customization guide

---

*This reference covers all available entry points and scripts in the Mirror Magi Meta-Agent system. Choose the method that best fits your workflow and use case.* 

# 🛠️ Core Scripts Reference

*Essential commands for AI-powered development planning and execution with Git integration*

---

## 🎯 Quick Start Workflow

### 1. Generate plan with AI (ChatGPT, Claude, etc.)
### 2. Structure as JSON
### 3. Validate structure
### 4. Execute step-by-step with automatic git commits

---

## 📋 Essential Commands

### 🔍 Plan Validation
```bash
npm run plan:validate
```
- Validates AI-generated plan structure
- Checks required fields and dependencies
- Saves valid plans for execution

### 👁️ View Plan
```bash
npm run plan:view
```
- Shows complete plan with all details
- Displays validation checklist
- Shows all tasks and dependencies

### ▶️ Execute Plan
```bash
npm run plan:continue
```
- Gets next Claude Code Max command
- Provides specific implementation instructions
- No placeholders - just exact commands
- Shows git integration tips

### 💾 Save Claude's Response (NEW)
```bash
npm run plan:save-response [task_id] "Claude's response..."
npm run plan:save-response [task_id] --file response.txt
```
- Saves Claude's implementation summary
- Extracts meaningful commit messages
- Enables better git history

### ✅ Mark Task Complete with Git Integration
```bash
npm run plan:complete [task_id]                    # Basic completion
npm run plan:complete [task_id] --commit           # Complete with commit
npm run plan:complete [task_id] --commit --message "Custom message"
npm run plan:complete [task_id] --no-commit        # Skip auto-commit
```
- Marks a task as completed
- Updates progress tracking
- Optionally commits changes with meaningful messages

### 📊 Check Progress
```bash
npm run plan:progress
npm run plan:status      # Alias for progress
```
- Shows overall completion percentage
- Lists completed and remaining tasks
- Shows git integration status

### ⚙️ Configure Git Integration (NEW)
```bash
npm run plan:config                           # View settings
npm run plan:config autoCommit true          # Enable auto-commit
npm run plan:config interactive false        # Disable prompts
npm run plan:config includeTaskId true       # Add task IDs to commits
npm run plan:config showGitInstructions true # Show git tips
```
- Configure git integration preferences
- Customize workflow behavior
- Set once, use everywhere

---

## 🔄 Git Integration Workflow

### Basic Workflow
```bash
# 1. Get task
npm run plan:continue

# 2. Implement with Claude
# Claude responds: "I've successfully created..."

# 3. Save response
npm run plan:save-response task_1 "Claude's response"

# 4. Complete with commit
npm run plan:complete task_1 --commit
```

### Auto-commit Workflow
```bash
# Enable once
npm run plan:config autoCommit true

# Then just:
npm run plan:continue
npm run plan:save-response task_1 "..."
npm run plan:complete task_1  # Auto-commits!
```

### Interactive Workflow
```bash
# Complete with options
npm run plan:complete task_1 --commit

# Shows:
# 🤖 Claude's summary: "I've successfully created..."
# 💬 Suggested: feat(ui): Created dashboard component (task_1)
# Options:
# 1. Use suggested
# 2. Use Claude's summary
# 3. Custom message
# 4. Skip commit
```

---

## 🗄️ Supabase Commands

### Pre-flight Check
```bash
npm run supabase:check
```
- Validates Supabase CLI installation
- Checks project connection
- Verifies environment setup
- Tests migration safety

---

## 🔧 Setup & Configuration

### Initial Setup
```bash
npm run setup
```
- Creates configuration files
- Sets up directory structure
- Initializes git preferences

### Validate Config
```bash
npm run validate
```
- Checks configuration validity
- Ensures all required files exist

---

## 📁 Enhanced Project Structure

```
meta-agent/
├── scripts/
│   ├── validation/
│   │   └── validate-plan.js       # Plan validator
│   ├── planning/
│   │   └── view-complete-plan.js  # Plan viewer
│   └── execution/
│       ├── plan-project.js        # Execution engine
│       ├── git-helpers.js         # Git operations
│       ├── commit-utils.js        # Commit formatting
│       └── claude-response-manager.js # Response storage
├── core/                          # Core engines
├── config/                        # Configuration
├── state/                         # Plan & git state
│   ├── master-plan.json          # Current plan
│   ├── claude-responses.json     # Saved responses
│   └── user-preferences.json     # Git preferences
├── docs/                          # Documentation
│   └── guides/                    
│       └── CLAUDE_COMMIT_INTEGRATION.md
└── README.md                      # Main documentation
```

---

## 🚀 Complete Example with Git

### 1. Generate Plan with AI
```
Create a user dashboard with analytics charts and settings panel
using React, TypeScript, and Tailwind CSS.
```

### 2. Structure as JSON
```json
{
  "id": "plan_dashboard",
  "goal": "Create user dashboard with analytics",
  "status": "ready",
  "phases": [{
    "id": "phase_1",
    "name": "Foundation",
    "description": "Basic structure",
    "tasks": [{
      "id": "task_1",
      "description": "Create dashboard page component",
      "type": "component_creation",
      "dependencies": [],
      "specifics": {
        "componentName": "Dashboard",
        "filePath": "src/app/dashboard/page.tsx"
      }
    }]
  }]
}
```

### 3. Validate
```bash
npm run plan:validate
```

### 4. Execute with Git
```bash
# Get command
npm run plan:continue

# Implement with Claude
# Claude: "I've successfully created the dashboard component with Chart.js integration..."

# Save response
npm run plan:save-response task_1 "I've successfully created the dashboard component with Chart.js integration, responsive layout, and real-time data updates."

# Complete with commit
npm run plan:complete task_1 --commit
# → Commits: "feat(ui): Created the dashboard component with Chart.js integration (task_1)"
```

---

## 🎨 Task Types Reference

| Type | Description | Commit Prefix |
|------|-------------|---------------|
| `component_creation` | UI components | `feat(ui)` |
| `api_integration` | API endpoints | `feat(api)` |
| `configuration` | Config files | `chore(config)` |
| `testing_implementation` | Tests | `test` |
| `feature_development` | Features | `feat` |
| `supabase_migration` | DB migrations | `feat(db)` |
| `supabase_rls` | Row security | `feat(security)` |
| `styling_implementation` | Styling | `style(ui)` |
| `data_modeling` | Data models | `feat(data)` |
| `bug_fix` | Bug fixes | `fix` |
| `documentation` | Docs | `docs` |
| `refactoring` | Refactoring | `refactor` |
| `performance` | Performance | `perf` |

---

## 💡 Pro Tips

### 1. Batch Operations
```bash
# Save multiple responses
npm run plan:save-response task_1 --file responses/task1.txt
npm run plan:save-response task_2 --file responses/task2.txt

# Complete all with commits
npm run plan:complete task_1 --commit
npm run plan:complete task_2 --commit
```

### 2. Custom Commit Messages
```bash
npm run plan:complete task_1 --commit --message "feat: Add dashboard with advanced analytics

- Implemented Chart.js integration
- Added real-time data updates
- Created responsive grid layout
- Added error boundaries"
```

### 3. Quick Non-interactive Mode
```bash
# Set preferences once
npm run plan:config autoCommit true
npm run plan:config interactive false

# Then work fast
npm run plan:continue
npm run plan:save-response task_1 "..."
npm run plan:complete task_1  # Auto-commits, no prompts
```

---

## 🌟 Best Practices

### For Planning
1. **Be specific** - Include exact file paths and component names
2. **Add dependencies** - Ensure logical task order
3. **Validate first** - Always validate before executing

### For Git Integration
1. **Save Claude's responses** - Better commit messages
2. **Use auto-commit** - Faster workflow
3. **Review periodically** - Check git log for clean history

### For Execution
1. **Complete tasks sequentially** - Maintain context
2. **Track progress** - Use `npm run plan:progress`
3. **Commit regularly** - One task = one commit

---

## 📚 Related Documentation

- **[Getting Started](./GETTING_STARTED.md)** - Quick start guide
- **[Claude Commit Integration](./guides/CLAUDE_COMMIT_INTEGRATION.md)** - Detailed git guide
- **[Complete Workflow Example](./guides/COMPLETE_WORKFLOW_EXAMPLE.md)** - End-to-end example
- **[Supabase Integration](./guides/SUPABASE_INTEGRATION_GUIDE.md)** - Database operations

---

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