justinramos101/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 réside dans skill.json ; ce fichier ne sert qu'au routage à l'exécution.

Produit : un change-plan.md (FAIRE), un audit-report.md accompagné d'un registre de constats + 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 bulle d'aide pour se rattraper. Par conséquent, le critère 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, non espérée ; la limite de confiance fermée par défaut. Il se situe au-dessus du socle client HTTP que possèdent dx-audit / dx-design, sans jamais le remplacer.

Activation

• Invocation nue ("use agent-dx", "start") : afficher un menu compact : choix du mode (guidé / pilote automatique / questionnez-moi ?) et intentions numérotées depuis le routeur. Attendre. Aucune inspection de fichier, aucun appel réseau, aucune écriture.
• Invocation concrète avec intention et surface déductible : passer directement à l'étape 3.
• Invocation ambiguë : poser une question — par ex., "Auditez-vous un SDK, un schéma d'outil, une enveloppe de sortie structurée ou une surface de télémétrie ?" ou "S'agit-il d'une révision contrat/reprise ou d'un audit de limite de confiance ?"

Flux de travail

1. Choisir l'intention. Charger references/intent-router.csv ; faire correspondre do, review ou design. 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 REVOIR. Ambigu → demander une fois avec le menu.
3. Charger le contexte fondé. Charger uniquement le playbook de la ligne choisie ainsi que ses core_refs. Ne pas charger d'autres playbooks (la ligne review/all n'en porte aucun — chaque agent de surface charge le sien ; voir l'étape 6).
4. Identifier la personne cible à partir de references/core/personas.md.
5. Puis calibrer selon l'échelle du projet (REVOIR / CONCEVOIR) conformément à references/calibration.md : en dessous de Critique, 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 (quand il grandit). Le palier alimente l'émission, jamais la gravité.
6. Lancer les lentilles en parallèle (REVOIR par défaut lorsqu'autorisé) : une surface par agent pour all ; sinon les trois lentilles ci-dessous. Retour 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 gravité 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, une gravité 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 uniquement après que chaque règle de vérification est réussie. Sinon, écrire le registre à docs/audits/agent-dx-findings-ledger-<YYYY-MM-DD>-<scope-slug>.md et l'état de workflow à docs/audits/agent-dx-workflow-state-<YYYY-MM-DD>-<scope-slug>.json (replier vers audit-artifacts/agent-dx-... si docs/audits/ n'est pas accessible en écriture). Rapporter les deux chemins ; garder les feuilles de route, les issues et les modifications non liées au suivi en option.

Mauvaise direction ? Si l'utilisateur dit que ce n'est pas ce qu'il voulait, revenir à l'étape 1 (Choisir l'intention) — ne pas corriger dans la mauvaise direction. Reformuler la compréhension corrigée et replanifier.

Modes

Brouillon guidé (par défaut), Pilote automatique, Questionnez-moi — voir references/modes.md. Proposer lors de l'invocation nue ; utiliser Brouillon guidé par défaut pour les invocations concrètes.

Exigences de sortie

Chaque sortie nomme l'intention, la/les surface(s), la personne, le/les playbook(s) appliqué(s) et les sources de fondement de skill.json ; REVOIR ajoute la gravité + la vérification pour chaque constat et le palier du projet. Nommer les garanties de consommabilité agent que vous choisissez délibérément de NE PAS ajouter (YAGNI), pas seulement celles que vous ajoutez.

Délégation aux sous-agents

Par défaut pour REVOIR lorsque la délégation est autorisée ; ignorer les travaux de petite taille ou confidentiels. 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érifier, erreurs façonnées pour la reprise, reprise sémantique, boucle bornée), confiance-et-isolement (injection de métadonnées d'outil, points de contrôle de garde-fou, murs d'identification, rédaction de contenu) — conformément à references/subagent-dispatch.md, puis synthétiser, en ordonnant par gravité.

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 des trois lentilles et synthèse.
• references/core/*.md — gravité, score, personnes, glossaire.
• 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.