Skip to main content

catesworks-repo-standards

Why It Exists​

An organization of dozens of repos drifts: different Node versions, different CI gates, different lint setups, different ways of deploying the same kind of service. The temptation is a tool that finds the drift and fixes it everywhere.

The skill was built from a consensus plan that went through six revisions and seven independent adversarial reviews, and every earlier draft made the same mistake: it asserted that a shared package, script or convention was in active use because it existed, without checking that anyone used it that way. The design that survived is deliberately narrow as a result: a large reporting surface and a small write surface. It tells you a lot, and it changes very little.

What It Does​

Given a repo, it resolves the repo's real GitHub topics, loads the repo's own exception file if one exists (the skill reads it and never writes it), and runs an org-wide baseline that always applies:

  • Node 24: verify-only, since the org is already conformant.
  • Runner group: report-only, per job. It never proposes a runs-on change.
  • Lint and format, Changesets or release-please detection: Tier 2 (a proposed diff for a human, no PR).
  • CI quality gate: report-only (does a pull-request workflow run lint, typecheck and test, and does a monorepo use --affected).

On the first run against the org it stops at an approval gate: the topic table must be confirmed or corrected by a person before any topic-specific branch goes active. Then it dispatches per topic (web, vercel, api, docker, desktop, cli, skills, auth, supabase, mcp and others). Each repo and topic outcome is written as one ledger row, incrementally.

Three tiers describe what it may do:

TierWhat it may do
Tier 1Open a pull request. Never commits to a default branch, never merges its own PR. Rollback is always "close the PR".
Tier 2Report plus a proposed diff attached to the run ledger. Never opens a PR.
Report-onlyAn informational ledger row, no diff.

How To Use It​

Ask for a conformance check of a repo (or of the org), and let it resolve topics from the live GitHub API. It writes a ledger of outcomes: conformant, exception-declared, needs-migration-tracked, blocked-pending-approval, or declined-via-pr-close. Add a .catesworks-standards.json to the target repo to record human-authored exceptions.

Gotchas & Invariants​

  1. Topics come from the API, never the name. A repo that merely shares a name prefix with a product family does not get that family's checks. A repo with no matching topic branch is a no-op, reported and not an error.
  2. The runner-group check is permanently report-only. No repo-level migration target survived verification during planning, so the skill never writes or proposes a runs-on change under any condition.
  3. Every write is a PR, never to a default branch, never self-merged. Branches are named catesworks-standards/<slug>.
  4. De-duplicate by branch name, and a closed PR is a decision. An open PR is skipped as "already proposed". A PR closed without merging is recorded as declined in the invoking workspace's ledger and never re-proposed until a human clears it. New PRs are capped per run.
  5. Recognize legitimate variants. Several repos intentionally have different deploy scripts with different roles (build and cut over, cut over only as the no-rebuild rollback, build and push only). The skill reports on function and never proposes collapsing them into one.
  6. Unconfirmed topic definitions ship as report-only. Definitions inferred from how topics co-occur are not enforcement until a person confirms them.
  7. Three actions are unreachable through this skill, with no carve-outs. Changing one repo's cross-repo Actions access level, any Android upload-keystore or Play Console setup, and any change to a shared cloud role's trust policy each need their own explicit approval outside the skill, even if the change is "just additive". If asked to do one while running the skill, it declines and explains.