/init-deep

name: init-deep
description: "Initializes a hierarchical AGENTS.md knowledge base for a project. Use when a repo needs its structure, commands, and conventions documented for agents."

/init-deep

Generate hierarchical AGENTS.md files: root + complexity-scored subdirectories, produced by a size-formula-driven dag map-reduce (`quick` scanners -> `unspecified-high` writers) so the main session's context stays flat at any repo size.

Usage

/init-deep                      # Update mode: modify existing + create new where warranted
/init-deep --create-new         # Read existing → remove all → regenerate from scratch
/init-deep --max-depth=2        # Limit directory depth (default: 3)

---

Workflow (High-Level)

1. **Size & route** (main session) - ONE eval cell measures the repo and computes the node formula. 2. **Map** (dag) - `quick` scanner nodes extract per-chunk facts into bounded file reports. 3. **Reduce** (dag) - `unspecified-high` writer nodes own disjoint subtrees: score, write AGENTS.md files, emit digests. 4. **Root & verify** (dag) - one node writes root AGENTS.md from digests only; one node verifies every file. 5. **Snapshot & mode** (main session) - snapshot contract unchanged.

<critical> **THE ALWAYS-REDUCE RULE.** The main session NEVER reads chunk reports or raw node outputs - only the verify node's verdict and, when a repair needs it, one digest. Context protection is structural (bounded fan-in at every stage), never a runtime "how much context is left" guess.

`todo` init the five phases; `start`/`done` each transition in real time. </critical>

---

Phase 1: Size & Route

Measure and compute in ONE eval cell - code, not mental arithmetic:

# Measure (tracked files minus vendored/generated: node_modules, .git, dist,
# build, out, vendor, target, coverage, lockfiles, minified and binary files)
S        = total source bytes after exclusions
per_dir  = source bytes per directory            # bin-packing input
depth    = max directory depth                   # respect --max-depth (default 3)
existing = every AGENTS.md / CLAUDE.md path      # read the ROOT one now

# Formula
CHUNK   = 400 * 1024          # ~100k tokens of source; a quick worker's usable window
                              # is ~150k over its fallback chain - leave room for its
                              # prompt and report
N_quick = ceil(S / CHUNK)     # bin-pack WHOLE directories into chunks; a directory
                              # larger than one chunk splits at its children
N_high  = ceil(N_quick / 12)  # one reducer absorbs ~12 reports (~60k tokens) and
                              # still has room to spot-check real code

Route:

• **N_quick < 4** -> inline path below; a dag costs more than it saves.
• **N_quick > `task.dag.max_nodes_per_run` (default 64)** -> raise the knob in omo config, or run one chained dag per top-level directory (multi-run composition, `mass-ulw` skill).
• **Otherwise** -> dag path: emit `CHUNKS = [{id, dirs, bytes}]`, assign each writer a directory SUBTREE (disjoint - no two writers own the same directory), and `mkdir -p .omo/init-deep/reports .omo/init-deep/digests`.

`--create-new`: read every existing AGENTS.md FIRST (still-true facts survive as scanner input), then delete all, then regenerate.

Inline path (N_quick < 4)

Small repo - skip the dag. Fire 2-4 parallel `explore` agents (structure, entry points, conventions, anti-patterns), for example:

task(subagent_type="explore", run_in_background=true, prompt="Project structure: map real layout via ast-grep structural search (sg/ast_grep MCP) + rg --files -> REPORT deviations from standard patterns")

Run the LSP/ast-grep code map yourself (`lsp_symbols` outlines + workspace inventory, `lsp_find_references` on top exports, ast-grep import/call shapes; when neither resolves, mark centrality unmeasured). Then score with the matrix below and write every file per the templates yourself. Phase 5 applies unchanged.

---

Phase 2: Map Wave - `quick` Scanners (dag)

Build and start the run in one eval JS cell with the dag SDK (`OMO_DAG_SDK_ROOT`); wave doctrine, the node prompt contract, and the failure playbook come from the `mass-ulw` skill's `references/planning.md`. One scanner node per chunk, `category: "quick"`, no `load_skills` - scanners stay lean and their prompt is a rigid numbered extraction template. Quick workers extract; they never judge and never write AGENTS.md:

TASK: Extract knowledge-base facts for chunk <id> (<dirs>) of <repo-root>.
Steps, in order:
1. Inventory each directory in scope: file count, LOC, languages, entry files.
2. Public exports/symbols other code imports - lsp_symbols and ast-grep
   import/call shapes, never file-name guesses.
3. Conventions that DEVIATE from stack defaults (configs, naming, layout).
4. Anti-patterns: DO NOT / NEVER / ALWAYS / DEPRECATED comments, forbidden patterns.
5. Hotspots: files >500 lines, high-reference symbols, complexity concentrations.
6. Build/test/dev commands touching these dirs.
DELIVERABLE: EXACTLY ONE file `.omo/init-deep/reports/<id>.md`, <=5k tokens, sections
`# CHUNK <id>` / `## INVENTORY` / `## EXPORTS` / `## CONVENTIONS` / `## ANTI-PATTERNS`
/ `## HOTSPOTS` / `## COMMANDS`; an empty section says `none`.
SCOPE: read only <dirs>; write only your report file. If an AGENTS.md exists in scope,
quote its still-true claims into the matching sections.
VERIFY: the report file exists and every section header is present.
STOP WHEN: the report is written and verified.

---

Phase 3: Reduce Wave - `unspecified-high` Writers (same dag)

One writer node per subtree, `dependsOn` its chunks' scanner ids, `load_skills: ["init-deep"]` - every writer carries this file, so the scoring matrix and templates below ARE its instructions:

TASK: Own subtree <path>: produce its AGENTS.md files for the repo knowledge base.
Steps, in order:
1. Read your chunk reports: .omo/init-deep/reports/<ids>.md. Reports ar