agileflow 2.50.0 → 2.55.0

package/src/core/commands/diagnose.md

@@ -28,55 +28,61 @@ OBJECTIVE: Validate AgileFlow system health, identify issues, and provide action
 The `diagnose` command runs comprehensive system health checks on your AgileFlow installation:
 
 **What it checks:**
-- JSON file validation (status.json, metadata, settings)
+- JSON file validation (status.json, metadata, settings) using `jq empty`
 - File structure integrity (docs/, .agileflow/, .claude/)
 - Auto-archival system configuration
 - Hooks system setup
 - File size analysis with warnings
 
-**JSON Validation:**
-- Validates all critical JSON files using jq
+**JSON Validation** (using jq):
+- Validates all critical JSON files: `jq empty <file>` check
 - Reports file sizes and warns if status.json exceeds 100KB
 - Distinguishes between critical and optional files
 - Shows detailed error messages for invalid JSON
 
-**Auto-Archival System:**
-- Checks if archive script exists and is executable
-- Verifies hook configuration in settings.json
+**Auto-Archival System**:
+- Checks if archive script exists and is executable (`[ -x <script> ]`)
+- Verifies hook configuration in settings.json (jq queries)
 - Reports archival threshold from metadata
 - Identifies missing or misconfigured components
 
-**Hooks System:**
-- Validates .claude/settings.json structure
+**Hooks System** (parsing required):
+- Validates .claude/settings.json structure (jq parsing)
 - Counts SessionStart, UserPromptSubmit, and Stop hooks
 - Reports configuration issues
 
-**File Size Analysis:**
+**File Size Analysis**:
 - Monitors status.json size with thresholds (50KB warning, 100KB critical)
-- Shows story counts for active and archived stories
+- Uses `stat` command to get file sizes
+- Uses `jq '.stories | length'` to count stories
 - Recommends archival when needed
 
-**Output Format:**
-- Uses indicators: ✅ (pass), ❌ (fail), ⚠️ (warning), ℹ️ (info)
+**Diagnostic Checks**:
+1. **JSON File Validation** → Check status.json, metadata, settings validity
+2. **Auto-Archival System** → Verify archive script + hook configuration
+3. **Hooks System** → Validate .claude/settings.json structure
+4. **File Size Analysis** → Check status.json size and story count
+
+**Output Format**:
+- Indicators: ✅ (pass), ❌ (fail), ⚠️ (warning), ℹ️ (info)
 - Shows file sizes in KB and story counts
 - Provides actionable next steps for each issue
 - Exit code 0 (healthy) or 1 (issues found)
 
-**Common Issues Detected:**
-1. Invalid JSON syntax in configuration files
-2. Large status.json files needing archival
+**Common Issues Detected**:
+1. Invalid JSON syntax (jq validation failure)
+2. Large status.json files needing archival (>100KB)
 3. Missing critical files (metadata, status.json)
 4. Auto-archival not configured or not executable
 5. Hooks system misconfiguration
 
-**Recommended Actions:**
+**Recommended Actions**:
 - Run after AgileFlow setup to verify installation
 - Run before major operations to catch issues early
 - Run periodically to maintain system health
-- Run after manual configuration changes
 - Use exit code in CI/CD pipelines for validation
 
-**Usage:**
+**Usage**:
 ```bash
 /agileflow:diagnose
 ```

package/src/core/commands/docs.md

@@ -85,6 +85,24 @@ node .agileflow/scripts/obtain-context.js docs
 - Markdown gap report with categorized findings
 - List of recommended actions with previews
 - Optional: Pull request with documentation updates (if approved)
+
+**Tool Usage Example**:
+When asking for approval before creating docs:
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Create missing documentation for detected code changes?",
+  "header": "Documentation Sync",
+  "multiSelect": false,
+  "options": [
+    {"label": "Create all missing docs", "description": "Auto-generate stubs for all missing documentation"},
+    {"label": "Review each one first", "description": "Preview each change before creating"},
+    {"label": "Skip documentation", "description": "Don't create docs now"}
+  ]
+}]</parameter>
+</invoke>
+```
+
 <!-- COMPACT_SUMMARY_END -->
 
 ---

package/src/core/commands/epic.md

@@ -77,6 +77,37 @@ Create a new epic with optional child stories.
 5. Ask: "Proceed with epic creation? (YES/NO)"
 6. On YES: Execute all writes
 7. On NO: Abort without changes
+
+**Tool Usage Examples**:
+
+TodoWrite:
+```xml
+<invoke name="TodoWrite">
+<parameter name="content">1. Parse inputs (EPIC, TITLE, OWNER, GOAL, STORIES)
+2. Create epic file from template
+3. For each story: create docs/06-stories/
+4. Merge into status.json
+5. Append assign events to bus log
+6. Show preview and wait for confirmation</parameter>
+<parameter name="status">in-progress</parameter>
+</invoke>
+```
+
+AskUserQuestion:
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Create epic EP-0010: Authentication with 3 stories?",
+  "header": "Confirm Epic Creation",
+  "multiSelect": false,
+  "options": [
+    {"label": "Yes, create epic", "description": "Create epic and all stories"},
+    {"label": "No, revise", "description": "Modify before creating"},
+    {"label": "Cancel", "description": "Don't create"}
+  ]
+}]</parameter>
+</invoke>
+```
 <!-- COMPACT_SUMMARY_END -->
 
 ## Prompt

package/src/core/commands/feedback.md

@@ -19,7 +19,7 @@ Collect feedback from agents and humans for continuous process improvement.
 **Purpose**: Collect feedback on stories, agents, and processes for continuous improvement
 
 **Quick Usage**:
-```
+```bash
 /agileflow:agent-feedback SCOPE=story STORY=US-0042
 /agileflow:agent-feedback SCOPE=epic EPIC=EP-0010
 /agileflow:agent-feedback SCOPE=sprint
@@ -27,30 +27,31 @@ Collect feedback from agents and humans for continuous process improvement.
 
 **What It Does**:
 1. Prompts for feedback at trigger points (story done, epic complete, sprint end)
-2. Collects structured feedback (ratings, comments, blockers)
-3. Saves feedback to `docs/08-project/feedback/`
+2. Collects structured feedback (ratings 1-5, comments, blockers)
+3. Saves feedback to `docs/08-project/feedback/` (markdown format)
 4. Analyzes patterns and generates insights
 5. Suggests improvement stories for recurring issues
 6. Tracks metrics over time (clarity, estimates, blockers)
 
 **Required Inputs**:
-- `SCOPE=story|epic|sprint` - Feedback scope (default: story)
+- `SCOPE`: story|epic|sprint (default: story)
 
 **Optional Inputs**:
-- `STORY=<US-ID>` - Story ID (required if SCOPE=story)
-- `EPIC=<EP-ID>` - Epic ID (required if SCOPE=epic)
-- `ANONYMOUS=yes|no` - Anonymous feedback (default: no)
-
-**Output Files**:
-- Feedback notes: `docs/08-project/feedback/<YYYYMMDD>-<ID>.md`
-- Summary log: `docs/08-project/retrospectives.md`
-- Optional: Improvement stories for issues
-
-**Feedback Types**:
-1. **Story Completion**: Clarity, smoothness, estimate accuracy (1-5 scale)
-2. **Agent Performance**: Completion rate, test coverage, reliability
-3. **Epic Retrospective**: Success metrics, wins, challenges, learnings
-4. **Sprint Retrospective**: Continue/Stop/Start, experiments, blockers
+- `STORY`: <US-ID> (required if SCOPE=story)
+- `EPIC`: <EP-ID> (required if SCOPE=epic)
+- `ANONYMOUS`: yes|no (default: no)
+
+**Data Sources** (parsing required):
+1. Story frontmatter files (US-*.md) - YAML extraction for dates, estimates
+2. status.json - Story metadata (JSON parsing)
+3. bus/log.jsonl - Activity logs for pattern detection (JSON line parsing)
+4. Feedback files (markdown parsing for metrics extraction)
+
+**Feedback Collection**:
+- **Story Completion**: AC clarity, dependencies resolved, estimate accuracy, smoothness (1-5 scale)
+- **Agent Performance**: Completion rate, test coverage, reliability metrics
+- **Epic Retrospective**: Success metrics, wins, challenges, learnings
+- **Sprint Retrospective**: Continue/Stop/Start, experiments, blockers
 
 **Metrics Tracked**:
 - Avg story clarity score (target: >4.0)
@@ -63,11 +64,22 @@ Collect feedback from agents and humans for continuous process improvement.
 1. Auto-prompt at trigger (story→done, epic complete, sprint end)
 2. Present feedback form with pre-filled context
 3. Ask: "Provide feedback now? (YES/NO/LATER)"
-4. Collect ratings and comments
-5. Save to feedback files
-6. Analyze patterns across feedback
+4. Collect ratings (1-5 scale) and free-form comments
+5. Save to docs/08-project/feedback/<YYYYMMDD>-<ID>.md
+6. Analyze patterns across feedback (pattern matching for recurring themes)
 7. Suggest improvement stories for recurring issues
 
+**Analysis** (pattern detection):
+- Scan all feedback for patterns: "unclear AC" → improve template
+- Calculate metrics: avg clarity score, estimate variance, blocker frequency
+- Track trends over time (metrics comparison)
+- Generate actionable recommendations
+
+**Output Files**:
+- Feedback notes: `docs/08-project/feedback/<YYYYMMDD>-<ID>.md`
+- Summary log: `docs/08-project/retrospectives.md`
+- Optional: Auto-generated improvement stories for issues
+
 **Example Story Feedback**:
 ```markdown
 ## Story Feedback: US-0042

package/src/core/commands/handoff.md

@@ -73,6 +73,35 @@ All endpoints tested and passing.
 - Documenting progress before pause
 - Highlighting blockers for next agent
 - Creating audit trail of work transitions
+
+**Tool Usage Examples**:
+
+TodoWrite:
+```xml
+<invoke name="TodoWrite">
+<parameter name="content">1. Parse inputs (STORY, FROM, TO, SUMMARY, BLOCKERS)
+2. Create handoff note from template
+3. Append bus line with type="handoff"
+4. Show preview and wait for confirmation</parameter>
+<parameter name="status">in-progress</parameter>
+</invoke>
+```
+
+AskUserQuestion:
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Create handoff from AG-API to AG-UI for US-0042?",
+  "header": "Confirm Handoff",
+  "multiSelect": false,
+  "options": [
+    {"label": "Yes, create", "description": "Create handoff note and bus log"},
+    {"label": "No, cancel", "description": "Don't create"}
+  ]
+}]</parameter>
+</invoke>
+```
+
 <!-- COMPACT_SUMMARY_END -->
 
 ## Prompt

package/src/core/commands/help.md

@@ -34,15 +34,24 @@ node .agileflow/scripts/obtain-context.js help
 - **Command**: /agileflow:help
 - **Purpose**: Display AgileFlow system overview
 - **No Arguments**: Shows system overview automatically
-- **Output**: Markdown overview (no file writes)
-- **Key Actions**:
-  1. Print folder map (docs/*)
-  2. Explain Epics, Stories, ADRs, status.json, bus/log.jsonl
-  3. Show daily workflow
-  4. List all available commands with examples
+- **Output**: Markdown overview (no file writes, display only)
+- **Key Actions**: Print folder map → Explain concepts → Show workflow → List all commands
 - **Workflow**: Pick story → Implement to AC → Tests → PR → Update status
 - **WIP Limit**: Max 2 stories/agent
-- **Command List**: Dynamic injection via <!-- {{COMMAND_LIST}} -->
+
+### Tool Usage
+
+This command uses NO tools (display-only, no file writes).
+
+Output includes:
+- Folder map (docs/*) and what lives where
+- What Epics, Stories, ADRs are
+- How docs/09-agents/status.json and bus/log.jsonl work
+- Daily flow: Pick story → Implement to AC → Tests → PR → Update status
+- WIP limit: max 2 stories/agent
+- All available commands with examples
+- Dynamic injection: <!-- {{COMMAND_LIST}} -->
+
 - **Related**: All AgileFlow commands, system documentation
 <!-- COMPACT_SUMMARY_END -->
 

package/src/core/commands/impact.md

@@ -55,8 +55,8 @@ ACTIVATION_SCRIPT
 **Purpose**: Analyze code change impact across codebase to prevent regressions
 
 **Core Workflow**:
-1. Detect changed files (git diff or FILES param)
-2. Build dependency graph (direct + indirect imports, 2 levels)
+1. Detect changed files (`git diff` or FILES param)
+2. Build dependency graph (direct + indirect imports, 2 levels deep)
 3. Find related tests (unit, integration, E2E)
 4. Analyze breaking changes (function signatures, types)
 5. Generate impact report with risk levels
@@ -64,77 +64,47 @@ ACTIVATION_SCRIPT
 
 **Key Analysis Methods**:
 - **Static Analysis**: AST parsing for imports, dependency graphs, circular deps, dead code
-- **Test Coverage Mapping**: Parse coverage reports, map changed lines to tests
-- **Pattern Matching**: Route tests for API changes, component tests for UI, etc.
+- **Test Coverage Mapping**: Parse coverage reports (coverage/lcov.info), map changed lines to tests
+- **Pattern Matching**: Route tests for API changes, component tests for UI changes
 
 **Input Parameters** (optional):
-- `FILES=<paths>` → Comma-separated file paths (default: auto-detect from git)
-- `BASE=<branch>` → Base branch for comparison (default: main/master)
-- `RUN_TESTS=yes|no` → Execute affected tests (default: yes if found)
+- `FILES`: <paths> (comma-separated file paths, default: auto-detect from git)
+- `BASE`: <branch> (base branch for comparison, default: main/master)
+- `RUN_TESTS`: yes|no (execute affected tests, default: yes if found)
+
+**Parsing Strategy**:
+1. Run `git diff <BASE>...HEAD --name-only` → Extract file paths
+2. For each file: Parse imports/requires (regex or AST parsing)
+3. Build adjacency list for dependency graph
+4. Query coverage reports to map changed lines to tests
+5. Pattern-match to identify test files (*.test.*, *.spec.*)
+6. Run DFS for direct/indirect dependents (2 levels)
+
+**Impact Analysis Steps**:
+1. Detect changed files → Parse dependencies → Build graph
+2. Find related tests (unit, integration, E2E)
+3. Detect breaking changes (function signature changes, type modifications)
+4. Identify affected callers with line numbers
+5. Calculate risk scores (critical/recommended/optional)
+6. Generate impact report → Optionally run tests
 
-**Impact Report Structure**:
+**Example Usage**:
+```bash
+/agileflow:impact
+/agileflow:impact FILES=src/api/auth.ts,src/middleware/jwt.ts
+/agileflow:impact BASE=develop RUN_TESTS=no
 ```
-# Impact Analysis Report
-- Changed Files: N
-- Affected Files: M
-- Tests to Run: X
-
-## Direct Impacts
-For each changed file:
-- Type (API/UI/Service/Model)
-- Changes (line count)
-- Direct dependents (imports this file)
-- Indirect dependents (2-level chain)
-- Related tests (✅ exists, ⚠️ needs update, ❌ missing)
-- Related stories (from docs/06-stories/)
-- Coverage percentage
-
-## Breaking Changes Detection
-- Function signature changes
-- Type modifications
-- Affected callers with line numbers
 
-## Test Recommendations
-- Critical (always run): Direct tests
-- Recommended (affected): Integration/E2E tests
-- Optional (low risk): Peripheral tests
-```
+**Output**: Impact report with changed files, affected files, tests to run, breaking changes detection, test recommendations, optional test execution
 
 **Actions After Analysis**:
 1. Show impact summary
 2. Prompt: "Run affected tests? (YES/NO)"
-3. If YES: Execute tests with `npm test -- <test-files>`
+3. If YES: Execute with `npm test -- <test-files>`
 4. If tests fail: Show failures, suggest regression story
 5. If breaking changes: Warn user, suggest ADR, create update stories
 
-**Integration Features**:
-- CI optimization (only run affected tests)
-- Story updates (append impact notes)
-- Event logging (bus/log.jsonl)
-- Dependency visualization (tree format)
-
-**Rules**:
-- Use static analysis over running tests (faster)
-- Prioritize tests by risk (critical path first)
-- Never skip tests for modified files
-- Warn about uncovered changes
-- Suggest creating tests for gaps
-- Always diff before modifying files
-
-**Example Usage**:
-```bash
-# Auto-detect changes
-/agileflow:impact
-
-# Specific files
-/agileflow:impact FILES=src/api/auth.ts,src/middleware/jwt.ts
-
-# Different base branch
-/agileflow:impact BASE=develop
-
-# Skip test execution
-/agileflow:impact RUN_TESTS=no
-```
+**Integration**: CI optimization (run only affected tests), story updates, event logging, dependency visualization
 <!-- COMPACT_SUMMARY_END -->
 
 ---

package/src/core/commands/metrics.md

@@ -34,24 +34,13 @@ Comprehensive project analytics dashboard with cycle time, lead time, throughput
 - `docs/06-stories/**/US-*.md` - Story metadata and frontmatter
 - `docs/05-epics/*.md` - Epic-level data
 
-**Core Metrics**:
-1. **Cycle Time**: Time from "in-progress" to "done" (actual work time)
-2. **Lead Time**: Time from creation to "done" (total time including waiting)
-3. **Throughput**: Stories completed per week
-4. **WIP**: Current work in progress vs limits
-5. **Agent Utilization**: Work distribution across agents
-6. **Epic Health**: Progress and blocking indicators
-7. **Estimation Accuracy**: Estimates vs actuals
-8. **Blocked Story Analysis**: Patterns and duration
-9. **Flow Efficiency**: Active work time / total lead time
-10. **Cumulative Flow**: Story distribution over time
+**Core Metrics**: Cycle Time, Lead Time, Throughput, WIP, Agent Utilization, Epic Health, Estimation Accuracy, Blocked Story Analysis, Flow Efficiency, Cumulative Flow
 
 **Critical Behavioral Rules**:
 - Calculate from raw data sources, never assume or estimate
 - Show trends (↗↘) compared to previous period
 - Use health indicators (🟢🟡🔴) for quick status assessment
 - Provide actionable recommendations based on data
-- Respect privacy: agent-level only, no individual metrics
 - Always include timeframe and generation timestamp
 
 **Input Parameters**:
@@ -62,29 +51,22 @@ Comprehensive project analytics dashboard with cycle time, lead time, throughput
 - `METRIC`: cycle-time|lead-time|throughput|all (default: all)
 
 **Workflow**:
-1. Parse input parameters or use defaults
-2. Load data from bus/log.jsonl and status.json
-3. Calculate requested metrics using timestamps
-4. Compute statistics (avg, median, p85, trends)
-5. Generate visualizations (ASCII bars, distributions)
-6. Identify patterns and anomalies
-7. Generate actionable recommendations
-8. Format output per FORMAT parameter
-9. Optionally save report to docs/08-project/metrics-reports/
-
-**Output Format (ASCII Dashboard)**:
-- Header with timeframe
-- Key metrics section with trends
-- WIP status and agent breakdown
-- Epic health with progress bars
-- Recommendations section
-- Related commands for deeper analysis
-
-**Integration Points**:
-- After `/agileflow:velocity` for detailed trends
-- After `/agileflow:board` to understand bottlenecks
-- Before `/agileflow:retro` to gather retrospective data
-- Auto-triggered by `/agileflow:babysit` when velocity drops
+1. Parse input parameters → Load data from bus/log.jsonl and status.json
+2. Calculate metrics using timestamps → Compute statistics (avg, median, p85, trends)
+3. Generate visualizations (ASCII bars, distributions)
+4. Identify patterns and anomalies → Generate actionable recommendations
+5. Format output per FORMAT parameter → Optionally save to docs/08-project/metrics-reports/
+
+**Example Usage**:
+```bash
+/agileflow:metrics
+/agileflow:metrics TIMEFRAME=90d EPIC=EP-0010
+/agileflow:metrics METRIC=cycle-time FORMAT=json
+```
+
+**Output**: ASCII dashboard with key metrics, WIP status, epic health, and recommendations
+
+**Integration**: After `/velocity` for trends, before `/retro` for retrospective data, auto-triggered by `/babysit`
 
 <!-- COMPACT_SUMMARY_END -->
 

package/src/core/commands/packages.md

@@ -52,6 +52,27 @@ node .agileflow/scripts/obtain-context.js packages
 - **Output**: Dashboard report, update report, or audit report
 - **Safety**: Never auto-update without approval, preview all commands
 - **Related**: Security audits, CI integration, Dependabot config
+
+**Tools Used**:
+- TodoWrite: Track 8-step dependency management workflow
+
+**TodoWrite Example**:
+```xml
+<invoke name="TodoWrite">
+<parameter name="content">
+1. Parse inputs (ACTION, SCOPE, OUTPUT, INCLUDE_DEV, SAVE_TO, AUTO_PR)
+2. Detect package manager(s) (npm, pip, cargo, etc.)
+3. Run analysis based on ACTION (dashboard/update/audit)
+4. Generate report with findings
+5. For ACTION=update: Show update plan and wait for YES/NO
+6. Apply updates (if approved)
+7. Save reports to docs/08-project/
+8. Create stories for security issues (if needed)
+</parameter>
+<parameter name="status">in-progress</parameter>
+</invoke>
+```
+
 <!-- COMPACT_SUMMARY_END -->
 
 ---

package/src/core/commands/pr.md

@@ -86,6 +86,21 @@ This gathers git status, stories/epics, session state, and registers for PreComp
 - Preserve checkbox states from AC_CHECKED input
 - Format test evidence clearly and readably
 - Suggest meaningful commit messages aligned with change type
+
+**Tool Usage Examples**:
+
+TodoWrite:
+```xml
+<invoke name="TodoWrite">
+<parameter name="content">1. Parse inputs (STORY, TITLE, AC_CHECKED, TEST_EVIDENCE, NOTES)
+2. Read story file to extract epic/summary/deps
+3. Generate PR description with all sections
+4. Output paste-ready PR body
+5. Suggest Conventional Commit subject</parameter>
+<parameter name="status">in-progress</parameter>
+</invoke>
+```
+
 <!-- COMPACT_SUMMARY_END -->
 
 ---

package/src/core/commands/readme-sync.md

@@ -36,18 +36,51 @@ node .agileflow/scripts/obtain-context.js readme-sync
 - **Purpose**: Synchronize folder README.md with current contents
 - **Arguments**: FOLDER=<path> | FOLDER=all
 - **Agent Spawning**: Spawns `readme-updater` agent for actual work
-- **Key Actions**:
-  1. List all files and subdirectories in FOLDER
-  2. Read current README.md (if exists)
-  3. Extract descriptions from each file (first heading or sentence)
-  4. Build new "## Contents" section with bullet list
-  5. Show diff and ask for confirmation via AskUserQuestion
-  6. Update if approved using Edit tool
+- **Key Actions**: List files → Extract descriptions → Build Contents section → Show diff → Update if approved
 - **FOLDER=all**: Sync all docs/*/ subdirectories in parallel
-- **AskUserQuestion**: Use XML format with multiSelect for decisions
+
+### Tool Usage Examples
+
+**Task** (to spawn readme-updater agent):
+```xml
+<invoke name="Task">
+<parameter name="description">Sync README for docs/02-practices</parameter>
+<parameter name="prompt">Audit and synchronize README.md for: docs/02-practices
+1. List all files and subdirectories
+2. Read current README.md (if exists)
+3. Extract descriptions from each file
+4. Build new '## Contents' section
+5. Show diff and ask for confirmation
+6. Update if approved</parameter>
+<parameter name="subagent_type">agileflow-readme-updater</parameter>
+</invoke>
+```
+
+**AskUserQuestion** (when folder is missing):
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{"question": "Which folder should I sync?", "header": "Folder", "multiSelect": false, "options": [{"label": "docs/02-practices (Recommended)", "description": "Sync practices documentation folder"}, {"label": "docs/04-architecture", "description": "Sync architecture documentation"}, {"label": "all", "description": "Sync all docs/ subfolders"}]}]</parameter>
+</invoke>
+```
+
+**AskUserQuestion** (for confirmation):
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{"question": "Apply these changes to README.md?", "header": "Update", "multiSelect": false, "options": [{"label": "Yes, update README (Recommended)", "description": "Write the proposed ## Contents section"}, {"label": "No, abort", "description": "Cancel without making changes"}]}]</parameter>
+</invoke>
+```
+
+**Edit** (to update README contents):
+```xml
+<invoke name="Edit">
+<parameter name="file_path">/full/path/to/docs/02-practices/README.md</parameter>
+<parameter name="old_string">## Contents\n\n[old file list]</parameter>
+<parameter name="new_string">## Contents\n\n- **file.md** – Description\n- **folder/** – Description</parameter>
+</invoke>
+```
+
 - **Output**: Updates only "## Contents" section, preserves all other sections
 - **Use Cases**: After adding files, before releases, documentation cleanup, reorganizing folders
-- **Related**: Async agent spawning patterns, AskUserQuestion format
 <!-- COMPACT_SUMMARY_END -->
 
 ---