--- name: platform-make-distro description: "Author a NET-NEW distribution — a themed, installable, self-hostable PRODUCT built on an existing blueprint (the Debian analogue: install and run). ALWAYS starts with a PREREQ-GATE: a built, GREEN blueprint MUST already exist (the delivery-stack one-rule — build ONE blueprint by hand before any product over it); no blueprint → STOP and build it first. A distribution adds ONLY a token theme + opinionated defaults + install wizard + optional CMS over the blueprint — it MUST NOT re-implement the blueprint or author reusable code (that lives in @platform-modules/* packages). Built only for a REAL install/self-host consumer (YAGNI — not speculatively). Graduates to its OWN repo (100% on published packages) once contracts freeze; in-monorepo until then. Use on /platform-make-distro or when asked to build an installable product/distro. Holds no code rules of its own — points to mod-www design §0/§9/§10 + delivery-stack §2." --- # Make Distribution — Net-New Installable-Product Authoring (prereq-gated) **Audience: AI coding agents first.** Optimize for activation, not prose — keep ladders as ladders. A **distribution** = a *themed, installable, self-hostable **product*** = a blueprint **+** a token theme **+** opinionated defaults **+** install wizard **+** optional CMS. The Debian analogue: an end-user **installs and runs** it (a blueprint is what you *develop with*; a distribution is what someone *installs*). This skill authors ONE distribution over an existing blueprint. > Holds **no code rules of its own.** Three-tier model (blueprint → distribution → instance) + graduation rule → `docs/specs/2026-06-17-mod-www-foss-site-program-design.md §0/§9/§10`. Vocabulary → `docs/specs/2026-06-16-delivery-stack.md §2` (the `distribution` row). Theme = token VALUES over the contract → `docs/specs/2026-06-16-ui-product-brief.md` + `@platform-modules/ui-tokens`. Code rules → `docs/standards/coding-standard.md`. Gates → `docs/plans/module-plan-template.md`. This file is *process*, not doctrine. ## Step 0 — PREREQ-GATE (BLOCKING — before anything else) **Rule (delivery-stack §0 one-rule): build ONE blueprint BY HAND, end-to-end, GREEN, before authoring any product over it.** A distribution with no underlying blueprint is the speculative-framework trap. 1. Name the blueprint this distribution sits on (e.g. `software-site` distribution over the `content-site` blueprint). 2. Confirm that blueprint **exists, is hand-built, and is green** — catalogued in `registry.json → blueprints`, with its `apps/consumer` artifacts (recipe + wiring + composition test) passing (delivery-stack §4.1). 3. **No green blueprint → STOP.** Build the blueprint by hand first (`/platform-make-modules` for missing modules → assemble the blueprint). Do not start a distribution on a blueprint that does not exist. ## Step 1 — YAGNI gate: is the distribution earned NOW? (BLOCKING) **Rule: a distribution is built only for a REAL install/self-host consumer — never speculatively.** A blueprint serves the *developer*; a distribution serves the *end-user who installs*. If no one yet needs to install-and-run, the distribution is **designed-for, built-later** (mod-www design §0: `software-site` is the roadmap target, deliberately deferred). - Real install/self-host consumer exists → proceed. - No consumer yet → record the distribution as **roadmap** (design the boundary so nothing leaks upward, build nothing). This is the gate **succeeding**. ## Step 2 — What a distribution ADDS (and must NOT do) **ADDS, over the blueprint (the only four):** 1. **A token theme** — the color/typography VALUES over the `@platform-modules/ui-tokens` *contract* (the blueprint wires the contract, ships no values; the distribution supplies them — this is where "UI variation" lives, mod-www §0). 2. **Opinionated defaults** — config the blueprint left open. 3. **Install wizard** — the install-and-run surface. 4. **Optional CMS** — headless editing (the `ContentStore` contract is frozen by a real CMS consumer in *this* program, mod-www §4 — not invented speculatively). **MUST NOT (reject on sight):** - Re-implement the blueprint, or author reusable code → reusable code ALWAYS lives in a `@platform-modules/*` package (mod-www §0), never inside a distribution. - Own this-deployment-only content/data → that is the **instance** tier (one deployed site), not the distribution. - Bake a host/framework/provider → north-star: never impose; the theme + defaults stay over swappable seams. ## Step 3 — Repo home + graduation (Debian-from-kernel) **Rule (mod-www §9): plan the dependency boundary as if the distribution were a separate repo TODAY (nothing leaks upward), but keep it IN-MONOREPO until the graduation trigger fires.** - **In-monorepo while contracts churn** — `workspace:^` gives atomic cross-package edits (a module fix + its consumer in one commit), the killer feature during the discovery loop. Splitting early taxes every iteration with a publish cycle. - **Graduate to its own repo — depending 100% on PUBLISHED `@platform-modules/*` — ONLY when both hold:** (a) the module contracts it consumes are **frozen**, AND (b) the publish path is **proven under real consumption**. Until both fire, keep in-repo. - The downward-only dependency (instance → distribution → blueprint → packages) holds regardless of repo home; the repo split only *enforces* it. ## Step 4 — Author + harness - **Theme** = token values + defaults over the blueprint; author against `coding-standard.md` (token discipline, a11y floor) — the distribution's UI passes the same `mod-ui-enforcement` rules as everything else. - **Public-language law (hard):** an installable product is maximally public — zero internal vocab (sourcing/seam/layer) or source-app names in anything it renders, its wizard, or its docs. - **Harness** = install-and-run proof: the distribution installs clean, the wizard completes, the themed product builds + passes its blueprint's gate (e.g. mod-www's 100/100 §7). Not "done" until install-and-run is demonstrated, not asserted. ## Build execution A distribution is multi-file product work → `cursor` in a worktree (`CLAUDE.md §4`; dispatch policy in `platform-orchestrator`). Judgment — prereq/YAGNI/graduation gate verdicts, theme/defaults boundary, what stays package vs distribution vs instance — is the main loop's alone, never delegated.