mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-12 02:37:45 +08:00
docs(skill): update command guide for v5.8.0 release
Major updates: - Add UI Design Style Memory workflow documentation - /memory:style-skill-memory command - /workflow:ui-design:codify-style orchestrator - /workflow:ui-design:reference-page-generator - Add /workflow:lite-plan intelligent planning command (testing) - Add /memory:code-map-memory code flow mapping (testing) Agent enhancements: - Add cli-explore-agent for code exploration - Enhance cli-planning-agent task generation - Major ui-design-agent refactoring Statistics: - Commands: 69 → 75 (+6) - Agents: 11 → 13 (+2) - Reference docs: 80 → 88 files Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
@@ -50,17 +50,18 @@ This workflow runs **fully autonomously** once triggered. Phase 1 (artifacts) ha
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
/workflow:brainstorm:auto-parallel "<topic>" [--count N]
|
||||
/workflow:brainstorm:auto-parallel "<topic>" [--count N] [--style-skill package-name]
|
||||
```
|
||||
|
||||
**Recommended Structured Format**:
|
||||
```bash
|
||||
/workflow:brainstorm:auto-parallel "GOAL: [objective] SCOPE: [boundaries] CONTEXT: [background]" [--count N]
|
||||
/workflow:brainstorm:auto-parallel "GOAL: [objective] SCOPE: [boundaries] CONTEXT: [background]" [--count N] [--style-skill package-name]
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `topic` (required): Topic or challenge description (structured format recommended)
|
||||
- `--count N` (optional): Number of roles to select (default: 3, max: 9)
|
||||
- `--style-skill package-name` (optional): Style SKILL package to load for UI design (located at `.claude/skills/style-{package-name}/`)
|
||||
|
||||
## 3-Phase Execution
|
||||
|
||||
@@ -150,6 +151,12 @@ TOPIC: {user-provided-topic}
|
||||
- Command: Read(.workflow/WFS-{session}/workflow-session.json)
|
||||
- Output: session_context (contains original user prompt as PRIMARY reference)
|
||||
|
||||
4. **load_style_skill** (ONLY for ui-designer role when style_skill_package exists)
|
||||
- Action: Load style SKILL package for design system reference
|
||||
- Command: Read(.claude/skills/style-{style_skill_package}/SKILL.md) AND Read(.workflow/reference_style/{style_skill_package}/design-tokens.json)
|
||||
- Output: style_skill_content, design_tokens
|
||||
- Usage: Apply design tokens in ui-designer analysis and artifacts
|
||||
|
||||
## Analysis Requirements
|
||||
**Primary Reference**: Original user prompt from workflow-session.json is authoritative
|
||||
**Framework Source**: Address all discussion points in guidance-specification.md from {role-name} perspective
|
||||
@@ -342,6 +349,34 @@ ELSE:
|
||||
EXECUTE: /workflow:brainstorm:artifacts "{topic}" --count {count_value}
|
||||
```
|
||||
|
||||
**Style-Skill Parameter Parsing**:
|
||||
```javascript
|
||||
// Extract --style-skill from user input
|
||||
IF user_input CONTAINS "--style-skill":
|
||||
EXTRACT style_skill_name FROM "--style-skill package-name" pattern
|
||||
|
||||
// Validate SKILL package exists
|
||||
skill_path = ".claude/skills/style-{style_skill_name}/SKILL.md"
|
||||
IF file_exists(skill_path):
|
||||
style_skill_package = style_skill_name
|
||||
style_reference_path = ".workflow/reference_style/{style_skill_name}"
|
||||
echo("✓ Style SKILL package found: style-{style_skill_name}")
|
||||
echo(" Design reference: {style_reference_path}")
|
||||
ELSE:
|
||||
echo("⚠ WARNING: Style SKILL package not found: {style_skill_name}")
|
||||
echo(" Expected location: {skill_path}")
|
||||
echo(" Continuing without style reference...")
|
||||
style_skill_package = null
|
||||
ELSE:
|
||||
style_skill_package = null
|
||||
echo("No style-skill specified, ui-designer will use default workflow")
|
||||
|
||||
// Store for Phase 2 ui-designer context
|
||||
CONTEXT_VARS:
|
||||
- style_skill_package: {style_skill_package}
|
||||
- style_reference_path: {style_reference_path}
|
||||
```
|
||||
|
||||
**Topic Structuring**:
|
||||
1. **Already Structured** → Pass directly to artifacts
|
||||
```
|
||||
@@ -374,15 +409,17 @@ EXECUTE: /workflow:brainstorm:artifacts "{topic}" --count {count_value}
|
||||
|
||||
**Phase 1 Output**:
|
||||
- `.workflow/WFS-{topic}/.brainstorming/guidance-specification.md` (framework content)
|
||||
- `.workflow/WFS-{topic}/workflow-session.json` (metadata: selected_roles[], topic, timestamps)
|
||||
- `.workflow/WFS-{topic}/workflow-session.json` (metadata: selected_roles[], topic, timestamps, style_skill_package)
|
||||
|
||||
**Phase 2 Output**:
|
||||
- `.workflow/WFS-{topic}/.brainstorming/{role}/analysis.md` (one per role)
|
||||
- `.superdesign/design_iterations/` (ui-designer artifacts, if --style-skill provided)
|
||||
|
||||
**Phase 3 Output**:
|
||||
- `.workflow/WFS-{topic}/.brainstorming/synthesis-specification.md` (integrated analysis)
|
||||
|
||||
**⚠️ Storage Separation**: Guidance content in .md files, metadata in .json (no duplication)
|
||||
**⚠️ Style References**: When --style-skill provided, workflow-session.json stores style_skill_package name, ui-designer loads from `.claude/skills/style-{package-name}/`
|
||||
|
||||
## Available Roles
|
||||
|
||||
|
||||
@@ -0,0 +1,962 @@
|
||||
---
|
||||
name: lite-plan
|
||||
description: Lightweight interactive planning and execution workflow with in-memory planning, code exploration, and immediate execution after user confirmation
|
||||
argument-hint: "[--tool claude|gemini|qwen|codex] [--quick] \"task description\"|file.md"
|
||||
allowed-tools: TodoWrite(*), Task(*), Bash(*), AskUserQuestion(*)
|
||||
timeout: 180000
|
||||
color: cyan
|
||||
---
|
||||
|
||||
# Workflow Lite-Plan Command (/workflow:lite-plan)
|
||||
|
||||
## Overview
|
||||
|
||||
Intelligent lightweight planning and execution command with dynamic workflow adaptation based on task complexity.
|
||||
|
||||
**Key Characteristics**:
|
||||
- Dynamic Workflow: Automatically decides whether to use exploration, clarification, and detailed planning
|
||||
- Smart Exploration: Calls cli-explore-agent only when task requires codebase context
|
||||
- Interactive Clarification: Asks user for more information after exploration if needed
|
||||
- Adaptive Planning: Simple tasks get direct planning, complex tasks use cli-planning-agent
|
||||
- Two-Dimensional Confirmation: User confirms task + selects execution method in one step
|
||||
- Direct Execution: Immediately starts execution (agent or CLI) after confirmation
|
||||
- Live Progress Tracking: Uses TodoWrite to track execution progress in real-time
|
||||
|
||||
## Core Functionality
|
||||
|
||||
- **Intelligent Task Analysis**: Automatically determines if exploration/planning agents are needed
|
||||
- **Dynamic Exploration**: Calls cli-explore-agent only when task requires codebase understanding
|
||||
- **Interactive Clarification**: Asks follow-up questions after exploration to gather missing information
|
||||
- **Adaptive Planning**:
|
||||
- Simple tasks: Direct planning by current Claude
|
||||
- Complex tasks: Delegates to cli-planning-agent for detailed breakdown
|
||||
- **Two-Dimensional Confirmation**: Single user interaction for task approval + execution method selection
|
||||
- **Direct Execution**: Immediate dispatch to selected execution method (agent or CLI)
|
||||
- **Live Progress Tracking**: Real-time TodoWrite updates during execution
|
||||
|
||||
## Comparison with Other Commands
|
||||
|
||||
| Feature | lite-plan | /cli:mode:plan | /workflow:plan |
|
||||
|---------|-----------|----------------|----------------|
|
||||
| Workflow Adaptation | Dynamic (intelligent) | Fixed | Fixed |
|
||||
| Code Exploration | Smart (when needed) | No | Always (context-search) |
|
||||
| Clarification | Yes (interactive) | No | No |
|
||||
| Planning Strategy | Adaptive (simple/complex) | Fixed template | Agent-based |
|
||||
| User Interaction | Two-dimensional | No | Minimal |
|
||||
| Direct Execution | Yes (immediate) | Yes (immediate) | No (requires /workflow:execute) |
|
||||
| Progress Tracking | Yes (TodoWrite live) | No | Yes (session-based) |
|
||||
| Execution Time | Fast (1-3 min) | Fast (2-5 min) | Slow (5-10 min) |
|
||||
| Tool Selection | User choice | --tool flag | Fixed (agent only) |
|
||||
| File Artifacts | No | No | Yes (IMPL_PLAN.md + JSON) |
|
||||
|
||||
## Usage
|
||||
|
||||
### Command Syntax
|
||||
```bash
|
||||
/workflow:lite-plan [FLAGS] <TASK_DESCRIPTION>
|
||||
|
||||
# Flags
|
||||
--tool <tool-name> Preset CLI tool (claude|gemini|qwen|codex); if not provided, user selects during confirmation
|
||||
--quick Skip code exploration phase (fast mode, completes within 60 seconds)
|
||||
|
||||
# Arguments
|
||||
<task-description> Task description or path to .md file (required)
|
||||
```
|
||||
|
||||
### Usage Examples
|
||||
```bash
|
||||
# Standard planning with full interaction
|
||||
/workflow:lite-plan "Implement user authentication with JWT tokens"
|
||||
# -> Shows plan, user confirms, selects tool, immediate execution
|
||||
|
||||
# Quick mode with preset tool
|
||||
/workflow:lite-plan --quick --tool gemini "Refactor logging module for better performance"
|
||||
# -> Skips exploration, user confirms plan, executes with Gemini
|
||||
|
||||
# Codex direct execution preset
|
||||
/workflow:lite-plan --tool codex "Add unit tests for authentication service"
|
||||
# -> User only confirms plan, executes with Codex immediately
|
||||
|
||||
# Agent mode with Claude
|
||||
/workflow:lite-plan "Design new API endpoints for payment processing"
|
||||
# -> User selects Claude agent, immediate execution
|
||||
```
|
||||
|
||||
## Execution Process
|
||||
|
||||
### Workflow Overview
|
||||
|
||||
```
|
||||
User Input ("/workflow:lite-plan \"task\"")
|
||||
|
|
||||
v
|
||||
[Phase 1] Task Analysis & Exploration Decision (10-20 seconds)
|
||||
-> Analyze task description
|
||||
-> Decision: Need exploration? (Yes/No/--quick override)
|
||||
-> If Yes: Launch cli-explore-agent
|
||||
-> Output: exploration findings (if performed)
|
||||
|
|
||||
v
|
||||
[Phase 2] Clarification (Optional, user interaction)
|
||||
-> If exploration revealed ambiguities or missing info
|
||||
-> AskUserQuestion: Gather clarifications
|
||||
-> Update task context with user responses
|
||||
-> If no clarification needed: Skip to Phase 3
|
||||
|
|
||||
v
|
||||
[Phase 3] Complexity Assessment & Planning (20-60 seconds)
|
||||
-> Assess task complexity (Low/Medium/High)
|
||||
-> Decision: Planning strategy
|
||||
- Low: Direct planning (current Claude)
|
||||
- Medium/High: Delegate to cli-planning-agent
|
||||
-> Output: Task breakdown with execution approach
|
||||
|
|
||||
v
|
||||
[Phase 4] Task Confirmation & Execution Selection (User interaction)
|
||||
-> Display task breakdown and approach
|
||||
-> AskUserQuestion: Two dimensions
|
||||
1. Confirm task (Yes/Modify/Cancel)
|
||||
2. Execution method (Direct/CLI)
|
||||
-> If confirmed: Proceed to Phase 5
|
||||
-> If modify: Re-run planning with feedback
|
||||
-> If cancel: Exit
|
||||
|
|
||||
v
|
||||
[Phase 5] Execution & Progress Tracking
|
||||
-> Create TodoWrite task list from breakdown
|
||||
-> Launch selected execution (agent or CLI)
|
||||
-> Track progress with TodoWrite updates
|
||||
-> Real-time status displayed to user
|
||||
|
|
||||
v
|
||||
Execution Complete
|
||||
```
|
||||
|
||||
### Task Management Pattern
|
||||
|
||||
- TodoWrite creates task list before execution starts (Phase 5)
|
||||
- Tasks marked as in_progress/completed during execution
|
||||
- Real-time progress updates visible to user
|
||||
- No intermediate file artifacts generated
|
||||
|
||||
## Detailed Phase Execution
|
||||
|
||||
### Phase 1: Task Analysis & Exploration Decision
|
||||
|
||||
**Operations**:
|
||||
- Analyze task description to determine if code exploration is needed
|
||||
- Decision logic:
|
||||
```javascript
|
||||
needsExploration = (
|
||||
task.mentions_specific_files ||
|
||||
task.requires_codebase_context ||
|
||||
task.needs_architecture_understanding ||
|
||||
task.modifies_existing_code
|
||||
) && !flags.includes('--quick')
|
||||
```
|
||||
|
||||
**Decision Criteria**:
|
||||
|
||||
| Task Type | Needs Exploration | Reason |
|
||||
|-----------|-------------------|--------|
|
||||
| "Implement new feature X" | Maybe | Depends on integration with existing code |
|
||||
| "Refactor module Y" | Yes | Needs understanding of current implementation |
|
||||
| "Add tests for Z" | Yes | Needs to understand code structure |
|
||||
| "Create new standalone utility" | No | Self-contained, no existing code context |
|
||||
| "Update documentation" | No | Doesn't require code exploration |
|
||||
| "Fix bug in function F" | Yes | Needs to understand implementation |
|
||||
|
||||
**If Exploration Needed**:
|
||||
- Launch cli-explore-agent with task-specific focus
|
||||
- Agent call format:
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="cli-explore-agent",
|
||||
description="Analyze codebase for task context",
|
||||
prompt=`
|
||||
Task: ${task_description}
|
||||
|
||||
Analyze and return the following information in structured format:
|
||||
1. Project Structure: Overall architecture and module organization
|
||||
2. Relevant Files: List of files that will be affected by this task (with paths)
|
||||
3. Current Implementation Patterns: Existing code patterns, conventions, and styles
|
||||
4. Dependencies: External dependencies and internal module dependencies
|
||||
5. Integration Points: Where this task connects with existing code
|
||||
6. Architecture Constraints: Technical limitations or requirements
|
||||
7. Clarification Needs: Ambiguities or missing information requiring user input
|
||||
|
||||
Time Limit: 60 seconds
|
||||
|
||||
Output Format: Return a JSON-like structured object with the above fields populated.
|
||||
Include specific file paths, pattern examples, and clear questions for clarifications.
|
||||
`
|
||||
)
|
||||
```
|
||||
|
||||
**Expected Return Structure**:
|
||||
```javascript
|
||||
explorationContext = {
|
||||
project_structure: "Description of overall architecture",
|
||||
relevant_files: ["src/auth/service.ts", "src/middleware/auth.ts", ...],
|
||||
patterns: "Description of existing patterns (e.g., 'Uses dependency injection pattern', 'React hooks convention')",
|
||||
dependencies: "List of dependencies and integration points",
|
||||
integration_points: "Where this connects with existing code",
|
||||
constraints: "Technical constraints (e.g., 'Must use existing auth library', 'No breaking changes')",
|
||||
clarification_needs: [
|
||||
{
|
||||
question: "Which authentication method to use?",
|
||||
context: "Found both JWT and Session patterns",
|
||||
options: ["JWT tokens", "Session-based", "Hybrid approach"]
|
||||
},
|
||||
// ... more clarification questions
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Output Processing**:
|
||||
- Store exploration findings in `explorationContext`
|
||||
- Extract `clarification_needs` array from exploration results
|
||||
- Set `needsClarification = (clarification_needs.length > 0)`
|
||||
- Use clarification_needs to generate Phase 2 questions
|
||||
|
||||
**Progress Tracking**:
|
||||
- Mark Phase 1 as completed
|
||||
- If needsClarification: Mark Phase 2 as in_progress
|
||||
- Else: Skip to Phase 3
|
||||
|
||||
**Expected Duration**: 10-20 seconds (analysis) + 30-60 seconds (exploration if needed)
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Clarification (Optional)
|
||||
|
||||
**Skip Condition**: Only run if Phase 1 set `needsClarification = true`
|
||||
|
||||
**Operations**:
|
||||
- Review `explorationContext.clarification_needs` from Phase 1
|
||||
- Generate AskUserQuestion based on exploration findings
|
||||
- Focus on ambiguities that affect implementation approach
|
||||
|
||||
**AskUserQuestion Call** (simplified reference):
|
||||
```javascript
|
||||
// Use clarification_needs from exploration to build questions
|
||||
AskUserQuestion({
|
||||
questions: explorationContext.clarification_needs.map(need => ({
|
||||
question: `${need.context}\n\n${need.question}`,
|
||||
header: "Clarification",
|
||||
multiSelect: false,
|
||||
options: need.options.map(opt => ({
|
||||
label: opt,
|
||||
description: `Use ${opt} approach`
|
||||
}))
|
||||
}))
|
||||
})
|
||||
```
|
||||
|
||||
**Output Processing**:
|
||||
- Collect user responses and store in `clarificationContext`
|
||||
- Format: `{ question_id: selected_answer, ... }`
|
||||
- This context will be passed to Phase 3 planning
|
||||
|
||||
**Progress Tracking**:
|
||||
- Mark Phase 2 as completed
|
||||
- Mark Phase 3 as in_progress
|
||||
|
||||
**Expected Duration**: User-dependent (typically 30-60 seconds)
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Complexity Assessment & Planning
|
||||
|
||||
**Operations**:
|
||||
- Assess task complexity based on multiple factors
|
||||
- Select appropriate planning strategy
|
||||
- Generate task breakdown using selected method
|
||||
|
||||
**Complexity Assessment Factors**:
|
||||
```javascript
|
||||
complexityScore = {
|
||||
file_count: exploration.files_to_modify.length,
|
||||
integration_points: exploration.dependencies.length,
|
||||
architecture_changes: exploration.requires_architecture_change,
|
||||
technology_stack: exploration.unfamiliar_technologies.length,
|
||||
task_scope: (task.estimated_steps > 5),
|
||||
cross_cutting_concerns: exploration.affects_multiple_modules
|
||||
}
|
||||
|
||||
// Calculate complexity
|
||||
if (complexityScore < 3) complexity = "Low"
|
||||
else if (complexityScore < 6) complexity = "Medium"
|
||||
else complexity = "High"
|
||||
```
|
||||
|
||||
**Complexity Levels**:
|
||||
|
||||
| Level | Characteristics | Planning Strategy |
|
||||
|-------|----------------|-------------------|
|
||||
| Low | 1-2 files, simple changes, clear requirements | Direct planning (current Claude) |
|
||||
| Medium | 3-5 files, moderate integration, some ambiguity | Delegate to cli-planning-agent |
|
||||
| High | 6+ files, complex architecture, high uncertainty | Delegate to cli-planning-agent with detailed analysis |
|
||||
|
||||
**Planning Execution**:
|
||||
|
||||
**Option A: Direct Planning (Low Complexity)**
|
||||
```javascript
|
||||
// Current Claude generates plan directly
|
||||
planObject = {
|
||||
summary: "Brief overview of what needs to be done",
|
||||
approach: "Step-by-step implementation strategy",
|
||||
tasks: [
|
||||
"Task 1: Specific action with file references",
|
||||
"Task 2: Specific action with file references",
|
||||
// ... 3-5 tasks
|
||||
],
|
||||
complexity: "Low",
|
||||
estimated_time: "15-30 minutes"
|
||||
}
|
||||
```
|
||||
|
||||
**Option B: Agent-Based Planning (Medium/High Complexity)**
|
||||
```javascript
|
||||
// Delegate to cli-planning-agent
|
||||
Task(
|
||||
subagent_type="cli-planning-agent",
|
||||
description="Generate detailed implementation plan",
|
||||
prompt=`
|
||||
Task: ${task_description}
|
||||
|
||||
Exploration Context:
|
||||
${JSON.stringify(explorationContext, null, 2)}
|
||||
|
||||
User Clarifications:
|
||||
${JSON.stringify(clarificationContext, null, 2) || "None provided"}
|
||||
|
||||
Complexity Level: ${complexity}
|
||||
|
||||
Generate a detailed implementation plan with the following components:
|
||||
|
||||
1. Summary: 2-3 sentence overview of the implementation
|
||||
2. Approach: High-level implementation strategy
|
||||
3. Task Breakdown: 5-10 specific, actionable tasks
|
||||
- Each task should specify:
|
||||
* What to do
|
||||
* Which files to modify/create
|
||||
* Dependencies on other tasks (if any)
|
||||
4. Task Dependencies: Explicit ordering requirements (e.g., "Task 2 depends on Task 1")
|
||||
5. Risks: Potential issues and mitigation strategies (for Medium/High complexity)
|
||||
6. Estimated Time: Total implementation time estimate
|
||||
7. Recommended Execution: "Direct" (agent) or "CLI" (autonomous tool)
|
||||
|
||||
Output Format: Return a structured object with these fields:
|
||||
{
|
||||
summary: string,
|
||||
approach: string,
|
||||
tasks: string[],
|
||||
dependencies: string[] (optional),
|
||||
risks: string[] (optional),
|
||||
estimated_time: string,
|
||||
recommended_execution: "Direct" | "CLI"
|
||||
}
|
||||
|
||||
Ensure tasks are specific, with file paths and clear acceptance criteria.
|
||||
`
|
||||
)
|
||||
|
||||
// Agent returns detailed plan
|
||||
planObject = agent_output.parse()
|
||||
```
|
||||
|
||||
**Expected Return Structure**:
|
||||
```javascript
|
||||
planObject = {
|
||||
summary: "Implement JWT-based authentication system with middleware integration",
|
||||
approach: "Create auth service layer, implement JWT utilities, add middleware, update routes",
|
||||
tasks: [
|
||||
"Create authentication service in src/auth/service.ts with login/logout/verify methods",
|
||||
"Implement JWT token utilities in src/auth/jwt.ts (generate, verify, refresh)",
|
||||
"Add authentication middleware to src/middleware/auth.ts",
|
||||
"Update API routes in src/routes/*.ts to use auth middleware",
|
||||
"Add integration tests for auth flow in tests/auth.test.ts"
|
||||
],
|
||||
dependencies: [
|
||||
"Task 3 depends on Task 2 (middleware needs JWT utilities)",
|
||||
"Task 4 depends on Task 3 (routes need middleware)",
|
||||
"Task 5 depends on Tasks 1-4 (tests need complete implementation)"
|
||||
],
|
||||
risks: [
|
||||
"Token refresh timing may conflict with existing session logic - test thoroughly",
|
||||
"Breaking change if existing auth is in use - plan migration strategy"
|
||||
],
|
||||
estimated_time: "30-45 minutes",
|
||||
recommended_execution: "CLI" // Based on clear requirements and straightforward implementation
|
||||
}
|
||||
```
|
||||
|
||||
**Output Structure**:
|
||||
```javascript
|
||||
planObject = {
|
||||
summary: "2-3 sentence overview",
|
||||
approach: "Implementation strategy",
|
||||
tasks: [
|
||||
"Task 1: ...",
|
||||
"Task 2: ...",
|
||||
// ... 3-10 tasks based on complexity
|
||||
],
|
||||
complexity: "Low|Medium|High",
|
||||
dependencies: ["task1 -> task2", ...], // if Medium/High
|
||||
risks: ["risk1", "risk2", ...], // if High
|
||||
estimated_time: "X minutes",
|
||||
recommended_execution: "Direct|CLI"
|
||||
}
|
||||
```
|
||||
|
||||
**Progress Tracking**:
|
||||
- Mark Phase 3 as completed
|
||||
- Mark Phase 4 as in_progress
|
||||
|
||||
**Expected Duration**:
|
||||
- Low complexity: 20-30 seconds (direct)
|
||||
- Medium/High complexity: 40-60 seconds (agent-based)
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Task Confirmation & Execution Selection
|
||||
|
||||
**User Interaction Flow**: Two-dimensional confirmation (task + execution method)
|
||||
|
||||
**Operations**:
|
||||
- Display plan summary with full task breakdown
|
||||
- Collect two-dimensional user input: Task confirmation + Execution method selection
|
||||
- Support modification flow if user requests changes
|
||||
|
||||
**Question 1: Task Confirmation**
|
||||
|
||||
Display plan to user and ask for confirmation:
|
||||
- Show: summary, approach, task breakdown, dependencies, risks, complexity, estimated time
|
||||
- Options: "Confirm" / "Modify" / "Cancel"
|
||||
- If Modify: Collect feedback via "Other" option, re-run Phase 3 with modifications
|
||||
- If Cancel: Exit workflow
|
||||
- If Confirm: Proceed to Question 2
|
||||
|
||||
**Question 2: Execution Method Selection** (Only if task confirmed)
|
||||
|
||||
Ask user to select execution method:
|
||||
- Show recommendation from `planObject.recommended_execution`
|
||||
- Options:
|
||||
- "Direct - Execute with Agent" (@code-developer)
|
||||
- "CLI - Gemini" (gemini-2.5-pro)
|
||||
- "CLI - Codex" (gpt-5)
|
||||
- "CLI - Qwen" (coder-model)
|
||||
- Store selection for Phase 5 execution
|
||||
|
||||
**Simplified AskUserQuestion Reference**:
|
||||
```javascript
|
||||
// Question 1: Task Confirmation
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: `[Display plan with all details]\n\nDo you confirm this plan?`,
|
||||
header: "Confirm Plan",
|
||||
options: [
|
||||
{ label: "Confirm", description: "Proceed to execution" },
|
||||
{ label: "Modify", description: "Adjust plan" },
|
||||
{ label: "Cancel", description: "Abort" }
|
||||
]
|
||||
}]
|
||||
})
|
||||
|
||||
// Question 2: Execution Method (if confirmed)
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: `Select execution method:\n[Show recommendation and tool descriptions]`,
|
||||
header: "Execution Method",
|
||||
options: [
|
||||
{ label: "Direct - Agent", description: "Interactive execution" },
|
||||
{ label: "CLI - Gemini", description: "gemini-2.5-pro" },
|
||||
{ label: "CLI - Codex", description: "gpt-5" },
|
||||
{ label: "CLI - Qwen", description: "coder-model" }
|
||||
]
|
||||
}]
|
||||
})
|
||||
```
|
||||
|
||||
**Decision Flow**:
|
||||
```
|
||||
Task Confirmation:
|
||||
├─ Confirm → Execution Method Selection → Phase 5
|
||||
├─ Modify → Collect feedback → Re-run Phase 3
|
||||
└─ Cancel → Exit (no execution)
|
||||
|
||||
Execution Method Selection:
|
||||
├─ Direct - Execute with Agent → Launch @code-developer
|
||||
├─ CLI - Gemini → Build and execute Gemini command
|
||||
├─ CLI - Codex → Build and execute Codex command
|
||||
└─ CLI - Qwen → Build and execute Qwen command
|
||||
```
|
||||
|
||||
**Progress Tracking**:
|
||||
- Mark Phase 4 as completed
|
||||
- Mark Phase 5 as in_progress
|
||||
|
||||
**Expected Duration**: User-dependent (1-3 minutes typical)
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: Execution & Progress Tracking
|
||||
|
||||
**Operations**:
|
||||
- Create TodoWrite task list from plan breakdown
|
||||
- Launch selected execution method (agent or CLI)
|
||||
- Track execution progress with real-time TodoWrite updates
|
||||
- Display status to user
|
||||
|
||||
**Step 5.1: Create TodoWrite Task List**
|
||||
|
||||
**Before execution starts**, create task list:
|
||||
```javascript
|
||||
TodoWrite({
|
||||
todos: planObject.tasks.map((task, index) => ({
|
||||
content: task,
|
||||
status: "pending",
|
||||
activeForm: task.replace(/^(.*?):/, "$1ing:") // "Implement X" -> "Implementing X"
|
||||
}))
|
||||
})
|
||||
```
|
||||
|
||||
**Example Task List**:
|
||||
```
|
||||
[ ] Implement authentication service in src/auth/service.ts
|
||||
[ ] Create JWT token utilities in src/auth/jwt.ts
|
||||
[ ] Add authentication middleware to src/middleware/auth.ts
|
||||
[ ] Update API routes to use authentication
|
||||
[ ] Add integration tests for auth flow
|
||||
```
|
||||
|
||||
**Step 5.2: Launch Execution**
|
||||
|
||||
Based on user selection in Phase 4, execute appropriate method:
|
||||
|
||||
#### Option A: Direct Execution with Agent
|
||||
|
||||
**Operations**:
|
||||
- Launch @code-developer agent with full plan context
|
||||
- Agent receives exploration findings, clarifications, and task breakdown
|
||||
- Agent call format:
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="code-developer",
|
||||
description="Implement planned tasks with progress tracking",
|
||||
prompt=`
|
||||
Implement the following tasks with TodoWrite progress updates:
|
||||
|
||||
Summary: ${planObject.summary}
|
||||
|
||||
Task Breakdown:
|
||||
${planObject.tasks.map((t, i) => `${i+1}. ${t}`).join('\n')}
|
||||
|
||||
${planObject.dependencies ? `\nTask Dependencies:\n${planObject.dependencies.join('\n')}` : ''}
|
||||
|
||||
Implementation Approach:
|
||||
${planObject.approach}
|
||||
|
||||
Code Context:
|
||||
${explorationContext || "No exploration performed"}
|
||||
|
||||
${clarificationContext ? `\nClarifications:\n${clarificationContext}` : ''}
|
||||
|
||||
${planObject.risks ? `\nRisks to Consider:\n${planObject.risks.join('\n')}` : ''}
|
||||
|
||||
IMPORTANT Instructions:
|
||||
- Update TodoWrite as you complete each task (mark as completed)
|
||||
- Follow task dependencies if specified
|
||||
- Implement tasks in sequence unless independent
|
||||
- Test functionality as you go
|
||||
- Handle risks proactively
|
||||
`
|
||||
)
|
||||
```
|
||||
|
||||
**Agent Responsibilities**:
|
||||
- Mark tasks as in_progress when starting
|
||||
- Mark tasks as completed when finished
|
||||
- Update TodoWrite in real-time for user visibility
|
||||
|
||||
#### Option B: CLI Execution (Gemini/Codex/Qwen)
|
||||
|
||||
**Operations**:
|
||||
- Build CLI command with comprehensive context
|
||||
- Execute CLI tool with write permissions
|
||||
- Monitor CLI output and update TodoWrite based on progress indicators
|
||||
- Parse CLI completion signals to mark tasks as done
|
||||
|
||||
**Command Format (Gemini)** - Full context with exploration and clarifications:
|
||||
```bash
|
||||
gemini -p "
|
||||
PURPOSE: Implement planned tasks with full context from exploration and planning
|
||||
TASK:
|
||||
${planObject.tasks.map((t, i) => `• ${t}`).join('\n')}
|
||||
|
||||
MODE: write
|
||||
|
||||
CONTEXT: @**/* | Memory: Implementation plan from lite-plan workflow
|
||||
|
||||
## Exploration Findings
|
||||
${explorationContext ? `
|
||||
Project Structure:
|
||||
${explorationContext.project_structure || 'Not available'}
|
||||
|
||||
Relevant Files:
|
||||
${explorationContext.relevant_files?.join('\n') || 'Not specified'}
|
||||
|
||||
Current Implementation Patterns:
|
||||
${explorationContext.patterns || 'Not analyzed'}
|
||||
|
||||
Dependencies and Integration Points:
|
||||
${explorationContext.dependencies || 'Not specified'}
|
||||
|
||||
Architecture Constraints:
|
||||
${explorationContext.constraints || 'None identified'}
|
||||
` : 'No exploration performed (task did not require codebase context)'}
|
||||
|
||||
## User Clarifications
|
||||
${clarificationContext ? `
|
||||
The following clarifications were provided by the user after exploration:
|
||||
${Object.entries(clarificationContext).map(([q, a]) => `Q: ${q}\nA: ${a}`).join('\n\n')}
|
||||
` : 'No clarifications needed'}
|
||||
|
||||
## Implementation Plan Context
|
||||
Task Summary: ${planObject.summary}
|
||||
|
||||
Implementation Approach:
|
||||
${planObject.approach}
|
||||
|
||||
${planObject.dependencies ? `
|
||||
Task Dependencies (execute in order):
|
||||
${planObject.dependencies.join('\n')}
|
||||
` : ''}
|
||||
|
||||
${planObject.risks ? `
|
||||
Identified Risks:
|
||||
${planObject.risks.join('\n')}
|
||||
` : ''}
|
||||
|
||||
Complexity Level: ${planObject.complexity}
|
||||
Estimated Time: ${planObject.estimated_time}
|
||||
|
||||
EXPECTED: All tasks implemented following the plan approach, with proper error handling and testing
|
||||
|
||||
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/02-implement-feature.txt) | Follow implementation approach exactly | Handle identified risks proactively | write=CREATE/MODIFY/DELETE
|
||||
" -m gemini-2.5-pro --approval-mode yolo
|
||||
```
|
||||
|
||||
**Command Format (Codex)** - Session-based with resume support:
|
||||
|
||||
**First Execution (Establish Session)**:
|
||||
```bash
|
||||
codex --full-auto exec "
|
||||
TASK: ${planObject.summary}
|
||||
|
||||
## Task Breakdown
|
||||
${planObject.tasks.map((t, i) => `${i+1}. ${t}`).join('\n')}
|
||||
|
||||
${planObject.dependencies ? `\n## Task Dependencies\n${planObject.dependencies.join('\n')}` : ''}
|
||||
|
||||
## Implementation Approach
|
||||
${planObject.approach}
|
||||
|
||||
## Code Context from Exploration
|
||||
${explorationContext ? `
|
||||
Project Structure: ${explorationContext.project_structure || 'Standard structure'}
|
||||
Relevant Files: ${explorationContext.relevant_files?.join(', ') || 'TBD'}
|
||||
Current Patterns: ${explorationContext.patterns || 'Follow existing conventions'}
|
||||
Integration Points: ${explorationContext.dependencies || 'None specified'}
|
||||
Constraints: ${explorationContext.constraints || 'None'}
|
||||
` : 'No prior exploration - analyze codebase as needed'}
|
||||
|
||||
${clarificationContext ? `\n## User Clarifications\n${Object.entries(clarificationContext).map(([q, a]) => `${q}: ${a}`).join('\n')}` : ''}
|
||||
|
||||
${planObject.risks ? `\n## Risks to Handle\n${planObject.risks.join('\n')}` : ''}
|
||||
|
||||
## Execution Instructions
|
||||
- Complete all tasks following the breakdown sequence
|
||||
- Respect task dependencies if specified
|
||||
- Test functionality as you implement
|
||||
- Handle identified risks proactively
|
||||
- Create session for potential resume if needed
|
||||
|
||||
Complexity: ${planObject.complexity}
|
||||
" -m gpt-5 --skip-git-repo-check -s danger-full-access
|
||||
```
|
||||
|
||||
**Subsequent Executions (Resume if needed)**:
|
||||
```bash
|
||||
# If first execution fails or is interrupted, can resume:
|
||||
codex --full-auto exec "
|
||||
Continue implementation from previous session.
|
||||
|
||||
Remaining tasks:
|
||||
${remaining_tasks.map((t, i) => `${i+1}. ${t}`).join('\n')}
|
||||
|
||||
Maintain context from previous execution.
|
||||
" resume --last -m gpt-5 --skip-git-repo-check -s danger-full-access
|
||||
```
|
||||
|
||||
**Codex Session Strategy**:
|
||||
- First execution establishes full context and creates session
|
||||
- If execution is interrupted or fails, use `resume --last` to continue
|
||||
- Resume inherits all context from original execution
|
||||
- Useful for complex tasks that may hit timeouts or require iteration
|
||||
|
||||
**Command Format (Qwen)** - Full context similar to Gemini:
|
||||
```bash
|
||||
qwen -p "
|
||||
PURPOSE: Implement planned tasks with comprehensive context
|
||||
|
||||
TASK:
|
||||
${planObject.tasks.map((t, i) => `• ${t}`).join('\n')}
|
||||
|
||||
MODE: write
|
||||
|
||||
CONTEXT: @**/* | Memory: Full implementation context from lite-plan
|
||||
|
||||
## Code Exploration Results
|
||||
${explorationContext ? `
|
||||
Analyzed Project Structure:
|
||||
${explorationContext.project_structure || 'Standard structure'}
|
||||
|
||||
Key Files to Modify:
|
||||
${explorationContext.relevant_files?.join('\n') || 'To be determined during implementation'}
|
||||
|
||||
Existing Code Patterns:
|
||||
${explorationContext.patterns || 'Follow codebase conventions'}
|
||||
|
||||
Dependencies:
|
||||
${explorationContext.dependencies || 'None specified'}
|
||||
|
||||
Constraints:
|
||||
${explorationContext.constraints || 'None identified'}
|
||||
` : 'No exploration performed - analyze codebase patterns as you implement'}
|
||||
|
||||
## Clarifications from User
|
||||
${clarificationContext ? `
|
||||
${Object.entries(clarificationContext).map(([question, answer]) => `
|
||||
Question: ${question}
|
||||
Answer: ${answer}
|
||||
`).join('\n')}
|
||||
` : 'No additional clarifications provided'}
|
||||
|
||||
## Implementation Strategy
|
||||
Summary: ${planObject.summary}
|
||||
|
||||
Approach:
|
||||
${planObject.approach}
|
||||
|
||||
${planObject.dependencies ? `
|
||||
Task Order (follow sequence):
|
||||
${planObject.dependencies.join('\n')}
|
||||
` : ''}
|
||||
|
||||
${planObject.risks ? `
|
||||
Risk Mitigation:
|
||||
${planObject.risks.join('\n')}
|
||||
` : ''}
|
||||
|
||||
Task Complexity: ${planObject.complexity}
|
||||
Time Estimate: ${planObject.estimated_time}
|
||||
|
||||
EXPECTED: Complete implementation with tests and proper error handling
|
||||
|
||||
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/02-implement-feature.txt) | Follow approach strictly | Test thoroughly | write=CREATE/MODIFY/DELETE
|
||||
" -m coder-model --approval-mode yolo
|
||||
```
|
||||
|
||||
**Execution with Progress Tracking**:
|
||||
```javascript
|
||||
// Launch CLI in background
|
||||
bash_result = Bash(
|
||||
command=cli_command,
|
||||
timeout=600000, // 10 minutes
|
||||
run_in_background=true
|
||||
)
|
||||
|
||||
// Monitor output and update TodoWrite
|
||||
// Parse CLI output for task completion indicators
|
||||
// Update TodoWrite when tasks complete
|
||||
// Example: When CLI outputs "✓ Task 1 complete" -> Mark task 1 as completed
|
||||
```
|
||||
|
||||
**CLI Progress Monitoring**:
|
||||
- Parse CLI output for completion keywords ("done", "complete", "✓", etc.)
|
||||
- Update corresponding TodoWrite tasks based on progress
|
||||
- Provide real-time visibility to user
|
||||
|
||||
**Step 5.3: Track Execution Progress**
|
||||
|
||||
**Real-time TodoWrite Updates**:
|
||||
```javascript
|
||||
// As execution progresses, update task status:
|
||||
|
||||
// Task started
|
||||
TodoWrite({
|
||||
todos: [
|
||||
{ content: "Implement auth service", status: "in_progress", activeForm: "Implementing auth service" },
|
||||
{ content: "Create JWT utilities", status: "pending", activeForm: "Creating JWT utilities" },
|
||||
// ...
|
||||
]
|
||||
})
|
||||
|
||||
// Task completed
|
||||
TodoWrite({
|
||||
todos: [
|
||||
{ content: "Implement auth service", status: "completed", activeForm: "Implementing auth service" },
|
||||
{ content: "Create JWT utilities", status: "in_progress", activeForm: "Creating JWT utilities" },
|
||||
// ...
|
||||
]
|
||||
})
|
||||
```
|
||||
|
||||
**User Visibility**:
|
||||
- User sees real-time task progress
|
||||
- Current task highlighted as "in_progress"
|
||||
- Completed tasks marked with checkmark
|
||||
- Pending tasks remain unchecked
|
||||
|
||||
**Progress Tracking**:
|
||||
- Mark Phase 5 as in_progress throughout execution
|
||||
- Mark Phase 5 as completed when all tasks done
|
||||
- Final status summary displayed to user
|
||||
|
||||
**Expected Duration**: Varies by task complexity and execution method
|
||||
- Low complexity: 5-15 minutes
|
||||
- Medium complexity: 15-45 minutes
|
||||
- High complexity: 45-120 minutes
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Workflow Intelligence
|
||||
|
||||
1. **Dynamic Adaptation**: Workflow automatically adjusts based on task characteristics
|
||||
- Smart exploration: Only runs when task requires codebase context
|
||||
- Adaptive planning: Simple tasks get direct planning, complex tasks use specialized agent
|
||||
- Context-aware clarification: Only asks questions when truly needed
|
||||
- Reduces unnecessary steps while maintaining thoroughness
|
||||
|
||||
2. **Progressive Clarification**: Gather information at the right time
|
||||
- Phase 1: Explore codebase to understand current state
|
||||
- Phase 2: Ask clarifying questions based on exploration findings
|
||||
- Phase 3: Plan with complete context (task + exploration + clarifications)
|
||||
- Avoids premature assumptions and reduces rework
|
||||
|
||||
3. **Complexity-Aware Planning**: Planning strategy matches task complexity
|
||||
- Low complexity (1-2 files): Direct planning by current Claude (fast, 20-30s)
|
||||
- Medium complexity (3-5 files): CLI planning agent (detailed, 40-50s)
|
||||
- High complexity (6+ files): CLI planning agent with risk analysis (thorough, 50-60s)
|
||||
- Balances speed and thoroughness appropriately
|
||||
|
||||
4. **Two-Dimensional Confirmation**: Separate task approval from execution method
|
||||
- First dimension: Confirm/Modify/Cancel plan
|
||||
- Second dimension: Direct execution vs CLI execution
|
||||
- Allows plan refinement without re-selecting execution method
|
||||
- Supports iterative planning with user feedback
|
||||
|
||||
### Task Management
|
||||
|
||||
1. **Live Progress Tracking**: TodoWrite provides real-time execution visibility
|
||||
- Tasks created before execution starts
|
||||
- Updated in real-time as work progresses
|
||||
- User sees current task being worked on
|
||||
- Clear completion status throughout execution
|
||||
|
||||
2. **Phase-Based Organization**: 5 distinct phases with clear transitions
|
||||
- Phase 1: Task Analysis & Exploration (automatic)
|
||||
- Phase 2: Clarification (conditional, interactive)
|
||||
- Phase 3: Planning (automatic, adaptive)
|
||||
- Phase 4: Confirmation (interactive, two-dimensional)
|
||||
- Phase 5: Execution & Tracking (automatic with live updates)
|
||||
|
||||
3. **Flexible Task Counts**: Task breakdown adapts to complexity
|
||||
- Low complexity: 3-5 tasks (focused)
|
||||
- Medium complexity: 5-7 tasks (detailed)
|
||||
- High complexity: 7-10 tasks (comprehensive)
|
||||
- Avoids artificial constraints while maintaining focus
|
||||
|
||||
4. **Dependency Tracking**: Medium/High complexity tasks include dependencies
|
||||
- Explicit task ordering when sequence matters
|
||||
- Parallel execution hints when tasks are independent
|
||||
- Risk flagging for complex interactions
|
||||
- Helps agent/CLI execute correctly
|
||||
|
||||
### Planning Standards
|
||||
|
||||
1. **Context-Rich Planning**: Plans include all relevant context
|
||||
- Exploration findings (code structure, patterns, constraints)
|
||||
- User clarifications (requirements, preferences, decisions)
|
||||
- Complexity assessment (risks, dependencies, time estimates)
|
||||
- Execution recommendations (Direct vs CLI, specific tool)
|
||||
|
||||
2. **Modification Support**: Plans can be iteratively refined
|
||||
- User can request plan modifications in Phase 4
|
||||
- Feedback incorporated into re-planning
|
||||
- No need to restart from scratch
|
||||
- Supports collaborative planning workflow
|
||||
|
||||
3. **No File Artifacts**: All planning stays in memory
|
||||
- Faster workflow without I/O overhead
|
||||
- Cleaner workspace
|
||||
- Plan context passed directly to execution
|
||||
- Reduces complexity and maintenance
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Common Errors
|
||||
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| Phase 1 Exploration Failure | cli-explore-agent unavailable or timeout | Skip exploration, set `explorationContext = null`, log warning, continue to Phase 2/3 with task description only |
|
||||
| Phase 2 Clarification Timeout | User no response > 5 minutes | Use exploration findings as-is without clarification, proceed to Phase 3 with warning |
|
||||
| Phase 3 Planning Agent Failure | cli-planning-agent unavailable or timeout | Fallback to direct planning by current Claude (simplified plan), continue to Phase 4 |
|
||||
| Phase 3 Planning Timeout | Planning takes > 90 seconds | Generate simplified direct plan, mark as "Quick Plan", continue to Phase 4 with reduced detail |
|
||||
| Phase 4 Confirmation Timeout | User no response > 5 minutes | Save plan context to temporary var, display resume instructions, exit gracefully |
|
||||
| Phase 4 Modification Loop | User requests modify > 3 times | Suggest breaking task into smaller pieces or using /workflow:plan for comprehensive planning |
|
||||
| Phase 5 CLI Tool Unavailable | Selected CLI tool not installed | Show installation instructions, offer to re-select (Direct execution or different CLI) |
|
||||
| Phase 5 Execution Failure | Agent/CLI crashes or errors | Display error details, save partial progress from TodoWrite, suggest manual recovery or retry |
|
||||
|
||||
## Input/Output
|
||||
|
||||
### Input Requirements
|
||||
- Task description: String or path to .md file (required)
|
||||
- Should be specific and concrete
|
||||
- Can include context about existing code or requirements
|
||||
- Examples:
|
||||
- "Implement user authentication with JWT tokens"
|
||||
- "Refactor logging module for better performance"
|
||||
- "Add unit tests for authentication service"
|
||||
- Flags (optional):
|
||||
- `--tool <name>`: Preset execution tool (claude|gemini|codex|qwen)
|
||||
- `--quick`: Skip code exploration phase
|
||||
|
||||
### Output Format
|
||||
|
||||
**In-Memory Plan Object**:
|
||||
```javascript
|
||||
{
|
||||
summary: "2-3 sentence overview of implementation",
|
||||
approach: "High-level implementation strategy",
|
||||
tasks: [
|
||||
"Task 1: Specific action with file locations",
|
||||
"Task 2: Specific action with file locations",
|
||||
// ... 3-7 tasks total
|
||||
],
|
||||
complexity: "Low|Medium|High",
|
||||
recommended_tool: "Claude|Gemini|Codex|Qwen",
|
||||
estimated_time: "X minutes"
|
||||
}
|
||||
```
|
||||
|
||||
**Execution Result**:
|
||||
- Immediate dispatch to selected tool/agent with plan context
|
||||
- No file artifacts generated during planning phase
|
||||
- Execution starts immediately after user confirmation
|
||||
- Tool/agent handles implementation and any necessary file operations
|
||||
|
||||
@@ -286,17 +286,16 @@ CATCH error:
|
||||
[
|
||||
{"content": "Phase 0: Validate parameters and prepare session", "status": "completed", "activeForm": "Validating parameters"},
|
||||
{"content": "Phase 1: Style extraction from source code (import-from-code)", "status": "completed", "activeForm": "Extracting styles"},
|
||||
{"content": "Phase 2.1: Validation and preparation (reference-page-generator)", "status": "in_progress", "activeForm": "Validating parameters"},
|
||||
{"content": "Phase 2.2: Component pattern extraction (reference-page-generator)", "status": "pending", "activeForm": "Extracting component patterns"},
|
||||
{"content": "Phase 2.3: Generate preview pages (reference-page-generator)", "status": "pending", "activeForm": "Generating preview"},
|
||||
{"content": "Phase 2.4: Generate metadata and documentation (reference-page-generator)", "status": "pending", "activeForm": "Generating documentation"},
|
||||
{"content": "Phase 2.0: Setup and validation (reference-page-generator)", "status": "in_progress", "activeForm": "Validating parameters"},
|
||||
{"content": "Phase 2.1: Prepare component data (reference-page-generator)", "status": "pending", "activeForm": "Copying layout templates"},
|
||||
{"content": "Phase 2.2: Generate preview pages (reference-page-generator)", "status": "pending", "activeForm": "Generating preview"},
|
||||
{"content": "Phase 3: Cleanup and verify package", "status": "pending", "activeForm": "Cleanup and verification"}
|
||||
]
|
||||
```
|
||||
|
||||
**Note**: Phase 1 tasks completed and collapsed. SlashCommand invocation **attaches** reference-page-generator's 4 tasks. Orchestrator **executes** these tasks itself.
|
||||
**Note**: Phase 1 tasks completed and collapsed. SlashCommand invocation **attaches** reference-page-generator's 3 tasks. Orchestrator **executes** these tasks itself.
|
||||
|
||||
**Next Action**: Tasks attached → **Execute Phase 2.1-2.4** sequentially
|
||||
**Next Action**: Tasks attached → **Execute Phase 2.0-2.2** sequentially
|
||||
|
||||
---
|
||||
|
||||
@@ -317,22 +316,19 @@ command = "/workflow:ui-design:reference-page-generator " +
|
||||
|
||||
```bash
|
||||
TRY:
|
||||
# SlashCommand invocation ATTACHES reference-page-generator's 4 tasks to current workflow
|
||||
# SlashCommand invocation ATTACHES reference-page-generator's 3 tasks to current workflow
|
||||
# Orchestrator will EXECUTE these attached tasks itself:
|
||||
# 1. Phase 2.1: Validation and preparation
|
||||
# 2. Phase 2.2: Component pattern extraction
|
||||
# 3. Phase 2.3: Generate preview pages
|
||||
# 4. Phase 2.4: Generate metadata and documentation
|
||||
# 1. Phase 2.0: Setup and validation
|
||||
# 2. Phase 2.1: Prepare component data
|
||||
# 3. Phase 2.2: Generate preview pages
|
||||
SlashCommand(command)
|
||||
|
||||
# After executing all attached tasks, verify package outputs
|
||||
required_files = [
|
||||
"layout-templates.json",
|
||||
"design-tokens.json",
|
||||
"component-patterns.json",
|
||||
"preview.html",
|
||||
"preview.css",
|
||||
"metadata.json",
|
||||
"README.md"
|
||||
"preview.css"
|
||||
]
|
||||
|
||||
missing_files = []
|
||||
@@ -365,16 +361,14 @@ CATCH error:
|
||||
- ✅ `reference-page-generator` executed successfully
|
||||
- ✅ Reference package created at `${package_path}/`
|
||||
- ✅ All required files present:
|
||||
- `layout-templates.json` - Layout templates from design run
|
||||
- `design-tokens.json` - Complete design token system
|
||||
- `component-patterns.json` - Component catalog
|
||||
- `preview.html` - Interactive multi-component showcase
|
||||
- `preview.css` - Showcase styling
|
||||
- `metadata.json` - Package metadata and version info
|
||||
- `README.md` - Package documentation and usage guide
|
||||
- ⭕ Optional files:
|
||||
- `animation-tokens.json` - Animation specifications (if available from extraction)
|
||||
|
||||
<!-- TodoWrite: REMOVE Phase 2.1-2.4 tasks, restore to orchestrator view -->
|
||||
<!-- TodoWrite: REMOVE Phase 2.0-2.2 tasks, restore to orchestrator view -->
|
||||
|
||||
**TodoWrite Update (Phase 2 completed - tasks collapsed)**:
|
||||
```json
|
||||
@@ -414,7 +408,7 @@ IF package_exists != "exists":
|
||||
|
||||
# Get absolute path and component count for final report
|
||||
absolute_package_path = Bash(cd "${package_path}" && pwd 2>/dev/null || echo "${package_path}")
|
||||
component_count = Bash(jq -r '.extraction_metadata.component_count // "unknown"' "${package_path}/component-patterns.json" 2>/dev/null || echo "unknown")
|
||||
component_count = Bash(jq -r '.layout_templates | length // "unknown"' "${package_path}/layout-templates.json" 2>/dev/null || echo "unknown")
|
||||
anim_exists = Bash(test -f "${package_path}/animation-tokens.json" && echo "✓" || echo "○")
|
||||
```
|
||||
|
||||
@@ -434,7 +428,7 @@ anim_exists = Bash(test -f "${package_path}/animation-tokens.json" && echo "✓"
|
||||
📄 Source: {source}
|
||||
📊 Components: {component_count}
|
||||
|
||||
Files: design-tokens.json, style-guide.md, component-patterns.json, preview.html, preview.css, metadata.json, README.md
|
||||
Files: layout-templates.json, design-tokens.json, animation-tokens.json (optional), preview.html, preview.css
|
||||
|
||||
Preview: file://{absolute_package_path}/preview.html
|
||||
|
||||
@@ -473,12 +467,12 @@ TodoWrite({todos: [
|
||||
// - TodoWrite becomes: Phase 0-1 (completed) + Phase 2 + Phase 3
|
||||
//
|
||||
// 4. PHASE 2 SlashCommand INVOCATION:
|
||||
// - SlashCommand(/workflow:ui-design:reference-page-generator) ATTACHES 4 tasks
|
||||
// - TodoWrite expands to: Phase 0-1 (completed) + 4 reference-page-generator tasks + Phase 3
|
||||
// - Orchestrator EXECUTES these 4 tasks sequentially (Phase 2.1 → 2.2 → 2.3 → 2.4)
|
||||
// - SlashCommand(/workflow:ui-design:reference-page-generator) ATTACHES 3 tasks
|
||||
// - TodoWrite expands to: Phase 0-1 (completed) + 3 reference-page-generator tasks + Phase 3
|
||||
// - Orchestrator EXECUTES these 3 tasks sequentially (Phase 2.0 → 2.1 → 2.2)
|
||||
//
|
||||
// 5. PHASE 2 TASKS COMPLETED:
|
||||
// - All 4 reference-page-generator tasks executed and completed
|
||||
// - All 3 reference-page-generator tasks executed and completed
|
||||
// - COLLAPSE completed tasks into Phase 2 summary
|
||||
// - TodoWrite returns to: Phase 0-2 (completed) + Phase 3 (in_progress)
|
||||
//
|
||||
@@ -533,25 +527,22 @@ User triggers: /workflow:ui-design:codify-style ./src --package-name my-style-v1
|
||||
↓
|
||||
[Phase 1 Complete] → TodoWrite: COLLAPSE Phase 1.0-1.3 into Phase 1 summary
|
||||
↓
|
||||
[Phase 2 Invoke] → SlashCommand(/workflow:ui-design:reference-page-generator) ATTACHES 4 tasks
|
||||
[Phase 2 Invoke] → SlashCommand(/workflow:ui-design:reference-page-generator) ATTACHES 3 tasks
|
||||
├─ Phase 0 (completed)
|
||||
├─ Phase 1: Style extraction from source code (completed) ← COLLAPSED
|
||||
├─ Phase 2.1: Validation and preparation (in_progress) ← ATTACHED
|
||||
├─ Phase 2.2: Component pattern extraction (pending) ← ATTACHED
|
||||
├─ Phase 2.3: Generate preview pages (pending) ← ATTACHED
|
||||
├─ Phase 2.4: Generate metadata and documentation (pending) ← ATTACHED
|
||||
├─ Phase 2.0: Setup and validation (in_progress) ← ATTACHED
|
||||
├─ Phase 2.1: Prepare component data (pending) ← ATTACHED
|
||||
├─ Phase 2.2: Generate preview pages (pending) ← ATTACHED
|
||||
└─ Phase 3: Cleanup and verify package (pending)
|
||||
↓
|
||||
[Execute Phase 2.1] → Validate parameters (orchestrator executes this)
|
||||
[Execute Phase 2.0] → Setup and validation (orchestrator executes this)
|
||||
↓
|
||||
[Execute Phase 2.2] → Extract component patterns (orchestrator executes this)
|
||||
[Execute Phase 2.1] → Prepare component data (orchestrator executes this)
|
||||
↓
|
||||
[Execute Phase 2.3] → Generate preview pages (orchestrator executes this)
|
||||
[Execute Phase 2.2] → Generate preview pages (orchestrator executes this)
|
||||
└─ Outputs: layout-templates.json, design-tokens.json, animation-tokens.json (optional), preview.html, preview.css
|
||||
↓
|
||||
[Execute Phase 2.4] → Generate metadata and docs (orchestrator executes this)
|
||||
└─ Outputs: component-patterns.json, preview.html, preview.css, metadata.json, README.md
|
||||
↓
|
||||
[Phase 2 Complete] → TodoWrite: COLLAPSE Phase 2.1-2.4 into Phase 2 summary
|
||||
[Phase 2 Complete] → TodoWrite: COLLAPSE Phase 2.0-2.2 into Phase 2 summary
|
||||
├─ Phase 0 (completed)
|
||||
├─ Phase 1: Style extraction from source code (completed)
|
||||
├─ Phase 2: Reference package generation (completed) ← COLLAPSED
|
||||
@@ -618,14 +609,11 @@ File discovery is fully automatic - no glob patterns needed.
|
||||
.workflow/
|
||||
├── reference_style/ # Default output directory
|
||||
│ └── {package-name}/
|
||||
│ ├── layout-templates.json
|
||||
│ ├── design-tokens.json
|
||||
│ ├── style-guide.md
|
||||
│ ├── component-patterns.json
|
||||
│ ├── animation-tokens.json (optional)
|
||||
│ ├── preview.html
|
||||
│ ├── preview.css
|
||||
│ ├── metadata.json
|
||||
│ └── README.md
|
||||
│ └── preview.css
|
||||
│
|
||||
└── codify-temp-{timestamp}/ # Temporary workspace (cleaned up after completion)
|
||||
├── style-extraction/
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: explore-auto
|
||||
description: Interactive exploratory UI design workflow with style-centric batch generation, creates design variants from prompts/images with parallel execution and user selection
|
||||
argument-hint: "[--input "<value>"] [--targets "<list>"] [--target-type "page|component"] [--session <id>] [--style-variants <count>] [--layout-variants <count>] [--batch-plan]"
|
||||
argument-hint: "[--input "<value>"] [--targets "<list>"] [--target-type "page|component"] [--session <id>] [--style-variants <count>] [--layout-variants <count>]"
|
||||
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*), Task(conceptual-planning-agent)
|
||||
---
|
||||
|
||||
@@ -25,18 +25,18 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
|
||||
- **ELSE**: Skip (use code import) → Auto-continues to Phase 9
|
||||
5. Phase 9 (layout-extract) → **Attach tasks → Execute → Collapse** → Auto-continues to Phase 10
|
||||
6. **Phase 10 (ui-assembly)** → **Attach tasks → Execute → Collapse** → Auto-continues to Phase 11
|
||||
7. Phase 11 (design-update) → **Attach tasks → Execute → Collapse** → Auto-continues to Phase 12 (if --batch-plan)
|
||||
8. Phase 12 (batch-plan, optional) → Reports completion
|
||||
7. **Phase 11 (preview-generation)** → **Execute script → Generate preview files** → Reports completion
|
||||
|
||||
**Phase Transition Mechanism**:
|
||||
- **Phase 5 (User Interaction)**: User confirms targets → IMMEDIATELY triggers Phase 7
|
||||
- **Phase 7-12 (Autonomous)**: `SlashCommand` invocation **ATTACHES** tasks to current workflow
|
||||
- **Phase 7-10 (Autonomous)**: `SlashCommand` invocation **ATTACHES** tasks to current workflow
|
||||
- **Task Execution**: Orchestrator **EXECUTES** these attached tasks itself
|
||||
- **Task Collapse**: After tasks complete, collapse them into phase summary
|
||||
- **Phase Transition**: Automatically execute next phase after collapsing
|
||||
- **Phase 11 (Script Execution)**: Execute preview generation script
|
||||
- No additional user interaction after Phase 5 confirmation
|
||||
|
||||
**Auto-Continue Mechanism**: TodoWrite tracks phase status with dynamic task attachment/collapse. After executing all attached tasks, you MUST immediately collapse them, restore phase summary, and execute the next phase. No user intervention required. The workflow is NOT complete until reaching Phase 11 (or Phase 12 if --batch-plan).
|
||||
**Auto-Continue Mechanism**: TodoWrite tracks phase status with dynamic task attachment/collapse. After executing all attached tasks, you MUST immediately collapse them, restore phase summary, and execute the next phase. No user intervention required. The workflow is NOT complete until reaching Phase 11 (preview generation).
|
||||
|
||||
**Task Attachment Model**: SlashCommand invocation is NOT delegation - it's task expansion. The orchestrator executes these attached tasks itself, not waiting for external completion.
|
||||
|
||||
@@ -50,7 +50,7 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
|
||||
4. **Default to All**: When selecting variants/prototypes, use ALL generated items
|
||||
5. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
|
||||
6. **⚠️ CRITICAL: Task Attachment Model** - SlashCommand invocation **ATTACHES** tasks to current workflow. Orchestrator **EXECUTES** these attached tasks itself, not waiting for external completion. This is NOT delegation - it's task expansion.
|
||||
7. **⚠️ CRITICAL: DO NOT STOP** - This is a continuous multi-phase workflow. After executing all attached tasks, you MUST immediately collapse them and execute the next phase. Workflow is NOT complete until Phase 11 (or Phase 12 if --batch-plan).
|
||||
7. **⚠️ CRITICAL: DO NOT STOP** - This is a continuous multi-phase workflow. After executing all attached tasks, you MUST immediately collapse them and execute the next phase. Workflow is NOT complete until Phase 11 (preview generation).
|
||||
|
||||
## Parameter Requirements
|
||||
|
||||
@@ -83,7 +83,6 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
|
||||
- `--session <id>`: Workflow session ID (standalone mode if omitted)
|
||||
- `--style-variants <count>`: Style variants (default: inferred from prompt or 3, range: 1-5)
|
||||
- `--layout-variants <count>`: Layout variants per style (default: inferred or 3, range: 1-5)
|
||||
- `--batch-plan`: Auto-generate implementation tasks after design-update
|
||||
|
||||
**Legacy Target Parameters** (maintained for backward compatibility):
|
||||
- `--pages "<list>"`: Alias for `--targets` with `--target-type page`
|
||||
@@ -128,7 +127,7 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
|
||||
**Integrated vs. Standalone**:
|
||||
- `--session` flag determines session integration or standalone execution
|
||||
|
||||
## 12-Phase Execution
|
||||
## 11-Phase Execution
|
||||
|
||||
### Phase 1: Parameter Parsing & Input Detection
|
||||
```bash
|
||||
@@ -585,33 +584,48 @@ SlashCommand(command)
|
||||
# Output:
|
||||
# - {target}-style-{s}-layout-{l}.html (assembled prototypes)
|
||||
# - {target}-style-{s}-layout-{l}.css
|
||||
# - compare.html (interactive matrix view)
|
||||
# - PREVIEW.md (usage instructions)
|
||||
# Note: compare.html and PREVIEW.md will be generated in Phase 11
|
||||
```
|
||||
|
||||
### Phase 11: Design System Integration
|
||||
### Phase 11: Generate Preview Files
|
||||
```bash
|
||||
command = "/workflow:ui-design:update" + (--session ? " --session {session_id}" : "")
|
||||
REPORT: "🚀 Phase 11: Generate Preview Files"
|
||||
|
||||
# SlashCommand invocation ATTACHES update's tasks to current workflow
|
||||
# Orchestrator will EXECUTE these attached tasks itself
|
||||
SlashCommand(command)
|
||||
# Update TodoWrite to reflect preview generation phase
|
||||
TodoWrite({todos: [
|
||||
{"content": "Execute style extraction", "status": "completed", "activeForm": "Executing style extraction"},
|
||||
{"content": "Execute animation extraction", "status": "completed", "activeForm": "Executing animation extraction"},
|
||||
{"content": "Execute layout extraction", "status": "completed", "activeForm": "Executing layout extraction"},
|
||||
{"content": "Execute UI assembly", "status": "completed", "activeForm": "Executing UI assembly"},
|
||||
{"content": "Generate preview files", "status": "in_progress", "activeForm": "Generating preview files"}
|
||||
]})
|
||||
|
||||
# After executing all attached tasks, collapse them into phase summary
|
||||
# When phase finishes:
|
||||
# - If --batch-plan flag present: IMMEDIATELY execute Phase 12 (auto-continue)
|
||||
# - If no --batch-plan: Workflow complete, display final report
|
||||
```
|
||||
# Execute preview generation script
|
||||
Bash(~/.claude/scripts/ui-generate-preview.sh "${base_path}/prototypes")
|
||||
|
||||
### Phase 12: Batch Task Generation (Optional)
|
||||
```bash
|
||||
IF --batch-plan:
|
||||
FOR target IN inferred_target_list:
|
||||
task_desc = "Implement {target} {target_type} based on design system"
|
||||
# Verify output files
|
||||
IF NOT exists("${base_path}/prototypes/compare.html"):
|
||||
ERROR: "Preview generation failed: compare.html not found"
|
||||
EXIT 1
|
||||
|
||||
# SlashCommand invocation ATTACHES plan's tasks to current workflow
|
||||
# Orchestrator will EXECUTE these attached tasks itself
|
||||
SlashCommand("/workflow:plan --agent \"{task_desc}\"")
|
||||
IF NOT exists("${base_path}/prototypes/PREVIEW.md"):
|
||||
ERROR: "Preview generation failed: PREVIEW.md not found"
|
||||
EXIT 1
|
||||
|
||||
# Mark preview generation as complete
|
||||
TodoWrite({todos: [
|
||||
{"content": "Execute style extraction", "status": "completed", "activeForm": "Executing style extraction"},
|
||||
{"content": "Execute animation extraction", "status": "completed", "activeForm": "Executing animation extraction"},
|
||||
{"content": "Execute layout extraction", "status": "completed", "activeForm": "Executing layout extraction"},
|
||||
{"content": "Execute UI assembly", "status": "completed", "activeForm": "Executing UI assembly"},
|
||||
{"content": "Generate preview files", "status": "completed", "activeForm": "Generating preview files"}
|
||||
]})
|
||||
|
||||
REPORT: "✅ Preview files generated successfully"
|
||||
REPORT: " → compare.html (interactive matrix view)"
|
||||
REPORT: " → PREVIEW.md (usage instructions)"
|
||||
|
||||
# Workflow complete, display final report
|
||||
```
|
||||
|
||||
## TodoWrite Pattern
|
||||
@@ -622,7 +636,7 @@ TodoWrite({todos: [
|
||||
{"content": "Execute animation extraction", "status": "pending", "activeForm": "Executing animation extraction"},
|
||||
{"content": "Execute layout extraction", "status": "pending", "activeForm": "Executing layout extraction"},
|
||||
{"content": "Execute UI assembly", "status": "pending", "activeForm": "Executing UI assembly"},
|
||||
{"content": "Execute design integration", "status": "pending", "activeForm": "Executing design integration"}
|
||||
{"content": "Generate preview files", "status": "pending", "activeForm": "Generating preview files"}
|
||||
]})
|
||||
|
||||
// ⚠️ CRITICAL: Dynamic TodoWrite task attachment strategy:
|
||||
@@ -630,18 +644,25 @@ TodoWrite({todos: [
|
||||
// **Key Concept**: SlashCommand invocation ATTACHES tasks to current workflow.
|
||||
// Orchestrator EXECUTES these attached tasks itself, not waiting for external completion.
|
||||
//
|
||||
// Phase 7-12 SlashCommand Invocation Pattern:
|
||||
// Phase 7-10 SlashCommand Invocation Pattern:
|
||||
// 1. SlashCommand invocation ATTACHES sub-command tasks to TodoWrite
|
||||
// 2. TodoWrite expands to include attached tasks
|
||||
// 3. Orchestrator EXECUTES attached tasks sequentially
|
||||
// 4. After all attached tasks complete, COLLAPSE them into phase summary
|
||||
// 5. Update next phase to in_progress
|
||||
// 6. IMMEDIATELY execute next phase SlashCommand (auto-continue)
|
||||
// 6. IMMEDIATELY execute next phase (auto-continue)
|
||||
//
|
||||
// Phase 11 Script Execution Pattern:
|
||||
// 1. Mark "Generate preview files" as in_progress
|
||||
// 2. Execute preview generation script via Bash tool
|
||||
// 3. Verify output files (compare.html, PREVIEW.md)
|
||||
// 4. Mark "Generate preview files" as completed
|
||||
//
|
||||
// Benefits:
|
||||
// ✓ Real-time visibility into sub-command task progress
|
||||
// ✓ Clean orchestrator-level summary after each phase
|
||||
// ✓ Clear mental model: SlashCommand = attach tasks, not delegate work
|
||||
// ✓ Script execution for preview generation (no delegation)
|
||||
// ✓ Dynamic attachment/collapse maintains clarity
|
||||
```
|
||||
|
||||
@@ -661,8 +682,7 @@ Phase 9: {n×l} layout templates (layout-extract with multi-select)
|
||||
Phase 10: UI Assembly (generate)
|
||||
- Pure assembly: layout templates + design tokens
|
||||
- {s}×{l}×{n} = {total} final prototypes
|
||||
Phase 11: Brainstorming artifacts updated
|
||||
[Phase 12: {n} implementation tasks created] # if --batch-plan
|
||||
Phase 11: Preview files generated (compare.html, PREVIEW.md)
|
||||
|
||||
Assembly Process:
|
||||
✅ Separation of Concerns: Layout (structure) + Style (tokens) kept separate
|
||||
@@ -700,6 +720,6 @@ Design Quality:
|
||||
- Layout plans stored as structured JSON
|
||||
- Optimized for {device_type} viewing
|
||||
|
||||
Next: [/workflow:execute] OR [Open compare.html → Select → /workflow:plan]
|
||||
Next: Open compare.html to preview all design variants
|
||||
```
|
||||
|
||||
|
||||
@@ -154,6 +154,23 @@ Task(subagent_type="ui-design-agent",
|
||||
|
||||
## Code Import Extraction Strategy
|
||||
|
||||
**Step 0: Fast Conflict Detection** (Use Bash/Grep for quick global scan)
|
||||
- Quick scan: \`rg --color=never -n "^\\s*--primary:|^\\s*--secondary:|^\\s*--accent:" --type css ${source}\` to find core color definitions with line numbers
|
||||
- Semantic search: \`rg --color=never -B3 -A1 "^\\s*--primary:" --type css ${source}\` to capture surrounding context and comments
|
||||
- Core token scan: Search for --primary, --secondary, --accent, --background patterns to detect all theme-critical definitions
|
||||
- Pattern: rg → Extract values → Compare → If different → Read full context with comments → Record conflict
|
||||
- Alternative (if many files): Execute CLI analysis for comprehensive report:
|
||||
\`\`\`bash
|
||||
cd ${source} && gemini -p \"
|
||||
PURPOSE: Detect color token conflicts across all CSS/SCSS/JS files
|
||||
TASK: • Scan all files for color definitions • Identify conflicting values • Extract semantic comments
|
||||
MODE: analysis
|
||||
CONTEXT: @**/*.css @**/*.scss @**/*.js @**/*.ts
|
||||
EXPECTED: JSON report listing conflicts with file:line, values, semantic context
|
||||
RULES: Focus on core tokens | Report ALL variants | analysis=READ-ONLY
|
||||
\"
|
||||
\`\`\`
|
||||
|
||||
**Step 1: Load file list**
|
||||
- Read(${intermediates_dir}/discovered-files.json)
|
||||
- Extract: file_types.css.files, file_types.js.files, file_types.html.files
|
||||
@@ -163,10 +180,11 @@ Task(subagent_type="ui-design-agent",
|
||||
- JavaScript/TypeScript: Theme configs (Tailwind, styled-components, CSS-in-JS)
|
||||
- HTML: Inline styles, usage patterns
|
||||
|
||||
**Step 3: Smart inference for gaps**
|
||||
- Infer missing tokens from existing patterns
|
||||
- Normalize inconsistent values into systematic scales
|
||||
- Fill missing categories from cross-file references
|
||||
**Step 3: Validation and Conflict Detection**
|
||||
- Report missing tokens WITHOUT inference (mark as "missing" in _metadata.completeness)
|
||||
- Detect and report inconsistent values across files (list ALL variants with file:line sources)
|
||||
- Report missing categories WITHOUT auto-filling (document gaps for manual review)
|
||||
- CRITICAL: Verify core tokens (primary, secondary, accent) against semantic comments in source code
|
||||
|
||||
## Output Files
|
||||
|
||||
@@ -178,7 +196,9 @@ Task(subagent_type="ui-design-agent",
|
||||
- Add \"_metadata.extraction_source\": \"code_import\"
|
||||
- Add \"_metadata.files_analyzed\": {css, js, html file lists}
|
||||
- Add \"_metadata.completeness\": {status, missing_categories, recommendations}
|
||||
- Add \"_metadata.conflicts\": Array of conflicting definitions (MANDATORY if conflicts exist)
|
||||
- Add \"_metadata.code_snippets\": Map of code snippets (see below)
|
||||
- Add \"_metadata.usage_recommendations\": Usage patterns from code (see below)
|
||||
- Include \"source\" field for each token (e.g., \"file.css:23\")
|
||||
|
||||
**Code Snippet Recording**:
|
||||
@@ -198,12 +218,35 @@ Task(subagent_type="ui-design-agent",
|
||||
- Typical ranges: Simple declarations (1-5 lines), Utility classes (5-15 lines), Complete configs (15-50 lines)
|
||||
- Preserve original formatting and indentation
|
||||
|
||||
**Conflict Detection and Reporting**:
|
||||
- When the same token is defined differently across multiple files, record in `_metadata.conflicts`
|
||||
- Follow Agent schema for conflicts array structure (see ui-design-agent.md)
|
||||
- Each conflict MUST include: token_name, category, all definitions with context, selected_value, selection_reason
|
||||
- Selection priority:
|
||||
1. Definitions with semantic comments explaining intent (/* Blue theme */, /* Primary brand color */)
|
||||
2. Definitions that align with overall color scheme described in comments
|
||||
3. When in doubt, report ALL variants and flag for manual review in completeness.recommendations
|
||||
|
||||
**Usage Recommendations Generation**:
|
||||
- Analyze code usage patterns to extract `_metadata.usage_recommendations` (see ui-design-agent.md schema)
|
||||
- **Typography recommendations**:
|
||||
* `common_sizes`: Identify most frequent font size usage (e.g., \"body_text\": \"base (1rem)\")
|
||||
* `common_combinations`: Extract heading+body pairings from actual usage (e.g., h1 with p tags)
|
||||
- **Spacing recommendations**:
|
||||
* `size_guide`: Categorize spacing values into tight/normal/loose based on frequency
|
||||
* `common_patterns`: Extract frequent padding/margin combinations from components
|
||||
- Analysis method: Scan code for class/style usage frequency, extract patterns from component implementations
|
||||
- Optional: If insufficient usage data, mark fields as empty arrays/objects with note in completeness.recommendations
|
||||
|
||||
## Code Import Specific Requirements
|
||||
- ✅ Read discovered-files.json FIRST to get file paths
|
||||
- ✅ Track extraction source for each token (file:line)
|
||||
- ✅ Record complete code snippets in _metadata.code_snippets (complete blocks with dependencies/comments)
|
||||
- ✅ Include completeness assessment in _metadata
|
||||
- ✅ Normalize inconsistent values into systematic scales
|
||||
- ✅ Report inconsistent values with ALL source locations in _metadata.conflicts (DO NOT auto-normalize or choose)
|
||||
- ✅ CRITICAL: Verify core theme tokens (primary, secondary, accent) match source code semantic intent
|
||||
- ✅ When conflicts exist, prefer definitions with semantic comments explaining intent
|
||||
- ❌ NO inference, NO smart filling, NO automatic conflict resolution
|
||||
- ❌ NO external research or web searches (code-only extraction)
|
||||
")
|
||||
```
|
||||
@@ -226,6 +269,23 @@ Task(subagent_type="ui-design-agent",
|
||||
|
||||
## Code Import Extraction Strategy
|
||||
|
||||
**Step 0: Fast Animation Discovery** (Use Bash/Grep for quick pattern detection)
|
||||
- Quick scan: \`rg --color=never -n "@keyframes|animation:|transition:" --type css ${source}\` to find animation definitions with line numbers
|
||||
- Framework detection: \`rg --color=never "framer-motion|gsap|@react-spring|react-spring" --type js --type ts ${source}\` to detect animation frameworks
|
||||
- Pattern categorization: \`rg --color=never -B2 -A5 "@keyframes" --type css ${source}\` to extract keyframe animations with context
|
||||
- Pattern: rg → Identify animation types → Map framework usage → Prioritize extraction targets
|
||||
- Alternative (if complex framework mix): Execute CLI analysis for comprehensive report:
|
||||
\`\`\`bash
|
||||
cd ${source} && gemini -p \"
|
||||
PURPOSE: Detect animation frameworks and patterns
|
||||
TASK: • Identify frameworks • Map animation patterns • Categorize by complexity
|
||||
MODE: analysis
|
||||
CONTEXT: @**/*.css @**/*.scss @**/*.js @**/*.ts
|
||||
EXPECTED: JSON report listing frameworks, animation types, file locations
|
||||
RULES: Focus on framework consistency | Map all animations | analysis=READ-ONLY
|
||||
\"
|
||||
\`\`\`
|
||||
|
||||
**Step 1: Load file list**
|
||||
- Read(${intermediates_dir}/discovered-files.json)
|
||||
- Extract: file_types.css.files, file_types.js.files, file_types.html.files
|
||||
@@ -288,6 +348,23 @@ Task(subagent_type="ui-design-agent",
|
||||
|
||||
## Code Import Extraction Strategy
|
||||
|
||||
**Step 0: Fast Component Discovery** (Use Bash/Grep for quick component scan)
|
||||
- Layout pattern scan: \`rg --color=never -n "display:\\s*(grid|flex)|grid-template" --type css ${source}\` to find layout systems
|
||||
- Component class scan: \`rg --color=never "class.*=.*\\"[^\"]*\\b(btn|button|card|input|modal|dialog|dropdown)" --type html --type js --type ts ${source}\` to identify UI components
|
||||
- Universal component heuristic: Components appearing in 3+ files = universal, <3 files = specialized
|
||||
- Pattern: rg → Count occurrences → Classify by frequency → Prioritize universal components
|
||||
- Alternative (if large codebase): Execute CLI analysis for comprehensive categorization:
|
||||
\`\`\`bash
|
||||
cd ${source} && gemini -p \"
|
||||
PURPOSE: Classify components as universal vs specialized
|
||||
TASK: • Identify UI components • Classify reusability • Map layout systems
|
||||
MODE: analysis
|
||||
CONTEXT: @**/*.css @**/*.scss @**/*.js @**/*.ts @**/*.html
|
||||
EXPECTED: JSON report categorizing components, layout patterns, naming conventions
|
||||
RULES: Focus on component reusability | Identify layout systems | analysis=READ-ONLY
|
||||
\"
|
||||
\`\`\`
|
||||
|
||||
**Step 1: Load file list**
|
||||
- Read(${intermediates_dir}/discovered-files.json)
|
||||
- Extract: file_types.css.files, file_types.js.files, file_types.html.files
|
||||
@@ -327,6 +404,11 @@ Task(subagent_type="ui-design-agent",
|
||||
* dom_structure with semantic HTML5
|
||||
* css_layout_rules using var() placeholders
|
||||
* Add \"description\" field explaining component purpose and classification rationale
|
||||
* **Add \"usage_guide\" field for universal components** (see ui-design-agent.md schema):
|
||||
- common_sizes: Extract size variants (small/medium/large) from code
|
||||
- variant_recommendations: Document when to use each variant (primary/secondary/etc)
|
||||
- usage_context: List typical usage scenarios from actual implementation
|
||||
- accessibility_tips: Extract ARIA patterns and a11y notes from code
|
||||
|
||||
**Code Snippet Recording**:
|
||||
- Record actual layout/component code in `extraction_metadata.code_snippets`
|
||||
@@ -345,6 +427,12 @@ Task(subagent_type="ui-design-agent",
|
||||
* Specialized: Feature-specific or domain-specific (checkout form, dashboard widget)
|
||||
- ✅ Record complete code snippets in extraction_metadata.code_snippets (complete components/structures)
|
||||
- ✅ **Document classification rationale** in component description
|
||||
- ✅ **Generate usage_guide for universal components** (REQUIRED):
|
||||
* Analyze code to extract size variants (scan for size-related classes/props)
|
||||
* Document variant usage from code comments and implementation patterns
|
||||
* List usage contexts from component instances in codebase
|
||||
* Extract accessibility patterns from ARIA attributes and a11y comments
|
||||
* If insufficient data, populate with minimal valid structure and note in completeness
|
||||
- ❌ NO external research or web searches (code-only extraction)
|
||||
")
|
||||
```
|
||||
|
||||
@@ -29,16 +29,6 @@ Converts design run extraction results into shareable reference package with:
|
||||
--output-dir <path> Output directory (default: .workflow/reference_style)
|
||||
```
|
||||
|
||||
### Usage Examples
|
||||
|
||||
```bash
|
||||
# Basic usage
|
||||
/workflow:ui-design:reference-page-generator --design-run .workflow/WFS-123/design-run-456 --package-name main-app-style-v1
|
||||
|
||||
# Custom output directory
|
||||
/workflow:ui-design:reference-page-generator --design-run .workflow/WFS-123/design-run-456 --package-name main-app-style-v1 --output-dir ./style-references
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Execution Process
|
||||
@@ -210,10 +200,18 @@ Task(ui-design-agent): `
|
||||
- Display typography scale (font sizes, weights)
|
||||
- Show typography combinations if available
|
||||
- Include font family examples
|
||||
- **Display usage recommendations** (from design-tokens.json _metadata.usage_recommendations.typography):
|
||||
* Common sizes table (small_text, body_text, heading)
|
||||
* Common combinations with use cases
|
||||
|
||||
### Section 3: Components
|
||||
- Render all components from layout-templates.json (use layout_templates field)
|
||||
- **Universal Components**: Display reusable multi-component showcases (buttons, inputs, cards, etc.)
|
||||
* **Display usage_guide** (from layout-templates.json):
|
||||
- Common sizes table with dimensions and use cases
|
||||
- Variant recommendations (when to use primary/secondary/etc)
|
||||
- Usage context list (typical scenarios)
|
||||
- Accessibility tips checklist
|
||||
- **Specialized Components**: Display module-specific components from code (feature-specific layouts, custom widgets)
|
||||
- Display all variants side-by-side
|
||||
- Show DOM structure with proper styling
|
||||
@@ -224,6 +222,9 @@ Task(ui-design-agent): `
|
||||
- Visual spacing scale
|
||||
- Border radius examples
|
||||
- Shadow depth examples
|
||||
- **Display spacing recommendations** (from design-tokens.json _metadata.usage_recommendations.spacing):
|
||||
* Size guide table (tight/normal/loose categories)
|
||||
* Common patterns with use cases and pixel values
|
||||
|
||||
### Section 5: Animations (if available)
|
||||
- Animation duration examples
|
||||
@@ -259,6 +260,11 @@ Task(ui-design-agent): `
|
||||
- ✅ Display component DOM structures with proper styling
|
||||
- ✅ Include usage code snippets
|
||||
- ✅ Label each component type clearly (Universal / Specialized)
|
||||
- ✅ **Display usage recommendations** when available:
|
||||
- Typography: common_sizes, common_combinations (from _metadata.usage_recommendations)
|
||||
- Components: usage_guide for universal components (from layout-templates)
|
||||
- Spacing: size_guide, common_patterns (from _metadata.usage_recommendations)
|
||||
- ✅ Gracefully handle missing usage data (display sections only if data exists)
|
||||
- ✅ Use Write() to save both files:
|
||||
- ${package_dir}/preview.html
|
||||
- ${package_dir}/preview.css
|
||||
|
||||
Reference in New Issue
Block a user