Pular para o conteúdo

Guias

Conduza de dentro do Claude Code

Os mods do Orkastery no Claude Code: o que já existe, como carregar e o que ainda é plano.

O que já existe

A RM-059 quer levar a condução da fábrica para dentro da sessão do Claude Code em que você já trabalha, por mods: plugins de function hooks do Claude Code, que rodam dentro do cliente, reagem a eventos da sessão e desenham painéis, faixas e avisos. Na versão 0.6.10 existem os dez mods do plano, além da ponte:

  • A ponte (ork-ponte), a base dos outros mods: dá a cada um o papel da sessão (dono na sessão de quem conduz, fase nas sessões de fase, ou dormente), o retrato do núcleo pelo ork_maestro, a faixa acima do prompt e o registro do que um mod mostrou ao dono. Ela tem os papéis dono e fase.
  • A Torre de Controle (ork-torre): na sessão do dono, um painel com cada thread aberta numa linha, com o trilho das seis fases, o modo, quem conduz e desde quando, o bloqueio tipado numa frase curta, os pedidos ao dono e a ação que o estado da thread pede. O comando /torre abre o painel, e apertar a linha abre o detalhe da thread. Ela depende da ponte e só tem o papel dono.
  • O Clima de Cota (ork-clima): na sessão do dono, lê as janelas de limite da conta a cada medição do motor (session.measure), guarda a série e prevê quando cada janela acaba no ritmo atual. Só no alerta, a faixa da ponte diz qual retomada da fila não cabe antes de a janela acabar, quanto dela já foi usado, quando ela acaba e quando renova; o comando /clima mostra cada janela, a fila de retomada, as threads abertas paradas por cota e as contas do registro do ork accounts esgotamentos. Ele só lê e avisa: trocar de conta, de runtime ou de modelo fica com o núcleo e com o dono. Também depende da ponte e só tem o papel dono.
  • O Freio de Lote (ork-freio), o primeiro mod de papel fase: na sessão de fase, depois de cada lote de ferramentas, ele acha os arquivos que o lote mexeu (pelos caminhos das edições e pela diferença do git status, que pega também a edição feita por Bash) e as claims da thread que os citam, pede ao núcleo, em segundo plano, a conferência delas com ork claims conferir, no sandbox do verify, e devolve no lote seguinte o que quebrou: o id da claim, o comando e o fim da saída. Também avisa quando o lote mexeu fora dos touch_paths do plano. Ele vai sozinho às sessões de fase pelo despacho, com o adaptador instalado (ork adapter install claude-code), e precisa de um ork com ork claims conferir no PATH da sessão: sem ele, avisa uma vez que a conferência está indisponível e segue. Também depende da ponte.
  • O Radar de Colisão (ork-radar): na sessão do dono, a cada 10 min e no comando /radar, calcula o merge de cada thread aberta contra a origin/main local e entre as threads, antes do SHIP, sem worktree e sem gravar objeto no repositório (por git merge-tree --write-tree num temporário). O painel mostra o mapa de calor, os arquivos em conflito, o lease que cobre cada um e, como texto, o comando ork worktree sync <thread> --dry-run que resolve; a colisão nova vira uma linha na faixa da ponte. O fetch continua com o núcleo. Ele só lê, depende da ponte e só tem o papel dono.
  • A Mesa do Dono (ork-mesa): na sessão do dono, junta num painel o que espera por você. O comando /mesa abre o lote de até cinco perguntas, cada uma com a alternativa recomendada na frente, o porquê e a consequência das outras; as decisões que a fábrica tomou por você na semana, com como mudar e o custo de reverter agora e depois; e as paradas, só para leitura. O botão Decidir só pede ao núcleo o diálogo nativo do host (ork_request_decision, com o threadId e o pedidoId), e o código e a letra para o Telegram ficam sempre à vista; a prova de que o diálogo abre quando o pedido vem de um mod ainda está pendente do dono. A Mesa só decide por você pela decisão autônoma do núcleo (ork_decision_record), e só quando o pedido declara que segue a recomendada no prazo e passa nas quatro condições do núcleo; hoje o núcleo não marca nenhum pedido assim, então ela não decide nada sozinha. Nunca responde um pedido. Depende da ponte e só tem o papel dono.
  • A Sentinela do Condutor (ork-sentinela): na sessão do dono, mantém pelo núcleo a presença dela nesta máquina, com uma batida a cada 60 s, e a tira quando a sessão acaba; enquanto a presença vale, o condutor externo cede o despacho. Quando um ledger de thread muda, e a cada batida, ela relê o passo do condutor em cada thread aberta e despacha a fase seguinte das threads #Auto que o núcleo manda despachar, uma vez por turno e só pelo ork phase run; a retomada só roda o ork retry run quando o ork retry plan é automático. A cada 5 min, o que só o dono resolve no ork pulse vira notificação do sistema, com o próximo passo do núcleo, uma vez por texto, e entra no registro da ponte, para o Telegram não repetir. A faixa da ponte mostra as threads andando e as paradas, e o comando /sentinela mostra o passo de cada thread e o diário do que ela despachou, cedeu e avisou, e também pausa e retoma a Sentinela. Ela depende da ponte e só tem o papel dono.
  • O Portão de Tarefas (ork-portao), o segundo mod de papel fase: na sessão de fase do GO, faz do quadro de tarefas do Claude Code o quadro do plano. A tarefa só entra apontando uma tarefa do plano com touch_paths e verify, e só fecha com a conferência do núcleo aprovada (ork claims conferir --tarefa, no sandbox do verify), nunca com o verify rodado pelo mod; plano sem tarefa assim não ganha portão. Com runtime.agent_teams ligado no manifesto, desligado por padrão, o teammate ocioso recebe a próxima tarefa cuja região está livre, dentro dos tetos do dono, e o Portão não toma lease. Depende da ponte.
  • A Pista de Entrega (ork-pista): na sessão do dono, o comando /pista abre uma pista por entrega, do CHECK verde ao merge, com as oito etapas que o núcleo lê (CHECK, verify, bundle, branch, PR, CI, conflito e entrega), o texto do núcleo em cada uma que falta e o próximo passo com o comando dele. Só mostra botão para a ação que o núcleo declara disponível: publicar a branch pelo ork ship publicar, só em #Auto e #Maestro, e registrar a entrega pelo ork ship registrar-pr; fora desses modos, só o comando, para você rodar. Nunca chama o Git nem a CLI do GitHub. Depende da ponte e só tem o papel dono.
  • O Ritual do MASTER (ork-ritual): na sessão do dono, o comando /nota mostra as entregas dos últimos 7 dias que esperam a sua nota, inclusive as aceitas por omissão, com a prova de cada uma: o índice derivado do ledger, o POSTMORTEM e as claims. O botão Dar a nota pede ao núcleo o formulário nativo do host, com a nota de 0 a 5 e o porquê, e quem grava o MASTER, com recibo, é o núcleo; sem o diálogo, o código para o Telegram fica à vista. Depende da ponte e só tem o papel dono.
  • O Mensageiro de Sessões (ork-mensageiro), de papéis dono e fase: a resposta que você dá pelo diálogo nativo da sua sessão chega à sessão de fase claude-bg que parou esperando por ela, sem você precisar entrar nela. O núcleo prende o pedido ao turno que parou e confere a mensagem nas duas pontas, e na sessão de fase só entra o que ele confirma. A resposta informa a sessão, mas não autoriza o que só você aprova, como um gate ou um push, e pelo Telegram ela não sai. Depende da ponte.

Carregue na sua sessão

A Torre, o Clima, o Radar, a Mesa, a Sentinela, a Pista e o Ritual só ligam na sessão do dono, e o Mensageiro liga nela e nas sessões de fase (o Freio e o Portão, de papel fase, chegam às sessões de fase pelo despacho), que a ponte reconhece por duas coisas: o orkastery.yaml na raiz e o servidor MCP orkastery do projeto conectado. Os comandos abaixo vêm em três grupos: o servidor MCP do projeto; o adaptador do Claude Code, que deixa a cópia de cada mod em .claude/plugins/orkastery/mods/<mod>, e a carga deles na sessão por --plugin-dir; e, sem o adaptador local, a instalação pelo marketplace do repositório, no escopo do projeto. Os comandos da Sentinela estão na seção seguinte.

A API de mods pede o Claude Code 2.1.287 ou mais novo. No CI, o job mods instala o Claude Code 2.1.296, valida e testa cada mod e procura no binário cada evento que eles usam; nessa busca, os builds 2.1.288 e 2.1.289 reprovam, sem ui.notify.

Os dois marketplaces se chamam orkastery, e o local, registrado a partir de .claude/plugins/orkastery na ativação do adaptador, não lista os mods. Não troque um pelo outro num projeto que usa o plugin do adaptador: remover um marketplace desinstala os plugins que vieram dele, e o plugin do marketplace do repositório não traz o guard PreToolUse nem o MCP do adaptador.

ork mcp install --project "$PWD" --host claude-code

ork adapter install claude-code
claude --plugin-dir .claude/plugins/orkastery/mods/ork-ponte --plugin-dir .claude/plugins/orkastery/mods/ork-torre --plugin-dir .claude/plugins/orkastery/mods/ork-clima --plugin-dir .claude/plugins/orkastery/mods/ork-radar --plugin-dir .claude/plugins/orkastery/mods/ork-mesa --plugin-dir .claude/plugins/orkastery/mods/ork-pista --plugin-dir .claude/plugins/orkastery/mods/ork-ritual --plugin-dir .claude/plugins/orkastery/mods/ork-mensageiro

claude plugin marketplace add orkastery/orkastery
claude plugin install ork-ponte@orkastery --scope project
claude plugin install ork-torre@orkastery --scope project
claude plugin install ork-clima@orkastery --scope project
claude plugin install ork-radar@orkastery --scope project
claude plugin install ork-mesa@orkastery --scope project
claude plugin install ork-pista@orkastery --scope project
claude plugin install ork-ritual@orkastery --scope project
claude plugin install ork-mensageiro@orkastery --scope project

Deixe a Sentinela despachar

Com a sua sessão aberta no Claude Code e a Sentinela ligada e não pausada, é ela que despacha a fase seguinte das threads #Auto e faz o retry delas, e o condutor externo (por exemplo, um cron no gateway do Hermes) cede. Com a Sentinela pausada, ou com a sessão fechada (a presença vence 3 min depois da última batida), o condutor externo volta a conduzir. Na versão 0.6.10, o condutor externo do próprio ork é a batida da condução (ork conducao batida): ela lê a presença e cede o despacho e o retry enquanto a Sentinela conduz, menos a retomada da fase que parou por cota, que continua com a batida porque a conta da Sentinela também pode esgotar. Ela segue com o merge do PR verde, o registro da entrega e o MASTER por omissão, dentro da autorização durável do dono; com ela no cron, o script de fora deixa de ser necessário. A publicação da branch, o merge do PR verde e os avisos do Telegram ficam sempre com o condutor externo: a Sentinela não publica branch, não abre nem mergeia PR e não manda mensagem pelo Telegram.

Ela usa os comandos de presença do núcleo, na versão 0.6.10, e carrega junto com a ponte, pela pasta do adaptador ou pelo marketplace do repositório, como no bloco abaixo. O script do condutor externo fica fora do repositório, e a mudança nele é sua: uma vez por rodada, antes do laço de despacho, ele lê o status da Sentinela com --json e, enquanto presenca.ativa for true, pula o despacho da fase seguinte e o ork retry run das threads #Auto. A publicação da branch que só espera push, o merge do PR verde e os avisos ao dono ficam como estão; sem presença viva, o condutor externo conduz como antes.

Não há despacho duplicado, porque os dois condutores despacham só pelo núcleo: o ork phase run toma a condução da thread sob uma trava do kernel. Com dois pedidos no mesmo instante, um despacha e o outro sai sem sessão nova; com a thread já conduzida, o pedido sai 3, com conducao.em-andamento, e grava conducao_recusada; e o mesmo pedido de quem já conduz grava despacho_idempotente e devolve a sessão em andamento. A Sentinela ainda relê a condução logo antes de despachar, nunca usa ork conducao assumir e guarda o turno que já despachou. O despacho dela leva o canal do Claude Code e a sessão dela na correlação, e o phase_dispatch mostra de onde veio.

A Sentinela não escolhe a fase: segue a ação que o núcleo dá a cada thread no status. No #Auto, depois de uma fase concluída, sai a fase seguinte à prova mais adiantada que a sessão do bloco deixou: o artefato da fase (goal.md, plan.md, check.md) gravado depois do despacho, o produto na branch, que mostra que houve GO, ou o ship_done e o master_done. Se o bloco já passou do CHECK, nada sai: a entrega fica com o condutor externo e com o dono. O CHECK que terminou sem exatamente um veredito é redespachado, e o despacho que falhou antes de abrir sessão vai ao ork retry plan. Pendência do dono (thread num ponto de HITL, pergunta aberta, escalação) segura qualquer passo, e, sem pedido guardado na criação da thread (ork thread new --pedido), a Sentinela não despacha e avisa.

Recusa que passa (outro condutor, projeto sem vaga, pedido aberto, falha) não queima o turno: a Sentinela tenta de novo depois de 3 min, e a mesma recusa seguida dobra a espera até 30 min; só o despacho feito, ou o pedido repetido de quem já conduz, fica de vez. Se o seu condutor externo despacha pela última linha do ledger, ele pode repetir uma fase que a sessão do bloco já fez; ler a ação de cada thread no mesmo status evita isso.

Para conferir, o status da Sentinela diz se ela está ligada nesta máquina e o passo de cada thread, o ork phase list <thread> mostra o despacho com o canal do Claude Code e, na sessão do dono, o /sentinela mostra o diário; as duas últimas linhas do bloco pausam e retomam a Sentinela.

claude --plugin-dir .claude/plugins/orkastery/mods/ork-ponte --plugin-dir .claude/plugins/orkastery/mods/ork-sentinela
claude plugin install ork-sentinela@orkastery --scope project

ork conducao sentinela status
ork phase list <thread>

/sentinela
/sentinela pausar
/sentinela retomar

Nas sessões de fase

O despacho claude-bg passa um --plugin-dir por mod de papel fase, depois do plugin do Orkastery, quando a pasta instalada do mod tem exatamente os arquivos do INSTALADO.json e a versão do Claude Code atende o mínimo do mod. Mod que pede versão mais nova fica de fora, com os que dependem dele, e o despacho segue; arquivo a mais, link ou declaração inválida recusa o despacho com runtime.context.installation. Hoje, a ponte, o Freio de Lote, o Portão de Tarefas e o Mensageiro de Sessões têm o papel fase. O papel fica no orkastery-mod.json do mod (ork.mod/v1): para tirar um mod das sessões de fase, mude o papel no catálogo e reinstale o adaptador.

A prova da RM-059 mediu, no Claude Code 2.1.296, que um mod carregado por --plugin-dir numa sessão de fase recebe os eventos da sessão; o script core/scripts/prova-mods-sessao-de-fase.cjs refaz essa prova.

A fundação dos mods traz também duas peças do núcleo. O ork claims conferir reexecuta, no sandbox do ork_verify e sem gravar recibo, só as claims pedidas (--claims) ou o verify de uma tarefa do plano (--tarefa); um teste que cria processo pode reprovar ali e passar no ork verify. O ork thread new --pedido guarda o pedido da thread em pedido.md, com o sha256, e o ork prompt render sem --pedido usa esse pedido.

O que nenhum mod faz

Nenhum mod aprova gate, permissão, nota do MASTER, push ou tag pelo dono, nem fala como o dono. A regra mora em adapters/claude-code/mods/autoridade.json e tem duas guardas: node core/scripts/checar-mods.cjs reprova o mod pelo fonte, e a ponte recusa em tempo de execução. O Freio nunca roda o comando de uma claim, nunca grava estado de claim e nunca para o laço: quem verifica continua sendo o ork verify. A Sentinela lê só pelo núcleo, despacha e retoma só pelo ork phase run e pelo ork retry run e nunca usa ork conducao assumir. A Torre, o Clima e o Radar só leem, e a Mesa só pede o diálogo ao núcleo e nunca responde um pedido: ação com efeito abre o mod dono dela, quando ele está carregado, ou aparece como comando do ork, para você rodar.

Os mods rodam com as permissões do seu usuário, sem sandbox, e a API de mods do Claude Code está em acesso antecipado e pode mudar entre versões. Nada no núcleo depende deles: sem mod, o despacho e o ciclo seguem como antes, e o Telegram continua como canal.

O que vem depois

Na versão 0.6.10, as quatro ondas da RM-059 estão no código: a onda 0, a fundação descrita acima; a onda 1, com a Torre de Controle, o Clima de Cota, o Freio de Lote e o Radar de Colisão; a onda 2, com a Mesa do Dono e a Sentinela do Condutor; e a onda 3, com a Pista de Entrega, o Ritual do MASTER, o Mensageiro de Sessões e o Portão de Tarefas. O item segue em desenvolvimento, com a exposição parcial e a habilitação em andamento, e as provas que pedem o dono, como a do diálogo aberto a pedido de um mod, continuam com ele.