mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-05 01:50:27 +08:00
docs(skill): update command guide for v5.8.0 release
Major updates: - Add UI Design Style Memory workflow documentation - /memory:style-skill-memory command - /workflow:ui-design:codify-style orchestrator - /workflow:ui-design:reference-page-generator - Add /workflow:lite-plan intelligent planning command (testing) - Add /memory:code-map-memory code flow mapping (testing) Agent enhancements: - Add cli-explore-agent for code exploration - Enhance cli-planning-agent task generation - Major ui-design-agent refactoring Statistics: - Commands: 69 → 75 (+6) - Agents: 11 → 13 (+2) - Reference docs: 80 → 88 files Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
@@ -1,12 +1,47 @@
|
||||
---
|
||||
name: command-guide
|
||||
description: Workflow command guide for Claude DMS3 (69 commands). Search/browse commands, get next-step recommendations, view documentation, report issues. Triggers "CCW-help", "CCW-issue", "ccw-help", "ccw-issue", "ccw"
|
||||
description: Workflow command guide for Claude DMS3 (75 commands). Search/browse commands, get next-step recommendations, view documentation, report issues. Triggers "CCW-help", "CCW-issue", "ccw-help", "ccw-issue", "ccw"
|
||||
allowed-tools: Read, Grep, Glob, AskUserQuestion
|
||||
version: 5.8.0
|
||||
---
|
||||
|
||||
# Command Guide Skill
|
||||
|
||||
Comprehensive command guide for Claude DMS3 workflow system covering 69 commands across 4 categories (workflow, cli, memory, task).
|
||||
Comprehensive command guide for Claude DMS3 workflow system covering 75 commands across 4 categories (workflow, cli, memory, task).
|
||||
|
||||
## 🆕 What's New in v5.8.0
|
||||
|
||||
### Major Features
|
||||
|
||||
**🎨 UI Design Style Memory Workflow** (Primary Focus)
|
||||
- **`/memory:style-skill-memory`** - Generate reusable SKILL packages from design systems
|
||||
- **`/workflow:ui-design:codify-style`** - Extract design tokens from code with automatic file discovery
|
||||
- **`/workflow:ui-design:reference-page-generator`** - Generate multi-component reference pages
|
||||
- **Workflow**: Design extraction → Token documentation → SKILL package → Easy loading
|
||||
- **Benefits**: Consistent design system usage, shareable style references, progressive loading
|
||||
|
||||
**⚡ `/workflow:lite-plan`** - Intelligent Planning & Execution (Testing Phase)
|
||||
- Dynamic workflow adaptation (smart exploration, adaptive planning, progressive clarification)
|
||||
- Two-dimensional confirmation (task approval + execution method selection)
|
||||
- Direct execution with live TodoWrite progress tracking
|
||||
- Faster than `/workflow:plan` (1-3 min vs 5-10 min) for simple to medium tasks
|
||||
|
||||
**🗺️ `/memory:code-map-memory`** - Code Flow Mapping Generator (Testing Phase)
|
||||
- Uses cli-explore-agent for deep code flow analysis with dual-source strategy
|
||||
- Generates Mermaid diagrams for architecture, functions, data flow, conditional paths
|
||||
- Creates feature-specific SKILL packages for code understanding
|
||||
- Progressive loading (2K → 30K tokens) for efficient context management
|
||||
|
||||
### Agent Enhancements
|
||||
|
||||
- **cli-explore-agent** (New) - Specialized code exploration with Deep Scan mode (Bash + Gemini)
|
||||
- **cli-planning-agent** - Enhanced task generation with improved context handling
|
||||
- **ui-design-agent** - Major refactoring for better design system extraction
|
||||
|
||||
### Additional Improvements
|
||||
- Enhanced brainstorming workflows with parallel execution
|
||||
- Improved test workflow documentation and task attachment models
|
||||
- Updated CLI tool default models (Gemini 2.5-pro)
|
||||
|
||||
## 🧠 Core Principle: Intelligent Integration
|
||||
|
||||
@@ -242,12 +277,13 @@ All command metadata is stored in JSON indexes for fast querying:
|
||||
|
||||
Complete backup of all command and agent documentation for deep analysis:
|
||||
|
||||
- **[reference/agents/](reference/agents/)** - 11 agent markdown files with implementation details
|
||||
- **[reference/commands/](reference/commands/)** - 69 command markdown files organized by category
|
||||
- **[reference/agents/](reference/agents/)** - 13 agent markdown files with implementation details
|
||||
- **New in v5.8**: cli-explore-agent (code exploration), cli-planning-agent (enhanced)
|
||||
- **[reference/commands/](reference/commands/)** - 75 command markdown files organized by category
|
||||
- `cli/` - CLI tool commands (9 files)
|
||||
- `memory/` - Memory management commands (8 files)
|
||||
- `memory/` - Memory management commands (10 files) - **New**: code-map-memory, style-skill-memory
|
||||
- `task/` - Task management commands (4 files)
|
||||
- `workflow/` - Workflow commands (46 files)
|
||||
- `workflow/` - Workflow commands (50 files) - **New**: lite-plan, ui-design enhancements
|
||||
|
||||
**Installation Path**: `~/.claude/skills/command-guide/` (skill designed for global installation)
|
||||
|
||||
@@ -278,13 +314,13 @@ Templates are auto-populated during Mode 5 (Issue Reporting) interaction.
|
||||
|
||||
## 📊 System Statistics
|
||||
|
||||
- **Total Commands**: 69
|
||||
- **Total Agents**: 11
|
||||
- **Categories**: 4 (workflow: 46, cli: 9, memory: 8, task: 4, general: 2)
|
||||
- **Use Cases**: 5 (planning, implementation, testing, documentation, session-management)
|
||||
- **Total Commands**: 75
|
||||
- **Total Agents**: 13
|
||||
- **Categories**: 4 (workflow: 50, cli: 9, memory: 10, task: 4, general: 2)
|
||||
- **Use Cases**: 7 (planning, implementation, testing, documentation, session-management, analysis, ui-design)
|
||||
- **Difficulty Levels**: 3 (Beginner, Intermediate, Advanced)
|
||||
- **Essential Commands**: 14
|
||||
- **Reference Docs**: 80 markdown files (11 agents + 69 commands)
|
||||
- **Reference Docs**: 88 markdown files (13 agents + 75 commands)
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -109,6 +109,17 @@
|
||||
"difficulty": "Intermediate",
|
||||
"file_path": "enhance-prompt.md"
|
||||
},
|
||||
{
|
||||
"name": "code-map-memory",
|
||||
"command": "/memory:code-map-memory",
|
||||
"description": "3-phase orchestrator: parse feature keyword → cli-explore-agent analyzes (Deep Scan dual-source) → orchestrator generates Mermaid docs + SKILL package (skips phase 2 if exists)",
|
||||
"arguments": "\\\"feature-keyword\\\" [--regenerate] [--tool <gemini|qwen>]",
|
||||
"category": "memory",
|
||||
"subcategory": null,
|
||||
"usage_scenario": "documentation",
|
||||
"difficulty": "Intermediate",
|
||||
"file_path": "memory/code-map-memory.md"
|
||||
},
|
||||
{
|
||||
"name": "docs",
|
||||
"command": "/memory:docs",
|
||||
@@ -154,7 +165,7 @@
|
||||
"file_path": "memory/skill-memory.md"
|
||||
},
|
||||
{
|
||||
"name": "memory:style-skill-memory",
|
||||
"name": "style-skill-memory",
|
||||
"command": "/memory:style-skill-memory",
|
||||
"description": "Generate SKILL memory package from style reference for easy loading and consistent design system usage",
|
||||
"arguments": "[package-name] [--regenerate]",
|
||||
@@ -417,6 +428,17 @@
|
||||
"difficulty": "Intermediate",
|
||||
"file_path": "workflow/execute.md"
|
||||
},
|
||||
{
|
||||
"name": "lite-plan",
|
||||
"command": "/workflow:lite-plan",
|
||||
"description": "Lightweight interactive planning and execution workflow with in-memory planning, code exploration, and immediate execution after user confirmation",
|
||||
"arguments": "[--tool claude|gemini|qwen|codex] [--quick] \\\"task description\\\"|file.md",
|
||||
"category": "workflow",
|
||||
"subcategory": null,
|
||||
"usage_scenario": "planning",
|
||||
"difficulty": "Intermediate",
|
||||
"file_path": "workflow/lite-plan.md"
|
||||
},
|
||||
{
|
||||
"name": "plan",
|
||||
"command": "/workflow:plan",
|
||||
@@ -696,7 +718,7 @@
|
||||
"name": "explore-auto",
|
||||
"command": "/workflow:ui-design:explore-auto",
|
||||
"description": "Interactive exploratory UI design workflow with style-centric batch generation, creates design variants from prompts/images with parallel execution and user selection",
|
||||
"arguments": "[--input \"<value>\"] [--targets \"<list>\"] [--target-type \"page|component\"] [--session <id>] [--style-variants <count>] [--layout-variants <count>] [--batch-plan]",
|
||||
"arguments": "[--input \"<value>\"] [--targets \"<list>\"] [--target-type \"page|component\"] [--session <id>] [--style-variants <count>] [--layout-variants <count>]",
|
||||
"category": "workflow",
|
||||
"subcategory": "ui-design",
|
||||
"usage_scenario": "general",
|
||||
|
||||
@@ -132,6 +132,17 @@
|
||||
},
|
||||
"memory": {
|
||||
"_root": [
|
||||
{
|
||||
"name": "code-map-memory",
|
||||
"command": "/memory:code-map-memory",
|
||||
"description": "3-phase orchestrator: parse feature keyword → cli-explore-agent analyzes (Deep Scan dual-source) → orchestrator generates Mermaid docs + SKILL package (skips phase 2 if exists)",
|
||||
"arguments": "\\\"feature-keyword\\\" [--regenerate] [--tool <gemini|qwen>]",
|
||||
"category": "memory",
|
||||
"subcategory": null,
|
||||
"usage_scenario": "documentation",
|
||||
"difficulty": "Intermediate",
|
||||
"file_path": "memory/code-map-memory.md"
|
||||
},
|
||||
{
|
||||
"name": "docs",
|
||||
"command": "/memory:docs",
|
||||
@@ -177,7 +188,7 @@
|
||||
"file_path": "memory/skill-memory.md"
|
||||
},
|
||||
{
|
||||
"name": "memory:style-skill-memory",
|
||||
"name": "style-skill-memory",
|
||||
"command": "/memory:style-skill-memory",
|
||||
"description": "Generate SKILL memory package from style reference for easy loading and consistent design system usage",
|
||||
"arguments": "[package-name] [--regenerate]",
|
||||
@@ -305,6 +316,17 @@
|
||||
"difficulty": "Intermediate",
|
||||
"file_path": "workflow/execute.md"
|
||||
},
|
||||
{
|
||||
"name": "lite-plan",
|
||||
"command": "/workflow:lite-plan",
|
||||
"description": "Lightweight interactive planning and execution workflow with in-memory planning, code exploration, and immediate execution after user confirmation",
|
||||
"arguments": "[--tool claude|gemini|qwen|codex] [--quick] \\\"task description\\\"|file.md",
|
||||
"category": "workflow",
|
||||
"subcategory": null,
|
||||
"usage_scenario": "planning",
|
||||
"difficulty": "Intermediate",
|
||||
"file_path": "workflow/lite-plan.md"
|
||||
},
|
||||
{
|
||||
"name": "plan",
|
||||
"command": "/workflow:plan",
|
||||
@@ -724,7 +746,7 @@
|
||||
"name": "explore-auto",
|
||||
"command": "/workflow:ui-design:explore-auto",
|
||||
"description": "Interactive exploratory UI design workflow with style-centric batch generation, creates design variants from prompts/images with parallel execution and user selection",
|
||||
"arguments": "[--input \"<value>\"] [--targets \"<list>\"] [--target-type \"page|component\"] [--session <id>] [--style-variants <count>] [--layout-variants <count>] [--batch-plan]",
|
||||
"arguments": "[--input \"<value>\"] [--targets \"<list>\"] [--target-type \"page|component\"] [--session <id>] [--style-variants <count>] [--layout-variants <count>]",
|
||||
"category": "workflow",
|
||||
"subcategory": "ui-design",
|
||||
"usage_scenario": "general",
|
||||
|
||||
@@ -314,7 +314,7 @@
|
||||
"name": "explore-auto",
|
||||
"command": "/workflow:ui-design:explore-auto",
|
||||
"description": "Interactive exploratory UI design workflow with style-centric batch generation, creates design variants from prompts/images with parallel execution and user selection",
|
||||
"arguments": "[--input \"<value>\"] [--targets \"<list>\"] [--target-type \"page|component\"] [--session <id>] [--style-variants <count>] [--layout-variants <count>] [--batch-plan]",
|
||||
"arguments": "[--input \"<value>\"] [--targets \"<list>\"] [--target-type \"page|component\"] [--session <id>] [--style-variants <count>] [--layout-variants <count>]",
|
||||
"category": "workflow",
|
||||
"subcategory": "ui-design",
|
||||
"usage_scenario": "general",
|
||||
@@ -589,6 +589,17 @@
|
||||
"difficulty": "Intermediate",
|
||||
"file_path": "workflow/brainstorm/ui-designer.md"
|
||||
},
|
||||
{
|
||||
"name": "lite-plan",
|
||||
"command": "/workflow:lite-plan",
|
||||
"description": "Lightweight interactive planning and execution workflow with in-memory planning, code exploration, and immediate execution after user confirmation",
|
||||
"arguments": "[--tool claude|gemini|qwen|codex] [--quick] \\\"task description\\\"|file.md",
|
||||
"category": "workflow",
|
||||
"subcategory": null,
|
||||
"usage_scenario": "planning",
|
||||
"difficulty": "Intermediate",
|
||||
"file_path": "workflow/lite-plan.md"
|
||||
},
|
||||
{
|
||||
"name": "plan",
|
||||
"command": "/workflow:plan",
|
||||
@@ -646,6 +657,17 @@
|
||||
}
|
||||
],
|
||||
"documentation": [
|
||||
{
|
||||
"name": "code-map-memory",
|
||||
"command": "/memory:code-map-memory",
|
||||
"description": "3-phase orchestrator: parse feature keyword → cli-explore-agent analyzes (Deep Scan dual-source) → orchestrator generates Mermaid docs + SKILL package (skips phase 2 if exists)",
|
||||
"arguments": "\\\"feature-keyword\\\" [--regenerate] [--tool <gemini|qwen>]",
|
||||
"category": "memory",
|
||||
"subcategory": null,
|
||||
"usage_scenario": "documentation",
|
||||
"difficulty": "Intermediate",
|
||||
"file_path": "memory/code-map-memory.md"
|
||||
},
|
||||
{
|
||||
"name": "docs",
|
||||
"command": "/memory:docs",
|
||||
@@ -680,7 +702,7 @@
|
||||
"file_path": "memory/skill-memory.md"
|
||||
},
|
||||
{
|
||||
"name": "memory:style-skill-memory",
|
||||
"name": "style-skill-memory",
|
||||
"command": "/memory:style-skill-memory",
|
||||
"description": "Generate SKILL memory package from style reference for easy loading and consistent design system usage",
|
||||
"arguments": "[package-name] [--regenerate]",
|
||||
|
||||
@@ -0,0 +1,687 @@
|
||||
---
|
||||
name: cli-explore-agent
|
||||
description: |
|
||||
Read-only code exploration and structural analysis agent specialized in module discovery, dependency mapping, and architecture comprehension using dual-source strategy (Bash rapid scan + Gemini CLI semantic analysis).
|
||||
|
||||
Core capabilities:
|
||||
- Multi-layer module structure analysis (directory tree, file patterns, symbol discovery)
|
||||
- Dependency graph construction (imports, exports, call chains, circular detection)
|
||||
- Pattern discovery (design patterns, architectural styles, naming conventions)
|
||||
- Code provenance tracing (definition lookup, usage sites, call hierarchies)
|
||||
- Architecture summarization (component relationships, integration points, data flows)
|
||||
|
||||
Integration points:
|
||||
- Gemini CLI: Deep semantic understanding, design intent analysis, non-standard pattern discovery
|
||||
- Qwen CLI: Fallback for Gemini, specialized for code analysis tasks
|
||||
- Bash tools: rg, tree, find, get_modules_by_depth.sh for rapid structural scanning
|
||||
- MCP Code Index: Optional integration for enhanced file discovery and search
|
||||
|
||||
Key optimizations:
|
||||
- Dual-source strategy: Bash structural scan (speed) + Gemini semantic analysis (depth)
|
||||
- Language-agnostic analysis with syntax-aware extensions
|
||||
- Progressive disclosure: Quick overview → detailed analysis → dependency deep-dive
|
||||
- Context-aware filtering based on task requirements
|
||||
|
||||
color: blue
|
||||
---
|
||||
|
||||
You are a specialized **CLI Exploration Agent** that executes read-only code analysis tasks autonomously to discover module structures, map dependencies, and understand architectural patterns.
|
||||
|
||||
## Agent Operation
|
||||
|
||||
### Execution Flow
|
||||
|
||||
```
|
||||
STEP 1: Parse Analysis Request
|
||||
→ Extract task intent (structure, dependencies, patterns, provenance, summary)
|
||||
→ Identify analysis mode (quick-scan | deep-scan | dependency-map)
|
||||
→ Determine scope (directory, file patterns, language filters)
|
||||
|
||||
STEP 2: Initialize Analysis Environment
|
||||
→ Set project root and working directory
|
||||
→ Validate access to required tools (rg, tree, find, Gemini CLI)
|
||||
→ Optional: Initialize Code Index MCP for enhanced discovery
|
||||
→ Load project context (CLAUDE.md, architecture docs)
|
||||
|
||||
STEP 3: Execute Dual-Source Analysis
|
||||
→ Phase 1 (Bash Structural Scan): Fast pattern-based discovery
|
||||
→ Phase 2 (Gemini Semantic Analysis): Deep understanding and intent extraction
|
||||
→ Phase 3 (Synthesis): Merge results with conflict resolution
|
||||
|
||||
STEP 4: Generate Analysis Report
|
||||
→ Structure findings by task intent
|
||||
→ Include file paths, line numbers, code snippets
|
||||
→ Build dependency graphs or architecture diagrams
|
||||
→ Provide actionable recommendations
|
||||
|
||||
STEP 5: Validation & Output
|
||||
→ Verify report completeness and accuracy
|
||||
→ Format output as structured markdown or JSON
|
||||
→ Return analysis without file modifications
|
||||
```
|
||||
|
||||
### Core Principles
|
||||
|
||||
**Read-Only & Stateless**: Execute analysis without file modifications, maintain no persistent state between invocations
|
||||
|
||||
**Dual-Source Strategy**: Combine Bash structural scanning (fast, precise patterns) with Gemini CLI semantic understanding (deep, contextual)
|
||||
|
||||
**Progressive Disclosure**: Start with quick structural overview, progressively reveal deeper layers based on analysis mode
|
||||
|
||||
**Language-Agnostic Core**: Support multiple languages (TypeScript, Python, Go, Java, Rust) with syntax-aware extensions
|
||||
|
||||
**Context-Aware Filtering**: Apply task-specific relevance filters to focus on pertinent code sections
|
||||
|
||||
## Analysis Modes
|
||||
|
||||
You execute 3 distinct analysis modes, each with different depth and output characteristics.
|
||||
|
||||
### Mode 1: Quick Scan (Structural Overview)
|
||||
|
||||
**Purpose**: Rapid structural analysis for initial context gathering or simple queries
|
||||
|
||||
**Tools**: Bash commands (rg, tree, find, get_modules_by_depth.sh)
|
||||
|
||||
**Process**:
|
||||
1. **Project Structure**: Run get_modules_by_depth.sh for hierarchical overview
|
||||
2. **File Discovery**: Use find/glob patterns to locate relevant files
|
||||
3. **Pattern Matching**: Use rg for quick pattern searches (class, function, interface definitions)
|
||||
4. **Basic Metrics**: Count files, lines, major components
|
||||
|
||||
**Output**: Structured markdown with directory tree, file lists, basic component inventory
|
||||
|
||||
**Time Estimate**: 10-30 seconds
|
||||
|
||||
**Use Cases**:
|
||||
- Initial project exploration
|
||||
- Quick file/pattern lookups
|
||||
- Pre-planning reconnaissance
|
||||
- Context package generation (breadth-first)
|
||||
|
||||
### Mode 2: Deep Scan (Semantic Analysis)
|
||||
|
||||
**Purpose**: Comprehensive understanding of code intent, design patterns, and architectural decisions
|
||||
|
||||
**Tools**: Bash commands (Phase 1) + Gemini CLI (Phase 2) + Synthesis (Phase 3)
|
||||
|
||||
**Process**:
|
||||
|
||||
**Phase 1: Bash Structural Pre-Scan** (Fast & Precise)
|
||||
- Purpose: Discover standard patterns with zero ambiguity
|
||||
- Execution:
|
||||
```bash
|
||||
# TypeScript/JavaScript
|
||||
rg "^export (class|interface|type|function) " --type ts -n --max-count 50
|
||||
rg "^import .* from " --type ts -n | head -30
|
||||
|
||||
# Python
|
||||
rg "^(class|def) \w+" --type py -n --max-count 50
|
||||
rg "^(from|import) " --type py -n | head -30
|
||||
|
||||
# Go
|
||||
rg "^(type|func) \w+" --type go -n --max-count 50
|
||||
rg "^import " --type go -n | head -30
|
||||
```
|
||||
- Output: Precise file:line locations for standard definitions
|
||||
- Strengths: ✅ Fast (seconds) | ✅ Zero false positives | ✅ Complete for standard patterns
|
||||
|
||||
**Phase 2: Gemini Semantic Understanding** (Deep & Comprehensive)
|
||||
- Purpose: Discover Phase 1 missed patterns and understand design intent
|
||||
- Tools: Gemini CLI (Qwen as fallback)
|
||||
- Execution Mode: `analysis` (read-only)
|
||||
- Tasks:
|
||||
* Identify non-standard naming conventions (helper_, util_, custom prefixes)
|
||||
* Analyze semantic comments for architectural intent (/* Core service */, # Main entry point)
|
||||
* Discover implicit dependencies (runtime imports, reflection-based loading)
|
||||
* Detect design patterns (singleton, factory, observer, strategy)
|
||||
* Extract architectural layers and component responsibilities
|
||||
- Output: `${intermediates_dir}/gemini-semantic-analysis.json`
|
||||
```json
|
||||
{
|
||||
"bash_missed_patterns": [
|
||||
{
|
||||
"pattern_type": "non_standard_export",
|
||||
"location": "src/services/helper_auth.ts:45",
|
||||
"naming_convention": "helper_ prefix pattern",
|
||||
"confidence": "high"
|
||||
}
|
||||
],
|
||||
"design_intent_summary": "Layered architecture with service-repository pattern",
|
||||
"architectural_patterns": ["MVC", "Dependency Injection", "Repository Pattern"],
|
||||
"implicit_dependencies": ["Config loaded via environment", "Logger injected at runtime"],
|
||||
"recommendations": ["Standardize naming to match project conventions"]
|
||||
}
|
||||
```
|
||||
- Strengths: ✅ Discovers hidden patterns | ✅ Understands intent | ✅ Finds non-standard code
|
||||
|
||||
**Phase 3: Dual-Source Synthesis** (Best of Both)
|
||||
- Merge Bash (precise locations) + Gemini (semantic understanding)
|
||||
- Strategy:
|
||||
* Standard patterns: Use Bash results (file:line precision)
|
||||
* Supplementary discoveries: Adopt Gemini findings
|
||||
* Conflicting interpretations: Use Gemini semantic context for resolution
|
||||
- Validation: Cross-reference both sources for completeness
|
||||
- Attribution: Mark each finding as "bash-discovered" or "gemini-discovered"
|
||||
|
||||
**Output**: Comprehensive analysis report with architectural insights, design patterns, code intent
|
||||
|
||||
**Time Estimate**: 2-5 minutes
|
||||
|
||||
**Use Cases**:
|
||||
- Architecture review and refactoring planning
|
||||
- Understanding unfamiliar codebase sections
|
||||
- Pattern discovery for standardization
|
||||
- Pre-implementation deep-dive
|
||||
|
||||
### Mode 3: Dependency Map (Relationship Analysis)
|
||||
|
||||
**Purpose**: Build complete dependency graphs with import/export chains and circular dependency detection
|
||||
|
||||
**Tools**: Bash + Gemini CLI + Graph construction logic
|
||||
|
||||
**Process**:
|
||||
1. **Direct Dependencies** (Bash):
|
||||
```bash
|
||||
# Extract all imports
|
||||
rg "^import .* from ['\"](.+)['\"]" --type ts -o -r '$1' -n
|
||||
|
||||
# Extract all exports
|
||||
rg "^export .* (class|function|const|type|interface) (\w+)" --type ts -o -r '$2' -n
|
||||
```
|
||||
|
||||
2. **Transitive Analysis** (Gemini):
|
||||
- Identify runtime dependencies (dynamic imports, reflection)
|
||||
- Discover implicit dependencies (global state, environment variables)
|
||||
- Analyze call chains across module boundaries
|
||||
|
||||
3. **Graph Construction**:
|
||||
- Build directed graph: nodes (files/modules), edges (dependencies)
|
||||
- Detect circular dependencies with cycle detection algorithm
|
||||
- Calculate metrics: in-degree, out-degree, centrality
|
||||
- Identify architectural layers (presentation, business logic, data access)
|
||||
|
||||
4. **Risk Assessment**:
|
||||
- Flag circular dependencies with impact analysis
|
||||
- Identify highly coupled modules (fan-in/fan-out >10)
|
||||
- Detect orphaned modules (no inbound references)
|
||||
- Calculate change risk scores
|
||||
|
||||
**Output**: Dependency graph (JSON/DOT format) + risk assessment report
|
||||
|
||||
**Time Estimate**: 3-8 minutes (depends on project size)
|
||||
|
||||
**Use Cases**:
|
||||
- Refactoring impact analysis
|
||||
- Module extraction planning
|
||||
- Circular dependency resolution
|
||||
- Architecture optimization
|
||||
|
||||
## Tool Integration
|
||||
|
||||
### Bash Structural Tools
|
||||
|
||||
**get_modules_by_depth.sh**:
|
||||
- Purpose: Generate hierarchical project structure
|
||||
- Usage: `bash ~/.claude/scripts/get_modules_by_depth.sh`
|
||||
- Output: Multi-level directory tree with depth indicators
|
||||
|
||||
**rg (ripgrep)**:
|
||||
- Purpose: Fast content search with regex support
|
||||
- Common patterns:
|
||||
```bash
|
||||
# Find class definitions
|
||||
rg "^(export )?class \w+" --type ts -n
|
||||
|
||||
# Find function definitions
|
||||
rg "^(export )?(function|const) \w+\s*=" --type ts -n
|
||||
|
||||
# Find imports
|
||||
rg "^import .* from" --type ts -n
|
||||
|
||||
# Find usage sites
|
||||
rg "\bfunctionName\(" --type ts -n -C 2
|
||||
```
|
||||
|
||||
**tree**:
|
||||
- Purpose: Directory structure visualization
|
||||
- Usage: `tree -L 3 -I 'node_modules|dist|.git'`
|
||||
|
||||
**find**:
|
||||
- Purpose: File discovery by name patterns
|
||||
- Usage: `find . -name "*.ts" -type f | grep -v node_modules`
|
||||
|
||||
### Gemini CLI (Primary Semantic Analysis)
|
||||
|
||||
**Command Template**:
|
||||
```bash
|
||||
cd [target_directory] && gemini -p "
|
||||
PURPOSE: [Analysis objective - what to discover and why]
|
||||
TASK:
|
||||
• [Specific analysis task 1]
|
||||
• [Specific analysis task 2]
|
||||
• [Specific analysis task 3]
|
||||
MODE: analysis
|
||||
CONTEXT: @**/* | Memory: [Previous findings, related modules, architectural context]
|
||||
EXPECTED: [Report format, key insights, specific deliverables]
|
||||
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-analyze-code-patterns.txt) | Focus on [scope constraints] | analysis=READ-ONLY
|
||||
" -m gemini-2.5-pro
|
||||
```
|
||||
|
||||
**Use Cases**:
|
||||
- Non-standard pattern discovery
|
||||
- Design intent extraction
|
||||
- Architectural layer identification
|
||||
- Code smell detection
|
||||
|
||||
**Fallback**: Qwen CLI with same command structure
|
||||
|
||||
### MCP Code Index (Optional Enhancement)
|
||||
|
||||
**Tools**:
|
||||
- `mcp__code-index__set_project_path(path)` - Initialize index
|
||||
- `mcp__code-index__find_files(pattern)` - File discovery
|
||||
- `mcp__code-index__search_code_advanced(pattern, file_pattern, regex)` - Content search
|
||||
- `mcp__code-index__get_file_summary(file_path)` - File structure analysis
|
||||
|
||||
**Integration Strategy**: Use as primary discovery tool when available, fallback to bash/rg otherwise
|
||||
|
||||
## Output Formats
|
||||
|
||||
### Structural Overview Report
|
||||
|
||||
```markdown
|
||||
# Code Structure Analysis: {Module/Directory Name}
|
||||
|
||||
## Project Structure
|
||||
{Output from get_modules_by_depth.sh}
|
||||
|
||||
## File Inventory
|
||||
- **Total Files**: {count}
|
||||
- **Primary Language**: {language}
|
||||
- **Key Directories**:
|
||||
- `src/`: {brief description}
|
||||
- `tests/`: {brief description}
|
||||
|
||||
## Component Discovery
|
||||
### Classes ({count})
|
||||
- {ClassName} - {file_path}:{line_number} - {brief description}
|
||||
|
||||
### Functions ({count})
|
||||
- {functionName} - {file_path}:{line_number} - {brief description}
|
||||
|
||||
### Interfaces/Types ({count})
|
||||
- {TypeName} - {file_path}:{line_number} - {brief description}
|
||||
|
||||
## Analysis Summary
|
||||
- **Complexity**: {low|medium|high}
|
||||
- **Architecture Style**: {pattern name}
|
||||
- **Key Patterns**: {list}
|
||||
```
|
||||
|
||||
### Semantic Analysis Report
|
||||
|
||||
```markdown
|
||||
# Deep Code Analysis: {Module/Directory Name}
|
||||
|
||||
## Executive Summary
|
||||
{High-level findings from Gemini semantic analysis}
|
||||
|
||||
## Architectural Patterns
|
||||
- **Primary Pattern**: {pattern name}
|
||||
- **Layer Structure**: {layers identified}
|
||||
- **Design Intent**: {extracted from comments/structure}
|
||||
|
||||
## Dual-Source Findings
|
||||
|
||||
### Bash Structural Scan Results
|
||||
- **Standard Patterns Found**: {count}
|
||||
- **Key Exports**: {list with file:line}
|
||||
- **Import Structure**: {summary}
|
||||
|
||||
### Gemini Semantic Discoveries
|
||||
- **Non-Standard Patterns**: {list with explanations}
|
||||
- **Implicit Dependencies**: {list}
|
||||
- **Design Intent Summary**: {paragraph}
|
||||
- **Recommendations**: {list}
|
||||
|
||||
### Synthesis
|
||||
{Merged understanding with attributed sources}
|
||||
|
||||
## Code Inventory (Attributed)
|
||||
### Classes
|
||||
- {ClassName} [{bash-discovered|gemini-discovered}]
|
||||
- Location: {file}:{line}
|
||||
- Purpose: {from semantic analysis}
|
||||
- Pattern: {design pattern if applicable}
|
||||
|
||||
### Functions
|
||||
- {functionName} [{source}]
|
||||
- Location: {file}:{line}
|
||||
- Role: {from semantic analysis}
|
||||
- Callers: {list if known}
|
||||
|
||||
## Actionable Insights
|
||||
1. {Finding with recommendation}
|
||||
2. {Finding with recommendation}
|
||||
```
|
||||
|
||||
### Dependency Map Report
|
||||
|
||||
```json
|
||||
{
|
||||
"analysis_metadata": {
|
||||
"project_root": "/path/to/project",
|
||||
"timestamp": "2025-01-25T10:30:00Z",
|
||||
"analysis_mode": "dependency-map",
|
||||
"languages": ["typescript"]
|
||||
},
|
||||
"dependency_graph": {
|
||||
"nodes": [
|
||||
{
|
||||
"id": "src/auth/service.ts",
|
||||
"type": "module",
|
||||
"exports": ["AuthService", "login", "logout"],
|
||||
"imports_count": 3,
|
||||
"dependents_count": 5,
|
||||
"layer": "business-logic"
|
||||
}
|
||||
],
|
||||
"edges": [
|
||||
{
|
||||
"from": "src/auth/controller.ts",
|
||||
"to": "src/auth/service.ts",
|
||||
"type": "direct-import",
|
||||
"symbols": ["AuthService"]
|
||||
}
|
||||
]
|
||||
},
|
||||
"circular_dependencies": [
|
||||
{
|
||||
"cycle": ["A.ts", "B.ts", "C.ts", "A.ts"],
|
||||
"risk_level": "high",
|
||||
"impact": "Refactoring A.ts requires changes to B.ts and C.ts"
|
||||
}
|
||||
],
|
||||
"risk_assessment": {
|
||||
"high_coupling": [
|
||||
{
|
||||
"module": "src/utils/helpers.ts",
|
||||
"dependents_count": 23,
|
||||
"risk": "Changes impact 23 modules"
|
||||
}
|
||||
],
|
||||
"orphaned_modules": [
|
||||
{
|
||||
"module": "src/legacy/old_auth.ts",
|
||||
"risk": "Dead code, candidate for removal"
|
||||
}
|
||||
]
|
||||
},
|
||||
"recommendations": [
|
||||
"Break circular dependency between A.ts and B.ts by introducing interface abstraction",
|
||||
"Refactor helpers.ts to reduce coupling (split into domain-specific utilities)"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Execution Patterns
|
||||
|
||||
### Pattern 1: Quick Project Reconnaissance
|
||||
|
||||
**Trigger**: User asks "What's the structure of X module?" or "Where is X defined?"
|
||||
|
||||
**Execution**:
|
||||
```
|
||||
1. Run get_modules_by_depth.sh for structural overview
|
||||
2. Use rg to find definitions: rg "class|function|interface X" -n
|
||||
3. Generate structural overview report
|
||||
4. Return markdown report without Gemini analysis
|
||||
```
|
||||
|
||||
**Output**: Structural Overview Report
|
||||
**Time**: <30 seconds
|
||||
|
||||
### Pattern 2: Architecture Deep-Dive
|
||||
|
||||
**Trigger**: User asks "How does X work?" or "Explain the architecture of X"
|
||||
|
||||
**Execution**:
|
||||
```
|
||||
1. Phase 1 (Bash): Scan for standard patterns (classes, functions, imports)
|
||||
2. Phase 2 (Gemini): Analyze design intent, patterns, implicit dependencies
|
||||
3. Phase 3 (Synthesis): Merge results with attribution
|
||||
4. Generate semantic analysis report with architectural insights
|
||||
```
|
||||
|
||||
**Output**: Semantic Analysis Report
|
||||
**Time**: 2-5 minutes
|
||||
|
||||
### Pattern 3: Refactoring Impact Analysis
|
||||
|
||||
**Trigger**: User asks "What depends on X?" or "Impact of changing X?"
|
||||
|
||||
**Execution**:
|
||||
```
|
||||
1. Build dependency graph using rg for direct dependencies
|
||||
2. Use Gemini to discover runtime/implicit dependencies
|
||||
3. Detect circular dependencies and high-coupling modules
|
||||
4. Calculate change risk scores
|
||||
5. Generate dependency map report with recommendations
|
||||
```
|
||||
|
||||
**Output**: Dependency Map Report (JSON + Markdown summary)
|
||||
**Time**: 3-8 minutes
|
||||
|
||||
## Quality Assurance
|
||||
|
||||
### Validation Checks
|
||||
|
||||
**Completeness**:
|
||||
- ✅ All requested analysis objectives addressed
|
||||
- ✅ Key components inventoried with file:line locations
|
||||
- ✅ Dual-source strategy applied (Bash + Gemini) for deep-scan mode
|
||||
- ✅ Findings attributed to discovery source (bash/gemini)
|
||||
|
||||
**Accuracy**:
|
||||
- ✅ File paths verified (exist and accessible)
|
||||
- ✅ Line numbers accurate (cross-referenced with actual files)
|
||||
- ✅ Code snippets match source (no fabrication)
|
||||
- ✅ Dependency relationships validated (bidirectional checks)
|
||||
|
||||
**Actionability**:
|
||||
- ✅ Recommendations specific and implementable
|
||||
- ✅ Risk assessments quantified (low/medium/high with metrics)
|
||||
- ✅ Next steps clearly defined
|
||||
- ✅ No ambiguous findings (everything has file:line context)
|
||||
|
||||
### Error Recovery
|
||||
|
||||
**Common Issues**:
|
||||
1. **Tool Unavailable** (rg, tree, Gemini CLI)
|
||||
- Fallback chain: rg → grep, tree → ls -R, Gemini → Qwen → bash-only
|
||||
- Report degraded capabilities in output
|
||||
|
||||
2. **Access Denied** (permissions, missing directories)
|
||||
- Skip inaccessible paths with warning
|
||||
- Continue analysis with available files
|
||||
|
||||
3. **Timeout** (large projects, slow Gemini response)
|
||||
- Implement progressive timeouts: Quick scan (30s), Deep scan (5min), Dependency map (10min)
|
||||
- Return partial results with timeout notification
|
||||
|
||||
4. **Ambiguous Patterns** (conflicting interpretations)
|
||||
- Use Gemini semantic analysis as tiebreaker
|
||||
- Document uncertainty in report with attribution
|
||||
|
||||
## Integration with Other Agents
|
||||
|
||||
### As Service Provider (Called by Others)
|
||||
|
||||
**Planning Agents** (`action-planning-agent`, `conceptual-planning-agent`):
|
||||
- **Use Case**: Pre-planning reconnaissance to understand existing code
|
||||
- **Input**: Task description + focus areas
|
||||
- **Output**: Structural overview + dependency analysis
|
||||
- **Flow**: Planning agent → CLI explore agent (quick-scan) → Context for planning
|
||||
|
||||
**Execution Agents** (`code-developer`, `cli-execution-agent`):
|
||||
- **Use Case**: Refactoring impact analysis before code modifications
|
||||
- **Input**: Target files/functions to modify
|
||||
- **Output**: Dependency map + risk assessment
|
||||
- **Flow**: Execution agent → CLI explore agent (dependency-map) → Safe modification strategy
|
||||
|
||||
**UI Design Agent** (`ui-design-agent`):
|
||||
- **Use Case**: Discover existing UI components and design tokens
|
||||
- **Input**: Component directory + file patterns
|
||||
- **Output**: Component inventory + styling patterns
|
||||
- **Flow**: UI agent delegates structure analysis to CLI explore agent
|
||||
|
||||
### As Consumer (Calls Others)
|
||||
|
||||
**Context Search Agent** (`context-search-agent`):
|
||||
- **Use Case**: Get project-wide context before analysis
|
||||
- **Flow**: CLI explore agent → Context search agent → Enhanced analysis with full context
|
||||
|
||||
**MCP Tools**:
|
||||
- **Use Case**: Enhanced file discovery and search capabilities
|
||||
- **Flow**: CLI explore agent → Code Index MCP → Faster pattern discovery
|
||||
|
||||
## Key Reminders
|
||||
|
||||
### ALWAYS
|
||||
|
||||
**Analysis Integrity**: ✅ Read-only operations | ✅ No file modifications | ✅ No state persistence | ✅ Verify file paths before reporting
|
||||
|
||||
**Dual-Source Strategy** (Deep-Scan Mode): ✅ Execute Bash scan first (Phase 1) | ✅ Run Gemini analysis (Phase 2) | ✅ Synthesize with attribution (Phase 3) | ✅ Cross-validate findings
|
||||
|
||||
**Tool Chain**: ✅ Prefer Code Index MCP when available | ✅ Fallback to rg/bash tools | ✅ Use Gemini CLI for semantic analysis (Qwen as fallback) | ✅ Handle tool unavailability gracefully
|
||||
|
||||
**Output Standards**: ✅ Include file:line locations | ✅ Attribute findings to source (bash/gemini) | ✅ Provide actionable recommendations | ✅ Use standardized report formats
|
||||
|
||||
**Mode Selection**: ✅ Match mode to task intent (quick-scan for simple queries, deep-scan for architecture, dependency-map for refactoring) | ✅ Communicate mode choice to user
|
||||
|
||||
### NEVER
|
||||
|
||||
**File Operations**: ❌ Modify files | ❌ Create/delete files | ❌ Execute write operations | ❌ Run build/test commands that change state
|
||||
|
||||
**Analysis Scope**: ❌ Exceed requested scope | ❌ Analyze unrelated modules | ❌ Include irrelevant findings | ❌ Mix multiple unrelated queries
|
||||
|
||||
**Output Quality**: ❌ Fabricate code snippets | ❌ Guess file locations | ❌ Report unverified dependencies | ❌ Provide ambiguous recommendations without context
|
||||
|
||||
**Tool Usage**: ❌ Skip Bash scan in deep-scan mode | ❌ Use Gemini for quick-scan mode (overkill) | ❌ Ignore fallback chain when tool fails | ❌ Proceed with incomplete tool setup
|
||||
|
||||
---
|
||||
|
||||
## Command Templates by Language
|
||||
|
||||
### TypeScript/JavaScript
|
||||
|
||||
```bash
|
||||
# Quick structural scan
|
||||
rg "^export (class|interface|type|function|const) " --type ts -n
|
||||
|
||||
# Find component definitions (React)
|
||||
rg "^export (default )?(function|const) \w+.*=.*\(" --type tsx -n
|
||||
|
||||
# Find imports
|
||||
rg "^import .* from ['\"](.+)['\"]" --type ts -o -r '$1'
|
||||
|
||||
# Find test files
|
||||
find . -name "*.test.ts" -o -name "*.spec.ts" | grep -v node_modules
|
||||
```
|
||||
|
||||
### Python
|
||||
|
||||
```bash
|
||||
# Find class definitions
|
||||
rg "^class \w+.*:" --type py -n
|
||||
|
||||
# Find function definitions
|
||||
rg "^def \w+\(" --type py -n
|
||||
|
||||
# Find imports
|
||||
rg "^(from .* import|import )" --type py -n
|
||||
|
||||
# Find test files
|
||||
find . -name "test_*.py" -o -name "*_test.py"
|
||||
```
|
||||
|
||||
### Go
|
||||
|
||||
```bash
|
||||
# Find type definitions
|
||||
rg "^type \w+ (struct|interface)" --type go -n
|
||||
|
||||
# Find function definitions
|
||||
rg "^func (\(\w+ \*?\w+\) )?\w+\(" --type go -n
|
||||
|
||||
# Find imports
|
||||
rg "^import \(" --type go -A 10
|
||||
|
||||
# Find test files
|
||||
find . -name "*_test.go"
|
||||
```
|
||||
|
||||
### Java
|
||||
|
||||
```bash
|
||||
# Find class definitions
|
||||
rg "^(public |private |protected )?(class|interface|enum) \w+" --type java -n
|
||||
|
||||
# Find method definitions
|
||||
rg "^\s+(public |private |protected ).*\w+\(.*\)" --type java -n
|
||||
|
||||
# Find imports
|
||||
rg "^import .*;" --type java -n
|
||||
|
||||
# Find test files
|
||||
find . -name "*Test.java" -o -name "*Tests.java"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Caching Strategy (Optional)
|
||||
|
||||
**Project Structure Cache**:
|
||||
- Cache `get_modules_by_depth.sh` output for 1 hour
|
||||
- Invalidate on file system changes (watch .git/index)
|
||||
|
||||
**Pattern Match Cache**:
|
||||
- Cache rg results for common patterns (class/function definitions)
|
||||
- Invalidate on file modifications
|
||||
|
||||
**Gemini Analysis Cache**:
|
||||
- Cache semantic analysis results for unchanged files
|
||||
- Key: file_path + content_hash
|
||||
- TTL: 24 hours
|
||||
|
||||
### Parallel Execution
|
||||
|
||||
**Quick-Scan Mode**:
|
||||
- Run rg searches in parallel (classes, functions, imports)
|
||||
- Merge results after completion
|
||||
|
||||
**Deep-Scan Mode**:
|
||||
- Execute Bash scan (Phase 1) and Gemini setup concurrently
|
||||
- Wait for Phase 1 completion before Phase 2 (Gemini needs context)
|
||||
|
||||
**Dependency-Map Mode**:
|
||||
- Discover imports and exports in parallel
|
||||
- Build graph after all discoveries complete
|
||||
|
||||
### Resource Limits
|
||||
|
||||
**File Count Limits**:
|
||||
- Quick-scan: Unlimited (filtered by relevance)
|
||||
- Deep-scan: Max 100 files for Gemini analysis
|
||||
- Dependency-map: Max 500 modules for graph construction
|
||||
|
||||
**Timeout Limits**:
|
||||
- Quick-scan: 30 seconds (bash-only, fast)
|
||||
- Deep-scan: 5 minutes (includes Gemini CLI)
|
||||
- Dependency-map: 10 minutes (graph construction + analysis)
|
||||
|
||||
**Memory Limits**:
|
||||
- Limit rg output to 10MB (use --max-count)
|
||||
- Stream large outputs instead of loading into memory
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,764 @@
|
||||
---
|
||||
name: code-map-memory
|
||||
description: 3-phase orchestrator: parse feature keyword → cli-explore-agent analyzes (Deep Scan dual-source) → orchestrator generates Mermaid docs + SKILL package (skips phase 2 if exists)
|
||||
argument-hint: "\"feature-keyword\" [--regenerate] [--tool <gemini|qwen>]"
|
||||
allowed-tools: SlashCommand(*), TodoWrite(*), Bash(*), Read(*), Write(*), Task(*)
|
||||
---
|
||||
|
||||
# Code Flow Mapping Generator
|
||||
|
||||
## Overview
|
||||
|
||||
**Pure Orchestrator with Agent Delegation**: Prepares context paths and delegates code flow analysis to specialized cli-explore-agent. Orchestrator transforms agent's JSON analysis into Mermaid documentation.
|
||||
|
||||
**Auto-Continue Workflow**: Runs fully autonomously once triggered. Each phase completes and automatically triggers the next phase.
|
||||
|
||||
**Execution Paths**:
|
||||
- **Full Path**: All 3 phases (no existing codemap OR `--regenerate` specified)
|
||||
- **Skip Path**: Phase 1 → Phase 3 (existing codemap found AND no `--regenerate` flag)
|
||||
- **Phase 3 Always Executes**: SKILL index is always generated or updated
|
||||
|
||||
**Agent Responsibility** (cli-explore-agent):
|
||||
- Deep code flow analysis using dual-source strategy (Bash + Gemini CLI)
|
||||
- Returns structured JSON with architecture, functions, data flow, conditionals, patterns
|
||||
- NO file writing - analysis only
|
||||
|
||||
**Orchestrator Responsibility**:
|
||||
- Provides feature keyword and analysis scope to agent
|
||||
- Transforms agent's JSON into Mermaid-enriched markdown documentation
|
||||
- Writes all files (5 docs + metadata.json + SKILL.md)
|
||||
|
||||
## Core Rules
|
||||
|
||||
1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 execution
|
||||
2. **Feature-Specific SKILL**: Each feature creates independent `.claude/skills/codemap-{feature}/` package
|
||||
3. **Specialized Agent**: Phase 2a uses cli-explore-agent for professional code analysis (Deep Scan mode)
|
||||
4. **Orchestrator Documentation**: Phase 2b transforms agent JSON into Mermaid markdown files
|
||||
5. **Auto-Continue**: After completing each phase, update TodoWrite and immediately execute next phase
|
||||
6. **No User Prompts**: Never ask user questions or wait for input between phases
|
||||
7. **Track Progress**: Update TodoWrite after EVERY phase completion before starting next phase
|
||||
8. **Multi-Level Detail**: Generate 4 levels: architecture → function → data → conditional
|
||||
|
||||
---
|
||||
|
||||
## 3-Phase Execution
|
||||
|
||||
### Phase 1: Parse Feature Keyword & Check Existing
|
||||
|
||||
**Goal**: Normalize feature keyword, check existing codemap, prepare for analysis
|
||||
|
||||
**Step 1: Parse Feature Keyword**
|
||||
```bash
|
||||
# Get feature keyword from argument
|
||||
FEATURE_KEYWORD="$1"
|
||||
|
||||
# Normalize: lowercase, spaces to hyphens
|
||||
normalized_feature=$(echo "$FEATURE_KEYWORD" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr '_' '-')
|
||||
|
||||
# Example: "User Authentication" → "user-authentication"
|
||||
# Example: "支付处理" → "支付处理" (keep non-ASCII)
|
||||
```
|
||||
|
||||
**Step 2: Set Tool Preference**
|
||||
```bash
|
||||
# Default to gemini unless --tool specified
|
||||
TOOL="${tool_flag:-gemini}"
|
||||
```
|
||||
|
||||
**Step 3: Check Existing Codemap**
|
||||
```bash
|
||||
# Define codemap directory
|
||||
CODEMAP_DIR=".claude/skills/codemap-${normalized_feature}"
|
||||
|
||||
# Check if codemap exists
|
||||
bash(test -d "$CODEMAP_DIR" && echo "exists" || echo "not_exists")
|
||||
|
||||
# Count existing files
|
||||
bash(find "$CODEMAP_DIR" -name "*.md" 2>/dev/null | wc -l || echo 0)
|
||||
```
|
||||
|
||||
**Step 4: Skip Decision**
|
||||
```javascript
|
||||
if (existing_files > 0 && !regenerate_flag) {
|
||||
SKIP_GENERATION = true
|
||||
message = "Codemap already exists, skipping Phase 2. Use --regenerate to force regeneration."
|
||||
} else if (regenerate_flag) {
|
||||
bash(rm -rf "$CODEMAP_DIR")
|
||||
SKIP_GENERATION = false
|
||||
message = "Regenerating codemap from scratch."
|
||||
} else {
|
||||
SKIP_GENERATION = false
|
||||
message = "No existing codemap found, generating new code flow analysis."
|
||||
}
|
||||
```
|
||||
|
||||
**Output Variables**:
|
||||
- `FEATURE_KEYWORD`: Original feature keyword
|
||||
- `normalized_feature`: Normalized feature name for directory
|
||||
- `CODEMAP_DIR`: `.claude/skills/codemap-{feature}`
|
||||
- `TOOL`: CLI tool to use (gemini or qwen)
|
||||
- `SKIP_GENERATION`: Boolean - whether to skip Phase 2
|
||||
|
||||
**TodoWrite**:
|
||||
- If skipping: Mark phase 1 completed, phase 2 completed, phase 3 in_progress
|
||||
- If not skipping: Mark phase 1 completed, phase 2 in_progress
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Code Flow Analysis & Documentation Generation
|
||||
|
||||
**Skip Condition**: Skipped if `SKIP_GENERATION = true`
|
||||
|
||||
**Goal**: Use cli-explore-agent for professional code analysis, then orchestrator generates Mermaid documentation
|
||||
|
||||
**Architecture**: Phase 2a (Agent Analysis) → Phase 2b (Orchestrator Documentation)
|
||||
|
||||
---
|
||||
|
||||
#### Phase 2a: cli-explore-agent Analysis
|
||||
|
||||
**Purpose**: Leverage specialized cli-explore-agent for deep code flow analysis
|
||||
|
||||
**Agent Task Specification**:
|
||||
|
||||
```
|
||||
Task(
|
||||
subagent_type: "cli-explore-agent",
|
||||
description: "Analyze code flow: {FEATURE_KEYWORD}",
|
||||
prompt: "
|
||||
Perform Deep Scan analysis for feature: {FEATURE_KEYWORD}
|
||||
|
||||
**Analysis Mode**: deep-scan (Dual-source: Bash structural scan + Gemini semantic analysis)
|
||||
|
||||
**Analysis Objectives**:
|
||||
1. **Module Architecture**: Identify high-level module organization, interactions, and entry points
|
||||
2. **Function Call Chains**: Trace execution paths, call sequences, and parameter flows
|
||||
3. **Data Transformations**: Map data structure changes and transformation stages
|
||||
4. **Conditional Paths**: Document decision trees, branches, and error handling strategies
|
||||
5. **Design Patterns**: Discover architectural patterns and extract design intent
|
||||
|
||||
**Scope**:
|
||||
- Feature: {FEATURE_KEYWORD}
|
||||
- CLI Tool: {TOOL} (gemini-2.5-pro or qwen coder-model)
|
||||
- File Discovery: MCP Code Index (preferred) + rg fallback
|
||||
- Target: 5-15 most relevant files
|
||||
|
||||
**Expected Output Format**:
|
||||
Return comprehensive analysis as structured JSON:
|
||||
{
|
||||
\"feature\": \"{FEATURE_KEYWORD}\",
|
||||
\"analysis_metadata\": {
|
||||
\"tool_used\": \"gemini|qwen\",
|
||||
\"timestamp\": \"ISO_TIMESTAMP\",
|
||||
\"analysis_mode\": \"deep-scan\"
|
||||
},
|
||||
\"files_analyzed\": [
|
||||
{\"file\": \"path/to/file.ts\", \"relevance\": \"high|medium|low\", \"role\": \"brief description\"}
|
||||
],
|
||||
\"architecture\": {
|
||||
\"overview\": \"High-level description\",
|
||||
\"modules\": [
|
||||
{\"name\": \"ModuleName\", \"file\": \"file:line\", \"responsibility\": \"description\", \"dependencies\": [...]}
|
||||
],
|
||||
\"interactions\": [
|
||||
{\"from\": \"ModuleA\", \"to\": \"ModuleB\", \"type\": \"import|call|data-flow\", \"description\": \"...\"}
|
||||
],
|
||||
\"entry_points\": [
|
||||
{\"function\": \"main\", \"file\": \"file:line\", \"description\": \"...\"}
|
||||
]
|
||||
},
|
||||
\"function_calls\": {
|
||||
\"call_chains\": [
|
||||
{
|
||||
\"chain_id\": 1,
|
||||
\"description\": \"User authentication flow\",
|
||||
\"sequence\": [
|
||||
{\"function\": \"login\", \"file\": \"file:line\", \"calls\": [\"validateCredentials\", \"createSession\"]}
|
||||
]
|
||||
}
|
||||
],
|
||||
\"sequences\": [
|
||||
{\"from\": \"Client\", \"to\": \"AuthService\", \"method\": \"login(username, password)\", \"returns\": \"Session\"}
|
||||
]
|
||||
},
|
||||
\"data_flow\": {
|
||||
\"structures\": [
|
||||
{\"name\": \"UserData\", \"stage\": \"input\", \"shape\": {\"username\": \"string\", \"password\": \"string\"}}
|
||||
],
|
||||
\"transformations\": [
|
||||
{\"from\": \"RawInput\", \"to\": \"ValidatedData\", \"transformer\": \"validateUser\", \"file\": \"file:line\"}
|
||||
]
|
||||
},
|
||||
\"conditional_logic\": {
|
||||
\"branches\": [
|
||||
{\"condition\": \"isAuthenticated\", \"file\": \"file:line\", \"true_path\": \"...\", \"false_path\": \"...\"}
|
||||
],
|
||||
\"error_handling\": [
|
||||
{\"error_type\": \"AuthenticationError\", \"handler\": \"handleAuthError\", \"file\": \"file:line\", \"recovery\": \"retry|fail\"}
|
||||
]
|
||||
},
|
||||
\"design_patterns\": [
|
||||
{\"pattern\": \"Repository Pattern\", \"location\": \"src/repositories\", \"description\": \"...\"}
|
||||
],
|
||||
\"recommendations\": [
|
||||
\"Consider extracting authentication logic into separate module\",
|
||||
\"Add error recovery for network failures\"
|
||||
]
|
||||
}
|
||||
|
||||
**Critical Requirements**:
|
||||
- Use Deep Scan mode: Bash (Phase 1 - precise locations) + Gemini CLI (Phase 2 - semantic understanding) + Synthesis (Phase 3 - merge with attribution)
|
||||
- Focus exclusively on {FEATURE_KEYWORD} feature flow
|
||||
- Include file:line references for ALL findings
|
||||
- Extract design intent from code structure and comments
|
||||
- NO FILE WRITING - return JSON analysis only
|
||||
- Handle tool failures gracefully (Gemini → Qwen fallback, MCP → rg fallback)
|
||||
"
|
||||
)
|
||||
```
|
||||
|
||||
**Agent Output**: JSON analysis result with architecture, functions, data flow, conditionals, and patterns
|
||||
|
||||
---
|
||||
|
||||
#### Phase 2b: Orchestrator Documentation Generation
|
||||
|
||||
**Purpose**: Transform cli-explore-agent JSON into Mermaid-enriched documentation
|
||||
|
||||
**Input**: Agent's JSON analysis result
|
||||
|
||||
**Process**:
|
||||
|
||||
1. **Parse Agent Analysis**:
|
||||
```javascript
|
||||
const analysis = JSON.parse(agentResult)
|
||||
const { feature, files_analyzed, architecture, function_calls, data_flow, conditional_logic, design_patterns } = analysis
|
||||
```
|
||||
|
||||
2. **Generate Mermaid Diagrams from Structured Data**:
|
||||
|
||||
**a) architecture-flow.md** (~3K tokens):
|
||||
```javascript
|
||||
// Convert architecture.modules + architecture.interactions → Mermaid graph TD
|
||||
const architectureMermaid = `
|
||||
graph TD
|
||||
${architecture.modules.map(m => ` ${m.name}[${m.name}]`).join('\n')}
|
||||
${architecture.interactions.map(i => ` ${i.from} -->|${i.type}| ${i.to}`).join('\n')}
|
||||
`
|
||||
|
||||
Write({
|
||||
file_path: `${CODEMAP_DIR}/architecture-flow.md`,
|
||||
content: `---
|
||||
feature: ${feature}
|
||||
level: architecture
|
||||
detail: high-level module interactions
|
||||
---
|
||||
# Architecture Flow: ${feature}
|
||||
|
||||
## Overview
|
||||
${architecture.overview}
|
||||
|
||||
## Module Architecture
|
||||
${architecture.modules.map(m => `### ${m.name}\n- **File**: ${m.file}\n- **Role**: ${m.responsibility}\n- **Dependencies**: ${m.dependencies.join(', ')}`).join('\n\n')}
|
||||
|
||||
## Flow Diagram
|
||||
\`\`\`mermaid
|
||||
${architectureMermaid}
|
||||
\`\`\`
|
||||
|
||||
## Key Interactions
|
||||
${architecture.interactions.map(i => `- **${i.from} → ${i.to}**: ${i.description}`).join('\n')}
|
||||
|
||||
## Entry Points
|
||||
${architecture.entry_points.map(e => `- **${e.function}** (${e.file}): ${e.description}`).join('\n')}
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
**b) function-calls.md** (~5K tokens):
|
||||
```javascript
|
||||
// Convert function_calls.sequences → Mermaid sequenceDiagram
|
||||
const sequenceMermaid = `
|
||||
sequenceDiagram
|
||||
${function_calls.sequences.map(s => ` ${s.from}->>${s.to}: ${s.method}`).join('\n')}
|
||||
`
|
||||
|
||||
Write({
|
||||
file_path: `${CODEMAP_DIR}/function-calls.md`,
|
||||
content: `---
|
||||
feature: ${feature}
|
||||
level: function
|
||||
detail: function-level call sequences
|
||||
---
|
||||
# Function Call Chains: ${feature}
|
||||
|
||||
## Call Sequence Diagram
|
||||
\`\`\`mermaid
|
||||
${sequenceMermaid}
|
||||
\`\`\`
|
||||
|
||||
## Detailed Call Chains
|
||||
${function_calls.call_chains.map(chain => `
|
||||
### Chain ${chain.chain_id}: ${chain.description}
|
||||
${chain.sequence.map(fn => `- **${fn.function}** (${fn.file})\n - Calls: ${fn.calls.join(', ')}`).join('\n')}
|
||||
`).join('\n')}
|
||||
|
||||
## Parameters & Returns
|
||||
${function_calls.sequences.map(s => `- **${s.method}** → Returns: ${s.returns || 'void'}`).join('\n')}
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
**c) data-flow.md** (~4K tokens):
|
||||
```javascript
|
||||
// Convert data_flow.transformations → Mermaid flowchart LR
|
||||
const dataFlowMermaid = `
|
||||
flowchart LR
|
||||
${data_flow.transformations.map((t, i) => ` Stage${i}[${t.from}] -->|${t.transformer}| Stage${i+1}[${t.to}]`).join('\n')}
|
||||
`
|
||||
|
||||
Write({
|
||||
file_path: `${CODEMAP_DIR}/data-flow.md`,
|
||||
content: `---
|
||||
feature: ${feature}
|
||||
level: data
|
||||
detail: data structure transformations
|
||||
---
|
||||
# Data Flow: ${feature}
|
||||
|
||||
## Data Transformation Diagram
|
||||
\`\`\`mermaid
|
||||
${dataFlowMermaid}
|
||||
\`\`\`
|
||||
|
||||
## Data Structures
|
||||
${data_flow.structures.map(s => `### ${s.name} (${s.stage})\n\`\`\`json\n${JSON.stringify(s.shape, null, 2)}\n\`\`\``).join('\n\n')}
|
||||
|
||||
## Transformations
|
||||
${data_flow.transformations.map(t => `- **${t.from} → ${t.to}** via \`${t.transformer}\` (${t.file})`).join('\n')}
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
**d) conditional-paths.md** (~4K tokens):
|
||||
```javascript
|
||||
// Convert conditional_logic.branches → Mermaid flowchart TD
|
||||
const conditionalMermaid = `
|
||||
flowchart TD
|
||||
Start[Entry Point]
|
||||
${conditional_logic.branches.map((b, i) => `
|
||||
Start --> Check${i}{${b.condition}}
|
||||
Check${i} -->|Yes| Path${i}A[${b.true_path}]
|
||||
Check${i} -->|No| Path${i}B[${b.false_path}]
|
||||
`).join('\n')}
|
||||
`
|
||||
|
||||
Write({
|
||||
file_path: `${CODEMAP_DIR}/conditional-paths.md`,
|
||||
content: `---
|
||||
feature: ${feature}
|
||||
level: conditional
|
||||
detail: decision trees and error paths
|
||||
---
|
||||
# Conditional Paths: ${feature}
|
||||
|
||||
## Decision Tree
|
||||
\`\`\`mermaid
|
||||
${conditionalMermaid}
|
||||
\`\`\`
|
||||
|
||||
## Branch Conditions
|
||||
${conditional_logic.branches.map(b => `- **${b.condition}** (${b.file})\n - True: ${b.true_path}\n - False: ${b.false_path}`).join('\n')}
|
||||
|
||||
## Error Handling
|
||||
${conditional_logic.error_handling.map(e => `- **${e.error_type}**: Handler \`${e.handler}\` (${e.file}) - Recovery: ${e.recovery}`).join('\n')}
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
**e) complete-flow.md** (~8K tokens):
|
||||
```javascript
|
||||
// Integrate all Mermaid diagrams
|
||||
Write({
|
||||
file_path: `${CODEMAP_DIR}/complete-flow.md`,
|
||||
content: `---
|
||||
feature: ${feature}
|
||||
level: complete
|
||||
detail: integrated multi-level view
|
||||
---
|
||||
# Complete Flow: ${feature}
|
||||
|
||||
## Integrated Flow Diagram
|
||||
\`\`\`mermaid
|
||||
graph TB
|
||||
subgraph Architecture
|
||||
${architecture.modules.map(m => ` ${m.name}[${m.name}]`).join('\n')}
|
||||
end
|
||||
|
||||
subgraph "Function Calls"
|
||||
${function_calls.call_chains[0]?.sequence.map(fn => ` ${fn.function}`).join('\n') || ''}
|
||||
end
|
||||
|
||||
subgraph "Data Flow"
|
||||
${data_flow.structures.map(s => ` ${s.name}[${s.name}]`).join('\n')}
|
||||
end
|
||||
\`\`\`
|
||||
|
||||
## Complete Trace
|
||||
[Comprehensive end-to-end documentation combining all analysis layers]
|
||||
|
||||
## Design Patterns Identified
|
||||
${design_patterns.map(p => `- **${p.pattern}** in ${p.location}: ${p.description}`).join('\n')}
|
||||
|
||||
## Recommendations
|
||||
${analysis.recommendations.map(r => `- ${r}`).join('\n')}
|
||||
|
||||
## Cross-References
|
||||
- [Architecture Flow](./architecture-flow.md) - High-level module structure
|
||||
- [Function Calls](./function-calls.md) - Detailed call chains
|
||||
- [Data Flow](./data-flow.md) - Data transformation stages
|
||||
- [Conditional Paths](./conditional-paths.md) - Decision trees and error handling
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
3. **Write metadata.json**:
|
||||
```javascript
|
||||
Write({
|
||||
file_path: `${CODEMAP_DIR}/metadata.json`,
|
||||
content: JSON.stringify({
|
||||
feature: feature,
|
||||
normalized_name: normalized_feature,
|
||||
generated_at: new Date().toISOString(),
|
||||
tool_used: analysis.analysis_metadata.tool_used,
|
||||
files_analyzed: files_analyzed.map(f => f.file),
|
||||
analysis_summary: {
|
||||
total_files: files_analyzed.length,
|
||||
modules_traced: architecture.modules.length,
|
||||
functions_traced: function_calls.call_chains.reduce((sum, c) => sum + c.sequence.length, 0),
|
||||
patterns_discovered: design_patterns.length
|
||||
}
|
||||
}, null, 2)
|
||||
})
|
||||
```
|
||||
|
||||
4. **Report Phase 2 Completion**:
|
||||
```
|
||||
Phase 2 Complete: Code flow analysis and documentation generated
|
||||
|
||||
- Agent Analysis: cli-explore-agent with {TOOL}
|
||||
- Files Analyzed: {count}
|
||||
- Documentation Generated: 5 markdown files + metadata.json
|
||||
- Location: {CODEMAP_DIR}
|
||||
```
|
||||
|
||||
**Completion Criteria**:
|
||||
- cli-explore-agent task completed successfully with JSON result
|
||||
- 5 documentation files written with valid Mermaid diagrams
|
||||
- metadata.json written with analysis summary
|
||||
- All files properly formatted and cross-referenced
|
||||
|
||||
**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Generate SKILL.md Index
|
||||
|
||||
**Note**: This phase **ALWAYS executes** - generates or updates the SKILL index.
|
||||
|
||||
**Goal**: Read generated flow documentation and create SKILL.md index with progressive loading
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. **Verify Generated Files**:
|
||||
```bash
|
||||
bash(find "{CODEMAP_DIR}" -name "*.md" -type f | sort)
|
||||
```
|
||||
|
||||
2. **Read metadata.json**:
|
||||
```javascript
|
||||
Read({CODEMAP_DIR}/metadata.json)
|
||||
// Extract: feature, normalized_name, files_analyzed, analysis_summary
|
||||
```
|
||||
|
||||
3. **Read File Headers** (optional, first 30 lines):
|
||||
```javascript
|
||||
Read({CODEMAP_DIR}/architecture-flow.md, limit: 30)
|
||||
Read({CODEMAP_DIR}/function-calls.md, limit: 30)
|
||||
// Extract overview and diagram counts
|
||||
```
|
||||
|
||||
4. **Generate SKILL.md Index**:
|
||||
|
||||
Template structure:
|
||||
```yaml
|
||||
---
|
||||
name: codemap-{normalized_feature}
|
||||
description: Code flow mapping for {FEATURE_KEYWORD} feature (located at {project_path}). Load this SKILL when analyzing, tracing, or understanding {FEATURE_KEYWORD} execution flow, especially when no relevant context exists in memory.
|
||||
version: 1.0.0
|
||||
generated_at: {ISO_TIMESTAMP}
|
||||
---
|
||||
# Code Flow Map: {FEATURE_KEYWORD}
|
||||
|
||||
## Feature: `{FEATURE_KEYWORD}`
|
||||
|
||||
**Analysis Date**: {DATE}
|
||||
**Tool Used**: {TOOL}
|
||||
**Files Analyzed**: {COUNT}
|
||||
|
||||
## Progressive Loading
|
||||
|
||||
### Level 0: Quick Overview (~2K tokens)
|
||||
- [Architecture Flow](./architecture-flow.md) - High-level module interactions
|
||||
|
||||
### Level 1: Core Flows (~10K tokens)
|
||||
- [Architecture Flow](./architecture-flow.md) - Module architecture
|
||||
- [Function Calls](./function-calls.md) - Function call chains
|
||||
|
||||
### Level 2: Complete Analysis (~20K tokens)
|
||||
- [Architecture Flow](./architecture-flow.md)
|
||||
- [Function Calls](./function-calls.md)
|
||||
- [Data Flow](./data-flow.md) - Data transformations
|
||||
|
||||
### Level 3: Deep Dive (~30K tokens)
|
||||
- [Architecture Flow](./architecture-flow.md)
|
||||
- [Function Calls](./function-calls.md)
|
||||
- [Data Flow](./data-flow.md)
|
||||
- [Conditional Paths](./conditional-paths.md) - Branches and error handling
|
||||
- [Complete Flow](./complete-flow.md) - Integrated comprehensive view
|
||||
|
||||
## Usage
|
||||
|
||||
Load this SKILL package when:
|
||||
- Analyzing {FEATURE_KEYWORD} implementation
|
||||
- Tracing execution flow for debugging
|
||||
- Understanding code dependencies
|
||||
- Planning refactoring or enhancements
|
||||
|
||||
## Analysis Summary
|
||||
|
||||
- **Modules Traced**: {modules_traced}
|
||||
- **Functions Traced**: {functions_traced}
|
||||
- **Files Analyzed**: {total_files}
|
||||
|
||||
## Mermaid Diagrams Included
|
||||
|
||||
- Architecture flow diagram (graph TD)
|
||||
- Function call sequence diagram (sequenceDiagram)
|
||||
- Data transformation flowchart (flowchart LR)
|
||||
- Conditional decision tree (flowchart TD)
|
||||
- Complete integrated diagram (graph TB)
|
||||
```
|
||||
|
||||
5. **Write SKILL.md**:
|
||||
```javascript
|
||||
Write({
|
||||
file_path: `{CODEMAP_DIR}/SKILL.md`,
|
||||
content: generatedIndexMarkdown
|
||||
})
|
||||
```
|
||||
|
||||
**Completion Criteria**:
|
||||
- SKILL.md index written
|
||||
- All documentation files verified
|
||||
- Progressive loading levels (0-3) properly structured
|
||||
- Mermaid diagram references included
|
||||
|
||||
**TodoWrite**: Mark phase 3 completed
|
||||
|
||||
**Final Report**:
|
||||
```
|
||||
Code Flow Mapping Complete
|
||||
|
||||
Feature: {FEATURE_KEYWORD}
|
||||
Location: .claude/skills/codemap-{normalized_feature}/
|
||||
|
||||
Files Generated:
|
||||
- SKILL.md (index)
|
||||
- architecture-flow.md (with Mermaid diagram)
|
||||
- function-calls.md (with Mermaid sequence diagram)
|
||||
- data-flow.md (with Mermaid flowchart)
|
||||
- conditional-paths.md (with Mermaid decision tree)
|
||||
- complete-flow.md (with integrated Mermaid diagram)
|
||||
- metadata.json
|
||||
|
||||
Analysis:
|
||||
- Files analyzed: {count}
|
||||
- Modules traced: {count}
|
||||
- Functions traced: {count}
|
||||
|
||||
Usage: Skill(command: "codemap-{normalized_feature}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### TodoWrite Patterns
|
||||
|
||||
**Initialization** (Before Phase 1):
|
||||
```javascript
|
||||
TodoWrite({todos: [
|
||||
{"content": "Parse feature keyword and check existing", "status": "in_progress", "activeForm": "Parsing feature keyword"},
|
||||
{"content": "Agent analyzes code flow and generates files", "status": "pending", "activeForm": "Analyzing code flow"},
|
||||
{"content": "Generate SKILL.md index", "status": "pending", "activeForm": "Generating SKILL index"}
|
||||
]})
|
||||
```
|
||||
|
||||
**Full Path** (SKIP_GENERATION = false):
|
||||
```javascript
|
||||
// After Phase 1
|
||||
TodoWrite({todos: [
|
||||
{"content": "Parse feature keyword and check existing", "status": "completed", ...},
|
||||
{"content": "Agent analyzes code flow and generates files", "status": "in_progress", ...},
|
||||
{"content": "Generate SKILL.md index", "status": "pending", ...}
|
||||
]})
|
||||
|
||||
// After Phase 2
|
||||
TodoWrite({todos: [
|
||||
{"content": "Parse feature keyword and check existing", "status": "completed", ...},
|
||||
{"content": "Agent analyzes code flow and generates files", "status": "completed", ...},
|
||||
{"content": "Generate SKILL.md index", "status": "in_progress", ...}
|
||||
]})
|
||||
|
||||
// After Phase 3
|
||||
TodoWrite({todos: [
|
||||
{"content": "Parse feature keyword and check existing", "status": "completed", ...},
|
||||
{"content": "Agent analyzes code flow and generates files", "status": "completed", ...},
|
||||
{"content": "Generate SKILL.md index", "status": "completed", ...}
|
||||
]})
|
||||
```
|
||||
|
||||
**Skip Path** (SKIP_GENERATION = true):
|
||||
```javascript
|
||||
// After Phase 1 (skip Phase 2)
|
||||
TodoWrite({todos: [
|
||||
{"content": "Parse feature keyword and check existing", "status": "completed", ...},
|
||||
{"content": "Agent analyzes code flow and generates files", "status": "completed", ...}, // Skipped
|
||||
{"content": "Generate SKILL.md index", "status": "in_progress", ...}
|
||||
]})
|
||||
```
|
||||
|
||||
### Execution Flow
|
||||
|
||||
**Full Path**:
|
||||
```
|
||||
User → TodoWrite Init → Phase 1 (parse) → Phase 2 (agent analyzes) → Phase 3 (write index) → Report
|
||||
```
|
||||
|
||||
**Skip Path**:
|
||||
```
|
||||
User → TodoWrite Init → Phase 1 (detect existing) → Phase 3 (update index) → Report
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
**Phase 1 Errors**:
|
||||
- Empty feature keyword: Report error, ask user to provide feature description
|
||||
- Invalid characters: Normalize and continue
|
||||
|
||||
**Phase 2 Errors (Agent)**:
|
||||
- Agent task fails: Retry once, report if fails again
|
||||
- No files discovered: Warn user, ask for more specific feature keyword
|
||||
- CLI failures: Agent handles internally with retries
|
||||
- Invalid Mermaid syntax: Agent validates before writing
|
||||
|
||||
**Phase 3 Errors**:
|
||||
- Write failures: Report which files failed
|
||||
- Missing files: Note in SKILL.md, suggest regeneration
|
||||
|
||||
---
|
||||
|
||||
## Parameters
|
||||
|
||||
```bash
|
||||
/memory:code-map-memory "feature-keyword" [--regenerate] [--tool <gemini|qwen>]
|
||||
```
|
||||
|
||||
**Arguments**:
|
||||
- **"feature-keyword"**: Feature or flow to analyze (required)
|
||||
- Examples: `"user authentication"`, `"payment processing"`, `"数据导入流程"`
|
||||
- Can be English, Chinese, or mixed
|
||||
- Spaces and underscores normalized to hyphens
|
||||
- **--regenerate**: Force regenerate existing codemap (deletes and recreates)
|
||||
- **--tool**: CLI tool for analysis (default: gemini)
|
||||
- `gemini`: Comprehensive flow analysis with gemini-2.5-pro
|
||||
- `qwen`: Alternative with coder-model
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
**Generated File Structure** (for all examples):
|
||||
```
|
||||
.claude/skills/codemap-{feature}/
|
||||
├── SKILL.md # Index (Phase 3)
|
||||
├── architecture-flow.md # Agent (Phase 2) - High-level flow
|
||||
├── function-calls.md # Agent (Phase 2) - Function chains
|
||||
├── data-flow.md # Agent (Phase 2) - Data transformations
|
||||
├── conditional-paths.md # Agent (Phase 2) - Branches & errors
|
||||
├── complete-flow.md # Agent (Phase 2) - Integrated view
|
||||
└── metadata.json # Agent (Phase 2)
|
||||
```
|
||||
|
||||
### Example 1: User Authentication Flow
|
||||
|
||||
```bash
|
||||
/memory:code-map-memory "user authentication"
|
||||
```
|
||||
|
||||
**Workflow**:
|
||||
1. Phase 1: Normalizes to "user-authentication", checks existing codemap
|
||||
2. Phase 2: Agent discovers auth-related files, executes CLI analysis, generates 5 flow docs with Mermaid
|
||||
3. Phase 3: Generates SKILL.md index with progressive loading
|
||||
|
||||
**Output**: `.claude/skills/codemap-user-authentication/` with 6 files + metadata
|
||||
|
||||
|
||||
### Example 3: Regenerate with Qwen
|
||||
|
||||
```bash
|
||||
/memory:code-map-memory "payment processing" --regenerate --tool qwen
|
||||
```
|
||||
|
||||
**Workflow**:
|
||||
1. Phase 1: Deletes existing codemap due to --regenerate
|
||||
2. Phase 2: Agent uses qwen with coder-model for fresh analysis
|
||||
3. Phase 3: Generates updated SKILL.md
|
||||
|
||||
---
|
||||
|
||||
## Benefits
|
||||
|
||||
- **Per-Feature SKILL**: Independent packages for each analyzed feature
|
||||
- **Specialized Agent**: cli-explore-agent with Deep Scan mode (Bash + Gemini dual-source)
|
||||
- **Professional Analysis**: Pre-defined workflow for code exploration and structure analysis
|
||||
- **Clear Separation**: Agent analyzes (JSON) → Orchestrator documents (Mermaid markdown)
|
||||
- **Multi-Level Detail**: 4 levels (architecture → function → data → conditional)
|
||||
- **Visual Flow**: Embedded Mermaid diagrams for all flow types
|
||||
- **Progressive Loading**: Token-efficient context loading (2K → 30K)
|
||||
- **Auto-Continue**: Fully autonomous 3-phase execution
|
||||
- **Smart Skip**: Detects existing codemap, 10x faster index updates
|
||||
- **CLI Integration**: Gemini/Qwen for deep semantic understanding
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
code-map-memory (orchestrator)
|
||||
├─ Phase 1: Parse & Check (bash commands, skip decision)
|
||||
├─ Phase 2: Code Analysis & Documentation (skippable)
|
||||
│ ├─ Phase 2a: cli-explore-agent Analysis
|
||||
│ │ └─ Deep Scan: Bash structural + Gemini semantic → JSON
|
||||
│ └─ Phase 2b: Orchestrator Documentation
|
||||
│ └─ Transform JSON → 5 Mermaid markdown files + metadata.json
|
||||
└─ Phase 3: Write SKILL.md (index generation, always runs)
|
||||
|
||||
Benefits:
|
||||
✅ Specialized agent: cli-explore-agent with dual-source strategy (Bash + Gemini)
|
||||
✅ Professional analysis: Pre-defined Deep Scan workflow
|
||||
✅ Clear separation: Agent analyzes (JSON) → Orchestrator documents (Mermaid)
|
||||
✅ Smart skip logic: 10x faster when codemap exists
|
||||
✅ Multi-level detail: Architecture → Functions → Data → Conditionals
|
||||
|
||||
Output: .claude/skills/codemap-{feature}/
|
||||
```
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
name: memory:style-skill-memory
|
||||
name: style-skill-memory
|
||||
description: Generate SKILL memory package from style reference for easy loading and consistent design system usage
|
||||
argument-hint: "[package-name] [--regenerate]"
|
||||
allowed-tools: Bash,Read,Write,TodoWrite
|
||||
@@ -18,6 +18,12 @@ auto-continue: true
|
||||
|
||||
**Use Case**: Load design system context when working with UI components, analyzing design patterns, or implementing style guidelines.
|
||||
|
||||
**Key Features**:
|
||||
- Extracts primary design references (colors, typography, spacing, etc.)
|
||||
- Provides dynamic adjustment guidelines for design tokens
|
||||
- Progressive loading structure for efficient token usage
|
||||
- Interactive preview showcase
|
||||
|
||||
---
|
||||
|
||||
## Usage
|
||||
@@ -57,7 +63,7 @@ package-name Style reference package name (required)
|
||||
```json
|
||||
[
|
||||
{"content": "Validate style reference package", "status": "in_progress", "activeForm": "Validating package"},
|
||||
{"content": "Read package metadata and documentation", "status": "pending", "activeForm": "Reading metadata"},
|
||||
{"content": "Read package data and extract design references", "status": "pending", "activeForm": "Reading package data"},
|
||||
{"content": "Generate SKILL.md with progressive loading", "status": "pending", "activeForm": "Generating SKILL.md"}
|
||||
]
|
||||
```
|
||||
@@ -117,80 +123,141 @@ if (regenerate_flag && skill_exists) {
|
||||
```json
|
||||
[
|
||||
{"content": "Validate style reference package", "status": "completed", "activeForm": "Validating package"},
|
||||
{"content": "Read package metadata and documentation", "status": "in_progress", "activeForm": "Reading metadata"}
|
||||
{"content": "Read package data and extract design references", "status": "in_progress", "activeForm": "Reading package data"}
|
||||
]
|
||||
```
|
||||
|
||||
**Next Action**: Continue to Phase 2
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Read Package Metadata
|
||||
### Phase 2: Read Package Data & Extract Design References
|
||||
|
||||
**Purpose**: Extract metadata and documentation for SKILL description generation
|
||||
**Purpose**: Extract package information and primary design references for SKILL description generation
|
||||
|
||||
**Step 1: Read metadata.json**
|
||||
**Step 1: Count Components**
|
||||
|
||||
```bash
|
||||
Read(file_path=".workflow/reference_style/${package_name}/metadata.json")
|
||||
```
|
||||
|
||||
**Extract Fields**:
|
||||
- `packageName`
|
||||
- `version`
|
||||
- `generatedAt`
|
||||
- `description`
|
||||
- `source.design_run`
|
||||
- `files` (count available files)
|
||||
|
||||
**Step 2: Read README.md**
|
||||
|
||||
```bash
|
||||
Read(file_path=".workflow/reference_style/${package_name}/README.md")
|
||||
```
|
||||
|
||||
**Extract Information**:
|
||||
- Package overview
|
||||
- Component catalog reference
|
||||
- Design token categories
|
||||
|
||||
**Step 3: Count Components**
|
||||
|
||||
```bash
|
||||
bash(test -f .workflow/reference_style/${package_name}/component-patterns.json && jq '.extraction_metadata.component_count' .workflow/reference_style/${package_name}/component-patterns.json 2>/dev/null || grep -c '"button"\|"input"\|"card"\|"badge"\|"alert"' .workflow/reference_style/${package_name}/component-patterns.json 2>/dev/null || echo 0)
|
||||
bash(jq '.layout_templates | length' .workflow/reference_style/${package_name}/layout-templates.json 2>/dev/null || echo 0)
|
||||
```
|
||||
|
||||
Store result as `component_count`
|
||||
|
||||
**Step 4: Check Available Files**
|
||||
**Step 2: Extract Component Types and Classification**
|
||||
|
||||
```bash
|
||||
bash(cd .workflow/reference_style/${package_name} && ls -1 *.json *.md *.html *.css 2>/dev/null | wc -l)
|
||||
# Extract component names from layout templates
|
||||
bash(jq -r '.layout_templates | keys[]' .workflow/reference_style/${package_name}/layout-templates.json 2>/dev/null | head -10)
|
||||
|
||||
# Count universal vs specialized components
|
||||
bash(jq '[.layout_templates[] | select(.component_type == "universal")] | length' .workflow/reference_style/${package_name}/layout-templates.json 2>/dev/null || echo 0)
|
||||
bash(jq '[.layout_templates[] | select(.component_type == "specialized")] | length' .workflow/reference_style/${package_name}/layout-templates.json 2>/dev/null || echo 0)
|
||||
|
||||
# Extract universal component names only
|
||||
bash(jq -r '.layout_templates | to_entries | map(select(.value.component_type == "universal")) | .[].key' .workflow/reference_style/${package_name}/layout-templates.json 2>/dev/null | head -10)
|
||||
```
|
||||
|
||||
Store as:
|
||||
- `COMPONENT_TYPES`: List of available component types (all)
|
||||
- `UNIVERSAL_COUNT`: Number of universal (reusable) components
|
||||
- `SPECIALIZED_COUNT`: Number of specialized (project-specific) components
|
||||
- `UNIVERSAL_COMPONENTS`: List of universal component names
|
||||
|
||||
**Step 3: Read Design Tokens**
|
||||
|
||||
```bash
|
||||
Read(file_path=".workflow/reference_style/${package_name}/design-tokens.json")
|
||||
```
|
||||
|
||||
**Extract Primary Design References**:
|
||||
|
||||
**Colors** (top 3-5 most important):
|
||||
```bash
|
||||
bash(jq -r '.colors | to_entries | .[0:5] | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null | head -5)
|
||||
```
|
||||
|
||||
**Typography** (heading and body fonts):
|
||||
```bash
|
||||
bash(jq -r '.typography | to_entries | select(.key | contains("family")) | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null)
|
||||
```
|
||||
|
||||
**Spacing Scale** (base spacing values):
|
||||
```bash
|
||||
bash(jq -r '.spacing | to_entries | .[0:5] | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null)
|
||||
```
|
||||
|
||||
**Border Radius** (base radius values):
|
||||
```bash
|
||||
bash(jq -r '.border_radius | to_entries | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null)
|
||||
```
|
||||
|
||||
**Shadows** (elevation levels):
|
||||
```bash
|
||||
bash(jq -r '.shadows | to_entries | .[0:3] | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null)
|
||||
```
|
||||
|
||||
Store extracted references as:
|
||||
- `PRIMARY_COLORS`: List of primary color tokens
|
||||
- `TYPOGRAPHY_FONTS`: Font family tokens
|
||||
- `SPACING_SCALE`: Base spacing values
|
||||
- `BORDER_RADIUS`: Radius values
|
||||
- `SHADOWS`: Shadow definitions
|
||||
|
||||
**Step 4: Read Animation Tokens (if available)**
|
||||
|
||||
```bash
|
||||
# Check if animation tokens exist
|
||||
bash(test -f .workflow/reference_style/${package_name}/animation-tokens.json && echo "available" || echo "not_available")
|
||||
```
|
||||
|
||||
If available, extract:
|
||||
```bash
|
||||
Read(file_path=".workflow/reference_style/${package_name}/animation-tokens.json")
|
||||
|
||||
# Extract primary animation values
|
||||
bash(jq -r '.duration | to_entries | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/animation-tokens.json 2>/dev/null)
|
||||
bash(jq -r '.easing | to_entries | .[0:3] | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/animation-tokens.json 2>/dev/null)
|
||||
```
|
||||
|
||||
Store as:
|
||||
- `ANIMATION_DURATIONS`: Animation duration tokens
|
||||
- `EASING_FUNCTIONS`: Easing function tokens
|
||||
|
||||
**Step 5: Count Files**
|
||||
|
||||
```bash
|
||||
bash(cd .workflow/reference_style/${package_name} && ls -1 *.json *.html *.css 2>/dev/null | wc -l)
|
||||
```
|
||||
|
||||
Store result as `file_count`
|
||||
|
||||
**Summary Data**:
|
||||
- `COMPONENT_COUNT`: Number of components in catalog
|
||||
**Summary Data Collected**:
|
||||
- `COMPONENT_COUNT`: Number of components in layout templates
|
||||
- `UNIVERSAL_COUNT`: Number of universal (reusable) components
|
||||
- `SPECIALIZED_COUNT`: Number of specialized (project-specific) components
|
||||
- `COMPONENT_TYPES`: List of component types (first 10)
|
||||
- `UNIVERSAL_COMPONENTS`: List of universal component names (first 10)
|
||||
- `FILE_COUNT`: Total files in package
|
||||
- `VERSION`: Package version (from metadata.json)
|
||||
- `DESCRIPTION`: Package description (from metadata.json)
|
||||
- `HAS_ANIMATIONS`: Whether animation tokens are available
|
||||
- `PRIMARY_COLORS`: Primary color tokens with values
|
||||
- `TYPOGRAPHY_FONTS`: Font family tokens
|
||||
- `SPACING_SCALE`: Base spacing scale
|
||||
- `BORDER_RADIUS`: Border radius values
|
||||
- `SHADOWS`: Shadow definitions
|
||||
- `ANIMATION_DURATIONS`: Animation durations (if available)
|
||||
- `EASING_FUNCTIONS`: Easing functions (if available)
|
||||
|
||||
**TodoWrite Update**:
|
||||
```json
|
||||
[
|
||||
{"content": "Read package metadata and documentation", "status": "completed", "activeForm": "Reading metadata"},
|
||||
{"content": "Read package data and extract design references", "status": "completed", "activeForm": "Reading package data"},
|
||||
{"content": "Generate SKILL.md with progressive loading", "status": "in_progress", "activeForm": "Generating SKILL.md"}
|
||||
]
|
||||
```
|
||||
|
||||
**Next Action**: Continue to Phase 3
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Generate SKILL.md
|
||||
|
||||
**Purpose**: Create SKILL memory index with progressive loading structure
|
||||
**Purpose**: Create SKILL memory index with progressive loading structure and design references
|
||||
|
||||
**Step 1: Create SKILL Directory**
|
||||
|
||||
@@ -202,27 +269,30 @@ bash(mkdir -p .claude/skills/style-${package_name})
|
||||
|
||||
**Format**:
|
||||
```
|
||||
{Package Name} design system with {component_count} components and interactive preview (located at .workflow/reference_style/{package_name}). Load when working with UI components, design tokens, style guidelines, analyzing design patterns, or implementing visual consistency.
|
||||
{package_name} project-independent design system with {universal_count} universal layout templates and interactive preview (located at .workflow/reference_style/{package_name}). Load when working with reusable UI components, design tokens, layout patterns, or implementing visual consistency. Excludes {specialized_count} project-specific components.
|
||||
```
|
||||
|
||||
**Key Elements**:
|
||||
- **Component Count**: Emphasize available component catalog
|
||||
- **Universal Count**: Emphasize available reusable layout templates
|
||||
- **Project Independence**: Clearly state project-independent nature
|
||||
- **Specialized Exclusion**: Mention excluded project-specific components
|
||||
- **Path Reference**: Precise package location
|
||||
- **Trigger Keywords**: UI components, design tokens, style guidelines, design patterns
|
||||
- **Trigger Keywords**: reusable UI components, design tokens, layout patterns, visual consistency
|
||||
- **Action Coverage**: working with, analyzing, implementing
|
||||
|
||||
**Example**:
|
||||
```
|
||||
main-app-style-v1 design system with 8 components and interactive preview (located at .workflow/reference_style/main-app-style-v1). Load when working with UI components, design tokens, style guidelines, analyzing design patterns, or implementing visual consistency.
|
||||
main-app-style-v1 project-independent design system with 5 universal layout templates and interactive preview (located at .workflow/reference_style/main-app-style-v1). Load when working with reusable UI components, design tokens, layout patterns, or implementing visual consistency. Excludes 3 project-specific components.
|
||||
```
|
||||
|
||||
**Step 3: Write SKILL.md** (Use Write tool)
|
||||
**Step 3: Write SKILL.md**
|
||||
|
||||
Use Write tool to generate SKILL.md with the following complete content:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: style-{package_name}
|
||||
description: {intelligent description from Step 2}
|
||||
version: {version from metadata.json}
|
||||
---
|
||||
|
||||
# {Package Name} Style SKILL Package
|
||||
@@ -231,64 +301,199 @@ version: {version from metadata.json}
|
||||
|
||||
## Package Overview
|
||||
|
||||
Style reference package with comprehensive design system documentation and interactive component preview.
|
||||
**Project-independent style reference package** extracted from codebase with reusable design patterns, tokens, and interactive preview.
|
||||
|
||||
**Package Details**:
|
||||
- Package: {package_name}
|
||||
- Version: {version}
|
||||
- Components: {component_count}
|
||||
- Layout Templates: {component_count} total
|
||||
- **Universal Components**: {universal_count} (reusable, project-independent)
|
||||
- **Specialized Components**: {specialized_count} (project-specific, excluded from reference)
|
||||
- Universal Component Types: {comma-separated list of UNIVERSAL_COMPONENTS}
|
||||
- Files: {file_count}
|
||||
- Generated: {generatedAt}
|
||||
- Animation Tokens: {has_animations ? "✓ Available" : "Not available"}
|
||||
|
||||
**⚠️ IMPORTANT - Project Independence**:
|
||||
This SKILL package represents a **pure style system** independent of any specific project implementation:
|
||||
- **Universal components** are generic, reusable patterns (buttons, inputs, cards, navigation)
|
||||
- **Specialized components** are project-specific implementations (excluded from this reference)
|
||||
- All design tokens and layout patterns are extracted for **reference purposes only**
|
||||
- Adapt and customize these references based on your project's specific requirements
|
||||
|
||||
---
|
||||
|
||||
## ⚡ Primary Design References
|
||||
|
||||
**IMPORTANT**: These are **reference values** extracted from the codebase. They should be **dynamically adjusted** based on your specific design needs, not treated as fixed constraints.
|
||||
|
||||
### 🎨 Colors
|
||||
|
||||
{FOR each color in PRIMARY_COLORS:
|
||||
- **{color.key}**: `{color.value}`
|
||||
}
|
||||
|
||||
**Usage Guidelines**:
|
||||
- These colors establish the foundation of the design system
|
||||
- Adjust saturation, lightness, or hue based on:
|
||||
- Brand requirements and accessibility needs
|
||||
- Context (light/dark mode, high-contrast themes)
|
||||
- User feedback and A/B testing results
|
||||
- Use color theory principles to maintain harmony when modifying
|
||||
|
||||
### 📝 Typography
|
||||
|
||||
{FOR each font in TYPOGRAPHY_FONTS:
|
||||
- **{font.key}**: `{font.value}`
|
||||
}
|
||||
|
||||
**Usage Guidelines**:
|
||||
- Font families can be substituted based on:
|
||||
- Brand identity and design language
|
||||
- Performance requirements (web fonts vs. system fonts)
|
||||
- Accessibility and readability considerations
|
||||
- Platform-specific availability
|
||||
- Maintain hierarchy and scale relationships when changing fonts
|
||||
|
||||
### 📏 Spacing Scale
|
||||
|
||||
{FOR each spacing in SPACING_SCALE:
|
||||
- **{spacing.key}**: `{spacing.value}`
|
||||
}
|
||||
|
||||
**Usage Guidelines**:
|
||||
- Spacing values form a consistent rhythm system
|
||||
- Adjust scale based on:
|
||||
- Target device (mobile vs. desktop vs. tablet)
|
||||
- Content density requirements
|
||||
- Component-specific needs (compact vs. comfortable layouts)
|
||||
- Maintain proportional relationships when scaling
|
||||
|
||||
### 🔲 Border Radius
|
||||
|
||||
{FOR each radius in BORDER_RADIUS:
|
||||
- **{radius.key}**: `{radius.value}`
|
||||
}
|
||||
|
||||
**Usage Guidelines**:
|
||||
- Border radius affects visual softness and modernity
|
||||
- Adjust based on:
|
||||
- Design aesthetic (sharp vs. rounded vs. pill-shaped)
|
||||
- Component type (buttons, cards, inputs have different needs)
|
||||
- Platform conventions (iOS vs. Android vs. Web)
|
||||
|
||||
### 🌫️ Shadows
|
||||
|
||||
{FOR each shadow in SHADOWS:
|
||||
- **{shadow.key}**: `{shadow.value}`
|
||||
}
|
||||
|
||||
**Usage Guidelines**:
|
||||
- Shadows create elevation and depth perception
|
||||
- Adjust based on:
|
||||
- Material design depth levels
|
||||
- Light/dark mode contexts
|
||||
- Performance considerations (complex shadows impact rendering)
|
||||
- Visual hierarchy needs
|
||||
|
||||
{IF HAS_ANIMATIONS:
|
||||
### ⏱️ Animation & Timing
|
||||
|
||||
**Durations**:
|
||||
{FOR each duration in ANIMATION_DURATIONS:
|
||||
- **{duration.key}**: `{duration.value}`
|
||||
}
|
||||
|
||||
**Easing Functions**:
|
||||
{FOR each easing in EASING_FUNCTIONS:
|
||||
- **{easing.key}**: `{easing.value}`
|
||||
}
|
||||
|
||||
**Usage Guidelines**:
|
||||
- Animation timing affects perceived responsiveness and polish
|
||||
- Adjust based on:
|
||||
- User expectations and platform conventions
|
||||
- Accessibility preferences (reduced motion)
|
||||
- Animation type (micro-interactions vs. page transitions)
|
||||
- Performance constraints (mobile vs. desktop)
|
||||
}
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Design Adaptation Strategies
|
||||
|
||||
### When to Adjust Design References
|
||||
|
||||
**Brand Alignment**:
|
||||
- Modify colors to match brand identity and guidelines
|
||||
- Adjust typography to reflect brand personality
|
||||
- Tune spacing and radius to align with brand aesthetic
|
||||
|
||||
**Accessibility Requirements**:
|
||||
- Increase color contrast ratios for WCAG compliance
|
||||
- Adjust font sizes and spacing for readability
|
||||
- Modify animation durations for reduced-motion preferences
|
||||
|
||||
**Platform Optimization**:
|
||||
- Adapt spacing for mobile touch targets (min 44x44px)
|
||||
- Adjust shadows and radius for platform conventions
|
||||
- Optimize animation performance for target devices
|
||||
|
||||
**Context-Specific Needs**:
|
||||
- Dark mode: Adjust colors, shadows, and contrasts
|
||||
- High-density displays: Fine-tune spacing and sizing
|
||||
- Responsive design: Scale tokens across breakpoints
|
||||
|
||||
### How to Apply Adjustments
|
||||
|
||||
1. **Identify Need**: Determine which tokens need adjustment based on your specific requirements
|
||||
2. **Maintain Relationships**: Preserve proportional relationships between related tokens
|
||||
3. **Test Thoroughly**: Validate changes across components and use cases
|
||||
4. **Document Changes**: Track modifications and rationale for team alignment
|
||||
5. **Iterate**: Refine based on user feedback and testing results
|
||||
|
||||
---
|
||||
|
||||
## Progressive Loading
|
||||
|
||||
### Level 0: Quick Start (~2K tokens)
|
||||
### Level 0: Design Tokens (~5K tokens)
|
||||
|
||||
Essential overview and package information.
|
||||
Essential design token system for consistent styling.
|
||||
|
||||
**Files**:
|
||||
- [README](../../../.workflow/reference_style/{package_name}/README.md) - Package overview and usage
|
||||
- [Metadata](../../../.workflow/reference_style/{package_name}/metadata.json) - Source and package info
|
||||
- [Design Tokens](../../../.workflow/reference_style/{package_name}/design-tokens.json) - Colors, typography, spacing, shadows, borders
|
||||
|
||||
**Use when**: Quick reference, understanding package structure
|
||||
**Use when**: Quick token reference, applying consistent styles, color/typography queries
|
||||
|
||||
---
|
||||
|
||||
### Level 1: Design Tokens (~8K tokens)
|
||||
### Level 1: Universal Layout Templates (~12K tokens)
|
||||
|
||||
Complete design token system with style guidelines.
|
||||
**Project-independent** component layout patterns for reusable UI elements.
|
||||
|
||||
**Files**:
|
||||
- [Design Tokens](../../../.workflow/reference_style/{package_name}/design-tokens.json) - Colors, typography, spacing, shadows
|
||||
- [Style Guide](../../../.workflow/reference_style/{package_name}/style-guide.md) - Design philosophy and usage guidelines
|
||||
- Level 0 files
|
||||
- [Layout Templates](../../../.workflow/reference_style/{package_name}/layout-templates.json) - Component structures with HTML/CSS patterns
|
||||
|
||||
**Use when**: Implementing UI, applying design tokens, style consistency
|
||||
**⚠️ Reference Strategy**:
|
||||
- **Only reference components with `component_type: "universal"`** - these are reusable, project-independent patterns
|
||||
- **Ignore components with `component_type: "specialized"`** - these are project-specific implementations
|
||||
- Universal components include: buttons, inputs, forms, cards, navigation, modals, etc.
|
||||
- Use universal patterns as **reference templates** to adapt for your specific project needs
|
||||
|
||||
**Use when**: Building components, understanding component architecture, implementing layouts
|
||||
|
||||
---
|
||||
|
||||
### Level 2: Components & Patterns (~15K tokens)
|
||||
### Level 2: Complete System (~20K tokens)
|
||||
|
||||
Full component catalog with patterns, variants, and states.
|
||||
Full design system with animations and interactive preview.
|
||||
|
||||
**Files**:
|
||||
- Level 1 files
|
||||
- [Component Patterns](../../../.workflow/reference_style/{package_name}/component-patterns.json) - Component catalog with DOM structures and CSS classes
|
||||
- All Level 1 files
|
||||
- [Animation Tokens](../../../.workflow/reference_style/{package_name}/animation-tokens.json) - Animation durations, easing, transitions _(if available)_
|
||||
|
||||
**Use when**: Building components, implementing interactions, animation development
|
||||
|
||||
---
|
||||
|
||||
### Level 3: Complete Reference (~25K tokens)
|
||||
|
||||
Everything including interactive preview reference and full documentation.
|
||||
|
||||
**Files**:
|
||||
- All Level 2 files
|
||||
- [Preview HTML](../../../.workflow/reference_style/{package_name}/preview.html) - Interactive component showcase (reference only)
|
||||
- [Preview HTML](../../../.workflow/reference_style/{package_name}/preview.html) - Interactive showcase (reference only)
|
||||
- [Preview CSS](../../../.workflow/reference_style/{package_name}/preview.css) - Showcase styling (reference only)
|
||||
|
||||
**Use when**: Comprehensive analysis, complete design system understanding, implementation validation
|
||||
**Use when**: Comprehensive analysis, animation development, complete design system understanding
|
||||
|
||||
---
|
||||
|
||||
@@ -317,62 +522,62 @@ python -m http.server 8080
|
||||
|
||||
### Loading Levels
|
||||
|
||||
**Level 0** (2K): Quick reference when you need basic package info
|
||||
**Level 0** (5K): Design tokens only
|
||||
```
|
||||
Load Level 0 for package overview
|
||||
Load Level 0 for design token reference
|
||||
```
|
||||
|
||||
**Level 1** (8K): Design token implementation
|
||||
**Level 1** (12K): Tokens + layout templates
|
||||
```
|
||||
Load Level 1 for design tokens and style guide
|
||||
Load Level 1 for layout templates and design tokens
|
||||
```
|
||||
|
||||
**Level 2** (15K): Component development
|
||||
**Level 2** (20K): Complete system with animations and preview
|
||||
```
|
||||
Load Level 2 for component patterns and animations
|
||||
```
|
||||
|
||||
**Level 3** (25K): Comprehensive understanding
|
||||
```
|
||||
Load Level 3 for complete design system reference
|
||||
Load Level 2 for complete design system with preview reference
|
||||
```
|
||||
|
||||
### Common Use Cases
|
||||
|
||||
**Implementing UI Components**:
|
||||
- Load Level 2 for component patterns
|
||||
- Reference component-patterns.json for DOM structure and CSS classes
|
||||
- Load Level 1 for universal layout templates
|
||||
- **Only reference components with `component_type: "universal"`** in layout-templates.json
|
||||
- Apply design tokens from design-tokens.json
|
||||
- Adapt patterns to your project's specific requirements
|
||||
|
||||
**Ensuring Style Consistency**:
|
||||
- Load Level 1 for design tokens
|
||||
- Use style-guide.md for design philosophy
|
||||
- Check preview.html for visual reference
|
||||
- Load Level 0 for design tokens
|
||||
- Use design-tokens.json for colors, typography, spacing
|
||||
- Check preview.html for visual reference (universal components only)
|
||||
|
||||
**Analyzing Design Patterns**:
|
||||
- Load Level 3 for complete analysis
|
||||
- Review component-patterns.json for architecture
|
||||
**Analyzing Component Patterns**:
|
||||
- Load Level 2 for complete analysis
|
||||
- Review layout-templates.json for component architecture
|
||||
- **Filter for `component_type: "universal"` to exclude project-specific implementations**
|
||||
- Check preview.html for implementation examples
|
||||
|
||||
**Animation Development**:
|
||||
- Load Level 2 for animation tokens
|
||||
- Load Level 2 for animation tokens (if available)
|
||||
- Reference animation-tokens.json for durations and easing
|
||||
- Apply consistent timing and transitions
|
||||
|
||||
**⚠️ Critical Usage Rule**:
|
||||
This is a **project-independent style reference system**. When working with layout-templates.json:
|
||||
- **USE**: Components marked `component_type: "universal"` as reusable reference patterns
|
||||
- **IGNORE**: Components marked `component_type: "specialized"` (project-specific implementations)
|
||||
- **ADAPT**: All patterns should be customized for your specific project needs
|
||||
|
||||
---
|
||||
|
||||
## Package Structure
|
||||
|
||||
```
|
||||
.workflow/reference_style/{package_name}/
|
||||
├── README.md # Package overview
|
||||
├── metadata.json # Package metadata
|
||||
├── design-tokens.json # Design token system
|
||||
├── style-guide.md # Style guide documentation
|
||||
├── component-patterns.json # Component catalog
|
||||
├── animation-tokens.json # Animation tokens (optional)
|
||||
├── preview.html # Interactive showcase
|
||||
└── preview.css # Showcase styling
|
||||
├── layout-templates.json # Layout templates from codebase
|
||||
├── design-tokens.json # Design token system
|
||||
├── animation-tokens.json # Animation tokens (optional)
|
||||
├── preview.html # Interactive showcase
|
||||
└── preview.css # Showcase styling
|
||||
```
|
||||
|
||||
---
|
||||
@@ -408,7 +613,7 @@ bash(test -f .claude/skills/style-${package_name}/SKILL.md && echo "success" ||
|
||||
```json
|
||||
[
|
||||
{"content": "Validate style reference package", "status": "completed", "activeForm": "Validating package"},
|
||||
{"content": "Read package metadata and documentation", "status": "completed", "activeForm": "Reading metadata"},
|
||||
{"content": "Read package data and extract design references", "status": "completed", "activeForm": "Reading package data"},
|
||||
{"content": "Generate SKILL.md with progressive loading", "status": "completed", "activeForm": "Generating SKILL.md"}
|
||||
]
|
||||
```
|
||||
@@ -419,38 +624,86 @@ bash(test -f .claude/skills/style-${package_name}/SKILL.md && echo "success" ||
|
||||
|
||||
## Completion Message
|
||||
|
||||
Display extracted primary design references to user:
|
||||
|
||||
```
|
||||
✅ SKILL memory generated successfully!
|
||||
|
||||
Package: {package_name}
|
||||
SKILL Location: .claude/skills/style-{package_name}/SKILL.md
|
||||
|
||||
Package Details:
|
||||
- Components: {component_count}
|
||||
📦 Package Details:
|
||||
- Layout Templates: {component_count} total
|
||||
- Universal (reusable): {universal_count}
|
||||
- Specialized (project-specific): {specialized_count}
|
||||
- Universal Component Types: {show first 5 UNIVERSAL_COMPONENTS, then "+ X more"}
|
||||
- Files: {file_count}
|
||||
- Version: {version}
|
||||
- Animation Tokens: {has_animations ? "✓ Available" : "Not available"}
|
||||
|
||||
Progressive Loading Levels:
|
||||
- Level 0: Quick Start (~2K tokens)
|
||||
- Level 1: Design Tokens (~8K tokens)
|
||||
- Level 2: Components & Patterns (~15K tokens)
|
||||
- Level 3: Complete Reference (~25K tokens)
|
||||
🎨 Primary Design References Extracted:
|
||||
{IF PRIMARY_COLORS exists:
|
||||
Colors:
|
||||
{show first 3 PRIMARY_COLORS with key: value}
|
||||
{if more than 3: + X more colors}
|
||||
}
|
||||
|
||||
Usage:
|
||||
{IF TYPOGRAPHY_FONTS exists:
|
||||
Typography:
|
||||
{show all TYPOGRAPHY_FONTS}
|
||||
}
|
||||
|
||||
{IF SPACING_SCALE exists:
|
||||
Spacing Scale:
|
||||
{show first 3 SPACING_SCALE items}
|
||||
{if more than 3: + X more spacing tokens}
|
||||
}
|
||||
|
||||
{IF BORDER_RADIUS exists:
|
||||
Border Radius:
|
||||
{show all BORDER_RADIUS}
|
||||
}
|
||||
|
||||
{IF HAS_ANIMATIONS:
|
||||
Animation:
|
||||
Durations: {count ANIMATION_DURATIONS} tokens
|
||||
Easing: {count EASING_FUNCTIONS} functions
|
||||
}
|
||||
|
||||
⚡ Progressive Loading Levels:
|
||||
- Level 0: Design Tokens (~5K tokens)
|
||||
- Level 1: Tokens + Layout Templates (~12K tokens)
|
||||
- Level 2: Complete System (~20K tokens)
|
||||
|
||||
💡 Usage:
|
||||
Load design system context when working with:
|
||||
- UI component implementation
|
||||
- Layout pattern analysis
|
||||
- Design token application
|
||||
- Style consistency validation
|
||||
- Design pattern analysis
|
||||
|
||||
Preview:
|
||||
⚠️ IMPORTANT - Project Independence:
|
||||
This is a **project-independent style reference system**:
|
||||
- Only use universal components (component_type: "universal") as reference patterns
|
||||
- Ignore specialized components (component_type: "specialized") - they are project-specific
|
||||
- The extracted design references are REFERENCE VALUES, not fixed constraints
|
||||
- Dynamically adjust colors, spacing, typography, and other tokens based on:
|
||||
- Brand requirements and accessibility needs
|
||||
- Platform-specific conventions and optimizations
|
||||
- Context (light/dark mode, responsive breakpoints)
|
||||
- User feedback and testing results
|
||||
|
||||
See SKILL.md for detailed adjustment guidelines and component filtering instructions.
|
||||
|
||||
🎯 Preview:
|
||||
Open interactive showcase:
|
||||
file://{absolute_path}/.workflow/reference_style/{package_name}/preview.html
|
||||
|
||||
Next Steps:
|
||||
1. Load appropriate level based on your task
|
||||
2. Reference component-patterns.json for implementation
|
||||
3. Use design-tokens.json for consistent styling
|
||||
📋 Next Steps:
|
||||
1. Load appropriate level based on your task context
|
||||
2. Review Primary Design References section for key design tokens
|
||||
3. Apply design tokens with dynamic adjustments as needed
|
||||
4. Reference layout-templates.json for component structures
|
||||
5. Use Design Adaptation Strategies when modifying tokens
|
||||
```
|
||||
|
||||
---
|
||||
@@ -463,8 +716,8 @@ Next Steps:
|
||||
|-------|-------|------------|
|
||||
| Package not found | Invalid package name or package doesn't exist | Run codify-style first to create package |
|
||||
| SKILL already exists | SKILL.md already generated | Use --regenerate to force regeneration |
|
||||
| Missing metadata.json | Incomplete package | Verify package integrity, re-run codify-style |
|
||||
| Invalid metadata format | Corrupted metadata.json | Regenerate package with codify-style |
|
||||
| Missing layout-templates.json | Incomplete package | Verify package integrity, re-run codify-style |
|
||||
| Invalid JSON format | Corrupted package files | Regenerate package with codify-style |
|
||||
|
||||
---
|
||||
|
||||
@@ -474,61 +727,144 @@ Next Steps:
|
||||
|
||||
1. **Check Before Generate**: Verify package exists before attempting SKILL generation
|
||||
2. **Respect Existing SKILL**: Don't overwrite unless --regenerate flag provided
|
||||
3. **Progressive Loading**: Always include all 4 levels (0-3) with clear token estimates
|
||||
4. **Intelligent Description**: Extract component count and key features from metadata
|
||||
3. **Extract Primary References**: Always extract and display key design values (colors, typography, spacing, border radius, shadows, animations)
|
||||
4. **Include Adjustment Guidance**: Provide clear guidelines on when and how to dynamically adjust design tokens
|
||||
5. **Progressive Loading**: Always include all 3 levels (0-2) with clear token estimates
|
||||
6. **Intelligent Description**: Extract component count and key features from metadata
|
||||
|
||||
### SKILL Description Format
|
||||
|
||||
**Template**:
|
||||
```
|
||||
{package_name} design system with {component_count} components and interactive preview (located at .workflow/reference_style/{package_name}). Load when working with UI components, design tokens, style guidelines, analyzing design patterns, or implementing visual consistency.
|
||||
{package_name} project-independent design system with {universal_count} universal layout templates and interactive preview (located at .workflow/reference_style/{package_name}). Load when working with reusable UI components, design tokens, layout patterns, or implementing visual consistency. Excludes {specialized_count} project-specific components.
|
||||
```
|
||||
|
||||
**Required Elements**:
|
||||
- Package name
|
||||
- Component count
|
||||
- Universal layout template count (emphasize reusability)
|
||||
- Project independence statement
|
||||
- Specialized component exclusion notice
|
||||
- Location (full path)
|
||||
- Trigger keywords (UI components, design tokens, style guidelines, design patterns)
|
||||
- Trigger keywords (reusable UI components, design tokens, layout patterns, visual consistency)
|
||||
- Action verbs (working with, analyzing, implementing)
|
||||
|
||||
### Primary Design References Extraction
|
||||
|
||||
**Required Data Extraction** (from design-tokens.json):
|
||||
- Colors: Primary, secondary, accent colors (top 3-5)
|
||||
- Typography: Font families for headings and body text
|
||||
- Spacing Scale: Base spacing values (xs, sm, md, lg, xl)
|
||||
- Border Radius: All radius tokens
|
||||
- Shadows: Shadow definitions (top 3 elevation levels)
|
||||
|
||||
**Component Classification Extraction** (from layout-templates.json):
|
||||
- Universal Count: Number of components with `component_type: "universal"`
|
||||
- Specialized Count: Number of components with `component_type: "specialized"`
|
||||
- Universal Component Names: List of universal component names (first 10)
|
||||
|
||||
**Optional Data Extraction** (from animation-tokens.json if available):
|
||||
- Animation Durations: All duration tokens
|
||||
- Easing Functions: Top 3 easing functions
|
||||
|
||||
**Extraction Format**:
|
||||
Use `jq` to extract tokens from JSON files. Each token should include key and value.
|
||||
For component classification, filter by `component_type` field.
|
||||
|
||||
### Dynamic Adjustment Guidelines
|
||||
|
||||
**Include in SKILL.md**:
|
||||
1. **Usage Guidelines per Category**: Specific guidance for each token category
|
||||
2. **Adjustment Strategies**: When to adjust design references
|
||||
3. **Practical Examples**: Context-specific adaptation scenarios
|
||||
4. **Best Practices**: How to maintain design system coherence while adjusting
|
||||
|
||||
### Progressive Loading Structure
|
||||
|
||||
**Level 0** (~2K tokens):
|
||||
- README.md
|
||||
- metadata.json
|
||||
|
||||
**Level 1** (~8K tokens):
|
||||
- Level 0 files
|
||||
**Level 0** (~5K tokens):
|
||||
- design-tokens.json
|
||||
- style-guide.md
|
||||
|
||||
**Level 2** (~15K tokens):
|
||||
**Level 1** (~12K tokens):
|
||||
- Level 0 files
|
||||
- layout-templates.json
|
||||
|
||||
**Level 2** (~20K tokens):
|
||||
- Level 1 files
|
||||
- component-patterns.json
|
||||
- animation-tokens.json (if exists)
|
||||
|
||||
**Level 3** (~25K tokens):
|
||||
- All files including preview.html/css
|
||||
- preview.html
|
||||
- preview.css
|
||||
|
||||
---
|
||||
|
||||
## Benefits
|
||||
|
||||
- **Project Independence**: Clear separation between universal (reusable) and specialized (project-specific) components
|
||||
- **Component Filtering**: Automatic classification helps identify which patterns are truly reusable
|
||||
- **Fast Context Loading**: Progressive levels for efficient token usage
|
||||
- **Primary Design References**: Extracted key design values (colors, typography, spacing, etc.) displayed prominently
|
||||
- **Dynamic Adjustment Guidance**: Clear instructions on when and how to adjust design tokens
|
||||
- **Intelligent Triggering**: Keywords optimize SKILL activation
|
||||
- **Complete Reference**: All package files accessible through SKILL
|
||||
- **Easy Regeneration**: Simple --regenerate flag for updates
|
||||
- **Clear Structure**: Organized levels by use case
|
||||
- **Clear Structure**: Organized levels by use case with component type filtering
|
||||
- **Practical Usage Guidelines**: Context-specific adjustment strategies and component selection criteria
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
style-skill-memory
|
||||
├─ Phase 1: Validate (check package exists, check SKILL exists)
|
||||
├─ Phase 2: Read Metadata (extract metadata.json, README.md, count components)
|
||||
└─ Phase 3: Generate SKILL.md (write SKILL with progressive loading)
|
||||
├─ Phase 1: Validate
|
||||
│ ├─ Parse package name from argument or auto-detect
|
||||
│ ├─ Check package exists in .workflow/reference_style/
|
||||
│ └─ Check if SKILL already exists (skip if exists and no --regenerate)
|
||||
│
|
||||
├─ Phase 2: Read Package Data & Extract Primary References
|
||||
│ ├─ Count components from layout-templates.json
|
||||
│ ├─ Extract component types list
|
||||
│ ├─ Extract primary colors from design-tokens.json (top 3-5)
|
||||
│ ├─ Extract typography (font families)
|
||||
│ ├─ Extract spacing scale (base values)
|
||||
│ ├─ Extract border radius tokens
|
||||
│ ├─ Extract shadow definitions (top 3)
|
||||
│ ├─ Extract animation tokens (if available)
|
||||
│ └─ Count total files in package
|
||||
│
|
||||
└─ Phase 3: Generate SKILL.md
|
||||
├─ Create SKILL directory
|
||||
├─ Generate intelligent description with keywords
|
||||
├─ Write SKILL.md with complete structure:
|
||||
│ ├─ Package Overview
|
||||
│ ├─ Primary Design References
|
||||
│ │ ├─ Colors with usage guidelines
|
||||
│ │ ├─ Typography with usage guidelines
|
||||
│ │ ├─ Spacing with usage guidelines
|
||||
│ │ ├─ Border Radius with usage guidelines
|
||||
│ │ ├─ Shadows with usage guidelines
|
||||
│ │ └─ Animation & Timing (if available)
|
||||
│ ├─ Design Adaptation Strategies
|
||||
│ │ ├─ When to adjust design references
|
||||
│ │ └─ How to apply adjustments
|
||||
│ ├─ Progressive Loading (3 levels)
|
||||
│ ├─ Interactive Preview
|
||||
│ ├─ Usage Guidelines
|
||||
│ ├─ Package Structure
|
||||
│ ├─ Regeneration
|
||||
│ └─ Related Commands
|
||||
├─ Verify SKILL.md created successfully
|
||||
└─ Display completion message with extracted design references
|
||||
|
||||
No external commands called
|
||||
Direct file reading and writing
|
||||
Smart description generation from metadata
|
||||
Data Flow:
|
||||
design-tokens.json → jq extraction → PRIMARY_COLORS, TYPOGRAPHY_FONTS,
|
||||
SPACING_SCALE, BORDER_RADIUS, SHADOWS
|
||||
animation-tokens.json → jq extraction → ANIMATION_DURATIONS, EASING_FUNCTIONS
|
||||
layout-templates.json → jq extraction → COMPONENT_COUNT, UNIVERSAL_COUNT,
|
||||
SPECIALIZED_COUNT, UNIVERSAL_COMPONENTS
|
||||
→ component_type filtering → Universal vs Specialized classification
|
||||
|
||||
Extracted data → SKILL.md generation → Primary Design References section
|
||||
→ Component Classification section
|
||||
→ Dynamic Adjustment Guidelines
|
||||
→ Project Independence warnings
|
||||
→ Completion message display
|
||||
```
|
||||
|
||||
@@ -50,17 +50,18 @@ This workflow runs **fully autonomously** once triggered. Phase 1 (artifacts) ha
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
/workflow:brainstorm:auto-parallel "<topic>" [--count N]
|
||||
/workflow:brainstorm:auto-parallel "<topic>" [--count N] [--style-skill package-name]
|
||||
```
|
||||
|
||||
**Recommended Structured Format**:
|
||||
```bash
|
||||
/workflow:brainstorm:auto-parallel "GOAL: [objective] SCOPE: [boundaries] CONTEXT: [background]" [--count N]
|
||||
/workflow:brainstorm:auto-parallel "GOAL: [objective] SCOPE: [boundaries] CONTEXT: [background]" [--count N] [--style-skill package-name]
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `topic` (required): Topic or challenge description (structured format recommended)
|
||||
- `--count N` (optional): Number of roles to select (default: 3, max: 9)
|
||||
- `--style-skill package-name` (optional): Style SKILL package to load for UI design (located at `.claude/skills/style-{package-name}/`)
|
||||
|
||||
## 3-Phase Execution
|
||||
|
||||
@@ -150,6 +151,12 @@ TOPIC: {user-provided-topic}
|
||||
- Command: Read(.workflow/WFS-{session}/workflow-session.json)
|
||||
- Output: session_context (contains original user prompt as PRIMARY reference)
|
||||
|
||||
4. **load_style_skill** (ONLY for ui-designer role when style_skill_package exists)
|
||||
- Action: Load style SKILL package for design system reference
|
||||
- Command: Read(.claude/skills/style-{style_skill_package}/SKILL.md) AND Read(.workflow/reference_style/{style_skill_package}/design-tokens.json)
|
||||
- Output: style_skill_content, design_tokens
|
||||
- Usage: Apply design tokens in ui-designer analysis and artifacts
|
||||
|
||||
## Analysis Requirements
|
||||
**Primary Reference**: Original user prompt from workflow-session.json is authoritative
|
||||
**Framework Source**: Address all discussion points in guidance-specification.md from {role-name} perspective
|
||||
@@ -342,6 +349,34 @@ ELSE:
|
||||
EXECUTE: /workflow:brainstorm:artifacts "{topic}" --count {count_value}
|
||||
```
|
||||
|
||||
**Style-Skill Parameter Parsing**:
|
||||
```javascript
|
||||
// Extract --style-skill from user input
|
||||
IF user_input CONTAINS "--style-skill":
|
||||
EXTRACT style_skill_name FROM "--style-skill package-name" pattern
|
||||
|
||||
// Validate SKILL package exists
|
||||
skill_path = ".claude/skills/style-{style_skill_name}/SKILL.md"
|
||||
IF file_exists(skill_path):
|
||||
style_skill_package = style_skill_name
|
||||
style_reference_path = ".workflow/reference_style/{style_skill_name}"
|
||||
echo("✓ Style SKILL package found: style-{style_skill_name}")
|
||||
echo(" Design reference: {style_reference_path}")
|
||||
ELSE:
|
||||
echo("⚠ WARNING: Style SKILL package not found: {style_skill_name}")
|
||||
echo(" Expected location: {skill_path}")
|
||||
echo(" Continuing without style reference...")
|
||||
style_skill_package = null
|
||||
ELSE:
|
||||
style_skill_package = null
|
||||
echo("No style-skill specified, ui-designer will use default workflow")
|
||||
|
||||
// Store for Phase 2 ui-designer context
|
||||
CONTEXT_VARS:
|
||||
- style_skill_package: {style_skill_package}
|
||||
- style_reference_path: {style_reference_path}
|
||||
```
|
||||
|
||||
**Topic Structuring**:
|
||||
1. **Already Structured** → Pass directly to artifacts
|
||||
```
|
||||
@@ -374,15 +409,17 @@ EXECUTE: /workflow:brainstorm:artifacts "{topic}" --count {count_value}
|
||||
|
||||
**Phase 1 Output**:
|
||||
- `.workflow/WFS-{topic}/.brainstorming/guidance-specification.md` (framework content)
|
||||
- `.workflow/WFS-{topic}/workflow-session.json` (metadata: selected_roles[], topic, timestamps)
|
||||
- `.workflow/WFS-{topic}/workflow-session.json` (metadata: selected_roles[], topic, timestamps, style_skill_package)
|
||||
|
||||
**Phase 2 Output**:
|
||||
- `.workflow/WFS-{topic}/.brainstorming/{role}/analysis.md` (one per role)
|
||||
- `.superdesign/design_iterations/` (ui-designer artifacts, if --style-skill provided)
|
||||
|
||||
**Phase 3 Output**:
|
||||
- `.workflow/WFS-{topic}/.brainstorming/synthesis-specification.md` (integrated analysis)
|
||||
|
||||
**⚠️ Storage Separation**: Guidance content in .md files, metadata in .json (no duplication)
|
||||
**⚠️ Style References**: When --style-skill provided, workflow-session.json stores style_skill_package name, ui-designer loads from `.claude/skills/style-{package-name}/`
|
||||
|
||||
## Available Roles
|
||||
|
||||
|
||||
@@ -0,0 +1,962 @@
|
||||
---
|
||||
name: lite-plan
|
||||
description: Lightweight interactive planning and execution workflow with in-memory planning, code exploration, and immediate execution after user confirmation
|
||||
argument-hint: "[--tool claude|gemini|qwen|codex] [--quick] \"task description\"|file.md"
|
||||
allowed-tools: TodoWrite(*), Task(*), Bash(*), AskUserQuestion(*)
|
||||
timeout: 180000
|
||||
color: cyan
|
||||
---
|
||||
|
||||
# Workflow Lite-Plan Command (/workflow:lite-plan)
|
||||
|
||||
## Overview
|
||||
|
||||
Intelligent lightweight planning and execution command with dynamic workflow adaptation based on task complexity.
|
||||
|
||||
**Key Characteristics**:
|
||||
- Dynamic Workflow: Automatically decides whether to use exploration, clarification, and detailed planning
|
||||
- Smart Exploration: Calls cli-explore-agent only when task requires codebase context
|
||||
- Interactive Clarification: Asks user for more information after exploration if needed
|
||||
- Adaptive Planning: Simple tasks get direct planning, complex tasks use cli-planning-agent
|
||||
- Two-Dimensional Confirmation: User confirms task + selects execution method in one step
|
||||
- Direct Execution: Immediately starts execution (agent or CLI) after confirmation
|
||||
- Live Progress Tracking: Uses TodoWrite to track execution progress in real-time
|
||||
|
||||
## Core Functionality
|
||||
|
||||
- **Intelligent Task Analysis**: Automatically determines if exploration/planning agents are needed
|
||||
- **Dynamic Exploration**: Calls cli-explore-agent only when task requires codebase understanding
|
||||
- **Interactive Clarification**: Asks follow-up questions after exploration to gather missing information
|
||||
- **Adaptive Planning**:
|
||||
- Simple tasks: Direct planning by current Claude
|
||||
- Complex tasks: Delegates to cli-planning-agent for detailed breakdown
|
||||
- **Two-Dimensional Confirmation**: Single user interaction for task approval + execution method selection
|
||||
- **Direct Execution**: Immediate dispatch to selected execution method (agent or CLI)
|
||||
- **Live Progress Tracking**: Real-time TodoWrite updates during execution
|
||||
|
||||
## Comparison with Other Commands
|
||||
|
||||
| Feature | lite-plan | /cli:mode:plan | /workflow:plan |
|
||||
|---------|-----------|----------------|----------------|
|
||||
| Workflow Adaptation | Dynamic (intelligent) | Fixed | Fixed |
|
||||
| Code Exploration | Smart (when needed) | No | Always (context-search) |
|
||||
| Clarification | Yes (interactive) | No | No |
|
||||
| Planning Strategy | Adaptive (simple/complex) | Fixed template | Agent-based |
|
||||
| User Interaction | Two-dimensional | No | Minimal |
|
||||
| Direct Execution | Yes (immediate) | Yes (immediate) | No (requires /workflow:execute) |
|
||||
| Progress Tracking | Yes (TodoWrite live) | No | Yes (session-based) |
|
||||
| Execution Time | Fast (1-3 min) | Fast (2-5 min) | Slow (5-10 min) |
|
||||
| Tool Selection | User choice | --tool flag | Fixed (agent only) |
|
||||
| File Artifacts | No | No | Yes (IMPL_PLAN.md + JSON) |
|
||||
|
||||
## Usage
|
||||
|
||||
### Command Syntax
|
||||
```bash
|
||||
/workflow:lite-plan [FLAGS] <TASK_DESCRIPTION>
|
||||
|
||||
# Flags
|
||||
--tool <tool-name> Preset CLI tool (claude|gemini|qwen|codex); if not provided, user selects during confirmation
|
||||
--quick Skip code exploration phase (fast mode, completes within 60 seconds)
|
||||
|
||||
# Arguments
|
||||
<task-description> Task description or path to .md file (required)
|
||||
```
|
||||
|
||||
### Usage Examples
|
||||
```bash
|
||||
# Standard planning with full interaction
|
||||
/workflow:lite-plan "Implement user authentication with JWT tokens"
|
||||
# -> Shows plan, user confirms, selects tool, immediate execution
|
||||
|
||||
# Quick mode with preset tool
|
||||
/workflow:lite-plan --quick --tool gemini "Refactor logging module for better performance"
|
||||
# -> Skips exploration, user confirms plan, executes with Gemini
|
||||
|
||||
# Codex direct execution preset
|
||||
/workflow:lite-plan --tool codex "Add unit tests for authentication service"
|
||||
# -> User only confirms plan, executes with Codex immediately
|
||||
|
||||
# Agent mode with Claude
|
||||
/workflow:lite-plan "Design new API endpoints for payment processing"
|
||||
# -> User selects Claude agent, immediate execution
|
||||
```
|
||||
|
||||
## Execution Process
|
||||
|
||||
### Workflow Overview
|
||||
|
||||
```
|
||||
User Input ("/workflow:lite-plan \"task\"")
|
||||
|
|
||||
v
|
||||
[Phase 1] Task Analysis & Exploration Decision (10-20 seconds)
|
||||
-> Analyze task description
|
||||
-> Decision: Need exploration? (Yes/No/--quick override)
|
||||
-> If Yes: Launch cli-explore-agent
|
||||
-> Output: exploration findings (if performed)
|
||||
|
|
||||
v
|
||||
[Phase 2] Clarification (Optional, user interaction)
|
||||
-> If exploration revealed ambiguities or missing info
|
||||
-> AskUserQuestion: Gather clarifications
|
||||
-> Update task context with user responses
|
||||
-> If no clarification needed: Skip to Phase 3
|
||||
|
|
||||
v
|
||||
[Phase 3] Complexity Assessment & Planning (20-60 seconds)
|
||||
-> Assess task complexity (Low/Medium/High)
|
||||
-> Decision: Planning strategy
|
||||
- Low: Direct planning (current Claude)
|
||||
- Medium/High: Delegate to cli-planning-agent
|
||||
-> Output: Task breakdown with execution approach
|
||||
|
|
||||
v
|
||||
[Phase 4] Task Confirmation & Execution Selection (User interaction)
|
||||
-> Display task breakdown and approach
|
||||
-> AskUserQuestion: Two dimensions
|
||||
1. Confirm task (Yes/Modify/Cancel)
|
||||
2. Execution method (Direct/CLI)
|
||||
-> If confirmed: Proceed to Phase 5
|
||||
-> If modify: Re-run planning with feedback
|
||||
-> If cancel: Exit
|
||||
|
|
||||
v
|
||||
[Phase 5] Execution & Progress Tracking
|
||||
-> Create TodoWrite task list from breakdown
|
||||
-> Launch selected execution (agent or CLI)
|
||||
-> Track progress with TodoWrite updates
|
||||
-> Real-time status displayed to user
|
||||
|
|
||||
v
|
||||
Execution Complete
|
||||
```
|
||||
|
||||
### Task Management Pattern
|
||||
|
||||
- TodoWrite creates task list before execution starts (Phase 5)
|
||||
- Tasks marked as in_progress/completed during execution
|
||||
- Real-time progress updates visible to user
|
||||
- No intermediate file artifacts generated
|
||||
|
||||
## Detailed Phase Execution
|
||||
|
||||
### Phase 1: Task Analysis & Exploration Decision
|
||||
|
||||
**Operations**:
|
||||
- Analyze task description to determine if code exploration is needed
|
||||
- Decision logic:
|
||||
```javascript
|
||||
needsExploration = (
|
||||
task.mentions_specific_files ||
|
||||
task.requires_codebase_context ||
|
||||
task.needs_architecture_understanding ||
|
||||
task.modifies_existing_code
|
||||
) && !flags.includes('--quick')
|
||||
```
|
||||
|
||||
**Decision Criteria**:
|
||||
|
||||
| Task Type | Needs Exploration | Reason |
|
||||
|-----------|-------------------|--------|
|
||||
| "Implement new feature X" | Maybe | Depends on integration with existing code |
|
||||
| "Refactor module Y" | Yes | Needs understanding of current implementation |
|
||||
| "Add tests for Z" | Yes | Needs to understand code structure |
|
||||
| "Create new standalone utility" | No | Self-contained, no existing code context |
|
||||
| "Update documentation" | No | Doesn't require code exploration |
|
||||
| "Fix bug in function F" | Yes | Needs to understand implementation |
|
||||
|
||||
**If Exploration Needed**:
|
||||
- Launch cli-explore-agent with task-specific focus
|
||||
- Agent call format:
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="cli-explore-agent",
|
||||
description="Analyze codebase for task context",
|
||||
prompt=`
|
||||
Task: ${task_description}
|
||||
|
||||
Analyze and return the following information in structured format:
|
||||
1. Project Structure: Overall architecture and module organization
|
||||
2. Relevant Files: List of files that will be affected by this task (with paths)
|
||||
3. Current Implementation Patterns: Existing code patterns, conventions, and styles
|
||||
4. Dependencies: External dependencies and internal module dependencies
|
||||
5. Integration Points: Where this task connects with existing code
|
||||
6. Architecture Constraints: Technical limitations or requirements
|
||||
7. Clarification Needs: Ambiguities or missing information requiring user input
|
||||
|
||||
Time Limit: 60 seconds
|
||||
|
||||
Output Format: Return a JSON-like structured object with the above fields populated.
|
||||
Include specific file paths, pattern examples, and clear questions for clarifications.
|
||||
`
|
||||
)
|
||||
```
|
||||
|
||||
**Expected Return Structure**:
|
||||
```javascript
|
||||
explorationContext = {
|
||||
project_structure: "Description of overall architecture",
|
||||
relevant_files: ["src/auth/service.ts", "src/middleware/auth.ts", ...],
|
||||
patterns: "Description of existing patterns (e.g., 'Uses dependency injection pattern', 'React hooks convention')",
|
||||
dependencies: "List of dependencies and integration points",
|
||||
integration_points: "Where this connects with existing code",
|
||||
constraints: "Technical constraints (e.g., 'Must use existing auth library', 'No breaking changes')",
|
||||
clarification_needs: [
|
||||
{
|
||||
question: "Which authentication method to use?",
|
||||
context: "Found both JWT and Session patterns",
|
||||
options: ["JWT tokens", "Session-based", "Hybrid approach"]
|
||||
},
|
||||
// ... more clarification questions
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Output Processing**:
|
||||
- Store exploration findings in `explorationContext`
|
||||
- Extract `clarification_needs` array from exploration results
|
||||
- Set `needsClarification = (clarification_needs.length > 0)`
|
||||
- Use clarification_needs to generate Phase 2 questions
|
||||
|
||||
**Progress Tracking**:
|
||||
- Mark Phase 1 as completed
|
||||
- If needsClarification: Mark Phase 2 as in_progress
|
||||
- Else: Skip to Phase 3
|
||||
|
||||
**Expected Duration**: 10-20 seconds (analysis) + 30-60 seconds (exploration if needed)
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Clarification (Optional)
|
||||
|
||||
**Skip Condition**: Only run if Phase 1 set `needsClarification = true`
|
||||
|
||||
**Operations**:
|
||||
- Review `explorationContext.clarification_needs` from Phase 1
|
||||
- Generate AskUserQuestion based on exploration findings
|
||||
- Focus on ambiguities that affect implementation approach
|
||||
|
||||
**AskUserQuestion Call** (simplified reference):
|
||||
```javascript
|
||||
// Use clarification_needs from exploration to build questions
|
||||
AskUserQuestion({
|
||||
questions: explorationContext.clarification_needs.map(need => ({
|
||||
question: `${need.context}\n\n${need.question}`,
|
||||
header: "Clarification",
|
||||
multiSelect: false,
|
||||
options: need.options.map(opt => ({
|
||||
label: opt,
|
||||
description: `Use ${opt} approach`
|
||||
}))
|
||||
}))
|
||||
})
|
||||
```
|
||||
|
||||
**Output Processing**:
|
||||
- Collect user responses and store in `clarificationContext`
|
||||
- Format: `{ question_id: selected_answer, ... }`
|
||||
- This context will be passed to Phase 3 planning
|
||||
|
||||
**Progress Tracking**:
|
||||
- Mark Phase 2 as completed
|
||||
- Mark Phase 3 as in_progress
|
||||
|
||||
**Expected Duration**: User-dependent (typically 30-60 seconds)
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Complexity Assessment & Planning
|
||||
|
||||
**Operations**:
|
||||
- Assess task complexity based on multiple factors
|
||||
- Select appropriate planning strategy
|
||||
- Generate task breakdown using selected method
|
||||
|
||||
**Complexity Assessment Factors**:
|
||||
```javascript
|
||||
complexityScore = {
|
||||
file_count: exploration.files_to_modify.length,
|
||||
integration_points: exploration.dependencies.length,
|
||||
architecture_changes: exploration.requires_architecture_change,
|
||||
technology_stack: exploration.unfamiliar_technologies.length,
|
||||
task_scope: (task.estimated_steps > 5),
|
||||
cross_cutting_concerns: exploration.affects_multiple_modules
|
||||
}
|
||||
|
||||
// Calculate complexity
|
||||
if (complexityScore < 3) complexity = "Low"
|
||||
else if (complexityScore < 6) complexity = "Medium"
|
||||
else complexity = "High"
|
||||
```
|
||||
|
||||
**Complexity Levels**:
|
||||
|
||||
| Level | Characteristics | Planning Strategy |
|
||||
|-------|----------------|-------------------|
|
||||
| Low | 1-2 files, simple changes, clear requirements | Direct planning (current Claude) |
|
||||
| Medium | 3-5 files, moderate integration, some ambiguity | Delegate to cli-planning-agent |
|
||||
| High | 6+ files, complex architecture, high uncertainty | Delegate to cli-planning-agent with detailed analysis |
|
||||
|
||||
**Planning Execution**:
|
||||
|
||||
**Option A: Direct Planning (Low Complexity)**
|
||||
```javascript
|
||||
// Current Claude generates plan directly
|
||||
planObject = {
|
||||
summary: "Brief overview of what needs to be done",
|
||||
approach: "Step-by-step implementation strategy",
|
||||
tasks: [
|
||||
"Task 1: Specific action with file references",
|
||||
"Task 2: Specific action with file references",
|
||||
// ... 3-5 tasks
|
||||
],
|
||||
complexity: "Low",
|
||||
estimated_time: "15-30 minutes"
|
||||
}
|
||||
```
|
||||
|
||||
**Option B: Agent-Based Planning (Medium/High Complexity)**
|
||||
```javascript
|
||||
// Delegate to cli-planning-agent
|
||||
Task(
|
||||
subagent_type="cli-planning-agent",
|
||||
description="Generate detailed implementation plan",
|
||||
prompt=`
|
||||
Task: ${task_description}
|
||||
|
||||
Exploration Context:
|
||||
${JSON.stringify(explorationContext, null, 2)}
|
||||
|
||||
User Clarifications:
|
||||
${JSON.stringify(clarificationContext, null, 2) || "None provided"}
|
||||
|
||||
Complexity Level: ${complexity}
|
||||
|
||||
Generate a detailed implementation plan with the following components:
|
||||
|
||||
1. Summary: 2-3 sentence overview of the implementation
|
||||
2. Approach: High-level implementation strategy
|
||||
3. Task Breakdown: 5-10 specific, actionable tasks
|
||||
- Each task should specify:
|
||||
* What to do
|
||||
* Which files to modify/create
|
||||
* Dependencies on other tasks (if any)
|
||||
4. Task Dependencies: Explicit ordering requirements (e.g., "Task 2 depends on Task 1")
|
||||
5. Risks: Potential issues and mitigation strategies (for Medium/High complexity)
|
||||
6. Estimated Time: Total implementation time estimate
|
||||
7. Recommended Execution: "Direct" (agent) or "CLI" (autonomous tool)
|
||||
|
||||
Output Format: Return a structured object with these fields:
|
||||
{
|
||||
summary: string,
|
||||
approach: string,
|
||||
tasks: string[],
|
||||
dependencies: string[] (optional),
|
||||
risks: string[] (optional),
|
||||
estimated_time: string,
|
||||
recommended_execution: "Direct" | "CLI"
|
||||
}
|
||||
|
||||
Ensure tasks are specific, with file paths and clear acceptance criteria.
|
||||
`
|
||||
)
|
||||
|
||||
// Agent returns detailed plan
|
||||
planObject = agent_output.parse()
|
||||
```
|
||||
|
||||
**Expected Return Structure**:
|
||||
```javascript
|
||||
planObject = {
|
||||
summary: "Implement JWT-based authentication system with middleware integration",
|
||||
approach: "Create auth service layer, implement JWT utilities, add middleware, update routes",
|
||||
tasks: [
|
||||
"Create authentication service in src/auth/service.ts with login/logout/verify methods",
|
||||
"Implement JWT token utilities in src/auth/jwt.ts (generate, verify, refresh)",
|
||||
"Add authentication middleware to src/middleware/auth.ts",
|
||||
"Update API routes in src/routes/*.ts to use auth middleware",
|
||||
"Add integration tests for auth flow in tests/auth.test.ts"
|
||||
],
|
||||
dependencies: [
|
||||
"Task 3 depends on Task 2 (middleware needs JWT utilities)",
|
||||
"Task 4 depends on Task 3 (routes need middleware)",
|
||||
"Task 5 depends on Tasks 1-4 (tests need complete implementation)"
|
||||
],
|
||||
risks: [
|
||||
"Token refresh timing may conflict with existing session logic - test thoroughly",
|
||||
"Breaking change if existing auth is in use - plan migration strategy"
|
||||
],
|
||||
estimated_time: "30-45 minutes",
|
||||
recommended_execution: "CLI" // Based on clear requirements and straightforward implementation
|
||||
}
|
||||
```
|
||||
|
||||
**Output Structure**:
|
||||
```javascript
|
||||
planObject = {
|
||||
summary: "2-3 sentence overview",
|
||||
approach: "Implementation strategy",
|
||||
tasks: [
|
||||
"Task 1: ...",
|
||||
"Task 2: ...",
|
||||
// ... 3-10 tasks based on complexity
|
||||
],
|
||||
complexity: "Low|Medium|High",
|
||||
dependencies: ["task1 -> task2", ...], // if Medium/High
|
||||
risks: ["risk1", "risk2", ...], // if High
|
||||
estimated_time: "X minutes",
|
||||
recommended_execution: "Direct|CLI"
|
||||
}
|
||||
```
|
||||
|
||||
**Progress Tracking**:
|
||||
- Mark Phase 3 as completed
|
||||
- Mark Phase 4 as in_progress
|
||||
|
||||
**Expected Duration**:
|
||||
- Low complexity: 20-30 seconds (direct)
|
||||
- Medium/High complexity: 40-60 seconds (agent-based)
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Task Confirmation & Execution Selection
|
||||
|
||||
**User Interaction Flow**: Two-dimensional confirmation (task + execution method)
|
||||
|
||||
**Operations**:
|
||||
- Display plan summary with full task breakdown
|
||||
- Collect two-dimensional user input: Task confirmation + Execution method selection
|
||||
- Support modification flow if user requests changes
|
||||
|
||||
**Question 1: Task Confirmation**
|
||||
|
||||
Display plan to user and ask for confirmation:
|
||||
- Show: summary, approach, task breakdown, dependencies, risks, complexity, estimated time
|
||||
- Options: "Confirm" / "Modify" / "Cancel"
|
||||
- If Modify: Collect feedback via "Other" option, re-run Phase 3 with modifications
|
||||
- If Cancel: Exit workflow
|
||||
- If Confirm: Proceed to Question 2
|
||||
|
||||
**Question 2: Execution Method Selection** (Only if task confirmed)
|
||||
|
||||
Ask user to select execution method:
|
||||
- Show recommendation from `planObject.recommended_execution`
|
||||
- Options:
|
||||
- "Direct - Execute with Agent" (@code-developer)
|
||||
- "CLI - Gemini" (gemini-2.5-pro)
|
||||
- "CLI - Codex" (gpt-5)
|
||||
- "CLI - Qwen" (coder-model)
|
||||
- Store selection for Phase 5 execution
|
||||
|
||||
**Simplified AskUserQuestion Reference**:
|
||||
```javascript
|
||||
// Question 1: Task Confirmation
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: `[Display plan with all details]\n\nDo you confirm this plan?`,
|
||||
header: "Confirm Plan",
|
||||
options: [
|
||||
{ label: "Confirm", description: "Proceed to execution" },
|
||||
{ label: "Modify", description: "Adjust plan" },
|
||||
{ label: "Cancel", description: "Abort" }
|
||||
]
|
||||
}]
|
||||
})
|
||||
|
||||
// Question 2: Execution Method (if confirmed)
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: `Select execution method:\n[Show recommendation and tool descriptions]`,
|
||||
header: "Execution Method",
|
||||
options: [
|
||||
{ label: "Direct - Agent", description: "Interactive execution" },
|
||||
{ label: "CLI - Gemini", description: "gemini-2.5-pro" },
|
||||
{ label: "CLI - Codex", description: "gpt-5" },
|
||||
{ label: "CLI - Qwen", description: "coder-model" }
|
||||
]
|
||||
}]
|
||||
})
|
||||
```
|
||||
|
||||
**Decision Flow**:
|
||||
```
|
||||
Task Confirmation:
|
||||
├─ Confirm → Execution Method Selection → Phase 5
|
||||
├─ Modify → Collect feedback → Re-run Phase 3
|
||||
└─ Cancel → Exit (no execution)
|
||||
|
||||
Execution Method Selection:
|
||||
├─ Direct - Execute with Agent → Launch @code-developer
|
||||
├─ CLI - Gemini → Build and execute Gemini command
|
||||
├─ CLI - Codex → Build and execute Codex command
|
||||
└─ CLI - Qwen → Build and execute Qwen command
|
||||
```
|
||||
|
||||
**Progress Tracking**:
|
||||
- Mark Phase 4 as completed
|
||||
- Mark Phase 5 as in_progress
|
||||
|
||||
**Expected Duration**: User-dependent (1-3 minutes typical)
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: Execution & Progress Tracking
|
||||
|
||||
**Operations**:
|
||||
- Create TodoWrite task list from plan breakdown
|
||||
- Launch selected execution method (agent or CLI)
|
||||
- Track execution progress with real-time TodoWrite updates
|
||||
- Display status to user
|
||||
|
||||
**Step 5.1: Create TodoWrite Task List**
|
||||
|
||||
**Before execution starts**, create task list:
|
||||
```javascript
|
||||
TodoWrite({
|
||||
todos: planObject.tasks.map((task, index) => ({
|
||||
content: task,
|
||||
status: "pending",
|
||||
activeForm: task.replace(/^(.*?):/, "$1ing:") // "Implement X" -> "Implementing X"
|
||||
}))
|
||||
})
|
||||
```
|
||||
|
||||
**Example Task List**:
|
||||
```
|
||||
[ ] Implement authentication service in src/auth/service.ts
|
||||
[ ] Create JWT token utilities in src/auth/jwt.ts
|
||||
[ ] Add authentication middleware to src/middleware/auth.ts
|
||||
[ ] Update API routes to use authentication
|
||||
[ ] Add integration tests for auth flow
|
||||
```
|
||||
|
||||
**Step 5.2: Launch Execution**
|
||||
|
||||
Based on user selection in Phase 4, execute appropriate method:
|
||||
|
||||
#### Option A: Direct Execution with Agent
|
||||
|
||||
**Operations**:
|
||||
- Launch @code-developer agent with full plan context
|
||||
- Agent receives exploration findings, clarifications, and task breakdown
|
||||
- Agent call format:
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="code-developer",
|
||||
description="Implement planned tasks with progress tracking",
|
||||
prompt=`
|
||||
Implement the following tasks with TodoWrite progress updates:
|
||||
|
||||
Summary: ${planObject.summary}
|
||||
|
||||
Task Breakdown:
|
||||
${planObject.tasks.map((t, i) => `${i+1}. ${t}`).join('\n')}
|
||||
|
||||
${planObject.dependencies ? `\nTask Dependencies:\n${planObject.dependencies.join('\n')}` : ''}
|
||||
|
||||
Implementation Approach:
|
||||
${planObject.approach}
|
||||
|
||||
Code Context:
|
||||
${explorationContext || "No exploration performed"}
|
||||
|
||||
${clarificationContext ? `\nClarifications:\n${clarificationContext}` : ''}
|
||||
|
||||
${planObject.risks ? `\nRisks to Consider:\n${planObject.risks.join('\n')}` : ''}
|
||||
|
||||
IMPORTANT Instructions:
|
||||
- Update TodoWrite as you complete each task (mark as completed)
|
||||
- Follow task dependencies if specified
|
||||
- Implement tasks in sequence unless independent
|
||||
- Test functionality as you go
|
||||
- Handle risks proactively
|
||||
`
|
||||
)
|
||||
```
|
||||
|
||||
**Agent Responsibilities**:
|
||||
- Mark tasks as in_progress when starting
|
||||
- Mark tasks as completed when finished
|
||||
- Update TodoWrite in real-time for user visibility
|
||||
|
||||
#### Option B: CLI Execution (Gemini/Codex/Qwen)
|
||||
|
||||
**Operations**:
|
||||
- Build CLI command with comprehensive context
|
||||
- Execute CLI tool with write permissions
|
||||
- Monitor CLI output and update TodoWrite based on progress indicators
|
||||
- Parse CLI completion signals to mark tasks as done
|
||||
|
||||
**Command Format (Gemini)** - Full context with exploration and clarifications:
|
||||
```bash
|
||||
gemini -p "
|
||||
PURPOSE: Implement planned tasks with full context from exploration and planning
|
||||
TASK:
|
||||
${planObject.tasks.map((t, i) => `• ${t}`).join('\n')}
|
||||
|
||||
MODE: write
|
||||
|
||||
CONTEXT: @**/* | Memory: Implementation plan from lite-plan workflow
|
||||
|
||||
## Exploration Findings
|
||||
${explorationContext ? `
|
||||
Project Structure:
|
||||
${explorationContext.project_structure || 'Not available'}
|
||||
|
||||
Relevant Files:
|
||||
${explorationContext.relevant_files?.join('\n') || 'Not specified'}
|
||||
|
||||
Current Implementation Patterns:
|
||||
${explorationContext.patterns || 'Not analyzed'}
|
||||
|
||||
Dependencies and Integration Points:
|
||||
${explorationContext.dependencies || 'Not specified'}
|
||||
|
||||
Architecture Constraints:
|
||||
${explorationContext.constraints || 'None identified'}
|
||||
` : 'No exploration performed (task did not require codebase context)'}
|
||||
|
||||
## User Clarifications
|
||||
${clarificationContext ? `
|
||||
The following clarifications were provided by the user after exploration:
|
||||
${Object.entries(clarificationContext).map(([q, a]) => `Q: ${q}\nA: ${a}`).join('\n\n')}
|
||||
` : 'No clarifications needed'}
|
||||
|
||||
## Implementation Plan Context
|
||||
Task Summary: ${planObject.summary}
|
||||
|
||||
Implementation Approach:
|
||||
${planObject.approach}
|
||||
|
||||
${planObject.dependencies ? `
|
||||
Task Dependencies (execute in order):
|
||||
${planObject.dependencies.join('\n')}
|
||||
` : ''}
|
||||
|
||||
${planObject.risks ? `
|
||||
Identified Risks:
|
||||
${planObject.risks.join('\n')}
|
||||
` : ''}
|
||||
|
||||
Complexity Level: ${planObject.complexity}
|
||||
Estimated Time: ${planObject.estimated_time}
|
||||
|
||||
EXPECTED: All tasks implemented following the plan approach, with proper error handling and testing
|
||||
|
||||
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/02-implement-feature.txt) | Follow implementation approach exactly | Handle identified risks proactively | write=CREATE/MODIFY/DELETE
|
||||
" -m gemini-2.5-pro --approval-mode yolo
|
||||
```
|
||||
|
||||
**Command Format (Codex)** - Session-based with resume support:
|
||||
|
||||
**First Execution (Establish Session)**:
|
||||
```bash
|
||||
codex --full-auto exec "
|
||||
TASK: ${planObject.summary}
|
||||
|
||||
## Task Breakdown
|
||||
${planObject.tasks.map((t, i) => `${i+1}. ${t}`).join('\n')}
|
||||
|
||||
${planObject.dependencies ? `\n## Task Dependencies\n${planObject.dependencies.join('\n')}` : ''}
|
||||
|
||||
## Implementation Approach
|
||||
${planObject.approach}
|
||||
|
||||
## Code Context from Exploration
|
||||
${explorationContext ? `
|
||||
Project Structure: ${explorationContext.project_structure || 'Standard structure'}
|
||||
Relevant Files: ${explorationContext.relevant_files?.join(', ') || 'TBD'}
|
||||
Current Patterns: ${explorationContext.patterns || 'Follow existing conventions'}
|
||||
Integration Points: ${explorationContext.dependencies || 'None specified'}
|
||||
Constraints: ${explorationContext.constraints || 'None'}
|
||||
` : 'No prior exploration - analyze codebase as needed'}
|
||||
|
||||
${clarificationContext ? `\n## User Clarifications\n${Object.entries(clarificationContext).map(([q, a]) => `${q}: ${a}`).join('\n')}` : ''}
|
||||
|
||||
${planObject.risks ? `\n## Risks to Handle\n${planObject.risks.join('\n')}` : ''}
|
||||
|
||||
## Execution Instructions
|
||||
- Complete all tasks following the breakdown sequence
|
||||
- Respect task dependencies if specified
|
||||
- Test functionality as you implement
|
||||
- Handle identified risks proactively
|
||||
- Create session for potential resume if needed
|
||||
|
||||
Complexity: ${planObject.complexity}
|
||||
" -m gpt-5 --skip-git-repo-check -s danger-full-access
|
||||
```
|
||||
|
||||
**Subsequent Executions (Resume if needed)**:
|
||||
```bash
|
||||
# If first execution fails or is interrupted, can resume:
|
||||
codex --full-auto exec "
|
||||
Continue implementation from previous session.
|
||||
|
||||
Remaining tasks:
|
||||
${remaining_tasks.map((t, i) => `${i+1}. ${t}`).join('\n')}
|
||||
|
||||
Maintain context from previous execution.
|
||||
" resume --last -m gpt-5 --skip-git-repo-check -s danger-full-access
|
||||
```
|
||||
|
||||
**Codex Session Strategy**:
|
||||
- First execution establishes full context and creates session
|
||||
- If execution is interrupted or fails, use `resume --last` to continue
|
||||
- Resume inherits all context from original execution
|
||||
- Useful for complex tasks that may hit timeouts or require iteration
|
||||
|
||||
**Command Format (Qwen)** - Full context similar to Gemini:
|
||||
```bash
|
||||
qwen -p "
|
||||
PURPOSE: Implement planned tasks with comprehensive context
|
||||
|
||||
TASK:
|
||||
${planObject.tasks.map((t, i) => `• ${t}`).join('\n')}
|
||||
|
||||
MODE: write
|
||||
|
||||
CONTEXT: @**/* | Memory: Full implementation context from lite-plan
|
||||
|
||||
## Code Exploration Results
|
||||
${explorationContext ? `
|
||||
Analyzed Project Structure:
|
||||
${explorationContext.project_structure || 'Standard structure'}
|
||||
|
||||
Key Files to Modify:
|
||||
${explorationContext.relevant_files?.join('\n') || 'To be determined during implementation'}
|
||||
|
||||
Existing Code Patterns:
|
||||
${explorationContext.patterns || 'Follow codebase conventions'}
|
||||
|
||||
Dependencies:
|
||||
${explorationContext.dependencies || 'None specified'}
|
||||
|
||||
Constraints:
|
||||
${explorationContext.constraints || 'None identified'}
|
||||
` : 'No exploration performed - analyze codebase patterns as you implement'}
|
||||
|
||||
## Clarifications from User
|
||||
${clarificationContext ? `
|
||||
${Object.entries(clarificationContext).map(([question, answer]) => `
|
||||
Question: ${question}
|
||||
Answer: ${answer}
|
||||
`).join('\n')}
|
||||
` : 'No additional clarifications provided'}
|
||||
|
||||
## Implementation Strategy
|
||||
Summary: ${planObject.summary}
|
||||
|
||||
Approach:
|
||||
${planObject.approach}
|
||||
|
||||
${planObject.dependencies ? `
|
||||
Task Order (follow sequence):
|
||||
${planObject.dependencies.join('\n')}
|
||||
` : ''}
|
||||
|
||||
${planObject.risks ? `
|
||||
Risk Mitigation:
|
||||
${planObject.risks.join('\n')}
|
||||
` : ''}
|
||||
|
||||
Task Complexity: ${planObject.complexity}
|
||||
Time Estimate: ${planObject.estimated_time}
|
||||
|
||||
EXPECTED: Complete implementation with tests and proper error handling
|
||||
|
||||
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/02-implement-feature.txt) | Follow approach strictly | Test thoroughly | write=CREATE/MODIFY/DELETE
|
||||
" -m coder-model --approval-mode yolo
|
||||
```
|
||||
|
||||
**Execution with Progress Tracking**:
|
||||
```javascript
|
||||
// Launch CLI in background
|
||||
bash_result = Bash(
|
||||
command=cli_command,
|
||||
timeout=600000, // 10 minutes
|
||||
run_in_background=true
|
||||
)
|
||||
|
||||
// Monitor output and update TodoWrite
|
||||
// Parse CLI output for task completion indicators
|
||||
// Update TodoWrite when tasks complete
|
||||
// Example: When CLI outputs "✓ Task 1 complete" -> Mark task 1 as completed
|
||||
```
|
||||
|
||||
**CLI Progress Monitoring**:
|
||||
- Parse CLI output for completion keywords ("done", "complete", "✓", etc.)
|
||||
- Update corresponding TodoWrite tasks based on progress
|
||||
- Provide real-time visibility to user
|
||||
|
||||
**Step 5.3: Track Execution Progress**
|
||||
|
||||
**Real-time TodoWrite Updates**:
|
||||
```javascript
|
||||
// As execution progresses, update task status:
|
||||
|
||||
// Task started
|
||||
TodoWrite({
|
||||
todos: [
|
||||
{ content: "Implement auth service", status: "in_progress", activeForm: "Implementing auth service" },
|
||||
{ content: "Create JWT utilities", status: "pending", activeForm: "Creating JWT utilities" },
|
||||
// ...
|
||||
]
|
||||
})
|
||||
|
||||
// Task completed
|
||||
TodoWrite({
|
||||
todos: [
|
||||
{ content: "Implement auth service", status: "completed", activeForm: "Implementing auth service" },
|
||||
{ content: "Create JWT utilities", status: "in_progress", activeForm: "Creating JWT utilities" },
|
||||
// ...
|
||||
]
|
||||
})
|
||||
```
|
||||
|
||||
**User Visibility**:
|
||||
- User sees real-time task progress
|
||||
- Current task highlighted as "in_progress"
|
||||
- Completed tasks marked with checkmark
|
||||
- Pending tasks remain unchecked
|
||||
|
||||
**Progress Tracking**:
|
||||
- Mark Phase 5 as in_progress throughout execution
|
||||
- Mark Phase 5 as completed when all tasks done
|
||||
- Final status summary displayed to user
|
||||
|
||||
**Expected Duration**: Varies by task complexity and execution method
|
||||
- Low complexity: 5-15 minutes
|
||||
- Medium complexity: 15-45 minutes
|
||||
- High complexity: 45-120 minutes
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Workflow Intelligence
|
||||
|
||||
1. **Dynamic Adaptation**: Workflow automatically adjusts based on task characteristics
|
||||
- Smart exploration: Only runs when task requires codebase context
|
||||
- Adaptive planning: Simple tasks get direct planning, complex tasks use specialized agent
|
||||
- Context-aware clarification: Only asks questions when truly needed
|
||||
- Reduces unnecessary steps while maintaining thoroughness
|
||||
|
||||
2. **Progressive Clarification**: Gather information at the right time
|
||||
- Phase 1: Explore codebase to understand current state
|
||||
- Phase 2: Ask clarifying questions based on exploration findings
|
||||
- Phase 3: Plan with complete context (task + exploration + clarifications)
|
||||
- Avoids premature assumptions and reduces rework
|
||||
|
||||
3. **Complexity-Aware Planning**: Planning strategy matches task complexity
|
||||
- Low complexity (1-2 files): Direct planning by current Claude (fast, 20-30s)
|
||||
- Medium complexity (3-5 files): CLI planning agent (detailed, 40-50s)
|
||||
- High complexity (6+ files): CLI planning agent with risk analysis (thorough, 50-60s)
|
||||
- Balances speed and thoroughness appropriately
|
||||
|
||||
4. **Two-Dimensional Confirmation**: Separate task approval from execution method
|
||||
- First dimension: Confirm/Modify/Cancel plan
|
||||
- Second dimension: Direct execution vs CLI execution
|
||||
- Allows plan refinement without re-selecting execution method
|
||||
- Supports iterative planning with user feedback
|
||||
|
||||
### Task Management
|
||||
|
||||
1. **Live Progress Tracking**: TodoWrite provides real-time execution visibility
|
||||
- Tasks created before execution starts
|
||||
- Updated in real-time as work progresses
|
||||
- User sees current task being worked on
|
||||
- Clear completion status throughout execution
|
||||
|
||||
2. **Phase-Based Organization**: 5 distinct phases with clear transitions
|
||||
- Phase 1: Task Analysis & Exploration (automatic)
|
||||
- Phase 2: Clarification (conditional, interactive)
|
||||
- Phase 3: Planning (automatic, adaptive)
|
||||
- Phase 4: Confirmation (interactive, two-dimensional)
|
||||
- Phase 5: Execution & Tracking (automatic with live updates)
|
||||
|
||||
3. **Flexible Task Counts**: Task breakdown adapts to complexity
|
||||
- Low complexity: 3-5 tasks (focused)
|
||||
- Medium complexity: 5-7 tasks (detailed)
|
||||
- High complexity: 7-10 tasks (comprehensive)
|
||||
- Avoids artificial constraints while maintaining focus
|
||||
|
||||
4. **Dependency Tracking**: Medium/High complexity tasks include dependencies
|
||||
- Explicit task ordering when sequence matters
|
||||
- Parallel execution hints when tasks are independent
|
||||
- Risk flagging for complex interactions
|
||||
- Helps agent/CLI execute correctly
|
||||
|
||||
### Planning Standards
|
||||
|
||||
1. **Context-Rich Planning**: Plans include all relevant context
|
||||
- Exploration findings (code structure, patterns, constraints)
|
||||
- User clarifications (requirements, preferences, decisions)
|
||||
- Complexity assessment (risks, dependencies, time estimates)
|
||||
- Execution recommendations (Direct vs CLI, specific tool)
|
||||
|
||||
2. **Modification Support**: Plans can be iteratively refined
|
||||
- User can request plan modifications in Phase 4
|
||||
- Feedback incorporated into re-planning
|
||||
- No need to restart from scratch
|
||||
- Supports collaborative planning workflow
|
||||
|
||||
3. **No File Artifacts**: All planning stays in memory
|
||||
- Faster workflow without I/O overhead
|
||||
- Cleaner workspace
|
||||
- Plan context passed directly to execution
|
||||
- Reduces complexity and maintenance
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Common Errors
|
||||
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| Phase 1 Exploration Failure | cli-explore-agent unavailable or timeout | Skip exploration, set `explorationContext = null`, log warning, continue to Phase 2/3 with task description only |
|
||||
| Phase 2 Clarification Timeout | User no response > 5 minutes | Use exploration findings as-is without clarification, proceed to Phase 3 with warning |
|
||||
| Phase 3 Planning Agent Failure | cli-planning-agent unavailable or timeout | Fallback to direct planning by current Claude (simplified plan), continue to Phase 4 |
|
||||
| Phase 3 Planning Timeout | Planning takes > 90 seconds | Generate simplified direct plan, mark as "Quick Plan", continue to Phase 4 with reduced detail |
|
||||
| Phase 4 Confirmation Timeout | User no response > 5 minutes | Save plan context to temporary var, display resume instructions, exit gracefully |
|
||||
| Phase 4 Modification Loop | User requests modify > 3 times | Suggest breaking task into smaller pieces or using /workflow:plan for comprehensive planning |
|
||||
| Phase 5 CLI Tool Unavailable | Selected CLI tool not installed | Show installation instructions, offer to re-select (Direct execution or different CLI) |
|
||||
| Phase 5 Execution Failure | Agent/CLI crashes or errors | Display error details, save partial progress from TodoWrite, suggest manual recovery or retry |
|
||||
|
||||
## Input/Output
|
||||
|
||||
### Input Requirements
|
||||
- Task description: String or path to .md file (required)
|
||||
- Should be specific and concrete
|
||||
- Can include context about existing code or requirements
|
||||
- Examples:
|
||||
- "Implement user authentication with JWT tokens"
|
||||
- "Refactor logging module for better performance"
|
||||
- "Add unit tests for authentication service"
|
||||
- Flags (optional):
|
||||
- `--tool <name>`: Preset execution tool (claude|gemini|codex|qwen)
|
||||
- `--quick`: Skip code exploration phase
|
||||
|
||||
### Output Format
|
||||
|
||||
**In-Memory Plan Object**:
|
||||
```javascript
|
||||
{
|
||||
summary: "2-3 sentence overview of implementation",
|
||||
approach: "High-level implementation strategy",
|
||||
tasks: [
|
||||
"Task 1: Specific action with file locations",
|
||||
"Task 2: Specific action with file locations",
|
||||
// ... 3-7 tasks total
|
||||
],
|
||||
complexity: "Low|Medium|High",
|
||||
recommended_tool: "Claude|Gemini|Codex|Qwen",
|
||||
estimated_time: "X minutes"
|
||||
}
|
||||
```
|
||||
|
||||
**Execution Result**:
|
||||
- Immediate dispatch to selected tool/agent with plan context
|
||||
- No file artifacts generated during planning phase
|
||||
- Execution starts immediately after user confirmation
|
||||
- Tool/agent handles implementation and any necessary file operations
|
||||
|
||||
@@ -286,17 +286,16 @@ CATCH error:
|
||||
[
|
||||
{"content": "Phase 0: Validate parameters and prepare session", "status": "completed", "activeForm": "Validating parameters"},
|
||||
{"content": "Phase 1: Style extraction from source code (import-from-code)", "status": "completed", "activeForm": "Extracting styles"},
|
||||
{"content": "Phase 2.1: Validation and preparation (reference-page-generator)", "status": "in_progress", "activeForm": "Validating parameters"},
|
||||
{"content": "Phase 2.2: Component pattern extraction (reference-page-generator)", "status": "pending", "activeForm": "Extracting component patterns"},
|
||||
{"content": "Phase 2.3: Generate preview pages (reference-page-generator)", "status": "pending", "activeForm": "Generating preview"},
|
||||
{"content": "Phase 2.4: Generate metadata and documentation (reference-page-generator)", "status": "pending", "activeForm": "Generating documentation"},
|
||||
{"content": "Phase 2.0: Setup and validation (reference-page-generator)", "status": "in_progress", "activeForm": "Validating parameters"},
|
||||
{"content": "Phase 2.1: Prepare component data (reference-page-generator)", "status": "pending", "activeForm": "Copying layout templates"},
|
||||
{"content": "Phase 2.2: Generate preview pages (reference-page-generator)", "status": "pending", "activeForm": "Generating preview"},
|
||||
{"content": "Phase 3: Cleanup and verify package", "status": "pending", "activeForm": "Cleanup and verification"}
|
||||
]
|
||||
```
|
||||
|
||||
**Note**: Phase 1 tasks completed and collapsed. SlashCommand invocation **attaches** reference-page-generator's 4 tasks. Orchestrator **executes** these tasks itself.
|
||||
**Note**: Phase 1 tasks completed and collapsed. SlashCommand invocation **attaches** reference-page-generator's 3 tasks. Orchestrator **executes** these tasks itself.
|
||||
|
||||
**Next Action**: Tasks attached → **Execute Phase 2.1-2.4** sequentially
|
||||
**Next Action**: Tasks attached → **Execute Phase 2.0-2.2** sequentially
|
||||
|
||||
---
|
||||
|
||||
@@ -317,22 +316,19 @@ command = "/workflow:ui-design:reference-page-generator " +
|
||||
|
||||
```bash
|
||||
TRY:
|
||||
# SlashCommand invocation ATTACHES reference-page-generator's 4 tasks to current workflow
|
||||
# SlashCommand invocation ATTACHES reference-page-generator's 3 tasks to current workflow
|
||||
# Orchestrator will EXECUTE these attached tasks itself:
|
||||
# 1. Phase 2.1: Validation and preparation
|
||||
# 2. Phase 2.2: Component pattern extraction
|
||||
# 3. Phase 2.3: Generate preview pages
|
||||
# 4. Phase 2.4: Generate metadata and documentation
|
||||
# 1. Phase 2.0: Setup and validation
|
||||
# 2. Phase 2.1: Prepare component data
|
||||
# 3. Phase 2.2: Generate preview pages
|
||||
SlashCommand(command)
|
||||
|
||||
# After executing all attached tasks, verify package outputs
|
||||
required_files = [
|
||||
"layout-templates.json",
|
||||
"design-tokens.json",
|
||||
"component-patterns.json",
|
||||
"preview.html",
|
||||
"preview.css",
|
||||
"metadata.json",
|
||||
"README.md"
|
||||
"preview.css"
|
||||
]
|
||||
|
||||
missing_files = []
|
||||
@@ -365,16 +361,14 @@ CATCH error:
|
||||
- ✅ `reference-page-generator` executed successfully
|
||||
- ✅ Reference package created at `${package_path}/`
|
||||
- ✅ All required files present:
|
||||
- `layout-templates.json` - Layout templates from design run
|
||||
- `design-tokens.json` - Complete design token system
|
||||
- `component-patterns.json` - Component catalog
|
||||
- `preview.html` - Interactive multi-component showcase
|
||||
- `preview.css` - Showcase styling
|
||||
- `metadata.json` - Package metadata and version info
|
||||
- `README.md` - Package documentation and usage guide
|
||||
- ⭕ Optional files:
|
||||
- `animation-tokens.json` - Animation specifications (if available from extraction)
|
||||
|
||||
<!-- TodoWrite: REMOVE Phase 2.1-2.4 tasks, restore to orchestrator view -->
|
||||
<!-- TodoWrite: REMOVE Phase 2.0-2.2 tasks, restore to orchestrator view -->
|
||||
|
||||
**TodoWrite Update (Phase 2 completed - tasks collapsed)**:
|
||||
```json
|
||||
@@ -414,7 +408,7 @@ IF package_exists != "exists":
|
||||
|
||||
# Get absolute path and component count for final report
|
||||
absolute_package_path = Bash(cd "${package_path}" && pwd 2>/dev/null || echo "${package_path}")
|
||||
component_count = Bash(jq -r '.extraction_metadata.component_count // "unknown"' "${package_path}/component-patterns.json" 2>/dev/null || echo "unknown")
|
||||
component_count = Bash(jq -r '.layout_templates | length // "unknown"' "${package_path}/layout-templates.json" 2>/dev/null || echo "unknown")
|
||||
anim_exists = Bash(test -f "${package_path}/animation-tokens.json" && echo "✓" || echo "○")
|
||||
```
|
||||
|
||||
@@ -434,7 +428,7 @@ anim_exists = Bash(test -f "${package_path}/animation-tokens.json" && echo "✓"
|
||||
📄 Source: {source}
|
||||
📊 Components: {component_count}
|
||||
|
||||
Files: design-tokens.json, style-guide.md, component-patterns.json, preview.html, preview.css, metadata.json, README.md
|
||||
Files: layout-templates.json, design-tokens.json, animation-tokens.json (optional), preview.html, preview.css
|
||||
|
||||
Preview: file://{absolute_package_path}/preview.html
|
||||
|
||||
@@ -473,12 +467,12 @@ TodoWrite({todos: [
|
||||
// - TodoWrite becomes: Phase 0-1 (completed) + Phase 2 + Phase 3
|
||||
//
|
||||
// 4. PHASE 2 SlashCommand INVOCATION:
|
||||
// - SlashCommand(/workflow:ui-design:reference-page-generator) ATTACHES 4 tasks
|
||||
// - TodoWrite expands to: Phase 0-1 (completed) + 4 reference-page-generator tasks + Phase 3
|
||||
// - Orchestrator EXECUTES these 4 tasks sequentially (Phase 2.1 → 2.2 → 2.3 → 2.4)
|
||||
// - SlashCommand(/workflow:ui-design:reference-page-generator) ATTACHES 3 tasks
|
||||
// - TodoWrite expands to: Phase 0-1 (completed) + 3 reference-page-generator tasks + Phase 3
|
||||
// - Orchestrator EXECUTES these 3 tasks sequentially (Phase 2.0 → 2.1 → 2.2)
|
||||
//
|
||||
// 5. PHASE 2 TASKS COMPLETED:
|
||||
// - All 4 reference-page-generator tasks executed and completed
|
||||
// - All 3 reference-page-generator tasks executed and completed
|
||||
// - COLLAPSE completed tasks into Phase 2 summary
|
||||
// - TodoWrite returns to: Phase 0-2 (completed) + Phase 3 (in_progress)
|
||||
//
|
||||
@@ -533,25 +527,22 @@ User triggers: /workflow:ui-design:codify-style ./src --package-name my-style-v1
|
||||
↓
|
||||
[Phase 1 Complete] → TodoWrite: COLLAPSE Phase 1.0-1.3 into Phase 1 summary
|
||||
↓
|
||||
[Phase 2 Invoke] → SlashCommand(/workflow:ui-design:reference-page-generator) ATTACHES 4 tasks
|
||||
[Phase 2 Invoke] → SlashCommand(/workflow:ui-design:reference-page-generator) ATTACHES 3 tasks
|
||||
├─ Phase 0 (completed)
|
||||
├─ Phase 1: Style extraction from source code (completed) ← COLLAPSED
|
||||
├─ Phase 2.1: Validation and preparation (in_progress) ← ATTACHED
|
||||
├─ Phase 2.2: Component pattern extraction (pending) ← ATTACHED
|
||||
├─ Phase 2.3: Generate preview pages (pending) ← ATTACHED
|
||||
├─ Phase 2.4: Generate metadata and documentation (pending) ← ATTACHED
|
||||
├─ Phase 2.0: Setup and validation (in_progress) ← ATTACHED
|
||||
├─ Phase 2.1: Prepare component data (pending) ← ATTACHED
|
||||
├─ Phase 2.2: Generate preview pages (pending) ← ATTACHED
|
||||
└─ Phase 3: Cleanup and verify package (pending)
|
||||
↓
|
||||
[Execute Phase 2.1] → Validate parameters (orchestrator executes this)
|
||||
[Execute Phase 2.0] → Setup and validation (orchestrator executes this)
|
||||
↓
|
||||
[Execute Phase 2.2] → Extract component patterns (orchestrator executes this)
|
||||
[Execute Phase 2.1] → Prepare component data (orchestrator executes this)
|
||||
↓
|
||||
[Execute Phase 2.3] → Generate preview pages (orchestrator executes this)
|
||||
[Execute Phase 2.2] → Generate preview pages (orchestrator executes this)
|
||||
└─ Outputs: layout-templates.json, design-tokens.json, animation-tokens.json (optional), preview.html, preview.css
|
||||
↓
|
||||
[Execute Phase 2.4] → Generate metadata and docs (orchestrator executes this)
|
||||
└─ Outputs: component-patterns.json, preview.html, preview.css, metadata.json, README.md
|
||||
↓
|
||||
[Phase 2 Complete] → TodoWrite: COLLAPSE Phase 2.1-2.4 into Phase 2 summary
|
||||
[Phase 2 Complete] → TodoWrite: COLLAPSE Phase 2.0-2.2 into Phase 2 summary
|
||||
├─ Phase 0 (completed)
|
||||
├─ Phase 1: Style extraction from source code (completed)
|
||||
├─ Phase 2: Reference package generation (completed) ← COLLAPSED
|
||||
@@ -618,14 +609,11 @@ File discovery is fully automatic - no glob patterns needed.
|
||||
.workflow/
|
||||
├── reference_style/ # Default output directory
|
||||
│ └── {package-name}/
|
||||
│ ├── layout-templates.json
|
||||
│ ├── design-tokens.json
|
||||
│ ├── style-guide.md
|
||||
│ ├── component-patterns.json
|
||||
│ ├── animation-tokens.json (optional)
|
||||
│ ├── preview.html
|
||||
│ ├── preview.css
|
||||
│ ├── metadata.json
|
||||
│ └── README.md
|
||||
│ └── preview.css
|
||||
│
|
||||
└── codify-temp-{timestamp}/ # Temporary workspace (cleaned up after completion)
|
||||
├── style-extraction/
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: explore-auto
|
||||
description: Interactive exploratory UI design workflow with style-centric batch generation, creates design variants from prompts/images with parallel execution and user selection
|
||||
argument-hint: "[--input "<value>"] [--targets "<list>"] [--target-type "page|component"] [--session <id>] [--style-variants <count>] [--layout-variants <count>] [--batch-plan]"
|
||||
argument-hint: "[--input "<value>"] [--targets "<list>"] [--target-type "page|component"] [--session <id>] [--style-variants <count>] [--layout-variants <count>]"
|
||||
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*), Task(conceptual-planning-agent)
|
||||
---
|
||||
|
||||
@@ -25,18 +25,18 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
|
||||
- **ELSE**: Skip (use code import) → Auto-continues to Phase 9
|
||||
5. Phase 9 (layout-extract) → **Attach tasks → Execute → Collapse** → Auto-continues to Phase 10
|
||||
6. **Phase 10 (ui-assembly)** → **Attach tasks → Execute → Collapse** → Auto-continues to Phase 11
|
||||
7. Phase 11 (design-update) → **Attach tasks → Execute → Collapse** → Auto-continues to Phase 12 (if --batch-plan)
|
||||
8. Phase 12 (batch-plan, optional) → Reports completion
|
||||
7. **Phase 11 (preview-generation)** → **Execute script → Generate preview files** → Reports completion
|
||||
|
||||
**Phase Transition Mechanism**:
|
||||
- **Phase 5 (User Interaction)**: User confirms targets → IMMEDIATELY triggers Phase 7
|
||||
- **Phase 7-12 (Autonomous)**: `SlashCommand` invocation **ATTACHES** tasks to current workflow
|
||||
- **Phase 7-10 (Autonomous)**: `SlashCommand` invocation **ATTACHES** tasks to current workflow
|
||||
- **Task Execution**: Orchestrator **EXECUTES** these attached tasks itself
|
||||
- **Task Collapse**: After tasks complete, collapse them into phase summary
|
||||
- **Phase Transition**: Automatically execute next phase after collapsing
|
||||
- **Phase 11 (Script Execution)**: Execute preview generation script
|
||||
- No additional user interaction after Phase 5 confirmation
|
||||
|
||||
**Auto-Continue Mechanism**: TodoWrite tracks phase status with dynamic task attachment/collapse. After executing all attached tasks, you MUST immediately collapse them, restore phase summary, and execute the next phase. No user intervention required. The workflow is NOT complete until reaching Phase 11 (or Phase 12 if --batch-plan).
|
||||
**Auto-Continue Mechanism**: TodoWrite tracks phase status with dynamic task attachment/collapse. After executing all attached tasks, you MUST immediately collapse them, restore phase summary, and execute the next phase. No user intervention required. The workflow is NOT complete until reaching Phase 11 (preview generation).
|
||||
|
||||
**Task Attachment Model**: SlashCommand invocation is NOT delegation - it's task expansion. The orchestrator executes these attached tasks itself, not waiting for external completion.
|
||||
|
||||
@@ -50,7 +50,7 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
|
||||
4. **Default to All**: When selecting variants/prototypes, use ALL generated items
|
||||
5. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
|
||||
6. **⚠️ CRITICAL: Task Attachment Model** - SlashCommand invocation **ATTACHES** tasks to current workflow. Orchestrator **EXECUTES** these attached tasks itself, not waiting for external completion. This is NOT delegation - it's task expansion.
|
||||
7. **⚠️ CRITICAL: DO NOT STOP** - This is a continuous multi-phase workflow. After executing all attached tasks, you MUST immediately collapse them and execute the next phase. Workflow is NOT complete until Phase 11 (or Phase 12 if --batch-plan).
|
||||
7. **⚠️ CRITICAL: DO NOT STOP** - This is a continuous multi-phase workflow. After executing all attached tasks, you MUST immediately collapse them and execute the next phase. Workflow is NOT complete until Phase 11 (preview generation).
|
||||
|
||||
## Parameter Requirements
|
||||
|
||||
@@ -83,7 +83,6 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
|
||||
- `--session <id>`: Workflow session ID (standalone mode if omitted)
|
||||
- `--style-variants <count>`: Style variants (default: inferred from prompt or 3, range: 1-5)
|
||||
- `--layout-variants <count>`: Layout variants per style (default: inferred or 3, range: 1-5)
|
||||
- `--batch-plan`: Auto-generate implementation tasks after design-update
|
||||
|
||||
**Legacy Target Parameters** (maintained for backward compatibility):
|
||||
- `--pages "<list>"`: Alias for `--targets` with `--target-type page`
|
||||
@@ -128,7 +127,7 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
|
||||
**Integrated vs. Standalone**:
|
||||
- `--session` flag determines session integration or standalone execution
|
||||
|
||||
## 12-Phase Execution
|
||||
## 11-Phase Execution
|
||||
|
||||
### Phase 1: Parameter Parsing & Input Detection
|
||||
```bash
|
||||
@@ -585,33 +584,48 @@ SlashCommand(command)
|
||||
# Output:
|
||||
# - {target}-style-{s}-layout-{l}.html (assembled prototypes)
|
||||
# - {target}-style-{s}-layout-{l}.css
|
||||
# - compare.html (interactive matrix view)
|
||||
# - PREVIEW.md (usage instructions)
|
||||
# Note: compare.html and PREVIEW.md will be generated in Phase 11
|
||||
```
|
||||
|
||||
### Phase 11: Design System Integration
|
||||
### Phase 11: Generate Preview Files
|
||||
```bash
|
||||
command = "/workflow:ui-design:update" + (--session ? " --session {session_id}" : "")
|
||||
REPORT: "🚀 Phase 11: Generate Preview Files"
|
||||
|
||||
# SlashCommand invocation ATTACHES update's tasks to current workflow
|
||||
# Orchestrator will EXECUTE these attached tasks itself
|
||||
SlashCommand(command)
|
||||
# Update TodoWrite to reflect preview generation phase
|
||||
TodoWrite({todos: [
|
||||
{"content": "Execute style extraction", "status": "completed", "activeForm": "Executing style extraction"},
|
||||
{"content": "Execute animation extraction", "status": "completed", "activeForm": "Executing animation extraction"},
|
||||
{"content": "Execute layout extraction", "status": "completed", "activeForm": "Executing layout extraction"},
|
||||
{"content": "Execute UI assembly", "status": "completed", "activeForm": "Executing UI assembly"},
|
||||
{"content": "Generate preview files", "status": "in_progress", "activeForm": "Generating preview files"}
|
||||
]})
|
||||
|
||||
# After executing all attached tasks, collapse them into phase summary
|
||||
# When phase finishes:
|
||||
# - If --batch-plan flag present: IMMEDIATELY execute Phase 12 (auto-continue)
|
||||
# - If no --batch-plan: Workflow complete, display final report
|
||||
```
|
||||
# Execute preview generation script
|
||||
Bash(~/.claude/scripts/ui-generate-preview.sh "${base_path}/prototypes")
|
||||
|
||||
### Phase 12: Batch Task Generation (Optional)
|
||||
```bash
|
||||
IF --batch-plan:
|
||||
FOR target IN inferred_target_list:
|
||||
task_desc = "Implement {target} {target_type} based on design system"
|
||||
# Verify output files
|
||||
IF NOT exists("${base_path}/prototypes/compare.html"):
|
||||
ERROR: "Preview generation failed: compare.html not found"
|
||||
EXIT 1
|
||||
|
||||
# SlashCommand invocation ATTACHES plan's tasks to current workflow
|
||||
# Orchestrator will EXECUTE these attached tasks itself
|
||||
SlashCommand("/workflow:plan --agent \"{task_desc}\"")
|
||||
IF NOT exists("${base_path}/prototypes/PREVIEW.md"):
|
||||
ERROR: "Preview generation failed: PREVIEW.md not found"
|
||||
EXIT 1
|
||||
|
||||
# Mark preview generation as complete
|
||||
TodoWrite({todos: [
|
||||
{"content": "Execute style extraction", "status": "completed", "activeForm": "Executing style extraction"},
|
||||
{"content": "Execute animation extraction", "status": "completed", "activeForm": "Executing animation extraction"},
|
||||
{"content": "Execute layout extraction", "status": "completed", "activeForm": "Executing layout extraction"},
|
||||
{"content": "Execute UI assembly", "status": "completed", "activeForm": "Executing UI assembly"},
|
||||
{"content": "Generate preview files", "status": "completed", "activeForm": "Generating preview files"}
|
||||
]})
|
||||
|
||||
REPORT: "✅ Preview files generated successfully"
|
||||
REPORT: " → compare.html (interactive matrix view)"
|
||||
REPORT: " → PREVIEW.md (usage instructions)"
|
||||
|
||||
# Workflow complete, display final report
|
||||
```
|
||||
|
||||
## TodoWrite Pattern
|
||||
@@ -622,7 +636,7 @@ TodoWrite({todos: [
|
||||
{"content": "Execute animation extraction", "status": "pending", "activeForm": "Executing animation extraction"},
|
||||
{"content": "Execute layout extraction", "status": "pending", "activeForm": "Executing layout extraction"},
|
||||
{"content": "Execute UI assembly", "status": "pending", "activeForm": "Executing UI assembly"},
|
||||
{"content": "Execute design integration", "status": "pending", "activeForm": "Executing design integration"}
|
||||
{"content": "Generate preview files", "status": "pending", "activeForm": "Generating preview files"}
|
||||
]})
|
||||
|
||||
// ⚠️ CRITICAL: Dynamic TodoWrite task attachment strategy:
|
||||
@@ -630,18 +644,25 @@ TodoWrite({todos: [
|
||||
// **Key Concept**: SlashCommand invocation ATTACHES tasks to current workflow.
|
||||
// Orchestrator EXECUTES these attached tasks itself, not waiting for external completion.
|
||||
//
|
||||
// Phase 7-12 SlashCommand Invocation Pattern:
|
||||
// Phase 7-10 SlashCommand Invocation Pattern:
|
||||
// 1. SlashCommand invocation ATTACHES sub-command tasks to TodoWrite
|
||||
// 2. TodoWrite expands to include attached tasks
|
||||
// 3. Orchestrator EXECUTES attached tasks sequentially
|
||||
// 4. After all attached tasks complete, COLLAPSE them into phase summary
|
||||
// 5. Update next phase to in_progress
|
||||
// 6. IMMEDIATELY execute next phase SlashCommand (auto-continue)
|
||||
// 6. IMMEDIATELY execute next phase (auto-continue)
|
||||
//
|
||||
// Phase 11 Script Execution Pattern:
|
||||
// 1. Mark "Generate preview files" as in_progress
|
||||
// 2. Execute preview generation script via Bash tool
|
||||
// 3. Verify output files (compare.html, PREVIEW.md)
|
||||
// 4. Mark "Generate preview files" as completed
|
||||
//
|
||||
// Benefits:
|
||||
// ✓ Real-time visibility into sub-command task progress
|
||||
// ✓ Clean orchestrator-level summary after each phase
|
||||
// ✓ Clear mental model: SlashCommand = attach tasks, not delegate work
|
||||
// ✓ Script execution for preview generation (no delegation)
|
||||
// ✓ Dynamic attachment/collapse maintains clarity
|
||||
```
|
||||
|
||||
@@ -661,8 +682,7 @@ Phase 9: {n×l} layout templates (layout-extract with multi-select)
|
||||
Phase 10: UI Assembly (generate)
|
||||
- Pure assembly: layout templates + design tokens
|
||||
- {s}×{l}×{n} = {total} final prototypes
|
||||
Phase 11: Brainstorming artifacts updated
|
||||
[Phase 12: {n} implementation tasks created] # if --batch-plan
|
||||
Phase 11: Preview files generated (compare.html, PREVIEW.md)
|
||||
|
||||
Assembly Process:
|
||||
✅ Separation of Concerns: Layout (structure) + Style (tokens) kept separate
|
||||
@@ -700,6 +720,6 @@ Design Quality:
|
||||
- Layout plans stored as structured JSON
|
||||
- Optimized for {device_type} viewing
|
||||
|
||||
Next: [/workflow:execute] OR [Open compare.html → Select → /workflow:plan]
|
||||
Next: Open compare.html to preview all design variants
|
||||
```
|
||||
|
||||
|
||||
@@ -154,6 +154,23 @@ Task(subagent_type="ui-design-agent",
|
||||
|
||||
## Code Import Extraction Strategy
|
||||
|
||||
**Step 0: Fast Conflict Detection** (Use Bash/Grep for quick global scan)
|
||||
- Quick scan: \`rg --color=never -n "^\\s*--primary:|^\\s*--secondary:|^\\s*--accent:" --type css ${source}\` to find core color definitions with line numbers
|
||||
- Semantic search: \`rg --color=never -B3 -A1 "^\\s*--primary:" --type css ${source}\` to capture surrounding context and comments
|
||||
- Core token scan: Search for --primary, --secondary, --accent, --background patterns to detect all theme-critical definitions
|
||||
- Pattern: rg → Extract values → Compare → If different → Read full context with comments → Record conflict
|
||||
- Alternative (if many files): Execute CLI analysis for comprehensive report:
|
||||
\`\`\`bash
|
||||
cd ${source} && gemini -p \"
|
||||
PURPOSE: Detect color token conflicts across all CSS/SCSS/JS files
|
||||
TASK: • Scan all files for color definitions • Identify conflicting values • Extract semantic comments
|
||||
MODE: analysis
|
||||
CONTEXT: @**/*.css @**/*.scss @**/*.js @**/*.ts
|
||||
EXPECTED: JSON report listing conflicts with file:line, values, semantic context
|
||||
RULES: Focus on core tokens | Report ALL variants | analysis=READ-ONLY
|
||||
\"
|
||||
\`\`\`
|
||||
|
||||
**Step 1: Load file list**
|
||||
- Read(${intermediates_dir}/discovered-files.json)
|
||||
- Extract: file_types.css.files, file_types.js.files, file_types.html.files
|
||||
@@ -163,10 +180,11 @@ Task(subagent_type="ui-design-agent",
|
||||
- JavaScript/TypeScript: Theme configs (Tailwind, styled-components, CSS-in-JS)
|
||||
- HTML: Inline styles, usage patterns
|
||||
|
||||
**Step 3: Smart inference for gaps**
|
||||
- Infer missing tokens from existing patterns
|
||||
- Normalize inconsistent values into systematic scales
|
||||
- Fill missing categories from cross-file references
|
||||
**Step 3: Validation and Conflict Detection**
|
||||
- Report missing tokens WITHOUT inference (mark as "missing" in _metadata.completeness)
|
||||
- Detect and report inconsistent values across files (list ALL variants with file:line sources)
|
||||
- Report missing categories WITHOUT auto-filling (document gaps for manual review)
|
||||
- CRITICAL: Verify core tokens (primary, secondary, accent) against semantic comments in source code
|
||||
|
||||
## Output Files
|
||||
|
||||
@@ -178,7 +196,9 @@ Task(subagent_type="ui-design-agent",
|
||||
- Add \"_metadata.extraction_source\": \"code_import\"
|
||||
- Add \"_metadata.files_analyzed\": {css, js, html file lists}
|
||||
- Add \"_metadata.completeness\": {status, missing_categories, recommendations}
|
||||
- Add \"_metadata.conflicts\": Array of conflicting definitions (MANDATORY if conflicts exist)
|
||||
- Add \"_metadata.code_snippets\": Map of code snippets (see below)
|
||||
- Add \"_metadata.usage_recommendations\": Usage patterns from code (see below)
|
||||
- Include \"source\" field for each token (e.g., \"file.css:23\")
|
||||
|
||||
**Code Snippet Recording**:
|
||||
@@ -198,12 +218,35 @@ Task(subagent_type="ui-design-agent",
|
||||
- Typical ranges: Simple declarations (1-5 lines), Utility classes (5-15 lines), Complete configs (15-50 lines)
|
||||
- Preserve original formatting and indentation
|
||||
|
||||
**Conflict Detection and Reporting**:
|
||||
- When the same token is defined differently across multiple files, record in `_metadata.conflicts`
|
||||
- Follow Agent schema for conflicts array structure (see ui-design-agent.md)
|
||||
- Each conflict MUST include: token_name, category, all definitions with context, selected_value, selection_reason
|
||||
- Selection priority:
|
||||
1. Definitions with semantic comments explaining intent (/* Blue theme */, /* Primary brand color */)
|
||||
2. Definitions that align with overall color scheme described in comments
|
||||
3. When in doubt, report ALL variants and flag for manual review in completeness.recommendations
|
||||
|
||||
**Usage Recommendations Generation**:
|
||||
- Analyze code usage patterns to extract `_metadata.usage_recommendations` (see ui-design-agent.md schema)
|
||||
- **Typography recommendations**:
|
||||
* `common_sizes`: Identify most frequent font size usage (e.g., \"body_text\": \"base (1rem)\")
|
||||
* `common_combinations`: Extract heading+body pairings from actual usage (e.g., h1 with p tags)
|
||||
- **Spacing recommendations**:
|
||||
* `size_guide`: Categorize spacing values into tight/normal/loose based on frequency
|
||||
* `common_patterns`: Extract frequent padding/margin combinations from components
|
||||
- Analysis method: Scan code for class/style usage frequency, extract patterns from component implementations
|
||||
- Optional: If insufficient usage data, mark fields as empty arrays/objects with note in completeness.recommendations
|
||||
|
||||
## Code Import Specific Requirements
|
||||
- ✅ Read discovered-files.json FIRST to get file paths
|
||||
- ✅ Track extraction source for each token (file:line)
|
||||
- ✅ Record complete code snippets in _metadata.code_snippets (complete blocks with dependencies/comments)
|
||||
- ✅ Include completeness assessment in _metadata
|
||||
- ✅ Normalize inconsistent values into systematic scales
|
||||
- ✅ Report inconsistent values with ALL source locations in _metadata.conflicts (DO NOT auto-normalize or choose)
|
||||
- ✅ CRITICAL: Verify core theme tokens (primary, secondary, accent) match source code semantic intent
|
||||
- ✅ When conflicts exist, prefer definitions with semantic comments explaining intent
|
||||
- ❌ NO inference, NO smart filling, NO automatic conflict resolution
|
||||
- ❌ NO external research or web searches (code-only extraction)
|
||||
")
|
||||
```
|
||||
@@ -226,6 +269,23 @@ Task(subagent_type="ui-design-agent",
|
||||
|
||||
## Code Import Extraction Strategy
|
||||
|
||||
**Step 0: Fast Animation Discovery** (Use Bash/Grep for quick pattern detection)
|
||||
- Quick scan: \`rg --color=never -n "@keyframes|animation:|transition:" --type css ${source}\` to find animation definitions with line numbers
|
||||
- Framework detection: \`rg --color=never "framer-motion|gsap|@react-spring|react-spring" --type js --type ts ${source}\` to detect animation frameworks
|
||||
- Pattern categorization: \`rg --color=never -B2 -A5 "@keyframes" --type css ${source}\` to extract keyframe animations with context
|
||||
- Pattern: rg → Identify animation types → Map framework usage → Prioritize extraction targets
|
||||
- Alternative (if complex framework mix): Execute CLI analysis for comprehensive report:
|
||||
\`\`\`bash
|
||||
cd ${source} && gemini -p \"
|
||||
PURPOSE: Detect animation frameworks and patterns
|
||||
TASK: • Identify frameworks • Map animation patterns • Categorize by complexity
|
||||
MODE: analysis
|
||||
CONTEXT: @**/*.css @**/*.scss @**/*.js @**/*.ts
|
||||
EXPECTED: JSON report listing frameworks, animation types, file locations
|
||||
RULES: Focus on framework consistency | Map all animations | analysis=READ-ONLY
|
||||
\"
|
||||
\`\`\`
|
||||
|
||||
**Step 1: Load file list**
|
||||
- Read(${intermediates_dir}/discovered-files.json)
|
||||
- Extract: file_types.css.files, file_types.js.files, file_types.html.files
|
||||
@@ -288,6 +348,23 @@ Task(subagent_type="ui-design-agent",
|
||||
|
||||
## Code Import Extraction Strategy
|
||||
|
||||
**Step 0: Fast Component Discovery** (Use Bash/Grep for quick component scan)
|
||||
- Layout pattern scan: \`rg --color=never -n "display:\\s*(grid|flex)|grid-template" --type css ${source}\` to find layout systems
|
||||
- Component class scan: \`rg --color=never "class.*=.*\\"[^\"]*\\b(btn|button|card|input|modal|dialog|dropdown)" --type html --type js --type ts ${source}\` to identify UI components
|
||||
- Universal component heuristic: Components appearing in 3+ files = universal, <3 files = specialized
|
||||
- Pattern: rg → Count occurrences → Classify by frequency → Prioritize universal components
|
||||
- Alternative (if large codebase): Execute CLI analysis for comprehensive categorization:
|
||||
\`\`\`bash
|
||||
cd ${source} && gemini -p \"
|
||||
PURPOSE: Classify components as universal vs specialized
|
||||
TASK: • Identify UI components • Classify reusability • Map layout systems
|
||||
MODE: analysis
|
||||
CONTEXT: @**/*.css @**/*.scss @**/*.js @**/*.ts @**/*.html
|
||||
EXPECTED: JSON report categorizing components, layout patterns, naming conventions
|
||||
RULES: Focus on component reusability | Identify layout systems | analysis=READ-ONLY
|
||||
\"
|
||||
\`\`\`
|
||||
|
||||
**Step 1: Load file list**
|
||||
- Read(${intermediates_dir}/discovered-files.json)
|
||||
- Extract: file_types.css.files, file_types.js.files, file_types.html.files
|
||||
@@ -327,6 +404,11 @@ Task(subagent_type="ui-design-agent",
|
||||
* dom_structure with semantic HTML5
|
||||
* css_layout_rules using var() placeholders
|
||||
* Add \"description\" field explaining component purpose and classification rationale
|
||||
* **Add \"usage_guide\" field for universal components** (see ui-design-agent.md schema):
|
||||
- common_sizes: Extract size variants (small/medium/large) from code
|
||||
- variant_recommendations: Document when to use each variant (primary/secondary/etc)
|
||||
- usage_context: List typical usage scenarios from actual implementation
|
||||
- accessibility_tips: Extract ARIA patterns and a11y notes from code
|
||||
|
||||
**Code Snippet Recording**:
|
||||
- Record actual layout/component code in `extraction_metadata.code_snippets`
|
||||
@@ -345,6 +427,12 @@ Task(subagent_type="ui-design-agent",
|
||||
* Specialized: Feature-specific or domain-specific (checkout form, dashboard widget)
|
||||
- ✅ Record complete code snippets in extraction_metadata.code_snippets (complete components/structures)
|
||||
- ✅ **Document classification rationale** in component description
|
||||
- ✅ **Generate usage_guide for universal components** (REQUIRED):
|
||||
* Analyze code to extract size variants (scan for size-related classes/props)
|
||||
* Document variant usage from code comments and implementation patterns
|
||||
* List usage contexts from component instances in codebase
|
||||
* Extract accessibility patterns from ARIA attributes and a11y comments
|
||||
* If insufficient data, populate with minimal valid structure and note in completeness
|
||||
- ❌ NO external research or web searches (code-only extraction)
|
||||
")
|
||||
```
|
||||
|
||||
@@ -29,16 +29,6 @@ Converts design run extraction results into shareable reference package with:
|
||||
--output-dir <path> Output directory (default: .workflow/reference_style)
|
||||
```
|
||||
|
||||
### Usage Examples
|
||||
|
||||
```bash
|
||||
# Basic usage
|
||||
/workflow:ui-design:reference-page-generator --design-run .workflow/WFS-123/design-run-456 --package-name main-app-style-v1
|
||||
|
||||
# Custom output directory
|
||||
/workflow:ui-design:reference-page-generator --design-run .workflow/WFS-123/design-run-456 --package-name main-app-style-v1 --output-dir ./style-references
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Execution Process
|
||||
@@ -210,10 +200,18 @@ Task(ui-design-agent): `
|
||||
- Display typography scale (font sizes, weights)
|
||||
- Show typography combinations if available
|
||||
- Include font family examples
|
||||
- **Display usage recommendations** (from design-tokens.json _metadata.usage_recommendations.typography):
|
||||
* Common sizes table (small_text, body_text, heading)
|
||||
* Common combinations with use cases
|
||||
|
||||
### Section 3: Components
|
||||
- Render all components from layout-templates.json (use layout_templates field)
|
||||
- **Universal Components**: Display reusable multi-component showcases (buttons, inputs, cards, etc.)
|
||||
* **Display usage_guide** (from layout-templates.json):
|
||||
- Common sizes table with dimensions and use cases
|
||||
- Variant recommendations (when to use primary/secondary/etc)
|
||||
- Usage context list (typical scenarios)
|
||||
- Accessibility tips checklist
|
||||
- **Specialized Components**: Display module-specific components from code (feature-specific layouts, custom widgets)
|
||||
- Display all variants side-by-side
|
||||
- Show DOM structure with proper styling
|
||||
@@ -224,6 +222,9 @@ Task(ui-design-agent): `
|
||||
- Visual spacing scale
|
||||
- Border radius examples
|
||||
- Shadow depth examples
|
||||
- **Display spacing recommendations** (from design-tokens.json _metadata.usage_recommendations.spacing):
|
||||
* Size guide table (tight/normal/loose categories)
|
||||
* Common patterns with use cases and pixel values
|
||||
|
||||
### Section 5: Animations (if available)
|
||||
- Animation duration examples
|
||||
@@ -259,6 +260,11 @@ Task(ui-design-agent): `
|
||||
- ✅ Display component DOM structures with proper styling
|
||||
- ✅ Include usage code snippets
|
||||
- ✅ Label each component type clearly (Universal / Specialized)
|
||||
- ✅ **Display usage recommendations** when available:
|
||||
- Typography: common_sizes, common_combinations (from _metadata.usage_recommendations)
|
||||
- Components: usage_guide for universal components (from layout-templates)
|
||||
- Spacing: size_guide, common_patterns (from _metadata.usage_recommendations)
|
||||
- ✅ Gracefully handle missing usage data (display sections only if data exists)
|
||||
- ✅ Use Write() to save both files:
|
||||
- ${package_dir}/preview.html
|
||||
- ${package_dir}/preview.css
|
||||
|
||||
Reference in New Issue
Block a user