diff --git a/.claude/skills/command-guide/SKILL.md b/.claude/skills/command-guide/SKILL.md index 13cc7787..551805a2 100644 --- a/.claude/skills/command-guide/SKILL.md +++ b/.claude/skills/command-guide/SKILL.md @@ -295,7 +295,8 @@ Templates are auto-populated during Mode 5 (Issue Reporting) interaction. When commands are added/modified/removed: ```bash -bash scripts/update-index.sh +cd /d/Claude_dms3/.claude/skills/command-guide +python scripts/analyze_commands.py ``` This script: @@ -307,7 +308,7 @@ This script: ### Committing Updates ```bash -git add .claude/skills/command-guide/index/ +git add .claude/skills/command-guide/ git commit -m "docs: update command indexes" git push ``` @@ -325,23 +326,28 @@ Team members get latest indexes via `git pull`. --- -**Version**: 1.3.1 (Path configuration for global installation) -**Last Updated**: 2025-11-06 +## ๐Ÿ”„ Maintenance + +### Documentation Updates + +This SKILL documentation is kept in sync with command implementations through a standardized update process. + +**Update Guideline**: See [UPDATE-GUIDELINE.md](UPDATE-GUIDELINE.md) for the complete documentation maintenance process. + +**Update Process**: +1. **Analyze**: Identify changed commands/agents from git commits +2. **Extract**: Gather change information and impact assessment +3. **Update**: Sync reference docs, guides, and examples +4. **Regenerate**: Run `scripts/analyze_commands.py` to rebuild indexes +5. **Validate**: Test examples and verify consistency +6. **Commit**: Follow standardized commit message format + +**Key Capabilities**: +- 6 operation modes (Search, Recommendations, Full Docs, Onboarding, Issue Reporting, Deep Analysis) +- 80 reference documentation files (11 agents + 69 commands) +- 5 JSON indexes for fast command lookup +- 8 comprehensive guides covering all workflow patterns +- 4 issue templates for standardized problem reporting +- CLI-assisted complex query analysis with gemini/qwen integration + **Maintainer**: Claude DMS3 Team - -**Changelog v1.3.1**: -- โœ… Updated all paths to use absolute paths (`~/.claude/skills/command-guide/`) -- โœ… CLI commands now use `--include-directories` with absolute reference path -- โœ… Ensures skill works correctly when installed in `~/.claude/skills/` - -**Changelog v1.3.0**: -- โœ… Added Mode 6: Deep Command Analysis with CLI-assisted queries -- โœ… Created reference documentation backup (80 files: 11 agents + 69 commands) -- โœ… Support simple queries (direct file lookup) and complex queries (CLI analysis) -- โœ… Integrated gemini/qwen for cross-command analysis and best practices - -**Changelog v1.2.0**: -- โœ… Added Interactive Diagnosis template with decision tree -- โœ… Enhanced all templates with complete command history sections -- โœ… Added privacy protection guidelines for sensitive information -- โœ… Integrated execution flow emphasis across all issue templates diff --git a/.claude/skills/command-guide/UPDATE-GUIDELINE.md b/.claude/skills/command-guide/UPDATE-GUIDELINE.md new file mode 100644 index 00000000..9cb641df --- /dev/null +++ b/.claude/skills/command-guide/UPDATE-GUIDELINE.md @@ -0,0 +1,592 @@ +# Command Guide Update Guideline + +## ๐Ÿ“‹ Purpose + +This document defines a **standardized, repeatable process** for updating command-guide documentation when command changes are detected. Use this guideline every time you need to update command-guide SKILL documentation to ensure consistency and completeness. + +--- + +## ๐ŸŽฏ Update Trigger Conditions + +Execute this update process when ANY of the following conditions are met: + +1. **New commands added** to `.claude/commands/` +2. **Command parameters changed** (new flags, modified behavior) +3. **Command architecture refactored** (workflow reorganization) +4. **Agent implementations updated** in `.claude/agents/` +5. **User explicitly requests** command-guide update + +--- + +## ๐Ÿ“Š Phase 1: Analysis & Discovery + +### Step 1.1: Identify Changed Files + +**Objective**: Discover what has changed since last update + +**Actions**: +```bash +# Find recent commits affecting commands/agents +git log --oneline --since="" --grep="command\|agent\|workflow" -20 + +# Show detailed changes +git diff .. --stat .claude/commands/ .claude/agents/ + +# Identify modified command files +git diff .. --name-only .claude/commands/ +``` + +**Output**: List of changed files and commit messages + +**Document**: +- Changed command files +- Changed agent files +- Key commit messages +- Change patterns (new features, refactoring, fixes) + +--- + +### Step 1.2: Analyze Change Scope + +**Objective**: Understand the nature and impact of changes + +**Questions to Answer**: +1. **What changed?** (parameters, workflow, architecture, behavior) +2. **Why changed?** (new feature, optimization, bug fix, refactoring) +3. **Impact scope?** (single command, workflow pattern, system-wide) +4. **User-facing?** (affects user commands, internal only) + +**Analysis Matrix**: + +| Change Type | Detection Method | Impact Level | +|-------------|--------------------|--------------| +| **New Parameter** | Diff `argument-hint` field | Medium | +| **Workflow Reorganization** | Multiple command changes | High | +| **Architecture Change** | Agent file changes + command changes | High | +| **Bug Fix** | Single file, small change | Low | +| **New Command** | New file in `.claude/commands/` | Medium-High | + +**Output**: Change classification and impact assessment + +--- + +### Step 1.3: Map Affected Documentation + +**Objective**: Identify which documentation files need updates + +**Mapping Rules**: + +**Command Changes** โ†’ Affects: +- `reference/commands//.md` (copy from source) +- `index/all-commands.json` (regenerate) +- `index/by-category.json` (if new category) +- `guides/ui-design-workflow-guide.md` (if UI workflow affected) +- `guides/workflow-patterns.md` (if workflow pattern changed) + +**Agent Changes** โ†’ Affects: +- `reference/agents/.md` (copy from source) +- `guides/implementation-details.md` (if agent behavior changed) + +**Workflow Reorganization** โ†’ Affects: +- All related command references +- Workflow guides +- Examples in guides + +**Output**: Checklist of files to update + +--- + +## ๐Ÿ”ง Phase 2: Content Preparation + +### Step 2.1: Extract Key Information + +**Objective**: Gather information needed for documentation updates + +**Extract from Git Commits**: +```bash +# Get commit details +git show --stat + +# Extract commit message +git log --format=%B -n 1 +``` + +**Information to Extract**: +1. **Feature Name** (from commit message) +2. **Change Description** (what was added/modified/removed) +3. **Rationale** (why the change was made) +4. **New Parameters** (from diff) +5. **Breaking Changes** (backward compatibility impact) +6. **Usage Examples** (from commit or command file) + +**Output**: Structured data for documentation + +--- + +### Step 2.2: Categorize Changes + +**Objective**: Organize changes into logical categories + +**Categories**: + +1. **Major Features** + - New commands + - New workflows + - Architecture changes + - User-facing feature additions + +2. **Enhancements** + - New parameters + - Improved behavior + - Performance optimizations + - Better error handling + +3. **Refactoring** + - Code reorganization (no user impact) + - Internal structure changes + - Consistency improvements + +4. **Bug Fixes** + - Corrected behavior + - Fixed edge cases + - Parameter validation fixes + +5. **Documentation** + - Updated descriptions + - New examples + - Clarified usage + +**Output**: Changes grouped by category with priority + +--- + +### Step 2.3: Analyze User Impact + +**Objective**: Determine what users need to know + +**User Impact Questions**: +1. **Do existing workflows break?** โ†’ Migration guide needed +2. **Are new features optional?** โ†’ Enhancement documentation +3. **Is behavior significantly different?** โ†’ Usage pattern updates +4. **Do examples need updates?** โ†’ Example refresh required + +**Impact Levels**: +- **Critical** (Breaking changes, migration required) +- **Important** (New features users should adopt) +- **Nice-to-have** (Enhancements, optional) +- **Internal** (No user action needed) + +**Output**: User-facing change summary with impact levels + +--- + +## ๐Ÿ“ Phase 3: Documentation Updates + +### Step 3.1: Update Reference Documentation + +**Objective**: Sync reference docs with source command files + +**Actions**: + +1. **Run Python Script to Sync & Rebuild**: + ```bash + cd /d/Claude_dms3/.claude/skills/command-guide + python scripts/analyze_commands.py + ``` + + This script automatically: + - Deletes existing `reference/` directory + - Copies all agent files from `.claude/agents/` to `reference/agents/` + - Copies all command files from `.claude/commands/` to `reference/commands/` + - Regenerates all 5 index files with updated metadata + +2. **Verify Completeness**: + - Check sync output for file counts (11 agents + 70 commands) + - Verify all 5 index files regenerated successfully + - Ensure YAML frontmatter integrity in copied files + +**Output**: Updated reference documentation matching source + regenerated indexes + +--- + +### Step 3.2: Update Workflow Guides + +**Objective**: Reflect changes in user-facing workflow guides + +**Workflow Guide Update Pattern**: + +**IF** (UI workflow commands changed): +1. Open `guides/ui-design-workflow-guide.md` +2. Locate affected workflow pattern sections +3. Update examples to use new parameters/behavior +4. Add "New!" badges for new features +5. Update performance metrics if applicable +6. Add troubleshooting entries for new issues + +**IF** (General workflow patterns changed): +1. Open `guides/workflow-patterns.md` +2. Update affected workflow examples +3. Add new pattern sections if applicable + +**Update Template for New Features**: +```markdown +### [Feature Name] (New!) + +**Purpose**: [What this feature enables] + +**Usage**: +```bash +[Example command with new feature] +``` + +**Benefits**: +- [Benefit 1] +- [Benefit 2] + +**When to Use**: +- [Use case 1] +- [Use case 2] +``` + +**Output**: Updated workflow guides with new features documented + +--- + +### Step 3.3: Update Examples and Best Practices + +**Objective**: Ensure examples reflect current best practices + +**Example Update Checklist**: +- [ ] Remove deprecated parameter usage +- [ ] Add examples for new parameters +- [ ] Update command syntax if changed +- [ ] Verify all examples are runnable +- [ ] Add "Note" sections for common pitfalls + +**Best Practices Update**: +- [ ] Add recommendations for new features +- [ ] Update "When to Use" guidelines +- [ ] Revise performance optimization tips +- [ ] Update troubleshooting entries + +**Output**: Current, runnable examples + +--- + +### Step 3.4: Update SKILL.md Metadata + +**Objective**: Keep SKILL.md current without version-specific details + +**Update Sections**: + +1. **Supporting Guides** (if new guide added): + ```markdown + - **[New Guide Name](guides/new-guide.md)** - Description + ``` + +2. **System Statistics** (if counts changed): + ```markdown + - **Total Commands**: + - **Total Agents**: + ``` + +3. **Remove Old Changelog Entries**: + - Keep only last 3 changelog entries + - Archive older entries to separate file if needed + +**DO NOT**: +- Add version numbers +- Add specific dates +- Create time-based changelog entries + +**Output**: Updated SKILL.md metadata + +--- + +## ๐Ÿงช Phase 4: Validation + +### Step 4.1: Consistency Check + +**Objective**: Ensure documentation is internally consistent + +**Checklist**: +- [ ] All command references use correct names +- [ ] Parameter descriptions match command files +- [ ] Examples use valid parameter combinations +- [ ] Links between documents are not broken +- [ ] Index files reflect current command count + +**Validation Commands**: +```bash +# Check for broken internal links +grep -r "\[.*\](.*\.md)" guides/ reference/ | grep -v "http" + +# Verify command count consistency +actual=$(find ../../commands -name "*.md" | wc -l) +indexed=$(jq '.commands | length' index/all-commands.json) +echo "Actual: $actual, Indexed: $indexed" +``` + +**Output**: Validation report + +--- + +### Step 4.2: Example Testing + +**Objective**: Verify all examples are runnable + +**Test Cases**: +- [ ] Copy example commands from guides +- [ ] Run in test environment +- [ ] Verify expected output +- [ ] Document any prerequisites + +**Note**: Some examples may be illustrative only; mark these clearly + +**Output**: Tested examples + +--- + +### Step 4.3: Peer Review Checklist + +**Objective**: Prepare documentation for review + +**Review Points**: +- [ ] Is the change clearly explained? +- [ ] Are examples helpful and clear? +- [ ] Is migration guidance complete (if breaking)? +- [ ] Are troubleshooting tips adequate? +- [ ] Is the documentation easy to scan? + +**Output**: Review-ready documentation + +--- + +## ๐Ÿ“ค Phase 5: Commit & Distribution + +### Step 5.1: Git Commit Structure + +**Objective**: Create clear, traceable commits + +**Commit Pattern**: +```bash +git add .claude/skills/command-guide/ + +# Commit message format +git commit -m "docs(command-guide): update for changes + +- Update reference docs for +- Enhance with documentation +- Regenerate indexes (new count: ) +- Add troubleshooting for + +Refs: +" +``` + +**Commit Message Rules**: +- **Type**: `docs(command-guide)` +- **Scope**: Always `command-guide` +- **Summary**: Concise, imperative mood +- **Body**: Bullet points for each change type +- **Refs**: Link to source change commits + +**Output**: Clean commit history + +--- + +### Step 5.2: Update Distribution + +**Objective**: Make updates available to users + +**Actions**: +```bash +# Push to remote +git push origin main + +# Verify GitHub reflects changes +# Check: https://github.com///tree/main/.claude/skills/command-guide +``` + +**User Notification** (if breaking changes): +- Update project README +- Add note to main documentation +- Consider announcement in team channels + +**Output**: Published updates + +--- + +## ๐Ÿ”„ Phase 6: Iteration & Improvement + +### Step 6.1: Gather Feedback + +**Objective**: Improve documentation based on usage + +**Feedback Sources**: +- User questions about changed commands +- Confusion points in examples +- Missing information requests +- Error reports + +**Track**: +- Common questions โ†’ Add to troubleshooting +- Confusing examples โ†’ Simplify or expand +- Missing use cases โ†’ Add to guides + +**Output**: Improvement backlog + +--- + +### Step 6.2: Continuous Refinement + +**Objective**: Keep documentation evolving + +**Regular Tasks**: +- [ ] Review index statistics monthly +- [ ] Update examples with real-world usage +- [ ] Consolidate redundant sections +- [ ] Expand troubleshooting based on issues +- [ ] Refresh screenshots/outputs if UI changed + +**Output**: Living documentation + +--- + +## ๐Ÿ“ Update Decision Matrix + +Use this matrix to determine update depth: + +| Change Scope | Reference Docs | Workflow Guides | Examples | Indexes | Migration Guide | +|--------------|----------------|-----------------|----------|---------|-----------------| +| **New Parameter** | Update command file | Add parameter note | Add usage example | Regenerate | No | +| **Workflow Refactor** | Update all affected | Major revision | Update all examples | Regenerate | If breaking | +| **New Command** | Copy new file | Add workflow pattern | Add examples | Regenerate | No | +| **Architecture Change** | Update all affected | Major revision | Comprehensive update | Regenerate | Yes | +| **Bug Fix** | Update description | Add note if user-visible | Fix incorrect examples | No change | No | +| **New Feature** | Update affected files | Add feature section | Add feature examples | Regenerate | No | + +--- + +## ๐ŸŽฏ Quality Gates + +Before considering documentation update complete, verify: + +### Gate 1: Completeness +- [ ] All changed commands have updated reference docs +- [ ] All new features are documented in guides +- [ ] All examples are current and correct +- [ ] Indexes reflect current state + +### Gate 2: Clarity +- [ ] Non-expert can understand changes +- [ ] Examples demonstrate key use cases +- [ ] Migration path is clear (if breaking) +- [ ] Troubleshooting covers common issues + +### Gate 3: Consistency +- [ ] Terminology is consistent across docs +- [ ] Parameter descriptions match everywhere +- [ ] Cross-references are accurate +- [ ] Formatting follows established patterns + +### Gate 4: Accessibility +- [ ] Table of contents is current +- [ ] Search/navigation works +- [ ] Related docs are linked +- [ ] Issue templates reference new content + +--- + +## ๐Ÿš€ Quick Start Template + +When updates are needed, follow this abbreviated workflow: + +```bash +# 1. ANALYZE (5 min) +git log --oneline --since="" --grep="command\|agent" -20 +# โ†’ Identify what changed + +# 2. EXTRACT (10 min) +git show --stat +git diff ..HEAD --stat .claude/commands/ +# โ†’ Understand changes + +# 3. UPDATE (30 min) +# - Update affected guide sections (ui-design-workflow-guide.md, etc.) +# - Add examples for new features +# - Document parameter changes + +# 4. SYNC & REGENERATE (2 min) +cd /d/Claude_dms3/.claude/skills/command-guide +python scripts/analyze_commands.py +# โ†’ Syncs reference docs + regenerates all 5 indexes + +# 5. VALIDATE (10 min) +# - Test examples +# - Check consistency +# - Verify links + +# 6. COMMIT (5 min) +git add .claude/skills/command-guide/ +git commit -m "docs(command-guide): update for changes" +git push origin main +``` + +**Total Time**: ~1 hour for typical update + +--- + +## ๐Ÿ”— Related Resources + +- **Python Index Script**: `.claude/skills/command-guide/scripts/analyze_commands.py` +- **Issue Templates**: `.claude/skills/command-guide/templates/` +- **SKILL Entry Point**: `.claude/skills/command-guide/SKILL.md` +- **Reference Source**: `.claude/commands/` and `.claude/agents/` + +--- + +## ๐Ÿ“Œ Appendix: Common Patterns + +### Pattern 1: New Parameter Addition + +**Example**: `--interactive` flag added to `explore-auto` + +**Update Sequence**: +1. Update `guides/ui-design-workflow-guide.md` with interactive examples +2. Add "When to Use" guidance +3. Run Python script to sync reference docs and regenerate indexes +4. Update argument-hint in examples + +--- + +### Pattern 2: Workflow Reorganization + +**Example**: Layout extraction split into concept generation + selection + +**Update Sequence**: +1. Major revision of workflow guide section +2. Update all workflow examples +3. Add migration notes for existing users +4. Update troubleshooting +5. Run Python script to sync and regenerate indexes + +--- + +### Pattern 3: Architecture Change + +**Example**: Agent execution model changed + +**Update Sequence**: +1. Update `guides/implementation-details.md` +2. Revise all workflow patterns using affected agents +3. Create migration guide +4. Update examples comprehensively +5. Run Python script to sync and regenerate indexes +6. Add extensive troubleshooting + +--- + +**End of Update Guideline** + +This guideline is a living document. Improve it based on update experience. diff --git a/.claude/skills/command-guide/guides/ui-design-workflow-guide.md b/.claude/skills/command-guide/guides/ui-design-workflow-guide.md index 0c2a2e9f..d509ec7c 100644 --- a/.claude/skills/command-guide/guides/ui-design-workflow-guide.md +++ b/.claude/skills/command-guide/guides/ui-design-workflow-guide.md @@ -55,7 +55,7 @@ Tools for combining components and integrating results. 4. **Assembly**: System generates a matrix of prototypes (3 styles ร— 1 layout = 3 prototypes). 5. **Review**: User views `compare.html` to select the best direction. -**Example:** +**Example (Non-Interactive - Default):** ```bash /workflow:ui-design:explore-auto \ @@ -71,6 +71,30 @@ Tools for combining components and integrating results. - 6 HTML prototypes (3 ร— 2 combinations) - `compare.html` for side-by-side comparison +**Example (Interactive Mode):** + +```bash +/workflow:ui-design:explore-auto \ + --prompt "Modern SaaS landing page with hero, features, pricing sections" \ + --style-variants 5 \ + --layout-variants 4 \ + --interactive \ + --session WFS-001 +``` + +**Interactive Flow:** +1. System generates 5 style concepts +2. **User selects** 2-3 preferred styles (multi-select) +3. System generates 4 layout concepts +4. **User selects** 2 preferred layouts (multi-select) +5. System generates only 4-6 final prototypes (selected combinations) + +**Benefits:** +- Reduces unnecessary generation (from 20 to 4-6 prototypes) +- Focuses resources on preferred design directions +- Saves 70-80% computation time +- Better exploration quality + --- ### Workflow B: Design Replication (Imitation) diff --git a/.claude/skills/command-guide/index/all-commands.json b/.claude/skills/command-guide/index/all-commands.json index cc1e4be7..b53bd1b1 100644 --- a/.claude/skills/command-guide/index/all-commands.json +++ b/.claude/skills/command-guide/index/all-commands.json @@ -685,7 +685,7 @@ "name": "explore-auto", "command": "/workflow:ui-design:explore-auto", "description": "Exploratory UI design workflow with style-centric batch generation, creates design variants from prompts/images with parallel execution", - "arguments": "[--prompt \"\"] [--images \"\"] [--targets \"\"] [--target-type \"page|component\"] [--session ] [--style-variants ] [--layout-variants ] [--batch-plan]", + "arguments": "[--prompt \"\"] [--images \"\"] [--targets \"\"] [--target-type \"page|component\"] [--session ] [--style-variants ] [--layout-variants ] [--interactive] [--batch-plan]", "category": "workflow", "subcategory": "ui-design", "usage_scenario": "general", @@ -707,7 +707,7 @@ "name": "generate", "command": "/workflow:ui-design:generate", "description": "Assemble UI prototypes by combining layout templates with design tokens, pure assembler without new content generation", - "arguments": "[--base-path ] [--session ] [--style-variants ] [--layout-variants ]", + "arguments": "[--base-path ] [--session ]", "category": "workflow", "subcategory": "ui-design", "usage_scenario": "implementation", @@ -729,7 +729,7 @@ "name": "workflow:ui-design:import-from-code", "command": "/workflow:ui-design:import-from-code", "description": "Import design system from code files (CSS/JS/HTML/SCSS) using parallel agent analysis with final synthesis", - "arguments": "[--source-path ] [--output-path ] [--css \\\"\\\"] [--js \\\"\\\"] [--scss \\\"\\\"] [--html \\\"\\\"] [--style-files \\\"\\\"] [--session ]", + "arguments": "[--base-path ] [--source ] [--css \\\"\\\"] [--js \\\"\\\"] [--scss \\\"\\\"] [--html \\\"\\\"] [--style-files \\\"\\\"] [--session ]", "category": "workflow", "subcategory": "ui-design", "usage_scenario": "planning", @@ -740,7 +740,7 @@ "name": "layout-extract", "command": "/workflow:ui-design:layout-extract", "description": "Extract structural layout information from reference images, URLs, or text prompts using Claude analysis", - "arguments": "[--base-path ] [--session ] [--images \"\"] [--urls \"\"] [--prompt \"\"] [--targets \"\"] [--variants ] [--device-type ]", + "arguments": "[--base-path ] [--session ] [--images \"\"] [--urls \"\"] [--prompt \"\"] [--targets \"\"] [--variants ] [--device-type ] [--interactive]", "category": "workflow", "subcategory": "ui-design", "usage_scenario": "general", @@ -751,7 +751,7 @@ "name": "style-extract", "command": "/workflow:ui-design:style-extract", "description": "Extract design style from reference images or text prompts using Claude analysis with variant generation", - "arguments": "[--base-path ] [--session ] [--images \"\"] [--urls \"\"] [--prompt \"\"] [--variants ]", + "arguments": "[--base-path ] [--session ] [--images \"\"] [--urls \"\"] [--prompt \"\"] [--variants ] [--interactive]", "category": "workflow", "subcategory": "ui-design", "usage_scenario": "general", diff --git a/.claude/skills/command-guide/index/by-category.json b/.claude/skills/command-guide/index/by-category.json index 3c9c523d..959eb982 100644 --- a/.claude/skills/command-guide/index/by-category.json +++ b/.claude/skills/command-guide/index/by-category.json @@ -713,7 +713,7 @@ "name": "explore-auto", "command": "/workflow:ui-design:explore-auto", "description": "Exploratory UI design workflow with style-centric batch generation, creates design variants from prompts/images with parallel execution", - "arguments": "[--prompt \"\"] [--images \"\"] [--targets \"\"] [--target-type \"page|component\"] [--session ] [--style-variants ] [--layout-variants ] [--batch-plan]", + "arguments": "[--prompt \"\"] [--images \"\"] [--targets \"\"] [--target-type \"page|component\"] [--session ] [--style-variants ] [--layout-variants ] [--interactive] [--batch-plan]", "category": "workflow", "subcategory": "ui-design", "usage_scenario": "general", @@ -735,7 +735,7 @@ "name": "generate", "command": "/workflow:ui-design:generate", "description": "Assemble UI prototypes by combining layout templates with design tokens, pure assembler without new content generation", - "arguments": "[--base-path ] [--session ] [--style-variants ] [--layout-variants ]", + "arguments": "[--base-path ] [--session ]", "category": "workflow", "subcategory": "ui-design", "usage_scenario": "implementation", @@ -757,7 +757,7 @@ "name": "workflow:ui-design:import-from-code", "command": "/workflow:ui-design:import-from-code", "description": "Import design system from code files (CSS/JS/HTML/SCSS) using parallel agent analysis with final synthesis", - "arguments": "[--source-path ] [--output-path ] [--css \\\"\\\"] [--js \\\"\\\"] [--scss \\\"\\\"] [--html \\\"\\\"] [--style-files \\\"\\\"] [--session ]", + "arguments": "[--base-path ] [--source ] [--css \\\"\\\"] [--js \\\"\\\"] [--scss \\\"\\\"] [--html \\\"\\\"] [--style-files \\\"\\\"] [--session ]", "category": "workflow", "subcategory": "ui-design", "usage_scenario": "planning", @@ -768,7 +768,7 @@ "name": "layout-extract", "command": "/workflow:ui-design:layout-extract", "description": "Extract structural layout information from reference images, URLs, or text prompts using Claude analysis", - "arguments": "[--base-path ] [--session ] [--images \"\"] [--urls \"\"] [--prompt \"\"] [--targets \"\"] [--variants ] [--device-type ]", + "arguments": "[--base-path ] [--session ] [--images \"\"] [--urls \"\"] [--prompt \"\"] [--targets \"\"] [--variants ] [--device-type ] [--interactive]", "category": "workflow", "subcategory": "ui-design", "usage_scenario": "general", @@ -779,7 +779,7 @@ "name": "style-extract", "command": "/workflow:ui-design:style-extract", "description": "Extract design style from reference images or text prompts using Claude analysis with variant generation", - "arguments": "[--base-path ] [--session ] [--images \"\"] [--urls \"\"] [--prompt \"\"] [--variants ]", + "arguments": "[--base-path ] [--session ] [--images \"\"] [--urls \"\"] [--prompt \"\"] [--variants ] [--interactive]", "category": "workflow", "subcategory": "ui-design", "usage_scenario": "general", diff --git a/.claude/skills/command-guide/index/by-use-case.json b/.claude/skills/command-guide/index/by-use-case.json index 59249f07..e7e92ad7 100644 --- a/.claude/skills/command-guide/index/by-use-case.json +++ b/.claude/skills/command-guide/index/by-use-case.json @@ -314,7 +314,7 @@ "name": "explore-auto", "command": "/workflow:ui-design:explore-auto", "description": "Exploratory UI design workflow with style-centric batch generation, creates design variants from prompts/images with parallel execution", - "arguments": "[--prompt \"\"] [--images \"\"] [--targets \"\"] [--target-type \"page|component\"] [--session ] [--style-variants ] [--layout-variants ] [--batch-plan]", + "arguments": "[--prompt \"\"] [--images \"\"] [--targets \"\"] [--target-type \"page|component\"] [--session ] [--style-variants ] [--layout-variants ] [--interactive] [--batch-plan]", "category": "workflow", "subcategory": "ui-design", "usage_scenario": "general", @@ -347,7 +347,7 @@ "name": "layout-extract", "command": "/workflow:ui-design:layout-extract", "description": "Extract structural layout information from reference images, URLs, or text prompts using Claude analysis", - "arguments": "[--base-path ] [--session ] [--images \"\"] [--urls \"\"] [--prompt \"\"] [--targets \"\"] [--variants ] [--device-type ]", + "arguments": "[--base-path ] [--session ] [--images \"\"] [--urls \"\"] [--prompt \"\"] [--targets \"\"] [--variants ] [--device-type ] [--interactive]", "category": "workflow", "subcategory": "ui-design", "usage_scenario": "general", @@ -358,7 +358,7 @@ "name": "style-extract", "command": "/workflow:ui-design:style-extract", "description": "Extract design style from reference images or text prompts using Claude analysis with variant generation", - "arguments": "[--base-path ] [--session ] [--images \"\"] [--urls \"\"] [--prompt \"\"] [--variants ]", + "arguments": "[--base-path ] [--session ] [--images \"\"] [--urls \"\"] [--prompt \"\"] [--variants ] [--interactive]", "category": "workflow", "subcategory": "ui-design", "usage_scenario": "general", @@ -503,7 +503,7 @@ "name": "generate", "command": "/workflow:ui-design:generate", "description": "Assemble UI prototypes by combining layout templates with design tokens, pure assembler without new content generation", - "arguments": "[--base-path ] [--session ] [--style-variants ] [--layout-variants ]", + "arguments": "[--base-path ] [--session ]", "category": "workflow", "subcategory": "ui-design", "usage_scenario": "implementation", @@ -615,7 +615,7 @@ "name": "workflow:ui-design:import-from-code", "command": "/workflow:ui-design:import-from-code", "description": "Import design system from code files (CSS/JS/HTML/SCSS) using parallel agent analysis with final synthesis", - "arguments": "[--source-path ] [--output-path ] [--css \\\"\\\"] [--js \\\"\\\"] [--scss \\\"\\\"] [--html \\\"\\\"] [--style-files \\\"\\\"] [--session ]", + "arguments": "[--base-path ] [--source ] [--css \\\"\\\"] [--js \\\"\\\"] [--scss \\\"\\\"] [--html \\\"\\\"] [--style-files \\\"\\\"] [--session ]", "category": "workflow", "subcategory": "ui-design", "usage_scenario": "planning", diff --git a/.claude/skills/command-guide/reference/commands/workflow/ui-design/animation-extract.md b/.claude/skills/command-guide/reference/commands/workflow/ui-design/animation-extract.md index 75d6a343..0206207e 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/ui-design/animation-extract.md +++ b/.claude/skills/command-guide/reference/commands/workflow/ui-design/animation-extract.md @@ -2,7 +2,7 @@ name: animation-extract description: Extract animation and transition patterns from URLs, CSS, or interactive questioning for design system documentation argument-hint: "[--base-path ] [--session ] [--urls ""] [--mode ] [--focus ""]" -allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), Bash(*), Task(ui-design-agent), mcp__chrome-devtools__navigate_page(*), mcp__chrome-devtools__evaluate_script(*) +allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), Bash(*), AskUserQuestion(*), Task(ui-design-agent), mcp__chrome-devtools__navigate_page(*), mcp__chrome-devtools__evaluate_script(*) --- # Animation Extraction Command @@ -51,7 +51,7 @@ ELSE: focus_types = ["all"] # Extract all animation types # Determine base path (auto-detect and convert to absolute) -relative_path=$(find .workflow -type d -name "design-run-*" | head -1) +relative_path=$(find .workflow -type d -name "design-run-*" -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2) base_path=$(cd "$relative_path" && pwd) bash(test -d "$base_path" && echo "โœ“ Base path: $base_path" || echo "โœ— Path not found") # OR use --base-path / --session parameters @@ -692,6 +692,32 @@ Task(ui-design-agent): ` **Phase 3 Output**: `animation-tokens.json` + `animation-guide.md` +### Step 3: Store User Selection Metadata (If Interactive Mode Used) + +```bash +# If interactive mode was used, save selection metadata for orchestrator +IF extraction_mode == "interactive" AND exists({base_path}/.intermediates/animation-analysis/animation-specification.json): + # Create user-selections directory + bash(mkdir -p {base_path}/.intermediates/user-selections) + + # Read specification to extract metadata + specification = Read({base_path}/.intermediates/animation-analysis/animation-specification.json) + + # Create selection metadata (for orchestrator compatibility) + selection_metadata = { + "metadata": { + "selected_at": NOW(), + "selection_type": "interactive_questionnaire", + "mode": "interactive" + }, + "selected_variants": [1], // Always 1 for interactive mode (single result) + "specification": specification.metadata + } + + # Write to standardized selection file + Write({base_path}/.intermediates/user-selections/animation-extract-selection.json, JSON.stringify(selection_metadata, indent=2)) +``` + ## Phase 4: Verify Output ### Step 1: Check Files Created diff --git a/.claude/skills/command-guide/reference/commands/workflow/ui-design/capture.md b/.claude/skills/command-guide/reference/commands/workflow/ui-design/capture.md index f1fa7b0b..9ca4d5dd 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/ui-design/capture.md +++ b/.claude/skills/command-guide/reference/commands/workflow/ui-design/capture.md @@ -21,7 +21,7 @@ Batch screenshot tool with MCP-first strategy and multi-tier fallback. Processes relative_path=$(if [ -n "$BASE_PATH" ]; then echo "$BASE_PATH" elif [ -n "$SESSION_ID" ]; then - find .workflow/WFS-$SESSION_ID/design-* -type d | head -1 || \ + find .workflow/WFS-$SESSION_ID/design-* -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2 || \ echo ".workflow/WFS-$SESSION_ID/design-run-$(date +%Y%m%d)-$RANDOM" else echo ".workflow/.design/design-run-$(date +%Y%m%d)-$RANDOM" diff --git a/.claude/skills/command-guide/reference/commands/workflow/ui-design/explore-auto.md b/.claude/skills/command-guide/reference/commands/workflow/ui-design/explore-auto.md index e75bbc2a..365b264f 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/ui-design/explore-auto.md +++ b/.claude/skills/command-guide/reference/commands/workflow/ui-design/explore-auto.md @@ -1,7 +1,7 @@ --- name: explore-auto description: Exploratory UI design workflow with style-centric batch generation, creates design variants from prompts/images with parallel execution -argument-hint: "[--prompt ""] [--images ""] [--targets ""] [--target-type "page|component"] [--session ] [--style-variants ] [--layout-variants ] [--batch-plan]"" +argument-hint: "[--prompt ""] [--images ""] [--targets ""] [--target-type "page|component"] [--session ] [--style-variants ] [--layout-variants ] [--interactive] [--batch-plan]"" allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*), Task(conceptual-planning-agent) --- @@ -60,6 +60,7 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(* - `--prompt ""`: Design style and target description - `--style-variants `: Style variants (default: inferred from prompt or 3, range: 1-5) - `--layout-variants `: Layout variants per style (default: inferred or 3, range: 1-5) +- `--interactive`: Enable interactive multi-selection mode for variants (default: false - non-interactive batch generation) - `--batch-plan`: Auto-generate implementation tasks after design-update **Legacy Parameters** (maintained for backward compatibility): @@ -154,6 +155,11 @@ ELSE: layout_variants = --layout-variants OR 3 VALIDATE: 1 <= style_variants <= 5, 1 <= layout_variants <= 5 + +# Interactive mode (default: disabled - non-interactive batch generation) +interactive_mode = --interactive !== undefined ? --interactive : false # Default to false + +REPORT: "๐ŸŽฏ Interactive mode: {interactive_mode ? 'enabled' : 'disabled'}" ``` ### Phase 0a-2: Device Type Inference @@ -310,7 +316,7 @@ detect_target_type(target_list): ```bash IF design_source IN ["code_only", "hybrid"]: REPORT: "๐Ÿ” Phase 0d: Code Import ({design_source})" - command = "/workflow:ui-design:import-from-code --base-path \"{base_path}\" --base-path \"{code_base_path}\"" + command = "/workflow:ui-design:import-from-code --base-path \"{base_path}\" --source \"{code_base_path}\"" SlashCommand(command) # Check file existence and assess completeness @@ -390,7 +396,8 @@ IF design_source == "visual_only" OR needs_visual_supplement: command = "/workflow:ui-design:style-extract --base-path \"{base_path}\" " + (--images ? "--images \"{images}\" " : "") + (--prompt ? "--prompt \"{prompt}\" " : "") + - "--variants {style_variants}" + "--variants {style_variants}" + + (interactive_mode ? " --interactive" : "") SlashCommand(command) ELSE: REPORT: "โœ… Phase 1: Style (Using Code Import)" @@ -419,7 +426,8 @@ IF (design_source == "visual_only" OR needs_visual_supplement) OR (NOT layout_co command = "/workflow:ui-design:layout-extract --base-path \"{base_path}\" " + (--images ? "--images \"{images}\" " : "") + (--prompt ? "--prompt \"{prompt}\" " : "") + - "--targets \"{targets_string}\" --variants {layout_variants} --device-type \"{device_type}\"" + "--targets \"{targets_string}\" --variants {layout_variants} --device-type \"{device_type}\"" + + (interactive_mode ? " --interactive" : "") SlashCommand(command) ELSE: REPORT: "โœ… Phase 2.5: Layout (Using Code Import)" @@ -427,8 +435,7 @@ ELSE: ### Phase 3: UI Assembly ```bash -command = "/workflow:ui-design:generate --base-path \"{base_path}\" " + - "--style-variants {style_variants} --layout-variants {layout_variants}" +command = "/workflow:ui-design:generate --base-path \"{base_path}\"" total = style_variants ร— layout_variants ร— len(inferred_target_list) diff --git a/.claude/skills/command-guide/reference/commands/workflow/ui-design/explore-layers.md b/.claude/skills/command-guide/reference/commands/workflow/ui-design/explore-layers.md index bd09b03c..4d71c632 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/ui-design/explore-layers.md +++ b/.claude/skills/command-guide/reference/commands/workflow/ui-design/explore-layers.md @@ -41,7 +41,7 @@ IF depth NOT IN [1, 2, 3, 4, 5]: relative_path=$(if [ -n "$BASE_PATH" ]; then echo "$BASE_PATH" elif [ -n "$SESSION_ID" ]; then - find .workflow/WFS-$SESSION_ID/design-* -type d | head -1 || \ + find .workflow/WFS-$SESSION_ID/design-* -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2 || \ echo ".workflow/WFS-$SESSION_ID/design-run-$(date +%Y%m%d)-$RANDOM" else echo ".workflow/.design/design-run-$(date +%Y%m%d)-$RANDOM" diff --git a/.claude/skills/command-guide/reference/commands/workflow/ui-design/generate.md b/.claude/skills/command-guide/reference/commands/workflow/ui-design/generate.md index 1a603157..752b8dd0 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/ui-design/generate.md +++ b/.claude/skills/command-guide/reference/commands/workflow/ui-design/generate.md @@ -1,7 +1,7 @@ --- name: generate description: Assemble UI prototypes by combining layout templates with design tokens, pure assembler without new content generation -argument-hint: [--base-path ] [--session ] [--style-variants ] [--layout-variants ] +argument-hint: [--base-path ] [--session ] allowed-tools: TodoWrite(*), Read(*), Write(*), Task(ui-design-agent), Bash(*) --- @@ -11,7 +11,7 @@ allowed-tools: TodoWrite(*), Read(*), Write(*), Task(ui-design-agent), Bash(*) Pure assembler that combines pre-extracted layout templates with design tokens to generate UI prototypes (`style ร— layout ร— targets`). No layout design logic - purely combines existing components. **Strategy**: Pure Assembly -- **Input**: `layout-templates.json` + `design-tokens.json` (+ reference images if available) +- **Input**: `layout-*.json` files + `design-tokens.json` (+ reference images if available) - **Process**: Combine structure (DOM) with style (tokens) - **Output**: Complete HTML/CSS prototypes - **No Design Logic**: All layout and style decisions already made @@ -25,8 +25,8 @@ Pure assembler that combines pre-extracted layout templates with design tokens t ### Step 1: Resolve Base Path & Parse Configuration ```bash -# Determine working directory (relative path) -relative_path=$(find .workflow -type d -name "design-run-*" | head -1) +# Determine working directory (relative path - finds latest) +relative_path=$(find .workflow -type d -name "design-run-*" -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2) # Convert to absolute path base_path=$(cd "$relative_path" && pwd) @@ -42,12 +42,18 @@ bash(ls "$base_path"/style-extraction/style-* -d | wc -l) ### Step 2: Load Layout Templates ```bash -# Check layout templates exist -bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists") +# Check layout templates exist (multi-file pattern) +bash(find {base_path}/layout-extraction -name "layout-*.json" -print -quit | grep -q . && echo "exists") -# Load layout templates -Read({base_path}/layout-extraction/layout-templates.json) -# Extract: targets, layout_variants count, device_type, template structures +# Get list of all layout files +bash(ls {base_path}/layout-extraction/layout-*.json 2>/dev/null) + +# Load each layout template file +FOR each layout_file in layout_files: + template_data = Read(layout_file) + # Extract: target, variant_id, device_type, dom_structure, css_layout_rules + +# Aggregate: targets[], layout_variants count, device_type, all template structures ``` **Output**: `base_path`, `style_variants`, `layout_templates[]`, `targets[]`, `device_type` @@ -99,9 +105,9 @@ Task(ui-design-agent): ` ## Inputs (READ ONLY - NO DESIGN DECISIONS) 1. Layout Template: - Read("{base_path}/layout-extraction/layout-templates.json") - Find template where: target={target} AND variant_id="layout-{layout_id}" - Extract: dom_structure, css_layout_rules, device_type, source_image_path + Read("{base_path}/layout-extraction/layout-{target}-{layout_id}.json") + This file contains the specific layout template for this target and variant. + Extract: dom_structure, css_layout_rules, device_type, source_image_path (from template field) 2. Design Tokens: Read("{base_path}/style-extraction/style-{style_id}/design-tokens.json") @@ -229,7 +235,7 @@ TodoWrite({todos: [ Configuration: - Style Variants: {style_variants} -- Layout Variants: {layout_variants} (from layout-templates.json) +- Layout Variants: {layout_variants} (from layout-*.json files) - Device Type: {device_type} - Targets: {targets} - Total Prototypes: {S ร— L ร— T} @@ -248,14 +254,15 @@ Quality: Generated Files: {base_path}/prototypes/ -โ”œโ”€โ”€ _templates/ -โ”‚ โ””โ”€โ”€ layout-templates.json (input, pre-extracted) โ”œโ”€โ”€ {target}-style-{s}-layout-{l}.html ({Sร—Lร—T} prototypes) โ”œโ”€โ”€ {target}-style-{s}-layout-{l}.css โ”œโ”€โ”€ compare.html (interactive matrix) โ”œโ”€โ”€ index.html (navigation) โ””โ”€โ”€ PREVIEW.md (instructions) +Input Files (from layout-extraction/): +โ”œโ”€โ”€ layout-{target}-{variant}.json (multiple files, one per target-variant combination) + Preview: 1. Open compare.html (recommended) 2. Open index.html @@ -277,8 +284,11 @@ bash(ls {base_path}/style-extraction/style-* -d | wc -l) ### Validation Commands ```bash -# Check layout templates exist -bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists") +# Check layout templates exist (multi-file pattern) +bash(find {base_path}/layout-extraction -name "layout-*.json" -print -quit | grep -q . && echo "exists") + +# Count layout files +bash(ls {base_path}/layout-extraction/layout-*.json 2>/dev/null | wc -l) # Check design tokens exist bash(test -f {base_path}/style-extraction/style-1/design-tokens.json && echo "valid") @@ -304,10 +314,10 @@ bash(~/.claude/scripts/ui-generate-preview.sh "{base_path}/prototypes") ``` {base_path}/ โ”œโ”€โ”€ layout-extraction/ -โ”‚ โ””โ”€โ”€ layout-templates.json # Input (from layout-extract) +โ”‚ โ””โ”€โ”€ layout-{target}-{variant}.json # Input (multiple files from layout-extract) โ”œโ”€โ”€ style-extraction/ โ”‚ โ””โ”€โ”€ style-{s}/ -โ”‚ โ”œโ”€โ”€ design-tokens.json # Input (from style-extract) +โ”‚ โ”œโ”€โ”€ design-tokens.json # Input (from style-extract) โ”‚ โ””โ”€โ”€ style-guide.md โ””โ”€โ”€ prototypes/ โ”œโ”€โ”€ {target}-style-{s}-layout-{l}.html # Assembled prototypes @@ -336,7 +346,7 @@ ERROR: Script permission denied ### Recovery Strategies - **Partial success**: Keep successful assembly combinations -- **Invalid template structure**: Validate layout-templates.json +- **Invalid template structure**: Validate layout-*.json files - **Invalid tokens**: Validate design-tokens.json structure ## Quality Checklist @@ -362,8 +372,8 @@ ERROR: Script permission denied **Prerequisites**: - `/workflow:ui-design:style-extract` โ†’ `design-tokens.json` + `style-guide.md` -- `/workflow:ui-design:layout-extract` โ†’ `layout-templates.json` +- `/workflow:ui-design:layout-extract` โ†’ `layout-{target}-{variant}.json` files -**Input**: `layout-templates.json` + `design-tokens.json` +**Input**: `layout-*.json` files + `design-tokens.json` **Output**: Sร—Lร—T prototypes for `/workflow:ui-design:update` **Called by**: `/workflow:ui-design:explore-auto`, `/workflow:ui-design:imitate-auto` diff --git a/.claude/skills/command-guide/reference/commands/workflow/ui-design/imitate-auto.md b/.claude/skills/command-guide/reference/commands/workflow/ui-design/imitate-auto.md index 6a63f65a..d3bb9c67 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/ui-design/imitate-auto.md +++ b/.claude/skills/command-guide/reference/commands/workflow/ui-design/imitate-auto.md @@ -225,8 +225,8 @@ IF design_source == "hybrid": REPORT: " โ†’ Source: {code_base_path}" REPORT: " โ†’ Mode: Hybrid (Web + Code)" - command = "/workflow:ui-design:import-from-code --output-path \"{base_path}\" " + - "--source-path \"{code_base_path}\"" + command = "/workflow:ui-design:import-from-code --base-path \"{base_path}\" " + + "--source \"{code_base_path}\"" TRY: SlashCommand(command) @@ -408,7 +408,7 @@ ELSE: extraction_prompt = f"Extract visual style tokens from '{primary_target}' with consistency across all pages." url_map_for_extract = ",".join([f"{name}:{url}" for name, url in url_map.items()]) - extract_command = f"/workflow:ui-design:style-extract --base-path \"{base_path}\" --images \"{images_glob}\" --urls \"{url_map_for_extract}\" --prompt \"{extraction_prompt}\" --variants 1" + extract_command = f"/workflow:ui-design:style-extract --base-path \"{base_path}\" --images \"{images_glob}\" --urls \"{url_map_for_extract}\" --prompt \"{extraction_prompt}\" --variants 1 --interactive" SlashCommand(extract_command) TodoWrite(mark_completed: "Extract style", mark_in_progress: "Extract animation") @@ -439,7 +439,7 @@ IF skip_layout: ELSE: REPORT: "๐Ÿš€ Phase 2.5: Layout Extraction" url_map_for_layout = ",".join([f"{target}:{url}" for target, url in url_map.items()]) - layout_extract_command = f"/workflow:ui-design:layout-extract --base-path \"{base_path}\" --images \"{images_glob}\" --urls \"{url_map_for_layout}\" --targets \"{','.join(target_names)}\" --variants 1" + layout_extract_command = f"/workflow:ui-design:layout-extract --base-path \"{base_path}\" --images \"{images_glob}\" --urls \"{url_map_for_layout}\" --targets \"{','.join(target_names)}\" --variants 1 --interactive" SlashCommand(layout_extract_command) TodoWrite(mark_completed: "Extract layout", mark_in_progress: "Assemble UI") diff --git a/.claude/skills/command-guide/reference/commands/workflow/ui-design/import-from-code.md b/.claude/skills/command-guide/reference/commands/workflow/ui-design/import-from-code.md index b5d25779..eb4d2638 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/ui-design/import-from-code.md +++ b/.claude/skills/command-guide/reference/commands/workflow/ui-design/import-from-code.md @@ -1,7 +1,7 @@ --- name: workflow:ui-design:import-from-code description: Import design system from code files (CSS/JS/HTML/SCSS) using parallel agent analysis with final synthesis -argument-hint: "[--source-path ] [--output-path ] [--css \"\"] [--js \"\"] [--scss \"\"] [--html \"\"] [--style-files \"\"] [--session ]" +argument-hint: "[--base-path ] [--source ] [--css \"\"] [--js \"\"] [--scss \"\"] [--html \"\"] [--style-files \"\"] [--session ]" allowed-tools: Read,Write,Bash,Glob,Grep,Task,TodoWrite auto-continue: true --- @@ -34,8 +34,8 @@ Extract design system tokens from source code files (CSS/SCSS/JS/TS/HTML) using /workflow:ui-design:import-from-code [FLAGS] # Flags ---source-path Source code directory to analyze (default: current directory) ---output-path Output directory for extracted design tokens (default: current directory) +--base-path Output directory for extracted design tokens (default: current directory) +--source Source code directory to analyze (default: base-path) --css "" CSS file glob pattern (e.g., "theme/*.css") --scss "" SCSS file glob pattern (e.g., "styles/*.scss") --js "" JavaScript file glob pattern (e.g., "theme/*.js") @@ -48,19 +48,19 @@ Extract design system tokens from source code files (CSS/SCSS/JS/TS/HTML) using ```bash # Basic usage - auto-discover all files -/workflow:ui-design:import-from-code --source-path ./src --output-path ./design-system +/workflow:ui-design:import-from-code --base-path ./design-system --source ./src # Target specific directories -/workflow:ui-design:import-from-code --source-path ./src --output-path ./design-system --css "theme/*.css" --js "theme/*.js" +/workflow:ui-design:import-from-code --base-path ./design-system --source ./src --css "theme/*.css" --js "theme/*.js" # Tailwind config only (output to current directory) -/workflow:ui-design:import-from-code --source-path ./ --js "tailwind.config.js" +/workflow:ui-design:import-from-code --source ./ --js "tailwind.config.js" # CSS framework import -/workflow:ui-design:import-from-code --source-path ./src --output-path ./design-system --css "styles/**/*.scss" --html "components/**/*.html" +/workflow:ui-design:import-from-code --base-path ./design-system --source ./src --css "styles/**/*.scss" --html "components/**/*.html" # Universal style files -/workflow:ui-design:import-from-code --source-path ./src --output-path ./design-system --style-files "**/theme.*" +/workflow:ui-design:import-from-code --base-path ./design-system --source ./src --style-files "**/theme.*" ``` --- @@ -75,12 +75,12 @@ Extract design system tokens from source code files (CSS/SCSS/JS/TS/HTML) using ```bash # 1. Initialize directories -source_path="${source_path:-.}" -output_path="${output_path:-.}" -intermediates_dir="${output_path}/.intermediates/import-analysis" +base_path="${base_path:-.}" +source="${source:-$base_path}" +intermediates_dir="${base_path}/.intermediates/import-analysis" mkdir -p "$intermediates_dir" -echo "[Phase 0] File Discovery Started (source: $source_path, output: $output_path)" +echo "[Phase 0] File Discovery Started (source: $source, output: $base_path)" ``` @@ -97,7 +97,7 @@ echo "[Phase 0] File Discovery Started (source: $source_path, output: $output_pa ```bash # 2. Discover files by type -cd "$source_path" || exit 1 +cd "$source" || exit 1 # CSS files if [ -n "$css" ]; then @@ -183,7 +183,7 @@ Task(ui-design-agent): ` [STYLE_TOKENS_EXTRACTION] Extract visual design tokens (colors, typography, spacing, shadows, borders) from ALL file types - MODE: style-extraction | SOURCE_PATH: ${source_path} | OUTPUT_PATH: ${output_path} + MODE: style-extraction | SOURCE: ${source} | BASE_PATH: ${base_path} ## Input Files (Can reference ANY file type) @@ -210,7 +210,7 @@ Task(ui-design-agent): ` ## Output Requirements - Generate 2 files in ${output_path}/style-extraction/style-1/: + Generate 2 files in ${base_path}/style-extraction/style-1/: 1. design-tokens.json (production-ready design tokens) 2. style-guide.md (design philosophy and usage guide) @@ -359,13 +359,13 @@ Task(ui-design-agent): ` ## Critical Requirements - โœ… Can read ANY file type (CSS/SCSS/JS/TS/HTML) - not restricted to CSS only - - โœ… Use Read() tool for each file you want to analyze (files are in SOURCE_PATH: ${source_path}) + - โœ… Use Read() tool for each file you want to analyze (files are in SOURCE: ${source}) - โœ… Cross-reference between file types for better extraction - โœ… Extract all visual token types systematically - - โœ… Create style-extraction/style-1/ directory first: Bash(mkdir -p "${output_path}/style-extraction/style-1") + - โœ… Create style-extraction/style-1/ directory first: Bash(mkdir -p "${base_path}/style-extraction/style-1") - โœ… Use Write() to save both files: - - ${output_path}/style-extraction/style-1/design-tokens.json - - ${output_path}/style-extraction/style-1/style-guide.md + - ${base_path}/style-extraction/style-1/design-tokens.json + - ${base_path}/style-extraction/style-1/style-guide.md - โœ… Include _metadata.completeness field to track missing content - โŒ NO external research or MCP calls ` @@ -380,7 +380,7 @@ Task(ui-design-agent): ` [ANIMATION_TOKENS_EXTRACTION] Extract animation/transition tokens from ALL file types - MODE: animation-extraction | SOURCE_PATH: ${source_path} | OUTPUT_PATH: ${output_path} + MODE: animation-extraction | SOURCE: ${source} | BASE_PATH: ${base_path} ## Input Files (Can reference ANY file type) @@ -407,7 +407,7 @@ Task(ui-design-agent): ` ## Output Requirements - Generate 2 files in ${output_path}/animation-extraction/: + Generate 2 files in ${base_path}/animation-extraction/: 1. animation-tokens.json (production-ready animation tokens) 2. animation-guide.md (animation usage guide) @@ -532,13 +532,13 @@ Task(ui-design-agent): ` ## Critical Requirements - โœ… Can read ANY file type (CSS/SCSS/JS/TS/HTML) - - โœ… Use Read() tool for each file you want to analyze (files are in SOURCE_PATH: ${source_path}) + - โœ… Use Read() tool for each file you want to analyze (files are in SOURCE: ${source}) - โœ… Detect animation framework if used - โœ… Extract all animation-related tokens - - โœ… Create animation-extraction/ directory first: Bash(mkdir -p "${output_path}/animation-extraction") + - โœ… Create animation-extraction/ directory first: Bash(mkdir -p "${base_path}/animation-extraction") - โœ… Use Write() to save both files: - - ${output_path}/animation-extraction/animation-tokens.json - - ${output_path}/animation-extraction/animation-guide.md + - ${base_path}/animation-extraction/animation-tokens.json + - ${base_path}/animation-extraction/animation-guide.md - โœ… Include _metadata.completeness field to track missing content - โŒ NO external research or MCP calls ` @@ -553,7 +553,7 @@ Task(ui-design-agent): ` [LAYOUT_PATTERNS_EXTRACTION] Extract layout patterns and component structures from ALL file types - MODE: layout-extraction | SOURCE_PATH: ${source_path} | OUTPUT_PATH: ${output_path} + MODE: layout-extraction | SOURCE: ${source} | BASE_PATH: ${base_path} ## Input Files (Can reference ANY file type) @@ -580,7 +580,7 @@ Task(ui-design-agent): ` ## Output Requirements - Generate 1 file: ${output_path}/layout-extraction/layout-templates.json + Generate 1 file: ${base_path}/layout-extraction/layout-templates.json ### layout-templates.json Structure: { @@ -677,11 +677,11 @@ Task(ui-design-agent): ` ## Critical Requirements - โœ… Can read ANY file type (CSS/SCSS/JS/TS/HTML) - - โœ… Use Read() tool for each file you want to analyze (files are in SOURCE_PATH: ${source_path}) + - โœ… Use Read() tool for each file you want to analyze (files are in SOURCE: ${source}) - โœ… Identify naming conventions and layout systems - โœ… Extract component patterns with variants and states - - โœ… Create layout-extraction/ directory first: Bash(mkdir -p "${output_path}/layout-extraction") - - โœ… Use Write() to save: ${output_path}/layout-extraction/layout-templates.json + - โœ… Create layout-extraction/ directory first: Bash(mkdir -p "${base_path}/layout-extraction") + - โœ… Use Write() to save: ${base_path}/layout-extraction/layout-templates.json - โœ… Include extraction_metadata.completeness field to track missing content - โŒ NO external research or MCP calls ` @@ -712,11 +712,11 @@ echo "[Phase 1] Parallel agent analysis complete" ### Generated Files -**Location**: `${output_path}/` +**Location**: `${base_path}/` **Directory Structure**: ``` -${output_path}/ +${base_path}/ โ”œโ”€โ”€ style-extraction/ โ”‚ โ””โ”€โ”€ style-1/ โ”‚ โ”œโ”€โ”€ design-tokens.json # Production-ready design tokens @@ -771,7 +771,7 @@ ${output_path}/ | Error | Cause | Resolution | |-------|-------|------------| -| No files discovered | Glob patterns too restrictive or wrong source-path | Check glob patterns and source-path, verify file locations | +| No files discovered | Glob patterns too restrictive or wrong --source path | Check glob patterns and --source parameter, verify file locations | | Agent reports "failed" status | No tokens found in any file | Review file content, check if files contain design tokens | | Empty completeness reports | Files exist but contain no extractable tokens | Manually verify token definitions in source files | | Missing file type | Specific file type not discovered | Use explicit glob flags (--css, --js, --html, --scss) | @@ -781,8 +781,8 @@ ${output_path}/ ## Best Practices 1. **Use auto-discovery for full projects**: Omit glob flags to discover all files automatically -2. **Target specific directories for speed**: Use `--source-path` to target source code and `--output-path` for extracted tokens, combined with specific globs for focused analysis -3. **Separate source and output**: Always use distinct `--source-path` (where source code lives) and `--output-path` (where design tokens are generated) to avoid polluting source code directory +2. **Target specific directories for speed**: Use `--source` to specify source code location and `--base-path` for extracted tokens output, combined with specific globs for focused analysis +3. **Separate source and output**: When analyzing external codebases, use `--source` to point to source code and `--base-path` for design tokens output directory (default: --source uses --base-path if not specified) 4. **Cross-reference agent reports**: Compare all three completeness reports to identify gaps 5. **Review missing content**: Check `missing` field in reports for actionable improvements -6. **Verify file discovery**: Check `${output_path}/.intermediates/import-analysis/*-files.txt` if agents report no data +6. **Verify file discovery**: Check `${base_path}/.intermediates/import-analysis/*-files.txt` if agents report no data diff --git a/.claude/skills/command-guide/reference/commands/workflow/ui-design/layout-extract.md b/.claude/skills/command-guide/reference/commands/workflow/ui-design/layout-extract.md index 77ed6760..62535941 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/ui-design/layout-extract.md +++ b/.claude/skills/command-guide/reference/commands/workflow/ui-design/layout-extract.md @@ -1,8 +1,8 @@ --- name: layout-extract description: Extract structural layout information from reference images, URLs, or text prompts using Claude analysis -argument-hint: [--base-path ] [--session ] [--images ""] [--urls ""] [--prompt ""] [--targets ""] [--variants ] [--device-type ] -allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), Bash(*), Task(ui-design-agent), mcp__exa__web_search_exa(*) +argument-hint: [--base-path ] [--session ] [--images ""] [--urls ""] [--prompt ""] [--targets ""] [--variants ] [--device-type ] [--interactive] +allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), Bash(*), AskUserQuestion(*), Task(ui-design-agent), mcp__exa__web_search_exa(*) --- # Layout Extraction Command @@ -66,7 +66,7 @@ ELSE: device_type = --device-type OR "responsive" # desktop|mobile|tablet|responsive # Determine base path (auto-detect and convert to absolute) -relative_path=$(find .workflow -type d -name "design-run-*" | head -1) +relative_path=$(find .workflow -type d -name "design-run-*" -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2) base_path=$(cd "$relative_path" && pwd) bash(test -d "$base_path" && echo "โœ“ Base path: $base_path" || echo "โœ— Path not found") # OR use --base-path / --session parameters @@ -260,11 +260,23 @@ bash(cat {base_path}/.intermediates/layout-analysis/analysis-options.json | grep --- -## Phase 1.5: User Confirmation (Explore Mode Only - INTERACTIVE) +## Phase 1.5: User Confirmation (Optional - Triggered by --interactive) **Purpose**: Allow user to select preferred layout concept(s) for each target before generating detailed templates -### Step 1: Load and Present Options +**Trigger Condition**: Execute this phase ONLY if `--interactive` flag is present + +### Step 1: Check Interactive Flag +```bash +# Skip this entire phase if --interactive flag is not present +IF NOT --interactive: + SKIP to Phase 2 + +# Interactive mode enabled +REPORT: "๐ŸŽฏ Interactive mode: User selection required for {targets.length} target(s)" +``` + +### Step 2: Load and Present Options ```bash # Read options file options = Read({base_path}/.intermediates/layout-analysis/analysis-options.json) @@ -354,6 +366,9 @@ FOR each target: ### Step 4: Write User Selection File ```bash +# Create user-selections directory +bash(mkdir -p {base_path}/.intermediates/user-selections) + # Calculate total selections across all targets total_selections = sum([len(selections[t].selected_indices) for t in targets]) @@ -365,14 +380,14 @@ selection_data = { "session_id": "{session_id}", "total_selections": total_selections }, - "selections": selections // {target: {selected_indices: [...], concept_names: [...]}} + "selected_variants": selections // {target: {selected_indices: [...], concept_names: [...]}} } -# Write to file -bash(echo '{selection_data}' > {base_path}/.intermediates/layout-analysis/user-selection.json) +# Write to standardized selection file +bash(echo '{selection_data}' > {base_path}/.intermediates/user-selections/layout-extract-selection.json) # Verify -bash(test -f {base_path}/.intermediates/layout-analysis/user-selection.json && echo "saved") +bash(test -f {base_path}/.intermediates/user-selections/layout-extract-selection.json && echo "saved") ``` ### Step 5: Confirmation Message @@ -395,11 +410,27 @@ Proceeding to generate {total_selections} detailed layout template(s)... **Executor**: `Task(ui-design-agent)` ร— `Total_Selected_Templates` in **parallel** -### Step 1: Load User Selections and Build Task List +### Step 1: Load User Selections or Default to All ```bash -# Read user selections -selection = Read({base_path}/.intermediates/layout-analysis/user-selection.json) -selections_per_target = selection.selections +# Check if user selection file exists (interactive mode) +IF exists({base_path}/.intermediates/user-selections/layout-extract-selection.json): + # Interactive mode: Use user-selected variants + selection = Read({base_path}/.intermediates/user-selections/layout-extract-selection.json) + selections_per_target = selection.selected_variants + + # Calculate total selections + total_selections = selection.metadata.total_selections +ELSE: + # Non-interactive mode: Generate ALL variants for ALL targets (default behavior) + selections_per_target = {} + total_selections = 0 + + FOR each target in targets: + selections_per_target[target] = { + "selected_indices": [1, 2, ..., variants_count], # All indices + "concept_names": [] # Will be filled from options + } + total_selections += variants_count # Read concept details options = Read({base_path}/.intermediates/layout-analysis/analysis-options.json) diff --git a/.claude/skills/command-guide/reference/commands/workflow/ui-design/style-extract.md b/.claude/skills/command-guide/reference/commands/workflow/ui-design/style-extract.md index aef7651c..86ac99f7 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/ui-design/style-extract.md +++ b/.claude/skills/command-guide/reference/commands/workflow/ui-design/style-extract.md @@ -1,8 +1,8 @@ --- name: style-extract description: Extract design style from reference images or text prompts using Claude analysis with variant generation -argument-hint: "[--base-path ] [--session ] [--images ""] [--urls ""] [--prompt ""] [--variants ]" -allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), mcp__chrome-devtools__navigate_page(*), mcp__chrome-devtools__evaluate_script(*) +argument-hint: "[--base-path ] [--session ] [--images ""] [--urls ""] [--prompt ""] [--variants ] [--interactive]" +allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), AskUserQuestion(*), mcp__chrome-devtools__navigate_page(*), mcp__chrome-devtools__evaluate_script(*) --- # Style Extraction Command @@ -46,7 +46,7 @@ variants_count = --variants OR 3 VALIDATE: 1 <= variants_count <= 5 # Determine base path (auto-detect and convert to absolute) -relative_path=$(find .workflow -type d -name "design-run-*" | head -1) +relative_path=$(find .workflow -type d -name "design-run-*" -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2) base_path=$(cd "$relative_path" && pwd) bash(test -d "$base_path" && echo "โœ“ Base path: $base_path" || echo "โœ— Path not found") # OR use --base-path / --session parameters @@ -204,11 +204,23 @@ bash(cat {base_path}/.intermediates/style-analysis/analysis-options.json | grep --- -## Phase 1.5: User Confirmation (Explore Mode Only - INTERACTIVE) +## Phase 1.5: User Confirmation (Optional - Triggered by --interactive) **Purpose**: Allow user to select preferred design direction(s) before generating full design systems -### Step 1: Load and Present Options +**Trigger Condition**: Execute this phase ONLY if `--interactive` flag is present + +### Step 1: Check Interactive Flag +```bash +# Skip this entire phase if --interactive flag is not present +IF NOT --interactive: + SKIP to Phase 2 + REPORT: "โ„น๏ธ Non-interactive mode: Will generate all {variants_count} variants" + +REPORT: "๐ŸŽฏ Interactive mode enabled: User selection required" +``` + +### Step 2: Load and Present Options ```bash # Read options file options = Read({base_path}/.intermediates/style-analysis/analysis-options.json) @@ -290,6 +302,9 @@ REPORT: "โœ… Selected {selected_indices.length} design direction(s)" ### Step 4: Write User Selection File ```bash +# Create user-selections directory +bash(mkdir -p {base_path}/.intermediates/user-selections) + # Create user selection JSON selection_data = { "metadata": { @@ -298,17 +313,17 @@ selection_data = { "session_id": "{session_id}", "selection_count": selected_indices.length }, - "selected_indices": selected_indices, // Array of selected indices + "selected_variants": selected_indices, // Array of selected indices (e.g., [1, 3]) "refinements": { "enabled": false } } -# Write to file -bash(echo '{selection_data}' > {base_path}/.intermediates/style-analysis/user-selection.json) +# Write to standardized selection file +bash(echo '{selection_data}' > {base_path}/.intermediates/user-selections/style-extract-selection.json) # Verify -bash(test -f {base_path}/.intermediates/style-analysis/user-selection.json && echo "saved") +bash(test -f {base_path}/.intermediates/user-selections/style-extract-selection.json && echo "saved") ``` ### Step 5: Confirmation Message @@ -329,11 +344,20 @@ Proceeding to generate {selected_indices.length} complete design system(s)... **Executor**: `Task(ui-design-agent)` for selected variant(s) -### Step 1: Load User Selection +### Step 1: Load User Selection or Default to All ```bash -# Read user selection -selection = Read({base_path}/.intermediates/style-analysis/user-selection.json) -selected_indices = selection.selected_indices # Array of selected indices +# Check if user selection file exists (interactive mode) +IF exists({base_path}/.intermediates/user-selections/style-extract-selection.json): + # Interactive mode: Use user-selected variants + selection = Read({base_path}/.intermediates/user-selections/style-extract-selection.json) + selected_indices = selection.selected_variants # Array of selected indices (e.g., [1, 3]) + + REPORT: "๐ŸŽฏ Interactive mode: Using {selected_indices.length} user-selected variant(s)" +ELSE: + # Non-interactive mode: Generate ALL variants (default behavior) + selected_indices = [1, 2, ..., variants_count] # All indices from 1 to variants_count + + REPORT: "โ„น๏ธ Non-interactive mode: Generating all {variants_count} variant(s)" # Read the selected direction details from options options = Read({base_path}/.intermediates/style-analysis/analysis-options.json)