CommunityRédaction et éditiongithub.com

maxgfr/ultraeval

Évaluez une compétence ou une base de code avec un workflow multi-agent, ancrez chaque constatation dans un véritable fichier:ligne et générez un backlog de correctifs TDD exploitable par une IA. Une compétence d'agent pour skills.sh.

Qu'est-ce que ultraeval ?

ultraeval est un outil d'évaluation automatisé conçu pour analyser en profondeur des compétences logicielles (skills) ou des bases de code complètes. Il orchestre un workflow multi-agent structuré qui planifie, exécute des tests, juge les résultats et produit un backlog de correctifs priorisé, chaque constatation étant impérativement ancrée à un fichier et une ligne réels du code cible. L'outil utilise un moteur déterministe léger pour générer le workflow et les contrats de sous-agents, puis applique une double vérification : une porte structurelle (check) qui valide l'existence des lignes citées, et une porte sémantique (verify) qui vérifie que le contenu soutient réellement la réclamation. Les sorties principales sont un fichier BACKLOG.json exploitable par une IA et des cartes TDD (FIX-*.md) pour chaque correctif, prêtes à être exécutées selon le cycle rouge→vert→refactor. ultraeval est conçu pour fonctionner via des appels CLI simples (node <skill-dir>/scripts/ultraeval.mjs <commande>) et s'intègre avec les environnements de workflow des agents (comme Workflow()). Il offre trois modes : audit (défauts), improve (opportunités) ou deep (les deux), et génère un tableau de bord de notation index.html. Cet outil est essentiel pour les développeurs qui souhaitent auditer la qualité d'un code, valider une compétence avant de l'adopter ou régulièrement vérifier l'absence de régressions après des modifications.

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add maxgfr/ultraeval

Installed? Explore more Rédaction et édition skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

ultraeval : évaluer une compétence ou une base de code → des documents de correctifs ancrés et exploitables par IA

Le markdown est le programme. Un petit moteur déterministe crée l'environnement d'exécution, génère le workflow multi-agent et impose une porte d'ancrage ; vous (avec des sous-agents déployés) effectuez les recherches, les jugements et la rédaction. Chaque constatation doit aboutir à un véritable fichier:ligne dans la cible — la porte rejette celles qui sont hallucinées — et la sortie est un backlog priorisé ainsi que des cartes TDD par correctif qu'un modèle peut implémenter suivant le cycle rouge→vert→refactor.

Quand l'utiliser

  • « Évaluer / auditer / noter / classer cette compétence (ou ce dépôt) » ; « est-elle prête pour la production / répond-elle aux attentes ? »
  • « Examiner cette base de code et me donner un plan de correctifs / un backlog TDD. »
  • Vérifier l'absence de régressions dans vos propres compétences après des modifications, ou évaluer une compétence tierce avant de lui faire confiance.

Pas pour : une revue de code rapide d'un seul fichier (il suffit de le lire) ; exécuter la suite de tests de la cible elle-même (faites-le directement).

La boucle

init → plan → run(recherche → plan-de-test → exécution+portes → jugement → résultats) → verify → backlog(TDD) → score → render

Tout est un simple appel node <skill-dir>/scripts/ultraeval.mjs <cmd>. Le déploiement de sous-agents est une optimisation encodée par le workflow généré — jamais une exigence.

Entrées à confirmer

  • Cible — un chemin vers la compétence/le dépôt à évaluer (ou une URL git que l'utilisateur a déjà clonée localement).
  • Type (Kind) — skill ou codebase (détection automatique : un SKILL.md ⇒ skill). Surchargez avec --kind.
  • Catégorie — par ex. « agent skill », « CLI », « bibliothèque », « application web », « outil de sécurité ». Oriente la grille d'évaluation de départ.
  • Mode — audit (défauts, par défaut) · improve (opportunités d'amélioration ancrées) · deep (les deux). Définissez avec --mode.

Modes et découverte d'améliorations

ultraeval trouve deux types d'éléments, tous deux ancrés et vérifiés :

  • Défauts (audit, deep) — quelque chose ne va pas ; chacun cite un véritable fichier:ligne.
  • Opportunités (improve, deep) — une piste d'amélioration ancrée (santé interne et produit/capacité), notée selon impact × effort. Découverte par analyze (points chauds déterminés/dépendances/churn/lacunes de test) → brainstorm (perspectives divergentes) → brainstorm --rank (intègre les opportunités classées dans findings.json en tant que kind:"opportunity"). La même porte s'applique — une opportunité doit s'ancrer dans du code/des métriques réels, pour ne jamais devenir un vague « tout réécrire ». Voir references/analysis-playbook.md.

Pour les modes improve/deep, l'étape plan ajoute les phases Analyze et Brainstorm au workflow généré.

Procédure

1. Créer l'environnement d'exécution.

node <skill-dir>/scripts/ultraeval.mjs init --target <CHEMIN> --out <RUN> [--kind skill|codebase] [--category "<c>"]

Écrit eval.config.json avec les dimensions de départ (voir references/rubric-library.md).

2. Générer le workflow + les contrats des sous-agents.

node <skill-dir>/scripts/ultraeval.mjs plan --run <RUN>

Produit <RUN>/eval.workflow.mjs (un Workflow multi-agent prêt à être lancé, avec les chemins absolus du moteur et de la cible intégrés), <RUN>/agents/*.md (les contrats de répartition), TEST-PLAN.template.md, dimensions.json, findings.schema.json.

3. Exécuter l'évaluation. Lancez le workflow généré avec l'outil Workflow de votre infrastructure : Workflow({ scriptPath: "<RUN>/eval.workflow.mjs" }). Il enchaîne Research → TestPlan → Execute → Findings → Gate → Judge → Results et s'invoque lui-même les portes du moteur. Si vous n'avez pas d'infrastructure Workflow, exécutez les étapes manuellement : lisez chaque agents/<stage>.md et répartissez un sous-agent selon le contrat. Voir references/orchestration.md. Chaque sous-agent reçoit le chemin ABSOLU <skill-dir>/scripts/ultraeval.mjs — il a son propre répertoire de travail et ne peut pas résoudre un chemin relatif (plan intègre déjà le chemin absolu dans le workflow).

4. Ancrer chaque constatation. Consolidez les résultats dans <RUN>/findings.json (schéma : references/gate-contract.md). Chaque constatation cite evidence[].ref comme chemin:ligne dans la cible ou run:relpath#Lnn dans un journal produit. Ensuite :

node <skill-dir>/scripts/ultraeval.mjs check --run <RUN>

Corrigez findings.json jusqu'à ce qu'il se termine avec le code 0 — réparez ou supprimez les constatations non ancrées ; n'affaiblissez jamais la porte.

5. Vérifier (porte de sortie au vérificateur).

node <skill-dir>/scripts/ultraeval.mjs verify --run <RUN>          # écrit VERIFY.todo.json
# remplissez chaque verdict : supported | partial | refuted | unsupported (utilisez des sous-agents sceptiques ; --shards N --shard i pour paralléliser)
node <skill-dir>/scripts/ultraeval.mjs verify --run <RUN> --apply <verdicts.json>
node <skill-dir>/scripts/ultraeval.mjs check --run <RUN> --semantic --require-verify   # porte de sortie — ne présentez jamais avant que cela ne réussisse

Une constatation refuted doit être marquée dismissed. Une constatation supported/partial survit.

6. Corriger — le livrable.

node <skill-dir>/scripts/ultraeval.mjs backlog --run <RUN> --tdd

Produit BACKLOG.json (une liste de tâches prioritaire et exploitable par une machine qu'un agent en aval peut exécuter), REMEDIATION.md, et une carte TDD fixes/FIX-*.md par constatation confirmée — chacune avec une spécification ROUGE de test qui échoue d'abord, le changement VERT et une commande VERIFY. Voir references/tdd-remediation.md.

7. Noter + générer le rendu + présenter.

node <skill-dir>/scripts/ultraeval.mjs score --run <RUN>           # judges.jsonl + dimensions -> scorecard.json (0-100 + meets-expectations)
node <skill-dir>/scripts/ultraeval.mjs render --run <RUN>          # index.html + index.md tableau de bord (affiche le verdict)

score réduit le judges.jsonl du panel de juges et les dimensions de configuration à un verdict pondéré ; une constatation P0 active (ou tout juge votant non, ou un score en dessous du seuil) fixe meets-expectations à faux. Présentez le verdict, le titre du backlog P0/P1 et les chemins (RESULTS.md, BACKLOG.json, fixes/) qu'un agent de correction doit consommer.

Codes de sortie de la CLI : 0 ok / porte passée · 1 porte échouée (check/verify) · 2 erreur d'utilisation ou d'exécution.

8. (optionnel) Exécuter les correctifs. Remettez chaque fixes/FIX-*.md à un agent de construction pour implémenter le TDD — la carte est écrite de manière à pouvoir passer par rouge→vert→refactor sans avoir à redériver le problème.

Le contrat d'ancrage

Une constatation n'est digne de confiance que si ses preuves sont résolues. check ouvre chaque chemin:ligne dans la cible et confirme que la ligne existe et est dans les limites ; une ligne obsolète ou inventée est un échec dur. verify demande ensuite à un sceptique si le contenu cité soutient réellement l'affirmation. Cette double porte (structurelle + sémantique) est l'essence même de l'outil — grammaire complète et règles de réussite/échec dans references/gate-contract.md.

Méthode et grilles d'évaluation

  • references/eval-playbook.md — la méthode recherche→plan-de-test→exécution→jugement→résultats, et comment construire une grille notée par dimension.
  • references/orchestration.md — le workflow généré, les contrats de répartition des sous-agents et l'invariant du <skill-dir> absolu pour le déploiement.
  • references/gate-contract.md — schéma de findings.json, grammaire des références de preuves et ce qui fait exactement réussir ou échouer check/verify.
  • references/tdd-remediation.md — la forme de BACKLOG.json et le format des cartes TDD fixes/FIX-*.md.
  • references/rubric-library.md — dimensions de départ par catégorie de cible.
  • references/analysis-playbook.md — les signaux analyze, les perspectives de brainstorming et comment les opportunités restent ancrées.

Sécurité

  • ultraeval lit seulement la cible et écrit dans <RUN>. Il n'exécute jamais le code de la cible ; le sous-agent exécuteur peut exécuter les propres commandes de la cible (tests, portes) — isolez les dépôts non fiables.
  • clean --run <RUN> supprime uniquement les artefacts dérivés de la porte et du rendu et conserve les livrables ; --all supprime toute l'exécution.

Skills associés