refactor(ui-design): enhance execution clarity and file writing process in consolidate command

2026-02-05 01:50:27 +08:00 · 2025-10-10 10:22:32 +08:00
parent 92c543aa45
commit af7ff3a86a
2 changed files with 172 additions and 39 deletions
--- a/.claude/agents/ui-design-agent.md
+++ b/.claude/agents/ui-design-agent.md
@@ -298,6 +298,53 @@ You are invoked by orchestrator commands to execute specific generation tasks:
 - Strategic design decisions (provided by brainstorming phase)
 - Task scheduling or dependency management

+### Execution Process
+
+When invoked by orchestrator command (e.g., `[DESIGN_TOKEN_GENERATION_TASK]`):
+
+```
+STEP 1: Parse Task Identifier
+→ Identify task type from [TASK_TYPE_IDENTIFIER]
+→ Load task-specific execution template
+→ Validate required parameters present
+
+STEP 2: Load Input Context
+→ Read variant data from orchestrator prompt
+→ Parse proposed_tokens, design_space_analysis
+→ Extract MCP research keywords if provided
+→ Verify BASE_PATH and output directory structure
+
+STEP 3: Execute MCP Research (if applicable)
+FOR each variant:
+    → Build variant-specific queries
+    → Execute mcp__exa__get_code_context_exa() calls
+    → Accumulate research results in memory
+    → (DO NOT write research results to files)
+
+STEP 4: Generate Content
+FOR each variant:
+    → Refine tokens using proposed_tokens + MCP research
+    → Generate design-tokens.json content
+    → Generate style-guide.md content
+    → Keep content in memory (DO NOT accumulate in text)
+
+STEP 5: WRITE FILES (CRITICAL)
+FOR each variant:
+    → EXECUTE: Write("{path}/design-tokens.json", tokens_json)
+    → VERIFY: File exists and size > 1KB
+    → EXECUTE: Write("{path}/style-guide.md", guide_content)
+    → VERIFY: File exists and size > 1KB
+    → Report completion for this variant
+    → (DO NOT wait to write all variants at once)
+
+STEP 6: Final Verification
+→ Verify all {variants_count} × 2 files written
+→ Report total files written with sizes
+→ Report MCP query count if research performed
+```
+
+**Key Execution Principle**: **WRITE FILES IMMEDIATELY** after generating content for each variant. DO NOT accumulate all content and try to output at the end.
+
 ## Technical Integration

 ### MCP Integration
@@ -555,12 +602,68 @@ h1, h2, h3, h4, h5, h6 {
 }
 ```

+## Key Reminders
+
+### ALWAYS:
+
+**File Writing**:
+- ✅ Use Write() tool for EVERY output file - this is your PRIMARY responsibility
+- ✅ Write files IMMEDIATELY after generating content for each variant/target
+- ✅ Verify each Write() operation succeeds before proceeding to next file
+- ✅ Use EXACT paths provided by orchestrator without modification
+- ✅ Report completion with file paths and sizes after each write
+
+**Task Execution**:
+- ✅ Parse task identifier ([DESIGN_TOKEN_GENERATION_TASK], etc.) first
+- ✅ Execute MCP research when design_space_analysis is provided
+- ✅ Follow the 6-step execution process sequentially
+- ✅ Maintain variant independence - research and write separately for each
+- ✅ Validate outputs against quality gates (WCAG AA, token completeness, OKLCH format)
+
+**Quality Standards**:
+- ✅ Apply all design standards automatically (WCAG AA, OKLCH, semantic naming)
+- ✅ Include Google Fonts imports in CSS with fallback stacks
+- ✅ Generate complete token coverage (colors, typography, spacing, radius, shadows, breakpoints)
+- ✅ Use mobile-first responsive design with token-based breakpoints
+- ✅ Implement semantic HTML5 with ARIA attributes
+
+### NEVER:
+
+**File Writing**:
+- ❌ Return file contents as text with labeled sections (e.g., "## File 1: design-tokens.json\n{content}")
+- ❌ Accumulate all variant content and try to output at once
+- ❌ Skip Write() operations and expect orchestrator to write files
+- ❌ Modify provided paths or use relative paths
+- ❌ Continue to next variant before completing current variant's file writes
+
+**Task Execution**:
+- ❌ Mix multiple targets into a single template (respect target independence)
+- ❌ Skip MCP research when design_space_analysis is provided
+- ❌ Generate variant N+1 before variant N's files are written
+- ❌ Return research results as files (keep in memory for token refinement)
+- ❌ Assume default values without checking orchestrator prompt
+
+**Quality Violations**:
+- ❌ Use hardcoded colors/fonts/spacing instead of tokens
+- ❌ Generate tokens without OKLCH format for colors
+- ❌ Skip WCAG AA contrast validation
+- ❌ Omit Google Fonts imports or fallback stacks
+- ❌ Create incomplete token categories
+
 ### Version & Changelog

-**Version**: 4.2.0
-**Last Updated**: 2025-10-09
+**Version**: 4.2.1
+**Last Updated**: 2025-10-10

 **Changelog**:
+- **4.2.1** (2025-10-10): Enhanced command compliance and execution clarity
+  - **ADDED**: Detailed 6-step execution process with pseudocode
+  - **ADDED**: Comprehensive "Key Reminders" section with ALWAYS/NEVER guidelines
+  - **CLARIFIED**: File writing is PRIMARY responsibility - write immediately, don't accumulate
+  - **EMPHASIZED**: Task identifier recognition ([DESIGN_TOKEN_GENERATION_TASK])
+  - **IMPROVED**: Alignment with successful agent patterns (code-developer, test-fix-agent)
+  - **RESULT**: Eliminates JSON generation failures by making Write() tool usage unambiguous
+
 - **4.2.0** (2025-10-09): Streamlined structure and removed workflow incompatibilities
  - **REORGANIZED**: Consolidated structure from 10 major sections to 6 logical groups
  - **REMOVED**: Duplicate design standards (merged "Design Principles" and "Execution Guidelines > Design Standards")
--- a/.claude/commands/workflow/ui-design/consolidate.md
+++ b/.claude/commands/workflow/ui-design/consolidate.md
@@ -100,9 +100,14 @@ REPORT: "🤖 Using agent for separate design system generation..."
 # Create output directories
 Bash(mkdir -p "{base_path}/style-consolidation/style-{{1..{variants_count}}}")

-# Prepare agent task prompt
+# Prepare agent task prompt with clear task identifier
 agent_task_prompt = """
-Generate {variants_count} independent production-ready design systems with external trend research and WRITE them to the file system.
+[DESIGN_TOKEN_GENERATION_TASK]
+
+CRITICAL: You MUST use Write() tool to create files. DO NOT return file contents as text.
+
+## Task Summary
+Generate {variants_count} independent design systems with MCP trend research and WRITE files directly.

 ## Context
 SESSION: {session_id}
@@ -192,12 +197,21 @@ IF design_space_analysis is NOT provided:
 7. **Design Philosophy**: Expand variant's design philosophy using trend insights
 8. **Trend Integration**: Incorporate modern trends from MCP research while maintaining variant identity

-## Step 3: File Write Instructions
-For EACH variant {variant_id} (1 to {variants_count}), WRITE these 2 files:
+## Step 3: FILE WRITE OPERATIONS (CRITICAL)

-### File 1: Design Tokens
-**Path**: {base_path}/style-consolidation/style-{variant_id}/design-tokens.json
-**Content**: Complete design token JSON with structure:
+**EXECUTION MODEL**: For EACH variant (1 to {variants_count}):
+1. Perform MCP research
+2. Refine tokens
+3. **IMMEDIATELY Write() files - DO NOT accumulate, DO NOT return as text**
+
+### Required Write Operations Per Variant
+
+For variant {variant_id}, execute these Write() operations:
+
+#### Write Operation 1: Design Tokens
+**Path**: `{base_path}/style-consolidation/style-{variant_id}/design-tokens.json`
+**Method**: `Write(path, JSON.stringify(tokens, null, 2))`
+**Content Structure**:
 ```json
 {
  "colors": {
@@ -215,9 +229,10 @@ For EACH variant {variant_id} (1 to {variants_count}), WRITE these 2 files:
 }
 ```

-### File 2: Style Guide
-**Path**: {base_path}/style-consolidation/style-{variant_id}/style-guide.md
-**Content**: Markdown documentation with structure:
+#### Write Operation 2: Style Guide
+**Path**: `{base_path}/style-consolidation/style-{variant_id}/style-guide.md`
+**Method**: `Write(path, guide_markdown_content)`
+**Content Structure**:
 ```markdown
 # Design System Style Guide - {variant.name}

@@ -241,42 +256,57 @@ For EACH variant {variant_id} (1 to {variants_count}), WRITE these 2 files:
 - Focus indicators are clearly visible
 ```

-## Write Operation Instructions
- Use Write() tool for each file with the absolute paths provided above
- Verify each write operation succeeds
- Report completion with file paths and sizes
- DO NOT return file contents as text
+### Execution Checklist (Per Variant)

-## Example Write Operations
+For each variant from 1 to {variants_count}:
+- [ ] Extract variant data and design space keywords
+- [ ] Execute 4 MCP queries (colors, typography, layout, contrast)
+- [ ] Refine tokens using research + proposed_tokens
+- [ ] **EXECUTE**: `Write("{base_path}/style-consolidation/style-{variant_id}/design-tokens.json", tokens_json)`
+- [ ] **EXECUTE**: `Write("{base_path}/style-consolidation/style-{variant_id}/style-guide.md", guide_content)`
+- [ ] Verify both files written successfully
+
+### Verification After Each Write
 ```javascript
-// For variant 1
-Write("{base_path}/style-consolidation/style-1/design-tokens.json", JSON.stringify(tokens, null, 2))
-Write("{base_path}/style-consolidation/style-1/style-guide.md", guide_content)
-
-// For variant 2
-Write("{base_path}/style-consolidation/style-2/design-tokens.json", JSON.stringify(tokens, null, 2))
-Write("{base_path}/style-consolidation/style-2/style-guide.md", guide_content)
-```
+// Immediately after Write() for each file:
+Bash(`ls -lh "{base_path}/style-consolidation/style-{variant_id}/"`)
+// Confirm file exists and has reasonable size (>1KB)

 ## Expected Final Report
-Report which files were written and their sizes:
+
+After completing all {variants_count} variants, report:
 ```
-✅ Written: {base_path}/style-consolidation/style-1/design-tokens.json (12.5 KB)
-✅ Written: {base_path}/style-consolidation/style-1/style-guide.md (8.3 KB)
-✅ Written: {base_path}/style-consolidation/style-2/design-tokens.json (11.8 KB)
-✅ Written: {base_path}/style-consolidation/style-2/style-guide.md (7.9 KB)
-... (for all {variants_count} variants)
+✅ Variant 1 ({variant_name}):
+   - design-tokens.json: 12.5 KB | {token_count} tokens
+   - style-guide.md: 8.3 KB
+✅ Variant 2 ({variant_name}):
+   - design-tokens.json: 11.8 KB | {token_count} tokens
+   - style-guide.md: 7.9 KB
+... (for all variants)
+
+Summary: {variants_count} design systems generated with {total_mcp_queries} MCP queries
 ```

-## Critical Requirements
- Generate files for ALL {variants_count} variants
- Use sequential IDs: style-1, style-2, ..., style-{variants_count}
- Each variant must be complete and independent
- Maintain consistent structure across all variants
- Write files directly using Write() tool - do NOT return contents as text
+## KEY REMINDERS (CRITICAL)
+
+**ALWAYS:**
+- Use Write() tool for EVERY file - this is your PRIMARY responsibility
+- Write files immediately after generating content for each variant
+- Verify each Write() operation succeeds before proceeding
+- Use exact paths provided: `{base_path}/style-consolidation/style-{variant_id}/...`
+- Execute MCP research independently for each variant
+- Report completion with file paths and sizes
+
+**NEVER:**
+- Return file contents as text with labeled sections
+- Accumulate all content and try to output at once
+- Skip Write() operations and expect orchestrator to write files
+- Use relative paths or modify provided paths
+- Skip MCP research if design_space_analysis is provided
+- Generate variant N+1 before completing variant N writes
 """

-# Execute agent task
+# Dispatch to ui-design-agent with task prompt
 Task(subagent_type="ui-design-agent", description="Generate {variants_count} separate design systems", prompt=agent_task_prompt)

 REPORT: "✅ Agent task dispatched for {variants_count} design systems"