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

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)
 - [Skills disponíveis](#skills-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 — `/sf-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`)
 
@@ -176,6 +178,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 `/sf-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-copilot init --name=MeuProjeto
+cd MeuProjeto
+
+# 2. Onboardar repo existente (pré-req: SSH/PAT já configurado)
+/sf-onboard https://github.com/empresa/app-legado.git
+
+# 3. (Multi-repo) Re-rodar pra cada repo do mesmo projeto
+/sf-onboard https://github.com/empresa/app-legado-web.git
+/sf-onboard https://github.com/empresa/app-legado-worker.git
+
+# 4. Começar features novas com o pipeline normal
+/sf-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 `/sf-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 `/sf-start` normal — `first_run` da feature já será `false`
+porque `docs/` existe.
+
 ## Skills disponíveis
 
 | Skill | Tipo | Função |
@@ -184,6 +228,7 @@ pra ver o fluxo completo com personas, artefatos e adapters.
 | `/sf-load <scope>` | Utilitária | Puxa Input do backend (incremental via hash) |
 | `/sf-publish <scope> <tipo>` | Utilitária | Publica PRD/TRD/Progresso nos targets. Auto-chamada por extract/plan |
 | `/sf-start <scope>` | Orquestrador | Entrada única. Cria `.context.md`, chama `/sf-load` + `/sf-discovery` + `/sf-extract` |
+| `/sf-onboard <git-url>` | Atômica | **Brownfield**. Clona repo existente, gera TRD + docs/ + projetos.yaml (sem PRD) |
 | `/sf-discovery <path>` | Atômica | Análise profunda prévia dos insumos (obrigatório em v4) |
 | `/sf-extract <scope>` | Atômica | Gera PRD e/ou TRD conforme conteúdo dos insumos |
 | `/sf-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-copilot",
-  "version": "0.7.0",
+  "version": "0.8.0-beta.1",
   "description": "Spec-first workflow kit for GitHub Copilot — AI-driven development with specs, not guesswork",
   "bin": {
     "spec-first-copilot": "bin/cli.js"

package/templates/.github/CHANGELOG.md

@@ -8,6 +8,50 @@
 
 ---
 
+## 0.8.0-beta.1 (2026-05-11) — Brownfield onboarding
+
+Skill nova `/sf-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
+
+- **`/sf-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/.github/copilot-instructions.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:
 | `/sf-load` | `.github/skills/sf-load/SKILL.md` |
 | `/sf-publish` | `.github/skills/sf-publish/SKILL.md` |
 | `/sf-start` | `.github/skills/sf-start/SKILL.md` |
+| `/sf-onboard` | `.github/skills/sf-onboard/SKILL.md` |
 | `/sf-discovery` | `.github/skills/sf-discovery/SKILL.md` |
 | `/sf-extract` | `.github/skills/sf-extract/SKILL.md` |
 | `/sf-design` | `.github/skills/sf-design/SKILL.md` |
@@ -108,6 +109,7 @@ ESTE REPO (projeto-base) = ORQUESTRADOR
 | `/sf-load <nome> \| --all` | Utilitária | Puxa Input + Output do backend. Incremental |
 | `/sf-publish <nome> <tipo>` | Utilitária | Publica artefato (PRD/TRD/Progresso) nos output.targets[]. Chamado auto por extract/sf-design/sf-plan |
 | `/sf-start <nome>` | Orquestrador | Entrada única do pipeline. Detecta first_run, cria .context.md, chama /sf-load + /sf-discovery + /sf-extract, para no checkpoint de aprovação |
+| `/sf-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 |
 | `/sf-discovery <path>` | Utilitária | Análise profunda dos insumos (OBRIGATÓRIO no /sf-start em v4) |
 | `/sf-extract <nome>` | Atômica | Lê workspace/Input/{nome}/ → gera PRD e/ou TRD conforme conteúdo. Re-executável |
 | `/sf-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, sf-start, sf-onboard, discovery, extract, design, plan, dev, merge-docs, session-finish)
 └── agents/                  ← 7 perfis de agents especializados
 
 docs/                        ← SÍNTESE CROSS-FEATURE (atualizada pelo /sf-merge-docs)

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

@@ -1,161 +1,161 @@
-
-# /sf-design $ARGUMENTS
-
-Skill atômica de design. Consome PRD + TRD aprovados e gera **`docs/` + `specs/{nome}/` + `projetos.yaml`** (este último em first-run).
-`$ARGUMENTS` = nome do scope (ex: `app_barbearia`, `feat_cadastro_cliente`).
-
-Em **first-run** (docs/ ausente): cria docs/ a partir do PRD+TRD + projetos.yaml + specs/.
-Em **feature** (docs/ existe): não cria docs/ (vem pelo /sf-merge-docs depois do /sf-dev) + gera apenas specs/ do scope atual.
-
-## Agente: Architect (Opus)
-
-Técnico e preciso. Deriva projeções a partir dos docs source sem reinventar decisões.
-
-## Pré-condições
-
-| # | Validação | Se falhar |
-|---|-----------|-----------|
-| 1 | `$ARGUMENTS` informado | Parar |
-| 2 | `.context.md` existe com status `extract_done` ou posterior | Se anterior → "/sf-extract $ARGUMENTS primeiro" |
-| 3 | Se `prd_existe=true`: `PRD.md` existe E `prd_aprovado=true` | Parar, listar ambiguidades pendentes (ver bloco abaixo) |
-| 4 | Se `trd_existe=true`: `TRD.md` existe E `trd_aprovado=true` | Parar, listar ambiguidades pendentes |
-| 5 | Pelo menos um dos 2 existe e está aprovado | Parar → "Extração falhou — nenhum doc aprovado" |
-
-Quando parar por ambiguidade:
-
-```
-Ambiguidades pendentes em PRD §12 / TRD §10:
-
-  AMB-PRD-001: {pergunta}
-  AMB-TRD-002: {pergunta}
-
-Como responder:
-  1. Abra workspace/Output/$ARGUMENTS/PRD.md (ou TRD.md)
-  2. Vá até §Ambiguidades e preencha a coluna `Resposta`
-  3. Marque prd_aprovado=true (ou trd_aprovado=true) em .context.md
-  4. Rode /sf-design $ARGUMENTS de novo
-
-Mais detalhes em .github/skills/sf-extract/SKILL.md → "Como responder ambiguidades".
-```
-
-## Passos
-
-### 1. Carregar contexto
-
-- `.context.md` → `first_run`, `prd_existe`, `trd_existe`, `areas_tocadas` (vazio, vai popular)
-- `workspace/Output/$ARGUMENTS/PRD.md` (se `prd_existe=true`)
-- `workspace/Output/$ARGUMENTS/TRD.md` (se `trd_existe=true`)
-- `docs/` (se existir — feature mode): baseline cross-feature
-- `discovery.md` (se existir): análise prévia
-- `.github/rules.md`
-- Templates:
-  - `.github/templates/specs/{brief,contracts,scenarios}.template.md`
-  - `.github/templates/estrutura/*.template.md` (só se first-run)
-  - `.github/templates/feature/projetos.template.yaml` (só se first-run)
-
-### 2. Determinar áreas tocadas
-
-Ler GATEs do TRD §2-§5 (se TRD existe). Áreas marcadas como `GATE: SIM` vão pra
-`.context.md → areas_tocadas: [...]`.
-
-Se TRD não existe (scope puro-produto, raro): `areas_tocadas = []`; `/sf-plan` vai
-gerar só tasks de frontend com base no PRD §7.
-
-### 3. Branch first-run vs feature
-
-Ler `first_run` do `.context.md`.
-
-#### Branch A — first_run = true (bootstrap)
-
-1. **Gerar `docs/`** (5 arquivos em `docs/` na raiz do projeto):
-
-   | Doc gerado | Fontes |
-   |-----------|--------|
-   | `architecture.md` | TRD §1.1 Stack + §1.2 Arquitetura + §1.3 Ambientes + §1.4 Deploy + §5 §Área-Infra |
-   | `domain.md` | PRD §1 Contexto + §2 Atores + §3 Jornadas (resumo) + TRD §4 §Área-DB |
-   | `conventions.md` | TRD §1.5 Segurança baseline + §7 Segurança detalhada + §5.3 Env vars + §5.4 Monitoramento |
-   | `apiContracts.md` | TRD §2.1 Endpoints + convenções de rota inferidas |
-   | `decisions.md` | TRD §9 ADRs (transcritas como ADR-001, ADR-002... imutáveis) |
-
-   Regras:
-   - Ler template → preencher TODAS as seções com dados do PRD/TRD
-   - Remover bloco `<!-- INSTRUÇÕES -->` do doc gerado
-   - Changelog inicia vazio
-   - Se PRD ou TRD não tem dados pra uma seção → "A definir" (não deixar vazio)
-
-2. **Gerar `projetos.yaml`** na raiz:
-
-   - Identificar serviços separados no TRD §1.2 Containers (api, worker, web, etc.)
-   - Perguntar ao usuário: organização GitHub, nome base, se algum repo já existe
-   - Mapear áreas → repos (API+DB costumam ir juntos; Frontend separado)
-   - Validar: cada área em `areas_tocadas` tem repo correspondente
-
-3. **Gerar `specs/$ARGUMENTS/`** (passo 4 abaixo, comum a first-run e feature)
-
-#### Branch B — first_run = false (feature)
-
-1. **Não toca em `docs/`** (isso é trabalho do /sf-merge-docs após /sf-dev)
-2. **Não gera `projetos.yaml`** (já existe do first-run)
-3. **Gera apenas `specs/$ARGUMENTS/`**
-
-### 4. Gerar `specs/$ARGUMENTS/` (sempre)
-
-Criar/sobrescrever os 4 arquivos em `specs/$ARGUMENTS/`:
-
-| Arquivo | Projeção de | Conteúdo |
-|---------|-------------|----------|
-| `brief.md` | PRD §1 + §10 + §11 + TRD §1 | Problema, Solução, Serviços tocados (de projetos.yaml), Escopo (Dentro/Fora), Decisões principais (ADRs resumidas) |
-| `contracts.md` | TRD §4 + §2.3 + §2.1 + §6 + PRD §5 | Dados (schema), Validações de Entrada, API (endpoints específicos), Integrações externas, Regras de Negócio com enforcement point |
-| `scenarios.md` | PRD §3 + §8 + §7 + TRD §8 | Pré-condições globais, Fluxos happy path, Fluxos de erro (com Ref CA), UI por componente, CAs com Given/When/Then, Estratégia de testes |
-| `tasks.md` | stub | (preenchido pelo `/sf-plan`) |
-
-Regras:
-- Projeções são **REGENERÁVEIS** — ao re-rodar `/sf-design`, sobrescreve
-- NUNCA editar direto em `specs/` — PRD/TRD são as fontes
-- Templates em `.github/templates/specs/`
-- Coders e Reviewer leem daqui, NUNCA de PRD/TRD direto
-
-### 5. Validação de consistência
-
-Antes de terminar, verificar:
-- Cada RN do PRD §5 aparece em `contracts.md → Regras de Negócio` com enforcement point
-- Cada endpoint do TRD §2.1 aparece em `contracts.md → API`
-- Cada CA em `scenarios.md` mapeia pra pelo menos 1 RN ou 1 jornada
-- Áreas em `areas_tocadas` têm entries em `contracts.md` e `scenarios.md`
-
-Divergências → alertar no output, sem falhar.
-
-### 6. Atualizar `.context.md`
-
-```yaml
-status: "design_done"
-areas_tocadas: [BACK, DB, ...]   # derivado do passo 2
-ultima_skill: "/sf-design"
-atualizado_em: "{{ISO_DATETIME}}"
-```
-
-### 7. Saída obrigatória
-
-```
-/sf-design $ARGUMENTS — completo ({{first-run | feature}})
-
-Artefatos:
-  - specs/$ARGUMENTS/brief.md
-  - specs/$ARGUMENTS/contracts.md
-  - specs/$ARGUMENTS/scenarios.md
-  - specs/$ARGUMENTS/tasks.md (stub — será preenchido por /sf-plan)
-  (se first-run:)
-  - docs/architecture.md, domain.md, conventions.md, apiContracts.md, decisions.md
-  - projetos.yaml
-
-Áreas tocadas: [BACK, DB, FRONT, INFRA]
-Validação: {{N issues / passed}}
-
-Próximo passo: /sf-plan $ARGUMENTS
-```
-
-## Regra de ouro
-
-- `/sf-design` NUNCA reinventa decisões. Apenas projeta PRD+TRD pra formatos consumíveis.
-- Se precisa de uma decisão nova que não está no PRD ou TRD: é ambiguidade — voltar pra `/sf-extract` com novo insumo.
-- Divergências entre PRD e TRD: **PRD vence em produto, TRD vence em técnica** (não há overlap por design).
+
+# /sf-design $ARGUMENTS
+
+Skill atômica de design. Consome PRD + TRD aprovados e gera **`docs/` + `specs/{nome}/` + `projetos.yaml`** (este último em first-run).
+`$ARGUMENTS` = nome do scope (ex: `app_barbearia`, `feat_cadastro_cliente`).
+
+Em **first-run** (docs/ ausente): cria docs/ a partir do PRD+TRD + projetos.yaml + specs/.
+Em **feature** (docs/ existe): não cria docs/ (vem pelo /sf-merge-docs depois do /sf-dev) + gera apenas specs/ do scope atual.
+
+## Agente: Architect (Opus)
+
+Técnico e preciso. Deriva projeções a partir dos docs source sem reinventar decisões.
+
+## Pré-condições
+
+| # | Validação | Se falhar |
+|---|-----------|-----------|
+| 1 | `$ARGUMENTS` informado | Parar |
+| 2 | `.context.md` existe com status `extract_done` ou posterior | Se anterior → "/sf-extract $ARGUMENTS primeiro" |
+| 3 | Se `prd_existe=true`: `PRD.md` existe E `prd_aprovado=true` | Parar, listar ambiguidades pendentes (ver bloco abaixo) |
+| 4 | Se `trd_existe=true`: `TRD.md` existe E `trd_aprovado=true` | Parar, listar ambiguidades pendentes |
+| 5 | Pelo menos um dos 2 existe e está aprovado | Parar → "Extração falhou — nenhum doc aprovado" |
+
+Quando parar por ambiguidade:
+
+```
+Ambiguidades pendentes em PRD §12 / TRD §10:
+
+  AMB-PRD-001: {pergunta}
+  AMB-TRD-002: {pergunta}
+
+Como responder:
+  1. Abra workspace/Output/$ARGUMENTS/PRD.md (ou TRD.md)
+  2. Vá até §Ambiguidades e preencha a coluna `Resposta`
+  3. Marque prd_aprovado=true (ou trd_aprovado=true) em .context.md
+  4. Rode /sf-design $ARGUMENTS de novo
+
+Mais detalhes em .github/skills/sf-extract/SKILL.md → "Como responder ambiguidades".
+```
+
+## Passos
+
+### 1. Carregar contexto
+
+- `.context.md` → `first_run`, `prd_existe`, `trd_existe`, `areas_tocadas` (vazio, vai popular)
+- `workspace/Output/$ARGUMENTS/PRD.md` (se `prd_existe=true`)
+- `workspace/Output/$ARGUMENTS/TRD.md` (se `trd_existe=true`)
+- `docs/` (se existir — feature mode): baseline cross-feature
+- `discovery.md` (se existir): análise prévia
+- `.github/rules.md`
+- Templates:
+  - `.github/templates/specs/{brief,contracts,scenarios}.template.md`
+  - `.github/templates/estrutura/*.template.md` (só se first-run)
+  - `.github/templates/feature/projetos.template.yaml` (só se first-run)
+
+### 2. Determinar áreas tocadas
+
+Ler GATEs do TRD §2-§5 (se TRD existe). Áreas marcadas como `GATE: SIM` vão pra
+`.context.md → areas_tocadas: [...]`.
+
+Se TRD não existe (scope puro-produto, raro): `areas_tocadas = []`; `/sf-plan` vai
+gerar só tasks de frontend com base no PRD §7.
+
+### 3. Branch first-run vs feature
+
+Ler `first_run` do `.context.md`.
+
+#### Branch A — first_run = true (bootstrap)
+
+1. **Gerar `docs/`** (5 arquivos em `docs/` na raiz do projeto):
+
+   | Doc gerado | Fontes |
+   |-----------|--------|
+   | `architecture.md` | TRD §1.1 Stack + §1.2 Arquitetura + §1.3 Ambientes + §1.4 Deploy + §5 §Área-Infra |
+   | `domain.md` | PRD §1 Contexto + §2 Atores + §3 Jornadas (resumo) + TRD §4 §Área-DB |
+   | `conventions.md` | TRD §1.5 Segurança baseline + §7 Segurança detalhada + §5.3 Env vars + §5.4 Monitoramento |
+   | `apiContracts.md` | TRD §2.1 Endpoints + convenções de rota inferidas |
+   | `decisions.md` | TRD §9 ADRs (transcritas como ADR-001, ADR-002... imutáveis) |
+
+   Regras:
+   - Ler template → preencher TODAS as seções com dados do PRD/TRD
+   - Remover bloco `<!-- INSTRUÇÕES -->` do doc gerado
+   - Changelog inicia vazio
+   - Se PRD ou TRD não tem dados pra uma seção → "A definir" (não deixar vazio)
+
+2. **Gerar `projetos.yaml`** na raiz:
+
+   - Identificar serviços separados no TRD §1.2 Containers (api, worker, web, etc.)
+   - Perguntar ao usuário: organização GitHub, nome base, se algum repo já existe
+   - Mapear áreas → repos (API+DB costumam ir juntos; Frontend separado)
+   - Validar: cada área em `areas_tocadas` tem repo correspondente
+
+3. **Gerar `specs/$ARGUMENTS/`** (passo 4 abaixo, comum a first-run e feature)
+
+#### Branch B — first_run = false (feature)
+
+1. **Não toca em `docs/`** (isso é trabalho do /sf-merge-docs após /sf-dev)
+2. **Não gera `projetos.yaml`** (já existe do first-run)
+3. **Gera apenas `specs/$ARGUMENTS/`**
+
+### 4. Gerar `specs/$ARGUMENTS/` (sempre)
+
+Criar/sobrescrever os 4 arquivos em `specs/$ARGUMENTS/`:
+
+| Arquivo | Projeção de | Conteúdo |
+|---------|-------------|----------|
+| `brief.md` | PRD §1 + §10 + §11 + TRD §1 | Problema, Solução, Serviços tocados (de projetos.yaml), Escopo (Dentro/Fora), Decisões principais (ADRs resumidas) |
+| `contracts.md` | TRD §4 + §2.3 + §2.1 + §6 + PRD §5 | Dados (schema), Validações de Entrada, API (endpoints específicos), Integrações externas, Regras de Negócio com enforcement point |
+| `scenarios.md` | PRD §3 + §8 + §7 + TRD §8 | Pré-condições globais, Fluxos happy path, Fluxos de erro (com Ref CA), UI por componente, CAs com Given/When/Then, Estratégia de testes |
+| `tasks.md` | stub | (preenchido pelo `/sf-plan`) |
+
+Regras:
+- Projeções são **REGENERÁVEIS** — ao re-rodar `/sf-design`, sobrescreve
+- NUNCA editar direto em `specs/` — PRD/TRD são as fontes
+- Templates em `.github/templates/specs/`
+- Coders e Reviewer leem daqui, NUNCA de PRD/TRD direto
+
+### 5. Validação de consistência
+
+Antes de terminar, verificar:
+- Cada RN do PRD §5 aparece em `contracts.md → Regras de Negócio` com enforcement point
+- Cada endpoint do TRD §2.1 aparece em `contracts.md → API`
+- Cada CA em `scenarios.md` mapeia pra pelo menos 1 RN ou 1 jornada
+- Áreas em `areas_tocadas` têm entries em `contracts.md` e `scenarios.md`
+
+Divergências → alertar no output, sem falhar.
+
+### 6. Atualizar `.context.md`
+
+```yaml
+status: "design_done"
+areas_tocadas: [BACK, DB, ...]   # derivado do passo 2
+ultima_skill: "/sf-design"
+atualizado_em: "{{ISO_DATETIME}}"
+```
+
+### 7. Saída obrigatória
+
+```
+/sf-design $ARGUMENTS — completo ({{first-run | feature}})
+
+Artefatos:
+  - specs/$ARGUMENTS/brief.md
+  - specs/$ARGUMENTS/contracts.md
+  - specs/$ARGUMENTS/scenarios.md
+  - specs/$ARGUMENTS/tasks.md (stub — será preenchido por /sf-plan)
+  (se first-run:)
+  - docs/architecture.md, domain.md, conventions.md, apiContracts.md, decisions.md
+  - projetos.yaml
+
+Áreas tocadas: [BACK, DB, FRONT, INFRA]
+Validação: {{N issues / passed}}
+
+Próximo passo: /sf-plan $ARGUMENTS
+```
+
+## Regra de ouro
+
+- `/sf-design` NUNCA reinventa decisões. Apenas projeta PRD+TRD pra formatos consumíveis.
+- Se precisa de uma decisão nova que não está no PRD ou TRD: é ambiguidade — voltar pra `/sf-extract` com novo insumo.
+- Divergências entre PRD e TRD: **PRD vence em produto, TRD vence em técnica** (não há overlap por design).