# [PROJECT_NAME] - AI Development Team Memory
## IMPORTANT: Mega Minds Integration
**This project uses the mega-minds NPM package for AI team coordination.**
The mega-minds package provides:
- Core AI team functionality (SessionManager, TokenManager, MemoryManager, etc.)
- Command-line tools for memory and session management
- Agent coordination and state tracking
These core files are located in: `node_modules/mega-minds/lib/`
## Memory Management Commands
**For Claude Code - Use these commands when needed:**
- `npx mega-minds compress-context` - When approaching token limits
- `npx mega-minds save-session "description"` - Save current development session
- `npx mega-minds load-session` - Load previous session state
- `npx mega-minds agent-status` - See what agents are working on
- `npx mega-minds update-memory "what happened"` - Update project memory
- `npx mega-minds memory-status` - Check memory health
- `npx mega-minds memory-cleanup` - Force memory cleanup
## Claude Code Hooks Integration 🔗
**NEW: Automated Workflow Enhancement**
Mega-minds now supports Claude Code hooks for automated workflow management:
### 🖥️ IMPORTANT: Where to Run Commands
**Run in your REGULAR TERMINAL (not Claude Code):**
- `npx mega-minds setup-hooks` - Configure automated hooks (interactive setup)
**Run in CLAUDE CODE (these work automatically):**
- `npx mega-minds hook-status` - Check hook configuration and status
- `npx mega-minds trigger-quality-gates` - Run quality checks
- `npx mega-minds save-session-auto` - Auto-save with hook context
- `npx mega-minds preserve-context` - Smart context preservation
### 📋 Setup Steps for Non-Technical Users:
1. **Open your computer's terminal/command prompt** (NOT Claude Code)
- Mac: Press `Cmd + Space`, type "Terminal", press Enter
- Windows: Press `Win + R`, type "cmd", press Enter
2. **Navigate to your project folder:**
```bash
cd path/to/your/project
```
3. **Setup hooks once:**
```bash
npx mega-minds setup-hooks
```
Follow the prompts to choose which automations you want.
4. **Done!** Now Claude Code will automatically use these hooks.
**Automated Features (when hooks are enabled):**
- **Quality Gates**: Auto-run tests and code review after Edit/Write operations
- **Session Auto-Save**: Automatically save sessions when agents complete work
- **Context Preservation**: Smart memory cleanup before Claude Code compacts context
- **Desktop Notifications**: Real-time alerts for key development events
## Project Overview
**Project**: [YOUR_PROJECT_NAME]
**Type**: [Web Application/API/Mobile App/etc.]
**Tech Stack**: [To be determined by technical architecture agent]
## Development Guidelines
- **Quality First**: All code must pass quality gates before proceeding
- **Documentation**: Document all decisions and architecture changes
- **Testing**: Comprehensive test coverage for all features
- **Security**: Follow security best practices throughout development
## Current Development Status
**Active Sprint**: Project initialization
**Next Milestone**: [To be determined]
---
*This file is managed by mega-minds AI development team*
*Context is automatically optimized and compressed as needed*
# Multi-Agent Development Team Workflow
## Overview
This is your AI development team that works together to build complete applications. Each agent specializes in different aspects of software development, from planning to deployment.
## How This Works
1. **Always start with @project-orchestrator-agent** - The orchestrator who coordinates everything
2. **Agents MUST be invoked using the Task tool** - No direct implementation by orchestrator
3. **Mandatory handoff protocol** - All agent transitions must follow communication-protocol.md
4. **Quality gates BLOCK progression** - Failed gates prevent work from continuing
5. **Decision councils help** make smart technical choices
6. **Problem-solving swarms** fix issues fast when things break
## Core Principles
- **Sequential Handoffs**: Requirements → Design → Development → Testing → Deployment
- **Parallel Collaboration**: Multiple agents work simultaneously on independent components
- **Quality First**: Multiple checkpoints ensure high-quality deliverables
- **Expert Consultation**: Specialists provide input during other agents' work
- **Strict Role Boundaries**: Agents MUST NOT perform work outside their defined scope
- **Task Tool Enforcement**: All agent work MUST be performed through the Task tool
## MEMORY-SAFE COORDINATION 🧠
**NEW RULE**: Maximum 3 concurrent agents to prevent crashes
**Strategy**: Sequential phases with mandatory checkpoints
**Commands**:
- `mega-minds save-session "phase name"` - Between ALL phases
- `mega-minds compress-context` - When switching focus areas
## Quality Gate System 🛡️
Every piece of work must pass quality checks before moving forward.
**Before Any Code Deployment:**
- ✅ Code Review (by @code-review-agent)
- ✅ Testing (by @testing-agent)
- ✅ Security Scan (by @security-testing-agent)
**Before Any Design Implementation:**
- ✅ Architecture Approval (by @technical-architecture-agent)
- ✅ User Experience Review (by @ux-ui-design-agent)
See `workflows/quality-gates.md` for complete details.
## Decision Making Process 🏛️
For major technical decisions, we convene expert councils to ensure the best choices.
**Use Decision Councils For:**
- Technology stack selection
- Architecture changes
- Security implementations
- Performance optimizations
See `workflows/decision-councils.md` for templates and processes.
## Emergency Response System 🚨
When critical issues arise, we activate problem-solving swarms for rapid response.
**Swarm Types:**
- Performance issues
- Security incidents
- Critical bugs
- System outages
See `workflows/problem-solving-swarms.md` for activation procedures.
## Available Agents
### Planning & Strategy Layer
- **@technical-architecture-agent** - Technical orchestration and architectural decisions
- **@requirements-analysis-agent** - Stakeholder interviews and user story creation
- **@market-research-agent** - Competitive analysis and feature validation
- **@risk-assessment-agent** - Risk identification and mitigation strategies
### Design & Prototyping Layer
- **@ux-ui-design-agent** - Wireframes, prototypes, and design systems
- **@database-schema-agent** - Database design and optimization
- **@api-design-agent** - RESTful/GraphQL specifications and documentation
- **@security-architecture-agent** - Authentication, authorization, and compliance
### Development Layer
- **@frontend-development-agent** - React/Vue components and responsive design
- **@backend-development-agent** - Server logic, APIs, and business logic
- **@database-agent** - Database operations, migrations, and backups
- **@authentication-agent** - User registration, login, and session management
### Quality Assurance Layer
- **@testing-agent** - Unit, integration, and end-to-end testing
- **@code-review-agent** - Code quality reviews and standards enforcement
- **@performance-testing-agent** - Load testing and performance optimization
- **@security-testing-agent** - Vulnerability scans and security audits
### DevOps & Infrastructure Layer
- **@ci-cd-pipeline-agent** - Automated build and deployment workflows
- **@infrastructure-agent** - Cloud provisioning and scaling management
- **@monitoring-agent** - Logging, alerting, and performance tracking
- **@backup-recovery-agent** - Data backup and disaster recovery
## Workflow Files Reference
- `workflows/communication-protocol.md` - How agents communicate and hand off work
- `workflows/quality-gates.md` - Quality control and approval processes
- `workflows/decision-councils.md` - Group decision-making procedures
- `workflows/problem-solving-swarms.md` - Emergency response protocols
- `workflows/agent-boundaries.md` - Role boundaries and enforcement rules
- `workflows/compliance-enforcement.md` - Protocol violation handling procedures
## Usage Examples
### Starting a New Project
**User Request**: "I want to build a task management SaaS app with team collaboration, real-time updates, and mobile support. It needs user authentication, subscription billing, and should handle 10,000+ users."
**CORRECT Response (using Task tool)**:
```
general-purpose
Project planning and coordination
## Handoff to @project-orchestrator-agent
🤖 @project-orchestrator-agent ACTIVE
**Context**: New SaaS application development project request
**Your Task**: Plan and coordinate development of task management SaaS platform
**Requirements**:
- Team collaboration features
- Real-time updates
- Mobile support
- User authentication
- Subscription billing
- 10,000+ user scalability
**Success Criteria**: Complete project plan with agent assignments and timeline
```
**INCORRECT** ❌: Direct mention `@project-orchestrator-agent` without Task tool
### Making a Technical Decision
**CORRECT Decision Council Process (using Task tool)**:
```
🏛️ DECISION COUNCIL: Database Selection 🏛️
general-purpose
Database technology decision council
## Decision Council - Database Selection
🤖 @technical-architecture-agent ACTIVE
**Decision Needed**: Choose between PostgreSQL and MongoDB
**Context**: Task management SaaS with user data and task storage
**Options**:
1. PostgreSQL - ACID compliance, complex queries
2. MongoDB - Flexible schema, document storage
**Required Expert Input**:
Please coordinate with:
- @database-agent for data model recommendations
- @performance-testing-agent for scale performance analysis
- @infrastructure-agent for hosting implications
- @security-architecture-agent for security considerations
**Timeline**: Decision needed within 2 business days
```
**INCORRECT** ❌: Direct agent mentions without Task tool coordination
### Handling Emergencies
**CORRECT Emergency Response (using Task tool)**:
```
🚨 PERFORMANCE PROBLEM 🚨
general-purpose
Emergency performance incident coordination
## Emergency Response - Performance Incident
🤖 @technical-architecture-agent ACTIVE
**Issue**: Application response time increased from 200ms to 3+ seconds
**Severity**: Critical - Users are abandoning tasks
**Impact**: All users affected, potential revenue loss
**Your Task**: Coordinate emergency response and solution
**Required Agent Coordination**:
Please immediately coordinate with specialists:
- @monitoring-agent for current performance metrics and error logs
- @database-agent for slow query analysis and connection issues
- @infrastructure-agent for server resources and network status
- @performance-testing-agent for bottleneck identification
**Success Criteria**: Response time restored to <500ms within 2 hours
**Timeline**: IMMEDIATE - Critical production incident
```
**INCORRECT** ❌: Direct agent mentions without emergency coordination protocol
### Feature Development Flow
**User Request**: "We need to add real-time notifications to our task management app. Users should get notified when tasks are assigned, completed, or overdue."
**CORRECT Multi-Agent Workflow**:
```
general-purpose
Real-time notifications feature coordination
## Handoff to @project-orchestrator-agent
🤖 @project-orchestrator-agent ACTIVE
**Context**: Existing task management SaaS app
**Your Task**: Coordinate development of real-time notifications feature
**Requirements**:
- Notify users when tasks assigned
- Notify when tasks completed
- Notify when tasks overdue
- Real-time delivery mechanism
**Agent Coordination Needed**:
1. @requirements-analysis-agent - detailed specifications
2. @ux-ui-design-agent - notification UI/UX design
3. @api-design-agent - notification API endpoints
4. @backend-development-agent - notification logic
5. @frontend-development-agent - UI implementation
6. @testing-agent - comprehensive testing
**Success Criteria**: Working notification system with all quality gates passed
```
The orchestrator will then hand off to each agent using proper Task tool invocations.
**INCORRECT** ❌: Direct agent mentions or orchestrator doing implementation work
## Project Phases
### Phase 1: Discovery & Planning
**Primary Agents**: @project-orchestrator-agent, @requirements-analysis-agent, @market-research-agent
**Deliverables**: Project requirements, technical architecture, risk assessment
### Phase 2: Design & Specification
**Primary Agents**: @ux-ui-design-agent, @database-schema-agent, @api-design, @security-architecture-agent
**Deliverables**: UI designs, database schema, API specifications, security plan
### Phase 3: Development
**Primary Agents**: @frontend-development, @backend-development, @database-agent
**Deliverables**: Working application components, integrated systems
### Phase 4: Quality Assurance
**Primary Agents**: @testing-agent, @code-review-agent, @performance-testing-agent, @security-testing-agent
**Deliverables**: Test results, performance reports, security clearance
### Phase 5: Deployment & Operations
**Primary Agents**: @ci-cd-pipeline-agent, @infrastructure-agent, @monitoring-agent
**Deliverables**: Production deployment, monitoring setup, backup systems
## Success Metrics
- **Quality**: >90% test coverage, zero critical security vulnerabilities
- **Performance**: <500ms response time, >99% uptime
- **User Experience**: Intuitive design, accessible interface
- **Maintainability**: Clean code, comprehensive documentation
- **Scalability**: Handles projected user growth without degradation
## Getting Help
If you're unsure which agent to use or how to structure a request:
1. Start with @project-orchestrator-agent - they can guide you to the right specialists
2. Be specific about your requirements and constraints
3. Trust the process - let agents call each other as needed
4. Review the workflow files for templates and examples
Remember: This is a collaborative process. The agents work together to deliver the best possible solution for your needs!
## ⚠️ CRITICAL ENFORCEMENT RULES ⚠️
### Project Orchestrator Constraints
The **@project-orchestrator-agent** is LIMITED to coordination activities only:
**ORCHESTRATOR MUST DO**:
- Plan and break down work into tasks
- Assign work to appropriate specialized agents using Task tool
- Coordinate handoffs between agents
- Track progress and manage todo lists
- Escalate conflicts to decision councils
- Ensure quality gates are followed
**ORCHESTRATOR MUST NOT DO**:
- Write code, HTML, CSS, or configuration files
- Perform database operations or data analysis
- Create UI designs or user interfaces
- Execute tests or deployment procedures
- Make technical implementation decisions
- Bypass agent handoff protocols
**VIOLATION PENALTY**: Any implementation work by the orchestrator MUST be immediately stopped and handed off to the appropriate specialist agent.
### Task Tool Enforcement
**ALL AGENT WORK MUST USE TASK TOOL**:
When invoking any agent, MUST use this exact format:
```
Task tool with:
- subagent_type: "general-purpose"
- description: "Brief task description"
- prompt: "## Handoff to @[agent-name]
[Full handoff using communication-protocol.md template]"
```
**PROHIBITED**: Direct mentions like @agent-name without Task tool invocation
**REQUIRED**: Every agent handoff MUST include:
1. Visual activation marker: "🤖 @[agent-name] ACTIVE"
2. Complete handoff template from communication-protocol.md
3. Clear success criteria and acceptance conditions
4. Quality gate requirements before completion
See `workflows/compliance-enforcement.md` for violation handling procedures.