spec-first-copilot 0.7.0 → 0.8.0-beta.2

package/templates/.github/skills/sf-session-finish/SKILL.md

@@ -1,93 +1,93 @@
----
-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
----
-
-# /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.
-
-## Passos
-
-### 1. Levantar estado atual
-
-Para cada `.context.md` em `workspace/Output/*/`:
-- Status atual + Progresso.md (% concluído, fase atual)
-- Tasks em andamento
-
-### 2. Verificar working tree dos repos
-
-Para cada repo em `projetos/`:
-```bash
-cd projetos/{repo}
-git status --short
-git log --oneline -3
-```
-- Se working tree sujo → avisar (sugerir commit antes de pausar)
-
-### 3. Atualizar `.ai/memory/napkin.md`
-
-Atualizar seção `## Sessão Atual` com:
-- Data, o que foi feito, o que estava em andamento
-- Decisões tomadas, armadilhas encontradas
-
-### 4. Gerar resumo de retomada
-
-Criar/atualizar `workspace/Output/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
-  - `workspace/Output/retomada.md` — ponto de retomada
-
-Para retomar:
-  1. Ler retomada.md
-  2. Seguir os passos listados
-```
-
-## Notas
-- Não modifica .context.md (status da pipeline não muda)
-- Não faz commit automático — avisa se working tree sujo
-- `retomada.md` é sobrescrito a cada /sf-session-finish (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
+---
+
+# /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.
+
+## Passos
+
+### 1. Levantar estado atual
+
+Para cada `.context.md` em `workspace/Output/*/`:
+- Status atual + Progresso.md (% concluído, fase atual)
+- Tasks em andamento
+
+### 2. Verificar working tree dos repos
+
+Para cada repo em `projetos/`:
+```bash
+cd projetos/{repo}
+git status --short
+git log --oneline -3
+```
+- Se working tree sujo → avisar (sugerir commit antes de pausar)
+
+### 3. Atualizar `.ai/memory/napkin.md`
+
+Atualizar seção `## Sessão Atual` com:
+- Data, o que foi feito, o que estava em andamento
+- Decisões tomadas, armadilhas encontradas
+
+### 4. Gerar resumo de retomada
+
+Criar/atualizar `workspace/Output/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
+  - `workspace/Output/retomada.md` — ponto de retomada
+
+Para retomar:
+  1. Ler retomada.md
+  2. Seguir os passos listados
+```
+
+## Notas
+- Não modifica .context.md (status da pipeline não muda)
+- Não faz commit automático — avisa se working tree sujo
+- `retomada.md` é sobrescrito a cada /sf-session-finish (ponto atual, não histórico)

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

@@ -1,192 +1,192 @@
-
-# /sf-start <nome>
-
-Orquestrador único de entrada do pipeline SFW v4.
-Mesma lógica pra qualquer scope (bootstrap, feature, bug, task técnica).
-Distinção "bootstrap vs feature" é derivada automaticamente da existência de `docs/`.
-
-## Argumento
-
-`<nome>` = nome do scope no Input (título da page no Confluence, nome da pasta no filesystem).
-Usuário nomeia livremente. Convenção sugerida (opcional):
-
-- Bootstrap/setup: `app_<nome_projeto>`, `bootstrap`, `setup_<nome>`
-- Features: `feat_<nome_descritivo>`
-- Bugs: `bug_<nome_descritivo>`
-- Tasks técnicas: `task_<nome_descritivo>`
-
-Framework aceita qualquer nome. Convenção é pra organização visual no Input.
-
-## Execução
-
-Siga EXATAMENTE os passos em ordem. Leia o arquivo completo antes de agir.
-
-### Passo 1 — Detectar first_run
-
-| Condição | Significado |
-|----------|-------------|
-| `docs/` ausente ou vazio | **first_run = true** — bootstrap do projeto. `/sf-design` vai criar `docs/` + `projetos.yaml` a partir do TRD |
-| `docs/` populado (≥1 arquivo) | **first_run = false** — feature/incremento. `docs/` atualizado via `/sf-merge-docs` no fim do `/sf-dev` |
-
-Registrar no `.context.md` (Passo 4). **Imutável** depois de criado.
-
-### Passo 2 — Carregar insumos do backend (`/sf-load`)
-
-**SEMPRE executar**, independente do Input já existir local.
-`/sf-load` é idempotente — se já existe, detecta INALTERADO e não sobrescreve.
-
-```
-Executar /sf-load {nome}
-```
-
-Seguir TODOS os passos do `/sf-load` (ver `.github/skills/sf-load/SKILL.md`):
-- Ler `sfw.config.yml` pra saber o adapter
-- Buscar scope `{nome}` no backend
-- Descer recursivamente até o último nível
-- Materializar TUDO em `workspace/Input/{nome}/`
-- Registrar no `.ai/load-log.md`
-
-**Se `sfw.config.yml` não existe**: projeto é 100% local.
-Pular `/sf-load` e ir direto pro Passo 3. Usuário deve ter colocado insumos
-manualmente em `workspace/Input/{nome}/`.
-
-### Passo 3 — Validar pré-condições
-
-| # | Validação | Se falhar |
-|---|-----------|-----------|
-| 1 | `<nome>` foi informado como argumento | Parar → "Informe o nome. Ex: /sf-start feat_cadastro_cliente" |
-| 2 | `workspace/Input/{nome}/` existe e contém ≥1 arquivo | Parar → "Nenhum insumo encontrado. Verifique o backend ou crie workspace/Input/{nome}/ manualmente" |
-| 3 | `workspace/Output/{nome}/.context.md` não existe OU tem status `not_started` | Se avançado → "Scope já em andamento. Status: {status}. Para continuar de onde parou, rode a skill do próximo estágio" |
-
-### Passo 4 — Criar estrutura de Output + `.context.md`
-
-1. Criar `workspace/Output/{nome}/` se não existir
-2. Criar `.context.md` usando template `.github/templates/feature/context.template.md`:
-
-```yaml
----
-nome: "{nome}"
-first_run: {true|false}      # derivado do Passo 1 (SEM aspas, bool real)
-prd_existe: false             # /sf-extract preenche
-trd_existe: false             # /sf-extract preenche
-prd_aprovado: false           # usuário (PM) marca true após revisar PRD
-trd_aprovado: false           # usuário (dev) marca true após revisar TRD
-areas_tocadas: []             # /sf-design preenche a partir dos GATEs do TRD
-input_path: "workspace/Input/{nome}/"
-status: "not_started"
-ultima_skill: "/sf-start"
-atualizado_em: "{{ISO_DATETIME}}"
----
-```
-
-### Passo 5 — Executar `/sf-discovery` (OBRIGATÓRIO em v4)
-
-> **Breaking v4**: discovery deixou de ser opcional. Força entendimento dos
-> insumos antes da extração. Reduz iteração de fix em PRD/TRD.
-
-```
-Executar /sf-discovery workspace/Input/{nome}/
-```
-
-Seguir `.github/skills/sf-discovery/SKILL.md`. Output: `workspace/Output/{nome}/sf-discovery.md`.
-
-Atualizar `.context.md`:
-```yaml
-status: "discovery_done"
-ultima_skill: "/sf-discovery"
-```
-
-### Passo 6 — Executar `/sf-extract`
-
-```
-Executar /sf-extract {nome}
-```
-
-Seguir `.github/skills/sf-extract/SKILL.md`. Pode gerar **PRD, TRD ou ambos** — dependendo
-dos insumos. Outputs:
-
-- `workspace/Output/{nome}/PRD.md` — se insumos têm conteúdo de produto
-- `workspace/Output/{nome}/TRD.md` — se insumos têm conteúdo técnico
-- `workspace/Output/{nome}/.extract-log.md` — hashes + destino por arquivo
-
-`/sf-extract` atualiza `.context.md`:
-```yaml
-status: "extract_done"
-prd_existe: {true|false}
-trd_existe: {true|false}
-```
-
-### Passo 7 — CHECKPOINT DUPLO — aprovação PM + dev
-
-Após `/sf-extract`, o orquestrador **para** e informa o usuário. Há 2 aprovações
-paralelas (ordem irrelevante entre elas, ambas precisam antes de prosseguir):
-
-```
-/sf-extract completou. Próximos passos:
-
-┌─ [PM APROVA PRD]  (se prd_existe=true)
-│    1. Abra workspace/Output/{nome}/PRD.md
-│    2. Revise as 13 seções
-│    3. Responda ambiguidades em §12 (coluna `Resposta`)
-│    4. Quando aprovar, edite .context.md: prd_aprovado: true
-│
-├─ [DEV APROVA TRD]  (se trd_existe=true)
-│    1. Abra workspace/Output/{nome}/TRD.md
-│    2. Revise as 11 seções (§Sistema + GATEs §Área-*)
-│    3. Responda ambiguidades em §10 (coluna `Resposta`)
-│    4. Quando aprovar, edite .context.md: trd_aprovado: true
-│
-└─ Quando as aprovações aplicáveis estiverem true, execute:
-     /sf-design {nome}
-```
-
-**Cenários**:
-- `prd_existe=true + trd_existe=true` (maioria): precisa PM aprovar PRD E dev aprovar TRD
-- `prd_existe=true + trd_existe=false`: só PM precisa aprovar PRD
-- `prd_existe=false + trd_existe=true`: só dev precisa aprovar TRD
-- `prd_existe=false + trd_existe=false`: extract reportou erro (não é possível chegar aqui)
-
-### Passo 8 — Encerrar orquestrador
-
-Após o CHECKPOINT do Passo 7, `/sf-start` **encerra**. O usuário revisa e aprova
-manualmente os docs, depois chama `/sf-design {nome}`.
-
-**Pipeline completo (para referência do usuário)**:
-
-```
-/sf-start {nome}                   ← ORQUESTRADOR (este skill)
-   ├─ /sf-load (se backend configurado)
-   ├─ /sf-discovery (obrigatório)
-   ├─ /sf-extract → gera PRD e/ou TRD
-   └─ STOP: aguarda aprovação PM (PRD) + aprovação dev (TRD)
-
-[manual: revisar PRD.md, marcar prd_aprovado=true]
-[manual: revisar TRD.md, marcar trd_aprovado=true]
-
-/sf-design {nome}
-   ├─ first_run=true: cria docs/ (5 arquivos) + projetos.yaml
-   ├─ sempre: gera specs/{nome}/ (brief, contracts, scenarios)
-   └─ status → design_done
-
-/sf-plan {nome}
-   └─ gera specs/{nome}/tasks.md + workspace/Output/{nome}/Progresso.md
-   └─ status → plan_done
-
-/sf-dev {nome}  (ou /sf-dev {nome} --fase 1)
-   ├─ first_run=true: INFRA-001 cria/clona repos em projetos/
-   ├─ implementa tasks com loop (coder → review → security review)
-   ├─ E2E + aprovação
-   ├─ se feature (first_run=false): chama /sf-merge-docs automaticamente
-   └─ status → dev_done → done
-```
-
-## Notas
-
-- `/sf-load` é sempre o 1º passo real — garante Input sincronizado com backend
-- Se não há `sfw.config.yml`, projeto é 100% local e `/sf-load` é pulado
-- `first_run` é imutável após criação do `.context.md`
-- `docs/` em first_run: NASCE no `/sf-design` (não no `/sf-extract`) a partir do TRD
-- `projetos.yaml` é gerado pelo `/sf-design` em first_run
-- **Aprovação dupla**: mesmo em time pequeno (dev = PM), mantém as 2 marcações —
-  "fluxo fica mais claro" vence cerimônia-mínima (decisão de v4)
-- Ambiguidades em §12 PRD / §10 TRD são BLOQUEANTES — `/sf-design` não avança sem respostas
+
+# /sf-start <nome>
+
+Orquestrador único de entrada do pipeline SFW v4.
+Mesma lógica pra qualquer scope (bootstrap, feature, bug, task técnica).
+Distinção "bootstrap vs feature" é derivada automaticamente da existência de `docs/`.
+
+## Argumento
+
+`<nome>` = nome do scope no Input (título da page no Confluence, nome da pasta no filesystem).
+Usuário nomeia livremente. Convenção sugerida (opcional):
+
+- Bootstrap/setup: `app_<nome_projeto>`, `bootstrap`, `setup_<nome>`
+- Features: `feat_<nome_descritivo>`
+- Bugs: `bug_<nome_descritivo>`
+- Tasks técnicas: `task_<nome_descritivo>`
+
+Framework aceita qualquer nome. Convenção é pra organização visual no Input.
+
+## Execução
+
+Siga EXATAMENTE os passos em ordem. Leia o arquivo completo antes de agir.
+
+### Passo 1 — Detectar first_run
+
+| Condição | Significado |
+|----------|-------------|
+| `docs/` ausente ou vazio | **first_run = true** — bootstrap do projeto. `/sf-design` vai criar `docs/` + `projetos.yaml` a partir do TRD |
+| `docs/` populado (≥1 arquivo) | **first_run = false** — feature/incremento. `docs/` atualizado via `/sf-merge-docs` no fim do `/sf-dev` |
+
+Registrar no `.context.md` (Passo 4). **Imutável** depois de criado.
+
+### Passo 2 — Carregar insumos do backend (`/sf-load`)
+
+**SEMPRE executar**, independente do Input já existir local.
+`/sf-load` é idempotente — se já existe, detecta INALTERADO e não sobrescreve.
+
+```
+Executar /sf-load {nome}
+```
+
+Seguir TODOS os passos do `/sf-load` (ver `.github/skills/sf-load/SKILL.md`):
+- Ler `sfw.config.yml` pra saber o adapter
+- Buscar scope `{nome}` no backend
+- Descer recursivamente até o último nível
+- Materializar TUDO em `workspace/Input/{nome}/`
+- Registrar no `.ai/load-log.md`
+
+**Se `sfw.config.yml` não existe**: projeto é 100% local.
+Pular `/sf-load` e ir direto pro Passo 3. Usuário deve ter colocado insumos
+manualmente em `workspace/Input/{nome}/`.
+
+### Passo 3 — Validar pré-condições
+
+| # | Validação | Se falhar |
+|---|-----------|-----------|
+| 1 | `<nome>` foi informado como argumento | Parar → "Informe o nome. Ex: /sf-start feat_cadastro_cliente" |
+| 2 | `workspace/Input/{nome}/` existe e contém ≥1 arquivo | Parar → "Nenhum insumo encontrado. Verifique o backend ou crie workspace/Input/{nome}/ manualmente" |
+| 3 | `workspace/Output/{nome}/.context.md` não existe OU tem status `not_started` | Se avançado → "Scope já em andamento. Status: {status}. Para continuar de onde parou, rode a skill do próximo estágio" |
+
+### Passo 4 — Criar estrutura de Output + `.context.md`
+
+1. Criar `workspace/Output/{nome}/` se não existir
+2. Criar `.context.md` usando template `.github/templates/feature/context.template.md`:
+
+```yaml
+---
+nome: "{nome}"
+first_run: {true|false}      # derivado do Passo 1 (SEM aspas, bool real)
+prd_existe: false             # /sf-extract preenche
+trd_existe: false             # /sf-extract preenche
+prd_aprovado: false           # usuário (PM) marca true após revisar PRD
+trd_aprovado: false           # usuário (dev) marca true após revisar TRD
+areas_tocadas: []             # /sf-design preenche a partir dos GATEs do TRD
+input_path: "workspace/Input/{nome}/"
+status: "not_started"
+ultima_skill: "/sf-start"
+atualizado_em: "{{ISO_DATETIME}}"
+---
+```
+
+### Passo 5 — Executar `/sf-discovery` (OBRIGATÓRIO em v4)
+
+> **Breaking v4**: discovery deixou de ser opcional. Força entendimento dos
+> insumos antes da extração. Reduz iteração de fix em PRD/TRD.
+
+```
+Executar /sf-discovery workspace/Input/{nome}/
+```
+
+Seguir `.github/skills/sf-discovery/SKILL.md`. Output: `workspace/Output/{nome}/sf-discovery.md`.
+
+Atualizar `.context.md`:
+```yaml
+status: "discovery_done"
+ultima_skill: "/sf-discovery"
+```
+
+### Passo 6 — Executar `/sf-extract`
+
+```
+Executar /sf-extract {nome}
+```
+
+Seguir `.github/skills/sf-extract/SKILL.md`. Pode gerar **PRD, TRD ou ambos** — dependendo
+dos insumos. Outputs:
+
+- `workspace/Output/{nome}/PRD.md` — se insumos têm conteúdo de produto
+- `workspace/Output/{nome}/TRD.md` — se insumos têm conteúdo técnico
+- `workspace/Output/{nome}/.extract-log.md` — hashes + destino por arquivo
+
+`/sf-extract` atualiza `.context.md`:
+```yaml
+status: "extract_done"
+prd_existe: {true|false}
+trd_existe: {true|false}
+```
+
+### Passo 7 — CHECKPOINT DUPLO — aprovação PM + dev
+
+Após `/sf-extract`, o orquestrador **para** e informa o usuário. Há 2 aprovações
+paralelas (ordem irrelevante entre elas, ambas precisam antes de prosseguir):
+
+```
+/sf-extract completou. Próximos passos:
+
+┌─ [PM APROVA PRD]  (se prd_existe=true)
+│    1. Abra workspace/Output/{nome}/PRD.md
+│    2. Revise as 13 seções
+│    3. Responda ambiguidades em §12 (coluna `Resposta`)
+│    4. Quando aprovar, edite .context.md: prd_aprovado: true
+│
+├─ [DEV APROVA TRD]  (se trd_existe=true)
+│    1. Abra workspace/Output/{nome}/TRD.md
+│    2. Revise as 11 seções (§Sistema + GATEs §Área-*)
+│    3. Responda ambiguidades em §10 (coluna `Resposta`)
+│    4. Quando aprovar, edite .context.md: trd_aprovado: true
+│
+└─ Quando as aprovações aplicáveis estiverem true, execute:
+     /sf-design {nome}
+```
+
+**Cenários**:
+- `prd_existe=true + trd_existe=true` (maioria): precisa PM aprovar PRD E dev aprovar TRD
+- `prd_existe=true + trd_existe=false`: só PM precisa aprovar PRD
+- `prd_existe=false + trd_existe=true`: só dev precisa aprovar TRD
+- `prd_existe=false + trd_existe=false`: extract reportou erro (não é possível chegar aqui)
+
+### Passo 8 — Encerrar orquestrador
+
+Após o CHECKPOINT do Passo 7, `/sf-start` **encerra**. O usuário revisa e aprova
+manualmente os docs, depois chama `/sf-design {nome}`.
+
+**Pipeline completo (para referência do usuário)**:
+
+```
+/sf-start {nome}                   ← ORQUESTRADOR (este skill)
+   ├─ /sf-load (se backend configurado)
+   ├─ /sf-discovery (obrigatório)
+   ├─ /sf-extract → gera PRD e/ou TRD
+   └─ STOP: aguarda aprovação PM (PRD) + aprovação dev (TRD)
+
+[manual: revisar PRD.md, marcar prd_aprovado=true]
+[manual: revisar TRD.md, marcar trd_aprovado=true]
+
+/sf-design {nome}
+   ├─ first_run=true: cria docs/ (5 arquivos) + projetos.yaml
+   ├─ sempre: gera specs/{nome}/ (brief, contracts, scenarios)
+   └─ status → design_done
+
+/sf-plan {nome}
+   └─ gera specs/{nome}/tasks.md + workspace/Output/{nome}/Progresso.md
+   └─ status → plan_done
+
+/sf-dev {nome}  (ou /sf-dev {nome} --fase 1)
+   ├─ first_run=true: INFRA-001 cria/clona repos em projetos/
+   ├─ implementa tasks com loop (coder → review → security review)
+   ├─ E2E + aprovação
+   ├─ se feature (first_run=false): chama /sf-merge-docs automaticamente
+   └─ status → dev_done → done
+```
+
+## Notas
+
+- `/sf-load` é sempre o 1º passo real — garante Input sincronizado com backend
+- Se não há `sfw.config.yml`, projeto é 100% local e `/sf-load` é pulado
+- `first_run` é imutável após criação do `.context.md`
+- `docs/` em first_run: NASCE no `/sf-design` (não no `/sf-extract`) a partir do TRD
+- `projetos.yaml` é gerado pelo `/sf-design` em first_run
+- **Aprovação dupla**: mesmo em time pequeno (dev = PM), mantém as 2 marcações —
+  "fluxo fica mais claro" vence cerimônia-mínima (decisão de v4)
+- Ambiguidades em §12 PRD / §10 TRD são BLOQUEANTES — `/sf-design` não avança sem respostas