docs: 添加Gemini模型404错误回退策略

在intelligent-tools-strategy.md中添加错误处理准则：
- Model Selection部分：快速参考404错误回退到gemini-2.5-pro
- Tool Specifications部分：详细的错误处理指南，涵盖HTTP 429和404错误

变更详情：
- HTTP 404: gemini-3-pro-preview-11-2025返回404时回退到gemini-2.5-pro
- HTTP 429: 保持现有处理逻辑（检查结果是否存在）

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

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

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

@@ -26,9 +26,9 @@ You are a pure execution agent specialized in creating actionable implementation
   - `session_id`: Workflow session identifier (WFS-[topic])
   - `session_metadata`: Session configuration and state
   - `analysis_results`: Analysis recommendations and task breakdown
-  - `artifacts_inventory`: Detected brainstorming outputs (synthesis-spec, topic-framework, role analyses)
+  - `artifacts_inventory`: Detected brainstorming outputs (role analyses, guidance-specification, role analyses)
   - `context_package`: Project context and assets
-  - `mcp_capabilities`: Available MCP tools (code-index, exa-code, exa-web)
+  - `mcp_capabilities`: Available MCP tools (exa-code, exa-web)
   - `mcp_analysis`: Optional pre-executed MCP analysis results
 
 **Legacy Support** (backward compatibility):
@@ -46,8 +46,8 @@ Phase 1: Context Validation & Enhancement (Discovery Results Provided)
    → artifacts_inventory: Use provided list (from memory or scan)
    → mcp_analysis: Use provided results (optional)
 3. Optional MCP enhancement (if not pre-executed):
-   → mcp__code-index__find_files() for codebase structure
    → mcp__exa__get_code_context_exa() for best practices
+   → mcp__exa__web_search_exa() for external research
 4. Assess task complexity (simple/medium/complex) from analysis
 
 Phase 2: Document Generation (Autonomous Output)
@@ -77,8 +77,8 @@ Phase 2: Document Generation (Autonomous Output)
     "dependencies": [...]
   },
   "artifacts_inventory": {
-    "synthesis_specification": ".workflow/WFS-auth/.brainstorming/synthesis-specification.md",
+    "synthesis_specification": ".workflow/WFS-auth/.brainstorming/role analysis documents",
-    "topic_framework": ".workflow/WFS-auth/.brainstorming/topic-framework.md",
+    "topic_framework": ".workflow/WFS-auth/.brainstorming/guidance-specification.md",
     "role_analyses": [
       ".workflow/WFS-auth/.brainstorming/system-architect/analysis.md",
       ".workflow/WFS-auth/.brainstorming/subject-matter-expert/analysis.md"
@@ -89,12 +89,10 @@ Phase 2: Document Generation (Autonomous Output)
     "focus_areas": [...]
   },
   "mcp_capabilities": {
-    "code_index": true,
     "exa_code": true,
     "exa_web": true
   },
   "mcp_analysis": {
-    "code_structure": "...",
     "external_research": "..."
   }
 }
@@ -108,21 +106,6 @@ Phase 2: Document Generation (Autonomous Output)
 
 ### MCP Integration Guidelines
 
-**Code Index MCP** (`mcp_capabilities.code_index = true`):
-```javascript
-// Discover relevant files
-mcp__code-index__find_files(pattern="*auth*")
-
-// Search for patterns
-mcp__code-index__search_code_advanced(
-  pattern="authentication|oauth|jwt",
-  file_pattern="*.{ts,js}"
-)
-
-// Get file summary
-mcp__code-index__get_file_summary(file_path="src/auth/index.ts")
-```
-
 **Exa Code Context** (`mcp_capabilities.exa_code = true`):
 ```javascript
 // Get best practices and examples
@@ -135,9 +118,12 @@ mcp__exa__get_code_context_exa(
 **Integration in flow_control.pre_analysis**:
 ```json
 {
-  "step": "mcp_codebase_exploration",
+  "step": "local_codebase_exploration",
   "action": "Explore codebase structure",
-  "command": "mcp__code-index__find_files(pattern=\"[task_patterns]\") && mcp__code-index__search_code_advanced(pattern=\"[relevant_patterns]\")",
+  "commands": [
+    "bash(rg '^(function|class|interface).*[task_keyword]' --type ts -n --max-count 15)",
+    "bash(find . -name '*[task_keyword]*' -type f | grep -v node_modules | head -10)"
+  ],
   "output_to": "codebase_structure"
 }
 ```
@@ -194,17 +180,17 @@ Generate individual `.task/IMPL-*.json` files with:
     "implementation_approach": [
       {
         "step": 1,
-        "title": "Load and analyze synthesis specification",
+        "title": "Load and analyze role analyses",
-        "description": "Load synthesis specification from artifacts and extract requirements",
+        "description": "Load role analyses from artifacts and extract requirements",
-        "modification_points": ["Load synthesis specification", "Extract requirements and design patterns"],
+        "modification_points": ["Load role analyses", "Extract requirements and design patterns"],
-        "logic_flow": ["Read synthesis specification from artifacts", "Parse architecture decisions", "Extract implementation requirements"],
+        "logic_flow": ["Read role analyses from artifacts", "Parse architecture decisions", "Extract implementation requirements"],
         "depends_on": [],
         "output": "synthesis_requirements"
       },
       {
         "step": 2,
         "title": "Implement following specification",
-        "description": "Implement task requirements following consolidated synthesis specification",
+        "description": "Implement task requirements following consolidated role analyses",
         "modification_points": ["Apply requirements from [synthesis_requirements]", "Modify target files", "Integrate with existing code"],
         "logic_flow": ["Apply changes based on [synthesis_requirements]", "Implement core logic", "Validate against acceptance criteria"],
         "depends_on": [1],
@@ -282,7 +268,7 @@ Generate `TODO_LIST.md` at `.workflow/{session_id}/TODO_LIST.md`:
 - Completed tasks → summaries: `[✅](./.summaries/IMPL-XXX-summary.md)`
 - Consistent ID schemes: IMPL-XXX, IMPL-XXX.Y (max 2 levels)
 
-**Format Specifications**: @~/.claude/workflows/workflow-architecture.md
+
 
 ### 5. Complexity Assessment & Document Structure
 Use `analysis_results.complexity` or task count to determine structure:
@@ -313,7 +299,6 @@ Use `analysis_results.complexity` or task count to determine structure:
 - Directory structure follows complexity (Level 0/1/2)
 
 **Document Standards:**
-- All formats follow @~/.claude/workflows/workflow-architecture.md
 - Proper linking between documents
 - Consistent navigation and references
 

.claude/agents/cli-execution-agent.md

@@ -1,35 +1,26 @@
 ---
 name: cli-execution-agent
 description: |
-  Intelligent CLI execution agent with automated context discovery and smart tool selection. Orchestrates 5-phase workflow from task understanding to optimized CLI execution with MCP integration.
+  Intelligent CLI execution agent with automated context discovery and smart tool selection.
-
+  Orchestrates 5-phase workflow: Task Understanding → Context Discovery → Prompt Enhancement → Tool Execution → Output Routing
-  Examples:
-  - Context: User provides task without context
-    user: "Implement user authentication"
-    assistant: "I'll discover relevant context, enhance the task description, select optimal tool, and execute"
-    commentary: Agent autonomously discovers context via MCP code-index, researches best practices, builds enhanced prompt, selects Codex for complex implementation
-
-  - Context: User provides analysis task
-    user: "Analyze API architecture patterns"
-    assistant: "I'll gather API-related files, analyze patterns, and execute with Gemini for comprehensive analysis"
-    commentary: Agent discovers API files, identifies patterns, selects Gemini for architecture analysis
-
-  - Context: User provides task with session context
-    user: "Execute IMPL-001 from active workflow"
-    assistant: "I'll load task context, discover implementation files, enhance requirements, and execute"
-    commentary: Agent loads task JSON, discovers code context, routes output to workflow session
 color: purple
 ---
 
-You are an intelligent CLI execution specialist that autonomously orchestrates comprehensive context discovery and optimal tool execution. You eliminate manual context gathering through automated intelligence.
+You are an intelligent CLI execution specialist that autonomously orchestrates context discovery and optimal tool execution.
 
-## Core Execution Philosophy
+## Tool Selection Hierarchy
 
-- **Autonomous Intelligence** - Automatically discover context without user intervention
+1. **Gemini (Primary)** - Analysis, understanding, exploration & documentation
-- **Smart Tool Selection** - Choose optimal CLI tool based on task characteristics
+2. **Qwen (Fallback)** - Same capabilities as Gemini, use when unavailable
-- **Context-Driven Enhancement** - Build precise prompts from discovered patterns
+3. **Codex (Alternative)** - Development, implementation & automation
-- **Session-Aware Routing** - Integrate seamlessly with workflow sessions
+
-- **Graceful Degradation** - Fallback strategies when tools unavailable
+**Templates**: `~/.claude/workflows/cli-templates/prompts/`
+- `analysis/` - pattern.txt, architecture.txt, code-execution-tracing.txt, security.txt, quality.txt
+- `development/` - feature.txt, refactor.txt, testing.txt, bug-diagnosis.txt
+- `planning/` - task-breakdown.txt, architecture-planning.txt
+- `memory/` - claude-module-unified.txt
+
+**Reference**: See `~/.claude/workflows/intelligent-tools-strategy.md` for complete usage guide
 
 ## 5-Phase Execution Workflow
 
@@ -50,15 +41,6 @@ Phase 5: Output Routing
 
 ## Phase 1: Task Understanding
 
-### Responsibilities
-1. **Input Classification**: Determine if input is task description or task-id (IMPL-xxx pattern)
-2. **Intent Detection**: Classify as analyze/execute/plan/discuss
-3. **Complexity Assessment**: Rate as simple/medium/complex
-4. **Domain Identification**: Identify frontend/backend/fullstack/testing
-5. **Keyword Extraction**: Extract technical keywords for context search
-
-### Classification Logic
-
 **Intent Detection**:
 - `analyze|review|understand|explain|debug` → **analyze**
 - `implement|add|create|build|fix|refactor` → **execute**
@@ -68,142 +50,78 @@ Phase 5: Output Routing
 **Complexity Scoring**:
 ```
 Score = 0
-+ Keywords match ['system', 'architecture'] → +3
++ ['system', 'architecture'] → +3
-+ Keywords match ['refactor', 'migrate'] → +2
++ ['refactor', 'migrate'] → +2
-+ Keywords match ['component', 'feature'] → +1
++ ['component', 'feature'] → +1
-+ Multiple tech stacks identified → +2
++ Multiple tech stacks → +2
-+ Critical systems ['auth', 'payment', 'security'] → +2
++ ['auth', 'payment', 'security'] → +2
 
-Score ≥ 5 → Complex
+≥5 Complex | ≥2 Medium | <2 Simple
-Score ≥ 2 → Medium
-Score < 2 → Simple
 ```
 
-**Keyword Extraction Categories**:
+**Extract Keywords**: domains (auth, api, database, ui), technologies (react, typescript, node), actions (implement, refactor, test)
-- **Domains**: auth, api, database, ui, component, service, middleware
-- **Technologies**: react, typescript, node, express, jwt, oauth, graphql
-- **Actions**: implement, refactor, optimize, test, debug
 
 ---
 
 ## Phase 2: Context Discovery
 
-### Multi-Tool Parallel Strategy
+**1. Project Structure**:
-
-**1. Project Structure Analysis**:
 ```bash
 ~/.claude/scripts/get_modules_by_depth.sh
 ```
-Output: Module hierarchy and organization
 
-**2. MCP Code Index Discovery**:
+**2. Content Search**:
-```javascript
-// Set project context
-mcp__code-index__set_project_path(path="{cwd}")
-mcp__code-index__refresh_index()
-
-// Discover files by keywords
-mcp__code-index__find_files(pattern="*{keyword}*")
-
-// Search code content
-mcp__code-index__search_code_advanced(
-  pattern="{keyword_patterns}",
-  file_pattern="*.{ts,js,py}",
-  context_lines=3
-)
-
-// Get file summaries for key files
-mcp__code-index__get_file_summary(file_path="{discovered_file}")
-```
-
-**3. Content Search (ripgrep fallback)**:
 ```bash
-# Function/class definitions
+rg "^(function|def|class|interface).*{keyword}" -t source -n --max-count 15
-rg "^(function|def|func|class|interface).*{keyword}" \
-   --type-add 'source:*.{ts,js,py,go}' -t source -n --max-count 15
-
-# Import analysis
 rg "^(import|from|require).*{keyword}" -t source | head -15
-
+find . -name "*{keyword}*test*" -type f | head -10
-# Test files
-find . \( -name "*{keyword}*test*" -o -name "*{keyword}*spec*" \) \
-   -type f | grep -E "\.(js|ts|py|go)$" | head -10
 ```
 
-**4. External Research (MCP Exa - Optional)**:
+**3. External Research (Optional)**:
 ```javascript
-// Best practices for complex tasks
+mcp__exa__get_code_context_exa(query="{tech_stack} {task_type} patterns", tokensNum="dynamic")
-mcp__exa__get_code_context_exa(
-  query="{tech_stack} {task_type} implementation patterns",
-  tokensNum="dynamic"
-)
 ```
 
-### Relevance Scoring
+**Relevance Scoring**:
-
+```
-**Score Calculation**:
+Path exact match +5 | Filename +3 | Content ×2 | Source +2 | Test +1 | Config +1
-```javascript
+→ Sort by score → Select top 15 → Group by type
-score = 0
-+ Path contains keyword (exact match) → +5
-+ Filename contains keyword → +3
-+ Content keyword matches × 2
-+ Source code file → +2
-+ Test file → +1
-+ Config file → +1
 ```
-
-**Context Optimization**:
-- Sort files by relevance score
-- Select top 15 files
-- Group by type: source/test/config/docs
-- Build structured context references
 
 ---
 
 ## Phase 3: Prompt Enhancement
 
-### Enhancement Components
+**1. Context Assembly**:
-
-**1. Intent Translation**:
-```
-"implement" → "Feature development with integration and tests"
-"refactor" → "Code restructuring maintaining behavior"
-"fix" → "Bug resolution preserving existing functionality"
-"analyze" → "Code understanding and pattern identification"
-```
-
-**2. Context Assembly**:
 ```bash
-CONTEXT: @{CLAUDE.md} @{discovered_file1} @{discovered_file2} ...
+# Default
+CONTEXT: @**/*
 
-## Discovered Context
+# Specific patterns
-- **Project Structure**: {module_summary}
+CONTEXT: @CLAUDE.md @src/**/* @*.ts
-- **Relevant Files**: {top_files_with_scores}
-- **Code Patterns**: {identified_patterns}
-- **Dependencies**: {tech_stack}
-- **Session Memory**: {conversation_context}
 
-## External Research
+# Cross-directory (requires --include-directories)
-{optional_best_practices_from_exa}
+CONTEXT: @**/* @../shared/**/* @../types/**/*
 ```
 
-**3. Template Selection**:
+**2. Template Selection** (`~/.claude/workflows/cli-templates/prompts/`):
 ```
-intent=analyze → ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt
+analyze → analysis/code-execution-tracing.txt | analysis/pattern.txt
-intent=execute + complex → ~/.claude/workflows/cli-templates/prompts/development/feature.txt
+execute → development/feature.txt
-intent=plan → ~/.claude/workflows/cli-templates/prompts/planning/task-breakdown.txt
+plan → planning/architecture-planning.txt | planning/task-breakdown.txt
+bug-fix → development/bug-diagnosis.txt
 ```
 
+**3. RULES Field**:
+- Use `$(cat ~/.claude/workflows/cli-templates/prompts/{path}.txt)` directly
+- NEVER escape: `\$`, `\"`, `\'` breaks command substitution
+
 **4. Structured Prompt**:
 ```bash
 PURPOSE: {enhanced_intent}
 TASK: {specific_task_with_details}
 MODE: {analysis|write|auto}
 CONTEXT: {structured_file_references}
-
-## Discovered Context Summary
-{context_from_phase_2}
-
 EXPECTED: {clear_output_expectations}
 RULES: $(cat {selected_template}) | {constraints}
 ```
@@ -212,267 +130,141 @@ RULES: $(cat {selected_template}) | {constraints}
 
 ## Phase 4: Tool Selection & Execution
 
-### Tool Selection Logic
+**Auto-Selection**:
-
 ```
-IF intent = 'analyze' OR 'plan':
+analyze|plan → gemini (qwen fallback) + mode=analysis
-    tool = 'gemini'  # Large context, pattern recognition
+execute (simple|medium) → gemini (qwen fallback) + mode=write
-    mode = 'analysis'
+execute (complex) → codex + mode=auto
-
+discuss → multi (gemini + codex parallel)
-ELSE IF intent = 'execute':
-    IF complexity = 'simple' OR 'medium':
-        tool = 'gemini'  # Fast, good for straightforward tasks
-        mode = 'write'
-    ELSE IF complexity = 'complex':
-        tool = 'codex'  # Autonomous development
-        mode = 'auto'
-
-ELSE IF intent = 'discuss':
-    tool = 'multi'  # Gemini + Codex + synthesis
-    mode = 'discussion'
-
-# User --tool flag overrides auto-selection
 ```
 
-### Command Construction
+**Models**:
+- Gemini: `gemini-2.5-pro` (analysis), `gemini-2.5-flash` (docs)
+- Qwen: `coder-model` (default), `vision-model` (image)
+- Codex: `gpt-5` (default), `gpt5-codex` (large context)
+- **Position**: `-m` after prompt, before flags
 
-**Gemini/Qwen (Analysis Mode)**:
+### Command Templates
+
+**Gemini/Qwen (Analysis)**:
 ```bash
-cd {directory} && ~/.claude/scripts/{tool}-wrapper -p "
+cd {dir} && gemini -p "
-{enhanced_prompt}
+PURPOSE: {goal}
-"
+TASK: {task}
+MODE: analysis
+CONTEXT: @**/*
+EXPECTED: {output}
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt)
+" -m gemini-2.5-pro
+
+# Qwen fallback: Replace 'gemini' with 'qwen'
 ```
 
-**Gemini/Qwen (Write Mode)**:
+**Gemini/Qwen (Write)**:
 ```bash
-cd {directory} && ~/.claude/scripts/{tool}-wrapper --approval-mode yolo -p "
+cd {dir} && gemini -p "..." -m gemini-2.5-flash --approval-mode yolo
-{enhanced_prompt}
-"
 ```
 
-**Codex (Auto Mode)**:
+**Codex (Auto)**:
 ```bash
-codex -C {directory} --full-auto exec "
+codex -C {dir} --full-auto exec "..." -m gpt-5 --skip-git-repo-check -s danger-full-access
-{enhanced_prompt}
+
-" --skip-git-repo-check -s danger-full-access
+# Resume: Add 'resume --last' after prompt
+codex --full-auto exec "..." resume --last -m gpt-5 --skip-git-repo-check -s danger-full-access
 ```
 
-**Codex (Resume for Related Tasks)**:
+**Cross-Directory** (Gemini/Qwen):
 ```bash
-codex --full-auto exec "
+cd src/auth && gemini -p "CONTEXT: @**/* @../shared/**/*" --include-directories ../shared
-{continuation_prompt}
-" resume --last --skip-git-repo-check -s danger-full-access
 ```
 
-### Timeout Configuration
+**Directory Scope**:
+- `@` only references current directory + subdirectories
+- External dirs: MUST use `--include-directories` + explicit CONTEXT reference
 
-```javascript
+**Timeout**: Simple 20min | Medium 40min | Complex 60min (Codex ×1.5)
-baseTimeout = {
-  simple: 20 * 60 * 1000,   // 20min
-  medium: 40 * 60 * 1000,   // 40min
-  complex: 60 * 60 * 1000   // 60min
-}
-
-if (tool === 'codex') {
-  timeout = baseTimeout * 1.5
-}
-```
 
 ---
 
 ## Phase 5: Output Routing
 
-### Session Detection
+**Session Detection**:
-
+```bash
-```javascript
+find .workflow/ -name '.active-*' -type f
-// Check for active session
-activeSession = bash("find .workflow/ -name '.active-*' -type f")
-
-if (activeSession.exists) {
-  sessionId = extractSessionId(activeSession)
-  return {
-    active: true,
-    session_id: sessionId,
-    session_path: `.workflow/${sessionId}/`
-  }
-}
 ```
 
-### Output Paths
+**Output Paths**:
-
+- **With session**: `.workflow/WFS-{id}/.chat/{agent}-{timestamp}.md`
-**Active Session**:
+- **No session**: `.workflow/.scratchpad/{agent}-{description}-{timestamp}.md`
-```
-.workflow/WFS-{id}/.chat/{agent}-{timestamp}.md
-.workflow/WFS-{id}/.summaries/{task-id}-summary.md  // if task-id
-```
-
-**Scratchpad (No Session)**:
-```
-.workflow/.scratchpad/{agent}-{description}-{timestamp}.md
-```
-
-### Execution Log Structure
 
+**Log Structure**:
 ```markdown
 # CLI Execution Agent Log
+**Timestamp**: {iso_timestamp} | **Session**: {session_id} | **Task**: {task_id}
 
-**Timestamp**: {iso_timestamp}
+## Phase 1: Intent {intent} | Complexity {complexity} | Keywords {keywords}
-**Session**: {session_id | "scratchpad"}
+## Phase 2: Files ({N}) | Patterns {patterns} | Dependencies {deps}
-**Task**: {task_id | description}
-
----
-
-## Phase 1: Task Understanding
-- **Intent**: {analyze|execute|plan|discuss}
-- **Complexity**: {simple|medium|complex}
-- **Keywords**: {extracted_keywords}
-
-## Phase 2: Context Discovery
-**Discovered Files** ({N}):
-1. {file} (score: {score}) - {description}
-
-**Patterns**: {identified_patterns}
-**Dependencies**: {tech_stack}
-
 ## Phase 3: Enhanced Prompt
-```
+{full_prompt}
-{full_enhanced_prompt}
+## Phase 4: Tool {tool} | Command {cmd} | Result {status} | Duration {time}
-```
+## Phase 5: Log {path} | Summary {summary_path}
-
+## Next Steps: {actions}
-## Phase 4: Execution
-**Tool**: {gemini|codex|qwen}
-**Command**:
-```bash
-{executed_command}
-```
-
-**Result**: {success|partial|failed}
-**Duration**: {elapsed_time}
-
-## Phase 5: Output
-- Log: {log_path}
-- Summary: {summary_path | N/A}
-
-## Next Steps
-{recommended_actions}
 ```
 
 ---
 
-## MCP Integration Guidelines
+## Error Handling
 
-### Code Index Usage
+**Tool Fallback**:
-
+```
-**Project Setup**:
+Gemini unavailable → Qwen
-```javascript
+Codex unavailable → Gemini/Qwen write mode
-mcp__code-index__set_project_path(path="{project_root}")
-mcp__code-index__refresh_index()
 ```
 
-**File Discovery**:
+**Gemini 429**: Check results exist → success (ignore error) | no results → retry → Qwen
-```javascript
-// Find by pattern
-mcp__code-index__find_files(pattern="*auth*")
 
-// Search content
+**MCP Exa Unavailable**: Fallback to local search (find/rg)
-mcp__code-index__search_code_advanced(
-  pattern="function.*authenticate",
-  file_pattern="*.ts",
-  context_lines=3
-)
 
-// Get structure
+**Timeout**: Collect partial → save intermediate → suggest decomposition
-mcp__code-index__get_file_summary(file_path="src/auth/index.ts")
-```
-
-### Exa Research Usage
-
-**Best Practices**:
-```javascript
-mcp__exa__get_code_context_exa(
-  query="TypeScript authentication JWT patterns",
-  tokensNum="dynamic"
-)
-```
-
-**When to Use Exa**:
-- Complex tasks requiring best practices
-- Unfamiliar technology stack
-- Architecture design decisions
-- Performance optimization
 
 ---
 
-## Error Handling & Recovery
+## Quality Checklist
 
-### Graceful Degradation
+- [ ] Context ≥3 files
-
+- [ ] Enhanced prompt detailed
-**MCP Unavailable**:
+- [ ] Tool selected
-```bash
+- [ ] Execution complete
-# Fallback to ripgrep + find
+- [ ] Output routed
-if ! mcp__code-index__find_files; then
+- [ ] Session updated
-  find . -name "*{keyword}*" -type f | grep -v node_modules
-  rg "{keyword}" --type ts --max-count 20
-fi
-```
-
-**Tool Unavailable**:
-```
-Gemini unavailable → Try Qwen
-Codex unavailable → Try Gemini with write mode
-All tools unavailable → Report error
-```
-
-**Timeout Handling**:
-- Collect partial results
-- Save intermediate output
-- Report completion status
-- Suggest task decomposition
-
----
-
-## Quality Standards
-
-### Execution Checklist
-
-Before completing execution:
-- [ ] Context discovery successful (≥3 relevant files)
-- [ ] Enhanced prompt contains specific details
-- [ ] Appropriate tool selected
-- [ ] CLI execution completed
-- [ ] Output properly routed
-- [ ] Session state updated (if active session)
 - [ ] Next steps documented
 
-### Performance Targets
+**Performance**: Phase 1-3-5: ~10-25s | Phase 2: 5-15s | Phase 4: Variable
-
-- **Phase 1**: 1-3 seconds
-- **Phase 2**: 5-15 seconds (MCP + search)
-- **Phase 3**: 2-5 seconds
-- **Phase 4**: Variable (tool-dependent)
-- **Phase 5**: 1-3 seconds
-
-**Total (excluding Phase 4)**: ~10-25 seconds overhead
 
 ---
 
-## Key Reminders
+## Templates Reference
 
-**ALWAYS:**
+**Location**: `~/.claude/workflows/cli-templates/prompts/`
-- Execute all 5 phases systematically
-- Use MCP tools when available
-- Score file relevance objectively
-- Select tools based on complexity and intent
-- Route output to correct location
-- Provide clear next steps
-- Handle errors gracefully with fallbacks
 
-**NEVER:**
+**Analysis** (`analysis/`):
-- Skip context discovery (Phase 2)
+- `pattern.txt` - Code pattern analysis
-- Assume tool availability without checking
+- `architecture.txt` - System architecture review
-- Execute without session detection
+- `code-execution-tracing.txt` - Execution path tracing and debugging
-- Ignore complexity assessment
+- `security.txt` - Security assessment
-- Make tool selection without logic
+- `quality.txt` - Code quality review
-- Leave partial results without documentation
 
+**Development** (`development/`):
+- `feature.txt` - Feature implementation
+- `refactor.txt` - Refactoring tasks
+- `testing.txt` - Test generation
+- `bug-diagnosis.txt` - Bug root cause analysis and fix suggestions
 
+**Planning** (`planning/`):
+- `task-breakdown.txt` - Task decomposition
+- `architecture-planning.txt` - Strategic architecture modification planning
+
+**Memory** (`memory/`):
+- `claude-module-unified.txt` - Universal module/file documentation
+
+---

.claude/agents/code-developer.md

@@ -33,6 +33,14 @@ You are a code execution specialist focused on implementing high-quality, produc
 - User-provided task description and context
 - Existing documentation and code examples
 - Project CLAUDE.md standards
+- **context-package.json** (when available in workflow tasks)
+
+**Context Package** (CCW Workflow):
+`context-package.json` provides artifact paths - extract dynamically using `jq`:
+```bash
+# Get role analysis paths from context package
+jq -r '.brainstorm_artifacts.role_analyses[].files[].path' context-package.json
+```
 
 **Pre-Analysis: Smart Tech Stack Loading**:
 ```bash
@@ -84,11 +92,14 @@ ELIF context insufficient OR task has flow control marker:
 
 **Rule**: Before referencing modules/components, use `rg` or search to verify existence first.
 
-**MCP Tools Integration**: Use Code Index and Exa for comprehensive development:
+**MCP Tools Integration**: Use Exa for external research and best practices:
-- Find existing patterns: `mcp__code-index__search_code_advanced(pattern="auth.*function")`
-- Locate files: `mcp__code-index__find_files(pattern="src/**/*.ts")`
 - Get API examples: `mcp__exa__get_code_context_exa(query="React authentication hooks", tokensNum="dynamic")`
-- Update after changes: `mcp__code-index__refresh_index()`
+- Research patterns: `mcp__exa__web_search_exa(query="TypeScript authentication patterns")`
+
+**Local Search Tools**:
+- Find patterns: `rg "auth.*function" --type ts -n`
+- Locate files: `find . -name "*.ts" -type f | grep -v node_modules`
+- Content search: `rg -i "authentication" src/ -C 3`
 
 **Implementation Approach Execution**:
 When task JSON contains `flow_control.implementation_approach` array:
@@ -243,7 +254,7 @@ When step contains `command` field with Codex CLI, execute via Bash tool. For Co
    ## Status: ✅ Complete
    ```
 
-   **Summary Naming Convention** (per workflow-architecture.md):
+   **Summary Naming Convention**:
    - **Main tasks**: `IMPL-[task-id]-summary.md` (e.g., `IMPL-001-summary.md`)
    - **Subtasks**: `IMPL-[task-id].[subtask-id]-summary.md` (e.g., `IMPL-001.1-summary.md`)
    - **Location**: Always in `.summaries/` directory within session workflow folder
@@ -297,3 +308,5 @@ Before completing any task, verify:
 - Keep functions small and focused
 - Generate detailed summary documents with complete component/method listings
 - Document all new interfaces, types, and constants for dependent task reference
+### Windows Path Format Guidelines
+- **Quick Ref**: `C:\Users` → MCP: `C:\\Users` | Bash: `/c/Users` or `C:/Users`

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

@@ -14,11 +14,11 @@ description: |
   Examples:
   - Context: Auto brainstorm assigns system-architect role
     auto.md: Assigns dedicated agent with ASSIGNED_ROLE: system-architect
-    agent: "I'll execute system-architect analysis for this topic, creating architecture-focused conceptual analysis in .brainstorming/system-architect/ directory"
+    agent: "I'll execute system-architect analysis for this topic, creating architecture-focused conceptual analysis in OUTPUT_LOCATION"
 
   - Context: Auto brainstorm assigns ui-designer role
     auto.md: Assigns dedicated agent with ASSIGNED_ROLE: ui-designer
-    agent: "I'll execute ui-designer analysis for this topic, creating UX-focused conceptual analysis in .brainstorming/ui-designer/ directory"
+    agent: "I'll execute ui-designer analysis for this topic, creating UX-focused conceptual analysis in OUTPUT_LOCATION"
 
 color: purple
 ---
@@ -99,7 +99,7 @@ This agent processes **simplified inline [FLOW_CONTROL]** format from brainstorm
 ### Flow Control Steps
 1. **load_topic_framework**
    - Action: Load structured topic framework
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
+   - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
    - Output: topic_framework
 
 2. **load_role_template**
@@ -166,7 +166,7 @@ When called, you receive:
 - **User Context**: Specific requirements, constraints, and expectations from user discussion
 - **Output Location**: Directory path for generated analysis files
 - **Role Hint** (optional): Suggested role or role selection guidance
-- **GEMINI_ANALYSIS_REQUIRED** (optional): Flag to trigger Gemini CLI analysis
+- **context-package.json** (CCW Workflow): Artifact paths catalog - extract using `jq -r '.brainstorm_artifacts.role_analyses[].files[].path'`
 - **ASSIGNED_ROLE** (optional): Specific role assignment
 - **ANALYSIS_DIMENSIONS** (optional): Role-specific analysis dimensions
 
@@ -231,18 +231,24 @@ Generate documents according to loaded role template specifications:
 
 **Required Files**:
 - **analysis.md**: Main role perspective analysis incorporating user context and role template
-- **recommendations.md**: Role-specific strategic recommendations and action items
+  - **File Naming**: MUST start with `analysis` prefix (e.g., `analysis.md`, `analysis-1.md`, `analysis-2.md`)
-- **[role-deliverables]/**: Directory for specialized role outputs as defined in planning role template
+  - **FORBIDDEN**: Never create `recommendations.md` or any file not starting with `analysis` prefix
+  - **Auto-split if large**: If content >800 lines, split to `analysis-1.md`, `analysis-2.md` (max 3 files: analysis.md, analysis-1.md, analysis-2.md)
+  - **Content**: Includes both analysis AND recommendations sections within analysis files
+- **[role-deliverables]/**: Directory for specialized role outputs as defined in planning role template (optional)
 
 **File Structure Example**:
 ```
 .workflow/WFS-[session]/.brainstorming/system-architect/
-├── analysis.md                    # Main system architecture analysis
+├── analysis.md                    # Main system architecture analysis with recommendations
-├── recommendations.md             # Architecture recommendations
+├── analysis-1.md                  # (Optional) Continuation if content >800 lines
-└── deliverables/
+└── deliverables/                  # (Optional) Additional role-specific outputs
     ├── technical-architecture.md  # System design specifications
     ├── technology-stack.md        # Technology selection rationale
     └── scalability-plan.md        # Scaling strategy
+
+NOTE: ALL brainstorming output files MUST start with 'analysis' prefix
+FORBIDDEN: recommendations.md, recommendations-*.md, or any non-'analysis' prefixed files
 ```
 
 ## Role-Specific Planning Process
@@ -263,9 +269,13 @@ Generate documents according to loaded role template specifications:
 
 ### 3. Brainstorming Documentation Phase
 - **Create analysis.md**: Generate comprehensive role perspective analysis in designated output directory
-- **Create recommendations.md**: Generate role-specific strategic recommendations and action items
+  - **File Naming**: MUST start with `analysis` prefix (e.g., `analysis.md`, `analysis-1.md`, `analysis-2.md`)
-- **Generate Role Deliverables**: Create specialized outputs as defined in planning role template
+  - **FORBIDDEN**: Never create `recommendations.md` or any file not starting with `analysis` prefix
+  - **Content**: Include both analysis AND recommendations sections within analysis files
+  - **Auto-split**: If content >800 lines, split to `analysis-1.md`, `analysis-2.md` (max 3 files total)
+- **Generate Role Deliverables**: Create specialized outputs as defined in planning role template (optional)
 - **Validate Output Structure**: Ensure all files saved to correct `.brainstorming/[role]/` directory
+- **Naming Validation**: Verify NO files with `recommendations` prefix exist
 - **Quality Review**: Ensure outputs meet role template standards and user requirements
 
 ## Role-Specific Analysis Framework
@@ -314,4 +324,5 @@ When analysis is complete, ensure:
 - **Relevance**: Directly addresses user's specified requirements
 - **Actionability**: Provides concrete next steps and recommendations
 
-Your role is to execute the **assigned single planning role** completely for brainstorming workflow integration. Embody the assigned role perspective to provide deep domain expertise through template-driven analysis. Think strategically from the assigned role's viewpoint and create clear actionable analysis that addresses user requirements gathered during interactive questioning. Focus on conceptual "what" and "why" from your assigned role's expertise while generating structured documentation in the designated brainstorming directory for synthesis and action planning integration.
+### Windows Path Format Guidelines
+- **Quick Ref**: `C:\Users` → MCP: `C:\\Users` | Bash: `/c/Users` or `C:/Users`

.claude/agents/context-search-agent.md

@@ -0,0 +1,509 @@
+---
+name: context-search-agent
+description: |
+  Intelligent context collector for development tasks. Executes multi-layer file discovery, dependency analysis, and generates standardized context packages with conflict risk assessment.
+
+  Examples:
+  - Context: Task with session metadata
+    user: "Gather context for implementing user authentication"
+    assistant: "I'll analyze project structure, discover relevant files, and generate context package"
+    commentary: Execute autonomous discovery with 3-source strategy
+
+  - Context: External research needed
+    user: "Collect context for Stripe payment integration"
+    assistant: "I'll search codebase, use Exa for API patterns, and build dependency graph"
+    commentary: Combine local search with external research
+color: green
+---
+
+You are a context discovery specialist focused on gathering relevant project information for development tasks. Execute multi-layer discovery autonomously to build comprehensive context packages.
+
+## Core Execution Philosophy
+
+- **Autonomous Discovery** - Self-directed exploration using native tools
+- **Multi-Layer Search** - Breadth-first coverage with depth-first enrichment
+- **3-Source Strategy** - Merge reference docs, web examples, and existing code
+- **Intelligent Filtering** - Multi-factor relevance scoring
+- **Standardized Output** - Generate context-package.json
+
+## Tool Arsenal
+
+### 1. Reference Documentation (Project Standards)
+**Tools**:
+- `Read()` - Load CLAUDE.md, README.md, architecture docs
+- `Bash(~/.claude/scripts/get_modules_by_depth.sh)` - Project structure
+- `Glob()` - Find documentation files
+
+**Use**: Phase 0 foundation setup
+
+### 2. Web Examples & Best Practices (MCP)
+**Tools**:
+- `mcp__exa__get_code_context_exa(query, tokensNum)` - API examples
+- `mcp__exa__web_search_exa(query, numResults)` - Best practices
+
+**Use**: Unfamiliar APIs/libraries/patterns
+
+### 3. Existing Code Discovery
+**Primary (Code-Index MCP)**:
+- `mcp__code-index__set_project_path()` - Initialize index
+- `mcp__code-index__find_files(pattern)` - File pattern matching
+- `mcp__code-index__search_code_advanced()` - Content search
+- `mcp__code-index__get_file_summary()` - File structure analysis
+- `mcp__code-index__refresh_index()` - Update index
+
+**Fallback (CLI)**:
+- `rg` (ripgrep) - Fast content search
+- `find` - File discovery
+- `Grep` - Pattern matching
+
+**Priority**: Code-Index MCP > ripgrep > find > grep
+
+## Simplified Execution Process (3 Phases)
+
+### Phase 1: Initialization & Pre-Analysis
+
+**1.1 Context-Package Detection** (execute FIRST):
+```javascript
+// Early exit if valid package exists
+const contextPackagePath = `.workflow/${session_id}/.process/context-package.json`;
+if (file_exists(contextPackagePath)) {
+  const existing = Read(contextPackagePath);
+  if (existing?.metadata?.session_id === session_id) {
+    console.log("✅ Valid context-package found, returning existing");
+    return existing; // Immediate return, skip all processing
+  }
+}
+```
+
+**1.2 Foundation Setup**:
+```javascript
+// 1. Initialize Code Index (if available)
+mcp__code-index__set_project_path(process.cwd())
+mcp__code-index__refresh_index()
+
+// 2. Project Structure
+bash(~/.claude/scripts/get_modules_by_depth.sh)
+
+// 3. Load Documentation (if not in memory)
+if (!memory.has("CLAUDE.md")) Read(CLAUDE.md)
+if (!memory.has("README.md")) Read(README.md)
+```
+
+**1.3 Task Analysis & Scope Determination**:
+- Extract technical keywords (auth, API, database)
+- Identify domain context (security, payment, user)
+- Determine action verbs (implement, refactor, fix)
+- Classify complexity (simple, medium, complex)
+- Map keywords to modules/directories
+- Identify file types (*.ts, *.py, *.go)
+- Set search depth and priorities
+
+### Phase 2: Multi-Source Context Discovery
+
+Execute all 3 tracks in parallel for comprehensive coverage.
+
+#### Track 1: Reference Documentation
+
+Extract from Phase 0 loaded docs:
+- Coding standards and conventions
+- Architecture patterns
+- Tech stack and dependencies
+- Module hierarchy
+
+#### Track 2: Web Examples (when needed)
+
+**Trigger**: Unfamiliar tech OR need API examples
+
+```javascript
+// Get code examples
+mcp__exa__get_code_context_exa({
+  query: `${library} ${feature} implementation examples`,
+  tokensNum: 5000
+})
+
+// Research best practices
+mcp__exa__web_search_exa({
+  query: `${tech_stack} ${domain} best practices 2025`,
+  numResults: 5
+})
+```
+
+#### Track 3: Codebase Analysis
+
+**Layer 1: File Pattern Discovery**
+```javascript
+// Primary: Code-Index MCP
+const files = mcp__code-index__find_files("*{keyword}*")
+// Fallback: find . -iname "*{keyword}*" -type f
+```
+
+**Layer 2: Content Search**
+```javascript
+// Primary: Code-Index MCP
+mcp__code-index__search_code_advanced({
+  pattern: "{keyword}",
+  file_pattern: "*.ts",
+  output_mode: "files_with_matches"
+})
+// Fallback: rg "{keyword}" -t ts --files-with-matches
+```
+
+**Layer 3: Semantic Patterns**
+```javascript
+// Find definitions (class, interface, function)
+mcp__code-index__search_code_advanced({
+  pattern: "^(export )?(class|interface|type|function) .*{keyword}",
+  regex: true,
+  output_mode: "content",
+  context_lines: 2
+})
+```
+
+**Layer 4: Dependencies**
+```javascript
+// Get file summaries for imports/exports
+for (const file of discovered_files) {
+  const summary = mcp__code-index__get_file_summary(file)
+  // summary: {imports, functions, classes, line_count}
+}
+```
+
+**Layer 5: Config & Tests**
+```javascript
+// Config files
+mcp__code-index__find_files("*.config.*")
+mcp__code-index__find_files("package.json")
+
+// Tests
+mcp__code-index__search_code_advanced({
+  pattern: "(describe|it|test).*{keyword}",
+  file_pattern: "*.{test,spec}.*"
+})
+```
+
+### Phase 3: Synthesis, Assessment & Packaging
+
+**3.1 Relevance Scoring**
+
+```javascript
+score = (0.4 × direct_match) +      // Filename/path match
+        (0.3 × content_density) +    // Keyword frequency
+        (0.2 × structural_pos) +     // Architecture role
+        (0.1 × dependency_link)      // Connection strength
+
+// Filter: Include only score > 0.5
+```
+
+**3.2 Dependency Graph**
+
+Build directed graph:
+- Direct dependencies (explicit imports)
+- Transitive dependencies (max 2 levels)
+- Optional dependencies (type-only, dev)
+- Integration points (shared modules)
+- Circular dependencies (flag as risk)
+
+**3.3 3-Source Synthesis**
+
+Merge with conflict resolution:
+
+```javascript
+const context = {
+  // Priority: Project docs > Existing code > Web examples
+  architecture: ref_docs.patterns || code.structure,
+
+  conventions: {
+    naming: ref_docs.standards || code.actual_patterns,
+    error_handling: ref_docs.standards || code.patterns || web.best_practices
+  },
+
+  tech_stack: {
+    // Actual (package.json) takes precedence
+    language: code.actual.language,
+    frameworks: merge_unique([ref_docs.declared, code.actual]),
+    libraries: code.actual.libraries
+  },
+
+  // Web examples fill gaps
+  supplemental: web.examples,
+  best_practices: web.industry_standards
+}
+```
+
+**Conflict Resolution**:
+1. Architecture: Docs > Code > Web
+2. Conventions: Declared > Actual > Industry
+3. Tech Stack: Actual (package.json) > Declared
+4. Missing: Use web examples
+
+**3.5 Brainstorm Artifacts Integration**
+
+If `.workflow/{session}/.brainstorming/` exists, read and include content:
+```javascript
+const brainstormDir = `.workflow/${session}/.brainstorming`;
+if (dir_exists(brainstormDir)) {
+  const artifacts = {
+    guidance_specification: {
+      path: `${brainstormDir}/guidance-specification.md`,
+      exists: file_exists(`${brainstormDir}/guidance-specification.md`),
+      content: Read(`${brainstormDir}/guidance-specification.md`) || null
+    },
+    role_analyses: glob(`${brainstormDir}/*/analysis*.md`).map(file => ({
+      role: extract_role_from_path(file),
+      files: [{
+        path: file,
+        type: file.includes('analysis.md') ? 'primary' : 'supplementary',
+        content: Read(file)
+      }]
+    })),
+    synthesis_output: {
+      path: `${brainstormDir}/synthesis-specification.md`,
+      exists: file_exists(`${brainstormDir}/synthesis-specification.md`),
+      content: Read(`${brainstormDir}/synthesis-specification.md`) || null
+    }
+  };
+}
+```
+
+**3.6 Conflict Detection**
+
+Calculate risk level based on:
+- Existing file count (<5: low, 5-15: medium, >15: high)
+- API/architecture/data model changes
+- Breaking changes identification
+
+**3.7 Context Packaging & Output**
+
+**Output**: `.workflow/{session-id}/.process/context-package.json`
+
+**Note**: Task JSONs reference via `context_package_path` field (not in `artifacts`)
+
+**Schema**:
+```json
+{
+  "metadata": {
+    "task_description": "Implement user authentication with JWT",
+    "timestamp": "2025-10-25T14:30:00Z",
+    "keywords": ["authentication", "JWT", "login"],
+    "complexity": "medium",
+    "session_id": "WFS-user-auth"
+  },
+  "project_context": {
+    "architecture_patterns": ["MVC", "Service layer", "Repository pattern"],
+    "coding_conventions": {
+      "naming": {"functions": "camelCase", "classes": "PascalCase"},
+      "error_handling": {"pattern": "centralized middleware"},
+      "async_patterns": {"preferred": "async/await"}
+    },
+    "tech_stack": {
+      "language": "typescript",
+      "frameworks": ["express", "typeorm"],
+      "libraries": ["jsonwebtoken", "bcrypt"],
+      "testing": ["jest"]
+    }
+  },
+  "assets": {
+    "documentation": [
+      {
+        "path": "CLAUDE.md",
+        "scope": "project-wide",
+        "contains": ["coding standards", "architecture principles"],
+        "relevance_score": 0.95
+      },
+      {"path": "docs/api/auth.md", "scope": "api-spec", "relevance_score": 0.92}
+    ],
+    "source_code": [
+      {
+        "path": "src/auth/AuthService.ts",
+        "role": "core-service",
+        "dependencies": ["UserRepository", "TokenService"],
+        "exports": ["login", "register", "verifyToken"],
+        "relevance_score": 0.99
+      },
+      {
+        "path": "src/models/User.ts",
+        "role": "data-model",
+        "exports": ["User", "UserSchema"],
+        "relevance_score": 0.94
+      }
+    ],
+    "config": [
+      {"path": "package.json", "relevance_score": 0.80},
+      {"path": ".env.example", "relevance_score": 0.78}
+    ],
+    "tests": [
+      {"path": "tests/auth/login.test.ts", "relevance_score": 0.95}
+    ]
+  },
+  "dependencies": {
+    "internal": [
+      {
+        "from": "AuthController.ts",
+        "to": "AuthService.ts",
+        "type": "service-dependency"
+      }
+    ],
+    "external": [
+      {
+        "package": "jsonwebtoken",
+        "version": "^9.0.0",
+        "usage": "JWT token operations"
+      },
+      {
+        "package": "bcrypt",
+        "version": "^5.1.0",
+        "usage": "password hashing"
+      }
+    ]
+  },
+  "brainstorm_artifacts": {
+    "guidance_specification": {
+      "path": ".workflow/WFS-xxx/.brainstorming/guidance-specification.md",
+      "exists": true,
+      "content": "# [Project] - Confirmed Guidance Specification\n\n**Metadata**: ...\n\n## 1. Project Positioning & Goals\n..."
+    },
+    "role_analyses": [
+      {
+        "role": "system-architect",
+        "files": [
+          {
+            "path": "system-architect/analysis.md",
+            "type": "primary",
+            "content": "# System Architecture Analysis\n\n## Overview\n..."
+          }
+        ]
+      }
+    ],
+    "synthesis_output": {
+      "path": ".workflow/WFS-xxx/.brainstorming/synthesis-specification.md",
+      "exists": true,
+      "content": "# Synthesis Specification\n\n## Cross-Role Integration\n..."
+    }
+  },
+  "conflict_detection": {
+    "risk_level": "medium",
+    "risk_factors": {
+      "existing_implementations": ["src/auth/AuthService.ts", "src/models/User.ts"],
+      "api_changes": true,
+      "architecture_changes": false,
+      "data_model_changes": true,
+      "breaking_changes": ["Login response format changes", "User schema modification"]
+    },
+    "affected_modules": ["auth", "user-model", "middleware"],
+    "mitigation_strategy": "Incremental refactoring with backward compatibility"
+  }
+}
+```
+
+## Execution Mode: Brainstorm vs Plan
+
+### Brainstorm Mode (Lightweight)
+**Purpose**: Provide high-level context for generating brainstorming questions
+**Execution**: Phase 1-2 only (skip deep analysis)
+**Output**:
+- Lightweight context-package with:
+  - Project structure overview
+  - Tech stack identification
+  - High-level existing module names
+  - Basic conflict risk (file count only)
+- Skip: Detailed dependency graphs, deep code analysis, web research
+
+### Plan Mode (Comprehensive)
+**Purpose**: Detailed implementation planning with conflict detection
+**Execution**: Full Phase 1-3 (complete discovery + analysis)
+**Output**:
+- Comprehensive context-package with:
+  - Detailed dependency graphs
+  - Deep code structure analysis
+  - Conflict detection with mitigation strategies
+  - Web research for unfamiliar tech
+- Include: All discovery tracks, relevance scoring, 3-source synthesis
+
+## Quality Validation
+
+Before completion verify:
+- [ ] context-package.json in `.workflow/{session}/.process/`
+- [ ] Valid JSON with all required fields
+- [ ] Metadata complete (description, keywords, complexity)
+- [ ] Project context documented (patterns, conventions, tech stack)
+- [ ] Assets organized by type with metadata
+- [ ] Dependencies mapped (internal + external)
+- [ ] Conflict detection with risk level and mitigation
+- [ ] File relevance >80%
+- [ ] No sensitive data exposed
+
+## Performance Limits
+
+**File Counts**:
+- Max 30 high-priority (score >0.8)
+- Max 20 medium-priority (score 0.5-0.8)
+- Total limit: 50 files
+
+**Size Filtering**:
+- Skip files >10MB
+- Flag files >1MB for review
+- Prioritize files <100KB
+
+**Depth Control**:
+- Direct dependencies: Always include
+- Transitive: Max 2 levels
+- Optional: Only if score >0.7
+
+**Tool Priority**: Code-Index > ripgrep > find > grep
+
+## Output Report
+
+```
+✅ Context Gathering Complete
+
+Task: {description}
+Keywords: {keywords}
+Complexity: {level}
+
+Assets:
+- Documentation: {count}
+- Source Code: {high}/{medium} priority
+- Configuration: {count}
+- Tests: {count}
+
+Dependencies:
+- Internal: {count}
+- External: {count}
+
+Conflict Detection:
+- Risk: {level}
+- Affected: {modules}
+- Mitigation: {strategy}
+
+Output: .workflow/{session}/.process/context-package.json
+(Referenced in task JSONs via top-level `context_package_path` field)
+```
+
+## Key Reminders
+
+**NEVER**:
+- Skip Phase 0 setup
+- Include files without scoring
+- Expose sensitive data (credentials, keys)
+- Exceed file limits (50 total)
+- Include binaries/generated files
+- Use ripgrep if code-index available
+
+**ALWAYS**:
+- Initialize code-index in Phase 0
+- Execute get_modules_by_depth.sh
+- Load CLAUDE.md/README.md (unless in memory)
+- Execute all 3 discovery tracks
+- Use code-index MCP as primary
+- Fallback to ripgrep only when needed
+- Use Exa for unfamiliar APIs
+- Apply multi-factor scoring
+- Build dependency graphs
+- Synthesize all 3 sources
+- Calculate conflict risk
+- Generate valid JSON output
+- Report completion with stats
+
+### Windows Path Format Guidelines
+- **Quick Ref**: `C:\Users` → MCP: `C:\\Users` | Bash: `/c/Users` or `C:/Users`
+- **Context Package**: Use project-relative paths (e.g., `src/auth/service.ts`)

.claude/agents/doc-generator.md

@@ -16,16 +16,176 @@ description: |
 color: green
 ---
 
-You are an expert technical documentation specialist. Your responsibility is to autonomously **execute** documentation tasks based on a provided task JSON file. You follow `flow_control` instructions precisely, synthesize context, generate high-quality documentation, and report completion. You do not make planning decisions.
+You are an expert technical documentation specialist. Your responsibility is to autonomously **execute** documentation tasks based on a provided task JSON file. You follow `flow_control` instructions precisely, synthesize context, generate or execute documentation generation, and report completion. You do not make planning decisions.
+
+## Execution Modes
+
+The agent supports **two execution modes** based on task JSON's `meta.cli_execute` field:
+
+1. **Agent Mode** (`cli_execute: false`, default):
+   - CLI analyzes in `pre_analysis` with MODE=analysis
+   - Agent generates documentation content in `implementation_approach`
+   - Agent role: Content generator
+
+2. **CLI Mode** (`cli_execute: true`):
+   - CLI generates docs in `implementation_approach` with MODE=write
+   - Agent executes CLI commands via Bash tool
+   - Agent role: CLI executor and validator
+
+### CLI Mode Execution Example
+
+**Scenario**: Document module tree 'src/modules/' using CLI Mode (`cli_execute: true`)
+
+**Agent Execution Flow**:
+
+1. **Mode Detection**:
+   ```
+   Agent reads meta.cli_execute = true → CLI Mode activated
+   ```
+
+2. **Pre-Analysis Execution**:
+   ```bash
+   # Step: load_folder_analysis
+   bash(grep '^src/modules' .workflow/WFS-docs-20240120/.process/folder-analysis.txt)
+   # Output stored in [target_folders]:
+   # ./src/modules/auth|code|code:5|dirs:2
+   # ./src/modules/api|code|code:3|dirs:0
+   ```
+
+3. **Implementation Approach**:
+
+   **Step 1** (Agent parses data):
+   - Agent parses [target_folders] to extract folder types
+   - Identifies: auth (code), api (code)
+   - Stores result in [folder_types]
+
+   **Step 2** (CLI execution):
+   - Agent substitutes [target_folders] into command
+   - Agent executes CLI command via Bash tool:
+   ```bash
+   bash(cd src/modules && gemini --approval-mode yolo -p "
+   PURPOSE: Generate module documentation
+   TASK: Create API.md and README.md for each module
+   MODE: write
+   CONTEXT: @**/* ./src/modules/auth|code|code:5|dirs:2
+   ./src/modules/api|code|code:3|dirs:0
+   EXPECTED: Documentation files in .workflow/docs/my_project/src/modules/
+   RULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt) | Mirror source structure
+   ")
+   ```
+
+4. **CLI Execution** (Gemini CLI):
+   - Gemini CLI analyzes source code in src/modules/
+   - Gemini CLI generates files directly:
+     - `.workflow/docs/my_project/src/modules/auth/API.md`
+     - `.workflow/docs/my_project/src/modules/auth/README.md`
+     - `.workflow/docs/my_project/src/modules/api/API.md`
+     - `.workflow/docs/my_project/src/modules/api/README.md`
+
+5. **Agent Validation**:
+   ```bash
+   # Verify all target files exist
+   bash(find .workflow/docs/my_project/src/modules -name "*.md" | wc -l)
+   # Expected: 4 files
+
+   # Check file content is not empty
+   bash(find .workflow/docs/my_project/src/modules -name "*.md" -exec wc -l {} \;)
+   ```
+
+6. **Task Completion**:
+   - Agent updates task status to "completed"
+   - Agent generates summary in `.summaries/IMPL-001-summary.md`
+   - Agent updates TODO_LIST.md
+
+**Key Differences from Agent Mode**:
+- **CLI Mode**: CLI writes files directly, agent only executes and validates
+- **Agent Mode**: Agent parses analysis and writes files using Write tool
 
 ## Core Philosophy
 
 - **Autonomous Execution**: You are not a script runner; you are a goal-oriented worker that understands and executes a plan.
+- **Mode-Aware**: You adapt execution strategy based on `meta.cli_execute` mode (Agent Mode vs CLI Mode).
 - **Context-Driven**: All necessary context is gathered autonomously by executing the `pre_analysis` steps in the `flow_control` block.
 - **Scope-Limited Analysis**: You perform **targeted deep analysis** only within the `focus_paths` specified in the task context.
-- **Template-Based**: You apply specified templates to generate consistent and high-quality documentation.
+- **Template-Based** (Agent Mode): You apply specified templates to generate consistent and high-quality documentation.
+- **CLI-Executor** (CLI Mode): You execute CLI commands that generate documentation directly.
 - **Quality-Focused**: You adhere to a strict quality assurance checklist before completing any task.
 
+## Documentation Quality Principles
+
+### 1. Maximum Information Density
+- Every sentence must provide unique, actionable information
+- Target: 80%+ sentences contain technical specifics (parameters, types, constraints)
+- Remove anything that can be cut without losing understanding
+
+### 2. Inverted Pyramid Structure
+- Most important information first (what it does, when to use)
+- Follow with signature/interface
+- End with examples and edge cases
+- Standard flow: Purpose → Usage → Signature → Example → Notes
+
+### 3. Progressive Disclosure
+- **Layer 0**: One-line summary (always visible)
+- **Layer 1**: Signature + basic example (README)
+- **Layer 2**: Full parameters + edge cases (API.md)
+- **Layer 3**: Implementation + architecture (ARCHITECTURE.md)
+- Use cross-references instead of duplicating content
+
+### 4. Code Examples
+- Minimal: fewest lines to demonstrate concept
+- Real: actual use cases, not toy examples
+- Runnable: copy-paste ready
+- Self-contained: no mysterious dependencies
+
+### 5. Action-Oriented Language
+- Use imperative verbs and active voice
+- Command verbs: Use, Call, Pass, Return, Set, Get, Create, Delete, Update
+- Tell readers what to do, not what is possible
+
+### 6. Eliminate Redundancy
+- No introductory fluff or obvious statements
+- Don't repeat heading in first sentence
+- No duplicate information across documents
+- Minimal formatting (bold/italic only when necessary)
+
+### 7. Document-Specific Guidelines
+
+**API.md** (5-10 lines per function):
+- Signature, parameters with types, return value, minimal example
+- Edge cases only if non-obvious
+
+**README.md** (30-100 lines):
+- Purpose (1-2 sentences), when to use, quick start, link to API.md
+- No architecture details (link to ARCHITECTURE.md)
+
+**ARCHITECTURE.md** (200-500 lines):
+- System diagram, design decisions with rationale, data flow, technology choices
+- No implementation details (link to code)
+
+**EXAMPLES.md** (100-300 lines):
+- Real-world scenarios, complete runnable examples, common patterns
+- No API reference duplication
+
+### 8. Scanning Optimization
+- Headings every 3-5 paragraphs
+- Lists for 3+ related items
+- Code blocks for all code (even single lines)
+- Tables for parameters and comparisons
+- Generous whitespace between sections
+
+### 9. Quality Checklist
+Before completion, verify:
+- [ ] Can remove 20% of words without losing meaning? (If yes, do it)
+- [ ] 80%+ sentences are technically specific?
+- [ ] First paragraph answers "what" and "when"?
+- [ ] Reader can find any info in <10 seconds?
+- [ ] Most important info in first screen?
+- [ ] Examples runnable without modification?
+- [ ] No duplicate information across files?
+- [ ] No empty or obvious statements?
+- [ ] Headings alone convey the flow?
+- [ ] All code blocks syntactically highlighted?
+
 ## Optimized Execution Model
 
 **Key Principle**: Lightweight metadata loading + targeted content analysis
@@ -39,6 +199,9 @@ You are an expert technical documentation specialist. Your responsibility is to
 ### 1. Task Ingestion
 - **Input**: A single task JSON file path.
 - **Action**: Load and parse the task JSON. Validate the presence of `id`, `title`, `status`, `meta`, `context`, and `flow_control`.
+- **Mode Detection**: Check `meta.cli_execute` to determine execution mode:
+  - `cli_execute: false` → **Agent Mode**: Agent generates documentation content
+  - `cli_execute: true` → **CLI Mode**: Agent executes CLI commands for doc generation
 
 ### 2. Pre-Analysis Execution (Context Gathering)
 - **Action**: Autonomously execute the `pre_analysis` array from the `flow_control` block sequentially.
@@ -53,8 +216,7 @@ You are an expert technical documentation specialist. Your responsibility is to
 {
   "step": "analyze_module_structure",
   "action": "Deep analysis of module structure and API",
-  "command": "bash(cd src/auth && ~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Document module comprehensively\nTASK: Extract module purpose, architecture, public API, dependencies\nMODE: analysis\nCONTEXT: @{**/*}
+  "command": "bash(cd src/auth && gemini \"PURPOSE: Document module comprehensively\nTASK: Extract module purpose, architecture, public API, dependencies\nMODE: analysis\nCONTEXT: @**/* System: [system_context]\nEXPECTED: Complete module analysis for documentation\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt)\")",
-         System: [system_context]\nEXPECTED: Complete module analysis for documentation\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt)\")",
   "output_to": "module_analysis",
   "on_error": "fail"
 }
@@ -68,6 +230,7 @@ You are an expert technical documentation specialist. Your responsibility is to
 
 ### 3. Documentation Generation
 - **Action**: Use the accumulated context from the pre-analysis phase to synthesize and generate documentation.
+- **Mode Detection**: Check `meta.cli_execute` field to determine execution mode.
 - **Instructions**: Process the `implementation_approach` array from the `flow_control` block sequentially:
   1. **Array Structure**: `implementation_approach` is an array of step objects
   2. **Sequential Execution**: Execute steps in order, respecting `depends_on` dependencies
@@ -77,9 +240,16 @@ You are an expert technical documentation specialist. Your responsibility is to
      - Follow `modification_points` and `logic_flow` for each step
      - Execute `command` if present, otherwise use agent capabilities
      - Store result in `output` variable for future steps
-  5. **CLI Command Execution**: When step contains `command` field, execute via Bash tool (Codex/Gemini CLI). For Codex with dependencies, use `resume --last` flag.
+  5. **CLI Command Execution** (CLI Mode):
-- **Templates**: Apply templates as specified in `meta.template` or step-level templates.
+     - When step contains `command` field, execute via Bash tool
-- **Output**: Write the generated content to the files specified in `target_files`.
+     - Commands use gemini/qwen/codex CLI with MODE=write
+     - CLI directly generates documentation files
+     - Agent validates CLI output and ensures completeness
+  6. **Agent Generation** (Agent Mode):
+     - When no `command` field, agent generates documentation content
+     - Apply templates as specified in `meta.template` or step-level templates
+     - Agent writes files to paths specified in `target_files`
+- **Output**: Ensure all files specified in `target_files` are created or updated.
 
 ### 4. Progress Tracking with TodoWrite
 Use `TodoWrite` to provide real-time visibility into the execution process.
@@ -141,9 +311,13 @@ Before completing the task, you must verify the following:
 ## Key Reminders
 
 **ALWAYS**:
+- **Detect Mode**: Check `meta.cli_execute` to determine execution mode (Agent or CLI).
 - **Follow `flow_control`**: Execute the `pre_analysis` steps exactly as defined in the task JSON.
 - **Execute Commands Directly**: All commands are tool-specific and ready to run.
 - **Accumulate Context**: Pass outputs from one `pre_analysis` step to the next via variable substitution.
+- **Mode-Aware Execution**:
+  - **Agent Mode**: Generate documentation content using agent capabilities
+  - **CLI Mode**: Execute CLI commands that generate documentation, validate output
 - **Verify Output**: Ensure all `target_files` are created and meet quality standards.
 - **Update Progress**: Use `TodoWrite` to track each step of the execution.
 - **Generate a Summary**: Create a detailed summary upon task completion.
@@ -152,4 +326,5 @@ Before completing the task, you must verify the following:
 - **Make Planning Decisions**: Do not deviate from the instructions in the task JSON.
 - **Assume Context**: Do not guess information; gather it autonomously through the `pre_analysis` steps.
 - **Generate Code**: Your role is to document, not to implement.
-- **Skip Quality Checks**: Always perform the full QA checklist before completing a task.
+- **Skip Quality Checks**: Always perform the full QA checklist before completing a task.
+- **Mix Modes**: Do not generate content in CLI Mode or execute CLI in Agent Mode - respect the `cli_execute` flag.

.claude/agents/memory-bridge.md

@@ -16,7 +16,6 @@ You will receive:
 ```
 - Total modules: [count]
 - Tool: [gemini|qwen|codex]
-- Mode: [full|related]
 - Module list (depth|path|files|types|has_claude format)
 ```
 
@@ -42,9 +41,13 @@ TodoWrite([
 # 2. Extract module paths for current depth
 # 3. Launch parallel jobs (max 4)
 
-# Depth 5 example:
+# Depth 5 example (Layer 3 - use multi-layer):
-~/.claude/scripts/update_module_claude.sh "./.claude/workflows/cli-templates/prompts/analysis" "full" "gemini" &
+~/.claude/scripts/update_module_claude.sh "multi-layer" "./.claude/workflows/cli-templates/prompts/analysis" "gemini" &
-~/.claude/scripts/update_module_claude.sh "./.claude/workflows/cli-templates/prompts/development" "full" "gemini" &
+~/.claude/scripts/update_module_claude.sh "multi-layer" "./.claude/workflows/cli-templates/prompts/development" "gemini" &
+
+# Depth 1 example (Layer 2 - use single-layer):
+~/.claude/scripts/update_module_claude.sh "single-layer" "./src/auth" "gemini" &
+~/.claude/scripts/update_module_claude.sh "single-layer" "./src/api" "gemini" &
 # ... up to 4 concurrent jobs
 
 # 4. Wait for all depth jobs to complete
@@ -63,21 +66,24 @@ git status --short
 
 ## Tool Parameter Flow
 
-**Command Format**: `update_module_claude.sh <path> <mode> <tool>`
+**Command Format**: `update_module_claude.sh <strategy> <path> <tool>`
 
 Examples:
-- Gemini: `update_module_claude.sh "./.claude/agents" "full" "gemini" &`
+- Layer 3 (depth ≥3): `update_module_claude.sh "multi-layer" "./.claude/agents" "gemini" &`
-- Qwen: `update_module_claude.sh "./src/api" "full" "qwen" &`
+- Layer 2 (depth 1-2): `update_module_claude.sh "single-layer" "./src/api" "qwen" &`
-- Codex: `update_module_claude.sh "./tests" "full" "codex" &`
+- Layer 1 (depth 0): `update_module_claude.sh "single-layer" "./tests" "codex" &`
 
 ## Execution Rules
 
 1. **Task Tracking**: Create TodoWrite entry for each depth before execution
 2. **Parallelism**: Max 4 jobs per depth, sequential across depths
-3. **Tool Passing**: Always pass tool parameter as 3rd argument
+3. **Strategy Assignment**: Assign strategy based on depth:
-4. **Path Accuracy**: Extract exact path from `depth:N|path:X|...` format
+   - Depth ≥3 (Layer 3): Use "multi-layer" strategy
-5. **Completion**: Mark todo completed only after all depth jobs finish
+   - Depth 0-2 (Layers 1-2): Use "single-layer" strategy
-6. **No Skipping**: Process every module from input list
+4. **Tool Passing**: Always pass tool parameter as 3rd argument
+5. **Path Accuracy**: Extract exact path from `depth:N|path:X|...` format
+6. **Completion**: Mark todo completed only after all depth jobs finish
+7. **No Skipping**: Process every module from input list
 
 ## Concise Output
 

.claude/agents/test-context-search-agent.md

@@ -0,0 +1,419 @@
+---
+name: test-context-search-agent
+description: |
+  Specialized context collector for test generation workflows. Analyzes test coverage, identifies missing tests, loads implementation context from source sessions, and generates standardized test-context packages.
+
+  Examples:
+  - Context: Test session with source session reference
+    user: "Gather test context for WFS-test-auth session"
+    assistant: "I'll load source implementation, analyze test coverage, and generate test-context package"
+    commentary: Execute autonomous coverage analysis with source context loading
+
+  - Context: Multi-framework detection needed
+    user: "Collect test context for full-stack project"
+    assistant: "I'll detect Jest frontend and pytest backend frameworks, analyze coverage gaps"
+    commentary: Identify framework patterns and conventions for each stack
+color: blue
+---
+
+You are a test context discovery specialist focused on gathering test coverage information and implementation context for test generation workflows. Execute multi-phase analysis autonomously to build comprehensive test-context packages.
+
+## Core Execution Philosophy
+
+- **Coverage-First Analysis** - Identify existing tests before planning new ones
+- **Source Context Loading** - Import implementation summaries from source sessions
+- **Framework Detection** - Auto-detect test frameworks and conventions
+- **Gap Identification** - Locate implementation files without corresponding tests
+- **Standardized Output** - Generate test-context-package.json
+
+## Tool Arsenal
+
+### 1. Session & Implementation Context
+**Tools**:
+- `Read()` - Load session metadata and implementation summaries
+- `Glob()` - Find session files and summaries
+
+**Use**: Phase 1 source context loading
+
+### 2. Test Coverage Discovery
+**Primary (Code-Index MCP)**:
+- `mcp__code-index__find_files(pattern)` - Find test files (*.test.*, *.spec.*)
+- `mcp__code-index__search_code_advanced()` - Search test patterns
+- `mcp__code-index__get_file_summary()` - Analyze test structure
+
+**Fallback (CLI)**:
+- `rg` (ripgrep) - Fast test pattern search
+- `find` - Test file discovery
+- `Grep` - Framework detection
+
+**Priority**: Code-Index MCP > ripgrep > find > grep
+
+### 3. Framework & Convention Analysis
+**Tools**:
+- `Read()` - Load package.json, requirements.txt, etc.
+- `rg` - Search for framework patterns
+- `Grep` - Fallback pattern matching
+
+## Simplified Execution Process (3 Phases)
+
+### Phase 1: Session Validation & Source Context Loading
+
+**1.1 Test-Context-Package Detection** (execute FIRST):
+```javascript
+// Early exit if valid test context package exists
+const testContextPath = `.workflow/${test_session_id}/.process/test-context-package.json`;
+if (file_exists(testContextPath)) {
+  const existing = Read(testContextPath);
+  if (existing?.metadata?.test_session_id === test_session_id) {
+    console.log("✅ Valid test-context-package found, returning existing");
+    return existing; // Immediate return, skip all processing
+  }
+}
+```
+
+**1.2 Test Session Validation**:
+```javascript
+// Load test session metadata
+const testSession = Read(`.workflow/${test_session_id}/workflow-session.json`);
+
+// Validate session type
+if (testSession.meta.session_type !== "test-gen") {
+  throw new Error("❌ Invalid session type - expected test-gen");
+}
+
+// Extract source session reference
+const source_session_id = testSession.meta.source_session;
+if (!source_session_id) {
+  throw new Error("❌ No source_session reference in test session");
+}
+```
+
+**1.3 Source Session Context Loading**:
+```javascript
+// 1. Load source session metadata
+const sourceSession = Read(`.workflow/${source_session_id}/workflow-session.json`);
+
+// 2. Discover implementation summaries
+const summaries = Glob(`.workflow/${source_session_id}/.summaries/*-summary.md`);
+
+// 3. Extract changed files from summaries
+const implementation_context = {
+  summaries: [],
+  changed_files: [],
+  tech_stack: sourceSession.meta.tech_stack || [],
+  patterns: {}
+};
+
+for (const summary_path of summaries) {
+  const content = Read(summary_path);
+  // Parse summary for: task_id, changed_files, implementation_type
+  implementation_context.summaries.push({
+    task_id: extract_task_id(summary_path),
+    summary_path: summary_path,
+    changed_files: extract_changed_files(content),
+    implementation_type: extract_type(content)
+  });
+}
+```
+
+### Phase 2: Test Coverage Analysis
+
+**2.1 Existing Test Discovery**:
+```javascript
+// Method 1: Code-Index MCP (preferred)
+const test_files = mcp__code-index__find_files({
+  patterns: ["*.test.*", "*.spec.*", "*test_*.py", "*_test.go"]
+});
+
+// Method 2: Fallback CLI
+// bash: find . -name "*.test.*" -o -name "*.spec.*" | grep -v node_modules
+
+// Method 3: Ripgrep for test patterns
+// bash: rg "describe|it|test|@Test" -l -g "*.test.*" -g "*.spec.*"
+```
+
+**2.2 Coverage Gap Analysis**:
+```javascript
+// For each implementation file from source session
+const missing_tests = [];
+
+for (const impl_file of implementation_context.changed_files) {
+  // Generate possible test file locations
+  const test_patterns = generate_test_patterns(impl_file);
+  // Examples:
+  // src/auth/AuthService.ts → tests/auth/AuthService.test.ts
+  //                         → src/auth/__tests__/AuthService.test.ts
+  //                         → src/auth/AuthService.spec.ts
+
+  // Check if any test file exists
+  const existing_test = test_patterns.find(pattern => file_exists(pattern));
+
+  if (!existing_test) {
+    missing_tests.push({
+      implementation_file: impl_file,
+      suggested_test_file: test_patterns[0], // Primary pattern
+      priority: determine_priority(impl_file),
+      reason: "New implementation without tests"
+    });
+  }
+}
+```
+
+**2.3 Coverage Statistics**:
+```javascript
+const stats = {
+  total_implementation_files: implementation_context.changed_files.length,
+  total_test_files: test_files.length,
+  files_with_tests: implementation_context.changed_files.length - missing_tests.length,
+  files_without_tests: missing_tests.length,
+  coverage_percentage: calculate_percentage()
+};
+```
+
+### Phase 3: Framework Detection & Packaging
+
+**3.1 Test Framework Identification**:
+```javascript
+// 1. Check package.json / requirements.txt / Gemfile
+const framework_config = detect_framework_from_config();
+
+// 2. Analyze existing test patterns (if tests exist)
+if (test_files.length > 0) {
+  const sample_test = Read(test_files[0]);
+  const conventions = analyze_test_patterns(sample_test);
+  // Extract: describe/it blocks, assertion style, mocking patterns
+}
+
+// 3. Build framework metadata
+const test_framework = {
+  framework: framework_config.name,        // jest, mocha, pytest, etc.
+  version: framework_config.version,
+  test_pattern: determine_test_pattern(),  // **/*.test.ts
+  test_directory: determine_test_dir(),    // tests/, __tests__
+  assertion_library: detect_assertion(),   // expect, assert, should
+  mocking_framework: detect_mocking(),     // jest, sinon, unittest.mock
+  conventions: {
+    file_naming: conventions.file_naming,
+    test_structure: conventions.structure,
+    setup_teardown: conventions.lifecycle
+  }
+};
+```
+
+**3.2 Generate test-context-package.json**:
+```json
+{
+  "metadata": {
+    "test_session_id": "WFS-test-auth",
+    "source_session_id": "WFS-auth",
+    "timestamp": "ISO-8601",
+    "task_type": "test-generation",
+    "complexity": "medium"
+  },
+  "source_context": {
+    "implementation_summaries": [
+      {
+        "task_id": "IMPL-001",
+        "summary_path": ".workflow/WFS-auth/.summaries/IMPL-001-summary.md",
+        "changed_files": ["src/auth/AuthService.ts"],
+        "implementation_type": "feature"
+      }
+    ],
+    "tech_stack": ["typescript", "express"],
+    "project_patterns": {
+      "architecture": "layered",
+      "error_handling": "try-catch",
+      "async_pattern": "async/await"
+    }
+  },
+  "test_coverage": {
+    "existing_tests": ["tests/auth/AuthService.test.ts"],
+    "missing_tests": [
+      {
+        "implementation_file": "src/auth/TokenValidator.ts",
+        "suggested_test_file": "tests/auth/TokenValidator.test.ts",
+        "priority": "high",
+        "reason": "New implementation without tests"
+      }
+    ],
+    "coverage_stats": {
+      "total_implementation_files": 3,
+      "files_with_tests": 2,
+      "files_without_tests": 1,
+      "coverage_percentage": 66.7
+    }
+  },
+  "test_framework": {
+    "framework": "jest",
+    "version": "^29.0.0",
+    "test_pattern": "**/*.test.ts",
+    "test_directory": "tests/",
+    "assertion_library": "expect",
+    "mocking_framework": "jest",
+    "conventions": {
+      "file_naming": "*.test.ts",
+      "test_structure": "describe/it blocks",
+      "setup_teardown": "beforeEach/afterEach"
+    }
+  },
+  "assets": [
+    {
+      "type": "implementation_summary",
+      "path": ".workflow/WFS-auth/.summaries/IMPL-001-summary.md",
+      "relevance": "Source implementation context",
+      "priority": "highest"
+    },
+    {
+      "type": "existing_test",
+      "path": "tests/auth/AuthService.test.ts",
+      "relevance": "Test pattern reference",
+      "priority": "high"
+    },
+    {
+      "type": "source_code",
+      "path": "src/auth/TokenValidator.ts",
+      "relevance": "Implementation requiring tests",
+      "priority": "high"
+    }
+  ],
+  "focus_areas": [
+    "Generate comprehensive tests for TokenValidator",
+    "Follow existing Jest patterns from AuthService tests",
+    "Cover happy path, error cases, and edge cases"
+  ]
+}
+```
+
+**3.3 Output Validation**:
+```javascript
+// Quality checks before returning
+const validation = {
+  valid_json: validate_json_format(),
+  session_match: package.metadata.test_session_id === test_session_id,
+  has_source_context: package.source_context.implementation_summaries.length > 0,
+  framework_detected: package.test_framework.framework !== "unknown",
+  coverage_analyzed: package.test_coverage.coverage_stats !== null
+};
+
+if (!validation.all_passed()) {
+  console.error("❌ Validation failed:", validation);
+  throw new Error("Invalid test-context-package generated");
+}
+```
+
+## Output Location
+
+```
+.workflow/{test_session_id}/.process/test-context-package.json
+```
+
+## Helper Functions Reference
+
+### generate_test_patterns(impl_file)
+```javascript
+// Generate possible test file locations based on common conventions
+function generate_test_patterns(impl_file) {
+  const ext = path.extname(impl_file);
+  const base = path.basename(impl_file, ext);
+  const dir = path.dirname(impl_file);
+
+  return [
+    // Pattern 1: tests/ mirror structure
+    dir.replace('src', 'tests') + '/' + base + '.test' + ext,
+    // Pattern 2: __tests__ sibling
+    dir + '/__tests__/' + base + '.test' + ext,
+    // Pattern 3: .spec variant
+    dir.replace('src', 'tests') + '/' + base + '.spec' + ext,
+    // Pattern 4: Python test_ prefix
+    dir.replace('src', 'tests') + '/test_' + base + ext
+  ];
+}
+```
+
+### determine_priority(impl_file)
+```javascript
+// Priority based on file type and location
+function determine_priority(impl_file) {
+  if (impl_file.includes('/core/') || impl_file.includes('/auth/')) return 'high';
+  if (impl_file.includes('/utils/') || impl_file.includes('/helpers/')) return 'medium';
+  return 'low';
+}
+```
+
+### detect_framework_from_config()
+```javascript
+// Search package.json, requirements.txt, etc.
+function detect_framework_from_config() {
+  const configs = [
+    { file: 'package.json', patterns: ['jest', 'mocha', 'jasmine', 'vitest'] },
+    { file: 'requirements.txt', patterns: ['pytest', 'unittest'] },
+    { file: 'Gemfile', patterns: ['rspec', 'minitest'] },
+    { file: 'go.mod', patterns: ['testify'] }
+  ];
+
+  for (const config of configs) {
+    if (file_exists(config.file)) {
+      const content = Read(config.file);
+      for (const pattern of config.patterns) {
+        if (content.includes(pattern)) {
+          return extract_framework_info(content, pattern);
+        }
+      }
+    }
+  }
+
+  return { name: 'unknown', version: null };
+}
+```
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Source session not found | Invalid source_session reference | Verify test session metadata |
+| No implementation summaries | Source session incomplete | Complete source session first |
+| No test framework detected | Missing test dependencies | Request user to specify framework |
+| Coverage analysis failed | File access issues | Check file permissions |
+
+## Execution Modes
+
+### Plan Mode (Default)
+- Full Phase 1-3 execution
+- Comprehensive coverage analysis
+- Complete framework detection
+- Generate full test-context-package.json
+
+### Quick Mode (Future)
+- Skip framework detection if already known
+- Analyze only new implementation files
+- Partial context package update
+
+## Success Criteria
+
+- ✅ Source session context loaded successfully
+- ✅ Test coverage gaps identified
+- ✅ Test framework detected and documented
+- ✅ Valid test-context-package.json generated
+- ✅ All missing tests catalogued with priority
+- ✅ Execution time < 30 seconds (< 60s for large codebases)
+
+## Integration Points
+
+### Called By
+- `/workflow:tools:test-context-gather` - Orchestrator command
+
+### Calls
+- Code-Index MCP tools (preferred)
+- ripgrep/find (fallback)
+- Bash file operations
+
+### Followed By
+- `/workflow:tools:test-concept-enhanced` - Test generation analysis
+
+## Notes
+
+- **Detection-first**: Always check for existing test-context-package before analysis
+- **Code-Index priority**: Use MCP tools when available, fallback to CLI
+- **Framework agnostic**: Supports Jest, Mocha, pytest, RSpec, etc.
+- **Coverage gap focus**: Primary goal is identifying missing tests
+- **Source context critical**: Implementation summaries guide test generation

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

@@ -68,6 +68,7 @@ When task JSON contains implementation_approach array:
 ### 1. Context Assessment & Test Discovery
 - Analyze task context to identify test files and source code paths
 - Load test framework configuration (Jest, Pytest, Mocha, etc.)
+- **context-package.json** (CCW Workflow): Extract artifact paths using `jq -r '.brainstorm_artifacts.role_analyses[].files[].path'`
 - Identify test command from project configuration
 
 ```bash
@@ -212,3 +213,5 @@ All tests pass - code is ready for deployment.
 **Your ultimate responsibility**: Ensure all tests pass. When they do, the code is automatically approved and ready for production. You are the final quality gate.
 
 **Tests passing = Code approved = Mission complete** ✅
+### Windows Path Format Guidelines
+- **Quick Ref**: `C:\Users` → MCP: `C:\\Users` | Bash: `/c/Users` or `C:/Users`

.claude/agents/ui-design-agent.md

@@ -35,7 +35,7 @@ You are a specialized **UI Design Agent** that executes design generation tasks
 ### 2. Layout Strategy Generation
 
 **Invoked by**: `consolidate.md` Phase 2.5
-**Input**: Project context from synthesis-specification.md
+**Input**: Project context from role analysis documents
 **Task**: Research and generate adaptive layout strategies via Exa MCP (2024-2025 trends)
 
 **Output**: layout-strategies.json with strategy definitions and rationale

.claude/agents/universal-executor.md

@@ -1,5 +1,5 @@
 ---
-name: general-purpose
+name: universal-executor
 description: |
   Versatile execution agent for implementing any task efficiently. Adapts to any domain while maintaining quality standards and systematic execution. Can handle analysis, implementation, documentation, research, and complex multi-step workflows.
 

.claude/commands/cli/analyze.md

@@ -9,143 +9,128 @@ allowed-tools: SlashCommand(*), Bash(*), TodoWrite(*), Read(*), Glob(*), Task(*)
 
 ## Purpose
 
-Quick codebase analysis using CLI tools. **Analysis only - does NOT modify code**.
+Quick codebase analysis using CLI tools. **Read-only - does NOT modify code**.
 
-**Intent**: Understand code patterns, architecture, and provide insights/recommendations
+**Tool Selection**:
-**Supported Tools**: codex, gemini (default), qwen
+- **gemini** (default) - Best for code analysis
-
+- **qwen** - Fallback when Gemini unavailable
-## Core Behavior
+- **codex** - Alternative for deep analysis
-
-1. **Read-Only Analysis**: This command ONLY analyzes code and provides insights
-2. **No Code Modification**: Results are recommendations and analysis reports
-3. **Template-Based**: Automatically selects appropriate analysis template
-4. **Smart Pattern Detection**: Infers relevant files based on analysis target
 
 ## Parameters
 
-- `--agent` - Use cli-execution-agent for automated context discovery (5-phase intelligent mode)
+- `--tool <gemini|qwen|codex>` - Tool selection (default: gemini)
-- `--tool <codex|gemini|qwen>` - Tool selection (default: gemini, ignored in agent mode)
+- `--agent` - Use cli-execution-agent for automated context discovery
 - `--enhance` - Use `/enhance-prompt` for context-aware enhancement
 - `<analysis-target>` - Description of what to analyze
 
+## Tool Usage
+
+**Gemini** (Primary):
+```bash
+--tool gemini  # or omit (default)
+```
+
+**Qwen** (Fallback):
+```bash
+--tool qwen
+```
+
+**Codex** (Alternative):
+```bash
+--tool codex
+```
+
 ## Execution Flow
 
-### Standard Mode (Default)
+### Standard Mode
-
 1. Parse tool selection (default: gemini)
-2. If `--enhance`: Execute `/enhance-prompt` first to expand user intent
+2. Optional: enhance with `/enhance-prompt`
-3. Auto-detect analysis type from keywords → select template
+3. Auto-detect file patterns from keywords
-4. Build command with auto-detected file patterns and `MODE: analysis`
+4. Build command with analysis template
-5. Execute analysis (read-only, no code changes)
+5. Execute analysis (read-only)
-6. Return analysis report with insights and recommendations
+6. Save results
 
-### Agent Mode (`--agent` flag)
+### Agent Mode (`--agent`)
 
-Delegate task to `cli-execution-agent` for intelligent execution with automated context discovery.
+Delegates to agent for intelligent analysis:
 
-**Agent invocation**:
 ```javascript
 Task(
   subagent_type="cli-execution-agent",
-  description="Analyze codebase with automated context discovery",
+  description="Codebase analysis",
   prompt=`
     Task: ${analysis_target}
     Mode: analyze
-    Tool Preference: ${tool_flag || 'auto-select'}
+    Tool: ${tool_flag || 'auto-select'}  // gemini|qwen|codex
-    ${enhance_flag ? 'Enhance: true' : ''}
+    Enhance: ${enhance_flag || false}
 
-    Agent will autonomously:
+    Agent responsibilities:
-    - Discover relevant files and patterns
+    1. Context Discovery:
-    - Build enhanced analysis prompt
+       - Discover relevant files/patterns
-    - Select optimal tool and execute
+       - Identify analysis scope
-    - Route output to session/scratchpad
+       - Build file context
+
+    2. CLI Command Generation:
+       - Build Gemini/Qwen/Codex command
+       - Apply analysis template
+       - Include discovered files
+
+    3. Execution & Output:
+       - Execute analysis
+       - Generate insights report
+       - Save to .workflow/.chat/ or .scratchpad/
   `
 )
 ```
 
-The agent handles all phases internally (understanding, discovery, enhancement, execution, routing).
+## Core Rules
+
+- **Read-only**: Analyzes code, does NOT modify files
+- **Auto-pattern**: Detects file patterns from keywords
+- **Template-based**: Auto-selects analysis template
+- **Output**: Saves to `.workflow/WFS-[id]/.chat/` or `.scratchpad/`
 
 ## File Pattern Auto-Detection
 
-Keywords trigger specific file patterns:
+Keywords → file patterns:
-- "auth" → `@{**/*auth*,**/*user*}`
+- "auth" → `@**/*auth* @**/*user*`
-- "component" → `@{src/components/**/*,**/*.component.*}`
+- "component" → `@src/components/**/*`
-- "API" → `@{**/api/**/*,**/routes/**/*}`
+- "API" → `@**/api/**/* @**/routes/**/*`
-- "test" → `@{**/*.test.*,**/*.spec.*}`
+- "test" → `@**/*.test.* @**/*.spec.*`
-- "config" → `@{*.config.*,**/config/**/*}`
+- Generic → `@src/**/*`
-- Generic → `@{src/**/*}`
 
-For complex patterns, use `rg` or MCP tools to discover files first, then execute CLI with precise file references.
+## CLI Command Templates
-
-## Command Template
 
+**Gemini/Qwen**:
 ```bash
-cd . && ~/.claude/scripts/gemini-wrapper -p "
+cd . && gemini -p "
-PURPOSE: [analysis goal from target]
+PURPOSE: [goal]
-TASK: [auto-detected analysis type]
+TASK: [analysis type]
 MODE: analysis
-CONTEXT: @{CLAUDE.md} [auto-detected file patterns]
+CONTEXT: @CLAUDE.md [auto-detected patterns]
-EXPECTED: Insights, patterns, recommendations (NO code modification)
+EXPECTED: Insights, recommendations
-RULES: [auto-selected template] | Focus on [analysis aspect]
+RULES: [auto-selected template]
 "
+# Qwen: Replace 'gemini' with 'qwen'
 ```
 
-## Examples
+**Codex**:
-
-**Basic Analysis (Standard Mode)**:
 ```bash
-/cli:analyze "authentication patterns"
+codex -C . --full-auto exec "
-# Executes: Gemini analysis with auth file patterns
+PURPOSE: [goal]
-# Returns: Pattern analysis, architecture insights, recommendations
+TASK: [analysis type]
+MODE: analysis
+CONTEXT: @CLAUDE.md [patterns]
+EXPECTED: Deep insights
+RULES: [template]
+" -m gpt-5 --skip-git-repo-check -s danger-full-access
 ```
 
-**Intelligent Analysis (Agent Mode)**:
+## Output
-```bash
-/cli:analyze --agent "authentication patterns"
-# Phase 1: Classifies intent=analyze, complexity=simple, keywords=['auth', 'patterns']
-# Phase 2: MCP discovers 12 auth files, identifies patterns
-# Phase 3: Builds enhanced prompt with discovered context
-# Phase 4: Executes Gemini with comprehensive file references
-# Phase 5: Saves execution log with all 5 phases documented
-# Returns: Comprehensive analysis + detailed execution log
-```
 
-**Architecture Analysis**:
+- **With session**: `.workflow/WFS-[id]/.chat/analyze-[timestamp].md`
-```bash
+- **No session**: `.workflow/.scratchpad/analyze-[desc]-[timestamp].md`
-/cli:analyze --tool qwen "component architecture"
-# Executes: Qwen with component file patterns
-# Returns: Architecture review, design patterns, improvement suggestions
-```
-
-**Performance Analysis**:
-```bash
-/cli:analyze --tool codex "performance bottlenecks"
-# Executes: Codex deep analysis with performance focus
-# Returns: Bottleneck identification, optimization recommendations
-```
-
-**Enhanced Analysis**:
-```bash
-/cli:analyze --enhance "fix auth issues"
-# Step 1: Enhance prompt to expand context
-# Step 2: Analysis with expanded context
-# Returns: Root cause analysis, fix recommendations (NO automatic fixes)
-```
-
-## Output Routing
-
-**Output Destination Logic**:
-- **Active session exists AND analysis is session-relevant**:
-  - Save to `.workflow/WFS-[id]/.chat/analyze-[timestamp].md`
-- **No active session OR one-off analysis**:
-  - Save to `.workflow/.scratchpad/analyze-[description]-[timestamp].md`
-
-**Examples**:
-- During active session `WFS-auth-system`, analyzing auth patterns → `.chat/analyze-20250105-143022.md`
-- No session, quick security check → `.scratchpad/analyze-security-20250105-143045.md`
 
 ## Notes
 
-- Command templates, file patterns, and best practices: see intelligent-tools-strategy.md (loaded in memory)
+- See `intelligent-tools-strategy.md` for detailed tool usage and templates
-- Scratchpad directory details: see workflow-architecture.md
-- Scratchpad files can be promoted to workflow sessions if analysis proves valuable

.claude/commands/cli/chat.md

@@ -9,148 +9,117 @@ allowed-tools: SlashCommand(*), Bash(*), Task(*)
 
 ## Purpose
 
-Direct Q&A interaction with CLI tools for codebase analysis. **Analysis only - does NOT modify code**.
+Direct Q&A interaction with CLI tools for codebase analysis. **Read-only - does NOT modify code**.
 
-**Intent**: Ask questions, get explanations, understand codebase structure
+**Tool Selection**:
-**Supported Tools**: codex, gemini (default), qwen
+- **gemini** (default) - Best for Q&A and explanations
-
+- **qwen** - Fallback when Gemini unavailable
-## Core Behavior
+- **codex** - Alternative for technical deep-dives
-
-1. **Conversational Analysis**: Direct question-answer interaction about codebase
-2. **Read-Only**: This command ONLY provides information and analysis
-3. **No Code Modification**: Results are explanations and insights
-4. **Flexible Context**: Choose specific files or entire codebase
 
 ## Parameters
 
+- `--tool <gemini|qwen|codex>` - Tool selection (default: gemini)
+- `--agent` - Use cli-execution-agent for automated context discovery
+- `--enhance` - Enhance inquiry with `/enhance-prompt`
 - `<inquiry>` (Required) - Question or analysis request
-- `--agent` - Use cli-execution-agent for automated context discovery (5-phase intelligent mode)
+
-- `--tool <codex|gemini|qwen>` - Select CLI tool (default: gemini, ignored in agent mode)
+## Tool Usage
-- `--enhance` - Enhance inquiry with `/enhance-prompt` first
+
-- `--all-files` - Include entire codebase in context
+**Gemini** (Primary):
-- `--save-session` - Save interaction to workflow session
+```bash
+--tool gemini  # or omit (default)
+```
+
+**Qwen** (Fallback):
+```bash
+--tool qwen
+```
+
+**Codex** (Alternative):
+```bash
+--tool codex
+```
 
 ## Execution Flow
 
-### Standard Mode (Default)
+### Standard Mode
-
 1. Parse tool selection (default: gemini)
-2. If `--enhance`: Execute `/enhance-prompt` to expand user intent
+2. Optional: enhance with `/enhance-prompt`
-3. Assemble context: `@{CLAUDE.md}` + user-specified files or `--all-files`
+3. Assemble context: `@CLAUDE.md` + inferred files
-4. Execute CLI tool with assembled context (read-only, analysis mode)
+4. Execute Q&A (read-only)
-5. Return explanations and insights (NO code changes)
+5. Return answer
-6. Optionally save to workflow session
 
-### Agent Mode (`--agent` flag)
+### Agent Mode (`--agent`)
 
-Delegate inquiry to `cli-execution-agent` for intelligent Q&A with automated context discovery.
+Delegates to agent for intelligent Q&A:
 
-**Agent invocation**:
 ```javascript
 Task(
   subagent_type="cli-execution-agent",
-  description="Answer question with automated context discovery",
+  description="Codebase Q&A",
   prompt=`
     Task: ${inquiry}
-    Mode: analyze (Q&A)
+    Mode: chat (Q&A)
-    Tool Preference: ${tool_flag || 'auto-select'}
+    Tool: ${tool_flag || 'auto-select'}  // gemini|qwen|codex
-    ${all_files_flag ? 'Scope: all-files' : ''}
+    Enhance: ${enhance_flag || false}
 
-    Agent will autonomously:
+    Agent responsibilities:
-    - Discover files relevant to the question
+    1. Context Discovery:
-    - Build Q&A prompt with precise context
+       - Discover files relevant to question
-    - Execute and generate comprehensive answer
+       - Identify key code sections
-    - Save conversation log
+       - Build precise context
+
+    2. CLI Command Generation:
+       - Build Gemini/Qwen/Codex command
+       - Include discovered context
+       - Apply Q&A template
+
+    3. Execution & Output:
+       - Execute Q&A analysis
+       - Generate detailed answer
+       - Save to .workflow/.chat/ or .scratchpad/
   `
 )
 ```
 
-The agent handles all phases internally.
+## Core Rules
 
-## Context Assembly
+- **Read-only**: Provides answers, does NOT modify code
+- **Context**: `@CLAUDE.md` + inferred or all files (`@**/*`)
+- **Output**: Saves to `.workflow/WFS-[id]/.chat/` or `.scratchpad/`
 
-**Always included**: `@{CLAUDE.md,**/*CLAUDE.md}` (project guidelines)
+## CLI Command Templates
-
-**Optional**:
-- User-explicit files from inquiry keywords
-- `--all-files` flag includes entire codebase (`--all-files` wrapper parameter)
-
-For targeted analysis, use `rg` or MCP tools to discover relevant files first, then build precise CONTEXT field.
-
-## Command Template
 
+**Gemini/Qwen**:
 ```bash
-cd . && ~/.claude/scripts/gemini-wrapper -p "
+cd . && gemini -p "
-INQUIRY: [user question]
+PURPOSE: Answer question
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [inferred or --all-files]
+TASK: [inquiry]
 MODE: analysis
-RESPONSE: Direct answer, explanation, insights (NO code modification)
+CONTEXT: @CLAUDE.md [inferred or @**/*]
+EXPECTED: Clear answer
+RULES: Focus on accuracy
 "
+# Qwen: Replace 'gemini' with 'qwen'
 ```
 
-## Examples
+**Codex**:
-
-**Basic Question (Standard Mode)**:
 ```bash
-/cli:chat "analyze the authentication flow"
+codex -C . --full-auto exec "
-# Executes: Gemini analysis
+PURPOSE: Answer question
-# Returns: Explanation of auth flow, components involved, data flow
+TASK: [inquiry]
+MODE: analysis
+CONTEXT: @CLAUDE.md [inferred or @**/*]
+EXPECTED: Detailed answer
+RULES: Technical depth
+" -m gpt-5 --skip-git-repo-check -s danger-full-access
 ```
 
-**Intelligent Q&A (Agent Mode)**:
+## Output
-```bash
-/cli:chat --agent "how does JWT token refresh work in this codebase"
-# Phase 1: Understands inquiry = JWT refresh mechanism
-# Phase 2: Discovers JWT files, refresh logic, middleware patterns
-# Phase 3: Builds Q&A prompt with discovered implementation details
-# Phase 4: Executes Gemini with precise context for accurate answer
-# Phase 5: Saves conversation log with discovered context
-# Returns: Detailed answer with code references + execution log
-```
 
-**Architecture Question**:
+- **With session**: `.workflow/WFS-[id]/.chat/chat-[timestamp].md`
-```bash
+- **No session**: `.workflow/.scratchpad/chat-[desc]-[timestamp].md`
-/cli:chat --tool qwen "how does React component optimization work here"
-# Executes: Qwen architecture analysis
-# Returns: Component structure explanation, optimization patterns used
-```
-
-**Security Analysis**:
-```bash
-/cli:chat --tool codex "review security vulnerabilities"
-# Executes: Codex security analysis
-# Returns: Vulnerability assessment, security recommendations (NO automatic fixes)
-```
-
-**Enhanced Inquiry**:
-```bash
-/cli:chat --enhance "explain the login issue"
-# Step 1: Enhance to expand login context
-# Step 2: Analysis with expanded understanding
-# Returns: Detailed explanation of login flow and potential issues
-```
-
-**Broad Context**:
-```bash
-/cli:chat --all-files "find all API endpoints"
-# Executes: Analysis across entire codebase
-# Returns: List and explanation of API endpoints (NO code generation)
-```
-
-## Output Routing
-
-**Output Destination Logic**:
-- **Active session exists AND query is session-relevant**:
-  - Save to `.workflow/WFS-[id]/.chat/chat-[timestamp].md`
-- **No active session OR unrelated query**:
-  - Save to `.workflow/.scratchpad/chat-[description]-[timestamp].md`
-
-**Examples**:
-- During active session `WFS-api-refactor`, asking about API structure → `.chat/chat-20250105-143022.md`
-- No session, asking about build process → `.scratchpad/chat-build-process-20250105-143045.md`
 
 ## Notes
 
-- Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory)
+- See `intelligent-tools-strategy.md` for detailed tool usage and templates
-- Scratchpad directory details: see workflow-architecture.md
-- Scratchpad conversations preserved for future reference

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

@@ -32,7 +32,7 @@ Creates tool-specific configuration directories:
 - `.gemini/settings.json`:
 ```json
 {
-  "contextfilename": "CLAUDE.md"
+  "contextfilename": ["CLAUDE.md","GEMINI.md"]
 }
 ```
 
@@ -40,7 +40,7 @@ Creates tool-specific configuration directories:
 - `.qwen/settings.json`:
 ```json
 {
-  "contextfilename": "CLAUDE.md"
+  "contextfilename": ["CLAUDE.md","QWEN.md"]
 }
 ```
 
@@ -178,7 +178,7 @@ target/
 /cli:cli-init --tool all --output=.config/
 ```
 
-## EXECUTION INSTRUCTIONS ⚡ START HERE
+## EXECUTION INSTRUCTIONS - START HERE
 
 **When this command is triggered, follow these exact steps:**
 
@@ -209,7 +209,7 @@ bash(find . -name "Dockerfile" | head -1)
 ```bash
 # Create .gemini/ directory and settings.json
 mkdir -p .gemini
-echo '{"contextfilename": "CLAUDE.md"}' > .gemini/settings.json
+Write({file_path: '.gemini/settings.json', content: '{"contextfilename": "CLAUDE.md"}'})
 
 # Create .geminiignore file with detected technology rules
 # Backup existing files if present
@@ -219,7 +219,7 @@ echo '{"contextfilename": "CLAUDE.md"}' > .gemini/settings.json
 ```bash
 # Create .qwen/ directory and settings.json
 mkdir -p .qwen
-echo '{"contextfilename": "CLAUDE.md"}' > .qwen/settings.json
+Write({file_path: '.qwen/settings.json', content: '{"contextfilename": "CLAUDE.md"}'})
 
 # Create .qwenignore file with detected technology rules
 # Backup existing files if present

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

@@ -130,7 +130,7 @@ git status --short
 codex -C [dir] --full-auto exec "
 PURPOSE: [group goal]
 TASK: [subtask description - first in group]
-CONTEXT: @{relevant_files} @{CLAUDE.md}
+CONTEXT: @{relevant_files} @CLAUDE.md
 EXPECTED: [specific deliverables]
 RULES: [constraints]
 Group [X]: [group name] - Subtask 1 of N in this group
@@ -164,7 +164,7 @@ git add -A
 codex -C [dir] --full-auto exec "
 PURPOSE: [new group goal]
 TASK: [subtask description - first in new group]
-CONTEXT: @{different_files} @{CLAUDE.md}
+CONTEXT: @{different_files} @CLAUDE.md
 EXPECTED: [specific deliverables]
 RULES: [constraints]
 Group [Y]: [new group name] - Subtask 1 of N in this group
@@ -257,12 +257,12 @@ TodoWrite({
 
 **When to Resume vs New Session**:
 ```
-✅ RESUME (same group):
+RESUME (same group):
   - Subtasks share files/modules
   - Logical continuation of previous work
   - Same architectural domain
 
-❌ NEW SESSION (different group):
+NEW SESSION (different group):
   - Independent task area
   - Different files/modules
   - Switching architectural domains
@@ -318,7 +318,7 @@ AskUserQuestion({
 
 **During Execution**:
 ```
-📊 Task Flow Diagram:
+Task Flow Diagram:
 [Group A: Auth Core]
   A1: Create user model ──┐
   A2: Add validation     ─┤─► [resume] ─► A3: Database schema
@@ -331,7 +331,7 @@ AskUserQuestion({
   C1: Unit tests ─────────────► [new session]
   C2: Integration tests ──────► [resume]
 
-📋 Task Decomposition:
+Task Decomposition:
   [Group A] 1. Create user model
   [Group A] 2. Add validation logic [resume]
   [Group A] 3. Implement database schema [resume]
@@ -341,28 +341,28 @@ AskUserQuestion({
   [Group C] 7. Unit tests [new session]
   [Group C] 8. Integration tests [resume]
 
-▶️  [Group A] Executing Subtask 1/8: Create user model
+[Group A] Executing Subtask 1/8: Create user model
   Starting new Codex session for Group A...
   [Codex output]
-  ✅ Subtask 1 completed
+  Subtask 1 completed
 
-🔍 Git Verification:
+Git Verification:
   M  src/models/user.ts
-  ✅ Changes verified
+  Changes verified
 
-▶️  [Group A] Executing Subtask 2/8: Add validation logic
+[Group A] Executing Subtask 2/8: Add validation logic
   Resuming Codex session (same group)...
   [Codex output]
-  ✅ Subtask 2 completed
+  Subtask 2 completed
 
-▶️  [Group B] Executing Subtask 4/8: Create auth endpoints
+[Group B] Executing Subtask 4/8: Create auth endpoints
   Starting NEW Codex session for Group B...
   [Codex output]
-  ✅ Subtask 4 completed
+  Subtask 4 completed
 ...
 
-✅ All Subtasks Completed
+All Subtasks Completed
-📊 Summary: [file references, changes, next steps]
+Summary: [file references, changes, next steps]
 ```
 
 **Final Summary**:
@@ -370,8 +370,8 @@ AskUserQuestion({
 # Task Execution Summary: [Task Description]
 
 ## Subtasks Completed
-1. ✅ [Subtask 1]: [files modified]
+1. [Subtask 1]: [files modified]
-2. ✅ [Subtask 2]: [files modified]
+2. [Subtask 2]: [files modified]
 ...
 
 ## Files Modified
@@ -515,6 +515,5 @@ AskUserQuestion({
 **Context Window**: `codex exec "..." resume --last` maintains conversation history, ensuring consistency across subtasks without redundant context injection.
 
 **Output Details**:
-- Output routing and scratchpad details: see workflow-architecture.md
 - Session management: see intelligent-tools-strategy.md
 - **⚠️ Code Modification**: This command performs multi-stage code modifications - execution log tracks all changes

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

@@ -69,11 +69,11 @@ Gemini analyzes the topic and proposes preliminary plan.
 ```bash
 # Round 1: CONTEXT_INPUT is the initial topic
 # Subsequent rounds: CONTEXT_INPUT is the synthesis from previous round
-~/.claude/scripts/gemini-wrapper -p "
+gemini -p "
 PURPOSE: Analyze and propose a plan for '[topic]'
 TASK: Provide initial analysis, identify key modules, and draft implementation plan
 MODE: analysis
-CONTEXT: @{CLAUDE.md} [auto-detected files]
+CONTEXT: @CLAUDE.md [auto-detected files]
 INPUT: [CONTEXT_INPUT]
 EXPECTED: Structured analysis and draft plan for discussion
 RULES: Focus on technical depth and practical considerations
@@ -90,7 +90,7 @@ codex --full-auto exec "
 PURPOSE: Critically review technical plan
 TASK: Review the provided plan, identify weaknesses, suggest alternatives, reason about trade-offs
 MODE: analysis
-CONTEXT: @{CLAUDE.md} [relevant files]
+CONTEXT: @CLAUDE.md [relevant files]
 INPUT_PLAN: [Output from Gemini's analysis]
 EXPECTED: Critical review with alternative ideas and risk analysis
 RULES: Focus on architectural soundness and implementation feasibility
@@ -279,11 +279,11 @@ Each round's output is structured as:
 
 | Command | Models | Rounds | Discussion | Implementation | Use Case |
 |---------|--------|--------|------------|----------------|----------|
-| `/cli:mode:plan` | Gemini | 1 | ❌ NO | ❌ NO | Single-model planning |
+| `/cli:mode:plan` | Gemini | 1 | NO | NO | Single-model planning |
-| `/cli:analyze` | Gemini/Qwen | 1 | ❌ NO | ❌ NO | Code analysis |
+| `/cli:analyze` | Gemini/Qwen | 1 | NO | NO | Code analysis |
-| `/cli:execute` | Any | 1 | ❌ NO | ✅ YES | Direct implementation |
+| `/cli:execute` | Any | 1 | NO | YES | Direct implementation |
-| `/cli:codex-execute` | Codex | 1 | ❌ NO | ✅ YES | Multi-stage implementation |
+| `/cli:codex-execute` | Codex | 1 | NO | YES | Multi-stage implementation |
-| `/cli:discuss-plan` | **Gemini+Codex+Claude** | **Multiple** | ✅ **YES** | ❌ **NO** | **Multi-perspective planning** |
+| `/cli:discuss-plan` | **Gemini+Codex+Claude** | **Multiple** | **YES** | **NO** | **Multi-perspective planning** |
 
 ## Best Practices
 
@@ -317,5 +317,4 @@ Each round's output is structured as:
 -   **Priority System**: Ensures Gemini leads analysis, Codex provides critique, Claude synthesizes
 -   **Output Quality**: Multi-perspective discussion produces more robust plans than single-model analysis
 -   Command patterns and session management: see intelligent-tools-strategy.md (loaded in memory)
--   Output routing details: see workflow-architecture.md
 -   For implementation after discussion, use `/cli:execute` or `/cli:codex-execute` separately

.claude/commands/cli/execute.md

@@ -27,7 +27,7 @@ Execute implementation tasks with **YOLO permissions** (auto-approves all confir
 ### YOLO Permissions
 Auto-approves: file pattern inference, execution, **file modifications**, summary generation
 
-**⚠️ WARNING**: This command will make actual code changes without manual confirmation
+**WARNING**: This command will make actual code changes without manual confirmation
 
 ### Execution Modes
 
@@ -45,11 +45,11 @@ Auto-approves: file pattern inference, execution, **file modifications**, summar
 
 ### Context Inference
 
-Auto-selects files based on keywords and technology:
+Auto-selects files based on keywords and technology (each @ references one pattern):
-- "auth" → `@{**/*auth*,**/*user*}`
+- "auth" → `@**/*auth* @**/*user*`
-- "React" → `@{src/**/*.{jsx,tsx}}`
+- "React" → `@src/**/*.jsx @src/**/*.tsx`
-- "api" → `@{**/api/**/*,**/routes/**/*}`
+- "api" → `@**/api/**/* @**/routes/**/*`
-- Always includes: `@{CLAUDE.md,**/*CLAUDE.md}`
+- Always includes: `@CLAUDE.md @**/*CLAUDE.md`
 
 For precise file targeting, use `rg` or MCP tools to discover files first.
 
@@ -111,11 +111,11 @@ Use `resume --last` when current task extends/relates to previous execution. See
 ### Standard Mode (Default)
 ```bash
 # Gemini/Qwen: MODE=write with --approval-mode yolo
-cd . && ~/.claude/scripts/gemini-wrapper --approval-mode yolo -p "
+cd . && gemini --approval-mode yolo "
 PURPOSE: [implementation goal]
 TASK: [specific implementation]
 MODE: write
-CONTEXT: @{CLAUDE.md} [auto-detected files]
+CONTEXT: @CLAUDE.md [auto-detected files]
 EXPECTED: Working implementation with code changes
 RULES: [constraints] | Auto-approve all changes
 "
@@ -158,14 +158,14 @@ The agent handles all phases internally, including complexity-based tool selecti
 
 ## Examples
 
-**Basic Implementation (Standard Mode)** (⚠️ modifies code):
+**Basic Implementation (Standard Mode)** (modifies code):
 ```bash
 /cli:execute "implement JWT authentication with middleware"
 # Executes: Creates auth middleware, updates routes, modifies config
 # Result: NEW/MODIFIED code files with JWT implementation
 ```
 
-**Intelligent Implementation (Agent Mode)** (⚠️ modifies code):
+**Intelligent Implementation (Agent Mode)** (modifies code):
 ```bash
 /cli:execute --agent "implement OAuth2 authentication with token refresh"
 # Phase 1: Classifies intent=execute, complexity=complex, keywords=['oauth2', 'auth', 'token', 'refresh']
@@ -176,7 +176,7 @@ The agent handles all phases internally, including complexity-based tool selecti
 # Result: Complete OAuth2 implementation + detailed execution log
 ```
 
-**Enhanced Implementation** (⚠️ modifies code):
+**Enhanced Implementation** (modifies code):
 ```bash
 /cli:execute --enhance "implement JWT authentication"
 # Step 1: Enhance to expand requirements
@@ -184,7 +184,7 @@ The agent handles all phases internally, including complexity-based tool selecti
 # Result: Complete auth system with MODIFIED code files
 ```
 
-**Task Execution** (⚠️ modifies code):
+**Task Execution** (modifies code):
 ```bash
 /cli:execute IMPL-001
 # Reads: .task/IMPL-001.json for requirements
@@ -192,14 +192,14 @@ The agent handles all phases internally, including complexity-based tool selecti
 # Result: Code changes per task definition
 ```
 
-**Codex Implementation** (⚠️ modifies code):
+**Codex Implementation** (modifies code):
 ```bash
 /cli:execute --tool codex "optimize database queries"
 # Executes: Codex with full file access
 # Result: MODIFIED query code, new indexes, updated tests
 ```
 
-**Qwen Code Generation** (⚠️ modifies code):
+**Qwen Code Generation** (modifies code):
 ```bash
 /cli:execute --tool qwen --enhance "refactor auth module"
 # Step 1: Enhanced refactoring plan
@@ -211,12 +211,11 @@ The agent handles all phases internally, including complexity-based tool selecti
 
 | Command | Intent | Code Changes | Auto-Approve |
 |---------|--------|--------------|--------------|
-| `/cli:analyze` | Understand code | ❌ NO | N/A |
+| `/cli:analyze` | Understand code | NO | N/A |
-| `/cli:chat` | Ask questions | ❌ NO | N/A |
+| `/cli:chat` | Ask questions | NO | N/A |
-| `/cli:execute` | **Implement** | ✅ **YES** | ✅ **YES** |
+| `/cli:execute` | **Implement** | **YES** | **YES** |
 
 ## Notes
 
 - Command templates, YOLO mode details, and session management: see intelligent-tools-strategy.md (loaded in memory)
-- Output routing and scratchpad details: see workflow-architecture.md
+- **Code Modification**: This command modifies code - execution logs document changes made
-- **⚠️ Code Modification**: This command modifies code - execution logs document changes made

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

@@ -0,0 +1,130 @@
+---
+name: bug-diagnosis
+description: Bug diagnosis and fix suggestions using CLI tools with specialized template
+argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] bug description"
+allowed-tools: SlashCommand(*), Bash(*), Task(*)
+---
+
+# CLI Mode: Bug Diagnosis (/cli:mode:bug-diagnosis)
+
+## Purpose
+
+Systematic bug diagnosis with root cause analysis template (`~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt`).
+
+**Tool Selection**:
+- **gemini** (default) - Best for bug diagnosis
+- **qwen** - Fallback when Gemini unavailable
+- **codex** - Alternative for complex bug analysis
+
+## Parameters
+
+- `--tool <gemini|qwen|codex>` - Tool selection (default: gemini)
+- `--agent` - Use cli-execution-agent for automated context discovery
+- `--enhance` - Enhance bug description with `/enhance-prompt`
+- `--cd "path"` - Target directory for focused diagnosis
+- `<bug-description>` (Required) - Bug description or error details
+
+## Tool Usage
+
+**Gemini** (Primary):
+```bash
+# Uses gemini by default, or specify explicitly
+--tool gemini
+```
+
+**Qwen** (Fallback):
+```bash
+--tool qwen
+```
+
+**Codex** (Alternative):
+```bash
+--tool codex
+```
+
+## Execution Flow
+
+### Standard Mode
+1. Parse tool selection (default: gemini)
+2. Optional: enhance with `/enhance-prompt`
+3. Detect directory from `--cd` or auto-infer
+4. Build command with template
+5. Execute diagnosis (read-only)
+6. Save to `.workflow/WFS-[id]/.chat/`
+
+### Agent Mode (`--agent`)
+
+Delegates to agent for intelligent diagnosis:
+
+```javascript
+Task(
+  subagent_type="cli-execution-agent",
+  description="Bug root cause diagnosis",
+  prompt=`
+    Task: ${bug_description}
+    Mode: bug-diagnosis
+    Tool: ${tool_flag || 'auto-select'}  // gemini|qwen|codex
+    Directory: ${cd_path || 'auto-detect'}
+    Template: ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt
+
+    Agent responsibilities:
+    1. Context Discovery:
+       - Locate error traces and logs
+       - Find related code sections
+       - Identify data flow paths
+
+    2. CLI Command Generation:
+       - Build Gemini/Qwen/Codex command
+       - Include diagnostic context
+       - Apply ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt template
+
+    3. Execution & Output:
+       - Execute root cause analysis
+       - Generate fix suggestions
+       - Save to .workflow/.chat/
+  `
+)
+```
+
+## Core Rules
+
+- **Read-only**: Diagnoses bugs, does NOT modify code
+- **Template**: Uses `~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt` for root cause analysis
+- **Output**: Saves to `.workflow/WFS-[id]/.chat/`
+
+## CLI Command Templates
+
+**Gemini/Qwen** (default, diagnosis only):
+```bash
+cd [dir] && gemini -p "
+PURPOSE: [goal]
+TASK: Root cause analysis
+MODE: analysis
+CONTEXT: @**/*
+EXPECTED: Diagnosis, fix plan
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt)
+"
+# Qwen: Replace 'gemini' with 'qwen'
+```
+
+**Codex** (diagnosis + potential fixes):
+```bash
+codex -C [dir] --full-auto exec "
+PURPOSE: [goal]
+TASK: Bug diagnosis
+MODE: analysis
+CONTEXT: @**/*
+EXPECTED: Diagnosis, fix suggestions
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt)
+" -m gpt-5 --skip-git-repo-check -s danger-full-access
+```
+
+## Output
+
+- **With session**: `.workflow/WFS-[id]/.chat/bug-diagnosis-[timestamp].md`
+- **No session**: `.workflow/.scratchpad/bug-diagnosis-[desc]-[timestamp].md`
+
+## Notes
+
+- Template: `~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt`
+- See `intelligent-tools-strategy.md` for detailed tool usage

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

@@ -1,164 +0,0 @@
----
-name: bug-index
-description: Bug analysis and fix suggestions using CLI tools
-argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] bug description"
-allowed-tools: SlashCommand(*), Bash(*), Task(*)
----
-
-# CLI Mode: Bug Index (/cli:mode:bug-index)
-
-## Purpose
-
-Systematic bug analysis with diagnostic template (`~/.claude/prompt-templates/bug-fix.md`).
-
-**Supported Tools**: codex, gemini (default), qwen
-**Key Feature**: `--cd` flag for directory-scoped analysis
-
-## Parameters
-
-- `--agent` - Use cli-execution-agent for automated context discovery (5-phase intelligent mode)
-- `--tool <codex|gemini|qwen>` - Tool selection (default: gemini, ignored in agent mode)
-- `--enhance` - Enhance bug description with `/enhance-prompt` first
-- `--cd "path"` - Target directory for focused analysis
-- `<bug-description>` (Required) - Bug description or error message
-
-## Execution Flow
-
-### Standard Mode (Default)
-
-1. **Parse tool selection**: Extract `--tool` flag (default: gemini)
-2. **If `--enhance` flag present**: Execute `/enhance-prompt "[bug-description]"` first
-3. Parse bug description (original or enhanced)
-4. Detect target directory (from `--cd` or auto-infer)
-5. Build command for selected tool with bug-fix template
-6. Execute analysis (read-only, provides fix recommendations)
-7. Save to `.workflow/WFS-[id]/.chat/bug-index-[timestamp].md`
-
-### Agent Mode (`--agent` flag)
-
-Delegate bug analysis to `cli-execution-agent` for intelligent debugging with automated context discovery.
-
-**Agent invocation**:
-```javascript
-Task(
-  subagent_type="cli-execution-agent",
-  description="Analyze bug with automated context discovery",
-  prompt=`
-    Task: ${bug_description}
-    Mode: debug (bug analysis)
-    Tool Preference: ${tool_flag || 'auto-select'}
-    ${cd_flag ? `Directory Scope: ${cd_path}` : ''}
-    Template: bug-fix
-
-    Agent will autonomously:
-    - Discover bug-related files and error traces
-    - Build debug prompt with bug-fix template
-    - Execute analysis and provide fix recommendations
-    - Save analysis log
-  `
-)
-```
-
-The agent handles all phases internally.
-
-## Core Rules
-
-1. **Analysis Only**: This command analyzes bugs and suggests fixes - it does NOT modify code
-2. **Enhance First (if flagged)**: Execute `/enhance-prompt` before analysis
-3. **Directory Context**: Use `cd` when `--cd` provided or auto-detected
-4. **Template Required**: Always use bug-fix template
-5. **Session Output**: Save analysis results and fix recommendations to session chat
-
-## Analysis Focus (via Template)
-
-- Root cause investigation and diagnosis
-- Code path tracing to locate issues
-- Targeted minimal fix recommendations
-- Impact assessment of proposed changes
-
-## Command Template
-
-```bash
-cd [directory] && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: [bug analysis goal]
-TASK: Systematic bug analysis and fix recommendations
-MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory]
-EXPECTED: Root cause analysis, code path tracing, targeted fix suggestions
-RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: [description]
-"
-```
-
-## Examples
-
-**Basic Bug Analysis (Standard Mode)**:
-```bash
-/cli:mode:bug-index "null pointer error in login flow"
-# Executes: Gemini with bug-fix template
-# Returns: Root cause analysis, fix recommendations
-```
-
-**Intelligent Bug Analysis (Agent Mode)**:
-```bash
-/cli:mode:bug-index --agent "intermittent token validation failure"
-# Phase 1: Classifies as debug task, extracts keywords ['token', 'validation', 'failure']
-# Phase 2: MCP discovers token validation code, middleware, test files with errors
-# Phase 3: Builds debug prompt with bug-fix template + discovered error patterns
-# Phase 4: Executes Gemini with comprehensive bug context
-# Phase 5: Saves analysis log with detailed fix recommendations
-# Returns: Root cause analysis + code path traces + minimal fix suggestions
-```
-
-**Standard Template Example**:
-```bash
-cd . && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: Debug authentication null pointer error
-TASK: Identify root cause and provide fix recommendations
-MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Root cause, code path, minimal fix suggestion, impact assessment
-RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: null pointer in login flow
-"
-```
-
-**Directory-Specific**:
-```bash
-cd src/auth && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: Fix token validation failure
-TASK: Analyze token validation bug in auth module
-MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Validation logic analysis, fix recommendation with minimal changes
-RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: token validation fails intermittently
-"
-```
-
-## Bug Investigation Workflow
-
-```bash
-# 1. Find bug-related files
-rg "error_keyword" --files-with-matches
-mcp__code-index__search_code_advanced(pattern="error|exception", file_pattern="*.ts")
-
-# 2. Execute bug analysis with focused context (analysis only, no code changes)
-/cli:mode:bug-index --cd "src/module" "specific error description"
-```
-
-## Output Routing
-
-**Output Destination Logic**:
-- **Active session exists AND bug is session-relevant**:
-  - Save to `.workflow/WFS-[id]/.chat/bug-index-[timestamp].md`
-- **No active session OR quick debugging**:
-  - Save to `.workflow/.scratchpad/bug-index-[description]-[timestamp].md`
-
-**Examples**:
-- During active session `WFS-payment-fix`, analyzing payment bug → `.chat/bug-index-20250105-143022.md`
-- No session, quick null pointer investigation → `.scratchpad/bug-index-null-pointer-20250105-143045.md`
-
-## Notes
-
-- Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory)
-- Scratchpad directory details: see workflow-architecture.md
-- Template path: `~/.claude/prompt-templates/bug-fix.md`
-- Always uses `--all-files` for comprehensive codebase context

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

@@ -9,162 +9,129 @@ allowed-tools: SlashCommand(*), Bash(*), Task(*)
 
 ## Purpose
 
-Systematic code analysis with execution path tracing template (`~/.claude/prompt-templates/code-analysis.md`).
+Systematic code analysis with execution path tracing template (`~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt`).
+
+**Tool Selection**:
+- **gemini** (default) - Best for code analysis and tracing
+- **qwen** - Fallback when Gemini unavailable
+- **codex** - Alternative for complex analysis tasks
 
-**Supported Tools**: codex, gemini (default), qwen
 **Key Feature**: `--cd` flag for directory-scoped analysis
 
 ## Parameters
 
-- `--agent` - Use cli-execution-agent for automated context discovery (5-phase intelligent mode)
+- `--tool <gemini|qwen|codex>` - Tool selection (default: gemini)
-- `--tool <codex|gemini|qwen>` - Tool selection (default: gemini, ignored in agent mode)
+- `--agent` - Use cli-execution-agent for automated context discovery
 - `--enhance` - Enhance analysis target with `/enhance-prompt` first
 - `--cd "path"` - Target directory for focused analysis
 - `<analysis-target>` (Required) - Code analysis target or question
 
+## Tool Usage
+
+**Gemini** (Primary):
+```bash
+/cli:mode:code-analysis --tool gemini "trace auth flow"
+# OR (default)
+/cli:mode:code-analysis "trace auth flow"
+```
+
+**Qwen** (Fallback):
+```bash
+/cli:mode:code-analysis --tool qwen "trace auth flow"
+```
+
+**Codex** (Alternative):
+```bash
+/cli:mode:code-analysis --tool codex "trace auth flow"
+```
+
 ## Execution Flow
 
 ### Standard Mode (Default)
 
-1. **Parse tool selection**: Extract `--tool` flag (default: gemini)
+1. Parse tool selection (default: gemini)
-2. **If `--enhance` flag present**: Execute `/enhance-prompt "[analysis-target]"` first
+2. Optional: enhance analysis target with `/enhance-prompt`
-3. Parse analysis target (original or enhanced)
+3. Detect target directory from `--cd` or auto-infer
-4. Detect target directory (from `--cd` or auto-infer)
+4. Build command with template
-5. Build command for selected tool with code-analysis template
+5. Execute analysis (read-only)
-6. Execute deep analysis (read-only, no code modification)
+6. Save to `.workflow/WFS-[id]/.chat/code-analysis-[timestamp].md`
-7. Save to `.workflow/WFS-[id]/.chat/code-analysis-[timestamp].md`
 
 ### Agent Mode (`--agent` flag)
 
-Delegate code analysis to `cli-execution-agent` for intelligent execution path tracing with automated context discovery.
+Delegates to `cli-execution-agent` for intelligent context discovery and analysis.
+
+## Core Rules
+
+- **Read-only**: Analyzes code, does NOT modify files
+- **Template**: Uses `~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt` for systematic analysis
+- **Output**: Saves to `.workflow/WFS-[id]/.chat/`
+
+## CLI Command Templates
+
+**Gemini/Qwen** (default, read-only analysis):
+```bash
+cd [dir] && gemini -p "
+PURPOSE: [goal]
+TASK: Execution path tracing
+MODE: analysis
+CONTEXT: @**/*
+EXPECTED: Trace, call diagram
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt)
+"
+# Qwen: Replace 'gemini' with 'qwen'
+```
+
+**Codex** (analysis + optimization suggestions):
+```bash
+codex -C [dir] --full-auto exec "
+PURPOSE: [goal]
+TASK: Path analysis
+MODE: analysis
+CONTEXT: @**/*
+EXPECTED: Trace, optimization
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt)
+" -m gpt-5 --skip-git-repo-check -s danger-full-access
+```
+
+## Agent Execution Context
+
+When `--agent` flag is used, delegate to agent:
 
-**Agent invocation**:
 ```javascript
 Task(
   subagent_type="cli-execution-agent",
-  description="Analyze code execution paths with automated context discovery",
+  description="Code execution path analysis",
   prompt=`
     Task: ${analysis_target}
-    Mode: code-analysis (execution tracing)
+    Mode: code-analysis
-    Tool Preference: ${tool_flag || 'auto-select'}
+    Tool: ${tool_flag || 'auto-select'}  // gemini|qwen|codex
-    ${cd_flag ? `Directory Scope: ${cd_path}` : ''}
+    Directory: ${cd_path || 'auto-detect'}
-    Template: code-analysis
+    Template: ~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt
 
-    Agent will autonomously:
+    Agent responsibilities:
-    - Discover execution paths and call flows
+    1. Context Discovery:
-    - Build analysis prompt with code-analysis template
+       - Identify entry points and call chains
-    - Execute deep tracing analysis
+       - Discover related files (MCP/ripgrep)
-    - Generate call diagrams and save log
+       - Map execution flow paths
+
+    2. CLI Command Generation:
+       - Build Gemini/Qwen/Codex command
+       - Include discovered context
+       - Apply ~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt template
+
+    3. Execution & Output:
+       - Execute analysis with selected tool
+       - Save to .workflow/WFS-[id]/.chat/
   `
 )
 ```
 
-The agent handles all phases internally.
+## Output
 
-## Core Rules
+- **With session**: `.workflow/WFS-[id]/.chat/code-analysis-[timestamp].md`
-
+- **No session**: `.workflow/.scratchpad/code-analysis-[desc]-[timestamp].md`
-1. **Analysis Only**: This command analyzes code and provides insights - it does NOT modify code
-2. **Tool Selection**: Use `--tool` value or default to gemini
-3. **Enhance First (if flagged)**: Execute `/enhance-prompt` before analysis
-4. **Directory Context**: Use `cd` when `--cd` provided or auto-detected
-5. **Template Required**: Always use code-analysis template
-6. **Session Output**: Save analysis results to session chat
-
-## Analysis Capabilities (via Template)
-
-- **Systematic Code Analysis**: Break down complex code into manageable parts
-- **Execution Path Tracing**: Track variable states and call stacks
-- **Control & Data Flow**: Understand code logic and data transformations
-- **Call Flow Visualization**: Diagram function calling sequences
-- **Logical Reasoning**: Explain "why" behind code behavior
-- **Debugging Insights**: Identify potential bugs or inefficiencies
-
-## Command Template
-
-```bash
-cd [directory] && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: [analysis goal]
-TASK: Systematic code analysis and execution path tracing
-MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory]
-EXPECTED: Execution trace, call flow diagram, debugging insights
-RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on [aspect]
-"
-```
-
-## Examples
-
-**Basic Code Analysis (Standard Mode)**:
-```bash
-/cli:mode:code-analysis "trace authentication execution flow"
-# Executes: Gemini with code-analysis template
-# Returns: Execution trace, call diagram, debugging insights
-```
-
-**Intelligent Code Analysis (Agent Mode)**:
-```bash
-/cli:mode:code-analysis --agent "trace JWT token validation from request to database"
-# Phase 1: Classifies as deep analysis, keywords ['jwt', 'token', 'validation', 'database']
-# Phase 2: MCP discovers request handler → middleware → service → repository chain
-# Phase 3: Builds analysis prompt with code-analysis template + complete call path
-# Phase 4: Executes Gemini with traced execution paths
-# Phase 5: Saves detailed analysis with call flow diagrams and variable states
-# Returns: Complete execution trace + call diagram + data flow analysis
-```
-
-**Standard Template Example**:
-```bash
-cd . && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: Trace authentication execution flow
-TASK: Analyze complete auth flow from request to response
-MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Step-by-step execution trace with call diagram, variable states
-RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on control flow
-"
-```
-
-**Directory-Specific Analysis**:
-```bash
-cd src/auth && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: Understand JWT token validation logic
-TASK: Trace JWT validation from middleware to service layer
-MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Validation flow diagram, token lifecycle analysis
-RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on security
-"
-```
-
-## Code Tracing Workflow
-
-```bash
-# 1. Find entry points and related files
-rg "function.*authenticate|class.*AuthService" --files-with-matches
-mcp__code-index__search_code_advanced(pattern="authenticate|login", file_pattern="*.ts")
-
-# 2. Build call graph understanding
-# entry → middleware → service → repository
-
-# 3. Execute deep analysis (analysis only, no code changes)
-/cli:mode:code-analysis --cd "src" "trace execution from entry point"
-```
-
-## Output Routing
-
-**Output Destination Logic**:
-- **Active session exists AND analysis is session-relevant**:
-  - Save to `.workflow/WFS-[id]/.chat/code-analysis-[timestamp].md`
-- **No active session OR standalone analysis**:
-  - Save to `.workflow/.scratchpad/code-analysis-[description]-[timestamp].md`
-
-**Examples**:
-- During active session `WFS-auth-refactor`, analyzing auth flow → `.chat/code-analysis-20250105-143022.md`
-- No session, tracing request lifecycle → `.scratchpad/code-analysis-request-flow-20250105-143045.md`
 
 ## Notes
 
-- Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory)
+- Template: `~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt`
-- Scratchpad directory details: see workflow-architecture.md
+- See `intelligent-tools-strategy.md` for detailed tool usage
-- Template path: `~/.claude/prompt-templates/code-analysis.md`
-- Always uses `--all-files` for comprehensive code context

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

@@ -9,160 +9,121 @@ allowed-tools: SlashCommand(*), Bash(*), Task(*)
 
 ## Purpose
 
-Comprehensive planning and architecture analysis with strategic planning template (`~/.claude/prompt-templates/plan.md`).
+Strategic software architecture planning template (`~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt`).
 
-**Supported Tools**: codex, gemini (default), qwen
+**Tool Selection**:
-**Key Feature**: `--cd` flag for directory-scoped planning
+- **gemini** (default) - Best for architecture planning
+- **qwen** - Fallback when Gemini unavailable
+- **codex** - Alternative for implementation planning
 
 ## Parameters
 
-- `--agent` - Use cli-execution-agent for automated context discovery (5-phase intelligent mode)
+- `--tool <gemini|qwen|codex>` - Tool selection (default: gemini)
-- `--tool <codex|gemini|qwen>` - Tool selection (default: gemini, ignored in agent mode)
+- `--agent` - Use cli-execution-agent for automated context discovery
-- `--enhance` - Enhance topic with `/enhance-prompt` first
+- `--enhance` - Enhance task with `/enhance-prompt`
 - `--cd "path"` - Target directory for focused planning
-- `<topic>` (Required) - Planning topic or architectural question
+- `<planning-task>` (Required) - Architecture planning task or modification requirements
+
+## Tool Usage
+
+**Gemini** (Primary):
+```bash
+--tool gemini  # or omit (default)
+```
+
+**Qwen** (Fallback):
+```bash
+--tool qwen
+```
+
+**Codex** (Alternative):
+```bash
+--tool codex
+```
 
 ## Execution Flow
 
-### Standard Mode (Default)
+### Standard Mode
+1. Parse tool selection (default: gemini)
+2. Optional: enhance with `/enhance-prompt`
+3. Detect directory from `--cd` or auto-infer
+4. Build command with template
+5. Execute planning (read-only, no code generation)
+6. Save to `.workflow/WFS-[id]/.chat/`
 
-1. **Parse tool selection**: Extract `--tool` flag (default: gemini)
+### Agent Mode (`--agent`)
-2. **If `--enhance` flag present**: Execute `/enhance-prompt "[topic]"` first
-3. Parse topic (original or enhanced)
-4. Detect target directory (from `--cd` or auto-infer)
-5. Build command for selected tool with planning template
-6. Execute analysis (read-only, no code modification)
-7. Save to `.workflow/WFS-[id]/.chat/plan-[timestamp].md`
 
-### Agent Mode (`--agent` flag)
+Delegates to agent for intelligent planning:
 
-Delegate planning to `cli-execution-agent` for intelligent strategic planning with automated architecture discovery.
-
-**Agent invocation**:
 ```javascript
 Task(
   subagent_type="cli-execution-agent",
-  description="Create strategic plan with automated architecture discovery",
+  description="Architecture modification planning",
   prompt=`
-    Task: ${planning_topic}
+    Task: ${planning_task}
-    Mode: plan (strategic planning)
+    Mode: architecture-planning
-    Tool Preference: ${tool_flag || 'auto-select'}
+    Tool: ${tool_flag || 'auto-select'}  // gemini|qwen|codex
-    ${cd_flag ? `Directory Scope: ${cd_path}` : ''}
+    Directory: ${cd_path || 'auto-detect'}
-    Template: plan
+    Template: ~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt
 
-    Agent will autonomously:
+    Agent responsibilities:
-    - Discover project structure and existing architecture
+    1. Context Discovery:
-    - Build planning prompt with plan template
+       - Analyze current architecture
-    - Execute strategic planning analysis
+       - Identify affected components
-    - Generate implementation roadmap and save
+       - Map dependencies and impacts
+
+    2. CLI Command Generation:
+       - Build Gemini/Qwen/Codex command
+       - Include architecture context
+       - Apply ~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt template
+
+    3. Execution & Output:
+       - Execute strategic planning
+       - Generate modification plan
+       - Save to .workflow/.chat/
   `
 )
 ```
 
-The agent handles all phases internally.
-
 ## Core Rules
 
-1. **Analysis Only**: This command provides planning recommendations and insights - it does NOT modify code
+- **Planning only**: Creates modification plans, does NOT generate code
-2. **Enhance First (if flagged)**: Execute `/enhance-prompt` before planning
+- **Template**: Uses `~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt` for strategic planning
-3. **Directory Context**: Use `cd` when `--cd` provided or auto-detected
+- **Output**: Saves to `.workflow/WFS-[id]/.chat/`
-4. **Template Required**: Always use planning template
-5. **Session Output**: Save analysis results to session chat
 
-## Planning Capabilities (via Template)
+## CLI Command Templates
-
-- Strategic architecture insights and recommendations
-- Implementation roadmaps and suggestions
-- Key technical decisions analysis
-- Risk assessment
-- Resource planning
-
-## Command Template
 
+**Gemini/Qwen** (default, planning only):
 ```bash
-cd [directory] && ~/.claude/scripts/gemini-wrapper --all-files -p "
+cd [dir] && gemini -p "
-PURPOSE: [planning goal from topic]
+PURPOSE: [goal]
-TASK: Comprehensive planning and architecture analysis
+TASK: Architecture planning
 MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory]
+CONTEXT: @**/*
-EXPECTED: Strategic insights, implementation recommendations, key decisions
+EXPECTED: Modification plan, impact analysis
-RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on [topic area]
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt)
 "
+# Qwen: Replace 'gemini' with 'qwen'
 ```
 
-## Examples
+**Codex** (planning + implementation guidance):
-
-**Basic Planning Analysis (Standard Mode)**:
 ```bash
-/cli:mode:plan "design user dashboard architecture"
+codex -C [dir] --full-auto exec "
-# Executes: Gemini with planning template
+PURPOSE: [goal]
-# Returns: Architecture recommendations, component design, roadmap
+TASK: Architecture planning
-```
-
-**Intelligent Planning (Agent Mode)**:
-```bash
-/cli:mode:plan --agent "design microservices architecture for payment system"
-# Phase 1: Classifies as architectural planning, keywords ['microservices', 'payment', 'architecture']
-# Phase 2: MCP discovers existing services, payment flows, integration patterns
-# Phase 3: Builds planning prompt with plan template + current architecture context
-# Phase 4: Executes Gemini with comprehensive project understanding
-# Phase 5: Saves planning document with implementation roadmap and migration strategy
-# Returns: Strategic architecture plan + implementation roadmap + risk assessment
-```
-
-**Standard Template Example**:
-```bash
-cd . && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: Design user dashboard architecture
-TASK: Plan dashboard component structure and data flow
 MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
+CONTEXT: @**/*
-EXPECTED: Architecture recommendations, component design, data flow diagram
+EXPECTED: Plan, implementation roadmap
-RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on scalability
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt)
-"
+" -m gpt-5 --skip-git-repo-check -s danger-full-access
 ```
 
-**Directory-Specific Planning**:
+## Output
-```bash
-cd src/api && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: Plan API refactoring strategy
-TASK: Analyze current API structure and recommend improvements
-MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Refactoring roadmap, breaking change analysis, migration plan
-RULES: $(cat ~/.claude/prompt-templates/plan.md) | Maintain backward compatibility
-"
-```
 
-## Planning Workflow
+- **With session**: `.workflow/WFS-[id]/.chat/plan-[timestamp].md`
-
+- **No session**: `.workflow/.scratchpad/plan-[desc]-[timestamp].md`
-```bash
-# 1. Discover project structure
-~/.claude/scripts/get_modules_by_depth.sh
-mcp__code-index__find_files(pattern="*.ts")
-
-# 2. Gather existing architecture info
-rg "architecture|design" --files-with-matches
-
-# 3. Execute planning analysis (analysis only, no code changes)
-/cli:mode:plan "topic for strategic planning"
-```
-
-## Output Routing
-
-**Output Destination Logic**:
-- **Active session exists AND planning is session-relevant**:
-  - Save to `.workflow/WFS-[id]/.chat/plan-[timestamp].md`
-- **No active session OR exploratory planning**:
-  - Save to `.workflow/.scratchpad/plan-[description]-[timestamp].md`
-
-**Examples**:
-- During active session `WFS-dashboard`, planning dashboard architecture → `.chat/plan-20250105-143022.md`
-- No session, exploring new feature idea → `.scratchpad/plan-feature-idea-20250105-143045.md`
 
 ## Notes
 
-- Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory)
+- Template: `~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt`
-- Scratchpad directory details: see workflow-architecture.md
+- See `intelligent-tools-strategy.md` for detailed tool usage
-- Template path: `~/.claude/prompt-templates/plan.md`
-- Always uses `--all-files` for comprehensive project context

.claude/commands/memory/load-skill-memory.md

@@ -0,0 +1,182 @@
+---
+name: load-skill-memory
+description: Activate SKILL package (auto-detect or manual) and load documentation based on task intent
+argument-hint: "[skill_name] \"task intent description\""
+allowed-tools: Bash(*), Read(*), Skill(*)
+---
+
+# Memory Load SKILL Command (/memory:load-skill-memory)
+
+## 1. Overview
+
+The `memory:load-skill-memory` command **activates SKILL package** (auto-detect from task or manual specification) and intelligently loads documentation based on user's task intent. The system automatically determines which documentation files to read based on the intent description.
+
+**Core Philosophy**:
+- **Flexible Activation**: Auto-detect skill from task description/paths, or user explicitly specifies
+- **Intent-Driven Loading**: System analyzes task intent to determine documentation scope
+- **Intelligent Selection**: Automatically chooses appropriate documentation level and modules
+- **Direct Context Loading**: Loads selected documentation into conversation memory
+
+**When to Use**:
+- Manually activate a known SKILL package for a specific task
+- Load SKILL context when system hasn't auto-triggered it
+- Force reload SKILL documentation with specific intent focus
+
+**Note**: Normal SKILL activation happens automatically via description triggers or path mentions (system extracts skill name from file paths for intelligent triggering). Use this command only when manual activation is needed.
+
+## 2. Parameters
+
+- `[skill_name]` (Optional): Name of SKILL package to activate
+  - If omitted: System auto-detects from task description or file paths
+  - If specified: Direct activation of named SKILL package
+  - Example: `my_project`, `api_service`
+  - Must match directory name under `.claude/skills/`
+
+- `"task intent description"` (Required): Description of what you want to do
+  - Used for both: auto-detection (if skill_name omitted) and documentation scope selection
+  - **Analysis tasks**: "分析builder pattern实现", "理解参数系统架构"
+  - **Modification tasks**: "修改workflow逻辑", "增强thermal template功能"
+  - **Learning tasks**: "学习接口设计模式", "了解测试框架使用"
+  - **With paths**: "修改D:\projects\my_project\src\auth.py的认证逻辑" (auto-extracts `my_project`)
+
+## 3. Execution Flow
+
+### Step 1: Determine SKILL Name (if not provided)
+
+**Auto-Detection Strategy** (when skill_name parameter is omitted):
+1. **Path Extraction**: Scan task description for file paths
+   - Extract potential project names from path segments
+   - Example: `"修改D:\projects\my_project\src\auth.py"` → extracts `my_project`
+2. **Keyword Matching**: Match task keywords against SKILL descriptions
+   - Search for project-specific terms, domain keywords
+3. **Validation**: Check if extracted name matches `.claude/skills/{skill_name}/`
+
+**Result**: Either uses provided skill_name or auto-detected name for activation
+
+### Step 2: Activate SKILL and Analyze Intent
+
+**Activate SKILL Package**:
+```javascript
+Skill(command: "${skill_name}")  // Uses provided or auto-detected name
+```
+
+**What Happens After Activation**:
+1. If SKILL exists in memory: System reads `.claude/skills/${skill_name}/SKILL.md`
+2. If SKILL not found in memory: Error - SKILL package doesn't exist
+3. SKILL description triggers are loaded into memory
+4. Progressive loading mechanism becomes available
+5. Documentation structure is now accessible
+
+**Intent Analysis**:
+Based on task intent description, system determines:
+- **Action type**: analyzing, modifying, learning
+- **Scope**: specific module, architecture overview, complete system
+- **Depth**: quick reference, detailed API, full documentation
+
+### Step 3: Intelligent Documentation Loading
+
+**Loading Strategy**:
+
+The system automatically selects documentation based on intent keywords:
+
+1. **Quick Understanding** ("了解", "快速理解", "什么是"):
+   - Load: Level 0 (README.md only, ~2K tokens)
+   - Use case: Quick overview of capabilities
+
+2. **Specific Module Analysis** ("分析XXX模块", "理解XXX实现"):
+   - Load: Module-specific README.md + API.md (~5K tokens)
+   - Use case: Deep dive into specific component
+
+3. **Architecture Review** ("架构", "设计模式", "整体结构"):
+   - Load: README.md + ARCHITECTURE.md (~10K tokens)
+   - Use case: System design understanding
+
+4. **Implementation/Modification** ("修改", "增强", "实现"):
+   - Load: Relevant module docs + EXAMPLES.md (~15K tokens)
+   - Use case: Code modification with examples
+
+5. **Comprehensive Learning** ("学习", "完整了解", "深入理解"):
+   - Load: Level 3 (All documentation, ~40K tokens)
+   - Use case: Complete system mastery
+
+**Documentation Loaded into Memory**:
+After loading, the selected documentation content is available in conversation memory for subsequent operations.
+
+## 4. Usage Examples
+
+### Example 1: Manual Specification
+
+**User Command**:
+```bash
+/memory:load-skill-memory my_project "修改认证模块增加OAuth支持"
+```
+
+**Execution**:
+```javascript
+// Step 1: Use provided skill_name
+skill_name = "my_project"  // Directly from parameter
+
+// Step 2: Activate SKILL
+Skill(command: "my_project")
+
+// Step 3: Intent Analysis
+Keywords: ["修改", "认证模块", "增加", "OAuth"]
+Action: modifying (implementation)
+Scope: auth module + examples
+
+// Load documentation based on intent
+Read(.workflow/docs/my_project/auth/README.md)
+Read(.workflow/docs/my_project/auth/API.md)
+Read(.workflow/docs/my_project/EXAMPLES.md)
+```
+
+### Example 2: Auto-Detection from Path
+
+**User Command**:
+```bash
+/memory:load-skill-memory "修改D:\projects\my_project\src\services\api.py的接口逻辑"
+```
+
+**Execution**:
+```javascript
+// Step 1: Auto-detect skill_name from path
+Path detected: "D:\projects\my_project\src\services\api.py"
+Extracted: "my_project"
+Validated: .claude/skills/my_project/ exists ✓
+skill_name = "my_project"
+
+// Step 2: Activate SKILL
+Skill(command: "my_project")
+
+// Step 3: Intent Analysis
+Keywords: ["修改", "services", "接口逻辑"]
+Action: modifying (implementation)
+Scope: services module + examples
+
+// Load documentation based on intent
+Read(.workflow/docs/my_project/services/README.md)
+Read(.workflow/docs/my_project/services/API.md)
+Read(.workflow/docs/my_project/EXAMPLES.md)
+```
+
+## 5. Intent Keyword Mapping
+
+**Quick Reference**:
+- **Triggers**: "了解", "快速", "什么是", "简介"
+- **Loads**: README.md only (~2K)
+
+**Module-Specific**:
+- **Triggers**: "XXX模块", "XXX组件", "分析XXX"
+- **Loads**: Module README + API (~5K)
+
+**Architecture**:
+- **Triggers**: "架构", "设计", "整体结构", "系统设计"
+- **Loads**: README + ARCHITECTURE (~10K)
+
+**Implementation**:
+- **Triggers**: "修改", "增强", "实现", "开发", "集成"
+- **Loads**: Relevant module + EXAMPLES (~15K)
+
+**Comprehensive**:
+- **Triggers**: "完整", "深入", "全面", "学习整个"
+- **Loads**: All documentation (~40K)

.claude/commands/memory/load.md

@@ -0,0 +1,240 @@
+---
+name: load
+description: Load project memory by delegating to agent, returns structured core content package for subsequent operations
+argument-hint: "[--tool gemini|qwen] \"task context description\""
+allowed-tools: Task(*), Bash(*)
+examples:
+  - /memory:load "在当前前端基础上开发用户认证功能"
+  - /memory:load --tool qwen -p "重构支付模块API"
+---
+
+# Memory Load Command (/memory:load)
+
+## 1. Overview
+
+The `memory:load` command **delegates to a universal-executor agent** to analyze the project and return a structured "Core Content Pack". This pack is loaded into the main thread's memory, providing essential context for subsequent agent operations while minimizing token consumption.
+
+**Core Philosophy**:
+- **Agent-Driven**: Fully delegates execution to universal-executor agent
+- **Read-Only Analysis**: Does not modify code, only extracts context
+- **Structured Output**: Returns standardized JSON content package
+- **Memory Optimization**: Package loaded directly into main thread memory
+- **Token Efficiency**: CLI analysis executed within agent to save tokens
+
+## 2. Parameters
+
+- `"task context description"` (Required): Task description to guide context extraction
+  - Example: "在当前前端基础上开发用户认证功能"
+  - Example: "重构支付模块API"
+  - Example: "修复数据库查询性能问题"
+
+- `--tool <gemini|qwen>` (Optional): Specify CLI tool for agent to use (default: gemini)
+  - gemini: Large context window, suitable for complex project analysis
+  - qwen: Alternative to Gemini with similar capabilities
+
+## 3. Agent-Driven Execution Flow
+
+The command fully delegates to **universal-executor agent**, which autonomously:
+
+1. **Analyzes Project Structure**: Executes `get_modules_by_depth.sh` to understand architecture
+2. **Loads Documentation**: Reads CLAUDE.md, README.md and other key docs
+3. **Extracts Keywords**: Derives core keywords from task description
+4. **Discovers Files**: Uses MCP code-index or rg/find to locate relevant files
+5. **CLI Deep Analysis**: Executes Gemini/Qwen CLI for deep context analysis
+6. **Generates Content Package**: Returns structured JSON core content package
+
+## 4. Core Content Package Structure
+
+**Output Format** - Loaded into main thread memory for subsequent use:
+
+```json
+{
+  "task_context": "在当前前端基础上开发用户认证功能",
+  "keywords": ["前端", "用户", "认证", "auth", "login"],
+  "project_summary": {
+    "architecture": "TypeScript + React frontend with Vite build system",
+    "tech_stack": ["React", "TypeScript", "Vite", "TailwindCSS"],
+    "key_patterns": [
+      "State management via Context API",
+      "Functional components with Hooks pattern",
+      "API calls encapsulated in custom hooks"
+    ]
+  },
+  "relevant_files": [
+    {
+      "path": "src/components/Auth/LoginForm.tsx",
+      "relevance": "Existing login form component",
+      "priority": "high"
+    },
+    {
+      "path": "src/contexts/AuthContext.tsx",
+      "relevance": "Authentication state management context",
+      "priority": "high"
+    },
+    {
+      "path": "CLAUDE.md",
+      "relevance": "Project development standards",
+      "priority": "high"
+    }
+  ],
+  "integration_points": [
+    "Must integrate with existing AuthContext",
+    "Follow component organization pattern: src/components/[Feature]/",
+    "API calls should use src/hooks/useApi.ts wrapper"
+  ],
+  "constraints": [
+    "Maintain backward compatibility",
+    "Follow TypeScript strict mode",
+    "Use existing UI component library"
+  ]
+}
+```
+
+## 5. Agent Invocation
+
+```javascript
+Task(
+  subagent_type="universal-executor",
+  description="Load project memory: ${task_description}",
+  prompt=`
+## Mission: Load Project Memory Context
+
+**Task**: Load project memory context for: "${task_description}"
+**Mode**: analysis
+**Tool Preference**: ${tool || 'gemini'}
+
+## Execution Steps
+
+### Step 1: Foundation Analysis
+
+1. **Project Structure**
+   \`\`\`bash
+   bash(~/.claude/scripts/get_modules_by_depth.sh)
+   \`\`\`
+
+2. **Core Documentation**
+   \`\`\`javascript
+   Read(CLAUDE.md)
+   Read(README.md)
+   \`\`\`
+
+### Step 2: Keyword Extraction & File Discovery
+
+1. Extract core keywords from task description
+2. Discover relevant files using ripgrep and find:
+   \`\`\`bash
+   # Find files by name
+   find . -name "*{keyword}*" -type f
+
+   # Search content with ripgrep
+   rg "{keyword}" --type ts --type md -C 2
+   rg -l "{keyword}" --type ts --type md  # List files only
+   \`\`\`
+
+### Step 3: Deep Analysis via CLI
+
+Execute Gemini/Qwen CLI for deep analysis (saves main thread tokens):
+
+\`\`\`bash
+cd . && ${tool} -p "
+PURPOSE: Extract project core context for task: ${task_description}
+TASK: Analyze project architecture, tech stack, key patterns, relevant files
+MODE: analysis
+CONTEXT: @CLAUDE.md,README.md @${discovered_files}
+EXPECTED: Structured project summary and integration point analysis
+RULES:
+- Focus on task-relevant core information
+- Identify key architecture patterns and technical constraints
+- Extract integration points and development standards
+- Output concise, structured format
+"
+\`\`\`
+
+### Step 4: Generate Core Content Package
+
+Generate structured JSON content package (format shown above)
+
+**Required Fields**:
+- task_context: Original task description
+- keywords: Extracted keyword array
+- project_summary: Architecture, tech stack, key patterns
+- relevant_files: File list with path, relevance, priority
+- integration_points: Integration guidance
+- constraints: Development constraints
+
+### Step 5: Return Content Package
+
+Return JSON content package as final output for main thread to load into memory.
+
+## Quality Checklist
+
+Before returning:
+- [ ] Valid JSON format
+- [ ] All required fields complete
+- [ ] relevant_files contains 3-10 files minimum
+- [ ] project_summary accurately reflects architecture
+- [ ] integration_points clearly specify integration paths
+- [ ] keywords accurately extracted (3-8 keywords)
+- [ ] Content concise, avoiding redundancy (< 5KB total)
+
+  `
+)
+```
+
+## 6. Usage Examples
+
+### Example 1: Load Context for New Feature
+
+```bash
+/memory:load "在当前前端基础上开发用户认证功能"
+```
+
+**Agent Execution**:
+1. Analyzes project structure (`get_modules_by_depth.sh`)
+2. Reads CLAUDE.md, README.md
+3. Extracts keywords: ["前端", "用户", "认证", "auth"]
+4. Uses MCP to search relevant files
+5. Executes Gemini CLI for deep analysis
+6. Returns core content package
+
+**Returned Package** (loaded into memory):
+```json
+{
+  "task_context": "在当前前端基础上开发用户认证功能",
+  "keywords": ["前端", "认证", "auth", "login"],
+  "project_summary": { ... },
+  "relevant_files": [ ... ],
+  "integration_points": [ ... ],
+  "constraints": [ ... ]
+}
+```
+
+### Example 2: Using Qwen Tool
+
+```bash
+/memory:load --tool qwen -p "重构支付模块API"
+```
+
+Agent uses Qwen CLI for analysis, returns same structured package.
+
+### Example 3: Bug Fix Context
+
+```bash
+/memory:load "修复登录验证错误"
+```
+
+Returns core context related to login validation, including test files and validation logic.
+
+### Memory Persistence
+
+- **Session-Scoped**: Content package valid for current session
+- **Subsequent Reference**: All subsequent agents/commands can access
+- **Reload Required**: New sessions need to re-execute /memory:load
+
+## 8. Notes
+
+- **Read-Only**: Does not modify any code, pure analysis
+- **Token Optimization**: CLI analysis executed within agent, saves main thread tokens
+- **Memory Loading**: Returned JSON loaded directly into main thread memory
+- **Subsequent Use**: Other commands/agents can reference this package for development
+- **Session-Level**: Content package valid for current session

.claude/commands/memory/skill-memory.md

@@ -0,0 +1,534 @@
+---
+name: skill-memory
+description: Generate SKILL package index from project documentation
+argument-hint: "[path] [--tool <gemini|qwen|codex>] [--regenerate] [--mode <full|partial>] [--cli-execute]"
+allowed-tools: SlashCommand(*), TodoWrite(*), Bash(*), Read(*), Write(*)
+---
+
+# Memory SKILL Package Generator
+
+## Orchestrator Role
+
+**Pure Orchestrator**: Execute documentation generation workflow, then generate SKILL.md index. Does NOT create task JSON files.
+
+**Auto-Continue Workflow**: This command runs **fully autonomously** once triggered. Each phase completes and automatically triggers the next phase without user interaction.
+
+**Execution Paths**:
+- **Full Path**: All 4 phases (no existing docs OR `--regenerate` specified)
+- **Skip Path**: Phase 1 → Phase 4 (existing docs found AND no `--regenerate` flag)
+- **Phase 4 Always Executes**: SKILL.md index is never skipped, always generated or updated
+
+## Core Rules
+
+1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 execution
+2. **No Task JSON**: This command does not create task JSON files - delegates to /memory:docs
+3. **Parse Every Output**: Extract required data from each command output (session_id, task_count, file paths)
+4. **Auto-Continue**: After completing each phase, update TodoWrite and immediately execute next phase
+5. **Track Progress**: Update TodoWrite after EVERY phase completion before starting next phase
+6. **Direct Generation**: Phase 4 directly generates SKILL.md using Write tool
+7. **No Manual Steps**: User should never be prompted for decisions between phases
+
+---
+
+## 4-Phase Execution
+
+### Phase 1: Prepare Arguments
+
+**Goal**: Parse command arguments and check existing documentation
+
+**Step 1: Get Target Path and Project Name**
+```bash
+# Get current directory (or use provided path)
+bash(pwd)
+
+# Get project name from directory
+bash(basename "$(pwd)")
+
+# Get project root
+bash(git rev-parse --show-toplevel 2>/dev/null || pwd)
+```
+
+**Output**:
+- `target_path`: `/d/my_project`
+- `project_name`: `my_project`
+- `project_root`: `/d/my_project`
+
+**Step 2: Set Default Parameters**
+```bash
+# Default values (use these unless user specifies otherwise):
+# - tool: "gemini"
+# - mode: "full"
+# - regenerate: false (no --regenerate flag)
+# - cli_execute: false (no --cli-execute flag)
+```
+
+**Step 3: Check Existing Documentation**
+```bash
+# Check if docs directory exists
+bash(test -d .workflow/docs/my_project && echo "exists" || echo "not_exists")
+
+# Count existing documentation files
+bash(find .workflow/docs/my_project -name "*.md" 2>/dev/null | wc -l || echo 0)
+```
+
+**Output**:
+- `docs_exists`: `exists` or `not_exists`
+- `existing_docs`: `5` (or `0` if no docs)
+
+**Step 4: Determine Execution Path**
+
+**Decision Logic**:
+```javascript
+if (existing_docs > 0 && !regenerate_flag) {
+  // Documentation exists and no regenerate flag
+  SKIP_DOCS_GENERATION = true
+  message = "Documentation already exists, skipping Phase 2 and Phase 3. Use --regenerate to force regeneration."
+} else if (regenerate_flag) {
+  // Force regeneration: delete existing docs
+  bash(rm -rf .workflow/docs/my_project 2>/dev/null || true)
+  SKIP_DOCS_GENERATION = false
+  message = "Regenerating documentation from scratch."
+} else {
+  // No existing docs
+  SKIP_DOCS_GENERATION = false
+  message = "No existing documentation found, generating new documentation."
+}
+```
+
+**Summary Variables**:
+- `PROJECT_NAME`: `my_project`
+- `TARGET_PATH`: `/d/my_project`
+- `DOCS_PATH`: `.workflow/docs/my_project`
+- `TOOL`: `gemini` (default) or user-specified
+- `MODE`: `full` (default) or user-specified
+- `CLI_EXECUTE`: `false` (default) or `true` if --cli-execute flag
+- `REGENERATE`: `false` (default) or `true` if --regenerate flag
+- `EXISTING_DOCS`: Count of existing documentation files
+- `SKIP_DOCS_GENERATION`: `true` if skipping Phase 2/3, `false` otherwise
+
+**Completion & TodoWrite**:
+- If `SKIP_DOCS_GENERATION = true`: Mark phase 1 completed, phase 2&3 completed (skipped), phase 4 in_progress
+- If `SKIP_DOCS_GENERATION = false`: Mark phase 1 completed, phase 2 in_progress
+
+**Next Action**:
+- If skipping: Display skip message → Jump to Phase 4 (SKILL.md generation)
+- If not skipping: Display preparation results → Continue to Phase 2 (documentation planning)
+
+---
+
+### Phase 2: Call /memory:docs
+
+**Skip Condition**: This phase is **skipped if SKIP_DOCS_GENERATION = true** (documentation already exists without --regenerate flag)
+
+**Goal**: Trigger documentation generation workflow
+
+**Command**:
+```bash
+SlashCommand(command="/memory:docs [targetPath] --tool [tool] --mode [mode] [--cli-execute]")
+```
+
+**Example**:
+```bash
+/memory:docs /d/my_app --tool gemini --mode full
+/memory:docs /d/my_app --tool gemini --mode full --cli-execute
+```
+
+**Note**: The `--regenerate` flag is handled in Phase 1 by deleting existing documentation. This command always calls `/memory:docs` without the regenerate flag, relying on docs.md's built-in update detection.
+
+**Parse Output**:
+- Extract session ID: `WFS-docs-[timestamp]` (store as `docsSessionId`)
+- Extract task count (store as `taskCount`)
+
+**Completion Criteria**:
+- `/memory:docs` command executed successfully
+- Session ID extracted and stored
+- Task count retrieved
+- Task files created in `.workflow/[docsSessionId]/.task/`
+- workflow-session.json exists
+
+**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
+
+**Next Action**: Display docs planning results (session ID, task count) → Auto-continue to Phase 3
+
+---
+
+### Phase 3: Execute Documentation Generation
+
+**Skip Condition**: This phase is **skipped if SKIP_DOCS_GENERATION = true** (documentation already exists without --regenerate flag)
+
+**Goal**: Execute documentation generation tasks
+
+**Command**:
+```bash
+SlashCommand(command="/workflow:execute")
+```
+
+**Note**: `/workflow:execute` automatically discovers active session from Phase 2
+
+**Completion Criteria**:
+- `/workflow:execute` command executed successfully
+- Documentation files generated in `.workflow/docs/[projectName]/`
+- All tasks marked as completed in session
+- At minimum: module documentation files exist (API.md and/or README.md)
+- For full mode: Project README, ARCHITECTURE, EXAMPLES files generated
+
+**TodoWrite**: Mark phase 3 completed, phase 4 in_progress
+
+**Next Action**: Display execution results (file count, module count) → Auto-continue to Phase 4
+
+---
+
+### Phase 4: Generate SKILL.md Index
+
+**Note**: This phase is **NEVER skipped** - it always executes to generate or update the SKILL index.
+
+**Step 1: Read Key Files** (Use Read tool)
+- `.workflow/docs/{project_name}/README.md` (required)
+- `.workflow/docs/{project_name}/ARCHITECTURE.md` (optional)
+
+**Step 2: Discover Structure**
+```bash
+bash(find .workflow/docs/{project_name} -name "*.md" | sed 's|.workflow/docs/{project_name}/||' | awk -F'/' '{if(NF>=2) print $1"/"$2}' | sort -u)
+```
+
+**Step 3: Generate Intelligent Description**
+
+Extract from README + structure: Function (capabilities), Modules (names), Keywords (API/CLI/auth/etc.)
+
+**Format**: `{Project} {core capabilities} (located at {project_path}). Load this SKILL when analyzing, modifying, or learning about {domain_description} or files under this path, especially when no relevant context exists in memory.`
+
+**Key Elements**:
+- **Path Reference**: Use `TARGET_PATH` from Phase 1 for precise location identification
+- **Domain Description**: Extract human-readable domain/feature area from README (e.g., "workflow management", "thermal modeling")
+- **Trigger Optimization**: Include project path, emphasize "especially when no relevant context exists in memory"
+- **Action Coverage**: analyzing (分析), modifying (修改), learning (了解)
+
+**Example**: "Workflow orchestration system with CLI tools and documentation generation (located at /d/Claude_dms3). Load this SKILL when analyzing, modifying, or learning about workflow management or files under this path, especially when no relevant context exists in memory."
+
+**Step 4: Write SKILL.md** (Use Write tool)
+```bash
+bash(mkdir -p .claude/skills/{project_name})
+```
+
+`.claude/skills/{project_name}/SKILL.md`:
+```yaml
+---
+name: {project_name}
+description: {intelligent description from Step 3}
+version: 1.0.0
+---
+# {Project Name} SKILL Package
+
+## Documentation: `../../../.workflow/docs/{project_name}/`
+
+## Progressive Loading
+### Level 0: Quick Start (~2K)
+- [README](../../../.workflow/docs/{project_name}/README.md)
+### Level 1: Core Modules (~8K)
+{Module READMEs}
+### Level 2: Complete (~25K)
+All modules + [Architecture](../../../.workflow/docs/{project_name}/ARCHITECTURE.md)
+### Level 3: Deep Dive (~40K)
+Everything + [Examples](../../../.workflow/docs/{project_name}/EXAMPLES.md)
+```
+
+**Completion Criteria**:
+- SKILL.md file created at `.claude/skills/{project_name}/SKILL.md`
+- Intelligent description generated from documentation
+- Progressive loading levels (0-3) properly structured
+- Module index includes all documented modules
+- All file references use relative paths
+
+**TodoWrite**: Mark phase 4 completed
+
+**Final Action**: Report completion summary to user
+
+**Return to User**:
+```
+SKILL Package Generation Complete
+
+Project: {project_name}
+Documentation: .workflow/docs/{project_name}/ ({doc_count} files)
+SKILL Index: .claude/skills/{project_name}/SKILL.md
+
+Generated:
+- {task_count} documentation tasks completed
+- SKILL.md with progressive loading (4 levels)
+- Module index with {module_count} modules
+
+Usage:
+- Load Level 0: Quick project overview (~2K tokens)
+- Load Level 1: Core modules (~8K tokens)
+- Load Level 2: Complete docs (~25K tokens)
+- Load Level 3: Everything (~40K tokens)
+```
+
+---
+
+## Implementation Details
+
+### Critical Rules
+
+1. **No User Prompts Between Phases**: Never ask user questions or wait for input between phases
+2. **Immediate Phase Transition**: After TodoWrite update, immediately execute next phase command
+3. **Status-Driven Execution**: Check TodoList status after each phase:
+   - If next task is "pending" → Mark it "in_progress" and execute
+   - If all tasks are "completed" → Report final summary
+4. **Phase Completion Pattern**:
+   ```
+   Phase N completes → Update TodoWrite (N=completed, N+1=in_progress) → Execute Phase N+1
+   ```
+
+### TodoWrite Patterns
+
+#### Initialization (Before Phase 1)
+
+**FIRST ACTION**: Create TodoList with all 4 phases
+```javascript
+TodoWrite({todos: [
+  {"content": "Parse arguments and prepare", "status": "in_progress", "activeForm": "Parsing arguments"},
+  {"content": "Call /memory:docs to plan documentation", "status": "pending", "activeForm": "Calling /memory:docs"},
+  {"content": "Execute documentation generation", "status": "pending", "activeForm": "Executing documentation"},
+  {"content": "Generate SKILL.md index", "status": "pending", "activeForm": "Generating SKILL.md"}
+]})
+```
+
+**SECOND ACTION**: Execute Phase 1 immediately
+
+#### Full Path (SKIP_DOCS_GENERATION = false)
+
+**After Phase 1**:
+```javascript
+TodoWrite({todos: [
+  {"content": "Parse arguments and prepare", "status": "completed", "activeForm": "Parsing arguments"},
+  {"content": "Call /memory:docs to plan documentation", "status": "in_progress", "activeForm": "Calling /memory:docs"},
+  {"content": "Execute documentation generation", "status": "pending", "activeForm": "Executing documentation"},
+  {"content": "Generate SKILL.md index", "status": "pending", "activeForm": "Generating SKILL.md"}
+]})
+// Auto-continue to Phase 2
+```
+
+**After Phase 2**:
+```javascript
+TodoWrite({todos: [
+  {"content": "Parse arguments and prepare", "status": "completed", "activeForm": "Parsing arguments"},
+  {"content": "Call /memory:docs to plan documentation", "status": "completed", "activeForm": "Calling /memory:docs"},
+  {"content": "Execute documentation generation", "status": "in_progress", "activeForm": "Executing documentation"},
+  {"content": "Generate SKILL.md index", "status": "pending", "activeForm": "Generating SKILL.md"}
+]})
+// Auto-continue to Phase 3
+```
+
+**After Phase 3**:
+```javascript
+TodoWrite({todos: [
+  {"content": "Parse arguments and prepare", "status": "completed", "activeForm": "Parsing arguments"},
+  {"content": "Call /memory:docs to plan documentation", "status": "completed", "activeForm": "Calling /memory:docs"},
+  {"content": "Execute documentation generation", "status": "completed", "activeForm": "Executing documentation"},
+  {"content": "Generate SKILL.md index", "status": "in_progress", "activeForm": "Generating SKILL.md"}
+]})
+// Auto-continue to Phase 4
+```
+
+**After Phase 4**:
+```javascript
+TodoWrite({todos: [
+  {"content": "Parse arguments and prepare", "status": "completed", "activeForm": "Parsing arguments"},
+  {"content": "Call /memory:docs to plan documentation", "status": "completed", "activeForm": "Calling /memory:docs"},
+  {"content": "Execute documentation generation", "status": "completed", "activeForm": "Executing documentation"},
+  {"content": "Generate SKILL.md index", "status": "completed", "activeForm": "Generating SKILL.md"}
+]})
+// Report completion summary to user
+```
+
+#### Skip Path (SKIP_DOCS_GENERATION = true)
+
+**After Phase 1** (detects existing docs, skips Phase 2 & 3):
+```javascript
+TodoWrite({todos: [
+  {"content": "Parse arguments and prepare", "status": "completed", "activeForm": "Parsing arguments"},
+  {"content": "Call /memory:docs to plan documentation", "status": "completed", "activeForm": "Calling /memory:docs"},
+  {"content": "Execute documentation generation", "status": "completed", "activeForm": "Executing documentation"},
+  {"content": "Generate SKILL.md index", "status": "in_progress", "activeForm": "Generating SKILL.md"}
+]})
+// Display skip message: "Documentation already exists, skipping Phase 2 and Phase 3. Use --regenerate to force regeneration."
+// Jump directly to Phase 4
+```
+
+**After Phase 4**:
+```javascript
+TodoWrite({todos: [
+  {"content": "Parse arguments and prepare", "status": "completed", "activeForm": "Parsing arguments"},
+  {"content": "Call /memory:docs to plan documentation", "status": "completed", "activeForm": "Calling /memory:docs"},
+  {"content": "Execute documentation generation", "status": "completed", "activeForm": "Executing documentation"},
+  {"content": "Generate SKILL.md index", "status": "completed", "activeForm": "Generating SKILL.md"}
+]})
+// Report completion summary to user
+```
+
+### Execution Flow Diagrams
+
+#### Full Path Flow
+```
+User triggers command
+  ↓
+[TodoWrite] Initialize 4 phases (Phase 1 = in_progress)
+  ↓
+[Execute] Phase 1: Parse arguments
+  ↓
+[TodoWrite] Phase 1 = completed, Phase 2 = in_progress
+  ↓
+[Execute] Phase 2: Call /memory:docs
+  ↓
+[TodoWrite] Phase 2 = completed, Phase 3 = in_progress
+  ↓
+[Execute] Phase 3: Call /workflow:execute
+  ↓
+[TodoWrite] Phase 3 = completed, Phase 4 = in_progress
+  ↓
+[Execute] Phase 4: Generate SKILL.md
+  ↓
+[TodoWrite] Phase 4 = completed
+  ↓
+[Report] Display completion summary
+```
+
+#### Skip Path Flow
+```
+User triggers command
+  ↓
+[TodoWrite] Initialize 4 phases (Phase 1 = in_progress)
+  ↓
+[Execute] Phase 1: Parse arguments, detect existing docs
+  ↓
+[TodoWrite] Phase 1 = completed, Phase 2&3 = completed (skipped), Phase 4 = in_progress
+  ↓
+[Display] Skip message: "Documentation already exists, skipping Phase 2 and Phase 3"
+  ↓
+[Execute] Phase 4: Generate SKILL.md (always runs)
+  ↓
+[TodoWrite] Phase 4 = completed
+  ↓
+[Report] Display completion summary
+```
+
+### Error Handling
+
+- If any phase fails, mark it as "in_progress" (not completed)
+- Report error details to user
+- Do NOT auto-continue to next phase on failure
+
+---
+
+## Parameters
+
+```bash
+/memory:skill-memory [path] [--tool <gemini|qwen|codex>] [--regenerate] [--mode <full|partial>] [--cli-execute]
+```
+
+- **path**: Target directory (default: current directory)
+- **--tool**: CLI tool for documentation (default: gemini)
+  - `gemini`: Comprehensive documentation
+  - `qwen`: Architecture analysis
+  - `codex`: Implementation validation
+- **--regenerate**: Force regenerate all documentation
+  - When enabled: Deletes existing `.workflow/docs/{project_name}/` before regeneration
+  - Ensures fresh documentation from source code
+- **--mode**: Documentation mode (default: full)
+  - `full`: Complete docs (modules + README + ARCHITECTURE + EXAMPLES)
+  - `partial`: Module docs only
+- **--cli-execute**: Enable CLI-based documentation generation (optional)
+  - When enabled: CLI generates docs directly in implementation_approach
+  - When disabled (default): Agent generates documentation content
+
+---
+
+## Examples
+
+### Example 1: Generate SKILL Package (Default)
+
+```bash
+/memory:skill-memory
+```
+
+**Workflow**:
+1. Phase 1: Detects current directory, checks existing docs
+2. Phase 2: Calls `/memory:docs . --tool gemini --mode full` (Agent Mode)
+3. Phase 3: Executes documentation generation via `/workflow:execute`
+4. Phase 4: Generates SKILL.md at `.claude/skills/{project_name}/SKILL.md`
+
+### Example 2: Regenerate with Qwen
+
+```bash
+/memory:skill-memory /d/my_app --tool qwen --regenerate
+```
+
+**Workflow**:
+1. Phase 1: Parses target path, detects regenerate flag, deletes existing docs
+2. Phase 2: Calls `/memory:docs /d/my_app --tool qwen --mode full`
+3. Phase 3: Executes documentation regeneration
+4. Phase 4: Generates updated SKILL.md
+
+### Example 3: Partial Mode (Modules Only)
+
+```bash
+/memory:skill-memory --mode partial
+```
+
+**Workflow**:
+1. Phase 1: Detects partial mode
+2. Phase 2: Calls `/memory:docs . --tool gemini --mode partial` (Agent Mode)
+3. Phase 3: Executes module documentation only
+4. Phase 4: Generates SKILL.md with module-only index
+
+### Example 4: CLI Execute Mode
+
+```bash
+/memory:skill-memory --cli-execute
+```
+
+**Workflow**:
+1. Phase 1: Detects CLI execute mode
+2. Phase 2: Calls `/memory:docs . --tool gemini --mode full --cli-execute` (CLI Mode)
+3. Phase 3: Executes CLI-based documentation generation
+4. Phase 4: Generates SKILL.md at `.claude/skills/{project_name}/SKILL.md`
+
+### Example 5: Skip Path (Existing Docs)
+
+```bash
+/memory:skill-memory
+```
+
+**Scenario**: Documentation already exists in `.workflow/docs/{project_name}/`
+
+**Workflow**:
+1. Phase 1: Detects existing docs (5 files), sets SKIP_DOCS_GENERATION = true
+2. Display: "Documentation already exists, skipping Phase 2 and Phase 3. Use --regenerate to force regeneration."
+3. Phase 4: Generates or updates SKILL.md index only (~5-10x faster)
+
+---
+
+## Benefits
+
+- **Pure Orchestrator**: No task JSON generation, delegates to /memory:docs
+- **Auto-Continue**: Autonomous 4-phase execution without user interaction
+- **Intelligent Skip**: Detects existing docs and skips regeneration for fast SKILL updates
+- **Always Fresh Index**: Phase 4 always executes to ensure SKILL.md stays synchronized
+- **Simplified**: ~70% less code than previous version
+- **Maintainable**: Changes to /memory:docs automatically apply
+- **Direct Generation**: Phase 4 directly writes SKILL.md
+- **Flexible**: Supports all /memory:docs options (tool, mode, cli-execute)
+
+## Architecture
+
+```
+skill-memory (orchestrator)
+  ├─ Phase 1: Prepare (bash commands, skip decision)
+  ├─ Phase 2: /memory:docs (task planning, skippable)
+  ├─ Phase 3: /workflow:execute (task execution, skippable)
+  └─ Phase 4: Write SKILL.md (direct file generation, always runs)
+
+No task JSON created by this command
+All documentation tasks managed by /memory:docs
+Smart skip logic: 5-10x faster when docs exist
+```

.claude/commands/memory/tech-research.md

@@ -0,0 +1,477 @@
+---
+name: tech-research
+description: Generate tech stack SKILL packages using Exa research via agent delegation
+argument-hint: "[session-id | tech-stack-name] [--regenerate] [--tool <gemini|qwen>]"
+allowed-tools: SlashCommand(*), TodoWrite(*), Bash(*), Read(*), Write(*), Task(*)
+---
+
+# Tech Stack Research SKILL Generator
+
+## Overview
+
+**Pure Orchestrator with Agent Delegation**: Prepares context paths and delegates ALL work to agent. Agent produces files directly.
+
+**Auto-Continue Workflow**: Runs fully autonomously once triggered. Each phase completes and automatically triggers the next phase.
+
+**Execution Paths**:
+- **Full Path**: All 3 phases (no existing SKILL OR `--regenerate` specified)
+- **Skip Path**: Phase 1 → Phase 3 (existing SKILL found AND no `--regenerate` flag)
+- **Phase 3 Always Executes**: SKILL index is always generated or updated
+
+**Agent Responsibility**:
+- Agent does ALL the work: context reading, Exa research, content synthesis, file writing
+- Orchestrator only provides context paths and waits for completion
+
+## Core Rules
+
+1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 execution
+2. **Context Path Delegation**: Pass session directory or tech stack name to agent, let agent do discovery
+3. **Agent Produces Files**: Agent directly writes all module files, orchestrator does NOT parse agent output
+4. **Auto-Continue**: After completing each phase, update TodoWrite and immediately execute next phase
+5. **No User Prompts**: Never ask user questions or wait for input between phases
+6. **Track Progress**: Update TodoWrite after EVERY phase completion before starting next phase
+7. **Lightweight Index**: Phase 3 only generates SKILL.md index by reading existing files
+
+---
+
+## 3-Phase Execution
+
+### Phase 1: Prepare Context Paths
+
+**Goal**: Detect input mode, prepare context paths for agent, check existing SKILL
+
+**Input Mode Detection**:
+```bash
+# Get input parameter
+input="$1"
+
+# Detect mode
+if [[ "$input" == WFS-* ]]; then
+  MODE="session"
+  SESSION_ID="$input"
+  CONTEXT_PATH=".workflow/${SESSION_ID}"
+else
+  MODE="direct"
+  TECH_STACK_NAME="$input"
+  CONTEXT_PATH="$input"  # Pass tech stack name as context
+fi
+```
+
+**Check Existing SKILL**:
+```bash
+# For session mode, peek at session to get tech stack name
+if [[ "$MODE" == "session" ]]; then
+  bash(test -f ".workflow/${SESSION_ID}/workflow-session.json")
+  Read(.workflow/${SESSION_ID}/workflow-session.json)
+  # Extract tech_stack_name (minimal extraction)
+fi
+
+# Normalize and check
+normalized_name=$(echo "$TECH_STACK_NAME" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
+bash(test -d ".claude/skills/${normalized_name}" && echo "exists" || echo "not_exists")
+bash(find ".claude/skills/${normalized_name}" -name "*.md" 2>/dev/null | wc -l || echo 0)
+```
+
+**Skip Decision**:
+```javascript
+if (existing_files > 0 && !regenerate_flag) {
+  SKIP_GENERATION = true
+  message = "Tech stack SKILL already exists, skipping Phase 2. Use --regenerate to force regeneration."
+} else if (regenerate_flag) {
+  bash(rm -rf ".claude/skills/${normalized_name}")
+  SKIP_GENERATION = false
+  message = "Regenerating tech stack SKILL from scratch."
+} else {
+  SKIP_GENERATION = false
+  message = "No existing SKILL found, generating new tech stack documentation."
+}
+```
+
+**Output Variables**:
+- `MODE`: `session` or `direct`
+- `SESSION_ID`: Session ID (if session mode)
+- `CONTEXT_PATH`: Path to session directory OR tech stack name
+- `TECH_STACK_NAME`: Extracted or provided tech stack name
+- `SKIP_GENERATION`: Boolean - whether to skip Phase 2
+
+**TodoWrite**:
+- If skipping: Mark phase 1 completed, phase 2 completed, phase 3 in_progress
+- If not skipping: Mark phase 1 completed, phase 2 in_progress
+
+---
+
+### Phase 2: Agent Produces All Files
+
+**Skip Condition**: Skipped if `SKIP_GENERATION = true`
+
+**Goal**: Delegate EVERYTHING to agent - context reading, Exa research, content synthesis, and file writing
+
+**Agent Task Specification**:
+
+```
+Task(
+  subagent_type: "general-purpose",
+  description: "Generate tech stack SKILL: {CONTEXT_PATH}",
+  prompt: "
+Generate a complete tech stack SKILL package with Exa research.
+
+**Context Provided**:
+- Mode: {MODE}
+- Context Path: {CONTEXT_PATH}
+
+**Templates Available**:
+- Module Format: ~/.claude/workflows/cli-templates/prompts/tech/tech-module-format.txt
+- SKILL Index: ~/.claude/workflows/cli-templates/prompts/tech/tech-skill-index.txt
+
+**Your Responsibilities**:
+
+1. **Extract Tech Stack Information**:
+
+   IF MODE == 'session':
+     - Read `.workflow/{SESSION_ID}/workflow-session.json`
+     - Read `.workflow/{SESSION_ID}/.process/context-package.json`
+     - Extract tech_stack: {language, frameworks, libraries}
+     - Build tech stack name: \"{language}-{framework1}-{framework2}\"
+     - Example: \"typescript-react-nextjs\"
+
+   IF MODE == 'direct':
+     - Tech stack name = CONTEXT_PATH
+     - Parse composite: split by '-' delimiter
+     - Example: \"typescript-react-nextjs\" → [\"typescript\", \"react\", \"nextjs\"]
+
+2. **Execute Exa Research** (4-6 parallel queries):
+
+   Base Queries (always execute):
+   - mcp__exa__get_code_context_exa(query: \"{tech} core principles best practices 2025\", tokensNum: 8000)
+   - mcp__exa__get_code_context_exa(query: \"{tech} common patterns architecture examples\", tokensNum: 7000)
+   - mcp__exa__web_search_exa(query: \"{tech} configuration setup tooling 2025\", numResults: 5)
+   - mcp__exa__get_code_context_exa(query: \"{tech} testing strategies\", tokensNum: 5000)
+
+   Component Queries (if composite):
+   - For each additional component:
+     mcp__exa__get_code_context_exa(query: \"{main_tech} {component} integration\", tokensNum: 5000)
+
+3. **Read Module Format Template**:
+
+   Read template for structure guidance:
+   ```bash
+   Read(~/.claude/workflows/cli-templates/prompts/tech/tech-module-format.txt)
+   ```
+
+4. **Synthesize Content into 6 Modules**:
+
+   Follow template structure from tech-module-format.txt:
+   - **principles.md** - Core concepts, philosophies (~3K tokens)
+   - **patterns.md** - Implementation patterns with code examples (~5K tokens)
+   - **practices.md** - Best practices, anti-patterns, pitfalls (~4K tokens)
+   - **testing.md** - Testing strategies, frameworks (~3K tokens)
+   - **config.md** - Setup, configuration, tooling (~3K tokens)
+   - **frameworks.md** - Framework integration (only if composite, ~4K tokens)
+
+   Each module follows template format:
+   - Frontmatter (YAML)
+   - Main sections with clear headings
+   - Code examples from Exa research
+   - Best practices sections
+   - References to Exa sources
+
+5. **Write Files Directly**:
+
+   ```javascript
+   // Create directory
+   bash(mkdir -p \".claude/skills/{tech_stack_name}\")
+
+   // Write each module file using Write tool
+   Write({ file_path: \".claude/skills/{tech_stack_name}/principles.md\", content: ... })
+   Write({ file_path: \".claude/skills/{tech_stack_name}/patterns.md\", content: ... })
+   Write({ file_path: \".claude/skills/{tech_stack_name}/practices.md\", content: ... })
+   Write({ file_path: \".claude/skills/{tech_stack_name}/testing.md\", content: ... })
+   Write({ file_path: \".claude/skills/{tech_stack_name}/config.md\", content: ... })
+   // Write frameworks.md only if composite
+
+   // Write metadata.json
+   Write({
+     file_path: \".claude/skills/{tech_stack_name}/metadata.json\",
+     content: JSON.stringify({
+       tech_stack_name,
+       components,
+       is_composite,
+       generated_at: timestamp,
+       source: \"exa-research\",
+       research_summary: { total_queries, total_sources }
+     })
+   })
+   ```
+
+6. **Report Completion**:
+
+   Provide summary:
+   - Tech stack name
+   - Files created (count)
+   - Exa queries executed
+   - Sources consulted
+
+**CRITICAL**:
+- MUST read external template files before generating content (step 3 for modules, step 4 for index)
+- You have FULL autonomy - read files, execute Exa, synthesize content, write files
+- Do NOT return JSON or structured data - produce actual .md files
+- Handle errors gracefully (Exa failures, missing files, template read failures)
+- If tech stack cannot be determined, ask orchestrator to clarify
+  "
+)
+```
+
+**Completion Criteria**:
+- Agent task executed successfully
+- 5-6 modular files written to `.claude/skills/{tech_stack_name}/`
+- metadata.json written
+- Agent reports completion
+
+**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
+
+---
+
+### Phase 3: Generate SKILL.md Index
+
+**Note**: This phase **ALWAYS executes** - generates or updates the SKILL index.
+
+**Goal**: Read generated module files and create SKILL.md index with loading recommendations
+
+**Steps**:
+
+1. **Verify Generated Files**:
+   ```bash
+   bash(find ".claude/skills/${TECH_STACK_NAME}" -name "*.md" -type f | sort)
+   ```
+
+2. **Read metadata.json**:
+   ```javascript
+   Read(.claude/skills/${TECH_STACK_NAME}/metadata.json)
+   // Extract: tech_stack_name, components, is_composite, research_summary
+   ```
+
+3. **Read Module Headers** (optional, first 20 lines):
+   ```javascript
+   Read(.claude/skills/${TECH_STACK_NAME}/principles.md, limit: 20)
+   // Repeat for other modules
+   ```
+
+4. **Read SKILL Index Template**:
+
+   ```javascript
+   Read(~/.claude/workflows/cli-templates/prompts/tech/tech-skill-index.txt)
+   ```
+
+5. **Generate SKILL.md Index**:
+
+   Follow template from tech-skill-index.txt with variable substitutions:
+   - `{TECH_STACK_NAME}`: From metadata.json
+   - `{MAIN_TECH}`: Primary technology
+   - `{ISO_TIMESTAMP}`: Current timestamp
+   - `{QUERY_COUNT}`: From research_summary
+   - `{SOURCE_COUNT}`: From research_summary
+   - Conditional sections for composite tech stacks
+
+   Template provides structure for:
+   - Frontmatter with metadata
+   - Overview and tech stack description
+   - Module organization (Core/Practical/Config sections)
+   - Loading recommendations (Quick/Implementation/Complete)
+   - Usage guidelines and auto-trigger keywords
+   - Research metadata and version history
+
+6. **Write SKILL.md**:
+   ```javascript
+   Write({
+     file_path: `.claude/skills/${TECH_STACK_NAME}/SKILL.md`,
+     content: generatedIndexMarkdown
+   })
+   ```
+
+**Completion Criteria**:
+- SKILL.md index written
+- All module files verified
+- Loading recommendations included
+
+**TodoWrite**: Mark phase 3 completed
+
+**Final Report**:
+```
+Tech Stack SKILL Package Complete
+
+Tech Stack: {TECH_STACK_NAME}
+Location: .claude/skills/{TECH_STACK_NAME}/
+
+Files: SKILL.md + 5-6 modules + metadata.json
+Exa Research: {queries} queries, {sources} sources
+
+Usage: Skill(command: "{TECH_STACK_NAME}")
+```
+
+---
+
+## Implementation Details
+
+### TodoWrite Patterns
+
+**Initialization** (Before Phase 1):
+```javascript
+TodoWrite({todos: [
+  {"content": "Prepare context paths", "status": "in_progress", "activeForm": "Preparing context paths"},
+  {"content": "Agent produces all module files", "status": "pending", "activeForm": "Agent producing files"},
+  {"content": "Generate SKILL.md index", "status": "pending", "activeForm": "Generating SKILL index"}
+]})
+```
+
+**Full Path** (SKIP_GENERATION = false):
+```javascript
+// After Phase 1
+TodoWrite({todos: [
+  {"content": "Prepare context paths", "status": "completed", ...},
+  {"content": "Agent produces all module files", "status": "in_progress", ...},
+  {"content": "Generate SKILL.md index", "status": "pending", ...}
+]})
+
+// After Phase 2
+TodoWrite({todos: [
+  {"content": "Prepare context paths", "status": "completed", ...},
+  {"content": "Agent produces all module files", "status": "completed", ...},
+  {"content": "Generate SKILL.md index", "status": "in_progress", ...}
+]})
+
+// After Phase 3
+TodoWrite({todos: [
+  {"content": "Prepare context paths", "status": "completed", ...},
+  {"content": "Agent produces all module files", "status": "completed", ...},
+  {"content": "Generate SKILL.md index", "status": "completed", ...}
+]})
+```
+
+**Skip Path** (SKIP_GENERATION = true):
+```javascript
+// After Phase 1 (skip Phase 2)
+TodoWrite({todos: [
+  {"content": "Prepare context paths", "status": "completed", ...},
+  {"content": "Agent produces all module files", "status": "completed", ...},  // Skipped
+  {"content": "Generate SKILL.md index", "status": "in_progress", ...}
+]})
+```
+
+### Execution Flow
+
+**Full Path**:
+```
+User → TodoWrite Init → Phase 1 (prepare) → Phase 2 (agent writes files) → Phase 3 (write index) → Report
+```
+
+**Skip Path**:
+```
+User → TodoWrite Init → Phase 1 (detect existing) → Phase 3 (update index) → Report
+```
+
+### Error Handling
+
+**Phase 1 Errors**:
+- Invalid session ID: Report error, verify session exists
+- Missing context-package: Warn, fall back to direct mode
+- No tech stack detected: Ask user to specify tech stack name
+
+**Phase 2 Errors (Agent)**:
+- Agent task fails: Retry once, report if fails again
+- Exa API failures: Agent handles internally with retries
+- Incomplete results: Warn user, proceed with partial data if minimum sections available
+
+**Phase 3 Errors**:
+- Write failures: Report which files failed
+- Missing files: Note in SKILL.md, suggest regeneration
+
+---
+
+## Parameters
+
+```bash
+/memory:tech-research [session-id | "tech-stack-name"] [--regenerate] [--tool <gemini|qwen>]
+```
+
+**Arguments**:
+- **session-id | tech-stack-name**: Input source (auto-detected by WFS- prefix)
+  - Session mode: `WFS-user-auth-v2` - Extract tech stack from workflow
+  - Direct mode: `"typescript"`, `"typescript-react-nextjs"` - User specifies
+- **--regenerate**: Force regenerate existing SKILL (deletes and recreates)
+- **--tool**: Reserved for future CLI integration (default: gemini)
+
+---
+
+## Examples
+
+**Generated File Structure** (for all examples):
+```
+.claude/skills/{tech-stack}/
+├── SKILL.md           # Index (Phase 3)
+├── principles.md      # Agent (Phase 2)
+├── patterns.md        # Agent
+├── practices.md       # Agent
+├── testing.md         # Agent
+├── config.md          # Agent
+├── frameworks.md      # Agent (if composite)
+└── metadata.json      # Agent
+```
+
+### Direct Mode - Single Stack
+
+```bash
+/memory:tech-research "typescript"
+```
+
+**Workflow**:
+1. Phase 1: Detects direct mode, checks existing SKILL
+2. Phase 2: Agent executes 4 Exa queries, writes 5 modules
+3. Phase 3: Generates SKILL.md index
+
+### Direct Mode - Composite Stack
+
+```bash
+/memory:tech-research "typescript-react-nextjs"
+```
+
+**Workflow**:
+1. Phase 1: Decomposes into ["typescript", "react", "nextjs"]
+2. Phase 2: Agent executes 6 Exa queries (4 base + 2 components), writes 6 modules (adds frameworks.md)
+3. Phase 3: Generates SKILL.md index with framework integration
+
+### Session Mode - Extract from Workflow
+
+```bash
+/memory:tech-research WFS-user-auth-20251104
+```
+
+**Workflow**:
+1. Phase 1: Reads session, extracts tech stack: `python-fastapi-sqlalchemy`
+2. Phase 2: Agent researches Python + FastAPI + SQLAlchemy, writes 6 modules
+3. Phase 3: Generates SKILL.md index
+
+### Regenerate Existing
+
+```bash
+/memory:tech-research "react" --regenerate
+```
+
+**Workflow**:
+1. Phase 1: Deletes existing SKILL due to --regenerate
+2. Phase 2: Agent executes fresh Exa research (latest 2025 practices)
+3. Phase 3: Generates updated SKILL.md
+
+### Skip Path - Fast Update
+
+```bash
+/memory:tech-research "python"
+```
+
+**Scenario**: SKILL already exists with 7 files
+
+**Workflow**:
+1. Phase 1: Detects existing SKILL, sets SKIP_GENERATION = true
+2. Phase 2: **SKIPPED**
+3. Phase 3: Updates SKILL.md index only (5-10x faster)
+
+

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

@@ -0,0 +1,333 @@
+---
+name: update-full
+description: Complete project-wide CLAUDE.md documentation update with agent-based parallel execution and tool fallback
+argument-hint: "[--tool gemini|qwen|codex] [--path <directory>]"
+---
+
+# Full Documentation Update (/memory:update-full)
+
+## Overview
+
+Orchestrates project-wide CLAUDE.md updates using batched agent execution with automatic tool fallback and 3-layer architecture support.
+
+**Parameters**:
+- `--tool <gemini|qwen|codex>`: Primary tool (default: gemini)
+- `--path <directory>`: Target specific directory (default: entire project)
+
+**Execution Flow**: Discovery → Plan Presentation → Execution → Safety Verification
+
+## 3-Layer Architecture & Auto-Strategy Selection
+
+### Layer Definition & Strategy Assignment
+
+| Layer | Depth | Strategy | Purpose | Context Pattern |
+|-------|-------|----------|---------|----------------|
+| **Layer 3** (Deepest) | ≥3 | `multi-layer` | Handle unstructured files, generate docs for all subdirectories | `@**/*` (all files) |
+| **Layer 2** (Middle) | 1-2 | `single-layer` | Aggregate from children + current code | `@*/CLAUDE.md @*.{ts,tsx,js,...}` |
+| **Layer 1** (Top) | 0 | `single-layer` | Aggregate from children + current code | `@*/CLAUDE.md @*.{ts,tsx,js,...}` |
+
+**Update Direction**: Layer 3 → Layer 2 → Layer 1 (bottom-up dependency flow)
+
+**Strategy Auto-Selection**: Strategies are automatically determined by directory depth - no user configuration needed.
+
+### Strategy Details
+
+#### Multi-Layer Strategy (Layer 3 Only)
+- **Use Case**: Deepest directories with unstructured file layouts
+- **Behavior**: Generates CLAUDE.md for current directory AND each subdirectory containing files
+- **Context**: All files in current directory tree (`@**/*`)
+- **Benefits**: Creates foundation documentation for upper layers to reference
+
+#### Single-Layer Strategy (Layers 1-2)
+- **Use Case**: Upper layers that aggregate from existing documentation
+- **Behavior**: Generates CLAUDE.md only for current directory
+- **Context**: Direct children CLAUDE.md files + current directory code files
+- **Benefits**: Minimal context consumption, clear layer separation
+
+### Example Flow
+```
+src/auth/handlers/ (depth 3) → MULTI-LAYER STRATEGY
+  CONTEXT: @**/* (all files in handlers/ and subdirs)
+  GENERATES: ./CLAUDE.md + CLAUDE.md in each subdir with files
+  ↓
+src/auth/ (depth 2) → SINGLE-LAYER STRATEGY
+  CONTEXT: @*/CLAUDE.md @*.ts (handlers/CLAUDE.md + current code)
+  GENERATES: ./CLAUDE.md only
+  ↓
+src/ (depth 1) → SINGLE-LAYER STRATEGY
+  CONTEXT: @*/CLAUDE.md (auth/CLAUDE.md, utils/CLAUDE.md)
+  GENERATES: ./CLAUDE.md only
+  ↓
+./ (depth 0) → SINGLE-LAYER STRATEGY
+  CONTEXT: @*/CLAUDE.md (src/CLAUDE.md, tests/CLAUDE.md)
+  GENERATES: ./CLAUDE.md only
+```
+
+## Core Execution Rules
+
+1. **Analyze First**: Git cache + module discovery before updates
+2. **Wait for Approval**: Present plan, no execution without user confirmation
+3. **Execution Strategy**:
+   - **<20 modules**: Direct parallel execution (max 4 concurrent per layer)
+   - **≥20 modules**: Agent batch processing (4 modules/agent, 73% overhead reduction)
+4. **Tool Fallback**: Auto-retry with fallback tools on failure
+5. **Layer Sequential**: Process layers 3→2→1 (bottom-up), parallel batches within layer
+6. **Safety Check**: Verify only CLAUDE.md files modified
+7. **Layer-based Grouping**: Group modules by LAYER (not depth) for execution
+
+## Tool Fallback Hierarchy
+
+```javascript
+--tool gemini  →  [gemini, qwen, codex]  // default
+--tool qwen    →  [qwen, gemini, codex]
+--tool codex   →  [codex, gemini, qwen]
+```
+
+**Trigger**: Non-zero exit code from update script
+
+| Tool   | Best For                       | Fallback To    |
+|--------|--------------------------------|----------------|
+| gemini | Documentation, patterns        | qwen → codex   |
+| qwen   | Architecture, system design    | gemini → codex |
+| codex  | Implementation, code quality   | gemini → qwen  |
+
+## Execution Phases
+
+### Phase 1: Discovery & Analysis
+
+```bash
+# Cache git changes
+bash(git add -A 2>/dev/null || true)
+
+# Get module structure
+bash(~/.claude/scripts/get_modules_by_depth.sh list)
+# OR with --path
+bash(cd <target-path> && ~/.claude/scripts/get_modules_by_depth.sh list)
+```
+
+**Parse output** `depth:N|path:<PATH>|...` to extract module paths and count.
+
+**Smart filter**: Auto-detect and skip tests/build/config/docs based on project tech stack.
+
+### Phase 2: Plan Presentation
+
+**For <20 modules**:
+```
+Update Plan:
+  Tool: gemini (fallback: qwen → codex)
+  Total: 7 modules
+  Execution: Direct parallel (< 20 modules threshold)
+
+  Will update:
+  - ./core/interfaces (12 files) - depth 2 [Layer 2] - single-layer strategy
+  - ./core (22 files) - depth 1 [Layer 2] - single-layer strategy
+  - ./models (9 files) - depth 1 [Layer 2] - single-layer strategy
+  - ./utils (12 files) - depth 1 [Layer 2] - single-layer strategy
+  - . (5 files) - depth 0 [Layer 1] - single-layer strategy
+
+  Context Strategy (Auto-Selected):
+  - Layer 2 (depth 1-2): @*/CLAUDE.md + current code files
+  - Layer 1 (depth 0): @*/CLAUDE.md + current code files
+
+  Auto-skipped: ./tests, __pycache__, setup.py (15 paths)
+  Execution order: Layer 2 → Layer 1
+  Estimated time: ~5-10 minutes
+
+  Confirm execution? (y/n)
+```
+
+**For ≥20 modules**:
+```
+Update Plan:
+  Tool: gemini (fallback: qwen → codex)
+  Total: 31 modules
+  Execution: Agent batch processing (4 modules/agent)
+
+  Will update:
+  - ./src/features/auth (12 files) - depth 3 [Layer 3] - multi-layer strategy
+  - ./.claude/commands/cli (6 files) - depth 3 [Layer 3] - multi-layer strategy
+  - ./src/utils (8 files) - depth 2 [Layer 2] - single-layer strategy
+  ...
+
+  Context Strategy (Auto-Selected):
+  - Layer 3 (depth ≥3): @**/* (all files)
+  - Layer 2 (depth 1-2): @*/CLAUDE.md + current code files
+  - Layer 1 (depth 0): @*/CLAUDE.md + current code files
+  
+  Auto-skipped: ./tests, __pycache__, setup.py (15 paths)
+  Execution order: Layer 2 → Layer 1
+  Estimated time: ~5-10 minutes
+
+  Agent allocation (by LAYER):
+  - Layer 3 (14 modules, depth ≥3): 4 agents [4, 4, 4, 2]
+  - Layer 2 (15 modules, depth 1-2): 4 agents [4, 4, 4, 3]
+  - Layer 1 (2 modules, depth 0): 1 agent [2]
+
+  Estimated time: ~15-25 minutes
+
+  Confirm execution? (y/n)
+```
+
+### Phase 3A: Direct Execution (<20 modules)
+
+**Strategy**: Parallel execution within layer (max 4 concurrent), no agent overhead.
+
+```javascript
+// Group modules by LAYER (not depth)
+let modules_by_layer = group_by_layer(module_list);
+let tool_order = construct_tool_order(primary_tool);
+
+// Process by LAYER (3 → 2 → 1), not by depth
+for (let layer of [3, 2, 1]) {
+  if (modules_by_layer[layer].length === 0) continue;
+
+  let batches = batch_modules(modules_by_layer[layer], 4);
+
+  for (let batch of batches) {
+    let parallel_tasks = batch.map(module => {
+      return async () => {
+        // Auto-determine strategy based on depth
+        let strategy = module.depth >= 3 ? "multi-layer" : "single-layer";
+
+        for (let tool of tool_order) {
+          let exit_code = bash(`cd ${module.path} && ~/.claude/scripts/update_module_claude.sh "${strategy}" "." "${tool}"`);
+          if (exit_code === 0) {
+            report(`✅ ${module.path} (Layer ${layer}) updated with ${tool}`);
+            return true;
+          }
+        }
+        report(`❌ FAILED: ${module.path} (Layer ${layer}) failed all tools`);
+        return false;
+      };
+    });
+
+    await Promise.all(parallel_tasks.map(task => task()));
+  }
+}
+```
+
+### Phase 3B: Agent Batch Execution (≥20 modules)
+
+**Strategy**: Batch modules into groups of 4, spawn memory-bridge agents per batch.
+
+```javascript
+// Group modules by LAYER and batch within each layer
+let modules_by_layer = group_by_layer(module_list);
+let tool_order = construct_tool_order(primary_tool);
+
+for (let layer of [3, 2, 1]) {
+  if (modules_by_layer[layer].length === 0) continue;
+
+  let batches = batch_modules(modules_by_layer[layer], 4);
+  let worker_tasks = [];
+
+  for (let batch of batches) {
+    worker_tasks.push(
+      Task(
+        subagent_type="memory-bridge",
+        description=`Update ${batch.length} modules in Layer ${layer}`,
+        prompt=generate_batch_worker_prompt(batch, tool_order, layer)
+      )
+    );
+  }
+
+  await parallel_execute(worker_tasks);
+}
+```
+
+**Batch Worker Prompt Template**:
+```
+PURPOSE: Update CLAUDE.md for assigned modules with tool fallback
+
+TASK: Update documentation for assigned modules using specified strategies.
+
+MODULES:
+{{module_path_1}} (strategy: {{strategy_1}})
+{{module_path_2}} (strategy: {{strategy_2}})
+...
+
+TOOLS (try in order): {{tool_1}}, {{tool_2}}, {{tool_3}}
+
+EXECUTION SCRIPT: ~/.claude/scripts/update_module_claude.sh
+  - Accepts strategy parameter: multi-layer | single-layer
+  - Tool execution via direct CLI commands (gemini/qwen/codex)
+
+EXECUTION FLOW (for each module):
+  1. Tool fallback loop (exit on first success):
+     for tool in {{tool_1}} {{tool_2}} {{tool_3}}; do
+       bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "{{strategy}}" "." "${tool}")
+       exit_code=$?
+
+       if [ $exit_code -eq 0 ]; then
+         report "✅ {{module_path}} updated with $tool"
+         break
+       else
+         report "⚠️  {{module_path}} failed with $tool, trying next..."
+         continue
+       fi
+     done
+
+  2. Handle complete failure (all tools failed):
+     if [ $exit_code -ne 0 ]; then
+       report "❌ FAILED: {{module_path}} - all tools exhausted"
+       # Continue to next module (do not abort batch)
+     fi
+
+FAILURE HANDLING:
+  - Module-level isolation: One module's failure does not affect others
+  - Exit code detection: Non-zero exit code triggers next tool
+  - Exhaustion reporting: Log modules where all tools failed
+  - Batch continuation: Always process remaining modules
+
+REPORTING FORMAT:
+  Per-module status:
+    ✅ path/to/module updated with {tool}
+    ⚠️  path/to/module failed with {tool}, trying next...
+    ❌ FAILED: path/to/module - all tools exhausted
+```
+### Phase 4: Safety Verification
+
+```bash
+# Check only CLAUDE.md modified
+bash(git diff --cached --name-only | grep -v "CLAUDE.md" || echo "Only CLAUDE.md files modified")
+
+# Display status
+bash(git status --short)
+```
+
+**Result Summary**:
+```
+Update Summary:
+  Total: 31 | Success: 29 | Failed: 2
+  Tool usage: gemini: 25, qwen: 4, codex: 0
+  Failed: path1, path2
+```
+
+## Error Handling
+
+**Batch Worker**: Tool fallback per module, batch isolation, clear status reporting
+**Coordinator**: Invalid path abort, user decline handling, safety check with auto-revert
+**Fallback Triggers**: Non-zero exit code, script timeout, unexpected output
+
+## Usage Examples
+
+```bash
+# Full project update (auto-strategy selection)
+/memory:update-full
+
+# Target specific directory
+/memory:update-full --path .claude
+/memory:update-full --path src/features/auth
+
+# Use specific tool
+/memory:update-full --tool qwen
+/memory:update-full --path .claude --tool qwen
+```
+
+## Key Advantages
+
+- **Efficiency**: 30 modules → 8 agents (73% reduction from sequential)
+- **Resilience**: 3-tier tool fallback per module
+- **Performance**: Parallel batches, no concurrency limits
+- **Observability**: Per-module tool usage, batch-level metrics
+- **Automation**: Zero configuration - strategy auto-selected by directory depth

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

@@ -1,330 +0,0 @@
----
-name: update-full
-description: Complete project-wide CLAUDE.md documentation update
-argument-hint: "[--tool gemini|qwen|codex] [--path <directory>]"
----
-
-# Full Documentation Update (/memory:update-full)
-
-## Coordinator Role
-
-**This command orchestrates project-wide CLAUDE.md updates** using depth-parallel execution strategy with intelligent complexity detection.
-
-**Execution Model**:
-
-1. **Initial Analysis**: Cache git changes, discover module structure
-2. **Complexity Detection**: Analyze module count, determine strategy
-3. **Plan Presentation**: Show user exactly what will be updated
-4. **Depth-Parallel Execution**: Update modules by depth (highest to lowest)
-5. **Safety Verification**: Ensure only CLAUDE.md files modified
-
-**Tool Selection**:
-- `--tool gemini` (default): Documentation generation, pattern recognition
-- `--tool qwen`: Architecture analysis, system design docs
-- `--tool codex`: Implementation validation, code quality analysis
-
-**Path Parameter**:
-- `--path <directory>` (optional): Target specific directory for updates
-- If not specified: Updates entire project from current directory
-- If specified: Changes to target directory before discovery
-
-## Core Rules
-
-1. **Analyze First**: Run git cache and module discovery before any updates
-2. **Scope Control**: Use --path to target specific directories, default is entire project
-3. **Wait for Approval**: Present plan, no execution without user confirmation
-4. **Depth-Parallel**: Same depth runs parallel (max 4 jobs), different depths sequential
-5. **Safety Check**: Verify only CLAUDE.md files modified, revert if source files touched
-6. **Independent Commands**: Each update is a separate bash() call
-7. **No Background Bash Tool**: Never use `run_in_background` parameter in bash() calls; use shell `&` for parallelism
-
-## Execution Workflow
-
-### Phase 1: Discovery & Analysis
-
-**Cache git changes:**
-```bash
-bash(git add -A 2>/dev/null || true)
-```
-
-**Get module structure:**
-
-*If no --path parameter:*
-```bash
-bash(~/.claude/scripts/get_modules_by_depth.sh list)
-```
-
-*If --path parameter specified:*
-```bash
-bash(cd <target-path> && ~/.claude/scripts/get_modules_by_depth.sh list)
-```
-
-**Example with path:**
-```bash
-# Update only .claude directory
-bash(cd .claude && ~/.claude/scripts/get_modules_by_depth.sh list)
-
-# Update specific feature directory
-bash(cd src/features/auth && ~/.claude/scripts/get_modules_by_depth.sh list)
-```
-
-**Parse Output**:
-- Extract module paths from `depth:N|path:<PATH>|...` format
-- Count total modules
-- Identify which modules have/need CLAUDE.md
-
-**Example output:**
-```
-depth:5|path:./.claude/workflows/cli-templates/prompts/analysis|files:5|has_claude:no
-depth:4|path:./.claude/commands/cli/mode|files:3|has_claude:no
-depth:3|path:./.claude/commands/cli|files:6|has_claude:no
-depth:0|path:.|files:14|has_claude:yes
-```
-
-**Validation**:
-- If --path specified, directory exists and is accessible
-- Module list contains depth and path information
-- At least one module exists
-- All paths are relative to target directory (if --path used)
-
----
-
-### Phase 2: Plan Presentation
-
-**Decision Logic**:
-- **Simple projects (≤20 modules)**: Present plan to user, wait for approval
-- **Complex projects (>20 modules)**: Delegate to memory-bridge agent
-
-**Plan format:**
-```
-📋 Update Plan:
-  Tool: gemini
-  Total modules: 31
-
-  NEW CLAUDE.md files (30):
-    - ./.claude/workflows/cli-templates/prompts/analysis/CLAUDE.md
-    - ./.claude/commands/cli/mode/CLAUDE.md
-    - ... (28 more)
-
-  UPDATE existing CLAUDE.md files (1):
-    - ./CLAUDE.md
-
-  ⚠️ Confirm execution? (y/n)
-```
-
-**User Confirmation Required**: No execution without explicit approval
-
----
-
-### Phase 3: Depth-Parallel Execution
-
-**Pattern**: Process highest depth first, parallel within depth, sequential across depths.
-
-**Command structure:**
-```bash
-bash(cd <module-path> && ~/.claude/scripts/update_module_claude.sh "." "full" "<tool>" &)
-```
-
-**Example - Depth 5 (8 modules):**
-```bash
-bash(cd ./.claude/workflows/cli-templates/prompts/analysis && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
-```
-```bash
-bash(cd ./.claude/workflows/cli-templates/prompts/development && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
-```
-```bash
-bash(cd ./.claude/workflows/cli-templates/prompts/documentation && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
-```
-```bash
-bash(cd ./.claude/workflows/cli-templates/prompts/implementation && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
-```
-
-*Wait for depth 5 completion...*
-
-**Example - Depth 4 (7 modules):**
-```bash
-bash(cd ./.claude/commands/cli/mode && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
-```
-```bash
-bash(cd ./.claude/commands/workflow/brainstorm && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
-```
-
-*Continue for remaining depths (3 → 2 → 1 → 0)...*
-
-**Execution Rules**:
-- Each command is separate bash() call
-- Up to 4 concurrent jobs per depth
-- Wait for all jobs in current depth before proceeding
-- Extract path from `depth:N|path:<PATH>|...` format
-- All paths relative to target directory (current dir or --path value)
-
-**Path Context**:
-- Without --path: Paths relative to current directory
-- With --path: Paths relative to specified target directory
-- Module discovery runs in target directory context
-
----
-
-### Phase 4: Safety Verification
-
-**Check modified files:**
-```bash
-bash(git diff --cached --name-only | grep -v "CLAUDE.md" || echo "✅ Only CLAUDE.md files modified")
-```
-
-**Expected output:**
-```
-✅ Only CLAUDE.md files modified
-```
-
-**If non-CLAUDE.md files detected:**
-```
-⚠️ Warning: Non-CLAUDE.md files were modified
-Modified files: src/index.ts, package.json
-→ Run: git restore --staged .
-```
-
-**Display final status:**
-```bash
-bash(git status --short)
-```
-
-**Example output:**
-```
-A  .claude/workflows/cli-templates/prompts/analysis/CLAUDE.md
-A  .claude/commands/cli/mode/CLAUDE.md
-M  CLAUDE.md
-... (30 more files)
-```
-
-## Command Pattern Reference
-
-**Single module update:**
-```bash
-bash(cd <module-path> && ~/.claude/scripts/update_module_claude.sh "." "full" "<tool>" &)
-```
-
-**Components**:
-- `cd <module-path>` - Navigate to module (from `path:` field)
-- `&&` - Ensure cd succeeds
-- `update_module_claude.sh` - Update script
-- `"."` - Current directory
-- `"full"` - Full update mode
-- `"<tool>"` - gemini/qwen/codex
-- `&` - Background execution
-
-**Path extraction:**
-```bash
-# From: depth:5|path:./src/auth|files:10|has_claude:no
-# Extract: ./src/auth
-# Command: bash(cd ./src/auth && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
-```
-
-## Complex Projects Strategy
-
-For projects >20 modules, delegate to memory-bridge agent:
-
-```javascript
-Task(
-  subagent_type="memory-bridge",
-  description="Complex project full update",
-  prompt=`
-CONTEXT:
-- Total modules: ${module_count}
-- Tool: ${tool}
-- Mode: full
-
-MODULE LIST:
-${modules_output}
-
-REQUIREMENTS:
-1. Use TodoWrite to track each depth level
-2. Process depths N→0 sequentially, max 4 parallel per depth
-3. Command: cd "<path>" && update_module_claude.sh "." "full" "${tool}" &
-4. Extract path from "depth:N|path:<PATH>|..." format
-5. Verify all modules processed
-6. Run safety check
-7. Display git status
-`
-)
-```
-
-## Error Handling
-
-- **Invalid path parameter**: Report error if --path directory doesn't exist, abort execution
-- **Module discovery failure**: Report error, abort execution
-- **User declines approval**: Abort execution, no changes made
-- **Safety check failure**: Automatic staging revert, report modified files
-- **Update script failure**: Report failed modules, continue with remaining
-
-## Coordinator Checklist
-
-✅ Parse `--tool` parameter (default: gemini)
-✅ Parse `--path` parameter (optional, default: current directory)
-✅ Execute git cache in current directory
-✅ Execute module discovery (with cd if --path specified)
-✅ Parse module list, count total modules
-✅ Determine strategy based on module count (≤20 vs >20)
-✅ Present plan with exact file paths
-✅ **Wait for user confirmation** (simple projects only)
-✅ Organize modules by depth
-✅ For each depth (highest to lowest):
-  - Launch up to 5 parallel updates
-  - Wait for depth completion
-  - Proceed to next depth
-✅ Run safety check after all updates
-✅ Display git status
-✅ Report completion summary
-
-
-
-## Tool Parameter Reference
-
-**Gemini** (default):
-- Best for: Documentation generation, pattern recognition, architecture review
-- Context window: Large, handles complex codebases
-- Output style: Comprehensive, detailed explanations
-
-**Qwen**:
-- Best for: Architecture analysis, system design documentation
-- Context window: Large, similar to Gemini
-- Output style: Structured, systematic analysis
-
-**Codex**:
-- Best for: Implementation validation, code quality analysis
-- Capabilities: Mathematical reasoning, autonomous development
-- Output style: Technical, implementation-focused
-
-## Path Parameter Reference
-
-**Use Cases**:
-
-**Update configuration directory only:**
-```bash
-/memory:update-full --path .claude
-```
-- Updates only .claude directory and subdirectories
-- Useful after workflow or command modifications
-- Faster than full project update
-
-**Update specific feature module:**
-```bash
-/memory:update-full --path src/features/auth
-```
-- Updates authentication feature and sub-modules
-- Ideal for feature-specific documentation
-- Isolates scope for targeted updates
-
-**Update nested structure:**
-```bash
-/memory:update-full --path .claude/workflows/cli-templates
-```
-- Updates deeply nested directory tree
-- Maintains relative path structure in output
-- All module paths relative to specified directory
-
-**Best Practices**:
-- Use `--path` when working on specific features/modules
-- Omit `--path` for project-wide architectural changes
-- Combine with `--tool` for specialized documentation needs
-- Verify directory exists before execution (automatic validation)

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

@@ -1,306 +0,0 @@
----
-name: update-related
-description: Context-aware CLAUDE.md documentation updates based on recent changes
-argument-hint: "[--tool gemini|qwen|codex]"
----
-
-# Related Documentation Update (/memory:update-related)
-
-## Coordinator Role
-
-**This command orchestrates context-aware CLAUDE.md updates** for modules affected by recent changes using intelligent change detection.
-
-**Execution Model**:
-
-1. **Change Detection**: Analyze git changes to identify affected modules
-2. **Complexity Analysis**: Evaluate change count and determine strategy
-3. **Plan Presentation**: Show user which modules need updates
-4. **Depth-Parallel Execution**: Update affected modules by depth (highest to lowest)
-5. **Safety Verification**: Ensure only CLAUDE.md files modified
-
-**Tool Selection**:
-- `--tool gemini` (default): Documentation generation, pattern recognition
-- `--tool qwen`: Architecture analysis, system design docs
-- `--tool codex`: Implementation validation, code quality analysis
-
-## Core Rules
-
-1. **Detect Changes First**: Use git diff to identify affected modules before updates
-2. **Wait for Approval**: Present plan, no execution without user confirmation
-3. **Related Mode**: Update only changed modules and their parent contexts
-4. **Depth-Parallel**: Same depth runs parallel (max 4 jobs), different depths sequential
-5. **Safety Check**: Verify only CLAUDE.md files modified, revert if source files touched
-6. **No Background Bash Tool**: Never use `run_in_background` parameter in bash() calls; use shell `&` for parallelism
-
-## Execution Workflow
-
-### Phase 1: Change Detection & Analysis
-
-**Refresh code index:**
-```bash
-bash(mcp__code-index__refresh_index)
-```
-
-**Detect changed modules:**
-```bash
-bash(~/.claude/scripts/detect_changed_modules.sh list)
-```
-
-**Cache git changes:**
-```bash
-bash(git add -A 2>/dev/null || true)
-```
-
-**Parse Output**:
-- Extract changed module paths from `depth:N|path:<PATH>|...` format
-- Count affected modules
-- Identify which modules have/need CLAUDE.md updates
-
-**Example output:**
-```
-depth:3|path:./src/api/auth|files:5|types:[ts]|has_claude:no|change:new
-depth:2|path:./src/api|files:12|types:[ts]|has_claude:yes|change:modified
-depth:1|path:./src|files:8|types:[ts]|has_claude:yes|change:parent
-depth:0|path:.|files:14|has_claude:yes|change:parent
-```
-
-**Fallback behavior**:
-- If no git changes detected, use recent modules (first 10 by depth)
-
-**Validation**:
-- Changed module list contains valid paths
-- At least one affected module exists
-
----
-
-### Phase 2: Plan Presentation
-
-**Decision Logic**:
-- **Simple changes (≤15 modules)**: Present plan to user, wait for approval
-- **Complex changes (>15 modules)**: Delegate to memory-bridge agent
-
-**Plan format:**
-```
-📋 Related Update Plan:
-  Tool: gemini
-  Changed modules: 4
-
-  NEW CLAUDE.md files (1):
-    - ./src/api/auth/CLAUDE.md [new module]
-
-  UPDATE existing CLAUDE.md files (3):
-    - ./src/api/CLAUDE.md [parent of changed auth/]
-    - ./src/CLAUDE.md [parent context]
-    - ./CLAUDE.md [root level]
-
-  ⚠️ Confirm execution? (y/n)
-```
-
-**User Confirmation Required**: No execution without explicit approval
-
----
-
-### Phase 3: Depth-Parallel Execution
-
-**Pattern**: Process highest depth first, parallel within depth, sequential across depths.
-
-**Command structure:**
-```bash
-bash(cd <module-path> && ~/.claude/scripts/update_module_claude.sh "." "related" "<tool>" &)
-```
-
-**Example - Depth 3 (new module):**
-```bash
-bash(cd ./src/api/auth && ~/.claude/scripts/update_module_claude.sh "." "related" "gemini" &)
-```
-
-*Wait for depth 3 completion...*
-
-**Example - Depth 2 (modified parent):**
-```bash
-bash(cd ./src/api && ~/.claude/scripts/update_module_claude.sh "." "related" "gemini" &)
-```
-
-*Wait for depth 2 completion...*
-
-**Example - Depth 1 & 0 (parent contexts):**
-```bash
-bash(cd ./src && ~/.claude/scripts/update_module_claude.sh "." "related" "gemini" &)
-```
-```bash
-bash(cd . && ~/.claude/scripts/update_module_claude.sh "." "related" "gemini" &)
-```
-
-*Wait for all depths completion...*
-
-**Execution Rules**:
-- Each command is separate bash() call
-- Up to 4 concurrent jobs per depth
-- Wait for all jobs in current depth before proceeding
-- Use "related" mode (not "full") for context-aware updates
-- Extract path from `depth:N|path:<PATH>|...` format
-
-**Related Mode Behavior**:
-- Updates module based on recent git changes
-- Includes parent context for better documentation coherence
-- More efficient than full updates for iterative development
-
----
-
-### Phase 4: Safety Verification
-
-**Check modified files:**
-```bash
-bash(git diff --cached --name-only | grep -v "CLAUDE.md" || echo "✅ Only CLAUDE.md files modified")
-```
-
-**Expected output:**
-```
-✅ Only CLAUDE.md files modified
-```
-
-**If non-CLAUDE.md files detected:**
-```
-⚠️ Warning: Non-CLAUDE.md files were modified
-Modified files: src/api/auth/index.ts, package.json
-→ Run: git restore --staged .
-```
-
-**Display final statistics:**
-```bash
-bash(git diff --stat)
-```
-
-**Example output:**
-```
-.claude/workflows/cli-templates/prompts/analysis/CLAUDE.md | 45 +++++++++++++++++++++
-src/api/CLAUDE.md                                          | 23 +++++++++--
-src/CLAUDE.md                                              | 12 ++++--
-CLAUDE.md                                                  | 8 ++--
-4 files changed, 82 insertions(+), 6 deletions(-)
-```
-
-## Command Pattern Reference
-
-**Single module update:**
-```bash
-bash(cd <module-path> && ~/.claude/scripts/update_module_claude.sh "." "related" "<tool>" &)
-```
-
-**Components**:
-- `cd <module-path>` - Navigate to module (from `path:` field)
-- `&&` - Ensure cd succeeds
-- `update_module_claude.sh` - Update script
-- `"."` - Current directory
-- `"related"` - Related mode (context-aware, change-based)
-- `"<tool>"` - gemini/qwen/codex
-- `&` - Background execution
-
-**Path extraction:**
-```bash
-# From: depth:3|path:./src/api/auth|files:5|change:new|has_claude:no
-# Extract: ./src/api/auth
-# Command: bash(cd ./src/api/auth && ~/.claude/scripts/update_module_claude.sh "." "related" "gemini" &)
-```
-
-**Mode comparison:**
-- `"full"` - Complete module documentation regeneration
-- `"related"` - Context-aware update based on recent changes (faster)
-
-## Complex Changes Strategy
-
-For changes affecting >15 modules, delegate to memory-bridge agent:
-
-```javascript
-Task(
-  subagent_type="memory-bridge",
-  description="Complex project related update",
-  prompt=`
-CONTEXT:
-- Total modules: ${change_count}
-- Tool: ${tool}
-- Mode: related
-
-MODULE LIST:
-${changed_modules_output}
-
-REQUIREMENTS:
-1. Use TodoWrite to track each depth level
-2. Process depths N→0 sequentially, max 4 parallel per depth
-3. Command: cd "<path>" && update_module_claude.sh "." "related" "${tool}" &
-4. Extract path from "depth:N|path:<PATH>|..." format
-5. Verify all ${change_count} modules processed
-6. Run safety check
-7. Display git diff --stat
-`
-)
-```
-
-## Error Handling
-
-- **No changes detected**: Use fallback mode (recent 10 modules)
-- **Change detection failure**: Report error, abort execution
-- **User declines approval**: Abort execution, no changes made
-- **Safety check failure**: Automatic staging revert, report modified files
-- **Update script failure**: Report failed modules, continue with remaining
-
-## Coordinator Checklist
-
-✅ Parse `--tool` parameter (default: gemini)
-✅ Refresh code index for accurate change detection
-✅ Detect changed modules via detect_changed_modules.sh
-✅ Cache git changes to protect current state
-✅ Parse changed module list, count affected modules
-✅ Apply fallback if no changes detected (recent 10 modules)
-✅ Determine strategy based on change count (≤15 vs >15)
-✅ Present plan with exact file paths and change types
-✅ **Wait for user confirmation** (simple changes only)
-✅ Organize modules by depth
-✅ For each depth (highest to lowest):
-  - Launch up to 4 parallel updates with "related" mode
-  - Wait for depth completion
-  - Proceed to next depth
-✅ Run safety check after all updates
-✅ Display git diff statistics
-✅ Report completion summary
-
-## Usage Examples
-
-```bash
-# Daily development update (default: gemini)
-/memory:update-related
-
-# After feature work with specific tool
-/memory:update-related --tool qwen
-
-# Code quality review after implementation
-/memory:update-related --tool codex
-```
-
-## Tool Parameter Reference
-
-**Gemini** (default):
-- Best for: Documentation generation, pattern recognition
-- Use case: Daily development updates, feature documentation
-- Output style: Comprehensive, contextual explanations
-
-**Qwen**:
-- Best for: Architecture analysis, system design
-- Use case: Structural changes, API design updates
-- Output style: Structured, systematic documentation
-
-**Codex**:
-- Best for: Implementation validation, code quality
-- Use case: After implementation, refactoring work
-- Output style: Technical, implementation-focused
-
-## Comparison with Full Update
-
-| Aspect | Related Update | Full Update |
-|--------|----------------|-------------|
-| **Scope** | Changed modules only | All project modules |
-| **Speed** | Fast (minutes) | Slower (10-30 min) |
-| **Use case** | Daily development | Major refactoring |
-| **Mode** | `"related"` | `"full"` |
-| **Trigger** | After commits | After major changes |
-| **Complexity threshold** | ≤15 modules | ≤20 modules |

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

@@ -0,0 +1,349 @@
+---
+name: update-related
+description: Context-aware CLAUDE.md documentation updates based on recent changes with agent-based execution and tool fallback
+argument-hint: "[--tool gemini|qwen|codex]"
+---
+
+# Related Documentation Update (/memory:update-related)
+
+## Overview
+
+Orchestrates context-aware CLAUDE.md updates for changed modules using batched agent execution with automatic tool fallback (gemini→qwen→codex).
+
+**Parameters**:
+- `--tool <gemini|qwen|codex>`: Primary tool (default: gemini)
+
+**Execution Flow**:
+1. Change Detection → 2. Plan Presentation → 3. Batched Agent Execution → 4. Safety Verification
+
+## Core Rules
+
+1. **Detect Changes First**: Use git diff to identify affected modules
+2. **Wait for Approval**: Present plan, no execution without user confirmation
+3. **Execution Strategy**:
+   - <15 modules: Direct parallel execution (max 4 concurrent per depth, no agent overhead)
+   - ≥15 modules: Agent batch processing (4 modules/agent, 73% overhead reduction)
+4. **Tool Fallback**: Auto-retry with fallback tools on failure
+5. **Depth Sequential**: Process depths N→0, parallel batches within depth (both modes)
+6. **Related Mode**: Update only changed modules and their parent contexts
+
+## Tool Fallback Hierarchy
+
+```javascript
+--tool gemini  →  [gemini, qwen, codex]  // default
+--tool qwen    →  [qwen, gemini, codex]
+--tool codex   →  [codex, gemini, qwen]
+```
+
+**Trigger**: Non-zero exit code from update script
+
+## Phase 1: Change Detection & Analysis
+
+```bash
+# Detect changed modules (no index refresh needed)
+bash(~/.claude/scripts/detect_changed_modules.sh list)
+
+# Cache git changes
+bash(git add -A 2>/dev/null || true)
+```
+
+**Parse output** `depth:N|path:<PATH>|change:<TYPE>` to extract affected modules.
+
+**Smart filter**: Auto-detect and skip tests/build/config/docs based on project tech stack (Node.js/Python/Go/Rust/etc).
+
+**Fallback**: If no changes detected, use recent modules (first 10 by depth).
+
+## Phase 2: Plan Presentation
+
+**Present filtered plan**:
+```
+Related Update Plan:
+  Tool: gemini (fallback: qwen → codex)
+  Changed: 4 modules | Batching: 4 modules/agent
+
+  Will update:
+  - ./src/api/auth (5 files) [new module]
+  - ./src/api (12 files) [parent of changed auth/]
+  - ./src (8 files) [parent context]
+  - . (14 files) [root level]
+
+  Auto-skipped (12 paths):
+  - Tests: ./src/api/auth.test.ts (8 paths)
+  - Config: tsconfig.json (3 paths)
+  - Other: node_modules (1 path)
+
+  Agent allocation:
+  - Depth 3 (1 module): 1 agent [1]
+  - Depth 2 (1 module): 1 agent [1]
+  - Depth 1 (1 module): 1 agent [1]
+  - Depth 0 (1 module): 1 agent [1]
+
+  Confirm execution? (y/n)
+```
+
+**Decision logic**:
+- User confirms "y": Proceed with execution
+- User declines "n": Abort, no changes
+- <15 modules: Direct execution
+- ≥15 modules: Agent batch execution
+
+## Phase 3A: Direct Execution (<15 modules)
+
+**Strategy**: Parallel execution within depth (max 4 concurrent), no agent overhead, tool fallback per module.
+
+```javascript
+let modules_by_depth = group_by_depth(changed_modules);
+let tool_order = construct_tool_order(primary_tool);
+
+for (let depth of sorted_depths.reverse()) {  // N → 0
+  let modules = modules_by_depth[depth];
+  let batches = batch_modules(modules, 4);  // Split into groups of 4
+
+  for (let batch of batches) {
+    // Execute batch in parallel (max 4 concurrent)
+    let parallel_tasks = batch.map(module => {
+      return async () => {
+        let success = false;
+        for (let tool of tool_order) {
+          let exit_code = bash(cd ${module.path} && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "${tool}");
+          if (exit_code === 0) {
+            report("${module.path} updated with ${tool}");
+            success = true;
+            break;
+          }
+        }
+        if (!success) {
+          report("FAILED: ${module.path} failed all tools");
+        }
+      };
+    });
+
+    await Promise.all(parallel_tasks.map(task => task()));  // Run batch in parallel
+  }
+}
+```
+
+**Benefits**:
+- No agent startup overhead
+- Parallel execution within depth (max 4 concurrent)
+- Tool fallback still applies per module
+- Faster for small changesets (<15 modules)
+- Same batching strategy as Phase 3B but without agent layer
+
+---
+
+## Phase 3B: Agent Batch Execution (≥15 modules)
+
+### Batching Strategy
+
+```javascript
+// Batch modules into groups of 4
+function batch_modules(modules, batch_size = 4) {
+  let batches = [];
+  for (let i = 0; i < modules.length; i += batch_size) {
+    batches.push(modules.slice(i, i + batch_size));
+  }
+  return batches;
+}
+// Examples: 10→[4,4,2] | 8→[4,4] | 3→[3]
+```
+
+### Coordinator Orchestration
+
+```javascript
+let modules_by_depth = group_by_depth(changed_modules);
+let tool_order = construct_tool_order(primary_tool);
+
+for (let depth of sorted_depths.reverse()) {  // N → 0
+  let batches = batch_modules(modules_by_depth[depth], 4);
+  let worker_tasks = [];
+
+  for (let batch of batches) {
+    worker_tasks.push(
+      Task(
+        subagent_type="memory-bridge",
+        description=`Update ${batch.length} modules at depth ${depth}`,
+        prompt=generate_batch_worker_prompt(batch, tool_order, "related")
+      )
+    );
+  }
+
+  await parallel_execute(worker_tasks);  // Batches run in parallel
+}
+```
+
+### Batch Worker Prompt Template
+
+```
+PURPOSE: Update CLAUDE.md for assigned modules with tool fallback (related mode)
+
+TASK:
+Update documentation for the following modules based on recent changes. For each module, try tools in order until success.
+
+MODULES:
+{{module_path_1}}
+{{module_path_2}}
+{{module_path_3}}
+{{module_path_4}}
+
+TOOLS (try in order):
+1. {{tool_1}}
+2. {{tool_2}}
+3. {{tool_3}}
+
+EXECUTION:
+For each module above:
+  1. cd "{{module_path}}"
+  2. Try tool 1:
+     bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "{{tool_1}}")
+     → Success: Report "{{module_path}} updated with {{tool_1}}", proceed to next module
+     → Failure: Try tool 2
+  3. Try tool 2:
+     bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "{{tool_2}}")
+     → Success: Report "{{module_path}} updated with {{tool_2}}", proceed to next module
+     → Failure: Try tool 3
+  4. Try tool 3:
+     bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "{{tool_3}}")
+     → Success: Report "{{module_path}} updated with {{tool_3}}", proceed to next module
+     → Failure: Report "FAILED: {{module_path}} failed all tools", proceed to next module
+
+REPORTING:
+Report final summary with:
+- Total processed: X modules
+- Successful: Y modules
+- Failed: Z modules
+- Tool usage: {{tool_1}}:X, {{tool_2}}:Y, {{tool_3}}:Z
+- Detailed results for each module
+```
+
+### Example Execution
+
+**Depth 3 (new module)**:
+```javascript
+Task(subagent_type="memory-bridge", batch=[./src/api/auth], mode="related")
+```
+
+**Benefits**:
+- 4 modules → 1 agent (75% reduction)
+- Parallel batches, sequential within batch
+- Each module gets full fallback chain
+- Context-aware updates based on git changes
+
+## Phase 4: Safety Verification
+
+```bash
+# Check only CLAUDE.md modified
+bash(git diff --cached --name-only | grep -v "CLAUDE.md" || echo "Only CLAUDE.md files modified")
+
+# Display statistics
+bash(git diff --stat)
+```
+
+**Aggregate results**:
+```
+Update Summary:
+  Total: 4 | Success: 4 | Failed: 0
+
+  Tool usage:
+  - gemini: 4 modules
+  - qwen: 0 modules (fallback)
+  - codex: 0 modules
+
+  Changes:
+  src/api/auth/CLAUDE.md  | 45 +++++++++++++++++++++
+  src/api/CLAUDE.md       | 23 +++++++++--
+  src/CLAUDE.md           | 12 ++++--
+  CLAUDE.md               | 8 ++--
+  4 files changed, 82 insertions(+), 6 deletions(-)
+```
+
+## Execution Summary
+
+**Module Count Threshold**:
+- **<15 modules**: Coordinator executes Phase 3A (Direct Execution)
+- **≥15 modules**: Coordinator executes Phase 3B (Agent Batch Execution)
+
+**Agent Hierarchy** (for ≥15 modules):
+- **Coordinator**: Handles batch division, spawns worker agents per depth
+- **Worker Agents**: Each processes 4 modules with tool fallback (related mode)
+
+## Error Handling
+
+**Batch Worker**:
+- Tool fallback per module (auto-retry)
+- Batch isolation (failures don't propagate)
+- Clear per-module status reporting
+
+**Coordinator**:
+- No changes: Use fallback (recent 10 modules)
+- User decline: No execution
+- Safety check fail: Auto-revert staging
+- Partial failures: Continue execution, report failed modules
+
+**Fallback Triggers**:
+- Non-zero exit code
+- Script timeout
+- Unexpected output
+
+## Tool Reference
+
+| Tool   | Best For                       | Fallback To    |
+|--------|--------------------------------|----------------|
+| gemini | Documentation, patterns        | qwen → codex   |
+| qwen   | Architecture, system design    | gemini → codex |
+| codex  | Implementation, code quality   | gemini → qwen  |
+
+## Usage Examples
+
+```bash
+# Daily development update
+/memory:update-related
+
+# After feature work with specific tool
+/memory:update-related --tool qwen
+
+# Code quality review after implementation
+/memory:update-related --tool codex
+```
+
+## Key Advantages
+
+**Efficiency**: 30 modules → 8 agents (73% reduction)
+**Resilience**: 3-tier fallback per module
+**Performance**: Parallel batches, no concurrency limits
+**Context-aware**: Updates based on actual git changes
+**Fast**: Only affected modules, not entire project
+
+## Coordinator Checklist
+
+- Parse `--tool` (default: gemini)
+- Refresh code index for accurate change detection
+- Detect changed modules via detect_changed_modules.sh
+- **Smart filter modules** (auto-detect tech stack, skip tests/build/config/docs)
+- Cache git changes
+- Apply fallback if no changes (recent 10 modules)
+- Construct tool fallback order
+- **Present filtered plan** with skip reasons and change types
+- **Wait for y/n confirmation**
+- Determine execution mode:
+  - **<15 modules**: Direct execution (Phase 3A)
+    - For each depth (N→0): Sequential module updates with tool fallback
+  - **≥15 modules**: Agent batch execution (Phase 3B)
+    - For each depth (N→0): Batch modules (4 per batch), spawn batch workers in parallel
+- Wait for depth/batch completion
+- Aggregate results
+- Safety check (only CLAUDE.md modified)
+- Display git diff statistics + summary
+
+## Comparison with Full Update
+
+| Aspect | Related Update | Full Update |
+|--------|----------------|-------------|
+| **Scope** | Changed modules only | All project modules |
+| **Speed** | Fast (minutes) | Slower (10-30 min) |
+| **Use case** | Daily development | Major refactoring |
+| **Mode** | `"related"` | `"full"` |
+| **Trigger** | After commits | After major changes |
+| **Batching** | 4 modules/agent | 4 modules/agent |
+| **Fallback** | gemini→qwen→codex | gemini→qwen→codex |
+| **Complexity threshold** | ≤15 modules | ≤20 modules |

.claude/commands/memory/workflow-skill-memory.md

@@ -0,0 +1,517 @@
+---
+name: workflow-skill-memory
+description: Generate SKILL package from archived workflow sessions for progressive context loading
+argument-hint: "session <session-id> | all"
+allowed-tools: Task(*), TodoWrite(*), Bash(*), Read(*), Write(*)
+---
+
+# Workflow SKILL Memory Generator
+
+## Overview
+
+Generate SKILL package from archived workflow sessions using agent-driven analysis. Supports single-session incremental updates or parallel processing of all sessions.
+
+**Scope**: Only processes WFS-* workflow sessions. Other session types (e.g., doc sessions) are automatically ignored.
+
+## Usage
+
+```bash
+/memory:workflow-skill-memory session WFS-<session-id>   # Process single WFS session
+/memory:workflow-skill-memory all                        # Process all WFS sessions in parallel
+```
+
+## Execution Modes
+
+### Mode 1: Single Session (`session <session-id>`)
+
+**Purpose**: Incremental update - process one archived session and merge into existing SKILL package
+
+**Workflow**:
+1. **Validate session**: Check if session exists in `.workflow/.archives/{session-id}/`
+2. **Invoke agent**: Call `universal-executor` to analyze session and update SKILL documents
+3. **Agent tasks**:
+   - Read session data from `.workflow/.archives/{session-id}/`
+   - Extract lessons, conflicts, and outcomes
+   - Use Gemini for intelligent aggregation (optional)
+   - Update or create SKILL documents using templates
+   - Regenerate SKILL.md index
+
+**Command Example**:
+```bash
+/memory:workflow-skill-memory session WFS-user-auth
+```
+
+**Expected Output**:
+```
+Session WFS-user-auth processed
+Updated:
+- sessions-timeline.md (1 session added)
+- lessons-learned.md (3 lessons merged)
+- conflict-patterns.md (1 conflict added)
+- SKILL.md (index regenerated)
+```
+
+---
+
+### Mode 2: All Sessions (`all`)
+
+**Purpose**: Full regeneration - process all archived sessions in parallel for complete SKILL package
+
+**Workflow**:
+1. **List sessions**: Read manifest.json to get all archived session IDs
+2. **Parallel invocation**: Launch multiple `universal-executor` agents in parallel (one per session)
+3. **Agent coordination**:
+   - Each agent processes one session independently
+   - Agents use Gemini for analysis
+   - Agents collect data into JSON (no direct file writes)
+   - Final aggregator agent merges results and generates SKILL documents
+
+**Command Example**:
+```bash
+/memory:workflow-skill-memory all
+```
+
+**Expected Output**:
+```
+All sessions processed in parallel
+Sessions: 8 total
+Updated:
+- sessions-timeline.md (8 sessions)
+- lessons-learned.md (24 lessons aggregated)
+- conflict-patterns.md (12 conflicts documented)
+- SKILL.md (index regenerated)
+```
+
+---
+
+## Implementation Flow
+
+### Phase 1: Validation and Setup
+
+**Step 1.1: Parse Command Arguments**
+
+Extract mode and session ID:
+```javascript
+if (args === "all") {
+  mode = "all"
+} else if (args.startsWith("session ")) {
+  mode = "session"
+  session_id = args.replace("session ", "").trim()
+} else {
+  ERROR = "Invalid arguments. Usage: session <session-id> | all"
+  EXIT
+}
+```
+
+**Step 1.2: Validate Archive Directory**
+```bash
+bash(test -d .workflow/.archives && echo "exists" || echo "missing")
+```
+
+If missing, report error and exit.
+
+**Step 1.3: Mode-Specific Validation**
+
+**Single Session Mode**:
+```bash
+# Validate session ID format (must start with WFS-)
+if [[ ! "$session_id" =~ ^WFS- ]]; then
+  ERROR = "Invalid session ID format. Only WFS-* sessions are supported"
+  EXIT
+fi
+
+# Check if session exists
+bash(test -d .workflow/.archives/{session_id} && echo "exists" || echo "missing")
+```
+
+If missing, report error: "Session {session_id} not found in archives"
+
+**All Sessions Mode**:
+```bash
+# Read manifest and filter only WFS- sessions
+bash(cat .workflow/.archives/manifest.json | jq -r '.archives[].session_id | select(startswith("WFS-"))')
+```
+
+Store filtered session IDs in array. Ignore doc sessions and other non-WFS sessions.
+
+**Step 1.4: TodoWrite Initialization**
+
+**Single Session Mode**:
+```javascript
+TodoWrite({todos: [
+  {"content": "Validate session existence", "status": "completed", "activeForm": "Validating session"},
+  {"content": "Invoke agent to process session", "status": "in_progress", "activeForm": "Invoking agent"},
+  {"content": "Verify SKILL package updated", "status": "pending", "activeForm": "Verifying update"}
+]})
+```
+
+**All Sessions Mode**:
+```javascript
+TodoWrite({todos: [
+  {"content": "Read manifest and list sessions", "status": "completed", "activeForm": "Reading manifest"},
+  {"content": "Invoke agents in parallel", "status": "in_progress", "activeForm": "Invoking agents"},
+  {"content": "Verify SKILL package regenerated", "status": "pending", "activeForm": "Verifying regeneration"}
+]})
+```
+
+---
+
+### Phase 2: Agent Invocation
+
+#### Single Session Mode - Agent Task
+
+Invoke `universal-executor` with session-specific task:
+
+**Agent Prompt Structure**:
+```
+Task: Process Workflow Session for SKILL Package
+
+Context:
+- Session ID: {session_id}
+- Session Path: .workflow/.archives/{session_id}/
+- Mode: Incremental update
+
+Objectives:
+
+1. Read session data:
+   - workflow-session.json (metadata)
+   - IMPL_PLAN.md (implementation summary)
+   - TODO_LIST.md (if exists)
+   - manifest.json entry for lessons
+
+2. Extract key information:
+   - Description, tags, metrics
+   - Lessons (successes, challenges, watch_patterns)
+   - Context package path (reference only)
+   - Key outcomes from IMPL_PLAN
+
+3. Use Gemini for aggregation (optional):
+   Command pattern:
+   cd .workflow/.archives/{session_id} && gemini -p "
+   PURPOSE: Extract lessons and conflicts from workflow session
+   TASK:
+   • Analyze IMPL_PLAN and lessons from manifest
+   • Identify success patterns and challenges
+   • Extract conflict patterns with resolutions
+   • Categorize by functional domain
+   MODE: analysis
+   CONTEXT: @IMPL_PLAN.md @workflow-session.json
+   EXPECTED: Structured lessons and conflicts in JSON format
+   RULES: Template reference from skill-aggregation.txt
+   "
+
+3.5. **Generate SKILL.md Description** (CRITICAL for auto-loading):
+
+   Read skill-index.txt template Section: "Description Field Generation"
+
+   Execute command to get project root:
+   ```bash
+   git rev-parse --show-toplevel  # Example output: /d/Claude_dms3
+   ```
+
+   Apply description format:
+   ```
+   Progressive workflow development history (located at {project_root}).
+   Load this SKILL when continuing development, analyzing past implementations,
+   or learning from workflow history, especially when no relevant context exists in memory.
+   ```
+
+   **Validation**:
+   - [ ] Path uses forward slashes (not backslashes)
+   - [ ] All three use cases present
+   - [ ] Trigger optimization phrase included
+   - [ ] Path is absolute (starts with / or drive letter)
+
+4. Read templates for formatting guidance:
+   - ~/.claude/workflows/cli-templates/prompts/workflow/skill-sessions-timeline.txt
+   - ~/.claude/workflows/cli-templates/prompts/workflow/skill-lessons-learned.txt
+   - ~/.claude/workflows/cli-templates/prompts/workflow/skill-conflict-patterns.txt
+   - ~/.claude/workflows/cli-templates/prompts/workflow/skill-index.txt
+
+   **CRITICAL**: From skill-index.txt, read these sections:
+   - "Description Field Generation" - Rules for generating description
+   - "Variable Substitution Guide" - All required variables
+   - "Generation Instructions" - Step-by-step generation process
+   - "Validation Checklist" - Final validation steps
+
+5. Update SKILL documents:
+   - sessions-timeline.md: Append new session, update domain grouping
+   - lessons-learned.md: Merge lessons into categories, update frequencies
+   - conflict-patterns.md: Add conflicts, update recurring pattern frequencies
+   - SKILL.md: Regenerate index with updated counts
+
+   **For SKILL.md generation**:
+   - Follow "Generation Instructions" from skill-index.txt (Steps 1-7)
+   - Use git command for project_root: `git rev-parse --show-toplevel`
+   - Apply "Description Field Generation" rules
+   - Validate using "Validation Checklist"
+   - Increment version (patch level)
+
+6. Return result JSON:
+   {
+     "status": "success",
+     "session_id": "{session_id}",
+     "updates": {
+       "sessions_added": 1,
+       "lessons_merged": count,
+       "conflicts_added": count
+     }
+   }
+```
+
+---
+
+#### All Sessions Mode - Parallel Agent Tasks
+
+**Step 2.1: Launch parallel session analyzers**
+
+Invoke multiple agents in parallel (one message with multiple Task calls):
+
+**Per-Session Agent Prompt**:
+```
+Task: Extract Session Data for SKILL Package
+
+Context:
+- Session ID: {session_id}
+- Mode: Parallel analysis (no direct file writes)
+
+Objectives:
+
+1. Read session data (same as single mode)
+
+2. Extract key information (same as single mode)
+
+3. Use Gemini for analysis (same as single mode)
+
+4. Return structured data JSON:
+   {
+     "status": "success",
+     "session_id": "{session_id}",
+     "data": {
+       "metadata": {
+         "description": "...",
+         "archived_at": "...",
+         "tags": [...],
+         "metrics": {...}
+       },
+       "lessons": {
+         "successes": [...],
+         "challenges": [...],
+         "watch_patterns": [...]
+       },
+       "conflicts": [
+         {
+           "type": "architecture|dependencies|testing|performance",
+           "pattern": "...",
+           "resolution": "...",
+           "code_impact": [...]
+         }
+       ],
+       "impl_summary": "First 200 chars of IMPL_PLAN",
+       "context_package_path": "..."
+     }
+   }
+```
+
+**Step 2.2: Aggregate results**
+
+After all session agents complete, invoke aggregator agent:
+
+**Aggregator Agent Prompt**:
+```
+Task: Aggregate Session Results and Generate SKILL Package
+
+Context:
+- Mode: Full regeneration
+- Input: JSON results from {session_count} session agents
+
+Objectives:
+
+1. Aggregate all session data:
+   - Collect metadata from all sessions
+   - Merge lessons by category
+   - Group conflicts by type
+   - Sort sessions by date
+
+2. Use Gemini for final aggregation:
+   gemini -p "
+   PURPOSE: Aggregate lessons and conflicts from all workflow sessions
+   TASK:
+   • Group successes by functional domain
+   • Categorize challenges by severity (HIGH/MEDIUM/LOW)
+   • Identify recurring conflict patterns
+   • Calculate frequencies and prioritize
+   MODE: analysis
+   CONTEXT: [Provide aggregated JSON data]
+   EXPECTED: Final aggregated structure for SKILL documents
+   RULES: Template reference from skill-aggregation.txt
+   "
+
+3. Read templates for formatting (same 4 templates as single mode)
+
+4. Generate all SKILL documents:
+   - sessions-timeline.md (all sessions, sorted by date)
+   - lessons-learned.md (aggregated lessons with frequencies)
+   - conflict-patterns.md (recurring patterns with resolutions)
+   - SKILL.md (index with progressive loading)
+
+5. Write files to .claude/skills/workflow-progress/
+
+6. Return result JSON:
+   {
+     "status": "success",
+     "sessions_processed": count,
+     "files_generated": ["SKILL.md", "sessions-timeline.md", ...],
+     "summary": {
+       "total_sessions": count,
+       "functional_domains": [...],
+       "date_range": "...",
+       "lessons_count": count,
+       "conflicts_count": count
+     }
+   }
+```
+
+---
+
+### Phase 3: Verification
+
+**Step 3.1: Check SKILL Package Files**
+```bash
+bash(ls -lh .claude/skills/workflow-progress/)
+```
+
+Verify all 4 files exist:
+- SKILL.md
+- sessions-timeline.md
+- lessons-learned.md
+- conflict-patterns.md
+
+**Step 3.2: TodoWrite Completion**
+
+Mark all tasks as completed.
+
+**Step 3.3: Display Summary**
+
+**Single Session Mode**:
+```
+Session {session_id} processed successfully
+
+Updated:
+- sessions-timeline.md
+- lessons-learned.md
+- conflict-patterns.md
+- SKILL.md
+
+SKILL Location: .claude/skills/workflow-progress/SKILL.md
+```
+
+**All Sessions Mode**:
+```
+All sessions processed in parallel
+
+Sessions: {count} total
+Functional Domains: {domain_list}
+Date Range: {earliest} - {latest}
+
+Generated:
+- sessions-timeline.md ({count} sessions)
+- lessons-learned.md ({lessons_count} lessons)
+- conflict-patterns.md ({conflicts_count} conflicts)
+- SKILL.md (4-level progressive loading)
+
+SKILL Location: .claude/skills/workflow-progress/SKILL.md
+
+Usage:
+- Level 0: Quick refresh (~2K tokens)
+- Level 1: Recent history (~8K tokens)
+- Level 2: Complete analysis (~25K tokens)
+- Level 3: Deep dive (~40K tokens)
+```
+
+---
+
+## Agent Guidelines
+
+### Agent Capabilities
+
+**universal-executor agents can**:
+- Read files from `.workflow/.archives/`
+- Execute bash commands
+- Call Gemini CLI for intelligent analysis
+- Read template files for formatting guidance
+- Write SKILL package files (single mode) or return JSON (parallel mode)
+- Return structured results
+
+### Gemini Usage Pattern
+
+**When to use Gemini**:
+- Aggregating lessons from multiple sources
+- Identifying recurring patterns
+- Classifying conflicts by type and severity
+- Extracting structured data from IMPL_PLAN
+
+**Fallback Strategy**: If Gemini fails or times out, use direct file parsing with structured extraction logic.
+
+---
+
+## Template System
+
+### Template Files
+
+All templates located in: `~/.claude/workflows/cli-templates/prompts/workflow/`
+
+1. **skill-sessions-timeline.txt**: Format for sessions-timeline.md
+2. **skill-lessons-learned.txt**: Format for lessons-learned.md
+3. **skill-conflict-patterns.txt**: Format for conflict-patterns.md
+4. **skill-index.txt**: Format for SKILL.md index
+5. **skill-aggregation.txt**: Rules for Gemini aggregation (existing)
+
+### Template Usage in Agent
+
+**Agents read templates to understand**:
+- File structure and markdown format
+- Data sources (which files to read)
+- Update strategy (incremental vs full)
+- Formatting rules and conventions
+- Aggregation logic (for Gemini)
+
+**Templates are NOT shown in this command documentation** - agents read them directly as needed.
+
+---
+
+## Error Handling
+
+### Validation Errors
+- **No archives directory**: "Error: No workflow archives found at .workflow/.archives/"
+- **Invalid session ID format**: "Error: Invalid session ID format. Only WFS-* sessions are supported"
+- **Session not found**: "Error: Session {session_id} not found in archives"
+- **No WFS sessions in manifest**: "Error: No WFS-* workflow sessions found in manifest.json"
+
+### Agent Errors
+- If agent fails, report error message from agent result
+- If Gemini times out, agents use fallback direct parsing
+- If template read fails, agents use inline format
+
+### Recovery
+- Single session mode: Can be retried without affecting other sessions
+- All sessions mode: If one agent fails, others continue; retry failed sessions individually
+
+
+
+## Integration
+
+### Called by `/workflow:session:complete`
+
+Automatically invoked after session archival:
+```bash
+SlashCommand(command="/memory:workflow-skill-memory session {session_id}")
+```
+
+### Manual Invocation
+
+Users can manually process sessions:
+```bash
+/memory:workflow-skill-memory session WFS-custom-feature  # Single session
+/memory:workflow-skill-memory all                         # Full regeneration
+```

.claude/commands/task/breakdown.md

@@ -10,13 +10,12 @@ argument-hint: "task-id"
 Breaks down complex tasks into executable subtasks with context inheritance and agent assignment.
 
 ## Core Principles
-**Task System:** @~/.claude/workflows/workflow-architecture.md
 **File Cohesion:** Related files must stay in same task
 **10-Task Limit:** Total tasks cannot exceed 10 (triggers re-scoping)
 
 ## Core Features
 
-⚠️ **CRITICAL**: Manual breakdown with safety controls to prevent file conflicts and task limit violations.
+**CRITICAL**: Manual breakdown with safety controls to prevent file conflicts and task limit violations.
 
 ### Breakdown Process
 1. **Session Check**: Verify active session contains parent task
@@ -51,7 +50,7 @@ Interactive process:
 Task: Build authentication module
 Current total tasks: 6/10
 
-⚠️  MANUAL BREAKDOWN REQUIRED
+MANUAL BREAKDOWN REQUIRED
 Define subtasks manually (remaining capacity: 4 tasks):
 
 1. Enter subtask title: User authentication core
@@ -60,11 +59,11 @@ Define subtasks manually (remaining capacity: 4 tasks):
 2. Enter subtask title: OAuth integration
    Focus files: services/OAuthService.js, routes/oauth.js
 
-⚠️  FILE CONFLICT DETECTED:
+FILE CONFLICT DETECTED:
    - routes/auth.js appears in multiple subtasks
    - Recommendation: Merge related authentication routes
 
-⚠️  SIMILAR FUNCTIONALITY WARNING:
+SIMILAR FUNCTIONALITY WARNING:
    - "User authentication" and "OAuth integration" both handle auth
    - Consider combining into single task
 
@@ -84,10 +83,10 @@ AskUserQuestion({
 
 User selected: "Proceed with breakdown"
 
-✅ Task IMPL-1 broken down:
+Task IMPL-1 broken down:
-▸ IMPL-1: Build authentication module (container)
+IMPL-1: Build authentication module (container)
-  ├── IMPL-1.1: User authentication core → @code-developer
+  ├── IMPL-1.1: User authentication core -> @code-developer
-  └── IMPL-1.2: OAuth integration → @code-developer
+  └── IMPL-1.2: OAuth integration -> @code-developer
 
 Files updated: .task/IMPL-1.json + 2 subtask files + TODO_LIST.md
 ```
@@ -99,7 +98,7 @@ Files updated: .task/IMPL-1.json + 2 subtask files + TODO_LIST.md
 - **Implementation** → `@code-developer`
 - **Testing** → `@code-developer` (type: "test-gen")
 - **Test Validation** → `@test-fix-agent` (type: "test-fix")
-- **Review** → `@general-purpose` (optional)
+- **Review** → `@universal-executor` (optional)
 
 ### Context Inheritance
 - Subtasks inherit parent requirements
@@ -138,7 +137,6 @@ Files updated: .task/IMPL-1.json + 2 subtask files + TODO_LIST.md
 
 ## Implementation Details
 
-See @~/.claude/workflows/workflow-architecture.md for:
 - Complete task JSON schema
 - Implementation field structure
 - Context inheritance rules
@@ -169,45 +167,38 @@ See @~/.claude/workflows/workflow-architecture.md for:
 ```bash
 /task:breakdown impl-1
 
-▸ impl-1: Build authentication (container)
+impl-1: Build authentication (container)
-  ├── impl-1.1: Design schema → @planning-agent
+  ├── impl-1.1: Design schema -> @planning-agent
-  ├── impl-1.2: Implement logic + tests → @code-developer
+  ├── impl-1.2: Implement logic + tests -> @code-developer
-  └── impl-1.3: Execute & fix tests → @test-fix-agent
+  └── impl-1.3: Execute & fix tests -> @test-fix-agent
 ```
 
 ## Error Handling
 
 ```bash
 # Task not found
-❌ Task IMPL-5 not found
+Task IMPL-5 not found
 
 # Already broken down
-⚠️ Task IMPL-1 already has subtasks
+Task IMPL-1 already has subtasks
 
 # Wrong status
-❌ Cannot breakdown completed task IMPL-2
+Cannot breakdown completed task IMPL-2
 
 # 10-task limit exceeded
-❌ Breakdown would exceed 10-task limit (current: 8, proposed: 4)
+Breakdown would exceed 10-task limit (current: 8, proposed: 4)
-   Suggestion: Re-scope project into smaller iterations
+Suggestion: Re-scope project into smaller iterations
 
 # File conflicts detected
-⚠️ File conflict: routes/auth.js appears in IMPL-1.1 and IMPL-1.2
+File conflict: routes/auth.js appears in IMPL-1.1 and IMPL-1.2
-   Recommendation: Merge subtasks or redistribute files
+Recommendation: Merge subtasks or redistribute files
 
 # Similar functionality warning
-⚠️ Similar functions detected: "user login" and "authentication"
+Similar functions detected: "user login" and "authentication"
-   Consider consolidating related functionality
+Consider consolidating related functionality
 
 # Manual breakdown required
-❌ Automatic breakdown disabled. Use manual breakdown process.
+Automatic breakdown disabled. Use manual breakdown process.
 ```
 
-## Related Commands
-
-- `/task:create` - Create new tasks
-- `/task:execute` - Execute subtasks
-- `/workflow:status` - View task hierarchy
-- `/workflow:plan` - Plan within 10-task limit
-
 **System ensures**: Manual breakdown control with file cohesion enforcement, similar functionality detection, and 10-task limit compliance

.claude/commands/task/create.md

@@ -37,7 +37,7 @@ Creates new implementation tasks with automatic context awareness and ID generat
 
 Output:
 ```
-✅ Task created: IMPL-1
+Task created: IMPL-1
 Title: Build authentication module
 Type: feature
 Agent: code-developer
@@ -73,7 +73,7 @@ Status: pending
 ### Analysis Triggers
 When implementation details incomplete:
 ```bash
-⚠️ Task requires analysis for implementation details
+Task requires analysis for implementation details
 Suggest running: gemini analysis for file locations and dependencies
 ```
 
@@ -104,7 +104,7 @@ Based on task type and title keywords:
 - **Design/Plan** → @planning-agent
 - **Test Generation** → @code-developer (type: "test-gen")
 - **Test Execution/Fix** → @test-fix-agent (type: "test-fix")
-- **Review/Audit** → @general-purpose (optional, only when explicitly requested)
+- **Review/Audit** → @universal-executor (optional, only when explicitly requested)
 
 ## Validation Rules
 
@@ -117,16 +117,16 @@ Based on task type and title keywords:
 
 ```bash
 # No workflow session
-❌ No active workflow found
+No active workflow found
-→ Use: /workflow init "project name"
+Use: /workflow init "project name"
 
 # Duplicate task
-⚠️ Similar task exists: IMPL-3
+Similar task exists: IMPL-3
-→ Continue anyway? (y/n)
+Continue anyway? (y/n)
 
 # Max depth exceeded
-❌ Cannot create IMPL-1.2.1 (max 2 levels)
+Cannot create IMPL-1.2.1 (max 2 levels)
-→ Use: IMPL-2 for new main task
+Use: IMPL-2 for new main task
 ```
 
 ## Examples
@@ -135,7 +135,7 @@ Based on task type and title keywords:
 ```bash
 /task:create "Implement user authentication"
 
-✅ Created IMPL-1: Implement user authentication
+Created IMPL-1: Implement user authentication
 Type: feature
 Agent: code-developer
 Status: pending
@@ -145,14 +145,8 @@ Status: pending
 ```bash
 /task:create "Fix login validation bug" --type=bugfix
 
-✅ Created IMPL-2: Fix login validation bug
+Created IMPL-2: Fix login validation bug
 Type: bugfix
 Agent: code-developer
 Status: pending
-```
+```
-
-## Related Commands
-
-- `/task:breakdown` - Break into subtasks
-- `/task:execute` - Execute with agent
-- `/context` - View task details

.claude/commands/task/execute.md

@@ -4,12 +4,12 @@ description: Execute tasks with appropriate agents and context-aware orchestrati
 argument-hint: "task-id"
 ---
 
-### 🚀 **Command Overview: `/task:execute`**
+## Command Overview: /task:execute
 
--   **Purpose**: Executes tasks using intelligent agent selection, context preparation, and progress tracking.
+**Purpose**: Executes tasks using intelligent agent selection, context preparation, and progress tracking.
--   **Core Principles**: @~/.claude/workflows/workflow-architecture.md
 
-### ⚙️ **Execution Modes**
+
+## Execution Modes
 
 -   **auto (Default)**
     -   Fully autonomous execution with automatic agent selection.
@@ -19,10 +19,10 @@ argument-hint: "task-id"
     -   Executes step-by-step, requiring user confirmation at each checkpoint.
     -   Allows for dynamic adjustments and manual review during the process.
 -   **review**
-    -   Optional manual review using `@general-purpose`.
+    -   Optional manual review using `@universal-executor`.
     -   Used only when explicitly requested by user.
 
-### 🤖 **Agent Selection Logic**
+## Agent Selection Logic
 
 The system determines the appropriate agent for a task using the following logic.
 
@@ -45,18 +45,18 @@ FUNCTION select_agent(task, agent_override):
             WHEN CONTAINS "Execute tests", "Fix tests", "Validate":
                 RETURN "@test-fix-agent" // type: test-fix
             WHEN CONTAINS "Review code":
-                RETURN "@general-purpose" // Optional manual review
+                RETURN "@universal-executor" // Optional manual review
             DEFAULT:
                 RETURN "@code-developer" // Default agent
         END CASE
 END FUNCTION
 ```
 
-### 🔄 **Core Execution Protocol**
+## Core Execution Protocol
 
-`Pre-Execution` **->** `Execution` **->** `Post-Execution`
+`Pre-Execution` -> `Execution` -> `Post-Execution`
 
-### ✅ **Pre-Execution Protocol**
+### Pre-Execution Protocol
 
 `Validate Task & Dependencies` **->** `Prepare Execution Context` **->** `Coordinate with TodoWrite`
 
@@ -65,7 +65,7 @@ END FUNCTION
 -   **Session Context Injection**: Provides workflow directory paths to agents for TODO_LIST.md and summary management.
 -   **TodoWrite Coordination**: Generates execution Todos and checkpoints, syncing with `TODO_LIST.md`.
 
-### 🏁 **Post-Execution Protocol**
+### Post-Execution Protocol
 
 `Update Task Status` **->** `Generate Summary` **->** `Save Artifacts` **->** `Sync All Progress` **->** `Validate File Integrity`
 
@@ -73,7 +73,7 @@ END FUNCTION
 -   Creates a summary in `.summaries/`.
 -   Stores outputs and syncs progress across the entire workflow session.
 
-### 🧠 **Task & Subtask Execution Logic**
+### Task & Subtask Execution Logic
 
 This logic defines how single, multiple, or parent tasks are handled.
 
@@ -99,7 +99,7 @@ FUNCTION execute_task_command(task_id, mode, parallel_flag):
 END FUNCTION
 ```
 
-### 🛡️ **Error Handling & Recovery Logic**
+### Error Handling & Recovery Logic
 
 ```pseudo
 FUNCTION pre_execution_check(task):
@@ -124,7 +124,7 @@ END FUNCTION
 ```
 
 
-### 📄 **Simplified Context Structure (JSON)**
+### Simplified Context Structure (JSON)
 
 This is the simplified data structure loaded to provide context for task execution.
 
@@ -189,7 +189,7 @@ This is the simplified data structure loaded to provide context for task executi
       "pre_analysis": [
         {
           "action": "analyze patterns",
-          "template": "~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt",
+          "template": "~/.claude/workflows/cli-templates/prompts/analysis/02-analyze-code-patterns.txt",
           "method": "gemini"
         }
       ]
@@ -213,7 +213,7 @@ This is the simplified data structure loaded to provide context for task executi
 }
 ```
 
-### 🎯 **Agent-Specific Context**
+### Agent-Specific Context
 
 Different agents receive context tailored to their function, including implementation details:
 
@@ -236,20 +236,20 @@ Different agents receive context tailored to their function, including implement
 - Error conditions to validate from implementation.context_notes.error_handling
 - Performance requirements from implementation.context_notes.performance_considerations
 
-**`@general-purpose`**:
+**`@universal-executor`**:
 - Used for optional manual reviews when explicitly requested
 - Code quality standards and implementation patterns
 - Security considerations from implementation.context_notes.risks
 - Dependency validation from implementation.context_notes.dependencies
 - Architecture compliance checks
 
-### 🗃️ **Simplified File Output**
+### Simplified File Output
 
 -   **Task JSON File (`.task/<task-id>.json`)**: Updated with status and last attempt time only.
 -   **Session File (`workflow-session.json`)**: Updated task stats (completed count).
 -   **Summary File**: Generated in `.summaries/` upon completion (optional).
 
-### 📝 **Simplified Summary Template**
+### Simplified Summary Template
 
 Optional summary file generated at `.summaries/IMPL-[task-id]-summary.md`.
 

.claude/commands/task/replan.md

@@ -24,7 +24,7 @@ Replans individual tasks or batch processes multiple tasks with change tracking
 - **Change Documentation**: Track all modifications
 - **Progress Tracking**: TodoWrite integration for batch operations
 
-⚠️ **CRITICAL**: Validates active session before replanning
+**CRITICAL**: Validates active session before replanning
 
 ## Operation Modes
 
@@ -189,7 +189,7 @@ AskUserQuestion({
 
 User selected: "Yes, rollback"
 
-✅ Task rolled back to version 1.1
+Task rolled back to version 1.1
 ```
 
 ## Batch Processing with TodoWrite
@@ -201,7 +201,7 @@ When processing multiple tasks, automatically creates TodoWrite task list:
 **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-004: Add FR-09 response surface explicit coverage
 - [ ] IMPL-008: Add NFR performance validation steps
 ```
 
@@ -255,9 +255,9 @@ AskUserQuestion({
 
 User selected: "Yes, apply"
 
-✓ Version 1.2 created
+Version 1.2 created
-✓ Context updated
+Context updated
-✓ Backup saved to .task/backup/IMPL-1-v1.1.json
+Backup saved to .task/backup/IMPL-1-v1.1.json
 ```
 
 ### Single Task - File Input
@@ -267,9 +267,9 @@ User selected: "Yes, apply"
 Loading requirements.md...
 Applying specification changes...
 
-✓ Task updated with new requirements
+Task updated with new requirements
-✓ Version 1.1 created
+Version 1.1 created
-✓ Backup saved to .task/backup/IMPL-2-v1.0.json
+Backup saved to .task/backup/IMPL-2-v1.0.json
 ```
 
 ### Batch Mode - From Verification Report
@@ -286,23 +286,23 @@ Found 4 tasks requiring replanning:
 Creating task tracking list...
 
 Processing IMPL-002...
-✓ Backup created: .task/backup/IMPL-002-v1.0.json
+Backup created: .task/backup/IMPL-002-v1.0.json
-✓ Updated to v1.1
+Updated to v1.1
 
 Processing IMPL-003...
-✓ Backup created: .task/backup/IMPL-003-v1.0.json
+Backup created: .task/backup/IMPL-003-v1.0.json
-✓ Updated to v1.1
+Updated to v1.1
 
 Processing IMPL-004...
-✓ Backup created: .task/backup/IMPL-004-v1.0.json
+Backup created: .task/backup/IMPL-004-v1.0.json
-✓ Updated to v1.1
+Updated to v1.1
 
 Processing IMPL-008...
-✓ Backup created: .task/backup/IMPL-008-v1.0.json
+Backup created: .task/backup/IMPL-008-v1.0.json
-✓ Updated to v1.1
+Updated to v1.1
 
-✅ Batch replan completed: 4/4 successful
+Batch replan completed: 4/4 successful
-📋 Summary report saved
+Summary report saved
 ```
 
 ### Batch Mode - Auto-detection
@@ -320,35 +320,35 @@ Entering batch mode...
 ### Single Task Errors
 ```bash
 # Task not found
-❌ Task IMPL-5 not found
+Task IMPL-5 not found
-→ Check task ID with /workflow:status
+Check task ID with /workflow:status
 
 # Task completed
-⚠️ Task IMPL-1 is completed (cannot replan)
+Task IMPL-1 is completed (cannot replan)
-→ Create new task for additional work
+Create new task for additional work
 
 # File not found
-❌ File requirements.md not found
+File requirements.md not found
-→ Check file path
+Check file path
 
 # No input provided
-❌ Please specify changes needed
+Please specify changes needed
-→ Provide text, file, or verification report
+Provide text, file, or verification report
 ```
 
 ### Batch Mode Errors
 ```bash
 # Invalid verification report
-❌ File does not contain valid verification report format
+File does not contain valid verification report format
-→ Check report structure or use single task mode
+Check report structure or use single task mode
 
 # Partial failures
-⚠️ Batch completed with errors: 3/4 successful
+Batch completed with errors: 3/4 successful
-→ Review error details in summary report
+Review error details in summary report
 
 # No replan recommendations found
-❌ Verification report contains no replan recommendations
+Verification report contains no replan recommendations
-→ Check report content or use /workflow:action-plan-verify first
+Check report content or use /workflow:action-plan-verify first
 ```
 
 ## Batch Mode Integration
@@ -429,16 +429,4 @@ TodoWrite({
 TodoWrite({
   todos: updateTaskStatus(taskId, "completed")
 });
-```
+```
-
-## Related Commands
-
-- `/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
-- `/task:breakdown` - Break down complex tasks
-
-## Context
-
-$ARGUMENTS

.claude/commands/version.md

@@ -152,12 +152,12 @@ bash(printf "%s\n%s" "3.2.1" "3.2.2" | sort -V | tail -n 1)
 
 **Scenario 1: Up to date**
 ```
-✅ You are on the latest stable version (3.2.1)
+You are on the latest stable version (3.2.1)
 ```
 
 **Scenario 2: Upgrade available**
 ```
-⬆️ A newer stable version is available: v3.2.2
+A newer stable version is available: v3.2.2
 Your version: 3.2.1
 
 To upgrade:
@@ -167,7 +167,7 @@ Bash: bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-W
 
 **Scenario 3: Development version**
 ```
-✨ You are running a development version (3.4.0-dev)
+You are running a development version (3.4.0-dev)
 This is newer than the latest stable release (v3.3.0)
 ```
 
@@ -252,7 +252,3 @@ ERROR: version.json is invalid or corrupted
 
 ### Timeout Configuration
 All network calls should use `timeout: 30000` (30 seconds) to handle slow connections.
-
-## Related Commands
-- `/cli:cli-init` - Initialize CLI configurations
-- `/workflow:session:list` - List workflow sessions

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

@@ -15,13 +15,13 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 ## Goal
 
-Identify inconsistencies, duplications, ambiguities, and underspecified items between action planning artifacts (`IMPL_PLAN.md`, `task.json`) and brainstorming artifacts (`synthesis-specification.md`) before implementation. This command MUST run only after `/workflow:plan` has successfully produced complete `IMPL_PLAN.md` and task JSON files.
+Identify inconsistencies, duplications, ambiguities, and underspecified items between action planning artifacts (`IMPL_PLAN.md`, `task.json`) and brainstorming artifacts (`role analysis documents`) before implementation. This command MUST run only after `/workflow:plan` has successfully produced complete `IMPL_PLAN.md` and task JSON files.
 
 ## Operating Constraints
 
 **STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands).
 
-**Synthesis Authority**: The `synthesis-specification.md` is **authoritative** for requirements and design decisions. Any conflicts between IMPL_PLAN/tasks and synthesis are automatically CRITICAL and require adjustment of the plan/tasks—not reinterpretation of requirements.
+**Synthesis Authority**: The `role analysis documents` is **authoritative** for requirements and design decisions. Any conflicts between IMPL_PLAN/tasks and synthesis are automatically CRITICAL and require adjustment of the plan/tasks—not reinterpretation of requirements.
 
 ## Execution Steps
 
@@ -45,13 +45,13 @@ brainstorm_dir = session_dir/.brainstorming
 task_dir = session_dir/.task
 
 # Validate required artifacts
-SYNTHESIS = brainstorm_dir/synthesis-specification.md
+SYNTHESIS = brainstorm_dir/role analysis documents
 IMPL_PLAN = session_dir/IMPL_PLAN.md
 TASK_FILES = Glob(task_dir/*.json)
 
 # Abort if missing
 IF NOT EXISTS(SYNTHESIS):
-    ERROR: "synthesis-specification.md not found. Run /workflow:brainstorm:synthesis first"
+    ERROR: "role analysis documents not found. Run /workflow:brainstorm:synthesis first"
     EXIT
 
 IF NOT EXISTS(IMPL_PLAN):
@@ -67,7 +67,12 @@ IF TASK_FILES.count == 0:
 
 Load only minimal necessary context from each artifact:
 
-**From synthesis-specification.md**:
+**From workflow-session.json** (NEW - PRIMARY REFERENCE):
+- Original user prompt/intent (project or description field)
+- User's stated goals and objectives
+- User's scope definition
+
+**From role analysis documents**:
 - Functional Requirements (IDs, descriptions, acceptance criteria)
 - Non-Functional Requirements (IDs, targets)
 - Business Requirements (IDs, success metrics)
@@ -117,7 +122,14 @@ Create internal representations (do not include raw artifacts in output):
 
 Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
 
-#### A. Requirements Coverage Analysis
+#### A. User Intent Alignment (NEW - CRITICAL)
+
+- **Goal Alignment**: IMPL_PLAN objectives match user's original intent
+- **Scope Drift**: Plan covers user's stated scope without unauthorized expansion
+- **Success Criteria Match**: Plan's success criteria reflect user's expectations
+- **Intent Conflicts**: Tasks contradicting user's original objectives
+
+#### B. Requirements Coverage Analysis
 
 - **Orphaned Requirements**: Requirements in synthesis with zero associated tasks
 - **Unmapped Tasks**: Tasks with no clear requirement linkage
@@ -167,6 +179,7 @@ Focus on high-signal findings. Limit to 50 findings total; aggregate remainder i
 Use this heuristic to prioritize findings:
 
 - **CRITICAL**:
+  - Violates user's original intent (goal misalignment, scope drift)
   - Violates synthesis authority (requirement conflict)
   - Core requirement with zero coverage
   - Circular dependencies
@@ -197,7 +210,7 @@ Output a Markdown report (no file writes) with the following structure:
 
 **Session**: WFS-{session-id}
 **Generated**: {timestamp}
-**Artifacts Analyzed**: synthesis-specification.md, IMPL_PLAN.md, {N} task files
+**Artifacts Analyzed**: role analysis documents, IMPL_PLAN.md, {N} task files
 
 ---
 
@@ -229,10 +242,10 @@ Output a Markdown report (no file writes) with the following structure:
 
 | Requirement ID | Requirement Summary | Has Task? | Task IDs | Priority Match | Notes |
 |----------------|---------------------|-----------|----------|----------------|-------|
-| FR-01 | User authentication | ✅ Yes | IMPL-1.1, IMPL-1.2 | ✅ Match | Complete |
+| FR-01 | User authentication | Yes | IMPL-1.1, IMPL-1.2 | Match | Complete |
-| FR-02 | Data export | ✅ Yes | IMPL-2.3 | ⚠️ Mismatch | High req → Med priority task |
+| FR-02 | Data export | Yes | IMPL-2.3 | Mismatch | High req → Med priority task |
-| FR-03 | Profile management | ❌ No | - | - | **CRITICAL: Zero coverage** |
+| FR-03 | Profile management | No | - | - | **CRITICAL: Zero coverage** |
-| NFR-01 | Response time <200ms | ❌ No | - | - | **HIGH: No performance tasks** |
+| NFR-01 | Response time <200ms | No | - | - | **HIGH: No performance tasks** |
 
 **Coverage Metrics**:
 - Functional Requirements: 85% (17/20 covered)
@@ -251,7 +264,7 @@ Output a Markdown report (no file writes) with the following structure:
 
 ### Dependency Graph Issues
 
-**Circular Dependencies**: None detected ✅
+**Circular Dependencies**: None detected
 
 **Broken Dependencies**:
 - IMPL-2.3 depends on "IMPL-2.4" (non-existent)
@@ -310,45 +323,41 @@ Output a Markdown report (no file writes) with the following structure:
 #### Action Recommendations
 
 **If CRITICAL Issues Exist**:
-- ❌ **BLOCK EXECUTION** - Resolve critical issues before proceeding
+- **BLOCK EXECUTION** - Resolve critical issues before proceeding
-- Use `/task:create` for missing requirements coverage
+- Use TodoWrite to track all required fixes
 - Fix broken dependencies and circular references
 
 **If Only HIGH/MEDIUM/LOW Issues**:
-- ⚠️ **PROCEED WITH CAUTION** - Fix high-priority issues first
+- **PROCEED WITH CAUTION** - Fix high-priority issues first
-- Use batch replan mode to apply all task improvements systematically
+- Use TodoWrite to systematically track and complete all improvements
 
-#### Batch Remediation
+#### TodoWrite-Based Remediation Workflow
 
 **Report Location**: `.workflow/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md`
 
-**Apply All Task Improvements** (Recommended):
+**Recommended Workflow**:
-```bash
+1. **Create TodoWrite Task List**: Extract all findings from report
-# Batch process all task replan recommendations
+2. **Process by Priority**: CRITICAL → HIGH → MEDIUM → LOW
-/task:replan --batch .workflow/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md
+3. **Complete Each Fix**: Mark tasks as in_progress/completed as you work
+4. **Validate Changes**: Verify each modification against requirements
 
-# Or with auto-confirmation (no prompts)
+**TodoWrite Task Structure Example**:
-/task:replan --batch ACTION_PLAN_VERIFICATION.md --auto-confirm
+```markdown
-```
+Priority Order:
-
+1. Fix coverage gaps (CRITICAL)
-**Manual Selective Fixes**:
+2. Resolve consistency conflicts (CRITICAL/HIGH)
-```bash
+3. Add missing specifications (MEDIUM)
-# Fix critical coverage gaps first
+4. Improve task quality (LOW)
-/task:create "Implement user authentication (FR-03)"
-/task:create "Add performance optimization (NFR-01)"
-
-# Then apply task refinements individually
-/task:replan IMPL-1.2 "Add context.artifacts and target_files"
 ```
 
 **Notes**:
-- Batch mode extracts all `/task:replan` commands from report
+- TodoWrite provides real-time progress tracking
-- Processes by priority: CRITICAL → HIGH → MEDIUM → LOW
+- Each finding becomes a trackable todo item
-- Creates TodoWrite tracking for all modifications
+- User can monitor progress throughout remediation
 - Architecture drift in IMPL_PLAN requires manual editing
 ```
 
-### 7. Save Report and Provide Remediation Options
+### 7. Save Report and Execute TodoWrite-Based Remediation
 
 **Save Analysis Report**:
 ```bash
@@ -356,87 +365,53 @@ report_path = ".workflow/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md"
 Write(report_path, full_report_content)
 ```
 
-At end of report, provide batch remediation guidance:
+**After Report Generation**:
+
+1. **Extract Findings**: Parse all issues by severity
+2. **Create TodoWrite Task List**: Convert findings to actionable todos
+3. **Execute Fixes**: Process each todo systematically
+4. **Update Task Files**: Apply modifications directly to task JSON files
+5. **Update IMPL_PLAN**: Apply strategic changes if needed
+
+At end of report, provide remediation guidance:
 
 ```markdown
-### 🔧 Remediation Options
+### 🔧 Remediation Workflow
 
-**Recommended Workflow**:
+**Recommended Approach**:
-1. **Batch Mode** (Fastest): Apply all task improvements automatically
+1. **Initialize TodoWrite**: Create comprehensive task list from all findings
-   ```bash
+2. **Process by Severity**: Start with CRITICAL, then HIGH, MEDIUM, LOW
-   /task:replan --batch .workflow/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md
+3. **Apply Fixes Directly**: Modify task.json files and IMPL_PLAN.md as needed
-   ```
+4. **Track Progress**: Mark todos as completed after each fix
 
-2. **Manual Review**: Examine each issue before applying
+**TodoWrite Execution Pattern**:
-   - Review findings in this report
+```bash
-   - Execute specific `/task:create` or `/task:replan` commands individually
+# Step 1: Create task list from verification report
+TodoWrite([
+  { content: "Fix FR-03 coverage gap - add authentication task", status: "pending", activeForm: "Fixing FR-03 coverage gap" },
+  { content: "Fix IMPL-1.2 consistency - align with ADR-02", status: "pending", activeForm: "Fixing IMPL-1.2 consistency" },
+  { content: "Add context.artifacts to IMPL-1.2", status: "pending", activeForm: "Adding context.artifacts to IMPL-1.2" },
+  # ... additional todos for each finding
+])
 
-3. **Architecture Changes**: Update IMPL_PLAN.md manually if architecture drift detected
+# Step 2: Process each todo systematically
-
+# Mark as in_progress when starting
-**Note**: This is read-only analysis. All fixes require explicit execution.
+# Apply fix using Read/Edit tools
+# Mark as completed when done
+# Move to next priority item
 ```
 
-### 8. Update Session Metadata
+**File Modification Workflow**:
+```bash
+# For task JSON modifications:
+1. Read(.workflow/WFS-{session}/.task/IMPL-X.Y.json)
+2. Edit() to apply fixes
+3. Mark todo as completed
 
-```json
+# For IMPL_PLAN modifications:
-{
+1. Read(.workflow/WFS-{session}/IMPL_PLAN.md)
-  "phases": {
+2. Edit() to apply strategic changes
-    "PLAN": {
+3. Mark todo as completed
-      "status": "completed",
-      "action_plan_verification": {
-        "completed": true,
-        "completed_at": "timestamp",
-        "overall_risk_level": "HIGH",
-        "recommendation": "PROCEED_WITH_FIXES",
-        "issues": {
-          "critical": 2,
-          "high": 5,
-          "medium": 8,
-          "low": 3
-        },
-        "coverage": {
-          "functional_requirements": 0.85,
-          "non_functional_requirements": 0.40,
-          "business_requirements": 1.00
-        },
-        "report_path": ".workflow/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md"
-      }
-    }
-  }
-}
 ```
 
-## Operating Principles
+**Note**: All fixes execute immediately after user confirmation without additional commands.
-
-### Context Efficiency
-- **Minimal high-signal tokens**: Focus on actionable findings
-- **Progressive disclosure**: Load artifacts incrementally
-- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow
-- **Deterministic results**: Rerunning without changes produces consistent IDs and counts
-
-### Analysis Guidelines
-- **NEVER modify files** (this is read-only analysis)
-- **NEVER hallucinate missing sections** (if absent, report them accurately)
-- **Prioritize synthesis violations** (these are always CRITICAL)
-- **Use examples over exhaustive rules** (cite specific instances)
-- **Report zero issues gracefully** (emit success report with coverage statistics)
-
-### Verification Taxonomy
-- **Coverage**: Requirements → Tasks mapping
-- **Consistency**: Cross-artifact alignment
-- **Dependencies**: Task ordering and relationships
-- **Synthesis Alignment**: Adherence to authoritative requirements
-- **Task Quality**: Specification completeness
-- **Feasibility**: Implementation risks
-
-## Behavior Rules
-
-- **If no issues found**: Report "✅ Action plan verification passed. No issues detected." and suggest proceeding to `/workflow:execute`.
-- **If CRITICAL issues exist**: Recommend blocking execution until resolved.
-- **If only HIGH/MEDIUM issues**: User may proceed with caution, but provide improvement suggestions.
-- **If IMPL_PLAN.md or task files missing**: Instruct user to run `/workflow:plan` first.
-- **Always provide actionable remediation suggestions**: Don't just identify problems—suggest solutions.
-
-## Context
-
-{ARGS}

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

@@ -1,6 +1,6 @@
 ---
 name: api-designer
-description: Generate or update api-designer/analysis.md addressing topic-framework discussion points
+description: Generate or update api-designer/analysis.md addressing guidance-specification discussion points
 argument-hint: "optional topic - uses existing framework if available"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
@@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ## 🔌 **API Designer Analysis Generator**
 
 ### Purpose
-**Specialized command for generating api-designer/analysis.md** that addresses topic-framework.md discussion points from backend API design perspective. Creates or updates role-specific analysis with framework references.
+**Specialized command for generating api-designer/analysis.md** that addresses guidance-specification.md discussion points from backend API design perspective. Creates or updates role-specific analysis with framework references.
 
 ### Core Function
-- **Framework-based Analysis**: Address each discussion point in topic-framework.md
+- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
 - **API Design Focus**: RESTful/GraphQL API design, endpoint structure, and contract definition
 - **Update Mechanism**: Create new or update existing analysis.md
 - **Agent Delegation**: Use conceptual-planning-agent for analysis generation
@@ -51,7 +51,7 @@ IF active_session EXISTS:
     session_id = get_active_session()
     brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
 
-    CHECK: brainstorm_dir/topic-framework.md
+    CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
         framework_mode = true
         load_framework = true
@@ -78,20 +78,20 @@ ELSE:
 ```
 
 ### Phase 3: Agent Task Generation
-**Framework-Based Analysis** (when topic-framework.md exists):
+**Framework-Based Analysis** (when guidance-specification.md exists):
 ```bash
 Task(subagent_type="conceptual-planning-agent",
      prompt="Generate API designer analysis addressing topic framework
 
      ## Framework Integration Required
-     **MANDATORY**: Load and address topic-framework.md discussion points
+     **MANDATORY**: Load and address guidance-specification.md discussion points
-     **Framework Reference**: @{session.brainstorm_dir}/topic-framework.md
+     **Framework Reference**: @{session.brainstorm_dir}/guidance-specification.md
      **Output Location**: {session.brainstorm_dir}/api-designer/analysis.md
 
      ## Analysis Requirements
-     1. **Load Topic Framework**: Read topic-framework.md completely
+     1. **Load Topic Framework**: Read guidance-specification.md completely
      2. **Address Each Discussion Point**: Respond to all 5 framework sections from API design perspective
-     3. **Include Framework Reference**: Start analysis.md with @../topic-framework.md
+     3. **Include Framework Reference**: Start analysis.md with @../guidance-specification.md
      4. **API Design Focus**: Emphasize endpoint structure, data contracts, versioning strategies
      5. **Structured Response**: Use framework structure for analysis organization
 
@@ -106,7 +106,7 @@ Task(subagent_type="conceptual-planning-agent",
      ```markdown
      # API Designer Analysis: [Topic]
 
-     **Framework Reference**: @../topic-framework.md
+     **Framework Reference**: @../guidance-specification.md
      **Role Focus**: Backend API Design and Contract Definition
 
      ## Core Requirements Analysis
@@ -140,14 +140,14 @@ IF update_mode = "incremental":
 
          ## Current Analysis Context
          **Existing Analysis**: @{session.brainstorm_dir}/api-designer/analysis.md
-         **Framework Reference**: @{session.brainstorm_dir}/topic-framework.md
+         **Framework Reference**: @{session.brainstorm_dir}/guidance-specification.md
 
          ## Update Requirements
          1. **Preserve Structure**: Maintain existing analysis structure
          2. **Add New Insights**: Integrate new API design insights and recommendations
          3. **Framework Alignment**: Ensure continued alignment with topic framework
          4. **API Updates**: Add new endpoint patterns, versioning strategies, documentation improvements
-         5. **Maintain References**: Keep @../topic-framework.md reference
+         5. **Maintain References**: Keep @../guidance-specification.md reference
 
          ## Update Instructions
          - Read existing analysis completely
@@ -163,14 +163,14 @@ IF update_mode = "incremental":
 ### Output Files
 ```
 .workflow/WFS-[topic]/.brainstorming/
-├── topic-framework.md          # Input: Framework (if exists)
+├── guidance-specification.md          # Input: Framework (if exists)
 └── api-designer/
     └── analysis.md            # ★ OUTPUT: Framework-based analysis
 ```
 
 ### Analysis Structure
 **Required Elements**:
-- **Framework Reference**: @../topic-framework.md (if framework exists)
+- **Framework Reference**: @../guidance-specification.md (if framework exists)
 - **Role Focus**: Backend API Design and Contract Definition perspective
 - **5 Framework Sections**: Address each framework discussion point
 - **API Design Recommendations**: Endpoint-specific insights and solutions

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

@@ -1,366 +1,605 @@
 ---
 name: artifacts
-description: Generate role-specific topic-framework.md dynamically based on selected roles
+description: Interactive clarification generating confirmed guidance specification
-argument-hint: "topic or challenge description for framework generation"
+argument-hint: "topic or challenge description [--count N]"
-allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*)
+allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*)
 ---
 
-# Topic Framework Generator Command
+## Overview
 
-## Usage
+Six-phase workflow: **Automatic project context collection** → Extract topic challenges → Select roles → Generate task-specific questions → Detect conflicts → Generate confirmed guidance (declarative statements only).
-```bash
+
-/workflow:brainstorm:artifacts "<topic>" [--roles "role1,role2,role3"]
+**Input**: `"GOAL: [objective] SCOPE: [boundaries] CONTEXT: [background]" [--count N]`
+**Output**: `.workflow/WFS-{topic}/.brainstorming/guidance-specification.md` (CONFIRMED/SELECTED format)
+**Core Principle**: Questions dynamically generated from project context + topic keywords/challenges, NOT from generic templates
+
+**Parameters**:
+- `topic` (required): Topic or challenge description (structured format recommended)
+- `--count N` (optional): Number of roles user WANTS to select (system will recommend N+2 options for user to choose from, default: 3)
+
+## Task Tracking
+
+**⚠️ TodoWrite Rule**: EXTEND auto-parallel's task list (NOT replace/overwrite)
+
+**When called from auto-parallel**:
+- Find the artifacts parent task: "Execute artifacts command for interactive framework generation"
+- Mark parent task as "in_progress"
+- APPEND artifacts sub-tasks AFTER the parent task (Phase 0-5)
+- Mark each sub-task as it completes
+- When Phase 5 completes, mark parent task as "completed"
+- **PRESERVE all other auto-parallel tasks** (role agents, synthesis)
+
+**Standalone Mode**:
+```json
+[
+  {"content": "Initialize session (.workflow/.active-* check, parse --count parameter)", "status": "pending", "activeForm": "Initializing"},
+  {"content": "Phase 0: Automatic project context collection (call context-gather)", "status": "pending", "activeForm": "Phase 0 context collection"},
+  {"content": "Phase 1: Extract challenges, output 2-4 task-specific questions, wait for user input", "status": "pending", "activeForm": "Phase 1 topic analysis"},
+  {"content": "Phase 2: Recommend count+2 roles, output role selection, wait for user input", "status": "pending", "activeForm": "Phase 2 role selection"},
+  {"content": "Phase 3: Generate 3-4 questions per role, output and wait for answers (max 10 per round)", "status": "pending", "activeForm": "Phase 3 role questions"},
+  {"content": "Phase 4: Detect conflicts, output clarifications, wait for answers (max 10 per round)", "status": "pending", "activeForm": "Phase 4 conflict resolution"},
+  {"content": "Phase 5: Transform Q&A to declarative statements, write guidance-specification.md", "status": "pending", "activeForm": "Phase 5 document generation"}
+]
 ```
 
-## Purpose
+## User Interaction Protocol
-**Generate dynamic topic-framework.md tailored to selected roles**. Creates role-specific discussion frameworks that address relevant perspectives. If no roles specified, generates comprehensive framework covering common analysis areas.
 
-## Role-Based Framework Generation
+### Question Output Format
 
-**Dynamic Generation**: Framework content adapts based on selected roles
+All questions output as structured text (detailed format with descriptions):
-- **With roles**: Generate targeted discussion points for specified roles only
-- **Without roles**: Generate comprehensive framework covering all common areas
 
-## Core Workflow
-
-### Topic Framework Generation Process
-
-**Phase 1: Session Management** ⚠️ FIRST STEP
-- **Active session detection**: Check `.workflow/.active-*` markers
-- **Session selection**: Prompt user if multiple active sessions found
-- **Auto-creation**: Create `WFS-[topic-slug]` only if no active session exists
-- **Framework check**: Check if `topic-framework.md` exists (update vs create mode)
-
-**Phase 2: Role Analysis** ⚠️ NEW
-- **Parse roles parameter**: Extract roles from `--roles "role1,role2,role3"` if provided
-- **Role validation**: Verify each role is valid (matches available role commands)
-- **Store role list**: Save selected roles to session metadata for reference
-- **Default behavior**: If no roles specified, use comprehensive coverage
-
-**Phase 3: Dynamic Topic Analysis**
-- **Scope definition**: Define topic boundaries and objectives
-- **Stakeholder identification**: Identify key users and stakeholders based on selected roles
-- **Requirements gathering**: Extract requirements relevant to selected roles
-- **Context collection**: Gather context appropriate for role perspectives
-
-**Phase 4: Role-Specific Framework Generation**
-- **Discussion points creation**: Generate 3-5 discussion areas **tailored to selected roles**
-- **Role-targeted questions**: Create questions specifically for chosen roles
-- **Framework document**: Generate `topic-framework.md` with role-specific sections
-- **Validation check**: Ensure framework addresses all selected role perspectives
-
-**Phase 5: Metadata Storage**
-- **Save role assignment**: Store selected roles in session metadata
-- **Framework versioning**: Track which roles framework addresses
-- **Update tracking**: Maintain role evolution if framework updated
-
-## Implementation Standards
-
-### Discussion-Driven Analysis
-**Interactive Approach**: Direct conversation and exploration without predefined role constraints
-
-**Process Flow**:
-1. **Topic introduction**: Understanding scope and context
-2. **Exploratory questioning**: Open-ended investigation
-3. **Component identification**: Breaking down into manageable pieces
-4. **Relationship analysis**: Understanding connections and dependencies
-5. **Documentation generation**: Structured capture of insights
-
-**Key Areas of Investigation**:
-- **Functional aspects**: What the topic needs to accomplish
-- **Technical considerations**: Implementation constraints and requirements
-- **User perspectives**: How different stakeholders are affected
-- **Business implications**: Cost, timeline, and strategic considerations
-- **Risk assessment**: Potential challenges and mitigation strategies
-
-### Document Generation Standards
-
-**Always Created**:
-- **discussion-summary.md**: Main conversation points and key insights
-- **component-analysis.md**: Detailed breakdown of topic components
-
-## Document Generation
-
-**Primary Output**: Single structured `topic-framework.md` document
-
-**Document Structure**:
-```
-.workflow/WFS-[topic]/.brainstorming/
-└── topic-framework.md          # ★ STRUCTURED FRAMEWORK DOCUMENT
-```
-
-**Note**: `workflow-session.json` is located at `.workflow/WFS-[topic]/workflow-session.json` (session root), not inside `.brainstorming/`.
-
-## Framework Template Structures
-
-### Dynamic Role-Based Framework
-
-Framework content adapts based on `--roles` parameter:
-
-#### Option 1: Specific Roles Provided
 ```markdown
-# [Topic] - Discussion Framework
+【问题{N} - {短标签}】{问题文本}
+a) {选项标签}
+   说明：{选项说明和影响}
+b) {选项标签}
+   说明：{选项说明和影响}
+c) {选项标签}
+   说明：{选项说明和影响}
 
-## Topic Overview
+请回答：{N}a 或 {N}b 或 {N}c
-- **Scope**: [Topic boundaries relevant to selected roles]
-- **Objectives**: [Goals from perspective of selected roles]
-- **Context**: [Background focusing on role-specific concerns]
-- **Target Roles**: ui-designer, system-architect, subject-matter-expert
-
-## Role-Specific Discussion Points
-
-### For UI Designer
-1. **User Interface Requirements**
-   - What interface components are needed?
-   - What user interactions must be supported?
-   - What visual design considerations apply?
-
-2. **User Experience Challenges**
-   - What are the key user journeys?
-   - What accessibility requirements exist?
-   - How to balance aesthetics with functionality?
-
-### For System Architect
-1. **Architecture Decisions**
-   - What architectural patterns fit this solution?
-   - What scalability requirements exist?
-   - How does this integrate with existing systems?
-
-2. **Technical Implementation**
-   - What technology stack is appropriate?
-   - What are the performance requirements?
-   - What dependencies must be managed?
-
-### For Subject Matter Expert
-1. **Domain Expertise & Standards**
-   - What industry standards and best practices apply?
-   - What regulatory compliance requirements exist?
-   - What domain-specific patterns should be followed?
-
-2. **Technical Quality & Risk**
-   - What technical debt considerations exist?
-   - What scalability and maintenance implications apply?
-   - What knowledge transfer and documentation is needed?
-
-## Cross-Role Integration Points
-- How do UI decisions impact architecture?
-- How does architecture constrain UI possibilities?
-- What domain standards affect both UI and architecture?
-
-## Framework Usage
-**For Role Agents**: Address your specific section + integration points
-**Reference Format**: @../topic-framework.md in your analysis.md
-**Update Process**: Use /workflow:brainstorm:artifacts to update
-
----
-*Generated for roles: ui-designer, system-architect, subject-matter-expert*
-*Last updated: [timestamp]*
 ```
 
-#### Option 2: No Roles Specified (Comprehensive)
+**Multi-select format** (Phase 2 role selection):
 ```markdown
-# [Topic] - Discussion Framework
+【角色选择】请选择 {count} 个角色参与头脑风暴分析
 
-## Topic Overview
+a) {role-name} ({中文名})
-- **Scope**: [Comprehensive topic boundaries]
+   推荐理由：{基于topic的相关性说明}
-- **Objectives**: [All-encompassing goals]
+b) {role-name} ({中文名})
-- **Context**: [Full background and constraints]
+   推荐理由：{基于topic的相关性说明}
-- **Stakeholders**: [All relevant parties]
+...
 
-## Core Discussion Areas
+支持格式：
+- 分别选择：2a 2c 2d (选择第2题的a、c、d选项)
+- 合并语法：2acd (选择a、c、d)
+- 逗号分隔：2a,c,d
 
-### 1. Requirements & Objectives
+请输入选择：
-- What are the fundamental requirements?
-- What are the critical success factors?
-- What constraints must be considered?
-
-### 2. Technical & Architecture
-- What are the technical challenges?
-- What architectural decisions are needed?
-- What integration points exist?
-
-### 3. User Experience & Design
-- Who are the primary users?
-- What are the key user journeys?
-- What usability requirements exist?
-
-### 4. Security & Compliance
-- What security requirements exist?
-- What compliance considerations apply?
-- What data protection is needed?
-
-### 5. Implementation & Operations
-- What are the implementation risks?
-- What resources are required?
-- How will this be maintained?
-
-## Available Role Perspectives
-Framework supports analysis from any of these roles:
-- **Technical**: system-architect, data-architect, subject-matter-expert
-- **Product & Design**: ui-designer, ux-expert, product-manager, product-owner
-- **Agile & Quality**: scrum-master, test-strategist
-
----
-*Comprehensive framework - adaptable to any role*
-*Last updated: [timestamp]*
 ```
 
-## Role-Specific Content Generation
+### Input Parsing Rules
 
-### Available Roles and Their Focus Areas
+**Supported formats** (intelligent parsing):
 
-**Technical Roles**:
+1. **Space-separated**: `1a 2b 3c` → Q1:a, Q2:b, Q3:c
-- `system-architect`: Architecture patterns, scalability, technology stack, integration
+2. **Comma-separated**: `1a,2b,3c` → Q1:a, Q2:b, Q3:c
-- `data-architect`: Data modeling, processing workflows, analytics, storage
+3. **Multi-select combined**: `2abc` → Q2: options a,b,c
-- `subject-matter-expert`: Domain expertise, industry standards, compliance, best practices
+4. **Multi-select spaces**: `2 a b c` → Q2: options a,b,c
+5. **Multi-select comma**: `2a,b,c` → Q2: options a,b,c
+6. **Natural language**: `问题1选a` → 1a (fallback parsing)
 
-**Product & Design Roles**:
+**Parsing algorithm**:
-- `ui-designer`: User interface, visual design, interaction patterns, accessibility
+- Extract question numbers and option letters
-- `ux-expert`: User experience optimization, usability testing, interaction design, design systems
+- Validate question numbers match output
-- `product-manager`: Business value, feature prioritization, market positioning, roadmap
+- Validate option letters exist for each question
-- `product-owner`: Backlog management, user stories, acceptance criteria, stakeholder alignment
+- If ambiguous/invalid, output example format and request re-input
 
-**Agile & Quality Roles**:
+**Error handling** (lenient):
-- `scrum-master`: Sprint planning, team dynamics, process optimization, delivery management
+- Recognize common variations automatically
-- `test-strategist`: Testing strategies, quality assurance, test automation, validation approaches
+- If parsing fails, show example and wait for clarification
+- Support re-input without penalty
 
-### Dynamic Discussion Point Generation
+### Batching Strategy
 
-**For each selected role, generate**:
+**Batch limits**:
-1. **2-3 core discussion areas** specific to that role's perspective
+- **Default**: Maximum 10 questions per round
-2. **3-5 targeted questions** per discussion area
+- **Phase 2 (role selection)**: Display all recommended roles at once (count+2 roles)
-3. **Cross-role integration points** showing how roles interact
+- **Auto-split**: If questions > 10, split into multiple rounds with clear round indicators
 
-**Example mapping**:
+**Round indicators**:
+```markdown
+===== 第 1 轮问题 (共2轮) =====
+【问题1 - ...】...
+【问题2 - ...】...
+...
+【问题10 - ...】...
+
+请回答 (格式: 1a 2b ... 10c)：
+```
+
+### Interaction Flow
+
+**Standard flow**:
+1. Output questions in formatted text
+2. Output expected input format example
+3. Wait for user input
+4. Parse input with intelligent matching
+5. If parsing succeeds → Store answers and continue
+6. If parsing fails → Show error, example, and wait for re-input
+
+**No question/option limits**: Text-based interaction removes previous 4-question and 4-option restrictions
+
+## Execution Phases
+
+### Session Management
+- Check `.workflow/.active-*` markers first
+- Multiple sessions → Prompt selection | Single → Use it | None → Create `WFS-[topic-slug]`
+- Parse `--count N` parameter from user input (default: 3 if not specified)
+- Store decisions in `workflow-session.json` including count parameter
+
+### Phase 0: Automatic Project Context Collection
+
+**Goal**: Gather project architecture, documentation, and relevant code context BEFORE user interaction
+
+**Detection Mechanism** (execute first):
 ```javascript
-// If roles = ["ui-designer", "system-architect"]
+// Check if context-package already exists
-Generate:
+const contextPackagePath = `.workflow/WFS-{session-id}/.process/context-package.json`;
-- UI Designer section: UI Requirements, UX Challenges
+
-- System Architect section: Architecture Decisions, Technical Implementation
+if (file_exists(contextPackagePath)) {
-- Integration Points: UI↔Architecture dependencies
+  // Validate package
+  const package = Read(contextPackagePath);
+  if (package.metadata.session_id === session_id) {
+    console.log("✅ Valid context-package found, skipping Phase 0");
+    return; // Skip to Phase 1
+  }
+}
 ```
 
-### Framework Generation Examples
+**Implementation**: Invoke `context-search-agent` only if package doesn't exist
 
-#### Example 1: Architecture-Heavy Topic
+```javascript
-```bash
+Task(
-/workflow:brainstorm:artifacts "Design scalable microservices platform" --roles "system-architect,data-architect,subject-matter-expert"
+  subagent_type="context-search-agent",
+  description="Gather project context for brainstorm",
+  prompt=`
+You are executing as context-search-agent (.claude/agents/context-search-agent.md).
+
+## Execution Mode
+**BRAINSTORM MODE** (Lightweight) - Phase 1-2 only (skip deep analysis)
+
+## Session Information
+- **Session ID**: ${session_id}
+- **Task Description**: ${task_description}
+- **Output Path**: .workflow/${session_id}/.process/context-package.json
+
+## Mission
+Execute complete context-search-agent workflow for implementation planning:
+
+### Phase 1: Initialization & Pre-Analysis
+1. **Detection**: Check for existing context-package (early exit if valid)
+2. **Foundation**: Initialize code-index, get project structure, load docs
+3. **Analysis**: Extract keywords, determine scope, classify complexity
+
+### Phase 2: Multi-Source Context Discovery
+Execute all 3 discovery tracks:
+- **Track 1**: Reference documentation (CLAUDE.md, architecture docs)
+- **Track 2**: Web examples (use Exa MCP for unfamiliar tech/APIs)
+- **Track 3**: Codebase analysis (5-layer discovery: files, content, patterns, deps, config/tests)
+
+### Phase 3: Synthesis, Assessment & Packaging
+1. Apply relevance scoring and build dependency graph
+2. Synthesize 3-source data (docs > code > web)
+3. Integrate brainstorm artifacts (if .brainstorming/ exists, read content)
+4. Perform conflict detection with risk assessment
+5. Generate and validate context-package.json
+
+## Output Requirements
+Complete context-package.json with:
+- **metadata**: task_description, keywords, complexity, tech_stack, session_id
+- **project_context**: architecture_patterns, coding_conventions, tech_stack
+- **assets**: {documentation[], source_code[], config[], tests[]} with relevance scores
+- **dependencies**: {internal[], external[]} with dependency graph
+- **brainstorm_artifacts**: {guidance_specification, role_analyses[], synthesis_output} with content
+- **conflict_detection**: {risk_level, risk_factors, affected_modules[], mitigation_strategy}
+
+## Quality Validation
+Before completion verify:
+- [ ] Valid JSON format with all required fields
+- [ ] File relevance accuracy >80%
+- [ ] Dependency graph complete (max 2 transitive levels)
+- [ ] Conflict risk level calculated correctly
+- [ ] No sensitive data exposed
+- [ ] Total files ≤50 (prioritize high-relevance)
+
+Execute autonomously following agent documentation.
+Report completion with statistics.
+`
+)
 ```
-**Generated framework focuses on**:
-- Service architecture and communication patterns
-- Data flow and storage strategies
-- Domain standards and best practices
 
-#### Example 2: User-Focused Topic
+**Graceful Degradation**:
-```bash
+- If agent fails: Log warning, continue to Phase 1 without project context
-/workflow:brainstorm:artifacts "Improve user onboarding experience" --roles "ui-designer,ux-expert,product-manager"
+- If package invalid: Re-run context-search-agent
+
+### Phase 1: Topic Analysis & Intent Classification
+
+**Goal**: Extract keywords/challenges to drive all subsequent question generation, **enriched by Phase 0 project context**
+
+**Steps**:
+1. **Load Phase 0 context** (if available):
+   - Read `.workflow/WFS-{session-id}/.process/context-package.json`
+   - Extract: tech_stack, existing modules, conflict_risk, relevant files
+
+2. **Deep topic analysis** (context-aware):
+   - Extract technical entities from topic + existing codebase
+   - Identify core challenges considering existing architecture
+   - Consider constraints (timeline/budget/compliance)
+   - Define success metrics based on current project state
+
+3. **Generate 2-4 context-aware probing questions**:
+   - Reference existing tech stack in questions
+   - Consider integration with existing modules
+   - Address identified conflict risks from Phase 0
+   - Target root challenges and trade-off priorities
+
+4. **User interaction**: Output questions using text format (see User Interaction Protocol), wait for user input
+
+5. **Parse user answers**: Use intelligent parsing to extract answers from user input (support multiple formats)
+
+6. **Storage**: Store answers to `session.intent_context` with `{extracted_keywords, identified_challenges, user_answers, project_context_used}`
+
+**Example Output**:
+```markdown
+===== Phase 1: 项目意图分析 =====
+
+【问题1 - 核心挑战】实时协作平台的主要技术挑战？
+a) 实时数据同步
+   说明：100+用户同时在线，状态同步复杂度高
+b) 可扩展性架构
+   说明：用户规模增长时的系统扩展能力
+c) 冲突解决机制
+   说明：多用户同时编辑的冲突处理策略
+
+【问题2 - 优先级】MVP阶段最关注的指标？
+a) 功能完整性
+   说明：实现所有核心功能
+b) 用户体验
+   说明：流畅的交互体验和响应速度
+c) 系统稳定性
+   说明：高可用性和数据一致性
+
+请回答 (格式: 1a 2b)：
 ```
-**Generated framework focuses on**:
-- Onboarding flow and UI components
-- User experience optimization and usability
-- Business value and success metrics
 
-#### Example 3: Agile Delivery Topic
+**User input examples**:
-```bash
+- `1a 2c` → Q1:a, Q2:c
-/workflow:brainstorm:artifacts "Optimize sprint delivery process" --roles "scrum-master,product-owner,test-strategist"
+- `1a,2c` → Q1:a, Q2:c
+
+**⚠️ CRITICAL**: Questions MUST reference topic keywords. Generic "Project type?" violates dynamic generation.
+
+### Phase 2: Role Selection
+
+**⚠️ CRITICAL**: User MUST interact to select roles. NEVER auto-select without user confirmation.
+
+**Available Roles**:
+- data-architect (数据架构师)
+- product-manager (产品经理)
+- product-owner (产品负责人)
+- scrum-master (敏捷教练)
+- subject-matter-expert (领域专家)
+- system-architect (系统架构师)
+- test-strategist (测试策略师)
+- ui-designer (UI 设计师)
+- ux-expert (UX 专家)
+
+**Steps**:
+1. **Intelligent role recommendation** (AI analysis):
+   - Analyze Phase 1 extracted keywords and challenges
+   - Use AI reasoning to determine most relevant roles for the specific topic
+   - Recommend count+2 roles (e.g., if user wants 3 roles, recommend 5 options)
+   - Provide clear rationale for each recommended role based on topic context
+
+2. **User selection** (text interaction):
+   - Output all recommended roles at once (no batching needed for count+2 roles)
+   - Display roles with labels and relevance rationale
+   - Wait for user input in multi-select format
+   - Parse user input (support multiple formats)
+   - **Storage**: Store selections to `session.selected_roles`
+
+**Example Output**:
+```markdown
+===== Phase 2: 角色选择 =====
+
+【角色选择】请选择 3 个角色参与头脑风暴分析
+
+a) system-architect (系统架构师)
+   推荐理由：实时同步架构设计和技术选型的核心角色
+b) ui-designer (UI设计师)
+   推荐理由：协作界面用户体验和实时状态展示
+c) product-manager (产品经理)
+   推荐理由：功能优先级和MVP范围决策
+d) data-architect (数据架构师)
+   推荐理由：数据同步模型和存储方案设计
+e) ux-expert (UX专家)
+   推荐理由：多用户协作交互流程优化
+
+支持格式：
+- 分别选择：2a 2c 2d (选择a、c、d)
+- 合并语法：2acd (选择a、c、d)
+- 逗号分隔：2a,c,d (选择a、c、d)
+
+请输入选择：
 ```
-**Generated framework focuses on**:
-- Sprint planning and team collaboration
-- Backlog management and prioritization
-- Quality assurance and testing strategies
 
-#### Example 4: Comprehensive Analysis
+**User input examples**:
-```bash
+- `2acd` → Roles: a, c, d (system-architect, product-manager, data-architect)
-/workflow:brainstorm:artifacts "Build real-time collaboration feature"
+- `2a 2c 2d` → Same result
+- `2a,c,d` → Same result
+
+**Role Recommendation Rules**:
+- NO hardcoded keyword-to-role mappings
+- Use intelligent analysis of topic, challenges, and requirements
+- Consider role synergies and coverage gaps
+- Explain WHY each role is relevant to THIS specific topic
+- Default recommendation: count+2 roles for user to choose from
+
+### Phase 3: Role-Specific Questions (Dynamic Generation)
+
+**Goal**: Generate deep questions mapping role expertise to Phase 1 challenges
+
+**Algorithm**:
 ```
-**Generated framework covers** all aspects (no roles specified)
+FOR each selected role:
+  1. Map Phase 1 challenges to role domain:
+     - "real-time sync" + system-architect → State management pattern
+     - "100 users" + system-architect → Communication protocol
+     - "low latency" + system-architect → Conflict resolution
 
-## Session Management ⚠️ CRITICAL
+  2. Generate 3-4 questions per role probing implementation depth, trade-offs, edge cases:
-- **⚡ FIRST ACTION**: Check for all `.workflow/.active-*` markers before processing
+     Q: "How handle real-time state sync for 100+ users?" (explores approach)
-- **Multiple sessions support**: Different Claude instances can have different active sessions
+     Q: "How resolve conflicts when 2 users edit simultaneously?" (explores edge case)
-- **User selection**: If multiple active sessions found, prompt user to select which one to work with
+     Options: [Event Sourcing/Centralized/CRDT] (concrete, explain trade-offs for THIS use case)
-- **Auto-session creation**: `WFS-[topic-slug]` only if no active session exists
-- **Session continuity**: MUST use selected active session for all processing
-- **Context preservation**: All discussion and analysis stored in session directory
-- **Session isolation**: Each session maintains independent state
 
-## Discussion Areas
+  3. Output questions in text format per role:
+     - Display all questions for current role (3-4 questions, no 10-question limit)
+     - Questions in Chinese (用中文提问)
+     - Wait for user input
+     - Parse answers using intelligent parsing
+     - Store answers to session.role_decisions[role]
+```
 
-### Core Investigation Topics
+**Batching Strategy**:
-- **Purpose & Goals**: What are we trying to achieve?
+- Each role outputs all its questions at once (typically 3-4 questions)
-- **Scope & Boundaries**: What's included and excluded?
+- No need to split per role (within 10-question batch limit)
-- **Success Criteria**: How do we measure success?
+- Multiple roles processed sequentially (one role at a time for clarity)
-- **Constraints**: What limitations exist?
-- **Stakeholders**: Who is affected or involved?
 
-### Technical Considerations
+**Output Format**: Follow standard format from "User Interaction Protocol" section (single-choice question format)
-- **Requirements**: What must the solution provide?
-- **Dependencies**: What does it rely on?
-- **Integration**: How does it connect to existing systems?
-- **Performance**: What are the speed/scale requirements?
-- **Security**: What protection is needed?
 
-### Implementation Factors
+**Example Topic-Specific Questions** (system-architect role for "real-time collaboration platform"):
-- **Timeline**: When is it needed?
+- "100+ 用户实时状态同步方案?" → Options: Event Sourcing / 集中式状态管理 / CRDT
-- **Resources**: What people/budget/tools are available?
+- "两个用户同时编辑冲突如何解决?" → Options: 自动合并 / 手动解决 / 版本控制
-- **Risks**: What could go wrong?
+- "低延迟通信协议选择?" → Options: WebSocket / SSE / 轮询
-- **Alternatives**: What other approaches exist?
+- "系统扩展性架构方案?" → Options: 微服务 / 单体+缓存 / Serverless
-- **Migration**: How do we transition from current state?
 
-## Update Mechanism ⚠️ SMART UPDATES
+**Quality Requirements**: See "Question Generation Guidelines" section for detailed rules
 
-### Framework Update Logic
+### Phase 4: Cross-Role Clarification (Conflict Detection)
-```bash
+
-# Check existing framework
+**Goal**: Resolve ACTUAL conflicts from Phase 3 answers, not pre-defined relationships
-IF topic-framework.md EXISTS:
+
-    SHOW current framework to user
+**Algorithm**:
-    ASK: "Framework exists. Do you want to:"
+```
-    OPTIONS:
+1. Analyze Phase 3 answers for conflicts:
-      1. "Replace completely" → Generate new framework
+   - Contradictory choices: product-manager "fast iteration" vs system-architect "complex Event Sourcing"
-      2. "Add discussion points" → Append to existing
+   - Missing integration: ui-designer "Optimistic updates" but system-architect didn't address conflict handling
-      3. "Refine existing points" → Interactive editing
+   - Implicit dependencies: ui-designer "Live cursors" but no auth approach defined
-      4. "Cancel" → Exit without changes
+
+2. FOR each detected conflict:
+   Generate clarification questions referencing SPECIFIC Phase 3 choices
+
+3. Output clarification questions in text format:
+   - Batch conflicts into rounds (max 10 questions per round)
+   - Display questions with context from Phase 3 answers
+   - Questions in Chinese (用中文提问)
+   - Wait for user input
+   - Parse answers using intelligent parsing
+   - Store answers to session.cross_role_decisions
+
+4. If NO conflicts: Skip Phase 4 (inform user: "未检测到跨角色冲突，跳过Phase 4")
+```
+
+**Batching Strategy**:
+- Maximum 10 clarification questions per round
+- If conflicts > 10, split into multiple rounds
+- Prioritize most critical conflicts first
+
+**Output Format**: Follow standard format from "User Interaction Protocol" section (single-choice question format with background context)
+
+**Example Conflict Detection** (from Phase 3 answers):
+- **Architecture Conflict**: "CRDT 与 UI 回滚期望冲突，如何解决?"
+  - Background: system-architect chose CRDT, ui-designer expects rollback UI
+  - Options: 采用 CRDT / 显示合并界面 / 切换到 OT
+- **Integration Gap**: "实时光标功能缺少身份认证方案"
+  - Background: ui-designer chose live cursors, no auth defined
+  - Options: OAuth 2.0 / JWT Token / Session-based
+
+**Quality Requirements**: See "Question Generation Guidelines" section for conflict-specific rules
+
+### Phase 5: Generate Guidance Specification
+
+**Steps**:
+1. Load all decisions: `intent_context` + `selected_roles` + `role_decisions` + `cross_role_decisions`
+2. Transform Q&A pairs to declarative: Questions → Headers, Answers → CONFIRMED/SELECTED statements
+3. Generate guidance-specification.md (template below) - **PRIMARY OUTPUT FILE**
+4. Update workflow-session.json with **METADATA ONLY**:
+   - session_id (e.g., "WFS-topic-slug")
+   - selected_roles[] (array of role names, e.g., ["system-architect", "ui-designer", "product-manager"])
+   - topic (original user input string)
+   - timestamp (ISO-8601 format)
+   - phase_completed: "artifacts"
+   - count_parameter (number from --count flag)
+5. Validate: No interrogative sentences in .md file, all decisions traceable, no content duplication in .json
+
+**⚠️ CRITICAL OUTPUT SEPARATION**:
+- **guidance-specification.md**: Full guidance content (decisions, rationale, integration points)
+- **workflow-session.json**: Session metadata ONLY (no guidance content, no decisions, no Q&A pairs)
+- **NO content duplication**: Guidance stays in .md, metadata stays in .json
+
+## Output Document Template
+
+**File**: `.workflow/WFS-{topic}/.brainstorming/guidance-specification.md`
+
+```markdown
+# [Project] - Confirmed Guidance Specification
+
+**Metadata**: [timestamp, type, focus, roles]
+
+## 1. Project Positioning & Goals
+**CONFIRMED Objectives**: [from topic + Phase 1]
+**CONFIRMED Success Criteria**: [from Phase 1 answers]
+
+## 2-N. [Role] Decisions
+### SELECTED Choices
+**[Question topic]**: [User's answer]
+- **Rationale**: [From option description]
+- **Impact**: [Implications]
+
+### Cross-Role Considerations
+**[Conflict resolved]**: [Resolution from Phase 4]
+- **Affected Roles**: [Roles involved]
+
+## Cross-Role Integration
+**CONFIRMED Integration Points**: [API/Data/Auth from multiple roles]
+
+## Risks & Constraints
+**Identified Risks**: [From answers] → Mitigation: [Approach]
+
+## Next Steps
+**⚠️ Automatic Continuation** (when called from auto-parallel):
+- auto-parallel will assign agents to generate role-specific analysis documents
+- Each selected role gets dedicated conceptual-planning-agent
+- Agents read this guidance-specification.md for framework context
+
+## Appendix: Decision Tracking
+| Decision ID | Category | Question | Selected | Phase | Rationale |
+|-------------|----------|----------|----------|-------|-----------|
+| D-001 | Intent | [Q] | [A] | 1 | [Why] |
+| D-002 | Roles | [Selected] | [Roles] | 2 | [Why] |
+| D-003+ | [Role] | [Q] | [A] | 3 | [Why] |
+```
+
+## Question Generation Guidelines
+
+### Core Principle: Developer-Facing Questions with User Context
+
+**Target Audience**: 开发者（理解技术但需要从用户需求出发）
+
+**Generation Philosophy**:
+1. **Phase 1**: 用户场景、业务约束、优先级（建立上下文）
+2. **Phase 2**: 基于话题分析的智能角色推荐（非关键词映射）
+3. **Phase 3**: 业务需求 + 技术选型（需求驱动的技术决策）
+4. **Phase 4**: 技术冲突的业务权衡（帮助开发者理解影响）
+
+### Universal Quality Rules
+
+**Question Structure** (all phases):
+```
+[业务场景/需求前提] + [技术关注点]
+```
+
+**Option Structure** (all phases):
+```
+标签：[技术方案简称] + (业务特征)
+说明：[业务影响] + [技术权衡]
+```
+
+**MUST Include** (all phases):
+- ✅ All questions in Chinese (用中文提问)
+- ✅ 业务场景作为问题前提
+- ✅ 技术选项的业务影响说明
+- ✅ 量化指标和约束条件
+
+**MUST Avoid** (all phases):
+- ❌ 纯技术选型无业务上下文
+- ❌ 过度抽象的用户体验问题
+- ❌ 脱离话题的通用架构问题
+
+### Phase-Specific Requirements
+
+**Phase 1 Requirements**:
+- Questions MUST reference topic keywords (NOT generic "Project type?")
+- Focus: 用户使用场景（谁用？怎么用？多频繁？）、业务约束（预算、时间、团队、合规）
+- Success metrics: 性能指标、用户体验目标
+- Priority ranking: MVP vs 长期规划
+
+**Phase 3 Requirements**:
+- Questions MUST reference Phase 1 keywords (e.g., "real-time", "100 users")
+- Options MUST be concrete approaches with relevance to topic
+- Each option includes trade-offs specific to this use case
+- Include 业务需求驱动的技术问题、量化指标（并发数、延迟、可用性）
+
+**Phase 4 Requirements**:
+- Questions MUST reference SPECIFIC Phase 3 choices in background context
+- Options address the detected conflict directly
+- Each option explains impact on both conflicting roles
+- NEVER use static "Cross-Role Matrix" - ALWAYS analyze actual Phase 3 answers
+- Focus: 技术冲突的业务权衡、帮助开发者理解不同选择的影响
+
+## Validation Checklist
+
+Generated guidance-specification.md MUST:
+- ✅ No interrogative sentences (use CONFIRMED/SELECTED)
+- ✅ Every decision traceable to user answer
+- ✅ Cross-role conflicts resolved or documented
+- ✅ Next steps concrete and specific
+- ✅ All Phase 1-4 decisions in session metadata
+
+## Update Mechanism
+
+```
+IF guidance-specification.md EXISTS:
+  Prompt: "Regenerate completely / Update sections / Cancel"
 ELSE:
-    CREATE new framework
+  Run full Phase 1-5 flow
 ```
 
-### Update Strategies
+## Governance Rules
 
-**1. Complete Replacement**
+**Output Requirements**:
-- Backup existing framework as `topic-framework-[timestamp].md.backup`
+- All decisions MUST use CONFIRMED/SELECTED (NO "?" in decision sections)
-- Generate completely new framework
+- Every decision MUST trace to user answer
-- Preserve role-specific analysis points from previous version
+- Conflicts MUST be resolved (not marked "TBD")
+- Next steps MUST be actionable
+- Topic preserved as authoritative reference in session
 
-**2. Incremental Addition**
+**CRITICAL**: Guidance is single source of truth for downstream phases. Ambiguity violates governance.
-- Load existing framework
-- Identify new discussion areas through user interaction
-- Add new sections while preserving existing structure
-- Update framework usage instructions
 
-**3. Refinement Mode**
+## Storage Validation
-- Interactive editing of existing discussion points
-- Allow modification of scope, objectives, and questions
-- Preserve framework structure and role assignments
-- Update timestamp and version info
 
-### Version Control
+**workflow-session.json** (metadata only):
-- **Backup Creation**: Always backup before major changes
+```json
-- **Change Tracking**: Include change summary in framework footer
+{
-- **Rollback Support**: Keep previous version accessible
+  "session_id": "WFS-{topic-slug}",
+  "type": "brainstorming",
+  "topic": "{original user input}",
+  "selected_roles": ["system-architect", "ui-designer", "product-manager"],
+  "phase_completed": "artifacts",
+  "timestamp": "2025-10-24T10:30:00Z",
+  "count_parameter": 3
+}
+```
 
-## Error Handling
+**⚠️ Rule**: Session JSON stores ONLY metadata (session_id, selected_roles[], topic, timestamps). All guidance content goes to guidance-specification.md.
-- **Session creation failure**: Provide clear error message and retry option
-- **Discussion stalling**: Offer structured prompts to continue exploration
-- **Documentation issues**: Graceful handling of file creation problems
-- **Missing context**: Prompt for additional information when needed
 
-## Reference Information
+## File Structure
 
-### File Structure Reference
+```
-**Architecture**: @~/.claude/workflows/workflow-architecture.md
+.workflow/WFS-[topic]/
-**Session Management**: Standard workflow session protocols
+├── .active-brainstorming
+├── workflow-session.json              # Session metadata ONLY
+└── .brainstorming/
+    └── guidance-specification.md      # Full guidance content
+```
 
-### Integration Points
-- **Compatible with**: Other brainstorming commands in the same session
-- **Builds foundation for**: More detailed planning and implementation phases
-- **Outputs used by**: `/workflow:brainstorm:synthesis` command for cross-analysis integration

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

@@ -7,359 +7,334 @@ allowed-tools: SlashCommand(*), Task(*), TodoWrite(*), Read(*), Write(*), Bash(*
 
 # Workflow Brainstorm Parallel Auto Command
 
+## Coordinator Role
+
+**This command is a pure orchestrator**: Execute 3 phases in sequence (interactive framework → parallel role analysis → synthesis), delegate to specialized commands/agents, and ensure complete execution through **automatic continuation**.
+
+**Execution Model - Auto-Continue Workflow**:
+
+This workflow runs **fully autonomously** once triggered. Phase 1 (artifacts) handles user interaction, Phase 2 (role agents) runs in parallel.
+
+1. **User triggers**: `/workflow:brainstorm:auto-parallel "topic" [--count N]`
+2. **Phase 1 executes** → artifacts command (interactive framework) → Auto-continues
+3. **Phase 2 executes** → Parallel role agents (N agents run concurrently) → Auto-continues
+4. **Phase 3 executes** → Synthesis command → Reports final summary
+
+**Auto-Continue Mechanism**:
+- TodoList tracks current phase status
+- After Phase 1 (artifacts) completion, automatically load roles and launch Phase 2 agents
+- After Phase 2 (all agents) completion, automatically execute Phase 3 synthesis
+- Progress updates shown at each phase for visibility
+
+## Core Rules
+
+1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 command execution
+2. **No Preliminary Analysis**: Do not analyze topic before Phase 1 - artifacts handles all analysis
+3. **Parse Every Output**: Extract selected_roles from workflow-session.json after Phase 1
+4. **Auto-Continue via TodoList**: Check TodoList status to execute next pending phase automatically
+5. **Track Progress**: Update TodoWrite after every phase completion
+6. **TodoWrite Extension**: artifacts command EXTENDS parent TodoList (NOT replaces)
+
 ## Usage
+
 ```bash
 /workflow:brainstorm:auto-parallel "<topic>" [--count N]
 ```
 
-**Parameters**:
+**Recommended Structured Format**:
-- `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
-- **Product & UX**: `user|ui|ux|interface|design|product|feature|experience` → ui-designer, user-researcher, product-manager, ux-expert, product-owner
-- **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 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/`
-**Available Roles**: api-designer, data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
-
-**Example**:
 ```bash
-bash($(cat "~/.claude/workflows/cli-templates/planning-roles/system-architect.md"))
+/workflow:brainstorm:auto-parallel "GOAL: [objective] SCOPE: [boundaries] CONTEXT: [background]" [--count N]
-bash($(cat "~/.claude/workflows/cli-templates/planning-roles/ui-designer.md"))
 ```
 
-## Core Workflow
+**Parameters**:
+- `topic` (required): Topic or challenge description (structured format recommended)
+- `--count N` (optional): Number of roles to select (default: 3, max: 9)
 
-### Structured Topic Processing → Role Analysis → Synthesis
+## 3-Phase Execution
-The command follows a structured three-phase approach with dedicated document types:
 
-**Phase 1: Framework Generation** ⚠️ COMMAND EXECUTION
+### Phase 1: Interactive Framework Generation
-- **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
+**Command**: `SlashCommand(command="/workflow:brainstorm:artifacts \"{topic}\" --count {N}")`
-- **Parallel execution**: Multiple roles execute simultaneously for faster completion
-- **Independent agents**: Each role gets dedicated conceptual-planning-agent running in parallel
-- **Shared framework**: All roles reference the same topic framework for consistency
-- **Concurrent generation**: Role-specific analysis documents generated simultaneously
-- **Progress tracking**: Parallel agents update progress independently
 
-**Phase 3: Synthesis Generation** ⚠️ COMMAND EXECUTION
+**What It Does**:
-- **Call synthesis command**: Execute `/workflow:brainstorm:synthesis` using SlashCommand tool
+- Topic analysis: Extract challenges, generate task-specific questions
+- Role selection: Recommend count+2 roles, user selects via AskUserQuestion
+- Role questions: Generate 3-4 questions per role, collect user decisions
+- Conflict resolution: Detect and resolve cross-role conflicts
+- Guidance generation: Transform Q&A to declarative guidance-specification.md
 
-## Implementation Standards
+**Parse Output**:
+- **⚠️ Memory Check**: If `selected_roles[]` already in conversation memory from previous load, skip file read
+- Extract: `selected_roles[]` from workflow-session.json (if not in memory)
+- Extract: `session_id` from workflow-session.json (if not in memory)
+- Verify: guidance-specification.md exists
 
-### Simplified Command Orchestration ⚠️ STREAMLINED
+**Validation**:
-Auto command coordinates independent specialized commands:
+- guidance-specification.md created with confirmed decisions
+- workflow-session.json contains selected_roles[] (metadata only, no content duplication)
+- Session directory `.workflow/WFS-{topic}/.brainstorming/` exists
 
-**Command Sequence**:
+**TodoWrite**: Mark phase 1 completed, phase 2 in_progress
-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`
 
-**SlashCommand Integration**:
+**After Phase 1**: Auto-continue to Phase 2 (role agent assignment)
-1. **artifacts command**: Called via SlashCommand tool with `--roles` parameter for role-specific framework generation
-2. **role agents**: Each agent reads its dedicated section in the role-specific framework
-3. **synthesis command**: Called via SlashCommand tool for final integration with role-targeted insights
-4. **Command coordination**: SlashCommand handles execution and validation
 
-**Role Selection Logic**:
+**⚠️ TodoWrite Coordination**: artifacts EXTENDS parent TodoList by:
-- **Technical**: `architecture|system|performance|database` → system-architect, data-architect, subject-matter-expert
+- Marking parent task "Execute artifacts..." as in_progress
-- **API & Backend**: `api|endpoint|rest|graphql|backend|interface|contract|service` → api-designer, system-architect, data-architect
+- APPENDING artifacts sub-tasks (Phase 1-5) after parent task
-- **Product & UX**: `user|ui|ux|interface|design|product|feature|experience` → ui-designer, ux-expert, product-manager, product-owner
+- PRESERVING all other auto-parallel tasks (role agents, synthesis)
-- **Agile & Delivery**: `agile|sprint|scrum|team|collaboration|delivery` → scrum-master, product-owner
+- When artifacts Phase 5 completes, marking parent task as completed
-- **Domain Expertise**: `domain|standard|compliance|expertise|regulation` → subject-matter-expert
-- **Auto-select**: N most relevant roles based on topic analysis (N from --count parameter, default: 3)
 
-### Parameter Parsing
+---
 
-**Count Parameter Handling**:
+### Phase 2: Parallel Role Analysis Execution
+
+**For Each Selected Role**:
 ```bash
-# Parse --count parameter from user input
+Task(conceptual-planning-agent): "
+[FLOW_CONTROL]
+
+Execute {role-name} analysis for existing topic framework
+
+## Context Loading
+ASSIGNED_ROLE: {role-name}
+OUTPUT_LOCATION: .workflow/WFS-{session}/.brainstorming/{role}/
+TOPIC: {user-provided-topic}
+
+## Flow Control Steps
+1. **load_topic_framework**
+   - Action: Load structured topic discussion framework
+   - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
+   - Output: topic_framework_content
+
+2. **load_role_template**
+   - Action: Load {role-name} planning template
+   - Command: Read(~/.claude/workflows/cli-templates/planning-roles/{role}.md)
+   - Output: role_template_guidelines
+
+3. **load_session_metadata**
+   - Action: Load session metadata and original user intent
+   - Command: Read(.workflow/WFS-{session}/workflow-session.json)
+   - Output: session_context (contains original user prompt as PRIMARY reference)
+
+## Analysis Requirements
+**Primary Reference**: Original user prompt from workflow-session.json is authoritative
+**Framework Source**: Address all discussion points in guidance-specification.md from {role-name} perspective
+**Role Focus**: {role-name} domain expertise aligned with user intent
+**Structured Approach**: Create analysis.md addressing framework discussion points
+**Template Integration**: Apply role template guidelines within framework structure
+
+## Expected Deliverables
+1. **analysis.md**: Comprehensive {role-name} analysis addressing all framework discussion points
+   - **File Naming**: MUST start with `analysis` prefix (e.g., `analysis.md`, `analysis-1.md`, `analysis-2.md`)
+   - **FORBIDDEN**: Never use `recommendations.md` or any filename not starting with `analysis`
+   - **Auto-split if large**: If content >800 lines, split to `analysis-1.md`, `analysis-2.md` (max 3 files: analysis.md, analysis-1.md, analysis-2.md)
+   - **Content**: Includes both analysis AND recommendations sections within analysis files
+2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
+3. **User Intent Alignment**: Validate analysis aligns with original user objectives from session_context
+
+## Completion Criteria
+- Address each discussion point from guidance-specification.md with {role-name} expertise
+- Provide actionable recommendations from {role-name} perspective within analysis files
+- All output files MUST start with `analysis` prefix (no recommendations.md or other naming)
+- Reference framework document using @ notation for integration
+- Update workflow-session.json with completion status
+"
+```
+
+**Parallel Execution**:
+- Launch N agents simultaneously (one message with multiple Task calls)
+- Each agent operates independently reading same guidance-specification.md
+- All agents update progress concurrently
+
+**Input**:
+- `selected_roles[]` from Phase 1
+- `session_id` from Phase 1
+- guidance-specification.md path
+
+**Validation**:
+- Each role creates `.workflow/WFS-{topic}/.brainstorming/{role}/analysis.md` (primary file)
+- If content is large (>800 lines), may split to `analysis-1.md`, `analysis-2.md` (max 3 files total)
+- **File naming pattern**: ALL files MUST start with `analysis` prefix (use `analysis*.md` for globbing)
+- **FORBIDDEN naming**: No `recommendations.md`, `recommendations-*.md`, or any non-`analysis` prefixed files
+- All N role analyses completed
+
+**TodoWrite**: Mark all N role agent tasks completed, phase 3 in_progress
+
+**After Phase 2**: Auto-continue to Phase 3 (synthesis)
+
+---
+
+### Phase 3: Synthesis Generation
+
+**Command**: `SlashCommand(command="/workflow:brainstorm:synthesis --session {sessionId}")`
+
+**What It Does**:
+- Load original user intent from workflow-session.json
+- Read all role analysis.md files
+- Integrate role insights into synthesis-specification.md
+- Validate alignment with user's original objectives
+
+**Input**: `sessionId` from Phase 1
+
+**Validation**:
+- `.workflow/WFS-{topic}/.brainstorming/synthesis-specification.md` exists
+- Synthesis references all role analyses
+
+**TodoWrite**: Mark phase 3 completed
+
+**Return to User**:
+```
+Brainstorming complete for session: {sessionId}
+Roles analyzed: {count}
+Synthesis: .workflow/WFS-{topic}/.brainstorming/synthesis-specification.md
+
+✅ Next Steps:
+1. /workflow:concept-clarify --session {sessionId}  # Optional refinement
+2. /workflow:plan --session {sessionId}  # Generate implementation plan
+```
+
+## TodoWrite Pattern
+
+```javascript
+// Initialize (before Phase 1)
+TodoWrite({todos: [
+  {"content": "Parse --count parameter from user input", "status": "in_progress", "activeForm": "Parsing count parameter"},
+  {"content": "Execute artifacts command for interactive framework generation", "status": "pending", "activeForm": "Executing artifacts interactive framework"},
+  {"content": "Load selected_roles from workflow-session.json", "status": "pending", "activeForm": "Loading selected roles"},
+  // Role agent tasks added dynamically after Phase 1 based on selected_roles count
+  {"content": "Execute synthesis command for final integration", "status": "pending", "activeForm": "Executing synthesis integration"}
+]})
+
+// After Phase 1 (artifacts completes, roles loaded)
+// Note: artifacts EXTENDS this list by appending its Phase 1-5 sub-tasks
+TodoWrite({todos: [
+  {"content": "Parse --count parameter from user input", "status": "completed", "activeForm": "Parsing count parameter"},
+  {"content": "Execute artifacts command for interactive framework generation", "status": "completed", "activeForm": "Executing artifacts interactive framework"},
+  {"content": "Load selected_roles from workflow-session.json", "status": "in_progress", "activeForm": "Loading selected roles"},
+  {"content": "Execute system-architect analysis [conceptual-planning-agent]", "status": "pending", "activeForm": "Executing system-architect analysis"},
+  {"content": "Execute ui-designer analysis [conceptual-planning-agent]", "status": "pending", "activeForm": "Executing ui-designer analysis"},
+  {"content": "Execute product-manager analysis [conceptual-planning-agent]", "status": "pending", "activeForm": "Executing product-manager analysis"},
+  // ... (N role tasks based on --count parameter)
+  {"content": "Execute synthesis command for final integration", "status": "pending", "activeForm": "Executing synthesis integration"}
+]})
+
+// After Phase 2 (all agents launched in parallel)
+TodoWrite({todos: [
+  // ... previous completed tasks
+  {"content": "Load selected_roles from workflow-session.json", "status": "completed", "activeForm": "Loading selected roles"},
+  {"content": "Execute system-architect analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing system-architect analysis"},
+  {"content": "Execute ui-designer analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing ui-designer analysis"},
+  {"content": "Execute product-manager analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing product-manager analysis"},
+  // ... (all N agents in_progress simultaneously)
+  {"content": "Execute synthesis command for final integration", "status": "pending", "activeForm": "Executing synthesis integration"}
+]})
+
+// After Phase 2 (all agents complete)
+TodoWrite({todos: [
+  // ... previous completed tasks
+  {"content": "Execute system-architect analysis [conceptual-planning-agent]", "status": "completed", "activeForm": "Executing system-architect analysis"},
+  {"content": "Execute ui-designer analysis [conceptual-planning-agent]", "status": "completed", "activeForm": "Executing ui-designer analysis"},
+  {"content": "Execute product-manager analysis [conceptual-planning-agent]", "status": "completed", "activeForm": "Executing product-manager analysis"},
+  {"content": "Execute synthesis command for final integration", "status": "in_progress", "activeForm": "Executing synthesis integration"}
+]})
+```
+
+## Input Processing
+
+**Count Parameter Parsing**:
+```javascript
+// Extract --count 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
+        count_value = 9  // Cap at maximum 9 roles
-    END IF
 ELSE:
-    count_value = 3  # Default to 3 roles
+    count_value = 3  // Default to 3 roles
-END IF
+
+// Pass to artifacts command
+EXECUTE: /workflow:brainstorm:artifacts "{topic}" --count {count_value}
 ```
 
-**Role Selection with Count**:
+**Topic Structuring**:
-1. **Analyze topic keywords**: Identify relevant role categories
+1. **Already Structured** → Pass directly to artifacts
-2. **Rank roles by relevance**: Score based on keyword matches
+   ```
-3. **Select top N roles**: Pick N most relevant roles (N = count_value)
+   User: "GOAL: Build platform SCOPE: 100 users CONTEXT: Real-time"
-4. **Ensure diversity**: Balance across different expertise areas
+   → Pass as-is to artifacts
-5. **Minimum guarantee**: Always include at least one role (default to product-manager if no matches)
+   ```
 
-### Simplified Processing Standards
+2. **Simple Text** → Pass directly (artifacts handles structuring)
+   ```
+   User: "Build collaboration platform"
+   → artifacts will analyze and structure
+   ```
 
-**Core Principles**:
+## Session Management
-1. **Minimal preprocessing** - Only workflow-session.json and basic role selection
-2. **Agent autonomy** - Agents handle their own context and validation
-3. **Parallel execution** - Multiple agents can work simultaneously
-4. **Post-processing synthesis** - Integration happens after agent completion
-5. **TodoWrite control** - Progress tracking throughout all phases
 
-**Implementation Rules**:
+**⚡ FIRST ACTION**: Check for `.workflow/.active-*` markers before Phase 1
-- **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
 
-**Agent Self-Management** (Agents decide their own approach):
+**Multiple Sessions Support**:
-- **Context gathering**: Agents determine what questions to ask
+- Different Claude instances can have different active brainstorming sessions
-- **Template usage**: Agents load and apply their own role templates
+- If multiple active sessions found, prompt user to select
-- **Analysis depth**: Agents determine appropriate level of detail
+- If single active session found, use it
-- **Documentation**: Agents create their own file structure and content
+- If no active session exists, create `WFS-[topic-slug]`
 
-### Session Management ⚠️ CRITICAL
+**Session Continuity**:
-- **⚡ FIRST ACTION**: Check for all `.workflow/.active-*` markers before role processing
+- MUST use selected active session for all phases
-- **Multiple sessions support**: Different Claude instances can have different active brainstorming sessions
+- Each role's context stored in session directory
-- **User selection**: If multiple active sessions found, prompt user to select which one to work with
+- Session isolation: Each session maintains independent state
-- **Auto-session creation**: `WFS-[topic-slug]` only if no active session exists
-- **Session continuity**: MUST use selected active session for all role processing
-- **Context preservation**: Each role's context and agent output stored in session directory
-- **Session isolation**: Each session maintains independent brainstorming state and role assignments
 
-## Document Generation
+## Output Structure
 
-**Command Coordination Workflow**: artifacts → parallel role analysis → synthesis
+**Phase 1 Output**:
+- `.workflow/WFS-{topic}/.brainstorming/guidance-specification.md` (framework content)
+- `.workflow/WFS-{topic}/workflow-session.json` (metadata: selected_roles[], topic, timestamps)
 
-**Output Structure**: Coordinated commands generate framework, role analyses, and synthesis documents as defined in their respective command specifications.
+**Phase 2 Output**:
+- `.workflow/WFS-{topic}/.brainstorming/{role}/analysis.md` (one per role)
 
+**Phase 3 Output**:
+- `.workflow/WFS-{topic}/.brainstorming/synthesis-specification.md` (integrated analysis)
 
-## Agent Prompt Templates
+**⚠️ Storage Separation**: Guidance content in .md files, metadata in .json (no duplication)
 
-### Task Agent Invocation Template
+## Available Roles
 
+- data-architect (数据架构师)
+- product-manager (产品经理)
+- product-owner (产品负责人)
+- scrum-master (敏捷教练)
+- subject-matter-expert (领域专家)
+- system-architect (系统架构师)
+- test-strategist (测试策略师)
+- ui-designer (UI 设计师)
+- ux-expert (UX 专家)
 
-```bash
+**Role Selection**: Handled by artifacts command (intelligent recommendation + user selection)
-Task(subagent_type="conceptual-planning-agent",
-     prompt="Execute brainstorming analysis: {role-name} perspective for {topic}
 
-     ## Role Assignment
+## Error Handling
-     **ASSIGNED_ROLE**: {role-name}
-     **TOPIC**: {user-provided-topic}
-     **OUTPUT_LOCATION**: .workflow/WFS-{topic}/.brainstorming/{role}/
 
-     ## Execution Instructions
+- **Role selection failure**: artifacts defaults to product-manager with explanation
-     [FLOW_CONTROL]
+- **Agent execution failure**: Agent-specific retry with minimal dependencies
-
+- **Template loading issues**: Agent handles graceful degradation
-     ### Flow Control Steps
+- **Synthesis conflicts**: Synthesis highlights disagreements without resolution
-     **AGENT RESPONSIBILITY**: Execute these pre_analysis steps sequentially with context accumulation:
-
-     1. **load_topic_framework**
-        - Action: Load structured topic discussion framework
-        - Command: bash(cat .workflow/WFS-{topic}/.brainstorming/topic-framework.md 2>/dev/null || echo 'Topic framework not found')
-        - Output: topic_framework
-
-     2. **load_role_template**
-        - Action: Load {role-name} planning template
-        - Command: bash($(cat "~/.claude/workflows/cli-templates/planning-roles/{role}.md"))
-        - Output: role_template
-
-     3. **load_session_metadata**
-        - Action: Load session metadata and topic description
-        - Command: bash(cat .workflow/WFS-{topic}/workflow-session.json 2>/dev/null || echo '{}')
-        - Output: session_metadata
-
-     ### Implementation Context
-     **Topic Framework**: Use loaded topic-framework.md for structured analysis
-     **Role Focus**: {role-name} domain expertise and perspective
-     **Analysis Type**: Address framework discussion points from role perspective
-     **Template Framework**: Combine role template with topic framework structure
-     **Structured Approach**: Create analysis.md addressing all topic framework points
-
-     ### Session Context
-     **Workflow Directory**: .workflow/WFS-{topic}/.brainstorming/
-     **Output Directory**: .workflow/WFS-{topic}/.brainstorming/{role}/
-     **Session JSON**: .workflow/WFS-{topic}/workflow-session.json
-
-     ### Dependencies & Context
-     **Topic**: {user-provided-topic}
-     **Role Template**: "~/.claude/workflows/cli-templates/planning-roles/{role}.md"
-     **User Requirements**: To be gathered through interactive questioning
-
-     ## Completion Requirements
-     1. Execute all flow control steps in sequence (load topic framework, role template, session metadata)
-     2. **Address Topic Framework**: Respond to all discussion points in topic-framework.md from role perspective
-     3. Apply role template guidelines within topic framework structure
-     4. Generate structured role analysis addressing framework points
-     5. Create single comprehensive deliverable in OUTPUT_LOCATION:
-        - analysis.md (structured analysis addressing all topic framework points with role-specific insights)
-     6. Include framework reference: @../topic-framework.md in analysis.md
-     7. Update workflow-session.json with completion status",
-     description="Execute {role-name} brainstorming analysis")
-```
-
-### Parallel Role Agent调用示例
-```bash
-# 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: {role-1} perspective for {topic}...",
-     description="Execute {role-1} brainstorming analysis")
-
-Task(subagent_type="conceptual-planning-agent",
-     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)
-**Synthesis execution**: Use SlashCommand to execute `/workflow:brainstorm:synthesis` after role completion
-
-
-## TodoWrite Control Flow ⚠️ CRITICAL
-
-### Workflow Progress Tracking
-**MANDATORY**: Use Claude Code's built-in TodoWrite tool throughout entire brainstorming workflow:
-
-```javascript
-// Phase 1: Create initial todo list for command-coordinated brainstorming workflow
-TodoWrite({
-  todos: [
-    {
-      content: "Initialize brainstorming session and detect active sessions",
-      status: "pending",
-      activeForm: "Initializing brainstorming session"
-    },
-    {
-      content: "Parse --count parameter and select N roles based on topic keyword analysis",
-      status: "pending",
-      activeForm: "Parsing parameters and selecting roles for brainstorming"
-    },
-    {
-      content: "Execute artifacts command with selected roles for role-specific framework",
-      status: "pending",
-      activeForm: "Generating role-specific topic framework"
-    },
-    {
-      content: "Execute [role-1] analysis [conceptual-planning-agent] [FLOW_CONTROL] addressing framework",
-      status: "pending",
-      activeForm: "Executing [role-1] structured framework analysis"
-    },
-    {
-      content: "Execute [role-2] analysis [conceptual-planning-agent] [FLOW_CONTROL] addressing framework",
-      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",
-      activeForm: "Executing synthesis command for integrated analysis"
-    }
-  ]
-});
-
-// Phase 2: Update status as workflow progresses - ONLY ONE task should be in_progress at a time
-TodoWrite({
-  todos: [
-    {
-      content: "Initialize brainstorming session and detect active sessions",
-      status: "completed",  // Mark completed preprocessing
-      activeForm: "Initializing brainstorming session"
-    },
-    {
-      content: "Select roles for topic analysis and create workflow-session.json",
-      status: "in_progress",  // Mark current task as in_progress
-      activeForm: "Selecting roles and creating session metadata"
-    },
-    // ... other tasks remain pending
-  ]
-});
-
-// Phase 3: Parallel agent execution tracking (N roles, N from --count parameter)
-TodoWrite({
-  todos: [
-    // ... previous completed tasks
-    {
-      content: "Execute [role-1] analysis [conceptual-planning-agent] [FLOW_CONTROL]",
-      status: "in_progress",  // Executing in parallel
-      activeForm: "Executing [role-1] brainstorming analysis"
-    },
-    {
-      content: "Execute [role-2] analysis [conceptual-planning-agent] [FLOW_CONTROL]",
-      status: "in_progress",  // Executing in parallel
-      activeForm: "Executing [role-2] brainstorming analysis"
-    },
-    // ... repeat for remaining N-2 roles
-    {
-      content: "Execute [role-N] analysis [conceptual-planning-agent] [FLOW_CONTROL]",
-      status: "in_progress",  // Executing in parallel
-      activeForm: "Executing [role-N] brainstorming analysis"
-    }
-  ]
-});
-```
-
-**TodoWrite Integration Rules**:
-1. **Create initial todos**: All workflow phases at start
-2. **Mark in_progress**: Multiple parallel tasks can be in_progress simultaneously
-3. **Update immediately**: After each task completion
-4. **Track agent execution**: Include [agent-type] and [FLOW_CONTROL] markers for parallel agents
-5. **Final synthesis**: Mark synthesis as in_progress only after all parallel agents complete
 
 ## Reference Information
 
-### Structured Processing Schema
+**File Structure**:
-Each role processing follows structured framework pattern:
+```
-- **topic_framework**: Structured discussion framework document
+.workflow/WFS-[topic]/
-- **role**: Selected planning role name with framework reference
+├── .active-brainstorming
-- **agent**: Dedicated conceptual-planning-agent instance
+├── workflow-session.json              # Session metadata ONLY
-- **structured_analysis**: Agent addresses all framework discussion points
+└── .brainstorming/
-- **output**: Role-specific analysis.md addressing topic framework structure
+    ├── guidance-specification.md      # Framework (Phase 1)
+    ├── {role-1}/
+    │   └── analysis.md                # Role analysis (Phase 2)
+    ├── {role-2}/
+    │   └── analysis.md
+    ├── {role-N}/
+    │   └── analysis.md
+    └── synthesis-specification.md     # Integration (Phase 3)
+```
 
-### File Structure Reference
+**Template Source**: `~/.claude/workflows/cli-templates/planning-roles/`
-**Architecture**: @~/.claude/workflows/workflow-architecture.md
-**Role Templates**: @~/.claude/workflows/cli-templates/planning-roles/
 
-### Execution Integration
-Command coordination model: artifacts command → parallel role analysis → synthesis command
-
-
-## Error Handling
-- **Role selection failure**: Default to `product-manager` with explanation
-- **Agent execution failure**: Agent-specific retry with minimal dependencies
-- **Template loading issues**: Agent handles graceful degradation
-- **Synthesis conflicts**: Synthesis agent highlights disagreements without resolution
-
-## Quality Standards
-
-### Agent Autonomy Excellence
-- **Single role focus**: Each agent handles exactly one role independently
-- **Self-contained execution**: Agent manages own context, validation, and output
-- **Parallel processing**: Multiple agents can execute simultaneously
-- **Complete ownership**: Agent produces entire role-specific analysis package
-
-### Minimal Coordination Excellence
-- **Lightweight handoff**: Only topic and role assignment provided
-- **Agent self-management**: Agents handle their own workflow and validation
-- **Concurrent operation**: No inter-agent dependencies enabling parallel execution
-- **Reference-based synthesis**: Post-processing integration without content duplication
-- **TodoWrite orchestration**: Progress tracking and workflow control throughout entire process

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

@@ -1,6 +1,6 @@
 ---
 name: data-architect
-description: Generate or update data-architect/analysis.md addressing topic-framework discussion points
+description: Generate or update data-architect/analysis.md addressing guidance-specification discussion points
 argument-hint: "optional topic - uses existing framework if available"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
@@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ## 📊 **Data Architect Analysis Generator**
 
 ### Purpose
-**Specialized command for generating data-architect/analysis.md** that addresses topic-framework.md discussion points from data architecture perspective. Creates or updates role-specific analysis with framework references.
+**Specialized command for generating data-architect/analysis.md** that addresses guidance-specification.md discussion points from data architecture perspective. Creates or updates role-specific analysis with framework references.
 
 ### Core Function
-- **Framework-based Analysis**: Address each discussion point in topic-framework.md
+- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
 - **Data Architecture Focus**: Data models, pipelines, governance, and analytics perspective
 - **Update Mechanism**: Create new or update existing analysis.md
 - **Agent Delegation**: Use conceptual-planning-agent for analysis generation
@@ -52,7 +52,7 @@ IF active_session EXISTS:
     session_id = get_active_session()
     brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
 
-    CHECK: brainstorm_dir/topic-framework.md
+    CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
         framework_mode = true
         load_framework = true
@@ -93,7 +93,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
 ## Flow Control Steps
 1. **load_topic_framework**
    - Action: Load structured topic discussion framework
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
+   - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
    - Output: topic_framework_content
 
 2. **load_role_template**
@@ -107,17 +107,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
    - Output: session_context
 
 ## Analysis Requirements
-**Framework Reference**: Address all discussion points in topic-framework.md from data architecture perspective
+**Framework Reference**: Address all discussion points in guidance-specification.md from data architecture perspective
 **Role Focus**: Data models, pipelines, governance, analytics platforms
 **Structured Approach**: Create analysis.md addressing framework discussion points
 **Template Integration**: Apply role template guidelines within framework structure
 
 ## Expected Deliverables
 1. **analysis.md**: Comprehensive data architecture analysis addressing all framework discussion points
-2. **Framework Reference**: Include @../topic-framework.md reference in analysis
+2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
 
 ## Completion Criteria
-- Address each discussion point from topic-framework.md with data architecture expertise
+- Address each discussion point from guidance-specification.md with data architecture expertise
 - Provide data model designs, pipeline architectures, and governance strategies
 - Include scalability, performance, and quality considerations
 - Reference framework document using @ notation for integration
@@ -136,7 +136,7 @@ TodoWrite({
       activeForm: "Detecting session and framework"
     },
     {
-      content: "Load topic-framework.md and session metadata for context",
+      content: "Load guidance-specification.md and session metadata for context",
       status: "pending",
       activeForm: "Loading framework and session context"
     },
@@ -164,7 +164,7 @@ TodoWrite({
 ### Framework-Based Analysis
 ```
 .workflow/WFS-{session}/.brainstorming/data-architect/
-└── analysis.md    # Structured analysis addressing topic-framework.md discussion points
+└── analysis.md    # Structured analysis addressing guidance-specification.md discussion points
 ```
 
 ### Analysis Document Structure
@@ -172,11 +172,11 @@ TodoWrite({
 # Data Architect Analysis: [Topic from Framework]
 
 ## Framework Reference
-**Topic Framework**: @../topic-framework.md
+**Topic Framework**: @../guidance-specification.md
 **Role Focus**: Data Architecture perspective
 
 ## Discussion Points Analysis
-[Address each point from topic-framework.md with data architecture expertise]
+[Address each point from guidance-specification.md with data architecture expertise]
 
 ### Core Requirements (from framework)
 [Data architecture perspective on requirements]
@@ -209,12 +209,12 @@ TodoWrite({
     "status": "completed",
     "framework_addressed": true,
     "output_location": ".workflow/WFS-{session}/.brainstorming/data-architect/analysis.md",
-    "framework_reference": "@../topic-framework.md"
+    "framework_reference": "@../guidance-specification.md"
   }
 }
 ```
 
 ### Integration Points
-- **Framework Reference**: @../topic-framework.md for structured discussion points
+- **Framework Reference**: @../guidance-specification.md for structured discussion points
 - **Cross-Role Synthesis**: Data architecture insights available for synthesis-report.md integration
 - **Agent Autonomy**: Independent execution with framework guidance

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

@@ -1,6 +1,6 @@
 ---
 name: product-manager
-description: Generate or update product-manager/analysis.md addressing topic-framework discussion points
+description: Generate or update product-manager/analysis.md addressing guidance-specification discussion points
 argument-hint: "optional topic - uses existing framework if available"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
@@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ## 🎯 **Product Manager Analysis Generator**
 
 ### Purpose
-**Specialized command for generating product-manager/analysis.md** that addresses topic-framework.md discussion points from product strategy perspective. Creates or updates role-specific analysis with framework references.
+**Specialized command for generating product-manager/analysis.md** that addresses guidance-specification.md discussion points from product strategy perspective. Creates or updates role-specific analysis with framework references.
 
 ### Core Function
-- **Framework-based Analysis**: Address each discussion point in topic-framework.md
+- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
 - **Product Strategy Focus**: User needs, business value, and market positioning
 - **Update Mechanism**: Create new or update existing analysis.md
 - **Agent Delegation**: Use conceptual-planning-agent for analysis generation
@@ -32,7 +32,7 @@ IF active_session EXISTS:
     session_id = get_active_session()
     brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
 
-    CHECK: brainstorm_dir/topic-framework.md
+    CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
         framework_mode = true
         load_framework = true
@@ -73,7 +73,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
 ## Flow Control Steps
 1. **load_topic_framework**
    - Action: Load structured topic discussion framework
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
+   - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
    - Output: topic_framework_content
 
 2. **load_role_template**
@@ -87,17 +87,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
    - Output: session_context
 
 ## Analysis Requirements
-**Framework Reference**: Address all discussion points in topic-framework.md from product strategy perspective
+**Framework Reference**: Address all discussion points in guidance-specification.md from product strategy perspective
 **Role Focus**: User value, business impact, market positioning, product strategy
 **Structured Approach**: Create analysis.md addressing framework discussion points
 **Template Integration**: Apply role template guidelines within framework structure
 
 ## Expected Deliverables
 1. **analysis.md**: Comprehensive product strategy analysis addressing all framework discussion points
-2. **Framework Reference**: Include @../topic-framework.md reference in analysis
+2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
 
 ## Completion Criteria
-- Address each discussion point from topic-framework.md with product management expertise
+- Address each discussion point from guidance-specification.md with product management expertise
 - Provide actionable business strategies and user value propositions
 - Include market analysis and competitive positioning insights
 - Reference framework document using @ notation for integration
@@ -116,7 +116,7 @@ TodoWrite({
       activeForm: "Detecting session and framework"
     },
     {
-      content: "Load topic-framework.md and session metadata for context",
+      content: "Load guidance-specification.md and session metadata for context",
       status: "pending",
       activeForm: "Loading framework and session context"
     },
@@ -144,7 +144,7 @@ TodoWrite({
 ### Framework-Based Analysis
 ```
 .workflow/WFS-{session}/.brainstorming/product-manager/
-└── analysis.md    # Structured analysis addressing topic-framework.md discussion points
+└── analysis.md    # Structured analysis addressing guidance-specification.md discussion points
 ```
 
 ### Analysis Document Structure
@@ -152,11 +152,11 @@ TodoWrite({
 # Product Manager Analysis: [Topic from Framework]
 
 ## Framework Reference
-**Topic Framework**: @../topic-framework.md
+**Topic Framework**: @../guidance-specification.md
 **Role Focus**: Product Strategy perspective
 
 ## Discussion Points Analysis
-[Address each point from topic-framework.md with product management expertise]
+[Address each point from guidance-specification.md with product management expertise]
 
 ### Core Requirements (from framework)
 [Product strategy perspective on user needs and requirements]
@@ -189,12 +189,12 @@ TodoWrite({
     "status": "completed",
     "framework_addressed": true,
     "output_location": ".workflow/WFS-{session}/.brainstorming/product-manager/analysis.md",
-    "framework_reference": "@../topic-framework.md"
+    "framework_reference": "@../guidance-specification.md"
   }
 }
 ```
 
 ### Integration Points
-- **Framework Reference**: @../topic-framework.md for structured discussion points
+- **Framework Reference**: @../guidance-specification.md for structured discussion points
 - **Cross-Role Synthesis**: Product strategy insights available for synthesis-report.md integration
 - **Agent Autonomy**: Independent execution with framework guidance

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

@@ -1,6 +1,6 @@
 ---
 name: product-owner
-description: Generate or update product-owner/analysis.md addressing topic-framework discussion points
+description: Generate or update product-owner/analysis.md addressing guidance-specification discussion points
 argument-hint: "optional topic - uses existing framework if available"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
@@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ## 🎯 **Product Owner Analysis Generator**
 
 ### Purpose
-**Specialized command for generating product-owner/analysis.md** that addresses topic-framework.md discussion points from product backlog and feature prioritization perspective. Creates or updates role-specific analysis with framework references.
+**Specialized command for generating product-owner/analysis.md** that addresses guidance-specification.md discussion points from product backlog and feature prioritization perspective. Creates or updates role-specific analysis with framework references.
 
 ### Core Function
-- **Framework-based Analysis**: Address each discussion point in topic-framework.md
+- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
 - **Product Backlog Focus**: Feature prioritization, user stories, and acceptance criteria
 - **Update Mechanism**: Create new or update existing analysis.md
 - **Agent Delegation**: Use conceptual-planning-agent for analysis generation
@@ -32,7 +32,7 @@ IF active_session EXISTS:
     session_id = get_active_session()
     brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
 
-    CHECK: brainstorm_dir/topic-framework.md
+    CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
         framework_mode = true
         load_framework = true
@@ -73,7 +73,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
 ## Flow Control Steps
 1. **load_topic_framework**
    - Action: Load structured topic discussion framework
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
+   - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
    - Output: topic_framework_content
 
 2. **load_role_template**
@@ -87,17 +87,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
    - Output: session_context
 
 ## Analysis Requirements
-**Framework Reference**: Address all discussion points in topic-framework.md from product backlog and feature prioritization perspective
+**Framework Reference**: Address all discussion points in guidance-specification.md from product backlog and feature prioritization perspective
 **Role Focus**: Backlog management, stakeholder alignment, feature prioritization, acceptance criteria
 **Structured Approach**: Create analysis.md addressing framework discussion points
 **Template Integration**: Apply role template guidelines within framework structure
 
 ## Expected Deliverables
 1. **analysis.md**: Comprehensive product ownership analysis addressing all framework discussion points
-2. **Framework Reference**: Include @../topic-framework.md reference in analysis
+2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
 
 ## Completion Criteria
-- Address each discussion point from topic-framework.md with product ownership expertise
+- Address each discussion point from guidance-specification.md with product ownership expertise
 - Provide actionable user stories and acceptance criteria definitions
 - Include feature prioritization and stakeholder alignment strategies
 - Reference framework document using @ notation for integration
@@ -116,7 +116,7 @@ TodoWrite({
       activeForm: "Detecting session and framework"
     },
     {
-      content: "Load topic-framework.md and session metadata for context",
+      content: "Load guidance-specification.md and session metadata for context",
       status: "pending",
       activeForm: "Loading framework and session context"
     },
@@ -144,7 +144,7 @@ TodoWrite({
 ### Framework-Based Analysis
 ```
 .workflow/WFS-{session}/.brainstorming/product-owner/
-└── analysis.md    # Structured analysis addressing topic-framework.md discussion points
+└── analysis.md    # Structured analysis addressing guidance-specification.md discussion points
 ```
 
 ### Analysis Document Structure
@@ -152,11 +152,11 @@ TodoWrite({
 # Product Owner Analysis: [Topic from Framework]
 
 ## Framework Reference
-**Topic Framework**: @../topic-framework.md
+**Topic Framework**: @../guidance-specification.md
 **Role Focus**: Product Backlog & Feature Prioritization perspective
 
 ## Discussion Points Analysis
-[Address each point from topic-framework.md with product ownership expertise]
+[Address each point from guidance-specification.md with product ownership expertise]
 
 ### Core Requirements (from framework)
 [User story formulation and backlog refinement perspective]
@@ -189,12 +189,12 @@ TodoWrite({
     "status": "completed",
     "framework_addressed": true,
     "output_location": ".workflow/WFS-{session}/.brainstorming/product-owner/analysis.md",
-    "framework_reference": "@../topic-framework.md"
+    "framework_reference": "@../guidance-specification.md"
   }
 }
 ```
 
 ### Integration Points
-- **Framework Reference**: @../topic-framework.md for structured discussion points
+- **Framework Reference**: @../guidance-specification.md for structured discussion points
 - **Cross-Role Synthesis**: Product ownership insights available for synthesis-report.md integration
 - **Agent Autonomy**: Independent execution with framework guidance

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

@@ -1,6 +1,6 @@
 ---
 name: scrum-master
-description: Generate or update scrum-master/analysis.md addressing topic-framework discussion points
+description: Generate or update scrum-master/analysis.md addressing guidance-specification discussion points
 argument-hint: "optional topic - uses existing framework if available"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
@@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ## 🎯 **Scrum Master Analysis Generator**
 
 ### Purpose
-**Specialized command for generating scrum-master/analysis.md** that addresses topic-framework.md discussion points from agile process and team collaboration perspective. Creates or updates role-specific analysis with framework references.
+**Specialized command for generating scrum-master/analysis.md** that addresses guidance-specification.md discussion points from agile process and team collaboration perspective. Creates or updates role-specific analysis with framework references.
 
 ### Core Function
-- **Framework-based Analysis**: Address each discussion point in topic-framework.md
+- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
 - **Agile Process Focus**: Sprint planning, team dynamics, and delivery optimization
 - **Update Mechanism**: Create new or update existing analysis.md
 - **Agent Delegation**: Use conceptual-planning-agent for analysis generation
@@ -32,7 +32,7 @@ IF active_session EXISTS:
     session_id = get_active_session()
     brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
 
-    CHECK: brainstorm_dir/topic-framework.md
+    CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
         framework_mode = true
         load_framework = true
@@ -73,7 +73,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
 ## Flow Control Steps
 1. **load_topic_framework**
    - Action: Load structured topic discussion framework
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
+   - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
    - Output: topic_framework_content
 
 2. **load_role_template**
@@ -87,17 +87,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
    - Output: session_context
 
 ## Analysis Requirements
-**Framework Reference**: Address all discussion points in topic-framework.md from agile process and team collaboration perspective
+**Framework Reference**: Address all discussion points in guidance-specification.md from agile process and team collaboration perspective
 **Role Focus**: Sprint planning, team dynamics, process optimization, delivery management
 **Structured Approach**: Create analysis.md addressing framework discussion points
 **Template Integration**: Apply role template guidelines within framework structure
 
 ## Expected Deliverables
 1. **analysis.md**: Comprehensive agile process analysis addressing all framework discussion points
-2. **Framework Reference**: Include @../topic-framework.md reference in analysis
+2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
 
 ## Completion Criteria
-- Address each discussion point from topic-framework.md with scrum mastery expertise
+- Address each discussion point from guidance-specification.md with scrum mastery expertise
 - Provide actionable sprint planning and team facilitation strategies
 - Include process optimization and impediment removal insights
 - Reference framework document using @ notation for integration
@@ -116,7 +116,7 @@ TodoWrite({
       activeForm: "Detecting session and framework"
     },
     {
-      content: "Load topic-framework.md and session metadata for context",
+      content: "Load guidance-specification.md and session metadata for context",
       status: "pending",
       activeForm: "Loading framework and session context"
     },
@@ -144,7 +144,7 @@ TodoWrite({
 ### Framework-Based Analysis
 ```
 .workflow/WFS-{session}/.brainstorming/scrum-master/
-└── analysis.md    # Structured analysis addressing topic-framework.md discussion points
+└── analysis.md    # Structured analysis addressing guidance-specification.md discussion points
 ```
 
 ### Analysis Document Structure
@@ -152,11 +152,11 @@ TodoWrite({
 # Scrum Master Analysis: [Topic from Framework]
 
 ## Framework Reference
-**Topic Framework**: @../topic-framework.md
+**Topic Framework**: @../guidance-specification.md
 **Role Focus**: Agile Process & Team Collaboration perspective
 
 ## Discussion Points Analysis
-[Address each point from topic-framework.md with scrum mastery expertise]
+[Address each point from guidance-specification.md with scrum mastery expertise]
 
 ### Core Requirements (from framework)
 [Sprint planning and iteration breakdown perspective]
@@ -189,12 +189,12 @@ TodoWrite({
     "status": "completed",
     "framework_addressed": true,
     "output_location": ".workflow/WFS-{session}/.brainstorming/scrum-master/analysis.md",
-    "framework_reference": "@../topic-framework.md"
+    "framework_reference": "@../guidance-specification.md"
   }
 }
 ```
 
 ### Integration Points
-- **Framework Reference**: @../topic-framework.md for structured discussion points
+- **Framework Reference**: @../guidance-specification.md for structured discussion points
 - **Cross-Role Synthesis**: Agile process insights available for synthesis-report.md integration
 - **Agent Autonomy**: Independent execution with framework guidance

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

@@ -1,6 +1,6 @@
 ---
 name: subject-matter-expert
-description: Generate or update subject-matter-expert/analysis.md addressing topic-framework discussion points
+description: Generate or update subject-matter-expert/analysis.md addressing guidance-specification discussion points
 argument-hint: "optional topic - uses existing framework if available"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
@@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ## 🎯 **Subject Matter Expert Analysis Generator**
 
 ### Purpose
-**Specialized command for generating subject-matter-expert/analysis.md** that addresses topic-framework.md discussion points from domain knowledge and technical expertise perspective. Creates or updates role-specific analysis with framework references.
+**Specialized command for generating subject-matter-expert/analysis.md** that addresses guidance-specification.md discussion points from domain knowledge and technical expertise perspective. Creates or updates role-specific analysis with framework references.
 
 ### Core Function
-- **Framework-based Analysis**: Address each discussion point in topic-framework.md
+- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
 - **Domain Expertise Focus**: Deep technical knowledge, industry standards, and best practices
 - **Update Mechanism**: Create new or update existing analysis.md
 - **Agent Delegation**: Use conceptual-planning-agent for analysis generation
@@ -32,7 +32,7 @@ IF active_session EXISTS:
     session_id = get_active_session()
     brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
 
-    CHECK: brainstorm_dir/topic-framework.md
+    CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
         framework_mode = true
         load_framework = true
@@ -73,7 +73,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
 ## Flow Control Steps
 1. **load_topic_framework**
    - Action: Load structured topic discussion framework
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
+   - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
    - Output: topic_framework_content
 
 2. **load_role_template**
@@ -87,17 +87,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
    - Output: session_context
 
 ## Analysis Requirements
-**Framework Reference**: Address all discussion points in topic-framework.md from domain expertise and technical standards perspective
+**Framework Reference**: Address all discussion points in guidance-specification.md from domain expertise and technical standards perspective
 **Role Focus**: Domain knowledge, technical standards, risk assessment, knowledge transfer
 **Structured Approach**: Create analysis.md addressing framework discussion points
 **Template Integration**: Apply role template guidelines within framework structure
 
 ## Expected Deliverables
 1. **analysis.md**: Comprehensive domain expertise analysis addressing all framework discussion points
-2. **Framework Reference**: Include @../topic-framework.md reference in analysis
+2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
 
 ## Completion Criteria
-- Address each discussion point from topic-framework.md with subject matter expertise
+- Address each discussion point from guidance-specification.md with subject matter expertise
 - Provide actionable technical standards and best practices recommendations
 - Include risk assessment and compliance considerations
 - Reference framework document using @ notation for integration
@@ -116,7 +116,7 @@ TodoWrite({
       activeForm: "Detecting session and framework"
     },
     {
-      content: "Load topic-framework.md and session metadata for context",
+      content: "Load guidance-specification.md and session metadata for context",
       status: "pending",
       activeForm: "Loading framework and session context"
     },
@@ -144,7 +144,7 @@ TodoWrite({
 ### Framework-Based Analysis
 ```
 .workflow/WFS-{session}/.brainstorming/subject-matter-expert/
-└── analysis.md    # Structured analysis addressing topic-framework.md discussion points
+└── analysis.md    # Structured analysis addressing guidance-specification.md discussion points
 ```
 
 ### Analysis Document Structure
@@ -152,11 +152,11 @@ TodoWrite({
 # Subject Matter Expert Analysis: [Topic from Framework]
 
 ## Framework Reference
-**Topic Framework**: @../topic-framework.md
+**Topic Framework**: @../guidance-specification.md
 **Role Focus**: Domain Expertise & Technical Standards perspective
 
 ## Discussion Points Analysis
-[Address each point from topic-framework.md with subject matter expertise]
+[Address each point from guidance-specification.md with subject matter expertise]
 
 ### Core Requirements (from framework)
 [Domain-specific requirements and industry standards perspective]
@@ -189,12 +189,12 @@ TodoWrite({
     "status": "completed",
     "framework_addressed": true,
     "output_location": ".workflow/WFS-{session}/.brainstorming/subject-matter-expert/analysis.md",
-    "framework_reference": "@../topic-framework.md"
+    "framework_reference": "@../guidance-specification.md"
   }
 }
 ```
 
 ### Integration Points
-- **Framework Reference**: @../topic-framework.md for structured discussion points
+- **Framework Reference**: @../guidance-specification.md for structured discussion points
 - **Cross-Role Synthesis**: Domain expertise insights available for synthesis-report.md integration
 - **Agent Autonomy**: Independent execution with framework guidance

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

@@ -1,346 +1,438 @@
 ---
 name: synthesis
-description: Generate synthesis-specification.md from topic-framework and role analyses with @ references using conceptual-planning-agent
+description: Clarify and refine role analyses through intelligent Q&A and targeted updates
-argument-hint: "no arguments required - synthesizes existing framework and role analyses"
+argument-hint: "[optional: --session session-id]"
-allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
+allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*), Edit(*), Glob(*)
 ---
 
-## 🧩 **Synthesis Document Generator**
+## Overview
 
-### Core Function
+Three-phase workflow to eliminate ambiguities and enhance conceptual depth in role analyses:
-**Specialized command for generating synthesis-specification.md** that integrates topic-framework.md and all role analysis.md files using @ reference system. Creates comprehensive implementation specification with cross-role insights.
 
-**Dynamic Role Discovery**: Automatically detects which roles participated in brainstorming by scanning for `*/analysis.md` files. Synthesizes only actual participating roles, not predefined lists.
+**Phase 1-2 (Main Flow)**: Session detection → File discovery → Path preparation
 
-### Primary Capabilities
+**Phase 3A (Analysis Agent)**: Cross-role analysis → Generate recommendations
-- **Dynamic Role Discovery**: Automatically identifies participating roles at runtime
-- **Framework Integration**: Reference topic-framework.md discussion points across all discovered roles
-- **Role Analysis Integration**: Consolidate all discovered role/analysis.md files using @ references
-- **Cross-Framework Comparison**: Compare how each participating role addressed framework discussion points
-- **@ Reference System**: Create structured references to source documents
-- **Update Detection**: Smart updates when new role analyses are added
-- **Flexible Participation**: Supports any subset of available roles (1 to 9+)
 
-### Document Integration Model
+**Phase 4 (Main Flow)**: User selects enhancements → User answers clarifications → Build update plan
-**Three-Document Reference System**:
-1. **topic-framework.md** → Structured discussion framework (input)
-2. **[role]/analysis.md** → Role-specific analyses addressing framework (input)
-3. **synthesis-specification.md** → Complete integrated specification (output)
 
-## ⚙️ **Execution Protocol**
+**Phase 5 (Parallel Update Agents)**: Each agent updates ONE role document → Parallel execution
 
-### ⚠️ Agent Execution with Flow Control
+**Phase 6 (Main Flow)**: Metadata update → Completion report
-**Execution Model**: Uses conceptual-planning-agent for synthesis generation with structured file loading.
 
-**Rationale**:
+**Key Features**:
-- **Autonomous Execution**: Agent independently loads and processes all required documents
+- Multi-agent architecture (analysis agent + parallel update agents)
-- **Flow Control**: Structured document loading ensures systematic analysis
+- Clear separation: Agent analysis vs Main flow interaction
-- **Complex Cognitive Analysis**: Leverages agent's analytical capabilities for cross-role synthesis
+- Parallel document updates (one agent per role)
-- **Conceptual Focus**: Agent specializes in conceptual analysis and multi-perspective integration
+- User intent alignment validation
 
-**Agent Responsibility**: All file reading and synthesis generation performed by conceptual-planning-agent with FLOW_CONTROL instructions.
+**Document Flow**:
+- Input: `[role]/analysis*.md`, `guidance-specification.md`, session metadata
+- Output: Updated `[role]/analysis*.md` with Enhancements + Clarifications sections
+
+## Task Tracking
 
-### 📋 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": "Detect session and validate analyses", "status": "in_progress", "activeForm": "Detecting session"},
-  {"content": "Discover participating role analyses dynamically", "status": "pending", "activeForm": "Discovering role analyses"},
+  {"content": "Discover role analysis file paths", "status": "pending", "activeForm": "Discovering paths"},
-  {"content": "Check existing synthesis and confirm user action", "status": "pending", "activeForm": "Checking update mechanism"},
+  {"content": "Execute analysis agent (cross-role analysis)", "status": "pending", "activeForm": "Executing analysis agent"},
-  {"content": "Execute synthesis generation using conceptual-planning-agent with FLOW_CONTROL", "status": "pending", "activeForm": "Executing agent-based synthesis generation"},
+  {"content": "Present enhancements for user selection", "status": "pending", "activeForm": "Presenting enhancements"},
-  {"content": "Agent performs cross-role analysis and generates synthesis-specification.md", "status": "pending", "activeForm": "Agent analyzing and generating synthesis"},
+  {"content": "Generate and present clarification questions", "status": "pending", "activeForm": "Clarifying with user"},
-  {"content": "Update workflow-session.json with synthesis completion status", "status": "pending", "activeForm": "Updating session metadata"}
+  {"content": "Build update plan from user input", "status": "pending", "activeForm": "Building update plan"},
+  {"content": "Execute parallel update agents (one per role)", "status": "pending", "activeForm": "Updating documents in parallel"},
+  {"content": "Update session metadata and generate report", "status": "pending", "activeForm": "Finalizing session"}
 ]
 ```
 
-### Phase 1: Document Discovery & Validation
+## Execution Phases
-```bash
-# Detect active brainstorming session
-CHECK: .workflow/.active-* marker files
-IF active_session EXISTS:
-    session_id = get_active_session()
-    brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
-ELSE:
-    ERROR: "No active brainstorming session found"
-    EXIT
 
-# Validate required documents
+### Phase 1: Discovery & Validation
-CHECK: brainstorm_dir/topic-framework.md
-IF NOT EXISTS:
-    ERROR: "topic-framework.md not found. Run /workflow:brainstorm:artifacts first"
-    EXIT
-```
 
-### Phase 2: Role Analysis Discovery
+1. **Detect Session**: Use `--session` parameter or `.workflow/.active-*` marker
-```bash
+2. **Validate Files**:
-# Dynamically discover available role analyses
+   - `guidance-specification.md` (optional, warn if missing)
-SCAN_DIRECTORY: .workflow/WFS-{session}/.brainstorming/
+   - `*/analysis*.md` (required, error if empty)
-FIND_ANALYSES: [
+3. **Load User Intent**: Extract from `workflow-session.json` (project/description field)
-    Scan all subdirectories for */analysis.md files
-    Extract role names from directory names
-]
 
-# Available roles (for reference, actual participation is dynamic):
+### Phase 2: Role Discovery & Path Preparation
-# - product-manager
-# - product-owner
-# - scrum-master
-# - system-architect
-# - ui-designer
-# - ux-expert
-# - data-architect
-# - subject-matter-expert
-# - test-strategist
 
-LOAD_DOCUMENTS: {
+**Main flow prepares file paths for Agent**:
-    "topic_framework": topic-framework.md,
-    "role_analyses": [dynamically discovered analysis.md files],
-    "participating_roles": [extract role names from discovered directories],
-    "existing_synthesis": synthesis-specification.md (if exists)
-}
 
-# Note: Not all roles participate in every brainstorming session
+1. **Discover Analysis Files**:
-# Only synthesize roles that actually produced analysis.md files
+   - Glob(.workflow/WFS-{session}/.brainstorming/*/analysis*.md)
-```
+   - Supports: analysis.md, analysis-1.md, analysis-2.md, analysis-3.md
+   - Validate: At least one file exists (error if empty)
 
-### Phase 3: Update Mechanism Check
+2. **Extract Role Information**:
-```bash
+   - `role_analysis_paths`: Relative paths from brainstorm_dir
-# Check for existing synthesis
+   - `participating_roles`: Role names extracted from directory paths
-IF synthesis-specification.md EXISTS:
-    SHOW current synthesis summary to user
-    ASK: "Synthesis exists. Do you want to:"
-    OPTIONS:
-      1. "Regenerate completely" → Create new synthesis
-      2. "Update with new analyses" → Integrate new role analyses
-      3. "Preserve existing" → Exit without changes
-ELSE:
-    CREATE new synthesis
-```
 
-### Phase 4: Agent Execution with Flow Control
+3. **Pass to Agent** (Phase 3):
-**Synthesis Generation using conceptual-planning-agent**
+   - `session_id`
+   - `brainstorm_dir`: .workflow/WFS-{session}/.brainstorming/
+   - `role_analysis_paths`: ["product-manager/analysis.md", "system-architect/analysis-1.md", ...]
+   - `participating_roles`: ["product-manager", "system-architect", ...]
 
-Delegate synthesis generation to conceptual-planning-agent with structured file loading:
+**Main Flow Responsibility**: File discovery and path preparation only (NO file content reading)
+
+### Phase 3A: Analysis & Enhancement Agent
+
+**First agent call**: Cross-role analysis and generate enhancement recommendations
 
 ```bash
 Task(conceptual-planning-agent): "
+## Agent Mission
+Analyze role documents, identify conflicts/gaps, and generate enhancement recommendations
+
+## Input from Main Flow
+- brainstorm_dir: {brainstorm_dir}
+- role_analysis_paths: {role_analysis_paths}
+- participating_roles: {participating_roles}
+
+## Execution Instructions
 [FLOW_CONTROL]
 
-Execute comprehensive synthesis generation from topic framework and role analyses
+### Flow Control Steps
+**AGENT RESPONSIBILITY**: Execute these analysis steps sequentially with context accumulation:
 
-## Context Loading
+1. **load_session_metadata**
-OUTPUT_FILE: synthesis-specification.md
+   - Action: Load original user intent as primary reference
-OUTPUT_PATH: .workflow/WFS-{session}/.brainstorming/synthesis-specification.md
+   - Command: Read({brainstorm_dir}/../workflow-session.json)
-SESSION_ID: {session_id}
+   - Output: original_user_intent (from project/description field)
-ANALYSIS_MODE: cross_role_synthesis
 
-## Flow Control Steps
+2. **load_role_analyses**
-1. **load_topic_framework**
+   - Action: Load all role analysis documents
-   - Action: Load structured topic discussion framework
+   - Command: For each path in role_analysis_paths: Read({brainstorm_dir}/{path})
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
+   - Output: role_analyses_content_map = {role_name: content}
-   - Output: topic_framework_content
 
-2. **discover_role_analyses**
+3. **cross_role_analysis**
-   - Action: Dynamically discover all participating role analysis files
+   - Action: Identify consensus themes, conflicts, gaps, underspecified areas
-   - Command: Glob(.workflow/WFS-{session}/.brainstorming/*/analysis.md)
+   - Output: consensus_themes, conflicting_views, gaps_list, ambiguities
-   - Output: role_analysis_paths, participating_roles
 
-3. **load_role_analyses**
+4. **generate_recommendations**
-   - Action: Load all discovered role analysis documents
+   - Action: Convert cross-role analysis findings into structured enhancement recommendations
-   - Command: Read(each path from role_analysis_paths)
+   - Format: EP-001, EP-002, ... (sequential numbering)
-   - Output: role_analyses_content
+   - Fields: id, title, affected_roles, category, current_state, enhancement, rationale, priority
+   - Taxonomy: Map to 9 categories (User Intent, Requirements, Architecture, UX, Feasibility, Risk, Process, Decisions, Terminology)
+   - Output: enhancement_recommendations (JSON array)
 
-4. **check_existing_synthesis**
+### Output to Main Flow
-   - Action: Check if synthesis-specification.md already exists
+Return JSON array:
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md) [if exists]
+[
-   - Output: existing_synthesis_content [optional]
+  {
+    \"id\": \"EP-001\",
+    \"title\": \"API Contract Specification\",
+    \"affected_roles\": [\"system-architect\", \"api-designer\"],
+    \"category\": \"Architecture\",
+    \"current_state\": \"High-level API descriptions\",
+    \"enhancement\": \"Add detailed contract definitions with request/response schemas\",
+    \"rationale\": \"Enables precise implementation and testing\",
+    \"priority\": \"High\"
+  },
+  ...
+]
 
-5. **load_session_metadata**
-   - Action: Load session metadata and context
-   - Command: Read(.workflow/WFS-{session}/workflow-session.json)
-   - Output: session_context
-
-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
-
-## Synthesis Requirements
-
-### 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**
+### Phase 4: Main Flow User Interaction
 
-### Output Location
+**Main flow handles all user interaction via text output**:
-The synthesis process creates **one consolidated document** that integrates all role perspectives:
 
-```
+**⚠️ CRITICAL**: ALL questions MUST use Chinese (所有问题必须用中文) for better user understanding
-.workflow/WFS-{topic-slug}/.brainstorming/
+
-├── topic-framework.md          # Input: Framework structure
+1. **Present Enhancement Options** (multi-select):
-├── [role]/analysis.md          # Input: Role analyses (multiple)
+```markdown
-└── synthesis-specification.md  # ★ OUTPUT: Complete integrated specification
+===== Enhancement 选择 =====
+
+请选择要应用的改进建议（可多选）：
+
+a) EP-001: API Contract Specification
+   影响角色：system-architect, api-designer
+   说明：添加详细的请求/响应 schema 定义
+
+b) EP-002: User Intent Validation
+   影响角色：product-manager, ux-expert
+   说明：明确用户需求优先级和验收标准
+
+c) EP-003: Error Handling Strategy
+   影响角色：system-architect
+   说明：统一异常处理和降级方案
+
+支持格式：1abc 或 1a 1b 1c 或 1a,b,c
+请输入选择（可跳过输入 skip）：
 ```
 
-#### synthesis-specification.md Structure
+2. **Generate Clarification Questions** (based on analysis agent output):
+   - ✅ **ALL questions in Chinese (所有问题必须用中文)**
+   - Use 9-category taxonomy scan results
+   - Prioritize most critical questions (no hard limit)
+   - Each with 2-4 options + descriptions
 
-**Document Purpose**: Defines **"WHAT"** to build - comprehensive requirements and design blueprint.
+3. **Interactive Clarification Loop** (max 10 questions per round):
-**Scope**: High-level features, requirements, and design specifications. Does NOT include executable task breakdown (that's IMPL_PLAN.md's responsibility).
+```markdown
+===== Clarification 问题 (第 1/2 轮) =====
 
-**Template Reference**: Complete document structure and content guidelines available in `synthesis-role.md` template, including:
+【问题1 - 用户意图】MVP 阶段的核心目标是什么？
-- Executive Summary with strategic overview
+a) 快速验证市场需求
-- Key Designs & Decisions (architecture diagrams, ADRs, user journeys)
+   说明：最小功能集，快速上线获取反馈
-- Controversial Points & Alternatives (decision transparency)
+b) 建立技术壁垒
-- Requirements & Acceptance Criteria (Functional, Non-Functional, Business)
+   说明：完善架构，为长期发展打基础
-- Design Specifications (UI/UX, Architecture, Domain Expertise)
+c) 实现功能完整性
-- Process & Collaboration Concerns (team skills, risks, patterns, constraints)
+   说明：覆盖所有规划功能，延迟上线
-- Implementation Roadmap (high-level phases)
-- Risk Assessment & Mitigation strategies
 
-**Agent Usage**: The conceptual-planning-agent loads this template to understand expected structure and quality standards.
+【问题2 - 架构决策】技术栈选择的优先考虑因素？
+a) 团队熟悉度
+   说明：使用现有技术栈，降低学习成本
+b) 技术先进性
+   说明：采用新技术，提升竞争力
+c) 生态成熟度
+   说明：选择成熟方案，保证稳定性
 
-## 🔄 **Session Integration**
+...（最多10个问题）
 
-### Streamlined Status Synchronization
+请回答 (格式: 1a 2b 3c...)：
-Upon completion, update `workflow-session.json`:
+```
 
-**Dynamic Role Participation**: The `participating_roles` and `roles_synthesized` values are determined at runtime based on actual analysis.md files discovered.
+Wait for user input → Parse all answers in batch → Continue to next round if needed
 
+4. **Build Update Plan**:
+```
+update_plan = {
+  "role1": {
+    "enhancements": [EP-001, EP-003],
+    "clarifications": [
+      {"question": "...", "answer": "...", "category": "..."},
+      ...
+    ]
+  },
+  "role2": {
+    "enhancements": [EP-002],
+    "clarifications": [...]
+  },
+  ...
+}
+```
+
+### Phase 5: Parallel Document Update Agents
+
+**Parallel agent calls** (one per role needing updates):
+
+```bash
+# Execute in parallel using single message with multiple Task calls
+
+Task(conceptual-planning-agent): "
+## Agent Mission
+Apply user-confirmed enhancements and clarifications to {role1} analysis document
+
+## Agent Intent
+- **Goal**: Integrate synthesis results into role-specific analysis
+- **Scope**: Update ONLY {role1}/analysis.md (isolated, no cross-role dependencies)
+- **Constraints**: Preserve original insights, add refinements without deletion
+
+## Input from Main Flow
+- role: {role1}
+- analysis_path: {brainstorm_dir}/{role1}/analysis.md
+- enhancements: [EP-001, EP-003] (user-selected improvements)
+- clarifications: [{question, answer, category}, ...] (user-confirmed answers)
+- original_user_intent: {from session metadata}
+
+## Execution Instructions
+[FLOW_CONTROL]
+
+### Flow Control Steps
+**AGENT RESPONSIBILITY**: Execute these update steps sequentially:
+
+1. **load_current_analysis**
+   - Action: Load existing role analysis document
+   - Command: Read({brainstorm_dir}/{role1}/analysis.md)
+   - Output: current_analysis_content
+
+2. **add_clarifications_section**
+   - Action: Insert Clarifications section with Q&A
+   - Format: \"## Clarifications\\n### Session {date}\\n- **Q**: {question} (Category: {category})\\n  **A**: {answer}\"
+   - Output: analysis_with_clarifications
+
+3. **apply_enhancements**
+   - Action: Integrate EP-001, EP-003 into relevant sections
+   - Strategy: Locate section by category (Architecture → Architecture section, UX → User Experience section)
+   - Output: analysis_with_enhancements
+
+4. **resolve_contradictions**
+   - Action: Remove conflicts between original content and clarifications/enhancements
+   - Output: contradiction_free_analysis
+
+5. **enforce_terminology_consistency**
+   - Action: Align all terminology with user-confirmed choices from clarifications
+   - Output: terminology_consistent_analysis
+
+6. **validate_user_intent_alignment**
+   - Action: Verify all updates support original_user_intent
+   - Output: validated_analysis
+
+7. **write_updated_file**
+   - Action: Save final analysis document
+   - Command: Write({brainstorm_dir}/{role1}/analysis.md, validated_analysis)
+   - Output: File update confirmation
+
+### Output
+Updated {role1}/analysis.md with Clarifications section + enhanced content
+")
+
+Task(conceptual-planning-agent): "
+## Agent Mission
+Apply user-confirmed enhancements and clarifications to {role2} analysis document
+
+## Agent Intent
+- **Goal**: Integrate synthesis results into role-specific analysis
+- **Scope**: Update ONLY {role2}/analysis.md (isolated, no cross-role dependencies)
+- **Constraints**: Preserve original insights, add refinements without deletion
+
+## Input from Main Flow
+- role: {role2}
+- analysis_path: {brainstorm_dir}/{role2}/analysis.md
+- enhancements: [EP-002] (user-selected improvements)
+- clarifications: [{question, answer, category}, ...] (user-confirmed answers)
+- original_user_intent: {from session metadata}
+
+## Execution Instructions
+[FLOW_CONTROL]
+
+### Flow Control Steps
+**AGENT RESPONSIBILITY**: Execute same 7 update steps as {role1} agent (load → clarifications → enhancements → contradictions → terminology → validation → write)
+
+### Output
+Updated {role2}/analysis.md with Clarifications section + enhanced content
+")
+
+# ... repeat for each role in update_plan
+```
+
+**Agent Characteristics**:
+- **Intent**: Integrate user-confirmed synthesis results (NOT generate new analysis)
+- **Isolation**: Each agent updates exactly ONE role (parallel execution safe)
+- **Context**: Minimal - receives only role-specific enhancements + clarifications
+- **Dependencies**: Zero cross-agent dependencies (full parallelism)
+- **Validation**: All updates must align with original_user_intent
+
+### Phase 6: Completion & Metadata Update
+
+**Main flow finalizes**:
+
+1. Wait for all parallel agents to complete
+2. Update workflow-session.json:
 ```json
 {
   "phases": {
     "BRAINSTORM": {
-      "status": "completed",
+      "status": "clarification_completed",
-      "synthesis_completed": true,
+      "clarification_completed": true,
       "completed_at": "timestamp",
-      "participating_roles": ["<dynamically-discovered-role-1>", "<dynamically-discovered-role-2>", "..."],
+      "participating_roles": [...],
-      "available_roles": ["product-manager", "product-owner", "scrum-master", "system-architect", "ui-designer", "ux-expert", "data-architect", "subject-matter-expert", "test-strategist"],
+      "clarification_results": {
-      "consolidated_output": {
+        "enhancements_applied": ["EP-001", "EP-002", ...],
-        "synthesis_specification": ".workflow/WFS-{topic}/.brainstorming/synthesis-specification.md"
+        "questions_asked": 3,
+        "categories_clarified": ["Architecture", "UX", ...],
+        "roles_updated": ["role1", "role2", ...],
+        "outstanding_items": []
       },
-      "synthesis_quality": {
+      "quality_metrics": {
-        "role_integration": "complete",
+        "user_intent_alignment": "validated",
         "requirement_coverage": "comprehensive",
-        "decision_transparency": "alternatives_documented",
+        "ambiguity_resolution": "complete",
-        "process_risks_identified": true,
+        "terminology_consistency": "enforced"
-        "implementation_readiness": "ready"
-      },
-      "content_metrics": {
-        "roles_synthesized": "<COUNT(participating_roles)>",
-        "functional_requirements": "<dynamic-count>",
-        "non_functional_requirements": "<dynamic-count>",
-        "business_requirements": "<dynamic-count>",
-        "architecture_decisions": "<dynamic-count>",
-        "controversial_points": "<dynamic-count>",
-        "diagrams_included": "<dynamic-count>",
-        "process_risks": "<dynamic-count>",
-        "team_skill_gaps": "<dynamic-count>",
-        "implementation_phases": "<dynamic-count>",
-        "risk_factors_identified": "<dynamic-count>"
       }
     }
   }
 }
 ```
 
-**Example with actual values**:
+3. Generate completion report (show to user):
+```markdown
+## ✅ Clarification Complete
+
+**Enhancements Applied**: EP-001, EP-002, EP-003
+**Questions Answered**: 3/5
+**Roles Updated**: role1, role2, role3
+
+### Next Steps
+✅ PROCEED: `/workflow:plan --session WFS-{session-id}`
+```
+
+## Output
+
+**Location**: `.workflow/WFS-{session}/.brainstorming/[role]/analysis*.md` (in-place updates)
+
+**Updated Structure**:
+```markdown
+## Clarifications
+### Session {date}
+- **Q**: {question} (Category: {category})
+  **A**: {answer}
+
+## {Existing Sections}
+{Refined content based on clarifications}
+```
+
+**Changes**:
+- User intent validated/corrected
+- Requirements more specific/measurable
+- Architecture with rationale
+- Ambiguities resolved, placeholders removed
+- Consistent terminology
+
+## Session Metadata
+
+Update `workflow-session.json`:
+
 ```json
 {
   "phases": {
     "BRAINSTORM": {
-      "status": "completed",
+      "status": "clarification_completed",
-      "participating_roles": ["product-manager", "system-architect", "ui-designer", "ux-expert", "scrum-master"],
+      "clarification_completed": true,
-      "content_metrics": {
+      "completed_at": "timestamp",
-        "roles_synthesized": 5,
+      "participating_roles": ["product-manager", "system-architect", ...],
-        "functional_requirements": 18,
+      "clarification_results": {
-        "controversial_points": 2
+        "questions_asked": 3,
+        "categories_clarified": ["Architecture & Design", ...],
+        "roles_updated": ["system-architect", "ui-designer", ...],
+        "outstanding_items": []
+      },
+      "quality_metrics": {
+        "user_intent_alignment": "validated",
+        "requirement_coverage": "comprehensive",
+        "ambiguity_resolution": "complete",
+        "terminology_consistency": "enforced",
+        "decision_transparency": "documented"
       }
     }
   }
 }
 ```
 
-## ✅ **Quality Assurance**
+## Quality Checklist
 
-Verify synthesis output meets these standards (detailed criteria in `synthesis-role.md` template):
+**Content**:
+- All role analyses loaded/analyzed
+- Cross-role analysis (consensus, conflicts, gaps)
+- 9-category ambiguity scan
+- Questions prioritized
+- Clarifications documented
 
-### Content Completeness
+**Analysis**:
-- [ ] All discovered role analyses integrated without gaps
+- User intent validated
-- [ ] Key designs documented (architecture diagrams, ADRs, user journeys via Mermaid)
+- Cross-role synthesis complete
-- [ ] Controversial points captured with alternatives and rationale
+- Ambiguities resolved
-- [ ] Process concerns included (team skills, risks, collaboration patterns)
+- Correct roles updated
-- [ ] Requirements documented (Functional, Non-Functional, Business) with sources
+- Terminology consistent
+- Contradictions removed
 
-### Analysis Quality
+**Documents**:
-- [ ] Cross-role synthesis identifies consensus and conflicts
+- Clarifications section formatted
-- [ ] Decision transparency documents both adopted and rejected alternatives
+- Sections reflect answers
-- [ ] Priority recommendations with multi-dimensional evaluation
+- No placeholders (TODO/TBD)
-- [ ] Implementation roadmap with phased approach
+- Valid Markdown
-- [ ] Risk assessment with mitigation strategies
+- Cross-references maintained
-- [ ] @ references to source role analyses throughout
 
-## 🚀 **Recommended Next Steps**
 
-After synthesis completion, proceed to action planning:
-
-### Standard Workflow (Recommended)
-```bash
-/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
-```
-
-### TDD Workflow
-```bash
-/workflow:concept-clarify --session WFS-{session-id}  # Optional: Clarify ambiguities
-/workflow:tdd-plan --session WFS-{session-id} "Feature description"
-/workflow:action-plan-verify --session WFS-{session-id}  # Optional: Verify plan quality
-/workflow:execute --session WFS-{session-id}
-```

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

@@ -1,6 +1,6 @@
 ---
 name: system-architect
-description: Generate or update system-architect/analysis.md addressing topic-framework discussion points
+description: Generate or update system-architect/analysis.md addressing guidance-specification discussion points
 argument-hint: "optional topic - uses existing framework if available"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
@@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ## 🏗️ **System Architect Analysis Generator**
 
 ### Purpose
-**Specialized command for generating system-architect/analysis.md** that addresses topic-framework.md discussion points from system architecture perspective. Creates or updates role-specific analysis with framework references.
+**Specialized command for generating system-architect/analysis.md** that addresses guidance-specification.md discussion points from system architecture perspective. Creates or updates role-specific analysis with framework references.
 
 ### Core Function
-- **Framework-based Analysis**: Address each discussion point in topic-framework.md
+- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
 - **Architecture Focus**: Technical architecture, scalability, and system design perspective
 - **Update Mechanism**: Create new or update existing analysis.md
 - **Agent Delegation**: Use conceptual-planning-agent for analysis generation
@@ -51,7 +51,7 @@ IF active_session EXISTS:
     session_id = get_active_session()
     brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
 
-    CHECK: brainstorm_dir/topic-framework.md
+    CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
         framework_mode = true
         load_framework = true
@@ -78,20 +78,20 @@ ELSE:
 ```
 
 ### Phase 3: Agent Task Generation
-**Framework-Based Analysis** (when topic-framework.md exists):
+**Framework-Based Analysis** (when guidance-specification.md exists):
 ```bash
 Task(subagent_type="conceptual-planning-agent",
      prompt="Generate system architect analysis addressing topic framework
 
      ## Framework Integration Required
-     **MANDATORY**: Load and address topic-framework.md discussion points
+     **MANDATORY**: Load and address guidance-specification.md discussion points
-     **Framework Reference**: @{session.brainstorm_dir}/topic-framework.md
+     **Framework Reference**: @{session.brainstorm_dir}/guidance-specification.md
      **Output Location**: {session.brainstorm_dir}/system-architect/analysis.md
 
      ## Analysis Requirements
-     1. **Load Topic Framework**: Read topic-framework.md completely
+     1. **Load Topic Framework**: Read guidance-specification.md completely
      2. **Address Each Discussion Point**: Respond to all 5 framework sections from system architecture perspective
-     3. **Include Framework Reference**: Start analysis.md with @../topic-framework.md
+     3. **Include Framework Reference**: Start analysis.md with @../guidance-specification.md
      4. **Technical Focus**: Emphasize scalability, architecture patterns, technology decisions
      5. **Structured Response**: Use framework structure for analysis organization
 
@@ -106,7 +106,7 @@ Task(subagent_type="conceptual-planning-agent",
      ```markdown
      # System Architect Analysis: [Topic]
 
-     **Framework Reference**: @../topic-framework.md
+     **Framework Reference**: @../guidance-specification.md
      **Role Focus**: System Architecture and Technical Design
 
      ## Core Requirements Analysis
@@ -140,14 +140,14 @@ IF update_mode = "incremental":
 
          ## Current Analysis Context
          **Existing Analysis**: @{session.brainstorm_dir}/system-architect/analysis.md
-         **Framework Reference**: @{session.brainstorm_dir}/topic-framework.md
+         **Framework Reference**: @{session.brainstorm_dir}/guidance-specification.md
 
          ## Update Requirements
          1. **Preserve Structure**: Maintain existing analysis structure
          2. **Add New Insights**: Integrate new technical insights and recommendations
          3. **Framework Alignment**: Ensure continued alignment with topic framework
          4. **Technical Updates**: Add new architecture patterns, technology considerations
-         5. **Maintain References**: Keep @../topic-framework.md reference
+         5. **Maintain References**: Keep @../guidance-specification.md reference
 
          ## Update Instructions
          - Read existing analysis completely
@@ -163,14 +163,14 @@ IF update_mode = "incremental":
 ### Output Files
 ```
 .workflow/WFS-[topic]/.brainstorming/
-├── topic-framework.md          # Input: Framework (if exists)
+├── guidance-specification.md          # Input: Framework (if exists)
 └── system-architect/
     └── analysis.md            # ★ OUTPUT: Framework-based analysis
 ```
 
 ### Analysis Structure
 **Required Elements**:
-- **Framework Reference**: @../topic-framework.md (if framework exists)
+- **Framework Reference**: @../guidance-specification.md (if framework exists)
 - **Role Focus**: System Architecture and Technical Design perspective
 - **5 Framework Sections**: Address each framework discussion point
 - **Technical Recommendations**: Architecture-specific insights and solutions

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

@@ -1,6 +1,6 @@
 ---
 name: ui-designer
-description: Generate or update ui-designer/analysis.md addressing topic-framework discussion points
+description: Generate or update ui-designer/analysis.md addressing guidance-specification discussion points
 argument-hint: "optional topic - uses existing framework if available"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
@@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ## 🎨 **UI Designer Analysis Generator**
 
 ### Purpose
-**Specialized command for generating ui-designer/analysis.md** that addresses topic-framework.md discussion points from UI/UX design perspective. Creates or updates role-specific analysis with framework references.
+**Specialized command for generating ui-designer/analysis.md** that addresses guidance-specification.md discussion points from UI/UX design perspective. Creates or updates role-specific analysis with framework references.
 
 ### Core Function
-- **Framework-based Analysis**: Address each discussion point in topic-framework.md
+- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
 - **UI/UX Focus**: User experience, interface design, and accessibility perspective
 - **Update Mechanism**: Create new or update existing analysis.md
 - **Agent Delegation**: Use conceptual-planning-agent for analysis generation
@@ -53,7 +53,7 @@ IF active_session EXISTS:
     session_id = get_active_session()
     brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
 
-    CHECK: brainstorm_dir/topic-framework.md
+    CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
         framework_mode = true
         load_framework = true
@@ -94,7 +94,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
 ## Flow Control Steps
 1. **load_topic_framework**
    - Action: Load structured topic discussion framework
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
+   - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
    - Output: topic_framework_content
 
 2. **load_role_template**
@@ -108,17 +108,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
    - Output: session_context
 
 ## Analysis Requirements
-**Framework Reference**: Address all discussion points in topic-framework.md from UI/UX perspective
+**Framework Reference**: Address all discussion points in guidance-specification.md from UI/UX perspective
 **Role Focus**: User experience design, interface optimization, accessibility compliance
 **Structured Approach**: Create analysis.md addressing framework discussion points
 **Template Integration**: Apply role template guidelines within framework structure
 
 ## Expected Deliverables
 1. **analysis.md**: Comprehensive UI/UX analysis addressing all framework discussion points
-2. **Framework Reference**: Include @../topic-framework.md reference in analysis
+2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
 
 ## Completion Criteria
-- Address each discussion point from topic-framework.md with UI/UX design expertise
+- Address each discussion point from guidance-specification.md with UI/UX design expertise
 - Provide actionable design recommendations and interface solutions
 - Include accessibility considerations and WCAG compliance planning
 - Reference framework document using @ notation for integration
@@ -137,7 +137,7 @@ TodoWrite({
       activeForm: "Detecting session and framework"
     },
     {
-      content: "Load topic-framework.md and session metadata for context",
+      content: "Load guidance-specification.md and session metadata for context",
       status: "pending",
       activeForm: "Loading framework and session context"
     },
@@ -165,7 +165,7 @@ TodoWrite({
 ### Framework-Based Analysis
 ```
 .workflow/WFS-{session}/.brainstorming/ui-designer/
-└── analysis.md    # Structured analysis addressing topic-framework.md discussion points
+└── analysis.md    # Structured analysis addressing guidance-specification.md discussion points
 ```
 
 ### Analysis Document Structure
@@ -173,11 +173,11 @@ TodoWrite({
 # UI Designer Analysis: [Topic from Framework]
 
 ## Framework Reference
-**Topic Framework**: @../topic-framework.md
+**Topic Framework**: @../guidance-specification.md
 **Role Focus**: UI/UX Design perspective
 
 ## Discussion Points Analysis
-[Address each point from topic-framework.md with UI/UX expertise]
+[Address each point from guidance-specification.md with UI/UX expertise]
 
 ### Core Requirements (from framework)
 [UI/UX perspective on requirements]
@@ -210,12 +210,12 @@ TodoWrite({
     "status": "completed",
     "framework_addressed": true,
     "output_location": ".workflow/WFS-{session}/.brainstorming/ui-designer/analysis.md",
-    "framework_reference": "@../topic-framework.md"
+    "framework_reference": "@../guidance-specification.md"
   }
 }
 ```
 
 ### Integration Points
-- **Framework Reference**: @../topic-framework.md for structured discussion points
+- **Framework Reference**: @../guidance-specification.md for structured discussion points
 - **Cross-Role Synthesis**: UI/UX insights available for synthesis-report.md integration
 - **Agent Autonomy**: Independent execution with framework guidance

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

@@ -1,6 +1,6 @@
 ---
 name: ux-expert
-description: Generate or update ux-expert/analysis.md addressing topic-framework discussion points
+description: Generate or update ux-expert/analysis.md addressing guidance-specification discussion points
 argument-hint: "optional topic - uses existing framework if available"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
@@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ## 🎯 **UX Expert Analysis Generator**
 
 ### Purpose
-**Specialized command for generating ux-expert/analysis.md** that addresses topic-framework.md discussion points from user experience and interface design perspective. Creates or updates role-specific analysis with framework references.
+**Specialized command for generating ux-expert/analysis.md** that addresses guidance-specification.md discussion points from user experience and interface design perspective. Creates or updates role-specific analysis with framework references.
 
 ### Core Function
-- **Framework-based Analysis**: Address each discussion point in topic-framework.md
+- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
 - **UX Design Focus**: User interface, interaction patterns, and usability optimization
 - **Update Mechanism**: Create new or update existing analysis.md
 - **Agent Delegation**: Use conceptual-planning-agent for analysis generation
@@ -53,7 +53,7 @@ IF active_session EXISTS:
     session_id = get_active_session()
     brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
 
-    CHECK: brainstorm_dir/topic-framework.md
+    CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
         framework_mode = true
         load_framework = true
@@ -94,7 +94,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
 ## Flow Control Steps
 1. **load_topic_framework**
    - Action: Load structured topic discussion framework
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
+   - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
    - Output: topic_framework_content
 
 2. **load_role_template**
@@ -108,17 +108,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
    - Output: session_context
 
 ## Analysis Requirements
-**Framework Reference**: Address all discussion points in topic-framework.md from user experience and interface design perspective
+**Framework Reference**: Address all discussion points in guidance-specification.md from user experience and interface design perspective
 **Role Focus**: UI design, interaction patterns, usability optimization, design systems
 **Structured Approach**: Create analysis.md addressing framework discussion points
 **Template Integration**: Apply role template guidelines within framework structure
 
 ## Expected Deliverables
 1. **analysis.md**: Comprehensive UX design analysis addressing all framework discussion points
-2. **Framework Reference**: Include @../topic-framework.md reference in analysis
+2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
 
 ## Completion Criteria
-- Address each discussion point from topic-framework.md with UX design expertise
+- Address each discussion point from guidance-specification.md with UX design expertise
 - Provide actionable interface design and usability optimization strategies
 - Include accessibility considerations and interaction pattern recommendations
 - Reference framework document using @ notation for integration
@@ -137,7 +137,7 @@ TodoWrite({
       activeForm: "Detecting session and framework"
     },
     {
-      content: "Load topic-framework.md and session metadata for context",
+      content: "Load guidance-specification.md and session metadata for context",
       status: "pending",
       activeForm: "Loading framework and session context"
     },
@@ -165,7 +165,7 @@ TodoWrite({
 ### Framework-Based Analysis
 ```
 .workflow/WFS-{session}/.brainstorming/ux-expert/
-└── analysis.md    # Structured analysis addressing topic-framework.md discussion points
+└── analysis.md    # Structured analysis addressing guidance-specification.md discussion points
 ```
 
 ### Analysis Document Structure
@@ -173,11 +173,11 @@ TodoWrite({
 # UX Expert Analysis: [Topic from Framework]
 
 ## Framework Reference
-**Topic Framework**: @../topic-framework.md
+**Topic Framework**: @../guidance-specification.md
 **Role Focus**: User Experience & Interface Design perspective
 
 ## Discussion Points Analysis
-[Address each point from topic-framework.md with UX design expertise]
+[Address each point from guidance-specification.md with UX design expertise]
 
 ### Core Requirements (from framework)
 [User interface and interaction design requirements perspective]
@@ -210,12 +210,12 @@ TodoWrite({
     "status": "completed",
     "framework_addressed": true,
     "output_location": ".workflow/WFS-{session}/.brainstorming/ux-expert/analysis.md",
-    "framework_reference": "@../topic-framework.md"
+    "framework_reference": "@../guidance-specification.md"
   }
 }
 ```
 
 ### Integration Points
-- **Framework Reference**: @../topic-framework.md for structured discussion points
+- **Framework Reference**: @../guidance-specification.md for structured discussion points
 - **Cross-Role Synthesis**: UX design insights available for synthesis-report.md integration
 - **Agent Autonomy**: Independent execution with framework guidance

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

@@ -1,332 +0,0 @@
----
-name: concept-clarify
-description: Identify underspecified areas in brainstorming artifacts through targeted clarification questions before action planning
-argument-hint: "[optional: --session session-id]"
-allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
----
-
-## User Input
-
-```text
-$ARGUMENTS
-```
-
-You **MUST** consider the user input before proceeding (if not empty).
-
-## Outline
-
-**Goal**: Detect and reduce ambiguity or missing decision points in planning artifacts before moving to task generation. Supports both brainstorm and plan workflows.
-
-**Timing**:
-- **Brainstorm mode**: Runs AFTER `/workflow:brainstorm:synthesis` and BEFORE `/workflow:plan`
-- **Plan mode**: Runs AFTER Phase 3 (concept-enhanced) and BEFORE Phase 4 (task-generate) within `/workflow:plan`
-
-This serves as a quality gate to ensure conceptual clarity before detailed task planning or generation.
-
-**Execution steps**:
-
-1. **Session Detection & Validation**
-   ```bash
-   # Detect active workflow session
-   IF --session parameter provided:
-       session_id = provided session
-   ELSE:
-       CHECK: .workflow/.active-* marker files
-       IF active_session EXISTS:
-           session_id = get_active_session()
-       ELSE:
-           ERROR: "No active workflow session found. Use --session <session-id> or start a session."
-           EXIT
-
-   # Mode detection: plan vs brainstorm
-   brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
-   process_dir = .workflow/WFS-{session}/.process/
-
-   IF EXISTS(process_dir/ANALYSIS_RESULTS.md):
-       clarify_mode = "plan"
-       primary_artifact = process_dir/ANALYSIS_RESULTS.md
-       INFO: "Plan mode: Analyzing ANALYSIS_RESULTS.md"
-   ELSE IF EXISTS(brainstorm_dir/synthesis-specification.md):
-       clarify_mode = "brainstorm"
-       primary_artifact = brainstorm_dir/synthesis-specification.md
-       INFO: "Brainstorm mode: Analyzing synthesis-specification.md"
-   ELSE:
-       ERROR: "No valid artifact found. Run /workflow:brainstorm:synthesis or /workflow:plan first"
-       EXIT
-
-   # Mode-specific validation
-   IF clarify_mode == "brainstorm":
-       CHECK: brainstorm_dir/topic-framework.md
-       IF NOT EXISTS:
-           WARN: "topic-framework.md not found. Verification will be limited."
-   ```
-
-2. **Load Artifacts (Mode-Aware)**
-   ```bash
-   # Load primary artifact (determined in step 1)
-   primary_content = Read(primary_artifact)
-
-   # Load mode-specific supplementary artifacts
-   IF clarify_mode == "brainstorm":
-       topic_framework = Read(brainstorm_dir + "/topic-framework.md") # if exists
-       role_analyses = Glob(brainstorm_dir + "/*/analysis.md")
-       participating_roles = extract_role_names(role_analyses)
-   # Plan mode: primary_content (ANALYSIS_RESULTS.md) is self-contained
-   ```
-
-3. **Ambiguity & Coverage Scan**
-
-   Perform structured scan using this taxonomy. For each category, mark status: **Clear** / **Partial** / **Missing**.
-
-   **Requirements Clarity**:
-   - Functional requirements specificity and measurability
-   - Non-functional requirements with quantified targets
-   - Business requirements with success metrics
-   - Acceptance criteria completeness
-
-   **Architecture & Design Clarity**:
-   - Architecture decisions with rationale
-   - Data model completeness (entities, relationships, constraints)
-   - Technology stack justification
-   - Integration points and API contracts
-
-   **User Experience & Interface**:
-   - User journey completeness
-   - Critical interaction flows
-   - Error/edge case handling
-   - Accessibility and localization considerations
-
-   **Implementation Feasibility**:
-   - Team capability vs. required skills
-   - External dependencies and failure modes
-   - Resource constraints (timeline, personnel)
-   - Technical constraints and tradeoffs
-
-   **Risk & Mitigation**:
-   - Critical risks identified
-   - Mitigation strategies defined
-   - Success factors clarity
-   - Monitoring and quality gates
-
-   **Process & Collaboration**:
-   - Role responsibilities and handoffs
-   - Collaboration patterns defined
-   - Timeline and milestone clarity
-   - Dependency management strategy
-
-   **Decision Traceability**:
-   - Controversial points documented
-   - Alternatives considered and rejected
-   - Decision rationale clarity
-   - Consensus vs. dissent tracking
-
-   **Terminology & Consistency**:
-   - Canonical terms defined
-   - Consistent naming across artifacts
-   - No unresolved placeholders (TODO, TBD, ???)
-
-   For each category with **Partial** or **Missing** status, add to candidate question queue unless:
-   - Clarification would not materially change implementation strategy
-   - Information is better deferred to planning phase
-
-4. **Generate Prioritized Question Queue**
-
-   Internally generate prioritized queue of candidate questions (maximum 5):
-
-   **Constraints**:
-   - Maximum 5 questions per session
-   - Each question must be answerable with:
-     * Multiple-choice (2-5 mutually exclusive options), OR
-     * Short answer (≤5 words)
-   - Only include questions whose answers materially impact:
-     * Architecture decisions
-     * Data modeling
-     * Task decomposition
-     * Risk mitigation
-     * Success criteria
-   - Ensure category coverage balance
-   - Favor clarifications that reduce downstream rework risk
-
-   **Prioritization Heuristic**:
-   ```
-   priority_score = (impact_on_planning * 0.4) +
-                    (uncertainty_level * 0.3) +
-                    (risk_if_unresolved * 0.3)
-   ```
-
-   If zero high-impact ambiguities found, proceed to **Step 8** (report success).
-
-5. **Sequential Question Loop** (Interactive)
-
-   Present **EXACTLY ONE** question at a time:
-
-   **Multiple-choice format**:
-   ```markdown
-   **Question {N}/5**: {Question text}
-
-   | Option | Description |
-   |--------|-------------|
-   | A | {Option A description} |
-   | B | {Option B description} |
-   | C | {Option C description} |
-   | D | {Option D description} |
-   | Short | Provide different answer (≤5 words) |
-   ```
-
-   **Short-answer format**:
-   ```markdown
-   **Question {N}/5**: {Question text}
-
-   Format: Short answer (≤5 words)
-   ```
-
-   **Answer Validation**:
-   - Validate answer maps to option or fits ≤5 word constraint
-   - If ambiguous, ask quick disambiguation (doesn't count as new question)
-   - Once satisfactory, record in working memory and proceed to next question
-
-   **Stop Conditions**:
-   - All critical ambiguities resolved
-   - User signals completion ("done", "no more", "proceed")
-   - Reached 5 questions
-
-   **Never reveal future queued questions in advance**.
-
-6. **Integration After Each Answer** (Incremental Update)
-
-   After each accepted answer:
-
-   ```bash
-   # Ensure Clarifications section exists
-   IF primary_content NOT contains "## Clarifications":
-       Insert "## Clarifications" section after first heading
-
-   # Create session subsection
-   IF NOT contains "### Session YYYY-MM-DD":
-       Create "### Session {today's date}" under "## Clarifications"
-
-   # Append clarification entry
-   APPEND: "- Q: {question} → A: {answer}"
-
-   # Apply clarification to appropriate section
-   CASE category:
-       Functional Requirements → Update "## Requirements" or equivalent section
-       Architecture → Update "## Architecture" or "## Design" sections
-       User Experience → Update "## UI/UX" or "## User Experience" sections
-       Risk → Update "## Risks" or "## Risk Assessment" sections
-       Process → Update "## Process" or "## Implementation" sections
-       Data Model → Update "## Data Model" or "## Database" sections
-       Non-Functional → Update "## Non-Functional Requirements" or equivalent
-
-   # Remove obsolete/contradictory statements
-   IF clarification invalidates existing statement:
-       Replace statement instead of duplicating
-
-   # Save immediately to primary_artifact
-   Write(primary_artifact)
-   ```
-
-7. **Validation After Each Write**
-
-   - [ ] Clarifications section contains exactly one bullet per accepted answer
-   - [ ] Total asked questions ≤ 5
-   - [ ] Updated sections contain no lingering placeholders
-   - [ ] No contradictory earlier statements remain
-   - [ ] Markdown structure valid
-   - [ ] Terminology consistent across all updated sections
-
-8. **Completion Report**
-
-   After questioning loop ends or early termination:
-
-   ```markdown
-   ## ✅ Concept Verification Complete
-
-   **Session**: WFS-{session-id}
-   **Mode**: {clarify_mode}
-   **Questions Asked**: {count}/5
-   **Artifacts Updated**: {primary_artifact filename}
-   **Sections Touched**: {list section names}
-
-   ### Coverage Summary
-
-   | Category | Status | Notes |
-   |----------|--------|-------|
-   | Requirements Clarity | ✅ Resolved | Acceptance criteria quantified |
-   | Architecture & Design | ✅ Clear | No ambiguities found |
-   | Implementation Feasibility | ⚠️ Deferred | Team training plan to be defined in IMPL_PLAN |
-   | Risk & Mitigation | ✅ Resolved | Critical risks now have mitigation strategies |
-   | ... | ... | ... |
-
-   **Legend**:
-   - ✅ Resolved: Was Partial/Missing, now addressed
-   - ✅ Clear: Already sufficient
-   - ⚠️ Deferred: Low impact, better suited for planning phase
-   - ❌ Outstanding: Still Partial/Missing but question quota reached
-
-   ### Recommendations
-
-   - ✅ **PROCEED to /workflow:plan**: Conceptual foundation is clear
-   - OR ⚠️ **Address Outstanding Items First**: {list critical outstanding items}
-   - OR 🔄 **Run /workflow:concept-clarify Again**: If new information available
-
-   ### Next Steps
-   ```bash
-   /workflow:plan  # Generate IMPL_PLAN.md and task.json
-   ```
-   ```
-
-9. **Update Session Metadata**
-
-   ```bash
-   # Update metadata based on mode
-   IF clarify_mode == "brainstorm":
-       phase_key = "BRAINSTORM"
-   ELSE: # plan mode
-       phase_key = "PLAN"
-
-   # Update session metadata
-   {
-     "phases": {
-       "{phase_key}": {
-         "status": "concept_verified",
-         "concept_verification": {
-           "completed": true,
-           "completed_at": "timestamp",
-           "mode": "{clarify_mode}",
-           "questions_asked": {count},
-           "categories_clarified": [{list}],
-           "outstanding_items": [],
-           "recommendation": "PROCEED" # or "ADDRESS_OUTSTANDING"
-         }
-       }
-     }
-   }
-   ```
-
-## Behavior Rules
-
-- **If no meaningful ambiguities found**: Report "No critical ambiguities detected. Conceptual foundation is clear." and suggest proceeding to `/workflow:plan`.
-- **If synthesis-specification.md missing**: Instruct user to run `/workflow:brainstorm:synthesis` first.
-- **Never exceed 5 questions** (disambiguation retries don't count as new questions).
-- **Respect user early termination**: Signals like "stop", "done", "proceed" should stop questioning.
-- **If quota reached with high-impact items unresolved**: Explicitly flag them under "Outstanding" with recommendation to address before planning.
-- **Avoid speculative tech stack questions** unless absence blocks conceptual clarity.
-
-## Operating Principles
-
-### Context Efficiency
-- **Minimal high-signal tokens**: Focus on actionable clarifications
-- **Progressive disclosure**: Load artifacts incrementally
-- **Deterministic results**: Rerunning without changes produces consistent analysis
-
-### Verification Guidelines
-- **NEVER hallucinate missing sections**: Report them accurately
-- **Prioritize high-impact ambiguities**: Focus on what affects planning
-- **Use examples over exhaustive rules**: Cite specific instances
-- **Report zero issues gracefully**: Emit success report with coverage statistics
-- **Update incrementally**: Save after each answer to minimize context loss
-
-## Context
-
-{ARGS}

.claude/commands/workflow/execute.md

@@ -11,6 +11,17 @@ Orchestrates autonomous workflow execution through systematic task discovery, ag
 
 **Resume Mode**: When called with `--resume-session` flag, skips discovery phase and directly enters TodoWrite generation and agent execution for the specified session.
 
+## Performance Optimization Strategy
+
+**Lazy Loading**: Task JSONs read **on-demand** during execution, not upfront. TODO_LIST.md + IMPL_PLAN.md provide metadata for planning.
+
+| Metric | Before | After | Improvement |
+|--------|--------|-------|-------------|
+| **Initial Load** | All task JSONs (~2,300 lines) | TODO_LIST.md only (~650 lines) | **72% reduction** |
+| **Startup Time** | Seconds | Milliseconds | **~90% faster** |
+| **Memory** | All tasks | 1-2 tasks | **90% less** |
+| **Scalability** | 10-20 tasks | 100+ tasks | **5-10x** |
+
 ## Core Rules
 **Complete entire workflow autonomously without user interruption, using TodoWrite for comprehensive progress tracking.**
 **Execute all discovered pending tasks sequentially until workflow completion or blocking dependency.**
@@ -35,28 +46,21 @@ Orchestrates autonomous workflow execution through systematic task discovery, ag
 - **Autonomous completion**: **Execute all tasks without user interruption until workflow complete**
 
 ## Flow Control Execution
-**[FLOW_CONTROL]** marker indicates sequential step execution required for context gathering and preparation. **These steps are executed BY THE AGENT, not by the workflow:execute command.**
+**[FLOW_CONTROL]** marker indicates task JSON contains `flow_control.pre_analysis` steps for context preparation.
 
-### Flow Control Rules
+### Orchestrator Responsibility
-1. **Auto-trigger**: When `task.flow_control.pre_analysis` array exists in task JSON, agents execute these steps
+- Pass complete task JSON to agent (including `flow_control` block)
-2. **Sequential Processing**: Agents execute steps in order, accumulating context including artifacts
+- Provide session paths for artifact access
-3. **Variable Passing**: Agents use `[variable_name]` syntax to reference step outputs including artifact content
+- Monitor agent completion
-4. **Error Handling**: Agents follow step-specific error strategies (`fail`, `skip_optional`, `retry_once`)
-5. **Artifacts Priority**: When artifacts exist in task.context.artifacts, load synthesis specifications first
 
-### Execution Pattern
+### Agent Responsibility
-```
+- Parse `flow_control.pre_analysis` array from JSON
-Step 1: load_dependencies → dependency_context
+- Execute steps sequentially with variable substitution
-Step 2: analyze_patterns [dependency_context] → pattern_analysis
+- Accumulate context from artifacts and dependencies
-Step 3: implement_solution [pattern_analysis] [dependency_context] → implementation
+- Follow error handling per `step.on_error`
-```
+- Complete implementation using accumulated context
 
-### Context Accumulation Process (Executed by Agents)
+**Orchestrator does NOT execute flow control steps - Agent interprets and executes them from JSON.**
-- **Load Artifacts**: Agents retrieve synthesis specifications and brainstorming outputs from `context.artifacts`
-- **Load Dependencies**: Agents retrieve summaries from `context.depends_on` tasks
-- **Execute Analysis**: Agents run CLI tools with accumulated context including artifacts
-- **Prepare Implementation**: Agents build comprehensive context for implementation
-- **Continue Implementation**: Agents use all accumulated context including artifacts for task execution
 
 ## Execution Lifecycle
 
@@ -70,40 +74,69 @@ Step 3: implement_solution [pattern_analysis] [dependency_context] → implement
 ### Phase 1: Discovery (Normal Mode Only)
 1. **Check Active Sessions**: Find `.workflow/.active-*` markers
 2. **Select Session**: If multiple found, prompt user selection
-3. **Load Session State**: Read `workflow-session.json` and `IMPL_PLAN.md`
+3. **Load Session Metadata**: Read `workflow-session.json` ONLY (minimal context)
-4. **Scan Tasks**: Analyze `.task/*.json` files for ready tasks
+4. **DO NOT read task JSONs yet** - defer until execution phase
 
 **Note**: In resume mode, this phase is completely skipped.
 
-### Phase 2: Analysis (Normal Mode Only)
+### Phase 2: Planning Document Analysis (Normal Mode Only)
-1. **Dependency Resolution**: Build execution order based on `depends_on`
+**Optimized to avoid reading all task JSONs upfront**
-2. **Status Validation**: Filter tasks with `status: "pending"` and met dependencies
+
-3. **Agent Assignment**: Determine agent type from `meta.agent` or `meta.type`
+1. **Read IMPL_PLAN.md**: Understand overall strategy, task breakdown summary, dependencies
-4. **Context Preparation**: Load dependency summaries and inherited context
+2. **Read TODO_LIST.md**: Get current task statuses and execution progress
+3. **Extract Task Metadata**: Parse task IDs, titles, and dependency relationships from TODO_LIST.md
+4. **Build Execution Queue**: Determine ready tasks based on TODO_LIST.md status and dependencies
+
+**Key Optimization**: Use IMPL_PLAN.md and TODO_LIST.md as primary sources instead of reading all task JSONs
 
 **Note**: In resume mode, this phase is also skipped as session analysis was already completed by `/workflow:status`.
 
-### Phase 3: Planning (Resume Mode Entry Point)
+### Phase 3: TodoWrite Generation (Resume Mode Entry Point)
 **This is where resume mode directly enters after skipping Phases 1 & 2**
 
-1. **Create TodoWrite List**: Generate task list with status markers from session state
+1. **Create TodoWrite List**: Generate task list from TODO_LIST.md (not from task JSONs)
-2. **Mark Initial Status**: Set first pending task as `in_progress`
+   - Parse TODO_LIST.md to extract all tasks with current statuses
+   - Identify first pending task with met dependencies
+   - Generate comprehensive TodoWrite covering entire workflow
+2. **Mark Initial Status**: Set first ready task as `in_progress` in TodoWrite
 3. **Prepare Session Context**: Inject workflow paths for agent use (using provided session-id)
-4. **Prepare Complete Task JSON**: Include pre_analysis and flow control steps for agent consumption
+4. **Validate Prerequisites**: Ensure IMPL_PLAN.md and TODO_LIST.md exist and are valid
-5. **Validate Prerequisites**: Ensure all required context is available from existing session
 
 **Resume Mode Behavior**:
-- Load existing session state directly from `.workflow/{session-id}/`
+- Load existing TODO_LIST.md directly from `.workflow/{session-id}/`
-- Use session's task files and summaries without discovery
+- Extract current progress from TODO_LIST.md
-- Generate TodoWrite from current session progress
+- Generate TodoWrite from TODO_LIST.md state
-- Proceed immediately to agent execution
+- Proceed immediately to agent execution (Phase 4)
 
-### Phase 4: Execution
+### Phase 4: Execution (Lazy Task Loading)
-1. **Pass Task with Flow Control**: Include complete task JSON with `pre_analysis` steps for agent execution
+**Key Optimization**: Read task JSON **only when needed** for execution
-2. **Launch Agent**: Invoke specialized agent with complete context including flow control steps
+
-3. **Monitor Progress**: Track agent execution and handle errors without user interruption
+1. **Identify Next Task**: From TodoWrite, get the next `in_progress` task ID
-4. **Collect Results**: Gather implementation results and outputs
+2. **Load Task JSON on Demand**: Read `.task/{task-id}.json` for current task ONLY
-5. **Continue Workflow**: Automatically proceed to next pending task until completion
+3. **Validate Task Structure**: Ensure all 5 required fields exist (id, title, status, meta, context, flow_control)
+4. **Pass Task with Flow Control**: Include complete task JSON with `pre_analysis` steps for agent execution
+5. **Launch Agent**: Invoke specialized agent with complete context including flow control steps
+6. **Monitor Progress**: Track agent execution and handle errors without user interruption
+7. **Collect Results**: Gather implementation results and outputs
+8. **Update TODO_LIST.md**: Mark current task as completed in TODO_LIST.md
+9. **Continue Workflow**: Identify next pending task from TODO_LIST.md and repeat from step 1
+
+**Execution Loop Pattern**:
+```
+while (TODO_LIST.md has pending tasks) {
+  next_task_id = getTodoWriteInProgressTask()
+  task_json = Read(.workflow/{session}/.task/{next_task_id}.json)  // Lazy load
+  executeTaskWithAgent(task_json)
+  updateTodoListMarkCompleted(next_task_id)
+  advanceTodoWriteToNextTask()
+}
+```
+
+**Benefits**:
+- Reduces initial context loading by ~90%
+- Only reads task JSON when actually executing
+- Scales better for workflows with many tasks
+- Faster startup time for workflow execution
 
 ### Phase 5: Completion
 1. **Update Task Status**: Mark completed tasks in JSON files
@@ -115,27 +148,33 @@ Step 3: implement_solution [pattern_analysis] [dependency_context] → implement
 
 ## Task Discovery & Queue Building
 
-### Session Discovery Process (Normal Mode)
+### Session Discovery Process (Normal Mode - Optimized)
 ```
 ├── Check for .active-* markers in .workflow/
 ├── If multiple active sessions found → Prompt user to select
 ├── Locate selected session's workflow folder
-├── Load selected session's workflow-session.json and IMPL_PLAN.md
+├── Load session metadata: workflow-session.json (minimal context)
-├── Scan selected session's .task/ directory for task JSON files
+├── Read IMPL_PLAN.md (strategy overview and task summary)
-├── Analyze task statuses and dependencies for selected session only
+├── Read TODO_LIST.md (current task statuses and dependencies)
-└── Build execution queue of ready tasks from selected session
+├── Parse TODO_LIST.md to extract task metadata (NO JSON loading)
+├── Build execution queue from TODO_LIST.md
+└── Generate TodoWrite from TODO_LIST.md state
 ```
 
-### Resume Mode Process (--resume-session flag)
+**Key Change**: Task JSONs are NOT loaded during discovery - they are loaded lazily during execution
+
+### Resume Mode Process (--resume-session flag - Optimized)
 ```
 ├── Use provided session-id directly (skip discovery)
 ├── Validate .workflow/{session-id}/ directory exists
-├── Load session's workflow-session.json and IMPL_PLAN.md directly
+├── Read TODO_LIST.md for current progress
-├── Scan session's .task/ directory for task JSON files
+├── Parse TODO_LIST.md to extract task IDs and statuses
-├── Use existing task statuses and dependencies (no re-analysis needed)
+├── Generate TodoWrite from TODO_LIST.md (prioritize in-progress/pending tasks)
-└── Build execution queue from session state (prioritize pending/in-progress tasks)
+└── Enter Phase 4 (Execution) with lazy task JSON loading
 ```
 
+**Key Change**: Completely skip IMPL_PLAN.md and task JSON loading - use TODO_LIST.md only
+
 ### Task Status Logic
 ```
 pending + dependencies_met → executable
@@ -143,6 +182,122 @@ completed → skip
 blocked → skip until dependencies clear
 ```
 
+## Batch Execution with Dependency Graph
+
+### Parallel Execution Algorithm
+**Core principle**: Execute independent tasks concurrently in batches based on dependency graph.
+
+#### Algorithm Steps (Optimized with Lazy Loading)
+```javascript
+function executeBatchWorkflow(sessionId) {
+  // 1. Build dependency graph from TODO_LIST.md (NOT task JSONs)
+  const graph = buildDependencyGraphFromTodoList(`.workflow/${sessionId}/TODO_LIST.md`);
+
+  // 2. Process batches until graph is empty
+  while (!graph.isEmpty()) {
+    // 3. Identify current batch (tasks with in-degree = 0)
+    const batch = graph.getNodesWithInDegreeZero();
+
+    // 4. Load task JSONs ONLY for current batch (lazy loading)
+    const batchTaskJsons = batch.map(taskId =>
+      Read(`.workflow/${sessionId}/.task/${taskId}.json`)
+    );
+
+    // 5. Check for parallel execution opportunities
+    const parallelGroups = groupByExecutionGroup(batchTaskJsons);
+
+    // 6. Execute batch concurrently
+    await Promise.all(
+      parallelGroups.map(group => executeBatch(group))
+    );
+
+    // 7. Update graph: remove completed tasks and their edges
+    graph.removeNodes(batch);
+
+    // 8. Update TODO_LIST.md and TodoWrite to reflect completed batch
+    updateTodoListAfterBatch(batch);
+    updateTodoWriteAfterBatch(batch);
+  }
+
+  // 9. All tasks complete - auto-complete session
+  SlashCommand("/workflow:session:complete");
+}
+
+function buildDependencyGraphFromTodoList(todoListPath) {
+  const todoContent = Read(todoListPath);
+  const tasks = parseTodoListTasks(todoContent);
+  const graph = new DirectedGraph();
+
+  tasks.forEach(task => {
+    graph.addNode(task.id, { id: task.id, title: task.title, status: task.status });
+    task.dependencies?.forEach(depId => graph.addEdge(depId, task.id));
+  });
+
+  return graph;
+}
+
+function parseTodoListTasks(todoContent) {
+  // Parse: - [ ] **IMPL-001**: Task title → [📋](./.task/IMPL-001.json)
+  const taskPattern = /- \[([ x])\] \*\*([A-Z]+-\d+(?:\.\d+)?)\*\*: (.+?) →/g;
+  const tasks = [];
+  let match;
+
+  while ((match = taskPattern.exec(todoContent)) !== null) {
+    tasks.push({
+      status: match[1] === 'x' ? 'completed' : 'pending',
+      id: match[2],
+      title: match[3]
+    });
+  }
+
+  return tasks;
+}
+
+function groupByExecutionGroup(tasks) {
+  const groups = {};
+
+  tasks.forEach(task => {
+    const groupId = task.meta.execution_group || task.id;
+    if (!groups[groupId]) groups[groupId] = [];
+    groups[groupId].push(task);
+  });
+
+  return Object.values(groups);
+}
+
+async function executeBatch(tasks) {
+  // Execute all tasks in batch concurrently
+  return Promise.all(
+    tasks.map(task => executeTask(task))
+  );
+}
+```
+
+#### Execution Group Rules
+1. **Same `execution_group` ID** → Execute in parallel (independent, different contexts)
+2. **No `execution_group` (null)** → Execute sequentially (has dependencies)
+3. **Different `execution_group` IDs** → Execute in parallel (independent batches)
+4. **Same `context_signature`** → Should have been merged (warning if not)
+
+#### Parallel Execution Example
+```
+Batch 1 (no dependencies):
+  - IMPL-1.1 (execution_group: "parallel-auth-api") → Agent 1
+  - IMPL-1.2 (execution_group: "parallel-ui-comp") → Agent 2
+  - IMPL-1.3 (execution_group: "parallel-db-schema") → Agent 3
+
+Wait for Batch 1 completion...
+
+Batch 2 (depends on Batch 1):
+  - IMPL-2.1 (execution_group: null, depends_on: [IMPL-1.1, IMPL-1.2]) → Agent 1
+
+Wait for Batch 2 completion...
+
+Batch 3 (independent of Batch 2):
+  - IMPL-3.1 (execution_group: "parallel-tests-1") → Agent 1
+  - IMPL-3.2 (execution_group: "parallel-tests-2") → Agent 2
+```
+
 ## TodoWrite Coordination
 **Comprehensive workflow tracking** with immediate status updates throughout entire execution without user interruption:
 
@@ -150,8 +305,11 @@ blocked → skip until dependencies clear
 1. **Initial Creation**: Generate TodoWrite from discovered pending tasks for entire workflow
    - **Normal Mode**: Create from discovery results
    - **Resume Mode**: Create from existing session state and current progress
-2. **Single In-Progress**: Mark ONLY ONE task as `in_progress` at a time
+2. **Parallel Task Support**:
-3. **Immediate Updates**: Update status after each task completion without user interruption
+   - **Single-task execution**: Mark ONLY ONE task as `in_progress` at a time
+   - **Batch execution**: Mark ALL tasks in current batch as `in_progress` simultaneously
+   - **Execution group indicator**: Show `[execution_group: group-id]` for parallel tasks
+3. **Immediate Updates**: Update status after each task/batch completion without user interruption
 4. **Status Synchronization**: Sync with JSON task files after updates
 5. **Continuous Tracking**: Maintain TodoWrite throughout entire workflow execution until completion
 
@@ -167,36 +325,71 @@ blocked → skip until dependencies clear
 **Use Claude Code's built-in TodoWrite tool** to track workflow progress in real-time:
 
 ```javascript
-// Create initial todo list from discovered pending tasks
+// Example 1: Sequential execution (traditional)
 TodoWrite({
   todos: [
     {
       content: "Execute IMPL-1.1: Design auth schema [code-developer] [FLOW_CONTROL]",
-      status: "pending",
+      status: "in_progress",  // Single task in progress
       activeForm: "Executing IMPL-1.1: Design auth schema"
     },
     {
       content: "Execute IMPL-1.2: Implement auth logic [code-developer] [FLOW_CONTROL]",
       status: "pending",
       activeForm: "Executing IMPL-1.2: Implement auth logic"
-    },
-    {
-      content: "Execute TEST-FIX-1: Validate implementation tests [test-fix-agent]",
-      status: "pending",
-      activeForm: "Executing TEST-FIX-1: Validate implementation tests"
     }
   ]
 });
 
-// Update status as tasks progress - ONLY ONE task should be in_progress at a time
+// Example 2: Batch execution (parallel tasks with execution_group)
 TodoWrite({
   todos: [
     {
-      content: "Execute IMPL-1.1: Design auth schema [code-developer] [FLOW_CONTROL]",
+      content: "Execute IMPL-1.1: Build Auth API [code-developer] [execution_group: parallel-auth-api]",
-      status: "in_progress",  // Mark current task as in_progress
+      status: "in_progress",  // Batch task 1
-      activeForm: "Executing IMPL-1.1: Design auth schema"
+      activeForm: "Executing IMPL-1.1: Build Auth API"
     },
-    // ... other tasks remain pending
+    {
+      content: "Execute IMPL-1.2: Build User UI [code-developer] [execution_group: parallel-ui-comp]",
+      status: "in_progress",  // Batch task 2 (running concurrently)
+      activeForm: "Executing IMPL-1.2: Build User UI"
+    },
+    {
+      content: "Execute IMPL-1.3: Setup Database [code-developer] [execution_group: parallel-db-schema]",
+      status: "in_progress",  // Batch task 3 (running concurrently)
+      activeForm: "Executing IMPL-1.3: Setup Database"
+    },
+    {
+      content: "Execute IMPL-2.1: Integration Tests [test-fix-agent] [depends_on: IMPL-1.1, IMPL-1.2, IMPL-1.3]",
+      status: "pending",  // Next batch (waits for current batch completion)
+      activeForm: "Executing IMPL-2.1: Integration Tests"
+    }
+  ]
+});
+
+// Example 3: After batch completion
+TodoWrite({
+  todos: [
+    {
+      content: "Execute IMPL-1.1: Build Auth API [code-developer] [execution_group: parallel-auth-api]",
+      status: "completed",  // Batch completed
+      activeForm: "Executing IMPL-1.1: Build Auth API"
+    },
+    {
+      content: "Execute IMPL-1.2: Build User UI [code-developer] [execution_group: parallel-ui-comp]",
+      status: "completed",  // Batch completed
+      activeForm: "Executing IMPL-1.2: Build User UI"
+    },
+    {
+      content: "Execute IMPL-1.3: Setup Database [code-developer] [execution_group: parallel-db-schema]",
+      status: "completed",  // Batch completed
+      activeForm: "Executing IMPL-1.3: Setup Database"
+    },
+    {
+      content: "Execute IMPL-2.1: Integration Tests [test-fix-agent]",
+      status: "in_progress",  // Next batch started
+      activeForm: "Executing IMPL-2.1: Integration Tests"
+    }
   ]
 });
 ```
@@ -211,18 +404,19 @@ TodoWrite({
 - **Workflow Completion Check**: When all tasks marked `completed`, auto-call `/workflow:session:complete`
 
 #### TODO_LIST.md Update Timing
-- **Before Agent Launch**: Update TODO_LIST.md to mark task as `in_progress` (⚠️)
+**Single source of truth for task status** - enables lazy loading by providing task metadata without reading JSONs
-- **After Task Complete**: Update TODO_LIST.md to mark as `completed` (✅), advance to next
+
-- **On Error**: Keep as `in_progress` in TODO_LIST.md, add error note
+- **Before Agent Launch**: Mark task as `in_progress`
-- **Workflow Complete**: When all tasks completed, call `/workflow:session:complete`
+- **After Task Complete**: Mark as `completed`, advance to next
-- **Session End**: Sync all TODO_LIST.md statuses with JSON task files
+- **On Error**: Keep as `in_progress`, add error note
+- **Workflow Complete**: Call `/workflow:session:complete`
 
 ### 3. Agent Context Management
 **Comprehensive context preparation** for autonomous agent execution:
 
 #### Context Sources (Priority Order)
 1. **Complete Task JSON**: Full task definition including all fields and artifacts
-2. **Artifacts Context**: Brainstorming outputs and synthesis specifications from task.context.artifacts
+2. **Artifacts Context**: Brainstorming outputs and role analysess from task.context.artifacts
 3. **Flow Control Context**: Accumulated outputs from pre_analysis steps (including artifact loading)
 4. **Dependency Summaries**: Previous task completion summaries
 5. **Session Context**: Workflow paths and session metadata
@@ -243,10 +437,10 @@ TodoWrite({
 {
   "task": { /* Complete task JSON with artifacts array */ },
   "artifacts": {
-    "synthesis_specification": { "path": ".workflow/WFS-session/.brainstorming/synthesis-specification.md", "priority": "highest" },
+    "synthesis_specification": { "path": "{{from context-package.json → brainstorm_artifacts.synthesis_output.path}}", "priority": "highest" },
-    "topic_framework": { "path": ".workflow/WFS-session/.brainstorming/topic-framework.md", "priority": "medium" },
+    "guidance_specification": { "path": "{{from context-package.json → brainstorm_artifacts.guidance_specification.path}}", "priority": "medium" },
-    "role_analyses": [ /* Individual role analysis files */ ],
+    "role_analyses": [ /* From context-package.json → brainstorm_artifacts.role_analyses[] */ ],
-    "available_artifacts": [ /* All detected brainstorming artifacts */ ]
+    "conflict_resolution": { "path": "{{from context-package.json → brainstorm_artifacts.conflict_resolution.path}}", "conditional": true }
   },
   "flow_context": {
     "step_outputs": {
@@ -258,7 +452,7 @@ TodoWrite({
   },
   "session": {
     "workflow_dir": ".workflow/WFS-session/",
-    "brainstorming_dir": ".workflow/WFS-session/.brainstorming/",
+    "context_package_path": ".workflow/WFS-session/.process/context-package.json",
     "todo_list_path": ".workflow/WFS-session/TODO_LIST.md",
     "summaries_dir": ".workflow/WFS-session/.summaries/",
     "task_json_path": ".workflow/WFS-session/.task/IMPL-1.1.json"
@@ -270,10 +464,10 @@ TodoWrite({
 
 #### Context Validation Rules
 - **Task JSON Complete**: All 5 fields present and valid, including artifacts array in context
-- **Artifacts Available**: Synthesis specifications and brainstorming outputs accessible
+- **Artifacts Available**: All artifacts loaded from context-package.json
 - **Flow Control Ready**: All pre_analysis steps completed including artifact loading steps
 - **Dependencies Loaded**: All depends_on summaries available
-- **Session Paths Valid**: All workflow paths exist and accessible, including .brainstorming directory
+- **Session Paths Valid**: All workflow paths exist and accessible (verified via context-package.json)
 - **Agent Assignment**: Valid agent type specified in meta.agent
 
 ### 4. Agent Execution Pattern
@@ -282,82 +476,40 @@ TodoWrite({
 #### Agent Prompt Template
 ```bash
 Task(subagent_type="{meta.agent}",
-     prompt="**TASK EXECUTION WITH FULL JSON LOADING**
+     prompt="**EXECUTE TASK FROM JSON**
 
-     ## STEP 1: Load Complete Task JSON
+     ## Task JSON Location
-     **MANDATORY**: First load the complete task JSON from: {session.task_json_path}
+     {session.task_json_path}
 
-     cat {session.task_json_path}
+     ## Instructions
+     1. **Load Complete Task JSON**: Read and validate all fields (id, title, status, meta, context, flow_control)
+     2. **Execute Flow Control**: If `flow_control.pre_analysis` exists, execute steps sequentially:
+        - Load artifacts (role analysis documents, role analyses) using commands in each step
+        - Accumulate context from step outputs using variable substitution [variable_name]
+        - Handle errors per step.on_error (skip_optional | fail | retry_once)
+     3. **Implement Solution**: Follow `flow_control.implementation_approach` using accumulated context
+     4. **Complete Task**:
+        - Update task status: `jq '.status = \"completed\"' {session.task_json_path} > temp.json && mv temp.json {session.task_json_path}`
+        - Update TODO_LIST.md: Mark task as [x] completed in {session.todo_list_path}
+        - Generate summary: {session.summaries_dir}/{task.id}-summary.md
+        - Check workflow completion and call `/workflow:session:complete` if all tasks done
 
-     **CRITICAL**: Validate all 5 required fields are present:
+     ## Context Sources (All from JSON)
-     - id, title, status, meta, context, flow_control
+     - Requirements: `context.requirements`
+     - Focus Paths: `context.focus_paths`
+     - Acceptance: `context.acceptance`
+     - Artifacts: `context.artifacts` (synthesis specs, brainstorming outputs)
+     - Dependencies: `context.depends_on`
+     - Target Files: `flow_control.target_files`
 
-     ## STEP 2: Task Definition (From Loaded JSON)
+     ## Session Paths
-     **ID**: Use id field from JSON
+     - Workflow Dir: {session.workflow_dir}
-     **Title**: Use title field from JSON
+     - TODO List: {session.todo_list_path}
-     **Type**: Use meta.type field from JSON
+     - Summaries: {session.summaries_dir}
-     **Agent**: Use meta.agent field from JSON
+     - Flow Context: {flow_context.step_outputs}
-     **Status**: Verify status is pending or active
 
-     ## STEP 3: Flow Control Execution (if flow_control.pre_analysis exists)
+     **Complete JSON structure is authoritative - load and follow it exactly.**"),
-     **AGENT RESPONSIBILITY**: Execute pre_analysis steps sequentially from loaded JSON:
+     description="Execute task: {task.id}")
-
-     **PRIORITY: Artifact Loading Steps First**
-     1. **Load Synthesis Specification** (if present): Priority artifact loading for consolidated design
-     2. **Load Individual Artifacts** (fallback): Load role-specific brainstorming outputs if synthesis unavailable
-     3. **Execute Remaining Steps**: Continue with other pre_analysis steps
-
-     For each step in flow_control.pre_analysis array:
-     1. Execute step.command/commands with variable substitution (support both single command and commands array)
-     2. Store output to step.output_to variable
-     3. Handle errors per step.on_error strategy (skip_optional, fail, retry_once)
-     4. Pass accumulated variables to next step including artifact context
-
-     **Special Artifact Loading Commands**:
-     - Use `bash(ls path 2>/dev/null || echo 'file not found')` for artifact existence checks
-     - Use `Read(path)` for loading artifact content
-     - Use `find` commands for discovering multiple artifact files
-     - Reference artifacts in subsequent steps using output variables: [synthesis_specification], [individual_artifacts]
-
-     ## STEP 4: Implementation Context (From JSON context field)
-     **Requirements**: Use context.requirements array from JSON
-     **Focus Paths**: Use context.focus_paths array from JSON
-     **Acceptance Criteria**: Use context.acceptance array from JSON
-     **Dependencies**: Use context.depends_on array from JSON
-     **Parent Context**: Use context.inherited object from JSON
-     **Artifacts**: Use context.artifacts array from JSON (synthesis specifications, brainstorming outputs)
-     **Target Files**: Use flow_control.target_files array from JSON
-     **Implementation Approach**: Use flow_control.implementation_approach object from JSON (with artifact integration)
-
-     ## STEP 5: Session Context (Provided by workflow:execute)
-     **Workflow Directory**: {session.workflow_dir}
-     **TODO List Path**: {session.todo_list_path}
-     **Summaries Directory**: {session.summaries_dir}
-     **Task JSON Path**: {session.task_json_path}
-     **Flow Context**: {flow_context.step_outputs}
-
-     ## STEP 6: Agent Completion Requirements
-     1. **Load Task JSON**: Read and validate complete task structure
-     2. **Execute Flow Control**: Run all pre_analysis steps if present
-     3. **Implement Solution**: Follow implementation_approach from JSON
-     4. **Update Progress**: Mark task status in JSON as completed
-     5. **Update TODO List**: Update TODO_LIST.md at provided path
-     6. **Generate Summary**: Create completion summary in summaries directory
-     7. **Check Workflow Complete**: After task completion, check if all workflow tasks done
-     8. **Auto-Complete Session**: If all tasks completed, call SlashCommand(\"/workflow:session:complete\")
-
-     **JSON UPDATE COMMAND**:
-     Update task status to completed using jq:
-     jq '.status = \"completed\"' {session.task_json_path} > temp.json && mv temp.json {session.task_json_path}
-
-     **WORKFLOW COMPLETION CHECK**:
-     After updating task status, check if workflow is complete:
-     total_tasks=\$(find .workflow/*/\.task/ -name "*.json" -type f 2>/dev/null | wc -l)
-     completed_tasks=\$(find .workflow/*/\.summaries/ -name "*.md" -type f 2>/dev/null | wc -l)
-     if [ \$total_tasks -eq \$completed_tasks ]; then
-       SlashCommand(command=\"/workflow:session:complete\")
-     fi"),
-     description="Execute task with full JSON loading and validation")
 ```
 
 #### Agent JSON Loading Specification
@@ -381,7 +533,7 @@ Task(subagent_type="{meta.agent}",
   "status": "pending|active|completed|blocked",
   "meta": {
     "type": "feature|bugfix|refactor|test-gen|test-fix|docs",
-    "agent": "@code-developer|@test-fix-agent|@general-purpose"
+    "agent": "@code-developer|@test-fix-agent|@universal-executor"
   },
   "context": {
     "requirements": ["req1", "req2"],
@@ -392,15 +544,16 @@ Task(subagent_type="{meta.agent}",
     "artifacts": [
       {
         "type": "synthesis_specification",
-        "source": "brainstorm_synthesis",
+        "source": "context-package.json → brainstorm_artifacts.synthesis_output",
-        "path": ".workflow/WFS-[session]/.brainstorming/synthesis-specification.md",
+        "path": "{{loaded dynamically from context-package.json}}",
         "priority": "highest",
         "contains": "complete_integrated_specification"
       },
       {
         "type": "individual_role_analysis",
-        "source": "brainstorm_roles",
+        "source": "context-package.json → brainstorm_artifacts.role_analyses[]",
-        "path": ".workflow/WFS-[session]/.brainstorming/[role]/analysis.md",
+        "path": "{{loaded dynamically from context-package.json}}",
+        "note": "Supports analysis*.md pattern (analysis.md, analysis-01.md, analysis-api.md, etc.)",
         "priority": "low",
         "contains": "role_specific_analysis_fallback"
       }
@@ -410,10 +563,11 @@ Task(subagent_type="{meta.agent}",
     "pre_analysis": [
       {
         "step": "load_synthesis_specification",
-        "action": "Load consolidated synthesis specification from brainstorming",
+        "action": "Load synthesis specification from context-package.json",
         "commands": [
-          "bash(ls .workflow/WFS-[session]/.brainstorming/synthesis-specification.md 2>/dev/null || echo 'synthesis specification not found')",
+          "Read(.workflow/WFS-[session]/.process/context-package.json)",
-          "Read(.workflow/WFS-[session]/.brainstorming/synthesis-specification.md)"
+          "Extract(brainstorm_artifacts.synthesis_output.path)",
+          "Read(extracted path)"
         ],
         "output_to": "synthesis_specification",
         "on_error": "skip_optional"
@@ -428,16 +582,16 @@ Task(subagent_type="{meta.agent}",
     "implementation_approach": [
       {
         "step": 1,
-        "title": "Implement task following synthesis specification",
+        "title": "Implement task following role analyses",
-        "description": "Implement '[title]' following synthesis specification. PRIORITY: Use synthesis-specification.md as primary requirement source. When implementation needs technical details (e.g., API schemas, caching configs, design tokens), refer to artifacts[] for detailed specifications from original role analyses.",
+        "description": "Implement '[title]' following role analyses. PRIORITY: Use role analysis documents as primary requirement source. When implementation needs technical details (e.g., API schemas, caching configs, design tokens), refer to artifacts[] for detailed specifications from original role analyses.",
         "modification_points": [
-          "Apply consolidated requirements from synthesis-specification.md",
+          "Apply consolidated requirements from role analysis documents",
           "Follow technical guidelines from synthesis",
           "Consult artifacts for implementation details when needed",
           "Integrate with existing patterns"
         ],
         "logic_flow": [
-          "Load synthesis specification",
+          "Load role analyses",
           "Parse architecture and requirements",
           "Implement following specification",
           "Consult artifacts for technical details when needed",
@@ -467,7 +621,7 @@ meta.agent missing → Infer from meta.type:
   - "feature" → @code-developer
   - "test-gen" → @code-developer
   - "test-fix" → @test-fix-agent
-  - "review" → @general-purpose
+  - "review" → @universal-executor
   - "docs" → @doc-generator
 ```
 

.claude/commands/workflow/plan.md

@@ -13,20 +13,19 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 
 **Execution Model - Auto-Continue Workflow with Quality Gate**:
 
-This workflow runs **mostly autonomously** once triggered, with one interactive quality gate (Phase 3.5). Phases 3 and 4 are delegated to specialized agents for complex analysis and task generation.
+This workflow runs **fully autonomously** once triggered. Phase 3 (conflict resolution) and Phase 4 (task generation) are delegated to specialized agents.
+
 
 1. **User triggers**: `/workflow:plan "task"`
 2. **Phase 1 executes** → Session discovery → Auto-continues
 3. **Phase 2 executes** → Context gathering → Auto-continues
-4. **Phase 3 executes** (cli-execution-agent) → Intelligent analysis → Auto-continues
+4. **Phase 3 executes** (optional, if conflict_risk ≥ medium) → Conflict resolution → Auto-continues
-5. **Phase 3.5 executes** → **Pauses for user Q&A** → User answers clarification questions → Auto-continues
+5. **Phase 4 executes** (task-generate-agent if --agent) → Task generation → Reports final summary
-6. **Phase 4 executes** (task-generate-agent if --agent) → Task generation → Reports final summary
 
 **Auto-Continue Mechanism**:
 - TodoList tracks current phase status
 - After each phase completion, automatically executes next pending phase
-- **Phase 3.5 requires user interaction** - answers clarification questions (up to 5)
+- All phases run autonomously without user interaction (clarification handled in brainstorm phase)
-- If no ambiguities found, Phase 3.5 auto-skips and continues to Phase 4
 - Progress updates shown at each phase for visibility
 
 **Execution Modes**:
@@ -84,7 +83,7 @@ CONTEXT: Existing user database schema, REST API endpoints
 
 **Parse Output**:
 - Extract: context-package.json path (store as `contextPath`)
-- Typical pattern: `.workflow/[sessionId]/.context/context-package.json`
+- Typical pattern: `.workflow/[sessionId]/.process/context-package.json`
 
 **Validation**:
 - Context package path extracted
@@ -96,49 +95,31 @@ CONTEXT: Existing user database schema, REST API endpoints
 
 ---
 
-### Phase 3: Intelligent Analysis (Agent-Delegated)
+### Phase 3: Conflict Resolution (Optional - auto-triggered by conflict risk)
 
-**Command**: `Task(subagent_type="cli-execution-agent", description="Intelligent Analysis", prompt="...")`
+**Trigger**: Only execute when context-package.json indicates conflict_risk is "medium" or "high"
 
-**Agent Task Prompt**:
+**Command**: `SlashCommand(command="/workflow:tools:conflict-resolution --session [sessionId] --context [contextPath]")`
-```
-Analyze project requirements and generate comprehensive solution blueprint for session [sessionId].
 
-Context: Load context package from [contextPath]
+**Input**:
-Output: Generate ANALYSIS_RESULTS.md in .workflow/[sessionId]/.process/
+- sessionId from Phase 1
-
+- contextPath from Phase 2
-Requirements:
+- conflict_risk from context-package.json
-- Review context-package.json and discover additional relevant files
-- Analyze architecture patterns, data models, and dependencies
-- Identify technical constraints and risks
-- Generate comprehensive solution blueprint
-- Include task breakdown recommendations
-
-Session: [sessionId]
-Mode: analysis (read-only during discovery, write for ANALYSIS_RESULTS.md)
-```
-
-**Input**: `sessionId` from Phase 1, `contextPath` from Phase 2
-
-**Agent Execution**:
-- Phase 1: Understands analysis intent, extracts keywords
-- Phase 2: Discovers additional context via MCP code-index
-- Phase 3: Enhances prompt with discovered patterns
-- Phase 4: Executes with Gemini (analysis mode), generates ANALYSIS_RESULTS.md
-- Phase 5: Routes output to session directory
 
 **Parse Output**:
-- Agent returns execution log path
+- Extract: Execution status (success/skipped/failed)
-- Verify ANALYSIS_RESULTS.md created by agent
+- Verify: CONFLICT_RESOLUTION.md file path (if executed)
 
 **Validation**:
-- File `.workflow/[sessionId]/.process/ANALYSIS_RESULTS.md` exists
+- File `.workflow/[sessionId]/.process/CONFLICT_RESOLUTION.md` exists (if executed)
-- Contains task recommendations section
-- Agent execution log saved to `.workflow/[sessionId]/.chat/`
 
-**TodoWrite**: Mark phase 3 completed, phase 3.5 in_progress
+**Skip Behavior**:
+- If conflict_risk is "none" or "low", skip directly to Phase 3.5
+- Display: "No significant conflicts detected, proceeding to clarification"
 
-**After Phase 3**: Return to user showing Phase 3 results, then auto-continue to Phase 3.5
+**TodoWrite**: Mark phase 3 completed (if executed) or skipped, phase 3.5 in_progress
+
+**After Phase 3**: Return to user showing conflict resolution results (if executed) and selected strategies, then auto-continue to Phase 3.5
 
 **Memory State Check**:
 - Evaluate current context window usage and memory state
@@ -150,45 +131,33 @@ Mode: analysis (read-only during discovery, write for ANALYSIS_RESULTS.md)
 
 ---
 
-### Phase 3.5: Concept Clarification (Quality Gate)
+### Phase 3.5: Pre-Task Generation Validation (Optional Quality Gate)
 
-**Command**: `SlashCommand(command="/workflow:concept-clarify --session [sessionId]")`
+**Purpose**: Optional quality gate before task generation - primarily handled by brainstorm synthesis phase
 
-**Purpose**: Quality gate to verify and clarify analysis results before task generation
 
-**Input**: `sessionId` from Phase 1
+**Current Behavior**: Auto-skip to Phase 4 (Task Generation)
 
-**Behavior**:
+**Future Enhancement**: Could add additional validation steps like:
-- Auto-detects plan mode (ANALYSIS_RESULTS.md exists)
+- Cross-reference checks between conflict resolution and brainstorm analyses
-- Interactively asks up to 5 targeted questions to resolve ambiguities
+- Final sanity checks before task generation
-- Updates ANALYSIS_RESULTS.md with clarifications
+- User confirmation prompt for proceeding
-- Pauses workflow for user input (breaks auto-continue temporarily)
 
-**Parse Output**:
+**TodoWrite**: Mark phase 3.5 completed (auto-skip), phase 4 in_progress
-- Verify clarifications added to ANALYSIS_RESULTS.md
-- Check recommendation: "PROCEED" or "ADDRESS_OUTSTANDING"
 
-**Validation**:
+**After Phase 3.5**: Auto-continue to Phase 4 immediately
-- ANALYSIS_RESULTS.md updated with `## Clarifications` section
-- All critical ambiguities resolved or documented as outstanding
-
-**TodoWrite**: Mark phase 3.5 completed, phase 4 in_progress
-
-**After Phase 3.5**: Return to user showing clarification summary, then auto-continue to Phase 4
-
-**Skip Conditions**:
-- If `/workflow:concept-clarify` reports "No critical ambiguities detected", automatically proceed to Phase 4
-- User can skip by responding "skip" or "proceed" immediately
 
 ---
 
 ### Phase 4: Task Generation
 
 **Relationship with Brainstorm Phase**:
-- If brainstorm synthesis exists (synthesis-specification.md), Phase 3 analysis incorporates it as input
+- If brainstorm role analyses exist ([role]/analysis.md files), Phase 3 analysis incorporates them as input
-- **synthesis-specification.md defines "WHAT"**: Requirements, design specs, high-level features
+- **User's original intent is ALWAYS primary**: New or refined user goals override brainstorm recommendations
+- **Role analysis.md files define "WHAT"**: Requirements, design specs, role-specific insights
 - **IMPL_PLAN.md defines "HOW"**: Executable task breakdown, dependencies, implementation sequence
-- Task generation translates high-level specifications into concrete, actionable work items
+- Task generation translates high-level role analyses into concrete, actionable work items
+- **Intent priority**: Current user prompt > role analysis.md files > guidance-specification.md
 
 **Command Selection**:
 - Manual: `SlashCommand(command="/workflow:tools:task-generate --session [sessionId]")`
@@ -223,36 +192,48 @@ Planning complete for session: [sessionId]
 Tasks generated: [count]
 Plan: .workflow/[sessionId]/IMPL_PLAN.md
 
-✅ Recommended Next Steps:
+Recommended Next Steps:
 1. /workflow:action-plan-verify --session [sessionId]  # Verify plan quality before execution
 2. /workflow:status  # Review task breakdown
 3. /workflow:execute  # Start implementation (after verification)
 
-⚠️ Quality Gate: Consider running /workflow:action-plan-verify to catch issues early
+Quality Gate: Consider running /workflow:action-plan-verify to catch issues early
 ```
 
 ## TodoWrite Pattern
 
 ```javascript
 // Initialize (before Phase 1)
+// Note: Phase 3 todo only added dynamically after Phase 2 if conflict_risk ≥ medium
 TodoWrite({todos: [
   {"content": "Execute session discovery", "status": "in_progress", "activeForm": "Executing session discovery"},
   {"content": "Execute context gathering", "status": "pending", "activeForm": "Executing context gathering"},
-  {"content": "Execute intelligent analysis", "status": "pending", "activeForm": "Executing intelligent analysis"},
+  // Phase 3 todo added dynamically after Phase 2 if conflict_risk ≥ medium
-  {"content": "Execute concept clarification", "status": "pending", "activeForm": "Executing concept clarification"},
   {"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"}
 ]})
 
-// After Phase 1
+// After Phase 2 (if conflict_risk ≥ medium, insert Phase 3 todo)
 TodoWrite({todos: [
   {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
-  {"content": "Execute context gathering", "status": "in_progress", "activeForm": "Executing context gathering"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
-  {"content": "Execute intelligent analysis", "status": "pending", "activeForm": "Executing intelligent analysis"},
+  {"content": "Resolve conflicts and apply fixes", "status": "in_progress", "activeForm": "Resolving conflicts"},
-  {"content": "Execute concept clarification", "status": "pending", "activeForm": "Executing concept clarification"},
   {"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"}
 ]})
 
-// Continue pattern for Phase 2, 3, 3.5, 4...
+// After Phase 2 (if conflict_risk is none/low, skip Phase 3, go directly to Phase 4)
+TodoWrite({todos: [
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Execute task generation", "status": "in_progress", "activeForm": "Executing task generation"}
+]})
+
+// After Phase 3 (if executed), continue to Phase 4
+TodoWrite({todos: [
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Resolve conflicts and apply fixes", "status": "completed", "activeForm": "Resolving conflicts"},
+  {"content": "Execute task generation", "status": "in_progress", "activeForm": "Executing task generation"}
+]})
 ```
 
 ## Input Processing
@@ -301,20 +282,22 @@ Phase 1: session:start --auto "structured-description"
     ↓
 Phase 2: context-gather --session sessionId "structured-description"
     ↓ Input: sessionId + session memory + structured description
-    ↓ Output: contextPath (context-package.json)
+    ↓ Output: contextPath (context-package.json) + conflict_risk
     ↓
-Phase 3: cli-execution-agent (Intelligent Analysis)
+Phase 3: conflict-resolution [AUTO-TRIGGERED if conflict_risk ≥ medium]
-    ↓ Input: sessionId + contextPath + task description
+    ↓ Input: sessionId + contextPath + conflict_risk
-    ↓ Agent discovers context, enhances prompt, executes with Gemini
+    ↓ CLI-powered conflict detection (JSON output)
-    ↓ Output: ANALYSIS_RESULTS.md + execution log
+    ↓ AskUserQuestion: Present conflicts + resolution strategies
-    ↓
+    ↓ User selects strategies (or skip)
-Phase 3.5: concept-clarify --session sessionId (Quality Gate)
+    ↓ Apply modifications via Edit tool:
-    ↓ Input: sessionId + ANALYSIS_RESULTS.md (auto-detected)
+    ↓   - Update guidance-specification.md
-    ↓ Interactive: User answers clarification questions
+    ↓   - Update role analyses (*.md)
-    ↓ Output: Updated ANALYSIS_RESULTS.md with clarifications
+    ↓   - Mark context-package.json as "resolved"
+    ↓ Output: Modified brainstorm artifacts (NO report file)
+    ↓ Skip if conflict_risk is none/low → proceed directly to Phase 4
     ↓
 Phase 4: task-generate[--agent] --session sessionId
-    ↓ Input: sessionId + clarified ANALYSIS_RESULTS.md + session memory
+    ↓ Input: sessionId + resolved brainstorm artifacts + session memory
     ↓ Output: IMPL_PLAN.md, task JSONs, TODO_LIST.md
     ↓
 Return summary to user
@@ -323,7 +306,7 @@ Return summary to user
 **Session Memory Flow**: Each phase receives session ID, which provides access to:
 - Previous task summaries
 - Existing context and analysis
-- Brainstorming artifacts
+- Brainstorming artifacts (potentially modified by Phase 3)
 - Session-specific configuration
 
 **Structured Description Benefits**:
@@ -340,27 +323,24 @@ Return summary to user
 
 ## Coordinator Checklist
 
-✅ **Pre-Phase**: Convert user input to structured format (GOAL/SCOPE/CONTEXT)
+- **Pre-Phase**: Convert user input to structured format (GOAL/SCOPE/CONTEXT)
-✅ Initialize TodoWrite before any command (include Phase 3.5)
+- Initialize TodoWrite before any command (Phase 3 added dynamically after Phase 2)
-✅ Execute Phase 1 immediately with structured description
+- Execute Phase 1 immediately with structured description
-✅ Parse session ID from Phase 1 output, store in memory
+- Parse session ID from Phase 1 output, store in memory
-✅ Pass session ID and structured description to Phase 2 command
+- Pass session ID and structured description to Phase 2 command
-✅ Parse context path from Phase 2 output, store in memory
+- Parse context path from Phase 2 output, store in memory
-✅ **Launch Phase 3 agent**: Build Task prompt with sessionId and contextPath
+- **Extract conflict_risk from context-package.json**: Determine Phase 3 execution
-✅ Wait for agent completion, parse execution log path
+- **If conflict_risk ≥ medium**: Launch Phase 3 conflict-resolution with sessionId and contextPath
-✅ Verify ANALYSIS_RESULTS.md created by agent
+- Wait for Phase 3 completion (if executed), verify CONFLICT_RESOLUTION.md created
-✅ **Execute Phase 3.5**: Pass session ID to `/workflow:concept-clarify`
+- **If conflict_risk is none/low**: Skip Phase 3, proceed directly to Phase 4
-✅ Wait for user interaction (clarification Q&A)
+- **Build Phase 4 command** based on flags:
-✅ Verify ANALYSIS_RESULTS.md updated with clarifications
-✅ Check recommendation: proceed if "PROCEED", otherwise alert user
-✅ **Build Phase 4 command** based on flags:
   - Base command: `/workflow:tools:task-generate` (or `-agent` if `--agent` flag)
   - Add `--session [sessionId]`
   - Add `--cli-execute` if flag present
-✅ Pass session ID to Phase 4 command
+- Pass session ID to Phase 4 command
-✅ Verify all Phase 4 outputs
+- Verify all Phase 4 outputs
-✅ Update TodoWrite after each phase
+- Update TodoWrite after each phase (dynamically adjust for Phase 3 presence)
-✅ After each phase, automatically continue to next phase based on TodoList status
+- After each phase, automatically continue to next phase based on TodoList status
 
 ## Structure Template Reference
 
@@ -388,3 +368,22 @@ CONSTRAINTS: [Limitations or boundaries]
 # Phase 2
 /workflow:tools:context-gather --session WFS-123 "GOAL: Build authentication\nSCOPE: JWT, login, registration\nCONTEXT: REST API"
 ```
+
+## Related Commands
+
+**Prerequisite Commands**:
+- `/workflow:brainstorm:artifacts` - Optional: Generate role-based analyses before planning (if complex requirements need multiple perspectives)
+- `/workflow:brainstorm:synthesis` - Optional: Refine brainstorm analyses with clarifications
+
+**Called by This Command** (5 phases):
+- `/workflow:session:start` - Phase 1: Create or discover workflow session
+- `/workflow:tools:context-gather` - Phase 2: Gather project context and analyze codebase
+- `/workflow:tools:conflict-resolution` - Phase 3: Detect and resolve conflicts (auto-triggered if conflict_risk ≥ medium)
+- `/compact` - Phase 3: Memory optimization (if context approaching limits)
+- `/workflow:tools:task-generate` - Phase 4: Generate task JSON files with manual approach
+- `/workflow:tools:task-generate-agent` - Phase 4: Generate task JSON files with agent-driven approach (when `--agent` flag used)
+
+**Follow-up Commands**:
+- `/workflow:action-plan-verify` - Recommended: Verify plan quality and catch issues before execution
+- `/workflow:status` - Review task breakdown and current progress
+- `/workflow:execute` - Begin implementation of generated tasks

.claude/commands/workflow/resume.md

@@ -89,5 +89,17 @@ The special `--resume-session` flag tells `/workflow:execute`:
 3. **Agent coordination**: TodoWrite and agent execution initiated successfully
 4. **Context preservation**: Session state and progress properly maintained
 
+## Related Commands
+
+**Prerequisite Commands**:
+- `/workflow:plan` or `/workflow:execute` - Workflow must be in progress or paused
+
+**Called by This Command** (2 phases):
+- `/workflow:status` - Phase 1: Analyze current session status and identify resume point
+- `/workflow:execute` - Phase 2: Resume execution with `--resume-session` flag
+
+**Follow-up Commands**:
+- None - Workflow continues automatically via `/workflow:execute`
+
 ---
 *Sequential command coordination for workflow session resumption*

.claude/commands/workflow/review.md

@@ -4,17 +4,17 @@ description: Optional specialized review (security, architecture, docs) for comp
 argument-hint: "[--type=security|architecture|action-items|quality] [optional: session-id]"
 ---
 
-### 🚀 Command Overview: `/workflow:review`
+## Command Overview: /workflow:review
 
 **Optional specialized review** for completed implementations. In the standard workflow, **passing tests = approved code**. Use this command only when specialized review is required (security, architecture, compliance, docs).
 
 ## Philosophy: "Tests Are the Review"
 
-- ✅ **Default**: All tests pass → Code approved
+- **Default**: All tests pass -> Code approved
-- 🔍 **Optional**: Specialized reviews for:
+- **Optional**: Specialized reviews for:
-  - 🔒 Security audits (vulnerabilities, auth/authz)
+  - Security audits (vulnerabilities, auth/authz)
-  - 🏗️ Architecture compliance (patterns, technical debt)
+  - Architecture compliance (patterns, technical debt)
-  - 📋 Action items verification (requirements met, acceptance criteria)
+  - Action items verification (requirements met, acceptance criteria)
 
 ## Review Types
 
@@ -44,13 +44,13 @@ fi
 
 # Step 2: Validation
 if [ ! -d ".workflow/${sessionId}" ]; then
-    echo "❌ Session ${sessionId} not found"
+    echo "Session ${sessionId} not found"
     exit 1
 fi
 
 # Check for completed tasks
 if [ ! -d ".workflow/${sessionId}/.summaries" ] || [ -z "$(find .workflow/${sessionId}/.summaries/ -name "IMPL-*.md" -type f 2>/dev/null)" ]; then
-    echo "❌ No completed implementation found. Complete implementation first"
+    echo "No completed implementation found. Complete implementation first"
     exit 1
 fi
 
@@ -59,7 +59,7 @@ review_type="${TYPE_ARG:-quality}"
 
 # Redirect docs review to specialized command
 if [ "$review_type" = "docs" ]; then
-    echo "💡 For documentation generation, please use:"
+    echo "For documentation generation, please use:"
     echo "   /workflow:tools:docs"
     echo ""
     echo "The docs command provides:"
@@ -73,7 +73,7 @@ fi
 # BASH_EXECUTION_STOPS → MODEL_ANALYSIS_BEGINS
 ```
 
-### 🧠 Model Analysis Phase
+### Model Analysis Phase
 
 After bash validation, the model takes control to:
 
@@ -92,17 +92,17 @@ After bash validation, the model takes control to:
 2. **Perform Specialized Review**: Based on `review_type`
 
    **Security Review** (`--type=security`):
-   - Use MCP code search for security patterns:
+   - Use ripgrep for security patterns:
      ```bash
-     mcp__code-index__search_code_advanced(pattern="password|token|secret|auth", file_pattern="*.{ts,js,py}")
+     rg "password|token|secret|auth" -g "*.{ts,js,py}"
-     mcp__code-index__search_code_advanced(pattern="eval|exec|innerHTML|dangerouslySetInnerHTML", file_pattern="*.{ts,js,tsx}")
+     rg "eval|exec|innerHTML|dangerouslySetInnerHTML" -g "*.{ts,js,tsx}"
      ```
    - Use Gemini for security analysis:
      ```bash
-     cd .workflow/${sessionId} && ~/.claude/scripts/gemini-wrapper -p "
+     cd .workflow/${sessionId} && gemini -p "
      PURPOSE: Security audit of completed implementation
      TASK: Review code for security vulnerabilities, insecure patterns, auth/authz issues
-     CONTEXT: @{.summaries/IMPL-*.md,../..,../../CLAUDE.md}
+     CONTEXT: @.summaries/IMPL-*.md,../.. @../../CLAUDE.md
      EXPECTED: Security findings report with severity levels
      RULES: Focus on OWASP Top 10, authentication, authorization, data validation, injection risks
      " --approval-mode yolo
@@ -111,10 +111,10 @@ After bash validation, the model takes control to:
    **Architecture Review** (`--type=architecture`):
    - Use Qwen for architecture analysis:
      ```bash
-     cd .workflow/${sessionId} && ~/.claude/scripts/qwen-wrapper -p "
+     cd .workflow/${sessionId} && qwen -p "
      PURPOSE: Architecture compliance review
      TASK: Evaluate adherence to architectural patterns, identify technical debt, review design decisions
-     CONTEXT: @{.summaries/IMPL-*.md,../..,../../CLAUDE.md}
+     CONTEXT: @.summaries/IMPL-*.md,../.. @../../CLAUDE.md
      EXPECTED: Architecture assessment with recommendations
      RULES: Check for patterns, separation of concerns, modularity, scalability
      " --approval-mode yolo
@@ -123,10 +123,10 @@ After bash validation, the model takes control to:
    **Quality Review** (`--type=quality`):
    - Use Gemini for code quality:
      ```bash
-     cd .workflow/${sessionId} && ~/.claude/scripts/gemini-wrapper -p "
+     cd .workflow/${sessionId} && gemini -p "
      PURPOSE: Code quality and best practices review
      TASK: Assess code readability, maintainability, adherence to best practices
-     CONTEXT: @{.summaries/IMPL-*.md,../..,../../CLAUDE.md}
+     CONTEXT: @.summaries/IMPL-*.md,../.. @../../CLAUDE.md
      EXPECTED: Quality assessment with improvement suggestions
      RULES: Check for code smells, duplication, complexity, naming conventions
      " --approval-mode yolo
@@ -143,10 +143,10 @@ After bash validation, the model takes control to:
      ' {} \;
 
      # Check implementation summaries against requirements
-     cd .workflow/${sessionId} && ~/.claude/scripts/gemini-wrapper -p "
+     cd .workflow/${sessionId} && gemini -p "
      PURPOSE: Verify all requirements and acceptance criteria are met
      TASK: Cross-check implementation summaries against original requirements
-     CONTEXT: @{.task/IMPL-*.json,.summaries/IMPL-*.md,../..,../../CLAUDE.md}
+     CONTEXT: @.task/IMPL-*.json,.summaries/IMPL-*.md,../.. @../../CLAUDE.md
      EXPECTED:
      - Requirements coverage matrix
      - Acceptance criteria verification
@@ -205,7 +205,7 @@ After bash validation, the model takes control to:
    ```bash
    # If architecture or quality issues found, suggest memory update
    if [ "$review_type" = "architecture" ] || [ "$review_type" = "quality" ]; then
-       echo "💡 Consider updating project documentation:"
+       echo "Consider updating project documentation:"
        echo "   /update-memory-related"
    fi
    ```
@@ -226,7 +226,7 @@ After bash validation, the model takes control to:
 /workflow:review --type=docs
 ```
 
-## ✨ Features
+## Features
 
 - **Simple Validation**: Check session exists and has completed tasks
 - **No Complex Orchestration**: Direct analysis, no multi-phase pipeline
@@ -240,10 +240,10 @@ After bash validation, the model takes control to:
 
 ```
 Standard Workflow:
-  plan → execute → test-gen → execute ✅
+  plan -> execute -> test-gen -> execute (complete)
 
 Optional Review (when needed):
-  plan → execute → test-gen → execute → review (security/architecture/docs)
+  plan -> execute -> test-gen -> execute -> review (security/architecture/docs)
 ```
 
 **When to Use**:
@@ -256,11 +256,3 @@ Optional Review (when needed):
 - Regular development (tests are sufficient)
 - Simple bug fixes (test-fix-agent handles it)
 - Minor changes (update-memory-related is enough)
-
-## Related Commands
-
-- `/workflow:execute` - Must complete implementation first
-- `/workflow:test-gen` - Primary quality gate (tests)
-- `/workflow:tools:docs` - Generate hierarchical documentation (use instead of `--type=docs`)
-- `/update-memory-related` - Update CLAUDE.md docs after architecture findings
-- `/workflow:status` - Check session status

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

@@ -1,6 +1,6 @@
 ---
 name: complete
-description: Mark the active workflow session as complete and remove active flag
+description: Mark the active workflow session as complete, archive it with lessons learned, and remove active flag
 examples:
   - /workflow:session:complete
   - /workflow:session:complete --detailed
@@ -9,7 +9,7 @@ examples:
 # Complete Workflow Session (/workflow:session:complete)
 
 ## Overview
-Mark the currently active workflow session as complete, update its status, and remove the active flag marker.
+Mark the currently active workflow session as complete, analyze it for lessons learned, move it to the archive directory, and remove the active flag marker.
 
 ## Usage
 ```bash
@@ -19,87 +19,129 @@ Mark the currently active workflow session as complete, update its status, and r
 
 ## Implementation Flow
 
-### Step 1: Find Active Session
+### Phase 1: Prepare for Archival (Minimal Manual Operations)
+
+**Purpose**: Find active session, move to archive location, pass control to agent. Minimal operations.
+
+#### Step 1.1: Find Active Session and Get Name
 ```bash
-ls .workflow/.active-* 2>/dev/null | head -1
+# Find active marker
-```
+bash(find .workflow/ -name ".active-*" -type f | head -1)
 
-### Step 2: Get Session Name
+# Extract session name from marker path
+bash(basename .workflow/.active-WFS-session-name | sed 's/^\.active-//')
+```
+**Output**: Session name `WFS-session-name`
+
+#### Step 1.2: Move Session to Archive
 ```bash
-basename .workflow/.active-WFS-session-name | sed 's/^\.active-//'
+# Create archive directory if needed
+bash(mkdir -p .workflow/.archives/)
+
+# Move session to archive location
+bash(mv .workflow/WFS-session-name .workflow/.archives/WFS-session-name)
+```
+**Result**: Session now at `.workflow/.archives/WFS-session-name/`
+
+### Phase 2: Agent-Orchestrated Completion (All Data Processing)
+
+**Purpose**: Agent analyzes archived session, generates metadata, updates manifest, and removes active marker.
+
+#### Agent Invocation
+
+Invoke `universal-executor` agent to complete the archival process.
+
+**Agent Task**:
+```
+Task(
+  subagent_type="universal-executor",
+  description="Complete session archival",
+  prompt=`
+Complete workflow session archival. Session already moved to archive location.
+
+## Context
+- Session: .workflow/.archives/WFS-session-name/
+- Active marker: .workflow/.active-WFS-session-name
+
+## Tasks
+
+1. **Extract session data** from workflow-session.json (session_id, description/topic, started_at/timestamp, completed_at, status)
+   - If status != "completed", update it with timestamp
+
+2. **Count files**: tasks (.task/*.json) and summaries (.summaries/*.md)
+
+3. **Generate lessons**: Use gemini with ~/.claude/workflows/cli-templates/prompts/archive/analysis-simple.txt (fallback: analyze files directly)
+   - Return: {successes, challenges, watch_patterns}
+
+4. **Build archive entry**:
+   - Calculate: duration_hours, success_rate, tags (3-5 keywords)
+   - Construct complete JSON with session_id, description, archived_at, archive_path, metrics, tags, lessons
+
+5. **Update manifest**: Initialize .workflow/.archives/manifest.json if needed, append entry
+
+6. **Remove active marker**
+
+7. **Return result**: {"status": "success", "session_id": "...", "archived_at": "...", "metrics": {...}, "lessons_summary": {...}}
+
+## Error Handling
+- On failure: return {"status": "error", "task": "...", "message": "..."}
+- Do NOT remove marker if failed
+  `
+)
 ```
 
-### Step 3: Update Session Status
+**Expected Output**:
+- Agent returns JSON result confirming successful archival
+- Display completion summary to user based on agent response
+
+## Workflow Execution Strategy
+
+### Two-Phase Approach (Optimized)
+
+**Phase 1: Minimal Manual Setup** (2 simple operations)
+- Find active session and extract name
+- Move session to archive location
+- **No data extraction** - agent handles all data processing
+- **No counting** - agent does this from archive location
+- **Total**: 2 bash commands (find + move)
+
+**Phase 2: Agent-Driven Completion** (1 agent invocation)
+- Extract all session data from archived location
+- Count tasks and summaries
+- Generate lessons learned analysis
+- Build complete archive metadata
+- Update manifest
+- Remove active marker
+- Return success/error result
+
+## Quick Commands
+
 ```bash
-jq '.status = "completed"' .workflow/WFS-session/workflow-session.json > temp.json
+# Phase 1: Find and move
-mv temp.json .workflow/WFS-session/workflow-session.json
+bash(find .workflow/ -name ".active-*" -type f | head -1)
+bash(basename .workflow/.active-WFS-session-name | sed 's/^\.active-//')
+bash(mkdir -p .workflow/.archives/)
+bash(mv .workflow/WFS-session-name .workflow/.archives/WFS-session-name)
+
+# Phase 2: Agent completes archival
+Task(subagent_type="universal-executor", description="Complete session archival", prompt=`...`)
 ```
 
-### Step 4: Add Completion Timestamp
+## Archive Query Commands
+
+After archival, you can query the manifest:
+
 ```bash
-jq '.completed_at = "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"' .workflow/WFS-session/workflow-session.json > temp.json
+# List all archived sessions
-mv temp.json .workflow/WFS-session/workflow-session.json
+jq '.archives[].session_id' .workflow/.archives/manifest.json
+
+# Find sessions by keyword
+jq '.archives[] | select(.description | test("auth"; "i"))' .workflow/.archives/manifest.json
+
+# Get specific session details
+jq '.archives[] | select(.session_id == "WFS-user-auth")' .workflow/.archives/manifest.json
+
+# List all watch patterns across sessions
+jq '.archives[].lessons.watch_patterns[]' .workflow/.archives/manifest.json
 ```
 
-### Step 5: Count Final Statistics
-```bash
-find .workflow/WFS-session/.task/ -name "*.json" -type f 2>/dev/null | wc -l
-find .workflow/WFS-session/.summaries/ -name "*.md" -type f 2>/dev/null | wc -l
-```
-
-### Step 6: Remove Active Marker
-```bash
-rm .workflow/.active-WFS-session-name
-```
-
-## Simple Bash Commands
-
-### Basic Operations
-- **Find active session**: `find .workflow/ -name ".active-*" -type f`
-- **Get session name**: `basename marker | sed 's/^\.active-//'`
-- **Update status**: `jq '.status = "completed"' session.json > temp.json`
-- **Add timestamp**: `jq '.completed_at = "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"'`
-- **Count tasks**: `find .task/ -name "*.json" -type f | wc -l`
-- **Count completed**: `find .summaries/ -name "*.md" -type f 2>/dev/null | wc -l`
-- **Remove marker**: `rm .workflow/.active-session`
-
-### Completion Result
-```
-Session WFS-user-auth completed
-- Status: completed
-- Started: 2025-09-15T10:00:00Z
-- Completed: 2025-09-15T16:30:00Z
-- Duration: 6h 30m
-- Total tasks: 8
-- Completed tasks: 8
-- Success rate: 100%
-```
-
-### Detailed Summary (--detailed flag)
-```
-Session Completion Summary:
-├── Session: WFS-user-auth
-├── Project: User authentication system
-├── Total time: 6h 30m
-├── Tasks completed: 8/8 (100%)
-├── Files generated: 24 files
-├── Summaries created: 8 summaries
-├── Status: All tasks completed successfully
-└── Location: .workflow/WFS-user-auth/
-```
-
-### Error Handling
-```bash
-# No active session
-find .workflow/ -name ".active-*" -type f 2>/dev/null || echo "No active session found"
-
-# Incomplete tasks
-task_count=$(find .task/ -name "*.json" -type f | wc -l)
-summary_count=$(find .summaries/ -name "*.md" -type f 2>/dev/null | wc -l)
-test $task_count -eq $summary_count || echo "Warning: Not all tasks completed"
-```
-
-## Related Commands
-- `/workflow:session:list` - View all sessions including completed
-- `/workflow:session:start` - Start new session
-- `/workflow:status` - Check completion status before completing

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

@@ -59,19 +59,19 @@ jq -r '.created_at // "unknown"' .workflow/WFS-session/workflow-session.json
 ```
 Workflow Sessions:
 
-✅ WFS-oauth-integration (ACTIVE)
+[ACTIVE] WFS-oauth-integration
    Project: OAuth2 authentication system
    Status: active
    Progress: 3/8 tasks completed
    Created: 2025-09-15T10:30:00Z
 
-⏸️ WFS-user-profile (PAUSED)
+[PAUSED] WFS-user-profile
    Project: User profile management
    Status: paused
    Progress: 1/5 tasks completed
    Created: 2025-09-14T14:15:00Z
 
-📁 WFS-database-migration (COMPLETED)
+[COMPLETED] WFS-database-migration
    Project: Database schema migration
    Status: completed
    Progress: 4/4 tasks completed
@@ -81,10 +81,10 @@ Total: 3 sessions (1 active, 1 paused, 1 completed)
 ```
 
 ### Status Indicators
-- **✅**: Active session
+- **[ACTIVE]**: Active session
-- **⏸️**: Paused session
+- **[PAUSED]**: Paused session
-- **📁**: Completed session
+- **[COMPLETED]**: Completed session
-- **❌**: Error/corrupted session
+- **[ERROR]**: Error/corrupted session
 
 ### Quick Commands
 ```bash
@@ -96,9 +96,4 @@ ls .workflow/.active-* | basename | sed 's/^\.active-//'
 
 # Show recent sessions
 ls -t .workflow/WFS-*/workflow-session.json | head -3
-```
+```
-
-## Related Commands
-- `/workflow:session:start` - Create new session
-- `/workflow:session:switch` - Switch to different session
-- `/workflow:session:status` - Detailed session info

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

@@ -64,9 +64,4 @@ Session WFS-user-auth resumed
 - Paused at: 2025-09-15T14:30:00Z
 - Resumed at: 2025-09-15T15:45:00Z
 - Ready for: /workflow:execute
-```
+```
-
-## Related Commands
-- `/workflow:session:pause` - Pause current session
-- `/workflow:execute` - Continue workflow execution
-- `/workflow:session:list` - Show all sessions

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

@@ -212,9 +212,4 @@ bash(echo '{"session_id":"WFS-test","project":"test project","status":"planning"
 - Pattern: `WFS-[lowercase-slug]`
 - Characters: `a-z`, `0-9`, `-` only
 - Max length: 50 characters
-- Uniqueness: Add numeric suffix if collision (`WFS-auth-2`, `WFS-auth-3`)
+- Uniqueness: Add numeric suffix if collision (`WFS-auth-2`, `WFS-auth-3`)
-
-## Related Commands
-- `/workflow:plan` - Uses `--auto` mode for session management
-- `/workflow:execute` - Uses discovery mode for session selection
-- `/workflow:session:status` - Shows detailed session information

.claude/commands/workflow/status.md

@@ -51,11 +51,11 @@ find .workflow/WFS-session/.summaries/ -name "*.md" -type f 2>/dev/null | wc -l
 **Progress**: 3/8 tasks completed
 
 ## Active Tasks
-- [⚠️] impl-1: Current task in progress
+- [IN PROGRESS] impl-1: Current task in progress
 - [ ] impl-2: Next pending task
 
 ## Completed Tasks
-- [✅] impl-0: Setup completed
+- [COMPLETED] impl-0: Setup completed
 ```
 
 ## Simple Bash Commands
@@ -112,13 +112,8 @@ Summary: .summaries/impl-1-summary.md
 
 ### Validation Results
 ```
-✅ Session file valid
+Session file valid
-✅ 8 task files found
+8 task files found
-✅ 3 summaries found
+3 summaries found
-⚠️ 5 tasks pending completion
+5 tasks pending completion
-```
+```
-
-## Related Commands
-- `/workflow:execute` - Uses this for task discovery
-- `/workflow:resume` - Uses this for progress analysis
-- `/workflow:session:status` - Shows session metadata

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

@@ -20,12 +20,12 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 execution
 2. **No Preliminary Analysis**: Do not read files before Phase 1
 3. **Parse Every Output**: Extract required data for next phase
-4. **Sequential Execution**: Each phase depends on previous output
+4. **Auto-Continue via TodoList**: Check TodoList status to execute next pending phase automatically
-5. **Complete All Phases**: Do not return until Phase 7 completes (with concept verification)
+5. **Track Progress**: Update TodoWrite after every phase completion
 6. **TDD Context**: All descriptions include "TDD:" prefix
-7. **Quality Gate**: Phase 5 concept verification ensures clarity before task generation
+7. **Quality Gate**: Phase 4 conflict resolution (optional, auto-triggered) validates compatibility before task generation
 
-## 7-Phase Execution (with Concept Verification)
+## 6-Phase Execution (with Conflict Resolution)
 
 ### Phase 1: Session Discovery
 **Command**: `/workflow:session:start --auto "TDD: [structured-description]"`
@@ -41,10 +41,32 @@ TEST_FOCUS: [Test scenarios]
 
 **Parse**: Extract sessionId
 
+**TodoWrite**: Mark phase 1 completed, phase 2 in_progress
+
+**After Phase 1**: Return to user showing Phase 1 results, then auto-continue to Phase 2
+
+---
+
 ### Phase 2: Context Gathering
 **Command**: `/workflow:tools:context-gather --session [sessionId] "TDD: [structured-description]"`
 
-**Parse**: Extract contextPath
+**Use Same Structured Description**: Pass the same structured format from Phase 1
+
+**Input**: `sessionId` from Phase 1
+
+**Parse Output**:
+- Extract: context-package.json path (store as `contextPath`)
+- Typical pattern: `.workflow/[sessionId]/.process/context-package.json`
+
+**Validation**:
+- Context package path extracted
+- File exists and is valid JSON
+
+**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
+
+**After Phase 2**: Return to user showing Phase 2 results, then auto-continue to Phase 3
+
+---
 
 ### Phase 3: Test Coverage Analysis
 **Command**: `/workflow:tools:test-context-gather --session [sessionId]`
@@ -63,34 +85,49 @@ TEST_FOCUS: [Test scenarios]
 - Prevents duplicate test creation
 - Enables integration with existing tests
 
-### Phase 4: TDD Analysis
+**TodoWrite**: Mark phase 3 completed, phase 4 in_progress
-**Command**: `/workflow:tools:concept-enhanced --session [sessionId] --context [contextPath]`
 
-**Note**: Generates ANALYSIS_RESULTS.md with TDD-specific structure:
+**After Phase 3**: Return to user showing test coverage results, then auto-continue to Phase 4
-- Feature list with testable requirements
-- Test cases for Red phase
-- Implementation requirements for Green phase
-- Refactoring opportunities
-- Task dependencies and execution order
 
-**Parse**: Verify ANALYSIS_RESULTS.md contains TDD breakdown sections
+---
 
-### Phase 5: Concept Verification (NEW QUALITY GATE)
+### Phase 4: Conflict Resolution (Optional - auto-triggered by conflict risk)
-**Command**: `/workflow:concept-verify --session [sessionId]`
 
-**Purpose**: Verify conceptual clarity before TDD task generation
+**Trigger**: Only execute when context-package.json indicates conflict_risk is "medium" or "high"
-- Clarify test requirements and acceptance criteria
-- Resolve ambiguities in expected behavior
-- Validate TDD approach is appropriate
 
-**Behavior**:
+**Command**: `SlashCommand(command="/workflow:tools:conflict-resolution --session [sessionId] --context [contextPath]")`
-- If no ambiguities found → Auto-proceed to Phase 6
-- If ambiguities exist → Interactive clarification (up to 5 questions)
-- After clarifications → Auto-proceed to Phase 6
 
-**Parse**: Verify concept verification completed (check for clarifications section in ANALYSIS_RESULTS.md or synthesis file if exists)
+**Input**:
+- sessionId from Phase 1
+- contextPath from Phase 2
+- conflict_risk from context-package.json
 
-### Phase 6: TDD Task Generation
+**Parse Output**:
+- Extract: Execution status (success/skipped/failed)
+- Verify: CONFLICT_RESOLUTION.md file path (if executed)
+
+**Validation**:
+- File `.workflow/[sessionId]/.process/CONFLICT_RESOLUTION.md` exists (if executed)
+
+**Skip Behavior**:
+- If conflict_risk is "none" or "low", skip directly to Phase 5
+- Display: "No significant conflicts detected, proceeding to TDD task generation"
+
+**TodoWrite**: Mark phase 4 completed (if executed) or skipped, phase 5 in_progress
+
+**After Phase 4**: Return to user showing conflict resolution results (if executed) and selected strategies, then auto-continue to Phase 5
+
+**Memory State Check**:
+- Evaluate current context window usage and memory state
+- If memory usage is high (>110K tokens or approaching context limits):
+  - **Command**: `SlashCommand(command="/compact")`
+  - This optimizes memory before proceeding to Phase 5
+- Memory compaction is particularly important after analysis phase which may generate extensive documentation
+- Ensures optimal performance and prevents context overflow
+
+---
+
+### Phase 5: TDD Task Generation
 **Command**:
 - Manual: `/workflow:tools:task-generate-tdd --session [sessionId]`
 - Agent: `/workflow:tools:task-generate-tdd --session [sessionId] --agent`
@@ -108,7 +145,7 @@ TEST_FOCUS: [Test scenarios]
 - 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)
+### Phase 6: TDD Structure Validation & Action Plan Verification (RECOMMENDED)
 **Internal validation first, then recommend external verification**
 
 **Internal Validation**:
@@ -134,14 +171,14 @@ 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 ✅)
+- Total task count: [M] (within 10-task limit)
 
 Structure:
-- IMPL-1: {Feature 1 Name} (Internal: 🔴 Red → 🟢 Green → 🔵 Refactor)
+- IMPL-1: {Feature 1 Name} (Internal: Red → Green → Refactor)
-- IMPL-2: {Feature 2 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.1: {Sub-feature A} (Internal: Red → Green → Refactor)
-  - IMPL-3.2: {Sub-feature B} (Internal: 🔴 Red → 🟢 Green → 🔵 Refactor)
+  - IMPL-3.2: {Sub-feature B} (Internal: Red → Green → Refactor)
 [...]
 
 Plans generated:
@@ -155,29 +192,55 @@ TDD Configuration:
 - Green phase includes test-fix cycle (max 3 iterations)
 - Auto-revert on max iterations reached
 
-✅ Recommended Next Steps:
+Recommended Next Steps:
 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 structure and dependencies
+Quality Gate: Consider running /workflow:action-plan-verify to validate TDD task structure and dependencies
 ```
 
 ## TodoWrite Pattern
 
 ```javascript
-// Initialize (7 phases now with concept verification)
+// Initialize (Phase 4 added dynamically after Phase 3 if conflict_risk ≥ medium)
-[
+TodoWrite({todos: [
-  {content: "Execute session discovery", status: "in_progress", activeForm: "Executing session discovery"},
+  {"content": "Execute session discovery", "status": "in_progress", "activeForm": "Executing session discovery"},
-  {content: "Execute context gathering", status: "pending", activeForm": "Executing context gathering"},
+  {"content": "Execute context gathering", "status": "pending", "activeForm": "Executing context gathering"},
-  {content: "Execute test coverage analysis", status: "pending", activeForm": "Executing test coverage analysis"},
+  {"content": "Execute test coverage analysis", "status": "pending", "activeForm": "Executing test coverage analysis"},
-  {content: "Execute TDD analysis", status: "pending", activeForm": "Executing TDD analysis"},
+  // Phase 4 todo added dynamically after Phase 3 if conflict_risk ≥ medium
-  {content: "Execute concept verification", status: "pending", activeForm": "Executing concept verification"},
+  {"content": "Execute TDD task generation", "status": "pending", "activeForm": "Executing TDD task generation"},
-  {content: "Execute TDD task generation", status: "pending", activeForm: "Executing TDD task generation"},
+  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
-  {content: "Validate TDD structure", status: "pending", activeForm: "Validating TDD structure"}
+]})
-]
 
-// Update after each phase: mark current "completed", next "in_progress"
+// After Phase 3 (if conflict_risk ≥ medium, insert Phase 4 todo)
+TodoWrite({todos: [
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
+  {"content": "Execute conflict resolution", "status": "in_progress", "activeForm": "Executing conflict resolution"},
+  {"content": "Execute TDD task generation", "status": "pending", "activeForm": "Executing TDD task generation"},
+  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
+]})
+
+// After Phase 3 (if conflict_risk is none/low, skip Phase 4, go directly to Phase 5)
+TodoWrite({todos: [
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
+  {"content": "Execute TDD task generation", "status": "in_progress", "activeForm": "Executing TDD task generation"},
+  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
+]})
+
+// After Phase 4 (if executed), continue to Phase 5
+TodoWrite({todos: [
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
+  {"content": "Execute conflict resolution", "status": "completed", "activeForm": "Executing conflict resolution"},
+  {"content": "Execute TDD task generation", "status": "in_progress", "activeForm": "Executing TDD task generation"},
+  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
+]})
 ```
 
 ## Input Processing
@@ -195,11 +258,6 @@ Convert user input to TDD-structured format:
 - **Command failure**: Keep phase in_progress, report error
 - **TDD validation failure**: Report incomplete chains or wrong dependencies
 
-## Related Commands
-- `/workflow:plan` - Standard (non-TDD) planning
-- `/workflow:execute` - Execute TDD tasks
-- `/workflow:tdd-verify` - Verify TDD compliance
-- `/workflow:status` - View progress
 ## TDD Workflow Enhancements
 
 ### Overview
@@ -231,7 +289,7 @@ IMPL (Green phase) tasks now include automatic test-fix cycle for resilient impl
 ```
 1. Write minimal implementation code
 2. Execute test suite
-3. IF tests pass → Complete task ✅
+3. IF tests pass → Complete task
 4. IF tests fail → Enter fix cycle:
    a. Gemini diagnoses with bug-fix template
    b. Apply fix (manual or Codex)
@@ -241,10 +299,10 @@ IMPL (Green phase) tasks now include automatic test-fix cycle for resilient impl
 ```
 
 **Benefits**:
-- ✅ Faster feedback within Green phase
+- Faster feedback within Green phase
-- ✅ Autonomous recovery from implementation errors
+- Autonomous recovery from implementation errors
-- ✅ Systematic debugging with Gemini
+- Systematic debugging with Gemini
-- ✅ Safe rollback prevents broken state
+- Safe rollback prevents broken state
 
 #### 3. Agent-Driven Planning
 **From plan --agent workflow**
@@ -272,7 +330,7 @@ Supports action-planning-agent for more autonomous TDD planning with:
 
 ### Migration Notes
 
-**Backward Compatibility**: ✅ Fully compatible
+**Backward Compatibility**: Fully compatible
 - Existing TDD workflows continue to work
 - New features are additive, not breaking
 - Phase 3 can be skipped if test-context-gather not available
@@ -304,3 +362,23 @@ Supports action-planning-agent for more autonomous TDD planning with:
 - `meta.max_iterations`: Fix attempts (default: 3)
 - `meta.use_codex`: Auto-fix mode (default: false)
 
+## Related Commands
+
+**Prerequisite Commands**:
+- None - TDD planning is self-contained (can optionally run brainstorm commands before)
+
+**Called by This Command** (6 phases):
+- `/workflow:session:start` - Phase 1: Create or discover TDD workflow session
+- `/workflow:tools:context-gather` - Phase 2: Gather project context and analyze codebase
+- `/workflow:tools:test-context-gather` - Phase 3: Analyze existing test patterns and coverage
+- `/workflow:tools:conflict-resolution` - Phase 4: Detect and resolve conflicts (auto-triggered if conflict_risk ≥ medium)
+- `/compact` - Phase 4: Memory optimization (if context approaching limits)
+- `/workflow:tools:task-generate-tdd` - Phase 5: Generate TDD task chains with Red-Green-Refactor cycles
+- `/workflow:tools:task-generate-tdd --agent` - Phase 5: Generate TDD tasks with agent-driven approach (when `--agent` flag used)
+
+**Follow-up Commands**:
+- `/workflow:action-plan-verify` - Recommended: Verify TDD plan quality and structure before execution
+- `/workflow:status` - Review TDD task breakdown
+- `/workflow:execute` - Begin TDD implementation
+- `/workflow:tdd-verify` - Post-execution: Verify TDD compliance and generate quality report
+

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

@@ -3,7 +3,7 @@ name: tdd-verify
 description: Verify TDD workflow compliance and generate quality report
 
 argument-hint: "[optional: WFS-session-id]"
-allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(gemini-wrapper:*)
+allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(gemini:*)
 ---
 
 # TDD Verification Command (/workflow:tdd-verify)
@@ -94,7 +94,7 @@ find .workflow/{sessionId}/.task/ -name '*.json' -exec jq -r '.meta.agent' {} \;
 **Gemini analysis for comprehensive TDD compliance report**
 
 ```bash
-cd project-root && ~/.claude/scripts/gemini-wrapper -p "
+cd project-root && gemini -p "
 PURPOSE: Generate TDD compliance report
 TASK: Analyze TDD workflow execution and generate quality report
 CONTEXT: @{.workflow/{sessionId}/.task/*.json,.workflow/{sessionId}/.summaries/*,.workflow/{sessionId}/.process/tdd-cycle-report.md}
@@ -118,14 +118,14 @@ RULES: Focus on TDD best practices and workflow adherence. Be specific about vio
 TDD Verification Report - Session: {sessionId}
 
 ## Chain Validation
-✅ Feature 1: TEST-1.1 → IMPL-1.1 → REFACTOR-1.1 (Complete)
+[COMPLETE] Feature 1: TEST-1.1 → IMPL-1.1 → REFACTOR-1.1 (Complete)
-✅ Feature 2: TEST-2.1 → IMPL-2.1 → REFACTOR-2.1 (Complete)
+[COMPLETE] Feature 2: TEST-2.1 → IMPL-2.1 → REFACTOR-2.1 (Complete)
-⚠️  Feature 3: TEST-3.1 → IMPL-3.1 (Missing REFACTOR phase)
+[INCOMPLETE] Feature 3: TEST-3.1 → IMPL-3.1 (Missing REFACTOR phase)
 
 ## Test Execution
-✅ All TEST tasks produced failing tests
+All TEST tasks produced failing tests
-✅ All IMPL tasks made tests pass
+All IMPL tasks made tests pass
-✅ All REFACTOR tasks maintained green tests
+All REFACTOR tasks maintained green tests
 
 ## Coverage Metrics
 Line Coverage: {percentage}%
@@ -237,7 +237,7 @@ Final Score: Max(0, Base Score - Deductions)
 
 ### Command Chain
 - **Called After**: `/workflow:execute` (when TDD tasks completed)
-- **Calls**: `/workflow:tools:tdd-coverage-analysis`, Gemini wrapper
+- **Calls**: `/workflow:tools:tdd-coverage-analysis`, Gemini CLI
 - **Related**: `/workflow:tdd-plan`, `/workflow:status`
 
 ### Basic Usage
@@ -271,20 +271,20 @@ Status: {EXCELLENT | GOOD | NEEDS IMPROVEMENT | FAILED}
 ## Chain Analysis
 
 ### Feature 1: {Feature Name}
-**Status**: ✅ Complete
+**Status**: Complete
 **Chain**: TEST-1.1 → IMPL-1.1 → REFACTOR-1.1
 
-- ✅ **Red Phase**: Test created and failed with clear message
+- **Red Phase**: Test created and failed with clear message
-- ✅ **Green Phase**: Minimal implementation made test pass
+- **Green Phase**: Minimal implementation made test pass
-- ✅ **Refactor Phase**: Code improved, tests remained green
+- **Refactor Phase**: Code improved, tests remained green
 
 ### Feature 2: {Feature Name}
-**Status**: ⚠️ Incomplete
+**Status**: Incomplete
 **Chain**: TEST-2.1 → IMPL-2.1 (Missing REFACTOR-2.1)
 
-- ✅ **Red Phase**: Test created and failed
+- **Red Phase**: Test created and failed
-- ⚠️ **Green Phase**: Implementation seems over-engineered
+- **Green Phase**: Implementation seems over-engineered
-- ❌ **Refactor Phase**: Missing
+- **Refactor Phase**: Missing
 
 **Issues**:
 - REFACTOR-2.1 task not completed
@@ -306,16 +306,16 @@ Status: {EXCELLENT | GOOD | NEEDS IMPROVEMENT | FAILED}
 ## TDD Cycle Validation
 
 ### Red Phase (Write Failing Test)
-- ✅ {N}/{total} features had failing tests initially
+- {N}/{total} features had failing tests initially
-- ⚠️ Feature 3: No evidence of initial test failure
+- Feature 3: No evidence of initial test failure
 
 ### Green Phase (Make Test Pass)
-- ✅ {N}/{total} implementations made tests pass
+- {N}/{total} implementations made tests pass
-- ✅ All implementations minimal and focused
+- All implementations minimal and focused
 
 ### Refactor Phase (Improve Quality)
-- ⚠️ {N}/{total} features completed refactoring
+- {N}/{total} features completed refactoring
-- ❌ Feature 2, 4: Refactoring step skipped
+- Feature 2, 4: Refactoring step skipped
 
 ## Best Practices Assessment
 
@@ -351,8 +351,3 @@ Status: {EXCELLENT | GOOD | NEEDS IMPROVEMENT | FAILED}
 {Summary of compliance status and next steps}
 ```
 
-## Related Commands
-- `/workflow:tdd-plan` - Creates TDD workflow
-- `/workflow:execute` - Executes TDD tasks
-- `/workflow:tools:tdd-coverage-analysis` - Analyzes test coverage
-- `/workflow:status` - Views workflow progress

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

@@ -10,6 +10,12 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Task(*)
 ## 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.
 
+**CRITICAL - Orchestrator Boundary**:
+- This command is the **ONLY place** where test failures are handled
+- All CLI analysis (Gemini/Qwen), fix task generation (IMPL-fix-N.json), and iteration management happen HERE
+- Agents (@test-fix-agent) only execute single tasks and return results
+- **Do NOT handle test failures in main workflow or other commands** - always delegate to this orchestrator
+
 **Resume Mode**: When called with `--resume-session` flag, skips discovery and continues from interruption point.
 
 ## Core Philosophy
@@ -53,21 +59,23 @@ Orchestrates dynamic test-fix workflow execution through iterative cycles of tes
 
 ## Responsibility Matrix
 
-**Clear division of labor between orchestrator and agents:**
+**CRITICAL - 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 |
+| Manage iteration loop | Yes - Controls loop flow | No - Executes single task |
-| Run CLI analysis (Gemini/Qwen) | ✅ Runs between agent tasks | ❌ Not involved |
+| Run CLI analysis (Gemini/Qwen) | Yes - Runs between agent tasks | No - Not involved |
-| Generate IMPL-fix-N.json | ✅ Creates task files | ❌ Not involved |
+| Generate IMPL-fix-N.json | Yes - Creates task files | No - Not involved |
-| Run tests | ❌ Delegates to agent | ✅ Executes test command |
+| Run tests | No - Delegates to agent | Yes - Executes test command |
-| Apply fixes | ❌ Delegates to agent | ✅ Modifies code |
+| Apply fixes | No - Delegates to agent | Yes - Modifies code |
-| Detect test failures | ✅ Analyzes agent output | ✅ Reports results |
+| Detect test failures | Yes - Analyzes results and decides next action | Yes - Executes tests and reports outcomes |
-| Add tasks to queue | ✅ Manages queue | ❌ Not involved |
+| Add tasks to queue | Yes - Manages queue | No - Not involved |
-| Update iteration state | ✅ Maintains state files | ✅ Updates task status |
+| Update iteration state | Yes - Maintains overall iteration state | Yes - Updates individual task status only |
 
 **Key Principle**: Orchestrator manages the "what" and "when"; agents execute the "how".
 
+**ENFORCEMENT**: If test failures occur outside this orchestrator, do NOT handle them inline - always call `/workflow:test-cycle-execute` instead.
+
 ## Execution Lifecycle
 
 ### Phase 1: Discovery & Initialization
@@ -217,20 +225,22 @@ Iteration N (managed by test-cycle-execute orchestrator):
 **Orchestrator executes CLI analysis between agent tasks:**
 
 #### When Test Failures Occur
-1. **[Orchestrator]** Detects failures from agent output
+1. **[Orchestrator]** Detects failures from agent test execution output
 2. **[Orchestrator]** Collects failure context from `.process/test-results.json` and logs
-3. **[Orchestrator]** Runs Gemini/Qwen wrapper with failure context
+3. **[Orchestrator]** Executes Gemini/Qwen CLI tool with failure context
-4. **[CLI Tool]** Analyzes failures and generates fix strategy
+4. **[Orchestrator]** Interprets CLI tool output to extract 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)
 
+**Note**: The orchestrator executes CLI analysis tools and processes their output. CLI tools provide analysis, orchestrator manages the workflow.
+
 #### CLI Analysis Command (executed by orchestrator)
 ```bash
-cd {project_root} && ~/.claude/scripts/gemini-wrapper -p "
+cd {project_root} && gemini -p "
 PURPOSE: Analyze test failures and generate fix strategy
 TASK: Review test failures and identify root causes
 MODE: analysis
-CONTEXT: @{test files, implementation files}
+CONTEXT: @test files @ implementation files
 
 [Test failure context and requirements...]
 
@@ -516,15 +526,16 @@ Task(subagent_type="{meta.agent}",
      ### For test-fix (IMPL-002):
      - Run test suite: {test_command}
      - Collect results to .process/test-results.json
-     - If failures: Save context, return to orchestrator
+     - Report results to orchestrator (do NOT analyze failures)
+     - Orchestrator will handle failure detection and iteration decisions
      - 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
+     - Return results to orchestrator
-     - If still failures: Save context with new failure data
+     - Do NOT run tests independently - orchestrator manages all test execution
-     - Update iteration state
+     - Do NOT handle failures - orchestrator analyzes and decides next iteration
 
      ## STEP 4: Implementation Context (From JSON)
      **Requirements**: {context.requirements}
@@ -642,10 +653,3 @@ mv temp.json iteration-state.json
 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

@@ -13,7 +13,11 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 
 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`).
+**CRITICAL - Command Scope**:
+- **This command ONLY generates task JSON files** (IMPL-001.json, IMPL-002.json)
+- **Does NOT execute tests or apply fixes** - all execution happens in separate orchestrator
+- **Must call `/workflow:test-cycle-execute`** after this command to actually run tests and fixes
+- **Test failure handling happens in test-cycle-execute**, not here
 
 ### Dual-Mode Support
 
@@ -44,12 +48,15 @@ fi
 
 ### Coordinator Role
 
-This command is a **pure orchestrator**:
+This command is a **pure planning coordinator**:
 - Does NOT analyze code directly
 - Does NOT generate tests or documentation
-- ONLY coordinates slash commands in sequence
+- Does NOT execute tests or apply fixes
+- Does NOT handle test failures or iterations
+- ONLY coordinates slash commands to generate task JSON files
 - Parses outputs to pass data between phases
 - Creates independent test workflow session
+- **All execution delegated to `/workflow:test-cycle-execute`**
 
 ---
 
@@ -267,14 +274,20 @@ Review artifacts:
 - Test plan: .workflow/[testSessionId]/IMPL_PLAN.md
 - Task list: .workflow/[testSessionId]/TODO_LIST.md
 
-Next Steps:
+CRITICAL - Next Steps:
-- Review IMPL_PLAN.md
+1. Review IMPL_PLAN.md
-- Execute: /workflow:test-cycle-execute [testSessionId]
+2. **MUST execute: /workflow:test-cycle-execute**
+   - This command only generated task JSON files
+   - Test execution and fix iterations happen in test-cycle-execute
+   - Do NOT attempt to run tests or fixes in main workflow
 ```
 
 **TodoWrite**: Mark phase 5 completed
 
-**Note**: Command completes here. Task execution requires separate workflow commands.
+**BOUNDARY NOTE**:
+- Command completes here - only task JSON files generated
+- All test execution, failure detection, CLI analysis, fix generation happens in `/workflow:test-cycle-execute`
+- This command does NOT handle test failures or apply fixes
 
 ---
 
@@ -329,7 +342,9 @@ Generates minimum 2 tasks (expandable for complex projects):
 
 **Agent**: `@test-fix-agent`
 
-**Purpose**: Execute tests and apply iterative fixes (max 5 iterations)
+**Purpose**: Execute initial tests and trigger orchestrator-managed fix cycles
+
+**Note**: This task executes tests and reports results. The test-cycle-execute orchestrator manages all fix iterations, CLI analysis, and fix task generation.
 
 **Task Configuration**:
 - Task ID: `IMPL-002`
@@ -340,11 +355,12 @@ Generates minimum 2 tasks (expandable for complex projects):
 - `context.requirements`: Execute and fix tests
 
 **Test-Fix Cycle Specification**:
-- **Cycle Pattern**: test → gemini_diagnose → manual_fix (or codex) → retest
+**Note**: This specification describes what test-cycle-execute orchestrator will do. The agent only executes single tasks.
-- **Tools Configuration**:
+- **Cycle Pattern** (orchestrator-managed): test → gemini_diagnose → manual_fix (or codex) → retest
+- **Tools Configuration** (orchestrator-controlled):
   - Gemini for analysis with bug-fix template → surgical fix suggestions
   - Manual fix application (default) OR Codex if `--use-codex` flag (resume mechanism)
-- **Exit Conditions**:
+- **Exit Conditions** (orchestrator-enforced):
   - Success: All tests pass
   - Failure: Max iterations reached (5)
 
@@ -446,25 +462,23 @@ WFS-test-[session]/
    - Use `--use-codex` for autonomous fix application
    - Use `--cli-execute` for enhanced generation capabilities
 
-### Related Commands
+## Related Commands
 
-**Planning Phase**:
+**Prerequisite Commands**:
-- `/workflow:plan` - Create implementation workflow
+- `/workflow:plan` or `/workflow:execute` - Complete implementation session (for Session Mode)
-- `/workflow:session:start` - Initialize workflow session
+- None for Prompt Mode (ad-hoc test generation)
 
-**Context Gathering**:
+**Called by This Command** (5 phases):
-- `/workflow:tools:test-context-gather` - Session-based context (Phase 2 for session mode)
+- `/workflow:session:start` - Phase 1: Create independent test workflow session
-- `/workflow:tools:context-gather` - Prompt-based context (Phase 2 for prompt mode)
+- `/workflow:tools:test-context-gather` - Phase 2 (Session Mode): Gather source session context
+- `/workflow:tools:context-gather` - Phase 2 (Prompt Mode): Analyze codebase directly
+- `/workflow:tools:test-concept-enhanced` - Phase 3: Generate test requirements using Gemini
+- `/workflow:tools:test-task-generate` - Phase 4: Generate test task JSONs with fix cycle specification
+- `/workflow:tools:test-task-generate --use-codex` - Phase 4: With automated Codex fixes (when `--use-codex` flag used)
+- `/workflow:tools:test-task-generate --cli-execute` - Phase 4: With CLI execution mode (when `--cli-execute` flag used)
 
-**Analysis & Task Generation**:
+**Follow-up Commands**:
-- `/workflow:tools:test-concept-enhanced` - Gemini test analysis (Phase 3)
+- `/workflow:status` - Review generated test tasks
-- `/workflow:tools:test-task-generate` - Generate test tasks (Phase 4)
+- `/workflow:test-cycle-execute` - Execute test generation and iterative fix cycles
+- `/workflow:execute` - Standard execution of generated test tasks
 
-**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,7 +24,7 @@ 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.
+**Command Scope**: This command ONLY prepares test workflow artifacts. It does NOT execute tests or implementation. Task execution requires separate user action.
 
 ## Core Rules
 
@@ -36,7 +36,7 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 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.
+9. **Command Boundary**: This command ends at Phase 5 summary. Test execution is NOT part of this command.
 
 ## 5-Phase Execution
 
@@ -177,13 +177,13 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 
 ---
 
-### Phase 5: Return Summary (⚠️ Command Ends Here)
+### 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.
+**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**:
 ```
-✅ Test workflow preparation complete!
+Test workflow preparation complete!
 
 Source Session: [sourceSessionId]
 Test Session: [testSessionId]
@@ -198,17 +198,17 @@ Test Framework: [detected framework]
 Test Files to Generate: [count]
 Fix Mode: [Manual|Codex Automated] (based on --use-codex flag)
 
-📋 Review Generated Artifacts:
+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.
+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.
+**Command Boundary**: After this phase, the command terminates and returns to user prompt.
 
 ---
 
@@ -244,7 +244,7 @@ Update status to `in_progress` when starting each phase, mark `completed` when d
 │   ↓                                                     │
 │ Phase 5: Return summary                                │
 └─────────────────────────────────────────────────────────┘
-         ⚠️ COMMAND ENDS - Control returns to user
+         COMMAND ENDS - Control returns to user
 
 Artifacts Created:
 ├── .workflow/WFS-test-[session]/
@@ -330,8 +330,18 @@ See `/workflow:tools:test-task-generate` for complete JSON schemas.
 
 ## Related Commands
 
-- `/workflow:tools:test-context-gather` - Phase 2 (coverage analysis)
+**Prerequisite Commands**:
-- `/workflow:tools:test-concept-enhanced` - Phase 3 (Gemini test analysis)
+- `/workflow:plan` or `/workflow:execute` - Complete implementation session that needs test validation
-- `/workflow:tools:test-task-generate` - Phase 4 (task generation)
+
-- `/workflow:execute` - Execute workflow
+**Called by This Command** (5 phases):
-- `/workflow:status` - Check progress
+- `/workflow:session:start` - Phase 1: Create independent test workflow session
+- `/workflow:tools:test-context-gather` - Phase 2: Analyze test coverage and gather source session context
+- `/workflow:tools:test-concept-enhanced` - Phase 3: Generate test requirements and strategy using Gemini
+- `/workflow:tools:test-task-generate` - Phase 4: Generate test generation and execution task JSONs
+- `/workflow:tools:test-task-generate --use-codex` - Phase 4: With automated Codex fixes (when `--use-codex` flag used)
+- `/workflow:tools:test-task-generate --cli-execute` - Phase 4: With CLI execution mode (when `--cli-execute` flag used)
+
+**Follow-up Commands**:
+- `/workflow:status` - Review generated test tasks
+- `/workflow:test-cycle-execute` - Execute test generation and fix cycles
+- `/workflow:execute` - Execute generated test tasks

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

@@ -1,380 +0,0 @@
----
-name: concept-enhanced
-description: Enhanced intelligent analysis with parallel CLI execution and design blueprint generation
-argument-hint: "--session WFS-session-id --context path/to/context-package.json"
-examples:
-  - /workflow:tools:concept-enhanced --session WFS-auth --context .workflow/WFS-auth/.process/context-package.json
-  - /workflow:tools:concept-enhanced --session WFS-payment --context .workflow/WFS-payment/.process/context-package.json
----
-
-# Enhanced Analysis Command (/workflow:tools:concept-enhanced)
-
-## Overview
-Advanced solution design and feasibility analysis engine with parallel CLI execution. Processes standardized context packages to produce ANALYSIS_RESULTS.md focused on solution improvements, key design decisions, and critical insights.
-
-**Scope**: Solution-focused technical analysis only. Does NOT generate task breakdowns or implementation plans.
-
-**Usage**: Standalone command or integrated into `/workflow:plan`. Accepts context packages and orchestrates Gemini/Codex for comprehensive analysis.
-
-## Core Philosophy & Responsibilities
-- **Solution-Focused Analysis**: Emphasize design decisions, architectural rationale, and critical insights (exclude task planning)
-- **Context-Driven**: Parse and validate context-package.json for precise analysis
-- **Intelligent Tool Selection**: Gemini for design (all tasks), Codex for validation (complex tasks only)
-- **Parallel Execution**: Execute multiple CLI tools simultaneously for efficiency
-- **Solution Design**: Evaluate architecture, identify key design decisions with rationale
-- **Feasibility Assessment**: Analyze technical complexity, risks, implementation readiness
-- **Optimization Recommendations**: Performance, security, and code quality improvements
-- **Perspective Synthesis**: Integrate multi-tool insights into unified assessment
-- **Single Output**: Generate only ANALYSIS_RESULTS.md with technical analysis
-
-## Analysis Strategy Selection
-
-### Tool Selection by Task Complexity
-
-**Simple Tasks (≤3 modules)**:
-- **Primary**: Gemini (rapid understanding + pattern recognition)
-- **Support**: Code-index (structural analysis)
-- **Mode**: Single-round analysis
-
-**Medium Tasks (4-6 modules)**:
-- **Primary**: Gemini (comprehensive analysis + architecture design)
-- **Support**: Code-index + Exa (best practices)
-- **Mode**: Single comprehensive round
-
-**Complex Tasks (>6 modules)**:
-- **Primary**: Gemini (comprehensive analysis) + Codex (validation)
-- **Mode**: Parallel execution - Gemini design + Codex feasibility
-
-### Tool Preferences by Tech Stack
-
-```json
-{
-  "frontend": {
-    "primary": "gemini",
-    "secondary": "codex",
-    "focus": ["component_design", "state_management", "ui_patterns"]
-  },
-  "backend": {
-    "primary": "codex",
-    "secondary": "gemini",
-    "focus": ["api_design", "data_flow", "security", "performance"]
-  },
-  "fullstack": {
-    "primary": "gemini",
-    "secondary": "codex",
-    "focus": ["system_architecture", "integration", "data_consistency"]
-  }
-}
-```
-
-## Execution Lifecycle
-
-### Phase 1: Validation & Preparation
-1. **Session Validation**: Verify `.workflow/{session_id}/` exists, load `workflow-session.json`
-2. **Context Package Validation**: Verify path, validate JSON format and structure
-3. **Task Analysis**: Extract keywords, identify domain/complexity, determine scope
-4. **Tool Selection**: Gemini (all tasks), +Codex (complex only), load templates
-
-### Phase 2: Analysis Preparation
-1. **Workspace Setup**: Create `.workflow/{session_id}/.process/`, initialize logs, set resource limits
-2. **Context Optimization**: Filter high-priority assets, organize structure, prepare templates
-3. **Execution Environment**: Configure CLI tools, set timeouts, prepare error handling
-
-### Phase 3: Parallel Analysis Execution
-1. **Gemini Solution Design & Architecture Analysis**
-   ```bash
-   ~/.claude/scripts/gemini-wrapper -p "
-   PURPOSE: Analyze and design optimal solution for {task_description}
-   TASK: Evaluate current architecture, propose solution design, identify key design decisions
-   CONTEXT: @{.workflow/{session_id}/.process/context-package.json,.workflow/{session_id}/workflow-session.json,CLAUDE.md}
-
-   **MANDATORY**: Read context-package.json to understand task requirements, source files, tech stack, project structure
-
-   **ANALYSIS PRIORITY**:
-   1. PRIMARY: Individual role analysis.md files (system-architect, ui-designer, etc.) - technical details, ADRs, decision context
-   2. SECONDARY: synthesis-specification.md - integrated requirements, cross-role alignment
-   3. REFERENCE: topic-framework.md - discussion context
-
-   EXPECTED:
-   1. CURRENT STATE: Existing patterns, code structure, integration points, technical debt
-   2. SOLUTION DESIGN: Core principles, system design, key decisions with rationale
-   3. CRITICAL INSIGHTS: Strengths, gaps, risks, tradeoffs
-   4. OPTIMIZATION: Performance, security, code quality recommendations
-   5. FEASIBILITY: Complexity analysis, compatibility, implementation readiness
-   6. OUTPUT: Write to .workflow/{session_id}/.process/gemini-solution-design.md
-
-   RULES:
-   - Focus on SOLUTION IMPROVEMENTS and KEY DESIGN DECISIONS (NO task planning)
-   - Identify code targets: existing "file:function:lines", new files "file"
-   - Do NOT create task lists, implementation steps, or code examples
-   " --approval-mode yolo
-   ```
-   Output: `.workflow/{session_id}/.process/gemini-solution-design.md`
-
-2. **Codex Technical Feasibility Validation** (Complex Tasks Only)
-   ```bash
-   codex --full-auto exec "
-   PURPOSE: Validate technical feasibility and identify implementation risks for {task_description}
-   TASK: Assess complexity, validate technology choices, evaluate performance/security implications
-   CONTEXT: @{.workflow/{session_id}/.process/context-package.json,.workflow/{session_id}/.process/gemini-solution-design.md,.workflow/{session_id}/workflow-session.json,CLAUDE.md}
-
-   **MANDATORY**: Read context-package.json, gemini-solution-design.md, and relevant source files
-
-   EXPECTED:
-   1. FEASIBILITY: Complexity rating, resource requirements, technology compatibility
-   2. RISK ANALYSIS: Implementation risks, integration challenges, performance/security concerns
-   3. VALIDATION: Development approach, quality standards, maintenance implications
-   4. RECOMMENDATIONS: Must-have requirements, optimization opportunities, security controls
-   5. OUTPUT: Write to .workflow/{session_id}/.process/codex-feasibility-validation.md
-
-   RULES:
-   - Focus on TECHNICAL FEASIBILITY and RISK ASSESSMENT (NO implementation planning)
-   - Verify code targets: existing "file:function:lines", new files "file"
-   - Do NOT create task breakdowns, step-by-step guides, or code examples
-   " --skip-git-repo-check -s danger-full-access
-   ```
-   Output: `.workflow/{session_id}/.process/codex-feasibility-validation.md`
-
-3. **Parallel Execution**: Launch tools simultaneously, monitor progress, handle completion/errors, maintain logs
-
-   **⚠️ IMPORTANT**: CLI commands MUST execute in foreground (NOT background). Do NOT use `run_in_background` parameter for Gemini/Codex execution.
-
-### Phase 4: Results Collection & Synthesis
-1. **Output Validation**: Validate gemini-solution-design.md (all), codex-feasibility-validation.md (complex), use logs if incomplete, classify status
-2. **Quality Assessment**: Verify design rationale, insight depth, feasibility rigor, optimization value
-3. **Synthesis Strategy**: Direct integration (simple/medium), multi-tool synthesis (complex), resolve conflicts, score confidence
-
-### Phase 5: ANALYSIS_RESULTS.md Generation
-1. **Report Sections**: Executive Summary, Current State, Solution Design, Implementation Strategy, Optimization, Success Factors, Confidence Scores
-2. **Guidelines**: Focus on solution improvements and design decisions (exclude task planning), emphasize rationale/tradeoffs/risk assessment
-3. **Output**: Single file `ANALYSIS_RESULTS.md` at `.workflow/{session_id}/.process/` with technical insights and optimization strategies
-
-## Analysis Results Format
-
-Generated ANALYSIS_RESULTS.md focuses on **solution improvements, key design decisions, and critical insights** (NOT task planning):
-
-```markdown
-# Technical Analysis & Solution Design
-
-## Executive Summary
-- **Analysis Focus**: {core_problem_or_improvement_area}
-- **Analysis Timestamp**: {timestamp}
-- **Tools Used**: {analysis_tools}
-- **Overall Assessment**: {feasibility_score}/5 - {recommendation_status}
-
----
-
-## 1. Current State Analysis
-
-### Architecture Overview
-- **Existing Patterns**: {key_architectural_patterns}
-- **Code Structure**: {current_codebase_organization}
-- **Integration Points**: {system_integration_touchpoints}
-- **Technical Debt Areas**: {identified_debt_with_impact}
-
-### Compatibility & Dependencies
-- **Framework Alignment**: {framework_compatibility_assessment}
-- **Dependency Analysis**: {critical_dependencies_and_risks}
-- **Migration Considerations**: {backward_compatibility_concerns}
-
-### Critical Findings
-- **Strengths**: {what_works_well}
-- **Gaps**: {missing_capabilities_or_issues}
-- **Risks**: {identified_technical_and_business_risks}
-
----
-
-## 2. Proposed Solution Design
-
-### Core Architecture Principles
-- **Design Philosophy**: {key_design_principles}
-- **Architectural Approach**: {chosen_architectural_pattern_with_rationale}
-- **Scalability Strategy**: {how_solution_scales}
-
-### System Design
-- **Component Architecture**: {high_level_component_design}
-- **Data Flow**: {data_flow_patterns_and_state_management}
-- **API Design**: {interface_contracts_and_specifications}
-- **Integration Strategy**: {how_components_integrate}
-
-### Key Design Decisions
-1. **Decision**: {critical_design_choice}
-   - **Rationale**: {why_this_approach}
-   - **Alternatives Considered**: {other_options_and_tradeoffs}
-   - **Impact**: {implications_on_architecture}
-
-2. **Decision**: {another_critical_choice}
-   - **Rationale**: {reasoning}
-   - **Alternatives Considered**: {tradeoffs}
-   - **Impact**: {consequences}
-
-### Technical Specifications
-- **Technology Stack**: {chosen_technologies_with_justification}
-- **Code Organization**: {module_structure_and_patterns}
-- **Testing Strategy**: {testing_approach_and_coverage}
-- **Performance Targets**: {performance_requirements_and_benchmarks}
-
----
-
-## 3. Implementation Strategy
-
-### Development Approach
-- **Core Implementation Pattern**: {primary_implementation_strategy}
-- **Module Dependencies**: {dependency_graph_and_order}
-- **Quality Assurance**: {qa_approach_and_validation}
-
-### Code Modification Targets
-**Purpose**: Specific code locations for modification AND new files to create
-
-**Identified Targets**:
-1. **Target**: `src/auth/AuthService.ts:login:45-52`
-   - **Type**: Modify existing
-   - **Modification**: Enhance error handling
-   - **Rationale**: Current logic lacks validation
-
-2. **Target**: `src/auth/PasswordReset.ts`
-   - **Type**: Create new file
-   - **Purpose**: Password reset functionality
-   - **Rationale**: New feature requirement
-
-**Format Rules**:
-- Existing files: `file:function:lines` (with line numbers)
-- New files: `file` (no function or lines)
-- Unknown lines: `file:function:*`
-- Task generation will refine these targets during `analyze_task_patterns` step
-
-### Feasibility Assessment
-- **Technical Complexity**: {complexity_rating_and_analysis}
-- **Performance Impact**: {expected_performance_characteristics}
-- **Resource Requirements**: {development_resources_needed}
-- **Maintenance Burden**: {ongoing_maintenance_considerations}
-
-### Risk Mitigation
-- **Technical Risks**: {implementation_risks_and_mitigation}
-- **Integration Risks**: {compatibility_challenges_and_solutions}
-- **Performance Risks**: {performance_concerns_and_strategies}
-- **Security Risks**: {security_vulnerabilities_and_controls}
-
----
-
-## 4. Solution Optimization
-
-### Performance Optimization
-- **Optimization Strategies**: {key_performance_improvements}
-- **Caching Strategy**: {caching_approach_and_invalidation}
-- **Resource Management**: {resource_utilization_optimization}
-- **Bottleneck Mitigation**: {identified_bottlenecks_and_solutions}
-
-### Security Enhancements
-- **Security Model**: {authentication_authorization_approach}
-- **Data Protection**: {data_security_and_encryption}
-- **Vulnerability Mitigation**: {known_vulnerabilities_and_controls}
-- **Compliance**: {regulatory_and_compliance_considerations}
-
-### Code Quality
-- **Code Standards**: {coding_conventions_and_patterns}
-- **Testing Coverage**: {test_strategy_and_coverage_goals}
-- **Documentation**: {documentation_requirements}
-- **Maintainability**: {maintainability_practices}
-
----
-
-## 5. Critical Success Factors
-
-### Technical Requirements
-- **Must Have**: {essential_technical_capabilities}
-- **Should Have**: {important_but_not_critical_features}
-- **Nice to Have**: {optional_enhancements}
-
-### Quality Metrics
-- **Performance Benchmarks**: {measurable_performance_targets}
-- **Code Quality Standards**: {quality_metrics_and_thresholds}
-- **Test Coverage Goals**: {testing_coverage_requirements}
-- **Security Standards**: {security_compliance_requirements}
-
-### Success Validation
-- **Acceptance Criteria**: {how_to_validate_success}
-- **Testing Strategy**: {validation_testing_approach}
-- **Monitoring Plan**: {production_monitoring_strategy}
-- **Rollback Plan**: {failure_recovery_strategy}
-
----
-
-## 6. Analysis Confidence & Recommendations
-
-### Assessment Scores
-- **Conceptual Integrity**: {score}/5 - {brief_assessment}
-- **Architectural Soundness**: {score}/5 - {brief_assessment}
-- **Technical Feasibility**: {score}/5 - {brief_assessment}
-- **Implementation Readiness**: {score}/5 - {brief_assessment}
-- **Overall Confidence**: {overall_score}/5
-
-### Final Recommendation
-**Status**: {PROCEED|PROCEED_WITH_MODIFICATIONS|RECONSIDER|REJECT}
-
-**Rationale**: {clear_explanation_of_recommendation}
-
-**Critical Prerequisites**: {what_must_be_resolved_before_proceeding}
-
----
-
-## 7. Reference Information
-
-### Tool Analysis Summary
-- **Gemini Insights**: {key_architectural_and_pattern_insights}
-- **Codex Validation**: {technical_feasibility_and_implementation_notes}
-- **Consensus Points**: {agreements_between_tools}
-- **Conflicting Views**: {disagreements_and_resolution}
-
-### Context & Resources
-- **Analysis Context**: {context_package_reference}
-- **Documentation References**: {relevant_documentation}
-- **Related Patterns**: {similar_implementations_in_codebase}
-- **External Resources**: {external_references_and_best_practices}
-```
-
-## Execution Management
-
-### Error Handling & Recovery
-1. **Pre-execution**: Verify session/context package, confirm CLI tools, validate dependencies
-2. **Monitoring & Timeout**: Track progress, 30-min limit, manage parallel execution, maintain status
-3. **Partial Recovery**: Generate results with incomplete outputs, use logs, provide next steps
-4. **Error Recovery**: Auto error detection, structured workflows, graceful degradation
-
-### Performance & Resource Optimization
-- **Parallel Analysis**: Execute multiple tools simultaneously to reduce time
-- **Context Sharding**: Analyze large projects by module shards
-- **Caching**: Reuse results for similar contexts
-- **Resource Management**: Monitor disk/CPU/memory, set limits, cleanup temporary files
-- **Timeout Control**: `timeout 600s` with partial result generation on failure
-
-## Integration & Success Criteria
-
-### Input/Output Interface
-**Input**:
-- `--session` (required): Session ID (e.g., WFS-auth)
-- `--context` (required): Context package path
-- `--depth` (optional): Analysis depth (quick|full|deep)
-- `--focus` (optional): Analysis focus areas
-
-**Output**:
-- Single file: `ANALYSIS_RESULTS.md` at `.workflow/{session_id}/.process/`
-- No supplementary files (JSON, roadmap, templates)
-
-### Quality & Success Validation
-**Quality Checks**: Completeness, consistency, feasibility validation
-
-**Success Criteria**:
-- ✅ Solution-focused analysis (design decisions, critical insights, NO task planning)
-- ✅ Single output file only
-- ✅ Design decision depth with rationale/alternatives/tradeoffs
-- ✅ Feasibility assessment (complexity, risks, readiness)
-- ✅ Optimization strategies (performance, security, quality)
-- ✅ Parallel execution efficiency (Gemini + Codex for complex tasks)
-- ✅ Robust error handling (validation, timeout, partial recovery)
-- ✅ Confidence scoring with clear recommendation status
-
-## Related Commands
-- `/context:gather` - Generate context packages required by this command
-- `/workflow:plan` - Call this command for analysis
-- `/task:create` - Create specific tasks based on analysis results

.claude/commands/workflow/tools/conflict-resolution.md

@@ -0,0 +1,471 @@
+---
+name: conflict-resolution
+description: Detect and resolve conflicts between plan and existing codebase using CLI-powered analysis
+argument-hint: "--session WFS-session-id --context path/to/context-package.json"
+examples:
+  - /workflow:tools:conflict-resolution --session WFS-auth --context .workflow/WFS-auth/.process/context-package.json
+  - /workflow:tools:conflict-resolution --session WFS-payment --context .workflow/WFS-payment/.process/context-package.json
+---
+
+# Conflict Resolution Command
+
+## Purpose
+Analyzes conflicts between implementation plans and existing codebase, generating multiple resolution strategies.
+
+**Scope**: Detection and strategy generation only - NO code modification or task creation.
+
+**Trigger**: Auto-executes in `/workflow:plan` Phase 3 when `conflict_risk ≥ medium`.
+
+## Core Responsibilities
+
+| Responsibility | Description |
+|---------------|-------------|
+| **Detect Conflicts** | Analyze plan vs existing code inconsistencies |
+| **Generate Strategies** | Provide 2-4 resolution options per conflict |
+| **CLI Analysis** | Use Gemini/Qwen (Claude fallback) |
+| **User Decision** | Present options, never auto-apply |
+| **Single Output** | `CONFLICT_RESOLUTION.md` with findings |
+
+## Conflict Categories
+
+### 1. Architecture Conflicts
+- Incompatible design patterns
+- Module structure changes
+- Pattern migration requirements
+
+### 2. API Conflicts
+- Breaking contract changes
+- Signature modifications
+- Public interface impacts
+
+### 3. Data Model Conflicts
+- Schema modifications
+- Type breaking changes
+- Data migration needs
+
+### 4. Dependency Conflicts
+- Version incompatibilities
+- Setup conflicts
+- Breaking updates
+
+## Execution Flow
+
+### Phase 1: Validation
+```
+1. Verify session directory exists
+2. Load context-package.json
+3. Check conflict_risk (skip if none/low)
+4. Prepare agent task prompt
+```
+
+### Phase 2: CLI-Powered Analysis
+
+**Agent Delegation**:
+```javascript
+Task(subagent_type="cli-execution-agent", prompt=`
+  ## Context
+  - Session: {session_id}
+  - Risk: {conflict_risk}
+  - Files: {existing_files_list}
+
+  ## Analysis Steps
+
+  ### 1. Load Context
+  - Read existing files from conflict_detection.existing_files
+  - Load plan from .workflow/{session_id}/.process/context-package.json
+  - Extract role analyses and requirements
+
+  ### 2. Execute CLI Analysis
+
+  Primary (Gemini):
+  cd {project_root} && gemini -p "
+  PURPOSE: Detect conflicts between plan and codebase
+  TASK:
+  • Compare architectures
+  • Identify breaking API changes
+  • Detect data model incompatibilities
+  • Assess dependency conflicts
+  MODE: analysis
+  CONTEXT: @{existing_files} @.workflow/{session_id}/**/*
+  EXPECTED: Conflict list with severity ratings
+  RULES: Focus on breaking changes and migration needs
+  "
+
+  Fallback: Qwen (same prompt) → Claude (manual analysis)
+
+  ### 3. Generate Strategies (2-4 per conflict)
+
+  Template per conflict:
+  - Severity: Critical/High/Medium
+  - Category: Architecture/API/Data/Dependency
+  - Affected files + impact
+  - Options with pros/cons, effort, risk
+  - Recommended strategy + rationale
+
+  ### 4. Return Structured Conflict Data
+
+  ⚠️ DO NOT generate CONFLICT_RESOLUTION.md file
+
+  Return JSON format for programmatic processing:
+
+  \`\`\`json
+  {
+    "conflicts": [
+      {
+        "id": "CON-001",
+        "brief": "一行中文冲突摘要",
+        "severity": "Critical|High|Medium",
+        "category": "Architecture|API|Data|Dependency",
+        "affected_files": [
+          ".workflow/{session}/.brainstorm/guidance-specification.md",
+          ".workflow/{session}/.brainstorm/system-architect/analysis.md"
+        ],
+        "description": "详细描述冲突 - 什么不兼容",
+        "impact": {
+          "scope": "影响的模块/组件",
+          "compatibility": "Yes|No|Partial",
+          "migration_required": true|false,
+          "estimated_effort": "人天估计"
+        },
+        "strategies": [
+          {
+            "name": "策略名称（中文）",
+            "approach": "实现方法简述",
+            "complexity": "Low|Medium|High",
+            "risk": "Low|Medium|High",
+            "effort": "时间估计",
+            "pros": ["优点1", "优点2"],
+            "cons": ["缺点1", "缺点2"],
+            "modifications": [
+              {
+                "file": ".workflow/{session}/.brainstorm/guidance-specification.md",
+                "section": "## 2. System Architect Decisions",
+                "change_type": "update",
+                "old_content": "原始内容片段（用于定位）",
+                "new_content": "修改后的内容",
+                "rationale": "为什么这样改"
+              },
+              {
+                "file": ".workflow/{session}/.brainstorm/system-architect/analysis.md",
+                "section": "## Design Decisions",
+                "change_type": "update",
+                "old_content": "原始内容片段",
+                "new_content": "修改后的内容",
+                "rationale": "修改理由"
+              }
+            ]
+          },
+          {
+            "name": "策略2名称",
+            "approach": "...",
+            "complexity": "Medium",
+            "risk": "Low",
+            "effort": "1-2天",
+            "pros": ["优点"],
+            "cons": ["缺点"],
+            "modifications": [...]
+          }
+        ],
+        "recommended": 0,
+        "modification_suggestions": [
+          "建议1：具体的修改方向或注意事项",
+          "建议2：可能需要考虑的边界情况",
+          "建议3：相关的最佳实践或模式"
+        ]
+      }
+    ],
+    "summary": {
+      "total": 2,
+      "critical": 1,
+      "high": 1,
+      "medium": 0
+    }
+  }
+  \`\`\`
+
+  ⚠️ CRITICAL Requirements for modifications field:
+  - old_content: Must be exact text from target file (20-100 chars for unique match)
+  - new_content: Complete replacement text (maintains formatting)
+  - change_type: "update" (replace), "add" (insert), "remove" (delete)
+  - file: Full path relative to project root
+  - section: Markdown heading for context (helps locate position)
+  - Minimum 2 strategies per conflict, max 4
+  - All text in Chinese for user-facing fields (brief, name, pros, cons)
+  - modification_suggestions: 2-5 actionable suggestions for custom handling (Chinese)
+
+  Quality Standards:
+  - Each strategy must have actionable modifications
+  - old_content must be precise enough for Edit tool matching
+  - new_content preserves markdown formatting and structure
+  - Recommended strategy (index) based on lowest complexity + risk
+  - modification_suggestions must be specific, actionable, and context-aware
+  - Each suggestion should address a specific aspect (compatibility, migration, testing, etc.)
+`)
+```
+
+**Agent Internal Flow**:
+```
+1. Load context package
+2. Check conflict_risk (exit if none/low)
+3. Read existing files + plan artifacts
+4. Run CLI analysis (Gemini→Qwen→Claude)
+5. Parse conflict findings
+6. Generate 2-4 strategies per conflict with modifications
+7. Return JSON to stdout (NOT file write)
+8. Return execution log path
+```
+
+### Phase 3: User Confirmation via Text Interaction
+
+**Command parses agent JSON output and presents conflicts to user via text**:
+
+```javascript
+// 1. Parse agent JSON output
+const conflictData = JSON.parse(agentOutput);
+const conflicts = conflictData.conflicts; // No 4-conflict limit
+
+// 2. Format conflicts as text output (max 10 per round)
+const batchSize = 10;
+const batches = chunkArray(conflicts, batchSize);
+
+for (const [batchIdx, batch] of batches.entries()) {
+  const totalBatches = batches.length;
+
+  // Output batch header
+  console.log(`===== 冲突解决 (第 ${batchIdx + 1}/${totalBatches} 轮) =====\n`);
+
+  // Output each conflict in batch
+  batch.forEach((conflict, idx) => {
+    const questionNum = batchIdx * batchSize + idx + 1;
+    console.log(`【问题${questionNum} - ${conflict.category}】${conflict.id}: ${conflict.brief}`);
+
+    conflict.strategies.forEach((strategy, sIdx) => {
+      const optionLetter = String.fromCharCode(97 + sIdx); // a, b, c, ...
+      console.log(`${optionLetter}) ${strategy.name}`);
+      console.log(`   说明：${strategy.approach}`);
+      console.log(`   复杂度: ${strategy.complexity} | 风险: ${strategy.risk} | 工作量: ${strategy.effort}`);
+    });
+
+    // Add custom option
+    const customLetter = String.fromCharCode(97 + conflict.strategies.length);
+    console.log(`${customLetter}) 自定义修改`);
+    console.log(`   说明：根据修改建议自行处理，不应用预设策略`);
+
+    // Show modification suggestions
+    if (conflict.modification_suggestions && conflict.modification_suggestions.length > 0) {
+      console.log(`   修改建议：`);
+      conflict.modification_suggestions.forEach(suggestion => {
+        console.log(`   - ${suggestion}`);
+      });
+    }
+    console.log();
+  });
+
+  console.log(`请回答 (格式: 1a 2b 3c...)：`);
+
+  // Wait for user input
+  const userInput = await readUserInput();
+
+  // Parse answers
+  const answers = parseUserAnswers(userInput, batch);
+}
+
+// 3. Build selected strategies (exclude custom selections)
+const selectedStrategies = answers.filter(a => !a.isCustom).map(a => a.strategy);
+const customConflicts = answers.filter(a => a.isCustom).map(a => ({
+  id: a.conflict.id,
+  brief: a.conflict.brief,
+  suggestions: a.conflict.modification_suggestions
+}));
+```
+
+**Text Output Example**:
+```markdown
+===== 冲突解决 (第 1/1 轮) =====
+
+【问题1 - Architecture】CON-001: 现有认证系统与计划不兼容
+a) 渐进式迁移
+   说明：保留现有系统，逐步迁移到新方案
+   复杂度: Medium | 风险: Low | 工作量: 3-5天
+b) 完全重写
+   说明：废弃旧系统，从零实现新认证
+   复杂度: High | 风险: Medium | 工作量: 7-10天
+c) 自定义修改
+   说明：根据修改建议自行处理，不应用预设策略
+   修改建议：
+   - 评估现有认证系统的兼容性，考虑是否可以通过适配器模式桥接
+   - 检查JWT token格式和验证逻辑是否需要调整
+   - 确保用户会话管理与新架构保持一致
+
+【问题2 - Data】CON-002: 数据库 schema 冲突
+a) 添加迁移脚本
+   说明：创建数据库迁移脚本处理 schema 变更
+   复杂度: Low | 风险: Low | 工作量: 1-2天
+b) 自定义修改
+   说明：根据修改建议自行处理，不应用预设策略
+   修改建议：
+   - 检查现有表结构是否支持新增字段，避免破坏性变更
+   - 考虑使用数据库版本控制工具（如Flyway或Liquibase）
+   - 准备数据迁移和回滚策略
+
+请回答 (格式: 1a 2b)：
+```
+
+**User Input Examples**:
+- `1a 2a` → Conflict 1: 渐进式迁移, Conflict 2: 添加迁移脚本
+- `1b 2b` → Conflict 1: 完全重写, Conflict 2: 自定义修改
+- `1c 2c` → Both choose custom modification (user handles manually with suggestions)
+
+### Phase 4: Apply Modifications
+
+```javascript
+// 1. Extract modifications from selected strategies
+const modifications = [];
+selectedStrategies.forEach(strategy => {
+  if (strategy !== "skip") {
+    modifications.push(...strategy.modifications);
+  }
+});
+
+// 2. Apply each modification using Edit tool
+modifications.forEach(mod => {
+  if (mod.change_type === "update") {
+    Edit({
+      file_path: mod.file,
+      old_string: mod.old_content,
+      new_string: mod.new_content
+    });
+  }
+  // Handle "add" and "remove" similarly
+});
+
+// 3. Update context-package.json
+const contextPackage = JSON.parse(Read(contextPath));
+contextPackage.conflict_detection.conflict_risk = "resolved";
+contextPackage.conflict_detection.resolved_conflicts = conflicts.map(c => c.id);
+contextPackage.conflict_detection.resolved_at = new Date().toISOString();
+Write(contextPath, JSON.stringify(contextPackage, null, 2));
+
+// 4. Output custom conflict summary (if any)
+if (customConflicts.length > 0) {
+  console.log("\n===== 需要自定义处理的冲突 =====\n");
+  customConflicts.forEach(conflict => {
+    console.log(`【${conflict.id}】${conflict.brief}`);
+    console.log("修改建议：");
+    conflict.suggestions.forEach(suggestion => {
+      console.log(`  - ${suggestion}`);
+    });
+    console.log();
+  });
+}
+
+// 5. Return summary
+return {
+  resolved: modifications.length,
+  custom: customConflicts.length,
+  modified_files: [...new Set(modifications.map(m => m.file))],
+  custom_conflicts: customConflicts
+};
+```
+
+**Validation**:
+```
+✓ Agent returns valid JSON structure
+✓ Text output displays all conflicts (max 10 per round)
+✓ User selections captured correctly
+✓ Edit tool successfully applies modifications
+✓ guidance-specification.md updated
+✓ Role analyses (*.md) updated
+✓ context-package.json marked as resolved
+✓ Agent log saved to .workflow/{session_id}/.chat/
+```
+
+## Output Format: Agent JSON Response
+
+**Focus**: Structured conflict data with actionable modifications for programmatic processing.
+
+**Format**: JSON to stdout (NO file generation)
+
+**Structure**: Defined in Phase 2, Step 4 (agent prompt)
+
+### Key Requirements
+| Requirement | Details |
+|------------|---------|
+| **Conflict batching** | Max 10 conflicts per round (no total limit) |
+| **Strategy count** | 2-4 strategies per conflict |
+| **Modifications** | Each strategy includes file paths, old_content, new_content |
+| **User-facing text** | Chinese (brief, strategy names, pros/cons) |
+| **Technical fields** | English (severity, category, complexity, risk) |
+| **old_content precision** | 20-100 chars for unique Edit tool matching |
+| **File targets** | guidance-specification.md, role analyses (*.md) |
+
+## Error Handling
+
+### Recovery Strategy
+```
+1. Pre-check: Verify conflict_risk ≥ medium
+2. Monitor: Track agent via Task tool
+3. Validate: Parse agent JSON output
+4. Recover:
+   - Agent failure → check logs + report error
+   - Invalid JSON → retry once with Claude fallback
+   - CLI failure → fallback to Claude analysis
+   - Edit tool failure → report affected files + rollback option
+   - User cancels → mark as "unresolved", continue to task-generate
+5. Degrade: If all fail, generate minimal conflict report and skip modifications
+```
+
+### Rollback Handling
+```
+If Edit tool fails mid-application:
+1. Log all successfully applied modifications
+2. Output rollback option via text interaction
+3. If rollback selected: restore files from git or backups
+4. If continue: mark partial resolution in context-package.json
+```
+
+## Integration
+
+### Interface
+**Input**:
+- `--session` (required): WFS-{session-id}
+- `--context` (required): context-package.json path
+- Requires: `conflict_risk ≥ medium`
+
+**Output**:
+- Modified files:
+  - `.workflow/{session_id}/.brainstorm/guidance-specification.md`
+  - `.workflow/{session_id}/.brainstorm/{role}/analysis.md`
+  - `.workflow/{session_id}/.process/context-package.json` (conflict_risk → resolved)
+- NO report file generation
+
+**User Interaction**:
+- Text-based strategy selection (max 10 conflicts per round)
+- Each conflict: 2-4 strategy options + "自定义修改" option (with suggestions)
+
+### Success Criteria
+```
+✓ CLI analysis returns valid JSON structure
+✓ Conflicts presented in batches (max 10 per round)
+✓ Min 2 strategies per conflict with modifications
+✓ Each conflict includes 2-5 modification_suggestions
+✓ Text output displays all conflicts correctly with suggestions
+✓ User selections captured and processed
+✓ Edit tool applies modifications successfully
+✓ Custom conflicts displayed with suggestions for manual handling
+✓ guidance-specification.md updated with resolved conflicts
+✓ Role analyses (*.md) updated with resolved conflicts
+✓ context-package.json marked as "resolved"
+✓ No CONFLICT_RESOLUTION.md file generated
+✓ Modification summary includes custom conflict count
+✓ Agent log saved to .workflow/{session_id}/.chat/
+✓ Error handling robust (validate/retry/degrade)
+```
+
+## Related Commands
+| Command | Relationship |
+|---------|--------------|
+| `/workflow:tools:context-gather` | Generates input conflict_detection data |
+| `/workflow:plan` | Auto-triggers this when risk ≥ medium |
+| `/workflow:tools:task-generate` | Uses resolved conflicts from updated brainstorm files |
+| `/workflow:brainstorm:artifacts` | Generates guidance-specification.md (modified by this command) |

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

@@ -1,300 +1,282 @@
 ---
 name: gather
-description: Intelligently collect project context based on task description and package into standardized JSON
+description: Intelligently collect project context using context-search-agent based on task description and package into standardized JSON
 argument-hint: "--session WFS-session-id \"task description\""
 examples:
   - /workflow:tools:context-gather --session WFS-user-auth "Implement user authentication system"
   - /workflow:tools:context-gather --session WFS-payment "Refactor payment module API"
   - /workflow:tools:context-gather --session WFS-bugfix "Fix login validation error"
+allowed-tools: Task(*), Read(*), Glob(*)
 ---
 
 # Context Gather Command (/workflow:tools:context-gather)
 
 ## Overview
-Intelligent context collector that gathers relevant information from project codebase, documentation, and dependencies based on task descriptions, generating standardized context packages.
+
+Orchestrator command that invokes `context-search-agent` to gather comprehensive project context for implementation planning. Generates standardized `context-package.json` with codebase analysis, dependencies, and conflict detection.
+
+**Agent**: `context-search-agent` (`.claude/agents/context-search-agent.md`)
 
 ## Core Philosophy
-- **Intelligent Collection**: Auto-identify relevant resources based on keyword analysis
-- **Comprehensive Coverage**: Collect code, documentation, configurations, and dependencies
-- **Standardized Output**: Generate unified format context-package.json
-- **Efficient Execution**: Optimize collection strategies to avoid irrelevant information
 
-## Core Responsibilities
+- **Agent Delegation**: Delegate all discovery to `context-search-agent` for autonomous execution
-- **Keyword Extraction**: Extract core keywords from task descriptions
+- **Detection-First**: Check for existing context-package before executing
-- **Smart Documentation Loading**: Load relevant project documentation based on keywords
+- **Plan Mode**: Full comprehensive analysis (vs lightweight brainstorm mode)
-- **Code Structure Analysis**: Analyze project structure to locate relevant code files
+- **Standardized Output**: Generate `.workflow/{session}/.process/context-package.json`
-- **Dependency Discovery**: Identify tech stack and dependency relationships
-- **MCP Tools Integration**: Leverage code-index tools for enhanced collection
-- **Context Packaging**: Generate standardized JSON context packages
 
-## Execution Process
+## Execution Flow
 
-### Phase 1: Task Analysis
+### Step 1: Context-Package Detection
-1. **Keyword Extraction**
-   - Parse task description to extract core keywords
-   - Identify technical domain (auth, API, frontend, backend, etc.)
-   - Determine complexity level (simple, medium, complex)
 
-2. **Scope Determination**
+**Execute First** - Check if valid package already exists:
-   - Define collection scope based on keywords
-   - Identify potentially involved modules and components
-   - Set file type filters
 
-### Phase 2: Project Structure Exploration
+```javascript
-1. **Architecture Analysis**
+const contextPackagePath = `.workflow/${session_id}/.process/context-package.json`;
-   - Use `~/.claude/scripts/get_modules_by_depth.sh` for comprehensive project structure
-   - Analyze project layout and module organization
-   - Identify key directories and components
 
-2. **Code File Location**
+if (file_exists(contextPackagePath)) {
-   - Use MCP tools for precise search: `mcp__code-index__find_files()` and `mcp__code-index__search_code_advanced()`
+  const existing = Read(contextPackagePath);
-   - Search for relevant source code files based on keywords
-   - Locate implementation files, interfaces, and modules
 
-3. **Documentation Collection**
+  // Validate package belongs to current session
-   - Load CLAUDE.md and README.md
+  if (existing?.metadata?.session_id === session_id) {
-   - Load relevant documentation from .workflow/docs/ based on keywords
+    console.log("✅ Valid context-package found for session:", session_id);
-   - Collect configuration files (package.json, requirements.txt, etc.)
+    console.log("📊 Stats:", existing.statistics);
-
+    console.log("⚠️  Conflict Risk:", existing.conflict_detection.risk_level);
-### Phase 3: Intelligent Filtering & Association
+    return existing; // Skip execution, return existing
-1. **Relevance Scoring**
+  } else {
-   - Score based on keyword match degree
+    console.warn("⚠️ Invalid session_id in existing package, re-generating...");
-   - Score based on file path relevance
-   - Score based on code content relevance
-
-2. **Dependency Analysis**
-   - Analyze import/require statements
-   - Identify inter-module dependencies
-   - Determine core and optional dependencies
-
-### Phase 4: Context Packaging
-1. **Standardized Output**
-   - Generate context-package.json
-   - Organize resources by type and importance
-   - Add relevance descriptions and usage recommendations
-
-## Context Package Format
-
-Generated context package format:
-
-```json
-{
-  "metadata": {
-    "task_description": "Implement user authentication system",
-    "timestamp": "2025-09-29T10:30:00Z",
-    "keywords": ["user", "authentication", "JWT", "login"],
-    "complexity": "medium",
-    "tech_stack": ["typescript", "node.js", "express"],
-    "session_id": "WFS-user-auth"
-  },
-  "assets": [
-    {
-      "type": "documentation",
-      "path": "CLAUDE.md",
-      "relevance": "Project development standards and conventions",
-      "priority": "high"
-    },
-    {
-      "type": "documentation",
-      "path": ".workflow/docs/architecture/security.md",
-      "relevance": "Security architecture design guidance",
-      "priority": "high"
-    },
-    {
-      "type": "source_code",
-      "path": "src/auth/AuthService.ts",
-      "relevance": "Existing authentication service implementation",
-      "priority": "high"
-    },
-    {
-      "type": "source_code",
-      "path": "src/models/User.ts",
-      "relevance": "User data model definition",
-      "priority": "medium"
-    },
-    {
-      "type": "config",
-      "path": "package.json",
-      "relevance": "Project dependencies and tech stack",
-      "priority": "medium"
-    },
-    {
-      "type": "test",
-      "path": "tests/auth/*.test.ts",
-      "relevance": "Authentication related test cases",
-      "priority": "medium"
-    }
-  ],
-  "tech_stack": {
-    "frameworks": ["express", "typescript"],
-    "libraries": ["jsonwebtoken", "bcrypt"],
-    "testing": ["jest", "supertest"]
-  },
-  "statistics": {
-    "total_files": 15,
-    "source_files": 8,
-    "docs_files": 4,
-    "config_files": 2,
-    "test_files": 1
   }
 }
 ```
 
-## MCP Tools Integration
+### Step 2: Invoke Context-Search Agent
 
-### Code Index Integration
+**Only execute if Step 1 finds no valid package**
-```bash
-# Set project path
-mcp__code-index__set_project_path(path="{current_project_path}")
 
-# Refresh index to ensure latest
+```javascript
-mcp__code-index__refresh_index()
+Task(
+  subagent_type="context-search-agent",
+  description="Gather comprehensive context for plan",
+  prompt=`
+You are executing as context-search-agent (.claude/agents/context-search-agent.md).
 
-# Search relevant files
+## Execution Mode
-mcp__code-index__find_files(pattern="*{keyword}*")
+**PLAN MODE** (Comprehensive) - Full Phase 1-3 execution
 
-# Search code content
+## Session Information
-mcp__code-index__search_code_advanced(
+- **Session ID**: ${session_id}
-  pattern="{keyword_patterns}",
+- **Task Description**: ${task_description}
-  file_pattern="*.{ts,js,py,go,md}",
+- **Output Path**: .workflow/${session_id}/.process/context-package.json
-  context_lines=3
+
+## Mission
+Execute complete context-search-agent workflow for implementation planning:
+
+### Phase 1: Initialization & Pre-Analysis
+1. **Detection**: Check for existing context-package (early exit if valid)
+2. **Foundation**: Initialize code-index, get project structure, load docs
+3. **Analysis**: Extract keywords, determine scope, classify complexity
+
+### Phase 2: Multi-Source Context Discovery
+Execute all 4 discovery tracks:
+- **Track 1**: Historical archive analysis (query manifest.json for lessons learned)
+- **Track 2**: Reference documentation (CLAUDE.md, architecture docs)
+- **Track 3**: Web examples (use Exa MCP for unfamiliar tech/APIs)
+- **Track 4**: Codebase analysis (5-layer discovery: files, content, patterns, deps, config/tests)
+
+### Phase 3: Synthesis, Assessment & Packaging
+1. Apply relevance scoring and build dependency graph
+2. Synthesize 4-source data (archive > docs > code > web)
+3. Integrate brainstorm artifacts (if .brainstorming/ exists, read content)
+4. Perform conflict detection with risk assessment
+5. **Inject historical conflicts** from archive analysis into conflict_detection
+6. Generate and validate context-package.json
+
+## Output Requirements
+Complete context-package.json with:
+- **metadata**: task_description, keywords, complexity, tech_stack, session_id
+- **project_context**: architecture_patterns, coding_conventions, tech_stack
+- **assets**: {documentation[], source_code[], config[], tests[]} with relevance scores
+- **dependencies**: {internal[], external[]} with dependency graph
+- **brainstorm_artifacts**: {guidance_specification, role_analyses[], synthesis_output} with content
+- **conflict_detection**: {risk_level, risk_factors, affected_modules[], mitigation_strategy, historical_conflicts[]}
+
+## Quality Validation
+Before completion verify:
+- [ ] Valid JSON format with all required fields
+- [ ] File relevance accuracy >80%
+- [ ] Dependency graph complete (max 2 transitive levels)
+- [ ] Conflict risk level calculated correctly
+- [ ] No sensitive data exposed
+- [ ] Total files ≤50 (prioritize high-relevance)
+
+Execute autonomously following agent documentation.
+Report completion with statistics.
+`
 )
 ```
 
+### Step 3: Output Verification
 
-## Session ID Integration
+After agent completes, verify output:
 
-### Session ID Usage
+```javascript
-- **Required Parameter**: `--session WFS-session-id`
+// Verify file was created
-- **Session Context Loading**: Load existing session state and task summaries
+const outputPath = `.workflow/${session_id}/.process/context-package.json`;
-- **Session Continuity**: Maintain context across pipeline phases
+if (!file_exists(outputPath)) {
+  throw new Error("❌ Agent failed to generate context-package.json");
+}
+```
 
-### Session State Management
+## Parameter Reference
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `--session` | string | ✅ | Workflow session ID (e.g., WFS-user-auth) |
+| `task_description` | string | ✅ | Detailed task description for context extraction |
+
+## Output Schema
+
+Refer to `context-search-agent.md` Phase 3.7 for complete `context-package.json` schema.
+
+**Key Sections**:
+- **metadata**: Session info, keywords, complexity, tech stack
+- **project_context**: Architecture patterns, conventions, tech stack
+- **assets**: Categorized files with relevance scores (documentation, source_code, config, tests)
+- **dependencies**: Internal and external dependency graphs
+- **brainstorm_artifacts**: Brainstorm documents with full content (if exists)
+- **conflict_detection**: Risk assessment with mitigation strategies and historical conflicts
+
+## Historical Archive Analysis
+
+### Track 1: Query Archive Manifest
+
+The context-search-agent MUST perform historical archive analysis as Track 1 in Phase 2:
+
+**Step 1: Check for Archive Manifest**
 ```bash
-# Validate session exists
+# Check if archive manifest exists
-if [ ! -d ".workflow/${session_id}" ]; then
+if [[ -f .workflow/.archives/manifest.json ]]; then
-  echo "❌ Session ${session_id} not found"
+  # Manifest available for querying
-  exit 1
 fi
-
-# Load session metadata
-session_metadata=".workflow/${session_id}/workflow-session.json"
 ```
 
-## Output Location
+**Step 2: Extract Task Keywords**
+```javascript
+// From current task description, extract key entities and operations
+const keywords = extractKeywords(task_description);
+// Examples: ["User", "model", "authentication", "JWT", "reporting"]
+```
 
-Context package output location:
+**Step 3: Search Archive for Relevant Sessions**
+```javascript
+// Query manifest for sessions with matching tags or descriptions
+const relevantArchives = archives.filter(archive => {
+  return archive.tags.some(tag => keywords.includes(tag)) ||
+         keywords.some(kw => archive.description.toLowerCase().includes(kw.toLowerCase()));
+});
 ```
-.workflow/{session_id}/.process/context-package.json
+
+**Step 4: Extract Watch Patterns**
+```javascript
+// For each relevant archive, check watch_patterns for applicability
+const historicalConflicts = [];
+
+relevantArchives.forEach(archive => {
+  archive.lessons.watch_patterns?.forEach(pattern => {
+    // Check if pattern trigger matches current task
+    if (isPatternRelevant(pattern.pattern, task_description)) {
+      historicalConflicts.push({
+        source_session: archive.session_id,
+        pattern: pattern.pattern,
+        action: pattern.action,
+        files_to_check: pattern.related_files,
+        archived_at: archive.archived_at
+      });
+    }
+  });
+});
 ```
 
+**Step 5: Inject into Context Package**
+```json
+{
+  "conflict_detection": {
+    "risk_level": "medium",
+    "risk_factors": ["..."],
+    "affected_modules": ["..."],
+    "mitigation_strategy": "...",
+    "historical_conflicts": [
+      {
+        "source_session": "WFS-auth-feature",
+        "pattern": "When modifying User model",
+        "action": "Check reporting-service and auditing-service dependencies",
+        "files_to_check": ["src/models/User.ts", "src/services/reporting.ts"],
+        "archived_at": "2025-09-16T09:00:00Z"
+      }
+    ]
+  }
+}
+```
+
+### Risk Level Escalation
+
+If `historical_conflicts` array is not empty, minimum risk level should be "medium":
+
+```javascript
+if (historicalConflicts.length > 0 && currentRisk === "low") {
+  conflict_detection.risk_level = "medium";
+  conflict_detection.risk_factors.push(
+    `${historicalConflicts.length} historical conflict pattern(s) detected from past sessions`
+  );
+}
+```
+
+### Archive Query Algorithm
+
+```markdown
+1. IF .workflow/.archives/manifest.json does NOT exist → Skip Track 1, continue to Track 2
+2. IF manifest exists:
+   a. Load manifest.json
+   b. Extract keywords from task_description (nouns, verbs, technical terms)
+   c. Filter archives where:
+      - ANY tag matches keywords (case-insensitive) OR
+      - description contains keywords (case-insensitive substring match)
+   d. For each relevant archive:
+      - Read lessons.watch_patterns array
+      - Check if pattern.pattern keywords overlap with task_description
+      - If relevant: Add to historical_conflicts array
+   e. IF historical_conflicts.length > 0:
+      - Set risk_level = max(current_risk, "medium")
+      - Add to risk_factors
+3. Continue to Track 2 (reference documentation)
+```
+
+## Usage Examples
+
+### Basic Usage
+```bash
+/workflow:tools:context-gather --session WFS-auth-feature "Implement JWT authentication with refresh tokens"
+```
+## Success Criteria
+
+- ✅ Valid context-package.json generated in `.workflow/{session}/.process/`
+- ✅ Contains >80% relevant files based on task keywords
+- ✅ Execution completes within 2 minutes
+- ✅ All required schema fields present and valid
+- ✅ Conflict risk accurately assessed
+- ✅ Agent reports completion with statistics
+
 ## Error Handling
 
-### Common Error Handling
+| Error | Cause | Resolution |
-1. **No Active Session**: Create temporary session directory
+|-------|-------|------------|
-2. **MCP Tools Unavailable**: Fallback to traditional bash commands
+| Package validation failed | Invalid session_id in existing package | Re-run agent to regenerate |
-3. **Permission Errors**: Prompt user to check file permissions
+| Agent execution timeout | Large codebase or slow MCP | Increase timeout, check code-index status |
-4. **Large Project Optimization**: Limit file count, prioritize high-relevance files
+| Missing required fields | Agent incomplete execution | Check agent logs, verify schema compliance |
+| File count exceeds limit | Too many relevant files | Agent should auto-prioritize top 50 by relevance |
 
-### Graceful Degradation Strategy
+## Notes
-```bash
-# Fallback when MCP unavailable
-if ! command -v mcp__code-index__find_files; then
-  # Use find command for file discovery
-  find . -name "*{keyword}*" -type f -not -path "*/node_modules/*" -not -path "*/.git/*"
 
-  # Alternative pattern matching
+- **Detection-first**: Always check for existing package before invoking agent
-  find . -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.go" \) -exec grep -l "{keyword}" {} \;
+- **Agent autonomy**: Agent handles all discovery logic per `.claude/agents/context-search-agent.md`
-fi
+- **No redundancy**: This command is a thin orchestrator, all logic in agent
-
+- **Plan-specific**: Use this for implementation planning; brainstorm mode uses direct agent call
-# Use ripgrep instead of MCP search
-rg "{keywords}" --type-add 'source:*.{ts,js,py,go}' -t source --max-count 30
-
-# Content-based search with context
-rg -A 3 -B 3 "{keywords}" --type-add 'source:*.{ts,js,py,go}' -t source
-
-# Quick relevance check
-grep -r --include="*.{ts,js,py,go}" -l "{keywords}" . | head -15
-
-# Test files discovery
-find . -name "*test*" -o -name "*spec*" | grep -E "\.(ts|js|py|go)$" | head -10
-
-# Import/dependency analysis
-rg "^(import|from|require|#include)" --type-add 'source:*.{ts,js,py,go}' -t source | head -20
-```
-
-## Performance Optimization
-
-### Large Project Optimization Strategy
-- **File Count Limit**: Maximum 50 files per type
-- **Size Filtering**: Skip oversized files (>10MB)
-- **Depth Limit**: Maximum search depth of 3 levels
-- **Caching Strategy**: Cache project structure analysis results
-
-### Parallel Processing
-- Documentation collection and code search in parallel
-- MCP tool calls and traditional commands in parallel
-- Reduce I/O wait time
-
-## Essential Bash Commands (Max 10)
-
-### 1. Project Structure Analysis
-```bash
-~/.claude/scripts/get_modules_by_depth.sh
-```
-
-### 2. File Discovery by Keywords
-```bash
-find . -name "*{keyword}*" -type f -not -path "*/node_modules/*" -not -path "*/.git/*"
-```
-
-### 3. Content Search in Code Files
-```bash
-rg "{keyword}" --type-add 'source:*.{ts,js,py,go}' -t source --max-count 20
-```
-
-### 4. Configuration Files Discovery
-```bash
-find . -maxdepth 3 \( -name "*.json" -o -name "package.json" -o -name "requirements.txt" -o -name "Cargo.toml" \) -not -path "*/node_modules/*"
-```
-
-### 5. Documentation Files Collection
-```bash
-find . -name "*.md" -o -name "README*" -o -name "CLAUDE.md" | grep -v node_modules | head -10
-```
-
-### 6. Test Files Location
-```bash
-find . \( -name "*test*" -o -name "*spec*" \) -type f | grep -E "\.(js|ts|py|go)$" | head -10
-```
-
-### 7. Function/Class Definitions Search
-```bash
-rg "^(function|def|func|class|interface)" --type-add 'source:*.{ts,js,py,go}' -t source -n --max-count 15
-```
-
-### 8. Import/Dependency Analysis
-```bash
-rg "^(import|from|require|#include)" --type-add 'source:*.{ts,js,py,go}' -t source | head -15
-```
-
-### 9. Workflow Session Information
-```bash
-find .workflow/ -name "*.json" -path "*/${session_id}/*" -o -name "workflow-session.json" | head -5
-```
-
-### 10. Context-Aware Content Search
-```bash
-rg -A 2 -B 2 "{keywords}" --type-add 'source:*.{ts,js,py,go}' -t source --max-count 10
-```
-
-## Success Criteria
-- Generate valid context-package.json file
-- Contains sufficient relevant information for subsequent analysis
-- Execution time controlled within 30 seconds
-- File relevance accuracy rate >80%
-
-## Related Commands
-- `/workflow:tools:concept-enhanced` - Consumes output of this command for analysis
-- `/workflow:plan` - Calls this command to gather context
-- `/workflow:status` - Can display context collection status

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

@@ -1,21 +1,25 @@
 ---
 name: task-generate-agent
 description: Autonomous task generation using action-planning-agent with discovery and output phases
-argument-hint: "--session WFS-session-id"
+argument-hint: "--session WFS-session-id [--cli-execute]"
 examples:
   - /workflow:tools:task-generate-agent --session WFS-auth
+  - /workflow:tools:task-generate-agent --session WFS-auth --cli-execute
 ---
 
 # Autonomous Task Generation Command
 
 ## Overview
-Autonomous task JSON and IMPL_PLAN.md generation using action-planning-agent with two-phase execution: discovery and document generation.
+Autonomous task JSON and IMPL_PLAN.md generation using action-planning-agent with two-phase execution: discovery and document generation. Supports both agent-driven execution (default) and CLI tool execution modes.
 
 ## Core Philosophy
 - **Agent-Driven**: Delegate execution to action-planning-agent for autonomous operation
 - **Two-Phase Flow**: Discovery (context gathering) → Output (document generation)
 - **Memory-First**: Reuse loaded documents from conversation memory
 - **MCP-Enhanced**: Use MCP tools for advanced code analysis and research
+- **Pre-Selected Templates**: Command selects correct template based on `--cli-execute` flag **before** invoking agent
+- **Agent Simplicity**: Agent receives pre-selected template and focuses only on content generation
+- **Path Clarity**: All `focus_paths` prefer absolute paths (e.g., `D:\\project\\src\\module`), or clear relative paths from project root (e.g., `./src/module`)
 
 ## Execution Lifecycle
 
@@ -26,21 +30,27 @@ Autonomous task JSON and IMPL_PLAN.md generation using action-planning-agent wit
 ```javascript
 {
   "session_id": "WFS-[session-id]",
+  "execution_mode": "agent-mode" | "cli-execute-mode",  // Determined by flag
+  "task_json_template_path": "~/.claude/workflows/cli-templates/prompts/workflow/task-json-agent-mode.txt"
+                           | "~/.claude/workflows/cli-templates/prompts/workflow/task-json-cli-mode.txt",
+  // Path selected by command based on --cli-execute flag, agent reads it
   "session_metadata": {
     // If in memory: use cached content
     // Else: Load from .workflow/{session-id}/workflow-session.json
   },
-  "analysis_results": {
+  "brainstorm_artifacts": {
-    // If in memory: use cached content
+    // Loaded from context-package.json → brainstorm_artifacts section
-    // Else: Load from .workflow/{session-id}/.process/ANALYSIS_RESULTS.md
+    "role_analyses": [
-  },
+      {
-  "artifacts_inventory": {
+        "role": "system-architect",
-    // If in memory: use cached list
+        "files": [{"path": "...", "type": "primary|supplementary"}]
-    // Else: Scan .workflow/{session-id}/.brainstorming/ directory
+      }
-    "synthesis_specification": "path or null",
+    ],
-    "topic_framework": "path or null",
+    "guidance_specification": {"path": "...", "exists": true},
-    "role_analyses": ["paths"]
+    "synthesis_output": {"path": "...", "exists": true},
+    "conflict_resolution": {"path": "...", "exists": true}  // if conflict_risk >= medium
   },
+  "context_package_path": ".workflow/{session-id}/.process/context-package.json",
   "context_package": {
     // If in memory: use cached content
     // Else: Load from .workflow/{session-id}/.process/context-package.json
@@ -61,31 +71,38 @@ Autonomous task JSON and IMPL_PLAN.md generation using action-planning-agent wit
    }
    ```
 
-2. **Load Analysis Results** (if not in memory)
+2. **Load Context Package** (if not in memory)
    ```javascript
-   if (!memory.has("ANALYSIS_RESULTS.md")) {
+   if (!memory.has("context-package.json")) {
-     Read(.workflow/{session-id}/.process/ANALYSIS_RESULTS.md)
+     Read(.workflow/{session-id}/.process/context-package.json)
    }
    ```
 
-3. **Discover Artifacts** (if not in memory)
+3. **Extract & Load Role Analyses** (from context-package.json)
    ```javascript
-   if (!memory.has("artifacts_inventory")) {
+   // Extract role analysis paths from context package
-     bash(find .workflow/{session-id}/.brainstorming/ -name "*.md" -type f)
+   const roleAnalysisPaths = contextPackage.brainstorm_artifacts.role_analyses
+     .flatMap(role => role.files.map(f => f.path));
+
+   // Load each role analysis file
+   roleAnalysisPaths.forEach(path => Read(path));
+   ```
+
+4. **Load Conflict Resolution** (from context-package.json, if exists)
+   ```javascript
+   if (contextPackage.brainstorm_artifacts.conflict_resolution?.exists) {
+     Read(contextPackage.brainstorm_artifacts.conflict_resolution.path)
    }
    ```
 
-4. **MCP Code Analysis** (optional - enhance understanding)
+5. **Code Analysis with Native Tools** (optional - enhance understanding)
-   ```javascript
+   ```bash
-   // Find relevant files for task context
+   # Find relevant files for task context
-   mcp__code-index__find_files(pattern="*auth*")
+   find . -name "*auth*" -type f
-   mcp__code-index__search_code_advanced(
+   rg "authentication|oauth" -g "*.ts"
-     pattern="authentication|oauth",
-     file_pattern="*.ts"
-   )
    ```
 
-5. **MCP External Research** (optional - gather best practices)
+6. **MCP External Research** (optional - gather best practices)
    ```javascript
    // Get external examples for implementation
    mcp__exa__get_code_context_exa(
@@ -96,6 +113,14 @@ Autonomous task JSON and IMPL_PLAN.md generation using action-planning-agent wit
 
 ### Phase 2: Agent Execution (Document Generation)
 
+**Pre-Agent Template Selection** (Command decides path before invoking agent):
+```javascript
+// Command checks flag and selects template PATH (not content)
+const templatePath = hasCliExecuteFlag
+  ? "~/.claude/workflows/cli-templates/prompts/workflow/task-json-cli-mode.txt"
+  : "~/.claude/workflows/cli-templates/prompts/workflow/task-json-agent-mode.txt";
+```
+
 **Agent Invocation**:
 ```javascript
 Task(
@@ -105,23 +130,32 @@ Task(
 ## Execution Context
 
 **Session ID**: WFS-{session-id}
-**Mode**: Two-Phase Autonomous Task Generation
+**Execution Mode**: {agent-mode | cli-execute-mode}
+**Task JSON Template Path**: {template_path}
 
 ## Phase 1: Discovery Results (Provided Context)
 
 ### Session Metadata
 {session_metadata_content}
 
-### Analysis Results
+### Role Analyses (Enhanced by Synthesis)
-{analysis_results_content}
+{role_analyses_content}
+- Includes requirements, design specs, enhancements, and clarifications from synthesis phase
 
 ### Artifacts Inventory
-- **Synthesis Specification**: {synthesis_spec_path}
+- **Guidance Specification**: {guidance_spec_path}
-- **Topic Framework**: {topic_framework_path}
 - **Role Analyses**: {role_analyses_list}
 
 ### Context Package
 {context_package_summary}
+- Includes conflict_risk assessment
+
+### Conflict Resolution (Conditional)
+If conflict_risk was medium/high, modifications have been applied to:
+- **guidance-specification.md**: Design decisions updated to resolve conflicts
+- **Role analyses (*.md)**: Recommendations adjusted for compatibility
+- **context-package.json**: Marked as "resolved" with conflict IDs
+- NO separate CONFLICT_RESOLUTION.md file (conflicts resolved in-place)
 
 ### MCP Analysis Results (Optional)
 **Code Structure**: {mcp_code_index_results}
@@ -147,334 +181,35 @@ Task(
 
 #### 1. Task JSON Files (.task/IMPL-*.json)
 **Location**: .workflow/{session-id}/.task/
-**Schema**: 5-field enhanced schema with artifacts
+**Template**: Read from the template path provided above
 
-**Required Fields**:
+**Task JSON Template Loading**:
-\`\`\`json
-{
-  "id": "IMPL-N[.M]",
-  "title": "Descriptive task name",
-  "status": "pending",
-  "meta": {
-    "type": "feature|bugfix|refactor|test|docs",
-    "agent": "@code-developer|@test-fix-agent|@general-purpose"
-  },
-  "context": {
-    "requirements": ["extracted from analysis"],
-    "focus_paths": ["src/paths"],
-    "acceptance": ["measurable criteria"],
-    "depends_on": ["IMPL-N"],
-    "artifacts": [
-      {
-        "type": "synthesis_specification",
-        "path": "{synthesis_spec_path}",
-        "priority": "highest",
-        "usage": "Primary requirement source - use for consolidated requirements and cross-role alignment"
-      },
-      {
-        "type": "role_analysis",
-        "path": "{role_analysis_path}",
-        "priority": "high",
-        "usage": "Technical/design/business details from specific roles. Common roles: system-architect (ADRs, APIs, caching), ui-designer (design tokens, layouts), product-manager (user stories, metrics)",
-        "note": "Dynamically discovered - multiple role analysis files included based on brainstorming results"
-      },
-      {
-        "type": "topic_framework",
-        "path": "{topic_framework_path}",
-        "priority": "low",
-        "usage": "Discussion context and framework structure"
-      }
-    ]
-  },
-  "flow_control": {
-    "pre_analysis": [
-      {
-        "step": "load_synthesis_specification",
-        "action": "Load consolidated synthesis specification",
-        "commands": [
-          "bash(ls {synthesis_spec_path} 2>/dev/null || echo 'not found')",
-          "Read({synthesis_spec_path})"
-        ],
-        "output_to": "synthesis_specification",
-        "on_error": "skip_optional"
-      },
-      {
-        "step": "mcp_codebase_exploration",
-        "action": "Explore codebase using MCP",
-        "command": "mcp__code-index__find_files(pattern=\\"[patterns]\\") && mcp__code-index__search_code_advanced(pattern=\\"[patterns]\\")",
-        "output_to": "codebase_structure"
-      },
-      {
-        "step": "analyze_task_patterns",
-        "action": "Analyze existing code patterns",
-        "commands": [
-          "bash(cd \\"[focus_paths]\\")",
-          "bash(~/.claude/scripts/gemini-wrapper -p \\"PURPOSE: Analyze patterns TASK: Review '[title]' CONTEXT: [synthesis_specification] EXPECTED: Pattern analysis RULES: Prioritize synthesis-specification.md\\")"
-        ],
-        "output_to": "task_context",
-        "on_error": "fail"
-      }
-    ],
-    "implementation_approach": [
-      {
-        "step": 1,
-        "title": "Implement task following synthesis specification",
-        "description": "Implement '[title]' following synthesis specification. PRIORITY: Use synthesis-specification.md as primary requirement source. When implementation needs technical details (e.g., API schemas, caching configs, design tokens), refer to artifacts[] for detailed specifications from original role analyses.",
-        "modification_points": [
-          "Apply consolidated requirements from synthesis-specification.md",
-          "Follow technical guidelines from synthesis",
-          "Consult artifacts for implementation details when needed",
-          "Integrate with existing patterns"
-        ],
-        "logic_flow": [
-          "Load synthesis specification and relevant role artifacts",
-          "Execute MCP code-index discovery for relevant files",
-          "Analyze existing patterns and identify modification targets",
-          "Implement following specification",
-          "Consult artifacts for technical details when needed",
-          "Validate against acceptance criteria"
-        ],
-        "depends_on": [],
-        "output": "implementation"
-      }
-    ],
-    "target_files": ["file:function:lines", "path/to/NewFile.ts"]
-  }
-}
 \`\`\`
+Read({template_path})
+\`\`\`
+
+**Important**:
+- Read the template from the path provided in context
+- Use the template structure exactly as written
+- Replace placeholder variables ({synthesis_spec_path}, {role_analysis_path}, etc.) with actual session-specific paths
+- Include MCP tool integration in pre_analysis steps
+- Map artifacts based on task domain (UI → ui-designer, Backend → system-architect)
 
 #### 2. IMPL_PLAN.md
 **Location**: .workflow/{session-id}/IMPL_PLAN.md
-**Structure**:
-\`\`\`markdown
----
-identifier: WFS-{session-id}
-source: "User requirements" | "File: path" | "Issue: ISS-001"
-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: "standard | tdd | design"  # Indicates execution model
-verification_history:  # CCW quality gates
-  concept_verify: "passed | skipped | pending"
-  action_plan_verify: "pending"
-phase_progression: "brainstorm → context → analysis → concept_verify → planning"  # CCW workflow phases
----
 
-# Implementation Plan: {Project Title}
+**IMPL_PLAN Template**:
-
-## 1. Summary
-Core requirements, objectives, technical approach summary (2-3 paragraphs max).
-
-**Core Objectives**:
-- [Key objective 1]
-- [Key objective 2]
-
-**Technical Approach**:
-- [High-level approach]
-
-## 2. Context Analysis
-
-### CCW Workflow Context
-**Phase Progression**:
-- ✅ Phase 1: Brainstorming (synthesis-specification.md generated)
-- ✅ Phase 2: Context Gathering (context-package.json: {N} files, {M} modules analyzed)
-- ✅ Phase 3: Enhanced Analysis (ANALYSIS_RESULTS.md: Gemini/Qwen/Codex parallel insights)
-- ✅ Phase 4: Concept Verification ({X} clarifications answered, synthesis updated | skipped)
-- ⏳ Phase 5: Action Planning (current phase - generating IMPL_PLAN.md)
-
-**Quality Gates**:
-- concept-verify: ✅ Passed (0 ambiguities remaining) | ⏭️ Skipped (user decision) | ⏳ Pending
-- action-plan-verify: ⏳ Pending (recommended before /workflow:execute)
-
-**Context Package Summary**:
-- **Focus Paths**: {list key directories from context-package.json}
-- **Key Files**: {list primary files for modification}
-- **Module Depth Analysis**: {from get_modules_by_depth.sh output}
-- **Smart Context**: {total file count} files, {module count} modules, {dependency count} dependencies identified
-
-### Project Profile
-- **Type**: Greenfield/Enhancement/Refactor
-- **Scale**: User count, data volume, complexity
-- **Tech Stack**: Primary technologies
-- **Timeline**: Duration and milestones
-
-### Module Structure
 \`\`\`
-[Directory tree showing key modules]
+$(cat ~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt)
 \`\`\`
 
-### Dependencies
+**Important**:
-**Primary**: [Core libraries and frameworks]
+- Use the template above for IMPL_PLAN.md generation
-**APIs**: [External services]
+- Replace all {placeholder} variables with actual session-specific values
-**Development**: [Testing, linting, CI/CD tools]
+- Populate CCW Workflow Context based on actual phase progression
-
+- Extract content from role analyses and context-package.json
-### Patterns & Conventions
+- List all detected brainstorming artifacts with correct paths (role analyses, guidance-specification.md)
-- **Architecture**: [Key patterns like DI, Event-Driven]
+- Include conflict resolution status if CONFLICT_RESOLUTION.md exists
-- **Component Design**: [Design patterns]
-- **State Management**: [State strategy]
-- **Code Style**: [Naming, TypeScript coverage]
-
-## 3. Brainstorming Artifacts Reference
-
-### Artifact Usage Strategy
-**Primary Reference (synthesis-specification.md)**:
-- **What**: Comprehensive implementation blueprint from multi-role synthesis
-- **When**: Every task references this first for requirements and design decisions
-- **How**: Extract architecture decisions, UI/UX patterns, functional requirements, non-functional requirements
-- **Priority**: Authoritative - overrides role-specific analyses when conflicts arise
-- **CCW Value**: Consolidates insights from all brainstorming roles into single source of truth
-
-**Context Intelligence (context-package.json)**:
-- **What**: Smart context gathered by CCW's context-gather phase
-- **Content**: Focus paths, dependency graph, existing patterns, module structure
-- **Usage**: Tasks load this via \`flow_control.preparatory_steps\` for environment setup
-- **CCW Value**: Automated intelligent context discovery replacing manual file exploration
-
-**Technical Analysis (ANALYSIS_RESULTS.md)**:
-- **What**: Gemini/Qwen/Codex parallel analysis results
-- **Content**: Optimization strategies, risk assessment, architecture review, implementation patterns
-- **Usage**: Referenced in task planning for technical guidance and risk mitigation
-- **CCW Value**: Multi-model parallel analysis providing comprehensive technical intelligence
-
-### Integrated Specifications (Highest Priority)
-- **synthesis-specification.md**: Comprehensive implementation blueprint
-  - Contains: Architecture design, UI/UX guidelines, functional/non-functional requirements, implementation roadmap, risk assessment
-
-### Supporting Artifacts (Reference)
-- **topic-framework.md**: Role-specific discussion points and analysis framework
-- **system-architect/analysis.md**: Detailed architecture specifications
-- **ui-designer/analysis.md**: Layout and component specifications
-- **product-manager/analysis.md**: Product vision and user stories
-
-**Artifact Priority in Development**:
-1. synthesis-specification.md (primary reference for all tasks)
-2. context-package.json (smart context for execution environment)
-3. ANALYSIS_RESULTS.md (technical analysis and optimization strategies)
-4. Role-specific analyses (fallback for detailed specifications)
-
-## 4. Implementation Strategy
-
-### Execution Strategy
-**Execution Model**: [Sequential | Parallel | Phased | TDD Cycles]
-
-**Rationale**: [Why this execution model fits the project]
-
-**Parallelization Opportunities**:
-- [List independent workstreams]
-
-**Serialization Requirements**:
-- [List critical dependencies]
-
-### Architectural Approach
-**Key Architecture Decisions**:
-- [ADR references from synthesis]
-- [Justification for architecture patterns]
-
-**Integration Strategy**:
-- [How modules communicate]
-- [State management approach]
-
-### Key Dependencies
-**Task Dependency Graph**:
-\`\`\`
-[High-level dependency visualization]
-\`\`\`
-
-**Critical Path**: [Identify bottleneck tasks]
-
-### Testing Strategy
-**Testing Approach**:
-- Unit testing: [Tools, scope]
-- Integration testing: [Key integration points]
-- E2E testing: [Critical user flows]
-
-**Coverage Targets**:
-- Lines: ≥70%
-- Functions: ≥70%
-- Branches: ≥65%
-
-**Quality Gates**:
-- [CI/CD gates]
-- [Performance budgets]
-
-## 5. Task Breakdown Summary
-
-### Task Count
-**{N} tasks** (flat hierarchy | two-level hierarchy, sequential | parallel execution)
-
-### Task Structure
-- **IMPL-1**: [Main task title]
-- **IMPL-2**: [Main task title]
-...
-
-### Complexity Assessment
-- **High**: [List with rationale]
-- **Medium**: [List]
-- **Low**: [List]
-
-### Dependencies
-[Reference Section 4.3 for dependency graph]
-
-**Parallelization Opportunities**:
-- [Specific task groups that can run in parallel]
-
-## 6. Implementation Plan (Detailed Phased Breakdown)
-
-### Execution Strategy
-
-**Phase 1 (Weeks 1-2): [Phase Name]**
-- **Tasks**: IMPL-1, IMPL-2
-- **Deliverables**:
-  - [Specific deliverable 1]
-  - [Specific deliverable 2]
-- **Success Criteria**:
-  - [Measurable criterion]
-
-**Phase 2 (Weeks 3-N): [Phase Name]**
-...
-
-### Resource Requirements
-
-**Development Team**:
-- [Team composition and skills]
-
-**External Dependencies**:
-- [Third-party services, APIs]
-
-**Infrastructure**:
-- [Development, staging, production environments]
-
-## 7. Risk Assessment & Mitigation
-
-| Risk | Impact | Probability | Mitigation Strategy | Owner |
-|------|--------|-------------|---------------------|-------|
-| [Risk description] | High/Med/Low | High/Med/Low | [Strategy] | [Role] |
-
-**Critical Risks** (High impact + High probability):
-- [Risk 1]: [Detailed mitigation plan]
-
-**Monitoring Strategy**:
-- [How risks will be monitored]
-
-## 8. Success Criteria
-
-**Functional Completeness**:
-- [ ] All requirements from synthesis-specification.md implemented
-- [ ] All acceptance criteria from task.json files met
-
-**Technical Quality**:
-- [ ] Test coverage ≥70%
-- [ ] Bundle size within budget
-- [ ] Performance targets met
-
-**Operational Readiness**:
-- [ ] CI/CD pipeline operational
-- [ ] Monitoring and logging configured
-- [ ] Documentation complete
-
-**Business Metrics**:
-- [ ] [Key business metrics from synthesis]
-\`\`\`
 
 #### 3. TODO_LIST.md
 **Location**: .workflow/{session-id}/TODO_LIST.md
@@ -495,52 +230,58 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 - \`- [x]\` = Completed leaf task
 \`\`\`
 
-### Execution Instructions
+### Execution Instructions for Agent
 
-**Step 1: Extract Task Definitions**
+**Agent Task**: Generate task JSON files, IMPL_PLAN.md, and TODO_LIST.md based on analysis results
-- Parse analysis results for task recommendations
-- Extract task ID, title, requirements, complexity
-- Map artifacts to relevant tasks based on type
 
-**Step 2: Generate Task JSON Files**
+**Note**: The correct task JSON template path has been pre-selected by the command based on the `--cli-execute` flag and is provided in the context as `{template_path}`.
-- Create individual .task/IMPL-*.json files
-- Embed artifacts array with detected brainstorming outputs
-- Generate flow_control with artifact loading steps
-- Add MCP tool integration for codebase exploration
 
-**Step 3: Create IMPL_PLAN.md**
+**Step 1: Load Task JSON Template**
-- Summarize requirements and technical approach
+- Read template from the provided path: `Read({template_path})`
-- List detected artifacts with priorities
+- This template is already the correct one based on execution mode
-- Document task breakdown and dependencies
-- Define execution strategy and success criteria
 
-**Step 4: Generate TODO_LIST.md**
+**Step 2: Extract and Decompose Tasks**
-- List all tasks with container/leaf structure
+- Parse role analysis.md files for requirements, design specs, and task recommendations
-- Link to task JSON files
+- Review synthesis enhancements and clarifications in role analyses
+- Apply conflict resolution strategies (if CONFLICT_RESOLUTION.md exists)
+- Apply task merging rules (merge when possible, decompose only when necessary)
+- Map artifacts to tasks based on domain (UI → ui-designer, Backend → system-architect, Data → data-architect)
+- Ensure task count ≤10
+
+**Step 3: Generate Task JSON Files**
+- Use the template structure from Step 1
+- Create .task/IMPL-*.json files with proper structure
+- Replace all {placeholder} variables with actual session paths
+- Embed artifacts array with brainstorming outputs
+- Include MCP tool integration in pre_analysis steps
+
+**Step 4: Create IMPL_PLAN.md**
+- Use IMPL_PLAN template
+- Populate all sections with session-specific content
+- List artifacts with priorities and usage guidelines
+- Document execution strategy and dependencies
+
+**Step 5: Generate TODO_LIST.md**
+- Create task progress checklist matching generated JSONs
 - Use proper status indicators (▸, [ ], [x])
+- Link to task JSON files
 
-**Step 5: Update Session State**
+**Step 6: Update Session State**
-- Update .workflow/{session-id}/workflow-session.json
+- Update workflow-session.json with task count and artifact inventory
-- Mark session as ready for execution
+- Mark session ready for execution
-- Record task count and artifact inventory
 
 ### MCP Enhancement Examples
 
 **Code Index Usage**:
 \`\`\`javascript
 // Discover authentication-related files
-mcp__code-index__find_files(pattern="*auth*")
+bash(find . -name "*auth*" -type f)
 
 // Search for OAuth patterns
-mcp__code-index__search_code_advanced(
+bash(rg "oauth|jwt|authentication" -g "*.{ts,js}")
-  pattern="oauth|jwt|authentication",
-  file_pattern="*.{ts,js}"
-)
 
 // Get file summary for key components
-mcp__code-index__get_file_summary(
+bash(rg "^(class|function|export|interface)" src/auth/index.ts)
-  file_path="src/auth/index.ts"
-)
 \`\`\`
 
 **Exa Research Usage**:
@@ -576,23 +317,13 @@ Before completion, verify:
 
 Generate all three documents and report completion status:
 - Task JSON files created: N files
-- Artifacts integrated: synthesis-spec, topic-framework, N role analyses
+- Artifacts integrated: synthesis-spec, guidance-specification, N role analyses
 - MCP enhancements: code-index, exa-research
 - Session ready for execution: /workflow:execute
 `
 )
 ```
 
-## Command Integration
-
-### Usage
-```bash
-# Basic usage
-/workflow:tools:task-generate-agent --session WFS-auth
-
-# Called by /workflow:plan
-SlashCommand(command="/workflow:tools:task-generate-agent --session WFS-[id]")
-```
 
 ### Agent Context Passing
 
@@ -607,36 +338,26 @@ const agentContext = {
     ? memory.get("workflow-session.json")
     : Read(.workflow/WFS-[id]/workflow-session.json),
 
-  analysis_results: memory.has("ANALYSIS_RESULTS.md")
+  context_package_path: ".workflow/WFS-[id]/.process/context-package.json",
-    ? memory.get("ANALYSIS_RESULTS.md")
-    : Read(.workflow/WFS-[id]/.process/ANALYSIS_RESULTS.md),
-
-  artifacts_inventory: memory.has("artifacts_inventory")
-    ? memory.get("artifacts_inventory")
-    : discoverArtifacts(),
 
   context_package: memory.has("context-package.json")
     ? memory.get("context-package.json")
-    : Read(.workflow/WFS-[id]/.process/context-package.json),
+    : Read(".workflow/WFS-[id]/.process/context-package.json"),
+
+  // Extract brainstorm artifacts from context package
+  brainstorm_artifacts: extractBrainstormArtifacts(context_package),
+
+  // Load role analyses using paths from context package
+  role_analyses: brainstorm_artifacts.role_analyses
+    .flatMap(role => role.files)
+    .map(file => Read(file.path)),
+
+  // Load conflict resolution if exists (from context package)
+  conflict_resolution: brainstorm_artifacts.conflict_resolution?.exists
+    ? Read(brainstorm_artifacts.conflict_resolution.path)
+    : null,
 
   // Optional MCP enhancements
   mcp_analysis: executeMcpDiscovery()
 }
 ```
-
-## Related Commands
-- `/workflow:plan` - Orchestrates planning and calls this command
-- `/workflow:tools:task-generate` - Manual version without agent
-- `/workflow:tools:context-gather` - Provides context package
-- `/workflow:tools:concept-enhanced` - Provides analysis results
-- `/workflow:execute` - Executes generated tasks
-
-## Key Differences from task-generate
-
-| Feature | task-generate | task-generate-agent |
-|---------|--------------|-------------------|
-| Execution | Manual/scripted | Agent-driven |
-| Phases | 6 phases | 2 phases (discovery + output) |
-| MCP Integration | Optional | Enhanced with examples |
-| Decision Logic | Command-driven | Agent-autonomous |
-| Complexity | Higher control | Simpler delegation |

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

@@ -2,7 +2,7 @@
 name: task-generate-tdd
 description: Generate TDD task chains with Red-Green-Refactor dependencies
 argument-hint: "--session WFS-session-id [--agent]"
-allowed-tools: Read(*), Write(*), Bash(gemini-wrapper:*), TodoWrite(*)
+allowed-tools: Read(*), Write(*), Bash(gemini:*), TodoWrite(*)
 ---
 
 # TDD Task Generation Command
@@ -49,6 +49,7 @@ Generate TDD-specific tasks from analysis results with complete Red-Green-Refact
 - **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
+- **Path Clarity**: All `focus_paths` prefer absolute paths (e.g., `D:\\project\\src\\module`), or clear relative paths from project root (e.g., `./src/module`)
 - **Artifact-Aware**: Integrates brainstorming outputs
 - **Memory-First**: Reuse loaded documents from memory
 - **Context-Aware**: Analyzes existing codebase and test patterns
@@ -72,25 +73,35 @@ Generate TDD-specific tasks from analysis results with complete Red-Green-Refact
    - If session metadata in memory → Skip loading
    - Else: Load `.workflow/{session_id}/workflow-session.json`
 
-2. **Analysis Results Loading**
+2. **Conflict Resolution Check** (NEW - Priority Input)
-   - If ANALYSIS_RESULTS.md in memory → Skip loading
+   - If CONFLICT_RESOLUTION.md exists → Load selected strategies
-   - Else: Read `.workflow/{session_id}/.process/ANALYSIS_RESULTS.md`
+   - Else: Skip to brainstorming artifacts
+   - Path: `.workflow/{session_id}/.process/CONFLICT_RESOLUTION.md`
 
 3. **Artifact Discovery**
    - If artifact inventory in memory → Skip scanning
    - Else: Scan `.workflow/{session_id}/.brainstorming/` directory
-   - Detect: synthesis-specification.md, topic-framework.md, role analyses
+   - Detect: role analysis documents, guidance-specification.md, role analyses
+
+4. **Context Package Loading**
+   - Load `.workflow/{session_id}/.process/context-package.json`
+   - Load `.workflow/{session_id}/.process/test-context-package.json` (if exists)
 
 ### Phase 2: TDD Task JSON Generation
 
-**Input**: Use `.process/ANALYSIS_RESULTS.md` directly (enhanced with TDD structure from concept-enhanced phase)
+**Input Sources** (priority order):
+1. **Conflict Resolution** (if exists): `.process/CONFLICT_RESOLUTION.md` - Selected resolution strategies
+2. **Brainstorming Artifacts**: Role analysis documents (system-architect, product-owner, etc.)
+3. **Context Package**: `.process/context-package.json` - Project structure and requirements
+4. **Test Context**: `.process/test-context-package.json` - Existing test patterns
 
-**ANALYSIS_RESULTS.md includes**:
+**TDD Task Structure includes**:
 - Feature list with testable requirements
 - Test cases for Red phase
-- Implementation requirements for Green phase
+- Implementation requirements for Green phase (with test-fix cycle)
 - Refactoring opportunities
 - Task dependencies and execution order
+- Conflict resolution decisions (if applicable)
 
 ### Phase 3: Task JSON & IMPL_PLAN.md Generation
 
@@ -124,6 +135,7 @@ For each feature, generate task(s) with ID format:
   "id": "IMPL-N",                                  // Task identifier
   "title": "Feature description with TDD",         // Human-readable title
   "status": "pending",                             // pending | in_progress | completed | container
+  "context_package_path": ".workflow/{session-id}/.process/context-package.json", // Path to smart context package
   "meta": {
     "type": "feature",                             // Task type
     "agent": "@code-developer",                    // Assigned agent
@@ -146,7 +158,7 @@ For each feature, generate task(s) with ID format:
         "expected_failure": "Why test should fail initially"
       }
     ],
-    "focus_paths": ["src/path/", "tests/path/"],  // Files to modify
+    "focus_paths": ["D:\\project\\src\\path", "./tests/path"],  // Absolute or clear relative paths from project root
     "acceptance": [                                // Success criteria
       "All tests pass (Red → Green)",
       "Code refactored (Refactor complete)",
@@ -247,13 +259,15 @@ Generate IMPL_PLAN.md with 8-section structure:
 ---
 identifier: WFS-{session-id}
 source: "User requirements" | "File: path"
-analysis: .workflow/{session-id}/.process/ANALYSIS_RESULTS.md
+conflict_resolution: .workflow/{session-id}/.process/CONFLICT_RESOLUTION.md  # if exists
 context_package: .workflow/{session-id}/.process/context-package.json
+context_package_path: .workflow/{session-id}/.process/context-package.json
+test_context: .workflow/{session-id}/.process/test-context-package.json  # if exists
 workflow_type: "tdd"
 verification_history:
-  concept_verify: "passed | skipped | pending"
+  conflict_resolution: "executed | skipped" # based on conflict_risk
   action_plan_verify: "pending"
-phase_progression: "brainstorm → context → test_context → analysis → concept_verify → tdd_planning"
+phase_progression: "brainstorm → context → test_context → conflict_resolution → tdd_planning"
 feature_count: N
 task_count: N  # ≤10 total
 task_breakdown:
@@ -283,10 +297,10 @@ tdd_workflow: true
 
 ## 3. Brainstorming Artifacts Reference
 - Artifact Usage Strategy
-  - synthesis-specification.md (primary reference)
+  - CONFLICT_RESOLUTION.md (if exists - selected resolution strategies)
+  - role analysis documents (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
@@ -397,9 +411,10 @@ Update workflow-session.json with TDD metadata:
 │   ├── IMPL-3.2.json                # Complex feature subtask (if needed)
 │   └── ...
 └── .process/
-    ├── ANALYSIS_RESULTS.md          # Enhanced with TDD breakdown from concept-enhanced
+    ├── CONFLICT_RESOLUTION.md       # Conflict resolution strategies (if conflict_risk ≥ medium)
     ├── test-context-package.json    # Test coverage analysis
     ├── context-package.json         # Input from context-gather
+    ├── context_package_path         # Path to smart context package
     └── green-fix-iteration-*.md     # Fix logs from Green phase test-fix cycles
 ```
 
@@ -438,7 +453,7 @@ Update workflow-session.json with TDD metadata:
 | Error | Cause | Resolution |
 |-------|-------|------------|
 | Session not found | Invalid session ID | Verify session exists |
-| Analysis missing | Incomplete planning | Run concept-enhanced first |
+| Context missing | Incomplete planning | Run context-gather first |
 
 ### TDD Generation Errors
 | Error | Cause | Resolution |
@@ -452,7 +467,7 @@ Update workflow-session.json with TDD metadata:
 
 ### Command Chain
 - **Called By**: `/workflow:tdd-plan` (Phase 4)
-- **Calls**: Gemini wrapper for TDD breakdown
+- **Calls**: Gemini CLI for TDD breakdown
 - **Followed By**: `/workflow:execute`, `/workflow:tdd-verify`
 
 ### Basic Usage

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

@@ -48,7 +48,7 @@ Specialized analysis tool for test generation workflows that uses Gemini to anal
 
 **Tool Configuration**:
 ```bash
-cd .workflow/{test_session_id}/.process && ~/.claude/scripts/gemini-wrapper -p "
+cd .workflow/{test_session_id}/.process && gemini -p "
 PURPOSE: Analyze test coverage gaps and design comprehensive test generation strategy
 TASK: Study implementation context, existing tests, and generate test requirements for missing coverage
 MODE: analysis

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

@@ -1,285 +1,188 @@
 ---
 name: test-context-gather
-description: Collect test coverage context and identify files requiring test generation
+description: Intelligently collect test coverage context using test-context-search-agent and package into standardized test-context JSON
 argument-hint: "--session WFS-test-session-id"
 examples:
   - /workflow:tools:test-context-gather --session WFS-test-auth
   - /workflow:tools:test-context-gather --session WFS-test-payment
+allowed-tools: Task(*), Read(*), Glob(*)
 ---
 
-# Test Context Gather Command
+# Test Context Gather Command (/workflow:tools:test-context-gather)
 
 ## Overview
-Specialized context collector for test generation workflows that analyzes test coverage, identifies missing tests, and packages implementation context from source sessions.
+
+Orchestrator command that invokes `test-context-search-agent` to gather comprehensive test coverage context for test generation workflows. Generates standardized `test-context-package.json` with coverage analysis, framework detection, and source implementation context.
+
+**Agent**: `test-context-search-agent` (`.claude/agents/test-context-search-agent.md`)
 
 ## Core Philosophy
-- **Coverage-First**: Analyze existing test coverage before planning
+
-- **Gap Identification**: Locate implementation files without corresponding tests
+- **Agent Delegation**: Delegate all test coverage analysis to `test-context-search-agent` for autonomous execution
+- **Detection-First**: Check for existing test-context-package before executing
+- **Coverage-First**: Analyze existing test coverage before planning new tests
 - **Source Context Loading**: Import implementation summaries from source session
-- **Framework Detection**: Auto-detect test framework and patterns
+- **Standardized Output**: Generate `.workflow/{test_session_id}/.process/test-context-package.json`
-- **MCP-Powered**: Leverage code-index tools for precise analysis
 
-## Core Responsibilities
+## Execution Flow
-- Load source session implementation context
-- Analyze current test coverage using MCP tools
-- Identify files requiring test generation
-- Detect test framework and conventions
-- Package test context for analysis phase
 
-## Execution Lifecycle
+### Step 1: Test-Context-Package Detection
 
-### Phase 1: Session Validation & Source Loading
+**Execute First** - Check if valid package already exists:
 
-1. **Test Session Validation**
+```javascript
-   - Load `.workflow/{test_session_id}/workflow-session.json`
+const testContextPath = `.workflow/${test_session_id}/.process/test-context-package.json`;
-   - Extract `meta.source_session` reference
-   - Validate test session type is "test-gen"
 
-2. **Source Session Context Loading**
+if (file_exists(testContextPath)) {
-   - Read `.workflow/{source_session_id}/workflow-session.json`
+  const existing = Read(testContextPath);
-   - Load implementation summaries from `.workflow/{source_session_id}/.summaries/`
-   - Extract changed files and implementation scope
-   - Identify implementation patterns and tech stack
 
-### Phase 2: Test Coverage Analysis (MCP Tools)
+  // Validate package belongs to current test session
-
+  if (existing?.metadata?.test_session_id === test_session_id) {
-1. **Existing Test Discovery**
+    console.log("✅ Valid test-context-package found for session:", test_session_id);
-   ```bash
+    console.log("📊 Coverage Stats:", existing.test_coverage.coverage_stats);
-   # Find all test files
+    console.log("🧪 Framework:", existing.test_framework.framework);
-   mcp__code-index__find_files(pattern="*.test.*")
+    console.log("⚠️  Missing Tests:", existing.test_coverage.missing_tests.length);
-   mcp__code-index__find_files(pattern="*.spec.*")
+    return existing; // Skip execution, return existing
-   mcp__code-index__find_files(pattern="*test_*.py")
+  } else {
-
+    console.warn("⚠️ Invalid test_session_id in existing package, re-generating...");
-   # Search for test patterns
+  }
-   mcp__code-index__search_code_advanced(
-     pattern="describe|it|test|@Test",
-     file_pattern="*.test.*",
-     context_lines=0
-   )
-   ```
-
-2. **Coverage Gap Analysis**
-   ```bash
-   # For each implementation file from source session
-   # Check if corresponding test file exists
-
-   # Example: src/auth/AuthService.ts -> tests/auth/AuthService.test.ts
-   #          src/utils/validator.py -> tests/test_validator.py
-
-   # Output: List of files without tests
-   ```
-
-3. **Test Statistics**
-   - Count total test files
-   - Count implementation files from source session
-   - Calculate coverage percentage
-   - Identify coverage gaps by module
-
-### Phase 3: Test Framework Detection
-
-1. **Framework Identification**
-   ```bash
-   # Check package.json or requirements.txt
-   mcp__code-index__search_code_advanced(
-     pattern="jest|mocha|jasmine|pytest|unittest|rspec",
-     file_pattern="package.json|requirements.txt|Gemfile",
-     context_lines=2
-   )
-
-   # Analyze existing test patterns
-   mcp__code-index__search_code_advanced(
-     pattern="describe\\(|it\\(|test\\(|def test_",
-     file_pattern="*.test.*",
-     context_lines=3
-   )
-   ```
-
-2. **Convention Analysis**
-   - Test file naming patterns (*.test.ts vs *.spec.ts)
-   - Test directory structure (tests/ vs __tests__ vs src/**/*.test.*)
-   - Assertion library (expect, assert, should)
-   - Mocking framework (jest.fn, sinon, unittest.mock)
-
-### Phase 4: Context Packaging
-
-Generate `test-context-package.json`:
-
-```json
-{
-  "metadata": {
-    "test_session_id": "WFS-test-auth",
-    "source_session_id": "WFS-auth",
-    "timestamp": "2025-10-04T10:30:00Z",
-    "task_type": "test-generation",
-    "complexity": "medium"
-  },
-  "source_context": {
-    "implementation_summaries": [
-      {
-        "task_id": "IMPL-001",
-        "summary_path": ".workflow/WFS-auth/.summaries/IMPL-001-summary.md",
-        "changed_files": [
-          "src/auth/AuthService.ts",
-          "src/auth/TokenValidator.ts",
-          "src/middleware/auth.ts"
-        ],
-        "implementation_type": "feature"
-      }
-    ],
-    "tech_stack": ["typescript", "express", "jsonwebtoken"],
-    "project_patterns": {
-      "architecture": "layered",
-      "error_handling": "try-catch with custom errors",
-      "async_pattern": "async/await"
-    }
-  },
-  "test_coverage": {
-    "existing_tests": [
-      "tests/auth/AuthService.test.ts",
-      "tests/middleware/auth.test.ts"
-    ],
-    "missing_tests": [
-      {
-        "implementation_file": "src/auth/TokenValidator.ts",
-        "suggested_test_file": "tests/auth/TokenValidator.test.ts",
-        "priority": "high",
-        "reason": "New implementation without tests"
-      }
-    ],
-    "coverage_stats": {
-      "total_implementation_files": 3,
-      "files_with_tests": 2,
-      "files_without_tests": 1,
-      "coverage_percentage": 66.7
-    }
-  },
-  "test_framework": {
-    "framework": "jest",
-    "version": "^29.0.0",
-    "test_pattern": "**/*.test.ts",
-    "test_directory": "tests/",
-    "assertion_library": "expect",
-    "mocking_framework": "jest",
-    "conventions": {
-      "file_naming": "*.test.ts",
-      "test_structure": "describe/it blocks",
-      "setup_teardown": "beforeEach/afterEach"
-    }
-  },
-  "assets": [
-    {
-      "type": "implementation_summary",
-      "path": ".workflow/WFS-auth/.summaries/IMPL-001-summary.md",
-      "relevance": "Source implementation context",
-      "priority": "highest"
-    },
-    {
-      "type": "existing_test",
-      "path": "tests/auth/AuthService.test.ts",
-      "relevance": "Test pattern reference",
-      "priority": "high"
-    },
-    {
-      "type": "source_code",
-      "path": "src/auth/TokenValidator.ts",
-      "relevance": "Implementation requiring tests",
-      "priority": "high"
-    },
-    {
-      "type": "documentation",
-      "path": "CLAUDE.md",
-      "relevance": "Project conventions",
-      "priority": "medium"
-    }
-  ],
-  "focus_areas": [
-    "Generate comprehensive tests for TokenValidator",
-    "Follow existing Jest patterns from AuthService tests",
-    "Cover happy path, error cases, and edge cases",
-    "Include integration tests for middleware"
-  ]
 }
 ```
 
-## Output Location
+### Step 2: Invoke Test-Context-Search Agent
 
-```
+**Only execute if Step 1 finds no valid package**
-.workflow/{test_session_id}/.process/test-context-package.json
-```
 
-## MCP Tools Usage
+```javascript
+Task(
+  subagent_type="test-context-search-agent",
+  description="Gather test coverage context",
+  prompt=`
+You are executing as test-context-search-agent (.claude/agents/test-context-search-agent.md).
 
-### File Discovery
+## Execution Mode
-```bash
+**PLAN MODE** (Comprehensive) - Full Phase 1-3 execution
-# Test files
-mcp__code-index__find_files(pattern="*.test.*")
-mcp__code-index__find_files(pattern="*.spec.*")
 
-# Implementation files
+## Session Information
-mcp__code-index__find_files(pattern="*.ts")
+- **Test Session ID**: ${test_session_id}
-mcp__code-index__find_files(pattern="*.js")
+- **Output Path**: .workflow/${test_session_id}/.process/test-context-package.json
-```
 
-### Content Search
+## Mission
-```bash
+Execute complete test-context-search-agent workflow for test generation planning:
-# Test framework detection
-mcp__code-index__search_code_advanced(
-  pattern="jest|mocha|pytest",
-  file_pattern="package.json|requirements.txt"
-)
 
-# Test pattern analysis
+### Phase 1: Session Validation & Source Context Loading
-mcp__code-index__search_code_advanced(
+1. **Detection**: Check for existing test-context-package (early exit if valid)
-  pattern="describe|it|test",
+2. **Test Session Validation**: Load test session metadata, extract source_session reference
-  file_pattern="*.test.*",
+3. **Source Context Loading**: Load source session implementation summaries, changed files, tech stack
-  context_lines=2
+
+### Phase 2: Test Coverage Analysis
+Execute coverage discovery:
+- **Track 1**: Existing test discovery (find *.test.*, *.spec.* files)
+- **Track 2**: Coverage gap analysis (match implementation files to test files)
+- **Track 3**: Coverage statistics (calculate percentages, identify gaps by module)
+
+### Phase 3: Framework Detection & Packaging
+1. Framework identification from package.json/requirements.txt
+2. Convention analysis from existing test patterns
+3. Generate and validate test-context-package.json
+
+## Output Requirements
+Complete test-context-package.json with:
+- **metadata**: test_session_id, source_session_id, task_type, complexity
+- **source_context**: implementation_summaries, tech_stack, project_patterns
+- **test_coverage**: existing_tests[], missing_tests[], coverage_stats
+- **test_framework**: framework, version, test_pattern, conventions
+- **assets**: implementation_summary[], existing_test[], source_code[] with priorities
+- **focus_areas**: Test generation guidance based on coverage gaps
+
+## Quality Validation
+Before completion verify:
+- [ ] Valid JSON format with all required fields
+- [ ] Source session context loaded successfully
+- [ ] Test coverage gaps identified
+- [ ] Test framework detected (or marked as 'unknown')
+- [ ] Coverage percentage calculated correctly
+- [ ] Missing tests catalogued with priority
+- [ ] Execution time < 30 seconds (< 60s for large codebases)
+
+Execute autonomously following agent documentation.
+Report completion with coverage statistics.
+`
 )
 ```
 
-### Coverage Analysis
+### Step 3: Output Verification
-```bash
-# For each implementation file
-# Check if test exists
-implementation_file="src/auth/AuthService.ts"
-test_file_patterns=(
-  "tests/auth/AuthService.test.ts"
-  "src/auth/AuthService.test.ts"
-  "src/auth/__tests__/AuthService.test.ts"
-)
 
-# Search for test file
+After agent completes, verify output:
-for pattern in "${test_file_patterns[@]}"; do
+
-  if mcp__code-index__find_files(pattern="$pattern") | grep -q .; then
+```javascript
-    echo "✅ Test exists: $pattern"
+// Verify file was created
-    break
+const outputPath = `.workflow/${test_session_id}/.process/test-context-package.json`;
-  fi
+if (!file_exists(outputPath)) {
-done
+  throw new Error("❌ Agent failed to generate test-context-package.json");
+}
+
+// Load and display summary
+const testContext = Read(outputPath);
+console.log("✅ Test context package generated successfully");
+console.log("📊 Coverage:", testContext.test_coverage.coverage_stats.coverage_percentage + "%");
+console.log("⚠️  Tests to generate:", testContext.test_coverage.missing_tests.length);
 ```
 
+## Parameter Reference
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `--session` | string | ✅ | Test workflow session ID (e.g., WFS-test-auth) |
+
+## Output Schema
+
+Refer to `test-context-search-agent.md` Phase 3.2 for complete `test-context-package.json` schema.
+
+**Key Sections**:
+- **metadata**: Test session info, source session reference, complexity
+- **source_context**: Implementation summaries with changed files and tech stack
+- **test_coverage**: Existing tests, missing tests with priorities, coverage statistics
+- **test_framework**: Framework name, version, patterns, conventions
+- **assets**: Categorized files with relevance (implementation_summary, existing_test, source_code)
+- **focus_areas**: Test generation guidance based on analysis
+
+## Usage Examples
+
+### Basic Usage
+```bash
+/workflow:tools:test-context-gather --session WFS-test-auth
+```
+
+### Expected Output
+```
+✅ Valid test-context-package found for session: WFS-test-auth
+📊 Coverage Stats: { total: 3, with_tests: 2, without_tests: 1, percentage: 66.7 }
+🧪 Framework: jest
+⚠️  Missing Tests: 1
+```
+
+## Success Criteria
+
+- ✅ Valid test-context-package.json generated in `.workflow/{test_session_id}/.process/`
+- ✅ Source session context loaded successfully
+- ✅ Test coverage gaps identified (>90% accuracy)
+- ✅ Test framework detected and documented
+- ✅ Execution completes within 30 seconds (60s for large codebases)
+- ✅ All required schema fields present and valid
+- ✅ Coverage statistics calculated correctly
+- ✅ Agent reports completion with statistics
+
 ## Error Handling
 
 | Error | Cause | Resolution |
 |-------|-------|------------|
+| Package validation failed | Invalid test_session_id in existing package | Re-run agent to regenerate |
 | Source session not found | Invalid source_session reference | Verify test session metadata |
 | No implementation summaries | Source session incomplete | Complete source session first |
-| MCP tools unavailable | MCP not configured | Fallback to bash find/grep |
+| Agent execution timeout | Large codebase or slow analysis | Increase timeout, check file access |
-| No test framework detected | Missing test dependencies | Request user to specify framework |
+| Missing required fields | Agent incomplete execution | Check agent logs, verify schema compliance |
-
+| No test framework detected | Missing test dependencies | Agent marks as 'unknown', manual specification needed |
-## Fallback Strategy (No MCP)
-
-```bash
-# File discovery
-find . -name "*.test.*" -o -name "*.spec.*" | grep -v node_modules
-
-# Framework detection
-grep -r "jest\|mocha\|pytest" package.json requirements.txt 2>/dev/null
-
-# Coverage analysis
-for impl_file in $(cat changed_files.txt); do
-  test_file=$(echo $impl_file | sed 's/src/tests/' | sed 's/\(.*\)\.\(ts\|js\|py\)$/\1.test.\2/')
-  [ ! -f "$test_file" ] && echo "$impl_file → MISSING TEST"
-done
-```
 
 ## Integration
 
@@ -287,20 +190,18 @@ done
 - `/workflow:test-gen` (Phase 3: Context Gathering)
 
 ### Calls
-- MCP code-index tools for analysis
+- `test-context-search-agent` - Autonomous test coverage analysis
-- Bash file operations for fallback
 
 ### Followed By
-- `/workflow:tools:test-concept-enhanced` - Analyzes context and plans test generation
+- `/workflow:tools:test-concept-enhanced` - Test generation analysis and planning
 
-## Success Criteria
+## Notes
 
-- ✅ Source session context loaded successfully
+- **Detection-first**: Always check for existing test-context-package before invoking agent
-- ✅ Test coverage gaps identified with MCP tools
+- **Agent autonomy**: Agent handles all coverage analysis logic per `.claude/agents/test-context-search-agent.md`
-- ✅ Test framework detected and documented
+- **No redundancy**: This command is a thin orchestrator, all logic in agent
-- ✅ Valid test-context-package.json generated
+- **Framework agnostic**: Supports Jest, Mocha, pytest, RSpec, Go testing, etc.
-- ✅ All missing tests catalogued with priority
+- **Coverage focus**: Primary goal is identifying implementation files without tests
-- ✅ Execution time < 20 seconds
 
 ## Related Commands
 

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

@@ -146,9 +146,9 @@ Generate **TWO task JSON files**:
         "step": "load_existing_test_patterns",
         "action": "Study existing tests for pattern reference",
         "commands": [
-          "mcp__code-index__find_files(pattern=\"*.test.*\")",
+          "bash(find . -name \"*.test.*\" -type f)",
           "bash(# Read first 2 existing test files as examples)",
-          "bash(test_files=$(mcp__code-index__find_files(pattern=\"*.test.*\") | head -2))",
+          "bash(test_files=$(find . -name \"*.test.*\" -type f | head -2))",
           "bash(for f in $test_files; do echo \"=== $f ===\"&& cat \"$f\"; done)"
         ],
         "output_to": "existing_test_patterns",
@@ -198,7 +198,7 @@ Generate **TWO task JSON files**:
         "Codex generates comprehensive test suite",
         "Codex validates test syntax and executability"
       ],
-      "command": "bash(codex -C [focus_paths] --full-auto exec \"PURPOSE: Generate comprehensive test suite TASK: Create test files based on TEST_ANALYSIS_RESULTS.md section 5 MODE: write CONTEXT: @{.workflow/WFS-test-[session]/.process/TEST_ANALYSIS_RESULTS.md,.workflow/WFS-test-[session]/.process/test-context-package.json} EXPECTED: All test files with happy path, error handling, edge cases, integration tests RULES: Follow test framework conventions, ensure tests are executable\" --skip-git-repo-check -s danger-full-access)",
+      "command": "bash(codex -C [focus_paths] --full-auto exec \"PURPOSE: Generate comprehensive test suite TASK: Create test files based on TEST_ANALYSIS_RESULTS.md section 5 MODE: write CONTEXT: @.workflow/WFS-test-[session]/.process/TEST_ANALYSIS_RESULTS.md @.workflow/WFS-test-[session]/.process/test-context-package.json EXPECTED: All test files with happy path, error handling, edge cases, integration tests RULES: Follow test framework conventions, ensure tests are executable\" --skip-git-repo-check -s danger-full-access)",
       "depends_on": [],
       "output": "test_generation"
     }],
@@ -282,11 +282,11 @@ Generate **TWO task JSON files**:
         "step": "analyze_test_coverage",
         "action": "Analyze test coverage and identify missing tests",
         "commands": [
-          "mcp__code-index__find_files(pattern=\"*.test.*\")",
+          "bash(find . -name \"*.test.*\" -type f)",
-          "mcp__code-index__search_code_advanced(pattern=\"test|describe|it|def test_\", file_pattern=\"*.test.*\")",
+          "bash(rg \"test|describe|it|def test_\" -g \"*.test.*\")",
           "bash(# Count implementation files vs test files)",
           "bash(impl_count=$(find [changed_files_dirs] -type f \\( -name '*.ts' -o -name '*.js' -o -name '*.py' \\) ! -name '*.test.*' 2>/dev/null | wc -l))",
-          "bash(test_count=$(mcp__code-index__find_files(pattern=\"*.test.*\") | wc -l))",
+          "bash(test_count=$(find . -name \"*.test.*\" -type f | wc -l))",
           "bash(echo \"Implementation files: $impl_count, Test files: $test_count\")"
         ],
         "output_to": "test_coverage_analysis",
@@ -323,7 +323,7 @@ Generate **TWO task JSON files**:
           "cycle_pattern": "test → gemini_diagnose → manual_fix (or codex if needed) → retest",
           "tools": {
             "test_execution": "bash(test_command)",
-            "diagnosis": "gemini-wrapper (MODE: analysis, uses bug-fix template)",
+            "diagnosis": "gemini (MODE: analysis, uses bug-fix template)",
             "fix_application": "manual (default) or codex exec resume --last (if explicitly needed)",
             "verification": "bash(test_command) + regression_check"
           },
@@ -354,16 +354,16 @@ Generate **TWO task JSON files**:
         "      * Source files from focus_paths",
         "      * Implementation summaries from source session",
         "    - Execute Gemini analysis with bug-fix template:",
-        "      bash(cd .workflow/WFS-test-[session]/.process && ~/.claude/scripts/gemini-wrapper --all-files -p \"",
+        "      bash(cd .workflow/WFS-test-[session]/.process && gemini \"",
         "      PURPOSE: Diagnose test failure iteration [N] and propose minimal fix",
         "      TASK: Systematic bug analysis and fix recommendations for test failure",
         "      MODE: analysis",
-        "      CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}",
+        "      CONTEXT: @CLAUDE.md,**/*CLAUDE.md",
         "               Test output: [test_failures]",
         "               Source files: [focus_paths]",
         "               Implementation: [implementation_context]",
         "      EXPECTED: Root cause analysis, code path tracing, targeted fixes",
-        "      RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: [test_failure_description]",
+        "      RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt) | Bug: [test_failure_description]",
         "             Minimal surgical fixes only - no refactoring",
         "      \" > fix-iteration-[N]-diagnosis.md)",
         "    - Parse diagnosis → extract fix_suggestion and target_files",
@@ -690,6 +690,6 @@ The `@test-fix-agent` will execute the task by following the `flow_control.imple
 6. **Phase 3**: Generate summary and certify code
 7. **Error Recovery**: Revert changes if max iterations reached
 
-**Bug Diagnosis Template**: Uses bug-fix.md template as referenced in bug-index.md for systematic root cause analysis, code path tracing, and targeted fix recommendations.
+**Bug Diagnosis Template**: Uses `~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt` template for systematic root cause analysis, code path tracing, and targeted fix recommendations.
 
 **Codex Usage**: The agent uses `codex exec "..." resume --last` pattern ONLY when meta.use_codex=true (--use-codex flag present) to maintain conversation context across multiple fix iterations, ensuring consistency and learning from previous attempts.

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

@@ -170,128 +170,318 @@ ELSE:
     extraction_insufficient = true
 ```
 
-### Step 2: Interactive Question Workflow (Agent)
+### Step 2: Generate Animation Questions (Main Flow)
 
 ```bash
 # If extraction failed or insufficient, use interactive questioning
 IF extraction_insufficient OR extraction_mode == "interactive":
-    REPORT: "🤔 Launching interactive animation specification mode"
+    REPORT: "🤔 Interactive animation specification mode"
+    REPORT: "   Context: {has_design_context ? 'Aligning with design tokens' : 'Standalone animation system'}"
+    REPORT: "   Focus: {focus_types}"
 
-    # Launch ui-design-agent for interactive questioning
+    # Determine question categories based on focus_types
-    Task(ui-design-agent): `
+    question_categories = []
-      [ANIMATION_SPECIFICATION_TASK]
+    IF "all" IN focus_types OR "transitions" IN focus_types:
-      Guide user through animation design decisions via structured questions
+        question_categories.append("timing_scale")
+        question_categories.append("easing_philosophy")
 
-      SESSION: {session_id} | MODE: interactive | BASE_PATH: {base_path}
+    IF "all" IN focus_types OR "interactions" IN focus_types OR "hover" IN focus_types:
+        question_categories.append("button_interactions")
+        question_categories.append("card_interactions")
+        question_categories.append("input_interactions")
 
-      ## Context
+    IF "all" IN focus_types OR "page" IN focus_types:
-      - Design tokens available: {has_design_context}
+        question_categories.append("page_transitions")
-      - Focus areas: {focus_types}
-      - Extracted data: {animations_extracted ? "Partial CSS data available" : "No CSS data"}
 
-      ## Interactive Workflow
+    IF "all" IN focus_types OR "loading" IN focus_types:
+        question_categories.append("loading_states")
 
-      For each animation category, ASK user and WAIT for response:
+    IF "all" IN focus_types OR "scroll" IN focus_types:
+        question_categories.append("scroll_animations")
+```
 
-      ### 1. Transition Duration Scale
+### Step 3: Output Questions in Text Format (Main Flow)
-      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
+```markdown
-      QUESTION: "What easing style matches your brand?"
+# Generate and output structured questions
-      OPTIONS:
+REPORT: ""
-        - "Linear" (constant speed, technical feel)
+REPORT: "===== 动画规格交互式配置 ====="
-        - "Ease-Out" (fast start, natural feel)
+REPORT: ""
-        - "Ease-In-Out" (balanced, polished feel)
-        - "Spring/Bounce" (playful, modern feel)
-        - "Custom" (specify cubic-bezier)
 
-      ### 3. Common Interactions (Ask for each)
+question_number = 1
-      FOR interaction IN ["button-hover", "link-hover", "card-hover", "modal-open", "dropdown-toggle"]:
+questions_output = []
-        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
+# Q1: Timing Scale (if included)
-      QUESTION: "Should page/route changes have animations?"
+IF "timing_scale" IN question_categories:
-      IF YES:
+    REPORT: "【问题{question_number} - 时间尺度】您的设计需要什么样的过渡速度？"
-        ASK: "What style?"
+    REPORT: "a) 快速敏捷"
-        OPTIONS:
+    REPORT: "   说明：100-200ms 过渡，适合工具型应用和即时反馈场景"
-          - "Fade" (crossfade between views)
+    REPORT: "b) 平衡适中"
-          - "Slide" (swipe left/right)
+    REPORT: "   说明：200-400ms 过渡，通用选择，符合多数用户预期"
-          - "Zoom" (scale in/out)
+    REPORT: "c) 流畅舒缓"
-          - "None"
+    REPORT: "   说明：400-600ms 过渡，适合品牌展示和沉浸式体验"
+    REPORT: "d) 自定义"
+    REPORT: "   说明：需要指定具体数值和使用场景"
+    REPORT: ""
+    questions_output.append({id: question_number, category: "timing_scale", options: ["a", "b", "c", "d"]})
+    question_number += 1
 
-      ### 5. Loading States
+# Q2: Easing Philosophy (if included)
-      QUESTION: "What loading animation style?"
+IF "easing_philosophy" IN question_categories:
-      OPTIONS:
+    REPORT: "【问题{question_number} - 缓动风格】哪种缓动曲线符合您的品牌调性？"
-        - "Spinner" (rotating circle)
+    REPORT: "a) 线性匀速"
-        - "Pulse" (opacity pulse)
+    REPORT: "   说明：恒定速度，技术感和精确性，适合数据可视化"
-        - "Skeleton" (shimmer effect)
+    REPORT: "b) 快入慢出"
-        - "Progress Bar" (linear fill)
+    REPORT: "   说明：快速启动自然减速，最接近物理世界，通用推荐"
-        - "Custom" (describe)
+    REPORT: "c) 慢入慢出"
+    REPORT: "   说明：平滑对称，精致优雅，适合高端品牌"
+    REPORT: "d) 弹性效果"
+    REPORT: "   说明：Spring/Bounce 回弹，活泼现代，适合互动性强的应用"
+    REPORT: ""
+    questions_output.append({id: question_number, category: "easing_philosophy", options: ["a", "b", "c", "d"]})
+    question_number += 1
 
-      ### 6. Micro-interactions
+# Q3-5: Interaction Animations (button, card, input - if included)
-      QUESTION: "Should form inputs have micro-interactions?"
+IF "button_interactions" IN question_categories:
-      IF YES:
+    REPORT: "【问题{question_number} - 按钮交互】按钮悬停/点击时如何反馈？"
-        ASK: "What interactions?"
+    REPORT: "a) 微妙变化"
-        OPTIONS:
+    REPORT: "   说明：仅颜色/透明度变化，适合简约设计"
-          - "Focus state animation" (border/shadow transition)
+    REPORT: "b) 抬升效果"
-          - "Error shake" (horizontal shake on error)
+    REPORT: "   说明：轻微缩放+阴影加深，增强物理感知"
-          - "Success check" (checkmark animation)
+    REPORT: "c) 滑动移位"
-          - "All of the above"
+    REPORT: "   说明：Transform translateY，视觉引导明显"
+    REPORT: "d) 无动画"
+    REPORT: "   说明：静态交互，性能优先或特定品牌要求"
+    REPORT: ""
+    questions_output.append({id: question_number, category: "button_interactions", options: ["a", "b", "c", "d"]})
+    question_number += 1
 
-      ### 7. Scroll Animations
+IF "card_interactions" IN question_categories:
-      QUESTION: "Should elements animate on scroll?"
+    REPORT: "【问题{question_number} - 卡片交互】卡片悬停时的动画效果？"
-      IF YES:
+    REPORT: "a) 阴影加深"
-        ASK: "What scroll animation style?"
+    REPORT: "   说明：Box-shadow 变化，层次感增强"
-        OPTIONS:
+    REPORT: "b) 上浮效果"
-          - "Fade In" (opacity 0→1)
+    REPORT: "   说明：Transform translateY(-4px)，明显的空间层次"
-          - "Slide Up" (translateY + fade)
+    REPORT: "c) 缩放放大"
-          - "Scale In" (scale 0.9→1 + fade)
+    REPORT: "   说明：Scale(1.02)，突出焦点内容"
-          - "Stagger" (sequential delays)
+    REPORT: "d) 无动画"
-          - "None"
+    REPORT: "   说明：静态卡片，性能或设计考量"
+    REPORT: ""
+    questions_output.append({id: question_number, category: "card_interactions", options: ["a", "b", "c", "d"]})
+    question_number += 1
 
-      ## Output Generation
+IF "input_interactions" IN question_categories:
+    REPORT: "【问题{question_number} - 表单交互】输入框是否需要微交互反馈？"
+    REPORT: "a) 聚焦动画"
+    REPORT: "   说明：边框/阴影过渡，清晰的状态指示"
+    REPORT: "b) 错误抖动"
+    REPORT: "   说明：水平shake动画，错误提示更明显"
+    REPORT: "c) 成功勾选"
+    REPORT: "   说明：Checkmark 动画，完成反馈"
+    REPORT: "d) 全部包含"
+    REPORT: "   说明：聚焦+错误+成功的完整反馈体系"
+    REPORT: "e) 无微交互"
+    REPORT: "   说明：标准表单，无额外动画"
+    REPORT: ""
+    questions_output.append({id: question_number, category: "input_interactions", options: ["a", "b", "c", "d", "e"]})
+    question_number += 1
 
-      Based on user responses, generate structured data:
+# Q6: Page Transitions (if included)
+IF "page_transitions" IN question_categories:
+    REPORT: "【问题{question_number} - 页面过渡】页面/路由切换是否需要过渡动画？"
+    REPORT: "a) 淡入淡出"
+    REPORT: "   说明：Crossfade 效果，平滑过渡不突兀"
+    REPORT: "b) 滑动切换"
+    REPORT: "   说明：Swipe left/right，方向性导航"
+    REPORT: "c) 缩放过渡"
+    REPORT: "   说明：Scale in/out，空间层次感"
+    REPORT: "d) 无过渡"
+    REPORT: "   说明：即时切换，性能优先"
+    REPORT: ""
+    questions_output.append({id: question_number, category: "page_transitions", options: ["a", "b", "c", "d"]})
+    question_number += 1
 
-      1. Create animation-specification.json with user choices:
+# Q7: Loading States (if included)
-         - timing_scale (fast/balanced/slow/custom)
+IF "loading_states" IN question_categories:
-         - easing_philosophy (linear/ease-out/ease-in-out/spring)
+    REPORT: "【问题{question_number} - 加载状态】加载时使用何种动画风格？"
-         - interactions: {interaction_name: {type, properties, timing}}
+    REPORT: "a) 旋转加载器"
-         - page_transitions: {enabled, style, duration}
+    REPORT: "   说明：Spinner 圆形旋转，通用加载指示"
-         - loading_animations: {style, duration}
+    REPORT: "b) 脉冲闪烁"
-         - scroll_animations: {enabled, style, stagger_delay}
+    REPORT: "   说明：Opacity pulse，轻量级反馈"
+    REPORT: "c) 骨架屏"
+    REPORT: "   说明：Shimmer effect，内容占位预览"
+    REPORT: "d) 进度条"
+    REPORT: "   说明：Linear fill，进度量化展示"
+    REPORT: ""
+    questions_output.append({id: question_number, category: "loading_states", options: ["a", "b", "c", "d"]})
+    question_number += 1
 
-      2. Write to {base_path}/.intermediates/animation-analysis/animation-specification.json
+# Q8: Scroll Animations (if included)
+IF "scroll_animations" IN question_categories:
+    REPORT: "【问题{question_number} - 滚动动画】元素是否在滚动时触发动画？"
+    REPORT: "a) 淡入出现"
+    REPORT: "   说明：Opacity 0→1，渐进式内容呈现"
+    REPORT: "b) 上滑出现"
+    REPORT: "   说明：TranslateY + fade，方向性引导"
+    REPORT: "c) 缩放淡入"
+    REPORT: "   说明：Scale 0.9→1 + fade，聚焦效果"
+    REPORT: "d) 交错延迟"
+    REPORT: "   说明：Stagger 序列动画，列表渐次呈现"
+    REPORT: "e) 无滚动动画"
+    REPORT: "   说明：静态内容，性能或可访问性考量"
+    REPORT: ""
+    questions_output.append({id: question_number, category: "scroll_animations", options: ["a", "b", "c", "d", "e"]})
+    question_number += 1
 
-      ## Critical Requirements
+REPORT: "支持格式："
-      - ✅ Use Write() tool immediately for specification file
+REPORT: "- 空格分隔：1a 2b 3c"
-      - ✅ Wait for user response after EACH question before proceeding
+REPORT: "- 逗号分隔：1a,2b,3c"
-      - ✅ Validate responses and ask for clarification if needed
+REPORT: "- 自由组合：1a 2b,3c"
-      - ✅ Provide sensible defaults if user skips questions
+REPORT: ""
-      - ❌ NO external research or MCP calls
+REPORT: "请输入您的选择："
-    `
+```
+
+### Step 4: Wait for User Input (Main Flow)
+
+```javascript
+# Wait for user input
+user_raw_input = WAIT_FOR_USER_INPUT()
+
+# Store raw input for debugging
+REPORT: "收到输入: {user_raw_input}"
+```
+
+### Step 5: Parse User Answers (Main Flow)
+
+```javascript
+# Intelligent input parsing (support multiple formats)
+answers = {}
+
+# Parse input using intelligent matching
+# Support formats: "1a 2b 3c", "1a,2b,3c", "1a 2b,3c"
+parsed_responses = PARSE_USER_INPUT(user_raw_input, questions_output)
+
+# Validate parsing
+IF parsed_responses.is_valid:
+    # Map question numbers to categories
+    FOR response IN parsed_responses.answers:
+        question_id = response.question_id
+        selected_option = response.option
+
+        # Find category for this question
+        FOR question IN questions_output:
+            IF question.id == question_id:
+                category = question.category
+                answers[category] = selected_option
+                REPORT: "✅ 问题{question_id} ({category}): 选择 {selected_option}"
+                break
+ELSE:
+    REPORT: "❌ 输入格式无法识别，请参考格式示例重新输入："
+    REPORT: "   示例：1a 2b 3c 4d"
+    # Return to Step 3 for re-input
+    GOTO Step 3
+```
+
+### Step 6: Write Animation Specification (Main Flow)
+
+```javascript
+# Map user choices to specification structure
+specification = {
+    "metadata": {
+        "source": "interactive",
+        "timestamp": NOW(),
+        "focus_types": focus_types,
+        "has_design_context": has_design_context
+    },
+    "timing_scale": MAP_TIMING_SCALE(answers.timing_scale),
+    "easing_philosophy": MAP_EASING_PHILOSOPHY(answers.easing_philosophy),
+    "interactions": {
+        "button": MAP_BUTTON_INTERACTION(answers.button_interactions),
+        "card": MAP_CARD_INTERACTION(answers.card_interactions),
+        "input": MAP_INPUT_INTERACTION(answers.input_interactions)
+    },
+    "page_transitions": MAP_PAGE_TRANSITIONS(answers.page_transitions),
+    "loading_animations": MAP_LOADING_STATES(answers.loading_states),
+    "scroll_animations": MAP_SCROLL_ANIMATIONS(answers.scroll_animations)
+}
+
+# Mapping functions (inline logic)
+FUNCTION MAP_TIMING_SCALE(option):
+    SWITCH option:
+        CASE "a": RETURN {scale: "fast", base_duration: "150ms", range: "100-200ms"}
+        CASE "b": RETURN {scale: "balanced", base_duration: "300ms", range: "200-400ms"}
+        CASE "c": RETURN {scale: "smooth", base_duration: "500ms", range: "400-600ms"}
+        CASE "d": RETURN {scale: "custom", base_duration: "300ms", note: "User to provide values"}
+
+FUNCTION MAP_EASING_PHILOSOPHY(option):
+    SWITCH option:
+        CASE "a": RETURN {style: "linear", curve: "linear"}
+        CASE "b": RETURN {style: "ease-out", curve: "cubic-bezier(0, 0, 0.2, 1)"}
+        CASE "c": RETURN {style: "ease-in-out", curve: "cubic-bezier(0.4, 0, 0.2, 1)"}
+        CASE "d": RETURN {style: "spring", curve: "cubic-bezier(0.34, 1.56, 0.64, 1)"}
+
+FUNCTION MAP_BUTTON_INTERACTION(option):
+    SWITCH option:
+        CASE "a": RETURN {type: "subtle", properties: ["color", "background-color", "opacity"]}
+        CASE "b": RETURN {type: "lift", properties: ["transform", "box-shadow"], transform: "scale(1.02)"}
+        CASE "c": RETURN {type: "slide", properties: ["transform"], transform: "translateY(-2px)"}
+        CASE "d": RETURN {type: "none", properties: []}
+
+FUNCTION MAP_CARD_INTERACTION(option):
+    SWITCH option:
+        CASE "a": RETURN {type: "shadow", properties: ["box-shadow"]}
+        CASE "b": RETURN {type: "float", properties: ["transform", "box-shadow"], transform: "translateY(-4px)"}
+        CASE "c": RETURN {type: "scale", properties: ["transform"], transform: "scale(1.02)"}
+        CASE "d": RETURN {type: "none", properties: []}
+
+FUNCTION MAP_INPUT_INTERACTION(option):
+    SWITCH option:
+        CASE "a": RETURN {enabled: ["focus"], focus: {properties: ["border-color", "box-shadow"]}}
+        CASE "b": RETURN {enabled: ["error"], error: {animation: "shake", keyframes: "translateX"}}
+        CASE "c": RETURN {enabled: ["success"], success: {animation: "checkmark", keyframes: "draw"}}
+        CASE "d": RETURN {enabled: ["focus", "error", "success"]}
+        CASE "e": RETURN {enabled: []}
+
+FUNCTION MAP_PAGE_TRANSITIONS(option):
+    SWITCH option:
+        CASE "a": RETURN {enabled: true, style: "fade", animation: "fadeIn/fadeOut"}
+        CASE "b": RETURN {enabled: true, style: "slide", animation: "slideLeft/slideRight"}
+        CASE "c": RETURN {enabled: true, style: "zoom", animation: "zoomIn/zoomOut"}
+        CASE "d": RETURN {enabled: false}
+
+FUNCTION MAP_LOADING_STATES(option):
+    SWITCH option:
+        CASE "a": RETURN {style: "spinner", animation: "rotate", keyframes: "360deg"}
+        CASE "b": RETURN {style: "pulse", animation: "pulse", keyframes: "opacity"}
+        CASE "c": RETURN {style: "skeleton", animation: "shimmer", keyframes: "gradient-shift"}
+        CASE "d": RETURN {style: "progress", animation: "fill", keyframes: "width"}
+
+FUNCTION MAP_SCROLL_ANIMATIONS(option):
+    SWITCH option:
+        CASE "a": RETURN {enabled: true, style: "fade", animation: "fadeIn"}
+        CASE "b": RETURN {enabled: true, style: "slideUp", animation: "slideUp", transform: "translateY(20px)"}
+        CASE "c": RETURN {enabled: true, style: "scaleIn", animation: "scaleIn", transform: "scale(0.9)"}
+        CASE "d": RETURN {enabled: true, style: "stagger", animation: "fadeIn", stagger_delay: "100ms"}
+        CASE "e": RETURN {enabled: false}
+
+# Write specification file
+output_path = "{base_path}/.intermediates/animation-analysis/animation-specification.json"
+Write(output_path, JSON.stringify(specification, indent=2))
+
+REPORT: "✅ Animation specification saved to {output_path}"
+REPORT: "   Proceeding to token synthesis..."
 ```
 
 ---
 
 **Phase 2 Output**: `animation-specification.json` (user preferences)
 
-## Phase 3: Animation Token Synthesis (Agent)
+## Phase 3: Animation Token Synthesis (Agent - No User Interaction)
 
 **Executor**: `Task(ui-design-agent)` for token generation
 
+**⚠️ CRITICAL**: This phase has NO user interaction. Agent only reads existing data and generates tokens.
+
 ### Step 1: Load All Input Sources
 
 ```bash
@@ -305,61 +495,96 @@ IF animations_extracted:
 user_specification = null
 IF exists({base_path}/.intermediates/animation-analysis/animation-specification.json):
     user_specification = Read(file)
+    REPORT: "✅ Loaded user specification from Phase 2"
+ELSE:
+    REPORT: "⚠️ No user specification found - using extracted CSS only"
 
 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
+### Step 2: Launch Token Generation Task (Pure Synthesis)
 
 ```javascript
 Task(ui-design-agent): `
   [ANIMATION_TOKEN_GENERATION_TASK]
-  Synthesize all animation data into production-ready animation tokens
+  Synthesize animation data into production-ready tokens - NO user interaction
 
   SESSION: {session_id} | BASE_PATH: {base_path}
 
-  ## Input Sources
+  ## ⚠️ CRITICAL: Pure Synthesis Task
-  1. Extracted CSS Animations: {JSON.stringify(extracted_animations) OR "None"}
+  - NO user questions or interaction
-  2. User Specification: {JSON.stringify(user_specification) OR "None"}
+  - READ existing specification files ONLY
-  3. Design Tokens Context: {JSON.stringify(design_tokens) OR "None"}
+  - Generate tokens based on available data
+
+  ## Input Sources (Read-Only)
+  1. **Extracted CSS Animations** (if available):
+     ${extracted_animations.length > 0 ? JSON.stringify(extracted_animations) : "None - skip CSS data"}
+
+  2. **User Specification** (REQUIRED if Phase 2 ran):
+     File: {base_path}/.intermediates/animation-analysis/animation-specification.json
+     ${user_specification ? "Status: ✅ Found - READ this file for user choices" : "Status: ⚠️ Not found - use CSS extraction only"}
+
+  3. **Design Tokens Context** (for alignment):
+     ${design_tokens ? JSON.stringify(design_tokens) : "None - standalone animation system"}
 
   ## Synthesis Rules
 
   ### Priority System
-  1. User specification (highest priority)
+  1. User specification from animation-specification.json (highest priority)
-  2. Extracted CSS values (medium priority)
+  2. Extracted CSS values from animations-*.json (medium priority)
   3. Industry best practices (fallback)
 
   ### Duration Normalization
-  - Analyze all extracted durations
+  - IF user_specification.timing_scale EXISTS:
-  - Cluster into 3-5 semantic scales: instant, fast, normal, slow, very-slow
+      Use user's chosen scale (fast/balanced/smooth/custom)
+  - ELSE IF extracted CSS durations available:
+      Cluster extracted durations into 3-5 semantic scales
+  - ELSE:
+      Use standard scale (instant:0ms, fast:150ms, normal:300ms, slow:500ms, very-slow:800ms)
   - Align with design token spacing scale if available
 
   ### Easing Standardization
-  - Identify common easing functions from extracted data
+  - IF user_specification.easing_philosophy EXISTS:
-  - Map to semantic names: linear, ease-in, ease-out, ease-in-out, spring
+      Use user's chosen philosophy (linear/ease-out/ease-in-out/spring)
-  - Convert all cubic-bezier values to standard format
+  - ELSE IF extracted CSS easings available:
+      Identify common easing functions from CSS
+  - ELSE:
+      Use standard easings
+  - Map to semantic names and convert to cubic-bezier format
 
   ### Animation Categorization
   Organize into:
-  - transitions: Property-specific transitions (color, transform, opacity)
+  - **duration**: Timing scale (instant, fast, normal, slow, very-slow)
-  - keyframe_animations: Named @keyframe animations
+  - **easing**: Easing functions (linear, ease-in, ease-out, ease-in-out, spring)
-  - interactions: Interaction-specific presets (hover, focus, active)
+  - **transitions**: Property-specific transitions (color, transform, opacity, etc.)
-  - micro_interactions: Small feedback animations
+  - **keyframes**: Named @keyframe animations (fadeIn, slideInUp, pulse, etc.)
-  - page_transitions: Route/view change animations
+  - **interactions**: Interaction-specific presets (button-hover, card-hover, input-focus, etc.)
-  - scroll_animations: Scroll-triggered animations
+  - **page_transitions**: Route/view change animations (if user enabled)
+  - **scroll_animations**: Scroll-triggered animations (if user enabled)
+
+  ### User Specification Integration
+  IF user_specification EXISTS:
+    - Map user choices to token values:
+      * timing_scale → duration values
+      * easing_philosophy → easing curves
+      * interactions.button → interactions.button-hover token
+      * interactions.card → interactions.card-hover token
+      * interactions.input → micro-interaction tokens
+      * page_transitions → page_transitions tokens
+      * loading_animations → loading state tokens
+      * scroll_animations → scroll_animations tokens
 
   ## Generate Files
 
   ### 1. animation-tokens.json
-  Complete animation token structure:
+  Complete animation token structure using var() references:
 
   {
     "duration": {
       "instant": "0ms",
-      "fast": "150ms",
+      "fast": "150ms",      # Adjust based on user_specification.timing_scale
       "normal": "300ms",
       "slow": "500ms",
       "very-slow": "800ms"
@@ -367,7 +592,7 @@ Task(ui-design-agent): `
     "easing": {
       "linear": "linear",
       "ease-in": "cubic-bezier(0.4, 0, 1, 1)",
-      "ease-out": "cubic-bezier(0, 0, 0.2, 1)",
+      "ease-out": "cubic-bezier(0, 0, 0.2, 1)",      # Adjust based on user_specification.easing_philosophy
       "ease-in-out": "cubic-bezier(0.4, 0, 0.2, 1)",
       "spring": "cubic-bezier(0.34, 1.56, 0.64, 1)"
     },
@@ -389,66 +614,74 @@ Task(ui-design-agent): `
       }
     },
     "keyframes": {
-      "fadeIn": {
+      "fadeIn": {"0%": {"opacity": "0"}, "100%": {"opacity": "1"}},
-        "0%": {"opacity": "0"},
+      "slideInUp": {"0%": {"transform": "translateY(20px)", "opacity": "0"}, "100%": {"transform": "translateY(0)", "opacity": "1"}},
-        "100%": {"opacity": "1"}
+      "pulse": {"0%, 100%": {"opacity": "1"}, "50%": {"opacity": "0.7"}},
-      },
+      # Add more keyframes based on user_specification choices
-      "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": {
+        # Map from user_specification.interactions.button
         "properties": ["background-color", "transform"],
         "duration": "var(--duration-fast)",
         "easing": "var(--easing-ease-out)",
         "transform": "scale(1.02)"
       },
       "card-hover": {
+        # Map from user_specification.interactions.card
         "properties": ["box-shadow", "transform"],
         "duration": "var(--duration-normal)",
         "easing": "var(--easing-ease-out)",
         "transform": "translateY(-4px)"
       }
+      # Add input-focus, modal-open, dropdown-toggle based on user choices
     },
     "page_transitions": {
+      # IF user_specification.page_transitions.enabled == true
       "fade": {
         "duration": "var(--duration-normal)",
         "enter": "fadeIn",
         "exit": "fadeOut"
       }
+      # Add slide, zoom based on user_specification.page_transitions.style
     },
     "scroll_animations": {
+      # IF user_specification.scroll_animations.enabled == true
       "default": {
-        "animation": "fadeInUp",
+        "animation": "fadeIn",  # From user_specification.scroll_animations.style
         "duration": "var(--duration-slow)",
         "easing": "var(--easing-ease-out)",
         "threshold": "0.1",
-        "stagger_delay": "100ms"
+        "stagger_delay": "100ms"  # From user_specification if stagger chosen
       }
     }
   }
 
   ### 2. animation-guide.md
-  Comprehensive usage guide:
+  Comprehensive usage guide with sections:
-  - Animation philosophy and rationale
+  - **Animation Philosophy**: Rationale from user choices and CSS analysis
-  - Duration scale explanation
+  - **Duration Scale**: Explanation of timing values and usage contexts
-  - Easing function usage guidelines
+  - **Easing Functions**: When to use each easing curve
-  - Interaction animation patterns
+  - **Transition Presets**: Property-specific transition guidelines
-  - Implementation examples (CSS and JS)
+  - **Keyframe Animations**: Available animations and use cases
-  - Accessibility considerations (prefers-reduced-motion)
+  - **Interaction Patterns**: Button, card, input animation examples
-  - Performance best practices
+  - **Page Transitions**: Route change animation implementation (if enabled)
+  - **Scroll Animations**: Scroll-trigger setup and configuration (if enabled)
+  - **Implementation Examples**: CSS and JavaScript code samples
+  - **Accessibility**: prefers-reduced-motion media query setup
+  - **Performance Best Practices**: Hardware acceleration, will-change usage
+
+  ## Output File Paths
+  - animation-tokens.json: {base_path}/animation-extraction/animation-tokens.json
+  - animation-guide.md: {base_path}/animation-extraction/animation-guide.md
 
   ## Critical Requirements
+  - ✅ READ animation-specification.json if it exists (from Phase 2)
   - ✅ Use Write() tool immediately for both files
-  - ✅ Ensure all tokens use CSS Custom Property format: var(--duration-fast)
+  - ✅ All tokens use CSS Custom Property format: var(--duration-fast)
   - ✅ Include prefers-reduced-motion media query guidance
-  - ✅ Validate all cubic-bezier values are valid
+  - ✅ Validate all cubic-bezier values are valid (4 numbers between 0-1)
+  - ❌ NO user questions or interaction in this phase
   - ❌ NO external research or MCP calls
 `
 ```
@@ -487,8 +720,8 @@ bash(ls -lh {base_path}/animation-extraction/)
 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: "Interactive specification (main flow)", status: "completed", activeForm: "Collecting user input in main flow"},
-  {content: "Animation token synthesis (agent)", status: "completed", activeForm: "Generating tokens"},
+  {content: "Animation token synthesis (agent - no interaction)", status: "completed", activeForm: "Generating tokens via agent"},
   {content: "Verify output files", status: "completed", activeForm: "Verifying files"}
 ]});
 ```
@@ -506,7 +739,7 @@ Configuration:
   - ✅ CSS extracted from {len(url_list)} URL(s)
   }
   {IF user_specification:
-  - ✅ User specification via interactive mode
+  - ✅ User specification via interactive mode (main flow)
   }
   {IF has_design_context:
   - ✅ Aligned with existing design tokens
@@ -652,11 +885,12 @@ ERROR: Invalid cubic-bezier values
 
 - **Auto-Trigger CSS Extraction** - Automatically extracts animations when --urls provided
 - **Hybrid Strategy** - Combines CSS extraction with interactive specification
+- **Main Flow Interaction** - User questions in main flow, agent only for token synthesis
 - **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
+- **Separated Concerns** - User decisions (Phase 2 main flow) → Token generation (Phase 3 agent)
 
 ## Integration
 

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

@@ -129,7 +129,10 @@ Task(ui-design-agent): `
   ## Reference
   - Layout inspiration: Read("{base_path}/.intermediates/layout-analysis/inspirations/{target}-layout-ideas.txt")
   - Design tokens: Read("{base_path}/style-extraction/style-{style_id}/design-tokens.json")
-    Parse ALL token values (colors, typography, spacing, borders, shadows, breakpoints)
+    Parse ALL token values including:
+    * colors, typography (with combinations), spacing, opacity
+    * border_radius, shadows, breakpoints
+    * component_styles (button, card, input variants)
   ${design_attributes ? "- Adapt DOM to: density, visual_weight, formality, organic_vs_geometric" : ""}
 
   ## Generation
@@ -152,14 +155,16 @@ Task(ui-design-agent): `
 
   2. CSS: {base_path}/prototypes/{target}-style-{style_id}-layout-N.css
      - Self-contained: Direct token VALUES (no var())
-     - Use tokens: colors, fonts, spacing, borders, shadows
+     - Use tokens: colors, fonts, spacing, opacity, borders, shadows
+     - IF tokens.component_styles exists: Use component presets for buttons, cards, inputs
+     - IF tokens.typography.combinations exists: Use typography presets for headings and body text
      - Device-optimized: {device_type} styles
      ${device_type === 'responsive' ? '- Responsive: Mobile-first @media' : '- Fixed: ' + device_type}
      ${design_attributes ? `
      - Token selection: density → spacing, visual_weight → shadows` : ""}
 
   ## Notes
-  - ✅ Token VALUES directly from design-tokens.json
+  - ✅ Token VALUES directly from design-tokens.json (with typography.combinations, opacity, component_styles support)
   - ✅ Follow prompt requirements for {target}
   - ✅ Optimize for {device_type}
   - ❌ NO var() refs, NO external deps

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

@@ -205,7 +205,7 @@ ELSE IF --prompt:
     target_source = "prompt_analysis"
 
 # Step 4: Session synthesis
-ELSE IF --session AND exists(synthesis-specification.md):
+ELSE IF --session AND exists(role analysis documents):
     target_list = extract_targets_from_synthesis(); target_type = "page"; target_source = "synthesis"
 
 # Step 5: Fallback

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

@@ -99,7 +99,11 @@ Task(ui-design-agent): `
 
   2. Design Tokens:
      Read("{base_path}/style-extraction/style-{style_id}/design-tokens.json")
-     Extract: ALL token values (colors, typography, spacing, borders, shadows, breakpoints)
+     Extract: ALL token values including:
+       * colors, typography (with combinations), spacing, opacity
+       * border_radius, shadows, breakpoints
+       * component_styles (button, card, input variants)
+     Note: typography.combinations, opacity, and component_styles fields contain preset configurations using var() references
 
   3. Animation Tokens (OPTIONAL):
      IF exists("{base_path}/animation-extraction/animation-tokens.json"):
@@ -133,11 +137,21 @@ Task(ui-design-agent): `
      - Replace ALL var(--*) with actual token values from design-tokens.json
        Example: var(--spacing-4) → 1rem (from tokens.spacing.4)
        Example: var(--breakpoint-md) → 768px (from tokens.breakpoints.md)
+       Example: var(--opacity-80) → 0.8 (from tokens.opacity.80)
      - Add visual styling using design tokens:
        * Colors: tokens.colors.*
-       * Typography: tokens.typography.*
+       * Typography: tokens.typography.* (including combinations)
+       * Opacity: tokens.opacity.*
        * Shadows: tokens.shadows.*
        * Border radius: tokens.border_radius.*
+     - IF tokens.component_styles exists: Add component style classes
+       * Generate classes for button variants (.btn-primary, .btn-secondary)
+       * Generate classes for card variants (.card-default, .card-interactive)
+       * Generate classes for input variants (.input-default, .input-focus, .input-error)
+       * Use var() references that resolve to actual token values
+     - IF tokens.typography.combinations exists: Add typography preset classes
+       * Generate classes for typography presets (.text-heading-primary, .text-body-regular, .text-caption)
+       * Use var() references for family, size, weight, line-height, letter-spacing
      - IF has_animations == true: Inject animation tokens
        * Add CSS Custom Properties for animations at :root level:
          --duration-instant, --duration-fast, --duration-normal, etc.

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

@@ -154,7 +154,7 @@ IF exists: SKIP to completion
 ### Step 2: Load Project Context (Explore Mode)
 ```bash
 # Load brainstorming context if available
-bash(test -f {base_path}/.brainstorming/synthesis-specification.md && cat it)
+bash(test -f {base_path}/.brainstorming/role analysis documents && cat it)
 ```
 
 ### Step 3: Generate Design Direction Options (Agent Task 1)
@@ -418,17 +418,33 @@ Task(ui-design-agent): `
   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)
+     - Complete token structure with ALL fields:
+       * colors (brand, surface, semantic, text, border) - OKLCH format
+       * typography (families, sizes, weights, line heights, letter spacing, combinations)
+       * typography.combinations: Predefined typography presets (heading-primary, heading-secondary, body-regular, body-emphasis, caption, label) using var() references
+       * spacing (0-24 scale)
+       * opacity (0, 10, 20, 40, 60, 80, 90, 100)
+       * border_radius (none to full)
+       * shadows (sm to xl)
+       * component_styles (button, card, input variants) - component presets using var() references
+       * 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" : ""}
+     - Common Tailwind CSS usage patterns in project (if extracting from existing project)
 
   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
+     - Typography Combinations section: Document each preset (heading-primary, heading-secondary, body-regular, body-emphasis, caption, label) with usage context and code examples
      - Spacing system explanation
+     - Opacity & Transparency section: Opacity scale usage, common use cases (disabled states, overlays, hover effects), accessibility considerations
+     - Shadows & Elevation section: Shadow hierarchy and semantic usage
+     - Component Styles section: Document button, card, and input variants with code examples and visual descriptions
+     - Border Radius system and semantic usage
      - Component examples and usage patterns
+     - Common Tailwind CSS patterns (if applicable)
 
   ## Critical Requirements
   - ✅ Use Write() tool immediately for each file
@@ -541,7 +557,7 @@ bash(cat {base_path}/style-extraction/style-1/design-tokens.json | grep -q "colo
 ### File Operations
 ```bash
 # Load brainstorming context
-bash(test -f .brainstorming/synthesis-specification.md && cat it)
+bash(test -f .brainstorming/role analysis documents && cat it)
 
 # Create directories
 bash(mkdir -p {base_path}/style-extraction/style-{{1..3}})
@@ -577,15 +593,46 @@ bash(test -f {base_path}/.intermediates/style-analysis/analysis-options.json &&
     "text": {"primary": "oklch(...)", "secondary": "oklch(...)", "tertiary": "oklch(...)", "inverse": "oklch(...)"},
     "border": {"default": "oklch(...)", "strong": "oklch(...)", "subtle": "oklch(...)"}
   },
-  "typography": {"font_family": {...}, "font_size": {...}, "font_weight": {...}, "line_height": {...}, "letter_spacing": {...}},
+  "typography": {
+    "font_family": {...},
+    "font_size": {...},
+    "font_weight": {...},
+    "line_height": {...},
+    "letter_spacing": {...},
+    "combinations": {
+      "heading-primary": {"family": "var(--font-family-heading)", "size": "var(--font-size-3xl)", "weight": "var(--font-weight-bold)", "line_height": "var(--line-height-tight)", "letter_spacing": "var(--letter-spacing-tight)"},
+      "heading-secondary": {...},
+      "body-regular": {...},
+      "body-emphasis": {...},
+      "caption": {...},
+      "label": {...}
+    }
+  },
   "spacing": {"0": "0", "1": "0.25rem", ..., "24": "6rem"},
+  "opacity": {"0": "0", "10": "0.1", "20": "0.2", "40": "0.4", "60": "0.6", "80": "0.8", "90": "0.9", "100": "1"},
   "border_radius": {"none": "0", "sm": "0.25rem", ..., "full": "9999px"},
   "shadows": {"sm": "...", "md": "...", "lg": "...", "xl": "..."},
+  "component_styles": {
+    "button": {
+      "primary": {"background": "var(--color-brand-primary)", "color": "var(--color-text-inverse)", "padding": "var(--spacing-3) var(--spacing-6)", "border_radius": "var(--border-radius-md)", "font_weight": "var(--font-weight-semibold)"},
+      "secondary": {...},
+      "tertiary": {...}
+    },
+    "card": {
+      "default": {"background": "var(--color-surface-elevated)", "padding": "var(--spacing-6)", "border_radius": "var(--border-radius-lg)", "shadow": "var(--shadow-md)"},
+      "interactive": {...}
+    },
+    "input": {
+      "default": {"border": "1px solid var(--color-border-default)", "padding": "var(--spacing-3)", "border_radius": "var(--border-radius-md)", "background": "var(--color-surface-background)"},
+      "focus": {...},
+      "error": {...}
+    }
+  },
   "breakpoints": {"sm": "640px", ..., "2xl": "1536px"}
 }
 ```
 
-**Requirements**: OKLCH colors, complete coverage, semantic naming, WCAG AA compliance
+**Requirements**: OKLCH colors, complete coverage, semantic naming, WCAG AA compliance, typography combinations, component style presets, opacity scale
 
 ## Error Handling
 

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

@@ -15,7 +15,7 @@ Synchronize finalized design system references to brainstorming artifacts, prepa
 
 - **Reference-Only Updates**: Use @ references, no content duplication
 - **Main Claude Execution**: Direct updates by main Claude (no Agent handoff)
-- **Synthesis Alignment**: Update synthesis-specification.md UI/UX Guidelines section
+- **Synthesis Alignment**: Update role analysis documents UI/UX Guidelines section
 - **Plan-Ready Output**: Ensure design artifacts discoverable by task-generate
 - **Minimal Reading**: Verify file existence, don't read design content
 
@@ -50,8 +50,8 @@ REPORT: "Found {count} design artifacts, {prototype_count} prototypes"
 ### Phase 1.1: Memory Check (Skip if Already Updated)
 
 ```bash
-# Check if synthesis-specification.md contains current design run reference
+# Check if role analysis documents contains current design run reference
-synthesis_spec_path = ".workflow/WFS-{session}/.brainstorming/synthesis-specification.md"
+synthesis_spec_path = ".workflow/WFS-{session}/.brainstorming/role analysis documents"
 current_design_run = basename(latest_design)  # e.g., "design-run-20250109-143022"
 
 IF exists(synthesis_spec_path):
@@ -68,7 +68,7 @@ IF exists(synthesis_spec_path):
 
 ```bash
 # Load target brainstorming artifacts (files to be updated)
-Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)
+Read(.workflow/WFS-{session}/.brainstorming/role analysis documents)
 IF exists(.workflow/WFS-{session}/.brainstorming/ui-designer/analysis.md): Read(analysis.md)
 
 # Optional: Read prototype notes for descriptions (minimal context)
@@ -80,7 +80,7 @@ FOR each selected_prototype IN selected_list:
 
 ### Phase 3: Update Synthesis Specification
 
-Update `.brainstorming/synthesis-specification.md` with design system references.
+Update `.brainstorming/role analysis documents` with design system references.
 
 **Target Section**: `## UI/UX Guidelines`
 
@@ -113,7 +113,7 @@ Update `.brainstorming/synthesis-specification.md` with design system references
 **Implementation**:
 ```bash
 # Option 1: Edit existing section
-Edit(file_path=".workflow/WFS-{session}/.brainstorming/synthesis-specification.md",
+Edit(file_path=".workflow/WFS-{session}/.brainstorming/role analysis documents",
      old_string="## UI/UX Guidelines\n[existing content]",
      new_string="## UI/UX Guidelines\n\n[new design reference content]")
 
@@ -122,12 +122,77 @@ IF section not found:
     Edit(file_path="...", old_string="[end of document]", new_string="\n\n## UI/UX Guidelines\n\n[new design reference content]")
 ```
 
-### Phase 4: Update UI Designer Style Guide
+### Phase 4A: Update Relevant Role Analysis Documents
 
-Create or update `.brainstorming/ui-designer/style-guide.md`:
+**Discovery**: Find role analysis.md files affected by design outputs
+
+```bash
+# Always update ui-designer
+ui_designer_files = Glob(".workflow/WFS-{session}/.brainstorming/ui-designer/analysis*.md")
+
+# Conditionally update other roles
+has_animations = exists({latest_design}/animation-extraction/animation-tokens.json)
+has_layouts = exists({latest_design}/layout-extraction/layout-templates.json)
+
+IF has_animations: ux_expert_files = Glob(".workflow/WFS-{session}/.brainstorming/ux-expert/analysis*.md")
+IF has_layouts: architect_files = Glob(".workflow/WFS-{session}/.brainstorming/system-architect/analysis*.md")
+IF selected_list: pm_files = Glob(".workflow/WFS-{session}/.brainstorming/product-manager/analysis*.md")
+```
+
+**Content Templates**:
+
+**ui-designer/analysis.md** (append if not exists):
+```markdown
+## Design System Implementation Reference
+
+**Design Tokens**: @../../design-{run_id}/{design_tokens_path}
+**Style Guide**: @../../design-{run_id}/{style_guide_path}
+**Prototypes**: {FOR each: @../../design-{run_id}/prototypes/{prototype}.html}
+
+*Reference added by /workflow:ui-design:update*
+```
+
+**ux-expert/analysis.md** (if animations):
+```markdown
+## Animation & Interaction Reference
+
+**Animations**: @../../design-{run_id}/animation-extraction/animation-tokens.json
+**Prototypes**: {FOR each: @../../design-{run_id}/prototypes/{prototype}.html}
+
+*Reference added by /workflow:ui-design:update*
+```
+
+**system-architect/analysis.md** (if layouts):
+```markdown
+## Layout Structure Reference
+
+**Layout Templates**: @../../design-{run_id}/layout-extraction/layout-templates.json
+
+*Reference added by /workflow:ui-design:update*
+```
+
+**product-manager/analysis.md** (if prototypes):
+```markdown
+## Prototype Validation Reference
+
+**Prototypes**: {FOR each: @../../design-{run_id}/prototypes/{prototype}.html}
+
+*Reference added by /workflow:ui-design:update*
+```
+
+**Implementation**:
+```bash
+FOR file IN [ui_designer_files, ux_expert_files, architect_files, pm_files]:
+  IF file exists AND section_not_exists(file):
+    Edit(file, old_string="[end of document]", new_string="\n\n{role-specific section}")
+```
+
+### Phase 4B: Create UI Designer Design System Reference
+
+Create or update `.brainstorming/ui-designer/design-system-reference.md`:
 
 ```markdown
-# UI Designer Style Guide
+# UI Designer Design System Reference
 
 ## Design System Integration
 This style guide references the finalized design system from the design refinement phase.
@@ -158,7 +223,7 @@ For complete token definitions and usage examples, see:
 
 **Implementation**:
 ```bash
-Write(file_path=".workflow/WFS-{session}/.brainstorming/ui-designer/style-guide.md",
+Write(file_path=".workflow/WFS-{session}/.brainstorming/ui-designer/design-system-reference.md",
       content="[generated content with @ references]")
 ```
 
@@ -168,8 +233,9 @@ Write(file_path=".workflow/WFS-{session}/.brainstorming/ui-designer/style-guide.
 TodoWrite({todos: [
   {content: "Validate session and design system artifacts", status: "completed", activeForm: "Validating artifacts"},
   {content: "Load target brainstorming artifacts", status: "completed", activeForm: "Loading target files"},
-  {content: "Update synthesis-specification.md with design references", status: "completed", activeForm: "Updating synthesis spec"},
+  {content: "Update role analysis documents with design references", status: "completed", activeForm: "Updating synthesis spec"},
-  {content: "Create/update ui-designer/style-guide.md", status: "completed", activeForm: "Updating UI designer guide"}
+  {content: "Update relevant role analysis.md documents", status: "completed", activeForm: "Updating role analysis files"},
+  {content: "Create/update ui-designer/design-system-reference.md", status: "completed", activeForm: "Creating design system reference"}
 ]});
 ```
 
@@ -178,8 +244,9 @@ TodoWrite({todos: [
 ✅ Design system references updated for session: WFS-{session}
 
 Updated artifacts:
-✓ synthesis-specification.md - UI/UX Guidelines section with @ references
+✓ role analysis documents - UI/UX Guidelines section with @ references
-✓ ui-designer/style-guide.md - Design system reference guide
+✓ {role_count} role analysis.md files - Design system references
+✓ ui-designer/design-system-reference.md - Design system reference guide
 
 Design system assets ready for /workflow:plan:
 - design-tokens.json | style-guide.md | {prototype_count} reference prototypes
@@ -193,31 +260,43 @@ Next: /workflow:plan [--agent] "<task description>"
 **Updated Files**:
 ```
 .workflow/WFS-{session}/.brainstorming/
-├── synthesis-specification.md       # Updated with UI/UX Guidelines section
+├── role analysis documents              # Updated with UI/UX Guidelines section
-└── ui-designer/
+├── ui-designer/
-    └── style-guide.md               # New or updated design reference guide
+│   ├── analysis*.md                     # Updated with design system references
+│   └── design-system-reference.md       # New or updated design reference guide
+├── ux-expert/analysis*.md               # Updated if animations exist
+├── product-manager/analysis*.md         # Updated if prototypes exist
+└── system-architect/analysis*.md        # Updated if layouts exist
 ```
 
-**@ Reference Format** (synthesis-specification.md):
+**@ Reference Format** (role analysis documents):
 ```
 @../design-{run_id}/style-extraction/style-1/design-tokens.json
 @../design-{run_id}/style-extraction/style-1/style-guide.md
 @../design-{run_id}/prototypes/{prototype}.html
 ```
 
-**@ Reference Format** (ui-designer/style-guide.md):
+**@ Reference Format** (ui-designer/design-system-reference.md):
 ```
 @../../design-{run_id}/style-extraction/style-1/design-tokens.json
 @../../design-{run_id}/style-extraction/style-1/style-guide.md
 @../../design-{run_id}/prototypes/{prototype}.html
 ```
 
+**@ Reference Format** (role analysis.md files):
+```
+@../../design-{run_id}/style-extraction/style-1/design-tokens.json
+@../../design-{run_id}/animation-extraction/animation-tokens.json
+@../../design-{run_id}/layout-extraction/layout-templates.json
+@../../design-{run_id}/prototypes/{prototype}.html
+```
+
 ## Integration with /workflow:plan
 
 After this update, `/workflow:plan` will discover design assets through:
 
 **Phase 3: Intelligent Analysis** (`/workflow:tools:concept-enhanced`)
-- Reads synthesis-specification.md → Discovers @ references → Includes design system context in ANALYSIS_RESULTS.md
+- Reads role analysis documents → Discovers @ references → Includes design system context in ANALYSIS_RESULTS.md
 
 **Phase 4: Task Generation** (`/workflow:tools:task-generate`)
 - Reads ANALYSIS_RESULTS.md → Discovers design assets → Includes design system paths in task JSON files
@@ -239,7 +318,7 @@ After this update, `/workflow:plan` will discover design assets through:
 ## Error Handling
 
 - **Missing design artifacts**: Error with message "Run /workflow:ui-design:style-extract and /workflow:ui-design:generate first"
-- **synthesis-specification.md not found**: Warning, create minimal version with just UI/UX Guidelines
+- **role analysis documents not found**: Warning, create minimal version with just UI/UX Guidelines
 - **ui-designer/ directory missing**: Create directory and file
 - **Edit conflicts**: Preserve existing content, append or replace only UI/UX Guidelines section
 - **Invalid prototype names**: Skip invalid entries, continue with valid ones
@@ -247,9 +326,11 @@ After this update, `/workflow:plan` will discover design assets through:
 ## Validation Checks
 
 After update, verify:
-- [ ] synthesis-specification.md contains UI/UX Guidelines section
+- [ ] role analysis documents contains UI/UX Guidelines section
 - [ ] UI/UX Guidelines include @ references (not content duplication)
-- [ ] ui-designer/style-guide.md created or updated
+- [ ] ui-designer/analysis*.md updated with design system references
+- [ ] ui-designer/design-system-reference.md created or updated
+- [ ] Relevant role analysis.md files updated (ux-expert, product-manager, system-architect)
 - [ ] All @ referenced files exist and are accessible
 - [ ] @ reference paths are relative and correct
 
@@ -264,7 +345,7 @@ After update, verify:
 ## Integration Points
 
 - **Input**: Design system artifacts from `/workflow:ui-design:style-extract` and `/workflow:ui-design:generate`
-- **Output**: Updated synthesis-specification.md, ui-designer/style-guide.md with @ references
+- **Output**: Updated role analysis documents, role analysis.md files, ui-designer/design-system-reference.md with @ references
 - **Next Phase**: `/workflow:plan` discovers and utilizes design system through @ references
 - **Auto Integration**: Automatically triggered by `/workflow:ui-design:auto` workflow
 

.claude/scripts/gemini-wrapper

@@ -1,288 +0,0 @@
-#!/bin/bash
-# gemini-wrapper - Token-aware wrapper for gemini command
-# Location: ~/.claude/scripts/gemini-wrapper
-#
-# This wrapper automatically manages --all-files flag based on project token count
-# and provides intelligent approval mode defaults
-#
-# Usage: gemini-wrapper [all gemini options]
-#
-# Approval Mode Options:
-#   --approval-mode default    : Prompt for approval on each tool call (default)
-#   --approval-mode auto_edit  : Auto-approve edit tools, prompt for others
-#   --approval-mode yolo       : Auto-approve all tool calls
-#
-# Note: Executes in current working directory
-
-set -e
-
-# Function to show help
-show_help() {
-    echo "gemini-wrapper - Token-aware wrapper for gemini command"
-    echo ""
-    echo "Usage: gemini-wrapper [options] [gemini options]"
-    echo ""
-    echo "Options:"
-    echo "  --approval-mode <mode>  Sets the approval mode for tool calls"
-    echo "                          Available modes:"
-    echo "                            default    : Prompt for approval on each tool call (default)"
-    echo "                            auto_edit  : Auto-approve edit tools, prompt for others"
-    echo "                            yolo       : Auto-approve all tool calls"
-    echo "  --help                  Show this help message"
-    echo ""
-    echo "Features:"
-    echo "  - Automatically manages --all-files flag based on project token count"
-    echo "  - Intelligent approval mode detection based on task type"
-    echo "  - Token limit: $DEFAULT_TOKEN_LIMIT (set GEMINI_TOKEN_LIMIT to override)"
-    echo ""
-    echo "Examples:"
-    echo "  gemini-wrapper -p \"Analyze the codebase structure\""
-    echo "  gemini-wrapper --approval-mode yolo -p \"Implement user authentication\""
-    echo "  gemini-wrapper --approval-mode auto_edit -p \"Fix all linting errors\""
-    echo ""
-}
-
-# Configuration
-DEFAULT_TOKEN_LIMIT=2000000
-TOKEN_LIMIT=${GEMINI_TOKEN_LIMIT:-$DEFAULT_TOKEN_LIMIT}
-
-# Colors for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-NC='\033[0m' # No Color
-
-# Respect custom Gemini base URL
-if [[ -n "$GOOGLE_GEMINI_BASE_URL" ]]; then
-    echo -e "${GREEN}🌐 Using custom Gemini base URL: $GOOGLE_GEMINI_BASE_URL${NC}" >&2
-    export GOOGLE_GEMINI_BASE_URL
-fi
-
-# Function to count tokens (approximate: chars/4) - optimized version
-count_tokens() {
-    local total_chars=0
-    local file_count=0
-
-    # Use single find with bulk wc for better performance
-    # Common source file extensions
-    local extensions="py js ts tsx jsx java cpp c h rs go md txt json yaml yml xml html css scss sass php rb sh bash"
-
-    # Build find command with extension patterns
-    local find_cmd="find . -type f \("
-    local first=true
-    for ext in $extensions; do
-        if [[ "$first" == true ]]; then
-            find_cmd+=" -name \"*.$ext\""
-            first=false
-        else
-            find_cmd+=" -o -name \"*.$ext\""
-        fi
-    done
-    find_cmd+=" \)"
-
-    # Exclude common build/cache directories
-    find_cmd+=" -not -path \"*/node_modules/*\""
-    find_cmd+=" -not -path \"*/.git/*\""
-    find_cmd+=" -not -path \"*/dist/*\""
-    find_cmd+=" -not -path \"*/build/*\""
-    find_cmd+=" -not -path \"*/.next/*\""
-    find_cmd+=" -not -path \"*/.nuxt/*\""
-    find_cmd+=" -not -path \"*/target/*\""
-    find_cmd+=" -not -path \"*/vendor/*\""
-    find_cmd+=" -not -path \"*/__pycache__/*\""
-    find_cmd+=" -not -path \"*/.cache/*\""
-    find_cmd+=" 2>/dev/null"
-
-    # Use efficient bulk processing with wc
-    if command -v wc >/dev/null 2>&1; then
-        # Try bulk wc first - much faster for many files
-        local wc_output
-        wc_output=$(eval "$find_cmd" | xargs wc -c 2>/dev/null | tail -n 1)
-
-        # Parse the total line (last line of wc output when processing multiple files)
-        if [[ -n "$wc_output" && "$wc_output" =~ ^[[:space:]]*([0-9]+)[[:space:]]+total[[:space:]]*$ ]]; then
-            total_chars="${BASH_REMATCH[1]}"
-            file_count=$(eval "$find_cmd" | wc -l 2>/dev/null || echo 0)
-        else
-            # Fallback: single file processing
-            while IFS= read -r file; do
-                if [[ -f "$file" && -r "$file" ]]; then
-                    local chars=$(wc -c < "$file" 2>/dev/null || echo 0)
-                    total_chars=$((total_chars + chars))
-                    file_count=$((file_count + 1))
-                fi
-            done < <(eval "$find_cmd")
-        fi
-    else
-        # No wc available - fallback method
-        while IFS= read -r file; do
-            if [[ -f "$file" && -r "$file" ]]; then
-                local chars=$(stat -c%s "$file" 2>/dev/null || echo 0)
-                total_chars=$((total_chars + chars))
-                file_count=$((file_count + 1))
-            fi
-        done < <(eval "$find_cmd")
-    fi
-
-    local estimated_tokens=$((total_chars / 4))
-    echo "$estimated_tokens $file_count"
-}
-
-# Function to validate approval mode
-validate_approval_mode() {
-    local mode="$1"
-    case "$mode" in
-        "default"|"auto_edit"|"yolo")
-            return 0
-            ;;
-        *)
-            echo -e "${RED}❌ Invalid approval mode: $mode${NC}" >&2
-            echo -e "${YELLOW}Valid modes: default, auto_edit, yolo${NC}" >&2
-            return 1
-            ;;
-    esac
-}
-
-# Parse arguments to check for flags
-has_all_files=false
-has_approval_mode=false
-approval_mode_value=""
-args=()
-i=0
-
-# Parse arguments with proper handling of --approval-mode value
-args=("$@")  # Start with all arguments
-parsed_args=()
-skip_next=false
-
-for ((i=0; i<${#args[@]}; i++)); do
-    if [[ "$skip_next" == true ]]; then
-        skip_next=false
-        continue
-    fi
-
-    arg="${args[i]}"
-    case "$arg" in
-        "--help"|"-h")
-            show_help
-            exit 0
-            ;;
-        "--all-files")
-            has_all_files=true
-            parsed_args+=("$arg")
-            ;;
-        "--approval-mode")
-            has_approval_mode=true
-            # Get the next argument as the mode value
-            if [[ $((i+1)) -lt ${#args[@]} ]]; then
-                approval_mode_value="${args[$((i+1))]}"
-                if validate_approval_mode "$approval_mode_value"; then
-                    parsed_args+=("$arg" "$approval_mode_value")
-                    skip_next=true
-                else
-                    exit 1
-                fi
-            else
-                echo -e "${RED}❌ --approval-mode requires a value${NC}" >&2
-                echo -e "${YELLOW}Valid modes: default, auto_edit, yolo${NC}" >&2
-                exit 1
-            fi
-            ;;
-        --approval-mode=*)
-            has_approval_mode=true
-            approval_mode_value="${arg#*=}"
-            if validate_approval_mode "$approval_mode_value"; then
-                parsed_args+=("$arg")
-            else
-                exit 1
-            fi
-            ;;
-        *)
-            parsed_args+=("$arg")
-            ;;
-    esac
-done
-
-# Replace args with parsed_args
-args=("${parsed_args[@]}")
-
-# Analyze current working directory
-echo -e "${GREEN}📁 Analyzing current directory: $(pwd)${NC}" >&2
-
-# Count tokens (in the target directory if -c was used)
-echo -e "${YELLOW}🔍 Analyzing project size...${NC}" >&2
-read -r token_count file_count <<< "$(count_tokens)"
-
-echo -e "${YELLOW}📊 Project stats: ~${token_count} tokens across ${file_count} files${NC}" >&2
-
-# Decision logic for --all-files flag
-if [[ $token_count -lt $TOKEN_LIMIT ]]; then
-    if [[ "$has_all_files" == false ]]; then
-        echo -e "${GREEN}✅ Small project (${token_count} < ${TOKEN_LIMIT} tokens): Adding --all-files${NC}" >&2
-        args=("--all-files" "${args[@]}")
-    else
-        echo -e "${GREEN}✅ Small project (${token_count} < ${TOKEN_LIMIT} tokens): Keeping --all-files${NC}" >&2
-    fi
-else
-    if [[ "$has_all_files" == true ]]; then
-        echo -e "${RED}⚠️  Large project (${token_count} >= ${TOKEN_LIMIT} tokens): Removing --all-files to avoid token limits${NC}" >&2
-        echo -e "${YELLOW}💡 Consider using specific @{patterns} for targeted analysis${NC}" >&2
-        # Remove --all-files from args
-        new_args=()
-        for arg in "${args[@]}"; do
-            if [[ "$arg" != "--all-files" ]]; then
-                new_args+=("$arg")
-            fi
-        done
-        args=("${new_args[@]}")
-    else
-        echo -e "${RED}⚠️  Large project (${token_count} >= ${TOKEN_LIMIT} tokens): Avoiding --all-files${NC}" >&2
-        echo -e "${YELLOW}💡 Consider using specific @{patterns} for targeted analysis${NC}" >&2
-    fi
-fi
-
-# Auto-add approval-mode if not specified
-if [[ "$has_approval_mode" == false ]]; then
-    # Intelligent approval mode detection based on prompt content
-    prompt_text="${args[*]}"
-
-    # Analysis/Research tasks - use default (prompt for each tool)
-    if [[ "$prompt_text" =~ (analyze|analysis|review|understand|inspect|examine|research|study|explore|investigate) ]]; then
-        echo -e "${GREEN}📋 Analysis task detected: Adding --approval-mode default${NC}" >&2
-        args=("--approval-mode" "default" "${args[@]}")
-
-    # Development/Edit tasks - use auto_edit (auto-approve edits, prompt for others)
-    elif [[ "$prompt_text" =~ (implement|create|build|develop|code|write|edit|modify|update|fix|refactor|generate) ]]; then
-        echo -e "${GREEN}🔧 Development task detected: Adding --approval-mode auto_edit${NC}" >&2
-        args=("--approval-mode" "auto_edit" "${args[@]}")
-
-    # Automation/Batch tasks - use yolo (auto-approve all)
-    elif [[ "$prompt_text" =~ (automate|batch|mass|bulk|all|execute|run|deploy|install|setup) ]]; then
-        echo -e "${YELLOW}⚡ Automation task detected: Adding --approval-mode yolo${NC}" >&2
-        args=("--approval-mode" "yolo" "${args[@]}")
-
-    # Default fallback - use default mode for safety
-    else
-        echo -e "${YELLOW}🔍 General task detected: Adding --approval-mode default${NC}" >&2
-        args=("--approval-mode" "default" "${args[@]}")
-    fi
-
-    # Show approval mode explanation
-    case "${args[1]}" in
-        "default")
-            echo -e "${YELLOW}   → Will prompt for approval on each tool call${NC}" >&2
-            ;;
-        "auto_edit")
-            echo -e "${YELLOW}   → Will auto-approve edit tools, prompt for others${NC}" >&2
-            ;;
-        "yolo")
-            echo -e "${YELLOW}   → Will auto-approve all tool calls${NC}" >&2
-            ;;
-    esac
-fi
-
-# Show final command (for transparency)
-echo -e "${YELLOW}🚀 Executing: gemini ${args[*]}${NC}" >&2
-
-# Execute gemini with adjusted arguments (we're already in the right directory)
-gemini "${args[@]}"

.claude/scripts/qwen-wrapper

@@ -1,228 +0,0 @@
-#!/bin/bash
-# qwen-wrapper - Token-aware wrapper for qwen command
-# Location: ~/.claude/scripts/qwen-wrapper
-#
-# This wrapper automatically manages --all-files flag based on project token count
-# and provides intelligent approval mode defaults
-#
-# Usage: qwen-wrapper [all qwen options]
-#
-# Approval Mode Options:
-#   --approval-mode default    : Prompt for approval on each tool call (default)
-#   --approval-mode auto_edit  : Auto-approve edit tools, prompt for others
-#   --approval-mode yolo       : Auto-approve all tool calls
-#
-# Note: Executes in current working directory
-
-set -e
-
-# Function to show help
-show_help() {
-    echo "qwen-wrapper - Token-aware wrapper for qwen command"
-    echo ""
-    echo "Usage: qwen-wrapper [options] [qwen options]"
-    echo ""
-    echo "Options:"
-    echo "  --approval-mode <mode>  Sets the approval mode for tool calls"
-    echo "                          Available modes:"
-    echo "                            default    : Prompt for approval on each tool call (default)"
-    echo "                            auto_edit  : Auto-approve edit tools, prompt for others"
-    echo "                            yolo       : Auto-approve all tool calls"
-    echo "  --help                  Show this help message"
-    echo ""
-    echo "Features:"
-    echo "  - Automatically manages --all-files flag based on project token count"
-    echo "  - Intelligent approval mode detection based on task type"
-    echo "  - Token limit: $DEFAULT_TOKEN_LIMIT (set QWEN_TOKEN_LIMIT to override)"
-    echo ""
-    echo "Examples:"
-    echo "  qwen-wrapper -p \"Analyze the codebase structure\""
-    echo "  qwen-wrapper --approval-mode yolo -p \"Implement user authentication\""
-    echo "  qwen-wrapper --approval-mode auto_edit -p \"Fix all linting errors\""
-    echo ""
-}
-
-# Function to validate approval mode
-validate_approval_mode() {
-    local mode="$1"
-    case "$mode" in
-        "default"|"auto_edit"|"yolo")
-            return 0
-            ;;
-        *)
-            echo -e "${RED}❌ Invalid approval mode: $mode${NC}" >&2
-            echo -e "${YELLOW}Valid modes: default, auto_edit, yolo${NC}" >&2
-            return 1
-            ;;
-    esac
-}
-
-# Configuration
-DEFAULT_TOKEN_LIMIT=2000000
-TOKEN_LIMIT=${QWEN_TOKEN_LIMIT:-$DEFAULT_TOKEN_LIMIT}
-
-# Colors for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-NC='\033[0m' # No Color
-
-# Function to count tokens (approximate: chars/4)
-count_tokens() {
-    local total_chars=0
-    local file_count=0
-    
-    # Count characters in common source files
-    while IFS= read -r -d '' file; do
-        if [[ -f "$file" && -r "$file" ]]; then
-            local chars=$(wc -c < "$file" 2>/dev/null || echo 0)
-            total_chars=$((total_chars + chars))
-            file_count=$((file_count + 1))
-        fi
-    done < <(find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.tsx" -o -name "*.jsx" -o -name "*.java" -o -name "*.cpp" -o -name "*.c" -o -name "*.h" -o -name "*.rs" -o -name "*.go" -o -name "*.md" -o -name "*.txt" -o -name "*.json" -o -name "*.yaml" -o -name "*.yml" -o -name "*.xml" -o -name "*.html" -o -name "*.css" -o -name "*.scss" -o -name "*.sass" -o -name "*.php" -o -name "*.rb" -o -name "*.sh" -o -name "*.bash" \) -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/dist/*" -not -path "*/build/*" -not -path "*/.next/*" -not -path "*/.nuxt/*" -not -path "*/target/*" -not -path "*/vendor/*" -print0 2>/dev/null)
-    
-    local estimated_tokens=$((total_chars / 4))
-    echo "$estimated_tokens $file_count"
-}
-
-# Parse arguments to check for flags
-has_all_files=false
-has_approval_mode=false
-approval_mode_value=""
-
-# Parse arguments with proper handling of --approval-mode value
-args=("$@")  # Start with all arguments
-parsed_args=()
-skip_next=false
-
-for ((i=0; i<${#args[@]}; i++)); do
-    if [[ "$skip_next" == true ]]; then
-        skip_next=false
-        continue
-    fi
-
-    arg="${args[i]}"
-    case "$arg" in
-        "--help"|"-h")
-            show_help
-            exit 0
-            ;;
-        "--all-files")
-            has_all_files=true
-            parsed_args+=("$arg")
-            ;;
-        "--approval-mode")
-            has_approval_mode=true
-            # Get the next argument as the mode value
-            if [[ $((i+1)) -lt ${#args[@]} ]]; then
-                approval_mode_value="${args[$((i+1))]}"
-                if validate_approval_mode "$approval_mode_value"; then
-                    parsed_args+=("$arg" "$approval_mode_value")
-                    skip_next=true
-                else
-                    exit 1
-                fi
-            else
-                echo -e "${RED}❌ --approval-mode requires a value${NC}" >&2
-                echo -e "${YELLOW}Valid modes: default, auto_edit, yolo${NC}" >&2
-                exit 1
-            fi
-            ;;
-        --approval-mode=*)
-            has_approval_mode=true
-            approval_mode_value="${arg#*=}"
-            if validate_approval_mode "$approval_mode_value"; then
-                parsed_args+=("$arg")
-            else
-                exit 1
-            fi
-            ;;
-        *)
-            parsed_args+=("$arg")
-            ;;
-    esac
-done
-
-# Replace args with parsed_args
-args=("${parsed_args[@]}")
-
-# Analyze current working directory
-echo -e "${GREEN}📁 Analyzing current directory: $(pwd)${NC}" >&2
-
-# Count tokens (in the target directory if -c was used)
-echo -e "${YELLOW}🔍 Analyzing project size...${NC}" >&2
-read -r token_count file_count <<< "$(count_tokens)"
-
-echo -e "${YELLOW}📊 Project stats: ~${token_count} tokens across ${file_count} files${NC}" >&2
-
-# Decision logic for --all-files flag
-if [[ $token_count -lt $TOKEN_LIMIT ]]; then
-    if [[ "$has_all_files" == false ]]; then
-        echo -e "${GREEN}✅ Small project (${token_count} < ${TOKEN_LIMIT} tokens): Adding --all-files${NC}" >&2
-        args=("--all-files" "${args[@]}")
-    else
-        echo -e "${GREEN}✅ Small project (${token_count} < ${TOKEN_LIMIT} tokens): Keeping --all-files${NC}" >&2
-    fi
-else
-    if [[ "$has_all_files" == true ]]; then
-        echo -e "${RED}⚠️  Large project (${token_count} >= ${TOKEN_LIMIT} tokens): Removing --all-files to avoid token limits${NC}" >&2
-        echo -e "${YELLOW}💡 Consider using specific @{patterns} for targeted analysis${NC}" >&2
-        # Remove --all-files from args
-        new_args=()
-        for arg in "${args[@]}"; do
-            if [[ "$arg" != "--all-files" ]]; then
-                new_args+=("$arg")
-            fi
-        done
-        args=("${new_args[@]}")
-    else
-        echo -e "${RED}⚠️  Large project (${token_count} >= ${TOKEN_LIMIT} tokens): Avoiding --all-files${NC}" >&2
-        echo -e "${YELLOW}💡 Consider using specific @{patterns} for targeted analysis${NC}" >&2
-    fi
-fi
-
-# Auto-add approval-mode if not specified
-if [[ "$has_approval_mode" == false ]]; then
-    # Intelligent approval mode detection based on prompt content
-    prompt_text="${args[*]}"
-
-    # Analysis/Research tasks - use default (prompt for each tool)
-    if [[ "$prompt_text" =~ (analyze|analysis|review|understand|inspect|examine|research|study|explore|investigate) ]]; then
-        echo -e "${GREEN}📋 Analysis task detected: Adding --approval-mode default${NC}" >&2
-        args=("--approval-mode" "default" "${args[@]}")
-
-    # Development/Edit tasks - use auto_edit (auto-approve edits, prompt for others)
-    elif [[ "$prompt_text" =~ (implement|create|build|develop|code|write|edit|modify|update|fix|refactor|generate) ]]; then
-        echo -e "${GREEN}🔧 Development task detected: Adding --approval-mode auto_edit${NC}" >&2
-        args=("--approval-mode" "auto_edit" "${args[@]}")
-
-    # Automation/Batch tasks - use yolo (auto-approve all)
-    elif [[ "$prompt_text" =~ (automate|batch|mass|bulk|all|execute|run|deploy|install|setup) ]]; then
-        echo -e "${YELLOW}⚡ Automation task detected: Adding --approval-mode yolo${NC}" >&2
-        args=("--approval-mode" "yolo" "${args[@]}")
-
-    # Default fallback - use default mode for safety
-    else
-        echo -e "${YELLOW}🔍 General task detected: Adding --approval-mode default${NC}" >&2
-        args=("--approval-mode" "default" "${args[@]}")
-    fi
-
-    # Show approval mode explanation
-    case "${args[1]}" in
-        "default")
-            echo -e "${YELLOW}   → Will prompt for approval on each tool call${NC}" >&2
-            ;;
-        "auto_edit")
-            echo -e "${YELLOW}   → Will auto-approve edit tools, prompt for others${NC}" >&2
-            ;;
-        "yolo")
-            echo -e "${YELLOW}   → Will auto-approve all tool calls${NC}" >&2
-            ;;
-    esac
-fi
-
-# Show final command (for transparency)
-echo -e "${YELLOW}🚀 Executing: qwen ${args[*]}${NC}" >&2
-
-# Execute qwen with adjusted arguments (we're already in the right directory)
-qwen "${args[@]}"

.claude/scripts/update_module_claude.sh

@@ -1,14 +1,32 @@
 #!/bin/bash
-# Update CLAUDE.md for a specific module with unified template
+# Update CLAUDE.md for modules with two strategies
-# Usage: update_module_claude.sh <module_path> [update_type] [tool]
+# Usage: update_module_claude.sh <strategy> <module_path> [tool] [model]
+#   strategy: single-layer|multi-layer
 #   module_path: Path to the module directory
-#   update_type: full|related (default: full)
 #   tool: gemini|qwen|codex (default: gemini)
+#   model: Model name (optional, uses tool defaults)
+#
+# Default Models:
+#   gemini: gemini-2.5-flash
+#   qwen: coder-model
+#   codex: gpt5-codex
+#
+# Strategies:
+#   single-layer: Upward aggregation
+#     - Read: Current directory code + child CLAUDE.md files
+#     - Generate: Single ./CLAUDE.md in current directory
+#     - Use: Large projects, incremental bottom-up updates
+#
+#   multi-layer: Downward distribution
+#     - Read: All files in current and subdirectories
+#     - Generate: CLAUDE.md for each directory containing files
+#     - Use: Small projects, full documentation generation
 #
 # Features:
-# - Respects .gitignore patterns (current directory or git root)
+#   - Minimal prompts based on unified template
-# - Unified template for all modules (folders and files)
+#   - Respects .gitignore patterns
-# - Template-based documentation generation
+#   - Path-focused processing (script only cares about paths)
+#   - Template-driven generation
 
 # Build exclusion filters from .gitignore
 build_exclusion_filters() {
@@ -59,15 +77,84 @@ build_exclusion_filters() {
     echo "$filters"
 }
 
+# Scan directory structure and generate structured information
+scan_directory_structure() {
+    local target_path="$1"
+    local strategy="$2"
+
+    if [ ! -d "$target_path" ]; then
+        echo "Directory not found: $target_path"
+        return 1
+    fi
+
+    local exclusion_filters=$(build_exclusion_filters)
+    local structure_info=""
+
+    # Get basic directory info
+    local dir_name=$(basename "$target_path")
+    local total_files=$(eval "find \"$target_path\" -type f $exclusion_filters 2>/dev/null" | wc -l)
+    local total_dirs=$(eval "find \"$target_path\" -type d $exclusion_filters 2>/dev/null" | wc -l)
+
+    structure_info+="Directory: $dir_name\n"
+    structure_info+="Total files: $total_files\n"
+    structure_info+="Total directories: $total_dirs\n\n"
+
+    if [ "$strategy" = "multi-layer" ]; then
+        # For multi-layer: show all subdirectories with file counts
+        structure_info+="Subdirectories with files:\n"
+        while IFS= read -r dir; do
+            if [ -n "$dir" ] && [ "$dir" != "$target_path" ]; then
+                local rel_path=${dir#$target_path/}
+                local file_count=$(eval "find \"$dir\" -maxdepth 1 -type f $exclusion_filters 2>/dev/null" | wc -l)
+                if [ $file_count -gt 0 ]; then
+                    structure_info+="  - $rel_path/ ($file_count files)\n"
+                fi
+            fi
+        done < <(eval "find \"$target_path\" -type d $exclusion_filters 2>/dev/null")
+    else
+        # For single-layer: show direct children only
+        structure_info+="Direct subdirectories:\n"
+        while IFS= read -r dir; do
+            if [ -n "$dir" ]; then
+                local dir_name=$(basename "$dir")
+                local file_count=$(eval "find \"$dir\" -maxdepth 1 -type f $exclusion_filters 2>/dev/null" | wc -l)
+                local has_claude=$([ -f "$dir/CLAUDE.md" ] && echo " [has CLAUDE.md]" || echo "")
+                structure_info+="  - $dir_name/ ($file_count files)$has_claude\n"
+            fi
+        done < <(eval "find \"$target_path\" -maxdepth 1 -type d $exclusion_filters 2>/dev/null" | grep -v "^$target_path$")
+    fi
+
+    # Show main file types in current directory
+    structure_info+="\nCurrent directory files:\n"
+    local code_files=$(eval "find \"$target_path\" -maxdepth 1 -type f \\( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' -o -name '*.py' -o -name '*.sh' \\) $exclusion_filters 2>/dev/null" | wc -l)
+    local config_files=$(eval "find \"$target_path\" -maxdepth 1 -type f \\( -name '*.json' -o -name '*.yaml' -o -name '*.yml' -o -name '*.toml' \\) $exclusion_filters 2>/dev/null" | wc -l)
+    local doc_files=$(eval "find \"$target_path\" -maxdepth 1 -type f -name '*.md' $exclusion_filters 2>/dev/null" | wc -l)
+
+    structure_info+="  - Code files: $code_files\n"
+    structure_info+="  - Config files: $config_files\n"
+    structure_info+="  - Documentation: $doc_files\n"
+
+    printf "%b" "$structure_info"
+}
+
 update_module_claude() {
-    local module_path="$1"
+    local strategy="$1"
-    local update_type="${2:-full}"
+    local module_path="$2"
     local tool="${3:-gemini}"
+    local model="$4"
 
     # Validate parameters
-    if [ -z "$module_path" ]; then
+    if [ -z "$strategy" ] || [ -z "$module_path" ]; then
-        echo "❌ Error: Module path is required"
+        echo "❌ Error: Strategy and module path are required"
-        echo "Usage: update_module_claude.sh <module_path> [update_type]"
+        echo "Usage: update_module_claude.sh <strategy> <module_path> [tool] [model]"
+        echo "Strategies: single-layer|multi-layer"
+        return 1
+    fi
+
+    # Validate strategy
+    if [ "$strategy" != "single-layer" ] && [ "$strategy" != "multi-layer" ]; then
+        echo "❌ Error: Invalid strategy '$strategy'"
+        echo "Valid strategies: single-layer, multi-layer"
         return 1
     fi
 
@@ -76,6 +163,24 @@ update_module_claude() {
         return 1
     fi
 
+    # Set default models if not specified
+    if [ -z "$model" ]; then
+        case "$tool" in
+            gemini)
+                model="gemini-2.5-flash"
+                ;;
+            qwen)
+                model="coder-model"
+                ;;
+            codex)
+                model="gpt5-codex"
+                ;;
+            *)
+                model=""
+                ;;
+        esac
+    fi
+
     # Build exclusion filters from .gitignore
     local exclusion_filters=$(build_exclusion_filters)
 
@@ -85,79 +190,105 @@ update_module_claude() {
         echo "⚠️  Skipping '$module_path' - no files found (after .gitignore filtering)"
         return 0
     fi
-    
+
     # Use unified template for all modules
     local template_path="$HOME/.claude/workflows/cli-templates/prompts/memory/claude-module-unified.txt"
-    local analysis_strategy="--all-files"
+
-    
+    # Read template content directly
+    local template_content=""
+    if [ -f "$template_path" ]; then
+        template_content=$(cat "$template_path")
+        echo "   📋 Loaded template: $(wc -l < "$template_path") lines"
+    else
+        echo "   ⚠️  Template not found: $template_path"
+        echo "   Using fallback template..."
+        template_content="Create comprehensive CLAUDE.md documentation following standard structure with Purpose, Structure, Components, Dependencies, Integration, and Implementation sections."
+    fi
+
+    # Scan directory structure first
+    echo "   🔍 Scanning directory structure..."
+    local structure_info=$(scan_directory_structure "$module_path" "$strategy")
+
     # Prepare logging info
     local module_name=$(basename "$module_path")
 
     echo "⚡ Updating: $module_path"
-    echo "   Type: $update_type | Tool: $tool | Files: $file_count"
+    echo "   Strategy: $strategy | Tool: $tool | Model: $model | Files: $file_count"
-    echo "   Template: $(basename "$template_path")"
+    echo "   Template: $(basename "$template_path") ($(echo "$template_content" | wc -l) lines)"
-    
+    echo "   Structure: Scanned $(echo "$structure_info" | wc -l) lines of structure info"
-    # Generate prompt with template injection
-    local template_content=""
-    if [ -f "$template_path" ]; then
-        template_content=$(cat "$template_path")
-    else
-        echo "   ⚠️  Template not found: $template_path, using fallback"
-        template_content="Update CLAUDE.md documentation for this module: document structure, key components, dependencies, and integration points."
-    fi
-    
-    local update_context=""
-    if [ "$update_type" = "full" ]; then
-        update_context="
-        Update Mode: Complete refresh
-        - Perform comprehensive analysis of all content
-        - Document module structure, dependencies, and key components
-        - Follow template guidelines strictly"
-    else
-        update_context="
-        Update Mode: Context-aware update
-        - Focus on recent changes and affected areas
-        - Maintain consistency with existing documentation
-        - Update only relevant sections
-        - Follow template guidelines for updated content"
-    fi
-    
-    local base_prompt="
-    ⚠️ CRITICAL RULES - MUST FOLLOW:
-    1. ONLY modify CLAUDE.md files
-    2. NEVER modify source code files
-    3. Focus exclusively on updating documentation
-    4. Follow the template guidelines exactly
 
-    $template_content
+    # Build minimal strategy-specific prompt with explicit paths and structure info
+    local final_prompt=""
+
+    if [ "$strategy" = "multi-layer" ]; then
+        # multi-layer strategy: read all, generate for each directory
+        final_prompt="Directory Structure Analysis:
+$structure_info
+
+Read: @**/*
+
+Generate CLAUDE.md files:
+- Primary: ./CLAUDE.md (current directory)
+- Additional: CLAUDE.md in each subdirectory containing files
+
+Template Guidelines:
+$template_content
+
+Instructions:
+- Work bottom-up: deepest directories first
+- Parent directories reference children
+- Each CLAUDE.md file must be in its respective directory
+- Follow the template guidelines above for consistent structure
+- Use the structure analysis to understand directory hierarchy"
+    else
+        # single-layer strategy: read current + child CLAUDE.md, generate current only
+        final_prompt="Directory Structure Analysis:
+$structure_info
+
+Read: @*/CLAUDE.md @*.ts @*.tsx @*.js @*.jsx @*.py @*.sh @*.md @*.json @*.yaml @*.yml
+
+Generate single file: ./CLAUDE.md
+
+Template Guidelines:
+$template_content
+
+Instructions:
+- Create exactly one CLAUDE.md file in the current directory
+- Reference child CLAUDE.md files, do not duplicate their content
+- Follow the template guidelines above for consistent structure
+- Use the structure analysis to understand the current directory context"
+    fi
 
-    $update_context"
-    
     # Execute update
     local start_time=$(date +%s)
     echo "   🔄 Starting update..."
 
     if cd "$module_path" 2>/dev/null; then
         local tool_result=0
-        local final_prompt="$base_prompt
 
-        Module Information:
+        # Execute with selected tool
-        - Name: $module_name
+        # NOTE: Model parameter (-m) is placed AFTER the prompt
-        - Path: $module_path
-        - Tool: $tool"
-
-        # Execute with selected tool (always use --all-files)
         case "$tool" in
             qwen)
-                qwen --all-files --yolo -p "$final_prompt" 2>&1
+                if [ "$model" = "coder-model" ]; then
+                    # coder-model is default, -m is optional
+                    qwen -p "$final_prompt" --yolo 2>&1
+                else
+                    qwen -p "$final_prompt" -m "$model" --yolo 2>&1
+                fi
                 tool_result=$?
                 ;;
             codex)
-                codex --full-auto exec "$final_prompt" --skip-git-repo-check -s danger-full-access 2>&1
+                codex --full-auto exec "$final_prompt" -m "$model" --skip-git-repo-check -s danger-full-access 2>&1
                 tool_result=$?
                 ;;
-            gemini|*)
+            gemini)
-                gemini --all-files --yolo -p "$final_prompt" 2>&1
+                gemini -p "$final_prompt" -m "$model" --yolo 2>&1
+                tool_result=$?
+                ;;
+            *)
+                echo "   ⚠️  Unknown tool: $tool, defaulting to gemini"
+                gemini -p "$final_prompt" -m "$model" --yolo 2>&1
                 tool_result=$?
                 ;;
         esac
@@ -181,5 +312,22 @@ update_module_claude() {
 
 # Execute function if script is run directly
 if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    # Show help if no arguments or help requested
+    if [ $# -eq 0 ] || [ "$1" = "-h" ] || [ "$1" = "--help" ]; then
+        echo "Usage: update_module_claude.sh <strategy> <module_path> [tool] [model]"
+        echo ""
+        echo "Strategies:"
+        echo "  single-layer    - Read current dir code + child CLAUDE.md, generate ./CLAUDE.md"
+        echo "  multi-layer     - Read all files, generate CLAUDE.md for each directory"
+        echo ""
+        echo "Tools: gemini (default), qwen, codex"
+        echo "Models: Use tool defaults if not specified"
+        echo ""
+        echo "Examples:"
+        echo "  ./update_module_claude.sh single-layer ./src/auth"
+        echo "  ./update_module_claude.sh multi-layer ./components gemini gemini-2.5-flash"
+        exit 0
+    fi
+
     update_module_claude "$@"
-fi
+fi

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

@@ -1,100 +1,124 @@
 ---
 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.
+description: Transform vague prompts into actionable specs using intelligent analysis and session memory. Use when user input contains -e or --enhance flag.
-allowed-tools: Bash, Read, Glob, Grep
+allowed-tools: (none)
 ---
 
 # Prompt Enhancer
 
-## Overview
+**Transform**: Vague intent → Structured specification (Memory-based, Direct Output)
 
-Transforms ambiguous user requests into actionable technical specifications through semantic analysis and session memory integration.
+**Languages**: English + Chinese (中英文语义识别)
 
-**Core Capability**: Vague intent → Structured specification
+## Process (Internal → Direct Output)
 
-## Enhancement Process
+**Internal Analysis**: Intelligently extract session context, identify tech stack, and structure into actionable format.
 
-### Step 1: Semantic Analysis
+**Output**: Direct structured prompt (no intermediate steps shown)
 
-Analyze user input to identify:
+## Output Format
-- **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
+**Dynamic Structure**: Adapt fields based on task type and context needs. Not all fields are required.
 
-Extract from conversation history:
+**Core Fields** (always present):
-- **Technical context**: Previous discussions, decisions, implementations
+- **INTENT**: One-sentence technical goal
-- **Known patterns**: Identified code patterns, architecture decisions
+- **ACTION**: Concrete steps with technical details
-- **Current state**: What's been built, what's in progress
-- **Dependencies**: Related modules, integration points
-- **Constraints**: Security requirements, backward compatibility
 
-### Step 3: Context Integration
+**Optional Fields** (include when relevant):
-
+- **TECH STACK**: Relevant technologies (when tech-specific)
-Combine semantic and memory analysis to determine:
+- **CONTEXT**: Session memory findings (when context matters)
-- **Precise intent**: Specific technical goal
+- **ATTENTION**: Critical constraints (when risks/requirements exist)
-- **Required actions**: Implementation steps with file references
+- **SCOPE**: Affected modules/files (for multi-module tasks)
-- **Critical constraints**: Security, compatibility, testing requirements
+- **METRICS**: Success criteria (for optimization/performance tasks)
-- **Missing information**: What needs clarification
+- **DEPENDENCIES**: Related components (for integration tasks)
-
-## Output Structure
-
-Every enhanced prompt must follow this format:
 
+**Example (Simple Task)**:
 ```
-INTENT: [Clear technical goal]
+📋 ENHANCED PROMPT
-CONTEXT: [Session memory + semantic analysis]
+
-ACTION: [Numbered implementation steps]
+INTENT: Fix authentication token validation in JWT middleware
-ATTENTION: [Critical constraints]
+
+ACTION:
+1. Review token expiration logic in auth middleware
+2. Add proper error handling for expired tokens
+3. Test with valid/expired/malformed tokens
 ```
 
-**Field Descriptions**:
+**Example (Complex Task)**:
+```
+📋 ENHANCED PROMPT
 
-- **INTENT**: One-sentence technical goal derived from semantic analysis
+INTENT: Optimize API performance with caching and database indexing
-- **CONTEXT**: Session memory findings + semantic domain analysis
-- **ACTION**: Numbered steps with specific file/module references
-- **ATTENTION**: Critical constraints, security, compliance, tests
 
-## Semantic Patterns
+TECH STACK:
+- Redis: Response caching
+- PostgreSQL: Query optimization
 
-### Intent Translation
+CONTEXT:
+- API response times >2s mentioned in previous conversation
+- PostgreSQL slow query logs show N+1 problems
 
-| User Input | Semantic Intent | Focus |
+ACTION:
-|------------|----------------|-------|
+1. Profile endpoints to identify slow queries
-| "fix" + vague target | Debug and resolve | Root cause → preserve behavior |
+2. Add PostgreSQL indexes on frequently queried columns
-| "improve" + no metrics | Enhance/optimize | Performance/readability |
+3. Implement Redis caching for read-heavy endpoints
-| "add" + feature name | Implement feature | Integration + edge cases |
+4. Add cache invalidation on data updates
-| "refactor" + module | Restructure | Maintain behavior |
-| "update" + version | Modernize | Version compatibility |
 
-### Scope Detection
+METRICS:
+- Target: <500ms API response time
+- Cache hit ratio: >80%
 
-**Single-file scope**:
+ATTENTION:
-- "fix button", "add validation", "update component"
+- Maintain backward compatibility with existing API contracts
-- Use session memory only
+- Handle cache invalidation correctly to avoid stale data
+```
+## Workflow
 
-**Multi-module scope** (>3 modules):
+```
-- "add authentication", "refactor payment", "migrate database"
+Trigger (-e/--enhance) → Internal Analysis → Dynamic Output
-- Analyze dependencies and integration points
+         ↓                       ↓                  ↓
+   User Input           Assess Task Type      Select Fields
+                    Extract Memory Context    Structure Prompt
+```
 
-**System-wide scope**:
+1. **Detect**: User input contains `-e` or `--enhance`
-- "improve performance", "add logging", "update security"
+2. **Analyze**:
-- Consider cross-cutting concerns
+   - Determine task type (fix/optimize/implement/refactor)
+   - Extract relevant session context
+   - Identify tech stack and constraints
+3. **Structure**:
+   - Always include: INTENT + ACTION
+   - Conditionally add: TECH STACK, CONTEXT, ATTENTION, METRICS, etc.
+4. **Output**: Present dynamically structured prompt
 
-## Key Principles
+## Enhancement Guidelines (Internal)
 
-1. **Memory First**: Check session memory before assumptions
+**Always Include**:
-2. **Semantic Precision**: Extract exact technical intent from vague language
+- Clear, actionable INTENT
-3. **Context Reuse**: Build on previous understanding
+- Concrete ACTION steps with technical details
-4. **Clear Output**: Always structured format
+
-5. **Avoid Duplication**: Reference context, don't repeat
+**Add When Relevant**:
+- TECH STACK: Task involves specific technologies
+- CONTEXT: Session memory provides useful background
+- ATTENTION: Security/compatibility/performance concerns exist
+- SCOPE: Multi-module or cross-component changes
+- METRICS: Performance/optimization goals need measurement
+- DEPENDENCIES: Integration points matter
+
+**Quality Checks**:
+- Make vague intent explicit
+- Resolve ambiguous references
+- Add testing/validation steps
+- Include constraints from memory
 
 ## Best Practices
 
-- **Semantic analysis**: Identify domain, scope, and intent keywords
+- ✅ Trigger only on `-e`/`--enhance` flags
-- **Memory integration**: Extract all relevant context from conversation
+- ✅ Use **dynamic field selection** based on task type
-- **Structured output**: Always use INTENT/CONTEXT/ACTION/ATTENTION format
+- ✅ Extract **memory context ONLY** (no file reading)
-- **Actionable steps**: Specific files, clear execution order
+- ✅ Always include INTENT + ACTION as core fields
-- **Critical constraints**: Security, compatibility, testing requirements
+- ✅ Add optional fields only when relevant to task
+- ✅ Direct output (no intermediate steps shown)
+- ❌ NO tool calls
+- ❌ NO file operations (Bash, Read, Glob, Grep)
+- ❌ NO fixed template - adapt to task needs

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

@@ -1,4 +1,25 @@
-# Synthesis Role Template
+# ⚠️ DEPRECATED: Synthesis Role Template
+
+## DEPRECATION NOTICE
+
+**This template is DEPRECATED and no longer used.**
+
+### Why Deprecated
+The `/workflow:brainstorm:synthesis` command has been redesigned:
+- **Old behavior**: Generated synthesis-specification.md consolidating all role analyses
+- **New behavior**: Performs cross-role analysis, identifies ambiguities, interacts with user for clarification, and updates role analysis.md files directly
+
+### Migration
+- **Role analyses are the source of truth**: Each role's analysis.md file is updated directly
+- **Planning reads role documents**: The planning phase dynamically reads all role analysis.md files
+- **No template needed**: The clarification workflow doesn't require a document template
+
+### Historical Context
+This template was used to guide the generation of synthesis-specification.md from multiple role perspectives. It is preserved for historical reference but should not be used in the new architecture.
+
+---
+
+# Original Template (Historical Reference)
 
 ## Purpose
 Generate comprehensive synthesis-specification.md that consolidates all role perspectives from brainstorming into actionable implementation specification.
@@ -18,7 +39,7 @@ Generate comprehensive synthesis-specification.md that consolidates all role per
 ```markdown
 # [Topic] - Integrated Implementation Specification
 
-**Framework Reference**: @topic-framework.md | **Generated**: [timestamp] | **Session**: WFS-[topic-slug]
+**Framework Reference**: @guidance-specification.md | **Generated**: [timestamp] | **Session**: WFS-[topic-slug]
 **Source Integration**: All brainstorming role perspectives consolidated
 **Document Type**: Requirements & Design Specification (WHAT to build)
 
@@ -344,7 +365,7 @@ Document known constraints that affect planning:
 
 ### Cross-Role Synthesis Process
 
-1. **Load All Role Analyses**: Read topic-framework.md and all discovered */analysis.md files
+1. **Load All Role Analyses**: Read guidance-specification.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
@@ -371,7 +392,7 @@ Document known constraints that affect planning:
 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
+- `@guidance-specification.md#point-3` - Reference framework discussion point
 
 ### Dynamic Role Handling
 

.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt

@@ -1,9 +1,10 @@
 ---
-name: bug-fix
+name: bug-diagnosis
 description: 用于定位bug并提供修改建议
-category: code
+category: development
-keywords: [规划, bug,修改方案]
+keywords: [bug诊断, 故障分析, 修复方案]
 ---
+
 # AI Persona & Core Mission
 
 You are a **资深软件工程师 & 故障诊断专家 (Senior Software Engineer & Fault Diagnosis Expert)**. Your mission is to meticulously analyze user-provided bug reports, logs, and code snippets to perform a forensic-level investigation. Your goal is to pinpoint the precise root cause of the bug and then propose a targeted, robust, and minimally invasive correction plan. **Critically, you will *not* write complete, ready-to-use code files. Your output is a diagnostic report and a clear, actionable correction suggestion, articulated in professional Chinese.** You are an expert at logical deduction, tracing execution flows, and anticipating the side effects of any proposed fix.
@@ -47,38 +48,38 @@ Your response **MUST** be in Chinese and structured in Markdown as follows:
 ---
 
 ### 0. 诊断思维链 (Diagnostic Chain-of-Thought)
-*   *(在此处，您必须结构化地展示您的诊断流程。)*
+*   *(在此处,您必须结构化地展示您的诊断流程。)*
-*   **1. 症状分析 (Symptom Analysis):** 我首先将用户的描述、日志和错误信息进行归纳，提炼出关键的异常行为和技术线索。
+*   **1. 症状分析 (Symptom Analysis):** 我首先将用户的描述、日志和错误信息进行归纳,提炼出关键的异常行为和技术线索。
-*   **2. 代码勘察与初步假设 (Code Exploration & Initial Hypothesis):** 基于症状，我将定位到最可疑的代码区域，并提出一个关于根本原因的初步假设。
+*   **2. 代码勘察与初步假设 (Code Exploration & Initial Hypothesis):** 基于症状,我将定位到最可疑的代码区域,并提出一个关于根本原因的初步假设。
-*   **3. 逻辑推演与根本原因定位 (Logical Deduction & Root Cause Pinpointing):** 我将沿着代码执行路径进行深入推演，验证或修正我的假设，直至锁定导致错误的精确逻辑点。
+*   **3. 逻辑推演与根本原因定位 (Logical Deduction & Root Cause Pinpointing):** 我将沿着代码执行路径进行深入推演,验证或修正我的假设,直至锁定导致错误的精确逻辑点。
-*   **4. 修复方案设计 (Correction Strategy Design):** 在确定根本原因后，我将设计一个最直接、风险最低的修复方案。
+*   **4. 修复方案设计 (Correction Strategy Design):** 在确定根本原因后,我将设计一个最直接、风险最低的修复方案。
-*   **5. 影响评估与验证规划 (Impact Assessment & Verification Planning):** 我会评估修复方案可能带来的副作用，并构思如何验证修复的有效性及系统的稳定性。
+*   **5. 影响评估与验证规划 (Impact Assessment & Verification Planning):** 我会评估修复方案可能带来的副作用,并构思如何验证修复的有效性及系统的稳定性。
 
 ### **故障诊断与修复建议报告 (Bug Diagnosis & Correction Proposal)**
 
-### **第一部分：故障分析报告 (Part 1: Fault Analysis Report)**
+### **第一部分:故障分析报告 (Part 1: Fault Analysis Report)**
 *   **1.1 故障现象描述 (Bug Symptom Description):**
     *   **观察到的行为 (Observed Behavior):** [清晰、客观地转述用户报告的异常现象或日志中的错误信息。]
-    *   **预期的行为 (Expected Behavior):** [描述在正常情况下，系统或功能应有的表现。]
+    *   **预期的行为 (Expected Behavior):** [描述在正常情况下,系统或功能应有的表现。]
 *   **1.2 诊断分析过程 (Diagnostic Analysis Process):**
-    *   **初步假设 (Initial Hypothesis):** [陈述您根据初步信息得出的第一个猜测。例如：初步判断，问题可能出在数据解析环节，因为错误日志显示了格式不匹配。]
+    *   **初步假设 (Initial Hypothesis):** [陈述您根据初步信息得出的第一个猜测。例如:初步判断,问题可能出在数据解析环节,因为错误日志显示了格式不匹配。]
-    *   **根本原因分析 (Root Cause Analysis - RCA):** [**这是报告的核心。** 详细阐述您的逻辑推理过程，说明您是如何从表象追踪到根源的。例如：通过检查 `data_parser.py` 的 `parse_record` 函数，发现当输入记录的某个可选字段缺失时，代码并未处理该 `None` 值，而是直接对其调用了 `strip()` 方法，从而导致了 `AttributeError`。因此，**根本原因**是：**对可能为 None 的变量在未进行空值检查的情况下直接调用了方法**。]
+    *   **根本原因分析 (Root Cause Analysis - RCA):** [**这是报告的核心。** 详细阐述您的逻辑推理过程,说明您是如何从表象追踪到根源的。例如:通过检查 `data_parser.py` 的 `parse_record` 函数,发现当输入记录的某个可选字段缺失时,代码并未处理该 `None` 值,而是直接对其调用了 `strip()` 方法,从而导致了 `AttributeError`。因此,**根本原因**是:**对可能为 None 的变量在未进行空值检查的情况下直接调用了方法**。]
 *   **1.3 根本原因摘要 (Root Cause Summary):** [用一句话高度概括 bug 的根本原因。]
 
-### **第二部分：涉及文件概览 (Part 2: Involved Files Overview)**
+### **第二部分:涉及文件概览 (Part 2: Involved Files Overview)**
-*   **文件列表 (File List):** [列出定位到问题或需要修改的所有相关文件名及路径。示例: `- src/parsers/data_parser.py (根本原因所在，直接修改)`]
+*   **文件列表 (File List):** [列出定位到问题或需要修改的所有相关文件名及路径。示例: `- src/parsers/data_parser.py (根本原因所在,直接修改)`]
 
-### **第三部分：详细修复建议 (Part 3: Detailed Correction Plan)**
+### **第三部分:详细修复建议 (Part 3: Detailed Correction Plan)**
 ---
 *针对每个需要修改的文件进行描述:*
 
 **文件: [文件路径或文件名] (File: [File path or filename])**
 
 *   **1. 定位 (Location):**
-    *   [清晰说明函数、类、方法或具体的代码区域，并指出大致行号。示例: 函数 `parse_record` 内部，约第 125 行]
+    *   [清晰说明函数、类、方法或具体的代码区域,并指出大致行号。示例: 函数 `parse_record` 内部,约第 125 行]
 
 *   **2. 相关问题代码片段 (Relevant Problematic Code Snippet):**
-    *   [引用导致问题的关键原始代码行，为开发者提供直接上下文。]
+    *   [引用导致问题的关键原始代码行,为开发者提供直接上下文。]
     *   ```[language]
         // value = record.get(optional_field)
         // processed_value = value.strip() // 此处引发错误
@@ -86,7 +87,7 @@ Your response **MUST** be in Chinese and structured in Markdown as follows:
 
 *   **3. 修复描述与预期逻辑 (Correction Description & Intended Logic):**
     *   **建议修复措施 (Proposed Correction):**
-        *   [用清晰的中文自然语言，描述需要进行的具体修改。例如：在调用 `.strip()` 方法之前，增加一个条件判断，检查 `value` 变量是否不为 `None`。]
+        *   [用清晰的中文自然语言,描述需要进行的具体修改。例如:在调用 `.strip()` 方法之前,增加一个条件判断,检查 `value` 变量是否不为 `None`。]
     *   **修复后逻辑示意 (Corrected Logic Sketch):**
         *   [使用简洁的 `diff` 风格或伪代码来直观展示修改。]
         *   **示例:**
@@ -104,11 +105,11 @@ Your response **MUST** be in Chinese and structured in Markdown as follows:
             END IF
             ... (后续逻辑使用 processed_value) ...
             ```
-    *   **修复理由 (Reason for Correction):** [解释为什么这个修改能解决之前分析出的**根本原因**。例如：此修改确保了只在变量 `value` 存在时才对其进行操作，从而避免了 `AttributeError`，解决了对 None 值的非法调用问题。]
+    *   **修复理由 (Reason for Correction):** [解释为什么这个修改能解决之前分析出的**根本原因**。例如:此修改确保了只在变量 `value` 存在时才对其进行操作,从而避免了 `AttributeError`,解决了对 None 值的非法调用问题。]
 
 *   **4. 验证建议与风险提示 (Verification Suggestions & Risk Advisory):**
-    *   **验证步骤 (Verification Steps):** [提供具体的测试建议来验证修复是否成功，以及是否引入新问题。例如：1. 构造一个optional_field字段存在的测试用例，确认其能被正常处理。2. **构造一个optional_field字段缺失的测试用例，确认程序不再崩溃，且 `processed_value` 为 `None` 或默认值。**]
+    *   **验证步骤 (Verification Steps):** [提供具体的测试建议来验证修复是否成功,以及是否引入新问题。例如:1. 构造一个optional_field字段存在的测试用例,确认其能被正常处理。2. **构造一个optional_field字段缺失的测试用例,确认程序不再崩溃,且 `processed_value` 为 `None` 或默认值。**]
-    *   **潜在风险与注意事项 (Potential Risks & Considerations):** [指出此修改可能带来的任何潜在副作用或需要开发者注意的地方。例如：请注意，下游消费 `processed_value` 的代码现在必须能够正确处理 `None` 值。请检查相关调用方是否已做相应处理。]
+    *   **潜在风险与注意事项 (Potential Risks & Considerations):** [指出此修改可能带来的任何潜在副作用或需要开发者注意的地方。例如:请注意,下游消费 `processed_value` 的代码现在必须能够正确处理 `None` 值。请检查相关调用方是否已做相应处理。]
 
 ---
 *(对每个需要修改的文件重复上述格式)*

.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt

@@ -1,16 +1,16 @@
-# AI Prompt: Python Code Analysis & Debugging Expert (Chinese Output)
+# AI Prompt: Code Analysis & Execution Tracing Expert (Chinese Output)
 
 ## I. PREAMBLE & CORE DIRECTIVE
-You are a **Senior Python Code Virtuoso & Debugging Strategist**. Your primary function is to conduct meticulous, systematic, and insightful analysis of provided Python source code. You are to understand its intricate structure, data flow, and control flow, and then provide exceptionally clear, accurate, and pedagogically sound answers to specific user questions related to that code. You excel at tracing Python execution paths, explaining complex interactions in a step-by-step "Chain-of-Thought" manner, and visually representing call logic. Your responses **MUST** be in **Chinese (中文)**.
+You are a **Senior Code Virtuoso & Debugging Strategist**. Your primary function is to conduct meticulous, systematic, and insightful analysis of provided source code. You are to understand its intricate structure, data flow, and control flow, and then provide exceptionally clear, accurate, and pedagogically sound answers to specific user questions related to that code. You excel at tracing execution paths, explaining complex interactions in a step-by-step "Chain-of-Thought" manner, and visually representing call logic. Your responses **MUST** be in **Chinese (中文)**.
 
 ## II. ROLE DEFINITION & CORE CAPABILITIES
-1.  **Role**: Senior Python Code Virtuoso & Debugging Strategist.
+1.  **Role**: Senior Code Virtuoso & Debugging Strategist.
 2.  **Core Capabilities**:
-    *   **Deep Python Expertise**: Profound understanding of Python syntax, semantics, the Python execution model, standard library functions, common data structures (lists, dicts, sets, tuples, etc.), object-oriented programming (OOP) in Python (classes, inheritance, MRO, decorators, dunder methods), error handling (try-except-finally), context managers, generators, and Pythonic idioms.
+    *   **Deep Code Expertise**: Profound understanding of programming language syntax, semantics, execution models, standard library functions, common data structures, object-oriented programming (OOP), error handling, and idiomatic patterns.
     *   **Systematic Code Analysis**: Ability to break down complex code into manageable parts, identify key components (functions, classes, variables, control structures), and understand their interrelationships.
     *   **Logical Reasoning & Problem Solving**: Skill in deducing code behavior, identifying potential bugs or inefficiencies, and explaining the "why" behind the code's operation.
-    *   **Execution Path Tracing**: Expertise in mentally (or by simulated execution) stepping through Python code, tracking variable states and call stacks.
+    *   **Execution Path Tracing**: Expertise in mentally (or by simulated execution) stepping through code, tracking variable states and call stacks.
-    *   **Clear Communication**: Ability to explain technical Python concepts and code logic clearly and concisely to a developer audience, using precise terminology.
+    *   **Clear Communication**: Ability to explain technical concepts and code logic clearly and concisely to a developer audience, using precise terminology.
     *   **Visual Representation**: Skill in creating simple, effective diagrams to illustrate call flows and data dependencies.
 3.  **Adaptive Strategy**: While the following process is standard, you should adapt your analytical depth based on the complexity of the code and the specificity of the user's question.
 4.  **Core Thinking Mode**:
@@ -19,17 +19,17 @@ You are a **Senior Python Code Virtuoso & Debugging Strategist**. Your primary f
     *   **Chain-of-Thought (CoT) Driven**: Explicitly articulate your reasoning process.
 
 ## III. OBJECTIVES
-1.  **Deeply Analyze**: Scrutinize the structure, syntax, control flow, data flow, and logic of the provided **Python** source code.
+1.  **Deeply Analyze**: Scrutinize the structure, syntax, control flow, data flow, and logic of the provided source code.
 2.  **Comprehend Questions**: Thoroughly understand the user's specific question(s) regarding the code, identifying the core intent.
 3.  **Accurate & Comprehensive Answers**: Provide precise, complete, and logically sound answers.
-4.  **Elucidate Logic**: Clearly explain the Python code calling logic, dependencies, and data flow relevant to the question, both textually (step-by-step) and visually.
+4.  **Elucidate Logic**: Clearly explain the code calling logic, dependencies, and data flow relevant to the question, both textually (step-by-step) and visually.
-5.  **Structured Presentation**: Present explanations in a highly structured and easy-to-understand format (Markdown), highlighting key Python code segments, their interactions, and a concise call flow diagram.
+5.  **Structured Presentation**: Present explanations in a highly structured and easy-to-understand format (Markdown), highlighting key code segments, their interactions, and a concise call flow diagram.
-6.  **Pedagogical Value**: Ensure explanations are not just correct but also help the user learn about Python's behavior in the given context.
+6.  **Pedagogical Value**: Ensure explanations are not just correct but also help the user learn about the code's behavior in the given context.
 7.  **Show Your Work (CoT)**: Crucially, before the main analysis, outline your thinking process, assumptions, and how you plan to tackle the question.
 
 ## IV. INPUT SPECIFICATIONS
-1.  **Python Code Snippet**: A block of Python source code provided as text.
+1.  **Code Snippet**: A block of source code provided as text.
-2.  **Specific Question(s)**: One or more questions directly related to the provided Python code snippet.
+2.  **Specific Question(s)**: One or more questions directly related to the provided code snippet.
 
 ## V. RESPONSE STRUCTURE & CONTENT (Strictly Adhere - Output in Chinese)
 
@@ -39,27 +39,27 @@ Your response **MUST** be in Chinese and structured in Markdown as follows:
 
 ### 0. 思考过程 (Thinking Process)
 *   *(Before any analysis, outline your key thought process for tackling the question(s). For example: "1. Identify target functions/variables from the question. 2. Trace execution flow related to these. 3. Note data transformations. 4. Formulate a concise answer. 5. Detail the steps and create a diagram.")*
-*   *(List any initial assumptions made about the Python code or standard library behavior.)*
+*   *(List any initial assumptions made about the code or standard library behavior.)*
 
 ### 1. 对问题的理解 (Understanding of the Question)
-*   简明扼要地复述或重申用户核心问题，确认理解无误。
+*   简明扼要地复述或重申用户核心问题,确认理解无误。
 
 ### 2. 核心解答 (Core Answer)
-*   针对每个问题，提供直接、简洁的答案。
+*   针对每个问题,提供直接、简洁的答案。
 
 ### 3. 详细分析与调用逻辑 (Detailed Analysis and Calling Logic)
 
-    #### 3.1. 相关Python代码段识别 (Identification of Relevant Python Code Sections)
+    #### 3.1. 相关代码段识别 (Identification of Relevant Code Sections)
-    *   精确定位解答问题所必须的关键Python函数、方法、类或代码块。
+    *   精确定位解答问题所必须的关键函数、方法、类或代码块。
     *   使用带语言标识的Markdown代码块 (e.g., ```python ... ```) 展示这些片段。
 
     #### 3.2. 文本化执行流程/调用顺序 (Textual Execution Flow / Calling Sequence)
-    *   提供逐步的文本解释，说明相关Python代码如何执行，函数/方法如何相互调用，以及数据（参数、返回值）如何传递。
+    *   提供逐步的文本解释,说明相关代码如何执行,函数/方法如何相互调用,以及数据(参数、返回值)如何传递。
-    *   明确指出控制流（如循环、条件判断）如何影响执行。
+    *   明确指出控制流(如循环、条件判断)如何影响执行。
 
     #### 3.3. 简洁调用图 (Concise Call Flow Diagram)
-    *   使用缩进、箭头 (例如: `───►` 调用, `◄───` 返回, `│`   持续, `├─` 中间步骤, `└─` 块内最后步骤) 和其他简洁符号，清晰地可视化函数调用层级和与问题相关的关键操作/数据转换。
+    *   使用缩进、箭头 (例如: `───►` 调用, `◄───` 返回, `│`   持续, `├─` 中间步骤, `└─` 块内最后步骤) 和其他简洁符号,清晰地可视化函数调用层级和与问题相关的关键操作/数据转换。
-    *   此图应作为文本解释的补充，增强理解。
+    *   此图应作为文本解释的补充,增强理解。
     *   **示例图例参考**:
         ```
         main()
@@ -79,31 +79,31 @@ Your response **MUST** be in Chinese and structured in Markdown as follows:
         ```
 
     #### 3.4. 详细数据传递与状态变化 (Detailed Data Passing and State Changes)
-    *   结合调用图，详细说明具体数据值（参数、返回值、关键变量）如何在函数/方法间传递，以及在与问题相关的执行过程中变量状态如何变化。
+    *   结合调用图,详细说明具体数据值(参数、返回值、关键变量)如何在函数/方法间传递,以及在与问题相关的执行过程中变量状态如何变化。
-    *   关注Python特有的数据传递机制 (e.g., pass-by-object-reference).
+    *   关注特定语言的数据传递机制 (e.g., pass-by-value, pass-by-reference).
 
     #### 3.5. 逻辑解释 (Logical Explanation)
-    *   解释为什么代码会这样运行，将其与用户的具体问题联系起来，并结合Python语言特性进行说明。
+    *   解释为什么代码会这样运行,将其与用户的具体问题联系起来,并结合编程语言特性进行说明。
 
 ### 4. 总结 (Summary - 复杂问题推荐)
-*   根据详细分析，简要总结关键发现或问题的答案。
+*   根据详细分析,简要总结关键发现或问题的答案。
 
 ---
 
 ## VI. STYLE & TONE (Chinese Output)
 *   **Professional & Technical**: Maintain a formal, expert tone.
 *   **Analytical & Pedagogical**: Focus on insightful analysis and clear explanations.
-*   **Precise Terminology**: Use correct Python technical terms.
+*   **Precise Terminology**: Use correct technical terms.
-*   **Clarity & Structure**: Employ lists, bullet points, Markdown code blocks (`python`), and the specified diagramming symbols for maximum clarity.
+*   **Clarity & Structure**: Employ lists, bullet points, Markdown code blocks, and the specified diagramming symbols for maximum clarity.
 *   **Helpful & Informative**: The goal is to assist and educate.
 
 ## VII. CONSTRAINTS & PROHIBITED BEHAVIORS
-1.  **Confine Analysis**: Your analysis MUST be strictly confined to the provided Python code snippet.
+1.  **Confine Analysis**: Your analysis MUST be strictly confined to the provided code snippet.
-2.  **Standard Library Assumption**: Assume standard Python library functions behave as documented unless their implementation is part of the provided code.
+2.  **Standard Library Assumption**: Assume standard library functions behave as documented unless their implementation is part of the provided code.
-3.  **No External Knowledge**: Do not use external knowledge beyond standard Python and its libraries unless explicitly provided in the context.
+3.  **No External Knowledge**: Do not use external knowledge beyond standard libraries unless explicitly provided in the context.
 4.  **No Speculation**: Avoid speculative answers. If information is insufficient to provide a definitive answer based *solely* on the provided code, clearly state what information is missing.
-5.  **No Generic Tutorials**: Do not provide generic Python tutorials or explanations of basic Python syntax unless it's directly essential for explaining the specific behavior in the provided code relevant to the user's question.
+5.  **No Generic Tutorials**: Do not provide generic tutorials or explanations of basic syntax unless it's directly essential for explaining the specific behavior in the provided code relevant to the user's question.
-6.  **Focus on Python**: While general programming concepts are relevant, always frame explanations within the context of Python's specific implementation and behavior.
+6.  **Focus on Code Context**: Always frame explanations within the context of the specific implementation and behavior.
 
 ## VIII. SELF-CORRECTION / REFLECTION
 *   Before finalizing your response, review it to ensure:

.claude/workflows/cli-templates/prompts/memory/02-document-module-structure.txt

@@ -1,6 +1,12 @@
 Create or update CLAUDE.md documentation using unified module/file template.
 
+## ⚠️ FILE NAMING RULE (CRITICAL)
+- Target file: MUST be named exactly `CLAUDE.md` in the current directory
+- NEVER create files like `ToolSidebar.CLAUDE.md` or `[filename].CLAUDE.md`
+- ALWAYS use the fixed name: `CLAUDE.md`
+
 ## CORE CHECKLIST ⚡
+□ MUST create/update file named exactly 'CLAUDE.md' (not variants)
 □ MUST include all 6 sections: Purpose, Structure, Components, Dependencies, Integration, Implementation
 □ For code files: Document all public/exported APIs with complete parameter details
 □ For folders: Reference subdirectory CLAUDE.md files instead of duplicating
@@ -64,6 +70,11 @@ Create or update CLAUDE.md documentation using unified module/file template.
 
 ## OUTPUT REQUIREMENTS
 
+### File Naming (CRITICAL)
+- **Output file**: MUST be named exactly `CLAUDE.md` in the current directory
+- **Examples of WRONG naming**: `ToolSidebar.CLAUDE.md`, `index.CLAUDE.md`, `utils.CLAUDE.md`
+- **Correct naming**: `CLAUDE.md` (always, for all directories)
+
 ### Template Structure
 ```markdown
 # [Module/File Name]
@@ -143,6 +154,7 @@ Create or update CLAUDE.md documentation using unified module/file template.
 - Update existing CLAUDE.md files rather than creating duplicate sections
 
 ## VERIFICATION CHECKLIST ✓
+□ Output file is named exactly 'CLAUDE.md' (not [filename].CLAUDE.md)
 □ All 6 required sections included (Purpose, Structure, Components, Dependencies, Integration, Implementation)
 □ All public/exported APIs documented with complete signatures
 □ Parameters documented with types, descriptions, and defaults

.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt

@@ -40,51 +40,51 @@ Your response **MUST** be in Chinese and structured in Markdown as follows:
 ---
 
 ### 0. 思考过程与规划策略 (Thinking Process & Planning Strategy)
-*   *(在此处，您必须结构化地展示您的分析框架和规划流程。)*
+*   *(在此处,您必须结构化地展示您的分析框架和规划流程。)*
-*   **1. 需求解析 (Requirement Analysis):** 我首先将用户的原始需求进行拆解和澄清，确保完全理解其核心目标和边界条件。
+*   **1. 需求解析 (Requirement Analysis):** 我首先将用户的原始需求进行拆解和澄清,确保完全理解其核心目标和边界条件。
-*   **2. 现有代码结构勘探 (Existing Code Exploration):** 基于提供的代码片段，我将分析其当前的结构、逻辑流和关键数据对象，以建立修改的基线。
+*   **2. 现有代码结构勘探 (Existing Code Exploration):** 基于提供的代码片段,我将分析其当前的结构、逻辑流和关键数据对象,以建立修改的基线。
-*   **3. 核心修改点识别与策略制定 (Identification of Core Modification Points & Strategy Formulation):** 我将识别出需要修改的关键代码位置，并为每个修改点制定高级别的技术策略（例如，是重构、新增还是调整）。
+*   **3. 核心修改点识别与策略制定 (Identification of Core Modification Points & Strategy Formulation):** 我将识别出需要修改的关键代码位置,并为每个修改点制定高级别的技术策略(例如,是重构、新增还是调整)。
-*   **4. 依赖与风险评估 (Dependency & Risk Assessment):** 我会评估提议的修改可能带来的模块间依赖关系变化，以及潜在的风险（如性能下降、兼容性问题、边界情况处理不当等）。
+*   **4. 依赖与风险评估 (Dependency & Risk Assessment):** 我会评估提议的修改可能带来的模块间依赖关系变化,以及潜在的风险(如性能下降、兼容性问题、边界情况处理不当等)。
-*   **5. 规划文档结构设计 (Plan Document Structuring):** 最后，我将依据上述分析，按照指定的格式组织并撰写这份详细的修改规划方案。
+*   **5. 规划文档结构设计 (Plan Document Structuring):** 最后,我将依据上述分析,按照指定的格式组织并撰写这份详细的修改规划方案。
 
 ### **代码修改规划方案 (Code Modification Plan)**
 
-### **第一部分：需求分析与规划总览 (Part 1: Requirements Analysis & Planning Overview)**
+### **第一部分:需求分析与规划总览 (Part 1: Requirements Analysis & Planning Overview)**
 *   **1.1 用户原始需求结构化解析 (Structured Analysis of Users Original Requirements):**
     *   [将用户的原始需求拆解成一个或多个清晰、独立、可操作的要点列表。每个要点都是一个明确的目标。]
     *   **- 需求点 A:** [描述第一个具体需求]
     *   **- 需求点 B:** [描述第二个具体需求]
     *   **- ...**
 *   **1.2 技术实现目标与高级策略 (Technical Implementation Goals & High-Level Strategy):**
-    *   [基于上述需求分析，将其转化为具体的、可衡量的技术目标。并简述为达成这些目标将采用的整体技术思路或架构策略。例如：为实现【需求点A】，我们需要在 `ServiceA` 中引入一个新的处理流程。为实现【需求点B】，我们将重构 `ModuleB` 的数据验证逻辑，以提高其扩展性。]
+    *   [基于上述需求分析,将其转化为具体的、可衡量的技术目标。并简述为达成这些目标将采用的整体技术思路或架构策略。例如:为实现【需求点A】,我们需要在 `ServiceA` 中引入一个新的处理流程。为实现【需求点B】,我们将重构 `ModuleB` 的数据验证逻辑,以提高其扩展性。]
 
-### **第二部分：涉及文件概览 (Part 2: Involved Files Overview)**
+### **第二部分:涉及文件概览 (Part 2: Involved Files Overview)**
-*   **文件列表 (File List):** [列出所有识别出的相关文件名（若路径已知/可推断，请包含路径）。不仅包括直接修改的文件，也包括提供关键上下文或可能受间接影响的文件。示例: `- src/core/module_a.py (直接修改)`, `- src/utils/helpers.py (依赖项，可能受影响)`, `- configs/settings.json (配置参考)`]
+*   **文件列表 (File List):** [列出所有识别出的相关文件名(若路径已知/可推断,请包含路径)。不仅包括直接修改的文件,也包括提供关键上下文或可能受间接影响的文件。示例: `- src/core/module_a.py (直接修改)`, `- src/utils/helpers.py (依赖项,可能受影响)`, `- configs/settings.json (配置参考)`]
 
-### **第三部分：详细修改计划 (Part 3: Detailed Modification Plan)**
+### **第三部分:详细修改计划 (Part 3: Detailed Modification Plan)**
 ---
 *针对每个需要直接修改的文件进行描述:*
 
 **文件: [文件路径或文件名] (File: [File path or filename])**
 
 *   **1. 位置 (Location):**
-    *   [清晰说明函数、类、方法或具体的代码区域，如果可能，指出大致行号范围。示例: 函数 `calculate_total_price` 内部，约第 75-80 行]
+    *   [清晰说明函数、类、方法或具体的代码区域,如果可能,指出大致行号范围。示例: 函数 `calculate_total_price` 内部,约第 75-80 行]
 
 *   **1.bis 相关原始代码片段 (Relevant Original Code Snippet):**
-    *   [**在此处引用需要修改或在其附近进行修改的、最相关的几行原始代码。** 这为开发者提供了直接的上下文。如果代码未提供，则注明相关代码未提供，根据描述进行规划。]
+    *   [**在此处引用需要修改或在其附近进行修改的、最相关的几行原始代码。** 这为开发者提供了直接的上下文。如果代码未提供,则注明相关代码未提供,根据描述进行规划。]
     *   ```[language]
         // 引用相关的1-5行原始代码
         ```
 
 *   **2. 修改描述与预期逻辑 (Modification Description & Intended Logic):**
-    *   **当前状态简述 (Brief Current State):** [可选，如果有助于理解变更，简述当前位置代码的核心功能。]
+    *   **当前状态简述 (Brief Current State):** [可选,如果有助于理解变更,简述当前位置代码的核心功能。]
     *   **拟议修改点 (Proposed Changes):**
         *   [分步骤详细描述需要进行的逻辑更改。用清晰的中文自然语言解释 *什么* 需要被改变或添加。]
     *   **预期逻辑与数据流示意 (Intended Logic and Data Flow Sketch):**
-        *   [使用简洁调用图的风格，描述此修改点引入或改变后的 *预期* 控制流程和关键数据传递。]
+        *   [使用简洁调用图的风格,描述此修改点引入或改变后的 *预期* 控制流程和关键数据传递。]
         *   [**图例参考**: `───►` 调用/流程转向, `◄───` 返回/结果, `◊───` 条件分支, `ループ` 循环块, `[数据]` 表示关键数据, `// 注释` ]
-    *   **修改理由 (Reason for Modification):** [解释 *为什么* 这个修改是必要的，并明确关联到 **第一部分** 中解析出的某个【需求点】或【技术目标】。]
+    *   **修改理由 (Reason for Modification):** [解释 *为什么* 这个修改是必要的,并明确关联到 **第一部分** 中解析出的某个【需求点】或【技术目标】。]
-    *   **预期结果 (Intended Outcome):** [描述此修改完成后，该代码段预期的行为或产出。]
+    *   **预期结果 (Intended Outcome):** [描述此修改完成后,该代码段预期的行为或产出。]
 
 *   **3. 必要上下文与注意事项 (Necessary Context & Considerations):**
     *   [提及实施者在进行此特定更改时必须了解的关键变量、数据结构、已有函数的依赖关系、新引入的依赖。]