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

Why

packages/ has 41 sibling top-level folders with no semantic grouping, making the repo hard to scan and forcing same-name nested folders like packages/geo/geo, packages/i18n/i18n, packages/r3f/r3f that confuse tooling, IDE navigation, and git mv rename heuristics. The platform/ catch-all and the implicit unknown/ bucket in STATUS.md further dilute the layout. Grouping current plugin folders under 18 stable category folders (per PROPOSED_STRUCTURE.md) gives every package one obvious home and eliminates the duplicate-name nesting.

What Changes

• BREAKING (filesystem only — no public API change): introduce a category level so the layout becomes packages/<category>/<plugin>/<pkg>/, where <category> is one of 18 fixed names: foundation, persistence, network, communication, api, auth, security, monitor, media, react, r3f, i18n, geo, finance, commerce, testing, tooling, games.
• Move all 41 current plugin folders under their assigned category using git mv so history is preserved (no packages_temp swap — that breaks rename detection for some files).
• Eliminate packages/platform/ by splitting its contents into foundation/, api/, communication/, monitor/ per PROPOSED_STRUCTURE.md.
• Update every workspace reference to the old paths: package.json workspaces glob, turbo.json, tsconfig.* paths, vitest/vite configs, scripts/folder-reorg/assignment.yml, MANIFEST.md, STATUS.md, OpenSpec archives that quote paths, CLAUDE.md package-listing snippets, and any internal docs that hard-code packages/<plugin>/.
• Regenerate MANIFEST.md via bun scripts/folder-reorg/generate-manifest.ts after the move and update scripts/folder-reorg/generate-manifest.ts itself if it assumes the 2-level layout.
• Update the CLAUDE.md "Layout" section to document the 3-level packages/<category>/<plugin>/<pkg>/ convention and the canonical 18-category list.
• Verify the move in a single commit on a dedicated branch so reviewers see one atomic rename; no package code or version is touched.

Capabilities

New Capabilities

• monorepo-layout: Canonical 3-level packages/<category>/<plugin>/<pkg>/ filesystem convention, the fixed 18-category vocabulary, the assignment rules (which plugin lives under which category), and the invariants enforced by scripts/folder-reorg/generate-manifest.ts and CI path-shape checks.

Modified Capabilities

Impact

• Filesystem: every package under packages/ moves one level deeper. No file contents change.
• Workspaces: Bun workspaces glob in root package.json widens from packages/*/* to packages/*/*/* (or equivalent). Turbo, Biome, Vitest, Playwright, tsup, Vite configs that hard-code paths must be updated.
• Tooling scripts: scripts/folder-reorg/generate-manifest.ts, scripts/folder-reorg/assignment.yml, scripts/publish.ts, and any lint scripts that walk packages/ need path-depth fixes.
• Docs: CLAUDE.md, MANIFEST.md, STATUS.md, PROPOSED_STRUCTURE.md, and archived OpenSpec changes that quote packages/<plugin>/<pkg>/ paths are updated for the new convention (archived specs only at quoted-path level — content stays frozen).
• No public surface change: @suaveplan/<pkg> import paths, package versions, and exports are untouched.
• Git history: preserved per file via git mv; one squash-friendly commit captures the entire move.
• CI: turbo cache is invalidated once; subsequent builds benefit from stable cache keys under the new paths.