deep-init

Deep Init - Hierarchical CLAUDE.md Generation

Arguments: $ARGUMENTS (optional path for single directory)

Flow:

• No args → Run Phase 1-3
• With path → Skip to Phase 3 for that path only

---

Phase 1: Discovery

Skip if $ARGUMENTS has path.

Step 1a: Structure

Build the directory tree from git-tracked files:

git ls-files | xargs -n1 dirname | sort | uniq -c | sort -rn

For each directory, capture:

• path - Directory path
• files - List of git-tracked filenames in this dir
• file_count - Number of direct files
• subtree_file_count - Total files in subtree
• has_manifest - Contains package.json, go.mod, Cargo.toml, pyproject.toml, etc.
• has_readme - Contains README.md

Step 1b: Semantic Context (if tools available)

If you have access to tools that can extract symbol signatures (class/function/type names) without reading full file contents, use them on directories with ≥3 files to gather:

• symbols - List of symbol names and their kinds
• domain_hints - Inferred from symbol names (e.g., AuthService → auth domain, StripeClient → integration)

This helps identify domain boundaries and integration points that aren't obvious from filenames alone.

Output: JSON tree structure with all directories and metadata (including symbols if available).

---

Phase 2: Judgment

Skip if $ARGUMENTS has path - use that as sole target.

Examine the full tree recursively. Identify directories warranting CLAUDE.md.

A directory qualifies if it is ANY of:

1. DOMAIN BOUNDARY - Distinct conceptual area (auth, billing, search). Cohesive files that belong together. Someone would work "in this domain."

2. INTEGRATION POINT - Connects to external systems. File names suggest external communication (webhook, client, adapter, api). Own config for external services.

3. SUB-APP - Self-contained application. Has entry points, routes, or own runtime. Could be extracted as standalone.

4. TECHNICAL COMPLEXITY - Specialized knowledge required. Non-obvious patterns that an AI agent would get wrong without guidance.