Factory visualization engineering workstreams

[williamthorsen]

Context

This ticket captures parallel engineering workstreams for the tilemap-based factory visualization (#293). Design decisions are documented in packages/factory/docs/visions/facility-architecture.md (the authoritative architecture document) and control-panel-research.md.

Prerequisites: Read facility-architecture.md first — it contains the three-zone layout, agent behavior state machines, artifact lifecycle, governor's office concept, and interaction model.

Layout (settled): Three zones — prep area (architect + planner), workshop (coder + reviewers + findings whiteboard), governor's office (orchestrator + delivery table + control console + action buttons). The orchestrator is the user's agent; they share the governor's office.

Artifact lifecycle (settled): created → in_transit → delivered

Workstream 1: Technical architecture plan — DONE

Completed across branches 293 and 295:

• facility-architecture.md captures the full spatial, behavioral, and compositional architecture
• Branch 295 implements layers 1-4 as pure TypeScript: room definitions, facility layout, agent assignments, state mapper, thought bubble mapper, position resolver, differ, transition planner, and TilemapScene

Remaining alignment work (tracked in facility-architecture.md § "Branch 295: implementation status"):

• Room renames: 5 rooms → 3 zones (prep, workshop, governor)
• Corridor path recalculation for new layout + doorway waypoint
• Artifact state rename: on_desk → created, add in_transit
• Add whiteboard entity to workshop zone

Workstream 2: Artifact content API

Goal: Design and implement GET /runs/:runId/artifacts/:filename — the Express endpoint that serves actual artifact file content (diffs, findings, plans, summaries).

Why: Every vision identified this as a prerequisite. It's settled, unambiguous work.

Details:

• The server already reads run-index.json files and knows artifact filenames from CanonicalRunStatus
• The endpoint needs to resolve the artifact's file path on disk from the run directory + filename
• Return raw content with appropriate content-type (text/markdown for .md files, application/json for .json)
• Optional: a ?format=html query param that renders markdown to HTML server-side
• Add to the existing routes in packages/factory/src/server/routes/runs.ts
• Add tests

Key files:

• packages/factory/src/server/routes/runs.ts (add endpoint here)
• packages/factory/src/server/services/project-scanner.ts (understands run directory layout)
• packages/factory/src/server/adapters/status-adapter.ts (parses run-index.json)
• packages/factory/src/shared/types/canonical.ts (artifact types)

Output: Working endpoint with tests.

Workstream 3: Governor interaction design

Goal: Design the interaction model for the governor's office — how the developer watches, inspects, and commands the orchestration.

Settled context: The orchestrator is the user's agent. They share the governor's office. The user observes at a glance, hovers to inspect, clicks to investigate, and clicks the orchestrator to chat. See facility-architecture.md § "Interaction model" and control-panel-research.md for patterns from Dagster, Temporal, Buildkite, Gastown, and industrial HMI.

Commands to explore:

• Cancel run — halt the orchestration. What does this mean at the MCP/orchestration level?
• Schedule additional review — request another review round. How does this feed back into the pipeline?
• Add comment / course-correct — send a message to an active agent. How would this work with the Task tool / subagent model?
• Retry failed phase — re-run a phase that failed. What state changes are needed?

For each command, answer:

1. What does the user see in the governor's office? (button on control console, context menu, keyboard shortcut)
2. What API call does the frontend make?
3. What happens on the server/orchestration side?
4. What are the constraints? (Can you cancel mid-phase? Can you inject a comment into a running subagent?)
5. What changes to run-index.json / the event log are needed?

Context: The orchestration system is built on Claude Code's Task tool — subagents are dispatched and run autonomously. Injecting commands into running subagents may not be possible without architectural changes. Be honest about what's feasible vs. aspirational.

Key files:

• packages/agents/content/skills/orchestrate/SKILL.md (the orchestration pipeline engine)
• packages/agents/content/skills/orchestrate/modules/review-cycle.md
• packages/factory/src/shared/types/canonical.ts
• packages/factory/docs/visions/control-panel-research.md (industry patterns)

Output: packages/factory/docs/governor-interaction.md

Workstream 4: Thought bubble data model and mapper — PARTIALLY DONE

Branch 295 implements mapRunToThoughtBubbles with severity-aware formatting. The office prototype demonstrates the visual design (bubble placement, fatal/warning styling, content examples).

Remaining:

• Cycle content (multiple texts rotating every 4-6 seconds, staggered across agents) — not yet implemented
• Freeze-on-hover interaction
• Integration with the updated 3-zone layout positions

Key files:

• packages/factory/src/shared/types/canonical.ts (source data)
• Branch 295's thought bubble mapper (existing implementation)
• packages/factory/docs/visions/facility-architecture.md § "Agent behaviors"

How to run these

Workstreams 2 and 3 are independent and can run in parallel. Workstream 1's alignment work and workstream 4's remaining items depend on branch 295 and should be done there.

For workstreams producing design documents, output goes to packages/factory/docs/ (not docs/visions/, which holds only the office prototype and its design docs).

[williamthorsen]

Replaced by focused tickets: #297 (artifact content API), #298 (governor interaction design), #299 (branch 295 alignment with three-zone layout).