scaffold

name

scaffold

description

Defines how packages/cli/scaffold is maintained as the authoring harness every generated project inherits verbatim, including the shipped production skill, the reserved discovery, obligation, and principle inventory, and the negative-probe and generated-consumer verification gates. Use before editing anything under packages/cli/scaffold, and to reach the production authoring procedure when authoring production content inside this repository.

Maintaining the scaffold

packages/cli/scaffold is the empty authoring harness @automovie/cli stamps out. A completed regression film fixture lives outside it so generated projects inherit capability and contracts, never another production's content. Treat every scaffold change as a generated-project API change.

The authoring procedure lives with the production

The procedure that authors a production ships inside the scaffold at packages/cli/scaffold/.agents/skills/production/. A generated project therefore holds its own authoring doctrine, and this repository holds exactly one copy of it.

Read the shipped production skill before authoring or reviewing production content anywhere, including a fixture or an experimental sandbox inside this repository. This maintenance skill does not restate it.

Editing any document under that directory changes what every future generated project is instructed to do. Apply the documentation skill writing rules, verify the links resolve from a generated project rather than from this repository, and run the verification gates below.

The shared contract inventory

packages/cli/scaffold/docs/discovery, docs/obligations, and docs/principles are an exact reserved inventory. @automovie/evidence pins their filenames and their ordered H2 anchors, so adding, removing, renaming, or reordering a shared H2 without the matching wiring fails the graph while it loads.

Changing that inventory means changing the target document, EXPECTED_CONTRACTS, the claim or reference that selects it, the package test's canaries, the paid population in internals/scaffold-evidence-gate.mjs whenever that probe's shape selects the target, and the routing guidance in docs/README.md and the shipped skill, in one coherent change. A new target family also joins the reserved directory set and the contract walk.

Classify before adding. A per-file review question is a principle, a role a whole population divides is an obligation, an open search whose result no checklist can enumerate is a discovery duty, and a production procedure is a skill document rather than a target. A rule that belongs to one production is never added here; it belongs to that production's local family and its additive claim.

An anchor is a citation address, so choose it for the durable question rather than the current wording. When an item's text changes, reread every citing host against the new text and renew its review from that reading. Replacing only the fingerprint records a check nobody performed.

Retire an item when it is wrong, absorbed, or inapplicable. Inconvenience to one production is not a reason; that production's own local targets are where its exceptions live.

Verification

After topology, contract, or citation changes, run the scaffold evidence gate. Falsify each new edge or refusal with a disposable negative probe, restore it, and require the normal graph to pass. Build and test the repository, generate a fresh scaffold from packed packages, and prove that its source lint and canaries pass while production design and compile refuse the unselected blank state. Compile the repository-only completed fixture to preserve production regression coverage. Measure every changed executable scaffold source at 100% statements, branches, functions, and lines.

For render, pose, expression, geometry, material, or motion changes, also follow the applicable 3D modeling and viewer verification skills.

The repository evidence graph skill owns committed requirement-to-source traceability for this repository's own packages. The generated-production graph is separate: apply that skill's citation honesty and diagnostic discipline to it, without imposing the requirement-specification-source triangle on a production.