spec-first-copilot 0.6.0-beta.9 → 0.7.0

package/templates/.github/copilot-instructions.md

@@ -1,262 +1,272 @@
-# Copilot Instructions — Projeto
-
-> Regras globais que o agente deve seguir em TODAS as interações neste projeto.
-> Este arquivo é lido automaticamente no início de cada sessão.
-
----
-
-## Inicialização (executar no início de cada sessão)
-
-### 1. Verificar dependências do workflow
-
-| Dependência | Caminho | Se não existir |
-|-------------|---------|----------------|
-| Napkin (memória) | `.ai/memory/napkin.md` | Criar com formato padrão: seções Decisões, Padrões, Armadilhas, Preferências (máx 10 itens/seção) |
-| Templates | `.github/templates/` | ERRO — projeto não está configurado |
-| Skills | `.github/skills/` | ERRO — projeto não está configurado |
-| Agents | `.github/agents/` | ERRO — projeto não está configurado |
-| Rules | `.github/rules.md` | ERRO — projeto não está configurado |
-| CHANGELOG do framework | `.github/CHANGELOG.md` | OK — projeto antigo sem update |
-| Retomada | `workspace/Output/retomada.md` | OK — primeira sessão |
-
-### 2. Validar acesso a todas skills
-
-Verificar que TODAS as 11 skills estão acessíveis:
-
-| Skill | Caminho |
-|-------|---------|
-| `/sf-mcp` | `.github/skills/sf-mcp/SKILL.md` |
-| `/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-discovery` | `.github/skills/sf-discovery/SKILL.md` |
-| `/sf-extract` | `.github/skills/sf-extract/SKILL.md` |
-| `/sf-design` | `.github/skills/sf-design/SKILL.md` |
-| `/sf-plan` | `.github/skills/sf-plan/SKILL.md` |
-| `/sf-dev` | `.github/skills/sf-dev/SKILL.md` |
-| `/sf-merge-docs` | `.github/skills/sf-merge-docs/SKILL.md` |
-| `/sf-session-finish` | `.github/skills/sf-session-finish/SKILL.md` |
-
-Se alguma skill não for encontrada → avisar o usuário.
-
-### 3. Carregar contexto
-
-1. Ler `.ai/memory/napkin.md` — decisões e padrões acumulados
-2. Ler `workspace/Output/retomada.md` (se existir) — ponto de retomada da última sessão
-3. Ler `docs/` (se existir) — contexto global do projeto (architecture, domain, conventions, apiContracts, decisions)
-4. Ler `.github/rules.md` — regras de desenvolvimento
-
----
-
-## Identidade do Projeto
-
-Este é um projeto que utiliza desenvolvimento **spec-first** assistido por IA.
-Nenhum código é escrito sem especificação aprovada (SDD).
-
-### Arquitetura: Projeto-base vs Repos de código
-
-```
-ESTE REPO (projeto-base) = ORQUESTRADOR
-├── .github/        ← AI operational config (rules, templates, skills, agents)
-├── .ai/            ← memória persistente (napkin, publish-log, load-log)
-├── docs/           ← síntese cross-feature (architecture, domain, conventions, apiContracts, decisions)
-├── specs/          ← projeções do SDD pro coder (brief, contracts, scenarios, tasks)
-├── workspace/      ← content compartilhável
-│   ├── Input/      ← insumos brutos do time
-│   └── Output/     ← outputs por scope (PRD, SDD, Progresso)
-├── sfw.config.yml  ← manifesto de adapters (input/output backends)
-├── projetos.yaml   ← manifesto de repos (gerado pelo /sf-design em first-run)
-└── projetos/       ← repos de código (gitignored, cada um com .git próprio)
-    ├── api/        ← repo: org/projeto-api
-    ├── web/        ← repo: org/projeto-web
-    └── worker/     ← repo: org/projeto-worker
-```
-
-**Três zonas, zero ambiguidade:**
-- **`.github/` + `.ai/`** → AI operational config + memória (time edita raro)
-- **`docs/`** → síntese cross-feature (atualizada pelo `/sf-merge-docs`)
-- **`workspace/`** → content compartilhável (Input = time, Output = workflow)
-- **`projetos/`** → código dos serviços (branches, PRs, commits acontecem aí)
-
-## Pipeline do Workflow
-
-```
-/sf-start <nome>
-    ↓ detecta first_run via presença/ausência de docs/
-    ↓ /sf-load <nome> (puxa insumos do backend) → workspace/Input/{nome}/
-    ↓ /sf-discovery (opcional, recomendado)
-    ↓
-/sf-extract → PRD.md (pode ser empty) + extract-log com tech chunks
-    ↓ checkpoint: usuário aprova
-/sf-design
-    ↓ first_run=true: SDD §Sistema completo + cria docs/ + projetos.yaml
-    ↓ first_run=false: SDD §Área-X tocadas + §11 Delta Specs
-    ↓ sempre: gera specs/{nome}/ (brief/contracts/scenarios)
-/sf-plan → specs/{nome}/tasks.md + Progresso.md (tasks com campo Repo:)
-    ↓
-/sf-dev → INFRA-001 cria/clona repos (se first-run) → código nos repos (Security Review pós-dev)
-    ↓ ao final, chama /sf-merge-docs automaticamente
-/sf-merge-docs → aplica SDD §11 em docs/ (síntese cross-feature atualizada)
-```
-
-## Skills disponíveis
-
-| Skill | Tipo | O que faz |
-|-------|------|-----------|
-| `/sf-mcp <provider>` | Setup | Configura backend externo interativamente. Cria .mcp.json + sfw.config.yml + ajusta .gitignore |
-| `/sf-load <nome> \| --all` | Utilitária | Puxa Input + Output do backend. Incremental |
-| `/sf-publish <nome> <tipo>` | Utilitária | Publica artefato (PRD/SDD/Progresso) nos output.targets[]. Chamado auto por extract/design/plan |
-| `/sf-start <nome>` | Orquestrador | Entrada única do pipeline. Detecta first_run, cria .context.md, chama /sf-load + /sf-extract, para no checkpoint |
-| `/sf-discovery <path>` | Utilitária | Análise profunda dos insumos (RECOMENDADO antes do /sf-extract) |
-| `/sf-extract <nome>` | Atômica | Lê workspace/Input/{nome}/ → gera PRD + categoriza tech chunks no extract-log. Re-executável |
-| `/sf-design <nome>` | Atômica | Pergunta aprovação → gera SDD. first_run cria docs/ + projetos.yaml; feature gera só áreas tocadas |
-| `/sf-plan <nome>` | Atômica | Lê SDD → gera tasks por área + Progresso.md |
-| `/sf-dev <nome>` | Atômica | Implementa tasks com loop (implement → test → review). Agents por área. /sf-merge-docs automático no fim |
-| `/sf-merge-docs <nome>` | Atômica | Aplica SDD §11 Delta Specs em docs/ (cross-feature sync). Chamado pelo /sf-dev, re-executável |
-| `/sf-session-finish` | Utilitária | Encerra sessão: salva estado, atualiza napkin, gera retomada.md |
-
-## Agents especializados (usados pelo /sf-dev)
-
-| Agent | Área | Stack padrão | Perfil |
-|-------|------|-------------|--------|
-| Backend Coder | BACK | .NET 8 / C# | `.github/agents/backend-coder.md` |
-| Frontend Coder | FRONT | React + Fusion | `.github/agents/frontend-coder.md` |
-| DB Coder | DB | PostgreSQL 16 | `.github/agents/db-coder.md` |
-| Infra Coder | INFRA | Docker | `.github/agents/infra-coder.md` |
-| Doc Writer | DOC | — | `.github/agents/doc-writer.md` |
-| Reviewer | Todas | — | `.github/agents/reviewer.md` |
-| Security Reviewer | Todas | — | `.github/agents/security-reviewer.md` |
-
-## Estado da pipeline (`.context.md`)
-
-Cada scope tem um `.context.md` em `workspace/Output/{nome}/`:
-
-```yaml
-nome: "{nome}"
-first_run: true|false    # imutável, derivado da ausência de docs/
-prd_empty: true|false    # preenchido pelo /sf-extract
-areas_tocadas: [...]     # preenchido pelo /sf-design
-input_path: "workspace/Input/{nome}/"
-status: not_started → extract_done → approved → design_done → plan_done → dev_in_progress → dev_done → done
-ultima_skill: "/sf-start"
-atualizado_em: "ISO_DATETIME"
-```
-
-Antes de executar qualquer skill, verificar o status. Cada skill só avança se o status anterior está correto. **Apenas skills atualizam `.context.md`** — usuário nunca edita manualmente.
-
-## Regras Invioláveis
-
-1. **Spec-first**: NUNCA gerar código sem SDD aprovado
-2. **Input é sagrado**: NUNCA modificar arquivos em `workspace/Input/`
-3. **Extração rígida**: categorias fixas do template, sem texto narrativo, ambiguidades são BLOQUEANTES
-4. **Consulta docs/ antes de ambiguidade**: Analyzer valida se resposta já está em `docs/` — se sim, marca resolvida, não pergunta
-5. **SDD é auto-contido**: coder lê APENAS specs/{nome}/ + task, NUNCA PRD/PM diretamente
-6. **Memória ativa**: ler napkin.md no início, atualizar ao descobrir padrões/armadilhas
-7. **Progresso atualizado**: atualizar Progresso.md ao concluir cada task
-8. **Delta Specs**: todo SDD tem §11 ADDED/MODIFIED/REMOVED — obrigatório (mesmo vazio)
-9. **Testes junto com código**: implementar e testar na mesma task, não separar
-
-## Estrutura de Documentação
-
-```
-.github/                     ← AI OPERATIONAL CONFIG
-├── copilot-instructions.md  ← Regras globais pro agente (este arquivo)
-├── rules.md                 ← Regras de desenvolvimento (lidas pelos coders)
-├── CHANGELOG.md             ← Histórico do framework (sobrescrito pelo `update`)
-├── templates/               ← Templates do workflow
-│   ├── feature/             ← PRD, SDD, context, extract-log, Progresso, backlog-extraido, projetos.yaml
-│   ├── specs/               ← brief, contracts, scenarios, tasks (projeções pro agent)
-│   ├── estrutura/           ← architecture, domain, conventions, apiContracts, decisions
-│   └── global/              ← progresso_global
-├── adapters/                ← SourceAdapter interface + ConfluenceAdapter + FilesystemAdapter
-├── skills/                  ← 11 skills (sf-mcp, sf-load, sf-publish, sf-start, sf-discovery, sf-extract, sf-design, sf-plan, sf-dev, sf-merge-docs, sf-session-finish)
-├── agents/                  ← 7 perfis de agents especializados
-└── instructions/            ← Instruções por contexto
-
-docs/                        ← SÍNTESE CROSS-FEATURE (atualizada pelo /sf-merge-docs)
-├── architecture.md          ← Stack + C4 + ambientes + deploy
-├── domain.md                ← Visão de negócio + modelo de dados consolidado
-├── conventions.md           ← Auth, authz, LGPD, env vars, monitoramento
-├── apiContracts.md          ← Convenções + catálogo de endpoints
-└── decisions.md             ← ADRs (append-only)
-
-specs/                       ← AGENT CONTRACTS (projeções do SDD pro coder)
-└── {nome}/
-    ├── brief.md             ← SDD §1+§2+§10 (Problema/Solução/Escopo)
-    ├── contracts.md         ← SDD §3+§4+§5+§6+§7 (§Sistema + áreas tocadas)
-    ├── scenarios.md         ← SDD §5.2+§8+§9 (Fluxos/UI/CAs)
-    └── tasks.md             ← Tabela única com coluna Área (gerado pelo /sf-plan)
-
-workspace/                   ← TEAM CONTENT
-├── Input/                   ← Insumos brutos (QUALQUER formato — nunca modificar)
-│   └── {nome}/              ← Nomeado livremente pelo usuário (ex: app_barbearia, feat_login)
-└── Output/                  ← Artefatos humanos gerados pelo workflow
-    └── {nome}/
-        ├── PRD.md           ← Requirements de produto (gerado pelo /sf-extract; pode ter empty: true)
-        ├── sdd.md           ← Especificação técnica narrativa (gerado pelo /sf-design)
-        ├── Progresso.md     ← Tracking de execução (gerado pelo /sf-plan)
-        ├── backlog_extraido.md ← (opcional) features fora-de-escopo detectadas em first-run
-        ├── .context.md      ← Estado da pipeline
-        ├── .extract-log.md  ← Log de hashes + categorização tech
-        ├── discovery.md     ← (opcional) análise do /sf-discovery
-        └── retomada.md      ← (session-finish) ponto de retomada
-
-projetos/                    ← Repos de serviços (gitignored, cada um com .git próprio)
-projetos.yaml                ← Manifesto: serviço → repo → áreas → stack (gerado em first-run)
-sfw.config.yml               ← Manifesto de adapters (input/output backends)
-```
-
-**Quem lê o quê:**
-- **Humano**: `workspace/Output/` (PRD/SDD narrativos + Progresso) + `docs/` (onboarding)
-- **Coder agent**: `specs/{nome}/` (projeções estruturadas) — NUNCA lê SDD direto
-- **Reviewer**: `specs/{nome}/scenarios.md` (CAs) + código
-- **Security Reviewer**: `specs/{nome}/contracts.md` + `docs/conventions.md` + código
-- **`/sf-merge-docs`**: `workspace/Output/{nome}/sdd.md` §11 (única leitura do SDD pelo pipeline)
-
-## Convenções
-
-- **Pastas de scope** (convenção sugerida, opcional): `feat_nome`, `bug_nome`, `task_nome`, ou bootstrap como `app_nome` (snake_case)
-- **Task IDs**: `AREA-NNN` (BACK-001, FRONT-001, DB-001, INFRA-001)
-- **Regras de negócio**: `RN-NNN` (IDs estáveis, nunca renumerar)
-- **Commits**: `tipo(TASK-ID): descrição` (feat, fix, refactor, test, docs, chore)
-- **Branches**: `feature/{nome}_fase{N}` (fase vem do PRD §11 Fases de Entrega)
-
-## Quando Parar e Perguntar
-
-- `workspace/Input/{nome}/` vazio ou inexistente → PARAR
-- Ambiguidade na extração (não coberta por `docs/`) → listar como pergunta BLOQUEANTE, PARAR
-- `.context.md` com status incompatível com a skill → PARAR, informar status atual
-- Task com dependência não concluída → avisar, não pular
-- Dúvida sobre regra de negócio → perguntar, NUNCA assumir
-- Quality gate reprovado 3x → escalar pro usuário
-
-## Arquivos Sensíveis
-
-### NUNCA modificar
-- `workspace/Input/**/*` — Insumos brutos. Somente leitura.
-- `.env`, `.env.*`, `.mcp.json` — Secrets.
-- `docs/decisions.md` — ADRs aceitas são imutáveis (apenas adicionar novas, com status "substituída por ADR-XXX" na original).
-
-### Requerem aprovação
-- `docs/*` — Só alterar via `/sf-merge-docs` após `/sf-dev`.
-- `.github/rules.md` — Alteração explícita.
-- `.github/copilot-instructions.md` — Meta-regras. Alteração requer aprovação.
-- `.github/skills/*`, `.github/agents/*`, `.github/templates/*` — Alteração requer aprovação.
-- `sfw.config.yml` — Manifesto de adapters. Mudar via `/sf-mcp` ou edição explícita.
-
-## Referências
-
-| Doc | Onde |
-|-----|------|
-| Rules de dev | `.github/rules.md` |
-| CHANGELOG do framework | `.github/CHANGELOG.md` |
-| Memória | `.ai/memory/napkin.md` |
-| Skills | `.github/skills/*/SKILL.md` |
-| Agents | `.github/agents/*.md` |
-| Templates | `.github/templates/` |
-| Adapters | `.github/adapters/` |
-| Síntese do sistema | `docs/*.md` |
-| Especialistas por scope | `workspace/Output/{nome}/sdd.md` |
-| Projeções pro coder | `specs/{nome}/*.md` |
-| Insumos brutos | `workspace/Input/` |
-| Outputs do workflow | `workspace/Output/` |
+# Copilot Instructions — Projeto
+
+> Regras globais para TODAS as interações neste projeto.
+> Lido automaticamente no início de cada sessão.
+
+---
+
+## Inicialização (executar no início de cada sessão)
+
+### 1. Verificar dependências do workflow
+
+| Dependência | Caminho | Se não existir |
+|-------------|---------|----------------|
+| Napkin (memória) | `.ai/memory/napkin.md` | Criar com formato padrão |
+| Templates | `.github/templates/` | ERRO — projeto não está configurado |
+| Commands | `.github/commands/` | ERRO — projeto não está configurado |
+| Agents | `.github/agents/` | ERRO — projeto não está configurado |
+| Rules | `.github/rules.md` | ERRO — projeto não está configurado |
+| CHANGELOG do framework | `.github/CHANGELOG.md` | OK — projeto antigo sem update |
+| Retomada | `workspace/Output/retomada.md` | OK — primeira sessão |
+
+### 2. Validar acesso a todos commands
+
+Verificar que TODOS os 11 commands estão acessíveis:
+
+| Command | Caminho |
+|---------|---------|
+| `/sf-mcp` | `.github/skills/sf-mcp/SKILL.md` |
+| `/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-discovery` | `.github/skills/sf-discovery/SKILL.md` |
+| `/sf-extract` | `.github/skills/sf-extract/SKILL.md` |
+| `/sf-design` | `.github/skills/sf-design/SKILL.md` |
+| `/sf-plan` | `.github/skills/sf-plan/SKILL.md` |
+| `/sf-dev` | `.github/skills/sf-dev/SKILL.md` |
+| `/sf-merge-docs` | `.github/skills/sf-merge-docs/SKILL.md` |
+| `/sf-session-finish` | `.github/skills/sf-session-finish/SKILL.md` |
+
+Se algum command não for encontrado → avisar o usuário.
+
+### 3. Carregar contexto
+
+1. Ler `.ai/memory/napkin.md` — decisões e padrões acumulados
+2. Ler `workspace/Output/retomada.md` (se existir) — ponto de retomada da última sessão
+3. Ler `docs/` (se existir) — contexto global do projeto (architecture, domain, conventions, apiContracts, decisions)
+4. Ler `.github/rules.md` — regras de desenvolvimento
+
+---
+
+## Identidade do Projeto
+
+Este é um projeto que utiliza desenvolvimento **spec-first** assistido por IA.
+Nenhum código é escrito sem especificações aprovadas (PRD + TRD).
+
+### Arquitetura: Projeto-base vs Repos de código
+
+```
+ESTE REPO (projeto-base) = ORQUESTRADOR
+├── .github/        ← AI operational config (rules, templates, commands, agents)
+├── .ai/            ← memória persistente (napkin, publish-log, load-log)
+├── docs/           ← síntese cross-feature (architecture, domain, conventions, apiContracts, decisions)
+├── specs/          ← projeções de PRD+TRD pro coder (brief, contracts, scenarios, tasks)
+├── workspace/      ← content compartilhável
+│   ├── Input/      ← insumos brutos do time
+│   └── Output/     ← outputs por scope (PRD, TRD, Progresso)
+├── sfw.config.yml  ← manifesto de adapters (input/output backends)
+├── projetos.yaml   ← manifesto de repos (gerado pelo /sf-design em first-run)
+└── projetos/       ← repos de código (gitignored, cada um com .git próprio)
+    ├── api/        ← repo: org/projeto-api
+    ├── web/        ← repo: org/projeto-web
+    └── worker/     ← repo: org/projeto-worker
+```
+
+**Três zonas, zero ambiguidade:**
+- **`.github/` + `.ai/`** → AI operational config + memória (time edita raro)
+- **`docs/`** → síntese cross-feature (atualizada pelo `/sf-merge-docs`)
+- **`workspace/`** → content compartilhável (Input = time, Output = workflow)
+- **`projetos/`** → código dos serviços (branches, PRs, commits acontecem aí)
+
+## Pipeline do Workflow
+
+```
+/sf-start <nome>
+    ↓ detecta first_run via presença/ausência de docs/
+    ↓ /sf-load <nome> (puxa insumos do backend) → workspace/Input/{nome}/
+    ↓ /sf-discovery (OBRIGATÓRIO em v4)
+    ↓
+/sf-extract → gera PRD.md e/ou TRD.md (ambos condicionais ao conteúdo dos insumos)
+    ↓ CHECKPOINT DUPLO:
+    ↓   - PM aprova PRD (marca prd_aprovado=true em .context.md)
+    ↓   - dev aprova TRD (marca trd_aprovado=true em .context.md)
+/sf-design
+    ↓ first_run=true: cria docs/ + projetos.yaml a partir de PRD+TRD aprovados
+    ↓ sempre: gera specs/{nome}/ (brief/contracts/scenarios)
+/sf-plan → specs/{nome}/tasks.md + Progresso.md (tasks com campo Repo:)
+    ↓
+/sf-dev → INFRA-001 cria/clona repos (se first-run) → código nos repos (Security Review pós-dev)
+    ↓ ao final de feature, chama /sf-merge-docs automaticamente
+/sf-merge-docs → diff semântico PRD+TRD ↔ docs/ → atualiza docs/ cross-feature
+```
+
+## Commands disponíveis (slash commands)
+
+| Command | Tipo | O que faz |
+|---------|------|-----------|
+| `/sf-mcp <provider>` | Setup | Configura backend externo interativamente. Cria .mcp.json + sfw.config.yml + ajusta .gitignore |
+| `/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-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 |
+| `/sf-plan <nome>` | Atômica | Lê PRD + TRD + specs/ → gera tasks por área + Progresso.md |
+| `/sf-dev <nome>` | Atômica | Implementa tasks com loop (implement → test → review). Agents por área. /sf-merge-docs automático no fim de features |
+| `/sf-merge-docs <nome>` | Atômica | Diff semântico PRD+TRD ↔ docs/ → atualiza docs/ cross-feature. Chamado pelo /sf-dev, re-executável |
+| `/sf-session-finish` | Utilitária | Encerra sessão: salva estado, atualiza napkin, gera retomada.md |
+
+## Agents especializados (usados pelo /sf-dev)
+
+| Agent | Área | Stack padrão | Perfil |
+|-------|------|-------------|--------|
+| Backend Coder | BACK | .NET 8 / C# | `.github/agents/backend-coder.md` |
+| Frontend Coder | FRONT | React + Fusion | `.github/agents/frontend-coder.md` |
+| DB Coder | DB | PostgreSQL 16 | `.github/agents/db-coder.md` |
+| Infra Coder | INFRA | Docker | `.github/agents/infra-coder.md` |
+| Doc Writer | DOC | — | `.github/agents/doc-writer.md` |
+| Reviewer | Todas | — | `.github/agents/reviewer.md` |
+| Security Reviewer | Todas | — | `.github/agents/security-reviewer.md` |
+
+## Estado da pipeline (`.context.md`)
+
+Cada scope tem um `.context.md` em `workspace/Output/{nome}/`:
+
+```yaml
+nome: "{nome}"
+first_run: true|false       # imutável, derivado da ausência de docs/
+prd_existe: true|false       # preenchido pelo /sf-extract
+trd_existe: true|false       # preenchido pelo /sf-extract
+prd_aprovado: true|false     # PM marca ao revisar PRD
+trd_aprovado: true|false     # dev marca ao revisar TRD
+areas_tocadas: [...]         # preenchido pelo /sf-design (dos GATEs do TRD)
+input_path: "workspace/Input/{nome}/"
+status: not_started → discovery_done → extract_done → prd_approved → trd_approved → design_done → plan_done → dev_in_progress → dev_done → done
+ultima_skill: "/sf-start"
+atualizado_em: "ISO_DATETIME"
+```
+
+Antes de executar qualquer command, verificar o status. Cada command só avança se o status anterior está correto. **Apenas commands atualizam `.context.md`** — usuário nunca edita manualmente.
+
+## Regras Invioláveis
+
+1. **Spec-first**: NUNCA gerar código sem PRD e/ou TRD aprovados
+2. **Input é sagrado**: NUNCA modificar arquivos em `workspace/Input/`
+3. **Extração rígida**: categorias fixas do template, sem texto narrativo, ambiguidades são BLOQUEANTES
+4. **Consulta docs/ antes de ambiguidade**: Analyzer valida se resposta já está em `docs/` — se sim, marca resolvida, não pergunta
+5. **Specs são auto-contidos**: coder lê APENAS `specs/{nome}/` + task, NUNCA PRD/TRD/PM diretamente
+6. **Memória ativa**: ler napkin.md no início, atualizar ao descobrir padrões/armadilhas
+7. **Progresso atualizado**: atualizar Progresso.md ao concluir cada task
+8. **docs/ é síntese cross-feature**: atualizado via /sf-merge-docs (diff PRD+TRD ↔ docs/) — nunca editado manualmente
+9. **Testes junto com código**: implementar e testar na mesma task, não separar
+10. **Não commitar sem pedir**: sempre perguntar antes de commitar
+
+## Estrutura de Documentação
+
+```
+.github/                     ← AI OPERATIONAL CONFIG
+├── rules.md                 ← Regras de desenvolvimento
+├── CHANGELOG.md             ← Histórico do framework (sobrescrito pelo `update`)
+├── templates/               ← Templates do workflow
+│   ├── feature/             ← PRD, TRD, context, extract-log, Progresso, projetos.yaml
+│   ├── specs/               ← brief, contracts, scenarios, tasks (projeções pro agent)
+│   ├── 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)
+└── agents/                  ← 7 perfis de agents especializados
+
+docs/                        ← SÍNTESE CROSS-FEATURE (atualizada pelo /sf-merge-docs)
+├── architecture.md          ← Stack + C4 + ambientes + deploy
+├── domain.md                ← Visão de negócio + modelo de dados consolidado
+├── conventions.md           ← Auth, authz, LGPD, env vars, monitoramento
+├── apiContracts.md          ← Convenções + catálogo de endpoints
+└── decisions.md             ← ADRs (append-only)
+
+specs/                       ← AGENT CONTRACTS (projeções de PRD+TRD pro coder)
+└── {nome}/
+    ├── brief.md             ← PRD §1+§10+§11 + TRD §Sistema (Problema/Solução/Serviços/Escopo)
+    ├── contracts.md         ← TRD §Área-DB + §Área-Backend + §6 Integrações + PRD §5 RNs
+    ├── scenarios.md         ← PRD §3 Jornadas + §8 Cenários + TRD §8 Estratégia de Testes
+    └── tasks.md             ← Tabela única com coluna Área (gerado pelo /sf-plan)
+
+workspace/                   ← TEAM CONTENT
+├── Input/                   ← Insumos brutos (QUALQUER formato — nunca modificar)
+│   └── {nome}/              ← Nomeado livremente pelo usuário (ex: app_barbearia, feat_login)
+└── Output/                  ← Artefatos humanos gerados pelo workflow
+    └── {nome}/
+        ├── PRD.md           ← Requirements de produto (gerado pelo /sf-extract; condicional — só se insumos têm produto)
+        ├── TRD.md           ← Requirements técnicos (gerado pelo /sf-extract; condicional — só se insumos têm técnica)
+        ├── Progresso.md     ← Tracking de execução (gerado pelo /sf-plan)
+        ├── .context.md      ← Estado da pipeline (prd_existe, trd_existe, aprovações, status)
+        ├── .extract-log.md  ← Log de hashes dos insumos
+        ├── discovery.md     ← análise do /sf-discovery (obrigatório em v4)
+        └── retomada.md      ← (session-finish) ponto de retomada
+
+projetos/                    ← Repos de serviços (gitignored, cada um com .git próprio)
+projetos.yaml                ← Manifesto: serviço → repo → áreas → stack (gerado em first-run)
+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
+- **Reviewer**: `specs/{nome}/scenarios.md` (CAs) + código
+- **Security Reviewer**: `specs/{nome}/contracts.md` + `docs/conventions.md` + código
+- **`/sf-merge-docs`**: `workspace/Output/{nome}/PRD.md + TRD.md` (diff semântico pra atualizar docs/)
+
+## Convenções
+
+- **Pastas de scope** (convenção sugerida, opcional): `feat_nome`, `bug_nome`, `task_nome`, ou bootstrap como `app_nome` (snake_case)
+- **Task IDs**: `AREA-NNN` (BACK-001, FRONT-001, DB-001, INFRA-001)
+- **Regras de negócio**: `RN-NNN` (IDs estáveis, nunca renumerar)
+- **Commits**: `tipo(TASK-ID): descrição` (feat, fix, refactor, test, docs, chore)
+- **Branches**: `feature/{nome}_fase{N}` (fase vem do PRD §11 Fases de Entrega)
+
+## Quando Parar e Perguntar
+
+- `workspace/Input/{nome}/` vazio ou inexistente → PARAR
+- Ambiguidade na extração (não coberta por `docs/`) → listar como pergunta BLOQUEANTE, PARAR
+- `.context.md` com status incompatível com o command → PARAR, informar status atual
+- Task com dependência não concluída → avisar, não pular
+- Dúvida sobre regra de negócio → perguntar, NUNCA assumir
+- Quality gate reprovado 3x → escalar pro usuário
+
+## Arquivos Sensíveis
+
+### NUNCA modificar
+- `workspace/Input/**/*` — Insumos brutos. Somente leitura.
+- `.env`, `.env.*`, `.mcp.json` — Secrets.
+- `docs/decisions.md` — ADRs aceitas são imutáveis (apenas adicionar novas, com status "substituída por ADR-XXX" na original).
+
+### Requerem aprovação
+- `docs/*` — Só alterar via `/sf-merge-docs` após `/sf-dev`.
+- `.github/rules.md` — Alteração explícita.
+- `copilot-instructions.md` — Meta-regras. Alteração requer aprovação.
+- `.github/commands/*`, `.github/agents/*`, `.github/templates/*` — Alteração requer aprovação.
+- `sfw.config.yml` — Manifesto de adapters. Mudar via `/sf-mcp` ou edição explícita.
+
+### Formato rígido (gerados por commands)
+- `.context.md` — YAML frontmatter, apenas commands atualizam.
+- `.extract-log.md` — Append-only, hashes obrigatórios.
+- `PRD.md`, `TRD.md` — Seguir template exato.
+- `specs/{nome}/tasks.md` — IDs sequenciais, campos obrigatórios.
+- `Progresso.md` — Tabelas com formato fixo.
+
+## Referências
+
+| Doc | Onde |
+|-----|------|
+| Rules de dev | `.github/rules.md` |
+| CHANGELOG do framework | `.github/CHANGELOG.md` |
+| Memória | `.ai/memory/napkin.md` |
+| Commands | `.github/commands/*.md` |
+| Agents | `.github/agents/*.md` |
+| Templates | `.github/templates/` |
+| Adapters | `.github/adapters/` |
+| Síntese do sistema | `docs/*.md` |
+| Source técnico por scope | `workspace/Output/{nome}/TRD.md` |
+| Projeções pro coder | `specs/{nome}/*.md` |
+| Insumos brutos | `workspace/Input/` |
+| Outputs do workflow | `workspace/Output/` |