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

package/dist/default_templates/meta/meta-implement.md

@@ -1,450 +0,0 @@
-# 🔨 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/default_templates/meta/meta-roadmap.md

@@ -1,265 +0,0 @@
-# 🗺️ 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.*

package/dist/default_templates/nestjs/nestjs-core.md

@@ -1,7 +0,0 @@
-# Framework: NestJS
-- **ALWAYS** follow the standard architecture: `Module` > `Controller` > `Service`.
-- **CONTROLLERS** should *only* handle HTTP request/response logic and DTO validation.
-- **SERVICES** should contain *all* business logic.
-- **ALWAYS** use DTOs (Data Transfer Objects) for `POST`/`PUT` bodies and validate them with `class-validator`.
-- **ALWAYS** use Dependency Injection. Never instantiate services manually.
-- **MODULES**: Keep modules granular. Import only what is needed.