mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-08 02:14:08 +08:00
Compare commits
28 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
fe0d30256c | ||
|
|
1c416b538d | ||
|
|
81362c14de | ||
|
|
fa6257ecae | ||
|
|
ccb4490ed4 | ||
|
|
58206f1996 | ||
|
|
564bcb72ea | ||
|
|
965a80b54e | ||
|
|
8f55bf2ece | ||
|
|
a721c50ba3 | ||
|
|
4a5c8490b1 | ||
|
|
2f0ca988f4 | ||
|
|
a45f5e9dc2 | ||
|
|
b8dc3018d4 | ||
|
|
9d4c9ef212 | ||
|
|
d7ffd6ee32 | ||
|
|
02ee426af0 | ||
|
|
e76e5bbf5c | ||
|
|
763c51cb28 | ||
|
|
c7542d95c8 | ||
|
|
02bf6e296c | ||
|
|
f839a3afb8 | ||
|
|
79714edc9a | ||
|
|
f9c33bd0ba | ||
|
|
e4a29c0b2e | ||
|
|
ca18043b14 | ||
|
|
871a02c1f8 | ||
|
|
3747a7b083 |
@@ -162,15 +162,15 @@ RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt)
|
||||
|
||||
**Gemini/Qwen (Write)**:
|
||||
```bash
|
||||
cd {dir} && gemini -p "..." -m gemini-2.5-flash --approval-mode yolo
|
||||
cd {dir} && gemini -p "..." --approval-mode yolo
|
||||
```
|
||||
|
||||
**Codex (Auto)**:
|
||||
```bash
|
||||
codex -C {dir} --full-auto exec "..." -m gpt-5 --skip-git-repo-check -s danger-full-access
|
||||
codex -C {dir} --full-auto exec "..." --skip-git-repo-check -s danger-full-access
|
||||
|
||||
# Resume: Add 'resume --last' after prompt
|
||||
codex --full-auto exec "..." resume --last -m gpt-5 --skip-git-repo-check -s danger-full-access
|
||||
codex --full-auto exec "..." resume --last --skip-git-repo-check -s danger-full-access
|
||||
```
|
||||
|
||||
**Cross-Directory** (Gemini/Qwen):
|
||||
|
||||
@@ -22,7 +22,7 @@ description: |
|
||||
- Progressive disclosure: Quick overview → detailed analysis → dependency deep-dive
|
||||
- Context-aware filtering based on task requirements
|
||||
|
||||
color: blue
|
||||
color: yellow
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
@@ -136,7 +136,7 @@ RULES: $(cat ~/.claude/workflows/cli-templates/prompts/{template}) |
|
||||
- Consider previous iteration failures
|
||||
- Validate fix doesn't introduce new vulnerabilities
|
||||
- analysis=READ-ONLY
|
||||
" -m {model} {timeout_flag}
|
||||
" {timeout_flag}
|
||||
```
|
||||
|
||||
**Layer-Specific Guidance Injection**:
|
||||
|
||||
@@ -1,37 +1,22 @@
|
||||
---
|
||||
name: enhance-prompt
|
||||
description: Enhanced prompt transformation using session memory and codebase analysis with --enhance flag detection
|
||||
description: Enhanced prompt transformation using session memory and intent analysis with --enhance flag detection
|
||||
argument-hint: "user input to enhance"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Systematically enhances user prompts by combining session memory context with codebase patterns, translating ambiguous requests into actionable specifications.
|
||||
Systematically enhances user prompts by leveraging session memory context and intent analysis, translating ambiguous requests into actionable specifications.
|
||||
|
||||
## Core Protocol
|
||||
|
||||
**Enhancement Pipeline:**
|
||||
`Intent Translation` → `Context Integration` → `Gemini Analysis (if needed)` → `Structured Output`
|
||||
`Intent Translation` → `Context Integration` → `Structured Output`
|
||||
|
||||
**Context Sources:**
|
||||
- Session memory (conversation history, previous analysis)
|
||||
- Codebase patterns (via Gemini when triggered)
|
||||
- Implicit technical requirements
|
||||
|
||||
## Gemini Trigger Logic
|
||||
|
||||
```pseudo
|
||||
FUNCTION should_use_gemini(user_prompt):
|
||||
critical_keywords = ["refactor", "migrate", "redesign", "auth", "payment", "security"]
|
||||
|
||||
RETURN (
|
||||
prompt_affects_multiple_modules(user_prompt, threshold=3) OR
|
||||
any_keyword_in_prompt(critical_keywords, user_prompt)
|
||||
)
|
||||
END
|
||||
```
|
||||
|
||||
**Gemini Integration:** ~/.claude/workflows/intelligent-tools-strategy.md
|
||||
- User intent patterns
|
||||
|
||||
## Enhancement Rules
|
||||
|
||||
@@ -47,22 +32,18 @@ END
|
||||
|
||||
### Context Integration Strategy
|
||||
|
||||
**Session Memory First:**
|
||||
**Session Memory:**
|
||||
- Reference recent conversation context
|
||||
- Reuse previously identified patterns
|
||||
- Build on established understanding
|
||||
|
||||
**Codebase Analysis (via Gemini):**
|
||||
- Only when complexity requires it
|
||||
- Focus on integration points
|
||||
- Identify existing patterns
|
||||
- Infer technical requirements from discussion
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
# User: "add login"
|
||||
# Session Memory: Previous auth discussion, JWT mentioned
|
||||
# Inferred: JWT-based auth, integrate with existing session management
|
||||
# Gemini (if multi-module): Analyze AuthService patterns, middleware structure
|
||||
# Action: Implement JWT authentication with session persistence
|
||||
```
|
||||
|
||||
## Output Structure
|
||||
@@ -76,7 +57,7 @@ ATTENTION: [Critical constraints]
|
||||
|
||||
### Output Examples
|
||||
|
||||
**Simple (no Gemini):**
|
||||
**Example 1:**
|
||||
```bash
|
||||
# Input: "fix login button"
|
||||
INTENT: Debug non-functional login button
|
||||
@@ -85,28 +66,28 @@ ACTION: Check event binding → verify state updates → test auth flow
|
||||
ATTENTION: Preserve existing OAuth integration
|
||||
```
|
||||
|
||||
**Complex (with Gemini):**
|
||||
**Example 2:**
|
||||
```bash
|
||||
# Input: "refactor payment code"
|
||||
INTENT: Restructure payment module for maintainability
|
||||
CONTEXT: Session memory - PCI compliance requirements
|
||||
Gemini - PaymentService → StripeAdapter pattern identified
|
||||
ACTION: Extract reusable validators → isolate payment gateway logic
|
||||
CONTEXT: Session memory - PCI compliance requirements, Stripe integration patterns
|
||||
ACTION: Extract reusable validators → isolate payment gateway logic → maintain adapter pattern
|
||||
ATTENTION: Zero behavior change, maintain PCI compliance, full test coverage
|
||||
```
|
||||
|
||||
## Automatic Triggers
|
||||
## Enhancement Triggers
|
||||
|
||||
- Ambiguous language: "fix", "improve", "clean up"
|
||||
- Multi-module impact (>3 modules)
|
||||
- Vague requests requiring clarification
|
||||
- Complex technical requirements
|
||||
- Architecture changes
|
||||
- Critical systems: auth, payment, security
|
||||
- Complex refactoring
|
||||
- Multi-step refactoring
|
||||
|
||||
## Key Principles
|
||||
|
||||
1. **Memory First**: Leverage session context before analysis
|
||||
2. **Minimal Gemini**: Only when complexity demands it
|
||||
3. **Context Reuse**: Build on previous understanding
|
||||
4. **Clear Output**: Structured, actionable specifications
|
||||
1. **Session Memory First**: Leverage conversation context and established understanding
|
||||
2. **Context Reuse**: Build on previous discussions and decisions
|
||||
3. **Clear Output**: Structured, actionable specifications
|
||||
4. **Intent Clarification**: Transform vague requests into specific technical goals
|
||||
5. **Avoid Duplication**: Reference existing context, don't repeat
|
||||
@@ -21,12 +21,14 @@ auto-continue: true
|
||||
**Key Features**:
|
||||
- Extracts primary design references (colors, typography, spacing, etc.)
|
||||
- Provides dynamic adjustment guidelines for design tokens
|
||||
- Includes prerequisites and tooling requirements (browsers, PostCSS, dark mode)
|
||||
- Progressive loading structure for efficient token usage
|
||||
- Complete implementation examples with React components
|
||||
- Interactive preview showcase
|
||||
|
||||
---
|
||||
|
||||
## Usage
|
||||
## Quick Reference
|
||||
|
||||
### Command Syntax
|
||||
|
||||
@@ -51,20 +53,77 @@ package-name Style reference package name (required)
|
||||
/memory:style-skill-memory
|
||||
```
|
||||
|
||||
### Key Variables
|
||||
|
||||
**Input Variables**:
|
||||
- `PACKAGE_NAME`: Style reference package name
|
||||
- `PACKAGE_DIR`: `.workflow/reference_style/${package_name}`
|
||||
- `SKILL_DIR`: `.claude/skills/style-${package_name}`
|
||||
- `REGENERATE`: `true` if --regenerate flag, `false` otherwise
|
||||
|
||||
**Data Sources** (Phase 2):
|
||||
- `DESIGN_TOKENS_DATA`: Complete design-tokens.json content (from Read)
|
||||
- `LAYOUT_TEMPLATES_DATA`: Complete layout-templates.json content (from Read)
|
||||
- `ANIMATION_TOKENS_DATA`: Complete animation-tokens.json content (from Read, if exists)
|
||||
|
||||
**Metadata** (Phase 2):
|
||||
- `COMPONENT_COUNT`: Total components
|
||||
- `UNIVERSAL_COUNT`: Universal components count
|
||||
- `SPECIALIZED_COUNT`: Specialized components count
|
||||
- `UNIVERSAL_COMPONENTS`: Universal component names (first 5)
|
||||
- `HAS_ANIMATIONS`: Whether animation-tokens.json exists
|
||||
|
||||
**Analysis Output** (`DESIGN_ANALYSIS` - Phase 2):
|
||||
- `has_colors`: Colors exist
|
||||
- `color_semantic`: Has semantic naming (primary/secondary/accent)
|
||||
- `uses_oklch`: Uses modern color spaces (oklch, lab, etc.)
|
||||
- `has_dark_mode`: Has separate light/dark mode color tokens
|
||||
- `spacing_pattern`: Pattern type ("linear", "geometric", "custom")
|
||||
- `spacing_scale`: Actual scale values (e.g., [4, 8, 16, 32, 64])
|
||||
- `has_typography`: Typography system exists
|
||||
- `typography_hierarchy`: Has size scale for hierarchy
|
||||
- `uses_calc`: Uses calc() expressions in token values
|
||||
- `has_radius`: Border radius exists
|
||||
- `radius_style`: Style characteristic ("sharp" <4px, "moderate" 4-8px, "rounded" >8px)
|
||||
- `has_shadows`: Shadow system exists
|
||||
- `shadow_pattern`: Elevation naming pattern
|
||||
- `has_animations`: Animation tokens exist
|
||||
- `animation_range`: Duration range (fast to slow)
|
||||
- `easing_variety`: Types of easing functions
|
||||
|
||||
### Common Errors
|
||||
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| Package not found | Invalid package name or doesn't exist | Run `/workflow:ui-design:codify-style` first |
|
||||
| SKILL already exists | SKILL.md already generated | Use `--regenerate` flag |
|
||||
| Missing layout-templates.json | Incomplete package | Verify package integrity, re-run codify-style |
|
||||
| Invalid JSON format | Corrupted package files | Regenerate package with codify-style |
|
||||
|
||||
---
|
||||
|
||||
## Execution Process
|
||||
|
||||
### Phase 1: Validate Package
|
||||
|
||||
**Purpose**: Check if style reference package exists
|
||||
|
||||
**TodoWrite** (First Action):
|
||||
```json
|
||||
[
|
||||
{"content": "Validate style reference package", "status": "in_progress", "activeForm": "Validating package"},
|
||||
{"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"}
|
||||
{
|
||||
"content": "Validate package exists and check SKILL status",
|
||||
"activeForm": "Validating package and SKILL status",
|
||||
"status": "in_progress"
|
||||
},
|
||||
{
|
||||
"content": "Read package data and analyze design system",
|
||||
"activeForm": "Reading package data and analyzing design system",
|
||||
"status": "pending"
|
||||
},
|
||||
{
|
||||
"content": "Generate SKILL.md with design principles and token values",
|
||||
"activeForm": "Generating SKILL.md with design principles and token values",
|
||||
"status": "pending"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
@@ -75,8 +134,6 @@ package-name Style reference package name (required)
|
||||
bash(echo "${package_name}" || basename "$(pwd)" | sed 's/^style-//')
|
||||
```
|
||||
|
||||
Store result as `package_name`
|
||||
|
||||
**Step 2: Validate Package Exists**
|
||||
|
||||
```bash
|
||||
@@ -113,152 +170,90 @@ if (regenerate_flag && skill_exists) {
|
||||
}
|
||||
```
|
||||
|
||||
**Summary Variables**:
|
||||
- `PACKAGE_NAME`: Style reference package name
|
||||
- `PACKAGE_DIR`: `.workflow/reference_style/${package_name}`
|
||||
- `SKILL_DIR`: `.claude/skills/style-${package_name}`
|
||||
- `REGENERATE`: `true` if --regenerate flag, `false` otherwise
|
||||
|
||||
**TodoWrite Update**:
|
||||
```json
|
||||
[
|
||||
{"content": "Validate style reference package", "status": "completed", "activeForm": "Validating package"},
|
||||
{"content": "Read package data and extract design references", "status": "in_progress", "activeForm": "Reading package data"}
|
||||
]
|
||||
```
|
||||
**TodoWrite Update**: Mark "Validate" as completed, "Read package data" as in_progress
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Read Package Data & Extract Design References
|
||||
### Phase 2: Read Package Data & Analyze Design System
|
||||
|
||||
**Purpose**: Extract package information and primary design references for SKILL description generation
|
||||
|
||||
**Step 1: Count Components**
|
||||
**Step 1: Read All JSON Files**
|
||||
|
||||
```bash
|
||||
bash(jq '.layout_templates | length' .workflow/reference_style/${package_name}/layout-templates.json 2>/dev/null || echo 0)
|
||||
```
|
||||
# Read layout templates
|
||||
Read(file_path=".workflow/reference_style/${package_name}/layout-templates.json")
|
||||
|
||||
Store result as `component_count`
|
||||
|
||||
**Step 2: Extract Component Types and Classification**
|
||||
|
||||
```bash
|
||||
# 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 design tokens
|
||||
Read(file_path=".workflow/reference_style/${package_name}/design-tokens.json")
|
||||
|
||||
# Read animation tokens (if exists)
|
||||
bash(test -f .workflow/reference_style/${package_name}/animation-tokens.json && echo "exists" || echo "missing")
|
||||
Read(file_path=".workflow/reference_style/${package_name}/animation-tokens.json") # if exists
|
||||
```
|
||||
|
||||
**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)**
|
||||
**Step 2: Extract Metadata for Description**
|
||||
|
||||
```bash
|
||||
# Check if animation tokens exist
|
||||
bash(test -f .workflow/reference_style/${package_name}/animation-tokens.json && echo "available" || echo "not_available")
|
||||
# Count components and classify by type
|
||||
bash(jq '.layout_templates | length' layout-templates.json)
|
||||
bash(jq '[.layout_templates[] | select(.component_type == "universal")] | length' layout-templates.json)
|
||||
bash(jq '[.layout_templates[] | select(.component_type == "specialized")] | length' layout-templates.json)
|
||||
bash(jq -r '.layout_templates | to_entries[] | select(.value.component_type == "universal") | .key' layout-templates.json | head -5)
|
||||
```
|
||||
|
||||
If available, extract:
|
||||
```bash
|
||||
Read(file_path=".workflow/reference_style/${package_name}/animation-tokens.json")
|
||||
Store results in metadata variables (see [Key Variables](#key-variables))
|
||||
|
||||
# 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)
|
||||
```
|
||||
**Step 3: Analyze Design System for Dynamic Principles**
|
||||
|
||||
Store as:
|
||||
- `ANIMATION_DURATIONS`: Animation duration tokens
|
||||
- `EASING_FUNCTIONS`: Easing function tokens
|
||||
|
||||
**Step 5: Count Files**
|
||||
Analyze design-tokens.json to extract characteristics and patterns:
|
||||
|
||||
```bash
|
||||
bash(cd .workflow/reference_style/${package_name} && ls -1 *.json *.html *.css 2>/dev/null | wc -l)
|
||||
# Color system characteristics
|
||||
bash(jq '.colors | keys' design-tokens.json)
|
||||
bash(jq '.colors | to_entries[0:2] | map(.value)' design-tokens.json)
|
||||
# Check for modern color spaces
|
||||
bash(jq '.colors | to_entries[] | .value | test("oklch|lab|lch")' design-tokens.json)
|
||||
# Check for dark mode variants
|
||||
bash(jq '.colors | keys | map(select(contains("dark") or contains("light")))' design-tokens.json)
|
||||
# → Store: has_colors, color_semantic, uses_oklch, has_dark_mode
|
||||
|
||||
# Spacing pattern detection
|
||||
bash(jq '.spacing | to_entries | map(.value) | map(gsub("[^0-9.]"; "") | tonumber)' design-tokens.json)
|
||||
# Analyze pattern: linear (4-8-12-16) vs geometric (4-8-16-32) vs custom
|
||||
# → Store: spacing_pattern, spacing_scale
|
||||
|
||||
# Typography characteristics
|
||||
bash(jq '.typography | keys | map(select(contains("family") or contains("weight")))' design-tokens.json)
|
||||
bash(jq '.typography | to_entries | map(select(.key | contains("size"))) | .[].value' design-tokens.json)
|
||||
# Check for calc() usage
|
||||
bash(jq '. | tostring | test("calc\\(")' design-tokens.json)
|
||||
# → Store: has_typography, typography_hierarchy, uses_calc
|
||||
|
||||
# Border radius style
|
||||
bash(jq '.border_radius | to_entries | map(.value)' design-tokens.json)
|
||||
# Check range: small (sharp <4px) vs moderate (4-8px) vs large (rounded >8px)
|
||||
# → Store: has_radius, radius_style
|
||||
|
||||
# Shadow characteristics
|
||||
bash(jq '.shadows | keys' design-tokens.json)
|
||||
bash(jq '.shadows | to_entries[0].value' design-tokens.json)
|
||||
# → Store: has_shadows, shadow_pattern
|
||||
|
||||
# Animations (if available)
|
||||
bash(jq '.duration | to_entries | map(.value)' animation-tokens.json)
|
||||
bash(jq '.easing | keys' animation-tokens.json)
|
||||
# → Store: has_animations, animation_range, easing_variety
|
||||
```
|
||||
|
||||
Store result as `file_count`
|
||||
Store analysis results in `DESIGN_ANALYSIS` (see [Key Variables](#key-variables))
|
||||
|
||||
**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
|
||||
- `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)
|
||||
**Note**: Analysis focuses on characteristics and patterns, not counts. Include technical feature detection (oklch, calc, dark mode) for Prerequisites section.
|
||||
|
||||
**TodoWrite Update**:
|
||||
```json
|
||||
[
|
||||
{"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"}
|
||||
]
|
||||
```
|
||||
**TodoWrite Update**: Mark "Read package data" as completed, "Generate SKILL.md" as in_progress
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Generate SKILL.md
|
||||
|
||||
**Purpose**: Create SKILL memory index with progressive loading structure and design references
|
||||
|
||||
**Step 1: Create SKILL Directory**
|
||||
|
||||
```bash
|
||||
@@ -272,336 +267,57 @@ bash(mkdir -p .claude/skills/style-${package_name})
|
||||
{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**:
|
||||
- **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**: reusable UI components, design tokens, layout patterns, visual consistency
|
||||
- **Action Coverage**: working with, analyzing, implementing
|
||||
**Step 3: Load and Process SKILL.md Template**
|
||||
|
||||
**Example**:
|
||||
```
|
||||
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 to generate SKILL.md with the following complete content:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: style-{package_name}
|
||||
description: {intelligent description from Step 2}
|
||||
---
|
||||
|
||||
# {Package Name} Style SKILL Package
|
||||
|
||||
## Documentation: `../../../.workflow/reference_style/{package_name}/`
|
||||
|
||||
## Package Overview
|
||||
|
||||
**Project-independent style reference package** extracted from codebase with reusable design patterns, tokens, and interactive preview.
|
||||
|
||||
**Package Details**:
|
||||
- Package: {package_name}
|
||||
- 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}
|
||||
- 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: Design Tokens (~5K tokens)
|
||||
|
||||
Essential design token system for consistent styling.
|
||||
|
||||
**Files**:
|
||||
- [Design Tokens](../../../.workflow/reference_style/{package_name}/design-tokens.json) - Colors, typography, spacing, shadows, borders
|
||||
|
||||
**Use when**: Quick token reference, applying consistent styles, color/typography queries
|
||||
|
||||
---
|
||||
|
||||
### Level 1: Universal Layout Templates (~12K tokens)
|
||||
|
||||
**Project-independent** component layout patterns for reusable UI elements.
|
||||
|
||||
**Files**:
|
||||
- Level 0 files
|
||||
- [Layout Templates](../../../.workflow/reference_style/{package_name}/layout-templates.json) - Component structures with HTML/CSS patterns
|
||||
|
||||
**⚠️ 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: Complete System (~20K tokens)
|
||||
|
||||
Full design system with animations and interactive preview.
|
||||
|
||||
**Files**:
|
||||
- All Level 1 files
|
||||
- [Animation Tokens](../../../.workflow/reference_style/{package_name}/animation-tokens.json) - Animation durations, easing, transitions _(if available)_
|
||||
- [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, animation development, complete design system understanding
|
||||
|
||||
---
|
||||
|
||||
## Interactive Preview
|
||||
|
||||
**Location**: `.workflow/reference_style/{package_name}/preview.html`
|
||||
|
||||
**View in Browser**:
|
||||
**⚠️ CRITICAL - Execute First**:
|
||||
```bash
|
||||
cd .workflow/reference_style/{package_name}
|
||||
python -m http.server 8080
|
||||
# Open http://localhost:8080/preview.html
|
||||
bash(cat ~/.claude/workflows/cli-templates/memory/style-skill-memory/skill-md-template.md)
|
||||
```
|
||||
|
||||
**Features**:
|
||||
- Color palette swatches with values
|
||||
- Typography scale and combinations
|
||||
- All components with variants and states
|
||||
- Spacing, radius, shadow visual examples
|
||||
- Interactive state demonstrations
|
||||
- Usage code snippets
|
||||
**Template Processing**:
|
||||
1. **Replace variables**: Substitute all `{variable}` placeholders with actual values from Phase 2
|
||||
2. **Generate dynamic sections**:
|
||||
- **Prerequisites & Tooling**: Generate based on `DESIGN_ANALYSIS` technical features (oklch, calc, dark mode)
|
||||
- **Design Principles**: Generate based on `DESIGN_ANALYSIS` characteristics
|
||||
- **Complete Implementation Example**: Include React component example with token adaptation
|
||||
- **Design Token Values**: Iterate `DESIGN_TOKENS_DATA`, `ANIMATION_TOKENS_DATA` and display all key-value pairs with DEFAULT annotations
|
||||
3. **Write to file**: Use Write tool to save to `.claude/skills/style-{package_name}/SKILL.md`
|
||||
|
||||
---
|
||||
**Variable Replacement Map**:
|
||||
- `{package_name}` → PACKAGE_NAME
|
||||
- `{intelligent_description}` → Generated description from Step 2
|
||||
- `{component_count}` → COMPONENT_COUNT
|
||||
- `{universal_count}` → UNIVERSAL_COUNT
|
||||
- `{specialized_count}` → SPECIALIZED_COUNT
|
||||
- `{universal_components_list}` → UNIVERSAL_COMPONENTS (comma-separated)
|
||||
- `{has_animations}` → HAS_ANIMATIONS
|
||||
|
||||
## Usage Guidelines
|
||||
**Dynamic Content Generation**:
|
||||
|
||||
### Loading Levels
|
||||
See template file for complete structure. Key dynamic sections:
|
||||
|
||||
**Level 0** (5K): Design tokens only
|
||||
```
|
||||
Load Level 0 for design token reference
|
||||
```
|
||||
1. **Prerequisites & Tooling** (based on DESIGN_ANALYSIS technical features):
|
||||
- IF uses_oklch → Include PostCSS plugin requirement (`postcss-oklab-function`)
|
||||
- IF uses_calc → Include preprocessor requirement for calc() expressions
|
||||
- IF has_dark_mode → Include dark mode implementation mechanism (class or media query)
|
||||
- ALWAYS include browser support, jq installation, and local server setup
|
||||
|
||||
**Level 1** (12K): Tokens + layout templates
|
||||
```
|
||||
Load Level 1 for layout templates and design tokens
|
||||
```
|
||||
2. **Design Principles** (based on DESIGN_ANALYSIS):
|
||||
- IF has_colors → Include "Color System" principle with semantic pattern
|
||||
- IF spacing_pattern detected → Include "Spatial Rhythm" with unified scale description (actual token values)
|
||||
- IF has_typography_hierarchy → Include "Typographic System" with scale examples
|
||||
- IF has_radius → Include "Shape Language" with style characteristic
|
||||
- IF has_shadows → Include "Depth & Elevation" with elevation pattern
|
||||
- IF has_animations → Include "Motion & Timing" with duration range
|
||||
- ALWAYS include "Accessibility First" principle
|
||||
|
||||
**Level 2** (20K): Complete system with animations and preview
|
||||
```
|
||||
Load Level 2 for complete design system with preview reference
|
||||
```
|
||||
|
||||
### Common Use Cases
|
||||
|
||||
**Implementing UI Components**:
|
||||
- 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 0 for design tokens
|
||||
- Use design-tokens.json for colors, typography, spacing
|
||||
- Check preview.html for visual reference (universal components only)
|
||||
|
||||
**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 (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}/
|
||||
├── 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Regeneration
|
||||
|
||||
To update this SKILL memory after package changes:
|
||||
|
||||
```bash
|
||||
/memory:style-skill-memory {package_name} --regenerate
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Commands
|
||||
|
||||
**Generate Package**:
|
||||
```bash
|
||||
/workflow:ui-design:codify-style --source ./src --package-name {package_name}
|
||||
```
|
||||
|
||||
**Update Package**:
|
||||
Re-run codify-style with same package name to update extraction.
|
||||
```
|
||||
3. **Design Token Values** (iterate from read data):
|
||||
- Colors: Iterate `DESIGN_TOKENS_DATA.colors`
|
||||
- Typography: Iterate `DESIGN_TOKENS_DATA.typography`
|
||||
- Spacing: Iterate `DESIGN_TOKENS_DATA.spacing`
|
||||
- Border Radius: Iterate `DESIGN_TOKENS_DATA.border_radius` with calc() explanations
|
||||
- Shadows: Iterate `DESIGN_TOKENS_DATA.shadows` with DEFAULT token annotations
|
||||
- Animations (if available): Iterate `ANIMATION_TOKENS_DATA.duration` and `ANIMATION_TOKENS_DATA.easing`
|
||||
|
||||
**Step 4: Verify SKILL.md Created**
|
||||
|
||||
@@ -609,115 +325,27 @@ Re-run codify-style with same package name to update extraction.
|
||||
bash(test -f .claude/skills/style-${package_name}/SKILL.md && echo "success" || echo "failed")
|
||||
```
|
||||
|
||||
**TodoWrite Update**:
|
||||
```json
|
||||
[
|
||||
{"content": "Validate style reference package", "status": "completed", "activeForm": "Validating package"},
|
||||
{"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"}
|
||||
]
|
||||
```
|
||||
|
||||
**Final Action**: Report completion summary to user
|
||||
**TodoWrite Update**: Mark all todos as completed
|
||||
|
||||
---
|
||||
|
||||
## Completion Message
|
||||
### Completion Message
|
||||
|
||||
Display extracted primary design references to user:
|
||||
Display a simple completion message with key information:
|
||||
|
||||
```
|
||||
✅ SKILL memory generated successfully!
|
||||
✅ SKILL memory generated for style package: {package_name}
|
||||
|
||||
Package: {package_name}
|
||||
SKILL Location: .claude/skills/style-{package_name}/SKILL.md
|
||||
📁 Location: .claude/skills/style-{package_name}/SKILL.md
|
||||
|
||||
📦 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}
|
||||
- Animation Tokens: {has_animations ? "✓ Available" : "Not available"}
|
||||
📊 Package Summary:
|
||||
- {component_count} components ({universal_count} universal, {specialized_count} specialized)
|
||||
- Design tokens: colors, typography, spacing, shadows{animations_note}
|
||||
|
||||
🎨 Primary Design References Extracted:
|
||||
{IF PRIMARY_COLORS exists:
|
||||
Colors:
|
||||
{show first 3 PRIMARY_COLORS with key: value}
|
||||
{if more than 3: + X more colors}
|
||||
}
|
||||
|
||||
{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
|
||||
|
||||
⚠️ 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 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
|
||||
💡 Usage: /memory:load-skill-memory style-{package_name} "your task description"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Common Errors
|
||||
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| 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 layout-templates.json | Incomplete package | Verify package integrity, re-run codify-style |
|
||||
| Invalid JSON format | Corrupted package files | Regenerate package with codify-style |
|
||||
Variables: `{package_name}`, `{component_count}`, `{universal_count}`, `{specialized_count}`, `{animations_note}` (", animations" if exists)
|
||||
|
||||
---
|
||||
|
||||
@@ -727,144 +355,42 @@ Open interactive showcase:
|
||||
|
||||
1. **Check Before Generate**: Verify package exists before attempting SKILL generation
|
||||
2. **Respect Existing SKILL**: Don't overwrite unless --regenerate flag provided
|
||||
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
|
||||
3. **Load Templates via cat**: Use `cat ~/.claude/workflows/cli-templates/memory/style-skill-memory/{template}` to load templates
|
||||
4. **Variable Substitution**: Replace all `{variable}` placeholders with actual values
|
||||
5. **Technical Feature Detection**: Analyze tokens for modern features (oklch, calc, dark mode) and generate appropriate Prerequisites section
|
||||
6. **Dynamic Content Generation**: Generate sections based on DESIGN_ANALYSIS characteristics
|
||||
7. **Unified Spacing Scale**: Use actual token values as primary scale reference, avoid contradictory pattern descriptions
|
||||
8. **Direct Iteration**: Iterate data structures (DESIGN_TOKENS_DATA, etc.) for token values
|
||||
9. **Annotate Special Tokens**: Add comments for DEFAULT tokens and calc() expressions
|
||||
10. **Embed jq Commands**: Include bash/jq commands in SKILL.md for dynamic loading
|
||||
11. **Progressive Loading**: Include all 3 levels (0-2) with specific jq commands
|
||||
12. **Complete Examples**: Include end-to-end implementation examples (React components)
|
||||
13. **Intelligent Description**: Extract component count and key features from metadata
|
||||
14. **Emphasize Flexibility**: Strongly warn against rigid copying - values are references for creative adaptation
|
||||
|
||||
### SKILL Description Format
|
||||
### Template Files Location
|
||||
|
||||
**Template**:
|
||||
```
|
||||
{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
|
||||
- Universal layout template count (emphasize reusability)
|
||||
- Project independence statement
|
||||
- Specialized component exclusion notice
|
||||
- Location (full path)
|
||||
- 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** (~5K tokens):
|
||||
- design-tokens.json
|
||||
|
||||
**Level 1** (~12K tokens):
|
||||
- Level 0 files
|
||||
- layout-templates.json
|
||||
|
||||
**Level 2** (~20K tokens):
|
||||
- Level 1 files
|
||||
- animation-tokens.json (if exists)
|
||||
- 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 with component type filtering
|
||||
- **Practical Usage Guidelines**: Context-specific adjustment strategies and component selection criteria
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
style-skill-memory
|
||||
├─ 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
|
||||
Phase 1: Validate
|
||||
├─ Parse package_name
|
||||
├─ Check PACKAGE_DIR exists
|
||||
└─ Check SKILL_DIR exists (skip if exists and no --regenerate)
|
||||
|
||||
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
|
||||
Phase 2: Read & Analyze
|
||||
├─ Read design-tokens.json → DESIGN_TOKENS_DATA
|
||||
├─ Read layout-templates.json → LAYOUT_TEMPLATES_DATA
|
||||
├─ Read animation-tokens.json → ANIMATION_TOKENS_DATA (if exists)
|
||||
├─ Extract Metadata → COMPONENT_COUNT, UNIVERSAL_COUNT, etc.
|
||||
└─ Analyze Design System → DESIGN_ANALYSIS (characteristics)
|
||||
|
||||
Extracted data → SKILL.md generation → Primary Design References section
|
||||
→ Component Classification section
|
||||
→ Dynamic Adjustment Guidelines
|
||||
→ Project Independence warnings
|
||||
→ Completion message display
|
||||
Phase 3: Generate
|
||||
├─ Create SKILL directory
|
||||
├─ Generate intelligent description
|
||||
├─ Load SKILL.md template (cat command)
|
||||
├─ Replace variables and generate dynamic content
|
||||
├─ Write SKILL.md
|
||||
├─ Verify creation
|
||||
├─ Load completion message template (cat command)
|
||||
└─ Display completion message
|
||||
```
|
||||
|
||||
@@ -7,7 +7,7 @@ argument-hint: "[--resume-session=\"session-id\"]"
|
||||
# Workflow Execute Command
|
||||
|
||||
## Overview
|
||||
Orchestrates autonomous workflow execution through systematic task discovery, agent coordination, and progress tracking. **Executes entire workflow without user interruption**, providing complete context to agents and ensuring proper flow control execution with comprehensive TodoWrite tracking.
|
||||
Orchestrates autonomous workflow execution through systematic task discovery, agent coordination, and progress tracking. **Executes entire workflow without user interruption** (except initial session selection if multiple active sessions exist), providing complete context to agents and ensuring proper flow control execution with comprehensive TodoWrite tracking.
|
||||
|
||||
**Resume Mode**: When called with `--resume-session` flag, skips discovery phase and directly enters TodoWrite generation and agent execution for the specified session.
|
||||
|
||||
@@ -22,83 +22,72 @@ Orchestrates autonomous workflow execution through systematic task discovery, ag
|
||||
| **Memory** | All tasks | 1-2 tasks | **90% less** |
|
||||
| **Scalability** | 10-20 tasks | 100+ tasks | **5-10x** |
|
||||
|
||||
**Loading Strategy**:
|
||||
- **TODO_LIST.md**: Read in Phase 2 (task metadata, status, dependencies)
|
||||
- **IMPL_PLAN.md**: Read existence in Phase 2, parse execution strategy when needed
|
||||
- **Task JSONs**: Complete lazy loading (read only during execution)
|
||||
|
||||
## Core Rules
|
||||
**Complete entire workflow autonomously without user interruption, using TodoWrite for comprehensive progress tracking.**
|
||||
**Execute all discovered pending tasks sequentially until workflow completion or blocking dependency.**
|
||||
**Execute all discovered pending tasks until workflow completion or blocking dependency.**
|
||||
**Auto-complete session when all tasks finished: Call `/workflow:session:complete` upon workflow completion.**
|
||||
|
||||
## Core Responsibilities
|
||||
- **Session Discovery**: Identify and select active workflow sessions
|
||||
- **Task Dependency Resolution**: Analyze task relationships and execution order
|
||||
- **Execution Strategy Parsing**: Extract execution model from IMPL_PLAN.md
|
||||
- **TodoWrite Progress Tracking**: Maintain real-time execution status throughout entire workflow
|
||||
- **Agent Orchestration**: Coordinate specialized agents with complete context
|
||||
- **Flow Control Execution**: Execute pre-analysis steps and context accumulation
|
||||
- **Status Synchronization**: Update task JSON files and workflow state
|
||||
- **Autonomous Completion**: Continue execution until all tasks complete or reach blocking state
|
||||
- **Session Auto-Complete**: Call `/workflow:session:complete` when all workflow tasks finished
|
||||
|
||||
## Execution Philosophy
|
||||
- **IMPL_PLAN-driven**: Follow execution strategy from IMPL_PLAN.md Section 4
|
||||
- **Discovery-first**: Auto-discover existing plans and tasks
|
||||
- **Status-aware**: Execute only ready tasks with resolved dependencies
|
||||
- **Context-rich**: Provide complete task JSON and accumulated context to agents
|
||||
- **Progress tracking**: **Continuous TodoWrite updates throughout entire workflow execution**
|
||||
- **Flow control**: Sequential step execution with variable passing
|
||||
- **Autonomous completion**: **Execute all tasks without user interruption until workflow complete**
|
||||
|
||||
## Flow Control Execution
|
||||
**[FLOW_CONTROL]** marker indicates task JSON contains `flow_control.pre_analysis` steps for context preparation.
|
||||
|
||||
### Orchestrator Responsibility
|
||||
- Pass complete task JSON to agent (including `flow_control` block)
|
||||
- Provide session paths for artifact access
|
||||
- Monitor agent completion
|
||||
|
||||
### Agent Responsibility
|
||||
- Parse `flow_control.pre_analysis` array from JSON
|
||||
- Execute steps sequentially with variable substitution
|
||||
- Accumulate context from artifacts and dependencies
|
||||
- Follow error handling per `step.on_error`
|
||||
- Complete implementation using accumulated context
|
||||
|
||||
**Orchestrator does NOT execute flow control steps - Agent interprets and executes them from JSON.**
|
||||
- **Progress tracking**: Continuous TodoWrite updates throughout entire workflow execution
|
||||
- **Autonomous completion**: Execute all tasks without user interruption until workflow complete
|
||||
|
||||
## Execution Lifecycle
|
||||
|
||||
### Resume Mode Detection
|
||||
**Special Flag Processing**: When `--resume-session="session-id"` is provided:
|
||||
1. **Skip Discovery Phase**: Use provided session ID directly
|
||||
2. **Load Specified Session**: Read session state from `.workflow/{session-id}/`
|
||||
3. **Direct TodoWrite Generation**: Skip to Phase 3 (Planning) immediately
|
||||
4. **Accelerated Execution**: Enter agent coordination without validation delays
|
||||
### Phase 1: Discovery
|
||||
**Applies to**: Normal mode only (skipped in resume mode)
|
||||
|
||||
### Phase 1: Discovery (Normal Mode Only)
|
||||
**Process**:
|
||||
1. **Check Active Sessions**: Find `.workflow/.active-*` markers
|
||||
2. **Select Session**: If multiple found, prompt user selection
|
||||
3. **Load Session Metadata**: Read `workflow-session.json` ONLY (minimal context)
|
||||
4. **DO NOT read task JSONs yet** - defer until execution phase
|
||||
|
||||
**Note**: In resume mode, this phase is completely skipped.
|
||||
**Resume Mode**: This phase is completely skipped when `--resume-session="session-id"` flag is provided.
|
||||
|
||||
### Phase 2: Planning Document Analysis
|
||||
**Applies to**: Normal mode only (skipped in resume mode)
|
||||
|
||||
### Phase 2: Planning Document Analysis (Normal Mode Only)
|
||||
**Optimized to avoid reading all task JSONs upfront**
|
||||
|
||||
1. **Read IMPL_PLAN.md**: Understand overall strategy, task breakdown summary, dependencies
|
||||
**Process**:
|
||||
1. **Read IMPL_PLAN.md**: Check existence, understand overall strategy
|
||||
2. **Read TODO_LIST.md**: Get current task statuses and execution progress
|
||||
3. **Extract Task Metadata**: Parse task IDs, titles, and dependency relationships from TODO_LIST.md
|
||||
4. **Build Execution Queue**: Determine ready tasks based on TODO_LIST.md status and dependencies
|
||||
|
||||
**Key Optimization**: Use IMPL_PLAN.md and TODO_LIST.md as primary sources instead of reading all task JSONs
|
||||
**Key Optimization**: Use IMPL_PLAN.md (existence check only) and TODO_LIST.md as primary sources instead of reading all task JSONs
|
||||
|
||||
**Note**: In resume mode, this phase is also skipped as session analysis was already completed by `/workflow:status`.
|
||||
**Resume Mode**: This phase is skipped when `--resume-session` flag is provided (session already known).
|
||||
|
||||
### Phase 3: TodoWrite Generation (Resume Mode Entry Point)
|
||||
**This is where resume mode directly enters after skipping Phases 1 & 2**
|
||||
### Phase 3: TodoWrite Generation
|
||||
**Applies to**: Both normal and resume modes (resume mode entry point)
|
||||
|
||||
**Process**:
|
||||
1. **Create TodoWrite List**: Generate task list from TODO_LIST.md (not from task JSONs)
|
||||
- Parse TODO_LIST.md to extract all tasks with current statuses
|
||||
- Identify first pending task with met dependencies
|
||||
- Generate comprehensive TodoWrite covering entire workflow
|
||||
2. **Mark Initial Status**: Set first ready task as `in_progress` in TodoWrite
|
||||
2. **Mark Initial Status**: Set first ready task(s) as `in_progress` in TodoWrite
|
||||
- **Sequential execution**: Mark ONE task as `in_progress`
|
||||
- **Parallel batch**: Mark ALL tasks in current batch as `in_progress`
|
||||
3. **Prepare Session Context**: Inject workflow paths for agent use (using provided session-id)
|
||||
4. **Validate Prerequisites**: Ensure IMPL_PLAN.md and TODO_LIST.md exist and are valid
|
||||
|
||||
@@ -108,18 +97,22 @@ Orchestrates autonomous workflow execution through systematic task discovery, ag
|
||||
- Generate TodoWrite from TODO_LIST.md state
|
||||
- Proceed immediately to agent execution (Phase 4)
|
||||
|
||||
### Phase 4: Execution (Lazy Task Loading)
|
||||
**Key Optimization**: Read task JSON **only when needed** for execution
|
||||
### Phase 4: Execution Strategy Selection & Task Execution
|
||||
**Applies to**: Both normal and resume modes
|
||||
|
||||
1. **Identify Next Task**: From TodoWrite, get the next `in_progress` task ID
|
||||
2. **Load Task JSON on Demand**: Read `.task/{task-id}.json` for current task ONLY
|
||||
3. **Validate Task Structure**: Ensure all 5 required fields exist (id, title, status, meta, context, flow_control)
|
||||
4. **Pass Task with Flow Control**: Include complete task JSON with `pre_analysis` steps for agent execution
|
||||
5. **Launch Agent**: Invoke specialized agent with complete context including flow control steps
|
||||
6. **Monitor Progress**: Track agent execution and handle errors without user interruption
|
||||
7. **Collect Results**: Gather implementation results and outputs
|
||||
8. **Update TODO_LIST.md**: Mark current task as completed in TODO_LIST.md
|
||||
9. **Continue Workflow**: Identify next pending task from TODO_LIST.md and repeat from step 1
|
||||
**Step 4A: Parse Execution Strategy from IMPL_PLAN.md**
|
||||
|
||||
Read IMPL_PLAN.md Section 4 to extract:
|
||||
- **Execution Model**: Sequential | Parallel | Phased | TDD Cycles
|
||||
- **Parallelization Opportunities**: Which tasks can run in parallel
|
||||
- **Serialization Requirements**: Which tasks must run sequentially
|
||||
- **Critical Path**: Priority execution order
|
||||
|
||||
If IMPL_PLAN.md lacks execution strategy, use intelligent fallback (analyze task structure).
|
||||
|
||||
**Step 4B: Execute Tasks with Lazy Loading**
|
||||
|
||||
**Key Optimization**: Read task JSON **only when needed** for execution
|
||||
|
||||
**Execution Loop Pattern**:
|
||||
```
|
||||
@@ -132,6 +125,16 @@ while (TODO_LIST.md has pending tasks) {
|
||||
}
|
||||
```
|
||||
|
||||
**Execution Process per Task**:
|
||||
1. **Identify Next Task**: From TodoWrite, get the next `in_progress` task ID
|
||||
2. **Load Task JSON on Demand**: Read `.task/{task-id}.json` for current task ONLY
|
||||
3. **Validate Task Structure**: Ensure all 5 required fields exist (id, title, status, meta, context, flow_control)
|
||||
4. **Launch Agent**: Invoke specialized agent with complete context including flow control steps
|
||||
5. **Monitor Progress**: Track agent execution and handle errors without user interruption
|
||||
6. **Collect Results**: Gather implementation results and outputs
|
||||
7. **Update TODO_LIST.md**: Mark current task as completed in TODO_LIST.md
|
||||
8. **Continue Workflow**: Identify next pending task from TODO_LIST.md and repeat
|
||||
|
||||
**Benefits**:
|
||||
- Reduces initial context loading by ~90%
|
||||
- Only reads task JSON when actually executing
|
||||
@@ -139,6 +142,9 @@ while (TODO_LIST.md has pending tasks) {
|
||||
- Faster startup time for workflow execution
|
||||
|
||||
### Phase 5: Completion
|
||||
**Applies to**: Both normal and resume modes
|
||||
|
||||
**Process**:
|
||||
1. **Update Task Status**: Mark completed tasks in JSON files
|
||||
2. **Generate Summary**: Create task summary in `.summaries/`
|
||||
3. **Update TodoWrite**: Mark current task complete, advance to next
|
||||
@@ -146,34 +152,52 @@ while (TODO_LIST.md has pending tasks) {
|
||||
5. **Check Workflow Complete**: Verify all tasks are completed
|
||||
6. **Auto-Complete Session**: Call `/workflow:session:complete` when all tasks finished
|
||||
|
||||
## Task Discovery & Queue Building
|
||||
## Execution Strategy (IMPL_PLAN-Driven)
|
||||
|
||||
### Session Discovery Process (Normal Mode - Optimized)
|
||||
```
|
||||
├── Check for .active-* markers in .workflow/
|
||||
├── If multiple active sessions found → Prompt user to select
|
||||
├── Locate selected session's workflow folder
|
||||
├── Load session metadata: workflow-session.json (minimal context)
|
||||
├── Read IMPL_PLAN.md (strategy overview and task summary)
|
||||
├── Read TODO_LIST.md (current task statuses and dependencies)
|
||||
├── Parse TODO_LIST.md to extract task metadata (NO JSON loading)
|
||||
├── Build execution queue from TODO_LIST.md
|
||||
└── Generate TodoWrite from TODO_LIST.md state
|
||||
```
|
||||
### Strategy Priority
|
||||
|
||||
**Key Change**: Task JSONs are NOT loaded during discovery - they are loaded lazily during execution
|
||||
**IMPL_PLAN-Driven Execution (Recommended)**:
|
||||
1. **Read IMPL_PLAN.md execution strategy** (Section 4: Implementation Strategy)
|
||||
2. **Follow explicit guidance**:
|
||||
- Execution Model (Sequential/Parallel/Phased/TDD)
|
||||
- Parallelization Opportunities (which tasks can run in parallel)
|
||||
- Serialization Requirements (which tasks must run sequentially)
|
||||
- Critical Path (priority execution order)
|
||||
3. **Use TODO_LIST.md for status tracking** only
|
||||
4. **IMPL_PLAN decides "HOW"**, execute.md implements it
|
||||
|
||||
### Resume Mode Process (--resume-session flag - Optimized)
|
||||
```
|
||||
├── Use provided session-id directly (skip discovery)
|
||||
├── Validate .workflow/{session-id}/ directory exists
|
||||
├── Read TODO_LIST.md for current progress
|
||||
├── Parse TODO_LIST.md to extract task IDs and statuses
|
||||
├── Generate TodoWrite from TODO_LIST.md (prioritize in-progress/pending tasks)
|
||||
└── Enter Phase 4 (Execution) with lazy task JSON loading
|
||||
```
|
||||
**Intelligent Fallback (When IMPL_PLAN lacks execution details)**:
|
||||
1. **Analyze task structure**:
|
||||
- Check `meta.execution_group` in task JSONs
|
||||
- Analyze `depends_on` relationships
|
||||
- Understand task complexity and risk
|
||||
2. **Apply smart defaults**:
|
||||
- No dependencies + same execution_group → Parallel
|
||||
- Has dependencies → Sequential (wait for deps)
|
||||
- Critical/high-risk tasks → Sequential
|
||||
3. **Conservative approach**: When uncertain, prefer sequential execution
|
||||
|
||||
**Key Change**: Completely skip IMPL_PLAN.md and task JSON loading - use TODO_LIST.md only
|
||||
### Execution Models
|
||||
|
||||
#### 1. Sequential Execution
|
||||
**When**: IMPL_PLAN specifies "Sequential" OR no clear parallelization guidance
|
||||
**Pattern**: Execute tasks one by one in TODO_LIST order
|
||||
**TodoWrite**: ONE task marked as `in_progress` at a time
|
||||
|
||||
#### 2. Parallel Execution
|
||||
**When**: IMPL_PLAN specifies "Parallel" with clear parallelization opportunities
|
||||
**Pattern**: Execute independent task groups concurrently
|
||||
**TodoWrite**: MULTIPLE tasks (in same batch) marked as `in_progress` simultaneously
|
||||
|
||||
#### 3. Phased Execution
|
||||
**When**: IMPL_PLAN specifies "Phased" with phase breakdown
|
||||
**Pattern**: Execute tasks in phases, respect phase boundaries
|
||||
**TodoWrite**: Within each phase, follow Sequential or Parallel rules
|
||||
|
||||
#### 4. Intelligent Fallback
|
||||
**When**: IMPL_PLAN lacks execution strategy details
|
||||
**Pattern**: Analyze task structure and apply smart defaults
|
||||
**TodoWrite**: Follow Sequential or Parallel rules based on analysis
|
||||
|
||||
### Task Status Logic
|
||||
```
|
||||
@@ -182,155 +206,36 @@ completed → skip
|
||||
blocked → skip until dependencies clear
|
||||
```
|
||||
|
||||
## Batch Execution with Dependency Graph
|
||||
|
||||
### Parallel Execution Algorithm
|
||||
**Core principle**: Execute independent tasks concurrently in batches based on dependency graph.
|
||||
|
||||
#### Algorithm Steps (Optimized with Lazy Loading)
|
||||
```javascript
|
||||
function executeBatchWorkflow(sessionId) {
|
||||
// 1. Build dependency graph from TODO_LIST.md (NOT task JSONs)
|
||||
const graph = buildDependencyGraphFromTodoList(`.workflow/${sessionId}/TODO_LIST.md`);
|
||||
|
||||
// 2. Process batches until graph is empty
|
||||
while (!graph.isEmpty()) {
|
||||
// 3. Identify current batch (tasks with in-degree = 0)
|
||||
const batch = graph.getNodesWithInDegreeZero();
|
||||
|
||||
// 4. Load task JSONs ONLY for current batch (lazy loading)
|
||||
const batchTaskJsons = batch.map(taskId =>
|
||||
Read(`.workflow/${sessionId}/.task/${taskId}.json`)
|
||||
);
|
||||
|
||||
// 5. Check for parallel execution opportunities
|
||||
const parallelGroups = groupByExecutionGroup(batchTaskJsons);
|
||||
|
||||
// 6. Execute batch concurrently
|
||||
await Promise.all(
|
||||
parallelGroups.map(group => executeBatch(group))
|
||||
);
|
||||
|
||||
// 7. Update graph: remove completed tasks and their edges
|
||||
graph.removeNodes(batch);
|
||||
|
||||
// 8. Update TODO_LIST.md and TodoWrite to reflect completed batch
|
||||
updateTodoListAfterBatch(batch);
|
||||
updateTodoWriteAfterBatch(batch);
|
||||
}
|
||||
|
||||
// 9. All tasks complete - auto-complete session
|
||||
SlashCommand("/workflow:session:complete");
|
||||
}
|
||||
|
||||
function buildDependencyGraphFromTodoList(todoListPath) {
|
||||
const todoContent = Read(todoListPath);
|
||||
const tasks = parseTodoListTasks(todoContent);
|
||||
const graph = new DirectedGraph();
|
||||
|
||||
tasks.forEach(task => {
|
||||
graph.addNode(task.id, { id: task.id, title: task.title, status: task.status });
|
||||
task.dependencies?.forEach(depId => graph.addEdge(depId, task.id));
|
||||
});
|
||||
|
||||
return graph;
|
||||
}
|
||||
|
||||
function parseTodoListTasks(todoContent) {
|
||||
// Parse: - [ ] **IMPL-001**: Task title → [📋](./.task/IMPL-001.json)
|
||||
const taskPattern = /- \[([ x])\] \*\*([A-Z]+-\d+(?:\.\d+)?)\*\*: (.+?) →/g;
|
||||
const tasks = [];
|
||||
let match;
|
||||
|
||||
while ((match = taskPattern.exec(todoContent)) !== null) {
|
||||
tasks.push({
|
||||
status: match[1] === 'x' ? 'completed' : 'pending',
|
||||
id: match[2],
|
||||
title: match[3]
|
||||
});
|
||||
}
|
||||
|
||||
return tasks;
|
||||
}
|
||||
|
||||
function groupByExecutionGroup(tasks) {
|
||||
const groups = {};
|
||||
|
||||
tasks.forEach(task => {
|
||||
const groupId = task.meta.execution_group || task.id;
|
||||
if (!groups[groupId]) groups[groupId] = [];
|
||||
groups[groupId].push(task);
|
||||
});
|
||||
|
||||
return Object.values(groups);
|
||||
}
|
||||
|
||||
async function executeBatch(tasks) {
|
||||
// Execute all tasks in batch concurrently
|
||||
return Promise.all(
|
||||
tasks.map(task => executeTask(task))
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
#### Execution Group Rules
|
||||
1. **Same `execution_group` ID** → Execute in parallel (independent, different contexts)
|
||||
2. **No `execution_group` (null)** → Execute sequentially (has dependencies)
|
||||
3. **Different `execution_group` IDs** → Execute in parallel (independent batches)
|
||||
4. **Same `context_signature`** → Should have been merged (warning if not)
|
||||
|
||||
#### Parallel Execution Example
|
||||
```
|
||||
Batch 1 (no dependencies):
|
||||
- IMPL-1.1 (execution_group: "parallel-auth-api") → Agent 1
|
||||
- IMPL-1.2 (execution_group: "parallel-ui-comp") → Agent 2
|
||||
- IMPL-1.3 (execution_group: "parallel-db-schema") → Agent 3
|
||||
|
||||
Wait for Batch 1 completion...
|
||||
|
||||
Batch 2 (depends on Batch 1):
|
||||
- IMPL-2.1 (execution_group: null, depends_on: [IMPL-1.1, IMPL-1.2]) → Agent 1
|
||||
|
||||
Wait for Batch 2 completion...
|
||||
|
||||
Batch 3 (independent of Batch 2):
|
||||
- IMPL-3.1 (execution_group: "parallel-tests-1") → Agent 1
|
||||
- IMPL-3.2 (execution_group: "parallel-tests-2") → Agent 2
|
||||
```
|
||||
|
||||
## TodoWrite Coordination
|
||||
**Comprehensive workflow tracking** with immediate status updates throughout entire execution without user interruption:
|
||||
|
||||
#### TodoWrite Workflow Rules
|
||||
1. **Initial Creation**: Generate TodoWrite from discovered pending tasks for entire workflow
|
||||
- **Normal Mode**: Create from discovery results
|
||||
- **Resume Mode**: Create from existing session state and current progress
|
||||
2. **Parallel Task Support**:
|
||||
- **Single-task execution**: Mark ONLY ONE task as `in_progress` at a time
|
||||
- **Batch execution**: Mark ALL tasks in current batch as `in_progress` simultaneously
|
||||
- **Execution group indicator**: Show `[execution_group: group-id]` for parallel tasks
|
||||
3. **Immediate Updates**: Update status after each task/batch completion without user interruption
|
||||
4. **Status Synchronization**: Sync with JSON task files after updates
|
||||
5. **Continuous Tracking**: Maintain TodoWrite throughout entire workflow execution until completion
|
||||
### TodoWrite Rules (Unified)
|
||||
|
||||
#### Resume Mode TodoWrite Generation
|
||||
**Special behavior when `--resume-session` flag is present**:
|
||||
- Load existing session progress from `.workflow/{session-id}/TODO_LIST.md`
|
||||
- Identify currently in-progress or next pending task
|
||||
- Generate TodoWrite starting from interruption point
|
||||
- Preserve completed task history in TodoWrite display
|
||||
- Focus on remaining pending tasks for execution
|
||||
**Rule 1: Initial Creation**
|
||||
- **Normal Mode**: Generate TodoWrite from discovered pending tasks for entire workflow
|
||||
- **Resume Mode**: Generate from existing session state and current progress
|
||||
|
||||
#### TodoWrite Tool Usage
|
||||
**Use Claude Code's built-in TodoWrite tool** to track workflow progress in real-time:
|
||||
**Rule 2: In-Progress Task Count (Execution-Model-Dependent)**
|
||||
- **Sequential execution**: Mark ONLY ONE task as `in_progress` at a time
|
||||
- **Parallel batch execution**: Mark ALL tasks in current batch as `in_progress` simultaneously
|
||||
- **Execution group indicator**: Show `[execution_group: group-id]` for parallel tasks
|
||||
|
||||
**Rule 3: Status Updates**
|
||||
- **Immediate Updates**: Update status after each task/batch completion without user interruption
|
||||
- **Status Synchronization**: Sync with JSON task files after updates
|
||||
- **Continuous Tracking**: Maintain TodoWrite throughout entire workflow execution until completion
|
||||
|
||||
**Rule 4: Workflow Completion Check**
|
||||
- When all tasks marked `completed`, auto-call `/workflow:session:complete`
|
||||
|
||||
### TodoWrite Tool Usage
|
||||
|
||||
**Example 1: Sequential Execution**
|
||||
```javascript
|
||||
// Example 1: Sequential execution (traditional)
|
||||
TodoWrite({
|
||||
todos: [
|
||||
{
|
||||
content: "Execute IMPL-1.1: Design auth schema [code-developer] [FLOW_CONTROL]",
|
||||
status: "in_progress", // Single task in progress
|
||||
status: "in_progress", // ONE task in progress
|
||||
activeForm: "Executing IMPL-1.1: Design auth schema"
|
||||
},
|
||||
{
|
||||
@@ -340,8 +245,10 @@ TodoWrite({
|
||||
}
|
||||
]
|
||||
});
|
||||
```
|
||||
|
||||
// Example 2: Batch execution (parallel tasks with execution_group)
|
||||
**Example 2: Parallel Batch Execution**
|
||||
```javascript
|
||||
TodoWrite({
|
||||
todos: [
|
||||
{
|
||||
@@ -366,44 +273,9 @@ TodoWrite({
|
||||
}
|
||||
]
|
||||
});
|
||||
|
||||
// Example 3: After batch completion
|
||||
TodoWrite({
|
||||
todos: [
|
||||
{
|
||||
content: "Execute IMPL-1.1: Build Auth API [code-developer] [execution_group: parallel-auth-api]",
|
||||
status: "completed", // Batch completed
|
||||
activeForm: "Executing IMPL-1.1: Build Auth API"
|
||||
},
|
||||
{
|
||||
content: "Execute IMPL-1.2: Build User UI [code-developer] [execution_group: parallel-ui-comp]",
|
||||
status: "completed", // Batch completed
|
||||
activeForm: "Executing IMPL-1.2: Build User UI"
|
||||
},
|
||||
{
|
||||
content: "Execute IMPL-1.3: Setup Database [code-developer] [execution_group: parallel-db-schema]",
|
||||
status: "completed", // Batch completed
|
||||
activeForm: "Executing IMPL-1.3: Setup Database"
|
||||
},
|
||||
{
|
||||
content: "Execute IMPL-2.1: Integration Tests [test-fix-agent]",
|
||||
status: "in_progress", // Next batch started
|
||||
activeForm: "Executing IMPL-2.1: Integration Tests"
|
||||
}
|
||||
]
|
||||
});
|
||||
```
|
||||
|
||||
**TodoWrite Integration Rules**:
|
||||
- **Continuous Workflow Tracking**: Use TodoWrite tool throughout entire workflow execution
|
||||
- **Real-time Updates**: Immediate progress tracking without user interruption
|
||||
- **Single Active Task**: Only ONE task marked as `in_progress` at any time
|
||||
- **Immediate Completion**: Mark tasks `completed` immediately after finishing
|
||||
- **Status Sync**: Sync TodoWrite status with JSON task files after each update
|
||||
- **Full Execution**: Continue TodoWrite tracking until all workflow tasks complete
|
||||
- **Workflow Completion Check**: When all tasks marked `completed`, auto-call `/workflow:session:complete`
|
||||
|
||||
#### TODO_LIST.md Update Timing
|
||||
### TODO_LIST.md Update Timing
|
||||
**Single source of truth for task status** - enables lazy loading by providing task metadata without reading JSONs
|
||||
|
||||
- **Before Agent Launch**: Mark task as `in_progress`
|
||||
@@ -411,18 +283,17 @@ TodoWrite({
|
||||
- **On Error**: Keep as `in_progress`, add error note
|
||||
- **Workflow Complete**: Call `/workflow:session:complete`
|
||||
|
||||
### 3. Agent Context Management
|
||||
**Comprehensive context preparation** for autonomous agent execution:
|
||||
## Agent Context Management
|
||||
|
||||
#### Context Sources (Priority Order)
|
||||
### Context Sources (Priority Order)
|
||||
1. **Complete Task JSON**: Full task definition including all fields and artifacts
|
||||
2. **Artifacts Context**: Brainstorming outputs and role analysess from task.context.artifacts
|
||||
2. **Artifacts Context**: Brainstorming outputs and role analyses from task.context.artifacts
|
||||
3. **Flow Control Context**: Accumulated outputs from pre_analysis steps (including artifact loading)
|
||||
4. **Dependency Summaries**: Previous task completion summaries
|
||||
5. **Session Context**: Workflow paths and session metadata
|
||||
6. **Inherited Context**: Parent task context and shared variables
|
||||
|
||||
#### Context Assembly Process
|
||||
### Context Assembly Process
|
||||
```
|
||||
1. Load Task JSON → Base context (including artifacts array)
|
||||
2. Load Artifacts → Synthesis specifications and brainstorming outputs
|
||||
@@ -432,7 +303,7 @@ TodoWrite({
|
||||
6. Combine All → Complete agent context with artifact integration
|
||||
```
|
||||
|
||||
#### Agent Context Package Structure
|
||||
### Agent Context Package Structure
|
||||
```json
|
||||
{
|
||||
"task": { /* Complete task JSON with artifacts array */ },
|
||||
@@ -462,7 +333,7 @@ TodoWrite({
|
||||
}
|
||||
```
|
||||
|
||||
#### Context Validation Rules
|
||||
### Context Validation Rules
|
||||
- **Task JSON Complete**: All 5 fields present and valid, including artifacts array in context
|
||||
- **Artifacts Available**: All artifacts loaded from context-package.json
|
||||
- **Flow Control Ready**: All pre_analysis steps completed including artifact loading steps
|
||||
@@ -470,10 +341,26 @@ TodoWrite({
|
||||
- **Session Paths Valid**: All workflow paths exist and accessible (verified via context-package.json)
|
||||
- **Agent Assignment**: Valid agent type specified in meta.agent
|
||||
|
||||
### 4. Agent Execution Pattern
|
||||
**Structured agent invocation** with complete context and clear instructions:
|
||||
## Agent Execution Pattern
|
||||
|
||||
#### Agent Prompt Template
|
||||
### Flow Control Execution
|
||||
**[FLOW_CONTROL]** marker indicates task JSON contains `flow_control.pre_analysis` steps for context preparation.
|
||||
|
||||
**Orchestrator Responsibility**:
|
||||
- Pass complete task JSON to agent (including `flow_control` block)
|
||||
- Provide session paths for artifact access
|
||||
- Monitor agent completion
|
||||
|
||||
**Agent Responsibility**:
|
||||
- Parse `flow_control.pre_analysis` array from JSON
|
||||
- Execute steps sequentially with variable substitution
|
||||
- Accumulate context from artifacts and dependencies
|
||||
- Follow error handling per `step.on_error`
|
||||
- Complete implementation using accumulated context
|
||||
|
||||
**Orchestrator does NOT execute flow control steps - Agent interprets and executes them from JSON.**
|
||||
|
||||
### Agent Prompt Template
|
||||
```bash
|
||||
Task(subagent_type="{meta.agent}",
|
||||
prompt="**EXECUTE TASK FROM JSON**
|
||||
@@ -512,7 +399,7 @@ Task(subagent_type="{meta.agent}",
|
||||
description="Execute task: {task.id}")
|
||||
```
|
||||
|
||||
#### Agent JSON Loading Specification
|
||||
### Agent JSON Loading Specification
|
||||
**MANDATORY AGENT PROTOCOL**: All agents must follow this exact loading sequence:
|
||||
|
||||
1. **JSON Loading**: First action must be `cat {session.task_json_path}`
|
||||
@@ -606,7 +493,7 @@ Task(subagent_type="{meta.agent}",
|
||||
}
|
||||
```
|
||||
|
||||
#### Execution Flow
|
||||
### Execution Flow
|
||||
1. **Load Task JSON**: Agent reads and validates complete JSON structure
|
||||
2. **Execute Flow Control**: Agent runs pre_analysis steps if present
|
||||
3. **Prepare Implementation**: Agent uses implementation_approach from JSON
|
||||
@@ -614,7 +501,7 @@ Task(subagent_type="{meta.agent}",
|
||||
5. **Update Status**: Agent marks JSON status as completed
|
||||
6. **Generate Summary**: Agent creates completion summary
|
||||
|
||||
#### Agent Assignment Rules
|
||||
### Agent Assignment Rules
|
||||
```
|
||||
meta.agent specified → Use specified agent
|
||||
meta.agent missing → Infer from meta.type:
|
||||
@@ -625,12 +512,6 @@ meta.agent missing → Infer from meta.type:
|
||||
- "docs" → @doc-generator
|
||||
```
|
||||
|
||||
#### Error Handling During Execution
|
||||
- **Agent Failure**: Retry once with adjusted context
|
||||
- **Flow Control Error**: Skip optional steps, fail on critical
|
||||
- **Context Missing**: Reload from JSON files and retry
|
||||
- **Timeout**: Mark as blocked, continue with next task
|
||||
|
||||
## Workflow File Structure Reference
|
||||
```
|
||||
.workflow/WFS-[topic-slug]/
|
||||
@@ -644,78 +525,26 @@ meta.agent missing → Infer from meta.type:
|
||||
│ ├── IMPL-1-summary.md # Task completion details
|
||||
│ └── IMPL-1.1-summary.md # Subtask completion details
|
||||
└── .process/ # Planning artifacts
|
||||
├── context-package.json # Smart context package
|
||||
└── ANALYSIS_RESULTS.md # Planning analysis results
|
||||
```
|
||||
|
||||
## Error Handling & Recovery
|
||||
|
||||
### Discovery Phase Errors
|
||||
| Error | Cause | Resolution | Command |
|
||||
|-------|-------|------------|---------|
|
||||
| No active session | No `.active-*` markers found | Create or resume session | `/workflow:plan "project"` |
|
||||
| Multiple sessions | Multiple `.active-*` markers | Select specific session | Manual choice prompt |
|
||||
| Corrupted session | Invalid JSON files | Recreate session structure | `/workflow:session:status --validate` |
|
||||
| Missing task files | Broken task references | Regenerate tasks | `/task:create` or repair |
|
||||
### Common Errors & Recovery
|
||||
|
||||
### Execution Phase Errors
|
||||
| Error | Cause | Recovery Strategy | Max Attempts |
|
||||
|-------|-------|------------------|--------------|
|
||||
| Error Type | Cause | Recovery Strategy | Max Attempts |
|
||||
|-----------|-------|------------------|--------------|
|
||||
| **Discovery Errors** |
|
||||
| No active session | No `.active-*` markers found | Create or resume session: `/workflow:plan "project"` | N/A |
|
||||
| Multiple sessions | Multiple `.active-*` markers | Prompt user selection | N/A |
|
||||
| Corrupted session | Invalid JSON files | Recreate session structure or validate files | N/A |
|
||||
| **Execution Errors** |
|
||||
| Agent failure | Agent crash/timeout | Retry with simplified context | 2 |
|
||||
| Flow control error | Command failure | Skip optional, fail critical | 1 per step |
|
||||
| Context loading error | Missing dependencies | Reload from JSON, use defaults | 3 |
|
||||
| JSON file corruption | File system issues | Restore from backup/recreate | 1 |
|
||||
|
||||
### Recovery Procedures
|
||||
|
||||
#### Session Recovery
|
||||
```bash
|
||||
# Check session integrity
|
||||
find .workflow -name ".active-*" | while read marker; do
|
||||
session=$(basename "$marker" | sed 's/^\.active-//')
|
||||
if [ ! -d ".workflow/$session" ]; then
|
||||
echo "Removing orphaned marker: $marker"
|
||||
rm "$marker"
|
||||
fi
|
||||
done
|
||||
|
||||
# Recreate corrupted session files
|
||||
if [ ! -f ".workflow/$session/workflow-session.json" ]; then
|
||||
echo '{"session_id":"'$session'","status":"active"}' > ".workflow/$session/workflow-session.json"
|
||||
fi
|
||||
```
|
||||
|
||||
#### Task Recovery
|
||||
```bash
|
||||
# Validate task JSON integrity
|
||||
for task_file in .workflow/$session/.task/*.json; do
|
||||
if ! jq empty "$task_file" 2>/dev/null; then
|
||||
echo "Corrupted task file: $task_file"
|
||||
# Backup and regenerate or restore from backup
|
||||
fi
|
||||
done
|
||||
|
||||
# Fix missing dependencies
|
||||
missing_deps=$(jq -r '.context.depends_on[]?' .workflow/$session/.task/*.json | sort -u)
|
||||
for dep in $missing_deps; do
|
||||
if [ ! -f ".workflow/$session/.task/$dep.json" ]; then
|
||||
echo "Missing dependency: $dep - creating placeholder"
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
#### Context Recovery
|
||||
```bash
|
||||
# Reload context from available sources
|
||||
if [ -f ".workflow/$session/.process/ANALYSIS_RESULTS.md" ]; then
|
||||
echo "Reloading planning context..."
|
||||
fi
|
||||
|
||||
# Restore from documentation if available
|
||||
if [ -d ".workflow/docs/" ]; then
|
||||
echo "Using documentation context as fallback..."
|
||||
fi
|
||||
```
|
||||
|
||||
### Error Prevention
|
||||
- **Pre-flight Checks**: Validate session integrity before execution
|
||||
- **Backup Strategy**: Create task snapshots before major operations
|
||||
@@ -723,16 +552,31 @@ fi
|
||||
- **Dependency Validation**: Check all depends_on references exist
|
||||
- **Context Verification**: Ensure all required context is available
|
||||
|
||||
## Usage Examples
|
||||
### Recovery Procedures
|
||||
|
||||
### Basic Usage
|
||||
**Session Recovery**:
|
||||
```bash
|
||||
/workflow:execute # Execute all pending tasks autonomously
|
||||
/workflow:session:status # Check progress
|
||||
/task:execute IMPL-1.2 # Execute specific task
|
||||
# Check session integrity
|
||||
find .workflow -name ".active-*" | while read marker; do
|
||||
session=$(basename "$marker" | sed 's/^\.active-//')
|
||||
[ ! -d ".workflow/$session" ] && rm "$marker"
|
||||
done
|
||||
|
||||
# Recreate corrupted session files
|
||||
[ ! -f ".workflow/$session/workflow-session.json" ] && \
|
||||
echo '{"session_id":"'$session'","status":"active"}' > ".workflow/$session/workflow-session.json"
|
||||
```
|
||||
|
||||
### Integration
|
||||
- **Planning**: `/workflow:plan` → `/workflow:execute` → `/workflow:review`
|
||||
- **Recovery**: `/workflow:status --validate` → `/workflow:execute`
|
||||
**Task Recovery**:
|
||||
```bash
|
||||
# Validate task JSON integrity
|
||||
for task_file in .workflow/$session/.task/*.json; do
|
||||
jq empty "$task_file" 2>/dev/null || echo "Corrupted: $task_file"
|
||||
done
|
||||
|
||||
# Fix missing dependencies
|
||||
missing_deps=$(jq -r '.context.depends_on[]?' .workflow/$session/.task/*.json | sort -u)
|
||||
for dep in $missing_deps; do
|
||||
[ ! -f ".workflow/$session/.task/$dep.json" ] && echo "Missing dependency: $dep"
|
||||
done
|
||||
```
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
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"
|
||||
argument-hint: "[--tool claude|gemini|qwen|codex] [-e|--explore] \"task description\"|file.md"
|
||||
allowed-tools: TodoWrite(*), Task(*), Bash(*), AskUserQuestion(*)
|
||||
timeout: 180000
|
||||
color: cyan
|
||||
@@ -13,15 +13,6 @@ color: cyan
|
||||
|
||||
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
|
||||
@@ -30,24 +21,11 @@ Intelligent lightweight planning and execution command with dynamic workflow ada
|
||||
- **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
|
||||
- **Two-Step Confirmation**: First display complete plan as text, then collect three-dimensional input (task approval + execution method + code review tool)
|
||||
- **Direct Execution**: Immediate dispatch to selected execution method (agent/codex/auto)
|
||||
- **Live Progress Tracking**: Real-time TodoWrite updates at execution call level ([Agent-1], [Codex-1], etc.) during execution
|
||||
- **Optional Code Review**: Post-execution quality analysis with gemini/agent or custom tools via "Other" option (e.g., qwen, codex)
|
||||
|
||||
## 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
|
||||
|
||||
@@ -56,31 +34,12 @@ Intelligent lightweight planning and execution command with dynamic workflow ada
|
||||
/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)
|
||||
-e, --explore Force code exploration phase (overrides auto-detection logic)
|
||||
|
||||
# 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
|
||||
|
||||
@@ -92,7 +51,7 @@ 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)
|
||||
-> Decision: Need exploration? (Yes/No)
|
||||
-> If Yes: Launch cli-explore-agent
|
||||
-> Output: exploration findings (if performed)
|
||||
|
|
||||
@@ -113,20 +72,21 @@ User Input ("/workflow:lite-plan \"task\"")
|
||||
|
|
||||
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
|
||||
-> Step 4.1: Output complete plan as text to user
|
||||
-> Step 4.2: AskUserQuestion with three dimensions
|
||||
1. Confirm task: Allow/Modify/Cancel (multi-select, can supplement via Other)
|
||||
2. Execution method: Agent/Codex/Auto (single-select, auto: simple→agent, complex→codex)
|
||||
3. Code review: Skip/Gemini/Agent/Other (single-select, can specify custom tool via Other)
|
||||
-> Process selections and proceed to Phase 5
|
||||
-> If cancel: Exit
|
||||
|
|
||||
v
|
||||
[Phase 5] Execution & Progress Tracking
|
||||
-> Create TodoWrite task list from breakdown
|
||||
-> Create TodoWrite execution call list (grouped tasks)
|
||||
-> Launch selected execution (agent or CLI)
|
||||
-> Track progress with TodoWrite updates
|
||||
-> Real-time status displayed to user
|
||||
-> Track execution call progress with TodoWrite updates
|
||||
-> Real-time call status displayed to user (e.g., "[Agent-1] (Task A + Task B)")
|
||||
-> If code review enabled: Run selected CLI analysis
|
||||
|
|
||||
v
|
||||
Execution Complete
|
||||
@@ -134,9 +94,10 @@ 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
|
||||
- TodoWrite creates execution call list before execution starts (Phase 5)
|
||||
- Execution calls ([Agent-1], [Codex-1], etc.) marked as in_progress/completed during execution
|
||||
- Each execution call handles multiple related tasks
|
||||
- Real-time progress updates visible at call level (not individual task level)
|
||||
- No intermediate file artifacts generated
|
||||
|
||||
## Detailed Phase Execution
|
||||
@@ -148,17 +109,21 @@ Execution Complete
|
||||
- Decision logic:
|
||||
```javascript
|
||||
needsExploration = (
|
||||
task.mentions_specific_files ||
|
||||
task.requires_codebase_context ||
|
||||
task.needs_architecture_understanding ||
|
||||
task.modifies_existing_code
|
||||
) && !flags.includes('--quick')
|
||||
flags.includes('--explore') || flags.includes('-e') || // Force exploration if flag present
|
||||
(
|
||||
task.mentions_specific_files ||
|
||||
task.requires_codebase_context ||
|
||||
task.needs_architecture_understanding ||
|
||||
task.modifies_existing_code
|
||||
)
|
||||
)
|
||||
```
|
||||
|
||||
**Decision Criteria**:
|
||||
|
||||
| Task Type | Needs Exploration | Reason |
|
||||
|-----------|-------------------|--------|
|
||||
| Any task with `-e` or `--explore` flag | **Yes (forced)** | **Flag overrides auto-detection logic** |
|
||||
| "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 |
|
||||
@@ -301,36 +266,25 @@ else complexity = "High"
|
||||
**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"
|
||||
}
|
||||
```
|
||||
|
||||
Current Claude generates plan directly following these guidelines:
|
||||
- **Summary**: 2-3 sentence overview of the implementation
|
||||
- **Approach**: High-level implementation strategy
|
||||
- **Task Breakdown**: 3-5 specific, actionable tasks with file paths
|
||||
- **Estimated Time**: Total implementation time estimate
|
||||
- **Recommended Execution**: "Agent" (for Low complexity tasks)
|
||||
|
||||
**Option B: Agent-Based Planning (Medium/High Complexity)**
|
||||
|
||||
Delegate to cli-planning-agent with detailed requirements:
|
||||
```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"}
|
||||
|
||||
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:
|
||||
@@ -338,75 +292,31 @@ Task(
|
||||
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")
|
||||
- Each task should specify: What to do, Which files to modify/create, Dependencies on other tasks (if any)
|
||||
4. Task Dependencies & Parallelization:
|
||||
- Identify independent tasks that can run in parallel (no shared file conflicts or logical dependencies)
|
||||
- Group tasks by execution order: parallel groups can execute simultaneously, sequential groups must wait for previous completion
|
||||
- Format: "Group 1 (parallel): Task 1, Task 2 | Group 2 (parallel): Task 3, Task 4 | Task 5 (depends on all)"
|
||||
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"
|
||||
}
|
||||
7. Recommended Execution: "Agent" or "Codex" based on task complexity
|
||||
|
||||
Ensure tasks are specific, with file paths and clear acceptance criteria.
|
||||
`
|
||||
)
|
||||
|
||||
// Agent returns detailed plan
|
||||
planObject = agent_output.parse()
|
||||
```
|
||||
|
||||
**Expected Return Structure**:
|
||||
**Expected Return Structure (Both Options)**:
|
||||
```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"
|
||||
summary: string, // 2-3 sentence overview
|
||||
approach: string, // High-level implementation strategy
|
||||
tasks: string[], // 3-5 tasks (Low) or 5-10 tasks (Medium/High) with file paths
|
||||
dependencies: string[], // Task execution order: parallel groups and sequential dependencies (Medium/High only)
|
||||
risks: string[], // Potential issues and mitigation strategies (Medium/High only)
|
||||
estimated_time: string, // Total implementation time estimate
|
||||
recommended_execution: string, // "Agent" (Low) or "Codex" (Medium/High)
|
||||
complexity: string // "Low" | "Medium" | "High"
|
||||
}
|
||||
```
|
||||
|
||||
@@ -422,75 +332,116 @@ planObject = {
|
||||
|
||||
### Phase 4: Task Confirmation & Execution Selection
|
||||
|
||||
**User Interaction Flow**: Two-dimensional confirmation (task + execution method)
|
||||
**User Interaction Flow**: Two-step confirmation process
|
||||
|
||||
**Step 4.1: Display Plan Summary**
|
||||
|
||||
First, output the complete plan to the user as regular text:
|
||||
|
||||
```
|
||||
## Implementation Plan
|
||||
|
||||
**Summary**: ${planObject.summary}
|
||||
|
||||
**Approach**: ${planObject.approach}
|
||||
|
||||
**Task Breakdown**:
|
||||
${planObject.tasks.map((t, i) => `${i+1}. ${t}`).join('\n')}
|
||||
|
||||
${planObject.dependencies ? `\n**Dependencies**:\n${planObject.dependencies.join('\n')}` : ''}
|
||||
|
||||
${planObject.risks ? `\n**Risks**:\n${planObject.risks.join('\n')}` : ''}
|
||||
|
||||
**Complexity**: ${planObject.complexity}
|
||||
**Estimated Time**: ${planObject.estimated_time}
|
||||
**Recommended Execution**: ${planObject.recommended_execution}
|
||||
```
|
||||
|
||||
**Step 4.2: Collect User Confirmation**
|
||||
|
||||
After displaying the plan, collect three inputs via AskUserQuestion:
|
||||
|
||||
**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
|
||||
- Collect three inputs:
|
||||
1. Task confirmation (multi-select: Allow/Modify/Cancel + optional supplements via "Other")
|
||||
2. Execution method (single-select: Agent/Codex/Auto)
|
||||
- Agent: Execute with @code-developer
|
||||
- Codex: Execute with codex CLI tool
|
||||
- Auto: Simple tasks (Low complexity) → Agent, Complex tasks (Medium/High) → Codex
|
||||
3. Code review tool (single-select: Skip/Gemini/Agent + custom tools via "Other")
|
||||
- Gemini Review: Use gemini CLI for code analysis
|
||||
- Agent Review: Use @code-reviewer agent
|
||||
- Other: Specify custom tool (e.g., "qwen", "codex") via text input
|
||||
- Support plan supplements and custom tool specification via "Other" input
|
||||
|
||||
**Question 1: Task Confirmation**
|
||||
**Three Questions in Single AskUserQuestion Call**:
|
||||
- Question 1: Task confirmation (multi-select: Allow/Modify/Cancel)
|
||||
- Question 2: Execution method selection (single-select: Agent/Codex/Auto)
|
||||
- Question 3: Code review tool selection (single-select: Skip/Gemini/Agent, custom via "Other")
|
||||
|
||||
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**:
|
||||
**AskUserQuestion Call**:
|
||||
```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" }
|
||||
]
|
||||
}]
|
||||
})
|
||||
questions: [
|
||||
{
|
||||
question: `**Plan Summary**: ${planObject.summary}
|
||||
|
||||
// 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" }
|
||||
]
|
||||
}]
|
||||
**Tasks**: ${planObject.tasks.length} tasks | **Complexity**: ${planObject.complexity} | **Estimated Time**: ${planObject.estimated_time}
|
||||
|
||||
Confirm this plan? (Multi-select enabled - you can select multiple options and add supplements via "Other")`,
|
||||
header: "Confirm Plan",
|
||||
multiSelect: true,
|
||||
options: [
|
||||
{ label: "Allow", description: "Proceed with plan as-is" },
|
||||
{ label: "Modify", description: "Adjust plan before execution" },
|
||||
{ label: "Cancel", description: "Abort workflow" }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: `Select execution method:`,
|
||||
header: "Execution",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Agent", description: "Execute with @code-developer agent" },
|
||||
{ label: "Codex", description: "Execute with codex CLI tool" },
|
||||
{ label: "Auto", description: `Auto-select: ${planObject.complexity === 'Low' ? 'Agent (Low complexity)' : 'Codex (Medium/High complexity)'}` }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: `Enable code review after execution?
|
||||
|
||||
(You can specify other tools like "qwen" or "codex" via "Other" option)`,
|
||||
header: "Code Review",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Gemini Review", description: "Review with Gemini CLI tool (gemini-2.5-pro)" },
|
||||
{ label: "Agent Review", description: "Review with @code-reviewer agent" },
|
||||
{ label: "Skip", description: "No review needed" }
|
||||
]
|
||||
}
|
||||
]
|
||||
})
|
||||
```
|
||||
|
||||
**Decision Flow**:
|
||||
```
|
||||
Task Confirmation:
|
||||
├─ Confirm → Execution Method Selection → Phase 5
|
||||
├─ Modify → Collect feedback → Re-run Phase 3
|
||||
Task Confirmation (Multi-select):
|
||||
├─ Allow (+ optional supplements in Other) → Proceed to Execution Method Selection
|
||||
├─ Modify (+ optional supplements in Other) → Re-run Phase 3 with modifications
|
||||
└─ 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
|
||||
Execution Method Selection (Single-select):
|
||||
├─ Agent → Launch @code-developer agent
|
||||
├─ Codex → Execute with codex CLI tool
|
||||
└─ Auto → Automatic selection:
|
||||
├─ If complexity = Low → Launch @code-developer agent
|
||||
└─ If complexity = Medium/High → Execute with codex CLI tool
|
||||
|
||||
Code Review Selection (after execution):
|
||||
├─ Skip → Skip review, workflow complete
|
||||
├─ Gemini Review → Run gemini code analysis (gemini-2.5-pro)
|
||||
├─ Agent Review → Current Claude agent review
|
||||
└─ Other → Specify custom tool (e.g., "qwen", "codex") via text input
|
||||
```
|
||||
|
||||
**Progress Tracking**:
|
||||
@@ -504,42 +455,57 @@ Execution Method Selection:
|
||||
### Phase 5: Execution & Progress Tracking
|
||||
|
||||
**Operations**:
|
||||
- Create TodoWrite task list from plan breakdown
|
||||
- Create TodoWrite execution call list (grouped tasks by dependencies)
|
||||
- Launch selected execution method (agent or CLI)
|
||||
- Track execution progress with real-time TodoWrite updates
|
||||
- Display status to user
|
||||
- Track execution call progress with real-time TodoWrite updates (not individual tasks)
|
||||
- Display execution status to user
|
||||
|
||||
**Step 5.1: Create TodoWrite Task List**
|
||||
**Step 5.1: Create TodoWrite Execution List**
|
||||
|
||||
**Before execution starts**, create task list:
|
||||
**Before execution starts**, create execution call list (not individual tasks):
|
||||
```javascript
|
||||
// Group tasks based on dependencies and execution strategy
|
||||
// Each execution call handles multiple related tasks
|
||||
executionCalls = groupTasksByExecution(planObject.tasks, planObject.dependencies)
|
||||
|
||||
TodoWrite({
|
||||
todos: planObject.tasks.map((task, index) => ({
|
||||
content: task,
|
||||
todos: executionCalls.map((call, index) => ({
|
||||
content: `[${call.method}-${index+1}] (${call.taskSummary})`,
|
||||
status: "pending",
|
||||
activeForm: task.replace(/^(.*?):/, "$1ing:") // "Implement X" -> "Implementing X"
|
||||
activeForm: `Executing [${call.method}-${index+1}] (${call.taskSummary})`
|
||||
}))
|
||||
})
|
||||
```
|
||||
|
||||
**Example Task List**:
|
||||
**Example Execution 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
|
||||
[ ] [Agent-1] (Implement auth service + Create JWT utilities)
|
||||
[ ] [Agent-2] (Add middleware + Update routes)
|
||||
[ ] [Codex-1] (Add integration tests for auth flow)
|
||||
```
|
||||
|
||||
**Task Grouping Logic**:
|
||||
- Parallel tasks → Single execution call
|
||||
- Sequential tasks → Separate execution calls
|
||||
- Complex tasks → May split into multiple calls based on file scope
|
||||
|
||||
**Step 5.2: Launch Execution**
|
||||
|
||||
**IMPORTANT**: CLI execution MUST run in foreground (no background execution)
|
||||
|
||||
Based on user selection in Phase 4, execute appropriate method:
|
||||
- **Agent**: Launch @code-developer agent
|
||||
- **Codex**: Execute with codex CLI tool
|
||||
- **Auto**: Automatic selection based on complexity
|
||||
- Low complexity → Agent execution
|
||||
- Medium/High complexity → Codex execution
|
||||
|
||||
#### Option A: Direct Execution with Agent
|
||||
|
||||
**Operations**:
|
||||
- Launch @code-developer agent with full plan context
|
||||
- Agent receives exploration findings, clarifications, and task breakdown
|
||||
- **For subsequent executions**: Include previous execution results to maintain context continuity
|
||||
- Agent call format:
|
||||
```javascript
|
||||
Task(
|
||||
@@ -555,6 +521,14 @@ Based on user selection in Phase 4, execute appropriate method:
|
||||
|
||||
${planObject.dependencies ? `\nTask Dependencies:\n${planObject.dependencies.join('\n')}` : ''}
|
||||
|
||||
${previousExecutionResults ? `\n## Previous Execution Results\n${previousExecutionResults.map(result => `
|
||||
[${result.executionId}] ${result.status}
|
||||
Tasks handled: ${result.tasksSummary}
|
||||
Completion status: ${result.completionSummary}
|
||||
Key outputs: ${result.keyOutputs || 'See git diff for details'}
|
||||
${result.notes ? `Notes: ${result.notes}` : ''}
|
||||
`).join('\n---\n')}` : ''}
|
||||
|
||||
Implementation Approach:
|
||||
${planObject.approach}
|
||||
|
||||
@@ -566,91 +540,50 @@ Based on user selection in Phase 4, execute appropriate method:
|
||||
${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
|
||||
- **Context Continuity**: Review previous execution results above to understand what's already completed
|
||||
- **Build on Previous Work**: Ensure your work integrates with previously completed tasks
|
||||
- **Avoid Duplication**: Don't redo tasks that are already completed in previous executions
|
||||
- **Parallel Execution**: Identify independent tasks from dependencies field and execute them in parallel using multiple tool calls in a single message
|
||||
- **Dependency Respect**: Sequential tasks must wait for dependent tasks to complete before starting
|
||||
- **Intelligent Grouping**: Analyze task dependencies to determine parallel groups - tasks with no file conflicts or logical dependencies can run simultaneously
|
||||
- Test functionality as you go
|
||||
- Handle risks proactively
|
||||
|
||||
Note: This agent call handles multiple tasks. TodoWrite tracking is managed at call level by orchestrator.
|
||||
`
|
||||
)
|
||||
```
|
||||
|
||||
**Agent Responsibilities**:
|
||||
- Mark tasks as in_progress when starting
|
||||
- Mark tasks as completed when finished
|
||||
- Update TodoWrite in real-time for user visibility
|
||||
- Each agent call handles multiple tasks (grouped by dependencies)
|
||||
- Agent updates TodoWrite at **call level** (not individual task level)
|
||||
- Mark execution call as in_progress when starting, completed when all assigned tasks finished
|
||||
|
||||
#### Option B: CLI Execution (Gemini/Codex/Qwen)
|
||||
**Execution Result Collection** (for multi-execution scenarios):
|
||||
- After each execution completes, collect result summary:
|
||||
```javascript
|
||||
executionResult = {
|
||||
executionId: "[Agent-1]" or "[Codex-1]",
|
||||
status: "completed" or "partial" or "failed",
|
||||
tasksSummary: "Brief description of tasks handled",
|
||||
completionSummary: "What was completed",
|
||||
keyOutputs: "Files created/modified, key changes",
|
||||
notes: "Any important context for next execution"
|
||||
}
|
||||
previousExecutionResults.push(executionResult)
|
||||
```
|
||||
- Pass `previousExecutionResults` to subsequent executions for context continuity
|
||||
|
||||
#### Option B: CLI Execution (Codex)
|
||||
|
||||
**Operations**:
|
||||
- Build CLI command with comprehensive context
|
||||
- Execute CLI tool with write permissions
|
||||
- Build codex CLI command with comprehensive context
|
||||
- **For subsequent executions**: Include previous execution results summary
|
||||
- Execute codex 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)**:
|
||||
**Command Format (Codex)** - Single execution with full context:
|
||||
```bash
|
||||
codex --full-auto exec "
|
||||
TASK: ${planObject.summary}
|
||||
@@ -660,6 +593,17 @@ ${planObject.tasks.map((t, i) => `${i+1}. ${t}`).join('\n')}
|
||||
|
||||
${planObject.dependencies ? `\n## Task Dependencies\n${planObject.dependencies.join('\n')}` : ''}
|
||||
|
||||
${previousExecutionResults ? `\n## Previous Execution Results\n${previousExecutionResults.map(result => `
|
||||
[${result.executionId}] ${result.status}
|
||||
Tasks: ${result.tasksSummary}
|
||||
Status: ${result.completionSummary}
|
||||
Outputs: ${result.keyOutputs || 'See git diff'}
|
||||
${result.notes ? `Notes: ${result.notes}` : ''}
|
||||
`).join('\n---\n')}
|
||||
|
||||
IMPORTANT: Review previous results above. Build on completed work. Avoid duplication.
|
||||
` : ''}
|
||||
|
||||
## Implementation Approach
|
||||
${planObject.approach}
|
||||
|
||||
@@ -677,158 +621,111 @@ ${clarificationContext ? `\n## User Clarifications\n${Object.entries(clarificati
|
||||
${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
|
||||
- Review previous execution results for context continuity
|
||||
- Build on previous work, don't duplicate completed tasks
|
||||
- Complete all assigned tasks in single execution
|
||||
- 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
|
||||
" --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.
|
||||
**Note**: Avoid `resume --last` unless task is exceptionally complex or hits timeout. Optimize task breakdown for full completion in single execution.
|
||||
|
||||
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 Result Collection** (for multi-execution scenarios):
|
||||
- After CLI execution completes, analyze output and collect result summary
|
||||
- Extract key information: modified files, completion status, important notes
|
||||
- Store in `previousExecutionResults` array for subsequent executions
|
||||
- Result structure same as Agent execution (see Option A above)
|
||||
|
||||
**Execution with Progress Tracking**:
|
||||
```javascript
|
||||
// Launch CLI in background
|
||||
// Launch CLI in foreground (NOT background)
|
||||
bash_result = Bash(
|
||||
command=cli_command,
|
||||
timeout=600000, // 10 minutes
|
||||
run_in_background=true
|
||||
timeout=600000 // 10 minutes
|
||||
)
|
||||
|
||||
// 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
|
||||
// Update TodoWrite when CLI execution call completes
|
||||
// Mark execution call (e.g., "[Codex-1]") as completed when CLI finishes
|
||||
// One CLI call may handle multiple tasks - track at call level, not task level
|
||||
```
|
||||
|
||||
**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
|
||||
- Monitor CLI execution at **call level** (not individual task level)
|
||||
- Update TodoWrite when CLI execution call completes (all assigned tasks done)
|
||||
- Provide real-time visibility of execution call progress to user
|
||||
|
||||
**Step 5.3: Track Execution Progress**
|
||||
|
||||
Track **agent/CLI call level** (not individual tasks):
|
||||
|
||||
**Real-time TodoWrite Updates**:
|
||||
```javascript
|
||||
// As execution progresses, update task status:
|
||||
|
||||
// Task started
|
||||
// When execution call starts
|
||||
TodoWrite({
|
||||
todos: [
|
||||
{ content: "Implement auth service", status: "in_progress", activeForm: "Implementing auth service" },
|
||||
{ content: "Create JWT utilities", status: "pending", activeForm: "Creating JWT utilities" },
|
||||
// ...
|
||||
{ content: "[Agent-1] (Implement auth service + Create JWT utilities)", status: "in_progress", activeForm: "Executing [Agent-1] (Implement auth service + Create JWT utilities)" },
|
||||
{ content: "[Agent-2] (Add middleware + Update routes)", status: "pending", activeForm: "Executing [Agent-2] (Add middleware + Update routes)" },
|
||||
{ content: "[Codex-1] (Add integration tests)", status: "pending", activeForm: "Executing [Codex-1] (Add integration tests)" }
|
||||
]
|
||||
})
|
||||
|
||||
// Task completed
|
||||
// When execution call completes
|
||||
TodoWrite({
|
||||
todos: [
|
||||
{ content: "Implement auth service", status: "completed", activeForm: "Implementing auth service" },
|
||||
{ content: "Create JWT utilities", status: "in_progress", activeForm: "Creating JWT utilities" },
|
||||
// ...
|
||||
{ content: "[Agent-1] (Implement auth service + Create JWT utilities)", status: "completed", activeForm: "Executing [Agent-1] (Implement auth service + Create JWT utilities)" },
|
||||
{ content: "[Agent-2] (Add middleware + Update routes)", status: "in_progress", activeForm: "Executing [Agent-2] (Add middleware + Update routes)" },
|
||||
{ content: "[Codex-1] (Add integration tests)", status: "pending", activeForm: "Executing [Codex-1] (Add integration tests)" }
|
||||
]
|
||||
})
|
||||
```
|
||||
|
||||
**User Visibility**:
|
||||
- User sees real-time task progress
|
||||
- Current task highlighted as "in_progress"
|
||||
- Completed tasks marked with checkmark
|
||||
- Pending tasks remain unchecked
|
||||
- User sees **execution call progress** (not individual task progress)
|
||||
- Current execution highlighted as "in_progress" (e.g., "[Agent-1] (Task A + Task B)")
|
||||
- Completed executions marked with checkmark
|
||||
- Pending executions remain unchecked
|
||||
- Each execution shows **task summary** for context
|
||||
|
||||
**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
|
||||
- Track agent/CLI call completion (not task completion)
|
||||
- One execution call may handle multiple tasks simultaneously
|
||||
- Mark Phase 5 as completed when all execution calls done
|
||||
|
||||
**Step 5.4: Code Review (Optional)**
|
||||
|
||||
**Skip Condition**: Only run if user selected review tool in Phase 4 (not "Skip")
|
||||
|
||||
**Operations**:
|
||||
- If "Agent Review": Current agent performs direct code review analysis
|
||||
- If "Gemini Review": Execute gemini CLI with code review analysis prompt
|
||||
- If "Other" (custom tool specified): Execute specified CLI tool (e.g., qwen, codex)
|
||||
- Review all modified files from execution
|
||||
- Generate quality assessment and improvement recommendations
|
||||
|
||||
**Command Format**:
|
||||
```bash
|
||||
# Agent Review: Direct agent review (no CLI command needed)
|
||||
# Uses analysis prompt and TodoWrite tools directly
|
||||
|
||||
# Gemini Review / Custom Tool (qwen, codex, etc.): Execute analysis command
|
||||
{selected_tool} -p "
|
||||
PURPOSE: Code review for implemented changes
|
||||
TASK: • Analyze code quality • Identify potential issues • Suggest improvements
|
||||
MODE: analysis
|
||||
CONTEXT: @**/* | Memory: Review changes from lite-plan execution
|
||||
EXPECTED: Quality assessment with actionable recommendations
|
||||
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-review-code-quality.txt) | Focus on recent changes | analysis=READ-ONLY
|
||||
"
|
||||
```
|
||||
|
||||
**Expected Duration**: Varies by task complexity and execution method
|
||||
- Low complexity: 5-15 minutes
|
||||
- Medium complexity: 15-45 minutes
|
||||
- High complexity: 45-120 minutes
|
||||
- Code review (if enabled): +2-5 minutes
|
||||
|
||||
---
|
||||
|
||||
@@ -841,6 +738,11 @@ TodoWrite({
|
||||
- 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
|
||||
- **Flag-Based Control**:
|
||||
- Use `-e` or `--explore` to force exploration when:
|
||||
- Task appears simple but you know it requires codebase context
|
||||
- Auto-detection might miss subtle integration points
|
||||
- You want comprehensive code understanding before planning
|
||||
|
||||
2. **Progressive Clarification**: Gather information at the right time
|
||||
- Phase 1: Explore codebase to understand current state
|
||||
@@ -854,19 +756,27 @@ TodoWrite({
|
||||
- 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
|
||||
4. **Two-Step Confirmation Process**: Clear plan presentation followed by comprehensive control
|
||||
- **Step 1**: Display complete plan as readable text output (not embedded in question)
|
||||
- Shows summary, approach, tasks, dependencies, risks, complexity, time estimate
|
||||
- Clear separation between plan content and user interaction
|
||||
- **Step 2**: Collect three-dimensional input via AskUserQuestion
|
||||
- First dimension: Confirm/Modify/Cancel plan (multi-select with supplement via "Other")
|
||||
- Second dimension: Execution method selection (Agent/Codex/Auto)
|
||||
- Third dimension: Code review tool selection (Skip/Gemini/Agent, custom via "Other")
|
||||
- Allows plan refinement without re-selecting execution method
|
||||
- Supports iterative planning with user feedback
|
||||
- Auto mode intelligently selects execution method based on complexity
|
||||
- Custom code review tools (qwen, codex, etc.) can be specified via "Other" option
|
||||
|
||||
### 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
|
||||
1. **Live Progress Tracking**: TodoWrite provides real-time execution call visibility
|
||||
- Execution calls ([Agent-1], [Codex-1], etc.) created before execution starts
|
||||
- Updated in real-time as execution calls progress
|
||||
- User sees current execution call being worked on (e.g., "[Agent-1] (Task A + Task B)")
|
||||
- Each execution call shows task summary for context
|
||||
- Clear completion status at call level (not individual task level)
|
||||
|
||||
2. **Phase-Based Organization**: 5 distinct phases with clear transitions
|
||||
- Phase 1: Task Analysis & Exploration (automatic)
|
||||
@@ -919,8 +829,8 @@ TodoWrite({
|
||||
| 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 |
|
||||
| Phase 5 Codex Unavailable | Codex tool not installed | Show installation instructions, offer to re-select (Agent execution or Auto mode) |
|
||||
| Phase 5 Execution Failure | Agent/Codex crashes or errors | Display error details, save partial progress from TodoWrite, suggest manual recovery or retry |
|
||||
|
||||
## Input/Output
|
||||
|
||||
@@ -933,8 +843,7 @@ TodoWrite({
|
||||
- "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
|
||||
- `-e` or `--explore`: Force code exploration phase (overrides auto-detection)
|
||||
|
||||
### Output Format
|
||||
|
||||
@@ -949,7 +858,7 @@ TodoWrite({
|
||||
// ... 3-7 tasks total
|
||||
],
|
||||
complexity: "Low|Medium|High",
|
||||
recommended_tool: "Claude|Gemini|Codex|Qwen",
|
||||
recommended_execution: "Agent|Codex", // Based on complexity
|
||||
estimated_time: "X minutes"
|
||||
}
|
||||
```
|
||||
|
||||
@@ -236,35 +236,31 @@ SlashCommand(command="/workflow:tools:task-generate-agent --session [sessionId]
|
||||
- `.workflow/[sessionId]/.task/IMPL-*.json` exists (at least one)
|
||||
- `.workflow/[sessionId]/TODO_LIST.md` exists
|
||||
|
||||
<!-- TodoWrite: When task-generate-agent invoked, INSERT 3 task-generate-agent tasks -->
|
||||
<!-- TodoWrite: When task-generate-agent invoked, ATTACH 1 agent task -->
|
||||
|
||||
**TodoWrite Update (Phase 4 SlashCommand invoked - tasks attached)**:
|
||||
**TodoWrite Update (Phase 4 SlashCommand invoked - agent task attached)**:
|
||||
```json
|
||||
[
|
||||
{"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
|
||||
{"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
|
||||
{"content": "Phase 4.1: Discovery - analyze requirements (task-generate-agent)", "status": "in_progress", "activeForm": "Analyzing requirements"},
|
||||
{"content": "Phase 4.2: Planning - design tasks (task-generate-agent)", "status": "pending", "activeForm": "Designing tasks"},
|
||||
{"content": "Phase 4.3: Output - generate JSONs (task-generate-agent)", "status": "pending", "activeForm": "Generating task JSONs"}
|
||||
{"content": "Execute task-generate-agent", "status": "in_progress", "activeForm": "Executing task-generate-agent"}
|
||||
]
|
||||
```
|
||||
|
||||
**Note**: SlashCommand invocation **attaches** task-generate-agent's 3 tasks. Orchestrator **executes** these tasks.
|
||||
**Note**: Single agent task attached. Agent autonomously completes discovery, planning, and output generation internally.
|
||||
|
||||
**Next Action**: Tasks attached → **Execute Phase 4.1-4.3** sequentially
|
||||
<!-- TodoWrite: After agent completes, mark task as completed -->
|
||||
|
||||
<!-- TodoWrite: After Phase 4 tasks complete, REMOVE Phase 4.1-4.3, restore to orchestrator view -->
|
||||
|
||||
**TodoWrite Update (Phase 4 completed - tasks collapsed)**:
|
||||
**TodoWrite Update (Phase 4 completed)**:
|
||||
```json
|
||||
[
|
||||
{"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
|
||||
{"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
|
||||
{"content": "Execute task generation", "status": "completed", "activeForm": "Executing task generation"}
|
||||
{"content": "Execute task-generate-agent", "status": "completed", "activeForm": "Executing task-generate-agent"}
|
||||
]
|
||||
```
|
||||
|
||||
**Note**: Phase 4 tasks completed and collapsed to summary.
|
||||
**Note**: Agent task completed. No collapse needed (single task).
|
||||
|
||||
**Return to User**:
|
||||
```
|
||||
@@ -288,31 +284,35 @@ Quality Gate: Consider running /workflow:action-plan-verify to catch issues earl
|
||||
|
||||
1. **Task Attachment** (when SlashCommand invoked):
|
||||
- Sub-command's internal tasks are **attached** to orchestrator's TodoWrite
|
||||
- Example: `/workflow:tools:context-gather` attaches 3 sub-tasks (Phase 2.1, 2.2, 2.3)
|
||||
- **Phase 2, 3**: Multiple sub-tasks attached (e.g., Phase 2.1, 2.2, 2.3)
|
||||
- **Phase 4**: Single agent task attached (e.g., "Execute task-generate-agent")
|
||||
- First attached task marked as `in_progress`, others as `pending`
|
||||
- Orchestrator **executes** these attached tasks sequentially
|
||||
|
||||
2. **Task Collapse** (after sub-tasks complete):
|
||||
- Remove detailed sub-tasks from TodoWrite
|
||||
- **Applies to Phase 2, 3**: Remove detailed sub-tasks from TodoWrite
|
||||
- **Collapse** to high-level phase summary
|
||||
- Example: Phase 2.1-2.3 collapse to "Execute context gathering: completed"
|
||||
- **Phase 4**: No collapse needed (single task, just mark completed)
|
||||
- Maintains clean orchestrator-level view
|
||||
|
||||
3. **Continuous Execution**:
|
||||
- After collapse, automatically proceed to next pending phase
|
||||
- After completion, automatically proceed to next pending phase
|
||||
- No user intervention required between phases
|
||||
- TodoWrite dynamically reflects current execution state
|
||||
|
||||
**Lifecycle Summary**: Initial pending tasks → Phase invoked (tasks ATTACHED) → Sub-tasks executed sequentially → Phase completed (tasks COLLAPSED to summary) → Next phase begins → Repeat until all phases complete.
|
||||
**Lifecycle Summary**: Initial pending tasks → Phase invoked (tasks ATTACHED) → Sub-tasks executed sequentially → Phase completed (tasks COLLAPSED to summary for Phase 2/3, or marked completed for Phase 4) → Next phase begins → Repeat until all phases complete.
|
||||
|
||||
### Benefits
|
||||
|
||||
- ✓ Real-time visibility into sub-task execution
|
||||
- ✓ Clear mental model: SlashCommand = attach → execute → collapse
|
||||
- ✓ Clear mental model: SlashCommand = attach → execute → collapse (Phase 2/3) or complete (Phase 4)
|
||||
- ✓ Clean summary after completion
|
||||
- ✓ Easy to track workflow progress
|
||||
|
||||
**Note**: See individual Phase descriptions (Phase 2, 3, 4) for detailed TodoWrite Update examples with full JSON structures.
|
||||
**Note**: See individual Phase descriptions for detailed TodoWrite Update examples:
|
||||
- **Phase 2, 3**: Multiple sub-tasks with attach/collapse pattern
|
||||
- **Phase 4**: Single agent task (no collapse needed)
|
||||
|
||||
## Input Processing
|
||||
|
||||
@@ -425,20 +425,21 @@ Conditional Branch: Check conflict_risk
|
||||
└─ ELSE: Skip Phase 3, proceed to Phase 4
|
||||
↓
|
||||
Phase 4: Task Generation (SlashCommand invoked)
|
||||
→ ATTACH 3 tasks: ← ATTACHED
|
||||
- Phase 4.1: Discovery - analyze requirements
|
||||
- Phase 4.2: Planning - design tasks
|
||||
- Phase 4.3: Output - generate JSONs
|
||||
→ Execute Phase 4.1-4.3
|
||||
→ COLLAPSE tasks ← COLLAPSED
|
||||
→ ATTACH 1 agent task: ← ATTACHED
|
||||
- Execute task-generate-agent
|
||||
→ Agent autonomously completes internally:
|
||||
(discovery → planning → output)
|
||||
→ Outputs: IMPL_PLAN.md, IMPL-*.json, TODO_LIST.md
|
||||
↓
|
||||
Return summary to user
|
||||
```
|
||||
|
||||
**Key Points**:
|
||||
- **← ATTACHED**: Sub-tasks attached to TodoWrite when SlashCommand invoked
|
||||
- **← COLLAPSED**: Sub-tasks collapsed to summary after completion
|
||||
- **← ATTACHED**: Tasks attached to TodoWrite when SlashCommand invoked
|
||||
- Phase 2, 3: Multiple sub-tasks
|
||||
- Phase 4: Single agent task
|
||||
- **← COLLAPSED**: Sub-tasks collapsed to summary after completion (Phase 2, 3 only)
|
||||
- **Phase 4**: Single agent task, no collapse (just mark completed)
|
||||
- **Conditional Branch**: Phase 3 only executes if conflict_risk ≥ medium
|
||||
- **Continuous Flow**: No user intervention between phases
|
||||
|
||||
|
||||
@@ -1,105 +0,0 @@
|
||||
---
|
||||
name: resume
|
||||
description: Resume paused workflow session with automatic progress analysis, pending task identification, and conflict detection
|
||||
argument-hint: "session-id for workflow session to resume"
|
||||
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
|
||||
---
|
||||
|
||||
# Sequential Workflow Resume Command
|
||||
|
||||
## Usage
|
||||
```bash
|
||||
/workflow:resume "<session-id>"
|
||||
```
|
||||
|
||||
## Purpose
|
||||
**Sequential command coordination for workflow resumption** by first analyzing current session status, then continuing execution with special resume context. This command orchestrates intelligent session resumption through two-step process.
|
||||
|
||||
## Command Coordination Workflow
|
||||
|
||||
### Phase 1: Status Analysis
|
||||
1. **Call status command**: Execute `/workflow:status` to analyze current session state
|
||||
2. **Verify session information**: Check session ID, progress, and current task status
|
||||
3. **Identify resume point**: Determine where workflow was interrupted
|
||||
|
||||
### Phase 2: Resume Execution
|
||||
1. **Call execute with resume flag**: Execute `/workflow:execute --resume-session="{session-id}"`
|
||||
2. **Pass session context**: Provide analyzed session information to execute command
|
||||
3. **Direct agent execution**: Skip discovery phase, directly enter TodoWrite and agent execution
|
||||
|
||||
## Implementation Protocol
|
||||
|
||||
### Sequential Command Execution
|
||||
```bash
|
||||
# Phase 1: Analyze current session status
|
||||
SlashCommand(command="/workflow:status")
|
||||
|
||||
# Phase 2: Resume execution with special flag
|
||||
SlashCommand(command="/workflow:execute --resume-session=\"{session-id}\"")
|
||||
```
|
||||
|
||||
### Progress Tracking
|
||||
```javascript
|
||||
TodoWrite({
|
||||
todos: [
|
||||
{
|
||||
content: "Analyze current session status and progress",
|
||||
status: "in_progress",
|
||||
activeForm: "Analyzing session status"
|
||||
},
|
||||
{
|
||||
content: "Resume workflow execution with session context",
|
||||
status: "pending",
|
||||
activeForm: "Resuming workflow execution"
|
||||
}
|
||||
]
|
||||
});
|
||||
```
|
||||
|
||||
## Resume Information Flow
|
||||
|
||||
### Status Analysis Results
|
||||
The `/workflow:status` command provides:
|
||||
- **Session ID**: Current active session identifier
|
||||
- **Current Progress**: Completed, in-progress, and pending tasks
|
||||
- **Interruption Point**: Last executed task and next pending task
|
||||
- **Session State**: Overall workflow status
|
||||
|
||||
### Execute Command Context
|
||||
The special `--resume-session` flag tells `/workflow:execute`:
|
||||
- **Skip Discovery**: Don't search for sessions, use provided session ID
|
||||
- **Direct Execution**: Go straight to TodoWrite generation and agent launching
|
||||
- **Context Restoration**: Use existing session state and summaries
|
||||
- **Resume Point**: Continue from identified interruption point
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Session Validation Failures
|
||||
- **Session not found**: Report missing session, suggest available sessions
|
||||
- **Session inactive**: Recommend activating session first
|
||||
- **Status command fails**: Retry once, then report analysis failure
|
||||
|
||||
### Execute Resumption Failures
|
||||
- **No pending tasks**: Report workflow completion status
|
||||
- **Execute command fails**: Report resumption failure, suggest manual intervention
|
||||
|
||||
## Success Criteria
|
||||
1. **Status analysis complete**: Session state properly analyzed and reported
|
||||
2. **Execute command launched**: Resume execution started with proper context
|
||||
3. **Agent coordination**: TodoWrite and agent execution initiated successfully
|
||||
4. **Context preservation**: Session state and progress properly maintained
|
||||
|
||||
## Related Commands
|
||||
|
||||
**Prerequisite Commands**:
|
||||
- `/workflow:plan` or `/workflow:execute` - Workflow must be in progress or paused
|
||||
|
||||
**Called by This Command** (2 phases):
|
||||
- `/workflow:status` - Phase 1: Analyze current session status and identify resume point
|
||||
- `/workflow:execute` - Phase 2: Resume execution with `--resume-session` flag
|
||||
|
||||
**Follow-up Commands**:
|
||||
- None - Workflow continues automatically via `/workflow:execute`
|
||||
|
||||
---
|
||||
*Sequential command coordination for workflow session resumption*
|
||||
@@ -1,380 +0,0 @@
|
||||
---
|
||||
name: capture
|
||||
description: Batch screenshot capture for UI design workflows using MCP puppeteer or local fallback with URL mapping
|
||||
argument-hint: --url-map "target:url,..." [--design-id <id>] [--session <id>]
|
||||
allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*), ListMcpResourcesTool(*), mcp__chrome-devtools__*, mcp__playwright__*
|
||||
---
|
||||
|
||||
# Batch Screenshot Capture (/workflow:ui-design:capture)
|
||||
|
||||
## Overview
|
||||
Batch screenshot tool with MCP-first strategy and multi-tier fallback. Processes multiple URLs in parallel.
|
||||
|
||||
**Strategy**: MCP → Playwright → Chrome → Manual
|
||||
**Output**: Flat structure `screenshots/{target}.png`
|
||||
|
||||
## Phase 1: Initialize & Parse
|
||||
|
||||
### Step 1: Determine Base Path & Generate Design ID
|
||||
```bash
|
||||
# Priority: --design-id > session (latest) > standalone (create new)
|
||||
if [ -n "$DESIGN_ID" ]; then
|
||||
# Use provided design ID
|
||||
relative_path=$(find .workflow -name "${DESIGN_ID}" -type d -print -quit)
|
||||
if [ -z "$relative_path" ]; then
|
||||
echo "ERROR: Design run not found: $DESIGN_ID"
|
||||
echo "HINT: Run '/workflow:ui-design:list' to see available design runs"
|
||||
exit 1
|
||||
fi
|
||||
elif [ -n "$SESSION_ID" ]; then
|
||||
# Find latest in session or create new
|
||||
relative_path=$(find .workflow/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
|
||||
if [ -z "$relative_path" ]; then
|
||||
design_id="design-run-$(date +%Y%m%d)-$RANDOM"
|
||||
relative_path=".workflow/WFS-$SESSION_ID/${design_id}"
|
||||
fi
|
||||
else
|
||||
# Create new standalone design run
|
||||
design_id="design-run-$(date +%Y%m%d)-$RANDOM"
|
||||
relative_path=".workflow/${design_id}"
|
||||
fi
|
||||
|
||||
# Create directory and convert to absolute path
|
||||
bash(mkdir -p "$relative_path"/screenshots)
|
||||
base_path=$(cd "$relative_path" && pwd)
|
||||
|
||||
# Extract and display design_id
|
||||
design_id=$(basename "$base_path")
|
||||
echo "✓ Design ID: $design_id"
|
||||
echo "✓ Base path: $base_path"
|
||||
```
|
||||
|
||||
### Step 2: Parse URL Map
|
||||
```javascript
|
||||
// Input: "home:https://linear.app, pricing:https://linear.app/pricing"
|
||||
url_entries = []
|
||||
|
||||
FOR pair IN split(params["--url-map"], ","):
|
||||
parts = pair.split(":", 1)
|
||||
|
||||
IF len(parts) != 2:
|
||||
ERROR: "Invalid format: {pair}. Expected: 'target:url'"
|
||||
EXIT 1
|
||||
|
||||
target = parts[0].strip().lower().replace(" ", "-")
|
||||
url = parts[1].strip()
|
||||
|
||||
// Validate target name
|
||||
IF NOT regex_match(target, r"^[a-z0-9][a-z0-9_-]*$"):
|
||||
ERROR: "Invalid target: {target}"
|
||||
EXIT 1
|
||||
|
||||
// Add https:// if missing
|
||||
IF NOT url.startswith("http"):
|
||||
url = f"https://{url}"
|
||||
|
||||
url_entries.append({target, url})
|
||||
```
|
||||
|
||||
**Output**: `base_path`, `url_entries[]`
|
||||
|
||||
### Step 3: Initialize Todos
|
||||
```javascript
|
||||
TodoWrite({todos: [
|
||||
{content: "Parse url-map", status: "completed", activeForm: "Parsing"},
|
||||
{content: "Detect MCP tools", status: "in_progress", activeForm: "Detecting"},
|
||||
{content: "Capture screenshots", status: "pending", activeForm: "Capturing"},
|
||||
{content: "Verify results", status: "pending", activeForm: "Verifying"}
|
||||
]})
|
||||
```
|
||||
|
||||
## Phase 2: Detect Screenshot Tools
|
||||
|
||||
### Step 1: Check MCP Availability
|
||||
```javascript
|
||||
// List available MCP servers
|
||||
all_resources = ListMcpResourcesTool()
|
||||
available_servers = unique([r.server for r in all_resources])
|
||||
|
||||
// Check Chrome DevTools MCP
|
||||
chrome_devtools = "chrome-devtools" IN available_servers
|
||||
chrome_screenshot = check_tool_exists("mcp__chrome-devtools__take_screenshot")
|
||||
|
||||
// Check Playwright MCP
|
||||
playwright_mcp = "playwright" IN available_servers
|
||||
playwright_screenshot = check_tool_exists("mcp__playwright__screenshot")
|
||||
|
||||
// Determine primary tool
|
||||
IF chrome_devtools AND chrome_screenshot:
|
||||
tool = "chrome-devtools"
|
||||
ELSE IF playwright_mcp AND playwright_screenshot:
|
||||
tool = "playwright"
|
||||
ELSE:
|
||||
tool = null
|
||||
```
|
||||
|
||||
**Output**: `tool` (chrome-devtools | playwright | null)
|
||||
|
||||
### Step 2: Check Local Fallback
|
||||
```bash
|
||||
# Only if MCP unavailable
|
||||
bash(which playwright 2>/dev/null || echo "")
|
||||
bash(which google-chrome || which chrome || which chromium 2>/dev/null || echo "")
|
||||
```
|
||||
|
||||
**Output**: `local_tools[]`
|
||||
|
||||
## Phase 3: Capture Screenshots
|
||||
|
||||
### Screenshot Format Options
|
||||
|
||||
**PNG Format** (default, lossless):
|
||||
- **Pros**: Lossless quality, best for detailed UI screenshots
|
||||
- **Cons**: Larger file sizes (typically 200-500 KB per screenshot)
|
||||
- **Parameters**: `format: "png"` (no quality parameter)
|
||||
- **Use case**: High-fidelity UI replication, design system extraction
|
||||
|
||||
**WebP Format** (optional, lossy/lossless):
|
||||
- **Pros**: Smaller file sizes with good quality (50-70% smaller than PNG)
|
||||
- **Cons**: Requires quality parameter, slight quality loss at high compression
|
||||
- **Parameters**: `format: "webp", quality: 90` (80-100 recommended)
|
||||
- **Use case**: Batch captures, network-constrained environments
|
||||
|
||||
**JPEG Format** (optional, lossy):
|
||||
- **Pros**: Smallest file sizes
|
||||
- **Cons**: Lossy compression, not recommended for UI screenshots
|
||||
- **Parameters**: `format: "jpeg", quality: 90`
|
||||
- **Use case**: Photo-heavy pages, not recommended for UI design
|
||||
|
||||
### Step 1: MCP Capture (If Available)
|
||||
```javascript
|
||||
IF tool == "chrome-devtools":
|
||||
// Get or create page
|
||||
pages = mcp__chrome-devtools__list_pages()
|
||||
|
||||
IF pages.length == 0:
|
||||
mcp__chrome-devtools__new_page({url: url_entries[0].url})
|
||||
page_idx = 0
|
||||
ELSE:
|
||||
page_idx = 0
|
||||
|
||||
mcp__chrome-devtools__select_page({pageIdx: page_idx})
|
||||
|
||||
// Capture each URL
|
||||
FOR entry IN url_entries:
|
||||
mcp__chrome-devtools__navigate_page({url: entry.url, timeout: 30000})
|
||||
bash(sleep 2)
|
||||
|
||||
// PNG format doesn't support quality parameter
|
||||
// Use PNG for lossless quality (larger files)
|
||||
mcp__chrome-devtools__take_screenshot({
|
||||
fullPage: true,
|
||||
format: "png",
|
||||
filePath: f"{base_path}/screenshots/{entry.target}.png"
|
||||
})
|
||||
|
||||
// Alternative: Use WebP with quality for smaller files
|
||||
// mcp__chrome-devtools__take_screenshot({
|
||||
// fullPage: true,
|
||||
// format: "webp",
|
||||
// quality: 90,
|
||||
// filePath: f"{base_path}/screenshots/{entry.target}.webp"
|
||||
// })
|
||||
|
||||
ELSE IF tool == "playwright":
|
||||
FOR entry IN url_entries:
|
||||
mcp__playwright__screenshot({
|
||||
url: entry.url,
|
||||
output_path: f"{base_path}/screenshots/{entry.target}.png",
|
||||
full_page: true,
|
||||
timeout: 30000
|
||||
})
|
||||
```
|
||||
|
||||
### Step 2: Local Fallback (If MCP Failed)
|
||||
```bash
|
||||
# Try Playwright CLI
|
||||
bash(playwright screenshot "$url" "$output_file" --full-page --timeout 30000)
|
||||
|
||||
# Try Chrome headless
|
||||
bash($chrome --headless --screenshot="$output_file" --window-size=1920,1080 "$url")
|
||||
```
|
||||
|
||||
### Step 3: Manual Mode (If All Failed)
|
||||
```
|
||||
⚠️ Manual Screenshot Required
|
||||
|
||||
Failed URLs:
|
||||
home: https://linear.app
|
||||
Save to: .workflow/design-run-20250110/screenshots/home.png
|
||||
|
||||
Steps:
|
||||
1. Visit URL in browser
|
||||
2. Take full-page screenshot
|
||||
3. Save to path above
|
||||
4. Type 'ready' to continue
|
||||
|
||||
Options: ready | skip | abort
|
||||
```
|
||||
|
||||
## Phase 4: Verification
|
||||
|
||||
### Step 1: Scan Captured Files
|
||||
```bash
|
||||
bash(ls -1 $base_path/screenshots/*.{png,jpg,jpeg,webp} 2>/dev/null)
|
||||
bash(du -h $base_path/screenshots/*.png 2>/dev/null)
|
||||
```
|
||||
|
||||
### Step 2: Generate Metadata
|
||||
```javascript
|
||||
captured_files = Glob(f"{base_path}/screenshots/*.{{png,jpg,jpeg,webp}}")
|
||||
captured_targets = [basename_no_ext(f) for f in captured_files]
|
||||
|
||||
metadata = {
|
||||
"timestamp": current_timestamp(),
|
||||
"total_requested": len(url_entries),
|
||||
"total_captured": len(captured_targets),
|
||||
"screenshots": []
|
||||
}
|
||||
|
||||
FOR entry IN url_entries:
|
||||
is_captured = entry.target IN captured_targets
|
||||
|
||||
metadata.screenshots.append({
|
||||
"target": entry.target,
|
||||
"url": entry.url,
|
||||
"captured": is_captured,
|
||||
"path": f"{base_path}/screenshots/{entry.target}.png" IF is_captured ELSE null,
|
||||
"size_kb": file_size_kb IF is_captured ELSE null
|
||||
})
|
||||
|
||||
Write(f"{base_path}/screenshots/capture-metadata.json", JSON.stringify(metadata))
|
||||
```
|
||||
|
||||
**Output**: `capture-metadata.json`
|
||||
|
||||
## Completion
|
||||
|
||||
### Todo Update
|
||||
```javascript
|
||||
TodoWrite({todos: [
|
||||
{content: "Parse url-map", status: "completed", activeForm: "Parsing"},
|
||||
{content: "Detect MCP tools", status: "completed", activeForm: "Detecting"},
|
||||
{content: "Capture screenshots", status: "completed", activeForm: "Capturing"},
|
||||
{content: "Verify results", status: "completed", activeForm: "Verifying"}
|
||||
]})
|
||||
```
|
||||
|
||||
### Output Message
|
||||
```
|
||||
✅ Batch screenshot capture complete!
|
||||
|
||||
Summary:
|
||||
- Requested: {total_requested}
|
||||
- Captured: {total_captured}
|
||||
- Success rate: {success_rate}%
|
||||
- Method: {tool || "Local fallback"}
|
||||
|
||||
Output:
|
||||
{base_path}/screenshots/
|
||||
├── home.png (245.3 KB)
|
||||
├── pricing.png (198.7 KB)
|
||||
└── capture-metadata.json
|
||||
|
||||
Next: /workflow:ui-design:extract --images "screenshots/*.png"
|
||||
```
|
||||
|
||||
## Simple Bash Commands
|
||||
|
||||
### Path Operations
|
||||
```bash
|
||||
# Find design directory
|
||||
bash(find .workflow -type d -name "design-run-*" | head -1)
|
||||
|
||||
# Create screenshot directory
|
||||
bash(mkdir -p $BASE_PATH/screenshots)
|
||||
```
|
||||
|
||||
### Tool Detection
|
||||
```bash
|
||||
# Check MCP
|
||||
all_resources = ListMcpResourcesTool()
|
||||
|
||||
# Check local tools
|
||||
bash(which playwright 2>/dev/null)
|
||||
bash(which google-chrome 2>/dev/null)
|
||||
```
|
||||
|
||||
### Verification
|
||||
```bash
|
||||
# List captures
|
||||
bash(ls -1 $base_path/screenshots/*.png 2>/dev/null)
|
||||
|
||||
# File sizes
|
||||
bash(du -h $base_path/screenshots/*.png)
|
||||
```
|
||||
|
||||
## Output Structure
|
||||
|
||||
```
|
||||
{base_path}/
|
||||
└── screenshots/
|
||||
├── home.png
|
||||
├── pricing.png
|
||||
├── about.png
|
||||
└── capture-metadata.json
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Common Errors
|
||||
```
|
||||
ERROR: Invalid url-map format
|
||||
→ Use: "target:url, target2:url2"
|
||||
|
||||
ERROR: png screenshots do not support 'quality'
|
||||
→ PNG format is lossless, no quality parameter needed
|
||||
→ Remove quality parameter OR switch to webp/jpeg format
|
||||
|
||||
ERROR: MCP unavailable
|
||||
→ Using local fallback
|
||||
|
||||
ERROR: All tools failed
|
||||
→ Manual mode activated
|
||||
```
|
||||
|
||||
### Format-Specific Errors
|
||||
```
|
||||
❌ Wrong: format: "png", quality: 90
|
||||
✅ Right: format: "png"
|
||||
|
||||
✅ Or use: format: "webp", quality: 90
|
||||
✅ Or use: format: "jpeg", quality: 90
|
||||
```
|
||||
|
||||
### Recovery
|
||||
- **Partial success**: Keep successful captures
|
||||
- **Retry**: Re-run with failed targets only
|
||||
- **Manual**: Follow interactive guidance
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
- [ ] All requested URLs processed
|
||||
- [ ] File sizes > 1KB (valid images)
|
||||
- [ ] Metadata JSON generated
|
||||
- [ ] No missing targets (or documented)
|
||||
|
||||
## Key Features
|
||||
|
||||
- **MCP-first**: Prioritize managed tools
|
||||
- **Multi-tier fallback**: 4 layers (MCP → Local → Manual)
|
||||
- **Batch processing**: Parallel capture
|
||||
- **Error tolerance**: Partial failures handled
|
||||
- **Structured output**: Flat, predictable
|
||||
|
||||
## Integration
|
||||
|
||||
**Input**: `--url-map` (multiple target:url pairs)
|
||||
**Output**: `screenshots/*.png` + `capture-metadata.json`
|
||||
**Called by**: `/workflow:ui-design:imitate-auto`, `/workflow:ui-design:explore-auto`
|
||||
**Next**: `/workflow:ui-design:extract` or `/workflow:ui-design:explore-layers`
|
||||
@@ -1,11 +1,11 @@
|
||||
---
|
||||
name: update
|
||||
description: Update brainstorming artifacts with finalized design system references from selected prototypes
|
||||
name: design-sync
|
||||
description: Synchronize finalized design system references to brainstorming artifacts, preparing them for /workflow:plan consumption
|
||||
argument-hint: --session <session_id> [--selected-prototypes "<list>"]
|
||||
allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
|
||||
---
|
||||
|
||||
# Design Update Command
|
||||
# Design Sync Command
|
||||
|
||||
## Overview
|
||||
|
||||
@@ -349,15 +349,3 @@ After update, verify:
|
||||
- **Next Phase**: `/workflow:plan` discovers and utilizes design system through @ references
|
||||
- **Auto Integration**: Automatically triggered by `/workflow:ui-design:auto` workflow
|
||||
|
||||
## Why Main Claude Execution?
|
||||
|
||||
This command is executed directly by main Claude (not delegated to an Agent) because:
|
||||
|
||||
1. **Simple Reference Generation**: Only generating file paths, not complex synthesis
|
||||
2. **Context Preservation**: Main Claude has full session and conversation context
|
||||
3. **Minimal Transformation**: Primarily updating references, not analyzing content
|
||||
4. **Path Resolution**: Requires precise relative path calculation
|
||||
5. **Edit Operations**: Better error recovery for Edit conflicts
|
||||
6. **Synthesis Pattern**: Follows same direct-execution pattern as other reference updates
|
||||
|
||||
This ensures reliable, lightweight integration without Agent handoff overhead.
|
||||
@@ -1,611 +0,0 @@
|
||||
---
|
||||
name: explore-layers
|
||||
description: Interactive deep UI capture with depth-controlled layer exploration using MCP puppeteer
|
||||
argument-hint: --url <url> --depth <1-5> [--design-id <id>] [--session <id>]
|
||||
allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*), mcp__chrome-devtools__*
|
||||
---
|
||||
|
||||
# Interactive Layer Exploration (/workflow:ui-design:explore-layers)
|
||||
|
||||
## Overview
|
||||
Single-URL depth-controlled interactive capture. Progressively explores UI layers from pages to Shadow DOM.
|
||||
|
||||
**Depth Levels**:
|
||||
- `1` = Page (full-page screenshot)
|
||||
- `2` = Elements (key components)
|
||||
- `3` = Interactions (modals, dropdowns)
|
||||
- `4` = Embedded (iframes, widgets)
|
||||
- `5` = Shadow DOM (web components)
|
||||
|
||||
**Requirements**: Chrome DevTools MCP
|
||||
|
||||
## Phase 1: Setup & Validation
|
||||
|
||||
### Step 1: Parse Parameters
|
||||
```javascript
|
||||
url = params["--url"]
|
||||
depth = int(params["--depth"])
|
||||
|
||||
// Validate URL
|
||||
IF NOT url.startswith("http"):
|
||||
url = f"https://{url}"
|
||||
|
||||
// Validate depth
|
||||
IF depth NOT IN [1, 2, 3, 4, 5]:
|
||||
ERROR: "Invalid depth: {depth}. Use 1-5"
|
||||
EXIT 1
|
||||
```
|
||||
|
||||
### Step 2: Determine Base Path
|
||||
```bash
|
||||
# Priority: --design-id > --session > create new
|
||||
if [ -n "$DESIGN_ID" ]; then
|
||||
# Exact match by design ID
|
||||
relative_path=$(find .workflow -name "${DESIGN_ID}" -type d -print -quit)
|
||||
if [ -z "$relative_path" ]; then
|
||||
echo "ERROR: Design run not found: $DESIGN_ID"
|
||||
echo "HINT: Run '/workflow:ui-design:list' to see available design runs"
|
||||
exit 1
|
||||
fi
|
||||
elif [ -n "$SESSION_ID" ]; then
|
||||
# Find latest in session or create new
|
||||
relative_path=$(find .workflow/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
|
||||
if [ -z "$relative_path" ]; then
|
||||
design_id="design-run-$(date +%Y%m%d)-$RANDOM"
|
||||
relative_path=".workflow/WFS-$SESSION_ID/${design_id}"
|
||||
fi
|
||||
else
|
||||
# Create new standalone design run
|
||||
design_id="design-run-$(date +%Y%m%d)-$RANDOM"
|
||||
relative_path=".workflow/${design_id}"
|
||||
fi
|
||||
|
||||
# Create directory structure and convert to absolute path
|
||||
bash(mkdir -p "$relative_path")
|
||||
base_path=$(cd "$relative_path" && pwd)
|
||||
|
||||
# Extract and display design_id
|
||||
design_id=$(basename "$base_path")
|
||||
echo "✓ Design ID: $design_id"
|
||||
echo "✓ Base path: $base_path"
|
||||
|
||||
# Create depth directories
|
||||
bash(for i in $(seq 1 $depth); do mkdir -p "$base_path"/screenshots/depth-$i; done)
|
||||
```
|
||||
|
||||
**Output**: `url`, `depth`, `base_path`
|
||||
|
||||
### Step 3: Validate MCP Availability
|
||||
```javascript
|
||||
all_resources = ListMcpResourcesTool()
|
||||
chrome_devtools = "chrome-devtools" IN [r.server for r in all_resources]
|
||||
|
||||
IF NOT chrome_devtools:
|
||||
ERROR: "explore-layers requires Chrome DevTools MCP"
|
||||
ERROR: "Install: npm i -g @modelcontextprotocol/server-chrome-devtools"
|
||||
EXIT 1
|
||||
```
|
||||
|
||||
### Step 4: Initialize Todos
|
||||
```javascript
|
||||
todos = [
|
||||
{content: "Setup and validation", status: "completed", activeForm: "Setting up"}
|
||||
]
|
||||
|
||||
FOR level IN range(1, depth + 1):
|
||||
todos.append({
|
||||
content: f"Depth {level}: {DEPTH_NAMES[level]}",
|
||||
status: "pending",
|
||||
activeForm: f"Capturing depth {level}"
|
||||
})
|
||||
|
||||
todos.append({content: "Generate layer map", status: "pending", activeForm: "Mapping"})
|
||||
|
||||
TodoWrite({todos})
|
||||
```
|
||||
|
||||
## Phase 2: Navigate & Load Page
|
||||
|
||||
### Step 1: Get or Create Browser Page
|
||||
```javascript
|
||||
pages = mcp__chrome-devtools__list_pages()
|
||||
|
||||
IF pages.length == 0:
|
||||
mcp__chrome-devtools__new_page({url: url, timeout: 30000})
|
||||
page_idx = 0
|
||||
ELSE:
|
||||
page_idx = 0
|
||||
mcp__chrome-devtools__select_page({pageIdx: page_idx})
|
||||
mcp__chrome-devtools__navigate_page({url: url, timeout: 30000})
|
||||
|
||||
bash(sleep 3) // Wait for page load
|
||||
```
|
||||
|
||||
**Output**: `page_idx`
|
||||
|
||||
## Phase 3: Depth 1 - Page Level
|
||||
|
||||
### Step 1: Capture Full Page
|
||||
```javascript
|
||||
TodoWrite(mark_in_progress: "Depth 1: Page")
|
||||
|
||||
output_file = f"{base_path}/screenshots/depth-1/full-page.png"
|
||||
|
||||
mcp__chrome-devtools__take_screenshot({
|
||||
fullPage: true,
|
||||
format: "png",
|
||||
quality: 90,
|
||||
filePath: output_file
|
||||
})
|
||||
|
||||
layer_map = {
|
||||
"url": url,
|
||||
"depth": depth,
|
||||
"layers": {
|
||||
"depth-1": {
|
||||
"type": "page",
|
||||
"captures": [{
|
||||
"name": "full-page",
|
||||
"path": output_file,
|
||||
"size_kb": file_size_kb(output_file)
|
||||
}]
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
TodoWrite(mark_completed: "Depth 1: Page")
|
||||
```
|
||||
|
||||
**Output**: `depth-1/full-page.png`
|
||||
|
||||
## Phase 4: Depth 2 - Element Level (If depth >= 2)
|
||||
|
||||
### Step 1: Analyze Page Structure
|
||||
```javascript
|
||||
IF depth < 2: SKIP
|
||||
|
||||
TodoWrite(mark_in_progress: "Depth 2: Elements")
|
||||
|
||||
snapshot = mcp__chrome-devtools__take_snapshot()
|
||||
|
||||
// Filter key elements
|
||||
key_types = ["nav", "header", "footer", "aside", "button", "form", "article"]
|
||||
key_elements = [
|
||||
el for el in snapshot.interactiveElements
|
||||
if el.type IN key_types OR el.role IN ["navigation", "banner", "main"]
|
||||
][:10] // Limit to top 10
|
||||
```
|
||||
|
||||
### Step 2: Capture Element Screenshots
|
||||
```javascript
|
||||
depth_2_captures = []
|
||||
|
||||
FOR idx, element IN enumerate(key_elements):
|
||||
element_name = sanitize(element.text[:20] or element.type) or f"element-{idx}"
|
||||
output_file = f"{base_path}/screenshots/depth-2/{element_name}.png"
|
||||
|
||||
TRY:
|
||||
mcp__chrome-devtools__take_screenshot({
|
||||
uid: element.uid,
|
||||
format: "png",
|
||||
quality: 85,
|
||||
filePath: output_file
|
||||
})
|
||||
|
||||
depth_2_captures.append({
|
||||
"name": element_name,
|
||||
"type": element.type,
|
||||
"path": output_file,
|
||||
"size_kb": file_size_kb(output_file)
|
||||
})
|
||||
CATCH error:
|
||||
REPORT: f"Skip {element_name}: {error}"
|
||||
|
||||
layer_map.layers["depth-2"] = {
|
||||
"type": "elements",
|
||||
"captures": depth_2_captures
|
||||
}
|
||||
|
||||
TodoWrite(mark_completed: "Depth 2: Elements")
|
||||
```
|
||||
|
||||
**Output**: `depth-2/{element}.png` × N
|
||||
|
||||
## Phase 5: Depth 3 - Interaction Level (If depth >= 3)
|
||||
|
||||
### Step 1: Analyze Interactive Triggers
|
||||
```javascript
|
||||
IF depth < 3: SKIP
|
||||
|
||||
TodoWrite(mark_in_progress: "Depth 3: Interactions")
|
||||
|
||||
// Detect structure
|
||||
structure = mcp__chrome-devtools__evaluate_script({
|
||||
function: `() => ({
|
||||
modals: document.querySelectorAll('[role="dialog"], .modal').length,
|
||||
dropdowns: document.querySelectorAll('[role="menu"], .dropdown').length,
|
||||
tooltips: document.querySelectorAll('[role="tooltip"], [title]').length
|
||||
})`
|
||||
})
|
||||
|
||||
// Identify triggers
|
||||
triggers = []
|
||||
FOR element IN snapshot.interactiveElements:
|
||||
IF element.attributes CONTAINS ("data-toggle", "aria-haspopup"):
|
||||
triggers.append({
|
||||
uid: element.uid,
|
||||
type: "modal" IF "modal" IN element.classes ELSE "dropdown",
|
||||
trigger: "click",
|
||||
text: element.text
|
||||
})
|
||||
ELSE IF element.attributes CONTAINS ("title", "data-tooltip"):
|
||||
triggers.append({
|
||||
uid: element.uid,
|
||||
type: "tooltip",
|
||||
trigger: "hover",
|
||||
text: element.text
|
||||
})
|
||||
|
||||
triggers = triggers[:10] // Limit
|
||||
```
|
||||
|
||||
### Step 2: Trigger Interactions & Capture
|
||||
```javascript
|
||||
depth_3_captures = []
|
||||
|
||||
FOR idx, trigger IN enumerate(triggers):
|
||||
layer_name = f"{trigger.type}-{sanitize(trigger.text[:15]) or idx}"
|
||||
output_file = f"{base_path}/screenshots/depth-3/{layer_name}.png"
|
||||
|
||||
TRY:
|
||||
// Trigger interaction
|
||||
IF trigger.trigger == "click":
|
||||
mcp__chrome-devtools__click({uid: trigger.uid})
|
||||
ELSE:
|
||||
mcp__chrome-devtools__hover({uid: trigger.uid})
|
||||
|
||||
bash(sleep 1)
|
||||
|
||||
// Capture
|
||||
mcp__chrome-devtools__take_screenshot({
|
||||
fullPage: false, // Viewport only
|
||||
format: "png",
|
||||
quality: 90,
|
||||
filePath: output_file
|
||||
})
|
||||
|
||||
depth_3_captures.append({
|
||||
"name": layer_name,
|
||||
"type": trigger.type,
|
||||
"trigger_method": trigger.trigger,
|
||||
"path": output_file,
|
||||
"size_kb": file_size_kb(output_file)
|
||||
})
|
||||
|
||||
// Dismiss (ESC key)
|
||||
mcp__chrome-devtools__evaluate_script({
|
||||
function: `() => {
|
||||
document.dispatchEvent(new KeyboardEvent('keydown', {key: 'Escape'}));
|
||||
}`
|
||||
})
|
||||
bash(sleep 0.5)
|
||||
|
||||
CATCH error:
|
||||
REPORT: f"Skip {layer_name}: {error}"
|
||||
|
||||
layer_map.layers["depth-3"] = {
|
||||
"type": "interactions",
|
||||
"triggers": structure,
|
||||
"captures": depth_3_captures
|
||||
}
|
||||
|
||||
TodoWrite(mark_completed: "Depth 3: Interactions")
|
||||
```
|
||||
|
||||
**Output**: `depth-3/{interaction}.png` × N
|
||||
|
||||
## Phase 6: Depth 4 - Embedded Level (If depth >= 4)
|
||||
|
||||
### Step 1: Detect Iframes
|
||||
```javascript
|
||||
IF depth < 4: SKIP
|
||||
|
||||
TodoWrite(mark_in_progress: "Depth 4: Embedded")
|
||||
|
||||
iframes = mcp__chrome-devtools__evaluate_script({
|
||||
function: `() => {
|
||||
return Array.from(document.querySelectorAll('iframe')).map(iframe => ({
|
||||
src: iframe.src,
|
||||
id: iframe.id || 'iframe',
|
||||
title: iframe.title || 'untitled'
|
||||
})).filter(i => i.src && i.src.startsWith('http'));
|
||||
}`
|
||||
})
|
||||
```
|
||||
|
||||
### Step 2: Capture Iframe Content
|
||||
```javascript
|
||||
depth_4_captures = []
|
||||
|
||||
FOR idx, iframe IN enumerate(iframes):
|
||||
iframe_name = f"iframe-{sanitize(iframe.title or iframe.id)}-{idx}"
|
||||
output_file = f"{base_path}/screenshots/depth-4/{iframe_name}.png"
|
||||
|
||||
TRY:
|
||||
// Navigate to iframe URL in new tab
|
||||
mcp__chrome-devtools__new_page({url: iframe.src, timeout: 30000})
|
||||
bash(sleep 2)
|
||||
|
||||
mcp__chrome-devtools__take_screenshot({
|
||||
fullPage: true,
|
||||
format: "png",
|
||||
quality: 90,
|
||||
filePath: output_file
|
||||
})
|
||||
|
||||
depth_4_captures.append({
|
||||
"name": iframe_name,
|
||||
"url": iframe.src,
|
||||
"path": output_file,
|
||||
"size_kb": file_size_kb(output_file)
|
||||
})
|
||||
|
||||
// Close iframe tab
|
||||
current_pages = mcp__chrome-devtools__list_pages()
|
||||
mcp__chrome-devtools__close_page({pageIdx: current_pages.length - 1})
|
||||
|
||||
CATCH error:
|
||||
REPORT: f"Skip {iframe_name}: {error}"
|
||||
|
||||
layer_map.layers["depth-4"] = {
|
||||
"type": "embedded",
|
||||
"captures": depth_4_captures
|
||||
}
|
||||
|
||||
TodoWrite(mark_completed: "Depth 4: Embedded")
|
||||
```
|
||||
|
||||
**Output**: `depth-4/iframe-*.png` × N
|
||||
|
||||
## Phase 7: Depth 5 - Shadow DOM (If depth = 5)
|
||||
|
||||
### Step 1: Detect Shadow Roots
|
||||
```javascript
|
||||
IF depth < 5: SKIP
|
||||
|
||||
TodoWrite(mark_in_progress: "Depth 5: Shadow DOM")
|
||||
|
||||
shadow_elements = mcp__chrome-devtools__evaluate_script({
|
||||
function: `() => {
|
||||
const elements = Array.from(document.querySelectorAll('*'));
|
||||
return elements
|
||||
.filter(el => el.shadowRoot)
|
||||
.map((el, idx) => ({
|
||||
tag: el.tagName.toLowerCase(),
|
||||
id: el.id || \`shadow-\${idx}\`,
|
||||
innerHTML: el.shadowRoot.innerHTML.substring(0, 100)
|
||||
}));
|
||||
}`
|
||||
})
|
||||
```
|
||||
|
||||
### Step 2: Capture Shadow DOM Components
|
||||
```javascript
|
||||
depth_5_captures = []
|
||||
|
||||
FOR idx, shadow IN enumerate(shadow_elements):
|
||||
shadow_name = f"shadow-{sanitize(shadow.id)}"
|
||||
output_file = f"{base_path}/screenshots/depth-5/{shadow_name}.png"
|
||||
|
||||
TRY:
|
||||
// Inject highlight script
|
||||
mcp__chrome-devtools__evaluate_script({
|
||||
function: `() => {
|
||||
const el = document.querySelector('${shadow.tag}${shadow.id ? "#" + shadow.id : ""}');
|
||||
if (el) {
|
||||
el.scrollIntoView({behavior: 'smooth', block: 'center'});
|
||||
el.style.outline = '3px solid red';
|
||||
}
|
||||
}`
|
||||
})
|
||||
|
||||
bash(sleep 0.5)
|
||||
|
||||
// Full-page screenshot (component highlighted)
|
||||
mcp__chrome-devtools__take_screenshot({
|
||||
fullPage: false,
|
||||
format: "png",
|
||||
quality: 90,
|
||||
filePath: output_file
|
||||
})
|
||||
|
||||
depth_5_captures.append({
|
||||
"name": shadow_name,
|
||||
"tag": shadow.tag,
|
||||
"path": output_file,
|
||||
"size_kb": file_size_kb(output_file)
|
||||
})
|
||||
|
||||
CATCH error:
|
||||
REPORT: f"Skip {shadow_name}: {error}"
|
||||
|
||||
layer_map.layers["depth-5"] = {
|
||||
"type": "shadow-dom",
|
||||
"captures": depth_5_captures
|
||||
}
|
||||
|
||||
TodoWrite(mark_completed: "Depth 5: Shadow DOM")
|
||||
```
|
||||
|
||||
**Output**: `depth-5/shadow-*.png` × N
|
||||
|
||||
## Phase 8: Generate Layer Map
|
||||
|
||||
### Step 1: Compile Metadata
|
||||
```javascript
|
||||
TodoWrite(mark_in_progress: "Generate layer map")
|
||||
|
||||
// Calculate totals
|
||||
total_captures = sum(len(layer.captures) for layer in layer_map.layers.values())
|
||||
total_size_kb = sum(
|
||||
sum(c.size_kb for c in layer.captures)
|
||||
for layer in layer_map.layers.values()
|
||||
)
|
||||
|
||||
layer_map["summary"] = {
|
||||
"timestamp": current_timestamp(),
|
||||
"total_depth": depth,
|
||||
"total_captures": total_captures,
|
||||
"total_size_kb": total_size_kb
|
||||
}
|
||||
|
||||
Write(f"{base_path}/screenshots/layer-map.json", JSON.stringify(layer_map, indent=2))
|
||||
|
||||
TodoWrite(mark_completed: "Generate layer map")
|
||||
```
|
||||
|
||||
**Output**: `layer-map.json`
|
||||
|
||||
## Completion
|
||||
|
||||
### Todo Update
|
||||
```javascript
|
||||
all_todos_completed = true
|
||||
TodoWrite({todos: all_completed_todos})
|
||||
```
|
||||
|
||||
### Output Message
|
||||
```
|
||||
✅ Interactive layer exploration complete!
|
||||
|
||||
Configuration:
|
||||
- URL: {url}
|
||||
- Max depth: {depth}
|
||||
- Layers explored: {len(layer_map.layers)}
|
||||
|
||||
Capture Summary:
|
||||
Depth 1 (Page): {depth_1_count} screenshot(s)
|
||||
Depth 2 (Elements): {depth_2_count} screenshot(s)
|
||||
Depth 3 (Interactions): {depth_3_count} screenshot(s)
|
||||
Depth 4 (Embedded): {depth_4_count} screenshot(s)
|
||||
Depth 5 (Shadow DOM): {depth_5_count} screenshot(s)
|
||||
|
||||
Total: {total_captures} captures ({total_size_kb:.1f} KB)
|
||||
|
||||
Output Structure:
|
||||
{base_path}/screenshots/
|
||||
├── depth-1/
|
||||
│ └── full-page.png
|
||||
├── depth-2/
|
||||
│ ├── navbar.png
|
||||
│ └── footer.png
|
||||
├── depth-3/
|
||||
│ ├── modal-login.png
|
||||
│ └── dropdown-menu.png
|
||||
├── depth-4/
|
||||
│ └── iframe-analytics.png
|
||||
├── depth-5/
|
||||
│ └── shadow-button.png
|
||||
└── layer-map.json
|
||||
|
||||
Next: /workflow:ui-design:extract --images "screenshots/**/*.png"
|
||||
```
|
||||
|
||||
## Simple Bash Commands
|
||||
|
||||
### Directory Setup
|
||||
```bash
|
||||
# Create depth directories
|
||||
bash(for i in $(seq 1 $depth); do mkdir -p $BASE_PATH/screenshots/depth-$i; done)
|
||||
```
|
||||
|
||||
### Validation
|
||||
```bash
|
||||
# Check MCP
|
||||
all_resources = ListMcpResourcesTool()
|
||||
|
||||
# Count captures per depth
|
||||
bash(ls $base_path/screenshots/depth-{1..5}/*.png 2>/dev/null | wc -l)
|
||||
```
|
||||
|
||||
### File Operations
|
||||
```bash
|
||||
# List all captures
|
||||
bash(find $base_path/screenshots -name "*.png" -type f)
|
||||
|
||||
# Total size
|
||||
bash(du -sh $base_path/screenshots)
|
||||
```
|
||||
|
||||
## Output Structure
|
||||
|
||||
```
|
||||
{base_path}/screenshots/
|
||||
├── depth-1/
|
||||
│ └── full-page.png
|
||||
├── depth-2/
|
||||
│ ├── {element}.png
|
||||
│ └── ...
|
||||
├── depth-3/
|
||||
│ ├── {interaction}.png
|
||||
│ └── ...
|
||||
├── depth-4/
|
||||
│ ├── iframe-*.png
|
||||
│ └── ...
|
||||
├── depth-5/
|
||||
│ ├── shadow-*.png
|
||||
│ └── ...
|
||||
└── layer-map.json
|
||||
```
|
||||
|
||||
## Depth Level Details
|
||||
|
||||
| Depth | Name | Captures | Time | Use Case |
|
||||
|-------|------|----------|------|----------|
|
||||
| 1 | Page | Full page | 30s | Quick preview |
|
||||
| 2 | Elements | Key components | 1-2min | Component library |
|
||||
| 3 | Interactions | Modals, dropdowns | 2-4min | UI flows |
|
||||
| 4 | Embedded | Iframes | 3-6min | Complete context |
|
||||
| 5 | Shadow DOM | Web components | 4-8min | Full coverage |
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Common Errors
|
||||
```
|
||||
ERROR: Chrome DevTools MCP required
|
||||
→ Install: npm i -g @modelcontextprotocol/server-chrome-devtools
|
||||
|
||||
ERROR: Invalid depth
|
||||
→ Use: 1-5
|
||||
|
||||
ERROR: Interaction trigger failed
|
||||
→ Some modals may be skipped, check layer-map.json
|
||||
```
|
||||
|
||||
### Recovery
|
||||
- **Partial success**: Lower depth captures preserved
|
||||
- **Trigger failures**: Interaction layer may be incomplete
|
||||
- **Iframe restrictions**: Cross-origin iframes skipped
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
- [ ] All depths up to specified level captured
|
||||
- [ ] layer-map.json generated with metadata
|
||||
- [ ] File sizes valid (> 500 bytes)
|
||||
- [ ] Interaction triggers executed
|
||||
- [ ] Shadow DOM elements highlighted
|
||||
|
||||
## Key Features
|
||||
|
||||
- **Depth-controlled**: Progressive capture 1-5 levels
|
||||
- **Interactive triggers**: Click/hover for hidden layers
|
||||
- **Iframe support**: Embedded content captured
|
||||
- **Shadow DOM**: Web component internals
|
||||
- **Structured output**: Organized by depth
|
||||
|
||||
## Integration
|
||||
|
||||
**Input**: Single URL + depth level (1-5)
|
||||
**Output**: Hierarchical screenshots + layer-map.json
|
||||
**Complements**: `/workflow:ui-design:capture` (multi-URL batch)
|
||||
**Next**: `/workflow:ui-design:extract` for design analysis
|
||||
@@ -1,174 +0,0 @@
|
||||
---
|
||||
name: list
|
||||
description: List all available design runs with metadata (session, created time, prototype count)
|
||||
argument-hint: [--session <id>]
|
||||
allowed-tools: Bash(*), Read(*)
|
||||
---
|
||||
|
||||
# List Design Runs (/workflow:ui-design:list)
|
||||
|
||||
## Overview
|
||||
List all available UI design runs across sessions or within a specific session. Displays design IDs with metadata for easy reference.
|
||||
|
||||
**Output**: Formatted list with design-id, session, created time, and prototype count
|
||||
|
||||
## Implementation
|
||||
|
||||
### Step 1: Determine Search Scope
|
||||
```bash
|
||||
# Priority: --session > all sessions
|
||||
search_path=$(if [ -n "$SESSION_ID" ]; then
|
||||
echo ".workflow/WFS-$SESSION_ID"
|
||||
else
|
||||
echo ".workflow"
|
||||
fi)
|
||||
```
|
||||
|
||||
### Step 2: Find and Display Design Runs
|
||||
```bash
|
||||
echo "Available design runs:"
|
||||
echo ""
|
||||
|
||||
# Find all design-run directories
|
||||
found_count=0
|
||||
while IFS= read -r line; do
|
||||
timestamp=$(echo "$line" | cut -d' ' -f1)
|
||||
path=$(echo "$line" | cut -d' ' -f2-)
|
||||
|
||||
# Extract design_id from path
|
||||
design_id=$(basename "$path")
|
||||
|
||||
# Extract session from path
|
||||
session_id=$(echo "$path" | grep -oP 'WFS-\K[^/]+' || echo "standalone")
|
||||
|
||||
# Format created date
|
||||
created_at=$(date -d "@${timestamp%.*}" '+%Y-%m-%d %H:%M' 2>/dev/null || echo "unknown")
|
||||
|
||||
# Count prototypes
|
||||
prototype_count=$(find "$path/prototypes" -name "*.html" 2>/dev/null | wc -l)
|
||||
|
||||
# Display formatted output
|
||||
echo " - $design_id"
|
||||
echo " Session: $session_id"
|
||||
echo " Created: $created_at"
|
||||
echo " Prototypes: $prototype_count"
|
||||
echo ""
|
||||
|
||||
found_count=$((found_count + 1))
|
||||
done < <(find "$search_path" -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr)
|
||||
|
||||
# Summary
|
||||
if [ $found_count -eq 0 ]; then
|
||||
echo " No design runs found."
|
||||
echo ""
|
||||
if [ -n "$SESSION_ID" ]; then
|
||||
echo "💡 HINT: Try running '/workflow:ui-design:explore-auto' to create a design run"
|
||||
else
|
||||
echo "💡 HINT: Try running '/workflow:ui-design:explore-auto --session <id>' to create a design run"
|
||||
fi
|
||||
else
|
||||
echo "Total: $found_count design run(s)"
|
||||
echo ""
|
||||
echo "💡 USE: /workflow:ui-design:generate --design-id \"<id>\""
|
||||
echo " OR: /workflow:ui-design:generate --session \"<session>\""
|
||||
fi
|
||||
```
|
||||
|
||||
### Step 3: Execute List Command
|
||||
```bash
|
||||
Bash(
|
||||
description: "List all UI design runs with metadata",
|
||||
command: "
|
||||
search_path=\"${search_path}\"
|
||||
SESSION_ID=\"${SESSION_ID:-}\"
|
||||
|
||||
echo 'Available design runs:'
|
||||
echo ''
|
||||
|
||||
found_count=0
|
||||
while IFS= read -r line; do
|
||||
timestamp=\$(echo \"\$line\" | cut -d' ' -f1)
|
||||
path=\$(echo \"\$line\" | cut -d' ' -f2-)
|
||||
|
||||
design_id=\$(basename \"\$path\")
|
||||
session_id=\$(echo \"\$path\" | grep -oP 'WFS-\\K[^/]+' || echo 'standalone')
|
||||
created_at=\$(date -d \"@\${timestamp%.*}\" '+%Y-%m-%d %H:%M' 2>/dev/null || echo 'unknown')
|
||||
prototype_count=\$(find \"\$path/prototypes\" -name '*.html' 2>/dev/null | wc -l)
|
||||
|
||||
echo \" - \$design_id\"
|
||||
echo \" Session: \$session_id\"
|
||||
echo \" Created: \$created_at\"
|
||||
echo \" Prototypes: \$prototype_count\"
|
||||
echo ''
|
||||
|
||||
found_count=\$((found_count + 1))
|
||||
done < <(find \"\$search_path\" -name 'design-run-*' -type d -printf '%T@ %p\\n' 2>/dev/null | sort -nr)
|
||||
|
||||
if [ \$found_count -eq 0 ]; then
|
||||
echo ' No design runs found.'
|
||||
echo ''
|
||||
if [ -n \"\$SESSION_ID\" ]; then
|
||||
echo '💡 HINT: Try running \\'/workflow:ui-design:explore-auto\\' to create a design run'
|
||||
else
|
||||
echo '💡 HINT: Try running \\'/workflow:ui-design:explore-auto --session <id>\\' to create a design run'
|
||||
fi
|
||||
else
|
||||
echo \"Total: \$found_count design run(s)\"
|
||||
echo ''
|
||||
echo '💡 USE: /workflow:ui-design:generate --design-id \"<id>\"'
|
||||
echo ' OR: /workflow:ui-design:generate --session \"<session>\"'
|
||||
fi
|
||||
"
|
||||
)
|
||||
```
|
||||
|
||||
## Example Output
|
||||
|
||||
### With Session Filter
|
||||
```
|
||||
$ /workflow:ui-design:list --session ui-redesign
|
||||
|
||||
Available design runs:
|
||||
|
||||
- design-run-20250109-143052
|
||||
Session: ui-redesign
|
||||
Created: 2025-01-09 14:30
|
||||
Prototypes: 12
|
||||
|
||||
- design-run-20250109-101534
|
||||
Session: ui-redesign
|
||||
Created: 2025-01-09 10:15
|
||||
Prototypes: 6
|
||||
|
||||
Total: 2 design run(s)
|
||||
|
||||
💡 USE: /workflow:ui-design:generate --design-id "<id>"
|
||||
OR: /workflow:ui-design:generate --session "<session>"
|
||||
```
|
||||
|
||||
### All Sessions
|
||||
```
|
||||
$ /workflow:ui-design:list
|
||||
|
||||
Available design runs:
|
||||
|
||||
- design-run-20250109-143052
|
||||
Session: ui-redesign
|
||||
Created: 2025-01-09 14:30
|
||||
Prototypes: 12
|
||||
|
||||
- design-run-20250108-092314
|
||||
Session: landing-page
|
||||
Created: 2025-01-08 09:23
|
||||
Prototypes: 3
|
||||
|
||||
- design-run-20250107-155623
|
||||
Session: standalone
|
||||
Created: 2025-01-07 15:56
|
||||
Prototypes: 8
|
||||
|
||||
Total: 3 design run(s)
|
||||
|
||||
💡 USE: /workflow:ui-design:generate --design-id "<id>"
|
||||
OR: /workflow:ui-design:generate --session "<session>"
|
||||
```
|
||||
@@ -1,21 +0,0 @@
|
||||
---
|
||||
name: Workflow Coordination
|
||||
description: Core coordination principles for multi-agent development workflows
|
||||
---
|
||||
## Core Agent Coordination Principles
|
||||
|
||||
### Planning First Principle
|
||||
|
||||
**Purpose**: Thorough upfront planning reduces risk, improves quality, and prevents costly rework.
|
||||
|
||||
|
||||
### TodoWrite Coordination Rules
|
||||
|
||||
1. **TodoWrite FIRST**: Always create TodoWrite entries *before* complex task execution begins.
|
||||
2. **Context Before Implementation**: Context gathering must complete before implementation tasks begin.
|
||||
3. **Agent Coordination**: Each agent is responsible for updating the status of its assigned todo.
|
||||
4. **Progress Visibility**: Provides clear workflow state visibility to stakeholders.
|
||||
|
||||
6. **Checkpoint Safety**: State is saved automatically after each agent completes its work.
|
||||
7. **Interrupt/Resume**: The system must support full state preservation and restoration.
|
||||
|
||||
@@ -78,7 +78,7 @@ cd src/auth && qwen -p "
|
||||
追踪用户登录的完整执行流程,
|
||||
从 API 入口到数据库查询,
|
||||
列出所有调用的函数和依赖关系
|
||||
" -m coder-model
|
||||
"
|
||||
```
|
||||
|
||||
**工具输出**:Qwen 理解需求,自动追踪执行路径
|
||||
@@ -278,7 +278,7 @@ codex -C src/auth --full-auto exec "
|
||||
**方式 1:CLI 工具语义调用**(推荐,灵活)
|
||||
|
||||
- **用户输入**:`使用 gemini 分析这个项目的架构设计,识别主要模块、依赖关系和架构模式`
|
||||
- **Claude Code 生成并执行**:`cd project-root && gemini -p "..." -m gemini-3-pro-preview-11-2025`
|
||||
- **Claude Code 生成并执行**:`cd project-root && gemini -p "..."`
|
||||
|
||||
**方式 2:Slash 命令**
|
||||
- **用户输入**:`/cli:analyze --tool gemini "分析项目架构"`
|
||||
@@ -291,7 +291,7 @@ codex -C src/auth --full-auto exec "
|
||||
|
||||
**方式 1:CLI 工具语义调用**
|
||||
- **用户输入**:`让 codex 实现用户认证功能:注册(邮箱+密码+验证)、登录(JWT token)、刷新令牌,技术栈 Node.js + Express`
|
||||
- **Claude Code 生成并执行**:`codex -C src/auth --full-auto exec "..." -m gpt-5 --skip-git-repo-check -s danger-full-access`
|
||||
- **Claude Code 生成并执行**:`codex -C src/auth --full-auto exec "..." --skip-git-repo-check -s danger-full-access`
|
||||
|
||||
**方式 2:Slash 命令**(工作流化)
|
||||
- **用户输入**:`/workflow:plan --agent "实现用户认证功能"` → `/workflow:execute`
|
||||
@@ -304,9 +304,9 @@ codex -C src/auth --full-auto exec "
|
||||
|
||||
**方式 1:CLI 工具语义调用**
|
||||
- **用户输入**:`使用 gemini 诊断登录超时问题,分析处理流程、性能瓶颈、数据库查询效率`
|
||||
- **Claude Code 生成并执行**:`cd src/auth && gemini -p "..." -m gemini-3-pro-preview-11-2025`
|
||||
- **Claude Code 生成并执行**:`cd src/auth && gemini -p "..."`
|
||||
- **用户输入**:`让 codex 根据上述分析修复登录超时,优化查询、添加缓存`
|
||||
- **Claude Code 生成并执行**:`codex -C src/auth --full-auto exec "..." -m gpt-5 --skip-git-repo-check -s danger-full-access`
|
||||
- **Claude Code 生成并执行**:`codex -C src/auth --full-auto exec "..." --skip-git-repo-check -s danger-full-access`
|
||||
|
||||
**方式 2:Slash 命令**
|
||||
- **用户输入**:`/cli:mode:bug-diagnosis --tool gemini "诊断登录超时"` → `/cli:execute --tool codex "修复登录超时"`
|
||||
@@ -319,7 +319,7 @@ codex -C src/auth --full-auto exec "
|
||||
|
||||
**方式 1:CLI 工具语义调用**
|
||||
- **用户输入**:`使用 gemini 为 API 模块生成技术文档,包含端点说明、数据模型、使用示例`
|
||||
- **Claude Code 生成并执行**:`cd src/api && gemini -p "..." -m gemini-3-pro-preview-11-2025 --approval-mode yolo`
|
||||
- **Claude Code 生成并执行**:`cd src/api && gemini -p "..." --approval-mode yolo`
|
||||
|
||||
**方式 2:Slash 命令**
|
||||
- **用户输入**:`/memory:docs src/api --tool gemini --mode full`
|
||||
|
||||
@@ -762,7 +762,7 @@ async function executeCLIAnalysis(prompt) {
|
||||
|
||||
// Execute gemini with analysis prompt using --include-directories
|
||||
// This allows gemini to access reference docs while maintaining correct file context
|
||||
const command = `gemini -p "${escapePrompt(prompt)}" -m gemini-3-pro-preview-11-2025 --include-directories ${referencePath}`;
|
||||
const command = `gemini -p "${escapePrompt(prompt)}" --include-directories ${referencePath}`;
|
||||
|
||||
try {
|
||||
const result = await execBash(command, { timeout: 120000 }); // 2 min timeout
|
||||
@@ -770,7 +770,7 @@ async function executeCLIAnalysis(prompt) {
|
||||
} catch (error) {
|
||||
// Fallback to qwen if gemini fails
|
||||
console.warn('Gemini failed, falling back to qwen');
|
||||
const fallbackCmd = `qwen -p "${escapePrompt(prompt)}" -m coder-model --include-directories ${referencePath}`;
|
||||
const fallbackCmd = `qwen -p "${escapePrompt(prompt)}" --include-directories ${referencePath}`;
|
||||
const result = await execBash(fallbackCmd, { timeout: 120000 });
|
||||
return parseAnalysisResult(result.stdout);
|
||||
}
|
||||
|
||||
@@ -162,15 +162,15 @@ RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt)
|
||||
|
||||
**Gemini/Qwen (Write)**:
|
||||
```bash
|
||||
cd {dir} && gemini -p "..." -m gemini-2.5-flash --approval-mode yolo
|
||||
cd {dir} && gemini -p "..." --approval-mode yolo
|
||||
```
|
||||
|
||||
**Codex (Auto)**:
|
||||
```bash
|
||||
codex -C {dir} --full-auto exec "..." -m gpt-5 --skip-git-repo-check -s danger-full-access
|
||||
codex -C {dir} --full-auto exec "..." --skip-git-repo-check -s danger-full-access
|
||||
|
||||
# Resume: Add 'resume --last' after prompt
|
||||
codex --full-auto exec "..." resume --last -m gpt-5 --skip-git-repo-check -s danger-full-access
|
||||
codex --full-auto exec "..." resume --last --skip-git-repo-check -s danger-full-access
|
||||
```
|
||||
|
||||
**Cross-Directory** (Gemini/Qwen):
|
||||
|
||||
@@ -136,7 +136,7 @@ RULES: $(cat ~/.claude/workflows/cli-templates/prompts/{template}) |
|
||||
- Consider previous iteration failures
|
||||
- Validate fix doesn't introduce new vulnerabilities
|
||||
- analysis=READ-ONLY
|
||||
" -m {model} {timeout_flag}
|
||||
" {timeout_flag}
|
||||
```
|
||||
|
||||
**Layer-Specific Guidance Injection**:
|
||||
|
||||
@@ -766,7 +766,7 @@ 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
|
||||
" --approval-mode yolo
|
||||
```
|
||||
|
||||
**Execution with Progress Tracking**:
|
||||
|
||||
@@ -0,0 +1,299 @@
|
||||
# SKILL.md Template for Style Memory Package
|
||||
|
||||
---
|
||||
name: style-{package_name}
|
||||
description: {intelligent_description}
|
||||
---
|
||||
|
||||
# {Package Name} Style SKILL Package
|
||||
|
||||
## 🔍 Quick Index
|
||||
|
||||
### Available JSON Fields
|
||||
|
||||
**High-level structure overview for quick understanding**
|
||||
|
||||
#### design-tokens.json
|
||||
```
|
||||
.colors # Color palette (brand, semantic, surface, text, border)
|
||||
.typography # Font families, sizes, weights, line heights
|
||||
.spacing # Spacing scale (xs, sm, md, lg, xl, etc.)
|
||||
.border_radius # Border radius tokens (sm, md, lg, etc.)
|
||||
.shadows # Shadow definitions (elevation levels)
|
||||
._metadata # Usage recommendations and guidelines
|
||||
├─ .usage_recommendations.typography
|
||||
├─ .usage_recommendations.spacing
|
||||
└─ ...
|
||||
```
|
||||
|
||||
#### layout-templates.json
|
||||
```
|
||||
.layout_templates # Component layout patterns
|
||||
├─ .<component_name>
|
||||
│ ├─ .component_type # "universal" or "specialized"
|
||||
│ ├─ .variants # Component variants array
|
||||
│ ├─ .usage_guide # Usage guidelines
|
||||
│ │ ├─ .common_sizes
|
||||
│ │ ├─ .variant_recommendations
|
||||
│ │ ├─ .usage_context
|
||||
│ │ └─ .accessibility_tips
|
||||
│ └─ ...
|
||||
```
|
||||
|
||||
#### animation-tokens.json (if available)
|
||||
```
|
||||
.duration # Animation duration tokens
|
||||
.easing # Easing function tokens
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
|
||||
### Progressive jq Usage Guide
|
||||
|
||||
#### 📦 Package Overview
|
||||
|
||||
**Base Location**: `.workflow/reference_style/{package_name}/`
|
||||
|
||||
**JSON Files**:
|
||||
- **Design Tokens**: `.workflow/reference_style/{package_name}/design-tokens.json`
|
||||
- **Layout Templates**: `.workflow/reference_style/{package_name}/layout-templates.json`
|
||||
- **Animation Tokens**: `.workflow/reference_style/{package_name}/animation-tokens.json` {has_animations ? "(available)" : "(not available)"}
|
||||
|
||||
**⚠️ Usage Note**: All jq commands below should be executed with directory context. Use the pattern:
|
||||
```bash
|
||||
cd .workflow/reference_style/{package_name} && jq '<query>' <file>.json
|
||||
```
|
||||
|
||||
#### 🔰 Level 0: Basic Queries (~5K tokens)
|
||||
|
||||
```bash
|
||||
# View entire file
|
||||
jq '.' <file>.json
|
||||
|
||||
# List top-level keys
|
||||
jq 'keys' <file>.json
|
||||
|
||||
# Extract specific field
|
||||
jq '.<field_name>' <file>.json
|
||||
```
|
||||
|
||||
**Use when:** Quick reference, first-time exploration
|
||||
|
||||
---
|
||||
|
||||
#### 🎯 Level 1: Filter & Extract (~12K tokens)
|
||||
|
||||
```bash
|
||||
# Count items
|
||||
jq '.<field> | length' <file>.json
|
||||
|
||||
# Filter by condition
|
||||
jq '[.<field>[] | select(.<key> == "<value>")]' <file>.json
|
||||
|
||||
# Extract names
|
||||
jq -r '.<field> | to_entries[] | select(<condition>) | .key' <file>.json
|
||||
|
||||
# Formatted output
|
||||
jq -r '.<field> | to_entries[] | "\(.key): \(.value)"' <file>.json
|
||||
```
|
||||
|
||||
**Universal components filter:** `select(.component_type == "universal")`
|
||||
|
||||
**Use when:** Building components, filtering data
|
||||
|
||||
---
|
||||
|
||||
#### 🚀 Level 2: Combine & Transform (~20K tokens)
|
||||
|
||||
```bash
|
||||
# Pattern search
|
||||
jq '.<field> | keys[] | select(. | contains("<pattern>"))' <file>.json
|
||||
|
||||
# Regex match
|
||||
jq -r '.<field> | to_entries[] | select(.key | test("<regex>"; "i"))' <file>.json
|
||||
|
||||
# Multi-file query
|
||||
jq '.' file1.json && jq '.' file2.json
|
||||
|
||||
# Nested extraction
|
||||
jq '.<field>["<name>"].<nested_field>' <file>.json
|
||||
|
||||
# Preview server (requires directory context)
|
||||
cd .workflow/reference_style/{package_name} && python -m http.server 8080
|
||||
```
|
||||
|
||||
**Use when:** Complex queries, comprehensive analysis
|
||||
|
||||
---
|
||||
|
||||
### Quick Reference: Consistency vs Adaptation
|
||||
|
||||
| Aspect | Prioritize Consistency | Prioritize Adaptation |
|
||||
|--------|----------------------|---------------------|
|
||||
| **UI Components** | Standard buttons, inputs, cards | Hero sections, landing pages |
|
||||
| **Spacing** | Component internal padding | Page layout, section gaps |
|
||||
| **Typography** | Body text, headings (h1-h6) | Display text, metric numbers |
|
||||
| **Colors** | Brand colors, semantic states | Marketing accents, data viz |
|
||||
| **Radius** | Interactive elements | Feature cards, containers |
|
||||
|
||||
---
|
||||
|
||||
## 📖 How to Use This SKILL
|
||||
|
||||
### Quick Access Pattern
|
||||
|
||||
**This SKILL provides design references, NOT executable code.** To use the design system:
|
||||
|
||||
1. **Query JSON files with jq commands**
|
||||
2. **Extract relevant tokens** for your implementation
|
||||
3. **Adapt values** based on your specific design needs
|
||||
|
||||
|
||||
### Progressive Loading
|
||||
|
||||
- **Level 0** (~5K tokens): Quick token reference with `jq '.colors'`, `jq '.typography'`
|
||||
- **Level 1** (~12K tokens): Component filtering with `select(.component_type == "universal")`
|
||||
- **Level 2** (~20K tokens): Complex queries, animations, and preview
|
||||
|
||||
---
|
||||
## ⚡ Core Rules
|
||||
|
||||
1. **Reference, Not Requirements**: This is a design reference system for inspiration and guidance. **DO NOT rigidly copy values.** Analyze the patterns and principles, then adapt creatively to build the optimal design for your specific requirements. Your project's unique needs, brand identity, and user context should drive the final design decisions.
|
||||
|
||||
2. **Universal Components Only**: When using `layout-templates.json`, **ONLY** reference components where `component_type: "universal"`. **IGNORE** `component_type: "specialized"`.
|
||||
|
||||
3. **Token Adaptation**: Adjust design tokens (colors, spacing, typography, shadows, etc.) based on:
|
||||
- Brand requirements and identity
|
||||
- Accessibility standards (WCAG compliance, readability)
|
||||
- Platform conventions (mobile/desktop, iOS/Android/Web)
|
||||
- Context needs (light/dark mode, responsive breakpoints)
|
||||
- User experience goals and interaction patterns
|
||||
- Performance and technical constraints
|
||||
|
||||
---
|
||||
|
||||
## ⚖️ Token Adaptation Strategy
|
||||
|
||||
### Balancing Consistency and Flexibility
|
||||
|
||||
**The Core Problem**: Reference tokens may not have suitable sizes or styles for your new interface needs. Blindly copying leads to poor, rigid design. But ignoring tokens breaks visual consistency.
|
||||
|
||||
**The Solution**: Use tokens as a **pattern foundation**, not a value prison.
|
||||
|
||||
---
|
||||
|
||||
### Decision Framework
|
||||
|
||||
**When to Use Existing Tokens (Maintain Consistency)**:
|
||||
- ✅ Common UI elements (buttons, cards, inputs, typography hierarchy)
|
||||
- ✅ Repeated patterns across multiple pages
|
||||
- ✅ Standard interactions (hover, focus, active states)
|
||||
- ✅ When existing token serves the purpose adequately
|
||||
|
||||
**When to Extend Tokens (Adapt for New Needs)**:
|
||||
- ✅ New component type not in reference system
|
||||
- ✅ Existing token creates visually awkward result
|
||||
- ✅ Special context requires unique treatment (hero sections, landing pages, data visualization)
|
||||
- ✅ Target device/platform has different constraints (mobile vs desktop)
|
||||
|
||||
|
||||
|
||||
### Integration Guidelines
|
||||
|
||||
**1. Document Your Extensions**
|
||||
When you create new token values:
|
||||
- Note the pattern/method used (interpolation, extrapolation, etc.)
|
||||
- Document the specific use case
|
||||
- Consider if it should be added to the design system
|
||||
|
||||
**2. Maintain Visual Consistency**
|
||||
- Use extended values sparingly (don't create 50 spacing tokens)
|
||||
- Prefer using existing tokens when "close enough" (90% fit is often acceptable)
|
||||
- Group extended tokens by context (e.g., "hero-section-padding", "dashboard-metric-size")
|
||||
|
||||
**3. Respect Core Patterns**
|
||||
- **Color**: Preserve hue and semantic meaning, adjust lightness/saturation
|
||||
- **Spacing**: Follow progression pattern (linear/geometric)
|
||||
- **Typography**: Maintain scale ratio and line-height relationships
|
||||
- **Radius**: Continue shape language (sharp vs rounded personality)
|
||||
|
||||
**4. Know When to Break Rules**
|
||||
Sometimes you need unique values for special contexts:
|
||||
- Landing page hero sections
|
||||
- Marketing/promotional components
|
||||
- Data visualization (charts, graphs)
|
||||
- Platform-specific requirements
|
||||
|
||||
**For these cases**: Create standalone tokens with clear naming (`hero-title-size`, `chart-accent-color`) rather than forcing into standard scale.
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Style Understanding & Design References
|
||||
|
||||
**IMPORTANT**: These are reference values and patterns extracted from codebase for inspiration. **DO NOT copy rigidly.** Use them as a starting point to understand design patterns, then creatively adapt to build the optimal solution for your specific project requirements, user needs, and brand identity.
|
||||
|
||||
### Design Principles
|
||||
|
||||
**Dynamically generated based on design token characteristics:**
|
||||
|
||||
{GENERATE_PRINCIPLES_FROM_DESIGN_ANALYSIS}
|
||||
|
||||
{IF DESIGN_ANALYSIS.has_colors:
|
||||
**Color System**
|
||||
- Semantic naming: {DESIGN_ANALYSIS.color_semantic ? "primary/secondary/accent hierarchy" : "descriptive names"}
|
||||
- Use color intentionally to guide attention and convey meaning
|
||||
- Maintain consistent color relationships for brand identity
|
||||
- Ensure sufficient contrast ratios (WCAG AA/AAA) for accessibility
|
||||
}
|
||||
|
||||
{IF DESIGN_ANALYSIS.spacing_pattern detected:
|
||||
**Spatial Rhythm**
|
||||
- Primary scale pattern: {DESIGN_ANALYSIS.spacing_scale} (derived from analysis, represents actual token values)
|
||||
- Pattern characteristics: {DESIGN_ANALYSIS.spacing_pattern} (e.g., "primarily geometric with practical refinements")
|
||||
- {DESIGN_ANALYSIS.spacing_pattern == "geometric" ? "Geometric progression provides clear hierarchy with exponential growth" : "Linear progression offers subtle gradations for fine control"}
|
||||
- Apply systematically: smaller values (4-12px) for compact elements, medium (16-32px) for standard spacing, larger (48px+) for section breathing room
|
||||
- Note: Practical scales may deviate slightly from pure mathematical patterns to optimize for real-world UI needs
|
||||
}
|
||||
|
||||
{IF DESIGN_ANALYSIS.has_typography with typography_hierarchy:
|
||||
**Typographic System**
|
||||
- Type scale establishes content hierarchy and readability
|
||||
- Size progression: {DESIGN_ANALYSIS.typography_scale_example} (e.g., "12px→14px→16px→20px→24px")
|
||||
- Use scale consistently: body text at base, headings at larger sizes
|
||||
- Maintain adequate line-height for readability (1.4-1.6 for body text)
|
||||
}
|
||||
|
||||
{IF DESIGN_ANALYSIS.has_radius:
|
||||
**Shape Language**
|
||||
- Radius style: {DESIGN_ANALYSIS.radius_style} (e.g., "sharp <4px: modern, technical" or "rounded >8px: friendly, approachable")
|
||||
- Creates visual personality: sharp = precision, rounded = warmth
|
||||
- Apply consistently across similar elements (all cards, all buttons)
|
||||
- Match to brand tone: corporate/technical = sharper, consumer/friendly = rounder
|
||||
}
|
||||
|
||||
{IF DESIGN_ANALYSIS.has_shadows:
|
||||
**Depth & Elevation**
|
||||
- Shadow pattern: {DESIGN_ANALYSIS.shadow_pattern} (e.g., "elevation-based: subtle→moderate→prominent")
|
||||
- Use shadows to indicate interactivity and component importance
|
||||
- Consistent application reinforces spatial relationships
|
||||
- Subtle for static cards, prominent for floating/interactive elements
|
||||
}
|
||||
|
||||
{IF DESIGN_ANALYSIS.has_animations:
|
||||
**Motion & Timing**
|
||||
- Duration range: {DESIGN_ANALYSIS.animation_range} (e.g., "100ms (fast feedback) to 300ms (content transitions)")
|
||||
- Easing variety: {DESIGN_ANALYSIS.easing_variety} (e.g., "ease-in-out for natural motion, ease-out for UI responses")
|
||||
- Fast durations for immediate feedback, slower for spatial changes
|
||||
- Consistent timing creates predictable, polished experience
|
||||
}
|
||||
|
||||
{ALWAYS include:
|
||||
**Accessibility First**
|
||||
- Minimum 4.5:1 contrast for text, 3:1 for UI components (WCAG AA)
|
||||
- Touch targets ≥44px for mobile interaction
|
||||
- Clear focus states for keyboard navigation
|
||||
- Test with screen readers and keyboard-only navigation
|
||||
}
|
||||
|
||||
---
|
||||
@@ -33,27 +33,28 @@ RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt) | [
|
||||
|
||||
```bash
|
||||
# Gemini/Qwen
|
||||
cd [dir] && gemini -p "[prompt]" [-m model] [--approval-mode yolo]
|
||||
cd [dir] && gemini -p "[prompt]" [--approval-mode yolo]
|
||||
|
||||
# Codex
|
||||
codex -C [dir] --full-auto exec "[prompt]" [-m model] [--skip-git-repo-check -s danger-full-access]
|
||||
codex -C [dir] --full-auto exec "[prompt]" [--skip-git-repo-check -s danger-full-access]
|
||||
```
|
||||
|
||||
### Model Selection
|
||||
|
||||
**Gemini**:
|
||||
- `gemini-2.5-pro` - Analysis (default)
|
||||
- `gemini-2.5-flash` - Documentation updates
|
||||
- `gemini-2.5-pro` - Default model (auto-selected)
|
||||
- `gemini-2.5-flash` - Fast processing
|
||||
|
||||
**Qwen**:
|
||||
- `coder-model` - Code analysis (default)
|
||||
- `coder-model` - Default model (auto-selected)
|
||||
- `vision-model` - Image analysis (rare)
|
||||
|
||||
**Codex**:
|
||||
- `gpt-5` - Analysis & execution (default)
|
||||
- `gpt5-codex` - Large context tasks
|
||||
- `gpt-5.1` - Default model (auto-selected)
|
||||
- `gpt-5.1-codex` - Extended capabilities
|
||||
- `gpt-5.1-codex-mini` - Lightweight tasks
|
||||
|
||||
**Note**: `-m` parameter placed AFTER prompt
|
||||
**Note**: All tools auto-select appropriate models. `-m` parameter rarely needed; omit for best results
|
||||
|
||||
### Quick Decision Matrix
|
||||
|
||||
@@ -239,24 +240,26 @@ Use the **[Standard Prompt Template](#standard-prompt-template)** for all tools.
|
||||
- **Directory**: `cd [directory] &&` (navigate to target directory)
|
||||
- **Tool**: `gemini` (primary) | `qwen` (fallback)
|
||||
- **Prompt**: `-p "[Standard Prompt Template]"` (prompt BEFORE options)
|
||||
- **Model**: `-m [model-name]` (optional, placed AFTER prompt)
|
||||
- **Model**: `-m [model-name]` (optional, NOT recommended - tools auto-select best model)
|
||||
- Gemini: `gemini-2.5-pro` (default) | `gemini-2.5-flash`
|
||||
- Qwen: `coder-model` (default) | `vision-model`
|
||||
- **Best practice**: Omit `-m` parameter for optimal model selection
|
||||
- **Position**: If used, place AFTER `-p "prompt"`
|
||||
- **Write Permission**: `--approval-mode yolo` (ONLY for MODE=write, placed AFTER prompt)
|
||||
|
||||
**Command Examples**:
|
||||
```bash
|
||||
# Analysis Mode (default, read-only)
|
||||
cd [directory] && gemini -p "[Standard Prompt Template]" -m gemini-2.5-pro
|
||||
cd [directory] && gemini -p "[Standard Prompt Template]"
|
||||
|
||||
# Write Mode (requires MODE=write in template + --approval-mode yolo)
|
||||
cd [directory] && gemini -p "[Standard Prompt Template with MODE: write]" -m gemini-2.5-flash --approval-mode yolo
|
||||
cd [directory] && gemini -p "[Standard Prompt Template with MODE: write]" --approval-mode yolo
|
||||
|
||||
# Fallback to Qwen
|
||||
cd [directory] && qwen -p "[Standard Prompt Template]" -m coder-model
|
||||
cd [directory] && qwen -p "[Standard Prompt Template]"
|
||||
|
||||
# Multi-directory support
|
||||
cd [directory] && gemini -p "[Standard Prompt Template]" -m gemini-2.5-pro --include-directories ../shared,../types
|
||||
cd [directory] && gemini -p "[Standard Prompt Template]" --include-directories ../shared,../types
|
||||
```
|
||||
|
||||
#### Codex
|
||||
@@ -267,29 +270,30 @@ cd [directory] && gemini -p "[Standard Prompt Template]" -m gemini-2.5-pro --inc
|
||||
- **Directory**: `-C [directory]` (target directory parameter)
|
||||
- **Execution Mode**: `--full-auto exec` (required for autonomous execution)
|
||||
- **Prompt**: `exec "[Standard Prompt Template]"` (prompt BEFORE options)
|
||||
- **Model**: `-m [model-name]` (optional, placed AFTER prompt, BEFORE flags)
|
||||
- `gpt-5` (default) | `gpt5-codex` (large context)
|
||||
- **Model**: `-m [model-name]` (optional, NOT recommended - Codex auto-selects best model)
|
||||
- Available: `gpt-5.1` | `gpt-5.1-codex` | `gpt-5.1-codex-mini`
|
||||
- **Best practice**: Omit `-m` parameter for optimal model selection
|
||||
- **Write Permission**: `--skip-git-repo-check -s danger-full-access` (ONLY for MODE=auto or MODE=write, placed at command END)
|
||||
- **Session Resume**: `resume --last` (placed AFTER prompt, BEFORE flags)
|
||||
|
||||
**Command Examples**:
|
||||
```bash
|
||||
# Auto Mode (requires MODE=auto in template + permission flags)
|
||||
codex -C [directory] --full-auto exec "[Standard Prompt Template with MODE: auto]" -m gpt-5 --skip-git-repo-check -s danger-full-access
|
||||
codex -C [directory] --full-auto exec "[Standard Prompt Template with MODE: auto]" --skip-git-repo-check -s danger-full-access
|
||||
|
||||
# Write Mode (requires MODE=write in template + permission flags)
|
||||
codex -C [directory] --full-auto exec "[Standard Prompt Template with MODE: write]" -m gpt-5 --skip-git-repo-check -s danger-full-access
|
||||
codex -C [directory] --full-auto exec "[Standard Prompt Template with MODE: write]" --skip-git-repo-check -s danger-full-access
|
||||
|
||||
# Session continuity
|
||||
# First task - MUST use full Standard Prompt Template to establish context
|
||||
codex -C project --full-auto exec "[Standard Prompt Template with MODE: auto]" -m gpt-5 --skip-git-repo-check -s danger-full-access
|
||||
codex -C project --full-auto exec "[Standard Prompt Template with MODE: auto]" --skip-git-repo-check -s danger-full-access
|
||||
|
||||
# Subsequent tasks - Can use brief prompt ONLY when using 'resume --last'
|
||||
# (inherits full context from previous session, no need to repeat template)
|
||||
codex --full-auto exec "Add JWT refresh token validation" resume --last --skip-git-repo-check -s danger-full-access
|
||||
|
||||
# With image attachment
|
||||
codex -C [directory] -i design.png --full-auto exec "[Standard Prompt Template]" -m gpt-5 --skip-git-repo-check -s danger-full-access
|
||||
codex -C [directory] -i design.png --full-auto exec "[Standard Prompt Template]" --skip-git-repo-check -s danger-full-access
|
||||
```
|
||||
|
||||
**Complete Example (Codex with full template)**:
|
||||
@@ -302,7 +306,7 @@ MODE: auto
|
||||
CONTEXT: @**/* | Memory: Following security patterns from project standards
|
||||
EXPECTED: Complete auth module with tests
|
||||
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/02-implement-feature.txt) | Follow existing patterns | auto=FULL operations
|
||||
" -m gpt-5 --skip-git-repo-check -s danger-full-access
|
||||
" --skip-git-repo-check -s danger-full-access
|
||||
|
||||
# Subsequent tasks - brief description with resume
|
||||
codex --full-auto exec "Add JWT refresh token validation" resume --last --skip-git-repo-check -s danger-full-access
|
||||
@@ -329,7 +333,7 @@ codex --full-auto exec "Add JWT refresh token validation" resume --last --skip-g
|
||||
2. Explicitly reference external files in CONTEXT field with @ patterns
|
||||
3. ⚠️ BOTH steps are MANDATORY
|
||||
|
||||
Example: `cd src/auth && gemini -p "CONTEXT: @**/* @../shared/**/*" -m gemini-2.5-pro --include-directories ../shared`
|
||||
Example: `cd src/auth && gemini -p "CONTEXT: @**/* @../shared/**/*" --include-directories ../shared`
|
||||
|
||||
**Rule**: If CONTEXT contains `@../dir/**/*`, command MUST include `--include-directories ../dir`
|
||||
|
||||
@@ -344,10 +348,10 @@ Example: `cd src/auth && gemini -p "CONTEXT: @**/* @../shared/**/*" -m gemini-2.
|
||||
**Syntax**:
|
||||
```bash
|
||||
# Comma-separated format
|
||||
gemini -p "prompt" -m gemini-2.5-pro --include-directories /path/to/project1,/path/to/project2
|
||||
gemini -p "prompt" --include-directories /path/to/project1,/path/to/project2
|
||||
|
||||
# Multiple flags format
|
||||
gemini -p "prompt" -m gemini-2.5-pro --include-directories /path/to/project1 --include-directories /path/to/project2
|
||||
gemini -p "prompt" --include-directories /path/to/project1 --include-directories /path/to/project2
|
||||
|
||||
# Recommended: cd + --include-directories
|
||||
cd src/auth && gemini -p "
|
||||
@@ -357,7 +361,7 @@ MODE: analysis
|
||||
CONTEXT: @**/* @../shared/**/* @../types/**/*
|
||||
EXPECTED: Complete analysis with cross-directory dependencies
|
||||
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-analyze-code-patterns.txt) | Focus on integration patterns | analysis=READ-ONLY
|
||||
" -m gemini-2.5-pro --include-directories ../shared,../types
|
||||
" --include-directories ../shared,../types
|
||||
```
|
||||
|
||||
**Best Practices**:
|
||||
@@ -445,7 +449,7 @@ MODE: analysis
|
||||
CONTEXT: @components/Auth.tsx @types/auth.d.ts @hooks/useAuth.ts | Memory: Previous refactoring identified type inconsistencies, following React hooks patterns, related implementation in @hooks/useAuth.ts (commit abc123)
|
||||
EXPECTED: Comprehensive analysis report with type safety recommendations, code examples, and references to previous findings
|
||||
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-analyze-code-patterns.txt) | Focus on type safety and component composition | analysis=READ-ONLY
|
||||
" -m gemini-2.5-pro
|
||||
"
|
||||
```
|
||||
|
||||
### RULES Field Configuration
|
||||
|
||||
65
CHANGELOG.md
65
CHANGELOG.md
@@ -6,6 +6,71 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
||||
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
|
||||
## [5.8.1] - 2025-01-16
|
||||
|
||||
### ⚡ Lite-Plan Workflow & CLI Tools Enhancement
|
||||
|
||||
This release introduces a powerful new lightweight planning workflow with intelligent automation and optimized CLI tool usage.
|
||||
|
||||
#### ✨ Added
|
||||
|
||||
**Lite-Plan Workflow** (`/workflow:lite-plan`):
|
||||
- ✨ **Interactive Lightweight Workflow** - Fast, in-memory planning and execution
|
||||
- **Phase 1: Task Analysis & Smart Exploration** (30-90s)
|
||||
- Auto-detects when codebase context is needed
|
||||
- Optional `@cli-explore-agent` for code understanding
|
||||
- Force exploration with `-e` or `--explore` flag
|
||||
- **Phase 2: Interactive Clarification** (user-dependent)
|
||||
- Ask follow-up questions based on exploration findings
|
||||
- Gather missing information before planning
|
||||
- **Phase 3: Adaptive Planning** (20-60s)
|
||||
- Low complexity: Direct planning by Claude
|
||||
- Medium/High complexity: Delegate to `@cli-planning-agent`
|
||||
- **Phase 4: Three-Dimensional Multi-Select Confirmation** (user-dependent)
|
||||
- ✅ **Task Approval**: Allow / Modify / Cancel (with optional supplements)
|
||||
- 🔧 **Execution Method**: Agent / Provide Plan / CLI (Gemini/Qwen/Codex)
|
||||
- 🔍 **Code Review**: No / Claude / Gemini / Qwen / Codex
|
||||
- **Phase 5: Live Execution & Tracking** (5-120min)
|
||||
- Real-time TodoWrite progress updates
|
||||
- Parallel task execution for independent tasks
|
||||
- Optional post-execution code review
|
||||
- ✨ **Parallel Task Execution** - Identifies independent tasks for concurrent execution
|
||||
- ✨ **Flexible Tool Selection** - Preset with `--tool` flag or choose during confirmation
|
||||
- ✨ **No File Artifacts** - All planning stays in memory for faster workflow
|
||||
|
||||
#### 🔄 Changed
|
||||
|
||||
**CLI Tools Optimization**:
|
||||
- 🔄 **Simplified Command Syntax** - Removed `-m` parameter requirement
|
||||
- Gemini: Auto-selects `gemini-2.5-pro` (default) or `gemini-2.5-flash`
|
||||
- Qwen: Auto-selects `coder-model` (default) or `vision-model`
|
||||
- Codex: Auto-selects `gpt-5.1` (default), `gpt-5.1-codex`, or `gpt-5.1-codex-mini`
|
||||
- 🔄 **Improved Model Selection** - Tools now auto-select best model for task
|
||||
- 🔄 **Updated Documentation** - Clearer guidelines in `intelligent-tools-strategy.md`
|
||||
|
||||
**Execution Workflow Enhancement**:
|
||||
- 🔄 **Streamlined Phases** - Simplified execution phases with lazy loading strategy
|
||||
- 🔄 **Enhanced Error Handling** - Improved error messages and recovery options
|
||||
- 🔄 **Clarified Resume Mode** - Better documentation for workflow resumption
|
||||
|
||||
**CLI Explore Agent**:
|
||||
- 🎨 **Improved Visibility** - Changed color scheme from blue to yellow
|
||||
|
||||
#### 📝 Documentation
|
||||
|
||||
**Updated Files**:
|
||||
- 🔄 **README.md / README_CN.md** - Added Lite-Plan workflow usage examples
|
||||
- 🔄 **COMMAND_REFERENCE.md** - Added `/workflow:lite-plan` entry
|
||||
- 🔄 **COMMAND_SPEC.md** - Added detailed technical specification for Lite-Plan
|
||||
- 🔄 **intelligent-tools-strategy.md** - Updated model selection guidelines
|
||||
|
||||
#### 🐛 Bug Fixes
|
||||
|
||||
- Fixed command syntax inconsistencies in CLI tool documentation
|
||||
- Improved task dependency detection for parallel execution
|
||||
|
||||
---
|
||||
|
||||
## [5.5.0] - 2025-11-06
|
||||
|
||||
### 🎯 Interactive Command Guide & Enhanced Documentation
|
||||
|
||||
@@ -38,6 +38,7 @@ These commands orchestrate complex, multi-phase development processes, from plan
|
||||
| Command | Description |
|
||||
|---|---|
|
||||
| `/workflow:plan` | Orchestrate 5-phase planning workflow with quality gate, executing commands and passing context between phases. |
|
||||
| `/workflow:lite-plan` | ⚡ **NEW** Lightweight interactive planning and execution workflow with in-memory planning, smart code exploration, three-dimensional multi-select confirmation (task approval + execution method + code review), and parallel task execution support. |
|
||||
| `/workflow:execute` | Coordinate agents for existing workflow tasks with automatic discovery. |
|
||||
| `/workflow:resume` | Intelligent workflow session resumption with automatic progress analysis. |
|
||||
| `/workflow:review` | Optional specialized review (security, architecture, docs) for completed implementation. |
|
||||
@@ -92,7 +93,7 @@ These commands orchestrate complex, multi-phase development processes, from plan
|
||||
| `/workflow:ui-design:style-extract` | Extract design style from reference images or text prompts using Claude's analysis. |
|
||||
| `/workflow:ui-design:layout-extract` | Extract structural layout information from reference images, URLs, or text prompts. |
|
||||
| `/workflow:ui-design:generate` | Assemble UI prototypes by combining layout templates with design tokens (pure assembler). |
|
||||
| `/workflow:ui-design:update` | Update brainstorming artifacts with finalized design system references. |
|
||||
| `/workflow:ui-design:design-sync` | Synchronize finalized design system references to brainstorming artifacts. |
|
||||
| `/workflow:ui-design:animation-extract` | Extract animation and transition patterns from URLs, CSS, or interactive questioning. |
|
||||
|
||||
### Internal Tools
|
||||
|
||||
@@ -45,6 +45,44 @@ High-level orchestrators for complex, multi-phase development processes.
|
||||
/workflow:plan "Create a simple Express API that returns Hello World"
|
||||
```
|
||||
|
||||
### **/workflow:lite-plan** ⚡ NEW
|
||||
|
||||
- **Syntax**: `/workflow:lite-plan [--tool claude|gemini|qwen|codex] [-e|--explore] "task description"|file.md`
|
||||
- **Parameters**:
|
||||
- `--tool` (Optional, String): Preset CLI tool for execution (claude|gemini|qwen|codex). If not provided, user selects during confirmation.
|
||||
- `-e, --explore` (Optional, Flag): Force code exploration phase (overrides auto-detection logic).
|
||||
- `task description|file.md` (Required, String): Task description or path to .md file.
|
||||
- **Responsibilities**: Lightweight interactive planning and execution workflow with 5 phases:
|
||||
1. **Task Analysis & Exploration**: Auto-detects need for codebase context, optionally launches `@cli-explore-agent` (30-90s)
|
||||
2. **Clarification**: Interactive Q&A based on exploration findings (user-dependent)
|
||||
3. **Planning**: Adaptive planning strategy - direct (Low complexity) or delegate to `@cli-planning-agent` (Medium/High complexity) (20-60s)
|
||||
4. **Three-Dimensional Confirmation**: Multi-select interaction for task approval + execution method + code review tool (user-dependent)
|
||||
5. **Execution & Tracking**: Live TodoWrite progress updates with selected method (5-120min)
|
||||
- **Key Features**:
|
||||
- **Smart Code Exploration**: Auto-detects when codebase context is needed (use `-e` to force)
|
||||
- **In-Memory Planning**: No file artifacts generated during planning phase
|
||||
- **Three-Dimensional Multi-Select**: Task approval (Allow/Modify/Cancel) + Execution method (Agent/Provide Plan/CLI) + Code review (No/Claude/Gemini/Qwen/Codex)
|
||||
- **Parallel Task Execution**: Identifies independent tasks for concurrent execution
|
||||
- **Flexible Execution**: Choose between Agent (@code-developer) or CLI (Gemini/Qwen/Codex)
|
||||
- **Optional Post-Review**: Built-in code quality analysis with user-selectable AI tool
|
||||
- **Agent Calls**:
|
||||
- `@cli-explore-agent` (conditional, Phase 1)
|
||||
- `@cli-planning-agent` (conditional, Phase 3 for Medium/High complexity)
|
||||
- `@code-developer` (conditional, Phase 5 if Agent execution selected)
|
||||
- **Skill Invocation**: None directly, but agents may invoke skills.
|
||||
- **Integration**: Standalone workflow for quick tasks. Alternative to `/workflow:plan` + `/workflow:execute` pattern.
|
||||
- **Example**:
|
||||
```bash
|
||||
# Basic usage with auto-detection
|
||||
/workflow:lite-plan "Add JWT authentication to user login"
|
||||
|
||||
# Force code exploration
|
||||
/workflow:lite-plan -e "Refactor logging module for better performance"
|
||||
|
||||
# Preset CLI tool
|
||||
/workflow:lite-plan --tool codex "Add unit tests for auth service"
|
||||
```
|
||||
|
||||
### **/workflow:execute**
|
||||
|
||||
- **Syntax**: `/workflow:execute [--resume-session="session-id"]`
|
||||
@@ -420,13 +458,13 @@ Specialized workflow for UI/UX design, from style extraction to prototype genera
|
||||
/workflow:ui-design:generate --session WFS-design-run
|
||||
```
|
||||
|
||||
### **/workflow:ui-design:update**
|
||||
- **Syntax**: `/workflow:ui-design:update --session <session_id> ...`
|
||||
- **Responsibilities**: Synchronizes the finalized design system references into the core brainstorming artifacts (`synthesis-specification.md`) to make them available for the planning phase.
|
||||
### **/workflow:ui-design:design-sync**
|
||||
- **Syntax**: `/workflow:ui-design:design-sync --session <session_id> [--selected-prototypes "<list>"]`
|
||||
- **Responsibilities**: Synchronizes the finalized design system references into the core brainstorming artifacts (`role analysis documents`) to make them available for the planning phase.
|
||||
- **Agent Calls**: None.
|
||||
- **Example**:
|
||||
```bash
|
||||
/workflow:ui-design:update --session WFS-my-app
|
||||
/workflow:ui-design:design-sync --session WFS-my-app
|
||||
```
|
||||
|
||||
### **/workflow:ui-design:animation-extract**
|
||||
|
||||
@@ -100,8 +100,8 @@ For UI-focused projects, start with design exploration before implementation: **
|
||||
# Step 1: Generate UI design variations (auto-creates session)
|
||||
/workflow:ui-design:explore-auto --prompt "A modern, clean admin dashboard login page"
|
||||
|
||||
# Step 2: Review designs in compare.html, then update brainstorming artifacts
|
||||
/workflow:ui-design:update --session <session-id> --selected-prototypes "login-v1,login-v2"
|
||||
# Step 2: Review designs in compare.html, then sync design system to brainstorming artifacts
|
||||
/workflow:ui-design:design-sync --session <session-id> --selected-prototypes "login-v1,login-v2"
|
||||
|
||||
# Step 3: Generate implementation plan with design references
|
||||
/workflow:plan
|
||||
|
||||
@@ -100,8 +100,8 @@
|
||||
# 第 1 步:生成 UI 设计变体(自动创建会话)
|
||||
/workflow:ui-design:explore-auto --prompt "一个现代、简洁的管理后台登录页面"
|
||||
|
||||
# 第 2 步:在 compare.html 中审查设计,然后更新头脑风暴工件
|
||||
/workflow:ui-design:update --session <session-id> --selected-prototypes "login-v1,login-v2"
|
||||
# 第 2 步:在 compare.html 中审查设计,然后同步设计系统到头脑风暴工件
|
||||
/workflow:ui-design:design-sync --session <session-id> --selected-prototypes "login-v1,login-v2"
|
||||
|
||||
# 第 3 步:使用设计引用生成实现计划
|
||||
/workflow:plan
|
||||
|
||||
48
README.md
48
README.md
@@ -2,7 +2,7 @@
|
||||
|
||||
<div align="center">
|
||||
|
||||
[](https://github.com/catlog22/Claude-Code-Workflow/releases)
|
||||
[](https://github.com/catlog22/Claude-Code-Workflow/releases)
|
||||
[](LICENSE)
|
||||
[]()
|
||||
|
||||
@@ -14,13 +14,20 @@
|
||||
|
||||
**Claude Code Workflow (CCW)** transforms AI development from simple prompt chaining into a robust, context-first orchestration system. It solves execution uncertainty and error accumulation through structured planning, deterministic execution, and intelligent multi-model orchestration.
|
||||
|
||||
> **🎉 Version 5.5: Interactive Command Guide & Enhanced Documentation**
|
||||
> **🎉 Version 5.8.1: Lite-Plan Workflow & CLI Tools Enhancement**
|
||||
>
|
||||
> **Core Improvements**:
|
||||
> - ✨ **Command-Guide Skill** - Interactive help system with CCW-help and CCW-issue triggers
|
||||
> - ✨ **Enhanced Command Descriptions** - All 69 commands updated with detailed functionality descriptions
|
||||
> - ✨ **5-Index Command System** - Organized by category, use-case, relationships, and essentials
|
||||
> - ✨ **Smart Recommendations** - Context-aware next-step suggestions for workflow guidance
|
||||
> - ✨ **Lite-Plan Workflow** (`/workflow:lite-plan`) - Lightweight interactive planning with intelligent automation
|
||||
> - **Three-Dimensional Multi-Select Confirmation**: Task approval + Execution method + Code review tool
|
||||
> - **Smart Code Exploration**: Auto-detects when codebase context is needed (use `-e` flag to force)
|
||||
> - **Parallel Task Execution**: Identifies independent tasks for concurrent execution
|
||||
> - **Flexible Execution**: Choose between Agent (@code-developer) or CLI (Gemini/Qwen/Codex)
|
||||
> - **Optional Post-Review**: Built-in code quality analysis with your choice of AI tool
|
||||
> - ✨ **CLI Tools Optimization** - Simplified command syntax with auto-model-selection
|
||||
> - Removed `-m` parameter requirement for Gemini, Qwen, and Codex (auto-selects best model)
|
||||
> - Clearer command structure and improved documentation
|
||||
> - 🔄 **Execution Workflow Enhancement** - Streamlined phases with lazy loading strategy
|
||||
> - 🎨 **CLI Explore Agent** - Improved visibility with yellow color scheme
|
||||
>
|
||||
> See [CHANGELOG.md](CHANGELOG.md) for full details.
|
||||
|
||||
@@ -108,6 +115,35 @@ The best way to get started is to follow the 5-minute tutorial in the [**Getting
|
||||
|
||||
Here is a quick example of a common development workflow:
|
||||
|
||||
### **Option 1: Lite-Plan Workflow** (⚡ Recommended for Quick Tasks)
|
||||
|
||||
Lightweight interactive workflow with in-memory planning and immediate execution:
|
||||
|
||||
```bash
|
||||
# Basic usage with auto-detection
|
||||
/workflow:lite-plan "Add JWT authentication to user login"
|
||||
|
||||
# Force code exploration
|
||||
/workflow:lite-plan -e "Refactor logging module for better performance"
|
||||
|
||||
# Preset CLI tool
|
||||
/workflow:lite-plan --tool codex "Add unit tests for auth service"
|
||||
```
|
||||
|
||||
**Interactive Flow**:
|
||||
1. **Phase 1**: Automatic task analysis and smart code exploration (if needed)
|
||||
2. **Phase 2**: Answer clarification questions (if any)
|
||||
3. **Phase 3**: Review generated plan with task breakdown
|
||||
4. **Phase 4**: Three-dimensional confirmation:
|
||||
- ✅ Confirm/Modify/Cancel task
|
||||
- 🔧 Choose execution: Agent / Provide Plan / CLI (Gemini/Qwen/Codex)
|
||||
- 🔍 Optional code review: No / Claude / Gemini / Qwen / Codex
|
||||
5. **Phase 5**: Watch real-time execution with live task tracking
|
||||
|
||||
### **Option 2: Full Workflow** (Comprehensive Planning)
|
||||
|
||||
Traditional multi-phase workflow for complex projects:
|
||||
|
||||
1. **Create a Plan** (automatically starts a session):
|
||||
```bash
|
||||
/workflow:plan "Implement JWT-based user login and registration"
|
||||
|
||||
48
README_CN.md
48
README_CN.md
@@ -2,7 +2,7 @@
|
||||
|
||||
<div align="center">
|
||||
|
||||
[](https://github.com/catlog22/Claude-Code-Workflow/releases)
|
||||
[](https://github.com/catlog22/Claude-Code-Workflow/releases)
|
||||
[](LICENSE)
|
||||
[]()
|
||||
|
||||
@@ -14,13 +14,20 @@
|
||||
|
||||
**Claude Code Workflow (CCW)** 将 AI 开发从简单的提示词链接转变为一个强大的、上下文优先的编排系统。它通过结构化规划、确定性执行和智能多模型编排,解决了执行不确定性和误差累积的问题。
|
||||
|
||||
> **🎉 版本 5.5: 交互式命令指南与增强文档**
|
||||
> **🎉 版本 5.8.1: Lite-Plan 工作流与 CLI 工具增强**
|
||||
>
|
||||
> **核心改进**:
|
||||
> - ✨ **命令指南技能** - 交互式帮助系统,支持 CCW-help 和 CCW-issue 触发
|
||||
> - ✨ **增强命令描述** - 所有 69 个命令更新了详细功能描述
|
||||
> - ✨ **5 索引命令系统** - 按分类、使用场景、关系和核心命令组织
|
||||
> - ✨ **智能推荐** - 基于上下文的工作流引导建议
|
||||
> - ✨ **Lite-Plan 工作流** (`/workflow:lite-plan`) - 轻量级交互式规划与智能自动化
|
||||
> - **三维多选确认**: 任务批准 + 执行方法 + 代码审查工具
|
||||
> - **智能代码探索**: 自动检测何时需要代码库上下文(使用 `-e` 标志强制探索)
|
||||
> - **并行任务执行**: 识别独立任务以实现并发执行
|
||||
> - **灵活执行**: 选择智能体(@code-developer)或 CLI(Gemini/Qwen/Codex)
|
||||
> - **可选后置审查**: 内置代码质量分析,可选择 AI 工具
|
||||
> - ✨ **CLI 工具优化** - 简化命令语法,自动模型选择
|
||||
> - 移除 Gemini、Qwen 和 Codex 的 `-m` 参数要求(自动选择最佳模型)
|
||||
> - 更清晰的命令结构和改进的文档
|
||||
> - 🔄 **执行工作流增强** - 简化阶段,采用延迟加载策略
|
||||
> - 🎨 **CLI Explore Agent** - 改进可见性,采用黄色配色方案
|
||||
>
|
||||
> 详见 [CHANGELOG.md](CHANGELOG.md)。
|
||||
|
||||
@@ -108,6 +115,35 @@ CCW 包含内置的**命令指南技能**,帮助您有效地发现和使用命
|
||||
|
||||
以下是一个常见开发工作流的快速示例:
|
||||
|
||||
### **选项 1: Lite-Plan 工作流** (⚡ 推荐用于快速任务)
|
||||
|
||||
轻量级交互式工作流,内存中规划并立即执行:
|
||||
|
||||
```bash
|
||||
# 基本用法,自动检测
|
||||
/workflow:lite-plan "为用户登录添加 JWT 认证"
|
||||
|
||||
# 强制代码探索
|
||||
/workflow:lite-plan -e "重构日志模块以提高性能"
|
||||
|
||||
# 预设 CLI 工具
|
||||
/workflow:lite-plan --tool codex "为认证服务添加单元测试"
|
||||
```
|
||||
|
||||
**交互流程**:
|
||||
1. **阶段 1**: 自动任务分析和智能代码探索(如需要)
|
||||
2. **阶段 2**: 回答澄清问题(如有)
|
||||
3. **阶段 3**: 查看生成的计划和任务分解
|
||||
4. **阶段 4**: 三维确认:
|
||||
- ✅ 确认/修改/取消任务
|
||||
- 🔧 选择执行方式: 智能体 / 仅提供计划 / CLI(Gemini/Qwen/Codex)
|
||||
- 🔍 可选代码审查: 否 / Claude / Gemini / Qwen / Codex
|
||||
5. **阶段 5**: 观察实时执行和任务跟踪
|
||||
|
||||
### **选项 2: 完整工作流** (综合规划)
|
||||
|
||||
适用于复杂项目的传统多阶段工作流:
|
||||
|
||||
1. **创建计划**(自动启动会话):
|
||||
```bash
|
||||
/workflow:plan "实现基于 JWT 的用户登录和注册"
|
||||
|
||||
Reference in New Issue
Block a user