MinionHive

Unleash the minions - they'll build it in parallel.

MinionHive is a Claude Code plugin that revolutionizes how you build software by providing:

• 🤖 Intelligent Task Analysis: AI determines optimal execution strategy
• ⚡ Safe Parallel Execution: AST-based conflict detection enables concurrent work without race conditions
• 🌊 Wave-Based Coordination: Tasks execute in dependency-respecting waves
• 📝 Contract-First Development: API contracts and zone boundaries designed before implementation
• ✅ Comprehensive Validation: Automated testing with local and E2E validation
• 🔍 Self-Validation: AI analyzes results and auto-fixes issues when confident
• 🎯 Full-Stack Best Practices: Frontend, Backend, Security, Performance, UX, Accessibility

Features

🎭 Intelligent Agent Orchestration

The Orchestrator Agent analyzes your task and determines the best execution strategy:

• Single domain? Handle it directly
• Multi-domain? Run conflict detection for safe parallel execution
• Need coordination? Design API contracts and zone boundaries first
• Always validate? Run tests automatically after execution

🧠 AI-Driven Domain Analysis & Conflict Detection

The Domain Analyzer Agent and Conflict Detector Agent use AI and AST analysis to decide:

• Which domains are involved (frontend, backend, database, etc.)
• Can work be parallelized safely? (AST-level dependency analysis)
• What are the conflict zones? (circular dependencies, high coupling)
• What are the API boundaries and zone boundaries?
• What's the optimal wave-based execution plan?

📋 Contract-First Development with Zone Boundaries

The API Contract Designer creates comprehensive contracts before parallel work:

• API endpoints with full type definitions
• Shared types and interfaces
• Zone boundaries (which files each agent can/cannot modify)
• Ownership rules (who owns shared code)
• Symbol contracts (shared functions/classes)
• Validation rules and error codes
• Clear documentation of assumptions

👥 Specialist Agents & Parallel Execution

Domain experts that work in safe parallel waves:

• Parallel Executor: Coordinates concurrent subagent execution
• Frontend Specialist: React, TypeScript, UX, Accessibility, Performance
• Backend Specialist: APIs, Databases, Security, Business Logic

Each specialist:

• Receives clear zone boundaries (files they can/cannot modify)
• Works within their assigned wave
• Follows comprehensive best practices
• Reports results for aggregation

✅ Comprehensive Validation & Review

The Validation Orchestrator ensures code quality before review:

• Local validation: Unit tests, type checking, linting
• E2E validation: Integration tests, browser tests
• Self-validation: AI analyzes results, creates fix plans
• Auto-fix: Applies fixes when confident, re-validates
• Configurable: User defines test commands and automation level

The Reviewer Agent then reviews and improves code across ALL domains:

• Frontend/UI best practices
• User Experience (UX)
• Accessibility (a11y)
• Backend architecture
• Security
• Performance
• Testing
• Code quality
• Documentation

With full autonomy - it makes improvements and reports what was done.

Installation

Option 1: Install via npm (Recommended) 📦

# Install globally
npm install -g @minionhive/core

# Install the plugin
minionhive install --global

# Restart Claude Code and you're ready!

Option 2: Claude Code Marketplace 🛒

# Coming soon to Claude Code marketplace!
# One-click installation from within Claude Code

Option 3: Clone from repository

# Clone and install
git clone https://github.com/GuitaristForEver/minion-hive.git
cd minion-hive
npm install
minionhive install --global

Option 4: Manual installation

# Download and copy to Claude plugins directory
cp -r /path/to/minionhive ~/.claude/plugins/minionhive

Verify Installation

# Check installation status
minionhive status

# View version
minionhive version

Usage

Smart Implementation with Safe Parallel Execution

Use /smart-implement for intelligent, parallelized feature development:

/smart-implement Add user profile page with avatar upload

What happens:

1. ✅ Orchestrator receives your request
2. ✅ Domain Analyzer determines it's a full-stack feature (frontend + backend)
3. ✅ NEW: Conflict Detector runs AST analysis to identify safe parallel zones
4. ✅ API Contract Designer creates zone boundaries and API contracts
5. ✅ NEW: Parallel Executor spawns concurrent subagents in waves:
   • Wave 1: Define shared types
   • Wave 2: Frontend UI + Backend API (parallel)
6. ✅ NEW: Validation Orchestrator runs automated tests:
   • Local: Unit tests, type checking, linting
   • E2E: Integration tests (if configured)
   • Auto-fixes issues when confident
7. ✅ Reviewer Agent reviews and improves
8. ✅ Complete implementation report with parallel execution metrics

Parallel Execution with Explicit Control

Use /parallel-execute for explicit parallel execution with conflict detection:

/parallel-execute Build analytics dashboard with real-time charts

Benefits over /smart-implement:

• Explicit parallel execution focus
• Detailed conflict analysis report
• Wave-by-wave progress tracking
• Performance metrics (speedup vs sequential)

Validation of Completed Work

Use /validate-work to validate code with automated testing:

# Validate current work
/validate-work

# Validate specific execution
/validate-work exec-2025-01-10-abc123

# Options
/validate-work --local-only    # Skip E2E tests
/validate-work --auto           # Run everything without prompts
/validate-work --config         # Configure validation

What happens:

1. Load or create validation configuration (first run)
2. Run local validation (tests, type checking, linting)
3. Run E2E validation (integration tests, browser tests)
4. Self-validate: Analyze results, identify issues
5. Auto-fix issues when confident
6. Report comprehensive results

Analyze Code Conflicts

Use /analyze-conflicts to understand dependencies and plan parallel work:

# Analyze entire codebase
/analyze-conflicts

# Analyze specific files
/analyze-conflicts src/components/UserProfile.tsx src/app/api/users/route.ts

# Generate visual graph
/analyze-conflicts --graph

Useful for:

• Planning refactors
• Understanding codebase architecture
• Debugging parallel execution issues
• Identifying conflict zones

Deep Code Review

Use /improve for comprehensive quality review:

# Review everything
/improve

# Review specific feature
/improve the authentication flow

# Review specific file
/improve src/components/UserProfile.tsx

# Focus on specific domain (but still checks others)
/improve for accessibility

What happens:

1. ✅ Reviewer Agent analyzes the code
2. ✅ Reviews across ALL domains (security, UX, a11y, performance, etc.)
3. ✅ Autonomously makes improvements (no approval needed)
4. ✅ Reports all changes made with detailed explanations

Direct Agent Invocation

You can also invoke agents directly:

# Use the orchestrator
@orchestrator implement a dashboard with real-time analytics

# Use the reviewer
@reviewer review the changes I just made

# Use domain specialists
@frontend-specialist build a responsive navigation menu
@backend-specialist create an API for user authentication

Agent Hierarchy

┌─────────────────────────────────────────────────────────────┐
│                      ORCHESTRATOR                           │
│  (Main coordinator - decides execution strategy)           │
└─────────────────────────────────────────────────────────────┘
                            │
                    ┌───────┴───────┐
                    ▼               ▼
        ┌────────────────┐  ┌──────────────────┐
        │ DOMAIN ANALYZER│  │ API CONTRACT     │
        │ (Split analysis)│  │ DESIGNER         │
        └────────────────┘  └──────────────────┘
                    │               │
                    └───────┬───────┘
                            ▼
            ┌───────────────────────────────┐
            │   PARALLEL EXECUTION          │
            ├─────────────┬─────────────────┤
            ▼             ▼                 ▼
    ┌──────────────┐ ┌──────────────┐  ┌───────┐
    │  FRONTEND    │ │   BACKEND    │  │  ...  │
    │  SPECIALIST  │ │   SPECIALIST │  │ More  │
    └──────────────┘ └──────────────┘  └───────┘
                            │
                            ▼
                    ┌──────────────┐
                    │   REVIEWER   │
                    │ (Auto-review)│
                    └──────────────┘

Examples

Example 1: Full-Stack Feature

Request:

/smart-implement Add a comment system to blog posts

Execution:

1. Domain Analyzer: "Full-stack feature - frontend + backend"
2. API Contract Designer: Creates comment types and API contracts
3. Parallel execution:
   • Frontend: Comment form, comment list, real-time updates
   • Backend: Comment API, database schema, validation, moderation
4. Reviewer: Adds rate limiting, improves accessibility, optimizes queries
5. Result: Complete, production-ready comment system

Example 2: Frontend-Only Task

Request:

/smart-implement Add dark mode toggle

Execution:

1. Domain Analyzer: "Frontend-only, no backend needed"
2. Skip conflict detection (not needed for single domain)
3. Frontend Specialist: Implements dark mode with persistence
4. Validation: All tests pass
5. Reviewer: Improves color contrast, adds keyboard shortcuts
6. Result: Accessible, polished dark mode feature

Example 3: Deep Review

Request:

/improve the checkout flow

Execution:

1. Reviewer analyzes checkout code
2. Finds issues:
   • Missing loading states → Fixed
   • Poor error messages → Improved
   • No keyboard navigation → Added
   • Slow API calls → Optimized
   • Missing ARIA labels → Added
3. Reports all improvements made

Best Practices Enforced

Frontend

• ✅ TypeScript strict typing
• ✅ React hooks best practices
• ✅ Responsive, mobile-first design
• ✅ Accessibility (WCAG AA minimum)
• ✅ Performance optimization
• ✅ Loading and error states

Backend

• ✅ Input validation (never trust client)
• ✅ SQL injection prevention
• ✅ Authentication & authorization
• ✅ Proper error handling
• ✅ Database optimization
• ✅ Security best practices

User Experience

• ✅ Clear feedback for all actions
• ✅ User-friendly error messages
• ✅ Loading indicators
• ✅ Empty states with helpful messaging
• ✅ Smooth transitions

Security

• ✅ Input sanitization
• ✅ HTTPS enforcement
• ✅ Rate limiting
• ✅ Secret management
• ✅ CORS configuration

Performance

• ✅ Code splitting
• ✅ Lazy loading
• ✅ Database indexes
• ✅ Caching strategies
• ✅ Bundle optimization

Accessibility

• ✅ Semantic HTML
• ✅ ARIA labels
• ✅ Keyboard navigation
• ✅ Screen reader support
• ✅ Color contrast (WCAG AA)

Architecture

Plugin Structure

ai-minions/
├── .claude-plugin/
│   └── plugin.json          # Plugin metadata
├── agents/
│   ├── orchestrator.md      # Main coordinator
│   ├── domain-analyzer.md   # Task analysis & splitting
│   ├── api-contract-designer.md  # Contract definition
│   ├── frontend-specialist.md    # Frontend expert
│   ├── backend-specialist.md     # Backend expert
│   └── reviewer.md          # Comprehensive reviewer
├── commands/
│   ├── improve.md           # /improve command
│   └── smart-implement.md   # /smart-implement command
├── hooks/
│   └── agent-complete.sh    # Auto-review trigger
└── README.md                # This file

How It Works

1. Request Received: User types /smart-implement [task]
2. Orchestrator Takes Control: Analyzes the request
3. Domain Analysis: AI determines optimal execution strategy
4. Contract Design (if needed): API contracts created first
5. Parallel Execution: Multiple specialists work simultaneously
6. Quality Review: Automatic comprehensive review
7. Results Delivered: Complete implementation with improvements

Configuration

No configuration needed! The plugin works out of the box with intelligent defaults.

Optional: Customize Agents

You can modify agent behavior by editing the markdown files in agents/:

# Edit the reviewer to focus on specific domains
vim agents/reviewer.md

# Customize the orchestrator's decision-making
vim agents/orchestrator.md

Philosophy

Why AI Minions?

Traditional development:

• ❌ You write frontend, then backend (sequential)
• ❌ You forget edge cases and best practices
• ❌ Code review happens manually (if at all)
• ❌ Quality inconsistent across the codebase

With AI Minions:

• ✅ Frontend + Backend work in parallel (faster)
• ✅ AI enforces best practices automatically
• ✅ Every task gets comprehensive review
• ✅ Consistent quality across all code

Core Principles

1. AI-Driven Intelligence: Let AI make smart execution decisions
2. Contract-First: Define interfaces before parallel work
3. True Parallelism: Multiple agents working simultaneously
4. Automatic Quality: Every task reviewed and improved
5. Full Autonomy: Reviewer makes improvements without approval
6. Comprehensive Coverage: All domains (frontend, backend, security, UX, a11y, performance)

Limitations

Current Limitations

1. Hook Integration: The agent-complete hook requires Claude Code native support (currently the orchestrator handles auto-review)
2. Single Project: Best suited for monorepo or single-project setups
3. Learning Period: First few uses help the system learn your codebase patterns

Future Enhancements

• Multi-project support
• Custom domain specialists (mobile, DevOps, ML, etc.)
• Configurable review priorities
• Integration with CI/CD pipelines
• Performance metrics tracking
• Team collaboration features

Troubleshooting

Agents not working?

# Check plugin is installed
claude /plugin list

# Reinstall if needed
claude /plugin remove minionhive
claude /plugin add /path/to/minionhive

Review too aggressive?

Edit agents/reviewer.md to adjust the autonomy level or prioritization.

Want faster execution?

The orchestrator already optimizes for speed through parallelism. If you want even faster, you can skip the review:

# Direct specialist invocation (skips review)
@frontend-specialist build a login form

Contributing

Contributions welcome!

Repository: https://github.com/GuitaristForEver/minion-hive

To add a new specialist agent:

1. Create agents/your-specialist.md
2. Add to plugin.json agents array
3. Update orchestrator to invoke your agent
4. Add documentation to README

Publishing

Publishing to npm

# Bump version
npm version patch  # or minor, or major

# Publish to npm
npm publish --access public

# Users can then install with:
npm install -g @minionhive/core

Claude Code Marketplace

To submit to Claude Code marketplace:

1. Ensure .claude-plugin/plugin.json is configured
2. Package includes all required metadata
3. Submit to Claude Code marketplace (details coming soon)

License

MIT License - feel free to use and modify!

See LICENSE for full details.

---

MinionHive: Where AI agents swarm together to build your software in parallel. 🐝⚡