Claude-Code-Workflow/.claude/commands/memory/tech-research.md

name, description, argument-hint, allowed-tools

name	description	argument-hint	allowed-tools
tech-research	Generate tech stack SKILL packages using Exa research via agent delegation	[session-id | tech-stack-name] [--regenerate] [--tool <gemini|qwen>]	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

# 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

# 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

# User provides tech stack name directly
tech_stack_name="$tech_stack_input"
# Example: "typescript", "python", "typescript-react-nextjs"

Step 3: Decompose Composite Stack

# 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

# 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:

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

// 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:

---
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:

---
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}

// 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(mkdir -p ".claude/skills/${TECH_STACK_NAME}")

Step 2: Write Modular Files

Use Write tool for each module file:

// 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

---
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

Write({
  file_path: `.claude/skills/${TECH_STACK_NAME}/SKILL.md`,
  content: generatedSKILLIndexMarkdown
})

Step 5: Write Metadata File

{
  "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"
}

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

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:

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:

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:

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:

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):

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:

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

/memory:tech-research [session-id | "tech-stack-name"] [--regenerate] [--tool <gemini|qwen>]

• 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

/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

/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

/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

/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

/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