@minhduydev/mdpi 0.3.2 → 0.4.1

package/dist/template/.pi/skills/frontend-design/SKILL.md

@@ -3,6 +3,8 @@ name: frontend-design
 description: MUST load when building any web UI with React-based frameworks — components, pages, or full applications. Covers Tailwind CSS v4, shadcn/ui, Motion animations. Base UI implementation skill; combine with aesthetic overlays (minimalist-ui, high-end-visual-design) for specific styles.
 ---
 
+**Aesthetic Context:** Your implementation must reflect the project `.pi/DESIGN.md` identity. Before writing any component, internalize the Overview & Mood, Colors, and Typography sections. All code output should feel like it belongs to the same intentional design system.
+
 # Frontend Design
 
 ## When to Use
@@ -18,6 +20,17 @@ description: MUST load when building any web UI with React-based frameworks —
 
 - Backend-only tasks or minimal UI with no visual design requirements.
 
+## Relationship to Other Skills
+
+| Skill | Role |
+|-------|------|
+| `design-taste-frontend` | Upstream — sets aesthetic baseline and anti-AI-slops. Load BEFORE this skill. |
+| `frontend-ui-engineering` | Sibling — handles component implementation, accessibility, and state patterns. |
+| `react-best-practices` | Complement — React/Next.js performance patterns. |
+| `baseline-ui` | Quick deslop pass for automatic fixes (spacing, typography). |
+
+**Pipeline:** `design-taste-frontend` → `frontend-design` → `frontend-ui-engineering`
+
 ## Reference Documentation
 
 ### Tailwind CSS v4.1
@@ -67,7 +80,7 @@ For sophisticated compositions: posters, brand materials, design systems.
 - `./references/design/interaction.md` - State models, focus, dialogs/popovers, loading patterns
 - `./references/design/ux-writing.md` - Button copy, error structure, empty states, i18n
 
-Search: `AI Slop Test`, `tinted neutrals`, `focus-visible`, `verb + object`, `65ch`
+Search: `tinted neutrals`, `focus-visible`, `verb + object`, `65ch`
 
 ## Design Thinking
 
@@ -79,49 +92,56 @@ Before coding, commit to BOLD aesthetic direction:
 
 Bold maximalism and refined minimalism both work. Key is intentionality.
 
-## Anti-Patterns (AI Fingerprints — NEVER)
-
-These patterns immediately signal "AI made this." Avoid them all.
+## Don't
 
 ### Typography
 
-- **Banned fonts**: Inter, Roboto, Arial, Open Sans, Lato, Montserrat, Space Grotesk, system-ui as display font
-- Monospace used as "developer aesthetic" shorthand
-- Big icons centered above every heading
-- Using `px` for body text (use `rem`/`em` to respect user settings)
+| Pattern | Replacement | Because |
+|---------|-------------|---------|
+| Inter, Roboto, Arial as display fonts | Distinctive display fonts (Instrument Sans, Outfit, Fraunces) | Overused fonts signal generic design |
+| Monospace used as "developer aesthetic" shorthand | Purposeful type choice; mono only for code/data | Mono-as-aesthetic reads as placeholder design |
+| Big icons centered above every heading | Integrated icon + heading lockup, or icon inline | Giant centered icons feel template-generated |
+| Using `px` for body text | `rem`/`em` to respect user font-size preferences | `px` ignores accessibility and user settings |
 
 ### Color
 
-- **AI palette**: Cyan-on-dark, purple-to-blue gradients, neon accents on dark backgrounds
-- Gray text on colored backgrounds (use darker shade of background color instead)
-- Pure `#000` or `#fff` (always tint — pure black/white don't exist in nature)
-- Gradient text on headings or metrics
-- `rgba()` / heavy alpha transparency as primary palette (design smell — define explicit colors)
+| Pattern | Replacement | Because |
+|---------|-------------|---------|
+| Gray text on colored backgrounds | Darker shade of the background color | Gray-on-color fails contrast and looks muddy |
+| Pure `#000` or `#fff` | Tinted near-black or near-white | Pure black/white don't exist in natural light |
+| Gradient text on headings or metrics | Solid, well-chosen heading color | Gradient text is a design crutch |
+| `rgba()` / heavy alpha transparency as primary palette | Explicit, named color values | Heavy alpha stacking creates unpredictable colors |
 
 ### Layout
 
-- Cards nested inside cards (use typography, spacing, dividers for hierarchy within a card)
-- Identical card grids (icon + heading + text repeated 3-6 times)
-- Hero metric template (big number + small label + gradient accent)
-- Center-aligning everything
-- Same spacing everywhere (no visual rhythm)
+| Pattern | Replacement | Because |
+|---------|-------------|---------|
+| Cards nested inside cards | Typography, spacing, dividers for hierarchy | Nested cards create visual noise without purpose |
+| Identical card grids (icon + heading + text ×3-6) | Varied layout with purposeful asymmetry | Repeated identical cards is the #1 AI tell |
+| Hero metric template (big number + small label + gradient accent) | Contextual data display — number embedded in prose or card | Generic hero metrics are the startup-template cliché |
+| Center-aligning everything | Left-align content blocks; reserve center for short hero headlines | Center-aligned body text is hard to scan |
+| Same spacing everywhere (no visual rhythm) | Use proximity to group related items; vary spacing to create sections | Uniform spacing flattens hierarchy |
 
 ### Visual
 
-- Glassmorphism used decoratively (blur cards, glow borders)
-- Thick colored border on one side of rounded rectangles
-- Sparklines as decoration (not connected to real data)
-- Generic drop shadows on everything
-- Rounded rectangles as the only shape language
+| Pattern | Replacement | Because |
+|---------|-------------|---------|
+| Glassmorphism used decoratively | Flat surfaces or layered shadows | Glassmorphism needs a functional reason for depth |
+| Thick colored border on one side of rounded rectangles | Subtle border or shadow on entire element | One-sided colored borders are a dated pattern |
+| Sparklines as decoration (not connected to real data) | Real sparklines from actual data, or omit entirely | Decorative sparklines are fake data theater |
+| Generic drop shadows on everything | Intentional shadow hierarchy — only where depth communicates meaning | Shadow-everywhere flattens the depth language |
+| Rounded rectangles as the only shape language | Mix shapes: sharp corners, soft corners, circles, organic shapes | Single-shape designs feel templated |
 
 ### Motion
 
-- Bounce or elastic easing (real objects decelerate smoothly)
-- Animating `height`, `width`, `padding`, `margin` (causes layout recalculation)
-- Default `ease` (compromise that's rarely optimal — use exponential easing)
-- Missing `prefers-reduced-motion` handling
+| Pattern | Replacement | Because |
+|---------|-------------|---------|
+| Bounce or elastic easing on UI | Exponential easing `cubic-bezier(0.16, 1, 0.3, 1)` | Real objects decelerate smoothly, not bounce |
+| Animating `height`, `width`, `padding`, `margin` | Animate only `transform` and `opacity` | Layout animations cause expensive repaints |
+| Default `ease` | Exponential easing curves tuned to animation purpose | Default `ease` is a compromise rarely optimal |
+| Missing `prefers-reduced-motion` handling | Always respect reduced motion preferences | ~35% of adults over 40 prefer reduced motion |
 
-> **The AI Slop Test**: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem.
+> **The Slop Test:** If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem.
 
 ## Best Practices
 
@@ -235,28 +255,21 @@ Create atmosphere: gradient meshes, noise textures, geometric patterns, layered
 
 | Rationalization | Reality |
 |---|---|
-| "The AI aesthetic is fine for now" | AI default styles (purple gradients, oversized cards) signal low quality. Use the design system. |
+| "The default look is fine for now" | Default styles signal low quality. Use the design system from the start. |
 | "I'll make it responsive later" | Retrofitting responsive design is 3x harder than building it mobile-first. |
 | "Accessibility is a nice-to-have" | It's a legal requirement in many jurisdictions and an engineering quality standard. |
 | "This is just a prototype" | Prototypes become production code. Build the foundation right from the start. |
-
-## Red Flags
-
-- Components exceeding 200 lines (split them)
-- Inline styles or arbitrary pixel values
-- Missing error states, loading states, or empty states
-- No keyboard navigation testing
-- Color as the sole indicator of state (red/green without text or icons)
-- Generic "AI look" (purple gradients, oversized cards, stock layouts)
+| "Typography doesn't matter for functionality" | Typography is 95% of web design. Bad type ruins even good layouts. |
+| "Users won't notice the details" | Users may not articulate it, but they feel quality. Details accumulate into perception. |
 
 ## Verification
 
-After building UI:
-
-- [ ] Component renders without console errors
-- [ ] All interactive elements are keyboard accessible (Tab through the page)
-- [ ] Screen reader can convey the page's content and structure
+- [ ] Design tokens defined: primitives + semantic layer, with dark mode variants
+- [ ] Typography: distinctive font pairing, fluid sizing with `clamp()`, `max-width: 65ch` on body text
+- [ ] Color: OKLCH tokens, tinted neutrals (chroma 0.01-0.02), sufficient contrast (4.5:1 min)
+- [ ] Motion: exponential easing only, `prefers-reduced-motion` handled, only `transform` + `opacity` animated
+- [ ] Spacing: consistent 4pt scale, `gap` over margins, self-adjusting grids
 - [ ] Responsive: works at 320px, 768px, 1024px, 1440px
-- [ ] Loading, error, and empty states all handled
-- [ ] Follows the project's design system (spacing, colors, typography)
-- [ ] No accessibility warnings in dev tools or axe-core
+- [ ] Interaction: all 8 states designed, `:focus-visible` used, skeletons over spinners
+- [ ] UX Writing: verb + object buttons, error = what + why + fix, empty states are onboarding
+- [ ] No banned fonts, no gray-on-color text, no pure black/white

package/dist/template/.pi/skills/frontend-ui-engineering/SKILL.md

@@ -30,14 +30,15 @@ This skill composes with others for a complete frontend quality pipeline:
 
 | Skill | Relationship | When to combine |
 |-------|-------------|-----------------|
-| `frontend-design` | Sibling | `frontend-design` covers general UI patterns with React. `frontend-ui-engineering` adds production-quality standards (accessibility, AI-aesthetic avoidance). Load both for serious UI work. |
-| `design-taste-frontend` | Upstream | Apply design-taste rules FIRST to establish the aesthetic baseline. Then use `frontend-ui-engineering` for implementation quality. |
+| `design-taste-frontend` | Upstream | Apply aesthetic baseline FIRST. Then use `frontend-ui-engineering` for implementation quality. |
+| `frontend-design` | Upstream | `frontend-design` covers design system + tokens. `frontend-ui-engineering` adds component implementation patterns. |
 | `react-best-practices` | Complement | Load when building React/Next.js components — covers performance-specific patterns (memo, useMemo, server components). |
-| `accessibility-audit` | Gate | After building UI, run `accessibility-audit` to verify WCAG 2.1 AA compliance. |
+| `baseline-ui` | Upstream | Quick deslop pass before implementation — fixes spacing, typography, layout basics automatically. |
+| `fixing-accessibility` | Gate | After building UI, run `fixing-accessibility` for actionable WCAG 2.1 AA fixes. |
 | `performance-optimization` | Gate | After UI is working, profile with `performance-optimization` for Core Web Vitals. |
-| `mockup-to-code` | Upstream | If converting from Figma/mockup, run `mockup-to-code` first, then refine with `frontend-ui-engineering`. |
+| `ui-craft-principles` | Complement | Apply 16 craft principles (concentric radius, optical alignment, etc.) for polish. |
 
-**Pipeline:** `design-taste-frontend` → `frontend-ui-engineering` → `accessibility-audit` + `performance-optimization`
+**Pipeline:** `design-taste-frontend` → `frontend-design` → `frontend-ui-engineering` → `fixing-accessibility` + `performance-optimization`
 
 ## Component Architecture
 
@@ -102,11 +103,11 @@ Global store (Zustand, Redux)    → Complex client state shared app-wide
 
 ## Design System Adherence
 
-### Avoid the AI Aesthetic
+### Avoid Common Visual Anti-Patterns
 
-AI-generated UI has recognizable patterns. Avoid all of them:
+These patterns degrade implementation quality. For design-level aesthetic rules, see `design-taste-frontend`.
 
-| AI Default | Production Quality |
+| Degraded Pattern | Production Quality |
 |---|---|
 | Purple/indigo everything | Use the project's actual color palette |
 | Excessive gradients | Flat or subtle gradients matching the design system |
@@ -185,29 +186,20 @@ Test at: 320px, 768px, 1024px, 1440px.
 - `aria-busy="true"` on loading regions
 - Avoid layout shifts during loading (reserve space)
 
-## Common Rationalizations
+## Don't
 
-| Rationalization | Reality |
-|---|---|
-| "Accessibility is a nice-to-have" | It's a legal requirement in many jurisdictions and an engineering quality standard. |
-| "We'll make it responsive later" | Retrofitting responsive design is 3x harder than building it from the start. |
-| "The design isn't final, so I'll skip styling" | Use the design system defaults. Unstyled UI creates a broken first impression. |
-| "This is just a prototype" | Prototypes become production code. Build the foundation right. |
-| "The AI aesthetic is fine for now" | It signals low quality. Use the project's actual design system from the start. |
-
-## Red Flags
-
-- Components with more than 200 lines (split them)
-- Inline styles or arbitrary pixel values
-- Missing error states, loading states, or empty states
-- No keyboard navigation testing
-- Color as the sole indicator of state (red/green without text or icons)
-- Generic "AI look" (purple gradients, oversized cards, stock layouts)
+| Pattern | Replacement | Because |
+|---------|-------------|---------|
+| Components over 200 lines | Split into smaller focused sub-components | Large components violate single responsibility |
+| Inline styles or arbitrary pixel values | Use design tokens and consistent spacing scale | Inline styles are not maintainable |
+| Missing error, loading, or empty states | Handle all 4 data states (loading, empty, error, normal) | Users see blank screens without complete state handling |
+| Color as sole indicator of state | Add text labels or icons alongside color | Color-only cues are inaccessible to colorblind users |
+| `<div onClick>` instead of `<button>` | Use `<button type="button">` with proper styling | div onClick has no keyboard or screen reader semantics |
+| Prop drilling deeper than 3 levels | Use context, composition, or state management | Deep prop drilling couples components unnecessarily |
+| Skipping heading levels (h1 → h3) | Maintain sequential hierarchy (h1 → h2 → h3) | Skipped levels break screen reader page navigation |
 
 ## Verification
 
-After building UI:
-
 - [ ] Component renders without console errors
 - [ ] All interactive elements are keyboard accessible (Tab through the page)
 - [ ] Screen reader can convey the page's content and structure
@@ -215,3 +207,5 @@ After building UI:
 - [ ] Loading, error, and empty states all handled
 - [ ] Follows the project's design system (spacing, colors, typography)
 - [ ] No accessibility warnings in dev tools or axe-core
+- [ ] No `<div onClick>` as button replacement — all interactive elements use semantic HTML
+- [ ] Components < 200 lines; larger components split into sub-components

package/dist/template/.pi/skills/memory-system/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: memory-system
+description: "Documents pi-hermes-memory capabilities: background auto-review, correction detection, tools (memory, memory_search, session_search), and commands. Load when the agent needs to understand or leverage the memory system — searching past failures, saving learnings, or learning the auto-flywheel."
+---
+
+# Memory System (pi-hermes-memory)
+
+## Overview
+
+pi-hermes-memory is the **persistent memory extension** that runs automatically in every pi session. It provides a self-learning flywheel without the agent needing to trigger it manually. This skill documents its capabilities so the agent can leverage them strategically.
+
+## Auto-Flywheel (already running — no trigger needed)
+
+### 1. Background Review — automated "compound" every ~10 turns
+
+Every N turns (default: 10) OR after accumulating enough tool calls, pi-hermes-memory spawns a background child process that:
+
+- Snaps the full conversation as `[USER]`/`[ASSISTANT]` prefixed text
+- Reviews for: user preferences, corrections, failures, insights, conventions, tool-quirks  
+- Saves notable findings to `MEMORY.md`, `USER.md`, or `failures.md`
+- Only acts if there's something genuinely worth saving ("Nothing to save." otherwise)
+- Non-blocking — the session continues while the review runs
+
+**→ You do NOT need to call this yourself.** It fires automatically on `turn_end`.
+
+### 2. Correction Detection — real-time error learning
+
+On every user message, pi-hermes-memory checks for correction patterns:
+
+| Strength | Patterns | Example |
+|----------|----------|---------|
+| **Strong** (always trigger) | `"don't do that"`, `"not like that"`, `"I said..."`, `"I told you..."`, `"that's not what I..."` | "Don't do that — use pnpm instead" |
+| **Weak** (needs directive) | `"no, ..."`, `"wrong, ..."`, `"actually..."` + verb like "use", "change", "fix" | "No, use the other approach" |
+| **Negative** (suppress) | `"no worries"`, `"no problem"`, `"actually looks great"` | Ignored |
+
+When detected → immediately saves to `target='failure', category='correction'` with the reason "User corrected the agent".
+
+**→ Corrections are captured automatically.** You don't need to save them — it's already done.
+
+### 3. Session Flush
+
+Before session compaction/shutdown, a flush prompt extracts anything worth remembering from the closing session.
+
+### 4. Auto-Consolidation
+
+When `MEMORY.md` reaches the 5,000 character limit, entries are auto-merged, deduped, and staled entries (>30 days, unreferenced) are removed.
+
+## Tools Available (agent can call)
+
+| Tool | Purpose | Key params |
+|------|---------|------------|
+| `memory` | Save/update/delete memories | `action` (add/replace/remove), `target` (memory/user/failure/project), `content`, `category` |
+| `memory_search` | Search durable memories across sessions | `query`, `target`, `category`, `project` |
+| `session_search` | Search past conversation messages | `query`, `project`, `role` |
+| `skill_manage` | Create/update procedural skills | `action`, `name`, `scope`, `when_to_use`, `procedure_steps` |
+
+## Memory Categories (for `target='failure'`)
+
+| Category | When to use | Example |
+|----------|------------|---------|
+| `failure` | Something tried that didn't work | "Used localStorage for tokens — XSS vulnerability" |
+| `correction` | User corrected the agent | "Use pnpm, not npm" |
+| `insight` | Durable learning from experience | "Complexity over 15 in a single function causes CI timeout" |
+| `preference` | User preference or work style | "Prefers terse responses, no cheerleading" |
+| `convention` | Project or team convention | "Monorepo with turborepo, uses pnpm workspaces" |
+| `tool-quirk` | Non-obvious tool behavior | "tsc --noEmit fails silently on .d.ts syntax errors" |
+
+## Commands Available (user can run)
+
+| Command | Purpose |
+|---------|---------|
+| `/memory-insights` | Show everything stored in memory |
+| `/memory-skills` | List all saved procedural skills |
+| `/memory-consolidate` | Manually trigger memory cleanup/merge |
+| `/memory-interview` | Onboarding interview to pre-fill user profile |
+| `/memory-switch-project` | List all project memories |
+| `/memory-index-sessions` | Import past sessions for search |
+| `/memory-sync-markdown` | Backfill Markdown entries into SQLite search |
+| `/memory-preview-context` | Show memory policy or legacy prompt blocks |
+| `/learn-memory-tool` | Interactive guide to the memory system |
+
+## When to Use memory_search
+
+Use `memory_search` when you need **durable, cross-session knowledge** — things that happened in previous sessions, not just the current one:
+
+- **Searching past failures**: `memory_search({ query: "similar error", target: "failure", category: "failure" })`
+- **Finding project conventions**: `memory_search({ query: "typescript pattern", project: "<project>" })`
+- **Recalling user preferences**: `memory_search({ query: "prefers", target: "user" })`
+- **Checking tool quirks**: `memory_search({ query: "pnpm install", category: "tool-quirk" })`
+
+Use `vcc_recall` when you need **current-session lineage** — what was just discussed or tried in this active workflow.
+
+Use both together in Guard phases for maximum recall coverage.
+
+## When to Explicitly Save (manual `memory` tool)
+
+Even though auto-review runs every 10 turns, manually save when:
+
+- **On 2x verification failure** — save the failed approach immediately so future sessions won't repeat it. Use `target='failure', category='failure'` with: what was tried, why it failed, the error, and what worked instead (if known).
+- **On a critical discovery** — if you learn something that would save 15+ minutes for future-self, don't wait for the auto-review cycle.
+- **On user's explicit request** — "remember this" → save immediately.
+- **On learning a tool-quirk** — non-obvious behavior that would trip up a future agent.
+
+## Pitfalls
+
+- **Waiting for auto-review for critical failures** — if verification just failed 2x, save that failure NOW. The auto-review might not fire for 10 more turns.
+- **Using vcc_recall for cross-session knowledge** — vcc_recall is lineage-scoped (active session); it may not find failures from a closed session. Use `memory_search` instead.
+- **Over-saving** — don't save task progress, session outcomes, or temporary state. The auto-review already captures durable learnings. Manual saves are for URGENT or USER-REQUESTED facts only.
+- **Assuming memory_search has everything** — if the SQLite sync is broken (the memory-sync-markdown command can fix this), older Markdown entries may not appear in search. The `/memory-sync-markdown` command backfills them.
+
+## Verification
+
+Before relying on memory_search:
+
+- [ ] Check if the SQLite sync is healthy (`/memory-insights` shows recent entries)
+- [ ] If search returns nothing but you KNOW the info was saved, run `/memory-sync-markdown` 
+- [ ] Use both `memory_search` AND `vcc_recall` in Guard phases for dual coverage
+- [ ] When saving a failure, include: what was tried, why it failed, the error message, reproduction steps