# Agent Orchestration Rule

> **How agents work together and when to invoke them.**

---

## When Applied

- Starting new features
- Fixing bugs
- Code review
- Security-sensitive changes
- Documentation updates

---

## Agent Auto-Invocation

Agents automatically invoke based on context:

### Feature Development
```
New Feature Request
       ↓
[Planner Agent] → Creates implementation plan
       ↓
[TDD Guide] → Ensures tests written first
       ↓
Implementation
       ↓
[Code Reviewer] → Reviews completed code
       ↓
[Security Reviewer] → If auth/input code
       ↓
[Doc Updater] → Updates documentation
```

### Bug Fix
```
Bug Report
       ↓
[TDD Guide] → Write failing test first
       ↓
Fix Implementation
       ↓
[Build Error Resolver] → If build breaks
       ↓
[Code Reviewer] → Reviews fix
```

### Code Changes
```
Code Written
       ↓
[Code Reviewer] → Auto-reviews changes
       ↓
[Security Reviewer] → If security-relevant
```

---

## Agent Invocation Triggers

| Agent | Auto-Triggers |
|-------|---------------|
| Planner | New feature requests |
| TDD Guide | Any implementation task |
| Build Error Resolver | Build/type failures |
| Code Reviewer | After code is written |
| Security Reviewer | Auth, input handling, secrets |
| Doc Updater | API changes, new features |
| E2E Runner | UI feature completion |
| Refactor Cleaner | On cleanup requests |
| Architect | Complex system design |

---

## Orchestration Patterns

### Sequential (Default)
```
Agent A → Agent B → Agent C
```
Each agent completes before the next starts.

### Parallel (When Independent)
```
Agent A ──┐
          ├──→ Continue
Agent B ──┘
```
Independent agents run simultaneously.

### Conditional
```
Agent A
   │
   ├── If security code → Security Reviewer
   │
   └── If UI code → E2E Runner
```

---

## Manual Override

### Skip Agent
```bash
/plan --skip-tdd    # Skip TDD enforcement
```

### Force Agent
```bash
/security-review    # Force security review
```

### Chain Agents
```bash
/orchestrate feature    # Full feature workflow
```

---

## Agent Communication

### Context Passing
Agents share context through:
1. Session state
2. File modifications
3. Todo list updates

### Handoff Pattern
```
Planner creates plan
   ↓
Plan stored in session state
   ↓
TDD Guide reads plan
   ↓
Implements with tests
   ↓
Code Reviewer sees changes
```

---

## Conflict Resolution

When agents disagree:

1. **Security always wins** - Security concerns override other suggestions
2. **User decides** - Present options for user choice
3. **Higher severity wins** - CRITICAL > HIGH > MEDIUM

---

## Configuration

In `.claude/settings.json`:

```json
{
  "agents": {
    "autoInvoke": true,
    "skipAgents": [],
    "forceAgents": ["tdd-guide"],
    "orchestration": {
      "feature": ["planner", "tdd-guide", "code-reviewer"],
      "bugfix": ["tdd-guide", "code-reviewer"]
    }
  }
}
```

---

## Enforcement

Orchestration rules ensure:
1. TDD always applied to implementations
2. Security review for sensitive code
3. Code review before commits
4. Documentation stays current
