repo-standardizer

# GitHub Repo Standardizer Detect a repository's current state, then polish its surface: issue forms, PR template, label taxonomy, CI, CODEOWNERS, rulesets, docs. Works on repo metadata and config files only — code logic is never touched. **Idempotent** — safe to re-run; fills gaps and reconciles drift without duplicating or clobbering. ## When to use - User says "standardize / tidy up / professionalize this repo" - A new repo was just created and needs templates, labels, CI, and rules from day one - A repo looks bare: no templates, no labels, no CI, no branch protection ## Preflight (mandatory, in order) > **Requires**: `gh` CLI (authenticated), `git`, `jq`, `python3` — verify > they exist before starting (`which gh git jq python3`). ### 1. Authenticate — check gh login first ```bash gh auth status 2>/dev/null || echo "NOT_LOGGED_IN" ``` - **Logged in** → continue; print `gh api user -q .login` so the user knows which account will act. - **Not logged in** → STOP. Tell the user (do not guess): 1. Run `gh auth login` (web/device flow), **or** 2. Export a token: `export GH_TOKEN=ghp_xxx` — needs `repo`, `workflow` (for CI files) and, for org repos, `admin:org` (or `admin:repo_hook` / org membership admin) scopes. - Never paste tokens into chat, logs, or files. If the user pastes a token in chat, advise them to revoke it and re-issue. - If `gh auth login` is impossible in this environment (headless), suggest `gh auth login --with-token` reading from a file the user created. Verify the acting account can write to the target: ```bash # user repos: no extra check needed beyond token scopes # org repos: must be a member/admin of the org gh api "orgs/ORG/memberships/$(gh api user -q .login)" -q .role 2>/dev/null || echo "NO_ORG_ACCESS" ``` - `admin`/`member` → OK. `404` → stop and ask the user to add the account to the org first. ### 2. Detect repository type ```bash gh repo view OWNER/REPO --json name,owner,visibility,defaultBranchRef,isArchived,isFork \ -q '{name:.name, ownerType:.owner.type, visibility:.visibility, defaultBranch:.defaultBranchRef.name, archived:.isArchived, fork:.isFork}' ``` | Field | Meaning | Consequence | |---|---|---| | `ownerType` | `User` = personal, `Organization` = org | Org repos can also use org-level rulesets; both support repo-level rulesets | | `visibility` | `PUBLIC` / `PRIVATE` / `INTERNAL` | Private: skip public-facing docs pressure, keep CI secrets minimal; public: README badges + CONTRIBUTING/SECURITY matter | | `archived` / `fork` | Read-only / fork | **Skip write modules**; report why | If the repo was not explicitly named by the user, confirm before touching an org or private repository. ### 3. Audit current state ```bash gh label list --repo OWNER/REPO --limit 200 gh api repos/OWNER/REPO/contents/.github -q '.[].path' 2>/dev/null || echo "no .github dir" gh api repos/OWNER/REPO/contents/.github/workflows -q '.[].name' 2>/dev/null || echo "no workflows" gh api repos/OWNER/REPO/rulesets -q '.[] | {name:.name, enforcement:.enforcement}' 2>/dev/null || echo "no rulesets" gh api repos/OWNER/REPO/branches -q '.[].name' 2>/dev/null for f in README.md CONTRIBUTING.md SECURITY.md LICENSE .gitignore; do gh api "repos/OWNER/REPO/contents/$f" -q .name 2>/dev/null || echo "missing: $f" done ``` ### 4. Detect test framework (for CI module) Check for these signals (first match wins): ```bash gh api repos/OWNER/REPO/contents/package.json -q .name 2>/dev/null # node → templates/ci-node.yml gh api repos/OWNER/REPO/contents/pyproject.toml -q .name 2>/dev/null # python → templates/ci-python.yml gh api repos/OWNER/REPO/contents/go.mod -q .name 2>/dev/null # go → templates/ci-go.yml gh api repos/OWNER/REPO/contents/Cargo.toml -q .name 2>/dev/null # rust → templates/ci-rust.yml ``` No signal → propose the generic CI (or ask the user whether CI is wanted at all). ### 5. Ask about language (before planning) - Ask the user which language `CONTRIBUTING.md` and the PR template should be written in (default: English, or the project's primary language for local projects). Translate the templates accordingly when generating — never assume a language. - (README languages are asked separately in Module F.) ### 6. Ask about automation (decides the Governance labels) Ask the user whether the repo has any **automation bots or AI writers** running on it — e.g. dependabot, a Stale bot, ClawSweeper, or an AI coding agent that auto-files PRs / auto-fixes issues. - **Why ask**: `r:*` / `clawsweeper:*` / `triage:*` / `close:*` labels are **signal labels, not categories** — a bot reads them and acts (auto-close, auto-lock, auto-fix, auto-merge). Without running automation those labels are dead weight, so the answer decides whether the Governance dimension is added at all (Module A, Step 2). - **Yes** → plan the `Governance / auto-close rules` dimension (add only the `r:*` rules matching the project's real reject criteria). - **No** → skip that dimension entirely — never add `r:*` / bot labels to a repo with no automation. ## Workflow 1. **Preflight** (above). If auth or access fails, stop with a clear message. 2. **Dry-run plan** — show the user a concise table of what will be created/updated/skipped. Get confirmation for: rulesets, branch deletion/protection changes, org-level changes, and anything destructive. 3. **Apply modules** (each idempotent; run in this order). 4. **Verify** — re-query and print an `applied / skipped / failed` checklist. ### Module A — Labels (design first, then idempotent upsert) **Step 1 — Profile the project** (adjust the taxonomy, never copy blindly): - **Rating labels** → design a themed tier system for THIS project (never copy an existing repo's set verbatim): - Reference example — OpenClaw's official repo uses themed tiers with emoji icons and a low→high color gradient (**EXAMPLE ONLY, do not copy**): `rating: 🧂 unranked krab` → `rating: 🦪 silver shellfish` → `rating: 🦐 gold shrimp` → `rating: 🦀 challenger crab` → `rating: 🐚 platinum hermit` → `rating: 🦞 diamond lobster` - International project → universal grades also work (`grade: S/A/B/C/D` or `★`–`★★★★★`) - Always redesign: pick a theme that fits the project (animals, gems, ranks, stars…) and the audience's language. Do not reuse any existing repo's rating labels as-is. - **Teams**: if the repo has an explicit division of labor (CODEOWNERS, CONTRIBUTING, a team list in docs) → add one `team: *` label per group (e.g. `team: frontend`, `team: algorithm`). No team list → skip. - **Project type** (library / app / coursework / org-infra) → decide which dimensions below are needed (`dependencies`, `security`, `docs`, …). - **Language**: write every label name and description in the language chosen in Preflight step 5 (default English; local project → its primary language). Never assume — translate every label name and description into the chosen language (emoji glyphs stay as-is). - **Exception — bot labels**: `r:*` / `clawsweeper:*` / `triage:*` / `close:*` names are matched literally by automation code (almost always English). Keep those **names** in the bot's language — a translated name breaks the bot. Only their `description` may use the user's language. **Step 2 — Compose categories.** Baseline lives in `templates/labels.json` (plain names, no emoji); extend or trim per the profile in Step 1. **Emoji policy — rating tiers are the ONLY mandatory-emoji labels.** Every `rating:*` / `issue-rating:*` tier MUST carry an emoji with a clear low→high gradient (e.g. `rating: 🦞 diamond lobster`). All other labels: emoji is the agent's call — add icons where they aid scanning, omit them where they clutter. **Consistency rule: within one dimension, either ALL labels carry an emoji or NONE do** — never a mixed half-emoji dimension (e.g. don't ship `🐛 bug` next to a plain `enhancement`). **Every dimension is opt-in except Type.** Add a dimension only if the repo actually needs it; skip it otherwise. The menu below mirrors OpenClaw's official label taxonomy (the richest open reference) — cover every dimension that applies, but never force one the repo doesn't use. **Priority uses `P0`–`P3`** (OpenClaw's convention — `P0` = emergency). Examples in the tables below show the optional emoji style — apply them all or none per dimension (baseline ships plain `P0`–`P3`): | Label | Meaning | Color | |---|---|---| | `🔴 P0` | Emergency: data loss, security bypass, crash loop, unusable core | `b60205` | | `🟠 P1` | High: blocks planned work, needs attention soon | `d93f0b` | | `🟡 P2` | Medium: normal priority | `fbca04` | | `🟢 P3` | Low: nice to have | `1a7f37` | **Dimension menu** (write each label in the user's chosen language): | Dimension | Labels (examples) | Add when | |---|---|---| | Type (always) | `🐛 bug` `✨ enhancement` `📚 documentation` `❓ question` `🙋 help wanted` `🌱 good first issue` | always | | Priority | `🔴 P0` `🟠 P1` `🟡 P2` `🟢 P3` | recommended | | Status | `🚧 in progress` `🧱 blocked` `✅ ready to merge` `🎉 merged` `🚫 wontfix` | recommended | | Impact | `impact: security` `impact: data-loss` `impact: availability` … | recommended; required for security-sensitive repos | | Rating (PR quality) | `rating: 🦞 diamond lobster` … themed tiers | PR-quality gate exists | | Issue rating | `issue-rating: 🦞 diamond lobster` … | issue-quality gate exists (may fold into Rating) | | Merge risk | `merge-risk: 🚨 security-boundary` `merge-risk: 🚨 availability` … | maintainer review process exists | | Size | `size: XS` `size: S` `size: M` `size: L` `size: XL` | large repo / team estimation | | Area / module | `area: core` `area: api` `area: cli` … | multi-module project | | Bug detail | `bug: behavior` `bug: crash` | crash-prone / many bug reports | | Governance / auto-close rules | `r: spam` `r: support` `r: no-ci-pr` … `clawsweeper:*` `triage:*` | automation bot enforces close/lock/review rules | | Close reason | `close: duplicate` `close: superseded` `close: invalid` … | close-automation bot exists | | Triage | `triage: bug` `triage: blocked` `triage: needs-review` … | triage workflow exists | | Proof | `proof: 🎥 video` `proof: 📸 screenshot` | reproduction evidence required | | Dependencies | `📦 dependencies` | dependabot / dependency PRs | | Security | `🔒 security` | security-sensitive repo | | Regression | `↩️ regression` | stable project (was-working-now-fails) | | Stale | `🕰️ stale` `🚫 no-stale` | stale automation exists | | Team | `team: <group>` | explicit division of labor | | Duplicate / invalid | `👯 duplicate` `🚫 invalid` | active public repo with many issues | | Channel | `channel: discord` `channel: telegram` … | multi-channel product (OpenClaw-style) | | App / platform | `app: ios` `app: android` `app: web-ui` … | multi-platform app | | Extensions / plugins | `extensions: <name>` `plugin: <name>` | plugin/extension ecosystem | **Governance rules (`r:` / bot labels) — gated by Preflight step 6.** Only consider this dimension if the user answered "yes" to automation bots / AI writers; skip it entirely otherwise. Auto-close and bot-state labels are **signal labels, not categories** — a bot (or Actions workflow) reads them and acts (auto-close, auto-lock, auto-fix, auto-merge). They are useless without the matching automation, so **skip them unless a governance bot actually runs** on the repo. If one does, add only the `r:*` rules matching the project's real off-topic / reject criteria (e.g. `r: spam`, `r: support`, `r: no-ci-pr`) plus the bot's own state labels (`clawsweeper:*`, `triage:*`, `close:*`). Never copy OpenClaw's set verbatim — its rules encode OpenClaw's specific product boundaries. **Impact dimension** — the security "blast radius" judgement (generalized from OpenClaw; trim to the repo's actual failure modes): | Label | Meaning | |---|---| | `impact: security` | security boundary, credentials, authz, sandbox, sensitive data | | `impact: data-loss` | loses/corrupts/drops user, session, or config data | | `impact: availability` | crash, hang, restart loop, or process outage | | `impact: auth-provider` | auth / routing / model choice / secret resolution breaks | | `impact: session-state` | session / memory / state drifts or corrupts (stateful systems) | | `impact: message-loss` | messages/events lost, duplicated, or misrouted (messaging systems) | | `impact: ux-blocker` | user blocked with no terminal/logs/support (GUI products) | | `impact: ux-friction` | confusing flow / support burden (GUI products) | | `impact: other` | meaningful impact outside the owned taxonomy | **Step 3 — Color rules (mandatory):** - **Diverse palette**: colors must be rich and varied — the whole label set should look like a palette, not a monochrome block. Even within one category, spread the hues (e.g. priority labels: red / orange / yellow / green, or four clearly different hues). - **Semantic hints (not hard mappings)**: `ready to merge` / `merged` / done → greens (never gray or red); `wontfix` → gray; `in progress` → blue. Everything else: pick colors that look good together and match the label's meaning loosely — but prefer variety over strict one-meaning-one-color. - **Emoji policy**: rating tiers are emoji-**mandatory** — every `rating:*` / `issue-rating:*` label needs a clear low→high emoji gradient (e.g. `rating: 🦞 diamond lobster`). Everywhere else, emoji is the agent's call: use icons where they aid scanning, omit them where they clutter. **Consistency: within one dimension, all labels carry an emoji or none do** — never a mixed half-emoji dimension. If used, the emoji must match the label's meaning, never decorative-only. - **Rating labels need docs**: when rating labels are added, also add `LABELS.md` (Step 4) describing each label's meaning and the explicit low→high order, so the ranking is unambiguous. - Neighboring labels must be distinguishable. Forbidden: all-one-color, adjacent duplicates, or colors that contradict the label content. **Step 4 — Rating-label docs (only if rating labels exist).** Generate `LABELS.md` from `templates/LABELS.md` (or extend an existing docs file): list every rating label with its meaning and the explicit low→high order, plus the rest of the taxonomy. Commit and push it together with the labels. **Step 5 — Idempotent upsert.** GitHub has **no** `PUT /labels/{name}` endpoint. Upsert = check existence (`GET /labels/{name}`), then `POST /labels` (create) or `PATCH /labels/{name}` (update). Works for both map-form and array-form `labels.json`: ```bash R="repos/OWNER/REPO"