/deep-init

name: deep-init
description: >-
  Generate an agent-agnostic, two-tier context layer for a codebase — a lean,
  always-loaded CLAUDE.md plus a deep, on-demand .ai/docs/ layer (business rules,
  live DB schema + ORM drift, cross-component workflows, and the WHY: ADRs + a
  knowledge log), every claim grounded to file:line and verified to exist.
  Built for legacy / under-documented repos. Invoke for: "deep-init", "/deep-init",
  "generate AGENTS.md / agent context", "document this codebase for an agent",
  "update the agent docs", "lint doc staleness".
disable-model-invocation: true
allowed-tools:
  - Read
  - Glob
  - Grep
  - LS
  - Bash
  - Task
  - Write
  - Edit
  - AskUserQuestion

DeepInit v2.0

DeepInit gives a coding agent **grounded, verified truth about a codebase — and the real problems hiding in it** — every claim tied to a `file:line` and checked to exist. Generating the agent-context layer is the **mechanism**; the payload is trustworthy understanding plus a ranked, grounded list of actual issues (DB-vs-code drift, intent/decision contradictions, silent cross-component coupling, unenforced business rules, risk hotspots).

It emits a **two-tier** context layer:

• **Lean, always-loaded** — `CLAUDE.md` (root + nested), ~100–150 lines, ONLY the highest-value non-obvious facts. Claude Code auto-loads `CLAUDE.md` (it does NOT read `AGENTS.md` natively); **DeepInit owns this front door** — the grounded, verified replacement for `/init`. `AGENTS.md` is a **conditional cross-tool export** (Cursor/Copilot/Windsurf, or `--canonical=agents`).
• **Deep, on-demand** — `.ai/docs/` (per-component + six whole-system docs + decisions + DB + the issue ledger), comprehensive, uncapped.

Why two tiers: comprehensive *always-loaded* context **hurts** coding agents (it duplicates what they already read — ETH/LogicStar, Feb 2026); context helps only when minimal and non-obvious. So leanness applies to the loaded slice; depth is preserved on demand. **Quality is primary — leanness serves it and never trades against it.** Issues are **report-only** and **never enter the lean tier** — they live in the deep ledger, the dashboard, and SARIF.

Pipeline (the stages, each in `references/`)

Detect → Plan → Extract → [Review*] → (ADR/KL) → Filter → Redact → Verify → Emit
                                   └─ Issue pass (report-only): detect → C-RAISE → verify → baseline-diff ─┘

| Stage | Reference | Role | |-------|-----------|------| | Detect (C1) | `detection.md` | layered ladder, architecture, component registry, git-intel (+ change-coupling), DB detect, cost | | Plan (C2) | `detection.md` (cost preflight) + `extraction.md` (dependency ordering) | toposort/waves (`extraction.md`), cost preflight (base + issue-pass terms) | | Extract (C3) | `extraction.md` (+ `database.md`) | per-component 11-section analysis; live schema + ORM drift | | Review* | `review.md` | `thorough`=2 cycles + an adaptive 3rd iff the cycle-2 quality gate still fails; `fast`=0 (mode-gated); R1.5 back-to-code validate | | ADR/KL | `adr.md` | the WHY — decisions + knowledge log (IF-4's input) | | **Issue detect** | `issues.md` | IF-1…IF-5 + the shipped roadmap families IF-8 / IF-3b / IF-7 (c-slice + a-commission semantic) / IF-6 / IF-10 (IF-9 deferred); issue-record schema; baseline match-key primitive | | **Issue raise (C-RAISE)** | `issue-filter.md` | linter-suppress · root-cause dedup · severity · polarity-flip suppression · forced R1.5 · verify routing | | Filter (C4) | `filter.md` | non-obviousness — decides lean vs deep PLACEMENT (never deletes; issues never lean — R9) | | Redact (C5) | `redaction.md` | secret/PII gate (unconditional; covers the issue ledger + dashboard blob) | | Verify (C6) | `verification.md` | citation-existence + plausibility (mandatory; routes issue verification) | | Emit (C7) | `generation.md` | two-tier output, manifest (schema 5 — +IF-5 risk metrics + processing timing), changelog, hashes, SARIF, multi-agent projections | | **Dashboard** | `dashboard.md` | self-contained `.ai/dashboard.html` over grounded truth + issue ledger | | **Viewer** | `viewer.md` | self-contained `.ai/docs-viewer.html` — a browsable READER over the generated docs (the human-facing first impression; a docs reader, not a graph) | | **Report** | `report.md` | unified self-contained `.ai/report.html` — MERGES Docs (the viewer) + Insights (the dashboard) into one co-branded artifact (ADR-019); deterministic `tools/build_report.py`; vendored libs inlined, not CDN; supersedes Dashboard + Viewer | | Update (C8) | `update.md` | `--update` (DP-1 skip + issue lifecycle) / `--lint` (0 tokens) | | **Triggers** | `triggers.md` | notify / session-start / opt-in auto-update; the `deepinit_status.py` keystone + `setup-hooks` | | **Heal** | `heal.md` | governed upkeep over update/lint; DEFAULT preview; hardcoded report-only floor | | Cross-cutting | `horizontal.md` | six whole-system docs (always re-run on `--update`) | | (all stages) | `global-rules.md` | never-fabricate, ID system (+ `ISS-`), provenance, DB security, R9 placement |

**Always read `references/global-rules.md` first.** Read each stage's reference before entering it (progressive disclosure).

Commands

deep-init                              # full run — strong defaults (deep + adaptive review + issues/dashboard/SARIF on)
deep-init fast                         # skip review (0 cycles) + token-saving heuristics (= /deep-init:fast)
deep-init --update [--review]          # incremental: changed components + DP-1 propagation (+ issue lifecycle diff)
deep-init --lint                       # staleness audit, ZERO LLM tokens (+ candidate resolved/critical issues)
deep-init --status                     # deterministic staleness check (0 tokens, no LLM) — the deepinit_status.py keystone (triggers.md)
deep-init --horizontal | --horizontal-only
deep-init --decisions-only             # extract/refresh ADRs + KL only (~5 min)
deep-init --update-adr [--recheck=adr,rules,i