| 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:
- 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.
- 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.
- 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 the agent-instructions
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
- 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.
- Agent-instructions file (CLAUDE.md or the project's equivalent) —
pointing at the pipeline documents, design.md, and the repo's conventions,
so every future coding session inherits the context.
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, create the agent-instructions file.
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, agent-instructions 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-first-deploy 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.
