spec-first-copilot 0.4.0 → 0.5.0-beta.0

package/templates/.github/skills/sf-setup-projeto/SKILL.md

@@ -1,123 +1,123 @@
----
-name: sf-setup-projeto
-description: |
-  Bootstrap do projeto. Cria contexto TRD, chama /sf-extract, para no checkpoint.
-  Trigger: /sf-setup-projeto
-author: GustavoMaritan
-version: 1.0.0
-date: 2026-04-08
----
-
-# Skill: /sf-setup-projeto
-
-> Orquestrador de bootstrap do projeto. Executa uma única vez.
-> Cria contexto TRD, chama `/extract` e para no checkpoint de aprovação.
-
-## Tipo
-Orquestrador (primeira etapa do pipeline)
-
-## Uso
-```
-/sf-setup-projeto
-```
-
-## Pré-condições
-
-| # | 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 templates vazios | Parar → "Setup já foi executado. Use /sf-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 estrutura
-```
-docs/Desenvolvimento/setup_projeto/
-├── .context.md        ← criado agora
-└── (TRD.md será criado pelo /extract)
-```
-
-### 2. Criar `.context.md`
-```yaml
----
-nome: "setup_projeto"
-tipo: "setup"
-documento: "TRD"
-pm_path: "docs/PM/setup_projeto/"
-status: "not_started"
-ultima_skill: "/sf-setup-projeto"
-atualizado_em: "{{ISO_DATETIME}}"
----
-```
-
-### 3. Sugerir /sf-discovery (RECOMENDADO)
-
-Antes de extrair, perguntar ao usuário:
-```
-📋 Insumos encontrados em docs/PM/setup_projeto/.
-
-Recomendo rodar /sf-discovery antes da extração para:
-  - Análise profunda dos insumos (parseia drawio, XML, SQL completo)
-  - Identificar gaps e contradições antes de estruturar
-  - Validar entendimento com você (mapa do sistema)
-
-Quer rodar /sf-discovery docs/PM/setup_projeto/ agora? (s/n)
-  Se SIM → rodar discovery, salvar discovery.md, depois continuar com extract
-  Se NÃO → pular direto para /sf-extract (ok para insumos simples)
-```
-
-Se o usuário aceitar:
-- Rodar `/sf-discovery docs/PM/setup_projeto/`
-- Aguardar conclusão — discovery.md salvo em `docs/Desenvolvimento/setup_projeto/`
-- Continuar para o passo 4
-
-### 4. Chamar `/sf-extract setup_projeto`
-O `/sf-extract` lê os insumos + discovery.md (se existir), gera o TRD e atualiza status para `extract_done`.
-
-### 5. CHECKPOINT — Parar e informar o usuário
-Mensagem ao usuário:
-```
-✅ TRD gerado em docs/Desenvolvimento/setup_projeto/TRD.md
-
-Revise o documento. Quando estiver satisfeito, execute:
-  /sf-design setup_projeto
-
-Se precisar adicionar mais insumos, coloque na pasta docs/PM/setup_projeto/
-e execute:
-  /sf-extract setup_projeto
-```
-
-**O orquestrador encerra aqui.** O restante do pipeline é responsabilidade do usuário chamar as skills atômicas na ordem:
-1. `/sf-design setup_projeto` (pergunta aprovação → gera SDD + docs/Estrutura/ + projetos.yaml)
-2. `/sf-plan setup_projeto` (gera tasks com campo Repo por task)
-3. `/sf-dev setup_projeto` (INFRA-001 cria/clona repos em projetos/, executa tasks nos repos corretos)
-
-## Saídas diretas desta skill
-- `docs/Desenvolvimento/setup_projeto/.context.md`
-- `docs/Desenvolvimento/setup_projeto/TRD.md` (via /extract)
-- `docs/Desenvolvimento/setup_projeto/.extract-log.md` (via /extract)
-
-## Saídas indiretas (skills subsequentes)
-- `sdd.md` (via /design)
-- `projetos.yaml` (via /sf-design — manifesto de repos)
-- `docs/Estrutura/` populado (via /design)
-- `*_tasks.md` + `Progresso.md` (via /plan)
-- `projetos/` com repos criados/clonados (via /sf-dev INFRA-001)
-
-## Erros
-
-| Erro | Ação |
-|------|------|
-| PM/setup_projeto/ não existe | Parar, instruir criação |
-| PM/setup_projeto/ vazio | Parar, listar formatos aceitos |
-| Estrutura/ já populado | Parar, sugerir /sf-feature |
-| Pipeline já iniciado | Parar, mostrar status atual do .context.md |
-
-## Notas
-- Esta skill roda **uma única vez** por projeto
-- docs/Estrutura/ é gerado pelo /sf-design (passo 3), não por tasks DOC
-- `projetos.yaml` é gerado pelo /sf-design (passo 3b) — mapeia serviços para repos
-- Repos são criados/clonados pelo /sf-dev (INFRA-001) dentro de `projetos/`
-- O `/merge-delta` NÃO se aplica ao setup (é criação, não atualização)
+---
+name: sf-setup-projeto
+description: |
+  Bootstrap do projeto. Cria contexto TRD, chama /sf-extract, para no checkpoint.
+  Trigger: /sf-setup-projeto
+author: GustavoMaritan
+version: 1.0.0
+date: 2026-04-08
+---
+
+# Skill: /sf-setup-projeto
+
+> Orquestrador de bootstrap do projeto. Executa uma única vez.
+> Cria contexto TRD, chama `/extract` e para no checkpoint de aprovação.
+
+## Tipo
+Orquestrador (primeira etapa do pipeline)
+
+## Uso
+```
+/sf-setup-projeto
+```
+
+## Pré-condições
+
+| # | Validação | Se falhar |
+|---|-----------|-----------|
+| 1 | `workspace/Input/setup_projeto/` existe | Parar → "Crie a pasta workspace/Input/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/` está vazio ou contém apenas templates vazios | Parar → "Setup já foi executado. Use /sf-feature para novas funcionalidades" |
+| 4 | `workspace/Output/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 estrutura
+```
+workspace/Output/setup_projeto/
+├── .context.md        ← criado agora
+└── (TRD.md será criado pelo /extract)
+```
+
+### 2. Criar `.context.md`
+```yaml
+---
+nome: "setup_projeto"
+tipo: "setup"
+documento: "TRD"
+pm_path: "workspace/Input/setup_projeto/"
+status: "not_started"
+ultima_skill: "/sf-setup-projeto"
+atualizado_em: "{{ISO_DATETIME}}"
+---
+```
+
+### 3. Sugerir /sf-discovery (RECOMENDADO)
+
+Antes de extrair, perguntar ao usuário:
+```
+📋 Insumos encontrados em workspace/Input/setup_projeto/.
+
+Recomendo rodar /sf-discovery antes da extração para:
+  - Análise profunda dos insumos (parseia drawio, XML, SQL completo)
+  - Identificar gaps e contradições antes de estruturar
+  - Validar entendimento com você (mapa do sistema)
+
+Quer rodar /sf-discovery workspace/Input/setup_projeto/ agora? (s/n)
+  Se SIM → rodar discovery, salvar discovery.md, depois continuar com extract
+  Se NÃO → pular direto para /sf-extract (ok para insumos simples)
+```
+
+Se o usuário aceitar:
+- Rodar `/sf-discovery workspace/Input/setup_projeto/`
+- Aguardar conclusão — discovery.md salvo em `workspace/Output/setup_projeto/`
+- Continuar para o passo 4
+
+### 4. Chamar `/sf-extract setup_projeto`
+O `/sf-extract` lê os insumos + discovery.md (se existir), gera o TRD e atualiza status para `extract_done`.
+
+### 5. CHECKPOINT — Parar e informar o usuário
+Mensagem ao usuário:
+```
+✅ TRD gerado em workspace/Output/setup_projeto/TRD.md
+
+Revise o documento. Quando estiver satisfeito, execute:
+  /sf-design setup_projeto
+
+Se precisar adicionar mais insumos, coloque na pasta workspace/Input/setup_projeto/
+e execute:
+  /sf-extract setup_projeto
+```
+
+**O orquestrador encerra aqui.** O restante do pipeline é responsabilidade do usuário chamar as skills atômicas na ordem:
+1. `/sf-design setup_projeto` (pergunta aprovação → gera SDD + docs/ + projetos.yaml)
+2. `/sf-plan setup_projeto` (gera tasks com campo Repo por task)
+3. `/sf-dev setup_projeto` (INFRA-001 cria/clona repos em projetos/, executa tasks nos repos corretos)
+
+## Saídas diretas desta skill
+- `workspace/Output/setup_projeto/.context.md`
+- `workspace/Output/setup_projeto/TRD.md` (via /extract)
+- `workspace/Output/setup_projeto/.extract-log.md` (via /extract)
+
+## Saídas indiretas (skills subsequentes)
+- `sdd.md` (via /design)
+- `projetos.yaml` (via /sf-design — manifesto de repos)
+- `docs/` populado (via /design)
+- `*_tasks.md` + `Progresso.md` (via /plan)
+- `projetos/` com repos criados/clonados (via /sf-dev INFRA-001)
+
+## Erros
+
+| Erro | Ação |
+|------|------|
+| workspace/Input/setup_projeto/ não existe | Parar, instruir criação |
+| workspace/Input/setup_projeto/ vazio | Parar, listar formatos aceitos |
+| docs/ já populado | Parar, sugerir /sf-feature |
+| Pipeline já iniciado | Parar, mostrar status atual do .context.md |
+
+## Notas
+- Esta skill roda **uma única vez** por projeto
+- docs/ é gerado pelo /sf-design (passo 3), não por tasks DOC
+- `projetos.yaml` é gerado pelo /sf-design (passo 3b) — mapeia serviços para repos
+- Repos são criados/clonados pelo /sf-dev (INFRA-001) dentro de `projetos/`
+- O `/merge-delta` NÃO se aplica ao setup (é criação, não atualização)

package/templates/{docs/_templates/estrutura/API.template.md → .github/templates/estrutura/apiContracts.template.md}

@@ -1,144 +1,151 @@
-# Convenções de API
-
-> Padrões globais para todas as APIs do sistema: versionamento, autenticação, paginação, erros.
-
----
-
-<!--
-=============================================================================
-INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
-=============================================================================
-
-ORIGEM: Gerado pelo /setup-projeto a partir do TRD §5.
-ATUALIZAÇÃO: /merge-delta quando features adicionam endpoints (Delta Specs do SDD §5 e §11).
-
-COMO GERAR:
-1. Ler TRD §5 (Convenções de API) — padrão geral, versionamento, autenticação
-2. Padrão geral e convenções são FIXOS após setup — definidos uma vez
-3. Catálogo de endpoints é DINÂMICO — cresce a cada feature
-4. Formatos de paginação, filtro e erro são FIXOS — toda API segue
-
-REGRAS:
-- Convenções são LEI — todo SDD §5 (endpoints) deve seguir estes padrões
-- Catálogo de endpoints atualizado a cada merge-delta
-- Mudanças em convenções (raro) devem gerar ADR
-- Rate limiting definido por categoria de endpoint, não individual
-
-=============================================================================
--->
-
-## Padrão Geral
-
-| Aspecto | Padrão |
-|---------|--------|
-| Estilo | <!-- REST / GraphQL / gRPC --> |
-| Formato | <!-- JSON / Protobuf --> |
-| Versionamento | <!-- /api/v1/ no path? Header? --> |
-| Autenticação | <!-- Bearer JWT? API Key? --> |
-| Content-Type | <!-- application/json --> |
-| Encoding | <!-- UTF-8 --> |
-
-## Convenções de Rotas
-
-| Operação | Método | Rota | Exemplo |
-|----------|--------|------|---------|
-| Listar | GET | `/api/v1/{recurso}` | |
-| Detalhar | GET | `/api/v1/{recurso}/:id` | |
-| Criar | POST | `/api/v1/{recurso}` | |
-| Atualizar completo | PUT | `/api/v1/{recurso}/:id` | |
-| Atualizar parcial | PATCH | `/api/v1/{recurso}/:id` | |
-| Remover/Inativar | DELETE | `/api/v1/{recurso}/:id` | |
-
-### Convenções de nomenclatura
-| Regra | Exemplo |
-|-------|---------|
-| Recursos no plural, kebab-case | `/api/v1/order-items` |
-| Ações não-CRUD como sub-recurso | `/api/v1/users/:id/activate` |
-| Filtros via query params | `/api/v1/users?status=active` |
-| Relações aninhadas (max 2 níveis) | `/api/v1/users/:id/orders` |
-
-## Paginação
-
-```json
-{
-  "data": [],
-  "meta": {
-    "page": 1,
-    "per_page": 20,
-    "total": 0,
-    "total_pages": 0
-  }
-}
-```
-
-Query params: `?page=1&per_page=20&sort=campo&order=asc`
-
-| Parâmetro | Default | Máximo | Descrição |
-|-----------|---------|--------|-----------|
-| `page` | 1 | — | Página atual |
-| `per_page` | 20 | <!-- Ex: 100 --> | Itens por página |
-| `sort` | — | — | Campo para ordenação |
-| `order` | `asc` | — | `asc` ou `desc` |
-
-## Filtros
-
-Query params: `?busca=termo&campo=valor`
-
-| Tipo de filtro | Formato | Exemplo |
-|----------------|---------|---------|
-| Igualdade | `?campo=valor` | `?status=ativo` |
-| Busca textual | `?busca=termo` | `?busca=joao` |
-| Range de data | `?de=YYYY-MM-DD&ate=YYYY-MM-DD` | `?de=2026-01-01&ate=2026-12-31` |
-| Múltiplos valores | `?campo=a,b,c` | `?status=ativo,pendente` |
-
-## Respostas de Erro
-
-```json
-{
-  "error": {
-    "code": "ERROR_CODE",
-    "message": "Mensagem legível para o usuário",
-    "details": [
-      { "field": "campo", "message": "Detalhe do erro" }
-    ]
-  }
-}
-```
-
-### Códigos HTTP
-
-| Código | Quando usar | Exemplo |
-|--------|-------------|---------|
-| 200 | Sucesso (GET, PUT, PATCH) | Recurso retornado/atualizado |
-| 201 | Criado com sucesso (POST) | Recurso criado, retorna o objeto |
-| 204 | Sucesso sem conteúdo (DELETE) | Recurso removido |
-| 400 | Dados inválidos (formato) | JSON malformado |
-| 401 | Não autenticado | Token ausente ou expirado |
-| 403 | Sem permissão | Papel sem acesso ao recurso |
-| 404 | Recurso não encontrado | ID inexistente |
-| 409 | Conflito (duplicidade) | Email já cadastrado |
-| 422 | Validação de negócio falhou | CPF inválido, regra RN-XXX violada |
-| 429 | Rate limit excedido | Muitas requisições |
-| 500 | Erro interno | Bug não tratado |
-
-### Códigos de erro do domínio
-
-| Código | Descrição | HTTP |
-|--------|-----------|------|
-| <!-- Ex: DUPLICATE_EMAIL --> | <!-- Email já cadastrado --> | <!-- 409 --> |
-
-## Catálogo de Endpoints
-
-> Atualizado a cada feature via /merge-delta. Visão consolidada de todas as APIs.
-
-| Método | Rota | Feature | Descrição |
-|--------|------|---------|-----------|
-|        |      |         |           |
-
----
-
-## Changelog
-
-| Data | Feature | Tipo | Descrição |
-|------|---------|------|-----------|
-|      |         |      |           |
+# Contratos de API
+
+> Padrões de endpoint, convenções de rotas, paginação, filtros, respostas de erro
+> e catálogo global. Contratos HTTP do sistema.
+> Autenticação detalhada e códigos de erro do domínio vivem em conventions.md.
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+ORIGEM: Gerado pelo /setup-projeto a partir do TRD §5 (API).
+ATUALIZAÇÃO: /merge-delta quando features adicionam endpoints
+(Delta Specs do SDD §5 e §11).
+
+COMO GERAR:
+1. Ler TRD §5 (Convenções de API) — padrão geral, versionamento
+2. Padrão geral e convenções são FIXOS após setup — definidos uma vez
+3. Catálogo de endpoints é DINÂMICO — cresce a cada feature via merge-delta
+4. Formatos de paginação, filtro e resposta de erro são FIXOS
+
+O QUE NÃO VAI AQUI:
+- Autenticação detalhada (hash, refresh, fluxo) → conventions.md
+- Autorização, roles, matriz de permissões → conventions.md
+- Códigos de erro do domínio → conventions.md
+- Rate limiting → conventions.md
+- CORS → conventions.md
+
+REGRAS:
+- Convenções são LEI — todo SDD §5 (endpoints) deve seguir
+- Catálogo atualizado a cada merge-delta
+- Mudanças em convenções (raro) devem gerar registro em decisions.md
+
+=============================================================================
+-->
+
+## Padrão Geral
+
+| Aspecto | Padrão |
+|---------|--------|
+| Estilo | <!-- REST / GraphQL / gRPC --> |
+| Formato | <!-- JSON / Protobuf --> |
+| Versionamento | <!-- /api/v1/ no path? Header? --> |
+| Content-Type | <!-- application/json --> |
+| Encoding | <!-- UTF-8 --> |
+
+> **Autenticação**: definida em [conventions.md → Autenticação](./conventions.md#autenticação).
+
+## Convenções de Rotas
+
+| Operação | Método | Rota | Exemplo |
+|----------|--------|------|---------|
+| Listar | GET | `/api/v1/{recurso}` | |
+| Detalhar | GET | `/api/v1/{recurso}/:id` | |
+| Criar | POST | `/api/v1/{recurso}` | |
+| Atualizar completo | PUT | `/api/v1/{recurso}/:id` | |
+| Atualizar parcial | PATCH | `/api/v1/{recurso}/:id` | |
+| Remover/Inativar | DELETE | `/api/v1/{recurso}/:id` | |
+
+### Convenções de nomenclatura
+
+| Regra | Exemplo |
+|-------|---------|
+| Recursos no plural, kebab-case | `/api/v1/order-items` |
+| Ações não-CRUD como sub-recurso | `/api/v1/users/:id/activate` |
+| Filtros via query params | `/api/v1/users?status=active` |
+| Relações aninhadas (max 2 níveis) | `/api/v1/users/:id/orders` |
+
+## Paginação
+
+```json
+{
+  "data": [],
+  "meta": {
+    "page": 1,
+    "per_page": 20,
+    "total": 0,
+    "total_pages": 0
+  }
+}
+```
+
+Query params: `?page=1&per_page=20&sort=campo&order=asc`
+
+| Parâmetro | Default | Máximo | Descrição |
+|-----------|---------|--------|-----------|
+| `page` | 1 | — | Página atual |
+| `per_page` | 20 | <!-- Ex: 100 --> | Itens por página |
+| `sort` | — | — | Campo para ordenação |
+| `order` | `asc` | — | `asc` ou `desc` |
+
+## Filtros
+
+Query params: `?busca=termo&campo=valor`
+
+| Tipo de filtro | Formato | Exemplo |
+|----------------|---------|---------|
+| Igualdade | `?campo=valor` | `?status=ativo` |
+| Busca textual | `?busca=termo` | `?busca=joao` |
+| Range de data | `?de=YYYY-MM-DD&ate=YYYY-MM-DD` | `?de=2026-01-01&ate=2026-12-31` |
+| Múltiplos valores | `?campo=a,b,c` | `?status=ativo,pendente` |
+
+## Respostas de Erro
+
+```json
+{
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "Mensagem legível para o usuário",
+    "details": [
+      { "field": "campo", "message": "Detalhe do erro" }
+    ]
+  }
+}
+```
+
+### Códigos HTTP
+
+| Código | Quando usar | Exemplo |
+|--------|-------------|---------|
+| 200 | Sucesso (GET, PUT, PATCH) | Recurso retornado/atualizado |
+| 201 | Criado com sucesso (POST) | Recurso criado, retorna o objeto |
+| 204 | Sucesso sem conteúdo (DELETE) | Recurso removido |
+| 400 | Dados inválidos (formato) | JSON malformado |
+| 401 | Não autenticado | Token ausente ou expirado |
+| 403 | Sem permissão | Papel sem acesso ao recurso |
+| 404 | Recurso não encontrado | ID inexistente |
+| 409 | Conflito (duplicidade) | Email já cadastrado |
+| 422 | Validação de negócio falhou | CPF inválido, regra RN-XXX violada |
+| 429 | Rate limit excedido | Muitas requisições |
+| 500 | Erro interno | Bug não tratado |
+
+> **Códigos de erro do domínio**: definidos em [conventions.md → Códigos de Erro do Domínio](./conventions.md#códigos-de-erro-do-domínio).
+
+## Catálogo de Endpoints
+
+> Atualizado a cada feature via /merge-delta. Visão consolidada de todas as APIs.
+
+| Método | Rota | Feature | Descrição |
+|--------|------|---------|-----------|
+|        |      |         |           |
+
+---
+
+## Changelog
+
+| Data | Feature | Tipo | Descrição |
+|------|---------|------|-----------|
+|      |         |      |           |