Skip to content
Pulci Nella — the Clownware markPulci Nella — the Clownware markClownware Docs

ADR-052: Script Taxonomy — Cloner-Facing vs Maintainer

Status

Section titled “Status”

Accepted

Context

Section titled “Context”

package.json exposes ~56 scripts. Most maintain the template itself (perf:baseline, perf:budgets, bundle:analyze, images:optimize, roadmap:update, the agents:* spine, release:*, audit:*) (amended 2026-08-02: the first four originally cited the scripts/src/*.ts file basenames — baseline-performance, track-performance-budgets, analyze-bundle, optimize-images-interactive — which were never script names). A portfolio cloner needs roughly ten of them. Surfacing all of them as flat peers of dev/build reads as “complex to use” and buries the everyday commands — a real onboarding cost for a distribution template (applies the scope framework of ADR-035).

The obvious fix — renaming maintainer scripts into a maint:* namespace — was rejected: ~30 scripts are referenced by name in CI workflows, Husky hooks, and inside other scripts (quality:ci calls agents:check; build calls env:validate and tokens:build; .github/workflows/* call several directly). Renaming them is high-risk churn with no functional benefit.

Decision

Section titled “Decision”

Treat the split as a documentation and ordering convention, not a renaming scheme.

  1. Group + order in package.json — cloner-facing core first (dev, build, preview, quality/quality:ci, test:*, tokens:build, format/lint*, check*, clean*), then a separator key, then the maintainer/advanced scripts. The separator uses inert "//1" / "//2" keys (valid JSON, ignored by tooling) since JSON has no comments.
  2. README “Key Commands” lists the ~10 everyday scripts up front; the full set lives in a collapsed “All Scripts Reference”.
  3. No renames, ever. Script names are a stable contract for CI, hooks, and muscle memory. This ADR explicitly forecloses a maint:*-style rename as out of scope — not deferred.

Consequences

Section titled “Consequences”
  • Positive: the everyday surface is obvious at a glance; zero CI/hook/doc breakage risk; the convention is cheap to maintain.
  • Negative: the inert "//1"/"//2" separator keys are a mild idiom; the grouping is a convention reviewers must honour when adding scripts (new cloner-facing scripts go above the separator, maintainer scripts below).

References

Section titled “References”

Enforcement

Section titled “Enforcement”
  • Testable consequences:
    • TC-1: every stable cloner-facing script name exists in package.json.
    • TC-2: the //1///2 separator keys are present, preserving the two-group ordering.
  • Checks:
    • TC-1, TC-2 → check script-contract (status: warn)
  • Not machine-checkable: which group a new script belongs to is a judgment call.
  • Graduation log: (empty at creation; entries added when a check changes status)

Date: 2026-06-07
Participants: Template maintainers
Outcome: Accepted — scripts grouped/ordered by audience; renaming foreclosed