trailofbits/code-improver

Code Improver

Améliorez n'importe quelle cible de code en exécutant /code-improver:improve — un workflow dynamique qui boucle entre le réviseur nommé et un sous-agent correcteur jusqu'à ce qu'une révision ne signale plus aucun constat critique ou majeur, puis nettoie ses propres résidus. La boucle, son registre et ses protections vivent dans le workflow ; cette compétence collecte les trois entrées requises par l'entrée générique et relaie le résultat.

Démarrer la boucle

L'utilisateur a fourni : $ARGUMENTS (si vide, prenez les détails de la conversation).

1. Collecter les trois entrées requises — pas de supposition

1. Cible : le chemin absolu vers le répertoire à améliorer. Résolvez les chemins relatifs par rapport au répertoire de travail ; vérifiez que le répertoire existe.
2. Réviseur : la compétence ou l'agent installé qui effectue chaque révision. L'utilisateur doit le nommer — il n'y a pas de valeur par défaut ni de réviseur intégré. Déterminez le type :
   • un agent avec espace de noms (ex. plugin-dev:skill-reviewer) → "kind": "agent"
   • une compétence installée (ex. pr-review-toolkit:review-pr) → "kind": "skill" Si le nom pourrait être l'un ou l'autre, consultez la liste des compétences de la session ; si toujours ambigu, demandez à l'utilisateur. Si aucun réviseur n'a été nommé, demandez — n'en choisissez pas un.
3. Périmètre : globs relatifs au dépôt que la boucle peut modifier. L'entrée générique le requiert explicitement ; si l'utilisateur n'en a pas fourni, proposez le répertoire cible (<chemin-relatif-au-dépôt>/**) et confirmez avant de lancer.

2. Résoudre le script de la boucle

La boucle est le workflow dynamique workflows/improve.js dans ce plugin. Lancez-le par chemin : scriptPath prend un chemin absolu résolu, et l'attribut name de l'outil Workflow résout les workflows intégrés et de projet, donc une instance installée depuis la place de marché peut ne pas répondre à code-improver:improve. Essayez dans l'ordre, le premier trouvé l'emporte — les répertoires personnels viennent avant . donc une copie installée l'emporte sur un checkout de cette place de marché :

1. Bash: ls -d -- "${CLAUDE_PLUGIN_ROOT}/workflows/improve.js"
2. Bash: ls -d -- "${CODEX_PLUGIN_ROOT}/workflows/improve.js" (si cette variable est définie à la place)
3. Bash: find ~/.claude ~/.codex . -maxdepth 7 -path '*/code-improver/workflows/improve.js' -print -quit 2>/dev/null

Utilisez le chemin exactement tel qu'imprimé. Son répertoire plugin — le chemin avec /workflows/improve.js supprimé — est pluginRoot. Si les trois échouent, essayez {name: "code-improver:improve"} une fois ; s'il est aussi indisponible, arrêtez-vous et dites que la boucle n'a pas pu être localisée. N'assemblez pas un chemin à la main et n'improvisez pas la boucle.

3. Invoquer le workflow

Exécutez-le avec l'outil Workflow, {scriptPath: "<le chemin de l'étape 2>", args: {...}} :

{
  "target": "<chemin absolu de la cible>",
  "reviewer": { "kind": "agent|skill", "name": "<nom-avec-espace-de-noms>", "notes": "<ce que le réviseur doit savoir sur la cible>" },
  "scope": ["<globe-relatif-au-dépôt>/**"],
  "pluginRoot": "<le répertoire plugin de l'étape 2>",
  "maxRounds": 5
}

• maxRounds seulement si l'utilisateur a demandé une limite différente.
• pluginRoot permet à l'exécution de trouver son collecteur de métriques ; omettez la clé seulement si l'étape 2 a trouvé le workflow par son nom — le workflow se cherche alors lui-même.
• finalize ({"version_bump": bool, "narration_strip": bool, "docs_pass": bool}) seulement pour remplacer les valeurs par défaut : incrémentation de version lorsque la cible se trouve dans un plugin, suppression de narration et passe de documentation toujours.
• decision seulement en cas de continuation (ci-dessous).

Le workflow s'exécute en arrière-plan et ne nécessite pas de supervision : il révise, corrige, re-révise, vérifie le périmètre après chaque tour de correction, et ne peut se terminer que sur une révision propre. Il ne commit jamais ; toutes les modifications restent dans l'arbre de travail.

Si l'outil Workflow est indisponible ou refusé, arrêtez-vous et dites-le. N'improvisez pas la boucle en ligne avec des modifications directes — le registre, la protection du périmètre et les garanties d'escalade vivent dans le workflow, et une imitation en ligne n'en a aucune.

Si le résultat est halted: "reviewer-unavailable", relaiez-le et arrêtez-vous. Le réviseur nommé n'est pas installé dans cette session ; dites à l'utilisateur quel plugin le fournit et relancez après installation. Ne révisez pas la cible vous-même.

Ne terminez pas votre tour pendant que la boucle tourne. L'outil Workflow renvoie un identifiant de tâche immédiatement ; le résultat arrive plus tard. Dans une session interactive, la notification de fin vous ré-invoque — attendez-la. Dans une exécution non interactive (script, CI, évaluation), il n'y a pas de tour ultérieur : s'arrêter abandonne la boucle en plein milieu d'un tour, donc après avoir lancé, interrogez la tâche (TaskOutput avec l'identifiant de tâche retourné, ou dormir-et-revérifier) jusqu'à ce qu'elle se termine, puis relaiez le résultat. Une session qui répond "la boucle tourne, je ferai un rapport plus tard" a perdu l'exécution.

Relayer le résultat

Le workflow renvoie un résultat structuré. Rapportez-le honnêtement — les distinctions sont importantes :

• converged: true — la dernière action était une révision avec zéro constat critique ou majeur. Rapportez les tours utilisés, les constats mineurs restants (open_minor_count) et les chemins des artefacts (ledger_path, metrics).
• capped: true — le budget de corrections est épuisé et la révision FINALE a encore trouvé des problèmes bloquants. Dites clairement : plafonné, PAS convergé, et listez open_blocking. Ne présentez pas cela comme un succès.
• escalation — la boucle a détecté qu'elle ne convergeait pas (constats récurrents, comptages non décroissants, ou une correction déplaçant un problème). Relayez le message d'escalade et les identifiants des constats à l'utilisateur : cela nécessite une décision de conception, pas plus de tours.
• halted — une protection s'est déclenchée (violation du périmètre, nouveaux fichiers non enregistrés, réviseur mort ou indisponible, ou une passe de finalisation dont ses propres modifications ont échoué au contrôle qui la suit). Relayez les chemins dans violations/new_untracked_files, les sites dans finalize_regressions, et les notes.
• notes voyagent toujours avec le résultat — mettez-les en évidence ; elles incluent des avertissements sonores comme "un dépôt git a été initialisé".

Continuer après une escalade

La boucle s'arrête sur escalade par conception. Lorsque l'utilisateur décide, démarrez une nouvelle exécution avec la même target et le même reviewer plus :

{ "decision": "<la décision de l'utilisateur, textuelle>" }

La nouvelle exécution recharge le registre sur disque, donc chaque constat, rejet et verdict est repris — les tours redémarrent, la re-dérivation n'est pas nécessaire.

Pour arrêter une boucle en cours d'exécution, arrêtez la tâche du workflow (TaskStop) ; le registre sur disque est à jour jusqu'au dernier tour et une nouvelle exécution reprendra à partir de là.

Quand NE PAS utiliser

• Une compétence Claude Code : utilisez l'entrée skill-improver — elle câble le bon réviseur
• Une branche / pull request : utilisez l'entrée pr-improver — elle dérive le périmètre du diff
• Révision unique : appelez le réviseur directement ; la valeur de la boucle est l'itération
• Corrections rapides uniques : modifiez le fichier directement