spec-first-copilot 0.2.0 → 0.4.0

package/templates/.github/copilot-instructions.md

@@ -1,176 +1,175 @@
-# Copilot Instructions — Projeto
-
-> Regras globais que o agente deve seguir em TODAS as interações neste projeto.
-> Este arquivo é 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: seções Decisões, Padrões, Armadilhas, Preferências (máx 10 itens/seção) |
-| Templates | `docs/_templates/` | ERRO — projeto não está configurado |
-| Skills | `.github/skills/` | ERRO — projeto não está configurado |
-| Agents | `.github/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 todas skills
-
-Verificar que TODAS as 9 skills estão acessíveis:
-
-| Skill | Caminho |
-|-------|---------|
-| `/sf-setup-projeto` | `.github/skills/sf-setup-projeto/SKILL.md` |
-| `/sf-feature` | `.github/skills/sf-feature/SKILL.md` |
-| `/sf-extract` | `.github/skills/sf-extract/SKILL.md` |
-| `/sf-design` | `.github/skills/sf-design/SKILL.md` |
-| `/sf-plan` | `.github/skills/sf-plan/SKILL.md` |
-| `/sf-dev` | `.github/skills/sf-dev/SKILL.md` |
-| `/sf-merge-delta` | `.github/skills/sf-merge-delta/SKILL.md` |
-| `/sf-pausar` | `.github/skills/sf-pausar/SKILL.md` |
-| `/sf-discovery` | `.github/skills/sf-discovery/SKILL.md` |
-
-Se alguma skill não for encontrada → 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.
-
-### 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/`
-Nenhum código é escrito sem especificação aprovada (SDD).
-
-## Pipeline do Workflow
-
-```
-docs/PM/ (qualquer arquivo)
-    ↓ /sf-setup-projeto (uma vez) ou /sf-feature (por feature)
-/sf-discovery → análise profunda dos insumos (RECOMENDADO, opcional)
-    ↓
-/sf-extract → PRD ou TRD (checkpoint — usuário revisa e aprova)
-    ↓
-/sf-design → SDD + projetos.yaml + docs/Estrutura/ (setup)
-    ↓
-/sf-plan → *_tasks.md + Progresso.md (tasks por fase × área)
-    ↓
-/sf-dev → código nos repos (Security Review pós-dev)
-    ↓
-/sf-merge-delta → docs/Estrutura/ atualizado (apenas para features)
-```
-
-## Skills disponíveis
-
-| Skill | Tipo | O que faz |
-|-------|------|-----------|
-| `/sf-setup-projeto` | Orquestrador | Bootstrap: cria .context.md, chama /sf-extract, para no checkpoint. Roda UMA vez |
-| `/sf-feature <nome>` | Orquestrador | Feature: cria .context.md tipo PRD, chama /sf-extract, para no checkpoint |
-| `/sf-extract <nome>` | Atômica | Lê docs/PM/{nome}/ → gera PRD ou TRD. Re-executável para novos insumos |
-| `/sf-design <nome>` | Atômica | Pergunta aprovação → gera SDD a partir do PRD/TRD |
-| `/sf-plan <nome>` | Atômica | Lê SDD → gera tasks por área + Progresso.md |
-| `/sf-dev <nome>` | Atômica | Implementa tasks com loop (implement → test → review). Agents por área |
-| `/sf-merge-delta <nome>` | Atômica | Aplica SDD §11 Delta Specs em docs/Estrutura/ |
-| `/sf-pausar` | Utilitária | Encerra sessão: salva estado, atualiza napkin, gera retomada.md |
-| `/sf-discovery` | Utilitária | Análise profunda de sistemas, arquiteturas e documentações |
-
-## Agents especializados (usados pelo /dev)
-
-| Agent | Área | Stack padrão | Perfil |
-|-------|------|-------------|--------|
-| Backend Coder | BACK | .NET 8 / C# | `.github/agents/backend-coder.md` |
-| Frontend Coder | FRONT | React + Fusion | `.github/agents/frontend-coder.md` |
-| DB Coder | BANCO | PostgreSQL 16 | `.github/agents/db-coder.md` |
-| Infra Coder | INFRA | Docker | `.github/agents/infra-coder.md` |
-| Doc Writer | DOC | — | `.github/agents/doc-writer.md` |
-| Reviewer | Todas | — | `.github/agents/reviewer.md` |
-| Security Reviewer | Todas | — | `.github/agents/security-reviewer.md` |
-
-## Estado da pipeline (`.context.md`)
-
-Cada feature/setup tem um `.context.md` em `docs/Desenvolvimento/{nome}/` que controla o fluxo:
-
-```
-not_started → extract_done → approved → design_done → plan_done → dev_in_progress → dev_done → done
-```
-
-Antes de executar qualquer skill, verificar o status no `.context.md`. Cada skill só avança se o status anterior está correto.
-
-## 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
-
-## Estrutura de Documentação
-
-```
-docs/
-├── PM/                  ← Insumos brutos (QUALQUER formato — nunca modificar)
-│   ├── setup_projeto/   ← Insumos de bootstrap
-│   └── feat_*/          ← Insumos por feature
-├── _templates/          ← 16 templates (feature/7 + estrutura/8 + global/1)
-├── Estrutura/           ← Retrato global do projeto (gerado por /setup-projeto via tasks DOC)
-└── Desenvolvimento/     ← Artefatos por feature
-    ├── rules.md         ← Regras de desenvolvimento
-    └── {nome}/          ← PRD/TRD, SDD, *_tasks.md, Progresso.md, .context.md, .extract-log.md
-```
-
-## 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 a skill → 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
-
-## Referências
-
-| Doc | Onde |
-|-----|------|
-| Rules de dev | `docs/Desenvolvimento/rules.md` |
-| Memória | `.ai/memory/napkin.md` |
-| Skills | `.github/skills/*.md` |
-| Agents | `.github/agents/*.md` |
-| Templates | `docs/_templates/` |
-| Estrutura do sistema | `docs/Estrutura/*.md` (após setup) |
+# Copilot Instructions — Projeto
+
+> Regras globais que o agente deve seguir em TODAS as interações neste projeto.
+> Este arquivo é 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: seções Decisões, Padrões, Armadilhas, Preferências (máx 10 itens/seção) |
+| Templates | `docs/_templates/` | ERRO — projeto não está configurado |
+| Skills | `.github/skills/` | ERRO — projeto não está configurado |
+| Agents | `.github/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 todas skills
+
+Verificar que TODAS as 9 skills estão acessíveis:
+
+| Skill | Caminho |
+|-------|---------|
+| `/sf-setup-projeto` | `.github/skills/sf-setup-projeto/SKILL.md` |
+| `/sf-feature` | `.github/skills/sf-feature/SKILL.md` |
+| `/sf-extract` | `.github/skills/sf-extract/SKILL.md` |
+| `/sf-design` | `.github/skills/sf-design/SKILL.md` |
+| `/sf-plan` | `.github/skills/sf-plan/SKILL.md` |
+| `/sf-dev` | `.github/skills/sf-dev/SKILL.md` |
+| `/sf-merge-delta` | `.github/skills/sf-merge-delta/SKILL.md` |
+| `/sf-session-finish` | `.github/skills/sf-session-finish/SKILL.md` |
+| `/sf-discovery` | `.github/skills/sf-discovery/SKILL.md` |
+
+Se alguma skill não for encontrada → 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.
+
+### 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/`
+Nenhum código é escrito sem especificação aprovada (SDD).
+
+## Pipeline do Workflow
+
+```
+docs/PM/ (qualquer arquivo)
+    ↓ /sf-setup-projeto (uma vez) ou /sf-feature (por feature)
+/sf-discovery → análise profunda dos insumos (RECOMENDADO, opcional)
+    ↓
+/sf-extract → PRD ou TRD (checkpoint — usuário revisa e aprova)
+    ↓
+/sf-design → SDD + projetos.yaml + docs/Estrutura/ (setup)
+    ↓
+/sf-plan → *_tasks.md + Progresso.md (tasks por fase × área)
+    ↓
+/sf-dev → código nos repos (Security Review pós-dev)
+    → merge-delta automático em features (aplica SDD §11 em docs/Estrutura/)
+```
+
+## Skills disponíveis
+
+| Skill | Tipo | O que faz |
+|-------|------|-----------|
+| `/sf-setup-projeto` | Orquestrador | Bootstrap: cria .context.md, chama /sf-extract, para no checkpoint. Roda UMA vez |
+| `/sf-feature <nome>` | Orquestrador | Feature: cria .context.md tipo PRD, chama /sf-extract, para no checkpoint |
+| `/sf-extract <nome>` | Atômica | Lê docs/PM/{nome}/ → gera PRD ou TRD. Re-executável para novos insumos |
+| `/sf-design <nome>` | Atômica | Pergunta aprovação → gera SDD a partir do PRD/TRD |
+| `/sf-plan <nome>` | Atômica | Lê SDD → gera tasks por área + Progresso.md |
+| `/sf-dev <nome>` | Atômica | Implementa tasks com loop (implement → test → review). Agents por área. Merge-delta automático em features |
+| `/sf-merge-delta <nome>` | Atômica | Aplica SDD §11 Delta Specs em docs/Estrutura/ (chamado automaticamente pelo /sf-dev, re-executável manualmente) |
+| `/sf-session-finish` | Utilitária | Encerra sessão: salva estado, atualiza napkin, gera retomada.md |
+| `/sf-discovery` | Utilitária | Análise profunda de sistemas, arquiteturas e documentações |
+
+## Agents especializados (usados pelo /dev)
+
+| Agent | Área | Stack padrão | Perfil |
+|-------|------|-------------|--------|
+| Backend Coder | BACK | .NET 8 / C# | `.github/agents/backend-coder.md` |
+| Frontend Coder | FRONT | React + Fusion | `.github/agents/frontend-coder.md` |
+| DB Coder | BANCO | PostgreSQL 16 | `.github/agents/db-coder.md` |
+| Infra Coder | INFRA | Docker | `.github/agents/infra-coder.md` |
+| Doc Writer | DOC | — | `.github/agents/doc-writer.md` |
+| Reviewer | Todas | — | `.github/agents/reviewer.md` |
+| Security Reviewer | Todas | — | `.github/agents/security-reviewer.md` |
+
+## Estado da pipeline (`.context.md`)
+
+Cada feature/setup tem um `.context.md` em `docs/Desenvolvimento/{nome}/` que controla o fluxo:
+
+```
+not_started → extract_done → approved → design_done → plan_done → dev_in_progress → dev_done → done
+```
+
+Antes de executar qualquer skill, verificar o status no `.context.md`. Cada skill só avança se o status anterior está correto.
+
+## 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
+
+## Estrutura de Documentação
+
+```
+docs/
+├── PM/                  ← Insumos brutos (QUALQUER formato — nunca modificar)
+│   ├── setup_projeto/   ← Insumos de bootstrap
+│   └── feat_*/          ← Insumos por feature
+├── _templates/          ← 16 templates (feature/7 + estrutura/8 + global/1)
+├── Estrutura/           ← Retrato global do projeto (gerado por /setup-projeto via tasks DOC)
+└── Desenvolvimento/     ← Artefatos por feature
+    ├── rules.md         ← Regras de desenvolvimento
+    └── {nome}/          ← PRD/TRD, SDD, *_tasks.md, Progresso.md, .context.md, .extract-log.md
+```
+
+## 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 a skill → 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
+
+## Referências
+
+| Doc | Onde |
+|-----|------|
+| Rules de dev | `docs/Desenvolvimento/rules.md` |
+| Memória | `.ai/memory/napkin.md` |
+| Skills | `.github/skills/*.md` |
+| Agents | `.github/agents/*.md` |
+| Templates | `docs/_templates/` |
+| Estrutura do sistema | `docs/Estrutura/*.md` (após setup) |

package/templates/.github/instructions/docs.instructions.md

@@ -1,123 +1,123 @@
-# Instruções — Documentação e Specs
-
-> Regras para o agente ao trabalhar com a camada de documentação.
-> Complementa `copilot-instructions.md` com detalhes operacionais.
-
-## Skills e fluxo
-
-O pipeline é executado por skills atômicas, cada uma com seu arquivo em `.github/skills/`:
-
-```
-/setup-projeto → /extract → /design → /plan → /dev → /merge-delta
-```
-
-Cada skill tem pré-condições, passos e saídas documentados. **Sempre ler a skill antes de executar.**
-
-## Estado da pipeline (`.context.md`)
-
-Cada feature/setup tem um `.context.md` (YAML frontmatter) que controla o fluxo:
-
-```
-not_started → extract_done → approved → design_done → plan_done → dev_in_progress → dev_done → done
-```
-
-- **Apenas skills atualizam** `.context.md` — o usuário nunca edita manualmente
-- **Aprovação** acontece no início do `/design` (skill pergunta ao usuário)
-- Antes de executar qualquer skill, verificar status no `.context.md`
-
-## Extração (/extract)
-
-Cada tipo de projeto tem seu documento de extração:
-
-| Comando | Documento | Template | Foco |
-|---------|----------|---------|------|
-| `/setup-projeto` | TRD.md | `_templates/feature/TRD.template.md` | Stack, arquitetura, infra, modelo base |
-| `/feature` | PRD.md | `_templates/feature/PRD.template.md` | Regras de negócio, jornadas, telas |
-
-### Multi-agent no /extract
-
-| Agente | Modelo | Papel |
-|--------|--------|-------|
-| Reader (1 por arquivo) | Sonnet | Lê e cataloga 1 arquivo por vez, em paralelo |
-| Analyzer | Opus | Cruza fontes, detecta gaps/contradições, gera documento final |
-
-### Regras da extração
-
-- Ler TODOS arquivos em `docs/PM/{nome}/` (qualquer formato: .md, .txt, .sql, .html, .xml, .csv, .png, .pdf)
-- Categorias FIXAS do template — não inventar seções novas
-- Regras de negócio com IDs únicos e estáveis (RN-001, RN-002 — nunca renumerar)
-- Ambiguidades = BLOQUEANTES (workflow para até responder)
-- Nunca INFERIR regra de negócio — se não está explícito, é ambiguidade
-- Contradições entre arquivos → ambiguidade citando ambos
-- Rastreabilidade obrigatória: cada informação aponta pro arquivo fonte
-- Arquivo não identificável → registrar como NÃO IDENTIFICADO no extract-log, gerar ambiguidade
-- Gerar `.extract-log.md` com hash SHA-256 (8 chars) por arquivo
-
-### Re-extração
-
-- Compara hashes com `.extract-log.md` existente → NOVO / MODIFICADO / INALTERADO
-- Merge ADITIVO (nunca remove info de arquivos inalterados)
-- Novas regras continuam sequência de IDs (se último era RN-005, próximo é RN-006)
-
-## Design (/design)
-
-1. Verificar aprovação do PRD/TRD (perguntar ao usuário)
-2. Verificar ambiguidades — todas devem estar respondidas
-3. Ler PRD/TRD + `docs/Estrutura/` + `rules.md`
-4. Gerar SDD usando `_templates/feature/sdd.template.md`
-5. SDD deve ser **auto-contido** — coder lê APENAS SDD + task, nada mais
-6. Toda regra referencia seção do PRD/TRD (rastreabilidade)
-7. §9 Estratégia de Testes: definir framework, estrutura, CAs mapeados a testes
-8. §11 Delta Specs: obrigatório (ADDED/MODIFIED/REMOVED)
-9. Seções N/A permitidas em setup (§4-§8 podem ser N/A)
-
-## Planejamento (/plan)
-
-1. Ler SDD completo + `docs/Estrutura/` + `rules.md`
-2. Áreas são DINÂMICAS — determinadas pelo SDD, não pré-definidas
-3. Para cada área → gerar `{area}_tasks.md` usando `_templates/feature/tasks.template.md`
-4. Tasks em fases sequenciais com prioridade P1/P2/P3
-5. Cada task: ID (AREA-NNN), título, tamanho (S/M/L), arquivos, ref SDD §N, depende, testes
-6. Gerar `Progresso.md` com ordem de execução e paralelismos
-7. Em setup: área DOC obrigatória (8 tasks, 1 por doc de Estrutura)
-
-## Desenvolvimento (/dev)
-
-### Agents por área (perfis em `.github/agents/`)
-
-| Área | Agente | Stack padrão |
-|------|--------|-------------|
-| BANCO | DB Coder | PostgreSQL 16 |
-| BACK | Backend Coder | .NET 8 / C# |
-| FRONT | Frontend Coder | React + Fusion |
-| INFRA | Infra Coder | Docker |
-| DOC | Doc Writer | — |
-| Todas | Reviewer | — |
-
-### Loop de desenvolvimento
-
-```
-Por task: implement → test unit → fix → lint → commit → review → fix → review (max 3)
-Por fase: integration tests → fix
-Por feature: E2E tests (CAs) → fix → dev_done
-```
-
-### Regras
-
-- Implement + testes na mesma task (não separar)
-- Agente selecionado pelo prefixo: BACK-* → Backend Coder
-- Modelo por tamanho: S/M → Sonnet, L → Opus
-- 1 commit por task: `tipo(TASK-ID): descrição`
-- Quality gate validado pelo Reviewer após cada task
-- Limite de retry: 3 reprovações → escalar pro usuário
-
-## /setup-projeto vs /feature
-
-| Aspecto | /setup-projeto | /feature |
-|---------|---------------|----------|
-| Input | `docs/PM/setup_projeto/` | `docs/PM/feat_nome/` |
-| Extração | TRD.md (técnico) | PRD.md (produto) |
-| SDD + Tasks | Sim (infra + DOC tasks) | Sim (feature tasks) |
-| Gera docs/Estrutura/ | Via tasks DOC | Não — atualiza via /merge-delta |
-| /merge-delta | Não se aplica | Obrigatório após /dev |
-| Pré-requisito | Nenhum (primeiro comando) | docs/Estrutura/ deve existir |
+# Instruções — Documentação e Specs
+
+> Regras para o agente ao trabalhar com a camada de documentação.
+> Complementa `copilot-instructions.md` com detalhes operacionais.
+
+## Skills e fluxo
+
+O pipeline é executado por skills atômicas, cada uma com seu arquivo em `.github/skills/`:
+
+```
+/setup-projeto → /extract → /design → /plan → /dev → /merge-delta
+```
+
+Cada skill tem pré-condições, passos e saídas documentados. **Sempre ler a skill antes de executar.**
+
+## Estado da pipeline (`.context.md`)
+
+Cada feature/setup tem um `.context.md` (YAML frontmatter) que controla o fluxo:
+
+```
+not_started → extract_done → approved → design_done → plan_done → dev_in_progress → dev_done → done
+```
+
+- **Apenas skills atualizam** `.context.md` — o usuário nunca edita manualmente
+- **Aprovação** acontece no início do `/design` (skill pergunta ao usuário)
+- Antes de executar qualquer skill, verificar status no `.context.md`
+
+## Extração (/extract)
+
+Cada tipo de projeto tem seu documento de extração:
+
+| Comando | Documento | Template | Foco |
+|---------|----------|---------|------|
+| `/setup-projeto` | TRD.md | `_templates/feature/TRD.template.md` | Stack, arquitetura, infra, modelo base |
+| `/feature` | PRD.md | `_templates/feature/PRD.template.md` | Regras de negócio, jornadas, telas |
+
+### Multi-agent no /extract
+
+| Agente | Modelo | Papel |
+|--------|--------|-------|
+| Reader (1 por arquivo) | Sonnet | Lê e cataloga 1 arquivo por vez, em paralelo |
+| Analyzer | Opus | Cruza fontes, detecta gaps/contradições, gera documento final |
+
+### Regras da extração
+
+- Ler TODOS arquivos em `docs/PM/{nome}/` (qualquer formato: .md, .txt, .sql, .html, .xml, .csv, .png, .pdf)
+- Categorias FIXAS do template — não inventar seções novas
+- Regras de negócio com IDs únicos e estáveis (RN-001, RN-002 — nunca renumerar)
+- Ambiguidades = BLOQUEANTES (workflow para até responder)
+- Nunca INFERIR regra de negócio — se não está explícito, é ambiguidade
+- Contradições entre arquivos → ambiguidade citando ambos
+- Rastreabilidade obrigatória: cada informação aponta pro arquivo fonte
+- Arquivo não identificável → registrar como NÃO IDENTIFICADO no extract-log, gerar ambiguidade
+- Gerar `.extract-log.md` com hash SHA-256 (8 chars) por arquivo
+
+### Re-extração
+
+- Compara hashes com `.extract-log.md` existente → NOVO / MODIFICADO / INALTERADO
+- Merge ADITIVO (nunca remove info de arquivos inalterados)
+- Novas regras continuam sequência de IDs (se último era RN-005, próximo é RN-006)
+
+## Design (/design)
+
+1. Verificar aprovação do PRD/TRD (perguntar ao usuário)
+2. Verificar ambiguidades — todas devem estar respondidas
+3. Ler PRD/TRD + `docs/Estrutura/` + `rules.md`
+4. Gerar SDD usando `_templates/feature/sdd.template.md`
+5. SDD deve ser **auto-contido** — coder lê APENAS SDD + task, nada mais
+6. Toda regra referencia seção do PRD/TRD (rastreabilidade)
+7. §9 Estratégia de Testes: definir framework, estrutura, CAs mapeados a testes
+8. §11 Delta Specs: obrigatório (ADDED/MODIFIED/REMOVED)
+9. Seções N/A permitidas em setup (§4-§8 podem ser N/A)
+
+## Planejamento (/plan)
+
+1. Ler SDD completo + `docs/Estrutura/` + `rules.md`
+2. Áreas são DINÂMICAS — determinadas pelo SDD, não pré-definidas
+3. Para cada área → gerar `{area}_tasks.md` usando `_templates/feature/tasks.template.md`
+4. Tasks em fases sequenciais com prioridade P1/P2/P3
+5. Cada task: ID (AREA-NNN), título, tamanho (S/M/L), arquivos, ref SDD §N, depende, testes
+6. Gerar `Progresso.md` com ordem de execução e paralelismos
+7. Em setup: área DOC obrigatória (8 tasks, 1 por doc de Estrutura)
+
+## Desenvolvimento (/dev)
+
+### Agents por área (perfis em `.github/agents/`)
+
+| Área | Agente | Stack padrão |
+|------|--------|-------------|
+| BANCO | DB Coder | PostgreSQL 16 |
+| BACK | Backend Coder | .NET 8 / C# |
+| FRONT | Frontend Coder | React + Fusion |
+| INFRA | Infra Coder | Docker |
+| DOC | Doc Writer | — |
+| Todas | Reviewer | — |
+
+### Loop de desenvolvimento
+
+```
+Por task: implement → test unit → fix → lint → commit → review → fix → review (max 3)
+Por fase: integration tests → fix
+Por feature: E2E tests (CAs) → fix → dev_done
+```
+
+### Regras
+
+- Implement + testes na mesma task (não separar)
+- Agente selecionado pelo prefixo: BACK-* → Backend Coder
+- Modelo por tamanho: S/M → Sonnet, L → Opus
+- 1 commit por task: `tipo(TASK-ID): descrição`
+- Quality gate validado pelo Reviewer após cada task
+- Limite de retry: 3 reprovações → escalar pro usuário
+
+## /setup-projeto vs /feature
+
+| Aspecto | /setup-projeto | /feature |
+|---------|---------------|----------|
+| Input | `docs/PM/setup_projeto/` | `docs/PM/feat_nome/` |
+| Extração | TRD.md (técnico) | PRD.md (produto) |
+| SDD + Tasks | Sim (infra + DOC tasks) | Sim (feature tasks) |
+| Gera docs/Estrutura/ | Via tasks DOC | Não — atualiza via /merge-delta |
+| /merge-delta | Não se aplica | Obrigatório após /dev |
+| Pré-requisito | Nenhum (primeiro comando) | docs/Estrutura/ deve existir |