spec-first-claude 0.2.0 → 0.4.0

package/templates/CLAUDE.md

@@ -1,199 +1,198 @@
-# 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) |
+# 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` |
+| `/session-finish` | `.claude/commands/session-finish.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 automático em features (aplica SDD §11 em docs/Estrutura/)
+```
+
+## 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 automático em features |
+| `/merge-delta <nome>` | Atômico | Aplica SDD §11 Delta Specs em docs/Estrutura/ (chamado automaticamente pelo /dev, re-executável manualmente) |
+| `/session-finish` | 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) |