create-sdd-ai-stack 0.1.17

package/README.md

@@ -0,0 +1,260 @@
+# 🤖 create-sdd-ai-stack
+
+> **O kit de regras de desenvolvimento para agentes de IA, baseado em Spec-Driven Development (SDD).**
+> Stack padrão: **Next.js 16**. Um `npx` e você tem um projeto com regras, arquitetura, design system e SDD prontos.
+
+```bash
+npx create-sdd-ai-stack meu-dashboard
+```
+
+---
+
+## 🎯 O que é isto
+
+Um **template de regras + código** para agentes de IA (Claude Code, Cursor, Copilot, Codex, Gemini CLI, Cline, Windsurf…).
+
+O agente abre o projeto, lê **uma** sequência de arquivos, e já sabe:
+o que construir agora, como estruturar, como escrever código, como commitar, quando parar.
+
+| Entrega | O que você recebe |
+| --- | --- |
+| **Regras** | `SDD/` com leis do agente, stack, design, arquitetura, SDD e stacks por ferramenta |
+| **Template** | App Next.js 16 completo, com design system já aplicado e buildando |
+| **CLI** | `npx create-sdd-ai-stack <nome>` — cria tudo em 1 comando |
+| **Submodule** | Instala só as regras em qualquer projeto, com atalhos na raiz |
+
+---
+
+## ⚡ Começando
+
+### 1. Projeto novo (recomendado)
+
+```bash
+npx create-sdd-ai-stack meu-app
+cd meu-app
+npm run dev
+```
+
+O que nasce:
+
+```text
+meu-app/
+├── src/
+│   ├── app/           # rotas (marketing pública + /app logado)
+│   ├── features/      # vertical slice de exemplo (domain/application/infrastructure/ui)
+│   ├── shared/        # design system, lib, server-only
+│   ├── proxy.ts       # network boundary + headers
+│   └── app/globals.css# TOKENS DO DESIGN SYSTEM
+├── tests/             # unit + e2e prontos
+├── SDD/               # 🧠 as regras
+├── AGENTS.md          # → atalho para ./SDD/AGENTS.md
+├── CLAUDE.md, GEMINI.md, .cursorrules, .github/copilot-instructions.md, …
+└── package.json
+```
+
+### 2. Projeto existente (só as regras)
+
+```bash
+# Opção A — submodule (atualiza com git)
+git submodule add https://github.com/marcelinosandroni/sdd-ai-stack.git SDD
+node SDD/SKILLS/install-submodule/install-submodule.mjs
+
+# Opção B — CLI
+npx create-sdd-ai-stack . --rules-only
+```
+
+Os atalhos da raiz (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`…) apontam para `./SDD/AGENTS.md`,
+então **todo agente já começa pelo lugar certo** — sem você precisar configurar nada.
+
+Atualizar as regras depois:
+
+```bash
+git submodule update --remote --merge SDD
+```
+
+> ⚠️ O `.gitignore` do app gerado protege `.env.local`, `.next/` e `node_modules/`.
+> Nunca commite um `.env` de verdade — só o `.env.example` (que tem placeholders).
+
+### 3. Opções da CLI
+
+```bash
+npx create-sdd-ai-stack meu-app --template next      # template (padrão)
+npx create-sdd-ai-stack meu-app --rules-only         # só as regras
+npx create-sdd-ai-stack meu-app --install            # roda npm install
+npx create-sdd-ai-stack meu-app --git                # git init + 1º commit
+npx create-sdd-ai-stack meu-app --submodule          # SDD/ como git submodule
+npx create-sdd-ai-stack meu-app --submodule <url>    # de um fork seu
+npx create-sdd-ai-stack meu-app --shortcuts stub     # sem symlink (Windows sem dev mode)
+```
+
+---
+
+## 🧠 O mapa das regras (`SDD/`)
+
+```text
+SDD/
+├── AGENTS.md            ⭐ leis + fluxo — LEIA PRIMEIRO
+├── specs/PLAN.md        ⭐ a task AGORA
+├── APP.md               o que é este app
+├── APP-STACK.md         qual stack este app usa
+├── NEXT.md              ⭐ Next.js 16 (stack padrão)
+├── NODE.md              Node.js puro (worker, cron, fila)
+├── REACT.md             React (server-first)
+├── DESIGN.md            🎨 design system completo
+├── ARCHITECTURE.md      🏗️ vertical slices
+├── stacks/              🧱 por ferramenta
+│   ├── typescript.md    tailwind.md     shadcn.md
+│   ├── testing.md       database.md     ai.md
+│   └── git.md           ci.md
+├── specs/               SDD operacional
+│   ├── PLAN.md  BACKLOG.md  ROADMAP.md
+│   ├── tasks/TASK_TEMPLATE.md
+│   └── history/phases/
+├── docs/                PRODUCT.md  CHANGELOG.md  PLANNING.md
+└── SKILLS/              automações (create-feature, install-submodule)
+```
+
+### Ordem de leitura imposta pelo `AGENTS.md`
+
+```text
+1. SDD/AGENTS.md      leis e fluxo
+2. SDD/specs/PLAN.md  a única task [-]
+3. SDD/APP.md         o que é este app
+4. SDD/APP-STACK.md   qual stack
+5. SDD/NEXT.md        regras da stack
+6. SDD/DESIGN.md      só se mexer em UI
+7. SDD/stacks/…       só a ferramenta que está tocando
+```
+
+> Cada doc de regra tem um **roteador no topo**: "se você está fazendo X, leia §Y".
+> Isso mantém o contexto do agente pequeno — importante, porque contexto longo é onde o agente morre.
+
+---
+
+## 🎨 Design System
+
+O `DESIGN.md` implementa o **Executive Engineering**: ardósia profunda (nunca preto puro),
+micro-bordas de 1px, acentos em lime neon `#BAF336` e mint `#34D399`, tipografia tripla
+(**Manrope** estrutural + **JetBrains Mono** técnica + **Playfair Display** editorial), grid de 12 colunas com max 1320px.
+
+Os tokens vivem em `src/app/globals.css` (bloco `@theme` do Tailwind v4) e viram utilitários
+(`bg-surface-raised`, `text-text-secondary`, `text-label-mono`, `border-border-subtle`…) +
+primitivos (`btn-primary`, `btn-secondary`, `card`, `card-metric`, `chip`, `field`).
+
+**Um lugar só.** Mudou o design? Muda no `@theme`, nunca no componente.
+
+---
+
+## 🏗️ Arquitetura
+
+Vertical slices. Uma pasta por domínio, com tudo que aquele domínio precisa:
+
+```text
+src/features/<dominio>/
+├── domain/           # entidades + contratos (I*.ts) — zero dependência
+├── application/      # use cases — regra pura, sem Next, sem Prisma
+├── infrastructure/   # Prisma, HTTP, filas
+├── container.ts      # DI do slice
+├── queries.ts        # entrada de leitura
+├── actions.ts        # entrada de escrita (Server Action)
+└── ui/               # componentes do domínio
+```
+
+Motivo de ser assim: **para entender um requisito você abre uma pasta só** — e o
+`application/` é testável sem mock de infra.
+
+---
+
+## 🚀 Publicar no npm
+
+Fluxo único: **você versiona, o GitHub Actions publica.**
+
+```bash
+npm run version:minor              # 0.1.17 → 0.2.0 (commita + cria tag v0.2.0)
+git push origin main
+git push origin --tags            # ← dispara a publicação
+```
+
+A primeira vez precisa resolver a autenticação. Com **2FA ligado na conta npm**, um token
+comum não publica (`EOTP` — o CI não tem como digitar o OTP). Duas saídas:
+
+```bash
+# A. Recomendado: publica a 1ª versão da sua máquina, ativa OIDC e apaga o token
+npm publish --access public --provenance=false --otp=123456
+#   ⚠️ --provenance=false é obrigatório fora do CI: o npm exige OIDC para gerar
+#      provenance e falha com "provider: null" se não achar o provedor
+# depois: npmjs.com → create-sdd-ai-stack → Settings → Trusted publishing
+#   owner: marcelinosandroni · repo: sdd-ai-stack · workflow: release.yml · allow: npm publish
+gh secret delete NPM_TOKEN --repo marcelinosandroni/sdd-ai-stack
+
+# B. Ponte: token granular com "Bypass 2FA" marcado (deprecado pelo npm em jan/2027)
+gh secret set NPM_TOKEN --repo marcelinosandroni/sdd-ai-stack
+```
+
+O workflow escolhe o modo sozinho: **com** `NPM_TOKEN` usa token, **sem** ele usa OIDC.
+Nada de token fica gravado em arquivo.
+
+**Guards antes de publicar:** `npm test` (22 testes) · links da doc · tag `vX.Y.Z` bate com
+o `package.json` · 10 arquivos essenciais presentes no tarball · `npm ≥ 11.5.1` · `concurrency` · provenance.
+
+📖 Passo a passo completo (os 3 caminhos de auth, troubleshooting e o caminho stage-only)
+em [`docs/RELEASE.md`](./docs/RELEASE.md).
+
+---
+
+## 🔌 Agentes suportados
+
+Os atalhos da raiz são criados para:
+
+| Arquivo | Agente |
+| --- | --- |
+| `AGENTS.md` | padrão de mercado (Cursor, Codex, Windsurf, Cline, Gemini) |
+| `CLAUDE.md` | Claude Code |
+| `GEMINI.md` | Gemini CLI |
+| `.cursorrules` | Cursor (formato antigo) |
+| `.windsurfrules` | Windsurf |
+| `.github/copilot-instructions.md` | GitHub Copilot |
+| `.clinerules` | Cline |
+
+Todos apontam para `SDD/AGENTS.md`. Nenhuma configuração manual necessária.
+
+---
+
+## 🧪 Verificação
+
+```bash
+npm test        # 20 testes da CLI, do scaffold e da documentação
+```
+
+O template em `template/next/` é validado de verdade: `typecheck` + `lint` + `test` + `test:e2e` + `build`.
+
+---
+
+## 📚 SKILLS
+
+| SKILL | O que faz |
+| --- | --- |
+| `create-feature` | Cria um vertical slice novo com domain/application/container/queries/actions |
+| `install-submodule` | Instala as regras em projeto existente + cria atalhos |
+| `check-docs` | Valida que todo link relativo entre documentos resolve |
+
+---
+
+## 🛡️ Qualidade
+
+```bash
+npm test                          # 22 testes: CLI, scaffold e integridade da documentação
+node SDD/SKILLS/check-docs/check-docs.mjs   # 29 documentos, links relativos
+npm run check:pack                # confere o que vai para o npm (71 arquivos, ~62 kB)
+```
+
+O template em `template/next/` é validado de verdade: `typecheck` + `lint` + `test` + `test:e2e` + `build`.
+O CI (`.github/workflows/ci.yml`) refaz essa validação a cada push, **gerando o app a partir do próprio template**.
+
+---
+
+## 👨‍💻 Autor
+
+**Marcelino Sandroni** — [github.com/marcelinosandroni](https://github.com/marcelinosandroni)
+
+MIT License.

package/SKILLS/check-docs/SKILL.md

@@ -0,0 +1,24 @@
+# 🧩 SKILL: check-docs
+
+> Valida que **todo link relativo entre documentos** resolve. Roda no hook de commit
+> e no CI para uma regra nunca apontar para arquivo morto.
+
+## ▶️ Uso
+
+```bash
+node SDD/SKILLS/check-docs/check-docs.mjs
+node SDD/SKILLS/check-docs/check-docs.mjs ../outro-projeto
+```
+
+## 📦 O que verifica
+
+- Coleta todo `.md` a partir da raiz do `SDD/`
+- Ignora blocos de código (` ``` ` / `~~~ `) — link ilustrativo dentro de exemplo não conta
+- Ignora `node_modules`, `.next`, `test-results`, `playwright-report`
+- Saída: exit 1 com a lista dos quebrados, ou exit 0 com o total de documentos
+
+## ✅ Quando rodar
+
+- Antes de commitar mudança em documentação
+- No CI, junto com os testes
+- Depois de renomear/mover qualquer documento de regra

package/SKILLS/check-docs/check-docs.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+/**
+ * SDD SKILL: check-docs
+ * Valida que todo link relativo entre documentos markdown resolve.
+ *
+ * Uso: node SDD/SKILLS/check-docs/check-docs.mjs [raiz]
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(process.argv[2] ?? path.join(here, "..", ".."));
+
+function stripCodeFences(md) {
+  return md.replace(/```[\s\S]*?```/g, "").replace(/~~~[\s\S]*?~~~/g, "");
+}
+
+/**
+ * `template/` é excluído de propósito: o README dele aponta para `./SDD/...`,
+ * que só existe DEPOIS do scaffold. Validar aqui daria falso positivo.
+ */
+function collectMarkdown(dir) {
+  const files = [];
+  (function walk(p) {
+    if (!fs.existsSync(p)) return;
+    const stat = fs.statSync(p);
+    if (stat.isDirectory()) {
+      const segs = p.split(/[\\/]/);
+      if (segs.some((s) => ["node_modules", ".next", "template", "test-results", "playwright-report"].includes(s))) return;
+      for (const e of fs.readdirSync(p)) walk(path.join(p, e));
+    } else if (/\.md$/.test(p)) {
+      files.push(p);
+    }
+  })(dir);
+  return files;
+}
+
+const files = collectMarkdown(root);
+
+const broken = [];
+const re = /\]\((\.{0,2}\/[^)#\s]+)(?:#[^)]*)?\)/g;
+
+for (const file of files) {
+  const txt = stripCodeFences(fs.readFileSync(file, "utf8"));
+  for (const m of txt.matchAll(re)) {
+    const target = path.resolve(path.dirname(file), m[1]);
+    if (!fs.existsSync(target)) broken.push(`  ${path.relative(root, file)} -> ${m[1]}`);
+  }
+}
+
+if (broken.length) {
+  console.error(`\n✖ ${broken.length} link(s) quebrado(s):\n${broken.join("\n")}\n`);
+  process.exit(1);
+}
+console.log(`✓ ${files.length} documentos, todos os links relativos resolvem.`);

package/SKILLS/create-feature/SKILL.md

@@ -0,0 +1,40 @@
+# 🧩 SKILL: create-feature
+
+> Cria um **vertical slice** novo em `src/features/<nome>/` já com domain, application,
+> infrastructure, container, queries e actions seguindo [SDD/ARCHITECTURE.md](../../ARCHITECTURE.md).
+
+## 🎯 Quando usar
+
+Toda vez que começa uma feature nova. Antes de escrever arquivo na mão, rode isto.
+
+## ▶️ Uso
+
+```bash
+node SDD/SKILLS/create-feature/create-feature.mjs billing
+```
+
+> Alternativa em bash: `bash SDD/SKILLS/create-feature.sh billing`
+
+## 📦 O que é criado
+
+```text
+src/features/billing/
+├── domain/
+│   ├── IBillingRepository.ts      # contrato (interface, sem dep externa)
+│   └── billing.schema.ts          # Zod na fronteira
+├── application/
+│   └── create-billing.usecase.ts  # regra de negócio pura
+├── infrastructure/                # (vazio — você implementa o repositório)
+├── container.ts                   # DI do slice
+├── queries.ts                     # entrada de leitura
+├── actions.ts                     # Server Action: auth → zod → authz → use case → cache
+└── ui/                            # componentes do domínio
+```
+
+## ✅ Checklist depois de rodar
+
+- [ ] Implementar `infrastructure/` (Prisma/API) satisfazendo a interface
+- [ ] Escrever teste unit do use case em `tests/unit/`
+- [ ] Registrar a task em `SDD/specs/PLAN.md` (`[-]`)
+- [ ] Criar a rota em `src/app/` **só roteando** para o slice
+- [ ] `npm run typecheck && npm run test:unit && npm run test:e2e`

package/SKILLS/create-feature/create-feature.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+/**
+ * SKILL: create-feature (versão multiplataforma, espelha create-feature.sh)
+ * Uso: node SDD/SKILLS/create-feature/create-feature.mjs <nome-do-slice>
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+const raw = process.argv[2];
+if (!raw) {
+  console.error("Uso: node create-feature.mjs <nome-do-slice>");
+  process.exit(1);
+}
+
+const name = raw.trim().toLowerCase().replace(/[^a-z0-9-]/g, "-");
+if (!name) {
+  console.error("✖ Nome inválido.");
+  process.exit(1);
+}
+
+const Pascal = name
+  .split(/[-_\s]+/)
+  .filter(Boolean)
+  .map((w) => w[0].toUpperCase() + w.slice(1))
+  .join("");
+
+const dir = path.resolve(process.cwd(), "src", "features", name);
+if (fs.existsSync(dir)) {
+  console.error(`✖ Já existe: ${dir}`);
+  process.exit(1);
+}
+
+for (const sub of ["domain", "application", "infrastructure", "ui"]) {
+  fs.mkdirSync(path.join(dir, sub), { recursive: true });
+}
+
+const write = (rel, body) => {
+  const p = path.join(dir, rel);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, body, "utf8");
+};
+
+write(`domain/I${Pascal}Repository.ts`, `export interface I${Pascal}Repository {
+  // TODO: contratos do domínio. Sem dependência externa.
+}
+`);
+
+write(`domain/${name}.schema.ts`, `import { z } from "zod";
+
+export const ${Pascal}Schema = z.object({
+  // TODO: campos + validações
+});
+
+export type ${Pascal}Input = z.infer<typeof ${Pascal}Schema>;
+`);
+
+write(`application/create-${name}.usecase.ts`, `import type { ${Pascal}Input } from "../domain/${name}.schema";
+import type { I${Pascal}Repository } from "../domain/I${Pascal}Repository";
+
+export class Create${Pascal}UseCase {
+  constructor(private readonly repo: I${Pascal}Repository) {}
+
+  async execute(input: ${Pascal}Input) {
+    // TODO: regra de negócio pura. Sem Next, sem Prisma.
+    throw new Error("not implemented");
+  }
+}
+`);
+
+write("container.ts", `import "server-only";
+import { Create${Pascal}UseCase } from "./application/create-${name}.usecase";
+import type { I${Pascal}Repository } from "./domain/I${Pascal}Repository";
+
+export function create${Pascal}UseCases(repo: I${Pascal}Repository) {
+  return {
+    create${Pascal}: new Create${Pascal}UseCase(repo),
+  };
+}
+`);
+
+write("queries.ts", `import "server-only";
+// TODO: leituras do domínio. Marque com 'use cache' quando fizer sentido.
+// Ver SDD/NEXT.md §4 e §6.
+
+export async function list${Pascal}() {
+  // TODO
+  throw new Error("not implemented");
+}
+`);
+
+write("actions.ts", `"use server";
+import { revalidatePath, updateTag } from "next/cache";
+import { z } from "zod";
+import { create${Pascal}UseCases } from "./container";
+import { ${Pascal}Schema } from "./domain/${name}.schema";
+
+export type ${Pascal}ActionState = {
+  ok: boolean;
+  errors?: Record<string, string[]>;
+  error?: string;
+};
+
+export async function create${Pascal}Action(
+  _prev: ${Pascal}ActionState,
+  formData: FormData,
+): Promise<${Pascal}ActionState> {
+  // 1. auth  2. zod  3. autorização  4. use case  5. cache
+  const parsed = ${Pascal}Schema.safeParse(Object.fromEntries(formData));
+  if (!parsed.success) {
+    return { ok: false, errors: z.flattenError(parsed.error).fieldErrors };
+  }
+
+  try {
+    const { create${Pascal} } = create${Pascal}UseCases(/* repo */ undefined as never);
+    await create${Pascal}.execute(parsed.data);
+    updateTag("${name}");
+    revalidatePath("/");
+    return { ok: true };
+  } catch {
+    return { ok: false, error: "Não foi possível concluir. Tente novamente." };
+  }
+}
+`);
+
+console.log(`✓ Slice criado em ${path.relative(process.cwd(), dir)}`);
+console.log("  1. Implemente o repositório em infrastructure/");
+console.log("  2. Escreva o teste em tests/unit/");
+console.log("  3. Registre a task em SDD/specs/PLAN.md");

package/SKILLS/create-feature.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+# SKILL: create-feature
+# Cria um novo vertical slice em src/features/<nome>/ com a estrutura padrão.
+set -euo pipefail
+
+NAME="${1:-}"
+if [ -z "$NAME" ]; then
+  echo "Uso: create-feature.sh <nome-do-slice>"
+  exit 1
+fi
+
+DIR="src/features/${NAME}"
+
+if [ -e "$DIR" ]; then
+  echo "✖ Já existe: $DIR"
+  exit 1
+fi
+
+mkdir -p "$DIR"/{domain,application,infrastructure,ui}
+
+cat > "$DIR/domain/I$(echo "$NAME" | sed 's/^\(.\)/\U\1/')Repository.ts" <<EOF
+export interface I$(echo "$NAME" | sed 's/^\(.\)/\U\1/')Repository {
+  // TODO: contratos do domínio. Sem dependência externa.
+}
+EOF
+
+cat > "$DIR/domain/${NAME}.schema.ts" <<EOF
+import { z } from "zod";
+
+export const ${NAME^}Schema = z.object({
+  // TODO: campos + validações
+});
+
+export type ${NAME^}Input = z.infer<typeof ${NAME^}Schema>;
+EOF
+
+cat > "$DIR/application/create-${NAME}.usecase.ts" <<EOF
+import type { ${NAME^}Input } from "../domain/${NAME}.schema";
+import type { I${NAME^}Repository } from "../domain/I${NAME^}Repository";
+
+export class Create${NAME^}UseCase {
+  constructor(private readonly repo: I${NAME^}Repository) {}
+
+  async execute(input: ${NAME^}Input) {
+    // TODO: regra de negócio pura. Sem Next, sem Prisma.
+    throw new Error("not implemented");
+  }
+}
+EOF
+
+cat > "$DIR/container.ts" <<EOF
+import "server-only";
+import { Create${NAME^}UseCase } from "./application/create-${NAME}.usecase";
+import type { I${NAME^}Repository } from "./domain/I${NAME^}Repository";
+
+export function create${NAME^}UseCases(repo: I${NAME^}Repository) {
+  return {
+    create${NAME^}: new Create${NAME^}UseCase(repo),
+  };
+}
+EOF
+
+cat > "$DIR/queries.ts" <<EOF
+import "server-only";
+// TODO: leituras do domínio. Marque com 'use cache' quando fizer sentido.
+// Ver SDD/NEXT.md §4 e §6.
+
+export async function list${NAME^}() {
+  // TODO
+  throw new Error("not implemented");
+}
+EOF
+
+cat > "$DIR/actions.ts" <<EOF
+"use server";
+import { revalidatePath, updateTag } from "next/cache";
+import { z } from "zod";
+import { create${NAME^}UseCases } from "./container";
+import { ${NAME^}Schema } from "./domain/${NAME}.schema";
+
+export type ${NAME^}ActionState = {
+  ok: boolean;
+  errors?: Record<string, string[]>;
+  error?: string;
+};
+
+export async function create${NAME^}Action(
+  _prev: ${NAME^}ActionState,
+  formData: FormData,
+): Promise<${NAME^}ActionState> {
+  // 1. auth  2. zod  3. autorização  4. use case  5. cache
+  const parsed = ${NAME^}Schema.safeParse(Object.fromEntries(formData));
+  if (!parsed.success) {
+    return { ok: false, errors: z.flattenError(parsed.error).fieldErrors };
+  }
+
+  try {
+    const { create${NAME^} } = create${NAME^}UseCases(/* repo */ undefined as never);
+    await create${NAME^}.execute(parsed.data);
+    updateTag("${NAME}");
+    revalidatePath("/");
+    return { ok: true };
+  } catch {
+    return { ok: false, error: "Não foi possível concluir. Tente novamente." };
+  }
+}
+EOF
+
+echo "✓ Slice criado em $DIR"
+echo "  1. Implemente o repositório em infrastructure/"
+echo "  2. Escreva o teste em tests/unit/"
+echo "  3. Registre a task em SDD/specs/PLAN.md"

package/SKILLS/install-submodule/SKILL.md

@@ -0,0 +1,42 @@
+# 🧩 SKILL: install-submodule
+
+> Instala o core de regras (`SDD/`) em um projeto **existente**, cria os atalhos da raiz
+> e deixa o agente pronto para trabalhar.
+
+## 🎯 Quando usar
+
+- Projeto já existe e você **não** quer o template Next.js.
+- Só quer as regras + atalhos, mantendo o código atual intocado.
+
+## ▶️ Uso
+
+```bash
+# Dentro do projeto alvo (ou passe o caminho como 1º argumento)
+node SDD/SKILLS/install-submodule/install-submodule.mjs
+
+# Instala em outro diretório
+node SDD/SKILLS/install-submodule/install-submodule.mjs ../meu-projeto
+
+# Sem git: cópia local
+node SDD/SKILLS/install-submodule/install-submodule.mjs . --copy
+```
+
+## 📦 O que faz
+
+1. `git submodule add <repo> SDD` (ou cópia com `--copy`)
+2. Cria atalhos na raiz: `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`,
+   `.windsurfrules`, `.github/copilot-instructions.md`, `.clinerules`
+   - tenta **symlink**; se o SO bloquear, grava um **stub** com o mesmo conteúdo da regra
+3. Preserva arquivos que já existam (não sobrescreve)
+
+## 🔄 Atualizar depois
+
+```bash
+git submodule update --remote --merge SDD
+git add SDD && git commit -m "chore(sdd): atualiza core"
+```
+
+## ⚠️ Pré-requisitos
+
+- Projeto precisa ser um repositório git (para o modo submodule).
+- `git` no PATH.