Initial Commit

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

@@ -0,0 +1,33 @@
+## 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
+
+<!-- None. No package-level capability spec changes behaviour; this is a pure filesystem reorganisation. Per-package specs in openspec/specs/<pkg>/ continue to describe runtime behaviour unchanged. -->
+
+## 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.