# VibeScope Master Plan — Multi-Agent Execution Map

> Companion to `00-MASTER-PLAN.md`. Operationalises the 12 tracks into a
> concrete agent-team plan with producer-vs-verifier separation.

---

## 1. Agent Team Composition

| Agent | Role | Specialty | Sessions to spawn |
|---|---|---|---|
| **Mavis (root)** | Owner / conductor | Decision-making, drift-checks, cross-track coordination | (this session — `413419604156710`) |
| **Helper Mavis** | Pact-alignment + verifier | Drift-check, integration tests, cross-thread regressions | `412100071272671` (existing) |
| **Producer A** | TS / state specialist | VSILStore, Scrubber, evaluator wiring | `pA` (spawn per phase) |
| **Producer B** | Graphics engineer | Canvas + pointer events + paint subsystems | `pB` (spawn per phase) |
| **Producer C** | React engineer | LayerPanel, Properties two-way binding | `pC` (spawn per phase) |
| **Producer D** | Animation specialist | Mask + Animation engines, keyframe ops | `pD` (spawn for Phase 6 only) |
| **Producer E** | Dev-tools engineer | Monaco, DevLayout, OAuth removal | `pE` (spawn for Phase 8) |
| **Producer F** | WebGL/Node engineer | WebGL2 shaders, Render CLI | `pF` (spawn for Phase 9) |
| **Producer G** | Verifier / QA | Drift-check, integration tests, performance gates | `pG` (always-on, co-resident with Helper Mavis) |

**Co-located agent dispatch**: `communicate` tool from Mavis (root) to Helper Mavis (existing) for pact-alignment + drift-check; `mavis session create` for new producers as needed.

---

## 2. Per-Phase Dispatch

### Phase 1 — Foundation Lock

| Step | Agent | Action |
|---|---|---|
| 1.1 | Mavis | Re-run drift-check baseline; confirm 32/0 PASS |
| 1.2 | Helper Mavis | Re-confirm pact files specialised; report any drift |
| 1.3 | Mavis | Sign off Phase 1; commit a `phase-1-foundation-lock` marker if any work was done |

**Outcome**: Drift baseline sealed. No code changes expected.

---

### Phase 2 — Editor Store

| Step | Agent | Action |
|---|---|---|
| 2.1 | Producer A | Implement `VSILStore.ts` + `vsilOps.ts` |
| 2.2 | Producer A | Wire 6 cards to read from VSILStore instead of mock imports |
| 2.3 | Producer A | Self-tests: `vsilOps.test.ts` (50+ cases) |
| 2.4 | Helper Mavis | Verify drift-check 32/0 + integration test (3-substrate CardMount parity) |
| 2.5 | Mavis | Sign off Phase 2; merge commit |

**Branch**: `phase-2-editor-store` (cut from main; merge when verifier green)

---

### Phase 3 — Scrubber + Evaluator

| Step | Agent | Action |
|---|---|---|
| 3.1 | Producer A | Implement `ScrubberContext.tsx` |
| 3.2 | Producer A | Refactor 6 cards to consume `useScrubber` instead of `useState<number>` |
| 3.3 | Producer A | Implement `CinemaProcedural.eval.ts` variant |
| 3.4 | Producer A | Self-tests: `scrubber-evaluator-integration.test.tsx` |
| 3.5 | Helper Mavis | Verify drift-check 32/0 + lint rule blocking local time state in cards |
| 3.6 | Mavis | Sign off Phase 3; merge commit |

**Branch**: `phase-3-scrubber-evaluator`

---

### Phase 4 — Paint Surface + Brush + Transform + Selection

**Parallel dispatch**: T4, T5, T6 run concurrently.

| Step | Agent | Action |
|---|---|---|
| 4.1a | Producer B (T4) | Implement `BrushEngine.ts` + `PaintSurface.tsx` |
| 4.1b | Producer B (T5) | Implement `TransformEngine.ts` |
| 4.1c | Producer B (T6) | Implement `SelectionEngine.ts` + `HitTest.ts` |
| 4.2 | Producer B | VisualCard refactor to use `<PaintSurface>` |
| 4.3 | Producer B | SelectionStore + integration with vsilOps |
| 4.4 | Producer B | Self-tests: brush (20+), transform (20+), selection (15+), hit-test |
| 4.5 | Producer G (perf) | Performance gate: 60fps paint with 50 layers, <16ms/frame |
| 4.6 | Helper Mavis | Drift-check 32/0 + integration tests |
| 4.7 | Mavis | Sign off Phase 4; merge commit |

**Branch**: `phase-4-paint-surface` (3 producer commits + 1 verifier + 1 merge)

**Risk concentration**: Canvas performance. Helper Mavis's verifier must enforce the 16ms budget test. If fails, do NOT advance.

---

### Phase 5 — Layer Panel

| Step | Agent | Action |
|---|---|---|
| 5.1 | Producer C | Implement `LayerPanel.tsx` + `LayerRow.tsx` |
| 5.2 | Producer C | Implement `layerOps.ts` |
| 5.3 | Producer C | Wire LayerPanel into CinemaLayout's Structure cell |
| 5.4 | Producer C | Inspector AST mode rewires to read from VSILStore |
| 5.5 | Producer C | Self-tests: `layerOps.test.ts`, `LayerPanel.test.tsx` |
| 5.6 | Helper Mavis | Drift-check + integration |
| 5.7 | Mavis | Sign off Phase 5; merge |

**Branch**: `phase-5-layer-panel`

---

### Phase 6 — Mask + Animation

**Parallel dispatch**: T8a (Mask) + T8b (Animation).

| Step | Agent | Action |
|---|---|---|
| 6.1a | Producer D (T8a) | Implement `MaskEngine.ts` |
| 6.1b | Producer D (T8b) | Implement `AnimationEngine.ts` + `animationOps.ts` (float + vec2 tracks) |
| 6.2 | Producer D | KeyframeRow component for Timeline |
| 6.3 | Producer D | TimelineCard refactor for draggable keyframes |
| 6.4 | Producer D | VisualCard mask mode toggle |
| 6.5 | Producer D | Self-tests: mask (15+), animation (15+), animationOps (50+) |
| 6.6 | Producer G (perf) | Performance gate: 60fps scrub with 4 animated layers |
| 6.7 | Helper Mavis | Drift-check + integration |
| 6.8 | Mavis | Sign off Phase 6; merge |

**Branch**: `phase-6-mask-animation`

---

### Phase 7 — Properties Two-Way

| Step | Agent | Action |
|---|---|---|
| 7.1 | Producer C | Implement `propertyBindings.ts` |
| 7.2 | Producer C | PropsMode refactor: controlled inputs bound to `vsilOps` |
| 7.3 | Producer C | Multi-selection handling for common properties |
| 7.4 | Producer C | Undo/redo wired to `mutationLog` |
| 7.5 | Producer C | Self-tests: `props-two-way.test.tsx` (20+ cases) |
| 7.6 | Producer G | Snapshot test: AST mode never emits write op |
| 7.7 | Helper Mavis | Drift-check + Inspector read-only invariant audit |
| 7.8 | Mavis | Sign off Phase 7; merge |

**Branch**: `phase-7-properties-twoway`

---

### Phase 8 — Cinema + Dev + Monaco

| Step | Agent | Action |
|---|---|---|
| 8.1 | Producer E | Implement `DesignerCard.tsx` (Monaco + VSIL JSON syntax) |
| 8.2 | Producer E | Implement `DataCard.tsx` + `LogsCard.tsx` (real state + engine telemetry) |
| 8.3 | Producer E | Implement `useMonacoVSIL.ts` |
| 8.4 | Producer E | CinemaLayout refactor: PaintSurface + Properties + LayerPanel + TimelineCard |
| 8.5 | Producer E | DevLayout refactor: DesignerCard + DataCard + LogsCard + InspectorCard AST |
| 8.6 | Producer E | Footer-level layout switcher in CentreStage |
| 8.7 | Producer E | DevLayoutGate: remove `FUTURE-OAUTH-INTEGRATION` marker (replace with `OAUTH-DEFERRED-VS-2026Q3` if real OAuth not yet built) |
| 8.8 | Producer E | Self-tests: CinemaLayout (5+), DevLayout (5+), DesignerCard (10+) |
| 8.9 | Helper Mavis | Drift-check + visual regression snapshots for both layouts |
| 8.10 | Mavis | Sign off Phase 8; merge |

**Branch**: `phase-8-cinema-dev-monaco`

---

### Phase 9 — WebGL2 + Render CLI + Docs

| Step | Agent | Action |
|---|---|---|
| 9.1 | Producer F | Implement `CinemaUltra.webgl.ts` (real vertex + fragment shaders) |
| 9.2 | Producer F | CinemaUltra.tsx refactor: WebGL2 path uses shader; procedural still falls back honestly |
| 9.3 | Producer F | Implement `renderCli.ts` (CLI driver for batch SVG output) |
| 9.4 | Producer F | Implement remaining 5 track kinds in animationOps (vec3/colour/path/string/discrete) |
| 9.5 | Producer F | Write `pact/workspaces/vibescope/editor-getting-started.md` |
| 9.6 | Producer F | Update `studio/modules/vibescope/README.md` |
| 9.7 | Producer F | Self-tests: ultra-webgl (5+), render-cli (5+), animationOps per-kind (5+ × 5 = 25+) |
| 9.8 | Helper Mavis | Final drift-check seal; produce sign-off report |
| 9.9 | Mavis | Sign off Phase 9 → DONE |

**Branch**: `phase-9-webgl-cli-docs`

---

## 3. Verifier Cadence (always-on)

| Check | When | Owner | Threshold |
|---|---|---|---|
| `pact/scripts/audit-chip-system-v3.3.x.sh` | After every commit | Helper Mavis | 32/0 PASS |
| `studio/ npm test` | After every commit | Producer G | 0 failures |
| Visual snapshot: 3-substrate CardMount parity | After Phase 2, 4, 8 | Helper Mavis | identical to Phase 1 baseline |
| Visual snapshot: Cinema layout | After Phase 5, 8 | Helper Mavis | new golden file |
| Visual snapshot: Dev layout | After Phase 8 | Helper Mavis | new golden file |
| Performance gate: 60fps paint with 50 layers | After Phase 4 | Producer G | <16ms/frame (procedural); <33ms (Ultra) |
| Performance gate: 60fps scrub with 4 animated layers | After Phase 6 | Producer G | <16ms/frame |
| Bundle size: VibeScope route | After Phase 8 | Producer G | <1.5MB (Monaco dynamic-imported) |
| Integration test: data-card-mount parity | After every CardMount change | Helper Mavis | unchanged from baseline |
| Stub marker scan | After every commit | Producer G | 0 STUB: in shipped code |

---

## 4. Decision Points (owner-only)

Mavis (root) decides at each phase boundary:

| Decision | Input | Options |
|---|---|---|
| Phase N → Phase N+1? | Helper Mavis verifier report + Producer G performance report | GO / RETRY (with specifics) / PARK |
| Branch merge? | Helper Mavis drift-check + integration test | MERGE / HOLD (with blocker list) |
| Performance gate fail? | Producer G performance report | ACCEPT (with documented regression) / REJECT (force producer fix) |
| Stub marker introduced? | Producer G scan report | REJECT (force producer fix before merge) |

---

## 5. Cross-Thread Coordination

- **Helper Mavis (`412100071272671`)**: Pact-alignment track root. Owns drift-check + integration tests + visual regression. Sign-off authority for every phase gate.
- **FreshCards thread (`404981936394548`)**: Notify when Phase 4 changes PaintSurface APIs (no shared code, but visual parity).
- **Oscar AI (`413171774529758`)**: No impact.
- **Oscar Website (`415655444668635`)**: No impact.
- **FreshVibe Coder (`417228937957532`)**: No impact (different module).

---

## 6. Failure Modes + Recovery

| Failure | Recovery |
|---|---|
| Producer commit breaks drift-check | Helper Mavis reports specific rule violation; Producer A/B/C/D/E/F fixes in 1 cycle |
| Performance gate fails | Producer G retries with profiler data; if unfixable in 1 cycle, scope cut (e.g., "reduce animated layer count for Phase 6 demo") |
| Monaco bundle > 1.5MB | Producer E adjusts dynamic-import path; if still > 1.5MB, defer Monaco to Phase 10 |
| Cross-track contract breach (e.g., T4 changes store shape T7 depends on) | Mavis (root) arbitrates; T12 verifier catches on next drift-check |
| Verifier disagreement | Mavis (root) decides; if persists, escalate to operator |

---

## END OF AGENT EXECUTION MAP