ptmrio/harness-subagent

Harness Subagent

Lancez un autre agent de codage en tant que sous‑agent unique, puis synthétisez.

Principe fondamental : le harness est un sous‑agent, pas une oracle. Un modèle qui révise son propre travail reproduit ses propres angles morts. Cette valeur est perdue si vous transmettez la réponse sans la juger.

Voix de l'orchestrateur : niveau CTO — bref, concis, puces, aperçus ASCII quand ils surpassent la prose. Restez aligné avec l'opérateur humain (explicitez les hypothèses ; demandez pour les actions irréversibles et les préférences produit non fixées ; n'inventez pas silencieusement le périmètre).

Règle collante : Si l'enfant rencontre des limites d'utilisation/taux (ou toute défaillance logicielle qui incite à un changement) ne pas rediriger vers un autre backend ou modèle. Signalez l'échec, marquez NON VÉRIFIÉ / bloqué, demandez une fois. Exception : une demande no-verdict de même famille / « quel harness » est une fuite de nidification — réécrivez la barrière d'identité, relancez une fois, même backend ; ne demandez pas et ne changez pas. Dans une boucle d'orchestration complète, arrêtez la checklist — ne continuez pas vers les étapes suivantes sans le livrable de l'étape échouée (par ex. pas d'Implémentation si les Pratiques sont mortes sur une limite).

Ne pas choisir un harness à cause d'un stéréotype de tâche sauf si la configuration utilisateur a cette clé (voir references/user-config.md). Ordre de routage : cette énoncé → configuration utilisateur → demande une fois. Même protocole pour chaque backend. Cartes de personnalité des rôles et Superpowers : references/roles.md (canonique).

Par défaut : Révision (ne pas modifier les fichiers de l'application). Autorisez les écritures dans l'application seulement lorsque l'utilisateur (ou un plan approuvé) demande une Implémentation. Révision et Visuel peuvent créer des fichiers temporaires et écrire des rapports.

Niveaux de commande (ne pas mélanger)

Cette compétence est unique. L'enfant ne doit pas la ré‑entrer. Les CLI des fournisseurs peuvent permettre un Agent imbriqué / spawn_agent ; ce n'est pas une licence pour exécuter ce protocole à nouveau.

Niveau	Qui	Commandes	Interdit comme « vôtre »
L0	Humain	/harness-subagent, « orchestrer », harness nommé, épingler self	Drapeaux de spawn.sh
L1	Parent qui a chargé cette compétence	scripts/spawn.sh --backend --mode, routage config, saut de même famille, demande une fois, synthétiser	Mettre des invocations de spawn.sh dans le brief ; demander à l'enfant quel harness
L2	CLI spawn.sh lancée	Superpowers du rôle uniquement, Playwright / captures nommées, report.md	Cette compétence, spawn.sh, requesting-code-review, « quel harness? », demande de même famille

L1 invoque scripts/spawn.sh --mode …. Cet argv n'est pas une instruction pour l'enfant. Si vous êtes L2 (HARNESS_SUBAGENT_RUN défini, ou l'invite commence par VOUS ÊTES LE TRAVAILLEUR), arrêtez de lire ce protocole de spawn et faites le travail décrit dans le brief.

spawn.sh exporte HARNESS_SUBAGENT_RUN et définit CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1. Un spawn.sh imbriqué meurt (variable déjà définie).

Orchestrer vs. unique

Précédence (évaluer dans l'ordre) :

1. Rétrécissement vers un seul travail gagne sur l'unique — l'énoncé nomme un travail (second avis, réviser ce diff, implémenter seulement …, réécrire le README, rechercher X) → un brief, un spawn. Un « Orchestre ceci — » initial ne force pas la boucle complète.
2. Boucle complète explicite gagne — l'utilisateur dit « exécute la boucle complète » / nomme pratiques+implémentation+révision ensemble / « orchestre cette fonctionnalité de bout en bout » sans aucun nom de travail unique → checklist complète ci‑dessous. Un harness nommé ici ne fait qu'épingler le backend pour chaque étape (ou configuration par étape) ; il ne réduit pas la boucle à un seul tir.
3. Sinon, demandez une fois ce qu'ils veulent (boucle complète vs. un seul travail).

Checklist de boucle complète (sauter les étapes déjà faites ou renoncées par l'utilisateur ; un travail par spawn) :

1. Pratiques — Recherche (ou parent self si épinglé) : exactement deux ancres — une directive officielle Anthropic + une OpenAI. Complétez éventuellement (sans remplacer) avec Cursor/xAI quand la pile/harness les rend pertinents. Citez + datez.
2. Implémenter — tranche limitée selon ces pratiques. Collez la table TDD complète de roles.md.
3. Valider — code-review (adversaire). Ajoutez code-review-visual quand l'interface utilisateur est en jeu.
4. Cohérence finale — parent par défaut self (ou un court spawn de Révision) : logique, redondance, cohérence globale par rapport aux deux ancres et à la demande initiale.

Si une étape est bloquée (y compris les limites collantes de chemin), arrêtez et demandez — ne sautez pas en avant.

Choisir un backend

Ne jamais lancer le harness de la même famille que le parent sauf si l'utilisateur l'a nommé ce tour (parent Grok → pas de grok ; parent Claude Code → pas de claude ; parent Codex → pas de codex ; parent Antigravity → pas de agy). Un harness par question sauf si l'utilisateur a demandé plusieurs avis.

La famille est le produit/CLI parent, pas l'identifiant du modèle. Cursor Agent, cursor-agent et Grok Bot sont cursor (même si le modèle est Grok). La CLI Grok Build est grok. Claude Code est claude. La CLI Codex est codex. La CLI Antigravity est agy. La CLI Gemini héritée est gemini (une famille différente ; ne la traitez pas comme agy). Un parent Cursor avec defaults.implement = "cursor" saute et demande une fois — ce jeton est un backend, pas self. Épinglez self quand cette session doit faire le travail.

L'utilisateur dit	Binaire (PATH)	Modèle par défaut (dernière série)	Réflexion par défaut	Drapeaux
Claude, Opus, Fable, ask-claude	claude	opus (aussi fable, sonnet, haiku)	xhigh	references/backend-claude.md
GPT, Codex, Sol, Terra, Luna, ask-gpt	codex	gpt-5.6-sol	xhigh	references/backend-codex.md
Grok, ask-grok	grok	grok-4.6	xhigh	references/backend-grok.md
Gemini, Antigravity, agy, ask-gemini	agy	défaut du fournisseur (omettre --model ; lister : agy models)	high	references/backend-agy.md
Non spécifié	Clé defaults.* correspondante dans la configuration utilisateur (spec, spec-ui, plan, plan-ui, implement, implement-ui, writer, research, code-review, code-review-visual, …) si définie et (backend pas de la famille parent, ou valeur est self-class) ; sinon demander une fois. Alias de révision : code-review-task / code-review-adversarial / code-review-adverserial / review → code-review (voir ordre de résolution dans user-config).	Config [models] / [effort], sinon valeurs par défaut du tableau	—	references/user-config.md

Si l'utilisateur épingle un identifiant de modèle, utilisez‑le. Cursor Agent / OpenCode / Droid / CLI Gemini héritée : references/more-clis.md (pas dans scripts/spawn.sh). Le jeton de configuration gemini est cette CLI héritée, pas un alias pour agy.

Listez ce que cette machine a réellement :

claude --help
codex debug models --bundled
grok models
agy models
cursor-agent --list-models

Windows PowerShell : Get-Command claude,codex,grok,agy. Ne pas coder en dur ~/.local/bin/…. agent dans PATH est souvent Grok Build, pas Cursor. La CLI de Cursor est cursor-agent.

Il n'y a pas de compétence harness-spawn. Les stubs obsolètes ask-claude / ask-gpt / ask-grok : cette compétence.

Configuration utilisateur

Optionnelle. Survit aux mises à jour de la compétence. Ne jamais stocker les préférences dans le clone de la compétence (npx skills add se propage dans tous les répertoires d'agent).

• Si $HARNESS_SUBAGENT_CONFIG est défini : ce fichier. Fichier manquant → demander une fois (ne pas dégrader).
• Sinon : ${XDG_CONFIG_HOME:-$HOME/.config}/harness-subagent/config.toml

Schéma, recherche et chemin d'écriture « toujours utiliser X » : references/user-config.md. Ne pas créer le fichier sauf si l'utilisateur a demandé à épingler.

Si la valeur defaults.* correspondante est self, orchestrator, parent ou you, faites le travail dans cette session. N'écrivez pas de brief. N'appelez pas scripts/spawn.sh. Un backend de la famille parent (grok alors que vous êtes Grok) n'est pas self — sautez et demandez une fois sauf si cette énoncé nomme ce harness.

OS, temp, stdin

Les agents parents envoient souvent du stdin. Traitez‑le comme hostile.

	Linux / macOS / WSL	Windows cmd	Windows PowerShell
Répertoire d'exécution	${TMPDIR:-/tmp}/harness-subagent/<run-id>	%TEMP%\harness-subagent\<id>	Join-Path $env:TEMP "harness-subagent\<id>"
Spawn	bash <skill>/scripts/spawn.sh …	Git Bash sur le chemin du script	Fichier argv de Git Bash (ci‑dessous) — jamais une recette -lc entre guillemets

Invoquez scripts/spawn.sh depuis le répertoire de la compétence du SKILL.md que vous avez chargé ce tour (chemin dans l'en‑tête de compétence). npx skills add -g propage des copies ; ne mélangez pas ~/.claude/skills, ~/.cursor/skills et ~/.agents/skills dans une même session.

cwd / -C / --cwd doit être un chemin que cette CLI comprend (WSL /mnt/d/… vs Windows D:\…). Ne mélangez pas Windows claude.exe dans WSL.

Captures d'écran visuelles : Claude et Cursor Agent ont besoin de --add-dir "$RUN" avec les captures dans $RUN. agy Révision/Visuel aussi ; agy Implémentation ne doit pas passer --add-dir (cela fait de $RUN un espace de travail inscriptible). Grok : copiez les captures dans --project (arborescence de l'application), jamais seulement dans $RUN — Grok ne peut pas lire le répertoire d'exécution temporaire. Codex : -i (script --image).

Windows PowerShell (pièges — ne pas sauter)

PowerShell développe $(…), cat et $RUN avant que bash ne les voie. Un & bash -lc "claude … $(cat $RUN/brief.md) > $RUN/last.md" entre guillemets cherchera D:\c\Users\…, écrira last.md dans / ou passera une invite vide/aplatie. system32\bash.exe est WSL — il ne peut pas voir %TEMP% comme /c/….

1. Épinglez Git Bash : "$env:ProgramFiles\Git\bin\bash.exe" (confirmez Test-Path ; n'utilisez pas WSL bash).
2. Écrivez brief.md avec l'outil Write (UTF-8). Ne pas Out-File / > depuis PowerShell 5.1 (UTF-16LE + NUL).
3. Exécutez le script de compétence en tant qu'arguments, mettez l'appel Shell en arrière‑plan (block_until_ms: 0 dans Cursor) :

& "$env:ProgramFiles\Git\bin\bash.exe" -- "<skill-dir>\scripts\spawn.sh" --backend claude --mode review --project "D:/Code/app" --run "C:/Users/<you>/AppData/Local/Temp/harness-subagent/<id>"

4. Listez le répertoire d'exécution avec Shell (Get-ChildItem / ls). Cursor Glob est limité à l'espace de travail et manquera %TEMP%.
5. Deux lancements échoués → arrêtez. Répondez à partir des preuves du parent. Marquez le harness NON VÉRIFIÉ. N'inventez pas une troisième recette de guillemets.

Si ce parent n'autorise que certaines CLI, le spawn sera bloqué sur bash / bash.exe, ce script ou le backend cible (codex, …). Demandez à l'utilisateur d'autoriser ceux‑ci, ou utilisez un mode d'approbation qui peut autoriser le spawn. Ne codez pas en dur une liste d'autorisation de la machine.

Le spawn épingle l'équivalent d'autorisation automatique : Claude/Grok --permission-mode auto. Codex tous modes --approve-for-me (ne passez pas aussi --sandbox : 0.147 mutex). agy Implémentation --dangerously-skip-permissions (agy n'a pas de classificateur Auto ; c'est YOLO). agy Révision l'omet. La révision Claude omet toujours Éditer/Écrire dans --tools (Bash reste pour les fichiers temporaires). Ne passez pas --ask-for-approval à codex exec (TUI uniquement ; exec le rejette). La restriction de modification de l'application est le brief (Ne modifiez pas les fichiers de l'application.), pas un bac à sable en lecture seule.

Protocole partagé

0. Porte. Nommez la seule chose que vous ne pouvez pas répondre à partir de ce dépôt / ce contexte. Si vous ne pouvez pas la nommer, ne lancez pas de spawn — sauf si cette énoncé a déjà nommé un harness (l'énoncé gagne toujours ; writer=self ne supprime pas « Demande à Claude de réécrire le README »). Nommer, style, formatage et « déjà essayé » qui est déjà la réponse ne valent pas un lancement. Écriture/recherche soutenue (une réécriture de README, une recherche concurrentielle) n'est pas « nommer » : lancez quand le chemin résolu est une CLI.
1. Écrivez brief.md sous le répertoire d'exécution temporaire (jamais à l'intérieur du dépôt).
2. Lancez scripts/spawn.sh en arrière‑plan (minutes ; un délai d'attente au premier plan tue les dépenses). Ne copiez pas et ne modifiez pas le script.
3. Attendez que le processus se termine. Ensuite, lisez $RUN/last.md et $RUN/capture-status.txt. Processus toujours en cours + pas encore de VERDICT → pas terminé. spawn.sh préfère déjà $RUN/report.md à la sortie standard finale et normalise les lignes en gras / VERDICT:. Si le statut est usage-limit ou no-verdict, marquez le harness NON VÉRIFIÉ / bloqué — n'inventez pas un verdict et ne redirigez pas vers d'autres backends (règle collante). Exception : un no-verdict qui est une demande de même famille / « quel harness » est une fuite de nidification — réécrivez la barrière d'identité et relancez une fois (même backend). Ne relancez pas un travail terminé à cause d'un préambule.
4. Synthétisez — jamais un simple collage.

Écrire le brief

Description de la tâche, pas un vidage de données. Ne collez pas de diffs ou de contenus de fichiers — nommez les chemins et une investigation limitée. Exception : fichiers inaccessibles depuis le répertoire de travail (captures d'écran sous le répertoire d'exécution temporaire).

• Préférez les fichiers/symboles nommés à « explore le dépôt ».
• Diff : plage exacte, git diff <A>..<B> -- <chemins…>.
• Visuel/confirmation : interdisez git log, git diff sur l'arbre complet, vidages de statut. spawn.sh --image est réservé à Codex. Claude : copiez les captures dans $RUN (reçoit déjà --add-dir "$RUN"). Grok : copiez les captures dans --project. Nommez les fichiers dans le brief.
• Mettez les preuves du parent sous Ce qui a déjà été essayé. Préférez « vérifie ceci » à « redécouvre ». Si vous avez déjà exécuté gh/curl et que Codex Review peut manquer de réseau, mettez la sortie ici et interdisez de ré‑exécuter ces commandes.
• Override produit : si l'utilisateur a verrouillé une décision produit, dites‑le.

Six parties, dans l'ordre :

1. Barrière d'identité de l'enfant — collez d'abord, textuellement, depuis references/roles.md. N'écrivez jamais scripts/spawn.sh ou --mode visual dans le brief (L2 le traite comme un ordre de ré‑orchestrer).
2. Objectif — une phrase nommant le verdict / le livrable (indice d'objectif de la carte de rôle).
3. Où chercher — chemins, commandes limitées, symboles ; liste d'autorisation de modification si Implémentation.
4. Ce qui a déjà été essayé
5. Ce qui changerait mon avis — preuves concluantes (Révision) ou portes d'acceptation (Implémentation).
6. Format de retour — collez depuis references/roles.md : le contrat de retour du rôle (inclut écrire report.md avant le nettoyage), la carte Superpowers (noms exacts), les doit/ne doit pas, et pour implémentation/implémentation-ui la table complète des politiques TDD (jamais « voir roles.md » seul). La carte de rôle gagne sur toute formulation de stub plus ancienne. Nommez le chemin du répertoire d'exécution pour report

… [tronqué pour la traduction]