LLM Wiki — Synaptic Lattice

Pstack

Properties1
tagsvibe-coding, orchestration, tool, coding-agent

Leitura de 12 min

Pstack

pstack é um plugin oficial de Cursor para trabalho rigoroso com agentes, criado por Lauren Tan (@poteto). O pacote atual reúne 24 workflow skills, 23 princípios de engenharia, 22 playbooks de tarefa (+ 1 interno “Opening a PR” usado pelos demais), 2 subagentes especializados, programas auxiliares e um automation pack opcional. A meta declarada não é mais código — é menos código, mais qualidade e verificação suficiente para vários agentes trabalharem em paralelo sem transformar o repositório em caos. Lauren usou as skills 9.000 vezes dentro do Cursor em uma semana antes de empacotá-las publicamente. As skills são arquivos SKILL.md portáteis — o mesmo formato que Claude Code, Codex e outros agentes carregam — então o coração do pstack funciona fora do Cursor, perdendo apenas recursos que dependem de API do Cursor (/add-plugin, /loop, modelo por subagente, Design Mode, ~/.cursor/rules/pstack-models.mdc). Filosofia central: agentes precisam do mesmo onboarding que um engenheiro novo (regras, skills, ferramentas, memória) — exceto que eles esquecem sempre; pstack vai fundo antes de ir largo, tornando um agente confiável em um problema completo antes de multiplicá-lo.

Arquitetura

O comando central é /poteto-mode, que atua como roteador sticky:

  1. Lê o índice de princípios dentro da skill poteto-mode.
  2. Casa o pedido com um playbook (bug fix, feature, refactoring, investigation, perf issue) e copia o playbook verbatim para a task list — passos nunca são improvisados ou omitidos silenciosamente; quando pulados, o motivo fica registrado.
  3. Chama skills especialistas conforme o playbook.
  4. Delega por papel de modelo (implementação, investigação, julgamento, review).
  5. Inspeciona e verifica o resultado antes de reportar sucesso, depois limpa, revisa e faz ship.

Enquanto o usuário estiver no modo, mensagens de follow-up (continue, do it, keep going until done) permanecem no mesmo playbook; new task inicia um casamento novo de playbook. Um pedido vira um fluxo completo de engenharia: objetivo + forma de verificação.

Playbooks por trabalho

  • Entender antes de mudar: Investigation (read-only; roteia por /how e, quando há história/intenção, /why). Para sistemas desconhecidos, começar aqui — agente que edita a primeira função plausível costuma corrigir sintoma; rastrear o caminho de runtime encontra a fronteira real.
  • Construir e mudar código: Bug fix (reproduzir antes de corrigir; causas concorrentes eliminadas com evidência de runtime; verificação da reprodução original na mesma interface), Feature (/how → /architect em paralelo → implementação delegada → review do diff → verificação na interface real), Refactoring (registra comportamento existente primeiro — characterization test/snapshot/script de equivalência — e muda a estrutura em passos pequenos mantendo a verificação verde), Perf issue (começa com trace; compara baseline vs. pós-mudança; “parece mais rápido” não conta), Hillclimb (melhorar uma métrica em várias tentativas; cada tentativa tem hipótese, medição, mantém ganho, descarta perda), Prototype (menor artefato descartável suficiente para decidir), Visual parity (começa com screenshots; diferença de pixel não-zero é falha).
  • Diagnosticar sem consertar: Runtime forensics (captura sinal ao vivo: perfil de CPU, snapshot de heap, trace de navegador) e Trace forensics (parte de artefato já capturado; torna dados grandes consultáveis, estreita ao frame custoso ou caminho de retenção, mapeia achado de volta ao código-fonte). Ambos param no diagnóstico — depois inicia-se Bug fix ou Perf issue novo.
  • Manter trabalho longo em movimento: Autonomous run (uma tarefa até condição verificável passar), Multi-phase plan, Autopilot-full (fila de PRs independentes por verificação e merge), Autopilot-stack (uma stack revisada de PRs, landing final com humano), Orchestrate (opção pesada: projeto de vários dias, muitos stacked PRs, coordinator permanente + frota de agentes; tarefa longa não é automaticamente programa — se um agente cabe numa sessão, Orchestrate é excesso).
  • Retomar trabalho com segurança: Session pickup (reconstrói estado de agente anterior a partir de transcript, branch e decision log; identifica feito/restante/onde retomar) e Pause safely (o inverso: para em fronteira atômica, torna o trabalho durável, escreve nota de retomada). Evitam que um agente novo refaça 3 horas de trabalho concluído por não saber onde o anterior parou.
  • Manter o pipeline de entrega: Babysit (leva PR ou stack a merge-ready: checa conflitos primeiro, reporta rebase necessário, lida com threads de review e CI) e Shipping (separado: verifica cada PR com agente fresco, checa se verdictos antigos ainda descrevem o commit atual, aterra só a parte contígua verificada da stack). PR verde é pronto para decisão de merge — não é merge automático.

Comandos de investigação e design

  • /how — traça o sistema atual. Pergunta estreita: um explainer lê e responde. Subsistema maior: exploração dividida em 2–4 partes (ex.: um agente rastreia modelo de dados, outro segue caminho de requisição, terceiro lê config e métricas) e um explainer combina em um relato único — modelo mental (conceitos, fluxo de runtime, arquivos relevantes, arestas), não código anotado.
  • /why — busca evidência histórica em 7 categorias: source control, issues/tickets, documentos longos, team chat, monitoramento de infra, error tracking, product analytics. Um investigador por categoria disponível; modelo final combina evidências e separa fatos diretos de inferência. Buscas vazias também são reportadas — se nenhum ticket ou doc explica uma escolha, o leitor deve saber.
  • /teach — combina mecânica e história quando lista de arquivos não basta (“convince me it fixes the cause instead of the symptom”).
  • /recall — reconstrói contexto próprio: busca transcrições recentes do workspace atual + estado de Git/PRs; devolve brief curto com trabalho concluído, threads ativas, problemas recorrentes e próximo movimento útil.
  • /architect — 5 fases: (1) ground o problema (roda /how no entorno; /why se muda ownership/camadas), (2) esboçar várias formas começando pelo uso do caller (tipos, assinaturas e fronteiras de módulo derivam do uso — evita design elegante no próprio arquivo e estranho em todo uso), (3) checkpoint se solicitado (/architect with checkpoint aprova design antes de implementar), (4) implementar contra o esboço, (5) descartar o esboço quando atrito repetido (casts, campos optional sempre presentes, exceções repetidas, parâmetros não previstos) provar que está errado.
  • /arena — mesma tarefa a vários modelos; cada candidato em worktree/temp próprio e explica alternativas consideradas e rejeitadas; coordinator cria rubrica privada, modelo separado julga cada candidato, coordinator lê tudo de ponta a ponta; escolhe um candidato como base e dobra as melhores ideias dos outros (não é votação: um pode contribuir melhor modelo de erro ou interface menor). Convergência total é registrada como evidência; divergência selvagem indica prompt subespecificado e re-roda com brief mais claro.
  • /swarm — diferente de /arena: divide tarefa em fatias independentes ou braços de corrida declarados, espera todo worker e devolve um relato; cada worker responde PASS/ISSUES/BLOCKED com evidência. Arena = designs concorrentes; Swarm = cobertura (ex.: “check every package under packages/ against its check.sh. One worker per package. One report.”).
  • /interrogate — review multi-modelo: mesmo diff/intent/regras a vários modelos (diversidade de modelos, não personas); lead reviewer deduplica achados, nota concordâncias e classifica tudo em 4 grupos: act on / consider / noted / dismissed. A seção dismissed faz parte do resultado — mostra o que o lead rejeitou e por quê, permitindo sobrepor o julgamento. Nunca aplica mudanças automaticamente.

Configuração de modelos

/setup-pstack detecta os modelos disponíveis na conta Cursor e os atribui a papéis (implementação, investigação, julgamento, review), gravando ~/.cursor/rules/pstack-models.mdc. É arquivo de override: papel ausente cai no default do bundle; auto/inherit-parent herdam o modelo do chat pai (não nomeiam modelo — erro comum). Painéis aceitam listas — o número de modelos vira o número de revisores/candidatos. Defaults: código para Grok; mudanças difíceis/julgamento/prosa para Opus 5.5; painéis de review mistos (Opus 5.5 + Sol + Grok). Rotina pode usar Composer 2.5 para economizar frontier models. Após setup, abrir novo chat para carregar a rule.

Princípios e verificação

Os 23 princípios são micro-skills indexadas dentro de poteto-mode (lidas no início de trabalho multi-etapa; o índice abre a skill completa quando o princípio é acionado). Não são comandos — você cita o nome para direcionar a run, e a resposta deve nomear a decisão que o princípio mudou (repetir o nome não conta):

  • Reduzem código: Laziness Protocol (prefere deleção e menor mudança completa), Subtract Before You Add (remove caminhos mortos antes de novo design), Minimize Reader Load (reduz camadas e estado oculto).
  • Shape de arquitetura: Model the Domain (substitui condições dispersas por uma estrutura explícita), Boundary Discipline (valida dados externos na borda e mantém lógica interna limpa), Type System Discipline (estados inválidos difíceis de representar), Make Operations Idempotent (retries convergem ao mesmo resultado).
  • Definem prova: Prove It Works (checa o artefato real), Fix Root Causes (reproduz o sintoma e segue ao mecanismo), Sequence Work into Verifiable Units (cada passo pequeno termina com uma verificação).
  • Delegação prática: Guard the Context Window (leitura em massa para subagentes; resumos ficam no chat principal), Separate Before Serializing Shared State (escritores paralelos em worktrees separados, não locks ao redor de um diretório compartilhado).

Verificação é parte de primeira classe: “build passed” não é evidência. A verificação deve casar com o que mudou — mudança de CLI roda o comando real; mudança de UI percorre o fluxo mudado; migração replays input real; perf compara traces; storage lê o valor de volta. Onde o repo não tem meio confiável, /create-verification-skill inspeciona o repositório e escreve verify-<app> local com instruções exatas para 5 trabalhos (launch, health check, drive user-facing behavior, capture evidence, clean up só o que a verificação iniciou) + feature map (cada feature registra como o usuário chega, como o agente dirige e qual estado observável prova); pstack roda a skill uma vez antes de entregar. /maintain-verification-skill compara features mapeadas com o fonte atual e roda uma passada ao vivo — pode atualizar a skill, mas não pode esconder bug de produto editando a doc.

O modo de execução noturna (“run pstack while you sleep”) empacota esse fluxo para rodar sem supervisão. Padrão overnight: condição de término verificável (não duração — “zero old callers e todo parser fixture passa”, não “trabalhe 4 horas”); iteração = checar condição → uma mudança justificada → verificar resultado real → se melhorou, keep+commit; senão descarta → uma linha de decision log → repete. /loop é comando do Cursor (acorda por evento ou heartbeat), não skill do pstack. O decision log é TSV (tempo, fase, decisão, motivo, evidência, resultado), local por padrão; projeto grande pode commitá-lo quando revisores precisam do rastro para confiar no trabalho.

Implicações

Para um founder/PM, pstack é a materialização de “o agente precisa do mesmo onboarding que um engenheiro novo”: regras, skills, ferramentas e memória como o onboarding do agente, com playbooks como contrato de qualidade. O custo é adotar o ecossistema Cursor (ou manter a porta não-oficial pstack-claude para Claude Code/Codex) e calibrar os papéis de modelo — sem isso, o ganho de rigor vira só mais atrito. Vários agents em uma tarefa com frontier models somam tokens rápido: use Composer 2.5 para rotina e guarde Opus para as partes difíceis. Não use o fluxo completo para toda mudança — mover uma data de publicação ou corrigir uma frase não precisa de vários modelos, arena de arquitetura, decision log e verification skill; toda essa maquinaria tem custo. Pstack é para investigação profunda, review adversarial, prova de runtime real e trabalho autônomo auditável; para manter o humano perto de cada decisão com o menor processo que funciona, Flavio prefere fstack.

Open Questions

  • Qual o ganho medido de qualidade/paridade de resultados entre rodar com e sem /poteto-mode?
  • Como o custo de tokens/tempo muda quando painéis multi-modelo rodam por padrão?
  • Formato completo dos 47 skills (24 workflow + 23 princípios) não lido integralmente — leitura direta no repositório é target futuro.

Exclusões e extras

  • O que pstack NÃO inclui: /deslop, control-cli, control-ui (plugin separado cursor-team-kit); /create-skill, /babysit, /loop (built-ins do Cursor — o playbook Babysit do pstack substitui o fluxo built-in para status de PR); shipping avançado assume GitHub e Orchestrate depende de Graphite.
  • Benny: automation pack dormente (não registrado como slash skills; setup copia para repo alvo só com enable explícito). Pipeline: triagem de relatórios de bug no Slack (lê anexos de imagem/vídeo, pede passos de reprodução mais claros), checa Git/Slack/Notion para distinguir regressão de comportamento intencional, cria ticket; outro automation pega via /orchestrate, tenta reproduzir com computer use (para perf: traces de CPU e heap snapshots antes/depois), workers frescos verificam a correção contra o ticket, outros gravam vídeos antes/depois e abrem PR com evidência. Ainda WIP.
  • Skills menores instaladas: unslop (corta AI tells de qualquer prosa; poteto-mode aplica a toda prosa, inclusive suas próprias respostas), technical-writing (padrão em camadas para docs/RFC/README/PR messages/commits, sobre Diátaxis + Google dev style + Simplified/Global Technical English), no-comments (spawna subagente Comment Sicko para strip de comments antes de review; oferece transformar comments de restrição em type/runtime check/test/lint rule), tdd (teste falhante antes da correção — só quando pedido ou quando o bug tem teste local óbvio e barato), typescript-best-practices (reading/editing .ts/.tsx; ancora Type System Discipline em sintaxe TS), blast-radius (o que uma mudança pode quebrar fora do diff; prova o fato que a torna segura rodando código real), figure-it-out (design de playbook customizado auditável para migração grande ou tarefa sem playbook adequado), show-me-your-work (decision log TSV), make-bot-ui (página com botões que acordam Grok Bot via webhook; sender key em servidor local, acesso opcional por Tailscale), /bro (reescreve a última resposta em linguagem simples).
  • Personalização: /automate-me lê transcrições recentes, identifica preferências repetidas (delegação, verificação, código, prosa, processo) e cria .cursor/skills/<your-name>-mode/SKILL.md; /reflect (após tarefa difícil) envia transcript a vários revisores e um sintetizador separa accepted/rejected/backlog — nada muda sem sua aprovação, evitando que uma tarefa estranha vire regra permanente.

Sources

Visão de gráfico

Backlinks