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

name: tech-research description: 3-phase orchestrator: extract tech stack from session/name → delegate to agent for Exa research and module generation → generate SKILL.md index (skips phase 2 if exists) argument-hint: "[session-id | tech-stack-name] [--regenerate] [--tool <gemini|qwen>]" allowed-tools: 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}

**Templates Available**:
- Module Format: ~/.claude/workflows/cli-templates/prompts/tech/tech-module-format.txt
- SKILL Index: ~/.claude/workflows/cli-templates/prompts/tech/tech-skill-index.txt

**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. **Read Module Format Template**:

   Read template for structure guidance:
   ```bash
   Read(~/.claude/workflows/cli-templates/prompts/tech/tech-module-format.txt)

4. Synthesize Content into 6 Modules:

   Follow template structure from tech-module-format.txt:

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

   Each module follows template format:

   • Frontmatter (YAML)
   • Main sections with clear headings
   • Code examples from Exa research
   • Best practices sections
   • References to Exa sources

5. Write Files Directly:

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

6. Report Completion:

   Provide summary:

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

CRITICAL:

• MUST read external template files before generating content (step 3 for modules, step 4 for index)
• 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, template read failures)
• 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. Read SKILL Index Template:

   Read(~/.claude/workflows/cli-templates/prompts/tech/tech-skill-index.txt)
   

5. Generate SKILL.md Index:

   Follow template from tech-skill-index.txt with variable substitutions:

   • {TECH_STACK_NAME}: From metadata.json
   • {MAIN_TECH}: Primary technology
   • {ISO_TIMESTAMP}: Current timestamp
   • {QUERY_COUNT}: From research_summary
   • {SOURCE_COUNT}: From research_summary
   • Conditional sections for composite tech stacks

   Template provides structure for:

   • Frontmatter with metadata
   • Overview and tech stack description
   • Module organization (Core/Practical/Config sections)
   • Loading recommendations (Quick/Implementation/Complete)
   • Usage guidelines and auto-trigger keywords
   • Research metadata and version history

6. 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)