agileflow 2.92.1 → 2.94.0

package/src/core/commands/rlm.md

@@ -0,0 +1,363 @@
+---
+description: Analyze complex documents using RLM (Recursive Language Models) pattern
+argument-hint: DOCUMENT=<path> QUERY=<text> [MAX_ITERATIONS=<number>] [DEPTH=<number>]
+compact_context:
+  priority: high
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:rlm - RLM document analysis"
+    - "Virtualize document - NEVER load full content into context"
+    - "Use document-repl.js for all document operations"
+    - "Delegate search to rlm-subcore agent (Haiku) when beneficial"
+    - "Synthesize results yourself (Sonnet) - sub-agent only searches"
+    - "Respect iteration limits and budget constraints"
+  state_fields:
+    - document_path
+    - document_chars
+    - complexity
+    - query
+    - iteration_count
+    - max_iterations
+---
+
+# /agileflow:rlm
+
+Analyze complex documents using the RLM (Recursive Language Models) pattern. Virtualizes documents outside context and uses programmatic search instead of loading full content.
+
+---
+
+## When to Use RLM
+
+| Scenario | Use RLM? | Why |
+|----------|----------|-----|
+| Document < 10k chars | No | Direct read is fine |
+| Document 10-50k chars, simple query | Maybe | Try direct first |
+| Document 50k+ chars | **Yes** | Context rot risk |
+| High cross-referencing (legal, specs) | **Yes** | Multi-hop reasoning needed |
+| Multiple questions about same doc | **Yes** | REPL state persists |
+
+---
+
+## STEP 0: Gather Context
+
+```bash
+node .agileflow/scripts/obtain-context.js rlm
+```
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+
+## COMPACT SUMMARY - /agileflow:rlm IS ACTIVE
+
+**ROLE**: Analyze complex documents without context rot using REPL + recursion pattern.
+
+### RULE #1: NEVER LOAD FULL DOCUMENT
+
+**CRITICAL**: The whole point of RLM is to NOT stuff the document into your context.
+
+**WRONG**:
+```bash
+Read("/path/to/large-contract.pdf")  # NO! Context rot!
+```
+
+**RIGHT**:
+```bash
+node packages/cli/scripts/document-repl.js --load="/path/to/large-contract.pdf" --info
+```
+
+### RULE #2: WORKFLOW PHASES
+
+**Phase 1: Assess**
+```bash
+# Get document info and complexity
+node packages/cli/scripts/document-repl.js --load="DOCUMENT" --info
+```
+
+If complexity is LOW and chars < 10k, consider direct read instead.
+
+**Phase 2: Explore Structure**
+```bash
+# Get table of contents
+node packages/cli/scripts/document-repl.js --load="DOCUMENT" --toc
+```
+
+**Phase 3: Targeted Search**
+```bash
+# Search for relevant terms from the query
+node packages/cli/scripts/document-repl.js --load="DOCUMENT" --search="keyword"
+```
+
+**Phase 4: Extract Sections**
+```bash
+# Get specific sections identified in search
+node packages/cli/scripts/document-repl.js --load="DOCUMENT" --section="Article 7"
+```
+
+**Phase 5: Synthesize**
+- YOU (Sonnet) synthesize the final answer
+- Sub-agent only did search, you do reasoning
+
+### RULE #3: DELEGATION DECISION
+
+| Complexity | Chars | Approach |
+|------------|-------|----------|
+| LOW | < 10k | Direct read (no RLM) |
+| LOW | 10-50k | REPL yourself (no sub-agent) |
+| MEDIUM | Any | REPL yourself |
+| HIGH | < 50k | REPL yourself |
+| HIGH | 50k+ | **Delegate to rlm-subcore** |
+
+**Delegate when**:
+- Document > 50k chars AND complexity HIGH
+- Multiple search operations needed
+- Budget optimization required
+
+### RULE #4: SUB-AGENT DELEGATION
+
+When delegating to rlm-subcore:
+
+```
+Task(
+  description: "Search merger agreement for termination clauses",
+  prompt: "Use document-repl.js to search '/path/to/doc.pdf' for 'termination'. Return all matches with context. Budget: 10000 chars.",
+  subagent_type: "agileflow-rlm-subcore",
+  model: "haiku"
+)
+```
+
+**Sub-agent returns**: Structured search results
+**You synthesize**: Use results to answer the original query
+
+### RULE #5: ITERATION LIMITS
+
+| Parameter | Default | Purpose |
+|-----------|---------|---------|
+| MAX_ITERATIONS | 10 | Prevent runaway loops |
+| DEPTH | 1 | Recursion depth (sub-agent layers) |
+| BUDGET | 15000 | Chars per operation |
+
+**Track iterations**: If approaching MAX_ITERATIONS, summarize what you have.
+
+### RULE #6: ANSWER FORMAT
+
+After analysis, provide:
+
+```markdown
+## RLM Analysis: [Document Name]
+
+**Query**: [Original question]
+**Document**: [path] (X chars, Y lines, COMPLEXITY)
+**Iterations**: N of MAX
+
+### Answer
+
+[Your synthesized answer based on extracted content]
+
+### Evidence
+
+1. **[Section/Line]**: [relevant excerpt]
+2. **[Section/Line]**: [relevant excerpt]
+
+### Confidence
+
+[HIGH/MEDIUM/LOW] - [reason for confidence level]
+```
+
+### Anti-Patterns (DON'T)
+
+- Load full document with Read tool
+- Skip complexity assessment
+- Let sub-agent do reasoning (they only search)
+- Exceed iteration limits without notice
+- Return raw search results as final answer
+
+### Correct Patterns (DO)
+
+- Assess complexity first
+- Use document-repl.js for all doc operations
+- Delegate search to sub-agent when beneficial
+- Synthesize results yourself
+- Track iterations and budget
+- Provide confidence assessment
+
+<!-- COMPACT_SUMMARY_END -->
+
+---
+
+## Arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| DOCUMENT | Yes | Path to document file |
+| QUERY | Yes | Question to answer about the document |
+| MAX_ITERATIONS | No | Max search iterations (default: 10) |
+| DEPTH | No | Recursion depth for sub-agents (default: 1) |
+
+---
+
+## IMMEDIATE ACTIONS
+
+Upon invocation:
+
+### Step 1: Validate Arguments
+
+```bash
+# Check DOCUMENT exists
+ls -la "DOCUMENT_PATH"
+
+# Check format is supported
+# Supported: .txt, .md, .pdf, .docx
+```
+
+If DOCUMENT or QUERY missing, ask user:
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Please provide the document path and your question.",
+  "header": "RLM Input",
+  "multiSelect": false,
+  "options": [
+    {"label": "Enter document path", "description": "Path to .txt, .md, .pdf, or .docx file"},
+    {"label": "Cancel", "description": "Exit RLM analysis"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+### Step 2: Assess Document
+
+```bash
+node packages/cli/scripts/document-repl.js --load="DOCUMENT" --info --json
+```
+
+**Decision point**: Based on complexity and size, decide approach:
+- LOW + small → suggest direct read
+- Otherwise → continue with RLM
+
+### Step 3: Explore Structure
+
+```bash
+node packages/cli/scripts/document-repl.js --load="DOCUMENT" --toc
+```
+
+### Step 4: Search Strategy
+
+Based on QUERY, identify search terms:
+1. Extract key concepts from query
+2. Search for each term
+3. Identify relevant sections
+
+```bash
+# For each key term
+node packages/cli/scripts/document-repl.js --load="DOCUMENT" --search="term1"
+node packages/cli/scripts/document-repl.js --load="DOCUMENT" --search="term2"
+```
+
+### Step 5: Extract Relevant Content
+
+Based on search results, extract full sections:
+
+```bash
+node packages/cli/scripts/document-repl.js --load="DOCUMENT" --section="Relevant Section"
+```
+
+Or specific line ranges:
+
+```bash
+node packages/cli/scripts/document-repl.js --load="DOCUMENT" --slice="100-200"
+```
+
+### Step 6: Synthesize Answer
+
+Using ONLY the extracted content (not full document):
+1. Answer the QUERY
+2. Cite evidence with line numbers
+3. Assess confidence
+
+### Step 7: Present Results
+
+Format as shown in RULE #6 above.
+
+---
+
+## Example Usage
+
+### Example 1: Legal Document Analysis
+
+```
+/agileflow:rlm DOCUMENT="contracts/merger-agreement.pdf" QUERY="What are the conditions precedent to closing for each party?"
+```
+
+**Workflow**:
+1. Assess: 429k chars, HIGH complexity
+2. TOC: Find "Article 7: Conditions Precedent"
+3. Search: "conditions precedent", "closing", "purchaser", "seller"
+4. Extract: Article 7 section
+5. Synthesize: List conditions for each party
+
+### Example 2: Technical Specification
+
+```
+/agileflow:rlm DOCUMENT="specs/api-specification.md" QUERY="What authentication methods are supported?"
+```
+
+**Workflow**:
+1. Assess: 85k chars, MEDIUM complexity
+2. TOC: Find "Authentication" section
+3. Search: "authentication", "auth", "OAuth", "JWT"
+4. Extract: Authentication section
+5. Synthesize: List supported methods with details
+
+### Example 3: Research Paper
+
+```
+/agileflow:rlm DOCUMENT="research/rlm-paper.pdf" QUERY="What are the limitations of the RLM approach?"
+```
+
+**Workflow**:
+1. Assess: 25k chars, LOW complexity
+2. Search: "limitations", "risks", "guardrails"
+3. Extract: Limitations section
+4. Synthesize: Summarize limitations
+
+---
+
+## Integration with Research Commands
+
+RLM can be used with research notes:
+
+```
+/agileflow:rlm DOCUMENT="docs/10-research/20260117-rlm-recursive-language-models.md" QUERY="What are the key findings?"
+```
+
+For smaller research notes, `/agileflow:research:view` may be sufficient.
+
+---
+
+## Error Handling
+
+| Error | Recovery |
+|-------|----------|
+| Document not found | Ask user for correct path |
+| Unsupported format | Suggest conversion to .txt/.md |
+| PDF parse error | Check pdf-parse installed |
+| DOCX parse error | Check mammoth installed |
+| Budget exceeded | Summarize partial results |
+| Max iterations | Report findings so far |
+
+---
+
+## Related Commands
+
+- `/agileflow:research:analyze` - Analyze research notes (uses RLM for large docs)
+- `/agileflow:research:view` - View research notes (direct read)
+- `/agileflow:research:synthesize` - Cross-document analysis
+
+---
+
+## References
+
+- Research: `docs/10-research/20260117-rlm-recursive-language-models.md`
+- Research: `docs/10-research/20260119-rlm-claude-code-implementation.md`
+- Sub-agent: `packages/cli/src/core/agents/rlm-subcore.md`
+- Script: `packages/cli/scripts/document-repl.js`

package/src/core/commands/roadmap/analyze.md

@@ -1,6 +1,6 @@
 ---
 description: Automated competitor analysis with feature gap identification
-argument-hint: "[COMPETITORS=<keywords>] [FOCUS=all|features|security|perf|ux] [OUTPUT=matrix|report|stories]"
+argument-hint: [COMPETITORS=<text>] [FOCUS=all|features|security|perf|ux] [OUTPUT=matrix|report|stories]
 compact_context:
   priority: high
   preserve_rules:

package/src/core/commands/rpi.md

@@ -1,6 +1,6 @@
 ---
 description: Orchestrate Research-Plan-Implement workflow with explicit phase transitions
-argument-hint: [TASK=<description>] [PHASE=research|plan|implement] [SKIP_RESEARCH=true]
+argument-hint: [TASK=<text>] [PHASE=research|plan|implement] [SKIP_RESEARCH=true|false]
 compact_context:
   priority: critical
   preserve_rules:
@@ -32,6 +32,14 @@ Guide complex tasks through three phases, each producing a compressed artifact f
 
 ---
 
+## STEP 0: Gather Context
+
+```bash
+node .agileflow/scripts/obtain-context.js rpi
+```
+
+---
+
 <!-- COMPACT_SUMMARY_START -->
 
 ## COMPACT SUMMARY - RPI WORKFLOW ACTIVE

package/src/core/commands/session/cleanup.md

@@ -0,0 +1,250 @@
+---
+description: Interactive session cleanup with AI assessment
+argument-hint: (no arguments)
+compact_context:
+  priority: high
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:session:cleanup - Review and clean up sessions"
+    - "Walk through EACH session with issues one-by-one"
+    - "Show file changes with AI assessment (SAFE/IMPORTANT)"
+    - "Use AskUserQuestion for EACH session with recommended action"
+    - "Recommended action based on allTrivial flag from health --detailed"
+    - "Track: deleted count, kept count, skipped count"
+  state_fields:
+    - health_report
+    - current_session_index
+    - total_sessions
+    - deleted_count
+    - kept_count
+---
+
+# /agileflow:session:cleanup
+
+Interactive session cleanup - review each session with health issues and decide what to do.
+
+---
+
+## Purpose
+
+When you have forgotten sessions with uncommitted changes, stale entries, or orphaned worktrees, this command:
+- Shows you what changed in each session
+- Analyzes whether changes are important or trivial
+- Provides AI recommendation for each session
+- Lets you decide one-by-one what to clean up
+
+---
+
+## IMMEDIATE ACTIONS
+
+### Step 1: Get Detailed Health Report
+
+```bash
+node .agileflow/scripts/session-manager.js health --detailed
+```
+
+Parse the JSON output and count total issues:
+- `uncommitted.length` - Sessions with uncommitted changes
+- `stale.length` - Sessions inactive for 7+ days
+- `orphanedRegistry.length` - Registry entries with missing paths
+- `orphanedWorktrees.length` - Worktrees not in registry
+
+If total is 0, display:
+```
+✅ All sessions healthy! Nothing to clean up.
+```
+And exit.
+
+### Step 2: Display Overview
+
+```
+📋 Session Health Check
+=======================
+
+Found {total_issues} issue(s) across {total_sessions} session(s).
+Let's go through each one.
+```
+
+### Step 3: Process Each Session with Uncommitted Changes
+
+For each session in `uncommitted` array:
+
+#### Step 3a: Display Session Header
+
+```
+─────────────────────────────────────────────────────────────
+Session {id} "{nickname}" ({current}/{total})
+─────────────────────────────────────────────────────────────
+```
+
+#### Step 3b: Display Files Changed
+
+```
+📝 {changeCount} uncommitted file(s):
+```
+
+For each file in `fileDetails`:
+- `M` status: `   M {file}` and if `trivial: true` add `(~{diffLines} lines - trivial)`
+- `??` status: `   ?? {file}` and if `existsInMain: true` add `(exists in main)`
+- Other: `   {status} {file}`
+
+#### Step 3c: Display AI Assessment
+
+If `allTrivial` is true:
+```
+🤖 Assessment: SAFE TO DELETE
+   No unique work - all changes are trivial or already in main.
+```
+
+If `allTrivial` is false:
+```
+🤖 Assessment: IMPORTANT - KEEP
+   This session has unique changes that may be valuable.
+```
+
+#### Step 3d: Ask User with AskUserQuestion
+
+**If SAFE (allTrivial: true):**
+```
+AskUserQuestion:
+  question: "Session {id} - What would you like to do?"
+  header: "Cleanup"
+  multiSelect: false
+  options:
+    - label: "Delete session (Recommended)"
+      description: "Remove session and worktree - no unique work"
+    - label: "Keep this session"
+      description: "Leave it as-is"
+    - label: "Stop cleanup"
+      description: "Exit and show summary"
+```
+
+**If IMPORTANT (allTrivial: false):**
+```
+AskUserQuestion:
+  question: "Session {id} - What would you like to do?"
+  header: "Cleanup"
+  multiSelect: false
+  options:
+    - label: "Keep this session (Recommended)"
+      description: "Preserve unique work"
+    - label: "Delete anyway"
+      description: "Remove session and lose changes"
+    - label: "Stop cleanup"
+      description: "Exit and show summary"
+```
+
+#### Step 3e: Execute User Choice
+
+**If "Delete" chosen:**
+```bash
+node .agileflow/scripts/session-manager.js delete {session_id} --remove-worktree
+```
+
+Display: `✓ Session {id} deleted`
+Increment deleted_count.
+
+**If "Keep" chosen:**
+Display: `→ Session {id} kept`
+Increment kept_count.
+
+**If "Stop cleanup" chosen:**
+Go to Step 6 (Final Summary).
+
+### Step 4: Process Orphaned Registry Entries
+
+For each entry in `orphanedRegistry`:
+
+```
+─────────────────────────────────────────────────────────────
+Orphaned Registry: Session {id} ({current}/{total})
+─────────────────────────────────────────────────────────────
+
+🗑️ Registry entry exists but path is missing:
+   Path: {path}
+   Branch: {branch}
+
+AskUserQuestion:
+  question: "Remove orphaned registry entry {id}?"
+  header: "Cleanup"
+  multiSelect: false
+  options:
+    - label: "Remove from registry (Recommended)"
+      description: "Clean up stale entry"
+    - label: "Skip"
+      description: "Leave in registry"
+    - label: "Stop cleanup"
+      description: "Exit and show summary"
+```
+
+**If "Remove" chosen:**
+Remove the entry from `.agileflow/sessions/registry.json`:
+```bash
+node .agileflow/scripts/session-manager.js delete {session_id}
+```
+
+### Step 5: Process Orphaned Worktrees
+
+For each entry in `orphanedWorktrees`:
+
+```
+─────────────────────────────────────────────────────────────
+Orphaned Worktree ({current}/{total})
+─────────────────────────────────────────────────────────────
+
+🗑️ Git worktree exists but not in registry:
+   Path: {path}
+
+AskUserQuestion:
+  question: "Remove orphaned worktree?"
+  header: "Cleanup"
+  multiSelect: false
+  options:
+    - label: "Remove worktree (Recommended)"
+      description: "Delete directory and prune git"
+    - label: "Skip"
+      description: "Leave worktree"
+    - label: "Stop cleanup"
+      description: "Exit and show summary"
+```
+
+**If "Remove" chosen:**
+```bash
+git worktree remove --force "{path}"
+```
+
+### Step 6: Final Summary
+
+```
+═══════════════════════════════════════════════════════════════
+Session Cleanup Complete
+═══════════════════════════════════════════════════════════════
+
+   ✓ Deleted: {deleted_count} session(s)
+   → Kept:    {kept_count} session(s)
+   ○ Skipped: {skipped_count} item(s)
+
+Run /agileflow:session:status to see remaining sessions.
+```
+
+---
+
+## Edge Cases
+
+### No Issues Found
+```
+✅ All sessions healthy! Nothing to clean up.
+```
+
+### User Stops Early
+Show partial summary with what was processed.
+
+### Main Session Protection
+The health check already excludes main session, so it won't appear in cleanup list.
+
+---
+
+## Related Commands
+
+- `/agileflow:session:status` - View all sessions
+- `/agileflow:session:end` - End current session with merge option
+- `/agileflow:session:new` - Create new parallel session

package/src/core/commands/session/end.md

@@ -31,6 +31,16 @@ When you're done with a session, this command:
 - Optionally removes the git worktree directory
 - Updates the registry with last active timestamp
 
+---
+
+## STEP 0: Gather Context
+
+```bash
+node .agileflow/scripts/obtain-context.js session:end
+```
+
+---
+
 ## IMMEDIATE ACTIONS
 
 ### Step 1: Get Current Session

package/src/core/commands/session/history.md

@@ -1,6 +1,6 @@
 ---
 description: View past session history and metrics
-argument-hint: "[DAYS=7|30|90|all]"
+argument-hint: [DAYS=7|30|90|all]
 compact_context:
   priority: medium
   preserve_rules:
@@ -27,6 +27,16 @@ View historical session data and metrics.
 
 Show all sessions (active and inactive) with creation dates, last activity, and work done.
 
+---
+
+## STEP 0: Gather Context
+
+```bash
+node .agileflow/scripts/obtain-context.js session:history
+```
+
+---
+
 ## Arguments
 
 | Argument | Default | Description |

package/src/core/commands/session/init.md

@@ -32,6 +32,16 @@ Sets up session tracking infrastructure:
 
 This command is typically called automatically by the SessionStart hook.
 
+---
+
+## STEP 0: Gather Context
+
+```bash
+node .agileflow/scripts/obtain-context.js session:init
+```
+
+---
+
 ## IMMEDIATE ACTIONS
 
 ### Step 1: Ensure Session Infrastructure