suaveplan/openspec/changes/restructure-packages-by-category/design.md

Context

packages/ currently holds 41 sibling folders at depth 2 (packages/<plugin>/<pkg>/). Three plugins (geo, i18n, r3f) collide with same-named packages they contain, producing packages/geo/geo/, packages/i18n/i18n/, packages/r3f/r3f/. A 4th catch-all (platform/) groups unrelated packages, and STATUS.md admits an implicit unknown/ bucket. The user wrote PROPOSED_STRUCTURE.md with 18 stable category names; this design turns that into an executable migration.

The user's first-draft mechanic was a packages_temp/ swap. That breaks Git rename detection for files whose containing directory is recreated mid-operation. git mv per plugin folder is strictly better — same end-state, full rename detection, single atomic commit.

Constraints: no public surface change, no version bump, no code edits in the rename commit, genesis branch only.

Goals / Non-Goals

Goals:

• One canonical home for every package, enforceable by a CI gate.
• Eliminate same-name nesting (geo/geo etc.) and the platform/ catch-all.
• Preserve git log --follow history across the move.
• Update every workspace-glob, turbo, vitest, tsup, biome, and script reference in lockstep so bun install && bunx turbo build works immediately after the commit.
• Refresh MANIFEST.md, CLAUDE.md, STATUS.md, assignment.yml to describe the 3-level layout.

Non-Goals:

• Renaming any @suaveplan/<pkg> import path. Only filesystem paths change.
• Splitting or merging packages. Code is byte-identical post-move.
• Touching archived OpenSpec changes' content (paths quoted inside archives stay frozen).
• Adopting forward-looking categories for packages that do not yet exist (e.g. video, store, logistics, gtap, vatdash named in PROPOSED_STRUCTURE.md); those land when those packages land.
• Bumping any package version.

Decisions

1. Three-level layout: packages/<category>/<plugin>/<pkg>/

Chosen: keep the existing <plugin>/<pkg>/ pair and add <category>/ above it.

Alternatives:

• Drop the plugin level (packages/<category>/<pkg>/): cleaner tree but loses the suaveplan-skills plugin grouping that assignment.yml depends on, and forces a flat list of ~270 package folders inside large categories like react/ and games/.
• Flatten same-name pairs (hoist geo/geo/ → geo/): solves nesting but creates an inconsistent depth (some packages at 2 levels, others at 3) that breaks every workspace glob.

Three-level is the only option that keeps glob-depth uniform AND preserves the plugin grouping.

2. git mv per plugin folder, one commit

Chosen: for each of the 41 plugin folders, run git mv packages/<plugin> packages/<category>/<plugin> (creating the category directory first). Squash into a single rename commit.

Alternatives:

• packages_temp/ swap (user's draft): breaks rename detection on files whose directory is recreated; reviewers see add+delete, not rename. Rejected.
• Script-driven from assignment.yml: still uses git mv internally, but the script becomes a single point of failure. We do the moves by hand from a checklist for auditability; the script lives in tasks.md as a documented helper.

3. Path-shape CI gate

Chosen: add a small script (scripts/lint/check-package-paths.ts) that walks packages/, asserts every package.json is at depth 3 (category/plugin/pkg), and asserts the category segment is in the canonical 18-name list. Wire it into turbo lint.

Alternatives:

• Enforce only via package.json workspaces glob: Bun silently ignores unmatched folders, so a stray two-level package becomes invisible rather than an error. Rejected.
• No gate: relies on convention drift; the original two-level layout is itself evidence that convention without enforcement decays.

4. Canonical 18-category list from PROPOSED_STRUCTURE.md

Chosen: adopt the 18 categories as the closed vocabulary. assignment.yml maps every current plugin to exactly one. Adding a 19th requires a new OpenSpec change that modifies the monorepo-layout spec.

Alternatives:

• Open vocabulary: invites the same drift that produced platform/ and unknown/. Rejected.

5. Plugin-to-category assignments (binding)

From PROPOSED_STRUCTURE.md, the 41 existing plugin folders map as follows:

Category	Plugin folders moving in
foundation/	core, data, random, timing, bitpacker, barcode, flow
persistence/	database, storage, cache
network/	network, drive, events
communication/	messaging, emails
api/	api
auth/	auth
security/	security, crypto
monitor/	monitor
media/	audio, audio-fx, audio-ir, image, fonts
react/	react, forms
r3f/	r3f
i18n/	i18n
geo/	geo
finance/	finance, payment
commerce/	booking, contacts
testing/	testing
tooling/	tooling, docs, docker
games/	games

The platform/ plugin folder is split: its contents are inspected and each child plugin moves to the category that fits (most candidates: foundation/, api/, communication/, monitor/). The exact per-package decomposition is in tasks.md step 3.

6. Workspace-glob change

Chosen: root package.json workspaces glob becomes ["packages/*/*/*"] (single line). No transitional dual-glob.

Alternatives:

• Dual glob (packages/*/* + packages/*/*/*) during transition: encourages partial migrations and delays the path-shape gate. Rejected — we move everything in one commit, no transition window.

Risks / Trade-offs

• Risk: turbo cache misses for the whole repo on the first build after the move. Mitigation: acceptable one-time cost; cache rebuilds in one bunx turbo build run. Run it locally before pushing.
• Risk: a hard-coded packages/<plugin>/<pkg> path is missed in a vitest config, tsup config, or doc snippet, breaking that package's gate. Mitigation: tasks.md includes a rg -n 'packages/[a-z][a-z0-9-]+/[a-z][a-z0-9-]+' sweep across the repo to find every literal occurrence before commit, plus a green bunx turbo lint typecheck test gate post-move.
• Risk: archived OpenSpec changes quote old paths; rewriting them violates the archive's frozen-content rule. Mitigation: archives are explicitly out of scope; readers see the old paths in archived deltas and the new paths in current docs. CLAUDE.md notes this.
• Risk: IDEs and find shortcuts that assume 2-level depth break for users. Mitigation: announce the change in the commit message; the path-shape CI gate makes the new convention discoverable.
• Trade-off: small categories (auth/, monitor/, i18n/, geo/, r3f/, testing/, games/) each hold a single plugin folder. Accepted because uniform depth beats variable depth — every glob, every script, every readme can assume 3 levels.
• Trade-off: git mv 41 folders is mechanical and tedious. Acceptable for a one-shot reorg; tasks.md lists every command verbatim.

Migration Plan

1. Branch: chore/restructure-packages-by-category off genesis.
2. Pre-flight: clean working tree in every worktree (git worktree list); turbo cache cleared; MANIFEST.md snapshot saved for post-move diff.
3. Move: run the 41 git mv commands from tasks.md step 4 in order. Create each packages/<category>/ directory just before the first git mv into it.
4. Decompose platform/: per-package, choose target category, git mv. Remove the empty platform/ directory.
5. Update configs: root package.json workspaces glob; turbo.json; any tsconfig*.json paths; scripts/folder-reorg/generate-manifest.ts; scripts/folder-reorg/assignment.yml; scripts/publish.ts; scripts/lint/check-test-runner-imports.ts; any vitest.config.* / vite.config.* / tsup.config.* that hard-codes packages/.
6. Add path-shape gate: create scripts/lint/check-package-paths.ts and wire it into the root lint script.
7. Regenerate manifest: bun scripts/folder-reorg/generate-manifest.ts. Diff against the pre-move snapshot — only path columns and the category column should change.
8. Update docs: CLAUDE.md Layout section, STATUS.md, PROPOSED_STRUCTURE.md (mark as adopted).
9. Verify: bun install && bunx turbo lint typecheck test green end-to-end. git log --follow spot-check on three packages (one from geo/, one from core/, one from the old platform/).
10. Commit: single squash commit titled chore(repo): restructure packages under 18 categories.
11. Rollback: if step 9 fails, git reset --hard origin/genesis (with explicit user approval — see CLAUDE.md git-safety rules). No partial restructure is shipped.

Open Questions

• Q1: Does the platform/ decomposition need its own follow-up OpenSpec change? Tentative answer: no — its packages are catalogued in tasks.md step 3 and the per-package category assignment is mechanical given the 18-category vocabulary. Promote to a follow-up only if any platform sub-package's category is genuinely contested.
• Q2: Do we add a packages/<category>/README.md per category? Tentative answer: no for now (CLAUDE.md rule: one README at package root only). Revisit if scanning a category's plugins becomes painful.
• Q3: Do we re-fold archived OpenSpec changes' quoted paths? Tentative answer: no — archives stay frozen; that is the whole point of the archive.