Começar
Comece pelo primeiro ciclo
Instale o CLI, confira o ambiente e transforme um pedido em trabalho verificável.
Instale e confira
Use Node.js 20 ou superior, Git e um repositório com pelo menos um commit: a thread parte do commit da base. O pacote se chama @orkastery/cli; o executável é ork. O núcleo não contém um modelo de IA. O runtime de agente configurado executa as fases: o claude-bg (o binário claude), que é o padrão, ou o Codex CLI. Esta documentação descreve a versão 0.6.10; confira a versão publicada com npm view @orkastery/cli version. O pacote traz nove dependências de runtime com versão fixa, entre elas os analisadores do grafo de código, que pede Node 20.19, 22.12 ou mais novo.
Só com o Codex, passe cada bloco dos modos permitidos para ele com ork setup <modo> --bloco N --runtime codex --model <modelo>. Depois disso, a falta do claude vira aviso no ork doctor.
npm install -g @orkastery/cli
ork doctor
ork demoPrepare o projeto
Execute ork init na raiz do seu repositório. Ele gera o manifesto, que define verificações, modo e integração com runtimes, e um bloco do Orkastery no AGENTS.md. O estado do ork (.orkastery/) e as worktrees das threads são da máquina, não do repositório: ficam fora do git sem mudar o seu .gitignore. Faça o commit do manifesto antes da primeira thread. Fora de um repositório git, o ork init recusa sem criar nada (init.fora-do-repositorio), e o ork doctor avisa quando o orkastery.yaml que leu fica fora do repositório, como o de um ork init antigo numa pasta acima.
Em seguida, responda à pauta de onboarding. Registre apenas nomes de variáveis de credenciais; os valores ficam no ambiente do processo ou no cofre do host. A etapa maestro também oferece as preferências da conversa: idioma, fuso e profundidade, ou o opt-out. Na versão 0.6.10, esse idioma (owner.language) também vale para o ork doctor, o ork init, o ork onboarding, o ork experiencia show, o ork thread new, o ork thread status, o ork phase list, o ork phase run, o ork verify, o ork ship, o ork pulse, o ork master, o ork retry plan, o ork retry run, o ork roadmap status e a ajuda, que falam inglês quando a escolha é o inglês; sem a escolha, decide o locale (LC_ALL, LC_MESSAGES, LANG). Os outros comandos seguem em português, e o --json não muda com a língua. Confira os valores efetivos com ork experiencia show --json; o guia de experiência de orquestração explica a instalação em cada host. Respondida, a etapa maestro grava o bloco owner no orkastery.yaml: faça o commit do manifesto de novo antes do primeiro ork ship, porque a árvore principal suja barra o merge com tree.blocked.
ork init --name "meu-produto" --abbrev prd
git add orkastery.yaml AGENTS.md
git commit -m "ork init"
ork onboarding
git commit -m "ork onboarding" orkastery.yaml
ork experiencia show --json
ork doctorCrie uma thread
Uma thread reúne objetivo, plano, implementação, verificação e entrega. Comece com um pedido pequeno e um critério observável. Com worktree.por_thread: true, o que o ork init grava, a thread nasce com a própria worktree e a branch ork/<slug>, sem flag; --dry-run mostra a worktree antes de criar e --sem-worktree cria sem ela, mas aí o ork ship na branch base é barrado. Use o ID retornado nos comandos seguintes; o ID de exemplo não é um recibo real.
Prefira claims com o teste focado: uma claim que roda a suíte inteira recebe aviso no registro e é recusada pelo ork ci prepare.
ork thread new "corrigir o filtro de data" --modo classic --dry-run
ork thread new "corrigir o filtro de data" --modo classic
ork thread status <thread>
ork phase list <thread>Feche a primeira thread em #Fast
O menor ciclo completo usa o modo #Fast: uma única fase, GO, cujo único ponto de HITL é aprovar o push. O ork phase run despacha o pedido para o runtime, que trabalha na worktree da thread. Registre a claim, o que o agente afirma mais o comando que a julga, e o ork verify a reexecuta no HEAD real com as verificações do manifesto. O ork ship faz o merge e o push com a sua autorização; sem o --autorizar-push, ele para com human.pending e mostra o comando que autoriza. O ork master por omissão fecha a thread com o índice derivado do ledger, e o ork thread status mostra status fechada.
Se o ork phase run parar com runtime.workspace-untrusted, rode claude uma vez na worktree, aceite a confiança no diretório e saia; depois, ork retry run <thread> despacha o GO de novo com o mesmo prompt gravado. O ork pulse mostra a mesma instrução. O quickstart do repositório detalha cada etapa no #Classic, que tem pontos de HITL também no objetivo, no plano e nas evidências.
ork thread new "corrigir o filtro de data" --modo fast
ork phase run <thread> GO --prompt "<o pedido>"
ork claims add <thread> <arquivo> --claim "<alegação>" --verificar "<comando de teste>"
ork verify <thread>
ork ship <thread> --para main --autorizar-push <você>
ork master <thread> --aceitar-omissao
ork thread status <thread>Confirme antes de avançar
Um ork doctor bloqueado impede novo despacho; um aviso nunca bloqueia. Cada falha traz a correção: antes do ork init, por exemplo, o manifesto ausente aponta ork init. Resolva a causa indicada e execute-o novamente. A demo é um exercício local de uma alegação que falha e depois passa; não comprova que seu projeto está pronto para publicação. A linha analisadores do grafo mostra as versões do typescript e do micromark que o ork grafo usa e, quando faltam, avisa com a correção.
Ative no seu host
Copiar os arquivos do adaptador não ativa o plugin do Claude Code: rode a ativação que o instalador imprime e depois instale o servidor MCP do projeto. Numa sessão aberta no projeto, diga orkastery maestro ou use /orkastery:ork; as fases são /orkastery:goal, /orkastery:plan, /orkastery:go, /orkastery:check, /orkastery:ship e /orkastery:master. No Codex, ork adapter install codex põe a entrada $ork nas skills do projeto.
O mesmo plugin, sem os hooks do projeto, também sai do marketplace do repositório. Use um dos dois caminhos, porque os dois se chamam orkastery.
ork adapter install claude-code
claude plugin validate "$PWD/.claude/plugins/orkastery"
claude plugin marketplace add "$PWD/.claude/plugins/orkastery" --scope project
claude plugin install orkastery@orkastery --scope project
ork mcp install --project "$PWD" --host claude-codeExperimente sem conta
ork demo funciona offline e sem conta: mostra uma claim falsa reprovada e a corrigida aceita. Para contribuir com o núcleo, a suíte hermética do CI não exige runtime de agente. A execução de fases usa o runtime e o perfil configurados no projeto.
ork demo
ork --version