GitHub Repo Standardizer

Standardize, professionalize, or tidy up any GitHub repository — emoji label taxonomy (P0–P3 priority, impact severity, auto-close rules), issue forms, PR template, CI, CODEOWNERS, rulesets, and docs. Use when creating a new repo or polishing an existing one.

Detect a repository's current state, then apply a professional baseline: issue forms, PR template, label taxonomy, CI, CODEOWNERS, rulesets, docs. 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)

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 the whole taxonomy (emoji + description) into the chosen language.
  • 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; extend or trim per the profile in Step 1. Prefix every label with an emoji — the whole taxonomy must be scannable at a glance.

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):

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	0e8a16

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.
• Every label gets an emoji / icon prefix — not just rating tiers. Each category carries a distinct, semantic emoji (bugs 🐛, features ✨, docs 📚, priority dots 🔴🟠🟡🟢, status markers 🚧✅🎉🚫). The emoji must match the label's meaning, never decorative-only. Rating tiers in particular need a clear low→high emoji gradient (e.g. rating: 🦞 diamond lobster).
• 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"
jq -c 'if type == "array" then .[] else to_entries[] | {name: .key} + .value end' templates/labels.json | while read -r l; do
  name=$(echo "$l" | jq -r .name); color=$(echo "$l" | jq -r .color); desc=$(echo "$l" | jq -r .description)
  enc=$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1]))" "$name")
  if gh api "$R/labels/$enc" >/dev/null 2>&1; then
    gh api -X PATCH "$R/labels/$enc" -f name="$name" -f color="$color" -f description="$desc" --silent && echo "label updated: $name"
  else
    gh api -X POST "$R/labels" -f name="$name" -f color="$color" -f description="$desc" --silent && echo "label created: $name"
  fi
done

• URL-encode label names (spaces, slashes).
• To reconcile drift (deleted manual labels), show the diff and ask before removing labels that are already in use.

Module B — Issue forms + config

Create .github/ISSUE_TEMPLATE/ with config.yml plus one YAML form per template (bug / feature / question). Push via a commit:

bash

mkdir -p .github/ISSUE_TEMPLATE
cp templates/issue-form-*.yml templates/config.yml .github/ISSUE_TEMPLATE/
git add .github/ISSUE_TEMPLATE && git commit -m "chore: add issue forms" && git push

• If templates already exist, diff them; only overwrite identical or clearly stale files (ask first if the user may have customized them).
• If there is no git clone, clone first (gh repo clone OWNER/REPO), edit, push.

Module C — PR template

bash

mkdir -p .github
cp templates/PR_TEMPLATE.md .github/PULL_REQUEST_TEMPLATE.md
git add .github/PULL_REQUEST_TEMPLATE.md && git commit -m "chore: add PR template" && git push

• Write the template in the user-chosen language (Preflight step 5).

Module D — CI workflow

Pick the workflow from the framework detection (templates/ci-*.yml). Write to .github/workflows/ci.yml, commit, push. Keep existing workflows; only add ci.yml if none exists.

• Note: pushing workflow files requires a token with the workflow scope; if the push is rejected with 403, tell the user their token lacks workflow.

Module E — Branch rules

Prefer rulesets (modern) over legacy branch protection:

bash

# list existing
gh api repos/OWNER/REPO/rulesets -q '.[].name'
# create (example: protect default branch)
gh api -X POST repos/OWNER/REPO/rulesets --input - <<'EOF'
{
  "name": "protect-default-branch",
  "target": "branch",
  "enforcement": "active",
  "conditions": {
    "ref_name": {"include": ["refs/heads/DEFAULT_BRANCH"], "exclude": []}
  },
  "rules": [
    {"type": "pull_request", "parameters": {"required_approving_review_count": 1, "dismiss_stale_reviews_on_push": true, "require_code_owner_review": false, "require_last_push_approval": true, "required_review_thread_resolution": true}},
    {"type": "required_linear_history"},
    {"type": "deletion"},
    {"type": "non_fast_forward"},
    {"type": "required_signatures"}
  ]
}
EOF

• Idempotency: if a ruleset with the same name exists, update it with PUT repos/OWNER/REPO/rulesets/{id} — full replace, include the complete body (name, enforcement, conditions, rules, bypass_actors). There is no PATCH for rulesets (PATCH returns 404).
• Optional admin bypass: add "bypass_actors": [{"actor_id": 5, "actor_type": "RepositoryRole", "bypass_mode": "always"}] (id 5 = admin) so maintainers can push directly to the protected branch; non-admins still go through pull requests.
• pull_request parameters are all required in current API versions: required_approving_review_count, dismiss_stale_reviews_on_push, require_code_owner_review, require_last_push_approval, required_review_thread_resolution. Omitting any → HTTP 422.
• target: "branch" + ref_name.include: refs/heads/<default>; also offer "tag" rules if tags matter.
• Org repos: optionally offer org-level rulesets (/orgs/{org}/rulesets).

Module F — Docs

README (ask about languages FIRST):

• Ask the user: which languages should the README support? (suggest the project's primary language + English for international projects)
• If a README already exists, ask whether to adapt it into more languages — never add languages without asking.
• Language switcher convention (pattern from programmingHLS/ccmm):
  • Default file stays README.md (usually English).
  • Extra languages: README.<lang>.md (e.g. README.zh.md, README.ja.md).
  • Top of every file, a switcher line — current language as plain text, others as relative links:
    • README.md: < English | [简体中文](./README.zh.md) >
    • README.zh.md: < [English](./README.md) | 简体中文 >
  • Keep structure, badges, and anchors parallel across language files.
• README.md: if missing or bare, generate one from templates/README.md (badges, install, usage, modules table). Keep the user's existing content if it is already substantive — only append a badges block.
• CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md: copy from templates if missing (write CONTRIBUTING.md in the user-chosen language from Preflight step 5).
• VISION.md: optional direction doc (modeled on OpenClaw's VISION.md) — generate a short vision from templates/VISION.md (origin, guiding principles, current state, direction, contribution rules) if the user wants one.
• THIRD_PARTY_NOTICES.md: add when the project adapts third-party content (licenses, fonts, code of conduct) — list each source and its license.
• docs/ARCHITECTURE.md: for non-trivial projects, generate a short architecture doc (structure, flow, constraints) from the audit.
• LICENSE: ask the user which license (default MIT) before creating.
• CHANGELOG.md: create from templates/CHANGELOG.md (Keep a Changelog format) if missing; log notable changes per release.

Module G — AI assistant guides (CLAUDE.md / AGENTS.md)

• Add a CLAUDE.md (guidance for Claude Code) and an AGENTS.md (guidance for any AI coding agent) when missing — see templates/CLAUDE.md and templates/AGENTS.md.
• If they already exist, diff and fill gaps rather than overwrite.
• Typical content, derived from the repo audit (Modules A–F):
  • Project: one-paragraph summary, status, stack.
  • Commands: build / test / lint / run (from CI detection + package scripts).
  • Conventions: commit style (see CONTRIBUTING), label taxonomy, i18n requirements, secrets policy (never hardcode keys), file map.
  • Caveats: known risks, areas to be careful with.
• CLAUDE.md vs AGENTS.md: CLAUDE.md is Claude-specific; AGENTS.md is agent-agnostic (works for Cursor/Copilot/OpenClaw too). Keep AGENTS.md free of Claude-only references.

Verification

bash

gh label list --repo OWNER/REPO --limit 200 | wc -l
gh api repos/OWNER/REPO/contents/.github/ISSUE_TEMPLATE -q '.[].name' 2>/dev/null
gh api repos/OWNER/REPO/contents/.github/PULL_REQUEST_TEMPLATE.md -q .name 2>/dev/null
gh api repos/OWNER/REPO/contents/.github/workflows/ci.yml -q .name 2>/dev/null
gh api repos/OWNER/REPO/rulesets -q '.[] | {name:.name, enforcement:.enforcement}'

Report a final table: module | status (applied/skipped/failed) | note.

Rules of thumb

• Idempotent: every module can run twice with the same result.
• Never clobber user content: diff first, ask before overwriting customized files.
• Auth first: no token, no action — tell the user how to log in, never guess.
• Dry-run before destructive ops: rulesets, branch rules, label deletion, visibility changes.
• Confirm scope: org/private repos and anything the user didn't explicitly name.

Templates

All templates live in templates/: labels.json, LABELS.md, config.yml, issue-form-bug.yml, issue-form-feature.yml, issue-form-question.yml, PR_TEMPLATE.md, ci-node.yml, ci-python.yml, ci-go.yml, ci-rust.yml, CODEOWNERS, CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md, CLAUDE.md, AGENTS.md, VISION.md, CHANGELOG.md, README.md, README.zh.md.