From 057782ee5b689d123d1b034a06996f2c2abffdd7 Mon Sep 17 00:00:00 2001 From: Roni Fabio Banaszewski Date: Wed, 2 Sep 2026 21:52:52 -0300 Subject: [PATCH 1/2] =?UTF-8?q?feat:=20prompt=20inicial,=20port=C3=B5es=20?= =?UTF-8?q?de=20commit=20que=20obrigam=20e=20tutor=20em=20toda=20a=20Fase?= =?UTF-8?q?=200=20e=20por=20arquivo?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Retorno do primeiro uso real no Antigravity. Três problemas observados: o aluno não sabe o que dizer para começar; o setup rodou com o architecture.md não commitado, porque o texto pedia o commit mas nada verificava; e nada convida o aluno a usar o tutor fora do ciclo de tarefa. - README ganha "O primeiro prompt": um texto para colar no chat que faz o agente recitar as regras, dizer em que fase o projeto está e qual é o próximo comando. Serve no primeiro dia e em qualquer retomada, e é também o teste de que a configuração da ferramenta carregou. - /utf-flows, /utf-architecture e /utf-setup passam a PARAR se o documento da etapa anterior não estiver commitado (git status --porcelain). Antes, só o /utf-backlog exigia isso. - Tutor na Fase 0: modos novos para prd, flows e architecture (explica o documento do aluno, não um exemplo) e para setup (monorepo, as duas metades, os arquivos que ele não escreveu, por que a suíte nasce verde). Os três primeiros são oferecidos no portão de cada documento; o de setup é despachado automaticamente, porque ali o aluno recebe dezenas de arquivos que não viu nascer. - Tutor por arquivo: novo modo `passo`, que lê o diff da tarefa um arquivo por vez, esperando o aluno a cada um, com a sintaxe nova nomeada onde ela aparece. O /utf-task passa a conduzir essa leitura antes do portão do commit, e o aluno pode dispensar. O modo `antes` também passa a prever arquivo por arquivo o que vai ser escrito. Um limite honesto: um subagente que escreve não consegue parar entre arquivos para ensinar. O que dá para fazer é ensinar entre a escrita e o commit, no ritmo do aluno — que é o que o modo `passo` faz. Co-Authored-By: Claude Opus 5 (1M context) --- .agents/agents/tutor.md | 111 ++++++++++++++++++++++++++++++ .agents/workflows/architecture.md | 7 ++ .agents/workflows/ciclo-tarefa.md | 2 +- .agents/workflows/prd.md | 1 + .agents/workflows/setup.md | 16 ++++- .agents/workflows/tutor.md | 9 +++ .agents/workflows/user-flows.md | 7 ++ .claude/commands/utf-tutor.md | 4 +- .cursor/commands/utf-tutor.md | 2 +- .opencode/command/utf-tutor.md | 2 +- README.md | 30 ++++++++ docs/tutorial-sdd.md | 17 ++++- 12 files changed, 200 insertions(+), 8 deletions(-) diff --git a/.agents/agents/tutor.md b/.agents/agents/tutor.md index 1eb1fc1..c82c3d5 100644 --- a/.agents/agents/tutor.md +++ b/.agents/agents/tutor.md @@ -62,6 +62,12 @@ Devolva markdown exatamente nesta forma: +## Arquivo por arquivo, o que vai aparecer +| Arquivo | O que vai ser escrito nele | O que você precisa reconhecer ali | + + ## Roteiro para conferir o diff na IDE <3 a 6 itens, na ordem de leitura: "abra tal arquivo e procure X; se estiver Y, entenda Z"> @@ -121,6 +127,111 @@ misture "o que faz", "por que assim" e "o que quebraria se...") O gabarito é para quem conduz o simulado, **não** para o aluno ver antes de responder. Quem te despachou vai fazer as perguntas uma a uma. +## Modo `passo` — a leitura do diff, um arquivo por vez + +O aluno acabou de receber o diff de uma tarefa e ele passou rápido demais. Aqui você não resume: **destrincha, arquivo por arquivo**, na ordem em que faz sentido ler — o teste primeiro, depois aquilo que ele obriga a existir. + +Este é o momento em que se aprende **sintaxe**. O aluno está vendo um `@Injectable`, um `async`, um `expect(...).rejects` pela primeira vez, e a chance de perguntar é agora, com cinco linhas na frente dele, não no PR com quarenta arquivos. + +O despacho traz o número da tarefa e o comando de diff. Rode-o e leia tudo. Devolva **um bloco por arquivo**, e nada além — quem conduz a conversa é quem te despachou, e vai entregar um bloco de cada vez: + +``` +# Tutor — Tarefa , arquivo por arquivo + +## Arquivo 1 de — `caminho/do/arquivo` + +**Por que este arquivo entra nesta tarefa:** + +**O que foi escrito:** + +**A sintaxe que aparece aqui pela primeira vez** +| No código | Como se chama | O que faz | +(só o que ainda não apareceu nos arquivos anteriores desta tarefa) + +**Se este arquivo não existisse:** + +**Pergunta:** + +## Arquivo 2 de — `...` +``` + +**Um arquivo por bloco, sem exceção** — mesmo o de três linhas. Arquivo pequeno (um módulo, um export, uma linha de configuração) costuma ser o que passa despercebido e o que o professor pergunta. + +--- + +## Modo `documento` — explicar um artefato da Fase 0 + +O despacho diz **qual** documento (`prd`, `flows` ou `architecture`) e o caminho dele. Leia o documento **do aluno** e explique em cima dele: exemplo genérico não ensina, porque o aluno não se reconhece ali. + +Ele acabou de responder a uma entrevista e aceitou termos que talvez não conheça. Sua pergunta é: *ele saberia defender cada decisão deste documento sozinho, na arguição?* + +``` +# Tutor — + +## O que este documento decide + + +## Os conceitos que aparecem nele +### + +(3 a 6 blocos: os conceitos que ele provavelmente não domina, não todos) + +## O que cada decisão obriga depois + + +## O que ainda está em aberto + + +## Três perguntas de professor +1. ... +(sem as respostas) + +## Para pesquisar +<2 a 4 termos exatos> +``` + +--- + +## Modo `setup` — explicar o scaffold recém-gerado + +Despachado automaticamente pelo `/utf-setup`, antes do primeiro Pull Request. É o **único momento do semestre em que o aluno recebe dezenas de arquivos que ele não escreveu e não viu nascer**. Trate cada arquivo e cada palavra como novidade. + +``` +# Tutor — o scaffold do projeto + +## O que é um monorepo, e por que este projeto é um + + +## As duas metades +### O backend `apps/api` — + +### O frontend `apps/web` — + + + +## Os arquivos que você não escreveu +| Arquivo ou pasta | Para que serve | Quando você vai mexer nele | +(só os que importam: o `package.json` da raiz e o de cada app, a configuração do +runner de teste, `.gitignore`, `.gitattributes`, `.github/`) + +## Por que a suíte nasce verde e vazia + + +## Três perguntas de professor +1. ... +(sem as respostas) + +## Para pesquisar +<2 a 4 termos exatos> +``` + --- > ⚠️ Você existe para o aluno chegar à defesa **sem precisar de você**. Nunca entregue texto pronto para ele colar no PR ou decorar — entregue entendimento. diff --git a/.agents/workflows/architecture.md b/.agents/workflows/architecture.md index a0bfe01..44f3ea4 100644 --- a/.agents/workflows/architecture.md +++ b/.agents/workflows/architecture.md @@ -15,6 +15,12 @@ Você é o entrevistador técnico. O aluno é o Arquiteto: **ele decide; você a ## Passo 0 — Pré-condições +0. **O documento anterior está commitado.** Rode `git status --porcelain docs/user-flows.md docs/design-tokens.md`: + se a saída **não** estiver vazia, ou se o arquivo não estiver versionado, **PARE** e + peça o commit ao aluno. Não é burocracia: cada documento da Fase 0 é decisão dele, e + o commit é o que põe o nome dele nessa decisão. Seguir sem commitar empilha quatro + documentos num commit só, no fim, e a autoria some. + 0. `docs/user-flows.md` tem pelo menos uma jornada desenhada, com o parágrafo de decisão sobre o nó vermelho. Se não tiver, **PARE** e mande rodar `/utf-flows`: é lá que aparecem os estados que faltam ("o pedido fica AGUARDANDO para sempre?"), e estado esquecido aqui vira retrabalho na primeira spec. 1. `docs/prd.md` existe, com glossário, atores e stories. Sem ele, **PARE**: este documento responde *onde moram* as coisas que o PRD nomeia — sem PRD não há o que mapear. Mande rodar `/utf-prd` antes. 2. Leia `docs/checklist.md` **inteiro** — a seção *Regras da disciplina* diz o que é stack fixa e o que é escolha do aluno, e vários IDs são padrões estruturais que este documento precisa declarar. @@ -43,6 +49,7 @@ Antes de fechar, confira que o documento declara **explicitamente** as quatro co 1. Percorra o `docs/checklist.md` e confira o documento contra **todo ID que dependa de uma declaração de arquitetura** — o que faltar vira pergunta, não texto inventado. 2. Grave `docs/architecture.md`. **PARE.** O aluno lê fora do chat; o commit é dele. Próximo passo: `/utf-setup`. + Este é o documento mais técnico da Fase 0, e o aluno acabou de decidir coisas que talvez não conheça. Ofereça, sem enfeite: *"Antes de commitar, rode `/utf-tutor architecture` — ele explica monorepo, camadas, ORM e o diagrama ER em cima das suas escolhas, não em exemplo genérico."* ## Proibições diff --git a/.agents/workflows/ciclo-tarefa.md b/.agents/workflows/ciclo-tarefa.md index 7cfab9a..7b16e94 100644 --- a/.agents/workflows/ciclo-tarefa.md +++ b/.agents/workflows/ciclo-tarefa.md @@ -94,7 +94,7 @@ Havendo apontamentos, **quem decide o destino de cada um é o usuário, não voc | Situação | O que fazer | | --- | --- | -| Ambos **APROVADO**, ou **todos os apontamentos recusados** na triagem | **PAUSA OBRIGATÓRIA — nada de commit ainda.** Apresente ao usuário: o resumo do diff (arquivos e o que mudou em cada um), o veredito dos dois revisores e o convite para **conferir o diff na IDE** com o roteiro que o tutor deu no Passo 1. Revisor aprovar não substitui o olho do dono: **espere o aceite explícito** ("pode commitar"). Só então marque a tarefa como feita no `plan.md` (`- [x]`) e faça o commit (incluindo pareceres e decisões) com a mensagem começando por `tarefa $1: ` — é essa convenção que permite ao `/utf-tutor $1` achar o diff. **Depois do commit**, ofereça `/utf-tutor $1` para a aula sobre o diff — antes dele o tutor não tem commit para localizar. Feche o relato com a **listinha das tarefas restantes** do `plan.md` (número e título, na ordem), dizendo qual é a próxima — ou, se não restar nenhuma, que o plano acabou e que `/utf-issue ` retoma no fechamento (auditor final e PR). Espere ele pedir a próxima (`/utf-task` sem número já a pega). | +| Ambos **APROVADO**, ou **todos os apontamentos recusados** na triagem | **PAUSA OBRIGATÓRIA — nada de commit ainda.** Apresente o veredito dos dois revisores e, **antes de pedir o aceite**, despache o tutor em modo `passo` e conduza a leitura do diff **um arquivo por vez**, esperando o usuário a cada arquivo. É aqui que ele aprende a sintaxe, com a mudança fresca e pequena — o implementador escreve rápido demais para alguém acompanhar, e sem esta parada o aluno chega ao PR sem ter lido nada. Ele pode dispensar (*"pode pular a leitura"*), e aí você segue direto; **não pule por conta própria**. Convide-o a acompanhar pelo diff na IDE, com o roteiro que o tutor deu no Passo 1. Revisor aprovar não substitui o olho do dono: **espere o aceite explícito** ("pode commitar"). Só então marque a tarefa como feita no `plan.md` (`- [x]`) e faça o commit (incluindo pareceres e decisões) com a mensagem começando por `tarefa $1: ` — é essa convenção que permite ao `/utf-tutor $1` achar o diff. **Depois do commit**, ofereça `/utf-tutor $1` para a aula sobre o diff — antes dele o tutor não tem commit para localizar. Feche o relato com a **listinha das tarefas restantes** do `plan.md` (número e título, na ordem), dizendo qual é a próxima — ou, se não restar nenhuma, que o plano acabou e que `/utf-issue ` retoma no fechamento (auditor final e PR). Espere ele pedir a próxima (`/utf-task` sem número já a pega). | | Algum apontamento **aceito**, rodada de revisão 1 | Volte ao Passo 2 com um implementador novo (sem repetir o tutor), transcrevendo **apenas os apontamentos aceitos**. | | Algum apontamento **aceito**, rodada de revisão 2 | **PARE. Não existe rodada 3.** | diff --git a/.agents/workflows/prd.md b/.agents/workflows/prd.md index 1db3f32..b31a1c7 100644 --- a/.agents/workflows/prd.md +++ b/.agents/workflows/prd.md @@ -48,6 +48,7 @@ Percorra o `docs/checklist.md` e confira o rascunho contra **todo ID cuja sement 1. Grave `docs/prd.md` completo. 2. **PARE.** O aluno lê o documento inteiro, fora do chat. Ajuste agora custa uma conversa; depois, custa uma spec. + Ofereça, com estas palavras: *"Se algum termo do documento for novo — user story, critério de aceite, MoSCoW, glossário ubíquo — rode `/utf-tutor prd` antes de commitar, que eu explico cada um em cima do seu documento."* 3. O commit do `prd.md` é **dele**. Próximos passos, nesta ordem: com o **aceite do professor** e stories `Ready`, `/utf-backlog` leva as stories para o GitHub (Issues + Kanban); depois `/utf-flows`, que desenha as jornadas e acha os pontos de desistência; e só então `/utf-architecture`. ## Proibições diff --git a/.agents/workflows/setup.md b/.agents/workflows/setup.md index d7c9fa1..b558655 100644 --- a/.agents/workflows/setup.md +++ b/.agents/workflows/setup.md @@ -14,6 +14,12 @@ que foi decidida. O que não estiver escrito lá, você pergunta; não escolhe. ## Passo 0 — Pré-condições (PARE se qualquer uma falhar) +0. **Os documentos da Fase 0 estão commitados.** Rode + `git status --porcelain docs/`: se a saída **não** estiver vazia, **PARE** e peça + o commit. O scaffold vai nascer a partir do `architecture.md`; se ele ainda não + está no histórico, o repositório não tem como provar qual decisão gerou qual + arquivo — e é essa rastreabilidade que a avaliação cobra. + 1. `docs/prd.md` e `docs/architecture.md` existem e declaram: o framework do backend, o framework do frontend, a estrutura de pastas do monorepo e como rodar os testes. Se algum desses quatro estiver ausente ou ambíguo, **PARE** e diga o que falta — @@ -154,12 +160,18 @@ motivo, **PARE** e relate. Não tente uma terceira abordagem. 1. Commits pequenos e nomeados por passo (apps, raiz, ferramentas do método) — **cada um proposto ao usuário antes** ("commit do passo X: ?"), nenhum sem o OK dele. -2. Relate ao usuário: o que foi gerado, a saída dos testes, e as decisões que o +2. **Despache o tutor em modo `setup`, antes do PR.** Este é o único momento do + semestre em que o aluno recebe um monte de arquivos que ele não escreveu e não + viu nascer — se ninguém explicar, ele abre o primeiro PR sem saber o que tem + dentro do próprio repositório. Não pergunte se ele quer: despache, apresente a + explicação na íntegra e só então siga. O despacho leva `docs/architecture.md`, a + lista de arquivos gerados e a saída dos testes. +3. Relate ao usuário: o que foi gerado, a saída dos testes, e as decisões que o `architecture.md` não cobria (Passo 2) para ele ratificar no documento. **Ratificação aprovada pelo usuário = atualize o `architecture.md` na mesma branch**, antes do PR — documento e scaffold entram juntos, contando a mesma história. -3. Instrua o usuário a abrir o PR com a etiqueta **`manutencao`** — setup é Task, +4. Instrua o usuário a abrir o PR com a etiqueta **`manutencao`** — setup é Task, não história. O corpo já vem preenchido pelo `.github/pull_request_template.md`, que está na `main` desde o template. Explique o detalhe que ninguém adivinha: diff --git a/.agents/workflows/tutor.md b/.agents/workflows/tutor.md index 76c89b1..450e262 100644 --- a/.agents/workflows/tutor.md +++ b/.agents/workflows/tutor.md @@ -16,6 +16,11 @@ Argumento recebido: **$1** | `antes ` | `antes` — explica a tarefa antes da implementação (normalmente quem chama isso é o ciclo-tarefa) | | `spec` | `spec` — explica as consequências técnicas da spec em rascunho | | `prova` | `prova` — simulado interativo sobre o diff inteiro da branch | +| `passo ` | `passo` — lê o diff da tarefa `` **um arquivo por vez**, no ritmo do aluno | +| `prd` | `documento` — explica o `docs/prd.md` que o aluno acabou de escrever | +| `flows` | `documento` — explica `docs/user-flows.md` e `docs/design-tokens.md` | +| `architecture` | `documento` — explica o `docs/architecture.md` | +| `setup` | `setup` — explica o scaffold gerado: monorepo, front, back e configuração | Sem argumento, pergunte ao usuário qual modo ele quer. @@ -27,10 +32,14 @@ Sem argumento, pergunte ao usuário qual modo ele quer. - **`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; o `^` e o `:` impedem que `tarefa 1` case com `tarefa 10`) e monte `git diff ^..`. Se a tarefa **ainda não foi commitada** (o aluno quer a aula antes de autorizar o commit), o diff é o working tree: `git add -A && git diff HEAD`. 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 main..HEAD`. + - **`passo`**: número da tarefa e o comando de diff — o mesmo do modo `depois` se a tarefa já foi commitada; `git add -A && git diff HEAD` se ela ainda está no working tree, esperando o portão do commit. + - **`documento`**: qual documento (`prd`, `flows` ou `architecture`) e o caminho dele. O tutor lê o documento do aluno, não um exemplo. + - **`setup`**: a lista de arquivos e pastas gerados (`git diff --stat main..HEAD` ou `git show --stat`), os comandos de teste do `architecture.md` e a saída da suíte. ## Entregar - **Modos `antes`, `depois` e `spec`:** apresente a resposta do tutor ao usuário **na íntegra, sem resumir** — resumo seu é exatamente a contaminação que o tutor existe para evitar. Depois, coloque-se à disposição para dúvidas: repasse cada dúvida ao tutor em novo despacho se ela exigir olhar o código de novo. +- **Modo `passo`:** o tutor te devolve um bloco por arquivo. **Entregue um bloco por vez** e espere o usuário dizer que entendeu ou perguntar. Não emende dois arquivos na mesma mensagem, mesmo que o segundo seja curto — o ponto do modo é o ritmo. Dúvida sobre um arquivo volta ao tutor em novo despacho, se exigir olhar o código de novo. No fim, pergunte se ele quer rever algum. - **Modo `prova`:** o tutor te devolve as questões **com gabarito**. O gabarito é seu, não do aluno: 1. Faça **uma pergunta por vez** e espere a resposta do usuário. 2. Compare com o gabarito e dê o retorno de forma didática: o que acertou, o que faltou, onde está a evidência (`arquivo:linha`). diff --git a/.agents/workflows/user-flows.md b/.agents/workflows/user-flows.md index 75ca635..73030c7 100644 --- a/.agents/workflows/user-flows.md +++ b/.agents/workflows/user-flows.md @@ -27,6 +27,12 @@ fechado. ## Passo 0 — Pré-condições +0. **O documento anterior está commitado.** Rode `git status --porcelain docs/prd.md`: + se a saída **não** estiver vazia, ou se o arquivo não estiver versionado, **PARE** e + peça o commit ao aluno. Não é burocracia: cada documento da Fase 0 é decisão dele, e + o commit é o que põe o nome dele nessa decisão. Seguir sem commitar empilha quatro + documentos num commit só, no fim, e a autoria some. + 1. `docs/prd.md` preenchido, com stories e critérios de aceite. Sem ele, **PARE** e mande rodar `/utf-prd` — jornada sem história é desenho decorativo. 2. Se `docs/user-flows.md` já tem jornada real (não é esqueleto), **PARE** e pergunte: @@ -115,6 +121,7 @@ registre como pendência — não invente cor nem link. 1. Grave `docs/user-flows.md` e `docs/design-tokens.md`. 2. **PARE.** O aluno lê fora do chat. O commit é dele. + Ofereça: *"Rode `/utf-flows` de novo se quiser outra jornada, ou `/utf-tutor flows` se quiser entender por que o nó vermelho muda o sistema."* 3. Próximo passo: `/utf-architecture` — que vai ler as jornadas para encontrar os estados e os pontos de decisão que o `architecture.md` precisa declarar. diff --git a/.claude/commands/utf-tutor.md b/.claude/commands/utf-tutor.md index 2ccbfac..47d5871 100644 --- a/.claude/commands/utf-tutor.md +++ b/.claude/commands/utf-tutor.md @@ -1,6 +1,6 @@ --- -description: Chama o agente tutor — /utf-tutor explica a tarefa n já implementada; /utf-tutor antes explica antes de implementar; /utf-tutor spec explica a spec em rascunho; /utf-tutor prova conduz o simulado pré-PR. -argument-hint: | spec | prova> +description: Chama o agente tutor — explica a tarefa já implementada; antes explica antes de implementar; spec explica a spec em rascunho; passo lê o diff arquivo por arquivo; prova conduz o simulado pré-PR; prd, flows, architecture e setup explicam os artefatos da Fase 0. +argument-hint: | passo | spec | prova | prd | flows | architecture | setup> --- Leia `.agents/workflows/tutor.md` e execute-o integralmente. diff --git a/.cursor/commands/utf-tutor.md b/.cursor/commands/utf-tutor.md index 045833f..0defed7 100644 --- a/.cursor/commands/utf-tutor.md +++ b/.cursor/commands/utf-tutor.md @@ -1,5 +1,5 @@ --- -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. +description: Chama o agente tutor: explica a tarefa já implementada; antes explica antes de implementar; spec explica a spec em rascunho; passo lê o diff arquivo por arquivo; prova conduz o simulado pré-PR; prd, flows, architecture e setup explicam os artefatos da Fase 0. --- Leia `.agents/workflows/tutor.md` e execute-o integralmente. diff --git a/.opencode/command/utf-tutor.md b/.opencode/command/utf-tutor.md index 2899bd5..9955087 100644 --- a/.opencode/command/utf-tutor.md +++ b/.opencode/command/utf-tutor.md @@ -1,5 +1,5 @@ --- -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. +description: Chama o agente tutor: explica a tarefa já implementada; antes explica antes de implementar; spec explica a spec em rascunho; passo lê o diff arquivo por arquivo; prova conduz o simulado pré-PR; prd, flows, architecture e setup explicam os artefatos da Fase 0. --- Leia `.agents/workflows/tutor.md` e execute-o integralmente. diff --git a/README.md b/README.md index 7855478..2f68c6a 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,36 @@ Bug e tarefa técnica não entram nessa tabela: eles nascem como Issue direto no etiqueta `manutencao`. O tutorial tem o passo a passo. Os modelos comentados de `spec.md` e `plan.md` ficam em `docs/modelo-spec.md` e `docs/modelo-plan.md`. +### O primeiro prompt + +Abra o chat da sua IDE e **cole o texto abaixo**. Ele confirma que o método carregou, +diz em que ponto o projeto está e qual é o próximo passo — serve no primeiro dia e em +qualquer volta depois de dias sem mexer. + +```text +Sou aluno da disciplina e este repositório usa o método UTF-SDD. + +Antes de qualquer outra coisa: + +1. Leia `.agents/rules/utf-rules.md` — é a constituição deste repositório e vale + para tudo o que fizermos daqui em diante. +2. Leia `docs/checklist.md` — é a ficha da disciplina: regras, indicadores e entregas. +3. Olhe `docs/`, `specs/` e o `git log`, e me responda: + - as regras inegociáveis, uma linha cada; + - em que fase o projeto está agora, e como você chegou a essa conclusão; + - qual é o próximo comando que eu devo rodar, o que ele vai me perguntar e o que + eu vou ter que decidir nele; + - o que precisa estar commitado antes de eu rodá-lo. + +Explique como se eu nunca tivesse visto este método. Não escreva código nem crie +nenhum arquivo nesta resposta. +``` + +Se o agente não souber recitar as regras, **elas não carregaram** — confira, na tabela +abaixo, se as pastas da sua ferramenta são mesmo as que ele lê. E, a qualquer momento, +`/utf-tutor` explica o que estiver na sua frente: `prd`, `flows`, `architecture` e +`setup` na Fase 0; `spec`, `antes `, `` e `prova` durante as histórias. + ### Um método, quatro ferramentas O conteúdo de verdade — constituição, fluxos e subagentes — vive uma vez só, em diff --git a/docs/tutorial-sdd.md b/docs/tutorial-sdd.md index 729d892..24f8e95 100644 --- a/docs/tutorial-sdd.md +++ b/docs/tutorial-sdd.md @@ -27,6 +27,17 @@ Cinco comandos, nesta ordem, cada um fechando num portão seu: Pré-requisito dos passos 2 e 5 (e, depois, de cada `/utf-issue`): `gh` autenticado ou MCP do GitHub. O `/utf-backlog` pode rodar de novo mais tarde, a cada leva de stories promovidas a `Ready`. +> 🎓 **O tutor também vale na Fase 0.** Cada documento é decisão sua, e decisão que +> você não sabe explicar não sobrevive à arguição. Antes de commitar, rode +> `/utf-tutor prd`, `/utf-tutor flows` ou `/utf-tutor architecture` — ele explica os +> conceitos em cima do **seu** documento, não em exemplo genérico. Depois do +> `/utf-setup` você não precisa pedir: o fluxo chama o tutor sozinho, porque ali é o +> único momento em que você recebe dezenas de arquivos que não escreveu. + +> ⛔ **Cada passo só começa com o anterior commitado.** Os comandos conferem isso e +> param se faltar. Não é burocracia: o commit é o que põe o seu nome na decisão. Sem +> ele, os quatro documentos caem num commit só no fim e a autoria some. + --- ## Antes de começar (uma vez por história) @@ -81,7 +92,8 @@ Dentro do comando acontece o ciclo completo, com as suas paradas: | Revisão em paralelo | revisor-conformidade + revisor-codigo | nada — quem despacha é o fluxo | | Pareceres gravados em `reviews/` | orquestrador | nada | | **Triagem** (se houve apontamentos) | orquestrador apresenta a lista | **🚪 aceita ou recusa cada um** — recusa exige justificativa, registrada em `reviews/tarefa-NN-decisoes-rN.md` | -| Commit `tarefa 1: ...` | orquestrador apresenta o diff e os pareceres | **🚪 confere o diff na IDE, com o roteiro do tutor, e autoriza** ("pode commitar"); depois do commit, `/utf-tutor 1` dá a aula sobre ele | +| **Leitura do diff, arquivo por arquivo** | tutor (modo `passo`), conduzido pelo orquestrador | acompanha **um arquivo por vez** e pergunta — é aqui que a sintaxe entra; diga "pode pular a leitura" se não quiser | +| Commit `tarefa 1: ...` | orquestrador apresenta o diff e os pareceres | **🚪 confere o diff na IDE e autoriza** ("pode commitar"); depois do commit, `/utf-tutor 1` amarra a tarefa inteira | Repita para cada tarefa: `/utf-task 2`, `/utf-task 3`… — ou apenas `/utf-task`, que pega a próxima pendente do `plan.md` e avisa quando não @@ -120,7 +132,10 @@ palavras, lista os apontamentos aceitos e recusados (saem dos arquivos | `/utf-setup` | Fase 0, etapa 5 — gera o scaffold do monorepo | | `/utf-issue ` | Para iniciar o ciclo da Issue (spec → plano) e, no fim, para fechá-la (auditor → PR); rodado de novo, retoma de onde parou | | `/utf-task [n]` | Uma vez **por tarefa** do plano — sem número, executa a próxima pendente | +| `/utf-tutor prd` · `flows` · `architecture` | Na Fase 0, antes de commitar cada documento | +| `/utf-tutor setup` | Depois do scaffold — monorepo, front, back e os arquivos que você não escreveu (o `/utf-setup` já chama sozinho) | | `/utf-tutor spec` | Antes de aprovar a spec | +| `/utf-tutor passo ` | A leitura do diff arquivo por arquivo, no seu ritmo (o `/utf-task` já chama sozinho, antes do commit) | | `/utf-tutor ` | Depois de uma tarefa, para a aula sobre aquele diff | | `/utf-tutor antes ` | Para reouvir a explicação pré-implementação de uma tarefa | | `/utf-tutor prova` | Antes de escrever o PR — o ensaio da defesa | From b8b27be6854255cef382d2bbf05fbee9da1ec275 Mon Sep 17 00:00:00 2001 From: Roni Fabio Banaszewski Date: Wed, 2 Sep 2026 21:59:02 -0300 Subject: [PATCH 2/2] refactor: workflows renomeados para utf-*, o mesmo comando nas quatro ferramentas MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit No Antigravity o comando é o nome do arquivo em .agents/workflows/, o que foi confirmado em teste real: ele listava /prd, /user-flows, /ciclo-tarefa e /utf-workflow, enquanto todos os guias dizem /utf-prd, /utf-flows e /utf-task. Os oito workflows passam a se chamar utf-prd, utf-flows, utf-backlog, utf-architecture, utf-setup, utf-issue, utf-task e utf-tutor, e as cascas de Claude Code, Cursor e OpenCode apontam para os novos caminhos. As notas de "no Antigravity leia o equivalente" saem do README e do tutorial, porque deixou de haver equivalente a traduzir. Os documentos em docs/ não são tocados: prd.md e architecture.md seguem com os nomes padrão de mercado. Co-Authored-By: Claude Opus 5 (1M context) --- .agents/rules/utf-rules.md | 4 ++-- .agents/workflows/{architecture.md => utf-architecture.md} | 0 .agents/workflows/{backlog.md => utf-backlog.md} | 0 .agents/workflows/{user-flows.md => utf-flows.md} | 0 .agents/workflows/{utf-workflow.md => utf-issue.md} | 4 ++-- .agents/workflows/{prd.md => utf-prd.md} | 0 .agents/workflows/{setup.md => utf-setup.md} | 0 .agents/workflows/{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-flows.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-flows.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-flows.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 +- README.md | 7 +------ docs/tutorial-sdd.md | 5 ----- 36 files changed, 33 insertions(+), 43 deletions(-) rename .agents/workflows/{architecture.md => utf-architecture.md} (100%) rename .agents/workflows/{backlog.md => utf-backlog.md} (100%) rename .agents/workflows/{user-flows.md => utf-flows.md} (100%) rename .agents/workflows/{utf-workflow.md => utf-issue.md} (93%) 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} (88%) diff --git a/.agents/rules/utf-rules.md b/.agents/rules/utf-rules.md index 4f22714..f040c75 100644 --- a/.agents/rules/utf-rules.md +++ b/.agents/rules/utf-rules.md @@ -8,7 +8,7 @@ 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. - Exceção única: o scaffold do `/utf-setup`, que não contém regra de negócio nem entidade do PRD — é Task de manutenção, sem spec. @@ -16,7 +16,7 @@ Você é um agente de IA atuando como equipe de execução. O usuário (aluno) 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`. 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 100% rename from .agents/workflows/backlog.md rename to .agents/workflows/utf-backlog.md diff --git a/.agents/workflows/user-flows.md b/.agents/workflows/utf-flows.md similarity index 100% rename from .agents/workflows/user-flows.md rename to .agents/workflows/utf-flows.md diff --git a/.agents/workflows/utf-workflow.md b/.agents/workflows/utf-issue.md similarity index 93% rename from .agents/workflows/utf-workflow.md rename to .agents/workflows/utf-issue.md index 715708d..cb88dcd 100644 --- a/.agents/workflows/utf-workflow.md +++ b/.agents/workflows/utf-issue.md @@ -48,13 +48,13 @@ status: rascunho # rascunho | aprovada - Aprovado, proponha o commit do plano (`plan: (#)`) e faça-o com o OK do usuário. Spec e plano são os primeiros commits da branch, **antes de qualquer código** — é o `git log` que prova que a especificação veio primeiro. **Passo 3: Execução (uma tarefa por vez)** -- 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. **Passo 4: Auditoria final e Pull Request** - Terminadas todas as tarefas, atualize **primeiro** a documentação: o status da história no `docs/prd.md` (→ `Live`), os diagramas do `docs/architecture.md` que mudaram, e a linha da spec no `specs/README.md` (→ `implementada`). Proponha o commit e faça-o **só com o "pode commitar" do usuário** — o portão do commit vale aqui como em cada tarefa. -- Despache então o subagente **auditor-final**, que compara o diff **inteiro** da branch contra o `spec.md` original — nunca contra o `plan.md` — e confere a documentação que acabou de ser atualizada. Se o veredito for NÃO PRONTO, cada pendência vira tarefa nova no `plan.md` (com o OK do usuário) e passa pelo `ciclo-tarefa`; depois o auditor roda de novo. +- Despache então o subagente **auditor-final**, que compara o diff **inteiro** da branch contra o `spec.md` original — nunca contra o `plan.md` — e confere a documentação que acabou de ser atualizada. Se o veredito for NÃO PRONTO, cada pendência vira tarefa nova no `plan.md` (com o OK do usuário) e passa pelo `/utf-task`; depois o auditor roda de novo. - Com PRONTO PARA PR, sugira `/utf-tutor prova` — o simulado interativo sobre o diff inteiro, que é o ensaio da defesa presencial. - Lembre o usuário de abrir o Pull Request com `Closes #`. - A seção **"O que este PR faz e por quê"** é escrita **pelo usuário, com as palavras dele**. Ofereça os fatos do diff; não ofereça o texto pronto. 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 88% rename from .agents/workflows/tutor.md rename to .agents/workflows/utf-tutor.md index 450e262..7e63fa4 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 /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 `/utf-task`) | | `spec` | `spec` — explica as consequências técnicas da spec em rascunho | | `prova` | `prova` — simulado interativo sobre o diff inteiro da branch | | `passo ` | `passo` — lê o diff da tarefa `` **um arquivo por vez**, no ritmo do aluno | @@ -29,7 +29,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; o `^` e o `:` impedem que `tarefa 1` case com `tarefa 10`) e monte `git diff ^..`. Se a tarefa **ainda não foi commitada** (o aluno quer a aula antes de autorizar o commit), o diff é o working tree: `git add -A && git diff HEAD`. 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 `/utf-task`; o `^` e o `:` impedem que `tarefa 1` case com `tarefa 10`) e monte `git diff ^..`. Se a tarefa **ainda não foi commitada** (o aluno quer a aula antes de autorizar o commit), o diff é o working tree: `git add -A && git diff HEAD`. 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 main..HEAD`. - **`passo`**: número da tarefa e o comando de diff — o mesmo do modo `depois` se a tarefa já foi commitada; `git add -A && git diff HEAD` se ela ainda está no working tree, esperando o portão do commit. diff --git a/.claude/agents/implementador.md b/.claude/agents/implementador.md index 922cd79..07bd5e0 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 8e0f4ee..f543fd3 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, monorepo, 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 e do /utf-flows. --- -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-flows.md b/.claude/commands/utf-flows.md index e52f095..5ece5bc 100644 --- a/.claude/commands/utf-flows.md +++ b/.claude/commands/utf-flows.md @@ -2,4 +2,4 @@ description: Desenha as jornadas de usuário (docs/user-flows.md) e os tokens de design (docs/design-tokens.md) a partir do prd.md. 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. +Leia `.agents/workflows/utf-flows.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 2600a6c..2600b0f 100644 --- a/.claude/commands/utf-setup.md +++ b/.claude/commands/utf-setup.md @@ -2,4 +2,4 @@ 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. +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 47d5871..af5465e 100644 --- a/.claude/commands/utf-tutor.md +++ b/.claude/commands/utf-tutor.md @@ -3,6 +3,6 @@ description: Chama o agente tutor — explica a tarefa já implementada; ant argument-hint: | passo | spec | prova | prd | flows | architecture | setup> --- -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 34de834..fbcdeec 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, monorepo, testes, glossário técnico e diagrama ER. Roda depois do /utf-flows. --- -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-flows.md b/.cursor/commands/utf-flows.md index d6535ab..5c7591a 100644 --- a/.cursor/commands/utf-flows.md +++ b/.cursor/commands/utf-flows.md @@ -2,4 +2,4 @@ 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. +Leia `.agents/workflows/utf-flows.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 f1bd539..394b09b 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-flows. --- -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 2600a6c..2600b0f 100644 --- a/.cursor/commands/utf-setup.md +++ b/.cursor/commands/utf-setup.md @@ -2,4 +2,4 @@ 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. +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 0defed7..dfce49b 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; passo lê o diff arquivo por arquivo; prova conduz o simulado pré-PR; prd, flows, architecture e setup explicam os artefatos da Fase 0. --- -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 34de834..fbcdeec 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, monorepo, testes, glossário técnico e diagrama ER. Roda depois do /utf-flows. --- -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-flows.md b/.opencode/command/utf-flows.md index d6535ab..5c7591a 100644 --- a/.opencode/command/utf-flows.md +++ b/.opencode/command/utf-flows.md @@ -2,4 +2,4 @@ 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. +Leia `.agents/workflows/utf-flows.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 f1bd539..394b09b 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-flows. --- -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 2600a6c..2600b0f 100644 --- a/.opencode/command/utf-setup.md +++ b/.opencode/command/utf-setup.md @@ -2,4 +2,4 @@ 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. +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 9955087..1897da8 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; passo lê o diff arquivo por arquivo; prova conduz o simulado pré-PR; prd, flows, architecture e setup explicam os artefatos da Fase 0. --- -Leia `.agents/workflows/tutor.md` e execute-o integralmente. +Leia `.agents/workflows/utf-tutor.md` e execute-o integralmente. Argumento: $ARGUMENTS diff --git a/README.md b/README.md index 2f68c6a..ebaa026 100644 --- a/README.md +++ b/README.md @@ -73,7 +73,7 @@ reescreve nada: o miolo é o mesmo. | --- | --- | --- | --- | | Claude Code | `CLAUDE.md` | `.claude/commands/` | `.claude/agents/` | | Cursor | `.cursor/rules/` | `.cursor/commands/` | `.cursor/agents/` | -| Antigravity | `.agents/rules/` | `.agents/workflows/` | `.agents/agents/` | +| Antigravity | `.agents/rules/` | `.agents/workflows/` (o nome do arquivo **é** o comando) | `.agents/agents/` | | OpenCode | `AGENTS.md` | `.opencode/command/` | `.opencode/agents/` | Nas quatro, os revisores e o tutor nascem **sem poder de escrita**; só o @@ -94,11 +94,6 @@ implementador escreve. A trava tem forças diferentes, e vale saber qual você t > nomes das pastas: renomeie `.opencode/agents/` para `.opencode/agent/` e > `.opencode/command/` para `.opencode/commands/`. O conteúdo é o mesmo. -> No **Antigravity**, o comando é o nome do arquivo em `.agents/workflows/`: -> `/prd`, `/backlog`, `/user-flows`, `/architecture`, `/setup`, `/utf-workflow` -> (= `/utf-issue`), `/ciclo-tarefa` (= `/utf-task`) e `/tutor`. Onde os guias -> dizem `/utf-`, leia o equivalente. - 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/tutorial-sdd.md b/docs/tutorial-sdd.md index 24f8e95..ee177b1 100644 --- a/docs/tutorial-sdd.md +++ b/docs/tutorial-sdd.md @@ -143,11 +143,6 @@ palavras, lista os apontamentos aceitos e recusados (saem dos arquivos Dizer "vamos trabalhar na Issue 12" em linguagem natural também dispara o fluxo (`utf-rules.md` §1) — os comandos são só o caminho mais curto. -> **No Antigravity o comando é o nome do arquivo em `.agents/workflows/`**, não o -> `/utf-*`: `/prd`, `/backlog`, `/user-flows`, `/architecture`, `/setup`, -> `/utf-workflow` (a Issue), `/ciclo-tarefa` (a tarefa) e `/tutor`. O conteúdo é -> o mesmo — onde este tutorial diz `/utf-`, leia o equivalente. - --- ## Fora do ciclo — bug e tarefa técnica