Discipline
Realmwalk/discipline
Docs + conventions + CLI para agentes IA manterem qualidade por 100+ sessões
Ver no GitHubFramework de documentação e conventions para manter agentes de IA em projetos de código a longo prazo. Inclui CLI pequeno, zero-dependências, que organiza docs em hot/cold paths, TODOs como fila (não log), changelog canônico e gates de autonomia. Model-agnostic: funciona com Claude Code, Cursor, Aider e outros.
Instalação
npx convez-ai Realmwalk/discipline1 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
- Manter agentes IA alinhados em projetos longos (meses/anos)
- Implementar spec-first workflow antes de gerar código
- Gerenciar autonomia de agentes com dois gates (tag + fila curada)
- Otimizar contexto carregando só docs necessários por tarefa
Veredito

Solução honesta e opinionada que troca alguns tokens por 4+ meses de estabilidade documentária. Funciona bem com agentes fortes (Claude 3.5+), exige disciplina real na limpeza de TODOs, mas resolve o problema verdadeiro: drift em projetos longos, não sessão 1. Robusto e agnóstico a modelo.
README
A tradução para o português deste README ainda está na fila.
Discipline
A small set of docs, conventions, and a tiny CLI for keeping AI coding agents on the rails over the long haul — past the first session and into session 100, when the usual single-file AGENTS.md has quietly gone stale.
Honest framing: this is what works for me. It's heavier on tokens than a minimal AGENTS.md — there are more docs, and the agent reads the ones it needs — but on longer-running projects it's given me noticeably better results: fewer stale docs, less agent drift, less cleanup after the fact. It's opinionated on purpose. Your mileage will vary.
I've used it most with Claude Code, but it's deliberately agent- and model-agnostic — it's just plain Markdown plus a small zero-dependency CLI, so it should work with Cursor, Codex, Aider, OpenCode, local models, or whatever you run. How well it works depends on the model you point at it; stronger models follow the conventions more reliably.
You can drop it into a new project or layer it onto an existing one.
How it's different
Most starter kits optimize session 1: one short AGENTS.md, terse rules, minimal startup tokens. That's great for a week. This optimizes for the project that's still going months later.
| Common approach | Discipline |
|---|---|
One AGENTS.md, kept tiny | Hot/cold path docs — the agent loads only what the task needs |
[x] DONE piling up in TODO | TODO entries are DELETED on ship — it's a queue, not a log |
| CHANGELOG + FEATURES + RELEASES drifting apart | One canonical CHANGELOG |
| "Just let the agent run" | Two-gate autonomy: a tag scheme + a curated queue before anything runs unattended |
| Build straight from a one-line ask | An optional spec-first flow: plain-English spec → technical plan → checks, before code |
Core ideas
- Hot/cold path docs. Some docs are read every session; others only when the agent works in that area. The split keeps the always-loaded context small as the project grows.
- The cleanup gate is a hard rule. Shipped TODO entries get deleted; every CHANGELOG entry has a date. It runs at session end, not "when convenient."
- Two-gate autonomy. A
[autonomy: …]tag says what kind of work something is; a curated queue says which specific items are pre-approved. Being "safe" isn't enough on its own — it also has to be queued. - Improvement with guardrails. Workflow-change proposals have to point at concrete friction they remove. Aspirational guidance that doesn't earn its place is worse than no guidance.
- Expensive models only where they earn it. The host runs on a workhorse model and spawns a stronger one for the genuinely hard subtask, rather than paying top-tier rates for the whole session.
- Provider-agnostic tiers. Frontier / Workhorse / Recon as the canonical tiers, so the playbook doesn't churn every time a vendor renames a model.
- A spec-first flow. A one-line request isn't a buildable contract. The optional Spec & Design flow turns it into a plain-English spec, then a technical plan with checks, before any code — so an agent builds the right thing instead of confidently building the wrong one. See
templates/SPEC_WORKFLOW.md.
Quick start
# Drop the templates into your project's docs/ folder
npx discipline-md init
That scaffolds a docs/ folder with the core templates plus a repo-root LICENSE and NOTICE. Fill in the placeholders, point your agent at docs/AGENTS.md, and it has a working playbook from the first session.
For wiring it to a specific harness (Claude Code's CLAUDE.md, Cursor rules, or AGENTS.md-native tools), see docs/HARNESS_INTEGRATION.md.
What ships
npx discipline-md init installs a small core set — the docs and agent roles a project actually needs from day one. The idea is to ship the minimum that's genuinely useful and add more only when a real need shows up, rather than a giant pile of stubs. Everything else is opt-in:
npx discipline-md add <template> # e.g. ARCHITECTURE, DATA_MODEL, DEPLOYMENT
npx discipline-md add-role <ROLE> # extra agent roles, when a project needs them
npx discipline-md list # see what's available
Lint
A gate a weak model can forget isn't really a gate, so there's a small linter for the mechanical ones:
npx discipline-md lint # lint ./docs/
npx discipline-md lint --target <path> # lint another repo
npx discipline-md lint --strict # warnings also fail the run
It checks things like [x] residue in TODO, tag values outside the documented set, queue entries with no backing task, oversized always-loaded docs, unfilled placeholders, stale handoffs, and the spec-flow conventions. Exit 1 on any error (or any warning under --strict); rules skip quietly when their file doesn't exist. Wire it into CI or your end-of-session checklist.
Status
Early and evolving. It's used and maintained on real projects — that dogfooding is the validation. The templates and the CLI are the stable core.
License
MIT. See LICENSE.
Contributing
Issues and PRs are welcome — especially friction you've hit on existing AGENTS.md / starter-kit setups, since that's what this is meant to fix.
- Every change lands via pull request and is reviewed by the maintainer, who is the final approver. (A local pre-push hook blocks direct pushes to the default branch.)
- One concern per PR.
- This competes on discipline, not template count — proposals that add breadth for its own sake will be declined; ones that close a real, demonstrated gap are exactly right.