diff --git a/.claude/commands/memory/tech-research.md b/.claude/commands/memory/tech-research.md new file mode 100644 index 00000000..46149286 --- /dev/null +++ b/.claude/commands/memory/tech-research.md @@ -0,0 +1,1162 @@ +--- +name: tech-research +description: Generate tech stack SKILL packages using Exa research via agent delegation +argument-hint: "[session-id | tech-stack-name] [--regenerate] [--tool ]" +allowed-tools: SlashCommand(*), TodoWrite(*), Bash(*), Read(*), Write(*), Task(*) +--- + +# Tech Stack Research SKILL Generator + +## Orchestrator Role + +**Pure Orchestrator with Agent Delegation**: Coordinates tech stack research workflow, delegates Exa research to agents via Task tool. + +**Auto-Continue Workflow**: Runs fully autonomously once triggered. Each phase completes and automatically triggers the next phase. + +**Execution Paths**: +- **Full Path**: All 4 phases (no existing SKILL OR `--regenerate` specified) +- **Skip Path**: Phase 1 → Phase 4 (existing SKILL found AND no `--regenerate` flag) +- **Phase 4 Always Executes**: SKILL index is always generated or updated + +## Core Rules + +1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 execution +2. **Agent Delegation**: Phase 2 uses Task tool to delegate Exa research to agent +3. **Parse Agent Output**: Extract research results from agent's return message +4. **Auto-Continue**: After completing each phase, update TodoWrite and immediately execute next phase +5. **Track Progress**: Update TodoWrite after EVERY phase completion before starting next phase +6. **Direct Generation**: Phase 4 directly generates modular SKILL files using Write tool +7. **No Manual Steps**: User should never be prompted for decisions between phases + +--- + +## 4-Phase Execution + +### Phase 1: Context Extraction & Tech Stack Detection + +**Goal**: Parse input, detect mode, extract tech stack, check existing SKILL + +**Step 1: Detect Input Mode** + +```bash +# Get input parameter (first argument after command) +input="$1" + +# Detect mode +if [[ "$input" == WFS-* ]]; then + MODE="session" + session_id="$input" +else + MODE="direct" + tech_stack_input="$input" +fi +``` + +**Step 2A: Session Mode - Extract Tech Stack** + +```bash +# Read session metadata +Read(.workflow/${session_id}/workflow-session.json) + +# Read context package for tech stack info +Read(.workflow/${session_id}/.process/context-package.json) + +# Extract tech_stack from context-package +# Example structure: +# { +# "project_context": { +# "tech_stack": { +# "language": "TypeScript", +# "frameworks": ["React", "Next.js"], +# "libraries": ["axios", "zustand"] +# } +# } +# } + +# Build tech stack name from components +# Format: "{language}-{framework1}-{framework2}" +# Example: "typescript-react-nextjs" +``` + +**Step 2B: Direct Mode - Parse Tech Stack** + +```bash +# User provides tech stack name directly +tech_stack_name="$tech_stack_input" +# Example: "typescript", "python", "typescript-react-nextjs" +``` + +**Step 3: Decompose Composite Stack** + +```bash +# Split by hyphen delimiter to detect components +IFS='-' read -ra COMPONENTS <<< "$tech_stack_name" + +# COMPONENTS array examples: +# "typescript" → ["typescript"] +# "typescript-react-nextjs" → ["typescript", "react", "nextjs"] + +# Identify main tech (first component) and additional components +main_tech="${COMPONENTS[0]}" +additional_components=("${COMPONENTS[@]:1}") # Rest of array + +# Determine if composite +if [ ${#additional_components[@]} -gt 0 ]; then + is_composite=true +else + is_composite=false +fi +``` + +**Step 4: Check Existing SKILL** + +```bash +# Normalize tech stack name (lowercase, replace spaces with hyphens) +normalized_name=$(echo "$tech_stack_name" | tr '[:upper:]' '[:lower:]' | tr ' ' '-') + +# Check if SKILL already exists +bash(test -d ".claude/skills/${normalized_name}" && echo "exists" || echo "not_exists") + +# Count existing files +bash(find ".claude/skills/${normalized_name}" -name "*.md" 2>/dev/null | wc -l || echo 0) +``` + +**Step 5: Determine Execution Path** + +**Decision Logic**: +```javascript +if (existing_files > 0 && !regenerate_flag) { + // SKILL exists and no regenerate flag + SKIP_GENERATION = true + message = "Tech stack SKILL already exists, skipping Phase 2 and Phase 3. Use --regenerate to force regeneration." +} else if (regenerate_flag) { + // Force regeneration: delete existing SKILL + bash(rm -rf ".claude/skills/${normalized_name}" 2>/dev/null || true) + SKIP_GENERATION = false + message = "Regenerating tech stack SKILL from scratch." +} else { + // No existing SKILL + SKIP_GENERATION = false + message = "No existing SKILL found, generating new tech stack documentation." +} +``` + +**Summary Variables**: +- `MODE`: `session` or `direct` +- `SESSION_ID`: Session ID (if session mode) +- `TECH_STACK_NAME`: Normalized name (e.g., "typescript-react-nextjs") +- `MAIN_TECH`: Primary technology (e.g., "typescript") +- `COMPONENTS`: Array of all components (e.g., ["typescript", "react", "nextjs"]) +- `ADDITIONAL_COMPONENTS`: Array of additional components (e.g., ["react", "nextjs"]) +- `IS_COMPOSITE`: Boolean - whether composite stack +- `EXISTING_FILES`: Count of existing SKILL files +- `SKIP_GENERATION`: Boolean - whether to skip Phase 2 & 3 +- `TOOL`: `gemini` or `qwen` (default: gemini) +- `REGENERATE`: Boolean - force regeneration flag + +**Completion & TodoWrite**: +- If `SKIP_GENERATION = true`: Mark phase 1 completed, phase 2&3 completed (skipped), phase 4 in_progress +- If `SKIP_GENERATION = false`: Mark phase 1 completed, phase 2 in_progress + +**Next Action**: +- If skipping: Display skip message → Jump to Phase 4 +- If not skipping: Display preparation results → Continue to Phase 2 + +--- + +### Phase 2: Agent-Delegated Exa Research + +**Skip Condition**: This phase is **skipped if SKIP_GENERATION = true** (SKILL already exists without --regenerate flag) + +**Goal**: Delegate Exa research to agent for comprehensive tech stack knowledge gathering + +**Agent Task Specification**: + +``` +Task( + subagent_type: "general-purpose", + description: "Exa research for {tech_stack_name}", + prompt: " +Execute comprehensive Exa research for the tech stack: {TECH_STACK_NAME} + +**Tech Stack Components**: +- Main Technology: {MAIN_TECH} +- Additional Components: {ADDITIONAL_COMPONENTS} (if composite) + +**Research Tasks**: + +1. **Base Tech Stack Research** (3 parallel Exa queries): + + Query 1 - Core Principles & Best Practices: + mcp__exa__get_code_context_exa({ + query: '{MAIN_TECH} core principles best practices design patterns 2025', + tokensNum: 8000 + }) + + Query 2 - Implementation Patterns & Architecture: + mcp__exa__get_code_context_exa({ + query: '{MAIN_TECH} common patterns architecture examples implementation guide', + tokensNum: 7000 + }) + + Query 3 - Configuration & Tooling: + mcp__exa__web_search_exa({ + query: '{MAIN_TECH} configuration setup tooling guide 2025', + numResults: 5 + }) + +2. **Composite Stack Research** (if IS_COMPOSITE = true): + + For each component in ADDITIONAL_COMPONENTS: + mcp__exa__get_code_context_exa({ + query: '{MAIN_TECH} {component} integration patterns best practices', + tokensNum: 5000 + }) + +3. **Testing & Quality Research**: + + mcp__exa__get_code_context_exa({ + query: '{MAIN_TECH} testing strategies unit testing integration testing', + tokensNum: 5000 + }) + +**Expected Output Structure**: + +Return a structured JSON object with research results: + +```json +{ + \"tech_stack_name\": \"{TECH_STACK_NAME}\", + \"main_tech\": \"{MAIN_TECH}\", + \"is_composite\": {IS_COMPOSITE}, + \"components\": [list of components], + + \"research_results\": { + \"core_principles\": { + \"content\": \"... extracted content ...\", + \"sources\": [\"url1\", \"url2\"], + \"token_count\": 8000 + }, + \"patterns\": { + \"content\": \"... patterns and architectures ...\", + \"sources\": [\"url3\", \"url4\"], + \"token_count\": 7000 + }, + \"configuration\": { + \"content\": \"... config and tooling ...\", + \"sources\": [\"url5\", \"url6\"], + \"token_count\": 5000 + }, + \"testing\": { + \"content\": \"... testing strategies ...\", + \"sources\": [\"url7\"], + \"token_count\": 5000 + }, + \"framework_integration\": { + \"{component1}\": { + \"content\": \"... integration patterns ...\", + \"sources\": [\"url8\"], + \"token_count\": 5000 + }, + \"{component2}\": { ... } + } + }, + + \"summary\": { + \"total_queries\": number, + \"total_sources\": number, + \"total_tokens\": number + } +} +``` + +**IMPORTANT**: +- Execute ALL Exa queries in parallel where possible +- Accumulate results in memory during research +- Return structured JSON at the end (not intermediate results) +- If Exa query fails, retry once or note failure in results +- DO NOT write any files - only return research data + " +) +``` + +**Parse Agent Output**: + +After agent completes, extract the JSON structure from agent's final message: + +```javascript +// Agent returns message with JSON structure +const agentOutput = parseAgentResponse(agent_return_message) + +// Extract key data +const researchResults = { + tech_stack_name: agentOutput.tech_stack_name, + main_tech: agentOutput.main_tech, + is_composite: agentOutput.is_composite, + components: agentOutput.components, + + // Research content sections + core_principles: agentOutput.research_results.core_principles, + patterns: agentOutput.research_results.patterns, + configuration: agentOutput.research_results.configuration, + testing: agentOutput.research_results.testing, + framework_integration: agentOutput.research_results.framework_integration, + + // Metadata + summary: agentOutput.summary +} + +// Store in conversation memory for Phase 3 +``` + +**Completion Criteria**: +- Agent task executed successfully +- Research results JSON extracted and parsed +- All required sections present (core_principles, patterns, configuration, testing) +- Framework integration data available (if composite) +- Summary metadata recorded + +**TodoWrite**: Mark phase 2 completed, phase 3 in_progress + +**Next Action**: Display research summary (queries executed, sources consulted) → Auto-continue to Phase 3 + +--- + +### Phase 3: Content Synthesis & Modular Structuring + +**Skip Condition**: This phase is **skipped if SKIP_GENERATION = true** (SKILL already exists without --regenerate flag) + +**Goal**: Synthesize Exa research results into structured modular content + +**Option A: Orchestrator Synthesis (Recommended for Speed)** + +Directly extract and structure content from Phase 2 agent output: + +**Step 1: Extract Core Sections** + +```javascript +// Use research results from Phase 2 (already in memory) + +const moduleSections = { + principles: extractPrinciplesContent(researchResults.core_principles), + patterns: extractPatternsContent(researchResults.patterns), + practices: extractPracticesContent(researchResults.core_principles, researchResults.patterns), + testing: extractTestingContent(researchResults.testing), + config: extractConfigContent(researchResults.configuration), + frameworks: extractFrameworksContent(researchResults.framework_integration) // Only if composite +} +``` + +**Step 2: Structure Content for Each Module** + +**principles.md Structure**: +```markdown +--- +module: principles +tech_stack: {TECH_STACK_NAME} +--- +# {TechStack} Core Principles + +## Overview +{Brief introduction from research} + +## Fundamental Concepts +{Extracted from core_principles.content} + +### Concept 1: {Name} +{Description} + +```{language} +// Code example from Exa research +``` + +### Concept 2: {Name} +{Description} + +## Design Philosophy +{Extracted philosophies} + +## References +{List sources from research_results.core_principles.sources} +``` + +**patterns.md Structure**: +```markdown +--- +module: patterns +tech_stack: {TECH_STACK_NAME} +--- +# {TechStack} Common Patterns + +## Implementation Patterns + +### Pattern 1: {Pattern Name} +**Use Case**: {When to use} + +```{language} +// Code example from Exa research +``` + +**Key Points**: +- {Point 1} +- {Point 2} + +### Pattern 2: {Pattern Name} +... + +## Architectural Patterns +{Extracted from patterns.content} + +## References +{List sources} +``` + +**practices.md Structure**: +```markdown +--- +module: practices +tech_stack: {TECH_STACK_NAME} +--- +# {TechStack} Best Practices + +## Do's and Don'ts + +### ✅ Best Practices +- DO: {Practice 1} +- DO: {Practice 2} + +### ❌ Anti-Patterns +- DON'T: {Anti-pattern 1} +- DON'T: {Anti-pattern 2} + +## Common Pitfalls +{Extracted warnings} + +### Pitfall 1: {Name} +**Problem**: {Description} +**Solution**: {How to avoid} + +## Code Quality Guidelines +{Extracted guidelines} + +## References +{List sources} +``` + +**testing.md Structure**: +```markdown +--- +module: testing +tech_stack: {TECH_STACK_NAME} +--- +# {TechStack} Testing Strategies + +## Testing Approaches + +### Unit Testing +{Extracted strategies} + +```{language} +// Unit test example from Exa +``` + +### Integration Testing +{Extracted strategies} + +### End-to-End Testing +{Extracted strategies} + +## Testing Frameworks +{List recommended frameworks} + +## Best Practices +{Testing best practices} + +## References +{List sources} +``` + +**config.md Structure**: +```markdown +--- +module: config +tech_stack: {TECH_STACK_NAME} +--- +# {TechStack} Configuration Guide + +## Basic Setup + +### Installation +```bash +# Installation commands from Exa research +``` + +### Project Initialization +{Setup steps} + +## Configuration Files + +### {config_file_name} +```{format} +// Configuration example from Exa +``` + +## Tooling + +### Essential Tools +- {Tool 1}: {Description} +- {Tool 2}: {Description} + +### IDE Setup +{IDE configuration recommendations} + +## References +{List sources} +``` + +**frameworks.md Structure** (Only if IS_COMPOSITE = true): +```markdown +--- +module: frameworks +tech_stack: {TECH_STACK_NAME} +components: {ADDITIONAL_COMPONENTS} +--- +# {TechStack} Framework Integration + +## Overview +Integration patterns for {MAIN_TECH} with {COMPONENTS} + +## {Component 1} Integration + +### Setup +{Integration setup from framework_integration[component1]} + +```{language} +// Integration code example +``` + +### Best Practices +{Component-specific best practices} + +## {Component 2} Integration +... + +## Common Integration Patterns +{Cross-framework patterns} + +## References +{List sources from all components} +``` + +**Step 3: Prepare Module Content Objects** + +```javascript +const moduleContents = { + "principles.md": generatePrinciplesMarkdown(moduleSections.principles), + "patterns.md": generatePatternsMarkdown(moduleSections.patterns), + "practices.md": generatePracticesMarkdown(moduleSections.practices), + "testing.md": generateTestingMarkdown(moduleSections.testing), + "config.md": generateConfigMarkdown(moduleSections.config), +} + +// Add frameworks.md only if composite +if (IS_COMPOSITE) { + moduleContents["frameworks.md"] = generateFrameworksMarkdown(moduleSections.frameworks) +} +``` + +**Option B: Agent Synthesis (More Thorough)** + +Alternatively, delegate synthesis to another agent: + +``` +Task( + subagent_type: "general-purpose", + description: "Synthesize tech stack content", + prompt: " +Synthesize the following Exa research results into 6 modular markdown files... + +{Include research results from Phase 2} + +Generate structured content for: +1. principles.md +2. patterns.md +3. practices.md +4. testing.md +5. config.md +6. frameworks.md (if composite) + +Follow the markdown structures specified in Phase 3... + " +) +``` + +**Completion Criteria**: +- All module contents prepared (5-6 modules depending on composite) +- Each module has structured markdown with code examples +- Source references included in each module +- Content ready for Phase 4 file writing + +**TodoWrite**: Mark phase 3 completed, phase 4 in_progress + +**Next Action**: Display synthesis summary (modules prepared, total size estimate) → Auto-continue to Phase 4 + +--- + +### Phase 4: Generate SKILL Package Files + +**Note**: This phase is **NEVER skipped** - it always executes to generate or update the SKILL package. + +**Step 1: Create SKILL Directory** + +```bash +bash(mkdir -p ".claude/skills/${TECH_STACK_NAME}") +``` + +**Step 2: Write Modular Files** + +Use Write tool for each module file: + +```javascript +// Write principles.md +Write({ + file_path: `.claude/skills/${TECH_STACK_NAME}/principles.md`, + content: moduleContents["principles.md"] +}) + +// Write patterns.md +Write({ + file_path: `.claude/skills/${TECH_STACK_NAME}/patterns.md`, + content: moduleContents["patterns.md"] +}) + +// Write practices.md +Write({ + file_path: `.claude/skills/${TECH_STACK_NAME}/practices.md`, + content: moduleContents["practices.md"] +}) + +// Write testing.md +Write({ + file_path: `.claude/skills/${TECH_STACK_NAME}/testing.md`, + content: moduleContents["testing.md"] +}) + +// Write config.md +Write({ + file_path: `.claude/skills/${TECH_STACK_NAME}/config.md`, + content: moduleContents["config.md"] +}) + +// Write frameworks.md (only if composite) +if (IS_COMPOSITE) { + Write({ + file_path: `.claude/skills/${TECH_STACK_NAME}/frameworks.md`, + content: moduleContents["frameworks.md"] + }) +} +``` + +**Step 3: Generate SKILL.md Index** + +```markdown +--- +name: {TECH_STACK_NAME} +description: {MAIN_TECH} development guidelines and best practices gathered from industry standards. Load when working with {TECH_STACK_NAME} projects or need {MAIN_TECH} reference. +version: 1.0.0 +generated: {timestamp} +source: exa-research +--- +# {TechStack} SKILL Package + +## Overview +Comprehensive {TECH_STACK_NAME} development guidelines based on industry best practices and Exa research. + +**Tech Stack**: {MAIN_TECH} {if composite: "+ {ADDITIONAL_COMPONENTS.join(', ')}"} + +## Modular Documentation + +### Core Understanding (~8K tokens) +- **[Principles](./principles.md)** - Core concepts, philosophies, and fundamental principles +- **[Patterns](./patterns.md)** - Implementation patterns with code examples and architectures + +### Practical Guidance (~7K tokens) +- **[Best Practices](./practices.md)** - Do's, don'ts, anti-patterns, and quality guidelines +- **[Testing](./testing.md)** - Testing strategies, frameworks, and approaches + +### Configuration & Integration (~7K tokens) +- **[Configuration](./config.md)** - Setup, tooling, and configuration guides +{if composite: "- **[Frameworks](./frameworks.md)** - Integration patterns for {ADDITIONAL_COMPONENTS.join(', ')}"} + +## Loading Recommendations + +**Quick Reference** (~10K tokens): +``` +Skill(command: "{TECH_STACK_NAME}") +Then request: principles.md + practices.md +``` + +**Implementation Focus** (~12K tokens): +``` +Load: patterns.md + config.md + testing.md +``` + +**Complete Package** (~22K tokens): +``` +Load all modules for comprehensive reference +``` + +## Usage + +Load this SKILL when: +- Starting a new {MAIN_TECH} project +- Reviewing {TECH_STACK_NAME} code +- Learning {MAIN_TECH} best practices +- Integrating {if composite: ADDITIONAL_COMPONENTS} +- Troubleshooting {MAIN_TECH} issues + +## Research Metadata + +- **Generated**: {timestamp} +- **Source**: Exa Research +- **Queries Executed**: {summary.total_queries} +- **Sources Consulted**: {summary.total_sources} +- **Total Research Tokens**: ~{summary.total_tokens} +- **Tech Stack Components**: {COMPONENTS.length} + +## Tech Stack Details + +**Primary**: {MAIN_TECH} +{if composite: +**Frameworks**: {ADDITIONAL_COMPONENTS.join(', ')} +} + +**Module Count**: {5 or 6 depending on composite} +**Estimated Total Size**: ~22K tokens +``` + +**Step 4: Write SKILL.md Index** + +```javascript +Write({ + file_path: `.claude/skills/${TECH_STACK_NAME}/SKILL.md`, + content: generatedSKILLIndexMarkdown +}) +``` + +**Step 5: Write Metadata File** + +```json +{ + "tech_stack_name": "{TECH_STACK_NAME}", + "main_tech": "{MAIN_TECH}", + "components": [array of components], + "is_composite": boolean, + "generated_at": "{ISO timestamp}", + "source": "exa-research", + "agent_delegated": true, + "research_summary": { + "total_queries": number, + "total_sources": number, + "total_tokens": number + }, + "modules": { + "principles": { "size_estimate": "~3K tokens" }, + "patterns": { "size_estimate": "~5K tokens" }, + "practices": { "size_estimate": "~4K tokens" }, + "testing": { "size_estimate": "~3K tokens" }, + "config": { "size_estimate": "~3K tokens" }, + "frameworks": { "size_estimate": "~4K tokens" } // if composite + }, + "last_updated": "{ISO timestamp}", + "version": "1.0.0" +} +``` + +```javascript +Write({ + file_path: `.claude/skills/${TECH_STACK_NAME}/metadata.json`, + content: JSON.stringify(metadataObject, null, 2) +}) +``` + +**Completion Criteria**: +- SKILL directory created +- 5-6 modular files written (depending on composite) +- SKILL.md index written with module references +- metadata.json written with research summary +- All files use proper markdown formatting + +**TodoWrite**: Mark phase 4 completed + +**Final Action**: Report completion summary to user + +**Return to User**: +``` +✅ Tech Stack SKILL Package Generation Complete + +Tech Stack: {TECH_STACK_NAME} +SKILL Location: .claude/skills/{TECH_STACK_NAME}/ + +Generated Files: +- SKILL.md (index with loading recommendations) +- principles.md (~3K tokens) +- patterns.md (~5K tokens) +- practices.md (~4K tokens) +- testing.md (~3K tokens) +- config.md (~3K tokens) +{if composite: "- frameworks.md (~4K tokens)"} +- metadata.json (research metadata) + +Exa Research Summary: +- Queries Executed: {summary.total_queries} +- Sources Consulted: {summary.total_sources} +- Research Tokens: ~{summary.total_tokens} + +Usage: +Skill(command: "{TECH_STACK_NAME}") # Load this SKILL for {TECH_STACK_NAME} development + +Loading Recommendations: +- Quick: principles.md + practices.md (~7K) +- Implementation: patterns.md + config.md (~8K) +- Complete: All modules (~22K) +``` + +--- + +## Implementation Details + +### Critical Rules + +1. **No User Prompts Between Phases**: Never ask user questions or wait for input between phases +2. **Immediate Phase Transition**: After TodoWrite update, immediately execute next phase command +3. **Agent Output Parsing**: Extract JSON structure from agent's final message in Phase 2 +4. **Status-Driven Execution**: Check TodoList status after each phase: + - If next task is "pending" → Mark it "in_progress" and execute + - If all tasks are "completed" → Report final summary +5. **Phase Completion Pattern**: + ``` + Phase N completes → Update TodoWrite (N=completed, N+1=in_progress) → Execute Phase N+1 + ``` + +### TodoWrite Patterns + +#### Initialization (Before Phase 1) + +**FIRST ACTION**: Create TodoList with all 4 phases +```javascript +TodoWrite({todos: [ + {"content": "Extract context and detect tech stack", "status": "in_progress", "activeForm": "Extracting context"}, + {"content": "Delegate Exa research to agent", "status": "pending", "activeForm": "Delegating to agent"}, + {"content": "Synthesize content into modules", "status": "pending", "activeForm": "Synthesizing content"}, + {"content": "Generate SKILL package files", "status": "pending", "activeForm": "Generating SKILL files"} +]}) +``` + +**SECOND ACTION**: Execute Phase 1 immediately + +#### Full Path (SKIP_GENERATION = false) + +**After Phase 1**: +```javascript +TodoWrite({todos: [ + {"content": "Extract context and detect tech stack", "status": "completed", "activeForm": "Extracting context"}, + {"content": "Delegate Exa research to agent", "status": "in_progress", "activeForm": "Delegating to agent"}, + {"content": "Synthesize content into modules", "status": "pending", "activeForm": "Synthesizing content"}, + {"content": "Generate SKILL package files", "status": "pending", "activeForm": "Generating SKILL files"} +]}) +// Auto-continue to Phase 2 +``` + +**After Phase 2**: +```javascript +TodoWrite({todos: [ + {"content": "Extract context and detect tech stack", "status": "completed", "activeForm": "Extracting context"}, + {"content": "Delegate Exa research to agent", "status": "completed", "activeForm": "Delegating to agent"}, + {"content": "Synthesize content into modules", "status": "in_progress", "activeForm": "Synthesizing content"}, + {"content": "Generate SKILL package files", "status": "pending", "activeForm": "Generating SKILL files"} +]}) +// Auto-continue to Phase 3 +``` + +**After Phase 3**: +```javascript +TodoWrite({todos: [ + {"content": "Extract context and detect tech stack", "status": "completed", "activeForm": "Extracting context"}, + {"content": "Delegate Exa research to agent", "status": "completed", "activeForm": "Delegating to agent"}, + {"content": "Synthesize content into modules", "status": "completed", "activeForm": "Synthesizing content"}, + {"content": "Generate SKILL package files", "status": "in_progress", "activeForm": "Generating SKILL files"} +]}) +// Auto-continue to Phase 4 +``` + +**After Phase 4**: +```javascript +TodoWrite({todos: [ + {"content": "Extract context and detect tech stack", "status": "completed", "activeForm": "Extracting context"}, + {"content": "Delegate Exa research to agent", "status": "completed", "activeForm": "Delegating to agent"}, + {"content": "Synthesize content into modules", "status": "completed", "activeForm": "Synthesizing content"}, + {"content": "Generate SKILL package files", "status": "completed", "activeForm": "Generating SKILL files"} +]}) +// Report completion summary to user +``` + +#### Skip Path (SKIP_GENERATION = true) + +**After Phase 1** (detects existing SKILL, skips Phase 2 & 3): +```javascript +TodoWrite({todos: [ + {"content": "Extract context and detect tech stack", "status": "completed", "activeForm": "Extracting context"}, + {"content": "Delegate Exa research to agent", "status": "completed", "activeForm": "Delegating to agent"}, + {"content": "Synthesize content into modules", "status": "completed", "activeForm": "Synthesizing content"}, + {"content": "Generate SKILL package files", "status": "in_progress", "activeForm": "Generating SKILL files"} +]}) +// Display skip message: "Tech stack SKILL already exists, skipping Phase 2 and Phase 3. Use --regenerate to force regeneration." +// Jump directly to Phase 4 +``` + +**After Phase 4**: +```javascript +TodoWrite({todos: [ + {"content": "Extract context and detect tech stack", "status": "completed", "activeForm": "Extracting context"}, + {"content": "Delegate Exa research to agent", "status": "completed", "activeForm": "Delegating to agent"}, + {"content": "Synthesize content into modules", "status": "completed", "activeForm": "Synthesizing content"}, + {"content": "Generate SKILL package files", "status": "completed", "activeForm": "Generating SKILL files"} +]}) +// Report completion summary to user +``` + +### Execution Flow Diagrams + +#### Full Path Flow +``` +User triggers command + ↓ +[TodoWrite] Initialize 4 phases (Phase 1 = in_progress) + ↓ +[Execute] Phase 1: Extract context, detect tech stack + ↓ +[TodoWrite] Phase 1 = completed, Phase 2 = in_progress + ↓ +[Execute] Phase 2: Task tool → Agent executes Exa research + ↓ +[Parse] Extract JSON from agent output + ↓ +[TodoWrite] Phase 2 = completed, Phase 3 = in_progress + ↓ +[Execute] Phase 3: Synthesize content into modules + ↓ +[TodoWrite] Phase 3 = completed, Phase 4 = in_progress + ↓ +[Execute] Phase 4: Write 5-6 modular files + SKILL.md + metadata.json + ↓ +[TodoWrite] Phase 4 = completed + ↓ +[Report] Display completion summary +``` + +#### Skip Path Flow +``` +User triggers command + ↓ +[TodoWrite] Initialize 4 phases (Phase 1 = in_progress) + ↓ +[Execute] Phase 1: Detect existing SKILL + ↓ +[TodoWrite] Phase 1 = completed, Phase 2&3 = completed (skipped), Phase 4 = in_progress + ↓ +[Display] Skip message: "Tech stack SKILL already exists, skipping Phase 2 and Phase 3" + ↓ +[Execute] Phase 4: Update SKILL.md index only (fast path) + ↓ +[TodoWrite] Phase 4 = completed + ↓ +[Report] Display completion summary +``` + +### Error Handling + +**Phase 1 Errors**: +- **Invalid session ID**: Report error, ask user to verify session exists +- **Missing context-package**: Warn user, fall back to direct mode (ask for tech stack name) +- **No tech stack detected**: Ask user to specify tech stack name directly + +**Phase 2 Errors (Agent Delegation)**: +- **Agent task fails**: Retry once, if fails again report error to user +- **Exa API failures**: Agent should handle internally with retries +- **Incomplete research results**: Warn user, proceed with partial data if minimum sections available + +**Phase 3 Errors**: +- **Parsing failures**: Fall back to basic content structure +- **Missing sections**: Generate placeholder content, note in metadata + +**Phase 4 Errors**: +- **Write failures**: Report which files failed, suggest manual retry +- **Directory creation fails**: Check permissions, report to user + +--- + +## Parameters + +```bash +/memory:tech-research [session-id | "tech-stack-name"] [--regenerate] [--tool ] +``` + +- **session-id | tech-stack-name**: Input source (auto-detected by WFS- prefix) + - **Session mode**: `WFS-user-auth-v2` - Extract tech stack from workflow session + - **Direct mode**: `"typescript"`, `"python"`, `"typescript-react-nextjs"` - User specifies tech stack +- **--regenerate**: Force regenerate existing SKILL (optional) + - When enabled: Deletes existing `.claude/skills/{tech_stack_name}/` before regeneration + - Ensures fresh documentation from Exa research +- **--tool**: CLI tool for additional analysis (optional, default: gemini) + - `gemini`: Use Gemini for supplemental analysis (future enhancement) + - `qwen`: Use Qwen for supplemental analysis (future enhancement) + - **Note**: Currently Phase 2 uses agent with Exa, this flag reserved for future use + +--- + +## Examples + +### Example 1: Direct Mode - Single Tech Stack + +```bash +/memory:tech-research "typescript" +``` + +**Workflow**: +1. Phase 1: Detects direct mode, parses "typescript", checks existing SKILL +2. Phase 2: Agent executes 4 Exa queries (principles, patterns, config, testing) +3. Phase 3: Synthesizes content into 5 modular files +4. Phase 4: Generates SKILL package at `.claude/skills/typescript/` + +**Generated Files**: +- `SKILL.md` (index) +- `principles.md` +- `patterns.md` +- `practices.md` +- `testing.md` +- `config.md` +- `metadata.json` + +### Example 2: Direct Mode - Composite Tech Stack + +```bash +/memory:tech-research "typescript-react-nextjs" +``` + +**Workflow**: +1. Phase 1: Detects composite stack, decomposes into ["typescript", "react", "nextjs"] +2. Phase 2: Agent executes 6 Exa queries: + - Base: principles, patterns, config, testing + - Components: react integration, nextjs integration +3. Phase 3: Synthesizes content into 6 modular files (adds frameworks.md) +4. Phase 4: Generates complete SKILL package + +**Generated Files**: +- `SKILL.md` (index with framework integration) +- `principles.md` +- `patterns.md` +- `practices.md` +- `testing.md` +- `config.md` +- `frameworks.md` (React + Next.js integration) +- `metadata.json` + +### Example 3: Session Mode - Extract from Workflow + +```bash +/memory:tech-research WFS-user-auth-20251104 +``` + +**Workflow**: +1. Phase 1: Detects session mode, reads workflow-session.json + context-package.json +2. Extracts tech stack: `{ language: "Python", frameworks: ["FastAPI", "SQLAlchemy"] }` +3. Builds tech stack name: "python-fastapi-sqlalchemy" +4. Phase 2: Agent executes Exa research for Python + FastAPI + SQLAlchemy +5. Phase 3: Synthesizes into 6 modules +6. Phase 4: Generates SKILL package at `.claude/skills/python-fastapi-sqlalchemy/` + +### Example 4: Regenerate Existing SKILL + +```bash +/memory:tech-research "react" --regenerate +``` + +**Workflow**: +1. Phase 1: Detects existing SKILL at `.claude/skills/react/`, deletes it due to --regenerate +2. Phase 2: Agent executes fresh Exa research for React (latest 2025 best practices) +3. Phase 3: Synthesizes updated content +4. Phase 4: Generates new SKILL package with latest information + +### Example 5: Skip Path - Update Index Only + +```bash +/memory:tech-research "python" +``` + +**Scenario**: SKILL already exists at `.claude/skills/python/` with 7 files + +**Workflow**: +1. Phase 1: Detects existing SKILL (7 files), sets SKIP_GENERATION = true +2. Display: "Tech stack SKILL already exists, skipping Phase 2 and Phase 3. Use --regenerate to force regeneration." +3. Phase 4: Updates SKILL.md index only (adds new metadata, updates timestamps) +4. **Result**: ~5-10x faster than full generation + +--- + +## Benefits + +- ✅ **Agent-Powered Research**: Delegates Exa queries to agent for parallel execution +- ✅ **Pure Orchestrator**: Command only coordinates workflow, doesn't execute research +- ✅ **Modular Structure**: 6 independent files for flexible loading +- ✅ **Composite Stack Support**: Auto-detects and researches multiple frameworks +- ✅ **Dual-Mode Input**: Works with session IDs or direct tech stack names +- ✅ **Intelligent Skip**: Fast SKILL updates without full regeneration +- ✅ **Always Current**: Exa research pulls latest 2025 best practices +- ✅ **Auto-Continue**: Autonomous 4-phase execution with progress tracking +- ✅ **Comprehensive**: Covers principles, patterns, practices, testing, config, integration + +## Architecture + +``` +tech-research (orchestrator) + ├─ Phase 1: Context Extraction (bash, Read, direct logic) + ├─ Phase 2: Agent Delegation (Task tool → Exa research agent) + ├─ Phase 3: Content Synthesis (parse agent output, structure modules) + └─ Phase 4: File Generation (Write tool, direct file creation, always runs) + +Agent Responsibilities (Phase 2): + ├─ Execute parallel Exa queries + ├─ Accumulate research results + ├─ Return structured JSON + └─ Handle Exa failures/retries + +Smart Skip Logic: + ├─ Existing SKILL → Skip Phase 2 & 3 (5-10x faster) + └─ --regenerate → Full path (fresh research) + +Modular SKILL Output: + ├─ SKILL.md (index, ~1K tokens) + ├─ principles.md (~3K tokens) + ├─ patterns.md (~5K tokens) + ├─ practices.md (~4K tokens) + ├─ testing.md (~3K tokens) + ├─ config.md (~3K tokens) + ├─ frameworks.md (~4K tokens, if composite) + └─ metadata.json (research metadata) + +Total: ~22K tokens per SKILL package +``` + +--- + +## Future Enhancements + +1. **Multi-Language Support**: Detect and generate SKILLs in multiple languages (English, Chinese) +2. **Version Management**: Track SKILL versions, allow version pinning +3. **Incremental Updates**: Update specific modules without full regeneration +4. **SKILL Dependencies**: Link related SKILLs (e.g., TypeScript → React → Next.js) +5. **Custom Templates**: User-defined module templates for specific patterns +6. **CLI Tool Integration**: Use --tool flag to invoke Gemini/Qwen for additional analysis +7. **Validation**: Verify generated content quality, detect incomplete sections +8. **Export Formats**: Generate PDF/HTML versions of SKILL packages diff --git a/.claude/commands/memory/workflow-skill-memory.md b/.claude/commands/memory/workflow-skill-memory.md new file mode 100644 index 00000000..4d363b8d --- /dev/null +++ b/.claude/commands/memory/workflow-skill-memory.md @@ -0,0 +1,739 @@ +--- +name: workflow-skill-memory +description: Generate SKILL package from archived workflow sessions for progressive context loading +argument-hint: "[--regenerate] [--incremental] [--filter ]" +allowed-tools: SlashCommand(*), TodoWrite(*), Bash(*), Read(*), Write(*) +--- + +# Workflow SKILL Memory Generator + +## Orchestrator Role + +**Pure Orchestrator**: Extract and aggregate workflow session history to generate SKILL package for progressive context loading. + +**Auto-Continue Workflow**: This command runs **fully autonomously** once triggered. Each phase completes and automatically triggers the next phase without user interaction. + +**Execution Paths**: +- **Full Path**: All 4 phases (no existing SKILL OR `--regenerate` specified) +- **Incremental Path**: Phase 1 → Phase 2 → Phase 4 (existing SKILL found AND `--incremental` flag) +- **Phase 4 Always Executes**: SKILL.md index is never skipped, always generated or updated + +## Core Rules + +1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 execution +2. **No Task JSON**: This command does not create task JSON files +3. **Parse Every Output**: Extract required data from each command output (session count, file paths) +4. **Auto-Continue**: After completing each phase, update TodoWrite and immediately execute next phase +5. **Track Progress**: Update TodoWrite after EVERY phase completion before starting next phase +6. **Direct Generation**: Phase 4 directly generates SKILL.md using Write tool +7. **No Manual Steps**: User should never be prompted for decisions between phases + +--- + +## 4-Phase Execution + +### Phase 1: Read Archived Sessions + +**Goal**: Read manifest.json and list all archived workflow sessions + +**Step 1.1: Check Archive Directory** +```bash +bash(test -d .workflow/.archives && echo "exists" || echo "not_exists") +``` + +**Step 1.2: Read Manifest** +```bash +bash(test -f .workflow/.archives/manifest.json && cat .workflow/.archives/manifest.json || echo "{}") +``` + +**Output**: +- `archive_exists`: `exists` or `not_exists` +- `manifest_content`: JSON content or empty object +- `session_count`: Number of archived sessions + +**Step 1.3: Parse Session List** + +Extract from manifest: +- Session IDs +- Descriptions +- Archived dates +- Tags +- Metrics (task_count, success_rate, duration_hours) + +**Step 1.4: Apply Filters (if --filter specified)** + +If user provided `--filter `: +- Filter sessions by description/tags matching topic +- Update session list to only include filtered sessions + +**Step 1.5: Determine Execution Path** + +**Decision Logic**: +```javascript +if (session_count === 0) { + // No archived sessions + ERROR = "No archived workflow sessions found" + SKIP_ALL = true +} else if (existing_SKILL && incremental_flag) { + // Incremental update: skip full aggregation + SKIP_AGGREGATION = true + message = "Incremental update mode, reusing existing aggregations." +} else if (regenerate_flag) { + // Force regeneration: delete existing SKILL + bash(rm -rf .claude/skills/workflow-progress 2>/dev/null || true) + SKIP_AGGREGATION = false + message = "Regenerating SKILL package from scratch." +} else { + // No existing SKILL or full generation + SKIP_AGGREGATION = false + message = "Generating new SKILL package." +} +``` + +**Summary Variables**: +- `SESSION_COUNT`: Total archived sessions (or filtered count) +- `SESSION_LIST`: Array of session objects [{id, description, archived_at, tags, metrics}] +- `FILTER_TOPIC`: Filter keyword (if specified) +- `INCREMENTAL`: `true` if --incremental flag +- `REGENERATE`: `true` if --regenerate flag +- `SKIP_AGGREGATION`: `true` if incremental update +- `SKIP_ALL`: `true` if no sessions found + +**Completion & TodoWrite**: +- If `SKIP_ALL = true`: Mark all phases completed (error), report error +- If `SKIP_AGGREGATION = true`: Mark phase 1 completed, phase 2&3 completed (skipped), phase 4 in_progress +- If `SKIP_AGGREGATION = false`: Mark phase 1 completed, phase 2 in_progress + +**Next Action**: +- If error: Display error message → Exit +- If skipping aggregation: Display skip message → Jump to Phase 4 +- Otherwise: Display session list → Continue to Phase 2 + +--- + +### Phase 2: Extract Session Data + +**Skip Condition**: This phase is **skipped if SKIP_AGGREGATION = true** (incremental mode with existing aggregations) + +**Goal**: Traverse archived sessions and extract key data + +**For Each Session**: + +**Step 2.1: Read Session Metadata** +```bash +bash(cat .workflow/.archives/WFS-{session_id}/workflow-session.json) +``` + +**Step 2.2: Check for Key Files** +```bash +# Context package path (reference only, don't read content) +bash(test -f .workflow/.archives/WFS-{session_id}/.process/context-package.json && echo "exists" || echo "missing") + +# IMPL_PLAN +bash(test -f .workflow/.archives/WFS-{session_id}/IMPL_PLAN.md && cat .workflow/.archives/WFS-{session_id}/IMPL_PLAN.md || echo "") + +# TODO_LIST +bash(test -f .workflow/.archives/WFS-{session_id}/TODO_LIST.md && cat .workflow/.archives/WFS-{session_id}/TODO_LIST.md || echo "") + +# Count tasks and summaries +bash(find .workflow/.archives/WFS-{session_id}/.task -name "*.json" 2>/dev/null | wc -l || echo 0) +bash(find .workflow/.archives/WFS-{session_id}/.summaries -name "*.md" 2>/dev/null | wc -l || echo 0) +``` + +**Step 2.3: Extract from Manifest Entry** + +For each session, extract from manifest.json: +- `lessons.successes` - Success patterns +- `lessons.challenges` - Challenges encountered +- `lessons.watch_patterns` - Things to watch for +- `tags` - Functional domain tags +- `metrics` - Task count, success rate, duration + +**Aggregated Data Structure**: +```javascript +{ + "sessions": [ + { + "session_id": "WFS-user-auth", + "description": "User authentication implementation", + "archived_at": "2025-11-03T12:00:00Z", + "tags": ["auth", "security", "jwt"], + "metrics": { + "task_count": 5, + "completed_tasks": 5, + "success_rate": 100, + "duration_hours": 4.5 + }, + "context_package_path": ".workflow/.archives/WFS-user-auth/.process/context-package.json", + "impl_plan_summary": "First 200 chars of IMPL_PLAN.md...", + "lessons": { + "successes": ["JWT implementation worked well", "..."], + "challenges": ["Token refresh edge cases", "..."], + "watch_patterns": ["Concurrent token validation", "..."] + } + } + ], + "aggregated_lessons": { + "successes_by_category": { + "auth": ["JWT implementation", "..."], + "testing": ["Coverage reached 90%", "..."] + }, + "challenges_by_severity": { + "high": ["Performance bottleneck in token validation", "..."], + "medium": ["Edge case handling", "..."] + }, + "watch_patterns": ["Token concurrency", "State management", "..."] + }, + "conflict_patterns": { + "architecture": [ + { + "pattern": "Multiple authentication strategies conflict", + "sessions": ["WFS-user-auth", "WFS-oauth"], + "resolution": "Unified auth interface" + } + ], + "dependencies": [ + { + "pattern": "Version mismatch in JWT libraries", + "sessions": ["WFS-user-auth"], + "resolution": "Lock to compatible version" + } + ] + } +} +``` + +**Completion Criteria**: +- All sessions traversed +- Data structure populated +- Aggregations computed (lessons by category, conflicts by type) + +**TodoWrite**: Mark phase 2 completed, phase 3 in_progress + +**Next Action**: Display extraction summary (sessions processed, lessons extracted) → Auto-continue to Phase 3 + +--- + +### Phase 3: Classify and Organize Data + +**Skip Condition**: This phase is **skipped if SKIP_AGGREGATION = true** (incremental mode) + +**Goal**: Organize extracted data by functional domains, timeline, and patterns + +**Step 3.1: Group Sessions by Tags** + +Organize sessions into functional domains: +```javascript +{ + "auth": [session_objects], + "payment": [session_objects], + "ui": [session_objects], + "testing": [session_objects], + "other": [session_objects] +} +``` + +**Step 3.2: Sort by Timeline** + +Create chronological timeline: +- Sort sessions by `archived_at` (newest first) +- Group by month/quarter for large histories + +**Step 3.3: Identify Recurring Patterns** + +**Lessons Analysis**: +- Successes that appear in multiple sessions → "Best Practices" +- Challenges that repeat → "Known Issues" +- Watch patterns with high frequency → "High Priority Warnings" + +**Conflict Analysis**: +- Group conflicts by type (architecture, dependencies, testing) +- Mark conflicts that occurred in multiple sessions +- Link resolutions to specific sessions + +**Step 3.4: Build Progressive Loading Structure** + +Organize data for 4 levels: +- **Level 0**: Top 5 recent sessions + Top 3 conflict patterns +- **Level 1**: Top 10 sessions + Lessons by category +- **Level 2**: All sessions + Full conflict analysis + IMPL_PLAN summaries +- **Level 3**: All sessions + Full IMPL_PLAN + TODO_LIST + Context package references + +**Completion Criteria**: +- Sessions grouped by domain +- Timeline structure created +- Recurring patterns identified +- Progressive loading structure built + +**TodoWrite**: Mark phase 3 completed, phase 4 in_progress + +**Next Action**: Display organization summary → Auto-continue to Phase 4 + +--- + +### Phase 4: Generate SKILL Package + +**Note**: This phase is **NEVER skipped** - it always executes to generate or update the SKILL package. + +**Step 4.1: Create SKILL Directory** +```bash +bash(mkdir -p .claude/skills/workflow-progress) +``` + +**Step 4.2: Generate sessions-timeline.md** + +Create timeline document: +```markdown +# Workflow Sessions Timeline + +## Recent Sessions (Last 5) + +### WFS-user-auth (2025-11-03) +**Description**: User authentication implementation +**Tags**: auth, security, jwt +**Metrics**: 5 tasks, 100% success, 4.5 hours +**Context Package**: [.workflow/.archives/WFS-user-auth/.process/context-package.json](.workflow/.archives/WFS-user-auth/.process/context-package.json) + +**Key Outcomes**: +- ✅ JWT implementation with refresh tokens +- ✅ Secure password hashing +- ⚠️ Watch: Token concurrency edge cases + +... + +## By Functional Domain + +### Authentication (3 sessions) +- WFS-user-auth (2025-11-03) +- WFS-oauth (2025-10-15) +- WFS-jwt-refresh (2025-09-20) + +### Payment (2 sessions) +- WFS-stripe-integration (2025-10-28) +- WFS-payment-webhooks (2025-09-10) + +... +``` + +**Step 4.3: Generate lessons-learned.md** + +Create lessons document: +```markdown +# Workflow Lessons Learned + +## Best Practices (Successes) + +### Authentication +- JWT implementation with refresh tokens works reliably +- Use bcrypt for password hashing (sessions: WFS-user-auth, WFS-oauth) + +### Testing +- TDD approach reduced bugs by 60% (sessions: WFS-user-auth, WFS-payment) +- Mocking external APIs saves development time + +... + +## Known Challenges + +### High Priority +- **Token refresh edge cases**: Concurrent requests can invalidate tokens prematurely + - Affected sessions: WFS-user-auth, WFS-jwt-refresh + - Resolution: Implement token refresh queue + +### Medium Priority +- **Performance bottlenecks**: Large payload serialization + - Affected sessions: WFS-payment-webhooks + - Resolution: Implement streaming responses + +... + +## Watch Patterns + +### Critical +1. **Token concurrency**: Always test concurrent token operations +2. **State management**: Redux state can become stale in async workflows +3. **Database migrations**: Always backup before schema changes + +... +``` + +**Step 4.4: Generate conflict-patterns.md** + +Create conflict patterns document: +```markdown +# Workflow Conflict Patterns + +## Architecture Conflicts + +### Multiple Authentication Strategies +**Pattern**: Different parts of system use incompatible auth methods +**Sessions**: WFS-user-auth, WFS-oauth +**Resolution**: Unified auth interface with strategy pattern + +**Code Impact**: +- Modified: src/auth/interface.ts, src/auth/jwt.ts, src/auth/oauth.ts +- Tests: src/auth/__tests__/ + +... + +## Dependency Conflicts + +### JWT Library Version Mismatch +**Pattern**: jsonwebtoken v8 vs v9 incompatibility +**Sessions**: WFS-user-auth +**Resolution**: Lock to jsonwebtoken@^9.0.0, update all imports + +... + +## Testing Conflicts + +### Mock Data Inconsistencies +**Pattern**: Different test suites use different user fixtures +**Sessions**: WFS-user-auth, WFS-payment +**Resolution**: Centralized test fixtures in tests/fixtures/ + +... +``` + +**Step 4.5: Generate SKILL.md** + +Create main SKILL index: +```yaml +--- +name: workflow-progress +description: Progressive workflow development history (located at {project_root}). Load this SKILL when continuing development, analyzing past implementations, or learning from workflow history, especially when no relevant context exists in memory. +version: 1.0.0 +--- +# Workflow Progress SKILL Package + +## Documentation: `../../../.workflow/.archives/` + +**Total Sessions**: {session_count} +**Functional Domains**: {domain_list} +**Date Range**: {earliest_date} - {latest_date} + +## Progressive Loading + +### Level 0: Quick Overview (~2K tokens) +- [Sessions Timeline](sessions-timeline.md#recent-sessions-last-5) - Recent 5 sessions +- [Top Conflict Patterns](conflict-patterns.md#top-patterns) - Top 3 recurring conflicts +- Quick reference for last completed work + +**Use Case**: Quick context refresh before starting new task + +### Level 1: Core History (~8K tokens) +- [Sessions Timeline](sessions-timeline.md) - Recent 10 sessions with details +- [Lessons Learned](lessons-learned.md#best-practices) - Success patterns by category +- [Conflict Patterns](conflict-patterns.md) - Known conflict types and resolutions +- Context package references (metadata only) + +**Use Case**: Understanding recent development patterns and avoiding known pitfalls + +### Level 2: Complete History (~25K tokens) +- All archived sessions with metadata +- Full lessons learned (successes, challenges, watch patterns) +- Complete conflict analysis with resolutions +- IMPL_PLAN summaries from all sessions +- Context package paths for on-demand loading + +**Use Case**: Comprehensive review before major refactoring or architecture changes + +### Level 3: Deep Dive (~40K tokens) +- Full IMPL_PLAN.md and TODO_LIST.md from all sessions +- Detailed task completion summaries +- Cross-session dependency analysis +- Direct context package file references + +**Use Case**: Investigating specific implementation details or debugging historical decisions + +--- + +## Quick Access + +### Recent Sessions +{list of 5 most recent sessions with one-line descriptions} + +### By Domain +- **Authentication**: {count} sessions +- **Payment**: {count} sessions +- **UI/UX**: {count} sessions +- **Testing**: {count} sessions +- **Other**: {count} sessions + +### Top Watch Patterns +1. {most frequent watch pattern} +2. {second most frequent} +3. {third most frequent} + +--- + +## Session Index + +### Authentication Sessions +- [WFS-user-auth](../../../.workflow/.archives/WFS-user-auth/) - JWT authentication (2025-11-03) + - Context: [context-package.json](../../../.workflow/.archives/WFS-user-auth/.process/context-package.json) + - Plan: [IMPL_PLAN.md](../../../.workflow/.archives/WFS-user-auth/IMPL_PLAN.md) + - Tags: auth, security, jwt + +... + +--- + +## Usage Examples + +### Loading Quick Context +```markdown +Load Level 0 from workflow-progress SKILL for overview of recent work +``` + +### Investigating Auth History +```markdown +Load Level 2 from workflow-progress SKILL, filter by "auth" tag +``` + +### Full Historical Analysis +```markdown +Load Level 3 from workflow-progress SKILL for complete development history +``` +``` + +**Step 4.6: Write All Files** + +Use Write tool to create: +1. `.claude/skills/workflow-progress/SKILL.md` +2. `.claude/skills/workflow-progress/sessions-timeline.md` +3. `.claude/skills/workflow-progress/lessons-learned.md` +4. `.claude/skills/workflow-progress/conflict-patterns.md` + +**Completion Criteria**: +- SKILL.md file created +- All support documents created +- Progressive loading structure verified +- File references use relative paths + +**TodoWrite**: Mark phase 4 completed + +**Final Action**: Report completion summary to user + +**Return to User**: +``` +✅ Workflow SKILL Package Generation Complete + +Sessions Processed: {session_count} +Functional Domains: {domain_count} +SKILL Location: .claude/skills/workflow-progress/SKILL.md + +Generated: +- sessions-timeline.md - {session_count} sessions organized chronologically +- lessons-learned.md - {success_count} successes, {challenge_count} challenges +- conflict-patterns.md - {conflict_count} conflict patterns documented +- SKILL.md with progressive loading (4 levels) + +Usage: +- Level 0: Quick refresh (~2K tokens) +- Level 1: Recent history (~8K tokens) +- Level 2: Complete analysis (~25K tokens) +- Level 3: Deep dive (~40K tokens) + +Trigger: Skill() will auto-load when continuing workflow development +``` + +--- + +## Implementation Details + +### Critical Rules + +1. **No User Prompts Between Phases**: Never ask user questions or wait for input between phases +2. **Immediate Phase Transition**: After TodoWrite update, immediately execute next phase command +3. **Status-Driven Execution**: Check TodoList status after each phase: + - If next task is "pending" → Mark it "in_progress" and execute + - If all tasks are "completed" → Report final summary +4. **Phase Completion Pattern**: + ``` + Phase N completes → Update TodoWrite (N=completed, N+1=in_progress) → Execute Phase N+1 + ``` + +### TodoWrite Patterns + +#### Initialization (Before Phase 1) + +**FIRST ACTION**: Create TodoList with all 4 phases +```javascript +TodoWrite({todos: [ + {"content": "Read archived sessions from manifest", "status": "in_progress", "activeForm": "Reading archived sessions"}, + {"content": "Extract session data and lessons", "status": "pending", "activeForm": "Extracting session data"}, + {"content": "Classify and organize data by domains", "status": "pending", "activeForm": "Classifying data"}, + {"content": "Generate SKILL package files", "status": "pending", "activeForm": "Generating SKILL files"} +]}) +``` + +**SECOND ACTION**: Execute Phase 1 immediately + +#### Full Path (SKIP_AGGREGATION = false) + +**After Phase 1**: +```javascript +TodoWrite({todos: [ + {"content": "Read archived sessions from manifest", "status": "completed", "activeForm": "Reading archived sessions"}, + {"content": "Extract session data and lessons", "status": "in_progress", "activeForm": "Extracting session data"}, + {"content": "Classify and organize data by domains", "status": "pending", "activeForm": "Classifying data"}, + {"content": "Generate SKILL package files", "status": "pending", "activeForm": "Generating SKILL files"} +]}) +// Auto-continue to Phase 2 +``` + +**After Phase 2**: +```javascript +TodoWrite({todos: [ + {"content": "Read archived sessions from manifest", "status": "completed", "activeForm": "Reading archived sessions"}, + {"content": "Extract session data and lessons", "status": "completed", "activeForm": "Extracting session data"}, + {"content": "Classify and organize data by domains", "status": "in_progress", "activeForm": "Classifying data"}, + {"content": "Generate SKILL package files", "status": "pending", "activeForm": "Generating SKILL files"} +]}) +// Auto-continue to Phase 3 +``` + +**After Phase 3**: +```javascript +TodoWrite({todos: [ + {"content": "Read archived sessions from manifest", "status": "completed", "activeForm": "Reading archived sessions"}, + {"content": "Extract session data and lessons", "status": "completed", "activeForm": "Extracting session data"}, + {"content": "Classify and organize data by domains", "status": "completed", "activeForm": "Classifying data"}, + {"content": "Generate SKILL package files", "status": "in_progress", "activeForm": "Generating SKILL files"} +]}) +// Auto-continue to Phase 4 +``` + +**After Phase 4**: +```javascript +TodoWrite({todos: [ + {"content": "Read archived sessions from manifest", "status": "completed", "activeForm": "Reading archived sessions"}, + {"content": "Extract session data and lessons", "status": "completed", "activeForm": "Extracting session data"}, + {"content": "Classify and organize data by domains", "status": "completed", "activeForm": "Classifying data"}, + {"content": "Generate SKILL package files", "status": "completed", "activeForm": "Generating SKILL files"} +]}) +// Report completion summary to user +``` + +#### Incremental Path (SKIP_AGGREGATION = true) + +**After Phase 1** (detects incremental mode, skips Phase 2 & 3): +```javascript +TodoWrite({todos: [ + {"content": "Read archived sessions from manifest", "status": "completed", "activeForm": "Reading archived sessions"}, + {"content": "Extract session data and lessons", "status": "completed", "activeForm": "Extracting session data"}, + {"content": "Classify and organize data by domains", "status": "completed", "activeForm": "Classifying data"}, + {"content": "Generate SKILL package files", "status": "in_progress", "activeForm": "Generating SKILL files"} +]}) +// Display skip message: "Incremental update mode, reusing existing aggregations." +// Jump directly to Phase 4 +``` + +**After Phase 4**: +```javascript +TodoWrite({todos: [ + {"content": "Read archived sessions from manifest", "status": "completed", "activeForm": "Reading archived sessions"}, + {"content": "Extract session data and lessons", "status": "completed", "activeForm": "Extracting session data"}, + {"content": "Classify and organize data by domains", "status": "completed", "activeForm": "Classifying data"}, + {"content": "Generate SKILL package files", "status": "completed", "activeForm": "Generating SKILL files"} +]}) +// Report completion summary to user +``` + +### Error Handling + +- If no archived sessions found, mark all tasks completed and report error +- If any phase fails, mark it as "in_progress" (not completed) +- Report error details to user +- Do NOT auto-continue to next phase on failure + +--- + +## Parameters + +```bash +/memory:workflow-skill-memory [--regenerate] [--incremental] [--filter ] +``` + +- **--regenerate**: Force regenerate all SKILL files from scratch + - When enabled: Deletes existing `.claude/skills/workflow-progress/` before regeneration + - Ensures fresh SKILL package from archived sessions +- **--incremental**: Incremental update mode (skip Phase 2 & 3 if existing SKILL found) + - When enabled: Reuses existing aggregations, only updates SKILL files + - Faster execution for adding new sessions +- **--filter **: Filter sessions by topic/tag + - Example: `--filter auth` only processes auth-related sessions + - Uses description and tags for matching + +--- + +## Examples + +### Example 1: Generate SKILL Package (Default) + +```bash +/memory:workflow-skill-memory +``` + +**Workflow**: +1. Phase 1: Reads manifest.json, gets all archived sessions +2. Phase 2: Extracts lessons, conflicts, and summaries from all sessions +3. Phase 3: Organizes data by domain and timeline +4. Phase 4: Generates SKILL.md at `.claude/skills/workflow-progress/SKILL.md` + +### Example 2: Regenerate SKILL Package + +```bash +/memory:workflow-skill-memory --regenerate +``` + +**Workflow**: +1. Phase 1: Deletes existing SKILL package, reads manifest +2. Phase 2-4: Full regeneration from archived sessions + +### Example 3: Incremental Update (Fast) + +```bash +/memory:workflow-skill-memory --incremental +``` + +**Workflow**: +1. Phase 1: Reads manifest, detects incremental mode +2. Display: "Incremental update mode, reusing existing aggregations." +3. Phase 4: Updates SKILL.md only (~5-10x faster) + +### Example 4: Filter by Topic + +```bash +/memory:workflow-skill-memory --filter auth +``` + +**Workflow**: +1. Phase 1: Reads manifest, filters sessions with "auth" in description/tags +2. Phase 2-4: Processes only auth-related sessions + +--- + +## Benefits + +- ✅ **Progressive Context Loading**: 4 levels (2K → 8K → 25K → 40K tokens) +- ✅ **Historical Wisdom**: Lessons learned and conflict patterns accumulated +- ✅ **Auto-Generated**: Called automatically by `/workflow:session:complete` +- ✅ **Incremental Updates**: Fast updates when adding new sessions +- ✅ **Intelligent Filtering**: Focus on specific functional domains +- ✅ **Reference-Based**: Context packages referenced by path, not duplicated +- ✅ **Lightweight**: Only aggregates lessons/conflicts, keeps original files + +## Architecture + +``` +workflow-skill-memory (orchestrator) + ├─ Phase 1: Read manifest and sessions (bash commands) + ├─ Phase 2: Extract data (bash + Read, skippable) + ├─ Phase 3: Organize data (in-memory, skippable) + └─ Phase 4: Write SKILL files (Write tool, always runs) + +No task JSON created by this command +Smart skip logic: 5-10x faster in incremental mode +``` diff --git a/.claude/commands/workflow/session/complete.md b/.claude/commands/workflow/session/complete.md index cd6994ea..bb025058 100644 --- a/.claude/commands/workflow/session/complete.md +++ b/.claude/commands/workflow/session/complete.md @@ -4,17 +4,19 @@ description: Mark the active workflow session as complete, archive it with lesso examples: - /workflow:session:complete - /workflow:session:complete --detailed + - /workflow:session:complete --skip-skill --- # Complete Workflow Session (/workflow:session:complete) ## Overview -Mark the currently active workflow session as complete, analyze it for lessons learned, move it to the archive directory, and remove the active flag marker. +Mark the currently active workflow session as complete, analyze it for lessons learned, move it to the archive directory, remove the active flag marker, and optionally update the workflow SKILL package. ## Usage ```bash -/workflow:session:complete # Complete current active session -/workflow:session:complete --detailed # Show detailed completion summary +/workflow:session:complete # Complete current active session +/workflow:session:complete --detailed # Show detailed completion summary +/workflow:session:complete --skip-skill # Complete without updating SKILL package ``` ## Implementation Flow @@ -94,9 +96,43 @@ Complete workflow session archival. Session already moved to archive location. - Agent returns JSON result confirming successful archival - Display completion summary to user based on agent response +### Phase 3: Auto-Generate SKILL Package (Optional) + +**Purpose**: Automatically update workflow progress SKILL package with newly archived session. + +**Note**: This phase can be skipped with `--skip-skill` flag. + +#### Command Invocation + +After Phase 2 completes successfully, invoke workflow SKILL memory generator in incremental mode: + +```bash +SlashCommand(command="/memory:workflow-skill-memory --incremental") +``` + +**What This Does**: +- Reads updated manifest.json with new archived session +- Incrementally updates SKILL package files +- Fast execution (~5-10x faster than full regeneration) +- Updates sessions-timeline.md, lessons-learned.md, conflict-patterns.md +- Regenerates SKILL.md with latest session information + +**Skip Condition**: +- If user provides `--skip-skill` flag, skip this phase entirely +- Useful when batching multiple session completions + +**Error Handling**: +- If SKILL generation fails, log warning but do NOT fail the completion +- Session is still marked as completed and archived +- User can manually run `/memory:workflow-skill-memory` later + +**Expected Output**: +- SKILL package updated with new session +- Confirmation message: "Workflow SKILL package updated" + ## Workflow Execution Strategy -### Two-Phase Approach (Optimized) +### Three-Phase Approach (Optimized) **Phase 1: Minimal Manual Setup** (2 simple operations) - Find active session and extract name @@ -114,6 +150,12 @@ Complete workflow session archival. Session already moved to archive location. - Remove active marker - Return success/error result +**Phase 3: SKILL Package Update** (1 slash command, optional) +- Invoke `/memory:workflow-skill-memory --incremental` +- Update workflow progress SKILL package with new session +- Fast incremental update using existing aggregations +- Can be skipped with `--skip-skill` flag + ## Quick Commands ```bash @@ -125,6 +167,9 @@ bash(mv .workflow/WFS-session-name .workflow/.archives/WFS-session-name) # Phase 2: Agent completes archival Task(subagent_type="universal-executor", description="Complete session archival", prompt=`...`) + +# Phase 3: Update SKILL package (optional) +SlashCommand(command="/memory:workflow-skill-memory --incremental") ``` ## Archive Query Commands @@ -144,4 +189,3 @@ jq '.archives[] | select(.session_id == "WFS-user-auth")' .workflow/.archives/ma # List all watch patterns across sessions jq '.archives[].lessons.watch_patterns[]' .workflow/.archives/manifest.json ``` - diff --git a/.claude/workflows/cli-templates/prompts/workflow/skill-aggregation.txt b/.claude/workflows/cli-templates/prompts/workflow/skill-aggregation.txt new file mode 100644 index 00000000..024b5c0f --- /dev/null +++ b/.claude/workflows/cli-templates/prompts/workflow/skill-aggregation.txt @@ -0,0 +1,152 @@ +You are aggregating workflow session history to generate a progressive SKILL package. + +## Your Task + +Analyze archived workflow sessions and aggregate: +1. **Lessons Learned** - Successes, challenges, and watch patterns +2. **Conflict Patterns** - Recurring conflicts and resolutions +3. **Implementation Summaries** - Key outcomes by functional domain + +## Input Data + +You will receive: +- Session metadata (session_id, description, tags, metrics) +- Lessons from each session (successes, challenges, watch_patterns) +- IMPL_PLAN summaries +- Context package metadata (keywords, tech_stack, complexity) + +## Output Requirements + +### 1. Aggregated Lessons + +**Successes by Category**: +- Group successful patterns by functional domain (auth, testing, performance, etc.) +- Identify practices that succeeded across multiple sessions +- Mark best practices (success in 3+ sessions) + +**Challenges by Severity**: +- HIGH: Blocked development for >4 hours OR repeated in 3+ sessions +- MEDIUM: Required significant rework OR repeated in 2 sessions +- LOW: Minor issues resolved quickly + +**Watch Patterns**: +- Identify patterns mentioned in 2+ sessions +- Prioritize by frequency and severity +- Mark CRITICAL patterns (appeared in 3+ sessions with HIGH severity) + +**Format**: +```json +{ + "successes_by_category": { + "auth": ["JWT implementation with refresh tokens (3 sessions)", ...], + "testing": ["TDD reduced bugs by 60% (2 sessions)", ...] + }, + "challenges_by_severity": { + "high": [ + { + "challenge": "Token refresh edge cases", + "sessions": ["WFS-user-auth", "WFS-jwt-refresh"], + "frequency": 2 + } + ], + "medium": [...], + "low": [...] + }, + "watch_patterns": [ + { + "pattern": "Token concurrency issues", + "frequency": 3, + "severity": "CRITICAL", + "sessions": ["WFS-user-auth", "WFS-jwt-refresh", "WFS-oauth"] + } + ] +} +``` + +### 2. Conflict Patterns + +**Analysis**: +- Group conflicts by type (architecture, dependencies, testing, performance) +- Identify recurring patterns (same conflict in different sessions) +- Link successful resolutions to specific sessions + +**Format**: +```json +{ + "architecture": [ + { + "pattern": "Multiple authentication strategies conflict", + "description": "Different auth methods (JWT, OAuth, session) cause integration issues", + "sessions": ["WFS-user-auth", "WFS-oauth"], + "resolution": "Unified auth interface with strategy pattern", + "code_impact": ["src/auth/interface.ts", "src/auth/jwt.ts", "src/auth/oauth.ts"], + "frequency": 2, + "severity": "high" + } + ], + "dependencies": [...], + "testing": [...], + "performance": [...] +} +``` + +### 3. Implementation Summary + +**By Functional Domain**: +- Group sessions by primary tag/domain +- Summarize key accomplishments +- Link to context packages and plans + +**Format**: +```json +{ + "auth": { + "session_count": 3, + "sessions": [ + { + "session_id": "WFS-user-auth", + "description": "JWT authentication implementation", + "key_outcomes": [ + "JWT token generation and validation", + "Refresh token mechanism", + "Secure password hashing with bcrypt" + ], + "context_package": ".workflow/.archives/WFS-user-auth/.process/context-package.json", + "metrics": {"task_count": 5, "success_rate": 100, "duration_hours": 4.5} + } + ], + "cumulative_metrics": { + "total_tasks": 15, + "avg_success_rate": 95, + "total_hours": 12.5 + } + }, + "payment": {...}, + "ui": {...} +} +``` + +## Analysis Guidelines + +1. **Identify Patterns**: Look for recurring themes across sessions +2. **Prioritize by Impact**: Focus on high-frequency, high-impact patterns +3. **Link Sessions**: Connect related sessions (same domain, similar challenges) +4. **Extract Wisdom**: Surface actionable insights from lessons learned +5. **Maintain Context**: Keep references to original sessions and files + +## Quality Criteria + +- ✅ All sessions processed and categorized +- ✅ Patterns identified and frequency counted +- ✅ Severity levels assigned based on impact +- ✅ Resolutions linked to specific sessions +- ✅ Output is valid JSON with no missing fields +- ✅ References (paths) are accurate and complete + +## Important Notes + +- **NO hallucination**: Only aggregate data from provided sessions +- **Preserve detail**: Keep specific session references for traceability +- **Smart grouping**: Group similar patterns even if wording differs slightly +- **Frequency matters**: Prioritize patterns that appear in multiple sessions +- **Context preservation**: Keep context package paths for on-demand loading