Factory visualization: two-level catwalk layout with artifact lifecycle

[williamthorsen]

Problem

The Factory visualization renders orchestrated development runs as a 2D Excalibur game scene, but currently lacks visual representation of several core aspects of the orchestration process:

1. Code as a fabricated product — the visualization doesn't show code being made; artifacts appear as uniform colored squares with no lifecycle
2. Orchestrator as hub/dispatcher — the orchestrator walks linearly through stations, but in reality it dispatches work to agents, collects results, consolidates reviews, and shuttles between stations
3. Review-fix cycle — the iterative loop (coder receives consolidated findings → fixes code → re-delivers) is completely invisible
4. Artifact provenance — no way to see who produced each artifact, how it was consumed, or its relationship to other artifacts
5. Parallel work — reviewers working simultaneously is indistinguishable from sequential work

Relevant considerations

• This is above all an educational tool about code orchestration. Visual clarity for understanding the process takes priority over game aesthetics.
• The visualization should be flexible enough to represent any orchestrated workflow, not just the current 7-phase pipeline. The orchestrate skill is generic; if we handle its abstractions (phases, subagents, artifacts, iterations), we can visualize any run.
• Placeholder fidelity is fine — labeled blocks for artifacts, existing sprites for agents. The goal is to get placement, movement, and state transitions right as a skeleton for future development (item sprites, tooltips, interactivity come later).
• The existing Excalibur game engine (v0.32), sprite system, gate animations, and multi-level layout support provide a solid foundation to build on.

Proposed solution

Redesign the factory layout as a two-level factory with:

• Catwalk (upper level) — The orchestrator walks here exclusively, acting as a foreman/dispatcher. It never descends to the ground floor.
• Ground floor (lower level) — Workstations arranged left-to-right in phase order, with subagents at each station.
• Vertical chutes — Connect catwalk to ground stations. Artifacts visibly descend (dispatch) and ascend (collection) through these chutes. Parallel dispatch (review phase) activates all chutes simultaneously.
• Three-beat cycle — Every phase follows: Dispatch (artifact descends) → Work (agent animates, new artifact materializes) → Collect (artifact ascends to orchestrator).
• Review-fix shuttle — The orchestrator physically walks back and forth between the coder and review stations on the catwalk, carrying code forward and consolidated fixes backward. Round counter shows iteration progress. Selective re-review activates only affected reviewers.
• Three-layer artifact model:
  • Station records (always visible): copies of artifacts at producing stations, with stacking for superseded versions
  • Conveyor artifacts (visible during movement): items carried by the orchestrator, with opacity reflecting lifecycle state
  • Paper trail (on-click, post-run): thin glowing lines connecting artifacts to their sources, revealing the dependency chain

Acceptance criteria

• Two-level layout renders: catwalk above, ground-floor stations below, with vertical chute lines connecting them
• Orchestrator walks exclusively on the catwalk, never on the ground floor
• Artifacts descend through chutes (dispatch) and ascend through chutes (collection) with visible animation
• Parallel dispatch shows all reviewer chutes activating simultaneously
• Review-fix shuttle cycle: orchestrator walks back and forth between coder and review stations, carrying artifacts
• Round counter displays current review iteration (e.g., "Round 1/3")
• Selective re-review: only affected reviewers reactivate; others remain "resting"
• Station records persist at stations after phase completes, with stacking for superseded versions (e.g., code v1 under code v2)
• Artifacts rendered as labeled, colored blocks (placeholder for future item sprites)
• Skipped phases appear as dark/inactive stations
• Station count is dynamic (driven by run's phase data, not hardcoded)
• Existing tests pass with updated SceneConfig shape
• Demo mode can step through all state transitions

[williamthorsen]

Implementation plan

Factory visualization redesign: two-level catwalk factory

Context

The Factory visualization renders orchestrated development runs as a 2D Excalibur game scene. The current implementation shows agents at stations with basic animations and colored squares for artifacts, but lacks visual representation of:

1. Code being fabricated — the core product of the factory isn't visible as something being made
2. The orchestrator's hub role — it currently walks linearly, but in reality it dispatches work, collects results, and shuttles between agents
3. The review-fix cycle — the iterative loop where the coder receives consolidated review findings, fixes code, and re-delivers is invisible
4. Artifact lifecycle — who produced each artifact, how it was consumed, and its relationship to other artifacts
5. Parallel work — reviewers working simultaneously isn't visually distinct from sequential work

The redesign introduces a two-level factory layout with a catwalk orchestrator, vertical artifact chutes, a shuttle pattern for the review-fix cycle, and a paper-trail system for post-run inspection.

Design

Spatial layout: two-level factory

Catwalk (upper level): Continuous walkway spanning the full width. The orchestrator walks here exclusively — it never descends to the ground floor. This reinforces its role as dispatcher/supervisor.

Ground floor (lower level): Workstations arranged left-to-right in phase order. Each station has one or more subagent slots. Station count is dynamic — driven by the run's phases, not hardcoded.

Vertical chutes: Connect catwalk to each ground station. Artifacts visibly descend (orchestrator → agent) and ascend (agent → orchestrator) through these chutes. During parallel dispatch (review phase), all chutes at a station activate simultaneously.

Skipped phases: Appear as dark/inactive stations. Present but dim, so users see the full possible pipeline.

  CATWALK ═══════╤═══════════╤═══════════╤═══════════════╤═══════
                 │chute      │chute      │chute          │chute
  ───────────────┼───────────┼───────────┼───────────────┼───────
  GROUND:    [Station 1] [Station 2] [Station 3]    [Station N]
              Architect    Planner     Coder        Reviewer(s)

Artifact model: station records + conveyor + paper trail

Three layers of artifact information, progressively disclosed:

Layer 1 — Station records (always visible): Every artifact a subagent produces leaves a copy at its station. These are the subagent's work products. Superseded versions stack (code v1 under code v2 under code v3).

Layer 2 — Conveyor artifacts (visible during movement): Artifacts the orchestrator carries between stations. These are the items flowing through the process. Opacity reflects lifecycle state:

• Active/in-transit: full opacity
• Consumed by next phase: faded
• Superseded: stacked under latest version

Layer 3 — Paper trail (on click, post-run): Click any persistent artifact to see its input chain. Thin glowing lines trace back to source artifacts at their producing stations. Shows how A led to B led to C.

Artifact types (labeled blocks for now, item sprites later):

Artifact	Label	Color	Producer	Consumer
Architecture doc	arch	blue	Architect	Planner, Coder
Orchestration plan	plan	green	Planner	Coder
Code / change summary	code	yellow	Coder	Reviewers
Review findings	review	red	Each reviewer	Orchestrator
Consolidated review	fixes	orange	Orchestrator	Coder
Simplified code review	clean	magenta	Simplifier	Coder
Holistic review	holi	cyan	Holistic reviewer	Coder
Run summary	summary	white	Orchestrator	(persisted)

Movement pattern: three-beat cycle

Every phase follows the same pattern:

1. Dispatch: Orchestrator stops above station on catwalk. Artifact descends through chute to agent(s). For parallel dispatch (review), one copy descends per reviewer simultaneously.

2. Work: Agent(s) animate "working". A new artifact materializes at the station.

3. Collect: Finished artifact ascends through chute to orchestrator. Orchestrator walks along catwalk to next station.

Review-fix shuttle cycle

The review phase extends the three-beat cycle with iteration:

Initial dispatch: Orchestrator drops [code] + [instructions] to all reviewers simultaneously. All begin working in parallel.

Collection: Reviews rise asynchronously as each reviewer finishes. Orchestrator waits until all are collected. A progress indicator shows "3/4 collected".

Consolidation: Orchestrator produces [fixes] artifact on the catwalk (brief "working" animation — the one time it fabricates something).

Fix dispatch: Orchestrator walks back to coder station, drops [fixes]. Coder works, produces [code v2] (stacks on v1).

Re-review (selective): Orchestrator carries [code v2] back to review station. Only reviewers whose findings were addressed reactivate. Inactive reviewers stay "resting".

Convergence: When criticality drops below threshold, orchestrator proceeds forward. Gate opens.

Visual cues for iteration:

• Round counter near review station: "Round 1/3", "Round 2/3"
• Shuttle trips visually show the back-and-forth
• Convergence triggers brief celebration before moving forward

State machine

State	Visual characteristics
Initialization	Stations appear sequentially. Skipped phases dim. Orchestrator appears on catwalk at leftmost active station. All gates closed (red).
Phase execution	Three-beat cycle (dispatch → work → collect). Gate opens between current and next station. Orchestrator walks to next station. Previous agents transition to "resting".
Review-fix loop	Shuttle cycle between impl and review stations. Round counter visible. Selective re-review shows which reviewers re-engage.
Run completed	All gates open. All agents celebrate. Final product at summary station highlighted/glowing. Station records become clickable (paper trail).
Run failed	All agents show "concerned". Failing station highlighted. Gate stays closed/red.
"What happened" mode	Post-run inspection. Camera shows full factory. Click any artifact for paper trail with glowing connection lines to source artifacts.

Flexibility

The design handles arbitrary orchestrated workflows:

• Dynamic station count from phaseDecisions + phases
• Iteration loops at any station (shuttle pattern is generic, not hardcoded to review)
• Variable agents per station (layout fans out chute to N agents)
• Phase ordering from data (left-to-right order matches run's phase sequence)

Core assumption: one orchestrator dispatches to one or more agents per phase, sequentially across phases, with possible iteration within a phase. This matches any orchestrated run.

Critical files

Must modify

• packages/factory/src/client/game/scenes/FactoryScene.ts — Scene orchestration (add catwalk level, chute animations, shuttle logic)
• packages/factory/src/client/game/layout/platform-layout.ts — Layout system (two-level geometry, chute positions)
• packages/factory/src/client/game/mappers/run-to-scene.ts — Scene config mapper (add conveyor artifact state, shuttle metadata)
• packages/factory/src/client/game/actors/ArtifactActor.ts — Artifact rendering (labeled blocks, opacity states, stacking)
• packages/factory/src/client/game/actors/AgentActor.ts — Agent positioning on two levels
• packages/factory/src/client/game/state/agent-state-resolver.ts — Animation states for shuttle cycle

Must add

• packages/factory/src/client/game/actors/ChuteActor.ts — Vertical chute between catwalk and ground station
• packages/factory/src/client/game/actors/CatwalkActor.ts — Catwalk platform geometry
• packages/factory/src/client/game/actors/ConveyorArtifactActor.ts — In-transit artifact (distinct from station record)
• packages/factory/src/client/game/actors/RoundCounterActor.ts — Review iteration counter display

Reference (read-only)

• packages/factory/src/shared/types/canonical.ts — CanonicalRunStatus data model
• packages/factory/src/shared/phase-inference.ts — Phase state inference
• packages/factory/src/client/game/actors/GateActor.ts — Existing gate animation pattern (reuse for chutes)
• packages/factory/src/client/game/actors/PlatformActor.ts — Existing platform geometry (extend for catwalk)
• packages/factory/src/client/game/actors/LadderActor.ts — Existing multi-level support

Existing utilities to reuse

• GateActor animation pattern (promise-based open/close with interpolation) → reuse for chute open/close
• AgentActor.walkPath() with cancel-and-restart → reuse for orchestrator catwalk movement
• agent-differ.ts diffing logic → extend for conveyor artifact lifecycle
• platform-layout.ts geometry computation → extend with catwalk level coordinates
• SVG sprite generation per role type → extend with orchestrator catwalk sprites

Verification

1. Visual smoke test: Run the factory with a demo orchestrated run. Verify:

   • Two-level layout renders (catwalk above, stations below)
   • Orchestrator walks on catwalk, not ground level
   • Artifacts descend/ascend through chutes
   • Review-fix shuttle cycle shows back-and-forth movement
   • Parallel reviewers activate simultaneously
   • Selective re-review shows subset of reviewers
   • Station records persist at stations after phase completes
   • Completed run shows all artifacts clickable

2. Existing tests: Run pnpm test in packages/factory — ensure run-to-scene.test.ts (1806 lines, 100+ cases) passes with updated SceneConfig shape

3. Layout verification: Check that station spacing, chute positions, and catwalk height work with varying reviewer counts (1, 2, 3, 4 reviewers)

4. Demo mode: Use DemoControlPanel to step through run states and verify each state transition animates correctly