<!-- Generated by Ruler -->


<!-- Source: .ruler/workflow_configuration.md -->

# CrewAI Workflow Configuration (v2.0)

## Architecture Overview

The crew system is organized into three phases with QA gates:

```
DESIGN → IMPLEMENTATION → ASSET GENERATION
  ↓           ↓              ↓
 QA          QA             QA + HITL
```

## Crews and Agents

### Design Phase Crews

**WorldDesignCrew**
- World Architect: High-level world structure
- Biome Designer: Individual biome specifications
- Ecosystem Specialist: Ecological relationships

**CreatureDesignCrew**
- Creature Designer: Species concepts and stats
- Behavior Specialist: AI patterns (Yuka.js)
- Stats Balancer: Numerical balance

**GameplayDesignCrew**
- Systems Designer: Core gameplay loops
- Combat Designer: Combat mechanics
- Economy Designer: Resources and progression

### Implementation Phase Crews

**ECSImplementationCrew**
- ECS Architect: Component schema design
- TypeScript Engineer: Type-safe implementation
- Systems Engineer: System logic

**RenderingCrew**
- Shader Engineer: GLSL for water/terrain
- R3F Specialist: React Three Fiber scenes
- Performance Engineer: Mobile optimization

### Operations Crews

**AssetPipelineCrew**
- Asset Director: Overall asset strategy
- Prompt Engineer: Meshy prompt optimization
- Asset QA: Quality assessment

**QAValidationCrew**
- Design Reviewer: Document quality
- Code Reviewer: TypeScript correctness
- Integration Tester: End-to-end validation

## LLM Configuration

All agents use Anthropic Claude directly for best code generation:

```python
from crew_agents.config.llm import get_llm

# Default - Claude 3.7 Sonnet
llm = get_llm()

# Or specify a model
llm = get_llm("claude-3-5-sonnet-20241022")
```

Environment variable: `ANTHROPIC_API_KEY` (primary) or `OPENROUTER_API_KEY` (fallback)

## Flow Patterns

### Self-Evaluation Loop

```python
@router(review_step)
def check_approval(self):
    if "APPROVED" in self.state.review.upper():
        return "next_phase"
    elif self.state.retry_count < self.state.max_retries:
        return "retry"
    else:
        return "next_phase"  # Proceed with warning
```

### Human-in-the-Loop (HITL)

Asset generation includes human approval via GitHub Issues:

```python
@listen("human_approval_gate")
def create_hitl_issue(self):
    # Creates GitHub issue for human review
    # Actual approval happens via webhook callback
    return {"status": "awaiting_human_approval"}
```

## Tool Access

Crews have access to tools based on their role:

| Crew | Tools |
|------|-------|
| All Design Crews | None (pure LLM reasoning) |
| ECS Implementation | File system (future) |
| Rendering | File system (future) |
| Asset Pipeline | Meshy API |
| QA Validation | File system, shell |

## Deliverable Standards

Every CrewAI task output must include:

1. **Design Docs**: Markdown format matching contracts in `shared/contracts/`
2. **Code**: TypeScript with zero errors, following `.ruler/` patterns
3. **QA Status**: Explicit APPROVED/REJECTED verdict
4. **Integration Notes**: How output connects to next phase

## Running Flows

```bash
# Run design phase
uv run crew_agents design

# Run implementation
uv run crew_agents implement

# Run asset generation
uv run crew_agents assets

# Run complete pipeline
uv run crew_agents full
```

## Configuration Files

Each crew has its own config directory:

```
crews/<crew_name>/config/
├── agents.yaml    # Agent definitions (role, goal, backstory)
└── tasks.yaml     # Task definitions (description, expected_output)
```

## See Also

- Main README: `python/crew_agents/README.md`
- CrewAI Docs: https://docs.crewai.com/
- OpenRouter: https://openrouter.ai/
