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.