@caoscompanybr/merlin 3.5.0

package/.merlin-core/skills/general/tailwind-design-system/references/component-patterns.md

@@ -0,0 +1,353 @@
+# Tailwind v4 Component Patterns
+
+> Reference for the tailwind-design-system skill. Production-ready CVA components for React 19.
+
+## CVA Button Component
+
+```typescript
+// components/ui/button.tsx
+import { Slot } from '@radix-ui/react-slot'
+import { cva, type VariantProps } from 'class-variance-authority'
+import { cn } from '@/lib/utils'
+
+const buttonVariants = cva(
+  'inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',
+  {
+    variants: {
+      variant: {
+        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
+        destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
+        outline: 'border border-border bg-background hover:bg-accent hover:text-accent-foreground',
+        secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
+        ghost: 'hover:bg-accent hover:text-accent-foreground',
+        link: 'text-primary underline-offset-4 hover:underline',
+      },
+      size: {
+        default: 'h-10 px-4 py-2',
+        sm: 'h-9 rounded-md px-3',
+        lg: 'h-11 rounded-md px-8',
+        icon: 'size-10',
+      },
+    },
+    defaultVariants: { variant: 'default', size: 'default' },
+  }
+)
+
+export interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {
+  asChild?: boolean
+}
+
+// React 19: ref as regular prop, no forwardRef
+export function Button({
+  className, variant, size, asChild = false, ref, ...props
+}: ButtonProps & { ref?: React.Ref<HTMLButtonElement> }) {
+  const Comp = asChild ? Slot : 'button'
+  return <Comp className={cn(buttonVariants({ variant, size, className }))} ref={ref} {...props} />
+}
+```
+
+Usage:
+
+```tsx
+<Button variant="destructive" size="lg">Delete</Button>
+<Button variant="outline">Cancel</Button>
+<Button asChild><Link href="/home">Home</Link></Button>
+```
+
+## Compound Card Component
+
+```typescript
+// components/ui/card.tsx
+import { cn } from '@/lib/utils'
+
+export function Card({ className, ref, ...props }:
+  React.HTMLAttributes<HTMLDivElement> & { ref?: React.Ref<HTMLDivElement> }) {
+  return <div ref={ref} className={cn(
+    'rounded-lg border border-border bg-card text-card-foreground shadow-sm', className
+  )} {...props} />
+}
+
+export function CardHeader({ className, ref, ...props }:
+  React.HTMLAttributes<HTMLDivElement> & { ref?: React.Ref<HTMLDivElement> }) {
+  return <div ref={ref} className={cn('flex flex-col space-y-1.5 p-6', className)} {...props} />
+}
+
+export function CardTitle({ className, ref, ...props }:
+  React.HTMLAttributes<HTMLHeadingElement> & { ref?: React.Ref<HTMLHeadingElement> }) {
+  return <h3 ref={ref} className={cn(
+    'text-2xl font-semibold leading-none tracking-tight', className
+  )} {...props} />
+}
+
+export function CardDescription({ className, ref, ...props }:
+  React.HTMLAttributes<HTMLParagraphElement> & { ref?: React.Ref<HTMLParagraphElement> }) {
+  return <p ref={ref} className={cn('text-sm text-muted-foreground', className)} {...props} />
+}
+
+export function CardContent({ className, ref, ...props }:
+  React.HTMLAttributes<HTMLDivElement> & { ref?: React.Ref<HTMLDivElement> }) {
+  return <div ref={ref} className={cn('p-6 pt-0', className)} {...props} />
+}
+
+export function CardFooter({ className, ref, ...props }:
+  React.HTMLAttributes<HTMLDivElement> & { ref?: React.Ref<HTMLDivElement> }) {
+  return <div ref={ref} className={cn('flex items-center p-6 pt-0', className)} {...props} />
+}
+```
+
+Usage:
+
+```tsx
+<Card>
+  <CardHeader>
+    <CardTitle>Account</CardTitle>
+    <CardDescription>Manage your account settings</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <form>...</form>
+  </CardContent>
+  <CardFooter>
+    <Button>Save</Button>
+  </CardFooter>
+</Card>
+```
+
+## Form Input with Error State
+
+```typescript
+// components/ui/input.tsx
+import { cn } from '@/lib/utils'
+
+export interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
+  error?: string
+  ref?: React.Ref<HTMLInputElement>
+}
+
+export function Input({ className, type, error, ref, ...props }: InputProps) {
+  return (
+    <div className="relative">
+      <input
+        type={type}
+        className={cn(
+          'flex h-10 w-full rounded-md border border-border bg-background px-3 py-2 text-sm ring-offset-background file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50',
+          error && 'border-destructive focus-visible:ring-destructive',
+          className
+        )}
+        ref={ref}
+        aria-invalid={!!error}
+        aria-describedby={error ? `${props.id}-error` : undefined}
+        {...props}
+      />
+      {error && (
+        <p id={`${props.id}-error`} className="mt-1 text-sm text-destructive" role="alert">
+          {error}
+        </p>
+      )}
+    </div>
+  )
+}
+
+// components/ui/label.tsx
+import { cva } from 'class-variance-authority'
+
+const labelVariants = cva(
+  'text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70'
+)
+
+export function Label({ className, ref, ...props }:
+  React.LabelHTMLAttributes<HTMLLabelElement> & { ref?: React.Ref<HTMLLabelElement> }) {
+  return <label ref={ref} className={cn(labelVariants(), className)} {...props} />
+}
+```
+
+## Form with React Hook Form + Zod
+
+```typescript
+import { useForm } from 'react-hook-form'
+import { zodResolver } from '@hookform/resolvers/zod'
+import { z } from 'zod'
+
+const schema = z.object({
+  email: z.string().email('Invalid email address'),
+  password: z.string().min(8, 'Password must be at least 8 characters'),
+})
+
+function LoginForm() {
+  const { register, handleSubmit, formState: { errors } } = useForm({
+    resolver: zodResolver(schema),
+  })
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)} className="space-y-4">
+      <div className="space-y-2">
+        <Label htmlFor="email">Email</Label>
+        <Input id="email" type="email" {...register('email')} error={errors.email?.message} />
+      </div>
+      <div className="space-y-2">
+        <Label htmlFor="password">Password</Label>
+        <Input id="password" type="password" {...register('password')} error={errors.password?.message} />
+      </div>
+      <Button type="submit" className="w-full">Sign In</Button>
+    </form>
+  )
+}
+```
+
+## Responsive Grid System
+
+```typescript
+// components/ui/grid.tsx
+import { cn } from '@/lib/utils'
+import { cva, type VariantProps } from 'class-variance-authority'
+
+const gridVariants = cva('grid', {
+  variants: {
+    cols: {
+      1: 'grid-cols-1',
+      2: 'grid-cols-1 sm:grid-cols-2',
+      3: 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-3',
+      4: 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-4',
+    },
+    gap: { none: 'gap-0', sm: 'gap-2', md: 'gap-4', lg: 'gap-6', xl: 'gap-8' },
+  },
+  defaultVariants: { cols: 3, gap: 'md' },
+})
+
+export function Grid({ className, cols, gap, ...props }:
+  React.HTMLAttributes<HTMLDivElement> & VariantProps<typeof gridVariants>) {
+  return <div className={cn(gridVariants({ cols, gap, className }))} {...props} />
+}
+
+const containerVariants = cva('mx-auto w-full px-4 sm:px-6 lg:px-8', {
+  variants: {
+    size: {
+      sm: 'max-w-screen-sm', md: 'max-w-screen-md', lg: 'max-w-screen-lg',
+      xl: 'max-w-screen-xl', '2xl': 'max-w-screen-2xl', full: 'max-w-full',
+    },
+  },
+  defaultVariants: { size: 'xl' },
+})
+
+export function Container({ className, size, ...props }:
+  React.HTMLAttributes<HTMLDivElement> & VariantProps<typeof containerVariants>) {
+  return <div className={cn(containerVariants({ size, className }))} {...props} />
+}
+```
+
+Usage:
+
+```tsx
+<Container>
+  <Grid cols={4} gap="lg">
+    {products.map((p) => (
+      <ProductCard key={p.id} product={p} />
+    ))}
+  </Grid>
+</Container>
+```
+
+## Dialog with Native CSS Animations
+
+```typescript
+// components/ui/dialog.tsx
+import * as DialogPrimitive from '@radix-ui/react-dialog'
+import { cn } from '@/lib/utils'
+
+export function DialogOverlay({ className, ref, ...props }:
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Overlay> & { ref?: React.Ref<HTMLDivElement> }) {
+  return (
+    <DialogPrimitive.Overlay ref={ref} className={cn(
+      'fixed inset-0 z-50 bg-black/80',
+      'data-[state=open]:animate-fade-in data-[state=closed]:animate-fade-out',
+      className
+    )} {...props} />
+  )
+}
+
+export function DialogContent({ className, children, ref, ...props }:
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content> & { ref?: React.Ref<HTMLDivElement> }) {
+  return (
+    <DialogPrimitive.Portal>
+      <DialogOverlay />
+      <DialogPrimitive.Content ref={ref} className={cn(
+        'fixed left-1/2 top-1/2 z-50 grid w-full max-w-lg -translate-x-1/2 -translate-y-1/2 gap-4 border border-border bg-background p-6 shadow-lg sm:rounded-lg',
+        'data-[state=open]:animate-slide-in data-[state=closed]:animate-fade-out',
+        className
+      )} {...props}>
+        {children}
+      </DialogPrimitive.Content>
+    </DialogPrimitive.Portal>
+  )
+}
+```
+
+## ThemeProvider (Dark Mode)
+
+```typescript
+// providers/ThemeProvider.tsx
+'use client'
+import { createContext, useContext, useEffect, useState } from 'react'
+
+type Theme = 'dark' | 'light' | 'system'
+
+const ThemeContext = createContext<{ theme: Theme; setTheme: (t: Theme) => void; resolvedTheme: 'dark' | 'light' } | undefined>(undefined)
+
+export function ThemeProvider({ children, defaultTheme = 'system', storageKey = 'theme' }:
+  { children: React.ReactNode; defaultTheme?: Theme; storageKey?: string }) {
+  const [theme, setTheme] = useState<Theme>(defaultTheme)
+  const [resolvedTheme, setResolvedTheme] = useState<'dark' | 'light'>('light')
+
+  useEffect(() => {
+    const stored = localStorage.getItem(storageKey) as Theme | null
+    if (stored) setTheme(stored)
+  }, [storageKey])
+
+  useEffect(() => {
+    const root = document.documentElement
+    root.classList.remove('light', 'dark')
+    const resolved = theme === 'system'
+      ? (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light')
+      : theme
+    root.classList.add(resolved)
+    setResolvedTheme(resolved)
+  }, [theme])
+
+  return (
+    <ThemeContext.Provider value={{
+      theme, resolvedTheme,
+      setTheme: (t) => { localStorage.setItem(storageKey, t); setTheme(t) },
+    }}>
+      {children}
+    </ThemeContext.Provider>
+  )
+}
+
+export const useTheme = () => {
+  const ctx = useContext(ThemeContext)
+  if (!ctx) throw new Error('useTheme must be used within ThemeProvider')
+  return ctx
+}
+```
+
+Theme toggle:
+
+```tsx
+import { Moon, Sun } from "lucide-react";
+
+export function ThemeToggle() {
+  const { resolvedTheme, setTheme } = useTheme();
+  return (
+    <Button
+      variant="ghost"
+      size="icon"
+      onClick={() => setTheme(resolvedTheme === "dark" ? "light" : "dark")}
+    >
+      <Sun className="size-5 rotate-0 scale-100 transition-all dark:-rotate-90 dark:scale-0" />
+      <Moon className="absolute size-5 rotate-90 scale-0 transition-all dark:rotate-0 dark:scale-100" />
+      <span className="sr-only">Toggle theme</span>
+    </Button>
+  );
+}
+```

package/.merlin-core/skills/general/teach-method/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: teach-method
+description: Teaches a project's published method and Merlin usage to a user WHEN INVITED — retrieval-grounded (from the published, redacted education corpus in RAGBASE or a vault teaching-pack), never invented, adapted to the learner's archetype, with mandatory source citations. Invocable by any agent (GRIMÓRIO uses it most). NOT a content generator — a disciplined tutor with hard confidentiality and anti-hallucination guardrails.
+license: Apache-2.0
+metadata:
+  author: merlin-framework
+  version: "1.0.0"
+  auto_activate:
+    [me-explica, modo-aula, ensina, teach-method, como-funciona, por-que-assim]
+  tool_reminders:
+    - "Teach ONLY from the published/redacted corpus (RAGBASE or <vault>/teaching-pack/) — never a raw mentorship corpus"
+    - "Every taught claim needs a [SOURCE: …] citation that resolves to a real guide/anchor; no chunk ⇒ say 'not in the material, I won't invent it'"
+    - "Allow-list: teach only what the corpus marks teachable; WALL OFF whatever it marks restricted (commercial IP, pricing/sales, ToS-risky topics)"
+    - "Product truth over guide: teach the product's REAL model (verify against the live schema/product); flag drifting guides as conceptual"
+    - "Silent by default — teach only on an invitation; never repeat a lesson already taught"
+---
+
+# Teach Method — the disciplined tutor
+
+Teaches a project's **published method** and Merlin usage to a user **when invited**. This skill
+carries the _discipline_; the _facts_ come from the project's education corpus at teach time. A
+consuming project supplies the corpus and the restricted-topic list — this skill never invents them.
+
+## 1. The invitation gate (when this activates)
+
+Stay silent by default. Activate only on:
+
+- **Explicit ask** — "me explica", "por quê assim?", "como funciona?", "modo aula" (or the install's
+  equivalents).
+- **Struggle signal** — same task reworked 3×, method broken repeatedly, visible rework.
+- **Onboarding** — a new member's first week (window open by default, then closes).
+
+Never interrupt execution mid-flow; never repeat a lesson already taught (track per learner/session).
+
+## 2. Source of truth (retrieval-grounded)
+
+Teach **only** from the **published, redacted** teaching corpus:
+
+- **RAGBASE** (preferred): query the knowledge base (`POST /chat`, or pgvector). Its power mode is an
+  Agno agent — reuse it.
+- **`<vault>/teaching-pack/`** (offline fallback): the redacted guides + lessons copied in at
+  provision time.
+
+Read/confirm the cited file before quoting. **No supporting chunk ⇒** say, literally, that it is not
+in the available material and that you will not invent it.
+
+## 3. Citation contract (non-negotiable)
+
+Every claim carries a source tag resolving to a real file + anchor, e.g.:
+
+```
+[SOURCE: <guide-id> §<section> · teaching-pack/<path>#<anchor>]
+```
+
+Audit: any taught sentence without an adjacent `[SOURCE:` is a violation.
+
+## 4. Adapt to the learner (4 archetypes — detect by behavior, no quiz)
+
+Default **[HANDS-ON]**. [BUSINESS]→lead with the gain · [TECHNICAL]→the contract/architecture ·
+[HANDS-ON]→an example on their OWN work · [CONCEPTUAL]→the whole model + the why. Adjust each turn;
+store the signal, never ask "what's your profile?".
+
+## 5. The teaching loop (per concept)
+
+1. **Reframe** in one plain sentence (no jargon).
+2. **Example from THEIR work** — a real item they just touched.
+3. **Cite the source** (§3).
+4. **One check question** ("does this fit your case?").
+5. **Point to the guide** to go deeper — then stop.
+
+## 6. Guardrails (hard)
+
+- **OFF unless a published, redacted corpus exists.** No runtime redaction of a raw mentorship corpus
+  (LLM filters are bypassable by paraphrase) — redact at the corpus level, not the prompt.
+- **Allow-list, corpus-defined:** teach only what the corpus marks teachable. **Wall off** whatever
+  it marks restricted (commercial IP, pricing/sales, multi-account/scraping or other ToS-risky
+  topics). The exclusion lives in the corpus, not in this skill.
+- **Product-truth overlay:** teach the product's **real** model — verify against the live
+  schema/product, and mark drifting guides as conceptual.
+- **Free vs premium:** teach to USE the method (just-in-time, on the user's own work). To MASTER/SELL
+  it = the human cohorts — add a cohort CTA from the paid tier up. Don't cannibalize.
+
+## Voice
+
+Speak the install's language; direct + warm + technical; specific over generic; analogies from the
+physical world; explicit uncertainty; "not in the material" over invention.

package/.merlin-core/skills/general/team-execution/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: team-execution
+description: Multi-agent team execution with coordinate, route, and broadcast modes
+license: Apache-2.0
+metadata:
+  author: merlin-framework
+  version: "3.0.0"
+  auto_activate:
+    [team-execute, coordinate-agents, broadcast-task, route-task, squad-work]
+---
+
+# Team Execution
+
+Multi-agent task dispatch using three execution modes. Composes ParallelExecutor, SubagentDispatcher, and ResultAggregator for scalable team-based work.
+
+## Execution Modes
+
+### COORDINATE
+
+Split a task among multiple agents by dividing files, run all in parallel, merge results.
+
+- **Best for:** Large implementation tasks with many files
+- **Strategy:** Round-robin file distribution, MERGE_ALL aggregation
+- **Example:** "Implement 12 API endpoints" → split across 3 dev agents
+
+### ROUTE
+
+Analyze the task description and dispatch to the single best-fit agent using keyword scoring.
+
+- **Best for:** Tasks with a clear domain owner
+- **Strategy:** Keyword match scoring, single dispatch
+- **Example:** "Write unit tests for auth module" → routes to QA
+
+### BROADCAST
+
+Send the same task to all specified agents and pick the highest quality result.
+
+- **Best for:** Design decisions, architecture trade-offs, getting multiple perspectives
+- **Strategy:** Parallel dispatch, BEST_QUALITY aggregation
+- **Example:** "Propose caching strategy" → architect + dev + devops all contribute, best wins
+
+## Squad Awareness
+
+Agents are organized into squads (functional teams):
+
+- **CORE:** architect, dev, qa — Core development team
+- **OPS:** devops, pm, sm — Operations team
+- **PRODUCT:** analyst, po, ux — Product team
+- **DATA:** data-engineer, researcher, scout — Data & research team
+
+When no agents are specified, the system selects from the appropriate squad based on task type.
+
+## Usage
+
+```
+/team_execute coordinate --agents dev,qa --task "Implement and test user auth"
+/team_execute route --task "Deploy staging environment"
+/team_execute broadcast --agents architect,dev --task "Propose database schema"
+```
+
+## Integration
+
+TeamExecutor composes existing execution primitives:
+
+- `ParallelExecutor` for concurrent task execution
+- `SubagentDispatcher` for agent-specific dispatch via Claude CLI
+- `ResultAggregator` for combining multi-agent outputs