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

package/dist/patterns/domain-expertise/server-components.md

@@ -0,0 +1,212 @@
+# Server Components Pattern
+
+## Purpose
+Guide usage of React Server Components (RSC) in Next.js. From **v0** pattern.
+
+## Template
+
+```markdown
+## React Server Components (RSC)
+
+### When to Use Server Components
+- {SCENARIO_1_FOR_SERVER}
+- {SCENARIO_2_FOR_SERVER}
+- {SCENARIO_3_FOR_SERVER}
+
+### When to Use Client Components
+- {SCENARIO_1_FOR_CLIENT}
+- {SCENARIO_2_FOR_CLIENT}
+- {SCENARIO_3_FOR_CLIENT}
+
+### Composition Patterns
+- {HOW_TO_MIX_SERVER_AND_CLIENT}
+- {PASSING_PROPS_BETWEEN_TYPES}
+- {HANDLING_SERIALIZATION}
+```
+
+## Examples
+
+### v0 (Next.js App Router RSC Guidelines)
+```markdown
+## React Server Components (RSC) in Next.js
+
+### When to Use Server Components (Default)
+- **Data Fetching**: When you need to fetch data from APIs or databases
+  ```typescript
+  // ✅ Server Component - fetch directly
+  export default async function BlogPost({ params }: { params: { id: string } }) {
+    const post = await fetch(`https://api.example.com/posts/${params.id}`)
+      .then(r => r.json());
+    return <article>{post.content}</article>;
+  }
+  ```
+
+- **Static Content**: Components that don't need interactivity
+  ```typescript
+  // ✅ Server Component - no hooks or events
+  export function Footer() {
+    return (
+      <footer>
+        <p>&copy; 2024 Company Name</p>
+        <nav>
+          <a href="/about">About</a>
+          <a href="/contact">Contact</a>
+        </nav>
+      </footer>
+    );
+  }
+  ```
+
+- **Sensitive Operations**: Backend logic that shouldn't be exposed to client
+  ```typescript
+  // ✅ Server Component - API key stays on server
+  async function fetchData() {
+    return await fetch('https://api.example.com/data', {
+      headers: { 'Authorization': `Bearer ${process.env.API_KEY}` }
+    }).then(r => r.json());
+  }
+  ```
+
+### When to Use Client Components ('use client')
+- **Interactivity**: Components with event handlers or React hooks
+  ```typescript
+  'use client';
+  import { useState } from 'react';
+  
+  export function Counter() {
+    const [count, setCount] = useState(0);
+    return <button onClick={() => setCount(count + 1)}>Count: {count}</button>;
+  }
+  ```
+
+- **Browser APIs**: Components using window, document, localStorage, etc.
+  ```typescript
+  'use client';
+  import { useEffect } from 'react';
+  
+  export function Tracker() {
+    useEffect(() => {
+      console.log('Page viewed:', window.location.href);
+    }, []);
+    return null;
+  }
+  ```
+
+- **Third-Party Libraries**: Components using client-only libraries
+  ```typescript
+  'use client';
+  import { useFormik } from 'formik'; // Client-side form library
+  
+  export function SignupForm() {
+    const formik = useFormik({ /* ... */ });
+    return <form onSubmit={formik.handleSubmit}>...</form>;
+  }
+  ```
+
+### Composition Patterns
+- **Server Component as Parent**: Client components can be children
+  ```typescript
+  // ✅ Server Component
+  export default async function Page() {
+    const data = await fetchData();
+    
+    return (
+      <div>
+        <h1>{data.title}</h1>
+        <InteractiveWidget data={data} /> {/* Client Component */}
+      </div>
+    );
+  }
+  ```
+
+- **Pass Serializable Props**: Only JSON-serializable data between boundaries
+  ```typescript
+  // ✅ Serializable props (string, number, plain object)
+  <ClientComponent title="Hello" count={5} data={{ id: 1 }} />
+  
+  // ❌ Non-serializable props (functions, class instances)
+  <ClientComponent onClick={() => {}} instance={new Date()} />
+  ```
+
+- **Workaround for Non-Serializable**: Use Server Actions or move logic to client
+  ```typescript
+  // ✅ Server Action (async function from server)
+  async function updateData(formData: FormData) {
+    'use server';
+    // Server-side logic
+  }
+  
+  // Pass action to client component
+  <ClientForm action={updateData} />
+  ```
+
+- **Client Component as Wrapper**: Server components can be passed as children
+  ```typescript
+  // ✅ Client Component wrapper
+  'use client';
+  export function AnimatedContainer({ children }: { children: React.ReactNode }) {
+    return <motion.div>{children}</motion.div>;
+  }
+  
+  // Usage: Server Component as child
+  <AnimatedContainer>
+    <ServerRenderedContent /> {/* Still a Server Component */}
+  </AnimatedContainer>
+  ```
+
+### Performance Considerations
+- **Minimize Client Bundles**: Keep 'use client' boundary as low as possible
+  ```typescript
+  // ❌ Entire page is client component (large bundle)
+  'use client';
+  export default function Page() {
+    const [state, setState] = useState();
+    return <div>...</div>;
+  }
+  
+  // ✅ Only interactive part is client component
+  export default function Page() {
+    return (
+      <div>
+        <StaticHeader /> {/* Server Component */}
+        <InteractiveWidget /> {/* Client Component - small bundle */}
+        <StaticFooter /> {/* Server Component */}
+      </div>
+    );
+  }
+  ```
+
+- **Data Fetching Location**: Fetch in Server Component, not Client Component
+  ```typescript
+  // ✅ Fetch in Server Component (faster, no loading state)
+  export default async function Page() {
+    const data = await fetchData();
+    return <ClientDisplay data={data} />;
+  }
+  
+  // ❌ Fetch in Client Component (slower, needs loading state)
+  'use client';
+  export default function Page() {
+    const [data, setData] = useState(null);
+    useEffect(() => { fetchData().then(setData); }, []);
+    if (!data) return <Spinner />;
+    return <div>{data}</div>;
+  }
+  ```
+```
+
+## Variables
+- `{SCENARIO_X_FOR_SERVER}`: When to use Server Component
+- `{SCENARIO_X_FOR_CLIENT}`: When to use Client Component
+- `{HOW_TO_MIX_SERVER_AND_CLIENT}`: Composition strategies
+- `{PASSING_PROPS_BETWEEN_TYPES}`: Serialization rules
+- `{HANDLING_SERIALIZATION}`: Workarounds for non-serializable data
+
+## Best Practices
+1. Default to Server Components (add 'use client' only when needed)
+2. Explain serialization boundaries (common source of bugs)
+3. Show composition patterns (client wrapping server, server wrapping client)
+4. Highlight performance benefits (smaller bundles, faster data fetching)
+5. Provide migration guide (Pages Router → App Router)
+6. Address common mistakes ('use client' on entire page)
+7. Benefits: Optimal performance, secure API calls, smaller JS bundles

package/dist/patterns/domain-expertise/shadcn-ui.md

@@ -0,0 +1,52 @@
+# shadcn/ui Component Library Pattern
+
+## Purpose
+Guide usage of shadcn/ui components in Next.js/React projects. From **same.new**.
+
+## Installation Pattern
+```bash
+npx shadcn-ui@latest add button
+npx shadcn-ui@latest add card dialog input
+```
+
+## Component Usage
+```tsx
+import { Button } from "@/components/ui/button"
+import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card"
+
+export function ProductCard({ product }: Props) {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>{product.name}</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <p>{product.description}</p>
+        <Button>Add to Cart</Button>
+      </CardContent>
+    </Card>
+  )
+}
+```
+
+## Customization
+```tsx
+// ✅ Extend with custom variants using cva
+import { cva } from "class-variance-authority"
+
+const buttonVariants = cva("base-classes", {
+  variants: {
+    variant: {
+      default: "bg-primary",
+      outline: "border border-input",
+      custom: "bg-gradient-to-r from-purple-500 to-pink-500"
+    }
+  }
+})
+```
+
+## Best Practices
+- Components are copied to your repo (not npm dependencies)
+- Customize in `components/ui/` as needed
+- Use Radix UI primitives for accessibility
+- Combine with Tailwind for styling

package/dist/patterns/domain-expertise/tailwind-patterns.md

@@ -0,0 +1,52 @@
+# Tailwind CSS Patterns
+
+## Purpose
+Enforce Tailwind CSS best practices and utility patterns. From **same.new** and **Loveable**.
+
+## Key Patterns
+
+### Utility-First Approach
+```tsx
+// ✅ Use utility classes
+<button className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600">
+  Click me
+</button>
+
+// ❌ Avoid custom CSS
+<button className="custom-button">Click me</button>
+```
+
+### Responsive Design
+```tsx
+// ✅ Mobile-first responsive utilities
+<div className="w-full md:w-1/2 lg:w-1/3 xl:w-1/4">
+  Responsive width
+</div>
+```
+
+### Dark Mode
+```tsx
+// ✅ Dark mode variants
+<div className="bg-white dark:bg-gray-900 text-gray-900 dark:text-white">
+  Content
+</div>
+```
+
+### Component Extraction
+```tsx
+// When utilities get too long (>5 classes), extract to component
+// ✅ Extract reusable pattern
+function Card({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="rounded-lg shadow-md p-6 bg-white dark:bg-gray-800">
+      {children}
+    </div>
+  );
+}
+```
+
+## Best Practices
+- Use arbitrary values sparingly: `w-[137px]` (prefer standard scale)
+- Group related utilities: layout, spacing, typography, colors
+- Use @apply only for component styles (avoid in utility classes)
+- Configure theme in tailwind.config.js for brand colors

package/dist/patterns/environment/container-awareness.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/environment/ide-features.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/environment/os-commands.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/organization/heading-hierarchy.md

@@ -0,0 +1,103 @@
+# Heading Hierarchy Pattern
+
+## Purpose
+Use Markdown headings to create scannable, nested instruction sections. From **v0**, **Claude**, and **Cline** patterns.
+
+## Template
+
+```markdown
+# {TOP_LEVEL_ROLE}
+
+## {SECTION_1}
+{Content}
+
+### {SUBSECTION_1_1}
+{Content}
+
+### {SUBSECTION_1_2}
+{Content}
+
+## {SECTION_2}
+{Content}
+
+### {SUBSECTION_2_1}
+{Content}
+
+## {SECTION_3}
+{Content}
+```
+
+## Examples
+
+### v0 (Code Generation Instructions)
+```markdown
+# v0 Code Generation Instructions
+
+## Code Style
+Write modern, idiomatic TypeScript with proper typing.
+
+### React Patterns
+- Use functional components with hooks
+- Prefer composition over inheritance
+- Extract reusable logic into custom hooks
+
+### Naming Conventions
+- Components: PascalCase (e.g., UserProfile)
+- Files: kebab-case (e.g., user-profile.tsx)
+- Functions: camelCase (e.g., handleSubmit)
+
+## Framework Requirements
+
+### Next.js App Router
+- Use Server Components by default
+- Add 'use client' only when necessary
+- Leverage React Server Components for data fetching
+
+### Routing
+- File-based routing in app/ directory
+- Use route groups (folders) for organization
+- Dynamic routes with [param] syntax
+```
+
+### Cline (Tool Usage Guidelines)
+```markdown
+# Cline Tool Usage Guidelines
+
+## File Operations
+
+### Reading Files
+- Use read_file for examining code
+- Read large sections to minimize API calls
+- Parallelize reads when possible
+
+### Writing Files
+- Show preview before making changes
+- Use replace_string_in_file for edits
+- Include 3-5 lines of context for accuracy
+
+## Terminal Commands
+
+### Command Execution
+- Run one command at a time (no parallel terminal calls)
+- Explain purpose of non-trivial commands
+- Use absolute paths to avoid navigation issues
+
+### Output Management
+- Filter output with grep/awk for large results
+- Use --no-pager for git commands
+- Disable paging to avoid truncation
+```
+
+## Variables
+- `{TOP_LEVEL_ROLE}`: Main purpose (H1 - appears once)
+- `{SECTION_X}`: Major category (H2 - primary divisions)
+- `{SUBSECTION_X_Y}`: Sub-category (H3 - detailed breakdowns)
+
+## Best Practices
+1. Use only one H1 (main title)
+2. H2 for major sections (5-10 max)
+3. H3 for subsections within H2
+4. Avoid going deeper than H3 (use lists instead)
+5. Keep headings concise (3-7 words)
+6. Use parallel structure (all H2s follow same pattern)
+7. Benefits: Easy to navigate, works in Markdown viewers, hierarchical structure

package/dist/patterns/organization/sequential-workflows.md

@@ -0,0 +1,102 @@
+# Sequential Workflows Pattern
+
+## Purpose
+Define step-by-step processes with clear ordering. From **Manus** agent loop pattern.
+
+## Template
+
+```markdown
+## {WORKFLOW_NAME}
+
+Follow these steps in order:
+
+1. **{STEP_1_NAME}**: {STEP_1_DESCRIPTION}
+   - {SUBSTEP_1_1}
+   - {SUBSTEP_1_2}
+
+2. **{STEP_2_NAME}**: {STEP_2_DESCRIPTION}
+   - {SUBSTEP_2_1}
+   - {SUBSTEP_2_2}
+
+3. **{STEP_3_NAME}**: {STEP_3_DESCRIPTION}
+   - {SUBSTEP_3_1}
+   - {SUBSTEP_3_2}
+
+Repeat until {COMPLETION_CONDITION}.
+```
+
+## Examples
+
+### Manus (Agent Execution Loop)
+```markdown
+## Agent Execution Loop
+
+Follow these steps in order:
+
+1. **Analyze Request**: Understand user intent and break down into subtasks
+   - Read the user's message carefully
+   - Identify required information and tools
+   - Determine if clarification is needed
+
+2. **Plan Actions**: Decide which tool(s) to use
+   - Select one tool per iteration (no parallel tool calls)
+   - Gather necessary parameters
+   - Anticipate potential errors
+
+3. **Execute Tool**: Call the selected tool and process results
+   - Invoke tool with validated parameters
+   - Parse output for relevant information
+   - Update internal state with findings
+
+4. **Reflect**: Evaluate progress and decide next action
+   - Compare current state to goal
+   - Identify remaining subtasks
+   - Determine if another iteration is needed
+
+Repeat until all subtasks are completed or user goal is achieved.
+```
+
+### v0 (Code Generation Workflow)
+```markdown
+## Code Generation Workflow
+
+Follow these steps in order:
+
+1. **Understand Requirements**: Parse user request for technical specs
+   - Identify framework (React, Vue, etc.)
+   - Determine styling approach (Tailwind, CSS modules)
+   - Note any specific libraries requested
+
+2. **Plan Structure**: Design component hierarchy
+   - Break UI into logical components
+   - Identify shared vs unique elements
+   - Map out data flow
+
+3. **Generate Code**: Write implementation
+   - Start with outer container/layout
+   - Add child components progressively
+   - Include proper TypeScript types
+
+4. **Verify Quality**: Check for common issues
+   - Ensure accessibility (ARIA labels, semantic HTML)
+   - Validate responsive design breakpoints
+   - Confirm proper error handling
+
+Repeat for each component in the hierarchy.
+```
+
+## Variables
+- `{WORKFLOW_NAME}`: Process title (e.g., "Request Processing", "Error Recovery")
+- `{STEP_X_NAME}`: Phase name (e.g., "Analyze", "Execute", "Verify")
+- `{STEP_X_DESCRIPTION}`: What happens in this phase
+- `{SUBSTEP_X_Y}`: Granular actions within phase
+- `{COMPLETION_CONDITION}`: When to stop iterating
+
+## Best Practices
+1. Number steps explicitly (1, 2, 3...) for clarity
+2. Use bold for step names to make them scannable
+3. Limit to 5-7 main steps (sub-steps for detail)
+4. Include decision points ("If X, then Y")
+5. State iteration/termination conditions clearly
+6. Use present tense imperative ("Analyze", not "You should analyze")
+7. Benefits: Reproducible process, clear sequencing, easy to debug

package/dist/patterns/organization/xml-rule-groups.md

@@ -0,0 +1,64 @@
+# XML Rule Groups Pattern
+
+## Purpose
+Structure instructions using XML-like tags for hierarchical organization. From **same.new** pattern.
+
+## Template
+
+```xml
+<rules>
+  <category name="{CATEGORY_NAME}">
+    <rule>{RULE_1}</rule>
+    <rule>{RULE_2}</rule>
+    <rule>{RULE_3}</rule>
+  </category>
+  
+  <category name="{CATEGORY_NAME_2}">
+    <rule>{RULE_4}</rule>
+    <rule>{RULE_5}</rule>
+  </category>
+</rules>
+```
+
+## Examples
+
+### same.new (Code Generation Rules)
+```xml
+<rules>
+  <category name="Code Style">
+    <rule>Use functional components with hooks, not class components</rule>
+    <rule>Prefer const over let, never use var</rule>
+    <rule>Use descriptive variable names (e.g., userData not ud)</rule>
+  </category>
+  
+  <category name="File Operations">
+    <rule>Always show a preview before writing files</rule>
+    <rule>Ask for confirmation before deleting or overwriting</rule>
+    <rule>Use relative paths for imports within the project</rule>
+  </category>
+  
+  <category name="Error Handling">
+    <rule>Wrap async operations in try-catch blocks</rule>
+    <rule>Return user-friendly error messages, not stack traces</rule>
+    <rule>Log errors for debugging but don't expose internals</rule>
+  </category>
+</rules>
+```
+
+## Variables
+- `{CATEGORY_NAME}`: Logical grouping (e.g., "Code Style", "Security", "Performance")
+- `{RULE_X}`: Specific instruction within category
+
+## Best Practices
+1. Keep categories focused (5-10 rules max per category)
+2. Use parallel structure for rules within a category
+3. Order categories by importance (most critical first)
+4. Use nested tags for sub-categories if needed:
+   ```xml
+   <category name="React">
+     <subcategory name="Hooks">
+       <rule>Always declare hooks at top level</rule>
+     </subcategory>
+   </category>
+   ```
+5. Benefits: Easy to scan, clear hierarchy, simple to add/remove sections