Redesign orchestrator robot

[williamthorsen]

Description

Users find the orchestrator's "working" animation distracting — the arm motions (3-frame loop cycling through raised/extended/lowering positions at 300ms) look like a cheerleader. The orchestrator also lacks the visual authority expected of a command unit.

Replace the orchestrator robot's body and animation system:

• Body: Replace legs with tank treads, extend the torso lower for a bulkier command-unit silhouette, replace the narrow antenna with a broader 3×2 beacon lamp
• Animations: Replace arm-wave working animation with mechanical vibration (upper body shifts 1px while treads stay planted) + beacon flashing. All activity is communicated through frame-based animation — no runtime scale pulse
• State change: Orchestrator default in-progress state changes from resting to idle
• Scope: Orchestrator robot only — subagent robots are completely unchanged

Design spec

docs/superpowers/specs/2026-03-12-orchestrator-redesign-design.md

Acceptance criteria

Must have

• Orchestrator sprite has tank treads (18×4), wider torso (16×14), beacon lamp (3×2), longer arms (2×8), no legs
• Orchestrator palette extended with index 6 beacon bright shade (#fff5c0)
• Working animation: body vibrates (upper body Y-1) + beacon flashes, 500ms cycle, Loop strategy
• Celebrating animation: vibrate + tread roll + visor pulse + beacon, 250ms cycle, Loop strategy
• Idle animation: still body, slow visor dim pulse, 1200ms cycle, PingPong strategy
• Concerned animation: head slouched +1px, beacon off, single frame, Freeze strategy
• Walking animation: tread pattern scrolls + beacon flashes, 300ms cycle, Loop strategy
• Deactivated: reuses idle with reduced opacity (unchanged behavior)
• OrchestratorActor scale pulse removed (_elapsed, onPreUpdate deleted)
• Orchestrator default in-progress state changed from resting to idle in agent-state-resolver.ts
• Frame config split: frameConfigForState() accepts CatwalkSpriteType parameter
• All subagent animations and behavior completely unchanged
• All tests pass, typecheck clean, lint clean

Should have

• Preview renderer updated with per-sprite-type animation definitions
• Timing values stored as named constants (ORCH_WORKING_DURATION, etc.)

Nice to have

• Follow-up ticket created for subagent idle/resting state semantic distinction

[williamthorsen]

Implementation plan

2026-03-12-orchestrator-redesign.md

Orchestrator robot redesign implementation plan

For agentic workers: REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Replace the orchestrator robot's cheerleader arm-wave animation with a tank-tread body that uses vibration, beacon flashing, and visor pulses to show activity states.

Architecture: The orchestrator sprite is rebuilt from scratch in orchestrator-poses.ts with new body parts (beacon lamp, wider torso, tank treads) composed into 9 poses for a 12-frame sprite sheet. Frame timing and coordinates are split per sprite type so the subagent animations remain untouched. The OrchestratorActor is simplified by removing its scale-pulse logic — animation is now fully frame-driven.

Tech Stack: TypeScript, Excalibur.js (game engine), SVG sprite sheets, Vitest

Spec: docs/superpowers/specs/2026-03-12-orchestrator-redesign-design.md

---

File structure

File	Action	Responsibility
packages/factory/scripts/sprites/palettes.ts	Modify	Add beacon bright shade (index 6) to orchestrator palette
packages/factory/scripts/sprites/orchestrator-poses.ts	Rewrite	New body parts + 9 pose compositions (was 12 with old body)
packages/factory/scripts/sprites/preview-renderer.ts	Modify	Update frame labels and animation defs for orchestrator's new layout
packages/factory/src/client/game/sprites/sprite-definitions.ts	Modify	Add ORCH_* frame coordinates/durations/strategies for orchestrator
packages/factory/src/client/visualizations/catwalk/sprites/catwalk-sprite-loader.ts	Modify	Split frameConfigForState() to accept sprite type
packages/factory/src/client/visualizations/catwalk/actors/OrchestratorActor.ts	Modify	Remove scale pulse, simplify to animation switching
packages/factory/src/client/game/state/agent-state-resolver.ts	Modify	Change orchestrator default from 'resting' to 'idle'
packages/factory/src/client/visualizations/catwalk/sprites/assets/orchestrator.svg	Regenerate	Output of pnpm generate-sprites

Test files affected:

File	Action
packages/factory/scripts/sprites/__tests__/svg-renderer.test.ts	May need palette length adjustment
packages/factory/src/client/game/sprites/__tests__/sprite-definitions.test.ts	Add orchestrator-specific constant tests
packages/factory/src/client/visualizations/catwalk/actors/__tests__/actors.test.ts	Update OrchestratorActor tests (remove scale pulse expectations)
packages/factory/src/client/visualizations/catwalk/sprites/__tests__/catwalk-sprite-loader.test.ts	Update for sprite-type-aware frame config
packages/factory/src/client/game/state/__tests__/agent-state-resolver.test.ts	Update orchestrator 'resting' → 'idle' expectations

---

Chunk 1: Palette and body parts

Task 1: Extend orchestrator palette with beacon bright shade

Files:

• Modify: packages/factory/scripts/sprites/palettes.ts

• Create: packages/factory/scripts/sprites/__tests__/palettes.test.ts

• Modify: packages/factory/scripts/sprites/__tests__/svg-renderer.test.ts (update pixel range from 0-5 to 0-6)

• Step 1: Write the failing test

Create packages/factory/scripts/sprites/__tests__/palettes.test.ts:

import { describe, expect, it } from 'vitest';

import { ORCHESTRATOR_PALETTE, SUBAGENT_PALETTE } from '../palettes.ts';

describe('ORCHESTRATOR_PALETTE', () => {
  it('has 7 entries (transparent + 5 shades + beacon bright)', () => {
    expect(ORCHESTRATOR_PALETTE).toHaveLength(7);
    expect(ORCHESTRATOR_PALETTE[0]).toBe('');
    expect(ORCHESTRATOR_PALETTE[6]).toBe('#fff5c0');
  });
});

describe('SUBAGENT_PALETTE', () => {
  it('has 6 entries (transparent + 5 shades) and is unchanged', () => {
    expect(SUBAGENT_PALETTE).toHaveLength(6);
  });
});

• Step 2: Run test to verify it fails

Run: pnpm --filter factory run test -- --run palettes
Expected: FAIL — palette has length 6, not 7.

• Step 3: Implement the palette extension

In palettes.ts, modify ORCHESTRATOR_PALETTE to append the beacon bright shade:

const basePalette = generatePalette(
  ORCHESTRATOR_HSL.hue,
  ORCHESTRATOR_HSL.saturation,
  ORCHESTRATOR_HSL.minLightness,
  ORCHESTRATOR_HSL.maxLightness,
);

/** Gold command-unit palette for the orchestrator robot, with beacon bright at index 6. */
export const ORCHESTRATOR_PALETTE: Palette = [...basePalette, '#fff5c0'] as Palette;

• Step 4: Run test to verify it passes

Run: pnpm --filter factory run test -- --run palettes
Expected: PASS

• Step 5: Update existing svg-renderer test for new palette range

In packages/factory/scripts/sprites/__tests__/svg-renderer.test.ts line 291, change:

// Before
).toBeLessThanOrEqual(5);
// After
).toBeLessThanOrEqual(6);

Run: pnpm --filter factory run test -- --run svg-renderer
Expected: PASS

• Step 6: Commit

git add packages/factory/scripts/sprites/palettes.ts packages/factory/scripts/sprites/__tests__/
git commit -m "feat: add beacon bright shade to orchestrator palette"

Task 2: Rewrite orchestrator body parts and poses

Files:

• Rewrite: packages/factory/scripts/sprites/orchestrator-poses.ts
• Create: packages/factory/scripts/sprites/__tests__/orchestrator-poses.test.ts

Pixel data reference: The visual mockup at .superpowers/brainstorm/29114-1773336772/all-states-v3.html contains the exact pixel grids rendered in the browser. Use these as reference for exact pixel values.

• Step 1: Write the failing test

Create packages/factory/scripts/sprites/__tests__/orchestrator-poses.test.ts:

import { describe, expect, it } from 'vitest';

import { ORCHESTRATOR_POSES } from '../orchestrator-poses.ts';

describe('ORCHESTRATOR_POSES', () => {
  it('exports exactly 12 poses', () => {
    expect(ORCHESTRATOR_POSES).toHaveLength(12);
  });

  it('every pixel index is within 0-6 (palette range including beacon bright)', () => {
    for (const [poseIndex, pose] of ORCHESTRATOR_POSES.entries()) {
      for (const [partIndex, part] of pose.entries()) {
        for (const [rowIndex, row] of part.pixels.entries()) {
          for (const [colIndex, value] of row.entries()) {
            expect(
              value,
              `pose ${poseIndex}, part ${partIndex}, row ${rowIndex}, col ${colIndex}: value ${value} out of range`,
            ).toBeGreaterThanOrEqual(0);
            expect(
              value,
              `pose ${poseIndex}, part ${partIndex}, row ${rowIndex}, col ${colIndex}: value ${value} out of range`,
            ).toBeLessThanOrEqual(6);
          }
        }
      }
    }
  });

  it('every pose has treads at offsetY 26 (bottom-anchored)', () => {
    for (const [index, pose] of ORCHESTRATOR_POSES.entries()) {
      const treadPart = pose[0];
      expect(treadPart?.offsetY, `pose ${index} treads not at row 26`).toBe(26);
    }
  });

  it('beacon on frames use palette index 6', () => {
    // Frame 4 (Working 1) should have beacon with index 6 pixels
    const beaconPart = ORCHESTRATOR_POSES[4]?.[5]; // last part = beacon
    expect(beaconPart).toBeDefined();
    const hasIndex6 = beaconPart!.pixels.some((row) => row.some((value) => value === 6));
    expect(hasIndex6).toBe(true);
  });
});

• Step 2: Run test to verify it fails

Run: pnpm --filter factory run test -- --run orchestrator-poses
Expected: FAIL (old poses have different structure).

• Step 3: Implement the new body parts and poses

Rewrite orchestrator-poses.ts with these body parts. All pixel grids must be complete — use the mockup HTML as reference for exact values.

Body part dimensions and positions:

Part	Width × Height	offsetX	offsetY	Notes
BEACON_ON	3×2	14	1	Top row: [6,6,6], bottom row: [5,4,5]
BEACON_OFF	3×2	14	1	Top row: [3,2,3], bottom row: [2,1,2]
HEAD	12×8	10	3	Same pixel data as current HEAD, repositioned
HEAD_SLOUCH	12×8	10	4	Same pixels as HEAD, +1px down
HEAD_VISOR_DIM	12×8	10	3	Visor rows 3-4 of pixel grid use index 3 instead of 5
HEAD_VISOR_BRIGHT	12×8	10	3	Visor rows 3-4 of pixel grid use index 6 instead of 5
TORSO	16×14	8	11	Extended from current 14×11. Follow existing shading pattern (5=left highlight, 1=right shadow, 3=body fill, 2=lower body) with chest panel band at row 4
TREADS_A	18×4	7	26	Row 0: all 1s (top border). Row 1: [1,2,2,...,2,1] (body). Row 2: alternating [1,3,1,3,...,1]. Row 3: all 1s (bottom border)
TREADS_B	18×4	7	26	Same as A but row 2 shifted: [1,1,3,1,3,...,1]
ARM_LEFT	2×8	6	12	Same shading as current ARM_LEFT_DOWN but 8 rows (was 7)
ARM_RIGHT	2×8	24	12	Same shading as current ARM_RIGHT_DOWN but 8 rows (was 7)

Vibrate helper:

function vibrate(part: BodyPart): BodyPart {
  return { ...part, offsetY: part.offsetY - 1 };
}

9 poses + 3 spare (spare slots reuse the idle base pose):

export const ORCHESTRATOR_POSES: Pose[] = [
  // Frame 0: Idle 1 — beacon dim, visor normal, treads A
  [TREADS_A, TORSO, ARM_LEFT, ARM_RIGHT, HEAD, BEACON_OFF],
  // Frame 1: Idle 2 — beacon dim, visor dimmed, treads A
  [TREADS_A, TORSO, ARM_LEFT, ARM_RIGHT, HEAD_VISOR_DIM, BEACON_OFF],
  // Frame 2: Concerned — head slouched, beacon dim
  [TREADS_A, TORSO, ARM_LEFT, ARM_RIGHT, HEAD_SLOUCH, BEACON_OFF],
  // Frame 3: (spare)
  [TREADS_A, TORSO, ARM_LEFT, ARM_RIGHT, HEAD, BEACON_OFF],
  // Frame 4: Working 1 — beacon on, body at normal Y
  [TREADS_A, TORSO, ARM_LEFT, ARM_RIGHT, HEAD, BEACON_ON],
  // Frame 5: Working 2 — beacon off, upper body Y-1
  [TREADS_A, vibrate(TORSO), vibrate(ARM_LEFT), vibrate(ARM_RIGHT), vibrate(HEAD), vibrate(BEACON_OFF)],
  // Frame 6: Walking 1 — beacon on, treads A
  [TREADS_A, TORSO, ARM_LEFT, ARM_RIGHT, HEAD, BEACON_ON],
  // Frame 7: Walking 2 — beacon off, treads B
  [TREADS_B, TORSO, ARM_LEFT, ARM_RIGHT, HEAD, BEACON_OFF],
  // Frame 8: Celebrating 1 — beacon on, visor bright, treads A, normal Y
  [TREADS_A, TORSO, ARM_LEFT, ARM_RIGHT, HEAD_VISOR_BRIGHT, BEACON_ON],
  // Frame 9: Celebrating 2 — beacon on, visor normal, treads B, upper body Y-1
  [TREADS_B, vibrate(TORSO), vibrate(ARM_LEFT), vibrate(ARM_RIGHT), vibrate(HEAD), vibrate(BEACON_ON)],
  // Frame 10: (spare)
  [TREADS_A, TORSO, ARM_LEFT, ARM_RIGHT, HEAD, BEACON_OFF],
  // Frame 11: (spare)
  [TREADS_A, TORSO, ARM_LEFT, ARM_RIGHT, HEAD, BEACON_OFF],
];

• Step 4: Run tests to verify they pass

Run: pnpm --filter factory run test -- --run orchestrator-poses
Expected: PASS

Also run: pnpm --filter factory run test -- --run svg-renderer
Expected: PASS (existing pose tests should pass with updated pixel range).

• Step 5: Regenerate the SVG sprite sheet

Run: pnpm --filter factory run generate-sprites
Expected: orchestrator.svg is regenerated in src/client/visualizations/catwalk/sprites/assets/. Open the preview HTML to visually verify the new poses look correct.

• Step 6: Commit

git add packages/factory/scripts/sprites/orchestrator-poses.ts packages/factory/scripts/sprites/__tests__/ packages/factory/src/client/visualizations/catwalk/sprites/assets/orchestrator.svg
git commit -m "feat: rewrite orchestrator body with tank treads and beacon lamp"

---

Chunk 2: Frame config split and sprite definitions

Task 3: Add orchestrator-specific frame coordinates and timing to sprite-definitions

Files:

• Modify: packages/factory/src/client/game/sprites/sprite-definitions.ts

• Modify: packages/factory/src/client/game/sprites/__tests__/sprite-definitions.test.ts

• Step 1: Write the failing tests

Add tests for the new orchestrator constants. These exist alongside the current (now subagent-only) constants:

The existing test file uses a single const { ... } = await import('../sprite-definitions.js') for all constants. Add all ORCH_* exports to this destructuring.

describe('orchestrator frame coordinates', () => {
  it('ORCH_IDLE_FRAME_COORDINATES has 2 frames at row 0', () => {
    expect(ORCH_IDLE_FRAME_COORDINATES).toEqual([
      { x: 0, y: 0 },
      { x: 1, y: 0 },
    ]);
  });

  it('ORCH_WORKING_FRAME_COORDINATES has 2 frames at row 1', () => {
    expect(ORCH_WORKING_FRAME_COORDINATES).toEqual([
      { x: 0, y: 1 },
      { x: 1, y: 1 },
    ]);
  });

  it('ORCH_WALKING_FRAME_COORDINATES has 2 frames at row 1', () => {
    expect(ORCH_WALKING_FRAME_COORDINATES).toEqual([
      { x: 2, y: 1 },
      { x: 3, y: 1 },
    ]);
  });

  it('ORCH_CELEBRATING_FRAME_COORDINATES has 2 frames at row 2', () => {
    expect(ORCH_CELEBRATING_FRAME_COORDINATES).toEqual([
      { x: 0, y: 2 },
      { x: 1, y: 2 },
    ]);
  });

  it('ORCH_CONCERNED_FRAME_COORDINATES has 1 frame at (2,0)', () => {
    expect(ORCH_CONCERNED_FRAME_COORDINATES).toEqual([{ x: 2, y: 0 }]);
  });
});

describe('orchestrator timing', () => {
  it('ORCH_WORKING_DURATION is 500ms', () => {
    expect(ORCH_WORKING_DURATION).toBe(500);
  });

  it('ORCH_CELEBRATING_DURATION is 250ms', () => {
    expect(ORCH_CELEBRATING_DURATION).toBe(250);
  });

  it('ORCH_IDLE_DURATION is 1200ms', () => {
    expect(ORCH_IDLE_DURATION).toBe(1200);
  });

  it('ORCH_WALKING_DURATION is 300ms', () => {
    expect(ORCH_WALKING_DURATION).toBe(300);
  });
});

describe('orchestrator strategies', () => {
  it('ORCH_WORKING_STRATEGY is Loop', () => {
    expect(ORCH_WORKING_STRATEGY).toBe(AnimationStrategy.Loop);
  });

  // Note: This deliberately differs from subagent CELEBRATING_STRATEGY (PingPong).
  // The orchestrator's celebrating animation is a 2-frame alternation (vibrate + tread roll)
  // that must loop continuously, not ping-pong.
  it('ORCH_CELEBRATING_STRATEGY is Loop (not PingPong like subagent)', () => {
    expect(ORCH_CELEBRATING_STRATEGY).toBe(AnimationStrategy.Loop);
  });

  it('ORCH_IDLE_STRATEGY is PingPong', () => {
    expect(ORCH_IDLE_STRATEGY).toBe(AnimationStrategy.PingPong);
  });

  it('ORCH_WALKING_STRATEGY is Loop', () => {
    expect(ORCH_WALKING_STRATEGY).toBe(AnimationStrategy.Loop);
  });

  it('ORCH_CONCERNED_STRATEGY is Freeze', () => {
    expect(ORCH_CONCERNED_STRATEGY).toBe(AnimationStrategy.Freeze);
  });
});

• Step 2: Run tests to verify they fail

Run: pnpm --filter factory run test -- --run sprite-definitions
Expected: FAIL — constants don't exist yet.

• Step 3: Add the orchestrator constants

In sprite-definitions.ts, add after the existing constants. Note: AnimationStrategy is imported from excalibur (line 1 of the file).

Important: The orchestrator celebrating strategy is Loop, deliberately differing from the subagent's PingPong. This is correct — the orchestrator's 2-frame celebrating animation alternates vibration + tread roll and must loop continuously.

// ── Orchestrator-specific frame coordinates ──
// The orchestrator uses a different sprite sheet layout than subagents.
// Row 0: idle 1 (0,0), idle 2 (1,0), concerned (2,0), spare (3,0)
// Row 1: working 1 (0,1), working 2 (1,1), walking 1 (2,1), walking 2 (3,1)
// Row 2: celebrating 1 (0,2), celebrating 2 (1,2), spare (2,2), spare (3,2)

export const ORCH_IDLE_FRAME_COORDINATES: ReadonlyArray<{ x: number; y: number }> = [
  { x: 0, y: 0 },
  { x: 1, y: 0 },
];

export const ORCH_WORKING_FRAME_COORDINATES: ReadonlyArray<{ x: number; y: number }> = [
  { x: 0, y: 1 },
  { x: 1, y: 1 },
];

export const ORCH_WALKING_FRAME_COORDINATES: ReadonlyArray<{ x: number; y: number }> = [
  { x: 2, y: 1 },
  { x: 3, y: 1 },
];

export const ORCH_CELEBRATING_FRAME_COORDINATES: ReadonlyArray<{ x: number; y: number }> = [
  { x: 0, y: 2 },
  { x: 1, y: 2 },
];

export const ORCH_CONCERNED_FRAME_COORDINATES: ReadonlyArray<{ x: number; y: number }> = [{ x: 2, y: 0 }];

// Orchestrator timing (per frame)
export const ORCH_IDLE_DURATION = 1200;
export const ORCH_WORKING_DURATION = 500;
export const ORCH_WALKING_DURATION = 300;
export const ORCH_CELEBRATING_DURATION = 250;
export const ORCH_CONCERNED_DURATION = 600;

// Orchestrator strategies
export const ORCH_IDLE_STRATEGY = AnimationStrategy.PingPong;
export const ORCH_WORKING_STRATEGY = AnimationStrategy.Loop;
export const ORCH_WALKING_STRATEGY = AnimationStrategy.Loop;
export const ORCH_CELEBRATING_STRATEGY = AnimationStrategy.Loop;
export const ORCH_CONCERNED_STRATEGY = AnimationStrategy.Freeze;

• Step 4: Run tests to verify they pass

Run: pnpm --filter factory run test -- --run sprite-definitions
Expected: PASS

• Step 5: Commit

git add packages/factory/src/client/game/sprites/sprite-definitions.ts packages/factory/src/client/game/sprites/__tests__/sprite-definitions.test.ts
git commit -m "feat: add orchestrator-specific sprite frame coordinates and timing"

Task 4: Split catwalk sprite loader frame config by sprite type

Files:

• Modify: packages/factory/src/client/visualizations/catwalk/sprites/catwalk-sprite-loader.ts

• Modify: packages/factory/src/client/visualizations/catwalk/sprites/__tests__/catwalk-sprite-loader.test.ts

• Step 1: Write the failing test

The existing tests mock Animation.fromSpriteSheetCoordinates via mockAnimationFromCoords. Add tests that verify the orchestrator path uses ORCH_* constants while the subagent path uses the original constants:

it('orchestrator working animation uses ORCH_WORKING_DURATION (500ms)', () => {
  loadAllCatwalkSprites();
  const workingCall = mockAnimationFromCoords.mock.calls.find(
    (call) =>
      call[0]?.frameCoordinates?.[0]?.x === ORCH_WORKING_FRAME_COORDINATES[0].x &&
      call[0]?.frameCoordinates?.[0]?.y === ORCH_WORKING_FRAME_COORDINATES[0].y,
  );
  expect(workingCall).toBeDefined();
  expect(workingCall![0].durationPerFrameMs).toBe(ORCH_WORKING_DURATION);
  expect(workingCall![0].strategy).toBe(ORCH_WORKING_STRATEGY);
});

it('subagent working animation still uses original WORKING_DURATION (300ms)', () => {
  loadAllCatwalkSprites();
  const workingCall = mockAnimationFromCoords.mock.calls.find(
    (call) =>
      call[0]?.frameCoordinates?.[0]?.x === WORKING_FRAME_COORDINATES[0].x &&
      call[0]?.frameCoordinates?.[0]?.y === WORKING_FRAME_COORDINATES[0].y,
  );
  expect(workingCall).toBeDefined();
  expect(workingCall![0].durationPerFrameMs).toBe(WORKING_DURATION);
});

Import ORCH_WORKING_FRAME_COORDINATES, ORCH_WORKING_DURATION, ORCH_WORKING_STRATEGY, and the existing WORKING_FRAME_COORDINATES, WORKING_DURATION from sprite-definitions.js.

• Step 2: Run test to verify it fails

Run: pnpm --filter factory run test -- --run catwalk-sprite-loader
Expected: FAIL — orchestrator still uses same config as subagent.

• Step 3: Implement the sprite-type-aware frame config

In catwalk-sprite-loader.ts, modify frameConfigForState to accept a CatwalkSpriteType parameter. Import the new ORCH_* constants. When spriteType === 'orchestrator', use the orchestrator constants; otherwise use the existing subagent constants.

function frameConfigForState(
  state: AgentAnimationState,
  spriteType: CatwalkSpriteType,
): { frameCoordinates: ReadonlyArray<{ x: number; y: number }>; duration: number; strategy: AnimationStrategy } {
  if (spriteType === 'orchestrator') {
    return orchestratorFrameConfig(state);
  }
  return subagentFrameConfig(state);
}

The orchestrator config function handles only the 5 states used by the orchestrator (idle, working, walking, celebrating, concerned) plus deactivated (reuses idle). For resting, reuse idle — the orchestrator never enters resting but the type system requires handling it.

Update buildAnimationsForSheet to pass the sprite type through.

• Step 4: Run tests to verify they pass

Run: pnpm --filter factory run test -- --run catwalk-sprite-loader
Expected: PASS

• Step 5: Run the full test suite

Run: pnpm --filter factory run test -- --run
Expected: PASS (verify no regressions in subagent behavior).

• Step 6: Commit

git add packages/factory/src/client/visualizations/catwalk/sprites/catwalk-sprite-loader.ts packages/factory/src/client/visualizations/catwalk/sprites/__tests__/catwalk-sprite-loader.test.ts packages/factory/src/client/game/sprites/sprite-definitions.ts
git commit -m "feat: split catwalk sprite frame config by sprite type"

---

Chunk 3: Actor simplification and state resolver

Task 5: Remove scale pulse from OrchestratorActor

Files:

• Modify: packages/factory/src/client/visualizations/catwalk/actors/OrchestratorActor.ts

• Modify: packages/factory/src/client/visualizations/catwalk/actors/__tests__/actors.test.ts

• Step 1: Update the tests

In actors.test.ts, update the OrchestratorActor describe block. Four tests call onPreUpdate and will break once it's removed:

1. Remove 'setWorking(true) enables pulse flag and restores full opacity' — asserts scale pulse in onPreUpdate.
2. Remove 'setWorking(false) disables pulse and sets idle opacity' — calls onPreUpdate.
3. Rewrite 'celebrate() disables working pulse and sets ACTIVE_OPACITY' (line 307) — currently calls onPreUpdate to verify pulse is disabled. Replace with a test that only checks observable state (opacity, scale, animation).
4. Rewrite 'fadeOut fades opacity to 0 and stops the working pulse' (line 321) — currently calls onPreUpdate to verify pulse is disabled. Replace with a test that only checks actions.fade was called.

Replacement tests:

it('setWorking(true) sets full opacity', () => {
  const actor = new OrchestratorActor({ working: false }, vec(0, 0));
  actor.setWorking(true);
  expect(actor.graphics.opacity).toBe(ACTIVE_OPACITY);
});

it('setWorking(false) sets idle opacity and resets scale', () => {
  const actor = new OrchestratorActor({ working: true }, vec(0, 0));
  actor.setWorking(false);
  expect(actor.graphics.opacity).toBe(ORCH_IDLE_OPACITY);
  expect(actor.scale).toEqual({ x: 1, y: 1 });
});

it('does not have onPreUpdate (no scale pulse)', () => {
  const actor = new OrchestratorActor({ working: false }, vec(0, 0));
  // onPreUpdate should be inherited default (no-op), not overridden
  expect(actor.constructor.prototype.hasOwnProperty('onPreUpdate')).toBe(false);
});

it('celebrate() sets ACTIVE_OPACITY and resets scale', () => {
  const actor = new OrchestratorActor({ working: true }, vec(0, 0));
  actor.celebrate();
  expect(actor.graphics.opacity).toBe(ACTIVE_OPACITY);
  expect(actor.scale).toEqual({ x: 1, y: 1 });
});

it('fadeOut calls actions.fade with opacity 0', () => {
  const actor = new OrchestratorActor({ working: true }, vec(0, 0));
  actor.fadeOut();
  expect(actor.actions.fade).toHaveBeenCalledWith(0, expect.any(Number));
});

• Step 2: Run tests to verify they fail

Run: pnpm --filter factory run test -- --run actors
Expected: FAIL — onPreUpdate still exists on the prototype.

• Step 3: Simplify OrchestratorActor

In OrchestratorActor.ts:

1. Remove the _elapsed field.
2. Remove the onPreUpdate override entirely.
3. Remove imports of PULSE_FREQUENCY, SCALE_PULSE_MAX, SCALE_PULSE_MIN from constants/animation.js.
4. Simplify setWorking:

setWorking(working: boolean): void {
  this._working = working;
  const animation = getAnimation('orchestrator', working ? 'working' : 'idle');
  this.graphics.use(animation);
  if (working) {
    this.graphics.opacity = ACTIVE_OPACITY;
  } else {
    this.scale = vec(1, 1);
    this.graphics.opacity = ORCH_IDLE_OPACITY;
  }
}

• Step 4: Run tests to verify they pass

Run: pnpm --filter factory run test -- --run actors
Expected: PASS

• Step 5: Verify StationAgentActor still uses scale pulse

Run: pnpm --filter factory run test -- --run actors
Expected: StationAgentActor tests still pass — it independently imports and uses the scale pulse constants.

• Step 6: Commit

git add packages/factory/src/client/visualizations/catwalk/actors/OrchestratorActor.ts packages/factory/src/client/visualizations/catwalk/actors/__tests__/actors.test.ts
git commit -m "refactor: remove scale pulse from OrchestratorActor"

Task 6: Change orchestrator default state from resting to idle

Files:

• Modify: packages/factory/src/client/game/state/agent-state-resolver.ts

• Modify: packages/factory/src/client/game/state/__tests__/agent-state-resolver.test.ts

• Step 1: Update the test expectations

In agent-state-resolver.test.ts, find all tests that assert the orchestrator gets 'resting' and change them to 'idle'. Two specific tests need updating:

1. 'assigns resting to orchestrator during in_progress' → rename to 'assigns idle to orchestrator during in_progress' and change expected value to 'idle'
2. 'assigns resting to orchestrator even when currentPhase matches its station' → rename to 'assigns idle to orchestrator even when currentPhase matches its station' and change expected value to 'idle'

Search the entire file for: expect(result[0]?.animationState).toBe('resting') — update every instance where the test subject is an orchestrator agent. Leave subagent 'resting' assertions unchanged.

• Step 2: Run tests to verify they fail

Run: pnpm --filter factory run test -- --run agent-state-resolver
Expected: FAIL — orchestrator still returns 'resting'.

• Step 3: Change the resolver

In agent-state-resolver.ts line 94, change:

// Before
return buildStateInfo(agent, 'resting');

// After
return buildStateInfo(agent, 'idle');

• Step 4: Run tests to verify they pass

Run: pnpm --filter factory run test -- --run agent-state-resolver
Expected: PASS

• Step 5: Run full test suite to check for ripple effects

Run: pnpm --filter factory run test -- --run

Check for failures in catwalk differ tests, choreographer tests, or run-to-catwalk mapper tests that may assert orchestrator state as 'resting'. Update those expectations to 'idle' as needed.

• Step 6: Commit

git add packages/factory/src/client/game/state/agent-state-resolver.ts packages/factory/src/client/game/state/__tests__/agent-state-resolver.test.ts
git commit -m "feat: orchestrator uses idle instead of resting as default state"

If other test files needed updates, include them in the commit.

---

Chunk 4: Preview renderer and final verification

Task 7: Update preview renderer for orchestrator layout

Files:

• Modify: packages/factory/scripts/sprites/preview-renderer.ts

• Step 1: Update frame labels and animation definitions

The preview renderer hardcodes frame labels and animation definitions. Update for the orchestrator's new layout:

The frame labels array is shared for both sprite types, but the orchestrator now has different frame assignments. The simplest approach: make the renderPreviewHtml function accept per-type animation definitions instead of sharing one set. Or: update the shared labels to be generic enough for both (e.g. Frame 0, Frame 1...) and rely on the animation previews to show the actual behavior.

Two things need splitting by sprite type:

1. ANIMATION_NAMES (line 20): This drives renderAnimationSectionsHtml() which generates HTML cells for both columns. Without splitting, the orchestrator column would render a "Resting" cell that the JS never populates. Parameterize renderAnimationSectionsHtml to accept a per-type names list (the idPrefix parameter already differentiates columns):

const SUBAGENT_ANIMATION_NAMES = ['Idle', 'Walking', 'Working', 'Celebrating', 'Concerned', 'Resting'];
const ORCHESTRATOR_ANIMATION_NAMES = ['Idle', 'Walking', 'Working', 'Celebrating', 'Concerned'];

function renderAnimationSectionsHtml(idPrefix: string, animationNames: readonly string[]): string {
  return animationNames.map((name) => { ... }).join('\n');
}

2. Animation definitions in the <script> block (line 144-151): Subagent keeps the current definitions, orchestrator gets:

var orchestratorAnimations = [
  {
    name: 'idle',
    frames: [
      { x: 0, y: 0 },
      { x: 1, y: 0 },
    ],
    duration: 1200,
    strategy: PING_PONG,
  },
  {
    name: 'walking',
    frames: [
      { x: 2, y: 1 },
      { x: 3, y: 1 },
    ],
    duration: 300,
    strategy: LOOP,
  },
  {
    name: 'working',
    frames: [
      { x: 0, y: 1 },
      { x: 1, y: 1 },
    ],
    duration: 500,
    strategy: LOOP,
  },
  {
    name: 'celebrating',
    frames: [
      { x: 0, y: 2 },
      { x: 1, y: 2 },
    ],
    duration: 250,
    strategy: LOOP,
  },
  { name: 'concerned', frames: [{ x: 2, y: 0 }], duration: 600, strategy: FREEZE },
];

Remove 'resting' from orchestrator animations (it doesn't use it).

• Step 2: Run the generator to verify output

Run: pnpm --filter factory run generate-sprites
Open the preview HTML and verify both sprite types animate correctly.

• Step 3: Commit

git add packages/factory/scripts/sprites/preview-renderer.ts
git commit -m "feat: update preview renderer for orchestrator's new sprite layout"

Task 8: Final verification

• Step 1: Run the full test suite

Run: pnpm --filter factory run test -- --run
Expected: All tests pass.

• Step 2: Run typecheck

Run: pnpm --filter factory run typecheck
Expected: No type errors.

• Step 3: Run lint

Run: pnpm --filter factory run lint
Expected: No lint errors.

• Step 4: Regenerate sprites and visually verify

Run: pnpm --filter factory run generate-sprites
Open the preview HTML. Verify:

• Orchestrator has tank tread body, beacon lamp, wider torso

• Idle animation: slow visor dim pulse, body still

• Working animation: body vibrates (upper body shifts 1px), beacon flashes, 500ms cycle

• Celebrating animation: fast vibrate + tread roll + visor pulse + beacon, 250ms cycle

• Walking animation: tread pattern scrolls + beacon flashes, 300ms cycle

• Concerned animation: head slouched, static

• Subagent animations: completely unchanged from before

• Step 5: Final commit (if any remaining changes)

git add -A
git commit -m "chore: regenerate orchestrator sprite sheet with new body design"

[williamthorsen]

Design insights

Vibration must be baked into sprite frames, not applied at runtime.
Excalibur.js renders each sprite frame as a single graphic — you cannot shift part of a sprite at runtime. The vibration effect (upper body moves 1px while treads stay planted) is achieved by having two frames in the sprite sheet: one at normal Y, one with upper body parts at offsetY-1. The actor simply switches between these frames.

Palette index 6 works without type changes.
The Palette type (readonly [transparent: '', ...colors: string[]]) already supports arbitrary length. The SVG renderer uses palette[paletteIndex] dynamically, so adding index 6 for the beacon bright shade requires zero changes to the type system or renderer.

Frame config must be split per sprite type.
The orchestrator's new sprite sheet layout is incompatible with the subagent's (different frame counts, grid positions, timing, and strategies per state). The frameConfigForState() function in catwalk-sprite-loader.ts must accept a CatwalkSpriteType parameter. The subagent constants keep their current unprefixed names; orchestrator constants use ORCH_* prefix.

The orchestrator celebrating strategy deliberately differs from the subagent.
Subagent uses PingPong for celebrating; orchestrator uses Loop. The orchestrator's 2-frame celebrating animation alternates vibration + tread roll and must loop continuously, not reverse direction.

StationAgentActor still uses the scale pulse constants.
When removing the scale pulse from OrchestratorActor, do NOT remove SCALE_PULSE_MIN, SCALE_PULSE_MAX, and PULSE_FREQUENCY from constants/animation.ts — StationAgentActor independently imports and uses them.