aped-method 1.7.0 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aped-method",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "type": "module",
   "description": "Scaffold the APED pipeline (Analyze, PRD, Epics, Dev, Review) into any Claude Code project",
   "bin": {

package/src/templates/references.js

@@ -552,7 +552,186 @@ mobile_app,"iOS,Android,app,mobile,iPhone,iPad","Native or cross-platform?;Offli
 saas_b2b,"SaaS,B2B,platform,dashboard,teams,enterprise","Multi-tenant?;Permission model?;Subscription tiers?;Integrations?;Compliance?","tenant_model;rbac_matrix;subscription_tiers;integration_list;compliance_reqs","cli_interface;mobile_first","compliance requirements;integration guides","Workflow automation;AI agents"
 cli_tool,"CLI,command,terminal,bash,script","Interactive or scriptable?;Output formats?;Config method?;Shell completion?","command_structure;output_formats;config_schema;scripting_support","visual_design;ux_principles;touch_interactions","CLI design patterns;shell integration","Natural language CLI;AI commands"`;
 
-const UX_PATTERNS = `# UX Screen Patterns Catalog
+const UX_PATTERNS = `# UX Design Rules — Priority-Ranked
+
+Rules ranked by impact. Apply in order — never skip a higher-priority rule for a lower one.
+
+---
+
+## P1: Accessibility (CRITICAL)
+
+- Contrast ≥ 4.5:1 normal text, ≥ 3:1 large text (WCAG AA)
+- Visible focus rings (2-4px) on ALL interactive elements
+- Alt text on meaningful images; decorative images use alt=""
+- aria-label on icon-only buttons
+- Tab order matches visual order; full keyboard support
+- Form inputs have visible labels (not placeholder-only)
+- Skip-to-main-content link for keyboard users
+- Heading hierarchy: sequential h1→h6, no level skipping
+- Information never relies on color alone (add icon/text)
+- Support dynamic text scaling (no truncation on resize)
+- Respect prefers-reduced-motion — disable animations when set
+- Screen reader: meaningful labels, logical reading order
+- Escape routes: cancel/back in modals and multi-step flows
+- Preserve system keyboard shortcuts
+
+## P2: Touch & Interaction (CRITICAL)
+
+- Touch targets ≥ 44x44pt (iOS) / 48x48dp (Android)
+- Minimum 8px gap between touch targets
+- Primary interactions via tap, never hover-only
+- Loading buttons: disable during async + show spinner
+- Error feedback: clear message near the problem field
+- cursor:pointer on clickable web elements
+- No horizontal swipe conflicts on main content
+- touch-action:manipulation to kill 300ms tap delay
+- Use platform-standard gestures consistently
+- Don't block system gestures (back swipe, control center)
+- Visual press feedback (ripple/opacity) within 80-150ms
+- Haptic feedback for confirmations only — no overuse
+- Always provide visible controls alongside gestures
+- Keep targets away from notch, Dynamic Island, edges
+- No precision-required taps on tiny icons
+
+## P3: Performance (HIGH)
+
+- Images: WebP/AVIF, responsive srcset, lazy load below fold
+- Declare width/height or aspect-ratio to prevent CLS
+- font-display:swap, preload only critical fonts
+- Critical CSS above the fold; lazy load the rest
+- Code split by route/feature
+- Third-party scripts: async/defer, audit necessity
+- Batch DOM reads then writes to reduce reflows
+- Reserve space for async content (no content jumping)
+- Virtualize lists with 50+ items
+- Keep per-frame work under 16ms for 60fps
+- Skeleton/shimmer for operations >300ms
+- Input latency under 100ms for taps/scrolls
+- Debounce/throttle high-frequency events (scroll, resize, input)
+- Provide offline state messaging
+- Degraded mode for slow networks
+
+## P4: Style & Consistency (HIGH)
+
+- Match visual style to product type and audience
+- Same style across all screens — no mixed aesthetics
+- SVG icons only (Lucide, Heroicons) — never emoji as structural icons
+- Color palette derived from product domain/industry
+- Effects (shadows, blur, radius) aligned with chosen style
+- Respect platform idioms (iOS HIG vs Material Design)
+- Hover/pressed/disabled states visually distinct
+- Consistent elevation/shadow scale across components
+- Design light and dark variants together from day 1
+- One icon set, one visual language throughout
+- Prefer native controls over custom when possible
+- One primary CTA per screen — secondary actions subordinate
+
+## P5: Layout & Responsive (HIGH)
+
+- viewport meta: width=device-width, initial-scale=1
+- Mobile-first: design small, scale up
+- Systematic breakpoints: 375 / 768 / 1024 / 1440
+- Minimum 16px body text on mobile
+- Line length: 35-60 chars mobile, 60-75 chars desktop
+- No horizontal scroll on any breakpoint
+- 4pt/8dp spacing scale consistently applied
+- Consistent max-width container on desktop (1200-1440px)
+- Layered z-index scale (avoid arbitrary values)
+- Safe padding for fixed/sticky elements
+- Avoid nested scroll regions
+- Prefer min-h-dvh over 100vh (mobile address bar)
+- Content priority: core content first on mobile
+- Visual hierarchy via size, spacing, and contrast
+
+## P6: Typography & Color (MEDIUM)
+
+- Body line-height: 1.5-1.75
+- Font pairing: match heading/body personalities
+- Consistent type scale: 12/14/16/18/24/32
+- Weight hierarchy: bold headings (600-700), regular body (400)
+- Semantic color tokens: primary, secondary, error, warning, success, surface
+- Dark mode: desaturated/lighter variants, NOT inverted colors
+- Foreground/background pairs meet 4.5:1 (AA) or 7:1 (AAA)
+- Prefer text wrapping over truncation; ellipsis only with tooltip
+- Tabular figures for data columns, prices, timers
+- Intentional whitespace to group and separate
+
+## P7: Animation (MEDIUM)
+
+- Duration: 150-300ms micro-interactions, ≤400ms complex, never >500ms
+- Animate transform and opacity ONLY (GPU composited)
+- ease-out entering, ease-in exiting
+- Every animation must express cause-effect (meaningful motion)
+- Max 1-2 animated elements per view transition
+- Exit animations ~60-70% of enter duration
+- Stagger list items by 30-50ms
+- Animations must be interruptible by user
+- Never block user input during animation
+- Subtle scale feedback on press (0.95-1.05)
+- Real-time response to drag/swipe/pinch gestures
+- Animations must not cause CLS (no layout shift)
+- Modal: animate from trigger source
+- Navigation: forward = left/up, backward = right/down
+
+## P8: Forms & Feedback (MEDIUM)
+
+- Visible label per input — never placeholder-only
+- Error shown below the field, near the problem
+- Submit: show loading → then success/error state
+- Mark required fields (asterisk + sr-only text)
+- Empty states: helpful message + CTA action
+- Toast: auto-dismiss 3-5s, use aria-live="polite"
+- Confirm before destructive actions
+- Persistent helper text below complex inputs
+- Disabled: opacity 0.38-0.5 + cursor change + no tap
+- Progressive disclosure: reveal options step by step
+- Validate on blur, show error after user finishes typing
+- Semantic input types (email, tel, number, url)
+- Password show/hide toggle
+- Support autocomplete/textContentType for autofill
+- Allow undo for destructive actions
+- Auto-focus first invalid field after submit
+- Error summary at top with anchor links for long forms
+- Mobile input height ≥ 44px
+- Unsaved changes: confirm before dismissing
+
+## P9: Navigation (HIGH)
+
+- Bottom nav ≤ 5 items, each with icon + label
+- Drawer for secondary nav only, not primary
+- Predictable back behavior; preserve scroll/state
+- All key screens reachable via deep link/URL
+- Current location visually highlighted (active state)
+- Primary vs secondary navigation clearly separated
+- Modal: clear close affordance, swipe-down on mobile
+- Search: accessible from top bar or dedicated tab
+- Breadcrumb for 3+ level deep hierarchies
+- Restore scroll, filters, input on back navigation
+- Adaptive: sidebar ≥1024px, bottom/top nav for small screens
+- Never silently reset navigation stack
+- Same navigation placement across all pages
+- Don't mix Tab + Sidebar + Bottom Nav simultaneously
+- Focus moves to main content on route change
+
+## P10: Charts & Data (LOW)
+
+- Match chart type to data: trend→line, comparison→bar, proportion→pie
+- Accessible color palettes — supplement with patterns/textures
+- Always show legend near chart
+- Tooltip on hover (web) or tap (mobile)
+- Label axes with units; never truncate/rotate axis labels
+- Responsive: reflow charts on small screens
+- Empty data: show "No data yet" with action
+- Skeleton placeholder while loading
+- Respect prefers-reduced-motion for chart animations
+- Virtualize/aggregate datasets >1000 points
+- Interactive elements ≥ 44pt tap area
+- No pie chart for >5 categories
+- Direct-label values for small datasets
+- Offer CSV/image export for data tables
+- Screen reader: aria-label describing key insight
+
+---
 
 ## Screen Types
 
@@ -580,55 +759,43 @@ const UX_PATTERNS = `# UX Screen Patterns Catalog
 - **Error Page**: error code, message, back/home links
 - **Loading**: skeleton screens, progress bar, spinner
 
-## Layout Patterns
-
-### Navigation
-- **Top Nav**: logo left, nav center/right, avatar far right
-- **Sidebar**: collapsible, icons + labels, active indicator, mobile hamburger
-- **Tab Bar**: bottom tabs (mobile), top tabs (desktop), badge counts
-- **Breadcrumb**: path hierarchy, current page non-linked
-
-### Content Layout
-- **Sidebar + Content**: 240-280px sidebar, fluid content, responsive collapse
-- **Full Width**: max-width container (1200-1440px), centered
-- **Split View**: list left, detail right (email pattern), resizable
-- **Grid**: 12-column, responsive breakpoints (sm/md/lg/xl)
-
-## Interaction Patterns
-
-### Forms
-- **Inline Validation**: validate on blur, show error below field, green checkmark on valid
-- **Progressive Disclosure**: show fields based on previous answers
-- **Autosave**: debounced save, "Saved" indicator, conflict resolution
-
-### Data
-- **Optimistic Updates**: update UI immediately, revert on error
-- **Pagination**: page numbers for known total, infinite scroll for feeds
-- **Search**: debounced input (300ms), loading indicator, clear button
-
-### Feedback
-- **Toast/Snackbar**: bottom-right, auto-dismiss (5s), action button, stacking
-- **Modal/Dialog**: overlay, focus trap, escape to close, confirm/cancel
-- **Inline Alerts**: contextual, dismissible, icon + message + action
-
-## Responsive Breakpoints
-
-| Name | Width | Typical |
-|------|-------|---------|
-| sm | < 640px | Mobile portrait |
-| md | 640-1024px | Tablet / mobile landscape |
-| lg | 1024-1440px | Desktop |
-| xl | > 1440px | Large desktop |
-
-## Accessibility Checklist
-
-- [ ] All interactive elements keyboard-navigable (Tab, Enter, Escape)
-- [ ] Focus indicator visible on all focusable elements
-- [ ] ARIA labels on icon-only buttons
-- [ ] Color contrast ratio ≥ 4.5:1 (text), ≥ 3:1 (large text)
-- [ ] Form fields have associated labels
-- [ ] Error messages linked to fields via aria-describedby
-- [ ] Skip navigation link for screen readers
-- [ ] Alt text on meaningful images
-- [ ] Touch targets ≥ 44x44px on mobile
+---
+
+## Pre-Delivery Checklist
+
+### Visual Quality
+- [ ] SVG icons only — no emoji as structural elements
+- [ ] Consistent icon family and stroke width
+- [ ] Press states don't shift layout or cause jitter
+- [ ] Semantic theme tokens used consistently
+- [ ] Official brand assets with correct proportions
+
+### Interaction
+- [ ] All tappable elements provide press feedback
+- [ ] Touch targets ≥ 44x44pt / 48x48dp
+- [ ] Micro-interactions 150-300ms with native easing
+- [ ] Disabled states visually clear and non-interactive
+- [ ] Screen reader focus order matches visual layout
+- [ ] No gesture conflicts between app and system
+
+### Light/Dark Mode
+- [ ] Primary text ≥ 4.5:1 contrast in both modes
+- [ ] Secondary text ≥ 3:1 contrast in both modes
+- [ ] Borders/dividers distinguishable in both modes
+- [ ] Modal scrim preserves foreground legibility
+- [ ] Both themes tested independently
+
+### Layout
+- [ ] Safe areas respected for fixed elements
+- [ ] Scroll content not hidden behind fixed bars
+- [ ] Tested: small phone, large phone, tablet (portrait + landscape)
+- [ ] 4/8dp spacing maintained throughout
+- [ ] Long-form text readable on larger screens
+
+### Accessibility
+- [ ] Meaningful images/icons have labels
+- [ ] Form fields have labels, hints, clear errors
+- [ ] Color not sole indicator of state
+- [ ] Reduced motion and dynamic text size supported
+- [ ] ARIA roles/states announced correctly
 `;

package/src/templates/skills.js

@@ -8,10 +8,21 @@ export function skills(c) {
       content: `---
 name: aped-a
 description: 'Analyzes a new project idea through parallel market, domain, and technical research. Use when user says "research idea", "aped analyze", or invokes /aped-a. Not for existing codebases — use aped-ctx for brownfield projects.'
+license: MIT
+metadata:
+  author: yabafre
+  version: ${c.cliVersion || '1.7.1'}
 ---
 
 # APED Analyze — Parallel Research to Product Brief
 
+## Critical Rules
+
+- NEVER skip Discovery questions — research quality depends on clear inputs
+- ALL 3 agents must complete before synthesis — do not proceed with partial results
+- Take your time with synthesis — quality is more important than speed
+- Do not skip validation steps
+
 ## Setup
 
 1. Read \`${a}/config.yaml\` — extract \`user_name\`, \`communication_language\`, \`ticket_system\`, \`git_provider\`
@@ -113,6 +124,20 @@ pipeline:
 ## Chain
 
 Invoke Skill tool with \`skill: "aped-p"\` to proceed to PRD phase.
+
+## Example
+
+User says: "I want to build a SaaS for restaurant inventory management"
+1. Discovery: ask what, for whom, why now
+2. Launch 3 agents: market (restaurant tech), domain (food service regulations), technical (inventory systems)
+3. Synthesize into product brief with 5 sections
+4. Validate → write to \`${o}/product-brief.md\`
+
+## Common Issues
+
+- **Agent returns empty results**: WebSearch may fail — retry with different keywords, broaden search terms
+- **Brief validation fails**: Check which section is missing, fill it from agent results, re-validate
+- **User gives vague answers**: Ask follow-up questions before launching research — garbage in = garbage out
 `,
     },
     // ── aped-p ──────────────────────────────────────────────
@@ -121,10 +146,21 @@ Invoke Skill tool with \`skill: "aped-p"\` to proceed to PRD phase.
       content: `---
 name: aped-p
 description: 'Generates PRD autonomously from product brief. Use when user says "create PRD", "generate PRD", "aped prd", or invokes /aped-p.'
+license: MIT
+metadata:
+  author: yabafre
+  version: ${c.cliVersion || '1.7.1'}
 ---
 
 # APED PRD — Autonomous PRD Generation
 
+## Critical Rules
+
+- EVERY FR must follow format: \`FR#: [Actor] can [capability]\` — no exceptions
+- Take your time to generate quality FRs — 10-80 range, each independently testable
+- Do not skip domain detection — it determines mandatory sections
+- Quality is more important than speed — validate before writing
+
 ## Setup
 
 1. Read \`${a}/config.yaml\` — extract \`user_name\`, \`communication_language\`, \`document_output_language\`
@@ -210,6 +246,20 @@ pipeline:
 Ask the user: "Do you want to design the UX before creating epics?"
 - If yes: invoke Skill tool with \`skill: "aped-ux"\`
 - If no: invoke Skill tool with \`skill: "aped-e"\` to skip directly to Epics
+
+## Example
+
+From a restaurant inventory brief → PRD generates:
+- FR1: Manager can add inventory items with name, quantity, and unit
+- FR2: Manager can set low-stock thresholds per item
+- FR3: System can send alerts when stock falls below threshold
+- NFR: The system shall respond to inventory queries within 200ms at p95
+
+## Common Issues
+
+- **FR count too low (<10)**: Brief may lack detail — re-read brief, extract implicit capabilities
+- **Anti-pattern words detected**: Replace "easy" with step count, "fast" with time threshold
+- **Validation script fails**: Run \`bash ${a}/aped-p/scripts/validate-prd.sh ${o}/prd.md\` — fix reported issues one by one
 `,
     },
     // ── aped-e ──────────────────────────────────────────────
@@ -218,10 +268,21 @@ Ask the user: "Do you want to design the UX before creating epics?"
       content: `---
 name: aped-e
 description: 'Creates epics and stories from PRD with full FR coverage. Use when user says "create epics", "break into stories", "aped epics", or invokes /aped-e.'
+license: MIT
+metadata:
+  author: yabafre
+  version: ${c.cliVersion || '1.7.1'}
 ---
 
 # APED Epics & Stories — Requirements Decomposition
 
+## Critical Rules
+
+- EVERY FR must map to exactly one epic — no orphans, no phantoms
+- Epics describe USER VALUE, not technical layers — "User Authentication" not "Database Setup"
+- Each story must be completable in 1 dev session — split if >8 tasks
+- Quality is more important than speed — do not skip coverage validation
+
 ## Setup
 
 1. Read \`${a}/config.yaml\` — extract config including \`ticket_system\`
@@ -302,6 +363,19 @@ mkdir -p ${o}/stories
 2. Create story files in \`${o}/stories/\` using \`${a}/templates/story.md\`
 3. Update \`${o}/state.yaml\` with sprint section and pipeline phase
 
+## Example
+
+PRD with 25 FRs → 3 epics:
+- Epic 1: "Users can manage inventory" (FR1-FR8, 4 stories)
+- Epic 2: "Managers can monitor stock levels" (FR9-FR16, 3 stories)
+- Epic 3: "System sends automated alerts" (FR17-FR25, 3 stories)
+
+## Common Issues
+
+- **Coverage validation fails**: Run \`validate-coverage.sh\` — lists orphan FRs
+- **Epic too large**: Split by sub-domain — e.g., "User Auth" → "Registration" + "Sessions"
+- **Forward dependencies**: If story B needs A, merge them or restructure
+
 ## Chain
 
 Invoke Skill tool with \`skill: "aped-d"\` to proceed to Dev Sprint.
@@ -314,10 +388,21 @@ Invoke Skill tool with \`skill: "aped-d"\` to proceed to Dev Sprint.
 name: aped-d
 description: 'Implements next story with TDD red-green-refactor cycle. Use when user says "start dev", "implement story", "aped dev", or invokes /aped-d.'
 disable-model-invocation: true
+license: MIT
+metadata:
+  author: yabafre
+  version: ${c.cliVersion || '1.7.1'}
 ---
 
 # APED Dev Sprint — TDD Story Implementation
 
+## Critical Rules
+
+- NEVER mark a task \`[x]\` without passing all 5 gate conditions
+- ALWAYS write the failing test FIRST — no implementation without a RED test
+- Take your time — quality is more important than speed
+- Do not skip validation steps or test runs
+
 ## Setup
 
 1. Read \`${a}/config.yaml\` — extract config including \`ticket_system\`, \`git_provider\`
@@ -395,6 +480,21 @@ Read \`git_provider\` and \`ticket_system\` from config:
 1. Update story: mark tasks \`[x]\`, fill Dev Agent Record
 2. Update \`${o}/state.yaml\`: story — \`review\`
 3. Invoke Skill tool with \`skill: "aped-r"\` to proceed to Review phase
+
+## Example
+
+Story "1-2-user-registration":
+1. RED: write test \`expect(register({email, password})).resolves.toHaveProperty('id')\` → fails
+2. GREEN: implement \`register()\` → test passes
+3. REFACTOR: extract validation → tests still pass
+4. GATE: tests exist ✓, pass ✓, matches spec ✓, ACs met ✓, no regressions ✓ → mark \`[x]\`
+
+## Common Issues
+
+- **Test framework not detected**: Ensure package.json has vitest/jest dependency, or use \`run-tests.sh\` manually
+- **3 consecutive failures**: HALT — ask user. Do not brute-force; the approach may be wrong
+- **Missing dependency**: HALT — ask user before installing. Do not add deps silently
+- **Tests pass before writing code**: The test is wrong — it doesn't test new behavior. Rewrite it
 `,
     },
     // ── aped-r ──────────────────────────────────────────────
@@ -404,10 +504,21 @@ Read \`git_provider\` and \`ticket_system\` from config:
 name: aped-r
 description: 'Reviews completed stories adversarially with minimum 3 findings. Use when user says "review code", "run review", "aped review", or invokes /aped-r.'
 disable-model-invocation: true
+license: MIT
+metadata:
+  author: yabafre
+  version: ${c.cliVersion || '1.7.1'}
 ---
 
 # APED Review — Adversarial Code Review
 
+## Critical Rules
+
+- MINIMUM 3 findings — if you found fewer, you didn't look hard enough. Re-examine.
+- NEVER skip the git audit — it catches undocumented file changes
+- Take your time — thoroughness is more important than speed
+- Do not rubber-stamp. Your job is to find problems, not to validate.
+
 ## Setup
 
 1. Read \`${a}/config.yaml\` — extract config including \`git_provider\`
@@ -464,6 +575,20 @@ Severity: CRITICAL > HIGH > MEDIUM > LOW. Format: \`[Severity] Description [file
 ## State Update
 
 Update \`${o}/state.yaml\`. If more stories remain: invoke Skill tool with \`skill: "aped-d"\`. If all stories done: report pipeline completion.
+
+## Example
+
+Review of story "1-2-user-registration":
+- [HIGH] No input validation on email field [src/auth/register.ts:42]
+- [MEDIUM] Password stored without hashing [src/auth/register.ts:58]
+- [LOW] Missing error message i18n [src/auth/register.ts:71]
+Result: 3 findings → story back to \`in-progress\` with [AI-Review] items.
+
+## Common Issues
+
+- **Git audit fails (no git repo)**: Script handles this — skips audit with WARNING, proceeds to code review
+- **Fewer than 3 findings**: Re-examine edge cases, error handling, test gaps, security surface
+- **Story file not found**: Check \`sprint.stories\` in state.yaml — story key may have changed
 `,
     },
     // ── aped-ux ─────────────────────────────────────────────
@@ -472,10 +597,22 @@ Update \`${o}/state.yaml\`. If more stories remain: invoke Skill tool with \`ski
       content: `---
 name: aped-ux
 description: 'Designs UX via the ANF framework (Assemble design system, Normalize with React preview, Fill all screens). Use when user says "design UX", "UX spec", "aped ux", or invokes /aped-ux. Runs between PRD and Epics phases.'
+license: MIT
+compatibility: 'Requires Node.js 18+ and npm for Vite+React preview scaffold'
+metadata:
+  author: yabafre
+  version: ${c.cliVersion || '1.7.1'}
 ---
 
 # APED UX — ANF Framework
 
+## Critical Rules
+
+- NEVER use lorem ipsum — every text element must reflect the actual product from the PRD
+- ALWAYS run the pre-delivery checklist before presenting to user
+- Take your time with each screen — quality is more important than speed
+- Do not skip the user review cycle — the prototype MUST be approved before proceeding
+
 Produces a validated, interactive React prototype from the PRD. The prototype becomes the UX spec that \`/aped-e\` consumes as the visual source of truth.
 
 **ANF = Assemble → Normalize → Fill**
@@ -590,10 +727,13 @@ Read PRD user journeys and screen inventory (from \`${a}/aped-ux/references/ux-p
    - \`src/App.tsx\` — router config
    - \`src/pages/{ScreenSlug}.tsx\` — one page per screen (initially placeholder)
 
-4. **Navigation** — working nav that links all screens:
+4. **Navigation** — read rules P9 (Navigation) from \`${a}/aped-ux/references/ux-patterns.md\`:
    - Sidebar or top nav matching design inspiration
-   - Active state indicators
-   - Mobile responsive (hamburger/drawer)
+   - Active state indicators on current route
+   - Mobile: bottom nav ≤5 items (icon + label) or hamburger/drawer
+   - Desktop ≥1024px: sidebar; smaller: bottom/top nav
+   - Predictable back behavior, preserve scroll/state
+   - Same navigation placement across all pages
 
 Run: \`npm run dev\` — verify app runs with working navigation.
 
@@ -620,42 +760,80 @@ For each screen, in priority order (core journey first):
 
 ### F1: Interaction States
 
+Read rules P7 (Animation) and P8 (Forms & Feedback) from \`${a}/aped-ux/references/ux-patterns.md\`.
+
 For each screen, add:
 
-1. **Loading states** — skeleton components or spinners where data loads
-2. **Empty states** — first-use experience, "no results" views with CTAs
-3. **Error states** — inline form validation, error boundaries, toast/snackbar
-4. **Success feedback** — confirmation messages, success toasts
+1. **Loading states** — skeleton/shimmer for operations >300ms, spinner for buttons
+2. **Empty states** — first-use experience with helpful message + CTA, "no results" views
+3. **Error states** — inline validation on blur, error below field, error summary at top for long forms
+4. **Success feedback** — toast auto-dismiss 3-5s, confirmation messages
+5. **Disabled states** — opacity 0.38-0.5, cursor change, non-interactive
+6. **Press feedback** — visual response within 80-150ms (ripple, opacity, scale 0.95-1.05)
+7. **Animations** — 150-300ms micro-interactions, transform/opacity only, ease-out enter, ease-in exit
 
-### F2: Responsive + Accessibility
+### F2: Responsive + Dark Mode
+
+Read rules P5 (Layout) and P6 (Typography & Color) from \`${a}/aped-ux/references/ux-patterns.md\`.
 
 1. **Responsive** — test and fix at 3 breakpoints:
-   - Mobile (375px): single column, hamburger nav, touch targets ≥44px
-   - Tablet (768px): adapted layout, sidebar may collapse
-   - Desktop (1440px): full layout
+   - Mobile (375px): single column, hamburger nav, touch targets ≥44px, safe areas
+   - Tablet (768px): adapted layout, sidebar may collapse, adjusted gutters
+   - Desktop (1440px): full layout, max-width container, sidebar visible
+
+2. **Dark mode** — if applicable:
+   - Semantic color tokens mapped per theme (not hardcoded hex)
+   - Desaturated/lighter variants, NOT inverted colors
+   - Primary text ≥ 4.5:1, secondary ≥ 3:1 in both modes
+   - Borders/dividers distinguishable in both modes
+   - Modal scrim: 40-60% black, foreground legible
+   - Test both themes independently
 
-2. **Accessibility** — verify:
-   - All images have alt text
-   - Form inputs have labels
-   - Color contrast ≥ 4.5:1
-   - Keyboard navigation works (Tab, Enter, Escape)
-   - Focus indicators visible
+### F3: Accessibility Pass
 
-### F3: User Review Cycle
+Read rules P1 (Accessibility) and P2 (Touch) from \`${a}/aped-ux/references/ux-patterns.md\`.
+
+- Contrast: 4.5:1 normal text, 3:1 large text (test with browser devtools)
+- Focus rings: 2-4px, visible on all interactive elements
+- Tab order: matches visual order
+- Form labels: visible, associated, not placeholder-only
+- Icon buttons: aria-label
+- Skip-to-main link
+- Heading hierarchy: h1→h2→h3, no skipping
+- Touch targets: ≥44x44pt with ≥8px spacing
+- No information conveyed by color alone
+
+### F4: Pre-Delivery Checklist
+
+Read the full Pre-Delivery Checklist from \`${a}/aped-ux/references/ux-patterns.md\`.
+
+Run through ALL checks before presenting to user:
+
+**Visual Quality** — SVG icons, consistent family, no press jitter, semantic tokens, brand assets
+**Interaction** — press feedback, touch targets, micro-interaction timing, disabled states, focus order
+**Light/Dark Mode** — contrast ratios in both, dividers visible, scrim legibility
+**Layout** — safe areas, fixed bars, tested 3 devices, spacing rhythm, text readability
+**Accessibility** — labels, hints, errors, color independence, reduced motion, ARIA
+
+If any check fails: fix before showing to user.
+
+### F5: User Review Cycle
 
 **This is the most important step.** The prototype must be validated by the user.
 
 1. Run \`npm run dev\` and give the user the local URL
-2. Ask: "Review each screen. What needs to change?"
-3. Categories of feedback:
+2. Present the pre-delivery checklist results
+3. Ask: "Review each screen. What needs to change?"
+4. Categories of feedback:
    - **Layout** — move, resize, reorder sections
    - **Content** — missing info, wrong hierarchy, unclear labels
    - **Style** — colors, spacing, typography adjustments
    - **Flow** — navigation changes, missing screens, wrong order
    - **Components** — wrong component type, missing states, wrong behavior
+   - **Dark mode** — contrast issues, token problems, scrim opacity
 
-4. **Iterate** until user says "approved" or "good enough"
-5. Each iteration: apply feedback → run dev → ask again
+5. **Iterate** until user says "approved" or "good enough"
+6. Each iteration: apply feedback → run checklist again → present → ask again
 
 \`TaskUpdate: "F — Fill: user review" → completed\`
 
@@ -706,6 +884,14 @@ Invoke Skill tool with \`skill: "aped-e"\` to proceed to Epics phase.
 - Screen references (wireframe screenshots)
 - Design tokens to respect
 - Responsive requirements per screen
+
+## Common Issues
+
+- **npm create vite fails**: Ensure Node.js 18+ is installed. Try \`node --version\` first.
+- **UI library install fails**: Check network. For shadcn, ensure the project has a tsconfig.json.
+- **User gives no design inspiration**: Use the product domain to suggest a style — "SaaS dashboard" → clean/minimal, "e-commerce" → card-heavy/visual
+- **Prototype looks wrong on mobile**: Check responsive breakpoints — sidebar must collapse, touch targets ≥ 44px
+- **Dark mode contrast fails**: Use semantic tokens, not hardcoded colors. Check with browser devtools contrast checker.
 `,
     },
     // ── aped-s ──────────────────────────────────────────────
@@ -714,7 +900,11 @@ Invoke Skill tool with \`skill: "aped-e"\` to proceed to Epics phase.
       content: `---
 name: aped-s
 description: 'Shows sprint status dashboard with progress, blockers, and next actions. Use when user says "sprint status", "show progress", "aped status", or invokes /aped-s.'
-allowed-tools: Read, Grep, Glob, Bash
+allowed-tools: "Read Grep Glob Bash"
+license: MIT
+metadata:
+  author: yabafre
+  version: ${c.cliVersion || '1.7.1'}
 ---
 
 # APED Status — Sprint Dashboard
@@ -776,6 +966,20 @@ If \`ticket_system\` is not \`none\`:
 ## Output
 
 Display only — no file writes, no state changes. Pure read-only dashboard.
+
+## Example
+
+\`\`\`
+Pipeline: A[✓] → P[✓] → UX[✓] → E[✓] → D[▶] → R[ ]
+Epic 1: User Auth        [████████░░] 80% (4/5)
+Epic 2: Dashboard         [██░░░░░░░░] 20% (1/5)
+Next: /aped-d (story 1-5-session-mgmt is ready-for-dev)
+\`\`\`
+
+## Common Issues
+
+- **State file not found**: Ensure \`${o}/state.yaml\` exists — run /aped-a first
+- **Stories show wrong status**: State.yaml may be stale — re-run the last phase to update it
 `,
     },
     // ── aped-c ──────────────────────────────────────────────
@@ -785,6 +989,10 @@ Display only — no file writes, no state changes. Pure read-only dashboard.
 name: aped-c
 description: 'Manages scope changes and pivots during development with impact analysis. Use when user says "correct course", "change scope", "pivot", "aped correct", or invokes /aped-c.'
 disable-model-invocation: true
+license: MIT
+metadata:
+  author: yabafre
+  version: ${c.cliVersion || '1.7.1'}
 ---
 
 # APED Correct Course — Managed Pivot
@@ -858,6 +1066,22 @@ After applying changes, verify:
 - No epic became too large (>8 stories)
 - No story became too large (>8 tasks)
 - Changed stories still fit single-session size
+
+## Example
+
+User says "We need to add OAuth — the client changed requirements":
+1. Impact: minor change — add FRs to PRD, create new stories
+2. Update PRD: add FR26-FR28 for OAuth
+3. Re-validate PRD
+4. Add stories to Epic 1 for OAuth support
+5. Re-validate coverage
+6. Reset new stories to \`ready-for-dev\`
+
+## Common Issues
+
+- **User wants to change everything**: Confirm scope — "Is this a pivot or an addition?"
+- **Invalidated stories have committed code**: Archive the code changes, don't delete — user may want to reference them
+- **FR count exceeds 80 after change**: Some features may need to move to a Growth phase scope
 `,
     },
     // ── aped-ctx ────────────────────────────────────────────
@@ -866,7 +1090,11 @@ After applying changes, verify:
       content: `---
 name: aped-ctx
 description: 'Analyzes existing codebase to generate project context for brownfield development. Use when user says "document codebase", "project context", "existing project", "aped context", or invokes /aped-ctx. Not for new project ideation — use aped-a for greenfield.'
-allowed-tools: Read, Grep, Glob, Bash
+allowed-tools: "Read Grep Glob Bash"
+license: MIT
+metadata:
+  author: yabafre
+  version: ${c.cliVersion || '1.7.1'}
 ---
 
 # APED Context — Brownfield Project Analysis
@@ -959,6 +1187,20 @@ project_context:
 Suggest:
 - If no brief exists: run \`/aped-a\` with project context loaded
 - If brief exists: context will inform \`/aped-p\` and \`/aped-d\` decisions
+
+## Example
+
+Scanning a Next.js SaaS project → project-context.md:
+- Stack: TypeScript, Next.js 14, Prisma, PostgreSQL
+- Pattern: App Router, server components, feature-based folders
+- Conventions: camelCase files, Zod validation, Tailwind CSS
+- 45 dependencies, 3 outdated, 0 security advisories
+
+## Common Issues
+
+- **No package.json/Cargo.toml found**: Project may be multi-language or unconventional — scan for entry points manually
+- **Very large codebase (>1000 files)**: Focus on src/ and key config files, don't scan node_modules or build output
+- **Monorepo detected**: Document each package/app separately in the context file
 `,
     },
     // ── aped-qa ─────────────────────────────────────────────
@@ -967,6 +1209,10 @@ Suggest:
       content: `---
 name: aped-qa
 description: 'Generates E2E and integration tests from acceptance criteria for completed features. Use when user says "generate tests", "E2E tests", "integration tests", "aped qa", or invokes /aped-qa.'
+license: MIT
+metadata:
+  author: yabafre
+  version: ${c.cliVersion || '1.7.1'}
 ---
 
 # APED QA — E2E & Integration Test Generation
@@ -1069,6 +1315,19 @@ QA doesn't affect pipeline state — it's an additive quality layer.
 ## Next Steps
 
 Suggest running \`/aped-s\` to view updated sprint status with QA coverage noted.
+
+## Example
+
+Epic 1 completed (3 stories) → generate QA:
+- E2E: 5 tests covering registration → login → dashboard journey
+- Integration: 3 API tests for auth endpoints
+- Report: 8/8 ACs covered, 0 gaps, 1 manual test suggested (email verification)
+
+## Common Issues
+
+- **Test framework not detected**: Check project config — ensure test runner is in dependencies
+- **ACs not testable**: Some ACs describe UX behavior — flag as "manual test required" in report
+- **Tests fail on generated code**: Review the test — it may assume a specific API shape. Adapt to actual implementation
 `,
     },
     // ── aped-quick ────────────────────────────────────────────
@@ -1077,6 +1336,10 @@ Suggest running \`/aped-s\` to view updated sprint status with QA coverage noted
       content: `---
 name: aped-quick
 description: 'Implements quick fixes and small features bypassing the full pipeline. Use when user says "quick fix", "quick feature", "hotfix", "aped quick", or invokes /aped-quick.'
+license: MIT
+metadata:
+  author: yabafre
+  version: ${c.cliVersion || '1.7.1'}
 ---
 
 # APED Quick — Fast Track for Small Changes
@@ -1140,6 +1403,20 @@ Read \`ticket_system\` and \`git_provider\` from config.
 1. Write quick spec to \`${o}/quick-specs/\` (create dir if needed)
 2. No state.yaml update — quick specs don't affect pipeline phase
 3. Report: files changed, tests added, quick spec path
+
+## Example
+
+User: "quick fix the login button not submitting"
+1. Quick spec: fix, "login form submit handler not wired"
+2. RED: test that clicking submit calls auth API
+3. GREEN: wire onClick → submitForm()
+4. Self-review: tests pass, no security issues
+5. Commit: \`fix(auth): wire login form submit handler\`
+
+## Common Issues
+
+- **Change touches >5 files**: This is too big for quick — recommend full pipeline
+- **New dependency needed**: HALT — ask user, this may need architectural discussion
 `,
     },
     // ── aped-all ─────────────────────────────────────────────
@@ -1149,6 +1426,10 @@ Read \`ticket_system\` and \`git_provider\` from config.
 name: aped-all
 description: 'Runs the full APED pipeline from Analyze through Review with auto-resume. Use when user says "run full pipeline", "aped all", or invokes /aped-all.'
 disable-model-invocation: true
+license: MIT
+metadata:
+  author: yabafre
+  version: ${c.cliVersion || '1.7.1'}
 ---
 
 # APED Pipeline — Full Orchestrator
@@ -1194,6 +1475,22 @@ State persists in \`${o}/state.yaml\`. Next \`/aped-all\` resumes from last inco
 ## Completion Report
 
 Total phases, epics, stories, review iterations. Pipeline status: COMPLETE.
+
+## Example
+
+Fresh start → full pipeline run:
+1. A: 3 parallel agents → product brief (5 min)
+2. P: PRD with 20 FRs generated + validated (3 min)
+3. UX: user says "skip" → proceed to epics
+4. E: 3 epics, 8 stories created (3 min)
+5. D→R loop: 8 stories × (dev + review) cycles
+6. All done → pipeline COMPLETE
+
+## Common Issues
+
+- **Phase fails and can't recover**: Check state.yaml — reset the failed phase to \`in-progress\` and re-run /aped-all
+- **Context window limit during long pipeline**: Normal — /aped-all chains via Skill tool which starts fresh context per phase
+- **User wants to skip a phase**: Supported — each phase asks "redo or skip?" if already done
 `,
     },
   ];