br1anchen/pstack-pair

Leia o adaptador de tempo de execução antes de seguir este fluxo de trabalho. Seus mapeamentos de tempo de execução se aplicam a todos os playbooks e scripts referenciados.

Par pstack

Dois agentes, uma sessão Herdr ou Rex, um repositório. O mestre possui o julgamento e o auxiliar possui a árvore de trabalho. Cada mensagem entre eles é um arquivo no armazenamento do par mais um prompt de uma linha que nomeia o arquivo. O terminal nunca é o registro, porque agentes na tela alternativa não deixam histórico de rolagem.

Pré-condições

1. Dentro do Herdr (test "${HERDR_ENV:-}" = 1) ou Rex (REX_BLOCK definido). Fora de ambos, informe e pare.

2. Carregue a skill do multiplexador para controle de painel e agente: a skill ~/.agents/skills/herdr/SKILL.md do Herdr (ou herdr --skill quando esse arquivo estiver ausente), ou rex skill show do Rex. Suas regras de segurança se aplicam em todo o processo. No Rex, leia Executando no Rex.

3. herdr ou rex, e Python 3.11 ou superior (python3), no PATH. scripts/pair.sh help lista todas as operações de armazenamento e canal; use-o em vez de chamadas herdr ou rex feitas manualmente para o par.

4. Inicie o mestre em modo automático. O Devin padroniza para ignorar permissões com --permission-mode dangerous. Outros tipos herdam o modo do mestre. pair.sh permission imprime o modo mestre detectado. Use --permission <mode> ou flags de permissão nativas após -- para substituir o padrão; --permission auto seleciona o modo inteligente do Devin. Tipos sem tradução usam flags nativas após --. spawn também pula o prompt de confiança de pasta de cada tipo, o que travaria um agente não supervisionado em uma pasta que ele não viu: pi recebe --approve, Devin --respect-workspace-trust false. Uma flag de confiança após -- a substitui. Claude e Codex, em vez disso, pedem para confiar em uma pasta que não viram; essa decisão é do humano, então spawn recusa o diálogo e para com o que fazer: abra esse agente no repositório uma vez e confie nele.

   Um Claude gerado também inicia sem servidores MCP (--strict-mcp-config e uma configuração vazia), já que cada servidor é um processo por sessão; um --mcp-config após -- mantém o seu.

Papéis

	Mestre	Auxiliar
Possui	plano, briefs, revisão, decisões, o humano	a árvore de trabalho, testes, diagnóstico, evidências
Executa pstack como	framing modo poteto, how, architect, skills de revisão	o playbook que cada brief nomeia, com sua lista de tarefas
Escreve	apenas o armazenamento do par	arquivos dentro do Escopo do brief, mais seu log de progresso e relatório
Fala através de	briefs, steers, revisões, ordens permanentes, portões	linhas de progresso, relatórios

Entre no seu papel. Mestre: references/master.md. Auxiliar: references/sidekick.md.

Armazenamento do par

${XDG_STATE_HOME:-$HOME/.local/state}/pstack/pair/<slug>/, criado por pair.sh init. Um escritor por arquivo.

Caminho	Escritor	Conteúdo
pair.json	mestre via pair.sh	nomes dos agentes, ids dos painéis, cwd, git root, fallback e failovers do auxiliar, posicionamento do painel (split ou tab)
standing-orders.md	mestre	restrições numeradas anexadas por caminho em cada brief
plans/NNN-<slug>.md	mestre	uma rodada de plano, a partir do modelo de plano
briefs/NNN-<slug>.md	mestre	uma unidade, a partir do modelo de brief
progress/NNN-<slug>.md	auxiliar via pair.sh progress	uma linha com timestamp por etapa concluída ou mudança de abordagem; um check-in mostra apenas as linhas que o mestre não viu
steers/NNN-<slug>-s<k>.md	mestre	direção k no meio do brief para a unidade NNN, a partir do modelo de steer; supersedes: nomeia o steer objetado ao qual responde
reports/NNN-<slug>-s<k>.md	auxiliar	objeção ao steer k, a partir do modelo de resposta a steer
reports/NNN-<slug>.md	auxiliar	evidências para o brief NNN, a partir do modelo de relatório, ou a resposta concordo/objeto ao plano NNN, a partir do modelo de resposta a plano
reviews/NNN-<slug>.md	mestre	veredito sobre o relatório NNN, a partir do modelo de revisão; agreed em um plano desbloqueia seus briefs
scratch/<id>	mestre via pair.sh scratch	link para uma worktree descartável no commit de uma unidade para reexecutar suas verificações, mantido fora do repositório sob ${XDG_STATE_HOME:-~/.local/state}/pstack/scratch/ (PSTACK_SCRATCH_ROOT o move), que Claude e Codex devem confiar uma vez por host (kitchen.py doctor verifica); removido após a revisão
gates.md	mestre	perguntas em aberto para o humano
decisions.tsv	mestre via pair.sh log	a trilha de mostre-seu-trabalho
status.md	pair.sh status	tabela derivada; nunca editada manualmente
queue	mestre via pair.sh queue e dispatch	o caminho do próximo brief, um slot
steps/NNN-<slug>.tsv	auxiliar via pair.sh step	uma linha por etapa commitada: número, commit, tempo, notas que resolve, resumo
notes/NNN-<slug>-n<k>.md	mestre via pair.sh new-note e note	revisão das etapas da unidade até a etapa k, a partir do modelo de nota: itens bloqueadores e acompanhamentos
followups.md	mestre via pair.sh note	acompanhamentos de cada nota, para um brief posterior ou um issue
session-handoff.md	mestre	contexto compacto de recuperação e próxima tarefa, lido na inicialização
sessions/	pair.sh spawn / rotate	relatórios prontos anteriores; exportações de sessão retidas e evidências de temporização
events.tsv	todo comando pair.sh	uma linha por mensagem, relatório, ativação e entrada de log, lido por pair.sh metrics

NNN é uma sequência preenchida com zeros compartilhada por plano ou brief, relatório e revisão, para que os arquivos de uma unidade sejam classificados juntos.

Mensagens

Texto do prompt	Direção	Auxiliar do remetente	Movimento do receptor
bootstrap (nomeia a skill e o armazenamento)	mestre para auxiliar	pair.sh spawn	etapas de inicialização, reports/000-ready.md, responder PRONTO
pstack-pair PLAN <caminho-do-plano>	mestre para auxiliar	pair.sh discuss	fundamentar o plano no código, escrever uma resposta concordo ou objeto, encerrar a vez
pstack-pair BRIEF <caminho-do-brief>	mestre para auxiliar	pair.sh dispatch	executar o brief, escrever seu relatório, executar pair.sh finish, então encerrar a vez com a linha RELATÓRIO
pstack-pair BRIEF <caminho-do-brief>, enfileirado	mestre para um auxiliar trabalhando	pair.sh queue	o mestre o despacha após uma sessão nova; pair.sh next recusa
pstack-pair STEER <caminho-do-steer>	mestre para um auxiliar trabalhando, ou para um pausado em uma objeção	pair.sh steer	lê-lo na chegada, entre chamadas de ferramenta; concordar e continuar, ou objetar com evidências e encerrar a vez
pstack-pair REPORT <caminho-do-relatório>	auxiliar para mestre	pair.sh finish (ou notify)	ler o relatório, revisar
pstack-pair STOP <armazenamento>	mestre para auxiliar	pair.sh stop	pausar com segurança, escrever um relatório de parada

O dispatch e wait do mestre retornam quando a resposta do auxiliar chega: o relatório escrito desde a mensagem, ou um auxiliar bloqueado. Um settle do multiplexador sozinho não é confiável: um auxiliar Devin mostra ocioso quando um prompt chega e entre etapas, e em um painel estreito pode mostrar concluído para uma execução inteira, então um settle é verificado em relação à linha "esc para interromper" do painel; um settle sem relatório que se mantém por um minuto encerra a espera com relatório: ausente. Eles também retornam quando o intervalo de check-in passa com o auxiliar ainda trabalhando, imprimindo um resumo de check-in em vez de um caminho de relatório. wait também retorna no momento em que o relatório de um brief despachado chega, mesmo quando o auxiliar já pegou o brief enfileirado; running: então nomeia o brief em que está. notify solicita o mestre apenas quando o mestre está ocioso, então um mestre em espera nunca é interrompido. Uma mensagem que você recebe após a compactação ainda nomeia esta skill e o arquivo a ser lido, então recarregue a skill e continue a partir desse arquivo.

Plano primeiro

A implementação começa apenas a partir de um plano que ambos os agentes concordaram. O mestre conduz a implementação, arquitetura e design do sistema: ele elabora plans/NNN-<slug>.md com o design escolhido, as alternativas que pesou e seus prós e contras, então o envia com pair.sh discuss. O auxiliar faz um brainstorm sobre essas compensações, verifica cada etapa em relação ao código e responde concordo ou objeto com evidências. O mestre revisa em uma nova rodada de plano ou responde às objeções, até que uma resposta diga concordo e o mestre escreva uma revisão com veredito agreed. pair.sh dispatch recusa um brief de funcionalidade, correção de bug, refatoração, problema de desempenho ou pstack-tdd cuja linha plan: não nomeie um plano acordado. Briefs somente leitura e forenses não precisam de plano; o brief de diagnóstico de um bug é executado antes de seu plano, então o plano se baseia em evidências de tempo de execução. Três rodadas sem acordo se tornam um portão para o humano, com ambas as posições em gates.md.

Check-ins e steers

O mestre conduz da mesma forma que um motorista de pareamento faz: ele verifica em um ritmo, não continuamente, e corrige a direção, não as teclas digitadas.

• O auxiliar anexa uma linha por etapa de lista de tarefas concluída e por mudança de abordagem para progress/NNN-<slug>.md através de pair.sh progress. Antes de escrever fora do Escopo ou se desviar do plano, ele escreve a linha primeiro, para que um check-in possa detectá-lo.
• dispatch e wait retornam no intervalo de check-in (--every MIN, nove minutos por padrão) quando o auxiliar ainda está trabalhando, com um resumo: tempo decorrido em relação ao timebox, as linhas de progresso ainda não vistas, arquivos tocados e quais estão fora do Escopo, commits desde o despacho e contagens de steer. Quando o auxiliar mudou de branch ou fez rebase, de modo que HEAD não descende mais do head do despacho, apenas os commits feitos desde o despacho contam como tocados. Esse resumo é tudo que o mestre lê entre relatórios; ele lê o painel apenas quando o resumo marca o log como OBSOLETO.
• Um steer é uma correção no meio do brief vinda do mestre: pair.sh new-steer, então pair.sh steer. Ele chega na fila de entrada do auxiliar enquanto ele trabalha; o harness o entrega entre chamadas de ferramenta e o auxiliar age sobre ele ali, não no final da etapa. Um auxiliar Devin o recebe como uma linha STEER: de seu próximo pair.sh step, notes, ou progress em vez disso, já que o Enter que entrega uma mensagem enfileirada ao Devin cancela seu comando em execução. --interrupt cancela a chamada de ferramenta em execução primeiro, para uma direção que não pode esperar por ela. Steers carregam direção: uma abordagem que o plano acordado não escolheu, desvio de escopo, uma etapa a pular, uma linha Proibida prestes a ser cruzada, ou novidades do humano. Qualquer coisa que a revisão possa pegar no final espera pela revisão.
• O auxiliar concorda ou objeta, como com um plano. Concordar: aplicar, reconhecer no log de progresso, continuar. Objetar: escrever a resposta ao steer com evidências e uma alternativa, notificar, encerrar a vez. O mestre responde com um steer que substitui o objetado, revisado ou retirado, e pair.sh steer retoma o auxiliar. Duas rodadas por steer; a decisão permanece com o mestre, e um desacordo persistente vai para uma rodada de plano.
• Dois steers novos por brief. Um terceiro significa que o brief estava errado: pare a unidade e refaça o brief.

Sessões de tarefa de todos os tipos

Um auxiliar de qualquer tipo (Claude, Codex, Devin, pi, Prime, Muse) usa uma conversa nova para cada brief concluído. Antes de gerar, enfileirar, rotacionar ou limpar seu armazenamento, leia o ciclo de vida da sessão Devin para Devin ou Pi, ou o adaptador Prime para Prime. Trabalho parcial e bloqueado permanece em sua sessão; um brief concluído deixa a fila para o mestre despachar. dispatch e discuss rotacionam o auxiliar por conta própria primeiro (rotated: em sua saída); pair.sh rotate permanece para o mestre executar manualmente. O armazenamento pstack persiste entre sessões.

Muse Code

Use --kind muse para qualquer papel. Leia o adaptador Muse para suas permissões, confiança, pré-execução e tratamento de saída. Muse mantém uma conversa por painel, então não é rotacionado por brief.

Prime Agent

Use --kind prime-agent para o auxiliar. Leia o adaptador Prime Agent para argumentos de modelo nativos, pré-execução, orientação, limpeza exata de sessão de daemon e failover de provedor. Prime usa o protocolo de armazenamento compartilhado e requer rotação após cada brief concluído.

Auxiliar Pi e fallback

Um auxiliar pi relata seu estado ao Herdr (e, com a extensão pstack, ao Rex) através de seus próprios eventos e enfileira um steer sem cancelar o comando em execução. Quando seu modelo está atrás de uma rota que pode falhar, gere-o com --fallback devin: spawn verifica o modelo primeiro, e pair.sh failover troca pelo fallback no meio da execução. Leia a referência do auxiliar Pi antes de gerar um.

Mantendo o auxiliar ocupado

O auxiliar é o caminho crítico: o mestre vira um relatório em minutos, enquanto uma unidade leva dezenas de minutos a horas. Três hábitos mantêm o auxiliar de esperar pelo mestre.

• Enfileire o próximo brief. Enquanto uma unidade é executada, o mestre elabora o próximo e o mantém com pair.sh queue. Após um relatório done, o auxiliar inicia uma nova sessão e o mestre despacha esse brief; pair.sh next recusa. A fila tem um slot e contém apenas uma unidade que não depende da revisão da unidade em execução, então um revise se torna um brief de acompanhamento, não uma retrabalho do enfileirado.
• Revise no commit. Um brief que escreve diz commit: yes, e o head: do relatório nomeia esse commit. O mestre o lê com git show enquanto o auxiliar trabalha na próxima unidade, e reexecuta verificações em pair.sh scratch <store> NNN-<slug>-review --at <head>, nunca na árvore compartilhada.
• Altere em vez de replanejar. Uma objeção que o mestre adota se torna uma emenda numerada na revisão agreed. Uma nova rodada de plano é para um design alterado.