contextdevkit 1.8.0

package/docs/CUSTOMIZING.md

@@ -0,0 +1,211 @@
+# Customizing ContextDevKit
+
+The kit works out of the box, but a few tweaks make it fit your project well.
+
+## 1. Tune which paths matter (do this first)
+
+`contextkit/config.json` → `ledger` drives drift detection. Defaults are generic
+(`src/`, `lib/`, `app/`, `packages/`, …). Adjust per stack:
+
+```jsonc
+{
+  "ledger": {
+    "important":    ["app/", "tests/", "pyproject.toml"],   // edits here → drift nudge
+    "irrelevant":   ["node_modules/", "dist/", "__pycache__/"], // never tracked
+    "registration": ["contextkit/memory/SESSIONS.md", "docs/CHANGELOG.md"] // counts as "registered"
+  }
+}
+```
+
+Examples: Python → add `app/`, `tests/`; Go → `cmd/`, `internal/`; Rust →
+`src/`, `Cargo.toml`. Use `/context-config set ledger.important '["app/","tests/"]'`
+or edit the file directly. Arrays **replace** the defaults.
+
+## 2. Protect high-risk paths (Level 5)
+
+`l5.highRiskPaths` is empty by default — the gate protects nothing until you fill
+it. Add the files whose blast radius is largest:
+
+```jsonc
+{ "l5": { "highRiskPaths": [
+  "db/schema.sql", "src/contracts/", "src/auth/", "openapi.yaml"
+] } }
+```
+
+Now editing any of those is blocked until `/simulate-impact` records a covering
+analysis.
+
+## 3. Grow your own squad of sub-agents (Level 4)
+
+Sub-agents are `.claude/agents/*.md` files with frontmatter. Copy
+`_TEMPLATE.md` and make the agent **sharp and narrow** — its `description` is how
+Claude decides when to route to it, so name the concrete files/dirs it owns.
+
+```markdown
+---
+name: api-specialist
+description: Use when the task touches src/api/ routes, request validation, or the service layer.
+# Optional: declare MCP servers the agent expects (ADR-0019)
+# mcpServers:
+#   - name: postgres
+#     rationale: needs read access to the production schema
+#     optional: true
+---
+You are api-specialist... (mental model, invariants, anti-patterns, self-audit)
+```
+
+Good agents do one domain extremely well and delegate the rest. The shipped
+`architect`, `code-reviewer`, `context-keeper`, `seo-specialist`,
+`landing-architect` are stack-agnostic references — read them as style guides
+before writing your own. Add domain agents (frontend, db, security, …) as your
+codebase grows.
+
+The kit ships **28 sub-agents** across 7 squads — see
+[`docs/SQUADS/design-team.md`](SQUADS/design-team.md) for the UI/UX/SEO/landing
+specialists and [`docs/SQUADS/agent-forge.md`](SQUADS/agent-forge.md) for the
+L6+ agent-forge squad.
+
+Tip: keep a short frontmatter `description` + a focused body. A vague
+"helps with everything" agent defeats routing.
+
+## 4. Add a slash command
+
+Slash commands are `.claude/commands/**/*.md` — frontmatter `description` (+ optional
+`argument-hint`) and a prompt body. `$ARGUMENTS` interpolates what the user typed.
+Drop a new file in and it's available immediately.
+
+Claude Code resolves commands by **file basename**, not path — so
+`/my-command` finds `my-command.md` whether you place it at the root or under
+`audit/my-command.md`. Use the existing packs (`audit/`, `pipeline/`, `qa/`,
+`vcs/`, `forge/`, `setup/`) as a taxonomy reference. See
+[`templates/claude/commands/README.md`](../templates/claude/commands/README.md)
+for the full taxonomy.
+
+## 5. Write your project's constitution
+
+The installed `CLAUDE.md` ships a generic coding constitution (file-size limit,
+SRP, naming, language policy, self-audit). **Edit it** to match your project:
+fill in the immutable rules (and link the ADR that justifies each), set the
+language policy, adjust the line limit. Keep it short — push detail into ADRs.
+
+## 6. Add a provider adapter (review, media)
+
+The kit ships two pluggable adapter surfaces. Both follow the same five-point
+contract: **no SDK dependency, refuse-on-missing-creds, typed errors,
+refuse-on-content-policy (where applicable), per-process cost cap (media only)**.
+
+### Review providers (`contextkit/runtime/providers/review/`)
+
+Add an adapter for GitLab / Bitbucket / Gitea by creating a new `.mjs` file that
+shells out to the user-installed CLI:
+
+```js
+// contextkit/runtime/providers/review/glab.mjs
+import { spawnSync } from 'node:child_process';
+import { ProviderError } from './_adapter.mjs';
+
+export const id = 'glab';
+export const cliBinary = 'glab';
+export const detectsRemote = (url) => /gitlab\.com[:/]/.test(url);
+
+function runGlab(args, { stdin } = {}) {
+  const r = spawnSync('glab', args, { input: stdin, encoding: 'utf-8' });
+  if (r.error?.code === 'ENOENT') throw new ProviderError('CLI_MISSING', 'glab CLI not installed');
+  if (r.status !== 0) throw new ProviderError('REMOTE_REJECTED', r.stderr);
+  return r.stdout;
+}
+
+export async function createPullRequest({ title, body, baseBranch }) { … }
+export async function listOpenReviewComments({ prNumber }) { … }
+export async function postReviewComment({ prNumber, body }) { … }
+```
+
+`detect.mjs` automatically discovers the file and routes by `origin` URL.
+Authority: [ADR-0021](../contextkit/memory/decisions/0021-provider-strategy-review-qa.md).
+
+### Media providers (`contextkit/runtime/providers/media/`)
+
+Add an adapter for Runway / Luma / Midjourney following the contract in
+`_adapter.mjs`:
+
+```js
+// contextkit/runtime/providers/media/my-provider.mjs
+import { MediaProviderError, MEDIA_ERROR_CODES, assertCredentials, noteCostOrThrow } from './_adapter.mjs';
+
+export const id = 'my-provider';
+export const kind = 'image';                       // or 'video'
+export const envVar = 'MY_PROVIDER_API_KEY';
+export const requiredEnv = ['MY_PROVIDER_API_KEY'];
+
+export async function generate({ prompt, outPath, options }) {
+  assertCredentials(requiredEnv);                  // refuse before network call
+  noteCostOrThrow(0.05);                            // per-process cost tally
+  // …node:fetch → write outPath…
+  return { outPath, durationMs, costEstimateUsd, providerRequestId };
+}
+```
+
+Authority: [ADR-0024](../contextkit/memory/decisions/0024-media-generation-veo-nano-banana.md).
+
+## 7. Credentials flow (`contextkit/.env.example`)
+
+The kit ships an `.env.example` template at the installed `contextkit/` root with
+commented credentials for `/media-gen` and a tour of the other `CONTEXTDEVKIT_*`
+env vars. Setup:
+
+1. Copy `contextkit/.env.example` to `contextkit/.env`.
+2. Fill in the keys you want (`GOOGLE_AI_API_KEY` for Nano Banana + Veo).
+3. (Optional) set `CONTEXTDEVKIT_MEDIA_MAX_USD=5.00` to cap per-process spend.
+4. Run scripts via Node 20.6+'s built-in env-file loader:
+
+```bash
+node --env-file=contextkit/.env contextkit/tools/scripts/media-gen.mjs image \
+  --prompt "..." --out hero.png
+```
+
+Or copy the values into your project's existing dotenv setup (Astro / Next /
+Nuxt / Vite all already read `.env` from the project root).
+
+**The kit never writes secrets.** `contextkit/.env.example` is the only template;
+you fill in `contextkit/.env` and it stays out of git via the standard `.env`
+gitignore convention.
+
+## 8. Rebrand the platform folder
+
+To rename `contextkit/` (e.g. to `devtools/`), change `PLATFORM_DIR` in
+`contextkit/runtime/config/paths.mjs`, rename the folder, and update the hook
+commands in `.claude/settings.json` (`node devtools/runtime/hooks/...`). Nothing
+else references the literal name.
+
+## 9. Updating the engine later
+
+Re-run the installer over the project. It overwrites only the engine and slash
+commands; it never touches your memory, config overrides, or `CLAUDE.md`:
+
+```bash
+node /path/to/contextdevkit/install.mjs --target . --level <N> --yes
+```
+
+Or, even simpler:
+
+```bash
+npx contextdevkit@latest --target . --update
+```
+
+This refreshes engine + slash commands + hook wiring for your **current** level.
+It **never** touches `CLAUDE.md`, `contextkit/config.json`, memory (ADRs/sessions/
+roadmap), pipeline tasks, scoped module `CLAUDE.md`, or your `contextkit/.env`.
+
+## Uninstall
+
+Delete the `contextkit/` folder and remove the ContextDevKit entries (the ones whose
+command contains `contextkit/runtime/hooks`) from `.claude/settings.json`. Your
+memory under `contextkit/memory/` is just markdown — keep a copy if you want the
+history.
+
+Or use the installer:
+
+```bash
+node /path/to/contextdevkit/install.mjs --target . --uninstall          # keeps memory + CLAUDE.md
+node /path/to/contextdevkit/install.mjs --target . --uninstall --purge  # also removes the engine
+```

package/docs/LEVELS.md

@@ -0,0 +1,151 @@
+# Levels
+
+ContextDevKit activates progressively. The active level lives in
+`contextkit/config.json` → `level` and drives both which hooks are wired in
+`.claude/settings.json` and which behaviours the hooks enable at runtime.
+
+Change level with `/context-level <n>` or
+`node contextkit/tools/scripts/context-level.mjs <n>` (then restart Claude Code so it
+reloads hooks).
+
+---
+
+## L1 — Memory
+
+**Goal:** never lose the *why*. The minimum that makes sessions continuous.
+
+- `SessionStart` hook injects boot context: latest session, CHANGELOG
+  `[Unreleased]`, git divergence vs upstream.
+- `/log-session` writes one markdown file per session under
+  `contextkit/memory/sessions/`.
+- `/new-adr` records architecture decisions (immutable once accepted).
+- `/state`, `/close-version`, `/context-refresh`.
+
+**Use when:** any project. This is the floor.
+
+## L2 — Ledger
+
+**Goal:** stop work from silently going unrecorded.
+
+- `PostToolUse` hook records every edit in a per-session ledger
+  (`.claude/.sessions/<sid>.json`).
+- `Stop` hook **blocks** the session from ending if ≥ 2 important files changed
+  and the session wasn't registered — nudging you to `/log-session`.
+- The boot context now also reports **drift** from earlier sessions that ended
+  without registering.
+
+**Use when:** you want the kit to actively keep memory honest (most projects).
+
+## L3 — Multi-session
+
+**Goal:** run several Claude sessions in parallel — same machine or different
+machines/devs — **without one silently overwriting another**.
+
+- `/claim` / `/release` reserve paths; the `PostToolUse` hook warns when you edit
+  a path another active session claimed.
+- **Concurrency guard** (`PreToolUse`): before you write a file, it warns if
+  another active session edited that exact file recently, or if it changed on
+  disk since you last wrote it — so you re-read and merge instead of clobbering.
+  (Claude Code's own `Edit` already refuses to edit a file changed since you read
+  it; the guard adds cross-session awareness and covers full-file `Write`s.)
+- **Boot awareness**: SessionStart lists other active branches — local worktrees
+  and recent **remote** feature branches (author + age) — so parallel work on
+  other machines is visible immediately.
+- **pre-push conflict check**: before a push lands, it fetches the upstream
+  (`l3.mainBranch`, default `main`) and **blocks** if your branch has a real
+  textual conflict with what was pushed there (warns on auto-mergeable overlap).
+  This is the cross-machine guarantee the local ledger can't give. Bypass:
+  `CONTEXT_ALLOW_CONFLICT_PUSH=1`.
+- `/worktree-new` creates an isolated git worktree (its own ledger).
+- `SESSIONS.md` / `WORKSPACE.md` are auto-generated; `pre-commit` regenerates
+  them; `commit-msg` enforces Conventional Commits (`[skip-cc]` to bypass).
+
+**Use when:** more than one session/developer, or you use worktrees.
+
+## L4 — Squads
+
+**Goal:** specialized review and design instead of one generalist.
+
+Sub-agents land in `.claude/agents/`, organised into **squads** (each squad has
+a router specialist + a roster). The kit ships **28 agents across 7 squads**:
+
+- **devteam** — `architect` (cross-cutting design), `code-reviewer`
+  (constitution audit), `context-keeper` (platform + memory), `test-engineer`.
+- **qa-team** — `qa-orchestrator` (router + sign-off) with `qa-unit` /
+  `qa-integration` / `qa-fuzzer` / `qa-perf` / `qa-e2e` specialists.
+- **design-team** — `ui-designer`, `ux-designer`, `accessibility`,
+  **`seo-specialist`** (SEO + AISO), **`landing-architect`** (high-conversion
+  landing pages with anti-Lovable posture).
+- **security-team** — `security`, `code-security`, `infra-security`.
+- **compliance-team** — `privacy-lgpd`, `governance-officer`.
+- **ops-team** — `devops`.
+- **agent-forge** *(activated at L6)* — `forge-orchestrator`, `model-router`,
+  `prompt-engineer`, `tool-designer`, `eval-designer`, `packager`,
+  `rag-designer`, `agent-architect`.
+
+Routing is automatic: Claude picks an agent by matching the user's intent to
+the `description` frontmatter. QA commands (`/test-plan`, `/scaffold-tests`,
+`/qa-signoff`) go through `qa-orchestrator`; `/landing-page` invokes
+`landing-architect`, which delegates indexability to `seo-specialist`.
+
+Use `_TEMPLATE.md` (or `/squad`) to grow your own domain agents. See
+[`docs/SQUADS/design-team.md`](SQUADS/design-team.md) and
+[`docs/SQUADS/agent-forge.md`](SQUADS/agent-forge.md).
+
+**Use when:** the codebase is big enough that domain expertise pays off.
+
+## L5 — Proactive
+
+**Goal:** convert "architecture before syntax" into executable governance.
+
+- `PreToolUse` gate: editing a path in `l5.highRiskPaths` is **blocked** until
+  you run `/simulate-impact` (which writes a Blast Radius Report and authorizes
+  the edit). Trivial edits can record an explicit auditable bypass.
+- `/tech-debt-sweep` audits the codebase against your `CLAUDE.md` constitution.
+- Auto-distill: after enough sessions, the Stop hook suggests `/distill-sessions`
+  to propose refinements to `CLAUDE.md`.
+
+**Use when:** the project has high-blast-radius areas (schema, public contracts,
+auth) you want protected from casual edits.
+
+---
+
+## L6 — Autonomy & Insight
+
+**Goal:** make the platform *act and learn*, not just remember and enforce. A
+**capability tier** — no new hook, commands on top of the L5 gates.
+
+- `/ship` — orchestrated pipeline (design → implement → review → test → record).
+- `/retro` — turns recurring drift/debt into governance (rules + ADRs).
+- `/context-stats` — telemetry (drift rate, cadence, ADR/agent counts).
+
+**Use when:** the practice is established and you want orchestration + insight.
+
+---
+
+## L7 — Ecosystem & Scale
+
+**Goal:** operate beyond a single repo and close the quality/insight loops. Also a
+**capability tier** — no new hook.
+
+- `/fleet` — one control plane over many repos (portfolio stats, cross-repo audit).
+- `/tune-agents` — propose outcome-driven refinements to agent briefings.
+- `/visual-test` — scaffold a browser-driven visual / screenshot harness.
+- `/playbook`, `/token-report`, `/security-setup` + pluggable detectors & stack presets.
+
+**Use when:** an existing/active project that should use the full toolkit from day one.
+
+---
+
+## Where to start
+
+The kit is **not** timid by default:
+
+- **AI-assisted coding a NEW / empty project from zero?** Start at **L3** — memory + drift +
+  multi-session + git hooks. A solid base, no ceremony.
+- **A project that already has code?** Start at **L7** — use everything. It's not
+  intrusive: the L5 `simulate-gate` stays inert until you set `l5.highRiskPaths`; the
+  rest is advisory. (See [ADR-0009].)
+
+`/context-level <n>` moves up or down any time. The installer picks **L3** (greenfield) or
+**L7** (existing) for you, based on whether the folder already has code.