br1anchen/pstack-pair

Lee el adaptador de ejecución antes de seguir este flujo de trabajo. Sus asignaciones de ejecución se aplican a todos los manuales y scripts referenciados.

Pstack pair

Dos agentes, una sesión de Herdr o Rex, un repositorio. El maestro posee el juicio y el compañero posee el árbol de trabajo. Cada mensaje entre ellos es un archivo en el almacén de pares más una línea de prompt que nombra el archivo. El terminal nunca es el registro, porque los agentes en la pantalla alternativa no dejan historial.

Precondiciones

1. Dentro de Herdr (test "${HERDR_ENV:-}" = 1) o Rex (REX_BLOCK establecido). Fuera de ambos, indícalo y detente.
2. Carga la habilidad del multiplexor para el control de paneles y agentes: la habilidad de Herdr ~/.agents/skills/herdr/SKILL.md (o herdr --skill cuando ese archivo no existe), o rex skill show de Rex. Sus reglas de seguridad se aplican en todo momento. En Rex, lee Ejecutando en Rex.
3. herdr o rex, y Python 3.11 o superior (python3), en PATH. scripts/pair.sh help lista todas las operaciones del almacén y del canal; úsalo en lugar de llamadas manuales a herdr o rex para el par.
4. Inicia el maestro en modo automático. Devin omite permisos por defecto con --permission-mode dangerous. Otros tipos heredan el modo del maestro. pair.sh permission imprime el modo del maestro detectado. Usa --permission <mode> o los indicadores nativos de permiso después de -- para anular el valor predeterminado; --permission auto selecciona el modo inteligente de Devin. Los tipos sin traducción toman indicadores nativos después de --. spawn también omite la solicitud de confianza de carpeta de cada tipo, que bloquearía a un agente desatendido en una carpeta que no ha visto: pi obtiene --approve, Devin --respect-workspace-trust false. Un indicador de confianza después de -- lo anula. Claude y Codex, en cambio, preguntan si confiar en una carpeta que no han visto; esa decisión es del humano, por lo que spawn rechaza el diálogo y se detiene indicando qué hacer: abre ese agente en el repositorio una vez y confía en él. Un Claude generado también se inicia sin servidores MCP (--strict-mcp-config y una configuración vacía), ya que cada servidor es un proceso por sesión; un --mcp-config después de -- conserva los tuyos.

Roles

	Maestro	Compañero
Posee	plan, briefs, revisión, decisiones, el humano	el árbol de trabajo, pruebas, diagnóstico, evidencia
Ejecuta pstack como	encuadre modo-poteto, how, architect, habilidades de revisión	el manual que nombra cada brief, con su lista de tareas
Escribe	solo el almacén de pares	archivos dentro del Alcance del brief, más su registro de progreso e informe
Habla a través de	briefs, correcciones, revisiones, órdenes permanentes, compuertas	líneas de progreso, informes

Entra en tu rol. Maestro: references/master.md. Compañero: references/sidekick.md.

Almacén de pares

${XDG_STATE_HOME:-$HOME/.local/state}/pstack/pair/<slug>/, creado por pair.sh init. Un escritor por archivo.

Ruta	Escritor	Contenido
pair.json	maestro vía pair.sh	nombres de agente, ids de panel, cwd, raíz git, respaldo y failovers del compañero, colocación del panel (split o tab)
standing-orders.md	maestro	restricciones numeradas pegadas por ruta en cada brief
plans/NNN-<slug>.md	maestro	una ronda de plan, desde la plantilla de plan
briefs/NNN-<slug>.md	maestro	una unidad, desde la plantilla de brief
progress/NNN-<slug>.md	compañero vía pair.sh progress	una línea con marca de tiempo por paso completado o cambio de enfoque; un check-in muestra solo las líneas que el maestro no ha visto
steers/NNN-<slug>-s<k>.md	maestro	corrección k a medio brief para la unidad NNN, desde la plantilla de corrección; supersedes: nombra la corrección objetada a la que responde
reports/NNN-<slug>-s<k>.md	compañero	objeción a la corrección k, desde la plantilla de respuesta a corrección
reports/NNN-<slug>.md	compañero	evidencia para el brief NNN, desde la plantilla de informe, o la respuesta de aceptar/objetar al plan NNN, desde la plantilla de respuesta a plan
reviews/NNN-<slug>.md	maestro	veredicto sobre el informe NNN, desde la plantilla de revisión; agreed en un plan desbloquea sus briefs
scratch/<id>	maestro vía pair.sh scratch	enlace a un árbol de trabajo desechable en el commit de una unidad para reejecutar sus comprobaciones, mantenido fuera del repositorio bajo ${XDG_STATE_HOME:-~/.local/state}/pstack/scratch/ (PSTACK_SCRATCH_ROOT lo mueve), que Claude y Codex deben confiar una vez por host (kitchen.py doctor lo comprueba); eliminado después de la revisión
gates.md	maestro	preguntas abiertas para el humano
decisions.tsv	maestro vía pair.sh log	el rastro de "muéstrame tu trabajo"
status.md	pair.sh status	tabla derivada; nunca editada a mano
queue	maestro vía pair.sh queue y dispatch	la ruta del siguiente brief, un espacio
steps/NNN-<slug>.tsv	compañero vía pair.sh step	una fila por paso comprometido: número, commit, hora, notas que resuelve, resumen
notes/NNN-<slug>-n<k>.md	maestro vía pair.sh new-note y note	revisión de los pasos de la unidad hasta el paso k, desde la plantilla de nota: elementos bloqueantes y seguimientos
followups.md	maestro vía pair.sh note	seguimientos de cada nota, para un brief posterior o un issue
session-handoff.md	maestro	contexto compacto de recuperación y próxima tarea, leído en el arranque
sessions/	pair.sh spawn / rotate	informes listos anteriores; exportaciones de sesión retenidas y evidencia de temporización
events.tsv	cada comando pair.sh	una fila por mensaje, informe, despertar y entrada de registro, leído por pair.sh metrics

NNN es una secuencia rellenada con ceros compartida por plan o brief, informe y revisión, de modo que los archivos de una unidad se ordenan juntos.

Mensajes

Texto del prompt	Dirección	Ayudante del remitente	Movimiento del receptor
bootstrap (nombra la habilidad y el almacén)	maestro a compañero	pair.sh spawn	pasos de arranque, reports/000-ready.md, responder READY
pstack-pair PLAN <plan-path>	maestro a compañero	pair.sh discuss	fundamentar el plan en el código, escribir una respuesta de aceptar u objetar, finalizar el turno
pstack-pair BRIEF <brief-path>	maestro a compañero	pair.sh dispatch	ejecutar el brief, escribir su informe, ejecutar pair.sh finish, luego finalizar el turno con la línea REPORT
pstack-pair BRIEF <brief-path>, en cola	maestro a un compañero trabajando	pair.sh queue	el maestro lo despacha después de una sesión nueva; pair.sh next rechaza
pstack-pair STEER <steer-path>	maestro a un compañero trabajando, o a uno en pausa por una objeción	pair.sh steer	leerlo al llegar, entre llamadas a herramientas; aceptar y continuar, u objetar con evidencia y finalizar el turno
pstack-pair REPORT <report-path>	compañero a maestro	pair.sh finish (o notify)	leer el informe, revisar
pstack-pair STOP <store>	maestro a compañero	pair.sh stop	pausar de forma segura, escribir un informe de parada

El dispatch y wait del maestro regresan cuando llega la respuesta del compañero: el informe escrito desde el mensaje, o un compañero blocked. No se confía únicamente en un settle del multiplexor: un compañero Devin se muestra inactivo cuando llega un prompt y entre pasos, y en un panel estrecho puede mostrarse como completado para toda una ejecución, por lo que un settle se verifica contra la línea "esc para interrumpir" del panel; un settle sin informe que se mantiene durante un minuto finaliza la espera con report: missing. También regresan cuando el intervalo de check-in pasa con el compañero aún trabajando, imprimiendo un resumen de check-in en lugar de una ruta de informe. wait también regresa en el momento en que un informe de brief despachado llega, incluso si el compañero ya ha tomado el brief en cola; running: entonces nombra el brief en el que está. notify solicita al maestro solo cuando el maestro está inactivo, por lo que un maestro en espera nunca es interrumpido. Un mensaje que recibes después de la compactación sigue nombrando esta habilidad y el archivo a leer, así que recarga la habilidad y continúa desde ese archivo.

Plan primero

La implementación comienza solo a partir de un plan que ambos agentes hayan acordado. El maestro impulsa la implementación, la arquitectura y el diseño del sistema: redacta plans/NNN-<slug>.md con el diseño elegido, las alternativas que sopesó y sus pros y contras, luego lo envía con pair.sh discuss. El compañero hace una lluvia de ideas sobre esas compensaciones, verifica cada paso contra el código y responde aceptar u objetar con evidencia. El maestro revisa en una nueva ronda de plan o responde a las objeciones, hasta que una respuesta dice aceptar y el maestro escribe una revisión con veredicto agreed. pair.sh dispatch rechaza un brief de característica, corrección de errores, refactorización, problema de rendimiento o pstack-tdd cuya línea plan: no nombre un plan acordado. Los briefs de solo lectura y forenses no necesitan plan; el brief de diagnóstico de un error se ejecuta antes de su plan, por lo que el plan se basa en evidencia de ejecución. Tres rondas sin acuerdo se convierten en una compuerta para el humano, con ambas posiciones en gates.md.

Check-ins y correcciones

El maestro impulsa como lo haría un conductor en pareja: supervisa en una cadencia, no continuamente, y corrige la dirección, no las pulsaciones de teclas.

• El compañero añade una línea por paso completado de la lista de tareas y por cambio de enfoque a progress/NNN-<slug>.md a través de pair.sh progress. Antes de escribir fuera del Alcance o desviarse del plan, escribe la línea primero, para que un check-in pueda detectarlo.
• dispatch y wait regresan en el intervalo de check-in (--every MIN, nueve minutos por defecto) cuando el compañero aún está trabajando, con un resumen: tiempo transcurrido contra el timebox, las líneas de progreso aún no vistas, archivos tocados y cuáles están fuera del Alcance, commits desde el despacho y recuento de correcciones. Cuando el compañero cambió de rama o hizo rebase, de modo que HEAD ya no desciende del head del despacho, solo los commits realizados desde el despacho cuentan como tocados. Ese resumen es todo lo que el maestro lee entre informes; lee el panel solo cuando el resumen marca el registro como STALE.
• Una corrección es una corrección a medio brief del maestro: pair.sh new-steer, luego pair.sh steer. Llega a la cola de entrada del compañero mientras trabaja; el arnés lo entrega entre llamadas a herramientas y el compañero actúa sobre él allí, no al final del paso. Un compañero Devin lo recibe como una línea STEER: desde su siguiente pair.sh step, notes, o progress, ya que el Enter que entrega un mensaje en cola a Devin cancela su comando en ejecución. --interrupt cancela primero la llamada a herramienta en ejecución, para una dirección que no puede esperar. Las correcciones llevan dirección: un enfoque que el plan acordado no eligió, desviación del alcance, un paso a omitir, una línea Prohibida a punto de cruzarse, o noticias del humano. Cualquier cosa que la revisión pueda detectar al final espera a la revisión.
• El compañero acepta u objeta, como con un plan. Aceptar: aplicar, reconocer en el registro de progreso, continuar. Objetar: escribir la respuesta a la corrección con evidencia y una alternativa, notificar, finalizar el turno. El maestro responde con una corrección que reemplaza a la objetada, revisada o retirada, y pair.sh steer reanuda al compañero. Dos rondas por corrección; la decisión permanece en el maestro, y un desacuerdo persistente pasa a una ronda de plan.
• Dos correcciones nuevas por brief. Una tercera significa que el brief era incorrecto: detener la unidad y re-brief.

Sesiones de tarea de todo tipo

Un compañero de cualquier tipo (Claude, Codex, Devin, pi, Prime, Muse) utiliza una conversación nueva por cada brief completado. Antes de generar, poner en cola, rotar o limpiar su almacenamiento, lee el ciclo de vida de la sesión Devin para Devin o Pi, o el adaptador Prime para Prime. El trabajo parcial y bloqueado permanece en su sesión; un brief completado deja la cola para que el maestro lo despache. dispatch y discuss rotan al compañero ellos mismos primero (rotated: en su salida); pair.sh rotate permanece para que el maestro lo ejecute manualmente. El almacén pstack persiste entre sesiones.

Muse Code

Usa --kind muse para cualquier rol. Lee el adaptador Muse para su manejo de permisos, confianza, preflight y salida. Muse mantiene una conversación por panel, por lo que no se rota por brief.

Prime Agent

Usa --kind prime-agent para el compañero. Lee el adaptador Prime Agent para argumentos de modelo nativos, preflight, corrección, limpieza exacta de sesiones daemon y failover del proveedor. Prime usa el protocolo de almacén compartido y requiere rotación después de cada brief completado.

Pi compañero y respaldo

Un compañero pi informa su estado a Herdr (y, con la extensión pstack, a Rex) a través de sus propios eventos y pone en cola una corrección sin cancelar el comando en ejecución. Cuando su modelo se encuentra detrás de una ruta que puede fallar, genéralo con --fallback devin: spawn comprueba el modelo primero, y pair.sh failover intercambia el respaldo a mitad de ejecución. Lee la referencia del compañero Pi antes de generar uno.

Manteniendo al compañero ocupado

El compañero es la ruta crítica: el maestro procesa un informe en minutos, mientras que una unidad lleva decenas de minutos u horas. Tres hábitos evitan que el compañero espere al maestro.

• Poner en cola el siguiente brief. Mientras una unidad se ejecuta, el maestro redacta la siguiente y la mantiene con pair.sh queue. Después de un informe done, el compañero inicia una sesión nueva y el maestro despacha ese brief; pair.sh next rechaza. La cola tiene un espacio y solo contiene una unidad que no dependa de la revisión de la unidad en ejecución, por lo que un revise se convierte en un brief de seguimiento, no en una reelaboración del que está en cola.
• Revisar en el commit. Un brief que escribe dice commit: yes, y el head: del informe nombra ese commit. El maestro lo lee con git show mientras el compañero trabaja en la siguiente unidad, y reejecuta comprobaciones en pair.sh scratch <store> NNN-<slug>-review --at <head>, nunca en el árbol compartido.
• Enmendar en lugar de replanificar. Una objeción que el maestro adopta se convierte en una enmienda numerada en la revisión agreed. Una nueva ronda de plan es para un diseño cambiado.

...