Guias
Contribuir
Escolha uma contribuição, prepare a prova e encontre o guia da sua tarefa.
Por onde começar
Feature nova começa no GitHub Discussions. Defeito começa por uma issue com o comando, a saída real e a versão. Documentação e correções pequenas podem ir direto a um PR. Consulte issues e roadmap antes de começar; comente na issue que pretende assumir.
Prepare uma mudança verificável
O PR explica o problema, a mudança, a prova, a baseline e o risco. Cole a saída real dos comandos. Separe regressões de falhas que já existiam; mudança de comportamento pede teste que reproduza o defeito. Usar o ork é recomendado e opcional. O mantenedor integra com CI verde no commit exato e conduz a publicação.
A publicação sai do CI pela tag v<versão>, nunca de uma máquina. O workflow confere que a tag bate com o core/package.json, que o commit está na main, que os cenários passam e que há uma dist-tag segura, e publica sempre com npm publish --tag <dist-tag>: versão estável maior que a latest usa latest, estável menor usa previous e não move a latest para trás, e pré-release usa o canal do primeiro identificador, como rc ou beta. Registro inacessível ou consulta em forma desconhecida falham antes do publish.
Se um dado privado escapou, corrija por PR mesmo que o valor já tenha aparecido antes, e complete na descrição o modelo de três linhas do guia de PR: o que foi corrigido agora, o que continua nos commits anteriores e a decisão do dono sobre reescrever o histórico. Tirar o dado da ponta não o tira dos commits anteriores; só o dono decide reescrever, e, sem a decisão dele, a terceira linha diz “decisão pendente”.
Rode os comandos a partir da raiz do checkout. O guia de testes traz a lista completa de checks. Os checks obrigatórios são documentacao (markdownlint e paridade), nucleo ork (build, testes, cenarios), um por versão do Node, e ork-verify.
A suíte inteira (npm --prefix core test) roda em qualquer máquina. Sem o codex em /usr/bin, sem PostgreSQL com a imagem pgvector/pgvector:pg16 ou sem o interpretador do OrkMind, os testes que precisam deles saem como skip com o motivo, e a suíte termina com 0 falhas. Com ORK_TESTE_EXIGE_AMBIENTE=1, nada é pulado e a dependência que faltar reprova; o test:ci liga essa variável sozinho.
Se usar o ork, rode ork ci prepare <thread>: ele grava .ork-ci/<thread>.json, só da sua thread; faça dele o último commit do PR, e o check ork-verify o acha pelo nome da branch.
Mexeu em skills, references, nos adaptadores do Claude Code ou do Codex ou na versão do core/package.json? Rode node core/scripts/gerar-marketplaces.cjs e comite o resultado; o CI confere com --verificar. Mudou o frontmatter de um item? Regere só as tabelas dele com ork docs sincronizar --escrever --so RM-NNN.
Mudou comportamento em core/, adapters/ ou marketplaces/? Acrescente uma linha na seção "Não publicado" do CHANGELOG: o check documentacao reprova o PR sem ela com changelog.linha-ausente. PR só de testes ou só de CI fica de fora. Confira antes do PR com node core/scripts/checar-changelog.cjs --base origin/main.
Depois que o PR de uma thread entra na main, o item dela tem de dizer codigo: Mesclado e o índice gerado tem de bater com o frontmatter. No PR, o CI só avisa; o push da main reprova. Quem mesclou abre o PR de docs com ork docs sincronizar --escrever --so RM-NNN, numa branch nova sobre a origin/main atualizada.
npm --prefix core ci
npm --prefix core run build
npm --prefix core run test:ci
node core/dist/index.js eval
node core/scripts/checar-changelog.cjs --base origin/mainTexto que o site usa
Os sites do Orkastery e do OrkMind são mantidos pela equipe. Cada página de documentação sai dos arquivos do repositório do Orkastery, sem cópia manual: o site guarda a impressão digital de cada fonte e a revisão editorial da página em cada língua. A sua mudança aparece no site na revisão seguinte, depois da revisão nas três línguas. Por isso a correção vai sempre na fonte, no repositório do Orkastery.
A página do site está errada e a fonte está certa? Abra a issue no repositório do Orkastery e cite o endereço da página.
Um guia por tarefa
Os guias-fonte estão em português do Brasil, como o restante da pasta docs. Contribuições técnicas claras em inglês são bem-vindas e nunca são recusadas só pela língua.
O CONTRIBUTING.md abre com o caminho curto em inglês, a partir da raiz do checkout: clone, npm --prefix core ci, build, node core/dist/index.js --version e npm --prefix core run test:ci, que é hermético (sem rede, Docker nem runtime de agente). O título do PR, as mensagens de commit e a linha do CHANGELOG podem ser em pt-BR ou em inglês; os nomes dos grupos do CHANGELOG (Adicionado, Mudado, Corrigido, Removido) não mudam.
As mensagens do CLI, os rótulos e a documentação são escritos em pt-BR. Nos comandos que seguem o locale na versão 0.6.10, como ork doctor, ork init, ork thread new e ork phase run, o inglês vem do catálogo de core/src/locale.ts e dos core/src/locale-*.ts, tipado pelo pt-BR.
Prazo, revisão e segurança
A meta é uma primeira resposta em até 7 dias para issues e uma primeira revisão no mesmo prazo para PRs. É meta, não garantia. Se passar do prazo, comente no pedido original.
O RM-050 mede este guia pelos PRs de fora: a fração cujo CI passa na primeira execução, com meta de 80%, e dois PRs mesclados sem ajuda do mantenedor, que fecham o piloto. A medida sai de node core/scripts/medir-piloto-de-contribuicao.cjs, que usa a rede e o gh autenticado. De fora é quem não é dono nem membro da organização, nem bot, e reexecutar o CI até passar não vira verde na primeira execução.
Vulnerabilidades vão pelo canal privado indicado em SECURITY.md. Nunca inclua segredos, dados pessoais ou dados de clientes no repositório.