maestro-flow 0.1.0

package/templates/cli/prompts/rules-tech-rules-agent-prompt.txt

@@ -0,0 +1,89 @@
+# Tech Stack Rules Generation Agent Prompt
+
+## Context Variables
+- {TECH_STACK_NAME}: Normalized tech stack name (e.g., "typescript-react")
+- {PRIMARY_LANG}: Primary language (e.g., "typescript")
+- {FILE_EXT}: File extension pattern (e.g., "{ts,tsx}")
+- {FRAMEWORK_TYPE}: frontend | backend | fullstack | library
+- {COMPONENTS}: Array of tech components
+- {OUTPUT_DIR}: .claude/rules/tech/{TECH_STACK_NAME}/
+
+## Agent Instructions
+
+Generate path-conditional rules for Claude Code automatic loading.
+
+### Step 1: Execute Exa Research
+
+Run 4-6 parallel queries based on tech stack:
+
+**Base Queries** (always execute):
+```
+mcp__exa__get_code_context_exa(query: "{PRIMARY_LANG} best practices principles 2025", tokensNum: 8000)
+mcp__exa__get_code_context_exa(query: "{PRIMARY_LANG} implementation patterns examples", tokensNum: 7000)
+mcp__exa__get_code_context_exa(query: "{PRIMARY_LANG} testing strategies conventions", tokensNum: 5000)
+mcp__exa__web_search_exa(query: "{PRIMARY_LANG} configuration setup 2025", numResults: 5)
+```
+
+**Component Queries** (for each framework in COMPONENTS):
+```
+mcp__exa__get_code_context_exa(query: "{PRIMARY_LANG} {component} integration patterns", tokensNum: 5000)
+```
+
+### Step 2: Read Rule Templates
+
+Read each template file before generating content:
+```
+Read(~/.ccw/workflows/cli-templates/prompts/rules/rule-core.txt)
+Read(~/.ccw/workflows/cli-templates/prompts/rules/rule-patterns.txt)
+Read(~/.ccw/workflows/cli-templates/prompts/rules/rule-testing.txt)
+Read(~/.ccw/workflows/cli-templates/prompts/rules/rule-config.txt)
+Read(~/.ccw/workflows/cli-templates/prompts/rules/rule-api.txt)       # Only if backend/fullstack
+Read(~/.ccw/workflows/cli-templates/prompts/rules/rule-components.txt) # Only if frontend/fullstack
+```
+
+### Step 3: Generate Rule Files
+
+Create directory and write files:
+```bash
+mkdir -p "{OUTPUT_DIR}"
+```
+
+**Always Generate**:
+- core.md (from rule-core.txt template)
+- patterns.md (from rule-patterns.txt template)
+- testing.md (from rule-testing.txt template)
+- config.md (from rule-config.txt template)
+
+**Conditional**:
+- api.md: Only if FRAMEWORK_TYPE == 'backend' or 'fullstack'
+- components.md: Only if FRAMEWORK_TYPE == 'frontend' or 'fullstack'
+
+### Step 4: Write Metadata
+
+```json
+{
+  "tech_stack": "{TECH_STACK_NAME}",
+  "primary_lang": "{PRIMARY_LANG}",
+  "file_ext": "{FILE_EXT}",
+  "framework_type": "{FRAMEWORK_TYPE}",
+  "components": ["{COMPONENTS}"],
+  "generated_at": "{ISO_TIMESTAMP}",
+  "source": "exa-research",
+  "files_generated": ["core.md", "patterns.md", "testing.md", "config.md", ...]
+}
+```
+
+### Step 5: Report Completion
+
+Provide summary:
+- Files created with their path patterns
+- Exa queries executed (count)
+- Sources consulted (count)
+
+## Critical Requirements
+
+1. Every .md file MUST start with `paths` YAML frontmatter
+2. Use {FILE_EXT} consistently across all rule files
+3. Synthesize Exa research into actionable rules
+4. Include code examples from Exa sources
+5. Keep each file focused on its specific domain

package/templates/cli/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

package/templates/cli/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

package/templates/cli/prompts/test-suggestions-enhancement.txt

@@ -0,0 +1,38 @@
+PURPOSE: Generate comprehensive multi-layer test enhancement suggestions
+  - Success: Cover L0-L3 layers with focus on API, integration, and error scenarios
+  - Scope: Files with coverage gaps identified in TEST_ANALYSIS_RESULTS.md
+  - Goal: Provide specific, actionable test case suggestions that increase coverage completeness
+
+TASK:
+  • L1 (Unit Tests): Suggest edge cases, boundary conditions, error paths, state transitions
+  • L2.1 (Integration): Suggest module interaction patterns, dependency injection scenarios
+  • L2.2 (API Contracts): Suggest request/response test cases, validation, status codes, error responses
+  • L2.4 (External APIs): Suggest mock strategies, failure scenarios, timeout handling, retry logic
+  • L2.5 (Failure Modes): Suggest exception hierarchies, error propagation, recovery strategies
+  • Cross-cutting: Suggest performance test cases, security considerations
+
+MODE: analysis
+
+CONTEXT: @.workflow/active/{test-session-id}/.process/TEST_ANALYSIS_RESULTS.md
+  Memory: Project type, test framework, existing test patterns, coverage gaps
+
+EXPECTED: Markdown report with structured test enhancement suggestions organized by:
+  1. File-level test requirements (per file needing tests)
+  2. Layer-specific test cases (L1, L2.1, L2.2, L2.4, L2.5)
+  3. Each suggestion includes:
+     - Test type and layer (e.g., "L2.2 API Contract Test")
+     - Specific test case description (e.g., "POST /api/users - Invalid email format")
+     - Expected behavior (e.g., "Returns 400 with validation error message")
+     - Dependencies/mocks needed (e.g., "Mock email service")
+     - Success criteria (e.g., "Status 400, error.field === 'email'")
+  4. Test ordering/dependencies (which tests should run first)
+  5. Integration test strategies (how components interact)
+  6. Error scenario matrix (all failure modes covered)
+
+CONSTRAINTS:
+  - Focus on identified coverage gaps from TEST_ANALYSIS_RESULTS.md
+  - Prioritize API tests, integration tests, and error scenarios
+  - No code generation - suggestions only with sufficient detail for implementation
+  - Consider project conventions and existing test patterns
+  - Each suggestion should be actionable and specific (not generic)
+  - Output format: Markdown with clear section headers