@minhduydev/mdpi 0.4.0 → 0.5.0

package/dist/template/.pi/skills/zustand/SKILL.md

@@ -0,0 +1,333 @@
+---
+name: zustand
+description: Use when implementing global or shared state management in React with Zustand v5. Covers store creation, slices pattern, middleware, selective subscriptions, React 19 + SSR integration. MUST load before any state management implementation.
+---
+
+# Zustand v5
+
+## When to Use
+
+- Managing global or shared client-side state in React
+- Replacing Redux, Jotai, or Context for state management
+- Creating stores that are used across multiple components
+- Implementing slices for domain-separated state
+- Persisting state to localStorage or sessionStorage
+- Using middleware (immer, devtools, persist)
+
+## When NOT to Use
+
+- Server state (use TanStack Query or Server Components)
+- Form state (use React Hook Form or Server Actions)
+- Single-component local state (use `useState` or `useReducer`)
+- Server Components (Zustand is client-only)
+
+## Setup
+
+```bash
+npm install zustand
+```
+
+## Basic Store
+
+```tsx
+// stores/counter.ts
+import { create } from 'zustand'
+
+interface CounterState {
+  count: number
+  increment: () => void
+  decrement: () => void
+  reset: () => void
+}
+
+export const useCounterStore = create<CounterState>((set) => ({
+  count: 0,
+  increment: () => set((state) => ({ count: state.count + 1 })),
+  decrement: () => set((state) => ({ count: state.count - 1 })),
+  reset: () => set({ count: 0 }),
+}))
+```
+
+```tsx
+// components/Counter.tsx
+'use client'
+
+import { useCounterStore } from '@/stores/counter'
+
+export function Counter() {
+  const { count, increment, decrement } = useCounterStore()
+
+  return (
+    <div>
+      <p>Count: {count}</p>
+      <button onClick={increment}>+</button>
+      <button onClick={decrement}>-</button>
+    </div>
+  )
+}
+```
+
+## Slices Pattern
+
+Split store into domain slices:
+
+```tsx
+// stores/index.ts
+import { create } from 'zustand'
+import { createAuthSlice, type AuthSlice } from './slices/auth'
+import { createCartSlice, type CartSlice } from './slices/cart'
+
+type Store = AuthSlice & CartSlice
+
+export const useStore = create<Store>()((...args) => ({
+  ...createAuthSlice(...args),
+  ...createCartSlice(...args),
+}))
+```
+
+```tsx
+// stores/slices/auth.ts
+import type { StateCreator } from 'zustand'
+
+export interface AuthSlice {
+  user: User | null
+  login: (credentials: Credentials) => Promise<void>
+  logout: () => void
+}
+
+export const createAuthSlice: StateCreator<AuthSlice, [], [], AuthSlice> = (set) => ({
+  user: null,
+  login: async (credentials) => {
+    const user = await api.login(credentials)
+    set({ user })
+  },
+  logout: () => set({ user: null }),
+})
+```
+
+## Selective Subscriptions
+
+Zustand re-renders only when **used** state changes:
+
+```tsx
+// ❌ Whole store — re-renders on any change
+const { count, name } = useStore()
+
+// ✅ Selective — re-renders only when count changes
+const count = useStore((state) => state.count)
+const increment = useStore((state) => state.increment) // Stable reference
+
+// ✅ Multiple values — useShallow for objects
+import { useShallow } from 'zustand/react/shallow'
+
+const { name, email } = useStore(
+  useShallow((state) => ({ name: state.user.name, email: state.user.email }))
+)
+```
+
+`useShallow` does shallow equality — avoids re-render when both values are the same.
+
+## Middleware
+
+### Persist (localStorage)
+
+```tsx
+import { create } from 'zustand'
+import { persist } from 'zustand/middleware'
+
+export const useSettingsStore = create(
+  persist(
+    (set) => ({
+      theme: 'light',
+      setTheme: (theme: 'light' | 'dark') => set({ theme }),
+    }),
+    {
+      name: 'app-settings',  // localStorage key
+      partialize: (state) => ({ theme: state.theme }),  // Only persist theme
+    }
+  )
+)
+```
+
+### Immer (Immutable Updates)
+
+```tsx
+import { create } from 'zustand'
+import { immer } from 'zustand/middleware/immer'
+
+export const useTodoStore = create(
+  immer((set) => ({
+    todos: [] as Todo[],
+    addTodo: (text: string) =>
+      set((state) => {
+        state.todos.push({ id: crypto.randomUUID(), text, done: false })
+      }),
+    toggleTodo: (id: string) =>
+      set((state) => {
+        const todo = state.todos.find((t) => t.id === id)
+        if (todo) todo.done = !todo.done
+      }),
+  }))
+)
+```
+
+### DevTools
+
+```tsx
+import { create } from 'zustand'
+import { devtools } from 'zustand/middleware'
+
+export const useStore = create(
+  devtools(
+    (set) => ({
+      count: 0,
+      increment: () => set((s) => ({ count: s.count + 1 }), false, 'increment'),
+    }),
+    { name: 'AppStore' }  // Name in Redux DevTools
+  )
+)
+```
+
+### Combining Multiple Middleware
+
+```tsx
+import { create } from 'zustand'
+import { devtools, persist, immer } from 'zustand/middleware'
+
+export const useStore = create(
+  devtools(
+    persist(
+      immer((set) => ({
+        // store...
+      })),
+      { name: 'app-storage' }
+    ),
+    { name: 'AppStore' }
+  )
+)
+```
+
+## React 19 + Server Components
+
+Zustand is **client-only**. Pattern for Next.js App Router:
+
+```tsx
+// stores/useStore.ts
+import { create } from 'zustand'
+
+export const useStore = create<Store>((set) => ({
+  // ...
+}))
+```
+
+```tsx
+// components/ClientWrapper.tsx
+'use client'
+
+import { useStore } from '@/stores/useStore'
+
+export function ClientWrapper({ children }) {
+  const data = useStore((s) => s.data)
+
+  return <div>{children}</div>
+}
+```
+
+**Rules**:
+- Stores are defined outside components (module scope)
+- Store consumers must be in `'use client'` components
+- Server Components can import the store type but cannot `useStore()`
+- Use React Context to provide a store instance if you need SSR hydration
+
+## SSR Hydration Pattern
+
+```tsx
+// app/providers.tsx
+'use client'
+
+import { type ReactNode, createContext, useContext, useRef } from 'react'
+import { type StoreApi, useStore } from 'zustand'
+
+// Create context for store
+const StoreContext = createContext<StoreApi<AppStore> | null>(null)
+
+export function StoreProvider({ children }: { children: ReactNode }) {
+  const storeRef = useRef<StoreApi<AppStore>>()
+
+  if (!storeRef.current) {
+    storeRef.current = createAppStore()
+  }
+
+  return (
+    <StoreContext.Provider value={storeRef.current}>
+      {children}
+    </StoreContext.Provider>
+  )
+}
+
+// Hook to use the store
+export function useAppStore<T>(selector: (state: AppStore) => T): T {
+  const store = useContext(StoreContext)
+  if (!store) throw new Error('Missing StoreProvider')
+  return useStore(store, selector)
+}
+```
+
+## Async Actions
+
+```tsx
+// Async actions are just async functions in the store:
+interface UserStore {
+  user: User | null
+  loading: boolean
+  error: Error | null
+  fetchUser: (id: string) => Promise<void>
+}
+
+export const useUserStore = create<UserStore>((set) => ({
+  user: null,
+  loading: false,
+  error: null,
+  fetchUser: async (id) => {
+    set({ loading: true, error: null })
+    try {
+      const user = await api.getUser(id)
+      set({ user, loading: false })
+    } catch (error) {
+      set({ error: error as Error, loading: false })
+    }
+  },
+}))
+```
+
+## When to Use Zustand vs Context vs TanStack Query
+
+| Tool | Best for |
+|------|----------|
+| **Zustand** | Global client state: theme, auth, cart, UI preferences |
+| **React Context** | Dependency injection, theming, auth provider — static values that rarely change |
+| **TanStack Query** | Server state: data fetching, caching, mutations |
+| **useState/useReducer** | Local component state |
+
+## Common Pitfalls
+
+| Pitfall | Fix |
+|---------|-----|
+| Using Zustand for server state | Use TanStack Query for fetched data — Zustand for client-only state |
+| `useStore()` without selector — re-renders on any change | Always use selectors: `useStore(s => s.count)` |
+| Multiple values returned as new object every render | Use `useShallow` for object selectors |
+| Store in Server Component | Move store usage to `'use client'` |
+| `getState()` in render | `getState()` is for callbacks/outside React, not render |
+| Large stores with everything in one file | Use slices pattern to separate domains |
+| Recreating store on every render | Define store outside component or use `useRef` for context pattern |
+
+## Verification
+
+- [ ] Store defined outside component (module scope) or via `useRef` in provider
+- [ ] All store consumers are in `'use client'` components
+- [ ] Selectors used for granular subscriptions — no destructured `useStore()`
+- [ ] `useShallow` used for multi-value object selectors
+- [ ] Server state (fetched data) managed by TanStack Query, not Zustand
+- [ ] Slices pattern used for stores with multiple domains
+- [ ] `persist` middleware configured with `partialize` to avoid storing sensitive data
+- [ ] DevTools middleware enabled (development only)

package/dist/template/.pi/templates/DESIGN.md

@@ -0,0 +1,76 @@
+---
+purpose: Project visual identity — single source of truth for mood, color, typography, layout, elevation, shapes, components, and design constraints.
+updated: 2026-06-19
+---
+
+# DESIGN.md — Project Visual Identity
+
+> **Aesthetic Anchor:** [One evocative sentence referencing a specific era, artifact, or scene — not adjectives. Example: "A 1970s graduate lecture handout, mimeographed on off-white paper."]
+
+## 1. Overview & Mood
+
+- **Mood:** [2-3 words: e.g., "Architectural Minimalism", "Warm Editorial", "Brutalist Terminal"]
+- **Specific Reference:** [A concrete scene, artifact, or era — not abstract adjectives]
+- **Tone:** [Professional / Playful / Serious / Warm / Clinical]
+- **Design Philosophy:** [1-2 sentences on guiding aesthetic principle]
+
+## 2. Colors
+
+- **Brand Palette:** `{colors.brand.primary}` `{colors.brand.secondary}` `{colors.brand.accent}`
+- **Neutral Scale:** `{colors.neutral.50}` → `{colors.neutral.950}` (50/100/200/300/400/500/600/700/800/900/950)
+- **Semantic Colors:** Success `{colors.semantic.success}`, Warning `{colors.semantic.warning}`, Error `{colors.semantic.error}`, Info `{colors.semantic.info}`
+- **Contrast Floor:** WCAG 2.1 AA minimum (≥ 4.5:1 for body text)
+- **No Pure Black:** Use `{colors.neutral.950}` instead of `#000`
+
+## 3. Typography
+
+- **Display Font:** `{typography.display.family}` — for H1, hero headings
+- **Body Font:** `{typography.body.family}` — for paragraphs, UI labels
+- **Mono Font:** `{typography.mono.family}` — for code, data, timestamps
+- **Scale:** `{typography.scale}` (e.g., 12/14/16/18/20/24/30/36/48/60/72)
+- **Weight Range:** `{typography.weights}` (e.g., 400/500/600/700)
+- **Line Height:** 1.5 body, 1.2 headings
+
+## 4. Layout & Spacing
+
+- **Grid Base:** `{layout.grid}` (e.g., 4px or 8px)
+- **Spacing Scale:** `{layout.spacing}` (e.g., 4/8/12/16/24/32/48/64/96)
+- **Max Content Width:** `{layout.maxWidth}` (e.g., 1280px)
+- **Column Count:** `{layout.columns}` (e.g., 12-column grid)
+- **Gutter Width:** `{layout.gutter}` (e.g., 24px)
+
+## 5. Elevation & Depth
+
+- **Shadow Scale:** 5 levels (none / sm / md / lg / xl)
+- **Depth Philosophy:** [Flat / Subtle depth / Heavy layering]
+- **Z-Index Layers:** Base content → Overlays → Modals → Toasts → Tooltips
+- **Border Usage:** When and where borders replace shadows
+
+## 6. Shapes & Corners
+
+- **Border Radius Scale:** `{shapes.borderRadius}` (e.g., 0/4/8/12/16/24/full)
+- **Corner Philosophy:** [Sharp / Soft / Rounded / Pill]
+- **Icon Style:** [Filled / Outline / Duotone / Custom]
+- **Stroke Width:** `{shapes.strokeWidth}` (e.g., 1px or 1.5px)
+
+## 7. Components
+
+- **Button Hierarchy:** Primary `{components.button.primary}` / Secondary `{components.button.secondary}` / Ghost `{components.button.ghost}` / Danger `{components.button.danger}`
+- **Input Style:** [Outlined / Filled / Underlined] with `{components.input.height}` height
+- **Card Style:** [Elevated / Bordered / Flat] with `{components.card.padding}` padding
+- **Modal Style:** [Centered / Slide-up / Fullscreen] with backdrop `{components.modal.backdrop}`
+- **Navigation:** [Top bar / Sidebar / Bottom tabs] with `{components.nav.height}`
+
+## 8. Do's and Don'ts
+
+### Do's
+
+- [Key principle 1 — with reasoning]
+- [Key principle 2 — with reasoning]
+- [Key principle 3 — with reasoning]
+
+### Don'ts
+
+- **Pattern:** [Anti-pattern] — **Replacement:** [Correct approach] — **Because:** [Why this matters]
+- **Pattern:** [Anti-pattern] — **Replacement:** [Correct approach] — **Because:** [Why this matters]
+- **Pattern:** [Anti-pattern] — **Replacement:** [Correct approach] — **Because:** [Why this matters]

package/dist/template/.pi/workflows/INDEX.md

@@ -4,7 +4,7 @@ purpose: Index of DAG workflows with trigger, phases, and invoking command
 
 # Workflows Index
 
-6 DAG workflows. All have `description` frontmatter (for `run_workflow` discovery) and use a consistent Phase format: `Agent`, `Concurrency`, `Depends on`, `Prompt`.
+7 DAG workflows. All have `description` frontmatter (for `run_workflow` discovery) and use a consistent Phase format: `Agent`, `Concurrency`, `Depends on`, `Prompt`.
 
 ## Invocation
 
@@ -24,6 +24,7 @@ Workflows may compose recursively (e.g., `development-lifecycle-workflow` Phase
 | `batch-implement` | 3 + merge | ≥5 independent tasks, no file conflicts | `/ship` Phase 3, `development-lifecycle-workflow` Phase 4 | One subagent per task in parallel, review, merge |
 | `deep-research` | 2 + synthesis | Complex/multi-angle topic | `/research` (complex mode) | Fan out web searches per angle, cross-check, cited report |
 | `development-lifecycle-workflow` | 5 | Explicit full-lifecycle multi-agent run | Manual / future `/lifecycle` | research → validate → plan → implement → verify (composes batch-implement) |
+| `frontend-feature-workflow` | 7 | Frontend feature build (mockup or spec) | `run_workflow({ name: "frontend-feature-workflow", args: { feature: "..." } })` | design analysis → deslop → architecture → craft → implement → harden → audit |
 | `garbage-collection` | 5 | Manual `/gc` or scheduled cadence | `/gc` | Fallow scan → grade → prioritize → optional cleanup PRs |
 | `quality-loop` | 7 (looped) | High-risk feature, explicit quality gating | `/ship` Phase 5 (Iterative Quality Loop) | Score-gated review loop until 5/5 or escalation |