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

package/README.md

@@ -20,6 +20,7 @@ agents especializados por área, security review e rastreabilidade ponta a ponta
 - [Instalação](#instalação)
 - [Estrutura gerada](#estrutura-gerada)
 - [Pipeline passo a passo](#pipeline-passo-a-passo)
+- [Brownfield: assumir aplicação existente](#brownfield-assumir-aplicação-existente)
 - [Commands disponíveis](#commands-disponíveis)
 - [Agents especializados](#agents-especializados)
 - [Backends plugáveis (adapters)](#backends-plugáveis-adapters)
@@ -39,6 +40,7 @@ de código.
 **Use-cases cobertos**:
 - Bootstrap de projeto novo (define stack + arquitetura + primeiras features)
 - Features novas em projeto existente (merge aditivo em docs cross-feature)
+- **Brownfield**: assumir aplicação existente — `/sfw-onboard` lê o código e gera a base documental (ver [seção dedicada](#brownfield-assumir-aplicação-existente))
 - Bugs e tasks técnicas (mesmo pipeline, escopo menor)
 - Times multi-dev (contratos firmes via `specs/` + `projetos.yaml`)
 
@@ -175,6 +177,48 @@ ausência/presença de `docs/`.
 [`apresentacao.html`](https://github.com/gustavomaritan-labs/spec-first-workflow/blob/main/packages/apresentacao.html)
 pra ver o fluxo completo com personas, artefatos e adapters.
 
+## Brownfield: assumir aplicação existente
+
+Para projetos que **já existem** e não nasceram com SFW. O `/sfw-onboard` lê o
+código, identifica stack/padrões/decisões observadas, e popula a base documental
+(TRD + `docs/` + `projetos.yaml`) sem PRD.
+
+**Filosofia**: cartógrafo, não arquiteto. Descreve o que existe sem julgar.
+Coders de features futuras **seguem** os padrões observados — mudanças entram
+como features propostas pelo dev.
+
+```bash
+# 1. Criar shell SFW vazio (mesma instalação)
+spec-first-claude init --name=MeuProjeto
+cd MeuProjeto
+
+# 2. Onboardar repo existente (pré-req: SSH/PAT já configurado)
+/sfw-onboard https://github.com/empresa/app-legado.git
+
+# 3. (Multi-repo) Re-rodar pra cada repo do mesmo projeto
+/sfw-onboard https://github.com/empresa/app-legado-web.git
+/sfw-onboard https://github.com/empresa/app-legado-worker.git
+
+# 4. Começar features novas com o pipeline normal
+/sfw-start feat_nova_funcionalidade
+```
+
+**O que é gerado**:
+- `projetos/<repo>/` — clone(s) com `.git` próprio
+- `workspace/Output/onboard_<repo>/TRD.md` — completo, com §1.6 Padrões Observados (snippets reais)
+- `workspace/Input/onboard_<repo>/code-snapshot.md` — índice + hashes (re-onboard incremental)
+- `docs/` — 5 arquivos cross-feature populados
+- `projetos.yaml` — entries dos repos clonados
+- `docs/decisions.md` — ADRs **inferidas** com flag `Inferido: true` (dev revisa e remove flag ao confirmar)
+
+**Re-onboard** quando o código legado evolui: rodar de novo, hash detecta arquivos
+modificados, merge aditivo no TRD.
+
+**Diferença vs `/sfw-start`**: brownfield NÃO gera PRD nem ambiguidades (código é
+a verdade), não tem checkpoint humano, e auto-aprova TRD. Após onboard, features
+novas entram pelo `/sfw-start` normal — `first_run` da feature já será `false`
+porque `docs/` existe.
+
 ## Commands disponíveis
 
 | Command | Tipo | Função |
@@ -183,6 +227,7 @@ pra ver o fluxo completo com personas, artefatos e adapters.
 | `/load <scope>` | Utilitária | Puxa Input do backend (incremental via hash) |
 | `/publish <scope> <tipo>` | Utilitária | Publica PRD/TRD/Progresso nos targets. Auto-chamada por extract/plan |
 | `/sfw-start <scope>` | Orquestrador | Entrada única. Cria `.context.md`, chama `/load` + `/discovery` + `/extract` |
+| `/sfw-onboard <git-url>` | Atômica | **Brownfield**. Clona repo existente, gera TRD + docs/ + projetos.yaml (sem PRD) |
 | `/discovery <path>` | Atômica | Análise profunda prévia dos insumos (obrigatório em v4) |
 | `/extract <scope>` | Atômica | Gera PRD e/ou TRD conforme conteúdo dos insumos |
 | `/design <scope>` | Atômica | PRD+TRD aprovados → `specs/`. First-run também cria `docs/` + `projetos.yaml` |

package/bin/cli.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 const path = require('path');
 const { init } = require('../lib/init');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-first-claude",
-  "version": "0.7.0",
+  "version": "0.8.0-beta.2",
   "description": "Spec-first workflow kit for Claude Code — AI-driven development with specs, not guesswork",
   "bin": {
     "spec-first-claude": "bin/cli.js"

package/templates/.claude/CHANGELOG.md

@@ -8,6 +8,67 @@
 
 ---
 
+## 0.8.0-beta.2 (2026-05-11) — Auth check pré-clone
+
+`/sfw-onboard` agora verifica autenticação git **antes** de tentar clonar,
+detectando SSH vs HTTPS e testando ssh-agent / credential helper / GH CLI.
+Falha cedo com mensagem específica em vez de erro genérico do `git clone`.
+
+### Adicionado
+
+- Passo 0 do `/sfw-onboard`: verificação proativa de auth
+  - SSH: `ssh-add -l` (agent vazio?) + `ssh -T git@<host>` (chave autorizada?)
+  - HTTPS: `git config credential.helper` + `gh auth status` + `git ls-remote`
+- 6 mensagens de erro específicas (ssh-agent off, agent vazio, chave não
+  autorizada, sem helper nem GH CLI, GH CLI deslogado, falha desconhecida)
+- Nota Windows/PowerShell sobre ssh-agent + alternativas (GH CLI, PAT)
+
+---
+
+## 0.8.0-beta.1 (2026-05-11) — Brownfield onboarding
+
+Skill nova `/sfw-onboard` pra assumir aplicações **já existentes**. Lê o
+código, gera TRD + `docs/` + `projetos.yaml` sem PRD. Cartógrafo descritivo —
+mapeia stack, padrões e decisões observadas sem julgar.
+
+### Adicionado
+
+- **`/sfw-onboard <git-url> [--branch=X] [--tag=Y] [--name=Z]`** — skill atômica:
+  - Clone em `projetos/<repo>/` (auth via SSH/PAT do user)
+  - Snapshot rastreável em `workspace/Input/onboard_<repo>/code-snapshot.md` (hashes SHA-256)
+  - 7 readers paralelos: DB, Backend, Frontend, Infra, Dependency, Security, Patterns
+  - Analyzer (Opus) consolida → TRD + `docs/` 5-arquivos + `projetos.yaml`
+  - Multi-repo via re-execução com mesmo `--name`
+  - Re-onboard incremental (NOVO/MODIFICADO/INALTERADO via hash)
+  - Sem ambiguidades — código resolve tudo
+  - `trd_aprovado=true` automático
+- **TRD §1.6 Padrões Observados** — nova seção obrigatória em onboard:
+  estrutura de pastas, naming, error handling, validação, testes, logging,
+  divergências internas. Com snippets reais do código (arquivo:linha).
+  Coders de features futuras leem antes de implementar.
+- **ADRs inferidas** em `docs/decisions.md` — flag `Inferido: true` distingue
+  decisão observada (cartógrafo) de decisão tomada em discussão. Dev remove
+  flag ao confirmar.
+- **`.context.md` campo `tipo`** — `scope` (pipeline normal) vs `onboard`
+  (brownfield). Campos novos: `repo_url`, `repo_branch`, `repo_path`.
+- **Fluxo de status alternativo** para onboarding:
+  `not_started → cloned → analyzing → done`.
+
+### Filosofia
+
+- **Cartógrafo, não arquiteto**: descreve o que existe sem julgar.
+- **Coders SEGUEM padrões observados** — propostas de mudança entram como
+  features explícitas do dev.
+- **Não há checkpoint humano** em onboard — código é a verdade.
+
+### Migração
+
+Não-breaking. Projetos existentes em `0.7.0` continuam funcionando sem mudança.
+Skill nova adicionada ao roster. Templates de `TRD.md`, `decisions.md` e
+`.context.md` ganharam campos opcionais.
+
+---
+
 ## 0.7.0 (2026-04-14) — Redesign v4 estável
 
 Promoção de `0.7.0-beta.1` para versão estável. Inclui fix crítico:

package/templates/.claude/commands/sfw-onboard.md

@@ -0,0 +1,426 @@
+# /sfw-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
+
+```
+/sfw-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: /sfw-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: "/sfw-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 /sfw-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: "/sfw-onboard"
+atualizado_em: "<ISO_DATETIME>"
+```
+
+### 11. Auto-publish (se `sfw.config.yml` configurado)
+
+Se `sfw.config.yml` existe:
+
+```
+/publish <scope> TRD
+```
+
+(Não publica PRD — não existe. Não publica Progresso — não há /plan em onboarding.)
+
+> **Nota**: `docs/` é local-only por design (ver `.claude/commands/publish.md`).
+> Se quiser publicar no Confluence, copiar manualmente ou aguardar feature futura.
+
+### 12. Saída obrigatória
+
+```
+/sfw-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: /sfw-onboard <outra-url>
+  4. Para começar feature nova: /sfw-start feat_<nome>
+```
+
+## Re-onboard
+
+Quando o código legado evolui e quer atualizar a base documental:
+
+```
+/sfw-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:
+
+```
+/sfw-onboard https://github.com/org/app-api.git --name=onboard_app
+/sfw-onboard https://github.com/org/app-web.git --name=onboard_app
+/sfw-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 /publish falhou | Reportar warning, manter artefatos locais |
+
+## Diferença vs `/sfw-start`
+
+| Aspecto | `/sfw-start` | `/sfw-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 `/design` (first-run) | Diretamente |
+| Gera `projetos.yaml`? | No `/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
+
+- `/sfw-onboard` é **ortogonal** ao pipeline `/sfw-start`. Não chama discovery/extract/design.
+- Após `/sfw-onboard`, qualquer feature nova entra pelo `/sfw-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-`/dev`).

package/templates/.claude/templates/estrutura/decisions.template.md

@@ -37,31 +37,22 @@ REGRAS:
 - Toda mudança de stack, banco, framework DEVE ter registro aqui
 - Decisões são APPEND-ONLY — histórico importa
 
-QUANDO CRIAR:
-- Escolha de tecnologia/framework (em first-run, alimenta a seção inicial)
-- Mudança de padrão de design (feature que introduz)
-- Decisão de infra (cloud provider, DB engine)
-- Trade-off significativo (performance vs simplicidade, etc.)
-- /merge-docs detecta §11 ADDED com impacto arquitetural
-
-QUANDO NÃO CRIAR:
-- Escolha de nome de variável
-- Implementação seguindo padrão já definido
-- Bug fix
-- Refactor sem mudança de interface
+ADRs INFERIDOS (origem /sfw-onboard de projeto brownfield):
+- Quando o /sfw-onboard cria a documentação a partir de código existente, gera
+  ADRs descrevendo decisões OBSERVADAS no código (não tomadas em discussão).
+- Cada ADR inferida tem flag `inferido: true` no início do bloco.
+- Texto descritivo, NÃO prescritivo: "Projeto usa PostgreSQL com JSONB pra X"
+  (não "decidimos usar"). Cartógrafo, não arquiteto.
+- Campo "Contexto" descreve o que o código revela. Campo "Alternativas" pode
+  ficar vazio ou listar "—" — não tem como saber o que foi descartado.
+- Quando dev revisa e confirma/edita o ADR inferido, REMOVE a flag `inferido`.
+- ADRs inferidos podem ser substituídos por novas ADRs (de features futuras)
+  como qualquer outro — flag não afeta imutabilidade.
 
 =============================================================================
 -->
 
-## Índice
-
-| ADR | Título | Status | Data |
-|-----|--------|--------|------|
-| ADR-001 | {{Título}} | proposta / aceita / substituída / descartada | |
-
-## Formato
-
-Cada decisão segue este modelo:
+## Formato — ADR normal
 
 ```markdown
 ### ADR-NNN: Título da Decisão
@@ -71,19 +62,61 @@ Cada decisão segue este modelo:
 - **Decisão**: O que decidimos?
 - **Alternativas consideradas**:
   1. Alternativa A — rejeitada porque...
-  2. Alternativa B — rejeitada porque...
 - **Consequências**:
   - Positivas: ...
   - Negativas: ...
   - Riscos: ...
 ```
 
+## Formato — ADR inferida (origem brownfield)
+
+```markdown
+### ADR-NNN: Título descritivo do padrão observado
+- **Status**: aceita
+- **Inferido**: true  <!-- remover este campo após dev revisar e confirmar -->
+- **Data**: YYYY-MM-DD (data do onboarding)
+- **Contexto**: O que o código revela sobre o cenário (não "decidimos" — "projeto usa")
+- **Decisão**: Padrão observado no código + onde ver (arquivo:linha)
+- **Alternativas consideradas**:
+  1. — (não inferível a partir do código)
+- **Consequências**:
+  - Observadas: efeitos visíveis do padrão no código atual
+```
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE — continuação
+=============================================================================
+
+QUANDO CRIAR:
+- Escolha de tecnologia/framework (em first-run, alimenta a seção inicial)
+- Mudança de padrão de design (feature que introduz)
+- Decisão de infra (cloud provider, DB engine)
+- Trade-off significativo (performance vs simplicidade, etc.)
+- /merge-docs detecta §11 ADDED com impacto arquitetural
+
+QUANDO NÃO CRIAR:
+- Escolha de nome de variável
+- Implementação seguindo padrão já definido
+- Bug fix
+- Refactor sem mudança de interface
+
+=============================================================================
+-->
+
+## Índice
+
+| ADR | Título | Status | Inferido | Data |
+|-----|--------|--------|----------|------|
+| ADR-001 | {{Título}} | proposta / aceita / substituída / descartada | sim/não | |
+
 ---
 
 ## Decisões
 
 ### ADR-001: {{Título}}
 - **Status**: aceita
+- **Inferido**: <!-- true se veio do /sfw-onboard; omitir após dev revisar -->
 - **Data**:
 - **Contexto**:
 - **Decisão**:

package/templates/.claude/templates/feature/TRD.template.md

@@ -126,6 +126,98 @@ RE-GERAÇÃO:
 - TLS: <!-- versão mínima -->
 - Secrets: <!-- onde e como -->
 
+### 1.6 Padrões Observados
+
+> **Obrigatório quando `tipo: onboard` em `.context.md`**. Em scopes normais é opcional
+> — preenchido apenas se o time já tem convenções tribais não documentadas em `docs/conventions.md`.
+> Coders de features futuras consultam ESTA seção antes de implementar — devem
+> SEGUIR os padrões existentes, não propor mudanças.
+>
+> **Snippets reais do código** (não pseudo-código). Cite arquivo+linha quando aplicável.
+> Quando padrões divergem internamente, documente o **mais frequente** como padrão
+> e cite divergências sem julgar (ex: "3 controllers seguem X, 1 segue Y").
+
+#### 1.6.1 Estrutura de pastas
+
+```
+<!-- snippet real do tree -->
+```
+
+| Camada | Onde mora | Convenção de nome |
+|--------|-----------|-------------------|
+|        |           |                   |
+
+#### 1.6.2 Naming
+
+| Tipo | Padrão observado | Exemplo do código |
+|------|------------------|-------------------|
+| Classe / módulo | | |
+| Função / método | | |
+| Arquivo | | |
+| Variável | | |
+| Constante | | |
+
+#### 1.6.3 Error handling
+
+```
+<!-- snippet real mostrando como erros são tratados (try/catch, Result, exceptions, errors) -->
+```
+
+| Aspecto | Padrão | Onde ver |
+|---------|--------|----------|
+| Captura | | |
+| Propagação | | |
+| Resposta HTTP de erro | | |
+| Logging do erro | | |
+
+#### 1.6.4 Validação
+
+```
+<!-- snippet real de validação de input -->
+```
+
+| Camada | Como valida | Lib/framework |
+|--------|-------------|---------------|
+| HTTP | | |
+| Domain | | |
+| DB | | |
+
+#### 1.6.5 Testes
+
+```
+<!-- snippet real de teste (nomenclatura, estrutura AAA/given-when-then) -->
+```
+
+| Aspecto | Padrão observado |
+|---------|------------------|
+| Framework | |
+| Localização dos testes | |
+| Naming dos arquivos de teste | |
+| Naming dos métodos de teste | |
+| Mock / stub | |
+| Coverage observada | |
+
+#### 1.6.6 Logging
+
+```
+<!-- snippet real de log estruturado -->
+```
+
+| Aspecto | Padrão |
+|---------|--------|
+| Lib | |
+| Níveis usados | |
+| Formato (json/text) | |
+| Campos padrão | |
+
+#### 1.6.7 Divergências internas observadas
+
+> Quando o código tem mais de um padrão pra mesma coisa. Sem julgar — apenas documentar.
+
+| Tema | Padrão dominante | Divergência | Onde ver |
+|------|------------------|-------------|----------|
+|      |                  |             |          |
+
 ---
 
 ## 2. §Área-Backend

package/templates/.claude/templates/feature/context.template.md

@@ -1,5 +1,6 @@
 ---
 nome: "{{NOME}}"
+tipo: "{{scope|onboard}}"
 first_run: {{true|false}}
 prd_existe: {{true|false}}
 trd_existe: {{true|false}}
@@ -7,6 +8,9 @@ prd_aprovado: {{true|false}}
 trd_aprovado: {{true|false}}
 areas_tocadas: []
 input_path: "workspace/Input/{{NOME}}/"
+repo_url: ""
+repo_branch: ""
+repo_path: ""
 status: "not_started"
 ultima_skill: ""
 atualizado_em: ""
@@ -21,11 +25,16 @@ SCHEMA v4 (mudou de v3):
 - prd_empty REMOVIDO (conceito obsoleto)
 - prd_existe/trd_existe: bool reais (SEM aspas) indicando se /extract gerou cada doc
 - prd_aprovado/trd_aprovado: bool reais (SEM aspas) controlando gate do /design
+- tipo: discrimina scopes do pipeline normal vs onboarding (brownfield)
+- repo_*: preenchidos só em scopes tipo "onboard"
 
 CAMPOS:
-- nome: identificador livre do scope (ex: app_barbearia, feat_login, infra_k8s)
+- nome: identificador livre do scope (ex: app_barbearia, feat_login, infra_k8s,
+  onboard_app_legado)
+- tipo: "scope" (default — pipeline normal /sfw-start) ou "onboard" (brownfield
+  via /sfw-onboard — código já existe, ler e documentar sem PRD)
 - first_run: bool — true se docs/ não existia quando /sfw-start foi chamado.
-  IMUTÁVEL após criação.
+  IMUTÁVEL após criação. Em onboard, sempre true.
 - prd_existe: bool — true se /extract gerou PRD.md (insumos tinham produto).
   false em scopes puro-técnicos.
 - trd_existe: bool — true se /extract gerou TRD.md (insumos tinham técnica).
@@ -36,6 +45,9 @@ CAMPOS:
 - areas_tocadas: lista de áreas do TRD que têm GATE=SIM. Preenchido pelo /design.
   Possíveis: BACK, FRONT, DB, INFRA. Derivado dos GATEs do TRD §2-§5.
 - input_path: caminho relativo da pasta de insumos
+- repo_url: (só onboard) URL git do repositório onboardeado
+- repo_branch: (só onboard) branch/tag clonada
+- repo_path: (só onboard) caminho relativo do clone em projetos/
 - status: estado atual da pipeline (ver fluxo abaixo)
 - ultima_skill: qual skill alterou este arquivo por último
 - atualizado_em: data/hora ISO da última atualização
@@ -64,8 +76,25 @@ FLUXO DE STATUS (v4):
 Se prd_existe=false: status pula direto de extract_done → trd_approved (sem passar
 por prd_approved). Mesmo vice-versa. Ordem das aprovações dentro do par é irrelevante.
 
+FLUXO ALTERNATIVO — tipo=onboard (brownfield):
+  not_started
+    ↓ /sfw-onboard cria .context.md, clona repo em projetos/<repo_path>/
+  cloned
+    ↓ snapshot gerado em workspace/Input/onboard_<repo>/
+  analyzing
+    ↓ readers paralelos + analyzer consolidam TRD + docs/ + projetos.yaml
+  done
+
+Em onboard:
+- prd_existe = false (sempre — código é técnico, sem PRD)
+- trd_existe = true (sempre)
+- trd_aprovado = true (sempre — código é a verdade, sem ambiguidades, dev valida lendo)
+- areas_tocadas preenchidas a partir dos GATEs do TRD
+- Re-onboard reentra em "analyzing" e refaz merge aditivo
+
 QUEM ATUALIZA:
-- /sfw-start: cria arquivo com status=not_started, first_run derivado de docs/
+- /sfw-onboard: cria arquivo com tipo=onboard, status=not_started → cloned → analyzing → done
+- /sfw-start: cria arquivo com tipo=scope, status=not_started, first_run derivado de docs/
 - /discovery: not_started → discovery_done
 - /extract: discovery_done → extract_done, preenche prd_existe + trd_existe
 - PM aprova: extract_done → prd_approved (atualiza prd_aprovado=true)

package/templates/CLAUDE.md

@@ -21,7 +21,7 @@
 
 ### 2. Validar acesso a todos commands
 
-Verificar que TODOS os 11 commands estão acessíveis:
+Verificar que TODOS os 12 commands estão acessíveis:
 
 | Command | Caminho |
 |---------|---------|
@@ -29,6 +29,7 @@ Verificar que TODOS os 11 commands estão acessíveis:
 | `/load` | `.claude/commands/load.md` |
 | `/publish` | `.claude/commands/publish.md` |
 | `/sfw-start` | `.claude/commands/sfw-start.md` |
+| `/sfw-onboard` | `.claude/commands/sfw-onboard.md` |
 | `/discovery` | `.claude/commands/discovery.md` |
 | `/extract` | `.claude/commands/extract.md` |
 | `/design` | `.claude/commands/design.md` |
@@ -108,6 +109,7 @@ ESTE REPO (projeto-base) = ORQUESTRADOR
 | `/load <nome> \| --all` | Utilitária | Puxa Input + Output do backend. Incremental |
 | `/publish <nome> <tipo>` | Utilitária | Publica artefato (PRD/TRD/Progresso) nos output.targets[]. Chamado auto por extract/design/plan |
 | `/sfw-start <nome>` | Orquestrador | Entrada única do pipeline. Detecta first_run, cria .context.md, chama /load + /discovery + /extract, para no checkpoint de aprovação |
+| `/sfw-onboard <git-url>` | Atômica | **Brownfield**. Clona repo existente em projetos/, lê código e gera TRD + docs/ + projetos.yaml (sem PRD). Cartógrafo descritivo |
 | `/discovery <path>` | Utilitária | Análise profunda dos insumos (OBRIGATÓRIO no /sfw-start em v4) |
 | `/extract <nome>` | Atômica | Lê workspace/Input/{nome}/ → gera PRD e/ou TRD conforme conteúdo. Re-executável |
 | `/design <nome>` | Atômica | Requer PRD e/ou TRD aprovados → gera specs/. first_run cria docs/ + projetos.yaml |
@@ -173,7 +175,7 @@ Antes de executar qualquer command, verificar o status. Cada command só avança
 │   ├── estrutura/           ← architecture, domain, conventions, apiContracts, decisions
 │   └── global/              ← progresso_global
 ├── adapters/                ← SourceAdapter interface + ConfluenceAdapter + FilesystemAdapter
-├── commands/                ← 11 commands (mcp, load, publish, sfw-start, discovery, extract, design, plan, dev, merge-docs, session-finish)
+├── commands/                ← 12 commands (mcp, load, publish, sfw-start, sfw-onboard, discovery, extract, design, plan, dev, merge-docs, session-finish)
 └── agents/                  ← 7 perfis de agents especializados
 
 docs/                        ← SÍNTESE CROSS-FEATURE (atualizada pelo /merge-docs)
@@ -211,7 +213,7 @@ sfw.config.yml               ← Manifesto de adapters (input/output backends)
 **Quem lê o quê:**
 - **Humano (PM)**: `workspace/Output/{nome}/PRD.md` para aprovar
 - **Humano (dev)**: `workspace/Output/{nome}/TRD.md` para aprovar + `docs/` (onboarding)
-- **Coder agent**: `specs/{nome}/` (projeções estruturadas) — NUNCA lê PRD/TRD direto
+- **Coder agent**: `specs/{nome}/` (projeções estruturadas) — NUNCA lê PRD/TRD direto. **Exceção brownfield**: lê TRD §1.6 Padrões Observados antes de implementar (segue padrões existentes)
 - **Reviewer**: `specs/{nome}/scenarios.md` (CAs) + código
 - **Security Reviewer**: `specs/{nome}/contracts.md` + `docs/conventions.md` + código
 - **`/merge-docs`**: `workspace/Output/{nome}/PRD.md + TRD.md` (diff semântico pra atualizar docs/)