convez.ai
AgenteDevOps & InfraestruturaIntermediário
intrepideai

donegate

intrepideai/donegate

Porta de saída determinística para agents — nada passa sem DONE.md

Ver no GitHub
InicialPluginScore · de 0 a 100

Um agent determinístico que bloqueia a conclusão de tarefas até que um arquivo DONE.md seja satisfeito. Integra-se com Claude Code, Codex e Cursor para forçar verificações de qualidade (testes, lint, guards) antes do finish, impedindo que agentes "trapaceiem" pulando testes ou ignorando falhas.

Instalação

$npx convez-ai intrepideai/donegate

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
75%
Último commit
há 1 mês
Versão
v0.1.0
Issues abertas
2
Contribuidores
1

Casos de uso

  • Garantir que agents de código não declarem sucesso com testes falhando
  • Detectar e bloquear truques como skip de testes e redução de cobertura
  • Automatizar checks de qualidade em pipelines CI com agents IA
  • Manter padrão de done consistente entre toda equipe de desenvolvimento

Veredito

Solução prática e sem dependências que resolve um problema real: agentes IA que mentem sobre estar prontos. O design de exit codes e guards é sólido para CI/CD e fluxos de agent coding. Recomendado para times que usam Claude Code/Cursor em produção.

README

A tradução para o português deste README ainda está na fila.

donegate

Your agent says it's done. DONE.md decides.

ci npm zero dependencies license MIT

One file. One command. Works with Claude Code, Codex, Cursor, CI, and anything that runs in a shell.


Every coding agent session ends the same way:

“All done! I've implemented the feature and all tests are passing ✅”

Sometimes that's true. Often it isn't — teams keep finding a third of the work missing behind green checkmarks, tests that pass because the agent wrote both the bug and the test, and suites that got quietly .skip'd into submission. The transcript says done. The repo disagrees.

donegate is the bouncer at the door. It turns your repo's definition of done into a file — DONE.md — and physically stops your agent from finishing until that file is satisfied. Not satisfied? The agent gets bounced back with the failing output and keeps working. Tried to cheat? The guards catch it, with file:line receipts.

No model calls. No config sprawl. No SaaS. Exit codes.

60-second start

npx donegate init       # writes DONE.md from your stack (npm/pnpm/uv/go/cargo/…)
npx donegate install    # gates every coding agent you use, project-wide

That's the whole setup. From now on, when Claude Code / Codex / Cursor tries to say "done", donegate runs your checks first. Commit DONE.md and .claude/settings.json (etc.) and everyone on the team gets the same gate for free. (donegate status shows the whole posture at a glance — donefile, baseline, hooks, last receipt.)

Want to see it catch a cheat before touching your own repo? Run the sandboxed demo:

curl -fsSL https://raw.githubusercontent.com/intrepideai/donegate/main/examples/demo.sh | bash

What that looks like

Act 1 — the agent finishes, the gate disagrees. The agent tries to stop; donegate runs the checks and bounces it back with evidence:

$ donegate check

 ✓ lint (104ms)
 ✗ tests (153ms)
   $ npm test exit 1
   │ # tests 2
   │ # pass 1
   │ # fail 1

 ✗ NOT DONE — 1 of 2 checks failed (377ms)

The stop is blocked. The failing output goes straight back into the agent's context: fix it, then finish.

Act 2 — the agent gets "creative". It skips the failing test instead of fixing the bug. Tests are green now. Watch:

$ donegate check

 ✓ lint (105ms)
 ✓ tests (138ms)          ← green!

 guards
 ✗ no_deleted_tests
   test/discount.test.js — test count dropped from 2 to 1 since the baseline
 ✗ no_new_skips
   test/discount.test.js:9 — test marked as skipped
     test.skip('rejects discounts over 100%', () => {

 ✗ NOT DONE — 2 guards tripped (314ms)

Exit code 3: checks pass, but the bar was lowered to get there. The agent gets told exactly what it did and that it didn't work.

Act 3 — the agent actually fixes the bug.

$ donegate check

 ✓ lint (104ms)
 ✓ tests (139ms)

 ✓ DONE — 2 checks passed, guards clean (320ms)
   receipt: .donegate/receipts/latest.json

Now it's allowed to say done — and there's a receipt to prove it.

DONE.md

README.md is for humans. AGENTS.md is for agents. DONE.md is for the moment they claim to be finished.

# Definition of Done

**Done here means:** types compile, every test passes from a real run,
and nothing was skipped, deleted, or suppressed to get there.

```yaml
version: 1

checks:
  - name: typecheck
    run: npx tsc --noEmit
  - name: tests
    run: npm test
    timeout: 600

guards:
  no_new_skips: true       # .skip/.only/xfail/t.Skip added       → fail
  no_deleted_tests: true   # test files/counts reduced            → fail
  no_disabled_lint: true   # eslint-disable/noqa/@ts-ignore added → fail
  no_done_edits: true      # this file edited mid-session         → fail
  no_new_todos: warn
  no_debug_artifacts: warn

gate:
  max_bounces: 3           # re-prompts per session before giving up
```

Prose for people, one yaml block for the gate. Checks are your own commands — donegate never invents or modifies them. Full schema: docs/spec.md · copy-paste starters: examples/ (node, python, go, rust, monorepo).

How the guards work

When a session starts, donegate snapshots a baseline: hash of every test file, test/skip counts per file, and the hash of DONE.md itself. When the agent tries to finish, it diffs reality against that baseline:

guardcatchesdefault
no_new_skips.skip .only xit @pytest.mark.skip xfail t.Skip() #[ignore] @Disabled — added in test files, or skip-counts risingfail
no_deleted_testsdeleted test files, per-file test counts droppingfail
no_disabled_linteslint-disable biome-ignore @ts-ignore # noqa # type: ignore //nolint #[allow(...)] @SuppressWarnings rubocop:disable — added anywherefail
no_done_editsDONE.md modified or deleted mid-sessionfail
no_new_todosTODO / FIXME / HACK introduced in codewarn
no_debug_artifactsconsole.log debugger breakpoint() pdb.set_trace binding.pry dbg! left in non-test codewarn

Everything is deterministic — diffs and regexes against your git history and the session baseline. Same tree, same verdict, on any machine. No LLM judges anything.

Two escape hatches, both human-controlled: files that legitimately contain these patterns (lint configs, pattern scanners) go in guards.exclude, and a deliberate DONE.md edit is blessed with donegate baseline. Renames are followed, so moving a test file is never "deleting" it.

Works with

commandmechanism
Claude Codedonegate install claudeStop hook — blocks the stop, feeds failures back
Codex CLIdonegate install codexStop hook (.codex/hooks.json)
Cursordonegate install cursorstop hook → followup_message
GitHub Actionsdonegate install cigates PRs, posts the receipt as a comment
anything elsedonegate run -- <cmd>baseline → run your agent → gate

Hooks are installed project-level by default (commit them — the whole team is gated) or --global for every repo you touch, and they carry explicit generous timeouts so a long test suite is never cut off by an agent's 60-second hook default. Repos without a DONE.md are silently ignored, an agent can never be trapped (see bounce protection in docs/hooks.md), and ctrl-c always means ctrl-c.

Receipts, not vibes

Every run writes .donegate/receipts/latest.json: verdict, every command + exit code + output tail, every guard finding with file:line, the baseline used, diffstat, git state, sha-stamped. donegate receipt --md renders it for PR comments — the CI install does this automatically:

✅ donegate: DONE

checkstatustime
typecheck✅ pass1.2s
tests✅ pass8.4s

donegate v0.1.0 · baseline c4bbac02e7 (session) · 3 files, +21/−18 · receipt ab19e3289c073e8c

When someone asks "did the agent actually run the tests?" — the answer is a file, not a feeling.

Exit codes

0done — checks pass, guards clean
1checks failed
2config error
3checks pass but a guard tripped — it was made to look done

Code 3 is the one to alert a human on.

FAQ (the short version)

Won't the agent just edit DONE.md? That trips no_done_edits. The definition of done is not the agent's to edit.

Won't it delete the failing test? That trips no_deleted_tests — file deletions and per-file test-count drops.

Does this replace CI? No — it runs before the agent declares victory, while it still has context to fix things. CI stays as the backstop (and donegate install ci makes CI speak DONE.md too).

Does it phone home / call a model? No network calls, no LLM, zero runtime dependencies. The entire tool is a few thousand lines of TypeScript you can read in one sitting.

More in docs/faq.md.

Philosophy

  1. Trust receipts, not transcripts. An agent's claim is not evidence. A command that exited 0 is.
  2. The bar is not negotiable mid-task. Humans set DONE.md; agents satisfy it.
  3. Deterministic or it doesn't ship. No model-graded gates. Same tree, same verdict.
  4. Fail open on infrastructure, fail closed on work. A broken config never traps an agent; a failing test never gets talked past.

Contributing

Guard patterns for more languages, stack detection, and new agent adapters are all small, well-tested PRs — see CONTRIBUTING.md. The repo is gated by its own DONE.md, naturally.


Built by Intrepide — an AI product studio. Every agent we ship runs behind guardrails, observability, and audit trails. donegate is that rule, open-sourced: agents don't declare success — evidence does.

MIT licensed.

Ver o original no GitHub

Bom para

Relacionados