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

package/dist/patterns/reasoning/preview-before-action.md

@@ -0,0 +1,194 @@
+# Preview Before Action Pattern
+
+## Purpose
+Show what will happen before executing, even for non-destructive operations. From **Cline** pattern.
+
+## Template
+
+```markdown
+## Preview Policy
+
+Before any file modification, show preview:
+
+### Preview Format
+```
+📝 **Preview**: {OPERATION_NAME}
+
+**File**: {FILE_PATH}
+**Lines**: {START_LINE}-{END_LINE}
+
+**Current**:
+```{LANGUAGE}
+{OLD_CODE}
+```
+
+**Proposed**:
+```{LANGUAGE}
+{NEW_CODE}
+```
+
+**Changes**:
+- {CHANGE_DESCRIPTION_1}
+- {CHANGE_DESCRIPTION_2}
+```
+```
+
+## Examples
+
+### Cline (Code Edit Preview)
+```markdown
+## Preview Policy: File Edits
+
+Before modifying files, show exact changes:
+
+📝 **Preview**: Update import path in Header component
+
+**File**: `src/components/Header.tsx`
+**Lines**: 1-10
+
+**Current**:
+```typescript
+import React from 'react';
+import { Button } from './ui/button';
+import { Logo } from './Logo';
+
+export const Header = () => {
+  return (
+    <header>
+      <Logo />
+      <Button>Click me</Button>
+    </header>
+  );
+};
+```
+
+**Proposed**:
+```typescript
+import React from 'react';
+import { Button } from '@/components/ui/Button'; // Fixed path and capitalization
+import { Logo } from './Logo';
+
+export const Header = () => {
+  return (
+    <header>
+      <Logo />
+      <Button>Click me</Button>
+    </header>
+  );
+};
+```
+
+**Changes**:
+- Changed `./ui/button` to `@/components/ui/Button`
+- Fixed case sensitivity (button → Button)
+- Uses absolute path alias (@/) for clarity
+
+Proceeding with edit...
+```
+
+### same.new (Component Creation Preview)
+```markdown
+## Preview Policy: New File Creation
+
+Before creating files, show complete content:
+
+📝 **Preview**: Create UserProfile component
+
+**File**: `src/components/UserProfile.tsx` (new file)
+
+**Content**:
+```typescript
+import React from 'react';
+
+interface UserProfileProps {
+  name: string;
+  email: string;
+  avatarUrl?: string;
+}
+
+export const UserProfile: React.FC<UserProfileProps> = ({
+  name,
+  email,
+  avatarUrl
+}) => {
+  return (
+    <div className="user-profile">
+      {avatarUrl && <img src={avatarUrl} alt={name} />}
+      <h2>{name}</h2>
+      <p>{email}</p>
+    </div>
+  );
+};
+```
+
+**Features**:
+- TypeScript with proper interface
+- Optional avatar support
+- Accessible img alt text
+- Clean, minimal styling hooks
+
+Creating file...
+```
+
+### v0 (Multi-File Preview)
+```markdown
+## Preview Policy: Multiple File Generation
+
+Before creating multiple files, show structure and key content:
+
+📝 **Preview**: Generate authentication system
+
+**Files to Create**:
+1. `src/lib/auth.ts` - Auth utilities (45 lines)
+2. `src/app/login/page.tsx` - Login page (80 lines)
+3. `src/app/signup/page.tsx` - Signup page (75 lines)
+4. `src/middleware.ts` - Route protection (20 lines)
+
+**Key Sections**:
+
+**auth.ts**:
+```typescript
+export async function hashPassword(password: string): Promise<string> { /*...*/ }
+export async function verifyPassword(password: string, hash: string): Promise<boolean> { /*...*/ }
+export async function createSession(userId: string): Promise<string> { /*...*/ }
+```
+
+**login/page.tsx**:
+```typescript
+export default function LoginPage() {
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  // ... form handling
+}
+```
+
+**Structure**:
+- Uses bcrypt for password hashing
+- JWT for session tokens
+- Server Actions for form submission
+- Protected routes via middleware
+
+Proceed with generation?
+```
+
+## Variables
+- `{OPERATION_NAME}`: What you're doing (e.g., "Update import path")
+- `{FILE_PATH}`: Absolute or relative path
+- `{START_LINE}` / `{END_LINE}`: Line range
+- `{LANGUAGE}`: Syntax highlighting language
+- `{OLD_CODE}`: Current file contents
+- `{NEW_CODE}`: Proposed changes
+- `{CHANGE_DESCRIPTION_X}`: Plain English explanation
+
+## Best Practices
+1. Show preview for:
+   - All file edits (even single-line changes)
+   - New file creation (show full content if <100 lines)
+   - File deletion (show what's being removed)
+   - Terminal commands with side effects
+2. Use syntax highlighting (```typescript, ```python, etc.)
+3. Include context lines (3-5 lines above/below change)
+4. Explain *why* change is needed, not just *what* changed
+5. For large files (>100 lines), show key sections + summary
+6. For multiple files, prioritize most critical/complex
+7. Benefits: Catches mistakes before execution, educates user, builds confidence

package/dist/patterns/reasoning/reflection-checkpoints.md

@@ -0,0 +1,166 @@
+# Reflection Checkpoints Pattern
+
+## Purpose
+Periodically evaluate progress and adjust strategy. From **Claude** and **Bolt.new** patterns.
+
+## Template
+
+```markdown
+## Reflection Checkpoints
+
+After every {N} iterations or {MILESTONE}, pause and reflect:
+
+### Progress Check
+- **What have we accomplished?** {LIST_COMPLETED_TASKS}
+- **What's remaining?** {LIST_PENDING_TASKS}
+- **Are we on track?** {YES_NO_AND_WHY}
+
+### Quality Check
+- **Does output meet requirements?** {VERIFY_AGAINST_SPECS}
+- **Are there obvious issues?** {BUGS_PERFORMANCE_STYLE}
+- **Is code/design idiomatic?** {FOLLOWS_BEST_PRACTICES}
+
+### Strategy Check
+- **Is current approach working?** {ASSESS_EFFECTIVENESS}
+- **Should we change tactics?** {ALTERNATIVE_APPROACHES}
+- **Do we need clarification?** {QUESTIONS_FOR_USER}
+
+### Decision
+- ✅ **Continue**: Current approach is effective
+- 🔄 **Adjust**: Modify strategy based on learnings
+- ❓ **Clarify**: Ask user for guidance
+- ⛔ **Stop**: Goal achieved or insurmountable blocker
+```
+
+## Examples
+
+### Claude (Long Conversation Reflection)
+```markdown
+## Reflection Checkpoints: Complex Refactoring
+
+After every 5 tool calls, pause and reflect:
+
+### Progress Check (After Iteration 5)
+- **What have we accomplished?**
+  - ✅ Identified 12 files needing refactoring
+  - ✅ Extracted common utility functions
+  - ✅ Created new shared module
+  
+- **What's remaining?**
+  - ⏳ Update imports in 8 consumer files
+  - ⏳ Write tests for new utilities
+  - ⏳ Remove duplicated code
+  
+- **Are we on track?**
+  - Yes, 40% complete, no major blockers
+
+### Quality Check
+- **Does output meet requirements?**
+  - New utilities are well-typed ✅
+  - Functions are properly documented ✅
+  
+- **Are there obvious issues?**
+  - No error handling in two functions ⚠️
+  - Missing input validation ⚠️
+  
+- **Is code idiomatic?**
+  - Follows TypeScript best practices ✅
+  - Consistent naming conventions ✅
+
+### Strategy Check
+- **Is current approach working?**
+  - Yes, incremental refactoring is safe and testable
+  
+- **Should we change tactics?**
+  - Add error handling before updating consumers
+  - Write tests now (easier with isolated utilities)
+  
+- **Do we need clarification?**
+  - Should we maintain backward compatibility?
+  - Preferred error handling strategy?
+
+### Decision
+- 🔄 **Adjust**: Add error handling and tests before proceeding
+  - Next 5 iterations: Focus on robustness
+  - Then continue with consumer updates
+```
+
+### Bolt.new (Build Pipeline Reflection)
+```markdown
+## Reflection Checkpoints: Full-Stack App Creation
+
+After each major milestone, pause and reflect:
+
+### Progress Check (After Database Setup)
+- **What have we accomplished?**
+  - ✅ Prisma schema defined
+  - ✅ Migrations run successfully
+  - ✅ Database seeded with test data
+  
+- **What's remaining?**
+  - ⏳ API routes for CRUD operations
+  - ⏳ Frontend components
+  - ⏳ Authentication integration
+  
+- **Are we on track?**
+  - Yes, 25% complete (1 of 4 phases done)
+
+### Quality Check
+- **Does output meet requirements?**
+  - Schema matches user's data model ✅
+  - Relationships properly defined ✅
+  
+- **Are there obvious issues?**
+  - No indexes on frequently queried fields ⚠️
+  - Missing cascade deletes on relationships ⚠️
+  
+- **Is code/design idiomatic?**
+  - Follows Prisma naming conventions ✅
+  - Uses appropriate field types ✅
+
+### Strategy Check
+- **Is current approach working?**
+  - Yes, schema-first design enables type-safe API
+  
+- **Should we change tactics?**
+  - Add indexes before building API (prevents performance issues)
+  - Use `onDelete: Cascade` for parent-child relationships
+  
+- **Do we need clarification?**
+  - Which fields will be most queried? (to optimize indexes)
+  - Should soft deletes be used instead of hard deletes?
+
+### Decision
+- 🔄 **Adjust**: Optimize schema before building API
+  - Add indexes on user_id, created_at
+  - Add cascade deletes on comment relationships
+  - Then proceed to API routes phase
+```
+
+## Variables
+- `{N}`: Number of iterations between checkpoints (e.g., 5, 10)
+- `{MILESTONE}`: Significant completion point (e.g., "after database setup")
+- `{LIST_COMPLETED_TASKS}`: Enumeration with ✅
+- `{LIST_PENDING_TASKS}`: Enumeration with ⏳
+- `{YES_NO_AND_WHY}`: Assessment with reasoning
+- `{VERIFY_AGAINST_SPECS}`: Compare to requirements
+- `{BUGS_PERFORMANCE_STYLE}`: Common quality issues
+- `{FOLLOWS_BEST_PRACTICES}`: Idiomatic code check
+- `{ASSESS_EFFECTIVENESS}`: Is strategy working?
+- `{ALTERNATIVE_APPROACHES}`: Other options to consider
+- `{QUESTIONS_FOR_USER}`: What to clarify
+
+## Best Practices
+1. Set checkpoint frequency based on task complexity (5-10 iterations)
+2. Use checkpoints at natural milestones (after component, API, test suite)
+3. Be honest about issues (don't hide problems until later)
+4. Adjust strategy based on findings (not just report)
+5. Ask user questions when uncertain (don't guess)
+6. Document decisions (why you adjusted or continued)
+7. Benefits: Catches issues early, prevents wasted work, maintains quality
+
+## Implementation Notes
+- Can be explicit (show user reflection) or implicit (internal reasoning)
+- Combine with thinking tags for transparent reasoning
+- Especially valuable for long-running tasks (>10 iterations)
+- Helps models avoid "tunnel vision" (blindly following initial plan)

package/dist/patterns/reasoning/result-verification.md

@@ -0,0 +1,157 @@
+# Result Verification Pattern
+
+## Purpose
+Validate tool outputs and check for errors after execution. From **Manus** and **Bolt.new** patterns.
+
+## Template
+
+```markdown
+## Result Verification
+
+After every tool call, verify the outcome:
+
+### 1. Check Status
+- **Success?** {DID_TOOL_COMPLETE_SUCCESSFULLY}
+- **Error?** {PARSE_ERROR_MESSAGE_IF_FAILED}
+
+### 2. Validate Output
+- **Expected?** {DOES_OUTPUT_MATCH_EXPECTATIONS}
+- **Complete?** {IS_ALL_REQUIRED_DATA_PRESENT}
+- **Correct?** {SPOT_CHECK_VALUES_OR_CONTENT}
+
+### 3. Handle Issues
+If verification fails:
+- **Retry**: {SAME_OPERATION_WITH_ADJUSTED_PARAMS}
+- **Fallback**: {ALTERNATIVE_APPROACH}
+- **Escalate**: {ASK_USER_FOR_HELP}
+
+### 4. Update State
+- **Record**: {SAVE_RELEVANT_DATA_FOR_NEXT_ITERATION}
+- **Track**: {UPDATE_PROGRESS_MARKERS}
+- **Learn**: {NOTE_PATTERNS_FOR_FUTURE_CALLS}
+```
+
+## Examples
+
+### Manus (File Read Verification)
+```markdown
+## Result Verification: Read File
+
+After reading file, verify the outcome:
+
+**Tool Call**:
+```
+read_file({ path: "src/app.ts", startLine: 1, endLine: 50 })
+```
+
+### 1. Check Status
+- **Success?** ✅ Tool returned 200 OK
+- **Error?** None
+
+### 2. Validate Output
+- **Expected?** ✅ File contains TypeScript code
+- **Complete?** ⚠️ File is 150 lines, only got first 50
+- **Correct?** ✅ Spot check: imports at top, export at bottom
+
+### 3. Handle Issues
+- **Issue**: Need more context (file is longer than expected)
+- **Action**: Read lines 50-150 in next iteration
+- **Record**: Note that app.ts is 150 lines total
+
+### 4. Update State
+- **Record**: app.ts imports from './config' and './utils'
+- **Track**: File analysis: 33% complete (1 of 3 files read fully)
+- **Learn**: Large files need multiple read calls
+```
+
+### Bolt.new (Build Command Verification)
+```markdown
+## Result Verification: Run Build
+
+After running build command, verify the outcome:
+
+**Tool Call**:
+```
+run_terminal({ command: "npm run build" })
+```
+
+### 1. Check Status
+- **Success?** ❌ Exit code: 1 (failure)
+- **Error?** "Module not found: Can't resolve '@/lib/utils'"
+
+### 2. Validate Output
+- **Expected?** ❌ Expected successful build
+- **Complete?** N/A (build failed)
+- **Correct?** N/A (error message is the output)
+
+### 3. Handle Issues
+- **Issue**: Module resolution error
+- **Root Cause**: Path alias (@/) not configured in tsconfig.json
+- **Action**: 
+  1. Read tsconfig.json to verify paths config
+  2. If missing, add paths: { "@/*": ["./src/*"] }
+  3. Retry build command
+
+### 4. Update State
+- **Record**: Build failed due to missing path alias
+- **Track**: Build attempt 1/3 failed, trying fix
+- **Learn**: Always verify tsconfig before using path aliases
+```
+
+### same.new (Component Generation Verification)
+```markdown
+## Result Verification: Create Component
+
+After creating component file, verify the outcome:
+
+**Tool Call**:
+```
+create_file({ path: "src/components/Button.tsx", content: "..." })
+```
+
+### 1. Check Status
+- **Success?** ✅ File created
+- **Error?** None
+
+### 2. Validate Output
+- **Expected?** ✅ File exists at specified path
+- **Complete?** ✅ Full component code written
+- **Correct?** 
+  - ✅ Has TypeScript interface
+  - ✅ Uses React.FC type
+  - ✅ Has proper exports
+  - ⚠️ Missing aria-label for accessibility
+
+### 3. Handle Issues
+- **Issue**: Missing accessibility attribute
+- **Action**: Edit file to add aria-label prop and usage
+- **Don't Create New**: Modify existing file instead
+
+### 4. Update State
+- **Record**: Button.tsx created, needs accessibility fix
+- **Track**: Component generation: 90% complete (add a11y)
+- **Learn**: Include aria attributes in initial generation
+```
+
+## Variables
+- `{DID_TOOL_COMPLETE_SUCCESSFULLY}`: Boolean + status code
+- `{PARSE_ERROR_MESSAGE_IF_FAILED}`: Extract meaningful error
+- `{DOES_OUTPUT_MATCH_EXPECTATIONS}`: Compare to intent
+- `{IS_ALL_REQUIRED_DATA_PRESENT}`: Completeness check
+- `{SPOT_CHECK_VALUES_OR_CONTENT}`: Validate sample data
+- `{SAME_OPERATION_WITH_ADJUSTED_PARAMS}`: Retry with fixes
+- `{ALTERNATIVE_APPROACH}`: Different tool or method
+- `{ASK_USER_FOR_HELP}`: When stuck or uncertain
+- `{SAVE_RELEVANT_DATA_FOR_NEXT_ITERATION}`: State updates
+- `{UPDATE_PROGRESS_MARKERS}`: Track completion
+- `{NOTE_PATTERNS_FOR_FUTURE_CALLS}`: Learning
+
+## Best Practices
+1. **Always** check tool return status (don't assume success)
+2. Parse error messages (extract actionable information)
+3. Validate output structure (not just success boolean)
+4. Spot-check content (random sampling for large outputs)
+5. Implement retry logic (up to 3 attempts with backoff)
+6. Fall back gracefully (alternative tools or manual steps)
+7. Update mental model (learn from successes and failures)
+8. Benefits: Robust execution, early error detection, self-correction, adaptive behavior

package/dist/patterns/reasoning/subtask-breakdown.md

@@ -0,0 +1,131 @@
+# Subtask Breakdown Pattern
+
+## Purpose
+Decompose complex requests into manageable steps. From **Manus** and **Bolt.new** patterns.
+
+## Template
+
+```markdown
+When faced with a complex task, break it down:
+
+## Task: {MAIN_GOAL}
+
+### Subtasks:
+1. {SUBTASK_1}
+   - Input: {WHAT_YOU_NEED}
+   - Output: {WHAT_YOU_PRODUCE}
+   - Depends on: {PREREQUISITES}
+
+2. {SUBTASK_2}
+   - Input: {WHAT_YOU_NEED}
+   - Output: {WHAT_YOU_PRODUCE}
+   - Depends on: {PREREQUISITES}
+
+3. {SUBTASK_3}
+   - Input: {WHAT_YOU_NEED}
+   - Output: {WHAT_YOU_PRODUCE}
+   - Depends on: {PREREQUISITES}
+
+### Execution Order:
+{WHICH_CAN_RUN_IN_PARALLEL}, {WHICH_MUST_BE_SEQUENTIAL}
+```
+
+## Examples
+
+### Bolt.new (Full-Stack App Creation)
+```markdown
+When creating a new application, break it down:
+
+## Task: Create a Next.js blog with authentication
+
+### Subtasks:
+1. **Initialize Project Structure**
+   - Input: Framework choice (Next.js), styling (Tailwind)
+   - Output: package.json, tsconfig.json, basic file structure
+   - Depends on: Nothing (can start immediately)
+
+2. **Set Up Database Schema**
+   - Input: Data models (User, Post, Comment)
+   - Output: Prisma schema, migrations
+   - Depends on: Project structure
+
+3. **Implement Authentication**
+   - Input: Auth provider (NextAuth.js), database schema
+   - Output: Login/signup pages, session management
+   - Depends on: Database schema
+
+4. **Build Blog Features**
+   - Input: Post CRUD operations, authentication
+   - Output: Create/edit/delete post UI, public blog pages
+   - Depends on: Authentication
+
+5. **Add Styling and Polish**
+   - Input: Component library (shadcn/ui), design tokens
+   - Output: Consistent UI, responsive design
+   - Depends on: Blog features (can run in parallel with testing)
+
+### Execution Order:
+- Sequential: 1 → 2 → 3 → 4
+- Parallel: 5 (styling) can happen alongside 4 (features)
+```
+
+### Manus (Debugging Workflow)
+```markdown
+When debugging an error, break it down:
+
+## Task: Fix "Module not found" error in React app
+
+### Subtasks:
+1. **Locate Error Source**
+   - Input: Error message, stack trace
+   - Output: File path and line number of import
+   - Depends on: Nothing
+
+2. **Verify Module Exists**
+   - Input: Import statement, project file structure
+   - Output: Confirmation if module exists or is missing
+   - Depends on: Error location
+
+3. **Check Import Path**
+   - Input: Relative vs absolute path, tsconfig paths
+   - Output: Correct import syntax
+   - Depends on: Module verification
+
+4. **Install Missing Package** (if needed)
+   - Input: Package name, package manager (npm/yarn/pnpm)
+   - Output: Updated package.json, node_modules
+   - Depends on: Module not existing in project
+
+5. **Verify Fix**
+   - Input: Updated import, build command
+   - Output: Successful build or new error
+   - Depends on: Import correction or package installation
+
+### Execution Order:
+- Sequential: 1 → 2 → (3 OR 4) → 5
+- Branch: If module exists (3), else (4)
+```
+
+## Variables
+- `{MAIN_GOAL}`: High-level objective
+- `{SUBTASK_X}`: Concrete, achievable step
+- `{WHAT_YOU_NEED}`: Required inputs/context
+- `{WHAT_YOU_PRODUCE}`: Expected output/deliverable
+- `{PREREQUISITES}`: Dependencies (other subtasks or external factors)
+- `{WHICH_CAN_RUN_IN_PARALLEL}`: Independent subtasks
+- `{WHICH_MUST_BE_SEQUENTIAL}`: Dependent subtasks
+
+## Best Practices
+1. Keep subtasks small (completable in 1-3 tool calls)
+2. Make dependencies explicit (enables parallelization)
+3. Identify inputs/outputs for each step (validates completeness)
+4. Number subtasks for easy reference
+5. Show alternative paths (if/else branches)
+6. Estimate complexity (simple/medium/complex)
+7. Benefits: Enables progress tracking, reveals missing steps, improves estimation
+
+## Implementation Notes
+- Use this pattern for tasks requiring >3 distinct operations
+- Can be combined with thinking tags (plan subtasks in <thinking>)
+- Update subtask status as you progress (✓ completed, ⏳ in progress)
+- Re-evaluate after each subtask (dependencies may change)