Init Deep

---
name: init-deep
description: Deeply analyze a codebase and generate multi-agent project documentation (AGENTS.md + CLAUDE.md + GEMINI.md + scoped docs). Only invoke when user explicitly types /init-deep.
argument-hint: "[--create-new] [--max-depth=N] [--only=claude,codex] [--skip-cursor] [--dry-run] [--doctor] [--sync-check]"
disable-model-invocation: true
---

# /init-deep — Deep Project Initialization

Analyze codebase deeply. Generate documentation that works across AI coding agents:

| File | Read by | Hierarchy | Purpose |
|------|---------|-----------|---------|
| `AGENTS.md` | OpenAI Codex | root + subdirs | Universal agent instructions (canonical) |
| `CLAUDE.md` | Claude Code | root + subdirs | Claude context, derived from AGENTS.md |
| `GEMINI.md` | Google Gemini CLI | root + `~/.gemini/` | Gemini context, derived from AGENTS.md |
| `.github/copilot-instructions.md` | GitHub Copilot | root only | Copilot-specific context |
| `.windsurfrules` | Windsurf | root only | Windsurf context (flat file) |
| `.clinerules` | Cline | root only | Cline context (flat file) |
| `.claude/rules/*.md` | Claude Code | glob-scoped | Scoped module docs with `paths:` frontmatter |
| `.cursor/rules/*.mdc` | Cursor | glob-scoped | Scoped module docs with `globs:` frontmatter |

**Primary native surfaces** — each tool has preferred file locations and formats. Some tools also read cross-compatible fallbacks, but portability comes from generating each platform's native surface.

**Key principle:** `AGENTS.md` is the canonical source. All other root files are derived from it with tool-specific additions. Content overlap ~90%.

## 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)
/init-deep --skip-cursor        # Skip .cursor/rules/ generation
/init-deep --skip-gemini        # Skip GEMINI.md generation
/init-deep --skip-copilot       # Skip .github/copilot-instructions.md
/init-deep --skip-windsurf      # Skip .windsurfrules
/init-deep --skip-cline         # Skip .clinerules
/init-deep --only=claude,codex  # Generate only specified platforms (comma-separated)
/init-deep --dry-run            # Preview what would be generated without writing files
/init-deep --doctor             # Verify existing docs are valid and complete
/init-deep --sync-check         # Check if derived files are in sync with canonical source
```

### Non-generation Modes

- `--dry-run` — show planned outputs (paths + line counts) without writing any files.
- `--doctor` — validate existing generated docs: check frontmatter, verify paths globs match real files, report stale or missing docs.
- `--sync-check` — compare each derived file against its canonical source and report drift (exit non-zero if out of sync).

## Date Preservation Rule

**CRITICAL:** When editing existing files, NEVER change dates, timestamps, or version numbers that already exist in the content. This includes:
- Dates in headings (e.g., `## 2026-03-24 — Initial Design`)
- Dates in frontmatter (`date:`, `created:`, `updated:`)
- Dates in file names
- Version numbers
- Timestamps in comments (e.g., `<!-- Generated by /init-deep -->`)
- The `<!-- Generated from ... by /init-deep. Keep in sync. -->` header comment — update only if the source file changed

When generating NEW files, do NOT add dates or timestamps. The git history is the authoritative timeline.

## Workflow

**Phase 1: Discovery -> Phase 2: Score & Decide -> Phase 3: Generate -> Phase 4: Review**

Track ALL phases with TodoWrite. Mark progress in real-time.

---

## Phase 1: Discovery + Analysis (Concurrent)

### Fire Background Analysis IMMEDIATELY

When the host platform supports subagents or parallel background agents, launch concurrent read-only analysis workers for:

1. **Project structure**: Language, framework, build system. Report only non-standard patterns.
2. **Entry points**: Main files, CLI entry points, server startup. Report non-standard organization.
3. **Conventions**: Config files (pyproject.toml, package.json, .eslintrc, tsconfig.json, ruff.toml). Report project-specific rules only.
4. **Anti-patterns**: Search for 'DO NOT', 'NEVER', 'ALWAYS', 'DEPRECATED', 'HACK', 'FIXME', 'TODO' comments. List forbidden patterns.
5. **Build/CI**: .github/workflows, Makefile, Dockerfile, docker-compose, CI configs. Report build/test/deploy commands.
6. **Test patterns**: Test configs, directory structure, fixtures, mocking patterns. Report unique conventions.

### Dynamic Analysis Scaling

After initial analysis, scale based on project size:

| Factor | Threshold | Additional Work |
|--------|-----------|-----------------|
| Total files | >100 | Focus on distinct file clusters |
| Total lines | >10k | Focus on large file analysis |
| Directory depth | >=4 | Deep module exploration |
| Large files (>500 lines) | >10 files | Complexity hotspot analysis |
| Monorepo | detected | Per-package analysis |
| Multiple languages | >1 | Per-language analysis |

If subagents are unavailable, run the same analyses in the main session and state that concurrency was unavailable.

### Structural Analysis

Use the platform's native file search tools (Glob/Grep/Search, `rg`, or equivalent) for:
- File counts per directory (top 30)
- Directory depth distribution
- Code concentration by extension
- Large files (>300 lines) — use `wc -l` via Bash only for line counting
- Existing docs across all agent formats:

```
Search: **/CLAUDE.md, **/AGENTS.md, **/GEMINI.md, **/AGENTS.override.md
Search: .claude/rules/*.md
Search: .cursor/rules/*.mdc
Search: .github/copilot-instructions.md
```

### Read All Existing Documentation

Read every agent config file found. Extract key insights. Store for deduplication.

If `--create-new`: read all existing first (preserve context), then note them for replacement.

---

## Phase 2: Scoring & Location Decision

### What gets generated

| Output | When | Format |
|--------|------|--------|
| **Root `AGENTS.md`** | Always | 50-150 lines, canonical source |
| **Root `CLAUDE.md`** | Always | Derived from AGENTS.md, Claude-specific additions |
| **Root `GEMINI.md`** | Unless --skip-gemini | Derived from AGENTS.md, Gemini-specific additions |
| **Root `.github/copilot-instructions.md`** | Unless --skip-copilot | Condensed from AGENTS.md (keep short — Copilot truncates) |
| **Root `.windsurfrules`** | Unless --skip-windsurf | Flat copy of AGENTS.md content |
| **Root `.clinerules`** | Unless --skip-cline | Flat copy of AGENTS.md content |
| **Subdir `AGENTS.md`** | Score >12, distinct domain | 20-60 lines, hierarchical scoped |
| **`.claude/rules/<module>.md`** | Same dirs as subdir AGENTS.md | 20-60 lines, `paths:` frontmatter |
| **`.cursor/rules/<module>.mdc`** | Unless --skip-cursor | 20-60 lines, Cursor MDC format |

### Scoring Matrix

Score each directory to determine if it needs scoped documentation:

| Factor | Weight | High (3pts) | Medium (2pts) | Low (1pt) | Source |
|--------|--------|-------------|---------------|-----------|--------|
| File count | 3x | >20 files | 10-20 | <10 | Glob |
| Code ratio | 2x | >70% code files | 40-70% | <40% | Glob |
| Module boundary | 2x | Has __init__.py/index.ts | Has exports | Neither | Glob |
| Large files | 2x | >3 files >300 lines | 1-3 | 0 | Bash wc |
| Distinct domain | 3x | Clear bounded context | Partial | Generic utility | analysis |
| Unique conventions | 2x | Own patterns/anti-patterns | Some | Same as parent | analysis |

### Decision Rules

| Score | Action |
|-------|--------|
| **Root (.)** | ALWAYS generate `AGENTS.md` + `CLAUDE.md` + `GEMINI.md` |
| **>12** | Create `<dir>/AGENTS.md` AND `.claude/rules/<name>.md` AND `.cursor/rules/<name>.mdc` |
| **8-12** | Create only if module has unique conventions or known pitfalls |
| **<8** | Skip — root docs cover it |

### Naming Convention

Derive names from directory paths:
- `src/domain/` -> `src/domain/AGENTS.md` + `.claude/rules/domain.md` + `.cursor/rules/domain.mdc`
- `src/runtime/` -> `src/runtime/AGENTS.md` + `.claude/rules/runtime.md`
- `src/tracks/copy_trade/` -> `src/tracks/copy_trade/AGENTS.md` + `.claude/rules/tracks-copy-trade.md`
- `tests/` -> `tests/AGENTS.md` + `.claude/rules/testing.md`

---

## Phase 3: Generate Files

**File Writing Rule**: If file already exists -> use Edit tool. If it does NOT exist -> use Write tool.
In update mode (default): PRESERVE existing content that is still accurate. PRESERVE all dates and timestamps.
In --create-new mode: regenerate from scratch but informed by what existed.

### 3a. Root AGENTS.md (50-150 lines, canonical)

```markdown
# AGENTS.md

## Overview
{1-2 sentences: what this project does + core tech stack}

## Setup
{Essential commands to get running — install, env vars, build}

## Commands
```bash
{dev / test / lint / build / deploy — the commands an AI agent needs}
```

## Architecture
{High-level data flow or module relationships}
{Structure tree — only non-obvious directories}

### Key Files
| File | Role |
|------|------|

## Conventions
{ONLY project-specific deviations from standard practices}
{Naming, patterns, import style — things that would surprise a new contributor}

## Known Pitfalls
{Non-obvious gotchas, things that break silently}
```

AGENTS.md content rules:
- Tool-neutral language — no "use the Read tool" or ".claude/rules/"
- No dates or timestamps — git history is the timeline
- No generic advice — only project-specific knowledge

### 3b. Root CLAUDE.md (derived from AGENTS.md)

**Size limit:** Keep CLAUDE.md under 200 lines — longer files consume tokens and reduce adherence.

**Two strategies** — pick based on project preference:

**Strategy A (import):** Minimal CLAUDE.md that imports AGENTS.md:
```markdown
# CLAUDE.md
@AGENTS.md

## Claude Code Specific
- Scoped rules in `.claude/rules/` for module-specific guidance
- Read Order: (Claude-only section)
```
Pros: single source of truth, zero drift. Cons: can't customize per-tool easily.

**Strategy B (derive):** Full copy with Claude additions (current default).

If the project already uses Strategy A, preserve it. Otherwise, use Strategy B:

After writing AGENTS.md, derive CLAUDE.md from it:

1. Copy AGENTS.md content
2. Replace title `# AGENTS.md` -> `# CLAUDE.md`
3. Add Claude-specific references (`.claude/rules/` pointers, Claude Code features) where helpful
4. Keep language appropriate — can reference Claude-specific tools
5. Add header comment: `<!-- Derived from AGENTS.md by /init-deep. Keep in sync. -->`
6. Keep same sections and structure
7. **PRESERVE any Claude-specific sections** that exist in current CLAUDE.md but not in AGENTS.md (e.g., Read Order, Context Maintenance)

CLAUDE.md content rules:
- CAN reference `.claude/rules/` directory
- CAN use Claude Code tool names
- KEEP all project-specific knowledge identical to AGENTS.md
- SAME length as AGENTS.md (50-150 lines), plus any Claude-specific extras
- NO dates or timestamps

### 3c. Root GEMINI.md (derived from AGENTS.md)

Unless `--skip-gemini`:

1. Copy AGENTS.md content
2. Replace title -> `# GEMINI.md`
3. Add header comment: `<!-- Derived from AGENTS.md by /init-deep. Keep in sync. -->`
4. Gemini CLI reads this file for project context — keep format identical
5. NO dates or timestamps

### 3e. Flat-file Formats (copilot, windsurf, cline)

These are simpler — single root file, no hierarchy, no frontmatter.

**`.github/copilot-instructions.md`** (unless --skip-copilot):
- Condensed version of AGENTS.md — Copilot is more aggressive about truncation
- Keep under 80 lines; prioritize commands and conventions
- Create `.github/` directory if needed
- Header: `<!-- Derived from AGENTS.md by /init-deep. Keep in sync. -->`

**`.windsurfrules`** (unless --skip-windsurf):
- Flat copy of AGENTS.md content (same sections, same knowledge)
- No frontmatter, no header comment (Windsurf reads raw)
- Replace `# AGENTS.md` title with `# Project Instructions`

**`.clinerules`** (unless --skip-cline):
- Same as .windsurfrules — flat Markdown, no frontmatter

### 3f. Scoped Files (Parallel)

For each scored location, generate BOTH `<dir>/AGENTS.md` AND `.claude/rules/<name>.md` (and optionally `.cursor/rules/<name>.mdc`).

Create `.claude/rules/` and `.cursor/rules/` directories if they don't exist.

**`<dir>/AGENTS.md`** (20-60 lines):
```markdown
# {Module Name}

{1-line purpose}

## Key Files
| File | Role |
|------|------|

## Conventions
{Module-specific conventions ONLY — different from project root}

## Anti-Patterns
{Explicitly forbidden in THIS module}

## Known Pitfalls
{Non-obvious gotchas specific to this module}
```

**`.claude/rules/{name}.md`** (20-60 lines):
```markdown
---
paths:
  - "{glob_pattern_1}"
  - "{glob_pattern_2}"
---

# {Module Name}

{Same content as the AGENTS.md above}
```

**`.cursor/rules/{name}.mdc`** (20-60 lines, unless --skip-cursor):
```markdown
---
description: {Module Name} — {1-line purpose}
globs:
  - "{glob_pattern_1}"
  - "{glob_pattern_2}"
---

# {Module Name}

{Same content as the AGENTS.md above}
```

Rules for ALL scoped files:
- 20-60 lines max each
- NEVER repeat content from root AGENTS.md / CLAUDE.md
- Only include sections with actual content — skip empty sections
- Telegraphic style — every line must earn its place
- Focus on what's UNIQUE to this module
- NO dates or timestamps

---

## Phase 4: Review & Deduplicate

### For root files:
1. **AGENTS.md <-> CLAUDE.md <-> GEMINI.md sync** — verify content is equivalent (modulo tool-specific language)
2. **Remove generic advice** — delete anything that applies to ALL projects
3. **Trim to 50-150 lines** — cut filler, keep signal
4. **Verify commands work** — spot-check 1-2 listed commands
5. **No dates/timestamps** — remove any that were accidentally added

### For scoped files:
1. **subdir AGENTS.md <-> rules/*.md sync** — verify each pair is equivalent
2. **Verify `paths:` frontmatter** in .claude/rules/ files — glob patterns must match actual file locations
3. **Verify `globs:` frontmatter** in .cursor/rules/ files — same patterns
4. **Remove root duplicates** — if scoped file says same thing as root, delete from scoped
5. **Trim to 20-60 lines** — aggressive
6. **Remove empty sections** — if a section has no content, delete the heading too
7. **Check no overlap** — two scoped files shouldn't cover the same paths/directories

### .gitattributes Check

Consider adding to `.gitattributes`:
```
CLAUDE.md linguist-generated=true
GEMINI.md linguist-generated=true
**/AGENTS.md linguist-generated=true
.windsurfrules linguist-generated=true
.clinerules linguist-generated=true
.github/copilot-instructions.md linguist-generated=true
```
This marks derived files as generated in GitHub diffs (collapsed by default).

### Final Report

```
=== /init-deep Complete ===

Mode: {update | create-new}

Root files:
  [OK] ./AGENTS.md ({N} lines) — canonical
  [OK] ./CLAUDE.md ({N} lines) — derived
  [OK] ./GEMINI.md ({N} lines) — derived
  [OK] .github/copilot-instructions.md ({N} lines) — condensed
  [OK] .windsurfrules ({N} lines) — derived
  [OK] .clinerules ({N} lines) — derived

Codex scoped (subdirectory AGENTS.md):
  [OK] src/domain/AGENTS.md ({N} lines)
  [OK] src/runtime/AGENTS.md ({N} lines)

Claude Code scoped (.claude/rules/):
  [OK] .claude/rules/domain.md ({N} lines, paths: src/domain/**)
  [OK] .claude/rules/runtime.md ({N} lines, paths: src/runtime/**)

Cursor scoped (.cursor/rules/):
  [OK] .cursor/rules/domain.mdc ({N} lines, globs: src/domain/**)
  [OK] .cursor/rules/runtime.mdc ({N} lines, globs: src/runtime/**)

Skipped:
  [SKIP] src/utils/ (score 6, covered by root)

Summary:
  Dirs analyzed: {N}
  Root docs: {N} (AGENTS.md + CLAUDE.md + GEMINI.md)
  Scoped docs: {N} sets (subdir AGENTS.md + .claude/rules/ + .cursor/rules/)
  Skipped: {N}

Compatibility (each tool reads ONLY its own files):
  + OpenAI Codex   — AGENTS.md (root + subdirs)
  + Claude Code    — CLAUDE.md (root + subdirs) + .claude/rules/
  + Google Gemini  — GEMINI.md
  + GitHub Copilot — .github/copilot-instructions.md
  + Cursor         — .cursor/rules/*.mdc
  + Windsurf       — .windsurfrules
  + Cline          — .clinerules
```

---

## Keeping Files in Sync

After initial generation, AGENTS.md is the **canonical source**. When updating:

1. Edit `AGENTS.md` (or subdirectory `AGENTS.md`)
2. Run `/init-deep` again — it will detect changes and update derived counterparts
3. Or manually sync: the header comment in each derived file shows its source

## Anti-Patterns (for this skill)

- **Changing dates**: NEVER modify existing dates, timestamps, or version numbers in files
- **Adding dates**: NEVER add dates/timestamps to generated content — git is the timeline
- **Single-format output**: MUST generate AGENTS.md + CLAUDE.md (+ GEMINI.md unless skipped)
- **Divergent content**: Root files must stay in sync — same knowledge, different packaging
- **Tool-specific language in AGENTS.md**: Keep AGENTS.md neutral — no "use the Read tool" or ".claude/rules/"
- **Unbounded shell search**: Prefer platform-native search tools or `rg`; avoid slow recursive `find`/`grep` scans when better search tools are available
- **Static analysis**: MUST scale analysis based on project size/depth
- **Sequential when parallel**: Analyses MUST run concurrently via Agent subagents where possible
- **Ignoring existing docs**: ALWAYS read existing files first, even with --create-new
- **Over-documenting**: Not every directory needs scoped docs — scoring matrix decides
- **Redundancy**: Scoped files NEVER repeat root content
- **Generic content**: Remove anything that applies to ALL projects
- **Verbose prose**: Telegraphic or cut it. Every line must help an AI agent work faster
- **Missing paths: frontmatter**: Every .claude/rules/ file MUST have paths: or it loads unconditionally
- **Missing globs: frontmatter**: Every .cursor/rules/ file MUST have globs: or it loads unconditionally