spec-first-claude 0.1.0

package/templates/.claude/commands/pausar.md

@@ -0,0 +1,83 @@
+# /pausar
+
+Encerra a sessão de trabalho de forma organizada.
+Consolida estado, atualiza memória, gera ponto de retomada para a próxima sessão.
+
+## Passos
+
+### 1. Levantar estado atual
+
+Para cada `.context.md` em `docs/Desenvolvimento/*/`:
+- Status atual + Progresso.md (% concluído, fase atual)
+- Tasks em andamento
+
+### 2. Verificar working tree dos repos
+
+Para cada repo em `projetos/`:
+```bash
+cd projetos/{repo}
+git status --short
+git log --oneline -3
+```
+- Se working tree sujo → avisar (sugerir commit antes de pausar)
+
+### 3. Atualizar `.ai/memory/napkin.md`
+
+Atualizar seção `## Sessão Atual` com:
+- Data, o que foi feito, o que estava em andamento
+- Decisões tomadas, armadilhas encontradas
+
+### 4. Gerar resumo de retomada
+
+Criar/atualizar `docs/Desenvolvimento/retomada.md`:
+
+```markdown
+# Ponto de Retomada — {{DATA}}
+
+> Gerado pelo /pausar. Leia este arquivo ao iniciar a próxima sessão.
+
+## Estado geral
+
+| Feature/Setup | Status | Fase atual | % | Próxima ação |
+|---------------|--------|------------|---|-------------|
+| {{nome}} | {{status}} | Fase {{N}} | {{%}} | {{ação}} |
+
+## Repos — estado do git
+
+| Repo | Branch ativa | Working tree | Último commit |
+|------|-------------|-------------|---------------|
+| {{repo}} | {{branch}} | limpo/sujo | {{commit msg}} |
+
+## O que estava em andamento
+
+- Task: {{AREA-NNN}} — {{descrição}}
+- Bloqueios: {{se houver}}
+- Decisões pendentes: {{se houver}}
+
+## Para retomar
+
+1. {{Passo 1 — ex: "Subir infra: docker compose up -d"}}
+2. {{Passo 2 — ex: "Continuar /dev feat_mvp --fase 2"}}
+3. {{Passo 3 — ex: "Resolver ambiguidade X do PRD"}}
+
+## Aprendizados desta sessão
+
+- {{Decisão ou armadilha que vale registrar}}
+```
+
+### 5. Informar ao usuário
+
+```
+✅ Sessão encerrada. Estado salvo em:
+  - `.ai/memory/napkin.md` — memória atualizada
+  - `docs/Desenvolvimento/retomada.md` — ponto de retomada
+
+Para retomar:
+  1. Ler retomada.md
+  2. Seguir os passos listados
+```
+
+## Notas
+- Não modifica .context.md (status da pipeline não muda)
+- Não faz commit automático — avisa se working tree sujo
+- `retomada.md` é sobrescrito a cada /pausar (ponto atual, não histórico)

package/templates/.claude/commands/plan.md

@@ -0,0 +1,86 @@
+# /plan $ARGUMENTS
+
+Skill atômica de planejamento. Lê SDD e gera tasks por área + Progresso.
+$ARGUMENTS = nome (ex: setup_projeto, feat_cadastro_cliente)
+
+## Agente: Planner (Opus)
+Metódico e exaustivo. Cada task auto-contida. Prioriza ordem correta.
+
+## Pré-condições
+
+| # | Validação | Se falhar |
+|---|-----------|-----------|
+| 1 | $ARGUMENTS informado | Parar |
+| 2 | `.context.md` com status `design_done` | Se anterior → "/design primeiro". Se posterior → "Tasks já geradas" |
+| 3 | `sdd.md` existe | Parar → "/design primeiro" |
+
+## Passos
+
+### 1. Ler contexto
+- SDD completo + `projetos.yaml` + `docs/Estrutura/` + `rules.md`
+- Template `tasks.template.md` + `Progresso.template.md`
+
+### 2. Identificar fases de entrega
+Ler PRD §11 (Fases de Entrega) — cada fase vira um agrupamento de tasks:
+- Fases são sequenciais: Fase 2 depende de Fase 1 concluída
+- Cada fase tem entregável e critério de done
+- O `/dev` pode rodar por fase: `/dev feat_nome --fase 1`
+
+### 3. Identificar áreas (por fase)
+
+| Seção SDD | Área |
+|-----------|------|
+| §3 Modelo de dados | BANCO |
+| §5 Endpoints API | BACK |
+| §6 Componentes/Telas | FRONT |
+| §8 Integrações | INFRA |
+| Outras | MOBILE, DEVOPS, etc. conforme SDD |
+
+> **Nota**: Área DOC NÃO existe mais no setup. docs/Estrutura/ é gerado pelo /design (passo 3).
+> DOC só aparece em features se houver necessidade explícita de documentação adicional.
+
+Áreas são DINÂMICAS — só criar as que o SDD exige.
+
+**Área INFRA obrigatória no setup:**
+Sempre gerar estas tasks no setup (antes de qualquer código):
+```
+- [ ] INFRA-001: Validar e configurar ambiente local [M]
+  (detectar OS, instalar Docker/.NET/Node, verificar portas)
+- [ ] INFRA-002: Criar docker-compose.yml + Dockerfiles [M]
+- [ ] INFRA-003: Hello world — subir stack completa e validar [M]
+  (docker compose up, migrations, health check, frontend carrega)
+```
+INFRA-001 é a PRIMEIRA task executada no /dev do setup (antes de BANCO, BACK, FRONT).
+INFRA-003 é a ÚLTIMA task (após tudo, como validação final).
+Setup só é `done` quando INFRA-003 passa.
+
+### 4. Gerar tasks por fase × área
+Para cada área → `{area}_tasks.md`, agrupadas por fase de entrega:
+```markdown
+- [ ] **AREA-NNN**: Título [Tamanho]
+  - Fase: {{N}} — {{Nome da fase de entrega}}
+  - Repo: `{{repo_name}}` (de projetos.yaml)
+  - Arquivos: `caminho/arquivo.ext` (relativo à raiz do repo)
+  - Testes: `caminho/teste.ext`
+  - SDD: §N.N — Referência específica
+  - Depende: AREA-NNN (ou —)
+```
+
+Regras:
+- **Repo obrigatório** — consultar `projetos.yaml` para mapear área → repo. Caminhos relativos ao repo
+- Tamanhos: S (<30min), M (30min-2h), L (2h+). L → avaliar se quebra em M+S
+- IDs sequenciais por área, nunca reutilizar
+- Dependências cross-area permitidas
+- Fases sequenciais: P1 (bloqueia), P2 (importante), P3 (nice-to-have)
+- Cada task inclui campo Testes (arquivo de teste correspondente)
+
+### 5. Gerar Progresso.md (por fase de entrega)
+- Resumo Área × Fase com contagem
+- Ordem de execução com paralelismos
+- Checklist pós-conclusão
+
+### 6. Atualizar progresso global + `.context.md`
+```yaml
+status: "plan_done"
+ultima_skill: "/plan"
+```

package/templates/.claude/commands/setup-projeto.md

@@ -0,0 +1,68 @@
+# /setup-projeto
+
+Orquestrador de bootstrap do projeto. Executa uma única vez.
+Cria contexto TRD, chama /extract e para no checkpoint de aprovação.
+
+## Execução
+
+Siga EXATAMENTE os passos da skill em ordem. Leia o arquivo completo antes de agir.
+
+### Pré-condições — validar TODAS antes de prosseguir
+
+| # | Validação | Se falhar |
+|---|-----------|-----------|
+| 1 | `docs/PM/setup_projeto/` existe | Parar → "Crie a pasta docs/PM/setup_projeto/ e adicione seus insumos" |
+| 2 | Pasta contém pelo menos 1 arquivo (ignorar .gitkeep) | Parar → "Adicione insumos na pasta (aceitos: .md, .txt, .sql, .xml, .html, .json, .csv, .png, .jpg, .pdf — qualquer formato)" |
+| 3 | `docs/Estrutura/` está vazio ou contém apenas .gitkeep | Parar → "Setup já foi executado. Use /feature para novas funcionalidades" |
+| 4 | `docs/Desenvolvimento/setup_projeto/.context.md` não existe ou status é `not_started` | Parar → "Setup já está em andamento. Verifique o status em .context.md" |
+
+### Passos
+
+1. Criar `docs/Desenvolvimento/setup_projeto/` se não existir
+
+2. Criar `.context.md`:
+```yaml
+---
+nome: "setup_projeto"
+tipo: "setup"
+documento: "TRD"
+pm_path: "docs/PM/setup_projeto/"
+status: "not_started"
+ultima_skill: "/setup-projeto"
+atualizado_em: "{{ISO_DATETIME}}"
+---
+```
+
+3. Sugerir /sf-discovery (RECOMENDADO):
+```
+📋 Recomendo rodar /sf-discovery antes da extração para análise profunda dos insumos.
+Quer rodar /sf-discovery docs/PM/setup_projeto/ agora? (s/n)
+```
+Se SIM → rodar discovery, salvar discovery.md em docs/Desenvolvimento/setup_projeto/
+Se NÃO → pular direto para extract
+
+4. Executar /extract setup_projeto (seguir o command /extract)
+
+5. CHECKPOINT — Parar e informar:
+```
+✅ TRD gerado em docs/Desenvolvimento/setup_projeto/TRD.md
+
+Revise o documento. Quando estiver satisfeito, execute:
+  /design setup_projeto
+
+Se precisar adicionar mais insumos, coloque na pasta docs/PM/setup_projeto/
+e execute:
+  /extract setup_projeto
+```
+
+**O orquestrador encerra aqui.** Próximos passos do usuário:
+1. `/design setup_projeto` (pergunta aprovação → gera SDD + docs/Estrutura/ + projetos.yaml)
+2. `/plan setup_projeto` (gera tasks com campo Repo por task)
+3. `/dev setup_projeto` (INFRA-001 cria/clona repos em projetos/, executa tasks nos repos corretos)
+
+### Notas
+- Esta skill roda UMA ÚNICA VEZ por projeto
+- docs/Estrutura/ é gerado pelo /design (passo 3), não por tasks DOC
+- `projetos.yaml` é gerado pelo /design (passo 3b) — mapeia serviços para repos
+- Repos são criados/clonados pelo /dev (INFRA-001) dentro de `projetos/`
+- /merge-delta NÃO se aplica ao setup (é criação, não atualização)

package/templates/.claude/settings.local.json

@@ -0,0 +1,6 @@
+{
+  "enabledMcpjsonServers": [
+    "supabase"
+  ],
+  "enableAllProjectMcpServers": true
+}

package/templates/CLAUDE.md

@@ -0,0 +1,199 @@
+# CLAUDE.md — Projeto
+
+> Regras globais para TODAS as interações neste projeto.
+> Lido automaticamente no início de cada sessão.
+
+---
+
+## Inicialização (executar no início de cada sessão)
+
+### 1. Verificar dependências do workflow
+
+| Dependência | Caminho | Se não existir |
+|-------------|---------|----------------|
+| Napkin (memória) | `.ai/memory/napkin.md` | Criar com formato padrão |
+| Templates | `docs/_templates/` | ERRO — projeto não está configurado |
+| Commands | `.claude/commands/` | ERRO — projeto não está configurado |
+| Agents | `.claude/agents/` | ERRO — projeto não está configurado |
+| Rules | `docs/Desenvolvimento/rules.md` | ERRO — projeto não está configurado |
+| Retomada | `docs/Desenvolvimento/retomada.md` | OK — primeira sessão |
+
+### 2. Validar acesso a todos commands
+
+Verificar que TODOS os 9 commands estão acessíveis:
+
+| Command | Caminho |
+|---------|---------|
+| `/setup-projeto` | `.claude/commands/setup-projeto.md` |
+| `/feature` | `.claude/commands/feature.md` |
+| `/discovery` | `.claude/commands/discovery.md` |
+| `/extract` | `.claude/commands/extract.md` |
+| `/design` | `.claude/commands/design.md` |
+| `/plan` | `.claude/commands/plan.md` |
+| `/dev` | `.claude/commands/dev.md` |
+| `/merge-delta` | `.claude/commands/merge-delta.md` |
+| `/pausar` | `.claude/commands/pausar.md` |
+
+Se algum command não for encontrado → avisar o usuário.
+
+### 3. Carregar contexto
+
+1. Ler `.ai/memory/napkin.md` — decisões e padrões acumulados
+2. Ler `docs/Desenvolvimento/retomada.md` (se existir) — ponto de retomada da última sessão
+3. Ler `docs/Estrutura/` (se existir) — contexto global do projeto
+4. Ler `docs/Desenvolvimento/rules.md` — regras de desenvolvimento
+
+---
+
+## Identidade do Projeto
+
+Este é um projeto que utiliza desenvolvimento **spec-first** assistido por IA.
+Nenhum código é escrito sem especificação aprovada (SDD).
+
+### Arquitetura: Projeto-base vs Repos de código
+
+```
+ESTE REPO (projeto-base) = ORQUESTRADOR
+├── docs/          ← specs, PRDs, SDDs, tasks (fonte de verdade)
+├── projetos.yaml  ← manifesto de repos
+└── projetos/      ← repos de código (gitignored, cada um com .git próprio)
+    ├── api/       ← repo: org/projeto-api
+    ├── web/       ← repo: org/projeto-web
+    └── worker/    ← repo: org/projeto-worker
+```
+
+**Regra clara**:
+- **Specs, docs, tasks, progresso** → ficam NESTE repo (projeto-base)
+- **Código, testes, Dockerfiles, CI** → ficam nos repos em `projetos/`
+- **Commits de código** → nos repos do serviço, NUNCA no projeto-base
+- **Git workflow (branches, PRs, merge)** → se aplica aos repos em `projetos/`
+
+## Pipeline do Workflow
+
+```
+docs/PM/ (qualquer arquivo)
+    ↓ /setup-projeto (uma vez) ou /feature (por feature)
+/sf-discovery → análise profunda dos insumos (RECOMENDADO, opcional)
+    ↓
+/extract → PRD ou TRD (checkpoint — usuário revisa e aprova)
+    ↓
+/design → SDD + projetos.yaml + docs/Estrutura/ (setup)
+    ↓
+/plan → *_tasks.md + Progresso.md (tasks com campo Repo:)
+    ↓
+/dev → INFRA-001 cria repos → código nos repos (Security Review pós-dev)
+    ↓
+/merge-delta → docs/Estrutura/ atualizado (apenas para features)
+```
+
+## Commands disponíveis (slash commands)
+
+| Command | Tipo | O que faz |
+|---------|------|-----------|
+| `/setup-projeto` | Orquestrador | Bootstrap: cria .context.md, chama /extract, para no checkpoint. Roda UMA vez |
+| `/feature <nome>` | Orquestrador | Feature: cria .context.md tipo PRD, chama /extract, para no checkpoint |
+| `/discovery <path>` | Utilitária | Análise profunda dos insumos (RECOMENDADO antes do /extract) |
+| `/extract <nome>` | Atômico | Lê docs/PM/{nome}/ → gera PRD ou TRD. Re-executável para novos insumos |
+| `/design <nome>` | Atômico | Pergunta aprovação → gera SDD a partir do PRD/TRD |
+| `/plan <nome>` | Atômico | Lê SDD → gera tasks por área + Progresso.md |
+| `/dev <nome>` | Atômico | Implementa tasks com loop (implement → test → review). Agents por área |
+| `/merge-delta <nome>` | Atômico | Aplica SDD §11 Delta Specs em docs/Estrutura/ |
+| `/pausar` | Utilitária | Encerra sessão: salva estado, atualiza napkin, gera retomada.md |
+
+## Agents especializados (usados pelo /dev)
+
+| Agent | Área | Stack padrão | Perfil |
+|-------|------|-------------|--------|
+| Backend Coder | BACK | .NET 8 / C# | `.claude/agents/backend-coder.md` |
+| Frontend Coder | FRONT | React + Fusion | `.claude/agents/frontend-coder.md` |
+| DB Coder | BANCO | PostgreSQL 16 | `.claude/agents/db-coder.md` |
+| Infra Coder | INFRA | Docker | `.claude/agents/infra-coder.md` |
+| Doc Writer | DOC | — | `.claude/agents/doc-writer.md` |
+| Reviewer | Todas | — | `.claude/agents/reviewer.md` |
+| Security Reviewer | Todas | — | `.claude/agents/security-reviewer.md` |
+
+## Estado da pipeline (`.context.md`)
+
+Cada feature/setup tem um `.context.md` em `docs/Desenvolvimento/{nome}/`:
+
+```
+not_started → extract_done → approved → design_done → plan_done → dev_in_progress → dev_done → done
+```
+
+Antes de executar qualquer command, verificar o status no `.context.md`. Cada command só avança se o status anterior está correto. Apenas commands atualizam `.context.md` — o usuário nunca edita manualmente.
+
+## Regras Invioláveis
+
+1. **Spec-first**: NUNCA gerar código sem SDD aprovado
+2. **PM é sagrado**: NUNCA modificar arquivos em `docs/PM/`
+3. **Extração rígida**: categorias fixas do template, sem texto narrativo, ambiguidades são BLOQUEANTES
+4. **SDD é auto-contido**: coder lê APENAS SDD + task, NUNCA PRD/PM diretamente
+5. **Memória ativa**: ler napkin.md no início, atualizar ao descobrir padrões/armadilhas
+6. **Progresso atualizado**: atualizar Progresso.md ao concluir cada task
+7. **Delta Specs**: todo SDD tem §11 ADDED/MODIFIED/REMOVED — obrigatório
+8. **Testes junto com código**: implementar e testar na mesma task, não separar
+9. **Não commitar sem pedir**: sempre perguntar antes de commitar
+
+## Estrutura de Documentação
+
+```
+docs/
+├── PM/                  ← Insumos brutos (QUALQUER formato — nunca modificar)
+│   ├── setup_projeto/   ← Insumos de bootstrap
+│   └── feat_*/          ← Insumos por feature
+├── _templates/          ← 18 templates (feature/7 + estrutura/8 + global/1 + projetos.yaml + backlog + extract-log)
+├── Estrutura/           ← Retrato global do projeto (gerado pelo /design)
+└── Desenvolvimento/     ← Artefatos por feature
+    ├── rules.md         ← Regras de desenvolvimento
+    └── {nome}/          ← PRD/TRD, SDD, *_tasks.md, Progresso.md, .context.md, .extract-log.md
+projetos/                ← Repos de serviços (gitignored, cada um com .git próprio)
+projetos.yaml            ← Manifesto: serviço → repo → áreas → stack
+```
+
+## Convenções
+
+- **Pastas**: `feat_nome`, `bug_nome`, `task_nome` (snake_case com prefixo)
+- **Task IDs**: `AREA-NNN` (BANCO-001, BACK-001, FRONT-001)
+- **Regras de negócio**: `RN-NNN` (IDs estáveis, nunca renumerar)
+- **Commits**: `tipo(TASK-ID): descrição` (feat, fix, refactor, test, docs, chore)
+- **Branches**: `feature/feat_nome`, `bugfix/bug_nome`, `task/task_nome`
+
+## Quando Parar e Perguntar
+
+- `docs/PM/{nome}/` vazio ou inexistente → PARAR
+- Ambiguidade na extração → listar como pergunta BLOQUEANTE, PARAR
+- `.context.md` com status incompatível com o command → PARAR, informar status atual
+- Task com dependência não concluída → avisar, não pular
+- Dúvida sobre regra de negócio → perguntar, NUNCA assumir
+- Quality gate reprovado 3x → escalar pro usuário
+
+## Arquivos Sensíveis
+
+### NUNCA modificar
+- `docs/PM/**/*` — Insumos brutos. Somente leitura.
+- `.env`, `.env.*` — Secrets.
+- `docs/Estrutura/ADRs.md` — ADRs aceitas são imutáveis (apenas adicionar novas).
+
+### Requerem aprovação
+- `docs/Estrutura/*` — Só alterar via /merge-delta após /dev.
+- `docs/Desenvolvimento/rules.md` — Alteração explícita.
+- `CLAUDE.md` — Meta-regras. Alteração requer aprovação.
+- `.claude/commands/*`, `.claude/agents/*` — Alteração requer aprovação.
+
+### Formato rígido (gerados por commands)
+- `.context.md` — YAML frontmatter, apenas commands atualizam.
+- `.extract-log.md` — Append-only, hashes obrigatórios.
+- `PRD.md`, `TRD.md`, `sdd.md` — Seguir template exato.
+- `*_tasks.md` — IDs sequenciais, campos obrigatórios.
+- `Progresso.md` — Tabelas com formato fixo.
+
+## Referências
+
+| Doc | Onde |
+|-----|------|
+| Rules de dev | `docs/Desenvolvimento/rules.md` |
+| Memória | `.ai/memory/napkin.md` |
+| Commands | `.claude/commands/*.md` |
+| Agents | `.claude/agents/*.md` |
+| Templates | `docs/_templates/` |
+| Estrutura do sistema | `docs/Estrutura/*.md` (após setup) |

package/templates/docs/Desenvolvimento/rules.md

@@ -0,0 +1,229 @@
+# Regras de Desenvolvimento
+
+> Regras que todos os agentes de desenvolvimento devem seguir.
+> Lido pelo Coder/Senior Coder e Reviewer antes de cada task.
+> Aplicado globalmente a todas as features.
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+QUANDO LER: Toda vez que /dev executar uma task. Obrigatório.
+QUEM LÊ: Coder, Senior Coder e Reviewer.
+COMO USAR: Regras aqui são LEI — não são sugestões. Violações reprovam a task no quality gate.
+
+PERSONALIZAÇÃO: Este arquivo é editado manualmente pelo time.
+As regras abaixo são o padrão do framework. O time pode:
+- Adicionar regras específicas da stack
+- Remover regras que não se aplicam
+- Ajustar convenções ao projeto
+
+=============================================================================
+-->
+
+## Regras Invioláveis
+
+1. **Spec-first**: Nenhuma task pode ser executada sem SDD aprovado
+2. **SDD é a fonte**: O coder lê APENAS o SDD + task — nunca consulta PRD ou PM diretamente
+3. **Um commit por task**: Cada task gera exatamente 1 commit
+4. **Sem invenção**: Se o SDD não especifica, o coder NÃO assume — para e reporta
+5. **Entregáveis contínuos**: Toda feature é faseada em entregáveis incrementais. Cada fase entrega valor ao usuário e pode ir para produção independentemente. Nunca "tudo ou nada" — sempre "pequeno e constante"
+6. **Nunca na main**: Todo código é desenvolvido em branch própria. Merge apenas via PR aprovado pelo usuário
+
+## Convenções de Código
+
+### Padrão geral
+- Todo código segue as convenções de `docs/Estrutura/Stack.md`
+- Nomes em inglês (código) — documentação em português
+- Sem código morto (comentado) — se não usa, apaga
+- Sem secrets hardcoded — sempre variáveis de ambiente
+
+### Backend
+- Testes obrigatórios: mínimo happy path + 1 cenário de erro
+- Validação de input na borda (controller/handler) — não no service
+- Erros de negócio: usar códigos definidos em `docs/Estrutura/API.md`
+- Tipos explícitos (sem `any`, `object`, `dynamic` genéricos)
+
+### Frontend
+- Componentes tipados com props documentadas
+- Estados explícitos: loading, empty, error, success
+- Sem lógica de negócio no componente — delegar para hooks/services
+
+### Banco de dados
+- Toda migration tem rollback testado
+- Execução sequencial — nunca pular migrations
+- Seeds apenas para ambiente de desenvolvimento
+
+## Convenções de Git
+
+> **Escopo**: Estas regras se aplicam aos **repositórios em `projetos/`** (api, web, worker, etc.).
+> O projeto-base em si é o orquestrador — specs e docs ficam aqui, código fica nos repos.
+
+### Commits
+```
+tipo(TASK-ID): descrição curta
+
+Corpo opcional com detalhes.
+
+Refs: feat_cadastro_cliente
+```
+
+| Tipo | Quando usar |
+|------|-------------|
+| `feat` | Nova funcionalidade |
+| `fix` | Correção de bug |
+| `refactor` | Mudança sem alterar comportamento |
+| `test` | Adição/alteração de testes |
+| `docs` | Documentação |
+| `chore` | Configuração, build, CI |
+
+### Branches
+```
+feature/feat_cadastro_cliente
+feature/feat_mvp_fase1
+bugfix/bug_cpf_duplicado
+task/task_otimizar_listagem
+```
+
+| Regra | Descrição |
+|-------|-----------|
+| Base | Sempre a partir de `main` atualizada (origin) |
+| Merge | Via Pull Request aprovado pelo usuário — NUNCA merge automático |
+| Conflitos | Resolver antes de mergear — nunca force push em branch compartilhada |
+
+### Git Workflow (5 passos obrigatórios)
+
+O /dev DEVE seguir este fluxo para CADA fase de entrega:
+
+#### Passo 1 — Antes de codar
+```bash
+# Verificar working tree limpo
+git status
+# Se há mudanças pendentes → sugerir commit ou stash antes de prosseguir
+# NUNCA começar a codar com working tree sujo
+```
+
+#### Passo 2 — Criar branch
+```bash
+# Atualizar main a partir do remote
+git checkout main
+git pull origin main
+
+# Criar branch para a fase
+git checkout -b feature/{nome}_fase{N}
+# Ex: feature/feat_mvp_fase1
+```
+- Branch criada no **repo do serviço** (projetos/api, projetos/web, etc.)
+- Se a fase afeta múltiplos repos → branch com mesmo nome em cada um
+- NUNCA desenvolver direto na main
+
+#### Passo 3 — Ao terminar a fase
+```bash
+# Atualizar Progresso.md com status da fase
+# Push da branch
+git push origin feature/{nome}_fase{N}
+
+# Abrir PR com template detalhado (ver seção abaixo)
+gh pr create --title "..." --body "..."
+```
+- Deixar ambiente local **rodando** (docker compose up + dotnet run + npm run dev)
+- Informar ao usuário que o ambiente está ON para testes manuais
+
+#### Passo 4 — Aguardar aprovação
+```
+⏸️ PARAR e aguardar.
+- O usuário revisa o PR, testa manualmente o ambiente local
+- Merge é MANUAL — o agente NUNCA faz merge
+- Se o usuário pedir ajustes → corrigir na mesma branch, push, atualizar PR
+```
+
+#### Passo 5 — Após merge (quando usuário confirmar)
+```bash
+# Atualizar main local
+git checkout main
+git pull origin main
+
+# Limpar branches mergeadas
+git branch -d feature/{nome}_fase{N}
+git remote prune origin
+```
+
+### Template de Pull Request
+
+Todo PR aberto pelo /dev DEVE seguir este formato:
+
+```markdown
+## Fase {N} — {Nome da fase}
+
+### O que foi entregue
+- [ ] {Entregável 1 da fase}
+- [ ] {Entregável 2 da fase}
+
+### Tasks concluídas
+| Task | Descrição | Testes |
+|------|-----------|--------|
+| BACK-001 | Criar endpoint X | ✅ unit + integration |
+| BANCO-001 | Migration tabela Y | ✅ rollback testado |
+| FRONT-001 | Tela de cadastro | ✅ unit |
+
+### Testes
+- ✅ Unit tests passando ({N}/{N})
+- ✅ Integration tests passando ({N}/{N})
+- ✅ Security Review aprovado
+- ⬜ E2E (aguardando teste manual do usuário)
+
+### Como testar manualmente
+1. Ambiente já está rodando em:
+   - API: http://localhost:8080
+   - Web: http://localhost:3000
+   - Banco: localhost:5432
+2. Fluxo para testar:
+   - {Passo 1 do teste manual}
+   - {Passo 2 do teste manual}
+   - {Resultado esperado}
+
+### Observações
+- {Decisões tomadas, trade-offs, pontos de atenção}
+```
+
+## Quality Gate (por task)
+
+> Checklist obrigatório. O Reviewer valida TODOS os itens antes de aprovar.
+
+- [ ] Código compila sem erros
+- [ ] Testes passam (se aplicável à task)
+- [ ] Lint limpo (sem warnings não justificados)
+- [ ] Critérios de aceite da task atendidos (ref SDD §9)
+- [ ] Sem TODOs no código sem justificativa
+- [ ] Sem secrets hardcoded
+- [ ] Commit segue convenção: `tipo(TASK-ID): descrição`
+- [ ] Arquivos listados na task foram os únicos modificados (sem side effects)
+
+## Regras por Stack
+
+> Seção opcional. Adicionar regras específicas da tecnologia escolhida.
+> Exemplos abaixo — remover/ajustar conforme o projeto.
+
+<!--
+### Node.js / TypeScript
+- ESLint + Prettier como formatador
+- Strict mode no tsconfig
+- Path aliases configurados (@/modules, @/shared)
+
+### Python
+- Ruff como linter/formatter
+- Type hints obrigatórios (mypy strict)
+- Virtual environment (venv ou poetry)
+
+### React / Next.js
+- Server Components por padrão, Client Components só quando necessário
+- Zustand ou Context para estado global (não Redux)
+- Tailwind CSS para estilos
+-->
+
+---
+
+> **Atualização**: Editado manualmente pelo time. Aplicado globalmente a todas as features.