Pular para o conteúdo
Orkastery

ork · ai software factory

O motor da fábrica de software autônoma

Um CLI determinístico que conduz N loops de agentes por seis fases e verifica cada alegação no HEAD real. Sem LLM embutido.

instalação 
npm install -g @orkastery/cli
ork doctor
o que vale nesta máquina agora: node, git,
repositório, runtime adapter, manifesto.
sai diferente de zero quando está bloqueado.
Repositório no GitHub Pacote no npm

o ciclo

A looping thread

Toda demanda vira um ciclo fechado: worktree própria, estado em disco próprio, ledger próprio, score próprio. As fases são sempre seis; os modos apenas agrupam fases em blocos.

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.

Demanda pequena recebe fases compactas, nunca menos fases. Um fix de uma linha ainda tem GOAL, ainda tem MASTER log. Uma entrega sem MASTER log não aconteceu.

condução

Cinco modos, uma #TAG no pedido

Você escolhe quanta pausa quer escrevendo a #TAG no próprio pedido. O host extrai a tag chamando o núcleo, e a validação também é do núcleo. Selecione um modo.

4 blocos de sessão

3 pausas humanas

GOAL pausa PLAN pausa GO-CHECK pausa SHIP-MASTER
slugs de sessão
goal, plan, f34, f56
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.

o coração do produto

A maquinaria que não acredita em self-report

Este é o produto. O resto é conveniência.

  1. o agente afirma

    "Implementei X, e os testes passam."

  2. claims.jsonl

    A claim é um contrato, não um adjetivo: alegação, arquivo e o comando que a comprova.

  3. ork verify

    Reexecuta o comando no HEAD real, na worktree real, agora. Não no texto do modelo.

  4. 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.

  5. gate bloqueado

    Motivo tipado, evidência real e correção sugerida. O ork fix open abre a spec da correção a partir do resultado do verify, não de prosa.

Os 12 motivos tipados de gate

Nenhum bloqueio é uma string de prosa. Todo bloqueio é um destes, com ação de retry determinada.

  • artifact.missing corrigir-dirigido
  • claims.failed corrigir-dirigido
  • claims.unverifiable corrigir-dirigido
  • verify.regression corrigir-dirigido
  • verify.failed corrigir-dirigido
  • tree.blocked sincronizar-worktree
  • lease.busy reexecutar
  • runtime.unavailable reexecutar
  • runtime.rate-limited esperar-janela
  • policy.violation escalar-humano
  • human.pending escalar-humano
  • cost.violation sem-retry

cost.violation é o único motivo que jamais recebe retry automático: reexecutar uma violação de custo é gastar de novo.

go-fix

Correção tipo A, de uma linha, recebe reverify parcial: só o que foi afetado. Tipo B devolve a tarefa ao GO e exige reverify completo. O veredito sai por correção, além do veredito da rodada.

fila durável

Runtime bateu limite de uso? A fase não morre: entra numa fila durável com o horário de reset lido do próprio stderr do adapter, e é retomada na janela seguinte, sem humano no meio.

freio

Estourou retry.max_tentativas? Sobe para o humano e para até o #Auto. Autonomia sem freio seria só ausência de controle.

paralelismo sem colisão

N looping threads, sem atropelo

Rodar várias threads ao mesmo tempo é fácil. Rodar várias threads sem que elas se atropelem é o trabalho.

Exemplo ilustrativo de três entregas em paralelo. Para consultar seu projeto, use ork board --all.

  • main-tree o ú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

Cinco famílias de leases tipados com TTL. Duas threads pedindo a mesma região entram numa fila FIFO, em vez de escrever uma por cima da outra. E ork board --all responde a única pergunta que importa numa máquina com três roadmaps abertos: o que está rolando aqui, agora.

janela de contexto

O gate de tokens e o handoff triado

A janela de contexto acaba no meio da thread. Copiar a sessão inteira para a próxima entrega uma sessão nova já cheia e sem espaço para trabalhar. O ork tria.

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

  1. CRÍTICO

    Vai inline, sempre: estado, decisões locked, critérios, claims.

  2. IMPORTANTE

    Vira ponteiro path#âncora com o momento certo de resolver (retrieve_when). Pedido fora do momento volta sem o conteúdo.

  3. RESUMÍVEL

    Resumo curto, com proveniência obrigatória: source, location e 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.

condução proativa

O radar HITL

Detectar pausa, impedimento e espera por humano antes de o humano perguntar.

O incidente que criou este radar: uma sessão ficou parada pedindo um código de duas etapas, e o humano descobriu sozinho, horas depois. O monitor via a sessão "viva" e concluía que o agente trabalhava. O sinal mais forte de que alguém precisava do humano era lido como o oposto.

ork sessions hitl parte das sessões, não das threads: uma chamada classifica todas, e só as paradas pagam o preço de uma inspeção profunda, que separa quem espera resposta de quem morreu esperando.

  • 43sessões varridas
  • 8paradas
  • 9sde varredura
varredura periódica a cada 10 min 
ork sessions hitl
2 sessões pedem você agora: pergunta, opções e a
recomendação por tipo. Alarme repetido não avisa de
novo: alarme falso crônico ensina a ignorar o radar.

auditoria periódica

Hardening por estágio

Cobrança de maduro em produto nascente mata a velocidade; leniência de nascente em produto maduro mata o produto. Os packs ativos acompanham o estágio.

  1. nascente

    clean-code · reuse

    Só avisa: o builder cria livre e o auditor anota.

  2. crescendo

    + architecture · data-model · ux

    Achado crítico vira proposta prioritária no roadmap.

  3. maduro

    + security-privacy · process

    A recorrência propõe promover a policy de warn para block.

Varredura determinística da superfície de rede, sem LLM

  • SP8 rota sem guarda de autenticação
  • SP9 endpoint de administração exposto
  • SP10 rota sem limite de taxa
  • SP11 CORS permissivo
  • SP12 rota sem esquema de validação de payload

Quando a leitura não dá confiança, o achado sai com confiança baixa e o título diz requer confirmação humana. Falso positivo disfarçado de certeza é o defeito que esse módulo existe para evitar. O auditor também não tem direito a self-report: ork audit verify reexecuta as claims dos achados.

o fecho

Toda thread termina na mesma pergunta

De 0 a 5, quão inteligentemente isso foi entregue?

entregou limpo, no caminho previsto

Métrica diz quanto a entrega custou. O score diz se o caminho foi esperto. O ork recusa score sem justificativa, em qualquer modo; nos modos sem pausa de MASTER, a thread cai na fila de ork master --batch para você pontuar em bloco. Ela não some.

O POSTMORTEM só aceita nove classes

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

adaptadores de host

Seu host, seus runtimes

O ork não quer ser a sua interface. Ele quer ser o motor debaixo dela. Zero regra de negócio no host: a #TAG do seu pedido vira modo porque o host pergunta ao núcleo, e quem valida é o núcleo.

Os adaptadores abaixo conectam seu host ao ork. Para executar a sinfonia, os dois runtimes homologados são Claude Code (claude-bg) e Codex (codex). Escolha runtime, modelo e esforço por bloco com ork setup.

claude-code

Plugin com skills, subagentes de fase, comandos de condução e hooks de verificação.

<projeto>/.claude/plugins/orkastery

hermes

Skill roteadora fina, plugin que a declara e script de abertura de thread.

<projeto>/.hermes

openclaw

openclaw.plugin.json com 16 tools ork_*, cada uma uma chamada de CLI.

<projeto>/.openclaw

codex

Skill, MCP com ações do dono e CHECK nativo por codex review.

<projeto>/.codex

hosts e runtimes 
ork adapter list       os hosts e o destino de cada um
ork adapter show hermes  os 3 pitfalls de instalação do host
ork adapter install claude-code  exemplo para o host Claude Code
rode com --dry-run antes de instalar o host
ork setup  runtimes: Claude Code (claude-bg) e Codex (codex)

o contraste

Por que não só um agente solto?

um agente solto

uma fábrica conduzida

Três agentes no mesmo repositório editam os mesmos arquivos.

Uma worktree git por thread, e escrita fora dela barrada por lease.

O agente diz que os testes passam, e você acredita.

O verify reexecuta o comando da claim no HEAD real e anexa a saída.

O contexto acaba e a sessão nova nasce entupida de colagem.

Gate de tokens mede a janela e o handoff triado passa só o que importa.

O merge é uma corrida, e o último a chegar sobrescreve.

main-tree é o único gate de merge: uma thread mergeia por vez.

Deu errado, e ninguém sabe dizer onde nem por quê.

Ledger append-only, prompt com sha256 e POSTMORTEM em nove classes fixas.

Terminou, e ninguém mede se o caminho foi bom.

Um score humano de 0 a 5 em toda entrega, sem exceção.

estado real

O que existe hoje, e o que ainda não

Este projeto publica lacuna como lacuna. O que está escrito como pronto tem comando que prova; o que não está pronto é dito com todas as letras.

  • funciona Onboarding do projeto por ork onboarding, com pauta e retomada de respostas
  • funciona Pulse de condução, sensores de sessão e fechamento administrativo separado do score
  • funciona Telemetria econômica: tempo, tokens, custo de referência, espera, riscos e estimativas do PLAN
  • funciona Playbooks nativos de Claude Code e Codex, com AGENTS.md gerenciado e claims tipadas
  • funciona Orquestração nos quatro hosts: Hermes, OpenClaw, Claude Code e Codex, sobre o mesmo núcleo
  • funciona Docs para usuários: instalação, primeira entrega e operação cotidiana em /docs/
  • funciona Núcleo ork: threads, 6 fases, modos #Classic, #Maestro, #Auto e #Fast, ledger, worktree, leases, board, escalonador
  • funciona Claims, baseline, verify no HEAD real, motivos tipados e policies executáveis
  • funciona Gate de tokens, handoff triado em 3 níveis, ork recall por momento
  • funciona ork ship serializado, com push provado por ls-remote
  • funciona MASTER log em contrato congelado, POSTMORTEM tipado e índice derivado do ledger
  • funciona Retry tipado, fila durável de rate limit, GO-FIX e CHECK-REVERIFY
  • funciona 7 packs de auditoria, board de dívida, superfície de ataque de rede (SP8 a SP12)
  • funciona Adaptadores dos quatro hosts, com skills, MCP e contratos tipados conforme cada cliente
  • funciona Camada OrkMind (memory.mode: orkmind), com degradação honesta para files
  • funciona Company Brain B1/B2: schema versionado, ACL, proveniência, receipts, reconciliação e rollback
  • funciona Biblioteca governada no OrkMind Web: tipos, coleções e fontes separados; fatos técnicos sob filtro
  • funciona Captura e consulta do Brain nos quatro hosts: Hermes, OpenClaw, Claude Code e Codex
  • funciona Criação durável de produto, projeto, iniciativa e operação, com journal e recuperação
  • não existe Medida runtime_reported de ocupação de janela
  • funciona Runtimes homologados: Claude Code (claude-bg) e Codex (codex)
  • funciona Maestro mode autônomo com Objective Envelope
  • planejado Company Brain B3–B7, cuidadores, Atlas, dados e world model

O Orkastery é construído com Orkastery: cada pull request do núcleo traz o pacote das claims, e o CI reexecuta cada uma antes do merge. O que ainda não funciona está marcado acima como lacuna, com todas as letras.

a batuta é sua

Pronto para reger?

Começar pelo repositório Falar com a org