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

package/dist/patterns/reasoning/agent-loop.md

@@ -0,0 +1,151 @@
+# Agent Loop Pattern
+
+## Purpose
+Define iterative execution cycle for autonomous agents. From **Manus** pattern.
+
+## Template
+
+```markdown
+## Agent Execution Loop
+
+Repeat the following cycle until goal is achieved:
+
+### 1. Observe
+- Read current state: {WHAT_TO_CHECK}
+- Identify changes: {WHAT_CHANGED_SINCE_LAST_ITERATION}
+- Note user input: {NEW_REQUIREMENTS_OR_FEEDBACK}
+
+### 2. Orient
+- Assess progress: {HOW_CLOSE_TO_GOAL}
+- Identify blockers: {WHAT_IS_PREVENTING_COMPLETION}
+- Update plan: {ADJUST_STRATEGY_IF_NEEDED}
+
+### 3. Decide
+- Select next action: {WHICH_TOOL_OR_OPERATION}
+- Validate feasibility: {CAN_THIS_ACTION_SUCCEED}
+- Prepare parameters: {GATHER_REQUIRED_INPUTS}
+
+### 4. Act
+- Execute selected action: {CALL_TOOL_OR_PERFORM_OPERATION}
+- Capture results: {STORE_OUTPUT_FOR_NEXT_ITERATION}
+- Handle errors: {RETRY_OR_FALLBACK_IF_FAILED}
+
+### 5. Reflect
+- Evaluate outcome: {DID_ACTION_ACHIEVE_INTENDED_EFFECT}
+- Learn from result: {UPDATE_KNOWLEDGE_OR_ASSUMPTIONS}
+- Decide continuation: {REPEAT_LOOP_OR_TERMINATE}
+
+**Termination Conditions**:
+- Goal achieved: {SUCCESS_CRITERIA_MET}
+- Unrecoverable error: {CANNOT_PROCEED_FURTHER}
+- Max iterations reached: {SAFETY_LIMIT_HIT}
+- User interruption: {USER_REQUESTED_STOP}
+```
+
+## Examples
+
+### Manus (Code Debugging Loop)
+```markdown
+## Agent Execution Loop: Debug and Fix Error
+
+Repeat the following cycle until error is resolved:
+
+### 1. Observe
+- Read current state: Error message, stack trace, failed test output
+- Identify changes: What code was just modified?
+- Note user input: Any hints or context provided?
+
+### 2. Orient
+- Assess progress: Is error message clearer than before?
+- Identify blockers: Missing dependencies? Syntax errors? Logic bugs?
+- Update plan: Do we need to install packages, fix imports, or rewrite logic?
+
+### 3. Decide
+- Select next action: Read error source file, check imports, run tests
+- Validate feasibility: Do we have file path? Are tools available?
+- Prepare parameters: File path, line numbers, test command
+
+### 4. Act
+- Execute selected action: `read_file(errorFile, errorLine-5, errorLine+5)`
+- Capture results: Store file contents, understand context
+- Handle errors: If file not found, search for similar files
+
+### 5. Reflect
+- Evaluate outcome: Does file content reveal the issue?
+- Learn from result: Update mental model of codebase
+- Decide continuation: If root cause found, apply fix; else investigate deeper
+
+**Termination Conditions**:
+- Goal achieved: Tests pass, error no longer occurs
+- Unrecoverable error: Required file deleted, system-level issue
+- Max iterations reached: 10 loops without progress (escalate to user)
+- User interruption: User provides new direction or cancels
+```
+
+### same.new (Feature Implementation Loop)
+```markdown
+## Agent Execution Loop: Build Feature
+
+Repeat the following cycle until feature is complete:
+
+### 1. Observe
+- Read current state: Existing components, dependencies, file structure
+- Identify changes: What was just created/modified?
+- Note user input: Feature requirements, design preferences
+
+### 2. Orient
+- Assess progress: Which components are done? What's remaining?
+- Identify blockers: Missing libraries? Unclear requirements?
+- Update plan: Break feature into smaller components if needed
+
+### 3. Decide
+- Select next action: Create component, install package, write test
+- Validate feasibility: Do we have design? Dependencies available?
+- Prepare parameters: Component name, props, styling approach
+
+### 4. Act
+- Execute selected action: `create_file(ComponentName.tsx, content)`
+- Capture results: Store component path for imports
+- Handle errors: If file exists, modify instead of create
+
+### 5. Reflect
+- Evaluate outcome: Does component match requirements?
+- Learn from result: Note patterns for similar components
+- Decide continuation: If feature incomplete, build next piece; else finalize
+
+**Termination Conditions**:
+- Goal achieved: Feature works, tests pass, user approves
+- Unrecoverable error: Conflicting requirements, impossible constraints
+- Max iterations reached: 20 loops (feature too complex, break down further)
+- User interruption: User requests changes or different feature
+```
+
+## Variables
+- `{WHAT_TO_CHECK}`: State to examine each iteration
+- `{WHAT_CHANGED_SINCE_LAST_ITERATION}`: Delta from previous cycle
+- `{NEW_REQUIREMENTS_OR_FEEDBACK}`: User input to incorporate
+- `{HOW_CLOSE_TO_GOAL}`: Progress measurement
+- `{WHAT_IS_PREVENTING_COMPLETION}`: Blockers/dependencies
+- `{ADJUST_STRATEGY_IF_NEEDED}`: Plan modifications
+- `{WHICH_TOOL_OR_OPERATION}`: Next action to take
+- `{CAN_THIS_ACTION_SUCCEED}`: Feasibility check
+- `{GATHER_REQUIRED_INPUTS}`: Parameter preparation
+- `{CALL_TOOL_OR_PERFORM_OPERATION}`: Execution step
+- `{STORE_OUTPUT_FOR_NEXT_ITERATION}`: Result capture
+- `{RETRY_OR_FALLBACK_IF_FAILED}`: Error handling
+- `{DID_ACTION_ACHIEVE_INTENDED_EFFECT}`: Outcome evaluation
+- `{UPDATE_KNOWLEDGE_OR_ASSUMPTIONS}`: Learning
+- `{REPEAT_LOOP_OR_TERMINATE}`: Continuation decision
+- `{SUCCESS_CRITERIA_MET}`: Goal achieved condition
+- `{CANNOT_PROCEED_FURTHER}`: Unrecoverable error condition
+- `{SAFETY_LIMIT_HIT}`: Max iterations condition
+- `{USER_REQUESTED_STOP}`: User interruption condition
+
+## Best Practices
+1. Use OODA framework (Observe, Orient, Decide, Act) + Reflect
+2. One tool call per iteration (no parallel in loop)
+3. State termination conditions explicitly
+4. Include safety limit (max iterations)
+5. Capture learnings between iterations
+6. Allow user interruption at any point
+7. Benefits: Autonomous operation, adaptability, progress tracking, safety bounds

package/dist/patterns/reasoning/confirmation-gates.md

@@ -0,0 +1,141 @@
+# Confirmation Gates Pattern
+
+## Purpose
+Require user approval before destructive or high-impact operations. From **same.new** and **Cline** patterns.
+
+## Template
+
+```markdown
+## Confirmation Gates
+
+Before executing {OPERATION_TYPE}, show preview and wait for approval:
+
+### Operations Requiring Confirmation
+- **File Deletion**: {LIST_FILES_TO_DELETE}
+- **Overwrite**: {SHOW_DIFF_OLD_VS_NEW}
+- **Bulk Changes**: {SUMMARIZE_SCOPE_AND_IMPACT}
+- **Destructive Commands**: {EXPLAIN_WHAT_WILL_BE_LOST}
+
+### Confirmation Format
+```
+⚠️ **Confirmation Required**
+
+**Operation**: {OPERATION_NAME}
+**Impact**: {WHAT_WILL_CHANGE}
+**Files Affected**: {COUNT_AND_LIST}
+
+**Preview**:
+{SHOW_BEFORE_AFTER_OR_DIFF}
+
+Proceed? (yes/no)
+```
+```
+
+## Examples
+
+### same.new (File Overwrite)
+```markdown
+## Confirmation Gates: File Operations
+
+Before overwriting existing files, show diff and wait for approval:
+
+⚠️ **Confirmation Required**
+
+**Operation**: Overwrite `src/components/Button.tsx`
+**Impact**: Existing component will be replaced
+**Files Affected**: 1 file
+
+**Preview (diff)**:
+```diff
+- export const Button = ({ label }: ButtonProps) => {
+-   return <button className="btn">{label}</button>;
++ export const Button = ({ children, variant = 'primary' }: ButtonProps) => {
++   return <button className={`btn btn-${variant}`}>{children}</button>;
+  };
+```
+
+**Risk Assessment**:
+- ✅ TypeScript types will catch breaking changes
+- ⚠️ Existing usages with `label` prop will need updates
+- ℹ️ Found 8 files importing this component
+
+Proceed? (yes/no)
+```
+
+### Cline (Bulk Deletion)
+```markdown
+## Confirmation Gates: Destructive Operations
+
+Before deleting multiple files, show impact and wait for approval:
+
+⚠️ **Confirmation Required**
+
+**Operation**: Delete unused test fixtures
+**Impact**: 12 files will be permanently deleted
+**Files Affected**:
+- tests/fixtures/user-data.json
+- tests/fixtures/product-catalog.json
+- tests/fixtures/old-api-response.json
+- ... (9 more files)
+
+**Risk Assessment**:
+- ⚠️ **WARNING**: This cannot be undone unless files are in git
+- ✅ Git status: All files committed (can recover from history)
+- ℹ️ These files are not referenced in any test files
+
+**Recommended Action**: Review list carefully before confirming
+
+Proceed? (yes/no)
+```
+
+### ChatGPT (Credential Exposure)
+```markdown
+## Confirmation Gates: Security Risk
+
+Before generating code with sensitive data, warn and request confirmation:
+
+⚠️ **Confirmation Required**
+
+**Operation**: Generate API client with authentication
+**Impact**: Code will include authentication logic
+**Security Risk**: HIGH
+
+**Warning**:
+- ❌ NEVER hardcode API keys in code
+- ❌ NEVER commit credentials to git
+- ✅ Use environment variables (.env file)
+- ✅ Add .env to .gitignore
+
+**Proposed Implementation**:
+```typescript
+const apiKey = process.env.API_KEY; // ✅ From environment
+// NOT: const apiKey = 'sk-abc123...'; // ❌ Hardcoded
+```
+
+I will generate code using environment variables. Proceed? (yes/no)
+```
+
+## Variables
+- `{OPERATION_TYPE}`: Category of operation (delete, overwrite, bulk edit)
+- `{LIST_FILES_TO_DELETE}`: Affected file paths
+- `{SHOW_DIFF_OLD_VS_NEW}`: Side-by-side or unified diff
+- `{SUMMARIZE_SCOPE_AND_IMPACT}`: How many files, what changes
+- `{EXPLAIN_WHAT_WILL_BE_LOST}`: Data that can't be recovered
+- `{OPERATION_NAME}`: Specific action (e.g., "Delete 12 test fixtures")
+- `{WHAT_WILL_CHANGE}`: User-facing description
+- `{COUNT_AND_LIST}`: Number and paths
+- `{SHOW_BEFORE_AFTER_OR_DIFF}`: Visual comparison
+
+## Best Practices
+1. Always show confirmation for:
+   - File/directory deletion
+   - Overwriting existing files (unless explicitly replacing)
+   - Running commands with sudo/admin privileges
+   - Exposing credentials or secrets
+   - Bulk operations (>5 files)
+2. Include risk assessment (✅ safe, ⚠️ warning, ❌ danger)
+3. Explain what can't be undone vs. what's recoverable
+4. Show concrete preview (diff, file list, command output)
+5. Suggest safer alternatives when applicable
+6. Wait for explicit "yes" (don't proceed on silence)
+7. Benefits: Prevents accidents, builds trust, surfaces unintended consequences

package/dist/patterns/reasoning/dependency-analysis.md

@@ -0,0 +1,132 @@
+# Dependency Analysis Pattern
+
+## Purpose
+Identify prerequisites, conflicts, and ordering constraints. From **Bolt.new** and **same.new** patterns.
+
+## Template
+
+```markdown
+## Dependency Analysis
+
+### Direct Dependencies
+- {COMPONENT_A} requires {COMPONENT_B}
+- {COMPONENT_C} requires {COMPONENT_D}
+
+### Transitive Dependencies
+- {COMPONENT_A} → {COMPONENT_B} → {COMPONENT_E}
+
+### Conflicts
+- {PACKAGE_X} v{VERSION_1} conflicts with {PACKAGE_Y} v{VERSION_2}
+- Resolution: {HOW_TO_RESOLVE}
+
+### Execution Order
+```mermaid
+graph TD
+  A[{TASK_A}] --> B[{TASK_B}]
+  A --> C[{TASK_C}]
+  B --> D[{TASK_D}]
+  C --> D
+```
+```
+
+## Examples
+
+### Bolt.new (Package Dependencies)
+```markdown
+## Dependency Analysis: Adding Prisma ORM
+
+### Direct Dependencies
+- Prisma Client requires `@prisma/client` package
+- Prisma CLI requires `prisma` as dev dependency
+- Database adapter requires PostgreSQL client
+
+### Transitive Dependencies
+- `@prisma/client` → database driver (pg, mysql2, etc.)
+- Prisma CLI → Node.js runtime (>= 16.13.0)
+- Database migrations → existing database connection
+
+### Conflicts
+- `@prisma/client` v5.x conflicts with Next.js v12 (uses CommonJS)
+- Resolution: Upgrade to Next.js v13+ (supports ESM) or use Prisma v4.x
+
+### Installation Order
+1. Install Prisma CLI (`npm i -D prisma`)
+2. Initialize Prisma (`npx prisma init`)
+3. Define schema (`schema.prisma`)
+4. Run migrations (`npx prisma migrate dev`)
+5. Install client (`npm i @prisma/client`)
+6. Generate client (`npx prisma generate`)
+
+### Why This Order?
+- CLI needed before `init` command
+- Schema must exist before migrations
+- Migrations create database tables
+- Client generated from schema
+```
+
+### same.new (Component Dependencies)
+```markdown
+## Dependency Analysis: Building Dashboard Layout
+
+### Direct Dependencies
+- `Dashboard` requires `Sidebar` component
+- `Dashboard` requires `TopNav` component
+- `Sidebar` requires `NavLink` component
+- `TopNav` requires `UserMenu` component
+
+### Transitive Dependencies
+- `Dashboard` → `Sidebar` → `NavLink` → `Icon` component
+- `Dashboard` → `TopNav` → `UserMenu` → `Avatar` component
+- All components → `ThemeProvider` context
+
+### Conflicts
+- `Sidebar` uses fixed positioning (overlaps main content on mobile)
+- `TopNav` uses sticky positioning (z-index conflict with modals)
+- Resolution: Establish z-index scale (nav: 100, sidebar: 200, modal: 1000)
+
+### Build Order
+```mermaid
+graph TD
+  A[Icon] --> B[NavLink]
+  C[Avatar] --> D[UserMenu]
+  B --> E[Sidebar]
+  D --> F[TopNav]
+  E --> G[Dashboard]
+  F --> G
+  H[ThemeProvider] --> G
+```
+
+1. Build leaf components (`Icon`, `Avatar`)
+2. Build composed components (`NavLink`, `UserMenu`)
+3. Build layout sections (`Sidebar`, `TopNav`)
+4. Build container (`Dashboard`)
+5. Wrap in `ThemeProvider`
+
+### Why This Order?
+- Leaf components have no dependencies (can build first)
+- Composed components need leaf components (build after)
+- Layout sections need composed components (build after)
+- Container orchestrates sections (build last)
+- Provider wraps everything (applied at root)
+```
+
+## Variables
+- `{COMPONENT_X}`: Module, package, or component
+- `{VERSION_X}`: Specific version number
+- `{TASK_X}`: Operation or build step
+- `{HOW_TO_RESOLVE}`: Conflict resolution strategy
+
+## Best Practices
+1. Distinguish direct vs transitive dependencies
+2. Identify circular dependencies early (impossible to resolve)
+3. Document version constraints (>=, ^, ~)
+4. Explain *why* order matters (not just *what* order)
+5. Visualize complex dependency graphs (Mermaid, ASCII)
+6. Plan for missing dependencies (install, create, mock)
+7. Benefits: Prevents build failures, enables parallel work, surfaces conflicts early
+
+## Implementation Notes
+- Run dependency analysis before starting multi-component builds
+- Update analysis when adding new dependencies
+- Use package manager output to verify constraints (`npm ls`, `pnpm why`)
+- Check for peer dependency warnings (often indicate conflicts)

package/dist/patterns/reasoning/one-tool-per-iteration.md

@@ -0,0 +1,152 @@
+# One Tool Per Iteration Pattern
+
+## Purpose
+Enforce sequential tool usage to maintain state consistency. From **Manus** and **Cline** patterns.
+
+## Template
+
+```markdown
+## Tool Execution Policy
+
+Execute tools sequentially, one per iteration:
+
+1. **Select One Tool**: Choose single tool based on current state
+2. **Gather Parameters**: Collect all required inputs for that tool
+3. **Execute**: Call the tool and wait for completion
+4. **Process Results**: Analyze output before next action
+5. **Repeat**: Select next tool based on new state
+
+**Never**:
+- Call multiple tools in parallel within the agent loop
+- Assume tool output without checking
+- Chain tools without validating intermediate results
+```
+
+## Examples
+
+### Manus (File Analysis)
+```markdown
+## Tool Execution Policy: Analyze Codebase
+
+Execute tools sequentially, one per iteration:
+
+**Iteration 1**: Search for files
+```
+tool: file_search
+params: { pattern: "**/*.ts" }
+result: [src/app.ts, src/utils.ts, src/config.ts]
+next_action: Read first file
+```
+
+**Iteration 2**: Read primary file
+```
+tool: read_file
+params: { path: "src/app.ts", startLine: 1, endLine: 100 }
+result: Contains import from "./utils"
+next_action: Read dependency
+```
+
+**Iteration 3**: Read dependency file
+```
+tool: read_file
+params: { path: "src/utils.ts", startLine: 1, endLine: 50 }
+result: Contains helper functions
+next_action: Analyze config
+```
+
+**Why Sequential?**
+- Iteration 2 revealed dependency on utils.ts (couldn't predict before iteration 1)
+- Iteration 3 needed based on imports found in iteration 2
+- Parallel calls would miss these dependencies
+```
+
+### Cline (Debugging Workflow)
+```markdown
+## Tool Execution Policy: Fix Runtime Error
+
+Execute tools sequentially, one per iteration:
+
+**Iteration 1**: Search for error in logs
+```
+tool: grep_search
+params: { query: "Error: Module not found", isRegexp: false }
+result: Found in src/components/Header.tsx line 5
+next_action: Read file with error
+```
+
+**Iteration 2**: Read file containing error
+```
+tool: read_file
+params: { path: "src/components/Header.tsx", startLine: 1, endLine: 20 }
+result: import { Button } from '@/components/ui/button'
+next_action: Check if file exists
+```
+
+**Iteration 3**: Verify imported file exists
+```
+tool: file_search
+params: { pattern: "**/ui/button.*" }
+result: src/components/ui/Button.tsx (capital B!)
+next_action: Fix import path
+```
+
+**Iteration 4**: Correct the import
+```
+tool: replace_string_in_file
+params: {
+  path: "src/components/Header.tsx",
+  oldString: "from '@/components/ui/button'",
+  newString: "from '@/components/ui/Button'"
+}
+result: File updated successfully
+next_action: Verify build passes
+```
+
+**Why Sequential?**
+- Couldn't identify file path until grep found it (iteration 1)
+- Couldn't determine fix until seeing actual import (iteration 2)
+- Couldn't know correct path until searching filesystem (iteration 3)
+- Each step informed the next action
+```
+
+## When to Break This Rule
+
+### Parallel Reads (Cline Exception)
+```markdown
+**Allowed**: Reading multiple independent files
+```
+tools: [
+  read_file({ path: "src/app.ts", startLine: 1, endLine: 50 }),
+  read_file({ path: "src/config.ts", startLine: 1, endLine: 30 }),
+  read_file({ path: "tests/app.test.ts", startLine: 1, endLine: 40 })
+]
+```
+
+**Why Allowed?**
+- Files are known to exist (from previous search)
+- No dependencies between reads
+- Just gathering context, not modifying state
+- Significantly faster than 3 sequential iterations
+
+**Not Allowed**: Reading files discovered during search
+- Risk: Files might not exist or might not contain expected content
+- Better: Read first file, validate, then read others if needed
+```
+
+## Variables
+- N/A (this is a process pattern, not a template)
+
+## Best Practices
+1. One tool call per iteration in agent loops
+2. Validate tool output before next call
+3. Exception: Parallel reads when files are pre-validated
+4. Never parallelize: writes, terminal commands, state-changing operations
+5. Use tool output to inform next tool selection
+6. Document why each tool was chosen (reasoning chain)
+7. Benefits: Predictable state, easier debugging, adaptive execution
+
+## Implementation Notes
+- Most models naturally follow this pattern
+- Explicitly state in system prompt to prevent parallel tool abuse
+- Useful for autonomous agents (Manus, Cline, Augment)
+- Less critical for user-directed agents (v0, same.new) where user provides guidance between steps