Scaffolding Maintainer

---
name: scaffolding-maintainer
description: >
  Maintains and improves the project-scaffolding skill. This skill should be used when the user
  asks to "update the scaffolding skill", "refresh framework versions", "are the versions stale",
  "check for outdated packages", "improve project-scaffolding", "act on the scaffolding
  observations", "add a project type to the scaffolder", "fix a scaffolding template", or after a
  scaffolding session logged an entry in assets/observations.md. Handles two distinct jobs:
  refreshing dependency facts from the npm and PyPI registries, and patching the skill's
  procedures, templates, and wizard options based on recorded real-world usage.
---

# 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.

```bash
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:

```bash
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:

```json
"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)

```bash
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:

```bash
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:

```bash
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:

```bash
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