@mir-code/specs-platform 1.0.1

package/assets/template/.agents/skills/mermaid-diagramming/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: mermaid-diagramming
+description: Como escrever diagramas Mermaid elegantes, legíveis e que renderizam de primeira na Specs Platform — escolha do tipo de diagrama, layout, paleta e classDef do tema escuro, limites de tamanho, e a lista de armadilhas de sintaxe que quebram o render. Carregue antes de escrever ou alterar qualquer bloco ```mermaid, em desenhos, specs ou discoveries.
+---
+
+# Diagramas Mermaid
+
+Esta skill é sobre **o desenho**, não sobre o arquivo que o contém. O formato do arquivo de um
+desenho (frontmatter, tipos, `meta.json`) está em `drawing-writing`.
+
+## O renderer que vai desenhar isto
+
+A Specs Platform renderiza com **Mermaid 11.17**, `theme: 'dark'`, layout **dagre** (o padrão),
+fonte Inter, e estas `themeVariables`:
+
+| variável | valor |
+|---|---|
+| `background` | `#1f1f1f` |
+| `primaryColor` | `#986dff` (roxo do accent) |
+| `primaryTextColor` | `#f9fafb` |
+| `primaryBorderColor` | `#2a2a2a` |
+| `lineColor` | `#6b7280` |
+| `secondaryColor` | `#151515` |
+| `tertiaryColor` | `#111111` |
+
+Consequências práticas, todas verificadas neste repositório:
+
+- **Fundo é escuro.** Toda cor que você escolher precisa contrastar com `#1f1f1f`. Preencher com
+  `#fff` ou usar texto `#000` sem `fill` explícito produz um bloco ilegível.
+- **`layout: elk` NÃO está disponível.** O pacote `@mermaid-js/layout-elk` não está instalado; um
+  bloco que pede elk falha no render e a página mostra "Erro no diagrama Mermaid". Use dagre —
+  ou seja, não declare `layout` nenhum.
+- **`securityLevel` é o padrão (`strict`).** `<br/>` funciona em rótulos; HTML arbitrário, não.
+  Não conte com `click`/callbacks.
+- Todo bloco ```mermaid vira um card com **zoom e pan em tela cheia**. Um diagrama que não cabe na
+  largura da página não é um problema fatal — mas ainda é um diagrama ruim se só se lê no zoom.
+
+## Escolha do tipo de diagrama
+
+Escolha pelo **tipo de pergunta**, não pelo que é mais bonito:
+
+| A pergunta é... | Use |
+|---|---|
+| Que peças existem e quem fala com quem? | `flowchart` com `subgraph` por camada |
+| Em que ordem as coisas acontecem, e quem espera por quem? | `sequenceDiagram` |
+| Em que estados uma entidade pode estar e o que a move? | `stateDiagram-v2` |
+| Como os dados se relacionam? | `erDiagram` (tabelas) ou `classDiagram` (objetos) |
+| Onde estão as fronteiras de sistema/infra? | `flowchart` com subgraphs nomeados pela fronteira |
+
+`flowchart` resolve a grande maioria. Prefira-o a `architecture-beta`, `C4Context`, `journey`,
+`mindmap` e afins: são mais frágeis, menos familiares e rendem pior no tema escuro. Só use um
+deles quando o `flowchart` genuinamente não expressa a ideia — e diga na legenda por quê.
+
+## Layout: como não produzir um diagrama largo demais
+
+- **`flowchart TB` no topo, `direction LR` dentro de cada `subgraph`.** Faixas horizontais
+  empilhadas rendem um diagrama equilibrado; `LR` puro no topo produz diagramas larguíssimos que
+  só se leem com scroll horizontal.
+- **Nunca ligue uma aresta a um `subgraph` inteiro.** Ligue sempre a um nó específico: uma aresta
+  apontando para o subgraph faz o Mermaid **ignorar o `direction` interno dele** — é a causa nº 1
+  de "por que meu diagrama ficou torto".
+- **Máximo ~15 nós por diagrama.** Passou disso, o problema não é o diagrama: é o recorte. Quebre
+  em dois blocos ```mermaid — um panorâmico e um de detalhe — em vez de espremer tudo.
+- Agrupe por **camada, fronteira ou etapa** — o que fizer o leitor achar a peça que procura.
+- Prefira poucos tipos de seta. `-->` para o caminho normal, `-.->` para o assíncrono/eventual,
+  `==>` para o caminho crítico. Três significados já é bastante; documente-os na legenda.
+
+## Cor: a paleta do tema escuro
+
+Use `classDef` — nunca `style` inline nó a nó, que é impossível de manter. Duas paletas,
+dependendo do que o desenho está dizendo.
+
+**Desenho de mudança** (o que esta task/feature vai mexer) — mesma paleta das specs:
+
+```
+  classDef changed fill:#3b2f00,stroke:#eab308,color:#fde68a
+  classDef added fill:#052e1a,stroke:#22c55e,color:#bbf7d0
+  classDef removed fill:#3b0d0d,stroke:#ef4444,color:#fecaca
+  classDef untouched fill:#151515,stroke:#2a2a2a,color:#9ca3af
+```
+
+Legenda: `> 🟡 alterado · 🟢 adicionado · 🔴 removido · ⚪ inalterado (contexto)`
+
+**Desenho de arquitetura** (como o sistema é, sem noção de mudança):
+
+```
+  classDef service fill:#241a3d,stroke:#986dff,color:#e9d5ff
+  classDef store fill:#0b2a3d,stroke:#38bdf8,color:#bae6fd
+  classDef queue fill:#3b2f00,stroke:#eab308,color:#fde68a
+  classDef external fill:#151515,stroke:#4b5563,color:#9ca3af
+  classDef actor fill:#052e1a,stroke:#22c55e,color:#bbf7d0
+```
+
+Legenda: `> 🟣 serviço · 🔵 armazenamento · 🟡 fila/tópico · 🟢 ator · ⚪ externo`
+
+Regras que valem para as duas:
+
+- **A cor precisa significar uma coisa só** — natureza da mudança **ou** natureza do componente,
+  nunca as duas no mesmo desenho.
+- **Toda paleta usada vira legenda.** Diagrama colorido sem legenda é decoração.
+- Aplique com `:::classe` no nó (`SQS[notification-q]:::queue`) ou com `class A,B,C queue` no fim.
+  Escolha um dos dois estilos e mantenha no arquivo inteiro.
+
+### Onde a legenda mora
+
+Depende de onde o diagrama está:
+
+- **Em `.specs/drawings/`** — a página renderiza **só o diagrama**, então a legenda tem de estar
+  **dentro dele**, como um nó solto sem arestas:
+
+  ```
+    leg[[legenda: roxo servico · amarelo fila/topico · verde ator · cinza externo<br/>pontilhado = redrive automatico, nao uma chamada]]:::legend
+    classDef legend fill:#111111,stroke:#2a2a2a,color:#9ca3af
+  ```
+
+  Sem aresta ligando o nó de legenda a nada — o dagre o encosta num canto livre, que é onde ele
+  deve ficar. Evite acentos e `·` colados em pontuação problemática dentro do rótulo.
+
+- **Em specs e discoveries** — o markdown em volta é renderizado, então a legenda é uma linha de
+  citação logo abaixo do bloco:
+  `> 🟡 alterado · 🟢 adicionado · 🔴 removido · ⚪ inalterado (contexto)`
+
+## Rótulos
+
+- **Um nó por recurso real** — fila, tabela, use case, endpoint, serviço, job. Nada de "o backend"
+  ou "a camada de dados": se não dá para apontar no repositório, o nó não ajuda ninguém.
+- Nomeie pelo **nome real do recurso** (`notification-q`, `ProcessEventService`,
+  `dev.samir.notification.adapter.out.dynamodb`), não por uma paráfrase.
+- **Sem aspas duplas dentro do rótulo.** Quando precisar de caractere problemático (`(`, `)`, `:`,
+  `,`, `#`), envolva o rótulo inteiro em aspas duplas: `A["POST /v1/notifications (async)"]`.
+  Para uma aspa literal, use a entidade `#quot;`.
+- **`<br/>` para quebrar linha**, nunca `\n`.
+- Duas linhas por rótulo é o teto. A terceira linha vira texto abaixo do diagrama.
+- IDs de nó em `camelCase` ou `kebab-case` curtos e estáveis (`snsTopic`, `notif-q`). Evite `end`
+  como id — é palavra reservada e quebra o parser.
+
+## Antes de gravar: a checklist que evita o card vermelho
+
+1. Todo `subgraph` tem `end`.
+2. Nenhuma aresta aponta para um `subgraph` (só para nós).
+3. Todo `classDef` declarado é usado, e todo `:::classe` referencia um `classDef` existente.
+4. Nenhum rótulo tem aspas duplas soltas nem `\n`.
+5. Não há `layout:` no frontmatter do diagrama.
+6. Contagem de nós ≤ 15.
+7. A legenda existe — nó `:::legend` dentro do diagrama num desenho, linha de citação abaixo do
+   bloco numa spec ou discovery.
+
+Se puder, valide de fato antes de entregar:
+
+```bash
+npx -y @mermaid-js/mermaid-cli -i <arquivo>.md -o /tmp/check.svg
+```
+
+Se o mmdc não estiver disponível, diga que a validação foi só a checklist — não afirme que
+renderizou.
+
+## Exemplo completo (arquivo de `.specs/drawings/`)
+
+````markdown
+---
+title: "Fan-out do SNS domain-events"
+type: architecture
+date: 2026-09-01
+---
+
+```mermaid
+flowchart TB
+  subgraph pub[Publicacao]
+    direction LR
+    prod[Publisher do evento]:::actor --> topic[SNS domain-events]:::queue
+  end
+
+  subgraph fanout[Fan-out]
+    direction LR
+    topic -->|filter policy<br/>PAYMENT_APPROVED, ORDER_CREATED| nq[SQS notification-q]:::queue
+    topic -->|sem filtro<br/>recebe tudo| aq[SQS audit-q]:::queue
+    nq -.->|maxReceiveCount estourado| dlq[SQS notification-dlq]:::queue
+  end
+
+  subgraph cons[Consumo]
+    direction LR
+    nq --> svc[notification-service]:::service
+    aq --> aud[consumidor de auditoria<br/>ainda nao implementado]:::external
+    dlq --> ops[inspecao manual<br/>via awslocal]:::external
+  end
+
+  leg[[legenda: roxo servico · amarelo fila/topico · verde ator · cinza externo<br/>pontilhado = redrive automatico do SQS, nao uma chamada do servico]]:::legend
+
+  classDef service fill:#241a3d,stroke:#986dff,color:#e9d5ff
+  classDef queue fill:#3b2f00,stroke:#eab308,color:#fde68a
+  classDef external fill:#151515,stroke:#4b5563,color:#9ca3af
+  classDef actor fill:#052e1a,stroke:#22c55e,color:#bbf7d0
+  classDef legend fill:#111111,stroke:#2a2a2a,color:#9ca3af
+```
+````
+
+Repare no que **não** está no arquivo: nenhum parágrafo, nenhuma seção, nenhum título no corpo.
+Todo o significado está nos rótulos dos nós e das arestas.

package/assets/template/.agents/skills/prototype-check/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: prototype-check
+description: Como consultar o protótipo do projeto antes de escrever ou implementar qualquer entregável visual — primeiro identificando a ferramenta (Claude Design ou Pencil) pelo bloco `prototype` do `.specs/config.json`, e só então aplicando o fluxo daquela ferramenta (abrir o canvas e ler as notas no Claude Design; Pencil MCP, node IDs e breakpoints no Pencil). Carregue em qualquer task que crie ou altere tela, componente visual ou fluxo de UI.
+---
+
+# Consulta ao protótipo
+
+A consulta é **bloqueante**: sem protótipo conferido, não se escreve critério de aceite visual nem
+se implementa tela. Mas o *como* muda conforme a ferramenta — então a primeira coisa a fazer nunca
+é abrir o protótipo, e sim **descobrir qual ferramenta o projeto usa**.
+
+## Passo 1 — Identificar a ferramenta (sempre primeiro)
+
+Leia o bloco `prototype` do `.specs/config.json`:
+
+```json
+{
+  "prototype": {
+    "tool": "claude-design",
+    "title": "Finance — redesign",
+    "url": "https://claude.ai/code/artifact/<id>",
+    "designDir": "design/finance-redesign",
+    "artboards": ["Desktop", "Mobile", "Loading"]
+  }
+}
+```
+
+- `tool: "claude-design"` → canvas do Claude Design, endereçado por `url`.
+- `tool: "pencil"` → arquivo `.pen` local, endereçado por `file` (e opcionalmente `nodeIds`).
+- Bloco ausente ou `null` → **o projeto não tem protótipo**: siga sem fase visual e diga isso no
+  relatório. Não invente um.
+
+O `meta.json` da feature pode declarar o seu próprio bloco `prototype`, e ele **substitui** o do
+projeto por completo — uma feature pode estar em outra ferramenta que o resto do repositório.
+Cheque o `meta.json` da feature antes de assumir o default.
+
+Sem bloco algum e com suspeita de que existe protótipo, confirme por heurística **e depois peça ao
+usuário para declarar**: `.pen` versionado ⇒ Pencil; `design/**/README.md` com link
+`claude.ai/code/artifact` ⇒ Claude Design.
+
+## Passo 2A — Claude Design
+
+O canvas é a fonte da verdade; ele **não vive no repositório** e não há MCP para lê-lo.
+
+1. Abra a `url` (ou peça ao usuário que abra e descreva/exporte o artboard em questão). Na Specs
+   Platform, o painel **Protótipo** da task já traz o botão que abre o canvas.
+2. Leia `<designDir>/README.md` — é onde ficam registradas as decisões de design, os artboards, os
+   estados de erro/vazio e o mapa de componentes. É a parte versionada do protótipo, e a única
+   consultável offline.
+3. Confira, para a tela da task: estrutura e hierarquia; estados (loading, erro, vazio); os
+   breakpoints que o protótipo cobre; e quais componentes do design system entram.
+4. **Não há node ID no Claude Design.** Referencie os artboards pelo nome ("Finance · Mobile"),
+   nunca por id inventado.
+5. Alterações no protótipo se pedem pelo slash command `/design` do Claude Code — é o mesmo caminho
+   do botão "Pedir alteração" da Specs Platform. Nunca edite o canvas por outro meio.
+6. A Specs Platform embute o protótipo a partir de um **snapshot local** (`prototype.snapshot`,
+   default `<designDir>/canvas.html`) — o canvas publicado recusa iframe cross-origin. Depois de
+   alterar o design, regrave esse arquivo: leia o canvas com a tool `Artifact` (`action: "read"`) e
+   grave o HTML devolvido no caminho do snapshot. É o que o botão **Sincronizar** faz.
+
+Divergência entre o README e o canvas: o **canvas ganha**, e o README deve ser atualizado na mesma
+task.
+
+## Passo 2B — Pencil
+
+O `.pen` é **encriptado**: nunca use `Read`/`Grep` nele. Só as tools do Pencil MCP.
+
+As tools `pencil` normalmente **não estão disponíveis dentro de subagentes de execução** — delegue
+a consulta a um sub-agente que as tenha, ou faça-a na sessão principal antes de delegar.
+
+1. Confirme a conexão e o arquivo aberto (estado do editor).
+2. **Obtenha os node IDs** dos nós relevantes: se o `meta.json`/`config.json` declarar `nodeIds`,
+   parta deles; senão, localize os nós por busca semântica pelo nome da tela/componente e confirme
+   com o usuário quais são os alvos antes de seguir.
+3. Para cada nó alvo, extraia: estrutura e hierarquia, tokens (cores, espaçamentos, tipografia),
+   estados e os **3 breakpoints** (desktop, tablet, mobile).
+4. Registre os node IDs consultados no relatório — é o que torna a consulta auditável.
+5. Alterações se pedem pelo mesmo MCP, devolvendo o antes/depois de cada nó afetado.
+
+## Regras comuns
+
+- **Nada de tokens fixos na spec** (hex, px, pesos): eles mudam no protótipo e a doc passa a
+  mentir. Descreva estrutura e intenção; quem implementa extrai os valores no momento da
+  implementação.
+- Tela que deveria existir e não está no protótipo: **pare e informe o usuário**. Não desenhe por
+  conta própria.
+- No relatório da task, inclua uma seção **Validação contra o protótipo** com a ferramenta usada, o
+  que foi conferido (✅/❌) e — no Pencil — os node IDs.
+- Ferramenta indisponível, sem resposta ou falhando após 2–3 tentativas: **pare e informe**, não
+  siga por aproximação.

package/assets/template/.agents/skills/refinement/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: refinement
+description: Transforma uma descrição livre em task ou feature documentada em `.specs/specs/` — contextualiza com as features existentes, valida contra o código real, fecha os requisitos sem deixar ambiguidade em silêncio e entrega uma spec pronta para o feature-runner executar. Carregue ao refinar, detalhar, especificar, quebrar ou planejar uma atividade do projeto.
+---
+
+# refinement
+
+Transforma uma descrição vaga em documentação **acionável, detalhada e alinhada com o estado real
+do projeto** — pronta para o `feature-runner` executar.
+
+Equivalências de tools Claude Code ↔ Cursor: `.agents/RUNTIME.md`.
+
+## Princípios invioláveis
+
+1. **Nunca altere código de produção.** Seu output é documentação em `.specs/specs/`. Leia o código
+   à vontade; não o modifique.
+2. **Sempre valide contra o estado real.** `Glob`, `Grep` e `Read` antes de referenciar qualquer
+   rota, componente, tipo ou tabela em critério de aceite. Siga a cadeia de verificação de
+   conhecimento da skill `requirements-closure` (código → docs → context7 → web → declarar
+   incerteza). **Nunca fabrique** API, campo ou comportamento — requisito inventado vira teste que
+   passa provando a coisa errada.
+3. **Sempre pergunte** diante de ambiguidade real de escopo, prioridade ou encaixe:
+   `AskUserQuestion` / `AskQuestion` com 2–4 opções concretas, recomendando uma quando tiver
+   opinião informada ("(Recomendado)").
+4. **Respeite as convenções** de `CLAUDE.md` (raiz), `.specs/specs/CLAUDE.md` e dos `CLAUDE.md` das
+   apps. Nunca invente formato novo.
+5. **Opere com paths absolutos** e **responda em português brasileiro**.
+6. **Não commite nem crie branches.**
+7. **Não altere o `status` de uma task** — isso é do `feature-runner`.
+
+## Skills por camada
+
+`spec-writing` (contrato do arquivo) e `requirements-closure` (como o critério é escrito e quando
+está fechado) são **obrigatórias** — carregue as duas antes de redigir qualquer critério. As demais,
+conforme o que a task toca:
+
+| Carregue | Quando |
+|---|---|
+| `test-strategy` | a task produz código testável — define `**Tipo:**` e `**Gate:**` do bloco de Testes. Quase sempre |
+| `input-security` | a task recebe input do usuário (formulário, body, query/path param, cookie, header, upload, webhook) (opcional — só se o projeto adotar essa skill) |
+| `ui-standards` | a task cria ou altera tela/componente (opcional — só se o projeto adotar essa skill) |
+| `prototype-check` | a task tem entregável visual — define como identificar a ferramenta e consultar o protótipo |
+
+Não carregue o que não vai usar.
+
+## Fluxo
+
+**0. Protótipo (quando o usuário fornecer node IDs).** Consulta ao protótipo é **bloqueante**, antes
+de ler código. Carregue `prototype-check` e siga o fluxo de delegação de lá. Conexão falhou ou os
+nós não retornaram ⇒ **PARE e informe o usuário**.
+
+**1. Entender a atividade.** Fixe **o quê** (funcionalidade, melhoria, correção), **por quê**
+(problema que resolve) e **onde** (frontend, backend, ambos, infra, docs). Descrição vaga do tipo
+"melhorar a performance" ⇒ `AskUserQuestion` para delimitar parte do sistema, comportamento atual
+vs. esperado e restrições.
+
+**2. Mapear o terreno.** → [mapear-terreno.md](references/mapear-terreno.md)
+
+**3. Decidir a estrutura.** → [estrutura.md](references/estrutura.md)
+
+**4. Fechar os requisitos.** → skill `requirements-closure`: o sweep das 9 dimensões implícitas
+(cada uma vira requisito **ou** `N/A porque <motivo>` — nunca em branco), a redação em EARS, os IDs
+de requisito e o portão de fechamento. **Esta fase não é opcional em task média ou grande.** O que
+não foi resolvido com o usuário vira linha na tabela de premissas, nunca sumiço silencioso.
+
+**5. Redigir.** Use `.specs/specs/_templates/` como ponto de partida, adaptando ao escopo real (não
+copie seção que não se aplica). Siga `spec-writing` para estrutura, diagrama, blocos `<details>` e
+frontmatter. Depois de escrever, atualize o `meta.json` correspondente — e o `overview.md` da
+feature quando a task nova mudar o desenho macro.
+
+**6. Validar.** → [validar-renderizacao.md](references/validar-renderizacao.md)
+
+**7. Reportar.** → formato abaixo.
+
+Leia cada referência **por completo** no momento em que a fase começa.
+
+## Regras que valem sempre ao redigir
+
+- Task com input do usuário **tem** bloco de segurança. Sem input, o relatório declara
+  "Segurança de inputs: N/A — a task não processa inputs externos".
+- Task de frontend **tem** blocos de responsividade, estados de UI e acessibilidade/animações.
+- Decisão que depende de versão de lib (ver a stack no `project.md`): consulte a doc atual via
+  sub-agente com MCP `context7` antes de fixar o critério, e registre a referência no relatório.
+- **Nada de token visual fixo** (hex, px, pesos) — eles vivem no protótipo, não na spec.
+- Decisão que vira restrição de projeto (outra feature precisaria saber dela) ⇒ proponha ao usuário
+  uma entrada `AD-NNN` em `.specs/STATE.md`. Decisão feature-local fica no arquivo da task.
+
+## Relatório
+
+```markdown
+## Refinamento concluído
+
+**Tipo:** <Nova task em feature existente | Nova feature | Refinamento de task existente>
+**Feature:** <título> (`.specs/specs/<slug>/`)
+**Task(s) criada(s)/refinada(s):**
+- `feat-<slug>-<task>.md` — <descrição curta>
+
+### Resumo do escopo
+- <bullet>
+
+### Sweep das dimensões implícitas
+- <dimensão> → <requisito criado | N/A porque ...>
+
+### Premissas registradas
+- <premissa> — default: <o que vamos fazer> — <racional>
+
+### Arquivos criados/modificados
+- <path> (criado/editado)
+
+### Dependências identificadas
+- <task X> (status) — <relação>
+
+### Decisões tomadas
+- <decisão e motivo, ou "nenhuma — tudo estava claro">
+
+### Validação
+- `node .agents/scripts/validate-spec.mjs <path>` — <0 erros / o que foi corrigido>
+- Renderização conferida em `/features/<slug>/<task>` — <ok / o que falhou>
+
+### Pontos que merecem atenção
+- <risco, ambiguidade remanescente ou sugestão de split>
+
+### Próximos passos
+- Para **executar**: `executar feat-<slug>-<task>`
+- Para **ajustar**: "Ajustar: <o que mudar>"
+```
+
+**Entrada "Ajustar: ..."** ⇒ releia o arquivo com `Read` antes de editar, aplique **apenas** o
+solicitado (não expanda escopo) e volte ao relatório atualizado.
+
+## Notas
+
+- Chame tools em paralelo quando forem independentes (leituras, greps).
+- Seja específico: o `feature-runner` usa seus critérios como spec de implementação.
+- Gap descoberto no projeto (tipo compartilhado que falta, endpoint que deveria existir) vira
+  **ponto de atenção** no relatório — não expanda o escopo por conta própria.

package/assets/template/.agents/skills/refinement/references/estrutura.md

@@ -0,0 +1,27 @@
+# Decidir a estrutura
+
+| Caso | Quando | O que produzir |
+|---|---|---|
+| **A** — nova task em feature existente | a atividade cabe numa feature já documentada | novo `feat-<slug>-<nome>.md` + entrada em `pages` do `meta.json` da feature |
+| **B** — feature nova | a atividade não pertence a nenhuma feature existente | pasta + `meta.json` + `overview.md` + tasks + slug no `.specs/specs/meta.json` raiz |
+| **C** — refinar task existente | já existe task cobrindo isso, mas rasa ou desatualizada | enriquecer o arquivo atual |
+
+Dúvida entre A e B ⇒ `AskUserQuestion` com prós e contras.
+
+## Heurísticas de quebra em tasks
+
+A fonte de verdade é a skill **`spec-writing`**, seção "Heurísticas de quebra em tasks" — quando
+quebrar, quando não quebrar e como ordenar o array `pages`. Carregue-a antes de decidir o recorte;
+não duplique a regra aqui.
+
+O usuário prefere **tasks quebradas por seção**, para ter controle sobre cada entrega. Na dúvida
+entre uma task grande e duas menores coesas, proponha as duas e deixe a escolha com ele.
+
+## Antes de escrever: a atividade merece spec?
+
+Se a atividade é pequena e coesa (≤3 arquivos, uma camada, nenhum contrato novo), documentar custa
+mais do que fazer. Diga isso ao usuário e ofereça o caminho do `refinement-runner` — refinar e
+executar direto, sem produzir documento. A decisão é dele.
+
+O inverso também vale: atividade que se quebraria em três ou mais tasks independentes **precisa** de
+spec, mesmo que tenha chegado como "faz rapidinho".

package/assets/template/.agents/skills/refinement/references/mapear-terreno.md

@@ -0,0 +1,46 @@
+# Mapear o terreno
+
+Em paralelo, antes de decidir qualquer coisa:
+
+- **`Glob` em `.specs/specs/*/meta.json`**, lidos todos — mapa completo de features e tasks. Para
+  as features relevantes, leia o `overview.md` e o frontmatter de cada task (inclusive `status`).
+- **`CLAUDE.md`** da raiz, `.specs/specs/CLAUDE.md` e o `CLAUDE.md` da app afetada.
+- **`.specs/STATE.md`, seção `## Decisions`** — leitura **obrigatória** antes de qualquer decisão
+  arquitetural. Detalhes abaixo.
+- **Código relacionado** via `Grep`/`Glob`: endpoints existentes, componentes, schema do banco,
+  tipos e utilitários compartilhados (ver a estrutura de pacotes no `project.md`).
+- **Dependências cruzadas:** o que é pré-requisito desta atividade e o que dependerá dela.
+- **Discoveries** em `.specs/discoveries/` que toquem o assunto — referencie em vez de duplicar.
+
+Escopo amplo demais para `Glob`/`Grep`: no máximo **1** chamada `Agent` com
+`subagent_type: Explore`, com foco específico.
+
+## Decisões ativas de projeto
+
+Toda entrada `AD-NNN` de `.specs/STATE.md` com `Status: active` é uma **restrição** que esta task
+precisa respeitar. Se uma decisão de feature anterior conflita com o que é melhor aqui, você tem
+duas saídas — ambas exigem escolha explícita:
+
+1. **Conformar** — desenhe dentro da restrição ativa.
+2. **Superar** — pergunte ao usuário e, aprovado, acrescente um `AD-NNN` novo em `.specs/STATE.md`
+   que substitui o antigo (marcando o antigo como `superseded by AD-NNN`) e documente o motivo. A
+   decisão nova passa a ser o padrão do projeto.
+
+**Ignorar uma decisão ativa em silêncio não é opção** — cria inconsistência invisível entre
+features, que só aparece meses depois.
+
+Quando a decisão merecer documento longo (comparação de alternativas, benchmark, plano de adoção),
+a discovery tipo `adr`/`rfc` é o documento e a entrada `AD-NNN` é o índice que aponta para ela.
+
+## Sinalizar riscos encontrados no caminho
+
+Enquanto lê o código, anote o que encontrar de problemático **nas áreas que esta task toca**:
+
+- código frágil — acoplamento forte, função gigante, estado implícito;
+- dívida técnica — gambiarra, workaround, API deprecada;
+- risco de segurança — input não validado, brecha de auth, segredo exposto;
+- gargalo — N+1, loop sem limite, índice faltando;
+- lacuna de teste — caminho não testado do qual esta task depende.
+
+Cada achado vai para **Pontos que merecem atenção** no relatório, com `file:line` e o que você
+sugere fazer. Não conserte nada: você não altera código de produção.

package/assets/template/.agents/skills/refinement/references/validar-renderizacao.md

@@ -0,0 +1,29 @@
+# Validar
+
+Duas checagens. Nenhuma é opcional — erro de frontmatter, slug inconsistente ou typo no `meta.json`
+quebra a página na Specs Platform.
+
+## 1. Validação determinística
+
+```bash
+node .agents/scripts/validate-spec.mjs .specs/specs/<slug>/feat-<slug>-<task>.md
+```
+
+Checa por código o que a skill `spec-writing` exige de memória: frontmatter e `status` válido,
+ordem das seções, ausência de H1 no corpo, `**Depende de:**`, `### Fora de escopo`, os quatro
+`classDef` do Mermaid, linha em branco nos `<details>`, heading proibido dentro de `<details>`,
+critério fora de EARS, ID de requisito malformado, premissa com célula vazia, e presença do arquivo
+em `pages` do `meta.json`.
+
+**Saída ≠ 0 ⇒ corrija antes de apresentar.** Rode no arquivo que você tocou; `--all` existe para
+inventário e hoje acusa as specs no formato antigo, que não são escopo do seu refinamento.
+
+## 2. Renderização
+
+1. `curl -sf http://localhost:4321/health` (UI e API na mesma porta). Não respondeu? rode
+   `specs status`; se não estiver no ar, peça ao usuário para rodar `specs start` na raiz.
+2. Abra as páginas criadas/editadas (`/features/<slug>` e `/features/<slug>/feat-<slug>-<task>`) —
+   via sub-agente com a ferramenta de E2E, ou pelos endpoints `/api/tree` e `/api/content`.
+3. Confirme: sem erro de console, título e seções renderizando, diagrama Mermaid sem erro, blocos
+   expansíveis abrindo, sidebar na ordem certa.
+4. Falhou algo? consulte a seção **Troubleshooting** de `SPECS.md` antes de mexer na configuração.