suaveplan/openspec/archive/2026-05-19-split-audio-plugins-fx/tasks.md

# Tasks — Split `audio-plugins-fx` into `audio-fx-plugin-*` per-plugin packages

> Every checkbox MUST reflect work actually done in this change. Strategy: build a real foundation + one canonical plugin, then a scaffold script replicates the per-plugin shape across the remaining 23.

## 1. Spec authoring

- [ ] 1.1 Read `openspec/AGENTS.md` §§ 13, 14, 14a, 2c, 6a, 7, 193
- [ ] 1.2 Read `openspec/specs/audio-core/spec.md` and `openspec/specs/audio-transport/spec.md` for surrounding capability shape
- [ ] 1.3 `proposal.md` (this change) — 25 packages enumerated, `audio-fx-plugin-*` naming
- [ ] 1.4 `specs/audio-plugins-fx/spec.md` — 5 ADDED + 1 REMOVED requirements, each with `**Verified by:**`
- [ ] 1.5 Working-notes checklist of every `### Requirement` and `#### Scenario`

## 2. Phase A — Build `audio-fx-plugin-base`

- [ ] 2.1 `mkdir -p packages/audio-fx/audio-fx-plugin-base/{src,tests}`
- [ ] 2.2 `git mv` every file from `packages/audio/audio-plugins-fx/src/{base,chain,registry}/` into `packages/audio-fx/audio-fx-plugin-base/src/` preserving directory structure
- [ ] 2.3 `git mv` `packages/audio/audio-plugins-fx/src/error-codes.{ts,md,test.ts}` into `packages/audio-fx/audio-fx-plugin-base/src/error-codes/`. Rename to `error-codes/error-codes.{ts,md,test.ts}` so the feature-folder convention holds.
- [ ] 2.4 Author `packages/audio-fx/audio-fx-plugin-base/package.json` — `version: 0.1.0`, `sideEffects: false`, deps `@suaveplan/{audio-core, audio-transport, error, events, opentelemetry, schema-registry, types}` + `tslib` + `zod` (all from catalog/workspace). Zero `@suaveplan/audio-fx-plugin-*` deps. Subpath exports: `.`, `./base`, `./chain`, `./registry`, `./error-codes`. `files: ["dist", "README.md"]`.
- [ ] 2.5 Author `tsconfig.json`, `tsconfig.lib.json`, `vite.config.ts` (multi-entry, `preserveModules: true`), `vitest.config.ts`, `README.md`. Copy from `packages/audio-ir/audio-ir-core/` and adjust names.
- [ ] 2.6 Author root barrel `src/index.ts` — explicit named re-exports (rule 10). Drop every `export *` from sub-barrels in the moved code; convert to named re-exports.
- [ ] 2.7 Rewrite internal imports inside moved files: `from "../base"` → `from "./base"`, etc. (verify with `rg "\.\./" packages/audio-fx/audio-fx-plugin-base/src`)
- [ ] 2.8 Add `tests/dep-graph.test.ts`: reads own `package.json`, asserts zero `@suaveplan/audio-fx-plugin-*` deps (including self).
- [ ] 2.9 Run `bun install && bunx turbo lint typecheck test build --filter=@suaveplan/audio-fx-plugin-base`. Must reach 100/100/100/100.

## 3. Phase B — Build `audio-fx-plugin-eq` as the canonical template

- [ ] 3.1 `mkdir -p packages/audio-fx/audio-fx-plugin-eq/src`
- [ ] 3.2 `git mv packages/audio/audio-plugins-fx/src/plugins/eq/* packages/audio-fx/audio-fx-plugin-eq/src/`
- [ ] 3.3 Author `package.json`, `tsconfig.json`, `tsconfig.lib.json`, `vite.config.ts`, `vitest.config.ts`, `README.md` for `audio-fx-plugin-eq`. Deps: `@suaveplan/audio-fx-plugin-base` (workspace:^) + whatever non-plugin `@suaveplan/*` packages the moved eq code imports (enumerate via `rg "@suaveplan/" packages/audio-fx/audio-fx-plugin-eq/src`).
- [ ] 3.4 Rewrite eq imports: `from "../../base"` → `from "@suaveplan/audio-fx-plugin-base/base"`, `from "../../chain"` → `from "@suaveplan/audio-fx-plugin-base/chain"`, etc.
- [ ] 3.5 Root barrel `src/index.ts` — explicit named re-exports; convert any `export *` to named.
- [ ] 3.6 `bunx turbo lint typecheck test build --filter=@suaveplan/audio-fx-plugin-eq` — green at 100/100/100/100.
- [ ] 3.7 Designate `audio-fx-plugin-eq`'s config files (`package.json`, `tsconfig.*`, `vite.config.ts`, `vitest.config.ts`, `README.md`) as the canonical per-plugin template. Save the rendered versions with `{PLUGIN_NAME}` markers re-introduced as `scripts/split-audio-fx-plugin/template/*.template` for the scaffold script to consume.

## 4. Phase C — Scaffold script + replicate across 23 remaining plugins

- [ ] 4.1 Author `scripts/split-audio-fx-plugin/scaffold.ts` (Bun-runnable TypeScript). Arguments: `--name <slug>` (e.g. `compressor`), `--source-dir <name>` (defaults to `<slug>`; used for the `game/` → `game-audio` rename).
- [ ] 4.2 Script steps:
  1. Validate slug matches `/^[a-z][a-z0-9-]*$/`. Refuse if a folder already exists at `packages/audio-fx/audio-fx-plugin-<slug>/`.
  2. Create `packages/audio-fx/audio-fx-plugin-<slug>/src/`.
  3. Copy every `scripts/split-audio-fx-plugin/template/*.template` to the new package root, replacing `{PLUGIN_NAME}` markers with `<slug>`. Strip the `.template` suffix.
  4. `git mv packages/audio/audio-plugins-fx/src/plugins/<source-dir>/* packages/audio-fx/audio-fx-plugin-<slug>/src/`.
  5. Walk every `.ts` / `.tsx` / `.md` file inside the new `src/` and rewrite relative imports: `../../base` → `@suaveplan/audio-fx-plugin-base/base`, `../../chain` → `@suaveplan/audio-fx-plugin-base/chain`, `../../registry` → `@suaveplan/audio-fx-plugin-base/registry`, `../../error-codes` → `@suaveplan/audio-fx-plugin-base/error-codes`. Also rewrite cross-plugin imports if any (`../<other-plugin>` should not exist; abort with an error if found).
  6. Convert every `export *` in the new package's barrels to explicit named re-exports (read the source's actual exports via a minimal AST walk or fallback to grep + manual fix-list).
  7. Author `src/index.ts` root barrel with explicit named re-exports of the plugin's public surface.
- [ ] 4.3 Run the script for each of the 23 remaining plugins, in alphabetical order: `audio-analyzer`, `audio-player`, `auto-filter`, `chorus`, `compressor`, `delay`, `distortion`, `filter`, `flanger`, `game-audio` (source dir `game`), `gate`, `glados`, `limiter`, `microphone`, `mixer`, `phaser`, `pitch-shifter`, `reverb`, `sampler`, `spatial`, `synthesizer`, `tremolo`, `widener`.
- [ ] 4.4 After every 5 plugins, run `bunx turbo lint typecheck test --filter='@suaveplan/audio-fx-plugin-*'` to catch regressions early.

## 5. Phase D — Repo plumbing

- [ ] 5.1 Delete `packages/audio/audio-plugins-fx/` (`git rm -rf`).
- [ ] 5.2 `rg "@suaveplan/audio-plugins-fx" packages/ apps/ scripts/ docs/ openspec/changes/ openspec/specs/` — zero hits. Hits in `openspec/archive/` are immutable history; ignore.
- [ ] 5.3 Update `scripts/folder-reorg/assignment.yml`: remove `audio-plugins-fx`; add 25 entries mapping every new `audio-fx-plugin-*` package to the `audio` plugin slot.
- [ ] 5.4 Update `CLAUDE.md` § Packages — replace `audio-plugins-fx` listing with `audio-fx-plugin-base` + 24 per-plugin entries (alphabetical).
- [ ] 5.5 Update `STATUS.md` — replace the `@suaveplan/audio-plugins-fx` row with 25 ✅ rows; update `## Counts` (`Migrated` +24).
- [ ] 5.6 `bun scripts/folder-reorg/generate-manifest.ts` — regenerate `MANIFEST.md`.

## 6. Phase E — Final verification (5-gate triple across the family)

- [ ] 6.1 `bun run check` — Biome 0/0/0/0 monorepo-wide
- [ ] 6.2 `bunx turbo lint typecheck test --filter='@suaveplan/audio-fx-plugin-*'` — green across all 25
- [ ] 6.3 `bunx turbo test:coverage --filter='@suaveplan/audio-fx-plugin-*'` — 100/100/100/100 on every package
- [ ] 6.4 `bunx turbo build --filter='@suaveplan/audio-fx-plugin-*'` — green
- [ ] 6.5 `bun scripts/openspec-conformance.ts @suaveplan/audio-fx-plugin-base` and `@suaveplan/audio-fx-plugin-eq` — both PASS
- [ ] 6.6 `bunx turbo build` (whole monorepo) — green; no downstream consumer breakage
- [ ] 6.7 `test ! -d packages/audio/audio-plugins-fx` — exit 0
- [ ] 6.8 `rg "@suaveplan/audio-plugins-fx" packages/ apps/ scripts/ docs/ openspec/changes/ openspec/specs/` — zero hits

## 7. Phase F — 7-row checklist (AGENTS §13)

- [ ] 7.1 Generics threaded; `expectTypeOf` assertions preserved on every literal-type claim
- [ ] 7.2 Zod schemas wired at every declared boundary — preserved by move
- [ ] 7.3 Every error code in each `error-codes.ts` thrown by at least one production path
- [ ] 7.4 Strict-mode behaviors tested both on and off — preserved
- [ ] 7.5 OTel instruments asserted with a real in-memory `MeterProvider` — preserved
- [ ] 7.6 Lifecycle dedup tests preserved (in-flight Promise, idempotent set/load)
- [ ] 7.7 No retroactive tick — every box reflects work done in this change

## 8. Phase G — Archive + commit

> Commit strategy: 3 commits scoped narrowly via explicit `git add <path>` — never `git add -A`.
> Touch ONLY these path families: `packages/audio-fx/audio-fx-plugin-*`, `packages/audio/audio-plugins-fx` (deletion), `scripts/split-audio-fx-plugin/`, `openspec/changes/split-audio-plugins-fx/`, `openspec/archive/2026-05-19-split-audio-plugins-fx/`, `openspec/specs/audio-plugins-fx/`, `STATUS.md`, `CLAUDE.md`, `scripts/folder-reorg/assignment.yml`, `MANIFEST.md`.
> DO NOT touch any file under `packages/react/`, `openspec/changes/add-react-auth-core/`, `openspec/changes/extend-react-ui-runtime-theme-mutation/`, or `bun.lock` — those belong to unrelated in-flight work.

- [ ] 8.1 Commit 1: `feat(audio-fx): extract audio-fx-plugin-base from audio-plugins-fx`. Body: base package shipped; eq shipped as the canonical template; scaffold script committed.
- [ ] 8.2 Commit 2: `feat(audio-fx): split 23 remaining FX plugins into audio-fx-plugin-* packages`. Body: lists every new package; notes the `game/` → `game-audio` rename; references Commit 1.
- [ ] 8.3 Fold spec delta into NEW `openspec/specs/audio-plugins-fx/spec.md`. The 5 ADDED requirements become the body; the REMOVED requirement is appended as a `## Historical: bundled package` note with a pointer to the archive.
- [ ] 8.4 `git mv openspec/changes/split-audio-plugins-fx openspec/archive/2026-05-19-split-audio-plugins-fx`.
- [ ] 8.5 Commit 3: `chore(audio-fx): delete audio-plugins-fx + archive split-audio-plugins-fx + refresh root docs`. Body: cites the deletion of the old folder, the STATUS / CLAUDE / MANIFEST / assignment.yml updates, and the archive move.
- [ ] 8.6 Every commit message ends with the standard trailer:
  ```
  Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
  ```
- [ ] 8.7 DO NOT push.