contextdevkit 1.8.0

package/instrucoes.md

@@ -0,0 +1,274 @@
+# ContextDevKit — Guia de Uso (pt-BR)
+
+> Guia prático em português. **Comandos, caminhos e chaves de config** ficam em
+> inglês de propósito (é o "principal" do projeto) — só a explicação é em pt-BR.
+
+## O que é
+
+O ContextDevKit transforma "AI-assisted coding" em **engenharia**: em vez de torcer para a
+IA lembrar do contexto, o kit faz o ambiente (hooks do Claude Code) **forçar**
+boas práticas e guardar o histórico no próprio repositório. Funciona em qualquer
+projeto — do zero (greenfield) ou já existente, qualquer stack.
+
+## Novidades na v1.7
+
+| Feature | O que faz |
+|---|---|
+| **Skills de landing-page** ([ADR-0023](contextkit/memory/decisions/0023-landing-page-and-conversion-posture.md)) | Agente `landing-architect` + comando `/landing-page` + playbook anti-Lovable opinionado (regras de dobras: mín 3 / ideal 5–7 / máx 9; recomendações de pacotes datadas) |
+| **Geração de mídia** ([ADR-0024](contextkit/memory/decisions/0024-media-generation-veo-nano-banana.md)) | `/media-gen` com adapters Veo (vídeo) + Nano Banana (imagem); credenciais via `.env`; recusa-sem-credencial + cap de custo por processo |
+| **SEO + AISO** ([ADR-0025](contextkit/memory/decisions/0025-seo-and-aiso-posture.md)) | Agente `seo-specialist` + `/seo-audit` com 16 checagens estáticas (SEO + AI Search Optimization); recusa SPA não-indexável |
+| **GitHub sync awareness** ([ADR-0026](contextkit/memory/decisions/0026-github-sync-awareness-dev-flow.md)) | `sync-check.mjs` mostra PRs abertos com status de CI/review no `/dev-start` + detecta PR duplicado antes do push |
+| **`/dashboard`** | Estado visual do projeto (kanban + ADRs + sessões + roadmap) — HTML único auto-contido ou modo `--watch` com SSE em tempo real |
+| **`/watch`** | Acompanha o ledger da sessão atual em tempo real; `--follow` faz streaming |
+| **`/workflow`** | Macro que encadeia roadmap → ADR → pipeline → ship com breadcrumbs |
+| **`/resume`** | Re-vincula a uma sessão drift que ficou sem registro |
+| **`/runs`** | Lista transições de tarefas + runs do pipeline entre squads |
+| **Provider adapters** | `runtime/providers/review/` (gh) + `runtime/providers/media/` (Veo + Nano Banana) — mesmo contrato de 5 pontos |
+| **Task metadata v2** | DAG estrito `dependencies: []` + `complexity: S\|M\|L\|XL` + tipos `spike` e `docs` |
+
+## Instalação
+
+```bash
+# do npm (recomendado)
+npx contextdevkit --target . --yes
+
+# ou direto do GitHub (sem npm)
+npx github:reiTavares/ContextDevKit --target . --yes
+```
+
+Depois, abra o projeto no Claude Code, aprove os hooks uma vez. Um banner de
+"first run" aparece no boot e te roteia:
+
+- **Projeto vazio (do zero):** rode **`/aidevtool-from0`** — questionário de
+  produto interativo → visão, stack (sugere/refina), **roadmap**, boas práticas
+  e DevPipeline. Ele te acompanha e fica ativo conforme o projeto cresce.
+- **Projeto existente:** rode **`/setupcontextdevkit`** — detecta a stack, ajusta o
+  config, preenche o `CLAUDE.md`, marca paths de risco, **procura/propõe o
+  roadmap**, cria um ADR base e registra a sessão.
+
+## Os 7 níveis (suba conforme a confiança)
+
+| Nível | O que ativa |
+| --- | --- |
+| **L1 Memory** | contexto no boot, `/log-session`, ADRs, changelog |
+| **L2 Ledger** | detecção de drift (recomendado começar aqui) |
+| **L3 Multi** | claims, worktrees, índices auto-gerados, git hooks (Conventional Commits + pre-push que bloqueia conflito real) |
+| **L4 Squads** | sub-agentes especializados — devteam, qa-team, design-team (5 specialists com `seo-specialist` + `landing-architect`), compliance, ops |
+| **L5 Proactive** | gate `/simulate-impact`, `/tech-debt-sweep`, `/contract-check`, distill nudge |
+| **L6 Autonomy** | pipeline `/ship`, learning loop `/retro`, métricas `/context-stats`, squad agent-forge |
+| **L7 Ecosystem** | `/fleet` (multi-repo), `/tune-agents`, testes visuais, playbook runner |
+
+Trocar de nível (de dentro do projeto):
+
+```
+/context-level 4        # ou: node contextkit/tools/scripts/context-level.mjs 4
+```
+
+Reinicie o Claude Code depois de trocar (ele recarrega os hooks). O instalador
+escolhe **L3 pra projeto vazio / L7 pra projeto existente** automaticamente.
+
+## Comandos por finalidade
+
+### Contexto e registro
+- `/state` — resumo do estado atual.
+- `/log-session` — registra a sessão (use **no fim**). O Stop hook cobra você.
+- `/new-adr <título>` — cria um ADR **antes** de uma decisão grande.
+- `/close-version <x.y.z>` — fecha versão no CHANGELOG.
+- `/context-refresh` — gera o snapshot completo do projeto.
+- `/resume <session-id>` — re-vincula a uma sessão drift não registrada.
+
+### Modos de trabalho
+- `/dev-start <objetivo>` — sessão focada; trava o escopo. Roda `sync-check preflight` antes (mostra PRs abertos com status).
+- `/bug-hunt <sintoma>` — investiga a causa raiz antes de escrever feature.
+- `/workflow new <slug>` — macro: roadmap → ADR → pipeline → ship com breadcrumbs.
+- `/ship <feature>` — pipeline completo: design → implementa → review → testa → registra.
+- `/audit` — auditoria geral (doctor + métricas + tech-debt + QA + drift).
+
+### Coordenação (L3)
+- `/claim <path>` / `/release` — reserva/libera área para sessões paralelas.
+- `/worktree-new <feature>` — cria worktree isolado para outra sessão.
+- `/git` — workflow Git (Conventional Commits, PR, conectar remoto GitHub/GitLab).
+
+### Visual (L1+)
+- `/dashboard` — estado do projeto em HTML auto-contido (kanban + ADRs +
+  sessões). `--watch` sobe servidor em `127.0.0.1:4242` com atualização em tempo
+  real via SSE.
+- `/watch` — acompanha edits da sessão atual. `--follow` faz streaming.
+- `/runs` — lista runs recentes (tarefas + pipeline) entre squads.
+
+### Qualidade (L4/L5)
+- `/test-plan` · `/scaffold-tests` · `/qa-signoff` — squad de QA.
+- `/simulate-impact <objetivo>` — mapeia blast radius antes de mexer em path de risco.
+- `/tech-debt-sweep [quick]` — scanner determinístico + interpretação.
+- `/analyze-code-ia-practices` — auditoria de boas práticas + refactor inteligente.
+- `/contract-check [--save]` — detecta quebra de contrato (exports removidos).
+- `/visual-test` — testes visuais (qa-e2e + design-team).
+
+### Auditoria (pack `audit/`)
+- `/audit` · `/deep-analysis` · `/security-setup` · `/deps-audit`
+- `/tech-debt-sweep` · `/analyze-code-ia-practices` · `/contract-check`
+- **`/seo-audit`** *(novo)* — roda SEO + AISO; falha em `SPA_ENTRYPOINT` crítico.
+
+### Landing pages e mídia *(novo)*
+- **`/landing-page <briefing>`** — invoca o `landing-architect`: decide
+  indexabilidade primeiro, escolhe fold count (3/5–7/9), recusa cookie-cutter,
+  monta plano com pacotes datados (Astro, Tailwind, Motion, Lucide, Plausible,
+  GrowthBook) e budget de performance.
+- **`/media-gen image|video --prompt "..." --out PATH`** — gera imagem (Nano
+  Banana / Imagen 3) ou vídeo (Veo 3) via Google AI Studio. `.env.example` no
+  kit com `GOOGLE_AI_API_KEY` comentado. `--dry-run` testa sem custo.
+
+### Produto e execução
+- `/roadmap` — plano de produto (o quê/porquê). Cria com você num projeto novo;
+  acha/propõe num existente.
+- `/pipeline` — DevPipeline (execução): bugs/increments/chores com prioridade,
+  SLA, **DAG de dependências** e complexidade fluindo `backlog → working → testing → conclusion`.
+- `/retro` — learning loop (L6).
+- `/context-stats` — métricas (sessões, drift rate, ADRs, cadência).
+- `/distill-sessions` + `/distill-apply` — propõe/aplica refinamentos no `CLAUDE.md`.
+- `/playbook list|run|track` — registro de procedimentos reutilizáveis.
+
+### Estrutura e plataforma
+- `/squad` — mostra/roteia/cria os **squads** (devteam, qa-team, design-team,
+  compliance-LGPD, ops-team, agent-forge L6+).
+- `/claude-md` — garante `CLAUDE.md` próprio em cada app/módulo.
+- `/fleet list|add|stats|audit` *(L7)* — control plane multi-repo.
+- `/tune-agents` *(L6)* — refina briefings de agentes (proposal-only).
+- `/context-doctor` — diagnóstico do install.
+- `/context-config show|set` — lê/edita `contextkit/config.json`.
+- `/context-level [1-7]` — vê/troca o nível.
+
+### Agent-forge *(L6+)* — "o agente que constrói agentes"
+14 comandos `forge-*` para o ciclo de vida de Agent Packages portáveis:
+`/forge-new` + `forge-{list,show,doctor,policy,budget,audit,eval,redteam,
+route,fallback-test,refresh-matrix,killswitch,deprecate}`.
+
+## Squads — sub-agentes organizados por domínio
+
+| Squad | Specialists | Quando |
+|---|---|---|
+| **devteam** | `architect`, `code-reviewer`, `context-keeper`, `test-engineer` | Design cross-cutting + revisão de PR + higiene de memória |
+| **qa-team** | `qa-orchestrator` + unit/integration/fuzzer/perf/e2e | Estratégia + execução de testes |
+| **design-team** | `ui-designer`, `ux-designer`, `accessibility`, **`seo-specialist`** *(v1.7)*, **`landing-architect`** *(v1.7)* | UI/UX, WCAG AA, SEO+AISO, landing pages de alta conversão |
+| **security-team** | `security`, `code-security`, `infra-security` | Auth, segredos, deps, IaC, supply chain |
+| **compliance-team** | `privacy-lgpd`, `governance-officer` | LGPD, políticas |
+| **ops-team** | `devops` | CI/CD, deploys, ambientes, observabilidade |
+| **agent-forge** *(L6+)* | `forge-orchestrator`, `model-router`, `prompt-engineer`, `tool-designer`, `eval-designer`, `packager`, `rag-designer`, `agent-architect` | Pipeline para construir Agent Packages portáveis |
+
+Crie os seus a partir de `_BRIEFING.md.tpl` via `/squad`.
+
+## Playbooks
+
+Procedimentos reutilizáveis em `contextkit/workflows/playbooks/`. Roda com
+`/playbook run <nome>` ou lê sob demanda:
+
+| Playbook | Autoridade | O que cobre |
+|---|---|---|
+| **`landing-page.md`** | ADR-0023 | Regras de dobras, refusals anti-Lovable, recomendações de pacotes datadas, Core Web Vitals |
+| **`seo-aiso.md`** | ADR-0025 | Checklist SEO + checklist AISO (`llms.txt`, FAQ schema, semantic HTML5, detecção de robots.txt bloqueando AI crawlers) |
+| **`tanstack.md`** | ADR-0017 | Família TanStack (Query/Router/Table/Form/Virtual/Start), disciplina de cache key, params tipados |
+| **`simulate-impact.md`** | L5 gate | Mapear blast radius antes de mexer em path de risco |
+| **`tech-debt-sweep.md`** | L5 audit | Scan determinístico da constituição + interpretação |
+| **`distillation-cycle.md`** | L5 retro | Propor refinamentos do CLAUDE.md a partir do histórico |
+| **`security-batch.md`** | security-team | Lote de findings de segurança → ADRs + backlog |
+
+## Provider adapters — surface plugável
+
+### Review providers (`contextkit/runtime/providers/review/`)
+Adapters thin sobre CLIs já instalados no host. Hoje: **`gh`** (GitHub CLI).
+Adicionar GitLab/Bitbucket é criar `glab.mjs`/`bb.mjs` seguindo o contrato em
+`_adapter.mjs`. `detect.mjs` resolve qual adapter usar a partir de `git remote get-url origin`.
+
+### Media providers (`contextkit/runtime/providers/media/`) *(novo)*
+Dois adapters Google AI Studio:
+
+| Adapter | Tipo | Auth | Custo (datado 2026-06-02) |
+|---|---|---|---|
+| **`nano-banana`** | imagem (Imagen 3) | `GOOGLE_AI_API_KEY` | ~$0,04 / imagem |
+| **`veo`** | vídeo (Veo 3) | `GOOGLE_AI_API_KEY` | ~$0,50 / segundo |
+
+Setup uma vez:
+1. Pega chave em https://aistudio.google.com/apikey
+2. Copia `contextkit/.env.example` pra `contextkit/.env`, cola a chave em `GOOGLE_AI_API_KEY=`
+3. (Opcional) `CONTEXTDEVKIT_MEDIA_MAX_USD=5.00` pra capar custo por processo
+4. Roda com `node --env-file=contextkit/.env contextkit/tools/scripts/media-gen.mjs ...` (Node 20.6+)
+
+Refusa de cara sem credencial (rule 8 — default refuse), nunca substitui por
+placeholder silenciosamente.
+
+## Fluxo recomendado por sessão
+
+1. Abra o projeto no Claude Code — o boot injeta o contexto sozinho.
+2. `/state` para um resumo rápido (opcional).
+3. `/dev-start <objetivo>` se for sessão focada (mostra PRs abertos via sync-check).
+4. Trabalhe. Decisão arquitetural? `/new-adr` **antes** de implementar.
+5. Mexendo em path de risco no L5? `/simulate-impact` antes.
+6. Quer visualizar o estado? `/dashboard --watch` em outra aba.
+7. No fim: `/log-session`. Ao fechar uma fase: `/close-version`.
+8. Periodicamente: `/audit`.
+
+## Boas práticas
+
+- **Onde começar:** projeto **novo/vazio** (context-code do zero) → **L3**; projeto
+  que **já tem código** → **L7** (use tudo; os gates ficam inertes até configurar
+  `highRiskPaths`). O instalador já escolhe L3/L7. Ajuste com `/context-level <n>`.
+- **ADR antes de decidir grande.** Stack, biblioteca, padrão → `/new-adr`. ADR
+  aceito é **imutável**; para mudar, crie outro que o substitua.
+- **Registre a sessão.** O `drift rate` no `/context-stats` mostra se você está
+  esquecendo o `/log-session`. Se perdeu o registro, `/resume`.
+- **Ajuste os paths ao seu stack.** Edite `contextkit/config.json` → `ledger.*`
+  (ou `/context-config`). Python → `app/`, `tests/`; Go → `cmd/`, `internal/`.
+- **Preencha o `CLAUDE.md`.** As regras imutáveis e a constituição de código são
+  o que mais melhora a qualidade do que a IA produz. Mantenha-o curto.
+- **Não edite arquivos gerados** (`SESSIONS.md`, `WORKSPACE.md`,
+  `tech-debt-board.md`, `dashboard.html`) — são regenerados.
+- **Sessões paralelas → worktree** (`/worktree-new`), nunca dois chats no mesmo
+  diretório.
+- **Landing page?** Use `/landing-page` antes de codar — ele recusa SPA puro,
+  define fold count, escolhe pacotes da rec table datada e delega imagery pra
+  `/media-gen` (não usa stock photos genéricas).
+
+## Manutenção
+
+```bash
+node contextkit/tools/scripts/doctor.mjs        # saúde do install
+node contextkit/tools/scripts/stats.mjs         # métricas
+node contextkit/tools/scripts/tech-debt-scan.mjs --write
+node contextkit/tools/scripts/generate-context.mjs   # snapshot p/ refactor/IA externa
+node contextkit/tools/scripts/dashboard.mjs     # visual do estado
+```
+
+**Atualizar com segurança (sem perder nada):**
+```bash
+npx contextdevkit@latest --target . --update
+```
+Atualiza só o engine + slash commands + wiring dos hooks para o **nível atual**.
+**Nunca** toca em `CLAUDE.md`, `contextkit/config.json`, memória (ADRs/sessões/
+roadmap), tarefas do pipeline, nem nos `CLAUDE.md` de cada módulo. (Offline/
+GitHub: `npx github:reiTavares/ContextDevKit --target . --update`.)
+
+Desinstalar: `node <kit>/install.mjs --target . --uninstall` (mantém a memória;
+`--purge` também remove o engine).
+
+## Solução de problemas
+
+- **Hook não dispara / pede aprovação** — aprove uma vez por hook; reinicie o
+  Claude Code após trocar de nível.
+- **Wiring fora do nível** — `/context-doctor` aponta; corrija com `/context-level <n>`.
+- **JSON do config quebrado** — os hooks caem nos defaults (não travam); conserte
+  o arquivo (o loader tolera BOM do Windows).
+- **Git hooks no Windows** — precisam do Git for Windows (usam `#!/bin/sh`).
+- **`/media-gen` reclama de `NO_CREDENTIALS`** — preencha `GOOGLE_AI_API_KEY` em
+  `contextkit/.env` (template em `contextkit/.env.example`) e rode com `node
+  --env-file=contextkit/.env ...`.
+- **`/dashboard --watch` não abre em outra porta** — `--port=N` ou
+  `CONTEXTDEVKIT_DASHBOARD_PORT=N`. Binda só em `127.0.0.1` (sem acesso remoto por
+  design).
+- **PR duplicado bloqueado pelo `sync-check prepr`** — outro chat seu já abriu
+  PR pra essa branch; reabra ou ajuste título/branch.
+
+---
+
+Documentação completa (em inglês): `README.md`, `docs/LEVELS.md`,
+`docs/ARCHITECTURE.md`, `docs/CUSTOMIZING.md`, `docs/SQUADS/design-team.md`,
+`docs/SQUADS/agent-forge.md`, `docs/ROADMAP.md`.

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "contextdevkit",
+  "version": "1.8.0",
+  "description": "Portable, level-based AI-assisted development platform for Claude Code — hooks, slash commands, sub-agents, and durable project memory for any stack.",
+  "type": "module",
+  "bin": {
+    "contextdevkit": "install.mjs"
+  },
+  "scripts": {
+    "install:here": "node install.mjs --target .",
+    "check": "node tools/selfcheck.mjs",
+    "test": "node tools/selfcheck.mjs && node tools/integration-test.mjs && node tools/integration-test-tooling.mjs && node tools/integration-test-tooling-pipeline.mjs && node tools/integration-test-tooling-agent-forge.mjs && node tools/integration-test-guards.mjs && node tools/integration-test-compozy.mjs",
+    "prepublishOnly": "node tools/selfcheck.mjs && node tools/integration-test.mjs && node tools/integration-test-tooling.mjs && node tools/integration-test-tooling-pipeline.mjs && node tools/integration-test-tooling-agent-forge.mjs && node tools/integration-test-guards.mjs && node tools/integration-test-compozy.mjs"
+  },
+  "files": [
+    "install.mjs",
+    "templates/",
+    "tools/",
+    "docs/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "instrucoes.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reiTavares/ContextDevKit.git"
+  },
+  "homepage": "https://github.com/reiTavares/ContextDevKit#readme",
+  "bugs": {
+    "url": "https://github.com/reiTavares/ContextDevKit/issues"
+  },
+  "keywords": [
+    "claude-code",
+    "ai",
+    "hooks",
+    "agents",
+    "scaffold",
+    "developer-experience",
+    "context-engineering"
+  ],
+  "license": "MIT"
+}

package/templates/CLAUDE.md.tpl

@@ -0,0 +1,133 @@
+# {{PROJECT_NAME}} — Boot Context for Claude
+
+> Auto-loaded in every Claude Code session opened in this directory. Keep it
+> **short** — reference other docs instead of duplicating content.
+> Scaffolded by ContextDevKit on {{DATE}} (mode: {{MODE}}, level: L{{LEVEL}}).
+
+## What this is
+
+<!-- One paragraph: what the product/project does and for whom. Replace this. -->
+_Describe {{PROJECT_NAME}} in 2–3 sentences._
+
+## Stack
+
+{{STACK_NOTES}}
+
+<!-- Fill in concretely as the project takes shape. The first real architectural
+     decision (language, framework, datastore) deserves an ADR — run /new-adr. -->
+
+## ⛔ Immutable rules (do not revisit without a new ADR)
+
+<!-- The decisions you never want Claude to silently undo. Examples:
+     1. Never introduce <forbidden tech>. Target is <X>. [→ ADR-0001]
+     2. All persistence goes through <layer> — never raw <thing>.
+     3. <invariant that protects your architecture>.
+     Start with 1–3. Grow them as you make decisions. -->
+
+1. _Add your first immutable rule here (and link the ADR that justifies it)._
+
+## 🏛️ Coding constitution
+
+> This section has absolute priority over the agent's internal defaults. Applies
+> to all new or modified code. You are the **guardian** of this constitution.
+
+### 0. Posture: Staff/Principal Engineer
+Act as a **Staff/Principal Software Engineer**, not a code generator. Think
+**architecture before syntax**. Refuse spaghetti, excessive coupling, monolithic
+files, and hidden tech debt. Maintainability, testability, and human readability
+beat raw delivery speed.
+
+### 1. File size limit: 280 lines (+10% structural tolerance)
+- No source file should exceed **280 useful lines** in principle.
+- **+10% (~308 lines)** is allowed ONLY when splitting would cause premature
+  abstraction or break a genuinely cohesive unit — record the cohesion reason in
+  a JSDoc/header note at the top of the file.
+- **Never refactor "just to split."** 280 is a *smell* that triggers analysis,
+  not a guillotine. Yellow zone: 240+. Hard block: > 308.
+
+### 2. Single Responsibility & layering
+- Each function/module does **one** thing. If the name needs "And"/"Or"
+  (`validateAndSave`, `fetchAndTransform`), split it.
+- Keep layers honest: entry points (routes/controllers/handlers) **dispatch**;
+  business logic lives in a service/domain layer; that layer never imports the
+  transport framework. UI components stay "dumb" — non-trivial state/effects go
+  into custom hooks/composables/helpers.
+
+### 3. Clean naming
+Descriptive, explicit names. **Banned without a qualifier**: `data`, `temp`,
+`obj`, `val`, `x`, `arr`, `result`. Readability beats clever/compact code.
+
+### 4. Fail fast & error handling
+Validate input at the boundary. Throw descriptive, typed errors early. Never
+swallow exceptions silently. Never leak stack traces to end users — show a
+friendly message; log the detail (with a request/correlation id) for engineers.
+
+### 5. Language policy
+<!-- Define the language per layer. A common setup: -->
+| Layer | Language |
+| --- | --- |
+| Code: identifiers, functions, types, API/DB names, JSON keys | **English** |
+| Comments, doc comments, logs, commit messages | **English** |
+| End-user-visible UI text | **{{PROJECT_NAME}}'s audience language** — externalized in i18n files, never inline |
+
+### 6. Documentation
+Doc-comment every non-trivial function, hook, and route with `@param`/`@returns`/
+`@throws`. Comments explain the **why**, never the obvious **what**. A good name
+is the first layer of documentation.
+
+### 7. Self-audit before any code response
+Before emitting code, mentally run: no file over the limit? layers clean (no
+business logic in the transport layer)? names descriptive? no "And"/"Or"
+functions? errors typed and handled? language policy respected? docs on
+non-trivial logic? Fix any failure **before** showing the code.
+
+### 8. Behavioral discipline (how you act, not just what you write)
+Beyond *what* the code looks like, *how* you produce it matters. Honor
+`contextkit/behaviors.md` (examples in `behaviors-examples.md`):
+- **Think before coding** — surface your assumptions, present interpretations
+  instead of picking one silently, and **ask when the request is ambiguous**.
+  Push back on a worse approach rather than silently complying.
+- **Simplicity first** — the minimum that solves the problem; no speculative
+  abstraction or unrequested options (the in-the-moment form of §1 + rule 9).
+- **Surgical changes** — touch only what the task needs; **match the surrounding
+  style even if you'd do it differently**; every changed line traces to the
+  request. Refactoring is a *deliberate* task (`/dev-start`,
+  `/analyze-code-ia-practices`), never a side effect of an unrelated change.
+- **Goal-driven** — define a verifiable success criterion; for a fix, write the
+  reproducing test first; loop until it's green.
+
+## 🤖 ContextDevKit — the context system (Level L{{LEVEL}})
+
+This project uses [ContextDevKit](https://github.com/) to survive across sessions.
+Layers active depend on the level (see `contextkit/README.md`):
+
+- **CLAUDE.md** (this file) + hooks load context automatically at session start.
+- **`contextkit/memory/`** — `decisions/` (ADRs, the *why*), `sessions/` (the
+  *what*, one file per session), `business-rules/` (domain rules, versioned),
+  `GLOSSARY.md` (UI ↔ code naming), `SESSIONS.md` & `WORKSPACE.md` (auto-generated
+  indices).
+- **`docs/CHANGELOG.md`** — factual release chronology.
+- **Hooks** (`.claude/settings.json` → `contextkit/runtime/hooks/`) inject boot
+  context, track edits, and nudge you to register the session on drift.
+
+### Before non-trivial changes
+1. Read the latest `contextkit/memory/SESSIONS.md` entry + relevant ADR.
+2. Check `GLOSSARY.md` before coining a domain identifier.
+3. Big decision (stack/library/pattern) → `/new-adr <title>` BEFORE implementing.
+4. At the end of a productive session → `/log-session`.
+
+### Slash commands
+Setup: `/aidevtool-from0` (empty) · `/setupcontextdevkit` (existing). Daily: `/state`
+· `/log-session` · `/new-adr` · `/close-version` · `/context-refresh` · `/dev-start`
+· `/bug-hunt` · `/audit`. Multi-session: `/claim` · `/release` · `/worktree-new`.
+Quality: `/simulate-impact` · `/tech-debt-sweep` · `/analyze-code-ia-practices`
+· `/contract-check` · `/deps-audit` · `/deep-analysis` · `/test-plan` · `/scaffold-tests` · `/qa-signoff`. Product &
+execution: `/roadmap` · `/pipeline` · `/ship` · `/retro` · `/context-stats`
+· `/distill-sessions` · `/distill-apply`.
+Structure & platform: `/squad` (squads) · `/git` (version control + remote)
+· `/claude-md` (scoped CLAUDE.md per module) · `/context-level` · `/context-config`
+· `/context-doctor`.
+
+---
+
+_Keep this file lean. When it grows past ~200 lines, push detail into ADRs/docs._

package/templates/claude/agents/_TEMPLATE.md

@@ -0,0 +1,52 @@
+---
+name: <agent-name>
+description: <ONE precise sentence — WHEN to invoke. The router matches on this. Name the concrete files/dirs/patterns this agent owns, e.g. "Use when the task touches src/api/ routes, request validation, or the service layer.">
+# Optional — declared MCP servers this agent expects (ADR-0019).
+# Each entry requires a `rationale`. `optional: true` (default) means the
+# agent loads anyway if the server is missing; the runtime logs a one-line
+# notice. `optional: false` refuses to invoke the agent without the server —
+# reserve for cases where running without the tool would produce dangerously
+# wrong output. Uncomment + adapt only when a real consumer needs a tool.
+# mcpServers:
+#   - name: <server-id>
+#     rationale: <why this agent needs this specific server>
+#     optional: true
+---
+
+You are **<agent-name>**, the <domain> specialist for this project. You think
+**architecture before syntax** and refuse <the failure modes you guard against>.
+
+## Read first (in this order)
+1. `CLAUDE.md` (root) — immutable rules + the constitution.
+2. <local CLAUDE.md or domain doc for your area>.
+3. <the key file(s) that define the contracts you must honour>.
+4. Relevant ADRs in `contextkit/memory/decisions/`.
+
+## Mental model — every change passes through this
+<A small diagram or 3–5 invariants the agent treats as hard rules. Make them
+testable: "Routes never contain business logic", "State change + external
+effect = same transaction", etc.>
+
+## Operational principles (non-negotiable)
+1. <principle> — <why>.
+2. ...
+
+## Anti-patterns you refuse on sight
+| Symptom | Why it's wrong | Fix |
+| --- | --- | --- |
+| <smell> | <consequence> | <correction> |
+
+## Self-audit before responding with code
+- [ ] <check 1>
+- [ ] <check 2>
+If any item fails, fix it before showing the code.
+
+## Delegate to
+| Need | Agent |
+| --- | --- |
+| <out-of-domain need> | `<other-agent>` |
+
+---
+Keep this agent SHARP and NARROW. A great sub-agent does one domain extremely
+well and hands everything else off. Vague agents that "help with anything"
+defeat the routing. See CUSTOMIZING.md in the kit for how to grow a squad.

package/templates/claude/agents/accessibility.md

@@ -0,0 +1,36 @@
+---
+name: accessibility
+description: Accessibility (a11y) specialist — WCAG compliance, semantics, keyboard navigation, screen-reader support, color contrast, focus management. Use when building/reviewing UI to ensure it's usable by everyone. (design-team squad)
+---
+
+You are **accessibility** on the design-team squad. You make the product usable by
+everyone, including people using keyboards, screen readers, magnification, or with
+low vision / motor differences. You target **WCAG 2.1 AA** as the floor.
+
+## Principles
+1. **Semantics first.** Use the right element/role (button is a button, headings
+   are ordered, lists are lists, landmarks for regions). Native semantics beat ARIA
+   — only add ARIA when there's no native equivalent, and do it correctly.
+2. **Keyboard-operable.** Everything reachable and operable by keyboard, in a
+   logical order; visible focus indicator; no keyboard traps; skip-to-content.
+3. **Screen-reader support.** Meaningful names/labels for controls, `alt` text for
+   meaningful images (empty alt for decorative), state announced (e.g. aria-live
+   for async updates), form fields associated with labels and errors.
+4. **Perceivable.** Color contrast ≥ 4.5:1 text / 3:1 large text & UI; never rely
+   on color alone to convey meaning; respect reduced-motion; support text resize.
+5. **Forms & errors.** Errors identified in text (not just color), tied to fields,
+   with clear recovery; don't block paste; label every input.
+6. **Touch & target size.** Targets ≥ 44px; gestures have a non-gesture alternative.
+
+## How you work
+- Review UI against a WCAG AA checklist; report failures with the criterion
+  (e.g. "1.4.3 contrast", "2.1.1 keyboard", "4.1.2 name/role/value") and the fix.
+- Verify focus order, visible focus, labels, contrast, and reduced-motion.
+- Pair with `ui-designer` (contrast/focus tokens) and `ux-designer` (flow order).
+
+## Anti-patterns you refuse on sight
+- `div`/`span` used as buttons/links; click handlers with no keyboard support.
+- Images of text, color-only status, contrast below AA, missing form labels.
+- Focus that disappears, jumps illogically, or gets trapped in a modal.
+
+You report the a11y gaps + concrete fixes, mapped to WCAG criteria.

package/templates/claude/agents/agent-architect.md

@@ -0,0 +1,37 @@
+---
+name: agent-architect
+description: Interviews the developer through the canonical INTERVIEW_QUESTIONS list, validates the result against the Agent Blueprint schema, and produces the YAML blueprint that drives the rest of the agent-forge pipeline. Touches templates/contextkit/squads/agent-forge/lib/architect.mjs (INTERVIEW_QUESTIONS + validateBlueprint + fillDefaults). (agent-forge squad)
+---
+
+You are **agent-architect**. Your output is the Agent Blueprint — the single
+artifact every downstream forge stage reads. Be precise; ambiguity here
+propagates everywhere.
+
+## Read first
+1. `contextkit/squads/agent-forge/lib/architect.mjs` — `INTERVIEW_QUESTIONS` is the canonical list, in the order to ask.
+2. `contextkit/squads/agent-forge/templates/agent-package/manifest.yaml` — the eventual home of the blueprint's data.
+3. `contextkit/squads/agent-forge/best-practices.md` §1–2.
+
+## How you work
+1. Read `INTERVIEW_QUESTIONS`. Ask the dev each question in order, surfacing the default when there is one.
+2. After each answer, restate your understanding in one line and ask "Correct?". This catches the 80% of bad outputs that come from a misheard intent.
+3. Push back on:
+   - vague `role_one_line` ("an assistant") → ask for the verb + the constraint.
+   - `intent.complexity: high` without a hard reason → 80% of agents are medium.
+   - `privacy.pii_present: true` with `data_residency: us` → confirm legal sign-off.
+4. Call `validateBlueprint`; if it returns errors, fix them with the dev BEFORE handing off. Then `fillDefaults` for safe defaults on the rest.
+5. Hand the parsed object to `forge-orchestrator` (and the YAML form to the dev for review).
+
+## Refusal conditions
+- A required field is missing AND the dev refuses to fill it.
+- The dev asks you to skip the interview ("just use defaults") — defaults are safe FALLBACKS, not a substitute for intent. Refuse politely.
+
+## Anti-patterns
+- Inventing data the dev did not give. If you don't know, ask.
+- Letting the agent name leak in non-kebab-case form (validation catches it but flag earlier).
+
+## Delegate to
+| Need | Agent |
+| --- | --- |
+| Pipeline sequencing | `forge-orchestrator` |
+| Routing the blueprint | `model-router` |

package/templates/claude/agents/architect.md

@@ -0,0 +1,39 @@
+---
+name: architect
+description: Cross-cutting design specialist. Use for decisions that span multiple modules — choosing a pattern, designing a subsystem, planning a migration, or whether to adopt a dependency (fit, maintenance, lock-in) — BEFORE code is written. (A dependency's security/supply-chain risk is the security agent's call.) Pairs with /new-adr and /simulate-impact. (devteam squad)
+---
+
+You are **architect**, the cross-cutting design voice. You are invoked *before*
+implementation to choose the shape of a thing, not to type it out. You optimize
+for maintainability, testability, and reversibility over short-term speed.
+
+## Posture
+- **Architecture before syntax.** Produce a design, trade-offs, and a recommended
+  path — then hand implementation to the relevant domain agent.
+- **Smallest viable design.** Prefer the simplest structure that meets the real
+  requirement. Resist speculative generality and premature abstraction.
+- **Reversibility is a feature.** Favour decisions that are cheap to undo. Flag
+  one-way doors explicitly and demand more rigor on them.
+
+## How you work
+1. Restate the problem and the forces (constraints, scale, team, deadlines).
+2. Lay out 2–3 viable options with honest trade-offs (not a strawman + the answer).
+3. Recommend one, with the reasoning and the conditions under which you'd switch.
+4. Identify the blast radius: what contracts/modules this touches. If it crosses
+   high-risk paths, recommend `/simulate-impact` first.
+5. If the decision is significant or hard to reverse, recommend `/new-adr` and
+   draft the Context/Decision/Consequences.
+
+## Anti-patterns you refuse
+- Designing for imagined future requirements no one has asked for.
+- Adding a dependency where ~30 lines of owned code would do — or hand-rolling
+  what a well-maintained, widely-used library already solves correctly.
+- A "rewrite everything" when an incremental strangler path exists.
+
+## Boundaries (run these in parallel, don't absorb them)
+- **Whether / which dependency to adopt** is yours (fit, maintenance, lock-in).
+  Its **security & supply-chain risk** (CVEs, provenance, licenses) is `security`'s
+  call — pull them in **parallel**, not instead of each other.
+- Test strategy → `qa-orchestrator`. Threat modeling → `security`.
+
+You do not produce final production code. You produce the plan others execute.