Initial Commit

openspec/archive/2026-04-25-folder-reorg-by-domain/specs/monorepo-structure/spec.md

@@ -0,0 +1,86 @@
+## ADDED Requirements
+
+### Requirement: Domain-first folder layout
+
+The monorepo SHALL organise packages into domain folders that map 1:1 to plugins in the `suaveplan-skills` marketplace. The layout is `packages/<plugin>/<package>/` where `<plugin>` is the marketplace plugin name without the `suaveplan-` prefix and `<package>` is the npm name without the `@suaveplan/` prefix. Tier (universal / browser / react / r3f / server / python) is NOT a directory — it is determined per-package by `package.json` deps, the `"browser"` field, peer deps, and `engines`.
+
+#### Scenario: Every package lives under a plugin folder
+
+- **WHEN** any package directory is inspected
+- **THEN** its path is `packages/<plugin>/<package>/` AND `<plugin>` matches a plugin defined in the marketplace assignment manifest
+
+#### Scenario: No tier-named top-level folders
+
+- **WHEN** the repository root is listed
+- **THEN** there are no `universal/`, `browser/`, `react/`, `r3f/`, `api/`, `server/`, `finance/`, `mcp/`, `python/`, or `gaming/` directories
+
+#### Scenario: Cross-tier domain co-location
+
+- **WHEN** a domain has packages spanning multiple tiers (e.g. `drive` with universal core, browser P2P plugin, react UI, and api plugin)
+- **THEN** all of those packages live under the same plugin folder (`packages/drive/`)
+
+### Requirement: Plugin → package assignment uniqueness
+
+Every package SHALL appear in exactly one plugin folder. No package may be present in two plugins.
+
+#### Scenario: Assignment manifest has unique entries
+
+- **WHEN** `scripts/folder-reorg/assignment.yml` is parsed
+- **THEN** the union of all packages across all plugins contains no duplicates
+
+### Requirement: Generated MANIFEST.md replaces @suaveplan/overview
+
+The repository SHALL contain a generated `MANIFEST.md` at the root that lists every plugin, every package, the inferred tier per package, the dependency graph, and a tier-overlay view. The manifest is regenerated by `bun scripts/generate-manifest.ts` and a `--check` mode validates that the committed file is up-to-date.
+
+#### Scenario: MANIFEST.md is up to date
+
+- **WHEN** `bun scripts/generate-manifest.ts --check` is run
+- **THEN** it exits with status 0 AND the committed `MANIFEST.md` matches the regenerated output byte-for-byte
+
+#### Scenario: @suaveplan/overview is absent
+
+- **WHEN** the repository is searched for `@suaveplan/overview`
+- **THEN** no `package.json` declares it as a dep AND no source file imports it AND no folder named `overview/` exists under `packages/`
+
+### Requirement: FOLDERS.yml is removed
+
+`FOLDERS.yml` SHALL NOT exist at the repository root. The folder layout is self-describing via the `packages/` tree and the per-tier overlay lives in `MANIFEST.md`.
+
+#### Scenario: FOLDERS.yml absent
+
+- **WHEN** the repository root is listed
+- **THEN** no file named `FOLDERS.yml` is present
+
+### Requirement: Tier inference from package.json
+
+`scripts/generate-manifest.ts` SHALL infer each package's tier deterministically from its `package.json` and source layout, in this priority order: python → r3f → react → browser → server → universal.
+
+- **python**: package directory name has prefix `python-` OR `package.json` has a top-level `"python"` field.
+- **r3f**: `peerDependencies` includes `@react-three/fiber` OR `three`.
+- **react**: `peerDependencies` includes `react` (and tier is not r3f).
+- **browser**: `package.json` has a `"browser"` field OR `engines` lacks `node`.
+- **server**: `bin` field is set OR direct dependencies include `bun:sqlite`, `node:fs`, `node:net`, `node:cluster`, `pg`, `ioredis`, or similar Node-only modules.
+- **universal**: none of the above match.
+
+#### Scenario: Tier inference is deterministic
+
+- **WHEN** `scripts/generate-manifest.ts --check` is run twice without source changes
+- **THEN** both runs produce identical tier classifications for every package
+
+### Requirement: Path references in CLAUDE.md and openspec/AGENTS.md updated
+
+`CLAUDE.md` and `openspec/AGENTS.md` SHALL reference packages via `packages/<plugin>/<pkg>/` paths. References to legacy `universal/<domain>/<pkg>/` or `packages/<tier>/<pkg>/` paths SHALL NOT exist in either file.
+
+#### Scenario: No legacy path references
+
+- **WHEN** `CLAUDE.md` and `openspec/AGENTS.md` are searched for the regex `(^|[^a-z])(universal|browser|react|r3f|server|finance|mcp|python|gaming)/[a-z]`
+- **THEN** zero matches are found in either file
+
+### Requirement: Migration is reversible until merged
+
+The folder migration SHALL execute via `git mv` (preserving file history) in a single commit, allowing `git revert` to restore the legacy layout if a regression is found before merge.
+
+#### Scenario: File history preserved
+
+- **WHEN** `git log --follow packages/<any-plugin>/<any-existing-pkg>/src/<any-file>.ts` is run after migration
+- **THEN** the log shows commits from before the migration (i.e. `git mv` preserved history, not `rm`+`add`)