11 KiB

Raw Blame History

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

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:

# 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

Detection Phase
- Claude Code scans .claude/agents/ directory
- Loads each agent's prompt.md file
- Parses agent capabilities and specializations
Context Building
- Integrates enterprise rules from .claude/rules/
- Loads knowledge bases from .claude/data/
- Prepares templates and tasks
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:

# 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/:

# 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/:

# 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

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

Missing Enterprise Rules

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

Context Not Preserving

# 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

Start with clean project directory
Copy entire .claude folder from repository
Verify all subdirectories are present
Test with simple agent activation

Agent Usage

Use clear, project-oriented language
Specify complexity level when known
Request specific thinking levels for critical decisions
Allow agents to complete full workflows

Maintenance

Keep .claude folder in version control
Update agents periodically from source repository
Customize rules for organization needs
Monitor agent performance and adjust accordingly

Support Resources

Integration Issues: GitHub Issues
Configuration Help: GitHub Discussions
Advanced Usage: Custom Implementations Guide

Optimized for Claude Code enterprise development

11 KiB Raw Blame History