docs: align guide and templates

GUIA-SDSD.md

@@ -37,6 +37,28 @@ copiados. Este repositório contém o guia, os templates em `templates/` e o
 contexto compartilhado em `.harness/`; ele não pretende ser uma aplicação já
 instalada.
 
+### Fronteira entre o kit e o projeto consumidor
+
+Use esta regra para ligar cada artefato ao seu dono:
+
+| Camada | Artefatos | Papel no fluxo |
+|---|---|---|
+| Metodologia | `GUIA-SDSD.md` | Define etapas, gates, prompts e critérios de escala |
+| Bootstrap | `templates/` | Fornece os arquivos iniciais para um projeto consumidor |
+| Constituição | `projeto/specs/mission.md`, `principles.md`, `tech-stack.md`, `roadmap.md` | Define propósito, limites, stack e ordem do trabalho |
+| Feature | `projeto/specs/YYYY-MM-DD-nome/` | Converte uma fase em requisitos, plano, segurança e validação executáveis |
+| Governo dos agentes | `projeto/AGENTS.md`, `projeto/.claude/`, `projeto/skills/` | Aplica regras, perfis e automações durante a execução |
+| Verificação | `projeto/.pre-commit-config.yaml`, `projeto/.github/workflows/` | Bloqueia problemas localmente e antes do merge |
+| Memória e histórico | `projeto/specs/STATE.md`, `projeto/specs/adr/`, `projeto/CHANGELOG.md` | Preserva contexto, decisões irreversíveis e mudanças confirmadas |
+
+Os arquivos equivalentes na raiz deste repositório (`specs/`, `.harness/` e
+`.github/workflows/`) pertencem ao desenvolvimento do próprio kit. Não são,
+automaticamente, a constituição, o contexto ou o CI de uma aplicação consumidora.
+
+Para instalar o kit, siga `templates/README.md`; para operar uma feature, siga
+os Passos 1 a 5 desta parte. Assim, cada etapa tem uma fonte, um destino e um
+gate verificável.
+
 ```
 projeto/
 ├── specs/                          ← Constituição + specs de funcionalidades
@@ -62,8 +84,7 @@ projeto/
 │   └── commands/                   ← Slash commands customizados (opcional)
 ├── skills/                         ← Skills reutilizáveis (progressive disclosure)
 │   ├── changelog/
-│   │   ├── SKILL.md                ← Frontmatter + descrição (sempre carregado)
-│   │   └── scripts/changelog.py    ← Carregado só quando a skill é invocada
+│   │   └── SKILL.md                ← Frontmatter + workflow (carregado quando invocado)
 │   └── feature-spec/
 │       └── SKILL.md
 ├── AGENTS.md                       ← Fonte única das regras de código (exportada para cada ferramenta)
@@ -409,7 +430,7 @@ Faça commit, mude para main, faça merge --no-ff e exclua a branch.
 
 **O que acontece:**
 1. Agente edita `roadmap.md` → adiciona `✅` na fase concluída
-2. Roda `python3 skills/changelog/scripts/changelog.py` → atualiza `CHANGELOG.md`
+2. Invoca a skill `changelog` → atualiza `CHANGELOG.md` conforme o histórico real
 3. (Se aplicável) Cria ADR em `specs/adr/`
 4. `git add` → `git commit` → `git checkout main` → `git merge --no-ff` → `git branch -d`
 

README.md

@@ -6,6 +6,26 @@ Este repositório é o **manual e o kit de templates** da metodologia. Ele não
 projeto de aplicação já configurado: a estrutura `specs/`, os agentes e as skills
 descritos no guia são criados no projeto que adota o SDSD, a partir de `templates/`.
 
+## 🧭 Como as partes se conectam
+
+Existem dois contextos que não devem ser misturados:
+
+| Contexto | Fonte | Responsabilidade |
+|---|---|---|
+| Kit SDSD | `GUIA-SDSD.md`, `templates/`, `.harness/`, `.github/workflows/` | Ensinar, fornecer e validar a metodologia |
+| Projeto consumidor | `specs/`, `AGENTS.md`, `skills/`, `.claude/`, `.pre-commit-config.yaml` e código | Aplicar a metodologia a um produto real |
+
+O caminho semântico é:
+
+`GUIA-SDSD.md` define o fluxo → `templates/` materializa o bootstrap →
+`specs/` registra a constituição e cada feature → `AGENTS.md` governa os agentes
+→ `skills/` automatiza tarefas repetíveis → `.claude/` fornece perfis de agente
+→ pre-commit e CI validam → `CHANGELOG.md`, ADRs e `STATE.md` preservam o resultado.
+
+O diretório `.harness/` contém o contexto operacional deste kit. Ele orienta a
+manutenção do próprio repositório e só deve ser levado a um projeto consumidor
+quando o time decidir adotar esse contexto como parte de sua governança.
+
 ## 🧠 O que é SDSD?
 
 SDSD é um fluxo de trabalho onde **toda funcionalidade começa com especificações rigorosas escritas ANTES do código**. Em vez de usar "prompts soltos" ou tratar a Inteligência Artificial como um adivinho de ideias vagas, a IA é usada para materializar e codificar especificações formais, mantendo o humano estritamente no controle da direção do produto, da arquitetura e da qualidade final (UX).
@@ -45,7 +65,7 @@ Skill `changelog` atualiza o `CHANGELOG.md`. Decisões irreversíveis viram um A
 ## 📖 Documentação e Templates
 
 - 👉 **[Guia técnico completo (GUIA-SDSD.md)](GUIA-SDSD.md)** — fluxo detalhado, prompts, prevenção de N+1/race conditions/memory leaks, CI/CD
-- 📁 **[Templates prontos (`templates/`)](templates/)** — `principles.md`, `AGENTS.md`, `.pre-commit-config.yaml` e subagent `security-auditor` para copiar direto no seu projeto
+- 📁 **[Templates prontos (`templates/`)](templates/)** — constituição, specs de feature, skills, agentes e pre-commit para copiar direto no seu projeto
 
 O diretório [`.harness/`](.harness/) contém contexto operacional reutilizável,
 como glossário, limites, padrões e modelos de registros. Ele complementa os

templates/README.md

@@ -1,6 +1,6 @@
 # Templates SDSD
 
-Cópias prontas dos arquivos referenciados no [GUIA-SDSD.md](../GUIA-SDSD.md). Copie para a raiz do seu projeto e ajuste os placeholders entre `[colchetes]`.
+Cópias prontas dos arquivos referenciados no [GUIA-SDSD.md](../GUIA-SDSD.md). Eles materializam o bootstrap do projeto consumidor; ajuste os placeholders entre `[colchetes]` depois do Grill.
 
 ## Conteúdo
 
@@ -14,7 +14,7 @@ Cópias prontas dos arquivos referenciados no [GUIA-SDSD.md](../GUIA-SDSD.md). C
 | [`specs/_feature/`](specs/_feature/) | `specs/YYYY-MM-DD-nome/` | Stubs de todos os artefatos de uma feature |
 | [`AGENTS.md`](AGENTS.md) | `AGENTS.md` (raiz) | Sempre — fonte única das regras de código (PARTE 10) |
 | [`.pre-commit-config.yaml`](.pre-commit-config.yaml) | `.pre-commit-config.yaml` (raiz) | Quando configurar o shift-left local (PARTE 4.1) |
-| [`.claude/agents/security-auditor.md`](.claude/agents/security-auditor.md) | `.claude/agents/security-auditor.md` | Quando usar Claude Code com subagents reais (PARTE 6) |
+| [`.claude/agents/`](.claude/agents/) | `.claude/agents/` | Perfis `security-auditor`, `code-reviewer`, `feature-developer` e `performance-optimizer` (PARTE 6) |
 | [`skills/`](skills/) | `skills/` | Skills reutilizáveis de changelog e feature spec |
 
 ## Setup rápido
@@ -25,17 +25,27 @@ cp -r templates/specs        /caminho/do/seu/projeto/
 cp    templates/AGENTS.md    /caminho/do/seu/projeto/
 cp    templates/.pre-commit-config.yaml /caminho/do/seu/projeto/
 cp -r templates/.claude      /caminho/do/seu/projeto/
+cp -r templates/skills       /caminho/do/seu/projeto/
 
 # 2. Ative o pre-commit
 cd /caminho/do/seu/projeto
 pipx install pre-commit
 pre-commit install
 
-# 3. Edite os placeholders [entre colchetes] em principles.md e AGENTS.md
+# 3. Leia specs/ e faça o Grill descrito no guia
+# 4. Preencha os placeholders [entre colchetes] em specs/ e AGENTS.md
+# 5. Exporte AGENTS.md para as ferramentas usadas pelo time
 ```
 
+> Este diretório não instala o CI do kit. Crie ou adapte os workflows do projeto
+> consumidor em `.github/workflows/`, conforme a stack definida em
+> `specs/tech-stack.md`. O `.harness/` deste repositório também não é copiado por
+> padrão: ele guarda contexto de manutenção do kit.
+
 ## Próximos passos
 
-1. Edite os placeholders da constituição e do `AGENTS.md`.
-2. Copie `specs/_feature/` para uma pasta datada quando iniciar uma feature.
-3. Sincronize `AGENTS.md` para `CLAUDE.md` e demais ferramentas (PARTE 10 do guia).
+1. Complete `specs/mission.md`, `principles.md`, `tech-stack.md` e `roadmap.md`.
+2. Escolha a próxima fase e copie `specs/_feature/` para uma pasta datada.
+3. Faça o Grill e preencha os artefatos da feature antes de escrever código.
+4. Execute `EXECUTE.md`, valide e só então confirme com changelog, ADR e `STATE.md`.
+5. Sincronize `AGENTS.md` para `CLAUDE.md` e demais ferramentas (PARTE 10 do guia).