codymaster 7.0.2 → 7.0.3

package/skills/cm-code-review/SKILL.md

@@ -118,7 +118,7 @@ When implementation is complete and all tests pass.
 3. **Execute chosen option**
 
 4. **Cleanup:**
-   - Remove worktree if using `cm-git-worktrees`
+   - Remove the isolated worktree/workspace if your execution flow created one
    - Delete feature branch if merged
    - Update task tracking
 
@@ -154,7 +154,7 @@ After processing review feedback, ALWAYS update `.cm/CONTINUITY.md`:
 | `cm-execution` | Reviews after each task in execution |
 | `cm-quality-gate` | Tests must pass before finishing branch |
 | `cm-identity-guard` | Before git push |
-| `cm-git-worktrees` | Cleanup worktree after completion |
+| `cm-execution` | Cleanup isolated workspace after completion |
 
 ## Karpathy Discipline — Review Checklist
 

package/skills/cm-codeintell/SKILL.md

@@ -1,7 +1,14 @@
 ---
 name: cm-codeintell
-description: "Unified code intelligence — Skeleton Index (zero-dep, <4s) + AST knowledge graph (CodeGraph) + architecture diagrams (Mermaid) + smart context builder. Pre-indexes code structure so AI agents understand any codebase instantly. 95% token compression for onboarding. 30% fewer tokens for deep analysis."
+description: Unified code intelligence — routes to Skeleton Index, CodeGraph, Architecture Diagram, or Smart Context Builder based on task shape. Loads deep refs on demand.
 token_budget: 1500
+token_core: 520
+token_refs:
+  layer-0-skeleton: 820
+  layer-1-codegraph: 980
+  layer-2-architecture: 620
+  layer-3-context-builder: 760
+  integration-workflows: 520
 compressed: true
 deprecated: false
 ---
@@ -9,599 +16,59 @@ deprecated: false
 # Code Intelligence — Structural Understanding for AI Agents
 
 ## TL;DR
-- **Use to** index codebase for fast structural understanding
-- **Outputs**: skeleton index, AST graph, Mermaid diagrams
-- **Token saving**: ~95% for onboarding, ~30% for deep analysis
-- **Next**: cm-planning or cm-debugging
+- **Use to** index a codebase for fast structural understanding
+- **Layers**: skeleton, code graph, architecture diagram, smart context
+- **Default**: start from the lightest useful layer
+- **Next**: `cm-planning`, `cm-debugging`, or `cm-execution`
 
-> **Stop scanning. Start querying.** Skeleton Index (<4s, zero deps) + AST graph + architecture diagrams = instant code understanding.
-> Inspired by [CodeGraph](https://github.com/colbymchenry/codegraph) + [GitDiagram](https://github.com/ahmedkhaleel2004/gitdiagram).
-> TRIZ-optimized: 10 inventive principles applied.
+> Stop scanning. Start querying. Load only the layer the task actually needs.
 
 ## When to Use
+- Understanding a medium or large codebase
+- Tracing callers, callees, or impact before edits
+- Building focused context for planning, debugging, or execution
+- Auto-triggering structural understanding during project setup
 
-**ALWAYS for medium-to-large projects.** This is infrastructure, not an action skill.
+## Choose a Layer
 
-- **Auto-triggered by:** `cm-start` Step 0.7 (project init) — **ALWAYS runs Layer 0**
-- **Manually triggered for:** "understand this codebase", "what calls X?", "what breaks if I change Y?"
-- **Skip when:** NEVER — Layer 0 (Skeleton) works on any project size
-
-### Detection Thresholds (Auto-Trigger)
-
-```
-TRIGGER if ANY of these are true:
-  → Project has >50 source files
-  → User wants to refactor or re-code an existing project
-  → User says "understand the codebase" / "what does this do?"
-  → cm-execution encounters >3 grep/glob calls for one task
-  → cm-debugging needs callers/callees to trace a bug
-```
-
----
-
-## Architecture: 4 Layers
-
-```
-┌──────────────────────────────────────────────────────────────────────────┐
-│                           cm-codeintell                                 │
-├──────────────────┬──────────────────┬──────────────────┬────────────────┤
-│  LAYER 0         │  LAYER 1         │  LAYER 2         │  LAYER 3       │
-│  Skeleton Index  │  Code Graph      │  Architecture    │  Smart Context │
-│  (Instant)       │  (Structure)     │  Diagram (Visual)│  (Synthesis)   │
-├──────────────────┼──────────────────┼──────────────────┼────────────────┤
-│ grep/find/awk    │ tree-sitter AST  │ File tree + LLM  │ All layers +   │
-│ → skeleton.md    │ → SQLite graph   │ → Mermaid.js     │ qmd → focused  │
-│ (~5K tokens)     │ → MCP server     │ → .cm/ storage   │ context packet │
-├──────────────────┼──────────────────┼──────────────────┼────────────────┤
-│ ZERO deps        │ codegraph_*      │ Auto-generated   │ Feeds: exec,   │
-│ <4 seconds       │ MCP tools        │ at project init  │ plan, debug    │
-│ ANY project size │ 50+ files        │ 20+ files        │ All consumers  │
-└──────────────────┴──────────────────┴──────────────────┴────────────────┘
-```
-
-### TRIZ Principles Applied
-
-| # | Principle | How Applied |
-|---|-----------|-------------|
-| **#1** Segmentation | 4 independent layers — each usable alone |
-| **#2** Taking Out | Extract only signatures, discard function bodies |
-| **#5** Merging | CodeGraph + GitDiagram + Skeleton → one unified skill |
-| **#10** Prior Action | Pre-index at project init, not at query time |
-| **#13** Inversion | Code summarizes ITSELF to agent (push, not pull) |
-| **#15** Dynamicity | Adaptive: skeleton (<20) vs graph (>50) vs full (>200) |
-| **#25** Self-Service | Auto-detect project size → auto-select intelligence level |
-| **#28** Mechanics Substitution | Replace file reading (slow) with pattern matching (fast) |
-| **#35** Parameter Changes | Unit: file content → function signature → 95% compression |
-| **#40** Composite | One skill = skeleton + graph + diagrams + context builder |
-
----
-
-## Layer 0: Skeleton Index (Instant — Zero Dependencies)
-
-> **Purpose:** Lightning-fast grep-based extraction of function signatures, class definitions, exports, and module boundaries. Produces a compact `.cm/skeleton.md` that gives the agent instant understanding of any codebase.
-
-### How It Works
-
-```
-1. SCAN     → find all source files (14 languages supported)
-2. EXTRACT  → grep for function/class/export signatures only
-3. GROUP    → organize by directory (module boundaries)
-4. CAP      → limit per-dir (15 files) + total (600 lines)
-5. OUTPUT   → .cm/skeleton.md (~5K tokens for 600-file project)
-```
-
-### Usage
-
-```bash
-# Run from project root
-bash scripts/index-codebase.sh
-
-# Custom paths
-bash scripts/index-codebase.sh /path/to/project /path/to/output.md
-```
-
-### What It Extracts (Per Language)
-
-| Language | Patterns Extracted |
-|----------|-------------------|
-| TypeScript/JavaScript | `export`, `function`, `class`, `interface`, `type`, `enum`, `const =`, routes |
-| Python | `def`, `async def`, `class`, `@app.route`, `from...import` |
-| Go | `func`, `type...struct`, `type...interface`, `package` |
-| Rust | `pub fn`, `struct`, `enum`, `impl`, `trait`, `mod` |
-| Java/Kotlin | `class`, `interface`, `fun`, `data class`, `package` |
-| PHP | `function`, `class`, `interface`, `trait`, `namespace` |
-| Ruby | `def`, `class`, `module` |
-| C/C++ | function declarations, `struct`, `class`, `typedef`, `#define` |
-| Swift | `func`, `class`, `struct`, `protocol`, `extension` |
-
-### Output Format
-
-```markdown
-# 🦴 Skeleton Index: my-project
-
-| Meta | Value |
-|------|-------|
-| Source Files | 127 |
-| Languages | typescript(89) python(38) |
-| Framework | next.js+cloudflare |
-
-## Entry Points
-- `src/index.ts`
-- `app/layout.tsx`
-
-## Directory Structure
-(compact tree, depth 2)
-
-## Code Skeleton
-### `src/auth/`
-**AuthService.ts**
-‍‍‍
-3:export class AuthService
-5:export async function login(email, password)
-12:export function validateToken(token)
-‍‍‍
-
-### `src/api/`
-**routes.ts**
-‍‍‍
-8:export const router
-15:router.get('/users'
-22:router.post('/auth'
-‍‍‍
-```
-
-### Compression Stats
-
-```
-┌──────────────────┬────────────┬────────────────┬──────────────┐
-│ Project Size     │ Raw Tokens │ Skeleton Tokens│ Compression  │
-├──────────────────┼────────────┼────────────────┼──────────────┤
-│ 50 files (small) │ ~20,000    │ ~1,500         │ 92.5%        │
-│ 200 files (med)  │ ~80,000    │ ~3,000         │ 96.3%        │
-│ 600 files (large)│ ~240,000   │ ~5,000         │ 97.9%        │
-└──────────────────┴────────────┴────────────────┴──────────────┘
-```
-
-### Agent Protocol
-
-```
-AT SESSION START:
-  1. Check if .cm/skeleton.md exists
-  2. IF exists → read it (~5K tokens) → instant codebase understanding
-  3. IF not exists → run: bash scripts/index-codebase.sh
-  4. Use skeleton to:
-     → Know what functions exist and where
-     → Understand module boundaries
-     → Navigate to the right file for any task
-     → Skip grep/list_dir when exploring
-
-WHEN TO RE-GENERATE:
-  → After major refactoring (>20 files changed)
-  → After branch switch
-  → When skeleton is >24h old
-  → User requests: "re-index the codebase"
-```
-
----
-
-## Layer 1: Code Graph (Structure)
-
-> **Purpose:** Pre-indexed AST-based knowledge graph. Functions, classes, imports, call relationships — all queryable instantly.
-
-### Setup
-
-```bash
-# Install CodeGraph (one-time)
-npx @colbymchenry/codegraph
-
-# Initialize for current project
-codegraph init .
-
-# Index the codebase (tree-sitter AST extraction)
-codegraph index .
-```
-
-### MCP Server Setup
-
-Add to your MCP config (`.mcp.json`, `claude_desktop_config.json`, etc.):
-
-```json
-{
-  "mcpServers": {
-    "codegraph": {
-      "command": "codegraph",
-      "args": ["serve"]
-    }
-  }
-}
-```
-
-### Key MCP Tools
-
-| Tool | What It Does | Replaces |
-|------|-------------|----------|
-| `codegraph_context(task)` | Build focused context for a task | Multiple grep + view_file calls |
-| `codegraph_search(query)` | Find symbols by name or meaning | `grep -r "pattern"` |
-| `codegraph_callers(symbol)` | What calls this function? | Manual file-by-file search |
-| `codegraph_callees(symbol)` | What does this function call? | Reading entire function + tracing |
-| `codegraph_impact(symbol)` | What breaks if I change this? | Nothing (CM couldn't do this) |
-| `codegraph_files(path)` | Project structure with metadata | `list_dir` recursive + `view_file` |
-| `codegraph_node(symbol)` | Full details of one symbol | `view_file` + manual parsing |
-
-### When Agents Use These Tools
-
-```
-INSTEAD OF:                          USE:
-─────────────────────────────────    ─────────────────────────
-grep -r "UserService" src/           codegraph_search("UserService")
-list_dir + view_file × 10           codegraph_context("implement auth")
-"What calls validatePayment?"       codegraph_callers("validatePayment")
-"What if I change this class?"      codegraph_impact("UserService", depth=2)
-list_dir src/ --recursive            codegraph_files("src/", format="tree")
-```
-
-### Keeping Index Fresh
-
-```
-AUTO-SYNC (built-in):
-  → CodeGraph hooks auto-sync when files change (if hooks installed)
-
-MANUAL SYNC (if hooks not installed):
-  → codegraph sync .
-
-WHEN TO RE-INDEX:
-  → After major refactoring (>20 files changed)
-  → After branch switch
-  → When codegraph_status reports stale index
-
-AI RULE: Before starting any task, check:
-  → codegraph status .
-  → If stale → codegraph sync . → then proceed
-```
-
----
-
-## Layer 2: Architecture Diagram (Visual)
-
-> **Purpose:** Auto-generated Mermaid.js architecture diagram from project structure. See the big picture at a glance.
-
-### Generation Process
-
-```
-1. EXTRACT  → Read file tree structure (codegraph_files or list_dir)
-2. ANALYZE  → Identify key directories, patterns, entry points
-3. GENERATE → Produce Mermaid.js diagram showing:
-              - Major modules/directories
-              - Key relationships (imports, API boundaries)
-              - Entry points (main, routes, handlers)
-              - Data flow direction
-4. STORE    → Save to .cm/architecture.mmd
-5. RENDER   → Display inline or via Pencil MCP
-```
-
-### Diagram Template
-
-When generating the architecture diagram, use this Mermaid structure:
-
-```markdown
-## Architecture Diagram
-
-​```mermaid
-graph TD
-    subgraph "Frontend"
-        A[pages/] --> B[components/]
-        B --> C[hooks/]
-        C --> D[utils/]
-    end
-
-    subgraph "Backend"
-        E[routes/] --> F[controllers/]
-        F --> G[services/]
-        G --> H[models/]
-    end
-
-    subgraph "Infrastructure"
-        I[config/]
-        J[middleware/]
-        K[database/]
-    end
-
-    A -->|API calls| E
-    G --> K
-    J --> E
-​```
-```
-
-### When to Generate
-
-```
-AUTO-GENERATE at:
-  → cm-start Step 0.5 (project init)
-  → cm-brainstorm-idea Phase 1a (codebase scan)
-  → First time running cm-codeintell on a project
-
-RE-GENERATE when:
-  → Major architectural change (new module, new service)
-  → User requests: "update the architecture diagram"
-  → >30 files added/removed since last generation
-
-STORE at:
-  → .cm/architecture.mmd (Mermaid source)
-  → Include in proposal.md when relevant
-```
-
-### Integration with Pencil MCP
-
-If Pencil MCP is available, render the diagram visually:
-
-```
-1. Generate Mermaid code → .cm/architecture.mmd
-2. If pencil MCP available → render as visual node
-3. If not → display Mermaid code inline (agents can parse it)
-```
-
----
-
-## Layer 3: Smart Context Builder (Synthesis)
-
-> **Purpose:** Combine graph data + diagram + text search into a focused context packet for any task.
-
-### Context Building Protocol
-
-When any CM skill needs to understand the codebase for a specific task:
-
-```
-1. QUERY GRAPH     → codegraph_context(task, maxNodes=20)
-                     Returns: entry points, related symbols, code snippets
-
-2. CHECK DIAGRAM   → Read .cm/architecture.mmd
-                     Identify which module/layer the task affects
-
-3. SEARCH DOCS     → IF qmd available: qmd query "task description"
-                     Returns: relevant documentation, past decisions
-
-4. COMPOSE PACKET  → Merge results into a structured context:
-                     {
-                       "task": "...",
-                       "affected_modules": ["..."],
-                       "entry_points": ["..."],
-                       "related_symbols": ["..."],
-                       "impact_radius": ["..."],
-                       "relevant_docs": ["..."],
-                       "architecture_context": "..."
-                     }
-
-5. FEED DOWNSTREAM → Pass context packet to requesting skill
-```
-
-### Adaptive Intelligence Levels
-
-```
-┌──────────────┬────────────┬─────────────────────────────────────────────────┐
-│ Project Size │ Level      │ What Activates                                  │
-├──────────────┼────────────┼─────────────────────────────────────────────────┤
-│ ANY size     │ SKELETON   │ Skeleton Index always runs (Layer 0)             │
-│ <20 files    │ MINIMAL    │ Skeleton only (no graph, no diagram)             │
-│ 20-50 files  │ LITE       │ Skeleton + architecture diagram                  │
-│ 50-200 files │ STANDARD   │ Skeleton + CodeGraph + diagram                   │
-│ >200 files   │ FULL       │ Skeleton + CodeGraph + diagram + qmd             │
-└──────────────┴────────────┴─────────────────────────────────────────────────┘
-
-Skeleton Index ALWAYS runs — it's the foundation for all levels.
-Detection is automatic at cm-start Step 0.7.
-User can override: "Use FULL intelligence mode"
-```
-
----
-
-## Integration with CodyMaster Skills
-
-### cm-start (Step 0.5 — enhanced)
-
-```
-EXISTING Step 0.5: Skill Coverage Check
-NEW addition:
-
-  0.5b. Code Intelligence Setup:
-    1. Count source files → determine intelligence level
-    2. IF level >= LITE:
-       → Auto-generate architecture diagram → .cm/architecture.mmd
-    3. IF level >= STANDARD:
-       → Check if CodeGraph installed: codegraph status
-       → IF not installed → suggest: "npx @colbymchenry/codegraph"
-       → IF installed but not indexed → codegraph init . && codegraph index .
-       → IF indexed → codegraph sync . (ensure fresh)
-    4. IF level >= FULL:
-       → Also check qmd (cm-deep-search detection)
-    5. Log intelligence level to CONTINUITY.md
-```
-
-### cm-execution (Pre-flight — enhanced)
-
-```
-EXISTING Pre-flight: Skill Coverage Audit
-NEW addition:
-
-  Pre-flight Step 2: Code Context Loading
-    IF codegraph available:
-      → For each task in current batch:
-        → context = codegraph_context(task.description, maxNodes=15)
-        → Inject context into agent prompt
-      → For tasks modifying shared code:
-        → impact = codegraph_impact(symbol, depth=2)
-        → If impact.affected > 10 files → WARN: "High impact change"
-
-    Result: Agents start with pre-loaded context instead of exploring
-```
-
-### cm-planning (Impact Analysis — new)
-
-```
-NEW addition to Phase A:
-
-  Before writing implementation plan:
-    1. For each proposed change:
-       → codegraph_impact(affected_symbol) → list affected files
-    2. If total impact > 20 files:
-       → Flag as HIGH RISK in plan
-       → Recommend cm-tdd coverage for all impacted callers
-    3. Include impact summary in OpenSpec `design.md`
 ```
+Need instant codebase orientation with zero extra setup?
+└─ YES → Layer 0: Skeleton Index
 
-### cm-debugging (Trace Analysis — enhanced)
+Need symbol search, callers/callees, or impact analysis?
+└─ YES → Layer 1: Code Graph
 
-```
-EXISTING Phase 2: Hypothesis Formation
-NEW enhancement:
-
-  IF codegraph available:
-    1. From error stack trace → extract function name
-    2. codegraph_callers(function) → who calls this?
-    3. codegraph_callees(function) → what does it call?
-    4. codegraph_impact(function) → what else is affected?
-    5. Use call chain to narrow hypotheses
-
-  Result: Root cause found in 1-2 queries instead of 5-10 grep calls
-```
-
-### cm-brainstorm-idea (Phase 1a — enhanced)
-
-```
-EXISTING Phase 1a: Codebase Scan
-NEW enhancement:
-
-  1. Read .cm/architecture.mmd for instant overview
-  2. IF codegraph available:
-     → codegraph_files(".", format="tree", includeMetadata=true)
-     → Summary: X symbols, Y edges, Z files
-  3. Present architecture diagram to user in Discovery output
-  4. Use graph to identify:
-     → Most connected modules (highest coupling)
-     → Isolated modules (candidates for parallel work)
-     → Dead code (unreferenced symbols)
-```
-
----
-
-## File Storage
-
-```
-.cm/
-├── skeleton.md               # Skeleton Index output (Layer 0)
-├── architecture.mmd          # Mermaid architecture diagram
-├── codegraph-meta.json       # Graph metadata (last indexed, stats)
-├── CONTINUITY.md             # (existing) — updated with intelligence level
-├── learnings.json            # (existing)
-└── decisions.json            # (existing)
-
-.codegraph/                   # CodeGraph's own directory (auto-created)
-├── codegraph.db              # SQLite graph database
-└── config.json               # CodeGraph configuration
-```
-
-### codegraph-meta.json Format
-
-```json
-{
-  "intelligenceLevel": "STANDARD",
-  "lastIndexed": "2026-03-25T22:25:00+07:00",
-  "stats": {
-    "sourceFiles": 127,
-    "symbols": 387,
-    "edges": 1204,
-    "languages": ["typescript", "javascript"]
-  },
-  "diagramGenerated": "2026-03-25T22:25:30+07:00",
-  "codegraphVersion": "1.0.0"
-}
-```
-
----
-
-## Lifecycle Position
+Need a visual system / module map?
+└─ YES → Layer 2: Architecture Diagram
 
-```
-cm-project-bootstrap → cm-codeintell (auto) → cm-brainstorm-idea → cm-planning → cm-execution
-      (create)          (index + diagram)         (analyze)           (plan)        (implement)
-                              ↑                                         ↓
-                         cm-debugging ←──── cm-quality-gate ←──── cm-tdd
-                        (trace callers)     (verify)            (test first)
-```
-
-### Memory System (Updated)
-
-```
-Tier 1: SENSORY        → Temporary session variables
-Tier 2: WORKING        → CONTINUITY.md (~500 words)
-Tier 3: LONG-TERM      → learnings.json, decisions.json
-Tier 4: SEMANTIC TEXT   → qmd (BM25 + vector over docs/text)
-Tier 5: STRUCTURAL     → CodeGraph (AST symbols + call graph)  ← NEW
+Need a focused context packet for another skill or agent?
+└─ YES → Layer 3: Smart Context Builder
 ```
 
----
+| Layer | Summary | Load |
+|---|---|---|
+| 0 | Grep-based skeleton index for instant orientation | `references/layer-0-skeleton.md` |
+| 1 | AST graph and symbol-query workflow | `references/layer-1-codegraph.md` |
+| 2 | Mermaid architecture generation | `references/layer-2-architecture.md` |
+| 3 | Synthesized focused context for downstream work | `references/layer-3-context-builder.md` |
 
-## Integration Table
+## Conditional References
+- Load only the target layer reference for the current task.
+- Load `references/integration-workflows.md` only when wiring `cm-codeintell` into `cm-start`, `cm-planning`, `cm-debugging`, or `cm-execution`.
 
-| Skill | Relationship |
-|-------|-------------|
-| `cm-start` | TRIGGERED AT: Step 0.5 — auto-detect, auto-setup |
-| `cm-execution` | CONSUMER: pre-flight context loading + impact warnings |
-| `cm-planning` | CONSUMER: impact analysis for change proposals |
-| `cm-debugging` | CONSUMER: caller/callee tracing for root cause |
-| `cm-brainstorm-idea` | CONSUMER: architecture diagram + graph summary |
-| `cm-deep-search` | COMPLEMENT: qmd = text search, codegraph = structural |
-| `cm-continuity` | STORES: intelligence level + graph metadata |
-| `cm-tdd` | CONSUMER: know all callers before refactoring |
-| `cm-safe-deploy` | CONSUMER: impact analysis as pre-deploy gate |
-| `cm-dockit` | CONSUMER: auto-generate architecture docs from graph |
-
----
+## Integration
+| Skill | How `cm-codeintell` helps |
+|---|---|
+| `cm-start` | bootstrap structural context early |
+| `cm-planning` | impact analysis and component boundaries |
+| `cm-debugging` | trace callers, callees, and failure paths |
+| `cm-execution` | pre-flight context for focused implementation |
 
 ## Rules
-
-```
-✅ DO:
-- Auto-detect project size and select appropriate intelligence level
-- Keep graph index fresh (sync before major tasks)
-- Use codegraph_context INSTEAD of grep/glob for code exploration
-- Generate architecture diagram at project init
-- Store metadata in .cm/codegraph-meta.json
-- Feed context to downstream skills (execution, planning, debugging)
-
-❌ DON'T:
-- Force CodeGraph on tiny projects (<20 files)
-- Skip freshness checks (stale index worse than no index)
-- Use codegraph as REPLACEMENT for qmd (they complement each other)
-- Assume codegraph is installed — always check first
-- Generate diagrams without validating Mermaid syntax
-- Store sensitive code in architecture diagrams
-```
-
----
-
-## Requirements
-
-```
-Layer 0 (Skeleton Index):
-  - ZERO dependencies (grep, find, awk — standard POSIX)
-  - Works on any OS (macOS, Linux, WSL)
-  - <4 seconds for 600-file projects
-
-Layer 1 (CodeGraph):
-  - Node.js 18+ (for tree-sitter binaries)
-  - npx @colbymchenry/codegraph (one-time install)
-  - ~50MB disk for SQLite + embeddings per project
-
-Layer 2 (Diagrams):
-  - No additional dependencies (uses agent's LLM)
-  - Mermaid.js knowledge (built into agent)
-
-Layer 3 (Smart Context):
-  - Layer 0 required (always available)
-  - Layers 1 + 2 optional upgrades
-  - Optional: qmd for text search complement
-```
+- Start from the lightest layer that answers the question.
+- Prefer Layer 0 when simple orientation is enough.
+- Regenerate or refresh indexes after major structural changes.
+- Do not pay for deep graph or context synthesis unless the task needs it.
 
 ## The Bottom Line
-
-**Skeleton Index = instant understanding. Code graph = deep meaning. Architecture diagrams = big picture. Together = AI that truly understands your code.**
+**Pick the cheapest layer that answers the question, then load deeper only when needed.**

package/skills/cm-codeintell/references/integration-workflows.md

@@ -0,0 +1,23 @@
+# Integration Workflows
+
+> Load this only when `cm-codeintell` is being wired into another skill flow.
+
+## `cm-start`
+- Run Layer 0 early for baseline project orientation
+- Add deeper layers only when project size or task complexity justifies it
+
+## `cm-planning`
+- Use Layer 0 or Layer 1 to map boundaries and likely impacted files
+- Use Layer 2 when architecture communication matters
+- Use Layer 3 for a planning-ready context packet
+
+## `cm-debugging`
+- Use Layer 1 for caller/callee tracing and impact
+- Use Layer 3 when the bug spans multiple modules or runtime paths
+
+## `cm-execution`
+- Use Layer 1 or Layer 3 as pre-flight context
+- Keep execution prompts focused on touched files and interfaces
+
+## Rule
+`cm-codeintell` is infrastructure, not a destination. Use it to reduce downstream search cost and ambiguity.