agileflow 3.3.0 → 3.4.1

package/src/core/commands/ideate/new.md

@@ -1,6 +1,6 @@
 ---
 description: Generate categorized improvement ideas using multi-expert analysis
-argument-hint: "[SCOPE=all|security|perf|code|ux] [DEPTH=quick|deep|ultradeep] [OUTPUT=report|stories|both] [HISTORY=true|false] [FOCUS=IDEA-XXXX]"
+argument-hint: "[SCOPE=all|security|perf|code|ux] [DEPTH=quick|deep|ultradeep|extreme] [OUTPUT=report|stories|both] [HISTORY=true|false] [FOCUS=IDEA-XXXX] [MODEL=haiku|sonnet|opus]"
 compact_context:
   priority: high
   preserve_rules:
@@ -9,7 +9,7 @@ compact_context:
     - "CRITICAL: Wait for all results before synthesis (use TaskOutput with block=true)"
     - "CRITICAL: Confidence scoring varies by depth: quick/deep (HIGH=2+ agree) | ultradeep (HIGH=3+ agree)"
     - "CRITICAL: Check ideation index for duplicates - show NEW vs RECURRING vs IMPLEMENTED"
-    - "MUST parse arguments: SCOPE (all/security/perf/code/ux) | DEPTH (quick/deep/ultradeep) | OUTPUT (report/stories/both) | HISTORY (true/false) | FOCUS (IDEA-XXXX)"
+    - "MUST parse arguments: SCOPE (all/security/perf/code/ux) | DEPTH (quick/deep/ultradeep) | OUTPUT (report/stories/both) | HISTORY (true/false) | FOCUS (IDEA-XXXX) | MODEL (haiku/sonnet/opus)"
     - "FOCUS mode: All experts analyze the same recurring idea - generate Implementation Brief"
     - "MUST categorize by domain: Security, Performance, Code Quality, UX, Testing, API/Architecture"
     - "MUST estimate effort for each idea: High/Medium/Low impact"
@@ -21,6 +21,7 @@ compact_context:
     - output_mode
     - history_enabled
     - focus_idea
+    - model
     - selected_experts
     - ideas_generated
     - new_ideas
@@ -194,27 +195,36 @@ Be SPECIFIC - reference actual file paths, function names, and code patterns.
 ```
 /agileflow:ideate:new SCOPE=all DEPTH=quick OUTPUT=report
 /agileflow:ideate:new FOCUS=IDEA-0023   # Deep dive into specific idea
+/agileflow:ideate:new DEPTH=ultradeep MODEL=opus   # Ultradeep with Opus in tmux sessions
 ```
 
 **What It Does**: Deploy 4-15 domain experts → Each generates 3-5 ideas → Synthesize with confidence scoring → Categorized report
 
 **Arguments**:
 - `SCOPE=all|security|perf|code|ux` (default: all)
-- `DEPTH=quick|deep|ultradeep` (default: quick) — ultradeep uses 13 experts for ~65 ideas
+- `DEPTH=quick|deep|ultradeep` (default: quick) — ultradeep spawns 13 experts as tmux sessions
 - `OUTPUT=report|stories|both` (default: report)
+- `MODEL=haiku|sonnet|opus` (default: haiku) — model for expert subagents
 
 ### Tool Usage Examples
 
-**Task** (deploy expert in parallel):
+**Task** (deploy expert in parallel - include `model` if MODEL specified):
 ```xml
 <invoke name="Task">
 <parameter name="description">Security ideation analysis</parameter>
 <parameter name="prompt">Generate 3-5 specific improvement ideas for this codebase from a SECURITY perspective...</parameter>
 <parameter name="subagent_type">agileflow-security</parameter>
+<parameter name="model">opus</parameter>
 <parameter name="run_in_background">true</parameter>
 </invoke>
 ```
 
+**Ultradeep** (spawn tmux sessions):
+```bash
+node .agileflow/scripts/spawn-audit-sessions.js --audit=ideate --target=. --focus=all --model=opus --dry-run
+node .agileflow/scripts/spawn-audit-sessions.js --audit=ideate --target=. --focus=all --model=opus
+```
+
 **TaskOutput** (collect results):
 ```xml
 <invoke name="TaskOutput">
@@ -255,40 +265,46 @@ Be SPECIFIC - reference actual file paths, function names, and code patterns.
                             ▼
 ┌─────────────────────────────────────────────────────────────┐
 │              IDEATION ORCHESTRATOR                          │
-│  1. Parse SCOPE to determine which experts                  │
-│  2. Deploy 4-13 experts IN PARALLEL (13 for ultradeep)      │
+│  1. Parse SCOPE, DEPTH, MODEL                               │
+│  2a. quick/deep: Deploy 4-13 experts via Task (in-process)  │
+│  2b. ultradeep: Spawn 13 tmux sessions via spawn-audit      │
 │  3. Each expert generates 3-5 improvement ideas             │
 │  4. Collect and synthesize with confidence scoring          │
 │  5. Generate categorized report                             │
 └─────────────────────────────────────────────────────────────┘
                             │
-        ┌───────────────────┼───────────────────┐
-        ▼                   ▼                   ▼
-┌───────────┐       ┌───────────┐       ┌───────────┐
-│  Security │       │Performance│       │  Refactor │
-│  Expert   │       │  Expert   │       │  Expert   │
-│           │       │           │       │           │
-│ 3-5 ideas │       │ 3-5 ideas │       │ 3-5 ideas │
-└───────────┘       └───────────┘       └───────────┘
-        │                   │                   │
-        └───────────────────┼───────────────────┘
-                            ▼
+              ┌─────────────┴─────────────┐
+              ▼                           ▼
+     [quick/deep]                  [ultradeep]
+   Task calls (in-proc)        tmux sessions (isolated)
+        ┌───────┼───────┐        ┌───────┼───────┐
+        ▼       ▼       ▼        ▼       ▼       ▼
+┌───────────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐
+│  Security │ │Perf │ │ ... │ │ Sec │ │Perf │ │ ... │ x13
+│ MODEL=X   │ │     │ │     │ │     │ │     │ │     │
+│ 3-5 ideas │ │     │ │     │ │     │ │     │ │     │
+└───────────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘
+        │         │       │        │       │       │
+        └─────────┴───────┘        └───────┴───────┘
+                  │                        │
+                  └────────────┬───────────┘
+                               ▼
 ┌─────────────────────────────────────────────────────────────┐
 │                   SYNTHESIS ENGINE                          │
-│  • Find overlapping ideas (HIGH CONFIDENCE)                 │
-│  • Flag unique insights with evidence (MEDIUM)              │
-│  • Discard vague suggestions (excluded)                     │
-│  • Categorize by domain                                     │
-│  • Estimate effort for each idea                            │
+│  - Find overlapping ideas (HIGH CONFIDENCE)                 │
+│  - Flag unique insights with evidence (MEDIUM)              │
+│  - Discard vague suggestions (excluded)                     │
+│  - Categorize by domain                                     │
+│  - Estimate effort for each idea                            │
 └─────────────────────────────────────────────────────────────┘
-                            │
-                            ▼
+                               │
+                               ▼
 ┌─────────────────────────────────────────────────────────────┐
 │                   IDEATION REPORT                           │
-│  📊 Total Ideas: X (High: Y, Medium: Z)                     │
-│  🎯 High-Confidence Improvements (agreed by 2+ experts)     │
-│  💡 Medium-Confidence Opportunities (single expert)         │
-│  📋 Suggested Stories (if OUTPUT=stories)                   │
+│  Total Ideas: X (High: Y, Medium: Z)                        │
+│  High-Confidence Improvements (agreed by 2+/3+ experts)     │
+│  Medium-Confidence Opportunities (single expert)            │
+│  Suggested Stories (if OUTPUT=stories)                       │
 └─────────────────────────────────────────────────────────────┘
 ```
 
@@ -316,19 +332,92 @@ Parse the input arguments:
 **DEPTH**:
 - `quick` (default): Each expert generates 3 ideas, focuses on high-impact only
 - `deep`: Each expert generates 5 ideas, includes lower-priority items
-- `ultradeep`: Deploy 13 experts (SCOPE=all) with 5 ideas each (~65 ideas), comprehensive coverage
+- `ultradeep`: Spawn each expert as a separate Claude Code session in tmux. Uses 13 experts (SCOPE=all) with 5 ideas each (~65 ideas). Requires tmux. Falls back to `deep` if tmux unavailable.
+
+> **Note**: `DEPTH=ultradeep` is recommended for comprehensive audits, pre-release reviews, or quarterly codebase assessments. Each expert gets its own Claude session with full context, producing higher-quality analysis than in-process subagents.
+
+**MODEL** (default: haiku):
+- `haiku`: Fast and cost-effective. Good for quick/deep ideation.
+- `sonnet`: Balanced quality and speed. Good default for deep analysis.
+- `opus`: Maximum quality. Recommended for ultradeep or high-stakes ideation.
 
-> **Note**: `DEPTH=ultradeep` is recommended for comprehensive audits, pre-release reviews, or quarterly codebase assessments. It deploys significantly more experts and takes longer to complete.
+> The MODEL parameter is passed to each expert subagent. For quick/deep depths, it sets the `model` parameter on Task calls. For ultradeep, it's passed to `spawn-audit-sessions.js` which sets `--model` on each tmux Claude session.
 
 **OUTPUT**:
 - `report` (default): Generate ideation report only
 - `stories`: Generate stories for high-confidence items
 - `both`: Report + stories
 
+### STEP 1.5: ULTRADEEP MODE (DEPTH=ultradeep)
+
+**If `DEPTH=ultradeep`**, use tmux-based session spawning instead of in-process Task calls:
+
+1. Show cost estimate:
+   ```bash
+   node .agileflow/scripts/spawn-audit-sessions.js --audit=ideate --target=. --focus=FOCUS_KEYS --model=MODEL --dry-run
+   ```
+2. Confirm with user before launching
+3. Spawn sessions (use `--json` to capture trace ID):
+   ```bash
+   node .agileflow/scripts/spawn-audit-sessions.js --audit=ideate --target=. --focus=FOCUS_KEYS --model=MODEL --json
+   ```
+   Parse the JSON output to get `traceId`. Example: `{"ok":true,"traceId":"abc123ef",...}`
+4. Wait for all analyzers to complete:
+   ```bash
+   node .agileflow/scripts/lib/tmux-audit-monitor.js wait TRACE_ID --timeout=1800
+   ```
+   - Exit 0 = all complete (JSON results on stdout)
+   - Exit 1 = timeout (partial results on stdout, `missing` array shows what's left)
+   - To check progress without blocking: `node .agileflow/scripts/lib/tmux-audit-monitor.js status TRACE_ID`
+   - To retry stalled analyzers: `node .agileflow/scripts/lib/tmux-audit-monitor.js retry TRACE_ID`
+5. Parse `results` array from the JSON output and proceed to STEP 4 (Synthesis).
+6. If tmux unavailable (spawn exits code 2), fall back to `DEPTH=deep` with warning
+
+**EXTREME mode** (DEPTH=extreme):
+Partition-based multi-agent audit. Instead of 1 expert per tmux window, the codebase is split into partitions and each partition runs ALL experts.
+1. Scan the target directory to understand the codebase structure:
+   - Use Glob to find top-level source directories
+   - Group related directories into 3-7 logical partitions (coherent domains: auth, api, ui, etc.)
+   - If user provided PARTITIONS=N (a number), split into exactly N partitions
+   - If user provided PARTITIONS=dir1,dir2,dir3, use those exact directories
+2. Show the partition plan and agent count to the user, confirm before launching:
+   Example: "5 partitions x 13 experts = 65 agents. Estimated cost: $X. Proceed?"
+3. Spawn sessions with partitions:
+   ```bash
+   node .agileflow/scripts/spawn-audit-sessions.js --audit=ideate --target=TARGET --depth=extreme --partitions=dir1,dir2,dir3 --focus=FOCUS_KEYS --model=MODEL --json
+   ```
+4. Wait and collect results (same as ultradeep - use tmux-audit-monitor.js)
+5. Run synthesis on combined results from all partitions (proceed to STEP 4)
+
+**PARTITIONS argument** (only used with DEPTH=extreme):
+| Value | Behavior |
+|-------|----------|
+| Not set | AI decides partitions (3-7 based on codebase size) |
+| `PARTITIONS=5` | AI creates exactly 5 partitions |
+| `PARTITIONS=src/auth,src/api,lib` | Use these exact directories |
+
+**FOCUS_KEYS mapping from SCOPE**:
+
+| SCOPE | FOCUS_KEYS for spawn-audit-sessions.js |
+|-------|---------------------------------------|
+| `all` | `all` (uses all 13 experts) |
+| `security` | `security,api,testing,compliance,monitoring` |
+| `perf` | `performance,database,api,monitoring,analytics` |
+| `code` | `refactor,testing,api,documentation,qa` |
+| `ux` | `ui,accessibility,api,analytics` |
+
+> **Skip to STEP 4** after ultradeep collection. Steps 2-3 are only for quick/deep modes.
+
+---
+
 ### STEP 2: DEPLOY EXPERTS IN PARALLEL
 
+**For quick/deep modes only** (ultradeep uses tmux sessions above).
+
 **CRITICAL**: Deploy ALL experts in a SINGLE message with multiple Task tool calls.
 
+**If MODEL is specified**, pass it to each Task call via the `model` parameter.
+
 Use this prompt template for each expert:
 
 ```
@@ -364,13 +453,14 @@ FORMAT each idea as:
 ---
 ```
 
-**Example deployment for SCOPE=all**:
+**Example deployment for SCOPE=all** (add `<parameter name="model">{MODEL}</parameter>` if MODEL is specified):
 
 ```xml
 <invoke name="Task">
 <parameter name="description">Security ideation</parameter>
 <parameter name="prompt">[prompt with domain=security]</parameter>
 <parameter name="subagent_type">agileflow-security</parameter>
+<parameter name="model">{MODEL}</parameter>
 <parameter name="run_in_background">true</parameter>
 </invoke>
 
@@ -378,6 +468,7 @@ FORMAT each idea as:
 <parameter name="description">Performance ideation</parameter>
 <parameter name="prompt">[prompt with domain=performance]</parameter>
 <parameter name="subagent_type">agileflow-performance</parameter>
+<parameter name="model">{MODEL}</parameter>
 <parameter name="run_in_background">true</parameter>
 </invoke>
 
@@ -385,6 +476,7 @@ FORMAT each idea as:
 <parameter name="description">Code quality ideation</parameter>
 <parameter name="prompt">[prompt with domain=refactor/code quality]</parameter>
 <parameter name="subagent_type">agileflow-refactor</parameter>
+<parameter name="model">{MODEL}</parameter>
 <parameter name="run_in_background">true</parameter>
 </invoke>
 
@@ -392,6 +484,7 @@ FORMAT each idea as:
 <parameter name="description">UX ideation</parameter>
 <parameter name="prompt">[prompt with domain=ui/ux]</parameter>
 <parameter name="subagent_type">agileflow-ui</parameter>
+<parameter name="model">{MODEL}</parameter>
 <parameter name="run_in_background">true</parameter>
 </invoke>
 
@@ -399,6 +492,7 @@ FORMAT each idea as:
 <parameter name="description">Testing ideation</parameter>
 <parameter name="prompt">[prompt with domain=testing]</parameter>
 <parameter name="subagent_type">agileflow-testing</parameter>
+<parameter name="model">{MODEL}</parameter>
 <parameter name="run_in_background">true</parameter>
 </invoke>
 
@@ -406,107 +500,42 @@ FORMAT each idea as:
 <parameter name="description">API/Architecture ideation</parameter>
 <parameter name="prompt">[prompt with domain=api/architecture]</parameter>
 <parameter name="subagent_type">agileflow-api</parameter>
+<parameter name="model">{MODEL}</parameter>
 <parameter name="run_in_background">true</parameter>
 </invoke>
 ```
 
-**Example deployment for SCOPE=all DEPTH=ultradeep** (13 experts):
-
-```xml
-<!-- Deploy ALL 13 experts in a SINGLE message -->
-<invoke name="Task">
-<parameter name="description">Security ideation</parameter>
-<parameter name="prompt">[prompt with domain=security]</parameter>
-<parameter name="subagent_type">agileflow-security</parameter>
-<parameter name="run_in_background">true</parameter>
-</invoke>
-
-<invoke name="Task">
-<parameter name="description">Performance ideation</parameter>
-<parameter name="prompt">[prompt with domain=performance]</parameter>
-<parameter name="subagent_type">agileflow-performance</parameter>
-<parameter name="run_in_background">true</parameter>
-</invoke>
-
-<invoke name="Task">
-<parameter name="description">Code quality ideation</parameter>
-<parameter name="prompt">[prompt with domain=refactor]</parameter>
-<parameter name="subagent_type">agileflow-refactor</parameter>
-<parameter name="run_in_background">true</parameter>
-</invoke>
-
-<invoke name="Task">
-<parameter name="description">UX ideation</parameter>
-<parameter name="prompt">[prompt with domain=ui]</parameter>
-<parameter name="subagent_type">agileflow-ui</parameter>
-<parameter name="run_in_background">true</parameter>
-</invoke>
-
-<invoke name="Task">
-<parameter name="description">Testing ideation</parameter>
-<parameter name="prompt">[prompt with domain=testing]</parameter>
-<parameter name="subagent_type">agileflow-testing</parameter>
-<parameter name="run_in_background">true</parameter>
-</invoke>
-
-<invoke name="Task">
-<parameter name="description">API/Architecture ideation</parameter>
-<parameter name="prompt">[prompt with domain=api]</parameter>
-<parameter name="subagent_type">agileflow-api</parameter>
-<parameter name="run_in_background">true</parameter>
-</invoke>
+> **Note**: Only include the `<parameter name="model">` line if MODEL was explicitly specified. If not specified, omit it to use the default model.
 
-<!-- Additional ultradeep experts (7 more) -->
-<invoke name="Task">
-<parameter name="description">Accessibility ideation</parameter>
-<parameter name="prompt">[prompt with domain=accessibility]</parameter>
-<parameter name="subagent_type">agileflow-accessibility</parameter>
-<parameter name="run_in_background">true</parameter>
-</invoke>
+**Example deployment for SCOPE=all DEPTH=ultradeep** (13 experts via tmux):
 
-<invoke name="Task">
-<parameter name="description">Compliance ideation</parameter>
-<parameter name="prompt">[prompt with domain=compliance]</parameter>
-<parameter name="subagent_type">agileflow-compliance</parameter>
-<parameter name="run_in_background">true</parameter>
-</invoke>
+```bash
+# 1. Dry run to show cost estimate
+node .agileflow/scripts/spawn-audit-sessions.js --audit=ideate --target=. --focus=all --model=opus --dry-run
 
-<invoke name="Task">
-<parameter name="description">Database ideation</parameter>
-<parameter name="prompt">[prompt with domain=database]</parameter>
-<parameter name="subagent_type">agileflow-database</parameter>
-<parameter name="run_in_background">true</parameter>
-</invoke>
+# 2. After user confirms, spawn sessions
+node .agileflow/scripts/spawn-audit-sessions.js --audit=ideate --target=. --focus=all --model=opus
+```
 
-<invoke name="Task">
-<parameter name="description">Monitoring ideation</parameter>
-<parameter name="prompt">[prompt with domain=monitoring]</parameter>
-<parameter name="subagent_type">agileflow-monitoring</parameter>
-<parameter name="run_in_background">true</parameter>
-</invoke>
+Each expert gets its own Claude Code tmux session with full context window. Use the monitor script to track progress:
 
-<invoke name="Task">
-<parameter name="description">QA ideation</parameter>
-<parameter name="prompt">[prompt with domain=qa]</parameter>
-<parameter name="subagent_type">agileflow-qa</parameter>
-<parameter name="run_in_background">true</parameter>
-</invoke>
+```bash
+# Check completion status
+node .agileflow/scripts/lib/tmux-audit-monitor.js status TRACE_ID
+# Wait for all to complete (blocks until done or timeout)
+node .agileflow/scripts/lib/tmux-audit-monitor.js wait TRACE_ID --timeout=1800
+# Collect whatever results are ready
+node .agileflow/scripts/lib/tmux-audit-monitor.js collect TRACE_ID
+```
 
-<invoke name="Task">
-<parameter name="description">Analytics ideation</parameter>
-<parameter name="prompt">[prompt with domain=analytics]</parameter>
-<parameter name="subagent_type">agileflow-analytics</parameter>
-<parameter name="run_in_background">true</parameter>
-</invoke>
+**For SCOPE-filtered ultradeep** (e.g., SCOPE=security):
 
-<invoke name="Task">
-<parameter name="description">Documentation ideation</parameter>
-<parameter name="prompt">[prompt with domain=documentation]</parameter>
-<parameter name="subagent_type">agileflow-documentation</parameter>
-<parameter name="run_in_background">true</parameter>
-</invoke>
+```bash
+node .agileflow/scripts/spawn-audit-sessions.js --audit=ideate --target=. --focus=security,api,testing,compliance,monitoring --model=sonnet
 ```
 
+> **Fallback**: If tmux is unavailable, fall back to DEPTH=deep with in-process Task calls (6 experts). Warn the user: "tmux not available, falling back to DEPTH=deep with 6 in-process experts"
+
 ### STEP 3: COLLECT RESULTS
 
 Wait for all experts to complete:
@@ -745,13 +774,17 @@ After generating output, present options:
 
 ### Example: Ultradeep Execution
 
-**User**: `/agileflow:ideate:new SCOPE=all DEPTH=ultradeep OUTPUT=both`
+**User**: `/agileflow:ideate:new SCOPE=all DEPTH=ultradeep MODEL=opus OUTPUT=both`
 
-**Step 1**: Parse → SCOPE=all (13 experts), DEPTH=ultradeep (5 ideas each), OUTPUT=both
+**Step 1**: Parse → SCOPE=all (13 experts), DEPTH=ultradeep, MODEL=opus, OUTPUT=both
 
-**Step 2**: Deploy 13 experts in parallel (security, performance, refactor, ui, testing, api, accessibility, compliance, database, monitoring, qa, analytics, documentation)
+**Step 1.5**: Ultradeep mode detected:
+- Run dry-run: `node .agileflow/scripts/spawn-audit-sessions.js --audit=ideate --target=. --focus=all --model=opus --dry-run`
+- Show cost estimate to user, confirm before launching
+- Spawn 13 tmux sessions: `node .agileflow/scripts/spawn-audit-sessions.js --audit=ideate --target=. --focus=all --model=opus`
+- Monitor `docs/09-agents/ultradeep/{trace_id}/` for sentinel files
 
-**Step 3**: Collect results (~65 raw ideas)
+**Step 3**: Collect results from sentinel files (~65 raw ideas)
 
 **Step 4**: Synthesize with ultradeep thresholds:
 - 8 ideas mentioned by 3+ experts → HIGH confidence
@@ -771,11 +804,12 @@ After generating output, present options:
 | Argument | Values | Default | Description |
 |----------|--------|---------|-------------|
 | SCOPE | all, security, perf, code, ux | all | Which domains to analyze |
-| DEPTH | quick, deep, ultradeep | quick | quick (3 ideas, 6 experts), deep (5 ideas, 6 experts), ultradeep (5 ideas, 13 experts) |
+| DEPTH | quick, deep, ultradeep | quick | quick (3 ideas, 6 experts), deep (5 ideas, 6 experts), ultradeep (5 ideas, 13 experts via tmux) |
 | OUTPUT | report, stories, both | report | What to generate |
 | HISTORY | true, false | true | Enable deduplication and history tracking. Set to false for faster runs without history analysis |
 | SHOW_IMPLEMENTED | true, false | false | Include already-implemented ideas in report (useful for tracking) |
 | FOCUS | IDEA-XXXX | - | Focus on a specific recurring idea (activates Implementation Brief mode) |
+| MODEL | haiku, sonnet, opus | haiku | Model for expert subagents. Passed to Task calls (quick/deep) or tmux sessions (ultradeep). |
 
 {{argument}}
 

package/src/core/commands/impact.md

@@ -1,5 +1,6 @@
 ---
 description: Analyze change impact across codebase
+phase: planning
 argument-hint: "[FILES=<paths>] [BASE=<branch>] [RUN_TESTS=true|false]"
 compact_context:
   priority: high

package/src/core/commands/learn/explain.md

@@ -0,0 +1,118 @@
+---
+description: Deep explanation of code areas - not just what the code does, but WHY it was written this way, with git history and design reasoning
+argument-hint: "[file|function|feature] [DEPTH=quick|thorough]"
+---
+
+# /agileflow:learn:explain
+
+Get a deep "why" explanation of code areas. Goes beyond what the code does to explain why it was written this way, what alternatives were considered, and what historical context shaped it.
+
+---
+
+## Quick Reference
+
+```
+/agileflow:learn:explain src/auth/middleware.ts             # Explain specific file
+/agileflow:learn:explain handleCheckout                     # Explain a function
+/agileflow:learn:explain "the caching layer"                # Explain a concept/area
+/agileflow:learn:explain app/api/ DEPTH=thorough            # Thorough explanation
+```
+
+---
+
+## How It Works
+
+1. **Find the code** - Locate the target file, function, or feature
+2. **Read the code** - Understand what it does
+3. **Check git history** - Find when/why it was written or changed
+4. **Analyze design decisions** - Explain the "why" behind the approach
+5. **Surface alternatives** - What other approaches could have been used
+6. **Present explanation** - Clear, educational explanation with context
+
+---
+
+## Step-by-Step Process
+
+### STEP 1: Parse Arguments
+
+```
+TARGET = file path, function name, or feature description
+DEPTH = quick (3-5 min read) or thorough (10-15 min read)
+```
+
+### STEP 2: Find and Read Code
+
+1. If file path: read the file directly
+2. If function name: search codebase for the function
+3. If feature description: use `Explore` agent to find relevant files
+
+### STEP 3: Analyze Git History
+
+```bash
+git log --follow --oneline {file}        # See file history
+git log -p --follow -S "{function}" -- . # Find when function was added/changed
+git blame {file}                          # See who wrote each line and when
+```
+
+### STEP 4: Generate Explanation
+
+Structure the explanation:
+
+```markdown
+## What This Code Does
+
+{Clear explanation of the code's purpose and behavior}
+
+## Why It's Written This Way
+
+{Design reasoning - what constraints or requirements led to this approach}
+
+### Historical Context
+{Git history insights - when it was written, major changes, why changes were made}
+
+### Design Decisions
+| Decision | Choice Made | Why | Alternative Considered |
+|----------|-------------|-----|----------------------|
+| {decision} | {choice} | {reasoning} | {what else could have been done} |
+
+## How It Connects
+
+{Data flow diagram showing where this code fits in the system}
+
+```mermaid
+graph LR
+    A[Input] --> B[This Code] --> C[Output]
+    B --> D[Side Effects]
+```
+
+## Key Concepts
+
+| Concept | Explanation |
+|---------|-------------|
+| {term} | {what it means in this context} |
+
+## Gotchas
+
+{Non-obvious behaviors, edge cases, or things to be careful about}
+```
+
+### STEP 5: Offer Follow-Up
+
+```
+Explanation complete for {target}.
+
+Options:
+- Explain a related area
+- Tour the broader system this belongs to
+- See similar patterns elsewhere in the codebase
+- Done
+```
+
+---
+
+## Related Commands
+
+- `/agileflow:learn:tour` - Guided codebase walkthrough
+- `/agileflow:learn:patterns` - Design patterns catalog
+- `/agileflow:learn:glossary` - Domain terminology
+- `/agileflow:context:full` - Full project context