spec-first-copilot 0.7.0-beta.1 → 0.7.0

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