Imported from mzored/init-deep (skills/init-deep/SKILL.md). Install upstream with npx skills add mzored/init-deep --skill init-deep. Copyright stays with the author.

/init-deep — Deep Project Initialization

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

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:

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

Scoring Matrix

Score each directory to determine if it needs scoped documentation:

Decision Rules

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)

# 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

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):

# {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):

---
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):

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