Ratchet — Loop de Entrega Contínua Nativa do GitHub
praveenvijayan/Ratchet
Entrega contínua com agentes IA, planejamento em markdown, revisão humana
Ver no GitHubRatchet é um agente que implementa um fluxo de entrega contínua forward-only no GitHub, permitindo que agentes de IA (Claude Code, GPT Codex, Antigravity) trabalhem autonomamente enquanto humanos focam em escrever planos e revisar PRs. O sistema elimina orquestradores e bancos de dados, operando inteiramente através de issues, branches, labels e Actions do GitHub.
Instalação
npx convez-ai praveenvijayan/Ratchet1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automatizar fluxos de desenvolvimento com agentes IA coordenados
- Implementar CI/CD que permite falhas retornarem à fila sem travamentos
- Gerenciar múltiplas ferramentas de agentes (Claude, Codex, Antigravity) com protocolo unificado
- Estruturar projetos para que agentes autônomos executem tarefas planejadas por humanos
Veredito

Ratchet é uma solução sofisticada e agnóstica de ferramentas para orquestração de agentes IA em fluxos de entrega. Exige compreensão profunda de GitHub Actions e arquitetura de agentes, mas elimina dependências de serviços externos — ideal para equipes que buscam automação escalável com protocolo GitHub-native.
README
A tradução para o português deste README ainda está na fila.
Ratchet — continuous, GitHub-native delivery for Claude Code, Codex & Antigravity
A forward-only delivery loop: work only moves toward shipped, and every failure
path returns to the queue rather than slipping backward or stalling. A drop-in
kit that turns any GitHub repo into a continuous loop run by coding agents, with
humans owning only two jobs: writing good plan files and reviewing PRs.
There is no orchestrator, no database, and no custom service — the protocol
lives entirely in GitHub (issues, branches, labels, Actions, PRs), so it works
with any agent that can run gh and read a markdown file.
Why it's cross-tool
The protocol is in GitHub, not in any one tool. The only tool-specific layer is the thin skill/slash-command ergonomics, and the three tools share open standards:
| Layer | Claude Code | GPT Codex | Antigravity |
|---|---|---|---|
| Operating manual | AGENTS.md (+ CLAUDE.md pointer) | AGENTS.md | AGENTS.md (+ GEMINI.md pointer) |
| Skills | .claude/skills/ | .agents/skills/ | .agents/skills/ |
| GitHub core (workflows, sync, labels) | shared | shared | shared |
.agents/skills/ is the canonical source and is read directly by Codex and
Antigravity. .claude/skills/ is a mirror for Claude Code. setup.sh keeps them
in sync.
Layout
AGENTS.md Operating manual (the 7-step loop). Canonical.
CLAUDE.md / GEMINI.md One-line pointers to AGENTS.md for each tool.
.agents/skills/<name>/ Canonical skills (Codex + Antigravity)
SKILL.md portable skill body
agents/openai.yaml Codex invocation policy (explicit-only)
.claude/skills/<name>/SKILL.md Mirror for Claude Code
plugin/ Optional Claude Code plugin packaging
.claude-plugin/marketplace.json Optional marketplace (Claude Code only)
AGENTS.md Operating manual (100% framework, overwrite-safe)
GATES.md Project config you hand-author (verification gates)
CLAUDE.md / GEMINI.md One-line pointers to AGENTS.md for each tool
.ratchet-version Installed framework version (managed by the updater)
.agents/skills/<name>/ Canonical skills (Codex + Antigravity)
SKILL.md portable skill body
agents/openai.yaml Codex invocation policy (explicit-only)
.claude/skills/<name>/SKILL.md Mirror for Claude Code
plugin/ Optional Claude Code plugin packaging
.claude-plugin/marketplace.json Optional marketplace (Claude Code only)
plan/
README.md The plan-file format contract
0001-email-login.md Worked example
memory/
USER.md Human-owned preferences (agent reads, never edits)
ARCHITECTURE.md Coarse codebase map (generated; scopes the agent's reads)
MEMORY.md Distilled knowledge cache (agent proposes via PR)
scripts/
plan-sync.mjs Zero-dep deterministic plan→issue compiler
ratchet-update.sh Pulls framework updates, preserves project files
.github/workflows/ plan-sync, unblock-dependents, sweep-stale-claims, ratchet-run
.env.example PAT documentation for local runs
setup.sh Sync skills into each tool's location
The skills: /ratchet-plan (idea → plan/*.md), /ratchet-sync
(compile plan files → issues now), /ratchet-init (one-time: labels, gate
detection into GATES.md, memory scaffold, codebase map, PAT check),
/ratchet-memory (prune & dedupe memory/MEMORY.md), /ratchet-map
(regenerate the coarse codebase map),
/ratchet-update (pull a newer framework version, project files untouched),
/ratchet-status (read-only: why is nothing ready, and what to do),
/ratchet-uninstall (cleanly remove Ratchet; keeps your data by default).
Install
- Copy this kit into your repo (or "Use this template"), and commit it.
- Make sure skills are where each tool expects them:
Codex and Antigravity also read./setup.sh # repo-local mirrors (works for all three on clone) ./setup.sh user-claude # optional: install for Claude Code across all repos ./setup.sh user-agents # optional: install for Codex/Antigravity across all repos.agents/skills/directly with no setup. - Run
/ratchet-initin your agent. It creates the labels, detects your stack to fill the Gates table inAGENTS.md, and walks you through the PAT.
Claude Code, one-command alternative
/plugin marketplace add praveenvijayan/Ratchet
/plugin install ratchet@ratchet
(Codex and Antigravity do not use this; they use .agents/skills/ + AGENTS.md.)
The PAT (read this)
The issue flow depends on workflows reacting to each other. GitHub's default
token can't trigger one workflow from another's events, so any automated
issue close would stall the loop. The workflows read
${{ secrets.FACTORY_PAT || secrets.GITHUB_TOKEN }}, so set a fine-grained PAT
as the FACTORY_PAT repo secret (and in .env as GITHUB_PAT for local runs).
With pure human merges the fallback works; the PAT makes it bulletproof.
/ratchet-init checks this and guides you. Never commit a real token —
.env is gitignored; only .env.example is committed.
The loop
- Ideate with the LLM until the idea is solid.
/ratchet-plan→ writesplan/*.md(one for a report, many for a plan) onto the rolling planning branch and opens/updates the planning PR.- Review and merge the planning PR;
plan-synccreates the issues onmain. - Issues appear (
state:ready). The agent picks the top unblocked one, claims it by creatingagent/issue-N, builds to the acceptance criteria, verifies the gates fail-fast, and opens a PR withCloses #N— then stops. - A human reviews and merges. GitHub closes the issue.
unblock-dependentsflips newly-unblocked issues tostate:ready;sweep-stale-claimsreturns abandoned work to the queue.- Repeat until the backlog is empty. New findings → new
plan/*.md.
Every failure path (red gate, crash, oversized issue, requested changes) returns
the issue to state:ready with a comment — nothing gets silently stuck.
Memory (so it scales to multi-year projects)
Three tiers, all GitHub-native — no vector DB, no external service:
- Working — the claimed issue + acceptance criteria, in context.
- Durable curated —
memory/USER.md(human-owned preferences),memory/ARCHITECTURE.md(a coarse, generated codebase map that scopes the agent's reads), andmemory/MEMORY.md(agent-proposed distilled knowledge), read at the start of every issue.MEMORY.mdis a cache, not a log: each entry is 1–2 lines linking to the issue/PR that is its real source, so it stays small even as the project grows huge. - Episodic — closed issues, merged PRs,
git log/blame, andplan/*.md, searched on demand. This is the unbounded long-term store.
The agent reads Tiers 1–2 each issue, searches Tier 3 when context is missing,
and proposes MEMORY.md edits inside its PR — so memory changes are reviewed
like code, never written silently. It never edits USER.md. Run
/ratchet-memory periodically to prune stale entries. Because all three tools
read AGENTS.md, this works identically in Claude Code, Codex, and Antigravity.
Updating Ratchet
Repos created from the template don't auto-update (that's the template
trade-off), but upgrading is one command and never needs a manual merge, because
AGENTS.md is 100% framework; the project-specific files (GATES.md config
plus the memory/ files) live outside it and the updater never touches them.
/ratchet-update # pull upstream main onto a review branch
/ratchet-update v1.2.0 # or a specific release tag
It pulls only framework paths (skills, workflows, scripts, AGENTS.md),
re-syncs the skill mirrors, bumps .ratchet-version, and stops for you to review
the diff and open a PR. It never touches GATES.md, memory/, your plan/*.md
issues, .env, README.md, LICENSE, or your code. (Claude Code users who
installed via the plugin can also update skills with
/plugin marketplace update ratchet; the git update covers all three tools.)
Hands-off continuous execution (opt-in)
By default a human re-invokes the agent after each merge ("pick the next issue").
To make the loop fully hands-off — human involvement ends at the merge until the
next PR — enable the ratchet-run workflow:
gh variable set RATCHET_AUTO --body true
gh secret set ANTHROPIC_API_KEY # the agent runtime in CI (or swap to Codex)
# FACTORY_PAT is already set by /ratchet-init
gh workflow run ratchet-run # kick off the first task after planning
Then every human merge triggers ratchet-run: it checks out the latest main
(fresh, so the next branch is never stale), picks the top ready issue, and an
agent works it to a PR and stops. You merge; it advances. The backlog drains one
merge at a time, and the merge is the only thing you do.
It is safe by default: without RATCHET_AUTO=true the workflow exists but
no-ops, so nothing runs or fails unexpectedly. The agent step uses Claude Code;
swap that one step for an OpenAI Codex action if you prefer. (Antigravity is used
interactively rather than in CI.) Mind the cost — each run spends agent API
tokens; set a budget/alert on your provider.