composer-studio.git · PLAN.md

revision 27f1002eea8d37b5b64486388ac8796a22f8b80c · complete file

# Composer Studio — Implementation Plan & Definition of Done

This plan tracks implementation of the Composer Studio agent and app inside the FountainKit workspace. It complements the AGENTS documents, which describe the target design. When reality diverges from this plan, update both the milestones here and the relevant `AGENTS.md` sections.

## High‑level goals

- Provide a two‑pane score + screenplay surface in FountainApps, backed by instruments (Score, Script, CuePlanner, Chat).
- Expose composer‑specific HTTP surfaces via OpenAPI and Swift OpenAPI Generator (`composer-score`, `composer-script`, `composer-cues`).
- Make `fountain.coach/agent/composer-studio/service` a first‑class agent in the control plane (bootstrap, gateway, planner, function‑caller, awareness, tools‑factory).
- Validate behaviour with service tests and MRTS/UI tests driven via MIDI 2.0 PE, spec‑first and prompt‑first.

## Milestones and DoD

### M1 — Specs stubbed and lint‑clean

**Scope**
- Add initial OpenAPI specs in FountainSpecCuration:
- `v1/composer-score.yml`
- `v1/composer-script.yml`
- `v1/composer-cues.yml`
- Register them in the OpenAPI README index.

**Definition of Done**
- Specs exist under `Packages/FountainSpecCuration/openapi/v1/`.
- `Scripts/openapi/openapi-lint.sh` passes for all three composer specs.
- `Packages/FountainSpecCuration/openapi/README.md` lists all three services.

**Status**
- DONE: stubs added and indexed; lint wiring still to be validated in CI.

### M2 — Service cores and handlers

**Scope**
- Add core library targets and (optionally) thin servers in FountainApps:
- `composer-score-service` (+ `*-server`).
- `composer-script-service` (+ `*-server`).
- `composer-cues-service` (+ `*-server`).
- Wire each core to its spec via `openapi.yaml` symlink and `openapi-generator-config.yaml`.
- Implement minimal handlers for the operations described in `services/AGENTS.md`, backed by FountainStore.

**Definition of Done**
- `swift build --package-path Packages/FountainApps` succeeds with composer targets enabled.
- Each composer service has at least one focused test target (e.g. `ComposerScoreServiceTests`) with basic CRUD flows covered.
- No generated Swift is committed; all handlers live in the core/server targets.

**Status**
- IN PROGRESS: composer service core targets exist (`composer-score-service`, `composer-script-service`, `composer-cues-service`) with minimal in‑memory handlers and tests. Full Store‑backed persistence and CI coverage are still pending.

### M3 — Agent‑facts and tool wiring

**Scope**
- Extend the OpenAPI→facts tooling so Tools Factory knows about composer specs.
- Generate agent‑facts for `fountain.coach/agent/composer-studio/service` from:
- `composer-score.yml`
- `composer-script.yml`
- `composer-cues.yml`
- existing awareness, planner, function‑caller, tools‑factory specs.

**Definition of Done**
- `Scripts/openapi/openapi-to-facts.sh` (or equivalent) can produce agent‑facts for composer‑studio.
- `agents` corpus in FountainStore contains a document describing composer‑studio tools and PE mappings.
- CI `openapi-facts-*` jobs include composer specs and remain green.

**Status**
- TODO: openapi‑to‑facts tooling is not yet aware of the composer specs or agent id.

### M4 — Agent profile and gateway endpoint

**Scope**
- Teach bootstrap about `fountain.coach/agent/composer-studio/service`:
- Load Teatro prompt and facts from `prompt:composer-studio` in corpus `composer-studio`.
- Incorporate composer tools from agent‑facts into the agent profile.
- Configure gateway to expose:
- `POST /agents/composer-studio/chat` using the composer‑studio profile.

**Definition of Done**
- A local gateway instance can handle `POST /agents/composer-studio/chat` and route calls through planner + function‑caller using composer tools.
- Basic smoke test: a minimal composer agent can echo back or log a plan without crashing, given instrument context.

**Status**
- TODO: no bootstrap/gateway wiring exists yet for composer‑studio; only design docs and specs.

### M5 — App surface and instrument bindings

**Scope**
- Evolve the `composer-studio` executable target in FountainApps to match the UI and instruments in this repo:
- Left panel: ScoreInstrument view.
- Right panel: ScriptInstrument view.
- Cue planner and chat panes.
- Bind instrument state to the composer services:
- Score pane → `composer-score` operations.
- Script pane → `composer-script` operations.
- Cue planner → `composer-cues` operations.
- Chat pane sends and receives messages via gateway’s `/agents/composer-studio/chat`.

**Definition of Done**
- `swift run --package-path Packages/FountainApps composer-studio` launches a macOS app with the two‑pane baseline layout.
- Editing script/score state in the UI results in consistent updates to FountainStore via the composer services.
- Chat sends instrument context to the agent endpoint and displays replies (even if the reasoning is still simple).

**Status**
- TODO: the current composer‑studio target is a design stub; no full binding to services or agent exists yet.

### M6 — MRTS and TDD integration

**Scope**
- Define an MRTS prompt and facts for Composer Studio in FountainStore:
- Page: `prompt:composer-studio` (segments `teatro.prompt` and `facts`).
- Add UI and robot tests in FountainApps:
- `ComposerStudioUITests` (patterned after Baseline‑PatchBay MRTS tests).
- Extend scripts/CI to run composer‑studio tests where appropriate.

**Definition of Done**
- Composer Studio has at least one MRTS test that drives the app via MIDI 2.0 PE and asserts numeric invariants (page/scene alignment, cue focus synchronisation, zoom stability).
- All new composer service and app tests are green in CI.
- `testing/AGENTS.md` remains accurate and references the actual test target names and commands.

**Status**
- TODO: testing is fully design‑only; no concrete tests or prompts exist yet for composer‑studio.

## Gap tracking\n+

Use this section as a quick checklist when starting a new implementation session:\n+
\n+
- [x] M1 specs exist and are indexed.\n+
- [ ] M1 specs linted and validated in CI.\n+
- [x] M2 composer service targets created and wired to specs.\n+
- [x] M2 service tests added and passing (local `swift test --filter Composer*ServiceTests`).\n+
- [ ] M3 Tools Factory updated for composer specs; agent‑facts seeded.\n+
- [ ] M4 bootstrap/gateway profile for composer‑studio.\n+
- [ ] M5 app target wired to services and agent endpoint.\n+
- [ ] M6 MRTS + TDD cycle in place.\n+
\n+
When any item flips from unchecked to checked, update both this file and the relevant `AGENTS.md` description.\n+