br1anchen/pstack-pair

Lisez l'adaptateur d'exécution avant de suivre ce workflow. Ses correspondances d'exécution s'appliquent à tous les playbooks et scripts référencés.

Pstack pair

Deux agents, une session Herdr ou Rex, un dépôt. Le maître possède le jugement et le coéquipier possède l'arbre de travail. Chaque message entre eux est un fichier dans le magasin de paires plus une invite d'une ligne qui nomme le fichier. Le terminal n'est jamais l'enregistrement, car les agents sur l'écran alternatif ne laissent pas de défilement arrière.

Préconditions

1. Dans Herdr (test "${HERDR_ENV:-}" = 1) ou Rex (REX_BLOCK défini). En dehors des deux, dites-le et arrêtez-vous.
2. Chargez le skill du multiplexeur pour le contrôle des volets et des agents : le fichier ~/.agents/skills/herdr/SKILL.md de Herdr (ou herdr --skill quand ce fichier est absent), ou rex skill show de Rex. Ses règles de sécurité s'appliquent partout. Dans Rex, lisez Running in Rex.
3. herdr ou rex, et Python 3.11 ou ultérieur (python3), sur le PATH. scripts/pair.sh help liste chaque opération de magasin et de canal ; utilisez-le au lieu d'appels herdr ou rex faits à la main pour la paire.
4. Démarrez le maître en mode automatique. Devin utilise par défaut --permission-mode dangerous pour contourner les permissions. Les autres types héritent du mode du maître. pair.sh permission affiche le mode maître détecté. Utilisez --permission <mode> ou les drapeaux de permission natifs après -- pour remplacer la valeur par défaut ; --permission auto sélectionne le mode intelligent Devin. Les types sans traduction prennent les drapeaux natifs après --. spawn ignore également l'invite de confiance du dossier de chaque type, qui bloquerait un agent sans surveillance dans un dossier qu'il n'a jamais vu : pi obtient --approve, Devin --respect-workspace-trust false. Un drapeau de confiance après -- le remplace. Claude et Codex demandent plutôt de faire confiance à un dossier qu'ils n'ont jamais vu ; cette décision appartient à l'humain, donc spawn refuse la boîte de dialogue et s'arrête en indiquant quoi faire : ouvrir cet agent dans le dépôt une fois et lui faire confiance. Un Claude engendré démarre également sans serveurs MCP (--strict-mcp-config et une configuration vide), car chaque serveur est un processus par session ; un --mcp-config après -- conserve le vôtre.

Rôles

	Maître	Coéquipier
Possède	plan, briefs, revue, décisions, l'humain	l'arbre de travail, tests, diagnostic, preuves
Exécute pstack comme	cadrage poteto-mode, how, architect, compétences de revue	le playbook que chaque brief nomme, avec sa liste de tâches
Écrit	uniquement le magasin de paires	fichiers dans le Scope du brief, plus son journal de progression et son rapport
Parle via	briefs, steers, revues, ordres permanents, portes	lignes de progression, rapports

Entrez votre rôle. Maître : references/master.md. Coéquipier : references/sidekick.md.

Magasin de paires

${XDG_STATE_HOME:-$HOME/.local/state}/pstack/pair/<slug>/, créé par pair.sh init. Un seul écrivain par fichier.

Chemin	Écrivain	Contenu
pair.json	maître via pair.sh	noms d'agents, identifiants de volet, répertoire de travail, racine git, la solution de repli et les basculements du coéquipier, placement du volet (split ou tab)
standing-orders.md	maître	contraintes numérotées collées par chemin dans chaque brief
plans/NNN-<slug>.md	maître	un cycle de plan, à partir du modèle de plan
briefs/NNN-<slug>.md	maître	une unité, à partir du modèle de brief
progress/NNN-<slug>.md	coéquipier via pair.sh progress	une ligne horodatée par étape terminée ou changement d'approche ; un pointage montre uniquement les lignes que le maître n'a pas vues
steers/NNN-<slug>-s<k>.md	maître	direction k en cours de brief pour l'unité NNN, à partir du modèle de steer ; supersedes: nomme le steer contesté auquel il répond
reports/NNN-<slug>-s<k>.md	coéquipier	objection au steer k, à partir du modèle de réponse au steer
reports/NNN-<slug>.md	coéquipier	preuves pour le brief NNN, à partir du modèle de rapport, ou la réponse d'accord/objection au plan NNN, à partir du modèle de réponse au plan
reviews/NNN-<slug>.md	maître	verdict sur le rapport NNN, à partir du modèle de revue ; agreed sur un plan déverrouille ses briefs
scratch/<id>	maître via pair.sh scratch	lien vers un arbre de travail jetable au commit d'une unité pour réexécuter ses vérifications, conservé en dehors du dépôt sous ${XDG_STATE_HOME:-~/.local/state}/pstack/scratch/ (PSTACK_SCRATCH_ROOT le déplace), que Claude et Codex doivent approuver une fois par hôte (kitchen.py doctor vérifie) ; supprimé après la revue
gates.md	maître	questions ouvertes pour l'humain
decisions.tsv	maître via pair.sh log	la trace « montre-moi ton travail »
status.md	pair.sh status	tableau dérivé ; jamais édité à la main
queue	maître via pair.sh queue et dispatch	le chemin du prochain brief, un emplacement
steps/NNN-<slug>.tsv	coéquipier via pair.sh step	une ligne par étape validée : numéro, commit, heure, notes qu'elle résout, résumé
notes/NNN-<slug>-n<k>.md	maître via pair.sh new-note et note	revue des étapes de l'unité jusqu'à l'étape k, à partir du modèle de note : éléments bloquants et suivis
followups.md	maître via pair.sh note	suivis de chaque note, pour un brief ultérieur ou un ticket
session-handoff.md	maître	contexte compact de récupération et de tâche suivante, lu au démarrage
sessions/	pair.sh spawn / rotate	rapports prêts précédents ; exports de session conservés et preuves de chronométrage
events.tsv	chaque commande pair.sh	une ligne par message, rapport, réveil et entrée de journal, lue par pair.sh metrics

NNN est une séquence remplie de zéros partagée par le plan ou le brief, le rapport et la revue, de sorte que les fichiers d'une unité se trient ensemble.

Messages

Texte de l'invite	Direction	Aide de l'expéditeur	Action du destinataire
bootstrap (nomme le skill et le magasin)	maître vers coéquipier	pair.sh spawn	étapes d'amorçage, reports/000-ready.md, réponse READY
pstack-pair PLAN <plan-path>	maître vers coéquipier	pair.sh discuss	ancrer le plan dans le code, écrire une réponse d'accord ou d'objection, terminer le tour
pstack-pair BRIEF <brief-path>	maître vers coéquipier	pair.sh dispatch	exécuter le brief, écrire son rapport, exécuter pair.sh finish, puis terminer le tour avec la ligne REPORT
pstack-pair BRIEF <brief-path>, mis en file	maître vers un coéquipier qui travaille	pair.sh queue	le maître le distribue après une nouvelle session ; pair.sh next refuse
pstack-pair STEER <steer-path>	maître vers un coéquipier qui travaille, ou vers un coéquipier en pause sur une objection	pair.sh steer	le lire à l'arrivée, entre les appels d'outils ; accepter et continuer, ou objecter avec des preuves et terminer le tour
pstack-pair REPORT <report-path>	coéquipier vers maître	pair.sh finish (ou notify)	lire le rapport, réviser
pstack-pair STOP <store>	maître vers coéquipier	pair.sh stop	mettre en pause en toute sécurité, écrire un rapport d'arrêt

Les dispatch et wait du maître reviennent lorsque la réponse du coéquipier atterrit : le rapport écrit depuis le message, ou un coéquipier blocked. Un état de repos du multiplexeur seul n'est pas fiable : un coéquipier Devin semble inactif à l'arrivée d'une invite et entre les étapes, et dans un volet étroit peut sembler avoir terminé pour toute une exécution, donc un état de repos est vérifié par rapport à la ligne « esc to interrupt » du volet ; un état de repos sans rapport qui dure une minute termine l'attente avec report: missing. Ils reviennent également lorsque l'intervalle de pointage passe alors que le coéquipier travaille toujours, en affichant un résumé de pointage au lieu d'un chemin de rapport. wait revient également dès que le rapport d'un brief distribué atterrit, même si le coéquipier a déjà pris le brief mis en file ; running: nomme alors le brief en cours. notify invite le maître uniquement lorsque le maître est inactif, donc un maître en attente n'est jamais interrompu. Un message que vous recevez après compaction nomme toujours ce skill et le fichier à lire, alors rechargez le skill et continuez à partir de ce fichier.

Plan d'abord

L'implémentation ne commence qu'à partir d'un plan que les deux agents ont accepté. Le maître conduit l'implémentation, l'architecture et la conception système : il rédige plans/NNN-<slug>.md avec la conception choisie, les alternatives qu'il a pesées, et leurs avantages et inconvénients, puis l'envoie avec pair.sh discuss. Le coéquipier réfléchit à ces compromis, vérifie chaque étape par rapport au code, et répond par un accord ou une objection avec des preuves. Le maître révise dans un nouveau cycle de plan ou répond aux objections, jusqu'à ce qu'une réponse dise « accord » et que le maître écrive une revue avec le verdict agreed. pair.sh dispatch refuse un brief de fonctionnalité, correction de bug, refactorisation, problème de performances, ou pstack-tdd dont la ligne plan: ne nomme pas un plan accepté. Les briefs en lecture seule et médico-légaux n'ont pas besoin de plan ; le brief de diagnostic d'un bug s'exécute avant son plan, donc le plan repose sur des preuves d'exécution. Trois cycles sans accord deviennent une porte pour l'humain, avec les deux positions dans gates.md.

Pointages et steers

Le maître conduit comme le conducteur d'un binôme : il lève les yeux à un rythme, pas en continu, et corrige la direction, pas les frappes.

• Le coéquipier ajoute une ligne par étape de liste de tâches terminée et par changement d'approche à progress/NNN-<slug>.md via pair.sh progress. Avant d'écrire en dehors du Scope ou de s'écarter du plan, il écrit d'abord la ligne, afin qu'un pointage puisse l'attraper.
• dispatch et wait reviennent à l'intervalle de pointage (--every MIN, neuf minutes par défaut) lorsque le coéquipier travaille toujours, avec un résumé : temps écoulé par rapport à la limite de temps, les lignes de progression non encore vues, les fichiers touchés et ceux qui sont en dehors du Scope, les commits depuis la distribution, et les compteurs de steers. Lorsque le coéquipier a changé de branche ou a rebasé, de sorte que HEAD ne descend plus du commit de distribution, seuls les commits effectués depuis la distribution comptent comme touchés. Ce résumé est tout ce que le maître lit entre les rapports ; il lit le volet uniquement lorsque le résumé marque le journal STALE.
• Un steer est une correction en cours de brief du maître : pair.sh new-steer, puis pair.sh steer. Il atterrit dans la file d'entrée du coéquipier pendant qu'il travaille ; le harnais le transmet entre les appels d'outils et le coéquipier agit dessus là, pas à la fin de l'étape. Un coéquipier Devin le reçoit comme une ligne STEER: de son prochain pair.sh step, notes ou progress à la place, puisque l'Entrée qui délivre un message en file d'attente à Devin annule sa commande en cours. --interrupt annule d'abord l'appel d'outil en cours, pour une direction qui ne peut pas attendre. Les steers portent une direction : une approche que le plan accepté n'a pas choisie, une dérive de portée, une étape à sauter, une ligne interdite sur le point d'être franchie, ou une nouvelle de l'humain. Tout ce que la revue peut attraper à la fin attend la revue.
• Le coéquipier accepte ou objecte, comme avec un plan. Accepter : appliquer, accuser réception dans le journal de progression, continuer. Objecter : écrire la réponse au steer avec des preuves et une alternative, notifier, terminer le tour. Le maître répond par un steer qui remplace celui qui a été contesté, révisé ou retiré, et pair.sh steer reprend le coéquipier. Deux tours par steer ; la décision reste avec le maître, et un désaccord persistant va à un cycle de plan.
• Deux nouveaux steers par brief. Un troisième signifie que le brief était erroné : arrêter l'unité et rebriefer.

Sessions de tâches de toutes sortes

Un coéquipier de toute sorte (Claude, Codex, Devin, pi, Prime, Muse) utilise une conversation fraîche pour chaque brief terminé. Avant d'engendrer, de mettre en file d'attente, de faire tourner ou de nettoyer son stockage, lisez le cycle de vie de session Devin pour Devin ou Pi, ou l'adaptateur Prime pour Prime. Le travail partiel et bloqué reste dans sa session ; un brief terminé quitte la file d'attente pour que le maître le distribue. dispatch et discuss font eux-mêmes tourner le coéquipier en premier (rotated: dans leur sortie) ; pair.sh rotate reste pour que le maître l'exécute à la main. Le magasin pstack persiste entre les sessions.

Muse Code

Utilisez --kind muse pour tout rôle. Lisez l'adaptateur Muse pour sa gestion des permissions, de la confiance, de la vérification préalable et de la sortie. Muse conserve une conversation par volet, donc il n'est pas tourné par brief.

Prime Agent

Utilisez --kind prime-agent pour le coéquipier. Lisez l'adaptateur Prime Agent pour les arguments de modèle natifs, la vérification préalable, le steering, le nettoyage exact de la session démon, et le basculement de fournisseur. Prime utilise le protocole de magasin partagé et nécessite une rotation après chaque brief terminé.

Coéquipier Pi et solution de repli

Un coéquipier pi signale son état à Herdr (et, avec l'extension pstack, à Rex) via ses propres événements et met en file d'attente un steer sans annuler la commande en cours. Lorsque son modèle se trouve derrière une route qui peut échouer, engendrez-le avec --fallback devin : spawn vérifie d'abord le modèle, et pair.sh failover échange la solution de repli en cours d'exécution. Lisez la référence du coéquipier Pi avant d'en engendrer un.

Garder le coéquipier occupé

Le coéquipier est le chemin critique : le maître traite un rapport en quelques minutes, tandis qu'une unité prend des dizaines de minutes à des heures. Trois habitudes empêchent le coéquipier d'attendre le maître.

• Mettre le prochain brief en file d'attente. Pendant qu'une unité s'exécute, le maître rédige le suivant et le retient avec pair.sh queue. Après un rapport done, le coéquipier démarre une nouvelle session et le maître distribue ce brief ; pair.sh next refuse. La file d'attente a un emplacement et contient uniquement une unité qui ne dépend pas de la revue de l'unité en cours, donc un revise devient un brief de suivi, pas une reprise de celui mis en file d'attente.
• Réviser au commit. Un brief qui écrit dit commit: yes, et le head: du rapport nomme ce commit. Le maître le lit avec git show pendant que le coéquipier travaille sur l'unité suivante, et réexécute les vérifications dans pair.sh scratch <store> NNN-<slug>-review --at <head>, jamais dans l'arbre partagé.
• Amender au lieu de replanifier. Une objection que le maître adopte devient un amendement numéroté dans la revue agreed. Un nouveau cycle de plan est destiné à une conception modifiée.