mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-05 01:50:27 +08:00
Refactor command YAML headers: replace examples with argument-hint
**Summary:** Updated all 62 command files in `.claude/commands` directory to improve parameter documentation clarity by replacing `examples` field with descriptive `argument-hint` field. **Changes:** - Added/improved `argument-hint` for all commands based on usage patterns - Removed `examples` field and all example items from YAML headers - Maintained all other YAML fields (name, description, usage, allowed-tools) - Deleted obsolete commands: workflow/issue/*, workflow/session/pause.md, workflow/session/switch.md - Cleaned up temporary analysis files **Rationale:** The `argument-hint` field provides clearer, more concise parameter documentation than example lists, improving command discoverability and usability in the Claude Code interface. **Files Modified:** 62 command files **Lines Changed:** -1570 insertions, +192 deletions 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
@@ -3,10 +3,6 @@ name: analyze
|
||||
description: Quick codebase analysis using CLI tools (codex/gemini/qwen)
|
||||
usage: /cli:analyze [--tool <codex|gemini|qwen>] [--enhance] <analysis-target>
|
||||
argument-hint: "[--tool codex|gemini|qwen] [--enhance] analysis target"
|
||||
examples:
|
||||
- /cli:analyze "authentication patterns"
|
||||
- /cli:analyze --tool qwen "API security"
|
||||
- /cli:analyze --tool codex --enhance "performance bottlenecks"
|
||||
allowed-tools: SlashCommand(*), Bash(*), TodoWrite(*), Read(*), Glob(*)
|
||||
---
|
||||
|
||||
|
||||
@@ -3,10 +3,6 @@ name: chat
|
||||
description: Simple CLI interaction command for direct codebase analysis
|
||||
usage: /cli:chat [--tool <codex|gemini|qwen>] [--enhance] "inquiry"
|
||||
argument-hint: "[--tool codex|gemini|qwen] [--enhance] inquiry"
|
||||
examples:
|
||||
- /cli:chat "analyze the authentication flow"
|
||||
- /cli:chat --tool qwen --enhance "optimize React component"
|
||||
- /cli:chat --tool codex "review security vulnerabilities"
|
||||
allowed-tools: SlashCommand(*), Bash(*)
|
||||
---
|
||||
|
||||
|
||||
@@ -3,11 +3,6 @@ name: cli-init
|
||||
description: Initialize CLI tool configurations (Gemini and Qwen) based on workspace analysis
|
||||
usage: /cli:cli-init [--tool <gemini|qwen|all>] [--output=<path>] [--preview]
|
||||
argument-hint: "[--tool gemini|qwen|all] [--output path] [--preview]"
|
||||
examples:
|
||||
- /cli:cli-init
|
||||
- /cli:cli-init --tool qwen
|
||||
- /cli:cli-init --tool all --preview
|
||||
- /cli:cli-init --output=.config/
|
||||
allowed-tools: Bash(*), Read(*), Write(*), Glob(*)
|
||||
---
|
||||
|
||||
@@ -452,4 +447,4 @@ docker-compose.override.yml
|
||||
| **Gemini-only workflow** | `/cli:cli-init --tool gemini` | Creates .gemini/ and .geminiignore only |
|
||||
| **Qwen-only workflow** | `/cli:cli-init --tool qwen` | Creates .qwen/ and .qwenignore only |
|
||||
| **Preview before commit** | `/cli:cli-init --preview` | Shows what would be generated |
|
||||
| **Update configurations** | `/cli:cli-init` | Regenerates all files with backups |
|
||||
| **Update configurations** | `/cli:cli-init` | Regenerates all files with backups |
|
||||
|
||||
@@ -3,10 +3,6 @@ name: codex-execute
|
||||
description: Automated task decomposition and execution with Codex using resume mechanism
|
||||
usage: /cli:codex-execute [--verify-git] <task-description|task-id>
|
||||
argument-hint: "[--verify-git] task description or task-id"
|
||||
examples:
|
||||
- /cli:codex-execute "implement user authentication system"
|
||||
- /cli:codex-execute --verify-git "refactor API layer"
|
||||
- /cli:codex-execute IMPL-001
|
||||
allowed-tools: SlashCommand(*), Bash(*), TodoWrite(*), Read(*), Glob(*)
|
||||
---
|
||||
|
||||
|
||||
@@ -3,11 +3,6 @@ name: execute
|
||||
description: Auto-execution of implementation tasks with YOLO permissions and intelligent context inference
|
||||
usage: /cli:execute [--tool <codex|gemini|qwen>] [--enhance] <description|task-id>
|
||||
argument-hint: "[--tool codex|gemini|qwen] [--enhance] description or task-id"
|
||||
examples:
|
||||
- /cli:execute "implement user authentication system"
|
||||
- /cli:execute --tool qwen --enhance "optimize React component"
|
||||
- /cli:execute --tool codex IMPL-001
|
||||
- /cli:execute --enhance "fix API performance issues"
|
||||
allowed-tools: SlashCommand(*), Bash(*)
|
||||
---
|
||||
|
||||
|
||||
@@ -3,10 +3,6 @@ name: bug-index
|
||||
description: Bug analysis and fix suggestions using CLI tools
|
||||
usage: /cli:mode:bug-index [--tool <codex|gemini|qwen>] [--enhance] [--cd "path"] "bug description"
|
||||
argument-hint: "[--tool codex|gemini|qwen] [--enhance] [--cd path] bug description"
|
||||
examples:
|
||||
- /cli:mode:bug-index "authentication null pointer error"
|
||||
- /cli:mode:bug-index --tool qwen --enhance "login not working"
|
||||
- /cli:mode:bug-index --tool codex --cd "src/auth" "token validation fails"
|
||||
allowed-tools: SlashCommand(*), Bash(*)
|
||||
---
|
||||
|
||||
|
||||
@@ -3,10 +3,6 @@ name: code-analysis
|
||||
description: Deep code analysis and debugging using CLI tools with specialized template
|
||||
usage: /cli:mode:code-analysis [--tool <codex|gemini|qwen>] [--enhance] [--cd "path"] "analysis target"
|
||||
argument-hint: "[--tool codex|gemini|qwen] [--enhance] [--cd path] analysis target"
|
||||
examples:
|
||||
- /cli:mode:code-analysis "analyze authentication flow logic"
|
||||
- /cli:mode:code-analysis --tool qwen --enhance "explain data transformation pipeline"
|
||||
- /cli:mode:code-analysis --tool codex --cd "src/core" "trace execution path for user registration"
|
||||
allowed-tools: SlashCommand(*), Bash(*)
|
||||
---
|
||||
|
||||
|
||||
@@ -3,10 +3,6 @@ name: plan
|
||||
description: Project planning and architecture analysis using CLI tools
|
||||
usage: /cli:mode:plan [--tool <codex|gemini|qwen>] [--enhance] [--cd "path"] "topic"
|
||||
argument-hint: "[--tool codex|gemini|qwen] [--enhance] [--cd path] topic"
|
||||
examples:
|
||||
- /cli:mode:plan "design user dashboard"
|
||||
- /cli:mode:plan --tool qwen --enhance "plan microservices migration"
|
||||
- /cli:mode:plan --tool codex --cd "src/auth" "authentication system"
|
||||
allowed-tools: SlashCommand(*), Bash(*)
|
||||
---
|
||||
|
||||
|
||||
@@ -3,10 +3,6 @@ name: enhance-prompt
|
||||
description: Context-aware prompt enhancement using session memory and codebase analysis
|
||||
usage: /enhance-prompt <user_input>
|
||||
argument-hint: "user input to enhance"
|
||||
examples:
|
||||
- /enhance-prompt "add user profile editing"
|
||||
- /enhance-prompt "fix login button"
|
||||
- /enhance-prompt "clean up the payment code"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
@@ -2,11 +2,7 @@
|
||||
name: breakdown
|
||||
description: Intelligent task decomposition with context-aware subtask generation
|
||||
usage: /task:breakdown <task-id>
|
||||
argument-hint: task-id
|
||||
examples:
|
||||
- /task:breakdown IMPL-1
|
||||
- /task:breakdown IMPL-1.1
|
||||
- /task:breakdown impl-3
|
||||
argument-hint: "task-id"
|
||||
---
|
||||
|
||||
# Task Breakdown Command (/task:breakdown)
|
||||
|
||||
@@ -2,11 +2,7 @@
|
||||
name: create
|
||||
description: Create implementation tasks with automatic context awareness
|
||||
usage: /task:create "title"
|
||||
argument-hint: "task title"
|
||||
examples:
|
||||
- /task:create "Implement user authentication"
|
||||
- /task:create "Build REST API endpoints"
|
||||
- /task:create "Fix login validation bug"
|
||||
argument-hint: "\"task title\""
|
||||
---
|
||||
|
||||
# Task Create Command (/task:create)
|
||||
|
||||
@@ -2,11 +2,7 @@
|
||||
name: execute
|
||||
description: Execute tasks with appropriate agents and context-aware orchestration
|
||||
usage: /task:execute <task-id>
|
||||
argument-hint: task-id
|
||||
examples:
|
||||
- /task:execute IMPL-1
|
||||
- /task:execute IMPL-1.2
|
||||
- /task:execute IMPL-3
|
||||
argument-hint: "task-id"
|
||||
---
|
||||
|
||||
### 🚀 **Command Overview: `/task:execute`**
|
||||
|
||||
@@ -2,11 +2,7 @@
|
||||
name: replan
|
||||
description: Replan individual tasks with detailed user input and change tracking
|
||||
usage: /task:replan <task-id> [input]
|
||||
argument-hint: task-id ["text"|file.md|ISS-001]
|
||||
examples:
|
||||
- /task:replan IMPL-1 "Add OAuth2 authentication support"
|
||||
- /task:replan IMPL-1 updated-specs.md
|
||||
- /task:replan IMPL-1 ISS-001
|
||||
argument-hint: "task-id [\"text\"|file.md]"
|
||||
---
|
||||
|
||||
# Task Replan Command (/task:replan)
|
||||
@@ -38,12 +34,6 @@ Replans individual tasks with multiple input options, change tracking, and versi
|
||||
```
|
||||
Supports: .md, .txt, .json, .yaml
|
||||
|
||||
### Issue Reference
|
||||
```bash
|
||||
/task:replan IMPL-1 ISS-001
|
||||
```
|
||||
Loads issue description and requirements
|
||||
|
||||
### Interactive Mode
|
||||
```bash
|
||||
/task:replan IMPL-1 --interactive
|
||||
|
||||
@@ -3,10 +3,6 @@ name: update-memory-full
|
||||
description: Complete project-wide CLAUDE.md documentation update
|
||||
usage: /update-memory-full [--tool <gemini|qwen|codex>]
|
||||
argument-hint: "[--tool gemini|qwen|codex]"
|
||||
examples:
|
||||
- /update-memory-full # Full project documentation update (gemini default)
|
||||
- /update-memory-full --tool qwen # Use Qwen for architecture analysis
|
||||
- /update-memory-full --tool codex # Use Codex for implementation validation
|
||||
---
|
||||
|
||||
### 🚀 Command Overview: `/update-memory-full`
|
||||
|
||||
@@ -3,10 +3,6 @@ name: update-memory-related
|
||||
description: Context-aware CLAUDE.md documentation updates based on recent changes
|
||||
usage: /update-memory-related [--tool <gemini|qwen|codex>]
|
||||
argument-hint: "[--tool gemini|qwen|codex]"
|
||||
examples:
|
||||
- /update-memory-related # Update documentation based on recent changes (gemini default)
|
||||
- /update-memory-related --tool qwen # Use Qwen for architecture analysis
|
||||
- /update-memory-related --tool codex # Use Codex for implementation validation
|
||||
---
|
||||
|
||||
### 🚀 Command Overview: `/update-memory-related`
|
||||
|
||||
@@ -2,8 +2,6 @@
|
||||
name: version
|
||||
description: Display version information and check for updates
|
||||
usage: /version
|
||||
examples:
|
||||
- /version
|
||||
allowed-tools: Bash(*)
|
||||
---
|
||||
|
||||
|
||||
@@ -2,10 +2,7 @@
|
||||
name: action-plan-verify
|
||||
description: Perform non-destructive cross-artifact consistency and quality analysis of IMPL_PLAN.md and task.json before execution
|
||||
usage: /workflow:action-plan-verify [--session <session-id>]
|
||||
argument-hint: "optional: --session <session-id>"
|
||||
examples:
|
||||
- /workflow:action-plan-verify
|
||||
- /workflow:action-plan-verify --session WFS-auth
|
||||
argument-hint: "[optional: --session session-id]"
|
||||
allowed-tools: Read(*), TodoWrite(*), Glob(*), Bash(*)
|
||||
---
|
||||
|
||||
|
||||
@@ -3,10 +3,6 @@ name: artifacts
|
||||
description: Generate role-specific topic-framework.md dynamically based on selected roles
|
||||
usage: /workflow:brainstorm:artifacts "<topic>" [--roles "role1,role2,role3"]
|
||||
argument-hint: "topic or challenge description for framework generation"
|
||||
examples:
|
||||
- /workflow:brainstorm:artifacts "Build real-time collaboration feature"
|
||||
- /workflow:brainstorm:artifacts "Optimize database performance" --roles "system-architect,data-architect,subject-matter-expert"
|
||||
- /workflow:brainstorm:artifacts "Implement secure authentication system" --roles "ui-designer,ux-expert,subject-matter-expert"
|
||||
allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*)
|
||||
---
|
||||
|
||||
@@ -368,4 +364,4 @@ ELSE:
|
||||
### Integration Points
|
||||
- **Compatible with**: Other brainstorming commands in the same session
|
||||
- **Builds foundation for**: More detailed planning and implementation phases
|
||||
- **Outputs used by**: `/workflow:brainstorm:synthesis` command for cross-analysis integration
|
||||
- **Outputs used by**: `/workflow:brainstorm:synthesis` command for cross-analysis integration
|
||||
|
||||
@@ -3,10 +3,6 @@ name: auto-parallel
|
||||
description: Parallel brainstorming automation with dynamic role selection and concurrent execution
|
||||
usage: /workflow:brainstorm:auto-parallel "<topic>"
|
||||
argument-hint: "topic or challenge description"
|
||||
examples:
|
||||
- /workflow:brainstorm:auto-parallel "Build real-time collaboration feature"
|
||||
- /workflow:brainstorm:auto-parallel "Optimize database performance for millions of users"
|
||||
- /workflow:brainstorm:auto-parallel "Implement secure authentication system"
|
||||
allowed-tools: SlashCommand(*), Task(*), TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*)
|
||||
---
|
||||
|
||||
@@ -327,4 +323,4 @@ Command coordination model: artifacts command → parallel role analysis → syn
|
||||
- **Agent self-management**: Agents handle their own workflow and validation
|
||||
- **Concurrent operation**: No inter-agent dependencies enabling parallel execution
|
||||
- **Reference-based synthesis**: Post-processing integration without content duplication
|
||||
- **TodoWrite orchestration**: Progress tracking and workflow control throughout entire process
|
||||
- **TodoWrite orchestration**: Progress tracking and workflow control throughout entire process
|
||||
|
||||
@@ -3,10 +3,6 @@ name: auto-squeeze
|
||||
description: Orchestrate 3-phase brainstorming workflow by executing commands sequentially
|
||||
usage: /workflow:brainstorm:auto-squeeze "<topic>"
|
||||
argument-hint: "topic or challenge description for coordinated brainstorming"
|
||||
examples:
|
||||
- /workflow:brainstorm:auto-squeeze "Build real-time collaboration feature"
|
||||
- /workflow:brainstorm:auto-squeeze "Optimize database performance for millions of users"
|
||||
- /workflow:brainstorm:auto-squeeze "Implement secure authentication system"
|
||||
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*)
|
||||
---
|
||||
|
||||
@@ -255,4 +251,4 @@ Return summary to user
|
||||
✅ Update TodoWrite after each role completion
|
||||
✅ Execute Phase 3 (synthesis) after all roles complete
|
||||
✅ Validate synthesis-report.md exists
|
||||
✅ Return summary with all generated files
|
||||
✅ Return summary with all generated files
|
||||
|
||||
@@ -3,10 +3,6 @@ name: data-architect
|
||||
description: Generate or update data-architect/analysis.md addressing topic-framework discussion points
|
||||
usage: /workflow:brainstorm:data-architect [topic]
|
||||
argument-hint: "optional topic - uses existing framework if available"
|
||||
examples:
|
||||
- /workflow:brainstorm:data-architect
|
||||
- /workflow:brainstorm:data-architect "user analytics data pipeline"
|
||||
- /workflow:brainstorm:data-architect "real-time data processing system"
|
||||
allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
|
||||
---
|
||||
|
||||
@@ -202,4 +198,4 @@ TodoWrite({
|
||||
### Integration Points
|
||||
- **Framework Reference**: @../topic-framework.md for structured discussion points
|
||||
- **Cross-Role Synthesis**: Data architecture insights available for synthesis-report.md integration
|
||||
- **Agent Autonomy**: Independent execution with framework guidance
|
||||
- **Agent Autonomy**: Independent execution with framework guidance
|
||||
|
||||
@@ -3,10 +3,6 @@ name: product-manager
|
||||
description: Generate or update product-manager/analysis.md addressing topic-framework discussion points
|
||||
usage: /workflow:brainstorm:product-manager [topic]
|
||||
argument-hint: "optional topic - uses existing framework if available"
|
||||
examples:
|
||||
- /workflow:brainstorm:product-manager
|
||||
- /workflow:brainstorm:product-manager "user authentication redesign"
|
||||
- /workflow:brainstorm:product-manager "mobile app performance optimization"
|
||||
allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
|
||||
---
|
||||
|
||||
|
||||
@@ -3,10 +3,6 @@ name: product-owner
|
||||
description: Generate or update product-owner/analysis.md addressing topic-framework discussion points
|
||||
usage: /workflow:brainstorm:product-owner [topic]
|
||||
argument-hint: "optional topic - uses existing framework if available"
|
||||
examples:
|
||||
- /workflow:brainstorm:product-owner
|
||||
- /workflow:brainstorm:product-owner "user authentication redesign"
|
||||
- /workflow:brainstorm:product-owner "mobile app performance optimization"
|
||||
allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
|
||||
---
|
||||
|
||||
|
||||
@@ -3,10 +3,6 @@ name: scrum-master
|
||||
description: Generate or update scrum-master/analysis.md addressing topic-framework discussion points
|
||||
usage: /workflow:brainstorm:scrum-master [topic]
|
||||
argument-hint: "optional topic - uses existing framework if available"
|
||||
examples:
|
||||
- /workflow:brainstorm:scrum-master
|
||||
- /workflow:brainstorm:scrum-master "user authentication redesign"
|
||||
- /workflow:brainstorm:scrum-master "mobile app performance optimization"
|
||||
allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
|
||||
---
|
||||
|
||||
|
||||
@@ -3,10 +3,6 @@ name: subject-matter-expert
|
||||
description: Generate or update subject-matter-expert/analysis.md addressing topic-framework discussion points
|
||||
usage: /workflow:brainstorm:subject-matter-expert [topic]
|
||||
argument-hint: "optional topic - uses existing framework if available"
|
||||
examples:
|
||||
- /workflow:brainstorm:subject-matter-expert
|
||||
- /workflow:brainstorm:subject-matter-expert "user authentication redesign"
|
||||
- /workflow:brainstorm:subject-matter-expert "mobile app performance optimization"
|
||||
allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
|
||||
---
|
||||
|
||||
|
||||
@@ -3,8 +3,6 @@ name: synthesis
|
||||
description: Generate synthesis-specification.md from topic-framework and role analyses with @ references
|
||||
usage: /workflow:brainstorm:synthesis
|
||||
argument-hint: "no arguments required - synthesizes existing framework and role analyses"
|
||||
examples:
|
||||
- /workflow:brainstorm:synthesis
|
||||
allowed-tools: Read(*), Write(*), TodoWrite(*), Glob(*)
|
||||
---
|
||||
|
||||
@@ -497,4 +495,4 @@ If you want to skip verification and proceed directly:
|
||||
/workflow:execute --session WFS-{session-id}
|
||||
```
|
||||
|
||||
⚠️ **Warning**: Skipping verification increases risk of late-stage issues and rework.
|
||||
⚠️ **Warning**: Skipping verification increases risk of late-stage issues and rework.
|
||||
|
||||
@@ -3,9 +3,6 @@ name: system-architect
|
||||
description: Generate or update system-architect/analysis.md addressing topic-framework discussion points
|
||||
usage: /workflow:brainstorm:system-architect [topic]
|
||||
argument-hint: "optional topic - uses existing framework if available"
|
||||
examples:
|
||||
- /workflow:brainstorm:system-architect
|
||||
- /workflow:brainstorm:system-architect "user authentication redesign"
|
||||
allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
|
||||
---
|
||||
|
||||
@@ -369,4 +366,4 @@ System architect perspective provides:
|
||||
- [ ] **Resource Planning**: Resource requirements clearly defined and realistic
|
||||
- [ ] **Risk Management**: Technical risks identified with mitigation plans
|
||||
- [ ] **Performance Validation**: Architecture can meet performance requirements
|
||||
- [ ] **Evolution Strategy**: Design allows for future growth and changes
|
||||
- [ ] **Evolution Strategy**: Design allows for future growth and changes
|
||||
|
||||
@@ -3,10 +3,6 @@ name: ui-designer
|
||||
description: Generate or update ui-designer/analysis.md addressing topic-framework discussion points
|
||||
usage: /workflow:brainstorm:ui-designer [topic]
|
||||
argument-hint: "optional topic - uses existing framework if available"
|
||||
examples:
|
||||
- /workflow:brainstorm:ui-designer
|
||||
- /workflow:brainstorm:ui-designer "user authentication redesign"
|
||||
- /workflow:brainstorm:ui-designer "mobile app navigation improvement"
|
||||
allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
|
||||
---
|
||||
|
||||
@@ -202,4 +198,4 @@ TodoWrite({
|
||||
### Integration Points
|
||||
- **Framework Reference**: @../topic-framework.md for structured discussion points
|
||||
- **Cross-Role Synthesis**: UI/UX insights available for synthesis-report.md integration
|
||||
- **Agent Autonomy**: Independent execution with framework guidance
|
||||
- **Agent Autonomy**: Independent execution with framework guidance
|
||||
|
||||
@@ -3,10 +3,6 @@ name: ux-expert
|
||||
description: Generate or update ux-expert/analysis.md addressing topic-framework discussion points
|
||||
usage: /workflow:brainstorm:ux-expert [topic]
|
||||
argument-hint: "optional topic - uses existing framework if available"
|
||||
examples:
|
||||
- /workflow:brainstorm:ux-expert
|
||||
- /workflow:brainstorm:ux-expert "user authentication redesign"
|
||||
- /workflow:brainstorm:ux-expert "mobile app performance optimization"
|
||||
allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
|
||||
---
|
||||
|
||||
|
||||
@@ -2,10 +2,7 @@
|
||||
name: concept-clarify
|
||||
description: Identify underspecified areas in brainstorming artifacts through targeted clarification questions before action planning
|
||||
usage: /workflow:concept-clarify [--session <session-id>]
|
||||
argument-hint: "optional: --session <session-id>"
|
||||
examples:
|
||||
- /workflow:concept-clarify
|
||||
- /workflow:concept-clarify --session WFS-auth
|
||||
argument-hint: "[optional: --session session-id]"
|
||||
allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
|
||||
---
|
||||
|
||||
|
||||
@@ -2,10 +2,7 @@
|
||||
name: execute
|
||||
description: Coordinate agents for existing workflow tasks with automatic discovery
|
||||
usage: /workflow:execute [--resume-session="session-id"]
|
||||
argument-hint: [--resume-session="session-id"]
|
||||
examples:
|
||||
- /workflow:execute
|
||||
- /workflow:execute --resume-session="WFS-user-auth"
|
||||
argument-hint: "[--resume-session=\"session-id\"]"
|
||||
---
|
||||
|
||||
# Workflow Execute Command
|
||||
|
||||
@@ -1,142 +0,0 @@
|
||||
---
|
||||
name: close
|
||||
description: Close a completed or obsolete workflow issue
|
||||
usage: /workflow:issue:close <issue-id> [reason]
|
||||
|
||||
examples:
|
||||
- /workflow:issue:close ISS-001
|
||||
- /workflow:issue:close ISS-001 "Feature implemented in PR #42"
|
||||
- /workflow:issue:close ISS-002 "Duplicate of ISS-001"
|
||||
---
|
||||
|
||||
# Close Workflow Issue (/workflow:issue:close)
|
||||
|
||||
## Purpose
|
||||
Mark an issue as closed/resolved with optional reason documentation.
|
||||
|
||||
## Usage
|
||||
```bash
|
||||
/workflow:issue:close <issue-id> ["reason"]
|
||||
```
|
||||
|
||||
## Closing Process
|
||||
|
||||
### Quick Close
|
||||
Simple closure without reason:
|
||||
```bash
|
||||
/workflow:issue:close ISS-001
|
||||
```
|
||||
|
||||
### Close with Reason
|
||||
Include closure reason:
|
||||
```bash
|
||||
/workflow:issue:close ISS-001 "Feature implemented in PR #42"
|
||||
/workflow/issue/close ISS-002 "Duplicate of ISS-001"
|
||||
/workflow/issue/close ISS-003 "No longer relevant"
|
||||
```
|
||||
|
||||
### Interactive Close (Default)
|
||||
Without reason, prompts for details:
|
||||
```
|
||||
Closing Issue ISS-001: Add OAuth2 social login support
|
||||
Current Status: Open | Priority: High | Type: Feature
|
||||
|
||||
Why is this issue being closed?
|
||||
1. ✅ Completed - Issue resolved successfully
|
||||
2. 🔄 Duplicate - Duplicate of another issue
|
||||
3. ❌ Invalid - Issue is invalid or not applicable
|
||||
4. 🚫 Won't Fix - Decided not to implement
|
||||
5. 📝 Custom reason
|
||||
|
||||
Choice: _
|
||||
```
|
||||
|
||||
## Closure Categories
|
||||
|
||||
### Completed (Default)
|
||||
- Issue was successfully resolved
|
||||
- Implementation finished
|
||||
- Requirements met
|
||||
- Ready for review/testing
|
||||
|
||||
### Duplicate
|
||||
- Same as existing issue
|
||||
- Consolidated into another issue
|
||||
- Reference to primary issue provided
|
||||
|
||||
### Invalid
|
||||
- Issue description unclear
|
||||
- Not a valid problem/request
|
||||
- Outside project scope
|
||||
- Misunderstanding resolved
|
||||
|
||||
### Won't Fix
|
||||
- Decided not to implement
|
||||
- Business decision to decline
|
||||
- Technical constraints prevent
|
||||
- Priority too low
|
||||
|
||||
### Custom Reason
|
||||
- Specific project context
|
||||
- Detailed explanation needed
|
||||
- Complex closure scenario
|
||||
|
||||
## Closure Effects
|
||||
|
||||
### Status Update
|
||||
- Changes status from "open" to "closed"
|
||||
- Records closure details
|
||||
- Saves closure reason and category
|
||||
|
||||
### Integration Cleanup
|
||||
- Unlinks from workflow tasks (if integrated)
|
||||
- Removes from active TodoWrite items
|
||||
- Updates session statistics
|
||||
|
||||
### History Preservation
|
||||
- Maintains full issue history
|
||||
- Records closure details
|
||||
- Preserves for future reference
|
||||
|
||||
## Session Updates
|
||||
|
||||
### Statistics
|
||||
Updates session issue counts:
|
||||
- Decrements open issues
|
||||
- Increments closed issues
|
||||
- Updates completion metrics
|
||||
|
||||
### Progress Tracking
|
||||
- Updates workflow progress
|
||||
- Refreshes TodoWrite status
|
||||
- Updates session health metrics
|
||||
|
||||
## Output
|
||||
Displays:
|
||||
- Issue closure confirmation
|
||||
- Closure reason and category
|
||||
- Updated session statistics
|
||||
- Related actions taken
|
||||
|
||||
## Reopening
|
||||
Closed issues can be reopened:
|
||||
```bash
|
||||
/workflow/issue/update ISS-001 --status=open
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
- **Issue not found**: Lists available open issues
|
||||
- **Already closed**: Shows current status and closure info
|
||||
- **Integration conflicts**: Handles task unlinking gracefully
|
||||
- **File errors**: Validates and repairs issue files
|
||||
|
||||
## Archive Management
|
||||
Closed issues:
|
||||
- Remain in .issues/ directory
|
||||
- Are excluded from default listings
|
||||
- Can be viewed with `/workflow/issue/list --closed`
|
||||
- Maintain full searchability
|
||||
|
||||
---
|
||||
|
||||
**Result**: Issue properly closed with documented reason and session cleanup
|
||||
@@ -1,106 +0,0 @@
|
||||
---
|
||||
name: create
|
||||
description: Create a new issue or change request
|
||||
usage: /workflow:issue:create "issue description"
|
||||
|
||||
examples:
|
||||
- /workflow:issue:create "Add OAuth2 social login support"
|
||||
- /workflow:issue:create "Fix user avatar security vulnerability"
|
||||
---
|
||||
|
||||
# Create Workflow Issue (/workflow:issue:create)
|
||||
|
||||
## Purpose
|
||||
Create a new issue or change request within the current workflow session.
|
||||
|
||||
## Usage
|
||||
```bash
|
||||
/workflow:issue:create "issue description"
|
||||
```
|
||||
|
||||
## Automatic Behavior
|
||||
|
||||
### Issue ID Generation
|
||||
- Generates unique ID: ISS-001, ISS-002, etc.
|
||||
- Sequential numbering within session
|
||||
- Stored in session's .issues/ directory
|
||||
|
||||
### Type Detection
|
||||
Automatically detects issue type from description:
|
||||
- **Bug**: Contains words like "fix", "error", "bug", "broken"
|
||||
- **Feature**: Contains words like "add", "implement", "create", "new"
|
||||
- **Optimization**: Contains words like "improve", "optimize", "performance"
|
||||
- **Documentation**: Contains words like "document", "readme", "docs"
|
||||
- **Refactor**: Contains words like "refactor", "cleanup", "restructure"
|
||||
|
||||
### Priority Assessment
|
||||
Auto-assigns priority based on keywords:
|
||||
- **Critical**: "critical", "urgent", "blocker", "security"
|
||||
- **High**: "important", "major", "significant"
|
||||
- **Medium**: Default for most issues
|
||||
- **Low**: "minor", "enhancement", "nice-to-have"
|
||||
|
||||
## Issue Storage
|
||||
|
||||
### File Structure
|
||||
```
|
||||
.workflow/WFS-[session]/.issues/
|
||||
├── ISS-001.json # Issue metadata
|
||||
├── ISS-002.json # Another issue
|
||||
└── issue-registry.json # Issue index
|
||||
```
|
||||
|
||||
### Issue Metadata
|
||||
Each issue stores:
|
||||
```json
|
||||
{
|
||||
"id": "ISS-001",
|
||||
"title": "Add OAuth2 social login support",
|
||||
"type": "feature",
|
||||
"priority": "high",
|
||||
"status": "open",
|
||||
"created_at": "2025-09-08T10:00:00Z",
|
||||
"category": "authentication",
|
||||
"estimated_impact": "medium",
|
||||
"blocking": false,
|
||||
"session_id": "WFS-oauth-integration"
|
||||
}
|
||||
```
|
||||
|
||||
## Session Integration
|
||||
|
||||
### Active Session Check
|
||||
- Uses current active session (marker file)
|
||||
- Creates .issues/ directory if needed
|
||||
- Updates session's issue tracking
|
||||
|
||||
### TodoWrite Integration
|
||||
Optionally adds to task list:
|
||||
- Creates todo for issue investigation
|
||||
- Links issue to implementation tasks
|
||||
- Updates progress tracking
|
||||
|
||||
## Output
|
||||
Displays:
|
||||
- Generated issue ID
|
||||
- Detected type and priority
|
||||
- Storage location
|
||||
- Integration status
|
||||
- Quick actions available
|
||||
|
||||
## Quick Actions
|
||||
After creation:
|
||||
- **View**: `/workflow:issue:list`
|
||||
- **Update**: `/workflow:issue:update ISS-001`
|
||||
- **Integrate**: Link to workflow tasks
|
||||
- **Close**: `/workflow:issue:close ISS-001`
|
||||
|
||||
## Error Handling
|
||||
- **No active session**: Prompts to start session first
|
||||
- **Directory creation**: Handles permission issues
|
||||
- **Duplicate description**: Warns about similar issues
|
||||
- **Invalid description**: Prompts for meaningful description
|
||||
|
||||
---
|
||||
|
||||
**Result**: New issue created and ready for management within workflow
|
||||
@@ -1,104 +0,0 @@
|
||||
---
|
||||
name: list
|
||||
description: List and filter workflow issues
|
||||
usage: /workflow:issue:list
|
||||
examples:
|
||||
- /workflow:issue:list
|
||||
- /workflow:issue:list --open
|
||||
- /workflow:issue:list --priority=high
|
||||
---
|
||||
|
||||
# List Workflow Issues (/workflow:issue:list)
|
||||
|
||||
## Purpose
|
||||
Display all issues and change requests within the current workflow session.
|
||||
|
||||
## Usage
|
||||
```bash
|
||||
/workflow:issue:list [filter]
|
||||
```
|
||||
|
||||
## Optional Filters
|
||||
Simple keyword-based filtering:
|
||||
```bash
|
||||
/workflow:issue:list --open # Only open issues
|
||||
/workflow:issue:list --closed # Only closed issues
|
||||
/workflow:issue:list --critical # Critical priority
|
||||
/workflow:issue:list --high # High priority
|
||||
/workflow:issue:list --bug # Bug type issues
|
||||
/workflow:issue:list --feature # Feature type issues
|
||||
/workflow:issue:list --blocking # Blocking issues only
|
||||
```
|
||||
|
||||
## Display Format
|
||||
|
||||
### Open Issues
|
||||
```
|
||||
🔴 ISS-001: Add OAuth2 social login support
|
||||
Type: Feature | Priority: High | Created: 2025-09-07
|
||||
Status: Open | Impact: Medium
|
||||
|
||||
🔴 ISS-002: Fix user avatar security vulnerability
|
||||
Type: Bug | Priority: Critical | Created: 2025-09-08
|
||||
Status: Open | Impact: High | 🚫 BLOCKING
|
||||
```
|
||||
|
||||
### Closed Issues
|
||||
```
|
||||
✅ ISS-003: Update authentication documentation
|
||||
Type: Documentation | Priority: Low
|
||||
Status: Closed | Completed: 2025-09-05
|
||||
Reason: Documentation updated in PR #45
|
||||
```
|
||||
|
||||
### Integrated Issues
|
||||
```
|
||||
🔗 ISS-004: Implement rate limiting
|
||||
Type: Feature | Priority: Medium
|
||||
Status: Integrated → IMPL-003
|
||||
Integrated: 2025-09-06 | Task: IMPL-3.json
|
||||
```
|
||||
|
||||
## Summary Stats
|
||||
```
|
||||
📊 Issue Summary for WFS-oauth-integration:
|
||||
Total: 4 issues
|
||||
🔴 Open: 2 | ✅ Closed: 1 | 🔗 Integrated: 1
|
||||
🚫 Blocking: 1 | ⚡ Critical: 1 | 📈 High: 1
|
||||
```
|
||||
|
||||
## Empty State
|
||||
If no issues exist:
|
||||
```
|
||||
No issues found for current session.
|
||||
|
||||
Create your first issue:
|
||||
/workflow:issue:create "describe the issue or request"
|
||||
```
|
||||
|
||||
## Quick Actions
|
||||
For each issue, shows available actions:
|
||||
- **Update**: `/workflow:issue:update ISS-001`
|
||||
- **Integrate**: Link to workflow tasks
|
||||
- **Close**: `/workflow:issue:close ISS-001`
|
||||
- **View Details**: Full issue information
|
||||
|
||||
## Session Context
|
||||
- Lists issues from current active session
|
||||
- Shows session name and directory
|
||||
- Indicates if .issues/ directory exists
|
||||
|
||||
## Sorting
|
||||
Issues are sorted by:
|
||||
1. Blocking status (blocking first)
|
||||
2. Priority (critical → high → medium → low)
|
||||
3. Creation date (newest first)
|
||||
|
||||
## Performance
|
||||
- Fast loading from JSON files
|
||||
- Cached issue registry
|
||||
- Efficient filtering
|
||||
|
||||
---
|
||||
|
||||
**Result**: Complete overview of all workflow issues with their current status
|
||||
@@ -1,135 +0,0 @@
|
||||
---
|
||||
name: update
|
||||
description: Update an existing workflow issue
|
||||
usage: /workflow:issue:update <issue-id> [changes]
|
||||
|
||||
examples:
|
||||
- /workflow:issue:update ISS-001
|
||||
- /workflow:issue:update ISS-001 --priority=critical
|
||||
- /workflow:issue:update ISS-001 --status=closed
|
||||
---
|
||||
|
||||
# Update Workflow Issue (/workflow:issue:update)
|
||||
|
||||
## Purpose
|
||||
Modify attributes and status of an existing workflow issue.
|
||||
|
||||
## Usage
|
||||
```bash
|
||||
/workflow:issue:update <issue-id> [options]
|
||||
```
|
||||
|
||||
## Quick Updates
|
||||
Simple attribute changes:
|
||||
```bash
|
||||
/workflow:issue:update ISS-001 --priority=critical
|
||||
/workflow:issue:update ISS-001 --status=closed
|
||||
/workflow:issue:update ISS-001 --blocking
|
||||
/workflow:issue:update ISS-001 --type=bug
|
||||
```
|
||||
|
||||
## Interactive Mode (Default)
|
||||
Without options, opens interactive editor:
|
||||
```
|
||||
Issue ISS-001: Add OAuth2 social login support
|
||||
Current Status: Open | Priority: High | Type: Feature
|
||||
|
||||
What would you like to update?
|
||||
1. Status (open → closed/integrated)
|
||||
2. Priority (high → critical/medium/low)
|
||||
3. Type (feature → bug/optimization/etc)
|
||||
4. Description
|
||||
5. Add comment
|
||||
6. Toggle blocking status
|
||||
7. Cancel
|
||||
|
||||
Choice: _
|
||||
```
|
||||
|
||||
## Available Updates
|
||||
|
||||
### Status Changes
|
||||
- **open** → **closed**: Issue resolved
|
||||
- **open** → **integrated**: Linked to workflow task
|
||||
- **closed** → **open**: Reopen issue
|
||||
- **integrated** → **open**: Unlink from tasks
|
||||
|
||||
### Priority Levels
|
||||
- **critical**: Urgent, blocking progress
|
||||
- **high**: Important, should address soon
|
||||
- **medium**: Standard priority
|
||||
- **low**: Nice-to-have, can defer
|
||||
|
||||
### Issue Types
|
||||
- **bug**: Something broken that needs fixing
|
||||
- **feature**: New functionality to implement
|
||||
- **optimization**: Performance or efficiency improvement
|
||||
- **refactor**: Code structure improvement
|
||||
- **documentation**: Documentation updates
|
||||
|
||||
### Additional Options
|
||||
- **blocking/non-blocking**: Whether issue blocks progress
|
||||
- **description**: Update issue description
|
||||
- **comments**: Add notes and updates
|
||||
|
||||
## Update Process
|
||||
|
||||
### Validation
|
||||
- Verifies issue exists in current session
|
||||
- Checks valid status transitions
|
||||
- Validates priority and type values
|
||||
|
||||
### Change Tracking
|
||||
- Records update details
|
||||
- Tracks who made changes
|
||||
- Maintains change history
|
||||
|
||||
### File Updates
|
||||
- Updates ISS-XXX.json file
|
||||
- Refreshes issue-registry.json
|
||||
- Updates session statistics
|
||||
|
||||
## Change History
|
||||
Maintains audit trail:
|
||||
```json
|
||||
{
|
||||
"changes": [
|
||||
{
|
||||
"field": "priority",
|
||||
"old_value": "high",
|
||||
"new_value": "critical",
|
||||
"reason": "Security implications discovered"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Integration Effects
|
||||
|
||||
### Task Integration
|
||||
When status changes to "integrated":
|
||||
- Links to workflow task (optional)
|
||||
- Updates task context with issue reference
|
||||
- Creates bidirectional linking
|
||||
|
||||
### Session Updates
|
||||
- Updates session issue statistics
|
||||
- Refreshes TodoWrite if applicable
|
||||
- Updates workflow progress tracking
|
||||
|
||||
## Output
|
||||
Shows:
|
||||
- What was changed
|
||||
- Before and after values
|
||||
- Integration status
|
||||
- Available next actions
|
||||
|
||||
## Error Handling
|
||||
- **Issue not found**: Lists available issues
|
||||
- **Invalid status**: Shows valid transitions
|
||||
- **Permission errors**: Clear error messages
|
||||
- **File corruption**: Validates and repairs
|
||||
|
||||
---
|
||||
|
||||
**Result**: Issue successfully updated with change tracking and integration
|
||||
@@ -2,12 +2,7 @@
|
||||
name: plan
|
||||
description: Orchestrate 4-phase planning workflow by executing commands and passing context between phases
|
||||
usage: /workflow:plan [--agent] <input>
|
||||
argument-hint: "[--agent] \"text description\"|file.md|ISS-001"
|
||||
examples:
|
||||
- /workflow:plan "Build authentication system"
|
||||
- /workflow:plan --agent "Build authentication system"
|
||||
- /workflow:plan requirements.md
|
||||
- /workflow:plan ISS-001
|
||||
argument-hint: "[--agent] \"text description\"|file.md"
|
||||
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
|
||||
---
|
||||
|
||||
@@ -202,12 +197,6 @@ TodoWrite({todos: [
|
||||
- Extract goal, scope, requirements
|
||||
- Format into structured description
|
||||
|
||||
4. **Issue Reference** (e.g., `ISS-001`) → Read and structure:
|
||||
- Read issue file
|
||||
- Extract title as goal
|
||||
- Extract description as scope/context
|
||||
- Format into structured description
|
||||
|
||||
## Data Flow
|
||||
|
||||
```
|
||||
@@ -297,4 +286,4 @@ CONSTRAINTS: [Limitations or boundaries]
|
||||
|
||||
# Phase 2
|
||||
/workflow:tools:context-gather --session WFS-123 "GOAL: Build authentication\nSCOPE: JWT, login, registration\nCONTEXT: REST API"
|
||||
```
|
||||
```
|
||||
|
||||
@@ -3,10 +3,6 @@ name: resume
|
||||
description: Intelligent workflow session resumption with automatic progress analysis
|
||||
usage: /workflow:resume "<session-id>"
|
||||
argument-hint: "session-id for workflow session to resume"
|
||||
examples:
|
||||
- /workflow:resume "WFS-user-auth"
|
||||
- /workflow:resume "WFS-api-integration"
|
||||
- /workflow:resume "WFS-database-migration"
|
||||
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
|
||||
---
|
||||
|
||||
|
||||
@@ -2,12 +2,7 @@
|
||||
name: review
|
||||
description: Optional specialized review (security, architecture, docs) for completed implementation
|
||||
usage: /workflow:review [--type=<type>] [session-id]
|
||||
argument-hint: "[--type=security|architecture|action-items|quality] [session-id]"
|
||||
examples:
|
||||
- /workflow:review # Quality review of active session
|
||||
- /workflow:review --type=security # Security audit of active session
|
||||
- /workflow:review --type=architecture WFS-user-auth # Architecture review of specific session
|
||||
- /workflow:review --type=action-items # Pre-deployment verification
|
||||
argument-hint: "[--type=security|architecture|action-items|quality] [optional: session-id]"
|
||||
---
|
||||
|
||||
### 🚀 Command Overview: `/workflow:review`
|
||||
|
||||
@@ -1,7 +1,6 @@
|
||||
---
|
||||
name: complete
|
||||
description: Mark the active workflow session as complete and remove active flag
|
||||
usage: /workflow:session:complete
|
||||
examples:
|
||||
- /workflow:session:complete
|
||||
- /workflow:session:complete --detailed
|
||||
|
||||
@@ -1,7 +1,6 @@
|
||||
---
|
||||
name: list
|
||||
description: List all workflow sessions with status
|
||||
usage: /workflow:session:list
|
||||
examples:
|
||||
- /workflow:session:list
|
||||
---
|
||||
|
||||
@@ -1,69 +0,0 @@
|
||||
---
|
||||
name: pause
|
||||
description: Pause the active workflow session
|
||||
usage: /workflow:session:pause
|
||||
examples:
|
||||
- /workflow:session:pause
|
||||
---
|
||||
|
||||
# Pause Workflow Session (/workflow:session:pause)
|
||||
|
||||
## Overview
|
||||
Pause the currently active workflow session, saving all state for later resumption.
|
||||
|
||||
## Usage
|
||||
```bash
|
||||
/workflow:session:pause # Pause current active session
|
||||
```
|
||||
|
||||
## Implementation Flow
|
||||
|
||||
### Step 1: Find Active Session
|
||||
```bash
|
||||
ls .workflow/.active-* 2>/dev/null | head -1
|
||||
```
|
||||
|
||||
### Step 2: Get Session Name
|
||||
```bash
|
||||
basename .workflow/.active-WFS-session-name | sed 's/^\.active-//'
|
||||
```
|
||||
|
||||
### Step 3: Update Session Status
|
||||
```bash
|
||||
jq '.status = "paused"' .workflow/WFS-session/workflow-session.json > temp.json
|
||||
mv temp.json .workflow/WFS-session/workflow-session.json
|
||||
```
|
||||
|
||||
### Step 4: Add Pause Timestamp
|
||||
```bash
|
||||
jq '.paused_at = "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"' .workflow/WFS-session/workflow-session.json > temp.json
|
||||
mv temp.json .workflow/WFS-session/workflow-session.json
|
||||
```
|
||||
|
||||
### Step 5: Remove Active Marker
|
||||
```bash
|
||||
rm .workflow/.active-WFS-session-name
|
||||
```
|
||||
|
||||
## Simple Bash Commands
|
||||
|
||||
### Basic Operations
|
||||
- **Find active session**: `ls .workflow/.active-*`
|
||||
- **Get session name**: `basename marker | sed 's/^\.active-//'`
|
||||
- **Update status**: `jq '.status = "paused"' session.json > temp.json`
|
||||
- **Add timestamp**: `jq '.paused_at = "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"'`
|
||||
- **Remove marker**: `rm .workflow/.active-session`
|
||||
|
||||
### Pause Result
|
||||
```
|
||||
Session WFS-user-auth paused
|
||||
- Status: paused
|
||||
- Paused at: 2025-09-15T14:30:00Z
|
||||
- Tasks preserved: 8 tasks
|
||||
- Can resume with: /workflow:session:resume
|
||||
```
|
||||
|
||||
## Related Commands
|
||||
- `/workflow:session:resume` - Resume paused session
|
||||
- `/workflow:session:list` - Show all sessions including paused
|
||||
- `/workflow:session:status` - Check session state
|
||||
@@ -1,9 +1,6 @@
|
||||
---
|
||||
name: resume
|
||||
description: Resume the most recently paused workflow session
|
||||
usage: /workflow:session:resume
|
||||
examples:
|
||||
- /workflow:session:resume
|
||||
---
|
||||
|
||||
# Resume Workflow Session (/workflow:session:resume)
|
||||
|
||||
@@ -1,7 +1,6 @@
|
||||
---
|
||||
name: start
|
||||
description: Discover existing sessions or start a new workflow session with intelligent session management
|
||||
usage: /workflow:session:start [--auto|--new] [task_description]
|
||||
argument-hint: [--auto|--new] [optional: task description for new session]
|
||||
examples:
|
||||
- /workflow:session:start
|
||||
|
||||
@@ -1,87 +0,0 @@
|
||||
---
|
||||
name: switch
|
||||
description: Switch to a different workflow session
|
||||
usage: /workflow:session:switch <session-id>
|
||||
argument-hint: session-id to switch to
|
||||
examples:
|
||||
- /workflow:session:switch WFS-oauth-integration
|
||||
- /workflow:session:switch WFS-user-profile
|
||||
---
|
||||
|
||||
# Switch Workflow Session (/workflow:session:switch)
|
||||
|
||||
## Overview
|
||||
Switch the active session to a different workflow session.
|
||||
|
||||
## Usage
|
||||
```bash
|
||||
/workflow:session:switch WFS-session-name # Switch to specific session
|
||||
```
|
||||
|
||||
## Implementation Flow
|
||||
|
||||
### Step 1: Validate Target Session
|
||||
```bash
|
||||
test -d .workflow/WFS-target-session && echo "Session exists"
|
||||
```
|
||||
|
||||
### Step 2: Pause Current Session
|
||||
```bash
|
||||
ls .workflow/.active-* 2>/dev/null | head -1
|
||||
jq '.status = "paused"' .workflow/current-session/workflow-session.json > temp.json
|
||||
```
|
||||
|
||||
### Step 3: Remove Current Active Marker
|
||||
```bash
|
||||
rm .workflow/.active-* 2>/dev/null
|
||||
```
|
||||
|
||||
### Step 4: Activate Target Session
|
||||
```bash
|
||||
jq '.status = "active"' .workflow/WFS-target/workflow-session.json > temp.json
|
||||
mv temp.json .workflow/WFS-target/workflow-session.json
|
||||
```
|
||||
|
||||
### Step 5: Create New Active Marker
|
||||
```bash
|
||||
touch .workflow/.active-WFS-target-session
|
||||
```
|
||||
|
||||
### Step 6: Add Switch Timestamp
|
||||
```bash
|
||||
jq '.switched_at = "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"' .workflow/WFS-target/workflow-session.json > temp.json
|
||||
mv temp.json .workflow/WFS-target/workflow-session.json
|
||||
```
|
||||
|
||||
## Simple Bash Commands
|
||||
|
||||
### Basic Operations
|
||||
- **Check session exists**: `test -d .workflow/WFS-session`
|
||||
- **Find current active**: `ls .workflow/.active-*`
|
||||
- **Pause current**: `jq '.status = "paused"' session.json > temp.json`
|
||||
- **Remove marker**: `rm .workflow/.active-*`
|
||||
- **Activate target**: `jq '.status = "active"' target.json > temp.json`
|
||||
- **Create marker**: `touch .workflow/.active-target`
|
||||
|
||||
### Switch Result
|
||||
```
|
||||
Switched to session: WFS-oauth-integration
|
||||
- Previous: WFS-user-auth (paused)
|
||||
- Current: WFS-oauth-integration (active)
|
||||
- Switched at: 2025-09-15T15:45:00Z
|
||||
- Ready for: /workflow:execute
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
```bash
|
||||
# Session not found
|
||||
test -d .workflow/WFS-nonexistent || echo "Error: Session not found"
|
||||
|
||||
# No sessions available
|
||||
ls .workflow/WFS-* 2>/dev/null || echo "No sessions available"
|
||||
```
|
||||
|
||||
## Related Commands
|
||||
- `/workflow:session:list` - Show all available sessions
|
||||
- `/workflow:session:pause` - Pause current before switching
|
||||
- `/workflow:execute` - Continue with new active session
|
||||
@@ -2,11 +2,7 @@
|
||||
name: workflow:status
|
||||
description: Generate on-demand views from JSON task data
|
||||
usage: /workflow:status [task-id]
|
||||
argument-hint: [optional: task-id]
|
||||
examples:
|
||||
- /workflow:status
|
||||
- /workflow:status impl-1
|
||||
- /workflow:status --validate
|
||||
argument-hint: "[optional: task-id]"
|
||||
---
|
||||
|
||||
# Workflow Status Command (/workflow:status)
|
||||
|
||||
@@ -2,11 +2,7 @@
|
||||
name: tdd-plan
|
||||
description: Orchestrate TDD workflow planning with Red-Green-Refactor task chains
|
||||
usage: /workflow:tdd-plan [--agent] <input>
|
||||
argument-hint: "[--agent] \"feature description\"|file.md|ISS-001"
|
||||
examples:
|
||||
- /workflow:tdd-plan "Implement user authentication"
|
||||
- /workflow:tdd-plan --agent requirements.md
|
||||
- /workflow:tdd-plan ISS-001
|
||||
argument-hint: "[--agent] \"feature description\"|file.md"
|
||||
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
|
||||
---
|
||||
|
||||
|
||||
@@ -2,10 +2,7 @@
|
||||
name: tdd-verify
|
||||
description: Verify TDD workflow compliance and generate quality report
|
||||
usage: /workflow:tdd-verify [session-id]
|
||||
argument-hint: "[WFS-session-id]"
|
||||
examples:
|
||||
- /workflow:tdd-verify
|
||||
- /workflow:tdd-verify WFS-auth
|
||||
argument-hint: "[optional: WFS-session-id]"
|
||||
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(gemini-wrapper:*)
|
||||
---
|
||||
|
||||
|
||||
@@ -2,10 +2,7 @@
|
||||
name: test-gen
|
||||
description: Create independent test-fix workflow session by analyzing completed implementation
|
||||
usage: /workflow:test-gen [--use-codex] <source-session-id>
|
||||
argument-hint: "[--use-codex] <source-session-id>"
|
||||
examples:
|
||||
- /workflow:test-gen WFS-user-auth
|
||||
- /workflow:test-gen --use-codex WFS-api-refactor
|
||||
argument-hint: "[--use-codex] source-session-id"
|
||||
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
|
||||
---
|
||||
|
||||
|
||||
@@ -3,9 +3,6 @@ name: task-generate-tdd
|
||||
description: Generate TDD task chains with Red-Green-Refactor dependencies
|
||||
usage: /workflow:tools:task-generate-tdd --session <session_id> [--agent]
|
||||
argument-hint: "--session WFS-session-id [--agent]"
|
||||
examples:
|
||||
- /workflow:tools:task-generate-tdd --session WFS-auth
|
||||
- /workflow:tools:task-generate-tdd --session WFS-auth --agent
|
||||
allowed-tools: Read(*), Write(*), Bash(gemini-wrapper:*), TodoWrite(*)
|
||||
---
|
||||
|
||||
|
||||
@@ -3,8 +3,6 @@ name: tdd-coverage-analysis
|
||||
description: Analyze test coverage and TDD cycle execution
|
||||
usage: /workflow:tools:tdd-coverage-analysis --session <session_id>
|
||||
argument-hint: "--session WFS-session-id"
|
||||
examples:
|
||||
- /workflow:tools:tdd-coverage-analysis --session WFS-auth
|
||||
allowed-tools: Read(*), Write(*), Bash(*)
|
||||
---
|
||||
|
||||
|
||||
@@ -1,12 +1,7 @@
|
||||
---
|
||||
name: batch-generate
|
||||
description: Prompt-driven batch UI generation using target-style-centric parallel execution
|
||||
usage: /workflow:ui-design:batch-generate --prompt "<description>" [--targets "<list>"] [--target-type "page|component"] [--device-type "desktop|mobile|tablet|responsive"] [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]
|
||||
examples:
|
||||
- /workflow:ui-design:batch-generate --prompt "Dashboard with metrics cards" --style-variants 3
|
||||
- /workflow:ui-design:batch-generate --prompt "Auth pages: login, signup" --session WFS-auth
|
||||
- /workflow:ui-design:batch-generate --prompt "Navbar, hero, footer components" --target-type component
|
||||
- /workflow:ui-design:batch-generate --prompt "Mobile e-commerce app" --device-type mobile
|
||||
argument-hint: [--targets "<list>"] [--target-type "page|component"] [--device-type "desktop|mobile|tablet|responsive"] [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]
|
||||
allowed-tools: TodoWrite(*), Read(*), Write(*), Task(ui-design-agent), Bash(*), mcp__exa__web_search_exa(*)
|
||||
---
|
||||
|
||||
|
||||
@@ -3,10 +3,6 @@ name: capture
|
||||
description: Batch screenshot capture for UI design workflows using MCP or local fallback
|
||||
usage: /workflow:ui-design:capture --url-map "<map>" [--base-path <path>] [--session <id>]
|
||||
argument-hint: --url-map "target:url,..." [--base-path path] [--session id]
|
||||
examples:
|
||||
- /workflow:ui-design:capture --url-map "home:https://linear.app, pricing:https://linear.app/pricing"
|
||||
- /workflow:ui-design:capture --session WFS-auth --url-map "dashboard:https://app.com/dash"
|
||||
- /workflow:ui-design:capture --base-path ".workflow/.design/run-20250110" --url-map "hero:https://example.com#hero"
|
||||
allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*), ListMcpResourcesTool(*), mcp__chrome-devtools__*, mcp__playwright__*
|
||||
---
|
||||
|
||||
|
||||
@@ -1,12 +1,7 @@
|
||||
---
|
||||
name: consolidate
|
||||
description: Consolidate style variants into independent design systems and plan layout strategies
|
||||
usage: /workflow:ui-design:consolidate [--base-path <path>] [--session <id>] [--variants <count>] [--layout-variants <count>]
|
||||
examples:
|
||||
- /workflow:ui-design:consolidate --base-path ".workflow/WFS-auth/design-run-20250109-143022" --variants 3
|
||||
- /workflow:ui-design:consolidate --session WFS-auth --variants 2
|
||||
- /workflow:ui-design:consolidate --base-path "./.workflow/.design/run-20250109-150533" # Uses all variants
|
||||
- /workflow:ui-design:consolidate --session WFS-auth # Process all variants from extraction
|
||||
argument-hint: /workflow:ui-design:consolidate [--base-path <path>] [--session <id>] [--variants <count>] [--layout-variants <count>]
|
||||
allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Task(*)
|
||||
---
|
||||
|
||||
|
||||
@@ -1,13 +1,7 @@
|
||||
---
|
||||
name: explore-auto
|
||||
description: Exploratory UI design workflow with style-centric batch generation
|
||||
usage: /workflow:ui-design:explore-auto [--prompt "<desc>"] [--images "<glob>"] [--targets "<list>"] [--target-type "page|component"] [--session <id>] [--style-variants <count>] [--layout-variants <count>] [--batch-plan]
|
||||
examples:
|
||||
- /workflow:ui-design:explore-auto --prompt "Generate 3 style variants for modern blog: home, article, author"
|
||||
- /workflow:ui-design:explore-auto --prompt "SaaS dashboard and settings with 2 layout options"
|
||||
- /workflow:ui-design:explore-auto --images "refs/*.png" --prompt "E-commerce: home, product, cart" --style-variants 3 --layout-variants 3
|
||||
- /workflow:ui-design:explore-auto --session WFS-auth --images "refs/*.png"
|
||||
- /workflow:ui-design:explore-auto --targets "navbar,hero" --target-type "component" --style-variants 3 --layout-variants 2
|
||||
argument-hint: "[--prompt "<desc>"] [--images "<glob>"] [--targets "<list>"] [--target-type "page|component"] [--session <id>] [--style-variants <count>] [--layout-variants <count>] [--batch-plan]""
|
||||
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*), Task(conceptual-planning-agent)
|
||||
---
|
||||
|
||||
|
||||
@@ -3,10 +3,6 @@ name: explore-layers
|
||||
description: Interactive deep UI capture with depth-controlled layer exploration
|
||||
usage: /workflow:ui-design:explore-layers --url <url> --depth <1-5> [--session <id>] [--base-path <path>]
|
||||
argument-hint: --url <url> --depth <1-5> [--session id] [--base-path path]
|
||||
examples:
|
||||
- /workflow:ui-design:explore-layers --url "https://app.linear.app" --depth 3
|
||||
- /workflow:ui-design:explore-layers --url "https://notion.so" --depth 2 --session WFS-notion-ui
|
||||
- /workflow:ui-design:explore-layers --url "https://app.com/dashboard" --depth 4
|
||||
allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*), mcp__chrome-devtools__*
|
||||
---
|
||||
|
||||
|
||||
@@ -1,11 +1,7 @@
|
||||
---
|
||||
name: generate
|
||||
description: Assemble UI prototypes by combining layout templates with design tokens (pure assembler)
|
||||
usage: /workflow:ui-design:generate [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]
|
||||
examples:
|
||||
- /workflow:ui-design:generate --session WFS-auth
|
||||
- /workflow:ui-design:generate --style-variants 2 --layout-variants 2
|
||||
- /workflow:ui-design:generate --base-path ".workflow/WFS-auth/design-run-20250109-143022"
|
||||
argument-hint: [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]
|
||||
allowed-tools: TodoWrite(*), Read(*), Write(*), Task(ui-design-agent), Bash(*)
|
||||
---
|
||||
|
||||
|
||||
@@ -1,13 +1,7 @@
|
||||
---
|
||||
name: imitate-auto
|
||||
description: High-speed multi-page UI replication with batch screenshot and optional token refinement
|
||||
usage: /workflow:ui-design:imitate-auto --url-map "<map>" [--capture-mode <batch|deep>] [--depth <1-5>] [--session <id>] [--refine-tokens] [--prompt "<desc>"]
|
||||
examples:
|
||||
- /workflow:ui-design:imitate-auto --url-map "home:https://linear.app, features:https://linear.app/features"
|
||||
- /workflow:ui-design:imitate-auto --session WFS-payment --url-map "pricing:https://stripe.com/pricing"
|
||||
- /workflow:ui-design:imitate-auto --url-map "dashboard:https://app.com/dash" --refine-tokens
|
||||
- /workflow:ui-design:imitate-auto --url-map "app:https://app.com" --capture-mode deep --depth 3
|
||||
- /workflow:ui-design:imitate-auto --url-map "home:https://example.com, about:https://example.com/about" --prompt "Focus on minimalist design"
|
||||
argument-hint: --url-map "<map>" [--capture-mode <batch|deep>] [--depth <1-5>] [--session <id>] [--refine-tokens] [--prompt "<desc>"]
|
||||
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Write(*), Bash(*)
|
||||
---
|
||||
|
||||
|
||||
@@ -1,12 +1,7 @@
|
||||
---
|
||||
name: layout-extract
|
||||
description: Extract structural layout information from reference images, URLs, or text prompts
|
||||
usage: /workflow:ui-design:layout-extract [--base-path <path>] [--session <id>] [--images "<glob>"] [--urls "<list>"] [--prompt "<desc>"] [--targets "<list>"] [--mode <imitate|explore>] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>]
|
||||
examples:
|
||||
- /workflow:ui-design:layout-extract --urls "home:https://linear.app" --mode imitate --targets "home"
|
||||
- /workflow:ui-design:layout-extract --images "refs/*.png" --mode explore --variants 3 --targets "dashboard"
|
||||
- /workflow:ui-design:layout-extract --prompt "Two-column blog with sticky sidebar" --mode explore --variants 2 --targets "blog-post"
|
||||
- /workflow:ui-design:layout-extract --session WFS-auth --urls "login:https://clerk.dev" --device-type mobile --targets "login"
|
||||
argument-hint: [--base-path <path>] [--session <id>] [--images "<glob>"] [--urls "<list>"] [--prompt "<desc>"] [--targets "<list>"] [--mode <imitate|explore>] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>]
|
||||
allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), Bash(*), Task(ui-design-agent), mcp__exa__web_search_exa(*)
|
||||
---
|
||||
|
||||
|
||||
@@ -1,13 +1,7 @@
|
||||
---
|
||||
name: style-extract
|
||||
description: Extract design style from reference images or text prompts using Claude's analysis
|
||||
usage: /workflow:ui-design:style-extract [--base-path <path>] [--session <id>] [--images "<glob>"] [--prompt "<desc>"] [--mode <imitate|explore>] [--variants <count>]
|
||||
examples:
|
||||
- /workflow:ui-design:style-extract --images "design-refs/*.png" --mode explore --variants 3
|
||||
- /workflow:ui-design:style-extract --prompt "Modern minimalist blog, dark theme" --mode explore --variants 3
|
||||
- /workflow:ui-design:style-extract --session WFS-auth --images "refs/*.png" --prompt "Linear.app style" --mode imitate
|
||||
- /workflow:ui-design:style-extract --base-path ".workflow/WFS-auth/design-run-20250109-143022" --images "refs/*.png" --mode explore --variants 3
|
||||
- /workflow:ui-design:style-extract --prompt "Bold vibrant" --mode imitate # High-fidelity single style
|
||||
argument-hint: "[--base-path <path>] [--session <id>] [--images "<glob>"] [--prompt "<desc>"] [--mode <imitate|explore>] [--variants <count>]"
|
||||
allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*)
|
||||
---
|
||||
|
||||
|
||||
@@ -1,10 +1,7 @@
|
||||
---
|
||||
name: update
|
||||
description: Update brainstorming artifacts with finalized design system references
|
||||
usage: /workflow:ui-design:update --session <session_id> [--selected-prototypes "<list>"]
|
||||
examples:
|
||||
- /workflow:ui-design:update --session WFS-auth
|
||||
- /workflow:ui-design:update --session WFS-dashboard --selected-prototypes "dashboard-variant-1"
|
||||
argument-hint: --session <session_id> [--selected-prototypes "<list>"]
|
||||
allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
|
||||
---
|
||||
|
||||
|
||||
@@ -1898,12 +1898,6 @@ This is a **breaking change release** with significant architectural improvement
|
||||
- **Intelligent Modes**: Auto template selection and precise planning
|
||||
- **Full Command Suite**: analyze, chat, execute, mode:auto, mode:bug-index, mode:plan
|
||||
|
||||
#### 🏷️ Issue Management Commands
|
||||
- `/workflow:issue:create` - Create new project issues with priority/type
|
||||
- `/workflow:issue:list` - List and filter issues by status/assignment
|
||||
- `/workflow:issue:update` - Update existing issue status and assignments
|
||||
- `/workflow:issue:close` - Close completed issues with resolution
|
||||
|
||||
#### 📋 Enhanced Workflow Commands
|
||||
- `/workflow:plan-verify` - Pre-execution validation using dual analysis
|
||||
- `/workflow:test-gen` - Generate comprehensive test workflows
|
||||
|
||||
167
README.md
167
README.md
@@ -275,28 +275,49 @@ MCP (Model Context Protocol) tools provide advanced codebase analysis. **Recomme
|
||||
```
|
||||
|
||||
**Phase 2: UI Design Refinement** *(Optional for UI-heavy projects)*
|
||||
|
||||
**🎯 Choose Your Workflow:**
|
||||
|
||||
**Scenario 1: Starting from an idea or concept** → Use `explore-auto`
|
||||
```bash
|
||||
# Matrix Exploration Mode - Multiple style/layout variants (v4.2.1+)
|
||||
# Generate multiple style and layout options to explore different directions
|
||||
/workflow:ui-design:explore-auto --prompt "Modern blog: home, article, author" --style-variants 3 --layout-variants 2
|
||||
# Creates a 3×2 matrix: 3 visual styles × 2 layouts = 6 prototypes to choose from
|
||||
```
|
||||
|
||||
# Fast Imitation Mode - Single design replication (v4.2.1+)
|
||||
**Scenario 2: Replicating an existing design** → Use `imitate-auto`
|
||||
```bash
|
||||
# Fast, high-fidelity replication of reference designs
|
||||
/workflow:ui-design:imitate-auto --images "refs/design.png" --pages "dashboard,settings"
|
||||
# Or auto-screenshot from URL (requires Playwright/Chrome DevTools MCP)
|
||||
/workflow:ui-design:imitate-auto --url "https://linear.app" --pages "home,features"
|
||||
```
|
||||
|
||||
# With session integration
|
||||
/workflow:ui-design:explore-auto --session WFS-auth --images "refs/*.png" --style-variants 2 --layout-variants 3
|
||||
**Scenario 3: Batch creation from existing design system** → Use `batch-generate`
|
||||
```bash
|
||||
# Already have a design system? Generate multiple pages quickly
|
||||
/workflow:ui-design:batch-generate --prompt "Create profile and settings pages" --layout-variants 2
|
||||
```
|
||||
|
||||
# Or run individual design phases (v4.4.0+)
|
||||
**Advanced: Manual Step-by-Step Control** (v4.4.0+)
|
||||
```bash
|
||||
# 1. Extract visual style (colors, typography, spacing)
|
||||
/workflow:ui-design:style-extract --images "refs/*.png" --mode explore --variants 3
|
||||
|
||||
# 2. Consolidate into production-ready design tokens
|
||||
/workflow:ui-design:consolidate --variants "variant-1,variant-3"
|
||||
|
||||
# 3. Extract layout structure (DOM, CSS layout rules)
|
||||
/workflow:ui-design:layout-extract --targets "dashboard,auth" --mode explore --variants 2 --device-type responsive
|
||||
|
||||
# 4. Combine style + layout → HTML/CSS prototypes
|
||||
/workflow:ui-design:generate --style-variants 1 --layout-variants 2
|
||||
|
||||
# Preview generated prototypes
|
||||
# Option 1: Open .workflow/WFS-auth/.design/prototypes/compare.html in browser
|
||||
# Option 2: Start local server
|
||||
# 5. Preview and select
|
||||
cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
|
||||
# Visit http://localhost:8080 for interactive preview with comparison tools
|
||||
# Visit http://localhost:8080/compare.html for side-by-side comparison
|
||||
|
||||
# 6. Integrate selected design into project
|
||||
/workflow:ui-design:update --session WFS-auth --selected-prototypes "dashboard-s1-l2"
|
||||
```
|
||||
|
||||
@@ -389,7 +410,7 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
|
||||
|
||||
| Command | Description |
|
||||
|---|---|
|
||||
| `/workflow:session:*` | Manage development sessions (`start`, `pause`, `resume`, `list`, `switch`, `complete`). |
|
||||
| `/workflow:session:*` | Manage development sessions (`start`, `resume`, `list`, `complete`). |
|
||||
| `/workflow:brainstorm:*` | Use role-based agents for multi-perspective planning. |
|
||||
| `/workflow:ui-design:explore-auto` | **v4.4.0** Matrix exploration mode - Generate multiple style × layout variants with layout/style separation. |
|
||||
| `/workflow:ui-design:imitate-auto` | **v4.4.0** Fast imitation mode - Rapid UI replication with auto-screenshot, layout extraction, and assembly. |
|
||||
@@ -413,6 +434,77 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
|
||||
|
||||
The design workflow system provides complete UI design refinement with **layout/style separation architecture**, **pure Claude execution**, **intelligent target inference**, and **zero external dependencies**.
|
||||
|
||||
#### 📐 Architecture Overview
|
||||
|
||||
The UI workflow follows a **separation of concerns** philosophy:
|
||||
- **Style (Visual Tokens)**: Colors, typography, spacing, borders → `design-tokens.json`
|
||||
- **Layout (Structure)**: DOM hierarchy, CSS layout rules → `layout-templates.json`
|
||||
- **Assembly**: Pure combination of style + layout → HTML/CSS prototypes
|
||||
|
||||
**Command Categories:**
|
||||
|
||||
| Category | Commands | Purpose |
|
||||
|----------|----------|---------|
|
||||
| **High-Level Orchestrators** | `explore-auto`, `imitate-auto`, `batch-generate` | Complete workflows (recommended) |
|
||||
| **Input/Capture** | `capture`, `explore-layers` | Screenshot acquisition |
|
||||
| **Analysis/Extraction** | `style-extract`, `layout-extract` | Visual style and structural layout extraction |
|
||||
| **Processing/Generation** | `consolidate`, `generate` | Token validation and prototype assembly |
|
||||
| **Integration** | `update` | Design system integration into project |
|
||||
|
||||
#### 🧭 Decision Tree: Which Command Should I Use?
|
||||
|
||||
```
|
||||
┌─ Have an idea or text description?
|
||||
│ └─→ /workflow:ui-design:explore-auto
|
||||
│ (Explores multiple style × layout options)
|
||||
│
|
||||
┌─ Want to replicate an existing design?
|
||||
│ └─→ /workflow:ui-design:imitate-auto
|
||||
│ (High-fidelity single design replication)
|
||||
│
|
||||
┌─ Already have a design system?
|
||||
│ └─→ /workflow:ui-design:batch-generate
|
||||
│ (Batch create multiple pages/components)
|
||||
│
|
||||
└─ Need fine-grained control?
|
||||
└─→ Use individual commands in sequence:
|
||||
1. style-extract → Extract colors, fonts, spacing
|
||||
2. consolidate → Validate and merge tokens
|
||||
3. layout-extract → Extract DOM structure
|
||||
4. generate → Combine into prototypes
|
||||
5. update → Integrate into project
|
||||
```
|
||||
|
||||
#### 🔄 Workflow Diagrams
|
||||
|
||||
**Explore Workflow** (Idea → Multiple Designs):
|
||||
```
|
||||
Prompt/Images → style-extract (explore mode)
|
||||
↓
|
||||
consolidate (N variants)
|
||||
↓
|
||||
layout-extract (explore mode)
|
||||
↓
|
||||
generate (N styles × M layouts)
|
||||
↓
|
||||
update (selected designs)
|
||||
```
|
||||
|
||||
**Imitate Workflow** (Reference → Single Design):
|
||||
```
|
||||
URL/Images → capture/explore-layers
|
||||
↓
|
||||
style-extract (imitate mode)
|
||||
↓
|
||||
layout-extract (imitate mode)
|
||||
↓
|
||||
consolidate (single variant)
|
||||
↓
|
||||
generate (1 style × 1 layout)
|
||||
↓
|
||||
update (final design)
|
||||
```
|
||||
|
||||
#### Core Commands
|
||||
|
||||
**`/workflow:ui-design:explore-auto`** - Matrix exploration mode
|
||||
@@ -546,6 +638,61 @@ php -S localhost:8080 # PHP
|
||||
- Dynamic page switching
|
||||
- Real-time responsive testing
|
||||
|
||||
#### 📦 Output Structure
|
||||
|
||||
All UI workflow outputs are organized in the `.design` directory within your session:
|
||||
|
||||
```
|
||||
.workflow/WFS-<session-id>/.design/
|
||||
├── design-run-YYYYMMDD-HHMMSS/ # Timestamped design run
|
||||
│ ├── screenshots/ # 📸 Captured screenshots
|
||||
│ │ ├── home.png
|
||||
│ │ └── dashboard.png
|
||||
│ │
|
||||
│ ├── style-extraction/ # 🎨 Style analysis phase
|
||||
│ │ ├── style-cards.json # AI-proposed style variants
|
||||
│ │ └── design-space-analysis.json # (explore mode) Diversity analysis
|
||||
│ │
|
||||
│ ├── layout-extraction/ # 🏗️ Layout analysis phase
|
||||
│ │ └── layout-templates.json # Structural templates with token-based CSS
|
||||
│ │
|
||||
│ ├── style-consolidation/ # ✅ Production design systems
|
||||
│ │ ├── style-1/
|
||||
│ │ │ ├── design-tokens.json # W3C design tokens
|
||||
│ │ │ ├── style-guide.md # Visual design documentation
|
||||
│ │ │ ├── tailwind.config.js # Tailwind configuration
|
||||
│ │ │ └── validation-report.json # WCAG AA validation results
|
||||
│ │ └── style-2/
|
||||
│ │ └── ...
|
||||
│ │
|
||||
│ └── prototypes/ # 🎯 Final HTML/CSS prototypes
|
||||
│ ├── home-style-1-layout-1.html # Matrix-generated prototypes
|
||||
│ ├── home-style-1-layout-1.css
|
||||
│ ├── home-style-1-layout-2.html
|
||||
│ ├── dashboard-style-2-layout-1.html
|
||||
│ ├── index.html # Master navigation page
|
||||
│ └── compare.html # Side-by-side comparison tool
|
||||
│
|
||||
└── latest -> design-run-YYYYMMDD-HHMMSS # Symlink to most recent run
|
||||
```
|
||||
|
||||
**Key Files:**
|
||||
|
||||
| File | Purpose | Generated By |
|
||||
|------|---------|--------------|
|
||||
| `style-cards.json` | AI-proposed visual styles with embedded tokens | `style-extract` |
|
||||
| `layout-templates.json` | Structural templates with token-based CSS | `layout-extract` |
|
||||
| `design-tokens.json` | Production-ready W3C design tokens | `consolidate` |
|
||||
| `style-guide.md` | Visual design system documentation | `consolidate` |
|
||||
| `compare.html` | Interactive prototype comparison matrix | `generate` |
|
||||
|
||||
**Best Practices:**
|
||||
|
||||
1. **Session Management**: All runs within a session accumulate in `.design/design-run-*/`
|
||||
2. **Versioning**: Each run is timestamped for easy rollback
|
||||
3. **Integration**: Use `update` command to link final tokens to project artifacts
|
||||
4. **Cleanup**: Old runs can be safely deleted; `latest` symlink always points to newest
|
||||
|
||||
---
|
||||
|
||||
### **Task & Memory Commands**
|
||||
|
||||
@@ -388,7 +388,7 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
|
||||
|
||||
| 命令 | 描述 |
|
||||
|---|---|
|
||||
| `/workflow:session:*` | 管理开发会话（`start`, `pause`, `resume`, `list`, `switch`, `complete`）。 |
|
||||
| `/workflow:session:*` | 管理开发会话（`start`, `resume`, `list`, `complete`）。 |
|
||||
| `/workflow:brainstorm:*` | 使用基于角色的智能体进行多视角规划。 |
|
||||
| `/workflow:ui-design:explore-auto` | **v4.2.1** 矩阵探索模式 - 生成多个风格×布局变体，全面探索设计方向。 |
|
||||
| `/workflow:ui-design:imitate-auto` | **v4.2.1** 快速模仿模式 - 单一设计快速复制，自动截图和直接令牌提取。 |
|
||||
|
||||
@@ -512,15 +512,13 @@ graph TD
|
||||
graph LR
|
||||
subgraph "Session Management"
|
||||
WFS_START["/workflow:session:start"]
|
||||
WFS_PAUSE["/workflow:session:pause"]
|
||||
WFS_RESUME["/workflow:session:resume"]
|
||||
WFS_SWITCH["/workflow:session:switch"]
|
||||
WFS_LIST["/workflow:session:list"]
|
||||
WFS_COMPLETE["/workflow:session:complete"]
|
||||
|
||||
WFS_START --> WFS_PAUSE
|
||||
WFS_PAUSE --> WFS_RESUME
|
||||
WFS_RESUME --> WFS_SWITCH
|
||||
WFS_SWITCH --> WFS_LIST
|
||||
WFS_START --> WFS_LIST
|
||||
WFS_LIST --> WFS_RESUME
|
||||
WFS_RESUME --> WFS_COMPLETE
|
||||
end
|
||||
|
||||
subgraph "Planning Phase"
|
||||
@@ -554,7 +552,6 @@ graph LR
|
||||
WFS_START --> WF_BRAINSTORM
|
||||
WF_PLAN --> WF_EXECUTE
|
||||
WF_EXECUTE --> TASK_CREATE
|
||||
WF_REVIEW --> WFS_PAUSE
|
||||
```
|
||||
|
||||
## 11. Planning Method Selection Flow
|
||||
|
||||
@@ -1,231 +0,0 @@
|
||||
# UI原型实例化脚本分析报告
|
||||
|
||||
## 问题现象
|
||||
|
||||
在执行 `ui-instantiate-prototypes.sh` 脚本时，生成了 `style-4` 的原型文件（如 `login-style-4-layout-1.html`），但实际上 `style-consolidation` 目录下只有3个样式目录（style-1, style-2, style-3）。
|
||||
|
||||
## 调查结果
|
||||
|
||||
### 1. 目录结构验证
|
||||
|
||||
```bash
|
||||
# 实际存在的样式目录
|
||||
.workflow/.design/run-20251009-210559/style-consolidation/
|
||||
├── style-1/
|
||||
├── style-2/
|
||||
└── style-3/
|
||||
|
||||
# 生成的原型文件包含
|
||||
prototypes/login-style-4-layout-1.html ❌ 引用不存在的 ../style-consolidation/style-4/tokens.css
|
||||
prototypes/sidebar-style-4-layout-1.html ❌ 引用不存在的 ../style-consolidation/style-4/tokens.css
|
||||
```
|
||||
|
||||
### 2. consolidation-report.json 确认
|
||||
|
||||
```json
|
||||
{
|
||||
"variant_count": 3, // 明确显示只有3个变体
|
||||
"variants": [
|
||||
{"id": "style-1"},
|
||||
{"id": "style-2"},
|
||||
{"id": "style-3"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 3. PREVIEW.md 显示异常
|
||||
|
||||
```markdown
|
||||
- **Style Variants:** 4 ⚠️ 与实际不符
|
||||
- **Total Prototypes:** 24 (4 × 3 × 2 = 24)
|
||||
```
|
||||
|
||||
### 4. 脚本auto_detect_style_variants()函数
|
||||
|
||||
```bash
|
||||
# 位置：.claude/scripts/ui-instantiate-prototypes.sh 第52-71行
|
||||
auto_detect_style_variants() {
|
||||
local base_path="$1"
|
||||
local style_dir="$base_path/../style-consolidation"
|
||||
|
||||
# 统计style-*目录数量
|
||||
local count=$(find "$style_dir" -maxdepth 1 -type d -name "style-*" | wc -l)
|
||||
echo "$count"
|
||||
}
|
||||
```
|
||||
|
||||
**验证测试**：
|
||||
```bash
|
||||
cd .workflow/.design/run-20251009-210559/style-consolidation
|
||||
find . -maxdepth 1 -type d -name "style-*" | wc -l
|
||||
# 输出：3 ✅ 函数逻辑正确
|
||||
```
|
||||
|
||||
## 根本原因分析
|
||||
|
||||
### ⚠️ 参数覆盖问题
|
||||
|
||||
脚本虽然有自动检测功能，但**允许手动参数覆盖**：
|
||||
|
||||
```bash
|
||||
# 自动检测模式（正确）
|
||||
ui-instantiate-prototypes.sh prototypes/ # 会自动检测到3个样式
|
||||
|
||||
# 手动模式（错误来源）
|
||||
ui-instantiate-prototypes.sh prototypes/ "login,sidebar" 4 3 # 强制指定4个样式变体 ❌
|
||||
```
|
||||
|
||||
### 🔍 实际调用场景
|
||||
|
||||
根据工作流命令 `.claude/commands/workflow/ui-design/generate.md` 第79-82行：
|
||||
|
||||
```bash
|
||||
# Phase 1: Path Resolution & Context Loading
|
||||
style_variants = --style-variants OR 3 # 默认为3
|
||||
```
|
||||
|
||||
**推断的问题来源**：
|
||||
1. 工作流命令被手动调用时，传入了 `--style-variants 4`
|
||||
2. 这个参数被直接传递给 `ui-instantiate-prototypes.sh` 脚本
|
||||
3. 脚本没有验证参数值与实际目录数量是否匹配
|
||||
4. 导致生成了引用不存在的style-4目录的HTML文件
|
||||
|
||||
## 问题影响
|
||||
|
||||
### 生成的style-4文件问题
|
||||
|
||||
所有 `*-style-4-*.html` 文件都会出现CSS加载失败：
|
||||
|
||||
```html
|
||||
<!-- 文件中的CSS引用 -->
|
||||
<link rel="stylesheet" href="../style-consolidation/style-4/tokens.css">
|
||||
<!-- ❌ 该路径不存在，导致样式无法加载 -->
|
||||
```
|
||||
|
||||
### 影响范围
|
||||
|
||||
- `login-style-4-layout-{1,2,3}.html` - 3个文件 ❌
|
||||
- `sidebar-style-4-layout-{1,2,3}.html` - 3个文件 ❌
|
||||
- 对应的 `*-notes.md` 文件 - 6个说明文件（内容错误）
|
||||
|
||||
## 解决方案
|
||||
|
||||
### 方案1：重新生成（推荐）
|
||||
|
||||
```bash
|
||||
cd .workflow/.design/run-20251009-210559/prototypes
|
||||
|
||||
# 删除错误的style-4文件
|
||||
rm -f *-style-4-*
|
||||
|
||||
# 重新运行脚本（使用自动检测）
|
||||
~/.claude/scripts/ui-instantiate-prototypes.sh . --session-id run-20251009-210559
|
||||
```
|
||||
|
||||
### 方案2：脚本增强（预防）
|
||||
|
||||
在 `ui-instantiate-prototypes.sh` 中添加参数验证：
|
||||
|
||||
```bash
|
||||
# 在第239行之后添加
|
||||
# Validate STYLE_VARIANTS matches actual directories
|
||||
actual_styles=$(find "$BASE_PATH/../style-consolidation" -maxdepth 1 -type d -name "style-*" | wc -l)
|
||||
if [ "$STYLE_VARIANTS" -gt "$actual_styles" ]; then
|
||||
log_warning "Requested $STYLE_VARIANTS style variants, but only found $actual_styles directories"
|
||||
log_info "Auto-correcting to $actual_styles style variants"
|
||||
STYLE_VARIANTS=$actual_styles
|
||||
fi
|
||||
```
|
||||
|
||||
### 方案3：工作流命令修复
|
||||
|
||||
在 `.claude/commands/workflow/ui-design/generate.md` 中添加验证：
|
||||
|
||||
```bash
|
||||
# Phase 1: Path Resolution & Context Loading (第79-82行之后)
|
||||
style_variants = --style-variants OR 3 # Default to 3
|
||||
|
||||
# 添加验证逻辑
|
||||
actual_styles = count_directories({base_path}/style-consolidation/style-*)
|
||||
IF style_variants > actual_styles:
|
||||
WARN: "Requested {style_variants} styles, but only {actual_styles} exist"
|
||||
REPORT: "Auto-correcting to {actual_styles} style variants"
|
||||
style_variants = actual_styles
|
||||
|
||||
VALIDATE: 1 <= style_variants <= 5
|
||||
```
|
||||
|
||||
## 预防措施
|
||||
|
||||
1. **优先使用自动检测**：
|
||||
```bash
|
||||
# ✅ 推荐：让脚本自动检测
|
||||
ui-instantiate-prototypes.sh prototypes/
|
||||
|
||||
# ⚠️ 谨慎：手动指定参数（需确保正确）
|
||||
ui-instantiate-prototypes.sh prototypes/ "login,sidebar" 3 3
|
||||
```
|
||||
|
||||
2. **验证consolidation输出**：
|
||||
```bash
|
||||
# 生成原型前，先确认样式数量
|
||||
jq '.variant_count' style-consolidation/consolidation-report.json
|
||||
```
|
||||
|
||||
3. **使用工作流命令**：
|
||||
```bash
|
||||
# 工作流命令会自动处理参数验证
|
||||
/workflow:ui-design:generate --base-path ".workflow/.design/run-xxx"
|
||||
```
|
||||
|
||||
## 技术细节
|
||||
|
||||
### 自动检测逻辑流程
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[调用脚本] --> B{检查参数数量}
|
||||
B -->|1个参数| C[自动检测模式]
|
||||
B -->|4个参数| D[手动模式]
|
||||
C --> E[检测style目录]
|
||||
D --> F[使用传入参数]
|
||||
E --> G[验证目录存在]
|
||||
F --> G
|
||||
G -->|不匹配| H[⚠️ 生成错误文件]
|
||||
G -->|匹配| I[✅ 正常生成]
|
||||
```
|
||||
|
||||
### find命令行为
|
||||
|
||||
```bash
|
||||
# 正确的检测命令
|
||||
find style-consolidation -maxdepth 1 -type d -name "style-*"
|
||||
# 输出：
|
||||
# style-consolidation/style-1
|
||||
# style-consolidation/style-2
|
||||
# style-consolidation/style-3
|
||||
|
||||
# wc -l 统计行数 = 3 ✅
|
||||
|
||||
# 注意：style-extraction 不会被匹配（它在父目录）
|
||||
# find . -maxdepth 1 -type d -name "style-*"
|
||||
# 只会在当前目录搜索，不会递归到子目录
|
||||
```
|
||||
|
||||
## 总结
|
||||
|
||||
### 问题根源
|
||||
✅ **确认**：脚本被手动调用时传入了错误的 `--style-variants 4` 参数，但实际只有3个样式目录存在。
|
||||
|
||||
### 脚本行为
|
||||
✅ **确认**：`auto_detect_style_variants()` 函数逻辑正确，能够正确检测到3个样式目录。
|
||||
|
||||
### 修复优先级
|
||||
1. 🔴 **立即**：删除错误的style-4文件，重新生成
|
||||
2. 🟡 **短期**：在脚本中添加参数验证逻辑
|
||||
3. 🟢 **长期**：在工作流命令中添加防护验证
|
||||
|
||||
### 最佳实践
|
||||
- 优先使用脚本的自动检测模式
|
||||
- 在手动指定参数前，先验证 `consolidation-report.json`
|
||||
- 使用工作流命令而非直接调用脚本
|
||||
@@ -1,425 +0,0 @@
|
||||
# UI设计工作流参数清晰度分析报告
|
||||
|
||||
## 📋 执行摘要
|
||||
|
||||
**问题来源**：用户手动调用 `/workflow:ui-design:generate` 时传入了 `--style-variants 4`，但实际只有3个样式目录存在，导致生成了引用不存在CSS文件的 `style-4` 原型。
|
||||
|
||||
**根本原因**：工作流命令链中参数命名不一致、验证缺失、文档说明不清晰。
|
||||
|
||||
## 🔍 关键发现
|
||||
|
||||
### 1. 参数命名不一致
|
||||
|
||||
| 命令 | 参数名称 | 默认值 | 说明 |
|
||||
|------|---------|--------|------|
|
||||
| `extract` | `--variants` | 1 | ⚠️ 未在文档中明确说明默认值 |
|
||||
| `consolidate` | `--variants` | 所有变体 | ⚠️ 与extract同名但语义不同 |
|
||||
| `generate` | `--style-variants` | 3 | ⚠️ 名称不一致，默认值说明不清晰 |
|
||||
|
||||
**问题**：
|
||||
- `extract` 和 `consolidate` 使用 `--variants`，但 `generate` 使用 `--style-variants`
|
||||
- `--variants` 在两个命令中含义不同：
|
||||
- `extract`：生成多少个变体
|
||||
- `consolidate`：处理多少个变体
|
||||
|
||||
### 2. 命名转换混淆
|
||||
|
||||
```
|
||||
extract 输出 → consolidate 处理 → generate 使用
|
||||
variant-1 → style-1/ → login-style-1-layout-1.html
|
||||
variant-2 → style-2/ → login-style-2-layout-1.html
|
||||
variant-3 → style-3/ → login-style-3-layout-1.html
|
||||
```
|
||||
|
||||
**问题**：
|
||||
- `variant-N` 到 `style-N` 的转换没有文档说明
|
||||
- 增加了用户的认知负担
|
||||
- 容易造成混淆和错误
|
||||
|
||||
### 3. 验证缺失
|
||||
|
||||
#### ❌ 当前状态（generate.md 第79-82行）
|
||||
|
||||
```bash
|
||||
# Phase 1: Path Resolution & Context Loading
|
||||
style_variants = --style-variants OR 3 # Default to 3
|
||||
VALIDATE: 1 <= style_variants <= 5
|
||||
```
|
||||
|
||||
**问题**：
|
||||
- ✅ 验证范围（1-5）
|
||||
- ❌ 不验证是否匹配实际目录数量
|
||||
- ❌ 允许传入 `4` 但实际只有 `3` 个目录
|
||||
|
||||
#### ✅ 应有的验证
|
||||
|
||||
```bash
|
||||
style_variants = --style-variants OR 3
|
||||
actual_styles = count_directories({base_path}/style-consolidation/style-*)
|
||||
|
||||
IF style_variants > actual_styles:
|
||||
WARN: "Requested {style_variants} styles, but only {actual_styles} exist"
|
||||
REPORT: "Auto-correcting to {actual_styles} style variants"
|
||||
style_variants = actual_styles
|
||||
|
||||
VALIDATE: 1 <= style_variants <= actual_styles
|
||||
```
|
||||
|
||||
### 4. 文档清晰度问题
|
||||
|
||||
#### extract.md
|
||||
|
||||
**问题点**：
|
||||
- ⚠️ 默认值 `1` 未在 `usage` 或 `argument-hint` 中说明
|
||||
- ⚠️ 输出的 `variant-N` 命名未解释后续转换为 `style-N`
|
||||
|
||||
**当前文档**（第580行附近）：
|
||||
```
|
||||
"id": "variant-2" # 缺少说明这会成为 style-2 目录
|
||||
```
|
||||
|
||||
#### consolidate.md
|
||||
|
||||
**问题点**：
|
||||
- ⚠️ `--variants` 与 `extract` 同名但语义不同
|
||||
- ⚠️ 默认行为（处理所有变体）不够突出
|
||||
- ⚠️ `variant-N` → `style-N` 转换未文档化
|
||||
|
||||
#### generate.md
|
||||
|
||||
**问题点**：
|
||||
- ⚠️ `--style-variants` 名称与前置命令不一致
|
||||
- ⚠️ 默认值 `3` 的来源和意义不清晰
|
||||
- ⚠️ 自动检测机制未说明
|
||||
- ❌ 手动覆盖无验证
|
||||
|
||||
**当前文档**（第79-82行）：
|
||||
```bash
|
||||
style_variants = --style-variants OR 3 # Default to 3
|
||||
VALIDATE: 1 <= style_variants <= 5
|
||||
```
|
||||
|
||||
## 💡 改进方案
|
||||
|
||||
### 方案1：代码层面改进（推荐）
|
||||
|
||||
#### 1.1 统一参数命名
|
||||
|
||||
```diff
|
||||
# extract.md
|
||||
- usage: /workflow:ui-design:extract [--variants <count>]
|
||||
+ usage: /workflow:ui-design:extract [--style-variants <count>]
|
||||
|
||||
# consolidate.md
|
||||
- usage: /workflow:ui-design:consolidate [--variants <count>]
|
||||
+ usage: /workflow:ui-design:consolidate [--style-variants <count>]
|
||||
|
||||
# generate.md (保持不变)
|
||||
usage: /workflow:ui-design:generate [--style-variants <count>]
|
||||
```
|
||||
|
||||
**优点**：
|
||||
- ✅ 全链路参数名称统一
|
||||
- ✅ 语义清晰（style-variants）
|
||||
- ✅ 降低混淆风险
|
||||
|
||||
#### 1.2 添加验证逻辑（关键）
|
||||
|
||||
##### generate.md 改进
|
||||
|
||||
```bash
|
||||
# Phase 1: Path Resolution & Context Loading
|
||||
style_variants = --style-variants OR 3 # Default to 3
|
||||
|
||||
# 🆕 添加验证逻辑
|
||||
actual_styles = count_directories({base_path}/style-consolidation/style-*)
|
||||
|
||||
IF actual_styles == 0:
|
||||
ERROR: "No style directories found in {base_path}/style-consolidation/"
|
||||
SUGGEST: "Run /workflow:ui-design:consolidate first"
|
||||
EXIT 1
|
||||
|
||||
IF style_variants > actual_styles:
|
||||
WARN: "⚠️ Requested {style_variants} style variants, but only {actual_styles} directories exist"
|
||||
REPORT: " Auto-correcting to {actual_styles} style variants"
|
||||
REPORT: " Available styles: {list_directories(style-consolidation/style-*)}"
|
||||
style_variants = actual_styles
|
||||
|
||||
VALIDATE: 1 <= style_variants <= actual_styles
|
||||
```
|
||||
|
||||
##### ui-instantiate-prototypes.sh 改进
|
||||
|
||||
在脚本第239行之后添加：
|
||||
|
||||
```bash
|
||||
# Validate STYLE_VARIANTS matches actual directories
|
||||
if [ "$STYLE_VARIANTS" -gt 0 ]; then
|
||||
actual_styles=$(find "$BASE_PATH/../style-consolidation" -maxdepth 1 -type d -name "style-*" 2>/dev/null | wc -l)
|
||||
|
||||
if [ "$actual_styles" -eq 0 ]; then
|
||||
log_error "No style directories found in style-consolidation/"
|
||||
log_info "Run /workflow:ui-design:consolidate first"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [ "$STYLE_VARIANTS" -gt "$actual_styles" ]; then
|
||||
log_warning "Requested $STYLE_VARIANTS style variants, but only found $actual_styles directories"
|
||||
log_info "Auto-correcting to $actual_styles style variants"
|
||||
STYLE_VARIANTS=$actual_styles
|
||||
fi
|
||||
fi
|
||||
```
|
||||
|
||||
#### 1.3 统一命名约定
|
||||
|
||||
##### extract.md 改进
|
||||
|
||||
修改输出格式（第580行附近）：
|
||||
|
||||
```diff
|
||||
# style-cards.json 格式
|
||||
{
|
||||
"style_cards": [
|
||||
{
|
||||
- "id": "variant-1",
|
||||
+ "id": "style-1",
|
||||
"name": "Modern Minimalist",
|
||||
...
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 方案2：文档层面改进
|
||||
|
||||
#### 2.1 extract.md 文档改进
|
||||
|
||||
```markdown
|
||||
## Parameters
|
||||
|
||||
- `--style-variants <count>`: Number of style variants to extract. **Default: 1**
|
||||
- Range: 1-5
|
||||
- Each variant will become an independent design system (style-1, style-2, etc.)
|
||||
- Output IDs use `style-N` format for consistency across the workflow
|
||||
|
||||
## Output Format
|
||||
|
||||
style-cards.json uses `style-N` IDs that directly correspond to directory names
|
||||
created by the consolidate command:
|
||||
|
||||
- `style-1` → `style-consolidation/style-1/`
|
||||
- `style-2` → `style-consolidation/style-2/`
|
||||
```
|
||||
|
||||
#### 2.2 consolidate.md 文档改进
|
||||
|
||||
```markdown
|
||||
## Parameters
|
||||
|
||||
- `--style-variants <count>`: Number of style variants to process from style-cards.json.
|
||||
**Default: all available variants**
|
||||
- Processes the first N variants from the style-cards array
|
||||
- Creates separate `style-{n}` directories for each variant
|
||||
- Range: 1 to count available in style-cards.json
|
||||
|
||||
## Naming Convention
|
||||
|
||||
Variants from extraction are materialized into style directories:
|
||||
- Input: `style-cards.json` with `style-1`, `style-2`, `style-3`
|
||||
- Output: `style-consolidation/style-1/`, `style-2/`, `style-3/` directories
|
||||
```
|
||||
|
||||
#### 2.3 generate.md 文档改进
|
||||
|
||||
```markdown
|
||||
## Parameters
|
||||
|
||||
- `--style-variants <count>`: Number of style variants to generate prototypes for.
|
||||
**Default: 3** (can be overridden)
|
||||
- Range: 1-5
|
||||
- ⚠️ **IMPORTANT**: This value MUST match the number of style-* directories in style-consolidation/
|
||||
- If mismatched, the command will auto-correct to the actual directory count
|
||||
- Use auto-detection (omit parameter) for safety
|
||||
|
||||
## Auto-Detection vs Manual Override
|
||||
|
||||
The command uses intelligent auto-detection:
|
||||
|
||||
1. **Auto-Detection** (Recommended):
|
||||
```bash
|
||||
/workflow:ui-design:generate --base-path ".workflow/.design/run-xxx"
|
||||
# Automatically counts style-1/, style-2/, style-3/ → uses 3
|
||||
```
|
||||
|
||||
2. **Manual Override** (Use with caution):
|
||||
```bash
|
||||
/workflow:ui-design:generate --style-variants 4
|
||||
# If only 3 styles exist, auto-corrects to 3 with warning
|
||||
```
|
||||
|
||||
3. **Safety Check**:
|
||||
- Command validates against actual `style-consolidation/style-*` directories
|
||||
- Prevents generation of prototypes referencing non-existent styles
|
||||
- Displays warning and auto-corrects if mismatch detected
|
||||
```
|
||||
|
||||
### 方案3：用户指南改进
|
||||
|
||||
创建 `.claude/commands/workflow/ui-design/README.md`：
|
||||
|
||||
```markdown
|
||||
# UI Design Workflow Parameter Guide
|
||||
|
||||
## Style Variant Count Flow
|
||||
|
||||
### 1. Extract Phase
|
||||
```bash
|
||||
/workflow:ui-design:extract --style-variants 3
|
||||
# Generates: style-cards.json with 3 style variants (style-1, style-2, style-3)
|
||||
```
|
||||
|
||||
### 2. Consolidate Phase
|
||||
```bash
|
||||
/workflow:ui-design:consolidate --style-variants 3
|
||||
# Creates: style-consolidation/style-1/, style-2/, style-3/
|
||||
```
|
||||
|
||||
### 3. Generate Phase
|
||||
```bash
|
||||
# ✅ Recommended: Let it auto-detect
|
||||
/workflow:ui-design:generate --base-path ".workflow/.design/run-xxx"
|
||||
|
||||
# ⚠️ Manual: Must match consolidation output
|
||||
/workflow:ui-design:generate --style-variants 3
|
||||
```
|
||||
|
||||
## ⚠️ Common Mistakes
|
||||
|
||||
### Mistake 1: Mismatched Counts
|
||||
```bash
|
||||
# ❌ Wrong: Request 4 styles when only 3 exist
|
||||
/workflow:ui-design:generate --style-variants 4
|
||||
# Only 3 directories in style-consolidation/ → ERROR
|
||||
|
||||
# ✅ Correct: Omit parameter for auto-detection
|
||||
/workflow:ui-design:generate --base-path ".workflow/.design/run-xxx"
|
||||
```
|
||||
|
||||
### Mistake 2: Naming Confusion
|
||||
```bash
|
||||
# ❌ Don't confuse variant-N with style-N
|
||||
# variant-N was old naming in style-cards.json
|
||||
# style-N is the current standard across all commands
|
||||
```
|
||||
|
||||
## 🎯 Best Practices
|
||||
|
||||
1. **Use auto-detection**: Omit `--style-variants` in generate command
|
||||
2. **Verify consolidation**: Check `consolidation-report.json` before generating
|
||||
3. **Use explore-auto**: Automated workflow prevents parameter mismatches
|
||||
4. **Check directories**: `ls .workflow/.design/run-xxx/style-consolidation/`
|
||||
```
|
||||
|
||||
## 🎯 实施优先级
|
||||
|
||||
### 🔴 高优先级（立即实施）
|
||||
|
||||
1. **generate.md 添加验证逻辑**
|
||||
- 防止参数不匹配问题再次发生
|
||||
- 影响范围：所有手动调用 generate 命令的场景
|
||||
|
||||
2. **ui-instantiate-prototypes.sh 添加验证**
|
||||
- 脚本层面的最后防线
|
||||
- 影响范围：所有原型生成操作
|
||||
|
||||
3. **文档说明默认值和验证机制**
|
||||
- 降低用户误用风险
|
||||
- 影响范围：所有新用户和手动操作场景
|
||||
|
||||
### 🟡 中优先级（短期改进）
|
||||
|
||||
4. **统一参数命名为 --style-variants**
|
||||
- 提高一致性，减少混淆
|
||||
- 影响范围：需要更新多个命令文件
|
||||
|
||||
5. **extract.md 统一使用 style-N 命名**
|
||||
- 消除命名转换混淆
|
||||
- 影响范围：需要更新 style-cards.json 格式
|
||||
|
||||
### 🟢 低优先级（长期优化）
|
||||
|
||||
6. **创建用户指南 README.md**
|
||||
- 提供完整的参数使用指南
|
||||
- 影响范围：文档层面，不影响功能
|
||||
|
||||
## 📊 改进效果预测
|
||||
|
||||
### 实施前
|
||||
|
||||
```
|
||||
用户手动调用: /workflow:ui-design:generate --style-variants 4
|
||||
实际目录数: 3
|
||||
结果: ❌ 生成 login-style-4-layout-1.html 引用不存在的 CSS
|
||||
```
|
||||
|
||||
### 实施后
|
||||
|
||||
```
|
||||
用户手动调用: /workflow:ui-design:generate --style-variants 4
|
||||
实际目录数: 3
|
||||
|
||||
验证检查:
|
||||
⚠️ Requested 4 style variants, but only 3 directories exist
|
||||
Available: style-1, style-2, style-3
|
||||
Auto-correcting to 3 style variants
|
||||
|
||||
结果: ✅ 生成正确的 style-1, style-2, style-3 原型，避免错误
|
||||
```
|
||||
|
||||
## 🔧 快速修复指南（针对当前问题）
|
||||
|
||||
### 立即修复生成的错误文件
|
||||
|
||||
```bash
|
||||
cd .workflow/.design/run-20251009-210559/prototypes
|
||||
|
||||
# 删除错误的 style-4 文件
|
||||
rm -f *-style-4-*
|
||||
|
||||
# 重新生成（使用自动检测）
|
||||
~/.claude/scripts/ui-instantiate-prototypes.sh . --session-id run-20251009-210559
|
||||
```
|
||||
|
||||
### 预防未来错误
|
||||
|
||||
```bash
|
||||
# ✅ 推荐：使用自动检测
|
||||
/workflow:ui-design:generate --base-path ".workflow/.design/run-xxx"
|
||||
|
||||
# ⚠️ 如果必须手动指定，先验证
|
||||
jq '.variant_count' .workflow/.design/run-xxx/style-consolidation/consolidation-report.json
|
||||
# 输出: 3
|
||||
# 然后使用该数字
|
||||
/workflow:ui-design:generate --style-variants 3
|
||||
```
|
||||
|
||||
## 📝 总结
|
||||
|
||||
**核心问题**：
|
||||
- 参数命名不统一（`--variants` vs `--style-variants`）
|
||||
- 命名转换混淆（`variant-N` → `style-N`）
|
||||
- 验证缺失（不检查参数是否匹配实际目录）
|
||||
- 文档不清晰（默认值、自动检测机制说明不足）
|
||||
|
||||
**关键改进**：
|
||||
1. ✅ 添加参数验证逻辑（防止不匹配）
|
||||
2. ✅ 统一参数命名（提高一致性）
|
||||
3. ✅ 完善文档说明（降低误用风险）
|
||||
4. ✅ 提供清晰的用户指南
|
||||
|
||||
**预期效果**：
|
||||
- 🔒 杜绝参数不匹配问题
|
||||
- 📈 提高工作流鲁棒性
|
||||
- 🎓 降低用户学习成本
|
||||
- 🚀 提升整体用户体验
|
||||
Reference in New Issue
Block a user