From 38104ae4a75f5e720601b0eaf92ad11d972e2d66 Mon Sep 17 00:00:00 2001 From: Roni Fabio Banaszewski Date: Mon, 31 Aug 2026 21:06:05 -0300 Subject: [PATCH 1/3] cascas: Cursor e OpenCode com a trava de escrita dos revisores Co-Authored-By: Claude Opus 5 --- .cursor/agents/auditor-final.md | 8 ++++++++ .cursor/agents/implementador.md | 5 +++++ .cursor/agents/revisor-codigo.md | 8 ++++++++ .cursor/agents/revisor-conformidade.md | 8 ++++++++ .cursor/agents/tutor.md | 8 ++++++++ .cursor/commands/utf-architecture.md | 5 +++++ .cursor/commands/utf-backlog.md | 5 +++++ .cursor/commands/utf-flows.md | 5 +++++ .cursor/commands/utf-issue.md | 7 +++++++ .cursor/commands/utf-prd.md | 5 +++++ .cursor/commands/utf-setup.md | 5 +++++ .cursor/commands/utf-task.md | 7 +++++++ .cursor/commands/utf-tutor.md | 7 +++++++ .cursor/rules/utf-rules.mdc | 9 +++++++++ .opencode/agents/auditor-final.md | 22 ++++++++++++++++++++++ .opencode/agents/implementador.md | 5 +++++ .opencode/agents/revisor-codigo.md | 22 ++++++++++++++++++++++ .opencode/agents/revisor-conformidade.md | 22 ++++++++++++++++++++++ .opencode/agents/tutor.md | 18 ++++++++++++++++++ .opencode/command/utf-architecture.md | 5 +++++ .opencode/command/utf-backlog.md | 5 +++++ .opencode/command/utf-flows.md | 5 +++++ .opencode/command/utf-issue.md | 7 +++++++ .opencode/command/utf-prd.md | 5 +++++ .opencode/command/utf-setup.md | 5 +++++ .opencode/command/utf-task.md | 7 +++++++ .opencode/command/utf-tutor.md | 7 +++++++ AGENTS.md | 7 +++++++ README.md | 23 ++++++++++++++++++++++- 29 files changed, 256 insertions(+), 1 deletion(-) create mode 100644 .cursor/agents/auditor-final.md create mode 100644 .cursor/agents/implementador.md create mode 100644 .cursor/agents/revisor-codigo.md create mode 100644 .cursor/agents/revisor-conformidade.md create mode 100644 .cursor/agents/tutor.md create mode 100644 .cursor/commands/utf-architecture.md create mode 100644 .cursor/commands/utf-backlog.md create mode 100644 .cursor/commands/utf-flows.md create mode 100644 .cursor/commands/utf-issue.md create mode 100644 .cursor/commands/utf-prd.md create mode 100644 .cursor/commands/utf-setup.md create mode 100644 .cursor/commands/utf-task.md create mode 100644 .cursor/commands/utf-tutor.md create mode 100644 .cursor/rules/utf-rules.mdc create mode 100644 .opencode/agents/auditor-final.md create mode 100644 .opencode/agents/implementador.md create mode 100644 .opencode/agents/revisor-codigo.md create mode 100644 .opencode/agents/revisor-conformidade.md create mode 100644 .opencode/agents/tutor.md create mode 100644 .opencode/command/utf-architecture.md create mode 100644 .opencode/command/utf-backlog.md create mode 100644 .opencode/command/utf-flows.md create mode 100644 .opencode/command/utf-issue.md create mode 100644 .opencode/command/utf-prd.md create mode 100644 .opencode/command/utf-setup.md create mode 100644 .opencode/command/utf-task.md create mode 100644 .opencode/command/utf-tutor.md create mode 100644 AGENTS.md diff --git a/.cursor/agents/auditor-final.md b/.cursor/agents/auditor-final.md new file mode 100644 index 0000000..02987c7 --- /dev/null +++ b/.cursor/agents/auditor-final.md @@ -0,0 +1,8 @@ +--- +name: auditor-final +description: Compara o diff inteiro da branch contra o spec.md original, antes do Pull Request. Somente leitura. +readonly: true +--- +Leia `.agents/agents/auditor-final.md` e siga-o integralmente antes de qualquer outra ação. + +O terminal existe apenas para `git diff`, `git log` e para rodar os testes. É proibido usá-lo para alterar qualquer arquivo. diff --git a/.cursor/agents/implementador.md b/.cursor/agents/implementador.md new file mode 100644 index 0000000..2a9a085 --- /dev/null +++ b/.cursor/agents/implementador.md @@ -0,0 +1,5 @@ +--- +name: implementador +description: Implementa UMA tarefa do plan.md seguindo TDD, com contexto limpo. Não revisa o próprio trabalho. +--- +Leia `.agents/agents/implementador.md` e siga-o integralmente antes de qualquer outra ação. diff --git a/.cursor/agents/revisor-codigo.md b/.cursor/agents/revisor-codigo.md new file mode 100644 index 0000000..4b766e3 --- /dev/null +++ b/.cursor/agents/revisor-codigo.md @@ -0,0 +1,8 @@ +--- +name: revisor-codigo +description: Revisa a qualidade do código de uma tarefa contra docs/architecture.md. Somente leitura — aponta, nunca corrige. +readonly: true +--- +Leia `.agents/agents/revisor-codigo.md` e siga-o integralmente antes de qualquer outra ação. + +O terminal existe apenas para `git diff`, `git log` e para rodar os testes. É proibido usá-lo para alterar qualquer arquivo. diff --git a/.cursor/agents/revisor-conformidade.md b/.cursor/agents/revisor-conformidade.md new file mode 100644 index 0000000..7642957 --- /dev/null +++ b/.cursor/agents/revisor-conformidade.md @@ -0,0 +1,8 @@ +--- +name: revisor-conformidade +description: Compara o diff de uma tarefa contra os critérios de aceite do spec.md. Somente leitura — aponta, nunca corrige. +readonly: true +--- +Leia `.agents/agents/revisor-conformidade.md` e siga-o integralmente antes de qualquer outra ação. + +O terminal existe apenas para `git diff`, `git log` e para rodar os testes. É proibido usá-lo para alterar qualquer arquivo. diff --git a/.cursor/agents/tutor.md b/.cursor/agents/tutor.md new file mode 100644 index 0000000..59cc9e6 --- /dev/null +++ b/.cursor/agents/tutor.md @@ -0,0 +1,8 @@ +--- +name: tutor +description: Ensina o aluno — explica a tarefa antes, o diff depois, a spec e o simulado pré-PR. Não escreve código, não corrige, não opina sobre qualidade. +readonly: true +--- +Leia `.agents/agents/tutor.md` e siga-o integralmente antes de qualquer outra ação. + +O terminal existe apenas para `git diff`, `git log` e para rodar os testes. É proibido usá-lo para alterar qualquer arquivo. diff --git a/.cursor/commands/utf-architecture.md b/.cursor/commands/utf-architecture.md new file mode 100644 index 0000000..34de834 --- /dev/null +++ b/.cursor/commands/utf-architecture.md @@ -0,0 +1,5 @@ +--- +description: Gera o docs/architecture.md por entrevista guiada — stack, monorepo, testes, glossário técnico e diagrama ER. Roda depois do /utf-flows. +--- + +Leia `.agents/workflows/architecture.md` e execute-o integralmente. diff --git a/.cursor/commands/utf-backlog.md b/.cursor/commands/utf-backlog.md new file mode 100644 index 0000000..3aaed35 --- /dev/null +++ b/.cursor/commands/utf-backlog.md @@ -0,0 +1,5 @@ +--- +description: Leva as stories Ready do prd.md para o GitHub — uma Issue por story e orientação do Kanban. Exige gh autenticado ou MCP do GitHub. +--- + +Leia `.agents/workflows/backlog.md` e execute-o integralmente. diff --git a/.cursor/commands/utf-flows.md b/.cursor/commands/utf-flows.md new file mode 100644 index 0000000..d6535ab --- /dev/null +++ b/.cursor/commands/utf-flows.md @@ -0,0 +1,5 @@ +--- +description: Desenha as jornadas de usuário e os tokens de design. Obriga pelo menos uma jornada com ponto de desistência. Roda antes do /utf-architecture. +--- + +Leia `.agents/workflows/user-flows.md` e execute-o integralmente. diff --git a/.cursor/commands/utf-issue.md b/.cursor/commands/utf-issue.md new file mode 100644 index 0000000..ebc3560 --- /dev/null +++ b/.cursor/commands/utf-issue.md @@ -0,0 +1,7 @@ +--- +description: Inicia o ciclo SDD completo de uma Issue — brainstorming, spec.md, plan.md e execução tarefa a tarefa. +--- + +Leia `.agents/workflows/utf-workflow.md` e execute-o integralmente. + +Issue a trabalhar: o valor que o usuário escreveu depois do comando. diff --git a/.cursor/commands/utf-prd.md b/.cursor/commands/utf-prd.md new file mode 100644 index 0000000..f1bd539 --- /dev/null +++ b/.cursor/commands/utf-prd.md @@ -0,0 +1,5 @@ +--- +description: Gera o docs/prd.md por entrevista guiada — tema, glossário, atores, user stories, regras de negócio e NFRs. Roda antes do /utf-flows. +--- + +Leia `.agents/workflows/prd.md` e execute-o integralmente. diff --git a/.cursor/commands/utf-setup.md b/.cursor/commands/utf-setup.md new file mode 100644 index 0000000..2600a6c --- /dev/null +++ b/.cursor/commands/utf-setup.md @@ -0,0 +1,5 @@ +--- +description: Gera a estrutura inicial do monorepo a partir do docs/architecture.md. Roda uma vez, antes da primeira Issue. Task de manutenção — sem spec. +--- + +Leia `.agents/workflows/setup.md` e execute-o integralmente. diff --git a/.cursor/commands/utf-task.md b/.cursor/commands/utf-task.md new file mode 100644 index 0000000..b16f266 --- /dev/null +++ b/.cursor/commands/utf-task.md @@ -0,0 +1,7 @@ +--- +description: Executa UMA tarefa do plan.md com implementador de contexto limpo, dois revisores somente-leitura e limite de 2 rodadas de revisão. Sem número, pega a próxima pendente. +--- + +Leia `.agents/workflows/ciclo-tarefa.md` e execute-o integralmente. + +Tarefa a executar: o valor que o usuário escreveu depois do comando. diff --git a/.cursor/commands/utf-tutor.md b/.cursor/commands/utf-tutor.md new file mode 100644 index 0000000..045833f --- /dev/null +++ b/.cursor/commands/utf-tutor.md @@ -0,0 +1,7 @@ +--- +description: Chama o agente tutor: explica a tarefa já implementada; antes explica antes de implementar; spec explica a spec em rascunho; prova conduz o simulado pré-PR. +--- + +Leia `.agents/workflows/tutor.md` e execute-o integralmente. + +Argumento: o valor que o usuário escreveu depois do comando. diff --git a/.cursor/rules/utf-rules.mdc b/.cursor/rules/utf-rules.mdc new file mode 100644 index 0000000..77f8d2b --- /dev/null +++ b/.cursor/rules/utf-rules.mdc @@ -0,0 +1,9 @@ +--- +description: Constituição da disciplina — as regras inegociáveis do método UTF-SDD. +alwaysApply: true +--- + +Leia `.agents/rules/utf-rules.md` e obedeça-o integralmente. Ele é a constituição +deste repositório; este arquivo é só a casca do Cursor. + +@.agents/rules/utf-rules.md diff --git a/.opencode/agents/auditor-final.md b/.opencode/agents/auditor-final.md new file mode 100644 index 0000000..63d1d8f --- /dev/null +++ b/.opencode/agents/auditor-final.md @@ -0,0 +1,22 @@ +--- +description: Compara o diff inteiro da branch contra o spec.md original, antes do Pull Request. Somente leitura. +mode: subagent +permission: + edit: deny + bash: + "*": deny + "git diff*": allow + "git log*": allow + "git status*": allow + "ls*": allow + "cat*": allow + "npm test*": allow + "npm run test*": allow + "npx vitest*": allow + "npx jest*": allow +--- +Leia `.agents/agents/auditor-final.md` e siga-o integralmente antes de qualquer outra ação. + +> A lista de comandos liberados acima cobre git e os testes mais comuns. +> **Ajuste-a à stack declarada no `docs/architecture.md`** — comando de teste +> que não estiver liberado simplesmente não roda, e o parecer sai incompleto. diff --git a/.opencode/agents/implementador.md b/.opencode/agents/implementador.md new file mode 100644 index 0000000..bdd2732 --- /dev/null +++ b/.opencode/agents/implementador.md @@ -0,0 +1,5 @@ +--- +description: Implementa UMA tarefa do plan.md seguindo TDD, com contexto limpo. Não revisa o próprio trabalho. +mode: subagent +--- +Leia `.agents/agents/implementador.md` e siga-o integralmente antes de qualquer outra ação. diff --git a/.opencode/agents/revisor-codigo.md b/.opencode/agents/revisor-codigo.md new file mode 100644 index 0000000..38e802a --- /dev/null +++ b/.opencode/agents/revisor-codigo.md @@ -0,0 +1,22 @@ +--- +description: Revisa a qualidade do código de uma tarefa contra docs/architecture.md. Somente leitura — aponta, nunca corrige. +mode: subagent +permission: + edit: deny + bash: + "*": deny + "git diff*": allow + "git log*": allow + "git status*": allow + "ls*": allow + "cat*": allow + "npm test*": allow + "npm run test*": allow + "npx vitest*": allow + "npx jest*": allow +--- +Leia `.agents/agents/revisor-codigo.md` e siga-o integralmente antes de qualquer outra ação. + +> A lista de comandos liberados acima cobre git e os testes mais comuns. +> **Ajuste-a à stack declarada no `docs/architecture.md`** — comando de teste +> que não estiver liberado simplesmente não roda, e o parecer sai incompleto. diff --git a/.opencode/agents/revisor-conformidade.md b/.opencode/agents/revisor-conformidade.md new file mode 100644 index 0000000..0322009 --- /dev/null +++ b/.opencode/agents/revisor-conformidade.md @@ -0,0 +1,22 @@ +--- +description: Compara o diff de uma tarefa contra os critérios de aceite do spec.md. Somente leitura — aponta, nunca corrige. +mode: subagent +permission: + edit: deny + bash: + "*": deny + "git diff*": allow + "git log*": allow + "git status*": allow + "ls*": allow + "cat*": allow + "npm test*": allow + "npm run test*": allow + "npx vitest*": allow + "npx jest*": allow +--- +Leia `.agents/agents/revisor-conformidade.md` e siga-o integralmente antes de qualquer outra ação. + +> A lista de comandos liberados acima cobre git e os testes mais comuns. +> **Ajuste-a à stack declarada no `docs/architecture.md`** — comando de teste +> que não estiver liberado simplesmente não roda, e o parecer sai incompleto. diff --git a/.opencode/agents/tutor.md b/.opencode/agents/tutor.md new file mode 100644 index 0000000..562d820 --- /dev/null +++ b/.opencode/agents/tutor.md @@ -0,0 +1,18 @@ +--- +description: Ensina o aluno — explica a tarefa antes, o diff depois, a spec e o simulado pré-PR. Não escreve código, não corrige, não opina sobre qualidade. +mode: subagent +permission: + edit: deny + bash: + "*": deny + "git diff*": allow + "git log*": allow + "git status*": allow + "ls*": allow + "cat*": allow +--- +Leia `.agents/agents/tutor.md` e siga-o integralmente antes de qualquer outra ação. + +> A lista de comandos liberados acima cobre git e os testes mais comuns. +> **Ajuste-a à stack declarada no `docs/architecture.md`** — comando de teste +> que não estiver liberado simplesmente não roda, e o parecer sai incompleto. diff --git a/.opencode/command/utf-architecture.md b/.opencode/command/utf-architecture.md new file mode 100644 index 0000000..34de834 --- /dev/null +++ b/.opencode/command/utf-architecture.md @@ -0,0 +1,5 @@ +--- +description: Gera o docs/architecture.md por entrevista guiada — stack, monorepo, testes, glossário técnico e diagrama ER. Roda depois do /utf-flows. +--- + +Leia `.agents/workflows/architecture.md` e execute-o integralmente. diff --git a/.opencode/command/utf-backlog.md b/.opencode/command/utf-backlog.md new file mode 100644 index 0000000..3aaed35 --- /dev/null +++ b/.opencode/command/utf-backlog.md @@ -0,0 +1,5 @@ +--- +description: Leva as stories Ready do prd.md para o GitHub — uma Issue por story e orientação do Kanban. Exige gh autenticado ou MCP do GitHub. +--- + +Leia `.agents/workflows/backlog.md` e execute-o integralmente. diff --git a/.opencode/command/utf-flows.md b/.opencode/command/utf-flows.md new file mode 100644 index 0000000..d6535ab --- /dev/null +++ b/.opencode/command/utf-flows.md @@ -0,0 +1,5 @@ +--- +description: Desenha as jornadas de usuário e os tokens de design. Obriga pelo menos uma jornada com ponto de desistência. Roda antes do /utf-architecture. +--- + +Leia `.agents/workflows/user-flows.md` e execute-o integralmente. diff --git a/.opencode/command/utf-issue.md b/.opencode/command/utf-issue.md new file mode 100644 index 0000000..91f6ba9 --- /dev/null +++ b/.opencode/command/utf-issue.md @@ -0,0 +1,7 @@ +--- +description: Inicia o ciclo SDD completo de uma Issue — brainstorming, spec.md, plan.md e execução tarefa a tarefa. +--- + +Leia `.agents/workflows/utf-workflow.md` e execute-o integralmente. + +Issue a trabalhar: $ARGUMENTS diff --git a/.opencode/command/utf-prd.md b/.opencode/command/utf-prd.md new file mode 100644 index 0000000..f1bd539 --- /dev/null +++ b/.opencode/command/utf-prd.md @@ -0,0 +1,5 @@ +--- +description: Gera o docs/prd.md por entrevista guiada — tema, glossário, atores, user stories, regras de negócio e NFRs. Roda antes do /utf-flows. +--- + +Leia `.agents/workflows/prd.md` e execute-o integralmente. diff --git a/.opencode/command/utf-setup.md b/.opencode/command/utf-setup.md new file mode 100644 index 0000000..2600a6c --- /dev/null +++ b/.opencode/command/utf-setup.md @@ -0,0 +1,5 @@ +--- +description: Gera a estrutura inicial do monorepo a partir do docs/architecture.md. Roda uma vez, antes da primeira Issue. Task de manutenção — sem spec. +--- + +Leia `.agents/workflows/setup.md` e execute-o integralmente. diff --git a/.opencode/command/utf-task.md b/.opencode/command/utf-task.md new file mode 100644 index 0000000..afb8bbf --- /dev/null +++ b/.opencode/command/utf-task.md @@ -0,0 +1,7 @@ +--- +description: Executa UMA tarefa do plan.md com implementador de contexto limpo, dois revisores somente-leitura e limite de 2 rodadas de revisão. Sem número, pega a próxima pendente. +--- + +Leia `.agents/workflows/ciclo-tarefa.md` e execute-o integralmente. + +Tarefa a executar: $ARGUMENTS diff --git a/.opencode/command/utf-tutor.md b/.opencode/command/utf-tutor.md new file mode 100644 index 0000000..2899bd5 --- /dev/null +++ b/.opencode/command/utf-tutor.md @@ -0,0 +1,7 @@ +--- +description: Chama o agente tutor: explica a tarefa já implementada; antes explica antes de implementar; spec explica a spec em rascunho; prova conduz o simulado pré-PR. +--- + +Leia `.agents/workflows/tutor.md` e execute-o integralmente. + +Argumento: $ARGUMENTS diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..80454ec --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,7 @@ +# Regras deste repositório + +Leia `.agents/rules/utf-rules.md` e obedeça-o integralmente — é a constituição do +método UTF-SDD, e vale para qualquer agente que trabalhe aqui. + +Os fluxos ficam em `.agents/workflows/` e os subagentes em `.agents/agents/`. +Cada harness tem só a casca: `.claude/`, `.cursor/`, `.opencode/`. O conteúdo é um só. diff --git a/README.md b/README.md index 3e91366..df2c717 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,9 @@ nunca é quem escreveu, e todo artefato é evidência para a defesa. 1. Clique em **Use this template → Create a new repository** (não faça fork). O repositório criado é seu. -2. Clone o seu repositório e abra-o na sua IDE agêntica (Claude Code, Cursor…). +2. Clone o seu repositório e abra-o na sua IDE agêntica. **Claude Code, Cursor, + Antigravity e OpenCode já vêm configurados** — inclusive a trava que impede os + revisores de editar arquivo. Veja *Um método, quatro ferramentas*, abaixo. 3. Leia `docs/checklist.md` — é a **ficha da disciplina**: as regras do projeto, os Indicadores de Desempenho (IDs) e as entregas. 4. Siga o fluxo, um comando por fase: @@ -25,6 +27,25 @@ nunca é quem escreveu, e todo artefato é evidência para a defesa. | Cada história | `/utf-issue ` → `/utf-task` | spec, plano e código, tarefa a tarefa | | Aprender | `/utf-tutor` | a explicação didática de cada passo | +### Um método, quatro ferramentas + +O conteúdo de verdade — constituição, fluxos e subagentes — vive uma vez só, em +`.agents/`. Cada ferramenta tem apenas uma casca de poucas linhas que aponta para +lá, com a sintaxe de permissão dela. Trocar de ferramenta no meio do semestre não +reescreve nada: o miolo é o mesmo. + +| Ferramenta | Regras | Comandos | Subagentes | +| --- | --- | --- | --- | +| Claude Code | `CLAUDE.md` | `.claude/commands/` | `.claude/agents/` | +| Cursor | `.cursor/rules/` | `.cursor/commands/` | `.cursor/agents/` | +| Antigravity | `.agents/rules/` | `.agents/workflows/` | `.agents/agents/` | +| OpenCode | `AGENTS.md` | `.opencode/command/` | `.opencode/agents/` | + +O **OpenCode funciona com modelos gratuitos** e é o único dos quatro que libera +comandos específicos do terminal em vez de ligar ou desligar o terminal inteiro — +a trava mais fechada das quatro. Ajuste a lista de comandos de teste em +`.opencode/agents/` à stack do seu `docs/architecture.md`. + O passo a passo detalhado está em [`docs/tutorial-sdd.md`](docs/tutorial-sdd.md); o porquê de cada regra, em [`docs/guia-sdd.md`](docs/guia-sdd.md). From d78794d0d21d29d22a5b22c2065b3f354d29c029 Mon Sep 17 00:00:00 2001 From: Roni Fabio Banaszewski Date: Mon, 31 Aug 2026 21:14:09 -0300 Subject: [PATCH 2/3] antigravity: trava de escrita dos revisores pela lista tools Co-Authored-By: Claude Opus 5 --- .agents/agents/auditor-final.md | 12 ++++++++++++ .agents/agents/implementador.md | 3 +++ .agents/agents/revisor-codigo.md | 12 ++++++++++++ .agents/agents/revisor-conformidade.md | 12 ++++++++++++ .agents/agents/tutor.md | 12 ++++++++++++ README.md | 20 ++++++++++++++++---- docs/guia-sdd.md | 15 +++++++++++---- 7 files changed, 78 insertions(+), 8 deletions(-) diff --git a/.agents/agents/auditor-final.md b/.agents/agents/auditor-final.md index d8d92b1..9c6aeac 100644 --- a/.agents/agents/auditor-final.md +++ b/.agents/agents/auditor-final.md @@ -1,8 +1,20 @@ --- name: auditor-final description: Passo 6 do ciclo. Compara o diff INTEIRO da branch contra a spec.md original, não contra o plano. Somente leitura. +mainAgent: false +subagent: true +tools: + - view_file + - grep_search + - run_command --- + + + # Auditor Final Você entra **uma vez**, quando todas as tarefas do `plan.md` terminaram. Sua pergunta é diferente da dos revisores de tarefa: diff --git a/.agents/agents/implementador.md b/.agents/agents/implementador.md index 479ddc9..1a3e0f2 100644 --- a/.agents/agents/implementador.md +++ b/.agents/agents/implementador.md @@ -1,8 +1,11 @@ --- name: implementador description: Implementa UMA tarefa do plan.md seguindo TDD, com contexto limpo. Não revisa o próprio trabalho e não decide que terminou. +mainAgent: false +subagent: true --- + # Implementador Você implementa **uma única tarefa** de um `plan.md`. Você não enxerga a conversa que te despachou: tudo que você precisa está no prompt de despacho e nos arquivos citados nele. Se faltar informação, **pergunte antes de escrever código** — não deduza. diff --git a/.agents/agents/revisor-codigo.md b/.agents/agents/revisor-codigo.md index bbda09c..7aa26f7 100644 --- a/.agents/agents/revisor-codigo.md +++ b/.agents/agents/revisor-codigo.md @@ -1,8 +1,20 @@ --- name: revisor-codigo description: Revisa qualidade do código de uma tarefa contra docs/architecture.md. Somente leitura — aponta, nunca corrige. +mainAgent: false +subagent: true +tools: + - view_file + - grep_search + - run_command --- + + + # Revisor de Código Você responde **uma única pergunta**: *este código respeita a arquitetura acordada e vai ser sustentável daqui a três semanas?* diff --git a/.agents/agents/revisor-conformidade.md b/.agents/agents/revisor-conformidade.md index 3ce0acd..76139d4 100644 --- a/.agents/agents/revisor-conformidade.md +++ b/.agents/agents/revisor-conformidade.md @@ -1,8 +1,20 @@ --- name: revisor-conformidade description: Compara o diff de uma tarefa contra os critérios de aceite do spec.md. Somente leitura — aponta, nunca corrige. +mainAgent: false +subagent: true +tools: + - view_file + - grep_search + - run_command --- + + + # Revisor de Conformidade Você responde **uma única pergunta**: *o que foi implementado atende ao que a `spec.md` pediu?* diff --git a/.agents/agents/tutor.md b/.agents/agents/tutor.md index 9a14cea..1eb1fc1 100644 --- a/.agents/agents/tutor.md +++ b/.agents/agents/tutor.md @@ -1,8 +1,20 @@ --- name: tutor description: Ensina o aluno, em nível bem didático, o que uma tarefa vai construir (antes) ou o que o diff construiu (depois). Não escreve código, não corrige, não opina sobre qualidade. Também explica decisões da spec e gera o simulado pré-PR. +mainAgent: false +subagent: true +tools: + - view_file + - grep_search + - run_command --- + + + # Tutor Você tem uma função só: **ensinar**. O aluno está aprendendo NestJS, Prisma e o frontend enquanto constrói o projeto — trate **todo conceito como possivelmente novo** para ele. Sua explicação é o que o prepara para a defesa presencial, onde ele terá que explicar cada trecho **sem você**. diff --git a/README.md b/README.md index df2c717..778a52b 100644 --- a/README.md +++ b/README.md @@ -41,10 +41,22 @@ reescreve nada: o miolo é o mesmo. | Antigravity | `.agents/rules/` | `.agents/workflows/` | `.agents/agents/` | | OpenCode | `AGENTS.md` | `.opencode/command/` | `.opencode/agents/` | -O **OpenCode funciona com modelos gratuitos** e é o único dos quatro que libera -comandos específicos do terminal em vez de ligar ou desligar o terminal inteiro — -a trava mais fechada das quatro. Ajuste a lista de comandos de teste em -`.opencode/agents/` à stack do seu `docs/architecture.md`. +Nas quatro, os revisores e o tutor nascem **sem poder de escrita**; só o +implementador escreve. A trava tem forças diferentes, e vale saber qual você tem: + +- **Claude Code, Cursor e Antigravity** negam a ferramenta de edição, mas precisam + liberar o terminal para o revisor rodar `git diff`. Quem tem terminal poderia, em + tese, escrever com `sed` ou redirecionamento — o que fecha isso ali é a proibição + escrita no prompt do agente. +- **O OpenCode fecha por configuração:** é o único que libera comandos específicos em + vez de ligar ou desligar o terminal inteiro. E **funciona com modelos gratuitos**, + o que faz dele o caminho de custo zero mais completo da disciplina. Ajuste a lista + de comandos de teste em `.opencode/agents/` à stack do seu `docs/architecture.md`: + comando que não estiver liberado não roda, e o parecer sai incompleto sem avisar. + +> Se o seu OpenCode não listar os agentes ou os comandos, é diferença de versão nos +> nomes das pastas: renomeie `.opencode/agents/` para `.opencode/agent/` e +> `.opencode/command/` para `.opencode/commands/`. O conteúdo é o mesmo. O passo a passo detalhado está em [`docs/tutorial-sdd.md`](docs/tutorial-sdd.md); o porquê de cada regra, em [`docs/guia-sdd.md`](docs/guia-sdd.md). diff --git a/docs/guia-sdd.md b/docs/guia-sdd.md index 9ec71a1..11e6f8c 100644 --- a/docs/guia-sdd.md +++ b/docs/guia-sdd.md @@ -1220,7 +1220,7 @@ partida, não fonte da verdade. | | Regras sempre ativas | Comando de fluxo | Subagentes | Trava de escrita | | --- | --- | --- | --- | --- | | **Claude Code** | `CLAUDE.md` | `.claude/commands/.md` | `.claude/agents/.md` | `tools:` — libera ou nega o terminal inteiro | -| **Antigravity** | `.agents/rules/.md` com `trigger: always_on` | painel *Customizations → Workflows*, invocado por `/nome` | `.agents/agents//agent.md` com `subagent: true` | `tools:` (lista) + `commandExecutionPolicy` | +| **Antigravity** | `.agents/rules/.md` com `trigger: always_on` | painel *Customizations → Workflows*, invocado por `/nome` | `.agents/agents/.md` (ou `/agent.md`) | `tools:` — a lista **é** a trava: o que não está nela o agente não tem | | **Cursor** | `.cursor/rules/.mdc` com `alwaysApply: true` | `.cursor/commands/.md` | `.cursor/agents/.md` | `readonly: true` — bloqueia edição e comandos que mudam estado | | **OpenCode** | `AGENTS.md` | `.opencode/command/.md` | `.opencode/agents/.md` com `mode: subagent` | `permission:` — aceita lista de comandos permitidos | @@ -1230,9 +1230,16 @@ Duas observações práticas: gratuitos e é o único dos quatro que deixa você liberar comandos específicos do terminal em vez de ligar ou desligar o terminal inteiro — o que fecha exatamente a brecha descrita no §7. -- **No Antigravity, cada agente é uma pasta**, não um arquivo solto: o caminho é - `.agents/agents/revisor-codigo/agent.md`. E nome de ferramenta escrito errado no - `tools:` faz o subagente travar em vez de dar erro — confira a grafia. +- **No Antigravity, a trava é a lista `tools:`, e ela é excludente**: o agente recebe + exatamente as ferramentas listadas e nada mais. Um revisor com + `view_file`, `grep_search` e `run_command` não tem como editar arquivo, porque a + ferramenta de escrita simplesmente não está lá. O `commandExecutionPolicy` aceita só + `off`, `auto`, `eager` e `sandbox` — ele não faz lista de comandos permitidos, então + não fecha a brecha do terminal. E **nome de ferramenta escrito errado trava o subagente + em vez de dar erro** — confira a grafia na documentação antes de inventar um nome. +- **Não liste `tools:` no agente que precisa escrever.** Lista incompleta tira dele a + ferramenta de edição, e ele trava em silêncio. Restrinja onde a restrição é o objetivo; + no implementador, deixe o padrão. Exemplo de um revisor somente-leitura no OpenCode, que é a forma mais completa da trava: From 3fbebb53210c864a93c81c39eb90df2e3b6210e2 Mon Sep 17 00:00:00 2001 From: Roni Fabio Banaszewski Date: Mon, 31 Aug 2026 21:33:57 -0300 Subject: [PATCH 3/3] opencode: tira write/edit do catalogo, alem de negar por permissao O bloco `permission:` nega na hora da chamada, mas mantem a ferramenta no catalogo do agente. O bloco `tools:` a remove. O guia prescreve os dois; so o `permission:` estava aplicado. Co-Authored-By: Claude Opus 5 --- .opencode/agents/auditor-final.md | 4 ++++ .opencode/agents/revisor-codigo.md | 4 ++++ .opencode/agents/revisor-conformidade.md | 4 ++++ .opencode/agents/tutor.md | 4 ++++ 4 files changed, 16 insertions(+) diff --git a/.opencode/agents/auditor-final.md b/.opencode/agents/auditor-final.md index 63d1d8f..4447145 100644 --- a/.opencode/agents/auditor-final.md +++ b/.opencode/agents/auditor-final.md @@ -1,6 +1,10 @@ --- description: Compara o diff inteiro da branch contra o spec.md original, antes do Pull Request. Somente leitura. mode: subagent +tools: + write: false + edit: false + patch: false permission: edit: deny bash: diff --git a/.opencode/agents/revisor-codigo.md b/.opencode/agents/revisor-codigo.md index 38e802a..e848860 100644 --- a/.opencode/agents/revisor-codigo.md +++ b/.opencode/agents/revisor-codigo.md @@ -1,6 +1,10 @@ --- description: Revisa a qualidade do código de uma tarefa contra docs/architecture.md. Somente leitura — aponta, nunca corrige. mode: subagent +tools: + write: false + edit: false + patch: false permission: edit: deny bash: diff --git a/.opencode/agents/revisor-conformidade.md b/.opencode/agents/revisor-conformidade.md index 0322009..d53ab4a 100644 --- a/.opencode/agents/revisor-conformidade.md +++ b/.opencode/agents/revisor-conformidade.md @@ -1,6 +1,10 @@ --- description: Compara o diff de uma tarefa contra os critérios de aceite do spec.md. Somente leitura — aponta, nunca corrige. mode: subagent +tools: + write: false + edit: false + patch: false permission: edit: deny bash: diff --git a/.opencode/agents/tutor.md b/.opencode/agents/tutor.md index 562d820..da5d4b3 100644 --- a/.opencode/agents/tutor.md +++ b/.opencode/agents/tutor.md @@ -1,6 +1,10 @@ --- description: Ensina o aluno — explica a tarefa antes, o diff depois, a spec e o simulado pré-PR. Não escreve código, não corrige, não opina sobre qualidade. mode: subagent +tools: + write: false + edit: false + patch: false permission: edit: deny bash: