init-deep

Codex Harness Tool Compatibility

This skill may include examples copied from the OpenCode harness. In Codex, do not call OpenCode-only tools such as call_omo_agent(...), task(...), background_output(...), or team_*(...) literally. Translate those examples to Codex native tools:

| OpenCode example | Codex tool to use |

| --- | --- |

| call_omo_agent(subagent_type="explore", ...) | multi_agent_v1.spawn_agent({"message":"TASK: act as an explorer. ...","agent_type":"explorer","fork_context":false}) |

| call_omo_agent(subagent_type="librarian", ...) | multi_agent_v1.spawn_agent({"message":"TASK: act as a librarian. ...","agent_type":"librarian","fork_context":false}) |

| task(subagent_type="plan", ...) | multi_agent_v1.spawn_agent({"message":"TASK: act as a planning agent. ...","agent_type":"plan","fork_context":false}) |

| task(subagent_type="oracle", ...) for final verification | By default, record a self-review in the notepad: re-read the diff, run diagnostics, and capture evidence for every acceptance criterion. Only when the user demanded strict, rigorous, or high-accuracy review, use multi_agent_v1.spawn_agent({"message":"TASK: act as a rigorous reviewer. ...","agent_type":"lazycodex-gate-reviewer","fork_context":false}); include fork_context: false. |

| task(category="...", ...) for implementation or QA | multi_agent_v1.spawn_agent({"message":"TASK: act as an implementation or QA worker. ...","agent_type":"lazycodex-worker-medium","fork_context":false}) |

| background_output(task_id="...") | multi_agent_v1.wait_agent(...) for mailbox signals |

| team_*(...) | Use Codex native subagents via multi_agent_v1.spawn_agent and multi_agent_v1.wait_agent; use multi_agent_v1.send_input and multi_agent_v1.close_agent only when exposed in the active tools list |

Role-specific behavior must be described in a self-contained message. Use fork_context: false to start the child with only the initial prompt (no parent history); use fork_context: true only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's message. OMO installs these selectable agent roles into ~/.codex/agents/: explorer, librarian, plan, momus, metis, lazycodex-code-reviewer, lazycodex-qa-executor, and lazycodex-gate-reviewer - pass the matching name as agent_type so the child gets that role's model and instructions. Inspect the actual spawn schema: whenever agent_type is exposed, EVERY spawn MUST select an exact LazyCodex role, on V1 or V2. Implementation difficulty selects lazycodex-worker-low, lazycodex-worker-medium, or lazycodex-worker-high; clone QA can select lazycodex-clone-fidelity-reviewer. Never select generic worker or default. If a code block below conflicts with this section, this section wins.

Codex exposes ONE of two subagent tool surfaces per session; check your own tool list and route accordingly. If multi_agent_v1. tools exist, use the table above as written. If instead a flat spawn_agent with a required task_name exists (multi_agent_v2), rewrite every multi_agent_v1. example: multi_agent_v1.spawn_agent({...,"fork_context":false}) becomes spawn_agent({"task_name":"<lowercase_digits_underscores>","message":...,"agent_type":...,"fork_turns":"none"}) ("all" only when full parent history is truly required); send_input becomes send_message; do not call close_agent/resume_agent (finished agents end on their own; followup_task re-tasks one, interrupt_agent stops one); wait_agent takes only timeout_ms and returns on any child mailbox activity. Do not infer role support from V1/V2 or a model version. Legacy-schema exception: only if the actual schema lacks agent_type, omit that unsupported field and carry the complete role instructions in message, with history explicitly disabled. This cannot select a specialized TOML; an installed managed default supplies the medium worker for unnamed non-forks. The guard has no schema metadata and rejects unnamed calls, so report incompatible routing instead of retrying generically. Every deliberate full-history fork must still name its role: Codex skips role application on unnamed full-history forks, an upstream gap no LazyCodex default can repair. If a code block below conflicts with this section, this section wins. fork_context is rejected on multi_agent_v2 (fork_context is not supported in MultiAgentV2; use fork_turns instead).

When translating load_skills=[...], include the requested skill names in the spawned agent's message. If a code block below conflicts with this section, this section wins.

Omit optional keys you do not set. Never send items: [], message: "", model: "", reasoning_effort: "", or service_tier: "" — Codex rejects them (Items can't be empty, reasoning_effort must not be empty).

For work likely to exceed one wait cycle, require the child to send WORKING: <task> - <current phase> before long passes and BLOCKED: <reason> only when progress stops. A multi_agent_v1.wait_agent timeout only means no new mailbox update arrived; back off between waits (double the timeout up to ~5 minutes) instead of spinning short cycles. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly BLOCKED:, or no longer running.

/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/ast-grep code map + read existing AGENTS.md

1. Score & Decide - Determine AGENTS.md locations from merged findings
2. Generate - Root first, then subdirs in parallel
3. Review - Deduplicate, trim, validate

<critical>

TodoWrite ALL phases. Mark in_progress → completed in real-time.

TodoWrite([
  { id: "discovery", content: "Fire explore agents + LSP/ast-grep map + 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. Ground every agent in real symbol data: any task touching structure, entry points, dependencies, or hotspots MUST query lsp_symbols/lsp_find_references and the ast-grep skill (sg) when present, and ground its claims in that data instead of guessing from conventions. Richer real context per agent = a more accurate project map.

// Fire all at once, collect results later
task(subagent_type="explore", load_skills=[], description="Explore project structure", run_in_background=true, prompt="Project structure: map real layout via glob + lsp_symbols scope=workspace → REPORT deviations from standard patterns")
task(subagent_type="explore", load_skills=[], description="Find entry points", run_in_background=true, prompt="Entry points: FIND main files, trace reach via lsp_symbols + lsp_find_references → 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/structure; lsp_find_references on core modules to see what is covered → 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 |

# 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

# 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. Code Map - drive LSP AND ast-grep (do NOT skip)

Highest-signal source for the CODE MAP and the Symbol/Export/Reference scoring rows. Complementary, not alternatives - run BOTH when present, alongside the explore agents.

LSP - check lsp_status; model-facing names are lsp_status/lsp_symbols/lsp_find_references/lsp_goto_definition (some harnesses drop the lsp_ prefix):

• lsp_symbols scope="document" on each entry point -> file outline.
• lsp_symbols scope="workspace", query by kind (class/interface/function) -> symbol inventory.
• lsp_find_references on top exports (line/character from the symbols result) -> reference centrality.

ast-grep - load the ast-grep skill; a first-class peer to LSP, NOT a last resort:

• sg --pattern 'export $$$' --lang <lang> -> export inventory; sg --pattern 'import $$$ from "$MOD"' -> dependency edges between modules for the scoring matrix.

Only if LSP is unavailable: explore agents + ast-grep alone, and mark reference centrality unmeasured in the CODE MAP.

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/ast-grep + 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/cg |

| Export count | 2x | >10 exports | LSP/cg |

| Reference centrality | 3x | >20 refs | LSP/cg |

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)

# PROJECT KNOWLEDGE BASE

**Generated:** {TIMESTAMP}
**Commit:** {SHORT_SHA}
**Branch:** {BRANCH}

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

## STRUCTURE

{root}/

├── {dir}/ # {non-obvious purpose only}

└── {entry}

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

## CODE MAP
{From LSP/ast-grep - skip only if neither exists or project <10 files}

| Symbol | Type | Location | Refs | Role |
|--------|------|----------|------|------|

## CONVENTIONS
{ONLY deviations from standard}

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

## UNIQUE STYLES
{Project-specific}

## COMMANDS

{dev/test/build}

## NOTES
{Gotchas}

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

Subdirectory AGENTS.md (Parallel)

Launch writing tasks for each location:

for loc in AGENTS_LOCATIONS (except root):
  task(category="writing", load_skills=[], run_in_background=false, description="Generate AGENTS.md", prompt=`
    Generate AGENTS.md for: ${loc.path}
    - Reason: ${loc.reason}
    - 30-80 lines max
    - NEVER repeat parent content
    - Sections: OVERVIEW (1 line), STRUCTURE (if >5 subdirs), WHERE TO LOOK, CONVENTIONS (if different), ANTI-PATTERNS
  `)

Wait for all. Mark "generate" as completed.

---

Phase 4: Review & Deduplicate

Mark "review" as in_progress.

For each generated file:

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

Mark "review" as completed.

---

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 + LSP + ast-grep 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