# BMAD-Spec Orchestrator documentation

Welcome to the complete documentation for the Claude-native BMAD-Spec Orchestrator system. This enterprise-grade AI orchestration platform transforms simple requests into production-ready software through 10 specialized agents working with Claude Code.

## Documentation structure

### 📚 User guides
- **[Getting started](user-guide/getting-started.md)** - Set up and create your first project in 10 minutes
- **[Agent reference](user-guide/agent-reference.md)** - Complete guide to all 10 AI agents 
- **[Workflow guide](user-guide/workflow-guide.md)** - Understanding adaptive workflows and complexity scoring
- **[Templates guide](user-guide/templates-guide.md)** - Using the 11 document templates effectively

### 🔧 API documentation
- **[Claude Code integration](api/claude-code-integration.md)** - Complete Claude Code setup and activation
- **[Agent API](api/agent-api.md)** - How agents communicate and share context
- **[Template API](api/template-api.md)** - Template variable system and customization

### 🚀 Deployment
- **[Installation](deployment/installation.md)** - Step-by-step setup for any project
- **[Configuration](deployment/configuration.md)** - Advanced system configuration options
- **[Troubleshooting](deployment/troubleshooting.md)** - Common issues and solutions

### 💡 Examples
- **[Basic projects](examples/basic-projects.md)** - Simple applications to get started
- **[Enterprise projects](examples/enterprise-projects.md)** - Complex systems and workflows
- **[Custom implementations](examples/custom-implementations.md)** - Advanced customization patterns

## Quick navigation

### New to BMAD-Spec Orchestrator
1. **[Installation guide](deployment/installation.md)** - Copy the `.claude` folder to your project
2. **[Getting started](user-guide/getting-started.md)** - Ask Claude to build your first app
3. **[Basic projects](examples/basic-projects.md)** - Learn through hands-on examples

### Experienced users
- **[Agent reference](user-guide/agent-reference.md)** - Deep dive into all 10 agents
- **[Advanced configuration](deployment/configuration.md)** - Customize for your needs
- **[Enterprise examples](examples/enterprise-projects.md)** - Complex workflow patterns

### System administrators
- **[Installation guide](deployment/installation.md)** - Enterprise deployment patterns
- **[Configuration](deployment/configuration.md)** - Security and performance tuning
- **[Claude Code integration](api/claude-code-integration.md)** - Complete setup reference

## How it works

The BMAD-Spec Orchestrator uses 10 specialized AI agents working through Claude Code to transform natural language requests into complete software solutions.

### Core agents (6)
- **🔍 Analyst** - Requirements and market research
- **📋 PM** - Product management and specifications  
- **🏗️ Architect** - System design with security-first approach
- **🎨 UX Expert** - User experience and interface design
- **💻 Developer** - Full-stack development and testing
- **🧪 QA** - Comprehensive quality assurance

### Orchestration agents (4)
- **🧙 BMAD Master** - Universal task executor
- **🎭 BMAD Orchestrator** - Workflow coordination
- **📝 Product Owner** - Backlog and story management
- **🏃 Scrum Master** - Process facilitation

### Intelligence features
- **Claude thinking optimization** - Uses `ultrathink`, `think harder`, `think hard` for optimal decision quality
- **Complexity scoring** - Automatically selects appropriate workflows (1-10 scale)
- **Context preservation** - Maintains perfect context across all agent interactions
- **Quality gates** - Comprehensive validation at every step

## Key concepts

### Agent activation
Agents activate automatically when you describe what you want to build:
```
"I need to create a web application for project management"
```

Claude recognizes this as a trigger and activates the orchestration system.

### Thinking optimization
Each agent uses Claude-specific thinking triggers for optimal performance:
- **`ultrathink`** - Critical decisions (architecture, security)
- **`think harder`** - Complex analysis (risk assessment, prioritization)  
- **think hard`** - Important tasks (market research, UX design)
- **`think`** - Standard reasoning and validation

### Quality standards
All agents follow enterprise rules from `.claude/rules/`:
- Professional writing without corporate jargon
- Security-first development practices
- 80%+ test coverage requirements
- WCAG 2.1 AA accessibility compliance
- Performance optimization throughout

## Enterprise features

### Security-first approach
- **Never bypasses permissions** - No dangerous shortcuts
- **Comprehensive validation** - Every output verified
- **Audit trails** - Complete decision logging
- **Zero-trust architecture** - Security built into every component

### Performance optimization
- **Parallel execution** - UX Expert and Architect run simultaneously
- **Intelligent caching** - Reduces redundant processing  
- **Context optimization** - Structured data passing between agents
- **Resource management** - Efficient computational allocation

### Quality assurance
- **Cross-agent validation** - Agents verify each other's work
- **Automated quality gates** - Every output meets thresholds
- **Error recovery** - Automatic retry with improved context
- **Continuous improvement** - System learns from patterns

## Support

- **Documentation issues** - [Report problems with these docs](https://github.com/oimiragieo/BMAD-SPEC-KIT/issues)
- **System issues** - [Problems with agent execution or quality](https://github.com/oimiragieo/BMAD-SPEC-KIT/issues)
- **Feature requests** - [Suggestions for new capabilities](https://github.com/oimiragieo/BMAD-SPEC-KIT/discussions)
- **Community discussions** - [Share experiences and patterns](https://github.com/oimiragieo/BMAD-SPEC-KIT/discussions)

## Contributing

The system supports customization and extensions:
- **Custom agents** - Add specialized domain expertise
- **Custom workflows** - Create patterns for specific use cases  
- **Custom templates** - Adapt documentation to your standards
- **Custom rules** - Add organization-specific quality standards

See the configuration guide for details on extending the system.

---

**Built for enterprise software development with Claude Code**