init-deep

name	init-deep
description	Generate hierarchical AGENTS.md files throughout a project. Fires parallel explore agents, scores directories by complexity, and produces root + subdirectory documentation.

/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 + 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

Create todos for ALL phases. Mark in_progress then completed in real-time.

---

Phase 1: Discovery + Analysis (Concurrent)

Fire Background Explore Agents IMMEDIATELY

Don't wait - these run async while main session works.

// Fire all at once, collect results later
explore: "Project structure: PREDICT standard patterns for detected language, REPORT deviations only"
explore: "Entry points: FIND main files, REPORT non-standard organization"
explore: "Conventions: FIND config files (.eslintrc, pyproject.toml, .editorconfig), REPORT project-specific rules"
explore: "Anti-patterns: FIND 'DO NOT', 'NEVER', 'ALWAYS', 'DEPRECATED' comments, LIST forbidden patterns"
explore: "Build/CI: FIND .github/workflows, Makefile, REPORT non-standard patterns"
explore: "Test patterns: FIND test configs, test structure, REPORT unique conventions"

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

Main Session: Concurrent Analysis

While background agents run, main session does:

1. Bash Structural Analysis

   # Directory depth + file counts
   find . -type d -not -path '*/\.*' -not -path '*/node_modules/*' | 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, extract key insights, conventions, anti-patterns.

If --create-new: Read all existing first (preserve context), then delete all, regenerate.

Collect Background Results

After main session analysis done, collect all task results and merge: bash + existing + explore findings.

---

Phase 2: Scoring & Location Decision

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

Decision Rules

Score	Action
Root (.)	ALWAYS create
>15	Create AGENTS.md
8-15	Create if distinct domain
<8	Skip (parent covers)

---

Phase 3: Generate AGENTS.md

Root AGENTS.md (Full Treatment)

# PROJECT KNOWLEDGE BASE

**Generated:** {TIMESTAMP}

## OVERVIEW
{1-2 sentences: what + core stack}

## STRUCTURE
{root}/
  {dir}/    # {non-obvious purpose only}
  {entry}

## WHERE TO LOOK
| Task | Location | Notes |

## CONVENTIONS
{ONLY deviations from standard}

## ANTI-PATTERNS (THIS PROJECT)
{Explicitly forbidden here}

## COMMANDS
{dev/test/build}

## NOTES
{Gotchas}

Quality gates: 50-150 lines, no generic advice, no obvious info.

Subdirectory AGENTS.md (Parallel)

For each scored location (except root):

• 30-80 lines max
• NEVER repeat parent content
• Sections: OVERVIEW (1 line), STRUCTURE (if >5 subdirs), WHERE TO LOOK, CONVENTIONS (if different), ANTI-PATTERNS

---

Phase 4: Review & Deduplicate

For each generated file:

• Remove generic advice
• Remove parent duplicates
• Trim to size limits
• Verify telegraphic style

---

Final Report

=== init-deep Complete ===

Mode: {update | create-new}

Files:
  [OK] ./AGENTS.md (root, {N} lines)
  [OK] ./src/hooks/AGENTS.md ({N} lines)

Dirs Analyzed: {N}
AGENTS.md Created: {N}
AGENTS.md Updated: {N}

Hierarchy:
  ./AGENTS.md
    src/hooks/AGENTS.md

---

Anti-Patterns

• Static agent count: MUST vary agents based on project size/depth
• Sequential execution: MUST parallel (explore concurrent)
• Ignoring existing: ALWAYS read existing first, even with --create-new
• Over-documenting: Not every dir needs AGENTS.md
• Redundancy: Child never repeats parent
• Generic content: Remove anything that applies to ALL projects
• Verbose style: Telegraphic or die