feat: Update workflow plan command to reference docs command output

- Add pre-analysis documentation check as first step - Reference specific paths from /workflow:docs output structure - Update flow_control to selectively load relevant documentation - Remove outdated plan-deep command - Add new doc-generator agent and workflow files 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2026-02-12 02:37:45 +08:00 · 2025-09-18 18:48:51 +08:00
parent fc6e851230
commit f39f1082d7
6 changed files with 1032 additions and 335 deletions
--- a/.claude/commands/workflow/docs.md
+++ b/.claude/commands/workflow/docs.md
@@ -0,0 +1,210 @@
+---
+name: docs
+description: Generate hierarchical architecture and API documentation using doc-generator agent with flow_control
+usage: /workflow:docs <type> [scope]
+argument-hint: "architecture"|"api"|"all"
+examples:
+  - /workflow:docs all
+  - /workflow:docs architecture src/modules
+  - /workflow:docs api --scope api/
+---
+
+# Hierarchical Documentation Generator
+
+## Usage
+```bash
+/workflow:docs <type> [scope]
+```
+
+## Document Types
+- **architecture**: System architecture documentation (bottom-up analysis)
+- **api**: API interface documentation (module-first approach)
+- **all**: Complete documentation suite with full hierarchy (default)
+
+## Generation Strategy
+Uses **doc-generator agent** with **flow_control** for structured documentation generation:
+1. Agent receives task with embedded flow_control structure
+2. Agent executes pre_analysis steps using CLI tools
+3. Agent generates hierarchical documentation (module → system)
+4. Agent tracks progress with TodoWrite throughout process
+
+## Output Structure
+```
+.workflow/docs/
+├── README.md              # System navigation
+├── modules/               # Level 1: Module documentation
+│   ├── [module-1]/
+│   │   ├── overview.md
+│   │   ├── api.md
+│   │   ├── dependencies.md
+│   │   └── examples.md
+│   └── [module-n]/...
+├── architecture/          # Level 2: System architecture
+│   ├── system-design.md
+│   ├── module-map.md
+│   ├── data-flow.md
+│   └── tech-stack.md
+└── api/                   # Level 2: Unified API docs
+    ├── unified-api.md
+    └── openapi.yaml
+```
+
+## Complete Documentation Generation (All Types)
+
+### Agent Task Invocation
+```bash
+Task(
+  description="Generate complete system documentation",
+  prompt="[FLOW_CONTROL] You are the doc-generator agent tasked with creating comprehensive system documentation. Execute the embedded flow_control structure for hierarchical documentation generation.
+
+Your flow_control includes these pre_analysis steps:
+1. Initialize TodoWrite tracking for documentation process
+2. Discover project modules using bash commands
+3. Analyze project structure with gemini-wrapper
+4. Perform deep module analysis with gemini-wrapper
+5. Scan API endpoints using bash/rg commands
+6. Analyze API structure with gemini-wrapper
+
+After pre_analysis, generate documentation:
+- Create module documentation in .workflow/docs/modules/
+- Generate architecture docs in .workflow/docs/architecture/
+- Create unified API docs in .workflow/docs/api/
+- Build main navigation in .workflow/docs/README.md
+
+Use TodoWrite to track progress and update status as you complete each phase.",
+  subagent_type="doc-generator"
+)
+```
+
+## Architecture-Only Documentation
+
+### Agent Task for Architecture Focus
+```bash
+Task(
+  description="Generate architecture documentation",
+  prompt="[FLOW_CONTROL] You are the doc-generator agent focused on architecture documentation.
+
+Execute flow_control with these pre_analysis steps:
+1. Initialize TodoWrite for architecture documentation tracking
+2. Analyze system architecture with gemini-wrapper using comprehensive architectural analysis rules
+3. Generate architecture documentation in .workflow/docs/architecture/
+
+Focus on system design, module relationships, and technology stack documentation.",
+  subagent_type="doc-generator"
+)
+```
+
+## API-Only Documentation
+
+### Agent Task for API Focus
+```bash
+Task(
+  description="Generate API documentation",
+  prompt="[FLOW_CONTROL] You are the doc-generator agent focused on API documentation.
+
+Execute flow_control with these pre_analysis steps:
+1. Initialize TodoWrite for API documentation tracking
+2. Scan for API endpoints using bash/rg commands
+3. Analyze API patterns with gemini-wrapper for comprehensive documentation
+4. Generate API documentation in .workflow/docs/api/
+
+Create complete API reference with OpenAPI specifications and usage examples.",
+  subagent_type="doc-generator"
+)
+```
+
+## Flow Control Templates
+
+The doc-generator agent internally uses these flow_control structures:
+
+### Complete Documentation Flow Control
+- **initialize_tracking**: Set up TodoWrite progress tracking
+- **discover_modules**: Find project modules with bash commands
+- **analyze_project_structure**: Comprehensive analysis with gemini-wrapper
+- **analyze_individual_modules**: Deep module analysis with gemini-wrapper
+- **scan_api_endpoints**: API endpoint discovery with bash/rg
+- **analyze_api_structure**: API documentation with gemini-wrapper
+
+### Architecture Flow Control
+- **initialize_architecture_tracking**: TodoWrite setup for architecture
+- **analyze_architecture**: System architecture analysis with gemini-wrapper
+
+### API Flow Control
+- **initialize_api_tracking**: TodoWrite setup for API documentation
+- **scan_apis**: API endpoint scanning with bash/rg
+- **analyze_api_patterns**: API documentation with gemini-wrapper
+
+## Analysis Templates
+
+### Project Structure Analysis Rules
+- Identify main modules and purposes
+- Map directory organization patterns
+- Extract entry points and configuration files
+- Recognize architectural styles and design patterns
+- Analyze module relationships and dependencies
+- Document technology stack and requirements
+
+### Module Analysis Rules
+- Identify module boundaries and entry points
+- Extract exported functions, classes, interfaces
+- Document internal organization and structure
+- Analyze API surfaces with types and parameters
+- Map dependencies within and between modules
+- Extract usage patterns and examples
+
+### API Analysis Rules
+- Classify endpoint types (REST, GraphQL, WebSocket, RPC)
+- Extract request/response parameters and schemas
+- Document authentication and authorization requirements
+- Generate OpenAPI 3.0 specification structure
+- Create comprehensive endpoint documentation
+- Provide usage examples and integration guides
+
+## Integration with Workflow System
+
+### Automatic Context Loading
+- Generated documentation serves as context for `/workflow:plan` and `/workflow:execute`
+- Documentation provides single source of truth for system understanding
+- Other workflow commands automatically reference `.workflow/docs/` for context
+
+### Progressive Enhancement
+- Documentation builds incrementally from modules to system
+- Individual modules can be re-documented as needed
+- System documentation synthesizes from module-level understanding
+
+## Key Benefits
+
+### Agent + Flow Control Architecture
+- **Unified Execution**: All documentation generation through doc-generator agent
+- **Structured Analysis**: Flow control ensures systematic context gathering
+- **CLI Tool Integration**: Agent uses bash, gemini-wrapper, and codex internally
+- **Progress Tracking**: TodoWrite provides visibility throughout process
+
+### Hierarchical Documentation
+- **Bottom-up Analysis**: Start with detailed module understanding
+- **System Synthesis**: Build unified documentation from module knowledge
+- **Two-level Architecture**: Module-level and system-level documentation
+
+### Quality and Consistency
+- **Flow Control Ensures Completeness**: Structured analysis prevents missing components
+- **Agent Expertise**: Specialized doc-generator provides consistent quality
+- **Tool Optimization**: Right tool for each analysis phase
+- **Error Recovery**: Progress tracking enables recovery from failures
+
+## Usage Examples
+
+```bash
+# Generate complete documentation suite
+/workflow:docs all
+
+# Generate only architecture documentation
+/workflow:docs architecture
+
+# Generate only API documentation
+/workflow:docs api
+
+# Generate scoped documentation
+/workflow:docs architecture src/core,src/auth
+```
+
+The system executes the appropriate agent task with embedded flow_control, ensuring systematic and comprehensive documentation generation.
--- a/.claude/commands/workflow/plan-deep.md
+++ b/.claude/commands/workflow/plan-deep.md
@@ -1,238 +0,0 @@
---
-name: plan-deep
-description: Deep technical planning with Gemini CLI analysis and action-planning-agent
-usage: /workflow:plan-deep <task_description>
-argument-hint: "task description" | requirements.md
-examples:
-  - /workflow:plan-deep "Refactor authentication system to use JWT"
-  - /workflow:plan-deep "Implement real-time notifications across modules"
-  - /workflow:plan-deep requirements.md
---
-
-# Workflow Plan Deep Command (/workflow:plan-deep)
-
-## Overview
-Creates comprehensive implementation plans through deep codebase analysis using Gemini CLI and the action-planning-agent. This command enforces multi-dimensional context gathering before planning, ensuring technical decisions are grounded in actual codebase understanding.
-
-## Key Differentiators
-
-### vs /workflow:plan
-| Feature | /workflow:plan | /workflow:plan-deep |
-|---------|---------------|-------------------|
-| **Analysis Depth** | Basic requirements extraction | Deep codebase analysis |
-| **Gemini CLI** | Optional | **Mandatory (via agent)** |
-| **Context Scope** | Current input only | Multi-dimensional analysis |
-| **Agent Used** | None (direct processing) | action-planning-agent |
-| **Output Detail** | Standard IMPL_PLAN | Enhanced hierarchical plan |
-| **Best For** | Quick planning | Complex technical tasks |
-
-## When to Use This Command
-
-### Ideal Scenarios
- **Cross-module refactoring** requiring understanding of multiple components
- **Architecture changes** affecting system-wide patterns
- **Complex feature implementation** spanning >3 modules
- **Performance optimization** requiring deep code analysis
- **Security enhancements** needing comprehensive vulnerability assessment
- **Technical debt resolution** with broad impact
-
-### Not Recommended For
- Simple, single-file changes
- Documentation updates
- Configuration adjustments
- Tasks with clear, limited scope
-
-## Execution Flow
-
-### 1. Input Processing
-```
-Input Analysis:
-├── Validate input clarity (reject vague descriptions)
-├── Parse task description or file
-├── Extract key technical terms
-├── Identify potential affected domains
-└── Prepare context for agent
-```
-
-**Clarity Requirements**:
- **Minimum specificity**: Must include clear technical goal and affected components
- **Auto-rejection**: Vague inputs like "optimize system", "refactor code", "improve performance" without context
- **Response**: `❌ Input too vague. Deep planning requires specific technical objectives and component scope.`
-
-### 2. Agent Invocation with Deep Analysis Flag
-The command invokes action-planning-agent with special parameters that **enforce** Gemini CLI analysis.
-
-### 3. Agent Processing (Delegated to action-planning-agent)
-
-**Agent Execution Flow**:
-```
-Agent receives DEEP_ANALYSIS_REQUIRED flag
-├── Executes 4-dimension Gemini CLI analysis in parallel:
-│   ├── Architecture Analysis (patterns, components)
-│   ├── Code Pattern Analysis (conventions, standards)
-│   ├── Impact Analysis (affected modules, dependencies)
-│   └── Testing Requirements (coverage, patterns)
-├── Consolidates Gemini results into gemini-analysis.md
-├── Creates workflow session directory
-├── Generates hierarchical IMPL_PLAN.md
-├── Creates TODO_LIST.md for tracking
-└── Saves all outputs to .workflow/WFS-[session-id]/
-```
-```markdown
-Task(action-planning-agent):
-  description: "Deep technical planning with mandatory codebase analysis"
-  prompt: |
-    Create implementation plan for: [task_description]
-    
-    EXECUTION MODE: DEEP_ANALYSIS_REQUIRED
-    
-    MANDATORY REQUIREMENTS:
-    - Execute comprehensive Gemini CLI analysis (4 dimensions)
-    - Skip PRD processing (no PRD provided)
-    - Skip session inheritance (standalone planning)
-    - Force FLOW_CONTROL flag = true
-    - Set pre_analysis = multi-step array format with comprehensive analysis steps
-    - Generate hierarchical task decomposition (max 2 levels: IMPL-N.M)
-    - Create detailed IMPL_PLAN.md with subtasks
-    - Generate TODO_LIST.md for tracking
-    
-    GEMINI ANALYSIS DIMENSIONS (execute in parallel):
-    1. Architecture Analysis - design patterns, component relationships
-    2. Code Pattern Analysis - conventions, error handling, validation
-    3. Impact Analysis - affected modules, breaking changes
-    4. Testing Requirements - coverage needs, test patterns
-    
-    FOCUS: Technical implementation based on deep codebase understanding
-```
-
-### 4. Output Generation (by Agent)
-The action-planning-agent generates in `.workflow/WFS-[session-id]/`:
- **IMPL_PLAN.md** - Hierarchical implementation plan with stages
- **TODO_LIST.md** - Unified hierarchical task tracking with ▸ container tasks and indented subtasks
- **.task/*.json** - Task definitions for complex projects
- **workflow-session.json** - Session tracking
- **gemini-analysis.md** - Consolidated Gemini analysis results
-
-## Command Processing Logic
-
-```python
-def process_plan_deep_command(input):
-    # Step 1: Parse input
-    task_description = parse_input(input)
-    
-    # Step 2: Build agent prompt with deep analysis flag
-    agent_prompt = f"""
-    EXECUTION_MODE: DEEP_ANALYSIS_REQUIRED
-    TASK: {task_description}
-    
-    MANDATORY FLAGS:
-    - FLOW_CONTROL = true
-    - pre_analysis = multi-step array format for comprehensive pre-analysis
-    - FORCE_PARALLEL_ANALYSIS = true
-    - SKIP_PRD = true
-    - SKIP_SESSION_INHERITANCE = true
-    
-    Execute comprehensive Gemini CLI analysis before planning.
-    """
-    
-    # Step 3: Invoke action-planning-agent
-    # Agent will handle session creation and Gemini execution
-    Task(
-        subagent_type="action-planning-agent",
-        description="Deep technical planning with mandatory analysis",
-        prompt=agent_prompt
-    )
-    
-    # Step 4: Agent handles all processing and outputs
-    return "Agent executing deep analysis and planning..."
-```
-
-## Error Handling
-
-### Common Issues and Solutions
-
-**Input Processing Errors**
- **Vague text input**: Auto-reject without guidance
-  - Rejected examples: "optimize system", "refactor code", "make it faster", "improve architecture"
-  - Response: Direct rejection message, no further assistance
-
-**Agent Execution Errors**
- Verify action-planning-agent availability
- Check for context size limits
- Agent handles Gemini CLI failures internally
-
-**Gemini CLI Failures (handled by agent)**
- Agent falls back to file-pattern based analysis
- Agent retries with reduced scope automatically
- Agent alerts if critical analysis fails
-
-**File Access Issues**
- Verify permissions for workflow directory
- Check file patterns for validity
- Alert on missing CLAUDE.md files
-
-## Integration Points
-
-### Related Commands
- `/workflow:plan` - Quick planning without deep analysis
- `/workflow:execute` - Execute generated plans
- `/workflow:review` - Review implementation progress
- `/context` - View generated planning documents
-
-### Agent Dependencies
- **action-planning-agent** - Core planning engine
- **code-developer** - For execution phase
- **code-review-agent** - For quality checks
-
-## Usage Examples
-
-### Example 1: Cross-Module Refactoring
-```bash
-/workflow:plan-deep "Refactor user authentication to use JWT tokens across all services"
-```
-Generates comprehensive plan analyzing:
- Current auth implementation
- All affected services
- Migration strategy
- Testing requirements
-
-### Example 2: Performance Optimization
-```bash
-/workflow:plan-deep "Optimize database query performance in reporting module"
-```
-Creates detailed plan including:
- Current query patterns analysis
- Bottleneck identification
- Optimization strategies
- Performance testing approach
-
-### Example 3: Architecture Enhancement
-```bash
-/workflow:plan-deep "Implement event-driven architecture for order processing"
-```
-Produces hierarchical plan with:
- Current architecture assessment
- Event flow design
- Module integration points
- Staged migration approach
-
-## Best Practices
-
-1. **Use for Complex Tasks**: Reserve for tasks requiring deep understanding
-2. **Provide Clear Descriptions**: Specific task descriptions yield better analysis
-3. **Review Gemini Output**: Check analysis results for accuracy
-4. **Iterate on Plans**: Refine based on initial analysis
-5. **Track Progress**: Use generated TODO_LIST.md for execution
-
-## Technical Notes
-
- **Agent-Driven Analysis**: action-planning-agent executes all Gemini CLI commands
- **Parallel Execution**: Agent runs 4 Gemini analyses concurrently for performance
- **Context Management**: Agent handles context size limits automatically
- **Structured Handoff**: Command passes DEEP_ANALYSIS_REQUIRED flag to agent
- **Session Management**: Agent creates and manages workflow session
- **Output Standards**: All documents follow established workflow formats
-
---
-
-**System ensures**: Deep technical understanding before planning through mandatory Gemini CLI analysis and intelligent agent orchestration
--- a/.claude/commands/workflow/plan.md
+++ b/.claude/commands/workflow/plan.md
@@ -21,28 +21,47 @@ examples:
 - **Issues**: `ISS-*`, `ISSUE-*`, `*-request-*` → Loads issue data and acceptance criteria
 - **Text**: Everything else → Parses natural language requirements

-## Default Analysis Workflow
+## Core Workflow

-### Automatic Intelligence Selection
-The command automatically performs comprehensive analysis by:
-1. **Context Gathering**: Reading relevant CLAUDE.md documentation based on task requirements
-2. **Task Assignment**: Automatically assigning Task agents based on complexity:
-   - **Simple tasks** (≤3 modules): Direct CLI tools (`~/.claude/scripts/gemini-wrapper` or `codex --full-auto exec`)
-   - **Complex tasks** (>3 modules): Task agents with integrated CLI tool access
-3. **Process Documentation**: Generates analysis artifacts in `.workflow/WFS-[session]/.process/ANALYSIS_RESULTS.md`
-4. **Flow Control Integration**: Automatic tool selection managed by flow_control system
+### Analysis & Planning Process
+The command performs comprehensive analysis through:

-### Analysis Artifacts Generated
- **ANALYSIS_RESULTS.md**: Documents context analysis, codebase structure, pattern identification, and task decomposition results
- **Context mapping**: Project structure, dependencies, and cohesion groups
+**0. Pre-Analysis Documentation Check** ⚠️ FIRST STEP
+- **Selective documentation loading based on task requirements**:
+  - **Always check**: `.workflow/docs/README.md` - System navigation and module index
+  - **For architecture tasks**: `.workflow/docs/architecture/system-design.md`, `module-map.md`
+  - **For specific modules**: `.workflow/docs/modules/[relevant-module]/overview.md`
+  - **For API tasks**: `.workflow/docs/api/unified-api.md`
+- **Context-driven selection**: Only load documentation relevant to the specific task scope
+- **Foundation for analysis**: Use relevant docs to understand affected components and dependencies
+
+**1. Context Gathering & Intelligence Selection**
+- Reading relevant CLAUDE.md documentation based on task requirements
+- Automatic tool assignment based on complexity:
+  - **Simple tasks** (≤3 modules): Direct CLI tools (`~/.claude/scripts/gemini-wrapper` or `codex --full-auto exec`)
+  - **Complex tasks** (>3 modules): Task agents with integrated CLI tool access
+- Flow control integration with automatic tool selection
+
+**2. Project Structure Analysis** ⚠️ CRITICAL PRE-PLANNING STEP
+- **Documentation Context First**: Reference `.workflow/docs/` content from `/workflow:docs` command if available
+- **Complexity assessment**: Count total saturated tasks
+- **Decomposition strategy**: Flat (≤5) | Hierarchical (6-10) | Re-scope (>10)
+- **Module boundaries**: Identify relationships and dependencies using existing documentation
+- **File grouping**: Cohesive file sets and target_files generation
+- **Pattern recognition**: Existing implementations and conventions
+
+**3. Analysis Artifacts Generated**
+- **ANALYSIS_RESULTS.md**: Context analysis, codebase structure, pattern identification, task decomposition
+- **Context mapping**: Project structure, dependencies, cohesion groups
 - **Implementation strategy**: Tool selection and execution approach

-## Core Rules
+## Implementation Standards

-### Agent Execution Context (CRITICAL)
-⚠️ **For agent execution phase**: Agents will automatically load context from plan-generated documents
+### Context Management & Agent Execution
+
+**Agent Context Loading** ⚠️ CRITICAL
+Agents automatically load context from plan-generated documents during execution:

-**Agent Context Loading Pattern**:
 ```json
 "flow_control": {
  "pre_analysis": [
@@ -51,7 +70,7 @@ The command automatically performs comprehensive analysis by:
      "action": "Load plan-generated analysis and context",
      "command": "bash(cat .workflow/WFS-[session]/.process/ANALYSIS_RESULTS.md 2>/dev/null || echo 'planning analysis not found')",
      "output_to": "planning_context"
-    }, // 可选：Task任务较为复杂时
+    },
    {
      "step": "load_dependencies",
      "action": "Retrieve dependency task summaries",
@@ -60,52 +79,48 @@ The command automatically performs comprehensive analysis by:
    },
    {
      "step": "load_documentation",
-      "action": "Retrieve project documentation based on task requirements",
-      "command": "bash(cat CLAUDE.md README.md 2>/dev/null || echo 'documentation not found')",
+      "action": "Retrieve relevant documentation based on task scope and requirements",
+      "command": "bash(cat .workflow/docs/README.md $(if [[ \"$TASK_TYPE\" == *\"architecture\"* ]]; then echo .workflow/docs/architecture/*.md; fi) $(if [[ \"$TASK_MODULES\" ]]; then for module in $TASK_MODULES; do echo .workflow/docs/modules/$module/*.md; done; fi) $(if [[ \"$TASK_TYPE\" == *\"api\"* ]]; then echo .workflow/docs/api/*.md; fi) CLAUDE.md README.md 2>/dev/null || echo 'documentation not found')",
      "output_to": "doc_context"
    }
  ]
 }
 ```

-**Trigger Conditions**:
- Task has `context.depends_on` array with task IDs
- Task references external documentation files
- Task builds upon previous implementation summaries
- Task requires configuration or schema files
+**Context Accumulation & Inheritance**:
+1. **Structure Analysis**: project hierarchy
+2. **Pattern Analysis**: Tool-specific commands → existing patterns
+3. **Dependency Mapping**: Previous task summaries → inheritance context
+4. **Task Context Generation**: Combined analysis → task.context fields

 **Content Sources**:
- Task summaries: `.workflow/WFS-[session]/.summaries/IMPL-[task-id]-summary.md` (主任务) / `IMPL-[task-id].[subtask-id]-summary.md` (子任务)
- Documentation: `CLAUDE.md`, `README.md`, config files (loaded based on task context requirements)
+- Task summaries: `.workflow/WFS-[session]/.summaries/IMPL-[task-id]-summary.md`
+- Generated documentation: `.workflow/docs/` (architecture, modules, APIs from `/workflow:docs`)
+- Documentation: `CLAUDE.md`, `README.md`, config files
 - Schema definitions: `.json`, `.yaml`, `.sql` files
 - Dependency contexts: `.workflow/WFS-[session]/.task/IMPL-*.json`
 - Analysis artifacts: `.workflow/WFS-[session]/.process/ANALYSIS_RESULTS.md`

-### File Structure Reference
-**Architecture**: @~/.claude/workflows/workflow-architecture.md
+**Trigger Conditions**: Task has `context.depends_on` array, references external docs, builds on previous summaries, requires config/schema files

+### Task Decomposition Standards

-### Task Limits & Decomposition
+**Core Principles**:
+1. **Functional Completeness** - Each task delivers complete, independently runnable functional unit including all related files (logic, UI, tests, config)
+2. **Minimum Size Threshold** - Single task must contain ≥3 related files or 200 lines of code; smaller content merged with adjacent features
+3. **Dependency Cohesion** - Tightly coupled components completed in same task (shared models, API endpoints, user flows)
+4. **Hierarchy Control** - Flat structure (≤5 tasks) | Two-level (6-10 tasks) | Re-scope (>10 tasks)
+
+**Implementation Rules**:
 - **Maximum 10 tasks**: Hard enforced limit - projects exceeding must be re-scoped
 - **Function-based decomposition**: By complete functional units, not files/steps
 - **File cohesion**: Group related files (UI + logic + tests + config) in same task
 - **Task saturation**: Merge "analyze + implement" by default (0.5 count for complex prep tasks)

-### Core Task Decomposition Standards
-1. **Functional Completeness Principle** - Each task must deliver a complete, independently runnable functional unit including all related files (logic, UI, tests, config)
+**Task Saturation Assessment**:
+- **Default Merge** (cohesive files together): Functional modules with UI + logic + tests + config, features with tests/docs, files sharing interfaces/data structures
+- **Only Separate When**: Independent functional modules, different tech stacks/deployment units, would exceed 10-task limit

-2. **Minimum Size Threshold** - A single task must contain at least 3 related files or 200 lines of code; content below this threshold must be merged with adjacent features
-
-3. **Dependency Cohesion Principle** - Tightly coupled components must be completed in the same task, including shared data models, same API endpoints, and all parts of a single user flow
-
-4. **Hierarchy Control Rule** - Use flat structure for ≤5 tasks, two-level structure for 6-10 tasks, and mandatory re-scoping into multiple iterations for >10 tasks
-
-### Pre-Planning Analysis (CRITICAL)
-⚠️ **Must complete BEFORE generating any plan documents**
-1. **Complexity assessment**: Count total saturated tasks
-2. **Decomposition strategy**: Flat (≤5) | Hierarchical (6-10) | Re-scope (>10)
-3. **File grouping**: Identify cohesive file sets
-4. **Quantity prediction**: Estimate main tasks, subtasks, container vs leaf ratio

 ### Session Management ⚠️ CRITICAL
 - **⚡ FIRST ACTION**: Check for all `.workflow/.active-*` markers before any planning
@@ -116,53 +131,25 @@ The command automatically performs comprehensive analysis by:
 - **⚠️ Dependency context**: MUST read ALL previous task summary documents from selected session before planning
 - **Session isolation**: Each session maintains independent context and state

-### Project Structure Analysis & Engineering Enhancement
-**⚠️ CRITICAL PRE-PLANNING STEP**: Must complete comprehensive project analysis before any task planning begins
-**Analysis Process**: Context Gathering → Codebase Exploration → Pattern Recognition → Implementation Strategy
-**Tool Selection Protocol** (Managed by flow_control):
- **Simple patterns** (≤3 modules): Direct CLI tools (`~/.claude/scripts/gemini-wrapper` or `codex --full-auto exec`)
- **Complex analysis** (>3 modules): Task agents with integrated CLI tool access and built-in tool capabilities
-**Tool Priority**: Task(complex) > Direct CLI(simple) > Hybrid(mixed complexity)
-**Automatic Selection**: flow_control system determines optimal tool based on task complexity and context requirements

-**Core Principles**:
- **Complexity-Driven Selection**: Simple patterns use direct CLI, complex analysis uses Task agents with CLI integration
- **Context-First Approach**: Always gather project understanding before tool selection
- **Intelligent Escalation**: Start CLI, escalate to Task agents when encountering complexity
- **Hybrid Flexibility**: Task agents can freely use CLI commands and built-in tools for comprehensive analysis
+**Task Patterns**:
+- ✅ **Correct (Function-based)**: `IMPL-001: User authentication system` (models + routes + components + middleware + tests)
+- ❌ **Wrong (File/step-based)**: `IMPL-001: Create database model`, `IMPL-002: Create API endpoint`

-**Structure Integration**:
- Identifies module boundaries and relationships
- Maps file dependencies and cohesion groups
- Populates task.context.focus_paths automatically
- Enables precise target_files generation
+## Document Generation

-## Task Patterns
+**Workflow**: Identifier Creation → Folder Structure → IMPL_PLAN.md → .task/IMPL-NNN.json → TODO_LIST.md

-### ✅ Correct (Function-based)
- `IMPL-001: User authentication system` (models + routes + components + middleware + tests)
- `IMPL-002: Data export functionality` (service + routes + UI + utils + tests)
-
-### ❌ Wrong (File/step-based)
- `IMPL-001: Create database model`
- `IMPL-002: Create API endpoint`
- `IMPL-003: Create frontend component`
-
-## Output Documents
-
-### Document Workflow
-**Identifier Creation** → **Folder Structure Creation** → **IMPL_PLAN.md** → **.task/IMPL-NNN.json** → **TODO_LIST.md**
-
-### Always Created
+**Always Created**:
 - **IMPL_PLAN.md**: Requirements, task breakdown, success criteria
 - **Session state**: Task references and paths

-### Auto-Created (complexity > simple)
+**Auto-Created (complexity > simple)**:
 - **TODO_LIST.md**: Hierarchical progress tracking
 - **.task/*.json**: Individual task definitions with flow_control
- **.process/ANALYSIS_RESULTS.md**: Analysis results and planning artifacts.Template:@~/.claude/workflows/ANALYSIS_RESULTS.md
+- **.process/ANALYSIS_RESULTS.md**: Analysis results and planning artifacts

-### Document Structure
+**Document Structure**:
 ```
 .workflow/WFS-[topic]/
 ├── IMPL_PLAN.md          # Main planning document
@@ -174,18 +161,10 @@ The command automatically performs comprehensive analysis by:
    └── IMPL-002.json
 ```

-## Task Saturation Assessment
-**Default Merge** (cohesive files together):
- Functional modules with UI + logic + tests + config
- Features with their tests and documentation
- Files sharing common interfaces/data structures

-**Only Separate When**:
- Completely independent functional modules
- Different tech stacks or deployment units
- Would exceed 10-task limit otherwise
+## Reference Information

-## Task JSON Schema (5-Field Architecture)
+### Task JSON Schema (5-Field Architecture)
 Each task.json uses the workflow-architecture.md 5-field schema:
 - **id**: IMPL-N[.M] format (max 2 levels)
 - **title**: Descriptive task name
@@ -194,7 +173,10 @@ Each task.json uses the workflow-architecture.md 5-field schema:
 - **context**: { requirements, focus_paths, acceptance, parent, depends_on, inherited, shared_context }
 - **flow_control**: { pre_analysis[], implementation_approach, target_files[] }

-## Execution Integration
+### File Structure Reference
+**Architecture**: @~/.claude/workflows/workflow-architecture.md
+
+### Execution Integration
 Documents created for `/workflow:execute`:
 - **IMPL_PLAN.md**: Context loading and requirements
 - **.task/*.json**: Agent implementation context
@@ -205,10 +187,4 @@ Documents created for `/workflow:execute`:
 - **File not found**: Clear suggestions
 - **>10 tasks**: Force re-scoping into iterations

-### Context Accumulation & Inheritance
-**Context Flow Process**:
-1. **Structure Analysis**: project hierarchy
-2. **Pattern Analysis**: Tool-specific commands → existing patterns
-3. **Dependency Mapping**: Previous task summaries → inheritance context
-4. **Task Context Generation**: Combined analysis → task.context fields