diff --git a/.claude/commands/memory/tech-research.md b/.claude/commands/memory/tech-research.md index 44ba2f9a..c64eebb6 100644 --- a/.claude/commands/memory/tech-research.md +++ b/.claude/commands/memory/tech-research.md @@ -119,6 +119,10 @@ Generate a complete tech stack SKILL package with Exa research. - 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**: @@ -147,16 +151,16 @@ Generate a complete tech stack SKILL package with Exa research. - For each additional component: mcp__exa__get_code_context_exa(query: \"{main_tech} {component} integration\", tokensNum: 5000) -3. **Synthesize Content into 6 Modules**: +3. **Read Module Format Template**: - 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 + Read template for structure guidance: + ```bash + Read(~/.claude/workflows/cli-templates/prompts/tech/tech-module-format.txt) + ``` - **Module Files**: +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) @@ -164,7 +168,14 @@ Generate a complete tech stack SKILL package with Exa research. - **config.md** - Setup, configuration, tooling (~3K tokens) - **frameworks.md** - Framework integration (only if composite, ~4K tokens) -4. **Write Files Directly**: + 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**: ```javascript // Create directory @@ -192,7 +203,7 @@ Generate a complete tech stack SKILL package with Exa research. }) ``` -5. **Report Completion**: +6. **Report Completion**: Provide summary: - Tech stack name @@ -201,9 +212,10 @@ Generate a complete tech stack SKILL package with Exa research. - 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) +- Handle errors gracefully (Exa failures, missing files, template read failures) - If tech stack cannot be determined, ask orchestrator to clarify " ) @@ -244,56 +256,31 @@ Generate a complete tech stack SKILL package with Exa research. // Repeat for other modules ``` -4. **Generate SKILL.md Index**: +4. **Read SKILL Index Template**: - **Template Structure**: - ```markdown - --- - 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}"} + ```javascript + Read(~/.claude/workflows/cli-templates/prompts/tech/tech-skill-index.txt) ``` -5. **Write SKILL.md**: +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**: ```javascript Write({ file_path: `.claude/skills/${TECH_STACK_NAME}/SKILL.md`, diff --git a/.claude/workflows/cli-templates/prompts/tech/tech-module-format.txt b/.claude/workflows/cli-templates/prompts/tech/tech-module-format.txt new file mode 100644 index 00000000..a90fd326 --- /dev/null +++ b/.claude/workflows/cli-templates/prompts/tech/tech-module-format.txt @@ -0,0 +1,359 @@ +Template for generating tech stack module documentation files + +## Purpose +Guide agent to create modular tech stack documentation from Exa research results. + +## File Location +`.claude/skills/{tech_stack_name}/*.md` + +## Module Structure + +Each module should include: +- **Frontmatter**: YAML with module name and tech stack +- **Main Sections**: Clear headings with hierarchical organization +- **Code Examples**: Real examples from Exa research +- **Best Practices**: Do's and don'ts sections +- **References**: Attribution to Exa sources + +--- + +## Module 1: principles.md (~3K tokens) + +**Purpose**: Core concepts, philosophies, and fundamental principles + +**Frontmatter**: +```yaml +--- +module: principles +tech_stack: {tech_stack_name} +description: Core concepts and philosophies +tokens: ~3000 +--- +``` + +**Structure**: +```markdown +# {Tech} Principles + +## Core Concepts +- Fundamental principle 1 +- Fundamental principle 2 +- Key philosophy + +## Design Philosophy +- Approach to problem-solving +- Architectural principles +- Core values + +## Key Features +- Feature 1: Description +- Feature 2: Description + +## When to Use +- Use case scenarios +- Best fit situations + +## References +- Source 1 from Exa +- Source 2 from Exa +``` + +--- + +## Module 2: patterns.md (~5K tokens) + +**Purpose**: Implementation patterns with code examples + +**Frontmatter**: +```yaml +--- +module: patterns +tech_stack: {tech_stack_name} +description: Implementation patterns with examples +tokens: ~5000 +--- +``` + +**Structure**: +```markdown +# {Tech} Patterns + +## Common Patterns + +### Pattern 1: {Name} +**Use Case**: When to use this pattern +**Implementation**: +\`\`\`{language} +// Code example from Exa +\`\`\` +**Benefits**: Why use this pattern + +### Pattern 2: {Name} +[Same structure] + +## Architectural Patterns +- Pattern descriptions +- Code examples + +## Component Patterns +- Reusable component structures +- Integration examples + +## References +- Exa sources with pattern examples +``` + +--- + +## Module 3: practices.md (~4K tokens) + +**Purpose**: Best practices, anti-patterns, pitfalls + +**Frontmatter**: +```yaml +--- +module: practices +tech_stack: {tech_stack_name} +description: Best practices and anti-patterns +tokens: ~4000 +--- +``` + +**Structure**: +```markdown +# {Tech} Best Practices + +## Do's +✅ **Practice 1**: Description + - Rationale + - Example scenario + +✅ **Practice 2**: Description + +## Don'ts +❌ **Anti-pattern 1**: What to avoid + - Why it's problematic + - Better alternative + +❌ **Anti-pattern 2**: What to avoid + +## Common Pitfalls +1. **Pitfall 1**: Description and solution +2. **Pitfall 2**: Description and solution + +## Performance Considerations +- Optimization techniques +- Common bottlenecks + +## Security Best Practices +- Security considerations +- Common vulnerabilities + +## References +- Exa sources for best practices +``` + +--- + +## Module 4: testing.md (~3K tokens) + +**Purpose**: Testing strategies, frameworks, and examples + +**Frontmatter**: +```yaml +--- +module: testing +tech_stack: {tech_stack_name} +description: Testing strategies and frameworks +tokens: ~3000 +--- +``` + +**Structure**: +```markdown +# {Tech} Testing + +## Testing Strategies +- Unit testing approach +- Integration testing approach +- E2E testing approach + +## Testing Frameworks +### Framework 1 +- Setup +- Basic usage +- Example: +\`\`\`{language} +// Test example from Exa +\`\`\` + +## Test Patterns +- Common test patterns +- Mock strategies +- Assertion best practices + +## Coverage Recommendations +- What to test +- Coverage targets + +## References +- Exa sources for testing examples +``` + +--- + +## Module 5: config.md (~3K tokens) + +**Purpose**: Setup, configuration, and tooling + +**Frontmatter**: +```yaml +--- +module: config +tech_stack: {tech_stack_name} +description: Setup, configuration, and tooling +tokens: ~3000 +--- +``` + +**Structure**: +```markdown +# {Tech} Configuration + +## Installation +\`\`\`bash +# Installation commands +\`\`\` + +## Basic Configuration +\`\`\`{config-format} +// Configuration example from Exa +\`\`\` + +## Common Configurations +### Development +- Dev config setup +- Hot reload configuration + +### Production +- Production optimizations +- Build configurations + +## Tooling +- Recommended tools +- IDE/Editor setup +- Linters and formatters + +## Environment Setup +- Environment variables +- Config file structure + +## References +- Exa sources for configuration +``` + +--- + +## Module 6: frameworks.md (~4K tokens) [CONDITIONAL] + +**Purpose**: Framework integration patterns (only for composite tech stacks) + +**Condition**: Only generate if `is_composite = true` + +**Frontmatter**: +```yaml +--- +module: frameworks +tech_stack: {tech_stack_name} +description: Framework integration patterns +tokens: ~4000 +conditional: composite_only +--- +``` + +**Structure**: +```markdown +# {Main Tech} + {Framework} Integration + +## Integration Overview +- How {main_tech} works with {framework} +- Architecture considerations + +## Setup +\`\`\`bash +# Integration setup commands +\`\`\` + +## Integration Patterns + +### Pattern 1: {Name} +\`\`\`{language} +// Integration example from Exa +\`\`\` + +## Best Practices +- Integration best practices +- Common pitfalls + +## Examples +- Real-world integration examples +- Code samples from Exa + +## References +- Exa sources for integration patterns +``` + +--- + +## Metadata File: metadata.json + +**Purpose**: Store generation metadata and research summary + +**Structure**: +```json +{ + "tech_stack_name": "typescript-react-nextjs", + "components": ["typescript", "react", "nextjs"], + "is_composite": true, + "generated_at": "2025-11-04T22:00:00Z", + "source": "exa-research", + "research_summary": { + "total_queries": 6, + "total_sources": 25, + "query_list": [ + "typescript core principles best practices 2025", + "react common patterns architecture examples", + "nextjs configuration setup tooling 2025", + "testing strategies", + "react nextjs integration", + "typescript react integration" + ] + } +} +``` + +--- + +## Generation Guidelines + +### Content Synthesis from Exa +- Extract relevant code examples from Exa results +- Synthesize information from multiple sources +- Maintain technical accuracy +- Cite sources in References section + +### Formatting Rules +- Use clear markdown headers +- Include code fences with language specification +- Use emoji for Do's (✅) and Don'ts (❌) +- Keep token estimates accurate + +### Error Handling +- If Exa query fails, note in References section +- If insufficient data, mark section as "Limited research available" +- Handle missing components gracefully + +### Token Distribution +- Total budget: ~22K tokens for 6 modules +- Adjust module size based on content availability +- Prioritize quality over hitting exact token counts diff --git a/.claude/workflows/cli-templates/prompts/tech/tech-skill-index.txt b/.claude/workflows/cli-templates/prompts/tech/tech-skill-index.txt new file mode 100644 index 00000000..f71cd23a --- /dev/null +++ b/.claude/workflows/cli-templates/prompts/tech/tech-skill-index.txt @@ -0,0 +1,185 @@ +Template for generating tech stack SKILL.md index file + +## Purpose +Create main SKILL package index with module references and loading recommendations. + +## File Location +`.claude/skills/{tech_stack_name}/SKILL.md` + +## Template Structure + +```markdown +--- +name: {TECH_STACK_NAME} +description: {MAIN_TECH} development guidelines from industry standards (Exa research) +version: 1.0.0 +generated: {ISO_TIMESTAMP} +source: exa-research +--- +# {TechStackTitle} SKILL Package + +## Overview + +{Brief 1-2 sentence description of the tech stack and purpose of this SKILL package} + +**Primary Technology**: {MAIN_TECH} +{IF_COMPOSITE}**Frameworks**: {COMPONENT_LIST}{/IF_COMPOSITE} + +## 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{/IF_COMPOSITE} + +## Loading Recommendations + +### Quick Reference (~7K tokens) +Load for quick consultation on core concepts: +- principles.md +- practices.md + +**Use When**: Need quick reminder of best practices or core principles + +### Implementation Focus (~8K tokens) +Load for active development work: +- patterns.md +- config.md + +**Use When**: Writing code, setting up projects, implementing features + +### Complete Package (~22K tokens) +Load all modules for comprehensive understanding: +- All 5-6 modules + +**Use When**: Learning tech stack, architecture reviews, comprehensive reference + +## Usage + +**Load this SKILL when**: +- Starting new {TECH_STACK} projects +- Reviewing {TECH_STACK} code +- Learning {TECH_STACK} best practices +- Implementing {TECH_STACK} patterns +- Troubleshooting {TECH_STACK} issues + +**Auto-triggers on**: +- Keywords: {TECH_KEYWORDS} +- File types: {FILE_EXTENSIONS} + +## Research Metadata + +- **Generated**: {ISO_TIMESTAMP} +- **Source**: Exa Research (web search + code context) +- **Queries Executed**: {QUERY_COUNT} +- **Sources Consulted**: {SOURCE_COUNT} +- **Research Quality**: {QUALITY_INDICATOR} + +## Tech Stack Components + +**Primary**: {MAIN_TECH} - {MAIN_TECH_DESCRIPTION} + +{IF_COMPOSITE} +**Additional Frameworks**: +{FOR_EACH_COMPONENT} +- **{COMPONENT_NAME}**: {COMPONENT_DESCRIPTION} +{/FOR_EACH_COMPONENT} +{/IF_COMPOSITE} + +## Version History + +- **v1.0.0** ({DATE}): Initial SKILL package generated from Exa research + +--- + +## Developer Notes + +This SKILL package was auto-generated using: +- `/memory:tech-research` command +- Exa AI research APIs (mcp__exa__get_code_context_exa, mcp__exa__web_search_exa) +- Token limit: ~5K per module, ~22K total + +To regenerate: +```bash +/memory:tech-research "{tech_stack_name}" --regenerate +``` +``` + +--- + +## Variable Substitution Guide + +### Required Variables +- `{TECH_STACK_NAME}`: Lowercase hyphenated name (e.g., "typescript-react-nextjs") +- `{TechStackTitle}`: Title case display name (e.g., "TypeScript React Next.js") +- `{MAIN_TECH}`: Primary technology (e.g., "TypeScript") +- `{ISO_TIMESTAMP}`: ISO 8601 timestamp (e.g., "2025-11-04T22:00:00Z") +- `{QUERY_COUNT}`: Number of Exa queries executed (e.g., 6) +- `{SOURCE_COUNT}`: Total sources consulted (e.g., 25) + +### Conditional Variables +- `{IF_COMPOSITE}...{/IF_COMPOSITE}`: Only include if tech stack has multiple components +- `{COMPONENT_LIST}`: Comma-separated list of framework names +- `{FOR_EACH_COMPONENT}...{/FOR_EACH_COMPONENT}`: Loop through components + +### Optional Variables +- `{MAIN_TECH_DESCRIPTION}`: One-line description of primary tech +- `{COMPONENT_DESCRIPTION}`: One-line description per component +- `{TECH_KEYWORDS}`: Comma-separated trigger keywords +- `{FILE_EXTENSIONS}`: File extensions (e.g., ".ts, .tsx, .jsx") +- `{QUALITY_INDICATOR}`: Research quality metric (e.g., "High", "Medium") + +--- + +## Generation Instructions + +### Step 1: Read metadata.json +Extract values for variables from metadata.json generated during module creation. + +### Step 2: Determine composite status +- Single tech: Omit {IF_COMPOSITE} sections +- Composite: Include frameworks section and integration module reference + +### Step 3: Calculate token estimates +- Verify module files exist +- Adjust token estimates based on actual file sizes +- Update loading recommendation estimates + +### Step 4: Generate descriptions +- **Overview**: Brief description of tech stack purpose +- **Main tech description**: One-liner for primary technology +- **Component descriptions**: One-liner per additional framework + +### Step 5: Build keyword lists +- Extract common keywords from tech stack name +- Add file extensions relevant to tech stack +- Include framework-specific triggers + +### Step 6: Format timestamps +- Use ISO 8601 format for all timestamps +- Include timezone (UTC recommended) + +### Step 7: Write SKILL.md +- Apply template with all substitutions +- Validate markdown formatting +- Verify all relative paths work + +--- + +## Validation Checklist + +- [ ] All module files exist and are referenced +- [ ] Token estimates are reasonably accurate +- [ ] Conditional sections handled correctly (composite vs single) +- [ ] Timestamps in ISO 8601 format +- [ ] All relative paths use ./ prefix +- [ ] Metadata section matches metadata.json +- [ ] Loading recommendations align with actual module sizes +- [ ] Usage section includes relevant trigger keywords