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

Overview

Pure Orchestrator with Agent Delegation: Prepares context paths and delegates ALL work to agent. Agent produces files directly.

Auto-Continue Workflow: Runs fully autonomously once triggered. Each phase completes and automatically triggers the next phase.

Execution Paths:

• Full Path: All 3 phases (no existing SKILL OR --regenerate specified)
• Skip Path: Phase 1 → Phase 3 (existing SKILL found AND no --regenerate flag)
• Phase 3 Always Executes: SKILL index is always generated or updated

Agent Responsibility:

• Agent does ALL the work: context reading, Exa research, content synthesis, file writing
• Orchestrator only provides context paths and waits for completion

Core Rules

1. Start Immediately: First action is TodoWrite initialization, second action is Phase 1 execution
2. Context Path Delegation: Pass session directory or tech stack name to agent, let agent do discovery
3. Agent Produces Files: Agent directly writes all module files, orchestrator does NOT parse agent output
4. Auto-Continue: After completing each phase, update TodoWrite and immediately execute next phase
5. No User Prompts: Never ask user questions or wait for input between phases
6. Track Progress: Update TodoWrite after EVERY phase completion before starting next phase
7. Lightweight Index: Phase 3 only generates SKILL.md index by reading existing files

---

3-Phase Execution

Phase 1: Prepare Context Paths

Goal: Detect input mode, prepare context paths for agent, check existing SKILL

Input Mode Detection:

# Get input parameter
input="$1"

# Detect mode
if [[ "$input" == WFS-* ]]; then
  MODE="session"
  SESSION_ID="$input"
  CONTEXT_PATH=".workflow/${SESSION_ID}"
else
  MODE="direct"
  TECH_STACK_NAME="$input"
  CONTEXT_PATH="$input"  # Pass tech stack name as context
fi

Check Existing SKILL:

# For session mode, peek at session to get tech stack name
if [[ "$MODE" == "session" ]]; then
  bash(test -f ".workflow/${SESSION_ID}/workflow-session.json")
  Read(.workflow/${SESSION_ID}/workflow-session.json)
  # Extract tech_stack_name (minimal extraction)
fi

# Normalize and check
normalized_name=$(echo "$TECH_STACK_NAME" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
bash(test -d ".claude/skills/${normalized_name}" && echo "exists" || echo "not_exists")
bash(find ".claude/skills/${normalized_name}" -name "*.md" 2>/dev/null | wc -l || echo 0)

Skip Decision:

if (existing_files > 0 && !regenerate_flag) {
  SKIP_GENERATION = true
  message = "Tech stack SKILL already exists, skipping Phase 2. Use --regenerate to force regeneration."
} else if (regenerate_flag) {
  bash(rm -rf ".claude/skills/${normalized_name}")
  SKIP_GENERATION = false
  message = "Regenerating tech stack SKILL from scratch."
} else {
  SKIP_GENERATION = false
  message = "No existing SKILL found, generating new tech stack documentation."
}

Output Variables:

• MODE: session or direct
• SESSION_ID: Session ID (if session mode)
• CONTEXT_PATH: Path to session directory OR tech stack name
• TECH_STACK_NAME: Extracted or provided tech stack name
• SKIP_GENERATION: Boolean - whether to skip Phase 2

TodoWrite:

• If skipping: Mark phase 1 completed, phase 2 completed, phase 3 in_progress
• If not skipping: Mark phase 1 completed, phase 2 in_progress

---

Phase 2: Agent Produces All Files

Skip Condition: Skipped if SKIP_GENERATION = true

Goal: Delegate EVERYTHING to agent - context reading, Exa research, content synthesis, and file writing

Agent Task Specification:

Task(
  subagent_type: "general-purpose",
  description: "Generate tech stack SKILL: {CONTEXT_PATH}",
  prompt: "
Generate a complete tech stack SKILL package with Exa research.

**Context Provided**:
- Mode: {MODE}
- Context Path: {CONTEXT_PATH}

**Your Responsibilities**:

1. **Extract Tech Stack Information**:

   IF MODE == 'session':
     - Read `.workflow/{SESSION_ID}/workflow-session.json`
     - Read `.workflow/{SESSION_ID}/.process/context-package.json`
     - Extract tech_stack: {language, frameworks, libraries}
     - Build tech stack name: \"{language}-{framework1}-{framework2}\"
     - Example: \"typescript-react-nextjs\"

   IF MODE == 'direct':
     - Tech stack name = CONTEXT_PATH
     - Parse composite: split by '-' delimiter
     - Example: \"typescript-react-nextjs\" → [\"typescript\", \"react\", \"nextjs\"]

2. **Execute Exa Research** (4-6 parallel queries):

   Base Queries (always execute):
   - mcp__exa__get_code_context_exa(query: \"{tech} core principles best practices 2025\", tokensNum: 8000)
   - mcp__exa__get_code_context_exa(query: \"{tech} common patterns architecture examples\", tokensNum: 7000)
   - mcp__exa__web_search_exa(query: \"{tech} configuration setup tooling 2025\", numResults: 5)
   - mcp__exa__get_code_context_exa(query: \"{tech} testing strategies\", tokensNum: 5000)

   Component Queries (if composite):
   - For each additional component:
     mcp__exa__get_code_context_exa(query: \"{main_tech} {component} integration\", tokensNum: 5000)

3. **Synthesize Content into 6 Modules**:

   Structure each module with:
   - Frontmatter (module name, tech stack)
   - Main sections with headings
   - Code examples from Exa research
   - Best practices / do's and don'ts
   - References to Exa sources

   **Module Files**:
   - **principles.md** - Core concepts, philosophies (~3K tokens)
   - **patterns.md** - Implementation patterns with code examples (~5K tokens)
   - **practices.md** - Best practices, anti-patterns, pitfalls (~4K tokens)
   - **testing.md** - Testing strategies, frameworks (~3K tokens)
   - **config.md** - Setup, configuration, tooling (~3K tokens)
   - **frameworks.md** - Framework integration (only if composite, ~4K tokens)

4. **Write Files Directly**:

   ```javascript
   // Create directory
   bash(mkdir -p \".claude/skills/{tech_stack_name}\")

   // Write each module file using Write tool
   Write({ file_path: \".claude/skills/{tech_stack_name}/principles.md\", content: ... })
   Write({ file_path: \".claude/skills/{tech_stack_name}/patterns.md\", content: ... })
   Write({ file_path: \".claude/skills/{tech_stack_name}/practices.md\", content: ... })
   Write({ file_path: \".claude/skills/{tech_stack_name}/testing.md\", content: ... })
   Write({ file_path: \".claude/skills/{tech_stack_name}/config.md\", content: ... })
   // Write frameworks.md only if composite

   // Write metadata.json
   Write({
     file_path: \".claude/skills/{tech_stack_name}/metadata.json\",
     content: JSON.stringify({
       tech_stack_name,
       components,
       is_composite,
       generated_at: timestamp,
       source: \"exa-research\",
       research_summary: { total_queries, total_sources }
     })
   })

5. Report Completion:

   Provide summary:

   • Tech stack name
   • Files created (count)
   • Exa queries executed
   • Sources consulted

CRITICAL:

• You have FULL autonomy - read files, execute Exa, synthesize content, write files
• Do NOT return JSON or structured data - produce actual .md files
• Handle errors gracefully (Exa failures, missing files)
• If tech stack cannot be determined, ask orchestrator to clarify " )

**Completion Criteria**:
- Agent task executed successfully
- 5-6 modular files written to `.claude/skills/{tech_stack_name}/`
- metadata.json written
- Agent reports completion

**TodoWrite**: Mark phase 2 completed, phase 3 in_progress

---

### Phase 3: Generate SKILL.md Index

**Note**: This phase **ALWAYS executes** - generates or updates the SKILL index.

**Goal**: Read generated module files and create SKILL.md index with loading recommendations

**Steps**:

1. **Verify Generated Files**:
   ```bash
   bash(find ".claude/skills/${TECH_STACK_NAME}" -name "*.md" -type f | sort)

2. Read metadata.json:

   Read(.claude/skills/${TECH_STACK_NAME}/metadata.json)
   // Extract: tech_stack_name, components, is_composite, research_summary
   

3. Read Module Headers (optional, first 20 lines):

   Read(.claude/skills/${TECH_STACK_NAME}/principles.md, limit: 20)
   // Repeat for other modules
   

4. Generate SKILL.md Index:

   Template Structure:

   ---
   name: {TECH_STACK_NAME}
   description: {MAIN_TECH} development guidelines from industry standards (Exa research)
   version: 1.0.0
   generated: {timestamp}
   source: exa-research
   ---
   # {TechStack} SKILL Package
   
   ## Overview
   {Brief description}
   
   ## Modular Documentation
   
   ### Core Understanding (~8K tokens)
   - [Principles](./principles.md) - Core concepts and philosophies
   - [Patterns](./patterns.md) - Implementation patterns with examples
   
   ### Practical Guidance (~7K tokens)
   - [Best Practices](./practices.md) - Do's, don'ts, anti-patterns
   - [Testing](./testing.md) - Testing strategies and frameworks
   
   ### Configuration & Integration (~7K tokens)
   - [Configuration](./config.md) - Setup, tooling, configuration
   {if composite: "- [Frameworks](./frameworks.md) - Integration patterns"}
   
   ## Loading Recommendations
   - **Quick**: principles.md + practices.md (~7K)
   - **Implementation**: patterns.md + config.md (~8K)
   - **Complete**: All modules (~22K)
   
   ## Usage
   Load when: starting {TECH_STACK} projects, reviewing code, learning best practices
   
   ## Research Metadata
   - Generated: {timestamp}
   - Source: Exa Research
   - Queries: {count}
   - Sources: {count}
   
   ## Tech Stack
   Primary: {MAIN_TECH}
   {if composite: "Frameworks: {COMPONENTS}"}
   

5. Write SKILL.md:

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

Completion Criteria:

• SKILL.md index written
• All module files verified
• Loading recommendations included

TodoWrite: Mark phase 3 completed

Final Report:

✅ Tech Stack SKILL Package Complete

Tech Stack: {TECH_STACK_NAME}
Location: .claude/skills/{TECH_STACK_NAME}/

Files: SKILL.md + 5-6 modules + metadata.json
Exa Research: {queries} queries, {sources} sources

Usage: Skill(command: "{TECH_STACK_NAME}")

---

Implementation Details

TodoWrite Patterns

Initialization (Before Phase 1):

TodoWrite({todos: [
  {"content": "Prepare context paths", "status": "in_progress", "activeForm": "Preparing context paths"},
  {"content": "Agent produces all module files", "status": "pending", "activeForm": "Agent producing files"},
  {"content": "Generate SKILL.md index", "status": "pending", "activeForm": "Generating SKILL index"}
]})

Full Path (SKIP_GENERATION = false):

// After Phase 1
TodoWrite({todos: [
  {"content": "Prepare context paths", "status": "completed", ...},
  {"content": "Agent produces all module files", "status": "in_progress", ...},
  {"content": "Generate SKILL.md index", "status": "pending", ...}
]})

// After Phase 2
TodoWrite({todos: [
  {"content": "Prepare context paths", "status": "completed", ...},
  {"content": "Agent produces all module files", "status": "completed", ...},
  {"content": "Generate SKILL.md index", "status": "in_progress", ...}
]})

// After Phase 3
TodoWrite({todos: [
  {"content": "Prepare context paths", "status": "completed", ...},
  {"content": "Agent produces all module files", "status": "completed", ...},
  {"content": "Generate SKILL.md index", "status": "completed", ...}
]})

Skip Path (SKIP_GENERATION = true):

// After Phase 1 (skip Phase 2)
TodoWrite({todos: [
  {"content": "Prepare context paths", "status": "completed", ...},
  {"content": "Agent produces all module files", "status": "completed", ...},  // Skipped
  {"content": "Generate SKILL.md index", "status": "in_progress", ...}
]})

Execution Flow

Full Path:

User → TodoWrite Init → Phase 1 (prepare) → Phase 2 (agent writes files) → Phase 3 (write index) → Report

Skip Path:

User → TodoWrite Init → Phase 1 (detect existing) → Phase 3 (update index) → Report

Error Handling

Phase 1 Errors:

• Invalid session ID: Report error, verify session exists
• Missing context-package: Warn, fall back to direct mode
• No tech stack detected: Ask user to specify tech stack name

Phase 2 Errors (Agent):

• Agent task fails: Retry once, report if fails again
• Exa API failures: Agent handles internally with retries
• Incomplete results: Warn user, proceed with partial data if minimum sections available

Phase 3 Errors:

• Write failures: Report which files failed
• Missing files: Note in SKILL.md, suggest regeneration

---

Parameters

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

Arguments:

• session-id | tech-stack-name: Input source (auto-detected by WFS- prefix)
  • Session mode: WFS-user-auth-v2 - Extract tech stack from workflow
  • Direct mode: "typescript", "typescript-react-nextjs" - User specifies
• --regenerate: Force regenerate existing SKILL (deletes and recreates)
• --tool: Reserved for future CLI integration (default: gemini)

---

Examples

Generated File Structure (for all examples):

.claude/skills/{tech-stack}/
├── SKILL.md           # Index (Phase 3)
├── principles.md      # Agent (Phase 2)
├── patterns.md        # Agent
├── practices.md       # Agent
├── testing.md         # Agent
├── config.md          # Agent
├── frameworks.md      # Agent (if composite)
└── metadata.json      # Agent

Direct Mode - Single Stack

/memory:tech-research "typescript"

Workflow:

1. Phase 1: Detects direct mode, checks existing SKILL
2. Phase 2: Agent executes 4 Exa queries, writes 5 modules
3. Phase 3: Generates SKILL.md index

Direct Mode - Composite Stack

/memory:tech-research "typescript-react-nextjs"

Workflow:

1. Phase 1: Decomposes into ["typescript", "react", "nextjs"]
2. Phase 2: Agent executes 6 Exa queries (4 base + 2 components), writes 6 modules (adds frameworks.md)
3. Phase 3: Generates SKILL.md index with framework integration

Session Mode - Extract from Workflow

/memory:tech-research WFS-user-auth-20251104

Workflow:

1. Phase 1: Reads session, extracts tech stack: python-fastapi-sqlalchemy
2. Phase 2: Agent researches Python + FastAPI + SQLAlchemy, writes 6 modules
3. Phase 3: Generates SKILL.md index

Regenerate Existing

/memory:tech-research "react" --regenerate

Workflow:

1. Phase 1: Deletes existing SKILL due to --regenerate
2. Phase 2: Agent executes fresh Exa research (latest 2025 practices)
3. Phase 3: Generates updated SKILL.md

Skip Path - Fast Update

/memory:tech-research "python"

Scenario: SKILL already exists with 7 files

Workflow:

1. Phase 1: Detects existing SKILL, sets SKIP_GENERATION = true
2. Phase 2: SKIPPED
3. Phase 3: Updates SKILL.md index only (5-10x faster)