@codedrifters/configulator 0.0.239 → 0.0.240

package/lib/index.mjs

@@ -767,6 +767,91 @@ var baseBundle = {
       ].join("\n"),
       tags: ["workflow"]
     },
+    {
+      name: "monorepo-layout",
+      description: "Canonical monorepo top-level folders (docs, apps, packages, sites), the @ownerscope/<name> scoping rule, the docs-singleton carve-out, and the scaffolding skills that place new sub-projects",
+      scope: AGENT_RULE_SCOPE.ALWAYS,
+      content: [
+        "# Monorepo Layout",
+        "",
+        "Every monorepo built with `@codedrifters/configulator` uses a single,",
+        "fixed top-level folder layout. Agents, scaffolding skills, pnpm-workspace",
+        "globs, Turbo filters, and CI cache keys all assume these roots.",
+        "",
+        "## Four Canonical Top-Level Folders",
+        "",
+        "| Folder | Purpose | Examples |",
+        "|--------|---------|----------|",
+        "| `/docs` | **Single** Starlight site covering the entire monorepo. The one site that lives outside `/sites`. | Monorepo-wide developer docs, ADRs, how-to guides. |",
+        "| `/apps/@scope/<name>` | Deployable applications \u2014 anything that runs or ships as a running process. | AWS CDK stacks, mobile apps (iOS/Android), backend services. |",
+        "| `/packages/@scope/<name>` | Shared libraries \u2014 published npm packages and workspace-internal libraries. | `@codedrifters/configulator`, `@codedrifters/constructs`, `@codedrifters/utils`. |",
+        "| `/sites/@scope/<name>` | User-facing web front ends that are **not** the monorepo-wide docs site. | Marketing sites, SPAs, per-client static sites. |",
+        "",
+        "No other top-level folder is part of this contract. Generated roots",
+        "(`.projen/`, `.github/`, `node_modules/`, `.turbo/`, etc.) are orthogonal",
+        "and unchanged.",
+        "",
+        "## Scoping Rule",
+        "",
+        "Every sub-project under `apps/`, `packages/`, or `sites/` is named",
+        "`@ownerscope/<name>`, where **scope is the owning party** (not a category).",
+        "",
+        "- `@codedrifters/configulator` \u2014 a shared library owned by CodeDrifters \u2192 `packages/@codedrifters/configulator`",
+        "- `@codedrifters/infrastructure-stack` \u2014 an AWS CDK app owned by CodeDrifters \u2192 `apps/@codedrifters/infrastructure-stack`",
+        "- `@clientA/iphone-app` \u2014 a mobile app owned by Client A \u2192 `apps/@clientA/iphone-app`",
+        "- `@clientB/marketing-site` \u2014 a marketing site owned by Client B \u2192 `sites/@clientB/marketing-site`",
+        "",
+        "The scope identifies **who owns the sub-project**, not what kind of",
+        "sub-project it is. Kind is captured by the top-level folder (`apps/`,",
+        "`packages/`, `sites/`). Never scope by category (e.g. `@apps/foo`,",
+        "`@libs/bar`) \u2014 the top-level folder already carries that information.",
+        "",
+        "## Docs-Singleton Carve-Out",
+        "",
+        "There is **exactly one** Starlight docs site per monorepo, and it lives",
+        "at `/docs`. It is **not** `sites/@scope/docs`.",
+        "",
+        "- The docs site is monorepo-wide. Sub-project documentation belongs",
+        "  inside that single site (under `docs/content/`), not in a per-package",
+        "  `docs/` folder.",
+        "- Configulator's `StarlightProject` defaults its `outdir` to `/docs`.",
+        "- `/sites` is reserved for end-user-facing web front ends (marketing",
+        "  sites, SPAs, client-facing apps). It deliberately does not host the",
+        "  dev-docs site.",
+        "",
+        "## Project-Type \u2192 `outdir` Mapping",
+        "",
+        "Configulator project types default their `outdir` according to the",
+        "following table. Override `outdir` explicitly only when you have a",
+        "genuine reason \u2014 the defaults cover the common path.",
+        "",
+        "| Configulator project type | Default `outdir` |",
+        "|---------------------------|------------------|",
+        "| `TypeScriptProject` | `packages/<scope>/<name>` |",
+        "| `AwsCdkProject` | `apps/<scope>/<name>` |",
+        "| `AstroProject` | `sites/<scope>/<name>` |",
+        "| `StarlightProject` (role = docs) | `docs/` |",
+        "",
+        "`<scope>` is parsed from the sub-project's package name (everything",
+        "after `@` and before `/`). `<name>` is the unscoped part of the",
+        "package name.",
+        "",
+        "## Placing New Sub-Projects",
+        "",
+        "Never hand-roll a sub-project path. Use one of the scaffolding skills,",
+        "which take `@scope/<name>` as input, validate it, and place the new",
+        "project in the correct folder:",
+        "",
+        "- `/create-package` \u2014 scaffolds a new `TypeScriptProject` under `packages/<scope>/<name>`",
+        "- `/create-app` \u2014 scaffolds a new `AwsCdkProject` under `apps/<scope>/<name>`",
+        "- `/create-site` \u2014 scaffolds a new `AstroProject` under `sites/<scope>/<name>`",
+        "",
+        "The monorepo-wide docs site at `/docs` is a singleton and is created",
+        "once per repo via `StarlightProject` \u2014 it is not scaffolded per",
+        "sub-project."
+      ].join("\n"),
+      tags: ["project"]
+    },
     {
       name: "issue-conventions",
       description: "Issue title prefixes, GitHub issue type mapping, prerequisite issues",