BMAD-METHOD/docs/api/claude-code-integration.md

# Claude Code Integration

Complete guide to setting up and optimizing the BMAD-Spec Orchestrator system with Claude Code.

## Overview

The BMAD-Spec Orchestrator is specifically designed for Claude Code, leveraging Claude's unique capabilities for maximum performance in enterprise software development.

## System Architecture

```mermaid
graph TB
    Claude[Claude Code] --> Detector[".claude Folder Detection"]
    Detector --> Loader["Agent System Loader"]
    Loader --> Context["Context Builder"]
    
    Context --> Agents["10 Specialized Agents"]
    Agents --> Rules["Enterprise Rules Engine"]
    Rules --> Thinking["Claude Thinking Optimizer"]
    
    Thinking --> Output["Optimized AI Responses"]
    Output --> Validation["Quality Gates"]
    Validation --> Delivery["Production-Ready Code"]
```

## Installation Integration

### Automatic Detection

Claude Code automatically detects and loads the orchestrator when it finds:

```
your-project/
├── .claude/
│   ├── CLAUDE.md              # Main configuration
│   ├── agents/                # 10 specialized agents
│   │   ├── analyst/
│   │   ├── pm/
│   │   ├── architect/
│   │   ├── developer/
│   │   ├── qa/
│   │   ├── ux-expert/
│   │   ├── bmad-master/
│   │   ├── bmad-orchestrator/
│   │   ├── product-owner/
│   │   └── scrum-master/
│   ├── rules/                 # Enterprise standards
│   ├── data/                  # Knowledge bases
│   ├── templates/             # Document templates
│   ├── tasks/                 # Procedural tasks
│   └── checklists/            # Quality assurance
```

### Configuration File

The main `CLAUDE.md` file configures the entire system:

```markdown
# BMAD-Spec Orchestrator System

## Agent Activation Triggers
- Development requests
- Architecture planning
- Quality assurance needs
- User experience design

## Enterprise Rules Integration
All agents follow comprehensive standards from:
- Writing excellence rules
- Code quality standards
- Security requirements
- Design principles
```

## Agent Integration

### Agent Loading Process

1. **Detection Phase**
   - Claude Code scans `.claude/agents/` directory
   - Loads each agent's `prompt.md` file
   - Parses agent capabilities and specializations

2. **Context Building**
   - Integrates enterprise rules from `.claude/rules/`
   - Loads knowledge bases from `.claude/data/`
   - Prepares templates and tasks

3. **Optimization Phase**
   - Applies Claude thinking triggers
   - Configures quality gates
   - Establishes agent communication protocols

### Agent Activation Patterns

#### Automatic Activation
```
User: "I need to create a web application for inventory management"

Claude Response:
🎯 BMAD-Spec Orchestrator Activated
📊 Complexity Assessment: Level 6/10 - Medium Enterprise Application
🔄 Recommended Workflow: greenfield-fullstack

Activating Analyst Agent for market research and competitive analysis...
```

#### Specific Agent Requests
```
User: "Activate the Architect agent to design a microservices system"

Claude Response:
🏗️ Architect Agent Activated

*ultrathink* about comprehensive microservices architecture...

Based on enterprise rules and security-first principles, I'll design 
a robust microservices system with:
- API Gateway pattern
- Service mesh architecture  
- Zero-trust security model
- Comprehensive monitoring
```

## Claude Thinking Optimization

### Thinking Trigger Hierarchy

The system uses Claude-specific thinking triggers for optimal decision quality:

#### `ultrathink` - Critical Decisions
- **Architecture design** - System design and technology selection
- **Security analysis** - Threat modeling and protection strategies  
- **Performance optimization** - Scalability and efficiency planning

#### `think harder` - Complex Analysis
- **Risk assessment** - Technical and business risk evaluation
- **Trade-off analysis** - Technology and design decision evaluation
- **Integration planning** - System interconnection strategies

#### `think hard` - Important Tasks
- **Market research** - Competitive analysis and opportunity assessment
- **UX design** - User experience and interface planning
- **Quality planning** - Testing and validation strategies

#### `think` - Standard Reasoning
- **Validation tasks** - Verification and consistency checks
- **Documentation** - Technical writing and specification creation
- **Implementation** - Code generation and development tasks

### Performance Optimization

#### Context Management
- **Structured data passing** - Agents share structured context
- **Memory optimization** - Efficient information retention
- **Context preservation** - No information loss between agents

#### Parallel Execution
- **UX Expert + Architect** - Simultaneous design and architecture work
- **Developer + QA** - Concurrent implementation and testing
- **Multiple validation** - Parallel quality assurance processes

## Enterprise Rules Integration

### Rule Categories

The system enforces comprehensive enterprise standards:

#### Writing Excellence (`/rules/writing-excellence.md`)
- Professional, human-like communication
- No corporate jargon or AI patterns
- Clear, actionable documentation
- Consistent terminology across agents

#### Code Quality (`/rules/code-quality.md`)
- 80%+ test coverage requirement
- Security-first development practices
- Performance optimization standards
- Clean code principles

#### Security Standards (`/rules/security.md`)
- Zero-trust architecture principles
- Comprehensive validation requirements
- Audit trail maintenance
- No dangerous permission bypasses

#### Design Standards (`/rules/design-standards.md`)
- WCAG 2.1 AA accessibility compliance
- Mobile-first responsive design
- Performance-optimized interfaces
- User-centered design principles

### Rule Application

Each agent automatically integrates rules:

```markdown
# Example: Developer Agent Integration

## Core Instructions
You are an enterprise Full-Stack Developer focused on production-ready code.

**Enterprise Rules Applied:**
- Code Quality: 80%+ test coverage, security-first practices
- Writing: Professional communication without AI jargon
- Security: Zero-trust principles, comprehensive validation
- Design: Accessibility compliance, performance optimization

**Thinking Optimization:**
- Use `think harder` for complex technical decisions
- Use `think` for implementation and validation tasks
```

## Quality Gates

### Validation Layers

#### Agent-Level Validation
- Each agent validates its own output against enterprise rules
- Consistency checks with previous agent work
- Quality threshold verification

#### Cross-Agent Validation  
- Agents verify each other's work for consistency
- Context preservation validation
- Integration point verification

#### System-Level Gates
- Enterprise rule compliance validation
- Security requirement verification
- Performance standard checks

### Error Recovery

#### Automatic Retry
- Failed outputs trigger context improvement
- Enhanced prompts with failure analysis
- Iterative improvement until quality gates pass

#### Context Enhancement
- Additional context provided on retry
- Specific failure points addressed
- Learning integration for future improvements

## Advanced Configuration

### Custom Agent Development

Create custom agents by adding to `.claude/agents/`:

```
custom-agent/
├── prompt.md              # Agent definition and capabilities
├── expertise.md           # Domain-specific knowledge
└── guidelines.md          # Custom operation guidelines
```

### Enterprise Rule Customization

Modify rules in `.claude/rules/`:

```markdown
# custom-industry-standards.md

## Industry-Specific Requirements
- Compliance with HIPAA/SOX/GDPR
- Industry-specific security frameworks
- Custom documentation standards
- Domain expertise requirements
```

### Template System Integration

The system uses templates from `.claude/templates/`:

```yaml
# custom-template.yaml
template:
  id: "custom-document"
  name: "Custom Enterprise Document"
  version: "1.0.0"
  
workflow:
  interaction_mode: "incremental"
  
sections:
  - id: "executive-summary"
    title: "Executive Summary"
    instruction: "Create comprehensive executive summary following enterprise writing standards"
```

## Troubleshooting Integration

### Common Issues

#### Agents Not Loading
```bash
# Check folder structure
ls -la .claude/agents/*/
# Should show prompt.md in each agent directory
```

#### Missing Enterprise Rules
```bash
# Verify rules directory
ls -la .claude/rules/
# Should show: writing-excellence.md, code-quality.md, security.md, etc.
```

#### Context Not Preserving
```bash
# Check CLAUDE.md configuration
cat .claude/CLAUDE.md
# Should reference context preservation and agent communication
```

### Performance Issues

#### Large Context Size
- Remove unused agents from `.claude/agents/`
- Minimize data files in `.claude/data/`
- Optimize templates in `.claude/templates/`

#### Slow Agent Activation
- Check for large files in `.claude/` subdirectories
- Optimize agent prompt files
- Remove unnecessary checklists and tasks

## API Reference

### Agent Activation API

Direct agent activation through Claude Code:

```
# Activate specific agent
"Activate the [Agent Name] agent to [specific task]"

# Multi-agent workflow
"I need the Analyst, PM, and Architect agents to collaborate on [project]"

# Complexity-based activation
"Create a [simple/medium/complex] application for [purpose]"
```

### Context Query API

Access system information:

```
# System status
"Show me the BMAD-Spec Orchestrator system status"

# Agent capabilities
"What can the [Agent Name] agent do?"

# Available templates
"List all available document templates"

# Rule summary
"Summarize the enterprise rules for [category]"
```

## Best Practices

### Project Setup
1. Start with clean project directory
2. Copy entire `.claude` folder from repository
3. Verify all subdirectories are present
4. Test with simple agent activation

### Agent Usage
1. Use clear, project-oriented language
2. Specify complexity level when known
3. Request specific thinking levels for critical decisions
4. Allow agents to complete full workflows

### Maintenance
1. Keep `.claude` folder in version control
2. Update agents periodically from source repository
3. Customize rules for organization needs
4. Monitor agent performance and adjust accordingly

## Support Resources

- **Integration Issues**: [GitHub Issues](https://github.com/oimiragieo/BMAD-SPEC-KIT/issues)
- **Configuration Help**: [GitHub Discussions](https://github.com/oimiragieo/BMAD-SPEC-KIT/discussions)
- **Advanced Usage**: [Custom Implementations Guide](../examples/custom-implementations.md)

---

**Optimized for Claude Code enterprise development**