Prumo

English · Português (Brasil)

Prumo é um projeto independente inspirado no graph-foreman, de JrSantiaggo, e orientado por PO First: planos aprovados, pesquisa e planejamento por fase, execução ordenada por dependências, revisão independente, evidências de validação e um dashboard local. O mesmo fluxo atende software, dados, automação, migrações e outras demandas.

O plano define o resultado esperado; o motor controla estados e registros. O ambiente de IA executa o trabalho e dispara seus agentes.

Contratos novos declaram o escopo de escrita antes da execução: caminhos investigados, ausência de escrita em arquivos ou escopo que ainda precisa de pesquisa. Recursos compartilhados identificam conflitos além dos arquivos, como alterações na mesma tabela do banco. A discussão esclarece dúvidas, o planejamento detalha a abordagem, a execução respeita o escopo aprovado e a revisão independente confere a entrega contra a referência anterior à execução. O dashboard explica a prontidão e os impedimentos. Contratos antigos permanecem compatíveis; adotar a política explícita exige uma atualização aprovada do plano.

Harnesses de IA compatíveis

O Prumo leva o mesmo fluxo orientado por evidências aos dez harnesses apresentados no guia integrado. Cada harness preserva seus próprios modelos, controles de planejamento e capacidades de agentes.

| Claude Code | Codex | Kiro | DeepSeek Harness | Antigravity | |:---:|:---:|:---:|:---:|:---:| | /prumo | $prumo | /prumo | /prumo | /prumo |

| OpenCode | Grok Build | GitHub Copilot | Hermes Agent | OpenClaw | |:---:|:---:|:---:|:---:|:---:| | @prumo / /prumo | /prumo | /prumo | /prumo | /prumo |

Conheça o dashboard

Estas capturas vêm do guia integrado e usam um plano fictício de checkout. Abra Guia no dashboard para experimentar os mesmos controles sem alterar seus planos. As imagens mostram a interface em inglês.

Fases e tarefas. Acompanhe o plano aprovado, as dependências e os estados atuais das tarefas.

Filtros e contagens. Foque em um estado de tarefa preservando os totais do plano completo.

Detalhes da tarefa. Leia o resumo, a validação, as dependências vinculadas e a jornada; expanda o card para consultar as evidências completas.

O guia de integração dos harnesses também mostra os pontos nativos de planejamento e escolha de modelo do Antigravity, OpenCode e Grok Build.

Instalação

Requer Node.js 22 ou superior e o ambiente escolhido. O instalador não instala Claude Code, Kiro, Codex, DeepSeek Harness, Antigravity, OpenCode ou Grok Build, nem altera suas permissões de execução.

Instale a CLI, a skill Prumo, o PO First e o serviço de dashboard do usuário em uma etapa:

npm install -g @henri-ralmeida/prumo

O postinstall global do npm configura todos os ambientes suportados detectados e habilita o dashboard em http://localhost:4949. Após iniciar o dashboard, a instalação abre o board no navegador padrão. Se o navegador estiver indisponível, a instalação termina e informa o endereço para acesso manual. A prévia e a preferência de manter o dashboard desabilitado não abrem o navegador. Uma instalação npm local no projeto é inerte: não altera configurações globais nem registra inicialização. Se os scripts do npm estavam desabilitados, ou um novo ambiente foi instalado depois, repare a configuração com prumo install --all.

Ao menos um ambiente configurado com sucesso é preservado e o dashboard é habilitado mesmo se outro falhar, mas o comando retorna código diferente de zero e informa a configuração incompleta. Se nenhum puder ser configurado, a instalação retorna erro e não habilita o dashboard. Repetir o comando retoma com segurança, sem duplicar arquivos, blocos gerenciados ou registros de inicialização.

Você também pode abrir o instalador interativo, escolher um ambiente ou conferir a prévia:

| Destino | Comando | |---|---| | Detectar e escolher ambientes disponíveis | bunx @henri-ralmeida/prumo@latest install | | Todos os ambientes detectados, sem perguntas | bunx @henri-ralmeida/prumo@latest install --all | | Claude Code | bunx @henri-ralmeida/prumo@latest install --claude | | Kiro | bunx @henri-ralmeida/prumo@latest install --kiro | | Codex | bunx @henri-ralmeida/prumo@latest install --codex | | DeepSeek Harness (DSH) | bunx @henri-ralmeida/prumo@latest install --dsh | | Antigravity | bunx @henri-ralmeida/prumo@latest install --antigravity | | OpenCode | bunx @henri-ralmeida/prumo@latest install --opencode | | Grok Build | bunx @henri-ralmeida/prumo@latest install --grok | | GitHub Copilot | /prumo | Skill pessoal e instruções gerenciadas de projeto para CLI e VS Code: ~/.copilot/skills/prumo, .github/copilot-instructions.md | | Reparar após scripts npm desabilitados | prumo install --all | | Conferir mudanças de ambientes e dashboard | prumo install --all --dry-run |

Ele detecta ambientes por configurações reais ou comandos no PATH (claude, kiro-cli / kiro, codex, dsh, agy / antigravity, opencode, grok). O DSH também pode ser detectado por sua estrutura global oficial sob um DSH_HOME não vazio, com fallback para ~/.dsh; Antigravity, OpenCode e Grok Build podem ser detectados pelas raízes de configuração existentes. Uma pasta .dsh vazia ou apenas .dsh/AGENTS.md dentro de um projeto não basta, e pastas de configuração vazias também não bastam. O menu mostra somente os ambientes detectados, inicialmente todos marcados. Use as setas para navegar, Espaço para marcar/desmarcar, A para todos/nenhum, Enter para instalar ou Esc para cancelar. A instalação é por usuário e vale para seus projetos; nenhuma alteração é aplicada antes da seleção.

Para instalar em todos os ambientes detectados sem perguntas, inclusive em scripts:

bunx @henri-ralmeida/prumo@latest install --all

Sem terminal interativo, use --all ou uma opção explícita de ambiente. Se nenhum ambiente for detectado, o instalador informa isso sem gravar arquivos. Uma flag explícita para um ambiente ausente encerra com código diferente de zero, identifica esse ambiente e não grava nada. Para escolher um ambiente diretamente:

bunx @henri-ralmeida/prumo@latest install --claude --lang pt-BR
bunx @henri-ralmeida/prumo@latest install --kiro --lang pt-BR
bunx @henri-ralmeida/prumo@latest install --codex --lang pt-BR
bunx @henri-ralmeida/prumo@latest install --dsh --lang pt-BR
bunx @henri-ralmeida/prumo@latest install --antigravity --lang pt-BR
bunx @henri-ralmeida/prumo@latest install --opencode --lang pt-BR
bunx @henri-ralmeida/prumo@latest install --grok --lang pt-BR

O idioma é detectado pelo país/região configurado no sistema operacional: Brasil seleciona português do Brasil; outras regiões ou configuração indisponível selecionam inglês. Usa a região residencial do Windows, as preferências regionais do macOS ou a localidade de endereços do Linux, independentemente do idioma de exibição/navegador. Não usa geolocalização por IP. Para escolher explicitamente, use --lang pt-BR ou --lang en. Por exemplo:

Essa preferência controla o dashboard, as mensagens da CLI e o idioma do PO First instalado. As regras do fluxo do Prumo usam uma fonte única em inglês e orientam os agentes a responder no idioma do usuário, salvo quando ele pedir outro. O PO First mantém modelos de instalação em inglês e português do Brasil.

bunx @henri-ralmeida/prumo@latest install --claude --lang en

Sem --lang, instalações existentes mantêm a preferência salva. O dashboard segue a instalação e não tem seletor de idioma separado. As respostas dos agentes seguem o idioma do usuário.

A instalação real também instala a CLI global persistente pelo npm; em um novo terminal, prumo -v e prumo update ficam disponíveis. Os arquivos dos ambientes continuam independentes do cache do Bun. --dry-run não altera CLI nem ambientes.

bunx @henri-ralmeida/prumo@latest install --claude --lang pt-BR --dry-run
bunx @henri-ralmeida/prumo@latest doctor --claude --lang pt-BR
bunx @henri-ralmeida/prumo@latest doctor --dsh --lang pt-BR

--dry-run apenas mostra mudanças nos ambientes e a criação ou reinício do serviço do dashboard. A instalação real mostra progresso enxuto; a prévia informa arquivos, backups e conflitos. Repita o comando para reparar ou atualizar; arquivos, blocos e registros de inicialização idênticos não são duplicados. --project <caminho> registra um projeto adicional e o inclui na busca por instalações e runs; pode ser repetido. O Prumo não varre o disco inteiro.

| Ambiente | Invocação | PO First | |---|---|---| | Claude Code | /prumo | Output style instalado e selecionado nas configurações | | Kiro | /prumo | Steering permanente e recursos explícitos dos agentes JSON encontrados | | Codex | $prumo / seletor de skills | Bloco no arquivo global de instruções efetivamente carregado | | DeepSeek Harness (DSH) | /prumo | Skill em <DSH_HOME>/skills/prumo e bloco PO First gerenciado em <DSH_HOME>/AGENTS.md | | Antigravity | /prumo | Skill nas duas raízes globais do Antigravity e PO First gerenciado em ~/.gemini/AGENTS.md | | OpenCode | @prumo (V2) / /prumo (V1) | Skill em ~/.config/opencode/skills/prumo e PO First gerenciado em ~/.config/opencode/AGENTS.md | | Grok Build | /prumo | Skill em $GROK_HOME/skills/prumo (ou ~/.grok/skills/prumo) e PO First gerenciado no AGENTS.md da mesma raiz |

Consulte o guia de integração dos harnesses para as raízes distintas do IDE/CLI do Antigravity, os caminhos de descoberta do OpenCode, as regras de projeto do Grok Build, os controles nativos de planejamento e os seletores de modelo. O Prumo preserva o catálogo e os padrões de modelo do harness; escolha o modelo atual nesse ambiente depois da instalação.

No DSH, DSH_HOME prevalece quando não está vazio; caso contrário, a raiz é ~/.dsh. O Prumo grava somente sua skill em <DSH_HOME>/skills/prumo e seu bloco PO First gerenciado no <DSH_HOME>/AGENTS.md global; com a raiz de fallback, esses caminhos são ~/.dsh/skills/prumo e ~/.dsh/AGENTS.md. install --all e o postinstall global incluem DSH somente quando ele é detectado. Update e reparo reutilizam instalações Prumo detectadas ou registradas, inclusive caminhos personalizados de DSH_HOME, sem criar uma instalação DSH do zero.

Estado do DSH: o Prumo oferece suporte ao DSH como quarto harness, mas nunca instala @deepseek-ai/dsh. A versão upstream validada nesta integração foi 0.1.6-alpha.2, que ainda está em alpha/developer preview e pode mudar de forma incompatível. install --dsh, doctor --dsh e dsh --profile headless --dump-config podem verificar a configuração estrutural sem credencial de provedor ou chamada de modelo. Uma conversa real com modelo depende da configuração de provedor do usuário e não foi comprovada por essas verificações.

O DSH já fornece descoberta nativa de skills, instruções globais em AGENTS.md, subagents e workflows nos perfis aplicáveis. O Prumo usa essas capacidades quando /prumo é invocado; não cria nem edita cordis.patch.yml, perfil DSH, plugin, subagent, workflow ou credencial e não substitui a orquestração própria do DSH.

PO First vale também fora do Prumo. Prioriza resultado, regras, escopo, decisões e evidência; não depende de outras skills pessoais. Ele liga cada critério material a evidência atual, pede uma contraprova independente contra o maior risco aplicável e encerra a investigação quando os critérios relevantes estão cobertos. O relato final começa pelo resultado observável. Sugestões aparecem apenas quando existe uma próxima ação útil: de uma a três em ordem de prioridade, com uma quarta somente para evitar falha, perda ou bloqueio crítico. No Claude, as instruções de programação permanecem habilitadas no estilo.

Abra uma nova sessão depois de instalar. doctor distingue arquivos instalados, configuração concluída e condições pendentes. Configurações locais, skills explicitamente desabilitadas e agentes Markdown que exigem conferência da herança são informados; o instalador não promete sobrepor políticas do ambiente. Inspeção de arquivos não comprova o comportamento de um modelo.

prumo status mostra harness, versão, idioma e identificador do conteúdo de cada instalação registrada. Também avisa quando um marcador antigo não guarda a identidade, quando o hash de engine.mjs diverge ou quando o conteúdo instalado difere deste pacote. prumo status --verify-install compara todos os arquivos distribuídos. doctor compara o conteúdo das instalações registradas no mesmo idioma, incluindo DSH. Antes de publicar uma mudança em arquivo distribuído, incremente a versão SemVer; use uma pré-versão somente depois de ajustar a validação SemVer, que atualmente aceita apenas X.Y.Z. npm run check e npm pack também comparam o manifesto dos arquivos distribuídos com scripts/release-baseline.json; ele registra o tarball 1.3.16 publicado no npm e sua integridade SHA-512. Atualize essa referência somente com o conteúdo exato do pacote depois de uma publicação.

Operações do dashboard

prumo dashboard status
prumo dashboard logs
prumo dashboard enable
prumo dashboard disable
prumo dashboard

status informa registro, processo, versão, conteúdo, origem, caminho, porta, URL e o mecanismo de inicialização escolhido. logs mostra os eventos recentes de ciclo de vida, com histórico limitado: inicialização, disponibilidade, avisos, erros fatais, sinais e um processo registrado que depois desapareceu. enable registra a inicialização para o usuário atual e inicia o servidor imediatamente: no Windows, tenta primeiro o Agendador de Tarefas; se a tarefa do usuário não puder ser criada, o Prumo usa automaticamente uma única entrada oculta na pasta Inicializar do usuário atual, sem pedir acesso de administrador. O macOS usa um LaunchAgent, e o Linux usa um serviço systemd do usuário com fallback XDG. Reinstalações e atualizações preservam o mecanismo escolhido. Um reinício espera o processo gerenciado anterior liberar a porta e confirma o identificador de conteúdo servido, mesmo quando a versão textual coincide. disable encerra um processo Prumo identificado com exatidão e remove somente o registro gerenciado; essa escolha sobrevive a reinstalações e atualizações. prumo dashboard sem complemento executa o servidor em primeiro plano. O rodapé mostra discretamente a origem, a versão, o identificador de conteúdo e o caminho do pacote servido; /api/about retorna esses mesmos dados.

O servidor escuta somente em 127.0.0.1:4949 e é somente leitura. Ele descobre workspaces centrais conhecidos e projetos registrados em installations.json, escolhe a run atual modificada mais recentemente, percebe novas runs sem reiniciar e mostra estado vazio quando nenhuma existe. Ele não executa tarefas, edita o estado do grafo, sincroniza planos nem varre o disco.

O dashboard mantém todos os cards no lugar enquanto os filtros reduzem a opacidade do trabalho não relacionado. Os filtros cobrem todos, concluídos, incompletos, aguardando dependências, prontos para discussão, em discussão, prontos para planejamento, planejando, prontos para executar, executando, revisando, bloqueados, falhos e ignorados; done e skipped são terminais. Ligue o contexto de dependências para revelar predecessores, sucessores diretos e suas curvas. A densidade é detalhada até 24 tarefas, compacta até 100 e densa acima disso; as fases também quebram conforme a largura da janela, e o painel lateral pode ser recolhido sem perder seleção ou navegação.

Em problemas de inicialização ou porta, comece por prumo dashboard status. Se outro Prumo ocupa a porta 4949, a configuração reutiliza ou reinicia o serviço gerenciado. Se for outro processo, o Prumo informa o conflito e nunca o encerra; resolva o processo identificado e execute prumo dashboard enable.

Atualizar os ambientes instalados

O instalador e o atualizador disponibilizam o comando curto:

prumo update --dry-run
prumo update

bunx @henri-ralmeida/prumo@latest update oferece a mesma atualização em qualquer pasta. Uma atualização real instala ou atualiza a CLI global, atualiza Prumo/PO First em todos os ambientes instalados detectados e reinicia o dashboard habilitado. Um dashboard disable explícito continua respeitado. --dry-run apenas mostra essas alterações. O npm precisa estar disponível; falha no download mantém as instalações intactas.

Atualizações normais mostram uma barra colorida e compacta de progresso por etapas em terminais interativos e terminam com Prumo atualizado com sucesso, seguido da versão instalada em Prumo v<versão>. Use prumo update --dry-run para ver a prévia detalhada de arquivos e conflitos. O instalador registra ambientes e caminhos personalizados em ~/.local/share/prumo/installations.json. A atualização também reconhece marcadores existentes do Prumo nos locais padrão e nos projetos informados com --project. Preserva o idioma de cada instalação, salvo uso de --lang, e reutiliza os backups e o tratamento de conflitos da instalação. Ambientes que contêm somente graph-foreman ficam fora da atualização. Não retoma planos nem cria tentativas. Após prumo update concluir, prumo -v mostra a versão publicada usada na atualização.

A atualização confere o conteúdo instalado, não apenas a versão salva. Ela reaplica arquivos quando uma cópia gerenciada diverge, uma ativação anterior continua pendente ou a CLI global está ausente. Um marcador de instalação danificado só é recuperado quando aquele ambiente/caminho exato está registrado e um backup do Prumo contém o original conferido byte a byte; caso contrário, a instalação continua pendente para reparo explícito. Uma atualização interrompida preserva seu checkpoint e as notas de versões perdidas até todos os conjuntos concluírem. Uma CLI global mais nova que o latest do npm nunca é rebaixada.

Executar install novamente é seguro. Ambientes completos na mesma versão são informados como já instalados, sem regravar arquivos nem criar backup. Instalações antigas, incompletas ou alteradas seguem as verificações normais de prévia, backup e conflito.

Instalação ao lado do graph-foreman

Use o mesmo comando install para instalar Prumo separado de uma instalação existente do graph-foreman. Para todos os ambientes detectados, confira a prévia e depois aplique:

bunx @henri-ralmeida/prumo@latest install --all --dry-run
bunx @henri-ralmeida/prumo@latest install --all

Omita --all para escolher pelas caixas de seleção, ou use uma opção explícita como --claude, --kiro, --codex, --dsh, --antigravity, --opencode, --grok ou --copilot. Se a instalação estiver dentro de um projeto, execute na pasta dele ou acrescente --project "<caminho-do-projeto>". Essa primeira troca usa install; update só atualiza ambientes que já contêm Prumo. Depois da migração, use a invocação de skill nativa do ambiente selecionado; a skill original /graph-foreman permanece intacta em sua pasta separada.

Quem tem somente graph-foreman mantém a skill e os planos intactos. Prumo usa seu próprio armazenamento e não importa esses planos automaticamente. A cópia de compatibilidade ocorre somente quando uma instalação anterior do Prumo é identificada pelo marcador de produto e versão do Prumo.

• Instala Prumo na mesma raiz de skills, copia arquivos adicionais da instalação legada quando não há conflito, confere a instalação e preserva a pasta original da skill graph-foreman.
• Para instalações antigas do Prumo, copia dados centrais duráveis do namespace histórico ~/.local/share/graph-foreman para ~/.local/share/prumo, preservando a pasta original inteira. Arquivos gerados de execução permanecem na origem. As runs do Prumo dentro de projetos ficam no lugar.
• Confere a cópia e detecta alterações concorrentes sem apagar arquivos da origem. Reverter a instalação não reverte os dados de runs copiados; backups antigos que registraram uma realocação mantêm suas verificações originais de reversão.
• Aplica cada conjunto separadamente. Arquivos personalizados conflitantes, configuração inválida, caminho vinculado ou arquivo ocupado impedem somente aquele conjunto. O instalador não encerra processos.
• Confere os bytes gravados e reverte o conjunto antes de informar sucesso em caso de falha. Alterações concorrentes são detectadas.

O backup informa o comando de reversão:

prumo restore "<diretório-do-backup>"

A reversão recusa sobrescrever arquivos que você editou depois. Os planos continuam no estado atual: reverter uma instalação não deve apagar trabalho em andamento. Mantenha sua rotina de backup dos dados de negócio; o instalador não captura uma imagem consistente de todos os planos ativos.

O dashboard habilitado é reiniciado depois de instalação ou atualização para servir a versão instalada. Um dashboard desabilitado permanece desabilitado.

Migrar uma run existente

Depois de atualizar o Prumo, execute a migração pela CLI instalada:

prumo migrate --check --run <nome-da-run>
prumo migrate --run <nome-da-run>

--check é somente leitura e informa os campos estruturais e contratos que precisam de migração. migrate atualiza uma run legada segura no próprio lugar, cria o backup versionado state.pre-migrate-v<schema>.json, preserva ids, dependências, evidências, tentativas e todas as tarefas done/skipped, e deixa fases adotadas pendentes sem abrir discussão ou planejamento. O comando é idempotente. Trabalho ativo ou rodada aberta que torne a conversão insegura adia a migração e informa o bloqueio. Os comandos do motor também tentam a mesma migração automaticamente quando for segura; altere a fonte aprovada e use sync-plan para mudanças de contrato em vez de editar state.json.

Executar um plano

Apresente e aprove o plano global no modo nativo de planejamento do ambiente de IA. Se esse modo bloquear escrita ou despacho de agentes, saia dele depois da aprovação. Então invoque a skill instalada do Prumo (/prumo, $prumo ou o seletor/ferramenta de skills do harness) para o plano aprovado. O motor registra despachos; quem cria agentes é o ambiente. Sem suporte a planejadores dedicados, executores ou revisores independentes, o fluxo deve informar a limitação.

O fluxo atual tem dois níveis de planejamento. O modo Plan/Spec global define e aprova o grafo. Cada fase então segue discutir → planejar → executar → revisar: primeiro o orquestrador registra a fase em discussão, pesquisa e faz ao menos uma pergunta contextual na conversa principal. Quando as áreas cinzentas relevantes estão fechadas, confira as ferramentas e permissões reais antes de planejar; nunca deduza suporte a subagentes ou gravação pelo nome do harness. Um planejador somente leitura pesquisa cada tarefa e grava somente seu artefato task-plan-<id>.json separado e imutável. Se não houver subagente planejador, informe essa limitação e deixe o orquestrador planejar localmente com pesquisa somente leitura. Se o planejador não puder gravar, ele retorna cada JSON completo em um bloco aberto com ```json, precedido pelo nome exato do arquivo; o orquestrador decodifica entidades HTML em valores de texto, valida e grava o artefato antes de concluir o planejamento. Planejar não implementa arquivos de produto nem edita o estado do grafo.

Uma fase fica disponível para discussão e planejamento somente quando todas as dependências externas de todos os membros não concluídos estão concluídas ou puladas. Um membro bloqueado segura a fase inteira; dependências internas bloqueiam apenas execução. O usuário pode escolher fases independentes para planejar em paralelo, independentemente da numeração. Preserve o grafo aprovado em vez de mover tarefas ou remover dependências para contornar bloqueios. Quando o usuário nomeia explicitamente uma tarefa existente, ela é o limite do planejamento: uma discussão, um planner e nenhuma tarefa auxiliar ou planejamento de irmãs sem aprovação explícita.

Resolva $ENGINE como scripts/engine.mjs dentro da skill Prumo instalada. A passagem completa da fase é:

node "$ENGINE" begin-phase-discussion F1
# Faça e responda às perguntas da fase na conversa principal.
node "$ENGINE" finish-phase-discussion F1 --context "$PRUMO_ROOT/.specs/graph/plans/discovery-F1.json"
node "$ENGINE" plan-phase F1 --agent plan-F1
# O planejador somente leitura grava um task-plan-<id>.json por tarefa alvo.
node "$ENGINE" finish-phase-planning F1 --plan-dir "$PRUMO_ROOT/.specs/graph/plans"
node "$ENGINE" start T1 --agent executor-T1
node "$ENGINE" review T1 --agent reviewer-T1

| Estado no dashboard | Cor | Significado | |---|---|---| | Pronto para discussão (ready_for_discussion) | Violeta | A fase precisa de discussão atual na conversa principal; ela pode acontecer antes das dependências das tarefas terminarem | | Em discussão (discussing) | Violeta | Estado persistido da fase enquanto a conversa principal resolve áreas cinzentas relevantes | | Pronto para planejamento (ready_to_plan) | Azul | Estado persistido da fase após encerrar a discussão; o planejador pode começar antes das dependências terminarem | | Em planejamento (planning) | Rosa | Um planejador somente leitura prepara planos separados para as tarefas da fase | | Pronto para executar (ready) | Verde-azulado | O plano da tarefa está atual e suas entradas do DAG estão prontas |

A descoberta usa a caixa nativa de perguntas do ambiente quando disponível e um bloco estruturado na conversa principal quando não estiver. Ela registra pesquisa leve, respostas reais, cobertura PO First, decisões, ideias adiadas e o motivo de não restar área cinzenta relevante. O planejador a consome sem repetir a discussão. Mudanças materiais de escopo, contrato ou decisões compartilhadas da fase exigem nova discussão e planejamento do trabalho afetado; um defeito de plano marcado pelo revisor replaneja somente aquela tarefa. Achados comuns do executor e retries corretivos reutilizam o plano imutável quando ele continua correto e atual.

Obstáculos recuperáveis pertencem ao executor: ele inspeciona a falha, faz pesquisa adicional direcionada quando necessário, troca para alternativas seguras dentro do contrato aprovado e repete as verificações relevantes até entregar o plano inteiro. A passagem ocorre somente quando ele acredita, com base nas evidências, que todos os critérios passam. O revisor é uma etapa de validação, não uma triagem de falhas. Bloqueio antecipado fica reservado para falta de autoridade, decisão consequencial ainda indefinida, risco destrutivo não autorizado, dependência externa ainda indisponível após tentativas proporcionais ou impossibilidade comprovada. Mudanças de estratégia reutilizam o mesmo plano; o planejador continua executando exatamente uma vez por contrato aprovado.

Runs existentes no modo por tarefa preservam fluxo e histórico. Antes de continuá-los, a skill do Prumo inspeciona e normaliza todos os contratos legados não terminais na fonte aprovada e sincroniza o run original. A migração de contratos não amplia o escopo do planejamento: uma tarefa escolhida explicitamente mantém um único planner por tarefa; nos demais casos, as fases elegíveis são adotadas em ordem com begin-phase-discussion <fase> --adopt-legacy. Ela não cria um segundo run para evitar a migração; adoção insegura é recusada de forma atômica. Consulte artefato de planejamento por fase e planos em andamento.

Para novos planos, selecione um workspace central. No PowerShell:

$prumoDefault = Join-Path $HOME '.local/share/prumo'
if (-not $env:PRUMO_HOME) { $env:PRUMO_HOME = $prumoDefault }
$env:PRUMO_ROOT = Join-Path $env:PRUMO_HOME 'meu-workspace'
New-Item -ItemType Directory -Force -Path $env:PRUMO_ROOT | Out-Null

No macOS/Linux:

export PRUMO_HOME="${PRUMO_HOME:-$HOME/.local/share/prumo}"
export PRUMO_ROOT="$PRUMO_HOME/meu-workspace"
mkdir -p "$PRUMO_ROOT"

Planos locais preservam o workspace original. GRAPH_FOREMAN_HOME localiza dados antigos para descoberta e migração; não escolhe o destino de planos novos. O armazenamento padrão é ~/.local/share/prumo, configurável por PRUMO_HOME. Referências antigas em GRAPH_ROOT/PRUMO_ROOT acompanham um workspace central migrado quando o grafo antigo já não existe e o novo está presente.

Claude Code, Kiro, Codex, DSH, Antigravity, OpenCode e Grok Build locais, executados pelo mesmo usuário, compartilham a pasta central do Prumo. Os comandos criam as pastas ausentes. O acesso depende das permissões de cada ambiente; sessões na nuvem não compartilham automaticamente os arquivos locais.

Os scripts ficam em scripts/, junto da skill. Resolva caminhos a partir dela. Consulte a referência do motor para comandos, contratos e estados.

O que significa aprovar

Uma mudança funcional precisa de um passo executável marcado kind: "functional". Lint, compilação, tipagem e texto isolados não bastam. O motor executa comandos aprovados e registra saída, retorno, diretório e prazo; o revisor avalia se a evidência comprova o comportamento pedido.

Documentação e outras tarefas sem efeito de execução podem usar validationMode: "inspection", com inspectionReason e evidência. A exceção não deve mascarar mudança funcional. Um rótulo no plano não prova a qualidade do teste.

Atualizar um contrato aprovado não exige inventar falha ou nova tentativa. refresh-contract preserva trabalho e estado, inclusive bloqueios, e invalida recibos antigos. Desbloquear e retomar são decisões separadas; instalar não faz nenhuma delas.

Mantenha contexto e requisitos substituídos nos documentos aprovados e no histórico, critérios vigentes em expect e provas reais em run. Cada critério funcional precisa de evidência relevante; um rótulo funcional não comprova a tarefa inteira. Após reprovação real com mudança aprovada do contrato: registre a falha, edite o plano, rode sync-plan enquanto está failed, confira a definição persistida e siga com retry, planejamento exigido e start junto dos disparos reais dos agentes. Consulte reprovação e alteração de contrato. Após interrupções, retome da fase registrada; não invente tentativas por um disparo que não aconteceu.

Revisões corretivas retomam na primeira etapa inválida quando as verificações estáticas determinísticas anteriores declaram cacheable: true e cachePaths relativos seguros. O Prumo reutiliza esses recibos somente enquanto os arquivos declarados permanecem iguais. Verificações funcionais sempre executam novamente.

Idiomas e compatibilidade

O idioma inicial segue a região configurada no sistema, com inglês como fallback. Use --lang en|pt-BR ou PRUMO_LANG para uma escolha explícita. O dashboard segue a preferência salva na instalação e não tem seletor de idioma. Interface, mensagens e documentação têm inglês e PT-BR; instruções internas ficam em inglês e orientam responder no idioma do usuário. Identificadores, contratos, comandos e saídas dos processos não são traduzidos.

Os testes do instalador e motor para Windows, macOS e Linux, com Node.js 22 e 24, estão definidos em CI. Cada aplicativo depende dos sistemas suportados por seu fornecedor. A matriz de verificação distingue testes automatizados e sessões reais.

Publicação de atualizações

Enviar alterações para main executa o CI; isso não publica o pacote npm nem atualiza uma release do GitHub. Cada atualização publicada precisa de uma nova versão em package.json, verificações de release e changelog correspondentes, CI aprovado, tag Git e release do GitHub. Publique o arquivo testado no npm como @henri-ralmeida/prumo; a tag latest do npm determina a versão instalada pelos comandos acima.

Desenvolvimento e licença

npm test
npm run check
npm pack

Ao editar traduções: node scripts/build-dashboard.mjs --write. O dashboard incorpora o catálogo para funcionar em servidores antigos sem novas rotas de arquivos.

O Prumo nasceu como fork do graph-foreman de JrSantiaggo e hoje é um projeto independente, sob licença MIT. As alterações estão documentadas no changelog.

Hermes Agent e OpenClaw também aceitam a instalação do Prumo. Use prumo install --hermes --project <projeto> ou prumo install --openclaw --project <workspace> e confira os caminhos, permissões e planejamento no guia de harnesses.