@fabioramos_02/create-esteira-gov 0.1.0

package/README.md

@@ -0,0 +1,89 @@
+# @fabioramos_02/create-esteira-gov
+
+Scaffold de uma **esteira spec-driven multi-agente** para Claude Code, pensada para projetos
+novos do governo de MS. Em vez de 14 skills, são **4 agentes + 1 orquestrador**, com o **core
+agnóstico de linguagem e escopo** — a variabilidade vive em **presets** plugáveis (app, BI,
+dados, protótipo, blank). Design System: [`@design-system-ms/ds-sis`](https://www.npmjs.com/package/@design-system-ms/ds-sis).
+
+## Uso
+
+```bash
+npx @fabioramos_02/create-esteira-gov meu-projeto --preset app
+# sem --preset abre um wizard para escolher
+cd meu-projeto
+# abra no Claude Code e rode:  /esteira
+```
+
+## A esteira
+
+```mermaid
+flowchart LR
+    D[Demanda] --> E[/especificar/]
+    E -->|spec.md| P[/planejar/]
+    P -->|plano.md| I[/implementar/]
+    I -->|código| V[/validar/]
+    V -->|validacao.md| OK([Pronto])
+    V -.REPROVADO.-> E
+    O{{/esteira}} -.orquestra.-> E
+```
+
+| Etapa | Skill | Lê | Produz |
+|------:|-------|----|--------|
+| 1 | `/especificar` | demanda | `spec.md` |
+| 2 | `/planejar` | `spec.md` + preset | `plano.md` |
+| 3 | `/implementar` | `plano.md` + preset | código |
+| 4 | `/validar` | `spec.md` + código | `validacao.md` |
+| — | `/esteira` | demanda | encadeia 1→4 |
+
+Handoff é por **arquivos** em `specs/NNNN-<slug>/`. A **spec é a fonte da verdade**.
+
+## Presets
+
+| Preset | Escopo | Linguagem | DS |
+|--------|--------|-----------|----|
+| `app` | App web gov acessível | TypeScript | css + web components |
+| `bi` | Dashboard / Power BI | JSON/DAX | tokens (tema) |
+| `dados` | ETL + análise | Python | tokens (paleta) |
+| `prototipo` | Protótipo rápido | HTML/CSS | css |
+| `blank` | Só a esteira | a definir | none |
+
+O Design System serve **qualquer escopo** porque exporta **tokens JSON** (Style Dictionary):
+web usa `/css` + componentes; BI e dados leem `/tokens` para tema/paleta.
+
+## Regras do template gerado
+- SRP: 1 arquivo = 1 responsabilidade.
+- Máximo **250 linhas por arquivo** (`npm run check` no projeto da esteira valida isso).
+- Nunca hardcode de cor/espaçamento — sempre via DS.
+- Conventional Commits, GitHub Flow, pt-BR.
+
+## Criar um preset novo
+Adicionar uma linguagem/escopo **não exige tocar nos agentes**:
+
+1. Crie `presets/<nome>/preset.json`:
+   ```json
+   {
+     "nome": "<nome>",
+     "descricao": "...",
+     "linguagem": "...",
+     "stack": ["..."],
+     "ds": "css+wc | css | tokens | none",
+     "comandos": { "check": "...", "lint": "...", "test": "..." }
+   }
+   ```
+2. (Opcional) Crie `presets/<nome>/template/` com o scaffold inicial daquele tipo.
+3. Pronto — o preset aparece no CLI e no wizard.
+
+Os agentes leem `.esteira/preset.json` do projeto gerado e se adaptam à stack/comandos.
+
+## Desenvolvimento
+
+```bash
+npm install
+npm run build   # tsc -> dist/
+npm run check   # falha se algum arquivo passar de 250 linhas
+```
+
+Publicação: `npm publish --access public`.
+
+## Créditos
+Inspirado (e simplificado) a partir de [igoruehara/spec-driven](https://github.com/igoruehara/spec-driven).

package/dist/bin/index.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { run } from "../src/cli.js";
+run(process.argv.slice(2)).catch((err) => {
+    console.error(`✖ ${err instanceof Error ? err.message : err}`);
+    process.exit(1);
+});

package/dist/src/cli.js

@@ -0,0 +1,70 @@
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { listPresets, loadPreset, presetTemplateDir } from "./presets.js";
+import { copyTree } from "./copy.js";
+import { pickPreset } from "./wizard.js";
+// dist/src/cli.js -> raiz do pacote (onde vivem template/ e presets/)
+const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+function parseArgs(argv) {
+    const a = { help: false };
+    for (let i = 0; i < argv.length; i++) {
+        const t = argv[i];
+        if (t === "--help" || t === "-h")
+            a.help = true;
+        else if (t === "--preset" || t === "-p")
+            a.preset = argv[++i];
+        else if (!t.startsWith("-") && !a.nome)
+            a.nome = t;
+    }
+    return a;
+}
+function usage() {
+    console.log(`
+create-esteira-gov — scaffold de esteira spec-driven (gov MS)
+
+Uso:
+  npx @fabioramos_02/create-esteira-gov <nome> [--preset <preset>]
+
+Presets: ${listPresets(pkgRoot).join(", ") || "(nenhum)"}
+`);
+}
+export async function run(argv) {
+    const args = parseArgs(argv);
+    if (args.help || !args.nome) {
+        usage();
+        if (!args.nome)
+            process.exitCode = 1;
+        return;
+    }
+    const dest = resolve(process.cwd(), args.nome);
+    if (existsSync(dest) && readdirSync(dest).length > 0) {
+        throw new Error(`Diretório "${args.nome}" já existe e não está vazio.`);
+    }
+    const preset = args.preset ?? (await pickPreset(listPresets(pkgRoot)));
+    const cfg = loadPreset(pkgRoot, preset);
+    const vars = { nome: args.nome, preset: cfg.nome };
+    mkdirSync(dest, { recursive: true });
+    copyTree(join(pkgRoot, "template"), dest, vars); // core agnóstico
+    const pt = presetTemplateDir(cfg);
+    if (pt)
+        copyTree(pt, dest, vars); // overlay do preset
+    writeManifest(dest, cfg);
+    printNext(args.nome, cfg);
+}
+/** Grava .esteira/preset.json no projeto p/ os agentes lerem stack/comandos. */
+function writeManifest(dest, cfg) {
+    const { dir: _omit, ...manifest } = cfg;
+    mkdirSync(join(dest, ".esteira"), { recursive: true });
+    writeFileSync(join(dest, ".esteira", "preset.json"), JSON.stringify(manifest, null, 2) + "\n");
+}
+function printNext(nome, cfg) {
+    console.log(`
+✔ Projeto "${nome}" criado (preset: ${cfg.nome} — ${cfg.descricao}).
+
+Próximos passos:
+  cd ${nome}
+  # abra no Claude Code e rode a esteira completa:  /esteira
+  # ou etapa a etapa:  /especificar -> /planejar -> /implementar -> /validar
+`);
+}

package/dist/src/copy.js

@@ -0,0 +1,41 @@
+import { readdirSync, readFileSync, writeFileSync, mkdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+const TEXT_EXT = new Set([
+    ".md", ".ts", ".tsx", ".js", ".mjs", ".cjs", ".json",
+    ".css", ".html", ".txt", ".yml", ".yaml", ".py",
+]);
+// npm remove arquivos ".gitignore" de pacotes publicados; guardamos como
+// "gitignore" no template e renomeamos na cópia.
+const RENAME = { gitignore: ".gitignore" };
+const TEXT_NAMES = new Set(["gitignore"]);
+function isText(name) {
+    if (name.startsWith(".") || TEXT_NAMES.has(name))
+        return true;
+    const dot = name.lastIndexOf(".");
+    const ext = dot >= 0 ? name.slice(dot) : "";
+    return TEXT_EXT.has(ext);
+}
+/** Substitui ocorrências de {{chave}} pelos valores em vars. */
+function applyVars(content, vars) {
+    return content.replace(/\{\{(\w+)\}\}/g, (m, k) => (k in vars ? vars[k] : m));
+}
+/**
+ * Copia srcDir -> destDir recursivamente.
+ * Arquivos de texto recebem substituição de placeholders; binários são copiados crus.
+ */
+export function copyTree(srcDir, destDir, vars) {
+    mkdirSync(destDir, { recursive: true });
+    for (const entry of readdirSync(srcDir)) {
+        const from = join(srcDir, entry);
+        const to = join(destDir, RENAME[entry] ?? entry);
+        if (statSync(from).isDirectory()) {
+            copyTree(from, to, vars);
+        }
+        else if (isText(entry)) {
+            writeFileSync(to, applyVars(readFileSync(from, "utf8"), vars));
+        }
+        else {
+            writeFileSync(to, readFileSync(from));
+        }
+    }
+}

package/dist/src/presets.js

@@ -0,0 +1,33 @@
+import { readdirSync, readFileSync, existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+export function presetsDir(pkgRoot) {
+    return join(pkgRoot, "presets");
+}
+/** Lista nomes de presets válidos (pastas com preset.json). */
+export function listPresets(pkgRoot) {
+    const dir = presetsDir(pkgRoot);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((n) => existsSync(join(dir, n, "preset.json")))
+        .sort();
+}
+/** Carrega e valida um preset pelo nome. */
+export function loadPreset(pkgRoot, nome) {
+    const dir = join(presetsDir(pkgRoot), nome);
+    const file = join(dir, "preset.json");
+    if (!existsSync(file)) {
+        const disp = listPresets(pkgRoot).join(", ") || "(nenhum)";
+        throw new Error(`Preset "${nome}" não encontrado. Disponíveis: ${disp}`);
+    }
+    const data = JSON.parse(readFileSync(file, "utf8"));
+    if (!data.nome || !data.comandos) {
+        throw new Error(`preset.json inválido em ${file}: faltam campos obrigatórios.`);
+    }
+    return { ...data, dir };
+}
+/** Pasta template/ do preset, se existir. */
+export function presetTemplateDir(preset) {
+    const t = join(preset.dir, "template");
+    return existsSync(t) && statSync(t).isDirectory() ? t : null;
+}

package/dist/src/wizard.js

@@ -0,0 +1,24 @@
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+/** Pergunta interativamente qual preset usar quando nenhum foi passado. */
+export async function pickPreset(presets) {
+    if (presets.length === 0)
+        throw new Error("Nenhum preset disponível no pacote.");
+    if (presets.length === 1)
+        return presets[0];
+    const rl = createInterface({ input: stdin, output: stdout });
+    try {
+        stdout.write("\nPresets disponíveis:\n");
+        presets.forEach((p, i) => stdout.write(`  ${i + 1}) ${p}\n`));
+        const ans = (await rl.question("Escolha (número ou nome): ")).trim();
+        const byIndex = presets[Number(ans) - 1];
+        if (byIndex)
+            return byIndex;
+        if (presets.includes(ans))
+            return ans;
+        throw new Error(`Opção inválida: "${ans}".`);
+    }
+    finally {
+        rl.close();
+    }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@fabioramos_02/create-esteira-gov",
+  "version": "0.1.0",
+  "description": "Scaffold de esteira spec-driven multi-agente Claude para projetos gov MS (app, BI, dados, protótipo).",
+  "type": "module",
+  "bin": {
+    "create-esteira-gov": "dist/bin/index.js"
+  },
+  "files": [
+    "dist",
+    "template",
+    "presets"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "check": "node scripts/check-limits.mjs",
+    "prepublishOnly": "npm run build && npm run check"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "spec-driven",
+    "claude",
+    "claude-code",
+    "scaffold",
+    "create",
+    "governo",
+    "design-system",
+    "ms"
+  ],
+  "author": "Fabio Ramos",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.4.0"
+  }
+}

package/presets/app/preset.json

@@ -0,0 +1,12 @@
+{
+  "nome": "app",
+  "descricao": "App web gov acessível (Next/React + DS)",
+  "linguagem": "typescript",
+  "stack": ["next", "react"],
+  "ds": "css+wc",
+  "comandos": {
+    "check": "npm run build",
+    "lint": "npm run lint",
+    "test": "npm test"
+  }
+}

package/presets/app/template/README.md

@@ -0,0 +1,10 @@
+# {{nome}} (preset `app`)
+
+App web gov acessível. Design System: `@design-system-ms/ds-sis` (CSS + Web Components). WCAG AA.
+
+## Início
+1. `npm install`
+2. Configure seu bundler (Next.js ou Vite) — este scaffold é mínimo de propósito.
+3. Veja `src/exemplo-ds.ts` para consumir o DS.
+
+Esteira: rode `/esteira` no Claude Code (ou etapa a etapa).

package/presets/app/template/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "{{nome}}",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@design-system-ms/ds-sis": "^0.1.0"
+  },
+  "scripts": {
+    "build": "echo 'configure seu bundler (Next.js ou Vite)'",
+    "lint": "echo 'configure o eslint'",
+    "test": "echo 'configure os testes'"
+  }
+}

package/presets/app/template/src/exemplo-ds.ts

@@ -0,0 +1,9 @@
+// Exemplo de consumo do Design System gov (preset app, ds = "css+wc").
+// 1) CSS base do DS:
+import "@design-system-ms/ds-sis/css";
+// 2) Web components do DS (use as tags no HTML, ex.: <ds-button>):
+import "@design-system-ms/ds-sis";
+
+// Regra: nunca hardcode cor/espaçamento — use classes/tokens do DS.
+export const dica =
+  "Veja o README de @design-system-ms/ds-sis para a lista de componentes disponíveis.";

package/presets/bi/preset.json

@@ -0,0 +1,12 @@
+{
+  "nome": "bi",
+  "descricao": "Dashboard / Power BI com tema do DS",
+  "linguagem": "json",
+  "stack": ["power-bi"],
+  "ds": "tokens",
+  "comandos": {
+    "check": "node tema/build-tema.mjs",
+    "lint": "echo 'sem lint'",
+    "test": "echo 'sem teste'"
+  }
+}

package/presets/bi/template/README.md

@@ -0,0 +1,10 @@
+# {{nome}} (preset `bi`)
+
+Projeto de BI / Power BI. Design System consumido via **tokens JSON**.
+
+## Tema do DS
+1. `npm i @design-system-ms/ds-sis`
+2. `node tema/build-tema.mjs` → gera `tema/tema-powerbi.json`
+3. No Power BI: **Exibir > Temas > Procurar temas** e selecione o JSON gerado.
+
+Esteira: rode `/esteira` no Claude Code (foco em modelagem + indicadores).

package/presets/bi/template/tema/build-tema.mjs

@@ -0,0 +1,29 @@
+// Gera um tema do Power BI a partir dos tokens do DS gov (preset bi, ds = "tokens").
+// Requer: npm i @design-system-ms/ds-sis
+import { writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+
+let tokens;
+try {
+  tokens = require("@design-system-ms/ds-sis/tokens");
+} catch {
+  console.log("Instale o DS primeiro: npm i @design-system-ms/ds-sis");
+  process.exit(0);
+}
+
+function extrairCores(t) {
+  // tokens.json segue o formato Style Dictionary — ajuste conforme a estrutura real.
+  const cores = JSON.stringify(t).match(/#[0-9a-fA-F]{6}/g) || [];
+  return [...new Set(cores)].slice(0, 8);
+}
+
+const tema = {
+  name: "DS-MS",
+  dataColors: extrairCores(tokens),
+  background: "#FFFFFF",
+};
+
+writeFileSync("tema/tema-powerbi.json", JSON.stringify(tema, null, 2) + "\n");
+console.log("✔ tema/tema-powerbi.json gerado a partir dos tokens do DS.");

package/presets/blank/preset.json

@@ -0,0 +1,12 @@
+{
+  "nome": "blank",
+  "descricao": "Só a esteira; escolha a stack na etapa de planejar",
+  "linguagem": "indefinida",
+  "stack": [],
+  "ds": "none",
+  "comandos": {
+    "check": "echo 'defina o check ao planejar'",
+    "lint": "echo 'defina o lint ao planejar'",
+    "test": "echo 'defina o test ao planejar'"
+  }
+}

package/presets/dados/preset.json

@@ -0,0 +1,12 @@
+{
+  "nome": "dados",
+  "descricao": "ETL + análise de dados (Python) com paleta do DS",
+  "linguagem": "python",
+  "stack": ["python", "pandas"],
+  "ds": "tokens",
+  "comandos": {
+    "check": "python -m compileall src",
+    "lint": "ruff check .",
+    "test": "pytest -q"
+  }
+}

package/presets/dados/template/README.md

@@ -0,0 +1,10 @@
+# {{nome}} (preset `dados`)
+
+ETL + análise em Python. As cores dos gráficos vêm dos **tokens JSON** do DS gov.
+
+## Início
+1. `pip install -r requirements.txt`
+2. (opcional) `npm i @design-system-ms/ds-sis` para a paleta oficial.
+3. `python src/analise_exemplo.py`
+
+Esteira: rode `/esteira` no Claude Code.

package/presets/dados/template/requirements.txt

@@ -0,0 +1,2 @@
+pandas
+matplotlib

package/presets/dados/template/src/analise_exemplo.py

@@ -0,0 +1,18 @@
+"""Exemplo: usar a paleta do DS gov em gráficos (preset dados, ds = "tokens")."""
+import json
+import re
+from pathlib import Path
+
+
+def carregar_paleta() -> list[str]:
+    """Lê as cores dos tokens do DS. Instale com: npm i @design-system-ms/ds-sis"""
+    p = Path("node_modules/@design-system-ms/ds-sis/dist/json/tokens.json")
+    if not p.exists():
+        return ["#244061"]  # fallback até instalar o DS
+    dados = json.loads(p.read_text(encoding="utf-8"))
+    cores = re.findall(r"#[0-9a-fA-F]{6}", json.dumps(dados))
+    return list(dict.fromkeys(cores))[:8]
+
+
+if __name__ == "__main__":
+    print("Paleta DS:", carregar_paleta())

package/presets/prototipo/preset.json

@@ -0,0 +1,12 @@
+{
+  "nome": "prototipo",
+  "descricao": "Protótipo rápido (HTML + DS), sem rigor de teste",
+  "linguagem": "html",
+  "stack": ["html", "css"],
+  "ds": "css",
+  "comandos": {
+    "check": "echo 'ok'",
+    "lint": "echo 'sem lint'",
+    "test": "echo 'sem teste'"
+  }
+}

package/presets/prototipo/template/README.md

@@ -0,0 +1,9 @@
+# {{nome}} (preset `prototipo`)
+
+Protótipo rápido HTML + DS gov. Sem rigor de teste — foco em validar ideia.
+
+## Início
+1. `npm i @design-system-ms/ds-sis`
+2. Abra `index.html` no navegador (ou use uma extensão Live Server).
+
+Esteira: rode `/esteira` (foco em `/especificar` + prototipar).

package/presets/prototipo/template/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="pt-BR">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{{nome}} — protótipo</title>
+    <!-- DS gov: instale com `npm i @design-system-ms/ds-sis` -->
+    <link rel="stylesheet" href="node_modules/@design-system-ms/ds-sis/dist/css/ds-sis.css" />
+  </head>
+  <body>
+    <main class="container">
+      <h1>{{nome}}</h1>
+      <p>Protótipo rápido com o Design System gov. Use classes/tokens do DS, sem hardcode.</p>
+    </main>
+  </body>
+</html>

package/template/.claude/skills/especificar/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: especificar
+description: Etapa 1 da esteira spec-driven. Transforma uma demanda solta em spec.md (a fonte da verdade) com objetivo, escopo e critérios de aceite testáveis. Use ao iniciar uma feature nova.
+---
+
+# /especificar — Etapa 1 da esteira
+
+Transforma demanda solta em **spec** rastreável.
+
+**Lê:** demanda do usuário (texto).
+**Produz:** `specs/NNNN-<slug>/spec.md` (base: `specs/_templates/spec.md`).
+
+## Passos
+1. Pergunte só o crítico (máx. 3): objetivo, escopo, restrições.
+2. Crie `specs/NNNN-<slug>/` (NNNN = próximo número sequencial).
+3. Preencha o template: objetivo único, escopo (inclui/não inclui), AC testáveis.
+4. Não invente requisito. Faltou info → registre como suposição explícita.
+
+## Pronto quando
+- [ ] objetivo mensurável
+- [ ] escopo delimitado
+- [ ] ≥ 1 AC por comportamento, todos verificáveis
+
+Próxima etapa: `/planejar`.

package/template/.claude/skills/esteira/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: esteira
+description: Orquestrador da esteira spec-driven. Encadeia as 4 etapas (especificar → planejar → implementar → validar) com handoff via arquivos. Use para tocar uma feature de ponta a ponta.
+---
+
+# /esteira — Orquestrador
+
+Roda a esteira inteira, com handoff explícito via arquivos em `specs/NNNN-<slug>/`.
+
+## Fluxo
+1. `/especificar` → `spec.md`
+2. `/planejar` → `plano.md` (só começa com a spec pronta)
+3. `/implementar` → código (só começa com o plano pronto)
+4. `/validar` → `validacao.md` (confronta com a spec)
+
+## Regras
+- Não pule etapa: cada uma só inicia quando a anterior entregou seu artefato.
+- Se `/validar` reprovar, volte à etapa apontada no veredito e reexecute dali.
+- Não duplique conteúdo entre etapas — cada artefato é a fonte da etapa seguinte.
+- Pare e peça confirmação ao usuário antes de decisões irreversíveis.

package/template/.claude/skills/implementar/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: implementar
+description: Etapa 3 da esteira spec-driven. Escreve o código seguindo plano.md, o Design System do governo e os comandos do preset, mantendo SRP e 250 linhas por arquivo. Use depois de /planejar.
+---
+
+# /implementar — Etapa 3 da esteira
+
+Escreve código fiel ao plano.
+
+**Lê:** `specs/NNNN-<slug>/plano.md` + `.esteira/preset.json`.
+**Produz:** código no projeto.
+
+## Regras
+- Siga a árvore e os contratos do plano. Precisou desviar → atualize o plano antes.
+- 1 responsabilidade por arquivo, ≤ 250 linhas.
+- Design System (`@design-system-ms/ds-sis`) conforme `preset.ds`:
+  - `css+wc` → importe `/css` + web components (`.`)
+  - `css` → importe `/css`
+  - `tokens` → carregue `/tokens` (JSON) p/ tema/paleta (BI, gráficos, Python)
+  - **nunca** hardcode cor/espaçamento.
+- Ao final, rode `preset.comandos.check`.
+
+## Pronto quando
+- [ ] todos os arquivos do plano implementados
+- [ ] `check` passa
+- [ ] sem hardcode de DS
+
+Anterior: `/planejar` · Próxima: `/validar`.

package/template/.claude/skills/planejar/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: planejar
+description: Etapa 2 da esteira spec-driven. Converte spec.md em plano.md — arquitetura, árvore de arquivos e contratos — respeitando o preset, o princípio de responsabilidade única e o limite de 250 linhas por arquivo. Use depois de /especificar.
+---
+
+# /planejar — Etapa 2 da esteira
+
+Desenha COMO construir, antes de escrever código.
+
+**Lê:** `specs/NNNN-<slug>/spec.md` + `.esteira/preset.json` (linguagem/stack).
+**Produz:** `specs/NNNN-<slug>/plano.md` (base: `specs/_templates/plano.md`).
+
+## Passos
+1. Leia a spec e o preset.
+2. Defina camadas e a árvore de arquivos — cada arquivo com 1 responsabilidade e ≤ 250 linhas.
+3. Para cada arquivo: responsabilidade + entrada → saída.
+4. Defina ordem de execução e riscos.
+
+## Pronto quando
+- [ ] todo AC da spec coberto por algum arquivo
+- [ ] nenhum arquivo planejado tende a passar de 250 linhas
+- [ ] contratos sem ambiguidade para implementar
+
+Anterior: `/especificar` · Próxima: `/implementar`.

package/template/.claude/skills/validar/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: validar
+description: Etapa 4 da esteira spec-driven. Confronta o código com a spec e os gates de qualidade (AC, lint, test, limite de 250 linhas, uso correto do Design System) e gera validacao.md. Use por último.
+---
+
+# /validar — Etapa 4 da esteira
+
+Confere se o código cumpre a spec.
+
+**Lê:** `specs/NNNN-<slug>/spec.md` + código + `.esteira/preset.json`.
+**Produz:** `specs/NNNN-<slug>/validacao.md` (base: `specs/_templates/validacao.md`).
+
+## Passos
+1. Marque cada AC da spec como OK/NOK com evidência.
+2. Rode os gates: `preset.comandos.lint`, `preset.comandos.test`, limite de 250 linhas.
+3. Cheque DS: sem cor/espaçamento hardcoded.
+4. Veredito: APROVADO só se todos os AC e gates passam.
+
+## Pronto quando
+- [ ] todos os AC OK
+- [ ] lint + test + limite de 250 OK
+- [ ] veredito escrito
+
+Anterior: `/implementar`. Se REPROVADO → volte à etapa indicada no veredito.

package/template/CLAUDE.md

@@ -0,0 +1,24 @@
+# {{nome}} — convenções do projeto
+
+Projeto gov MS estruturado com a **esteira spec-driven** (preset: `{{preset}}`).
+
+## Fluxo de trabalho
+Toda feature passa pela esteira (skills em `.claude/skills/`):
+
+`/especificar` → `/planejar` → `/implementar` → `/validar`
+
+Ou rode `/esteira` para tocar tudo de ponta a ponta. Os artefatos ficam em
+`specs/NNNN-<slug>/` (`spec.md`, `plano.md`, `validacao.md`). **A spec é a fonte da verdade** —
+o código deriva dela, não o contrário.
+
+## Regras
+- **SRP:** 1 arquivo = 1 responsabilidade.
+- **Máx 250 linhas por arquivo.**
+- **Design System gov:** `@design-system-ms/ds-sis` — nunca hardcode de cor/espaçamento.
+  Modo de consumo conforme `.esteira/preset.json` (campo `ds`).
+- Conventional Commits, GitHub Flow.
+- Código e comunicação em pt-BR.
+
+## Preset
+Stack, linguagem e comandos (`check`/`lint`/`test`) ficam em `.esteira/preset.json`.
+Os agentes leem esse arquivo para se adaptar à linguagem/escopo do projeto.

package/template/gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+.DS_Store
+*.log

package/template/specs/_templates/plano.md

@@ -0,0 +1,22 @@
+# Plano — <feature>
+
+> Deriva de `spec.md`. Cada arquivo ≤ 250 linhas, 1 responsabilidade.
+
+## Arquitetura
+<camadas / abordagem em 2-3 linhas>
+
+## Árvore de arquivos
+```
+src/...
+```
+
+## Contratos
+| Arquivo | Responsabilidade | Entrada → Saída |
+|---------|------------------|-----------------|
+|         |                  |                 |
+
+## Ordem de execução
+1. ...
+
+## Riscos / decisões
+- ...

package/template/specs/_templates/spec.md

@@ -0,0 +1,17 @@
+# Spec — <feature>
+
+> Fonte da verdade. O código deriva daqui.
+
+## Objetivo
+<frase única e mensurável>
+
+## Escopo
+- **Inclui:** ...
+- **Não inclui:** ...
+
+## Critérios de aceite (AC)
+- [ ] AC1 — <comportamento verificável>
+- [ ] AC2 — ...
+
+## Restrições / notas
+- ...

package/template/specs/_templates/validacao.md

@@ -0,0 +1,16 @@
+# Validação — <feature>
+
+> Confronta o código com `spec.md`.
+
+## Critérios de aceite
+- [ ] AC1 — OK/NOK + evidência
+- [ ] AC2 — ...
+
+## Gates de qualidade
+- [ ] lint (`preset.comandos.lint`) ok
+- [ ] test (`preset.comandos.test`) ok
+- [ ] limite de 250 linhas ok
+- [ ] DS: sem cor/espaçamento hardcoded
+
+## Veredito
+APROVADO / REPROVADO — <motivo; se reprovado, indicar a etapa para retorno>