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

package/dist/patterns/reasoning/thinking-tags.md

@@ -0,0 +1,100 @@
+# Thinking Tags Pattern
+
+## Purpose
+Encourage explicit pre-action analysis and planning. From **v0** pattern.
+
+## Template
+
+```markdown
+Before executing any action, think through:
+
+<thinking>
+1. **Understand**: {WHAT_USER_WANTS}
+2. **Analyze**: {CURRENT_STATE_AND_CONSTRAINTS}
+3. **Plan**: {APPROACH_TO_TAKE}
+4. **Anticipate**: {POTENTIAL_ISSUES}
+</thinking>
+
+Then proceed with execution.
+```
+
+## Examples
+
+### v0 (Component Generation)
+```markdown
+Before generating code, think through the requirements:
+
+<thinking>
+1. **Understand**: What component is needed?
+   - Is this a new component or modification?
+   - What props/state does it need?
+   - What's the visual hierarchy?
+
+2. **Analyze**: What are the constraints?
+   - Framework: Next.js App Router or Pages?
+   - Styling: Tailwind, CSS modules, or styled-components?
+   - Dependencies: What libraries are available?
+
+3. **Plan**: What's the implementation approach?
+   - Component structure (parent/children)
+   - Data flow (props down, events up)
+   - File organization (co-located vs separate)
+
+4. **Anticipate**: What could go wrong?
+   - Missing types (add proper TypeScript interfaces)
+   - Accessibility issues (add ARIA labels)
+   - Responsive design (include breakpoints)
+</thinking>
+
+Then generate the component code.
+```
+
+### Manus (Tool Selection)
+```markdown
+Before calling a tool, analyze the situation:
+
+<thinking>
+1. **Understand**: What information do I need?
+   - What's the user's end goal?
+   - What data is missing?
+   - What assumptions am I making?
+
+2. **Analyze**: What tools are available?
+   - Which tool provides the needed information?
+   - Are there dependencies between tools?
+   - Can I gather everything in one call?
+
+3. **Plan**: What's the optimal tool sequence?
+   - Start with broad context (file search)
+   - Then narrow down (read specific files)
+   - Validate with targeted checks (grep for patterns)
+
+4. **Anticipate**: What if the tool fails?
+   - File doesn't exist → search for similar names
+   - Permission denied → check alternate paths
+   - Timeout → break into smaller operations
+</thinking>
+
+Then proceed with tool call.
+```
+
+## Variables
+- `{WHAT_USER_WANTS}`: Parsed intent from user message
+- `{CURRENT_STATE_AND_CONSTRAINTS}`: Known facts and limitations
+- `{APPROACH_TO_TAKE}`: High-level strategy
+- `{POTENTIAL_ISSUES}`: Risk assessment
+
+## Best Practices
+1. Use `<thinking>` tags to separate planning from execution
+2. Keep each section concise (2-4 bullet points)
+3. Ask questions to surface uncertainties
+4. Reference specific context (files, variables, constraints)
+5. State assumptions explicitly
+6. Consider failure modes and fallbacks
+7. Benefits: Reduces errors, improves reasoning transparency, enables self-correction
+
+## Implementation Notes
+- Some models (Claude, GPT-4) benefit from explicit thinking sections
+- Can be hidden from user output (system-level reasoning)
+- Useful for complex tasks (code generation, debugging, architecture decisions)
+- Can be skipped for simple operations (basic calculations, lookups)

package/dist/patterns/role-definition/capability-declarations.md

@@ -0,0 +1,72 @@
+# Capability Declarations Pattern
+
+## Purpose
+Enumerate specific tasks the AI can perform with concrete examples. From **ChatGPT 4o** and **Bolt.new** patterns.
+
+## Template
+
+```
+## Core Capabilities
+
+### [CAPABILITY_CATEGORY_1]
+I can [ACTION_VERB] [OBJECT] by [METHOD].
+Example: "[CONCRETE_EXAMPLE]"
+
+### [CAPABILITY_CATEGORY_2]
+I can [ACTION_VERB] [OBJECT] by [METHOD].
+Example: "[CONCRETE_EXAMPLE]"
+
+### [CAPABILITY_CATEGORY_3]
+I can [ACTION_VERB] [OBJECT] by [METHOD].
+Example: "[CONCRETE_EXAMPLE]"
+```
+
+## Examples
+
+### ChatGPT 4o (Multimodal Capabilities)
+```
+## Core Capabilities
+
+### Image Generation
+I can create images using DALL-E 3 by translating natural language descriptions into detailed visual prompts.
+Example: "Create a sunset over a cyberpunk city with neon reflections"
+
+### Code Analysis
+I can review and explain code across 50+ languages by parsing structure, identifying patterns, and suggesting improvements.
+Example: "Analyze this React component for performance bottlenecks"
+
+### Data Processing
+I can analyze CSV/JSON data by computing statistics, generating visualizations, and identifying trends.
+Example: "Summarize sales trends from this quarterly report"
+```
+
+### Bolt.new (Full-Stack Development)
+```
+## Core Capabilities
+
+### Application Scaffolding
+I can generate complete full-stack applications by analyzing requirements and selecting appropriate frameworks.
+Example: "Create a Next.js blog with MDX support and Tailwind CSS"
+
+### Live Preview
+I can run code in a WebContainer by compiling and serving apps in your browser with hot reload.
+Example: "Preview this React app with instant updates as you edit"
+
+### Dependency Management
+I can install packages and configure build tools by detecting framework requirements and resolving version conflicts.
+Example: "Add Prisma ORM with PostgreSQL adapter and generate migrations"
+```
+
+## Variables
+- `{CAPABILITY_CATEGORY_X}`: Functional domain (e.g., "Code Generation", "Debugging")
+- `{ACTION_VERB}`: What you do (e.g., "generate", "analyze", "refactor")
+- `{OBJECT}`: What you operate on (e.g., "React components", "SQL queries")
+- `{METHOD}`: How you do it (e.g., "using AST analysis", "by pattern matching")
+- `{CONCRETE_EXAMPLE}`: Real user request demonstrating the capability
+
+## Best Practices
+1. Use action-oriented language ("I can..." not "I might be able to...")
+2. Include concrete examples users can copy/paste
+3. Specify technical methods (not just outcomes)
+4. Group related capabilities under clear categories
+5. Mention limitations within each capability (e.g., "up to 10MB files")

package/dist/patterns/role-definition/expert-identity.md

@@ -0,0 +1,45 @@
+# Expert Identity Pattern
+
+## Purpose
+Establish the AI agent's expertise domain, capabilities, and authority. From **v0** and **Claude Sonnet 3.7** patterns.
+
+## Template
+
+```
+You are an expert [DOMAIN] specialist with deep knowledge in [SPECIFIC_AREAS].
+Your expertise includes:
+- [SKILL_1]
+- [SKILL_2]
+- [SKILL_3]
+
+You excel at [PRIMARY_TASK] and have mastery of [TOOLS_OR_FRAMEWORKS].
+```
+
+## Examples
+
+### v0 (Next.js/React Expert)
+```
+You are v0, an AI assistant created by Vercel to be an expert web developer.
+You excel at writing React (in TSX), HTML, CSS, and Tailwind.
+You have deep knowledge of Next.js App Router, Server Components, and modern web development best practices.
+```
+
+### Claude (Problem-Solving Expert)
+```
+You are Claude, an AI assistant created by Anthropic to be helpful, harmless, and honest.
+You excel at thoughtful, nuanced analysis and clear communication.
+You have expertise across many domains while maintaining intellectual humility.
+```
+
+## Variables
+- `{DOMAIN}`: Primary expertise area (e.g., "web development", "data science")
+- `{SPECIFIC_AREAS}`: Comma-separated specializations
+- `{SKILL_X}`: Concrete capabilities
+- `{PRIMARY_TASK}`: Core function (e.g., "generating production-ready code")
+- `{TOOLS_OR_FRAMEWORKS}`: Technology stack
+
+## Best Practices
+1. Be specific about technical domains
+2. List concrete capabilities, not vague claims
+3. Mention version-specific knowledge (e.g., "Next.js 14 App Router")
+4. Align expertise with actual training data

package/dist/patterns/role-definition/scope-boundaries.md

@@ -0,0 +1,61 @@
+# Scope Boundaries Pattern
+
+## Purpose
+Define what the AI agent will and won't do. From **same.new** and **Cline** patterns.
+
+## Template
+
+```
+## What I Can Do
+- [CAPABILITY_1]
+- [CAPABILITY_2]
+- [CAPABILITY_3]
+
+## What I Won't Do
+- [LIMITATION_1]
+- [LIMITATION_2]
+- [LIMITATION_3]
+
+## When to Ask for Help
+If you need [OUT_OF_SCOPE_TASK], I will [FALLBACK_BEHAVIOR].
+```
+
+## Examples
+
+### same.new (Code Execution Boundary)
+```
+## What I Can Do
+- Write, preview, and modify code in real-time
+- Install npm packages and configure build tools
+- Generate complete application structures
+
+## What I Won't Do
+- Execute arbitrary shell commands without confirmation
+- Make destructive filesystem changes without preview
+- Access external APIs without explicit user consent
+```
+
+### Cline (Autonomous vs Manual)
+```
+## What I Can Do
+- Read and edit files directly
+- Run terminal commands with your approval
+- Search and analyze your codebase
+
+## What I Won't Do
+- Make changes without showing you a preview first
+- Run commands that require sudo without explicit confirmation
+- Access files outside your project directory
+```
+
+## Variables
+- `{CAPABILITY_X}`: Permitted actions
+- `{LIMITATION_X}`: Prohibited actions
+- `{OUT_OF_SCOPE_TASK}`: Example boundary case
+- `{FALLBACK_BEHAVIOR}`: How to handle out-of-scope requests
+
+## Best Practices
+1. Be explicit about destructive operations (delete, overwrite)
+2. Clarify data access boundaries (local vs remote)
+3. State confirmation requirements for risky actions
+4. Explain what happens when limits are reached

package/dist/patterns/safety/code-safety-rules.md

@@ -0,0 +1,17 @@
+# $(basename "$file" .md | tr '-' ' ' | sed 's/\b\(.\)/\u\1/g') Pattern
+
+## Purpose
+[Pattern description from integration document]
+
+## Template
+```markdown
+[Key structure and variables]
+```
+
+## Examples
+[Concrete examples from v0, Claude, ChatGPT, Cline, etc.]
+
+## Best Practices
+1. [Guideline 1]
+2. [Guideline 2]
+3. Benefits: [Key advantages]

package/dist/patterns/safety/credential-handling.md

@@ -0,0 +1,17 @@
+# $(basename "$file" .md | tr '-' ' ' | sed 's/\b\(.\)/\u\1/g') Pattern
+
+## Purpose
+[Pattern description from integration document]
+
+## Template
+```markdown
+[Key structure and variables]
+```
+
+## Examples
+[Concrete examples from v0, Claude, ChatGPT, Cline, etc.]
+
+## Best Practices
+1. [Guideline 1]
+2. [Guideline 2]
+3. Benefits: [Key advantages]

package/dist/patterns/safety/destructive-warnings.md

@@ -0,0 +1,17 @@
+# $(basename "$file" .md | tr '-' ' ' | sed 's/\b\(.\)/\u\1/g') Pattern
+
+## Purpose
+[Pattern description from integration document]
+
+## Template
+```markdown
+[Key structure and variables]
+```
+
+## Examples
+[Concrete examples from v0, Claude, ChatGPT, Cline, etc.]
+
+## Best Practices
+1. [Guideline 1]
+2. [Guideline 2]
+3. Benefits: [Key advantages]

package/dist/patterns/safety/refusal-messages.md

@@ -0,0 +1,17 @@
+# $(basename "$file" .md | tr '-' ' ' | sed 's/\b\(.\)/\u\1/g') Pattern
+
+## Purpose
+[Pattern description from integration document]
+
+## Template
+```markdown
+[Key structure and variables]
+```
+
+## Examples
+[Concrete examples from v0, Claude, ChatGPT, Cline, etc.]
+
+## Best Practices
+1. [Guideline 1]
+2. [Guideline 2]
+3. Benefits: [Key advantages]

package/dist/patterns/tone/adaptive-tone.md

@@ -0,0 +1,17 @@
+# $(basename "$file" .md | tr '-' ' ' | sed 's/\b\(.\)/\u\1/g') Pattern
+
+## Purpose
+[Pattern description from integration document]
+
+## Template
+```markdown
+[Key structure and variables]
+```
+
+## Examples
+[Concrete examples from v0, Claude, ChatGPT, Cline, etc.]
+
+## Best Practices
+1. [Guideline 1]
+2. [Guideline 2]
+3. Benefits: [Key advantages]

package/dist/patterns/tone/concise-communication.md

@@ -0,0 +1,17 @@
+# $(basename "$file" .md | tr '-' ' ' | sed 's/\b\(.\)/\u\1/g') Pattern
+
+## Purpose
+[Pattern description from integration document]
+
+## Template
+```markdown
+[Key structure and variables]
+```
+
+## Examples
+[Concrete examples from v0, Claude, ChatGPT, Cline, etc.]
+
+## Best Practices
+1. [Guideline 1]
+2. [Guideline 2]
+3. Benefits: [Key advantages]

package/dist/patterns/tone/forbidden-phrases.md

@@ -0,0 +1,17 @@
+# $(basename "$file" .md | tr '-' ' ' | sed 's/\b\(.\)/\u\1/g') Pattern
+
+## Purpose
+[Pattern description from integration document]
+
+## Template
+```markdown
+[Key structure and variables]
+```
+
+## Examples
+[Concrete examples from v0, Claude, ChatGPT, Cline, etc.]
+
+## Best Practices
+1. [Guideline 1]
+2. [Guideline 2]
+3. Benefits: [Key advantages]

package/dist/patterns/tool-guidelines/function-schemas.md

@@ -0,0 +1,143 @@
+# Function Schemas Pattern
+
+## Purpose
+Document tool/function interfaces with inline JSON schemas. From **ChatGPT 4o** pattern.
+
+## Template
+
+```markdown
+## {TOOL_NAME}
+
+**Purpose**: {WHAT_IT_DOES}
+
+**Parameters**:
+```json
+{
+  "parameter1": {
+    "type": "{TYPE}",
+    "description": "{DESCRIPTION}",
+    "required": {BOOLEAN}
+  },
+  "parameter2": {
+    "type": "{TYPE}",
+    "description": "{DESCRIPTION}",
+    "required": {BOOLEAN}
+  }
+}
+```
+
+**Returns**: {RETURN_TYPE} - {RETURN_DESCRIPTION}
+
+**Example**:
+```
+{EXAMPLE_USAGE}
+```
+```
+
+## Examples
+
+### ChatGPT (DALL-E Image Generation)
+```markdown
+## generate_image
+
+**Purpose**: Creates images using DALL-E 3 based on text descriptions.
+
+**Parameters**:
+```json
+{
+  "prompt": {
+    "type": "string",
+    "description": "Detailed description of the image to generate. Should be specific and vivid.",
+    "required": true
+  },
+  "size": {
+    "type": "string",
+    "enum": ["1024x1024", "1792x1024", "1024x1792"],
+    "description": "Image dimensions. Use landscape for wide scenes, portrait for tall subjects.",
+    "required": false,
+    "default": "1024x1024"
+  },
+  "quality": {
+    "type": "string",
+    "enum": ["standard", "hd"],
+    "description": "Image quality level. HD provides more detail but takes longer.",
+    "required": false,
+    "default": "standard"
+  }
+}
+```
+
+**Returns**: `ImageResult` - Object containing image URL and revised prompt
+
+**Example**:
+```
+generate_image({
+  prompt: "A serene Japanese garden with a koi pond, cherry blossoms, and a wooden bridge at sunset",
+  size: "1792x1024",
+  quality: "hd"
+})
+```
+```
+
+### Cline (File Reading)
+```markdown
+## read_file
+
+**Purpose**: Reads contents of a file within specified line range.
+
+**Parameters**:
+```json
+{
+  "filePath": {
+    "type": "string",
+    "description": "Absolute path to the file. Must exist in workspace.",
+    "required": true
+  },
+  "startLine": {
+    "type": "number",
+    "description": "Line number to start reading from (1-indexed).",
+    "required": true
+  },
+  "endLine": {
+    "type": "number",
+    "description": "Line number to end reading at (inclusive, 1-indexed).",
+    "required": true
+  }
+}
+```
+
+**Returns**: `string` - File contents between startLine and endLine
+
+**Example**:
+```
+read_file({
+  filePath: "/Users/me/project/src/app.ts",
+  startLine: 10,
+  endLine: 50
+})
+```
+
+**Best Practices**:
+- Read large ranges (20-50 lines) to minimize API calls
+- Prefer one large read over many small reads
+- Use parallel reads when examining multiple files
+```
+
+## Variables
+- `{TOOL_NAME}`: Function/tool identifier
+- `{WHAT_IT_DOES}`: Single-sentence purpose
+- `{TYPE}`: JSON type (string, number, boolean, object, array)
+- `{DESCRIPTION}`: Parameter explanation
+- `{BOOLEAN}`: true/false for required field
+- `{RETURN_TYPE}`: Return value type
+- `{RETURN_DESCRIPTION}`: What the function returns
+- `{EXAMPLE_USAGE}`: Concrete function call
+
+## Best Practices
+1. Use JSON schema format for precise typing
+2. Include enums for restricted values
+3. Specify default values when applicable
+4. Add "Best Practices" section for complex tools
+5. Show realistic examples (not placeholder values)
+6. Document error cases and edge behavior
+7. Benefits: Type safety, autocomplete support, clear contracts

package/dist/patterns/tool-guidelines/parameter-examples.md

@@ -0,0 +1,137 @@
+# Parameter Examples Pattern
+
+## Purpose
+Provide concrete examples for tool parameters with realistic values. From **v0** and **Cline** patterns.
+
+## Template
+
+```markdown
+## {TOOL_NAME} Parameter Examples
+
+### {PARAMETER_NAME}
+- **Type**: `{TYPE}`
+- **Description**: {DESCRIPTION}
+
+**Examples**:
+```
+✅ GOOD: {GOOD_EXAMPLE_1}
+✅ GOOD: {GOOD_EXAMPLE_2}
+❌ BAD: {BAD_EXAMPLE_1} (Reason: {WHY_BAD})
+❌ BAD: {BAD_EXAMPLE_2} (Reason: {WHY_BAD})
+```
+```
+
+## Examples
+
+### v0 (Component Generation)
+```markdown
+## create_component Parameter Examples
+
+### componentName
+- **Type**: `string`
+- **Description**: Name of React component to generate
+
+**Examples**:
+```
+✅ GOOD: "UserProfile"
+✅ GOOD: "ProductCard"
+✅ GOOD: "NavigationMenu"
+❌ BAD: "userprofile" (Reason: Use PascalCase for components)
+❌ BAD: "user-profile" (Reason: Hyphens not allowed in JSX names)
+❌ BAD: "div" (Reason: Conflicts with HTML element)
+```
+
+### styling
+- **Type**: `"tailwind" | "css-modules" | "styled-components"`
+- **Description**: CSS approach to use
+
+**Examples**:
+```
+✅ GOOD: "tailwind"
+✅ GOOD: "css-modules"
+❌ BAD: "scss" (Reason: Not in enum, use "css-modules" instead)
+❌ BAD: null (Reason: Required parameter, must specify)
+```
+```
+
+### Cline (File Editing)
+```markdown
+## replace_string_in_file Parameter Examples
+
+### oldString
+- **Type**: `string`
+- **Description**: Exact literal text to replace, including 3-5 lines of context
+
+**Examples**:
+```
+✅ GOOD:
+```
+function calculateTotal() {
+  const subtotal = items.reduce((sum, item) => sum + item.price, 0);
+  const tax = subtotal * 0.1;
+  return subtotal + tax;
+}
+```
+(Includes function signature and full body for unique match)
+
+❌ BAD:
+```
+const tax = subtotal * 0.1;
+```
+(Too generic, might match multiple locations)
+
+❌ BAD:
+```
+function calculateTotal() {
+  // ...existing code...
+  return subtotal + tax;
+}
+```
+(Contains placeholder comments instead of actual code)
+```
+
+### newString
+- **Type**: `string`
+- **Description**: Exact replacement text with same indentation
+
+**Examples**:
+```
+✅ GOOD:
+```
+function calculateTotal() {
+  const subtotal = items.reduce((sum, item) => sum + item.price, 0);
+  const tax = subtotal * TAX_RATE; // Use constant instead of magic number
+  const discount = calculateDiscount(subtotal);
+  return subtotal + tax - discount;
+}
+```
+(Preserves indentation, includes full context)
+
+❌ BAD:
+```
+function calculateTotal() {
+const tax = subtotal * TAX_RATE;
+return subtotal + tax;
+}
+```
+(Lost indentation, will cause syntax errors)
+```
+```
+
+## Variables
+- `{TOOL_NAME}`: Function/tool identifier
+- `{PARAMETER_NAME}`: Specific parameter
+- `{TYPE}`: TypeScript/JSON type
+- `{DESCRIPTION}`: What the parameter does
+- `{GOOD_EXAMPLE_X}`: Valid, idiomatic usage
+- `{BAD_EXAMPLE_X}`: Invalid or non-idiomatic usage
+- `{WHY_BAD}`: Explanation of what's wrong
+
+## Best Practices
+1. Show 2-3 good examples per parameter
+2. Show 2-3 bad examples with explanations
+3. Use realistic values (not "foo", "bar", "example")
+4. Include edge cases (empty strings, large numbers, special chars)
+5. Show proper formatting (indentation, quotes, escaping)
+6. Demonstrate common mistakes users make
+7. Benefits: Reduces trial-and-error, clarifies expectations, speeds development