claude-agents-manager/CLAUDE.md

Elite AI research and development platform with 60+ specialized agents, comprehensive research workflows, citation-backed reports, and advanced multi-agent coordination for Claude Code. Features deep research capabilities, concurrent execution, shared mem

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 🚨 CRITICAL: Concurrent Execution Required

**GOLDEN RULE**: Execute ALL related operations concurrently in a single message for maximum performance.

### Mandatory Concurrent Patterns:
- **File Operations**: Batch all reads/writes/edits in one message
- **Agent Spawning**: Launch related agents simultaneously  
- **Command Execution**: Run bash commands together
- **Memory Operations**: Store/retrieve data in parallel

## 🛠️ Development Commands

### Testing & Quality
- `npm test` - Run all test suites using test runner at test/run-all-tests.js
- `npm run test:memory` - Test memory system functionality
- `npm run test:concurrent` - Test concurrent execution patterns
- `npm run test:commands` - Test CLI command functionality
- `npm run test:integration` - Run integration tests
- `npm run lint` - Run ESLint on src/**/*.js files (configured with CLI-specific rules)
- `npm run format` - Format code with Prettier

### Development Commands
- `npm start` - Start the CLI tool (equivalent to `claude-agents`)
- `npm run customize` - Launch customization suite
- `npm run workflow` - Launch workflow orchestration
- `npm run demo` - Run enhanced workflow demonstration
- `npm run research-demo` - Execute research workflow example
- `npm run research-standard` - Execute standard research assignment
- `npm run research-deep` - Execute deep research assignment

### CLI Commands
- `claude-agents init` - Initialize agents in project (with --respect-context-forge option)
- `claude-agents install [agent]` - Install specific agent or interactive selection
- `claude-agents install --all` - Install all available agents
- `claude-agents run <agent> --task "task"` - Run agent independently  
- `claude-agents dashboard` - Launch web dashboard on port 7842
- `claude-agents list` - List available agents (--installed for installed only)
- `claude-agents customize` - Enterprise agent customization suite
- `claude-agents workflow` - Orchestrate multi-agent workflows
- `claude-agents research` - Elite Research Team coordination and execution
- `claude-agents uninstall` - Bulk uninstall with cleanup options

## 🏗️ Architecture Overview

This is a CLI tool for managing specialized AI agents that integrate with Claude Code.

### Core Components

**CLI System (`src/index.js`)**
- Commander.js-based CLI with commands in `src/commands/`
- Commands: init, install, list, run, dashboard, create, remove, etc.

**Agent System (`agents/` directory)**  
- 60+ specialized AI agents organized into team-based categories
- Teams: software-architecture, software-engineering, programming-languages, distributed-systems, cloud-infrastructure, security-operations, performance-reliability, devops-automation, ai-machine-learning, data-engineering, business-strategy, customer-engagement, content-documentation, elite-research, consultancy-agents, wshobson-integration
- Each agent: `agent.md` (definition), `metadata.json` (config), optional `hooks.json`
- Global access: All agents accessible by name without subdirectory paths
- Agent loading and runtime in `src/utils/agents.js` with recursive team support and context-forge integration
- Supports agent discovery across multiple installation paths (npm global, local development, etc.)
- YAML frontmatter parsing for agent metadata and tools specification

**Memory System (`src/memory/index.js`)** 
- SimpleMemoryStore class with JSON persistence in `.swarm/memory.json`
- TTL support, namespacing, pattern matching for agent coordination

**Context-Forge Integration (`src/utils/contextForgeDetector.js`)**
- Detects existing context-forge projects and preserves their structure
- Integrates with PRPs, implementation plans, and existing commands
- Automatic memory initialization for context-forge projects
- Context-aware agent enhancement with project-specific instructions
- PRP state tracking and validation gate enforcement

**Dashboard (`dashboard/` directory)**
- Next.js web interface for agent management on port 7842

## 📋 Available Agents

### Core Development Agents
- **project-planner**: Strategic planning and task decomposition
- **api-developer**: Backend API development (REST/GraphQL)
- **frontend-developer**: Modern web interface implementation
- **tdd-specialist**: Test-driven development specialist
- **code-reviewer**: Code quality, security, and best practices
- **debugger**: Error analysis and debugging specialist
- **refactor**: Code refactoring and improvement

### Specialized Agents  
- **doc-writer**: Technical documentation specialist
- **security-scanner**: Security vulnerability detection
- **devops-engineer**: CI/CD and deployment automation
- **product-manager**: Product requirements and user stories
- **marketing-writer**: Technical marketing content
- **api-documenter**: OpenAPI/Swagger documentation
- **test-runner**: Automated test execution
- **shadcn-ui-builder**: UI/UX with ShadCN components

### Agent Features
- **Enterprise-Grade Enhancement**: All agents upgraded to consultancy-level depth
- **Context-aware integration** with context-forge projects
- **Professional Methodologies**: Industry-standard frameworks and best practices
- **Executive Templates**: High-quality output formats for business stakeholders
- **Concurrent Execution**: Parallel processing for maximum efficiency
- **Shared memory system** for coordination via SimpleMemoryStore
- **Workflow Orchestration**: Multi-agent coordination for complex tasks
- **Hooks system** for automated workflows
- **Customization Suite**: Interactive enhancement and customization tools

## 🎯 Usage Patterns

### Agent Execution
```bash
# Independent execution  
claude-agents run <agent> --task "description"

# In Claude Code via slash commands
/review                    # Code review
/test                     # Run tests  
/debug "error message"    # Debug issues
/api "user endpoints"     # API development
```

### Enterprise Workflows
```bash
# Full-stack development workflow
claude-agents workflow --template fullstack-development

# Data science pipeline
claude-agents workflow --template data-science-pipeline

# Enterprise consulting engagement
claude-agents workflow --template enterprise-consulting
```

### Agent Customization
```bash
# Interactive customization suite
claude-agents customize

# Import all 44 wshobson agents with enterprise enhancements
npm run import-wshobson

# Enhance specific agent
claude-agents customize --agent api-developer
```

### Context-Forge Integration
- Agents automatically detect context-forge projects
- Preserve existing CLAUDE.md, PRPs, and implementation plans
- Commands placed in `.claude/commands/agents/` to avoid conflicts
- Memory system tracks project state and PRP execution

## 💾 Memory System

Agents coordinate through SimpleMemoryStore with JSON persistence in `.swarm/memory.json`:

### Key Features
- TTL support with automatic cleanup
- Pattern matching with wildcards (`memory.keys("agent:*")`)
- Namespacing (`agent:planner:tasks`)
- Context-forge project detection and PRP state tracking
- Agent coordination and knowledge sharing

### Context-Forge Methods
- `memory.isContextForgeProject()` - Detect context-forge projects
- `memory.getAvailablePRPs()` - List available PRPs  
- `memory.getPRPState(filename)` - Get PRP execution state
- `memory.getImplementationProgress()` - Get implementation progress

## 🪝 Hooks System

Automated workflows triggered by agent actions in `hooks.json`:

### Hook Types
- `PostToolUse:Edit` - After file modifications
- `PostToolUse:Write` - After file creation  
- `PostToolUse:Bash` - After command execution
- `TaskComplete` - After agent task completion

### Example Hook Configuration
```json
{
  "PostToolUse:Edit": {
    "commands": ["npm run lint", "npm test"]
  }
}
```

## 🧪 Testing

### Test Commands
- `npm test` - Run all test suites
- `npm run test:memory` - Memory system tests
- `npm run test:concurrent` - Concurrent execution tests  
- `npm run test:commands` - CLI command tests

### Test Structure  
- `test/run-all-tests.js` - Main test runner with comprehensive coverage
- `test/memory.test.js` - Memory system tests including TTL and context-forge integration
- `test/concurrent-execution.test.js` - Concurrency pattern tests for parallel operations
- `test/commands.test.js` - CLI command functionality tests
- `test/context-forge-integration.test.js` - Context-forge project detection and integration tests

## 🔧 Development Notes

### Key Principles
- **Always execute operations concurrently** when possible
- **Use specialized agents** for domain-specific tasks
- **Leverage memory system** for agent coordination
- **Test after significant changes** using appropriate test commands
- **Follow ESLint configuration** - CLI-specific rules allow console.log, process.exit, and flexible error handling
- **Respect agent discovery paths** - System searches multiple locations for agent installation compatibility

### Code Quality Standards
- ESLint configuration optimized for CLI tools (see `.eslintrc.cjs`)
- Prettier formatting for consistent code style
- Comprehensive test coverage with isolated test environments
- Error handling with graceful degradation for missing dependencies

### Context-Forge Projects
- System automatically detects context-forge projects
- Preserves existing PRPs and implementation plans
- Commands placed in `.claude/commands/agents/` to avoid conflicts
- Memory tracks project state and PRP execution status