init-deep

## Claude Code Harness Tool Compatibility This skill may include examples copied from the OpenCode or Codex harness. In Claude Code, do not call OpenCode/Codex-only tools such as `task(...)`, `call_omo_agent(...)`, `spawn_agent(...)`, `background_output(...)`, `wait_agent(...)`, `team_*(...)`, `send_message(...)`, `followup_task(...)`, or `close_agent(...)` literally. Translate those examples to Claude Code native tools: | OpenCode / Codex example | Claude Code tool to use | | --- | --- | | `task(subagent_type="explore", ...)` / `call_omo_agent(...)` / `spawn_agent(agent_type="explorer", ...)` | the `Task` tool (spawn a subagent of the matching type) | | `task(subagent_type="plan"/"oracle", ...)` / `spawn_agent(agent_type="plan"/"reviewer", ...)` | the `Task` tool with the planner/reviewer subagent, or the `Skill` tool | | `task(category="...", ...)` | the `Task` tool (general-purpose subagent) or run the work inline | | `background_output(...)` / `wait_agent(...)` | await the subagent's return value / the system completion notification | | `team_*(...)` / `send_message`/`followup_task`/`close_agent` | run multiple `Task` subagents and synthesize their results | When translating `load_skills=[...]`, invoke the requested skills with the `Skill` tool or pass their names in the spawned subagent's prompt. If a code block below conflicts with this section, this section wins. # /init-deep Generate hierarchical AGENTS.md files. Root + complexity-scored subdirectories. ## 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. **Discovery + Analysis** (concurrent) - Fire background explore agents immediately - Main session: bash structure + LSP codemap + read existing AGENTS.md 2. **Score & Decide** - Determine AGENTS.md locations from merged findings 3. **Generate** - Root first, then subdirs in parallel 4. **Review** - Deduplicate, trim, validate <critical> **TodoWrite ALL phases. Mark in_progress → completed in real-time.** ``` TodoWrite([ { id: "discovery", content: "Fire explore agents + LSP codemap + read existing", status: "pending", priority: "high" }, { id: "scoring", content: "Score directories, determine locations", status: "pending", priority: "high" }, { id: "generate", content: "Generate AGENTS.md files (root + subdirs)", status: "pending", priority: "high" }, { id: "review", content: "Deduplicate, validate, trim", status: "pending", priority: "medium" } ]) ``` </critical> --- ## Phase 1: Discovery + Analysis (Concurrent) **Mark "discovery" as in_progress.** ### Fire Background Explore Agents IMMEDIATELY Don't wait-these run async while main session works. ``` // Fire all at once, collect results later task(subagent_type="explore", load_skills=[], description="Explore project structure", run_in_background=true, prompt="Project structure: PREDICT standard patterns for detected language → REPORT deviations only") task(subagent_type="explore", load_skills=[], description="Find entry points", run_in_background=true, prompt="Entry points: FIND main files → REPORT non-standard organization") task(subagent_type="explore", load_skills=[], description="Find conventions", run_in_background=true, prompt="Conventions: FIND config files (.eslintrc, pyproject.toml, .editorconfig) → REPORT project-specific rules") task(subagent_type="explore", load_skills=[], description="Find anti-patterns", run_in_background=true, prompt="Anti-patterns: FIND 'DO NOT', 'NEVER', 'ALWAYS', 'DEPRECATED' comments → LIST forbidden patterns") task(subagent_type="explore", load_skills=[], description="Explore build/CI", run_in_background=true, prompt="Build/CI: FIND .github/workflows, Makefile → REPORT non-standard patterns") task(subagent_type="explore", load_skills=[], description="Find test patterns", run_in_background=true, prompt="Test patterns: FIND test configs, test structure → REPORT unique conventions") ``` <dynamic-agents> **DYNAMIC AGENT SPAWNING**: After bash analysis, spawn ADDITIONAL explore agents based on project scale: | Factor | Threshold | Additional Agents | |--------|-----------|-------------------| | **Total files** | >100 | +1 per 100 files | | **Total lines** | >10k | +1 per 10k lines | | **Directory depth** | ≥4 | +2 for deep exploration | | **Large files (>500 lines)** | >10 files | +1 for complexity hotspots | | **Monorepo** | detected | +1 per package/workspace | | **Multiple languages** | >1 | +1 per language | ```bash # Measure project scale first total_files=$(find . -type f -not -path '*/node_modules/*' -not -path '*/.git/*' | wc -l) total_lines=$(find . -type f \\( -name "*.ts" -o -name "*.py" -o -name "*.go" \\) -not -path '*/node_modules/*' -exec wc -l {} + 2>/dev/null | tail -1 | awk '{print $1}') large_files=$(find . -type f \\( -name "*.ts" -o -name "*.py" \\) -not -path '*/node_modules/*' -exec wc -l {} + 2>/dev/null | awk '$1 > 500 {count++} END {print count+0}') max_depth=$(find . -type d -not -path '*/node_modules/*' -not -path '*/.git/*' | awk -F/ '{print NF}' | sort -rn | head -1) ``` Example spawning: ``` // 500 files, 50k lines, depth 6, 15 large files → spawn 5+5+2+1 = 13 additional agents task(subagent_type="explore", load_skills=[], description="Analyze large files", run_in_background=true, prompt="Large file analysis: FIND files >500 lines, REPORT complexity hotspots") task(subagent_type="explore", load_skills=[], description="Explore deep modules", run_in_background=true, prompt="Deep modules at depth 4+: FIND hidden patterns, internal conventions") task(subagent_type="explore", load_skills=[], description="Find shared utilities", run_in_background=true, prompt="Cross-cutting concerns: FIND shared utilities across directories") // ... more based on calculation ``` </dynamic-agents> ### Main Session: Concurrent Analysis **While background agents run**, main session does: #### 1. Bash Structural Analysis ```bash # Directory depth + file counts find . -type d -not -path '*/\\.*' -not -path '*/node_modules/*' -not -path '*/venv/*' -not -path '*/dist/*' -not -path '*/build/*' | awk -F/ '{print NF-1}' | sort -n | uniq -c # Files per directory (top 30) find . -type f -not -path '*/\\.*' -not -path '*/node_modules/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -30 # Code concentration by extension find . -type f \\( -name "*.py" -o -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.go" -o -name "*.rs" \\) -not -path '*/node_modules/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -20 # Existing AGENTS.md / CLAUDE.md find . -type f \\( -name "AGENTS.md" -o -name "CLAUDE.md" \\) -not -path '*/node_modules/*' 2>/dev/null ``` #### 2. Read Existing AGENTS.md ``` For each existing file found: Read(filePath=file) Extract: key insights, conventions, anti-patterns Store in EXISTING_AGENTS map ``` If `--create-new`: Read all existing first (preserve context) → then delete all → regenerate. #### 3. LSP Codemap (if available) ``` LspServers() # Check availability # Entry points (parallel) LspDocumentSymbols(filePath="src/index.ts") LspDocumentSymbols(filePath="main.py") # Key symbols (parallel) LspWorkspaceSymbols(filePath=".", query="class") LspWorkspaceSymbols(filePath=".", query="interface") LspWorkspaceSymbols(filePath=".", query="function") # Centrality for top exports LspFindReferences(filePath="...", line=X, character=Y) ``` **LSP Fallback**: If unavailable, rely on explore agents + AST-grep. ### Collect Background Results ``` // After main session analysis done, collect all task results for each background task ID (`bg_...`): background_output(task_id="bg_...") ``` **Merge: bash + LSP + existing + explore findings. Mark "discovery" as completed.** --- ## Phase 2: Scoring & Location Decision **Mark "scoring" as in_progress.** ### Scoring Matrix | Factor | Weight | High Threshold | Source | |--------|--------|----------------|--------| | File count | 3x | >20 | bash | | Subdir count | 2x | >5 | bash | | Code ratio | 2x | >70% | bash | | Unique patterns | 1x | Has own config | explore | | Module boundary | 2x | Has index.ts/__init__.py | bash | | Symbol density | 2x | >30 symbols | LSP | | Export count | 2x | >10 exports | LSP | | Reference centrality | 3x | >20 refs | LSP | ### Decision Rules | Score | Action | |-------|--------| | **Root (.)** | ALWAYS create | | **>15** | Create AGENTS.md | | **8-15** | Create if distinct domain | | **<8** | Skip (parent covers) | ### Output ``` AGENTS_LOCATIONS = [ { path: ".", type: "root" }, { path: "src/hooks", score: 18, reason: "high complexity" }, { path: "src/api", score: 12, reason: "distinct domain" } ] ``` **Mark "scoring" as completed.** --- ## Phase 3: Generate AGENTS.md **Mark "generate" as in_progress.** <critical> **File Writing Rule**: If AGENTS.md already exists at the target path → use `Edit` tool. If it does NOT exist → use `Write` tool. NEVER use Write to overwrite an existing file. ALWAYS check existence first via `Read` or discovery results. </critical> ### Root AGENTS.md (Full Treatment) ```markdown # PROJECT KNOWLEDGE BASE **Generated:** {TIMESTAMP} **Commit:** {SHORT_SHA} **Branch:** {BRANCH} ## OVERVIEW {1-2 sentences: what + core stack} ## STRUCTURE ``` {root}/