@mir-code/specs-platform 1.0.1

package/assets/template/.agents/skills/drawing-writing/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: drawing-writing
+description: Como escrever e manter os desenhos de `.specs/drawings/` — os cinco tipos (architecture, flow, sequence, data, state), o frontmatter, a regra de "só o diagrama, sem prosa", e a atualização do `meta.json`. Carregue ao criar ou alterar qualquer arquivo em `.specs/drawings/`.
+---
+
+# Escrita de desenhos
+
+Desenhos são a memória visual do projeto: arquitetura, fluxos, sequências, modelo de dados,
+máquinas de estado. Moram em `.specs/drawings/<slug>.md`, **sem subpastas**.
+
+A página de um desenho na Specs Platform **é o diagrama**: o canvas ocupa a tela inteira, com
+arrasto e zoom, sem índice e sem corpo de markdown. Nada que você escrever fora do bloco
+```mermaid aparece para o leitor — só no editor.
+
+A sintaxe Mermaid — escolha do tipo de diagrama, layout, paleta, `classDef`, armadilhas de render
+— está na skill `mermaid-diagramming`. Carregue as duas.
+
+Um desenho **não altera código de produção**. O output é um `.md` + a entrada no `meta.json`.
+
+## A regra que manda em tudo: só o diagrama
+
+O arquivo é **frontmatter + um bloco ```mermaid**. Mais nada.
+
+- **Sem `## Visão geral`, sem `## Notas`, sem `## Fontes`, sem parágrafo de introdução.** A página
+  não renderiza nada disso.
+- **Sem `# Título`** — o título vem do frontmatter e aparece na topbar.
+- **A legenda vai dentro do diagrama**, como um nó (veja `mermaid-diagramming`). Uma linha de
+  citação abaixo do bloco não seria exibida.
+- **Tudo que você precisaria explicar em prosa vira rótulo.** Se o desenho só faz sentido com um
+  parágrafo ao lado, o problema é o desenho: nomeie melhor os nós, rotule as arestas, corte o que
+  não pertence ao recorte.
+- Contexto, trade-offs e "por quês" que não cabem num rótulo **não pertencem a um desenho** —
+  pertencem a uma discovery (`.specs/discoveries/`) ou à spec da task. Linke o desenho de lá.
+
+Mais de um bloco ```mermaid no mesmo arquivo é permitido, e a página mostra uma faixa de abas —
+use só quando forem **zooms diferentes da mesma pergunta** (panorama + detalhe). Perguntas
+diferentes viram desenhos diferentes.
+
+## Os cinco tipos
+
+O `type` do frontmatter é a **pergunta que o desenho responde**, não o tipo de diagrama Mermaid
+(um `architecture` costuma ser um `flowchart`).
+
+| Tipo | Responde | Diagrama típico |
+|---|---|---|
+| `architecture` | Que peças existem e como se conectam? | `flowchart` com subgraphs |
+| `flow` | Que caminho um pedido/dado percorre, com que desvios? | `flowchart` com decisões |
+| `sequence` | Em que ordem, e quem espera por quem? | `sequenceDiagram` |
+| `data` | Como os dados se relacionam? | `erDiagram` / `classDiagram` |
+| `state` | Em que estados uma entidade vive e o que a move? | `stateDiagram-v2` |
+
+Se o usuário não indicar o tipo, infira do pedido. Só pergunte quando genuinamente ambíguo.
+**Não invente tipos novos** — a UI só conhece esses cinco e cai em `architecture` no resto.
+
+## Nome do arquivo
+
+`kebab-case`, começando com letra minúscula, descrevendo o **assunto**, não o formato:
+`fan-out-sns-sqs`, `ciclo-vida-notificacao`, `retry-e-dlq`, `modelo-notifications`.
+
+Não prefixe com o tipo (`arch-`, `seq-`): o badge da sidebar já mostra isso.
+
+Se o slug já existir, **pergunte** se é para sobrescrever ou criar com sufixo.
+
+## O arquivo, inteiro
+
+````markdown
+---
+title: "Fan-out do SNS domain-events"
+type: architecture
+date: 2026-09-01
+---
+
+```mermaid
+flowchart TB
+  ...
+```
+````
+
+`date` é a data de criação, ISO, sem hora. Não a atualize a cada edição — ela diz quando o desenho
+nasceu, e a sidebar a usa como referência de idade.
+
+## `meta.json`
+
+Depois de gravar o arquivo:
+
+1. Leia `.specs/drawings/meta.json`; se não existir, crie com
+   `{ "title": "Desenhos", "pages": [] }`.
+2. Acrescente o slug (sem `.md`) ao fim de `pages` — **sem duplicar** se já estiver lá.
+
+A ordem de `pages` é a ordem da sidebar, e o usuário pode reordenar arrastando. Ao acrescentar um
+desenho novo, sempre no fim: reordenar é decisão dele.
+
+## Alterando um desenho existente
+
+1. Leia o arquivo inteiro antes de mexer.
+2. Preserve o que não foi pedido — título, tipo, `date`, os `classDef`, os outros diagramas.
+3. Se a mudança acrescenta uma cor ou um tipo de seta, **atualize o nó de legenda** junto.
+4. Se a mudança troca o `type`, o slug provavelmente também deveria mudar — pergunte.
+5. Se o pedido é "explica isso aqui", não acrescente prosa ao arquivo: melhore os rótulos, ou
+   proponha uma discovery.

package/assets/template/.agents/skills/execution-protocol/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: execution-protocol
+description: Protocolo de execução comum aos agentes que escrevem código — princípios invioláveis (nada de commit sem aprovação, nada de ação destrutiva, escopo fechado), blast radius, verificação do repositório antes de começar, o ciclo halt → ajustar → complete e o formato do relatório de code review. Carregue no início de qualquer execução que produza código.
+---
+
+# Protocolo de execução
+
+Vale para `feature-runner` e `refinement-runner`. Eles diferem no que leem antes de implementar;
+daqui para frente, o comportamento é o mesmo.
+
+## Princípios invioláveis
+
+1. **Nunca commite, dê push ou merge sem aprovação explícita no chat.** A execução padrão termina
+   **antes** do commit, com o relatório de halt.
+2. **Nunca use ação destrutiva como atalho.** Proibidos: `git reset --hard`, `push --force`,
+   `--no-verify`, `--amend`, `git add -A`, `git add .`, `git clean -f`, `git checkout .`,
+   `git stash` como forma de "guardar" trabalho. Deu errado? investigue a causa e reporte.
+3. **Blast radius.** Aprovação de spec ou de escopo autoriza **implementação local** e nada mais.
+   O commit e o push só acontecem após um **"Complete"** explícito, e ele é pedido uma vez só, no
+   fim de tudo — "Prosseguir" entre tasks **não** autoriza git. Não autoriza force-push, deploy, migration
+   em produção, alteração de infra externa nem nada visível fora do repositório — cada uma dessas
+   exige go-ahead explícito **para aquela ação**, mesmo com a execução já aprovada.
+4. **Não expanda escopo.** Apareceu algo fora do que foi fechado? vira **ponto de atenção** no
+   relatório, não código. A heurística: *"isso está na definição da minha task?"* Se não, não toque.
+5. **Nunca invente convenção, ferramenta ou biblioteca nova** sem aprovação. Use o que o monorepo
+   já tem.
+6. **Respeite as restrições de leitura** dos arquivos de design: o `project.md` indica quais são
+   encriptados e só podem ser lidos pela tool do MCP, nunca por `Read`/`Grep`.
+7. **Nunca crie arquivo `.md` novo** a menos que a atividade peça documentação.
+8. **Pergunte diante de ambiguidade real** de escopo, design, contrato de API ou biblioteca —
+   pergunta estruturada (`AskUserQuestion` / `AskQuestion`) com 2–4 opções concretas. Nunca
+   pergunte "posso prosseguir?"; prossiga quando o caminho estiver claro.
+9. **Opere com paths absolutos** e **responda em português brasileiro**.
+
+## Verificar o repositório (antes de tocar em código)
+
+1. `git status --porcelain` — working tree sujo ⇒ **pare e pergunte** (pode ser trabalho do usuário).
+2. `git rev-parse --abbrev-ref HEAD` — deve ser `master`; se não for, `git checkout master`.
+3. `git pull --ff-only origin master`.
+4. Falhou (não fast-forward, conflito, sem rede) ⇒ **pare e reporte**. Nunca recupere com ação
+   destrutiva.
+
+Todo o trabalho é feito direto na `master`. Não crie branches.
+
+**Deduza o tipo do commit já aqui:** `feat` (mais comum), `fix`, `refactor`, `chore`, `docs`,
+`test`, `infra`. Ambíguo ⇒ pergunte agora, não no fim.
+
+## Convenções de código
+
+- **Formatação e tipagem** conforme a seção *Convenções de código* de
+  [`.agents/project.md`](../../project.md).
+- **Reusar antes de criar:** utilitários, tipos, componentes, hooks. Procure com `Grep`/`Glob` nos
+  diretórios de reuso que o `project.md` lista, antes de escrever qualquer coisa nova.
+- **Idioma do código e do conteúdo** conforme a seção *Identidade* do `project.md` (arquivo, classe,
+  função, variável, comentário, rota, coluna seguem o idioma do código; texto de usuário final e
+  documentação seguem o idioma do conteúdo).
+- **Comentário só como JSDoc curto** acima de classe/função/interface/tipo exportado. Nada de
+  comentário inline narrando passo a passo, banner de seção, JSDoc em constante ou nota de decisão
+  (isso vive na spec). Ao editar, remova esse tipo de comentário na região tocada. Exceções:
+  `TODO:`/`FIXME:` com contexto real e supressões justificadas.
+- Use as tools dedicadas de leitura/edição (`Read`, `Edit`/`StrReplace`, `Write`, `Glob`, `Grep`).
+  Terminal (`Bash`/`Shell`) só para git, gerenciador de pacotes e checagens — nunca `cat`/`grep`/`sed`.
+
+## Gate por task
+
+Toda task que produz código testável roda o gate do pacote tocado **antes** de ser dada como
+pronta. Os níveis, os comandos reais e a matriz de cobertura estão na skill **`test-strategy`** —
+carregue-a. Em resumo: rode o gate do pacote tocado (comando no `project.md`), saída ≠ 0 é bloqueio, e a contagem
+de testes não pode cair sem justificativa.
+
+## Verificação antes do halt
+
+Entrega com código testável passa pela skill **`verification`** antes do relatório: um sub-agente
+novo re-deriva a cobertura com evidence-or-zero e roda o sensor de discriminação. O bloco que ele
+devolve entra no relatório como seção própria — é o que o code review humano lê no lugar de prosa.
+
+## O ciclo halt → ajustar → complete
+
+**O git roda uma vez só, no Complete final.** Não existe commit automático nem commit
+intermediário — em nenhum modo. Entre tasks de uma feature o usuário diz "Prosseguir", e isso não
+toca no git: a task fecha com `status: completed` e o código no working tree.
+
+As três entradas possíveis:
+
+| Entrada | O que faz |
+|---|---|
+| **"Prosseguir"** | aprova a task atual e avança para a próxima. **Nenhum git.** Só aparece quando ainda há task pendente |
+| **"Ajustar: ..."** | itera na entrega atual e repete o halt, sem commitar |
+| **"Complete"** | **único** ponto em que o git roda: stage, commit e push. Só é oferecido no halt final |
+
+Detalhes nas referências:
+
+- [Relatório de halt](references/relatorio-halt.md) — o formato, os dois tipos de halt
+  (intermediário e final) e o que acrescentar quando a task é visual ou não tem input externo.
+- [Git: stage, commit e push](references/git.md) — o procedimento do Complete e quando ele roda em
+  cada modo.
+
+**Entrada "Ajustar: ..."** ⇒ confirme a branch, aplique **apenas** o solicitado (não expanda
+escopo), e volte ao halt com o relatório atualizado. Se o ajuste trouxer ambiguidade nova,
+**pergunte antes de implementar**.
+
+**"Esquece" / "abortar" / "cancela"** ⇒ pare imediatamente e pergunte se deve reverter o working
+tree. **Não reverta por conta própria.**
+
+## Pausa de sessão
+
+Trabalho interrompido no meio (o usuário encerra, o contexto acaba, aparece bloqueio externo):
+antes de sair, substitua **apenas** a seção `## Handoff` de `.specs/STATE.md` pelo snapshot atual.
+O formato e a regra de escrita section-scoped estão no próprio arquivo. **Não toque na seção
+`## Decisions`** — sobrescrever o arquivo inteiro apaga o log de decisões em silêncio.

package/assets/template/.agents/skills/execution-protocol/references/git.md

@@ -0,0 +1,104 @@
+# Git: stage, commit e push
+
+Entrada: o usuário respondeu **"Complete"**. Só com aprovação explícita. **Nunca antecipe.**
+
+> **O git roda uma vez só, no Complete final.** Não existe commit automático, não existe commit
+> intermediário, não existe commit local "de checkpoint". Em qualquer modo — task avulsa, feature
+> com pausa ou feature sem pausa — nada é commitado enquanto o usuário não disser "Complete" no fim
+> de tudo. Entre tasks o usuário diz **"Prosseguir"**, e isso **não toca no git**.
+
+## Procedimento
+
+1. `git rev-parse --abbrev-ref HEAD` (deve ser `master`) e `git pull --ff-only origin master`.
+   Falhou ⇒ pare e reporte.
+
+2. **Atualize o status da task** no frontmatter: `in-progress` → `completed`.
+   (O `refinement-runner` não tem arquivo de task — pule este passo e o seguinte.)
+
+3. **Registre a execução** no fim do arquivo da task, no formato da skill `spec-writing` (seção
+   `## Execuções`, entrada nova no topo, dentro de um `<details>`). Data via
+   `date '+%d/%m/%Y %H:%M'`; tipo = o `<type>` do commit em maiúsculo. Máximo 8 bullets,
+   específicos ("Criado `.../health-routes.ts` com rota `GET /health`", não "adicionada rota").
+
+4. **Recalcule o status agregado da feature** lendo o frontmatter de todas as tasks de
+   `meta.json.pages`: `completed` se todas; `in-progress` se houver mistura ou alguma em
+   andamento; `pending` se todas pendentes. **Não invente** campo `status` no `meta.json` — o
+   agregado só aparece na mensagem de commit.
+
+5. **Stage por nome explícito** — nunca `git add -A` nem `git add .`:
+
+   ```bash
+   git add -- <arquivo1> <arquivo2> <task.md>
+   ```
+
+   Confira com `git status` que **só** o esperado está staged.
+
+6. **Valide a mensagem antes de commitar:**
+
+   ```bash
+   node .agents/scripts/check-commit.mjs --message "<type>(<feature-slug>): <título da task>"
+   ```
+
+   Saída ≠ 0 ⇒ corrija o formato antes de seguir.
+
+7. **Commit com HEREDOC:**
+
+   ```bash
+   git commit -m "$(cat <<'EOF'
+   <type>(<feature-slug>): <título da task>
+
+   Refs: .specs/specs/<slug>/feat-<slug>-<task>.md
+   Task status: in-progress -> completed
+   Feature status: <pending|in-progress|completed>
+
+   Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
+   EOF
+   )"
+   ```
+
+   Hook de pre-commit falhou ⇒ **corrija e faça um commit novo**. Nunca `--amend` nem
+   `--no-verify`. Unidades lógicas claramente separáveis podem virar commits separados
+   referenciando a mesma task.
+
+8. **Push — condicional ao modo** (ver abaixo). Falhou ⇒ pare e reporte. Nunca `--force`.
+
+9. **Reporte:**
+
+   ```markdown
+   ## Complete
+
+   **Branch:** `master` (commit direto)
+   **Commit(s):** <hash curto> — <título da task>
+   **Push:** origin/master @ <hash curto>
+   **Status final da task:** completed
+   **Status agregado da feature:** <pending|in-progress|completed>
+   ```
+
+## Quando este procedimento roda
+
+| Modo | Entre tasks | Git |
+|---|---|---|
+| **Task avulsa** | — | no Complete, ao fim da task |
+| **Feature com pausa** (padrão) | halt de review a cada task; usuário diz **"Prosseguir"** | **uma vez só**, no Complete depois da última task |
+| **Feature sem pausa** | nenhum halt; avança sozinho | **uma vez só**, no Complete depois da última task |
+
+Nos dois modos de feature, cada task intermediária termina com `status: completed` no frontmatter,
+o registro em Execuções e o código no **working tree** — e nada mais. O commit cobre a feature
+inteira.
+
+> **Por que um commit só.** O revisor avalia a feature de uma vez. Commit intermediário congela
+> decisão que ainda pode mudar no review e obriga commit de correção em cima. E um working tree
+> limpo de commits parciais é trivial de descartar se a feature inteira for rejeitada.
+
+Unidades lógicas claramente separáveis podem virar **commits separados no mesmo Complete** — isso é
+organização do diff final, não checkpoint intermediário.
+
+Vale sempre: **nenhum commit e nenhum push sem "Complete" explícito no chat.**
+
+## Depois do Complete
+
+Reporte e encerre. Não há próxima task a executar: o Complete só acontece quando todas já estão
+`completed` no working tree.
+
+Se por algum motivo restar task `pending` em `pages` (o usuário pediu Complete antes do fim),
+**avise explicitamente** quais ficaram de fora e confirme que é intencional antes de commitar.

package/assets/template/.agents/skills/execution-protocol/references/relatorio-halt.md

@@ -0,0 +1,103 @@
+# Relatório de halt
+
+Você **termina seu turno** aqui. Nada de `git commit`, `push`, `merge` ou `stash`.
+
+O relatório é a pauta do code review — mantenha-o enxuto e específico. Lidere com o que importa,
+sem parágrafo de aquecimento.
+
+## Formato
+
+```markdown
+## Tarefa pronta para code review
+
+**Feature:** <título> (`.specs/specs/<slug>/`)
+**Task:** <título> (`.specs/specs/<slug>/feat-<slug>-<task>.md`)
+**Branch:** `master`
+**Status atualizado:** pending → in-progress (working tree, sem commit)
+
+### Resumo do que foi feito
+- <bullet>
+
+### Arquivos modificados
+- `caminho/arquivo.ts`
+- `.specs/specs/<slug>/feat-<slug>-<task>.md` (status)
+
+### Gate
+- **Comando:** o gate do pacote tocado (ver `project.md`)
+- **Resultado:** <X passou, 0 falhou> · contagem antes <A> → depois <B>
+
+### Verificação independente
+<bloco devolvido pelo Verifier — ver skill `verification`. Sem código testável na entrega,
+escreva: "N/A — a entrega não produz código com teste automatizado.">
+
+### Decisões tomadas durante a execução
+- <decisão e motivo, ou "nenhuma decisão não trivial">
+
+### Pontos para você revisar com atenção
+- <ponto>
+
+### Como revisar
+Abra a task na Specs Platform e clique em **Revisar** (ou vá direto em
+`http://localhost:4321/features/<slug>/<task>/review`): a tela lista os arquivos alterados
+agrupados por natureza, com o diff de cada um e um botão para abrir o arquivo no editor.
+
+### Próximos passos
+<ver "Os dois tipos de halt" abaixo — o bloco muda conforme restem ou não tasks pendentes>
+```
+
+## Os dois tipos de halt
+
+O relatório é o mesmo; o que muda é o bloco final, porque **só o halt final autoriza git**.
+
+**Halt intermediário** — feature com pausa, ainda há task pendente em `pages`:
+
+```markdown
+### Próximos passos
+- **"Prosseguir"** — sigo para a próxima task (`<título da próxima>`). **Nada é commitado**: o
+  código fica no working tree e o git só roda no Complete final.
+- **"Ajustar: <descrição>"** — itero nesta task e repito o halt.
+
+**Progresso da feature:** <N> de <T> tasks concluídas (working tree, sem commit).
+```
+
+**Halt final** — task avulsa, ou última task da feature:
+
+```markdown
+### Próximos passos
+- **"Complete"** — commito na `master`, faço push e encerro. Este é o único ponto em que o git
+  roda.
+- **"Ajustar: <descrição>"** — itero e repito o halt sem commitar.
+```
+
+Nunca ofereça "Complete" num halt intermediário. Oferecer commit no meio da feature convida
+exatamente o commit parcial que o fluxo existe para evitar.
+
+## Seções condicionais
+
+**Task visual** — acrescente: validação contra
+protótipo, testes E2E, matriz de estados cobertos, animações, acessibilidade e divergências do
+refinamento.
+
+**Task sem input externo** — inclua a linha: *"Segurança de inputs: N/A — a task não processa
+inputs externos."* A declaração é explícita; omitir a seção em
+silêncio não vale.
+
+**Premissas assumidas** — se você fechou alguma ambiguidade por conta própria (ver
+`requirements-closure`), liste-as com o default escolhido e o racional. O revisor precisa poder
+discordar de uma premissa antes que ela vire código consolidado.
+
+**Refinement-runner** — deixe explícito que **nenhum arquivo em `.specs/specs/` foi criado ou
+alterado**, e inclua o escopo consolidado (o que entra, o que não entra, critérios de aceite) que
+substitui o documento de spec.
+
+## O diff a revisar
+
+Em qualquer modo de feature, o diff é **todo o working tree** — não há commit parcial para separar
+as tasks.
+
+**Feature sem pausa:** o halt acontece uma vez só, ao fim da última task, e o relatório traz uma
+seção por task executada.
+
+**Feature com pausa:** cada halt intermediário cobre **só a task recém-concluída** (é isso que
+torna a revisão gerenciável), e o halt final resume as tasks anteriores em uma linha cada, detalha
+a última e aponta o diff acumulado para a revisão de conjunto.

package/assets/template/.agents/skills/feature-runner/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: feature-runner
+description: Executa tarefas documentadas em `.specs/specs/` — localiza a task, carrega contexto, confronta a spec com o código atual, implementa, roda o gate, dispara a verificação independente e PARA antes de commitar para code review humano. Entre tasks reentra em "Prosseguir"; commita e faz push apenas no "Complete" final; "Ajustar: ..." itera sem commitar. Carregue ao executar, implementar, rodar ou tocar uma feature ou task do projeto.
+---
+
+# feature-runner
+
+Executa tarefas documentadas em `.specs/specs/`. A stack, os comandos e as convenções do projeto
+estão em [`.agents/project.md`](../../project.md) — leia-o junto com a `execution-protocol`.
+
+O ciclo: **localizar → contextualizar → confrontar → implementar → verificar → halt para code
+review → complete**.
+
+Equivalências de tools Claude Code ↔ Cursor: `.agents/RUNTIME.md`.
+
+## Ponto de partida obrigatório
+
+**Carregue a skill `execution-protocol` antes de qualquer coisa.** Ela detém os princípios
+invioláveis (nada de commit sem aprovação, nada de ação destrutiva, escopo fechado, blast radius),
+a verificação do repositório, as convenções de código e todo o ciclo halt → ajustar → complete.
+Esta skill aqui só cobre o que é específico de executar uma spec.
+
+## Skills por camada
+
+| Carregue | Quando |
+|---|---|
+| `execution-protocol` | **sempre**, antes de tudo |
+| `spec-writing` | **sempre** — você lê a task, atualiza `status` e escreve o registro de Execuções no formato dela |
+| `test-strategy` | a entrega produz código testável — define o gate que fecha cada task |
+| `verification` | a entrega produz código com teste automatizado — o Verifier roda antes do halt |
+| `input-security` | o código toca 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 — consulta obrigatória ao protótipo antes de implementar |
+
+Task de backend puro: `execution-protocol` + `spec-writing` + `test-strategy` + `verification` +
+`input-security`. As convenções de arquitetura de cada app estão nos respectivos `CLAUDE.md`.
+
+## Fluxo
+
+Ponto de entrada pelo contexto: pedido de execução ⇒ **1**; **"Prosseguir"** ⇒ volta ao **3** com a
+próxima task; **"Ajustar: ..."** ⇒ ciclo de ajuste do `execution-protocol`; **"Complete"** ⇒ **7**.
+
+1. **Localizar a task e carregar contexto** → [localizar.md](references/localizar.md)
+2. **Verificar o repositório** → `execution-protocol`
+3. **Confrontar a spec com o código atual** → [divergencias.md](references/divergencias.md)
+4. **Marcar `in-progress` e implementar** → [implementar.md](references/implementar.md)
+5. **Gate + verificação independente** → skills `test-strategy` e `verification`
+6. **Halt** → [relatorio-halt.md](../execution-protocol/references/relatorio-halt.md)
+   — intermediário (resta task pendente) oferece "Prosseguir"; final oferece "Complete"
+7. **Complete, só no fim de tudo** → [git.md](../execution-protocol/references/git.md)
+
+Leia cada referência **por completo** no momento em que a fase começa — não antecipe todas.
+
+## Modo feature
+
+Quando o pedido é a feature inteira, execute as tasks na ordem de `meta.json.pages`, pulando as
+`completed`. Só pare quando todas estiverem `completed` ou o usuário abortar.
+
+**Por padrão há pausa de review a cada task:** você entrega o relatório de halt daquela task e
+aguarda **"Prosseguir"** (avança para a próxima) ou **"Ajustar: ..."** (itera nesta). O usuário
+pode dispensar a pausa, e aí você encadeia as tasks sozinho até a última.
+
+**Em nenhum dos dois o git roda no meio.** Cada task intermediária fecha com `status: completed` no
+frontmatter, o registro em Execuções e o código no **working tree**. O commit e o push acontecem
+**uma vez só**, no "Complete" depois da última task. A pausa muda quanto você revisa pelo caminho,
+nunca quanto é commitado.
+
+Não ofereça "Complete" enquanto restar task pendente — ver
+[relatorio-halt.md](../execution-protocol/references/relatorio-halt.md).
+
+## Specs Platform
+
+As docs são renderizadas pela Specs Platform (`@mir-code/specs-platform`) — `specs start` na raiz
+sobe a plataforma localmente. O botão "Rodar Tarefa" da UI dispara esta skill em um terminal novo, conforme
+`.specs/config.json`. Problema operacional da plataforma (não sobe, porta ocupada, botão não
+dispara): consulte o **Troubleshooting** de `SPECS.md` antes de mexer na configuração.
+
+## Notas
+
+- Chame tools em paralelo quando forem independentes.
+- Mantenha o relatório de halt enxuto — ele é a pauta do code review.

package/assets/template/.agents/skills/feature-runner/references/divergencias.md

@@ -0,0 +1,38 @@
+# Confrontar a spec com o código atual
+
+Antes de tocar código: o escopo ainda faz sentido? há decisão em aberto? há melhoria óbvia que vale
+propor?
+
+O refinamento foi escrito **antes** e pode ter envelhecido. **Não o siga cegamente.**
+
+## Divergências que exigem parada
+
+- decisão que contradiz código já mergeado (ex.: manda criar `UserRoleDialog`, mas já existe
+  `EditUserModal` mais completo);
+- decisão que contradiz o protótipo atual;
+- biblioteca ou primitivo que não cabe mais (deprecated, ou o projeto padronizou outro);
+- estrutura de rotas/arquivos que viola convenção recente;
+- critério que referencia algo inexistente — salvo se a task for justamente criar esse algo;
+- padrão obsoleto (ex.: `unstable_cache` onde a versão atual usa `cacheTag`);
+- abordagem que a doc atual (context7) desencoraja;
+- critério que conflita com uma decisão `active` de `.specs/STATE.md`.
+
+Para cada uma, `AskUserQuestion` com três coisas:
+
+1. **o que a spec diz** — citando o trecho;
+2. **o que existe hoje** — com evidência (`file:line`);
+3. **2–3 opções** — seguir assim mesmo, adaptar, refinar antes de executar — **mais a sua
+   recomendação**.
+
+Divergência pequena e previsível (um import que mudou de lugar) você ajusta sozinho e sinaliza no
+relatório de halt.
+
+## Lacunas de precisão no critério
+
+Critério de aceite sem desfecho preciso ("trata o erro graciosamente", "exibe mensagem amigável")
+não dá para testar — a asserção vira vaga e passa com implementação errada.
+
+Encontrou? **não invente o valor.** Pergunte qual é o desfecho esperado (status, campo, mensagem,
+estado persistido) e registre a resposta como decisão no relatório. Se o usuário disser "você
+decide", registre como **premissa** com o default escolhido e o racional, no formato da skill
+`requirements-closure`.

package/assets/template/.agents/skills/feature-runner/references/implementar.md

@@ -0,0 +1,80 @@
+# Implementar
+
+## 1. Marcar `in-progress`
+
+`Edit` no frontmatter da task: `status: pending` → `status: in-progress`. **Não commite** — a
+mudança entra no commit final. Não mexa no `meta.json`.
+
+## 2. Declarar o plano antes de escrever código
+
+Antes da primeira edição, diga explicitamente:
+
+- **Premissas** — o que você está assumindo; qualquer incerteza restante;
+- **Arquivos a tocar** — só os que a task exige;
+- **Como vai verificar** — qual gate, qual comando, o que prova que funcionou.
+
+Não prossiga sem isso. É o que impede a implementação de crescer sem controle.
+
+## 3. Testes antes da implementação
+
+Se a task produz código com tipo de teste exigido (ver matriz da skill `test-strategy`):
+
+1. Escreva os testes **derivados dos critérios de aceite da spec**, não do código.
+2. Cada critério vira pelo menos uma asserção cujo **valor afirmado** é o desfecho que a spec
+   define.
+3. Onde a spec não define valor preciso, registre como **lacuna de precisão** e pergunte — nunca
+   escreva asserção vaga que passa em silêncio.
+4. Casos de borda listados na spec viram casos de teste.
+
+**Restrições duras (integridade de teste):** nunca enfraqueça asserção, nunca delete ou pule caso
+de teste, nunca use `.skip`/`.todo` para contornar vermelho. Teste genuinamente errado ⇒ **pare e
+pergunte** antes de mexer.
+
+## 4. Implementar
+
+Satisfaça o **Escopo** e os **critérios de aceite** dos blocos do detalhamento técnico. Escreva o
+mínimo que passa nos testes e atende ao gate — melhoria estrutural fica para task de refactor.
+
+As convenções (formatação, tipagem, reuso antes de criação, idioma do código, política de
+comentários, tools de edição) estão na skill `execution-protocol`.
+
+**Frontend:** consulte o protótipo antes de implementar, conforme `prototype-check`. Se o projeto
+adotar as skills `ui-standards` e `input-security`, siga-as também.
+
+## 5. Gate
+
+Rode o gate do pacote tocado, com o comando que o `project.md` define para o nível do gate
+(ver a skill `test-strategy`).
+
+Saída ≠ 0 ⇒ **pare, corrija, rode de novo**. Não siga com vermelho. Confira que a contagem de
+testes não caiu.
+
+O comando de lint + format ao final é barato e recomendado. O build completo do repositório só
+quando a task exigir — é caro em monorepo. Ambos estão no `project.md`.
+
+## 6. Revisão pós-gate
+
+1. **Test Adequacy Review** (skill `test-strategy`, Checks A–D): cobertura com `file:line`,
+   litmus anti-raso, mapeamento reverso, conformidade. Qualquer falha ⇒ reescreva e rode o gate de
+   novo.
+2. **Divergiu da spec?** marque no código:
+   ```ts
+   // SPEC_DEVIATION: <o que divergiu>
+   // Motivo: <por que foi necessário>
+   ```
+   e registre no relatório de halt.
+3. **Complexidade:** um engenheiro sênior chamaria isso de complicado demais? Sim ⇒ simplifique e
+   rode o gate de novo.
+4. **Escopo:** você tocou algum arquivo que não estava no plano do passo 2? Se sim, justifique no
+   relatório ou reverta.
+
+## 7. Guarda de escopo durante a implementação
+
+Você vai notar coisas que dariam para melhorar. **Não aja sobre elas.**
+
+- **Bug** ⇒ traga para o usuário no relatório, ou registre como task separada.
+- **Melhoria** ⇒ vira "ponto de atenção" no relatório.
+- **Relacionado à task atual** ⇒ só entra se estiver nos critérios de aceite.
+
+Nunca "já que estou aqui". Scope creep durante a implementação é o principal destruidor de
+qualidade de review.

package/assets/template/.agents/skills/feature-runner/references/localizar.md

@@ -0,0 +1,46 @@
+# Localizar a task e carregar contexto
+
+## 1. Casar a entrada com uma `(feature, task)`
+
+`Glob` em `.specs/specs/*/meta.json`, leia os `meta.json` e case a entrada do usuário — ela pode vir
+como slug, título, nome de arquivo ou descrição livre.
+
+| Situação | O que fazer |
+|---|---|
+| Entrada identifica a feature **e** o usuário pediu a feature inteira | modo feature, a partir da primeira `pending` |
+| Entrada identifica só a feature e não está claro | `AskUserQuestion` listando as tasks na ordem de `pages` com o status de cada uma |
+| Ambiguidade entre features | `AskUserQuestion` |
+| Task já `completed` | **pare e pergunte** se a re-execução é intencional |
+
+## 2. Carregar contexto
+
+Em paralelo:
+
+- `CLAUDE.md` da raiz e `.specs/specs/CLAUDE.md`;
+- `meta.json` e `overview.md` da feature;
+- o arquivo da task;
+- as demais tasks da feature (dependências cruzadas);
+- tudo que a lista `**Depende de:**` linkar;
+- **`.specs/STATE.md`, seção `## Decisions`** — toda entrada `AD-NNN` com `Status: active` é
+  restrição de projeto que esta implementação precisa respeitar. Conflito com o que a task pede?
+  **pare e pergunte** antes de decidir: conformar ou propor supersessão.
+
+`PRD.md` / `SDD.md` só se a task for de design ou arquitetura.
+
+## 3. Procurar o que já existe
+
+Antes de escrever código novo, `Grep`/`Glob` nos diretórios de reuso do `project.md`:
+os pacotes compartilhados e o código das apps (a estrutura está no `project.md`).
+**Reuso vem antes de criação** — utilitário, tipo, componente,
+hook.
+
+Escopo amplo demais para `Glob`/`Grep`: no máximo **1** `Agent` com `subagent_type: Explore`, com
+foco específico.
+
+## 4. Cadeia de verificação de conhecimento
+
+Decisão que depende de versão de lib (o `project.md` lista as que mais mudam decisão): consulte a doc
+atual via sub-agente com MCP `context7` **antes** de implementar. Não confie na memória — a skill
+`requirements-closure` tem a cadeia completa (código → docs → context7 → web → declarar incerteza).
+
+**Nunca fabrique** API, campo ou comportamento. Não achou? diga "não sei" e pergunte.