Document format — prefer .kmd

mandatory

Documentos versionados no monorepo Koder devem usar a extensão `.kmd` (Koder Markdown) por default. `.md` continua aceito apenas em arquivos cujo nome literal é exigido por ferramentas externas (Claude Code lê `CLAUDE.md`; forges renderizam `README.md`/`LICENSE.md`/etc.) ou em conteúdo gerado por terceiros sob nosso controle limitado. KMD é um superset de CommonMark — renomear `.md → .kmd` em si não exige mudança de conteúdo; o que ganhamos é parse semântico, frontmatter checado, cross-refs validadas, e preview first-class no Koder Dok / Koder Flow.

Policy — Document format: prefer .kmd

KMD é o formato canônico de documentação da Koder Stack (engines/lang/kmd). Toda documentação *ova*vai em .kmd. .md só em casos onde o nome literal *.md é parte do contrato com tooling externa.

Regra base

*efault* novo arquivo de documentação criado neste monorepo usa extensão .kmd.

Aplica-se a:

  • RFCs, specs, policies novas (ver caveat sobre policies abaixo)
  • READMEs de módulos (README.kmd)
  • CHANGELOGs (CHANGELOG.kmd)
  • CONTRIBUTING (CONTRIBUTING.kmd)
  • Runbooks, guias, referências internas, ADRs
  • Notas de design, briefings, post-mortems
  • Slides em formato texto (*.kmd consumido por engines/lang/kmd

    preview)

Exceções obrigatórias — manter .md

Os arquivos abaixo *evem*ficar .md. Qualquer renomeação para .kmd quebra contrato com ferramenta externa:

Arquivo / pattern Por que tem que ficar .md
CLAUDE.md (qualquer nível) Claude Code lê o nome literal; renomear desliga o contexto
README.md na raiz do monorepo e na raiz de produtos publicados em forges externos Koder Flow, GitHub, Gitea, GitLab renderizam só esse nome
LICENSE.md, LICENSE SPDX/forge convention
CODE_OF_CONDUCT.md, SECURITY.md GitHub-style community health files
.github*.md, .gitea/**/*.md Issue/PR templates lidos pelo forge
Build/vendor trees: node_modules, vendor, target, build, .git Conteúdo de terceiros / build output — fora do escopo
meta/context*.md (memória, k-save, hooks output) Arquivos lidos por agentes externos que esperam .md; reavaliar caso a caso quando tooling for atualizado

Quando há dúvida: .kmd é a escolha segura. Se uma ferramenta externa quebrar, abrir issue + voltar para .md localmente.

Caveat — policies (este arquivo) e specs

  • *metadocsstack/specs.kmd`* — já é a convenção. Continuar.
  • *metadocsstack/policies.md`* — atualmente .md por motivos

    históricos. CLAUDE.md global faz referência por nome (policies/X.md). *ção tracked* migrar policies para .kmd quando CLAUDE.md aceitar reescrita das referências. Até lá, novas policies entram em .md para consistência com as siblings (incluindo este arquivo).

  • *metadocsstack/modules

*.md → .kmd`) em sweep única, atualizando CLAUDE.md global no mesmo commit |

4 Migração de meta/docs/stack/modules*.md quando o pipeline de

/k-housekeep for refatorado |

5 Avaliar migração seletiva de meta/context*.md (parcial — só os

que não são lidos por agentes externos hoje) |

Source: ../home/koder/dev/koder/meta/docs/stack/policies/document-format.kmd