/init-deep

Init Deep — Generate Directory CLAUDE.md Files

Analyze the project structure, generate CLAUDE.md files for each significant directory, and auto-configure Serena MCP if the project has language server support.

Target: {{arguments}} (default: current project root)

Workflow

Step 0: Initialize OmO State

mkdir -p .claude/omo/{plans,drafts,notepads,handoffs,evidence}

Step 0.5: Configure Permissions for Autonomous Execution

Check if .claude/settings.local.json exists in the project root. If it doesn't, create it with the recommended OmO permissions:

{
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "Write",
      "Glob",
      "Grep",
      "Bash(git *)",
      "Bash(mkdir *)",
      "Bash(ls *)",
      "Bash(cat *)",
      "Bash(bash .claude/plugins/omo/scripts/*)",
      "mcp__plugin_omo_serena__*",
      "mcp__plugin_omo_context7__*",
      "mcp__plugin_omo_grep_app__*",
      "WebFetch",
      "WebSearch"
    ]
  }
}

If the file already exists, merge the permissions.allow entries without removing existing rules. Tell the user what was added.

This enables autonomous execution for Atlas, Hephaestus, and other agents without constant permission prompts. Arbitrary bash commands (beyond git, mkdir, ls, cat, and OmO scripts) still require user approval.

Step 1: Discovery & Background Exploration

Launch explorer agents in background (run_in_background: true):

• Explorer 1: Project structure and entry points
• Explorer 2: Code conventions and patterns
• Explorer 3: Build/test patterns and anti-patterns
• Explorer 4: Dependencies and integration points

Scale agent count with project complexity (more directories = more agents).

While explorers run in background, proceed with Step 2 scoring.

Step 2: Score Directories

List all directories and score each using weighted factors:

Factor	Weight	How to Measure
File count	3x	Number of files in directory
Subdirectory count	2x	Number of subdirectories
Code file ratio	2x	Code files / total files (exclude generated, config, assets)
Symbol density	2x	Count of exported functions, classes, types (grep for export)
Export count	1x	Number of items exported from index/barrel files
Reference centrality	1x	How many other directories import from this one

Thresholds:

• Score > 15: Generate CLAUDE.md
• Score 8-15: Generate only if directory has a distinct domain/purpose
• Score < 8: Skip

Step 3: Auto-Configure Serena MCP

Check if the project has language server support by looking for:

• tsconfig.json or jsconfig.json → TypeScript/JavaScript LSP
• pyproject.toml or setup.py or setup.cfg → Python LSP
• Cargo.toml → Rust LSP
• go.mod → Go LSP
• pom.xml or build.gradle → Java LSP
• *.sln or *.csproj → C# LSP
• Gemfile → Ruby LSP
• Package.swift → Swift LSP

If any are found, create or update the project's .mcp.json:

{
  "serena": {
    "command": "uvx",
    "args": [
      "--from",
      "git+https://github.com/oraios/serena",
      "serena",
      "start-mcp-server",
      "--context",
      "claude-code",
      "--project",
      "{absolute-path-to-project-root}"
    ]
  }
}

If .mcp.json already exists in the project, merge the serena entry without overwriting existing MCP servers. If serena is already configured, skip this step.

Also check if .claude/settings.local.json has enableAllProjectMcpServers or enabledMcpjsonServers — if not, inform the user they need to enable the MCP server.

Step 4: Generate CLAUDE.md Files

Root CLAUDE.md (50-150 lines):

# {Project Name}

## Overview
{What this project does, 2-3 sentences}

## Tech Stack
{Languages, frameworks, key dependencies}

## Project Structure
{Directory tree with one-line descriptions}

## Where to Look
{Map of "if you need X, look in Y"}

## Conventions
{Code style, naming patterns, architectural patterns}

## Anti-Patterns
{Things to avoid that are specific to this codebase}

## Development
{How to build, test, run}

Subdirectory CLAUDE.md (30-80 lines max):

# {Directory Name}

## Purpose
{What this directory contains and why}

## Key Files
- `file.ts` — {purpose}
- `other.ts` — {purpose}

## Conventions
{Patterns specific to this directory}

## Dependencies
{What this directory depends on and what depends on it}

Generate subdirectory files in parallel. Never duplicate parent content in child files.

Step 5: Review Pass

Before writing, validate:

• Remove generic advice that could apply to any project
• Eliminate parent-child content redundancy
• Enforce size limits (root: 150 lines max, subdirs: 80 lines max)
• Ensure telegraphic writing style (facts, not prose)

Step 6: Write Files

Write CLAUDE.md to each directory. Do NOT overwrite existing CLAUDE.md files — instead, merge new information into them.

Rules

• Keep descriptions concise and factual
• Reference actual file names and patterns found in the code
• Do not add aspirational content ("should", "could") — describe what IS
• Scale dynamically: more files in a directory = more detail in its CLAUDE.md
• Use explorer agent findings, not assumptions