Add repo-standardizer skill: polish any GitHub repo surface (#2715)

* Add repo-standardizer skill: polish any GitHub repo surface * fix(skill): remove non-string metadata and fix template README refs for vally lint * docs(skill): drop markdown relative links from README language-switcher example Vally valid-refs flagged ./README.md and ./README.zh.md as missing file references; they are generated artifacts, not skill files. Keep the example as plain text to satisfy the linter. * fix(template): add missing language switcher to English README template Align with README.zh.md template and SKILL.md switcher convention: current language as plain text, other languages as relative links. --------- Co-authored-by: programmingWTF <programmingWTF@users.noreply.github.com>
2026-08-24 09:56:51 +00:00 · 2026-08-21 12:01:37 +08:00
parent 89e85e6060
commit 09e7be729f
23 changed files with 1123 additions and 0 deletions
@@ -0,0 +1,489 @@
+---
+name: repo-standardizer
+description: Polish any GitHub repository's surface — labels (emoji rating tiers, P0–P3 priority, impact severity), issue forms, PR template, CI workflows, CODEOWNERS, rulesets, docs. Repo meta & config only — no code logic touched. Use when creating a new repo or polishing an existing one.
+---
+
+# 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"
+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:
+
+- **Replace placeholders** in `config.yml` (`OWNER/REPO` in the
+  Discussions / Security contact URLs) — see Template placeholders.
+- Write the forms in the user-chosen language (Preflight step 5): translate
+  form names, labels, descriptions, and placeholder text; `title:` prefix
+  and `labels:` values stay as-is (they must match the label taxonomy).
+
+```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).
+  The PR template has no placeholders to replace.
+
+### Module D — CI workflow
+
+Pick the workflow from the framework detection (templates/ci-*.yml —
+they trigger on `$default-branch`, so they work for any default branch
+name). Write to `.github/workflows/ci.yml`, commit, push. Keep existing
+workflows; only add `ci.yml` if none exists.
+
+- Node projects: `ci-node.yml` installs dependencies lockfile-aware
+  (`npm ci` / `pnpm install --frozen-lockfile` / `yarn install
+  --frozen-lockfile`, with plain `npm install` as fallback) — no manual
+  adjustment needed for pnpm / yarn repos.
+
+- 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 | 简体中文 >`  (简体中文 links to `README.zh.md`)
+    - `README.zh.md`:    `< English | 简体中文 >`  (English links to `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. **Replace
+  placeholders** (badge URLs, clone URL, owner credit) per Template
+  placeholders.
+- `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; **replace `OWNER/REPO`** in `SECURITY.md`'s
+  advisory link per Template placeholders).
+- `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 (**replace `PROJECT_NAME`** per Template placeholders).
+- `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 (**replace
+  `YYYY-MM-DD`** in the placeholder date line per Template placeholders).
+
+### 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` (**replace `OWNER/REPO`** and the i18n placeholder
+  per Template placeholders).
+- 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`.
+
+## Template placeholders (replace on copy)
+
+Templates stay generic — `OWNER/REPO`, `OWNER_USERNAME`, `PROJECT_NAME`,
+`YYYY-MM-DD` are placeholders the agent fills in when copying a template
+into the target repo. **Unreplaced placeholders ship broken links** (badges,
+clone URL, discussions, security advisory, CODEOWNERS handle) into the
+user's repo.
+
+| Placeholder | Replace with |
+|---|---|
+| `OWNER` | target repo owner login (user or org) |
+| `REPO` | target repo name |
+| `OWNER_USERNAME` | owner's default reviewer / team handle |
+| `PROJECT_NAME` | project display name |
+| `YYYY-MM-DD` | current date |
+
+Resolve the values once up front, then substitute in every copied file
+(`config.yml`, `README*.md`, `SECURITY.md`, `CODEOWNERS`, `AGENTS.md` /
+`CLAUDE.md`, `VISION.md`, …):
+
+```bash
+O=OWNER R=REPO N=PROJECT_NAME D=$(date +%F)
+sed -i "s|OWNER_USERNAME|$O|g; s|OWNER/REPO|$O/$R|g; s|PROJECT_NAME|$N|g; s|YYYY-MM-DD|$D|g" \
+  .github/ISSUE_TEMPLATE/config.yml README.md SECURITY.md .github/CODEOWNERS AGENTS.md
+```
+
+- Replace `OWNER_USERNAME` before `OWNER/REPO` — the former contains the
+  `OWNER` prefix, so order matters with naive `sed`.
+- Only `config.yml`, `README*.md`, `SECURITY.md`, `CODEOWNERS`, `AGENTS.md` /
+  `CLAUDE.md`, `VISION.md`, `CHANGELOG.md` carry placeholders; the issue
+  forms, PR template, CI workflows, and CoC are placeholder-free.
+- CI templates need no substitution, but **translate** their human-facing
+  text if the user chose a non-English language.
+
+## 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`, `templates/README.md`,
+`templates/README.zh.md`.