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

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

@@ -1,151 +0,0 @@
-# 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/default_templates/patterns/reasoning/confirmation-gates.md

@@ -1,141 +0,0 @@
-# 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/default_templates/patterns/reasoning/dependency-analysis.md

@@ -1,132 +0,0 @@
-# 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/default_templates/patterns/reasoning/one-tool-per-iteration.md

@@ -1,152 +0,0 @@
-# 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