{
  "markdown": "# Repo Hygiene\n\nA small, opinionated skill set that keeps codebases healthy as coding agents work in them. Modeled on [Superpowers](https://github.com/obra/superpowers): one bootstrap skill is injected at session start, and five sub-skills auto-trigger at the right moments.\n\nIt complements Superpowers — Superpowers gives you the workflow disciplines (brainstorming, TDD, debugging, planning); `repo-hygiene` gives you the lower-level hygiene that should hold across every change:\n\n- Orient before you edit\n- Docstring what you write\n- Keep files from sprawling\n- Update docs when you change public surface\n- Test what you ship\n- Write commit messages that explain WHY\n- Verify before you commit\n- Clean up existing codebases in reviewable phases\n\n## How it works\n\nA SessionStart hook injects [`skills/using-repo-hygiene/SKILL.md`](skills/using-repo-hygiene/SKILL.md) into the system context of every conversation. That bootstrap tells the agent which sub-skill applies at which moment. The agent then invokes the relevant sub-skill via the harness's `Skill` (or equivalent) tool when its trigger fires.\n\nThe skills don't trigger on every keystroke — they trigger at meaningful moments: starting work in a new repo, writing a new function, changing a public API, committing.\n\n## Skill catalog\n\n| Skill | Triggers when |\n|---|---|\n| [`using-repo-hygiene`](skills/using-repo-hygiene/SKILL.md) | Bootstrap — loaded into every session |\n| [`orienting-to-repo`](skills/orienting-to-repo/SKILL.md) | Starting substantive work in an unfamiliar repo |\n| [`writing-docstrings`](skills/writing-docstrings/SKILL.md) | Writing or modifying any function, method, class, or source file |\n| [`keeping-files-small`](skills/keeping-files-small/SKILL.md) | About to add lines to a file already >400 lines, or your edit pushes one past that |\n| [`keeping-docs-fresh`](skills/keeping-docs-fresh/SKILL.md) | Changing a public API surface (renames, signature changes, new flags/routes/env vars, schema migrations) |\n| [`testing-new-code`](skills/testing-new-code/SKILL.md) | Adding business logic, branching code, public API, or fixing a bug |\n| [`writing-commit-messages`](skills/writing-commit-messages/SKILL.md) | Drafting any commit message |\n| [`gating-commits`](skills/gating-commits/SKILL.md) | About to commit, merge, or push |\n| [`cleaning-existing-codebase`](skills/cleaning-existing-codebase/SKILL.md) | User asks to \"clean up\" or apply repo-hygiene to an existing project |\n\nEach `SKILL.md` is the canonical source — read those for the rules. The bootstrap stays lightweight so it can ride in every session without burning context.\n\n## Quickstart\n\nInstallation differs by harness. Pick the section for the agent you use.\n\n### Claude Code\n\nThe plugin lives in this repo. To register it as a development marketplace:\n\n```bash\n/plugin marketplace add gg-mo/repo-hygiene\n/plugin install repo-hygiene@repo-hygiene-dev\n```\n\nOr for a local checkout:\n\n```bash\n/plugin marketplace add /path/to/repo-hygiene\n/plugin install repo-hygiene@repo-hygiene-dev\n```\n\n### Codex CLI / Codex App\n\nThe Codex manifest lives in `.codex-plugin/plugin.json`. Install via the plugins UI by pointing to this repo, or via:\n\n```bash\ncodex plugin install https://github.com/gg-mo/repo-hygiene\n```\n\n### Cursor\n\n```bash\ncursor plugin install https://github.com/gg-mo/repo-hygiene\n```\n\nThe Cursor-specific hook config is at `hooks/hooks-cursor.json`.\n\n### OpenCode\n\n```bash\nopencode plugin install repo-hygiene\n```\n\nThe OpenCode adapter is `.opencode/plugins/repo-hygiene.js`. It registers `skills/` with OpenCode's skill loader and transforms the first user message of each session to include the bootstrap.\n\n### Gemini CLI\n\n```bash\ngemini extension install gg-mo/repo-hygiene\n```\n\nThe Gemini entry file [`GEMINI.md`](GEMINI.md) imports the bootstrap skill via `@`-reference. Tool-name mappings (e.g. `TodoWrite` → equivalent) are documented inside the bootstrap.\n\n### GitHub Copilot CLI\n\n```bash\ncopilot plugin install gg-mo/repo-hygiene\n```\n\nThe shared SessionStart hook auto-detects Copilot CLI via the `COPILOT_CLI=1` environment variable and emits the SDK-standard `additionalContext` JSON.\n\n### Local install (no plugin)\n\nIf you don't want to register a plugin, drop the skills into your local Claude Code skills directory:\n\n```bash\n# User-level (applies to all your sessions)\ncp -r skills/* ~/.claude/skills/\n\n# Project-level (applies only inside this repo)\ncp -r skills/* /path/to/your/project/.claude/skills/\n```\n\nYou'll lose the SessionStart auto-bootstrap (so `using-repo-hygiene` won't auto-load), but the sub-skills will still be discoverable by the `Skill` tool when their descriptions match.\n\n## Bypass\n\nA user can suppress any hygiene skill for one turn by including `#hygiene-skip <reason>` in their message. The agent acknowledges the bypass and proceeds. This is for the cases where the skill would be genuinely wrong — not a way to disable hygiene permanently.\n\n## How the skills were built\n\nEach sub-skill was developed via the TDD-for-skills cycle from [`superpowers:writing-skills`](https://github.com/obra/superpowers/tree/main/skills/writing-skills):\n\n1. **RED** — dispatch a subagent with a representative scenario, no skill loaded; document its baseline behavior verbatim.\n2. **GREEN** — write the skill addressing the specific failure modes observed.\n3. **REFACTOR** — re-test with the skill loaded; tighten any new rationalizations.\n\nThe baseline scenarios surfaced honest admissions like *\"without this nudge I'd treat 'ship it' as authorization to commit whatever's staged\"* and *\"user said commit, so commit.\"* The skills are tuned against those exact failure modes. See [CLAUDE.md](CLAUDE.md) for how to test changes when contributing.\n\n## Repo layout\n\n```\n.\n├── .claude-plugin/         # Claude Code plugin manifest + marketplace\n├── .codex-plugin/          # Codex CLI / App manifest\n├── .cursor-plugin/         # Cursor manifest\n├── .opencode/plugins/      # OpenCode JS adapter\n├── hooks/\n│   ├── hooks.json          # Claude Code SessionStart registration\n│   ├── hooks-cursor.json   # Cursor SessionStart registration\n│   ├── run-hook.cmd        # Polyglot batch/bash wrapper (Windows + Unix)\n│   └── session-start       # Bash script that injects the bootstrap\n├── skills/\n│   ├── using-repo-hygiene/         # Bootstrap (loaded at session start)\n│   ├── orienting-to-repo/\n│   ├── writing-docstrings/\n│   ├── keeping-files-small/\n│   ├── keeping-docs-fresh/\n│   ├── testing-new-code/\n│   ├── writing-commit-messages/\n│   ├── gating-commits/\n│   └── cleaning-existing-codebase/\n├── gemini-extension.json   # Gemini CLI extension manifest\n├── GEMINI.md               # Gemini bootstrap entry (@-imports the skill)\n├── CLAUDE.md               # Contributor guidelines\n├── AGENTS.md               # → CLAUDE.md (symlink)\n├── package.json            # OpenCode entry + npm metadata\n└── README.md\n```\n\n## Contributing\n\nSee [CLAUDE.md](CLAUDE.md). Short version: skills are documentation that shapes agent behavior. Don't edit them without the RED → GREEN → REFACTOR cycle. One problem per PR.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n",
  "bytes": 7128,
  "sha": "6d6b7491a2b478065675cf655d9c5559bb0a74aef4948cf4cc2c41450bdd1c36",
  "repo_slug": "gg-mo/repo-hygiene",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_gg_mo_repo_hygiene_repo_hygiene_4dd468d7/readme"
}