DevTeam: Claude Code Multi-Agent Dev System — Orchestration
Orchestration Hierarchy
DevTeam has a four-level orchestration stack, each level strictly delegating downward:
Level 1: Commands (/devteam:plan, /devteam:implement, /devteam:bug)
Level 2: Sprint Orchestrator (sprint execution, worktree management)
Level 3: Task Loop (single-task quality iteration, model escalation)
Level 4: Specialist Agents (implementation, quality gates, validation)
Sprint Orchestrator (Level 2)
agents/orchestration/sprint-orchestrator.md — model: opus
Responsibilities:
- Load sprint from SQLite (tasks, dependencies, parallelizable flags)
- Spawn Task Loop instances for each task (sequentially or in parallel up to
max_concurrent_tasks: 3)
- Track task completion status in SQLite after each Task Loop returns
- Call Sprint Loop agent for sprint-level validation after all tasks complete
- Create PR and sprint summary on success
The Sprint Orchestrator never writes code or runs tests. All implementation is delegated to the Task Loop.
Task Loop (Level 3)
agents/orchestration/task-loop.md — model: opus, formerly "Ralph"
The Task Loop is an iteration controller that delegates every action:
1. Call Implementation Agent(s) → specialist agents
2. Call Scope Validator → verify files changed match scope
3. Call Quality Gate Enforcer → tests, lint, types, security, coverage
4. Call Requirements Validator → check acceptance criteria
5. Evaluate results → iterate / escalate / complete
The Task Loop explicitly does NOT write code, run tests, fix issues, or make implementation decisions. Those are the specialist agents' jobs.
Iteration limit: 10 per task. After 10 iterations, task is marked failed; sprint continues.
Model Escalation (within Task Loop)
Escalation occurs when quality gates repeatedly fail:
Simple task (score 0–4): haiku → haiku → sonnet → sonnet → opus
Moderate task (score 5–8): sonnet → sonnet → opus → opus
Complex task (score 9–14): opus → opus → opus
After 2 consecutive haiku failures → escalate to sonnet. After 2 sonnet failures → escalate to opus. After 3 opus failures → Bug Council activation.
Override rules bypass complexity scoring: security and architecture tasks always start at opus; documentation tasks start at haiku.
Bug Council Pattern
Triggered when: task is critical/high severity, opus has failed 3+ times, complexity score ≥ 10, or bug_council: true is set in task metadata.
Five specialist agents run in parallel:
- Root Cause Analyst — error analysis, hypothesis generation
- Code Archaeologist — git history, regression detection
- Pattern Matcher — similar bugs, anti-patterns
- Systems Thinker — dependency graph, architectural issues
- Adversarial Tester — edge cases, security vulnerabilities
The bug-council-orchestrator synthesizes the five outputs into a solution report. Implementation then resumes through the Task Loop with the synthesized solution as additional context.
Anti-abandonment principle: the system never stops trying. After Bug Council, the Task Loop continues iteration with opus, notifying the human after max iterations are exhausted while still attempting to resolve.
Quality Gate Enforcement
agents/orchestration/quality-gate-enforcer.md runs four checks sequentially:
- Tests (run test suite; all must pass)
- Type checking (no type errors)
- Linting (no lint errors)
- Security audit (critical/high issues block completion)
- Coverage (if minimum_coverage > 0 in config)
Results are written to SQLite (quality_gates table). The PostToolUse (Bash) hook detects gate results from command output and updates state.
agents/orchestration/requirements-validator.md checks each acceptance criterion from the task's JSON against the current codebase. Unmet criteria cause re-iteration.
agents/orchestration/scope-validator.md compares modified files against the task's allowed_files/allowed_patterns list. Violations cause rollback and re-implementation.
Sprint-Level Validation
agents/orchestration/sprint-loop.md runs after all tasks in a sprint complete:
- All tasks passed quality gates
- No regressions in previously passing tests
- Sprint acceptance criteria met
- PR-ready state (clean build, passing CI)
If sprint-level validation fails, failed tasks are re-entered into the Task Loop.
Parallel Execution
max_concurrent_tasks: 3 allows up to three Task Loop instances simultaneously. Tasks eligible for parallel execution include: testing, documentation, frontend, and independent backend tasks. Sequential enforcement applies to: database migrations, security tasks, and deployments.
Worktrees are used for parallel sprint tracks when features span multiple independent workstreams. merge-tracks command handles the merge after parallel worktrees complete.
Hook-Enforced Governance
The hook layer enforces orchestration invariants at runtime:
| Hook |
Type |
Function |
| PreToolUse (Edit|Write) |
command |
Iteration limit check, circuit breaker |
| PreToolUse (Edit|Write) |
prompt |
LLM semantic scope check |
| PreToolUse (Bash) |
command |
Dangerous operation detection |
| PostToolUse (Bash) |
command |
Quality gate result detection |
| PostToolUse (Edit|Write) |
command |
File modification state tracking |
| Stop |
command |
Block exit unless gates pass or EXIT_SIGNAL |
| SubagentStart |
command |
Agent start time logging |
| SubagentStop |
command |
Agent completion logging |
| TaskCompleted |
command |
Task completion logging |
| PreCompact |
command |
State serialization before context compaction |
The Stop hook is the anti-abandonment enforcement point: an agent cannot exit until all quality gates have passed for the current task. The only escape is an explicit EXIT_SIGNAL: true in state (set by human notification after max iterations).
Agent Selection
Agent selection uses keyword matching on task title/description combined with file type detection. Matching rules live in .devteam/agent-selection.md. The Task Loop reads the matched agent slug from the task's JSON and spawns the corresponding agent from agents/{category}/{slug}.md.