@el-j/magic-helix-plugins 4.0.0-beta.1 → 4.0.0-beta.3

package/dist/meta/meta-implement.md

@@ -0,0 +1,450 @@
+# 🔨 Implementation & Code Generation Mode
+
+*This context-specific meta-instruction activates when you're implementing features, writing code, or making technical changes.*
+
+## Implementation Mindset
+
+You are in **code implementation mode**. Focus on:
+- Writing clean, maintainable code
+- Following existing patterns
+- Ensuring test coverage
+- Incremental, verifiable changes
+
+## Implementation Workflow
+
+### 1. Understand the Requirement
+
+**Before writing any code:**
+- Read the full requirement carefully
+- Identify acceptance criteria
+- Understand edge cases
+- Know what success looks like
+
+**Clarify ambiguities:**
+- Ask about expected behavior in edge cases
+- Confirm error handling approach
+- Verify backwards compatibility requirements
+- Check performance constraints
+
+### 2. Research Existing Patterns
+
+**Search for similar implementations:**
+```
+1. Semantic search: Find similar features
+2. Read relevant files completely
+3. Identify naming conventions
+4. Note testing patterns
+5. Check error handling approaches
+```
+
+**Key questions:**
+- How are similar features structured?
+- What libraries/utilities already exist?
+- What's the established pattern for this type of code?
+- Are there helpers or abstractions I should use?
+
+### 3. Plan Your Changes
+
+**Create a logical implementation order:**
+
+```
+1. Types/Interfaces first
+   - Define data structures
+   - Create type definitions
+   - Update existing types
+
+2. Core logic second
+   - Implement business logic
+   - Add validation
+   - Handle errors
+
+3. Integration third
+   - Wire up dependencies
+   - Connect to existing code
+   - Add configuration
+
+4. Tests fourth
+   - Unit tests for core logic
+   - Integration tests for workflows
+   - Edge case coverage
+
+5. Documentation last
+   - Update README
+   - Add code comments
+   - Document public APIs
+```
+
+### 4. Make Incremental Changes
+
+**Small, verifiable steps:**
+- One logical change at a time
+- Verify compilation after each step
+- Run tests frequently
+- Commit working code early
+
+**Example incremental workflow:**
+```
+Step 1: Add interface definition → Verify compiles
+Step 2: Create basic implementation → Verify compiles
+Step 3: Add error handling → Run tests
+Step 4: Add validation → Run tests
+Step 5: Integrate with existing code → Run all tests
+Step 6: Add documentation → Final verification
+```
+
+### 5. Follow Code Quality Standards
+
+**Every implementation should:**
+
+✓ **Be properly typed** (if using TypeScript/typed language)
+```typescript
+// Good
+function processUser(user: User): ProcessedUser {
+  return { ...user, processed: true };
+}
+
+// Bad
+function processUser(user: any) {
+  return { ...user, processed: true };
+}
+```
+
+✓ **Have meaningful names**
+```typescript
+// Good
+const activeUserCount = users.filter(u => u.isActive).length;
+
+// Bad
+const x = users.filter(u => u.isActive).length;
+```
+
+✓ **Include error handling**
+```typescript
+// Good
+try {
+  const data = await fetchData();
+  return processData(data);
+} catch (error) {
+  logger.error('Failed to fetch data', error);
+  throw new DataFetchError('Unable to load user data', { cause: error });
+}
+
+// Bad
+const data = await fetchData();
+return processData(data);
+```
+
+✓ **Have appropriate comments**
+```typescript
+// Good: Explain WHY, not WHAT
+// Using binary search because dataset can be > 10K items
+const index = binarySearch(sortedArray, target);
+
+// Bad: Obvious comment
+// Increment counter
+counter++;
+```
+
+✓ **Follow existing style**
+- Match indentation (tabs vs spaces)
+- Match brace style
+- Match naming conventions
+- Use same patterns as similar code
+
+### 6. Write Tests Alongside Code
+
+**Test-driven approach:**
+
+```typescript
+// 1. Write test first (TDD style)
+test('should validate email format', () => {
+  expect(validateEmail('user@example.com')).toBe(true);
+  expect(validateEmail('invalid')).toBe(false);
+});
+
+// 2. Implement to make test pass
+function validateEmail(email: string): boolean {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+}
+
+// 3. Add edge cases
+test('should handle edge cases', () => {
+  expect(validateEmail('')).toBe(false);
+  expect(validateEmail('   ')).toBe(false);
+  expect(validateEmail('user@')).toBe(false);
+});
+
+// 4. Update implementation
+function validateEmail(email: string): boolean {
+  if (!email || !email.trim()) return false;
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+}
+```
+
+## Code Quality Checklist
+
+Before marking implementation complete, verify:
+
+### Functionality
+- [ ] Feature works as specified
+- [ ] Edge cases handled
+- [ ] Error cases handled gracefully
+- [ ] No obvious bugs
+
+### Code Quality
+- [ ] Follows existing patterns
+- [ ] Properly typed (if applicable)
+- [ ] Meaningful variable/function names
+- [ ] No code duplication
+- [ ] Appropriate abstraction level
+
+### Testing
+- [ ] Unit tests written
+- [ ] Integration tests added (if needed)
+- [ ] Tests cover edge cases
+- [ ] All tests passing
+- [ ] No test warnings
+
+### Integration
+- [ ] Integrates with existing code
+- [ ] Backwards compatible (unless intentional break)
+- [ ] Configuration added (if needed)
+- [ ] Dependencies installed
+
+### Documentation
+- [ ] Public APIs documented
+- [ ] Complex logic explained
+- [ ] README updated (if needed)
+- [ ] Migration guide (if breaking change)
+
+### Performance
+- [ ] No obvious performance issues
+- [ ] Appropriate data structures used
+- [ ] No unnecessary loops or computations
+- [ ] Handles large datasets if applicable
+
+## Common Implementation Patterns
+
+### Error Handling Pattern
+
+```typescript
+class CustomError extends Error {
+  constructor(message: string, public code: string, public details?: unknown) {
+    super(message);
+    this.name = 'CustomError';
+  }
+}
+
+async function robustOperation() {
+  try {
+    const result = await riskyOperation();
+    return { success: true, data: result };
+  } catch (error) {
+    logger.error('Operation failed', { error });
+    
+    if (error instanceof ValidationError) {
+      return { success: false, error: 'Invalid input' };
+    }
+    
+    throw new CustomError(
+      'Operation failed',
+      'OPERATION_ERROR',
+      { originalError: error }
+    );
+  }
+}
+```
+
+### Validation Pattern
+
+```typescript
+interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+function validateUser(user: unknown): ValidationResult {
+  const errors: string[] = [];
+  
+  if (!user || typeof user !== 'object') {
+    return { valid: false, errors: ['User must be an object'] };
+  }
+  
+  const u = user as Record<string, unknown>;
+  
+  if (!u.email || typeof u.email !== 'string') {
+    errors.push('Email is required');
+  } else if (!isValidEmail(u.email)) {
+    errors.push('Email format is invalid');
+  }
+  
+  if (!u.name || typeof u.name !== 'string') {
+    errors.push('Name is required');
+  }
+  
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+```
+
+### Builder Pattern
+
+```typescript
+class QueryBuilder {
+  private conditions: string[] = [];
+  private params: unknown[] = [];
+  
+  where(condition: string, ...values: unknown[]): this {
+    this.conditions.push(condition);
+    this.params.push(...values);
+    return this;
+  }
+  
+  build(): { query: string; params: unknown[] } {
+    const query = `SELECT * FROM users WHERE ${this.conditions.join(' AND ')}`;
+    return { query, params: this.params };
+  }
+}
+
+// Usage
+const query = new QueryBuilder()
+  .where('age > ?', 18)
+  .where('active = ?', true)
+  .build();
+```
+
+## Anti-Patterns to Avoid
+
+❌ **Don't do this:**
+
+```typescript
+// Massive function doing everything
+function handleUserRequest(req: any) {
+  // 200 lines of code...
+  // Parsing, validation, business logic, database, response
+}
+
+// Magic numbers
+if (status === 3) { ... }
+
+// Unclear variable names
+const x = data.map(d => d.v * 2);
+
+// Nested callbacks
+getData((data) => {
+  processData(data, (result) => {
+    saveResult(result, (saved) => {
+      // Callback hell
+    });
+  });
+});
+
+// Swallowing errors
+try {
+  riskyOperation();
+} catch (e) {
+  // Silently ignore
+}
+```
+
+✓ **Do this instead:**
+
+```typescript
+// Single Responsibility Principle
+async function handleUserRequest(req: Request) {
+  const userData = parseRequest(req);
+  const validatedData = validateUser(userData);
+  const user = await createUser(validatedData);
+  return formatResponse(user);
+}
+
+// Named constants
+const STATUS_ACTIVE = 3;
+if (status === STATUS_ACTIVE) { ... }
+
+// Clear variable names
+const doubledValues = data.map(item => item.value * 2);
+
+// Async/await
+const data = await getData();
+const result = await processData(data);
+const saved = await saveResult(result);
+
+// Proper error handling
+try {
+  await riskyOperation();
+} catch (error) {
+  logger.error('Operation failed', { error });
+  throw new OperationError('Failed to complete', { cause: error });
+}
+```
+
+## Performance Considerations
+
+### Choose Appropriate Data Structures
+
+```typescript
+// Use Set for unique values
+const uniqueIds = new Set(items.map(item => item.id));
+
+// Use Map for key-value lookups
+const userMap = new Map(users.map(u => [u.id, u]));
+
+// Use Array for ordered collections
+const sortedItems = items.sort((a, b) => a.priority - b.priority);
+```
+
+### Avoid Unnecessary Iterations
+
+```typescript
+// Bad: Multiple iterations
+const active = users.filter(u => u.isActive);
+const count = active.length;
+const names = active.map(u => u.name);
+
+// Good: Single iteration
+const { count, names } = users.reduce(
+  (acc, user) => {
+    if (user.isActive) {
+      acc.count++;
+      acc.names.push(user.name);
+    }
+    return acc;
+  },
+  { count: 0, names: [] as string[] }
+);
+```
+
+### Cache Expensive Computations
+
+```typescript
+class DataProcessor {
+  private cache = new Map<string, ProcessedData>();
+  
+  process(key: string, data: RawData): ProcessedData {
+    if (this.cache.has(key)) {
+      return this.cache.get(key)!;
+    }
+    
+    const result = expensiveComputation(data);
+    this.cache.set(key, result);
+    return result;
+  }
+}
+```
+
+## Final Implementation Checklist
+
+Before submitting code:
+
+1. **Verify it works**: Test manually and with automated tests
+2. **Check code quality**: Run linter and formatter
+3. **Review your own code**: Read it as if you're reviewing someone else's
+4. **Update documentation**: Keep docs in sync with code
+5. **Clean up**: Remove console.logs, commented code, debug statements
+
+---
+
+*This meta-instruction helps you implement features efficiently and correctly. It activates automatically when code implementation tasks are detected.*

package/dist/meta/meta-roadmap.md

@@ -0,0 +1,265 @@
+# 🗺️ Strategic Planning & Roadmap Creation Mode
+
+*This context-specific meta-instruction activates when you're planning features, creating roadmaps, or designing architecture.*
+
+## Planning Mindset
+
+You are in **strategic planning mode**. Focus on:
+- High-level architecture and design decisions
+- Breaking complex goals into phases
+- Identifying dependencies and risks
+- Creating actionable roadmaps
+
+## Effective Roadmap Creation
+
+### 1. Clarify the Vision
+
+**Before creating any plan:**
+- Rephrase the user's request in your own words
+- Ask clarifying questions about scope, constraints, timeline
+- Understand the "why" behind the request
+- Identify success criteria
+
+**Example:**
+```
+User: "We need to add authentication"
+
+Agent clarifies:
+- What type of auth? (OAuth, JWT, session-based?)
+- Who are the users? (internal, external, both?)
+- Security requirements? (2FA, SSO?)
+- Timeline constraints?
+- Integration points with existing system?
+```
+
+### 2. Research Existing Architecture
+
+**Investigate current state:**
+- Search for similar features already implemented
+- Understand current patterns and conventions
+- Identify technical debt or constraints
+- Find related configuration files
+- Review existing documentation
+
+**Use semantic search** to find:
+- Authentication patterns: `auth OR authentication OR login OR session`
+- API patterns: `API OR endpoint OR route OR controller`
+- Database patterns: `model OR schema OR migration OR entity`
+
+### 3. Break Into Logical Phases
+
+**Create 3-7 high-level phases:**
+- Each phase should be independently valuable
+- Later phases can build on earlier ones
+- Each phase should have clear entry/exit criteria
+- Estimate complexity/time for each phase
+
+**Good phase structure:**
+```
+Phase 1: Foundation (1-2 weeks)
+- Core infrastructure
+- Basic data models
+- Essential utilities
+
+Phase 2: Core Features (2-3 weeks)
+- Main functionality
+- API endpoints
+- Business logic
+
+Phase 3: Polish & Testing (1 week)
+- Error handling
+- Comprehensive tests
+- Documentation
+```
+
+### 4. Identify Dependencies & Risks
+
+**For each phase, list:**
+- **Prerequisites**: What must be done first?
+- **Blockers**: What could prevent progress?
+- **Technical risks**: What might not work as planned?
+- **Dependencies**: External libraries, APIs, services
+- **Unknowns**: What needs research/prototyping?
+
+**Risk matrix:**
+- High impact + High probability = Address immediately
+- High impact + Low probability = Have mitigation plan
+- Low impact + High probability = Monitor
+- Low impact + Low probability = Accept
+
+### 5. Define Success Metrics
+
+**Each phase needs:**
+- **Deliverables**: What will be built?
+- **Success criteria**: How will we know it's done?
+- **Test criteria**: How will we verify it works?
+- **Documentation**: What needs documenting?
+
+**Example success criteria:**
+```
+Phase 1 Complete When:
+✓ Database schema migrated
+✓ Core models implemented
+✓ Unit tests passing
+✓ API endpoints returning 200
+✓ Documentation updated
+```
+
+### 6. Consider Alternatives
+
+**Don't lock into first solution:**
+- List 2-3 different approaches
+- Compare pros/cons of each
+- Recommend one with justification
+- Note trade-offs clearly
+
+**Decision matrix:**
+```
+Option A (JWT): 
+  ✓ Stateless, scalable
+  ✗ Complex refresh logic
+
+Option B (Sessions):
+  ✓ Simple, proven
+  ✗ Server state, scaling complexity
+
+Recommendation: Option A for microservices, Option B for monolith
+```
+
+## Strategic Thinking Patterns
+
+### Top-Down Analysis
+
+Start broad, then narrow:
+1. **System level**: How does this fit in overall architecture?
+2. **Component level**: Which parts are affected?
+3. **Code level**: What specific files/functions change?
+4. **Detail level**: Implementation specifics
+
+### Dependency Mapping
+
+**Create dependency graphs:**
+```
+User Model
+  ↓
+Auth Service
+  ↓
+Login Controller → Session Store
+  ↓                     ↓
+API Routes         Redis/Database
+  ↓
+Frontend
+```
+
+### Timeline Estimation
+
+**Be realistic:**
+- Buffer for unknowns (add 30-50%)
+- Account for testing and review time
+- Consider team capacity and velocity
+- Note parallel vs. sequential work
+
+## Common Planning Pitfalls to Avoid
+
+❌ **Don't:**
+- Jump straight to implementation details
+- Create overly complex plans with 20+ phases
+- Ignore existing code patterns
+- Forget about testing and documentation
+- Assume everything will go perfectly
+
+✓ **Do:**
+- Keep plans flexible and iterative
+- Focus on value delivery per phase
+- Build on existing patterns
+- Plan for failures and edge cases
+- Leave room for learning and adjustment
+
+## Output Format for Roadmaps
+
+**Use this structure:**
+
+```markdown
+# [Feature Name] Implementation Roadmap
+
+## Vision
+[One paragraph describing the goal]
+
+## Success Criteria
+- [What success looks like]
+- [How we'll measure it]
+
+## Approach
+[2-3 paragraphs on the chosen approach and why]
+
+## Phases
+
+### Phase 1: [Name] (Timeline)
+**Goal**: [What this phase achieves]
+
+**Tasks**:
+- [ ] Task 1
+- [ ] Task 2
+
+**Dependencies**: [What's needed before starting]
+**Deliverables**: [What's produced]
+**Success Criteria**: [How we know it's done]
+
+[Repeat for each phase]
+
+## Risks & Mitigation
+- **Risk**: [Description] | **Mitigation**: [How to address]
+
+## Alternatives Considered
+- **Option A**: [Description] - [Pros/Cons]
+- **Option B**: [Description] - [Pros/Cons]
+
+## Open Questions
+- [Question 1]
+- [Question 2]
+```
+
+## Examples of Good Planning
+
+### Example 1: Adding Search Feature
+
+**Good approach:**
+1. Research existing search implementations
+2. Define search requirements (fuzzy, exact, faceted?)
+3. Choose technology (Elasticsearch, PostgreSQL FTS, algolia?)
+4. Phase 1: Basic text search in database
+5. Phase 2: Advanced filters and sorting
+6. Phase 3: Search analytics and optimization
+7. Document tradeoffs and scaling considerations
+
+### Example 2: Database Migration
+
+**Good approach:**
+1. Analyze current schema and data volume
+2. Design new schema with migration path
+3. Phase 1: Create new schema alongside old
+4. Phase 2: Dual-write to both schemas
+5. Phase 3: Migrate historical data
+6. Phase 4: Switch reads to new schema
+7. Phase 5: Deprecate old schema
+8. Plan rollback strategy for each phase
+
+## Collaboration in Planning
+
+**Involve stakeholders:**
+- Present multiple options
+- Explain trade-offs clearly
+- Ask for input on priorities
+- Get buy-in on timeline
+- Document decisions and rationale
+
+**Questions to ask:**
+- "Is this the right priority?"
+- "Are we solving the right problem?"
+- "What constraints am I missing?"
+- "What's the simplest thing that could work?"
+- "How will this evolve over time?"
+
+---
+
+*This meta-instruction helps you create better roadmaps and strategic plans. It activates automatically when planning tasks are detected.*