Thulr/agent-skill-kit

Agent DX

L'expérience développeur d'une surface où un agent IA est le développeur — un SDK, un outil, une sortie structurée, une enveloppe d'erreur ou une télémétrie qu'un agent consomme pour construire ou agir. La provenance se trouve dans skill.json ; ce fichier n'est qu'un routage d'exécution.

Produit : un change-plan.md (FAIRE), un audit-report.md plus un registre des constats et un état de workflow lorsqu'il est suivi (REVOIR), ou un design-doc.md / refactor-runbook.md / explanation.md (CONCEVOIR).

Principe fondamental

Un agent consomme la surface seul, à la vitesse de la machine, sans aide contextuelle. Le niveau d'exigence pour tout SDK, outil, erreur ou span est de savoir si un consommateur stochastique peut l'analyser, s'en remettre et ne pas en être affecté : des contrats typés plutôt que de la prose ; une récupération conçue dès le départ, pas simplement espérée ; la frontière de confiance fermée par défaut. Il se situe au-dessus du socle client HTTP que dx-audit / dx-design possèdent, sans jamais le remplacer.

Activation

• Invocation nue ("utilise agent-dx", "revise notre surface d'outils MCP", "démarre") : charger references/intent-router.csv, afficher le menu d'intention, proposer le mode. Attendre. Aucune inspection de fichier, appel réseau ou écriture.
• Invocation concrète avec intention et surface déductibles : passer à l'étape 3.
• Périmètre ambigu : poser une seule question de blocage nommant l'intention ou la surface candidate ; ne pas inspecter d'abord les systèmes privés.

Workflow

1. Choisir l'intention. Charger references/intent-router.csv ; faire correspondre à faire, revoir, ou concevoir. Ambigu → demander une fois.
2. Choisir la surface. Charger references/intents/<intent>.csv ; faire correspondre une ou plusieurs de sdk-design, tools-and-mcp, structured-output, errors-and-retry, sdk-telemetry — ou all pour un déploiement en éventail de REVUE. Ambigu → demander une fois avec le menu.
3. Charger le contexte ancré. Charger uniquement le playbook de la ligne choisie ainsi que ses core_refs. Ne pas charger les autres playbooks (la ligne review/all n'en porte aucun — chaque agent de surface charge le sien ; voir l'étape 6).
4. Identifier la persona cible à partir de references/core/personas.md.
5. Puis calibrer selon l'échelle du projet (REVOIR / CONCEVOIR) selon references/calibration.md : en dessous de Porteur de charge, réduire le périmètre, regrouper les lacunes de même mécanisme en un seul constat systémique, et séparer Maintenant vs Plus tard (à mesure qu'il grandit). Le niveau alimente l'émission, jamais la sévérité.
6. Déployer les lentilles en parallèle (REVOIR par défaut lorsque permis) : une surface par agent pour all ; sinon les trois lentilles ci-dessous. Repli séquentiel si aucune primitive de délégation.
7. Appliquer le playbook. Utiliser les heuristiques étiquetées pour l'intention. Pour REVOIR, noter chaque surface de 0 à 10 (references/core/score-rubric.md) ; synthétiser les constats des lentilles, en préservant les désaccords comme questions ouvertes. Appliquer la sévérité et les identifiants stables AGENT-DX-<surface>-NNN (references/core/severity-rubric.md) : AGENT-DX-SDK, AGENT-DX-TOOL, AGENT-DX-OUT, AGENT-DX-ERR, AGENT-DX-TEL.
8. Émettre. FAIRE → templates/change-plan.md. REVOIR → templates/audit-report.md. CONCEVOIR → templates/design-doc.md (forme), templates/refactor-runbook.md (séquence de durcissement), ou templates/explanation.md (expliquer un principe).
9. Créer, reprendre ou fermer l'état de suivi (REVOIR). Pour un audit avec 7 constats ou plus, toute sévérité 3–4, ou une demande de sauvegarde/suivi/clôture, charger references/trackable-findings.md. Si la demande nomme un registre existant, un état de workflow, une PR ou un identifiant AGENT-DX-*, lire d'abord l'état sauvegardé ; mettre à jour les statuts seulement après que chaque règle de vérification réussit. Sinon, écrire le registre dans docs/audits/agent-dx-findings-ledger-<YYYY-MM-DD>-<scope-slug>.md et l'état de workflow dans docs/audits/agent-dx-workflow-state-<YYYY-MM-DD>-<scope-slug>.json (replier sur audit-artifacts/agent-dx-... si docs/audits/ est inaccessible en écriture). Reporter les deux chemins ; garder les feuilles de route, les issues et les modifications non liées au suivi en opt-in.

Modes

Brouillon Guidé (par défaut), Pilote Automatique, Interroge-Moi — voir references/modes.md. Proposer à l'invocation nue ; utiliser Brouillon Guidé par défaut pour les invocations concrètes.

Exigences de sortie

Chaque sortie nomme l'intention, la ou les surfaces, la persona, le ou les playbooks appliqués et les sources d'ancrage de skill.json ; REVOIR ajoute la sévérité + la vérification par constat et le niveau du projet. Nommer les garanties de consommabilité par agent que vous NE mettez PAS délibérément en œuvre (YAGNI), pas seulement celles que vous mettez.

Répartition en sous-agents

Par défaut pour REVOIR lorsque la délégation est permise ; ignorer les tâches mineures ou liées à des secrets. Lancer trois lentilles en parallèle — contrat-et-schéma (schémas typés à partir du code, enveloppe d'erreur stable, sortie validée), récupération-agent (stop+vérifie, erreurs adaptées au retry, retry sémantique, boucle bornée), confiance-et-isolation (injection de métadonnées d'outil, points de contrôle de garde-fou, murs d'identification, masquage de contenu) — selon references/subagent-dispatch.md, puis synthétiser en ordonnant par sévérité.

Carte des références

• references/intent-router.csv + references/intents/<intent>.csv — les deux couches de routage.
• references/playbooks/<surface>.md — sdk-design, tools-and-mcp, structured-output, errors-and-retry, sdk-telemetry.
• references/subagent-dispatch.md — invites et synthèse des trois lentilles.
• references/core/{severity-rubric,score-rubric,personas,glossary}.md — échelles, public, termes.
• references/{calibration,trackable-findings,modes}.md — partagés (liens symboliques).
• templates/*.md — change-plan, audit-report, design-doc, refactor-runbook, explanation, plus les artefacts de suivi partagés.
• evals/, skill.json — portes et provenance.