spec-first-copilot 0.1.0

package/templates/docs/_templates/feature/Progresso.template.md

@@ -0,0 +1,136 @@
+# Progresso — {{FEATURE}}
+
+> Visão consolidada do andamento da feature.
+> Organizado por **fases de entrega** — cada fase é um entregável independente.
+> Atualizado automaticamente pelo /dev a cada task concluída.
+
+---
+
+## Status Geral: `não iniciado`
+
+<!-- não iniciado → em desenvolvimento → em revisão → concluído → arquivado -->
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+COMO GERAR ESTE ARQUIVO:
+
+1. Ler PRD §11 (Fases de Entrega) para definir as fases
+2. Ler TODOS os *_tasks.md da feature
+3. Para cada FASE DE ENTREGA, listar as áreas e contagem de tasks
+4. A visão primária é POR FASE, não por área
+
+COMO ATUALIZAR:
+
+- O /dev atualiza após cada task concluída
+- Status por fase: ⬜ pendente → 🔄 em andamento → ✅ concluída
+- Fase concluída = todas tasks de todas áreas daquela fase estão [x]
+- Ao concluir uma fase: registrar no Histórico + abrir PR
+
+=============================================================================
+-->
+
+## Fases de Entrega
+
+| Fase | Nome | Prioridade | Entregável | Status | Tasks |
+|------|------|-----------|------------|--------|-------|
+| 1 | {{Nome}} | P1 | {{Entregável}} | ⬜ pendente | 0/{{N}} |
+| 2 | {{Nome}} | P1 | {{Entregável}} | ⬜ pendente | 0/{{N}} |
+| 3 | {{Nome}} | P2 | {{Entregável}} | ⬜ pendente | 0/{{N}} |
+
+---
+
+## Fase 1 — {{Nome}} [P1]
+
+> **Entregável**: {{O que o usuário pode usar}}
+> **Critério de done**: {{Testes E2E que devem passar}}
+> **Branch**: `feature/{{FEATURE}}_fase1`
+> **PR**: (a ser criado)
+
+### Tasks por área
+
+#### {{AREA_1}} ({{N}} tasks)
+
+| Task | Descrição | Tamanho | Repo | Status |
+|------|-----------|---------|------|--------|
+| AREA-001 | | S/M/L | {{repo}} | ⬜ |
+
+#### {{AREA_2}} ({{N}} tasks)
+
+| Task | Descrição | Tamanho | Repo | Status |
+|------|-----------|---------|------|--------|
+| AREA-001 | | S/M/L | {{repo}} | ⬜ |
+
+### Resumo Fase 1
+
+| Área | Total | Feitas | % |
+|------|-------|--------|---|
+| {{AREA_1}} | {{N}} | 0 | 0% |
+| {{AREA_2}} | {{N}} | 0 | 0% |
+| **Total Fase 1** | **{{N}}** | **0** | **0%** |
+
+---
+
+## Fase 2 — {{Nome}} [P1]
+
+> **Entregável**: {{...}}
+> **Depende de**: Fase 1 concluída
+
+<!-- Repetir mesma estrutura -->
+
+---
+
+## Totais Gerais
+
+| Fase | Total | Feitas | % |
+|------|-------|--------|---|
+| Fase 1 | {{N}} | 0 | 0% |
+| Fase 2 | {{N}} | 0 | 0% |
+| **Total** | **{{N}}** | **0** | **0%** |
+
+---
+
+## Ordem de Execução
+
+```
+Fase 1:
+  1. INFRA (setup de repos/ambiente)
+  2. BANCO (schema/migrations)
+  3. BACK (endpoints) ← pode paralelizar com FRONT após BANCO
+  4. FRONT (telas)
+  → PR Fase 1 + testes manuais + merge
+
+Fase 2:
+  1. BANCO (novas tabelas/migrations)
+  2. BACK (endpoints + regras)
+  3. FRONT (telas + integração)
+  → PR Fase 2 + testes manuais + merge
+```
+
+---
+
+## Histórico
+
+| Data | Evento | Detalhes |
+|------|--------|----------|
+| | Feature criada | PRD aprovado, SDD gerado |
+
+---
+
+## Pós-conclusão (por fase)
+
+- [ ] PR aberto com template detalhado
+- [ ] Ambiente local rodando para testes manuais
+- [ ] Testes automatizados passando (unit + integration + security)
+- [ ] Usuário aprovou e fez merge
+
+## Pós-conclusão (feature completa)
+
+- [ ] Todas fases concluídas e mergeadas
+- [ ] Mergear Delta Specs (SDD §11) nos docs de `docs/Estrutura/`
+- [ ] Atualizar `docs/Desenvolvimento/progresso.md` (visão global)
+- [ ] Atualizar `.ai/memory/napkin.md` se houver aprendizado relevante

package/templates/docs/_templates/feature/TRD.template.md

@@ -0,0 +1,200 @@
+# TRD — {{PROJETO}}
+## Technical Requirements Document
+
+> **Artefato gerado pela IA** a partir do processamento de todos os insumos em `docs/PM/setup_projeto/`.
+> Este é o checkpoint de extração para ESTRUTURAÇÃO do projeto.
+> Após aprovação, gera os documentos de `docs/Estrutura/`.
+
+---
+
+## Meta
+
+| Campo | Valor |
+|-------|-------|
+| Tipo | `setup-projeto` |
+| Status | `em extração` → `aguardando revisão` → `aprovado` |
+| Insumos processados | {{LISTA_INSUMOS}} |
+| Gerado em | |
+| Aprovado em | |
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+QUANDO USAR: Gerado pelo /extract (chamado via /setup-projeto). NUNCA por /feature.
+QUEM GERA: Agent Analyzer (Opus) a partir dos outputs dos Readers (Sonnet).
+
+COMO GERAR:
+1. Readers (Sonnet) leem cada arquivo de docs/PM/setup_projeto/ individualmente
+2. Analyzer (Opus) recebe todos os outputs e:
+   a. Consolida decisões técnicas, stack, arquitetura, modelo base
+   b. Cruza informações entre fontes — detecta contradições
+   c. Identifica gaps — decisões críticas sem resposta viram perguntas §9
+   d. Gera este documento seguindo as 10 seções fixas
+3. Focar em ESTRUTURA do sistema, não em features específicas
+4. Para cada informação, registrar DE QUAL insumo veio (§10)
+
+FORMATOS DE INSUMO (o que extrair de cada):
+- .txt, .md → visão, requisitos técnicos, decisões de arquitetura
+- .sql → modelo de dados base, convenções, tipos
+- .html → protótipos que revelam stack frontend
+- .xml (drawio) → diagramas de arquitetura, fluxos de infra
+- .json → configurações, schemas
+- Outros → extrair o que for relevante
+
+PÓS-APROVAÇÃO:
+- /design gera SDD a partir deste TRD
+- /plan gera tasks DOC que criam os 8 docs de docs/Estrutura/
+- Cada seção do TRD alimenta um doc específico:
+  §1 → Visao.md | §2 → Stack.md | §3 → Arquitetura.md
+  §4 → Modelo_Dados.md | §5 → API.md | §6 → Infraestrutura.md
+  §7 → Seguranca.md | §8 → Visao.md (roadmap de módulos)
+
+REGRAS DA EXTRAÇÃO:
+- Categorias FIXAS (as 10 seções abaixo) — não inventar novas
+- SEM texto narrativo — apenas informação estruturada
+- Ambiguidades são BLOQUEANTES (§9) — workflow para até responder
+- Nunca INFERIR decisão técnica — se não está explícito, perguntar
+- Contradição entre fontes → gerar pergunta em §9 citando ambos
+
+RE-EXTRAÇÃO:
+- Merge ADITIVO com TRD existente (não sobrescrever)
+- Seções afetadas marcadas com <!-- ATUALIZADO: re-extração ISO_DATE -->
+
+=============================================================================
+-->
+
+## 1. Visão do Sistema
+
+### O que é?
+<!-- Para que serve o sistema, qual problema resolve -->
+
+### Quem usa?
+
+| Ator | Papel | Permissões gerais |
+|------|-------|--------------------|
+|      |       |                    |
+
+### Integrações externas
+
+| Sistema | Direção | Descrição |
+|---------|---------|-----------|
+|         |         |           |
+
+### Restrições e premissas
+-
+
+---
+
+## 2. Stack e Tecnologias
+
+| Camada | Tecnologia | Versão | Justificativa extraída |
+|--------|-----------|--------|------------------------|
+|        |           |        |                        |
+
+### Ferramentas de desenvolvimento
+
+| Ferramenta | Para quê |
+|-----------|----------|
+|           |          |
+
+---
+
+## 3. Arquitetura
+
+### Containers identificados
+
+| Container | Tecnologia | Responsabilidade |
+|-----------|-----------|-----------------|
+|           |           |                 |
+
+### Padrões de comunicação
+-
+
+### Padrões de design
+-
+
+---
+
+## 4. Modelo de Dados Base
+
+> Extraído de: arquivos `.sql`, texto.
+
+| Tabela | Campos principais | Propósito |
+|--------|-------------------|-----------|
+|        |                   |           |
+
+### Convenções identificadas
+-
+
+---
+
+## 5. Convenções de API
+
+| Aspecto | Convenção extraída |
+|---------|-------------------|
+| Estilo | |
+| Formato | |
+| Versionamento | |
+| Autenticação | |
+| Paginação | |
+| Erros | |
+
+---
+
+## 6. Infraestrutura
+
+| Aspecto | Decisão extraída |
+|---------|-----------------|
+| Hospedagem | |
+| CI/CD | |
+| Containers | |
+| Ambientes | |
+
+---
+
+## 7. Segurança
+
+| Aspecto | Requisito extraído |
+|---------|-------------------|
+| Autenticação | |
+| Autorização | |
+| CORS | |
+| Rate limiting | |
+| LGPD | |
+| Auditoria | |
+
+---
+
+## 8. Módulos Planejados
+
+> Roadmap extraído dos insumos — ordem de implementação.
+
+| # | Módulo | Prioridade | Dependências |
+|---|--------|-----------|--------------|
+| 1 |        |           |              |
+
+---
+
+## 9. Ambiguidades e Perguntas
+
+> ⚠️ **BLOQUEANTE** — responder antes de gerar docs/Estrutura/.
+
+| # | Pergunta | Contexto | Resposta do usuário |
+|---|----------|----------|---------------------|
+| 1 | ⚠️ | | (aguardando) |
+
+---
+
+## 10. Rastreabilidade
+
+| Insumo | Tipo | O que foi extraído |
+|--------|------|--------------------|
+| `{{arquivo}}` | {{tipo}} | {{seções alimentadas}} |
+
+---
+
+> **Próximo passo**: Após aprovação, este TRD alimenta a geração de TODOS os documentos de `docs/Estrutura/`.

package/templates/docs/_templates/feature/backlog-extraido.template.md

@@ -0,0 +1,154 @@
+# Roadmap de Produto — {{NOME}}
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+QUANDO USAR: Gerado APENAS pelo /extract durante /setup-projeto.
+Nunca gerado em /feature.
+
+COMO GERAR:
+1. Durante a extração do TRD, o Analyzer encontra informações que não são infra
+   (regras de negócio, jornadas, telas, fluxos, entidades de domínio)
+2. Em vez de listar features soltas, ORGANIZAR em fases de entrega:
+   a. Identificar entidades/funcionalidades nos insumos
+   b. Mapear dependências entre elas (ex: agendamento depende de cadastro)
+   c. Agrupar em fases por dependência + complexidade
+   d. Definir entregável por fase (o que o usuário pode usar ao final)
+   e. Priorizar: P1 (base/core), P2 (operacional), P3 (crescimento)
+3. Para cada item, rastrear o arquivo fonte
+4. Sugerir UMA feature única com nome descritivo (ex: feat_mvp, feat_produto)
+
+PRINCÍPIO: Entregáveis contínuos — cada fase entrega valor e pode ir pra produção.
+Nunca "tudo ou nada". Pequeno e constante.
+
+CRITÉRIOS DE FASEAMENTO:
+- Fase 1 sempre = cadastros base / fundação (sem isso nada funciona)
+- Cada fase depende das anteriores (sequencial)
+- Cada fase tem entregável testável pelo usuário
+- Máximo 4-5 fases (se precisa de mais, agrupar melhor)
+
+USO POSTERIOR:
+- O usuário cria UMA feature (ex: /feature feat_mvp)
+- O /extract dessa feature gera PRD com as fases já sugeridas aqui
+- O /plan organiza tasks por fase de entrega × área
+
+=============================================================================
+-->
+
+> Roadmap faseado de produto extraído dos insumos do setup.
+> Organizado por fases de entrega incrementais — cada fase entrega valor e pode ir pra produção.
+> Fonte de verdade para criação de features via `/feature`.
+
+---
+
+## Feature sugerida: `{{FEATURE_NAME}}`
+
+> {{Descrição em 1-2 frases do produto completo}}
+
+---
+
+## Fase 1 — {{Nome}} [P1 — Fundação]
+
+> **Entregável**: {{O que o usuário pode fazer/ver ao final desta fase}}
+> **Critério de done**: {{Como validar que a fase está pronta}}
+
+### Funcionalidades
+
+| # | Funcionalidade | Tipo | Descrição | Fonte |
+|---|---------------|------|-----------|-------|
+| 1 | | CRUD / Feature / Config | | {{arquivo}} |
+
+### Entidades envolvidas
+
+| Entidade | Campos principais | Fonte |
+|----------|-------------------|-------|
+| | | |
+
+### Regras de negócio
+
+| ID | Regra | Fonte |
+|----|-------|-------|
+| RN-001 | | {{arquivo}} |
+
+### Jornadas de usuário
+
+| # | Jornada | Atores | Fonte |
+|---|---------|--------|-------|
+| 1 | | | |
+
+---
+
+## Fase 2 — {{Nome}} [P1 — Core Business]
+
+> **Entregável**: {{O que o usuário pode fazer/ver ao final desta fase}}
+> **Critério de done**: {{Como validar}}
+> **Depende de**: Fase 1
+
+### Funcionalidades
+
+| # | Funcionalidade | Tipo | Descrição | Fonte |
+|---|---------------|------|-----------|-------|
+| 1 | | | | |
+
+### Entidades envolvidas
+
+| Entidade | Campos principais | Fonte |
+|----------|-------------------|-------|
+| | | |
+
+### Regras de negócio
+
+| ID | Regra | Fonte |
+|----|-------|-------|
+| RN-NNN | | |
+
+### Jornadas de usuário
+
+| # | Jornada | Atores | Fonte |
+|---|---------|--------|-------|
+| 1 | | | |
+
+---
+
+## Fase 3 — {{Nome}} [P2 — Operacional]
+
+> **Entregável**: {{...}}
+> **Critério de done**: {{...}}
+> **Depende de**: Fase 2
+
+<!-- Repetir estrutura -->
+
+---
+
+## Fase 4 — {{Nome}} [P3 — Crescimento]
+
+> **Entregável**: {{...}}
+> **Critério de done**: {{...}}
+> **Depende de**: Fase 3
+
+<!-- Repetir estrutura -->
+
+---
+
+## Visão geral das fases
+
+| Fase | Nome | Prioridade | Entregável | Depende de |
+|------|------|-----------|------------|------------|
+| 1 | | P1 | | — |
+| 2 | | P1 | | Fase 1 |
+| 3 | | P2 | | Fase 2 |
+| 4 | | P3 | | Fase 3 |
+
+## Telas/fluxos identificados (por fase)
+
+| # | Tela/Fluxo | Fase | Fonte |
+|---|-----------|------|-------|
+| 1 | | | |
+
+---
+
+> **Próximo passo**: Criar a feature com `/feature {{FEATURE_NAME}}`
+> O /extract vai gerar o PRD usando este roadmap como referência.
+> O /plan vai organizar tasks por fase de entrega × área.

package/templates/docs/_templates/feature/context.template.md

@@ -0,0 +1,42 @@
+---
+nome: "{{NOME}}"
+tipo: "{{feature|setup}}"
+documento: "{{PRD|TRD}}"
+pm_path: "docs/PM/{{NOME}}/"
+status: "not_started"
+ultima_skill: ""
+atualizado_em: ""
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+CAMPOS:
+- nome: identificador da feature/setup (ex: feat_cadastro_cliente, setup_projeto)
+- tipo: "feature" para /feature, "setup" para /setup-projeto
+- documento: "PRD" para features, "TRD" para setup
+- pm_path: caminho relativo para a pasta de insumos no PM/
+- status: estado atual da pipeline (ver fluxo abaixo)
+- ultima_skill: qual skill alterou este arquivo por último
+- atualizado_em: data/hora ISO da última atualização
+
+FLUXO DE STATUS:
+  not_started → extract_done → approved → design_done → plan_done → dev_in_progress → dev_done → done
+
+QUEM ATUALIZA:
+- /setup-projeto ou /feature: cria o arquivo com status not_started
+- /extract: not_started → extract_done
+- /design: extract_done → approved → design_done (aprovação via pergunta ao usuário)
+- /plan: design_done → plan_done
+- /dev: plan_done → dev_in_progress → dev_done
+- /merge-delta: dev_done → done (apenas para features, não para setup)
+
+REGRAS:
+- Nunca pular etapas no fluxo de status
+- Nunca editar manualmente — apenas skills atualizam este arquivo
+- Se status não corresponde ao esperado, a skill deve parar e avisar
+
+=============================================================================
+-->

package/templates/docs/_templates/feature/extract-log.template.md

@@ -0,0 +1,38 @@
+# Extract Log — {{NOME}}
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+QUANDO USAR: Criado pelo /extract na primeira extração. Atualizado em re-extrações.
+QUEM GERA: Agent Analyzer (Opus) ao final da extração.
+
+COMO GERAR:
+1. Cada extração gera uma nova seção com timestamp
+2. Para cada arquivo processado: nome, hash SHA-256 (8 chars), classificação, status, seções alimentadas
+3. Classificação: contexto de re-extração (NOVO, MODIFICADO, INALTERADO)
+4. Status: resultado da leitura (extraído, parcial, não identificado)
+5. Seções alimentadas: quais §N do PRD/TRD foram preenchidas a partir deste arquivo
+
+REGRAS:
+- Hashes são SHA-256 truncados em 8 caracteres
+- Arquivo .gitkeep é sempre ignorado
+- Arquivos INALTERADOS aparecem no log mas com seções "—"
+- Append-only: nunca remover extrações anteriores do log
+
+CLASSIFICAÇÕES POSSÍVEIS:
+- NOVO: arquivo não existia no log anterior
+- MODIFICADO: hash diferente do log anterior
+- INALTERADO: hash igual ao log anterior
+- NÃO IDENTIFICADO: Reader não conseguiu extrair conteúdo (binário, corrompido, formato desconhecido)
+- PARCIAL: Reader extraiu algo mas com limitações (imagem sem OCR, PDF escaneado)
+
+=============================================================================
+-->
+
+## Extração 1 — {{ISO_DATETIME}}
+
+| Arquivo | Hash | Classificação | Status | Seções alimentadas |
+|---------|------|---------------|--------|--------------------|
+| `{{arquivo}}` | {{hash_8}} | NOVO | extraído | §N, §N |

package/templates/docs/_templates/feature/projetos.template.yaml

@@ -0,0 +1,73 @@
+# projetos.yaml — Manifesto de Repositórios
+#
+# =============================================================================
+# INSTRUÇÕES PARA O AGENTE
+# =============================================================================
+#
+# QUANDO CRIAR: Gerado pelo /design (passo 3, setup) após definir a arquitetura.
+# QUEM GERA: Agent Architect (Opus), baseado no TRD §3 (Arquitetura) e §6 (Infra).
+#
+# COMO GERAR:
+# 1. Ler TRD §3 Arquitetura → identificar quais serviços existem (api, worker, web, etc.)
+# 2. Para cada serviço, definir: nome do repo, path local, áreas de task, stack
+# 3. Se o repo já existe no GitHub, marcar existing: true
+# 4. Se é novo, marcar existing: false (será criado pelo /dev INFRA-001)
+#
+# REGRAS:
+# - Todo serviço identificado no TRD §3 DEVE ter uma entrada
+# - O campo `areas` define quais prefixos de task escrevem nesse repo
+# - Uma área NÃO pode pertencer a dois repos (mapeamento 1:1)
+# - BANCO pode ir junto com api (se usa EF migrations) ou separado (se repo de migrations)
+# - O campo `stack` deve ser consistente com docs/Estrutura/Stack.md
+# - O `org` é a organização/user do GitHub
+# =============================================================================
+
+# Organização/usuário no GitHub
+org: "{{GITHUB_ORG}}"
+
+# Nome base do projeto (usado como prefixo dos repos)
+project: "{{PROJECT_NAME}}"
+
+# Repositórios
+repos:
+  # Exemplo: API backend
+  api:
+    repo: "{{GITHUB_ORG}}/{{PROJECT_NAME}}-api"    # nome completo do repo
+    path: "projetos/api"                             # path local (relativo à raiz)
+    existing: false                                   # true = clonar, false = criar
+    areas: [BACK, BANCO]                             # áreas de task que escrevem aqui
+    stack: ".NET 8"                                   # stack principal
+    branch_prefix: "feature/"                         # prefixo de branches de feature
+
+  # Exemplo: Worker/background jobs
+  # worker:
+  #   repo: "{{GITHUB_ORG}}/{{PROJECT_NAME}}-worker"
+  #   path: "projetos/worker"
+  #   existing: false
+  #   areas: [BACK]                                  # worker tem tasks BACK separadas
+  #   stack: ".NET 8"
+  #   branch_prefix: "feature/"
+
+  # Exemplo: Frontend web
+  # web:
+  #   repo: "{{GITHUB_ORG}}/{{PROJECT_NAME}}-web"
+  #   path: "projetos/web"
+  #   existing: false
+  #   areas: [FRONT]
+  #   stack: "React"
+  #   branch_prefix: "feature/"
+
+  # Exemplo: App mobile
+  # mobile:
+  #   repo: "{{GITHUB_ORG}}/{{PROJECT_NAME}}-mobile"
+  #   path: "projetos/mobile"
+  #   existing: false
+  #   areas: [MOBILE]
+  #   stack: "React Native"
+  #   branch_prefix: "feature/"
+
+# Notas:
+# - projetos/ está no .gitignore do projeto-base (contém repos independentes)
+# - Cada repo tem seu próprio .git, CI/CD, e deploy
+# - O projeto-base é o "cérebro" — specs, docs, pipeline
+# - Os repos em projetos/ são o "corpo" — código implementado