mirror-magi-meta-agent/CONTRIBUTING.md

AI-powered development planning and execution system with Supabase integration

# Contributing to Mirror Magi Meta-Agent

Thank you for your interest in contributing! 🎉

## 🚀 Quick Start

1. **Fork** the repository
2. **Clone** your fork
3. **Create** a feature branch: `git checkout -b feature/amazing-feature`
4. **Make** your changes
5. **Test** your changes: `npm test`
6. **Commit** your changes: `git commit -m 'Add amazing feature'`
7. **Push** to your branch: `git push origin feature/amazing-feature`
8. **Open** a Pull Request

## 🎯 What We're Looking For

### High Priority
- 🐛 **Bug fixes** - Especially workflow issues
- 📝 **Documentation improvements** - Make it clearer for users
- 🔧 **Core workflow enhancements** - AI → Structure → Validate → Execute
- ✨ **New AI integrations** - Support more AI assistants

### Medium Priority
- 🎨 **UI/UX improvements** - Better command outputs
- ⚡ **Performance optimizations** - Faster plan processing
- 🧪 **Test coverage** - More comprehensive testing

### Nice to Have
- 🌟 **New features** - Advanced planning capabilities
- 📦 **Integration examples** - CI/CD workflows
- 🛠️ **Developer tools** - Better debugging

## 🛠️ Development Setup

```bash
# Clone and setup
git clone https://github.com/mirror-magi/mirror-magi.git
cd mirror-magi/meta-agent
npm install

# Test your setup
npm test

# Try the CLI
npm link
mirror-magi test
```

## 📝 Code Guidelines

### JavaScript/Node.js
- **ES6+ syntax** preferred
- **Clear variable names** - `userPlan` not `up`
- **Comments** for complex logic
- **Error handling** - Always handle errors gracefully

### Documentation
- **Clear examples** - Show actual usage
- **Visual aids** - ASCII diagrams encouraged
- **Step-by-step** - Break down complex processes
- **Emojis** - Use sparingly but effectively 🎯

### Commit Messages
```
feat: add support for Gemini AI integration
fix: resolve plan validation edge case
docs: improve getting started guide
refactor: simplify command generation logic
```

## 🧪 Testing

```bash
# Run all tests
npm test

# Test specific functionality
npm run plan:validate  # Test validation
npm run plan:view      # Test plan viewing
```

### Manual Testing
1. Create a test plan with AI
2. Validate the structure
3. Execute a few tasks
4. Verify commands work with Claude Code Max

## 📋 Pull Request Checklist

- [ ] **Tests pass** - `npm test` succeeds
- [ ] **Documentation updated** - If adding features
- [ ] **Examples included** - Show how to use new features
- [ ] **Backward compatible** - Don't break existing workflows
- [ ] **Clear description** - Explain what and why

## 🎯 Project Philosophy

### Core Principles
1. **Simple workflow** - AI → Structure → Validate → Execute
2. **No placeholders** - Always generate specific commands
3. **Any AI works** - Don't lock into one provider
4. **Human control** - User structures the plan, AI executes
5. **Claude Code Max focus** - Perfect integration

### What We Avoid
- ❌ Complex multi-step setup processes
- ❌ Vendor lock-in to specific AI services
- ❌ Ambiguous or placeholder-filled commands
- ❌ Breaking the core 4-step workflow

## 🤝 Community

- **Be respectful** - Everyone's learning
- **Help others** - Answer questions when you can
- **Share examples** - Real usage helps everyone
- **Stay focused** - Keep it about the core workflow

## 📞 Getting Help

- 💬 **Issues** - For bugs and feature requests
- 📖 **Discussions** - For questions and ideas
- 📧 **Email** - contact@mirrormagi.dev for sensitive issues

---

*Let's make AI-powered development accessible to everyone!* ✨