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

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)