mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-13 02:41:50 +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
@@ -0,0 +1,764 @@
|
||||
---
|
||||
name: code-map-memory
|
||||
description: 3-phase orchestrator: parse feature keyword → cli-explore-agent analyzes (Deep Scan dual-source) → orchestrator generates Mermaid docs + SKILL package (skips phase 2 if exists)
|
||||
argument-hint: "\"feature-keyword\" [--regenerate] [--tool <gemini|qwen>]"
|
||||
allowed-tools: SlashCommand(*), TodoWrite(*), Bash(*), Read(*), Write(*), Task(*)
|
||||
---
|
||||
|
||||
# Code Flow Mapping Generator
|
||||
|
||||
## Overview
|
||||
|
||||
**Pure Orchestrator with Agent Delegation**: Prepares context paths and delegates code flow analysis to specialized cli-explore-agent. Orchestrator transforms agent's JSON analysis into Mermaid documentation.
|
||||
|
||||
**Auto-Continue Workflow**: Runs fully autonomously once triggered. Each phase completes and automatically triggers the next phase.
|
||||
|
||||
**Execution Paths**:
|
||||
- **Full Path**: All 3 phases (no existing codemap OR `--regenerate` specified)
|
||||
- **Skip Path**: Phase 1 → Phase 3 (existing codemap found AND no `--regenerate` flag)
|
||||
- **Phase 3 Always Executes**: SKILL index is always generated or updated
|
||||
|
||||
**Agent Responsibility** (cli-explore-agent):
|
||||
- Deep code flow analysis using dual-source strategy (Bash + Gemini CLI)
|
||||
- Returns structured JSON with architecture, functions, data flow, conditionals, patterns
|
||||
- NO file writing - analysis only
|
||||
|
||||
**Orchestrator Responsibility**:
|
||||
- Provides feature keyword and analysis scope to agent
|
||||
- Transforms agent's JSON into Mermaid-enriched markdown documentation
|
||||
- Writes all files (5 docs + metadata.json + SKILL.md)
|
||||
|
||||
## Core Rules
|
||||
|
||||
1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 execution
|
||||
2. **Feature-Specific SKILL**: Each feature creates independent `.claude/skills/codemap-{feature}/` package
|
||||
3. **Specialized Agent**: Phase 2a uses cli-explore-agent for professional code analysis (Deep Scan mode)
|
||||
4. **Orchestrator Documentation**: Phase 2b transforms agent JSON into Mermaid markdown files
|
||||
5. **Auto-Continue**: After completing each phase, update TodoWrite and immediately execute next phase
|
||||
6. **No User Prompts**: Never ask user questions or wait for input between phases
|
||||
7. **Track Progress**: Update TodoWrite after EVERY phase completion before starting next phase
|
||||
8. **Multi-Level Detail**: Generate 4 levels: architecture → function → data → conditional
|
||||
|
||||
---
|
||||
|
||||
## 3-Phase Execution
|
||||
|
||||
### Phase 1: Parse Feature Keyword & Check Existing
|
||||
|
||||
**Goal**: Normalize feature keyword, check existing codemap, prepare for analysis
|
||||
|
||||
**Step 1: Parse Feature Keyword**
|
||||
```bash
|
||||
# Get feature keyword from argument
|
||||
FEATURE_KEYWORD="$1"
|
||||
|
||||
# Normalize: lowercase, spaces to hyphens
|
||||
normalized_feature=$(echo "$FEATURE_KEYWORD" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr '_' '-')
|
||||
|
||||
# Example: "User Authentication" → "user-authentication"
|
||||
# Example: "支付处理" → "支付处理" (keep non-ASCII)
|
||||
```
|
||||
|
||||
**Step 2: Set Tool Preference**
|
||||
```bash
|
||||
# Default to gemini unless --tool specified
|
||||
TOOL="${tool_flag:-gemini}"
|
||||
```
|
||||
|
||||
**Step 3: Check Existing Codemap**
|
||||
```bash
|
||||
# Define codemap directory
|
||||
CODEMAP_DIR=".claude/skills/codemap-${normalized_feature}"
|
||||
|
||||
# Check if codemap exists
|
||||
bash(test -d "$CODEMAP_DIR" && echo "exists" || echo "not_exists")
|
||||
|
||||
# Count existing files
|
||||
bash(find "$CODEMAP_DIR" -name "*.md" 2>/dev/null | wc -l || echo 0)
|
||||
```
|
||||
|
||||
**Step 4: Skip Decision**
|
||||
```javascript
|
||||
if (existing_files > 0 && !regenerate_flag) {
|
||||
SKIP_GENERATION = true
|
||||
message = "Codemap already exists, skipping Phase 2. Use --regenerate to force regeneration."
|
||||
} else if (regenerate_flag) {
|
||||
bash(rm -rf "$CODEMAP_DIR")
|
||||
SKIP_GENERATION = false
|
||||
message = "Regenerating codemap from scratch."
|
||||
} else {
|
||||
SKIP_GENERATION = false
|
||||
message = "No existing codemap found, generating new code flow analysis."
|
||||
}
|
||||
```
|
||||
|
||||
**Output Variables**:
|
||||
- `FEATURE_KEYWORD`: Original feature keyword
|
||||
- `normalized_feature`: Normalized feature name for directory
|
||||
- `CODEMAP_DIR`: `.claude/skills/codemap-{feature}`
|
||||
- `TOOL`: CLI tool to use (gemini or qwen)
|
||||
- `SKIP_GENERATION`: Boolean - whether to skip Phase 2
|
||||
|
||||
**TodoWrite**:
|
||||
- If skipping: Mark phase 1 completed, phase 2 completed, phase 3 in_progress
|
||||
- If not skipping: Mark phase 1 completed, phase 2 in_progress
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Code Flow Analysis & Documentation Generation
|
||||
|
||||
**Skip Condition**: Skipped if `SKIP_GENERATION = true`
|
||||
|
||||
**Goal**: Use cli-explore-agent for professional code analysis, then orchestrator generates Mermaid documentation
|
||||
|
||||
**Architecture**: Phase 2a (Agent Analysis) → Phase 2b (Orchestrator Documentation)
|
||||
|
||||
---
|
||||
|
||||
#### Phase 2a: cli-explore-agent Analysis
|
||||
|
||||
**Purpose**: Leverage specialized cli-explore-agent for deep code flow analysis
|
||||
|
||||
**Agent Task Specification**:
|
||||
|
||||
```
|
||||
Task(
|
||||
subagent_type: "cli-explore-agent",
|
||||
description: "Analyze code flow: {FEATURE_KEYWORD}",
|
||||
prompt: "
|
||||
Perform Deep Scan analysis for feature: {FEATURE_KEYWORD}
|
||||
|
||||
**Analysis Mode**: deep-scan (Dual-source: Bash structural scan + Gemini semantic analysis)
|
||||
|
||||
**Analysis Objectives**:
|
||||
1. **Module Architecture**: Identify high-level module organization, interactions, and entry points
|
||||
2. **Function Call Chains**: Trace execution paths, call sequences, and parameter flows
|
||||
3. **Data Transformations**: Map data structure changes and transformation stages
|
||||
4. **Conditional Paths**: Document decision trees, branches, and error handling strategies
|
||||
5. **Design Patterns**: Discover architectural patterns and extract design intent
|
||||
|
||||
**Scope**:
|
||||
- Feature: {FEATURE_KEYWORD}
|
||||
- CLI Tool: {TOOL} (gemini-2.5-pro or qwen coder-model)
|
||||
- File Discovery: MCP Code Index (preferred) + rg fallback
|
||||
- Target: 5-15 most relevant files
|
||||
|
||||
**Expected Output Format**:
|
||||
Return comprehensive analysis as structured JSON:
|
||||
{
|
||||
\"feature\": \"{FEATURE_KEYWORD}\",
|
||||
\"analysis_metadata\": {
|
||||
\"tool_used\": \"gemini|qwen\",
|
||||
\"timestamp\": \"ISO_TIMESTAMP\",
|
||||
\"analysis_mode\": \"deep-scan\"
|
||||
},
|
||||
\"files_analyzed\": [
|
||||
{\"file\": \"path/to/file.ts\", \"relevance\": \"high|medium|low\", \"role\": \"brief description\"}
|
||||
],
|
||||
\"architecture\": {
|
||||
\"overview\": \"High-level description\",
|
||||
\"modules\": [
|
||||
{\"name\": \"ModuleName\", \"file\": \"file:line\", \"responsibility\": \"description\", \"dependencies\": [...]}
|
||||
],
|
||||
\"interactions\": [
|
||||
{\"from\": \"ModuleA\", \"to\": \"ModuleB\", \"type\": \"import|call|data-flow\", \"description\": \"...\"}
|
||||
],
|
||||
\"entry_points\": [
|
||||
{\"function\": \"main\", \"file\": \"file:line\", \"description\": \"...\"}
|
||||
]
|
||||
},
|
||||
\"function_calls\": {
|
||||
\"call_chains\": [
|
||||
{
|
||||
\"chain_id\": 1,
|
||||
\"description\": \"User authentication flow\",
|
||||
\"sequence\": [
|
||||
{\"function\": \"login\", \"file\": \"file:line\", \"calls\": [\"validateCredentials\", \"createSession\"]}
|
||||
]
|
||||
}
|
||||
],
|
||||
\"sequences\": [
|
||||
{\"from\": \"Client\", \"to\": \"AuthService\", \"method\": \"login(username, password)\", \"returns\": \"Session\"}
|
||||
]
|
||||
},
|
||||
\"data_flow\": {
|
||||
\"structures\": [
|
||||
{\"name\": \"UserData\", \"stage\": \"input\", \"shape\": {\"username\": \"string\", \"password\": \"string\"}}
|
||||
],
|
||||
\"transformations\": [
|
||||
{\"from\": \"RawInput\", \"to\": \"ValidatedData\", \"transformer\": \"validateUser\", \"file\": \"file:line\"}
|
||||
]
|
||||
},
|
||||
\"conditional_logic\": {
|
||||
\"branches\": [
|
||||
{\"condition\": \"isAuthenticated\", \"file\": \"file:line\", \"true_path\": \"...\", \"false_path\": \"...\"}
|
||||
],
|
||||
\"error_handling\": [
|
||||
{\"error_type\": \"AuthenticationError\", \"handler\": \"handleAuthError\", \"file\": \"file:line\", \"recovery\": \"retry|fail\"}
|
||||
]
|
||||
},
|
||||
\"design_patterns\": [
|
||||
{\"pattern\": \"Repository Pattern\", \"location\": \"src/repositories\", \"description\": \"...\"}
|
||||
],
|
||||
\"recommendations\": [
|
||||
\"Consider extracting authentication logic into separate module\",
|
||||
\"Add error recovery for network failures\"
|
||||
]
|
||||
}
|
||||
|
||||
**Critical Requirements**:
|
||||
- Use Deep Scan mode: Bash (Phase 1 - precise locations) + Gemini CLI (Phase 2 - semantic understanding) + Synthesis (Phase 3 - merge with attribution)
|
||||
- Focus exclusively on {FEATURE_KEYWORD} feature flow
|
||||
- Include file:line references for ALL findings
|
||||
- Extract design intent from code structure and comments
|
||||
- NO FILE WRITING - return JSON analysis only
|
||||
- Handle tool failures gracefully (Gemini → Qwen fallback, MCP → rg fallback)
|
||||
"
|
||||
)
|
||||
```
|
||||
|
||||
**Agent Output**: JSON analysis result with architecture, functions, data flow, conditionals, and patterns
|
||||
|
||||
---
|
||||
|
||||
#### Phase 2b: Orchestrator Documentation Generation
|
||||
|
||||
**Purpose**: Transform cli-explore-agent JSON into Mermaid-enriched documentation
|
||||
|
||||
**Input**: Agent's JSON analysis result
|
||||
|
||||
**Process**:
|
||||
|
||||
1. **Parse Agent Analysis**:
|
||||
```javascript
|
||||
const analysis = JSON.parse(agentResult)
|
||||
const { feature, files_analyzed, architecture, function_calls, data_flow, conditional_logic, design_patterns } = analysis
|
||||
```
|
||||
|
||||
2. **Generate Mermaid Diagrams from Structured Data**:
|
||||
|
||||
**a) architecture-flow.md** (~3K tokens):
|
||||
```javascript
|
||||
// Convert architecture.modules + architecture.interactions → Mermaid graph TD
|
||||
const architectureMermaid = `
|
||||
graph TD
|
||||
${architecture.modules.map(m => ` ${m.name}[${m.name}]`).join('\n')}
|
||||
${architecture.interactions.map(i => ` ${i.from} -->|${i.type}| ${i.to}`).join('\n')}
|
||||
`
|
||||
|
||||
Write({
|
||||
file_path: `${CODEMAP_DIR}/architecture-flow.md`,
|
||||
content: `---
|
||||
feature: ${feature}
|
||||
level: architecture
|
||||
detail: high-level module interactions
|
||||
---
|
||||
# Architecture Flow: ${feature}
|
||||
|
||||
## Overview
|
||||
${architecture.overview}
|
||||
|
||||
## Module Architecture
|
||||
${architecture.modules.map(m => `### ${m.name}\n- **File**: ${m.file}\n- **Role**: ${m.responsibility}\n- **Dependencies**: ${m.dependencies.join(', ')}`).join('\n\n')}
|
||||
|
||||
## Flow Diagram
|
||||
\`\`\`mermaid
|
||||
${architectureMermaid}
|
||||
\`\`\`
|
||||
|
||||
## Key Interactions
|
||||
${architecture.interactions.map(i => `- **${i.from} → ${i.to}**: ${i.description}`).join('\n')}
|
||||
|
||||
## Entry Points
|
||||
${architecture.entry_points.map(e => `- **${e.function}** (${e.file}): ${e.description}`).join('\n')}
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
**b) function-calls.md** (~5K tokens):
|
||||
```javascript
|
||||
// Convert function_calls.sequences → Mermaid sequenceDiagram
|
||||
const sequenceMermaid = `
|
||||
sequenceDiagram
|
||||
${function_calls.sequences.map(s => ` ${s.from}->>${s.to}: ${s.method}`).join('\n')}
|
||||
`
|
||||
|
||||
Write({
|
||||
file_path: `${CODEMAP_DIR}/function-calls.md`,
|
||||
content: `---
|
||||
feature: ${feature}
|
||||
level: function
|
||||
detail: function-level call sequences
|
||||
---
|
||||
# Function Call Chains: ${feature}
|
||||
|
||||
## Call Sequence Diagram
|
||||
\`\`\`mermaid
|
||||
${sequenceMermaid}
|
||||
\`\`\`
|
||||
|
||||
## Detailed Call Chains
|
||||
${function_calls.call_chains.map(chain => `
|
||||
### Chain ${chain.chain_id}: ${chain.description}
|
||||
${chain.sequence.map(fn => `- **${fn.function}** (${fn.file})\n - Calls: ${fn.calls.join(', ')}`).join('\n')}
|
||||
`).join('\n')}
|
||||
|
||||
## Parameters & Returns
|
||||
${function_calls.sequences.map(s => `- **${s.method}** → Returns: ${s.returns || 'void'}`).join('\n')}
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
**c) data-flow.md** (~4K tokens):
|
||||
```javascript
|
||||
// Convert data_flow.transformations → Mermaid flowchart LR
|
||||
const dataFlowMermaid = `
|
||||
flowchart LR
|
||||
${data_flow.transformations.map((t, i) => ` Stage${i}[${t.from}] -->|${t.transformer}| Stage${i+1}[${t.to}]`).join('\n')}
|
||||
`
|
||||
|
||||
Write({
|
||||
file_path: `${CODEMAP_DIR}/data-flow.md`,
|
||||
content: `---
|
||||
feature: ${feature}
|
||||
level: data
|
||||
detail: data structure transformations
|
||||
---
|
||||
# Data Flow: ${feature}
|
||||
|
||||
## Data Transformation Diagram
|
||||
\`\`\`mermaid
|
||||
${dataFlowMermaid}
|
||||
\`\`\`
|
||||
|
||||
## Data Structures
|
||||
${data_flow.structures.map(s => `### ${s.name} (${s.stage})\n\`\`\`json\n${JSON.stringify(s.shape, null, 2)}\n\`\`\``).join('\n\n')}
|
||||
|
||||
## Transformations
|
||||
${data_flow.transformations.map(t => `- **${t.from} → ${t.to}** via \`${t.transformer}\` (${t.file})`).join('\n')}
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
**d) conditional-paths.md** (~4K tokens):
|
||||
```javascript
|
||||
// Convert conditional_logic.branches → Mermaid flowchart TD
|
||||
const conditionalMermaid = `
|
||||
flowchart TD
|
||||
Start[Entry Point]
|
||||
${conditional_logic.branches.map((b, i) => `
|
||||
Start --> Check${i}{${b.condition}}
|
||||
Check${i} -->|Yes| Path${i}A[${b.true_path}]
|
||||
Check${i} -->|No| Path${i}B[${b.false_path}]
|
||||
`).join('\n')}
|
||||
`
|
||||
|
||||
Write({
|
||||
file_path: `${CODEMAP_DIR}/conditional-paths.md`,
|
||||
content: `---
|
||||
feature: ${feature}
|
||||
level: conditional
|
||||
detail: decision trees and error paths
|
||||
---
|
||||
# Conditional Paths: ${feature}
|
||||
|
||||
## Decision Tree
|
||||
\`\`\`mermaid
|
||||
${conditionalMermaid}
|
||||
\`\`\`
|
||||
|
||||
## Branch Conditions
|
||||
${conditional_logic.branches.map(b => `- **${b.condition}** (${b.file})\n - True: ${b.true_path}\n - False: ${b.false_path}`).join('\n')}
|
||||
|
||||
## Error Handling
|
||||
${conditional_logic.error_handling.map(e => `- **${e.error_type}**: Handler \`${e.handler}\` (${e.file}) - Recovery: ${e.recovery}`).join('\n')}
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
**e) complete-flow.md** (~8K tokens):
|
||||
```javascript
|
||||
// Integrate all Mermaid diagrams
|
||||
Write({
|
||||
file_path: `${CODEMAP_DIR}/complete-flow.md`,
|
||||
content: `---
|
||||
feature: ${feature}
|
||||
level: complete
|
||||
detail: integrated multi-level view
|
||||
---
|
||||
# Complete Flow: ${feature}
|
||||
|
||||
## Integrated Flow Diagram
|
||||
\`\`\`mermaid
|
||||
graph TB
|
||||
subgraph Architecture
|
||||
${architecture.modules.map(m => ` ${m.name}[${m.name}]`).join('\n')}
|
||||
end
|
||||
|
||||
subgraph "Function Calls"
|
||||
${function_calls.call_chains[0]?.sequence.map(fn => ` ${fn.function}`).join('\n') || ''}
|
||||
end
|
||||
|
||||
subgraph "Data Flow"
|
||||
${data_flow.structures.map(s => ` ${s.name}[${s.name}]`).join('\n')}
|
||||
end
|
||||
\`\`\`
|
||||
|
||||
## Complete Trace
|
||||
[Comprehensive end-to-end documentation combining all analysis layers]
|
||||
|
||||
## Design Patterns Identified
|
||||
${design_patterns.map(p => `- **${p.pattern}** in ${p.location}: ${p.description}`).join('\n')}
|
||||
|
||||
## Recommendations
|
||||
${analysis.recommendations.map(r => `- ${r}`).join('\n')}
|
||||
|
||||
## Cross-References
|
||||
- [Architecture Flow](./architecture-flow.md) - High-level module structure
|
||||
- [Function Calls](./function-calls.md) - Detailed call chains
|
||||
- [Data Flow](./data-flow.md) - Data transformation stages
|
||||
- [Conditional Paths](./conditional-paths.md) - Decision trees and error handling
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
3. **Write metadata.json**:
|
||||
```javascript
|
||||
Write({
|
||||
file_path: `${CODEMAP_DIR}/metadata.json`,
|
||||
content: JSON.stringify({
|
||||
feature: feature,
|
||||
normalized_name: normalized_feature,
|
||||
generated_at: new Date().toISOString(),
|
||||
tool_used: analysis.analysis_metadata.tool_used,
|
||||
files_analyzed: files_analyzed.map(f => f.file),
|
||||
analysis_summary: {
|
||||
total_files: files_analyzed.length,
|
||||
modules_traced: architecture.modules.length,
|
||||
functions_traced: function_calls.call_chains.reduce((sum, c) => sum + c.sequence.length, 0),
|
||||
patterns_discovered: design_patterns.length
|
||||
}
|
||||
}, null, 2)
|
||||
})
|
||||
```
|
||||
|
||||
4. **Report Phase 2 Completion**:
|
||||
```
|
||||
Phase 2 Complete: Code flow analysis and documentation generated
|
||||
|
||||
- Agent Analysis: cli-explore-agent with {TOOL}
|
||||
- Files Analyzed: {count}
|
||||
- Documentation Generated: 5 markdown files + metadata.json
|
||||
- Location: {CODEMAP_DIR}
|
||||
```
|
||||
|
||||
**Completion Criteria**:
|
||||
- cli-explore-agent task completed successfully with JSON result
|
||||
- 5 documentation files written with valid Mermaid diagrams
|
||||
- metadata.json written with analysis summary
|
||||
- All files properly formatted and cross-referenced
|
||||
|
||||
**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Generate SKILL.md Index
|
||||
|
||||
**Note**: This phase **ALWAYS executes** - generates or updates the SKILL index.
|
||||
|
||||
**Goal**: Read generated flow documentation and create SKILL.md index with progressive loading
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. **Verify Generated Files**:
|
||||
```bash
|
||||
bash(find "{CODEMAP_DIR}" -name "*.md" -type f | sort)
|
||||
```
|
||||
|
||||
2. **Read metadata.json**:
|
||||
```javascript
|
||||
Read({CODEMAP_DIR}/metadata.json)
|
||||
// Extract: feature, normalized_name, files_analyzed, analysis_summary
|
||||
```
|
||||
|
||||
3. **Read File Headers** (optional, first 30 lines):
|
||||
```javascript
|
||||
Read({CODEMAP_DIR}/architecture-flow.md, limit: 30)
|
||||
Read({CODEMAP_DIR}/function-calls.md, limit: 30)
|
||||
// Extract overview and diagram counts
|
||||
```
|
||||
|
||||
4. **Generate SKILL.md Index**:
|
||||
|
||||
Template structure:
|
||||
```yaml
|
||||
---
|
||||
name: codemap-{normalized_feature}
|
||||
description: Code flow mapping for {FEATURE_KEYWORD} feature (located at {project_path}). Load this SKILL when analyzing, tracing, or understanding {FEATURE_KEYWORD} execution flow, especially when no relevant context exists in memory.
|
||||
version: 1.0.0
|
||||
generated_at: {ISO_TIMESTAMP}
|
||||
---
|
||||
# Code Flow Map: {FEATURE_KEYWORD}
|
||||
|
||||
## Feature: `{FEATURE_KEYWORD}`
|
||||
|
||||
**Analysis Date**: {DATE}
|
||||
**Tool Used**: {TOOL}
|
||||
**Files Analyzed**: {COUNT}
|
||||
|
||||
## Progressive Loading
|
||||
|
||||
### Level 0: Quick Overview (~2K tokens)
|
||||
- [Architecture Flow](./architecture-flow.md) - High-level module interactions
|
||||
|
||||
### Level 1: Core Flows (~10K tokens)
|
||||
- [Architecture Flow](./architecture-flow.md) - Module architecture
|
||||
- [Function Calls](./function-calls.md) - Function call chains
|
||||
|
||||
### Level 2: Complete Analysis (~20K tokens)
|
||||
- [Architecture Flow](./architecture-flow.md)
|
||||
- [Function Calls](./function-calls.md)
|
||||
- [Data Flow](./data-flow.md) - Data transformations
|
||||
|
||||
### Level 3: Deep Dive (~30K tokens)
|
||||
- [Architecture Flow](./architecture-flow.md)
|
||||
- [Function Calls](./function-calls.md)
|
||||
- [Data Flow](./data-flow.md)
|
||||
- [Conditional Paths](./conditional-paths.md) - Branches and error handling
|
||||
- [Complete Flow](./complete-flow.md) - Integrated comprehensive view
|
||||
|
||||
## Usage
|
||||
|
||||
Load this SKILL package when:
|
||||
- Analyzing {FEATURE_KEYWORD} implementation
|
||||
- Tracing execution flow for debugging
|
||||
- Understanding code dependencies
|
||||
- Planning refactoring or enhancements
|
||||
|
||||
## Analysis Summary
|
||||
|
||||
- **Modules Traced**: {modules_traced}
|
||||
- **Functions Traced**: {functions_traced}
|
||||
- **Files Analyzed**: {total_files}
|
||||
|
||||
## Mermaid Diagrams Included
|
||||
|
||||
- Architecture flow diagram (graph TD)
|
||||
- Function call sequence diagram (sequenceDiagram)
|
||||
- Data transformation flowchart (flowchart LR)
|
||||
- Conditional decision tree (flowchart TD)
|
||||
- Complete integrated diagram (graph TB)
|
||||
```
|
||||
|
||||
5. **Write SKILL.md**:
|
||||
```javascript
|
||||
Write({
|
||||
file_path: `{CODEMAP_DIR}/SKILL.md`,
|
||||
content: generatedIndexMarkdown
|
||||
})
|
||||
```
|
||||
|
||||
**Completion Criteria**:
|
||||
- SKILL.md index written
|
||||
- All documentation files verified
|
||||
- Progressive loading levels (0-3) properly structured
|
||||
- Mermaid diagram references included
|
||||
|
||||
**TodoWrite**: Mark phase 3 completed
|
||||
|
||||
**Final Report**:
|
||||
```
|
||||
Code Flow Mapping Complete
|
||||
|
||||
Feature: {FEATURE_KEYWORD}
|
||||
Location: .claude/skills/codemap-{normalized_feature}/
|
||||
|
||||
Files Generated:
|
||||
- SKILL.md (index)
|
||||
- architecture-flow.md (with Mermaid diagram)
|
||||
- function-calls.md (with Mermaid sequence diagram)
|
||||
- data-flow.md (with Mermaid flowchart)
|
||||
- conditional-paths.md (with Mermaid decision tree)
|
||||
- complete-flow.md (with integrated Mermaid diagram)
|
||||
- metadata.json
|
||||
|
||||
Analysis:
|
||||
- Files analyzed: {count}
|
||||
- Modules traced: {count}
|
||||
- Functions traced: {count}
|
||||
|
||||
Usage: Skill(command: "codemap-{normalized_feature}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### TodoWrite Patterns
|
||||
|
||||
**Initialization** (Before Phase 1):
|
||||
```javascript
|
||||
TodoWrite({todos: [
|
||||
{"content": "Parse feature keyword and check existing", "status": "in_progress", "activeForm": "Parsing feature keyword"},
|
||||
{"content": "Agent analyzes code flow and generates files", "status": "pending", "activeForm": "Analyzing code flow"},
|
||||
{"content": "Generate SKILL.md index", "status": "pending", "activeForm": "Generating SKILL index"}
|
||||
]})
|
||||
```
|
||||
|
||||
**Full Path** (SKIP_GENERATION = false):
|
||||
```javascript
|
||||
// After Phase 1
|
||||
TodoWrite({todos: [
|
||||
{"content": "Parse feature keyword and check existing", "status": "completed", ...},
|
||||
{"content": "Agent analyzes code flow and generates files", "status": "in_progress", ...},
|
||||
{"content": "Generate SKILL.md index", "status": "pending", ...}
|
||||
]})
|
||||
|
||||
// After Phase 2
|
||||
TodoWrite({todos: [
|
||||
{"content": "Parse feature keyword and check existing", "status": "completed", ...},
|
||||
{"content": "Agent analyzes code flow and generates files", "status": "completed", ...},
|
||||
{"content": "Generate SKILL.md index", "status": "in_progress", ...}
|
||||
]})
|
||||
|
||||
// After Phase 3
|
||||
TodoWrite({todos: [
|
||||
{"content": "Parse feature keyword and check existing", "status": "completed", ...},
|
||||
{"content": "Agent analyzes code flow and generates files", "status": "completed", ...},
|
||||
{"content": "Generate SKILL.md index", "status": "completed", ...}
|
||||
]})
|
||||
```
|
||||
|
||||
**Skip Path** (SKIP_GENERATION = true):
|
||||
```javascript
|
||||
// After Phase 1 (skip Phase 2)
|
||||
TodoWrite({todos: [
|
||||
{"content": "Parse feature keyword and check existing", "status": "completed", ...},
|
||||
{"content": "Agent analyzes code flow and generates files", "status": "completed", ...}, // Skipped
|
||||
{"content": "Generate SKILL.md index", "status": "in_progress", ...}
|
||||
]})
|
||||
```
|
||||
|
||||
### Execution Flow
|
||||
|
||||
**Full Path**:
|
||||
```
|
||||
User → TodoWrite Init → Phase 1 (parse) → Phase 2 (agent analyzes) → Phase 3 (write index) → Report
|
||||
```
|
||||
|
||||
**Skip Path**:
|
||||
```
|
||||
User → TodoWrite Init → Phase 1 (detect existing) → Phase 3 (update index) → Report
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
**Phase 1 Errors**:
|
||||
- Empty feature keyword: Report error, ask user to provide feature description
|
||||
- Invalid characters: Normalize and continue
|
||||
|
||||
**Phase 2 Errors (Agent)**:
|
||||
- Agent task fails: Retry once, report if fails again
|
||||
- No files discovered: Warn user, ask for more specific feature keyword
|
||||
- CLI failures: Agent handles internally with retries
|
||||
- Invalid Mermaid syntax: Agent validates before writing
|
||||
|
||||
**Phase 3 Errors**:
|
||||
- Write failures: Report which files failed
|
||||
- Missing files: Note in SKILL.md, suggest regeneration
|
||||
|
||||
---
|
||||
|
||||
## Parameters
|
||||
|
||||
```bash
|
||||
/memory:code-map-memory "feature-keyword" [--regenerate] [--tool <gemini|qwen>]
|
||||
```
|
||||
|
||||
**Arguments**:
|
||||
- **"feature-keyword"**: Feature or flow to analyze (required)
|
||||
- Examples: `"user authentication"`, `"payment processing"`, `"数据导入流程"`
|
||||
- Can be English, Chinese, or mixed
|
||||
- Spaces and underscores normalized to hyphens
|
||||
- **--regenerate**: Force regenerate existing codemap (deletes and recreates)
|
||||
- **--tool**: CLI tool for analysis (default: gemini)
|
||||
- `gemini`: Comprehensive flow analysis with gemini-2.5-pro
|
||||
- `qwen`: Alternative with coder-model
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
**Generated File Structure** (for all examples):
|
||||
```
|
||||
.claude/skills/codemap-{feature}/
|
||||
├── SKILL.md # Index (Phase 3)
|
||||
├── architecture-flow.md # Agent (Phase 2) - High-level flow
|
||||
├── function-calls.md # Agent (Phase 2) - Function chains
|
||||
├── data-flow.md # Agent (Phase 2) - Data transformations
|
||||
├── conditional-paths.md # Agent (Phase 2) - Branches & errors
|
||||
├── complete-flow.md # Agent (Phase 2) - Integrated view
|
||||
└── metadata.json # Agent (Phase 2)
|
||||
```
|
||||
|
||||
### Example 1: User Authentication Flow
|
||||
|
||||
```bash
|
||||
/memory:code-map-memory "user authentication"
|
||||
```
|
||||
|
||||
**Workflow**:
|
||||
1. Phase 1: Normalizes to "user-authentication", checks existing codemap
|
||||
2. Phase 2: Agent discovers auth-related files, executes CLI analysis, generates 5 flow docs with Mermaid
|
||||
3. Phase 3: Generates SKILL.md index with progressive loading
|
||||
|
||||
**Output**: `.claude/skills/codemap-user-authentication/` with 6 files + metadata
|
||||
|
||||
|
||||
### Example 3: Regenerate with Qwen
|
||||
|
||||
```bash
|
||||
/memory:code-map-memory "payment processing" --regenerate --tool qwen
|
||||
```
|
||||
|
||||
**Workflow**:
|
||||
1. Phase 1: Deletes existing codemap due to --regenerate
|
||||
2. Phase 2: Agent uses qwen with coder-model for fresh analysis
|
||||
3. Phase 3: Generates updated SKILL.md
|
||||
|
||||
---
|
||||
|
||||
## Benefits
|
||||
|
||||
- **Per-Feature SKILL**: Independent packages for each analyzed feature
|
||||
- **Specialized Agent**: cli-explore-agent with Deep Scan mode (Bash + Gemini dual-source)
|
||||
- **Professional Analysis**: Pre-defined workflow for code exploration and structure analysis
|
||||
- **Clear Separation**: Agent analyzes (JSON) → Orchestrator documents (Mermaid markdown)
|
||||
- **Multi-Level Detail**: 4 levels (architecture → function → data → conditional)
|
||||
- **Visual Flow**: Embedded Mermaid diagrams for all flow types
|
||||
- **Progressive Loading**: Token-efficient context loading (2K → 30K)
|
||||
- **Auto-Continue**: Fully autonomous 3-phase execution
|
||||
- **Smart Skip**: Detects existing codemap, 10x faster index updates
|
||||
- **CLI Integration**: Gemini/Qwen for deep semantic understanding
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
code-map-memory (orchestrator)
|
||||
├─ Phase 1: Parse & Check (bash commands, skip decision)
|
||||
├─ Phase 2: Code Analysis & Documentation (skippable)
|
||||
│ ├─ Phase 2a: cli-explore-agent Analysis
|
||||
│ │ └─ Deep Scan: Bash structural + Gemini semantic → JSON
|
||||
│ └─ Phase 2b: Orchestrator Documentation
|
||||
│ └─ Transform JSON → 5 Mermaid markdown files + metadata.json
|
||||
└─ Phase 3: Write SKILL.md (index generation, always runs)
|
||||
|
||||
Benefits:
|
||||
✅ Specialized agent: cli-explore-agent with dual-source strategy (Bash + Gemini)
|
||||
✅ Professional analysis: Pre-defined Deep Scan workflow
|
||||
✅ Clear separation: Agent analyzes (JSON) → Orchestrator documents (Mermaid)
|
||||
✅ Smart skip logic: 10x faster when codemap exists
|
||||
✅ Multi-level detail: Architecture → Functions → Data → Conditionals
|
||||
|
||||
Output: .claude/skills/codemap-{feature}/
|
||||
```
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
name: memory:style-skill-memory
|
||||
name: style-skill-memory
|
||||
description: Generate SKILL memory package from style reference for easy loading and consistent design system usage
|
||||
argument-hint: "[package-name] [--regenerate]"
|
||||
allowed-tools: Bash,Read,Write,TodoWrite
|
||||
@@ -18,6 +18,12 @@ auto-continue: true
|
||||
|
||||
**Use Case**: Load design system context when working with UI components, analyzing design patterns, or implementing style guidelines.
|
||||
|
||||
**Key Features**:
|
||||
- Extracts primary design references (colors, typography, spacing, etc.)
|
||||
- Provides dynamic adjustment guidelines for design tokens
|
||||
- Progressive loading structure for efficient token usage
|
||||
- Interactive preview showcase
|
||||
|
||||
---
|
||||
|
||||
## Usage
|
||||
@@ -57,7 +63,7 @@ package-name Style reference package name (required)
|
||||
```json
|
||||
[
|
||||
{"content": "Validate style reference package", "status": "in_progress", "activeForm": "Validating package"},
|
||||
{"content": "Read package metadata and documentation", "status": "pending", "activeForm": "Reading metadata"},
|
||||
{"content": "Read package data and extract design references", "status": "pending", "activeForm": "Reading package data"},
|
||||
{"content": "Generate SKILL.md with progressive loading", "status": "pending", "activeForm": "Generating SKILL.md"}
|
||||
]
|
||||
```
|
||||
@@ -117,80 +123,141 @@ if (regenerate_flag && skill_exists) {
|
||||
```json
|
||||
[
|
||||
{"content": "Validate style reference package", "status": "completed", "activeForm": "Validating package"},
|
||||
{"content": "Read package metadata and documentation", "status": "in_progress", "activeForm": "Reading metadata"}
|
||||
{"content": "Read package data and extract design references", "status": "in_progress", "activeForm": "Reading package data"}
|
||||
]
|
||||
```
|
||||
|
||||
**Next Action**: Continue to Phase 2
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Read Package Metadata
|
||||
### Phase 2: Read Package Data & Extract Design References
|
||||
|
||||
**Purpose**: Extract metadata and documentation for SKILL description generation
|
||||
**Purpose**: Extract package information and primary design references for SKILL description generation
|
||||
|
||||
**Step 1: Read metadata.json**
|
||||
**Step 1: Count Components**
|
||||
|
||||
```bash
|
||||
Read(file_path=".workflow/reference_style/${package_name}/metadata.json")
|
||||
```
|
||||
|
||||
**Extract Fields**:
|
||||
- `packageName`
|
||||
- `version`
|
||||
- `generatedAt`
|
||||
- `description`
|
||||
- `source.design_run`
|
||||
- `files` (count available files)
|
||||
|
||||
**Step 2: Read README.md**
|
||||
|
||||
```bash
|
||||
Read(file_path=".workflow/reference_style/${package_name}/README.md")
|
||||
```
|
||||
|
||||
**Extract Information**:
|
||||
- Package overview
|
||||
- Component catalog reference
|
||||
- Design token categories
|
||||
|
||||
**Step 3: Count Components**
|
||||
|
||||
```bash
|
||||
bash(test -f .workflow/reference_style/${package_name}/component-patterns.json && jq '.extraction_metadata.component_count' .workflow/reference_style/${package_name}/component-patterns.json 2>/dev/null || grep -c '"button"\|"input"\|"card"\|"badge"\|"alert"' .workflow/reference_style/${package_name}/component-patterns.json 2>/dev/null || echo 0)
|
||||
bash(jq '.layout_templates | length' .workflow/reference_style/${package_name}/layout-templates.json 2>/dev/null || echo 0)
|
||||
```
|
||||
|
||||
Store result as `component_count`
|
||||
|
||||
**Step 4: Check Available Files**
|
||||
**Step 2: Extract Component Types and Classification**
|
||||
|
||||
```bash
|
||||
bash(cd .workflow/reference_style/${package_name} && ls -1 *.json *.md *.html *.css 2>/dev/null | wc -l)
|
||||
# Extract component names from layout templates
|
||||
bash(jq -r '.layout_templates | keys[]' .workflow/reference_style/${package_name}/layout-templates.json 2>/dev/null | head -10)
|
||||
|
||||
# Count universal vs specialized components
|
||||
bash(jq '[.layout_templates[] | select(.component_type == "universal")] | length' .workflow/reference_style/${package_name}/layout-templates.json 2>/dev/null || echo 0)
|
||||
bash(jq '[.layout_templates[] | select(.component_type == "specialized")] | length' .workflow/reference_style/${package_name}/layout-templates.json 2>/dev/null || echo 0)
|
||||
|
||||
# Extract universal component names only
|
||||
bash(jq -r '.layout_templates | to_entries | map(select(.value.component_type == "universal")) | .[].key' .workflow/reference_style/${package_name}/layout-templates.json 2>/dev/null | head -10)
|
||||
```
|
||||
|
||||
Store as:
|
||||
- `COMPONENT_TYPES`: List of available component types (all)
|
||||
- `UNIVERSAL_COUNT`: Number of universal (reusable) components
|
||||
- `SPECIALIZED_COUNT`: Number of specialized (project-specific) components
|
||||
- `UNIVERSAL_COMPONENTS`: List of universal component names
|
||||
|
||||
**Step 3: Read Design Tokens**
|
||||
|
||||
```bash
|
||||
Read(file_path=".workflow/reference_style/${package_name}/design-tokens.json")
|
||||
```
|
||||
|
||||
**Extract Primary Design References**:
|
||||
|
||||
**Colors** (top 3-5 most important):
|
||||
```bash
|
||||
bash(jq -r '.colors | to_entries | .[0:5] | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null | head -5)
|
||||
```
|
||||
|
||||
**Typography** (heading and body fonts):
|
||||
```bash
|
||||
bash(jq -r '.typography | to_entries | select(.key | contains("family")) | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null)
|
||||
```
|
||||
|
||||
**Spacing Scale** (base spacing values):
|
||||
```bash
|
||||
bash(jq -r '.spacing | to_entries | .[0:5] | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null)
|
||||
```
|
||||
|
||||
**Border Radius** (base radius values):
|
||||
```bash
|
||||
bash(jq -r '.border_radius | to_entries | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null)
|
||||
```
|
||||
|
||||
**Shadows** (elevation levels):
|
||||
```bash
|
||||
bash(jq -r '.shadows | to_entries | .[0:3] | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null)
|
||||
```
|
||||
|
||||
Store extracted references as:
|
||||
- `PRIMARY_COLORS`: List of primary color tokens
|
||||
- `TYPOGRAPHY_FONTS`: Font family tokens
|
||||
- `SPACING_SCALE`: Base spacing values
|
||||
- `BORDER_RADIUS`: Radius values
|
||||
- `SHADOWS`: Shadow definitions
|
||||
|
||||
**Step 4: Read Animation Tokens (if available)**
|
||||
|
||||
```bash
|
||||
# Check if animation tokens exist
|
||||
bash(test -f .workflow/reference_style/${package_name}/animation-tokens.json && echo "available" || echo "not_available")
|
||||
```
|
||||
|
||||
If available, extract:
|
||||
```bash
|
||||
Read(file_path=".workflow/reference_style/${package_name}/animation-tokens.json")
|
||||
|
||||
# Extract primary animation values
|
||||
bash(jq -r '.duration | to_entries | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/animation-tokens.json 2>/dev/null)
|
||||
bash(jq -r '.easing | to_entries | .[0:3] | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/animation-tokens.json 2>/dev/null)
|
||||
```
|
||||
|
||||
Store as:
|
||||
- `ANIMATION_DURATIONS`: Animation duration tokens
|
||||
- `EASING_FUNCTIONS`: Easing function tokens
|
||||
|
||||
**Step 5: Count Files**
|
||||
|
||||
```bash
|
||||
bash(cd .workflow/reference_style/${package_name} && ls -1 *.json *.html *.css 2>/dev/null | wc -l)
|
||||
```
|
||||
|
||||
Store result as `file_count`
|
||||
|
||||
**Summary Data**:
|
||||
- `COMPONENT_COUNT`: Number of components in catalog
|
||||
**Summary Data Collected**:
|
||||
- `COMPONENT_COUNT`: Number of components in layout templates
|
||||
- `UNIVERSAL_COUNT`: Number of universal (reusable) components
|
||||
- `SPECIALIZED_COUNT`: Number of specialized (project-specific) components
|
||||
- `COMPONENT_TYPES`: List of component types (first 10)
|
||||
- `UNIVERSAL_COMPONENTS`: List of universal component names (first 10)
|
||||
- `FILE_COUNT`: Total files in package
|
||||
- `VERSION`: Package version (from metadata.json)
|
||||
- `DESCRIPTION`: Package description (from metadata.json)
|
||||
- `HAS_ANIMATIONS`: Whether animation tokens are available
|
||||
- `PRIMARY_COLORS`: Primary color tokens with values
|
||||
- `TYPOGRAPHY_FONTS`: Font family tokens
|
||||
- `SPACING_SCALE`: Base spacing scale
|
||||
- `BORDER_RADIUS`: Border radius values
|
||||
- `SHADOWS`: Shadow definitions
|
||||
- `ANIMATION_DURATIONS`: Animation durations (if available)
|
||||
- `EASING_FUNCTIONS`: Easing functions (if available)
|
||||
|
||||
**TodoWrite Update**:
|
||||
```json
|
||||
[
|
||||
{"content": "Read package metadata and documentation", "status": "completed", "activeForm": "Reading metadata"},
|
||||
{"content": "Read package data and extract design references", "status": "completed", "activeForm": "Reading package data"},
|
||||
{"content": "Generate SKILL.md with progressive loading", "status": "in_progress", "activeForm": "Generating SKILL.md"}
|
||||
]
|
||||
```
|
||||
|
||||
**Next Action**: Continue to Phase 3
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Generate SKILL.md
|
||||
|
||||
**Purpose**: Create SKILL memory index with progressive loading structure
|
||||
**Purpose**: Create SKILL memory index with progressive loading structure and design references
|
||||
|
||||
**Step 1: Create SKILL Directory**
|
||||
|
||||
@@ -202,27 +269,30 @@ bash(mkdir -p .claude/skills/style-${package_name})
|
||||
|
||||
**Format**:
|
||||
```
|
||||
{Package Name} design system with {component_count} components and interactive preview (located at .workflow/reference_style/{package_name}). Load when working with UI components, design tokens, style guidelines, analyzing design patterns, or implementing visual consistency.
|
||||
{package_name} project-independent design system with {universal_count} universal layout templates and interactive preview (located at .workflow/reference_style/{package_name}). Load when working with reusable UI components, design tokens, layout patterns, or implementing visual consistency. Excludes {specialized_count} project-specific components.
|
||||
```
|
||||
|
||||
**Key Elements**:
|
||||
- **Component Count**: Emphasize available component catalog
|
||||
- **Universal Count**: Emphasize available reusable layout templates
|
||||
- **Project Independence**: Clearly state project-independent nature
|
||||
- **Specialized Exclusion**: Mention excluded project-specific components
|
||||
- **Path Reference**: Precise package location
|
||||
- **Trigger Keywords**: UI components, design tokens, style guidelines, design patterns
|
||||
- **Trigger Keywords**: reusable UI components, design tokens, layout patterns, visual consistency
|
||||
- **Action Coverage**: working with, analyzing, implementing
|
||||
|
||||
**Example**:
|
||||
```
|
||||
main-app-style-v1 design system with 8 components and interactive preview (located at .workflow/reference_style/main-app-style-v1). Load when working with UI components, design tokens, style guidelines, analyzing design patterns, or implementing visual consistency.
|
||||
main-app-style-v1 project-independent design system with 5 universal layout templates and interactive preview (located at .workflow/reference_style/main-app-style-v1). Load when working with reusable UI components, design tokens, layout patterns, or implementing visual consistency. Excludes 3 project-specific components.
|
||||
```
|
||||
|
||||
**Step 3: Write SKILL.md** (Use Write tool)
|
||||
**Step 3: Write SKILL.md**
|
||||
|
||||
Use Write tool to generate SKILL.md with the following complete content:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: style-{package_name}
|
||||
description: {intelligent description from Step 2}
|
||||
version: {version from metadata.json}
|
||||
---
|
||||
|
||||
# {Package Name} Style SKILL Package
|
||||
@@ -231,64 +301,199 @@ version: {version from metadata.json}
|
||||
|
||||
## Package Overview
|
||||
|
||||
Style reference package with comprehensive design system documentation and interactive component preview.
|
||||
**Project-independent style reference package** extracted from codebase with reusable design patterns, tokens, and interactive preview.
|
||||
|
||||
**Package Details**:
|
||||
- Package: {package_name}
|
||||
- Version: {version}
|
||||
- Components: {component_count}
|
||||
- Layout Templates: {component_count} total
|
||||
- **Universal Components**: {universal_count} (reusable, project-independent)
|
||||
- **Specialized Components**: {specialized_count} (project-specific, excluded from reference)
|
||||
- Universal Component Types: {comma-separated list of UNIVERSAL_COMPONENTS}
|
||||
- Files: {file_count}
|
||||
- Generated: {generatedAt}
|
||||
- Animation Tokens: {has_animations ? "✓ Available" : "Not available"}
|
||||
|
||||
**⚠️ IMPORTANT - Project Independence**:
|
||||
This SKILL package represents a **pure style system** independent of any specific project implementation:
|
||||
- **Universal components** are generic, reusable patterns (buttons, inputs, cards, navigation)
|
||||
- **Specialized components** are project-specific implementations (excluded from this reference)
|
||||
- All design tokens and layout patterns are extracted for **reference purposes only**
|
||||
- Adapt and customize these references based on your project's specific requirements
|
||||
|
||||
---
|
||||
|
||||
## ⚡ Primary Design References
|
||||
|
||||
**IMPORTANT**: These are **reference values** extracted from the codebase. They should be **dynamically adjusted** based on your specific design needs, not treated as fixed constraints.
|
||||
|
||||
### 🎨 Colors
|
||||
|
||||
{FOR each color in PRIMARY_COLORS:
|
||||
- **{color.key}**: `{color.value}`
|
||||
}
|
||||
|
||||
**Usage Guidelines**:
|
||||
- These colors establish the foundation of the design system
|
||||
- Adjust saturation, lightness, or hue based on:
|
||||
- Brand requirements and accessibility needs
|
||||
- Context (light/dark mode, high-contrast themes)
|
||||
- User feedback and A/B testing results
|
||||
- Use color theory principles to maintain harmony when modifying
|
||||
|
||||
### 📝 Typography
|
||||
|
||||
{FOR each font in TYPOGRAPHY_FONTS:
|
||||
- **{font.key}**: `{font.value}`
|
||||
}
|
||||
|
||||
**Usage Guidelines**:
|
||||
- Font families can be substituted based on:
|
||||
- Brand identity and design language
|
||||
- Performance requirements (web fonts vs. system fonts)
|
||||
- Accessibility and readability considerations
|
||||
- Platform-specific availability
|
||||
- Maintain hierarchy and scale relationships when changing fonts
|
||||
|
||||
### 📏 Spacing Scale
|
||||
|
||||
{FOR each spacing in SPACING_SCALE:
|
||||
- **{spacing.key}**: `{spacing.value}`
|
||||
}
|
||||
|
||||
**Usage Guidelines**:
|
||||
- Spacing values form a consistent rhythm system
|
||||
- Adjust scale based on:
|
||||
- Target device (mobile vs. desktop vs. tablet)
|
||||
- Content density requirements
|
||||
- Component-specific needs (compact vs. comfortable layouts)
|
||||
- Maintain proportional relationships when scaling
|
||||
|
||||
### 🔲 Border Radius
|
||||
|
||||
{FOR each radius in BORDER_RADIUS:
|
||||
- **{radius.key}**: `{radius.value}`
|
||||
}
|
||||
|
||||
**Usage Guidelines**:
|
||||
- Border radius affects visual softness and modernity
|
||||
- Adjust based on:
|
||||
- Design aesthetic (sharp vs. rounded vs. pill-shaped)
|
||||
- Component type (buttons, cards, inputs have different needs)
|
||||
- Platform conventions (iOS vs. Android vs. Web)
|
||||
|
||||
### 🌫️ Shadows
|
||||
|
||||
{FOR each shadow in SHADOWS:
|
||||
- **{shadow.key}**: `{shadow.value}`
|
||||
}
|
||||
|
||||
**Usage Guidelines**:
|
||||
- Shadows create elevation and depth perception
|
||||
- Adjust based on:
|
||||
- Material design depth levels
|
||||
- Light/dark mode contexts
|
||||
- Performance considerations (complex shadows impact rendering)
|
||||
- Visual hierarchy needs
|
||||
|
||||
{IF HAS_ANIMATIONS:
|
||||
### ⏱️ Animation & Timing
|
||||
|
||||
**Durations**:
|
||||
{FOR each duration in ANIMATION_DURATIONS:
|
||||
- **{duration.key}**: `{duration.value}`
|
||||
}
|
||||
|
||||
**Easing Functions**:
|
||||
{FOR each easing in EASING_FUNCTIONS:
|
||||
- **{easing.key}**: `{easing.value}`
|
||||
}
|
||||
|
||||
**Usage Guidelines**:
|
||||
- Animation timing affects perceived responsiveness and polish
|
||||
- Adjust based on:
|
||||
- User expectations and platform conventions
|
||||
- Accessibility preferences (reduced motion)
|
||||
- Animation type (micro-interactions vs. page transitions)
|
||||
- Performance constraints (mobile vs. desktop)
|
||||
}
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Design Adaptation Strategies
|
||||
|
||||
### When to Adjust Design References
|
||||
|
||||
**Brand Alignment**:
|
||||
- Modify colors to match brand identity and guidelines
|
||||
- Adjust typography to reflect brand personality
|
||||
- Tune spacing and radius to align with brand aesthetic
|
||||
|
||||
**Accessibility Requirements**:
|
||||
- Increase color contrast ratios for WCAG compliance
|
||||
- Adjust font sizes and spacing for readability
|
||||
- Modify animation durations for reduced-motion preferences
|
||||
|
||||
**Platform Optimization**:
|
||||
- Adapt spacing for mobile touch targets (min 44x44px)
|
||||
- Adjust shadows and radius for platform conventions
|
||||
- Optimize animation performance for target devices
|
||||
|
||||
**Context-Specific Needs**:
|
||||
- Dark mode: Adjust colors, shadows, and contrasts
|
||||
- High-density displays: Fine-tune spacing and sizing
|
||||
- Responsive design: Scale tokens across breakpoints
|
||||
|
||||
### How to Apply Adjustments
|
||||
|
||||
1. **Identify Need**: Determine which tokens need adjustment based on your specific requirements
|
||||
2. **Maintain Relationships**: Preserve proportional relationships between related tokens
|
||||
3. **Test Thoroughly**: Validate changes across components and use cases
|
||||
4. **Document Changes**: Track modifications and rationale for team alignment
|
||||
5. **Iterate**: Refine based on user feedback and testing results
|
||||
|
||||
---
|
||||
|
||||
## Progressive Loading
|
||||
|
||||
### Level 0: Quick Start (~2K tokens)
|
||||
### Level 0: Design Tokens (~5K tokens)
|
||||
|
||||
Essential overview and package information.
|
||||
Essential design token system for consistent styling.
|
||||
|
||||
**Files**:
|
||||
- [README](../../../.workflow/reference_style/{package_name}/README.md) - Package overview and usage
|
||||
- [Metadata](../../../.workflow/reference_style/{package_name}/metadata.json) - Source and package info
|
||||
- [Design Tokens](../../../.workflow/reference_style/{package_name}/design-tokens.json) - Colors, typography, spacing, shadows, borders
|
||||
|
||||
**Use when**: Quick reference, understanding package structure
|
||||
**Use when**: Quick token reference, applying consistent styles, color/typography queries
|
||||
|
||||
---
|
||||
|
||||
### Level 1: Design Tokens (~8K tokens)
|
||||
### Level 1: Universal Layout Templates (~12K tokens)
|
||||
|
||||
Complete design token system with style guidelines.
|
||||
**Project-independent** component layout patterns for reusable UI elements.
|
||||
|
||||
**Files**:
|
||||
- [Design Tokens](../../../.workflow/reference_style/{package_name}/design-tokens.json) - Colors, typography, spacing, shadows
|
||||
- [Style Guide](../../../.workflow/reference_style/{package_name}/style-guide.md) - Design philosophy and usage guidelines
|
||||
- Level 0 files
|
||||
- [Layout Templates](../../../.workflow/reference_style/{package_name}/layout-templates.json) - Component structures with HTML/CSS patterns
|
||||
|
||||
**Use when**: Implementing UI, applying design tokens, style consistency
|
||||
**⚠️ Reference Strategy**:
|
||||
- **Only reference components with `component_type: "universal"`** - these are reusable, project-independent patterns
|
||||
- **Ignore components with `component_type: "specialized"`** - these are project-specific implementations
|
||||
- Universal components include: buttons, inputs, forms, cards, navigation, modals, etc.
|
||||
- Use universal patterns as **reference templates** to adapt for your specific project needs
|
||||
|
||||
**Use when**: Building components, understanding component architecture, implementing layouts
|
||||
|
||||
---
|
||||
|
||||
### Level 2: Components & Patterns (~15K tokens)
|
||||
### Level 2: Complete System (~20K tokens)
|
||||
|
||||
Full component catalog with patterns, variants, and states.
|
||||
Full design system with animations and interactive preview.
|
||||
|
||||
**Files**:
|
||||
- Level 1 files
|
||||
- [Component Patterns](../../../.workflow/reference_style/{package_name}/component-patterns.json) - Component catalog with DOM structures and CSS classes
|
||||
- All Level 1 files
|
||||
- [Animation Tokens](../../../.workflow/reference_style/{package_name}/animation-tokens.json) - Animation durations, easing, transitions _(if available)_
|
||||
|
||||
**Use when**: Building components, implementing interactions, animation development
|
||||
|
||||
---
|
||||
|
||||
### Level 3: Complete Reference (~25K tokens)
|
||||
|
||||
Everything including interactive preview reference and full documentation.
|
||||
|
||||
**Files**:
|
||||
- All Level 2 files
|
||||
- [Preview HTML](../../../.workflow/reference_style/{package_name}/preview.html) - Interactive component showcase (reference only)
|
||||
- [Preview HTML](../../../.workflow/reference_style/{package_name}/preview.html) - Interactive showcase (reference only)
|
||||
- [Preview CSS](../../../.workflow/reference_style/{package_name}/preview.css) - Showcase styling (reference only)
|
||||
|
||||
**Use when**: Comprehensive analysis, complete design system understanding, implementation validation
|
||||
**Use when**: Comprehensive analysis, animation development, complete design system understanding
|
||||
|
||||
---
|
||||
|
||||
@@ -317,62 +522,62 @@ python -m http.server 8080
|
||||
|
||||
### Loading Levels
|
||||
|
||||
**Level 0** (2K): Quick reference when you need basic package info
|
||||
**Level 0** (5K): Design tokens only
|
||||
```
|
||||
Load Level 0 for package overview
|
||||
Load Level 0 for design token reference
|
||||
```
|
||||
|
||||
**Level 1** (8K): Design token implementation
|
||||
**Level 1** (12K): Tokens + layout templates
|
||||
```
|
||||
Load Level 1 for design tokens and style guide
|
||||
Load Level 1 for layout templates and design tokens
|
||||
```
|
||||
|
||||
**Level 2** (15K): Component development
|
||||
**Level 2** (20K): Complete system with animations and preview
|
||||
```
|
||||
Load Level 2 for component patterns and animations
|
||||
```
|
||||
|
||||
**Level 3** (25K): Comprehensive understanding
|
||||
```
|
||||
Load Level 3 for complete design system reference
|
||||
Load Level 2 for complete design system with preview reference
|
||||
```
|
||||
|
||||
### Common Use Cases
|
||||
|
||||
**Implementing UI Components**:
|
||||
- Load Level 2 for component patterns
|
||||
- Reference component-patterns.json for DOM structure and CSS classes
|
||||
- Load Level 1 for universal layout templates
|
||||
- **Only reference components with `component_type: "universal"`** in layout-templates.json
|
||||
- Apply design tokens from design-tokens.json
|
||||
- Adapt patterns to your project's specific requirements
|
||||
|
||||
**Ensuring Style Consistency**:
|
||||
- Load Level 1 for design tokens
|
||||
- Use style-guide.md for design philosophy
|
||||
- Check preview.html for visual reference
|
||||
- Load Level 0 for design tokens
|
||||
- Use design-tokens.json for colors, typography, spacing
|
||||
- Check preview.html for visual reference (universal components only)
|
||||
|
||||
**Analyzing Design Patterns**:
|
||||
- Load Level 3 for complete analysis
|
||||
- Review component-patterns.json for architecture
|
||||
**Analyzing Component Patterns**:
|
||||
- Load Level 2 for complete analysis
|
||||
- Review layout-templates.json for component architecture
|
||||
- **Filter for `component_type: "universal"` to exclude project-specific implementations**
|
||||
- Check preview.html for implementation examples
|
||||
|
||||
**Animation Development**:
|
||||
- Load Level 2 for animation tokens
|
||||
- Load Level 2 for animation tokens (if available)
|
||||
- Reference animation-tokens.json for durations and easing
|
||||
- Apply consistent timing and transitions
|
||||
|
||||
**⚠️ Critical Usage Rule**:
|
||||
This is a **project-independent style reference system**. When working with layout-templates.json:
|
||||
- **USE**: Components marked `component_type: "universal"` as reusable reference patterns
|
||||
- **IGNORE**: Components marked `component_type: "specialized"` (project-specific implementations)
|
||||
- **ADAPT**: All patterns should be customized for your specific project needs
|
||||
|
||||
---
|
||||
|
||||
## Package Structure
|
||||
|
||||
```
|
||||
.workflow/reference_style/{package_name}/
|
||||
├── README.md # Package overview
|
||||
├── metadata.json # Package metadata
|
||||
├── design-tokens.json # Design token system
|
||||
├── style-guide.md # Style guide documentation
|
||||
├── component-patterns.json # Component catalog
|
||||
├── animation-tokens.json # Animation tokens (optional)
|
||||
├── preview.html # Interactive showcase
|
||||
└── preview.css # Showcase styling
|
||||
├── layout-templates.json # Layout templates from codebase
|
||||
├── design-tokens.json # Design token system
|
||||
├── animation-tokens.json # Animation tokens (optional)
|
||||
├── preview.html # Interactive showcase
|
||||
└── preview.css # Showcase styling
|
||||
```
|
||||
|
||||
---
|
||||
@@ -408,7 +613,7 @@ bash(test -f .claude/skills/style-${package_name}/SKILL.md && echo "success" ||
|
||||
```json
|
||||
[
|
||||
{"content": "Validate style reference package", "status": "completed", "activeForm": "Validating package"},
|
||||
{"content": "Read package metadata and documentation", "status": "completed", "activeForm": "Reading metadata"},
|
||||
{"content": "Read package data and extract design references", "status": "completed", "activeForm": "Reading package data"},
|
||||
{"content": "Generate SKILL.md with progressive loading", "status": "completed", "activeForm": "Generating SKILL.md"}
|
||||
]
|
||||
```
|
||||
@@ -419,38 +624,86 @@ bash(test -f .claude/skills/style-${package_name}/SKILL.md && echo "success" ||
|
||||
|
||||
## Completion Message
|
||||
|
||||
Display extracted primary design references to user:
|
||||
|
||||
```
|
||||
✅ SKILL memory generated successfully!
|
||||
|
||||
Package: {package_name}
|
||||
SKILL Location: .claude/skills/style-{package_name}/SKILL.md
|
||||
|
||||
Package Details:
|
||||
- Components: {component_count}
|
||||
📦 Package Details:
|
||||
- Layout Templates: {component_count} total
|
||||
- Universal (reusable): {universal_count}
|
||||
- Specialized (project-specific): {specialized_count}
|
||||
- Universal Component Types: {show first 5 UNIVERSAL_COMPONENTS, then "+ X more"}
|
||||
- Files: {file_count}
|
||||
- Version: {version}
|
||||
- Animation Tokens: {has_animations ? "✓ Available" : "Not available"}
|
||||
|
||||
Progressive Loading Levels:
|
||||
- Level 0: Quick Start (~2K tokens)
|
||||
- Level 1: Design Tokens (~8K tokens)
|
||||
- Level 2: Components & Patterns (~15K tokens)
|
||||
- Level 3: Complete Reference (~25K tokens)
|
||||
🎨 Primary Design References Extracted:
|
||||
{IF PRIMARY_COLORS exists:
|
||||
Colors:
|
||||
{show first 3 PRIMARY_COLORS with key: value}
|
||||
{if more than 3: + X more colors}
|
||||
}
|
||||
|
||||
Usage:
|
||||
{IF TYPOGRAPHY_FONTS exists:
|
||||
Typography:
|
||||
{show all TYPOGRAPHY_FONTS}
|
||||
}
|
||||
|
||||
{IF SPACING_SCALE exists:
|
||||
Spacing Scale:
|
||||
{show first 3 SPACING_SCALE items}
|
||||
{if more than 3: + X more spacing tokens}
|
||||
}
|
||||
|
||||
{IF BORDER_RADIUS exists:
|
||||
Border Radius:
|
||||
{show all BORDER_RADIUS}
|
||||
}
|
||||
|
||||
{IF HAS_ANIMATIONS:
|
||||
Animation:
|
||||
Durations: {count ANIMATION_DURATIONS} tokens
|
||||
Easing: {count EASING_FUNCTIONS} functions
|
||||
}
|
||||
|
||||
⚡ Progressive Loading Levels:
|
||||
- Level 0: Design Tokens (~5K tokens)
|
||||
- Level 1: Tokens + Layout Templates (~12K tokens)
|
||||
- Level 2: Complete System (~20K tokens)
|
||||
|
||||
💡 Usage:
|
||||
Load design system context when working with:
|
||||
- UI component implementation
|
||||
- Layout pattern analysis
|
||||
- Design token application
|
||||
- Style consistency validation
|
||||
- Design pattern analysis
|
||||
|
||||
Preview:
|
||||
⚠️ IMPORTANT - Project Independence:
|
||||
This is a **project-independent style reference system**:
|
||||
- Only use universal components (component_type: "universal") as reference patterns
|
||||
- Ignore specialized components (component_type: "specialized") - they are project-specific
|
||||
- The extracted design references are REFERENCE VALUES, not fixed constraints
|
||||
- Dynamically adjust colors, spacing, typography, and other tokens based on:
|
||||
- Brand requirements and accessibility needs
|
||||
- Platform-specific conventions and optimizations
|
||||
- Context (light/dark mode, responsive breakpoints)
|
||||
- User feedback and testing results
|
||||
|
||||
See SKILL.md for detailed adjustment guidelines and component filtering instructions.
|
||||
|
||||
🎯 Preview:
|
||||
Open interactive showcase:
|
||||
file://{absolute_path}/.workflow/reference_style/{package_name}/preview.html
|
||||
|
||||
Next Steps:
|
||||
1. Load appropriate level based on your task
|
||||
2. Reference component-patterns.json for implementation
|
||||
3. Use design-tokens.json for consistent styling
|
||||
📋 Next Steps:
|
||||
1. Load appropriate level based on your task context
|
||||
2. Review Primary Design References section for key design tokens
|
||||
3. Apply design tokens with dynamic adjustments as needed
|
||||
4. Reference layout-templates.json for component structures
|
||||
5. Use Design Adaptation Strategies when modifying tokens
|
||||
```
|
||||
|
||||
---
|
||||
@@ -463,8 +716,8 @@ Next Steps:
|
||||
|-------|-------|------------|
|
||||
| Package not found | Invalid package name or package doesn't exist | Run codify-style first to create package |
|
||||
| SKILL already exists | SKILL.md already generated | Use --regenerate to force regeneration |
|
||||
| Missing metadata.json | Incomplete package | Verify package integrity, re-run codify-style |
|
||||
| Invalid metadata format | Corrupted metadata.json | Regenerate package with codify-style |
|
||||
| Missing layout-templates.json | Incomplete package | Verify package integrity, re-run codify-style |
|
||||
| Invalid JSON format | Corrupted package files | Regenerate package with codify-style |
|
||||
|
||||
---
|
||||
|
||||
@@ -474,61 +727,144 @@ Next Steps:
|
||||
|
||||
1. **Check Before Generate**: Verify package exists before attempting SKILL generation
|
||||
2. **Respect Existing SKILL**: Don't overwrite unless --regenerate flag provided
|
||||
3. **Progressive Loading**: Always include all 4 levels (0-3) with clear token estimates
|
||||
4. **Intelligent Description**: Extract component count and key features from metadata
|
||||
3. **Extract Primary References**: Always extract and display key design values (colors, typography, spacing, border radius, shadows, animations)
|
||||
4. **Include Adjustment Guidance**: Provide clear guidelines on when and how to dynamically adjust design tokens
|
||||
5. **Progressive Loading**: Always include all 3 levels (0-2) with clear token estimates
|
||||
6. **Intelligent Description**: Extract component count and key features from metadata
|
||||
|
||||
### SKILL Description Format
|
||||
|
||||
**Template**:
|
||||
```
|
||||
{package_name} design system with {component_count} components and interactive preview (located at .workflow/reference_style/{package_name}). Load when working with UI components, design tokens, style guidelines, analyzing design patterns, or implementing visual consistency.
|
||||
{package_name} project-independent design system with {universal_count} universal layout templates and interactive preview (located at .workflow/reference_style/{package_name}). Load when working with reusable UI components, design tokens, layout patterns, or implementing visual consistency. Excludes {specialized_count} project-specific components.
|
||||
```
|
||||
|
||||
**Required Elements**:
|
||||
- Package name
|
||||
- Component count
|
||||
- Universal layout template count (emphasize reusability)
|
||||
- Project independence statement
|
||||
- Specialized component exclusion notice
|
||||
- Location (full path)
|
||||
- Trigger keywords (UI components, design tokens, style guidelines, design patterns)
|
||||
- Trigger keywords (reusable UI components, design tokens, layout patterns, visual consistency)
|
||||
- Action verbs (working with, analyzing, implementing)
|
||||
|
||||
### Primary Design References Extraction
|
||||
|
||||
**Required Data Extraction** (from design-tokens.json):
|
||||
- Colors: Primary, secondary, accent colors (top 3-5)
|
||||
- Typography: Font families for headings and body text
|
||||
- Spacing Scale: Base spacing values (xs, sm, md, lg, xl)
|
||||
- Border Radius: All radius tokens
|
||||
- Shadows: Shadow definitions (top 3 elevation levels)
|
||||
|
||||
**Component Classification Extraction** (from layout-templates.json):
|
||||
- Universal Count: Number of components with `component_type: "universal"`
|
||||
- Specialized Count: Number of components with `component_type: "specialized"`
|
||||
- Universal Component Names: List of universal component names (first 10)
|
||||
|
||||
**Optional Data Extraction** (from animation-tokens.json if available):
|
||||
- Animation Durations: All duration tokens
|
||||
- Easing Functions: Top 3 easing functions
|
||||
|
||||
**Extraction Format**:
|
||||
Use `jq` to extract tokens from JSON files. Each token should include key and value.
|
||||
For component classification, filter by `component_type` field.
|
||||
|
||||
### Dynamic Adjustment Guidelines
|
||||
|
||||
**Include in SKILL.md**:
|
||||
1. **Usage Guidelines per Category**: Specific guidance for each token category
|
||||
2. **Adjustment Strategies**: When to adjust design references
|
||||
3. **Practical Examples**: Context-specific adaptation scenarios
|
||||
4. **Best Practices**: How to maintain design system coherence while adjusting
|
||||
|
||||
### Progressive Loading Structure
|
||||
|
||||
**Level 0** (~2K tokens):
|
||||
- README.md
|
||||
- metadata.json
|
||||
|
||||
**Level 1** (~8K tokens):
|
||||
- Level 0 files
|
||||
**Level 0** (~5K tokens):
|
||||
- design-tokens.json
|
||||
- style-guide.md
|
||||
|
||||
**Level 2** (~15K tokens):
|
||||
**Level 1** (~12K tokens):
|
||||
- Level 0 files
|
||||
- layout-templates.json
|
||||
|
||||
**Level 2** (~20K tokens):
|
||||
- Level 1 files
|
||||
- component-patterns.json
|
||||
- animation-tokens.json (if exists)
|
||||
|
||||
**Level 3** (~25K tokens):
|
||||
- All files including preview.html/css
|
||||
- preview.html
|
||||
- preview.css
|
||||
|
||||
---
|
||||
|
||||
## Benefits
|
||||
|
||||
- **Project Independence**: Clear separation between universal (reusable) and specialized (project-specific) components
|
||||
- **Component Filtering**: Automatic classification helps identify which patterns are truly reusable
|
||||
- **Fast Context Loading**: Progressive levels for efficient token usage
|
||||
- **Primary Design References**: Extracted key design values (colors, typography, spacing, etc.) displayed prominently
|
||||
- **Dynamic Adjustment Guidance**: Clear instructions on when and how to adjust design tokens
|
||||
- **Intelligent Triggering**: Keywords optimize SKILL activation
|
||||
- **Complete Reference**: All package files accessible through SKILL
|
||||
- **Easy Regeneration**: Simple --regenerate flag for updates
|
||||
- **Clear Structure**: Organized levels by use case
|
||||
- **Clear Structure**: Organized levels by use case with component type filtering
|
||||
- **Practical Usage Guidelines**: Context-specific adjustment strategies and component selection criteria
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
style-skill-memory
|
||||
├─ Phase 1: Validate (check package exists, check SKILL exists)
|
||||
├─ Phase 2: Read Metadata (extract metadata.json, README.md, count components)
|
||||
└─ Phase 3: Generate SKILL.md (write SKILL with progressive loading)
|
||||
├─ Phase 1: Validate
|
||||
│ ├─ Parse package name from argument or auto-detect
|
||||
│ ├─ Check package exists in .workflow/reference_style/
|
||||
│ └─ Check if SKILL already exists (skip if exists and no --regenerate)
|
||||
│
|
||||
├─ Phase 2: Read Package Data & Extract Primary References
|
||||
│ ├─ Count components from layout-templates.json
|
||||
│ ├─ Extract component types list
|
||||
│ ├─ Extract primary colors from design-tokens.json (top 3-5)
|
||||
│ ├─ Extract typography (font families)
|
||||
│ ├─ Extract spacing scale (base values)
|
||||
│ ├─ Extract border radius tokens
|
||||
│ ├─ Extract shadow definitions (top 3)
|
||||
│ ├─ Extract animation tokens (if available)
|
||||
│ └─ Count total files in package
|
||||
│
|
||||
└─ Phase 3: Generate SKILL.md
|
||||
├─ Create SKILL directory
|
||||
├─ Generate intelligent description with keywords
|
||||
├─ Write SKILL.md with complete structure:
|
||||
│ ├─ Package Overview
|
||||
│ ├─ Primary Design References
|
||||
│ │ ├─ Colors with usage guidelines
|
||||
│ │ ├─ Typography with usage guidelines
|
||||
│ │ ├─ Spacing with usage guidelines
|
||||
│ │ ├─ Border Radius with usage guidelines
|
||||
│ │ ├─ Shadows with usage guidelines
|
||||
│ │ └─ Animation & Timing (if available)
|
||||
│ ├─ Design Adaptation Strategies
|
||||
│ │ ├─ When to adjust design references
|
||||
│ │ └─ How to apply adjustments
|
||||
│ ├─ Progressive Loading (3 levels)
|
||||
│ ├─ Interactive Preview
|
||||
│ ├─ Usage Guidelines
|
||||
│ ├─ Package Structure
|
||||
│ ├─ Regeneration
|
||||
│ └─ Related Commands
|
||||
├─ Verify SKILL.md created successfully
|
||||
└─ Display completion message with extracted design references
|
||||
|
||||
No external commands called
|
||||
Direct file reading and writing
|
||||
Smart description generation from metadata
|
||||
Data Flow:
|
||||
design-tokens.json → jq extraction → PRIMARY_COLORS, TYPOGRAPHY_FONTS,
|
||||
SPACING_SCALE, BORDER_RADIUS, SHADOWS
|
||||
animation-tokens.json → jq extraction → ANIMATION_DURATIONS, EASING_FUNCTIONS
|
||||
layout-templates.json → jq extraction → COMPONENT_COUNT, UNIVERSAL_COUNT,
|
||||
SPECIALIZED_COUNT, UNIVERSAL_COMPONENTS
|
||||
→ component_type filtering → Universal vs Specialized classification
|
||||
|
||||
Extracted data → SKILL.md generation → Primary Design References section
|
||||
→ Component Classification section
|
||||
→ Dynamic Adjustment Guidelines
|
||||
→ Project Independence warnings
|
||||
→ Completion message display
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user