@orkastery/cli 0.2.0

package/adapters/claude-code/commands/master.md

@@ -0,0 +1,42 @@
+---
+description: Fecha a thread com POSTMORTEM tipado e o score humano de 0 a 5.
+argument-hint: "<thread-id> --score 0-5"
+allowed-tools: Bash(ork:*), Read, Glob, Grep
+---
+
+# /master
+
+Fase MASTER (F6): POSTMORTEM tipado, MASTER log no contrato congelado e o score humano com justificativa. Uma entrega sem MASTER log nao aconteceu.
+
+## O que este comando faz
+
+1. Mostra ao builder as classes de falha do catalogo fixo:
+
+```bash
+ork master classes
+```
+
+2. Pede ao builder o score e a justificativa. **O score e do humano, em todos os modos.** Este
+   comando nunca inventa nota.
+
+3. Fecha a thread:
+
+```bash
+ork master <thread> --score <0-5> --justificativa "<texto>" --classe <classe> --por "<quem>"
+```
+
+4. Nos modos sem pausa de MASTER, mostra a fila que ainda espera humano:
+
+```bash
+ork master --batch
+```
+
+## Regras do adaptador
+
+- **Zero regra de negocio aqui.** Este comando traduz intencao em chamada de `ork` e nada mais.
+  Quem valida modo, monta prompt, decide gate e prova entrega e o nucleo.
+- **A #TAG vem do pedido, nao de configuracao.** O modo sai de `ork modos --do-pedido`, que usa a
+  mesma funcao do nucleo; sem tag vale o `conduction.default_mode` do manifesto. A validacao
+  contra `conduction.allowed_modes` acontece dentro do `ork thread new`, nunca aqui.
+- **Nada de escrever codigo de produto neste comando.** Quem escreve e a sessao que o `ork`
+  despacha, com o prompt gravado e o sha no ledger.

package/adapters/claude-code/commands/ork.md

@@ -0,0 +1,37 @@
+---
+description: Painel do Orkastery: estado das threads, escalonador, modos e o que a maquina permite agora.
+argument-hint: "[board|plan|doctor|modos]"
+allowed-tools: Bash(ork:*), Read
+---
+
+# /ork
+
+Entrada geral do adaptador. Nao conduz fase nenhuma: mostra o estado e diz qual comando responde
+pela intencao do builder.
+
+## O que este comando faz
+
+```bash
+ork doctor       # o que vale nesta maquina agora (sai != 0 se bloqueado)
+ork board        # todas as threads em uma visao
+ork board plan   # quem avanca agora, quem espera e por que
+ork modos        # a tabela dos 5 modos de conducao por #TAG
+ork master --batch  # o que fechou e ainda espera score humano
+```
+
+## Roteamento
+
+| O builder quer | Comando |
+|---|---|
+| abrir demanda nova | `/goal <pedido com #TAG>` |
+| especificar | `/plan <thread>` |
+| implementar | `/go <thread>` |
+| verificar | `/check <thread>` |
+| entregar | `/ship <thread>` |
+| fechar e dar o score | `/master <thread>` |
+
+## Regras do adaptador
+
+- **Zero regra de negocio aqui.** Este comando le e apresenta; quem decide e o humano e quem
+  verifica e o `ork`.
+- Um `fail` do `ork doctor` para o ciclo antes de ele abrir, e isso e economia, nao obstaculo.

package/adapters/claude-code/commands/plan.md

@@ -0,0 +1,47 @@
+---
+description: Conduz a fase PLAN da thread pelo `ork`.
+argument-hint: "<thread-id> [observacao]"
+allowed-tools: Bash(ork:*), Read, Glob, Grep
+---
+
+# /plan
+
+Fase PLAN (F2): tarefas fatiadas com `touch_paths` e verify por tarefa, decisoes D1..Dn com domicilio unico. PLAN nao implementa.
+
+## O que este comando faz
+
+1. Le o estado real da thread antes de qualquer coisa:
+
+```bash
+ork thread status <thread>
+```
+
+2. Despacha a fase:
+
+```bash
+ork phase run <thread> PLAN --prompt "<o que o plano precisa cobrir>"
+```
+
+3. Reserva as regioes que o plano declarou tocar, para que outra thread nao escreva por cima:
+
+```bash
+ork lease acquire "path:<glob>" --thread <thread> --motivo "PLAN reservou a regiao"
+```
+
+4. Exporta o handoff tipado para a fase seguinte, em vez de confiar na memoria da sessao:
+
+```bash
+ork handoff export <thread> --proxima-fase GO
+```
+
+5. Se o modo pausa, apresenta os tradeoffs com opcoes e uma recomendacao, e espera o veredito.
+
+## Regras do adaptador
+
+- **Zero regra de negocio aqui.** Este comando traduz intencao em chamada de `ork` e nada mais.
+  Quem valida modo, monta prompt, decide gate e prova entrega e o nucleo.
+- **A #TAG vem do pedido, nao de configuracao.** O modo sai de `ork modos --do-pedido`, que usa a
+  mesma funcao do nucleo; sem tag vale o `conduction.default_mode` do manifesto. A validacao
+  contra `conduction.allowed_modes` acontece dentro do `ork thread new`, nunca aqui.
+- **Nada de escrever codigo de produto neste comando.** Quem escreve e a sessao que o `ork`
+  despacha, com o prompt gravado e o sha no ledger.

package/adapters/claude-code/commands/ship.md

@@ -0,0 +1,45 @@
+---
+description: Entrega a thread pelo `ork ship`: merge serializado e push provado.
+argument-hint: "<thread-id> [--para <branch>]"
+allowed-tools: Bash(ork:*), Read, Glob, Grep
+---
+
+# /ship
+
+Fase SHIP (F5): merge serializado por lease, atualizacao contra a base, push provado por comando e plano de rollback. Nada de `git push` na mao: o guard bloqueia e o motivo e que push na mao nao e provado.
+
+## O que este comando faz
+
+1. Ressincroniza quando a base andou:
+
+```bash
+ork worktree sync <thread>
+```
+
+2. Ensaia a entrega inteira antes de tocar em qualquer coisa:
+
+```bash
+ork ship <thread> --para main --dry-run
+```
+
+3. Entrega, com a autorizacao registrada:
+
+```bash
+ork ship <thread> --para main --autorizar-push "<quem>"
+```
+
+4. Mostra a prova ao builder: `mergeSha`, `shaRemoto` e `pushVerificado` no ledger.
+
+```bash
+ork phase list <thread>
+```
+
+## Regras do adaptador
+
+- **Zero regra de negocio aqui.** Este comando traduz intencao em chamada de `ork` e nada mais.
+  Quem valida modo, monta prompt, decide gate e prova entrega e o nucleo.
+- **A #TAG vem do pedido, nao de configuracao.** O modo sai de `ork modos --do-pedido`, que usa a
+  mesma funcao do nucleo; sem tag vale o `conduction.default_mode` do manifesto. A validacao
+  contra `conduction.allowed_modes` acontece dentro do `ork thread new`, nunca aqui.
+- **Nada de escrever codigo de produto neste comando.** Quem escreve e a sessao que o `ork`
+  despacha, com o prompt gravado e o sha no ledger.

package/adapters/claude-code/hooks/hooks.json

@@ -0,0 +1,17 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/ork-guard.js\"",
+            "timeout": 10,
+            "statusMessage": "ork guard: conferindo o comando"
+          }
+        ]
+      }
+    ]
+  }
+}

package/adapters/claude-code/hooks/ork-guard.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * Guard `PreToolUse` do adaptador Claude Code (bloco B4).
+ *
+ * Ele NAO tem regra de negocio: nao consulta ledger, nao decide quem pode entregar e nao
+ * conhece thread nenhuma. Ele bloqueia, mecanicamente, a classe de comando que destroi
+ * trabalho alheio sem pedir licenca, e manda o agente pelo caminho que o `ork` verifica.
+ *
+ * Dois bloqueios, herdados de incidente real:
+ *  1. `git add -A` e parentes: engolem arquivo de outra thread que estava na mesma arvore.
+ *     A regra do produto e um commit atomico por tarefa, com os arquivos nomeados.
+ *  2. `git push` na mao: o push do Orkastery e provado, comparando o sha local com o que o
+ *     remoto reporta, e serializado por lease. Push por fora nao e proibido por gosto: ele
+ *     e um push que ninguem consegue provar depois.
+ *
+ * Protocolo: le o JSON do PreToolUse no stdin, escreve a decisao em JSON no stdout e sai
+ * com codigo 2 quando nega (os dois canais, para funcionar tanto no host que le a decisao
+ * quanto no que le o codigo de saida). Erro interno NUNCA bloqueia: um guard que quebra a
+ * sessao por um bug proprio e pior que nenhum guard.
+ */
+
+'use strict';
+
+/** Padroes bloqueados. Cada um traz o motivo e o caminho que o `ork` verifica. */
+const BLOQUEIOS = [
+  {
+    nome: 'git-add-em-massa',
+    regex: /\bgit\s+add\s+(?:-A\b|--all\b|\.(?:\s|$))/,
+    motivo: 'git add em massa engole arquivo de outra thread que esteja na mesma arvore',
+    caminho: 'nomeie os arquivos da tarefa: git add -- <arquivo> [<arquivo>...]',
+  },
+  {
+    nome: 'git-commit-em-massa',
+    regex: /\bgit\s+commit\b[^|;&]*\s-(?:a|[a-zA-Z]*a[a-zA-Z]*)\b/,
+    motivo: 'git commit -a comita tudo que esta rastreado, nao a tarefa',
+    caminho: 'adicione os arquivos da tarefa e comite sem -a',
+  },
+  {
+    nome: 'force-push',
+    regex: /\bgit\s+push\b[^|;&]*(?:--force\b|--force-with-lease\b|\s-f\b)/,
+    motivo: 'force push reescreve historico publico e apaga entrega de outra thread',
+    caminho: 'nunca. Se a base precisa mudar, isso e decisao registrada, nao comando.',
+  },
+  {
+    nome: 'push-nao-provado',
+    regex: /\bgit\s+push\b/,
+    motivo:
+      'push na mao nao e provado: o Orkastery compara o sha local com o que o remoto reporta e serializa o merge por lease',
+    caminho: 'entregue por: ork ship <thread> --para <base> --autorizar-push <quem>',
+  },
+  {
+    nome: 'reset-destrutivo',
+    regex: /\bgit\s+(?:reset\s+--hard|clean\s+-[a-zA-Z]*[fd]|checkout\s+--\s+\.)/,
+    motivo: 'descarte em massa apaga trabalho nao commitado sem deixar rastro',
+    caminho: 'descarte por arquivo, ou registre a decisao antes: ork gate approve <thread> <sobre> --por <quem>',
+  },
+  {
+    nome: 'remocao-recursiva-ampla',
+    regex: /\brm\s+-[a-zA-Z]*r[a-zA-Z]*f?\s+(?:\/|\*|~|\$|\.\s*$|\.\/\s*$)/,
+    motivo: 'remocao recursiva com alvo amplo ou variavel apaga o que ninguem pediu',
+    caminho: 'remova caminhos nomeados, dentro da worktree da thread',
+  },
+];
+
+function decidir(entrada) {
+  const nome = entrada && entrada.tool_name;
+  if (nome !== 'Bash') return null;
+  const comando = String((entrada.tool_input && entrada.tool_input.command) || '');
+  if (comando.trim() === '') return null;
+  // Comando do proprio `ork` passa: quem verifica o push provado e o merge serializado e ele.
+  if (/^\s*(?:[A-Za-z0-9_]+=\S*\s+)*(?:\S*\/)?ork\s/.test(comando)) return null;
+  for (const b of BLOQUEIOS) {
+    if (b.regex.test(comando)) return b;
+  }
+  return null;
+}
+
+function main(bruto) {
+  let entrada;
+  try {
+    entrada = JSON.parse(bruto || '{}');
+  } catch (e) {
+    // Entrada ilegivel nao bloqueia: o guard erra para o lado de deixar passar.
+    process.stdout.write(JSON.stringify({ ork_guard: 'entrada-ilegivel', decisao: 'allow' }) + '\n');
+    return 0;
+  }
+  const bloqueio = decidir(entrada);
+  if (!bloqueio) {
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow' },
+        ork_guard: 'ok',
+      }) + '\n'
+    );
+    return 0;
+  }
+  const razao =
+    `ork guard bloqueou "${bloqueio.nome}": ${bloqueio.motivo}.\n` + `caminho: ${bloqueio.caminho}`;
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: razao,
+      },
+      ork_guard: bloqueio.nome,
+    }) + '\n'
+  );
+  process.stderr.write(razao + '\n');
+  return 2;
+}
+
+let bruto = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (c) => {
+  bruto += c;
+});
+process.stdin.on('end', () => {
+  let codigo = 0;
+  try {
+    codigo = main(bruto);
+  } catch (e) {
+    // Bug do guard nao derruba a sessao do builder.
+    process.stderr.write(`ork guard falhou e liberou por seguranca: ${e && e.message}\n`);
+    codigo = 0;
+  }
+  process.exitCode = codigo;
+});
+
+module.exports = { BLOQUEIOS, decidir };

package/adapters/hermes/README.md

@@ -0,0 +1,45 @@
+# Adaptador Hermes
+
+O Hermes vira **podio** do Orkastery: uma skill roteadora fina, um plugin que a declara e um script
+que abre thread a partir do pedido cru do builder.
+
+## Instalacao
+
+```bash
+ork adapter install hermes                       # instala em <projeto>/.hermes
+ork adapter install hermes --dir ~/.hermes       # instala para a maquina
+ork adapter install hermes --dry-run             # lista o que seria escrito
+```
+
+## O que entra
+
+| Arquivo | Papel |
+|---|---|
+| `skills/orkastery-devmaster/SKILL.md` | O roteador: le a #TAG, chama o `ork`, apresenta os gates |
+| `hermes.plugin.json` | Declara a skill, o binario do `ork` e as tags de conducao |
+| `bin/ork-abrir-thread.sh` | Abre a thread com o modo lido do pedido, em um comando |
+
+## O encolhimento, que e o ponto
+
+A skill devmaster do Hermes carregava a metodologia inteira em prosa: era ela quem "lembrava" das
+regras das fases, dos gates e do score. O roteador tem pouco mais de cem linhas e **nao perde
+capacidade nenhuma**, porque o que ele deixou de dizer o `ork` passou a executar. O mesmo ciclo
+real roda antes e depois; o que mudou e quem garante.
+
+Se esta skill comecar a crescer de novo com metodologia, isso e bandeira vermelha: a regra nova
+pertence ao nucleo, com teste, e nao a esta prosa.
+
+## Os 3 pitfalls de instalacao
+
+1. **`ork` fora do PATH do Hermes.** O host costuma rodar com um ambiente mais enxuto que o do
+   terminal do builder, e `~/.local/bin` pode nao estar la. O `hermes.plugin.json` grava o caminho
+   absoluto em `requires.comando` e o script honra `ORK_BIN`. Prove antes de confiar:
+   `ORK_BIN=$(command -v ork) ; "$ORK_BIN" doctor`.
+
+2. **Reimplementar o parse da #TAG no host.** E a tentacao obvia, sao cinco strings. Duas
+   implementacoes divergem na primeira tag nova, e a divergencia aparece como thread aberta no modo
+   errado, o que ninguem percebe ate a pausa que nao veio. Use `ork modos --do-pedido`, sempre.
+
+3. **Validar `allowed_modes` no host.** Um host que recusa o modo antes de chamar o `ork` recusa
+   com a regra que ele tem em cache, nao com a do manifesto do projeto. Deixe o
+   `ork thread new` recusar: o erro vem tipado, com a lista permitida do projeto certo.

package/adapters/hermes/bin/ork-abrir-thread.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env sh
+# Abre uma thread do Orkastery a partir do pedido cru do builder.
+#
+# Zero regra de negocio: o modo sai de `ork modos --do-pedido`, que usa a mesma funcao do
+# nucleo, e a validacao contra `conduction.allowed_modes` acontece dentro do `ork thread new`.
+# Este script existe para o host nao ser tentado a reimplementar o parse da #TAG.
+#
+# Uso: ork-abrir-thread.sh "<nome curto>" "<pedido inteiro do builder>" [--worktree auto]
+
+set -eu
+
+if [ "$#" -lt 2 ]; then
+  echo "uso: ork-abrir-thread.sh \"<nome curto>\" \"<pedido do builder>\" [argumentos extras]" >&2
+  exit 2
+fi
+
+ORK="${ORK_BIN:-ork}"
+NOME="$1"
+PEDIDO="$2"
+shift 2
+
+MODO="$("$ORK" modos --do-pedido "$PEDIDO")"
+echo "modo de conducao lido do pedido: $MODO" >&2
+
+exec "$ORK" thread new "$NOME" --mode "$MODO" "$@"

package/adapters/hermes/hermes.plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "orkastery",
+  "displayName": "Orkastery",
+  "version": "{{versao}}",
+  "description": "Conducao de looping threads em 6 fases pelo nucleo `ork`. O Hermes vira podio: le a #TAG do pedido, chama o `ork` e apresenta os gates ao humano.",
+  "license": "MIT",
+  "kind": "skill-router",
+  "skills": ["./skills/orkastery-devmaster"],
+  "bin": {
+    "ork-abrir-thread": "./bin/ork-abrir-thread.sh"
+  },
+  "requires": {
+    "ork": ">=0.1.0",
+    "comando": "{{ork_bin}}"
+  },
+  "conduction": {
+    "tags": ["#Look", "#Ork", "#Classic", "#Maestro", "#Auto"],
+    "parse": "ork modos --do-pedido \"<pedido>\"",
+    "nota": "O host transporta a tag. A validacao contra conduction.allowed_modes e do nucleo."
+  }
+}

package/adapters/hermes/skills/orkastery-devmaster/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: orkastery-devmaster
+description: "Roteador do Orkastery no Hermes: le a #TAG de conducao do pedido do builder, chama o `ork` para abrir e conduzir a thread pelas 6 fases, e apresenta os gates ao humano. Zero regra de negocio: quem decide e o humano, quem verifica e o `ork`."
+bucket: hermes
+roteia: "ork modos --do-pedido | ork thread new | ork phase run | ork ship | ork master"
+license: MIT
+---
+
+# Orkastery no Hermes
+
+## O que esta skill e
+
+O roteador do Orkastery dentro do Hermes, e **so isso**. Ela nao conduz fase por conta propria,
+nao escreve codigo e nao guarda metodologia: ela traduz o pedido do builder em chamada de `ork`,
+mostra o que o `ork` respondeu e para nos gates.
+
+Antes desta skill, a skill devmaster do Hermes carregava a metodologia inteira em prosa e era ela
+quem "lembrava" das regras. Isso e exatamente a fragilidade que corroeu o Devmaster original:
+regra que existe so como texto e regra que ninguem verifica. **Agora a metodologia e executavel e
+mora no `ork`; aqui ficou o roteador.**
+
+## Quando usar
+
+Sempre que o builder pedir trabalho de produto num repositorio que tem `orkastery.yaml`.
+
+## Passo 1: o modo sai do pedido, nao de configuracao
+
+```bash
+MODO=$(ork modos --do-pedido "<pedido inteiro do builder>")
+```
+
+O comando usa a mesma funcao do nucleo que reconhece `#Look`, `#Ork`, `#Classic`, `#Maestro` e
+`#Auto`. Sem tag no texto vale o `conduction.default_mode` do manifesto. **Nao reimplemente esse
+parse aqui**, e nao valide o modo: `conduction.allowed_modes` e conferido dentro do
+`ork thread new`, que recusa com erro tipado quando o projeto nao permite o modo pedido.
+
+| #TAG | Pausas | Quando o builder escolhe |
+|---|---|---|
+| `#Look` | 6 | Risco alto, passo irreversivel, dominio novo |
+| `#Ork` | 5 | Veredito separado da execucao e da evidencia |
+| `#Classic` | 3 | O padrao: premissas delicadas, entrega solta, score em batch |
+| `#Maestro` | 1 | Solucao clara e agil, score em batch |
+| `#Auto` | 0 | Docs, estudos, configuracoes, auditorias |
+
+## Passo 2: antes de abrir, confira a maquina
+
+```bash
+ork doctor          # sai != 0 quando o despacho nao vale (custo, runtime, ambiente)
+ork board plan      # quem avanca agora, quem espera e por que
+```
+
+Um `fail` do doctor para o ciclo antes de ele abrir. Isso e economia, nao obstaculo.
+
+## Passo 3: abrir a thread e conduzir as fases
+
+```bash
+ork thread new "<nome curto>" --mode "$MODO" --worktree auto
+ork phase run <thread> GOAL  --prompt "<pedido do builder>"
+ork phase run <thread> PLAN  --prompt "<o que o plano precisa cobrir>"
+ork worktree ensure <thread>
+ork verify <thread> --baseline
+ork phase run <thread> GO    --prompt "<uma tarefa do PLAN por vez>"
+ork verify <thread>
+ork phase run <thread> CHECK --prompt "<escopo da verificacao>"
+ork ship <thread> --para main --autorizar-push "<quem>"
+ork master <thread> --score <0-5> --justificativa "<texto>" --por "<quem>"
+```
+
+Cada `phase run` grava o prompt exato com sha256 e registra no ledger. O `ork` reverifica no
+runtime que a sessao existe: self-report de despacho nao vale como evidencia.
+
+## Passo 4: apresentar os gates ao humano
+
+O Hermes e o podio: e aqui que o builder ve a evidencia e da o veredito. Quando o bloco pausa,
+mostre o que o `ork` produziu e espere. A liberacao vira evento:
+
+```bash
+ork gate approve <thread> <objetivo|premissas|evidencias|push|score> --por "<quem>"
+```
+
+Quando o bloco nao pausa (`#Maestro`, `#Auto`), o `ork` registra a decisao autonoma com quem
+decidiu, com que evidencia e por que. **O modo afrouxa a pausa, NUNCA a verificacao.**
+
+## Passo 5: o score
+
+O score de 0 a 5 e humano em todos os modos. Nos modos sem pausa de MASTER, ele vai para a fila:
+
+```bash
+ork master --batch
+```
+
+Fila que ninguem passa e score que nao existe. Traga a fila ao builder.
+
+## Racionalizacoes comuns
+
+| Desculpa | Realidade |
+|---|---|
+| "Faco a fase aqui mesmo, e mais rapido" | A camada que apresenta nao escreve codigo de produto. Quem escreve e a sessao que o `ork` despacha, com prompt gravado e sha no ledger. |
+| "Guardo as regras da metodologia nesta skill" | Metodologia em prosa e metodologia que ninguem verifica. Ela mora no `ork`; aqui fica o roteamento. |
+| "Valido o modo antes de chamar o `ork`" | Validacao duplicada e validacao que vai divergir. `conduction.allowed_modes` e do nucleo. |
+| "O builder confia, pulo o gate desta vez" | Gate pulado e gate que nao existe. Se o modo nao pausa, o `ork` registra a decisao autonoma; se pausa, ele espera. |
+| "Score eu estimo pelo resultado" | O score e do humano em todos os modos. Estimar nota destroi a unica metrica de conducao do produto. |
+
+## Bandeiras vermelhas
+
+- Esta skill crescendo de novo para carregar metodologia em vez de roteamento.
+- Chamada de `git` direta em vez de `ork ship`.
+- Modo escolhido por configuracao do host, e nao pela #TAG do pedido.
+- Thread aberta com `ork doctor` em `fail`.
+- Fila de `ork master --batch` crescendo sem ninguem passar nela.
+
+## Verificacao antes de responder ao builder
+
+Modo lido do pedido pelo `ork`, doctor conferido, thread aberta pelo nucleo, fase despachada com
+prompt gravado, gate apresentado ou decisao autonoma registrada, e uma linha dizendo em que ponto
+a thread esta e o que acontece agora.

package/adapters/openclaw/README.md

@@ -0,0 +1,63 @@
+# Adaptador OpenClaw
+
+O OpenClaw recebe o Orkastery como um conjunto de **tools `ork_*`**: cada tool e uma chamada de CLI
+declarada em `openclaw.plugin.json`, sem codigo de cola e sem regra de negocio no host.
+
+## Instalacao
+
+```bash
+ork adapter install openclaw                     # instala em <projeto>/.openclaw
+ork adapter install openclaw --dir ~/.openclaw   # instala para a maquina
+ork adapter install openclaw --dry-run           # lista o que seria escrito
+```
+
+O instalador renderiza `{{ork_bin}}` com o caminho absoluto do `ork` desta maquina e grava
+`INSTALADO.json` com a origem e o sha256 de cada arquivo.
+
+## As tools
+
+| Tool | O que faz |
+|---|---|
+| `ork_doctor` | O que vale nesta maquina agora; sai != 0 quando o despacho nao vale |
+| `ork_modo_do_pedido` | Le a #TAG do pedido e devolve o modo (use SEMPRE, nao reconheca a tag no host) |
+| `ork_thread_new` | Cria a thread, o slug de 3 partes e o ledger |
+| `ork_thread_status` | Estado da thread cruzado com o runtime |
+| `ork_phase_run` | Despacha uma fase, gravando o prompt exato com sha256 |
+| `ork_phase_list` | O ledger, evento a evento |
+| `ork_claims_add` | Registra alegacao verificavel com o comando que a comprova |
+| `ork_verify` / `ork_verify_baseline` | Reexecuta no HEAD real; grava a baseline antes do GO |
+| `ork_worktree_ensure` / `ork_worktree_audit` | Worktree isolada, conferida no proprio git |
+| `ork_gate_approve` | Autorizacao humana registrada no ledger |
+| `ork_ship` | Merge serializado por lease e push provado contra o remoto |
+| `ork_master` | POSTMORTEM tipado e o score HUMANO de 0 a 5 |
+| `ork_board` / `ork_master_batch` | Escalonador e fila de score |
+
+## A #TAG de conducao
+
+`ork_modo_do_pedido` devolve JSON com o modo, a tag, se veio do pedido ou do
+`conduction.default_mode`, e quantas pausas humanas aquele modo tem. O host passa o resultado a
+`ork_thread_new` e **nao decide nada**: `conduction.allowed_modes` e conferido dentro do
+`ork thread new`, que recusa com erro tipado quando o projeto nao permite o modo.
+
+## Os 3 pitfalls de instalacao
+
+1. **Placeholder `{{ork_bin}}` que fica no arquivo.** O OpenClaw executa o vetor de comando como
+   ele esta: um `{{ork_bin}}` nao renderizado vira "comando nao encontrado" em toda tool, e a
+   sessao so descobre isso quando ja abriu thread na cabeca do agente. O instalador renderiza o
+   caminho absoluto; confira depois com
+   `grep -c '{{' <destino>/openclaw.plugin.json`, que precisa devolver `0`.
+
+2. **Argumento com espaco quebrado em varios argumentos.** Cada tool declara o comando como
+   **vetor**, nunca como string de shell, exatamente para que um pedido com espaco, aspas ou
+   quebra de linha chegue inteiro em `--prompt`. Se voce adaptar uma tool, mantenha o vetor: uma
+   string de shell aqui vira injecao de comando com o texto do builder dentro.
+
+3. **Tool que reimplementa regra do nucleo.** A tentacao e criar uma tool "esperta" que decide o
+   modo, monta o prompt ou escolhe a base. Toda tool deste plugin e uma chamada de CLI e nada
+   mais; a decisao que parece faltar aqui ja existe do outro lado, com teste. Tool nova que precisa
+   de logica e sinal de que a logica pertence ao `ork`.
+
+## O que este adaptador nao faz
+
+Nao escreve codigo de produto, nao decide gate e nao valida modo. Ele traduz intencao em chamada de
+`ork`, apresenta o resultado ao humano e registra o que o humano decidiu.

package/adapters/openclaw/bin/ork-abrir-thread.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env sh
+# Abre uma thread do Orkastery a partir do pedido cru do builder, no OpenClaw.
+#
+# Existe para o host nao reimplementar o parse da #TAG: o modo sai de `ork modos --do-pedido`,
+# que usa a mesma funcao do nucleo, e `conduction.allowed_modes` e validado pelo `ork thread new`.
+#
+# Uso: ork-abrir-thread.sh "<nome curto>" "<pedido inteiro do builder>" [argumentos extras]
+
+set -eu
+
+if [ "$#" -lt 2 ]; then
+  echo "uso: ork-abrir-thread.sh \"<nome curto>\" \"<pedido do builder>\" [argumentos extras]" >&2
+  exit 2
+fi
+
+ORK="${ORK_BIN:-ork}"
+NOME="$1"
+PEDIDO="$2"
+shift 2
+
+MODO="$("$ORK" modos --do-pedido "$PEDIDO")"
+echo "modo de conducao lido do pedido: $MODO" >&2
+
+exec "$ORK" thread new "$NOME" --mode "$MODO" "$@"