diff --git a/src/features/builtin-commands/templates/init-deep.ts b/src/features/builtin-commands/templates/init-deep.ts index e43e10d..beb1be8 100644 --- a/src/features/builtin-commands/templates/init-deep.ts +++ b/src/features/builtin-commands/templates/init-deep.ts @@ -1,228 +1,191 @@ -export const INIT_DEEP_TEMPLATE = `# Initialize Deep Knowledge Base +export const INIT_DEEP_TEMPLATE = `# /init-deep -Generate comprehensive AGENTS.md files across project hierarchy. Combines root-level project knowledge (gen-knowledge) with complexity-based subdirectory documentation (gen-knowledge-deep). +Generate hierarchical AGENTS.md files. Root + complexity-scored subdirectories. ## Usage \`\`\` -/init-deep # Analyze and generate hierarchical AGENTS.md -/init-deep --create-new # Force create from scratch (ignore existing) -/init-deep --max-depth=2 # Limit to N directory levels (default: 3) +/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) \`\`\` --- -## Core Principles +## Workflow (High-Level) -- **Telegraphic Style**: Sacrifice grammar for concision ("Project uses React" → "React 18") -- **Predict-then-Compare**: Predict standard → find actual → document ONLY deviations -- **Hierarchy Aware**: Parent covers general, children cover specific -- **No Redundancy**: Child AGENTS.md NEVER repeats parent content -- **LSP-First**: Use LSP tools for accurate code intelligence when available (semantic > text search) - ---- - -## Process +1. **Discovery + Analysis** (concurrent) + - Fire background explore agents immediately + - Main session: bash structure + LSP codemap + read existing AGENTS.md +2. **Score & Decide** - Determine AGENTS.md locations from merged findings +3. **Generate** - Root first, then subdirs in parallel +4. **Review** - Deduplicate, trim, validate -**MANDATORY: TodoWrite for ALL phases. Mark in_progress → completed in real-time.** - - -### Phase 0: Initialize - +**TodoWrite ALL phases. Mark in_progress → completed in real-time.** \`\`\` TodoWrite([ - { id: "p1-analysis", content: "Parallel project structure & complexity analysis", status: "pending", priority: "high" }, - { id: "p2-scoring", content: "Score directories, determine AGENTS.md locations", status: "pending", priority: "high" }, - { id: "p3-root", content: "Generate root AGENTS.md with Predict-then-Compare", status: "pending", priority: "high" }, - { id: "p4-subdirs", content: "Generate subdirectory AGENTS.md files in parallel", status: "pending", priority: "high" }, - { id: "p5-review", content: "Review, deduplicate, validate all files", status: "pending", priority: "medium" } + { id: "discovery", content: "Fire explore agents + LSP codemap + 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" } ]) \`\`\` - ---- - -## Phase 1: Parallel Project Analysis - -**Mark "p1-analysis" as in_progress.** - - -**EXECUTION PATTERN**: Fire background agents FIRST (non-blocking), then main session builds codemap understanding using LSP tools in parallel. This maximizes throughput—agents discover while you analyze. --- -### Step 1: Fire Background Explore Agents (IMMEDIATELY) +## Phase 1: Discovery + Analysis (Concurrent) -Fire ALL background tasks at once. They run asynchronously—don't wait for results yet. +**Mark "discovery" as in_progress.** + +### Fire Background Explore Agents IMMEDIATELY + +Don't wait—these run async while main session works. \`\`\` -// Fire immediately - these run in parallel, non-blocking -background_task(agent="explore", prompt="Project structure: PREDICT standard {lang} patterns → FIND package.json/pyproject.toml/go.mod → REPORT deviations only") - -background_task(agent="explore", prompt="Entry points: PREDICT typical (main.py, index.ts) → FIND actual → REPORT non-standard organization") - -background_task(agent="explore", prompt="Conventions: FIND .cursor/rules, .cursorrules, eslintrc, pyproject.toml → REPORT project-specific rules DIFFERENT from defaults") - -background_task(agent="explore", prompt="Anti-patterns: FIND comments with 'DO NOT', 'NEVER', 'ALWAYS', 'LEGACY', 'DEPRECATED' → REPORT forbidden patterns") - -background_task(agent="explore", prompt="Build/CI: FIND .github/workflows, Makefile, justfile → REPORT non-standard build/deploy patterns") - -background_task(agent="explore", prompt="Test patterns: FIND pytest.ini, jest.config, test structure → REPORT unique testing conventions") +// Fire all at once, collect results later +background_task(agent="explore", prompt="Project structure: PREDICT standard patterns for detected language → REPORT deviations only") +background_task(agent="explore", prompt="Entry points: FIND main files → REPORT non-standard organization") +background_task(agent="explore", prompt="Conventions: FIND config files (.eslintrc, pyproject.toml, .editorconfig) → REPORT project-specific rules") +background_task(agent="explore", prompt="Anti-patterns: FIND 'DO NOT', 'NEVER', 'ALWAYS', 'DEPRECATED' comments → LIST forbidden patterns") +background_task(agent="explore", prompt="Build/CI: FIND .github/workflows, Makefile → REPORT non-standard patterns") +background_task(agent="explore", prompt="Test patterns: FIND test configs, test structure → REPORT unique conventions") \`\`\` ---- + +**DYNAMIC AGENT SPAWNING**: After bash analysis, spawn ADDITIONAL explore agents based on project scale: -### Step 2: Main Session Codemap Understanding (while background runs) +| 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 | -While background agents discover patterns, main session builds codemap understanding using direct tools. - - - -#### Structural Analysis (bash) \`\`\`bash -# Task A: Directory depth analysis -find . -type d -not -path '*/\\.*' -not -path '*/node_modules/*' -not -path '*/venv/*' -not -path '*/__pycache__/*' -not -path '*/dist/*' -not -path '*/build/*' | awk -F/ '{print NF-1}' | sort -n | uniq -c +# 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) +\`\`\` -# Task B: File count per directory -find . -type f -not -path '*/\\.*' -not -path '*/node_modules/*' -not -path '*/venv/*' -not -path '*/__pycache__/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -30 +Example spawning: +\`\`\` +// 500 files, 50k lines, depth 6, 15 large files → spawn 5+5+2+1 = 13 additional agents +background_task(agent="explore", prompt="Large file analysis: FIND files >500 lines, REPORT complexity hotspots") +background_task(agent="explore", prompt="Deep modules at depth 4+: FIND hidden patterns, internal conventions") +background_task(agent="explore", prompt="Cross-cutting concerns: FIND shared utilities across directories") +// ... more based on calculation +\`\`\` + -# Task C: Code concentration -find . -type f \\( -name "*.py" -o -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.go" -o -name "*.rs" -o -name "*.java" \\) -not -path '*/node_modules/*' -not -path '*/venv/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -20 +### Main Session: Concurrent Analysis -# Task D: Existing knowledge files +**While background agents run**, main session does: + +#### 1. Bash Structural Analysis +\`\`\`bash +# 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 \`\`\` -#### LSP Codemap Analysis (main session - semantic understanding) - -LSP provides semantic understanding beyond text search. Build the codemap while background agents run. - +#### 2. Read Existing AGENTS.md \`\`\` -# Check LSP availability first -lsp_servers() # Verify language server is available - -# Analyze entry point files (run in parallel) -lsp_document_symbols(filePath="src/index.ts") # Main entry -lsp_document_symbols(filePath="src/main.py") # Python entry -lsp_document_symbols(filePath="cmd/main.go") # Go entry - -# Discover key symbols across workspace (run in parallel) -lsp_workspace_symbols(filePath=".", query="class") # All classes -lsp_workspace_symbols(filePath=".", query="interface") # All interfaces -lsp_workspace_symbols(filePath=".", query="function") # Top-level functions -lsp_workspace_symbols(filePath=".", query="type") # Type definitions - -# Analyze symbol centrality (for top 5-10 key symbols) -# High reference count = central/important concept -lsp_find_references(filePath="src/index.ts", line=X, character=Y) # Main export +For each existing file found: + Read(filePath=file) + Extract: key insights, conventions, anti-patterns + Store in EXISTING_AGENTS map \`\`\` - - -#### Codemap Output Format +If \`--create-new\`: Read all existing first (preserve context) → then delete all → regenerate. +#### 3. LSP Codemap (if available) \`\`\` -CODE_INTELLIGENCE = { - entry_points: [ - { file: "src/index.ts", exports: ["Plugin", "createHook"], symbol_count: 12 } - ], - key_symbols: [ - { name: "Plugin", type: "class", file: "src/index.ts", refs: 45, role: "Central orchestrator" }, - { name: "createHook", type: "function", file: "src/utils.ts", refs: 23, role: "Hook factory" } - ], - module_boundaries: [ - { dir: "src/hooks", exports: 21, imports_from: ["shared/"] }, - { dir: "src/tools", exports: 15, imports_from: ["shared/", "hooks/"] } - ] -} +lsp_servers() # Check availability + +# Entry points (parallel) +lsp_document_symbols(filePath="src/index.ts") +lsp_document_symbols(filePath="main.py") + +# Key symbols (parallel) +lsp_workspace_symbols(filePath=".", query="class") +lsp_workspace_symbols(filePath=".", query="interface") +lsp_workspace_symbols(filePath=".", query="function") + +# Centrality for top exports +lsp_find_references(filePath="...", line=X, character=Y) \`\`\` - -**LSP Fallback**: If LSP unavailable (no server installed), skip LSP section and rely on explore agents + AST-grep patterns. - +**LSP Fallback**: If unavailable, rely on explore agents + AST-grep. + +### Collect Background Results + +\`\`\` +// After main session analysis done, collect all task results +for each task_id: background_output(task_id="...") +\`\`\` + +**Merge: bash + LSP + existing + explore findings. Mark "discovery" as completed.** --- -### Step 3: Collect Background Results +## Phase 2: Scoring & Location Decision -After main session analysis complete, collect background agent results: - -\`\`\` -// Collect all background_task results -// background_output(task_id="...") for each fired task -\`\`\` - -**Merge bash + LSP + background agent findings. Mark "p1-analysis" as completed.** - ---- - -## Phase 2: Complexity Scoring & Location Decision - -**Mark "p2-scoring" as in_progress.** +**Mark "scoring" as in_progress.** ### Scoring Matrix -| Factor | Weight | Threshold | Source | -|--------|--------|-----------|--------| -| File count | 3x | >20 files = high | bash | -| Subdirectory count | 2x | >5 subdirs = high | bash | -| Code file ratio | 2x | >70% code = high | bash | +| 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 __init__.py/index.ts | bash | -| **Symbol density** | 2x | >30 symbols = high | LSP | -| **Export count** | 2x | >10 exports = high | LSP | -| **Reference centrality** | 3x | Symbols with >20 refs | LSP | - - -**LSP-Enhanced Scoring** (if available): - -\`\`\` -For each directory in candidates: - symbols = lsp_document_symbols(dir/index.ts or dir/__init__.py) - - symbol_score = len(symbols) > 30 ? 6 : len(symbols) > 15 ? 3 : 0 - export_score = count(exported symbols) > 10 ? 4 : 0 - - # Check if this module is central (many things depend on it) - for each exported symbol: - refs = lsp_find_references(symbol) - if refs > 20: centrality_score += 3 - - total_score += symbol_score + export_score + centrality_score -\`\`\` - +| Module boundary | 2x | Has index.ts/__init__.py | bash | +| Symbol density | 2x | >30 symbols | LSP | +| Export count | 2x | >10 exports | LSP | +| Reference centrality | 3x | >20 refs | LSP | ### Decision Rules | Score | Action | |-------|--------| -| **Root (.)** | ALWAYS create AGENTS.md | -| **High (>15)** | Create dedicated AGENTS.md | -| **Medium (8-15)** | Create if distinct domain | -| **Low (<8)** | Skip, parent sufficient | - -### Output Format +| **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/api", score: 18, reason: "high complexity, 45 files" }, - { path: "src/hooks", score: 12, reason: "distinct domain, unique patterns" }, + { path: "src/hooks", score: 18, reason: "high complexity" }, + { path: "src/api", score: 12, reason: "distinct domain" } ] \`\`\` -**Mark "p2-scoring" as completed.** +**Mark "scoring" as completed.** --- -## Phase 3: Generate Root AGENTS.md +## Phase 3: Generate AGENTS.md -**Mark "p3-root" as in_progress.** +**Mark "generate" as in_progress.** -Root AGENTS.md gets **full treatment** with Predict-then-Compare synthesis. - -### Required Sections +### Root AGENTS.md (Full Treatment) \`\`\`markdown # PROJECT KNOWLEDGE BASE @@ -232,153 +195,75 @@ Root AGENTS.md gets **full treatment** with Predict-then-Compare synthesis. **Branch:** {BRANCH} ## OVERVIEW - -{1-2 sentences: what project does, core tech stack} +{1-2 sentences: what + core stack} ## STRUCTURE - \\\`\\\`\\\` -{project-root}/ -├── {dir}/ # {non-obvious purpose only} -└── {entry} # entry point +{root}/ +├── {dir}/ # {non-obvious purpose only} +└── {entry} \\\`\\\`\\\` ## WHERE TO LOOK - | Task | Location | Notes | |------|----------|-------| -| Add feature X | \\\`src/x/\\\` | {pattern hint} | ## CODE MAP - -{Generated from LSP analysis - shows key symbols and their relationships} +{From LSP - skip if unavailable or project <10 files} | Symbol | Type | Location | Refs | Role | |--------|------|----------|------|------| -| {MainClass} | Class | \\\`src/index.ts\\\` | {N} | {Central orchestrator} | -| {createX} | Function | \\\`src/utils.ts\\\` | {N} | {Factory pattern} | -| {Config} | Interface | \\\`src/types.ts\\\` | {N} | {Configuration contract} | - -### Module Dependencies - -\\\`\\\`\\\` -{entry} ──imports──> {core/} - │ │ - └──imports──> {utils/} <──imports── {features/} -\\\`\\\`\\\` - - -**Skip CODE MAP if**: LSP unavailable OR project too small (<10 files) OR no clear module boundaries. - ## CONVENTIONS - -{ONLY deviations from standard - skip generic advice} - -- **{rule}**: {specific detail} +{ONLY deviations from standard} ## ANTI-PATTERNS (THIS PROJECT) - -{Things explicitly forbidden HERE} - -- **{pattern}**: {why} → {alternative} +{Explicitly forbidden here} ## UNIQUE STYLES - -{Project-specific coding styles} - -- **{style}**: {how different} +{Project-specific} ## COMMANDS - \\\`\\\`\\\`bash -{dev-command} -{test-command} -{build-command} +{dev/test/build} \\\`\\\`\\\` ## NOTES - -{Gotchas, non-obvious info} +{Gotchas} \`\`\` -### Quality Gates +**Quality gates**: 50-150 lines, no generic advice, no obvious info. -- [ ] Size: 50-150 lines -- [ ] No generic advice ("write clean code") -- [ ] No obvious info ("tests/ has tests") -- [ ] Every item is project-specific +### Subdirectory AGENTS.md (Parallel) -**Mark "p3-root" as completed.** +Launch document-writer agents for each location: + +\`\`\` +for loc in AGENTS_LOCATIONS (except root): + background_task(agent="document-writer", 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: Generate Subdirectory AGENTS.md +## Phase 4: Review & Deduplicate -**Mark "p4-subdirs" as in_progress.** +**Mark "review" as in_progress.** -For each location in AGENTS_LOCATIONS (except root), launch **parallel document-writer agents**: +For each generated file: +- Remove generic advice +- Remove parent duplicates +- Trim to size limits +- Verify telegraphic style -\`\`\`typescript -for (const loc of AGENTS_LOCATIONS.filter(l => l.path !== ".")) { - background_task({ - agent: "document-writer", - prompt: \\\` - Generate AGENTS.md for: \${loc.path} - - CONTEXT: - - Complexity reason: \${loc.reason} - - Parent AGENTS.md: ./AGENTS.md (already covers project overview) - - CRITICAL RULES: - 1. Focus ONLY on this directory's specific context - 2. NEVER repeat parent AGENTS.md content - 3. Shorter is better - 30-80 lines max - 4. Telegraphic style - sacrifice grammar - - REQUIRED SECTIONS: - - OVERVIEW (1 line: what this directory does) - - STRUCTURE (only if >5 subdirs) - - WHERE TO LOOK (directory-specific tasks) - - CONVENTIONS (only if DIFFERENT from root) - - ANTI-PATTERNS (directory-specific only) - - OUTPUT: Write to \${loc.path}/AGENTS.md - \\\` - }) -} -\`\`\` - -**Wait for all agents. Mark "p4-subdirs" as completed.** - ---- - -## Phase 5: Review & Deduplicate - -**Mark "p5-review" as in_progress.** - -### Validation Checklist - -For EACH generated AGENTS.md: - -| Check | Action if Fail | -|-------|----------------| -| Contains generic advice | REMOVE the line | -| Repeats parent content | REMOVE the line | -| Missing required section | ADD it | -| Over 150 lines (root) / 80 lines (subdir) | TRIM | -| Verbose explanations | REWRITE telegraphic | - -### Cross-Reference Validation - -\`\`\` -For each child AGENTS.md: - For each line in child: - If similar line exists in parent: - REMOVE from child (parent already covers) -\`\`\` - -**Mark "p5-review" as completed.** +**Mark "review" as completed.** --- @@ -387,31 +272,29 @@ For each child AGENTS.md: \`\`\` === init-deep Complete === -Files Generated: +Mode: {update | create-new} + +Files: ✓ ./AGENTS.md (root, {N} lines) ✓ ./src/hooks/AGENTS.md ({N} lines) - ✓ ./src/tools/AGENTS.md ({N} lines) -Directories Analyzed: {N} +Dirs Analyzed: {N} AGENTS.md Created: {N} -Total Lines: {N} +AGENTS.md Updated: {N} Hierarchy: ./AGENTS.md - ├── src/hooks/AGENTS.md - └── src/tools/AGENTS.md + └── src/hooks/AGENTS.md \`\`\` --- -## Anti-Patterns for THIS Command +## Anti-Patterns -- **Over-documenting**: Not every directory needs AGENTS.md -- **Redundancy**: Child must NOT repeat parent +- **Static agent count**: MUST vary agents based on project size/depth +- **Sequential execution**: MUST parallel (explore + LSP 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 -- **Sequential execution**: MUST use parallel agents -- **Deep nesting**: Rarely need AGENTS.md at depth 4+ -- **Verbose style**: "This directory contains..." → just list it -- **Ignoring LSP**: If LSP available, USE IT - semantic analysis > text grep -- **LSP without fallback**: Always have explore agent backup if LSP unavailable -- **Over-referencing**: Don't trace refs for EVERY symbol - focus on exports only` +- **Verbose style**: Telegraphic or die`