convez.ai
SkillDevOps & InfraestruturaIntermediário
gg-mo

Repo Hygiene

gg-mo/repo-hygiene

Skills para manter codebases limpos e bem documentados durante edições de IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Conjunto de skills que mantém repositórios saudáveis enquanto agentes de IA trabalham neles. Injeta práticas de higiene em momentos críticos: orientação inicial, documentação, testes, validação de commits e limpeza de código legado. Complementa fluxos de TDD e planejamento com disciplinas técnicas de baixo nível.

Instalação

$npx convez-ai gg-mo/repo-hygiene

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
3
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 6 meses
Versão
v0.1.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Garantir documentação automática em novas funções e APIs
  • Validar qualidade de commits antes de push com regras de higiene
  • Orientar agentes de IA em repositórios desconhecidos antes de editar
  • Manter arquivos compactos e refatorar quando ultrapassam limite de linhas
  • Aplicar limpeza estruturada em codebases legados em fases revisáveis

Veredito

Skill bem arquitetada que resolve um problema real: manter padrões de qualidade enquanto agentes de IA editam código. A abordagem modular com triggers em momentos específicos (não a cada keystroke) é eficiente. Recomendado para equipes que usam Claude Code, Cursor ou Codex e precisam de guardrails automáticos de higiene.

README

A tradução para o português deste README ainda está na fila.

Repo Hygiene

A small, opinionated skill set that keeps codebases healthy as coding agents work in them. Modeled on Superpowers: one bootstrap skill is injected at session start, and five sub-skills auto-trigger at the right moments.

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

  • Orient before you edit
  • Docstring what you write
  • Keep files from sprawling
  • Update docs when you change public surface
  • Test what you ship
  • Write commit messages that explain WHY
  • Verify before you commit
  • Clean up existing codebases in reviewable phases

How it works

A SessionStart hook injects 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.

The 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.

Skill catalog

SkillTriggers when
using-repo-hygieneBootstrap — loaded into every session
orienting-to-repoStarting substantive work in an unfamiliar repo
writing-docstringsWriting or modifying any function, method, class, or source file
keeping-files-smallAbout to add lines to a file already >400 lines, or your edit pushes one past that
keeping-docs-freshChanging a public API surface (renames, signature changes, new flags/routes/env vars, schema migrations)
testing-new-codeAdding business logic, branching code, public API, or fixing a bug
writing-commit-messagesDrafting any commit message
gating-commitsAbout to commit, merge, or push
cleaning-existing-codebaseUser asks to "clean up" or apply repo-hygiene to an existing project

Each 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.

Quickstart

Installation differs by harness. Pick the section for the agent you use.

Claude Code

The plugin lives in this repo. To register it as a development marketplace:

/plugin marketplace add gg-mo/repo-hygiene
/plugin install repo-hygiene@repo-hygiene-dev

Or for a local checkout:

/plugin marketplace add /path/to/repo-hygiene
/plugin install repo-hygiene@repo-hygiene-dev

Codex CLI / Codex App

The Codex manifest lives in .codex-plugin/plugin.json. Install via the plugins UI by pointing to this repo, or via:

codex plugin install https://github.com/gg-mo/repo-hygiene

Cursor

cursor plugin install https://github.com/gg-mo/repo-hygiene

The Cursor-specific hook config is at hooks/hooks-cursor.json.

OpenCode

opencode plugin install repo-hygiene

The 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.

Gemini CLI

gemini extension install gg-mo/repo-hygiene

The Gemini entry file GEMINI.md imports the bootstrap skill via @-reference. Tool-name mappings (e.g. TodoWrite → equivalent) are documented inside the bootstrap.

GitHub Copilot CLI

copilot plugin install gg-mo/repo-hygiene

The shared SessionStart hook auto-detects Copilot CLI via the COPILOT_CLI=1 environment variable and emits the SDK-standard additionalContext JSON.

Local install (no plugin)

If you don't want to register a plugin, drop the skills into your local Claude Code skills directory:

# User-level (applies to all your sessions)
cp -r skills/* ~/.claude/skills/

# Project-level (applies only inside this repo)
cp -r skills/* /path/to/your/project/.claude/skills/

You'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.

Bypass

A 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.

How the skills were built

Each sub-skill was developed via the TDD-for-skills cycle from superpowers:writing-skills:

  1. RED — dispatch a subagent with a representative scenario, no skill loaded; document its baseline behavior verbatim.
  2. GREEN — write the skill addressing the specific failure modes observed.
  3. REFACTOR — re-test with the skill loaded; tighten any new rationalizations.

The 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 for how to test changes when contributing.

Repo layout

.
├── .claude-plugin/         # Claude Code plugin manifest + marketplace
├── .codex-plugin/          # Codex CLI / App manifest
├── .cursor-plugin/         # Cursor manifest
├── .opencode/plugins/      # OpenCode JS adapter
├── hooks/
│   ├── hooks.json          # Claude Code SessionStart registration
│   ├── hooks-cursor.json   # Cursor SessionStart registration
│   ├── run-hook.cmd        # Polyglot batch/bash wrapper (Windows + Unix)
│   └── session-start       # Bash script that injects the bootstrap
├── skills/
│   ├── using-repo-hygiene/         # Bootstrap (loaded at session start)
│   ├── orienting-to-repo/
│   ├── writing-docstrings/
│   ├── keeping-files-small/
│   ├── keeping-docs-fresh/
│   ├── testing-new-code/
│   ├── writing-commit-messages/
│   ├── gating-commits/
│   └── cleaning-existing-codebase/
├── gemini-extension.json   # Gemini CLI extension manifest
├── GEMINI.md               # Gemini bootstrap entry (@-imports the skill)
├── CLAUDE.md               # Contributor guidelines
├── AGENTS.md               # → CLAUDE.md (symlink)
├── package.json            # OpenCode entry + npm metadata
└── README.md

Contributing

See 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.

License

MIT. See LICENSE.

Ver o original no GitHub

Bom para

Relacionados