Release v4.4.1: Implementation approach structure refactoring

- Refactor implementation_approach from object to array format
- Add step-based execution with dependency management
- Add CLI execution mode support with --cli-execute flag
- Add Codex resume mechanism for context continuity
- Update 15 files across agents, commands, and core architecture
- Major docs.md refactoring (67% size reduction)
- Enhanced workflow-architecture.md with flow control documentation

.claude/agents/action-planning-agent.md

@@ -142,37 +142,6 @@ mcp__exa__get_code_context_exa(
 }
 ```
 
-**Legacy Pre-Execution Analysis** (backward compatibility):
-- **Multi-step Pre-Analysis**: Execute comprehensive analysis BEFORE implementation begins
-  - **Sequential Processing**: Process each step sequentially, expanding brief actions
-  - **Template Usage**: Use full template paths with $(cat template_path)
-  - **Method Selection**: gemini/codex/manual/auto-detected
-- **CLI Commands**:
-  - **Gemini**: `bash(~/.claude/scripts/gemini-wrapper -p "$(cat template_path) [action]")`
-  - **Codex**: `bash(codex --full-auto exec "$(cat template_path) [action]" -s danger-full-access)`
-- **Follow Guidelines**: @~/.claude/workflows/intelligent-tools-strategy.md 
-
-### Pre-Execution Analysis
-**When [MULTI_STEP_ANALYSIS] marker is present:**
-
-#### Multi-Step Pre-Analysis Execution
-1. Process each analysis step sequentially from pre_analysis array
-2. For each step:
-   - Expand brief action into comprehensive analysis task
-   - Use specified template with $(cat template_path)
-   - Execute with specified method (gemini/codex/manual/auto-detected)
-3. Accumulate results across all steps for comprehensive context
-4. Use consolidated analysis to inform implementation stages and task breakdown
-
-#### Analysis Dimensions Coverage
-- **Exa Research**: Use `mcp__exa__get_code_context_exa` for technology stack selection and API patterns
-- Architecture patterns and component relationships
-- Implementation conventions and coding standards
-- Module dependencies and integration points
-- Testing requirements and coverage patterns
-- Security considerations and performance implications
-3. Use Codex insights to create self-guided implementation stages
-
 ## Core Functions
 
 ### 1. Stage Design
@@ -222,11 +191,26 @@ Generate individual `.task/IMPL-*.json` files with:
         "output_to": "codebase_structure"
       }
     ],
-    "implementation_approach": {
-      "task_description": "Implement following synthesis specification",
-      "modification_points": ["Apply requirements"],
-      "logic_flow": ["Load spec", "Analyze", "Implement", "Validate"]
-    },
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Load and analyze synthesis specification",
+        "description": "Load synthesis specification from artifacts and extract requirements",
+        "modification_points": ["Load synthesis specification", "Extract requirements and design patterns"],
+        "logic_flow": ["Read synthesis specification from artifacts", "Parse architecture decisions", "Extract implementation requirements"],
+        "depends_on": [],
+        "output": "synthesis_requirements"
+      },
+      {
+        "step": 2,
+        "title": "Implement following specification",
+        "description": "Implement task requirements following consolidated synthesis specification",
+        "modification_points": ["Apply requirements from [synthesis_requirements]", "Modify target files", "Integrate with existing code"],
+        "logic_flow": ["Apply changes based on [synthesis_requirements]", "Implement core logic", "Validate against acceptance criteria"],
+        "depends_on": [1],
+        "output": "implementation"
+      }
+    ],
     "target_files": ["file:function:lines", "path/to/NewFile.ts"]
   }
 }

.claude/agents/code-developer.md

@@ -90,6 +90,32 @@ ELIF context insufficient OR task has flow control marker:
 - Get API examples: `mcp__exa__get_code_context_exa(query="React authentication hooks", tokensNum="dynamic")`
 - Update after changes: `mcp__code-index__refresh_index()`
 
+**Implementation Approach Execution**:
+When task JSON contains `flow_control.implementation_approach` array:
+1. **Sequential Processing**: Execute steps in order, respecting `depends_on` dependencies
+2. **Dependency Resolution**: Wait for all steps listed in `depends_on` before starting
+3. **Variable Substitution**: Use `[variable_name]` to reference outputs from previous steps
+4. **Step Structure**:
+   - `step`: Unique identifier (1, 2, 3...)
+   - `title`: Step title
+   - `description`: Detailed description with variable references
+   - `modification_points`: Code modification targets
+   - `logic_flow`: Business logic sequence
+   - `command`: Optional CLI command (only when explicitly specified)
+   - `depends_on`: Array of step numbers that must complete first
+   - `output`: Variable name for this step's output
+5. **Execution Rules**:
+   - Execute step 1 first (typically has `depends_on: []`)
+   - For each subsequent step, verify all `depends_on` steps completed
+   - Substitute `[variable_name]` with actual outputs from previous steps
+   - Store this step's result in the `output` variable for future steps
+   - If `command` field present, execute it; otherwise use agent capabilities
+
+**CLI Command Execution (CLI Execute Mode)**:
+When step contains `command` field with Codex CLI, execute via Bash tool. For Codex resume:
+- First task (`depends_on: []`): `codex -C [path] --full-auto exec "..." --skip-git-repo-check -s danger-full-access`
+- Subsequent tasks (has `depends_on`): Add `resume --last` flag to maintain session context
+
 **Test-Driven Development**:
 - Write tests first (red → green → refactor)
 - Focus on core functionality and edge cases

.claude/agents/conceptual-planning-agent.md

@@ -83,6 +83,54 @@ def handle_brainstorm_assignment(prompt):
         generate_brainstorm_analysis(role, context_vars, output_location, topic)
 ```
 
+## Flow Control Format Handling
+
+This agent processes **simplified inline [FLOW_CONTROL]** format from brainstorm workflows.
+
+### Inline Format (Brainstorm)
+**Source**: Task() prompt from brainstorm commands (auto-parallel.md, etc.)
+
+**Structure**: Markdown list format (3-5 steps)
+
+**Example**:
+```markdown
+[FLOW_CONTROL]
+
+### Flow Control Steps
+1. **load_topic_framework**
+   - Action: Load structured topic framework
+   - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
+   - Output: topic_framework
+
+2. **load_role_template**
+   - Action: Load role-specific planning template
+   - Command: bash($(cat "~/.claude/workflows/cli-templates/planning-roles/{role}.md"))
+   - Output: role_template
+
+3. **load_session_metadata**
+   - Action: Load session metadata
+   - Command: bash(cat .workflow/WFS-{session}/workflow-session.json)
+   - Output: session_metadata
+```
+
+**Characteristics**:
+- 3-5 simple context loading steps
+- Written directly in prompt (not persistent)
+- No dependency management
+- Used for temporary context preparation
+
+### NOT Handled by This Agent
+
+**JSON format** (used by code-developer, test-fix-agent):
+```json
+"flow_control": {
+  "pre_analysis": [...],
+  "implementation_approach": [...]
+}
+```
+
+This complete JSON format is stored in `.task/IMPL-*.json` files and handled by implementation agents, not conceptual-planning-agent.
+
 ### Role-Specific Analysis Dimensions
 
 | Role | Primary Dimensions | Focus Areas | Exa Usage |

.claude/agents/doc-generator.md

@@ -68,8 +68,17 @@ You are an expert technical documentation specialist. Your responsibility is to
 
 ### 3. Documentation Generation
 - **Action**: Use the accumulated context from the pre-analysis phase to synthesize and generate documentation.
-- **Instructions**: Follow the `implementation_approach` defined in the `flow_control` block.
-- **Templates**: Apply templates as specified in `meta.template` or `implementation_approach`.
+- **Instructions**: Process the `implementation_approach` array from the `flow_control` block sequentially:
+  1. **Array Structure**: `implementation_approach` is an array of step objects
+  2. **Sequential Execution**: Execute steps in order, respecting `depends_on` dependencies
+  3. **Variable Substitution**: Use `[variable_name]` to reference outputs from previous steps
+  4. **Step Processing**:
+     - Verify all `depends_on` steps completed before starting
+     - Follow `modification_points` and `logic_flow` for each step
+     - Execute `command` if present, otherwise use agent capabilities
+     - Store result in `output` variable for future steps
+  5. **CLI Command Execution**: When step contains `command` field, execute via Bash tool (Codex/Gemini CLI). For Codex with dependencies, use `resume --last` flag.
+- **Templates**: Apply templates as specified in `meta.template` or step-level templates.
 - **Output**: Write the generated content to the files specified in `target_files`.
 
 ### 4. Progress Tracking with TodoWrite

.claude/agents/test-fix-agent.md

@@ -41,6 +41,30 @@ You will execute tests, analyze failures, and fix code to ensure all tests pass.
 
 ## Execution Process
 
+### Flow Control Execution
+When task JSON contains `flow_control` field, execute preparation and implementation steps systematically.
+
+**Pre-Analysis Steps** (`flow_control.pre_analysis`):
+1. **Sequential Processing**: Execute steps in order, accumulating context
+2. **Variable Substitution**: Use `[variable_name]` to reference previous outputs
+3. **Error Handling**: Follow step-specific strategies (`skip_optional`, `fail`, `retry_once`)
+
+**Implementation Approach** (`flow_control.implementation_approach`):
+When task JSON contains implementation_approach array:
+1. **Sequential Execution**: Process steps in order, respecting `depends_on` dependencies
+2. **Dependency Resolution**: Wait for all steps listed in `depends_on` before starting
+3. **Variable References**: Use `[variable_name]` to reference outputs from previous steps
+4. **Step Structure**:
+   - `step`: Step number (1, 2, 3...)
+   - `title`: Step title
+   - `description`: Detailed description with variable references
+   - `modification_points`: Test and code modification targets
+   - `logic_flow`: Test-fix iteration sequence
+   - `command`: Optional CLI command (only when explicitly specified)
+   - `depends_on`: Array of step numbers that must complete first
+   - `output`: Variable name for this step's output
+
+
 ### 1. Context Assessment & Test Discovery
 - Analyze task context to identify test files and source code paths
 - Load test framework configuration (Jest, Pytest, Mocha, etc.)
@@ -61,16 +85,34 @@ fi
 - Parse test results to identify failures
 
 ### 3. Failure Diagnosis & Fixing Loop
+
+**Execution Modes**:
+
+**A. Manual Mode (Default, meta.use_codex=false)**:
 ```
-WHILE tests are failing:
-    1. Analyze failure output
-    2. Identify root cause in source code
-    3. Modify source code to fix issue
-    4. Re-run affected tests
+WHILE tests are failing AND iterations < max_iterations:
+    1. Use Gemini to diagnose failure (bug-fix template)
+    2. Present fix recommendations to user
+    3. User applies fixes manually
+    4. Re-run test suite
     5. Verify fix doesn't break other tests
 END WHILE
 ```
 
+**B. Codex Mode (meta.use_codex=true)**:
+```
+WHILE tests are failing AND iterations < max_iterations:
+    1. Use Gemini to diagnose failure (bug-fix template)
+    2. Use Codex to apply fixes automatically with resume mechanism
+    3. Re-run test suite
+    4. Verify fix doesn't break other tests
+END WHILE
+```
+
+**Codex Resume in Test-Fix Cycle** (when `meta.use_codex=true`):
+- First iteration: Start new Codex session with full context
+- Subsequent iterations: Use `resume --last` to maintain fix history and apply consistent strategies
+
 ### 4. Code Quality Certification
 - All tests pass → Code is APPROVED ✅
 - Generate summary documenting:

.claude/commands/cli/analyze.md

@@ -1,12 +1,7 @@
 ---
 name: analyze
 description: Quick codebase analysis using CLI tools (codex/gemini/qwen)
-usage: /cli:analyze [--tool <codex|gemini|qwen>] [--enhance] <analysis-target>
 argument-hint: "[--tool codex|gemini|qwen] [--enhance] analysis target"
-examples:
-  - /cli:analyze "authentication patterns"
-  - /cli:analyze --tool qwen "API security"
-  - /cli:analyze --tool codex --enhance "performance bottlenecks"
 allowed-tools: SlashCommand(*), Bash(*), TodoWrite(*), Read(*), Glob(*)
 ---
 

.claude/commands/cli/chat.md

@@ -1,12 +1,7 @@
 ---
 name: chat
 description: Simple CLI interaction command for direct codebase analysis
-usage: /cli:chat [--tool <codex|gemini|qwen>] [--enhance] "inquiry"
 argument-hint: "[--tool codex|gemini|qwen] [--enhance] inquiry"
-examples:
-  - /cli:chat "analyze the authentication flow"
-  - /cli:chat --tool qwen --enhance "optimize React component"
-  - /cli:chat --tool codex "review security vulnerabilities"
 allowed-tools: SlashCommand(*), Bash(*)
 ---
 

.claude/commands/cli/cli-init.md

@@ -1,13 +1,7 @@
 ---
 name: cli-init
 description: Initialize CLI tool configurations (Gemini and Qwen) based on workspace analysis
-usage: /cli:cli-init [--tool <gemini|qwen|all>] [--output=<path>] [--preview]
 argument-hint: "[--tool gemini|qwen|all] [--output path] [--preview]"
-examples:
-  - /cli:cli-init
-  - /cli:cli-init --tool qwen
-  - /cli:cli-init --tool all --preview
-  - /cli:cli-init --output=.config/
 allowed-tools: Bash(*), Read(*), Write(*), Glob(*)
 ---
 
@@ -452,4 +446,4 @@ docker-compose.override.yml
 | **Gemini-only workflow** | `/cli:cli-init --tool gemini` | Creates .gemini/ and .geminiignore only |
 | **Qwen-only workflow** | `/cli:cli-init --tool qwen` | Creates .qwen/ and .qwenignore only |
 | **Preview before commit** | `/cli:cli-init --preview` | Shows what would be generated |
-| **Update configurations** | `/cli:cli-init` | Regenerates all files with backups |
+| **Update configurations** | `/cli:cli-init` | Regenerates all files with backups |

.claude/commands/cli/codex-execute.md

@@ -1,12 +1,7 @@
 ---
 name: codex-execute
 description: Automated task decomposition and execution with Codex using resume mechanism
-usage: /cli:codex-execute [--verify-git] <task-description|task-id>
 argument-hint: "[--verify-git] task description or task-id"
-examples:
-  - /cli:codex-execute "implement user authentication system"
-  - /cli:codex-execute --verify-git "refactor API layer"
-  - /cli:codex-execute IMPL-001
 allowed-tools: SlashCommand(*), Bash(*), TodoWrite(*), Read(*), Glob(*)
 ---
 

.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
+
+-   `<input>` (Required): Topic description or task ID (e.g., "Design a new caching layer" or `PLAN-002`)
+-   `--rounds <N>` (Optional): Maximum number of discussion rounds (default: prompts after each round)
+-   `--task-id <id>` (Optional): Associates discussion with workflow task ID
+-   `--topic <description>` (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

.claude/commands/cli/execute.md

@@ -1,13 +1,7 @@
 ---
 name: execute
 description: Auto-execution of implementation tasks with YOLO permissions and intelligent context inference
-usage: /cli:execute [--tool <codex|gemini|qwen>] [--enhance] <description|task-id>
 argument-hint: "[--tool codex|gemini|qwen] [--enhance] description or task-id"
-examples:
-  - /cli:execute "implement user authentication system"
-  - /cli:execute --tool qwen --enhance "optimize React component"
-  - /cli:execute --tool codex IMPL-001
-  - /cli:execute --enhance "fix API performance issues"
 allowed-tools: SlashCommand(*), Bash(*)
 ---
 

.claude/commands/cli/mode/bug-index.md

@@ -1,12 +1,7 @@
 ---
 name: bug-index
 description: Bug analysis and fix suggestions using CLI tools
-usage: /cli:mode:bug-index [--tool <codex|gemini|qwen>] [--enhance] [--cd "path"] "bug description"
 argument-hint: "[--tool codex|gemini|qwen] [--enhance] [--cd path] bug description"
-examples:
-  - /cli:mode:bug-index "authentication null pointer error"
-  - /cli:mode:bug-index --tool qwen --enhance "login not working"
-  - /cli:mode:bug-index --tool codex --cd "src/auth" "token validation fails"
 allowed-tools: SlashCommand(*), Bash(*)
 ---
 

.claude/commands/cli/mode/code-analysis.md

@@ -1,12 +1,7 @@
 ---
 name: code-analysis
 description: Deep code analysis and debugging using CLI tools with specialized template
-usage: /cli:mode:code-analysis [--tool <codex|gemini|qwen>] [--enhance] [--cd "path"] "analysis target"
 argument-hint: "[--tool codex|gemini|qwen] [--enhance] [--cd path] analysis target"
-examples:
-  - /cli:mode:code-analysis "analyze authentication flow logic"
-  - /cli:mode:code-analysis --tool qwen --enhance "explain data transformation pipeline"
-  - /cli:mode:code-analysis --tool codex --cd "src/core" "trace execution path for user registration"
 allowed-tools: SlashCommand(*), Bash(*)
 ---
 

.claude/commands/cli/mode/plan.md

@@ -1,12 +1,7 @@
 ---
 name: plan
 description: Project planning and architecture analysis using CLI tools
-usage: /cli:mode:plan [--tool <codex|gemini|qwen>] [--enhance] [--cd "path"] "topic"
 argument-hint: "[--tool codex|gemini|qwen] [--enhance] [--cd path] topic"
-examples:
-  - /cli:mode:plan "design user dashboard"
-  - /cli:mode:plan --tool qwen --enhance "plan microservices migration"
-  - /cli:mode:plan --tool codex --cd "src/auth" "authentication system"
 allowed-tools: SlashCommand(*), Bash(*)
 ---
 

.claude/commands/enhance-prompt.md

@@ -1,12 +1,7 @@
 ---
 name: enhance-prompt
 description: Context-aware prompt enhancement using session memory and codebase analysis
-usage: /enhance-prompt <user_input>
 argument-hint: "user input to enhance"
-examples:
-  - /enhance-prompt "add user profile editing"
-  - /enhance-prompt "fix login button"
-  - /enhance-prompt "clean up the payment code"
 ---
 
 ## Overview

.claude/commands/task/breakdown.md

@@ -1,12 +1,7 @@
 ---
 name: breakdown
 description: Intelligent task decomposition with context-aware subtask generation
-usage: /task:breakdown <task-id>
-argument-hint: task-id
-examples:
-  - /task:breakdown IMPL-1
-  - /task:breakdown IMPL-1.1
-  - /task:breakdown impl-3
+argument-hint: "task-id"
 ---
 
 # Task Breakdown Command (/task:breakdown)

.claude/commands/task/create.md

@@ -1,12 +1,7 @@
 ---
 name: create
 description: Create implementation tasks with automatic context awareness
-usage: /task:create "title"
-argument-hint: "task title"
-examples:
-  - /task:create "Implement user authentication"
-  - /task:create "Build REST API endpoints"
-  - /task:create "Fix login validation bug"
+argument-hint: "\"task title\""
 ---
 
 # Task Create Command (/task:create)

.claude/commands/task/execute.md

@@ -1,12 +1,7 @@
 ---
 name: execute
 description: Execute tasks with appropriate agents and context-aware orchestration
-usage: /task:execute <task-id>
-argument-hint: task-id
-examples:
-  - /task:execute IMPL-1
-  - /task:execute IMPL-1.2
-  - /task:execute IMPL-3
+argument-hint: "task-id"
 ---
 
 ### 🚀 **Command Overview: `/task:execute`**

.claude/commands/task/replan.md

@@ -1,12 +1,7 @@
 ---
 name: replan
 description: Replan individual tasks with detailed user input and change tracking
-usage: /task:replan <task-id> [input]
-argument-hint: task-id ["text"|file.md|ISS-001]
-examples:
-  - /task:replan IMPL-1 "Add OAuth2 authentication support"
-  - /task:replan IMPL-1 updated-specs.md
-  - /task:replan IMPL-1 ISS-001
+argument-hint: "task-id [\"text\"|file.md]"
 ---
 
 # Task Replan Command (/task:replan)
@@ -38,12 +33,6 @@ Replans individual tasks with multiple input options, change tracking, and versi
 ```
 Supports: .md, .txt, .json, .yaml
 
-### Issue Reference
-```bash
-/task:replan IMPL-1 ISS-001
-```
-Loads issue description and requirements
-
 ### Interactive Mode
 ```bash
 /task:replan IMPL-1 --interactive

.claude/commands/update-memory-full.md

@@ -1,12 +1,7 @@
 ---
 name: update-memory-full
 description: Complete project-wide CLAUDE.md documentation update
-usage: /update-memory-full [--tool <gemini|qwen|codex>]
 argument-hint: "[--tool gemini|qwen|codex]"
-examples:
-  - /update-memory-full                      # Full project documentation update (gemini default)
-  - /update-memory-full --tool qwen          # Use Qwen for architecture analysis
-  - /update-memory-full --tool codex         # Use Codex for implementation validation
 ---
 
 ### 🚀 Command Overview: `/update-memory-full`

.claude/commands/update-memory-related.md

@@ -1,12 +1,7 @@
 ---
 name: update-memory-related
 description: Context-aware CLAUDE.md documentation updates based on recent changes
-usage: /update-memory-related [--tool <gemini|qwen|codex>]
 argument-hint: "[--tool gemini|qwen|codex]"
-examples:
-  - /update-memory-related                    # Update documentation based on recent changes (gemini default)
-  - /update-memory-related --tool qwen        # Use Qwen for architecture analysis
-  - /update-memory-related --tool codex       # Use Codex for implementation validation
 ---
 
 ### 🚀 Command Overview: `/update-memory-related`

.claude/commands/version.md

@@ -1,9 +1,6 @@
 ---
 name: version
 description: Display version information and check for updates
-usage: /version
-examples:
-  - /version
 allowed-tools: Bash(*)
 ---
 

.claude/commands/workflow/action-plan-verify.md

@@ -1,11 +1,7 @@
 ---
 name: action-plan-verify
 description: Perform non-destructive cross-artifact consistency and quality analysis of IMPL_PLAN.md and task.json before execution
-usage: /workflow:action-plan-verify [--session <session-id>]
-argument-hint: "optional: --session <session-id>"
-examples:
-  - /workflow:action-plan-verify
-  - /workflow:action-plan-verify --session WFS-auth
+argument-hint: "[optional: --session session-id]"
 allowed-tools: Read(*), TodoWrite(*), Glob(*), Bash(*)
 ---
 

.claude/commands/workflow/brainstorm/artifacts.md

@@ -1,12 +1,7 @@
 ---
 name: artifacts
 description: Generate role-specific topic-framework.md dynamically based on selected roles
-usage: /workflow:brainstorm:artifacts "<topic>" [--roles "role1,role2,role3"]
 argument-hint: "topic or challenge description for framework generation"
-examples:
-  - /workflow:brainstorm:artifacts "Build real-time collaboration feature"
-  - /workflow:brainstorm:artifacts "Optimize database performance" --roles "system-architect,data-architect,subject-matter-expert"
-  - /workflow:brainstorm:artifacts "Implement secure authentication system" --roles "ui-designer,ux-expert,subject-matter-expert"
 allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*)
 ---
 
@@ -368,4 +363,4 @@ ELSE:
 ### Integration Points
 - **Compatible with**: Other brainstorming commands in the same session
 - **Builds foundation for**: More detailed planning and implementation phases
-- **Outputs used by**: `/workflow:brainstorm:synthesis` command for cross-analysis integration
+- **Outputs used by**: `/workflow:brainstorm:synthesis` command for cross-analysis integration

.claude/commands/workflow/brainstorm/auto-parallel.md

@@ -1,12 +1,7 @@
 ---
 name: auto-parallel
 description: Parallel brainstorming automation with dynamic role selection and concurrent execution
-usage: /workflow:brainstorm:auto-parallel "<topic>"
 argument-hint: "topic or challenge description"
-examples:
-  - /workflow:brainstorm:auto-parallel "Build real-time collaboration feature"
-  - /workflow:brainstorm:auto-parallel "Optimize database performance for millions of users"
-  - /workflow:brainstorm:auto-parallel "Implement secure authentication system"
 allowed-tools: SlashCommand(*), Task(*), TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*)
 ---
 
@@ -327,4 +322,4 @@ Command coordination model: artifacts command → parallel role analysis → syn
 - **Agent self-management**: Agents handle their own workflow and validation
 - **Concurrent operation**: No inter-agent dependencies enabling parallel execution
 - **Reference-based synthesis**: Post-processing integration without content duplication
-- **TodoWrite orchestration**: Progress tracking and workflow control throughout entire process
+- **TodoWrite orchestration**: Progress tracking and workflow control throughout entire process

.claude/commands/workflow/brainstorm/auto-squeeze.md

@@ -1,12 +1,7 @@
 ---
 name: auto-squeeze
 description: Orchestrate 3-phase brainstorming workflow by executing commands sequentially
-usage: /workflow:brainstorm:auto-squeeze "<topic>"
 argument-hint: "topic or challenge description for coordinated brainstorming"
-examples:
-  - /workflow:brainstorm:auto-squeeze "Build real-time collaboration feature"
-  - /workflow:brainstorm:auto-squeeze "Optimize database performance for millions of users"
-  - /workflow:brainstorm:auto-squeeze "Implement secure authentication system"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*)
 ---
 
@@ -255,4 +250,4 @@ Return summary to user
 ✅ Update TodoWrite after each role completion
 ✅ Execute Phase 3 (synthesis) after all roles complete
 ✅ Validate synthesis-report.md exists
-✅ Return summary with all generated files
+✅ Return summary with all generated files

.claude/commands/workflow/brainstorm/data-architect.md

@@ -1,12 +1,7 @@
 ---
 name: data-architect
 description: Generate or update data-architect/analysis.md addressing topic-framework discussion points
-usage: /workflow:brainstorm:data-architect [topic]
 argument-hint: "optional topic - uses existing framework if available"
-examples:
-  - /workflow:brainstorm:data-architect
-  - /workflow:brainstorm:data-architect "user analytics data pipeline"
-  - /workflow:brainstorm:data-architect "real-time data processing system"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
 
@@ -202,4 +197,4 @@ TodoWrite({
 ### Integration Points
 - **Framework Reference**: @../topic-framework.md for structured discussion points
 - **Cross-Role Synthesis**: Data architecture insights available for synthesis-report.md integration
-- **Agent Autonomy**: Independent execution with framework guidance
+- **Agent Autonomy**: Independent execution with framework guidance

.claude/commands/workflow/brainstorm/product-manager.md

@@ -1,12 +1,7 @@
 ---
 name: product-manager
 description: Generate or update product-manager/analysis.md addressing topic-framework discussion points
-usage: /workflow:brainstorm:product-manager [topic]
 argument-hint: "optional topic - uses existing framework if available"
-examples:
-  - /workflow:brainstorm:product-manager
-  - /workflow:brainstorm:product-manager "user authentication redesign"
-  - /workflow:brainstorm:product-manager "mobile app performance optimization"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
 

.claude/commands/workflow/brainstorm/product-owner.md

@@ -1,12 +1,7 @@
 ---
 name: product-owner
 description: Generate or update product-owner/analysis.md addressing topic-framework discussion points
-usage: /workflow:brainstorm:product-owner [topic]
 argument-hint: "optional topic - uses existing framework if available"
-examples:
-  - /workflow:brainstorm:product-owner
-  - /workflow:brainstorm:product-owner "user authentication redesign"
-  - /workflow:brainstorm:product-owner "mobile app performance optimization"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
 

.claude/commands/workflow/brainstorm/scrum-master.md

@@ -1,12 +1,7 @@
 ---
 name: scrum-master
 description: Generate or update scrum-master/analysis.md addressing topic-framework discussion points
-usage: /workflow:brainstorm:scrum-master [topic]
 argument-hint: "optional topic - uses existing framework if available"
-examples:
-  - /workflow:brainstorm:scrum-master
-  - /workflow:brainstorm:scrum-master "user authentication redesign"
-  - /workflow:brainstorm:scrum-master "mobile app performance optimization"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
 

.claude/commands/workflow/brainstorm/subject-matter-expert.md

@@ -1,12 +1,7 @@
 ---
 name: subject-matter-expert
 description: Generate or update subject-matter-expert/analysis.md addressing topic-framework discussion points
-usage: /workflow:brainstorm:subject-matter-expert [topic]
 argument-hint: "optional topic - uses existing framework if available"
-examples:
-  - /workflow:brainstorm:subject-matter-expert
-  - /workflow:brainstorm:subject-matter-expert "user authentication redesign"
-  - /workflow:brainstorm:subject-matter-expert "mobile app performance optimization"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
 

.claude/commands/workflow/brainstorm/synthesis.md

@@ -1,10 +1,7 @@
 ---
 name: synthesis
 description: Generate synthesis-specification.md from topic-framework and role analyses with @ references
-usage: /workflow:brainstorm:synthesis
 argument-hint: "no arguments required - synthesizes existing framework and role analyses"
-examples:
-  - /workflow:brainstorm:synthesis
 allowed-tools: Read(*), Write(*), TodoWrite(*), Glob(*)
 ---
 
@@ -497,4 +494,4 @@ If you want to skip verification and proceed directly:
 /workflow:execute --session WFS-{session-id}
 ```
 
-⚠️ **Warning**: Skipping verification increases risk of late-stage issues and rework.
+⚠️ **Warning**: Skipping verification increases risk of late-stage issues and rework.

.claude/commands/workflow/brainstorm/system-architect.md

@@ -1,11 +1,7 @@
 ---
 name: system-architect
 description: Generate or update system-architect/analysis.md addressing topic-framework discussion points
-usage: /workflow:brainstorm:system-architect [topic]
 argument-hint: "optional topic - uses existing framework if available"
-examples:
-  - /workflow:brainstorm:system-architect
-  - /workflow:brainstorm:system-architect "user authentication redesign"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
 
@@ -369,4 +365,4 @@ System architect perspective provides:
 - [ ] **Resource Planning**: Resource requirements clearly defined and realistic
 - [ ] **Risk Management**: Technical risks identified with mitigation plans
 - [ ] **Performance Validation**: Architecture can meet performance requirements
-- [ ] **Evolution Strategy**: Design allows for future growth and changes
+- [ ] **Evolution Strategy**: Design allows for future growth and changes

.claude/commands/workflow/brainstorm/ui-designer.md

@@ -1,12 +1,7 @@
 ---
 name: ui-designer
 description: Generate or update ui-designer/analysis.md addressing topic-framework discussion points
-usage: /workflow:brainstorm:ui-designer [topic]
 argument-hint: "optional topic - uses existing framework if available"
-examples:
-  - /workflow:brainstorm:ui-designer
-  - /workflow:brainstorm:ui-designer "user authentication redesign"
-  - /workflow:brainstorm:ui-designer "mobile app navigation improvement"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
 
@@ -202,4 +197,4 @@ TodoWrite({
 ### Integration Points
 - **Framework Reference**: @../topic-framework.md for structured discussion points
 - **Cross-Role Synthesis**: UI/UX insights available for synthesis-report.md integration
-- **Agent Autonomy**: Independent execution with framework guidance
+- **Agent Autonomy**: Independent execution with framework guidance

.claude/commands/workflow/brainstorm/ux-expert.md

@@ -1,12 +1,7 @@
 ---
 name: ux-expert
 description: Generate or update ux-expert/analysis.md addressing topic-framework discussion points
-usage: /workflow:brainstorm:ux-expert [topic]
 argument-hint: "optional topic - uses existing framework if available"
-examples:
-  - /workflow:brainstorm:ux-expert
-  - /workflow:brainstorm:ux-expert "user authentication redesign"
-  - /workflow:brainstorm:ux-expert "mobile app performance optimization"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
 

.claude/commands/workflow/concept-clarify.md

@@ -1,11 +1,7 @@
 ---
 name: concept-clarify
 description: Identify underspecified areas in brainstorming artifacts through targeted clarification questions before action planning
-usage: /workflow:concept-clarify [--session <session-id>]
-argument-hint: "optional: --session <session-id>"
-examples:
-  - /workflow:concept-clarify
-  - /workflow:concept-clarify --session WFS-auth
+argument-hint: "[optional: --session session-id]"
 allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
 ---
 

.claude/commands/workflow/execute.md

@@ -1,11 +1,7 @@
 ---
 name: execute
 description: Coordinate agents for existing workflow tasks with automatic discovery
-usage: /workflow:execute [--resume-session="session-id"]
-argument-hint: [--resume-session="session-id"]
-examples:
-  - /workflow:execute
-  - /workflow:execute --resume-session="WFS-user-auth"
+argument-hint: "[--resume-session=\"session-id\"]"
 ---
 
 # Workflow Execute Command
@@ -429,10 +425,28 @@ Task(subagent_type="{meta.agent}",
         "on_error": "skip_optional|fail|retry_once"
       }
     ],
-    "implementation_approach": {
-      "task_description": "Implement following consolidated synthesis specification...",
-      "modification_points": ["Apply synthesis specification requirements..."]
-    },
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Implement task following synthesis specification",
+        "description": "Implement '[title]' following synthesis specification. PRIORITY: Use synthesis-specification.md as primary requirement source. When implementation needs technical details (e.g., API schemas, caching configs, design tokens), refer to artifacts[] for detailed specifications from original role analyses.",
+        "modification_points": [
+          "Apply consolidated requirements from synthesis-specification.md",
+          "Follow technical guidelines from synthesis",
+          "Consult artifacts for implementation details when needed",
+          "Integrate with existing patterns"
+        ],
+        "logic_flow": [
+          "Load synthesis specification",
+          "Parse architecture and requirements",
+          "Implement following specification",
+          "Consult artifacts for technical details when needed",
+          "Validate against acceptance criteria"
+        ],
+        "depends_on": [],
+        "output": "implementation"
+      }
+    ],
     "target_files": ["file:function:lines", "path/to/NewFile.ts"]
   }
 }

.claude/commands/workflow/issue/close.md

@@ -1,142 +0,0 @@
----
-name: close
-description: Close a completed or obsolete workflow issue
-usage: /workflow:issue:close <issue-id> [reason]
-
-examples:
-  - /workflow:issue:close ISS-001
-  - /workflow:issue:close ISS-001 "Feature implemented in PR #42"
-  - /workflow:issue:close ISS-002 "Duplicate of ISS-001"
----
-
-# Close Workflow Issue (/workflow:issue:close)
-
-## Purpose
-Mark an issue as closed/resolved with optional reason documentation.
-
-## Usage
-```bash
-/workflow:issue:close <issue-id> ["reason"]
-```
-
-## Closing Process
-
-### Quick Close
-Simple closure without reason:
-```bash
-/workflow:issue:close ISS-001
-```
-
-### Close with Reason
-Include closure reason:
-```bash
-/workflow:issue:close ISS-001 "Feature implemented in PR #42"
-/workflow/issue/close ISS-002 "Duplicate of ISS-001"  
-/workflow/issue/close ISS-003 "No longer relevant"
-```
-
-### Interactive Close (Default)
-Without reason, prompts for details:
-```
-Closing Issue ISS-001: Add OAuth2 social login support
-Current Status: Open | Priority: High | Type: Feature
-
-Why is this issue being closed?
-1. ✅ Completed - Issue resolved successfully
-2. 🔄 Duplicate - Duplicate of another issue
-3. ❌ Invalid - Issue is invalid or not applicable  
-4. 🚫 Won't Fix - Decided not to implement
-5. 📝 Custom reason
-
-Choice: _
-```
-
-## Closure Categories
-
-### Completed (Default)
-- Issue was successfully resolved
-- Implementation finished
-- Requirements met
-- Ready for review/testing
-
-### Duplicate
-- Same as existing issue
-- Consolidated into another issue
-- Reference to primary issue provided
-
-### Invalid
-- Issue description unclear
-- Not a valid problem/request
-- Outside project scope
-- Misunderstanding resolved
-
-### Won't Fix
-- Decided not to implement
-- Business decision to decline
-- Technical constraints prevent
-- Priority too low
-
-### Custom Reason
-- Specific project context
-- Detailed explanation needed
-- Complex closure scenario
-
-## Closure Effects
-
-### Status Update
-- Changes status from "open" to "closed"
-- Records closure details
-- Saves closure reason and category
-
-### Integration Cleanup
-- Unlinks from workflow tasks (if integrated)
-- Removes from active TodoWrite items
-- Updates session statistics
-
-### History Preservation
-- Maintains full issue history
-- Records closure details
-- Preserves for future reference
-
-## Session Updates
-
-### Statistics
-Updates session issue counts:
-- Decrements open issues
-- Increments closed issues
-- Updates completion metrics
-
-### Progress Tracking
-- Updates workflow progress
-- Refreshes TodoWrite status
-- Updates session health metrics
-
-## Output
-Displays:
-- Issue closure confirmation
-- Closure reason and category
-- Updated session statistics  
-- Related actions taken
-
-## Reopening
-Closed issues can be reopened:
-```bash
-/workflow/issue/update ISS-001 --status=open
-```
-
-## Error Handling
-- **Issue not found**: Lists available open issues
-- **Already closed**: Shows current status and closure info
-- **Integration conflicts**: Handles task unlinking gracefully
-- **File errors**: Validates and repairs issue files
-
-## Archive Management
-Closed issues:
-- Remain in .issues/ directory
-- Are excluded from default listings
-- Can be viewed with `/workflow/issue/list --closed`
-- Maintain full searchability
-
----
-
-**Result**: Issue properly closed with documented reason and session cleanup

.claude/commands/workflow/issue/create.md

@@ -1,106 +0,0 @@
----
-name: create
-description: Create a new issue or change request
-usage: /workflow:issue:create "issue description"
-
-examples:
-  - /workflow:issue:create "Add OAuth2 social login support"
-  - /workflow:issue:create "Fix user avatar security vulnerability"
----
-
-# Create Workflow Issue (/workflow:issue:create)
-
-## Purpose
-Create a new issue or change request within the current workflow session.
-
-## Usage
-```bash
-/workflow:issue:create "issue description"
-```
-
-## Automatic Behavior
-
-### Issue ID Generation
-- Generates unique ID: ISS-001, ISS-002, etc.
-- Sequential numbering within session
-- Stored in session's .issues/ directory
-
-### Type Detection
-Automatically detects issue type from description:
-- **Bug**: Contains words like "fix", "error", "bug", "broken"
-- **Feature**: Contains words like "add", "implement", "create", "new"
-- **Optimization**: Contains words like "improve", "optimize", "performance"
-- **Documentation**: Contains words like "document", "readme", "docs"
-- **Refactor**: Contains words like "refactor", "cleanup", "restructure"
-
-### Priority Assessment
-Auto-assigns priority based on keywords:
-- **Critical**: "critical", "urgent", "blocker", "security"
-- **High**: "important", "major", "significant"
-- **Medium**: Default for most issues
-- **Low**: "minor", "enhancement", "nice-to-have"
-
-## Issue Storage
-
-### File Structure
-```
-.workflow/WFS-[session]/.issues/
-├── ISS-001.json          # Issue metadata
-├── ISS-002.json          # Another issue
-└── issue-registry.json   # Issue index
-```
-
-### Issue Metadata
-Each issue stores:
-```json
-{
-  "id": "ISS-001",
-  "title": "Add OAuth2 social login support",
-  "type": "feature",
-  "priority": "high",
-  "status": "open",
-  "created_at": "2025-09-08T10:00:00Z",
-  "category": "authentication",
-  "estimated_impact": "medium",
-  "blocking": false,
-  "session_id": "WFS-oauth-integration"
-}
-```
-
-## Session Integration
-
-### Active Session Check
-- Uses current active session (marker file)
-- Creates .issues/ directory if needed
-- Updates session's issue tracking
-
-### TodoWrite Integration
-Optionally adds to task list:
-- Creates todo for issue investigation
-- Links issue to implementation tasks
-- Updates progress tracking
-
-## Output
-Displays:
-- Generated issue ID
-- Detected type and priority
-- Storage location
-- Integration status
-- Quick actions available
-
-## Quick Actions
-After creation:
-- **View**: `/workflow:issue:list`
-- **Update**: `/workflow:issue:update ISS-001`
-- **Integrate**: Link to workflow tasks
-- **Close**: `/workflow:issue:close ISS-001`
-
-## Error Handling
-- **No active session**: Prompts to start session first
-- **Directory creation**: Handles permission issues
-- **Duplicate description**: Warns about similar issues
-- **Invalid description**: Prompts for meaningful description
-
----
-
-**Result**: New issue created and ready for management within workflow

.claude/commands/workflow/issue/list.md

@@ -1,104 +0,0 @@
----
-name: list
-description: List and filter workflow issues
-usage: /workflow:issue:list
-examples:
-  - /workflow:issue:list
-  - /workflow:issue:list --open
-  - /workflow:issue:list --priority=high
----
-
-# List Workflow Issues (/workflow:issue:list)
-
-## Purpose
-Display all issues and change requests within the current workflow session.
-
-## Usage
-```bash
-/workflow:issue:list [filter]
-```
-
-## Optional Filters
-Simple keyword-based filtering:
-```bash
-/workflow:issue:list --open           # Only open issues
-/workflow:issue:list --closed         # Only closed issues
-/workflow:issue:list --critical       # Critical priority
-/workflow:issue:list --high           # High priority
-/workflow:issue:list --bug            # Bug type issues
-/workflow:issue:list --feature        # Feature type issues
-/workflow:issue:list --blocking       # Blocking issues only
-```
-
-## Display Format
-
-### Open Issues
-```
-🔴 ISS-001: Add OAuth2 social login support
-   Type: Feature | Priority: High | Created: 2025-09-07
-   Status: Open | Impact: Medium
-   
-🔴 ISS-002: Fix user avatar security vulnerability  
-   Type: Bug | Priority: Critical | Created: 2025-09-08
-   Status: Open | Impact: High | 🚫 BLOCKING
-```
-
-### Closed Issues
-```
-✅ ISS-003: Update authentication documentation
-   Type: Documentation | Priority: Low
-   Status: Closed | Completed: 2025-09-05
-   Reason: Documentation updated in PR #45
-```
-
-### Integrated Issues
-```
-🔗 ISS-004: Implement rate limiting
-   Type: Feature | Priority: Medium
-   Status: Integrated → IMPL-003
-   Integrated: 2025-09-06 | Task: IMPL-3.json
-```
-
-## Summary Stats
-```
-📊 Issue Summary for WFS-oauth-integration:
-   Total: 4 issues
-   🔴 Open: 2 | ✅ Closed: 1 | 🔗 Integrated: 1
-   🚫 Blocking: 1 | ⚡ Critical: 1 | 📈 High: 1
-```
-
-## Empty State
-If no issues exist:
-```
-No issues found for current session.
-
-Create your first issue:
-/workflow:issue:create "describe the issue or request"
-```
-
-## Quick Actions
-For each issue, shows available actions:
-- **Update**: `/workflow:issue:update ISS-001`
-- **Integrate**: Link to workflow tasks  
-- **Close**: `/workflow:issue:close ISS-001`
-- **View Details**: Full issue information
-
-## Session Context
-- Lists issues from current active session
-- Shows session name and directory
-- Indicates if .issues/ directory exists
-
-## Sorting
-Issues are sorted by:
-1. Blocking status (blocking first)
-2. Priority (critical → high → medium → low)
-3. Creation date (newest first)
-
-## Performance
-- Fast loading from JSON files
-- Cached issue registry
-- Efficient filtering
-
----
-
-**Result**: Complete overview of all workflow issues with their current status

.claude/commands/workflow/issue/update.md

@@ -1,135 +0,0 @@
----
-name: update
-description: Update an existing workflow issue
-usage: /workflow:issue:update <issue-id> [changes]
-
-examples:
-  - /workflow:issue:update ISS-001
-  - /workflow:issue:update ISS-001 --priority=critical
-  - /workflow:issue:update ISS-001 --status=closed
----
-
-# Update Workflow Issue (/workflow:issue:update)
-
-## Purpose
-Modify attributes and status of an existing workflow issue.
-
-## Usage
-```bash
-/workflow:issue:update <issue-id> [options]
-```
-
-## Quick Updates
-Simple attribute changes:
-```bash
-/workflow:issue:update ISS-001 --priority=critical
-/workflow:issue:update ISS-001 --status=closed
-/workflow:issue:update ISS-001 --blocking
-/workflow:issue:update ISS-001 --type=bug
-```
-
-## Interactive Mode (Default)
-Without options, opens interactive editor:
-```
-Issue ISS-001: Add OAuth2 social login support
-Current Status: Open | Priority: High | Type: Feature
-
-What would you like to update?
-1. Status (open → closed/integrated)
-2. Priority (high → critical/medium/low)  
-3. Type (feature → bug/optimization/etc)
-4. Description
-5. Add comment
-6. Toggle blocking status
-7. Cancel
-
-Choice: _
-```
-
-## Available Updates
-
-### Status Changes
-- **open** → **closed**: Issue resolved
-- **open** → **integrated**: Linked to workflow task
-- **closed** → **open**: Reopen issue
-- **integrated** → **open**: Unlink from tasks
-
-### Priority Levels
-- **critical**: Urgent, blocking progress
-- **high**: Important, should address soon
-- **medium**: Standard priority
-- **low**: Nice-to-have, can defer
-
-### Issue Types  
-- **bug**: Something broken that needs fixing
-- **feature**: New functionality to implement
-- **optimization**: Performance or efficiency improvement
-- **refactor**: Code structure improvement
-- **documentation**: Documentation updates
-
-### Additional Options
-- **blocking/non-blocking**: Whether issue blocks progress
-- **description**: Update issue description
-- **comments**: Add notes and updates
-
-## Update Process
-
-### Validation
-- Verifies issue exists in current session
-- Checks valid status transitions
-- Validates priority and type values
-
-### Change Tracking
-- Records update details
-- Tracks who made changes
-- Maintains change history
-
-### File Updates
-- Updates ISS-XXX.json file
-- Refreshes issue-registry.json
-- Updates session statistics
-
-## Change History
-Maintains audit trail:
-```json
-{
-  "changes": [
-    {
-      "field": "priority",
-      "old_value": "high",
-      "new_value": "critical",
-      "reason": "Security implications discovered"
-    }
-  ]
-}
-```
-
-## Integration Effects
-
-### Task Integration
-When status changes to "integrated":
-- Links to workflow task (optional)
-- Updates task context with issue reference
-- Creates bidirectional linking
-
-### Session Updates
-- Updates session issue statistics
-- Refreshes TodoWrite if applicable
-- Updates workflow progress tracking
-
-## Output
-Shows:
-- What was changed
-- Before and after values
-- Integration status
-- Available next actions
-
-## Error Handling
-- **Issue not found**: Lists available issues
-- **Invalid status**: Shows valid transitions
-- **Permission errors**: Clear error messages
-- **File corruption**: Validates and repairs
-
----
-
-**Result**: Issue successfully updated with change tracking and integration

.claude/commands/workflow/plan.md

@@ -1,13 +1,7 @@
 ---
 name: plan
 description: Orchestrate 4-phase planning workflow by executing commands and passing context between phases
-usage: /workflow:plan [--agent] <input>
-argument-hint: "[--agent] \"text description\"|file.md|ISS-001"
-examples:
-  - /workflow:plan "Build authentication system"
-  - /workflow:plan --agent "Build authentication system"
-  - /workflow:plan requirements.md
-  - /workflow:plan ISS-001
+argument-hint: "[--agent] [--cli-execute] \"text description\"|file.md"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 ---
 
@@ -36,6 +30,7 @@ This workflow runs **fully autonomously** once triggered. Each phase completes,
 **Execution Modes**:
 - **Manual Mode** (default): Use `/workflow:tools:task-generate`
 - **Agent Mode** (`--agent`): Use `/workflow:tools:task-generate-agent`
+- **CLI Execute Mode** (`--cli-execute`): Generate tasks with Codex execution commands
 
 ## Core Rules
 
@@ -124,9 +119,23 @@ CONTEXT: Existing user database schema, REST API endpoints
 - **IMPL_PLAN.md defines "HOW"**: Executable task breakdown, dependencies, implementation sequence
 - Task generation translates high-level specifications into concrete, actionable work items
 
-**Command**:
+**Command Selection**:
 - Manual: `SlashCommand(command="/workflow:tools:task-generate --session [sessionId]")`
 - Agent: `SlashCommand(command="/workflow:tools:task-generate-agent --session [sessionId]")`
+- CLI Execute: Add `--cli-execute` flag to either command
+
+**Flag Combination**:
+- `--cli-execute` alone: Manual task generation with CLI execution
+- `--agent --cli-execute`: Agent task generation with CLI execution
+
+**Command Examples**:
+```bash
+# Manual with CLI execution
+/workflow:tools:task-generate --session WFS-auth --cli-execute
+
+# Agent with CLI execution
+/workflow:tools:task-generate-agent --session WFS-auth --cli-execute
+```
 
 **Input**: `sessionId` from Phase 1
 
@@ -202,12 +211,6 @@ TodoWrite({todos: [
    - Extract goal, scope, requirements
    - Format into structured description
 
-4. **Issue Reference** (e.g., `ISS-001`) → Read and structure:
-   - Read issue file
-   - Extract title as goal
-   - Extract description as scope/context
-   - Format into structured description
-
 ## Data Flow
 
 ```
@@ -266,7 +269,10 @@ Return summary to user
 ✅ Parse context path from Phase 2 output, store in memory
 ✅ Pass session ID and context path to Phase 3 command
 ✅ Verify ANALYSIS_RESULTS.md after Phase 3
-✅ Select correct Phase 4 command based on --agent flag
+✅ **Build Phase 4 command** based on flags:
+  - Base command: `/workflow:tools:task-generate` (or `-agent` if `--agent` flag)
+  - Add `--session [sessionId]`
+  - Add `--cli-execute` if flag present
 ✅ Pass session ID to Phase 4 command
 ✅ Verify all Phase 4 outputs
 ✅ Update TodoWrite after each phase
@@ -297,4 +303,4 @@ CONSTRAINTS: [Limitations or boundaries]
 
 # Phase 2
 /workflow:tools:context-gather --session WFS-123 "GOAL: Build authentication\nSCOPE: JWT, login, registration\nCONTEXT: REST API"
-```
+```

.claude/commands/workflow/resume.md

@@ -1,12 +1,7 @@
 ---
 name: resume
 description: Intelligent workflow session resumption with automatic progress analysis
-usage: /workflow:resume "<session-id>"
 argument-hint: "session-id for workflow session to resume"
-examples:
-  - /workflow:resume "WFS-user-auth"
-  - /workflow:resume "WFS-api-integration"
-  - /workflow:resume "WFS-database-migration"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 ---
 

.claude/commands/workflow/review.md

@@ -1,13 +1,7 @@
 ---
 name: review
 description: Optional specialized review (security, architecture, docs) for completed implementation
-usage: /workflow:review [--type=<type>] [session-id]
-argument-hint: "[--type=security|architecture|action-items|quality] [session-id]"
-examples:
-  - /workflow:review                           # Quality review of active session
-  - /workflow:review --type=security           # Security audit of active session
-  - /workflow:review --type=architecture WFS-user-auth  # Architecture review of specific session
-  - /workflow:review --type=action-items       # Pre-deployment verification
+argument-hint: "[--type=security|architecture|action-items|quality] [optional: session-id]"
 ---
 
 ### 🚀 Command Overview: `/workflow:review`

.claude/commands/workflow/session/complete.md

@@ -1,7 +1,6 @@
 ---
 name: complete
 description: Mark the active workflow session as complete and remove active flag
-usage: /workflow:session:complete
 examples:
   - /workflow:session:complete
   - /workflow:session:complete --detailed

.claude/commands/workflow/session/list.md

@@ -1,7 +1,6 @@
 ---
 name: list
 description: List all workflow sessions with status
-usage: /workflow:session:list
 examples:
   - /workflow:session:list
 ---

.claude/commands/workflow/session/pause.md

@@ -1,69 +0,0 @@
----
-name: pause
-description: Pause the active workflow session
-usage: /workflow:session:pause
-examples:
-  - /workflow:session:pause
----
-
-# Pause Workflow Session (/workflow:session:pause)
-
-## Overview
-Pause the currently active workflow session, saving all state for later resumption.
-
-## Usage
-```bash
-/workflow:session:pause      # Pause current active session
-```
-
-## Implementation Flow
-
-### Step 1: Find Active Session
-```bash
-ls .workflow/.active-* 2>/dev/null | head -1
-```
-
-### Step 2: Get Session Name
-```bash
-basename .workflow/.active-WFS-session-name | sed 's/^\.active-//'
-```
-
-### Step 3: Update Session Status
-```bash
-jq '.status = "paused"' .workflow/WFS-session/workflow-session.json > temp.json
-mv temp.json .workflow/WFS-session/workflow-session.json
-```
-
-### Step 4: Add Pause Timestamp
-```bash
-jq '.paused_at = "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"' .workflow/WFS-session/workflow-session.json > temp.json
-mv temp.json .workflow/WFS-session/workflow-session.json
-```
-
-### Step 5: Remove Active Marker
-```bash
-rm .workflow/.active-WFS-session-name
-```
-
-## Simple Bash Commands
-
-### Basic Operations
-- **Find active session**: `ls .workflow/.active-*`
-- **Get session name**: `basename marker | sed 's/^\.active-//'`
-- **Update status**: `jq '.status = "paused"' session.json > temp.json`
-- **Add timestamp**: `jq '.paused_at = "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"'`
-- **Remove marker**: `rm .workflow/.active-session`
-
-### Pause Result
-```
-Session WFS-user-auth paused
-- Status: paused
-- Paused at: 2025-09-15T14:30:00Z
-- Tasks preserved: 8 tasks
-- Can resume with: /workflow:session:resume
-```
-
-## Related Commands
-- `/workflow:session:resume` - Resume paused session
-- `/workflow:session:list` - Show all sessions including paused
-- `/workflow:session:status` - Check session state

.claude/commands/workflow/session/resume.md

@@ -1,9 +1,6 @@
 ---
 name: resume
 description: Resume the most recently paused workflow session
-usage: /workflow:session:resume
-examples:
-  - /workflow:session:resume
 ---
 
 # Resume Workflow Session (/workflow:session:resume)

.claude/commands/workflow/session/start.md

@@ -1,7 +1,6 @@
 ---
 name: start
 description: Discover existing sessions or start a new workflow session with intelligent session management
-usage: /workflow:session:start [--auto|--new] [task_description]
 argument-hint: [--auto|--new] [optional: task description for new session]
 examples:
   - /workflow:session:start

.claude/commands/workflow/session/switch.md

@@ -1,87 +0,0 @@
----
-name: switch
-description: Switch to a different workflow session
-usage: /workflow:session:switch <session-id>
-argument-hint: session-id to switch to
-examples:
-  - /workflow:session:switch WFS-oauth-integration
-  - /workflow:session:switch WFS-user-profile
----
-
-# Switch Workflow Session (/workflow:session:switch)
-
-## Overview
-Switch the active session to a different workflow session.
-
-## Usage
-```bash
-/workflow:session:switch WFS-session-name     # Switch to specific session
-```
-
-## Implementation Flow
-
-### Step 1: Validate Target Session
-```bash
-test -d .workflow/WFS-target-session && echo "Session exists"
-```
-
-### Step 2: Pause Current Session
-```bash
-ls .workflow/.active-* 2>/dev/null | head -1
-jq '.status = "paused"' .workflow/current-session/workflow-session.json > temp.json
-```
-
-### Step 3: Remove Current Active Marker
-```bash
-rm .workflow/.active-* 2>/dev/null
-```
-
-### Step 4: Activate Target Session
-```bash
-jq '.status = "active"' .workflow/WFS-target/workflow-session.json > temp.json
-mv temp.json .workflow/WFS-target/workflow-session.json
-```
-
-### Step 5: Create New Active Marker
-```bash
-touch .workflow/.active-WFS-target-session
-```
-
-### Step 6: Add Switch Timestamp
-```bash
-jq '.switched_at = "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"' .workflow/WFS-target/workflow-session.json > temp.json
-mv temp.json .workflow/WFS-target/workflow-session.json
-```
-
-## Simple Bash Commands
-
-### Basic Operations
-- **Check session exists**: `test -d .workflow/WFS-session`
-- **Find current active**: `ls .workflow/.active-*`
-- **Pause current**: `jq '.status = "paused"' session.json > temp.json`
-- **Remove marker**: `rm .workflow/.active-*`
-- **Activate target**: `jq '.status = "active"' target.json > temp.json`
-- **Create marker**: `touch .workflow/.active-target`
-
-### Switch Result
-```
-Switched to session: WFS-oauth-integration
-- Previous: WFS-user-auth (paused)
-- Current: WFS-oauth-integration (active)
-- Switched at: 2025-09-15T15:45:00Z
-- Ready for: /workflow:execute
-```
-
-### Error Handling
-```bash
-# Session not found
-test -d .workflow/WFS-nonexistent || echo "Error: Session not found"
-
-# No sessions available
-ls .workflow/WFS-* 2>/dev/null || echo "No sessions available"
-```
-
-## Related Commands
-- `/workflow:session:list` - Show all available sessions
-- `/workflow:session:pause` - Pause current before switching
-- `/workflow:execute` - Continue with new active session

.claude/commands/workflow/status.md

@@ -1,12 +1,7 @@
 ---
 name: workflow:status
 description: Generate on-demand views from JSON task data
-usage: /workflow:status [task-id]
-argument-hint: [optional: task-id]
-examples:
-  - /workflow:status
-  - /workflow:status impl-1
-  - /workflow:status --validate
+argument-hint: "[optional: task-id]"
 ---
 
 # Workflow Status Command (/workflow:status)

.claude/commands/workflow/tdd-plan.md

@@ -1,12 +1,7 @@
 ---
 name: tdd-plan
 description: Orchestrate TDD workflow planning with Red-Green-Refactor task chains
-usage: /workflow:tdd-plan [--agent] <input>
-argument-hint: "[--agent] \"feature description\"|file.md|ISS-001"
-examples:
-  - /workflow:tdd-plan "Implement user authentication"
-  - /workflow:tdd-plan --agent requirements.md
-  - /workflow:tdd-plan ISS-001
+argument-hint: "[--agent] \"feature description\"|file.md"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 ---
 

.claude/commands/workflow/tdd-verify.md

@@ -1,11 +1,8 @@
 ---
 name: tdd-verify
 description: Verify TDD workflow compliance and generate quality report
-usage: /workflow:tdd-verify [session-id]
-argument-hint: "[WFS-session-id]"
-examples:
-  - /workflow:tdd-verify
-  - /workflow:tdd-verify WFS-auth
+
+argument-hint: "[optional: WFS-session-id]"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(gemini-wrapper:*)
 ---
 

.claude/commands/workflow/test-gen.md

@@ -1,11 +1,7 @@
 ---
 name: test-gen
 description: Create independent test-fix workflow session by analyzing completed implementation
-usage: /workflow:test-gen [--use-codex] <source-session-id>
-argument-hint: "[--use-codex] <source-session-id>"
-examples:
-  - /workflow:test-gen WFS-user-auth
-  - /workflow:test-gen --use-codex WFS-api-refactor
+argument-hint: "[--use-codex] [--cli-execute] source-session-id"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 ---
 
@@ -127,11 +123,12 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 ---
 
 ### Phase 4: Generate Test Tasks
-**Command**: `SlashCommand(command="/workflow:tools:test-task-generate [--use-codex] --session [testSessionId]")`
+**Command**: `SlashCommand(command="/workflow:tools:test-task-generate [--use-codex] [--cli-execute] --session [testSessionId]")`
 
 **Input**:
 - `testSessionId` from Phase 1
-- `--use-codex` flag (if present in original command)
+- `--use-codex` flag (if present in original command) - Controls IMPL-002 fix mode
+- `--cli-execute` flag (if present in original command) - Controls IMPL-001 generation mode
 
 **Expected Behavior**:
 - Parse TEST_ANALYSIS_RESULTS.md from Phase 3

.claude/commands/workflow/tools/concept-enhanced.md

@@ -1,7 +1,6 @@
 ---
 name: concept-enhanced
 description: Enhanced intelligent analysis with parallel CLI execution and design blueprint generation
-usage: /workflow:tools:concept-enhanced --session <session_id> --context <context_package_path>
 argument-hint: "--session WFS-session-id --context path/to/context-package.json"
 examples:
   - /workflow:tools:concept-enhanced --session WFS-auth --context .workflow/WFS-auth/.process/context-package.json

.claude/commands/workflow/tools/context-gather.md

@@ -1,7 +1,6 @@
 ---
 name: gather
 description: Intelligently collect project context based on task description and package into standardized JSON
-usage: /workflow:tools:context-gather --session <session_id> "<task_description>"
 argument-hint: "--session WFS-session-id \"task description\""
 examples:
   - /workflow:tools:context-gather --session WFS-user-auth "Implement user authentication system"

.claude/commands/workflow/tools/task-generate-agent.md

@@ -1,7 +1,6 @@
 ---
 name: task-generate-agent
 description: Autonomous task generation using action-planning-agent with discovery and output phases
-usage: /workflow:tools:task-generate-agent --session <session_id>
 argument-hint: "--session WFS-session-id"
 examples:
   - /workflow:tools:task-generate-agent --session WFS-auth
@@ -216,17 +215,29 @@ Task(
         "on_error": "fail"
       }
     ],
-    "implementation_approach": {
-      "task_description": "Implement '[title]' following synthesis specification. PRIORITY: Use synthesis-specification.md as primary requirement source. When implementation needs technical details (e.g., API schemas, caching configs, design tokens), refer to artifacts[] for detailed specifications from original role analyses.",
-      "modification_points": ["Apply requirements from synthesis"],
-      "logic_flow": [
-        "Load synthesis specification",
-        "Analyze existing patterns",
-        "Implement following specification",
-        "Consult artifacts for technical details when needed",
-        "Validate against acceptance criteria"
-      ]
-    },
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Implement task following synthesis specification",
+        "description": "Implement '[title]' following synthesis specification. PRIORITY: Use synthesis-specification.md as primary requirement source. When implementation needs technical details (e.g., API schemas, caching configs, design tokens), refer to artifacts[] for detailed specifications from original role analyses.",
+        "modification_points": [
+          "Apply consolidated requirements from synthesis-specification.md",
+          "Follow technical guidelines from synthesis",
+          "Consult artifacts for implementation details when needed",
+          "Integrate with existing patterns"
+        ],
+        "logic_flow": [
+          "Load synthesis specification and relevant role artifacts",
+          "Execute MCP code-index discovery for relevant files",
+          "Analyze existing patterns and identify modification targets",
+          "Implement following specification",
+          "Consult artifacts for technical details when needed",
+          "Validate against acceptance criteria"
+        ],
+        "depends_on": [],
+        "output": "implementation"
+      }
+    ],
     "target_files": ["file:function:lines", "path/to/NewFile.ts"]
   }
 }

.claude/commands/workflow/tools/task-generate-tdd.md

@@ -1,11 +1,7 @@
 ---
 name: task-generate-tdd
 description: Generate TDD task chains with Red-Green-Refactor dependencies
-usage: /workflow:tools:task-generate-tdd --session <session_id> [--agent]
 argument-hint: "--session WFS-session-id [--agent]"
-examples:
-  - /workflow:tools:task-generate-tdd --session WFS-auth
-  - /workflow:tools:task-generate-tdd --session WFS-auth --agent
 allowed-tools: Read(*), Write(*), Bash(gemini-wrapper:*), TodoWrite(*)
 ---
 
@@ -178,51 +174,53 @@ For each feature, generate 3 tasks with ID format:
         "on_error": "skip_optional"
       }
     ],
-    "implementation_approach": {
-      "task_description": "Write minimal code to pass tests, then enter iterative fix cycle if they still fail",
-      "initial_implementation": [
-        "Write minimal code based on test requirements",
-        "Execute test suite: bash(npm test -- tests/auth/login.test.ts)",
-        "If tests pass → Complete task",
-        "If tests fail → Capture failure logs and proceed to test-fix cycle"
-      ],
-      "test_fix_cycle": {
-        "max_iterations": 3,
-        "cycle_pattern": "gemini_diagnose → manual_fix (or codex if meta.use_codex=true) → retest",
-        "tools": {
-          "diagnosis": "gemini-wrapper (MODE: analysis, uses bug-fix template)",
-          "fix_application": "manual (default) or codex if meta.use_codex=true",
-          "verification": "bash(npm test -- tests/auth/login.test.ts)"
-        },
-        "exit_conditions": {
-          "success": "all_tests_pass",
-          "failure": "max_iterations_reached"
-        },
-        "steps": [
-          "ITERATION LOOP (max 3):",
-          "  1. Gemini Diagnosis:",
-          "     bash(cd .workflow/WFS-xxx/.process && ~/.claude/scripts/gemini-wrapper --all-files -p \"",
-          "     PURPOSE: Diagnose TDD Green phase test failure iteration [N]",
-          "     TASK: Systematic bug analysis and fix recommendations",
-          "     MODE: analysis",
-          "     CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}",
-          "              Test output: [test_failures]",
-          "              Test requirements: [test_requirements]",
-          "              Implementation: [focus_paths]",
-          "     EXPECTED: Root cause analysis, code path tracing, targeted fixes",
-          "     RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: [test_failure_description]",
-          "            Minimal surgical fixes only - stay in Green phase",
-          "     \" > green-fix-iteration-[N]-diagnosis.md)",
-          "  2. Apply Fix (check meta.use_codex):",
-          "     IF meta.use_codex=false (default): Present diagnosis to user for manual fix",
-          "     IF meta.use_codex=true: Codex applies fix automatically",
-          "  3. Retest: bash(npm test -- tests/auth/login.test.ts)",
-          "  4. If pass → Exit loop, complete task",
-          "     If fail → Continue to next iteration",
-          "IF max_iterations reached: Revert changes, report failure"
-        ]
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Implement minimal code to pass tests",
+        "description": "Write minimal code based on test requirements following TDD principles - no over-engineering",
+        "modification_points": [
+          "Load test requirements from TEST phase",
+          "Create/modify implementation files",
+          "Implement only what tests require",
+          "Focus on passing tests, not perfection"
+        ],
+        "logic_flow": [
+          "Load test requirements from [test_requirements]",
+          "Parse test expectations and edge cases",
+          "Write minimal implementation code",
+          "Avoid premature optimization or abstraction"
+        ],
+        "depends_on": [],
+        "output": "initial_implementation"
+      },
+      {
+        "step": 2,
+        "title": "Test and iteratively fix until passing",
+        "description": "Run tests and enter iterative fix cycle if needed (max 3 iterations with auto-revert on failure)",
+        "modification_points": [
+          "Execute test suite",
+          "If tests fail: diagnose with Gemini",
+          "Apply fixes (manual or Codex if meta.use_codex=true)",
+          "Retest and iterate"
+        ],
+        "logic_flow": [
+          "Run test suite",
+          "If all tests pass → Complete",
+          "If tests fail → Enter iteration loop (max 3):",
+          "  Extract failure messages and stack traces",
+          "  Use Gemini bug-fix template for diagnosis",
+          "  Generate targeted fix recommendations",
+          "  Apply fixes (manual or Codex)",
+          "  Rerun tests",
+          "  If pass → Complete, if fail → Continue iteration",
+          "If max_iterations reached → Trigger auto-revert"
+        ],
+        "command": "bash(npm test -- tests/auth/login.test.ts)",
+        "depends_on": [1],
+        "output": "test_results"
       }
-    },
+    ],
     "post_completion": [
       {
         "step": "verify_tests_passing",

.claude/commands/workflow/tools/task-generate.md

@@ -1,10 +1,10 @@
 ---
 name: task-generate
 description: Generate task JSON files and IMPL_PLAN.md from analysis results with artifacts integration
-usage: /workflow:tools:task-generate --session <session_id>
-argument-hint: "--session WFS-session-id"
+argument-hint: "--session WFS-session-id [--cli-execute]"
 examples:
   - /workflow:tools:task-generate --session WFS-auth
+  - /workflow:tools:task-generate --session WFS-auth --cli-execute
 ---
 
 # Task Generation Command
@@ -12,12 +12,30 @@ examples:
 ## Overview
 Generate task JSON files and IMPL_PLAN.md from analysis results with automatic artifact detection and integration.
 
+## Execution Modes
+
+### Agent Mode (Default)
+Tasks execute within agent context using agent's capabilities:
+- Agent reads synthesis specifications
+- Agent implements following requirements
+- Agent validates implementation
+- **Benefit**: Seamless context within single agent execution
+
+### CLI Execute Mode (`--cli-execute`)
+Tasks execute using Codex CLI with resume mechanism:
+- Each task uses `codex exec` command in `implementation_approach`
+- First task establishes Codex session
+- Subsequent tasks use `codex exec "..." resume --last` for context continuity
+- **Benefit**: Codex's autonomous development capabilities with persistent context
+- **Use Case**: Complex implementation requiring Codex's reasoning and iteration
+
 ## Core Philosophy
 - **Analysis-Driven**: Generate from ANALYSIS_RESULTS.md
 - **Artifact-Aware**: Auto-detect brainstorming outputs
 - **Context-Rich**: Embed comprehensive context in task JSON
 - **Flow-Control Ready**: Pre-define implementation steps
 - **Memory-First**: Reuse loaded documents from memory
+- **CLI-Aware**: Support Codex resume mechanism for persistent context
 
 ## Core Responsibilities
 - Parse analysis results and extract tasks
@@ -154,23 +172,52 @@ Generate task JSON files and IMPL_PLAN.md from analysis results with automatic a
         "on_error": "fail"
       }
     ],
-    "implementation_approach": {
-      "task_description": "Implement '[title]' following synthesis specification. PRIORITY: Use synthesis-specification.md as primary requirement source. When implementation needs technical details (e.g., API schemas, caching configs, design tokens), refer to artifacts[] for detailed specifications from original role analyses.",
-      "modification_points": [
-        "Apply consolidated requirements from synthesis-specification.md",
-        "Follow technical guidelines from synthesis",
-        "Consult artifacts for implementation details when needed",
-        "Integrate with existing patterns"
-      ],
-      "logic_flow": [
-        "Load synthesis specification",
-        "Extract requirements and design",
-        "Analyze existing patterns",
-        "Implement following specification",
-        "Consult artifacts for technical details when needed",
-        "Validate against acceptance criteria"
-      ]
-    },
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Implement task following synthesis specification",
+        "description": "Implement '[title]' following synthesis specification. PRIORITY: Use synthesis-specification.md as primary requirement source. When implementation needs technical details (e.g., API schemas, caching configs, design tokens), refer to artifacts[] for detailed specifications from original role analyses.",
+        "modification_points": [
+          "Apply consolidated requirements from synthesis-specification.md",
+          "Follow technical guidelines from synthesis",
+          "Consult artifacts for implementation details when needed",
+          "Integrate with existing patterns"
+        ],
+        "logic_flow": [
+          "Load synthesis specification",
+          "Extract requirements and design",
+          "Analyze existing patterns",
+          "Implement following specification",
+          "Consult artifacts for technical details when needed",
+          "Validate against acceptance criteria"
+        ],
+        "depends_on": [],
+        "output": "implementation"
+      }
+    ],
+
+    // CLI Execute Mode: Use Codex command (when --cli-execute flag present)
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Execute implementation with Codex",
+        "description": "Use Codex CLI to implement '[title]' following synthesis specification with autonomous development capabilities",
+        "modification_points": [
+          "Codex loads synthesis specification and artifacts",
+          "Codex implements following requirements",
+          "Codex validates and tests implementation"
+        ],
+        "logic_flow": [
+          "Establish or resume Codex session",
+          "Pass synthesis specification to Codex",
+          "Codex performs autonomous implementation",
+          "Codex validates against acceptance criteria"
+        ],
+        "command": "bash(codex -C [focus_paths] --full-auto exec \"PURPOSE: [title] TASK: [requirements] MODE: auto CONTEXT: @{[synthesis_path],[artifacts_paths]} EXPECTED: [acceptance] RULES: Follow synthesis-specification.md\" [resume_flag] --skip-git-repo-check -s danger-full-access)",
+        "depends_on": [],
+        "output": "implementation"
+      }
+    ],
     "target_files": ["file:function:lines"]
   }
 }
@@ -182,7 +229,37 @@ Generate task JSON files and IMPL_PLAN.md from analysis results with automatic a
 3. Generate task context (requirements, focus_paths, acceptance)
 4. **Determine modification targets**: Extract specific code locations from analysis
 5. Build flow_control with artifact loading steps and target_files
-6. Create individual task JSON files in `.task/`
+6. **CLI Execute Mode**: If `--cli-execute` flag present, generate Codex commands
+7. Create individual task JSON files in `.task/`
+
+#### Codex Resume Mechanism (CLI Execute Mode)
+
+**Session Continuity Strategy**:
+- **First Task** (no depends_on or depends_on=[]): Establish new Codex session
+  - Command: `codex -C [path] --full-auto exec "[prompt]" --skip-git-repo-check -s danger-full-access`
+  - Creates new session context
+
+- **Subsequent Tasks** (has depends_on): Resume previous Codex session
+  - Command: `codex --full-auto exec "[prompt]" resume --last --skip-git-repo-check -s danger-full-access`
+  - Maintains context from previous implementation
+  - **Critical**: `resume --last` flag enables context continuity
+
+**Resume Flag Logic**:
+```javascript
+// Determine resume flag based on task dependencies
+const resumeFlag = task.context.depends_on && task.context.depends_on.length > 0
+  ? "resume --last"
+  : "";
+
+// First task (IMPL-001): no resume flag
+// Later tasks (IMPL-002, IMPL-003): use "resume --last"
+```
+
+**Benefits**:
+- ✅ Shared context across related tasks
+- ✅ Codex learns from previous implementations
+- ✅ Consistent patterns and conventions
+- ✅ Reduced redundant analysis
 
 #### Target Files Generation (Critical)
 **Purpose**: Identify specific code locations for modification AND new files to create
@@ -543,8 +620,82 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 /workflow:tools:task-generate --session WFS-auth
 ```
 
+## CLI Execute Mode Examples
+
+### Example 1: First Task (Establish Session)
+```json
+{
+  "id": "IMPL-001",
+  "title": "Implement user authentication module",
+  "context": {
+    "depends_on": [],
+    "focus_paths": ["src/auth"],
+    "requirements": ["JWT-based authentication", "Login and registration endpoints"]
+  },
+  "flow_control": {
+    "implementation_approach": [{
+      "step": 1,
+      "title": "Execute implementation with Codex",
+      "command": "bash(codex -C src/auth --full-auto exec \"PURPOSE: Implement user authentication module TASK: JWT-based authentication with login and registration MODE: auto CONTEXT: @{.workflow/WFS-session/.brainstorming/synthesis-specification.md} EXPECTED: Complete auth module with tests RULES: Follow synthesis specification\" --skip-git-repo-check -s danger-full-access)",
+      "depends_on": [],
+      "output": "implementation"
+    }]
+  }
+}
+```
+
+### Example 2: Subsequent Task (Resume Session)
+```json
+{
+  "id": "IMPL-002",
+  "title": "Add password reset functionality",
+  "context": {
+    "depends_on": ["IMPL-001"],
+    "focus_paths": ["src/auth"],
+    "requirements": ["Password reset via email", "Token validation"]
+  },
+  "flow_control": {
+    "implementation_approach": [{
+      "step": 1,
+      "title": "Execute implementation with Codex",
+      "command": "bash(codex --full-auto exec \"PURPOSE: Add password reset functionality TASK: Password reset via email with token validation MODE: auto CONTEXT: Previous auth implementation from session EXPECTED: Password reset endpoints with email integration RULES: Maintain consistency with existing auth patterns\" resume --last --skip-git-repo-check -s danger-full-access)",
+      "depends_on": [],
+      "output": "implementation"
+    }]
+  }
+}
+```
+
+### Example 3: Third Task (Continue Session)
+```json
+{
+  "id": "IMPL-003",
+  "title": "Implement role-based access control",
+  "context": {
+    "depends_on": ["IMPL-001", "IMPL-002"],
+    "focus_paths": ["src/auth"],
+    "requirements": ["User roles and permissions", "Middleware for route protection"]
+  },
+  "flow_control": {
+    "implementation_approach": [{
+      "step": 1,
+      "title": "Execute implementation with Codex",
+      "command": "bash(codex --full-auto exec \"PURPOSE: Implement role-based access control TASK: User roles, permissions, and route protection middleware MODE: auto CONTEXT: Existing auth system from session EXPECTED: RBAC system integrated with current auth RULES: Use established patterns from session context\" resume --last --skip-git-repo-check -s danger-full-access)",
+      "depends_on": [],
+      "output": "implementation"
+    }]
+  }
+}
+```
+
+**Pattern Summary**:
+- IMPL-001: Fresh start with `-C src/auth` and full prompt
+- IMPL-002: Resume with `resume --last`, references "previous auth implementation"
+- IMPL-003: Resume with `resume --last`, references "existing auth system"
+
 ## Related Commands
 - `/workflow:plan` - Orchestrates entire planning
+- `/workflow:plan --cli-execute` - Planning with CLI execution mode
 - `/workflow:tools:context-gather` - Provides context package
 - `/workflow:tools:concept-enhanced` - Provides analysis results
 - `/workflow:execute` - Executes generated tasks

.claude/commands/workflow/tools/tdd-coverage-analysis.md

@@ -1,10 +1,7 @@
 ---
 name: tdd-coverage-analysis
 description: Analyze test coverage and TDD cycle execution
-usage: /workflow:tools:tdd-coverage-analysis --session <session_id>
 argument-hint: "--session WFS-session-id"
-examples:
-  - /workflow:tools:tdd-coverage-analysis --session WFS-auth
 allowed-tools: Read(*), Write(*), Bash(*)
 ---
 

.claude/commands/workflow/tools/test-concept-enhanced.md

@@ -1,7 +1,6 @@
 ---
 name: test-concept-enhanced
 description: Analyze test requirements and generate test generation strategy using Gemini
-usage: /workflow:tools:test-concept-enhanced --session <test_session_id> --context <test_context_package_path>
 argument-hint: "--session WFS-test-session-id --context path/to/test-context-package.json"
 examples:
   - /workflow:tools:test-concept-enhanced --session WFS-test-auth --context .workflow/WFS-test-auth/.process/test-context-package.json

.claude/commands/workflow/tools/test-context-gather.md

@@ -1,7 +1,6 @@
 ---
 name: test-context-gather
 description: Collect test coverage context and identify files requiring test generation
-usage: /workflow:tools:test-context-gather --session <test_session_id>
 argument-hint: "--session WFS-test-session-id"
 examples:
   - /workflow:tools:test-context-gather --session WFS-test-auth

.claude/commands/workflow/tools/test-task-generate.md

@@ -1,11 +1,12 @@
 ---
 name: test-task-generate
 description: Generate test-fix task JSON with iterative test-fix-retest cycle specification
-usage: /workflow:tools:test-task-generate [--use-codex] --session <test-session-id>
-argument-hint: "[--use-codex] --session WFS-test-session-id"
+argument-hint: "[--use-codex] [--cli-execute] --session WFS-test-session-id"
 examples:
   - /workflow:tools:test-task-generate --session WFS-test-auth
   - /workflow:tools:test-task-generate --use-codex --session WFS-test-auth
+  - /workflow:tools:test-task-generate --cli-execute --session WFS-test-auth
+  - /workflow:tools:test-task-generate --cli-execute --use-codex --session WFS-test-auth
 ---
 
 # Test Task Generation Command
@@ -13,6 +14,16 @@ examples:
 ## Overview
 Generate specialized test-fix task JSON with comprehensive test-fix-retest cycle specification, including Gemini diagnosis (using bug-fix template) and manual fix workflow (Codex automation only when explicitly requested).
 
+## Execution Modes
+
+### Test Generation (IMPL-001)
+- **Agent Mode (Default)**: @code-developer generates tests within agent context
+- **CLI Execute Mode (`--cli-execute`)**: Use Codex CLI for autonomous test generation
+
+### Test Fix (IMPL-002)
+- **Manual Mode (Default)**: Gemini diagnosis → user applies fixes
+- **Codex Mode (`--use-codex`)**: Gemini diagnosis → Codex applies fixes with resume mechanism
+
 ## Core Philosophy
 - **Analysis-Driven Test Generation**: Use TEST_ANALYSIS_RESULTS.md from test-concept-enhanced
 - **Agent-Based Test Creation**: Call @code-developer agent for comprehensive test generation
@@ -38,8 +49,9 @@ Generate specialized test-fix task JSON with comprehensive test-fix-retest cycle
 ### Phase 1: Input Validation & Discovery
 
 1. **Parameter Parsing**
-   - Parse `--use-codex` flag from command arguments
-   - Store flag value for IMPL-002.json generation
+   - Parse `--use-codex` flag from command arguments → Controls IMPL-002 fix mode
+   - Parse `--cli-execute` flag from command arguments → Controls IMPL-001 generation mode
+   - Store flag values for task JSON generation
 
 2. **Test Session Validation**
    - Load `.workflow/{test-session-id}/workflow-session.json`
@@ -143,31 +155,53 @@ Generate **TWO task JSON files**:
         "on_error": "skip_optional"
       }
     ],
-    "implementation_approach": {
-      "task_description": "Generate comprehensive test suite based on TEST_ANALYSIS_RESULTS.md. Follow test generation strategy and create all test files listed in section 5 (Implementation Targets).",
-      "generation_steps": [
-        "Read TEST_ANALYSIS_RESULTS.md section 3 (Test Requirements by File)",
-        "Read TEST_ANALYSIS_RESULTS.md section 4 (Test Generation Strategy)",
-        "Study existing test patterns from test_context.test_framework.conventions",
-        "For each test file in section 5 (Implementation Targets):",
-        "  - Create test file with specified scenarios",
-        "  - Implement happy path tests",
-        "  - Implement error handling tests",
-        "  - Implement edge case tests",
-        "  - Implement integration tests (if specified)",
-        "  - Add required mocks and fixtures",
-        "Follow test framework conventions and project standards",
-        "Ensure all tests are executable and syntactically valid"
+    // Agent Mode (Default): Agent implements tests
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Generate comprehensive test suite",
+        "description": "Generate comprehensive test suite based on TEST_ANALYSIS_RESULTS.md. Follow test generation strategy and create all test files listed in section 5 (Implementation Targets).",
+        "modification_points": [
+          "Read TEST_ANALYSIS_RESULTS.md sections 3 and 4",
+          "Study existing test patterns",
+          "Create test files with all required scenarios",
+          "Implement happy path, error handling, edge case, and integration tests",
+          "Add required mocks and fixtures"
+        ],
+        "logic_flow": [
+          "Read TEST_ANALYSIS_RESULTS.md section 3 (Test Requirements by File)",
+          "Read TEST_ANALYSIS_RESULTS.md section 4 (Test Generation Strategy)",
+          "Study existing test patterns from test_context.test_framework.conventions",
+          "For each test file in section 5 (Implementation Targets): Create test file with specified scenarios, Implement happy path tests, Implement error handling tests, Implement edge case tests, Implement integration tests (if specified), Add required mocks and fixtures",
+          "Follow test framework conventions and project standards",
+          "Ensure all tests are executable and syntactically valid"
+        ],
+        "depends_on": [],
+        "output": "test_suite"
+      }
+    ],
+
+    // CLI Execute Mode (--cli-execute): Use Codex command (alternative format shown below)
+    "implementation_approach": [{
+      "step": 1,
+      "title": "Generate tests using Codex",
+      "description": "Use Codex CLI to autonomously generate comprehensive test suite based on TEST_ANALYSIS_RESULTS.md",
+      "modification_points": [
+        "Codex loads TEST_ANALYSIS_RESULTS.md and existing test patterns",
+        "Codex generates all test files listed in analysis section 5",
+        "Codex ensures tests follow framework conventions"
       ],
-      "quality_criteria": [
-        "All test scenarios from analysis are implemented",
-        "Test structure matches existing patterns",
-        "Clear test descriptions and assertions",
-        "Proper setup/teardown and fixtures",
-        "Dependencies properly mocked",
-        "Tests follow project coding standards"
-      ]
-    },
+      "logic_flow": [
+        "Start new Codex session",
+        "Pass TEST_ANALYSIS_RESULTS.md to Codex",
+        "Codex studies existing test patterns",
+        "Codex generates comprehensive test suite",
+        "Codex validates test syntax and executability"
+      ],
+      "command": "bash(codex -C [focus_paths] --full-auto exec \"PURPOSE: Generate comprehensive test suite TASK: Create test files based on TEST_ANALYSIS_RESULTS.md section 5 MODE: write CONTEXT: @{.workflow/WFS-test-[session]/.process/TEST_ANALYSIS_RESULTS.md,.workflow/WFS-test-[session]/.process/test-context-package.json} EXPECTED: All test files with happy path, error handling, edge cases, integration tests RULES: Follow test framework conventions, ensure tests are executable\" --skip-git-repo-check -s danger-full-access)",
+      "depends_on": [],
+      "output": "test_generation"
+    }],
     "target_files": [
       "{test_file_1 from TEST_ANALYSIS_RESULTS.md section 5}",
       "{test_file_2 from TEST_ANALYSIS_RESULTS.md section 5}",
@@ -279,24 +313,27 @@ Generate **TWO task JSON files**:
         "on_error": "skip_optional"
       }
     ],
-    "implementation_approach": {
-      "task_description": "Execute iterative test-fix-retest cycle using Gemini diagnosis (bug-fix template) and manual fixes (Codex only if explicitly needed)",
-      "test_fix_cycle": {
-        "max_iterations": 5,
-        "cycle_pattern": "test → gemini_diagnose → manual_fix (or codex if needed) → retest",
-        "tools": {
-          "test_execution": "bash(test_command)",
-          "diagnosis": "gemini-wrapper (MODE: analysis, uses bug-fix template)",
-          "fix_application": "manual (default) or codex exec resume --last (if explicitly needed)",
-          "verification": "bash(test_command) + regression_check"
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Execute iterative test-fix-retest cycle",
+        "description": "Execute iterative test-fix-retest cycle using Gemini diagnosis (bug-fix template) and manual fixes (Codex only if meta.use_codex=true). Max 5 iterations with automatic revert on failure.",
+        "test_fix_cycle": {
+          "max_iterations": 5,
+          "cycle_pattern": "test → gemini_diagnose → manual_fix (or codex if needed) → retest",
+          "tools": {
+            "test_execution": "bash(test_command)",
+            "diagnosis": "gemini-wrapper (MODE: analysis, uses bug-fix template)",
+            "fix_application": "manual (default) or codex exec resume --last (if explicitly needed)",
+            "verification": "bash(test_command) + regression_check"
+          },
+          "exit_conditions": {
+            "success": "all_tests_pass",
+            "failure": "max_iterations_reached",
+            "error": "test_command_not_found"
+          }
         },
-        "exit_conditions": {
-          "success": "all_tests_pass",
-          "failure": "max_iterations_reached",
-          "error": "test_command_not_found"
-        }
-      },
-      "modification_points": [
+        "modification_points": [
         "PHASE 1: Initial Test Execution",
         "  1.1. Discover test command from framework detection",
         "  1.2. Execute initial test run: bash([test_command])",
@@ -428,33 +465,36 @@ Generate **TWO task JSON files**:
         "  Generate summary (include test generation info)",
         "  Certify code APPROVED"
       ],
-      "error_handling": {
-        "max_iterations_reached": {
-          "action": "revert_all_changes",
-          "commands": [
-            "bash(git reset --hard HEAD)",
-            "bash(jq '.status = \"blocked\"' .workflow/[session]/.task/IMPL-001.json > temp.json && mv temp.json .workflow/[session]/.task/IMPL-001.json)"
-          ],
-          "report": "Generate failure report with iteration logs in .summaries/IMPL-001-failure-report.md"
+        "error_handling": {
+          "max_iterations_reached": {
+            "action": "revert_all_changes",
+            "commands": [
+              "bash(git reset --hard HEAD)",
+              "bash(jq '.status = \"blocked\"' .workflow/[session]/.task/IMPL-001.json > temp.json && mv temp.json .workflow/[session]/.task/IMPL-001.json)"
+            ],
+            "report": "Generate failure report with iteration logs in .summaries/IMPL-001-failure-report.md"
+          },
+          "test_command_fails": {
+            "action": "treat_as_test_failure",
+            "context": "Use stderr as failure context for Gemini diagnosis"
+          },
+          "codex_apply_fails": {
+            "action": "retry_once_then_skip",
+            "fallback": "Mark iteration as skipped, continue to next"
+          },
+          "gemini_diagnosis_fails": {
+            "action": "retry_with_simplified_context",
+            "fallback": "Use previous diagnosis, continue"
+          },
+          "regression_detected": {
+            "action": "log_warning_continue",
+            "context": "Include regression info in next Gemini diagnosis"
+          }
         },
-        "test_command_fails": {
-          "action": "treat_as_test_failure",
-          "context": "Use stderr as failure context for Gemini diagnosis"
-        },
-        "codex_apply_fails": {
-          "action": "retry_once_then_skip",
-          "fallback": "Mark iteration as skipped, continue to next"
-        },
-        "gemini_diagnosis_fails": {
-          "action": "retry_with_simplified_context",
-          "fallback": "Use previous diagnosis, continue"
-        },
-        "regression_detected": {
-          "action": "log_warning_continue",
-          "context": "Include regression info in next Gemini diagnosis"
-        }
+        "depends_on": [],
+        "output": "test_fix_results"
       }
-    },
+    ],
     "target_files": [
       "Auto-discovered from test failures",
       "Extracted from Gemini diagnosis each iteration",

.claude/commands/workflow/ui-design/batch-generate.md

@@ -1,12 +1,7 @@
 ---
 name: batch-generate
 description: Prompt-driven batch UI generation using target-style-centric parallel execution
-usage: /workflow:ui-design:batch-generate --prompt "<description>" [--targets "<list>"] [--target-type "page|component"] [--device-type "desktop|mobile|tablet|responsive"] [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]
-examples:
-  - /workflow:ui-design:batch-generate --prompt "Dashboard with metrics cards" --style-variants 3
-  - /workflow:ui-design:batch-generate --prompt "Auth pages: login, signup" --session WFS-auth
-  - /workflow:ui-design:batch-generate --prompt "Navbar, hero, footer components" --target-type component
-  - /workflow:ui-design:batch-generate --prompt "Mobile e-commerce app" --device-type mobile
+argument-hint: [--targets "<list>"] [--target-type "page|component"] [--device-type "desktop|mobile|tablet|responsive"] [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]
 allowed-tools: TodoWrite(*), Read(*), Write(*), Task(ui-design-agent), Bash(*), mcp__exa__web_search_exa(*)
 ---
 

.claude/commands/workflow/ui-design/capture.md

@@ -1,12 +1,7 @@
 ---
 name: capture
 description: Batch screenshot capture for UI design workflows using MCP or local fallback
-usage: /workflow:ui-design:capture --url-map "<map>" [--base-path <path>] [--session <id>]
 argument-hint: --url-map "target:url,..." [--base-path path] [--session id]
-examples:
-  - /workflow:ui-design:capture --url-map "home:https://linear.app, pricing:https://linear.app/pricing"
-  - /workflow:ui-design:capture --session WFS-auth --url-map "dashboard:https://app.com/dash"
-  - /workflow:ui-design:capture --base-path ".workflow/.design/run-20250110" --url-map "hero:https://example.com#hero"
 allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*), ListMcpResourcesTool(*), mcp__chrome-devtools__*, mcp__playwright__*
 ---
 

.claude/commands/workflow/ui-design/consolidate.md

@@ -1,12 +1,7 @@
 ---
 name: consolidate
 description: Consolidate style variants into independent design systems and plan layout strategies
-usage: /workflow:ui-design:consolidate [--base-path <path>] [--session <id>] [--variants <count>] [--layout-variants <count>]
-examples:
-  - /workflow:ui-design:consolidate --base-path ".workflow/WFS-auth/design-run-20250109-143022" --variants 3
-  - /workflow:ui-design:consolidate --session WFS-auth --variants 2
-  - /workflow:ui-design:consolidate --base-path "./.workflow/.design/run-20250109-150533"  # Uses all variants
-  - /workflow:ui-design:consolidate --session WFS-auth  # Process all variants from extraction
+argument-hint: /workflow:ui-design:consolidate [--base-path <path>] [--session <id>] [--variants <count>] [--layout-variants <count>]
 allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Task(*)
 ---
 

.claude/commands/workflow/ui-design/explore-auto.md

@@ -1,13 +1,7 @@
 ---
 name: explore-auto
 description: Exploratory UI design workflow with style-centric batch generation
-usage: /workflow:ui-design:explore-auto [--prompt "<desc>"] [--images "<glob>"] [--targets "<list>"] [--target-type "page|component"] [--session <id>] [--style-variants <count>] [--layout-variants <count>] [--batch-plan]
-examples:
-  - /workflow:ui-design:explore-auto --prompt "Generate 3 style variants for modern blog: home, article, author"
-  - /workflow:ui-design:explore-auto --prompt "SaaS dashboard and settings with 2 layout options"
-  - /workflow:ui-design:explore-auto --images "refs/*.png" --prompt "E-commerce: home, product, cart" --style-variants 3 --layout-variants 3
-  - /workflow:ui-design:explore-auto --session WFS-auth --images "refs/*.png"
-  - /workflow:ui-design:explore-auto --targets "navbar,hero" --target-type "component" --style-variants 3 --layout-variants 2
+argument-hint: "[--prompt "<desc>"] [--images "<glob>"] [--targets "<list>"] [--target-type "page|component"] [--session <id>] [--style-variants <count>] [--layout-variants <count>] [--batch-plan]""
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*), Task(conceptual-planning-agent)
 ---
 

.claude/commands/workflow/ui-design/explore-layers.md

@@ -1,12 +1,7 @@
 ---
 name: explore-layers
 description: Interactive deep UI capture with depth-controlled layer exploration
-usage: /workflow:ui-design:explore-layers --url <url> --depth <1-5> [--session <id>] [--base-path <path>]
 argument-hint: --url <url> --depth <1-5> [--session id] [--base-path path]
-examples:
-  - /workflow:ui-design:explore-layers --url "https://app.linear.app" --depth 3
-  - /workflow:ui-design:explore-layers --url "https://notion.so" --depth 2 --session WFS-notion-ui
-  - /workflow:ui-design:explore-layers --url "https://app.com/dashboard" --depth 4
 allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*), mcp__chrome-devtools__*
 ---
 

.claude/commands/workflow/ui-design/generate.md

@@ -1,11 +1,7 @@
 ---
 name: generate
 description: Assemble UI prototypes by combining layout templates with design tokens (pure assembler)
-usage: /workflow:ui-design:generate [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]
-examples:
-  - /workflow:ui-design:generate --session WFS-auth
-  - /workflow:ui-design:generate --style-variants 2 --layout-variants 2
-  - /workflow:ui-design:generate --base-path ".workflow/WFS-auth/design-run-20250109-143022"
+argument-hint: [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]
 allowed-tools: TodoWrite(*), Read(*), Write(*), Task(ui-design-agent), Bash(*)
 ---
 
@@ -15,10 +11,11 @@ allowed-tools: TodoWrite(*), Read(*), Write(*), Task(ui-design-agent), Bash(*)
 Pure assembler that combines pre-extracted layout templates with design tokens to generate UI prototypes (`style × layout × targets`). No layout design logic - purely combines existing components.
 
 **Strategy**: Pure Assembly
-- **Input**: `layout-templates.json` + `design-tokens.json`
+- **Input**: `layout-templates.json` + `design-tokens.json` (+ reference images if available)
 - **Process**: Combine structure (DOM) with style (tokens)
 - **Output**: Complete HTML/CSS prototypes
 - **No Design Logic**: All layout and style decisions already made
+- **Automatic Image Reference**: If source images exist in layout templates, they're automatically used for visual context
 
 **Prerequisite Commands**:
 - `/workflow:ui-design:style-extract` → Style tokens
@@ -34,6 +31,8 @@ bash(find .workflow -type d -name "design-*" | head -1)  # Auto-detect
 
 # Get style count
 bash(ls {base_path}/style-consolidation/style-* -d | wc -l)
+
+# Image reference auto-detected from layout template source_image_path
 ```
 
 ### Step 2: Load Layout Templates
@@ -82,18 +81,29 @@ Task(ui-design-agent): `
   1. Layout Template:
      Read("{base_path}/layout-extraction/layout-templates.json")
      Find template where: target={target} AND variant_id="layout-{layout_id}"
-     Extract: dom_structure, css_layout_rules, device_type
+     Extract: dom_structure, css_layout_rules, device_type, source_image_path
 
   2. Design Tokens:
      Read("{base_path}/style-consolidation/style-{style_id}/design-tokens.json")
      Extract: ALL token values (colors, typography, spacing, borders, shadows, breakpoints)
 
+  3. Reference Image (AUTO-DETECTED):
+     IF template.source_image_path exists:
+       Read(template.source_image_path)
+       Purpose: Additional visual context for better placeholder content generation
+       Note: This is for reference only - layout and style decisions already made
+     ELSE:
+       Use generic placeholder content
+
   ## Assembly Process
   1. Build HTML: {base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.html
      - Recursively build from template.dom_structure
      - Add: <!DOCTYPE html>, <head>, <meta viewport>
      - CSS link: <link href="{target}-style-{style_id}-layout-{layout_id}.css">
-     - Inject placeholder content (Lorem ipsum, sample data)
+     - Inject placeholder content:
+       * Default: Use Lorem ipsum, generic sample data
+       * If reference image available: Generate more contextually appropriate placeholders
+         (e.g., realistic headings, meaningful text snippets that match the visual context)
      - Preserve all attributes from dom_structure
 
   2. Build CSS: {base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.css
@@ -173,6 +183,7 @@ Configuration:
 - Device Type: {device_type}
 - Targets: {targets}
 - Total Prototypes: {S × L × T}
+- Image Reference: Auto-detected (uses source images when available in layout templates)
 
 Assembly Process:
 - Pure assembly: Combined pre-extracted layouts + design tokens

.claude/commands/workflow/ui-design/imitate-auto.md

@@ -1,13 +1,7 @@
 ---
 name: imitate-auto
 description: High-speed multi-page UI replication with batch screenshot and optional token refinement
-usage: /workflow:ui-design:imitate-auto --url-map "<map>" [--capture-mode <batch|deep>] [--depth <1-5>] [--session <id>] [--refine-tokens] [--prompt "<desc>"]
-examples:
-  - /workflow:ui-design:imitate-auto --url-map "home:https://linear.app, features:https://linear.app/features"
-  - /workflow:ui-design:imitate-auto --session WFS-payment --url-map "pricing:https://stripe.com/pricing"
-  - /workflow:ui-design:imitate-auto --url-map "dashboard:https://app.com/dash" --refine-tokens
-  - /workflow:ui-design:imitate-auto --url-map "app:https://app.com" --capture-mode deep --depth 3
-  - /workflow:ui-design:imitate-auto --url-map "home:https://example.com, about:https://example.com/about" --prompt "Focus on minimalist design"
+argument-hint: --url-map "<map>" [--capture-mode <batch|deep>] [--depth <1-5>] [--session <id>] [--refine-tokens] [--prompt "<desc>"]
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Write(*), Bash(*)
 ---
 

.claude/commands/workflow/ui-design/layout-extract.md

@@ -1,12 +1,7 @@
 ---
 name: layout-extract
 description: Extract structural layout information from reference images, URLs, or text prompts
-usage: /workflow:ui-design:layout-extract [--base-path <path>] [--session <id>] [--images "<glob>"] [--urls "<list>"] [--prompt "<desc>"] [--targets "<list>"] [--mode <imitate|explore>] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>]
-examples:
-  - /workflow:ui-design:layout-extract --urls "home:https://linear.app" --mode imitate --targets "home"
-  - /workflow:ui-design:layout-extract --images "refs/*.png" --mode explore --variants 3 --targets "dashboard"
-  - /workflow:ui-design:layout-extract --prompt "Two-column blog with sticky sidebar" --mode explore --variants 2 --targets "blog-post"
-  - /workflow:ui-design:layout-extract --session WFS-auth --urls "login:https://clerk.dev" --device-type mobile --targets "login"
+argument-hint: [--base-path <path>] [--session <id>] [--images "<glob>"] [--urls "<list>"] [--prompt "<desc>"] [--targets "<list>"] [--mode <imitate|explore>] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>]
 allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), Bash(*), Task(ui-design-agent), mcp__exa__web_search_exa(*)
 ---
 
@@ -149,6 +144,11 @@ Task(ui-design-agent): `
   Each template must include:
   - target (string)
   - variant_id (string, e.g., "layout-1")
+  - source_image_path (string, REQUIRED): Path to the primary reference image used for this layout analysis
+    * For image input: Use the actual image file path from {images_pattern}
+    * For URL input: Use the screenshot path if available, or empty string
+    * For text/prompt input: Use empty string
+    * Example: "{base_path}/screenshots/home.png"
   - device_type (string)
   - design_philosophy (string)
   - dom_structure (JSON object)
@@ -281,6 +281,7 @@ bash(echo '{json}' > {base_path}/layout-extraction/layout-templates.json)
     {
       "target": "home",
       "variant_id": "layout-1",
+      "source_image_path": "{base_path}/screenshots/home.png",
       "device_type": "responsive",
       "design_philosophy": "Responsive 3-column holy grail layout with fixed header and footer",
       "dom_structure": {

.claude/commands/workflow/ui-design/style-extract.md

@@ -1,13 +1,7 @@
 ---
 name: style-extract
 description: Extract design style from reference images or text prompts using Claude's analysis
-usage: /workflow:ui-design:style-extract [--base-path <path>] [--session <id>] [--images "<glob>"] [--prompt "<desc>"] [--mode <imitate|explore>] [--variants <count>]
-examples:
-  - /workflow:ui-design:style-extract --images "design-refs/*.png" --mode explore --variants 3
-  - /workflow:ui-design:style-extract --prompt "Modern minimalist blog, dark theme" --mode explore --variants 3
-  - /workflow:ui-design:style-extract --session WFS-auth --images "refs/*.png" --prompt "Linear.app style" --mode imitate
-  - /workflow:ui-design:style-extract --base-path ".workflow/WFS-auth/design-run-20250109-143022" --images "refs/*.png" --mode explore --variants 3
-  - /workflow:ui-design:style-extract --prompt "Bold vibrant" --mode imitate  # High-fidelity single style
+argument-hint: "[--base-path <path>] [--session <id>] [--images "<glob>"] [--prompt "<desc>"] [--mode <imitate|explore>] [--variants <count>]"
 allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*)
 ---
 

.claude/commands/workflow/ui-design/update.md

@@ -1,10 +1,7 @@
 ---
 name: update
 description: Update brainstorming artifacts with finalized design system references
-usage: /workflow:ui-design:update --session <session_id> [--selected-prototypes "<list>"]
-examples:
-  - /workflow:ui-design:update --session WFS-auth
-  - /workflow:ui-design:update --session WFS-dashboard --selected-prototypes "dashboard-variant-1"
+argument-hint: --session <session_id> [--selected-prototypes "<list>"]
 allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
 ---
 

.claude/workflows/cli-templates/prompts/documentation/api-reference.txt

@@ -1,240 +0,0 @@
-# API-Level Documentation Template
-
-Generate comprehensive API documentation following this structure:
-
-## Overview
-[Brief description of the API's purpose and capabilities]
-
-## Authentication
-### Authentication Method
-[e.g., JWT, OAuth2, API Keys]
-
-### Obtaining Credentials
-```bash
-# Example authentication flow
-```
-
-### Using Credentials
-```http
-GET /api/resource HTTP/1.1
-Authorization: Bearer <token>
-```
-
----
-
-## Base URL
-```
-Production: https://api.example.com/v1
-Staging: https://staging.api.example.com/v1
-```
-
-## Common Response Codes
-| Code | Description |
-|------|-------------|
-| 200  | Success |
-| 201  | Created |
-| 400  | Bad Request |
-| 401  | Unauthorized |
-| 403  | Forbidden |
-| 404  | Not Found |
-| 500  | Internal Server Error |
-
----
-
-## Endpoints
-
-### Resource: Users
-
-#### GET /users
-**Description**: Retrieves a paginated list of users.
-
-**Query Parameters**:
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `limit` | number | No | Number of results (default: 20, max: 100) |
-| `offset` | number | No | Pagination offset (default: 0) |
-| `sort` | string | No | Sort field (e.g., `name`, `-created_at`) |
-
-**Example Request**:
-```http
-GET /users?limit=10&offset=0&sort=-created_at HTTP/1.1
-Authorization: Bearer <token>
-```
-
-**Response (200 OK)**:
-```json
-{
-  "data": [
-    {
-      "id": 1,
-      "name": "John Doe",
-      "email": "john@example.com",
-      "created_at": "2024-01-01T00:00:00Z"
-    }
-  ],
-  "pagination": {
-    "total": 100,
-    "limit": 10,
-    "offset": 0
-  }
-}
-```
-
-**Error Response (401 Unauthorized)**:
-```json
-{
-  "error": {
-    "code": "UNAUTHORIZED",
-    "message": "Invalid or expired token"
-  }
-}
-```
-
----
-
-#### GET /users/:id
-**Description**: Retrieves a single user by ID.
-
-**Path Parameters**:
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `id` | number | User ID |
-
-**Example Request**:
-```http
-GET /users/123 HTTP/1.1
-Authorization: Bearer <token>
-```
-
-**Response (200 OK)**:
-```json
-{
-  "id": 123,
-  "name": "John Doe",
-  "email": "john@example.com",
-  "created_at": "2024-01-01T00:00:00Z",
-  "updated_at": "2024-01-15T10:30:00Z"
-}
-```
-
----
-
-#### POST /users
-**Description**: Creates a new user.
-
-**Request Body**:
-```json
-{
-  "name": "Jane Smith",
-  "email": "jane@example.com",
-  "password": "securePassword123"
-}
-```
-
-**Validation Rules**:
-- `name`: Required, 2-100 characters
-- `email`: Required, valid email format, must be unique
-- `password`: Required, minimum 8 characters
-
-**Response (201 Created)**:
-```json
-{
-  "id": 124,
-  "name": "Jane Smith",
-  "email": "jane@example.com",
-  "created_at": "2024-01-20T12:00:00Z"
-}
-```
-
-**Error Response (400 Bad Request)**:
-```json
-{
-  "error": {
-    "code": "VALIDATION_ERROR",
-    "message": "Validation failed",
-    "details": [
-      {
-        "field": "email",
-        "message": "Email already exists"
-      }
-    ]
-  }
-}
-```
-
----
-
-#### PUT /users/:id
-**Description**: Updates an existing user.
-
-**Path Parameters**:
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `id` | number | User ID |
-
-**Request Body** (all fields optional):
-```json
-{
-  "name": "Jane Doe",
-  "email": "jane.doe@example.com"
-}
-```
-
-**Response (200 OK)**:
-```json
-{
-  "id": 124,
-  "name": "Jane Doe",
-  "email": "jane.doe@example.com",
-  "updated_at": "2024-01-21T09:15:00Z"
-}
-```
-
----
-
-#### DELETE /users/:id
-**Description**: Deletes a user.
-
-**Path Parameters**:
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `id` | number | User ID |
-
-**Response (204 No Content)**:
-[Empty response body]
-
----
-
-## Rate Limiting
-- **Limit**: 1000 requests per hour per API key
-- **Headers**:
-  - `X-RateLimit-Limit`: Total requests allowed
-  - `X-RateLimit-Remaining`: Requests remaining
-  - `X-RateLimit-Reset`: Unix timestamp when limit resets
-
----
-
-## SDKs and Client Libraries
-- [JavaScript/TypeScript SDK](./sdks/javascript.md)
-- [Python SDK](./sdks/python.md)
-
----
-
-## Webhooks
-[Description of webhook system if applicable]
-
----
-
-## Changelog
-### v1.1.0 (2024-01-20)
-- Added user sorting functionality
-- Improved error messages
-
-### v1.0.0 (2024-01-01)
-- Initial API release
-
----
-
-**API Version**: 1.1.0
-**Last Updated**: [Auto-generated timestamp]
-**Support**: api-support@example.com

.claude/workflows/cli-templates/prompts/documentation/api.txt

@@ -0,0 +1,337 @@
+# Unified API Documentation Template
+
+Generate comprehensive API documentation. This template supports both **Code API** (for libraries/modules) and **HTTP API** (for web services). Include only the sections relevant to your project type.
+
+---
+
+## Part A: Code API (For Libraries, Modules, SDKs)
+
+**Use this section when documenting**: Exported functions, classes, interfaces, and types from code modules.
+
+**Omit this section if**: This is a pure web service with only HTTP endpoints and no programmatic API.
+
+### 1. Exported Functions
+
+For each exported function, provide:
+```typescript
+/**
+ * Brief one-line description of what the function does
+ * @param paramName - Parameter type and description
+ * @returns Return type and description
+ * @throws ErrorType - When this error occurs
+ */
+export function functionName(paramName: ParamType): ReturnType;
+```
+
+**Example**:
+```typescript
+/**
+ * Authenticates a user with email and password
+ * @param credentials - User email and password
+ * @returns Authentication token and user info
+ * @throws AuthenticationError - When credentials are invalid
+ */
+export function authenticate(credentials: Credentials): Promise<AuthResult>;
+```
+
+### 2. Exported Classes
+
+For each exported class, provide:
+```typescript
+/**
+ * Brief one-line description of the class purpose
+ */
+export class ClassName {
+  constructor(param: Type);
+
+  // Public properties
+  propertyName: Type;
+
+  // Public methods
+  methodName(param: Type): ReturnType;
+}
+```
+
+**Example**:
+```typescript
+/**
+ * Manages user session lifecycle and token refresh
+ */
+export class SessionManager {
+  constructor(config: SessionConfig);
+
+  // Current session state
+  isActive: boolean;
+
+  // Refresh the session token
+  refresh(): Promise<void>;
+
+  // Terminate the session
+  destroy(): void;
+}
+```
+
+### 3. Exported Interfaces
+
+For each exported interface, provide:
+```typescript
+/**
+ * Brief description of what this interface represents
+ */
+export interface InterfaceName {
+  field1: Type;  // Field description
+  field2: Type;  // Field description
+  method?: (param: Type) => ReturnType;  // Optional method
+}
+```
+
+### 4. Type Definitions
+
+For each exported type, provide:
+```typescript
+/**
+ * Brief description of what this type represents
+ */
+export type TypeName = string | number | CustomType;
+```
+
+---
+
+## Part B: HTTP API (For Web Services, REST APIs, GraphQL)
+
+**Use this section when documenting**: HTTP endpoints, REST APIs, GraphQL APIs, webhooks.
+
+**Omit this section if**: This is a library/SDK with no HTTP interface.
+
+### 1. Overview
+
+[Brief description of the API's purpose and capabilities]
+
+**Base URL**:
+```
+Production: https://api.example.com/v1
+Staging: https://staging.api.example.com/v1
+Development: http://localhost:3000/api/v1
+```
+
+### 2. Authentication
+
+#### Authentication Method
+[e.g., JWT Bearer Token, OAuth2, API Keys]
+
+#### Obtaining Credentials
+```bash
+# Example: Login to get token
+curl -X POST https://api.example.com/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email": "user@example.com", "password": "password"}'
+```
+
+#### Using Credentials
+```http
+GET /api/resource HTTP/1.1
+Authorization: Bearer <token>
+```
+
+### 3. Common Response Codes
+
+| Code | Description | Common Causes |
+|------|-------------|---------------|
+| 200  | Success | Request completed successfully |
+| 201  | Created | Resource created successfully |
+| 400  | Bad Request | Invalid request body or parameters |
+| 401  | Unauthorized | Missing or invalid authentication |
+| 403  | Forbidden | Authenticated but not authorized |
+| 404  | Not Found | Resource does not exist |
+| 429  | Too Many Requests | Rate limit exceeded |
+| 500  | Internal Server Error | Server-side error |
+
+### 4. Endpoints
+
+#### Resource: [Resource Name, e.g., Users]
+
+##### GET /resource
+**Description**: [What this endpoint does]
+
+**Query Parameters**:
+| Parameter | Type | Required | Description | Default |
+|-----------|------|----------|-------------|---------|
+| `limit` | number | No | Number of results | 20 |
+| `offset` | number | No | Pagination offset | 0 |
+
+**Example Request**:
+```http
+GET /users?limit=10&offset=0 HTTP/1.1
+Authorization: Bearer <token>
+```
+
+**Response (200 OK)**:
+```json
+{
+  "data": [
+    {
+      "id": 1,
+      "name": "John Doe",
+      "email": "john@example.com"
+    }
+  ],
+  "pagination": {
+    "total": 100,
+    "limit": 10,
+    "offset": 0
+  }
+}
+```
+
+**Error Response (401 Unauthorized)**:
+```json
+{
+  "error": {
+    "code": "UNAUTHORIZED",
+    "message": "Invalid or expired token"
+  }
+}
+```
+
+---
+
+##### POST /resource
+**Description**: [What this endpoint does]
+
+**Request Body**:
+```json
+{
+  "field1": "value",
+  "field2": 123
+}
+```
+
+**Validation Rules**:
+- `field1`: Required, 2-100 characters
+- `field2`: Required, positive integer
+
+**Response (201 Created)**:
+```json
+{
+  "id": 124,
+  "field1": "value",
+  "field2": 123,
+  "created_at": "2024-01-20T12:00:00Z"
+}
+```
+
+---
+
+##### PUT /resource/:id
+**Description**: [What this endpoint does]
+
+**Path Parameters**:
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `id` | number | Resource ID |
+
+**Request Body** (all fields optional):
+```json
+{
+  "field1": "new value"
+}
+```
+
+**Response (200 OK)**:
+```json
+{
+  "id": 124,
+  "field1": "new value",
+  "updated_at": "2024-01-21T09:15:00Z"
+}
+```
+
+---
+
+##### DELETE /resource/:id
+**Description**: [What this endpoint does]
+
+**Path Parameters**:
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `id` | number | Resource ID |
+
+**Response (204 No Content)**:
+[Empty response body]
+
+---
+
+### 5. Rate Limiting
+
+- **Limit**: 1000 requests per hour per API key
+- **Headers**:
+  - `X-RateLimit-Limit`: Total requests allowed
+  - `X-RateLimit-Remaining`: Requests remaining
+  - `X-RateLimit-Reset`: Unix timestamp when limit resets
+
+**Example Response Headers**:
+```http
+X-RateLimit-Limit: 1000
+X-RateLimit-Remaining: 847
+X-RateLimit-Reset: 1640000000
+```
+
+### 6. Webhooks (Optional)
+
+[Description of webhook system if applicable]
+
+**Webhook Events**:
+- `resource.created` - Triggered when a new resource is created
+- `resource.updated` - Triggered when a resource is updated
+- `resource.deleted` - Triggered when a resource is deleted
+
+**Webhook Payload Example**:
+```json
+{
+  "event": "resource.created",
+  "timestamp": "2024-01-20T12:00:00Z",
+  "data": {
+    "id": 124,
+    "field1": "value"
+  }
+}
+```
+
+---
+
+## Rules
+
+1. **Include only relevant sections** - Skip Part A for pure web services, skip Part B for pure libraries
+2. **Signatures only in Part A** - No implementation code in Code API section
+3. **Complete examples in Part B** - All HTTP examples should be runnable
+4. **Consistent formatting** - Use language-specific code blocks (TypeScript, HTTP, JSON, bash)
+5. **Brief descriptions** - One line per item is sufficient for Code API
+6. **Detailed explanations for HTTP** - Include request/response examples, validation rules, error cases
+7. **Alphabetical order** - Sort items within each section for easy lookup
+8. **Public API only** - Do not document internal/private exports or endpoints
+
+---
+
+## Template Usage Guidelines
+
+### For Module-Level API.md (Code API)
+**Use**: Part A only
+**Location**: `modules/[module-name]/API.md`
+**Focus**: Exported functions, classes, interfaces
+
+### For Project-Level HTTP API Documentation
+**Use**: Part B only
+**Location**: `.workflow/docs/api/README.md`
+**Focus**: REST/GraphQL endpoints, authentication
+
+### For Full-Stack Projects (Both Code and HTTP APIs)
+**Use**: Both Part A and Part B
+**Organization**:
+- Part A for SDK/client library APIs
+- Part B for HTTP endpoints
+
+---
+
+**Last Updated**: [Auto-generated timestamp]
+**API Version**: [Version number]
+**Module/Service Path**: [Auto-fill with actual path]

.claude/workflows/cli-templates/prompts/documentation/folder-navigation.txt

@@ -0,0 +1,68 @@
+# Folder Navigation Documentation Template
+
+Generate a navigation README for directories that contain only subdirectories (no code files). This serves as an index to help readers navigate to specific modules.
+
+## Structure
+
+### 1. Overview
+
+Brief description of what this directory/category contains:
+
+> The `modules/` directory contains the core business logic modules of the application. Each subdirectory represents a self-contained functional module with its own responsibilities.
+
+### 2. Directory Structure
+
+Provide a tree view of the subdirectories with brief descriptions:
+
+```
+modules/
+├── auth/              - User authentication and authorization
+├── api/               - API route handlers and middleware
+├── database/          - Database connections and ORM models
+└── utils/             - Shared utility functions
+```
+
+### 3. Module Quick Reference
+
+Table format for quick scanning:
+
+| Module | Purpose | Key Features |
+|--------|---------|--------------|
+| [auth](./auth/) | Authentication | JWT tokens, session management |
+| [api](./api/) | API routing | REST endpoints, validation |
+| [database](./database/) | Data layer | PostgreSQL, migrations |
+| [utils](./utils/) | Utilities | Logging, helpers |
+
+### 4. How to Navigate
+
+Guidance on which module to explore based on needs:
+
+- **For authentication logic** → [auth module](./auth/)
+- **For API endpoints** → [api module](./api/)
+- **For database queries** → [database module](./database/)
+- **For helper functions** → [utils module](./utils/)
+
+### 5. Module Relationships (Optional)
+
+If modules have significant dependencies, show them:
+
+```
+api → auth (uses for authentication)
+api → database (uses for data access)
+auth → database (uses for user storage)
+```
+
+---
+
+## Rules
+
+1. **Keep it brief** - This is an index, not detailed documentation
+2. **One-line descriptions** - Each module gets a concise purpose statement
+3. **Scannable format** - Use tables and lists for quick navigation
+4. **Link to submodules** - Every module mentioned should link to its README
+5. **No code examples** - This is navigation only
+
+---
+
+**Directory Path**: [Auto-fill with actual directory path]
+**Last Updated**: [Auto-generated timestamp]

.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt

@@ -1,91 +0,0 @@
-# Module-Level Documentation Template
-
-Generate detailed module documentation following this structure:
-
-## 1. Purpose and Responsibilities
-[What this module does, its boundaries, and its role in the larger system]
-
-## 2. Internal Architecture
-- **Key Components**:
-  - [Component 1]: [Description and responsibility]
-  - [Component 2]: [Description and responsibility]
-- **Data Flow**: [How data moves through the module, with diagrams if applicable]
-- **Core Logic**: [Explanation of the main business logic and algorithms]
-- **State Management**: [How state is managed within the module]
-
-## 3. Public API / Interface
-### Exported Functions
-```typescript
-/**
- * Function description
- * @param param1 - Parameter description
- * @returns Return value description
- */
-export function exampleFunction(param1: Type): ReturnType;
-```
-
-### Exported Classes
-```typescript
-/**
- * Class description
- */
-export class ExampleClass {
-  // Public methods and properties
-}
-```
-
-### Usage Examples
-```typescript
-import { exampleFunction } from './module';
-
-// Example 1: Basic usage
-const result = exampleFunction(input);
-
-// Example 2: Advanced usage
-// ...
-```
-
-## 4. Dependencies
-### Internal Dependencies
-- **[Module A]**: [Why this dependency exists, what it provides]
-- **[Module B]**: [Purpose of dependency]
-
-### External Dependencies
-- **[Library 1]** (`version`): [Purpose and usage]
-- **[Library 2]** (`version`): [Purpose and usage]
-
-## 5. Configuration
-### Environment Variables
-- `ENV_VAR_NAME`: [Description, default value]
-
-### Configuration Options
-```typescript
-interface ModuleConfig {
-  option1: Type; // Description
-  option2: Type; // Description
-}
-```
-
-## 6. Testing
-### Running Tests
-```bash
-npm test -- module-name
-```
-
-### Test Coverage
-- Unit tests: [Coverage percentage or key test files]
-- Integration tests: [Coverage or test scenarios]
-
-## 7. Common Use Cases
-1. **Use Case 1**: [Description and code example]
-2. **Use Case 2**: [Description and code example]
-
-## 8. Troubleshooting
-### Common Issues
-- **Issue 1**: [Description and solution]
-- **Issue 2**: [Description and solution]
-
----
-**Module Path**: [File path]
-**Last Updated**: [Auto-generated timestamp]
-**Owner/Maintainer**: [Team or individual]

.claude/workflows/cli-templates/prompts/documentation/module-readme.txt

@@ -0,0 +1,98 @@
+# Module README Documentation Template
+
+Generate comprehensive module documentation focused on understanding and usage. Explain WHAT the module does, WHY it exists, and HOW to use it. Do NOT duplicate API signatures (those belong in API.md).
+
+## Structure
+
+### 1. Purpose
+
+**What**: Clearly state what this module is responsible for
+**Why**: Explain why this module exists and what problems it solves
+**Boundaries**: Define what is IN scope and OUT of scope
+
+Example:
+> The `auth` module handles user authentication and authorization. It exists to centralize security logic and provide a consistent authentication interface across the application. It does NOT handle user profile management or session storage.
+
+### 2. Core Concepts
+
+List and explain key concepts, patterns, or abstractions used by this module:
+
+- **Concept 1**: [Brief explanation of important concept]
+- **Concept 2**: [Another key concept users should understand]
+- **Pattern**: [Architectural pattern used, e.g., "Uses middleware pattern for request processing"]
+
+### 3. Usage Scenarios
+
+Provide 2-4 common use cases with code examples:
+
+#### Scenario 1: [Common use case title]
+```typescript
+// Brief example showing how to use the module for this scenario
+import { functionName } from './module';
+
+const result = functionName(input);
+```
+
+#### Scenario 2: [Another common use case]
+```typescript
+// Another practical example
+```
+
+### 4. Dependencies
+
+#### Internal Dependencies
+List other project modules this module depends on and explain why:
+- **[Module Name]** - [Why this dependency exists and what it provides]
+
+#### External Dependencies
+List third-party libraries and their purpose:
+- **[Library Name]** (`version`) - [What functionality it provides to this module]
+
+### 5. Configuration
+
+#### Environment Variables
+List any environment variables the module uses:
+- `ENV_VAR_NAME` - [Description, type, default value]
+
+#### Configuration Options
+If the module accepts configuration objects:
+```typescript
+// Example configuration
+const config = {
+  option1: value,  // Description of option1
+  option2: value,  // Description of option2
+};
+```
+
+### 6. Testing
+
+Explain how to test code that uses this module:
+```bash
+# Command to run tests for this module
+npm test -- path/to/module
+```
+
+**Test Coverage**: [Brief note on what's tested]
+
+### 7. Common Issues
+
+List 2-3 common problems and their solutions:
+
+#### Issue: [Common problem description]
+**Solution**: [How to resolve it]
+
+---
+
+## Rules
+
+1. **No API duplication** - Refer to API.md for signatures
+2. **Focus on understanding** - Explain concepts, not just code
+3. **Practical examples** - Show real usage, not trivial cases
+4. **Clear dependencies** - Help readers understand module relationships
+5. **Concise** - Each section should be scannable and to-the-point
+
+---
+
+**Module Path**: [Auto-fill with actual module path]
+**Last Updated**: [Auto-generated timestamp]
+**See also**: [Link to API.md for interface details]

.claude/workflows/cli-templates/prompts/documentation/project-architecture.txt

@@ -0,0 +1,167 @@
+# Project Architecture Documentation Template
+
+Generate comprehensive architecture documentation that synthesizes information from all module documents. Focus on system-level design, module relationships, and aggregated API overview. This document should be created AFTER all module documentation is complete.
+
+## Structure
+
+### 1. System Overview
+
+High-level description of the system architecture:
+
+**Architectural Style**: [e.g., Layered, Microservices, Event-Driven, Hexagonal]
+
+**Core Principles**:
+- [Principle 1, e.g., "Separation of concerns"]
+- [Principle 2, e.g., "Dependency inversion"]
+- [Principle 3, e.g., "Single responsibility"]
+
+**Technology Stack**:
+- **Languages**: [Primary programming languages]
+- **Frameworks**: [Key frameworks]
+- **Databases**: [Data storage solutions]
+- **Infrastructure**: [Deployment, hosting, CI/CD]
+
+### 2. System Structure
+
+Visual representation of the system structure using text diagrams:
+
+```
+┌─────────────────────────────────────┐
+│         Application Layer           │
+│  (API Routes, Controllers)          │
+└────────────┬────────────────────────┘
+             │
+┌────────────▼────────────────────────┐
+│       Business Logic Layer          │
+│  (Modules: auth, orders, payments)  │
+└────────────┬────────────────────────┘
+             │
+┌────────────▼────────────────────────┐
+│        Data Access Layer            │
+│  (Database, ORM, Repositories)      │
+└─────────────────────────────────────┘
+```
+
+### 3. Module Map
+
+Comprehensive list of all modules with their responsibilities:
+
+| Module | Layer | Responsibility | Dependencies |
+|--------|-------|----------------|--------------|
+| `auth` | Business | Authentication & authorization | database, utils |
+| `api` | Application | HTTP routing & validation | auth, orders |
+| `database` | Data | Data persistence | - |
+| `utils` | Infrastructure | Shared utilities | - |
+
+### 4. Module Interactions
+
+Describe key interaction patterns between modules:
+
+#### Data Flow Example: User Authentication
+```
+1. Client → api/login endpoint
+2. api → auth.authenticateUser()
+3. auth → database.findUser()
+4. database → PostgreSQL
+5. auth → JWT token generation
+6. api → Response with token
+```
+
+#### Dependency Graph
+```
+api ──────┐
+          ├──→ auth ───→ database
+orders ───┤              ↑
+          └──────────────┘
+```
+
+### 5. Design Patterns
+
+Document key architectural patterns used:
+
+#### Pattern 1: [Pattern Name, e.g., "Repository Pattern"]
+- **Where**: [Which modules use this pattern]
+- **Why**: [Reason for using this pattern]
+- **How**: [Brief explanation of implementation]
+
+#### Pattern 2: [Another pattern]
+[Similar structure]
+
+### 6. Aggregated API Overview
+
+High-level summary of all public APIs across modules. Group by category:
+
+#### Authentication APIs
+- `auth.authenticate(credentials)` - Validate user credentials
+- `auth.authorize(user, permission)` - Check user permissions
+- `auth.generateToken(userId)` - Create JWT token
+
+#### Data APIs
+- `database.findOne(query)` - Find single record
+- `database.findMany(query)` - Find multiple records
+- `database.insert(data)` - Insert new record
+
+#### Utility APIs
+- `utils.logger.log(message)` - Application logging
+- `utils.validator.validate(data, schema)` - Data validation
+
+*Note: For detailed API signatures, refer to individual module API.md files*
+
+### 7. Data Flow
+
+Describe how data moves through the system:
+
+**Request Lifecycle**:
+1. HTTP request enters through API layer
+2. Request validation and authentication (auth module)
+3. Business logic processing (domain modules)
+4. Data persistence (database module)
+5. Response formatting and return
+
+**Event Flow** (if applicable):
+- [Describe event-driven flows if present]
+
+### 8. Security Architecture
+
+Overview of security measures:
+
+- **Authentication**: [JWT, OAuth2, etc.]
+- **Authorization**: [RBAC, ACL, etc.]
+- **Data Protection**: [Encryption, hashing]
+- **API Security**: [Rate limiting, CORS, etc.]
+
+### 9. Scalability Considerations
+
+Architectural decisions that support scalability:
+
+- [Horizontal scaling approach]
+- [Caching strategy]
+- [Database optimization]
+- [Load balancing]
+
+---
+
+## Rules
+
+1. **Synthesize, don't duplicate** - Reference module docs, don't copy them
+2. **System-level perspective** - Focus on how modules work together
+3. **Visual aids** - Use diagrams for clarity (ASCII art is fine)
+4. **Aggregated APIs** - One-line summaries only, link to detailed docs
+5. **Design rationale** - Explain WHY decisions were made
+6. **Maintain consistency** - Ensure all module docs are considered
+
+---
+
+## Required Inputs
+
+This document requires the following to be available:
+- All module README.md files (for understanding module purposes)
+- All module API.md files (for aggregating API overview)
+- Project README.md (for context and navigation)
+
+---
+
+**Last Updated**: [Auto-generated timestamp]
+**See also**:
+- [Project README](./README.md) for project overview
+- [Module Documentation](./modules/) for detailed module docs

.claude/workflows/cli-templates/prompts/documentation/project-examples.txt

@@ -0,0 +1,205 @@
+# Project Examples Documentation Template
+
+Generate practical, end-to-end examples demonstrating core usage patterns of the project. Focus on realistic scenarios that span multiple modules. These examples should help users understand how to accomplish common tasks.
+
+## Structure
+
+### 1. Introduction
+
+Brief overview of what these examples cover:
+
+> This document provides complete, working examples for common use cases. Each example demonstrates how multiple modules work together to accomplish a specific task.
+
+**Prerequisites**:
+- [List required setup, e.g., "Project installed and configured"]
+- [Environment requirements, e.g., "PostgreSQL running on localhost"]
+
+### 2. Quick Start Example
+
+The simplest possible working example to get started:
+
+```typescript
+// The minimal example to verify setup
+import { App } from './src';
+
+const app = new App();
+await app.start();
+console.log('Application running!');
+```
+
+**What this does**: [Brief explanation]
+
+### 3. Core Use Cases
+
+Provide 3-5 complete examples for common scenarios:
+
+#### Example 1: [Scenario Name, e.g., "User Registration and Login"]
+
+**Objective**: [What this example accomplishes]
+
+**Modules involved**: `auth`, `database`, `api`
+
+**Complete code**:
+```typescript
+import { createUser, authenticateUser } from './modules/auth';
+import { startServer } from './modules/api';
+
+// Step 1: Initialize the application
+const app = await startServer({ port: 3000 });
+
+// Step 2: Register a new user
+const user = await createUser({
+  email: 'user@example.com',
+  password: 'securePassword123',
+  name: 'John Doe'
+});
+
+// Step 3: Authenticate the user
+const session = await authenticateUser({
+  email: 'user@example.com',
+  password: 'securePassword123'
+});
+
+// Step 4: Use the authentication token
+console.log('Login successful, token:', session.token);
+```
+
+**Expected output**:
+```
+Server started on port 3000
+User created: { id: 1, email: 'user@example.com', name: 'John Doe' }
+Login successful, token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+```
+
+**Explanation**:
+1. [Step-by-step breakdown of what each part does]
+2. [How modules interact]
+3. [Common variations or customizations]
+
+---
+
+#### Example 2: [Another Common Scenario]
+
+[Similar structure with complete code]
+
+---
+
+#### Example 3: [Another Use Case]
+
+[Similar structure with complete code]
+
+### 4. Advanced Examples
+
+More complex scenarios for power users:
+
+#### Advanced Example 1: [Complex Scenario]
+
+**Objective**: [What this example accomplishes]
+
+**Modules involved**: [List]
+
+```typescript
+// Complete working code with detailed comments
+```
+
+**Key points**:
+- [Important concept or gotcha]
+- [Performance consideration]
+- [Security note]
+
+### 5. Integration Examples
+
+Examples showing how to integrate with external systems:
+
+#### Integration with [External System]
+
+```typescript
+// Example of integrating with a third-party service
+```
+
+### 6. Testing Examples
+
+Show how to test code that uses this project:
+
+```typescript
+// Example test case using the project
+import { describe, it, expect } from 'your-test-framework';
+
+describe('User authentication', () => {
+  it('should authenticate valid credentials', async () => {
+    const result = await authenticateUser({
+      email: 'test@example.com',
+      password: 'password123'
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.token).toBeDefined();
+  });
+});
+```
+
+### 7. Best Practices
+
+Demonstrate recommended patterns:
+
+#### Pattern 1: [Best Practice Title]
+```typescript
+// Good: Recommended approach
+const result = await handleWithErrorRecovery(operation);
+
+// Bad: Anti-pattern to avoid
+const result = operation(); // No error handling
+```
+
+**Why**: [Explanation of why this is the best approach]
+
+#### Pattern 2: [Another Best Practice]
+[Similar structure]
+
+### 8. Troubleshooting Common Issues
+
+Example-based solutions to common problems:
+
+#### Issue: [Common Problem]
+
+**Symptom**: [What the user experiences]
+
+**Solution**:
+```typescript
+// Before: Code that causes the issue
+const broken = doSomethingWrong();
+
+// After: Corrected code
+const fixed = doSomethingRight();
+```
+
+---
+
+## Rules
+
+1. **Complete, runnable code** - Every example should be copy-paste ready
+2. **Real-world scenarios** - Avoid trivial or contrived examples
+3. **Explain the flow** - Show how modules work together
+4. **Include output** - Show what users should expect to see
+5. **Error handling** - Demonstrate proper error handling patterns
+6. **Comment complex parts** - Help readers understand non-obvious code
+7. **Version compatibility** - Note if examples are version-specific
+
+---
+
+## Code Quality Standards
+
+All example code should:
+- Follow project coding standards
+- Include proper error handling
+- Use async/await correctly
+- Show TypeScript types where applicable
+- Be tested and verified to work
+
+---
+
+**Last Updated**: [Auto-generated timestamp]
+**See also**:
+- [Project README](./README.md) for getting started
+- [Architecture](./ARCHITECTURE.md) for understanding system design
+- [Module Documentation](./modules/) for API details

.claude/workflows/task-core.md

@@ -42,11 +42,17 @@ All task files use this simplified 5-field schema (aligned with workflow-archite
         "on_error": "skip_optional"
       }
     ],
-    "implementation_approach": {
-      "task_description": "Implement comprehensive JWT authentication system...",
-      "modification_points": ["Add JWT token generation...", "..."],
-      "logic_flow": ["User login request → validate credentials...", "..."]
-    },
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Implement JWT authentication system",
+        "description": "Implement comprehensive JWT authentication system with token generation, validation, and refresh logic",
+        "modification_points": ["Add JWT token generation", "Implement token validation middleware", "Create refresh token logic"],
+        "logic_flow": ["User login request → validate credentials", "Generate JWT access and refresh tokens", "Store refresh token securely", "Return tokens to client"],
+        "depends_on": [],
+        "output": "jwt_implementation"
+      }
+    ],
     "target_files": [
       "src/auth/login.ts:handleLogin:75-120",
       "src/middleware/auth.ts:validateToken",

.claude/workflows/tool-control.yaml

@@ -0,0 +1,10 @@
+# Tool Control Configuration
+# Controls whether CLI tools (Gemini, Qwen, Codex) are enabled in the workspace
+
+tools:
+  gemini:
+    enabled: true
+  qwen:
+    enabled: true
+  codex:
+    enabled: true

.claude/workflows/workflow-architecture.md

@@ -162,17 +162,61 @@ All task files use this unified 5-field schema with optional artifacts enhanceme
         "output_to": "context"
       }
     ],
-    "implementation_approach": {
-      "task_description": "Implement JWT authentication following [design]",
-      "modification_points": [
-        "Add JWT generation using [parent] patterns",
-        "Implement validation middleware from [context]"
-      ],
-      "logic_flow": [
-        "User login → validate with [inherited] → generate JWT",
-        "Protected route → extract JWT → validate using [shared] rules"
-      ]
-    },
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Set up authentication infrastructure",
+        "description": "Install JWT library and create auth config following [design] patterns from [parent]",
+        "modification_points": [
+          "Add JWT library dependencies to package.json",
+          "Create auth configuration file using [parent] patterns"
+        ],
+        "logic_flow": [
+          "Install jsonwebtoken library via npm",
+          "Configure JWT secret and expiration from [inherited]",
+          "Export auth config for use by [jwt_generator]"
+        ],
+        "depends_on": [],
+        "output": "auth_config"
+      },
+      {
+        "step": 2,
+        "title": "Implement JWT generation",
+        "description": "Create JWT token generation logic using [auth_config] and [inherited] validation patterns",
+        "modification_points": [
+          "Add JWT generation function in auth service",
+          "Implement token signing with [auth_config]"
+        ],
+        "logic_flow": [
+          "User login → validate credentials with [inherited]",
+          "Generate JWT payload with user data",
+          "Sign JWT using secret from [auth_config]",
+          "Return signed token"
+        ],
+        "depends_on": [1],
+        "output": "jwt_generator"
+      },
+      {
+        "step": 3,
+        "title": "Implement JWT validation middleware",
+        "description": "Create middleware to validate JWT tokens using [auth_config] and [shared] rules",
+        "modification_points": [
+          "Create validation middleware using [jwt_generator]",
+          "Add token verification using [shared] rules",
+          "Implement user attachment to request object"
+        ],
+        "logic_flow": [
+          "Protected route → extract JWT from Authorization header",
+          "Validate token signature using [auth_config]",
+          "Check token expiration and [shared] rules",
+          "Decode payload and attach user to request",
+          "Call next() or return 401 error"
+        ],
+        "command": "bash(npm test -- middleware.test.ts)",
+        "depends_on": [1, 2],
+        "output": "auth_middleware"
+      }
+    ],
     "target_files": [
       "src/auth/login.ts:handleLogin:75-120",
       "src/middleware/auth.ts:validateToken",
@@ -208,33 +252,329 @@ Optional field referencing brainstorming outputs for task execution:
 **Types & Priority**: synthesis_specification (highest) → topic_framework (medium) → individual_role_analysis (low)
 
 #### Flow Control Configuration
-The **flow_control** field manages task execution with two main components:
+The **flow_control** field manages task execution through structured sequential steps. For complete format specifications and usage guidelines, see [Flow Control Format Guide](#flow-control-format-guide) below.
 
-**pre_analysis** - Context gathering phase:
-- **Flexible commands**: Supports multiple tool types (see Tool Reference below)
-- **Step structure**: Each step has `step`, `action`, `command` fields
-- **Variable accumulation**: Steps can reference previous outputs via `[variable_name]`
-- **Error handling**: `skip_optional`, `fail`, `retry_once`, `manual_intervention`
+**Quick Reference**:
+- **pre_analysis**: Context gathering steps (supports multiple command types)
+- **implementation_approach**: Implementation steps array with dependency management
+- **target_files**: Target files for modification (file:function:lines format)
+- **Variable references**: Use `[variable_name]` to reference step outputs
+- **Tool integration**: Supports Gemini, Codex, Bash commands, and MCP tools
 
-**implementation_approach** - Implementation definition:
-- **task_description**: Comprehensive implementation description
-- **modification_points**: Specific code modification targets
-- **logic_flow**: Business logic execution sequence
-- **target_files**: Target file list - existing files in `file:function:lines` format, new files as `file` only
+## Flow Control Format Guide
 
-#### Tool Reference
-**Command Types Available**:
-- **Gemini CLI**: `~/.claude/scripts/gemini-wrapper -p "prompt"`
-- **Codex CLI**: `codex --full-auto exec "task" -s danger-full-access`
-- **Built-in Tools**: `grep(pattern)`, `glob(pattern)`, `search(query)`
-- **Bash Commands**: `bash(rg 'pattern' src/)`, `bash(find . -name "*.ts")`
+The `[FLOW_CONTROL]` marker indicates that a task or prompt contains flow control steps for sequential execution. There are **two distinct formats** used in different scenarios:
 
-#### Variable System & Context Flow
-**Flow Control Variables**: Use `[variable_name]` format for dynamic content:
+### Format Comparison Matrix
+
+| Aspect | Inline Format | JSON Format |
+|--------|--------------|-------------|
+| **Used In** | Brainstorm workflows | Implementation tasks |
+| **Agent** | conceptual-planning-agent | code-developer, test-fix-agent, doc-generator |
+| **Location** | Task() prompt (markdown) | .task/IMPL-*.json file |
+| **Persistence** | Temporary (prompt-only) | Persistent (file storage) |
+| **Complexity** | Simple (3-5 steps) | Complex (10+ steps) |
+| **Dependencies** | None | Full `depends_on` support |
+| **Purpose** | Load brainstorming context | Implement task with preparation |
+
+### Inline Format (Brainstorm)
+
+**Marker**: `[FLOW_CONTROL]` written directly in Task() prompt
+
+**Structure**: Markdown list format
+
+**Used By**: Brainstorm commands (`auto-parallel.md`, role commands)
+
+**Agent**: `conceptual-planning-agent`
+
+**Example**:
+```markdown
+[FLOW_CONTROL]
+
+### Flow Control Steps
+**AGENT RESPONSIBILITY**: Execute these pre_analysis steps sequentially with context accumulation:
+
+1. **load_topic_framework**
+   - Action: Load structured topic discussion framework
+   - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
+   - Output: topic_framework
+
+2. **load_role_template**
+   - Action: Load role-specific planning template
+   - Command: bash($(cat "~/.claude/workflows/cli-templates/planning-roles/{role}.md"))
+   - Output: role_template
+
+3. **load_session_metadata**
+   - Action: Load session metadata and topic description
+   - Command: bash(cat .workflow/WFS-{session}/workflow-session.json 2>/dev/null || echo '{}')
+   - Output: session_metadata
+```
+
+**Characteristics**:
+- 3-5 simple context loading steps
+- Written directly in prompt (not persistent)
+- No dependency management between steps
+- Used for temporary context preparation
+- Variables: `[variable_name]` for output references
+
+### JSON Format (Implementation)
+
+**Marker**: `[FLOW_CONTROL]` used in TodoWrite or documentation to indicate task has flow control
+
+**Structure**: Complete JSON structure in task file
+
+**Used By**: Implementation tasks (IMPL-*.json)
+
+**Agents**: `code-developer`, `test-fix-agent`, `doc-generator`
+
+**Example**:
+```json
+"flow_control": {
+  "pre_analysis": [
+    {
+      "step": "load_synthesis_specification",
+      "action": "Load consolidated synthesis specification",
+      "commands": [
+        "bash(ls .workflow/WFS-{session}/.brainstorming/synthesis-specification.md 2>/dev/null || echo 'not found')",
+        "Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)"
+      ],
+      "output_to": "synthesis_specification",
+      "on_error": "skip_optional"
+    },
+    {
+      "step": "mcp_codebase_exploration",
+      "action": "Explore codebase using MCP",
+      "command": "mcp__code-index__find_files(pattern=\"*.ts\") && mcp__code-index__search_code_advanced(pattern=\"auth\")",
+      "output_to": "codebase_structure"
+    }
+  ],
+  "implementation_approach": [
+    {
+      "step": 1,
+      "title": "Setup infrastructure",
+      "description": "Install JWT library and create config following [synthesis_specification]",
+      "modification_points": [
+        "Add JWT library dependencies to package.json",
+        "Create auth configuration file"
+      ],
+      "logic_flow": [
+        "Install jsonwebtoken library via npm",
+        "Configure JWT secret from [synthesis_specification]",
+        "Export auth config for use by [jwt_generator]"
+      ],
+      "depends_on": [],
+      "output": "auth_config"
+    },
+    {
+      "step": 2,
+      "title": "Implement JWT generation",
+      "description": "Create JWT token generation logic using [auth_config]",
+      "modification_points": [
+        "Add JWT generation function in auth service",
+        "Implement token signing with [auth_config]"
+      ],
+      "logic_flow": [
+        "User login → validate credentials",
+        "Generate JWT payload with user data",
+        "Sign JWT using secret from [auth_config]",
+        "Return signed token"
+      ],
+      "depends_on": [1],
+      "output": "jwt_generator"
+    }
+  ],
+  "target_files": [
+    "src/auth/login.ts:handleLogin:75-120",
+    "src/middleware/auth.ts:validateToken"
+  ]
+}
+```
+
+**Characteristics**:
+- Persistent storage in .task/IMPL-*.json files
+- Complete dependency management (`depends_on` arrays)
+- Two-phase structure: `pre_analysis` + `implementation_approach`
+- Error handling strategies (`on_error` field)
+- Target file specifications
+- Variables: `[variable_name]` for cross-step references
+
+### JSON Format Field Specifications
+
+#### pre_analysis Field
+**Purpose**: Context gathering phase before implementation
+
+**Structure**: Array of step objects with sequential execution
+
+**Step Fields**:
+- **step**: Step identifier (string, e.g., "load_synthesis_specification")
+- **action**: Human-readable description of the step
+- **command** or **commands**: Single command string or array of command strings
+- **output_to**: Variable name for storing step output
+- **on_error**: Error handling strategy (`skip_optional`, `fail`, `retry_once`, `manual_intervention`)
+
+**Command Types Supported**:
+- **Bash commands**: `bash(command)` - Any shell command
+- **Tool calls**: `Read(file)`, `Glob(pattern)`, `Grep(pattern)`
+- **MCP tools**: `mcp__code-index__find_files()`, `mcp__exa__get_code_context_exa()`
+- **CLI wrappers**: `~/.claude/scripts/gemini-wrapper`, `codex --full-auto exec`
+
+**Example**:
+```json
+{
+  "step": "load_context",
+  "action": "Load project context and patterns",
+  "commands": [
+    "bash(~/.claude/scripts/get_modules_by_depth.sh)",
+    "Read(CLAUDE.md)"
+  ],
+  "output_to": "project_structure",
+  "on_error": "skip_optional"
+}
+```
+
+#### implementation_approach Field
+**Purpose**: Define implementation steps with dependency management
+
+**Structure**: Array of step objects (NOT object format)
+
+**Step Fields (All Required)**:
+- **step**: Unique step number (1, 2, 3, ...) - serves as step identifier
+- **title**: Brief step title
+- **description**: Comprehensive implementation description with context variable references
+- **modification_points**: Array of specific code modification targets
+- **logic_flow**: Array describing business logic execution sequence
+- **depends_on**: Array of step numbers this step depends on (e.g., `[1]`, `[1, 2]`) - empty array `[]` for independent steps
+- **output**: Output variable name that can be referenced by subsequent steps via `[output_name]`
+
+**Optional Fields**:
+- **command**: Command for step execution (supports any shell command or CLI tool)
+  - When omitted: Agent interprets modification_points and logic_flow to execute
+  - When specified: Command executes the step directly
+
+**Execution Modes**:
+- **Default (without command)**: Agent executes based on modification_points and logic_flow
+- **With command**: Specified command handles execution
+
+**Command Field Usage**:
+- **Default approach**: Omit command field - let agent execute autonomously
+- **CLI tools (codex/gemini/qwen)**: Add ONLY when user explicitly requests CLI tool usage
+- **Simple commands**: Can include bash commands, test commands, validation scripts
+- **Complex workflows**: Use command for multi-step operations or tool coordination
+
+**Command Format Examples** (only when explicitly needed):
+```json
+// Simple Bash
+"command": "bash(npm install package)"
+"command": "bash(npm test)"
+
+// Validation
+"command": "bash(test -f config.ts && grep -q 'JWT_SECRET' config.ts)"
+
+// Codex (user requested)
+"command": "codex -C path --full-auto exec \"task\" --skip-git-repo-check -s danger-full-access"
+
+// Codex Resume (user requested, maintains context)
+"command": "codex --full-auto exec \"task\" resume --last --skip-git-repo-check -s danger-full-access"
+
+// Gemini (user requested)
+"command": "~/.claude/scripts/gemini-wrapper -p \"analyze [context]\""
+
+// Qwen (fallback for Gemini)
+"command": "~/.claude/scripts/qwen-wrapper -p \"analyze [context]\""
+```
+
+**Example Step**:
+```json
+{
+  "step": 2,
+  "title": "Implement JWT generation",
+  "description": "Create JWT token generation logic using [auth_config]",
+  "modification_points": [
+    "Add JWT generation function in auth service",
+    "Implement token signing with [auth_config]"
+  ],
+  "logic_flow": [
+    "User login → validate credentials",
+    "Generate JWT payload with user data",
+    "Sign JWT using secret from [auth_config]",
+    "Return signed token"
+  ],
+  "depends_on": [1],
+  "output": "jwt_generator"
+}
+```
+
+#### target_files Field
+**Purpose**: Specify files to be modified or created
+
+**Format**: Array of strings
+- **Existing files**: `"file:function:lines"` (e.g., `"src/auth/login.ts:handleLogin:75-120"`)
+- **New files**: `"path/to/NewFile.ts"` (file path only)
+
+### Tool Reference
+
+**Available Command Types**:
+
+**Gemini CLI**:
+```bash
+~/.claude/scripts/gemini-wrapper -p "prompt"
+~/.claude/scripts/gemini-wrapper --approval-mode yolo -p "prompt"  # For write mode
+```
+
+**Qwen CLI** (Gemini fallback):
+```bash
+~/.claude/scripts/qwen-wrapper -p "prompt"
+~/.claude/scripts/qwen-wrapper --approval-mode yolo -p "prompt"  # For write mode
+```
+
+**Codex CLI**:
+```bash
+codex -C directory --full-auto exec "task" --skip-git-repo-check -s danger-full-access
+codex --full-auto exec "task" resume --last --skip-git-repo-check -s danger-full-access
+```
+
+**Built-in Tools**:
+- `Read(file_path)` - Read file contents
+- `Glob(pattern)` - Find files by pattern
+- `Grep(pattern)` - Search content with regex
+- `bash(command)` - Execute bash command
+
+**MCP Tools**:
+- `mcp__code-index__find_files(pattern="*.ts")` - Find files using code index
+- `mcp__code-index__search_code_advanced(pattern="auth")` - Search code patterns
+- `mcp__exa__get_code_context_exa(query="...")` - Get code context from Exa
+- `mcp__exa__web_search_exa(query="...")` - Web search via Exa
+
+**Bash Commands**:
+```bash
+bash(rg 'pattern' src/)
+bash(find . -name "*.ts")
+bash(npm test)
+bash(git log --oneline | head -5)
+```
+
+### Variable System & Context Flow
+
+**Variable Reference Syntax**:
+Both formats use `[variable_name]` syntax for referencing outputs from previous steps.
+
+**Variable Types**:
 - **Step outputs**: `[step_output_name]` - Reference any pre_analysis step output
 - **Task properties**: `[task_property]` - Reference any task context field
 - **Previous results**: `[analysis_result]` - Reference accumulated context
-- **Commands**: All commands wrapped with appropriate error handling
+- **Implementation outputs**: Reference outputs from previous implementation steps
+
+**Examples**:
+```json
+// Reference pre_analysis output
+"description": "Install JWT library following [synthesis_specification]"
+
+// Reference previous step output
+"description": "Create middleware using [auth_config] and [jwt_generator]"
+
+// Reference task context
+"command": "bash(cd [focus_paths] && npm test)"
+```
 
 **Context Accumulation Process**:
 1. **Structure Analysis**: `get_modules_by_depth.sh` → project hierarchy
@@ -248,16 +588,76 @@ The **flow_control** field manages task execution with two main components:
 - **Session → Task**: Global session context included in all tasks
 - **Module → Feature**: Module patterns inform feature implementation
 
+### Agent Processing Rules
+
+**conceptual-planning-agent** (Inline Format):
+- Parses markdown list from prompt
+- Executes 3-5 simple loading steps
+- No dependency resolution needed
+- Accumulates context in variables
+- Used only in brainstorm workflows
+
+**code-developer, test-fix-agent** (JSON Format):
+- Loads complete task JSON from file
+- Executes `pre_analysis` steps sequentially
+- Processes `implementation_approach` with dependency resolution
+- Handles complex variable substitution
+- Updates task status in JSON file
+
+### Usage Guidelines
+
+**Use Inline Format When**:
+- Running brainstorm workflows
+- Need 3-5 simple context loading steps
+- No persistence required
+- No dependencies between steps
+- Temporary context preparation
+
+**Use JSON Format When**:
+- Implementing features or tasks
+- Need 10+ complex execution steps
+- Require dependency management
+- Need persistent task definitions
+- Complex variable flow between steps
+- Error handling strategies needed
+
+### Variable Reference Syntax
+
+Both formats use `[variable_name]` syntax for referencing outputs:
+
+**Inline Format**:
+```markdown
+2. **analyze_context**
+   - Action: Analyze using [topic_framework] and [role_template]
+   - Output: analysis_results
+```
+
+**JSON Format**:
+```json
+{
+  "step": 2,
+  "description": "Implement following [synthesis_specification] and [codebase_structure]",
+  "depends_on": [1],
+  "output": "implementation"
+}
+```
+
 ### Task Validation Rules
 1. **ID Uniqueness**: All task IDs must be unique
 2. **Hierarchical Format**: Must follow IMPL-N[.M] pattern (maximum 2 levels)
 3. **Parent References**: All parent IDs must exist as JSON files
 4. **Status Consistency**: Status values from defined enumeration
-5. **Required Fields**: All 5 core fields must be present
+5. **Required Fields**: All 5 core fields must be present (id, title, status, meta, context, flow_control)
 6. **Focus Paths Structure**: context.focus_paths must contain concrete paths (no wildcards)
 7. **Flow Control Format**: pre_analysis must be array with required fields
-8. **Dependency Integrity**: All depends_on task IDs must exist as JSON files
+8. **Dependency Integrity**: All task-level depends_on references must exist as JSON files
 9. **Artifacts Structure**: context.artifacts (optional) must use valid type, priority, and path format
+10. **Implementation Steps Array**: implementation_approach must be array of step objects
+11. **Step Number Uniqueness**: All step numbers within a task must be unique and sequential (1, 2, 3, ...)
+12. **Step Dependencies**: All step-level depends_on numbers must reference valid steps within same task
+13. **Step Sequence**: Step numbers should match array order (first item step=1, second item step=2, etc.)
+14. **Step Required Fields**: Each step must have step, title, description, modification_points, logic_flow, depends_on, output
+15. **Step Optional Fields**: command field is optional - when omitted, agent executes based on modification_points and logic_flow
 
 ## Workflow Structure
 

CHANGELOG.md

@@ -5,6 +5,182 @@ All notable changes to Claude Code Workflow (CCW) will be documented in this fil
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.4.1] - 2025-10-12
+
+### 🔧 Implementation Approach Structure Refactoring
+
+This release refactors the task generation system from a simple object-based implementation approach to a structured step-based approach with dependency management and CLI execution support.
+
+#### Changed
+
+**Implementation Approach Structure** (Major Refactoring):
+- **Array Format**: Changed from single object to array of step objects
+  - Before (v4.4.0): Single `implementation_approach` object with description
+  - After (v4.4.1): Array of steps with sequential execution and dependencies
+- **Step Structure**: Each step now includes:
+  - `step`: Step number (1, 2, 3...)
+  - `title`: Step title
+  - `description`: Detailed description with variable references
+  - `modification_points`: Specific modification targets
+  - `logic_flow`: Business logic sequence
+  - `command`: Optional CLI command for execution
+  - `depends_on`: Array of step numbers (dependencies)
+  - `output`: Variable name for step output (used in `[variable_name]` references)
+- **Benefits**:
+  - ✅ Multi-step workflows with clear dependencies
+  - ✅ Variable substitution between steps (`[variable_name]`)
+  - ✅ Better task decomposition clarity
+  - ✅ Sequential execution with dependency resolution
+
+**CLI Execution Mode Support**:
+- **New `--cli-execute` Flag**: Added to workflow commands
+  - `/workflow:plan --cli-execute` - Generate tasks with CLI execution
+  - `/workflow:test-gen --cli-execute` - Generate test tasks with CLI execution
+  - `/workflow:tools:task-generate --cli-execute` - Manual task generation with CLI
+  - `/workflow:tools:task-generate-agent --cli-execute` - Agent task generation with CLI
+  - `/workflow:tools:test-task-generate --cli-execute` - Test task generation with CLI
+- **Codex Resume Mechanism**: Maintains session context across steps
+  - First step: `codex exec "..."` (starts new session)
+  - Subsequent steps: `codex exec "..." resume --last` (continues session)
+  - Benefits: Context continuity, consistent implementation style
+
+**Agent Updates**:
+- **action-planning-agent.md**: Updated task generation with step-based approach
+- **code-developer.md**: Added implementation approach execution logic
+- **conceptual-planning-agent.md**: Added flow control format handling documentation
+- **doc-generator.md**: Updated to process step-based implementation approach
+- **test-fix-agent.md**: Added flow control execution and Codex mode support
+
+**Workflow Command Updates**:
+- **execute.md**: Updated task JSON examples with new structure
+- **plan.md**: Added `--cli-execute` flag and command examples
+- **test-gen.md**: Added `--cli-execute` flag support
+- **docs.md**: Refactored from 1328 to 435 lines (67% reduction)
+- **task-generate-agent.md**: Updated to generate step-based tasks
+- **task-generate-tdd.md**: Enhanced with array format and CLI execution
+- **task-generate.md**: Added CLI execution mode documentation
+- **test-task-generate.md**: Added CLI execution mode support
+
+**Core Architecture Updates**:
+- **task-core.md**: Updated implementation approach structure
+- **workflow-architecture.md**: Enhanced with flow control documentation (474 lines added)
+
+#### Technical Details
+
+**Step Execution Flow**:
+```javascript
+// Old approach (v4.4.0)
+"implementation_approach": {
+  "task_description": "Implement feature X",
+  "modification_points": ["File A", "File B"],
+  "logic_flow": ["Step 1", "Step 2"]
+}
+
+// New approach (v4.4.1)
+"implementation_approach": [
+  {
+    "step": 1,
+    "title": "Load requirements",
+    "description": "Load and analyze [previous_output]",
+    "modification_points": ["Parse requirements"],
+    "logic_flow": ["Read input", "Extract data"],
+    "depends_on": [],
+    "output": "requirements"
+  },
+  {
+    "step": 2,
+    "title": "Implement feature",
+    "description": "Implement using [requirements]",
+    "modification_points": ["File A", "File B"],
+    "logic_flow": ["Apply changes", "Validate"],
+    "command": "codex exec '...' resume --last",
+    "depends_on": [1],
+    "output": "implementation"
+  }
+]
+```
+
+**CLI Command Examples**:
+```bash
+# Manual task generation with CLI execution
+/workflow:tools:task-generate --session WFS-auth --cli-execute
+
+# Agent task generation with CLI execution
+/workflow:tools:task-generate-agent --session WFS-auth --cli-execute
+
+# Test task generation with CLI execution
+/workflow:tools:test-task-generate --session WFS-test --cli-execute
+
+# Full planning workflow with CLI execution
+/workflow:plan "Implement auth system" --cli-execute
+```
+
+#### Files Changed
+
+**Agents** (5 files):
+- `.claude/agents/action-planning-agent.md`
+- `.claude/agents/code-developer.md`
+- `.claude/agents/conceptual-planning-agent.md`
+- `.claude/agents/doc-generator.md`
+- `.claude/agents/test-fix-agent.md`
+
+**Commands** (7 files):
+- `.claude/commands/workflow/execute.md`
+- `.claude/commands/workflow/plan.md`
+- `.claude/commands/workflow/test-gen.md`
+- `.claude/commands/workflow/tools/docs.md` (major refactoring: 1328→435 lines)
+- `.claude/commands/workflow/tools/task-generate-agent.md`
+- `.claude/commands/workflow/tools/task-generate-tdd.md`
+- `.claude/commands/workflow/tools/task-generate.md`
+- `.claude/commands/workflow/tools/test-task-generate.md`
+
+**Core Architecture** (2 files):
+- `.claude/workflows/task-core.md`
+- `.claude/workflows/workflow-architecture.md` (+474 lines of flow control documentation)
+
+**Total Impact**:
+- 15 files changed
+- +1341 lines, -782 lines
+- Net: +559 lines
+- Major improvements in task generation clarity and CLI execution support
+
+#### Migration Guide
+
+**For Existing Workflows**:
+1. **Backward Compatible**: Old object-based approach still supported
+2. **Gradual Migration**: Can mix old and new formats in same workflow
+3. **Automatic Handling**: Agents detect and handle both formats
+
+**For New Workflows**:
+1. **Use Step-Based Approach**: Better for multi-step tasks
+2. **Enable CLI Execution**: Use `--cli-execute` flag for automated execution
+3. **Leverage Resume**: Use Codex resume for context continuity
+
+**Example Migration**:
+```bash
+# Old workflow (v4.4.0)
+/workflow:plan "Implement auth system"
+
+# New workflow (v4.4.1) - with CLI execution
+/workflow:plan "Implement auth system" --cli-execute
+```
+
+#### Benefits
+
+**Task Generation**:
+- 🎯 **Clearer Structure**: Step-based approach improves task clarity
+- 🔄 **Better Dependencies**: Explicit dependency management between steps
+- 📊 **Variable References**: Cross-step data flow with `[variable_name]`
+- 🤖 **Automated Execution**: CLI execution mode reduces manual intervention
+
+**Development Workflow**:
+- ⚡ **Faster Execution**: Codex resume maintains context
+- 🔍 **Better Traceability**: Each step's output explicitly tracked
+- 🧪 **Easier Testing**: Isolated steps can be tested independently
+- 📚 **Improved Documentation**: Flow control structure self-documenting
+
+---
+
 ## [4.4.0] - 2025-10-11
 
 ### 🏗️ UI Design Workflow V3 - Layout/Style Separation Architecture
@@ -1898,12 +2074,6 @@ This is a **breaking change release** with significant architectural improvement
 - **Intelligent Modes**: Auto template selection and precise planning
 - **Full Command Suite**: analyze, chat, execute, mode:auto, mode:bug-index, mode:plan
 
-#### 🏷️ Issue Management Commands
-- `/workflow:issue:create` - Create new project issues with priority/type
-- `/workflow:issue:list` - List and filter issues by status/assignment
-- `/workflow:issue:update` - Update existing issue status and assignments
-- `/workflow:issue:close` - Close completed issues with resolution
-
 #### 📋 Enhanced Workflow Commands
 - `/workflow:plan-verify` - Pre-execution validation using dual analysis
 - `/workflow:test-gen` - Generate comprehensive test workflows

CLAUDE.md

@@ -5,6 +5,7 @@
 This document defines project-specific coding standards and development principles.
 ### CLI Tool Context Protocols
 For all CLI tool usage, command syntax, and integration guidelines:
+- **Tool Control Configuration**: @~/.claude/workflows/tool-control.yaml - Controls CLI tool availability for all commands and agent executions (if disabled, use other enabled CLI tools or Claude's own capabilities)
 - **Intelligent Context Strategy**: @~/.claude/workflows/intelligent-tools-strategy.md
 - **Context Search Commands**: @~/.claude/workflows/context-search-strategy.md
 - **MCP Tool Strategy**: @~/.claude/workflows/mcp-tool-strategy.md

Install-Claude.ps1

@@ -570,6 +570,66 @@ function Copy-FileToDestination {
     }
 }
 
+function Backup-AndReplaceDirectory {
+    param(
+        [string]$Source,
+        [string]$Destination,
+        [string]$Description = "directory",
+        [string]$BackupFolder = $null
+    )
+
+    if (-not (Test-Path $Source)) {
+        Write-ColorOutput "WARNING: Source $Description not found: $Source" $ColorWarning
+        return $false
+    }
+
+    # Backup destination if it exists
+    if (Test-Path $Destination) {
+        Write-ColorOutput "Found existing $Description at: $Destination" $ColorInfo
+
+        # Backup entire directory if backup is enabled
+        if (-not $NoBackup -and $BackupFolder) {
+            Write-ColorOutput "Backing up entire $Description..." $ColorInfo
+            if (Backup-DirectoryToFolder -DirectoryPath $Destination -BackupFolder $BackupFolder) {
+                Write-ColorOutput "Backed up $Description to: $BackupFolder" $ColorSuccess
+            }
+        } elseif ($NoBackup) {
+            if (-not (Confirm-Action "Replace existing $Description without backup?" -DefaultYes:$false)) {
+                Write-ColorOutput "Skipping $Description installation" $ColorWarning
+                return $false
+            }
+        }
+
+        # Get all items from source to determine what to clear in destination
+        Write-ColorOutput "Clearing conflicting items in destination $Description..." $ColorInfo
+        $sourceItems = Get-ChildItem -Path $Source -Force
+
+        foreach ($sourceItem in $sourceItems) {
+            $destItemPath = Join-Path $Destination $sourceItem.Name
+            if (Test-Path $destItemPath) {
+                Write-ColorOutput "Removing existing: $($sourceItem.Name)" $ColorInfo
+                Remove-Item -Path $destItemPath -Recurse -Force -ErrorAction SilentlyContinue
+            }
+        }
+        Write-ColorOutput "Cleared conflicting items in destination" $ColorSuccess
+    } else {
+        # Create destination directory if it doesn't exist
+        New-Item -ItemType Directory -Path $Destination -Force | Out-Null
+        Write-ColorOutput "Created destination directory: $Destination" $ColorInfo
+    }
+
+    # Copy all items from source to destination
+    Write-ColorOutput "Copying $Description from $Source to $Destination..." $ColorInfo
+    $sourceItems = Get-ChildItem -Path $Source -Force
+    foreach ($item in $sourceItems) {
+        $destPath = Join-Path $Destination $item.Name
+        Copy-Item -Path $item.FullName -Destination $destPath -Recurse -Force
+    }
+    Write-ColorOutput "$Description installed successfully" $ColorSuccess
+
+    return $true
+}
+
 function Merge-DirectoryContents {
     param(
         [string]$Source,
@@ -577,34 +637,34 @@ function Merge-DirectoryContents {
         [string]$Description = "directory contents",
         [string]$BackupFolder = $null
     )
-    
+
     if (-not (Test-Path $Source)) {
         Write-ColorOutput "WARNING: Source $Description not found: $Source" $ColorWarning
         return $false
     }
-    
+
     # Create destination directory if it doesn't exist
     if (-not (Test-Path $Destination)) {
         New-Item -ItemType Directory -Path $Destination -Force | Out-Null
         Write-ColorOutput "Created destination directory: $Destination" $ColorInfo
     }
-    
+
     # Get all items in source directory
     $sourceItems = Get-ChildItem -Path $Source -Recurse -File
     $mergedCount = 0
     $skippedCount = 0
-    
+
     foreach ($item in $sourceItems) {
         # Calculate relative path from source
         $relativePath = $item.FullName.Substring($Source.Length + 1)
         $destinationPath = Join-Path $Destination $relativePath
-        
+
         # Ensure destination directory exists
         $destinationDir = Split-Path $destinationPath -Parent
         if (-not (Test-Path $destinationDir)) {
             New-Item -ItemType Directory -Path $destinationDir -Force | Out-Null
         }
-        
+
         # Handle file merging
         if (Test-Path $destinationPath) {
             $fileName = Split-Path $relativePath -Leaf
@@ -639,7 +699,7 @@ function Merge-DirectoryContents {
             $mergedCount++
         }
     }
-    
+
     Write-ColorOutput "Merged $mergedCount files, skipped $skippedCount files" $ColorSuccess
     return $true
 }
@@ -727,25 +787,25 @@ function Install-Global {
         }
     }
 
-    # Merge .claude directory contents (don't replace entire directory)
-    Write-ColorOutput "Merging .claude directory contents..." $ColorInfo
-    $claudeMerged = Merge-DirectoryContents -Source $sourceClaudeDir -Destination $globalClaudeDir -Description ".claude directory contents" -BackupFolder $backupFolder
+    # Replace .claude directory (backup → clear → copy entire folder)
+    Write-ColorOutput "Installing .claude directory..." $ColorInfo
+    $claudeInstalled = Backup-AndReplaceDirectory -Source $sourceClaudeDir -Destination $globalClaudeDir -Description ".claude directory" -BackupFolder $backupFolder
 
     # Handle CLAUDE.md file in .claude directory
     Write-ColorOutput "Installing CLAUDE.md to global .claude directory..." $ColorInfo
     $claudeMdInstalled = Copy-FileToDestination -Source $sourceClaudeMd -Destination $globalClaudeMd -Description "CLAUDE.md" -BackupFolder $backupFolder
 
-    # Merge .codex directory contents
-    Write-ColorOutput "Merging .codex directory contents..." $ColorInfo
-    $codexMerged = Merge-DirectoryContents -Source $sourceCodexDir -Destination $globalCodexDir -Description ".codex directory contents" -BackupFolder $backupFolder
+    # Replace .codex directory (backup → clear → copy entire folder)
+    Write-ColorOutput "Installing .codex directory..." $ColorInfo
+    $codexInstalled = Backup-AndReplaceDirectory -Source $sourceCodexDir -Destination $globalCodexDir -Description ".codex directory" -BackupFolder $backupFolder
 
-    # Merge .gemini directory contents
-    Write-ColorOutput "Merging .gemini directory contents..." $ColorInfo
-    $geminiMerged = Merge-DirectoryContents -Source $sourceGeminiDir -Destination $globalGeminiDir -Description ".gemini directory contents" -BackupFolder $backupFolder
+    # Replace .gemini directory (backup → clear → copy entire folder)
+    Write-ColorOutput "Installing .gemini directory..." $ColorInfo
+    $geminiInstalled = Backup-AndReplaceDirectory -Source $sourceGeminiDir -Destination $globalGeminiDir -Description ".gemini directory" -BackupFolder $backupFolder
 
-    # Merge .qwen directory contents
-    Write-ColorOutput "Merging .qwen directory contents..." $ColorInfo
-    $qwenMerged = Merge-DirectoryContents -Source $sourceQwenDir -Destination $globalQwenDir -Description ".qwen directory contents" -BackupFolder $backupFolder
+    # Replace .qwen directory (backup → clear → copy entire folder)
+    Write-ColorOutput "Installing .qwen directory..." $ColorInfo
+    $qwenInstalled = Backup-AndReplaceDirectory -Source $sourceQwenDir -Destination $globalQwenDir -Description ".qwen directory" -BackupFolder $backupFolder
 
     # Create version.json in global .claude directory
     Write-ColorOutput "Creating version.json..." $ColorInfo
@@ -815,13 +875,9 @@ function Install-Path {
         $destFolderPath = Join-Path $localClaudeDir $folder
 
         if (Test-Path $sourceFolderPath) {
-            if (Test-Path $destFolderPath) {
-                if ($backupFolder) {
-                    Backup-DirectoryToFolder -DirectoryPath $destFolderPath -BackupFolder $backupFolder
-                }
-            }
-
-            Copy-DirectoryRecursive -Source $sourceFolderPath -Destination $destFolderPath
+            # Use new backup and replace logic for local folders
+            Write-ColorOutput "Installing local folder: $folder..." $ColorInfo
+            Backup-AndReplaceDirectory -Source $sourceFolderPath -Destination $destFolderPath -Description "$folder folder" -BackupFolder $backupFolder
             Write-ColorOutput "Installed local folder: $folder" $ColorSuccess
         } else {
             Write-ColorOutput "WARNING: Source folder not found: $folder" $ColorWarning
@@ -882,17 +938,17 @@ function Install-Path {
     Write-ColorOutput "Installing CLAUDE.md to global .claude directory..." $ColorInfo
     Copy-FileToDestination -Source $sourceClaudeMd -Destination $globalClaudeMd -Description "CLAUDE.md" -BackupFolder $backupFolder
 
-    # Merge .codex directory contents to local location
-    Write-ColorOutput "Merging .codex directory contents to local location..." $ColorInfo
-    $codexMerged = Merge-DirectoryContents -Source $sourceCodexDir -Destination $localCodexDir -Description ".codex directory contents" -BackupFolder $backupFolder
+    # Replace .codex directory to local location (backup → clear → copy entire folder)
+    Write-ColorOutput "Installing .codex directory to local location..." $ColorInfo
+    $codexInstalled = Backup-AndReplaceDirectory -Source $sourceCodexDir -Destination $localCodexDir -Description ".codex directory" -BackupFolder $backupFolder
 
-    # Merge .gemini directory contents to local location
-    Write-ColorOutput "Merging .gemini directory contents to local location..." $ColorInfo
-    $geminiMerged = Merge-DirectoryContents -Source $sourceGeminiDir -Destination $localGeminiDir -Description ".gemini directory contents" -BackupFolder $backupFolder
+    # Replace .gemini directory to local location (backup → clear → copy entire folder)
+    Write-ColorOutput "Installing .gemini directory to local location..." $ColorInfo
+    $geminiInstalled = Backup-AndReplaceDirectory -Source $sourceGeminiDir -Destination $localGeminiDir -Description ".gemini directory" -BackupFolder $backupFolder
 
-    # Merge .qwen directory contents to local location
-    Write-ColorOutput "Merging .qwen directory contents to local location..." $ColorInfo
-    $qwenMerged = Merge-DirectoryContents -Source $sourceQwenDir -Destination $localQwenDir -Description ".qwen directory contents" -BackupFolder $backupFolder
+    # Replace .qwen directory to local location (backup → clear → copy entire folder)
+    Write-ColorOutput "Installing .qwen directory to local location..." $ColorInfo
+    $qwenInstalled = Backup-AndReplaceDirectory -Source $sourceQwenDir -Destination $localQwenDir -Description ".qwen directory" -BackupFolder $backupFolder
 
     # Create version.json in local .claude directory
     Write-ColorOutput "Creating version.json in local directory..." $ColorInfo

Install-Claude.sh

@@ -340,6 +340,64 @@ function copy_file_to_destination() {
     fi
 }
 
+function backup_and_replace_directory() {
+    local source="$1"
+    local destination="$2"
+    local description="${3:-directory}"
+    local backup_folder="${4:-}"
+
+    if [ ! -d "$source" ]; then
+        write_color "WARNING: Source $description not found: $source" "$COLOR_WARNING"
+        return 1
+    fi
+
+    # Backup destination if it exists
+    if [ -d "$destination" ]; then
+        write_color "Found existing $description at: $destination" "$COLOR_INFO"
+
+        # Backup entire directory if backup is enabled
+        if [ "$NO_BACKUP" = false ] && [ -n "$backup_folder" ]; then
+            write_color "Backing up entire $description..." "$COLOR_INFO"
+            if backup_directory_to_folder "$destination" "$backup_folder"; then
+                write_color "Backed up $description to: $backup_folder" "$COLOR_SUCCESS"
+            fi
+        elif [ "$NO_BACKUP" = true ]; then
+            if ! confirm_action "Replace existing $description without backup?" false; then
+                write_color "Skipping $description installation" "$COLOR_WARNING"
+                return 1
+            fi
+        fi
+
+        # Get all items from source to determine what to clear in destination
+        write_color "Clearing conflicting items in destination $description..." "$COLOR_INFO"
+        while IFS= read -r -d '' source_item; do
+            local item_name=$(basename "$source_item")
+            local dest_item_path="${destination}/${item_name}"
+
+            if [ -e "$dest_item_path" ]; then
+                write_color "Removing existing: $item_name" "$COLOR_INFO"
+                rm -rf "$dest_item_path"
+            fi
+        done < <(find "$source" -mindepth 1 -maxdepth 1 -print0)
+        write_color "Cleared conflicting items in destination" "$COLOR_SUCCESS"
+    else
+        # Create destination directory if it doesn't exist
+        mkdir -p "$destination"
+        write_color "Created destination directory: $destination" "$COLOR_INFO"
+    fi
+
+    # Copy all items from source to destination
+    write_color "Copying $description from $source to $destination..." "$COLOR_INFO"
+    while IFS= read -r -d '' item; do
+        local item_name=$(basename "$item")
+        local dest_path="${destination}/${item_name}"
+        cp -r "$item" "$dest_path"
+    done < <(find "$source" -mindepth 1 -maxdepth 1 -print0)
+    write_color "$description installed successfully" "$COLOR_SUCCESS"
+
+    return 0
+}
+
 function merge_directory_contents() {
     local source="$1"
     local destination="$2"
@@ -447,25 +505,25 @@ function install_global() {
         fi
     fi
 
-    # Merge .claude directory contents
-    write_color "Merging .claude directory contents..." "$COLOR_INFO"
-    merge_directory_contents "$source_claude_dir" "$global_claude_dir" ".claude directory contents" "$backup_folder"
+    # Replace .claude directory (backup → clear conflicting → copy)
+    write_color "Installing .claude directory..." "$COLOR_INFO"
+    backup_and_replace_directory "$source_claude_dir" "$global_claude_dir" ".claude directory" "$backup_folder"
 
     # Handle CLAUDE.md file
     write_color "Installing CLAUDE.md to global .claude directory..." "$COLOR_INFO"
     copy_file_to_destination "$source_claude_md" "$global_claude_md" "CLAUDE.md" "$backup_folder"
 
-    # Merge .codex directory contents
-    write_color "Merging .codex directory contents..." "$COLOR_INFO"
-    merge_directory_contents "$source_codex_dir" "$global_codex_dir" ".codex directory contents" "$backup_folder"
+    # Replace .codex directory (backup → clear conflicting → copy)
+    write_color "Installing .codex directory..." "$COLOR_INFO"
+    backup_and_replace_directory "$source_codex_dir" "$global_codex_dir" ".codex directory" "$backup_folder"
 
-    # Merge .gemini directory contents
-    write_color "Merging .gemini directory contents..." "$COLOR_INFO"
-    merge_directory_contents "$source_gemini_dir" "$global_gemini_dir" ".gemini directory contents" "$backup_folder"
+    # Replace .gemini directory (backup → clear conflicting → copy)
+    write_color "Installing .gemini directory..." "$COLOR_INFO"
+    backup_and_replace_directory "$source_gemini_dir" "$global_gemini_dir" ".gemini directory" "$backup_folder"
 
-    # Merge .qwen directory contents
-    write_color "Merging .qwen directory contents..." "$COLOR_INFO"
-    merge_directory_contents "$source_qwen_dir" "$global_qwen_dir" ".qwen directory contents" "$backup_folder"
+    # Replace .qwen directory (backup → clear conflicting → copy)
+    write_color "Installing .qwen directory..." "$COLOR_INFO"
+    backup_and_replace_directory "$source_qwen_dir" "$global_qwen_dir" ".qwen directory" "$backup_folder"
 
     # Remove empty backup folder
     if [ -n "$backup_folder" ] && [ -d "$backup_folder" ]; then
@@ -528,11 +586,9 @@ function install_path() {
         local dest_folder="${local_claude_dir}/${folder}"
 
         if [ -d "$source_folder" ]; then
-            if [ -d "$dest_folder" ] && [ -n "$backup_folder" ]; then
-                backup_directory_to_folder "$dest_folder" "$backup_folder"
-            fi
-
-            copy_directory_recursive "$source_folder" "$dest_folder"
+            # Use new backup and replace logic for local folders
+            write_color "Installing local folder: $folder..." "$COLOR_INFO"
+            backup_and_replace_directory "$source_folder" "$dest_folder" "$folder folder" "$backup_folder"
             write_color "✓ Installed local folder: $folder" "$COLOR_SUCCESS"
         else
             write_color "WARNING: Source folder not found: $folder" "$COLOR_WARNING"
@@ -590,17 +646,17 @@ function install_path() {
     write_color "Installing CLAUDE.md to global .claude directory..." "$COLOR_INFO"
     copy_file_to_destination "$source_claude_md" "$global_claude_md" "CLAUDE.md" "$backup_folder"
 
-    # Merge .codex directory contents to local location
-    write_color "Merging .codex directory contents to local location..." "$COLOR_INFO"
-    merge_directory_contents "$source_codex_dir" "$local_codex_dir" ".codex directory contents" "$backup_folder"
+    # Replace .codex directory to local location (backup → clear conflicting → copy)
+    write_color "Installing .codex directory to local location..." "$COLOR_INFO"
+    backup_and_replace_directory "$source_codex_dir" "$local_codex_dir" ".codex directory" "$backup_folder"
 
-    # Merge .gemini directory contents to local location
-    write_color "Merging .gemini directory contents to local location..." "$COLOR_INFO"
-    merge_directory_contents "$source_gemini_dir" "$local_gemini_dir" ".gemini directory contents" "$backup_folder"
+    # Replace .gemini directory to local location (backup → clear conflicting → copy)
+    write_color "Installing .gemini directory to local location..." "$COLOR_INFO"
+    backup_and_replace_directory "$source_gemini_dir" "$local_gemini_dir" ".gemini directory" "$backup_folder"
 
-    # Merge .qwen directory contents to local location
-    write_color "Merging .qwen directory contents to local location..." "$COLOR_INFO"
-    merge_directory_contents "$source_qwen_dir" "$local_qwen_dir" ".qwen directory contents" "$backup_folder"
+    # Replace .qwen directory to local location (backup → clear conflicting → copy)
+    write_color "Installing .qwen directory to local location..." "$COLOR_INFO"
+    backup_and_replace_directory "$source_qwen_dir" "$local_qwen_dir" ".qwen directory" "$backup_folder"
 
     # Remove empty backup folder
     if [ -n "$backup_folder" ] && [ -d "$backup_folder" ]; then

README.md

@@ -144,17 +144,43 @@ After installation, run the following command to ensure CCW is working:
 
 ## ⚙️ Configuration
 
-### **Prerequisites: Required Tools**
+### **Tool Control System**
 
-Before using CCW, install the following command-line tools:
+CCW uses a **configuration-based tool control system** that makes external CLI tools **optional** rather than required. This allows you to:
 
-#### **Core CLI Tools**
+- ✅ **Start with Claude-only mode** - Work immediately without installing additional tools
+- ✅ **Progressive enhancement** - Add external tools selectively as needed
+- ✅ **Graceful degradation** - Automatic fallback when tools are unavailable
+- ✅ **Flexible configuration** - Control tool availability per project
 
-| Tool | Purpose | Installation |
-|------|---------|--------------|
-| **Gemini CLI** | AI analysis & documentation | `npm install -g @google/gemini-cli` ([GitHub](https://github.com/google-gemini/gemini-cli)) |
-| **Codex CLI** | AI development & implementation | `npm install -g @openai/codex` ([GitHub](https://github.com/openai/codex)) |
-| **Qwen Code** | AI architecture & code generation | `npm install -g @qwen-code/qwen-code` ([Docs](https://github.com/QwenLM/qwen-code)) |
+**Configuration File**: `~/.claude/workflows/tool-control.yaml`
+
+```yaml
+tools:
+  gemini:
+    enabled: false  # Optional: AI analysis & documentation
+  qwen:
+    enabled: true   # Optional: AI architecture & code generation
+  codex:
+    enabled: true   # Optional: AI development & implementation
+```
+
+**Behavior**:
+- **When disabled**: CCW automatically falls back to other enabled tools or Claude's native capabilities
+- **When enabled**: Uses specialized tools for their specific strengths
+- **Default**: All tools disabled - Claude-only mode works out of the box
+
+### **Optional CLI Tools** *(Enhanced Capabilities)*
+
+While CCW works with Claude alone, installing these tools provides enhanced analysis and extended context:
+
+#### **External CLI Tools**
+
+| Tool | Purpose | Installation | Benefits |
+|------|---------|--------------|----------|
+| **Gemini CLI** | AI analysis & documentation | `npm install -g @google/gemini-cli` ([GitHub](https://github.com/google-gemini/gemini-cli)) | Free quota, extended context for complex projects |
+| **Codex CLI** | AI development & implementation | `npm install -g @openai/codex` ([GitHub](https://github.com/openai/codex)) | Autonomous development, mathematical reasoning |
+| **Qwen Code** | AI architecture & code generation | `npm install -g @qwen-code/qwen-code` ([Docs](https://github.com/QwenLM/qwen-code)) | Large context window, architecture analysis |
 
 #### **System Utilities**
 
@@ -248,29 +274,65 @@ MCP (Model Context Protocol) tools provide advanced codebase analysis. **Recomme
 /workflow:brainstorm:synthesis  # Generate consolidated specification
 ```
 
-**Phase 2: UI Design Refinement** *(Optional for UI-heavy projects)*
+**Phase 1.5: Concept Verification** *(Optional Quality Gate)*
 ```bash
-# Matrix Exploration Mode - Multiple style/layout variants (v4.2.1+)
+# Identify and resolve ambiguities in brainstorming artifacts
+/workflow:concept-clarify
+
+# OR specify session explicitly
+/workflow:concept-clarify --session WFS-auth
+```
+- Runs after `/workflow:brainstorm:synthesis` and before `/workflow:plan`
+- Interactive Q&A to clarify underspecified requirements, architecture decisions, or risks
+- Maximum 5 questions per session with multiple-choice or short-answer format
+- Updates `synthesis-specification.md` with clarifications incrementally
+- Ensures conceptual foundation is clear before detailed planning
+- Generates coverage summary with recommendations to proceed or address outstanding items
+
+**Phase 2: UI Design Refinement** *(Optional for UI-heavy projects)*
+
+**🎯 Choose Your Workflow:**
+
+**Scenario 1: Starting from an idea or concept** → Use `explore-auto`
+```bash
+# Generate multiple style and layout options to explore different directions
 /workflow:ui-design:explore-auto --prompt "Modern blog: home, article, author" --style-variants 3 --layout-variants 2
+# Creates a 3×2 matrix: 3 visual styles × 2 layouts = 6 prototypes to choose from
+```
 
-# Fast Imitation Mode - Single design replication (v4.2.1+)
+**Scenario 2: Replicating an existing design** → Use `imitate-auto`
+```bash
+# Fast, high-fidelity replication of reference designs
 /workflow:ui-design:imitate-auto --images "refs/design.png" --pages "dashboard,settings"
+# Or auto-screenshot from URL (requires Playwright/Chrome DevTools MCP)
+/workflow:ui-design:imitate-auto --url "https://linear.app" --pages "home,features"
+```
 
-# With session integration
-/workflow:ui-design:explore-auto --session WFS-auth --images "refs/*.png" --style-variants 2 --layout-variants 3
+**Scenario 3: Batch creation from existing design system** → Use `batch-generate`
+```bash
+# Already have a design system? Generate multiple pages quickly
+/workflow:ui-design:batch-generate --prompt "Create profile and settings pages" --layout-variants 2
+```
 
-# Or run individual design phases (v4.4.0+)
+**Advanced: Manual Step-by-Step Control** (v4.4.0+)
+```bash
+# 1. Extract visual style (colors, typography, spacing)
 /workflow:ui-design:style-extract --images "refs/*.png" --mode explore --variants 3
+
+# 2. Consolidate into production-ready design tokens
 /workflow:ui-design:consolidate --variants "variant-1,variant-3"
+
+# 3. Extract layout structure (DOM, CSS layout rules)
 /workflow:ui-design:layout-extract --targets "dashboard,auth" --mode explore --variants 2 --device-type responsive
+
+# 4. Combine style + layout → HTML/CSS prototypes
 /workflow:ui-design:generate --style-variants 1 --layout-variants 2
 
-# Preview generated prototypes
-# Option 1: Open .workflow/WFS-auth/.design/prototypes/compare.html in browser
-# Option 2: Start local server
+# 5. Preview and select
 cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
-# Visit http://localhost:8080 for interactive preview with comparison tools
+# Visit http://localhost:8080/compare.html for side-by-side comparison
 
+# 6. Integrate selected design into project
 /workflow:ui-design:update --session WFS-auth --selected-prototypes "dashboard-s1-l2"
 ```
 
@@ -283,6 +345,22 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
 /workflow:tdd-plan "Implement authentication with test-first development"
 ```
 
+**Phase 3.5: Action Plan Verification** *(Optional Pre-Execution Check)*
+```bash
+# Validate plan consistency and completeness
+/workflow:action-plan-verify
+
+# OR specify session explicitly
+/workflow:action-plan-verify --session WFS-auth
+```
+- Runs after `/workflow:plan` or `/workflow:tdd-plan` and before `/workflow:execute`
+- Read-only analysis of `IMPL_PLAN.md` and task JSON files against `synthesis-specification.md`
+- Validates requirements coverage, dependency integrity, and synthesis alignment
+- Identifies inconsistencies, duplications, ambiguities, and underspecified items
+- Generates detailed verification report with severity-rated findings (CRITICAL/HIGH/MEDIUM/LOW)
+- Recommends whether to PROCEED, PROCEED_WITH_FIXES, or BLOCK_EXECUTION
+- Provides actionable remediation suggestions for detected issues
+
 **Phase 4: Execution**
 ```bash
 # Execute tasks with AI agents
@@ -363,8 +441,9 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
 
 | Command | Description |
 |---|---|
-| `/workflow:session:*` | Manage development sessions (`start`, `pause`, `resume`, `list`, `switch`, `complete`). |
+| `/workflow:session:*` | Manage development sessions (`start`, `resume`, `list`, `complete`). |
 | `/workflow:brainstorm:*` | Use role-based agents for multi-perspective planning. |
+| `/workflow:concept-clarify` | **Optional** Quality gate - Identify and resolve ambiguities in brainstorming artifacts before planning (runs after synthesis, before plan). |
 | `/workflow:ui-design:explore-auto` | **v4.4.0** Matrix exploration mode - Generate multiple style × layout variants with layout/style separation. |
 | `/workflow:ui-design:imitate-auto` | **v4.4.0** Fast imitation mode - Rapid UI replication with auto-screenshot, layout extraction, and assembly. |
 | `/workflow:ui-design:style-extract` | **v4.4.0** Extract visual style (colors, typography, spacing) from images/text using Claude-native analysis. |
@@ -374,6 +453,7 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
 | `/workflow:ui-design:update` | **v4.4.0** Integrate finalized design system into brainstorming artifacts. |
 | `/workflow:plan` | Create a detailed, executable plan from a description. |
 | `/workflow:tdd-plan` | Create TDD workflow (6 phases) with test coverage analysis and Red-Green-Refactor cycles. |
+| `/workflow:action-plan-verify` | **Optional** Pre-execution check - Validate IMPL_PLAN.md and task.json consistency and completeness (runs after plan, before execute). |
 | `/workflow:execute` | Execute the current workflow plan autonomously. |
 | `/workflow:status` | Display the current status of the workflow. |
 | `/workflow:test-gen [--use-codex] <session>` | Create test generation workflow with auto-diagnosis and fix cycle for completed implementations. |
@@ -387,6 +467,77 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
 
 The design workflow system provides complete UI design refinement with **layout/style separation architecture**, **pure Claude execution**, **intelligent target inference**, and **zero external dependencies**.
 
+#### 📐 Architecture Overview
+
+The UI workflow follows a **separation of concerns** philosophy:
+- **Style (Visual Tokens)**: Colors, typography, spacing, borders → `design-tokens.json`
+- **Layout (Structure)**: DOM hierarchy, CSS layout rules → `layout-templates.json`
+- **Assembly**: Pure combination of style + layout → HTML/CSS prototypes
+
+**Command Categories:**
+
+| Category | Commands | Purpose |
+|----------|----------|---------|
+| **High-Level Orchestrators** | `explore-auto`, `imitate-auto`, `batch-generate` | Complete workflows (recommended) |
+| **Input/Capture** | `capture`, `explore-layers` | Screenshot acquisition |
+| **Analysis/Extraction** | `style-extract`, `layout-extract` | Visual style and structural layout extraction |
+| **Processing/Generation** | `consolidate`, `generate` | Token validation and prototype assembly |
+| **Integration** | `update` | Design system integration into project |
+
+#### 🧭 Decision Tree: Which Command Should I Use?
+
+```
+┌─ Have an idea or text description?
+│  └─→ /workflow:ui-design:explore-auto
+│     (Explores multiple style × layout options)
+│
+┌─ Want to replicate an existing design?
+│  └─→ /workflow:ui-design:imitate-auto
+│     (High-fidelity single design replication)
+│
+┌─ Already have a design system?
+│  └─→ /workflow:ui-design:batch-generate
+│     (Batch create multiple pages/components)
+│
+└─ Need fine-grained control?
+   └─→ Use individual commands in sequence:
+       1. style-extract → Extract colors, fonts, spacing
+       2. consolidate → Validate and merge tokens
+       3. layout-extract → Extract DOM structure
+       4. generate → Combine into prototypes
+       5. update → Integrate into project
+```
+
+#### 🔄 Workflow Diagrams
+
+**Explore Workflow** (Idea → Multiple Designs):
+```
+Prompt/Images → style-extract (explore mode)
+                     ↓
+              consolidate (N variants)
+                     ↓
+              layout-extract (explore mode)
+                     ↓
+              generate (N styles × M layouts)
+                     ↓
+              update (selected designs)
+```
+
+**Imitate Workflow** (Reference → Single Design):
+```
+URL/Images → capture/explore-layers
+                  ↓
+           style-extract (imitate mode)
+                  ↓
+           layout-extract (imitate mode)
+                  ↓
+           consolidate (single variant)
+                  ↓
+           generate (1 style × 1 layout)
+                  ↓
+           update (final design)
+```
+
 #### Core Commands
 
 **`/workflow:ui-design:explore-auto`** - Matrix exploration mode
@@ -520,6 +671,61 @@ php -S localhost:8080           # PHP
 - Dynamic page switching
 - Real-time responsive testing
 
+#### 📦 Output Structure
+
+All UI workflow outputs are organized in the `.design` directory within your session:
+
+```
+.workflow/WFS-<session-id>/.design/
+├── design-run-YYYYMMDD-HHMMSS/          # Timestamped design run
+│   ├── screenshots/                      # 📸 Captured screenshots
+│   │   ├── home.png
+│   │   └── dashboard.png
+│   │
+│   ├── style-extraction/                 # 🎨 Style analysis phase
+│   │   ├── style-cards.json             # AI-proposed style variants
+│   │   └── design-space-analysis.json   # (explore mode) Diversity analysis
+│   │
+│   ├── layout-extraction/                # 🏗️ Layout analysis phase
+│   │   └── layout-templates.json        # Structural templates with token-based CSS
+│   │
+│   ├── style-consolidation/              # ✅ Production design systems
+│   │   ├── style-1/
+│   │   │   ├── design-tokens.json       # W3C design tokens
+│   │   │   ├── style-guide.md           # Visual design documentation
+│   │   │   ├── tailwind.config.js       # Tailwind configuration
+│   │   │   └── validation-report.json   # WCAG AA validation results
+│   │   └── style-2/
+│   │       └── ...
+│   │
+│   └── prototypes/                       # 🎯 Final HTML/CSS prototypes
+│       ├── home-style-1-layout-1.html   # Matrix-generated prototypes
+│       ├── home-style-1-layout-1.css
+│       ├── home-style-1-layout-2.html
+│       ├── dashboard-style-2-layout-1.html
+│       ├── index.html                   # Master navigation page
+│       └── compare.html                 # Side-by-side comparison tool
+│
+└── latest -> design-run-YYYYMMDD-HHMMSS  # Symlink to most recent run
+```
+
+**Key Files:**
+
+| File | Purpose | Generated By |
+|------|---------|--------------|
+| `style-cards.json` | AI-proposed visual styles with embedded tokens | `style-extract` |
+| `layout-templates.json` | Structural templates with token-based CSS | `layout-extract` |
+| `design-tokens.json` | Production-ready W3C design tokens | `consolidate` |
+| `style-guide.md` | Visual design system documentation | `consolidate` |
+| `compare.html` | Interactive prototype comparison matrix | `generate` |
+
+**Best Practices:**
+
+1. **Session Management**: All runs within a session accumulate in `.design/design-run-*/`
+2. **Versioning**: Each run is timestamped for easy rollback
+3. **Integration**: Use `update` command to link final tokens to project artifacts
+4. **Cleanup**: Old runs can be safely deleted; `latest` symlink always points to newest
+
 ---
 
 ### **Task & Memory Commands**

README_CN.md

@@ -2,7 +2,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/version-v4.3.0-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases)
+[![Version](https://img.shields.io/badge/version-v4.4.0-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)]()
 [![MCP工具](https://img.shields.io/badge/🔧_MCP工具-实验性-orange.svg)](https://github.com/modelcontextprotocol)
@@ -15,13 +15,13 @@
 
 **Claude Code Workflow (CCW)** 是一个新一代的多智能体自动化开发框架，通过智能工作流管理和自主执行来协调复杂的软件开发任务。
 
-> **🎉 最新版本: v4.3.0** - UI 设计工作流 V2 自包含 CSS 架构。详见 [CHANGELOG.md](CHANGELOG.md)。
+> **🎉 最新版本: v4.4.0** - UI 设计工作流 V3 布局/样式分离架构。详见 [CHANGELOG.md](CHANGELOG.md)。
 >
-> **v4.3.0 版本新特性**:
-> - 🎨 **自包含 CSS**: Agent 从 design-tokens.json 直接生成独立 CSS
-> - ⚡ **简化工作流**: 移除占位符机制和令牌转换步骤
-> - 💪 **更强风格差异**: CSS 使用直接令牌值，实现更强视觉区分
-> - 📉 **代码减少 31%**: 移除 346 行代码，职责更清晰
+> **v4.4.0 版本新特性**:
+> - 🏗️ **布局/样式分离**: 新的 `layout-extract` 命令将结构与视觉令牌分离
+> - 📦 **纯汇编器**: `generate` 命令现在纯粹组合预提取的布局 + 样式
+> - 🎯 **更好的多样性**: 布局探索生成结构上不同的设计
+> - ✅ **单一职责**: 每个阶段（样式、布局、汇编）都有明确的目的
 
 ---
 
@@ -144,17 +144,43 @@ bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-Workflo
 
 ## ⚙️ 配置
 
-### **前置要求：必需工具**
+### **工具控制系统**
 
-在使用 CCW 之前，请安装以下命令行工具：
+CCW 使用**基于配置的工具控制系统**，使外部 CLI 工具成为**可选项**而非必需项。这允许您：
 
-#### **核心 CLI 工具**
+- ✅ **从纯 Claude 模式开始** - 无需安装额外工具即可立即开始工作
+- ✅ **渐进式增强** - 根据需要选择性地添加外部工具
+- ✅ **优雅降级** - 工具不可用时自动回退
+- ✅ **灵活配置** - 按项目控制工具可用性
 
-| 工具 | 用途 | 安装方式 |
-|------|------|----------|
-| **Gemini CLI** | AI 分析与文档生成 | `npm install -g @google/gemini-cli` ([GitHub](https://github.com/google-gemini/gemini-cli)) |
-| **Codex CLI** | AI 开发与实现 | `npm install -g @openai/codex` ([GitHub](https://github.com/openai/codex)) |
-| **Qwen Code** | AI 架构与代码生成 | `npm install -g @qwen-code/qwen-code` ([文档](https://github.com/QwenLM/qwen-code)) |
+**配置文件**: `~/.claude/workflows/tool-control.yaml`
+
+```yaml
+tools:
+  gemini:
+    enabled: false  # 可选：AI 分析与文档生成
+  qwen:
+    enabled: true   # 可选：AI 架构与代码生成
+  codex:
+    enabled: true   # 可选：AI 开发与实现
+```
+
+**行为**:
+- **禁用时**: CCW 自动回退到其他已启用工具或 Claude 的原生能力
+- **启用时**: 使用专用工具发挥各自优势
+- **默认**: 所有工具禁用 - 纯 Claude 模式开箱即用
+
+### **可选 CLI 工具** *(增强功能)*
+
+虽然 CCW 仅使用 Claude 即可工作，但安装这些工具可提供增强的分析和扩展上下文：
+
+#### **外部 CLI 工具**
+
+| 工具 | 用途 | 安装方式 | 优势 |
+|------|------|----------|------|
+| **Gemini CLI** | AI 分析与文档生成 | `npm install -g @google/gemini-cli` ([GitHub](https://github.com/google-gemini/gemini-cli)) | 免费配额，复杂项目的扩展上下文 |
+| **Codex CLI** | AI 开发与实现 | `npm install -g @openai/codex` ([GitHub](https://github.com/openai/codex)) | 自主开发，数学推理 |
+| **Qwen Code** | AI 架构与代码生成 | `npm install -g @qwen-code/qwen-code` ([文档](https://github.com/QwenLM/qwen-code)) | 大上下文窗口，架构分析 |
 
 #### **系统实用工具**
 
@@ -248,28 +274,65 @@ MCP (模型上下文协议) 工具提供高级代码库分析。**推荐安装**
 /workflow:brainstorm:synthesis  # 生成综合规范
 ```
 
-**阶段 2：UI 设计精炼** *(UI 密集型项目可选)*
+**阶段 1.5：概念验证** *(可选质量关卡)*
 ```bash
-# 矩阵探索模式 - 多个风格×布局变体（v4.2.1+）
+# 识别并解决头脑风暴产物中的歧义
+/workflow:concept-clarify
+
+# 或显式指定会话
+/workflow:concept-clarify --session WFS-auth
+```
+- 在 `/workflow:brainstorm:synthesis` 之后、`/workflow:plan` 之前运行
+- 通过交互式问答澄清未明确的需求、架构决策或风险
+- 每次会话最多 5 个问题，支持多选或简答格式
+- 增量更新 `synthesis-specification.md` 以记录澄清内容
+- 确保概念基础明确后再进行详细规划
+- 生成覆盖度摘要，建议继续或解决未决项
+
+**阶段 2：UI 设计精炼** *(UI 密集型项目可选)*
+
+**🎯 选择您的工作流：**
+
+**场景 1：从想法或概念开始** → 使用 `explore-auto`
+```bash
+# 生成多个风格和布局选项来探索不同方向
 /workflow:ui-design:explore-auto --prompt "现代博客：首页，文章，作者" --style-variants 3 --layout-variants 2
+# 创建一个 3×2 矩阵：3种视觉风格 × 2种布局 = 6个原型供选择
+```
 
-# 快速模仿模式 - 单一设计快速复制（v4.2.1+）
+**场景 2：复制现有设计** → 使用 `imitate-auto`
+```bash
+# 快速、高保真复制参考设计
 /workflow:ui-design:imitate-auto --images "refs/design.png" --pages "dashboard,settings"
+# 或从 URL 自动截图（需要 Playwright/Chrome DevTools MCP）
+/workflow:ui-design:imitate-auto --url "https://linear.app" --pages "home,features"
+```
 
-# 与会话集成
-/workflow:ui-design:explore-auto --session WFS-auth --images "refs/*.png" --style-variants 2 --layout-variants 3
+**场景 3：从现有设计系统批量创建** → 使用 `batch-generate`
+```bash
+# 已有设计系统？快速生成多个页面
+/workflow:ui-design:batch-generate --prompt "创建个人资料和设置页面" --layout-variants 2
+```
 
-# 或者运行单独的设计阶段
-/workflow:ui-design:extract --images "refs/*.png" --variants 3
+**高级：手动分步控制** (v4.4.0+)
+```bash
+# 1. 提取视觉样式（颜色、排版、间距）
+/workflow:ui-design:style-extract --images "refs/*.png" --mode explore --variants 3
+
+# 2. 整合为可用于生产的设计令牌
 /workflow:ui-design:consolidate --variants "variant-1,variant-3"
-/workflow:ui-design:generate --pages "dashboard,auth" --style-variants 2 --layout-variants 2
 
-# 预览生成的原型
-# 选项1：在浏览器中打开 .workflow/WFS-auth/.design/prototypes/compare.html
-# 选项2：启动本地服务器
+# 3. 提取布局结构（DOM、CSS 布局规则）
+/workflow:ui-design:layout-extract --targets "dashboard,auth" --mode explore --variants 2 --device-type responsive
+
+# 4. 组合样式 + 布局 → HTML/CSS 原型
+/workflow:ui-design:generate --style-variants 1 --layout-variants 2
+
+# 5. 预览并选择
 cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
-# 访问 http://localhost:8080 获取交互式预览和对比工具
+# 访问 http://localhost:8080/compare.html 进行并排比较
 
+# 6. 将选定的设计集成到项目中
 /workflow:ui-design:update --session WFS-auth --selected-prototypes "dashboard-s1-l2"
 ```
 
@@ -282,6 +345,22 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
 /workflow:tdd-plan "使用测试优先开发实现认证"
 ```
 
+**阶段 3.5：行动计划验证** *(可选执行前检查)*
+```bash
+# 验证计划一致性和完整性
+/workflow:action-plan-verify
+
+# 或显式指定会话
+/workflow:action-plan-verify --session WFS-auth
+```
+- 在 `/workflow:plan` 或 `/workflow:tdd-plan` 之后、`/workflow:execute` 之前运行
+- 对 `IMPL_PLAN.md` 和任务 JSON 文件进行只读分析，并与 `synthesis-specification.md` 对照
+- 验证需求覆盖率、依赖完整性和综合对齐性
+- 识别不一致、重复、歧义和未充分说明的项目
+- 生成详细验证报告，包含严重性评级的发现（CRITICAL/HIGH/MEDIUM/LOW）
+- 建议是否 PROCEED、PROCEED_WITH_FIXES 或 BLOCK_EXECUTION
+- 提供针对检测到的问题的可操作修复建议
+
 **阶段 4：执行**
 ```bash
 # 使用 AI 智能体执行任务
@@ -362,16 +441,19 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
 
 | 命令 | 描述 |
 |---|---|
-| `/workflow:session:*` | 管理开发会话（`start`, `pause`, `resume`, `list`, `switch`, `complete`）。 |
+| `/workflow:session:*` | 管理开发会话（`start`, `resume`, `list`, `complete`）。 |
 | `/workflow:brainstorm:*` | 使用基于角色的智能体进行多视角规划。 |
-| `/workflow:ui-design:explore-auto` | **v4.2.1** 矩阵探索模式 - 生成多个风格×布局变体，全面探索设计方向。 |
-| `/workflow:ui-design:imitate-auto` | **v4.2.1** 快速模仿模式 - 单一设计快速复制，自动截图和直接令牌提取。 |
-| `/workflow:ui-design:extract` | **v4.2.1** 使用 Claude 原生分析从图像/文本提取设计。单次生成变体。 |
-| `/workflow:ui-design:consolidate` | **v4.2.1** 使用 Claude 合成将风格变体整合为经过验证的设计令牌。 |
-| `/workflow:ui-design:generate` | **v4.2.1** 生成矩阵模式（风格×布局组合）的令牌驱动 HTML/CSS 原型。 |
-| `/workflow:ui-design:update` | **v4.2.1** 将最终确定的设计系统集成到头脑风暴产物中。 |
+| `/workflow:concept-clarify` | **可选** 质量关卡 - 在规划之前识别并解决头脑风暴产物中的歧义（在综合后、规划前运行）。 |
+| `/workflow:ui-design:explore-auto` | **v4.4.0** 矩阵探索模式 - 通过布局/样式分离生成多个风格×布局变体。 |
+| `/workflow:ui-design:imitate-auto` | **v4.4.0** 快速模仿模式 - 通过自动截图、布局提取和汇编实现快速 UI 复制。 |
+| `/workflow:ui-design:style-extract` | **v4.4.0** 使用 Claude 原生分析从图像/文本提取视觉样式（颜色、排版、间距）。 |
+| `/workflow:ui-design:layout-extract` | **v4.4.0** 通过设备感知模板提取结构布局（DOM、CSS 布局规则）。 |
+| `/workflow:ui-design:consolidate` | **v4.4.0** 使用 Claude 合成将风格变体整合为经过验证的设计令牌。 |
+| `/workflow:ui-design:generate` | **v4.4.0** 纯汇编器 - 组合布局模板 + 设计令牌 → HTML/CSS 原型。 |
+| `/workflow:ui-design:update` | **v4.4.0** 将最终确定的设计系统集成到头脑风暴产物中。 |
 | `/workflow:plan` | 从描述创建详细、可执行的计划。 |
 | `/workflow:tdd-plan` | 创建 TDD 工作流（6 阶段），包含测试覆盖分析和 Red-Green-Refactor 循环。 |
+| `/workflow:action-plan-verify` | **可选** 执行前检查 - 验证 IMPL_PLAN.md 和任务 JSON 的一致性和完整性（在规划后、执行前运行）。 |
 | `/workflow:execute` | 自主执行当前的工作流计划。 |
 | `/workflow:status` | 显示工作流的当前状态。 |
 | `/workflow:test-gen [--use-codex] <session>` | 为已完成实现创建独立测试生成工作流，支持自动诊断和修复。 |
@@ -381,9 +463,80 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
 | `/workflow:tools:test-concept-enhanced` | 使用 Gemini 生成测试策略和需求分析。 |
 | `/workflow:tools:test-task-generate` | 生成测试任务 JSON，包含 test-fix-cycle 规范。 |
 
-### **UI 设计工作流命令 (`/workflow:ui-design:*`)** *(v4.2.1)*
+### **UI 设计工作流命令 (`/workflow:ui-design:*`)** *(v4.4.0)*
 
-设计工作流系统提供完整的 UI 设计精炼，具备**纯 Claude 执行**、**智能页面推断**和**零外部依赖**。
+设计工作流系统提供完整的 UI 设计精炼，具备**布局/样式分离架构**、**纯 Claude 执行**、**智能目标推断**和**零外部依赖**。
+
+#### 📐 架构概述
+
+UI 工作流遵循**关注点分离**哲学：
+- **样式（视觉令牌）**：颜色、排版、间距、边框 → `design-tokens.json`
+- **布局（结构）**：DOM 层次结构、CSS 布局规则 → `layout-templates.json`
+- **汇编**：纯粹组合样式 + 布局 → HTML/CSS 原型
+
+**命令分类：**
+
+| 类别 | 命令 | 目的 |
+|----------|----------|---------|
+| **高级编排器** | `explore-auto`, `imitate-auto`, `batch-generate` | 完整工作流（推荐） |
+| **输入/捕获** | `capture`, `explore-layers` | 截图获取 |
+| **分析/提取** | `style-extract`, `layout-extract` | 视觉样式和结构布局提取 |
+| **处理/生成** | `consolidate`, `generate` | 令牌验证和原型汇编 |
+| **集成** | `update` | 设计系统集成到项目 |
+
+#### 🧭 决策树：应该使用哪个命令？
+
+```
+┌─ 有想法或文本描述？
+│  └─→ /workflow:ui-design:explore-auto
+│     （探索多个风格 × 布局选项）
+│
+┌─ 想复制现有设计？
+│  └─→ /workflow:ui-design:imitate-auto
+│     （高保真单一设计复制）
+│
+┌─ 已有设计系统？
+│  └─→ /workflow:ui-design:batch-generate
+│     （批量创建多个页面/组件）
+│
+└─ 需要细粒度控制？
+   └─→ 按顺序使用单独命令：
+       1. style-extract → 提取颜色、字体、间距
+       2. consolidate → 验证并合并令牌
+       3. layout-extract → 提取 DOM 结构
+       4. generate → 组合为原型
+       5. update → 集成到项目
+```
+
+#### 🔄 工作流程图
+
+**探索工作流**（想法 → 多个设计）：
+```
+提示词/图像 → style-extract（探索模式）
+                     ↓
+              consolidate（N 个变体）
+                     ↓
+              layout-extract（探索模式）
+                     ↓
+              generate（N 个样式 × M 个布局）
+                     ↓
+              update（选定的设计）
+```
+
+**模仿工作流**（参考 → 单一设计）：
+```
+URL/图像 → capture/explore-layers
+                  ↓
+           style-extract（模仿模式）
+                  ↓
+           layout-extract（模仿模式）
+                  ↓
+           consolidate（单一变体）
+                  ↓
+           generate（1 个样式 × 1 个布局）
+                  ↓
+           update（最终设计）
+```
 
 #### 核心命令
 
@@ -420,27 +573,64 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
 - **🎯 直接提取**: 跳过变体选择，直接进入实现
 - **🔧 单一设计聚焦**: 最适合快速复制现有设计
 
-**`/workflow:ui-design:style-consolidate`** - 验证和合并令牌
+**`/workflow:ui-design:style-extract`** - 视觉样式提取（v4.4.0）
+```bash
+# 纯文本提示
+/workflow:ui-design:style-extract --prompt "现代极简，深色主题" --mode explore --variants 3
+
+# 纯图像
+/workflow:ui-design:style-extract --images "refs/*.png" --mode explore --variants 3
+
+# 混合（文本指导图像分析）
+/workflow:ui-design:style-extract --images "refs/*.png" --prompt "Linear.app 风格" --mode imitate
+
+# 高保真单一风格
+/workflow:ui-design:style-extract --images "design.png" --mode imitate
+```
+- **🎨 仅视觉令牌**：颜色、排版、间距（无布局结构）
+- **🔄 双模式**：模仿（单一变体）/ 探索（多个变体）
+- **Claude 原生**：单次分析，无外部工具
+- **输出**：包含嵌入式 `proposed_tokens` 的 `style-cards.json`
+
+**`/workflow:ui-design:layout-extract`** - 结构布局提取（v4.4.0）
+```bash
+# 探索模式 - 多个布局变体
+/workflow:ui-design:layout-extract --targets "home,dashboard" --mode explore --variants 3 --device-type responsive
+
+# 模仿模式 - 单一布局复制
+/workflow:ui-design:layout-extract --images "refs/*.png" --targets "dashboard" --mode imitate --device-type desktop
+
+# 使用 MCP 研究（探索模式）
+/workflow:ui-design:layout-extract --prompt "电商结账" --targets "cart,checkout" --mode explore --variants 2
+```
+- **🏗️ 仅结构**：DOM 层次结构、CSS 布局规则（无视觉样式）
+- **📱 设备感知**：桌面、移动、平板、响应式优化
+- **🧠 智能体驱动**：使用 ui-design-agent 进行结构分析
+- **🔍 MCP 研究**：布局模式灵感（探索模式）
+- **输出**：包含基于令牌的 CSS 的 `layout-templates.json`
+
+**`/workflow:ui-design:consolidate`** - 验证和合并令牌
 ```bash
 # 整合选定的风格变体
-/workflow:ui-design:style-consolidate --session WFS-auth --variants "variant-1,variant-3"
+/workflow:ui-design:consolidate --session WFS-auth --variants "variant-1,variant-3"
 ```
-- **功能**: WCAG AA 验证、OKLCH 颜色、W3C 令牌格式
-- **输出**: `design-tokens.json`、`style-guide.md`、`tailwind.config.js`
+- **Claude 合成**：单次生成所有设计系统文件
+- **功能**：WCAG AA 验证、OKLCH 颜色、W3C 令牌格式
+- **输出**：`design-tokens.json`、`style-guide.md`、`tailwind.config.js`、`validation-report.json`
 
-**`/workflow:ui-design:generate`** - 生成 HTML/CSS 原型
+**`/workflow:ui-design:generate`** - 纯汇编器（v4.4.0）
 ```bash
-# 矩阵模式 - 风格×布局组合
-/workflow:ui-design:generate --pages "dashboard,auth" --style-variants 2 --layout-variants 3
+# 组合布局模板 + 设计令牌
+/workflow:ui-design:generate --style-variants 1 --layout-variants 2
 
-# 单页面多变体
-/workflow:ui-design:generate --pages "home" --style-variants 3 --layout-variants 2
+# 多个样式与多个布局
+/workflow:ui-design:generate --style-variants 2 --layout-variants 3
 ```
-- **🎯 矩阵生成**: 创建所有风格×布局组合
-- **📊 多页面支持**: 跨页面一致的设计系统
-- **✅ 一致性验证**: 自动跨页面一致性报告（v4.2.0+）
-- **🔍 交互式预览**: `compare.html` 并排比较
-- **📋 批量选择**: 按风格或布局过滤器快速选择
+- **📦 纯汇编**：组合预提取的 layout-templates.json + design-tokens.json
+- **❌ 无设计逻辑**：所有布局/样式决策在之前阶段完成
+- **✅ 令牌解析**：用实际令牌值替换 var() 占位符
+- **🎯 矩阵输出**：生成样式 × 布局 × 目标原型
+- **🔍 交互式预览**：`compare.html` 并排比较
 
 **`/workflow:ui-design:update`** - 集成设计系统
 ```bash
@@ -481,6 +671,61 @@ php -S localhost:8080           # PHP
 - 动态页面切换
 - 实时响应式测试
 
+#### 📦 输出结构
+
+所有 UI 工作流输出都组织在会话内的 `.design` 目录中：
+
+```
+.workflow/WFS-<session-id>/.design/
+├── design-run-YYYYMMDD-HHMMSS/          # 带时间戳的设计运行
+│   ├── screenshots/                      # 📸 捕获的截图
+│   │   ├── home.png
+│   │   └── dashboard.png
+│   │
+│   ├── style-extraction/                 # 🎨 样式分析阶段
+│   │   ├── style-cards.json             # AI 提议的风格变体
+│   │   └── design-space-analysis.json   # （探索模式）多样性分析
+│   │
+│   ├── layout-extraction/                # 🏗️ 布局分析阶段
+│   │   └── layout-templates.json        # 包含基于令牌的 CSS 的结构模板
+│   │
+│   ├── style-consolidation/              # ✅ 生产设计系统
+│   │   ├── style-1/
+│   │   │   ├── design-tokens.json       # W3C 设计令牌
+│   │   │   ├── style-guide.md           # 视觉设计文档
+│   │   │   ├── tailwind.config.js       # Tailwind 配置
+│   │   │   └── validation-report.json   # WCAG AA 验证结果
+│   │   └── style-2/
+│   │       └── ...
+│   │
+│   └── prototypes/                       # 🎯 最终 HTML/CSS 原型
+│       ├── home-style-1-layout-1.html   # 矩阵生成的原型
+│       ├── home-style-1-layout-1.css
+│       ├── home-style-1-layout-2.html
+│       ├── dashboard-style-2-layout-1.html
+│       ├── index.html                   # 主导航页面
+│       └── compare.html                 # 并排比较工具
+│
+└── latest -> design-run-YYYYMMDD-HHMMSS  # 指向最新运行的符号链接
+```
+
+**关键文件：**
+
+| 文件 | 目的 | 生成命令 |
+|------|---------|--------------|
+| `style-cards.json` | AI 提议的视觉样式及嵌入的令牌 | `style-extract` |
+| `layout-templates.json` | 包含基于令牌的 CSS 的结构模板 | `layout-extract` |
+| `design-tokens.json` | 可用于生产的 W3C 设计令牌 | `consolidate` |
+| `style-guide.md` | 视觉设计系统文档 | `consolidate` |
+| `compare.html` | 交互式原型比较矩阵 | `generate` |
+
+**最佳实践：**
+
+1. **会话管理**：会话内的所有运行累积在 `.design/design-run-*/`
+2. **版本控制**：每次运行都有时间戳，便于回滚
+3. **集成**：使用 `update` 命令将最终令牌链接到项目产物
+4. **清理**：旧运行可以安全删除；`latest` 符号链接始终指向最新的
+
 ---
 
 ### **任务与内存命令**

WORKFLOW_DIAGRAMS.md

@@ -512,15 +512,13 @@ graph TD
 graph LR
     subgraph "Session Management"
         WFS_START["/workflow:session:start"]
-        WFS_PAUSE["/workflow:session:pause"]
         WFS_RESUME["/workflow:session:resume"]
-        WFS_SWITCH["/workflow:session:switch"]
         WFS_LIST["/workflow:session:list"]
+        WFS_COMPLETE["/workflow:session:complete"]
 
-        WFS_START --> WFS_PAUSE
-        WFS_PAUSE --> WFS_RESUME
-        WFS_RESUME --> WFS_SWITCH
-        WFS_SWITCH --> WFS_LIST
+        WFS_START --> WFS_LIST
+        WFS_LIST --> WFS_RESUME
+        WFS_RESUME --> WFS_COMPLETE
     end
 
     subgraph "Planning Phase"
@@ -554,7 +552,6 @@ graph LR
     WFS_START --> WF_BRAINSTORM
     WF_PLAN --> WF_EXECUTE
     WF_EXECUTE --> TASK_CREATE
-    WF_REVIEW --> WFS_PAUSE
 ```
 
 ## 11. Planning Method Selection Flow

ui-instantiate-analysis.md

@@ -1,231 +0,0 @@
-# UI原型实例化脚本分析报告
-
-## 问题现象
-
-在执行 `ui-instantiate-prototypes.sh` 脚本时，生成了 `style-4` 的原型文件（如 `login-style-4-layout-1.html`），但实际上 `style-consolidation` 目录下只有3个样式目录（style-1, style-2, style-3）。
-
-## 调查结果
-
-### 1. 目录结构验证
-
-```bash
-# 实际存在的样式目录
-.workflow/.design/run-20251009-210559/style-consolidation/
-├── style-1/
-├── style-2/
-└── style-3/
-
-# 生成的原型文件包含
-prototypes/login-style-4-layout-1.html  ❌ 引用不存在的 ../style-consolidation/style-4/tokens.css
-prototypes/sidebar-style-4-layout-1.html  ❌ 引用不存在的 ../style-consolidation/style-4/tokens.css
-```
-
-### 2. consolidation-report.json 确认
-
-```json
-{
-  "variant_count": 3,  // 明确显示只有3个变体
-  "variants": [
-    {"id": "style-1"},
-    {"id": "style-2"},
-    {"id": "style-3"}
-  ]
-}
-```
-
-### 3. PREVIEW.md 显示异常
-
-```markdown
-- **Style Variants:** 4  ⚠️ 与实际不符
-- **Total Prototypes:** 24  (4 × 3 × 2 = 24)
-```
-
-### 4. 脚本auto_detect_style_variants()函数
-
-```bash
-# 位置：.claude/scripts/ui-instantiate-prototypes.sh 第52-71行
-auto_detect_style_variants() {
-    local base_path="$1"
-    local style_dir="$base_path/../style-consolidation"
-
-    # 统计style-*目录数量
-    local count=$(find "$style_dir" -maxdepth 1 -type d -name "style-*" | wc -l)
-    echo "$count"
-}
-```
-
-**验证测试**：
-```bash
-cd .workflow/.design/run-20251009-210559/style-consolidation
-find . -maxdepth 1 -type d -name "style-*" | wc -l
-# 输出：3 ✅ 函数逻辑正确
-```
-
-## 根本原因分析
-
-### ⚠️ 参数覆盖问题
-
-脚本虽然有自动检测功能，但**允许手动参数覆盖**：
-
-```bash
-# 自动检测模式（正确）
-ui-instantiate-prototypes.sh prototypes/  # 会自动检测到3个样式
-
-# 手动模式（错误来源）
-ui-instantiate-prototypes.sh prototypes/ "login,sidebar" 4 3  # 强制指定4个样式变体 ❌
-```
-
-### 🔍 实际调用场景
-
-根据工作流命令 `.claude/commands/workflow/ui-design/generate.md` 第79-82行：
-
-```bash
-# Phase 1: Path Resolution & Context Loading
-style_variants = --style-variants OR 3  # 默认为3
-```
-
-**推断的问题来源**：
-1. 工作流命令被手动调用时，传入了 `--style-variants 4`
-2. 这个参数被直接传递给 `ui-instantiate-prototypes.sh` 脚本
-3. 脚本没有验证参数值与实际目录数量是否匹配
-4. 导致生成了引用不存在的style-4目录的HTML文件
-
-## 问题影响
-
-### 生成的style-4文件问题
-
-所有 `*-style-4-*.html` 文件都会出现CSS加载失败：
-
-```html
-<!-- 文件中的CSS引用 -->
-<link rel="stylesheet" href="../style-consolidation/style-4/tokens.css">
-<!-- ❌ 该路径不存在，导致样式无法加载 -->
-```
-
-### 影响范围
-
-- `login-style-4-layout-{1,2,3}.html` - 3个文件 ❌
-- `sidebar-style-4-layout-{1,2,3}.html` - 3个文件 ❌
-- 对应的 `*-notes.md` 文件 - 6个说明文件（内容错误）
-
-## 解决方案
-
-### 方案1：重新生成（推荐）
-
-```bash
-cd .workflow/.design/run-20251009-210559/prototypes
-
-# 删除错误的style-4文件
-rm -f *-style-4-*
-
-# 重新运行脚本（使用自动检测）
-~/.claude/scripts/ui-instantiate-prototypes.sh . --session-id run-20251009-210559
-```
-
-### 方案2：脚本增强（预防）
-
-在 `ui-instantiate-prototypes.sh` 中添加参数验证：
-
-```bash
-# 在第239行之后添加
-# Validate STYLE_VARIANTS matches actual directories
-actual_styles=$(find "$BASE_PATH/../style-consolidation" -maxdepth 1 -type d -name "style-*" | wc -l)
-if [ "$STYLE_VARIANTS" -gt "$actual_styles" ]; then
-    log_warning "Requested $STYLE_VARIANTS style variants, but only found $actual_styles directories"
-    log_info "Auto-correcting to $actual_styles style variants"
-    STYLE_VARIANTS=$actual_styles
-fi
-```
-
-### 方案3：工作流命令修复
-
-在 `.claude/commands/workflow/ui-design/generate.md` 中添加验证：
-
-```bash
-# Phase 1: Path Resolution & Context Loading (第79-82行之后)
-style_variants = --style-variants OR 3  # Default to 3
-
-# 添加验证逻辑
-actual_styles = count_directories({base_path}/style-consolidation/style-*)
-IF style_variants > actual_styles:
-    WARN: "Requested {style_variants} styles, but only {actual_styles} exist"
-    REPORT: "Auto-correcting to {actual_styles} style variants"
-    style_variants = actual_styles
-
-VALIDATE: 1 <= style_variants <= 5
-```
-
-## 预防措施
-
-1. **优先使用自动检测**：
-   ```bash
-   # ✅ 推荐：让脚本自动检测
-   ui-instantiate-prototypes.sh prototypes/
-
-   # ⚠️ 谨慎：手动指定参数（需确保正确）
-   ui-instantiate-prototypes.sh prototypes/ "login,sidebar" 3 3
-   ```
-
-2. **验证consolidation输出**：
-   ```bash
-   # 生成原型前，先确认样式数量
-   jq '.variant_count' style-consolidation/consolidation-report.json
-   ```
-
-3. **使用工作流命令**：
-   ```bash
-   # 工作流命令会自动处理参数验证
-   /workflow:ui-design:generate --base-path ".workflow/.design/run-xxx"
-   ```
-
-## 技术细节
-
-### 自动检测逻辑流程
-
-```mermaid
-graph TD
-    A[调用脚本] --> B{检查参数数量}
-    B -->|1个参数| C[自动检测模式]
-    B -->|4个参数| D[手动模式]
-    C --> E[检测style目录]
-    D --> F[使用传入参数]
-    E --> G[验证目录存在]
-    F --> G
-    G -->|不匹配| H[⚠️ 生成错误文件]
-    G -->|匹配| I[✅ 正常生成]
-```
-
-### find命令行为
-
-```bash
-# 正确的检测命令
-find style-consolidation -maxdepth 1 -type d -name "style-*"
-# 输出：
-# style-consolidation/style-1
-# style-consolidation/style-2
-# style-consolidation/style-3
-
-# wc -l 统计行数 = 3 ✅
-
-# 注意：style-extraction 不会被匹配（它在父目录）
-# find . -maxdepth 1 -type d -name "style-*"
-# 只会在当前目录搜索，不会递归到子目录
-```
-
-## 总结
-
-### 问题根源
-✅ **确认**：脚本被手动调用时传入了错误的 `--style-variants 4` 参数，但实际只有3个样式目录存在。
-
-### 脚本行为
-✅ **确认**：`auto_detect_style_variants()` 函数逻辑正确，能够正确检测到3个样式目录。
-
-### 修复优先级
-1. 🔴 **立即**：删除错误的style-4文件，重新生成
-2. 🟡 **短期**：在脚本中添加参数验证逻辑
-3. 🟢 **长期**：在工作流命令中添加防护验证
-
-### 最佳实践
-- 优先使用脚本的自动检测模式
-- 在手动指定参数前，先验证 `consolidation-report.json`
-- 使用工作流命令而非直接调用脚本

ui-workflow-parameter-clarity-report.md

@@ -1,425 +0,0 @@
-# UI设计工作流参数清晰度分析报告
-
-## 📋 执行摘要
-
-**问题来源**：用户手动调用 `/workflow:ui-design:generate` 时传入了 `--style-variants 4`，但实际只有3个样式目录存在，导致生成了引用不存在CSS文件的 `style-4` 原型。
-
-**根本原因**：工作流命令链中参数命名不一致、验证缺失、文档说明不清晰。
-
-## 🔍 关键发现
-
-### 1. 参数命名不一致
-
-| 命令 | 参数名称 | 默认值 | 说明 |
-|------|---------|--------|------|
-| `extract` | `--variants` | 1 | ⚠️ 未在文档中明确说明默认值 |
-| `consolidate` | `--variants` | 所有变体 | ⚠️ 与extract同名但语义不同 |
-| `generate` | `--style-variants` | 3 | ⚠️ 名称不一致，默认值说明不清晰 |
-
-**问题**：
-- `extract` 和 `consolidate` 使用 `--variants`，但 `generate` 使用 `--style-variants`
-- `--variants` 在两个命令中含义不同：
-  - `extract`：生成多少个变体
-  - `consolidate`：处理多少个变体
-
-### 2. 命名转换混淆
-
-```
-extract 输出        → consolidate 处理      → generate 使用
-variant-1           → style-1/              → login-style-1-layout-1.html
-variant-2           → style-2/              → login-style-2-layout-1.html
-variant-3           → style-3/              → login-style-3-layout-1.html
-```
-
-**问题**：
-- `variant-N` 到 `style-N` 的转换没有文档说明
-- 增加了用户的认知负担
-- 容易造成混淆和错误
-
-### 3. 验证缺失
-
-#### ❌ 当前状态（generate.md 第79-82行）
-
-```bash
-# Phase 1: Path Resolution & Context Loading
-style_variants = --style-variants OR 3  # Default to 3
-VALIDATE: 1 <= style_variants <= 5
-```
-
-**问题**：
-- ✅ 验证范围（1-5）
-- ❌ 不验证是否匹配实际目录数量
-- ❌ 允许传入 `4` 但实际只有 `3` 个目录
-
-#### ✅ 应有的验证
-
-```bash
-style_variants = --style-variants OR 3
-actual_styles = count_directories({base_path}/style-consolidation/style-*)
-
-IF style_variants > actual_styles:
-    WARN: "Requested {style_variants} styles, but only {actual_styles} exist"
-    REPORT: "Auto-correcting to {actual_styles} style variants"
-    style_variants = actual_styles
-
-VALIDATE: 1 <= style_variants <= actual_styles
-```
-
-### 4. 文档清晰度问题
-
-#### extract.md
-
-**问题点**：
-- ⚠️ 默认值 `1` 未在 `usage` 或 `argument-hint` 中说明
-- ⚠️ 输出的 `variant-N` 命名未解释后续转换为 `style-N`
-
-**当前文档**（第580行附近）：
-```
-"id": "variant-2"  # 缺少说明这会成为 style-2 目录
-```
-
-#### consolidate.md
-
-**问题点**：
-- ⚠️ `--variants` 与 `extract` 同名但语义不同
-- ⚠️ 默认行为（处理所有变体）不够突出
-- ⚠️ `variant-N` → `style-N` 转换未文档化
-
-#### generate.md
-
-**问题点**：
-- ⚠️ `--style-variants` 名称与前置命令不一致
-- ⚠️ 默认值 `3` 的来源和意义不清晰
-- ⚠️ 自动检测机制未说明
-- ❌ 手动覆盖无验证
-
-**当前文档**（第79-82行）：
-```bash
-style_variants = --style-variants OR 3  # Default to 3
-VALIDATE: 1 <= style_variants <= 5
-```
-
-## 💡 改进方案
-
-### 方案1：代码层面改进（推荐）
-
-#### 1.1 统一参数命名
-
-```diff
-# extract.md
-- usage: /workflow:ui-design:extract [--variants <count>]
-+ usage: /workflow:ui-design:extract [--style-variants <count>]
-
-# consolidate.md
-- usage: /workflow:ui-design:consolidate [--variants <count>]
-+ usage: /workflow:ui-design:consolidate [--style-variants <count>]
-
-# generate.md (保持不变)
-  usage: /workflow:ui-design:generate [--style-variants <count>]
-```
-
-**优点**：
-- ✅ 全链路参数名称统一
-- ✅ 语义清晰（style-variants）
-- ✅ 降低混淆风险
-
-#### 1.2 添加验证逻辑（关键）
-
-##### generate.md 改进
-
-```bash
-# Phase 1: Path Resolution & Context Loading
-style_variants = --style-variants OR 3  # Default to 3
-
-# 🆕 添加验证逻辑
-actual_styles = count_directories({base_path}/style-consolidation/style-*)
-
-IF actual_styles == 0:
-    ERROR: "No style directories found in {base_path}/style-consolidation/"
-    SUGGEST: "Run /workflow:ui-design:consolidate first"
-    EXIT 1
-
-IF style_variants > actual_styles:
-    WARN: "⚠️ Requested {style_variants} style variants, but only {actual_styles} directories exist"
-    REPORT: "   Auto-correcting to {actual_styles} style variants"
-    REPORT: "   Available styles: {list_directories(style-consolidation/style-*)}"
-    style_variants = actual_styles
-
-VALIDATE: 1 <= style_variants <= actual_styles
-```
-
-##### ui-instantiate-prototypes.sh 改进
-
-在脚本第239行之后添加：
-
-```bash
-# Validate STYLE_VARIANTS matches actual directories
-if [ "$STYLE_VARIANTS" -gt 0 ]; then
-    actual_styles=$(find "$BASE_PATH/../style-consolidation" -maxdepth 1 -type d -name "style-*" 2>/dev/null | wc -l)
-
-    if [ "$actual_styles" -eq 0 ]; then
-        log_error "No style directories found in style-consolidation/"
-        log_info "Run /workflow:ui-design:consolidate first"
-        exit 1
-    fi
-
-    if [ "$STYLE_VARIANTS" -gt "$actual_styles" ]; then
-        log_warning "Requested $STYLE_VARIANTS style variants, but only found $actual_styles directories"
-        log_info "Auto-correcting to $actual_styles style variants"
-        STYLE_VARIANTS=$actual_styles
-    fi
-fi
-```
-
-#### 1.3 统一命名约定
-
-##### extract.md 改进
-
-修改输出格式（第580行附近）：
-
-```diff
-# style-cards.json 格式
-{
-  "style_cards": [
-    {
--     "id": "variant-1",
-+     "id": "style-1",
-      "name": "Modern Minimalist",
-      ...
-    }
-  ]
-}
-```
-
-### 方案2：文档层面改进
-
-#### 2.1 extract.md 文档改进
-
-```markdown
-## Parameters
-
-- `--style-variants <count>`: Number of style variants to extract. **Default: 1**
-  - Range: 1-5
-  - Each variant will become an independent design system (style-1, style-2, etc.)
-  - Output IDs use `style-N` format for consistency across the workflow
-
-## Output Format
-
-style-cards.json uses `style-N` IDs that directly correspond to directory names
-created by the consolidate command:
-
-- `style-1` → `style-consolidation/style-1/`
-- `style-2` → `style-consolidation/style-2/`
-```
-
-#### 2.2 consolidate.md 文档改进
-
-```markdown
-## Parameters
-
-- `--style-variants <count>`: Number of style variants to process from style-cards.json.
-  **Default: all available variants**
-  - Processes the first N variants from the style-cards array
-  - Creates separate `style-{n}` directories for each variant
-  - Range: 1 to count available in style-cards.json
-
-## Naming Convention
-
-Variants from extraction are materialized into style directories:
-- Input: `style-cards.json` with `style-1`, `style-2`, `style-3`
-- Output: `style-consolidation/style-1/`, `style-2/`, `style-3/` directories
-```
-
-#### 2.3 generate.md 文档改进
-
-```markdown
-## Parameters
-
-- `--style-variants <count>`: Number of style variants to generate prototypes for.
-  **Default: 3** (can be overridden)
-  - Range: 1-5
-  - ⚠️ **IMPORTANT**: This value MUST match the number of style-* directories in style-consolidation/
-  - If mismatched, the command will auto-correct to the actual directory count
-  - Use auto-detection (omit parameter) for safety
-
-## Auto-Detection vs Manual Override
-
-The command uses intelligent auto-detection:
-
-1. **Auto-Detection** (Recommended):
-   ```bash
-   /workflow:ui-design:generate --base-path ".workflow/.design/run-xxx"
-   # Automatically counts style-1/, style-2/, style-3/ → uses 3
-   ```
-
-2. **Manual Override** (Use with caution):
-   ```bash
-   /workflow:ui-design:generate --style-variants 4
-   # If only 3 styles exist, auto-corrects to 3 with warning
-   ```
-
-3. **Safety Check**:
-   - Command validates against actual `style-consolidation/style-*` directories
-   - Prevents generation of prototypes referencing non-existent styles
-   - Displays warning and auto-corrects if mismatch detected
-```
-
-### 方案3：用户指南改进
-
-创建 `.claude/commands/workflow/ui-design/README.md`：
-
-```markdown
-# UI Design Workflow Parameter Guide
-
-## Style Variant Count Flow
-
-### 1. Extract Phase
-```bash
-/workflow:ui-design:extract --style-variants 3
-# Generates: style-cards.json with 3 style variants (style-1, style-2, style-3)
-```
-
-### 2. Consolidate Phase
-```bash
-/workflow:ui-design:consolidate --style-variants 3
-# Creates: style-consolidation/style-1/, style-2/, style-3/
-```
-
-### 3. Generate Phase
-```bash
-# ✅ Recommended: Let it auto-detect
-/workflow:ui-design:generate --base-path ".workflow/.design/run-xxx"
-
-# ⚠️ Manual: Must match consolidation output
-/workflow:ui-design:generate --style-variants 3
-```
-
-## ⚠️ Common Mistakes
-
-### Mistake 1: Mismatched Counts
-```bash
-# ❌ Wrong: Request 4 styles when only 3 exist
-/workflow:ui-design:generate --style-variants 4
-# Only 3 directories in style-consolidation/ → ERROR
-
-# ✅ Correct: Omit parameter for auto-detection
-/workflow:ui-design:generate --base-path ".workflow/.design/run-xxx"
-```
-
-### Mistake 2: Naming Confusion
-```bash
-# ❌ Don't confuse variant-N with style-N
-# variant-N was old naming in style-cards.json
-# style-N is the current standard across all commands
-```
-
-## 🎯 Best Practices
-
-1. **Use auto-detection**: Omit `--style-variants` in generate command
-2. **Verify consolidation**: Check `consolidation-report.json` before generating
-3. **Use explore-auto**: Automated workflow prevents parameter mismatches
-4. **Check directories**: `ls .workflow/.design/run-xxx/style-consolidation/`
-```
-
-## 🎯 实施优先级
-
-### 🔴 高优先级（立即实施）
-
-1. **generate.md 添加验证逻辑**
-   - 防止参数不匹配问题再次发生
-   - 影响范围：所有手动调用 generate 命令的场景
-
-2. **ui-instantiate-prototypes.sh 添加验证**
-   - 脚本层面的最后防线
-   - 影响范围：所有原型生成操作
-
-3. **文档说明默认值和验证机制**
-   - 降低用户误用风险
-   - 影响范围：所有新用户和手动操作场景
-
-### 🟡 中优先级（短期改进）
-
-4. **统一参数命名为 --style-variants**
-   - 提高一致性，减少混淆
-   - 影响范围：需要更新多个命令文件
-
-5. **extract.md 统一使用 style-N 命名**
-   - 消除命名转换混淆
-   - 影响范围：需要更新 style-cards.json 格式
-
-### 🟢 低优先级（长期优化）
-
-6. **创建用户指南 README.md**
-   - 提供完整的参数使用指南
-   - 影响范围：文档层面，不影响功能
-
-## 📊 改进效果预测
-
-### 实施前
-
-```
-用户手动调用: /workflow:ui-design:generate --style-variants 4
-实际目录数: 3
-结果: ❌ 生成 login-style-4-layout-1.html 引用不存在的 CSS
-```
-
-### 实施后
-
-```
-用户手动调用: /workflow:ui-design:generate --style-variants 4
-实际目录数: 3
-
-验证检查:
-⚠️ Requested 4 style variants, but only 3 directories exist
-   Available: style-1, style-2, style-3
-   Auto-correcting to 3 style variants
-
-结果: ✅ 生成正确的 style-1, style-2, style-3 原型，避免错误
-```
-
-## 🔧 快速修复指南（针对当前问题）
-
-### 立即修复生成的错误文件
-
-```bash
-cd .workflow/.design/run-20251009-210559/prototypes
-
-# 删除错误的 style-4 文件
-rm -f *-style-4-*
-
-# 重新生成（使用自动检测）
-~/.claude/scripts/ui-instantiate-prototypes.sh . --session-id run-20251009-210559
-```
-
-### 预防未来错误
-
-```bash
-# ✅ 推荐：使用自动检测
-/workflow:ui-design:generate --base-path ".workflow/.design/run-xxx"
-
-# ⚠️ 如果必须手动指定，先验证
-jq '.variant_count' .workflow/.design/run-xxx/style-consolidation/consolidation-report.json
-# 输出: 3
-# 然后使用该数字
-/workflow:ui-design:generate --style-variants 3
-```
-
-## 📝 总结
-
-**核心问题**：
-- 参数命名不统一（`--variants` vs `--style-variants`）
-- 命名转换混淆（`variant-N` → `style-N`）
-- 验证缺失（不检查参数是否匹配实际目录）
-- 文档不清晰（默认值、自动检测机制说明不足）
-
-**关键改进**：
-1. ✅ 添加参数验证逻辑（防止不匹配）
-2. ✅ 统一参数命名（提高一致性）
-3. ✅ 完善文档说明（降低误用风险）
-4. ✅ 提供清晰的用户指南
-
-**预期效果**：
-- 🔒 杜绝参数不匹配问题
-- 📈 提高工作流鲁棒性
-- 🎓 降低用户学习成本
-- 🚀 提升整体用户体验