scaffolding-maintainer

Scaffolding Maintainer

Improves the project-scaffolding skill along two separate paths. Keep them separate — they have different sources of truth and different failure modes.

Path	What changes	Source of truth	Risk if wrong
A. Fact refresh	Version numbers in assets/versions.json	npm / PyPI registries	Generated projects pin versions that do not exist or do not install
B. Procedure improvement	SKILL.md, references, wizard options, templates in scaffold.py	assets/observations.md	The wizard recommends something wrong or generates broken code

Absolute Rules

1. Never write a version number from memory. Model recall of package versions is unreliable and silently wrong. Every version in versions.json must come from refresh_versions.py, which queries the registries directly. If the network is unavailable, stop and say so.
2. Never auto-apply a major version bump. A major bump can invalidate the template source in scaffold.py, not just the number. Follow references/template-drift.md first.
3. Never finish without running verification. scripts/verify_scaffold.py must pass before repackaging, and --install must pass before adopting any version change. A version that resolves is not a version that builds.
4. Never delete observation entries. Mark them resolved in place so the log stays auditable.

Path A: Refresh Versions

Run from the project-scaffolding/ directory.

python3 scripts/scaffold.py --version-status      # how stale is it?
python3 scripts/refresh_versions.py               # dry run; reports -> bump  !! review

Read the report:

• -> bump lines are minor/patch moves within the existing major. Because the manifest uses caret (^) and >= ranges, users already resolve to these versions at install time. Applying them is safe and mostly cosmetic.
• !! review lines are major bumps, pre-1.0 minors, or 0.0.x patches. These need judgment. Do not apply them with --include-review until the template check in references/template-drift.md is done for each affected package.
• A !! line ending in [safe now: X] has an in-series update available. --apply takes those automatically: the major stays held, but the package still gets its fixes. An in-series bump is safe for the package itself, not necessarily for its peers — bumping TypeScript 5.8 to 5.9 once broke Angular 19, whose peer range capped at <5.9. Always run --install afterwards.

Apply the safe set, then handle reviews individually:

python3 scripts/refresh_versions.py --apply       # applies bump lines only
python3 scripts/verify_scaffold.py                # regenerate every project type

When a major bump is genuinely not wanted — a package pinned for compatibility with something else, such as React Native tracking an Expo SDK — record it in the manifest's hold map with a reason rather than repeatedly declining it:

"hold": { "react-native": "must match the Expo SDK version the wizard offers" }

Path B: Act on Observations

Read assets/observations.md. Group entries by tag and decide what each class warrants:

Tag	Typical fix
default-rejected	If one default is rejected repeatedly, change the recommendation in SKILL.md and references/wizard-options.md — or present it as an explicit choice instead of a default
missing-option	Add the framework or option: update references/wizard-options.md, SKILL.md's type list, and implement a creator method in scaffold.py
broken-output	Fix the generator, then add the case to verify_scaffold.py so it cannot regress
template-drift	Update the template method in scaffold.py to match the pinned major

Require a pattern before changing a default. A single rejection is one user's preference, not evidence. Two or three independent entries with the same shape justify a change. State the evidence count when proposing one.

When an entry is acted on, append -> RESOLVED <date>: <what changed> to that line. When an entry is judged not actionable, append -> WONTFIX <date>: <why>.

See references/review-workflow.md for the full patching procedure, including how to add a new project type end to end.

Verification (mandatory)

python3 scripts/verify_scaffold.py                # all types generate, configs parse
python3 scripts/verify_scaffold.py --snapshot     # record current output as the golden baseline
python3 scripts/verify_scaffold.py --compare      # diff against the golden baseline

Use --compare after any change that should not alter output (a refactor). Use --snapshot to re-baseline deliberately after a change that should. An unexplained diff means stop and investigate, not re-snapshot.

--install is the mode that finds real defects. Generation checks confirm files are well-formed; they cannot tell that a template imports a package nobody declared, that a lint script points at a removed command, or that a tsconfig option was deprecated. Only installing the project and running its scripts finds those. Run it after any version adoption, and after any template change:

python3 scaffolding-maintainer/scripts/verify_scaffold.py --install --only react nextjs

Node version matters: run it on the Node major the manifest targets, since several toolchains refuse to start on older releases.

Stage the baseline with -f. Generated projects contain their own .gitignore files, and a nested .gitignore overrides the repository's rules for its subtree — so a plain git add drops files (.vscode/settings.json, src/lib/*) from the baseline without reporting anything:

python3 scaffolding-maintainer/scripts/verify_scaffold.py --snapshot
git add -f tests/golden
git diff --cached --name-only -- tests/golden | wc -l   # must equal the file count on disk

Already-tracked files stay tracked regardless of ignore rules; -f matters only for files a snapshot newly introduces.

Repackaging

After any change under project-scaffolding/, repackage from the repository root:

cd project-scaffolding && zip -r ../project-scaffolding.skill SKILL.md scripts/ references/ assets/
cd ../scaffolding-maintainer && zip -r ../scaffolding-maintainer.skill SKILL.md scripts/ references/

Note assets/ is included — the version manifest lives there, and a package without it will fail at import with a missing-manifest error.

Then record the change in CHANGELOG.md at the repository root.

Additional Resources

• references/template-drift.md — how to check whether a major bump invalidates template source, package by package
• references/review-workflow.md — full procedure for patching the skill, including adding a new project type
• scripts/verify_scaffold.py — generates every project type and validates the output