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

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

@@ -0,0 +1,437 @@
+---
+name: sf-onboard
+description: |
+  Brownfield onboarding. Clona repo existente em projetos/, lê o código e gera
+  TRD + docs/ + projetos.yaml sem PRD. Cartógrafo descritivo (não arquiteto).
+  Trigger: /sf-onboard <git-url> [--branch=X] [--tag=Y] [--name=Z]
+author: GustavoMaritan
+version: 1.0.0
+date: 2026-05-11
+---
+
+# /sf-onboard $ARGUMENTS
+
+Skill atômica de **brownfield onboarding**. Clona um repositório existente em
+`projetos/`, lê o código e gera **TRD + `docs/` + `projetos.yaml`** sem PRD.
+
+**Filosofia**: cartógrafo, não arquiteto. Mapeia stack, padrões e uso sem julgar.
+Coders futuros SEGUEM o que já existe — propostas de mudança entram como
+features explícitas do dev.
+
+## Argumento
+
+```
+/sf-onboard <git-url> [--branch=<branch>] [--tag=<tag>] [--name=<scope-name>]
+```
+
+| Param | Default | Descrição |
+|-------|---------|-----------|
+| `<git-url>` | (obrigatório) | URL git clonável (https/ssh). Auth é pré-req do user (SSH key/PAT configurado) |
+| `--branch` | `main` | Branch a clonar |
+| `--tag` | — | Tag específica (mutuamente exclusivo com `--branch`) |
+| `--name` | inferido do URL | Nome do scope. Default: `onboard_<repo-name>` |
+
+**Multi-repo** (poly-repo): re-executar a skill N vezes, uma por repo. Cada
+execução adiciona uma entry em `projetos.yaml` e merge aditivo no TRD.
+
+## Multi-agent
+
+| Agente | Modelo | Papel |
+|--------|--------|-------|
+| **DB Reader** | Sonnet | Lê migrations, schemas, ORMs → fragmento §Área-DB |
+| **Backend Reader** | Sonnet | Lê routes/controllers/services → fragmento §Área-Backend + §6 Integrações |
+| **Frontend Reader** | Sonnet | Lê rotas, componentes, state → fragmento §Área-Frontend |
+| **Infra Reader** | Sonnet | Lê Dockerfile, CI/CD, k8s, configs → fragmento §Área-Infra |
+| **Dependency Reader** | Sonnet | Lê package.json / *.csproj / pom.xml / go.mod → fragmento §1.1 Stack |
+| **Security Reader** | Sonnet | Lê auth/authz/secrets/headers → fragmento §7 Segurança |
+| **Patterns Reader** | Sonnet | Identifica padrões observados (estrutura, naming, error handling, validação, testes, logging) → fragmento §1.6 |
+| **Analyzer** | Opus | Consolida TODOS fragmentos → TRD completo + `docs/` + `projetos.yaml` |
+
+## Pré-condições
+
+| # | Validação | Se falhar |
+|---|-----------|-----------|
+| 1 | `<git-url>` informado | Parar → "Informe a URL do repositório. Ex: /sf-onboard https://github.com/org/app.git" |
+| 2 | `git` instalado no PATH (`git --version`) | Parar → "Git não encontrado no PATH" |
+| 3 | **Auth git pré-verificada** (ver passo 0) | Parar com instrução específica conforme tipo de URL |
+| 4 | `--branch` e `--tag` não usados juntos | Parar → "Use --branch OU --tag, não ambos" |
+| 5 | Scope `onboard_<repo>` não está em `analyzing` | Se sim → "Onboarding anterior incompleto. Rode novamente pra retomar" |
+
+### Passo 0 — Verificar autenticação ANTES de clonar
+
+Detectar tipo de URL e testar auth proativamente. Falhar cedo com mensagem
+clara é melhor que esperar o `git clone` quebrar sem contexto.
+
+**Detectar tipo de URL**:
+
+| Padrão | Tipo |
+|--------|------|
+| `git@<host>:<org>/<repo>.git` | SSH |
+| `ssh://git@<host>/...` | SSH |
+| `https://<host>/...` | HTTPS |
+
+**Se SSH** — testar agente + conectividade:
+
+```bash
+# 1. ssh-agent rodando com chave carregada?
+ssh-add -l
+#    Saída esperada: linha(s) com fingerprint. Se "The agent has no identities",
+#    user precisa rodar `ssh-add ~/.ssh/id_ed25519` (ou similar).
+#    Se "Could not open a connection to your authentication agent",
+#    user precisa iniciar o ssh-agent.
+
+# 2. Host autenticável? (extrair host da URL, ex: github.com)
+ssh -T -o StrictHostKeyChecking=accept-new -o BatchMode=yes git@<host>
+#    GitHub retorna exit 1 com "Hi <user>! You've successfully authenticated"
+#    GitLab/Bitbucket têm mensagens análogas.
+#    Exit 255 ou "Permission denied (publickey)" → chave não autorizada.
+```
+
+**Se HTTPS** — testar credential helper ou GH CLI:
+
+```bash
+# 1. Git credential helper configurado?
+git config --get credential.helper
+#    Vazio → user usa GH CLI ou vai ser perguntado credencial no clone.
+
+# 2. (Se host = github.com) GH CLI autenticado?
+gh auth status --hostname github.com
+#    Exit 0 + "Logged in to github.com" → ok
+#    Exit 1 → não logado
+
+# 3. Alternativa: tentar ls-remote sem clonar (mais leve que clone)
+GIT_TERMINAL_PROMPT=0 git ls-remote --heads <git-url> HEAD
+#    Exit 0 → auth ok
+#    Exit ≠ 0 + "Authentication failed" → credencial ausente/inválida
+#    Exit ≠ 0 + "could not read Username" → terminal prompt bloqueado, sem credential helper
+```
+
+**Mensagens de erro específicas**:
+
+| Cenário | Mensagem |
+|---------|----------|
+| SSH sem ssh-agent | "ssh-agent não está rodando. Inicie com `eval $(ssh-agent)` (Linux/Mac) ou `Start-Service ssh-agent` (Windows)" |
+| SSH agent vazio | "Nenhuma chave SSH carregada. Rode `ssh-add ~/.ssh/id_ed25519` (ajuste o nome se diferente)" |
+| SSH host nega | "Chave SSH não autorizada em `<host>`. Verifique se a chave pública está cadastrada em `<host>/settings/keys` (GitHub) ou equivalente" |
+| HTTPS sem helper nem GH CLI | "Credencial HTTPS não configurada. Opções: (1) `gh auth login` se host=github.com; (2) configurar credential helper (`git config --global credential.helper manager`); (3) usar URL SSH (`git@<host>:...`)" |
+| HTTPS GH CLI deslogado | "GH CLI não autenticado. Rode `gh auth login` e tente novamente" |
+| `ls-remote` falha por motivo desconhecido | "Falha ao acessar o repo: `<stderr do ls-remote>`. Verifique a URL e suas credenciais" |
+
+**Sucesso**: log breve "Auth OK ({tipo})" e prosseguir para o Passo 1.
+
+> **Nota Windows/PowerShell**: comandos `ssh-add`, `ssh -T`, `gh`, `git`
+> assumem disponíveis no PATH. Em ambientes sem ssh-agent nativo (Windows
+> antigo), instruir uso do GH CLI ou HTTPS+PAT.
+
+## Passos
+
+### 1. Resolver nome do scope e path
+
+- `<repo-name>` = último segmento da URL sem `.git`
+  - Ex: `https://github.com/org/app-legado.git` → `app-legado`
+- `scope = --name || "onboard_<repo-name>"`
+- `path = "projetos/<repo-name>"`
+
+Se `--branch` ausente e `--tag` ausente → branch = `main`.
+
+### 2. Detectar re-onboard
+
+| Condição | Comportamento |
+|----------|---------------|
+| `workspace/Output/<scope>/.context.md` não existe | **Primeira vez** — criar tudo do zero |
+| `.context.md` existe com tipo=onboard | **Re-onboard** — pull no clone existente, merge aditivo |
+| `.context.md` existe com tipo≠onboard | Parar → "Scope <scope> já é usado por pipeline normal. Use --name pra dar outro nome" |
+
+### 3. Clonar / atualizar o repositório
+
+**Primeira vez**:
+```bash
+git clone --branch <branch> <git-url> projetos/<repo-name>
+# OU se --tag:
+git clone --depth 1 --branch <tag> <git-url> projetos/<repo-name>
+```
+
+**Re-onboard**:
+```bash
+cd projetos/<repo-name>
+git fetch
+git checkout <branch-ou-tag>
+git pull --ff-only
+```
+
+Capturar `commit_hash` resultante (`git rev-parse HEAD`) — vai pro snapshot.
+
+### 4. Criar `.context.md`
+
+```yaml
+---
+nome: "<scope>"
+tipo: "onboard"
+first_run: true
+prd_existe: false
+trd_existe: false
+prd_aprovado: false
+trd_aprovado: false
+areas_tocadas: []
+input_path: "workspace/Input/<scope>/"
+repo_url: "<git-url>"
+repo_branch: "<branch-ou-tag>"
+repo_path: "projetos/<repo-name>"
+status: "cloned"
+ultima_skill: "/sf-onboard"
+atualizado_em: "<ISO_DATETIME>"
+---
+```
+
+### 5. Gerar snapshot rastreável
+
+Criar `workspace/Input/<scope>/code-snapshot.md`:
+
+```markdown
+# Code Snapshot — <repo-name>
+
+**Repo**: <git-url>
+**Branch/Tag**: <branch-ou-tag>
+**Commit**: <commit_hash>
+**Onboard em**: <ISO_DATETIME>
+
+## Arquivos lidos
+
+| Arquivo | Hash | Tipo | Classificação | Lido por |
+|---------|------|------|---------------|----------|
+| `package.json` | a3f29c1d | dependency | NOVO | Dependency Reader |
+| `src/api/UserController.cs` | b8e221f0 | source | NOVO | Backend Reader, Patterns Reader |
+| ... | | | | |
+```
+
+**Regras**:
+- Hash SHA-256 truncado em 8 chars
+- Classificação: NOVO / MODIFICADO / INALTERADO (vs snapshot anterior)
+- Re-onboard: append nova seção `## Snapshot N — <ISO_DATETIME>` (append-only)
+- Ignorar: `node_modules/`, `bin/`, `obj/`, `dist/`, `build/`, `.git/`, `vendor/`, `target/`, lock files binários
+
+### 6. Atualizar status → analyzing
+
+```yaml
+status: "analyzing"
+atualizado_em: "<ISO_DATETIME>"
+```
+
+### 7. Disparar readers em paralelo
+
+Cada Reader recebe:
+- Path do clone: `projetos/<repo-name>/`
+- Lista de arquivos relevantes pra área (pre-filtrado por glob)
+- Snapshot anterior (se re-onboard) pra detectar MODIFICADO
+
+| Reader | Globs (exemplos) | Output |
+|--------|------------------|--------|
+| **Dependency** | `package.json`, `*.csproj`, `pom.xml`, `go.mod`, `requirements.txt`, `Pipfile`, `Gemfile`, `composer.json` | Linguagem, framework, versões, libs principais |
+| **DB** | `**/migrations/**`, `**/Migrations/**`, `**/*.sql`, `**/schema.prisma`, `**/models/**`, `**/Entities/**` | Tabelas, colunas, índices, FKs, ORM detectado |
+| **Backend** | `**/Controllers/**`, `**/routes/**`, `**/api/**`, `**/handlers/**`, `**/services/**`, `**/usecases/**` | Endpoints (método+rota+auth), services, integrações |
+| **Frontend** | `**/pages/**`, `**/routes/**`, `**/components/**`, `**/store/**`, `**/hooks/**` | Rotas, componentes, state lib, design system |
+| **Infra** | `Dockerfile*`, `docker-compose*.yml`, `.github/workflows/**`, `.gitlab-ci.yml`, `**/*.tf`, `k8s/**`, `helm/**` | Containers, CI/CD, deploy, env vars esperadas |
+| **Security** | `**/*auth*`, `**/*authz*`, `**/*middleware*`, `**/*.env.example`, `.env*` (só nomes de var, nunca valores), config files | Mecanismo de auth, papéis, CORS, secrets management |
+| **Patterns** | Mesmos do Backend + Frontend, amostragem representativa | Estrutura, naming, error handling, validação, testes, logging — com snippets reais |
+
+**Cada Reader produz** um fragmento estruturado seguindo as seções correspondentes
+do `TRD.template.md`. Não interpreta — só cataloga. Se algo está ambíguo entre
+2 arquivos (ex: 2 padrões diferentes de error handling), Reader reporta **ambos
+com contagem** ("X em 12 arquivos, Y em 3"). Analyzer decide o dominante depois.
+
+### 8. Analyzer consolida (Opus)
+
+Recebe todos fragmentos. Gera:
+
+#### 8.1 `workspace/Output/<scope>/TRD.md`
+
+Seguindo `templates/feature/TRD.template.md`:
+
+- **§1 §Sistema** (GATE=SIM sempre)
+  - §1.1 Stack (do Dependency Reader)
+  - §1.2 Arquitetura C4 (inferida da estrutura de pastas + dependências)
+  - §1.3 Ambientes (do Infra Reader)
+  - §1.4 Deploy (do Infra Reader)
+  - §1.5 Segurança baseline (do Security Reader)
+  - **§1.6 Padrões Observados** (do Patterns Reader — OBRIGATÓRIO em onboard)
+- **§2-§5 §Áreas** — GATE=SIM para áreas que existem no código, GATE=NÃO pras ausentes
+- **§6 Integrações Externas** (do Backend Reader)
+- **§7 Segurança Detalhada** (do Security Reader)
+- **§8 Estratégia de Testes** (do Patterns Reader)
+- **§9 Decisões Técnicas (ADRs)** — gerar ADRs **inferidas** com flag `Inferido: true`
+- **§10 Ambiguidades** — VAZIA em onboard (código resolve tudo)
+- **§11 Rastreabilidade** — citar arquivo:linha por seção
+
+**Regras absolutas do Analyzer em onboard**:
+- ❌ **NUNCA** marcar ambiguidade. Se 2 padrões divergem, escolher o **mais frequente**
+  e documentar a divergência em §1.6.7 sem julgar.
+- ❌ **NUNCA** sugerir mudanças, "melhorias" ou best practices.
+- ❌ **NUNCA** usar linguagem prescritiva ("deveria", "recomendado"). Sempre descritiva ("usa", "implementa").
+- ✅ Citar arquivo:linha em snippets de §1.6.
+
+#### 8.2 `docs/` (5 arquivos cross-feature)
+
+Gerar todos os 5 a partir do TRD recém-gerado, seguindo templates de `estrutura/`:
+
+| Arquivo | Origem |
+|---------|--------|
+| `docs/architecture.md` | TRD §1.1 + §1.2 + §1.3 + §1.4 |
+| `docs/domain.md` | TRD §Área-DB + visão de negócio inferida da nomenclatura |
+| `docs/conventions.md` | TRD §1.6 + §7 + §8 |
+| `docs/apiContracts.md` | TRD §2.1 + §6 |
+| `docs/decisions.md` | TRD §9 (todas ADRs com flag `Inferido: true`) |
+
+Cada arquivo gerado tem changelog inicial:
+```markdown
+| <DATA> | onboard_<repo> | INICIAL | Gerado por /sf-onboard a partir do código existente |
+```
+
+#### 8.3 `projetos.yaml`
+
+Popular com o repo clonado:
+
+```yaml
+org: "<org-inferida-do-url>"
+project: "<nome-do-projeto>"
+
+repos:
+  <nome-curto>:
+    repo: "<org>/<repo-name>"
+    path: "projetos/<repo-name>"
+    existing: true                # SEMPRE true em onboard
+    areas: [<áreas-detectadas>]   # do Analyzer baseado nos GATEs do TRD
+    stack: "<stack>"              # do TRD §1.1
+    branch_prefix: "feature/"     # ou detectar convenção do repo
+```
+
+Se já existe `projetos.yaml` (re-onboard ou multi-repo) → **merge aditivo**:
+adiciona novo repo, não sobrescreve outros.
+
+### 9. Detecção de monorepo (opcional)
+
+Se o repo clonado contém múltiplos `package.json` / `pom.xml` / `*.csproj` em
+subdirs (não na raiz), pode ser monorepo. Comportamento:
+
+- Cada subprojeto identificado vira uma entry em `projetos.yaml`
+- Mesma URL git, paths diferentes (`projetos/<repo>/services/api`, `projetos/<repo>/web`)
+- TRD documenta arquitetura geral em §1.2
+
+### 10. Atualizar `.context.md` → done
+
+```yaml
+status: "done"
+prd_existe: false
+trd_existe: true
+prd_aprovado: false      # n/a — sempre false em onboard
+trd_aprovado: true       # SEMPRE true em onboard (código é a verdade)
+areas_tocadas: [<áreas-com-GATE=SIM>]
+ultima_skill: "/sf-onboard"
+atualizado_em: "<ISO_DATETIME>"
+```
+
+### 11. Auto-publish (se `sfw.config.yml` configurado)
+
+Se `sfw.config.yml` existe:
+
+```
+/sf-publish <scope> TRD
+```
+
+(Não publica PRD — não existe. Não publica Progresso — não há /sf-plan em onboarding.)
+
+> **Nota**: `docs/` é local-only por design (ver `.github/skills/sf-publish/SKILL.md`).
+> Se quiser publicar no Confluence, copiar manualmente ou aguardar feature futura.
+
+### 12. Saída obrigatória
+
+```
+/sf-onboard — completo
+
+Repo: <git-url> (<branch-ou-tag> @ <commit-hash>)
+Clone: projetos/<repo-name>
+
+Artefatos gerados:
+  - workspace/Output/<scope>/TRD.md
+  - workspace/Output/<scope>/.context.md
+  - workspace/Input/<scope>/code-snapshot.md
+  - docs/architecture.md
+  - docs/domain.md
+  - docs/conventions.md
+  - docs/apiContracts.md
+  - docs/decisions.md (<N> ADRs inferidas)
+  - projetos.yaml (entry: <nome-curto>)
+
+Áreas detectadas: BACK, FRONT, DB, INFRA (conforme TRD)
+Padrões observados: ver TRD §1.6 (<N> categorias)
+ADRs inferidas: <N> (revisar e remover flag `Inferido` ao confirmar)
+
+Próximos passos:
+  1. [dev] Revisar workspace/Output/<scope>/TRD.md
+     - Especialmente §1.6 Padrões Observados (coders vão seguir)
+     - §9 ADRs inferidas (confirmar ou ajustar; remover flag `Inferido` ao validar)
+  2. [dev] Revisar docs/ (5 arquivos)
+  3. Para onboardar outro repo do mesmo projeto: /sf-onboard <outra-url>
+  4. Para começar feature nova: /sf-start feat_<nome>
+```
+
+## Re-onboard
+
+Quando o código legado evolui e quer atualizar a base documental:
+
+```
+/sf-onboard <mesma-url> [--branch=<outra>]
+```
+
+Skill detecta `tipo=onboard` no `.context.md` existente e:
+1. `git pull` no clone
+2. Snapshot novo com classificação NOVO/MODIFICADO/INALTERADO
+3. Readers reprocessam **apenas arquivos MODIFICADOS ou NOVOS**
+4. Analyzer faz **merge aditivo** no TRD existente
+5. `docs/` atualizado com changelog `re-onboard <DATA>`
+6. `projetos.yaml` inalterado (mesmo repo)
+
+## Multi-repo
+
+App = N repos (api, web, worker). Rodar a skill N vezes:
+
+```
+/sf-onboard https://github.com/org/app-api.git --name=onboard_app
+/sf-onboard https://github.com/org/app-web.git --name=onboard_app
+/sf-onboard https://github.com/org/app-worker.git --name=onboard_app
+```
+
+Mesmo `--name` → mesmo `.context.md`, mesmo TRD (merge aditivo), `projetos.yaml`
+recebe 3 entries. Áreas distribuídas: api=[BACK,DB], web=[FRONT], worker=[BACK].
+
+Se `--name` diferentes → scopes separados (raro, mas suportado).
+
+## Erros
+
+| Erro | Ação |
+|------|------|
+| Auth falha (capturado no Passo 0) | Parar com mensagem específica conforme cenário (ver tabela do Passo 0) |
+| Clone falha mesmo com auth OK | Reportar `stderr` do git; verificar se a URL e branch existem |
+| Repo vazio | Parar — "Nada a onboardar" |
+| Nenhum reader produziu fragmento (stack desconhecida) | Parar — "Stack não reconhecida. Detalhe TRD manualmente ou peça suporte" |
+| `projetos/<repo-name>/` já existe e NÃO é clone do mesmo URL | Parar — "Path já em uso por outro repo. Use --name pra dar outro nome" |
+| `sfw.config.yml` aponta backend mas /sf-publish falhou | Reportar warning, manter artefatos locais |
+
+## Diferença vs `/sf-start`
+
+| Aspecto | `/sf-start` | `/sf-onboard` |
+|---------|--------------|----------------|
+| Entrada | Insumos brutos do PM em `workspace/Input/` | URL git de código existente |
+| Gera PRD? | Sim (se insumos têm produto) | Não |
+| Gera TRD? | Sim (após aprovação) | Sim (auto-aprovado) |
+| Gera `docs/`? | No `/sf-design` (first-run) | Diretamente |
+| Gera `projetos.yaml`? | No `/sf-design` (first-run) | Diretamente |
+| Ambiguidades? | Sim (PRD §12, TRD §10) | Não (código resolve) |
+| Checkpoint humano? | Sim (PM + dev) | Não (one-shot) |
+| Filosofia | Design upfront | Cartógrafo descritivo |
+
+## Notas
+
+- `/sf-onboard` é **ortogonal** ao pipeline `/sf-start`. Não chama discovery/sf-extract/sf-design.
+- Após `/sf-onboard`, qualquer feature nova entra pelo `/sf-start feat_<nome>` normal — `first_run` da feature será `false` porque `docs/` já existe.
+- Coder de feature futura **DEVE** ler TRD §1.6 Padrões Observados antes de implementar.
+- Re-onboard NÃO atualiza `specs/` de features já desenvolvidas (são imutáveis pós-`/sf-dev`).