Da intenção à entrega verificada.

01. Primeiros passos

Você precisa de Node.js 20 ou superior, Git e um runtime homologado instalado e autenticado: Claude Code ou Codex. Execute os comandos no terminal do projeto que deseja conduzir.

npm install -g @orkastery/cli
ork doctor

# Dentro do repositorio Git do seu projeto
ork init
ork onboarding
ork setup

doctor verifica o ambiente. init cria o manifesto do projeto. onboarding apresenta a pauta de configuração e permite retomar o que falta. Em setup, confira os runtimes e as escolhas de cada bloco.

Antes de continuar, resolva os itens obrigatórios apontados pelo diagnóstico. A configuração de memória é opcional para iniciar o fluxo.

02. Sua primeira entrega

Abra uma thread para um resultado concreto. Diga o que deve mudar e como alguém poderá verificar que ficou pronto. Uma worktree mantém as alterações dessa entrega separadas de outras threads.

ork thread new minha-entrega --modo maestro --worktree auto

# Substitua <id> pelo identificador que o Ork devolveu
ork phase run <id> GOAL --prompt "Descreva a entrega e como conferir o resultado"

Guarde o identificador mostrado pelo comando. Você o usará para acompanhar a entrega e consultar suas evidências.

O modo escolhido define onde o fluxo pausa. Uma aprovação de fase não substitui os testes e as políticas do projeto.

03. Critério de pronto e validação cruzada

Diga na abertura da thread o que prova que ficou pronto. O critério vira claim do núcleo, registrada antes de o trabalho começar, e não relato do agente. Com --exige-runtime-diferente, o CHECK precisa rodar num runtime que não fez o GO.

ork thread new checkout-mobile --modo maestro --worktree auto \
  --done "checkout passa no e2e :: npm run e2e" \
  --exige-runtime-diferente

Use ;; para vários critérios. O antigo envelope de objetivo (ork objective) foi aposentado em 24/09/2026; estas duas propriedades são o que ficou dele, agora em qualquer thread.

04. Organizar produtos, projetos e iniciativas

O portfólio torna explícito o contexto de negócio. Um produto reúne projetos; um projeto é uma demanda que pode ocupar um ticket de roadmap; uma iniciativa é uma frente de entrega dentro desse projeto. O ciclo do Ork pode entregar o projeto inteiro ou um conjunto declarado de iniciativas.

ork portfolio create product prod-loja --title "Loja"
ork portfolio create project proj-checkout   --title "Novo checkout" --parent prod-loja
ork portfolio create initiative init-mobile-first   --title "Checkout mobile" --parent proj-checkout

ork portfolio list project
ork portfolio show proj-checkout

ork portfolio inspect <id> --json mostra a entidade, a origem e os ciclos com as lacunas explícitas. O Ork valida pais e dependências antes de gravar.

05. Usar nos hosts de agentes

Prepare o adaptador e o servidor MCP no próprio projeto. O instalador preserva configurações existentes e deixa a ativação pendente para o consentimento do cliente.

# Execute na raiz absoluta do projeto
ork adapter install claude-code
ork mcp install --project "$PWD" --host claude-code

ork adapter install codex
ork mcp install --project "$PWD" --host codex --owner-permissions orchestrate

Abra uma nova sessão na raiz do projeto. No Claude Code, invoque /orkastery:ork. No Codex, invoque $ork. Hermes e OpenClaw usam seus adaptadores finos para o mesmo núcleo. Escreva o pedido normalmente e inclua a modalidade, por exemplo: #Maestro implemente e publique esta entrega.

O agente pode iniciar a thread, acompanhar o estado, pedir uma decisão, retomar e apresentar a entrega usando as ferramentas estruturadas do projeto. --owner-permissions orchestrate é um opt-in local do Codex para três operações do dono; não concede shell irrestrito nem elimina os pedidos de consentimento do cliente.

Decisões humanas aparecem como formulário nativo na sessão e ficam ligadas ao pedido correto. Não habilite respostas automáticas para esses formulários. Em outra worktree, prepare e confira novamente a descoberta do MCP.

06. Escolher o modo

Escolha pela quantidade de acompanhamento que a entrega precisa. A verificação continua obrigatória em todos os modos.

Consulte ork modos para ver o contrato exato dos blocos na sua instalação.

07. Acompanhar e responder

ork board --all
ork pulse --json
ork orquestracao status
ork sessions hitl --so-paradas

Você não precisa perguntar o status: a cada hora chega um resumo com quantas decisões estão pendentes, quantas são urgentes, quantas bloqueiam uma thread e quantas são críticas, e a pergunta "posso mandar agora?". Com o seu sim, as perguntas chegam em lotes de até cinco, cada uma com alternativas de a a d e uma recomendada. O que é óbvio chega decidido e informado.

O board mostra as threads. O pulse consolida os sinais de condução. O status de orquestração e o radar de sessões ajudam a localizar pausas, impedimentos e falhas.

Na sessão do Claude Code ou Codex, peça para o Ork mostrar o andamento ou o próximo passo. Quando aparecer um pedido humano, confira a thread, a fase e a pergunta antes de responder. Uma autorização vale para a ação apresentada e não para todas as ações futuras.

Entender o radar e a sincronização de pedidos humanos ↗

08. Verificar e publicar

Uma claim liga uma afirmação a um comando que pode comprová-la. Se a verificação reprovar, corrija a causa e execute-a novamente antes de publicar.

ork verify <id>
ork ci prepare <id>
ork ci status
ork ship <id> --para main
ork master

ci prepare materializa o CHECK independente para o runner; ci status consulta o check ligado ao SHA exato. O SHIP exige esse contexto verde quando a política do repositório o torna obrigatório, repete as verificações e prova o SHA remoto após o push.

Ao final, o MASTER registra o que aconteceu, com um índice derivado do ledger: rodadas de correção, veredito do CHECK, CI vermelho antes do verde. A entrega é aceita por padrão, com registro; a sua nota, quando você der, sobrescreve.

09. Métricas via agentes

ledger stats agrega duração, tokens, SHIPs, lead time, espera humana, riscos preventivos e custo de referência. Cada campo informa cobertura; custo de referência serve para comparação e não representa a fatura do provedor.

ork ledger stats --desde 7d --json

# Declare os contrafactuais enquanto planeja uma thread
ork ledger estimate <id> --sem-ia 40 --ia-sem-ork 18   --por maestro --metodo "estimativa por tarefas"   --premissas "escopo fechado" --incerteza "+/- 25%"

As estimativas registradas no PLAN alimentam as comparações de tempo sem Ork e sem IA. Sem amostras, o ROI permanece indisponível em vez de inventar uma economia.

Peça a Hermes, OpenClaw, Claude ou Codex para apresentar o pulse, o board ou as métricas com fonte e período. O agente consulta o estado canônico do Ork; não existe um cockpit web paralelo.

10. Orquestração nos agentes

A interface oficial de condução é a conversa autenticada com Hermes, OpenClaw, Claude ou Codex. Diga o resultado desejado, o modo e o escopo; o host traduz a intenção para operações tipadas do Orkastery e devolve status, decisões pendentes e evidências na mesma sessão.

GOAL, PLAN, GO, CHECK, SHIP e MASTER continuam no núcleo determinístico. Trocar de host não troca a thread nem cria outra verdade: objective, claims, logs, receipts e Company Brain preservam a identidade compartilhada.

O OrkMind Web permanece como workspace de conhecimento. Ele permite consultar e escrever documentos, decisões, memórias e entidades autorizadas, mas não inicia, aprova, pausa nem configura execuções. As antigas superfícies Cockpit e Kanban foram retiradas do produto.

11. Memória e Biblioteca

Consulte ork memory status para saber qual regime está efetivamente em uso. O modo de arquivos permite começar localmente; a integração com OrkMind depende da configuração e da disponibilidade do serviço.

No regime OrkMind, o Ork usa o tenant declarado, consulta contexto por tags e publica somente as origens autorizadas. Uma configuração solicitada não prova que a conexão está ativa: leia o regime efetivo e qualquer diagnóstico de degradação. Guarde credenciais fora dos documentos e use referências de ambiente na configuração.

No OrkMind Web, /knowledge é a Biblioteca principal. Ela reúne o recorte autorizado de memórias, documentos, decisões e entidades do Company Brain. Tipo ontológico, coleção de memória e origem são dimensões separadas; /memory continua sendo a superfície operacional legada. Produtos, projetos e iniciativas podem aparecer sem coleção.

Conhecer o OrkMind →

12. Usar o Company Brain

O Company Brain conecta o catálogo prod → proj → init ao histórico da factory: fases, pedidos HITL, decisões, resultados, claims e artefatos conservam identidade, origem e revisão. Ele não transforma conteúdo lembrado em autorização.

ork brain status
ork brain inventory
ork brain query --help
ork brain receipts

# Operações duráveis de criação
ork creation list --json
ork creation show <operation-id> --json

brain status mostra o transporte e a ativação efetivos. inventory e query são leituras; escritas protegidas passam por plano de ativação, aceite explícito, lease, receipt e readback. sync, reconcile e rollback preservam histórico e publicam falhas de forma explícita.

A criação do portfólio usa journal durável e chave de idempotência. Se o processo cair entre etapas, consulte a operação e use resume ou compensate com a versão esperada; não recrie o mesmo projeto por fora.

As 23 coleções válidas organizam memórias e não são o catálogo. Uma memória na coleção project fala sobre um projeto; a entidade proj-* é o projeto com identidade e relações. A Biblioteca deixa essa diferença visível e não cria cópias automaticamente.

Hermes, OpenClaw, Claude Code e Codex usam adaptadores finos para chegar ao mesmo núcleo. Confirme o adapter instalado e a identidade do host; a paridade é de contrato e evidência, não de interface visual. A expansão para organizações, geografias, sistemas, Atlas e cuidadores permanece no C2.

13. Documentação de produto e roadmap

O produto e o roadmap podem viver no seu repositório, em Markdown com frontmatter, legíveis por uma pessoa com pressa e por agentes. Cada página afirma coisas conferíveis (arquivos, símbolos, contratos, comandos, commits), e o Ork reprova quando ela diverge.

ork docs init          # padrões, modelos, índices e lint no seu projeto
ork docs verificar     # página contra código, CLI e git; sai != 0 com erro
ork docs sincronizar   # mostra os fatos do ledger e do git que mudariam
ork docs sincronizar --escrever

O sincronizador grava só fatos: o commit do merge, a fase da thread, a branch criada. Ciclo, deploy, exposição e habilitação continuam sendo decisão de pessoa. Rode ork docs verificar no CI para barrar a divergência antes do merge.

14. Resolver problemas