docs: restructure test-fix-gen workflow documentation

Reorganize documentation with improved structure and clarity:
- Add comprehensive dual-mode support (session vs prompt mode)
- Enhance usage examples with clear mode comparison
- Detail task specifications for IMPL-001 and IMPL-002
- Improve phase execution flow descriptions
- Add complete artifacts and output structure
- Expand best practices and related commands sections

The restructured documentation maintains backward compatibility while
making dual-mode functionality more discoverable and easier to use.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

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

@@ -284,10 +284,22 @@ codex exec "CONTINUE TO NEXT SUBTASK: ..." resume --last --skip-git-repo-check -
 1. Mark subtask as blocked in TodoWrite
 2. Report error details to user
 3. Pause execution for manual intervention
-4. User can choose to:
-   - Retry current subtask
-   - Continue to next subtask
-   - Abort entire task
+4. Use AskUserQuestion for recovery decision:
+
+```typescript
+AskUserQuestion({
+  questions: [{
+    question: "Codex execution failed for the subtask. How should the workflow proceed?",
+    header: "Recovery",
+    options: [
+      { label: "Retry Subtask", description: "Attempt to execute the same subtask again." },
+      { label: "Skip Subtask", description: "Continue to the next subtask in the plan." },
+      { label: "Abort Workflow", description: "Stop the entire execution." }
+    ],
+    multiSelect: false
+  }]
+})
+```
 
 **Git Verification Failure** (if --verify-git):
 1. Show unexpected changes

.claude/commands/cli/discuss-plan.md

@@ -121,9 +121,22 @@ Claude (orchestrating AI) synthesizes both outputs:
 ### 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
+2.  **Continue or Conclude**: Use AskUserQuestion to prompt user:
+
+```typescript
+AskUserQuestion({
+  questions: [{
+    question: "Round of discussion complete. What is the next step?",
+    header: "Next Round",
+    options: [
+      { label: "Start another round", description: "Continue the discussion to refine the plan further." },
+      { label: "Conclude and finalize", description: "End the discussion and save the final plan." }
+    ],
+    multiSelect: false
+  }]
+})
+```
+
 3.  **Loop or Finalize**:
     -   Continue → New round with Gemini analyzing latest synthesis
     -   Conclude → Save final synthesized document

.claude/commands/memory/docs.md

@@ -742,27 +742,15 @@ bash(
 
 ## Execution Commands
 
-### Full Mode (--mode full)
 ```bash
-# Level 1 - Module documentation (parallel)
-/workflow:execute IMPL-001
-/workflow:execute IMPL-002
-/workflow:execute IMPL-003
+# Execute entire workflow (auto-discovers active session)
+/workflow:execute
 
-# Level 2 - Project README (after Level 1)
-/workflow:execute IMPL-004
+# Or specify session
+/workflow:execute --resume-session="WFS-docs-yyyymmdd-hhmmss"
 
-# Level 3 - Architecture & Examples (after Level 2)
-/workflow:execute IMPL-005  # ARCHITECTURE.md + EXAMPLES.md
-/workflow:execute IMPL-006  # HTTP API (if present)
-```
-
-### Partial Mode (--mode partial)
-```bash
-# Only Level 1 tasks generated (module documentation)
-/workflow:execute IMPL-001
-/workflow:execute IMPL-002
-/workflow:execute IMPL-003
+# Individual task execution (if needed)
+/task:execute IMPL-001
 ```
 
 ## Simple Bash Commands

.claude/commands/task/breakdown.md

@@ -68,7 +68,21 @@ Define subtasks manually (remaining capacity: 4 tasks):
    - "User authentication" and "OAuth integration" both handle auth
    - Consider combining into single task
 
-Proceed with breakdown? (y/n): y
+# Use AskUserQuestion for confirmation
+AskUserQuestion({
+  questions: [{
+    question: "File conflicts and/or similar functionality detected. How do you want to proceed?",
+    header: "Confirm",
+    options: [
+      { label: "Proceed with breakdown", description: "Accept the risks and create the subtasks as defined." },
+      { label: "Restart breakdown", description: "Discard current subtasks and start over." },
+      { label: "Cancel breakdown", description: "Abort the operation and leave the parent task as is." }
+    ],
+    multiSelect: false
+  }]
+})
+
+User selected: "Proceed with breakdown"
 
 ✅ Task IMPL-1 broken down:
 ▸ IMPL-1: Build authentication module (container)

.claude/commands/task/replan.md

@@ -1,57 +1,95 @@
 ---
 name: replan
 description: Replan individual tasks with detailed user input and change tracking
-argument-hint: "task-id [\"text\"|file.md]"
+argument-hint: "task-id [\"text\"|file.md] | --batch [verification-report.md]"
+allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
 ---
 
 # Task Replan Command (/task:replan)
 
 ## Overview
-Replans individual tasks with multiple input options, change tracking, and version management.
+Replans individual tasks or batch processes multiple tasks with change tracking and backup management.
+
+**Modes**:
+- **Single Task Mode**: Replan one task with specific changes
+- **Batch Mode**: Process multiple tasks from action-plan verification report
 
 ## Core Principles
 **Task System:** @~/.claude/workflows/task-core.md
 
 ## Key Features
-- **Single-Task Focus**: Operates on individual tasks only
-- **Multiple Input Sources**: Text, files, or issue references
-- **Version Tracking**: Backup previous versions
+- **Single/Batch Operations**: Single task or multiple tasks from verification report
+- **Multiple Input Sources**: Text, files, or verification report
+- **Backup Management**: Automatic backup of previous versions
 - **Change Documentation**: Track all modifications
+- **Progress Tracking**: TodoWrite integration for batch operations
 
 ⚠️ **CRITICAL**: Validates active session before replanning
 
-## Input Sources
+## Operation Modes
 
-### Direct Text (Default)
+### Single Task Mode
+
+#### Direct Text (Default)
 ```bash
 /task:replan IMPL-1 "Add OAuth2 authentication support"
 ```
 
-### File-based Input
+#### File-based Input
 ```bash
 /task:replan IMPL-1 updated-specs.md
 ```
 Supports: .md, .txt, .json, .yaml
 
-### Interactive Mode
+#### Interactive Mode
 ```bash
 /task:replan IMPL-1 --interactive
 ```
 Guided step-by-step modification process with validation
 
+### Batch Mode
+
+#### From Verification Report
+```bash
+/task:replan --batch ACTION_PLAN_VERIFICATION.md
+```
+
+**Workflow**:
+1. Parse verification report to extract replan recommendations
+2. Create TodoWrite task list for all modifications
+3. Process each task sequentially with confirmation
+4. Track progress and generate summary report
+
+**Auto-detection**: If input file contains "Action Plan Verification Report" header, automatically enters batch mode
+
 ## Replanning Process
 
+### Single Task Process
+
 1. **Load & Validate**: Read task JSON and validate session
 2. **Parse Input**: Process changes from input source
-3. **Backup Version**: Create previous version backup
+3. **Create Backup**: Save previous version to backup folder
 4. **Update Task**: Modify JSON structure and relationships
 5. **Save Changes**: Write updated task and increment version
 6. **Update Session**: Reflect changes in workflow stats
 
-## Version Management
+### Batch Process
 
-### Version Tracking
-Tasks maintain version history:
+1. **Parse Verification Report**: Extract all replan recommendations
+2. **Initialize TodoWrite**: Create task list for tracking
+3. **For Each Task**:
+   - Mark todo as in_progress
+   - Load and validate task JSON
+   - Create backup
+   - Apply recommended changes
+   - Save updated task
+   - Mark todo as completed
+4. **Generate Summary**: Report all changes and backup locations
+
+## Backup Management
+
+### Backup Tracking
+Tasks maintain backup history:
 ```json
 {
   "id": "IMPL-1",
@@ -61,7 +99,8 @@ Tasks maintain version history:
       "version": "1.2",
       "reason": "Add OAuth2 support",
       "input_source": "direct_text",
-      "backup_location": ".task/versions/IMPL-1-v1.1.json"
+      "backup_location": ".task/backup/IMPL-1-v1.1.json",
+      "timestamp": "2025-10-17T10:30:00Z"
     }
   ]
 }
@@ -73,11 +112,15 @@ Tasks maintain version history:
 ```
 .task/
 ├── IMPL-1.json                    # Current version
-├── versions/
-│   └── IMPL-1-v1.1.json          # Previous backup
+├── backup/
+│   ├── IMPL-1-v1.0.json          # Original version
+│   ├── IMPL-1-v1.1.json          # Previous backup
+│   └── IMPL-1-v1.2.json          # Latest backup
 └── [new subtasks as needed]
 ```
 
+**Backup Naming**: `{task-id}-v{version}.json`
+
 ## Implementation Updates
 
 ### Change Detection
@@ -127,18 +170,68 @@ Updates workflow-session.json with:
 /task:replan IMPL-1 --rollback v1.1
 
 Rollback to version 1.1:
-- Restore task from backup
+- Restore task from backup/.../IMPL-1-v1.1.json
 - Remove new subtasks if any
 - Update session stats
 
-Confirm rollback? (y/n): y
+# Use AskUserQuestion for confirmation
+AskUserQuestion({
+  questions: [{
+    question: "Are you sure you want to roll back this task to a previous version?",
+    header: "Confirm",
+    options: [
+      { label: "Yes, rollback", description: "Restore the task from the selected backup." },
+      { label: "No, cancel", description: "Keep the current version of the task." }
+    ],
+    multiSelect: false
+  }]
+})
+
+User selected: "Yes, rollback"
 
 ✅ Task rolled back to version 1.1
 ```
 
+## Batch Processing with TodoWrite
+
+### Progress Tracking
+When processing multiple tasks, automatically creates TodoWrite task list:
+
+```markdown
+**Batch Replan Progress**:
+- [x] IMPL-002: Add FR-12 draft saving acceptance criteria
+- [x] IMPL-003: Add FR-14 history tracking acceptance criteria
+- [⧗] IMPL-004: Add FR-09 response surface explicit coverage
+- [ ] IMPL-008: Add NFR performance validation steps
+```
+
+### Batch Report
+After completion, generates summary:
+```markdown
+## Batch Replan Summary
+
+**Total Tasks**: 4
+**Successful**: 3
+**Failed**: 1
+**Skipped**: 0
+
+### Changes Made
+- IMPL-002 v1.0 → v1.1: Added FR-12 acceptance criteria
+- IMPL-003 v1.0 → v1.1: Added FR-14 acceptance criteria
+- IMPL-004 v1.0 → v1.1: Added FR-09 explicit coverage
+
+### Backups Created
+- .task/backup/IMPL-002-v1.0.json
+- .task/backup/IMPL-003-v1.0.json
+- .task/backup/IMPL-004-v1.0.json
+
+### Errors
+- IMPL-008: File not found (task may have been renamed)
+```
+
 ## Examples
 
-### Text Input
+### Single Task - Text Input
 ```bash
 /task:replan IMPL-1 "Add OAuth2 authentication support"
 
@@ -147,14 +240,27 @@ Proposed updates:
 + Add OAuth2 integration
 + Update authentication flow
 
-Apply changes? (y/n): y
+# Use AskUserQuestion for confirmation
+AskUserQuestion({
+  questions: [{
+    question: "Do you want to apply these changes to the task?",
+    header: "Apply",
+    options: [
+      { label: "Yes, apply", description: "Create new version with these changes." },
+      { label: "No, cancel", description: "Discard changes and keep current version." }
+    ],
+    multiSelect: false
+  }]
+})
+
+User selected: "Yes, apply"
 
 ✓ Version 1.2 created
 ✓ Context updated
-✓ Backup saved
+✓ Backup saved to .task/backup/IMPL-1-v1.1.json
 ```
 
-### File Input
+### Single Task - File Input
 ```bash
 /task:replan IMPL-2 requirements.md
 
@@ -163,14 +269,59 @@ Applying specification changes...
 
 ✓ Task updated with new requirements
 ✓ Version 1.1 created
+✓ Backup saved to .task/backup/IMPL-2-v1.0.json
+```
+
+### Batch Mode - From Verification Report
+```bash
+/task:replan --batch .workflow/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md
+
+Parsing verification report...
+Found 4 tasks requiring replanning:
+- IMPL-002: Add FR-12 draft saving acceptance criteria
+- IMPL-003: Add FR-14 history tracking acceptance criteria
+- IMPL-004: Add FR-09 response surface explicit coverage
+- IMPL-008: Add NFR performance validation steps
+
+Creating task tracking list...
+
+Processing IMPL-002...
+✓ Backup created: .task/backup/IMPL-002-v1.0.json
+✓ Updated to v1.1
+
+Processing IMPL-003...
+✓ Backup created: .task/backup/IMPL-003-v1.0.json
+✓ Updated to v1.1
+
+Processing IMPL-004...
+✓ Backup created: .task/backup/IMPL-004-v1.0.json
+✓ Updated to v1.1
+
+Processing IMPL-008...
+✓ Backup created: .task/backup/IMPL-008-v1.0.json
+✓ Updated to v1.1
+
+✅ Batch replan completed: 4/4 successful
+📋 Summary report saved
+```
+
+### Batch Mode - Auto-detection
+```bash
+# If file contains "Action Plan Verification Report", auto-enters batch mode
+/task:replan ACTION_PLAN_VERIFICATION.md
+
+Detected verification report format
+Entering batch mode...
+[same as above]
 ```
 
 ## Error Handling
 
+### Single Task Errors
 ```bash
 # Task not found
 ❌ Task IMPL-5 not found
-→ Check task ID with /context
+→ Check task ID with /workflow:status
 
 # Task completed
 ⚠️ Task IMPL-1 is completed (cannot replan)
@@ -182,12 +333,112 @@ Applying specification changes...
 
 # No input provided
 ❌ Please specify changes needed
-→ Provide text, file, or issue reference
+→ Provide text, file, or verification report
+```
+
+### Batch Mode Errors
+```bash
+# Invalid verification report
+❌ File does not contain valid verification report format
+→ Check report structure or use single task mode
+
+# Partial failures
+⚠️ Batch completed with errors: 3/4 successful
+→ Review error details in summary report
+
+# No replan recommendations found
+❌ Verification report contains no replan recommendations
+→ Check report content or use /workflow:action-plan-verify first
+```
+
+## Batch Mode Integration
+
+### Input Format Expectations
+Batch mode parses verification reports looking for:
+
+1. **Required Actions Section**: Commands like `/task:replan IMPL-X "changes"`
+2. **Findings Table**: Task IDs with recommendations
+3. **Next Actions Section**: Specific replan commands
+
+**Example Patterns**:
+```markdown
+#### 1. HIGH Priority - Address FR Coverage Gaps
+/task:replan IMPL-004 "
+Add explicit acceptance criteria:
+- FR-09: Response surface 3D visualization
+"
+
+#### 2. MEDIUM Priority - Enhance NFR Coverage
+/task:replan IMPL-008 "
+Add performance testing:
+- NFR-01: Load test API endpoints
+"
+```
+
+### Extraction Logic
+1. Scan for `/task:replan` commands in report
+2. Extract task ID and change description
+3. Group by priority (HIGH, MEDIUM, LOW)
+4. Process in priority order with TodoWrite tracking
+
+### Confirmation Behavior
+- **Default**: Confirm each task before applying
+- **With `--auto-confirm`**: Apply all changes without prompting
+  ```bash
+  /task:replan --batch report.md --auto-confirm
+  ```
+
+## Implementation Details
+
+### Backup Management
+```typescript
+// Backup file naming convention
+const backupPath = `.task/backup/${taskId}-v${previousVersion}.json`;
+
+// Backup metadata in task JSON
+{
+  "replan_history": [
+    {
+      "version": "1.2",
+      "timestamp": "2025-10-17T10:30:00Z",
+      "reason": "Add FR-09 explicit coverage",
+      "input_source": "batch_verification_report",
+      "backup_location": ".task/backup/IMPL-004-v1.1.json"
+    }
+  ]
+}
+```
+
+### TodoWrite Integration
+```typescript
+// Initialize tracking for batch mode
+TodoWrite({
+  todos: taskList.map(task => ({
+    content: `${task.id}: ${task.changeDescription}`,
+    status: "pending",
+    activeForm: `Replanning ${task.id}`
+  }))
+});
+
+// Update progress during processing
+TodoWrite({
+  todos: updateTaskStatus(taskId, "in_progress")
+});
+
+// Mark completed
+TodoWrite({
+  todos: updateTaskStatus(taskId, "completed")
+});
 ```
 
 ## Related Commands
 
-- `/context` - View updated task structure
+- `/workflow:status` - View task structure and versions
+- `/workflow:action-plan-verify` - Generate verification report for batch mode
 - `/task:execute` - Execute replanned task
 - `/task:create` - Create new tasks
-- `/workflow:action-plan` - For workflow-wide changes
+- `/task:breakdown` - Break down complex tasks
+
+## Context
+
+$ARGUMENTS

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

@@ -307,48 +307,73 @@ Output a Markdown report (no file writes) with the following structure:
 
 ### Next Actions
 
-#### If CRITICAL Issues Exist (Current Status: 2 CRITICAL)
-**Recommendation**: ❌ **BLOCK EXECUTION** - Resolve CRITICAL issues before proceeding
+#### Action Recommendations
 
-**Required Actions**:
-1. **CRITICAL**: Add authentication implementation tasks to cover FR-03
-2. **CRITICAL**: Add performance optimization tasks to cover NFR-01
+**If CRITICAL Issues Exist**:
+- ❌ **BLOCK EXECUTION** - Resolve critical issues before proceeding
+- Use `/task:create` for missing requirements coverage
+- Fix broken dependencies and circular references
 
-#### If Only HIGH/MEDIUM/LOW Issues
-**Recommendation**: ⚠️ **PROCEED WITH CAUTION** - Issues are non-blocking but should be addressed
+**If Only HIGH/MEDIUM/LOW Issues**:
+- ⚠️ **PROCEED WITH CAUTION** - Fix high-priority issues first
+- Use batch replan mode to apply all task improvements systematically
 
-**Suggested Improvements**:
-1. Add context.artifacts references to all tasks (use /task:replan)
-2. Fix broken dependency IMPL-2.3 → IMPL-2.4
-3. Add flow_control.target_files to underspecified tasks
+#### Batch Remediation
 
-#### Command Suggestions
+**Report Location**: `.workflow/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md`
+
+**Apply All Task Improvements** (Recommended):
 ```bash
-# Fix critical coverage gaps
+# Batch process all task replan recommendations
+/task:replan --batch .workflow/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md
+
+# Or with auto-confirmation (no prompts)
+/task:replan --batch ACTION_PLAN_VERIFICATION.md --auto-confirm
+```
+
+**Manual Selective Fixes**:
+```bash
+# Fix critical coverage gaps first
 /task:create "Implement user authentication (FR-03)"
 /task:create "Add performance optimization (NFR-01)"
 
-# Refine existing tasks
+# Then apply task refinements individually
 /task:replan IMPL-1.2 "Add context.artifacts and target_files"
-
-# Update IMPL_PLAN if architecture drift detected
-# (Manual edit required)
-```
 ```
 
-### 7. Provide Remediation Options
+**Notes**:
+- Batch mode extracts all `/task:replan` commands from report
+- Processes by priority: CRITICAL → HIGH → MEDIUM → LOW
+- Creates TodoWrite tracking for all modifications
+- Architecture drift in IMPL_PLAN requires manual editing
+```
 
-At end of report, ask the user:
+### 7. Save Report and Provide Remediation Options
+
+**Save Analysis Report**:
+```bash
+report_path = ".workflow/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md"
+Write(report_path, full_report_content)
+```
+
+At end of report, provide batch remediation guidance:
 
 ```markdown
 ### 🔧 Remediation Options
 
-Would you like me to:
-1. **Generate task suggestions** for unmapped requirements (no auto-creation)
-2. **Provide specific edit commands** for top N issues (you execute manually)
-3. **Create remediation checklist** for systematic fixing
+**Recommended Workflow**:
+1. **Batch Mode** (Fastest): Apply all task improvements automatically
+   ```bash
+   /task:replan --batch .workflow/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md
+   ```
 
-(Do NOT apply fixes automatically - this is read-only analysis)
+2. **Manual Review**: Examine each issue before applying
+   - Review findings in this report
+   - Execute specific `/task:create` or `/task:replan` commands individually
+
+3. **Architecture Changes**: Update IMPL_PLAN.md manually if architecture drift detected
+
+**Note**: This is read-only analysis. All fixes require explicit execution.
 ```
 
 ### 8. Update Session Metadata

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

@@ -1,7 +1,7 @@
 ---
 name: auto-parallel
 description: Parallel brainstorming automation with dynamic role selection and concurrent execution
-argument-hint: "topic or challenge description"
+argument-hint: "topic or challenge description" [--count N]
 allowed-tools: SlashCommand(*), Task(*), TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*)
 ---
 
@@ -9,9 +9,13 @@ allowed-tools: SlashCommand(*), Task(*), TodoWrite(*), Read(*), Write(*), Bash(*
 
 ## Usage
 ```bash
-/workflow:brainstorm:auto-parallel "<topic>"
+/workflow:brainstorm:auto-parallel "<topic>" [--count N]
 ```
 
+**Parameters**:
+- `topic` (required): Topic or challenge description
+- `--count N` (optional): Number of roles to auto-select (default: 3, max: 9)
+
 ## Role Selection Logic
 - **Technical & Architecture**: `architecture|system|performance|database|security` → system-architect, data-architect, security-expert, subject-matter-expert
 - **API & Backend**: `api|endpoint|rest|graphql|backend|interface|contract|service` → api-designer, system-architect, data-architect
@@ -19,8 +23,9 @@ allowed-tools: SlashCommand(*), Task(*), TodoWrite(*), Read(*), Write(*), Bash(*
 - **Business & Process**: `business|process|workflow|cost|innovation|testing` → business-analyst, innovation-lead, test-strategist
 - **Agile & Delivery**: `agile|sprint|scrum|team|collaboration|delivery` → scrum-master, product-owner
 - **Domain Expertise**: `domain|standard|compliance|expertise|regulation` → subject-matter-expert
-- **Multi-role**: Complex topics automatically select 2-3 complementary roles
+- **Multi-role**: Complex topics automatically select N complementary roles (N specified by --count, default 3)
 - **Default**: `product-manager` if no clear match
+- **Count Parameter**: `--count N` determines number of roles to auto-select (default: 3, max: 9)
 
 **Template Loading**: `bash($(cat "~/.claude/workflows/cli-templates/planning-roles/<role-name>.md"))`
 **Template Source**: `.claude/workflows/cli-templates/planning-roles/`
@@ -38,8 +43,8 @@ bash($(cat "~/.claude/workflows/cli-templates/planning-roles/ui-designer.md"))
 The command follows a structured three-phase approach with dedicated document types:
 
 **Phase 1: Framework Generation** ⚠️ COMMAND EXECUTION
-- **Role selection**: Auto-select 2-3 roles based on topic keywords (see Role Selection Logic)
-- **Call artifacts command**: Execute `/workflow:brainstorm:artifacts "{topic}" --roles "{role1,role2,role3}"` using SlashCommand tool
+- **Role selection**: Auto-select N roles based on topic keywords and --count parameter (default: 3, see Role Selection Logic)
+- **Call artifacts command**: Execute `/workflow:brainstorm:artifacts "{topic}" --roles "{role1,role2,...,roleN}"` using SlashCommand tool
 - **Role-specific framework**: Generate framework with sections tailored to selected roles
 
 **Phase 2: Role Analysis Execution** ⚠️ PARALLEL AGENT ANALYSIS
@@ -58,8 +63,8 @@ The command follows a structured three-phase approach with dedicated document ty
 Auto command coordinates independent specialized commands:
 
 **Command Sequence**:
-1. **Role Selection**: Auto-select 2-3 relevant roles based on topic keywords
-2. **Generate Role-Specific Framework**: Use SlashCommand to execute `/workflow:brainstorm:artifacts "{topic}" --roles "{role1,role2,role3}"`
+1. **Role Selection**: Auto-select N relevant roles based on topic keywords and --count parameter (default: 3)
+2. **Generate Role-Specific Framework**: Use SlashCommand to execute `/workflow:brainstorm:artifacts "{topic}" --roles "{role1,role2,...,roleN}"`
 3. **Parallel Role Analysis**: Execute selected role agents in parallel, each reading their specific framework section
 4. **Generate Synthesis**: Use SlashCommand to execute `/workflow:brainstorm:synthesis`
 
@@ -75,7 +80,29 @@ Auto command coordinates independent specialized commands:
 - **Product & UX**: `user|ui|ux|interface|design|product|feature|experience` → ui-designer, ux-expert, product-manager, product-owner
 - **Agile & Delivery**: `agile|sprint|scrum|team|collaboration|delivery` → scrum-master, product-owner
 - **Domain Expertise**: `domain|standard|compliance|expertise|regulation` → subject-matter-expert
-- **Auto-select**: 2-3 most relevant roles based on topic analysis
+- **Auto-select**: N most relevant roles based on topic analysis (N from --count parameter, default: 3)
+
+### Parameter Parsing
+
+**Count Parameter Handling**:
+```bash
+# Parse --count parameter from user input
+IF user_input CONTAINS "--count":
+    EXTRACT count_value FROM "--count N" pattern
+    IF count_value > 9:
+        count_value = 9  # Cap at maximum 9 roles
+    END IF
+ELSE:
+    count_value = 3  # Default to 3 roles
+END IF
+```
+
+**Role Selection with Count**:
+1. **Analyze topic keywords**: Identify relevant role categories
+2. **Rank roles by relevance**: Score based on keyword matches
+3. **Select top N roles**: Pick N most relevant roles (N = count_value)
+4. **Ensure diversity**: Balance across different expertise areas
+5. **Minimum guarantee**: Always include at least one role (default to product-manager if no matches)
 
 ### Simplified Processing Standards
 
@@ -87,7 +114,7 @@ Auto command coordinates independent specialized commands:
 5. **TodoWrite control** - Progress tracking throughout all phases
 
 **Implementation Rules**:
-- **Maximum 3 roles**: Auto-selected based on simple keyword mapping
+- **Role count**: N roles auto-selected based on --count parameter (default: 3, max: 9) and keyword mapping
 - **No upfront validation**: Agents handle their own context requirements
 - **Parallel execution**: Each agent operates concurrently without dependencies
 - **Synthesis at end**: Integration only after all agents complete
@@ -180,18 +207,22 @@ Task(subagent_type="conceptual-planning-agent",
 
 ### Parallel Role Agent调用示例
 ```bash
-# Execute multiple roles in parallel using single message with multiple Task calls
-Task(subagent_type="conceptual-planning-agent",
-     prompt="Execute brainstorming analysis: system-architect perspective for {topic}...",
-     description="Execute system-architect brainstorming analysis")
+# Execute N roles in parallel using single message with multiple Task calls
+# (N determined by --count parameter, default 3, shown below with 3 roles as example)
 
 Task(subagent_type="conceptual-planning-agent",
-     prompt="Execute brainstorming analysis: ui-designer perspective for {topic}...",
-     description="Execute ui-designer brainstorming analysis")
+     prompt="Execute brainstorming analysis: {role-1} perspective for {topic}...",
+     description="Execute {role-1} brainstorming analysis")
 
 Task(subagent_type="conceptual-planning-agent",
-     prompt="Execute brainstorming analysis: security-expert perspective for {topic}...",
-     description="Execute security-expert brainstorming analysis")
+     prompt="Execute brainstorming analysis: {role-2} perspective for {topic}...",
+     description="Execute {role-2} brainstorming analysis")
+
+Task(subagent_type="conceptual-planning-agent",
+     prompt="Execute brainstorming analysis: {role-3} perspective for {topic}...",
+     description="Execute {role-3} brainstorming analysis")
+
+# ... repeat for remaining N-3 roles if --count > 3
 ```
 
 ### Direct Synthesis Process (Command-Driven)
@@ -213,9 +244,9 @@ TodoWrite({
       activeForm: "Initializing brainstorming session"
     },
     {
-      content: "Select roles based on topic keyword analysis",
+      content: "Parse --count parameter and select N roles based on topic keyword analysis",
       status: "pending",
-      activeForm: "Selecting roles for brainstorming analysis"
+      activeForm: "Parsing parameters and selecting roles for brainstorming"
     },
     {
       content: "Execute artifacts command with selected roles for role-specific framework",
@@ -232,6 +263,12 @@ TodoWrite({
       status: "pending",
       activeForm: "Executing [role-2] structured framework analysis"
     },
+    // ... repeat for N roles (N determined by --count parameter, default 3)
+    {
+      content: "Execute [role-N] analysis [conceptual-planning-agent] [FLOW_CONTROL] addressing framework",
+      status: "pending",
+      activeForm: "Executing [role-N] structured framework analysis"
+    },
     {
       content: "Execute synthesis command using SlashCommand for final integration",
       status: "pending",
@@ -257,24 +294,25 @@ TodoWrite({
   ]
 });
 
-// Phase 3: Parallel agent execution tracking
+// Phase 3: Parallel agent execution tracking (N roles, N from --count parameter)
 TodoWrite({
   todos: [
     // ... previous completed tasks
     {
-      content: "Execute system-architect analysis [conceptual-planning-agent] [FLOW_CONTROL]",
+      content: "Execute [role-1] analysis [conceptual-planning-agent] [FLOW_CONTROL]",
       status: "in_progress",  // Executing in parallel
-      activeForm: "Executing system-architect brainstorming analysis"
+      activeForm: "Executing [role-1] brainstorming analysis"
     },
     {
-      content: "Execute ui-designer analysis [conceptual-planning-agent] [FLOW_CONTROL]",
+      content: "Execute [role-2] analysis [conceptual-planning-agent] [FLOW_CONTROL]",
       status: "in_progress",  // Executing in parallel
-      activeForm: "Executing ui-designer brainstorming analysis"
+      activeForm: "Executing [role-2] brainstorming analysis"
     },
+    // ... repeat for remaining N-2 roles
     {
-      content: "Execute security-expert analysis [conceptual-planning-agent] [FLOW_CONTROL]",
+      content: "Execute [role-N] analysis [conceptual-planning-agent] [FLOW_CONTROL]",
       status: "in_progress",  // Executing in parallel
-      activeForm: "Executing security-expert brainstorming analysis"
+      activeForm: "Executing [role-N] brainstorming analysis"
     }
   ]
 });

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

@@ -1,8 +1,8 @@
 ---
 name: synthesis
-description: Generate synthesis-specification.md from topic-framework and role analyses with @ references
+description: Generate synthesis-specification.md from topic-framework and role analyses with @ references using conceptual-planning-agent
 argument-hint: "no arguments required - synthesizes existing framework and role analyses"
-allowed-tools: Read(*), Write(*), TodoWrite(*), Glob(*)
+allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
 
 ## 🧩 **Synthesis Document Generator**
@@ -29,15 +29,29 @@ allowed-tools: Read(*), Write(*), TodoWrite(*), Glob(*)
 
 ## ⚙️ **Execution Protocol**
 
-### ⚠️ Direct Execution by Main Claude
-**Execution Model**: Main Claude directly executes this command without delegating to sub-agents.
+### ⚠️ Agent Execution with Flow Control
+**Execution Model**: Uses conceptual-planning-agent for synthesis generation with structured file loading.
 
 **Rationale**:
-- **Full Context Access**: Avoids context transmission loss that occurs with Task tool delegation
-- **Complex Cognitive Analysis**: Leverages main Claude's complete reasoning capabilities for cross-role synthesis
-- **Tool Usage**: Combines Read/Write/Glob tools with main Claude's analytical intelligence
+- **Autonomous Execution**: Agent independently loads and processes all required documents
+- **Flow Control**: Structured document loading ensures systematic analysis
+- **Complex Cognitive Analysis**: Leverages agent's analytical capabilities for cross-role synthesis
+- **Conceptual Focus**: Agent specializes in conceptual analysis and multi-perspective integration
 
-**DO NOT use Task tool** - Main Claude performs intelligent analysis directly while reading/writing files, ensuring no information loss from context passing.
+**Agent Responsibility**: All file reading and synthesis generation performed by conceptual-planning-agent with FLOW_CONTROL instructions.
+
+### 📋 Task Tracking Protocol
+Initialize synthesis task tracking using TodoWrite at command start:
+```json
+[
+  {"content": "Detect active session and validate topic-framework.md existence", "status": "in_progress", "activeForm": "Detecting session and validating framework"},
+  {"content": "Discover participating role analyses dynamically", "status": "pending", "activeForm": "Discovering role analyses"},
+  {"content": "Check existing synthesis and confirm user action", "status": "pending", "activeForm": "Checking update mechanism"},
+  {"content": "Execute synthesis generation using conceptual-planning-agent with FLOW_CONTROL", "status": "pending", "activeForm": "Executing agent-based synthesis generation"},
+  {"content": "Agent performs cross-role analysis and generates synthesis-specification.md", "status": "pending", "activeForm": "Agent analyzing and generating synthesis"},
+  {"content": "Update workflow-session.json with synthesis completion status", "status": "pending", "activeForm": "Updating session metadata"}
+]
+```
 
 ### Phase 1: Document Discovery & Validation
 ```bash
@@ -102,79 +116,104 @@ ELSE:
     CREATE new synthesis
 ```
 
-### Phase 4: Synthesis Generation Process
-Initialize synthesis task tracking:
-```json
-[
-  {"content": "Validate topic-framework.md and role analyses availability", "status": "in_progress", "activeForm": "Validating source documents"},
-  {"content": "Load topic framework discussion points structure", "status": "pending", "activeForm": "Loading framework structure"},
-  {"content": "Cross-analyze role responses to each framework point", "status": "pending", "activeForm": "Cross-analyzing framework responses"},
-  {"content": "Generate synthesis-specification.md with @ references", "status": "pending", "activeForm": "Generating synthesis with references"},
-  {"content": "Update session metadata with synthesis completion", "status": "pending", "activeForm": "Updating session metadata"}
-]
-```
+### Phase 4: Agent Execution with Flow Control
+**Synthesis Generation using conceptual-planning-agent**
 
-### Phase 5: Cross-Role Analysis Execution
+Delegate synthesis generation to conceptual-planning-agent with structured file loading:
 
-**Dynamic Role Processing**: The number and types of roles are determined at runtime based on actual analysis.md files discovered in Phase 2.
+```bash
+Task(conceptual-planning-agent): "
+[FLOW_CONTROL]
 
-#### 5.1 Data Collection and Preprocessing
-```pseudo
-# Iterate over dynamically discovered role analyses
-FOR each discovered_role IN participating_roles:
-    role_directory = brainstorm_dir + "/" + discovered_role
+Execute comprehensive synthesis generation from topic framework and role analyses
 
-    # Load role analysis (required)
-    role_analysis = Read(role_directory + "/analysis.md")
+## Context Loading
+OUTPUT_FILE: synthesis-specification.md
+OUTPUT_PATH: .workflow/WFS-{session}/.brainstorming/synthesis-specification.md
+SESSION_ID: {session_id}
+ANALYSIS_MODE: cross_role_synthesis
 
-    # Load optional artifacts if present
-    IF EXISTS(role_directory + "/recommendations.md"):
-        role_recommendations[discovered_role] = Read(role_directory + "/recommendations.md")
-    END IF
+## Flow Control Steps
+1. **load_topic_framework**
+   - Action: Load structured topic discussion framework
+   - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
+   - Output: topic_framework_content
 
-    # Extract insights from analysis
-    role_insights[discovered_role] = extract_key_insights(role_analysis)
-    role_recommendations[discovered_role] = extract_recommendations(role_analysis)
-    role_concerns[discovered_role] = extract_concerns_risks(role_analysis)
-    role_diagrams[discovered_role] = identify_diagrams_and_visuals(role_analysis)
-END FOR
+2. **discover_role_analyses**
+   - Action: Dynamically discover all participating role analysis files
+   - Command: Glob(.workflow/WFS-{session}/.brainstorming/*/analysis.md)
+   - Output: role_analysis_paths, participating_roles
 
-# Log participating roles for metadata
-participating_role_count = COUNT(participating_roles)
-participating_role_names = participating_roles
-```
+3. **load_role_analyses**
+   - Action: Load all discovered role analysis documents
+   - Command: Read(each path from role_analysis_paths)
+   - Output: role_analyses_content
 
-#### 5.2 Cross-Role Insight Analysis
-```pseudo
-# Consensus identification (across all participating roles)
-consensus_areas = identify_common_themes(role_insights)
-agreement_matrix = create_agreement_matrix(role_recommendations)
+4. **check_existing_synthesis**
+   - Action: Check if synthesis-specification.md already exists
+   - Command: Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md) [if exists]
+   - Output: existing_synthesis_content [optional]
 
-# Disagreement analysis (track which specific roles disagree)
-disagreement_areas = identify_conflicting_views(role_insights)
-tension_points = analyze_role_conflicts(role_recommendations)
-FOR each conflict IN disagreement_areas:
-    conflict.dissenting_roles = identify_dissenting_roles(conflict)
-END FOR
+5. **load_session_metadata**
+   - Action: Load session metadata and context
+   - Command: Read(.workflow/WFS-{session}/workflow-session.json)
+   - Output: session_context
 
-# Innovation opportunity extraction
-innovation_opportunities = extract_breakthrough_ideas(role_insights)
-synergy_opportunities = identify_cross_role_synergies(role_insights)
-```
+6. **load_synthesis_template**
+   - Action: Load synthesis role template for structure and guidelines
+   - Command: Read(~/.claude/workflows/cli-templates/planning-roles/synthesis-role.md)
+   - Output: synthesis_template_guidelines
 
-#### 5.3 Priority and Decision Matrix Generation
-```pseudo
-# Create comprehensive evaluation matrix
-FOR each recommendation:
-    impact_score = calculate_business_impact(recommendation, role_insights)
-    feasibility_score = calculate_technical_feasibility(recommendation, role_insights)
-    effort_score = calculate_implementation_effort(recommendation, role_insights)
-    risk_score = calculate_associated_risks(recommendation, role_insights)
-    
-    priority_score = weighted_score(impact_score, feasibility_score, effort_score, risk_score)
-END FOR
+## Synthesis Requirements
 
-SORT recommendations BY priority_score DESC
+### Core Integration
+**Cross-Role Analysis**: Integrate all discovered role analyses with comprehensive coverage
+**Framework Integration**: Address how each role responded to topic-framework.md discussion points
+**Decision Transparency**: Document both adopted solutions and rejected alternatives with rationale
+**Process Integration**: Include team capability gaps, process risks, and collaboration patterns
+**Visual Documentation**: Include key diagrams (architecture, data model, user journey) via Mermaid
+**Priority Matrix**: Create quantified recommendation matrix with multi-dimensional evaluation
+**Actionable Plan**: Provide phased implementation roadmap with clear next steps
+
+### Cross-Role Analysis Process (Agent Internal Execution)
+Perform systematic cross-role analysis following these steps:
+
+1. **Data Collection**: Extract key insights, recommendations, concerns, and diagrams from each discovered role analysis
+2. **Consensus Identification**: Identify common themes and agreement areas across all participating roles
+3. **Disagreement Analysis**: Document conflicting views and track which specific roles disagree on each point
+4. **Innovation Extraction**: Identify breakthrough ideas and cross-role synergy opportunities
+5. **Priority Scoring**: Calculate multi-dimensional priority scores (impact, feasibility, effort, risk) for each recommendation
+6. **Decision Matrix**: Create comprehensive evaluation matrix and sort recommendations by priority
+
+## Synthesis Quality Standards
+Follow synthesis-specification.md structure defined in synthesis-role.md template:
+- Use template structure for comprehensive document organization
+- Apply analysis guidelines for cross-role synthesis process
+- Include all required sections from template (Executive Summary, Key Designs, Requirements, etc.)
+- Follow @ reference system for traceability to source role analyses
+- Apply quality standards from template (completeness, visual clarity, decision transparency)
+- Validate output against template's output validation checklist
+
+## Expected Deliverables
+1. **synthesis-specification.md**: Complete integrated specification consolidating all role perspectives
+2. **@ References**: Include cross-references to source role analyses
+3. **Session Metadata Update**: Update workflow-session.json with synthesis completion status
+
+## Completion Criteria
+- All discovered role analyses integrated without gaps
+- Framework discussion points addressed across all roles
+- Controversial points documented with dissenting roles identified
+- Process concerns (team capabilities, risks, collaboration) captured
+- Quantified priority recommendations with evaluation criteria
+- Actionable implementation plan with phased approach
+- Comprehensive risk assessment with mitigation strategies
+
+## Execution Notes
+- Dynamic role participation: Only synthesize roles that produced analysis.md files
+- Update mechanism: If synthesis exists, prompt user for regenerate/update/preserve decision
+- Timeout allocation: Complex synthesis task (60-90 min recommended)
+- Reference @intelligent-tools-strategy.md for timeout guidelines
+"
 ```
 
 ## 📊 **Output Specification**
@@ -189,153 +228,22 @@ The synthesis process creates **one consolidated document** that integrates all
 └── synthesis-specification.md  # ★ OUTPUT: Complete integrated specification
 ```
 
-#### synthesis-specification.md Structure (Complete Specification)
+#### synthesis-specification.md Structure
 
 **Document Purpose**: Defines **"WHAT"** to build - comprehensive requirements and design blueprint.
 **Scope**: High-level features, requirements, and design specifications. Does NOT include executable task breakdown (that's IMPL_PLAN.md's responsibility).
 
-```markdown
-# [Topic] - Integrated Implementation Specification
+**Template Reference**: Complete document structure and content guidelines available in `synthesis-role.md` template, including:
+- Executive Summary with strategic overview
+- Key Designs & Decisions (architecture diagrams, ADRs, user journeys)
+- Controversial Points & Alternatives (decision transparency)
+- Requirements & Acceptance Criteria (Functional, Non-Functional, Business)
+- Design Specifications (UI/UX, Architecture, Domain Expertise)
+- Process & Collaboration Concerns (team skills, risks, patterns, constraints)
+- Implementation Roadmap (high-level phases)
+- Risk Assessment & Mitigation strategies
 
-**Framework Reference**: @topic-framework.md | **Generated**: [timestamp] | **Session**: WFS-[topic-slug]
-**Source Integration**: All brainstorming role perspectives consolidated
-**Document Type**: Requirements & Design Specification (WHAT to build)
-
-## Executive Summary
-Strategic overview with key insights, breakthrough opportunities, and implementation priorities.
-
-## Key Designs & Decisions
-### Core Architecture Diagram
-```mermaid
-graph TD
-    A[Component A] --> B[Component B]
-    B --> C[Component C]
-```
-*Reference: @system-architect/analysis.md#architecture-diagram*
-
-### User Journey Map
-![User Journey](./assets/user-journey.png)
-*Reference: @ux-expert/analysis.md#user-journey*
-
-### Data Model Overview
-```mermaid
-erDiagram
-    USER ||--o{ ORDER : places
-    ORDER ||--|{ LINE-ITEM : contains
-```
-*Reference: @data-architect/analysis.md#data-model*
-
-### Architecture Decision Records (ADRs)
-**ADR-01: [Decision Title]**
-- **Context**: Background and problem statement
-- **Decision**: Chosen approach
-- **Rationale**: Why this approach was selected
-- **Reference**: @system-architect/analysis.md#adr-01
-
-## Controversial Points & Alternatives
-| Point | Adopted Solution | Alternative Solution(s) | Decision Rationale | Dissenting Roles |
-|-------|------------------|-------------------------|--------------------| -----------------|
-| Authentication | JWT Token (@security-expert) | Session-Cookie (@system-architect) | Stateless API support for multi-platform | System Architect noted session performance benefits |
-| UI Framework | React (@ui-designer) | Vue.js (@subject-matter-expert) | Team expertise and ecosystem maturity | Subject Matter Expert preferred Vue for learning curve |
-
-*This section preserves decision context and rejected alternatives for future reference.*
-
-## Requirements & Acceptance Criteria
-### Functional Requirements
-| ID | Description | Rationale Summary | Source | Priority | Acceptance | Dependencies |
-|----|-------------|-------------------|--------|----------|------------|--------------|
-| FR-01 | User authentication | Enable secure multi-platform access | @product-manager/analysis.md | High | User can login via email/password | None |
-| FR-02 | Data export | User-requested analytics feature | @product-owner/analysis.md | Medium | Export to CSV/JSON | FR-01 |
-
-### Non-Functional Requirements
-| ID | Description | Rationale Summary | Target | Validation | Source |
-|----|-------------|-------------------|--------|------------|--------|
-| NFR-01 | Response time | UX research shows <200ms critical | <200ms | Load testing | @ux-expert/analysis.md |
-| NFR-02 | Data encryption | Compliance requirement | AES-256 | Security audit | @security-expert/analysis.md |
-
-### Business Requirements
-| ID | Description | Rationale Summary | Value | Success Metric | Source |
-|----|-------------|-------------------|-------|----------------|--------|
-| BR-01 | User retention | Market analysis shows engagement gap | High | 80% 30-day retention | @product-manager/analysis.md |
-| BR-02 | Revenue growth | Business case justification | High | 25% MRR increase | @product-owner/analysis.md |
-
-## Design Specifications
-### UI/UX Guidelines
-**Consolidated from**: @ui-designer/analysis.md, @ux-expert/analysis.md
-- Component specifications and interaction patterns
-- Visual design system and accessibility requirements
-- User flow and interface specifications
-
-### Architecture Design
-**Consolidated from**: @system-architect/analysis.md, @data-architect/analysis.md
-- System architecture and component interactions
-- Data flow and storage strategy
-- Technology stack decisions
-
-### Domain Expertise & Standards
-**Consolidated from**: @subject-matter-expert/analysis.md
-- Industry standards and best practices
-- Compliance requirements and regulations
-- Technical quality and domain-specific patterns
-
-## Process & Collaboration Concerns
-**Consolidated from**: @scrum-master/analysis.md, @product-owner/analysis.md
-
-### Team Capability Assessment
-| Required Skill | Current Level | Gap Analysis | Mitigation Strategy | Reference |
-|----------------|---------------|--------------|---------------------|-----------|
-| Kubernetes | Intermediate | Need advanced knowledge | Training + external consultant | @scrum-master/analysis.md |
-| React Hooks | Advanced | Team ready | None | @scrum-master/analysis.md |
-
-### Process Risks
-| Risk | Impact | Probability | Mitigation | Owner |
-|------|--------|-------------|------------|-------|
-| Cross-team API dependency | High | Medium | Early API contract definition | @scrum-master/analysis.md |
-| UX-Dev alignment gap | Medium | High | Weekly design sync meetings | @ux-expert/analysis.md |
-
-### Collaboration Patterns
-- **Design-Dev Pairing**: UI Designer and Frontend Dev pair programming for complex interactions
-- **Architecture Reviews**: Weekly arch review for system-level decisions
-- **User Testing Cadence**: Bi-weekly UX testing sessions with real users
-- **Reference**: @scrum-master/analysis.md#collaboration
-
-### Timeline Constraints
-- **Blocking Dependencies**: Project-X API must complete before Phase 2
-- **Resource Constraints**: Only 2 backend developers available in Q1
-- **External Dependencies**: Third-party OAuth provider integration timeline
-- **Reference**: @scrum-master/analysis.md#constraints
-
-## Implementation Roadmap (High-Level)
-### Development Phases
-**Phase 1** (0-3 months): Foundation and core features
-**Phase 2** (3-6 months): Advanced features and integrations
-**Phase 3** (6+ months): Optimization and innovation
-
-### Technical Guidelines
-- Development standards and code organization
-- Testing strategy and quality assurance
-- Deployment and monitoring approach
-
-### Feature Grouping (Epic-Level)
-- High-level feature grouping and prioritization
-- Epic-level dependencies and sequencing
-- Strategic milestones and release planning
-
-**Note**: Detailed task breakdown into executable work items is handled by `/workflow:plan` → `IMPL_PLAN.md`
-
-## Risk Assessment & Mitigation
-### Critical Risks Identified
-1. **Risk**: Description | **Mitigation**: Strategy
-2. **Risk**: Description | **Mitigation**: Strategy
-
-### Success Factors
-- Key factors for implementation success
-- Continuous monitoring requirements
-- Quality gates and validation checkpoints
-
----
-*Complete implementation specification consolidating all role perspectives into actionable guidance*
-```
+**Agent Usage**: The conceptual-planning-agent loads this template to understand expected structure and quality standards.
 
 ## 🔄 **Session Integration**
 
@@ -400,98 +308,39 @@ Upon completion, update `workflow-session.json`:
 
 ## ✅ **Quality Assurance**
 
-### Required Synthesis Elements
-- [ ] Integration of all available role analyses with comprehensive coverage
-- [ ] **Key Designs & Decisions**: Architecture diagrams, user journey maps, ADRs documented
-- [ ] **Controversial Points**: Disagreement points, alternatives, and decision rationale captured
-- [ ] **Process Concerns**: Team capability gaps, process risks, collaboration patterns identified
-- [ ] Quantified priority recommendation matrix with evaluation criteria
-- [ ] Actionable implementation plan with phased approach
-- [ ] Comprehensive risk assessment with mitigation strategies
+Verify synthesis output meets these standards (detailed criteria in `synthesis-role.md` template):
 
-### Synthesis Analysis Quality Standards
-- [ ] **Completeness**: Integrates all available role analyses without gaps
-- [ ] **Visual Clarity**: Key diagrams (architecture, data model, user journey) included via Mermaid or images
-- [ ] **Decision Transparency**: Documents not just decisions, but alternatives and why they were rejected
-- [ ] **Insight Generation**: Identifies cross-role patterns and deep insights
-- [ ] **Actionability**: Provides specific, executable recommendations with rationale
-- [ ] **Balance**: Considers all role perspectives, including process-oriented roles (Scrum Master)
-- [ ] **Forward-Looking**: Includes long-term strategic and innovation considerations
+### Content Completeness
+- [ ] All discovered role analyses integrated without gaps
+- [ ] Key designs documented (architecture diagrams, ADRs, user journeys via Mermaid)
+- [ ] Controversial points captured with alternatives and rationale
+- [ ] Process concerns included (team skills, risks, collaboration patterns)
+- [ ] Requirements documented (Functional, Non-Functional, Business) with sources
 
-### Output Validation Criteria
-- [ ] **Priority-Based**: Recommendations prioritized using multi-dimensional evaluation
-- [ ] **Context-Rich**: Each requirement includes rationale summary for immediate understanding
-- [ ] **Resource-Aware**: Team skill gaps and constraints explicitly documented
-- [ ] **Risk-Managed**: Both technical and process risks captured with mitigation strategies
-- [ ] **Measurable Success**: Clear success metrics and monitoring frameworks
-- [ ] **Clear Actions**: Specific next steps with assigned responsibilities and timelines
-
-### Integration Excellence Standards
-- [ ] **Cross-Role Synthesis**: Successfully identifies and documents role perspective conflicts
-- [ ] **No Role Marginalization**: Process, UX, and compliance concerns equally visible as functional requirements
-- [ ] **Strategic Coherence**: Recommendations form coherent strategic direction
-- [ ] **Implementation Readiness**: Plans detailed enough for immediate execution, with clear handoff to IMPL_PLAN.md
-- [ ] **Stakeholder Alignment**: Addresses needs and concerns of all key stakeholders
-- [ ] **Decision Traceability**: Every major decision traceable to source role analysis via @ references
-- [ ] **Continuous Improvement**: Establishes framework for ongoing optimization and learning
+### Analysis Quality
+- [ ] Cross-role synthesis identifies consensus and conflicts
+- [ ] Decision transparency documents both adopted and rejected alternatives
+- [ ] Priority recommendations with multi-dimensional evaluation
+- [ ] Implementation roadmap with phased approach
+- [ ] Risk assessment with mitigation strategies
+- [ ] @ references to source role analyses throughout
 
 ## 🚀 **Recommended Next Steps**
 
-After synthesis completion, follow this recommended workflow:
+After synthesis completion, proceed to action planning:
 
-### Option 1: Standard Planning Workflow (Recommended)
+### Standard Workflow (Recommended)
 ```bash
-# Step 1: Verify conceptual clarity (Quality Gate)
-/workflow:concept-verify --session WFS-{session-id}
-# → Interactive Q&A (up to 5 questions) to clarify ambiguities in synthesis
-
-# Step 2: Proceed to action planning (after concept verification)
-/workflow:plan --session WFS-{session-id}
-# → Generates IMPL_PLAN.md and task.json files
-
-# Step 3: Verify action plan quality (Quality Gate)
-/workflow:action-plan-verify --session WFS-{session-id}
-# → Read-only analysis to catch issues before execution
-
-# Step 4: Start implementation
-/workflow:execute --session WFS-{session-id}
+/workflow:concept-clarify --session WFS-{session-id}  # Optional: Clarify ambiguities
+/workflow:plan --session WFS-{session-id}             # Generate IMPL_PLAN.md and tasks
+/workflow:action-plan-verify --session WFS-{session-id}  # Optional: Verify plan quality
+/workflow:execute --session WFS-{session-id}          # Start implementation
 ```
 
-### Option 2: TDD Workflow
+### TDD Workflow
 ```bash
-# Step 1: Verify conceptual clarity
-/workflow:concept-verify --session WFS-{session-id}
-
-# Step 2: Generate TDD task chains (RED-GREEN-REFACTOR)
+/workflow:concept-clarify --session WFS-{session-id}  # Optional: Clarify ambiguities
 /workflow:tdd-plan --session WFS-{session-id} "Feature description"
-
-# Step 3: Verify TDD plan quality
-/workflow:action-plan-verify --session WFS-{session-id}
-
-# Step 4: Execute TDD workflow
+/workflow:action-plan-verify --session WFS-{session-id}  # Optional: Verify plan quality
 /workflow:execute --session WFS-{session-id}
 ```
-
-### Quality Gates Explained
-
-**`/workflow:concept-verify`** (Phase 2 - After Brainstorming):
-- **Purpose**: Detect and resolve conceptual ambiguities before detailed planning
-- **Time**: 10-20 minutes (interactive)
-- **Value**: Reduces downstream rework by 40-60%
-- **Output**: Updated synthesis-specification.md with clarifications
-
-**`/workflow:action-plan-verify`** (Phase 4 - After Planning):
-- **Purpose**: Validate IMPL_PLAN.md and task.json consistency and completeness
-- **Time**: 5-10 minutes (read-only analysis)
-- **Value**: Prevents execution of flawed plans, saves 2-5 days
-- **Output**: Verification report with actionable recommendations
-
-### Skip Verification? (Not Recommended)
-
-If you want to skip verification and proceed directly:
-```bash
-/workflow:plan --session WFS-{session-id}
-/workflow:execute --session WFS-{session-id}
-```
-
-⚠️ **Warning**: Skipping verification increases risk of late-stage issues and rework.

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

@@ -95,47 +95,72 @@ TEST_FOCUS: [Test scenarios]
 - Manual: `/workflow:tools:task-generate-tdd --session [sessionId]`
 - Agent: `/workflow:tools:task-generate-tdd --session [sessionId] --agent`
 
-**Parse**: Extract feature count, chain count, task count
+**Parse**: Extract feature count, task count (not chain count - tasks now contain internal TDD cycles)
 
 **Validate**:
-- IMPL_PLAN.md exists (unified plan with TDD Task Chains section)
-- TEST-*.json, IMPL-*.json, REFACTOR-*.json exist
-- TODO_LIST.md exists
-- IMPL tasks include test-fix-cycle configuration
+- IMPL_PLAN.md exists (unified plan with TDD Implementation Tasks section)
+- IMPL-*.json files exist (one per feature, or container + subtasks for complex features)
+- TODO_LIST.md exists with internal TDD phase indicators
+- Each IMPL task includes:
+  - `meta.tdd_workflow: true`
+  - `flow_control.implementation_approach` with 3 steps (red/green/refactor)
+  - Green phase includes test-fix-cycle configuration
 - IMPL_PLAN.md contains workflow_type: "tdd" in frontmatter
+- Task count ≤10 (compliance with task limit)
 
 ### Phase 7: TDD Structure Validation & Action Plan Verification (RECOMMENDED)
 **Internal validation first, then recommend external verification**
 
 **Internal Validation**:
-1. Each feature has TEST → IMPL → REFACTOR chain
-2. Dependencies: IMPL depends_on TEST, REFACTOR depends_on IMPL
-3. Meta fields: tdd_phase correct ("red"/"green"/"refactor")
-4. Agents: TEST uses @code-review-test-agent, IMPL/REFACTOR use @code-developer
-5. IMPL tasks contain test-fix-cycle in flow_control for iterative Green phase
+1. Each task contains complete TDD workflow (Red-Green-Refactor internally)
+2. Task structure validation:
+   - `meta.tdd_workflow: true` in all IMPL tasks
+   - `flow_control.implementation_approach` has exactly 3 steps
+   - Each step has correct `tdd_phase`: "red", "green", "refactor"
+3. Dependency validation:
+   - Sequential features: IMPL-N depends_on ["IMPL-(N-1)"] if needed
+   - Complex features: IMPL-N.M depends_on ["IMPL-N.(M-1)"] for subtasks
+4. Agent assignment: All IMPL tasks use @code-developer
+5. Test-fix cycle: Green phase step includes test-fix-cycle logic with max_iterations
+6. Task count: Total tasks ≤10 (simple + subtasks)
 
 **Return Summary**:
 ```
 TDD Planning complete for session: [sessionId]
 
 Features analyzed: [N]
-TDD chains generated: [N]
-Total tasks: [3N]
+Total tasks: [M] (1 task per simple feature + subtasks for complex features)
+
+Task breakdown:
+- Simple features: [K] tasks (IMPL-1 to IMPL-K)
+- Complex features: [L] features with [P] subtasks
+- Total task count: [M] (within 10-task limit ✅)
 
 Structure:
-- Feature 1: TEST-1.1 → IMPL-1.1 → REFACTOR-1.1
+- IMPL-1: {Feature 1 Name} (Internal: 🔴 Red → 🟢 Green → 🔵 Refactor)
+- IMPL-2: {Feature 2 Name} (Internal: 🔴 Red → 🟢 Green → 🔵 Refactor)
+- IMPL-3: {Complex Feature} (Container)
+  - IMPL-3.1: {Sub-feature A} (Internal: 🔴 Red → 🟢 Green → 🔵 Refactor)
+  - IMPL-3.2: {Sub-feature B} (Internal: 🔴 Red → 🟢 Green → 🔵 Refactor)
 [...]
 
-Plan:
+Plans generated:
 - Unified Implementation Plan: .workflow/[sessionId]/IMPL_PLAN.md
-  (includes TDD Task Chains section with workflow_type: "tdd")
+  (includes TDD Implementation Tasks section with workflow_type: "tdd")
+- Task List: .workflow/[sessionId]/TODO_LIST.md
+  (with internal TDD phase indicators)
+
+TDD Configuration:
+- Each task contains complete Red-Green-Refactor cycle
+- Green phase includes test-fix cycle (max 3 iterations)
+- Auto-revert on max iterations reached
 
 ✅ Recommended Next Steps:
-1. /workflow:action-plan-verify --session [sessionId]  # Verify TDD plan quality
+1. /workflow:action-plan-verify --session [sessionId]  # Verify TDD plan quality and dependencies
 2. /workflow:execute --session [sessionId]  # Start TDD execution
 3. /workflow:tdd-verify [sessionId]  # Post-execution TDD compliance check
 
-⚠️ Quality Gate: Consider running /workflow:action-plan-verify to validate TDD task dependencies
+⚠️ Quality Gate: Consider running /workflow:action-plan-verify to validate TDD task structure and dependencies
 ```
 
 ## TodoWrite Pattern
@@ -232,14 +257,18 @@ Supports action-planning-agent for more autonomous TDD planning with:
 
 ### Workflow Comparison
 
-| Aspect | Previous | Current |
-|--------|----------|---------|
-| **Phases** | 5 | 6 (test coverage analysis) |
+| Aspect | Previous | Current (Optimized) |
+|--------|----------|---------------------|
+| **Phases** | 6 (with test coverage) | 7 (added concept verification) |
 | **Context** | Greenfield assumption | Existing codebase aware |
+| **Task Structure** | 1 feature = 3 tasks (TEST/IMPL/REFACTOR) | 1 feature = 1 task (internal TDD cycle) |
+| **Task Count** | 5 features = 15 tasks | 5 features = 5 tasks (70% reduction) |
 | **Green Phase** | Single implementation | Iterative with fix cycle |
 | **Failure Handling** | Manual intervention | Auto-diagnose + fix + revert |
 | **Test Analysis** | None | Deep coverage analysis |
 | **Feedback Loop** | Post-execution | During Green phase |
+| **Task Management** | High overhead (15 tasks) | Low overhead (5 tasks) |
+| **Execution Efficiency** | Frequent context switching | Continuous context per feature |
 
 ### Migration Notes
 
@@ -251,19 +280,26 @@ Supports action-planning-agent for more autonomous TDD planning with:
 **Session Structure**:
 ```
 .workflow/WFS-xxx/
-├── IMPL_PLAN.md (unified plan with TDD Task Chains section)
-├── TODO_LIST.md
+├── IMPL_PLAN.md (unified plan with TDD Implementation Tasks section)
+├── TODO_LIST.md (with internal TDD phase indicators)
 ├── .process/
 │   ├── context-package.json
 │   ├── test-context-package.json
 │   ├── ANALYSIS_RESULTS.md (enhanced with TDD breakdown)
-│   └── green-fix-iteration-*.md (fix logs)
+│   └── green-fix-iteration-*.md (fix logs from Green phase cycles)
 └── .task/
-    ├── TEST-*.json (Red phase)
-    ├── IMPL-*.json (Green phase with test-fix-cycle)
-    └── REFACTOR-*.json (Refactor phase)
+    ├── IMPL-1.json (Complete TDD task: Red-Green-Refactor internally)
+    ├── IMPL-2.json (Complete TDD task)
+    ├── IMPL-3.json (Complex feature container, if needed)
+    ├── IMPL-3.1.json (Complex feature subtask, if needed)
+    └── IMPL-3.2.json (Complex feature subtask, if needed)
 ```
 
+**File Count Comparison**:
+- **Old structure**: 5 features = 15 task files (TEST/IMPL/REFACTOR × 5)
+- **New structure**: 5 features = 5 task files (IMPL-N × 5)
+- **Complex features**: Add container + subtasks only when necessary
+
 **Configuration Options** (in IMPL tasks):
 - `meta.max_iterations`: Fix attempts (default: 3)
 - `meta.use_codex`: Auto-fix mode (default: false)

.claude/commands/workflow/test-cycle-execute.md

@@ -0,0 +1,651 @@
+---
+name: test-cycle-execute
+description: Execute test-fix workflow with dynamic task generation and iterative fix cycles
+argument-hint: "[--resume-session=\"session-id\"] [--max-iterations=N]"
+allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Task(*)
+---
+
+# Workflow Test-Cycle-Execute Command
+
+## Overview
+Orchestrates dynamic test-fix workflow execution through iterative cycles of testing, analysis, and fixing. **Unlike standard execute, this command dynamically generates intermediate tasks** during execution based on test results and CLI analysis, enabling adaptive problem-solving.
+
+**Resume Mode**: When called with `--resume-session` flag, skips discovery and continues from interruption point.
+
+## Core Philosophy
+
+### Dynamic vs Static Execution
+**Standard Execute**: Pre-defined task queue → Sequential execution → Complete
+**Test Execute**: Initial tasks → Test → Analyze → Generate fix tasks → Execute → Re-test → Repeat
+
+### Iteration Loop Pattern
+```
+1. Execute current task (test/implement)
+2. Run tests and collect results
+3. If failures: CLI analysis → Generate fix tasks → Execute → Back to 2
+4. If success: Mark complete → Next task
+5. Repeat until all tests pass or max iterations reached
+```
+
+### Agent Coordination
+- **@code-developer**: Understands requirements, generates implementations
+- **@test-fix-agent**: Executes tests, applies fixes, validates results
+- **CLI Tools (Gemini/Qwen)**: Analyzes failures, suggests fix strategies
+
+## Core Rules
+1. **Dynamic Task Generation**: Create intermediate fix tasks based on test failures
+2. **Iterative Execution**: Repeat test-fix cycles until success or max iterations
+3. **CLI-Driven Analysis**: Use Gemini/Qwen to analyze failures and plan fixes
+4. **Agent Delegation**: All execution delegated to specialized agents
+5. **Context Accumulation**: Each iteration builds on previous attempt context
+6. **Autonomous Completion**: Continue until all tests pass without user interruption
+
+## Core Responsibilities
+- **Session Discovery**: Identify test-fix workflow sessions
+- **Task Queue Management**: Maintain dynamic task queue with runtime additions
+- **Test Execution**: Run tests through @test-fix-agent
+- **Failure Analysis**: Use CLI tools to diagnose test failures
+- **Fix Task Generation**: Create intermediate fix tasks dynamically
+- **Iteration Control**: Manage fix cycles with max iteration limits
+- **Context Propagation**: Pass failure context and fix history between iterations
+- **Progress Tracking**: TodoWrite updates for entire iteration cycle
+- **Session Auto-Complete**: Call `/workflow:session:complete` when all tests pass
+
+## Responsibility Matrix
+
+**Clear division of labor between orchestrator and agents:**
+
+| Responsibility | test-cycle-execute (Orchestrator) | @test-fix-agent (Executor) |
+|----------------|----------------------------|---------------------------|
+| Manage iteration loop | ✅ Controls loop flow | ❌ Executes single task |
+| Run CLI analysis (Gemini/Qwen) | ✅ Runs between agent tasks | ❌ Not involved |
+| Generate IMPL-fix-N.json | ✅ Creates task files | ❌ Not involved |
+| Run tests | ❌ Delegates to agent | ✅ Executes test command |
+| Apply fixes | ❌ Delegates to agent | ✅ Modifies code |
+| Detect test failures | ✅ Analyzes agent output | ✅ Reports results |
+| Add tasks to queue | ✅ Manages queue | ❌ Not involved |
+| Update iteration state | ✅ Maintains state files | ✅ Updates task status |
+
+**Key Principle**: Orchestrator manages the "what" and "when"; agents execute the "how".
+
+## Execution Lifecycle
+
+### Phase 1: Discovery & Initialization
+1. **Detect Session Type**: Identify test-fix session from `workflow_type: "test_session"`
+2. **Load Session State**: Read `workflow-session.json`, `IMPL_PLAN.md`, `TODO_LIST.md`
+3. **Scan Initial Tasks**: Analyze `.task/*.json` files
+4. **Initialize TodoWrite**: Create task list including initial tasks
+5. **Prepare Iteration Context**: Setup iteration counter and max limits
+
+**Resume Mode**: Load existing iteration context from `.process/iteration-state.json`
+
+### Phase 2: Task Execution Loop
+**Main execution loop with dynamic task generation (executed by test-cycle-execute orchestrator):**
+
+**Execution Order**: The workflow begins by executing IMPL-001 (test generation) first. Upon successful completion, IMPL-002 (test-fix cycle) is initiated, starting the iterative test-fix loop.
+
+```
+For each task in queue:
+  1. [Orchestrator] Load task JSON and context
+  2. [Orchestrator] Determine task type (test-gen, test-fix, fix-iteration)
+  3. [Orchestrator] Execute task through appropriate agent
+  4. [Orchestrator] Collect agent results and check exit conditions
+  5. If test failures detected:
+     a. [Orchestrator] Run CLI analysis (Gemini/Qwen)
+     b. [Orchestrator] Generate fix task JSON (IMPL-fix-N.json)
+     c. [Orchestrator] Insert fix task at front of queue
+     d. [Orchestrator] Continue loop
+  6. If test success:
+     a. [Orchestrator] Mark task complete
+     b. [Orchestrator] Update TodoWrite
+     c. [Orchestrator] Continue to next task
+  7. [Orchestrator] Check max iterations limit
+```
+
+**Note**: The orchestrator controls the loop. Agents execute individual tasks and return results.
+
+### Phase 3: Iteration Cycle (Test-Fix Loop)
+
+**Orchestrator-controlled iteration with agent delegation:**
+
+#### Iteration Structure
+```
+Iteration N (managed by test-cycle-execute orchestrator):
+├── 1. Test Execution
+│   ├── [Orchestrator] Launch @test-fix-agent with test task
+│   ├── [Agent] Run test suite
+│   ├── [Agent] Collect failures and report back
+│   └── [Orchestrator] Receive failure report
+├── 2. Failure Analysis
+│   ├── [Orchestrator] Run CLI tool (Gemini/Qwen)
+│   ├── [CLI Tool] Analyze error messages and failure context
+│   ├── [CLI Tool] Identify root causes
+│   └── [CLI Tool] Generate fix strategy → saved to iteration-N-analysis.md
+├── 3. Fix Task Generation
+│   ├── [Orchestrator] Parse CLI analysis results
+│   ├── [Orchestrator] Create IMPL-fix-N.json with:
+│   │   ├── meta.agent: "@test-fix-agent"
+│   │   ├── Failure context (content, not just path)
+│   │   └── Fix strategy from CLI analysis
+│   └── [Orchestrator] Insert into task queue (front position)
+├── 4. Fix Execution
+│   ├── [Orchestrator] Launch @test-fix-agent with fix task
+│   ├── [Agent] Load fix strategy from task context
+│   ├── [Agent] Apply fixes to code/tests
+│   └── [Agent] Report completion
+└── 5. Re-test
+    └── [Orchestrator] Return to step 1 with updated code
+```
+
+**Key**: Orchestrator runs CLI analysis between agent tasks, then generates new fix tasks.
+
+#### Iteration Task JSON Template
+```json
+{
+  "id": "IMPL-fix-{iteration}",
+  "title": "Fix test failures - Iteration {N}",
+  "status": "pending",
+  "meta": {
+    "type": "test-fix-iteration",
+    "agent": "@test-fix-agent",
+    "iteration": N,
+    "parent_task": "IMPL-002",
+    "max_iterations": 5
+  },
+  "context": {
+    "requirements": [
+      "Fix identified test failures",
+      "Address root causes from analysis"
+    ],
+    "failure_context": {
+      "failed_tests": ["test1", "test2"],
+      "error_messages": ["error1", "error2"],
+      "failure_analysis": "Raw test output and error messages",
+      "previous_attempts": ["iteration-1 context"]
+    },
+    "fix_strategy": {
+      "approach": "Generated by CLI tool (Gemini/Qwen) analysis",
+      "modification_points": ["file1:func1", "file2:func2"],
+      "expected_outcome": "All tests pass"
+    },
+    "depends_on": ["IMPL-fix-{N-1}"],
+    "inherited": {
+      "iteration_history": [...]
+    }
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "load_failure_context",
+        "command": "Read(.workflow/{session}/.process/iteration-{N-1}-failures.json)",
+        "output_to": "previous_failures",
+        "on_error": "skip_optional"
+      },
+      {
+        "step": "load_fix_strategy",
+        "command": "Read(.workflow/{session}/.process/iteration-{N}-strategy.md)",
+        "output_to": "fix_strategy",
+        "on_error": "fail"
+      }
+    ],
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Apply fixes from strategy",
+        "description": "Implement fixes identified by CLI analysis",
+        "modification_points": "From fix_strategy",
+        "logic_flow": [
+          "Load failure context and strategy",
+          "Apply surgical fixes",
+          "Run tests",
+          "Validate fixes"
+        ]
+      }
+    ],
+    "target_files": ["from fix_strategy"],
+    "exit_conditions": {
+      "success": "all_tests_pass",
+      "failure": "max_iterations_reached",
+      "max_iterations": 5
+    }
+  }
+}
+```
+
+### Phase 4: CLI Analysis Integration
+
+**Orchestrator executes CLI analysis between agent tasks:**
+
+#### When Test Failures Occur
+1. **[Orchestrator]** Detects failures from agent output
+2. **[Orchestrator]** Collects failure context from `.process/test-results.json` and logs
+3. **[Orchestrator]** Runs Gemini/Qwen wrapper with failure context
+4. **[CLI Tool]** Analyzes failures and generates fix strategy
+5. **[Orchestrator]** Saves analysis to `.process/iteration-N-analysis.md`
+6. **[Orchestrator]** Generates `IMPL-fix-N.json` with strategy content (not just path)
+
+#### CLI Analysis Command (executed by orchestrator)
+```bash
+cd {project_root} && ~/.claude/scripts/gemini-wrapper -p "
+PURPOSE: Analyze test failures and generate fix strategy
+TASK: Review test failures and identify root causes
+MODE: analysis
+CONTEXT: @{test files, implementation files}
+
+[Test failure context and requirements...]
+
+EXPECTED: Detailed fix strategy in markdown format
+RULES: Focus on minimal changes, avoid over-engineering
+"
+```
+
+#### Analysis Output Structure
+```markdown
+# Test Failure Analysis - Iteration {N}
+
+## Root Cause Analysis
+1. **Test: test_auth_flow**
+   - Error: `Expected 200, got 401`
+   - Root Cause: Missing authentication token in request headers
+   - Affected Code: `src/auth/client.ts:45`
+
+2. **Test: test_data_validation**
+   - Error: `TypeError: Cannot read property 'name' of undefined`
+   - Root Cause: Null check missing before property access
+   - Affected Code: `src/validators/user.ts:23`
+
+## Fix Strategy
+
+### Priority 1: Authentication Issue
+- **File**: src/auth/client.ts
+- **Function**: sendRequest (line 45)
+- **Change**: Add token header: `headers['Authorization'] = 'Bearer ' + token`
+- **Verification**: Run test_auth_flow
+
+### Priority 2: Null Check
+- **File**: src/validators/user.ts
+- **Function**: validateUser (line 23)
+- **Change**: Add check: `if (!user?.name) return false`
+- **Verification**: Run test_data_validation
+
+## Verification Plan
+1. Apply fixes in order
+2. Run test suite after each fix
+3. Check for regressions
+4. Validate all tests pass
+
+## Risk Assessment
+- Low risk: Changes are surgical and isolated
+- No breaking changes expected
+- Existing tests should remain green
+```
+
+### Phase 5: Task Queue Management
+
+**Orchestrator maintains dynamic task queue with runtime insertions:**
+
+#### Dynamic Queue Operations
+```
+Initial Queue: [IMPL-001, IMPL-002]
+
+After IMPL-002 execution (test failures detected by orchestrator):
+  [Orchestrator] Generates IMPL-fix-1.json
+  [Orchestrator] Inserts at front: [IMPL-fix-1, IMPL-002-retest, ...]
+
+After IMPL-fix-1 execution (still failures):
+  [Orchestrator] Generates IMPL-fix-2.json
+  [Orchestrator] Inserts at front: [IMPL-fix-2, IMPL-002-retest, ...]
+
+After IMPL-fix-2 execution (success):
+  [Orchestrator] Continues to: [IMPL-002-complete, ...]
+```
+
+#### Queue Priority Rules (orchestrator-managed)
+1. **Fix tasks**: Inserted at queue front for immediate execution
+2. **Retest tasks**: Automatically scheduled after fix tasks
+3. **Regular tasks**: Standard dependency order preserved
+4. **Iteration limit**: Max 5 fix iterations per test task (orchestrator enforces)
+
+### Phase 6: Completion & Session Management
+
+#### Success Conditions
+- All initial tasks completed
+- All generated fix tasks completed
+- All tests passing
+- No pending tasks in queue
+
+#### Completion Steps
+1. **Final Validation**: Run full test suite one more time
+2. **Update Session State**: Mark all tasks completed
+3. **Generate Summary**: Create session completion summary
+4. **Update TodoWrite**: Mark all items completed
+5. **Auto-Complete**: Call `/workflow:session:complete`
+
+#### Failure Conditions
+- Max iterations reached without success
+- Unrecoverable test failures
+- Agent execution errors
+
+#### Failure Handling
+1. **Document State**: Save current iteration context
+2. **Generate Report**: Create failure analysis report
+3. **Preserve Context**: Keep all iteration logs
+4. **Mark Blocked**: Update task status to blocked
+5. **Return Control**: Return to user with detailed report
+
+## TodoWrite Coordination
+
+### TodoWrite Structure for Test-Execute
+```javascript
+TodoWrite({
+  todos: [
+    {
+      content: "Execute IMPL-001: Generate tests [code-developer]",
+      status: "completed",
+      activeForm: "Executing test generation"
+    },
+    {
+      content: "Execute IMPL-002: Test & Fix Cycle [test-fix-agent] [ITERATION]",
+      status: "in_progress",
+      activeForm: "Running test-fix iteration cycle"
+    },
+    {
+      content: "  → Iteration 1: Initial test run",
+      status: "completed",
+      activeForm: "Running initial tests"
+    },
+    {
+      content: "  → Iteration 2: Fix auth issues",
+      status: "in_progress",
+      activeForm: "Fixing authentication issues"
+    },
+    {
+      content: "  → Iteration 3: Re-test and validate",
+      status: "pending",
+      activeForm: "Re-testing after fixes"
+    }
+  ]
+});
+```
+
+### TodoWrite Update Rules
+1. **Initial Tasks**: Standard task list
+2. **Iteration Start**: Add nested iteration item
+3. **Fix Task Added**: Add fix task as nested item
+4. **Iteration Complete**: Mark iteration item completed
+5. **All Complete**: Mark parent task completed
+
+## Agent Context Package
+
+**Generated by test-cycle-execute orchestrator before launching agents.**
+
+The orchestrator assembles this context package from:
+- Task JSON file (IMPL-*.json)
+- Iteration state files
+- Test results and failure context
+- Session metadata
+
+This package is passed to agents via the Task tool's prompt context.
+
+### Enhanced Context for Test-Fix Agent
+```json
+{
+  "task": { /* IMPL-fix-N.json */ },
+  "iteration_context": {
+    "current_iteration": N,
+    "max_iterations": 5,
+    "previous_attempts": [
+      {
+        "iteration": N-1,
+        "failures": ["test1", "test2"],
+        "fixes_attempted": ["fix1", "fix2"],
+        "result": "partial_success"
+      }
+    ],
+    "failure_analysis": {
+      "source": "gemini_cli",
+      "analysis_file": ".process/iteration-N-analysis.md",
+      "fix_strategy": { /* from CLI */ }
+    }
+  },
+  "test_context": {
+    "test_framework": "jest|pytest|...",
+    "test_files": ["path/to/test1.test.ts"],
+    "test_command": "npm test",
+    "coverage_target": 80
+  },
+  "session": {
+    "workflow_dir": ".workflow/WFS-test-{session}/",
+    "iteration_state_file": ".process/iteration-state.json",
+    "test_results_file": ".process/test-results.json",
+    "fix_history_file": ".process/fix-history.json"
+  }
+}
+```
+
+## File Structure
+
+### Test-Fix Session Files
+```
+.workflow/WFS-test-{session}/
+├── workflow-session.json          # Session metadata with workflow_type
+├── IMPL_PLAN.md                   # Test plan
+├── TODO_LIST.md                   # Progress tracking
+├── .task/
+│   ├── IMPL-001.json              # Test generation task
+│   ├── IMPL-002.json              # Initial test-fix task
+│   ├── IMPL-fix-1.json            # Generated: Iteration 1 fix
+│   ├── IMPL-fix-2.json            # Generated: Iteration 2 fix
+│   └── ...
+├── .summaries/
+│   ├── IMPL-001-summary.md
+│   ├── IMPL-002-summary.md
+│   └── iteration-summaries/
+│       ├── iteration-1.md
+│       ├── iteration-2.md
+│       └── ...
+└── .process/
+    ├── TEST_ANALYSIS_RESULTS.md   # From planning phase
+    ├── iteration-state.json       # Current iteration state
+    ├── test-results.json          # Latest test results
+    ├── test-output.log            # Full test output
+    ├── fix-history.json           # All fix attempts
+    ├── iteration-1-analysis.md    # CLI analysis for iteration 1
+    ├── iteration-1-failures.json  # Failures from iteration 1
+    ├── iteration-1-strategy.md    # Fix strategy for iteration 1
+    ├── iteration-2-analysis.md
+    └── ...
+```
+
+### Iteration State JSON
+```json
+{
+  "session_id": "WFS-test-user-auth",
+  "current_task": "IMPL-002",
+  "current_iteration": 2,
+  "max_iterations": 5,
+  "started_at": "2025-10-17T10:00:00Z",
+  "iterations": [
+    {
+      "iteration": 1,
+      "started_at": "2025-10-17T10:05:00Z",
+      "completed_at": "2025-10-17T10:15:00Z",
+      "test_results": {
+        "total": 10,
+        "passed": 7,
+        "failed": 3,
+        "failures": ["test1", "test2", "test3"]
+      },
+      "analysis_file": ".process/iteration-1-analysis.md",
+      "fix_task": "IMPL-fix-1",
+      "result": "partial_success"
+    }
+  ],
+  "status": "active",
+  "next_action": "execute_fix_task"
+}
+```
+
+## Agent Prompt Template
+
+**Unified template for all agent tasks (orchestrator invokes with Task tool):**
+
+```bash
+Task(subagent_type="{meta.agent}",
+     prompt="**TASK EXECUTION: {task.title}**
+
+     ## STEP 1: Load Complete Task JSON
+     **MANDATORY**: First load the complete task JSON from: {session.task_json_path}
+
+     cat {session.task_json_path}
+
+     **CRITICAL**: Validate all required fields present
+
+     ## STEP 2: Task Context (From Loaded JSON)
+     **ID**: {task.id}
+     **Type**: {task.meta.type}
+     **Agent**: {task.meta.agent}
+
+     ## STEP 3: Execute Task Based on Type
+
+     ### For test-gen (IMPL-001):
+     - Generate tests based on TEST_ANALYSIS_RESULTS.md
+     - Follow test framework conventions
+     - Create test files in target_files
+
+     ### For test-fix (IMPL-002):
+     - Run test suite: {test_command}
+     - Collect results to .process/test-results.json
+     - If failures: Save context, return to orchestrator
+     - If success: Mark complete
+
+     ### For test-fix-iteration (IMPL-fix-N):
+     - Load fix strategy from context.fix_strategy (CONTENT, not path)
+     - Apply surgical fixes to identified files
+     - Run tests to verify
+     - If still failures: Save context with new failure data
+     - Update iteration state
+
+     ## STEP 4: Implementation Context (From JSON)
+     **Requirements**: {context.requirements}
+     **Fix Strategy**: {context.fix_strategy} (full content provided in task JSON)
+     **Failure Context**: {context.failure_context}
+     **Iteration History**: {context.inherited.iteration_history}
+
+     ## STEP 5: Flow Control Execution
+     If flow_control.pre_analysis exists, execute steps sequentially
+
+     ## STEP 6: Agent Completion
+     1. Execute task following implementation_approach
+     2. Update task status in JSON
+     3. Update TODO_LIST.md
+     4. Generate summary in .summaries/
+     5. **CRITICAL**: Save results for orchestrator to analyze
+
+     **Output Requirements**:
+     - test-results.json: Structured test results
+     - test-output.log: Full test output
+     - iteration-state.json: Current iteration state (if applicable)
+     - task-summary.md: Completion summary
+
+     **Return to Orchestrator**: Agent completes and returns. Orchestrator decides next action.
+     "),
+     description="Execute {task.type} task with JSON validation")
+```
+
+**Key Points**:
+- Agent executes single task and returns
+- Orchestrator analyzes results and decides next step
+- Fix strategy content (not path) embedded in task JSON by orchestrator
+- Agent does not manage iteration loop
+
+## Error Handling & Recovery
+
+### Iteration Failure Scenarios
+| Scenario | Handling | Recovery |
+|----------|----------|----------|
+| Test execution error | Log error, save context | Retry with error context |
+| CLI analysis failure | Fallback to Qwen, or manual analysis | Retry analysis with different tool |
+| Agent execution error | Save iteration state | Retry agent with simplified context |
+| Max iterations reached | Generate failure report | Mark blocked, return to user |
+| Unexpected test regression | Rollback last fix | Analyze regression, add to fix strategy |
+
+### Recovery Procedures
+
+#### Resume from Interruption
+```bash
+# Load iteration state
+iteration_state=$(cat .workflow/{session}/.process/iteration-state.json)
+current_iteration=$(jq -r '.current_iteration' <<< "$iteration_state")
+
+# Determine resume point
+if [[ "$(jq -r '.next_action' <<< "$iteration_state")" == "execute_fix_task" ]]; then
+  # Resume fix task execution
+  task_id="IMPL-fix-${current_iteration}"
+else
+  # Resume test execution
+  task_id="IMPL-002"
+fi
+```
+
+#### Rollback Failed Fix
+```bash
+# Revert last commit (if fixes were committed)
+git revert HEAD
+
+# Remove failed fix task
+rm .workflow/{session}/.task/IMPL-fix-{N}.json
+
+# Restore iteration state
+jq '.current_iteration -= 1' iteration-state.json > temp.json
+mv temp.json iteration-state.json
+
+# Re-run analysis with additional context
+# Include failure reason in next analysis
+```
+
+## Usage Examples
+
+### Basic Usage
+```bash
+# Execute test-fix workflow
+/workflow:test-cycle-execute
+
+# Resume interrupted session
+/workflow:test-cycle-execute --resume-session="WFS-test-user-auth"
+
+# Set custom iteration limit
+/workflow:test-cycle-execute --max-iterations=10
+```
+
+### Integration with Planning
+```bash
+# 1. Plan test workflow
+/workflow:test-fix-gen WFS-user-auth
+
+# 2. Execute with dynamic iteration
+/workflow:test-cycle-execute
+
+# 3. Monitor progress
+/workflow:status
+
+# 4. Resume if interrupted
+/workflow:test-cycle-execute --resume-session="WFS-test-user-auth"
+```
+
+## Best Practices
+
+1. **Set Realistic Iteration Limits**: Default 5, increase for complex fixes
+2. **Commit Between Iterations**: Easier rollback if needed
+3. **Monitor Iteration Logs**: Review CLI analysis for insights
+4. **Incremental Fixes**: Prefer multiple small iterations over large changes
+5. **Verify No Regressions**: Check all tests pass, not just previously failing ones
+6. **Preserve Context**: All iteration artifacts saved for debugging
+
+## Related Commands
+
+- `/workflow:test-fix-gen` - Planning phase (creates initial tasks)
+- `/workflow:execute` - Standard workflow execution (no dynamic iteration)
+- `/workflow:status` - Check progress and iteration state
+- `/workflow:session:complete` - Mark session complete (auto-called on success)
+- `/task:create` - Manually create additional tasks if needed

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

@@ -0,0 +1,470 @@
+---
+name: test-fix-gen
+description: Create independent test-fix workflow session from existing implementation (session or prompt-based)
+argument-hint: "[--use-codex] [--cli-execute] (source-session-id | \"feature description\" | /path/to/file.md)"
+allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
+---
+
+# Workflow Test-Fix Generation Command (/workflow:test-fix-gen)
+
+## Overview
+
+### What It Does
+
+This command creates an independent test-fix workflow session for existing code. It orchestrates a 5-phase process to analyze implementation, generate test requirements, and create executable test generation and fix tasks.
+
+**⚠️ Command Scope**: Prepares test workflow artifacts only. Task execution requires separate commands (`/workflow:test-cycle-execute` or `/workflow:execute`).
+
+### Dual-Mode Support
+
+**Automatic mode detection** based on input pattern:
+
+| Mode | Input Pattern | Context Source | Use Case |
+|------|--------------|----------------|----------|
+| **Session Mode** | `WFS-xxx` | Source session summaries | Test validation for completed workflow |
+| **Prompt Mode** | Text or file path | Direct codebase analysis | Test generation from description |
+
+**Detection Logic**:
+```bash
+if [[ "$input" == WFS-* ]]; then
+  MODE="session"  # Use test-context-gather
+else
+  MODE="prompt"   # Use context-gather
+fi
+```
+
+### Core Principles
+
+- **Dual Input Support**: Accepts session ID (WFS-xxx) or feature description/file path
+- **Session Isolation**: Creates independent `WFS-test-[slug]` session
+- **Context-First**: Gathers implementation context via appropriate method
+- **Format Reuse**: Creates standard `IMPL-*.json` tasks with `meta.type: "test-fix"`
+- **Manual First**: Default to manual fixes, use `--use-codex` for automation
+- **Automatic Detection**: Input pattern determines execution mode
+
+### Coordinator Role
+
+This command is a **pure orchestrator**:
+- Does NOT analyze code directly
+- Does NOT generate tests or documentation
+- ONLY coordinates slash commands in sequence
+- Parses outputs to pass data between phases
+- Creates independent test workflow session
+
+---
+
+## Usage
+
+### Command Syntax
+
+```bash
+# Basic syntax
+/workflow:test-fix-gen [FLAGS] <INPUT>
+
+# Flags (optional)
+--use-codex        # Enable Codex automated fixes in IMPL-002
+--cli-execute      # Enable CLI execution in IMPL-001
+
+# Input
+<INPUT>            # Session ID, description, or file path
+```
+
+### Usage Examples
+
+#### Session Mode
+```bash
+# Test validation for completed implementation
+/workflow:test-fix-gen WFS-user-auth-v2
+
+# With automated fixes
+/workflow:test-fix-gen --use-codex WFS-api-endpoints
+
+# With CLI execution
+/workflow:test-fix-gen --cli-execute --use-codex WFS-payment-flow
+```
+
+#### Prompt Mode - Text Description
+```bash
+# Generate tests from feature description
+/workflow:test-fix-gen "Test the user authentication API endpoints in src/auth/api.ts"
+
+# With automated fixes
+/workflow:test-fix-gen --use-codex "Test user registration and login flows"
+```
+
+#### Prompt Mode - File Reference
+```bash
+# Generate tests from requirements file
+/workflow:test-fix-gen ./docs/api-requirements.md
+
+# With flags
+/workflow:test-fix-gen --use-codex --cli-execute ./specs/feature.md
+```
+
+### Mode Comparison
+
+| Aspect | Session Mode | Prompt Mode |
+|--------|-------------|-------------|
+| **Phase 1** | Create `WFS-test-[source]` with `source_session_id` | Create `WFS-test-[slug]` without `source_session_id` |
+| **Phase 2** | `/workflow:tools:test-context-gather` | `/workflow:tools:context-gather` |
+| **Phase 3-5** | Identical | Identical |
+| **Context** | Source session summaries + artifacts | Direct codebase analysis |
+
+---
+
+## Execution Flow
+
+### Core Execution Rules
+
+1. **Start Immediately**: First action is TodoWrite, second is Phase 1 session creation
+2. **No Preliminary Analysis**: Do not read files before Phase 1
+3. **Parse Every Output**: Extract required data from each phase for next phase
+4. **Sequential Execution**: Each phase depends on previous phase's output
+5. **Complete All Phases**: Do not return until Phase 5 completes
+6. **Track Progress**: Update TodoWrite after every phase
+7. **Automatic Detection**: Mode auto-detected from input pattern
+8. **Parse Flags**: Extract `--use-codex` and `--cli-execute` flags for Phase 4
+
+### 5-Phase Execution
+
+#### Phase 1: Create Test Session
+
+**Command**:
+- **Session Mode**: `SlashCommand("/workflow:session:start --new \"Test validation for [sourceSessionId]\"")`
+- **Prompt Mode**: `SlashCommand("/workflow:session:start --new \"Test generation for: [description]\"")`
+
+**Input**: User argument (session ID, description, or file path)
+
+**Expected Behavior**:
+- Creates new session: `WFS-test-[slug]`
+- Writes `workflow-session.json` metadata:
+  - **Session Mode**: Includes `workflow_type: "test_session"`, `source_session_id: "[sourceId]"`
+  - **Prompt Mode**: Includes `workflow_type: "test_session"` only
+- Returns new session ID
+
+**Parse Output**:
+- Extract: `testSessionId` (pattern: `WFS-test-[slug]`)
+
+**Validation**:
+- **Session Mode**: Source session exists with completed IMPL tasks
+- **Both Modes**: New test session directory created with metadata
+
+**TodoWrite**: Mark phase 1 completed, phase 2 in_progress
+
+---
+
+#### Phase 2: Gather Test Context
+
+**Command**:
+- **Session Mode**: `SlashCommand("/workflow:tools:test-context-gather --session [testSessionId]")`
+- **Prompt Mode**: `SlashCommand("/workflow:tools:context-gather --session [testSessionId] \"[task_description]\"")`
+
+**Input**: `testSessionId` from Phase 1
+
+**Expected Behavior**:
+- **Session Mode**:
+  - Load source session implementation context and summaries
+  - Analyze test coverage using MCP tools
+  - Identify files requiring tests
+- **Prompt Mode**:
+  - Analyze codebase based on description
+  - Identify relevant files and dependencies
+- Detect test framework and conventions
+- Generate context package JSON
+
+**Parse Output**:
+- Extract: `contextPath` (pattern: `.workflow/[testSessionId]/.process/[test-]context-package.json`)
+
+**Validation**:
+- Context package created with coverage analysis
+- Test framework detected
+- Test conventions documented
+
+**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
+
+---
+
+#### Phase 3: Test Generation Analysis
+
+**Command**: `SlashCommand("/workflow:tools:test-concept-enhanced --session [testSessionId] --context [contextPath]")`
+
+**Input**:
+- `testSessionId` from Phase 1
+- `contextPath` from Phase 2
+
+**Expected Behavior**:
+- Use Gemini to analyze coverage gaps and implementation
+- Study existing test patterns and conventions
+- Generate test requirements for missing test files
+- Design test generation strategy
+- Generate `TEST_ANALYSIS_RESULTS.md`
+
+**Parse Output**:
+- Verify `.workflow/[testSessionId]/.process/TEST_ANALYSIS_RESULTS.md` created
+
+**Validation**:
+- TEST_ANALYSIS_RESULTS.md exists with complete sections:
+  - Coverage Assessment
+  - Test Framework & Conventions
+  - Test Requirements by File
+  - Test Generation Strategy
+  - Implementation Targets
+  - Success Criteria
+
+**TodoWrite**: Mark phase 3 completed, phase 4 in_progress
+
+---
+
+#### Phase 4: Generate Test Tasks
+
+**Command**: `SlashCommand("/workflow:tools:test-task-generate [--use-codex] [--cli-execute] --session [testSessionId]")`
+
+**Input**:
+- `testSessionId` from Phase 1
+- `--use-codex` flag (if present) - Controls IMPL-002 fix mode
+- `--cli-execute` flag (if present) - Controls IMPL-001 generation mode
+
+**Expected Behavior**:
+- Parse TEST_ANALYSIS_RESULTS.md from Phase 3
+- Generate **minimum 2 task JSON files** (expandable based on complexity):
+  - **IMPL-001.json**: Test Understanding & Generation (`@code-developer`)
+  - **IMPL-002.json**: Test Execution & Fix Cycle (`@test-fix-agent`)
+  - **IMPL-003+**: Additional tasks if needed for complex projects
+- Generate `IMPL_PLAN.md` with test strategy
+- Generate `TODO_LIST.md` with task checklist
+
+**Parse Output**:
+- Verify `.workflow/[testSessionId]/.task/IMPL-001.json` exists
+- Verify `.workflow/[testSessionId]/.task/IMPL-002.json` exists
+- Verify additional `.task/IMPL-*.json` if applicable
+- Verify `IMPL_PLAN.md` and `TODO_LIST.md` created
+
+**TodoWrite**: Mark phase 4 completed, phase 5 in_progress
+
+---
+
+#### Phase 5: Return Summary
+
+**Return to User**:
+```
+Independent test-fix workflow created successfully!
+
+Input: [original input]
+Mode: [Session|Prompt]
+Test Session: [testSessionId]
+
+Tasks Created:
+- IMPL-001: Test Understanding & Generation (@code-developer)
+- IMPL-002: Test Execution & Fix Cycle (@test-fix-agent)
+[- IMPL-003+: Additional tasks if applicable]
+
+Test Framework: [detected framework]
+Test Files to Generate: [count]
+Max Fix Iterations: 5
+Fix Mode: [Manual|Codex Automated]
+
+Review artifacts:
+- Test plan: .workflow/[testSessionId]/IMPL_PLAN.md
+- Task list: .workflow/[testSessionId]/TODO_LIST.md
+
+Next Steps:
+- Review IMPL_PLAN.md
+- Execute: /workflow:test-cycle-execute [testSessionId]
+```
+
+**TodoWrite**: Mark phase 5 completed
+
+**Note**: Command completes here. Task execution requires separate workflow commands.
+
+---
+
+### TodoWrite Progress Tracking
+
+Track all 5 phases:
+
+```javascript
+TodoWrite({todos: [
+  {"content": "Create independent test session", "status": "in_progress|completed", "activeForm": "Creating test session"},
+  {"content": "Gather test coverage context", "status": "pending|in_progress|completed", "activeForm": "Gathering test coverage context"},
+  {"content": "Analyze test requirements with Gemini", "status": "pending|in_progress|completed", "activeForm": "Analyzing test requirements"},
+  {"content": "Generate test generation and execution tasks", "status": "pending|in_progress|completed", "activeForm": "Generating test tasks"},
+  {"content": "Return workflow summary", "status": "pending|in_progress|completed", "activeForm": "Returning workflow summary"}
+]})
+```
+
+Update status to `in_progress` when starting each phase, `completed` when done.
+
+---
+
+## Task Specifications
+
+Generates minimum 2 tasks (expandable for complex projects):
+
+### IMPL-001: Test Understanding & Generation
+
+**Agent**: `@code-developer`
+
+**Purpose**: Understand source implementation and generate test files
+
+**Task Configuration**:
+- Task ID: `IMPL-001`
+- `meta.type: "test-gen"`
+- `meta.agent: "@code-developer"`
+- `context.requirements`: Understand source implementation and generate tests
+- `flow_control.target_files`: Test files to create from TEST_ANALYSIS_RESULTS.md section 5
+
+**Execution Flow**:
+1. **Understand Phase**:
+   - Load TEST_ANALYSIS_RESULTS.md and test context
+   - Understand source code implementation patterns
+   - Analyze test requirements and conventions
+   - Identify test scenarios and edge cases
+2. **Generation Phase**:
+   - Generate test files following existing patterns
+   - Ensure test coverage aligns with requirements
+3. **Verification Phase**:
+   - Verify test completeness and correctness
+
+### IMPL-002: Test Execution & Fix Cycle
+
+**Agent**: `@test-fix-agent`
+
+**Purpose**: Execute tests and apply iterative fixes (max 5 iterations)
+
+**Task Configuration**:
+- Task ID: `IMPL-002`
+- `meta.type: "test-fix"`
+- `meta.agent: "@test-fix-agent"`
+- `meta.use_codex: true|false` (based on `--use-codex` flag)
+- `context.depends_on: ["IMPL-001"]`
+- `context.requirements`: Execute and fix tests
+
+**Test-Fix Cycle Specification**:
+- **Cycle Pattern**: test → gemini_diagnose → manual_fix (or codex) → retest
+- **Tools Configuration**:
+  - Gemini for analysis with bug-fix template → surgical fix suggestions
+  - Manual fix application (default) OR Codex if `--use-codex` flag (resume mechanism)
+- **Exit Conditions**:
+  - Success: All tests pass
+  - Failure: Max iterations reached (5)
+
+**Execution Flow**:
+1. **Phase 1**: Initial test execution
+2. **Phase 2**: Iterative Gemini diagnosis + manual/Codex fixes
+3. **Phase 3**: Final validation and certification
+
+### IMPL-003+: Additional Tasks (Optional)
+
+**Scenarios for Multiple Tasks**:
+- Large projects requiring per-module test generation
+- Separate integration vs unit test tasks
+- Specialized test types (performance, security, etc.)
+
+**Agent**: `@code-developer` or specialized agents based on requirements
+
+---
+
+## Artifacts & Output
+
+### Output Files Structure
+
+Created in `.workflow/WFS-test-[session]/`:
+
+```
+WFS-test-[session]/
+├── workflow-session.json          # Session metadata
+├── IMPL_PLAN.md                   # Test generation and execution strategy
+├── TODO_LIST.md                   # Task checklist
+├── .task/
+│   ├── IMPL-001.json              # Test understanding & generation
+│   ├── IMPL-002.json              # Test execution & fix cycle
+│   └── IMPL-*.json                # Additional tasks (if applicable)
+└── .process/
+    ├── [test-]context-package.json # Context and coverage analysis
+    └── TEST_ANALYSIS_RESULTS.md    # Test requirements and strategy
+```
+
+### Session Metadata
+
+**File**: `workflow-session.json`
+
+**Session Mode** includes:
+- `workflow_type: "test_session"`
+- `source_session_id: "[sourceSessionId]"` (enables automatic cross-session context)
+
+**Prompt Mode** includes:
+- `workflow_type: "test_session"`
+- No `source_session_id` field
+
+### Complete Data Flow
+
+**Example Command**: `/workflow:test-fix-gen WFS-user-auth`
+
+**Phase Execution Chain**:
+1. Phase 1: `session-start` → `WFS-test-user-auth`
+2. Phase 2: `test-context-gather` → `test-context-package.json`
+3. Phase 3: `test-concept-enhanced` → `TEST_ANALYSIS_RESULTS.md`
+4. Phase 4: `test-task-generate` → `IMPL-001.json` + `IMPL-002.json` (+ additional if needed)
+5. Phase 5: Return summary
+
+**Command completes after Phase 5**
+
+---
+
+## Reference
+
+### Error Handling
+
+| Phase | Error Condition | Action |
+|-------|----------------|--------|
+| 1 | Source session not found (session mode) | Return error with source session ID |
+| 1 | No completed IMPL tasks (session mode) | Return error, source incomplete |
+| 2 | Context gathering failed | Return error, check source artifacts |
+| 3 | Gemini analysis failed | Return error, check context package |
+| 4 | Task generation failed | Retry once, then return error with details |
+
+### Best Practices
+
+1. **Before Running**:
+   - Ensure implementation is complete (session mode: check summaries exist)
+   - Commit all implementation changes
+   - Review source code quality
+
+2. **After Running**:
+   - Review generated `IMPL_PLAN.md` before execution
+   - Check `TEST_ANALYSIS_RESULTS.md` for completeness
+   - Verify task dependencies in `TODO_LIST.md`
+
+3. **During Execution**:
+   - Monitor iteration logs in `.process/fix-iteration-*`
+   - Track progress with `/workflow:status`
+   - Review Gemini diagnostic outputs
+
+4. **Mode Selection**:
+   - Use **Session Mode** for completed workflow validation
+   - Use **Prompt Mode** for ad-hoc test generation
+   - Use `--use-codex` for autonomous fix application
+   - Use `--cli-execute` for enhanced generation capabilities
+
+### Related Commands
+
+**Planning Phase**:
+- `/workflow:plan` - Create implementation workflow
+- `/workflow:session:start` - Initialize workflow session
+
+**Context Gathering**:
+- `/workflow:tools:test-context-gather` - Session-based context (Phase 2 for session mode)
+- `/workflow:tools:context-gather` - Prompt-based context (Phase 2 for prompt mode)
+
+**Analysis & Task Generation**:
+- `/workflow:tools:test-concept-enhanced` - Gemini test analysis (Phase 3)
+- `/workflow:tools:test-task-generate` - Generate test tasks (Phase 4)
+
+**Execution**:
+- `/workflow:test-cycle-execute` - Execute test-fix workflow (recommended for IMPL-002)
+- `/workflow:execute` - Execute standard workflow tasks
+- `/workflow:status` - Check task progress
+
+**Review & Management**:
+- `/workflow:review` - Review workflow results
+- `/workflow:session:complete` - Mark session complete

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

@@ -24,16 +24,19 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 3. Analyze implementation with concept-enhanced → Parse ANALYSIS_RESULTS.md
 4. Generate test task from analysis → Return summary
 
+**⚠️ Command Scope**: This command ONLY prepares test workflow artifacts. It does NOT execute tests or implementation. Task execution requires separate user action.
+
 ## Core Rules
 
 1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 test session creation
 2. **No Preliminary Analysis**: Do not read files or analyze before Phase 1
 3. **Parse Every Output**: Extract required data from each phase for next phase
 4. **Sequential Execution**: Each phase depends on previous phase's output
-5. **Complete All Phases**: Do not return to user until Phase 4 completes (execution triggered separately)
+5. **Complete All Phases**: Do not return to user until Phase 5 completes (summary returned)
 6. **Track Progress**: Update TodoWrite after every phase completion
 7. **Automatic Detection**: context-gather auto-detects test session and gathers source session context
 8. **Parse --use-codex Flag**: Extract flag from arguments and pass to Phase 4 (test-task-generate)
+9. **⚠️ Command Boundary**: This command ends at Phase 5 summary. Test execution is NOT part of this command.
 
 ## 5-Phase Execution
 
@@ -174,32 +177,39 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 
 ---
 
-### Phase 5: Return Summary to User
+### Phase 5: Return Summary (⚠️ Command Ends Here)
+
+**⚠️ Important**: This is the final phase of `/workflow:test-gen`. The command completes and returns control to the user. No automatic execution occurs.
 
 **Return to User**:
 ```
-Independent test-fix workflow created successfully!
+✅ Test workflow preparation complete!
 
 Source Session: [sourceSessionId]
 Test Session: [testSessionId]
 
-Tasks Created:
-- IMPL-001: Test Generation (@code-developer)
-- IMPL-002: Test Execution & Fix Cycle (@test-fix-agent)
+Artifacts Created:
+- Test context analysis
+- Test generation strategy
+- Task definitions (IMPL-001, IMPL-002)
+- Implementation plan
 
 Test Framework: [detected framework]
 Test Files to Generate: [count]
-Max Fix Iterations: 5
 Fix Mode: [Manual|Codex Automated] (based on --use-codex flag)
 
-Next Steps:
-1. Review test plan: .workflow/[testSessionId]/IMPL_PLAN.md
-2. Execute workflow: /workflow:execute
-3. Monitor progress: /workflow:status
+📋 Review Generated Artifacts:
+- Test plan: .workflow/[testSessionId]/IMPL_PLAN.md
+- Task list: .workflow/[testSessionId]/TODO_LIST.md
+- Analysis: .workflow/[testSessionId]/.process/TEST_ANALYSIS_RESULTS.md
+
+⚠️ Ready for execution. Use appropriate workflow commands to proceed.
 ```
 
 **TodoWrite**: Mark phase 5 completed
 
+**⚠️ Command Boundary**: After this phase, the command terminates and returns to user prompt.
+
 ---
 
 ## TodoWrite Pattern
@@ -221,19 +231,32 @@ Update status to `in_progress` when starting each phase, mark `completed` when d
 ## Data Flow
 
 ```
-/workflow:test-gen WFS-user-auth
-  ↓
-Phase 1: session-start → WFS-test-user-auth
-  ↓
-Phase 2: test-context-gather → test-context-package.json
-  ↓
-Phase 3: test-concept-enhanced → TEST_ANALYSIS_RESULTS.md
-  ↓
-Phase 4: test-task-generate → IMPL-001.json + IMPL-002.json
-  ↓
-Phase 5: Return summary
-  ↓
-/workflow:execute → IMPL-001 (@code-developer) → IMPL-002 (@test-fix-agent)
+┌─────────────────────────────────────────────────────────┐
+│ /workflow:test-gen WFS-user-auth                        │
+├─────────────────────────────────────────────────────────┤
+│ Phase 1: session-start → WFS-test-user-auth            │
+│   ↓                                                     │
+│ Phase 2: test-context-gather → test-context-package.json│
+│   ↓                                                     │
+│ Phase 3: test-concept-enhanced → TEST_ANALYSIS_RESULTS.md│
+│   ↓                                                     │
+│ Phase 4: test-task-generate → IMPL-001.json + IMPL-002.json│
+│   ↓                                                     │
+│ Phase 5: Return summary                                │
+└─────────────────────────────────────────────────────────┘
+         ⚠️ COMMAND ENDS - Control returns to user
+
+Artifacts Created:
+├── .workflow/WFS-test-[session]/
+│   ├── workflow-session.json
+│   ├── IMPL_PLAN.md
+│   ├── TODO_LIST.md
+│   ├── .task/
+│   │   ├── IMPL-001.json (test generation task)
+│   │   └── IMPL-002.json (test execution task)
+│   └── .process/
+│       ├── test-context-package.json
+│       └── TEST_ANALYSIS_RESULTS.md
 ```
 
 ## Session Metadata
@@ -242,9 +265,16 @@ Test session includes `workflow_type: "test_session"` and `source_session_id` fo
 
 ## Task Output
 
-Generates two tasks:
-- **IMPL-001** (@code-developer): Test generation from TEST_ANALYSIS_RESULTS.md
-- **IMPL-002** (@test-fix-agent): Test execution with iterative fix cycle (max 5 iterations)
+Generates two task definition files:
+- **IMPL-001.json**: Test generation task specification
+  - Agent: @code-developer
+  - Input: TEST_ANALYSIS_RESULTS.md
+  - Output: Test files based on analysis
+- **IMPL-002.json**: Test execution and fix cycle specification
+  - Agent: @test-fix-agent
+  - Dependency: IMPL-001 must complete first
+  - Max iterations: 5
+  - Fix mode: Manual or Codex (based on --use-codex flag)
 
 See `/workflow:tools:test-task-generate` for complete task JSON schemas.
 
@@ -269,28 +299,34 @@ Created in `.workflow/WFS-test-[session]/`:
 - `IMPL_PLAN.md` - Test plan
 - `TODO_LIST.md` - Task checklist
 
-## Agent Execution
+## Task Specifications
 
-**IMPL-001** (@code-developer):
-- Generates test files based on TEST_ANALYSIS_RESULTS.md
-- Follows existing test patterns and conventions
+**IMPL-001.json Structure**:
+- `meta.type: "test-gen"`
+- `meta.agent: "@code-developer"`
+- `context.requirements`: Generate tests based on TEST_ANALYSIS_RESULTS.md
+- `flow_control.target_files`: Test files to create
+- `flow_control.implementation_approach`: Test generation strategy
 
-**IMPL-002** (@test-fix-agent):
-1. Run test suite
-2. Iterative fix cycle (max 5):
-   - Gemini diagnosis with bug-fix template → surgical fix suggestions
-   - Manual fix application (default) OR Codex applies fixes if --use-codex flag (resume mechanism)
-   - Retest and check regressions
-3. Final validation and certification
+**IMPL-002.json Structure**:
+- `meta.type: "test-fix"`
+- `meta.agent: "@test-fix-agent"`
+- `meta.use_codex`: true/false (based on --use-codex flag)
+- `context.depends_on: ["IMPL-001"]`
+- `flow_control.implementation_approach.test_fix_cycle`: Complete cycle specification
+  - Gemini diagnosis template
+  - Fix application mode (manual/codex)
+  - Max iterations: 5
+- `flow_control.implementation_approach.modification_points`: 3-phase flow
 
-See `/workflow:tools:test-task-generate` for detailed specifications.
+See `/workflow:tools:test-task-generate` for complete JSON schemas.
 
 ## Best Practices
 
-1. Run after implementation complete (ensure source session has summaries)
-2. Commit implementation changes before test-gen
-3. Monitor execution with `/workflow:status`
-4. Review iteration logs in `.process/fix-iteration-*`
+1. **Prerequisites**: Ensure source session has completed IMPL tasks with summaries
+2. **Clean State**: Commit implementation changes before running test-gen
+3. **Review Artifacts**: Check generated IMPL_PLAN.md and TODO_LIST.md before proceeding
+4. **Understand Scope**: This command only prepares artifacts; it does not execute tests
 
 ## Related Commands
 

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

@@ -8,12 +8,47 @@ allowed-tools: Read(*), Write(*), Bash(gemini-wrapper:*), TodoWrite(*)
 # TDD Task Generation Command
 
 ## Overview
-Generate TDD-specific task chains from analysis results with enforced Red-Green-Refactor structure and dependencies.
+Generate TDD-specific tasks from analysis results with complete Red-Green-Refactor cycles contained within each task.
 
-## Core Philosophy
-- **TDD-First**: Every feature starts with a failing test
-- **Chain-Enforced**: Dependencies ensure proper TDD cycle
-- **Phase-Explicit**: Each task marked with Red/Green/Refactor phase
+## Task Strategy & Philosophy
+
+### Optimized Task Structure (Current)
+- **1 feature = 1 task** containing complete TDD cycle internally
+- Each task executes Red-Green-Refactor phases sequentially
+- Task count = Feature count (typically 5 features = 5 tasks)
+- **Benefits**:
+  - 70% reduction in task management overhead
+  - Continuous context per feature (no switching between TEST/IMPL/REFACTOR)
+  - Simpler dependency management
+  - Maintains TDD rigor through internal phase structure
+
+**Previous Approach** (Deprecated):
+- 1 feature = 3 separate tasks (TEST-N.M, IMPL-N.M, REFACTOR-N.M)
+- 5 features = 15 tasks with complex dependency chains
+- High context switching cost between phases
+
+### When to Use Subtasks
+- Feature complexity >2500 lines or >6 files per TDD cycle
+- Multiple independent sub-features needing parallel execution
+- Strong technical dependency blocking (e.g., API before UI)
+- Different tech stacks or domains within feature
+
+### Task Limits
+- **Maximum 10 tasks** (hard limit for TDD workflows)
+- **Feature-based**: Complete functional units with internal TDD cycles
+- **Hierarchy**: Flat (≤5 simple features) | Two-level (6-10 for complex features with sub-features)
+- **Re-scope**: If >10 tasks needed, break project into multiple TDD workflow sessions
+
+### TDD Cycle Mapping
+- **Old approach**: 1 feature = 3 tasks (TEST-N.M, IMPL-N.M, REFACTOR-N.M)
+- **Current approach**: 1 feature = 1 task (IMPL-N with internal Red-Green-Refactor phases)
+- **Complex features**: 1 container (IMPL-N) + subtasks (IMPL-N.M) when necessary
+
+### Core Principles
+- **TDD-First**: Every feature starts with a failing test (Red phase)
+- **Feature-Complete Tasks**: Each task contains complete Red-Green-Refactor cycle
+- **Phase-Explicit**: Internal phases clearly marked in flow_control.implementation_approach
+- **Task Merging**: Prefer single task per feature over decomposition
 - **Artifact-Aware**: Integrates brainstorming outputs
 - **Memory-First**: Reuse loaded documents from memory
 - **Context-Aware**: Analyzes existing codebase and test patterns
@@ -22,16 +57,16 @@ Generate TDD-specific task chains from analysis results with enforced Red-Green-
 
 ## Core Responsibilities
 - Parse analysis results and identify testable features
-- Generate Red-Green-Refactor task chains for each feature
-- Enforce proper dependencies (TEST → IMPL → REFACTOR)
-- Create TDD_PLAN.md and enhanced IMPL_PLAN.md
-- Generate TODO_LIST.md with TDD phase indicators
-- Update session state for TDD execution
+- Generate feature-complete tasks with internal TDD cycles (1 task per simple feature)
+- Apply task merging strategy by default, create subtasks only when complexity requires
+- Generate IMPL_PLAN.md with TDD Implementation Tasks section
+- Generate TODO_LIST.md with internal TDD phase indicators
+- Update session state for TDD execution with task count compliance
 
 ## Execution Lifecycle
 
 ### Phase 1: Input Validation & Discovery
-**⚡ Memory-First Rule**: Skip file loading if documents already in conversation memory
+**Memory-First Rule**: Skip file loading if documents already in conversation memory
 
 1. **Session Validation**
    - If session metadata in memory → Skip loading
@@ -50,584 +85,352 @@ Generate TDD-specific task chains from analysis results with enforced Red-Green-
 
 **Input**: Use `.process/ANALYSIS_RESULTS.md` directly (enhanced with TDD structure from concept-enhanced phase)
 
-**Note**: The ANALYSIS_RESULTS.md now includes TDD-specific breakdown:
+**ANALYSIS_RESULTS.md includes**:
 - Feature list with testable requirements
 - Test cases for Red phase
 - Implementation requirements for Green phase
 - Refactoring opportunities
 - Task dependencies and execution order
 
-### Phase 3: Enhanced IMPL_PLAN.md Generation
+### Phase 3: Task JSON & IMPL_PLAN.md Generation
 
-#### Task Chain Structure
-For each feature, generate 3 tasks with ID format:
-- **TEST-N.M** (Red phase)
-- **IMPL-N.M** (Green phase)
-- **REFACTOR-N.M** (Refactor phase)
+#### Task Structure (Feature-Complete with Internal TDD)
+For each feature, generate task(s) with ID format:
+- **IMPL-N** - Single task containing complete TDD cycle (Red-Green-Refactor)
+- **IMPL-N.M** - Sub-tasks only when feature is complex (>2500 lines or technical blocking)
 
-#### Chain Dependency Rules
-- **IMPL depends_on TEST**: Cannot implement before test exists
-- **REFACTOR depends_on IMPL**: Cannot refactor before implementation
-- **Cross-feature dependencies**: If Feature 2 needs Feature 1, then `IMPL-2.1 depends_on ["REFACTOR-1.1"]`
+**Task Dependency Rules**:
+- **Sequential features**: IMPL-2 depends_on ["IMPL-1"] if Feature 2 needs Feature 1
+- **Independent features**: No dependencies, can execute in parallel
+- **Complex features**: IMPL-N.2 depends_on ["IMPL-N.1"] for subtask ordering
 
-#### Agent Assignment
-- **TEST tasks** → `@code-review-test-agent`
-- **IMPL tasks** → `@code-developer`
-- **REFACTOR tasks** → `@code-developer`
+**Agent Assignment**:
+- **All IMPL tasks** → `@code-developer` (handles full TDD cycle)
+- Agent executes Red, Green, Refactor phases sequentially within task
 
-#### Meta Fields
-- `meta.type`: "test" | "feature" | "refactor"
-- `meta.agent`: Agent for task execution
-- `meta.tdd_phase`: "red" | "green" | "refactor"
+**Meta Fields**:
+- `meta.type`: "feature" (TDD-driven feature implementation)
+- `meta.agent`: "@code-developer"
+- `meta.tdd_workflow`: true (enables TDD-specific flow)
+- `meta.tdd_phase`: Not used (phases are in flow_control.implementation_approach)
+- `meta.max_iterations`: 3 (for Green phase test-fix cycle)
+- `meta.use_codex`: false (manual fixes by default)
 
-#### Task JSON Examples
+#### Task JSON Structure Reference
 
-**RED Phase - Test Task (TEST-1.1.json)**
+**Simple Feature Task (IMPL-N.json)** - Recommended for most features:
 ```json
 {
-  "id": "TEST-1.1",
-  "title": "Write failing test for user authentication",
-  "status": "pending",
+  "id": "IMPL-N",                                  // Task identifier
+  "title": "Feature description with TDD",         // Human-readable title
+  "status": "pending",                             // pending | in_progress | completed | container
   "meta": {
-    "type": "test",
-    "agent": "@code-review-test-agent",
-    "tdd_phase": "red"
+    "type": "feature",                             // Task type
+    "agent": "@code-developer",                    // Assigned agent
+    "tdd_workflow": true,                          // REQUIRED: Enables TDD flow
+    "max_iterations": 3,                           // Green phase test-fix cycle limit
+    "use_codex": false                             // false=manual fixes, true=Codex automated fixes
   },
   "context": {
-    "requirements": [
-      "Write test case for login with valid credentials",
-      "Test should fail with 'AuthService not implemented' error",
-      "Include tests for invalid credentials and edge cases"
+    "requirements": [                              // Feature requirements with TDD phases
+      "Feature description",
+      "Red: Test scenarios to write",
+      "Green: Implementation approach with test-fix cycle",
+      "Refactor: Code quality improvements"
     ],
-    "focus_paths": ["tests/auth/login.test.ts"],
-    "acceptance": [
-      "Test file created with at least 3 test cases",
-      "Test runs and fails with clear error message",
-      "Test assertions define expected behavior"
+    "tdd_cycles": [                                // OPTIONAL: Detailed test cycles
+      {
+        "cycle": 1,
+        "feature": "Specific functionality",
+        "test_focus": "What to test",
+        "expected_failure": "Why test should fail initially"
+      }
     ],
-    "depends_on": []
+    "focus_paths": ["src/path/", "tests/path/"],  // Files to modify
+    "acceptance": [                                // Success criteria
+      "All tests pass (Red → Green)",
+      "Code refactored (Refactor complete)",
+      "Test coverage ≥80%"
+    ],
+    "depends_on": []                               // Task dependencies
   },
   "flow_control": {
-    "pre_analysis": [
+    "pre_analysis": [                              // OPTIONAL: Pre-execution checks
       {
         "step": "check_test_framework",
-        "action": "Verify test framework is configured",
-        "command": "bash(npm list jest || npm list vitest)",
+        "action": "Verify test framework",
+        "command": "bash(npm list jest)",
         "output_to": "test_framework_info",
         "on_error": "warn"
       }
-    ]
-  }
-}
-```
-
-**GREEN Phase - Implementation Task (IMPL-1.1.json)**
-```json
-{
-  "id": "IMPL-1.1",
-  "title": "Implement user authentication to pass tests",
-  "status": "pending",
-  "meta": {
-    "type": "feature",
-    "agent": "@code-developer",
-    "tdd_phase": "green",
-    "max_iterations": 3,
-    "use_codex": false
-  },
-  "context": {
-    "requirements": [
-      "Implement minimal AuthService to pass TEST-1.1",
-      "Handle valid and invalid credentials",
-      "Return appropriate success/error responses",
-      "If tests fail after implementation, diagnose and fix iteratively"
     ],
-    "focus_paths": ["src/auth/AuthService.ts", "tests/auth/login.test.ts"],
-    "acceptance": [
-      "All tests in TEST-1.1 pass",
-      "Implementation is minimal and focused",
-      "No over-engineering or premature optimization",
-      "Test failures resolved within iteration limit"
-    ],
-    "depends_on": ["TEST-1.1"]
-  },
-  "flow_control": {
-    "pre_analysis": [
-      {
-        "step": "load_test_requirements",
-        "action": "Read test specifications from TEST phase",
-        "command": "bash(cat .workflow/WFS-xxx/.summaries/TEST-1.1-summary.md)",
-        "output_to": "test_requirements",
-        "on_error": "fail"
-      },
-      {
-        "step": "verify_tests_failing",
-        "action": "Confirm tests are currently failing (Red phase validation)",
-        "command": "bash(npm test -- tests/auth/login.test.ts || echo 'Tests failing as expected')",
-        "output_to": "initial_test_status",
-        "on_error": "warn"
-      },
-      {
-        "step": "load_test_context",
-        "action": "Load test patterns and framework info",
-        "command": "bash(cat .workflow/WFS-xxx/.process/test-context-package.json 2>/dev/null || echo '{}')",
-        "output_to": "test_context",
-        "on_error": "skip_optional"
-      }
-    ],
-    "implementation_approach": [
+    "implementation_approach": [                   // REQUIRED: 3 TDD phases
       {
         "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"
-        ],
+        "title": "RED Phase: Write failing tests",
+        "tdd_phase": "red",                        // REQUIRED: Phase identifier
+        "description": "Write comprehensive failing tests",
+        "modification_points": ["Files/changes to make"],
+        "logic_flow": ["Step-by-step process"],
+        "acceptance": ["Phase success criteria"],
         "depends_on": [],
-        "output": "initial_implementation"
+        "output": "failing_tests"
       },
       {
         "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"
-        ],
+        "title": "GREEN Phase: Implement to pass tests",
+        "tdd_phase": "green",                      // REQUIRED: Phase identifier
+        "description": "Minimal implementation with test-fix cycle",
+        "modification_points": ["Implementation files"],
         "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"
+          "Implement minimal code",
+          "Run tests",
+          "If fail → Enter iteration loop (max 3):",
+          "  1. Extract failure messages",
+          "  2. Gemini bug-fix diagnosis",
+          "  3. Apply fixes",
+          "  4. Rerun tests",
+          "If max_iterations → Auto-revert"
         ],
-        "command": "bash(npm test -- tests/auth/login.test.ts)",
+        "acceptance": ["All tests pass"],
+        "command": "bash(npm test -- tests/path/)",
         "depends_on": [1],
-        "output": "test_results"
+        "output": "passing_implementation"
+      },
+      {
+        "step": 3,
+        "title": "REFACTOR Phase: Improve code quality",
+        "tdd_phase": "refactor",                   // REQUIRED: Phase identifier
+        "description": "Refactor while keeping tests green",
+        "modification_points": ["Quality improvements"],
+        "logic_flow": ["Incremental refactoring with test verification"],
+        "acceptance": ["Tests still pass", "Code quality improved"],
+        "command": "bash(npm run lint && npm test)",
+        "depends_on": [2],
+        "output": "refactored_implementation"
       }
     ],
-    "post_completion": [
+    "post_completion": [                           // OPTIONAL: Final verification
       {
-        "step": "verify_tests_passing",
-        "action": "Confirm all tests now pass (Green phase achieved)",
-        "command": "bash(npm test -- tests/auth/login.test.ts)",
-        "output_to": "final_test_status",
+        "step": "verify_full_tdd_cycle",
+        "action": "Confirm complete TDD cycle",
+        "command": "bash(npm test && echo 'TDD complete')",
+        "output_to": "final_validation",
         "on_error": "fail"
       }
     ],
-    "error_handling": {
-      "max_iterations_reached": {
+    "error_handling": {                            // OPTIONAL: Error recovery
+      "green_phase_max_iterations": {
         "action": "revert_all_changes",
-        "commands": [
-          "bash(git reset --hard HEAD)",
-          "bash(echo 'TDD Green phase failed: Unable to pass tests within 3 iterations' > .workflow/WFS-xxx/.process/green-phase-failure.md)"
-        ],
-        "report": "Generate failure report in .summaries/IMPL-1.1-failure-report.md"
+        "commands": ["bash(git reset --hard HEAD)"],
+        "report": "Generate failure report"
       }
     }
   }
 }
 ```
 
-**REFACTOR Phase - Refactoring Task (REFACTOR-1.1.json)**
-```json
-{
-  "id": "REFACTOR-1.1",
-  "title": "Refactor authentication implementation",
-  "status": "pending",
-  "meta": {
-    "type": "refactor",
-    "agent": "@code-developer",
-    "tdd_phase": "refactor"
-  },
-  "context": {
-    "requirements": [
-      "Improve code quality while keeping tests green",
-      "Remove duplication in credential validation",
-      "Improve error handling and logging",
-      "Enhance code readability and maintainability"
-    ],
-    "focus_paths": ["src/auth/AuthService.ts", "tests/auth/login.test.ts"],
-    "acceptance": [
-      "Code quality improved (complexity, readability)",
-      "All tests still pass after refactoring",
-      "No new functionality added",
-      "Duplication eliminated"
-    ],
-    "depends_on": ["IMPL-1.1"]
-  },
-  "flow_control": {
-    "pre_analysis": [
-      {
-        "step": "verify_tests_passing",
-        "action": "Run tests to confirm green state before refactoring",
-        "command": "bash(npm test -- tests/auth/login.test.ts)",
-        "output_to": "test_status",
-        "on_error": "fail"
-      },
-      {
-        "step": "analyze_code_quality",
-        "action": "Run linter and complexity analysis",
-        "command": "bash(npm run lint src/auth/AuthService.ts)",
-        "output_to": "quality_metrics",
-        "on_error": "warn"
-      }
-    ],
-    "post_completion": [
-      {
-        "step": "verify_tests_still_passing",
-        "action": "Confirm tests remain green after refactoring",
-        "command": "bash(npm test -- tests/auth/login.test.ts)",
-        "output_to": "final_test_status",
-        "on_error": "fail"
-      }
-    ]
-  }
-}
-```
+**Key JSON Fields Summary**:
+- `meta.tdd_workflow`: Must be `true`
+- `meta.max_iterations`: Green phase fix cycle limit (default: 3)
+- `meta.use_codex`: Automated fixes (false=manual, true=Codex)
+- `flow_control.implementation_approach`: Exactly 3 steps with `tdd_phase`: "red", "green", "refactor"
+- `context.tdd_cycles`: Optional detailed test cycle specifications
+- `context.parent`: Required for subtasks (IMPL-N.M)
 
-### Phase 4: Unified IMPL_PLAN.md Generation
+#### IMPL_PLAN.md Structure
 
-Generate single comprehensive IMPL_PLAN.md with enhanced 8-section structure:
+Generate IMPL_PLAN.md with 8-section structure:
 
-**Frontmatter**:
+**Frontmatter** (required fields):
 ```yaml
 ---
 identifier: WFS-{session-id}
-source: "User requirements" | "File: path" | "Issue: ISS-001"
+source: "User requirements" | "File: path"
 analysis: .workflow/{session-id}/.process/ANALYSIS_RESULTS.md
-artifacts: .workflow/{session-id}/.brainstorming/
-context_package: .workflow/{session-id}/.process/context-package.json  # CCW smart context
-workflow_type: "tdd"  # TDD-specific workflow
-verification_history:  # CCW quality gates
+context_package: .workflow/{session-id}/.process/context-package.json
+workflow_type: "tdd"
+verification_history:
   concept_verify: "passed | skipped | pending"
   action_plan_verify: "pending"
-phase_progression: "brainstorm → context → test_context → analysis → concept_verify → tdd_planning"  # TDD workflow phases
+phase_progression: "brainstorm → context → test_context → analysis → concept_verify → tdd_planning"
 feature_count: N
-task_count: 3N
-tdd_chains: N
+task_count: N  # ≤10 total
+task_breakdown:
+  simple_features: K
+  complex_features: L
+  total_subtasks: M
+tdd_workflow: true
 ---
 ```
 
-**Complete Structure** (8 Sections):
+**8 Sections Structure**:
 
 ```markdown
 # Implementation Plan: {Project Title}
 
 ## 1. Summary
-Core requirements, objectives, and TDD-specific technical approach (2-3 paragraphs max).
-
-**Core Objectives**:
-- [Key objective 1]
-- [Key objective 2]
-
-**Technical Approach**:
-- TDD-driven development with Red-Green-Refactor cycles
-- [Other high-level approaches]
+- Core requirements and objectives (2-3 paragraphs)
+- TDD-specific technical approach
 
 ## 2. Context Analysis
-
-### CCW Workflow Context
-**Phase Progression** (TDD-specific):
-- ✅ Phase 1: Brainstorming (synthesis-specification.md generated)
-- ✅ Phase 2: Context Gathering (context-package.json: {N} files, {M} modules analyzed)
-- ✅ Phase 3: Test Coverage Analysis (test-context-package.json: existing test patterns identified)
-- ✅ Phase 4: TDD Analysis (ANALYSIS_RESULTS.md: test-first requirements with Gemini/Qwen insights)
-- ✅ Phase 5: Concept Verification ({X} clarifications answered, test requirements clarified | skipped)
-- ⏳ Phase 6: TDD Task Generation (current phase - generating IMPL_PLAN.md with TDD chains)
-
-**Quality Gates**:
-- concept-verify: ✅ Passed (test requirements clarified, 0 ambiguities) | ⏭️ Skipped (user decision) | ⏳ Pending
-- action-plan-verify: ⏳ Pending (recommended before /workflow:execute for TDD dependency validation)
-
-**Context Package Summary**:
-- **Focus Paths**: {list key directories from context-package.json}
-- **Key Files**: {list primary files for modification}
-- **Test Context**: {existing test patterns, coverage baseline, test framework detected}
-- **Module Depth Analysis**: {from get_modules_by_depth.sh output}
-- **Smart Context**: {total file count} files, {module count} modules, {test file count} tests identified
-
-### Project Profile
-- **Type**: Greenfield/Enhancement/Refactor
-- **Scale**: User count, data volume, complexity
-- **Tech Stack**: Primary technologies
-- **Timeline**: Duration and milestones
-- **TDD Framework**: Testing framework and tools
-
-### Module Structure
-```
-[Directory tree showing key modules and test directories]
-```
-
-### Dependencies
-**Primary**: [Core libraries and frameworks]
-**Testing**: [Test framework, mocking libraries]
-**Development**: [Linting, CI/CD tools]
-
-### Patterns & Conventions
-- **Architecture**: [Key patterns]
-- **Testing Patterns**: [Unit, integration, E2E patterns]
-- **Code Style**: [Naming, TypeScript coverage]
+- CCW Workflow Context (Phase progression, Quality gates)
+- Context Package Summary (Focus paths, Test context)
+- Project Profile (Type, Scale, Tech Stack, Timeline)
+- Module Structure (Directory tree)
+- Dependencies (Primary, Testing, Development)
+- Patterns & Conventions
 
 ## 3. Brainstorming Artifacts Reference
-
-### Artifact Usage Strategy
-**Primary Reference (synthesis-specification.md)**:
-- **What**: Comprehensive implementation blueprint from multi-role synthesis
-- **When**: Every TDD task (TEST/IMPL/REFACTOR) references this for requirements and acceptance criteria
-- **How**: Extract testable requirements, architecture decisions, expected behaviors
-- **Priority**: Authoritative - defines what to test and how to implement
-- **CCW Value**: Consolidates insights from all brainstorming roles into single source of truth for TDD
-
-**Context Intelligence (context-package.json & test-context-package.json)**:
-- **What**: Smart context from CCW's context-gather and test-context-gather phases
-- **Content**: Focus paths, dependency graph, existing test patterns, test framework configuration
-- **Usage**: RED phase loads test patterns, GREEN phase loads implementation context
-- **CCW Value**: Automated discovery of existing tests and patterns for TDD consistency
-
-**Technical Analysis (ANALYSIS_RESULTS.md)**:
-- **What**: Gemini/Qwen parallel analysis with TDD-specific breakdown
-- **Content**: Testable requirements, test scenarios, implementation strategies, risk assessment
-- **Usage**: RED phase references test cases, GREEN phase references implementation approach
-- **CCW Value**: Multi-model analysis providing comprehensive TDD guidance
-
-### Integrated Specifications (Highest Priority)
-- **synthesis-specification.md**: Comprehensive implementation blueprint
-  - Contains: Architecture design, functional/non-functional requirements
-
-### Supporting Artifacts (Reference)
-- **topic-framework.md**: Discussion framework
-- **system-architect/analysis.md**: Architecture specifications
-- **Role-specific analyses**: [Other relevant analyses]
-
-**Artifact Priority in Development**:
-1. synthesis-specification.md (primary reference for test cases and implementation)
-2. test-context-package.json (existing test patterns for TDD consistency)
-3. context-package.json (smart context for execution environment)
-4. ANALYSIS_RESULTS.md (technical analysis with TDD breakdown)
-5. Role-specific analyses (supplementary)
+- Artifact Usage Strategy
+  - synthesis-specification.md (primary reference)
+  - test-context-package.json (test patterns)
+  - context-package.json (smart context)
+  - ANALYSIS_RESULTS.md (technical analysis)
+- Artifact Priority in Development
 
 ## 4. Implementation Strategy
+- Execution Strategy (TDD Cycles: Red-Green-Refactor)
+- Architectural Approach
+- Key Dependencies (Task dependency graph)
+- Testing Strategy (Coverage targets, Quality gates)
 
-### Execution Strategy
-**Execution Model**: TDD Cycles (Red-Green-Refactor)
-
-**Rationale**: Test-first approach ensures correctness and reduces bugs
-
-**TDD Cycle Pattern**:
-- RED: Write failing test
-- GREEN: Implement minimal code to pass (with test-fix cycle if needed)
-- REFACTOR: Improve code quality while keeping tests green
-
-**Parallelization Opportunities**:
-- [Independent features that can be developed in parallel]
-
-### Architectural Approach
-**Key Architecture Decisions**:
-- [ADR references from synthesis]
-- [TDD-compatible architecture patterns]
-
-**Integration Strategy**:
-- [How modules communicate]
-- [Test isolation strategy]
-
-### Key Dependencies
-**Task Dependency Graph**:
-```
-Feature 1:
-  TEST-1.1 (RED)
-      ↓
-  IMPL-1.1 (GREEN) [with test-fix cycle]
-      ↓
-  REFACTOR-1.1 (REFACTOR)
-
-Feature 2:
-  TEST-2.1 (RED) [depends on REFACTOR-1.1 if related]
-      ↓
-  IMPL-2.1 (GREEN)
-      ↓
-  REFACTOR-2.1 (REFACTOR)
-```
-
-**Critical Path**: [Identify bottleneck features]
-
-### Testing Strategy
-**TDD Testing Approach**:
-- Unit testing: Each feature has comprehensive unit tests
-- Integration testing: Cross-feature integration
-- E2E testing: Critical user flows after all TDD cycles
-
-**Coverage Targets**:
-- Lines: ≥80% (TDD ensures high coverage)
-- Functions: ≥80%
-- Branches: ≥75%
-
-**Quality Gates**:
-- All tests must pass before moving to next phase
-- Refactor phase must maintain test success
-
-## 5. TDD Task Chains (TDD-Specific Section)
-
-### Feature-by-Feature TDD Chains
-
-**Feature 1: {Feature Name}**
-```
-🔴 TEST-1.1: Write failing test for {feature}
-    ↓
-🟢 IMPL-1.1: Implement to pass tests (includes test-fix cycle: max 3 iterations)
-    ↓
-🔵 REFACTOR-1.1: Refactor implementation while keeping tests green
-```
-
-**Feature 2: {Feature Name}**
-```
-🔴 TEST-2.1: Write failing test for {feature}
-    ↓
-🟢 IMPL-2.1: Implement to pass tests (includes test-fix cycle)
-    ↓
-🔵 REFACTOR-2.1: Refactor implementation
-```
-
-[Continue for all N features]
-
-### TDD Task Breakdown Summary
-- **Total Features**: {N}
-- **Total Tasks**: {3N} (N TEST + N IMPL + N REFACTOR)
-- **TDD Chains**: {N}
+## 5. TDD Implementation Tasks
+- Feature-by-Feature TDD Tasks
+  - Each task: IMPL-N with internal Red → Green → Refactor
+  - Dependencies and complexity metrics
+- Complex Feature Examples (when subtasks needed)
+- TDD Task Breakdown Summary
 
 ## 6. Implementation Plan (Detailed Phased Breakdown)
-
-### Execution Strategy
-
-**TDD Cycle Execution**: Feature-by-feature sequential TDD cycles
-
-**Phase 1 (Weeks 1-2): Foundation Features**
-- **Features**: Feature 1, Feature 2
-- **Tasks**: TEST-1.1, IMPL-1.1, REFACTOR-1.1, TEST-2.1, IMPL-2.1, REFACTOR-2.1
-- **Deliverables**:
-  - Complete TDD cycles for foundation features
-  - All tests passing
-- **Success Criteria**:
-  - ≥80% test coverage
-  - All RED-GREEN-REFACTOR cycles completed
-
-**Phase 2 (Weeks 3-N): Advanced Features**
-[Continue with remaining features]
-
-### Resource Requirements
-
-**Development Team**:
-- [Team composition with TDD experience]
-
-**External Dependencies**:
-- [Testing frameworks, mocking services]
-
-**Infrastructure**:
-- [CI/CD with test automation]
+- Execution Strategy (feature-by-feature sequential)
+- Phase breakdown (Phase 1, Phase 2, etc.)
+- Resource Requirements (Team, Dependencies, Infrastructure)
 
 ## 7. Risk Assessment & Mitigation
-
-| Risk | Impact | Probability | Mitigation Strategy | Owner |
-|------|--------|-------------|---------------------|-------|
-| Tests fail repeatedly in GREEN phase | High | Medium | Test-fix cycle (max 3 iterations) with auto-revert | Dev Team |
-| Complex features hard to test | High | Medium | Break down into smaller testable units | Architect |
-| [Other risks] | Med/Low | Med/Low | [Strategies] | [Owner] |
-
-**Critical Risks** (TDD-Specific):
-- **GREEN phase failures**: Mitigated by test-fix cycle with Gemini diagnosis
-- **Test coverage gaps**: Mitigated by TDD-first approach ensuring tests before code
-
-**Monitoring Strategy**:
-- Track TDD cycle completion rate
-- Monitor test success rate per iteration
+- Risk table (Risk, Impact, Probability, Mitigation, Owner)
+- Critical Risks (TDD-specific)
+- Monitoring Strategy
 
 ## 8. Success Criteria
-
-**Functional Completeness**:
-- [ ] All features implemented through TDD cycles
-- [ ] All RED-GREEN-REFACTOR cycles completed successfully
-
-**Technical Quality**:
-- [ ] Test coverage ≥80% (ensured by TDD)
-- [ ] All tests passing (GREEN state achieved)
-- [ ] Code refactored for quality (REFACTOR phase completed)
-
-**Operational Readiness**:
-- [ ] CI/CD pipeline with automated test execution
-- [ ] Test failure alerting configured
-
-**TDD Compliance**:
-- [ ] Every feature has TEST → IMPL → REFACTOR chain
-- [ ] No implementation without tests (RED-first principle)
-- [ ] Refactoring did not break tests
+- Functional Completeness
+- Technical Quality (Test coverage ≥80%)
+- Operational Readiness
+- TDD Compliance
 ```
 
-### Phase 5: TODO_LIST.md Generation
+### Phase 4: TODO_LIST.md Generation
 
-Generate task list with TDD phase indicators:
+Generate task list with internal TDD phase indicators:
+
+**For Simple Features (1 task per feature)**:
 ```markdown
-## Feature 1: {Feature Name}
-- [ ] **TEST-1.1**: Write failing test (🔴 RED) → [📋](./.task/TEST-1.1.json)
-- [ ] **IMPL-1.1**: Implement to pass tests (🟢 GREEN) [depends: TEST-1.1] → [📋](./.task/IMPL-1.1.json)
-- [ ] **REFACTOR-1.1**: Refactor implementation (🔵 REFACTOR) [depends: IMPL-1.1] → [📋](./.task/REFACTOR-1.1.json)
+## TDD Implementation Tasks
+
+### Feature 1: {Feature Name}
+- [ ] **IMPL-1**: Implement {feature} with TDD → [Task](./.task/IMPL-1.json)
+  - Internal phases: Red → Green → Refactor
+  - Dependencies: None
+
+### Feature 2: {Feature Name}
+- [ ] **IMPL-2**: Implement {feature} with TDD → [Task](./.task/IMPL-2.json)
+  - Internal phases: Red → Green → Refactor
+  - Dependencies: IMPL-1
 ```
 
-### Phase 6: Session State Update
+**For Complex Features (with subtasks)**:
+```markdown
+### Feature 3: {Complex Feature Name}
+▸ **IMPL-3**: Implement {complex feature} with TDD → [Task](./.task/IMPL-3.json)
+  - [ ] **IMPL-3.1**: {Sub-feature A} with TDD → [Task](./.task/IMPL-3.1.json)
+    - Internal phases: Red → Green → Refactor
+  - [ ] **IMPL-3.2**: {Sub-feature B} with TDD → [Task](./.task/IMPL-3.2.json)
+    - Internal phases: Red → Green → Refactor
+    - Dependencies: IMPL-3.1
+```
+
+**Status Legend**:
+```markdown
+## Status Legend
+- ▸ = Container task (has subtasks)
+- [ ] = Pending task
+- [x] = Completed task
+- Red = Write failing tests
+- Green = Implement to pass tests (with test-fix cycle)
+- Refactor = Improve code quality
+```
+
+### Phase 5: Session State Update
 
 Update workflow-session.json with TDD metadata:
 ```json
 {
   "workflow_type": "tdd",
-  "feature_count": 10,
-  "task_count": 30,
-  "tdd_chains": 10
+  "feature_count": 5,
+  "task_count": 5,
+  "task_breakdown": {
+    "simple_features": 4,
+    "complex_features": 1,
+    "total_subtasks": 2
+  },
+  "tdd_workflow": true,
+  "task_limit_compliance": true
 }
 ```
 
+**Task Count Calculation**:
+- **Simple features**: 1 task each (IMPL-N with internal TDD cycle)
+- **Complex features**: 1 container + M subtasks (IMPL-N + IMPL-N.M)
+- **Total**: Simple feature count + Complex feature subtask count
+- **Example**: 4 simple + 1 complex (with 2 subtasks) = 6 total tasks (not 15)
+
 ## Output Files Structure
 ```
 .workflow/{session-id}/
-├── IMPL_PLAN.md                     # Unified plan with TDD Task Chains section
-├── TODO_LIST.md                     # Progress tracking with TDD phases
+├── IMPL_PLAN.md                     # Unified plan with TDD Implementation Tasks section
+├── TODO_LIST.md                     # Progress tracking with internal TDD phase indicators
 ├── .task/
-│   ├── TEST-1.1.json                # Red phase task
-│   ├── IMPL-1.1.json                # Green phase task (with test-fix-cycle)
-│   ├── REFACTOR-1.1.json            # Refactor phase task
+│   ├── IMPL-1.json                  # Complete TDD task (Red-Green-Refactor internally)
+│   ├── IMPL-2.json                  # Complete TDD task
+│   ├── IMPL-3.json                  # Complex feature container (if needed)
+│   ├── IMPL-3.1.json                # Complex feature subtask (if needed)
+│   ├── IMPL-3.2.json                # Complex feature subtask (if needed)
 │   └── ...
 └── .process/
     ├── ANALYSIS_RESULTS.md          # Enhanced with TDD breakdown from concept-enhanced
     ├── test-context-package.json    # Test coverage analysis
     ├── context-package.json         # Input from context-gather
-    └── green-fix-iteration-*.md     # Fix logs from Green phase
+    └── green-fix-iteration-*.md     # Fix logs from Green phase test-fix cycles
 ```
 
+**File Count**:
+- **Old approach**: 5 features = 15 task JSON files (TEST/IMPL/REFACTOR × 5)
+- **New approach**: 5 features = 5 task JSON files (IMPL-N × 5)
+- **Complex feature**: 1 feature = 1 container + M subtasks (IMPL-N + IMPL-N.M)
+
 ## Validation Rules
 
-### Chain Completeness
-- Every TEST-N.M must have corresponding IMPL-N.M and REFACTOR-N.M
+### Task Completeness
+- Every IMPL-N must contain complete TDD workflow in `flow_control.implementation_approach`
+- Each task must have 3 steps with `tdd_phase`: "red", "green", "refactor"
+- Every task must have `meta.tdd_workflow: true`
 
 ### Dependency Enforcement
-- IMPL-N.M must have `depends_on: ["TEST-N.M"]`
-- REFACTOR-N.M must have `depends_on: ["IMPL-N.M"]`
+- Sequential features: IMPL-N depends_on ["IMPL-(N-1)"] if needed
+- Complex feature subtasks: IMPL-N.M depends_on ["IMPL-N.(M-1)"] or parent dependencies
+- No circular dependencies allowed
 
 ### Task Limits
-- Maximum 10 features (30 tasks total)
-- Flat hierarchy only
+- Maximum 10 total tasks (simple + subtasks)
+- Flat hierarchy (≤5 tasks) or two-level (6-10 tasks with containers)
+- Re-scope requirements if >10 tasks needed
+
+### TDD Workflow Validation
+- `meta.tdd_workflow` must be true
+- `flow_control.implementation_approach` must have exactly 3 steps
+- Each step must have `tdd_phase` field ("red", "green", or "refactor")
+- Green phase step must include test-fix cycle logic
+- `meta.max_iterations` must be present (default: 3)
 
 ## Error Handling
 
@@ -640,9 +443,10 @@ Update workflow-session.json with TDD metadata:
 ### TDD Generation Errors
 | Error | Cause | Resolution |
 |-------|-------|------------|
-| Feature count exceeds 10 | Too many features | Re-scope requirements |
+| Task count exceeds 10 | Too many features or subtasks | Re-scope requirements or merge features |
 | Missing test framework | No test config | Configure testing first |
-| Invalid chain structure | Parsing error | Fix TDD breakdown |
+| Invalid TDD workflow | Missing tdd_phase or incomplete flow_control | Fix TDD structure in ANALYSIS_RESULTS.md |
+| Missing tdd_workflow flag | Task doesn't have meta.tdd_workflow: true | Add TDD workflow metadata |
 
 ## Integration & Usage
 
@@ -665,17 +469,32 @@ Update workflow-session.json with TDD metadata:
 TDD task generation complete for session: WFS-auth
 
 Features analyzed: 5
-TDD chains generated: 5
-Total tasks: 15 (5 TEST + 5 IMPL + 5 REFACTOR)
+Total tasks: 5 (1 task per feature with internal TDD cycles)
+
+Task breakdown:
+- Simple features: 4 tasks (IMPL-1 to IMPL-4)
+- Complex features: 1 task with 2 subtasks (IMPL-5, IMPL-5.1, IMPL-5.2)
+- Total task count: 6 (within 10-task limit)
 
 Structure:
-- Feature 1: TEST-1.1 → IMPL-1.1 → REFACTOR-1.1
-- Feature 2: TEST-2.1 → IMPL-2.1 → REFACTOR-2.1
+- IMPL-1: User Authentication (Internal: Red → Green → Refactor)
+- IMPL-2: Password Reset (Internal: Red → Green → Refactor)
+- IMPL-3: Email Verification (Internal: Red → Green → Refactor)
+- IMPL-4: Role Management (Internal: Red → Green → Refactor)
+- IMPL-5: Payment System (Container)
+  - IMPL-5.1: Gateway Integration (Internal: Red → Green → Refactor)
+  - IMPL-5.2: Transaction Management (Internal: Red → Green → Refactor)
 
 Plans generated:
-- Unified Plan: .workflow/WFS-auth/IMPL_PLAN.md (includes TDD Task Chains section)
+- Unified Plan: .workflow/WFS-auth/IMPL_PLAN.md (includes TDD Implementation Tasks section)
+- Task List: .workflow/WFS-auth/TODO_LIST.md (with internal TDD phase indicators)
 
-Next: /workflow:execute or /workflow:tdd-verify
+TDD Configuration:
+- Each task contains complete Red-Green-Refactor cycle
+- Green phase includes test-fix cycle (max 3 iterations)
+- Auto-revert on max iterations reached
+
+Next: /workflow:action-plan-verify --session WFS-auth (recommended) or /workflow:execute --session WFS-auth
 ```
 
 ## Test Coverage Analysis Integration
@@ -704,10 +523,10 @@ IMPL (Green phase) tasks include automatic test-fix cycle:
 5. **Safety Net**: Auto-revert all changes if max iterations reached
 
 **Key Benefits**:
-- ✅ Faster feedback loop within Green phase
-- ✅ Autonomous recovery from initial implementation errors
-- ✅ Systematic debugging with Gemini's bug-fix template
-- ✅ Safe rollback prevents broken TDD state
+- Faster feedback loop within Green phase
+- Autonomous recovery from initial implementation errors
+- Systematic debugging with Gemini's bug-fix template
+- Safe rollback prevents broken TDD state
 
 ## Configuration Options
 - **meta.max_iterations**: Number of fix attempts (default: 3 for TDD, 5 for test-gen)

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

@@ -0,0 +1,677 @@
+---
+name: animation-extract
+description: Extract animation and transition patterns from URLs, CSS, or interactive questioning
+argument-hint: "[--base-path <path>] [--session <id>] [--urls "<list>"] [--mode <auto|interactive>] [--focus "<types>"]"
+allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), Bash(*), Task(ui-design-agent), mcp__chrome-devtools__navigate_page(*), mcp__chrome-devtools__evaluate_script(*)
+---
+
+# Animation Extraction Command
+
+## Overview
+
+Extract animation and transition patterns from web pages using CSS extraction, visual analysis, or interactive questioning. This command generates production-ready animation tokens and guidelines that integrate with design systems.
+
+**Strategy**: Hybrid Extraction with Interactive Fallback
+
+- **Auto Mode (Priority 1)**: Extract from CSS via Chrome DevTools when URLs provided
+- **Visual Mode (Priority 2)**: Analyze screenshots for motion cues (blur, position changes)
+- **Interactive Mode (Priority 3)**: Guided questioning when extraction insufficient
+- **Output**: `animation-tokens.json` + `animation-guide.md`
+
+## Phase 0: Setup & Input Validation
+
+### Step 1: Detect Input Mode & Base Path
+
+```bash
+# Detect input source
+# Priority: --urls → url mode | --mode interactive → question mode
+
+# Parse URLs if provided (format: "target:url,target:url,...")
+IF --urls:
+    url_list = []
+    FOR pair IN split(--urls, ","):
+        IF ":" IN pair:
+            target, url = pair.split(":", 1)
+            url_list.append({target: target.strip(), url: url.strip()})
+        ELSE:
+            url_list.append({target: "page", url: pair.strip()})
+
+    has_urls = true
+    primary_url = url_list[0].url
+ELSE:
+    has_urls = false
+
+# Determine extraction mode
+extraction_mode = --mode OR (has_urls ? "auto" : "interactive")
+
+# Parse animation focus (if provided)
+IF --focus:
+    focus_types = split(--focus, ",")  # e.g., "transitions,hover,scroll"
+ELSE:
+    focus_types = ["all"]  # Extract all animation types
+
+# Determine base path
+bash(find .workflow -type d -name "design-*" | head -1)  # Auto-detect
+# OR use --base-path / --session parameters
+```
+
+### Step 2: Load Design Tokens Context
+
+```bash
+# Load existing design tokens for duration/easing alignment
+IF exists({base_path}/style-extraction/style-1/design-tokens.json):
+    design_tokens = Read({base_path}/style-extraction/style-1/design-tokens.json)
+    has_design_context = true
+ELSE:
+    has_design_context = false
+    WARN: "⚠️ No design tokens found - animation tokens will use standalone values"
+
+# Create output directory
+bash(mkdir -p {base_path}/animation-extraction)
+bash(mkdir -p {base_path}/.intermediates/animation-analysis)
+```
+
+---
+
+**Phase 0 Output**: `extraction_mode`, `base_path`, `has_urls`, `url_list[]`, `focus_types[]`, `has_design_context`
+
+## Phase 1: CSS Animation Extraction (Auto Mode - URL Required)
+
+### Step 1: Check Extraction Mode
+
+```bash
+# extraction_mode == "interactive" → skip to Phase 2
+# extraction_mode == "auto" AND has_urls → execute this phase
+```
+
+**If interactive mode**: Skip to Phase 2
+
+### Step 2: Extract Computed Animations (Auto-Trigger)
+
+```bash
+# AUTO-TRIGGER: If URLs are available, automatically extract CSS animations/transitions
+
+IF has_urls AND mcp_chrome_devtools_available:
+    REPORT: "🔍 Auto-triggering URL mode: Extracting CSS animations and transitions"
+
+    # Read extraction script
+    script_content = Read(~/.claude/scripts/extract-animations.js)
+
+    # For each URL:
+    FOR url_info IN url_list:
+        target = url_info.target
+        url = url_info.url
+
+        REPORT: "   Processing: {target} ({url})"
+
+        # Open page in Chrome DevTools
+        mcp__chrome-devtools__navigate_page(url=url)
+
+        # Wait for page to fully load and animations to initialize
+        bash(sleep 2)
+
+        # Execute extraction script
+        result = mcp__chrome-devtools__evaluate_script(function=script_content)
+
+        # Save raw animation data
+        Write({base_path}/.intermediates/animation-analysis/animations-{target}.json, result)
+
+        REPORT: "   ✅ Extracted: {result.summary.total_animations} animations, {result.summary.total_transitions} transitions"
+
+    animations_extracted = true
+    REPORT: "   ✅ CSS animation extraction complete"
+ELSE IF has_urls AND NOT mcp_chrome_devtools_available:
+    animations_extracted = false
+    REPORT: "⚠️ Chrome DevTools MCP not available"
+    REPORT: "   Falling back to interactive mode for animation guidance"
+ELSE:
+    animations_extracted = false
+```
+
+**Extraction Script Reference**: `~/.claude/scripts/extract-animations.js`
+
+**Usage**: Read the script file and use content directly in `mcp__chrome-devtools__evaluate_script()`
+
+**Script returns**:
+- `metadata`: Extraction timestamp, URL, method
+- `transitions`: Array of transition definitions (property, duration, easing, delay)
+- `animations`: Array of keyframe animations (name, duration, easing, keyframes)
+- `transforms`: Common transform patterns
+- `summary`: Statistics (total_animations, total_transitions, unique_easings)
+
+**Benefits**:
+- ✅ Real animation values from production sites
+- ✅ Captures all CSS transitions and @keyframes rules
+- ✅ Identifies common easing functions and durations
+- ✅ Maps animations to element selectors
+
+---
+
+**Phase 1 Output**: `animations-{target}.json` (intermediate files)
+
+## Phase 2: Interactive Animation Specification (Interactive/Fallback Mode)
+
+### Step 1: Check if Extraction Sufficient
+
+```bash
+# If animations extracted from CSS, check coverage
+IF animations_extracted:
+    total_animations = sum([data.summary.total_animations for data in all_extracted])
+    total_transitions = sum([data.summary.total_transitions for data in all_extracted])
+
+    # If sufficient data found, skip interactive mode
+    IF total_animations >= 3 OR total_transitions >= 5:
+        REPORT: "✅ Sufficient animation data extracted from CSS"
+        SKIP to Phase 3
+    ELSE:
+        REPORT: "⚠️ Limited animation data found - launching interactive mode"
+        extraction_insufficient = true
+ELSE:
+    extraction_insufficient = true
+```
+
+### Step 2: Interactive Question Workflow (Agent)
+
+```bash
+# If extraction failed or insufficient, use interactive questioning
+IF extraction_insufficient OR extraction_mode == "interactive":
+    REPORT: "🤔 Launching interactive animation specification mode"
+
+    # Launch ui-design-agent for interactive questioning
+    Task(ui-design-agent): `
+      [ANIMATION_SPECIFICATION_TASK]
+      Guide user through animation design decisions via structured questions
+
+      SESSION: {session_id} | MODE: interactive | BASE_PATH: {base_path}
+
+      ## Context
+      - Design tokens available: {has_design_context}
+      - Focus areas: {focus_types}
+      - Extracted data: {animations_extracted ? "Partial CSS data available" : "No CSS data"}
+
+      ## Interactive Workflow
+
+      For each animation category, ASK user and WAIT for response:
+
+      ### 1. Transition Duration Scale
+      QUESTION: "What timing scale feels right for your design?"
+      OPTIONS:
+        - "Fast & Snappy" (100-200ms transitions)
+        - "Balanced" (200-400ms transitions)
+        - "Smooth & Deliberate" (400-600ms transitions)
+        - "Custom" (specify values)
+
+      ### 2. Easing Philosophy
+      QUESTION: "What easing style matches your brand?"
+      OPTIONS:
+        - "Linear" (constant speed, technical feel)
+        - "Ease-Out" (fast start, natural feel)
+        - "Ease-In-Out" (balanced, polished feel)
+        - "Spring/Bounce" (playful, modern feel)
+        - "Custom" (specify cubic-bezier)
+
+      ### 3. Common Interactions (Ask for each)
+      FOR interaction IN ["button-hover", "link-hover", "card-hover", "modal-open", "dropdown-toggle"]:
+        QUESTION: "How should {interaction} animate?"
+        OPTIONS:
+          - "Subtle" (color/opacity change only)
+          - "Lift" (scale + shadow increase)
+          - "Slide" (transform translateY)
+          - "Fade" (opacity transition)
+          - "None" (no animation)
+          - "Custom" (describe behavior)
+
+      ### 4. Page Transitions
+      QUESTION: "Should page/route changes have animations?"
+      IF YES:
+        ASK: "What style?"
+        OPTIONS:
+          - "Fade" (crossfade between views)
+          - "Slide" (swipe left/right)
+          - "Zoom" (scale in/out)
+          - "None"
+
+      ### 5. Loading States
+      QUESTION: "What loading animation style?"
+      OPTIONS:
+        - "Spinner" (rotating circle)
+        - "Pulse" (opacity pulse)
+        - "Skeleton" (shimmer effect)
+        - "Progress Bar" (linear fill)
+        - "Custom" (describe)
+
+      ### 6. Micro-interactions
+      QUESTION: "Should form inputs have micro-interactions?"
+      IF YES:
+        ASK: "What interactions?"
+        OPTIONS:
+          - "Focus state animation" (border/shadow transition)
+          - "Error shake" (horizontal shake on error)
+          - "Success check" (checkmark animation)
+          - "All of the above"
+
+      ### 7. Scroll Animations
+      QUESTION: "Should elements animate on scroll?"
+      IF YES:
+        ASK: "What scroll animation style?"
+        OPTIONS:
+          - "Fade In" (opacity 0→1)
+          - "Slide Up" (translateY + fade)
+          - "Scale In" (scale 0.9→1 + fade)
+          - "Stagger" (sequential delays)
+          - "None"
+
+      ## Output Generation
+
+      Based on user responses, generate structured data:
+
+      1. Create animation-specification.json with user choices:
+         - timing_scale (fast/balanced/slow/custom)
+         - easing_philosophy (linear/ease-out/ease-in-out/spring)
+         - interactions: {interaction_name: {type, properties, timing}}
+         - page_transitions: {enabled, style, duration}
+         - loading_animations: {style, duration}
+         - scroll_animations: {enabled, style, stagger_delay}
+
+      2. Write to {base_path}/.intermediates/animation-analysis/animation-specification.json
+
+      ## Critical Requirements
+      - ✅ Use Write() tool immediately for specification file
+      - ✅ Wait for user response after EACH question before proceeding
+      - ✅ Validate responses and ask for clarification if needed
+      - ✅ Provide sensible defaults if user skips questions
+      - ❌ NO external research or MCP calls
+    `
+```
+
+---
+
+**Phase 2 Output**: `animation-specification.json` (user preferences)
+
+## Phase 3: Animation Token Synthesis (Agent)
+
+**Executor**: `Task(ui-design-agent)` for token generation
+
+### Step 1: Load All Input Sources
+
+```bash
+# Gather all available animation data
+extracted_animations = []
+IF animations_extracted:
+    FOR target IN target_list:
+        IF exists({base_path}/.intermediates/animation-analysis/animations-{target}.json):
+            extracted_animations.append(Read(file))
+
+user_specification = null
+IF exists({base_path}/.intermediates/animation-analysis/animation-specification.json):
+    user_specification = Read(file)
+
+design_tokens = null
+IF has_design_context:
+    design_tokens = Read({base_path}/style-extraction/style-1/design-tokens.json)
+```
+
+### Step 2: Launch Token Generation Task
+
+```javascript
+Task(ui-design-agent): `
+  [ANIMATION_TOKEN_GENERATION_TASK]
+  Synthesize all animation data into production-ready animation tokens
+
+  SESSION: {session_id} | BASE_PATH: {base_path}
+
+  ## Input Sources
+  1. Extracted CSS Animations: {JSON.stringify(extracted_animations) OR "None"}
+  2. User Specification: {JSON.stringify(user_specification) OR "None"}
+  3. Design Tokens Context: {JSON.stringify(design_tokens) OR "None"}
+
+  ## Synthesis Rules
+
+  ### Priority System
+  1. User specification (highest priority)
+  2. Extracted CSS values (medium priority)
+  3. Industry best practices (fallback)
+
+  ### Duration Normalization
+  - Analyze all extracted durations
+  - Cluster into 3-5 semantic scales: instant, fast, normal, slow, very-slow
+  - Align with design token spacing scale if available
+
+  ### Easing Standardization
+  - Identify common easing functions from extracted data
+  - Map to semantic names: linear, ease-in, ease-out, ease-in-out, spring
+  - Convert all cubic-bezier values to standard format
+
+  ### Animation Categorization
+  Organize into:
+  - transitions: Property-specific transitions (color, transform, opacity)
+  - keyframe_animations: Named @keyframe animations
+  - interactions: Interaction-specific presets (hover, focus, active)
+  - micro_interactions: Small feedback animations
+  - page_transitions: Route/view change animations
+  - scroll_animations: Scroll-triggered animations
+
+  ## Generate Files
+
+  ### 1. animation-tokens.json
+  Complete animation token structure:
+
+  {
+    "duration": {
+      "instant": "0ms",
+      "fast": "150ms",
+      "normal": "300ms",
+      "slow": "500ms",
+      "very-slow": "800ms"
+    },
+    "easing": {
+      "linear": "linear",
+      "ease-in": "cubic-bezier(0.4, 0, 1, 1)",
+      "ease-out": "cubic-bezier(0, 0, 0.2, 1)",
+      "ease-in-out": "cubic-bezier(0.4, 0, 0.2, 1)",
+      "spring": "cubic-bezier(0.34, 1.56, 0.64, 1)"
+    },
+    "transitions": {
+      "color": {
+        "property": "color, background-color, border-color",
+        "duration": "var(--duration-fast)",
+        "easing": "var(--easing-ease-out)"
+      },
+      "transform": {
+        "property": "transform",
+        "duration": "var(--duration-normal)",
+        "easing": "var(--easing-ease-out)"
+      },
+      "opacity": {
+        "property": "opacity",
+        "duration": "var(--duration-normal)",
+        "easing": "var(--easing-ease-in-out)"
+      }
+    },
+    "keyframes": {
+      "fadeIn": {
+        "0%": {"opacity": "0"},
+        "100%": {"opacity": "1"}
+      },
+      "slideInUp": {
+        "0%": {"transform": "translateY(20px)", "opacity": "0"},
+        "100%": {"transform": "translateY(0)", "opacity": "1"}
+      },
+      "pulse": {
+        "0%, 100%": {"opacity": "1"},
+        "50%": {"opacity": "0.7"}
+      }
+    },
+    "interactions": {
+      "button-hover": {
+        "properties": ["background-color", "transform"],
+        "duration": "var(--duration-fast)",
+        "easing": "var(--easing-ease-out)",
+        "transform": "scale(1.02)"
+      },
+      "card-hover": {
+        "properties": ["box-shadow", "transform"],
+        "duration": "var(--duration-normal)",
+        "easing": "var(--easing-ease-out)",
+        "transform": "translateY(-4px)"
+      }
+    },
+    "page_transitions": {
+      "fade": {
+        "duration": "var(--duration-normal)",
+        "enter": "fadeIn",
+        "exit": "fadeOut"
+      }
+    },
+    "scroll_animations": {
+      "default": {
+        "animation": "fadeInUp",
+        "duration": "var(--duration-slow)",
+        "easing": "var(--easing-ease-out)",
+        "threshold": "0.1",
+        "stagger_delay": "100ms"
+      }
+    }
+  }
+
+  ### 2. animation-guide.md
+  Comprehensive usage guide:
+  - Animation philosophy and rationale
+  - Duration scale explanation
+  - Easing function usage guidelines
+  - Interaction animation patterns
+  - Implementation examples (CSS and JS)
+  - Accessibility considerations (prefers-reduced-motion)
+  - Performance best practices
+
+  ## Critical Requirements
+  - ✅ Use Write() tool immediately for both files
+  - ✅ Ensure all tokens use CSS Custom Property format: var(--duration-fast)
+  - ✅ Include prefers-reduced-motion media query guidance
+  - ✅ Validate all cubic-bezier values are valid
+  - ❌ NO external research or MCP calls
+`
+```
+
+---
+
+**Phase 3 Output**: `animation-tokens.json` + `animation-guide.md`
+
+## Phase 4: Verify Output
+
+### Step 1: Check Files Created
+
+```bash
+# Verify animation tokens created
+bash(test -f {base_path}/animation-extraction/animation-tokens.json && echo "exists")
+bash(test -f {base_path}/animation-extraction/animation-guide.md && echo "exists")
+
+# Validate structure
+bash(cat {base_path}/animation-extraction/animation-tokens.json | grep -q "duration" && echo "valid")
+bash(cat {base_path}/animation-extraction/animation-tokens.json | grep -q "easing" && echo "valid")
+```
+
+### Step 2: Verify File Sizes
+
+```bash
+bash(ls -lh {base_path}/animation-extraction/)
+```
+
+**Output**: 2 files verified (animation-tokens.json, animation-guide.md)
+
+## Completion
+
+### Todo Update
+
+```javascript
+TodoWrite({todos: [
+  {content: "Setup and input validation", status: "completed", activeForm: "Validating inputs"},
+  {content: "CSS animation extraction (auto mode)", status: "completed", activeForm: "Extracting from CSS"},
+  {content: "Interactive specification (fallback)", status: "completed", activeForm: "Collecting user input"},
+  {content: "Animation token synthesis (agent)", status: "completed", activeForm: "Generating tokens"},
+  {content: "Verify output files", status: "completed", activeForm: "Verifying files"}
+]});
+```
+
+### Output Message
+
+```
+✅ Animation extraction complete!
+
+Configuration:
+- Session: {session_id}
+- Extraction Mode: {extraction_mode} (auto/interactive)
+- Input Sources:
+  {IF animations_extracted:
+  - ✅ CSS extracted from {len(url_list)} URL(s)
+  }
+  {IF user_specification:
+  - ✅ User specification via interactive mode
+  }
+  {IF has_design_context:
+  - ✅ Aligned with existing design tokens
+  }
+
+Generated Files:
+{base_path}/animation-extraction/
+├── animation-tokens.json      # Production-ready animation tokens
+└── animation-guide.md          # Usage guidelines and examples
+
+{IF animations_extracted:
+Intermediate Analysis:
+{base_path}/.intermediates/animation-analysis/
+├── animations-*.json           # Extracted CSS data ({len(url_list)} files)
+}
+{IF user_specification:
+└── animation-specification.json # User preferences
+}
+
+Extracted Data Summary:
+- Duration scales: {duration_count} values
+- Easing functions: {easing_count} types
+- Interaction presets: {interaction_count} patterns
+- Keyframe animations: {keyframe_count} animations
+
+Next: Animation tokens ready for integration
+  • style-extract/layout-extract can reference animation tokens
+  • generate command will include animation CSS
+  • Tokens use var() format for easy customization
+```
+
+## Simple Bash Commands
+
+### Path Operations
+
+```bash
+# Find design directory
+bash(find .workflow -type d -name "design-*" | head -1)
+
+# Create output directories
+bash(mkdir -p {base_path}/animation-extraction)
+bash(mkdir -p {base_path}/.intermediates/animation-analysis)
+```
+
+### Validation Commands
+
+```bash
+# Check if already extracted
+bash(test -f {base_path}/animation-extraction/animation-tokens.json && echo "exists")
+
+# Validate JSON structure
+bash(cat {base_path}/animation-extraction/animation-tokens.json | grep -q "duration" && echo "valid")
+
+# Count animation types
+bash(cat animation-tokens.json | grep -c "\"keyframes\":")
+```
+
+### File Operations
+
+```bash
+# Load design tokens context
+bash(test -f {base_path}/style-extraction/style-1/design-tokens.json && cat it)
+
+# Verify output
+bash(ls {base_path}/animation-extraction/)
+```
+
+## Output Structure
+
+```
+{base_path}/
+├── .intermediates/                  # Intermediate analysis files
+│   └── animation-analysis/
+│       ├── animations-{target}.json      # Extracted CSS (auto mode)
+│       └── animation-specification.json  # User input (interactive mode)
+└── animation-extraction/            # Final animation tokens
+    ├── animation-tokens.json        # Production-ready animation tokens
+    └── animation-guide.md            # Usage guide and examples
+```
+
+## animation-tokens.json Format
+
+```json
+{
+  "duration": {
+    "instant": "0ms",
+    "fast": "150ms",
+    "normal": "300ms",
+    "slow": "500ms",
+    "very-slow": "800ms"
+  },
+  "easing": {
+    "linear": "linear",
+    "ease-in": "cubic-bezier(0.4, 0, 1, 1)",
+    "ease-out": "cubic-bezier(0, 0, 0.2, 1)",
+    "ease-in-out": "cubic-bezier(0.4, 0, 0.2, 1)",
+    "spring": "cubic-bezier(0.34, 1.56, 0.64, 1)"
+  },
+  "transitions": {
+    "color": {"property": "...", "duration": "var(--duration-fast)", "easing": "..."},
+    "transform": {"property": "...", "duration": "...", "easing": "..."}
+  },
+  "keyframes": {
+    "fadeIn": {"0%": {...}, "100%": {...}},
+    "slideInUp": {...}
+  },
+  "interactions": {
+    "button-hover": {"properties": [...], "duration": "...", "transform": "..."},
+    "card-hover": {...}
+  },
+  "page_transitions": {...},
+  "scroll_animations": {...}
+}
+```
+
+**Requirements**: CSS var() format, valid cubic-bezier values, prefers-reduced-motion support
+
+## Error Handling
+
+### Common Errors
+
+```
+ERROR: No URL or interactive mode specified
+→ Provide --urls for auto mode or use --mode interactive
+
+ERROR: Chrome DevTools unavailable
+→ Automatically falls back to interactive mode
+
+ERROR: Insufficient animation data extracted
+→ Launches interactive mode for supplemental input
+
+ERROR: Invalid cubic-bezier values
+→ Validates and corrects to nearest standard easing
+```
+
+### Recovery Strategies
+
+- **CSS extraction failure**: Falls back to interactive mode
+- **Partial extraction**: Supplements with interactive questioning
+- **Invalid data**: Validates and uses fallback values
+
+## Key Features
+
+- **Auto-Trigger CSS Extraction** - Automatically extracts animations when --urls provided
+- **Hybrid Strategy** - Combines CSS extraction with interactive specification
+- **Intelligent Fallback** - Gracefully handles extraction failures
+- **Context-Aware** - Aligns with existing design tokens
+- **Production-Ready** - CSS var() format, accessibility support
+- **Comprehensive Coverage** - Transitions, keyframes, interactions, scroll animations
+- **Agent-Driven** - Autonomous token generation with ui-design-agent
+
+## Integration
+
+**Workflow Position**: Between style extraction and layout extraction (or parallel)
+
+**New Workflow**:
+1. `/workflow:ui-design:style-extract` → `design-tokens.json` + `style-guide.md`
+2. **`/workflow:ui-design:animation-extract`** → `animation-tokens.json` + `animation-guide.md` (NEW)
+3. `/workflow:ui-design:layout-extract` → `layout-templates.json`
+4. `/workflow:ui-design:generate`:
+   - Reads: design-tokens.json + animation-tokens.json + layout-templates.json
+   - Generates: Prototypes with animation CSS included
+
+**Input**: URLs (auto mode) or interactive questioning
+**Output**: `animation-tokens.json` + `animation-guide.md`
+**Next**: `/workflow:ui-design:layout-extract` OR `/workflow:ui-design:generate`
+
+**Note**: This command extracts motion design patterns (animations, transitions) to complement visual style tokens. Can run in parallel with layout-extract.

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

@@ -20,10 +20,11 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
 1. User triggers: `/workflow:ui-design:explore-auto [params]`
 2. Phase 0c: Target confirmation → User confirms → **IMMEDIATELY triggers Phase 1**
 3. Phase 1 (style-extract) → **WAIT for completion** → Auto-continues
-4. Phase 2 (layout-extract) → **WAIT for completion** → Auto-continues
-5. **Phase 3 (ui-assembly)** → **WAIT for completion** → Auto-continues
-6. Phase 4 (design-update) → **WAIT for completion** → Auto-continues
-7. Phase 5 (batch-plan, optional) → Reports completion
+4. Phase 2.3 (animation-extract, optional) → **WAIT for completion** → Auto-continues
+5. Phase 2.5 (layout-extract) → **WAIT for completion** → Auto-continues
+6. **Phase 3 (ui-assembly)** → **WAIT for completion** → Auto-continues
+7. Phase 4 (design-update) → **WAIT for completion** → Auto-continues
+8. Phase 5 (batch-plan, optional) → Reports completion
 
 **Phase Transition Mechanism**:
 - **Phase 0c (User Interaction)**: User confirms targets → IMMEDIATELY triggers Phase 1
@@ -276,10 +277,26 @@ SlashCommand(command)
 
 # Output: {style_variants} style cards with design_attributes
 # SlashCommand blocks until phase complete
-# Upon completion, IMMEDIATELY execute Phase 2 (auto-continue)
+# Upon completion, IMMEDIATELY execute Phase 2.3 (auto-continue)
 ```
 
-### Phase 2: Layout Extraction
+### Phase 2.3: Animation Extraction (Optional - Interactive Mode)
+```bash
+# Animation extraction for motion design patterns
+REPORT: "🚀 Phase 2.3: Animation Extraction (interactive mode)"
+REPORT: "   → Mode: Interactive specification"
+REPORT: "   → Purpose: Define motion design patterns"
+
+command = "/workflow:ui-design:animation-extract --base-path \"{base_path}\" --mode interactive"
+
+SlashCommand(command)
+
+# Output: animation-tokens.json + animation-guide.md
+# SlashCommand blocks until phase complete
+# Upon completion, IMMEDIATELY execute Phase 2.5 (auto-continue)
+```
+
+### Phase 2.5: Layout Extraction
 ```bash
 targets_string = ",".join(inferred_target_list)
 command = "/workflow:ui-design:layout-extract --base-path \"{base_path}\" " +

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

@@ -57,6 +57,21 @@ Read({base_path}/style-extraction/style-{id}/design-tokens.json)
 
 **Output**: `design_tokens[]` for all style variants
 
+### Step 4: Load Animation Tokens (Optional)
+```bash
+# Check if animation tokens exist
+bash(test -f {base_path}/animation-extraction/animation-tokens.json && echo "exists")
+
+# Load animation tokens if available
+IF exists({base_path}/animation-extraction/animation-tokens.json):
+    animation_tokens = Read({base_path}/animation-extraction/animation-tokens.json)
+    has_animations = true
+ELSE:
+    has_animations = false
+```
+
+**Output**: `animation_tokens` (optional), `has_animations` flag
+
 ## Phase 2: Assembly (Agent)
 
 **Executor**: `Task(ui-design-agent)` × `T × S × L` tasks (can be batched)
@@ -86,7 +101,15 @@ Task(ui-design-agent): `
      Read("{base_path}/style-extraction/style-{style_id}/design-tokens.json")
      Extract: ALL token values (colors, typography, spacing, borders, shadows, breakpoints)
 
-  3. Reference Image (AUTO-DETECTED):
+  3. Animation Tokens (OPTIONAL):
+     IF exists("{base_path}/animation-extraction/animation-tokens.json"):
+       Read("{base_path}/animation-extraction/animation-tokens.json")
+       Extract: duration, easing, transitions, keyframes, interactions
+       has_animations = true
+     ELSE:
+       has_animations = false
+
+  4. Reference Image (AUTO-DETECTED):
      IF template.source_image_path exists:
        Read(template.source_image_path)
        Purpose: Additional visual context for better placeholder content generation
@@ -115,6 +138,14 @@ Task(ui-design-agent): `
        * Typography: tokens.typography.*
        * Shadows: tokens.shadows.*
        * Border radius: tokens.border_radius.*
+     - IF has_animations == true: Inject animation tokens
+       * Add CSS Custom Properties for animations at :root level:
+         --duration-instant, --duration-fast, --duration-normal, etc.
+         --easing-linear, --easing-ease-out, etc.
+       * Add @keyframes rules from animation_tokens.keyframes
+       * Add interaction classes (.button-hover, .card-hover) from animation_tokens.interactions
+       * Add utility classes (.transition-color, .transition-transform) from animation_tokens.transitions
+       * Include prefers-reduced-motion media query for accessibility
      - Device-optimized for template.device_type
 
   ## Assembly Rules

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

@@ -20,9 +20,10 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Write(*), Bash(*)
 2. Phase 0: Initialize and parse parameters
 3. Phase 1: Screenshot capture (batch or deep mode) → **WAIT for completion** → Auto-continues
 4. Phase 2: Style extraction (complete design systems) → **WAIT for completion** → Auto-continues
-5. Phase 2.5: Layout extraction (structure templates) → **WAIT for completion** → Auto-continues
-6. Phase 3: Batch UI assembly → **WAIT for completion** → Auto-continues
-7. Phase 4: Design system integration → Reports completion
+5. Phase 2.3: Animation extraction (CSS auto mode) → **WAIT for completion** → Auto-continues
+6. Phase 2.5: Layout extraction (structure templates) → **WAIT for completion** → Auto-continues
+7. Phase 3: Batch UI assembly → **WAIT for completion** → Auto-continues
+8. Phase 4: Design system integration → Reports completion
 
 **Phase Transition Mechanism**:
 - `SlashCommand` is BLOCKING - execution pauses until completion
@@ -98,19 +99,6 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Write(*), Bash(*)
 ### Phase 0: Initialization and Target Parsing
 
 ```bash
-REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-REPORT: "🚀 UI Design Imitate-Auto"
-REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-
-# Constants
-DEPTH_NAMES = {
-    1: "Page level",
-    2: "Element level",
-    3: "Interaction level",
-    4: "Embedded level",
-    5: "Shadow DOM"
-}
-
 # Generate run ID
 run_id = "run-$(date +%Y%m%d-%H%M%S)"
 
@@ -119,12 +107,10 @@ IF --session:
     session_id = {provided_session}
     base_path = ".workflow/WFS-{session_id}/design-{run_id}"
     session_mode = "integrated"
-    REPORT: "Mode: Integrated (Session: {session_id})"
 ELSE:
     session_id = null
     base_path = ".workflow/.design/{run_id}"
     session_mode = "standalone"
-    REPORT: "Mode: Standalone"
 
 # Create base directory
 Bash(mkdir -p "{base_path}")
@@ -198,25 +184,12 @@ metadata = {
 
 Write("{base_path}/.run-metadata.json", JSON.stringify(metadata, null, 2))
 
-REPORT: ""
-REPORT: "Configuration:"
-REPORT: "  Capture mode: {capture_mode}"
-IF capture_mode == "deep":
-    REPORT: "    Depth level: {depth} ({DEPTH_NAMES[depth]})"
-    REPORT: "    Target: '{primary_target}' ({url_map[primary_target]})"
-ELSE:
-    REPORT: "    Targets: {len(target_names)} pages"
-    REPORT: "    Primary source: '{primary_target}' ({url_map[primary_target]})"
-    REPORT: "    All targets: {', '.join(target_names)}"
-IF --prompt:
-    REPORT: "  Prompt guidance: \"{--prompt}\""
-REPORT: ""
-
 # Initialize TodoWrite
 TodoWrite({todos: [
   {content: "Initialize and parse url-map", status: "completed", activeForm: "Initializing"},
   {content: capture_mode == "batch" ? f"Batch screenshot capture ({len(target_names)} targets)" : f"Deep exploration (depth {depth})", status: "pending", activeForm: "Capturing screenshots"},
   {content: "Extract style (complete design systems)", status: "pending", activeForm: "Extracting style"},
+  {content: "Extract animation (CSS auto mode)", status: "pending", activeForm: "Extracting animation"},
   {content: "Extract layout (structure templates)", status: "pending", activeForm: "Extracting layout"},
   {content: f"Assemble UI for {len(target_names)} targets", status: "pending", activeForm: "Assembling UI"},
   {content: session_id ? "Integrate design system" : "Standalone completion", status: "pending", activeForm: "Completing"}
@@ -227,22 +200,14 @@ TodoWrite({todos: [
 
 ```bash
 REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-REPORT: f"🚀 Phase 1: Screenshot Capture ({capture_mode} mode)"
+REPORT: "🚀 Phase 1: Screenshot Capture"
 REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 
 IF capture_mode == "batch":
     # Mode A: Batch Multi-URL Capture
-    REPORT: "Using batch capture for multiple URLs..."
-
-    # Build url-map string for capture command
     url_map_command_string = ",".join([f"{name}:{url}" for name, url in url_map.items()])
-
-    # Call capture command
     capture_command = f"/workflow:ui-design:capture --base-path \"{base_path}\" --url-map \"{url_map_command_string}\""
 
-    REPORT: f"  Command: {capture_command}"
-    REPORT: f"  Targets: {len(target_names)}"
-
     TRY:
         SlashCommand(capture_command)
     CATCH error:
@@ -263,34 +228,19 @@ IF capture_mode == "batch":
     total_requested = screenshot_metadata.total_requested
     missing_count = total_requested - captured_count
 
-    REPORT: ""
-    REPORT: "✅ Batch capture complete:"
-    REPORT: "   Captured: {captured_count}/{total_requested} screenshots ({(captured_count/total_requested*100):.1f}%)"
-
     IF missing_count > 0:
         missing_targets = [s.target for s in screenshot_metadata.screenshots if not s.captured]
-        WARN: "   ⚠️ Missing {missing_count} screenshots: {', '.join(missing_targets)}"
-        WARN: "   Proceeding with available screenshots for extract phase"
+        WARN: "⚠️ Missing {missing_count} screenshots: {', '.join(missing_targets)}"
 
-    # If all screenshots failed, terminate
     IF captured_count == 0:
         ERROR: "No screenshots captured - cannot proceed"
-        ERROR: "Please check URLs and tool availability"
         EXIT 1
 
 ELSE:  # capture_mode == "deep"
     # Mode B: Deep Interactive Layer Exploration
-    REPORT: "Using deep exploration for single URL..."
-
     primary_url = url_map[primary_target]
-
-    # Call explore-layers command
     explore_command = f"/workflow:ui-design:explore-layers --url \"{primary_url}\" --depth {depth} --base-path \"{base_path}\""
 
-    REPORT: f"  Command: {explore_command}"
-    REPORT: f"  URL: {primary_url}"
-    REPORT: f"  Depth: {depth} ({DEPTH_NAMES[depth]})"
-
     TRY:
         SlashCommand(explore_command)
     CATCH error:
@@ -307,16 +257,7 @@ ELSE:  # capture_mode == "deep"
         EXIT 1
 
     layer_map = Read(layer_map_path)
-    total_layers = len(layer_map.layers)
     captured_count = layer_map.summary.total_captures
-
-    REPORT: ""
-    REPORT: "✅ Deep exploration complete:"
-    REPORT: "   Layers: {total_layers} (depth 1-{depth})"
-    REPORT: "   Captures: {captured_count} screenshots"
-    REPORT: "   Total size: {layer_map.summary.total_size_kb:.1f} KB"
-
-    # Count actual images for extract phase
     total_requested = captured_count  # For consistency with batch mode
 
 TodoWrite(mark_completed: f"Batch screenshot capture ({len(target_names)} targets)" IF capture_mode == "batch" ELSE f"Deep exploration (depth {depth})",
@@ -326,31 +267,29 @@ TodoWrite(mark_completed: f"Batch screenshot capture ({len(target_names)} target
 ### Phase 2: Style Extraction (Visual Tokens)
 
 ```bash
-REPORT: ""
 REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-REPORT: "🚀 Phase 2: Extract Style (Visual Tokens)"
+REPORT: "🚀 Phase 2: Style Extraction"
 REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 
 # Use all screenshots as input to extract single design system
 IF capture_mode == "batch":
     images_glob = f"{base_path}/screenshots/*.{{png,jpg,jpeg,webp}}"
 ELSE:  # deep mode
-    images_glob = f"{base_path}/screenshots/**/*.{{png,jpg,jpeg,webp}}"  # Include all depth directories
+    images_glob = f"{base_path}/screenshots/**/*.{{png,jpg,jpeg,webp}}"
 
 # Build extraction prompt
 IF --prompt:
     user_guidance = {--prompt}
-    extraction_prompt = f"Extract visual style tokens (colors, typography, spacing) from the '{primary_target}' page. Use other screenshots for consistency. User guidance: {user_guidance}"
+    extraction_prompt = f"Extract visual style tokens from '{primary_target}'. User guidance: {user_guidance}"
 ELSE:
-    extraction_prompt = f"Extract visual style tokens (colors, typography, spacing) from the '{primary_target}' page. Use other screenshots for consistency across all pages."
+    extraction_prompt = f"Extract visual style tokens from '{primary_target}' with consistency across all pages."
+
+# Build url-map string for style-extract (enables computed styles extraction)
+url_map_for_extract = ",".join([f"{name}:{url}" for name, url in url_map.items()])
 
 # Call style-extract command (imitate mode, automatically uses single variant)
-extract_command = f"/workflow:ui-design:style-extract --base-path \"{base_path}\" --images \"{images_glob}\" --prompt \"{extraction_prompt}\" --mode imitate"
-
-REPORT: "Calling style-extract command..."
-REPORT: f"  Mode: imitate (high-fidelity single style, auto variants=1)"
-REPORT: f"  Primary source: '{primary_target}'"
-REPORT: f"  Images: {images_glob}"
+# Pass --urls to enable auto-trigger of computed styles extraction
+extract_command = f"/workflow:ui-design:style-extract --base-path \"{base_path}\" --images \"{images_glob}\" --urls \"{url_map_for_extract}\" --prompt \"{extraction_prompt}\" --mode imitate"
 
 TRY:
     SlashCommand(extract_command)
@@ -359,53 +298,64 @@ CATCH error:
     ERROR: "Cannot proceed without visual tokens"
     EXIT 1
 
-# style-extract outputs to: {base_path}/style-extraction/style-1/design-tokens.json
-
 # Verify extraction results
 design_tokens_path = "{base_path}/style-extraction/style-1/design-tokens.json"
 style_guide_path = "{base_path}/style-extraction/style-1/style-guide.md"
 
-IF NOT exists(design_tokens_path):
-    ERROR: "style-extract command did not generate design-tokens.json"
-    ERROR: "Expected: {design_tokens_path}"
+IF NOT exists(design_tokens_path) OR NOT exists(style_guide_path):
+    ERROR: "style-extract did not generate required files"
     EXIT 1
 
-IF NOT exists(style_guide_path):
-    ERROR: "style-extract command did not generate style-guide.md"
-    ERROR: "Expected: {style_guide_path}"
-    EXIT 1
-
-design_tokens = Read(design_tokens_path)
-
-REPORT: ""
-REPORT: "✅ Phase 2 complete:"
-REPORT: "   Output: style-extraction/style-1/"
-REPORT: "   Files: design-tokens.json, style-guide.md"
-REPORT: "   Quality: Production-ready (WCAG AA)"
-
 TodoWrite(mark_completed: "Extract style (complete design systems)",
+          mark_in_progress: "Extract animation (CSS auto mode)")
+```
+
+### Phase 2.3: Animation Extraction (CSS Auto Mode)
+
+```bash
+REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+REPORT: "🚀 Phase 2.3: Animation Extraction"
+REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+# Build URL list for animation-extract (auto mode for CSS extraction)
+url_map_for_animation = ",".join([f"{target}:{url}" for target, url in url_map.items()])
+
+# Call animation-extract command (auto mode for CSS animation extraction)
+# Pass --urls to auto-trigger CSS animation/transition extraction via Chrome DevTools
+animation_extract_command = f"/workflow:ui-design:animation-extract --base-path \"{base_path}\" --urls \"{url_map_for_animation}\" --mode auto"
+
+TRY:
+    SlashCommand(animation_extract_command)
+CATCH error:
+    ERROR: "Animation extraction failed: {error}"
+    ERROR: "Cannot proceed without animation tokens"
+    EXIT 1
+
+# Verify animation extraction results
+animation_tokens_path = "{base_path}/animation-extraction/animation-tokens.json"
+animation_guide_path = "{base_path}/animation-extraction/animation-guide.md"
+
+IF NOT exists(animation_tokens_path) OR NOT exists(animation_guide_path):
+    ERROR: "animation-extract did not generate required files"
+    EXIT 1
+
+TodoWrite(mark_completed: "Extract animation (CSS auto mode)",
           mark_in_progress: "Extract layout (structure templates)")
 ```
 
 ### Phase 2.5: Layout Extraction (Structure Templates)
 
 ```bash
-REPORT: ""
 REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-REPORT: "🚀 Phase 2.5: Extract Layout (Structure Templates)"
+REPORT: "🚀 Phase 2.5: Layout Extraction"
 REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 
-# Reuse same screenshots for layout extraction
-# Build URL map for layout-extract (uses first URL from each target)
+# Build URL map for layout-extract
 url_map_for_layout = ",".join([f"{target}:{url}" for target, url in url_map.items()])
 
 # Call layout-extract command (imitate mode for structure replication)
-layout_extract_command = f"/workflow:ui-design:layout-extract --base-path \"{base_path}\" --images \"{images_glob}\" --targets \"{','.join(target_names)}\" --mode imitate"
-
-REPORT: "Calling layout-extract command..."
-REPORT: f"  Mode: imitate (high-fidelity structure replication)"
-REPORT: f"  Targets: {', '.join(target_names)}"
-REPORT: f"  Images: {images_glob}"
+# Pass --urls to enable auto-trigger of DOM structure extraction
+layout_extract_command = f"/workflow:ui-design:layout-extract --base-path \"{base_path}\" --images \"{images_glob}\" --urls \"{url_map_for_layout}\" --targets \"{','.join(target_names)}\" --mode imitate"
 
 TRY:
     SlashCommand(layout_extract_command)
@@ -414,24 +364,13 @@ CATCH error:
     ERROR: "Cannot proceed without layout templates"
     EXIT 1
 
-# layout-extract outputs to: {base_path}/layout-extraction/layout-templates.json
-
 # Verify layout extraction results
 layout_templates_path = "{base_path}/layout-extraction/layout-templates.json"
 
 IF NOT exists(layout_templates_path):
-    ERROR: "layout-extract command did not generate layout-templates.json"
-    ERROR: "Expected: {layout_templates_path}"
+    ERROR: "layout-extract did not generate layout-templates.json"
     EXIT 1
 
-layout_templates = Read(layout_templates_path)
-template_count = len(layout_templates.layout_templates)
-
-REPORT: ""
-REPORT: "✅ Phase 2.5 complete:"
-REPORT: "   Templates: {template_count} layout structures"
-REPORT: "   Targets: {', '.join(target_names)}"
-
 TodoWrite(mark_completed: "Extract layout (structure templates)",
           mark_in_progress: f"Assemble UI for {len(target_names)} targets")
 ```
@@ -439,25 +378,13 @@ TodoWrite(mark_completed: "Extract layout (structure templates)",
 ### Phase 3: Batch UI Assembly
 
 ```bash
-REPORT: ""
 REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-REPORT: "🚀 Phase 3: Batch UI Assembly"
+REPORT: "🚀 Phase 3: UI Assembly"
 REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 
-# Note: design-tokens.json already generated in Phase 2 (style-extract)
-# Located at: {base_path}/style-extraction/style-1/design-tokens.json
-
-# Build targets string
-targets_string = ",".join(target_names)
-
-# Call generate command (now pure assembler - combines layout templates + design tokens)
+# Call generate command (pure assembler - combines layout templates + design tokens)
 generate_command = f"/workflow:ui-design:generate --base-path \"{base_path}\" --style-variants 1 --layout-variants 1"
 
-REPORT: "Calling generate command (pure assembler)..."
-REPORT: f"  Targets: {targets_string} (from layout templates)"
-REPORT: f"  Configuration: 1 style × 1 layout × {len(target_names)} pages"
-REPORT: f"  Inputs: layout-templates.json + design-tokens.json"
-
 TRY:
     SlashCommand(generate_command)
 CATCH error:
@@ -465,22 +392,13 @@ CATCH error:
     ERROR: "Layout templates or design tokens may be invalid"
     EXIT 1
 
-# generate outputs to: {base_path}/prototypes/{target}-style-1-layout-1.html
-
 # Verify assembly results
 prototypes_dir = "{base_path}/prototypes"
 generated_html_files = Glob(f"{prototypes_dir}/*-style-1-layout-1.html")
 generated_count = len(generated_html_files)
 
-REPORT: ""
-REPORT: "✅ Phase 4 complete:"
-REPORT: "   Assembled: {generated_count} HTML prototypes"
-REPORT: "   Targets: {', '.join(target_names)}"
-REPORT: "   Output: {prototypes_dir}/"
-
 IF generated_count < len(target_names):
-    WARN: "   ⚠️ Expected {len(target_names)} prototypes, assembled {generated_count}"
-    WARN: "   Some targets may have failed - check generate output"
+    WARN: "⚠️ Expected {len(target_names)} prototypes, assembled {generated_count}"
 
 TodoWrite(mark_completed: f"Assemble UI for {len(target_names)} targets",
           mark_in_progress: session_id ? "Integrate design system" : "Standalone completion")
@@ -489,30 +407,18 @@ TodoWrite(mark_completed: f"Assemble UI for {len(target_names)} targets",
 ### Phase 4: Design System Integration
 
 ```bash
-REPORT: ""
 REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 REPORT: "🚀 Phase 4: Design System Integration"
 REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 
 IF session_id:
-    REPORT: "Integrating design system into session {session_id}..."
-
     update_command = f"/workflow:ui-design:update --session {session_id}"
 
     TRY:
         SlashCommand(update_command)
     CATCH error:
-        WARN: "Design system integration failed: {error}"
-        WARN: "Prototypes are still available at {base_path}/prototypes/"
-        # Don't terminate, prototypes already generated
-
-    REPORT: "✅ Design system integrated into session {session_id}"
-ELSE:
-    REPORT: "ℹ️ Standalone mode: Skipping integration"
-    REPORT: "   Prototypes available at: {base_path}/prototypes/"
-    REPORT: "   To integrate later:"
-    REPORT: "   1. Create a workflow session"
-    REPORT: "   2. Copy design-tokens.json to session artifacts"
+        WARN: "⚠️ Design system integration failed: {error}"
+        WARN: "Prototypes available at {base_path}/prototypes/"
 
 # Update metadata
 metadata = Read("{base_path}/.run-metadata.json")
@@ -534,6 +440,7 @@ TodoWrite({todos: [
   {content: "Initialize and parse url-map", status: "completed", activeForm: "Initializing"},
   {content: capture_mode == "batch" ? f"Batch screenshot capture ({len(target_names)} targets)" : f"Deep exploration (depth {depth})", status: "completed", activeForm: "Capturing"},
   {content: "Extract style (complete design systems)", status: "completed", activeForm: "Extracting"},
+  {content: "Extract animation (CSS auto mode)", status: "completed", activeForm: "Extracting animation"},
   {content: "Extract layout (structure templates)", status: "completed", activeForm: "Extracting layout"},
   {content: f"Assemble UI for {len(target_names)} targets", status: "completed", activeForm: "Assembling"},
   {content: session_id ? "Integrate design system" : "Standalone completion", status: "completed", activeForm: "Completing"}
@@ -561,6 +468,10 @@ Phase 2 - Style Extraction: ✅ Production-ready design systems
   Output: style-extraction/style-1/ (design-tokens.json + style-guide.md)
   Quality: WCAG AA compliant, OKLCH colors
 
+Phase 2.3 - Animation Extraction: ✅ CSS animations and transitions
+  Output: animation-extraction/ (animation-tokens.json + animation-guide.md)
+  Method: Auto-extracted from live URLs via Chrome DevTools
+
 Phase 2.5 - Layout Extraction: ✅ Structure templates
   Templates: {template_count} layout structures
 
@@ -591,6 +502,9 @@ ELSE:
 │   └── style-1/
 │       ├── design-tokens.json
 │       └── style-guide.md
+├── animation-extraction/           # CSS animations and transitions
+│   ├── animation-tokens.json
+│   └── animation-guide.md
 ├── layout-extraction/              # Structure templates
 │   └── layout-templates.json
 └── prototypes/                     # {generated_count} HTML/CSS files
@@ -729,9 +643,10 @@ TodoWrite({todos: [
      - `--capture-mode batch`: `/workflow:ui-design:capture` (multi-URL batch)
      - `--capture-mode deep`: `/workflow:ui-design:explore-layers` (single-URL depth exploration)
   2. `/workflow:ui-design:style-extract` (Phase 2 - complete design systems)
-  3. `/workflow:ui-design:layout-extract` (Phase 2.5 - structure templates)
-  4. `/workflow:ui-design:generate` (Phase 3 - pure assembly)
-  5. `/workflow:ui-design:update` (Phase 4, if --session)
+  3. `/workflow:ui-design:animation-extract` (Phase 2.3 - CSS animations and transitions)
+  4. `/workflow:ui-design:layout-extract` (Phase 2.5 - structure templates)
+  5. `/workflow:ui-design:generate` (Phase 3 - pure assembly)
+  6. `/workflow:ui-design:update` (Phase 4, if --session)
 
 ## Completion Output
 

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

@@ -29,6 +29,22 @@ Extract structural layout information from reference images, URLs, or text promp
 # Detect input source
 # Priority: --urls + --images → hybrid | --urls → url | --images → image | --prompt → text
 
+# Parse URLs if provided (format: "target:url,target:url,...")
+IF --urls:
+    url_list = []
+    FOR pair IN split(--urls, ","):
+        IF ":" IN pair:
+            target, url = pair.split(":", 1)
+            url_list.append({target: target.strip(), url: url.strip()})
+        ELSE:
+            # Single URL without target
+            url_list.append({target: "page", url: pair.strip()})
+
+    has_urls = true
+ELSE:
+    has_urls = false
+    url_list = []
+
 # Determine extraction mode
 extraction_mode = --mode OR "imitate"  # "imitate" or "explore"
 
@@ -40,8 +56,15 @@ ELSE IF extraction_mode == "explore":
     VALIDATE: 1 <= variants_count <= 5
 
 # Resolve targets
-# Priority: --targets → prompt analysis → default ["page"]
-targets = --targets OR extract_from_prompt(--prompt) OR ["page"]
+# Priority: --targets → url_list targets → prompt analysis → default ["page"]
+IF --targets:
+    targets = split(--targets, ",")
+ELSE IF has_urls:
+    targets = [url_info.target for url_info in url_list]
+ELSE IF --prompt:
+    targets = extract_from_prompt(--prompt)
+ELSE:
+    targets = ["page"]
 
 # Resolve device type
 device_type = --device-type OR "responsive"  # desktop|mobile|tablet|responsive
@@ -68,27 +91,43 @@ Read({image_path})  # Load each image
 bash(mkdir -p {base_path}/layout-extraction)
 ```
 
-### Step 2.5: Extract DOM Structure (URL Mode - Enhancement)
+### Step 2.5: Extract DOM Structure (URL Mode - Auto-Trigger)
 ```bash
-# If URLs are available, extract real DOM structure
+# AUTO-TRIGGER: If URLs are available (from --urls parameter), automatically extract real DOM structure
 # This provides accurate layout data to supplement visual analysis
 
-# For each URL in url_list:
-IF url_available AND mcp_chrome_devtools_available:
-    # Read extraction script
-    Read(~/.claude/scripts/extract-layout-structure.js)
+# Check if URLs provided via --urls parameter
+IF --urls AND url_list:
+    REPORT: "🔍 Auto-triggering URL mode: Extracting DOM structure"
 
-    # Open page in Chrome DevTools
-    mcp__chrome-devtools__navigate_page(url="{target_url}")
-
-    # Execute layout extraction script
-    result = mcp__chrome-devtools__evaluate_script(function="[SCRIPT_CONTENT]")
-
-    # Save DOM structure for this target (intermediate file)
     bash(mkdir -p {base_path}/.intermediates/layout-analysis)
-    Write({base_path}/.intermediates/layout-analysis/dom-structure-{target}.json, result)
 
-    dom_structure_available = true
+    # For each URL in url_list:
+    FOR url_info IN url_list:
+        target = url_info.target
+        url = url_info.url
+
+        IF mcp_chrome_devtools_available:
+            REPORT: "   Processing: {target} ({url})"
+
+            # Read extraction script
+            script_content = Read(~/.claude/scripts/extract-layout-structure.js)
+
+            # Open page in Chrome DevTools
+            mcp__chrome-devtools__navigate_page(url=url)
+
+            # Execute layout extraction script
+            result = mcp__chrome-devtools__evaluate_script(function=script_content)
+
+            # Save DOM structure for this target (intermediate file)
+            Write({base_path}/.intermediates/layout-analysis/dom-structure-{target}.json, result)
+
+            REPORT: "   ✅ DOM structure extracted for '{target}'"
+        ELSE:
+            REPORT: "   ⚠️ Chrome DevTools MCP not available, falling back to visual analysis"
+            BREAK
+
+    dom_structure_available = mcp_chrome_devtools_available
 ELSE:
     dom_structure_available = false
 ```
@@ -98,15 +137,50 @@ ELSE:
 **Usage**: Read the script file and use content directly in `mcp__chrome-devtools__evaluate_script()`
 
 **Script returns**:
-- `metadata`: Extraction timestamp, URL, method
+- `metadata`: Extraction timestamp, URL, method, version
 - `patterns`: Layout pattern statistics (flexColumn, flexRow, grid counts)
 - `structure`: Hierarchical DOM tree with layout properties
+- `exploration`: (Optional) Progressive exploration results when standard selectors fail
 
 **Benefits**:
 - ✅ Real flex/grid configuration (justifyContent, alignItems, gap, etc.)
 - ✅ Accurate element bounds (x, y, width, height)
 - ✅ Structural hierarchy with depth control
 - ✅ Layout pattern identification (flex-row, flex-column, grid-NCol)
+- ✅ Progressive exploration: Auto-discovers missing selectors
+
+**Progressive Exploration Strategy** (v2.2.0+):
+
+When script finds <3 main containers, it automatically:
+1. **Scans** all large visible containers (≥500×300px)
+2. **Extracts** class patterns matching: `main|content|wrapper|container|page|layout|app`
+3. **Suggests** new selectors to add to script
+4. **Returns** exploration data in `result.exploration`:
+   ```json
+   {
+     "triggered": true,
+     "discoveredCandidates": [{classes, bounds, display}],
+     "suggestedSelectors": [".wrapper", ".page-index"],
+     "recommendation": ".wrapper, .page-index, .app-container"
+   }
+   ```
+
+**Using Exploration Results**:
+```javascript
+// After extraction, check for suggestions
+IF result.exploration?.triggered:
+    REPORT: result.exploration.warning
+    REPORT: "Suggested selectors: " + result.exploration.recommendation
+
+    // Update script by adding to commonClassSelectors array
+    // Then re-run extraction for better coverage
+```
+
+**Selector Update Workflow**:
+1. Run extraction on unfamiliar site
+2. Check `result.exploration.suggestedSelectors`
+3. Add relevant selectors to script's `commonClassSelectors`
+4. Re-run extraction → improved container detection
 
 ### Step 3: Memory Check
 ```bash
@@ -122,7 +196,7 @@ IF exists: SKIP to completion
 
 **Phase 0 Output**: `input_mode`, `base_path`, `extraction_mode`, `variants_count`, `targets[]`, `device_type`, loaded inputs
 
-## Phase 1: Layout Research (Explore Mode Only)
+## Phase 1: Layout Concept Generation (Explore Mode Only)
 
 ### Step 1: Check Extraction Mode
 ```bash
@@ -143,93 +217,311 @@ bash(mkdir -p {base_path}/.intermediates/layout-analysis/inspirations)
 Write({base_path}/.intermediates/layout-analysis/inspirations/{target}-layout-ideas.txt, inspiration_content)
 ```
 
-**Output**: Inspiration text files for each target (explore mode only)
-
-## Phase 2: Layout Analysis & Synthesis (Agent)
-
+### Step 3: Generate Layout Concept Options (Agent Task 1)
 **Executor**: `Task(ui-design-agent)`
 
-### Step 1: Launch Agent Task
+Launch agent to generate `variants_count` layout concept options for each target:
+
 ```javascript
 Task(ui-design-agent): `
-  [LAYOUT_EXTRACTION_TASK]
-  Analyze references and extract structural layout templates.
+  [LAYOUT_CONCEPT_GENERATION_TASK]
+  Generate {variants_count} structurally distinct layout concepts for each target
+
+  SESSION: {session_id} | MODE: explore | BASE_PATH: {base_path}
+  TARGETS: {targets} | DEVICE_TYPE: {device_type}
+
+  ## Input Analysis
+  - Targets: {targets.join(", ")}
+  - Device type: {device_type}
+  - Layout inspiration: Read inspirations from {base_path}/.intermediates/layout-analysis/inspirations/
+  - Visual references: {loaded_images if available}
+  ${dom_structure_available ? "- DOM Structure: Read from .intermediates/layout-analysis/dom-structure-*.json" : ""}
+
+  ## Analysis Rules
+  - For EACH target, generate {variants_count} structurally DIFFERENT layout concepts
+  - Concepts must differ in: grid structure, component arrangement, visual hierarchy
+  - Each concept should have distinct navigation pattern, content flow, and responsive behavior
+
+  ## Generate for EACH Target
+  For target in {targets}:
+    For concept_index in 1..{variants_count}:
+      1. **Concept Definition**:
+         - concept_name (descriptive, e.g., "Classic Three-Column Holy Grail")
+         - design_philosophy (1-2 sentences explaining the structural approach)
+         - layout_pattern (e.g., "grid-3col", "flex-row", "single-column", "asymmetric-grid")
+         - key_components (array of main layout regions)
+         - structural_features (list of distinguishing characteristics)
+
+      2. **Wireframe Preview** (simple text representation):
+         - ascii_art (simple ASCII box diagram showing layout structure)
+         - Example:
+           ┌─────────────────┐
+           │     HEADER      │
+           ├──┬─────────┬────┤
+           │ L│  MAIN   │ R  │
+           └──┴─────────┴────┘
+
+  ## Output
+  Write single JSON file: {base_path}/.intermediates/layout-analysis/analysis-options.json
+
+  Use schema from INTERACTIVE-DATA-SPEC.md (Layout Extract: analysis-options.json)
+
+  CRITICAL: Use Write() tool immediately after generating complete JSON
+`
+```
+
+### Step 4: Verify Options File Created
+```bash
+bash(test -f {base_path}/.intermediates/layout-analysis/analysis-options.json && echo "created")
+
+# Quick validation
+bash(cat {base_path}/.intermediates/layout-analysis/analysis-options.json | grep -q "layout_concepts" && echo "valid")
+```
+
+**Output**: `analysis-options.json` with layout concept options for all targets
+
+---
+
+## Phase 1.5: User Confirmation (Explore Mode Only - INTERACTIVE)
+
+**Purpose**: Allow user to select preferred layout concept(s) for each target before generating detailed templates
+
+### Step 1: Load and Present Options
+```bash
+# Read options file
+options = Read({base_path}/.intermediates/layout-analysis/analysis-options.json)
+
+# Parse layout concepts
+layout_concepts = options.layout_concepts
+```
+
+### Step 2: Present Options to User (Per Target)
+For each target, present layout concept options and capture selection:
+
+```
+📋 Layout Concept Options for Target: {target}
+
+We've generated {variants_count} structurally different layout concepts for review.
+Please select your preferred concept for this target.
+
+{FOR each concept in layout_concepts[target]:
+  ═══════════════════════════════════════════════════
+  Concept {concept.index}: {concept.concept_name}
+  ═══════════════════════════════════════════════════
+
+  Philosophy: {concept.design_philosophy}
+  Pattern: {concept.layout_pattern}
+
+  Components:
+  {FOR each component in concept.key_components:
+    • {component}
+  }
+
+  Features:
+  {FOR each feature in concept.structural_features:
+    • {feature}
+  }
+
+  Wireframe:
+  {concept.wireframe_preview.ascii_art}
+
+  ═══════════════════════════════════════════════════
+}
+```
+
+### Step 3: Capture User Selection (Per Target)
+```javascript
+// Use AskUserQuestion tool for each target
+FOR each target:
+  AskUserQuestion({
+    questions: [{
+      question: "Which layout concept do you prefer for '{target}'?",
+      header: "Layout for " + target,
+      multiSelect: false,
+      options: [
+        {FOR each concept in layout_concepts[target]:
+          label: "Concept {concept.index}: {concept.concept_name}",
+          description: "{concept.design_philosophy}"
+        }
+      ]
+    }]
+  })
+
+  // Parse user response
+  selected_option_text = user_answer
+
+  // Check for user cancellation
+  IF selected_option_text == null OR selected_option_text == "":
+      REPORT: "⚠️ User canceled selection. Workflow terminated."
+      EXIT workflow
+
+  // Extract concept index from response format "Concept N: Name"
+  match = selected_option_text.match(/Concept (\d+):/)
+  IF match:
+      selected_index = parseInt(match[1])
+  ELSE:
+      ERROR: "Invalid selection format. Expected 'Concept N: ...' format"
+      EXIT workflow
+
+  // Store selection for this target
+  selections[target] = {
+    selected_index: selected_index,
+    concept_name: layout_concepts[target][selected_index-1].concept_name
+  }
+```
+
+### Step 4: Write User Selection File
+```bash
+# Create user selection JSON
+selection_data = {
+  "metadata": {
+    "selected_at": "{current_timestamp}",
+    "selection_type": "per_target",
+    "session_id": "{session_id}"
+  },
+  "selections": selections  // {target: {selected_index, concept_name}}
+}
+
+# Write to file
+bash(echo '{selection_data}' > {base_path}/.intermediates/layout-analysis/user-selection.json)
+
+# Verify
+bash(test -f {base_path}/.intermediates/layout-analysis/user-selection.json && echo "saved")
+```
+
+### Step 5: Confirmation Message
+```
+✅ Selections recorded!
+
+{FOR each target, selection in selections:
+  • {target}: Concept {selection.selected_index} - {selection.concept_name}
+}
+
+Proceeding to generate detailed layout templates based on your selections...
+```
+
+**Output**: `user-selection.json` with user's choices for all targets
+
+## Phase 2: Layout Template Generation (Agent Task 2)
+
+**Executor**: `Task(ui-design-agent)` for selected concept(s)
+
+### Step 1: Load User Selection (Explore Mode)
+```bash
+# For explore mode, read user selection
+IF extraction_mode == "explore":
+    selection = Read({base_path}/.intermediates/layout-analysis/user-selection.json)
+    selections_per_target = selection.selections
+
+    # Also read the selected concept details from options
+    options = Read({base_path}/.intermediates/layout-analysis/analysis-options.json)
+    layout_concepts = options.layout_concepts
+
+    # Build selected concepts map
+    selected_concepts = {}
+    FOR each target in targets:
+        selected_index = selections_per_target[target].selected_index
+        selected_concepts[target] = layout_concepts[target][selected_index-1]  # 0-indexed
+ELSE:
+    # Imitate mode - no selection needed
+    selected_concepts = null
+```
+
+### Step 2: Launch Agent Task
+Generate layout templates for selected concepts:
+```javascript
+Task(ui-design-agent): `
+  [LAYOUT_TEMPLATE_GENERATION_TASK]
+  Generate detailed layout templates based on user-selected concepts.
   Focus ONLY on structure and layout. DO NOT concern with visual style (colors, fonts, etc.).
 
-  REFERENCES:
-  - Input: {reference_material}  // Images, URLs, or prompt
-  - Mode: {extraction_mode}  // 'imitate' or 'explore'
-  - Targets: {targets}  // List of page/component names
-  - Variants per Target: {variants_count}
-  - Device Type: {device_type}
-  ${exploration_mode ? "- Layout Inspiration: Read('" + base_path + "/.intermediates/layout-analysis/inspirations/{target}-layout-ideas.txt')" : ""}
-  ${dom_structure_available ? "- DOM Structure Data: Read('" + base_path + "/.intermediates/layout-analysis/dom-structure-{target}.json') - USE THIS for accurate layout properties" : ""}
+  SESSION: {session_id} | MODE: {extraction_mode} | BASE_PATH: {base_path}
+  DEVICE_TYPE: {device_type}
 
-  ## Analysis & Generation
-  ${dom_structure_available ? "IMPORTANT: You have access to real DOM structure data with accurate flex/grid properties, bounds, and hierarchy. Use this data as ground truth for layout analysis." : ""}
-  For EACH target in {targets}:
-    For EACH variant (1 to {variants_count}):
-      1. **Analyze Structure**:
-         ${dom_structure_available ?
-           "- Use DOM structure data as primary source for layout properties" +
-           "- Extract real flex/grid configurations (display, flexDirection, justifyContent, alignItems, gap)" +
-           "- Use actual element bounds for responsive breakpoint decisions" +
-           "- Preserve identified patterns (flex-row, flex-column, grid-NCol)" +
-           "- Reference screenshots for visual context only" :
-           "- Deconstruct reference images/URLs to understand layout, hierarchy, responsiveness"}
-      2. **Define Philosophy**: Short description (e.g., "Asymmetrical grid with overlapping content areas")
-      3. **Generate DOM Structure**:
-         ${dom_structure_available ?
-           "- Base structure on extracted DOM tree from .intermediates" +
-           "- Preserve semantic tags and hierarchy from dom-structure-{target}.json" +
-           "- Maintain layout patterns identified in patterns field" :
-           "- JSON object representing semantic HTML5 structure"}
-         - Semantic tags: <header>, <nav>, <main>, <aside>, <section>, <footer>
-         - ARIA roles and accessibility attributes
-         - Device-specific structure:
-           * mobile: Single column, stacked sections, touch targets ≥44px
-           * desktop: Multi-column grids, hover states, larger hit areas
-           * tablet: Hybrid layouts, flexible columns
-           * responsive: Breakpoint-driven adaptive layouts (mobile-first)
-         - In 'explore' mode: Each variant structurally DISTINCT
-      4. **Define Component Hierarchy**: High-level array of main layout regions
-         Example: ["header", "main-content", "sidebar", "footer"]
-      5. **Generate CSS Layout Rules**:
-         ${dom_structure_available ?
-           "- Use real layout properties from DOM structure data" +
-           "- Convert extracted flex/grid values to CSS rules" +
-           "- Preserve actual gap, justifyContent, alignItems values" +
-           "- Use element bounds to inform responsive breakpoints" :
-           "- Focus ONLY on layout (Grid, Flexbox, position, alignment, gap, etc.)"}
-         - Use CSS Custom Properties for spacing/breakpoints: var(--spacing-4), var(--breakpoint-md)
-         - Device-specific styles (mobile-first @media for responsive)
-         - NO colors, NO fonts, NO shadows - layout structure only
+  ${extraction_mode == "explore" ? `
+  USER SELECTIONS:
+  ${targets.map(target => `
+  Target: ${target}
+  - Selected Concept: ${selected_concepts[target].concept_name}
+  - Philosophy: ${selected_concepts[target].design_philosophy}
+  - Pattern: ${selected_concepts[target].layout_pattern}
+  - Key Components: ${selected_concepts[target].key_components.join(", ")}
+  - Structural Features: ${selected_concepts[target].structural_features.join(", ")}
+  `).join("\n")}
+  ` : `
+  MODE: Imitate - High-fidelity replication of reference layout structure
+  TARGETS: ${targets.join(", ")}
+  `}
+
+  ## Input Analysis
+  - Targets: {targets.join(", ")}
+  - Device type: {device_type}
+  - Visual references: {loaded_images if available}
+  ${dom_structure_available ? "- DOM Structure Data: Read from .intermediates/layout-analysis/dom-structure-*.json - USE THIS for accurate layout properties" : ""}
+
+  ## Generation Rules
+  ${extraction_mode == "explore" ? `
+  - **Explore Mode**: Develop each user-selected layout concept into a detailed template
+  - Use the selected concept's key_components as foundation
+  - Apply the selected layout_pattern (grid-3col, flex-row, etc.)
+  - Honor the structural_features defined in the concept
+  - Expand the concept with complete DOM structure and CSS layout rules
+  ` : `
+  - **Imitate Mode**: High-fidelity replication of reference layout structure
+  ${dom_structure_available ? "- Use DOM structure data as ground truth" : "- Use visual inference"}
+  `}
+  ${dom_structure_available ? `
+  - IMPORTANT: You have access to real DOM structure data with accurate flex/grid properties
+  - Use DOM data as primary source for layout properties
+  - Extract real flex/grid configurations (display, flexDirection, justifyContent, alignItems, gap)
+  - Use actual element bounds for responsive breakpoint decisions
+  - Preserve identified patterns from DOM structure
+  ` : ""}
+
+  ## Generate for EACH Target
+  For target in {targets}:
+    ${extraction_mode == "explore" ? "Based on user-selected concept:" : "Based on reference:"}
+
+    1. **DOM Structure**:
+       - Semantic HTML5 tags: <header>, <nav>, <main>, <aside>, <section>, <footer>
+       - ARIA roles and accessibility attributes
+       ${extraction_mode == "explore" ? "- Use key_components from selected concept" : ""}
+       ${dom_structure_available ? "- Base on extracted DOM tree from .intermediates" : "- Infer from visual analysis"}
+       - Device-specific optimizations for {device_type}
+
+    2. **Component Hierarchy**:
+       - Array of main layout regions
+       ${extraction_mode == "explore" ? "- Derived from selected concept's key_components" : ""}
+
+    3. **CSS Layout Rules**:
+       ${extraction_mode == "explore" ? "- Implement selected layout_pattern" : ""}
+       ${dom_structure_available ? "- Use real layout properties from DOM structure data" : "- Focus on Grid, Flexbox, position, alignment"}
+       - Use CSS Custom Properties: var(--spacing-*), var(--breakpoint-*)
+       - Device-specific styles (mobile-first @media for responsive)
+       - NO colors, NO fonts, NO shadows - layout structure only
 
   ## Output Format
-  Return JSON object with layout_templates array.
+  Write complete layout-templates.json with layout_templates array.
   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"
+  - variant_id: "layout-1" (always 1 since only selected concept is generated)
+  - source_image_path (string): Reference image path
   - device_type (string)
-  - design_philosophy (string)
+  - design_philosophy (string ${extraction_mode == "explore" ? "- from selected concept" : ""})
   - dom_structure (JSON object)
   - component_hierarchy (array of strings)
   - css_layout_rules (string)
 
-  ## Notes
-  - Structure only, no visual styling
-  - Use var() for all spacing/sizing
-  - Layouts must be structurally distinct in explore mode
-  - Write complete layout-templates.json
+  ## Critical Requirements
+  - ✅ Use Write() tool for layout-templates.json
+  - ✅ One template per target (only selected concept)
+  - ✅ Structure only, no visual styling
+  - ✅ Token-based CSS (var())
+  ${extraction_mode == "explore" ? "- ✅ Maintain consistency with selected concepts" : ""}
 `
 ```
 
-**Output**: Agent returns JSON with `layout_templates` array
+**Output**: Agent generates `layout-templates.json` with one template per target
 
 ### Step 2: Write Output File
 ```bash
@@ -266,6 +558,13 @@ Configuration:
 - Targets: {targets}
 - Variants per Target: {variants_count}
 - Total Templates: {targets.length × variants_count}
+{IF has_urls AND dom_structure_available:
+- 🔍 URL Mode: DOM structure extracted from {len(url_list)} URL(s)
+- Accuracy: Real flex/grid properties from live pages
+}
+{IF has_urls AND NOT dom_structure_available:
+- ⚠️ URL Mode: Chrome DevTools unavailable, used visual analysis fallback
+}
 
 {IF extraction_mode == "explore":
 Layout Research:
@@ -278,6 +577,9 @@ Generated Templates:
 
 Output File:
 - {base_path}/layout-extraction/layout-templates.json
+{IF dom_structure_available:
+- {base_path}/.intermediates/layout-analysis/dom-structure-*.json ({len(url_list)} files)
+}
 
 Next: /workflow:ui-design:generate will combine these structural templates with style systems to produce final prototypes.
 ```
@@ -412,13 +714,14 @@ ERROR: MCP search failed (explore mode)
 
 ## Key Features
 
+- **Auto-Trigger URL Mode** - Automatically extracts DOM structure when --urls provided (no manual flag needed)
 - **Hybrid Extraction Strategy** - Combines real DOM structure data with AI visual analysis
 - **Accurate Layout Properties** - Chrome DevTools extracts real flex/grid configurations, bounds, and hierarchy
 - **Separation of Concerns** - Decouples layout (structure) from style (visuals)
 - **Structural Exploration** - Explore mode enables A/B testing of different layouts
 - **Token-Based Layout** - CSS uses `var()` placeholders for instant design system adaptation
 - **Device-Specific** - Tailored structures for different screen sizes
-- **Graceful Fallback** - Works with images/text when URL unavailable
+- **Graceful Fallback** - Falls back to visual analysis if Chrome DevTools unavailable
 - **Foundation for Assembly** - Provides structural blueprint for refactored `generate` command
 - **Agent-Powered** - Deep structural analysis with AI
 

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

@@ -1,8 +1,8 @@
 ---
 name: style-extract
 description: Extract design style from reference images or text prompts using Claude's analysis
-argument-hint: "[--base-path <path>] [--session <id>] [--images "<glob>"] [--prompt "<desc>"] [--mode <imitate|explore>] [--variants <count>]"
-allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*)
+argument-hint: "[--base-path <path>] [--session <id>] [--images "<glob>"] [--urls "<list>"] [--prompt "<desc>"] [--mode <imitate|explore>] [--variants <count>]"
+allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), mcp__chrome-devtools__navigate_page(*), mcp__chrome-devtools__evaluate_script(*)
 ---
 
 # Style Extraction Command
@@ -22,7 +22,23 @@ Extract design style from reference images or text prompts using Claude's built-
 ### Step 1: Detect Input Mode, Extraction Mode & Base Path
 ```bash
 # Detect input source
-# Priority: --images + --prompt → hybrid | --images → image | --prompt → text
+# Priority: --urls + --images + --prompt → hybrid-url | --urls + --images → url-image | --urls → url | --images + --prompt → hybrid | --images → image | --prompt → text
+
+# Parse URLs if provided (format: "target:url,target:url,...")
+IF --urls:
+    url_list = []
+    FOR pair IN split(--urls, ","):
+        IF ":" IN pair:
+            target, url = pair.split(":", 1)
+            url_list.append({target: target.strip(), url: url.strip()})
+        ELSE:
+            # Single URL without target
+            url_list.append({target: "page", url: pair.strip()})
+
+    has_urls = true
+    primary_url = url_list[0].url  # First URL as primary source
+ELSE:
+    has_urls = false
 
 # Determine extraction mode
 # Priority: --mode parameter → default "imitate"
@@ -40,32 +56,48 @@ bash(find .workflow -type d -name "design-*" | head -1)  # Auto-detect
 # OR use --base-path / --session parameters
 ```
 
-### Step 2: Extract Computed Styles (URL Mode - Optional Enhancement)
+### Step 2: Extract Computed Styles (URL Mode - Auto-Trigger)
 ```bash
-# If URL is available from capture metadata, extract real CSS values
+# AUTO-TRIGGER: If URLs are available (from --urls parameter or capture metadata), automatically extract real CSS values
 # This provides accurate design tokens to supplement visual analysis
 
-# Check for URL metadata from capture phase
-Read({base_path}/.metadata/capture-urls.json)  # If exists
+# Priority 1: Check for --urls parameter
+IF has_urls:
+    url_to_extract = primary_url
+    url_source = "--urls parameter"
+
+# Priority 2: Check for URL metadata from capture phase
+ELSE IF exists({base_path}/.metadata/capture-urls.json):
+    capture_urls = Read({base_path}/.metadata/capture-urls.json)
+    url_to_extract = capture_urls[0]  # Use first URL
+    url_source = "capture metadata"
+ELSE:
+    url_to_extract = null
+
+# Execute extraction if URL available
+IF url_to_extract AND mcp_chrome_devtools_available:
+    REPORT: "🔍 Auto-triggering URL mode: Extracting computed styles from {url_source}"
+    REPORT: "   URL: {url_to_extract}"
 
-# For each URL in capture metadata:
-IF url_available AND mcp_chrome_devtools_available:
     # Read extraction script
-    Read(~/.claude/scripts/extract-computed-styles.js)
+    script_content = Read(~/.claude/scripts/extract-computed-styles.js)
 
     # Open page in Chrome DevTools
-    mcp__chrome-devtools__navigate_page(url="{target_url}")
+    mcp__chrome-devtools__navigate_page(url=url_to_extract)
 
     # Execute extraction script directly
-    result = mcp__chrome-devtools__evaluate_script(function="[SCRIPT_CONTENT]")
+    result = mcp__chrome-devtools__evaluate_script(function=script_content)
 
     # Save computed styles to intermediates directory
     bash(mkdir -p {base_path}/.intermediates/style-analysis)
     Write({base_path}/.intermediates/style-analysis/computed-styles.json, result)
 
     computed_styles_available = true
+    REPORT: "   ✅ Computed styles extracted and saved"
 ELSE:
     computed_styles_available = false
+    IF url_to_extract:
+        REPORT: "⚠️ Chrome DevTools MCP not available, falling back to visual analysis"
 ```
 
 **Extraction Script Reference**: `~/.claude/scripts/extract-computed-styles.js`
@@ -106,9 +138,9 @@ IF exists: SKIP to completion
 
 ---
 
-**Phase 0 Output**: `input_mode`, `base_path`, `extraction_mode`, `variants_count`, `loaded_images[]` or `prompt_guidance`
+**Phase 0 Output**: `input_mode`, `base_path`, `extraction_mode`, `variants_count`, `loaded_images[]` or `prompt_guidance`, `has_urls`, `url_list[]`, `computed_styles_available`
 
-## Phase 1: Design Space Analysis (Explore Mode Only)
+## Phase 1: Design Direction Generation (Explore Mode Only)
 
 ### Step 1: Check Extraction Mode
 ```bash
@@ -125,97 +157,289 @@ IF exists: SKIP to completion
 bash(test -f {base_path}/.brainstorming/synthesis-specification.md && cat it)
 ```
 
-### Step 3: Generate Divergent Directions (Claude Native)
-AI analyzes requirements and generates `variants_count` maximally contrasting design directions:
+### Step 3: Generate Design Direction Options (Agent Task 1)
+**Executor**: `Task(ui-design-agent)`
 
-**Input**: User prompt + project context + image count
-**Analysis**: 6D attribute space (color saturation, visual weight, formality, organic/geometric, innovation, density)
-**Output**: JSON with divergent_directions, each having:
-- philosophy_name (2-3 words)
-- design_attributes (specific scores)
-- search_keywords (3-5 keywords)
-- anti_keywords (2-3 keywords)
-- rationale (contrast explanation)
+Launch agent to generate `variants_count` design direction options with previews:
 
-### Step 4: Write Design Space Analysis
-```bash
-bash(mkdir -p {base_path}/.intermediates/style-analysis)
-bash(echo '{design_space_analysis}' > {base_path}/.intermediates/style-analysis/design-space-analysis.json)
-
-# Verify output
-bash(test -f {base_path}/.intermediates/style-analysis/design-space-analysis.json && echo "saved")
-```
-
-**Output**: `design-space-analysis.json` (intermediate analysis file)
-
-## Phase 2: Design System Generation (Agent)
-
-**Executor**: `Task(ui-design-agent)` for all variants
-
-### Step 1: Create Output Directories
-```bash
-bash(mkdir -p {base_path}/style-extraction/style-{{1..{variants_count}}})
-```
-
-### Step 2: Launch Agent Task
-For all variants (1 to {variants_count}):
 ```javascript
 Task(ui-design-agent): `
-  [DESIGN_SYSTEM_GENERATION_TASK]
-  Generate {variants_count} independent production-ready design systems
+  [DESIGN_DIRECTION_GENERATION_TASK]
+  Generate {variants_count} maximally contrasting design directions with visual previews
 
-  SESSION: {session_id} | MODE: {extraction_mode} | BASE_PATH: {base_path}
-
-  CRITICAL PATH: Use loop index (N) for directories: style-1/, style-2/, ..., style-N/
-
-  VARIANT DATA:
-  {FOR each variant with index N:
-    VARIANT INDEX: {N}
-    {IF extraction_mode == "explore":
-      Design Philosophy: {divergent_direction[N].philosophy_name}
-      Design Attributes: {divergent_direction[N].design_attributes}
-      Search Keywords: {divergent_direction[N].search_keywords}
-      Anti-keywords: {divergent_direction[N].anti_keywords}
-    }
-  }
+  SESSION: {session_id} | MODE: explore | BASE_PATH: {base_path}
 
   ## Input Analysis
-  - Input mode: {input_mode} (image/text/hybrid)
-  - Visual references: {loaded_images OR prompt_guidance}
-  - Computed styles: {computed_styles if available}
-  - Design space analysis: {design_space_analysis if explore mode}
+  - User prompt: {prompt_guidance}
+  - Visual references: {loaded_images if available}
+  - Project context: {brainstorming_context if available}
 
   ## Analysis Rules
-  - **Explore mode**: Each variant follows pre-defined philosophy and attributes
-  - **Imitate mode**: High-fidelity replication of reference design
-    - If computed_styles available: Use as ground truth for border-radius, shadows, spacing, typography, colors
-    - Otherwise: Visual inference
-  - OKLCH color format (convert RGB from computed styles)
-  - WCAG AA compliance: 4.5:1 text, 3:1 UI
+  - Analyze 6D attribute space: color saturation, visual weight, formality, organic/geometric, innovation, density
+  - Generate {variants_count} directions with MAXIMUM contrast
+  - Each direction must be distinctly different (min distance score: 0.7)
 
-  ## Generate (For EACH variant, use loop index N for paths)
-  1. {base_path}/style-extraction/style-{N}/design-tokens.json
-     - Complete token structure: colors, typography, spacing, border_radius, shadows, breakpoints
-     - All colors in OKLCH format
-     - {IF explore mode: Apply design_attributes to token values (saturation→chroma, density→spacing, etc.)}
+  ## Generate for EACH Direction
+  1. **Core Philosophy**:
+     - philosophy_name (2-3 words, e.g., "Minimalist & Airy")
+     - design_attributes (6D scores 0-1)
+     - search_keywords (3-5 keywords)
+     - anti_keywords (2-3 keywords to avoid)
+     - rationale (why this is distinct from others)
 
-  2. {base_path}/style-extraction/style-{N}/style-guide.md
-     - Expanded design philosophy
-     - Complete color system with accessibility notes
-     - Typography documentation
-     - Usage guidelines
+  2. **Visual Preview Elements**:
+     - primary_color (OKLCH format)
+     - secondary_color (OKLCH format)
+     - accent_color (OKLCH format)
+     - font_family_heading (specific font name)
+     - font_family_body (specific font name)
+     - border_radius_base (e.g., "0.5rem")
+     - mood_description (1-2 sentences describing the feel)
 
-  ## Critical Requirements
-  - ✅ Use Write() tool immediately for each file
-  - ✅ Use loop index N for directory names: style-1/, style-2/, etc.
-  - ❌ NO external research or MCP calls (pure AI generation)
-  - {IF explore mode: Apply philosophy-driven refinement using design_attributes}
-  - {IF explore mode: Maintain divergence using anti_keywords}
-  - Complete each variant's files before moving to next variant
+  ## Output
+  Write single JSON file: {base_path}/.intermediates/style-analysis/analysis-options.json
+
+  Use schema from INTERACTIVE-DATA-SPEC.md (Style Extract: analysis-options.json)
+
+  CRITICAL: Use Write() tool immediately after generating complete JSON
 `
 ```
 
-**Output**: Agent generates `variants_count × 2` files
+### Step 4: Verify Options File Created
+```bash
+bash(test -f {base_path}/.intermediates/style-analysis/analysis-options.json && echo "created")
+
+# Quick validation
+bash(cat {base_path}/.intermediates/style-analysis/analysis-options.json | grep -q "design_directions" && echo "valid")
+```
+
+**Output**: `analysis-options.json` with design direction options
+
+---
+
+## Phase 1.5: User Confirmation (Explore Mode Only - INTERACTIVE)
+
+**Purpose**: Allow user to select preferred design direction(s) before generating full design systems
+
+### Step 1: Load and Present Options
+```bash
+# Read options file
+options = Read({base_path}/.intermediates/style-analysis/analysis-options.json)
+
+# Parse design directions
+design_directions = options.design_directions
+```
+
+### Step 2: Present Options to User
+```
+📋 Design Direction Options
+
+We've generated {variants_count} contrasting design directions for your review.
+Please select the direction(s) you'd like to develop into complete design systems.
+
+{FOR each direction in design_directions:
+  ═══════════════════════════════════════════════════
+  Option {direction.index}: {direction.philosophy_name}
+  ═══════════════════════════════════════════════════
+
+  Philosophy: {direction.rationale}
+
+  Visual Preview:
+  • Colors: {direction.preview.primary_color} (primary), {direction.preview.accent_color} (accent)
+  • Typography: {direction.preview.font_family_heading} (headings), {direction.preview.font_family_body} (body)
+  • Border Radius: {direction.preview.border_radius_base}
+  • Mood: {direction.preview.mood_description}
+
+  Design Attributes:
+  • Color Saturation: {direction.design_attributes.color_saturation * 100}%
+  • Visual Weight: {direction.design_attributes.visual_weight * 100}%
+  • Formality: {direction.design_attributes.formality * 100}%
+  • Innovation: {direction.design_attributes.innovation * 100}%
+
+  Keywords: {join(direction.search_keywords, ", ")}
+  Avoiding: {join(direction.anti_keywords, ", ")}
+}
+
+═══════════════════════════════════════════════════
+```
+
+### Step 3: Capture User Selection
+```javascript
+// Use AskUserQuestion tool for selection
+AskUserQuestion({
+  questions: [{
+    question: "Which design direction would you like to develop into a complete design system?",
+    header: "Style Choice",
+    multiSelect: false,  // Single selection for Phase 1
+    options: [
+      {FOR each direction:
+        label: "Option {direction.index}: {direction.philosophy_name}",
+        description: "{direction.mood_description}"
+      }
+    ]
+  }]
+})
+
+// Parse user response (e.g., "Option 1: Minimalist & Airy")
+selected_option_text = user_answer
+
+// Check for user cancellation
+IF selected_option_text == null OR selected_option_text == "":
+    REPORT: "⚠️ User canceled selection. Workflow terminated."
+    EXIT workflow
+
+// Extract option index from response format "Option N: Name"
+match = selected_option_text.match(/Option (\d+):/)
+IF match:
+    selected_index = parseInt(match[1])
+ELSE:
+    ERROR: "Invalid selection format. Expected 'Option N: ...' format"
+    EXIT workflow
+```
+
+### Step 4: Write User Selection File
+```bash
+# Create user selection JSON
+selection_data = {
+  "metadata": {
+    "selected_at": "{current_timestamp}",
+    "selection_type": "single",
+    "session_id": "{session_id}"
+  },
+  "selected_indices": [selected_index],
+  "refinements": {
+    "enabled": false
+  }
+}
+
+# Write to file
+bash(echo '{selection_data}' > {base_path}/.intermediates/style-analysis/user-selection.json)
+
+# Verify
+bash(test -f {base_path}/.intermediates/style-analysis/user-selection.json && echo "saved")
+```
+
+### Step 5: Confirmation Message
+```
+✅ Selection recorded!
+
+You selected: Option {selected_index} - {selected_direction.philosophy_name}
+
+Proceeding to generate complete design system based on your selection...
+```
+
+**Output**: `user-selection.json` with user's choice
+
+## Phase 2: Design System Generation (Agent Task 2)
+
+**Executor**: `Task(ui-design-agent)` for selected variant(s)
+
+### Step 1: Load User Selection (Explore Mode)
+```bash
+# For explore mode, read user selection
+IF extraction_mode == "explore":
+    selection = Read({base_path}/.intermediates/style-analysis/user-selection.json)
+    selected_indices = selection.selected_indices
+    refinements = selection.refinements
+
+    # Also read the selected direction details from options
+    options = Read({base_path}/.intermediates/style-analysis/analysis-options.json)
+    selected_directions = [options.design_directions[i-1] for i in selected_indices]  # 0-indexed
+
+    # For Phase 1, we only allow single selection
+    selected_direction = selected_directions[0]
+    actual_variants_count = 1
+ELSE:
+    # Imitate mode - generate single variant without selection
+    selected_direction = null
+    actual_variants_count = 1
+```
+
+### Step 2: Create Output Directory
+```bash
+# Create directory for selected variant only
+bash(mkdir -p {base_path}/style-extraction/style-1)
+```
+
+### Step 3: Launch Agent Task
+Generate design system for selected direction:
+```javascript
+Task(ui-design-agent): `
+  [DESIGN_SYSTEM_GENERATION_TASK]
+  Generate production-ready design system based on user-selected direction
+
+  SESSION: {session_id} | MODE: {extraction_mode} | BASE_PATH: {base_path}
+
+  ${extraction_mode == "explore" ? `
+  USER SELECTION:
+  - Selected Direction: ${selected_direction.philosophy_name}
+  - Design Attributes: ${JSON.stringify(selected_direction.design_attributes)}
+  - Search Keywords: ${selected_direction.search_keywords.join(", ")}
+  - Anti-keywords: ${selected_direction.anti_keywords.join(", ")}
+  - Rationale: ${selected_direction.rationale}
+  - Preview Colors: Primary=${selected_direction.preview.primary_color}, Accent=${selected_direction.preview.accent_color}
+  - Preview Typography: Heading=${selected_direction.preview.font_family_heading}, Body=${selected_direction.preview.font_family_body}
+  - Preview Border Radius: ${selected_direction.preview.border_radius_base}
+
+  ${refinements.enabled ? `
+  USER REFINEMENTS:
+  ${refinements.primary_color ? "- Primary Color Override: " + refinements.primary_color : ""}
+  ${refinements.font_family_heading ? "- Heading Font Override: " + refinements.font_family_heading : ""}
+  ${refinements.font_family_body ? "- Body Font Override: " + refinements.font_family_body : ""}
+  ` : ""}
+  ` : ""}
+
+  ## Input Analysis
+  - Input mode: {input_mode} (image/text/hybrid${has_urls ? "/url" : ""})
+  - Visual references: {loaded_images OR prompt_guidance}
+  ${computed_styles_available ? "- Computed styles: Use as ground truth (Read from .intermediates/style-analysis/computed-styles.json)" : ""}
+
+  ## Generation Rules
+  ${extraction_mode == "explore" ? `
+  - **Explore Mode**: Develop the selected design direction into a complete design system
+  - Use preview elements as foundation and expand with full token coverage
+  - Apply design_attributes to all token values:
+    * color_saturation → OKLCH chroma values
+    * visual_weight → font weights, shadow depths
+    * density → spacing scale compression/expansion
+    * formality → typography choices, border radius
+    * organic_geometric → border radius, shape patterns
+    * innovation → token naming, experimental values
+  - Honor search_keywords for design inspiration
+  - Avoid anti_keywords patterns
+  ` : `
+  - **Imitate Mode**: High-fidelity replication of reference design
+  ${computed_styles_available ? "- Use computed styles as ground truth for all measurements" : "- Use visual inference for measurements"}
+  `}
+  - All colors in OKLCH format ${computed_styles_available ? "(convert from computed RGB)" : ""}
+  - WCAG AA compliance: 4.5:1 text contrast, 3:1 UI contrast
+
+  ## Generate
+  Create complete design system in {base_path}/style-extraction/style-1/
+
+  1. **design-tokens.json**:
+     - Complete token structure: colors (brand, surface, semantic, text, border), typography (families, sizes, weights, line heights, letter spacing), spacing (0-24 scale), border_radius (none to full), shadows (sm to xl), breakpoints (sm to 2xl)
+     - All colors in OKLCH format
+     ${extraction_mode == "explore" ? "- Start from preview colors and expand to full palette" : ""}
+     ${extraction_mode == "explore" && refinements.enabled ? "- Apply user refinements where specified" : ""}
+
+  2. **style-guide.md**:
+     - Design philosophy (${extraction_mode == "explore" ? "expand on: " + selected_direction.philosophy_name : "describe the reference design"})
+     - Complete color system documentation with accessibility notes
+     - Typography scale and usage guidelines
+     - Spacing system explanation
+     - Component examples and usage patterns
+
+  ## Critical Requirements
+  - ✅ Use Write() tool immediately for each file
+  - ✅ Write to style-1/ directory (single output)
+  - ❌ NO external research or MCP calls (pure AI generation)
+  - ✅ Maintain consistency with user-selected direction
+  ${refinements.enabled ? "- ✅ Apply user refinements precisely" : ""}
+`
+```
+
+**Output**: Agent generates 2 files (design-tokens.json, style-guide.md) for selected direction
 
 ## Phase 3: Verify Output
 
@@ -254,25 +478,34 @@ TodoWrite({todos: [
 Configuration:
 - Session: {session_id}
 - Extraction Mode: {extraction_mode} (imitate/explore)
-- Input Mode: {input_mode} (image/text/hybrid)
+- Input Mode: {input_mode} (image/text/hybrid{"/url" if has_urls else ""})
 - Variants: {variants_count}
 - Production-Ready: Complete design systems generated
+{IF has_urls AND computed_styles_available:
+- 🔍 URL Mode: Computed styles extracted from {len(url_list)} URL(s)
+- Accuracy: Pixel-perfect design tokens from DOM
+}
+{IF has_urls AND NOT computed_styles_available:
+- ⚠️ URL Mode: Chrome DevTools unavailable, used visual analysis fallback
+}
 
 {IF extraction_mode == "explore":
-Design Space Analysis:
-- {variants_count} maximally contrasting design directions
-- Min contrast distance: {design_space_analysis.contrast_verification.min_pairwise_distance}
+Design Direction Selection:
+- You selected: Option {selected_index} - {selected_direction.philosophy_name}
+- Generated from {variants_count} contrasting design direction options
 }
 
 Generated Files:
 {base_path}/style-extraction/
-├── style-1/ (design-tokens.json, style-guide.md)
-├── style-2/ (same structure)
-└── style-{variants_count}/ (same structure)
+└── style-1/ (design-tokens.json, style-guide.md)
 
-{IF extraction_mode == "explore":
+{IF computed_styles_available:
 Intermediate Analysis:
-{base_path}/.intermediates/style-analysis/design-space-analysis.json
+{base_path}/.intermediates/style-analysis/computed-styles.json (extracted from {primary_url})
+}
+{IF extraction_mode == "explore":
+{base_path}/.intermediates/style-analysis/analysis-options.json (design direction options)
+{base_path}/.intermediates/style-analysis/user-selection.json (your selection)
 }
 
 Next: /workflow:ui-design:layout-extract --session {session_id} --targets "..."
@@ -315,7 +548,7 @@ bash(mkdir -p {base_path}/style-extraction/style-{{1..3}})
 
 # Verify output
 bash(ls {base_path}/style-extraction/style-1/)
-bash(test -f {base_path}/.intermediates/style-analysis/design-space-analysis.json && echo "saved")
+bash(test -f {base_path}/.intermediates/style-analysis/analysis-options.json && echo "saved")
 ```
 
 ## Output Structure
@@ -325,13 +558,12 @@ bash(test -f {base_path}/.intermediates/style-analysis/design-space-analysis.jso
 ├── .intermediates/                  # Intermediate analysis files
 │   └── style-analysis/
 │       ├── computed-styles.json     # Extracted CSS values from DOM (if URL available)
-│       └── design-space-analysis.json  # Design directions (explore mode only)
-└── style-extraction/                # Final design systems
-    ├── style-1/
-    │   ├── design-tokens.json       # Production-ready design tokens
-    │   └── style-guide.md           # Design philosophy and usage guide
-    ├── style-2/ (same structure)
-    └── style-N/ (same structure)
+│       ├── analysis-options.json    # Design direction options (explore mode only)
+│       └── user-selection.json      # User's selected direction (explore mode only)
+└── style-extraction/                # Final design system
+    └── style-1/
+        ├── design-tokens.json       # Production-ready design tokens
+        └── style-guide.md           # Design philosophy and usage guide
 ```
 
 ## design-tokens.json Format
@@ -371,6 +603,7 @@ ERROR: Claude JSON parsing error
 
 ## Key Features
 
+- **Auto-Trigger URL Mode** - Automatically extracts computed styles when --urls provided (no manual flag needed)
 - **Direct Design System Generation** - Complete design-tokens.json + style-guide.md in one step
 - **Hybrid Extraction Strategy** - Combines computed CSS values (ground truth) with AI visual analysis
 - **Pixel-Perfect Accuracy** - Chrome DevTools extracts exact border-radius, shadows, spacing values
@@ -378,7 +611,7 @@ ERROR: Claude JSON parsing error
 - **Variant-Specific Directions** - Each variant has unique philosophy, keywords, anti-patterns
 - **Maximum Contrast Guarantee** - Variants maximally distant in attribute space
 - **Flexible Input** - Images, text, URLs, or hybrid mode
-- **Graceful Fallback** - Falls back to pure visual inference if URL unavailable
+- **Graceful Fallback** - Falls back to pure visual inference if Chrome DevTools unavailable
 - **Production-Ready** - OKLCH colors, WCAG AA compliance, semantic naming
 - **Agent-Driven** - Autonomous multi-file generation with ui-design-agent
 

.claude/scripts/extract-animations.js

@@ -0,0 +1,243 @@
+/**
+ * Animation & Transition Extraction Script
+ *
+ * Extracts CSS animations, transitions, and transform patterns from a live web page.
+ * This script runs in the browser context via Chrome DevTools Protocol.
+ *
+ * @returns {Object} Structured animation data
+ */
+(() => {
+  const extractionTimestamp = new Date().toISOString();
+  const currentUrl = window.location.href;
+
+  /**
+   * Parse transition shorthand or individual properties
+   */
+  function parseTransition(element, computedStyle) {
+    const transition = computedStyle.transition || computedStyle.webkitTransition;
+
+    if (!transition || transition === 'none' || transition === 'all 0s ease 0s') {
+      return null;
+    }
+
+    // Parse shorthand: "property duration easing delay"
+    const transitions = [];
+    const parts = transition.split(/,\s*/);
+
+    parts.forEach(part => {
+      const match = part.match(/^(\S+)\s+([\d.]+m?s)\s+(\S+)(?:\s+([\d.]+m?s))?/);
+      if (match) {
+        transitions.push({
+          property: match[1],
+          duration: match[2],
+          easing: match[3],
+          delay: match[4] || '0s'
+        });
+      }
+    });
+
+    return transitions.length > 0 ? transitions : null;
+  }
+
+  /**
+   * Extract animation name and properties
+   */
+  function parseAnimation(element, computedStyle) {
+    const animationName = computedStyle.animationName || computedStyle.webkitAnimationName;
+
+    if (!animationName || animationName === 'none') {
+      return null;
+    }
+
+    return {
+      name: animationName,
+      duration: computedStyle.animationDuration || computedStyle.webkitAnimationDuration,
+      easing: computedStyle.animationTimingFunction || computedStyle.webkitAnimationTimingFunction,
+      delay: computedStyle.animationDelay || computedStyle.webkitAnimationDelay || '0s',
+      iterationCount: computedStyle.animationIterationCount || computedStyle.webkitAnimationIterationCount || '1',
+      direction: computedStyle.animationDirection || computedStyle.webkitAnimationDirection || 'normal',
+      fillMode: computedStyle.animationFillMode || computedStyle.webkitAnimationFillMode || 'none'
+    };
+  }
+
+  /**
+   * Extract transform value
+   */
+  function parseTransform(computedStyle) {
+    const transform = computedStyle.transform || computedStyle.webkitTransform;
+
+    if (!transform || transform === 'none') {
+      return null;
+    }
+
+    return transform;
+  }
+
+  /**
+   * Get element selector (simplified for readability)
+   */
+  function getSelector(element) {
+    if (element.id) {
+      return `#${element.id}`;
+    }
+
+    if (element.className && typeof element.className === 'string') {
+      const classes = element.className.trim().split(/\s+/).slice(0, 2).join('.');
+      if (classes) {
+        return `.${classes}`;
+      }
+    }
+
+    return element.tagName.toLowerCase();
+  }
+
+  /**
+   * Extract all stylesheets and find @keyframes rules
+   */
+  function extractKeyframes() {
+    const keyframes = {};
+
+    try {
+      // Iterate through all stylesheets
+      Array.from(document.styleSheets).forEach(sheet => {
+        try {
+          // Skip external stylesheets due to CORS
+          if (sheet.href && !sheet.href.startsWith(window.location.origin)) {
+            return;
+          }
+
+          Array.from(sheet.cssRules || sheet.rules || []).forEach(rule => {
+            // Check for @keyframes rules
+            if (rule.type === CSSRule.KEYFRAMES_RULE || rule.type === CSSRule.WEBKIT_KEYFRAMES_RULE) {
+              const name = rule.name;
+              const frames = {};
+
+              Array.from(rule.cssRules || []).forEach(keyframe => {
+                const key = keyframe.keyText; // e.g., "0%", "50%", "100%"
+                frames[key] = keyframe.style.cssText;
+              });
+
+              keyframes[name] = frames;
+            }
+          });
+        } catch (e) {
+          // Skip stylesheets that can't be accessed (CORS)
+          console.warn('Cannot access stylesheet:', sheet.href, e.message);
+        }
+      });
+    } catch (e) {
+      console.error('Error extracting keyframes:', e);
+    }
+
+    return keyframes;
+  }
+
+  /**
+   * Scan visible elements for animations and transitions
+   */
+  function scanElements() {
+    const elements = document.querySelectorAll('*');
+    const transitionData = [];
+    const animationData = [];
+    const transformData = [];
+
+    const uniqueTransitions = new Set();
+    const uniqueAnimations = new Set();
+    const uniqueEasings = new Set();
+    const uniqueDurations = new Set();
+
+    elements.forEach(element => {
+      // Skip invisible elements
+      const rect = element.getBoundingClientRect();
+      if (rect.width === 0 && rect.height === 0) {
+        return;
+      }
+
+      const computedStyle = window.getComputedStyle(element);
+
+      // Extract transitions
+      const transitions = parseTransition(element, computedStyle);
+      if (transitions) {
+        const selector = getSelector(element);
+        transitions.forEach(t => {
+          const key = `${t.property}-${t.duration}-${t.easing}`;
+          if (!uniqueTransitions.has(key)) {
+            uniqueTransitions.add(key);
+            transitionData.push({
+              selector,
+              ...t
+            });
+            uniqueEasings.add(t.easing);
+            uniqueDurations.add(t.duration);
+          }
+        });
+      }
+
+      // Extract animations
+      const animation = parseAnimation(element, computedStyle);
+      if (animation) {
+        const selector = getSelector(element);
+        const key = `${animation.name}-${animation.duration}`;
+        if (!uniqueAnimations.has(key)) {
+          uniqueAnimations.add(key);
+          animationData.push({
+            selector,
+            ...animation
+          });
+          uniqueEasings.add(animation.easing);
+          uniqueDurations.add(animation.duration);
+        }
+      }
+
+      // Extract transforms (on hover/active, we only get current state)
+      const transform = parseTransform(computedStyle);
+      if (transform) {
+        const selector = getSelector(element);
+        transformData.push({
+          selector,
+          transform
+        });
+      }
+    });
+
+    return {
+      transitions: transitionData,
+      animations: animationData,
+      transforms: transformData,
+      uniqueEasings: Array.from(uniqueEasings),
+      uniqueDurations: Array.from(uniqueDurations)
+    };
+  }
+
+  /**
+   * Main extraction function
+   */
+  function extractAnimations() {
+    const elementData = scanElements();
+    const keyframes = extractKeyframes();
+
+    return {
+      metadata: {
+        timestamp: extractionTimestamp,
+        url: currentUrl,
+        method: 'chrome-devtools',
+        version: '1.0.0'
+      },
+      transitions: elementData.transitions,
+      animations: elementData.animations,
+      transforms: elementData.transforms,
+      keyframes: keyframes,
+      summary: {
+        total_transitions: elementData.transitions.length,
+        total_animations: elementData.animations.length,
+        total_transforms: elementData.transforms.length,
+        total_keyframes: Object.keys(keyframes).length,
+        unique_easings: elementData.uniqueEasings,
+        unique_durations: elementData.uniqueDurations
+      }
+    };
+  }
+
+  // Execute extraction
+  return extractAnimations();
+})();

.claude/scripts/extract-layout-structure.js

@@ -1,10 +1,27 @@
 /**
- * Extract Layout Structure from DOM
+ * Extract Layout Structure from DOM - Enhanced Version
  *
  * Extracts real layout information from DOM to provide accurate
  * structural data for UI replication.
  *
+ * Features:
+ * - Framework detection (Nuxt.js, Next.js, React, Vue, Angular)
+ * - Multi-strategy container detection (strict → relaxed → class-based → framework-specific)
+ * - Intelligent main content detection with common class names support
+ * - Supports modern SPA frameworks
+ * - Detects non-semantic main containers (.main, .content, etc.)
+ * - Progressive exploration: Auto-discovers missing selectors when standard patterns fail
+ * - Suggests new class names to add to script based on actual page structure
+ *
+ * Progressive Exploration:
+ * When fewer than 3 main containers are found, the script automatically:
+ * 1. Analyzes all large visible containers (≥500×300px)
+ * 2. Extracts class name patterns (main/content/wrapper/container/page/etc.)
+ * 3. Suggests new selectors to add to the script
+ * 4. Returns exploration data in result.exploration
+ *
  * Usage: Execute via Chrome DevTools evaluate_script
+ * Version: 2.2.0
  */
 
 (() => {
@@ -62,7 +79,7 @@
   const identifyPattern = (props) => {
     const { display, flexDirection, gridTemplateColumns } = props;
 
-    if (display === 'flex') {
+    if (display === 'flex' || display === 'inline-flex') {
       if (flexDirection === 'column') return 'flex-column';
       if (flexDirection === 'row') return 'flex-row';
       return 'flex';
@@ -77,12 +94,23 @@
       return 'grid';
     }
 
-    if (display === 'inline-flex') return 'inline-flex';
     if (display === 'block') return 'block';
 
     return display;
   };
 
+  /**
+   * Detect frontend framework
+   */
+  const detectFramework = () => {
+    if (document.querySelector('#__nuxt')) return { name: 'Nuxt.js', version: 'unknown' };
+    if (document.querySelector('#__next')) return { name: 'Next.js', version: 'unknown' };
+    if (document.querySelector('[data-reactroot]')) return { name: 'React', version: 'unknown' };
+    if (document.querySelector('[ng-version]')) return { name: 'Angular', version: 'unknown' };
+    if (window.Vue) return { name: 'Vue.js', version: window.Vue.version || 'unknown' };
+    return { name: 'Unknown', version: 'unknown' };
+  };
+
   /**
    * Build layout tree recursively
    */
@@ -139,35 +167,165 @@
   };
 
   /**
-   * Find main layout containers
+   * Find main layout containers with multi-strategy approach
    */
   const findMainContainers = () => {
-    const selectors = [
+    const containers = [];
+    const found = new Set();
+
+    // Strategy 1: Strict selectors (body direct children)
+    const strictSelectors = [
       'body > header',
       'body > nav',
       'body > main',
-      'body > footer',
+      'body > footer'
+    ];
+
+    // Strategy 2: Relaxed selectors (any level)
+    const relaxedSelectors = [
+      'header',
+      'nav',
+      'main',
+      'footer',
       '[role="banner"]',
       '[role="navigation"]',
       '[role="main"]',
       '[role="contentinfo"]'
     ];
 
-    const containers = [];
+    // Strategy 3: Common class-based main content selectors
+    const commonClassSelectors = [
+      '.main',
+      '.content',
+      '.main-content',
+      '.page-content',
+      '.container.main',
+      '.wrapper > .main',
+      'div[class*="main-wrapper"]',
+      'div[class*="content-wrapper"]'
+    ];
 
-    selectors.forEach(selector => {
-      const element = document.querySelector(selector);
-      if (element) {
-        const tree = buildLayoutTree(element, 0, 3);
-        if (tree) {
-          containers.push(tree);
-        }
+    // Strategy 4: Framework-specific selectors
+    const frameworkSelectors = [
+      '#__nuxt header', '#__nuxt .main', '#__nuxt main', '#__nuxt footer',
+      '#__next header', '#__next .main', '#__next main', '#__next footer',
+      '#app header', '#app .main', '#app main', '#app footer',
+      '[data-app] header', '[data-app] .main', '[data-app] main', '[data-app] footer'
+    ];
+
+    // Try all strategies
+    const allSelectors = [...strictSelectors, ...relaxedSelectors, ...commonClassSelectors, ...frameworkSelectors];
+
+    allSelectors.forEach(selector => {
+      try {
+        const elements = document.querySelectorAll(selector);
+        elements.forEach(element => {
+          // Avoid duplicates and invisible elements
+          if (!found.has(element) && element.offsetParent !== null) {
+            found.add(element);
+            const tree = buildLayoutTree(element, 0, 3);
+            if (tree && tree.bounds.width > 0 && tree.bounds.height > 0) {
+              containers.push(tree);
+            }
+          }
+        });
+      } catch (e) {
+        console.warn(`Selector failed: ${selector}`, e);
       }
     });
 
+    // Fallback: If no containers found, use body's direct children
+    if (containers.length === 0) {
+      Array.from(document.body.children).forEach(child => {
+        if (child.offsetParent !== null && !found.has(child)) {
+          const tree = buildLayoutTree(child, 0, 2);
+          if (tree && tree.bounds.width > 100 && tree.bounds.height > 100) {
+            containers.push(tree);
+          }
+        }
+      });
+    }
+
     return containers;
   };
 
+  /**
+   * Progressive exploration: Discover main containers when standard selectors fail
+   * Analyzes large visible containers and suggests class name patterns
+   */
+  const exploreMainContainers = () => {
+    const candidates = [];
+    const minWidth = 500;
+    const minHeight = 300;
+
+    // Find all large visible divs
+    const allDivs = document.querySelectorAll('div');
+    allDivs.forEach(div => {
+      const rect = div.getBoundingClientRect();
+      const style = window.getComputedStyle(div);
+
+      // Filter: large size, visible, not header/footer
+      if (rect.width >= minWidth &&
+          rect.height >= minHeight &&
+          div.offsetParent !== null &&
+          !div.closest('header') &&
+          !div.closest('footer')) {
+
+        const classes = Array.from(div.classList);
+        const area = rect.width * rect.height;
+
+        candidates.push({
+          element: div,
+          classes: classes,
+          area: area,
+          bounds: {
+            width: Math.round(rect.width),
+            height: Math.round(rect.height)
+          },
+          display: style.display,
+          depth: getElementDepth(div)
+        });
+      }
+    });
+
+    // Sort by area (largest first) and take top candidates
+    candidates.sort((a, b) => b.area - a.area);
+
+    // Extract unique class patterns from top candidates
+    const classPatterns = new Set();
+    candidates.slice(0, 20).forEach(c => {
+      c.classes.forEach(cls => {
+        // Identify potential main content class patterns
+        if (cls.match(/main|content|container|wrapper|page|body|layout|app/i)) {
+          classPatterns.add(cls);
+        }
+      });
+    });
+
+    return {
+      candidates: candidates.slice(0, 10).map(c => ({
+        classes: c.classes,
+        bounds: c.bounds,
+        display: c.display,
+        depth: c.depth
+      })),
+      suggestedSelectors: Array.from(classPatterns).map(cls => `.${cls}`)
+    };
+  };
+
+  /**
+   * Get element depth in DOM tree
+   */
+  const getElementDepth = (element) => {
+    let depth = 0;
+    let current = element;
+    while (current.parentElement) {
+      depth++;
+      current = current.parentElement;
+    }
+    return depth;
+  };
+
   /**
    * Analyze layout patterns
    */
@@ -199,21 +357,53 @@
   };
 
   /**
-   * Main extraction function
+   * Main extraction function with progressive exploration
    */
   const extractLayout = () => {
+    const framework = detectFramework();
     const containers = findMainContainers();
     const patterns = analyzePatterns(containers);
 
-    return {
+    // Progressive exploration: if too few containers found, explore and suggest
+    let exploration = null;
+    const minExpectedContainers = 3; // At least header, main, footer
+
+    if (containers.length < minExpectedContainers) {
+      exploration = exploreMainContainers();
+
+      // Add warning message
+      exploration.warning = `Only ${containers.length} containers found. Consider adding these selectors to the script:`;
+      exploration.recommendation = exploration.suggestedSelectors.join(', ');
+    }
+
+    const result = {
       metadata: {
         extractedAt: new Date().toISOString(),
         url: window.location.href,
-        method: 'layout-structure'
+        framework: framework,
+        method: 'layout-structure-enhanced',
+        version: '2.2.0'
+      },
+      statistics: {
+        totalContainers: containers.length,
+        patterns: patterns
       },
-      patterns: patterns,
       structure: containers
     };
+
+    // Add exploration results if triggered
+    if (exploration) {
+      result.exploration = {
+        triggered: true,
+        reason: 'Insufficient containers found with standard selectors',
+        discoveredCandidates: exploration.candidates,
+        suggestedSelectors: exploration.suggestedSelectors,
+        warning: exploration.warning,
+        recommendation: exploration.recommendation
+      };
+    }
+
+    return result;
   };
 
   // Execute and return results

.claude/skills/prompt-enhancer/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: Prompt Enhancer
+description: Systematically enhance unclear and ambiguous user prompts by combining session memory with codebase analysis. AUTO-TRIGGER when user input is vague, lacks technical specificity (e.g., "fix", "improve", "clean up", "update", "refactor"), uses unclear references ("it", "that", "this thing"), or affects multiple modules or critical systems. Essential for transforming vague intent into actionable specifications.
+allowed-tools: Bash, Read, Glob, Grep
+---
+
+# Prompt Enhancer
+
+## Overview
+
+Transforms ambiguous user requests into actionable technical specifications through semantic analysis and session memory integration.
+
+**Core Capability**: Vague intent → Structured specification
+
+## Enhancement Process
+
+### Step 1: Semantic Analysis
+
+Analyze user input to identify:
+- **Intent keywords**: fix, improve, add, refactor, update, migrate
+- **Technical scope**: single file vs multi-module
+- **Domain context**: auth, payment, security, API, UI, database
+- **Implied requirements**: performance, security, testing, documentation
+
+### Step 2: Memory Analysis
+
+Extract from conversation history:
+- **Technical context**: Previous discussions, decisions, implementations
+- **Known patterns**: Identified code patterns, architecture decisions
+- **Current state**: What's been built, what's in progress
+- **Dependencies**: Related modules, integration points
+- **Constraints**: Security requirements, backward compatibility
+
+### Step 3: Context Integration
+
+Combine semantic and memory analysis to determine:
+- **Precise intent**: Specific technical goal
+- **Required actions**: Implementation steps with file references
+- **Critical constraints**: Security, compatibility, testing requirements
+- **Missing information**: What needs clarification
+
+## Output Structure
+
+Every enhanced prompt must follow this format:
+
+```
+INTENT: [Clear technical goal]
+CONTEXT: [Session memory + semantic analysis]
+ACTION: [Numbered implementation steps]
+ATTENTION: [Critical constraints]
+```
+
+**Field Descriptions**:
+
+- **INTENT**: One-sentence technical goal derived from semantic analysis
+- **CONTEXT**: Session memory findings + semantic domain analysis
+- **ACTION**: Numbered steps with specific file/module references
+- **ATTENTION**: Critical constraints, security, compliance, tests
+
+## Semantic Patterns
+
+### Intent Translation
+
+| User Input | Semantic Intent | Focus |
+|------------|----------------|-------|
+| "fix" + vague target | Debug and resolve | Root cause → preserve behavior |
+| "improve" + no metrics | Enhance/optimize | Performance/readability |
+| "add" + feature name | Implement feature | Integration + edge cases |
+| "refactor" + module | Restructure | Maintain behavior |
+| "update" + version | Modernize | Version compatibility |
+
+### Scope Detection
+
+**Single-file scope**:
+- "fix button", "add validation", "update component"
+- Use session memory only
+
+**Multi-module scope** (>3 modules):
+- "add authentication", "refactor payment", "migrate database"
+- Analyze dependencies and integration points
+
+**System-wide scope**:
+- "improve performance", "add logging", "update security"
+- Consider cross-cutting concerns
+
+## Key Principles
+
+1. **Memory First**: Check session memory before assumptions
+2. **Semantic Precision**: Extract exact technical intent from vague language
+3. **Context Reuse**: Build on previous understanding
+4. **Clear Output**: Always structured format
+5. **Avoid Duplication**: Reference context, don't repeat
+
+## Best Practices
+
+- **Semantic analysis**: Identify domain, scope, and intent keywords
+- **Memory integration**: Extract all relevant context from conversation
+- **Structured output**: Always use INTENT/CONTEXT/ACTION/ATTENTION format
+- **Actionable steps**: Specific files, clear execution order
+- **Critical constraints**: Security, compatibility, testing requirements

.claude/workflows/cli-templates/planning-roles/synthesis-role.md

@@ -0,0 +1,393 @@
+# Synthesis Role Template
+
+## Purpose
+Generate comprehensive synthesis-specification.md that consolidates all role perspectives from brainstorming into actionable implementation specification.
+
+## Role Focus
+- **Cross-Role Integration**: Synthesize insights from all participating roles
+- **Decision Transparency**: Document both adopted and rejected alternatives
+- **Process Integration**: Include team capabilities, risks, and collaboration patterns
+- **Visual Documentation**: Key diagrams via Mermaid (architecture, data model, user journey)
+- **Priority Matrix**: Quantified recommendations with multi-dimensional evaluation
+- **Actionable Planning**: Phased implementation roadmap with clear next steps
+
+## Document Structure Template
+
+### synthesis-specification.md
+
+```markdown
+# [Topic] - Integrated Implementation Specification
+
+**Framework Reference**: @topic-framework.md | **Generated**: [timestamp] | **Session**: WFS-[topic-slug]
+**Source Integration**: All brainstorming role perspectives consolidated
+**Document Type**: Requirements & Design Specification (WHAT to build)
+
+---
+
+## Executive Summary
+
+Provide strategic overview covering:
+- **Key Insights**: Major findings from cross-role analysis
+- **Breakthrough Opportunities**: Innovation opportunities identified
+- **Implementation Priorities**: High-level prioritization with rationale
+- **Strategic Direction**: Recommended approach and vision
+
+Include metrics from role synthesis:
+- Roles synthesized: [count]
+- Requirements captured: [FR/NFR/BR counts]
+- Controversial decisions: [count]
+- Risk factors identified: [count]
+
+---
+
+## Key Designs & Decisions
+
+### Core Architecture Diagram
+```mermaid
+graph TD
+    A[Component A] --> B[Component B]
+    B --> C[Component C]
+```
+*Reference: @system-architect/analysis.md#architecture-diagram*
+
+### User Journey Map
+![User Journey](./assets/user-journey.png)
+*Reference: @ux-expert/analysis.md#user-journey*
+
+### Data Model Overview
+```mermaid
+erDiagram
+    USER ||--o{ ORDER : places
+    ORDER ||--|{ LINE-ITEM : contains
+```
+*Reference: @data-architect/analysis.md#data-model*
+
+### Architecture Decision Records (ADRs)
+
+**ADR-01: [Decision Title]**
+- **Context**: Background and problem statement
+- **Decision**: Chosen approach
+- **Rationale**: Why this approach was selected
+- **Consequences**: Expected impacts and tradeoffs
+- **Reference**: @[role]/analysis.md#adr-01
+
+[Repeat for each major architectural decision]
+
+---
+
+## Controversial Points & Alternatives
+
+Document disagreements and alternative approaches considered:
+
+| Point | Adopted Solution | Alternative Solution(s) | Decision Rationale | Dissenting Roles |
+|-------|------------------|-------------------------|--------------------| -----------------|
+| Authentication | JWT Token (@security-expert) | Session-Cookie (@system-architect) | Stateless API support for multi-platform | System Architect noted session performance benefits |
+| UI Framework | React (@ui-designer) | Vue.js (@subject-matter-expert) | Team expertise and ecosystem maturity | Subject Matter Expert preferred Vue for learning curve |
+
+*This section preserves decision context and rejected alternatives for future reference.*
+
+**Analysis Guidelines**:
+- Identify where roles disagreed on approach
+- Document both solutions with equal respect
+- Explain why one was chosen over the other
+- Preserve dissenting perspectives for future consideration
+
+---
+
+## Requirements & Acceptance Criteria
+
+### Functional Requirements
+
+| ID | Description | Rationale Summary | Source | Priority | Acceptance Criteria | Dependencies |
+|----|-------------|-------------------|--------|----------|---------------------|--------------|
+| FR-01 | User authentication | Enable secure multi-platform access | @product-manager/analysis.md | High | User can login via email/password with MFA | None |
+| FR-02 | Data export | User-requested analytics feature | @product-owner/analysis.md | Medium | Export to CSV/JSON formats | FR-01 |
+
+**Guidelines**:
+- Extract from product-manager, product-owner, and other role analyses
+- Include rationale summary for immediate understanding
+- Specify clear, testable acceptance criteria
+- Map dependencies between requirements
+
+### Non-Functional Requirements
+
+| ID | Description | Rationale Summary | Target | Validation Method | Source |
+|----|-------------|-------------------|--------|-------------------|--------|
+| NFR-01 | Response time | UX research shows <200ms critical for engagement | <200ms | Load testing | @ux-expert/analysis.md |
+| NFR-02 | Data encryption | Compliance requirement (GDPR, HIPAA) | AES-256 | Security audit | @security-expert/analysis.md |
+
+**Guidelines**:
+- Extract performance, security, scalability requirements
+- Include specific, measurable targets
+- Reference source role for traceability
+
+### Business Requirements
+
+| ID | Description | Rationale Summary | Value | Success Metric | Source |
+|----|-------------|-------------------|-------|----------------|--------|
+| BR-01 | User retention | Market analysis shows engagement gap | High | 80% 30-day retention | @product-manager/analysis.md |
+| BR-02 | Revenue growth | Business case justification for investment | High | 25% MRR increase | @product-owner/analysis.md |
+
+**Guidelines**:
+- Capture business value and success metrics
+- Link to product-manager and product-owner analyses
+
+---
+
+## Design Specifications
+
+### UI/UX Guidelines
+**Consolidated from**: @ui-designer/analysis.md, @ux-expert/analysis.md
+
+- **Component Specifications**: Reusable UI components and patterns
+- **Interaction Patterns**: User interaction flows and behaviors
+- **Visual Design System**: Colors, typography, spacing guidelines
+- **Accessibility Requirements**: WCAG compliance, screen reader support
+- **User Flow Specifications**: Step-by-step user journeys
+- **Responsive Design**: Mobile, tablet, desktop breakpoints
+
+### Architecture Design
+**Consolidated from**: @system-architect/analysis.md, @data-architect/analysis.md
+
+- **System Architecture**: High-level component architecture and interactions
+- **Data Flow**: Data processing pipelines and transformations
+- **Storage Strategy**: Database selection, schema design, caching
+- **Technology Stack**: Languages, frameworks, infrastructure decisions
+- **Integration Patterns**: Service communication, API design
+- **Scalability Approach**: Horizontal/vertical scaling strategies
+
+### Domain Expertise & Standards
+**Consolidated from**: @subject-matter-expert/analysis.md
+
+- **Industry Standards**: Compliance requirements (HIPAA, GDPR, etc.)
+- **Best Practices**: Domain-specific proven patterns
+- **Regulatory Requirements**: Legal and compliance constraints
+- **Technical Quality**: Code quality, testing, documentation standards
+- **Domain-Specific Patterns**: Industry-proven architectural patterns
+
+---
+
+## Process & Collaboration Concerns
+**Consolidated from**: @scrum-master/analysis.md, @product-owner/analysis.md
+
+### Team Capability Assessment
+
+| Required Skill | Current Level | Gap Analysis | Mitigation Strategy | Reference |
+|----------------|---------------|--------------|---------------------|-----------|
+| Kubernetes | Intermediate | Need advanced knowledge for scaling | Training + external consultant | @scrum-master/analysis.md |
+| React Hooks | Advanced | Team ready | None | @scrum-master/analysis.md |
+| GraphQL | Beginner | Significant gap for API layer | 2-week training + mentor pairing | @scrum-master/analysis.md |
+
+**Guidelines**:
+- Identify all required technical skills
+- Assess team's current capability level
+- Document gap and mitigation plan
+- Estimate timeline impact of skill gaps
+
+### Process Risks
+
+| Risk | Impact | Probability | Mitigation | Owner | Reference |
+|------|--------|-------------|------------|-------|-----------|
+| Cross-team API dependency | High | Medium | Early API contract definition | Tech Lead | @scrum-master/analysis.md |
+| UX-Dev alignment gap | Medium | High | Weekly design sync meetings | Product Manager | @ux-expert/analysis.md |
+
+**Guidelines**:
+- Capture both technical and process risks
+- Include probability and impact assessment
+- Specify concrete mitigation strategies
+- Assign ownership for risk management
+
+### Collaboration Patterns
+
+Document recommended collaboration workflows:
+
+- **Design-Dev Pairing**: UI Designer and Frontend Dev pair programming for complex interactions
+- **Architecture Reviews**: Weekly arch review for system-level decisions
+- **User Testing Cadence**: Bi-weekly UX testing sessions with real users
+- **Code Review Process**: PR review within 24 hours, 2 approvals required
+- **Daily Standups**: 15-minute sync across all roles
+
+*Reference: @scrum-master/analysis.md#collaboration*
+
+### Timeline Constraints
+
+Document known constraints that affect planning:
+
+- **Blocking Dependencies**: Project-X API must complete before Phase 2
+- **Resource Constraints**: Only 2 backend developers available in Q1
+- **External Dependencies**: Third-party OAuth provider integration timeline (6 weeks)
+- **Hard Deadlines**: MVP launch date for investor demo (Q2 end)
+
+*Reference: @scrum-master/analysis.md#constraints*
+
+---
+
+## Implementation Roadmap (High-Level)
+
+### Development Phases
+
+**Phase 1** (0-3 months): Foundation and Core Features
+- Infrastructure setup and basic architecture
+- Core authentication and user management
+- Essential functional requirements (FR-01, FR-02, FR-03)
+- Foundational UI components
+
+**Phase 2** (3-6 months): Advanced Features and Integrations
+- Advanced functional requirements
+- Third-party integrations
+- Analytics and reporting
+- Advanced UI/UX enhancements
+
+**Phase 3** (6+ months): Optimization and Innovation
+- Performance optimization
+- Advanced analytics and ML features
+- Innovation opportunities from brainstorming
+- Technical debt reduction
+
+### Technical Guidelines
+
+**Development Standards**:
+- Code organization and project structure
+- Naming conventions and style guides
+- Version control and branching strategy
+- Development environment setup
+
+**Testing Strategy**:
+- Unit testing (80% coverage minimum)
+- Integration testing approach
+- E2E testing for critical paths
+- Performance testing benchmarks
+
+**Deployment Approach**:
+- CI/CD pipeline configuration
+- Staging and production environments
+- Monitoring and alerting setup
+- Rollback procedures
+
+### Feature Grouping (Epic-Level)
+
+**Epic 1: User Authentication & Authorization**
+- Requirements: FR-01, FR-03, NFR-02
+- Priority: High
+- Dependencies: None
+- Estimated Timeline: 4 weeks
+
+**Epic 2: Data Management & Export**
+- Requirements: FR-02, FR-05, NFR-01
+- Priority: Medium
+- Dependencies: Epic 1
+- Estimated Timeline: 6 weeks
+
+[Continue for all major feature groups]
+
+**Note**: Detailed task breakdown into executable work items is handled by `/workflow:plan` → `IMPL_PLAN.md`
+
+---
+
+## Risk Assessment & Mitigation
+
+### Critical Risks Identified
+
+**Technical Risks**:
+1. **Risk**: Database scalability under projected load
+   - **Impact**: High (system downtime, user dissatisfaction)
+   - **Probability**: Medium
+   - **Mitigation**: Early load testing, database sharding plan, caching strategy
+   - **Owner**: System Architect
+
+2. **Risk**: Third-party API reliability and rate limits
+   - **Impact**: Medium (feature degradation)
+   - **Probability**: High
+   - **Mitigation**: Implement circuit breakers, fallback mechanisms, local caching
+   - **Owner**: Backend Lead
+
+**Process Risks**:
+3. **Risk**: Cross-team coordination delays
+   - **Impact**: High (timeline slippage)
+   - **Probability**: Medium
+   - **Mitigation**: Weekly sync meetings, clear API contracts, buffer time in estimates
+   - **Owner**: Scrum Master
+
+4. **Risk**: Skill gap in new technologies
+   - **Impact**: Medium (quality issues, slower delivery)
+   - **Probability**: High
+   - **Mitigation**: Training program, pair programming, external consultant support
+   - **Owner**: Engineering Manager
+
+### Success Factors
+
+**Key factors for implementation success**:
+- Strong product-engineering collaboration with weekly syncs
+- Clear acceptance criteria and definition of done
+- Regular user testing and feedback integration
+- Proactive risk monitoring and mitigation
+
+**Continuous Monitoring Requirements**:
+- Sprint velocity and burndown tracking
+- Code quality metrics (coverage, complexity, tech debt)
+- Performance metrics (response time, error rate, uptime)
+- User satisfaction metrics (NPS, usage analytics)
+
+**Quality Gates and Validation Checkpoints**:
+- Code review approval before merge
+- Automated test suite passing (unit, integration, E2E)
+- Security scan and vulnerability assessment
+- Performance benchmark validation
+- Stakeholder demo and approval before production
+
+---
+
+*Complete implementation specification consolidating all role perspectives into actionable guidance*
+```
+
+## Analysis Guidelines for Agent
+
+### Cross-Role Synthesis Process
+
+1. **Load All Role Analyses**: Read topic-framework.md and all discovered */analysis.md files
+2. **Extract Key Insights**: Identify main recommendations, concerns, and innovations from each role
+3. **Identify Consensus Areas**: Find common themes across multiple roles
+4. **Document Disagreements**: Capture controversial points where roles differ
+5. **Prioritize Recommendations**: Use multi-dimensional scoring:
+   - Business impact (product-manager, product-owner)
+   - Technical feasibility (system-architect, data-architect)
+   - Implementation effort (scrum-master, developers)
+   - Risk assessment (security-expert, subject-matter-expert)
+6. **Create Comprehensive Roadmap**: Synthesize into phased implementation plan
+
+### Quality Standards
+
+- **Completeness**: Integrate ALL discovered role analyses without gaps
+- **Visual Clarity**: Include key diagrams (architecture, data model, user journey) via Mermaid or images
+- **Decision Transparency**: Document not just decisions, but alternatives and why they were rejected
+- **Insight Generation**: Identify cross-role patterns and deep insights beyond individual analyses
+- **Actionability**: Provide specific, executable recommendations with clear rationale
+- **Balance**: Give equal weight to all role perspectives (process, UX, compliance, functional)
+- **Forward-Looking**: Include long-term strategic and innovation considerations
+- **Traceability**: Every major decision links to source role analysis via @ references
+
+### @ Reference System
+
+Use @ references to link back to source role analyses:
+- `@role/analysis.md` - Reference entire role analysis
+- `@role/analysis.md#section` - Reference specific section
+- `@topic-framework.md#point-3` - Reference framework discussion point
+
+### Dynamic Role Handling
+
+- Not all roles participate in every brainstorming session
+- Synthesize only roles that produced analysis.md files
+- Adapt structure based on available role perspectives
+- If role missing, acknowledge gap if relevant to topic
+
+### Output Validation
+
+Before completing, verify:
+- [ ] All discovered role analyses integrated
+- [ ] Framework discussion points addressed across roles
+- [ ] Controversial points documented with dissenting roles identified
+- [ ] Process concerns (team skills, risks, collaboration) captured
+- [ ] Quantified priority recommendations with evaluation criteria
+- [ ] Actionable implementation plan with phased approach
+- [ ] Comprehensive risk assessment with mitigation strategies
+- [ ] @ references to source analyses throughout document

CLAUDE.md

@@ -6,9 +6,9 @@ This document defines project-specific coding standards and development principl
 ### 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)
+- **MCP Tool Strategy**: @~/.claude/workflows/mcp-tool-strategy.md
 - **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
 
 **Context Requirements**:
 - Identify 3+ existing similar patterns before implementation

GETTING_STARTED.md

@@ -1,7 +1,7 @@
 
 # 🚀 Claude Code Workflow (CCW) - Getting Started Guide
 
-Welcome to Claude Code Workflow (CCW)! This guide will help you get up and running in 5 minutes and experience AI-driven automated software development.
+Welcome to Claude Code Workflow (CCW) v4.5.0! This guide will help you get up and running in 5 minutes and experience AI-driven automated software development with our latest workflow system optimizations.
 
 ---
 
@@ -73,6 +73,7 @@ Understanding these concepts will help you use CCW more effectively:
     > -   `@code-developer`: Responsible for writing and implementing code.
     > -   `@test-fix-agent`: Responsible for running tests and automatically fixing failures.
     > -   `@ui-design-agent`: Responsible for UI design and prototype creation.
+    > -   `@cli-execution-agent`: Responsible for autonomous CLI task handling (v4.5.0+).
 
 -   **Workflow**
     > A series of predefined, collaborative commands used to orchestrate different agents and tools to achieve a complex development goal (e.g., `plan`, `execute`, `test-gen`).

GETTING_STARTED_CN.md

@@ -1,7 +1,7 @@
 
 # 🚀 Claude Code Workflow (CCW) - 快速上手指南
 
-欢迎来到 Claude Code Workflow (CCW)！本指南将帮助您在 5 分钟内快速入门，体验由 AI 驱动的自动化软件开发流程。
+欢迎来到 Claude Code Workflow (CCW) v4.5.0！本指南将帮助您在 5 分钟内快速入门，体验由 AI 驱动的自动化软件开发流程，以及我们最新的工作流系统优化。
 
 ---
 
@@ -73,6 +73,7 @@
     > -   `@code-developer`: 负责编写和实现代码。
     > -   `@test-fix-agent`: 负责运行测试并自动修复失败的用例。
     > -   `@ui-design-agent`: 负责 UI 设计和原型创建。
+    > -   `@cli-execution-agent`: 负责自主 CLI 任务处理（v4.5.0+）。
 
 -   **工作流 (Workflow)**
     > 一系列预定义的、相互协作的命令，用于编排不同的智能体和工具，以完成一个复杂的开发目标（如 `plan`、`execute`、`test-gen`）。

README.md

@@ -2,7 +2,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/version-v4.4.0-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases)
+[![Version](https://img.shields.io/badge/version-v4.5.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 Tools](https://img.shields.io/badge/🔧_MCP_Tools-Experimental-orange.svg)](https://github.com/modelcontextprotocol)
@@ -15,13 +15,14 @@
 
 **Claude Code Workflow (CCW)** transforms AI development from simple prompt chaining into a robust, context-first orchestration system. It solves execution uncertainty and error accumulation through structured planning, deterministic execution, and intelligent multi-model orchestration.
 
-> **🎉 Latest: v4.4.0** - UI Design Workflow V3 with Layout/Style Separation Architecture. See [CHANGELOG.md](CHANGELOG.md) for details.
+> **🎉 Latest: v4.5.0** - Workflow System Optimization. See [CHANGELOG.md](CHANGELOG.md) for details.
 >
-> **What's New in v4.4.0**:
-> - 🏗️ **Layout/Style Separation**: New `layout-extract` command separates structure from visual tokens
-> - 📦 **Pure Assembler**: `generate` command now purely combines pre-extracted layouts + styles
-> - 🎯 **Better Variety**: Layout exploration generates structurally distinct designs
-> - ✅ **Single Responsibility**: Each phase (style, layout, assembly) has clear purpose
+> **What's New in v4.5.0**:
+> - 🤖 **Enhanced Agent Protocols**: Unified execution protocols across Gemini/Qwen/Codex with structured output templates
+> - 🎨 **Streamlined UI Workflows**: Simplified design commands with improved documentation
+> - 📋 **Optimized Templates**: Refined workflow templates for better clarity and efficiency
+> - 🔧 **Improved CLI Commands**: Enhanced command documentation and tool integration
+> - ✨ **CLI Execution Agent**: New autonomous agent for CLI task handling
 
 ---
 
@@ -269,12 +270,14 @@ MCP (Model Context Protocol) tools provide advanced codebase analysis. **Recomme
 |------------|---------|-------------------|
 | **Exa MCP** | External API patterns & best practices | [Install Guide](https://smithery.ai/server/exa) |
 | **Code Index MCP** | Advanced internal code search | [Install Guide](https://github.com/johnhuang316/code-index-mcp) |
+| **Chrome DevTools MCP** | ⚠️ **Required for UI workflows** - URL mode design extraction | [Install Guide](https://github.com/ChromeDevTools/chrome-devtools-mcp) |
 
 #### Benefits When Enabled
 - 📊 **Faster Analysis**: Direct codebase indexing vs manual searching
 - 🌐 **External Context**: Real-world API patterns and examples
 - 🔍 **Advanced Search**: Pattern matching and similarity detection
 - ⚡ **Better Reliability**: Primary tools for certain workflows
+- 🎨 **UI Workflows**: Chrome DevTools enables pixel-perfect design extraction from live URLs
 
 ⚠️ **Note**: Some workflows expect MCP tools to be available. Without them, you may experience:
 - Slower code analysis and search operations
@@ -397,8 +400,8 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
 **Phase 5: Testing & Quality Assurance**
 ```bash
 # Generate independent test-fix workflow (v3.2.2+)
-/workflow:test-gen WFS-auth  # Creates WFS-test-auth session
-/workflow:execute            # Runs test validation
+/workflow:test-gen WFS-auth         # Creates WFS-test-auth session
+/workflow:test-cycle-execute        # Execute test-fix cycle with iterative validation
 
 # OR verify TDD compliance (TDD workflow)
 /workflow:tdd-verify
@@ -491,6 +494,8 @@ 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**.
 
+⚠️ **For URL-based design extraction**: Install [Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp) to enable auto-extraction of computed styles and DOM structure from live URLs. Falls back to visual analysis if unavailable.
+
 #### 📐 Architecture Overview
 
 The UI workflow follows a **separation of concerns** philosophy:

README_CN.md

@@ -2,7 +2,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/version-v4.4.0-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases)
+[![Version](https://img.shields.io/badge/version-v4.5.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,14 @@
 
 **Claude Code Workflow (CCW)** 将 AI 开发从简单提示词链接转变为强大的上下文优先编排系统。通过结构化规划、确定性执行和智能多模型编排，解决执行不确定性和误差累积问题。
 
-> **🎉 最新版本: v4.4.0** - UI 设计工作流 V3 布局/样式分离架构。详见 [CHANGELOG.md](CHANGELOG.md)。
+> **🎉 最新版本: v4.5.0** - 工作流系统优化。详见 [CHANGELOG.md](CHANGELOG.md)。
 >
-> **v4.4.0 版本新特性**:
-> - 🏗️ **布局/样式分离**: 新的 `layout-extract` 命令将结构与视觉令牌分离
-> - 📦 **纯汇编器**: `generate` 命令现在纯粹组合预提取的布局 + 样式
-> - 🎯 **更好的多样性**: 布局探索生成结构上不同的设计
-> - ✅ **单一职责**: 每个阶段（样式、布局、汇编）都有明确的目的
+> **v4.5.0 版本新特性**:
+> - 🤖 **增强的代理协议**: 统一 Gemini/Qwen/Codex 执行协议，提供结构化输出模板
+> - 🎨 **精简的 UI 工作流**: 简化设计命令，改进文档说明
+> - 📋 **优化的模板**: 精炼工作流模板，提升清晰度和效率
+> - 🔧 **改进的 CLI 命令**: 增强命令文档和工具集成
+> - ✨ **CLI 执行智能体**: 新增自主 CLI 任务处理智能体
 
 ---
 
@@ -269,12 +270,14 @@ MCP (模型上下文协议) 工具提供高级代码库分析。**推荐安装**
 |------------|------|---------|
 | **Exa MCP** | 外部 API 模式和最佳实践 | [安装指南](https://smithery.ai/server/exa) |
 | **Code Index MCP** | 高级内部代码搜索 | [安装指南](https://github.com/johnhuang316/code-index-mcp) |
+| **Chrome DevTools MCP** | ⚠️ **UI 工作流必需** - URL 模式设计提取 | [安装指南](https://github.com/ChromeDevTools/chrome-devtools-mcp) |
 
 #### 启用后的好处
 - 📊 **更快分析**: 直接代码库索引 vs 手动搜索
 - 🌐 **外部上下文**: 真实世界的 API 模式和示例
 - 🔍 **高级搜索**: 模式匹配和相似性检测
 - ⚡ **更好的可靠性**: 某些工作流的主要工具
+- 🎨 **UI 工作流**: Chrome DevTools 实现从在线 URL 进行像素级精确设计提取
 
 ⚠️ **注意**: 某些工作流期望 MCP 工具可用。如果没有安装，您可能会遇到：
 - 代码分析和搜索操作速度较慢
@@ -489,7 +492,9 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
 
 ### **UI 设计工作流命令 (`/workflow:ui-design:*`)** *(v4.4.0)*
 
-设计工作流系统提供完整的 UI 设计精炼，具备**布局/样式分离架构**、**纯 Claude 执行**、**智能目标推断**和**零外部依赖**。
+⚠️ **基于 URL 的设计提取**: 安装 [Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp) 以启用从在线 URL 自动提取计算样式和 DOM 结构。如果不可用，将回退到视觉分析。
+
+设计工作流系统提供完整的 UI 设计精炼,具备**布局/样式分离架构**、**纯 Claude 执行**、**智能目标推断**和**零外部依赖**。
 
 #### 📐 架构概述
 

skills.md

@@ -0,0 +1,598 @@
+# Agent Skills
+
+> Create, manage, and share Skills to extend Claude's capabilities in Claude Code.
+
+This guide shows you how to create, use, and manage Agent Skills in Claude Code. Skills are modular capabilities that extend Claude's functionality through organized folders containing instructions, scripts, and resources.
+
+## Prerequisites
+
+* Claude Code version 1.0 or later
+* Basic familiarity with [Claude Code](/en/docs/claude-code/quickstart)
+
+## What are Agent Skills?
+
+Agent Skills package expertise into discoverable capabilities. Each Skill consists of a `SKILL.md` file with instructions that Claude reads when relevant, plus optional supporting files like scripts and templates.
+
+**How Skills are invoked**: Skills are **model-invoked**—Claude autonomously decides when to use them based on your request and the Skill's description. This is different from slash commands, which are **user-invoked** (you explicitly type `/command` to trigger them).
+
+**Benefits**:
+
+* Extend Claude's capabilities for your specific workflows
+* Share expertise across your team via git
+* Reduce repetitive prompting
+* Compose multiple Skills for complex tasks
+
+Learn more in the [Agent Skills overview](/en/docs/agents-and-tools/agent-skills/overview).
+
+<Note>
+  For a deep dive into the architecture and real-world applications of Agent Skills, read our engineering blog: [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills).
+</Note>
+
+## Create a Skill
+
+Skills are stored as directories containing a `SKILL.md` file.
+
+### Personal Skills
+
+Personal Skills are available across all your projects. Store them in `~/.claude/skills/`:
+
+```bash  theme={null}
+mkdir -p ~/.claude/skills/my-skill-name
+```
+
+**Use personal Skills for**:
+
+* Your individual workflows and preferences
+* Experimental Skills you're developing
+* Personal productivity tools
+
+### Project Skills
+
+Project Skills are shared with your team. Store them in `.claude/skills/` within your project:
+
+```bash  theme={null}
+mkdir -p .claude/skills/my-skill-name
+```
+
+**Use project Skills for**:
+
+* Team workflows and conventions
+* Project-specific expertise
+* Shared utilities and scripts
+
+Project Skills are checked into git and automatically available to team members.
+
+### Plugin Skills
+
+Skills can also come from [Claude Code plugins](/en/docs/claude-code/plugins). Plugins may bundle Skills that are automatically available when the plugin is installed. These Skills work the same way as personal and project Skills.
+
+## Write SKILL.md
+
+Create a `SKILL.md` file with YAML frontmatter and Markdown content:
+
+```yaml  theme={null}
+---
+name: Your Skill Name
+description: Brief description of what this Skill does and when to use it
+---
+
+# Your Skill Name
+
+## Instructions
+Provide clear, step-by-step guidance for Claude.
+
+## Examples
+Show concrete examples of using this Skill.
+```
+
+The `description` field is critical for Claude to discover when to use your Skill. It should include both what the Skill does and when Claude should use it.
+
+See the [best practices guide](/en/docs/agents-and-tools/agent-skills/best-practices) for complete authoring guidance.
+
+## Add supporting files
+
+Create additional files alongside SKILL.md:
+
+```
+my-skill/
+├── SKILL.md (required)
+├── reference.md (optional documentation)
+├── examples.md (optional examples)
+├── scripts/
+│   └── helper.py (optional utility)
+└── templates/
+    └── template.txt (optional template)
+```
+
+Reference these files from SKILL.md:
+
+````markdown  theme={null}
+For advanced usage, see [reference.md](reference.md).
+
+Run the helper script:
+```bash
+python scripts/helper.py input.txt
+```
+````
+
+Claude reads these files only when needed, using progressive disclosure to manage context efficiently.
+
+## Restrict tool access with allowed-tools
+
+Use the `allowed-tools` frontmatter field to limit which tools Claude can use when a Skill is active:
+
+```yaml  theme={null}
+---
+name: Safe File Reader
+description: Read files without making changes. Use when you need read-only file access.
+allowed-tools: Read, Grep, Glob
+---
+
+# Safe File Reader
+
+This Skill provides read-only file access.
+
+## Instructions
+1. Use Read to view file contents
+2. Use Grep to search within files
+3. Use Glob to find files by pattern
+```
+
+When this Skill is active, Claude can only use the specified tools (Read, Grep, Glob) without needing to ask for permission. This is useful for:
+
+* Read-only Skills that shouldn't modify files
+* Skills with limited scope (e.g., only data analysis, no file writing)
+* Security-sensitive workflows where you want to restrict capabilities
+
+If `allowed-tools` is not specified, Claude will ask for permission to use tools as normal, following the standard permission model.
+
+<Note>
+  `allowed-tools` is only supported for Skills in Claude Code.
+</Note>
+
+## View available Skills
+
+Skills are automatically discovered by Claude from three sources:
+
+* Personal Skills: `~/.claude/skills/`
+* Project Skills: `.claude/skills/`
+* Plugin Skills: bundled with installed plugins
+
+**To view all available Skills**, ask Claude directly:
+
+```
+What Skills are available?
+```
+
+or
+
+```
+List all available Skills
+```
+
+This will show all Skills from all sources, including plugin Skills.
+
+**To inspect a specific Skill**, you can also check the filesystem:
+
+```bash  theme={null}
+# List personal Skills
+ls ~/.claude/skills/
+
+# List project Skills (if in a project directory)
+ls .claude/skills/
+
+# View a specific Skill's content
+cat ~/.claude/skills/my-skill/SKILL.md
+```
+
+## Test a Skill
+
+After creating a Skill, test it by asking questions that match your description.
+
+**Example**: If your description mentions "PDF files":
+
+```
+Can you help me extract text from this PDF?
+```
+
+Claude autonomously decides to use your Skill if it matches the request—you don't need to explicitly invoke it. The Skill activates automatically based on the context of your question.
+
+## Debug a Skill
+
+If Claude doesn't use your Skill, check these common issues:
+
+### Make description specific
+
+**Too vague**:
+
+```yaml  theme={null}
+description: Helps with documents
+```
+
+**Specific**:
+
+```yaml  theme={null}
+description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
+```
+
+Include both what the Skill does and when to use it in the description.
+
+### Verify file path
+
+**Personal Skills**: `~/.claude/skills/skill-name/SKILL.md`
+**Project Skills**: `.claude/skills/skill-name/SKILL.md`
+
+Check the file exists:
+
+```bash  theme={null}
+# Personal
+ls ~/.claude/skills/my-skill/SKILL.md
+
+# Project
+ls .claude/skills/my-skill/SKILL.md
+```
+
+### Check YAML syntax
+
+Invalid YAML prevents the Skill from loading. Verify the frontmatter:
+
+```bash  theme={null}
+cat SKILL.md | head -n 10
+```
+
+Ensure:
+
+* Opening `---` on line 1
+* Closing `---` before Markdown content
+* Valid YAML syntax (no tabs, correct indentation)
+
+### View errors
+
+Run Claude Code with debug mode to see Skill loading errors:
+
+```bash  theme={null}
+claude --debug
+```
+
+## Share Skills with your team
+
+**Recommended approach**: Distribute Skills through [plugins](/en/docs/claude-code/plugins).
+
+To share Skills via plugin:
+
+1. Create a plugin with Skills in the `skills/` directory
+2. Add the plugin to a marketplace
+3. Team members install the plugin
+
+For complete instructions, see [Add Skills to your plugin](/en/docs/claude-code/plugins#add-skills-to-your-plugin).
+
+You can also share Skills directly through project repositories:
+
+### Step 1: Add Skill to your project
+
+Create a project Skill:
+
+```bash  theme={null}
+mkdir -p .claude/skills/team-skill
+# Create SKILL.md
+```
+
+### Step 2: Commit to git
+
+```bash  theme={null}
+git add .claude/skills/
+git commit -m "Add team Skill for PDF processing"
+git push
+```
+
+### Step 3: Team members get Skills automatically
+
+When team members pull the latest changes, Skills are immediately available:
+
+```bash  theme={null}
+git pull
+claude  # Skills are now available
+```
+
+## Update a Skill
+
+Edit SKILL.md directly:
+
+```bash  theme={null}
+# Personal Skill
+code ~/.claude/skills/my-skill/SKILL.md
+
+# Project Skill
+code .claude/skills/my-skill/SKILL.md
+```
+
+Changes take effect the next time you start Claude Code. If Claude Code is already running, restart it to load the updates.
+
+## Remove a Skill
+
+Delete the Skill directory:
+
+```bash  theme={null}
+# Personal
+rm -rf ~/.claude/skills/my-skill
+
+# Project
+rm -rf .claude/skills/my-skill
+git commit -m "Remove unused Skill"
+```
+
+## Best practices
+
+### Keep Skills focused
+
+One Skill should address one capability:
+
+**Focused**:
+
+* "PDF form filling"
+* "Excel data analysis"
+* "Git commit messages"
+
+**Too broad**:
+
+* "Document processing" (split into separate Skills)
+* "Data tools" (split by data type or operation)
+
+### Write clear descriptions
+
+Help Claude discover when to use Skills by including specific triggers in your description:
+
+**Clear**:
+
+```yaml  theme={null}
+description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or analyzing tabular data in .xlsx format.
+```
+
+**Vague**:
+
+```yaml  theme={null}
+description: For files
+```
+
+### Test with your team
+
+Have teammates use Skills and provide feedback:
+
+* Does the Skill activate when expected?
+* Are the instructions clear?
+* Are there missing examples or edge cases?
+
+### Document Skill versions
+
+You can document Skill versions in your SKILL.md content to track changes over time. Add a version history section:
+
+```markdown  theme={null}
+# My Skill
+
+## Version History
+- v2.0.0 (2025-10-01): Breaking changes to API
+- v1.1.0 (2025-09-15): Added new features
+- v1.0.0 (2025-09-01): Initial release
+```
+
+This helps team members understand what changed between versions.
+
+## Troubleshooting
+
+### Claude doesn't use my Skill
+
+**Symptom**: You ask a relevant question but Claude doesn't use your Skill.
+
+**Check**: Is the description specific enough?
+
+Vague descriptions make discovery difficult. Include both what the Skill does and when to use it, with key terms users would mention.
+
+**Too generic**:
+
+```yaml  theme={null}
+description: Helps with data
+```
+
+**Specific**:
+
+```yaml  theme={null}
+description: Analyze Excel spreadsheets, generate pivot tables, create charts. Use when working with Excel files, spreadsheets, or .xlsx files.
+```
+
+**Check**: Is the YAML valid?
+
+Run validation to check for syntax errors:
+
+```bash  theme={null}
+# View frontmatter
+cat .claude/skills/my-skill/SKILL.md | head -n 15
+
+# Check for common issues
+# - Missing opening or closing ---
+# - Tabs instead of spaces
+# - Unquoted strings with special characters
+```
+
+**Check**: Is the Skill in the correct location?
+
+```bash  theme={null}
+# Personal Skills
+ls ~/.claude/skills/*/SKILL.md
+
+# Project Skills
+ls .claude/skills/*/SKILL.md
+```
+
+### Skill has errors
+
+**Symptom**: The Skill loads but doesn't work correctly.
+
+**Check**: Are dependencies available?
+
+Claude will automatically install required dependencies (or ask for permission to install them) when it needs them.
+
+**Check**: Do scripts have execute permissions?
+
+```bash  theme={null}
+chmod +x .claude/skills/my-skill/scripts/*.py
+```
+
+**Check**: Are file paths correct?
+
+Use forward slashes (Unix style) in all paths:
+
+**Correct**: `scripts/helper.py`
+**Wrong**: `scripts\helper.py` (Windows style)
+
+### Multiple Skills conflict
+
+**Symptom**: Claude uses the wrong Skill or seems confused between similar Skills.
+
+**Be specific in descriptions**: Help Claude choose the right Skill by using distinct trigger terms in your descriptions.
+
+Instead of:
+
+```yaml  theme={null}
+# Skill 1
+description: For data analysis
+
+# Skill 2
+description: For analyzing data
+```
+
+Use:
+
+```yaml  theme={null}
+# Skill 1
+description: Analyze sales data in Excel files and CRM exports. Use for sales reports, pipeline analysis, and revenue tracking.
+
+# Skill 2
+description: Analyze log files and system metrics data. Use for performance monitoring, debugging, and system diagnostics.
+```
+
+## Examples
+
+### Simple Skill (single file)
+
+```
+commit-helper/
+└── SKILL.md
+```
+
+```yaml  theme={null}
+---
+name: Generating Commit Messages
+description: Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes.
+---
+
+# Generating Commit Messages
+
+## Instructions
+
+1. Run `git diff --staged` to see changes
+2. I'll suggest a commit message with:
+   - Summary under 50 characters
+   - Detailed description
+   - Affected components
+
+## Best practices
+
+- Use present tense
+- Explain what and why, not how
+```
+
+### Skill with tool permissions
+
+```
+code-reviewer/
+└── SKILL.md
+```
+
+```yaml  theme={null}
+---
+name: Code Reviewer
+description: Review code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.
+allowed-tools: Read, Grep, Glob
+---
+
+# Code Reviewer
+
+## Review checklist
+
+1. Code organization and structure
+2. Error handling
+3. Performance considerations
+4. Security concerns
+5. Test coverage
+
+## Instructions
+
+1. Read the target files using Read tool
+2. Search for patterns using Grep
+3. Find related files using Glob
+4. Provide detailed feedback on code quality
+```
+
+### Multi-file Skill
+
+```
+pdf-processing/
+├── SKILL.md
+├── FORMS.md
+├── REFERENCE.md
+└── scripts/
+    ├── fill_form.py
+    └── validate.py
+```
+
+**SKILL.md**:
+
+````yaml  theme={null}
+---
+name: PDF Processing
+description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction. Requires pypdf and pdfplumber packages.
+---
+
+# PDF Processing
+
+## Quick start
+
+Extract text:
+```python
+import pdfplumber
+with pdfplumber.open("doc.pdf") as pdf:
+    text = pdf.pages[0].extract_text()
+```
+
+For form filling, see [FORMS.md](FORMS.md).
+For detailed API reference, see [REFERENCE.md](REFERENCE.md).
+
+## Requirements
+
+Packages must be installed in your environment:
+```bash
+pip install pypdf pdfplumber
+```
+````
+
+<Note>
+  List required packages in the description. Packages must be installed in your environment before Claude can use them.
+</Note>
+
+Claude loads additional files only when needed.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Authoring best practices" icon="lightbulb" href="/en/docs/agents-and-tools/agent-skills/best-practices">
+    Write Skills that Claude can use effectively
+  </Card>
+
+  <Card title="Agent Skills overview" icon="book" href="/en/docs/agents-and-tools/agent-skills/overview">
+    Learn how Skills work across Claude products
+  </Card>
+
+  <Card title="Get started with Agent Skills" icon="rocket" href="/en/docs/agents-and-tools/agent-skills/quickstart">
+    Create your first Skill
+  </Card>
+</CardGroup>