Guides
Contribute
Choose a contribution, prepare evidence and find the guide for your task.
Where to start
Start new features in GitHub Discussions. Report bugs in an issue with the command, actual output and version. Documentation and small fixes can go straight to a PR. Check existing issues and the roadmap first; comment on an issue before picking it up.
Prepare a verifiable change
A PR explains the problem, change, evidence, baseline and risk. Include actual command output. Separate regressions from existing failures; behavior changes need a test that reproduces the problem. Using ork is recommended and optional. The maintainer integrates with passing CI at the exact commit and handles publishing.
Publishing runs in CI from the v<version> tag, never from a machine. The workflow checks that the tag matches core/package.json, that the commit is on main, that the scenarios pass and that there is a safe dist-tag, and always publishes with npm publish --tag <dist-tag>: a stable version above latest uses latest, a lower stable version uses previous and does not move latest back, and a prerelease uses the channel from its first identifier, such as rc or beta. An unreachable registry or a lookup in an unknown shape fails before the publish.
If private data slipped out, fix it through a PR even if the value has appeared before, and fill in the description the three-line template from the PR guide: what was fixed now, what remains in earlier commits and the owner’s decision on rewriting history. Removing the data from the tip does not remove it from earlier commits; only the owner decides to rewrite, and, without that decision, the third line says “decisão pendente”.
Run commands from the checkout root. The testing guide lists the complete checks. The required checks are documentacao (markdownlint e paridade), nucleo ork (build, testes, cenarios), one per Node version, and ork-verify.
The full suite (npm --prefix core test) runs on any machine. Without codex in /usr/bin, without PostgreSQL with the pgvector/pgvector:pg16 image or without the OrkMind interpreter, the tests that need them are skipped with the reason, and the suite ends with 0 failures. With ORK_TESTE_EXIGE_AMBIENTE=1, nothing is skipped and a missing dependency fails; test:ci sets that variable on its own.
If you use ork, run ork ci prepare <thread>: it writes .ork-ci/<thread>.json for your thread only; make it the PR’s last commit, and the ork-verify check finds it by branch name.
Changed skills, references, the Claude Code or Codex adapters, or the version in core/package.json? Run node core/scripts/gerar-marketplaces.cjs and commit the result; CI checks it with --verificar. Changed an item’s frontmatter? Regenerate only its tables with ork docs sincronizar --escrever --so RM-NNN.
Changed behavior in core/, adapters/ or marketplaces/? Add a line under "Não publicado" in the CHANGELOG: the documentacao check fails a PR without it with changelog.linha-ausente. Test-only and CI-only PRs are exempt. Check before opening the PR with node core/scripts/checar-changelog.cjs --base origin/main.
Once a thread’s PR reaches main, its item must say codigo: Mesclado and the generated index must match the frontmatter. On the PR, CI only warns; the push to main fails. Whoever merged opens the docs PR with ork docs sincronizar --escrever --so RM-NNN, on a new branch from the updated origin/main.
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/mainText the site uses
The Orkastery and OrkMind sites are maintained by the team. Each documentation page comes from files in the Orkastery repository, with no manual copy: the site keeps a fingerprint of each source and the editorial review of the page in each language. Your change shows up on the site at the next review, after review in all three languages. That is why the fix always goes to the source, in the Orkastery repository.
Is the site page wrong while the source is right? Open an issue in the Orkastery repository and cite the page address.
One guide per task
Source guides are in Brazilian Portuguese, like the rest of the docs folder. Clear technical contributions in English are welcome and are never turned away for language alone.
CONTRIBUTING.md opens with the short path in English, from the checkout root: clone, npm --prefix core ci, build, node core/dist/index.js --version and npm --prefix core run test:ci, which is hermetic (no network, no Docker, no agent runtime). The PR title, commit messages and CHANGELOG line can be in pt-BR or in English; the CHANGELOG group names (Adicionado, Mudado, Corrigido, Removido) stay as they are.
CLI messages, labels and documentation are written in pt-BR. For the commands that follow the locale in version 0.6.10, such as ork doctor, ork init, ork thread new and ork phase run, the English comes from the catalog in core/src/locale.ts and the core/src/locale-*.ts files, typed by the pt-BR.
Response time, review and security
The target is an initial response to issues within 7 days, and an initial PR review within the same period. This is a target, not a guarantee. If it is missed, comment on the original request.
RM-050 measures this guide by outside PRs: the share whose CI passes on the first run, with an 80% target, and two PRs merged without the maintainer’s help, which close the pilot. The measurement comes from node core/scripts/medir-piloto-de-contribuicao.cjs, which uses the network and an authenticated gh. Outside means neither the owner, an organization member nor a bot, and re-running CI until it passes does not count as green on the first run.
Report vulnerabilities through the private channel in SECURITY.md. Keep secrets, personal information and customer data out of the repository.