diff --git a/.claude/commands/cli/discuss-plan.md b/.claude/commands/cli/discuss-plan.md
new file mode 100644
index 00000000..bc1a5065
--- /dev/null
+++ b/.claude/commands/cli/discuss-plan.md
@@ -0,0 +1,308 @@
+---
+name: discuss-plan
+description: Orchestrates an iterative, multi-model discussion for planning and analysis without implementation.
+argument-hint: "[--topic '...'] [--task-id '...'] [--rounds N]"
+allowed-tools: SlashCommand(*), Bash(*), TodoWrite(*), Read(*), Glob(*)
+---
+
+# CLI Discuss-Plan Command (/cli:discuss-plan)
+
+## Purpose
+
+Orchestrates a multi-model collaborative discussion for in-depth planning and problem analysis. This command facilitates an iterative dialogue between Gemini, Codex, and Claude (the orchestrating AI) to explore a topic from multiple perspectives, refine ideas, and build a robust plan.
+
+**This command is for discussion and planning ONLY. It does NOT modify any code.**
+
+## Core Workflow: The Discussion Loop
+
+The command operates in iterative rounds, allowing the plan to evolve with each cycle. The user can choose to continue for more rounds or conclude when consensus is reached.
+
+```
+Topic Input → [Round 1: Gemini → Codex → Claude] → [User Review] →
+[Round 2: Gemini → Codex → Claude] → ... → Final Plan
+```
+
+### Model Roles & Priority
+
+**Priority Order**: Gemini > Codex > Claude
+
+1. **Gemini (The Analyst)** - Priority 1
+ - Kicks off each round with deep analysis
+ - Provides foundational ideas and draft plans
+ - Analyzes current context or previous synthesis
+
+2. **Codex (The Architect/Critic)** - Priority 2
+ - Reviews Gemini's output critically
+ - Uses deep reasoning for technical trade-offs
+ - Proposes alternative strategies
+ - **Participates purely in conversational/reasoning capacity**
+ - Uses resume mechanism to maintain discussion context
+
+3. **Claude (The Synthesizer/Moderator)** - Priority 3
+ - Synthesizes discussion from Gemini and Codex
+ - Highlights agreements and contentions
+ - Structures refined plan
+ - Poses key questions for next round
+
+## Parameters
+
+- `` (Required): Topic description or task ID (e.g., "Design a new caching layer" or `PLAN-002`)
+- `--rounds ` (Optional): Maximum number of discussion rounds (default: prompts after each round)
+- `--task-id ` (Optional): Associates discussion with workflow task ID
+- `--topic ` (Optional): High-level topic for discussion
+
+## Execution Flow
+
+### Phase 1: Initial Setup
+
+1. **Input Processing**: Parse topic or task ID
+2. **Context Gathering**: Identify relevant files based on topic
+
+### Phase 2: Discussion Round
+
+Each round consists of three sequential steps, tracked via `TodoWrite`.
+
+**Step 1: Gemini's Analysis (Priority 1)**
+
+Gemini analyzes the topic and proposes preliminary plan.
+
+```bash
+# Round 1: CONTEXT_INPUT is the initial topic
+# Subsequent rounds: CONTEXT_INPUT is the synthesis from previous round
+~/.claude/scripts/gemini-wrapper -p "
+PURPOSE: Analyze and propose a plan for '[topic]'
+TASK: Provide initial analysis, identify key modules, and draft implementation plan
+MODE: analysis
+CONTEXT: @{CLAUDE.md} [auto-detected files]
+INPUT: [CONTEXT_INPUT]
+EXPECTED: Structured analysis and draft plan for discussion
+RULES: Focus on technical depth and practical considerations
+"
+```
+
+**Step 2: Codex's Critique (Priority 2)**
+
+Codex reviews Gemini's output using conversational reasoning. Uses `resume --last` to maintain context across rounds.
+
+```bash
+# First round (new session)
+codex chat "
+PURPOSE: Critically review technical plan
+TASK: Review the provided plan, identify weaknesses, suggest alternatives, reason about trade-offs
+MODE: analysis
+CONTEXT: @{CLAUDE.md} [relevant files]
+INPUT_PLAN: [Output from Gemini's analysis]
+EXPECTED: Critical review with alternative ideas and risk analysis
+RULES: Focus on architectural soundness and implementation feasibility
+"
+
+# Subsequent rounds (resume discussion)
+codex chat "
+PURPOSE: Re-evaluate plan based on latest synthesis
+TASK: Review updated plan and discussion points, provide further critique or refined ideas
+MODE: analysis
+CONTEXT: Previous discussion context (maintained via resume)
+INPUT_PLAN: [Output from Gemini's analysis for current round]
+EXPECTED: Updated critique building on previous discussion
+RULES: Build on previous insights, avoid repeating points
+" resume --last
+```
+
+**Step 3: Claude's Synthesis (Priority 3)**
+
+Claude (orchestrating AI) synthesizes both outputs:
+
+- Summarizes Gemini's proposal and Codex's critique
+- Highlights agreements and disagreements
+- Structures consolidated plan
+- Presents open questions for next round
+- This synthesis becomes input for next round
+
+### Phase 3: User Review and Iteration
+
+1. **Present Synthesis**: Show synthesized plan and key discussion points
+2. **Continue or Conclude**: Prompt user:
+ - **(1)** Start another round of discussion
+ - **(2)** Conclude and finalize the plan
+3. **Loop or Finalize**:
+ - Continue → New round with Gemini analyzing latest synthesis
+ - Conclude → Save final synthesized document
+
+## TodoWrite Tracking
+
+Progress tracked for each round and model.
+
+```javascript
+// Example for 2-round discussion
+TodoWrite({
+ todos: [
+ // Round 1
+ { content: "[Round 1] Gemini: Analyzing topic", status: "completed", activeForm: "Analyzing with Gemini" },
+ { content: "[Round 1] Codex: Critiquing plan", status: "completed", activeForm: "Critiquing with Codex" },
+ { content: "[Round 1] Claude: Synthesizing discussion", status: "completed", activeForm: "Synthesizing discussion" },
+ { content: "[User Action] Review Round 1 and decide next step", status: "in_progress", activeForm: "Awaiting user decision" },
+
+ // Round 2
+ { content: "[Round 2] Gemini: Analyzing refined plan", status: "pending", activeForm: "Analyzing refined plan" },
+ { content: "[Round 2] Codex: Re-evaluating plan [resume]", status: "pending", activeForm: "Re-evaluating with Codex" },
+ { content: "[Round 2] Claude: Finalizing plan", status: "pending", activeForm: "Finalizing plan" },
+ { content: "Discussion complete - Final plan generated", status: "pending", activeForm: "Generating final document" }
+ ]
+})
+```
+
+## Output Routing
+
+- **Primary Log**: Entire multi-round discussion logged to single file:
+ - `.workflow/WFS-[id]/.chat/discuss-plan-[topic]-[timestamp].md`
+- **Final Plan**: Clean final version saved upon conclusion:
+ - `.workflow/WFS-[id]/.summaries/plan-[topic].md`
+- **Scratchpad**: If no session active:
+ - `.workflow/.scratchpad/discuss-plan-[topic]-[timestamp].md`
+
+## Discussion Structure
+
+Each round's output is structured as:
+
+```markdown
+## Round N: [Topic]
+
+### Gemini's Analysis (Priority 1)
+[Gemini's full analysis and proposal]
+
+### Codex's Critique (Priority 2)
+[Codex's critical review and alternatives]
+
+### Claude's Synthesis (Priority 3)
+**Points of Agreement:**
+- [Agreement 1]
+- [Agreement 2]
+
+**Points of Contention:**
+- [Issue 1]: Gemini suggests X, Codex suggests Y
+- [Issue 2]: Trade-off between A and B
+
+**Consolidated Plan:**
+[Structured plan incorporating both perspectives]
+
+**Open Questions for Next Round:**
+1. [Question 1]
+2. [Question 2]
+```
+
+## Examples
+
+### Example 1: Multi-Round Architecture Discussion
+
+**Command**: `/cli:discuss-plan --topic "Design a real-time notification system"`
+
+**Round 1**:
+1. **Gemini**: Proposes WebSocket-based architecture with RabbitMQ message queue
+2. **Codex**: Critiques as overly complex for MVP. Suggests Server-Sent Events (SSE) for simplicity (one-way notifications). Questions RabbitMQ necessity, proposes simpler Redis Pub/Sub
+3. **Claude**: Synthesizes views:
+ - **Plan A (Gemini)**: WebSockets + RabbitMQ (highly scalable, complex)
+ - **Plan B (Codex)**: SSE + Redis (simpler, less overhead)
+ - **Open Question**: Is bi-directional communication critical, or is simplicity priority?
+4. **User Action**: Opts for another round to explore trade-offs
+
+**Round 2**:
+1. **Gemini**: Analyzes synthesized document. Notes that if features like "user is typing" indicators are roadmapped, WebSockets better long-term. Drafts plan starting with SSE/Redis but designing for easy migration
+2. **Codex**: Reviews migration plan. Reasons that migration itself could be complex. If feature set likely to expand, starting with WebSockets using managed service might be best cost/benefit
+3. **Claude**: Synthesizes new discussion:
+ - **Consensus**: Simple SSE/Redis too short-sighted
+ - **Refined Options**:
+ 1. Phased approach (SSE → WebSocket) with clear migration plan
+ 2. Direct WebSocket with managed service (Pusher, Ably) to reduce ops overhead
+ - **Recommendation**: Option 2 most robust and future-proof
+4. **User Action**: Agrees with recommendation, concludes discussion
+
+**Final Output**: Planning document saved with:
+- Chosen architecture (Managed WebSocket service)
+- Multi-round reasoning
+- High-level implementation steps
+
+### Example 2: Feature Design Discussion
+
+**Command**: `/cli:discuss-plan --topic "Design user permission system" --rounds 2`
+
+**Round 1**:
+1. **Gemini**: Proposes RBAC (Role-Based Access Control) with predefined roles
+2. **Codex**: Suggests ABAC (Attribute-Based Access Control) for more flexibility
+3. **Claude**: Synthesizes trade-offs between simplicity (RBAC) vs flexibility (ABAC)
+
+**Round 2**:
+1. **Gemini**: Analyzes hybrid approach - RBAC for core permissions, attributes for fine-grained control
+2. **Codex**: Reviews hybrid model, identifies implementation challenges
+3. **Claude**: Final plan with phased rollout strategy
+
+**Automatic Conclusion**: Command concludes after 2 rounds as specified
+
+### Example 3: Problem-Solving Discussion
+
+**Command**: `/cli:discuss-plan --topic "Debug memory leak in data pipeline" --task-id ISSUE-042`
+
+**Round 1**:
+1. **Gemini**: Identifies potential leak sources (unclosed handles, growing cache, event listeners)
+2. **Codex**: Adds profiling tool recommendations, suggests memory monitoring
+3. **Claude**: Structures debugging plan with phased approach
+
+**User Decision**: Single round sufficient, concludes with debugging strategy
+
+## Consensus Mechanisms
+
+**When to Continue:**
+- Significant disagreement between models
+- Open questions requiring deeper analysis
+- Trade-offs need more exploration
+- User wants additional perspectives
+
+**When to Conclude:**
+- Models converge on solution
+- All key questions addressed
+- User satisfied with plan depth
+- Maximum rounds reached (if specified)
+
+## Comparison with Other Commands
+
+| Command | Models | Rounds | Discussion | Implementation | Use Case |
+|---------|--------|--------|------------|----------------|----------|
+| `/cli:mode:plan` | Gemini | 1 | ❌ NO | ❌ NO | Single-model planning |
+| `/cli:analyze` | Gemini/Qwen | 1 | ❌ NO | ❌ NO | Code analysis |
+| `/cli:execute` | Any | 1 | ❌ NO | ✅ YES | Direct implementation |
+| `/cli:codex-execute` | Codex | 1 | ❌ NO | ✅ YES | Multi-stage implementation |
+| `/cli:discuss-plan` | **Gemini+Codex+Claude** | **Multiple** | ✅ **YES** | ❌ **NO** | **Multi-perspective planning** |
+
+## Best Practices
+
+1. **Use for Complex Decisions**: Ideal for architectural decisions, design trade-offs, problem-solving
+2. **Start with Broad Topic**: Let first round establish scope, subsequent rounds refine
+3. **Review Each Synthesis**: Claude's synthesis is key decision point - review carefully
+4. **Know When to Stop**: Don't over-iterate - 2-3 rounds usually sufficient
+5. **Task Association**: Use `--task-id` for traceability in workflow
+6. **Save Intermediate Results**: Each round's synthesis saved automatically
+7. **Let Models Disagree**: Divergent views often reveal important trade-offs
+8. **Focus Questions**: Use Claude's open questions to guide next round
+
+## Breaking Discussion Loops
+
+**Detecting Loops:**
+- Models repeating same arguments
+- No new insights emerging
+- Trade-offs well understood
+
+**Breaking Strategies:**
+1. **User Decision**: Make executive decision when enough info gathered
+2. **Timeboxing**: Set max rounds upfront with `--rounds`
+3. **Criteria-Based**: Define decision criteria before starting
+4. **Hybrid Approach**: Accept multiple valid solutions in final plan
+
+## Notes
+
+- **Pure Discussion**: This command NEVER modifies code - only produces planning documents
+- **Codex Role**: Codex participates as reasoning/critique tool, not executor
+- **Resume Context**: Codex maintains discussion context via `resume --last`
+- **Priority System**: Ensures Gemini leads analysis, Codex provides critique, Claude synthesizes
+- **Output Quality**: Multi-perspective discussion produces more robust plans than single-model analysis
+- Command patterns and session management: see intelligent-tools-strategy.md (loaded in memory)
+- Output routing details: see workflow-architecture.md
+- For implementation after discussion, use `/cli:execute` or `/cli:codex-execute` separately
diff --git a/.claude/commands/workflow/tools/docs.md b/.claude/commands/workflow/tools/docs.md
index cfd5a033..4edad148 100644
--- a/.claude/commands/workflow/tools/docs.md
+++ b/.claude/commands/workflow/tools/docs.md
@@ -1,101 +1,166 @@
---
name: docs
description: Documentation planning and orchestration - creates structured documentation tasks for execution
-argument-hint: "architecture"|"api"|"all" [--tool ] [--scope ]
+argument-hint: "[path] [--tool ] [--cli-generate]"
examples:
- - /workflow:docs all # Complete documentation (gemini default)
- - /workflow:docs all --tool qwen # Use Qwen for architecture focus
- - /workflow:docs architecture --scope src/modules
- - /workflow:docs api --tool gemini --scope api/
+ - /workflow:docs # Current directory (root: full docs, subdir: module only)
+ - /workflow:docs src/modules # Module documentation only
+ - /workflow:docs . --tool qwen # Root directory with Qwen
+ - /workflow:docs src/api --tool gemini # API module documentation
+ - /workflow:docs --cli-generate # Use CLI for doc generation (not just analysis)
---
# Workflow Documentation Command
-## Purpose
+## Overview
+
+### Purpose
**`/workflow:docs` is a lightweight planner/orchestrator** - it analyzes project structure using metadata tools, decomposes documentation work into tasks, and generates execution plans. It does **NOT** generate any documentation content itself.
**Key Principle**: Lightweight Planning + Targeted Execution
- **docs.md** → Collect metadata (paths, structure), generate task JSONs with path references
-- **doc-generator.md** → Execute targeted analysis on focus_paths, generate content
+- **doc-generator agent** → Execute targeted analysis on focus_paths, generate content
**Optimization Philosophy**:
-- **Planning phase**: Minimal context - only metadata (module paths, file lists via `get_modules_by_depth.sh` and Code Index MCP)
+- **Planning phase**: Minimal context - only metadata (module paths, file lists)
- **Task JSON**: Store path references, not content
- **Execution phase**: Targeted deep analysis within focus_paths scope
-## Usage
+### Key Features
+
+**CLI Generation Control**
+- Two execution modes: Analysis mode (default) vs Generation mode (--cli-generate)
+- Analysis mode: CLI tools analyze in `pre_analysis`, agent writes docs in `implementation_approach`
+- Generation mode: CLI tools generate docs directly in `implementation_approach` with MODE=write
+- Flexible workflow: Choose between agent-driven or CLI-driven documentation generation
+
+**Path-Based Control**
+- Flexible path specification: Document entire project (root) or specific subdirectories
+- Automatic root detection: Uses git repository root to determine scope
+- Smart task generation: Root paths get full docs, subdirectories get module docs only
+
+**Update Mode**
+- Automatic detection: Recognizes existing documentation files
+- Content preservation: Maintains user modifications when updating
+- Incremental improvements: Add new sections without losing existing content
+- Safe regeneration: Can safely re-run command to update stale docs
+
+**Bottom-Up Strategy**
+- Self-contained modules first: Each module gets complete documentation (API.md + README.md)
+- Project-level aggregation: README, Architecture, Examples synthesize from completed modules
+- No premature aggregation: Project docs wait for all module docs to complete
+- Conditional project docs: Only generated when running from project root
+
+**Dynamic Recognition**
+- No hardcoded paths: Automatically discovers all project directories
+- Intelligent type detection: Code folders get API.md + README.md, navigation folders get README.md only
+- Respects project structure: Works with any directory layout
+
+**Correct Dependencies**
+- Level 1 (Module trees): Always generated, can execute in parallel
+- Level 2 (Project README): Only if root, must wait for all module docs
+- Level 3 (Architecture/Examples): Only if root, must wait for project README
+
+### Usage
```bash
-/workflow:docs [--tool ] [--scope ]
+/workflow:docs [path] [--tool ] [--cli-generate]
```
-### Parameters
+**Parameters**:
-- **type**: `architecture` | `api` | `all` (required)
- - `architecture`: System design, module interactions, patterns
- - `api`: Endpoint documentation, API specifications
- - `all`: Complete documentation suite
+- **path**: Target directory path (optional, default: current directory)
+ - If path is project root: Generate full documentation (modules + project-level docs)
+ - If path is subdirectory: Generate module documentation only (API.md + README.md)
+ - Path can be relative (e.g., `src/modules`) or absolute
- **--tool**: `gemini` | `qwen` | `codex` (optional, default: gemini)
- - `gemini`: Comprehensive documentation, pattern recognition
+ - `gemini`: Comprehensive documentation, pattern recognition (default)
- `qwen`: Architecture analysis, system design focus
- `codex`: Implementation validation, code quality
-- **--scope**: Directory path filter (optional)
+- **--cli-generate**: Enable CLI-based documentation generation (optional)
+ - When enabled: CLI tools generate documentation content in implementation_approach
+ - When disabled (default): CLI tools only used for analysis in pre_analysis
+ - Requires MODE=write in CLI commands for file generation
-## Planning Workflow
+## Workflow
-### Complete Execution Flow
+### Planning Phases
```
-/workflow:docs [type] [--tool] [--scope]
+/workflow:docs [path] [--tool] [--cli-generate]
↓
-Phase 1: Init Session → Create session dir & active marker
+Phase 1: Initialize Session → Create session dir, detect root status, record cli_generate flag
↓
-Phase 2: Module Analysis → Run get_modules_by_depth.sh
+Phase 2: Analyze Structure → Run get_modules_by_depth.sh, classify folders
↓
-Phase 3: Quick Assess → Check existing docs
+Phase 3: Detect Update Mode → Check existing docs, determine create/update
↓
-Phase 4: Decompose → Create task list & TodoWrite
+Phase 4: Decompose Tasks → Generate Level 1-3 tasks based on root status
↓
-Phase 5: Generate Tasks → Build IMPL-*.json & plans
+Phase 5: Generate Task JSONs → Build IMPL-*.json with flow_control
+ - cli_generate=false: CLI in pre_analysis (MODE=analysis)
+ - cli_generate=true: CLI in implementation_approach (MODE=write)
↓
✅ Planning Complete → Show TodoWrite status
```
-### Phase Details
+### Phase 1: Initialize Session
-#### Phase 1: Session Initialization
```bash
-# Parse arguments and create session structure
-doc_type="all" # architecture|api|all
+# Parse arguments
+path="${1:-.}" # Target path (default: current directory)
tool="gemini" # gemini|qwen|codex (default: gemini)
-scope="" # optional path filter
+cli_generate=false # CLI-based generation flag
+# Parse options
+shift
+while [[ $# -gt 0 ]]; do
+ case "$1" in
+ --tool) tool="$2"; shift 2 ;;
+ --cli-generate) cli_generate=true; shift ;;
+ *) shift ;;
+ esac
+done
+
+# Detect project root and determine if target is root
+project_root=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+target_path=$(cd "$path" && pwd)
+is_root=false
+[[ "$target_path" == "$project_root" ]] && is_root=true
+
+# Create session structure
timestamp=$(date +%Y%m%d-%H%M%S)
session_dir=".workflow/WFS-docs-${timestamp}"
mkdir -p "${session_dir}"/{.task,.process,.summaries}
touch ".workflow/.active-WFS-docs-${timestamp}"
+
+# Record configuration
+echo "path=$path" >> "${session_dir}/.process/config.txt"
+echo "target_path=$target_path" >> "${session_dir}/.process/config.txt"
+echo "is_root=$is_root" >> "${session_dir}/.process/config.txt"
+echo "tool=$tool" >> "${session_dir}/.process/config.txt"
+echo "cli_generate=$cli_generate" >> "${session_dir}/.process/config.txt"
```
-#### Phase 2: Lightweight Metadata Collection with Folder Type Analysis (MANDATORY)
+### Phase 2: Analyze Structure
+
```bash
-# Step 1: Run get_modules_by_depth.sh for module hierarchy (metadata only)
+# Step 1: Discover module hierarchy
module_data=$(~/.claude/scripts/get_modules_by_depth.sh)
# Format: depth:N|path:|files:N|size:N|has_claude:yes/no
-# Step 2: Analyze each folder to determine its type
-# Create folder analysis file
+# Step 2: Classify each folder by type
mkdir -p "${session_dir}/.process"
> "${session_dir}/.process/folder-analysis.txt"
-# For each folder discovered by get_modules_by_depth.sh:
while IFS='|' read -r depth_info path_info files_info size_info claude_info; do
folder_path=$(echo "$path_info" | cut -d':' -f2-)
depth=$(echo "$depth_info" | cut -d':' -f2)
- # Count code files in this folder (not recursive, maxdepth 1)
+ # Count code files (maxdepth 1)
code_files=$(find "$folder_path" -maxdepth 1 -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.go" -o -name "*.java" -o -name "*.rs" \) 2>/dev/null | wc -l)
# Count immediate subfolders
@@ -114,9 +179,7 @@ while IFS='|' read -r depth_info path_info files_info size_info claude_info; do
echo "${folder_path}|${folder_type}|depth:${depth}|code_files:${code_files}|subfolders:${subfolders}" >> "${session_dir}/.process/folder-analysis.txt"
done <<< "$module_data"
-# Step 3: Group folders by top-level directories for task assignment
-# Example: src/modules/auth, src/modules/api → group under "src/modules"
-# This reduces task count while maintaining logical organization
+# Step 3: Group folders by top-level directories
awk -F'|' '{
split($1, parts, "/");
if (length(parts) >= 2) {
@@ -124,57 +187,142 @@ awk -F'|' '{
print top_dir;
}
}' "${session_dir}/.process/folder-analysis.txt" | sort -u > "${session_dir}/.process/top-level-dirs.txt"
-
-# IMPORTANT: Do NOT read file contents in planning phase
-# Only collect: paths, file counts, module structure, folder types
```
-#### Phase 3: Quick Documentation Assessment
-```bash
-# Lightweight check - no heavy analysis
-existing_docs=$(find . -maxdepth 2 -name "*.md" -not -path "./.workflow/*" | wc -l)
+### Phase 3: Detect Update Mode
-if [[ $existing_docs -gt 5 ]]; then
- find . -maxdepth 3 -name "*.md" > "${session_dir}/.process/existing-docs.txt"
+```bash
+# Detect existing documentation
+existing_docs=$(find "$target_path" -name "API.md" -o -name "README.md" -o -name "ARCHITECTURE.md" -o -name "EXAMPLES.md" 2>/dev/null | grep -v ".workflow" | wc -l)
+
+# List existing documentation for update mode
+if [[ $existing_docs -gt 0 ]]; then
+ echo "Update mode: Found $existing_docs existing documentation files"
+ find "$target_path" -name "API.md" -o -name "README.md" -o -name "ARCHITECTURE.md" -o -name "EXAMPLES.md" 2>/dev/null | grep -v ".workflow" > "${session_dir}/.process/existing-docs.txt"
+ echo "mode=update" >> "${session_dir}/.process/config.txt"
+else
+ echo "mode=create" >> "${session_dir}/.process/config.txt"
fi
# Record strategy
cat > "${session_dir}/.process/strategy.md" </dev/null | xargs cat 2>/dev/null || echo 'No existing docs')",
+ "output_to": "existing_module_docs",
+ "note": "Update mode: preserve existing content"
+ },
{
"step": "load_folder_analysis",
- "action": "Load folder type analysis for this tree",
"command": "bash(grep '^src/modules' ${session_dir}/.process/folder-analysis.txt)",
- "output_to": "target_folders",
- "on_error": "fail",
- "note": "Filter analysis to only this tree's folders"
+ "output_to": "target_folders"
},
{
"step": "analyze_module_tree_content",
- "action": "Deep analysis of module tree content",
- "command": "bash(cd src/modules && ~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Document module tree comprehensively\\nTASK: For each folder, generate appropriate documentation (API.md for code folders, README.md for all)\\nMODE: analysis\\nCONTEXT: @{**/*} [target_folders]\\nEXPECTED: Structured documentation content for entire tree\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/api.txt) for API docs, $(cat ~/.claude/workflows/cli-templates/prompts/documentation/module-readme.txt) for module README, $(cat ~/.claude/workflows/cli-templates/prompts/documentation/folder-navigation.txt) for navigation README\")",
+ "command": "bash(cd src/modules && ~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Document module tree\\nTASK: Analyze module structure and generate documentation outline\\nMODE: analysis\\nCONTEXT: @{**/*} [target_folders] [existing_module_docs]\\nEXPECTED: Documentation content outline\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/api.txt) | Analyze structure only\")",
"output_to": "tree_documentation",
- "on_error": "fail",
- "note": "Analysis scoped to focus_paths only - controlled context"
+ "note": "CLI for analysis only, agent generates final docs"
}
],
"implementation_approach": {
- "task_description": "Generate all documentation files for the module tree based on folder types",
"logic_flow": [
"Parse [target_folders] to get list of folders and their types",
+ "Parse [tree_documentation] for structure outline",
"For each folder in tree:",
- " if type == 'code':",
- " - Generate API.md using api.txt template (Part A: Code API)",
- " - Generate README.md using module-readme.txt template",
- " elif type == 'navigation':",
- " - Generate README.md using folder-navigation.txt template",
- "Maintain directory structure in output"
+ " if type == 'code': Generate API.md + README.md using [tree_documentation]",
+ " elif type == 'navigation': Generate README.md only"
]
},
"target_files": [
- ".workflow/docs/modules/README.md",
".workflow/docs/modules/*/API.md",
- ".workflow/docs/modules/*/README.md",
- ".workflow/docs/modules/*/*/API.md",
- ".workflow/docs/modules/*/*/README.md"
+ ".workflow/docs/modules/*/README.md"
]
}
}
```
-### 2. Project README Task (IMPL-[N+1]) - Level 2
-**Purpose**: Project-level overview and navigation
-**Output**: `.workflow/docs/README.md`
-**Dependencies**: All Level 1 module tree tasks (MUST complete first)
+**CLI Generate Mode (--cli-generate specified)**:
+```json
+{
+ "id": "IMPL-001",
+ "title": "Document Module Tree: 'src/modules/'",
+ "status": "pending",
+ "meta": {
+ "type": "docs-tree",
+ "agent": "@doc-generator",
+ "tool": "gemini",
+ "template": "api + module-readme + folder-navigation",
+ "cli_generate": true
+ },
+ "context": {
+ "requirements": [
+ "Recursively process all folders in src/modules/",
+ "For folders with code files: generate API.md + README.md",
+ "For folders with only subfolders: generate README.md (navigation)",
+ "Use folder-analysis.txt to determine folder types"
+ ],
+ "focus_paths": ["src/modules"],
+ "folder_analysis_file": "${session_dir}/.process/folder-analysis.txt",
+ "acceptance": [
+ "All code-containing folders have both API.md and README.md",
+ "All navigation folders have README.md",
+ "Documents follow their respective templates"
+ ]
+ },
+ "flow_control": {
+ "pre_analysis": [
+ {
+ "step": "load_existing_docs",
+ "command": "bash(find src/modules -name 'API.md' -o -name 'README.md' 2>/dev/null | xargs cat 2>/dev/null || echo 'No existing docs')",
+ "output_to": "existing_module_docs",
+ "note": "Update mode: preserve existing content"
+ },
+ {
+ "step": "load_folder_analysis",
+ "command": "bash(grep '^src/modules' ${session_dir}/.process/folder-analysis.txt)",
+ "output_to": "target_folders"
+ }
+ ],
+ "implementation_approach": {
+ "logic_flow": [
+ "Parse [target_folders] to get list of folders and their types",
+ "For each folder in tree:",
+ " if type == 'code': Call CLI to generate API.md + README.md",
+ " elif type == 'navigation': Call CLI to generate README.md only"
+ ],
+ "cli_generation": [
+ {
+ "step": "generate_module_tree_docs",
+ "command": "bash(cd src/modules && ~/.claude/scripts/gemini-wrapper --approval-mode yolo -p \"PURPOSE: Document module tree\\nTASK: Generate complete documentation files for each folder\\nMODE: write\\nCONTEXT: @{**/*} [target_folders] [existing_module_docs]\\nEXPECTED: Generated API.md and README.md files\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/api.txt) | Update existing docs, preserve modifications\")",
+ "output_to": "generated_docs",
+ "note": "CLI generates documentation files with MODE=write"
+ }
+ ]
+ },
+ "target_files": [
+ ".workflow/docs/modules/*/API.md",
+ ".workflow/docs/modules/*/README.md"
+ ]
+ }
+}
+```
-**Complete JSON Structure**:
+#### 2. Project README Task (Level 2)
+
+**Note**: Like Level 1 tasks, this task also has two modes based on `--cli-generate` flag:
+- **Default mode**: CLI analysis in `pre_analysis`, agent generates docs
+- **CLI generate mode**: CLI generation in `implementation_approach` with MODE=write
+
+**Default Mode Example**:
```json
{
"id": "IMPL-004",
@@ -314,58 +682,38 @@ fi
"context": {
"requirements": [
"Aggregate information from all module documentation",
- "Generate navigation links to all modules",
- "Provide project overview and getting started guide",
- "Use Project README Template"
+ "Generate navigation links to all modules"
],
- "focus_paths": ["."],
- "acceptance": [
- "Complete .workflow/docs/README.md following template",
- "All modules linked in navigation",
- "Project structure clearly explained"
- ],
- "scope": "Project root - aggregates all module info"
+ "focus_paths": ["."]
},
"flow_control": {
"pre_analysis": [
+ {
+ "step": "load_existing_project_readme",
+ "command": "bash(cat .workflow/docs/README.md 2>/dev/null || echo 'No existing README')",
+ "output_to": "existing_readme"
+ },
{
"step": "load_all_module_docs",
- "action": "Load all module documentation for aggregation",
"command": "bash(find .workflow/docs/modules -name 'README.md' -o -name 'API.md' | xargs cat)",
- "output_to": "all_module_docs",
- "on_error": "fail",
- "note": "This step requires all module tree tasks to be completed"
+ "output_to": "all_module_docs"
},
{
"step": "analyze_project_structure",
- "action": "Synthesize project overview from module docs",
- "command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Generate project overview\\nTASK: Extract project structure, navigation, and summary from all module docs\\nMODE: analysis\\nCONTEXT: [all_module_docs] @{package.json,CLAUDE.md}\\nEXPECTED: Project README content\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/project-readme.txt) | Focus on navigation and aggregation\")",
- "output_to": "project_overview",
- "on_error": "fail",
- "note": "Synthesizes information from completed module docs"
+ "command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Generate project overview\\nTASK: Extract project structure from module docs\\nMODE: analysis\\nCONTEXT: [all_module_docs] [existing_readme]\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/project-readme.txt) | Preserve user modifications\")",
+ "output_to": "project_overview"
}
],
- "implementation_approach": {
- "task_description": "Generate project README aggregating all module information",
- "logic_flow": [
- "Load template: ~/.claude/workflows/cli-templates/prompts/documentation/project-readme.txt",
- "Extract module list and purposes from [all_module_docs]",
- "Generate navigation structure with links to all modules",
- "Fill template sections with [project_overview]",
- "Format output as Markdown"
- ]
- },
"target_files": [".workflow/docs/README.md"]
}
}
```
-### 3. Architecture Documentation Task (IMPL-[N+2]) - Level 3
-**Purpose**: System design and patterns aggregation
-**Output**: `.workflow/docs/ARCHITECTURE.md`
-**Dependencies**: Project README (IMPL-[N+1]) - MUST complete first
+#### 3. Architecture Documentation Task (Level 3)
-**Complete JSON Structure**:
+**Note**: Level 3 tasks also support both modes based on `--cli-generate` flag.
+
+**Default Mode Example**:
```json
{
"id": "IMPL-005",
@@ -378,63 +726,34 @@ fi
"tool": "gemini",
"template": "project-architecture"
},
- "context": {
- "requirements": [
- "Synthesize system architecture from all module docs",
- "Aggregate API overview from all module API.md files",
- "Document module interactions and design patterns",
- "Use Project Architecture Template"
- ],
- "focus_paths": ["."],
- "acceptance": [
- "Complete .workflow/docs/ARCHITECTURE.md following template",
- "All modules included in architecture overview",
- "Aggregated API section with links to detailed docs"
- ],
- "scope": "System-level architecture synthesis"
- },
"flow_control": {
"pre_analysis": [
+ {
+ "step": "load_existing_architecture",
+ "command": "bash(cat .workflow/docs/ARCHITECTURE.md 2>/dev/null || echo 'No existing ARCHITECTURE')",
+ "output_to": "existing_architecture"
+ },
{
"step": "load_all_docs",
- "action": "Load project README and all module documentation",
- "command": "bash(cat .workflow/docs/README.md && find .workflow/docs/modules -name 'README.md' -o -name 'API.md' | xargs cat)",
- "output_to": "all_docs",
- "on_error": "fail",
- "note": "Requires both project README and all module docs to be complete"
+ "command": "bash(cat .workflow/docs/README.md && find .workflow/docs/modules -name '*.md' | xargs cat)",
+ "output_to": "all_docs"
},
{
"step": "synthesize_architecture",
- "action": "Create system architecture synthesis",
- "command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Synthesize system architecture\\nTASK: Create comprehensive architecture doc from all module information\\nMODE: analysis\\nCONTEXT: [all_docs]\\nEXPECTED: Architecture documentation with patterns, module map, aggregated APIs\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/project-architecture.txt) | Focus on system-level view, aggregate APIs, show relationships\")",
- "output_to": "architecture_content",
- "on_error": "fail",
- "note": "Synthesizes from completed documentation"
+ "command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Synthesize architecture\\nCONTEXT: [all_docs] [existing_architecture]\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/project-architecture.txt)\")",
+ "output_to": "architecture_content"
}
],
- "implementation_approach": {
- "task_description": "Generate architecture documentation synthesizing all module information",
- "logic_flow": [
- "Load template: ~/.claude/workflows/cli-templates/prompts/documentation/project-architecture.txt",
- "Extract module purposes and responsibilities from [all_docs]",
- "Build module map showing relationships",
- "Aggregate public APIs from all API.md files",
- "Generate architecture diagrams (text-based)",
- "Fill template sections with [architecture_content]",
- "Format output as Markdown"
- ]
- },
"target_files": [".workflow/docs/ARCHITECTURE.md"]
}
}
```
-### 4. Examples Documentation Task (IMPL-[N+3]) - Level 3
-**Purpose**: Practical usage examples and best practices
-**Output**: `.workflow/docs/EXAMPLES.md`
-**Dependencies**: Project README (IMPL-[N+1]) - MUST complete first
+#### 4. Examples Documentation Task (Level 3)
-**Complete JSON Structure**:
+**Note**: Same dual-mode support as other tasks.
+
+**Default Mode Example**:
```json
{
"id": "IMPL-006",
@@ -447,68 +766,34 @@ fi
"tool": "gemini",
"template": "project-examples"
},
- "context": {
- "requirements": [
- "Create end-to-end usage examples spanning multiple modules",
- "Demonstrate common scenarios with complete, runnable code",
- "Show best practices and integration patterns",
- "Use Project Examples Template"
- ],
- "focus_paths": ["."],
- "acceptance": [
- "Complete .workflow/docs/EXAMPLES.md following template",
- "All code examples are complete and runnable",
- "Core use cases covered with explanations"
- ],
- "scope": "Project-level examples"
- },
"flow_control": {
"pre_analysis": [
{
- "step": "load_project_readme",
- "action": "Load project README for context",
- "command": "bash(cat .workflow/docs/README.md)",
- "output_to": "project_readme",
- "on_error": "fail",
- "note": "Requires project README to be complete"
+ "step": "load_existing_examples",
+ "command": "bash(cat .workflow/docs/EXAMPLES.md 2>/dev/null || echo 'No existing EXAMPLES')",
+ "output_to": "existing_examples"
},
{
- "step": "identify_example_scenarios",
- "action": "Identify key usage scenarios from module docs",
- "command": "bash(find .workflow/docs/modules -name 'README.md' | xargs grep -A 5 'Usage Scenarios\\|Common Use Cases' | head -100)",
- "output_to": "module_usage_patterns",
- "on_error": "skip_optional"
+ "step": "load_project_readme",
+ "command": "bash(cat .workflow/docs/README.md)",
+ "output_to": "project_readme"
},
{
"step": "generate_examples_content",
- "action": "Create comprehensive examples based on project structure",
- "command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Generate practical usage examples\\nTASK: Create end-to-end examples showing how modules work together\\nMODE: analysis\\nCONTEXT: [project_readme] [module_usage_patterns] @{src/**/*.ts}\\nEXPECTED: Complete, runnable code examples\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/project-examples.txt) | Focus on real-world scenarios\")",
- "output_to": "examples_content",
- "on_error": "fail"
+ "command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Generate usage examples\\nCONTEXT: [project_readme] [existing_examples]\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/project-examples.txt)\")",
+ "output_to": "examples_content"
}
],
- "implementation_approach": {
- "task_description": "Generate comprehensive examples documentation",
- "logic_flow": [
- "Load template: ~/.claude/workflows/cli-templates/prompts/documentation/project-examples.txt",
- "Identify 3-5 core usage scenarios from [module_usage_patterns]",
- "Generate complete, runnable code for each scenario",
- "Add explanations and best practices",
- "Fill template sections with [examples_content]",
- "Format output as Markdown"
- ]
- },
"target_files": [".workflow/docs/EXAMPLES.md"]
}
}
```
-### 5. HTTP API Documentation (IMPL-[N+4]) - Level 3 (Optional)
-**Purpose**: REST/GraphQL API reference
-**Output**: `.workflow/docs/api/README.md`
-**Dependencies**: Project README (IMPL-[N+1])
+#### 5. HTTP API Documentation Task (Level 3, Optional)
-**Complete JSON Structure**:
+**Note**: Same dual-mode support as other tasks.
+
+**Default Mode Example**:
```json
{
"id": "IMPL-007",
@@ -521,321 +806,60 @@ fi
"tool": "gemini",
"template": "api"
},
- "context": {
- "requirements": [
- "Document all API endpoints with request/response formats",
- "Include authentication and error handling",
- "Generate OpenAPI specification if applicable",
- "Use API-Level Documentation Template"
- ],
- "focus_paths": ["src/api", "src/routes", "src/controllers"],
- "acceptance": [
- "Complete .workflow/docs/api/README.md following template",
- "All endpoints documented with examples",
- "OpenAPI spec generated if REST API detected"
- ]
- },
"flow_control": {
"pre_analysis": [
+ {
+ "step": "load_existing_api_docs",
+ "command": "bash(cat .workflow/docs/api/README.md 2>/dev/null || echo 'No existing API docs')",
+ "output_to": "existing_api_docs"
+ },
{
"step": "discover_api_endpoints",
- "action": "Find all API routes and endpoints using MCP",
- "command": "mcp__code-index__search_code_advanced(pattern='router\\.|app\\.|@(Get|Post|Put|Delete|Patch)', file_pattern='*.{ts,js}', output_mode='content', head_limit=100)",
- "output_to": "endpoint_discovery",
- "on_error": "skip_optional",
- "note": "Use MCP instead of rg for better structure"
+ "command": "mcp__code-index__search_code_advanced(pattern='router\\.|@(Get|Post)', file_pattern='*.{ts,js}')",
+ "output_to": "endpoint_discovery"
},
{
"step": "analyze_api_structure",
- "action": "Analyze API structure and patterns",
- "command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Document HTTP API comprehensively\\nTASK: Extract endpoints, auth, request/response formats\\nMODE: analysis\\nCONTEXT: @{src/api/**/*,src/routes/**/*,src/controllers/**/*}\\nEXPECTED: Complete HTTP API documentation\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/api.txt) | Use Part B: HTTP API only\")",
- "output_to": "api_analysis",
- "on_error": "fail",
- "note": "Analysis limited to API-related paths - controlled context"
+ "command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Document HTTP API\\nCONTEXT: @{src/api/**/*} [existing_api_docs]\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/api.txt) | Use Part B: HTTP API\")",
+ "output_to": "api_analysis"
}
],
- "implementation_approach": {
- "task_description": "Use api_analysis to populate HTTP API Documentation Template",
- "logic_flow": [
- "Load template: ~/.claude/workflows/cli-templates/prompts/documentation/api.txt",
- "Use Part B: HTTP API section only",
- "Parse api_analysis for: endpoints, auth, request/response",
- "Fill template sections with extracted information",
- "Generate OpenAPI spec if REST API detected",
- "Format output as Markdown"
- ]
- },
- "target_files": [
- ".workflow/docs/api/README.md",
- ".workflow/docs/api/openapi.yaml"
- ]
+ "target_files": [".workflow/docs/api/README.md"]
}
}
```
-## Planning Outputs
+### Template Reference
-### File Structure
-```
-.workflow/
-├── .active-WFS-docs-20240120-143022
-└── WFS-docs-20240120-143022/
- ├── IMPL_PLAN.md # Implementation plan
- ├── TODO_LIST.md # Progress tracker
- ├── .process/
- │ ├── strategy.md # Doc strategy
- │ └── existing-docs.txt # Existing docs list
- └── .task/
- ├── IMPL-001.json # System overview
- ├── IMPL-002.json # Module: auth
- ├── IMPL-003.json # Module: api
- ├── IMPL-004.json # Architecture
- └── IMPL-005.json # API docs
-```
+**5 Specialized Templates**:
+- **api.txt**: Unified template for Code API (Part A) and HTTP API (Part B)
+- **module-readme.txt**: Module purpose, usage, dependencies
+- **folder-navigation.txt**: Navigation README for folders with only subdirectories
+- **project-readme.txt**: Project overview, getting started, module navigation
+- **project-architecture.txt**: System structure, module map, design patterns
+- **project-examples.txt**: End-to-end usage examples
-### IMPL_PLAN.md
-```markdown
-# Documentation Implementation Plan
-
-**Session**: WFS-docs-[timestamp]
-**Type**: [architecture|api|all]
-**Tool**: [gemini|qwen|codex]
-**Strategy**: Bottom-up, layered approach
-
-## Task Breakdown by Level
-
-### Level 1: Module Tree Tasks (Parallel Execution)
-- **IMPL-001**: Document tree 'src/modules/'
- - Output: modules/*/API.md, modules/*/README.md
- - Templates: api.txt (Part A), module-readme.txt, folder-navigation.txt
-- **IMPL-002**: Document tree 'src/utils/'
-- **IMPL-003**: Document tree 'lib/'
-
-### Level 2: Project README (Sequential - Depends on Level 1)
-- **IMPL-004**: Generate Project README
- - Output: .workflow/docs/README.md
- - Template: project-readme.txt
- - Dependencies: IMPL-001, IMPL-002, IMPL-003
-
-### Level 3: Architecture & Examples (Parallel - Depends on Level 2)
-- **IMPL-005**: Generate Architecture Documentation
- - Output: .workflow/docs/ARCHITECTURE.md
- - Template: project-architecture.txt
- - Dependencies: IMPL-004
-- **IMPL-006**: Generate Examples Documentation
- - Output: .workflow/docs/EXAMPLES.md
- - Template: project-examples.txt
- - Dependencies: IMPL-004
-- **IMPL-007**: Generate HTTP API Documentation (Optional)
- - Output: .workflow/docs/api/README.md
- - Template: api.txt (Part B)
- - Dependencies: IMPL-004
-
-## Execution Order (Respects Dependencies)
-1. **Level 1** (Parallel): IMPL-001, IMPL-002, IMPL-003
-2. **Level 2** (After Level 1): IMPL-004
-3. **Level 3** (After Level 2, can parallelize within level): IMPL-005, IMPL-006, IMPL-007
-```
-
-### TODO_LIST.md
-```markdown
-# Documentation Progress Tracker
-
-## Level 1: Module Tree Tasks (Can execute in parallel)
-- [ ] **IMPL-001**: Document tree 'src/modules/'
-- [ ] **IMPL-002**: Document tree 'src/utils/'
-- [ ] **IMPL-003**: Document tree 'lib/'
-
-## Level 2: Project README (Execute after Level 1)
-- [ ] **IMPL-004**: Generate Project README (depends on IMPL-001~003)
-
-## Level 3: Architecture & Examples (Execute after Level 2, can parallelize)
-- [ ] **IMPL-005**: Generate Architecture Documentation (depends on IMPL-004)
-- [ ] **IMPL-006**: Generate Examples Documentation (depends on IMPL-004)
-- [ ] **IMPL-007**: Generate HTTP API Documentation (Optional, depends on IMPL-004)
-
-## Execution
-
-### Sequential (Respects Dependencies)
-```bash
-# Level 1 - Execute in parallel or sequence
-/workflow:execute IMPL-001
-/workflow:execute IMPL-002
-/workflow:execute IMPL-003
-
-# Wait for Level 1 to complete, then Level 2
-/workflow:execute IMPL-004
-
-# Wait for Level 2 to complete, then Level 3 (can parallelize)
-/workflow:execute IMPL-005
-/workflow:execute IMPL-006
-/workflow:execute IMPL-007 # if applicable
-```
-
-### With Dependency Awareness (Future Enhancement)
-```bash
-# /workflow:execute will automatically handle dependencies
-/workflow:execute --auto-deps IMPL-007
-# This would automatically execute IMPL-001~003 → IMPL-004 → IMPL-007
-```
-```
-
-## Execution Phase
-
-### Layered Execution Flow
-
-```
-Phase 1: Module Tree Generation (Level 1 - Parallel)
-├─ /workflow:execute IMPL-001 (src/modules/) ──┐
-├─ /workflow:execute IMPL-002 (src/utils/) ──┼─> All complete
-└─ /workflow:execute IMPL-003 (lib/) ──┘
- │
-Phase 2: Project README (Level 2 - Sequential) │
-└─ /workflow:execute IMPL-004 <────────────────┘ (Waits for Level 1)
- │
-Phase 3: Architecture & Examples (Level 3) │
-├─ /workflow:execute IMPL-005 (Architecture) <─┤
-├─ /workflow:execute IMPL-006 (Examples) <──┤ (Waits for Level 2)
-└─ /workflow:execute IMPL-007 (HTTP API) <──┘
-```
-
-### Per-Task Execution Flow
-
-```
-For Each Task (IMPL-001 to IMPL-007):
-
-/workflow:execute IMPL-NNN
- ↓
-Check dependencies (if specified in depends_on)
- ↓
-TodoWrite: pending → in_progress
- ↓
-Execute flow_control (pre_analysis steps)
- ↓
-Generate Documentation (apply template)
- ↓
-TodoWrite: in_progress → completed
- ↓
-✅ Task Complete
-```
-
-### TodoWrite Status Tracking
-
-**Planning Phase**:
-```
-✅ Session initialization (completed)
-⏳ IMPL-001: Project Overview (pending)
-⏳ IMPL-002: Module 'auth' (pending)
-```
-
-**Execution Phase**:
-```
-Executing IMPL-001:
-✅ Session initialization
-🔄 IMPL-001: Project Overview (in_progress)
-⏳ IMPL-002: Module 'auth'
-
-After IMPL-001:
-✅ Session initialization
-✅ IMPL-001: Project Overview (completed)
-🔄 IMPL-002: Module 'auth' (in_progress)
-```
-
-## Documentation Output
-
-### Final Structure (Revised)
-```
-.workflow/docs/
-├── modules/ # IMPL-001,002,003 (Level 1)
-│ ├── README.md # Navigation for modules/
-│ ├── auth/
-│ │ ├── API.md # Auth module API signatures
-│ │ ├── README.md # Auth module documentation
-│ │ └── middleware/
-│ │ ├── API.md # Middleware API
-│ │ └── README.md # Middleware docs
-│ └── api/
-│ ├── API.md # API module signatures
-│ └── README.md # API module docs
-├── README.md # IMPL-004 (Level 2) - Project overview
-├── ARCHITECTURE.md # IMPL-005 (Level 3) - System architecture
-├── EXAMPLES.md # IMPL-006 (Level 3) - Usage examples
-└── api/ # IMPL-007 (Level 3, Optional)
- └── README.md # HTTP API reference
-```
-
-## Next Steps
-
-### 1. Review Planning Output
-```bash
-cat .workflow/WFS-docs-*/IMPL_PLAN.md
-cat .workflow/WFS-docs-*/TODO_LIST.md
-```
-
-### 2. Execute Documentation Tasks
-```bash
-# Sequential (recommended)
-/workflow:execute IMPL-001 # System overview first
-/workflow:execute IMPL-002 # Module docs
-/workflow:execute IMPL-003
-/workflow:execute IMPL-004 # Architecture
-/workflow:execute IMPL-005 # API docs
-
-# Parallel (module docs only)
-/workflow:execute IMPL-002 &
-/workflow:execute IMPL-003 &
-wait
-```
-
-### 3. Review Generated Documentation
-```bash
-ls -lah .workflow/docs/
-cat .workflow/docs/README.md
-```
-
-### 4. TodoWrite Progress
-- Planning: All tasks `pending`
-- Execution: `pending` → `in_progress` → `completed`
-- Real-time status updates via TodoWrite
-
-## Error Handling
+### Error Handling
- **No modules found**: Create only IMPL-001 (system overview)
-- **Scope path invalid**: Show error and exit
+- **Invalid path**: Show error and exit
- **Active session exists**: Prompt to complete or pause
- **Tool unavailable**: Fall back to gemini
-## Key Benefits
+### Next Steps
-### Bottom-Up Documentation Strategy
-- **Self-contained modules first**: Each module gets complete documentation (API.md + README.md)
-- **Project-level aggregation**: README, Architecture, Examples synthesize from completed modules
-- **No premature aggregation**: Project docs wait for all module docs to complete
+```bash
+# 1. Review planning output
+cat .workflow/WFS-docs-*/IMPL_PLAN.md
+cat .workflow/WFS-docs-*/TODO_LIST.md
-### Dynamic Folder Structure Recognition
-- **No hardcoded paths**: Automatically discovers all project directories
-- **Intelligent type detection**: Code folders get API.md + README.md, navigation folders get README.md only
-- **Respects project structure**: Works with any directory layout (not just "modules/")
+# 2. Execute tasks (respects dependencies)
+/workflow:execute IMPL-001
+/workflow:execute IMPL-002
+/workflow:execute IMPL-003
+# ... then Level 2 and 3 if root
-### Clear Separation of Concerns
-- **API.md**: Pure interface signatures (what can be called)
-- **README.md**: Purpose, usage, concepts (how and why to use it)
-- **Architecture.md**: System design and module relationships
-- **Examples.md**: End-to-end usage scenarios
-
-### Correct Dependency Management
-- **Level 1** (Module trees): Can execute in parallel
-- **Level 2** (Project README): Must wait for all module docs
-- **Level 3** (Architecture/Examples): Must wait for project README
-- **Prevents incomplete aggregation**: Ensures all source data exists before synthesis
-
-### Scalable Task Management
-- **Coarse-grained tasks**: One task per top-level directory tree (not per module)
-- **Recursive processing**: Each task handles all subfolders within its tree
-- **Reduced task count**: 3 tree tasks instead of 10+ module tasks
-
-### Template-Driven Consistency
-- **5 specialized templates**: api (unified), module-readme, folder-navigation, project-architecture, project-examples
-- **Clear template purpose**: Each template focuses on a single documentation aspect
-- **Unified API template**: Single api.txt handles both Code API (Part A) and HTTP API (Part B)
-- **No content duplication**: API signatures stay in API.md, usage stays in README.md
+# 3. Review generated documentation
+ls -lah .workflow/docs/
+cat .workflow/docs/README.md
+```