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

package/templates/.github/skills/sf-merge-docs/SKILL.md

@@ -1,152 +1,152 @@
-
-# /sf-merge-docs $ARGUMENTS
-
-Skill atômica pós-dev. Aplica as decisões de **PRD + TRD aprovados** em `docs/` pra manter a síntese cross-feature sincronizada com o estado do sistema.
-`$ARGUMENTS` = nome do scope (ex: `feat_cadastro_cliente`).
-
-Chamado automaticamente pelo `/sf-dev` ao final. Re-executável manualmente quando precisa.
-
-> **Mudança v3 → v4**: antes aplicava `SDD §11 Delta Specs` (mecanismo OpenSpec).
-> Agora lê **PRD + TRD aprovados diretamente** e infere o delta comparando com
-> o estado atual de `docs/` (diff semântico). SDD não existe mais em v4.
-
-## Agente: Integrator (Opus)
-
-Em v4 promovido de Sonnet → Opus: diff semântico PRD/TRD ↔ docs/ exige reasoning
-de maior nível que o antigo "aplicar §11 explícito". Meticuloso com consistência.
-Merge idempotente — re-aplicar os mesmos docs source não duplica conteúdo.
-
-## Pré-condições
-
-| # | Validação | Se falhar |
-|---|-----------|-----------|
-| 1 | `$ARGUMENTS` informado | Parar |
-| 2 | `.context.md` com status `dev_done` (uso auto no /sf-dev) OU `design_done` a mais (uso manual) | Se anterior → "Rode /sf-design primeiro" |
-| 3 | Pelo menos PRD.md OU TRD.md existe e está aprovado | Parar — "Nenhum doc source aprovado pra mergear" |
-| 4 | `docs/` populado (veio de first-run anterior) | Parar — "/sf-design com first_run=true é quem cria docs/" |
-
-> `/sf-merge-docs` **só se aplica a features**, não a first-run. Em first-run, é o
-> próprio `/sf-design` que cria `docs/` a partir de PRD+TRD — não há o que mergear.
-
-## Passos
-
-### 1. Snapshot do estado atual de docs/
-
-Ler `docs/{architecture,domain,conventions,apiContracts,decisions}.md`.
-Indexar por elementos (tabelas, endpoints, ADRs, papéis, env vars...) pra diff.
-
-### 2. Extrair elementos-destino do PRD e TRD aprovados
-
-| Fonte (PRD/TRD) | Elemento | Destino em docs/ |
-|-----------------|----------|------------------|
-| TRD §1.1 Stack | Nova tecnologia / versão | `architecture.md` §Stack |
-| TRD §1.2 Arquitetura | Novo container / padrão | `architecture.md` §Containers/Padrões |
-| TRD §1.3 Ambientes | Novo ambiente / mudança | `architecture.md` §Ambientes |
-| TRD §1.4 Deploy | Mudança na estratégia | `architecture.md` §Deploy |
-| TRD §4 §Área-DB | Nova tabela / índice / FK | `domain.md` §Catálogo de Tabelas |
-| TRD §2.1 Endpoints | Novo endpoint | `apiContracts.md` §Catálogo |
-| TRD §7.1 Auth | Mudança em auth | `conventions.md` §Autenticação |
-| TRD §7.2 Autorização | Novo papel / permissão | `conventions.md` §Autorização |
-| TRD §7.3 LGPD | Novo dado pessoal | `conventions.md` §LGPD |
-| TRD §7.4 Rate limit | Nova categoria | `conventions.md` §Rate Limiting |
-| TRD §5.3 Env vars | Nova variável | `conventions.md` §Variáveis de Ambiente |
-| TRD §6 Integrações | Novo sistema externo | `domain.md` §Integrações Externas |
-| TRD §9 ADRs | Nova decisão | `decisions.md` (append-only, imutável) |
-| PRD §2 Atores | Novo papel/persona | `domain.md` §Usuários e Papéis |
-| PRD §5 RNs | Nova regra de negócio | (não vai pra docs/ — fica em specs/{nome}/contracts.md) |
-
-> **Regra**: PRD alimenta poucas seções de `docs/` (só atores e alto-nível).
-> O grosso vem do TRD — `docs/` é síntese técnica + negócio cross-feature.
-
-### 3. Diff semântico: calcular ADDED / MODIFIED / REMOVED
-
-Pra cada elemento-destino extraído (passo 2), comparar com snapshot (passo 1):
-
-| Resultado | Condição | Ação |
-|-----------|----------|------|
-| ADDED | Elemento não existe em docs/ | Adicionar na seção apropriada |
-| MODIFIED | Elemento existe mas mudou (nome igual, valor diferente) | Atualizar campos |
-| UNCHANGED | Elemento existe e está igual | Skip (idempotente) |
-| REMOVED | Elemento estava em docs/ mas não aparece em PRD+TRD aprovados | **NÃO remover** — apenas registrar no output como "possivelmente orfão" |
-
-> **Conservadorismo em REMOVED**: PRD/TRD falam só da feature atual. Algo que
-> "não aparece" pode ser de outra feature (que continua válida). NUNCA deletar
-> automaticamente. Reportar e deixar remoção manual.
-
-### 4. Aplicar ADDED e MODIFIED
-
-- Localizar seção apropriada no doc destino
-- Preservar estrutura do template (não quebrar tabelas)
-- ADRs em `decisions.md`: SEMPRE append; ADR com status=aceita é imutável
-- Registrar cada mudança em changelog do doc afetado
-
-### 5. Changelog em cada doc afetado
-
-Adicionar linha no `## Changelog` do doc:
-
-```markdown
-| Data | Feature | Tipo | Descrição |
-|------|---------|------|-----------|
-| {{ISO_DATE}} | $ARGUMENTS | ADDED | Endpoint POST /api/v1/users |
-| {{ISO_DATE}} | $ARGUMENTS | MODIFIED | Matriz de permissões: novo role `manager` |
-```
-
-### 6. Validar consistência cross-doc
-
-- Referências quebradas (endpoint do apiContracts referencia tabela que não existe em domain) → reportar
-- Papel novo em conventions mas não aparece em matriz de autorização → reportar
-- ADR substituída mas ainda referenciada → reportar
-
-Validação reporta, não bloqueia. Usuário decide se resolve manualmente.
-
-### 7. Atualizar status
-
-```yaml
-status: "done"
-ultima_skill: "/sf-merge-docs"
-atualizado_em: "{{ISO_DATETIME}}"
-```
-
-### 8. Saída obrigatória
-
-```
-/sf-merge-docs $ARGUMENTS — completo
-
-docs/ sincronizado com PRD + TRD aprovados:
-- docs/architecture.md    (2 ADDED, 0 MODIFIED)
-- docs/apiContracts.md    (3 ADDED, 1 MODIFIED)
-- docs/conventions.md     (0 ADDED, 1 MODIFIED — novo role)
-- docs/decisions.md       (1 ADDED — ADR-007)
-- docs/domain.md          (0 mudanças)
-
-Possivelmente órfãos (NÃO removidos — revisão manual):
-  - docs/apiContracts.md: endpoint `/legacy/foo` não aparece em PRD+TRD novos
-    (pode ser de outra feature; deletar manualmente se confirmado deprecated)
-
-Validação: passed / N issues
-```
-
-## Erros
-
-| Erro | Ação |
-|------|------|
-| Status != `dev_done` (auto) nem >= `design_done` (manual) | Parar — pedir rodar /sf-dev ou /sf-design primeiro |
-| `docs/` não existe | Parar — explicar que `/sf-design` em first-run cria docs/ (feature só atualiza) |
-| PRD+TRD sem nada novo vs docs/ | Marcar `done` (legítimo — feature sem impacto cross-feature) |
-| Elemento MODIFIED não encontrado no doc | Converter pra ADDED + reportar (doc estava desatualizado) |
-| Referências quebradas detectadas | Reportar, não bloqueia |
-
-## Uso automático (pelo `/sf-dev`)
-
-`/sf-dev` chama `/sf-merge-docs` automaticamente ao final de feature (não first-run):
-
-- Condição: `status=dev_done` E `first_run=false` E (`prd_aprovado=true` OU `trd_aprovado=true`)
-- Rodado inline, sem nova interação
-- Falha em `/sf-merge-docs` não derruba `/sf-dev` — apenas reporta; user pode re-rodar manualmente
-
-## Uso manual
-
-Rodar `/sf-merge-docs $ARGUMENTS` quando:
-- `/sf-dev` falhou e você quer sincronizar docs/ com o que já foi aprovado
-- Fez edição direta em PRD/TRD aprovados e quer propagar pra docs/
-- Quer forçar um re-merge (idempotente — não duplica)
+
+# /sf-merge-docs $ARGUMENTS
+
+Skill atômica pós-dev. Aplica as decisões de **PRD + TRD aprovados** em `docs/` pra manter a síntese cross-feature sincronizada com o estado do sistema.
+`$ARGUMENTS` = nome do scope (ex: `feat_cadastro_cliente`).
+
+Chamado automaticamente pelo `/sf-dev` ao final. Re-executável manualmente quando precisa.
+
+> **Mudança v3 → v4**: antes aplicava `SDD §11 Delta Specs` (mecanismo OpenSpec).
+> Agora lê **PRD + TRD aprovados diretamente** e infere o delta comparando com
+> o estado atual de `docs/` (diff semântico). SDD não existe mais em v4.
+
+## Agente: Integrator (Opus)
+
+Em v4 promovido de Sonnet → Opus: diff semântico PRD/TRD ↔ docs/ exige reasoning
+de maior nível que o antigo "aplicar §11 explícito". Meticuloso com consistência.
+Merge idempotente — re-aplicar os mesmos docs source não duplica conteúdo.
+
+## Pré-condições
+
+| # | Validação | Se falhar |
+|---|-----------|-----------|
+| 1 | `$ARGUMENTS` informado | Parar |
+| 2 | `.context.md` com status `dev_done` (uso auto no /sf-dev) OU `design_done` a mais (uso manual) | Se anterior → "Rode /sf-design primeiro" |
+| 3 | Pelo menos PRD.md OU TRD.md existe e está aprovado | Parar — "Nenhum doc source aprovado pra mergear" |
+| 4 | `docs/` populado (veio de first-run anterior) | Parar — "/sf-design com first_run=true é quem cria docs/" |
+
+> `/sf-merge-docs` **só se aplica a features**, não a first-run. Em first-run, é o
+> próprio `/sf-design` que cria `docs/` a partir de PRD+TRD — não há o que mergear.
+
+## Passos
+
+### 1. Snapshot do estado atual de docs/
+
+Ler `docs/{architecture,domain,conventions,apiContracts,decisions}.md`.
+Indexar por elementos (tabelas, endpoints, ADRs, papéis, env vars...) pra diff.
+
+### 2. Extrair elementos-destino do PRD e TRD aprovados
+
+| Fonte (PRD/TRD) | Elemento | Destino em docs/ |
+|-----------------|----------|------------------|
+| TRD §1.1 Stack | Nova tecnologia / versão | `architecture.md` §Stack |
+| TRD §1.2 Arquitetura | Novo container / padrão | `architecture.md` §Containers/Padrões |
+| TRD §1.3 Ambientes | Novo ambiente / mudança | `architecture.md` §Ambientes |
+| TRD §1.4 Deploy | Mudança na estratégia | `architecture.md` §Deploy |
+| TRD §4 §Área-DB | Nova tabela / índice / FK | `domain.md` §Catálogo de Tabelas |
+| TRD §2.1 Endpoints | Novo endpoint | `apiContracts.md` §Catálogo |
+| TRD §7.1 Auth | Mudança em auth | `conventions.md` §Autenticação |
+| TRD §7.2 Autorização | Novo papel / permissão | `conventions.md` §Autorização |
+| TRD §7.3 LGPD | Novo dado pessoal | `conventions.md` §LGPD |
+| TRD §7.4 Rate limit | Nova categoria | `conventions.md` §Rate Limiting |
+| TRD §5.3 Env vars | Nova variável | `conventions.md` §Variáveis de Ambiente |
+| TRD §6 Integrações | Novo sistema externo | `domain.md` §Integrações Externas |
+| TRD §9 ADRs | Nova decisão | `decisions.md` (append-only, imutável) |
+| PRD §2 Atores | Novo papel/persona | `domain.md` §Usuários e Papéis |
+| PRD §5 RNs | Nova regra de negócio | (não vai pra docs/ — fica em specs/{nome}/contracts.md) |
+
+> **Regra**: PRD alimenta poucas seções de `docs/` (só atores e alto-nível).
+> O grosso vem do TRD — `docs/` é síntese técnica + negócio cross-feature.
+
+### 3. Diff semântico: calcular ADDED / MODIFIED / REMOVED
+
+Pra cada elemento-destino extraído (passo 2), comparar com snapshot (passo 1):
+
+| Resultado | Condição | Ação |
+|-----------|----------|------|
+| ADDED | Elemento não existe em docs/ | Adicionar na seção apropriada |
+| MODIFIED | Elemento existe mas mudou (nome igual, valor diferente) | Atualizar campos |
+| UNCHANGED | Elemento existe e está igual | Skip (idempotente) |
+| REMOVED | Elemento estava em docs/ mas não aparece em PRD+TRD aprovados | **NÃO remover** — apenas registrar no output como "possivelmente orfão" |
+
+> **Conservadorismo em REMOVED**: PRD/TRD falam só da feature atual. Algo que
+> "não aparece" pode ser de outra feature (que continua válida). NUNCA deletar
+> automaticamente. Reportar e deixar remoção manual.
+
+### 4. Aplicar ADDED e MODIFIED
+
+- Localizar seção apropriada no doc destino
+- Preservar estrutura do template (não quebrar tabelas)
+- ADRs em `decisions.md`: SEMPRE append; ADR com status=aceita é imutável
+- Registrar cada mudança em changelog do doc afetado
+
+### 5. Changelog em cada doc afetado
+
+Adicionar linha no `## Changelog` do doc:
+
+```markdown
+| Data | Feature | Tipo | Descrição |
+|------|---------|------|-----------|
+| {{ISO_DATE}} | $ARGUMENTS | ADDED | Endpoint POST /api/v1/users |
+| {{ISO_DATE}} | $ARGUMENTS | MODIFIED | Matriz de permissões: novo role `manager` |
+```
+
+### 6. Validar consistência cross-doc
+
+- Referências quebradas (endpoint do apiContracts referencia tabela que não existe em domain) → reportar
+- Papel novo em conventions mas não aparece em matriz de autorização → reportar
+- ADR substituída mas ainda referenciada → reportar
+
+Validação reporta, não bloqueia. Usuário decide se resolve manualmente.
+
+### 7. Atualizar status
+
+```yaml
+status: "done"
+ultima_skill: "/sf-merge-docs"
+atualizado_em: "{{ISO_DATETIME}}"
+```
+
+### 8. Saída obrigatória
+
+```
+/sf-merge-docs $ARGUMENTS — completo
+
+docs/ sincronizado com PRD + TRD aprovados:
+- docs/architecture.md    (2 ADDED, 0 MODIFIED)
+- docs/apiContracts.md    (3 ADDED, 1 MODIFIED)
+- docs/conventions.md     (0 ADDED, 1 MODIFIED — novo role)
+- docs/decisions.md       (1 ADDED — ADR-007)
+- docs/domain.md          (0 mudanças)
+
+Possivelmente órfãos (NÃO removidos — revisão manual):
+  - docs/apiContracts.md: endpoint `/legacy/foo` não aparece em PRD+TRD novos
+    (pode ser de outra feature; deletar manualmente se confirmado deprecated)
+
+Validação: passed / N issues
+```
+
+## Erros
+
+| Erro | Ação |
+|------|------|
+| Status != `dev_done` (auto) nem >= `design_done` (manual) | Parar — pedir rodar /sf-dev ou /sf-design primeiro |
+| `docs/` não existe | Parar — explicar que `/sf-design` em first-run cria docs/ (feature só atualiza) |
+| PRD+TRD sem nada novo vs docs/ | Marcar `done` (legítimo — feature sem impacto cross-feature) |
+| Elemento MODIFIED não encontrado no doc | Converter pra ADDED + reportar (doc estava desatualizado) |
+| Referências quebradas detectadas | Reportar, não bloqueia |
+
+## Uso automático (pelo `/sf-dev`)
+
+`/sf-dev` chama `/sf-merge-docs` automaticamente ao final de feature (não first-run):
+
+- Condição: `status=dev_done` E `first_run=false` E (`prd_aprovado=true` OU `trd_aprovado=true`)
+- Rodado inline, sem nova interação
+- Falha em `/sf-merge-docs` não derruba `/sf-dev` — apenas reporta; user pode re-rodar manualmente
+
+## Uso manual
+
+Rodar `/sf-merge-docs $ARGUMENTS` quando:
+- `/sf-dev` falhou e você quer sincronizar docs/ com o que já foi aprovado
+- Fez edição direta em PRD/TRD aprovados e quer propagar pra docs/
+- Quer forçar um re-merge (idempotente — não duplica)

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

@@ -0,0 +1,370 @@
+---
+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 | Parar → "Git não encontrado no PATH" |
+| 3 | URL acessível (auth do user) | Parar → "Falha ao clonar. Configure SSH/PAT antes de rodar /sf-onboard" |
+| 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" |
+
+## 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 |
+|------|------|
+| URL não acessível | Parar, sugerir checar SSH/PAT |
+| 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`).