From b8e393e8e5502e5f6f99147cbca59d43b6def88b Mon Sep 17 00:00:00 2001 From: Wesley Simplicio Date: Tue, 4 Aug 2026 16:33:22 -0300 Subject: [PATCH 1/8] docs: add global LLM architecture rules --- AGENTS.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 16a0169b..86a9d7f1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,3 +9,31 @@ Use `simplicio-mapper` for bounded context, `simplicio-fast` for snapshots and P ### Execution and evidence Use `simplicio`/`simplicio shell compact` for inspection and `simplicio edit --plan` or governed dev-cli for mutation. Preserve `simplicio.io/v1`; run `simplicio contracts smoke --json`, focused tests and `simplicio validate "" --repo . --json`; close only with `simplicio evidence`. Facts are `MEASURED|` only with receipts, otherwise `UNVERIFIED|`; savings come only from `simplicio savings report --repo . --json`. Missing dependencies fail closed; never fabricate context or output. + + +## Regras arquiteturais obrigatórias para qualquer LLM + +Estas regras valem para análise, planejamento, implementação, revisão, testes, +release e documentação neste ecossistema. O agente deve lê-las antes de agir: + +1. **Não mantenha compatibilidade retroativa.** O que está obsoleto deve ser + deletado diretamente. Não adicione camadas de compatibilidade, migrações ou + fallbacks para preservar comportamento antigo. +2. **Escolha a implementação mais simples que atende à necessidade atual.** + Não crie abstrações preventivas nem camadas de configuração desnecessárias. +3. **Divida o sistema em camadas longas.** Faça primeiro uma versão mínima + end-to-end funcionando; depois adicione capacidades por cima. Não desmonte + algo que funciona por complexidades inacabadas. +4. **Mantenha os componentes modulares**, com responsabilidades claramente + separadas e limites explícitos. +5. **Priorize bibliotecas maduras e mantidas.** Não reescreva do zero sem + motivo técnico explícito e registrado. +6. **Inspecione primeiro as dependências existentes.** Antes de adicionar um + pacote ou escrever uma solução própria, verifique o que o projeto já possui. +7. **Decida a arquitetura pensando no longo prazo.** Não aceite soluções + temporárias com a intenção de mudar depois. +8. **Use padrões de produtos maduros.** Pesquise como soluções consolidadas + resolvem o mesmo problema e reutilize padrões validados; não reinvente a roda. + + + From 102daadff95da51b01c445381980733992e225a6 Mon Sep 17 00:00:00 2001 From: Wesley Simplicio Date: Tue, 4 Aug 2026 16:34:19 -0300 Subject: [PATCH 2/8] docs: add global LLM architecture guidance --- CLAUDE.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..9813bd91 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,31 @@ +# CLAUDE.md — simplicio-code + +Use `AGENTS.md` como contrato canônico deste repositório e cumpra as regras abaixo antes de agir. + + + +## Regras arquiteturais obrigatórias para qualquer LLM + +Estas regras valem para análise, planejamento, implementação, revisão, testes, +release e documentação neste ecossistema. O agente deve lê-las antes de agir: + +1. **Não mantenha compatibilidade retroativa.** O que está obsoleto deve ser + deletado diretamente. Não adicione camadas de compatibilidade, migrações ou + fallbacks para preservar comportamento antigo. +2. **Escolha a implementação mais simples que atende à necessidade atual.** + Não crie abstrações preventivas nem camadas de configuração desnecessárias. +3. **Divida o sistema em camadas longas.** Faça primeiro uma versão mínima + end-to-end funcionando; depois adicione capacidades por cima. Não desmonte + algo que funciona por complexidades inacabadas. +4. **Mantenha os componentes modulares**, com responsabilidades claramente + separadas e limites explícitos. +5. **Priorize bibliotecas maduras e mantidas.** Não reescreva do zero sem + motivo técnico explícito e registrado. +6. **Inspecione primeiro as dependências existentes.** Antes de adicionar um + pacote ou escrever uma solução própria, verifique o que o projeto já possui. +7. **Decida a arquitetura pensando no longo prazo.** Não aceite soluções + temporárias com a intenção de mudar depois. +8. **Use padrões de produtos maduros.** Pesquise como soluções consolidadas + resolvem o mesmo problema e reutilize padrões validados; não reinvente a roda. + + From 5b2e322df2bdd95cd76c29d22e9b59d6b8211b21 Mon Sep 17 00:00:00 2001 From: Wesley Simplicio Date: Tue, 4 Aug 2026 16:34:21 -0300 Subject: [PATCH 3/8] docs: add global LLM architecture guidance --- GEMINI.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 GEMINI.md diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 00000000..fcc20a69 --- /dev/null +++ b/GEMINI.md @@ -0,0 +1,31 @@ +# GEMINI.md — simplicio-code + +Use `AGENTS.md` como contrato canônico deste repositório. + + + +## Regras arquiteturais obrigatórias para qualquer LLM + +Estas regras valem para análise, planejamento, implementação, revisão, testes, +release e documentação neste ecossistema. O agente deve lê-las antes de agir: + +1. **Não mantenha compatibilidade retroativa.** O que está obsoleto deve ser + deletado diretamente. Não adicione camadas de compatibilidade, migrações ou + fallbacks para preservar comportamento antigo. +2. **Escolha a implementação mais simples que atende à necessidade atual.** + Não crie abstrações preventivas nem camadas de configuração desnecessárias. +3. **Divida o sistema em camadas longas.** Faça primeiro uma versão mínima + end-to-end funcionando; depois adicione capacidades por cima. Não desmonte + algo que funciona por complexidades inacabadas. +4. **Mantenha os componentes modulares**, com responsabilidades claramente + separadas e limites explícitos. +5. **Priorize bibliotecas maduras e mantidas.** Não reescreva do zero sem + motivo técnico explícito e registrado. +6. **Inspecione primeiro as dependências existentes.** Antes de adicionar um + pacote ou escrever uma solução própria, verifique o que o projeto já possui. +7. **Decida a arquitetura pensando no longo prazo.** Não aceite soluções + temporárias com a intenção de mudar depois. +8. **Use padrões de produtos maduros.** Pesquise como soluções consolidadas + resolvem o mesmo problema e reutilize padrões validados; não reinvente a roda. + + From 00b6baeaa3e2ee41316ec53437ae5418bab2a5fe Mon Sep 17 00:00:00 2001 From: Wesley Simplicio Date: Tue, 4 Aug 2026 16:34:22 -0300 Subject: [PATCH 4/8] docs: add global LLM architecture guidance --- llms.txt | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 llms.txt diff --git a/llms.txt b/llms.txt new file mode 100644 index 00000000..1eda5f3c --- /dev/null +++ b/llms.txt @@ -0,0 +1,22 @@ +# simplicio-code — LLM orientation + +Read AGENTS.md before planning or changing this repository. + + + +GLOBAL ARCHITECTURE RULES FOR LLMS + +1. Do not preserve backward compatibility. Delete obsolete behavior directly; + do not add compatibility layers, migrations, or legacy fallbacks. +2. Choose the simplest implementation that meets the current need. +3. Build long-lived layers incrementally: make the minimum end-to-end version + work first, then add capabilities without dismantling working code. +4. Keep components modular with clear separation of responsibilities. +5. Prefer mature, maintained libraries; do not rewrite from scratch without an + explicit technical reason. +6. Inspect existing dependencies before adding packages or reimplementing. +7. Make architecture decisions for the long term; do not leave temporary + solutions to change later. +8. Reuse validated patterns from mature products instead of reinventing them. + + From a22418746e1836906569dd171d58f7feb685d783 Mon Sep 17 00:00:00 2001 From: Wesley Simplicio Date: Tue, 4 Aug 2026 16:43:26 -0300 Subject: [PATCH 5/8] docs: make no-fallback policy explicit --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 86a9d7f1..021cccfa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,7 +18,7 @@ release e documentação neste ecossistema. O agente deve lê-las antes de agir: 1. **Não mantenha compatibilidade retroativa.** O que está obsoleto deve ser deletado diretamente. Não adicione camadas de compatibilidade, migrações ou - fallbacks para preservar comportamento antigo. + fallbacks. 2. **Escolha a implementação mais simples que atende à necessidade atual.** Não crie abstrações preventivas nem camadas de configuração desnecessárias. 3. **Divida o sistema em camadas longas.** Faça primeiro uma versão mínima From 1a049be6ba5fed2e637095c3ecf8bce73a4d8915 Mon Sep 17 00:00:00 2001 From: Wesley Simplicio Date: Tue, 4 Aug 2026 16:43:29 -0300 Subject: [PATCH 6/8] docs: make no-fallback policy explicit --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 9813bd91..29a8cf12 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -11,7 +11,7 @@ release e documentação neste ecossistema. O agente deve lê-las antes de agir: 1. **Não mantenha compatibilidade retroativa.** O que está obsoleto deve ser deletado diretamente. Não adicione camadas de compatibilidade, migrações ou - fallbacks para preservar comportamento antigo. + fallbacks. 2. **Escolha a implementação mais simples que atende à necessidade atual.** Não crie abstrações preventivas nem camadas de configuração desnecessárias. 3. **Divida o sistema em camadas longas.** Faça primeiro uma versão mínima From 2caf803f32f8ec6d388e45b94a7a1ce84a6dc5a6 Mon Sep 17 00:00:00 2001 From: Wesley Simplicio Date: Tue, 4 Aug 2026 16:43:30 -0300 Subject: [PATCH 7/8] docs: make no-fallback policy explicit --- GEMINI.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GEMINI.md b/GEMINI.md index fcc20a69..1753742d 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -11,7 +11,7 @@ release e documentação neste ecossistema. O agente deve lê-las antes de agir: 1. **Não mantenha compatibilidade retroativa.** O que está obsoleto deve ser deletado diretamente. Não adicione camadas de compatibilidade, migrações ou - fallbacks para preservar comportamento antigo. + fallbacks. 2. **Escolha a implementação mais simples que atende à necessidade atual.** Não crie abstrações preventivas nem camadas de configuração desnecessárias. 3. **Divida o sistema em camadas longas.** Faça primeiro uma versão mínima From 2a4cf050aa18480b1846f4496c29dd4da3edf4b7 Mon Sep 17 00:00:00 2001 From: Wesley Simplicio Date: Tue, 4 Aug 2026 16:43:32 -0300 Subject: [PATCH 8/8] docs: make no-fallback policy explicit --- llms.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/llms.txt b/llms.txt index 1eda5f3c..b73cd78e 100644 --- a/llms.txt +++ b/llms.txt @@ -7,7 +7,7 @@ Read AGENTS.md before planning or changing this repository. GLOBAL ARCHITECTURE RULES FOR LLMS 1. Do not preserve backward compatibility. Delete obsolete behavior directly; - do not add compatibility layers, migrations, or legacy fallbacks. + do not add compatibility layers, migrations, or fallbacks. 2. Choose the simplest implementation that meets the current need. 3. Build long-lived layers incrementally: make the minimum end-to-end version work first, then add capabilities without dismantling working code.