refactor(ui-design): enhance task attachment model and phase execution flow for improved clarity and automation

2026-02-12 02:37:45 +08:00 · 2025-11-11 18:48:04 +08:00
parent 4048ed4cc0
commit 52c8fe1d5c
4 changed files with 310 additions and 119 deletions
--- a/.claude/commands/workflow/ui-design/codify-style.md
+++ b/.claude/commands/workflow/ui-design/codify-style.md
@@ -21,17 +21,21 @@ auto-continue: true
 **Autonomous Flow** (⚠️ CONTINUOUS EXECUTION - DO NOT STOP):
 1. User triggers: `/workflow:ui-design:codify-style <path> --package-name <name>`
 2. Phase 0: Parameter validation & preparation → **IMMEDIATELY triggers Phase 1**
-3. Phase 1 (import-from-code) → **Execute phase (blocks until finished)** → Auto-continues to Phase 2
-4. Phase 2 (reference-page-generator) → **Execute phase (blocks until finished)** → Auto-continues to Phase 3
-5. Phase 3 (cleanup & verification) → Reports completion
+3. Phase 1 (import-from-code) → **Attach 4 tasks → Execute tasks → Collapse** → Auto-continues to Phase 2
+4. Phase 2 (reference-page-generator) → **Attach 4 tasks → Execute tasks → Collapse** → Auto-continues to Phase 3
+5. Phase 3 (cleanup & verification) → **Execute orchestrator task** → Reports completion

 **Phase Transition Mechanism**:
 - **Phase 0 (Validation)**: Validate parameters, prepare workspace → IMMEDIATELY triggers Phase 1
- **Phase 1-3 (Autonomous)**: `SlashCommand` is BLOCKING - execution pauses until the command finishes
- When each phase finishes executing: Automatically process output and execute next phase
+- **Phase 1-2 (Task Attachment)**: `SlashCommand` invocation **ATTACHES** tasks to current workflow. Orchestrator **EXECUTES** these tasks itself.
+- **Task Execution**: Orchestrator runs attached tasks sequentially, updating TodoWrite as each completes
+- **Task Collapse**: After all attached tasks complete, collapse them into phase summary
+- **Phase Transition**: Automatically execute next phase after collapsing completed tasks
 - No user interaction required after initial command

-**Auto-Continue Mechanism**: TodoWrite tracks phase status. When each phase finishes executing, you MUST immediately construct and execute the next phase command. No user intervention required. The workflow is NOT complete until reaching Phase 3.
+**Auto-Continue Mechanism**: TodoWrite tracks phase status with dynamic task attachment/collapse. After executing all attached tasks, you MUST immediately collapse them, restore phase summary, and execute the next phase. No user intervention required. The workflow is NOT complete until reaching Phase 3.
+
+**Task Attachment Model**: SlashCommand invocation is NOT delegation - it's task expansion. The orchestrator executes these attached tasks itself, not waiting for external completion.

 ## Core Rules

@@ -40,8 +44,9 @@ auto-continue: true
 3. **Parse & Pass**: Extract required data from each command output (design run path, metadata)
 4. **Intelligent Validation**: Smart parameter validation with user-friendly error messages
 5. **Safety First**: Package overwrite protection, existence checks, fallback error handling
-6. **Track Progress**: Update TodoWrite after EVERY phase completion before starting next phase
-7. **⚠️ CRITICAL: DO NOT STOP** - This is a continuous multi-phase workflow. Each SlashCommand execution blocks until finished, then you MUST immediately execute the next phase. Workflow is NOT complete until Phase 3.
+6. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
+7. **⚠️ CRITICAL: Task Attachment Model** - SlashCommand invocation **ATTACHES** tasks to current workflow. Orchestrator **EXECUTES** these attached tasks itself, not waiting for external completion. This is NOT delegation - it's task expansion.
+8. **⚠️ CRITICAL: DO NOT STOP** - This is a continuous multi-phase workflow. After executing all attached tasks, you MUST immediately collapse them and execute the next phase. Workflow is NOT complete until Phase 3.

 ---

@@ -96,13 +101,15 @@ auto-continue: true
 **TodoWrite** (First Action):
 ```json
 [
-  {"content": "Validate parameters and prepare session", "status": "in_progress", "activeForm": "Validating parameters"},
-  {"content": "Extract styles from source code", "status": "pending", "activeForm": "Extracting styles"},
-  {"content": "Generate reference package with preview", "status": "pending", "activeForm": "Generating reference"},
-  {"content": "Cleanup and verify package", "status": "pending", "activeForm": "Cleanup and verification"}
+  {"content": "Phase 0: Validate parameters and prepare session", "status": "in_progress", "activeForm": "Validating parameters"},
+  {"content": "Phase 1: Style extraction from source code (import-from-code)", "status": "pending", "activeForm": "Extracting styles"},
+  {"content": "Phase 2: Reference package generation (reference-page-generator)", "status": "pending", "activeForm": "Generating package"},
+  {"content": "Phase 3: Cleanup and verify package", "status": "pending", "activeForm": "Cleanup and verification"}
 ]
 ```

+**Note**: Orchestrator tracks only high-level phases. Sub-command details shown when executed.
+
 **Step 0a: Parse and Validate Required Parameters**

 ```bash
@@ -209,9 +216,24 @@ STORE: temp_session_id, temp_design_run_id, design_run_path
 - `TEMP_DESIGN_RUN_ID`: `design-run-{timestamp}`
 - `DESIGN_RUN_PATH`: Absolute path to temporary workspace

-**TodoWrite Update**: Mark Phase 0 completed, Phase 1 in_progress
+<!-- TodoWrite: Update Phase 0 → completed, Phase 1 → in_progress, INSERT import-from-code tasks -->

-**Next Action**: Validation complete → **IMMEDIATELY execute Phase 1** (auto-continue)
+**TodoWrite Update (Phase 1 SlashCommand invoked - tasks attached)**:
+```json
+[
+  {"content": "Phase 0: Validate parameters and prepare session", "status": "completed", "activeForm": "Validating parameters"},
+  {"content": "Phase 1.0: Discover and categorize code files (import-from-code)", "status": "in_progress", "activeForm": "Discovering code files"},
+  {"content": "Phase 1.1: Style Agent extraction (import-from-code)", "status": "pending", "activeForm": "Extracting style tokens"},
+  {"content": "Phase 1.2: Animation Agent extraction (import-from-code)", "status": "pending", "activeForm": "Extracting animation tokens"},
+  {"content": "Phase 1.3: Layout Agent extraction (import-from-code)", "status": "pending", "activeForm": "Extracting layout patterns"},
+  {"content": "Phase 2: Reference package generation (reference-page-generator)", "status": "pending", "activeForm": "Generating package"},
+  {"content": "Phase 3: Cleanup and verify package", "status": "pending", "activeForm": "Cleanup and verification"}
+]
+```
+
+**Note**: SlashCommand invocation **attaches** import-from-code's 4 tasks to current workflow. Orchestrator **executes** these tasks itself.
+
+**Next Action**: Tasks attached → **Execute Phase 1.0-1.3** sequentially

 ---

@@ -228,13 +250,19 @@ command = "/workflow:ui-design:import-from-code" +
          " --source \"${source}\""
 ```

-**Execute Command**:
+**Execute Command (Task Attachment Pattern)**:

 ```bash
 TRY:
+    # SlashCommand invocation ATTACHES import-from-code's 4 tasks to current workflow
+    # Orchestrator will EXECUTE these attached tasks itself:
+    #   1. Phase 1.0: Discover and categorize code files
+    #   2. Phase 1.1: Style Agent extraction
+    #   3. Phase 1.2: Animation Agent extraction
+    #   4. Phase 1.3: Layout Agent extraction
    SlashCommand(command)

-    # Verify extraction outputs
+    # After executing all attached tasks, verify extraction outputs
    tokens_path = "${design_run_path}/style-extraction/style-1/design-tokens.json"
    guide_path = "${design_run_path}/style-extraction/style-1/style-guide.md"

@@ -269,9 +297,24 @@ CATCH error:
  - `animation-tokens.json` - Animation specifications
  - `component-patterns.json` - Component catalog

-**TodoWrite Update**: Mark Phase 1 completed, Phase 2 in_progress
+<!-- TodoWrite: REMOVE Phase 1.0-1.3 tasks, INSERT reference-page-generator tasks -->

-**Next Action**: Extraction verified → **IMMEDIATELY execute Phase 2** (auto-continue)
+**TodoWrite Update (Phase 2 SlashCommand invoked - tasks attached)**:
+```json
+[
+  {"content": "Phase 0: Validate parameters and prepare session", "status": "completed", "activeForm": "Validating parameters"},
+  {"content": "Phase 1: Style extraction from source code (import-from-code)", "status": "completed", "activeForm": "Extracting styles"},
+  {"content": "Phase 2.1: Validation and preparation (reference-page-generator)", "status": "in_progress", "activeForm": "Validating parameters"},
+  {"content": "Phase 2.2: Component pattern extraction (reference-page-generator)", "status": "pending", "activeForm": "Extracting component patterns"},
+  {"content": "Phase 2.3: Generate preview pages (reference-page-generator)", "status": "pending", "activeForm": "Generating preview"},
+  {"content": "Phase 2.4: Generate metadata and documentation (reference-page-generator)", "status": "pending", "activeForm": "Generating documentation"},
+  {"content": "Phase 3: Cleanup and verify package", "status": "pending", "activeForm": "Cleanup and verification"}
+]
+```
+
+**Note**: Phase 1 tasks completed and collapsed. SlashCommand invocation **attaches** reference-page-generator's 4 tasks. Orchestrator **executes** these tasks itself.
+
+**Next Action**: Tasks attached → **Execute Phase 2.1-2.4** sequentially

 ---

@@ -288,13 +331,19 @@ command = "/workflow:ui-design:reference-page-generator " +
          "--output-dir \"${output_dir}\""
 ```

-**Execute Command**:
+**Execute Command (Task Attachment Pattern)**:

 ```bash
 TRY:
+    # SlashCommand invocation ATTACHES reference-page-generator's 4 tasks to current workflow
+    # Orchestrator will EXECUTE these attached tasks itself:
+    #   1. Phase 2.1: Validation and preparation
+    #   2. Phase 2.2: Component pattern extraction
+    #   3. Phase 2.3: Generate preview pages
+    #   4. Phase 2.4: Generate metadata and documentation
    SlashCommand(command)

-    # Verify package outputs
+    # After executing all attached tasks, verify package outputs
    required_files = [
        "design-tokens.json",
        "component-patterns.json",
@@ -343,9 +392,21 @@ CATCH error:
 - ⭕ Optional files:
  - `animation-tokens.json` - Animation specifications (if available from extraction)

-**TodoWrite Update**: Mark Phase 2 completed, Phase 3 in_progress
+<!-- TodoWrite: REMOVE Phase 2.1-2.4 tasks, restore to orchestrator view -->

-**Next Action**: Package verified → **IMMEDIATELY execute Phase 3** (auto-continue)
+**TodoWrite Update (Phase 2 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Phase 0: Validate parameters and prepare session", "status": "completed", "activeForm": "Validating parameters"},
+  {"content": "Phase 1: Style extraction from source code (import-from-code)", "status": "completed", "activeForm": "Extracting styles"},
+  {"content": "Phase 2: Reference package generation (reference-page-generator)", "status": "completed", "activeForm": "Generating package"},
+  {"content": "Phase 3: Cleanup and verify package", "status": "in_progress", "activeForm": "Cleanup and verification"}
+]
+```
+
+**Note**: Phase 2 tasks completed and collapsed to summary.
+
+**Next Action**: TodoWrite restored → **Execute Phase 3** (orchestrator's own task)

 ---

@@ -375,7 +436,7 @@ component_count = Bash(jq -r '.extraction_metadata.component_count // "unknown"'
 anim_exists = Bash(test -f "${package_path}/animation-tokens.json" && echo "✓" || echo "○")
 ```

-**TodoWrite Update**: Mark Phase 3 completed
+<!-- TodoWrite: Update Phase 3 → completed -->

 **Final Action**: Display completion summary to user

@@ -403,20 +464,52 @@ Next: /memory:style-skill-memory {package_name}
 ## TodoWrite Pattern

 ```javascript
-// Initialize IMMEDIATELY after user confirms in Phase 0 to track multi-phase execution
+// Initialize IMMEDIATELY at the start to track orchestrator workflow (4 high-level tasks)
 TodoWrite({todos: [
-  {"content": "Validate parameters and prepare session", "status": "in_progress", "activeForm": "Validating parameters"},
-  {"content": "Extract styles from source code", "status": "pending", "activeForm": "Extracting styles"},
-  {"content": "Generate reference package with preview", "status": "pending", "activeForm": "Generating reference"},
-  {"content": "Cleanup and verify package", "status": "pending", "activeForm": "Cleanup and verification"}
+  {"content": "Phase 0: Validate parameters and prepare session", "status": "in_progress", "activeForm": "Validating parameters"},
+  {"content": "Phase 1: Style extraction from source code (import-from-code)", "status": "pending", "activeForm": "Extracting styles"},
+  {"content": "Phase 2: Reference package generation (reference-page-generator)", "status": "pending", "activeForm": "Generating package"},
+  {"content": "Phase 3: Cleanup and verify package", "status": "pending", "activeForm": "Cleanup and verification"}
 ]})

-// ⚠️ CRITICAL: When each phase finishes, you MUST:
-// 1. SlashCommand blocks and returns when phase finishes executing
-// 2. Update current phase: status → "completed"
-// 3. Update next phase: status → "in_progress"
-// 4. IMMEDIATELY execute next phase command (auto-continue)
-// This ensures continuous workflow tracking and prevents premature stopping
+// ⚠️ CRITICAL: Dynamic TodoWrite task attachment strategy:
+//
+// **Key Concept**: SlashCommand invocation ATTACHES tasks to current workflow.
+// Orchestrator EXECUTES these attached tasks itself, not waiting for external completion.
+//
+// 1. INITIAL STATE: 4 orchestrator-level tasks only
+//
+// 2. PHASE 1 SlashCommand INVOCATION:
+//    - SlashCommand(/workflow:ui-design:import-from-code) ATTACHES 4 tasks
+//    - TodoWrite expands to: Phase 0 (completed) + 4 import-from-code tasks + Phase 2 + Phase 3
+//    - Orchestrator EXECUTES these 4 tasks sequentially (Phase 1.0 → 1.1 → 1.2 → 1.3)
+//    - First attached task marked as in_progress
+//
+// 3. PHASE 1 TASKS COMPLETED:
+//    - All 4 import-from-code tasks executed and completed
+//    - COLLAPSE completed tasks into Phase 1 summary
+//    - TodoWrite becomes: Phase 0-1 (completed) + Phase 2 + Phase 3
+//
+// 4. PHASE 2 SlashCommand INVOCATION:
+//    - SlashCommand(/workflow:ui-design:reference-page-generator) ATTACHES 4 tasks
+//    - TodoWrite expands to: Phase 0-1 (completed) + 4 reference-page-generator tasks + Phase 3
+//    - Orchestrator EXECUTES these 4 tasks sequentially (Phase 2.1 → 2.2 → 2.3 → 2.4)
+//
+// 5. PHASE 2 TASKS COMPLETED:
+//    - All 4 reference-page-generator tasks executed and completed
+//    - COLLAPSE completed tasks into Phase 2 summary
+//    - TodoWrite returns to: Phase 0-2 (completed) + Phase 3 (in_progress)
+//
+// 6. PHASE 3 EXECUTION:
+//    - Orchestrator's own task (no SlashCommand attachment)
+//    - Mark Phase 3 as completed
+//    - Final state: All 4 orchestrator tasks completed
+//
+// Benefits:
+// ✓ Real-time visibility into attached tasks during execution
+// ✓ Clean orchestrator-level summary after tasks complete
+// ✓ Clear mental model: SlashCommand = attach tasks, not delegate work
+// ✓ Dynamic attachment/collapse maintains clarity
 ```

 ---
@@ -426,44 +519,73 @@ TodoWrite({todos: [
 ```
 User triggers: /workflow:ui-design:codify-style ./src --package-name my-style-v1
  ↓
-[Phase 0] TodoWrite initialization (4 phases)
+[TodoWrite Init] 4 orchestrator-level tasks
+  ├─ Phase 0: Validate parameters and prepare session (in_progress)
+  ├─ Phase 1: Style extraction from source code (pending)
+  ├─ Phase 2: Reference package generation (pending)
+  └─ Phase 3: Cleanup and verify package (pending)
  ↓
 [Phase 0] Parameter validation & preparation
  ├─ Parse positional path parameter
  ├─ Validate source directory exists
  ├─ Auto-generate or validate package name
-  │  • If --package-name provided: validate format
-  │  • If not provided: auto-generate from directory name
-  ├─ Check package overwrite protection (fail if exists without --overwrite)
+  ├─ Check package overwrite protection
  ├─ Create temporary workspace
  └─ Display configuration summary
  ↓
-[Phase 0 Complete] → TodoWrite(Phase 0 = completed, Phase 1 = in_progress)
-  ↓ (IMMEDIATELY auto-continue)
-[Phase 1] SlashCommand(/workflow:ui-design:import-from-code ...)
-  ├─ Extract design tokens from source code
-  ├─ Generate style guide
-  ├─ Extract component patterns
-  └─ Verify extraction outputs
-  ↓ (blocks until finished)
-[Phase 1 Complete] → TodoWrite(Phase 1 = completed, Phase 2 = in_progress)
-  ↓ (IMMEDIATELY auto-continue)
-[Phase 2] SlashCommand(/workflow:ui-design:reference-page-generator ...)
-  ├─ Generate design-tokens.json
-  ├─ Generate component-patterns.json
-  ├─ Create preview.html + preview.css
-  ├─ Generate metadata.json
-  └─ Create README.md
-  ↓ (blocks until finished)
-[Phase 2 Complete] → TodoWrite(Phase 2 = completed, Phase 3 = in_progress)
-  ↓ (IMMEDIATELY auto-continue)
-[Phase 3] Cleanup & Verification
+[Phase 0 Complete] → TodoWrite: Phase 0 → completed
+  ↓
+[Phase 1 Invoke] → SlashCommand(/workflow:ui-design:import-from-code) ATTACHES 4 tasks
+  ├─ Phase 0 (completed)
+  ├─ Phase 1.0: Discover and categorize code files (in_progress)  ← ATTACHED
+  ├─ Phase 1.1: Style Agent extraction (pending)                   ← ATTACHED
+  ├─ Phase 1.2: Animation Agent extraction (pending)               ← ATTACHED
+  ├─ Phase 1.3: Layout Agent extraction (pending)                  ← ATTACHED
+  ├─ Phase 2: Reference package generation (pending)
+  └─ Phase 3: Cleanup and verify package (pending)
+  ↓
+[Execute Phase 1.0] → Discover files (orchestrator executes this)
+  ↓
+[Execute Phase 1.1-1.3] → Run 3 agents in parallel (orchestrator executes these)
+  └─ Outputs: design-tokens.json, style-guide.md, animation-tokens.json, layout-templates.json
+  ↓
+[Phase 1 Complete] → TodoWrite: COLLAPSE Phase 1.0-1.3 into Phase 1 summary
+  ↓
+[Phase 2 Invoke] → SlashCommand(/workflow:ui-design:reference-page-generator) ATTACHES 4 tasks
+  ├─ Phase 0 (completed)
+  ├─ Phase 1: Style extraction from source code (completed)        ← COLLAPSED
+  ├─ Phase 2.1: Validation and preparation (in_progress)           ← ATTACHED
+  ├─ Phase 2.2: Component pattern extraction (pending)             ← ATTACHED
+  ├─ Phase 2.3: Generate preview pages (pending)                   ← ATTACHED
+  ├─ Phase 2.4: Generate metadata and documentation (pending)      ← ATTACHED
+  └─ Phase 3: Cleanup and verify package (pending)
+  ↓
+[Execute Phase 2.1] → Validate parameters (orchestrator executes this)
+  ↓
+[Execute Phase 2.2] → Extract component patterns (orchestrator executes this)
+  ↓
+[Execute Phase 2.3] → Generate preview pages (orchestrator executes this)
+  ↓
+[Execute Phase 2.4] → Generate metadata and docs (orchestrator executes this)
+  └─ Outputs: component-patterns.json, preview.html, preview.css, metadata.json, README.md
+  ↓
+[Phase 2 Complete] → TodoWrite: COLLAPSE Phase 2.1-2.4 into Phase 2 summary
+  ├─ Phase 0 (completed)
+  ├─ Phase 1: Style extraction from source code (completed)
+  ├─ Phase 2: Reference package generation (completed)             ← COLLAPSED
+  └─ Phase 3: Cleanup and verify package (in_progress)
+  ↓
+[Execute Phase 3] → Orchestrator's own task (no attachment needed)
  ├─ Remove temporary workspace
  ├─ Verify package directory
  ├─ Extract component count
  └─ Display completion summary
  ↓
-[Phase 3 Complete] → TodoWrite(Phase 3 = completed)
+[Phase 3 Complete] → TodoWrite: Phase 3 → completed
+  ├─ Phase 0 (completed)
+  ├─ Phase 1 (completed)
+  ├─ Phase 2 (completed)
+  └─ Phase 3 (completed)
 ```

 ---