Implement role-type architecture and all-phase agent mapping

[williamthorsen]

Description

The orchestration visualizer currently hardcodes 4 agent roles (architect, planner, coder, reviewer) in the mapper, leaving stations 4-6 (simplifier, holistic, summary) unpopulated. Agent visuals are keyed to individual role names, which means every new orchestration agent type would require Factory code changes.

This ticket introduces a RoleType abstraction (5 types: orchestrator, analyst, planner, author, reviewer) and extends the mapper to create agents for all 7 phases. Agent appearance is determined by roleType, making the visualization extensible without code changes when new agent roles are added to the orchestration system.

Part of Phase 4 ("Character sprites and animation") from #1.

Acceptance criteria

Must have

• RoleType union type defined with 5 values: orchestrator, analyst, planner, author, reviewer
• Phase-to-roleType mapping constant covering all 7 phases
• AgentConfig includes roleType and stackOffset fields
• buildAgents() creates agents for all 7 phases (architecture through summary)
• Parallel review station creates one agent per entry in parallelReview.reviewers map
• Agents at the same station stack vertically using stackOffset
• AgentActor constructor takes RoleType and uses ROLE_TYPE_COLORS for coloring
• Test fixtures updated with realistic all-phase data (named reviewers, simplifier, holistic)
• All existing tests updated; new tests for all-phase agent creation, parallel reviewer stacking, edge cases

Should have

• Simplifier agent only created when codeSimplifier.ran === true
• Orchestrator agent only created when run status is completed
• Legacy review format (phases.review) produces single reviewer agent
• Empty reviewers map produces single generic "reviewer" agent

Nice to have

• Role-type constants test verifying coverage of all PHASE_NAMES entries

Dependencies

None — this is the foundation ticket.

[williamthorsen]

Implementation notes (from planning session, 2026-02-26)

These notes capture initial exploration and a proposed approach.
The implementer should verify assumptions and adapt as needed.

Files to create

File	Purpose
src/shared/constants/role-types.ts	RoleType union, PHASE_ROLE_TYPE map, ROLE_TYPE_COLORS map
src/shared/constants/__tests__/role-types.test.ts	Verify coverage of all PHASE_NAMES and palette colors

Files to modify

File	Changes
src/client/game/mappers/run-to-scene.ts	Add roleType + stackOffset to AgentConfig; rewrite buildAgents for all 7 phases; pass status.status to buildAgents
src/client/game/actors/AgentActor.ts	Constructor takes RoleType; use ROLE_TYPE_COLORS instead of ROLE_COLORS
src/client/game/scenes/FactoryScene.ts	Pass roleType to AgentActor; compute y-position from stackOffset (y = 320 - stackOffset * 20)
src/__test-helpers__/fixtures.ts	Update createCompletedRunPhases() with named reviewers, codeSimplifier, holisticReview
src/client/game/mappers/__tests__/run-to-scene.test.ts	New tests for all-phase agents, parallel reviewers, stacking, edge cases
src/client/game/actors/__tests__/AgentActor.test.ts	Test all 5 roleTypes with expected colors
src/client/game/scenes/__tests__/FactoryScene.test.ts	Update for roleType constructor signature and vertical stacking

Key interface

// role-types.ts
export type RoleType = 'orchestrator' | 'analyst' | 'planner' | 'author' | 'reviewer';

// run-to-scene.ts
export interface AgentConfig {
  role: string;         // Display label (e.g., "correctness-reviewer")
  roleType: RoleType;   // Visual identity (one of 5 types)
  stationIndex: number;
  stackOffset: number;  // Vertical offset for stacking at same station
}

buildAgents logic

architecture present       → { role: 'architect',          roleType: 'analyst',      station: 0 }
planning present           → { role: 'planner',            roleType: 'planner',      station: 1 }
implementation present     → { role: 'coder',              roleType: 'author',       station: 2 }
parallelReview.reviewers   → one agent per entry, each     roleType: 'reviewer',     station: 3, stackOffset: i
legacy review present      → { role: 'reviewer',           roleType: 'reviewer',     station: 3 }
codeSimplifier.ran         → { role: 'simplifier',         roleType: 'reviewer',     station: 4 }
holisticReview present     → { role: 'holistic-reviewer',  roleType: 'reviewer',     station: 5 }
run completed              → { role: 'orchestrator',       roleType: 'orchestrator', station: 6 }

Verification

1. pnpm run ws test && pnpm run ws typecheck && pnpm run ws lint
2. Manual: pnpm run dev → select a completed run → agents visible at all active stations
3. Manual: parallel reviewers stack vertically at review station

---

Plan artifact: ~/.ai/projects/codeassembly/tickets/CODY-5.1/20260226-2130Z_role-type-architecture_plan.md

[williamthorsen]

Closed by #8