convez.ai
AgenteAutomaçãoIntermediário
Realmwalk

Discipline

Realmwalk/discipline

Docs + conventions + CLI para agentes IA manterem qualidade por 100+ sessões

Ver no GitHub
InicialPluginScore · de 0 a 100

Framework 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/discipline

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
42%
Último commit
há 2 meses
Versão
—
Issues abertas
0
Contribuidores
1

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 approachDiscipline
One AGENTS.md, kept tinyHot/cold path docs — the agent loads only what the task needs
[x] DONE piling up in TODOTODO entries are DELETED on ship — it's a queue, not a log
CHANGELOG + FEATURES + RELEASES drifting apartOne 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 askAn optional spec-first flow: plain-English spec → technical plan → checks, before code

Core ideas

  1. 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.
  2. 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."
  3. 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.
  4. 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.
  5. 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.
  6. Provider-agnostic tiers. Frontier / Workhorse / Recon as the canonical tiers, so the playbook doesn't churn every time a vendor renames a model.
  7. 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.
Ver o original no GitHub

Bom para

Relacionados