spec-first-copilot 0.3.0 → 0.4.0

package/templates/.github/skills/sf-plan/SKILL.md

@@ -1,178 +1,178 @@
----
-name: sf-plan
-description: |
-  Planejamento. Gera tasks por fase de entrega e área.
-  Trigger: /sf-plan
-author: GustavoMaritan
-version: 1.0.0
-date: 2026-04-08
----
-
-# Skill: /sf-plan
-
-> Skill atômica de planejamento. Lê SDD e gera tasks por área + Progresso.
-
-## Tipo
-Atômica — Single-agent
-
-## Uso
-```
-/sf-plan <nome>
-```
-Exemplo: `/sf-plan feat_cadastro_cliente`
-
----
-
-## Agente
-
-| Campo | Valor |
-|-------|-------|
-| **Papel** | Planejador técnico — decompõe especificação em tasks atômicas, ordenadas e com dependências explícitas |
-| **Modelo** | Opus |
-| **Comportamento** | Metódico e exaustivo. Cada task deve ser auto-contida (coder lê SDD §N + task, nada mais). Prioriza ordem de execução correta sobre paralelismo. Nunca cria task sem referência ao SDD. |
-
----
-
-## Pré-condições
-
-| # | Validação | Se falhar |
-|---|-----------|-----------|
-| 1 | Argumento `nome` foi informado | Parar → "Informe o nome. Ex: /sf-plan feat_cadastro_cliente" |
-| 2 | `docs/Desenvolvimento/{nome}/.context.md` existe com status `design_done` | Se anterior → "Execute /sf-design {nome} primeiro". Se posterior → "Tasks já foram geradas (status: {status})" |
-| 3 | `sdd.md` existe na pasta | Parar → "SDD não encontrado. Execute /sf-design {nome}" |
-
-## Passos
-
-### 1. Ler contexto
-- Ler `.context.md` → validar status
-- Ler `sdd.md` completo
-- Ler `projetos.yaml` (manifesto de repos — mapeamento área → repo)
-- Ler `docs/Estrutura/` (Stack, Arquitetura — para convenções por área)
-- Ler `docs/Desenvolvimento/rules.md` (padrões de código, commit, branch)
-- Carregar template `docs/_templates/feature/tasks.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: `/sf-dev feat_nome --fase 1`
-
-### 3. Identificar áreas afetadas (por fase)
-Para cada fase de entrega, mapear seções do SDD para áreas de tasks:
-
-| Seção do SDD | Área | Condição |
-|-------------|------|----------|
-| §3 Modelo de dados | BANCO | Se há entidades/migrations |
-| §5 Endpoints API | BACK | Se há endpoints definidos |
-| §6 Componentes e telas | FRONT | Se há UI especificada |
-| §8 Integrações externas | INFRA | Se há infra/serviços externos |
-| Outras | MOBILE, DEVOPS, etc. | Conforme necessidade do SDD |
-
-> **Nota**: Área DOC NÃO existe mais no setup. docs/Estrutura/ é gerado pelo /sf-design (passo 3).
-> DOC só aparece em features se houver necessidade explícita de documentação adicional.
-
-Áreas são **dinâmicas** — só cria o que o SDD exige. Não criar área vazia.
-
-**Á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 /sf-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 identificada, gerar `{area}_tasks.md`.
-Tasks são agrupadas por **fase de entrega** (do PRD §11), não só por fase técnica.
-
-**Estrutura de cada task:**
-```markdown
-- [ ] **AREA-NNN**: Título descritivo [Tamanho]
-  - Fase: {{N}} — {{Nome da fase de entrega}}
-  - Repo: `{{nome_repo}}` (de projetos.yaml)
-  - Arquivos: `caminho/do/arquivo.ext` (relativo à raiz do repo)
-  - SDD: §N.N — Referência específica
-  - Depende: AREA-NNN (ou — se não depende)
-```
-
-**Regras de decomposição:**
-1. Cada task é **atômica** — implementável sem consultar nada além de SDD §N + task
-2. **Repo obrigatório** — consultar `projetos.yaml` para mapear área → repo. Caminhos de arquivo são relativos à raiz do repo
-3. Tamanhos realistas: **S** (<30min), **M** (30min-2h), **L** (2h+)
-4. Se uma task é L, avaliar se pode ser quebrada em M+S
-5. IDs sequenciais por área: BANCO-001, BANCO-002, BACK-001, BACK-002
-6. IDs nunca reutilizados — se uma task for removida, o ID é aposentado
-7. Dependências explícitas — inclusive cross-area (FRONT-004 depende BACK-003)
-8. Prioridades por fase: **P1** (bloqueia outros), **P2** (importante), **P3** (nice-to-have)
-
-**Organização em fases (sequenciais dentro da área):**
-
-| Área | Fases típicas (adaptar ao SDD) |
-|------|-------------------------------|
-| BANCO | Schema/Migrations → Índices/Constraints → Seeds |
-| BACK | Setup/Config → DTOs/Validações → Repository/Service → Controller → Testes |
-| FRONT | Setup/Rotas → Componentes base → Telas → Integração API → Polish/UX |
-| INFRA | Provisioning → Config → Deploy → Monitoramento |
-| DOC | Gerar docs/Estrutura/ a partir do TRD |
-
-### 5. Gerar `Progresso.md`
-Usando template `docs/_templates/feature/Progresso.template.md`:
-
-- Resumo por Área × Fase com contagem de tasks
-- Status por fase: ⬜ pendente | 🔄 em andamento | ✅ concluída
-- **Ordem de execução** com paralelismos:
-  ```
-  1. BANCO Fase 1 (Schema) — primeiro sempre
-  2. BANCO Fase 2 + BACK Fase 1 — podem paralelizar
-  3. BACK Fase 2-3 — sequencial
-  4. FRONT Fase 1-2 — pode iniciar após BACK Fase 3
-  ...
-  ```
-- Totais por área e geral
-- Checklist pós-conclusão (merge delta, atualizar progresso global, napkin)
-
-### 6. Atualizar progresso global
-Adicionar entrada em `docs/Desenvolvimento/progresso.md`:
-
-```markdown
-| {nome} | plan_done | BANCO: 0/N | BACK: 0/N | FRONT: 0/N |
-```
-
-### 7. Atualizar `.context.md`
-```yaml
-status: "plan_done"
-ultima_skill: "/sf-plan"
-atualizado_em: "{{ISO_DATETIME}}"
-```
-
----
-
-## Saídas
-
-| Arquivo | Descrição |
-|---------|-----------|
-| `{area}_tasks.md` | 1 arquivo por área (dinâmico: banco_tasks.md, back_tasks.md, etc.) |
-| `Progresso.md` | Dashboard da feature com ordem de execução |
-| `progresso.md` (global) | Atualizado com nova feature |
-| `.context.md` | Atualizado com status `plan_done` |
-
-## Pós-condições
-- Cada task é auto-contida com referência ao SDD
-- Dependências resolvíveis (não há ciclos)
-- Ordem de execução definida no Progresso.md
-- Feature pronta para `/dev`
-
-## Erros
-
-| Erro | Ação |
-|------|------|
-| Nome não informado | Parar, mostrar exemplo |
-| Status não é design_done | Parar, sugerir skill correspondente |
-| SDD não encontrado | Parar, sugerir /sf-design |
-| SDD com seções vazias obrigatórias | Parar, listar o que falta — sugerir voltar ao /sf-design |
-| Dependência circular detectada | Parar, reportar o ciclo e sugerir reorganização |
+---
+name: sf-plan
+description: |
+  Planejamento. Gera tasks por fase de entrega e área.
+  Trigger: /sf-plan
+author: GustavoMaritan
+version: 1.0.0
+date: 2026-04-08
+---
+
+# Skill: /sf-plan
+
+> Skill atômica de planejamento. Lê SDD e gera tasks por área + Progresso.
+
+## Tipo
+Atômica — Single-agent
+
+## Uso
+```
+/sf-plan <nome>
+```
+Exemplo: `/sf-plan feat_cadastro_cliente`
+
+---
+
+## Agente
+
+| Campo | Valor |
+|-------|-------|
+| **Papel** | Planejador técnico — decompõe especificação em tasks atômicas, ordenadas e com dependências explícitas |
+| **Modelo** | Opus |
+| **Comportamento** | Metódico e exaustivo. Cada task deve ser auto-contida (coder lê SDD §N + task, nada mais). Prioriza ordem de execução correta sobre paralelismo. Nunca cria task sem referência ao SDD. |
+
+---
+
+## Pré-condições
+
+| # | Validação | Se falhar |
+|---|-----------|-----------|
+| 1 | Argumento `nome` foi informado | Parar → "Informe o nome. Ex: /sf-plan feat_cadastro_cliente" |
+| 2 | `docs/Desenvolvimento/{nome}/.context.md` existe com status `design_done` | Se anterior → "Execute /sf-design {nome} primeiro". Se posterior → "Tasks já foram geradas (status: {status})" |
+| 3 | `sdd.md` existe na pasta | Parar → "SDD não encontrado. Execute /sf-design {nome}" |
+
+## Passos
+
+### 1. Ler contexto
+- Ler `.context.md` → validar status
+- Ler `sdd.md` completo
+- Ler `projetos.yaml` (manifesto de repos — mapeamento área → repo)
+- Ler `docs/Estrutura/` (Stack, Arquitetura — para convenções por área)
+- Ler `docs/Desenvolvimento/rules.md` (padrões de código, commit, branch)
+- Carregar template `docs/_templates/feature/tasks.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: `/sf-dev feat_nome --fase 1`
+
+### 3. Identificar áreas afetadas (por fase)
+Para cada fase de entrega, mapear seções do SDD para áreas de tasks:
+
+| Seção do SDD | Área | Condição |
+|-------------|------|----------|
+| §3 Modelo de dados | BANCO | Se há entidades/migrations |
+| §5 Endpoints API | BACK | Se há endpoints definidos |
+| §6 Componentes e telas | FRONT | Se há UI especificada |
+| §8 Integrações externas | INFRA | Se há infra/serviços externos |
+| Outras | MOBILE, DEVOPS, etc. | Conforme necessidade do SDD |
+
+> **Nota**: Área DOC NÃO existe mais no setup. docs/Estrutura/ é gerado pelo /sf-design (passo 3).
+> DOC só aparece em features se houver necessidade explícita de documentação adicional.
+
+Áreas são **dinâmicas** — só cria o que o SDD exige. Não criar área vazia.
+
+**Á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 /sf-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 identificada, gerar `{area}_tasks.md`.
+Tasks são agrupadas por **fase de entrega** (do PRD §11), não só por fase técnica.
+
+**Estrutura de cada task:**
+```markdown
+- [ ] **AREA-NNN**: Título descritivo [Tamanho]
+  - Fase: {{N}} — {{Nome da fase de entrega}}
+  - Repo: `{{nome_repo}}` (de projetos.yaml)
+  - Arquivos: `caminho/do/arquivo.ext` (relativo à raiz do repo)
+  - SDD: §N.N — Referência específica
+  - Depende: AREA-NNN (ou — se não depende)
+```
+
+**Regras de decomposição:**
+1. Cada task é **atômica** — implementável sem consultar nada além de SDD §N + task
+2. **Repo obrigatório** — consultar `projetos.yaml` para mapear área → repo. Caminhos de arquivo são relativos à raiz do repo
+3. Tamanhos realistas: **S** (<30min), **M** (30min-2h), **L** (2h+)
+4. Se uma task é L, avaliar se pode ser quebrada em M+S
+5. IDs sequenciais por área: BANCO-001, BANCO-002, BACK-001, BACK-002
+6. IDs nunca reutilizados — se uma task for removida, o ID é aposentado
+7. Dependências explícitas — inclusive cross-area (FRONT-004 depende BACK-003)
+8. Prioridades por fase: **P1** (bloqueia outros), **P2** (importante), **P3** (nice-to-have)
+
+**Organização em fases (sequenciais dentro da área):**
+
+| Área | Fases típicas (adaptar ao SDD) |
+|------|-------------------------------|
+| BANCO | Schema/Migrations → Índices/Constraints → Seeds |
+| BACK | Setup/Config → DTOs/Validações → Repository/Service → Controller → Testes |
+| FRONT | Setup/Rotas → Componentes base → Telas → Integração API → Polish/UX |
+| INFRA | Provisioning → Config → Deploy → Monitoramento |
+| DOC | Gerar docs/Estrutura/ a partir do TRD |
+
+### 5. Gerar `Progresso.md`
+Usando template `docs/_templates/feature/Progresso.template.md`:
+
+- Resumo por Área × Fase com contagem de tasks
+- Status por fase: ⬜ pendente | 🔄 em andamento | ✅ concluída
+- **Ordem de execução** com paralelismos:
+  ```
+  1. BANCO Fase 1 (Schema) — primeiro sempre
+  2. BANCO Fase 2 + BACK Fase 1 — podem paralelizar
+  3. BACK Fase 2-3 — sequencial
+  4. FRONT Fase 1-2 — pode iniciar após BACK Fase 3
+  ...
+  ```
+- Totais por área e geral
+- Checklist pós-conclusão (merge delta, atualizar progresso global, napkin)
+
+### 6. Atualizar progresso global
+Adicionar entrada em `docs/Desenvolvimento/progresso.md`:
+
+```markdown
+| {nome} | plan_done | BANCO: 0/N | BACK: 0/N | FRONT: 0/N |
+```
+
+### 7. Atualizar `.context.md`
+```yaml
+status: "plan_done"
+ultima_skill: "/sf-plan"
+atualizado_em: "{{ISO_DATETIME}}"
+```
+
+---
+
+## Saídas
+
+| Arquivo | Descrição |
+|---------|-----------|
+| `{area}_tasks.md` | 1 arquivo por área (dinâmico: banco_tasks.md, back_tasks.md, etc.) |
+| `Progresso.md` | Dashboard da feature com ordem de execução |
+| `progresso.md` (global) | Atualizado com nova feature |
+| `.context.md` | Atualizado com status `plan_done` |
+
+## Pós-condições
+- Cada task é auto-contida com referência ao SDD
+- Dependências resolvíveis (não há ciclos)
+- Ordem de execução definida no Progresso.md
+- Feature pronta para `/dev`
+
+## Erros
+
+| Erro | Ação |
+|------|------|
+| Nome não informado | Parar, mostrar exemplo |
+| Status não é design_done | Parar, sugerir skill correspondente |
+| SDD não encontrado | Parar, sugerir /sf-design |
+| SDD com seções vazias obrigatórias | Parar, listar o que falta — sugerir voltar ao /sf-design |
+| Dependência circular detectada | Parar, reportar o ciclo e sugerir reorganização |

package/templates/.github/skills/{sf-pausar → sf-session-finish}/SKILL.md

@@ -1,120 +1,120 @@
----
-name: sf-pausar
-description: |
-  Encerrar sessão. Salva estado, atualiza napkin, gera retomada.md.
-  Trigger: /sf-pausar
-author: GustavoMaritan
-version: 1.0.0
-date: 2026-04-08
----
-
-# Skill: /sf-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.
-
-## Tipo
-Utilitária — roda a qualquer momento
-
-## Uso
-```
-/sf-pausar
-```
-
----
-
-## Passos
-
-### 1. Levantar estado atual de cada feature/setup
-
-Para cada `.context.md` em `docs/Desenvolvimento/*/`:
-- Ler status atual
-- Ler Progresso.md (se existir) → % concluído, fase atual
-- Identificar tasks em andamento (`- [ ]` com dependências resolvidas)
-
-### 2. Verificar working tree dos repos
-
-Para cada repo em `projetos/`:
-```bash
-cd projetos/{repo}
-git status --short
-git log --oneline -3
-```
-- Listar mudanças não commitadas
-- Listar branches ativas
-- Se há working tree sujo → avisar (sugerir commit antes de pausar)
-
-### 3. Atualizar `.ai/memory/napkin.md`
-
-Adicionar/atualizar seção `## Sessão Atual` com:
-- Data da sessão
-- O que foi feito (tasks concluídas, fases entregues)
-- O que estava em andamento (task atual, bloqueios)
-- Decisões tomadas durante a sessão
-- Armadilhas encontradas (se houver novos aprendizados)
-
-### 4. Gerar resumo de retomada
-
-Criar/atualizar `docs/Desenvolvimento/retomada.md`:
-
-```markdown
-# Ponto de Retomada — {{DATA}}
-
-> Gerado pelo /sf-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 /sf-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 na próxima sessão:
-  1. Ler retomada.md
-  2. Seguir os passos listados em "Para retomar"
-```
-
----
-
-## Saídas
-
-| Arquivo | Descrição |
-|---------|-----------|
-| `.ai/memory/napkin.md` | Sessão atual atualizada |
-| `docs/Desenvolvimento/retomada.md` | Ponto de retomada com estado completo |
-
-## Notas
-
-- Não modifica .context.md (o status da pipeline não muda ao pausar)
-- Não faz commit automático — se tem working tree sujo, avisa mas não força
-- Pode ser chamada a qualquer momento, não só no final do dia
-- O arquivo `retomada.md` é sobrescrito a cada /sf-pausar (é ponto atual, não histórico)
+---
+name: sf-session-finish
+description: |
+  Encerrar sessão. Salva estado, atualiza napkin, gera retomada.md.
+  Trigger: /sf-session-finish
+author: GustavoMaritan
+version: 1.0.0
+date: 2026-04-08
+---
+
+# Skill: /sf-session-finish
+
+> Encerra a sessão de trabalho de forma organizada.
+> Consolida estado, atualiza memória, gera ponto de retomada para a próxima sessão.
+
+## Tipo
+Utilitária — roda a qualquer momento
+
+## Uso
+```
+/sf-session-finish
+```
+
+---
+
+## Passos
+
+### 1. Levantar estado atual de cada feature/setup
+
+Para cada `.context.md` em `docs/Desenvolvimento/*/`:
+- Ler status atual
+- Ler Progresso.md (se existir) → % concluído, fase atual
+- Identificar tasks em andamento (`- [ ]` com dependências resolvidas)
+
+### 2. Verificar working tree dos repos
+
+Para cada repo em `projetos/`:
+```bash
+cd projetos/{repo}
+git status --short
+git log --oneline -3
+```
+- Listar mudanças não commitadas
+- Listar branches ativas
+- Se há working tree sujo → avisar (sugerir commit antes de pausar)
+
+### 3. Atualizar `.ai/memory/napkin.md`
+
+Adicionar/atualizar seção `## Sessão Atual` com:
+- Data da sessão
+- O que foi feito (tasks concluídas, fases entregues)
+- O que estava em andamento (task atual, bloqueios)
+- Decisões tomadas durante a sessão
+- Armadilhas encontradas (se houver novos aprendizados)
+
+### 4. Gerar resumo de retomada
+
+Criar/atualizar `docs/Desenvolvimento/retomada.md`:
+
+```markdown
+# Ponto de Retomada — {{DATA}}
+
+> Gerado pelo /sf-session-finish. 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 /sf-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 na próxima sessão:
+  1. Ler retomada.md
+  2. Seguir os passos listados em "Para retomar"
+```
+
+---
+
+## Saídas
+
+| Arquivo | Descrição |
+|---------|-----------|
+| `.ai/memory/napkin.md` | Sessão atual atualizada |
+| `docs/Desenvolvimento/retomada.md` | Ponto de retomada com estado completo |
+
+## Notas
+
+- Não modifica .context.md (o status da pipeline não muda ao pausar)
+- Não faz commit automático — se tem working tree sujo, avisa mas não força
+- Pode ser chamada a qualquer momento, não só no final do dia
+- O arquivo `retomada.md` é sobrescrito a cada /sf-session-finish (é ponto atual, não histórico)