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

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
• 0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
• 0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

1. Pre-flight

• 1.1 Create branch chore/restructure-packages-by-category off genesis.
• 1.2 Run git worktree list and confirm every worktree is clean (git status in each). Abort and reconcile if anything is dirty.
• 1.3 Snapshot current MANIFEST.md as MANIFEST.before.md (not committed; used for post-move diff).
• 1.4 Snapshot current bunx turbo ls --json output for the same purpose.
• 1.5 Audit packages/platform/ and decide a target category for every sub-package (record decisions inline in this tasks file under §3).

2. Authoritative assignment file

• 2.1 Update scripts/folder-reorg/assignment.yml so each plugin entry includes a category: field with one of the 18 canonical names: foundation, persistence, network, communication, api, auth, security, monitor, media, react, r3f, i18n, geo, finance, commerce, testing, tooling, games.
• 2.2 Commit the YAML update on the restructure branch before doing any git mv, so the rename commit and the assignment metadata stay in lockstep on review.

3. Decompose packages/platform/

• 3.1 List every sub-package under packages/platform/ (ls packages/platform).
• 3.2 For each, record <pkg> → <category> in this checklist (e.g. webhook-client → communication). Use only the 18 canonical categories.
• 3.3 Confirm no platform sub-package needs to be split across multiple categories. If one does, raise it as an open question on the OpenSpec proposal before proceeding.

4. Move plugin folders with git mv (one commit, one folder at a time)

Run commands from the repo root. Create the category directory just before the first git mv into it.

• 4.1 foundation/: mkdir -p packages/foundation && git mv packages/core packages/foundation/core && git mv packages/data packages/foundation/data && git mv packages/random packages/foundation/random && git mv packages/timing packages/foundation/timing && git mv packages/bitpacker packages/foundation/bitpacker && git mv packages/barcode packages/foundation/barcode && git mv packages/flow packages/foundation/flow.
• 4.2 persistence/: mkdir -p packages/persistence && git mv packages/database packages/persistence/database && git mv packages/storage packages/persistence/storage && git mv packages/cache packages/persistence/cache.
• 4.3 network/: mkdir -p packages/network-cat && git mv packages/network packages/network-cat/network && git mv packages/drive packages/network-cat/drive && git mv packages/events packages/network-cat/events && mv packages/network-cat packages/network (use the temp-name swap only at the category level to avoid colliding with the existing packages/network/ plugin folder; the git mv of the inner network plugin is what Git tracks, the final mv of the empty category folder is content-free).
• 4.4 communication/: mkdir -p packages/communication && git mv packages/messaging packages/communication/messaging && git mv packages/emails packages/communication/emails.
• 4.5 api/: mkdir -p packages/api-cat && git mv packages/api packages/api-cat/api && mv packages/api-cat packages/api (same category/plugin name collision dance as network).
• 4.6 auth/: mkdir -p packages/auth-cat && git mv packages/auth packages/auth-cat/auth && mv packages/auth-cat packages/auth.
• 4.7 security/: mkdir -p packages/security-cat && git mv packages/security packages/security-cat/security && git mv packages/crypto packages/security-cat/crypto && mv packages/security-cat packages/security.
• 4.8 monitor/: mkdir -p packages/monitor-cat && git mv packages/monitor packages/monitor-cat/monitor && mv packages/monitor-cat packages/monitor.
• 4.9 media/: mkdir -p packages/media && git mv packages/audio packages/media/audio && git mv packages/audio-fx packages/media/audio-fx && git mv packages/audio-ir packages/media/audio-ir && git mv packages/image packages/media/image && git mv packages/fonts packages/media/fonts.
• 4.10 react/: mkdir -p packages/react-cat && git mv packages/react packages/react-cat/react && git mv packages/forms packages/react-cat/forms && mv packages/react-cat packages/react.
• 4.11 r3f/: mkdir -p packages/r3f-cat && git mv packages/r3f packages/r3f-cat/r3f && mv packages/r3f-cat packages/r3f.
• 4.12 i18n/: mkdir -p packages/i18n-cat && git mv packages/i18n packages/i18n-cat/i18n && mv packages/i18n-cat packages/i18n.
• 4.13 geo/: mkdir -p packages/geo-cat && git mv packages/geo packages/geo-cat/geo && mv packages/geo-cat packages/geo.
• 4.14 finance/: mkdir -p packages/finance-cat && git mv packages/finance packages/finance-cat/finance && git mv packages/payment packages/finance-cat/payment && mv packages/finance-cat packages/finance.
• 4.15 commerce/: mkdir -p packages/commerce && git mv packages/booking packages/commerce/booking && git mv packages/contacts packages/commerce/contacts.
• 4.16 testing/: mkdir -p packages/testing-cat && git mv packages/testing packages/testing-cat/testing && mv packages/testing-cat packages/testing.
• 4.17 tooling/: mkdir -p packages/tooling-cat && git mv packages/tooling packages/tooling-cat/tooling && git mv packages/docs packages/tooling-cat/docs && git mv packages/docker packages/tooling-cat/docker && mv packages/tooling-cat packages/tooling.
• 4.18 games/: mkdir -p packages/games-cat && git mv packages/games packages/games-cat/games && mv packages/games-cat packages/games.
• 4.19 Decompose packages/platform/ per §3 decisions: one git mv packages/platform/<pkg> packages/<category>/<plugin>/<pkg> per sub-package (or to its parent plugin folder if it belongs there). Remove the now-empty packages/platform/ directory with rmdir packages/platform.
• 4.20 Verify: find packages -mindepth 1 -maxdepth 1 -type d | sort returns exactly the 18 canonical category names and nothing else.
• 4.21 Verify: find packages -mindepth 3 -maxdepth 3 -name package.json | wc -l equals the count of @suaveplan/* packages from the pre-flight snapshot.

5. Update workspace and tooling configuration

• 5.1 Root package.json: change workspaces from ["packages/*/*"] (or whatever the current glob is) to ["packages/*/*/*"]. Verify no other glob is needed.
• 5.2 Root turbo.json: scan for any hard-coded packages/<plugin>/... paths and update to three-level.
• 5.3 Root tsconfig*.json: update any paths mappings that reference packages/<plugin>/<pkg> to packages/<category>/<plugin>/<pkg>.
• 5.4 scripts/folder-reorg/generate-manifest.ts: update path-walking logic to assume three levels under packages/; load category list from the YAML constant.
• 5.5 scripts/publish.ts: update any path-resolution code that walks packages/.
• 5.6 scripts/lint/check-test-runner-imports.ts: update its packages/<plugin>/<pkg> glob to three levels.
• 5.7 Per-package configs: rg -n "packages/[a-z][a-z0-9-]+/[a-z][a-z0-9-]+(/|['\")\\\\])" --type-add 'cfg:*.{json,ts,js,mjs,cjs,yml,yaml,toml}' -tcfg and audit every hit. Update each to the three-level form (or to a category-agnostic resolution if better).
• 5.8 biome.json (and any per-package biome.json): update path globs.
• 5.9 playwright.config.* (root and per-package): update path globs.

6. Add path-shape CI gate

• 6.1 Create scripts/lint/check-package-paths.ts that walks packages/, asserts every package.json is at depth 3 segments under packages/, and asserts the category segment is in the canonical 18-name list (loaded from scripts/folder-reorg/assignment.yml).
• 6.2 Add it to the root lint script and to turbo.json lint task pipeline.
• 6.3 Run it locally; confirm it exits zero.

7. Regenerate manifest

• 7.1 Run bun scripts/folder-reorg/generate-manifest.ts.
• 7.2 Diff the new MANIFEST.md against MANIFEST.before.md: only path strings and the new category column should differ. No package additions, removals, or version changes.
• 7.3 Stage MANIFEST.md.

8. Documentation updates

• 8.1 CLAUDE.md "Layout (packages/<plugin>/<pkg>/)" section: rewrite the heading to Layout (packages/<category>/<plugin>/<pkg>/), document the 18-category vocabulary, and reference scripts/folder-reorg/assignment.yml as the source of truth.
• 8.2 STATUS.md: replace the implicit unknown/ bucket with category headers; reflect the new paths.
• 8.3 PROPOSED_STRUCTURE.md: add a one-line note at the top — Status: adopted via openspec/changes/restructure-packages-by-category — and leave the rationale intact for historical context.
• 8.4 Spot-check root-level README.md for packages/<plugin> references; update.
• 8.5 Do NOT modify any file under openspec/archive/ even if it quotes old paths.

9. Verification gate

• 9.1 bun install at repo root succeeds with no workspace package not found errors.
• 9.2 bunx turbo ls lists the same package count as the pre-flight snapshot.
• 9.3 bunx turbo lint typecheck green across the whole monorepo.
• 9.4 bunx turbo test green across the whole monorepo (allow expected DB-integration skips per CLAUDE.md).
• 9.5 bun scripts/lint/check-package-paths.ts exits zero.
• 9.6 git log --follow packages/foundation/core/error/src/error.ts (or another sample file) shows pre-restructure history.
• 9.7 git show --stat HEAD of the restructure commit shows only renames, zero content edits.

10. Commit and ship

• 10.1 Squash all step-4/5/6/7/8 work into one commit: chore(repo): restructure packages under 18 categories
• 10.2 Push branch; confirm CI green.
• 10.3 Open PR to genesis with the proposal, design, and tasks linked from the description.
• 10.4 After merge, fold the spec delta into openspec/specs/monorepo-layout/spec.md and archive openspec/changes/restructure-packages-by-category/ to openspec/archive/<yyyy-mm-dd>-restructure-packages-by-category/.