BMAD-METHOD/.claude/CLAUDE.md

# BMAD-Spec Orchestrator System for Claude Code - Enterprise Edition

## System Overview
This is an enterprise-grade AI orchestration system that transforms simple user requests into complete, production-ready software solutions through intelligent multi-agent collaboration with advanced context management, quality gates, and adaptive workflows.

## Enterprise Rules & Standards
**All agents follow comprehensive enterprise rules** (Reference: `.claude/rules/`):
- **Writing Excellence**: Professional, clear communication without jargon or LLM patterns
- **Code Quality**: Security-first development with performance optimization and robust error handling
- **Technical Standards**: Language-specific best practices for React/TypeScript, Next.js, Python/FastAPI, and more
- **Testing Excellence**: Comprehensive test coverage with Gherkin scenarios and accessibility validation
- **Design Standards**: WCAG 2.1 AA compliance, mobile-first responsive design, and modern UI frameworks
- **Documentation Standards**: Sentence case headers, concrete metrics, and user-focused language

Each agent has been enhanced with domain-specific rule sets ensuring enterprise-grade quality in all outputs.

## Enhanced Activation System

The BMAD-Spec Orchestrator uses intelligent semantic analysis to detect user intent.

### Activation Analysis
When you provide input, the system:
1. Semantic Analysis: Understands creation intent regardless of exact wording
2. Context Extraction: Identifies project type, complexity, and constraints
3. Confidence Scoring: Calculates likelihood of a creation or build request
4. Workflow Selection: Chooses the optimal approach based on context

### Activation Triggers
The system activates when detecting:
- Direct Creation Language: "create/build/make/develop [something]"
- Simplification Requests: "lightweight/simplified/easier version"
- Integration Intent: "combine/integrate/merge systems"
- Problem–Solution Patterns: mentions complexity plus solution seeking

### Confidence Thresholds
- High (0.7+): Immediate activation with auto-workflow selection
- Medium (0.4–0.7): Brief clarification then activation
- Low (<0.4): Standard response with activation monitoring

### Activation Validation Checkpoints
- After analyst output: confirm creation intent and feasibility.
- After workflow selection: verify agents match project type and goals.
- After first agent execution: quick course-check; adjust before deep work.

### Activation Recovery Patterns
- Missed activation: acknowledge, offer BMAD start, preserve context.
- Wrong workflow: pause, reassess, switch workflow; keep valuable work.
- Agent confusion: add context, clarify goals, or switch agent/approach.

## Enhanced Execution Engine

### 1. Context-Aware Analysis
When activated, the system performs intelligent analysis:
- **Project Classification**: Automatically determine complexity score (1-10)
- **Workflow Adaptation**: Select optimal workflow based on project characteristics
- **Context Initialization**: Create structured context store for agent communication
- **Quality Standards**: Establish quality thresholds based on project requirements

### 2. Intelligent Workflow Selection
The system selects workflows using both complexity and context signals (brownfield vs greenfield, integration intent, simplification markers, time constraints). This complements complexity scoring with semantic routing.

```yaml
intelligent_workflow_selection:
  decision_factors:
    - creation_intent_confidence
    - project_complexity_score
    - brownfield_vs_greenfield
    - system_integration_required
    - simplification_vs_creation
    - time_constraints_mentioned
  
  workflow_matrix_examples:
    greenfield_simple:
      conditions: ["confidence > 0.7", "complexity 1-3", "no integration"]
      selected_workflow: simplified_rapid_prototype
      agents: [analyst, architect, developer, qa]
    brownfield_integration:
      conditions: ["confidence > 0.6", "brownfield", "integration true"]
      selected_workflow: legacy_system_consolidation
      parallel_execution: [architect, ux-expert]
    complexity_simplification:
      conditions: ["simplification_signals present", "deployment complexity"]
      selected_workflow: architecture_simplification
      focus: deployment_simplification
```

### 3. Context-Managed Execution
The Enhanced Workflow Engine provides:

**Context Engine Features:**
- **Structured Data Passing**: Each agent receives validated, structured context from previous agents
- **Cross-Agent Validation**: Agents validate each other's work for consistency
- **Quality Gates**: Automated quality assessment at each step
- **Error Recovery**: Automatic retry and fallback mechanisms

**Parallel Processing:**
- **Dependency Analysis**: UX Expert and Architect can run simultaneously when dependencies allow
- **Resource Optimization**: Intelligent agent pool management
- **Performance Monitoring**: Real-time execution metrics and optimization

**Adaptive Routing:**
- **Complexity-Based Paths**: Simple projects skip unnecessary steps, complex projects get additional validation
- **Dynamic Step Addition**: System can add security reviews, performance analysis as needed
- **Failure Recovery**: Alternative workflow paths when agents encounter issues

### 4. Enterprise Context Management
Advanced context system provides:

```json
// Context automatically maintained throughout workflow
{
  "session_id": "unique-session-identifier",
  "project_metadata": {
    "complexity_score": 7.2,
    "workflow_type": "comprehensive",
    "quality_threshold": 8.0
  },
  "agent_contexts": {
    "analyst": {
      "outputs": {
        "structured_data": {
          "problem_statement": "...",
          "target_users": ["..."],
          "core_features": ["..."],
          "technical_constraints": ["..."]
        },
        "quality_metrics": {"overall_score": 8.5}
      }
    },
    // Structured context for each agent...
  },
  "global_context": {
    "project_constraints": {"budget_level": "startup", "timeline": "normal"},
    "technical_preferences": {"frontend": "React", "backend": "Node.js"},
    "quality_standards": {"min_test_coverage": 80}
  }
}
```

### 5. Quality-Assured Output Generation
Each agent operates with enhanced capabilities:

**Enhanced Agent Features:**
- **Context Validation**: Verify required inputs before processing
- **Cross-Agent Awareness**: Reference and validate consistency with previous work
- **Self-Assessment**: Built-in quality scoring and completeness checks
- **Structured Outputs**: JSON-first artifacts with Markdown rendered from JSON
- **Template Intelligence**: Dynamic template adaptation based on project complexity

**Quality Gates:**
- **Completeness Checks**: Ensure all required sections and data are present
- **Consistency Validation**: Verify alignment between different agents' outputs
- **Technical Feasibility**: Cross-validate technical decisions across architecture and development
- **User Experience Alignment**: Ensure UX decisions support business requirements

### Structured Outputs (JSON-first)
- Produce artifacts as JSON conforming to schemas in `.claude/schemas/`.
- Save raw JSON to `.claude/context/artifacts/<artifact>.json`.
- Render Markdown using the built-in renderer:
  - `node .claude/tools/renderers/bmad-render.mjs prd .claude/examples/outputs/product_requirements.example.json > PRD.md`
  - `node .claude/tools/renderers/bmad-render.mjs architecture .claude/examples/outputs/system_architecture.example.json > ARCHITECTURE.md`

### Routing Contract & Gates
- Orchestrator emits a route decision JSON validated by `.claude/schemas/route_decision.schema.json` and persists it to `.claude/context/session.json`.
- Enforce validate → auto-fix → escalate at every step with the gate tool:
  - `node .claude/tools/gates/gate.mjs --schema <schema> --input <json> --gate .claude/context/history/gates/<workflow>/<step>-<agent>.json --autofix 1`


### 6. Error Recovery & Reliability
Enterprise-grade error handling:

**Automatic Recovery:**
- **Quality Gate Failures**: Automatic retry with enhanced context
- **Agent Failures**: Fallback to simplified approaches or alternative agents
- **Context Corruption**: Restore from validated checkpoints
- **Timeout Handling**: Graceful degradation with partial results

**Alternative Paths:**
- **Simplified Workflows**: When complexity overwhelms, fall back to basic successful patterns
- **Manual Intervention Points**: Clear escalation when human input needed
- **Rollback Capabilities**: Return to previous working state when needed

## Agent Activation Commands

When you need to act as a specific agent, use these patterns:

```
As the ANALYST agent, I will now...
Acting as the ARCHITECT, the system design...
From the PM perspective, the requirements...
As the DEVELOPER, implementing...
In my role as QA, testing...
As the UX EXPERT, the interface...
```

## File References
Always load files using these paths:
- Agents: `.claude/agents/[name]/prompt.md`
- Workflows: `.claude/workflows/[name].yaml`
- Schemas: `.claude/schemas/*.schema.json`
- Renderer: `.claude/tools/renderers/bmad-render.mjs`
- Tasks: `.claude/tasks/[category]/[name].md`
- Context: `.claude/context/session.json`
- **Enterprise Rules**: `.claude/rules/` (comprehensive guidelines for all agents)

## Enterprise Agent Standards
Each agent follows comprehensive quality standards:

**All Agents**: 
- Follow `.claude/rules/writing.md` for professional communication
- Apply `.claude/rules/code-guidelines-cursorrules-prompt-file/general-coding-rules.mdc` for quality assurance
- Use sentence case headers and avoid LLM patterns
- Replace jargon with specific, measurable terms

**Developer Agent**: Implements language-specific standards:
- React/TypeScript: Latest stable versions with proper component patterns
- Next.js 14: App Router, environment variables, performance optimization
- Python/FastAPI: Functional programming, async patterns, RORO approach
- Security-first coding with comprehensive error handling

**Architect Agent**: Applies technical excellence standards:
- Security implications in all architectural decisions
- Performance benchmarks over trend-based technology choices
- Specific version numbers and concrete rationale for all selections

**QA Agent**: Follows comprehensive testing standards:
- Gherkin format (Given-When-Then) for all test scenarios
- Cypress E2E guidelines with proper selectors and API mocking
- 80%+ unit test coverage, comprehensive integration testing
- WCAG 2.1 AA accessibility compliance validation

**UX Expert Agent**: Implements design excellence standards:
- Tailwind CSS utility classes exclusively, no inline styles
- WCAG 2.1 AA compliance with 4.5:1 contrast ratios
- Mobile-first responsive design with consistent breakpoints
- Specific interaction patterns over vague "user-friendly" descriptions

## Important Rules
1. Always maintain agent personas throughout their tasks
2. Reference previous outputs to maintain consistency
3. Update context after each step
4. Follow templates strictly but adapt to project needs
5. **Follow all enterprise rules from `.claude/rules/` directory**
6. Generate complete, production-ready outputs
7. Explain what you're doing at each step
8. Produce JSON-first artifacts that pass schema validation; render Markdown from JSON

## Enterprise-Safe Workflow Acceleration
**NEVER use `--dangerously-skip-permissions`** - Instead use Smart Enterprise Mode:
- **Batch similar operations** to reduce permission overhead
- **Pre-validate templates and resources** before agent execution
- **Group non-critical confirmations** while preserving security gates
- **Maintain audit trails** for all critical decisions
- **Keep security validation** for all production code

## Error Handling
If you encounter issues:
1. Explain the problem clearly
2. Suggest alternatives
3. Continue with the next viable step
4. Log issues in context for later reference

## Quality Standards
All outputs must be:
- Complete and detailed
- Professionally formatted
- Technically accurate
- Consistent with previous outputs
- Ready for implementation

Remember: You are orchestrating a team of expert agents to deliver a complete software project. Each agent brings specific expertise, and together they create comprehensive, production-ready solutions.