Project Scaffolding

---
name: project-scaffolding
description: >-
  Turns the pipeline's design documents into a running system. Reads the
  architecture document and implementation plan, executes each ecosystem's
  current official project generator to create the real repo structure (one
  deployable unit per architecture container, monorepo by default), wires the
  walking skeleton end-to-end — UI shell with the design system's tokens.json,
  API, domain stub, local database — stands up the engineering foundations
  (CI, environments, test harness, deployment config written but not
  executed), and verifies empirically by building and running the skeleton
  test. Deploy-ready, not deployed. Use after implementation-planning and
  before per-slice work, when the plan's walking skeleton needs to become a
  real repo. Trigger on "scaffold the project", "set up the repo", "create
  the project structure", "build the walking skeleton", "initialize the
  codebase", or "stand up the skeleton". Checkpoints progress and resumes
  safely — never regenerates over a partial scaffold.
---

# Project Scaffolding

The first skill in the pipeline whose output is a **running system**, not a
document. It takes the architecture and the plan and produces the walking
skeleton as a real repo: generated structure, wired end-to-end, foundations in
place, verified by execution. It ends where deployment begins — everything is
deploy-*ready*; the first actual deploy is the user's step.

Three principles govern it:

1. **The stack is an input, never a decision.** The architecture's ADRs already
   chose the technology. This skill reads the stack and refuses to relitigate
   it. Gaps the generators need answered (package manager, monorepo tool) are
   elicited — and flagged as candidate architecture amendments.
2. **Official generators first, manual structure second.** Every serious
   ecosystem ships an official project initializer that encodes *current*
   best-practice structure. Discover it, verify it against live docs (never
   trust memory for CLI names/flags — live reality always wins), run it for
   real, then customize. Hand-build only where no generator exists, following
   that ecosystem's documented conventions. This keeps the skill self-updating:
   framework conventions change, generators change with them, the skill
   inherits it.
3. **What this skill owns is the stack-independent layer**: the walking-skeleton
   wiring between units, module-boundary enforcement, the design system wired
   into the UI shell, pipeline conventions carried into the repo, and empirical
   verification. Generators create isolated apps; this skill makes them a
   system.

## Inputs

Defaults below; user-provided paths win. Each degrades independently.

- **Architecture** — `docs/architecture.md` (primary). The stack per container
  (from ADRs), the containers themselves (each becomes a deployable unit),
  module boundaries, deployment target, cross-cutting concepts. Without it the
  skill can still run by eliciting the stack directly, but say plainly that
  fidelity suffers — this skill is designed to realize an architecture.
- **Implementation plan** — `docs/implementation-plan.md`. The walking-skeleton
  spec (what's real, what's stubbed, done-when) and the engineering-foundations
  checklist. If missing, derive a minimal skeleton from the architecture and
  confirm it with the user.
- **UX foundations** — `docs/ux-foundations.md`, `docs/design.md`,
  `docs/tokens.json`. The UI-shell contract: tokens wired into each frontend
  surface's token mechanism, design.md referenced from AGENTS.md
  file.
- **SRS** — `docs/srs.md`, light touch: constraints (§2.5) affecting tooling.

**Source-gated traceability**: scaffold decisions cite ADR and container names
when the documents exist; prose otherwise; never fabricate a reference.

**RTM: no write-back.** Scaffolding realizes containers, not requirements —
nothing here maps to a requirement row, and per the RTM column-ownership
contract this skill does not touch `docs/rtm.md`.

## Outputs

1. **The repo** — generated per-unit structure (monorepo by default), module
   boundaries enforced (folders + import/lint rules), skeleton wired
   end-to-end, one passing end-to-end test, CI config, environment configs,
   deployment config written (not executed), `docs/` carried in.
2. **Agent instructions** — `AGENTS.md` at the root carrying the substance
   (pipeline documents, design.md, conventions, commands), plus `CLAUDE.md`
   containing only `@AGENTS.md` as a pointer: one source of truth, every
   coding tool covered, so any future session inherits the context.
3. **`docs/scaffold-notes.md`** — the project-owned record: generators +
   versions + flags actually used, deviations from expectation, decisions
   made, what's stubbed where. Consumers: future sessions on this project, the
   build phases, and the skill author if they ever hand-promote a durable
   lesson into the skill. Notes live in the project, never in the skill folder.

## Workflow

### Phase 0 — Resume check (always first)

Read `references/checkpointing.md`. Look for `docs/.scaffold-progress.md` and
signs of a partial scaffold. If found: **never regenerate over it** —
regeneration over a half-built repo is destructive. Summarize what exists,
what's pending, confirm, and resume at the first pending unit/step. Fresh
start: create the tracker and proceed.

### Phase 1 — Ingest and confirm the scaffold plan (the one gate)

Read the input documents. Extract the build contract: per container — language/
framework (cite the ADR), store bindings, boundaries; plus the skeleton spec
and foundations checklist from the plan. Then play back a short **scaffold
plan** — units and their stacks, repo shape, local data story, CI target, the
done-when condition — and get explicit confirmation. **This is the single gate
before real files are created**; after the nod, the skill executes without
further ceremony.

Repo shape: **monorepo by default**; ask only when signals point otherwise
(e.g., the deployment view implies independently released units or separate
ownership).

### Phase 2 — Gap elicitation (brief)

Ask only what the documents don't answer and the generators require: package
manager, monorepo tool (if multi-unit), repo name/location, versions where it
matters. Batch, offer defaults, keep it short. Anything the *architecture*
should have answered gets flagged as a candidate architecture amendment.

### Phase 3 — Environment preflight and tooling discovery

Read `references/scaffolding-guide.md` (Tooling discovery). Preflight the
environment: required runtimes, package managers, Docker (if the local data
story needs it). Missing prerequisites are a **blocking ask** — surfaced to
the user, never silently worked around. Then, per unit: identify the
ecosystem's current official generator, verify name/flags against live docs
when uncertain, and record generator + version + flags into scaffold-notes.
No generator → plan manual structure from documented conventions.

### Phase 4 — Generate and structure

Run the generators **for real**, per unit, checkpointing after each. Then apply
the pipeline's layer (scaffolding-guide, Structure): monorepo arrangement,
module boundaries as folders + import/lint rules (the architecture's seams made
enforceable), strip generator boilerplate that conflicts with the architecture,
carry `docs/` into the repo, write AGENTS.md (+ the CLAUDE.md pointer) and the READMEs.

### Phase 5 — Wire the walking skeleton

Read `references/skeleton-guide.md`. One trivial end-to-end path: UI shell
(tokens.json wired into each frontend's token mechanism; design.md referenced)
→ API endpoint → domain stub → local database → back. Stubs exactly where the
plan said stubs. Checkpoint per wiring step.

### Phase 6 — Engineering foundations

The plan's checklist made real (skeleton-guide, Foundations): CI pipeline
(lint, test, build) that would run green; environment configs as config, not
provisioned; observability hooks (structured logging at minimum); the test
harness with the one end-to-end skeleton test; deployment config written for
the architecture's target. **Deploy-readiness is the boundary** — nothing is
provisioned or deployed.

### Phase 7 — Empirical verification

Read `references/verification.md`. Verification here means **running things**:
clean install, every unit builds, the skeleton test passes locally (the plan's
done-when — local half verified; deployed half recorded as pending first
deploy), lint/boundary rules pass, CI config valid, tokens actually render in
the shell, AGENTS.md paths resolve. Fix-loop failures; flag anything
unfixable in the delivery summary — never silently ship a broken skeleton.

### Phase 8 — Deliver

Summarize: what exists, the exact commands to run it, what's stubbed, the
pending-initial-deployment note, and the handoff — the skeleton is ready for slice 1
via **detailed-design** (contracts/data) and **ui-design** (screens by SCR ID).
Finalize scaffold-notes and mark the tracker complete.

## Scope boundaries

Does **not**: choose or change the stack (architecture's job — gaps go back as
amendments); deploy or provision infrastructure (deploy-ready only); implement
features or design slices (per-slice detailed-design/ui-design, then build);
write to the RTM.

## What good looks like

- Every deployable unit traces to an architecture container; every stack choice
  cites its ADR (source-gated).
- Generators were discovered and verified live, run for real, and recorded —
  name, version, flags — in scaffold-notes.
- The skeleton test passes on a clean local run; the done-when condition's
  local half is *demonstrated*, not asserted.
- Module boundaries are enforceable (lint/import rules), not aspirational.
- tokens.json is actually wired — delete it and the shell visibly breaks.
- A stopped run resumes without regenerating anything already built.