catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-11 02:33:51 +08:00
Code Issues Packages Projects Releases Wiki Activity

Refactor workflows to enhance task attachment and execution model

Browse Source 
- Updated auto-parallel.md to clarify the task attachment model, emphasizing the orchestration of tasks through attachment rather than delegation. Improved descriptions of phases and execution flow.
- Revised plan.md, tdd-plan.md, test-fix-gen.md, and test-gen.md to simplify lifecycle patterns, replacing detailed patterns with concise lifecycle summaries.
- Modified reference-page-generator.md to streamline the component extraction process, focusing on layout templates and removing unnecessary complexity in the operations.
- Enhanced error handling and output messages across various workflows to improve clarity and user guidance.
This commit is contained in:
catlog22
2025-11-11 19:52:58 +08:00
parent 7d77b0e6f7
commit a393d95cf9
6 changed files with 194 additions and 495 deletions
Download Patch File Download Diff File Expand all files Collapse all files

203
.claude/commands/workflow/brainstorm/auto-parallel.md
View File

@@ -9,22 +9,32 @@ allowed-tools: SlashCommand(*), Task(*), TodoWrite(*), Read(*), Write(*), Bash(*
## Coordinator Role ## 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**. **This command is a pure orchestrator**: Execute 3 phases in sequence (interactive framework → parallel role analysis → synthesis), coordinating specialized commands/agents through task attachment model.
**Task Attachment Model**:
- SlashCommand invocation **expands workflow** by attaching sub-tasks to current TodoWrite
- Task agent execution **attaches analysis tasks** to orchestrator's TodoWrite
- Phase 1: artifacts command attaches its internal tasks (Phase 1-5)
- Phase 2: N conceptual-planning-agent tasks attached in parallel
- Phase 3: synthesis command attaches its internal tasks
- Orchestrator **executes these attached tasks** sequentially (Phase 1, 3) or in parallel (Phase 2)
- After completion, attached tasks are **collapsed** back to high-level phase summary
- This is **task expansion**, not external delegation
**Execution Model - Auto-Continue Workflow**: **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. 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]` 1. **User triggers**: `/workflow:brainstorm:auto-parallel "topic" [--count N]`
2. **Phase 1 executes** → artifacts command (interactive framework) → Auto-continues 2. **Phase 1 executes** → artifacts command (tasks ATTACHED) → Auto-continues
3. **Phase 2 executes** → Parallel role agents (N agents run concurrently) → Auto-continues 3. **Phase 2 executes** → Parallel role agents (N tasks ATTACHED concurrently) → Auto-continues
4. **Phase 3 executes** → Synthesis command → Reports final summary 4. **Phase 3 executes** → Synthesis command (tasks ATTACHED) → Reports final summary
**Auto-Continue Mechanism**: **Auto-Continue Mechanism**:
- TodoList tracks current phase status - TodoList tracks current phase status and dynamically manages task attachment/collapse
- When Phase 1 (artifacts) finishes executing, automatically load roles and launch Phase 2 agents - When Phase 1 (artifacts) finishes executing, automatically load roles and launch Phase 2 agents
- When Phase 2 (all agents) finishes executing, automatically execute Phase 3 synthesis - When Phase 2 (all agents) finishes executing, automatically execute Phase 3 synthesis
- Progress updates shown at each phase for visibility - **⚠️ CONTINUOUS EXECUTION** - Do not stop until all phases complete
## Core Rules ## Core Rules
@@ -32,8 +42,10 @@ This workflow runs **fully autonomously** once triggered. Phase 1 (artifacts) ha
2. **No Preliminary Analysis**: Do not analyze topic before Phase 1 - artifacts handles all analysis 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 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 4. **Auto-Continue via TodoList**: Check TodoList status to execute next pending phase automatically
5. **Track Progress**: Update TodoWrite when each phase finishes executing 5. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
6. **TodoWrite Extension**: artifacts command EXTENDS parent TodoList (NOT replaces) 6. **Task Attachment Model**: SlashCommand and Task invocations **attach** sub-tasks to current workflow. Orchestrator **executes** these attached tasks itself, then **collapses** them after completion
7. **⚠️ CRITICAL: DO NOT STOP**: Continuous multi-phase workflow. After executing all attached tasks, immediately collapse them and execute next phase
8. **Parallel Execution**: Phase 2 attaches multiple agent tasks simultaneously for concurrent execution
## Usage ## Usage
@@ -74,15 +86,37 @@ This workflow runs **fully autonomously** once triggered. Phase 1 (artifacts) ha
- workflow-session.json contains selected_roles[] (metadata only, no content duplication) - workflow-session.json contains selected_roles[] (metadata only, no content duplication)
- Session directory `.workflow/WFS-{topic}/.brainstorming/` exists - Session directory `.workflow/WFS-{topic}/.brainstorming/` exists
**TodoWrite**: Mark phase 1 completed, phase 2 in_progress **TodoWrite Update (Phase 1 SlashCommand invoked - tasks attached)**:
```json
[
{"content": "Parse --count parameter from user input", "status": "completed", "activeForm": "Parsing count parameter"},
{"content": "Phase 1.1: Topic analysis and question generation (artifacts)", "status": "in_progress", "activeForm": "Analyzing topic"},
{"content": "Phase 1.2: Role selection and user confirmation (artifacts)", "status": "pending", "activeForm": "Selecting roles"},
{"content": "Phase 1.3: Role questions and user decisions (artifacts)", "status": "pending", "activeForm": "Collecting role questions"},
{"content": "Phase 1.4: Conflict detection and resolution (artifacts)", "status": "pending", "activeForm": "Resolving conflicts"},
{"content": "Phase 1.5: Guidance specification generation (artifacts)", "status": "pending", "activeForm": "Generating guidance"},
{"content": "Execute parallel role analysis", "status": "pending", "activeForm": "Executing parallel role analysis"},
{"content": "Execute synthesis integration", "status": "pending", "activeForm": "Executing synthesis integration"}
]
```
**After Phase 1**: Auto-continue to Phase 2 (role agent assignment) **Note**: SlashCommand invocation **attaches** artifacts' 5 internal tasks. Orchestrator **executes** these tasks sequentially.
**⚠️ TodoWrite Coordination**: artifacts EXTENDS parent TodoList by: **Next Action**: Tasks attached → **Execute Phase 1.1-1.5** sequentially
- Marking parent task "Execute artifacts..." as in_progress
- APPENDING artifacts sub-tasks (Phase 1-5) after parent task **TodoWrite Update (Phase 1 completed - tasks collapsed)**:
- PRESERVING all other auto-parallel tasks (role agents, synthesis) ```json
- When artifacts Phase 5 completes, marking parent task as completed [
{"content": "Parse --count parameter from user input", "status": "completed", "activeForm": "Parsing count parameter"},
{"content": "Execute artifacts interactive framework generation", "status": "completed", "activeForm": "Executing artifacts interactive framework"},
{"content": "Execute parallel role analysis", "status": "pending", "activeForm": "Executing parallel role analysis"},
{"content": "Execute synthesis integration", "status": "pending", "activeForm": "Executing synthesis integration"}
]
```
**Note**: Phase 1 tasks completed and collapsed to summary.
**After Phase 1**: Auto-continue to Phase 2 (parallel role agent execution)
--- ---
@@ -143,8 +177,9 @@ TOPIC: {user-provided-topic}
**Parallel Execution**: **Parallel Execution**:
- Launch N agents simultaneously (one message with multiple Task calls) - Launch N agents simultaneously (one message with multiple Task calls)
- Each agent task **attached** to orchestrator's TodoWrite
- All agents execute concurrently, each attaching their own analysis sub-tasks
- Each agent operates independently reading same guidance-specification.md - Each agent operates independently reading same guidance-specification.md
- All agents update progress concurrently
**Input**: **Input**:
- `selected_roles[]` from Phase 1 - `selected_roles[]` from Phase 1
@@ -158,7 +193,33 @@ TOPIC: {user-provided-topic}
- **FORBIDDEN naming**: No `recommendations.md`, `recommendations-*.md`, or any non-`analysis` prefixed files - **FORBIDDEN naming**: No `recommendations.md`, `recommendations-*.md`, or any non-`analysis` prefixed files
- All N role analyses completed - All N role analyses completed
**TodoWrite**: Mark all N role agent tasks completed, phase 3 in_progress **TodoWrite Update (Phase 2 agents invoked - tasks attached in parallel)**:
```json
[
{"content": "Parse --count parameter from user input", "status": "completed", "activeForm": "Parsing count parameter"},
{"content": "Execute artifacts interactive framework generation", "status": "completed", "activeForm": "Executing artifacts interactive framework"},
{"content": "Phase 2.1: Execute system-architect analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing system-architect analysis"},
{"content": "Phase 2.2: Execute ui-designer analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing ui-designer analysis"},
{"content": "Phase 2.3: Execute product-manager analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing product-manager analysis"},
{"content": "Execute synthesis integration", "status": "pending", "activeForm": "Executing synthesis integration"}
]
```
**Note**: Multiple Task invocations **attach** N role analysis tasks simultaneously. Orchestrator **executes** these tasks in parallel.
**Next Action**: Tasks attached → **Execute Phase 2.1-2.N** concurrently
**TodoWrite Update (Phase 2 completed - tasks collapsed)**:
```json
[
{"content": "Parse --count parameter from user input", "status": "completed", "activeForm": "Parsing count parameter"},
{"content": "Execute artifacts interactive framework generation", "status": "completed", "activeForm": "Executing artifacts interactive framework"},
{"content": "Execute parallel role analysis", "status": "completed", "activeForm": "Executing parallel role analysis"},
{"content": "Execute synthesis integration", "status": "pending", "activeForm": "Executing synthesis integration"}
]
```
**Note**: Phase 2 parallel tasks completed and collapsed to summary.
**After Phase 2**: Auto-continue to Phase 3 (synthesis) **After Phase 2**: Auto-continue to Phase 3 (synthesis)
@@ -180,7 +241,33 @@ TOPIC: {user-provided-topic}
- `.workflow/WFS-{topic}/.brainstorming/synthesis-specification.md` exists - `.workflow/WFS-{topic}/.brainstorming/synthesis-specification.md` exists
- Synthesis references all role analyses - Synthesis references all role analyses
**TodoWrite**: Mark phase 3 completed **TodoWrite Update (Phase 3 SlashCommand invoked - tasks attached)**:
```json
[
{"content": "Parse --count parameter from user input", "status": "completed", "activeForm": "Parsing count parameter"},
{"content": "Execute artifacts interactive framework generation", "status": "completed", "activeForm": "Executing artifacts interactive framework"},
{"content": "Execute parallel role analysis", "status": "completed", "activeForm": "Executing parallel role analysis"},
{"content": "Phase 3.1: Load role analysis files (synthesis)", "status": "in_progress", "activeForm": "Loading role analyses"},
{"content": "Phase 3.2: Integrate insights across roles (synthesis)", "status": "pending", "activeForm": "Integrating insights"},
{"content": "Phase 3.3: Generate synthesis specification (synthesis)", "status": "pending", "activeForm": "Generating synthesis"}
]
```
**Note**: SlashCommand invocation **attaches** synthesis' internal tasks. Orchestrator **executes** these tasks sequentially.
**Next Action**: Tasks attached → **Execute Phase 3.1-3.3** sequentially
**TodoWrite Update (Phase 3 completed - tasks collapsed)**:
```json
[
{"content": "Parse --count parameter from user input", "status": "completed", "activeForm": "Parsing count parameter"},
{"content": "Execute artifacts interactive framework generation", "status": "completed", "activeForm": "Executing artifacts interactive framework"},
{"content": "Execute parallel role analysis", "status": "completed", "activeForm": "Executing parallel role analysis"},
{"content": "Execute synthesis integration", "status": "completed", "activeForm": "Executing synthesis integration"}
]
```
**Note**: Phase 3 tasks completed and collapsed to summary.
**Return to User**: **Return to User**:
``` ```
@@ -195,49 +282,49 @@ Synthesis: .workflow/WFS-{topic}/.brainstorming/synthesis-specification.md
## TodoWrite Pattern ## TodoWrite Pattern
```javascript **Core Concept**: Dynamic task attachment and collapse for parallel brainstorming workflow with interactive framework generation and concurrent role analysis.
// 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) ### Key Principles
// 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) 1. **Task Attachment** (when SlashCommand/Task invoked):
TodoWrite({todos: [ - Sub-command's or agent's internal tasks are **attached** to orchestrator's TodoWrite
// ... previous completed tasks - Phase 1: `/workflow:brainstorm:artifacts` attaches 5 internal tasks (Phase 1.1-1.5)
{"content": "Load selected_roles from workflow-session.json", "status": "completed", "activeForm": "Loading selected roles"}, - Phase 2: Multiple `Task(conceptual-planning-agent)` calls attach N role analysis tasks simultaneously
{"content": "Execute system-architect analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing system-architect analysis"}, - Phase 3: `/workflow:brainstorm:synthesis` attaches 3 internal tasks (Phase 3.1-3.3)
{"content": "Execute ui-designer analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing ui-designer analysis"}, - First attached task marked as `in_progress`, others as `pending`
{"content": "Execute product-manager analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing product-manager analysis"}, - Orchestrator **executes** these attached tasks (sequentially for Phase 1, 3; in parallel for Phase 2)
// ... (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) 2. **Task Collapse** (after sub-tasks complete):
TodoWrite({todos: [ - Remove detailed sub-tasks from TodoWrite
// ... previous completed tasks - **Collapse** to high-level phase summary
{"content": "Execute system-architect analysis [conceptual-planning-agent]", "status": "completed", "activeForm": "Executing system-architect analysis"}, - Example: Phase 1.1-1.5 collapse to "Execute artifacts interactive framework generation: completed"
{"content": "Execute ui-designer analysis [conceptual-planning-agent]", "status": "completed", "activeForm": "Executing ui-designer analysis"}, - Phase 2: Multiple role tasks collapse to "Execute parallel role analysis: completed"
{"content": "Execute product-manager analysis [conceptual-planning-agent]", "status": "completed", "activeForm": "Executing product-manager analysis"}, - Phase 3: Synthesis tasks collapse to "Execute synthesis integration: completed"
{"content": "Execute synthesis command for final integration", "status": "in_progress", "activeForm": "Executing synthesis integration"} - Maintains clean orchestrator-level view
]})
``` 3. **Continuous Execution**:
- After collapse, automatically proceed to next pending phase
- No user intervention required between phases
- TodoWrite dynamically reflects current execution state
**Lifecycle Summary**: Initial pending tasks → Phase 1 invoked (artifacts tasks ATTACHED) → Artifacts sub-tasks executed → Phase 1 completed (tasks COLLAPSED) → Phase 2 invoked (N role tasks ATTACHED in parallel) → Role analyses executed concurrently → Phase 2 completed (tasks COLLAPSED) → Phase 3 invoked (synthesis tasks ATTACHED) → Synthesis sub-tasks executed → Phase 3 completed (tasks COLLAPSED) → Workflow complete.
### Brainstorming Workflow Specific Features
- **Phase 1**: Interactive framework generation with user Q&A (SlashCommand attachment)
- **Phase 2**: Parallel role analysis execution with N concurrent agents (Task agent attachments)
- **Phase 3**: Cross-role synthesis integration (SlashCommand attachment)
- **Dynamic Role Count**: `--count N` parameter determines number of Phase 2 parallel tasks (default: 3, max: 9)
- **Mixed Execution**: Sequential (Phase 1, 3) and Parallel (Phase 2) task execution
**Benefits**:
- Real-time visibility into attached tasks during execution
- Clean orchestrator-level summary after tasks complete
- Clear mental model: SlashCommand/Task = attach tasks, not delegate work
- Parallel execution support for concurrent role analysis
- Dynamic attachment/collapse maintains clarity
**Note**: See individual Phase descriptions (Phase 1, 2, 3) for detailed TodoWrite Update examples with full JSON structures.
## Input Processing ## Input Processing

12
.claude/commands/workflow/plan.md
View File

@@ -303,17 +303,7 @@ Quality Gate: Consider running /workflow:action-plan-verify to catch issues earl
- No user intervention required between phases - No user intervention required between phases
- TodoWrite dynamically reflects current execution state - TodoWrite dynamically reflects current execution state
### Lifecycle Pattern **Lifecycle Summary**: Initial pending tasks → Phase invoked (tasks ATTACHED) → Sub-tasks executed sequentially → Phase completed (tasks COLLAPSED to summary) → Next phase begins → Repeat until all phases complete.
```
Initial: [Phase 1: pending] [Phase 2: pending] [Phase 3: pending]
↓
Phase 2 Invoked (ATTACHED):
[Phase 1: completed] [Phase 2.1: in_progress] [Phase 2.2: pending] [Phase 2.3: pending] [Phase 3: pending]
↓
Phase 2 Completed (COLLAPSED):
[Phase 1: completed] [Phase 2: completed] [Phase 3: pending]
```
### Benefits ### Benefits

18
.claude/commands/workflow/tdd-plan.md
View File

@@ -337,23 +337,7 @@ Quality Gate: Consider running /workflow:action-plan-verify to validate TDD task
- No user intervention required between phases - No user intervention required between phases
- TodoWrite dynamically reflects current execution state - TodoWrite dynamically reflects current execution state
### Lifecycle Pattern **Lifecycle Summary**: Initial pending tasks → Phase invoked (tasks ATTACHED) → Sub-tasks executed sequentially → Phase completed (tasks COLLAPSED to summary) → Next phase begins (conditional Phase 4 if conflict_risk ≥ medium) → Repeat until all phases complete.
```
Initial: [Phase 1: pending] [Phase 2: pending] [Phase 3: pending] [Phase 5: pending]
↓
Phase 3 Invoked (ATTACHED):
[Phase 1-2: completed] [Phase 3.1: in_progress] [Phase 3.2: pending] [Phase 3.3: pending] [Phase 5: pending]
↓
Phase 3 Completed (COLLAPSED):
[Phase 1-2: completed] [Phase 3: completed] [Phase 5: pending]
↓
Phase 5 Invoked (ATTACHED, generates TDD tasks):
[Phase 1-3: completed] [Phase 5.1: in_progress] [Phase 5.2: pending] [Phase 5.3: pending]
↓
Phase 5 Completed (COLLAPSED, each IMPL task contains Red-Green-Refactor cycle):
[Phase 1-3: completed] [Phase 5: completed] [Phase 6: in_progress]
```
### TDD-Specific Features ### TDD-Specific Features

20
.claude/commands/workflow/test-fix-gen.md
View File

@@ -362,25 +362,7 @@ CRITICAL - Next Steps:
- No user intervention required between phases - No user intervention required between phases
- TodoWrite dynamically reflects current execution state - TodoWrite dynamically reflects current execution state
#### Lifecycle Pattern **Lifecycle Summary**: Initial pending tasks → Phase invoked (tasks ATTACHED with mode-specific context gathering) → Sub-tasks executed sequentially → Phase completed (tasks COLLAPSED to summary) → Next phase begins → Repeat until all phases complete.
```
Initial: [Phase 1: pending] [Phase 2: pending] [Phase 3: pending] [Phase 4: pending] [Phase 5: pending]
↓
Phase 2 Invoked (ATTACHED - mode-specific context gathering):
[Phase 1: completed] [Phase 2.1: in_progress] [Phase 2.2: pending] [Phase 2.3: pending] [Phase 3: pending] [Phase 4: pending] [Phase 5: pending]
↓
Phase 2 Completed (COLLAPSED):
[Phase 1: completed] [Phase 2: completed] [Phase 3: pending] [Phase 4: pending] [Phase 5: pending]
↓
Phase 3 Invoked (ATTACHED):
[Phase 1: completed] [Phase 2: completed] [Phase 3.1: in_progress] [Phase 3.2: pending] [Phase 3.3: pending] [Phase 4: pending] [Phase 5: pending]
↓
Phase 3 Completed (COLLAPSED):
[Phase 1: completed] [Phase 2: completed] [Phase 3: completed] [Phase 4: pending] [Phase 5: pending]
↓
[Continue pattern through Phase 4 and Phase 5...]
```
#### Test-Fix-Gen Specific Features #### Test-Fix-Gen Specific Features

20
.claude/commands/workflow/test-gen.md
View File

@@ -346,25 +346,7 @@ Ready for execution. Use appropriate workflow commands to proceed.
- No user intervention required between phases - No user intervention required between phases
- TodoWrite dynamically reflects current execution state - TodoWrite dynamically reflects current execution state
### Lifecycle Pattern **Lifecycle Summary**: Initial pending tasks → Phase invoked (tasks ATTACHED) → Sub-tasks executed sequentially → Phase completed (tasks COLLAPSED to summary) → Next phase begins → Repeat until all phases complete.
```
Initial: [Phase 1: pending] [Phase 2: pending] [Phase 3: pending] [Phase 4: pending] [Phase 5: pending]
↓
Phase 2 Invoked (ATTACHED):
[Phase 1: completed] [Phase 2.1: in_progress] [Phase 2.2: pending] [Phase 2.3: pending] [Phase 3: pending] [Phase 4: pending] [Phase 5: pending]
↓
Phase 2 Completed (COLLAPSED):
[Phase 1: completed] [Phase 2: completed] [Phase 3: pending] [Phase 4: pending] [Phase 5: pending]
↓
Phase 3 Invoked (ATTACHED):
[Phase 1: completed] [Phase 2: completed] [Phase 3.1: in_progress] [Phase 3.2: pending] [Phase 3.3: pending] [Phase 4: pending] [Phase 5: pending]
↓
Phase 3 Completed (COLLAPSED):
[Phase 1: completed] [Phase 2: completed] [Phase 3: completed] [Phase 4: pending] [Phase 5: pending]
↓
[Continue pattern through Phase 4 and Phase 5...]
```
### Test-Gen Specific Features ### Test-Gen Specific Features

416
.claude/commands/workflow/ui-design/reference-page-generator.md
View File

@@ -10,12 +10,11 @@ auto-continue: true
## Overview ## Overview
Converts design run extraction results into shareable, versioned reference package with: Converts design run extraction results into shareable reference package with:
- Interactive multi-component preview (preview.html + preview.css) - Interactive multi-component preview (preview.html + preview.css)
- Component pattern extraction (component-patterns.json) - Component layout templates (layout-templates.json)
- Package metadata and documentation (metadata.json + README.md)
**Role**: Takes existing design run (from `import-from-code` or other extraction commands) and enhances it with component analysis, preview generation, and packaging. **Role**: Takes existing design run (from `import-from-code` or other extraction commands) and generates preview pages for easy reference.
## Usage ## Usage
@@ -75,12 +74,13 @@ fi
# 4. Check required extraction files exist # 4. Check required extraction files exist
required_files=( required_files=(
"$design_run/style-extraction/style-1/design-tokens.json" "$design_run/style-extraction/style-1/design-tokens.json"
"$design_run/layout-extraction/layout-templates.json"
) )
for file in "${required_files[@]}"; do for file in "${required_files[@]}"; do
if [ ! -f "$file" ]; then if [ ! -f "$file" ]; then
echo "ERROR: Required file not found: $file" echo "ERROR: Required file not found: $file"
echo "HINT: Ensure design run has style extraction results" echo "HINT: Ensure design run has style and layout extraction results"
exit 1 exit 1
fi fi
done done
@@ -118,180 +118,36 @@ echo " Output: $package_dir"
```json ```json
[ [
{"content": "Phase 0: 验证和准备", "status": "completed", "activeForm": "验证参数"}, {"content": "Phase 0: 验证和准备", "status": "completed", "activeForm": "验证参数"},
{"content": "Phase 1: 组件模式提取", "status": "in_progress", "activeForm": "提取组件模式"}, {"content": "Phase 1: 准备组件数据", "status": "in_progress", "activeForm": "复制布局模板"},
{"content": "Phase 2: 生成预览页面", "status": "pending", "activeForm": "生成预览"}, {"content": "Phase 2: 生成预览页面", "status": "pending", "activeForm": "生成预览"}
{"content": "Phase 3: 生成元数据和文档", "status": "pending", "activeForm": "生成文档"}
] ]
``` ```
--- ---
### Phase 1: Component Pattern Extraction ### Phase 1: Prepare Component Data
**Purpose**: Run Component Agent to extract UI component patterns from design run **Purpose**: Copy layout templates to package directory (used as component reference)
**Agent Task**: **Operations**:
```javascript ```bash
Task(ui-design-agent): ` echo "[Phase 1] Preparing component data from design run"
[COMPONENT_PATTERNS_EXTRACTION]
Extract reusable UI component patterns from design run extraction results
MODE: component-analysis | DESIGN_RUN: ${design_run} | OUTPUT: ${package_dir} # Copy layout templates as component patterns
cp "${design_run}/layout-extraction/layout-templates.json" "${package_dir}/layout-templates.json"
## Input Files # Verify copy
if [ ! -f "${package_dir}/layout-templates.json" ]; then
echo "ERROR: Failed to copy layout templates"
exit 1
fi
**Design Run Path**: ${design_run} # Count components from layout templates
component_count=$(jq -r '.layout_templates | length // 0' "${package_dir}/layout-templates.json" 2>/dev/null || echo 0)
You can read ALL files in the design run directory: echo " ✓ Layout templates copied (${component_count} components)"
- style-extraction/style-1/design-tokens.json echo "[Phase 1] Component data preparation complete"
- animation-extraction/animation-tokens.json (if exists)
- layout-extraction/layout-templates.json (if exists)
- Source code files referenced in extraction metadata
## Extraction Strategy
**Component Identification**:
1. Scan design tokens for component-level styles (component_styles in design-tokens.json)
2. Review layout templates for component structures
3. Identify common UI component patterns (button, input, card, modal, badge, alert, etc.)
4. Extract DOM structure for each component
5. Identify CSS class patterns and variants
6. Map component states (default, hover, active, disabled, focus, error, success)
## Output Requirements
Generate 1 file: ${package_dir}/component-patterns.json
### component-patterns.json Structure:
{
"extraction_metadata": {
"package_name": "${package_name}",
"source_design_run": "${design_run}",
"extraction_time": "ISO8601 timestamp",
"files_analyzed": {
"design_tokens": "path/to/design-tokens.json",
"animation_tokens": "path/to/animation-tokens.json (if exists)",
"layout_templates": "path/to/layout-templates.json (if exists)"
},
"component_count": 8
},
"components": {
"button": {
"base_structure": {
"tag": "button",
"base_classes": ["btn"],
"attributes": {
"type": "button",
"role": "button"
}
},
"variants": {
"primary": {
"classes": ["btn-primary"],
"description": "Main call-to-action button",
"style_tokens": {
"background": "var(--color-brand-primary)",
"color": "var(--color-text-inverse)",
"padding": "var(--spacing-3) var(--spacing-6)",
"border_radius": "var(--border-radius-md)"
}
},
"secondary": {
"classes": ["btn-secondary"],
"description": "Secondary action button",
"style_tokens": {
"background": "var(--color-surface-elevated)",
"color": "var(--color-text-primary)",
"border": "1px solid var(--color-border-default)"
}
}
},
"sizes": {
"sm": {"classes": ["btn-sm"]},
"base": {"classes": []},
"lg": {"classes": ["btn-lg"]}
},
"states": {
"default": {"classes": []},
"hover": {"pseudo": ":hover"},
"active": {"pseudo": ":active"},
"disabled": {"attribute": "disabled", "classes": ["btn-disabled"]}
},
"usage_examples": [
"<button class=\"btn btn-primary\">Primary</button>",
"<button class=\"btn btn-secondary btn-lg\">Large Secondary</button>"
]
},
"input": {
"base_structure": {
"tag": "input",
"base_classes": ["input"],
"attributes": {"type": "text"}
},
"variants": {
"default": {
"classes": ["input-default"],
"description": "Standard text input",
"style_tokens": {
"border": "1px solid var(--color-border-default)",
"padding": "var(--spacing-3)",
"border_radius": "var(--border-radius-md)"
}
}
},
"states": {
"default": {"classes": []},
"focus": {"pseudo": ":focus"},
"error": {"classes": ["input-error"]},
"disabled": {"attribute": "disabled"}
},
"usage_examples": [
"<input class=\"input input-default\" type=\"text\" placeholder=\"Enter text\">"
]
},
"card": {
"base_structure": {
"tag": "div",
"base_classes": ["card"],
"children": [
{"tag": "div", "classes": ["card-header"], "optional": true},
{"tag": "div", "classes": ["card-body"]},
{"tag": "div", "classes": ["card-footer"], "optional": true}
]
},
"variants": {
"default": {
"classes": ["card-default"],
"description": "Standard elevated card",
"style_tokens": {
"background": "var(--color-surface-elevated)",
"padding": "var(--spacing-6)",
"border_radius": "var(--border-radius-lg)",
"box_shadow": "var(--shadow-md)"
}
}
},
"usage_examples": [
"<div class=\"card card-default\"><div class=\"card-body\">Content</div></div>"
]
}
}
}
## Completeness Criteria
- Extract at least 5 core component types (button, input, card, badge, alert, etc.)
- Include all variants and states for each component
- Provide usage examples for each component
- Map style tokens to component styles
## Critical Requirements
- ✅ Read design run extraction files using Read() tool
- ✅ Cross-reference design tokens with component styles
- ✅ Generate comprehensive component patterns catalog
- ✅ Use Write() to save: ${package_dir}/component-patterns.json
- ❌ NO external research or MCP calls
`
``` ```
<!-- TodoWrite: Mark Phase 1 complete, start Phase 2 --> <!-- TodoWrite: Mark Phase 1 complete, start Phase 2 -->
@@ -299,14 +155,14 @@ Task(ui-design-agent): `
**TodoWrite**: **TodoWrite**:
```json ```json
[ [
{"content": "Phase 1: 组件模式提取", "status": "completed", "activeForm": "提取组件模式"}, {"content": "Phase 1: 准备组件数据", "status": "completed", "activeForm": "复制布局模板"},
{"content": "Phase 2: 生成预览页面", "status": "in_progress", "activeForm": "生成预览"} {"content": "Phase 2: 生成预览页面", "status": "in_progress", "activeForm": "生成预览"}
] ]
``` ```
--- ---
### Phase 2: Preview Generation ### Phase 2: Preview Generation (Final Phase)
**Purpose**: Generate interactive multi-component preview (preview.html + preview.css) **Purpose**: Generate interactive multi-component preview (preview.html + preview.css)
@@ -321,7 +177,7 @@ Task(ui-design-agent): `
## Input Files (MUST READ ALL) ## Input Files (MUST READ ALL)
1. ${package_dir}/component-patterns.json (component patterns - REQUIRED) 1. ${package_dir}/layout-templates.json (component layout patterns - REQUIRED)
2. ${design_run}/style-extraction/style-1/design-tokens.json (design tokens - REQUIRED) 2. ${design_run}/style-extraction/style-1/design-tokens.json (design tokens - REQUIRED)
3. ${design_run}/animation-extraction/animation-tokens.json (optional, if exists) 3. ${design_run}/animation-extraction/animation-tokens.json (optional, if exists)
@@ -340,9 +196,9 @@ Task(ui-design-agent): `
- Include font family examples - Include font family examples
### Section 3: Components ### Section 3: Components
- Render all components from component-patterns.json - Render all components from layout-templates.json (use layout_templates field)
- Display all variants side-by-side - Display all variants side-by-side
- Show all states (default, hover, active, disabled, focus, error) - Show DOM structure with proper styling
- Include usage code snippets in <details> tags - Include usage code snippets in <details> tags
### Section 4: Spacing & Layout ### Section 4: Spacing & Layout
@@ -364,23 +220,23 @@ Task(ui-design-agent): `
- Complete standalone HTML file - Complete standalone HTML file
- Responsive design with mobile-first approach - Responsive design with mobile-first approach
- Sticky navigation for sections - Sticky navigation for sections
- Interactive state demonstrations - Interactive component demonstrations
- Code snippets in collapsible <details> elements - Code snippets in collapsible <details> elements
- Footer with package metadata - Footer with package metadata
### preview.css Structure: ### preview.css Structure:
- CSS Custom Properties from design-tokens.json - CSS Custom Properties from design-tokens.json
- Typography combination classes - Typography combination classes
- Component classes from component-patterns.json - Component classes from layout-templates.json
- Preview page layout styles - Preview page layout styles
- Interactive demo styles - Interactive demo styles
## Critical Requirements ## Critical Requirements
- ✅ Read ALL input files (component-patterns.json, design-tokens.json, animation-tokens.json if exists) - ✅ Read ALL input files (layout-templates.json, design-tokens.json, animation-tokens.json if exists)
- ✅ Generate complete, interactive showcase HTML - ✅ Generate complete, interactive showcase HTML
- ✅ All CSS uses var() references to design tokens - ✅ All CSS uses var() references to design tokens
- ✅ Display ALL components from component-patterns.json - ✅ Display ALL components from layout-templates.json
- ✅ Display ALL variants and states for each component - ✅ Display component DOM structures with proper styling
- ✅ Include usage code snippets - ✅ Include usage code snippets
- ✅ Use Write() to save both files: - ✅ Use Write() to save both files:
- ${package_dir}/preview.html - ${package_dir}/preview.html
@@ -389,175 +245,14 @@ Task(ui-design-agent): `
` `
``` ```
<!-- TodoWrite: Mark Phase 2 complete, start Phase 3 -->
**TodoWrite**:
```json
[
{"content": "Phase 2: 生成预览页面", "status": "completed", "activeForm": "生成预览"},
{"content": "Phase 3: 生成元数据和文档", "status": "in_progress", "activeForm": "生成文档"}
]
```
---
### Phase 3: Metadata & Documentation Generation
**Purpose**: Create package metadata and documentation
**Operations**:
```bash
echo "[Phase 3] Generating package metadata and documentation"
# 1. Copy design tokens to package directory
cp "${design_run}/style-extraction/style-1/design-tokens.json" "${package_dir}/design-tokens.json"
cp "${design_run}/style-extraction/style-1/style-guide.md" "${package_dir}/style-guide.md" 2>/dev/null || true
# 2. Copy animation tokens if exists
if [ -f "${design_run}/animation-extraction/animation-tokens.json" ]; then
cp "${design_run}/animation-extraction/animation-tokens.json" "${package_dir}/animation-tokens.json"
fi
# 3. Get Git information (if in git repo)
git_commit=""
git_repo=""
if git rev-parse --is-inside-work-tree > /dev/null 2>&1; then
git_commit=$(git rev-parse HEAD 2>/dev/null || echo "")
git_repo=$(git config --get remote.origin.url 2>/dev/null || echo "")
fi
# 4. Get source path from design run metadata
source_path=$(grep -Po '"extraction_source":\s*"\K[^"]+' "${design_run}/style-extraction/style-1/design-tokens.json" 2>/dev/null || echo "code_import")
# 5. Generate metadata.json
cat > "${package_dir}/metadata.json" <<EOF
{
"packageName": "${package_name}",
"version": "1.0.0",
"generatedAt": "$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date)",
"source": {
"type": "git",
"repository": "${git_repo}",
"commit": "${git_commit}",
"design_run": "${design_run}"
},
"description": "Style reference package extracted from design run",
"files": {
"design_tokens": "design-tokens.json",
"style_guide": "style-guide.md",
"component_patterns": "component-patterns.json",
"animation_tokens": "animation-tokens.json",
"preview_html": "preview.html",
"preview_css": "preview.css"
},
"usage": {
"command": "/workflow:ui-design:codify-style --package-name ${package_name}",
"skill_memory": "/memory:style-skill-memory ${package_name}",
"description": "Reference this package for consistent design system usage"
}
}
EOF
echo " ✓ metadata.json created"
# 6. Generate README.md
cat > "${package_dir}/README.md" <<'EOFREADME'
# ${package_name}
Style reference package with interactive component preview.
## Contents
- **design-tokens.json**: Complete design token system
- **style-guide.md**: Detailed style guide documentation
- **component-patterns.json**: Reusable component patterns
- **preview.html**: Interactive component showcase
- **preview.css**: Showcase styling
- **animation-tokens.json**: Animation tokens (if available)
- **metadata.json**: Package metadata
## Usage
### Preview Package
Open `preview.html` in a browser to view the interactive component showcase.
```bash
# Using local server
cd ${package_dir}
python -m http.server 8080
# Then open http://localhost:8080/preview.html
```
### Use in Workflow
Reference this package in UI design workflows or generate SKILL memory:
```bash
# Generate SKILL memory for easy loading
/memory:style-skill-memory ${package_name}
```
## Package Information
- **Generated**: $(date)
- **Source**: Design run extraction
- **Version**: 1.0.0
## Component Catalog
See `component-patterns.json` for complete component catalog with variants, states, and usage examples.
## Design Tokens
All design tokens are available as CSS custom properties. See `design-tokens.json` for complete token reference.
EOFREADME
echo " ✓ README.md created"
# 7. Verify all files exist
echo "[Phase 3] Verifying package files"
required_files=(
"design-tokens.json"
"component-patterns.json"
"preview.html"
"preview.css"
"metadata.json"
"README.md"
)
missing_files=()
for file in "${required_files[@]}"; do
if [ ! -f "${package_dir}/${file}" ]; then
missing_files+=("$file")
fi
done
if [ ${#missing_files[@]} -gt 0 ]; then
echo " ❌ ERROR: Missing required files: ${missing_files[*]}"
exit 1
fi
echo " ✓ All required files present"
# 8. Count component patterns (use jq for reliable parsing)
component_count=$(jq -r '.extraction_metadata.component_count // 0' "${package_dir}/component-patterns.json" 2>/dev/null || grep -c '"button"\|"input"\|"card"\|"badge"\|"alert"' "${package_dir}/component-patterns.json" 2>/dev/null || echo 0)
echo " ✓ Package complete with ${component_count} components"
```
<!-- TodoWrite: Mark all complete --> <!-- TodoWrite: Mark all complete -->
**TodoWrite**: **TodoWrite**:
```json ```json
[ [
{"content": "Phase 0: 验证和准备", "status": "completed", "activeForm": "验证参数"}, {"content": "Phase 0: 验证和准备", "status": "completed", "activeForm": "验证参数"},
{"content": "Phase 1: 组件模式提取", "status": "completed", "activeForm": "提取组件模式"}, {"content": "Phase 1: 准备组件数据", "status": "completed", "activeForm": "复制布局模板"},
{"content": "Phase 2: 生成预览页面", "status": "completed", "activeForm": "生成预览"}, {"content": "Phase 2: 生成预览页面", "status": "completed", "activeForm": "生成预览"}
{"content": "Phase 3: 生成元数据和文档", "status": "completed", "activeForm": "生成文档"}
] ]
``` ```
@@ -568,47 +263,26 @@ echo " ✓ Package complete with ${component_count} components"
``` ```
${output_dir}/ ${output_dir}/
└── ${package_name}/ └── ${package_name}/
├── design-tokens.json # Design token system (copied from design run) ├── layout-templates.json # Layout templates (copied from design run)
├── style-guide.md # Style guide (copied from design run) ├── preview.html # Interactive showcase (NEW)
├── component-patterns.json # Component patterns (NEW) └── preview.css # Showcase styling (NEW)
├── animation-tokens.json # Animation tokens (optional, copied from design run)
├── preview.html # Interactive showcase (NEW)
├── preview.css # Showcase styling (NEW)
├── metadata.json # Package metadata (NEW)
└── README.md # Package documentation (NEW)
``` ```
## Completion Message ## Completion Message
``` ```
✅ Reference package generated successfully! ✅ Preview package generated!
Package: {package_name} Package: {package_name}
Location: {package_dir} Location: {package_dir}
Generated Files: Files:
✓ design-tokens.json Design token system ✓ layout-templates.json {component_count} components
✓ style-guide.md Style guide documentation ✓ preview.html Interactive showcase
✓ component-patterns.json Component catalog ({component_count} components)
✓ preview.html Interactive multi-component showcase
✓ preview.css Showcase styling ✓ preview.css Showcase styling
✓ animation-tokens.json Animation tokens {if exists: "✓" else: "○ (not found)"}
✓ metadata.json Package metadata
✓ README.md Package documentation
Preview Package: Open preview:
Open the interactive showcase:
file://{absolute_path_to_package_dir}/preview.html file://{absolute_path_to_package_dir}/preview.html
Or use a local server:
cd {package_dir}
python -m http.server 8080
# Then open http://localhost:8080/preview.html
Next Steps:
1. Review preview.html to verify components
2. Generate SKILL memory: /memory:style-skill-memory {package_name}
3. Use package as design reference in future workflows
``` ```
## Error Handling ## Error Handling
@@ -620,8 +294,8 @@ Next Steps:
| Missing --design-run or --package-name | Required parameters not provided | Provide both flags | | Missing --design-run or --package-name | Required parameters not provided | Provide both flags |
| Invalid package name | Contains uppercase, special chars | Use lowercase, alphanumeric, hyphens only | | Invalid package name | Contains uppercase, special chars | Use lowercase, alphanumeric, hyphens only |
| Design run not found | Incorrect path or design run doesn't exist | Verify design run path, run import-from-code first | | Design run not found | Incorrect path or design run doesn't exist | Verify design run path, run import-from-code first |
| Missing extraction files | Design run incomplete | Ensure design run has style-extraction results | | Missing extraction files | Design run incomplete | Ensure design run has style-extraction and layout-extraction results |
| Component extraction failed | No components found | Review design tokens for component_styles | | Layout templates copy failed | layout-templates.json not found | Run import-from-code with Layout Agent first |
| Preview generation failed | Invalid design tokens | Check design-tokens.json format | | Preview generation failed | Invalid design tokens | Check design-tokens.json format |
--- ---