Um ciclo com responsabilidades claras
Defina objetivo e plano, implemente na worktree, confira a evidência e entregue pelo núcleo. Cada fase tem um contrato; o resultado não depende de acreditar no relatório do agente.
Ler o guia →Sua atenção, no ponto certo
Escolha #Classic, #Maestro ou #Auto para o ciclo completo. #Fast atende ajustes pequenos dentro de seus limites. Os modos controlam pausas; permissões e provas continuam explícitas.
Ler o guia →Evidência antes de crença
Claims carregam comandos reproduzíveis. A baseline distingue falha anterior de regressão. CHECK independente e push comprovado separam implementação de entrega.
Ler o guia →Contexto com origem
OrkMind conecta memória governada e Company Brain. O contexto ajuda a decidir; ele não substitui o estado da thread nem concede autorização.
Ler o guia →Conceitos
Como as peças se conectam
O host apresenta, o núcleo verifica e o runtime implementa. Conheça as fronteiras antes de conduzir o primeiro ciclo.
Ler o guia →Comece pelo ambiente
Instale o CLI e confira os requisitos do seu projeto. A documentação acompanha configuração, fases e verificações. @orkastery/cli 0.5.0.
Documentação →npm install -g @orkastery/cli
ork doctorAponte três agentes para o mesmo repositórioe você recebe três agentes se atropelando,e um relatório dizendo que deu tudo certo.
O problema real não é o agente. É conduzir o trabalho: manter o roadmap, isolar threads, pedir a decisão certa, serializar o merge e reexecutar cada alegação.
A Orkastery ocupa esse papel. O método e o código são públicos; a prova acompanha o trabalho e pode ser reexecutada.
Evidência antes de crença
Pausa humana no lugar certo
Lacuna publicada como lacuna
Contexto com origem
Seis fases que nenhum agente pula
No ciclo completo, cada fase tem um contrato. Toque em uma fase para conhecer o que ela entrega. #Fast tem escopo próprio, limitado ao GO.
F1 · GOAL
o que vale a pena, e como se prova
Objetivo verificável, impact map, critérios de sucesso e claims com comando de verificação. Não implementa.
o ork exige Claim sem comando é recusada como claims.unverifiable.
F2 · PLAN
o caminho, com domicílio único por decisão
Tarefas, touch_paths, decisões D1..Dn com domicílio único e verify executável por tarefa. Não implementa.
o ork exige Plano sem verify executável não vira GO.
F3 · GO
a escrita, fatia por fatia
Implementação fatia por fatia, um commit atômico por tarefa, dentro da worktree da thread.
o ork exige Escrita fora da worktree da thread é barrada por lease.
F4 · CHECK
a desconfiança, com comando na mão
Verificação contra a baseline, review de código, testes, segurança e performance.
o ork exige Claim reprovada vira verify.regression ou claims.failed, com a saída real anexada.
F5 · SHIP
o merge, um de cada vez
Merge serializado, push provado por comando, roadmap atualizado e plano de rollback.
o ork exige Push só conta quando git ls-remote bate com o sha local.
F6 · MASTER
a nota, dada por gente
MASTER log com postmortem tipado, lições e o score humano de 0 a 5.
o ork exige Score sem justificativa é recusado, em qualquer modo.
O ciclo completo termina com MASTER log. #Fast tem contrato próprio, limitado ao GO. Implementação e entrega são resultados distintos.
Threads em paralelo, merge serializado
ork-pagamentos
GO
worktree própria · ledger próprio · score próprio
ork-relatorio
CHECK
worktree própria · ledger próprio · score próprio
ork-publicacao
SHIP
worktree própria · ledger próprio · score próprio
lease main-tree
uma thread mergeia por vez
as outras esperam em fila FIFO, não sobrescrevem
ship com push provado por git ls-remote
Exemplo ilustrativo de três entregas em paralelo. Para consultar seu projeto, use ork board --all.
-
main-treeo único gate de merge -
worktree-write:<thread>escrita dentro da própria worktree -
path:<glob>região de arquivos reservada -
board:<card>um card, um dono por vez -
service:<porta>porta local sem disputa
Exemplos de leases tipados com TTL. Threads que pedem a mesma região entram numa fila FIFO. ork board --all mostra o trabalho atual.
Quanta pausa você quer? Escreva uma #TAG.
Escolha onde o ciclo espera por você. Claims, verificação e políticas continuam valendo em todos os modos.
-
- pausa sobre
- objetivo, plano, evidências, com autorização antecipada de push
- use quando
- O padrão do ork init: premissas delicadas com entrega confiável.
- slugs de sessão
- goal, plan, f34, f56
-
- pausa sobre
- premissas
- use quando
- Solução clara e ágil, sem tradeoff pesado: uma pausa para alinhar as premissas.
- slugs de sessão
- f12, f345, master
-
- pausa sobre
- nada
- use quando
- Docs, estudos, pesquisas, configurações, auditorias, migrações.
- slugs de sessão
- full
-
- pausa sobre
- nada; o push para a base continua pedindo autorização
- use quando
- Pedido pequeno e claro, de minutos: uma fase só, sem cerimônia, com Claude Sonnet ou GPT Terra em esforço alto.
- slugs de sessão
- go
bloco que pausa e espera o veredito humano
bloco que segue sozinho, com decisão no ledger
O modo afrouxa a pausa. O modo nunca afrouxa a verificação.
Com Claude Code (claude-bg) e Codex (codex) homologados,
cada bloco pode abrir com runtime, modelo e esforço próprios, pelo
ork setup.
Sua atenção onde ela é necessária
- trabalhando
- esperando humano
- morta, estado carimbado
Uma sessão viva pode estar esperando uma pessoa. O radar distingue atividade, espera humana e encerramento com evidência.
Consulte as sessões antes de concluir que uma thread está trabalhando. O resultado depende do estado observado agora.
ork sessions hitlNão peça para acreditar. Rode.
Comandos reproduzíveis conferem o trabalho na árvore real. A baseline separa regressão de dívida anterior.
ork verify <thread>
npm --prefix core run test:ci
ork modos-
o agente afirma
Uma alegação precisa de prova executável.
-
claims.jsonl
A claim é um contrato, não um adjetivo: alegação, arquivo e o comando que a comprova.
-
ork verify
Reexecuta o comando no HEAD real, na worktree real, agora. Não no texto do modelo.
-
baseline de antes do GO
passava antes vira
verify.regression: o defeito é desta thread.já falhava vira dívida pré-existente: anotada, não imputada à thread.
sem baseline vira
verify.failed, sem chutar de quem é a culpa. -
gate bloqueado
Motivo tipado, evidência real e correção sugerida. O
ork fix openabre a spec da correção a partir do resultado do verify, não de prosa.
Motivos tipados de gate
Exemplos de motivos do núcleo. Consulte a política atual com ork retry policy.
-
artifact.missingcorrigir-dirigido -
claims.failedcorrigir-dirigido -
claims.unverifiablecorrigir-dirigido -
verify.regressioncorrigir-dirigido -
verify.failedcorrigir-dirigido -
tree.blockedsincronizar-worktree -
lease.busyreexecutar -
runtime.model-unavailablereexecutar -
runtime.unavailablereexecutar -
runtime.rate-limitedesperar-janela -
policy.violationescalar-humano -
human.pendingescalar-humano -
cost.violationsem-retry
cost.violation é o único motivo que
jamais recebe retry automático: reexecutar uma violação de custo é gastar de novo.
Contexto para a próxima sessão
ork gate next
A fase termina e o gate mede a ocupação da janela de contexto.
- runtime_reported
- estimated, por transcript
- informada, pelo host
- unavailable
Quando nenhuma fonte sabe medir, o veredito sai
same-session com decididoPor: ausencia-de-medida.
Decidir por dado que não existe é pior do que não decidir.
Uma lacuna nunca vira zero.
não
Mesma sessão. O trabalho continua onde está.
sim
Nova sessão, com handoff triado. Nada de copiar a sessão anterior inteira e entregar uma sessão nova já cheia.
A triagem em três níveis
-
Crítico
Vai inline, sempre: estado, decisões locked, critérios, claims.
-
Importante
Vira ponteiro
path#âncoracom o momento certo de resolver (retrieve_when). Pedido fora do momento volta sem o conteúdo. -
Resumível
Resumo curto, com proveniência obrigatória:
source,locatione o sha256 do arquivo de origem.
Com o OrkMind ligado, o mesmo ponteiro resolve por
busca semântica por tag. Com o OrkMind fora do ar, ele resolve por
path#âncora, e o fluxo de quem lê o handoff não muda em nada. A
degradação tem motivo tipado.
Aprender com a entrega
De 0 a 5, quão inteligentemente isso foi entregue?
entregou limpo, no caminho previsto
Demonstração do score, sem enviar uma nota. A nota real exige autoria humana e justificativa. Use ork master pedir para pedir a nota pelo canal autenticado; ork master --batch consulta a fila.
Classes tipadas de postmortem
Classe livre vira texto solto, e texto solto não agrega. Toda falha entra em uma destas:
- sem-falha
- erro-de-spec
- base-avancou
- conflito
- rate-limit
- modelo
- processo
- scope-creep
- outra