@xonovex/skills 0.1.0

package/skills/motion-react-guidelines/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: motion-guidelines
+description: >-
+  Trigger on Motion animations, `whileHover`, `whileInView`, scroll effects, spring physics, gesture animations. Use when creating React animations with Motion. Apply for entrance animations, hover effects, scroll reveals, layout transitions, drag interactions. Keywords: Motion, motion/react, animation, React, spring physics, whileHover, whileTap, useScroll, layoutId, AnimatePresence.
+---
+
+# Motion Animation Guidelines
+
+## Requirements
+
+- Install: `npm install motion`
+- Import: `import { motion } from "motion/react"`
+
+## Essentials
+
+- **Entrance animations** - Use `initial`/`animate` with opacity+transform; 0.6-0.8s duration, ease `[0.22, 1, 0.36, 1]`, see [reference/entrance.md](reference/entrance.md)
+- **Gesture interactions** - Use `whileHover`/`whileTap` with spring physics (stiffness: 300, damping: 20), see [reference/gestures.md](reference/gestures.md)
+- **Scroll effects** - Use `whileInView` with `viewport={{once: true, amount: 0.3}}`; use `useScroll`/`useTransform` for parallax, see [reference/scroll.md](reference/scroll.md)
+- **Layout animations** - Use `layout` prop for automatic FLIP; use `layoutId` for shared element morphing, see [reference/layout.md](reference/layout.md)
+- **Stagger sequences** - Use variants with `staggerChildren: 0.1` and `delayChildren`, see [reference/stagger.md](reference/stagger.md)
+- **Exit animations** - Wrap in `<AnimatePresence>` with `exit` prop, see [reference/exit.md](reference/exit.md)
+- **Performance** - Only animate transform/opacity; use `useReducedMotion()` for accessibility, see [reference/performance.md](reference/performance.md)
+
+## Example
+
+```tsx
+import {motion} from "motion/react";
+
+export function FadeUp({children}: {children: React.ReactNode}) {
+  return (
+    <motion.div
+      initial={{opacity: 0, y: 20}}
+      animate={{opacity: 1, y: 0}}
+      transition={{duration: 0.6, ease: [0.22, 1, 0.36, 1]}}
+    >
+      {children}
+    </motion.div>
+  );
+}
+
+export function HoverCard({children}: {children: React.ReactNode}) {
+  return (
+    <motion.div
+      whileHover={{y: -8, boxShadow: "0 20px 40px rgba(0,0,0,0.12)"}}
+      transition={{type: "spring", stiffness: 300, damping: 20}}
+    >
+      {children}
+    </motion.div>
+  );
+}
+```
+
+## Progressive Disclosure
+
+- Read [reference/entrance.md](reference/entrance.md) - When creating fade-in, slide-up, or hero animations
+- Read [reference/gestures.md](reference/gestures.md) - When adding hover, tap, or focus interactions
+- Read [reference/scroll.md](reference/scroll.md) - When building scroll reveals or parallax effects
+- Read [reference/layout.md](reference/layout.md) - When animating layout changes or shared elements
+- Read [reference/stagger.md](reference/stagger.md) - When orchestrating sequential child animations
+- Read [reference/exit.md](reference/exit.md) - When animating component unmounting
+- Read [reference/spring-physics.md](reference/spring-physics.md) - When tuning spring stiffness, damping, mass
+- Read [reference/motion-values.md](reference/motion-values.md) - When using useMotionValue, useSpring, useTransform, useAnimate, or MotionConfig
+- Read [reference/performance.md](reference/performance.md) - When optimizing animations or supporting reduced motion
+- Read [reference/svg-path.md](reference/svg-path.md) - When animating SVG paths or strokes
+- Read [reference/3d-effects.md](reference/3d-effects.md) - When creating 3D cards, perspective, or rotations
+- Read [reference/text-effects.md](reference/text-effects.md) - When animating text reveals, scramble, or typewriter effects

package/skills/motion-react-guidelines/reference/3d-effects.md

@@ -0,0 +1,35 @@
+# filename: 3d-effects
+
+**Guideline:** Set `perspective` on parent; use `transformStyle: "preserve-3d"` on children; drive 3D via `useMotionValue` + `useSpring`.
+
+**Rationale:** Perspective creates 3D depth; preserve-3d enables layering; motion values drive smooth tilt/flip without re-renders.
+
+**Example:**
+```tsx
+function Card3D({children}: {children: React.ReactNode}) {
+  const x = useMotionValue(0);
+  const y = useMotionValue(0);
+  const rotateX = useSpring(useTransform(y, [-0.5, 0.5], [15, -15]));
+  const rotateY = useSpring(useTransform(x, [-0.5, 0.5], [-15, 15]));
+
+  return (
+    <motion.div
+      style={{rotateX, rotateY, transformStyle: "preserve-3d"}}
+      onMouseMove={(e) => {
+        const rect = e.currentTarget.getBoundingClientRect();
+        x.set((e.clientX - rect.left) / rect.width - 0.5);
+      }}
+    >
+      {children}
+    </motion.div>
+  );
+}
+```
+
+**Techniques:**
+- Parent perspective: `style={{perspective: 1000}}`; higher = less depth distortion
+- Flip cards: `animate={{rotateY: isFlipped ? 180 : 0}}`; use `backfaceVisibility: "hidden"`
+- 3D carousel: Position items with `rotateY(angle)` and `translateZ()` in transforms
+- Layered stacks: `translateZ(i * 20px)` for depth; `whileHover={{rotateX, rotateY}}` on container
+- Shine effect: Use `useTransform()` to derive shine position from mouse coordinates; gradient follows
+- Transform properties: `rotateX/Y/Z`, `x/y/z`, `scale/scaleX/Y/Z`, `transformOrigin`

package/skills/motion-react-guidelines/reference/entrance.md

@@ -0,0 +1,36 @@
+# filename: entrance
+
+**Guideline:** Use `initial`/`animate` with opacity and transforms (y, x, scale); apply Apple easing `[0.22, 1, 0.36, 1]` for smooth deceleration.
+
+**Rationale:** Opacity + transforms are GPU-optimized; transforms avoid layout thrashing; easing creates polished, professional feel.
+
+**Example:**
+```tsx
+function FadeUp({children}) {
+  return (
+    <motion.div
+      initial={{opacity: 0, y: 20}}
+      animate={{opacity: 1, y: 0}}
+      transition={{duration: 0.6, ease: [0.22, 1, 0.36, 1]}}
+    >
+      {children}
+    </motion.div>
+  );
+}
+
+// Staggered hero
+<motion.section initial="hidden" animate="visible"
+  variants={{visible: {transition: {staggerChildren: 0.15}}}}>
+  <motion.h1 variants={{hidden: {opacity: 0, y: 30}, visible: {opacity: 1, y: 0}}} />
+</motion.section>
+```
+
+**Techniques:**
+- Fade up: `initial={{opacity: 0, y: 20}}` → `animate={{opacity: 1, y: 0}}`
+- Fade in scale: `initial={{opacity: 0, scale: 0.95}}` for zoom-in effect
+- Slide directions: `x: -50` (left), `x: 50` (right), `y: 50` (bottom)
+- Spring entrance: `type: "spring", stiffness: 300, damping: 20` for bouncy
+- Duration hierarchy: Headlines 0.8s, subheadings 0.6s, body 0.5s, small 0.3-0.4s
+- Stagger children: Parent variant with `staggerChildren: 0.1-0.15` for cascading
+- Apple easing: `ease: [0.22, 1, 0.36, 1]` for professional smooth deceleration
+- Always combine opacity with transform for optimal performance; never use margin for animation

package/skills/motion-react-guidelines/reference/exit.md

@@ -0,0 +1,35 @@
+# filename: exit
+
+**Guideline:** Wrap conditionally rendered elements in `<AnimatePresence>` to enable exit animations; React removes elements instantly without it.
+
+**Rationale:** AnimatePresence delays DOM removal until exit animation completes; enables smooth transitions and proper cleanup.
+
+**Example:**
+```tsx
+function Modal({isOpen, onClose}) {
+  return (
+    <AnimatePresence>
+      {isOpen && (
+        <motion.div
+          initial={{opacity: 0, scale: 0.95}}
+          animate={{opacity: 1, scale: 1}}
+          exit={{opacity: 0, scale: 0.95}}
+          transition={{type: "spring", stiffness: 300}}
+        >
+          Modal content
+        </motion.div>
+      )}
+    </AnimatePresence>
+  );
+}
+```
+
+**Techniques:**
+- Always wrap conditionals: `<AnimatePresence>{condition && <motion.div exit={{...}} />}</AnimatePresence>`
+- Unique keys: Required for list animations; prevents animation identity loss on reorder
+- Exit modes: `"sync"` (enter/exit simultaneous), `"wait"` (exit first, then enter), `"popLayout"` (exit removed from flow)
+- Exit callbacks: `onExitComplete={() => {...}}` fires when all exit animations finish
+- Page transitions: Use `key={location.pathname}` with router to trigger exit/enter on route change
+- List animations: `height: 0` on exit shrinks before removal; `opacity: 0` fades
+- Staggered exit: Use parent variant with `staggerDirection: -1` to reverse animation order
+- Modal backdrop: Animate both backdrop (fade) and content (scale) simultaneously for depth

package/skills/motion-react-guidelines/reference/gestures.md

@@ -0,0 +1,23 @@
+# gestures: Gesture Interactions
+
+**Guideline:** Use whileHover/whileTap/whileFocus with spring physics; never use duration for gestures (springs feel responsive).
+
+**Rationale:** Spring transitions feel instantaneous and natural; duration-based easing delays feedback.
+
+**Example:**
+```tsx
+<motion.button
+  whileHover={{scale: 1.05}}
+  whileTap={{scale: 0.95}}
+  whileFocus={{boxShadow: "0 0 0 3px rgba(66, 153, 225, 0.6)"}}
+  transition={{type: "spring", stiffness: 400, damping: 25}}
+/>
+```
+
+**Techniques:**
+- whileHover/whileTap/whileFocus: Gesture states; always use spring transitions
+- Spring presets: Snappy (buttons) 400/25, smooth (cards) 300/20, bouncy 200/10
+- Hover effects: y: -8, boxShadow, scale 1.02-1.05
+- Magnetic button: useMotionValue + useSpring for cursor tracking
+- Dock scaling: Distance-based proximity effect via Math.abs(index - hovered)
+- Accessibility: Include whileFocus for keyboard users; test with Tab key

package/skills/motion-react-guidelines/reference/layout.md

@@ -0,0 +1,39 @@
+# filename: layout
+
+**Guideline:** Use `layout` prop for automatic FLIP animations on size/position changes; use `layoutId` for shared element transitions between DOM nodes.
+
+**Rationale:** `layout` auto-animates position/size without manually specifying targets; `layoutId` enables seamless transitions across screens (gallery → modal).
+
+**Example:**
+```tsx
+function ExpandingCard({expanded}) {
+  return (
+    <motion.div
+      layout
+      style={{width: expanded ? 400 : 200}}
+      transition={{type: "spring", stiffness: 300}}
+    />
+  );
+}
+
+// Shared element transition
+<motion.div layoutId={`card-${id}`} onClick={() => setSelected(item)}>
+  <motion.img layoutId={`image-${id}`} src={item.image} />
+</motion.div>
+
+{selected && (
+  <motion.div layoutId={`card-${selected.id}`} style={{position: "fixed"}}>
+    <motion.img layoutId={`image-${selected.id}`} src={selected.image} />
+  </motion.div>
+)}
+```
+
+**Techniques:**
+- `layout`: Animate position and size changes automatically (FLIP algorithm)
+- `layout="position"`: Only position (for text); `layout="size"`: Only size
+- `layoutId`: Same ID on elements across different DOM states for smooth morphing
+- `<Reorder.Group values={items} onReorder={setItems}>`: Drag-to-reorder with auto-layout
+- `<Reorder.Item value={item}>`: Draggable list item
+- Accordion: Combine `layout` with `AnimatePresence` for smooth expand/collapse
+- Tabs indicator: `layoutId="tab-indicator"` + conditional render for smooth underline transition
+- Always wrap conditional elements in `<AnimatePresence>` for exit animations

package/skills/motion-react-guidelines/reference/motion-values.md

@@ -0,0 +1,33 @@
+# filename: motion-values
+
+**Guideline:** Use `useMotionValue` for high-frequency updates (mouse, scroll) without re-renders; derive with `useTransform`; smooth with `useSpring`.
+
+**Rationale:** Motion values bypass React rendering; enables 60fps tracking; perfect for animations that don't need state.
+
+**Example:**
+```tsx
+function MouseTracker() {
+  const x = useMotionValue(0);
+  const springX = useSpring(x, {stiffness: 150, damping: 15});
+
+  return (
+    <div onMouseMove={(e) => x.set(e.clientX)}>
+      <motion.div style={{x: springX}} />
+    </div>
+  );
+}
+
+// Derive multiple values from one source
+const background = useTransform(x, [-100, 0, 100], ["red", "white", "green"]);
+const scale = useTransform(x, [-100, 100], [0.5, 1.5]);
+```
+
+**Techniques:**
+- `useMotionValue(initial)`: Create raw value; `.set()` updates without renders
+- `useTransform(value, [input], [output])`: Map range; supports colors, strings, numbers
+- `useSpring(value, config)`: Add spring physics (stiffness, damping, mass)
+- `useMotionTemplate`: Dynamic CSS strings with backticks: `` `radial-gradient(... ${x}px ...)` ``
+- `useScroll()`: Returns `scrollX`/`scrollY`/`scrollXProgress`/`scrollYProgress` (0-1)
+- Subscription: `value.on("change", latest => {...})`; unsubscribe in cleanup
+- `useAnimate()`: Imperative control - `const [scope, animate] = useAnimate()`, then `await animate(scope.current, {...})`
+- Performance: Never use state for real-time values; motion values skip renders for 60fps tracking

package/skills/motion-react-guidelines/reference/performance.md

@@ -0,0 +1,32 @@
+# performance: Performance and Accessibility
+
+**Guideline:** Animate only GPU-accelerated transforms (x/y/scale/rotate) and opacity; use scaleX/Y or layout for size changes; support prefers-reduced-motion.
+
+**Rationale:** Transform/opacity don't trigger layout recalculation; width/height cause jank. Respecting prefers-reduced-motion is legal requirement (WCAG 2.1).
+
+**Example:**
+```tsx
+import {motion, useReducedMotion} from "motion/react";
+
+function AccessibleDiv({children}) {
+  const shouldReduceMotion = useReducedMotion();
+  return (
+    <motion.div
+      initial={shouldReduceMotion ? false : {opacity: 0, y: 20}}
+      animate={{opacity: 1, y: 0}}
+      transition={shouldReduceMotion ? {duration: 0} : {duration: 0.6}}
+    >
+      {children}
+    </motion.div>
+  );
+}
+```
+
+**Techniques:**
+- GPU-accelerated: x, y, z, scale, rotate, opacity, skew (no layout recalc)
+- Never animate: width, height, margin, padding, left/top/right/bottom (triggers jank)
+- useReducedMotion(): Check for prefers-reduced-motion; skip animations if true
+- Layout prop: Use `layout` for size/position changes instead of animating dimensions
+- LazyMotion: Wrap app with LazyMotion + domAnimation to reduce bundle (use `m` instead of `motion`)
+- willChange: Add for high-frequency animations
+- Accessible wrapper: Create MotionSafe component that skips animations for reduced-motion users

package/skills/motion-react-guidelines/reference/scroll.md

@@ -0,0 +1,38 @@
+# filename: scroll
+
+**Guideline:** Use `whileInView` for scroll-triggered reveals; use `useScroll()` + `useTransform()` for precise parallax and scroll-linked effects.
+
+**Rationale:** `whileInView` leverages Intersection Observer; `useScroll()` enables smooth parallax without scroll listeners; `useTransform` maps scroll range to outputs.
+
+**Example:**
+```tsx
+function ScrollReveal({children}) {
+  return (
+    <motion.div
+      initial={{opacity: 0, y: 50}}
+      whileInView={{opacity: 1, y: 0}}
+      viewport={{once: true, amount: 0.3}}
+      transition={{duration: 0.6}}
+    >
+      {children}
+    </motion.div>
+  );
+}
+
+// Parallax
+function Parallax() {
+  const ref = useRef(null);
+  const {scrollYProgress} = useScroll({target: ref, offset: ["start end", "end start"]});
+  const backgroundY = useTransform(scrollYProgress, [0, 1], [0, -150]);
+  return <motion.div ref={ref} style={{y: backgroundY}} />;
+}
+```
+
+**Techniques:**
+- `whileInView`: Animates when element enters viewport; `viewport={{once: true, amount: 0.3}}` triggers at 30% visible
+- `useScroll()`: Returns `scrollX/Y` and `scrollXProgress/scrollYProgress` (0-1 normalized)
+- `useTransform(scrollProgress, [0, 1], [outputStart, outputEnd])`: Map scroll to colors, positions, scale
+- `useInView(ref, {once: true})`: Imperative boolean hook for manual control
+- Staggered scroll reveal: `variants` with `staggerChildren` inside `whileInView`
+- Scroll progress bar: `scaleX: scrollYProgress` with `transformOrigin: "left"`
+- Viewport options: `amount` (0-1), `margin` (CSS pixels), `once: true` (single animation)

package/skills/motion-react-guidelines/reference/spring-physics.md

@@ -0,0 +1,40 @@
+# filename: spring-physics
+
+**Guideline:** Use `type: "spring"` for interactive gestures; adjust `stiffness` (speed), `damping` (bounce), `mass` (weight) for feel.
+
+**Rationale:** Spring animations are interruptible and natural; duration animations are rigid but synchronized; match animation type to use case.
+
+**Example:**
+```tsx
+// Snappy (buttons, quick interactions)
+<motion.div
+  whileHover={{scale: 1.05}}
+  transition={{type: "spring", stiffness: 400, damping: 25}}
+/>
+
+// Bouncy (playful entrance)
+<motion.div
+  initial={{scale: 0.9}}
+  animate={{scale: 1}}
+  transition={{type: "spring", stiffness: 200, damping: 8}}
+/>
+
+// Smooth (cards, panels)
+<motion.div
+  whileHover={{y: -8}}
+  transition={{type: "spring", stiffness: 300, damping: 20}}
+/>
+```
+
+**Techniques:**
+- `stiffness: 100-500`: Response speed; higher = faster snap to target
+- `damping: 10-50`: Bounce control; higher = less bouncy/overshoot
+- `mass: 0.5-3`: Perceived weight; higher = heavier, slower response
+- Snappy preset: `stiffness: 400, damping: 25` for buttons, quick feedback
+- Smooth preset: `stiffness: 300, damping: 20` for regular elements
+- Bouncy preset: `stiffness: 200, damping: 8` for attention-grabbing/playful
+- Heavy preset: `stiffness: 100, damping: 15, mass: 2` for modals, large elements
+- Gentle preset: `stiffness: 150, damping: 15` for subtle, understated movements
+- Use `useSpring()` hook for smoothing raw motion values (mouse tracking, scroll)
+- Spring for: Gestures, hover, tap, drag interactions, interactive feedback, layout changes
+- Duration for: Entrance sequences, scroll reveals, page transitions, synchronized multi-element animations

package/skills/motion-react-guidelines/reference/stagger.md

@@ -0,0 +1,34 @@
+# filename: stagger
+
+**Guideline:** Use `staggerChildren` in parent variant transitions to orchestrate sequential child animations; never use manual delays.
+
+**Rationale:** Variants + stagger maintains maintainability; auto-sequencing prevents timing bugs; reversible with `staggerDirection: -1`.
+
+**Example:**
+```tsx
+const container = {
+  hidden: {},
+  visible: {
+    transition: {staggerChildren: 0.1, delayChildren: 0.2}
+  }
+};
+const item = {
+  hidden: {opacity: 0, y: 20},
+  visible: {opacity: 1, y: 0, transition: {duration: 0.5}}
+};
+
+<motion.ul variants={container} initial="hidden" animate="visible">
+  {items.map((i, idx) => (
+    <motion.li key={idx} variants={item}>{i}</motion.li>
+  ))}
+</motion.ul>
+```
+
+**Techniques:**
+- Parent variant: `staggerChildren` (per-child delay), `delayChildren` (initial delay before first)
+- Child variant: individual `initial`/`visible`/`exit` states
+- Grid stagger: 0.02-0.05 for dense layouts; 0.08-0.12 for lists; 0.15-0.2 for hero sections
+- Reverse exit: `exit: {transition: {staggerDirection: -1}}` for backwards animation
+- Scroll trigger: `whileInView="visible"` + `viewport={{once: true}}` for scroll-triggered stagger
+- Always use unique `key` on list items for proper animation tracking
+- Never use `delay: i * 0.1`; always use variants + staggerChildren for maintainability

package/skills/motion-react-guidelines/reference/svg-path.md

@@ -0,0 +1,33 @@
+# filename: svg-path
+
+**Guideline:** Animate SVG paths with `pathLength` from 0 to 1 for drawing effects; pair with `opacity` for simultaneous fade-in.
+
+**Rationale:** Motion's `pathLength` auto-calculates stroke-dash math; simpler than manual `strokeDasharray`/`strokeDashoffset`.
+
+**Example:**
+```tsx
+function DrawingIcon() {
+  return (
+    <svg width="100" height="100" viewBox="0 0 100 100">
+      <motion.path
+        d="M 10 50 Q 50 10 90 50 Q 50 90 10 50"
+        fill="none"
+        stroke="#667eea"
+        strokeWidth={2}
+        initial={{pathLength: 0, opacity: 0}}
+        animate={{pathLength: 1, opacity: 1}}
+        transition={{duration: 1.5}}
+      />
+    </svg>
+  );
+}
+```
+
+**Techniques:**
+- Path animation: `initial={{pathLength: 0}}` → `animate={{pathLength: 1}}`; 0-1 range
+- Staggered paths: Use `variants` + `custom` prop for per-path delays
+- Progress circles: `animate={{pathLength: progress}}` (0 to dynamic value)
+- Checkmarks: Combine `pathLength` animation with `opacity` transition on different durations
+- Flowing lines: Use `strokeDasharray="10 5"` + `strokeDashoffset: [0, -30]` with `repeat: Infinity`
+- Connection lines: Bezier curves `C` command for smooth connections; `rotateY` adjustment for vertical lines
+- Stroke caps: `strokeLinecap="round"` + `strokeLinejoin="round"` for smoother endpoints

package/skills/motion-react-guidelines/reference/text-effects.md

@@ -0,0 +1,39 @@
+# filename: text-effects
+
+**Guideline:** Split text into words/characters in spans; use `overflow: hidden` with `y: ["100%", 0]` for elegant reveal animations.
+
+**Rationale:** Splitting enables per-element stagger; `overflow: hidden` masks overflow for clean Y-translate reveals; avoid animating entire text blocks.
+
+**Example:**
+```tsx
+function TextReveal({text}) {
+  return (
+    <motion.div initial="hidden" animate="visible" variants={{
+      hidden: {},
+      visible: {transition: {staggerChildren: 0.1}}
+    }}>
+      {text.split(" ").map((word, i) => (
+        <span key={i} style={{display: "inline-block", overflow: "hidden"}}>
+          <motion.span variants={{
+            hidden: {y: "100%", opacity: 0},
+            visible: {y: 0, opacity: 1}
+          }} style={{display: "inline-block"}}>
+            {word}
+          </motion.span>
+          <span>&nbsp;</span>
+        </span>
+      ))}
+    </motion.div>
+  );
+}
+```
+
+**Techniques:**
+- Word reveal: Split by space, `y: ["100%", 0]`, stagger 0.05-0.15
+- Character reveal: Split by `""`, stagger 0.02-0.05, add `y: 20` for bounce effect
+- Typewriter: Use `useState` + `setInterval`, slice() text incrementally, add blinking cursor
+- Wavy text: Per-character `y: [0, -10, 0]` with delay based on index
+- Gradient animation: `backgroundPosition` with `backgroundSize: "300% 100%"`
+- Word highlight: Overlay `scaleX: 0` → `scaleX: 1` highlight box behind word
+- Overflow masking: Always wrap in `<span style={{overflow: "hidden"}}>` for clean reveals
+- Keep stagger delays small: 0.02-0.1 for natural flow

package/skills/plan-guidelines/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: plan-guidelines
+description: >-
+  Trigger on planning sessions, research tasks, architecture decisions. Use when planning research and analysis tasks. Apply for code alignment, simplification, hardening, template extraction. Keywords: research, planning, task breakdown, code analysis, refactoring, template extraction, shared libraries, TODO scanning.
+---
+
+# Planning Research Guidelines
+
+## Core Principles
+
+- **Research First** - Analyze before creating implementation plans, see [reference/general-research.md](reference/general-research.md)
+- **Use Task Agents** - Leverage Explore subagent with model=haiku, see [reference/general-research.md](reference/general-research.md)
+- **Validation Required** - All analysis validates with typecheck/lint/build
+- **Reports, Not Code** - Research generates reports without modifications
+
+## Research Workflow
+
+- **Launch Exploration** - Use Task tool with subagent_type=Explore and model=haiku
+- **Analyze and Report** - Process results, identify patterns, document findings
+
+## Planning Workflow
+
+- **Create Implementation Plan** - Document architecture, technology choices, create tasks, see [reference/plan-create.md](reference/plan-create.md)
+- **Break Down Work** - Use TaskCreate for each step with subject/description/activeForm
+- **Define Dependencies** - Use TaskUpdate to set blockedBy/blocks relationships
+- **Track Progress** - Use TaskList, TaskGet, TaskUpdate to manage execution
+
+## Skills to Consult
+
+- **Include in all plans** - Add "Skills to consult:" section with comma-separated list, see [reference/plan-create.md](reference/plan-create.md)
+
+## Progressive Disclosure
+
+### Research Analysis
+- Read [reference/general-research.md](reference/general-research.md) - Research codebase and web for requirements
+- Read [reference/code-align.md](reference/code-align.md) - Compare two similar implementations
+- Read [reference/code-barrels-remove.md](reference/code-barrels-remove.md) - Analyze barrel exports for removal
+- Read [reference/code-comments-remove.md](reference/code-comments-remove.md) - Identify non-essential comments
+- Read [reference/code-harden.md](reference/code-harden.md) - Improve type safety and error handling
+- Read [reference/code-shared-extract.md](reference/code-shared-extract.md) - Find duplicated patterns to extract
+- Read [reference/code-simplify.md](reference/code-simplify.md) - Reduce code complexity
+- Read [reference/code-template-extract.md](reference/code-template-extract.md) - Create reusable templates
+- Read [reference/code-template-scaffold.md](reference/code-template-scaffold.md) - Generate from templates
+- Read [reference/todos.md](reference/todos.md) - Scan and group TODO comments
+
+### Plan Creation
+- Read [reference/plan-create.md](reference/plan-create.md) - Create plan with task breakdown and dependencies
+- Read [reference/plan-tdd-create.md](reference/plan-tdd-create.md) - Create TDD plan with sequential RED-GREEN-COMMIT tasks
+
+## Task Management
+
+- **TaskCreate** - Create with subject, description, activeForm
+- **TaskUpdate** - Set dependencies (addBlockedBy/addBlocks), update status
+- **TaskList** - View all tasks with status and dependencies
+- **TaskGet** - Retrieve full details before starting work
+- **Dependencies** - Independent (no blockedBy), Sequential (set blockedBy), TDD (strict order)

package/skills/plan-guidelines/reference/code-align.md

@@ -0,0 +1,23 @@
+# code-align: Analyze Code Alignment Between Similar Implementations
+
+**Guideline:** Compare implementations to identify structural differences, inconsistencies, and alignment opportunities.
+
+**Rationale:** Similar code should follow consistent patterns. Identifies bugs from missing error handling, outdated APIs, or logic differences.
+
+**Example:**
+```
+// Compare two API implementations
+File A: imports v3.5, uses async/await, has try-catch
+File B: imports v2.1, uses callbacks, missing error handling
+
+Report: Version mismatch (v3.5 vs v2.1), pattern divergence (async vs callback)
+```
+
+**Techniques:**
+- Load both files and detect code type (TypeScript, Python, Go, etc.)
+- Compare imports, dependencies, and version constraints across implementations
+- Analyze interfaces, types, and function signatures for structural differences
+- Examine error handling patterns, validation logic, and edge cases
+- Review code organization, constants, and configuration defaults
+- Generate alignment report with percentage match and critical differences
+- Document recommendations for standardizing diverged implementations

package/skills/plan-guidelines/reference/code-barrels-remove.md

@@ -0,0 +1,24 @@
+# code-barrels-remove: Analyze Sub-Directory Barrel Exports for Removal
+
+**Guideline:** Identify sub-directory barrel files for removal and convert imports to direct file paths.
+
+**Rationale:** Sub-barrels add indirection without clear benefits. Removing them simplifies navigation, makes imports explicit, and reduces circular dependency risks.
+
+**Example:**
+```typescript
+// Before: Barrel indirection
+import { User, Role } from './auth'  // From src/auth/index.ts
+
+// After: Direct imports
+import { User } from './auth/user'
+import { Role } from './auth/role'
+```
+
+**Techniques:**
+- Find all `index.ts`/`index.js` files in subdirectories (exclude root `src/index.ts`)
+- Confirm each is a barrel by verifying it contains only re-exports
+- Search for all imports from sub-barrel paths (pattern: `from "./subdir"`)
+- Map each import to its actual source files to understand impact
+- Update root barrel to convert relative paths to direct source context
+- Track all usages across codebase and plan import migrations
+- Generate report with line savings, import count, and deletion plan

package/skills/plan-guidelines/reference/code-comments-remove.md

@@ -0,0 +1,28 @@
+# code-comments-remove: Identify Non-Essential Comments for Removal
+
+**Guideline:** Analyze and remove non-essential comments while preserving functional directives.
+
+**Rationale:** Self-documenting code preferred over comments. Remove explanatory, obvious, and commented-out code while preserving functional directives (eslint-disable, @ts-expect-error, TODO).
+
+**Example:**
+```typescript
+// REMOVE: Redundant comment
+// Get the user ID
+const userId = user.id
+
+// KEEP: Functional directive
+// eslint-disable-next-line no-unsafe-optional-chaining
+const role = user?.profile?.role?.name
+
+// REMOVE: Commented-out code
+// const oldUserId = user.legacy_id
+```
+
+**Techniques:**
+- Detect comment syntax by language (C-style: `//`, `/* */`; hash-style: `#`)
+- Distinguish functional directives (eslint, prettier, type hints) from explanatory comments
+- Identify and categorize comments: explanatory, obvious, or commented-out code blocks
+- Preserve critical directives: TODO, FIXME, @ts-expect-error, eslint-disable, go:generate, etc.
+- Flag explanatory comments that duplicate clear code logic
+- Find commented-out code blocks for removal (often outdated)
+- Generate removal report with counts by category and impact summary