Build orchestration visualizer with retro game aesthetic

[williamthorsen]

Overview

Build Artifactory - a web-based visualizer that displays orchestration workflow progress as a retro pixel-art game with Donkey Kong aesthetics. This serves as a developer tool to understand orchestration status during active runs while being engaging enough to create buzz.

Problem

Orchestration currently produces timestamped markdown artifacts and a status.json file, but there's no visual way to understand what's happening during a run. Developers have to read files directly or mentally map the workflow.

Solution

A locally-running web application that displays orchestration progress as an animated factory/construction site with worker characters representing different agents (architect, planner, coder, reviewers). The spatial layout encodes the dependency graph, making the workflow structure immediately clear.

Key Features

Visual Design

• Platform view (side-scrolling like Donkey Kong)
• Pixel art workers with hard hats representing different agent roles
• Color-coded artifacts as crates (blue=architecture, green=plan, yellow=code, red=findings)
• Industrial aesthetic: girders, platforms, work lights, factory wall with iteration counter
• Retro palette: CGA/EGA inspired colors, pixel fonts

Game Board Layout

• Horizontal flow (left → right): Architecture → Planning → Implementation → Review → Simplifier → Holistic Review → Summary
• Parallel review area: 4 reviewers stacked vertically at same horizontal position
• Visual dependencies: Gates between stations open when dependencies complete
• Fix cycle visualization: Coder walks backward when findings exist, returns after fixes

Interactivity

• Click agents to see status details and current work
• Click artifacts to read markdown content with syntax highlighting
• Run selector to switch between orchestration runs
• Real-time updates via polling (2-second interval for in-progress runs)
• Static view for completed runs (no polling, just final state)

Architecture

Backend (Node.js/TypeScript)

• Express server with REST API
• GET /api/status - Returns current status.json
• GET /api/artifact/:runId/:filename - Returns artifact markdown
• Reads from ~/.ai/projects/{project-slug}/tickets/{ticket-id}/{run-id}/
• Stateless file reading (no database)

Frontend (React + Excalibur.js)

• React for UI shell (sidebar, modals, controls)
• Excalibur.js game engine for sprite rendering and animations
• Vite build tooling
• TypeScript throughout

Data Flow

• Frontend polls /api/status every 2 seconds
• Detects state changes (phase transitions, new artifacts, criticality)
• Triggers Excalibur animations via custom event system
• status.json is source of truth - frontend only visualizes, never invents state

Implementation Phases

1. Backend Setup - Express server, artifact path resolution, API endpoints
2. Frontend Shell - React app, polling hook, UI components (sidebar, modal, top bar)
3. Excalibur Game Board - Scene setup, station positioning, camera controls
4. Character Sprites & Animation - Agent actors with animation states (idle, working, walking, carrying)
5. Artifacts & Fix Cycles - Artifact crates, fix cycle loops, iteration counter
6. Interactivity - Click handlers, run selector, pause/resume controls
7. Visual Polish - Proper pixel art, particle effects, lighting, CRT scanline effects

Tech Stack

• Frontend: React 18+, TypeScript, Excalibur.js, Vite
• Backend: Node.js 18+, TypeScript, Express
• Dev Tools: pnpm, Prettier, ESLint, strict TypeScript

Success Criteria

Functional:

• ✅ Visualizes all orchestration phases accurately
• ✅ Updates in real-time during active runs
• ✅ Shows final state for completed runs
• ✅ All agents and artifacts are clickable
• ✅ Markdown rendering works correctly

Aesthetic:

• ✅ Retro pixel art style with engaging animations
• ✅ Clear spatial encoding of workflow dependencies
• ✅ Smooth 60 FPS rendering

UX:

• ✅ Camera follows active phase automatically
• ✅ Intuitive click interactions
• ✅ Responsive controls (pause, refresh, run selector)

Next Steps

See detailed implementation plan in comment below.

[williamthorsen]

Orchestration Visualizer Implementation Plan

Context

Build a web-based visualizer for the orchestrate skill that displays orchestration workflow progress as a retro pixel-art "game" with Donkey Kong aesthetics. The visualizer serves as a developer tool to understand orchestration status during active runs, while also being engaging enough to create buzz.

Problem addressed: Orchestration currently produces timestamped markdown artifacts and a status.json file, but there's no visual way to understand what's happening during a run. Developers have to read files directly or mentally map the workflow.

Intended outcome: A locally-running web application that displays orchestration progress as an animated factory/construction site with worker characters representing different agents (architect, planner, coder, reviewers). The spatial layout encodes the dependency graph, making the workflow structure immediately clear.

Architecture

System Components

Backend (Node.js/TypeScript):

• Express server serving static frontend assets
• REST API endpoints:
  • GET /api/status - Returns current status.json content
  • GET /api/artifact/:runId/:filename - Returns artifact markdown content
• Reads from ~/.ai/projects/{project-slug}/tickets/{ticket-id}/{run-id}/ (artifact directory structure from artifact-conventions.md)
• Stateless - just file reads on demand
• CORS enabled for local development

Frontend (React + Excalibur):

• React app shell with:
  • Excalibur game canvas for main visualization
  • Sidebar panel for agent/artifact details (shown on click)
  • Top bar with run selector and controls
• Excalibur Engine manages game board, sprites, animations
• Polling loop: fetch /api/status every 2 seconds, update game state
• Custom event system bridges React state to Excalibur scene updates

File System Contract:

• Backend expects standard artifact structure from orchestrate skill (see agents/common/skills/_data/artifact-conventions.md)
• Frontend parses status.json schema (phases, criticality, timestamps)
• Artifacts are markdown files read on-demand when clicked

Game Board Layout (Platform View)

Horizontal flow (left to right):

1. Architecture Station
2. Planning Station
3. Implementation Station
4. Review Area (4 parallel reviewers stacked vertically at same horizontal position)
   • Core Reviewer (top platform)
   • Silent-Failure Hunter
   • Test Analyzer
   • Code Reviewer (bottom platform)
5. Code Simplifier Station
6. Holistic Review Station
7. Summary Station

Visual dependency encoding:

• Gates between stations (red barrier = closed, no barrier = open)
• Station lighting (lit = active, dimmed = waiting, green flag = completed)
• Fix cycle loop: Coder walks backward to Implementation when findings exist, then forward again after fixes
• Iteration counter on factory wall: "Review Cycle: 2/3"

Implementation Approach

Technology Stack

Frontend:

• React 18+ with TypeScript
• Excalibur.js game engine (TypeScript-first 2D engine)
• Vite for build tooling
• React Router (if multiple views needed)

Backend:

• Node.js 18+ with TypeScript
• Express.js for API server
• No database - reads directly from file system

Development:

• pnpm for package management (matches repo convention)
• Prettier + ESLint (matches repo standards)
• TSConfig with strict mode

Project Structure

orchestration-visualizer/
├── backend/
│   ├── src/
│   │   ├── server.ts          # Express server setup
│   │   ├── routes/
│   │   │   ├── status.ts      # GET /api/status endpoint
│   │   │   └── artifacts.ts   # GET /api/artifact/:runId/:filename
│   │   └── utils/
│   │       └── artifactReader.ts  # File system reading logic
│   ├── package.json
│   └── tsconfig.json
├── frontend/
│   ├── src/
│   │   ├── main.tsx           # React entry point
│   │   ├── App.tsx            # Root component
│   │   ├── components/
│   │   │   ├── GameCanvas.tsx      # Excalibur canvas wrapper
│   │   │   ├── Sidebar.tsx         # Agent/artifact detail panel
│   │   │   ├── TopBar.tsx          # Run selector and controls
│   │   │   └── ArtifactModal.tsx   # Markdown artifact viewer
│   │   ├── game/
│   │   │   ├── GameScene.ts        # Main Excalibur scene
│   │   │   ├── actors/
│   │   │   │   ├── Agent.ts        # Base agent character class
│   │   │   │   ├── Artifact.ts     # Artifact crate sprite
│   │   │   │   ├── Station.ts      # Work station sprite
│   │   │   │   └── Gate.ts         # Dependency gate sprite
│   │   │   └── animations/
│   │   │       └── spriteSheets.ts # Sprite sheet definitions
│   │   ├── types/
│   │   │   └── orchestration.ts    # TypeScript types for status.json
│   │   └── hooks/
│   │       └── useOrchestrationStatus.ts  # Polling hook
│   ├── public/
│   │   └── assets/
│   │       ├── sprites/        # Pixel art sprite sheets (PNG)
│   │       └── fonts/          # Pixel fonts
│   ├── package.json
│   ├── tsconfig.json
│   └── vite.config.ts
└── README.md

Key Components

Backend Components

1. Status Endpoint (backend/src/routes/status.ts):

• Reads status.json from artifact directory
• Resolves artifact directory using logic from agents/common/skills/_data/artifact-conventions.md:
  • Read artifacts.base_dir from .agents/preferences.yaml or ~/.agents/preferences.yaml
  • Default to ~/.ai
  • Path: {base_dir}/projects/{project-slug}/tickets/{ticket-id}/{run-id}/status.json
• Returns JSON response or 404 if not found

2. Artifact Endpoint (backend/src/routes/artifacts.ts):

• Reads specific artifact markdown file by filename
• Returns markdown content as text
• Validates filename to prevent directory traversal attacks

3. Artifact Reader Utility (backend/src/utils/artifactReader.ts):

• Reusable logic for resolving artifact paths
• Uses get-project-slug and get-ticket-id conventions from repo

Frontend Components

1. Polling Hook (frontend/src/hooks/useOrchestrationStatus.ts):

• Custom React hook that polls /api/status every 2 seconds
• Compares previous vs current status to detect changes
• Returns: { status, isLoading, error, changes }

2. Game Scene (frontend/src/game/GameScene.ts):

• Main Excalibur Scene managing the game board
• Creates Station, Agent, Artifact, Gate actors
• Subscribes to custom events from React: phaseChange, newArtifact, agentStateChange
• Camera follows active station (auto-pan)
• Handles click events on agents/artifacts, emits to React layer

3. Agent Actor (frontend/src/game/actors/Agent.ts):

• Excalibur Actor subclass representing worker characters
• Animation states: idle, working, walking, carrying, celebrating, concerned
• Properties: role (architect, coder, reviewer), currentStation, status
• Sprite sheets with 16x16 or 32x32 pixel art (upscaled 2x-4x)

4. Station Actor (frontend/src/game/actors/Station.ts):

• Represents work stations (platforms)
• States: waiting (dimmed), active (lit), completed (green flag)
• Positions calculated from dependency graph

5. Sidebar Component (frontend/src/components/Sidebar.tsx):

• Slides in from right when agent/artifact clicked
• Shows agent status and current work
• Link to view latest artifact
• Close button

6. Artifact Modal (frontend/src/components/ArtifactModal.tsx):

• Overlay modal displaying markdown content
• Syntax highlighting for code blocks
• Renders findings (F/W/T/R/S) with color coding
• Scrollable content

Visual Design Details

Pixel Art Assets:

• Character sprites: 32x32 pixels, upscaled 4x for display
• Color-coded hard hats by role (blue=architect, yellow=coder, red=reviewer)
• 3-4 frame animations per state
• Artifact crates: 16x16 pixels, color-coded by type
• Industrial background: girders, brick walls, work lights

Color Palette:

• Limited retro palette (CGA/EGA inspired)
• Agents: distinct hard hat colors
• Artifacts: blue (architecture), green (plan), yellow (code), red (findings)
• UI: dark background with scanline CRT effect

Typography:

• Pixel font for all text (Press Start 2P or similar)
• Big chunky buttons

Data Flow

1. Initial Load:

User opens browser → React app loads
→ Fetches /api/status
→ Parses status.json
→ Initializes Excalibur scene with current state
→ Positions agents at appropriate stations
→ Shows artifacts as crates

2. Polling Loop (in-progress runs):

Every 2 seconds:
  Fetch /api/status
  → Compare with previous
  → Detect changes (phase transitions, new artifacts, criticality)
  → Emit events to Excalibur: gameScene.events.emit('phaseChange', data)
  → Excalibur updates animations/positions

3. User Interactions:

Click agent → React state updates → Sidebar slides in
Click artifact → Fetch /api/artifact/:runId/:filename → Show in modal
Select different run → Update run ID → Fetch new status.json

4. Completed Runs:

• Show final static state (all phases complete)
• No polling (just fetch once)
• Idle animations only
• Click around to read artifacts

Interactivity

Clickable Elements:

• Agent characters: Shows sidebar with status/artifact details, highlights sprite
• Artifact crates: Opens modal with markdown content
• Stations: Tooltip on hover with phase name and status

Controls (Top Bar):

• Run selector dropdown: Recent runs from ~/.ai/projects/{project-slug}/tickets/
• Pause/resume polling button (in-progress runs only)
• Manual refresh button
• Jump to current phase button (camera pan)

Camera:

• Auto-pan: follows active station/agent
• Manual pan: click and drag or arrow keys
• Horizontal scrolling (game board wider than viewport)

Critical Files and Existing Patterns

Files to Reference

Orchestration conventions:

• agents/common/skills/orchestrate/SKILL.md - Full orchestration workflow spec
• agents/common/skills/_data/artifact-conventions.md - Artifact structure, naming, paths
• Example status.json: ~/.ai/projects/configs-macos/tickets/MAC-122/20260225-0923Z-orchestrated/status.json

Project structure conventions:

• .agents/PROJECT.md - Project conventions for this repo
• Uses pnpm, TypeScript, ES modules
• Prettier for formatting

Existing Utilities to Reuse

For artifact path resolution:

• agents/common/skills/get-project-slug/SKILL.md - Logic for deriving project slug
• agents/common/skills/get-ticket-id/SKILL.md - Logic for extracting ticket ID
• These skills show the path resolution algorithm to implement in backend

No existing code to reuse - this is a new standalone application. However, the backend should implement the same path resolution logic documented in those skills.

Implementation Steps

Phase 1: Backend Setup

1. Initialize Node.js/TypeScript project in orchestration-visualizer/backend/
2. Set up Express server with CORS
3. Implement artifact path resolution (based on artifact-conventions.md)
4. Create /api/status endpoint
5. Create /api/artifact/:runId/:filename endpoint
6. Test with curl/Postman against real orchestration artifacts

Phase 2: Frontend Shell

1. Initialize React + Vite project in orchestration-visualizer/frontend/
2. Set up TypeScript types for status.json schema
3. Create polling hook (useOrchestrationStatus)
4. Build TopBar component (run selector, controls)
5. Build Sidebar component (empty for now)
6. Build ArtifactModal component with markdown rendering
7. Test data fetching and state management

Phase 3: Excalibur Game Board

1. Install Excalibur.js
2. Create GameCanvas React wrapper component
3. Implement GameScene with basic layout (platforms, background)
4. Create Station actors and position them based on workflow
5. Create Gate actors (dependency barriers)
6. Test scene rendering and camera controls

Phase 4: Character Sprites and Animation

1. Create pixel art sprite sheets for each agent role (or use placeholder colored squares initially)
2. Implement Agent actor class with animation states
3. Position agents at stations based on status.json
4. Implement walking animations (coder moving between stations)
5. Implement working animations (hammer, inspect, etc.)
6. Test state transitions as status.json changes

Phase 5: Artifacts and Fix Cycles

1. Create Artifact actor (crate sprites)
2. Spawn artifacts when status.json shows new artifacts
3. Implement fix cycle: coder walks back when findings exist
4. Show iteration counter on wall
5. Test parallel review visualization (4 reviewers at once)

Phase 6: Interactivity

1. Implement click handling on agents (show sidebar)
2. Implement click handling on artifacts (fetch markdown, show modal)
3. Connect run selector to backend (list available runs)
4. Implement pause/resume polling
5. Test all interactive features

Phase 7: Visual Polish

1. Add proper pixel art sprites (replace placeholders)
2. Implement factory/construction site background
3. Add particle effects (sparkles, dust)
4. Add gate opening/closing animations
5. Add completion flags and lighting effects
6. Apply CRT scanline effect to UI panels
7. Test overall aesthetic

Verification

End-to-End Testing

1. Start backend:

cd orchestration-visualizer/backend
pnpm install
pnpm dev  # Runs on localhost:3000

2. Start frontend:

cd orchestration-visualizer/frontend
pnpm install
pnpm dev  # Runs on localhost:5173

3. Test with real orchestration run:

• Run an orchestration in this repo: /orchestrate "some task"
• Open browser to localhost:5173
• Verify visualizer shows current orchestration state
• Watch agents animate as phases progress
• Click agents to see details
• Click artifacts to read markdown

4. Test with completed run:

• Select a completed run from dropdown
• Verify shows final static state
• Verify all artifacts are clickable
• Verify no polling (completed runs don't update)

5. Manual test cases:

• Architecture phase visualizes correctly
• Planning phase visualizes correctly
• Implementation phase shows coder working
• Parallel review shows 4 reviewers at once
• Fix cycle: coder walks back when findings exist
• Iteration counter increments
• Code simplifier appears after convergence
• Holistic review shows at end
• Clicking agent shows sidebar with details
• Clicking artifact opens modal with markdown
• Run selector switches between runs
• Pause button stops polling
• Camera follows active phase
• Pixel art aesthetic looks retro/engaging

Success Criteria

Functional:

• ✅ Visualizes all orchestration phases accurately
• ✅ Updates in real-time during active runs
• ✅ Shows final state for completed runs
• ✅ All agents and artifacts are clickable
• ✅ Markdown rendering works correctly

Aesthetic:

• ✅ Retro pixel art style with Donkey Kong feel
• ✅ Smooth animations for state transitions
• ✅ Engaging to watch (not just functional)
• ✅ Clear spatial encoding of workflow dependencies

Performance:

• ✅ Renders smoothly (60 FPS)
• ✅ Polling doesn't cause lag
• ✅ Handles long orchestration runs (many artifacts)

Notes

• MVP scope: Focus on visualizing the core workflow first. Sound effects, advanced animations, and replay features can be added later.
• Pixel art: Initial implementation can use colored rectangles as placeholders. Proper sprites can be created iteratively.
• Run selector: Initially hardcode a test run path. Full run discovery (scanning ~/.ai) can be added after basic visualization works.
• Error handling: Backend should handle missing files gracefully (return 404). Frontend should show friendly error messages.
• Deployment: This runs locally only for now. No need for production deployment setup.

[williamthorsen]

Plan: Artifactory — Project setup through static scene

Issue: #1 — Build orchestration visualizer with retro game aesthetic
Scope: Phases 0–3 (of 7 total). Establishes the full-stack foundation: package scaffolding, Express backend with filesystem discovery, React shell with polling, and static Excalibur.js scene rendering real orchestration data. Animation and interactivity deferred to a follow-up plan.

Context

Orchestration runs produce timestamped markdown artifacts and a status.json file under ~/.ai/projects/{slug}/tickets/{ticket-id}/{run-id}/, but there's no visual way to understand workflow progress. Artifactory will render this data as a retro pixel-art factory scene. This plan covers the foundation: getting real data flowing from filesystem → Express API → React → Excalibur canvas.

The repo is a PNPM monorepo cloned from a template. Template packages (react, api, nextjs, svelte, astro, chrome, cdk, _workspace) will be deleted. A single new packages/artifactory package will be created. Development proceeds from the next branch.

Authoritative data model

The orchestrate skill definition (~/.claude/skills/orchestrate/SKILL.md) is the authoritative source for the status.json schema and orchestration flow. Most existing runs in ~/.ai/projects/ were created by older versions of the skill — only the most recent 1–2 runs (e.g., MAC-122) reflect the current schema.

Current Orchestration Phases (from SKILL.md)

#	Phase	Skill phase	Required	Agents
1	Architecture	Phase 1	Optional	orchestrated-architect
2	Planning	Phase 2	Optional	orchestrated-planner
3	Implementation	Phase 3	Required	orchestrated-coder
4	Parallel Review	Phase 4	Required	orchestrated-reviewer + aspect reviewers (code, silent-failure, test)
5	Code Simplifier	Phase 4a	After reviews converge	pr-review-toolkit:code-simplifier
6	Holistic Review	Phase 4b	After simplifier	orchestrated-reviewer (holistic)
7	Summary	Phase 5	Always	Orchestrator writes directly

Current status.json Schema (from SKILL.md)

Initial structure (written at run start):

{
  "runId": "{run-id}",
  "projectSlug": "{slug}",
  "ticketId": "{ticket-id}",
  "projectRoot": "{cwd}",
  "branch": "{branch}",
  "task": "{task description}",
  "startedAt": "{ISO timestamp}",
  "status": "in_progress",
  "phases": {},
  "phaseDecision": {},
  "externalPlan": false
}

Fields added during execution: mergeBaseSha, diffBase, maxReviewRounds, fixLowFindings, completedAt.

Phase structures populated during run:

Architecture: { status, impactLevel, artifact }

Planning: { status, stepCount, artifacts[] }

Implementation: { status, artifact, qualityGates: { typecheck, lint, tests } }

Parallel review (SKILL.md canonical form):

"parallelReview": {
  "aggregatedCriticality": "medium",
  "reviewers": {
    "core": { "status": "completed", "criticality": "medium" },
    "aspect-silent-failure": { "status": "completed|skipped|failed", "criticality": "low" },
    "aspect-test": { "status": "skipped", "reason": "no source or test files changed" },
    "aspect-code": { "status": "completed", "criticality": "medium" }
  },
  "coderFixCycleRan": true,
  "selectiveReReview": {
    "ran": true,
    "reviewersDispatched": ["core", "aspect-code"],
    "additionalFixCycleRan": false
  }
}

Code Simplifier: { ran, actionableFindings, coderFixCycleRan }

Holistic Review: { status, criticality, coderFixCycleRan, reviewRoundsUsed, artifact }

Artifact Naming Convention (from SKILL.md)

Pattern: {YYYYMMDD-HHMMZ}_{role}_{artifact-type}.{ext}

Roles: orchestrator, architect, planner, coder, reviewer, aspect

Example artifact trail (from a full run):

20260225-0923Z_orchestrator_run-manifest.md
20260225-0924Z_architect_architecture.md
20260225-0930Z_planner_orchestration-plan.md
20260225-0930Z_planner_orchestration-plan.json
20260225-0940Z_coder_change-summary.md
20260225-0950Z_reviewer_review.md            ← parallel dispatch
20260225-0950Z_aspect_silent-failure-review.md
20260225-0950Z_aspect_test-review.md
20260225-0950Z_aspect_code-review.md
20260225-0955Z_coder_change-summary.md       ← fix cycle
20260225-1000Z_reviewer_review.md            ← selective re-review
20260225-1005Z_aspect_code-simplifier-review.md
20260225-1010Z_coder_change-summary.md       ← simplifier fixes
20260225-1015Z_reviewer_holistic-review.md
20260225-1020Z_coder_change-summary.md       ← holistic fixes
20260225-1025Z_reviewer_holistic-review.md   ← holistic re-review
20260225-1042Z_orchestrator_run-summary.md

Schema Discrepancy: SKILL.md vs Actual Data

The SKILL.md documents the intended schema, but the actual MAC-122 status.json differs in reviewer structure:

Field	SKILL.md says	MAC-122 actual
Reviewer ran?	"status": "completed"	"ran": true
Reviewer keys	core, aspect-silent-failure, aspect-test, aspect-code	core, silent-failure-hunter, pr-test-analyzer, code-reviewer
Extra fields	—	reReviewCriticality, reReviewError

The types should handle what the orchestrator actually writes (the MAC-122 pattern), not just the SKILL.md example. During implementation, parse both status and ran fields defensively.

Legacy Schema (V1)

Older runs (pre-Feb 25) use a different review structure: phases.review with { status, rounds, finalCriticality, findings } instead of parallelReview. No codeSimplifier or holisticReview. Detection: absence of parallelReview key. Support via adapter as best-effort, not primary target.

Phase 0: Monorepo Cleanup + Package Scaffolding

0a. Delete template packages

Remove all template workspaces:

packages/api/
packages/react/
packages/nextjs/
packages/svelte/
packages/astro/
packages/chrome/
packages/cdk/
packages/_workspace/

Keep monorepo root infrastructure (config/, scripts/, root configs).

0b. Create packages/artifactory

packages/artifactory/package.json — Follow _workspace template pattern:

{
  "name": "artifactory",
  "version": "0.1.0",
  "private": true,
  "type": "module",
  "scripts": {
    "build": "pnpm vite build",          // Override: Vite build instead of esbuild
    "dev": "tsx src/server/index.ts & pnpm vite --host",  // Override: start both servers
    "dev:server": "tsx --watch src/server/index.ts",
    "dev:client": "pnpm vite --host",
    "ws": "node --import tsx ../../scripts/run-workspace-script.ts"
  },
  "dependencies": {
    "excalibur": "^0.30.x",          // Game engine (verify latest stable)
    "express": "^5.x",               // HTTP server
    "react": "^19.2.0",
    "react-dom": "^19.2.0"
  },
  "devDependencies": {
    "@testing-library/dom": "10.4.1",
    "@testing-library/jest-dom": "6.9.1",
    "@testing-library/react": "16.3.0",
    "@types/express": "^5.x",
    "@types/react": "19.2.2",
    "@types/react-dom": "19.2.2",
    "eslint-plugin-react": "7.37.5",
    "jsdom": "26.1.0"
  }
}

Note: Exact versions will be resolved at install time. The dev script runs server and client concurrently.

packages/artifactory/tsconfig.json — Extend root, add DOM libs for client:

{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "jsx": "react-jsx",
    "lib": ["DOM", "DOM.Iterable", "ESNext"],
    "strict": true
  },
  "include": ["src/", "*.ts"]
}

packages/artifactory/vite.config.ts — Extend root base config, add React plugin and proxy:

// Pattern from packages/react/vite.config.ts
import createReactPlugin from '@vitejs/plugin-react';
import { mergeConfig } from 'vite';
import baseConfig from '../../vite.config.ts';

export default mergeConfig(baseConfig, {
  plugins: [createReactPlugin()],
  root: '.', // Vite serves from package root
  server: {
    port: 5180,
    proxy: {
      '/api': 'http://localhost:5181', // Proxy API calls to Express
    },
  },
});

packages/artifactory/vitest.config.ts — Extend shared config, jsdom environment:

// Pattern from packages/react/vitest.config.ts
import createReactPlugin from '@vitejs/plugin-react';
import { mergeConfig } from 'vitest/config';
import baseConfig from '../../config/vitest.config.ts';

export default mergeConfig(baseConfig, {
  plugins: [createReactPlugin()],
  test: {
    coverage: { include: ['src/**/*.{ts,tsx}'] },
    environment: 'jsdom',
    include: ['src/**/__tests__/*.test.{ts,tsx}'],
    setupFiles: ['vitest.setup.ts'],
  },
});

Additional config files (follow existing patterns):

• packages/artifactory/eslint.config.js — Extend root config + react plugin (pattern from packages/react/eslint.config.js)
• packages/artifactory/tsconfig.eslint.json — For ESLint TypeScript parsing
• packages/artifactory/vitest.setup.ts — Import @testing-library/jest-dom/vitest
• packages/artifactory/index.html — Vite entry point, loads src/client/main.tsx

0c. Directory structure

packages/artifactory/
├── index.html
├── package.json
├── tsconfig.json
├── tsconfig.eslint.json
├── vite.config.ts
├── vitest.config.ts
├── vitest.setup.ts
├── eslint.config.js
└── src/
    ├── client/                     # React + Excalibur frontend
    │   ├── main.tsx                # React entry point
    │   ├── App.tsx
    │   ├── api/
    │   │   └── client.ts           # API fetch functions
    │   ├── components/
    │   │   ├── GameCanvas.tsx       # Excalibur mount point
    │   │   ├── RunSelector.tsx      # Project/ticket/run picker
    │   │   └── StatusBar.tsx        # Top bar with run info
    │   ├── game/
    │   │   ├── scenes/
    │   │   │   └── FactoryScene.ts  # Main game scene
    │   │   ├── actors/
    │   │   │   ├── AgentActor.ts    # Worker sprite
    │   │   │   ├── ArtifactActor.ts # Crate sprite
    │   │   │   ├── StationActor.ts  # Phase station
    │   │   │   └── GateActor.ts     # Dependency gate
    │   │   └── mappers/
    │   │       └── run-to-scene.ts  # Data → game entities
    │   └── hooks/
    │       └── useRunStatus.ts      # Polling hook
    ├── server/
    │   ├── index.ts                 # Express app entry
    │   ├── routes/
    │   │   ├── projects.ts          # GET /api/projects, /api/projects/:slug/runs
    │   │   ├── runs.ts              # GET /api/runs/:runId
    │   │   └── artifacts.ts         # GET /api/runs/:runId/artifacts/:filename
    │   ├── services/
    │   │   └── project-scanner.ts   # Filesystem discovery + indexing
    │   └── adapters/
    │       └── status-adapter.ts    # Normalize status.json schema versions
    └── shared/
        ├── types/
        │   ├── canonical.ts         # Normalized run status types
        │   └── api.ts               # API request/response types
        └── constants/
            └── palette.ts           # CGA/EGA color definitions

Verification (Phase 0)

• pnpm install succeeds
• pnpm run ws typecheck passes in packages/artifactory
• pnpm run ws lint passes
• pnpm run ws test runs (placeholder test)
• Root pnpm run check still passes

---

Phase 1: Shared Types + Backend API

1a. Canonical types (src/shared/types/canonical.ts)

Types mirror the current SKILL.md status.json schema directly — no normalization layer needed for current-format runs. The types serve as the shared contract between server and client.

// Matches current orchestrate SKILL.md status.json schema
interface RunStatus {
  runId: string;
  projectSlug: string;
  ticketId: string | undefined;
  projectRoot: string;
  branch: string;
  task: string;
  startedAt: string;           // ISO 8601
  completedAt: string | undefined;
  status: 'in_progress' | 'completed' | 'failed' | 'needs_manual_review';
  externalPlan: boolean;
  mergeBaseSha: string | undefined;
  diffBase: string | undefined;
  maxReviewRounds: number | undefined;
  fixLowFindings: boolean | undefined;
  phases: Phases;
  phaseDecision: Record<string, { run: boolean; reason: string }>;
}

interface Phases {
  architecture: ArchitecturePhase | undefined;
  planning: PlanningPhase | undefined;
  implementation: ImplementationPhase | undefined;
  parallelReview: ParallelReviewPhase | undefined;
  codeSimplifier: CodeSimplifierPhase | undefined;
  holisticReview: HolisticReviewPhase | undefined;
}

type Criticality = 'none' | 'low' | 'medium' | 'high';
type ReviewerStatus = 'completed' | 'skipped' | 'failed';

interface ParallelReviewPhase {
  aggregatedCriticality: Criticality;
  reviewRoundsUsed: number;
  reviewers: Record<string, {
    status: ReviewerStatus;
    criticality: Criticality | undefined;
    reason: string | undefined;          // For skipped reviewers
    reReviewCriticality: Criticality | undefined;
    reReviewError: string | undefined;
  }>;
  coderFixCycleRan: boolean;
  selectiveReReview: {
    ran: boolean;
    reviewersDispatched: string[];
    additionalFixCycleRan: boolean;
  } | undefined;
}

// ... other phase interfaces follow same structure from SKILL.md

1b. Status adapter (src/server/adapters/status-adapter.ts)

Primary path: Parse current-format status.json directly into RunStatus types. Validate required fields, use undefined for optional ones.

Legacy path: Detect V1 runs (absence of parallelReview key in phases). Convert phases.review → phases.parallelReview with a single "core" reviewer. Best-effort — not the primary development target.

Write unit tests using an anonymized copy of the MAC-122 status.json as the primary fixture, plus one V1 fixture for legacy coverage.

1c. Project scanner (src/server/services/project-scanner.ts)

Scan ~/.ai/projects/ on startup. Build an in-memory index:

interface ProjectIndex {
  projects: Array<{
    slug: string;
    tickets: Array<{
      ticketId: string;
      runs: Array<{
        runId: string;
        path: string;         // Absolute path to run directory
        status: string;       // Quick status from status.json
        startedAt: string;
      }>;
    }>;
  }>;
}

Handle two directory patterns observed:

• ~/.ai/projects/{slug}/tickets/{ticket-id}/{run-id}/ (most runs)
• ~/.ai/projects/{slug}/{ticket-id}/{run-id}/ (RAD-1 run — no tickets/ directory)

Support configurable base path via AI_PROJECTS_PATH environment variable, defaulting to ~/.ai/projects.

1d. Express routes (src/server/routes/)

Endpoint	Returns
GET /api/projects	ProjectIndex — full tree
GET /api/runs/:projectSlug/:runId	CanonicalRunStatus
GET /api/runs/:projectSlug/:runId/artifacts	List of artifact filenames in run directory
GET /api/runs/:projectSlug/:runId/artifacts/:filename	Raw markdown content

1e. Express server (src/server/index.ts)

• Port 5181
• CORS enabled for dev (localhost:5180)
• Scan projects on startup, log count
• JSON body parsing
• Error handling middleware

Verification (Phase 1)

• Unit tests for status adapter with V1 and V2 fixtures
• Unit tests for project scanner with mock filesystem
• Manual: tsx src/server/index.ts starts, curl localhost:5181/api/projects returns real data
• Manual: curl localhost:5181/api/runs/configs-macos/20260225-0923Z-orchestrated returns canonical status

---

Phase 2: React Shell + API Client + Polling

2a. API client (src/client/api/client.ts)

Typed fetch wrappers for all endpoints. Returns canonical types from src/shared/types/.

2b. React app shell

• App.tsx: Layout with sidebar (RunSelector) and main area (GameCanvas placeholder)
• RunSelector.tsx: Dropdowns for project → ticket → run. Loads project index on mount.
• StatusBar.tsx: Displays run metadata (ID, status, duration, branch)

2c. Polling hook (src/client/hooks/useRunStatus.ts)

• Polls /api/runs/:slug/:runId every 2 seconds when status === 'in_progress'
• Stops polling when run completes
• Compares previous/current to avoid unnecessary re-renders
• Returns { data, isLoading, error }

2d. Minimal styling

CSS modules or inline styles. Dark background (CGA black #000000), retro-styled UI controls. No Tailwind — keep dependencies minimal.

Verification (Phase 2)

• pnpm dev starts both servers, frontend loads at localhost:5180
• RunSelector populates with real projects/tickets/runs from ~/.ai/projects/
• Selecting a run shows its canonical status in StatusBar
• Browser DevTools Network tab shows polling behavior (2s interval, stops for completed runs)

---

Phase 3: Static Excalibur Scene

3a. GameCanvas component (src/client/components/GameCanvas.tsx)

React component that mounts an Excalibur Engine to a canvas element. Manages engine lifecycle (start/stop) via useEffect. Receives CanonicalRunStatus as prop, passes to scene.

3b. Factory scene (src/client/game/scenes/FactoryScene.ts)

Excalibur Scene subclass. Layout:

• Dark background (CGA palette)
• Horizontal platform/girder spanning the width
• 7 station positions along the platform (left → right):
  1. Architecture
  2. Planning
  3. Implementation
  4. Parallel Review (vertically stacked: core, silent-failure, test, code)
  5. Code Simplifier
  6. Holistic Review
  7. Summary

3c. Actors

All use Excalibur's Actor class with colored rectangles (procedural sprites — no art assets yet):

• StationActor: Platform segment with label text. Gray if phase skipped, colored if ran.
• AgentActor: Small colored rectangle representing a worker. Positioned at their current phase station. Colors: architect=blue, planner=green, coder=yellow, reviewers=red variants.
• ArtifactActor: Small colored square representing a crate near its owning station. Colors per issue: blue=architecture, green=plan, yellow=code, red=findings.
• GateActor: Vertical bar between stations. Green if dependency met, red/gray if not.

3d. Run-to-scene mapper (src/client/game/mappers/run-to-scene.ts)

Pure function: CanonicalRunStatus → SceneConfig. Maps:

• Which stations are active vs skipped
• Where each agent currently "is" (based on phase status)
• Which artifacts exist at each station
• Which gates are open (dependency complete) vs closed

3e. Color palette (src/shared/constants/palette.ts)

CGA/EGA-inspired constants:

export const PALETTE = {
  black: '#000000',
  darkBlue: '#0000AA',
  darkGreen: '#00AA00',
  darkCyan: '#00AAAA',
  darkRed: '#AA0000',
  darkMagenta: '#AA00AA',
  brown: '#AA5500',
  lightGray: '#AAAAAA',
  darkGray: '#555555',
  blue: '#5555FF',
  green: '#55FF55',
  cyan: '#55FFFF',
  red: '#FF5555',
  magenta: '#FF55FF',
  yellow: '#FFFF55',
  white: '#FFFFFF',
} as const;

Verification (Phase 3)

• Select a completed run → canvas renders all phase stations with colored agents
• Skipped phases (e.g., architecture on a small task) show grayed stations
• Parallel review station shows 4 vertically stacked reviewer agents
• Artifacts visible as crates at their stations
• Gates colored correctly (green for completed dependencies)
• Canvas renders at 60fps (check via browser DevTools Performance tab)

---

Files to Create

File	Phase	Purpose
packages/artifactory/package.json	0	Package definition
packages/artifactory/index.html	0	Vite HTML entry
packages/artifactory/tsconfig.json	0	TypeScript config
packages/artifactory/tsconfig.eslint.json	0	ESLint TS config
packages/artifactory/vite.config.ts	0	Vite + proxy config
packages/artifactory/vitest.config.ts	0	Test config
packages/artifactory/vitest.setup.ts	0	Test setup
packages/artifactory/eslint.config.js	0	Lint config
src/shared/types/canonical.ts	1	Normalized data model
src/shared/types/api.ts	1	API types
src/shared/constants/palette.ts	3	Color constants
src/server/index.ts	1	Express entry
src/server/adapters/status-adapter.ts	1	Schema normalization
src/server/services/project-scanner.ts	1	Filesystem discovery
src/server/routes/projects.ts	1	Project endpoints
src/server/routes/runs.ts	1	Run endpoints
src/server/routes/artifacts.ts	1	Artifact endpoints
src/client/main.tsx	2	React entry
src/client/App.tsx	2	Root component
src/client/api/client.ts	2	API fetch layer
src/client/components/RunSelector.tsx	2	Run picker
src/client/components/StatusBar.tsx	2	Run info display
src/client/components/GameCanvas.tsx	3	Excalibur mount
src/client/game/scenes/FactoryScene.ts	3	Game scene
src/client/game/actors/AgentActor.ts	3	Worker actor
src/client/game/actors/ArtifactActor.ts	3	Crate actor
src/client/game/actors/StationActor.ts	3	Station actor
src/client/game/actors/GateActor.ts	3	Gate actor
src/client/game/mappers/run-to-scene.ts	3	Data → scene
src/client/hooks/useRunStatus.ts	2	Polling hook

Files to Delete

All contents of:

• packages/api/
• packages/react/
• packages/nextjs/
• packages/svelte/
• packages/astro/
• packages/chrome/
• packages/cdk/
• packages/_workspace/

Key Patterns to Follow

• Vite config: Use mergeConfig(baseConfig, ...) pattern from packages/react/vite.config.ts
• Vitest config: Extend config/vitest.config.ts, add jsdom environment (pattern from packages/react/vitest.config.ts)
• ESLint: Spread root config + react plugin rules (pattern from packages/react/eslint.config.js)
• Workspace scripts: "ws": "node --import tsx ../../scripts/run-workspace-script.ts" with build/dev overrides
• TypeScript: Extend root tsconfig, add jsx: "react-jsx" and DOM libs

Verification (End-to-End)

After all 4 phases:

1. pnpm install — no errors
2. pnpm run check from root — typecheck, lint, format, tests all pass
3. pnpm dev from packages/artifactory — starts Express (5181) + Vite (5180)
4. Open http://localhost:5180 — React app loads
5. RunSelector shows real projects from ~/.ai/projects/
6. Select a current-format run (MAC-122) → canvas renders static factory scene with agents at correct stations, artifacts as crates, gates reflecting dependencies
7. Verify parallel review station shows all 4 reviewer positions (core + 3 aspect reviewers)
8. In-progress run triggers 2s polling (test by editing a status.json "status": "in_progress")
9. Legacy V1 run (MAC-56) renders with best-effort adapter — review section shows single reviewer