From 47043a8129cce1e6c05958a05e82517f107d594c Mon Sep 17 00:00:00 2001 From: Roni Fabio Banaszewski Date: Tue, 1 Sep 2026 17:47:23 -0300 Subject: [PATCH] fix: alinha guia, CONTRIBUTING e workflows com o restante do template MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Renomeia os arquivos de .agents/workflows/ para os nomes utf-* dos comandos (utf-workflow -> utf-issue, ciclo-tarefa -> utf-task), para os comandos /utf-* valerem também no Antigravity; atualiza todas as referências nas cascas (.claude, .cursor, .opencode) e na constituição - CONTRIBUTING: o Portão de Entendimento passa a descrever só a regra que o CI verifica (400 caracteres); a atualização de docs//specs/ é cobrada pelo auditor-final e pelo colega, não pelo CI - Guia §3.2: glossário do PRD volta a ser só de negócio (Termo/Significa/ Não confundir com), com o mapeamento PT->EN no architecture.md - Guia §6: remove restos de NestJS (Nest -> Angular inject(); decorator -> função de Guard) - Guia: remove linha duplicada do checklist.md (§3.6), corrige CPROVADO -> PENDENTE/CONFIRMADA e o zero à esquerda em 31-vaga-concorrente - Backlog: Kanban ganha a coluna Blocked que o guia já mencionava - architecture.md: título sem a expansão trocada da sigla SSD Co-Authored-By: Claude Fable 5 --- .agents/rules/utf-rules.md | 4 +-- .../{architecture.md => utf-architecture.md} | 0 .../workflows/{backlog.md => utf-backlog.md} | 2 +- .../workflows/{design.md => utf-design.md} | 0 .../{utf-workflow.md => utf-issue.md} | 2 +- .agents/workflows/{prd.md => utf-prd.md} | 0 .agents/workflows/{setup.md => utf-setup.md} | 0 .../{ciclo-tarefa.md => utf-task.md} | 0 .agents/workflows/{tutor.md => utf-tutor.md} | 6 ++-- .claude/agents/implementador.md | 2 +- .claude/commands/utf-architecture.md | 2 +- .claude/commands/utf-backlog.md | 2 +- .claude/commands/utf-design.md | 2 +- .claude/commands/utf-issue.md | 2 +- .claude/commands/utf-prd.md | 2 +- .claude/commands/utf-setup.md | 2 +- .claude/commands/utf-task.md | 2 +- .claude/commands/utf-tutor.md | 2 +- .cursor/commands/utf-architecture.md | 2 +- .cursor/commands/utf-backlog.md | 2 +- .cursor/commands/utf-design.md | 2 +- .cursor/commands/utf-issue.md | 2 +- .cursor/commands/utf-prd.md | 2 +- .cursor/commands/utf-setup.md | 2 +- .cursor/commands/utf-task.md | 2 +- .cursor/commands/utf-tutor.md | 2 +- .opencode/command/utf-architecture.md | 2 +- .opencode/command/utf-backlog.md | 2 +- .opencode/command/utf-design.md | 2 +- .opencode/command/utf-issue.md | 2 +- .opencode/command/utf-prd.md | 2 +- .opencode/command/utf-setup.md | 2 +- .opencode/command/utf-task.md | 2 +- .opencode/command/utf-tutor.md | 2 +- CONTRIBUTING.md | 9 +++--- docs/architecture.md | 2 +- docs/guia-sdd.md | 30 ++++++++++--------- 37 files changed, 53 insertions(+), 52 deletions(-) rename .agents/workflows/{architecture.md => utf-architecture.md} (100%) rename .agents/workflows/{backlog.md => utf-backlog.md} (94%) rename .agents/workflows/{design.md => utf-design.md} (100%) rename .agents/workflows/{utf-workflow.md => utf-issue.md} (92%) rename .agents/workflows/{prd.md => utf-prd.md} (100%) rename .agents/workflows/{setup.md => utf-setup.md} (100%) rename .agents/workflows/{ciclo-tarefa.md => utf-task.md} (100%) rename .agents/workflows/{tutor.md => utf-tutor.md} (89%) diff --git a/.agents/rules/utf-rules.md b/.agents/rules/utf-rules.md index 9ae8ead..4485304 100644 --- a/.agents/rules/utf-rules.md +++ b/.agents/rules/utf-rules.md @@ -8,14 +8,14 @@ Você é um agente de IA atuando como equipe de execução. O usuário (aluno) ## 1. Fases Estritas do Spec-Driven Development (SDD) - Você está proibido de pular etapas. O ciclo é: Entendimento -> Planejamento -> Execução -> Revisão. -- Sempre que o usuário pedir para trabalhar em uma Issue (ou usar `/utf-issue `), leia e execute `.agents/workflows/utf-workflow.md`. A execução de cada tarefa do plano segue `.agents/workflows/ciclo-tarefa.md` (`/utf-task `). +- Sempre que o usuário pedir para trabalhar em uma Issue (ou usar `/utf-issue `), leia e execute `.agents/workflows/utf-issue.md`. A execução de cada tarefa do plano segue `.agents/workflows/utf-task.md` (`/utf-task `). - **PROIBIDO CODIFICAR CEDO:** Nunca gere código funcional (TypeScript, HTML, CSS, etc.) sem antes conduzir um brainstorming e ter os artefatos `spec.md` e `plan.md` salvos e aprovados explicitamente pelo usuário. ## 2. Limites do Ciclo (as duas rodadas) Existem **dois contadores diferentes**, aninhados. Eles não se somam e não se substituem: - **Rodada de TDD** — vive dentro do implementador. Se o mesmo teste falhar duas vezes seguidas pelo mesmo motivo, ele PARA e relata. Não tenta uma terceira abordagem. -- **Rodada de revisão** — vive no fluxo `ciclo-tarefa`. Uma rodada é uma passada inteira: implementar → revisar → triagem do usuário. Havendo apontamento aceito na segunda, o fluxo PARA e escala. **Não existe rodada 3.** +- **Rodada de revisão** — vive no fluxo `utf-task` (o ciclo da tarefa). Uma rodada é uma passada inteira: implementar → revisar → triagem do usuário. Havendo apontamento aceito na segunda, o fluxo PARA e escala. **Não existe rodada 3.** Ao estourar qualquer um dos dois, PARE IMEDIATAMENTE e diga qual estourou: "Estourei o limite de 2 rodadas de TDD" ou "de revisão". Há algo errado com a premissa ou o contexto — quem analisa é o usuário. Não entre em loops de refatoração infinitos. diff --git a/.agents/workflows/architecture.md b/.agents/workflows/utf-architecture.md similarity index 100% rename from .agents/workflows/architecture.md rename to .agents/workflows/utf-architecture.md diff --git a/.agents/workflows/backlog.md b/.agents/workflows/utf-backlog.md similarity index 94% rename from .agents/workflows/backlog.md rename to .agents/workflows/utf-backlog.md index b1e125f..51a6124 100644 --- a/.agents/workflows/backlog.md +++ b/.agents/workflows/utf-backlog.md @@ -44,7 +44,7 @@ usuário — Issue criada aparece para a turma e para o professor. A criação do board é **manual** (a interface do Projects muda rápido e o aluno precisa conhecê-la): oriente-o a criar um Project no repositório com as -colunas `Backlog`, `Ready`, `In Progress`, `Done`, e a adicionar as Issues +colunas `Backlog`, `Ready`, `In Progress`, `Blocked` e `Done` (a `Blocked` recebe a história pausada à espera de outra — guia, seção *Quando o ciclo não é linear*), e a adicionar as Issues recém-criadas — `Must Have` primeiro no topo do `Backlog`. Se o MCP/`gh` da sessão conseguir adicionar as Issues ao Project, ofereça diff --git a/.agents/workflows/design.md b/.agents/workflows/utf-design.md similarity index 100% rename from .agents/workflows/design.md rename to .agents/workflows/utf-design.md diff --git a/.agents/workflows/utf-workflow.md b/.agents/workflows/utf-issue.md similarity index 92% rename from .agents/workflows/utf-workflow.md rename to .agents/workflows/utf-issue.md index 8099810..fb16d39 100644 --- a/.agents/workflows/utf-workflow.md +++ b/.agents/workflows/utf-issue.md @@ -34,7 +34,7 @@ status: rascunho # rascunho | aprovada **Passo 3: Execução (uma tarefa por vez)** - A branch da história existe desde o Passo 1. Antes do primeiro código, confira que o `spec.md` (aprovado) e o `plan.md` estão commitados nela — é esse `git log` que prova que a especificação veio antes do código. -- Execute **uma tarefa por vez** através do fluxo `ciclo-tarefa` (`.agents/workflows/ciclo-tarefa.md`), que despacha o subagente **implementador** com contexto limpo e, depois dele, dois revisores distintos e somente-leitura: **revisor-conformidade** (diff × critérios de aceite da `spec.md`) e **revisor-codigo** (diff × `docs/architecture.md`). +- Execute **uma tarefa por vez** através do fluxo `utf-task` (`.agents/workflows/utf-task.md`), que despacha o subagente **implementador** com contexto limpo e, depois dele, dois revisores distintos e somente-leitura: **revisor-conformidade** (diff × critérios de aceite da `spec.md`) e **revisor-codigo** (diff × `docs/architecture.md`). - **Você nunca revisa o código que você mesmo despachou.** Revisor é sempre outro agente, sem permissão de escrita. Auto-auditoria não conta como revisão: quem escreveu carrega os mesmos pontos cegos. - Ao fim de cada tarefa, pare e devolva o controle ao usuário. Ele pede a próxima. diff --git a/.agents/workflows/prd.md b/.agents/workflows/utf-prd.md similarity index 100% rename from .agents/workflows/prd.md rename to .agents/workflows/utf-prd.md diff --git a/.agents/workflows/setup.md b/.agents/workflows/utf-setup.md similarity index 100% rename from .agents/workflows/setup.md rename to .agents/workflows/utf-setup.md diff --git a/.agents/workflows/ciclo-tarefa.md b/.agents/workflows/utf-task.md similarity index 100% rename from .agents/workflows/ciclo-tarefa.md rename to .agents/workflows/utf-task.md diff --git a/.agents/workflows/tutor.md b/.agents/workflows/utf-tutor.md similarity index 89% rename from .agents/workflows/tutor.md rename to .agents/workflows/utf-tutor.md index 67c86b9..cb4e1c1 100644 --- a/.agents/workflows/tutor.md +++ b/.agents/workflows/utf-tutor.md @@ -1,5 +1,5 @@ --- -description: Despacha o agente tutor no modo certo — explicar uma tarefa já feita (número), as decisões da spec (spec) ou conduzir o simulado pré-PR (prova). O modo "antes" é despachado automaticamente pelo ciclo-tarefa. +description: Despacha o agente tutor no modo certo — explicar uma tarefa já feita (número), as decisões da spec (spec) ou conduzir o simulado pré-PR (prova). O modo "antes" é despachado automaticamente pelo fluxo utf-task. --- # Fluxo do tutor @@ -13,7 +13,7 @@ Argumento recebido: **$1** | `$1` | Modo do tutor | | --- | --- | | um número (ex.: `3`) | `depois` — explica a tarefa 3, já implementada e aprovada | -| `antes ` | `antes` — explica a tarefa antes da implementação (normalmente quem chama isso é o ciclo-tarefa) | +| `antes ` | `antes` — explica a tarefa antes da implementação (normalmente quem chama isso é o fluxo utf-task) | | `spec` | `spec` — explica as consequências técnicas da spec em rascunho | | `prova` | `prova` — simulado interativo sobre o diff inteiro da branch | @@ -24,7 +24,7 @@ Sem argumento, pergunte ao usuário qual modo ele quer. 1. Descubra a pasta `specs/-/` da branch atual. 2. Todo despacho leva os caminhos completos de `spec.md`, `plan.md` e `docs/architecture.md`, além do **modo**. 3. Conforme o modo, acrescente: - - **`depois`**: número e texto literal da tarefa, e o comando de diff. Encontre o commit da tarefa com `git log --oneline --grep "tarefa "` (convenção de commit do ciclo-tarefa) e monte `git diff ^..`. Se a tarefa tiver mais de um commit ou o commit não for encontrado, monte o intervalo à mão e confirme com o usuário antes de despachar. + - **`depois`**: número e texto literal da tarefa, e o comando de diff. Encontre o commit da tarefa com `git log --oneline --grep "tarefa "` (convenção de commit do fluxo utf-task) e monte `git diff ^..`. Se a tarefa tiver mais de um commit ou o commit não for encontrado, monte o intervalo à mão e confirme com o usuário antes de despachar. - **`antes`**: número e texto literal da tarefa, e os critérios de aceite ligados a ela, transcritos. - **`prova`**: o comando do diff completo da branch: `git diff develop..HEAD` (no Gitflow a feature branch nasce da `develop` — diff contra a `main` traria trabalho de outras histórias já integradas). diff --git a/.claude/agents/implementador.md b/.claude/agents/implementador.md index 922cd79..36dbbfc 100644 --- a/.claude/agents/implementador.md +++ b/.claude/agents/implementador.md @@ -1,6 +1,6 @@ --- name: implementador -description: Implementa UMA tarefa do plan.md seguindo TDD, com contexto limpo. Use quando o fluxo ciclo-tarefa despachar a implementação de uma tarefa. Não revisa o próprio trabalho. +description: Implementa UMA tarefa do plan.md seguindo TDD, com contexto limpo. Use quando o fluxo utf-task despachar a implementação de uma tarefa. Não revisa o próprio trabalho. tools: Read, Grep, Glob, Edit, Write, Bash --- diff --git a/.claude/commands/utf-architecture.md b/.claude/commands/utf-architecture.md index 821a298..8238f70 100644 --- a/.claude/commands/utf-architecture.md +++ b/.claude/commands/utf-architecture.md @@ -2,4 +2,4 @@ description: Gera o docs/architecture.md por entrevista guiada a partir do prd.md — stack, projeto, testes, glossário técnico, diagrama ER e os padrões cobrados pelos IDs. Garante o que o /utf-setup exige. Roda depois do /utf-prd. --- -Leia `.agents/workflows/architecture.md` e execute-o integralmente. +Leia `.agents/workflows/utf-architecture.md` e execute-o integralmente. diff --git a/.claude/commands/utf-backlog.md b/.claude/commands/utf-backlog.md index 9cd1117..df2736f 100644 --- a/.claude/commands/utf-backlog.md +++ b/.claude/commands/utf-backlog.md @@ -2,4 +2,4 @@ description: Leva as stories Ready do prd.md para o GitHub — uma Issue por story (descrição só com o link para o PRD) e orientação do Kanban no Projects. Roda depois do /utf-prd, com aceite do professor. Exige MCP do GitHub ou gh autenticado. --- -Leia `.agents/workflows/backlog.md` e execute-o integralmente. +Leia `.agents/workflows/utf-backlog.md` e execute-o integralmente. diff --git a/.claude/commands/utf-design.md b/.claude/commands/utf-design.md index 173db2e..90d4ad9 100644 --- a/.claude/commands/utf-design.md +++ b/.claude/commands/utf-design.md @@ -2,4 +2,4 @@ description: Conduz as decisões de design da Fase 0 — framework CSS, tokens (docs/design-tokens.md), protótipo navegável, Mobile-First e identidade PWA. Roda depois do /utf-prd e antes do /utf-architecture. --- -Leia `.agents/workflows/design.md` e execute-o integralmente. +Leia `.agents/workflows/utf-design.md` e execute-o integralmente. diff --git a/.claude/commands/utf-issue.md b/.claude/commands/utf-issue.md index 695a152..f7b3f3b 100644 --- a/.claude/commands/utf-issue.md +++ b/.claude/commands/utf-issue.md @@ -3,6 +3,6 @@ description: Inicia o ciclo SDD completo de uma Issue — entendimento e brainst argument-hint: --- -Leia `.agents/workflows/utf-workflow.md` e execute-o integralmente. +Leia `.agents/workflows/utf-issue.md` e execute-o integralmente. Issue a trabalhar: $1 diff --git a/.claude/commands/utf-prd.md b/.claude/commands/utf-prd.md index 5a43849..52c585f 100644 --- a/.claude/commands/utf-prd.md +++ b/.claude/commands/utf-prd.md @@ -2,4 +2,4 @@ description: Gera o docs/prd.md por entrevista guiada — tema, glossário, atores, user stories com critérios verificáveis, regras de negócio e NFRs. Uma pergunta por vez; quem decide é o aluno. Roda antes do /utf-architecture. --- -Leia `.agents/workflows/prd.md` e execute-o integralmente. +Leia `.agents/workflows/utf-prd.md` e execute-o integralmente. diff --git a/.claude/commands/utf-setup.md b/.claude/commands/utf-setup.md index 1850c48..79bd6cd 100644 --- a/.claude/commands/utf-setup.md +++ b/.claude/commands/utf-setup.md @@ -2,4 +2,4 @@ description: Gera a estrutura inicial do projeto 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. +Leia `.agents/workflows/utf-setup.md` e execute-o integralmente. diff --git a/.claude/commands/utf-task.md b/.claude/commands/utf-task.md index f56382d..8e5f9b2 100644 --- a/.claude/commands/utf-task.md +++ b/.claude/commands/utf-task.md @@ -3,6 +3,6 @@ description: Executa UMA tarefa do plan.md com implementador de contexto limpo, argument-hint: [numero-da-tarefa] --- -Leia `.agents/workflows/ciclo-tarefa.md` e execute-o integralmente. +Leia `.agents/workflows/utf-task.md` e execute-o integralmente. Tarefa a executar: $1 (se vazio, a primeira pendente do `plan.md` — o workflow explica como resolver) diff --git a/.claude/commands/utf-tutor.md b/.claude/commands/utf-tutor.md index 2ccbfac..cc80cd7 100644 --- a/.claude/commands/utf-tutor.md +++ b/.claude/commands/utf-tutor.md @@ -3,6 +3,6 @@ description: Chama o agente tutor — /utf-tutor explica a tarefa n já impl argument-hint: | spec | prova> --- -Leia `.agents/workflows/tutor.md` e execute-o integralmente. +Leia `.agents/workflows/utf-tutor.md` e execute-o integralmente. Argumento: $ARGUMENTS diff --git a/.cursor/commands/utf-architecture.md b/.cursor/commands/utf-architecture.md index c0a1f36..3b1e316 100644 --- a/.cursor/commands/utf-architecture.md +++ b/.cursor/commands/utf-architecture.md @@ -2,4 +2,4 @@ description: Gera o docs/architecture.md por entrevista guiada — stack, projeto, testes, glossário técnico e diagrama ER. Roda depois do /utf-design. --- -Leia `.agents/workflows/architecture.md` e execute-o integralmente. +Leia `.agents/workflows/utf-architecture.md` e execute-o integralmente. diff --git a/.cursor/commands/utf-backlog.md b/.cursor/commands/utf-backlog.md index 3aaed35..e0d570c 100644 --- a/.cursor/commands/utf-backlog.md +++ b/.cursor/commands/utf-backlog.md @@ -2,4 +2,4 @@ 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. +Leia `.agents/workflows/utf-backlog.md` e execute-o integralmente. diff --git a/.cursor/commands/utf-design.md b/.cursor/commands/utf-design.md index 173db2e..90d4ad9 100644 --- a/.cursor/commands/utf-design.md +++ b/.cursor/commands/utf-design.md @@ -2,4 +2,4 @@ description: Conduz as decisões de design da Fase 0 — framework CSS, tokens (docs/design-tokens.md), protótipo navegável, Mobile-First e identidade PWA. Roda depois do /utf-prd e antes do /utf-architecture. --- -Leia `.agents/workflows/design.md` e execute-o integralmente. +Leia `.agents/workflows/utf-design.md` e execute-o integralmente. diff --git a/.cursor/commands/utf-issue.md b/.cursor/commands/utf-issue.md index ebc3560..60b2704 100644 --- a/.cursor/commands/utf-issue.md +++ b/.cursor/commands/utf-issue.md @@ -2,6 +2,6 @@ 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. +Leia `.agents/workflows/utf-issue.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 index 779bd62..7702ef8 100644 --- a/.cursor/commands/utf-prd.md +++ b/.cursor/commands/utf-prd.md @@ -2,4 +2,4 @@ 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-design. --- -Leia `.agents/workflows/prd.md` e execute-o integralmente. +Leia `.agents/workflows/utf-prd.md` e execute-o integralmente. diff --git a/.cursor/commands/utf-setup.md b/.cursor/commands/utf-setup.md index 1850c48..79bd6cd 100644 --- a/.cursor/commands/utf-setup.md +++ b/.cursor/commands/utf-setup.md @@ -2,4 +2,4 @@ description: Gera a estrutura inicial do projeto 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. +Leia `.agents/workflows/utf-setup.md` e execute-o integralmente. diff --git a/.cursor/commands/utf-task.md b/.cursor/commands/utf-task.md index b16f266..2fd9a31 100644 --- a/.cursor/commands/utf-task.md +++ b/.cursor/commands/utf-task.md @@ -2,6 +2,6 @@ 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. +Leia `.agents/workflows/utf-task.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 index 045833f..2068d83 100644 --- a/.cursor/commands/utf-tutor.md +++ b/.cursor/commands/utf-tutor.md @@ -2,6 +2,6 @@ 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. +Leia `.agents/workflows/utf-tutor.md` e execute-o integralmente. Argumento: o valor que o usuário escreveu depois do comando. diff --git a/.opencode/command/utf-architecture.md b/.opencode/command/utf-architecture.md index c0a1f36..3b1e316 100644 --- a/.opencode/command/utf-architecture.md +++ b/.opencode/command/utf-architecture.md @@ -2,4 +2,4 @@ description: Gera o docs/architecture.md por entrevista guiada — stack, projeto, testes, glossário técnico e diagrama ER. Roda depois do /utf-design. --- -Leia `.agents/workflows/architecture.md` e execute-o integralmente. +Leia `.agents/workflows/utf-architecture.md` e execute-o integralmente. diff --git a/.opencode/command/utf-backlog.md b/.opencode/command/utf-backlog.md index 3aaed35..e0d570c 100644 --- a/.opencode/command/utf-backlog.md +++ b/.opencode/command/utf-backlog.md @@ -2,4 +2,4 @@ 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. +Leia `.agents/workflows/utf-backlog.md` e execute-o integralmente. diff --git a/.opencode/command/utf-design.md b/.opencode/command/utf-design.md index 173db2e..90d4ad9 100644 --- a/.opencode/command/utf-design.md +++ b/.opencode/command/utf-design.md @@ -2,4 +2,4 @@ description: Conduz as decisões de design da Fase 0 — framework CSS, tokens (docs/design-tokens.md), protótipo navegável, Mobile-First e identidade PWA. Roda depois do /utf-prd e antes do /utf-architecture. --- -Leia `.agents/workflows/design.md` e execute-o integralmente. +Leia `.agents/workflows/utf-design.md` e execute-o integralmente. diff --git a/.opencode/command/utf-issue.md b/.opencode/command/utf-issue.md index 91f6ba9..db297e4 100644 --- a/.opencode/command/utf-issue.md +++ b/.opencode/command/utf-issue.md @@ -2,6 +2,6 @@ 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. +Leia `.agents/workflows/utf-issue.md` e execute-o integralmente. Issue a trabalhar: $ARGUMENTS diff --git a/.opencode/command/utf-prd.md b/.opencode/command/utf-prd.md index 779bd62..7702ef8 100644 --- a/.opencode/command/utf-prd.md +++ b/.opencode/command/utf-prd.md @@ -2,4 +2,4 @@ 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-design. --- -Leia `.agents/workflows/prd.md` e execute-o integralmente. +Leia `.agents/workflows/utf-prd.md` e execute-o integralmente. diff --git a/.opencode/command/utf-setup.md b/.opencode/command/utf-setup.md index 1850c48..79bd6cd 100644 --- a/.opencode/command/utf-setup.md +++ b/.opencode/command/utf-setup.md @@ -2,4 +2,4 @@ description: Gera a estrutura inicial do projeto 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. +Leia `.agents/workflows/utf-setup.md` e execute-o integralmente. diff --git a/.opencode/command/utf-task.md b/.opencode/command/utf-task.md index afb8bbf..d3b211d 100644 --- a/.opencode/command/utf-task.md +++ b/.opencode/command/utf-task.md @@ -2,6 +2,6 @@ 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. +Leia `.agents/workflows/utf-task.md` e execute-o integralmente. Tarefa a executar: $ARGUMENTS diff --git a/.opencode/command/utf-tutor.md b/.opencode/command/utf-tutor.md index 2899bd5..9785651 100644 --- a/.opencode/command/utf-tutor.md +++ b/.opencode/command/utf-tutor.md @@ -2,6 +2,6 @@ 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. +Leia `.agents/workflows/utf-tutor.md` e execute-o integralmente. Argumento: $ARGUMENTS diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 25437ec..b9f510f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -59,15 +59,14 @@ O que é **norma inegociável** deste repositório são os cinco portões humano ## 🛑 O Portão de Entendimento (Regras de Pull Request) -Se o Pull Request for a primeira vez que você olha o código, o método falhou. Todo PR que altera código em `apps/` passa por uma verificação rígida antes de ser mesclado. +Se o Pull Request for a primeira vez que você olha o código, o método falhou. Todo PR passa por uma verificação automática antes de ser mesclado, e ela confere **uma regra só**: -**O PR será REPROVADO se:** +**O PR será REPROVADO se** a descrição não contiver a seção _"O que este PR faz e por quê"_ preenchida por você com pelo menos **400 caracteres** (não cole o _diff_ nem a saída da IA; explique com suas palavras). Vale para **todos** os PRs, inclusive os de manutenção. -1. Não atualizar nenhum arquivo em `docs/` ou `specs/`. -2. A descrição não contiver a seção _"O que este PR faz e por quê"_ preenchida por você com pelo menos 400 caracteres (Não cole o _diff_ nem a saída da IA; explique com suas palavras). +A documentação anda junto do código, mas quem cobra isso não é o CI: PR de história que muda comportamento atualiza `docs/` e `specs/` no mesmo commit — é o **auditor-final** (antes do PR) e o colega que revisa que conferem. **Exceção (Manutenção puramente técnica):** -Se a mudança não afeta o produto (ex: atualizar versão, refatorar código, arrumar formatação), você não precisa criar um `spec.md`. Abra o PR direto e aplique a etiqueta `manutencao`. +Se a mudança não afeta o produto (ex: atualizar versão, refatorar código, arrumar formatação), você não precisa criar um `spec.md`. Abra o PR direto e aplique a etiqueta `manutencao` — a explicação de 400 caracteres continua valendo. --- diff --git a/docs/architecture.md b/docs/architecture.md index 3b905d6..c9339e4 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,4 +1,4 @@ -# 🛠️ Architecture / Software Design Document (SSD) +# 🛠️ Architecture / SSD **Projeto:** [nome] **Versão:** 0.0.0 · esqueleto — preencha via `/utf-architecture` diff --git a/docs/guia-sdd.md b/docs/guia-sdd.md index 71353c1..f61d5a8 100644 --- a/docs/guia-sdd.md +++ b/docs/guia-sdd.md @@ -140,16 +140,18 @@ visão, as histórias de usuário (com status de rascunho até concluído) e um **Visão e objetivo.** Um ou dois parágrafos: que problema o sistema resolve, para quem. **Glossário ubíquo.** A parte mais subestimada do PRD, e a que mais economiza tempo -depois. Uma tabela ligando o termo do negócio, em português, ao nome da entidade no -código: +depois. Uma tabela com os termos do negócio, em português, como as pessoas falam — +cada um com o que significa e com o que não confundir: -| Termo do negócio | Entidade no código | Atributos principais | +| Termo | Significa | Não confundir com | | --- | --- | --- | -| Carona | `Ride` | `id, driver, origin, destination, departsAt, seats, status` | -| Solicitação | `RideRequest` | `id, ride, passenger, status` | +| Carona | A oferta de um trajeto com vagas, feita por um motorista | Solicitação (o pedido de vaga) | +| Solicitação | O pedido de um passageiro por uma vaga numa carona | Vaga confirmada | -Sem isso, a IA cria `Carona`, `Ride` e `Trip` na mesma base, em semanas -diferentes, e cada um parece razoável no contexto em que nasceu. +Tecnologia não entra aqui: a tradução de cada termo para a entidade no código +(Carona → `Ride`) vive no **glossário técnico do `architecture.md`**, e é de lá que a +IA tira os nomes. Sem essa dupla, ela cria `Carona`, `Ride` e `Trip` na mesma base, +em semanas diferentes, e cada um parece razoável no contexto em que nasceu. **Atores e permissões.** Quem usa o sistema e o que cada perfil pode fazer. @@ -259,7 +261,6 @@ confiar. | `docs/architecture.md` | **onde as coisas estão** — estrutura, entidades, contratos, estados | | `docs/design-tokens.md` | **como o produto se parece** — tokens, breakpoints, identidade PWA, protótipo | | `docs/checklist.md` | **o que a disciplina exige** — regras, IDs e entregas | -| `docs/checklist.md` | **o que a disciplina exige** — regras, IDs e entregas | | `specs/` | **o que está sendo construído agora** — uma pasta por história | Se você precisa saber o status da solicitação, existe **um** lugar: a máquina de estados no @@ -659,8 +660,8 @@ E existe um teste de uma linha para responder: > naturalmente separar por camada, porque é assim que o código se organiza. E aí o > estrago é duplo: além do backlog ficar impossível de demonstrar, **a spec fica sem > critério de aceite verificável**. "O endpoint existe" não é algo que alguém consegue -> confirmar usando o sistema; "quando o motorista aceita, a solicitação muda para CPROVADO e -> ele recebe o e-mail" é. Fatia horizontal não gera spec ruim por acaso — gera por +> confirmar usando o sistema; "quando o motorista aceita, a solicitação muda de PENDENTE +> para CONFIRMADA e a vaga sai do total disponível" é. Fatia horizontal não gera spec ruim por acaso — gera por > construção, porque não existe usuário no fim dela. "Criar o método `accept()` no `RideRequestService`" não é algo que um usuário faz. Ninguém @@ -799,7 +800,7 @@ Com quinze pastas em `specs/`, ninguém sabe o que está vivo. Mantenha um | --- | --- | --- | --- | | #12 | `12-concluir-carona` | implementada | — | | #27 | `27-solicitar-vaga` | bloqueada | espera #31 | -| #31 | `031-vaga-concorrente` | aberta | descoberta durante #27 | +| #31 | `31-vaga-concorrente` | aberta | descoberta durante #27 | --- @@ -866,10 +867,11 @@ chega como surpresa. o diff daquela tarefa e o `architecture.md`, e devolve: 1. **O que o código faz**, em português, seguindo o caminho da requisição -2. **Por que o framework faz assim** — não "criei um service", mas *por que o Nest injeta - o service em vez de você dar `new`, e o que quebraria se não injetasse* +2. **Por que o framework faz assim** — não "criei um service", mas *por que o Angular + injeta o service via `inject()` em vez de você dar `new`, e o que quebraria se não + injetasse* 3. **O nome certo dos conceitos** que apareceram, para você conseguir pesquisar sozinho - ("isso se chama injeção de dependência", "esse decorator é um Guard") + ("isso se chama injeção de dependência", "essa função passada à rota é um Guard") 4. **Três perguntas** que um professor poderia fazer sobre esse diff Se você não souber responder às três, o trabalho não acabou. Leia o código de novo, ou