- Updated implementation_approach in task-generate-tdd.md to use an array format with detailed steps for minimal code implementation and iterative testing.
- Enhanced task-generate.md to support CLI execution mode with Codex, including examples for task execution and session management.
- Modified test-task-generate.md to incorporate CLI execution mode, allowing Codex to autonomously generate tests and execute iterative test-fix cycles.
- Revised task-core.md and workflow-architecture.md to adopt a step-based implementation approach, improving clarity and dependency management in task execution.
- Improved documentation in workflow-architecture.md to clarify flow control structure and variable referencing.
- Introduced the discuss-plan command to facilitate iterative discussions among Gemini, Codex, and Claude.
- Defined roles and priorities for each model in the discussion loop.
- Established a structured workflow for input processing, discussion rounds, and user review.
- Implemented TodoWrite tracking for progress across rounds.
- Specified output routing for logs and final plans.
- Included examples and best practices for effective usage.
- Introduced a unified API documentation template covering both Code API and HTTP API sections.
- Created a folder navigation documentation template for directories containing subdirectories.
- Developed a module README documentation template focusing on module purpose, usage, and dependencies.
- Added a project architecture documentation template synthesizing module information and system design.
- Implemented a project examples documentation template showcasing practical usage scenarios.
- Established a project-level documentation template outlining project overview, architecture, and navigation.
**Summary:**
Applied the same selective replacement logic from Install-Claude.ps1 to Install-Claude.sh (Bash version).
**Changes:**
- Added `backup_and_replace_directory` function for folder-level operations
- Modified `install_global` to use selective replacement for .claude, .codex, .gemini, .qwen
- Modified `install_path` to use selective replacement for local folders and config directories
- Maintained `merge_directory_contents` for backward compatibility
**New Installation Flow:**
1. Backup entire existing directory to timestamped backup folder
2. Only remove items in destination that match source item names
3. Copy source items to destination
4. Preserve all other files in destination directory
**Benefits:**
- Protects user-created files and session data
- Only updates files that come from installation source
- Safer incremental updates
- Consistent behavior across PowerShell and Bash versions
**Example:**
Source: .claude/{commands, workflows, scripts}
Destination before: .claude/{commands, workflows, custom.json, .workflow/}
Destination after: .claude/{commands, workflows, scripts, custom.json, .workflow/}
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
**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>
- Add Tool Control System section explaining optional external CLI tools
- Replace "Prerequisites: Required Tools" with optional tool configuration
- Document graceful degradation and progressive enhancement features
- Add configuration file reference and usage examples
- Update both English and Chinese versions
This addresses Issue #2 by documenting the new optional CLI dependency system.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Added reference to tool-control.yaml for CLI tool availability management
- Includes new tool-control.yaml configuration file
- Helps coordinate tool usage across commands and agent executions
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Implemented the `/workflow:ui-design:explore-layers` command for depth-controlled UI capture.
- Defined depth levels from full-page screenshots to Shadow DOM exploration.
- Included setup, validation, and navigation phases with error handling.
- Captured screenshots at various depths and generated a comprehensive layer map.
- Added examples and usage instructions for ease of use.
- Introduced a new workflow named `imitate-auto-v3` that allows for batch screenshot capture and optional token refinement.
- Implemented a comprehensive 5-phase execution protocol to handle initialization, screenshot capture, style extraction, token processing, and UI generation.
- Added support for multiple target URLs through a `--url-map` parameter, enhancing flexibility in design replication.
- Included optional parameters for session management and token refinement, allowing users to customize their workflow experience.
- Enhanced error handling and reporting throughout the workflow to ensure clarity and ease of debugging.
- Deprecated the previous `imitate-auto.md` workflow in favor of this more robust version.
- Introduced Phase 0c for user confirmation before initiating the workflow.
- Updated phases to ensure immediate transitions between style extraction, consolidation, and UI generation.
- Revised documentation to reflect changes in phase execution and user interaction.
- Changed terminology from "style-centric" to "target-style-centric" to emphasize the new approach.
- Improved layout planning to focus on gathering layout inspiration rather than strict structural differences.
- Enhanced task descriptions and requirements for clarity and consistency across phases.
- Updated TodoWrite patterns to track progress accurately through the new workflow structure.
- Remove npx playwright to prevent auto-installation triggers
- Add explicit tool availability checks using 'which' command
- Check for playwright-cli, google-chrome, chrome, and chromium executables
- Only attempt screenshot capture if tools are already installed
- Provide clear tool availability reporting to users
- Gracefully fallback to manual mode when no tools available
- Support chromium browser on Linux systems
This ensures the workflow never triggers package installations and works
safely in environments without screenshot tools installed.
Add Phase 0.1/1.1 memory check to all UI design workflow commands to skip
execution when outputs already exist. This optimization dramatically reduces
redundant execution time from minutes to <1 second.
Changes:
- extract.md: Check for style-cards.json, skip Phase 0.5-3 if exists
- consolidate.md: Check for style-1/design-tokens.json, skip Phase 2-6
- generate.md: Check for compare.html, skip Phase 1.5-4
- update.md: Check for current design run in synthesis-spec, skip Phase 2-5
Benefits:
- >99% time reduction for repeated workflow execution
- Automatic cache detection without manual flags
- Clear reporting of skipped phases
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Agent now directly generates HTML with final CSS references (no placeholders)
- Remove tokens.css dependency - agents create self-contained CSS from design-tokens.json
- Simplify ui-generate-preview-v2.sh (no placeholder replacement logic)
- Update Phase 2.5 validation to check actual href attributes
- Remove Phase 1.6 (token conversion step)
- Improve agent instructions with direct CSS value usage from design tokens
Benefits:
- Simpler workflow with fewer intermediate steps
- More flexible CSS generation - agents can adapt token values based on design_attributes
- Better style differentiation across variants
- Reduced dependencies and potential error points
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Replace exa-code with web-search for diverse layout inspiration
- Simplify from keyword pools to direct "common variations" search
- Add selection strategy for agents to pick different structural patterns
- Support unlimited layout variants with natural diversity
Impact: Prevents layout architecture convergence by leveraging web search
for real-world layout variations instead of code examples.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Implemented a new script to generate compare.html and index.html for UI prototypes.
- Auto-detects styles, layouts, and targets from HTML file patterns.
- Generates an interactive comparison matrix and a simple index of prototypes.
- Includes a detailed PREVIEW.md guide with usage instructions and file structure.
Clarified file writing patterns across UI design workflows to prevent confusion
between "generate content as output then save" vs "direct write to file" approaches.
Changes:
- extract.md: Merged Phase 2 & 3 to unify style synthesis and file write operations
* Updated phase title to emphasize direct file writing
* Added explicit note about internal processing without context output
* Consolidated parse-and-write step into single atomic operation
- imitate-auto.md: Added clarifying comments for orchestrator file transformation
* Documented that Phase 2 uses orchestrator-level read-process-write pattern
* Explained this as performance optimization to bypass consolidate phase
The entire UI design workflow now consistently follows clear file operation patterns
with no ambiguous intermediate output steps.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Replace mcp__exa__get_code_context_exa with mcp__exa__web_search_exa in consolidate.md
for trend research queries (colors, typography, layout, contrast, accessibility)
- Add Phase 0.75 URL Content Analysis in imitate-auto.md for screenshot fallback mode
- Use web_search_exa for design pattern extraction from URLs when screenshots unavailable
- Update workflow documentation to reflect new MCP tool usage
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fix critical CSS loading issue where component templates were missing
style references due to contradictory instructions.
Changes:
- Require all templates (pages and components) to generate complete HTML5 documents
- Components now use full document structure with isolated body content
- Guarantees <head> tag presence for CSS placeholder injection
- Update validation to enforce <!DOCTYPE html> requirement
- Update documentation to reflect unified template approach
This ensures ui-instantiate-prototypes.sh can reliably inject STRUCTURAL_CSS
and TOKEN_CSS placeholders, fixing component styling issues.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Remove Code Index MCP integration (focus on design trends only)
- Replace mcp__exa__get_code_context_exa with mcp__exa__web_search_exa for design trend research
- Add detailed shell script integration documentation:
- convert_tokens_to_css.sh: Token JSON to CSS conversion with usage patterns and error handling
- ui-instantiate-prototypes.sh: Template instantiation with auto-detection and mode options
- Update MCP use cases to focus on design trends, color/typography, and accessibility patterns
- Clarify that agent uses web search for current design trends, not code implementation
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
**Extract Changes:**
- Remove Phase 1.5 MCP trend research (Exa queries)
- Save design-space-analysis.json with search keywords for consolidate
- Update to pure Claude-native analysis (aligns with philosophy)
- Simplify completion todos and output documentation
**Consolidate Changes:**
- Load design-space-analysis.json from extraction phase
- Add Step 1: Variant-Specific Trend Research (MCP) to agent prompt
- Agent performs 4 MCP queries per variant + shared accessibility research
- Refine tokens using trend insights while maintaining variant identity
- Update completion reporting and key features
**Generate Changes:**
- Enhance HTML placeholder documentation with critical warnings
- Add complete HTML template examples (page/component modes)
- Clarify {{STRUCTURAL_CSS}} and {{TOKEN_CSS}} placeholder rules
- Simplify agent completion requirements (remove detailed report format)
- Allow agent to self-report completion status
**Benefits:**
- Extract becomes truly Claude-native (no external tools)
- Consolidate agent handles all MCP research in one place
- Better separation of concerns between phases
- Clearer template generation instructions for agents
- More flexible agent reporting
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Added validation for --style-variants in generate command to ensure it matches actual style directories, preventing errors during prototype generation.
- Updated ui-instantiate-prototypes.sh script to validate style variants against existing directories, providing warnings and auto-correcting when necessary.
- Improved clarity in generate.md documentation regarding parameters, default values, and auto-detection mechanisms.
- Created a comprehensive UI Design Workflow Parameter Clarity Report to address inconsistencies in parameter naming and documentation across extract, consolidate, and generate commands.
- Unified parameter naming conventions to reduce confusion and improve user experience.
- Enhanced user guidance with a new README.md for the UI Design Workflow, outlining best practices and common mistakes.
- Removed the generation of a unified consolidation report in the consolidate.md file, streamlining the output structure.
- Updated the extract.md file to prioritize the --base-path argument for session management and improved error handling for style variant detection.
- Enhanced generate.md to enforce critical requirements for layout templates, ensuring independence from other targets.
- Added a comprehensive analysis report for the ui-instantiate-prototypes.sh script, detailing issues with style variant mismatches and proposing solutions for validation and prevention.
Changes agent task delegation from direct file writing to labeled output format, giving main command control over file paths. Fixes path inconsistency issues when called from explore-auto workflow.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Consolidate separate page/component modes into a unified target system to
reduce code duplication and simplify the workflow parameter model.
Changes:
- Merge --pages and --components into unified --targets parameter
- Add --target-type (auto|page|component) with intelligent detection
- Remove Phase 0d from explore-auto.md (131 lines of duplicate logic)
- Implement detect_target_type() helper for automatic classification
- Update generate.md to support adaptive wrapper generation
- Full HTML structure for pages
- Minimal wrapper for isolated components
- Update imitate-auto.md and update.md for parameter consistency
- Enhance ui-design-agent.md with adaptive design capabilities
- Maintain full backward compatibility with legacy syntax
Benefits:
- Code reduction: -35% in target inference logic (255 → 165 lines)
- Maintenance: Single unified logic path vs dual implementations
- Extensibility: Foundation for future mixed-mode support
- UX: Simpler parameter model with automatic type detection
Technical Details:
- explore-auto.md: 605 lines changed (unified Phase 0c)
- generate.md: 353 lines changed (targets + adaptive wrapper)
- Net change: +685 insertions, -504 deletions across 5 files
All existing workflows remain compatible via legacy parameter support.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fix layout strategy generation issues across UI design commands:
- consolidate.md: Enhance layout synthesis prompt with explicit examples and requirements
* Add concrete 3-layout example to clarify expected output structure
* Emphasize requirement to generate EXACTLY N strategies (not more, not less)
* Add sequential ID validation (layout-1, layout-2, ..., layout-N)
- explore-auto.md: Add missing --layout-variants parameter to consolidate command call
* Phase 2 now passes layout_variants count to ensure correct strategy generation
* Prevents mismatch between requested layouts and generated strategies
- extract.md: Update next step suggestions to include --layout-variants parameter
* Users now see optional [--layout-variants <count>] in command examples
* Improves discoverability of layout customization option
Before: consolidate would only generate default 3 layouts even when user specified different count
After: consolidate receives and respects user-specified layout variant count
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Enhance UI Design Workflow with intelligent design trend research capabilities:
- Add design trend analysis in extract phase using Exa MCP API
- Integrate layout strategy planning with current UI/UX patterns (2024-2025)
- Update consolidation command to include dynamic layout generation
- Add ui-instantiate-prototypes.sh script for prototype management
- Simplify path structure by removing nested .design directories
- Update workflow architecture documentation
This integration enables context-aware design decisions based on modern design trends
and improves the quality of generated UI prototypes.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Introduced a new command `/workflow:ui-design:imitate-auto` for imitating UI designs from URLs or images.
- Streamlined execution model with 5 phases: initialization, screenshot capture, style extraction, token adaptation, and prototype generation.
- Emphasized single style and layout generation, bypassing the consolidate step for improved speed.
- Implemented automated screenshot capture with fallback to manual input if necessary.
- Enhanced error handling for missing references and screenshot failures.
- Provided detailed documentation and examples for usage and execution flows.
