aped-method 1.7.0 → 1.9.0

package/package.json

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

package/src/templates/references.js

@@ -50,6 +50,22 @@ export function references(c) {
       path: `${a}/aped-ux/references/ux-patterns.md`,
       content: UX_PATTERNS,
     },
+    {
+      path: `${a}/aped-s/references/status-format.md`,
+      content: STATUS_FORMAT,
+    },
+    {
+      path: `${a}/aped-c/references/scope-change-guide.md`,
+      content: SCOPE_CHANGE_GUIDE,
+    },
+    {
+      path: `${a}/aped-ctx/references/analysis-checklist.md`,
+      content: ANALYSIS_CHECKLIST,
+    },
+    {
+      path: `${a}/aped-qa/references/test-patterns.md`,
+      content: TEST_PATTERNS,
+    },
   ];
 }
 
@@ -552,7 +568,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 +775,339 @@ 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
+`;
+
+const STATUS_FORMAT = `# Sprint Status Dashboard Format
+
+## Pipeline Progress Bar
+
+Display format:
+\`\`\`
+Pipeline: A[✓] → P[✓] → UX[✓] → E[✓] → D[▶] → R[ ]
+\`\`\`
+
+Symbols:
+- \`✓\` = phase done
+- \`▶\` = phase in-progress
+- \` \` = phase not started
+- \`—\` = phase skipped
+
+## Epic Progress Bar
+
+\`\`\`
+Epic 1: {{title}}  [████████░░] 80% (4/5 stories)
+\`\`\`
+
+- Bar: 10 chars wide, \`█\` for done, \`░\` for remaining
+- Show fraction and percentage
+
+## Story Status Icons
+
+| Status | Icon | Meaning |
+|--------|------|---------|
+| done | ✓ | Story completed and reviewed |
+| review | ⟳ | Waiting for adversarial review |
+| in-progress | ▶ | Currently being implemented |
+| ready-for-dev | ○ | Ready to start |
+| backlog | · | Not yet planned |
+| blocked | ✗ | Blocked by issue |
+
+## Blocker Categories
+
+- **[AI-Review]** items — review findings not yet addressed
+- **HALT** — dev stopped due to missing config/dependency/ambiguity
+- **Stuck** — in-progress for multiple sessions without progress
+- **Dependency** — blocked by another story
+
+## Next Action Logic
+
+| Current State | Suggestion |
+|---------------|------------|
+| Stories ready-for-dev | "Run /aped-d to implement next story" |
+| Stories in review | "Run /aped-r to review completed story" |
+| All stories done | "Pipeline complete! Run /aped-qa for E2E tests" |
+| Blockers found | Describe each blocker and resolution path |
+| No state file | "Run /aped-a to start the pipeline" |
+`;
+
+const SCOPE_CHANGE_GUIDE = `# Scope Change Management Guide
+
+## Impact Assessment Matrix
+
+| Change Type | PRD | UX | Epics | Stories | Code | Severity |
+|-------------|-----|-----|-------|---------|------|----------|
+| New feature added | Add FRs | Add screens | New stories | Create | None | Minor |
+| Feature removed | Remove FRs | Remove screens | Archive stories | Archive | May delete | Minor |
+| FR modified | Update FR | May update | Update story ACs | Update | May refactor | Medium |
+| Architecture change | Update NFRs | May rebuild | Update all Dev Notes | Reset | May rewrite | Major |
+| Priority reorder | No change | No change | Reorder | Reset status | None | Minor |
+| Complete pivot | Restart | Restart | Restart | Restart | Archive | Critical |
+
+## Change Process
+
+### Step 1: Document the Change
+- What changed and why
+- Who requested it (user, stakeholder, technical discovery)
+- Date of change
+
+### Step 2: Impact Analysis
+- List all affected artifacts (PRD sections, stories, code files)
+- Classify severity (minor/medium/major/critical)
+- Estimate effort to apply change
+
+### Step 3: User Confirmation
+- Present impact summary to user
+- Get explicit "proceed" before making changes
+- For major/critical: warn about in-progress work loss
+
+### Step 4: Execute Change
+- Archive affected artifacts to \`{output}/archive/{date}/\`
+- Apply changes top-down (PRD → UX → Epics → Stories)
+- Re-validate at each level (scripts)
+- Update state.yaml
+
+### Step 5: Verify Consistency
+- FR coverage still 100%
+- No orphan stories
+- No broken dependencies
+- State reflects new reality
+
+## Scope Creep Detection
+
+Warning signs:
+- Total FRs grew >20% from original PRD
+- Epic count increased
+- Stories consistently exceed single-session size
+- "Just one more thing" pattern repeating
+
+Response:
+- Flag to user with metrics
+- Suggest moving additions to Growth phase
+- Enforce MVP discipline
+`;
+
+const ANALYSIS_CHECKLIST = `# Brownfield Project Analysis Checklist
+
+## Phase 1: Structure Discovery
+
+- [ ] Identify primary language(s) from config files
+- [ ] Map directory structure (max 3 levels)
+- [ ] Find entry points (main, index, app, server)
+- [ ] Count: files, LOC, languages
+- [ ] Identify package manager (npm, yarn, pnpm, cargo, pip, go mod)
+- [ ] Check for monorepo structure (workspaces, packages/)
+
+## Phase 2: Architecture Mapping
+
+- [ ] Identify pattern (MVC, hexagonal, microservices, monolith, serverless)
+- [ ] Map data flow: entry → processing → storage → response
+- [ ] List databases and data stores
+- [ ] List external API integrations
+- [ ] List message queues/event systems
+- [ ] Identify caching layer
+- [ ] Map authentication/authorization flow
+
+## Phase 3: Convention Extraction
+
+- [ ] File naming convention (camelCase, kebab-case, PascalCase)
+- [ ] Function/method naming convention
+- [ ] Code organization (feature-based, layer-based, domain-based)
+- [ ] Error handling pattern (try/catch, Result type, error codes)
+- [ ] Logging approach (structured, unstructured, library used)
+- [ ] Config management (env vars, .env files, config files, vault)
+- [ ] Linting/formatting (ESLint, Prettier, Biome, rustfmt)
+
+## Phase 4: Dependency Audit
+
+- [ ] List production dependencies with versions
+- [ ] Flag outdated packages (major versions behind)
+- [ ] Check for known security advisories
+- [ ] Identify lock file type
+- [ ] Note any vendored/bundled dependencies
+- [ ] Check for deprecated packages
+
+## Phase 5: Testing
+
+- [ ] Identify test framework(s)
+- [ ] Estimate test coverage (file count, coverage reports)
+- [ ] Check for CI/CD pipeline config
+- [ ] Identify test types present (unit, integration, E2E)
+- [ ] Check for test fixtures/factories/mocks
+
+## Output Format
+
+\`\`\`markdown
+# Project Context: {name}
+
+## Tech Stack
+- Language: {lang} {version}
+- Framework: {framework} {version}
+- Database: {db}
+- Test Framework: {test_fw}
+
+## Architecture
+- Pattern: {pattern}
+- Entry: {entry_point}
+- Modules: {key_modules}
+
+## Conventions
+- Files: {naming}
+- Code style: {linter}
+- Error handling: {pattern}
+
+## Dependencies ({count} total)
+| Package | Version | Purpose | Status |
+|---------|---------|---------|--------|
+
+## Integration Points
+| Service | Purpose | Protocol |
+|---------|---------|----------|
+
+## Notes
+- {important_context_for_dev}
+\`\`\`
+`;
+
+const TEST_PATTERNS = `# E2E & Integration Test Patterns
+
+## Framework Selection
+
+| Project Type | E2E Framework | Integration Framework |
+|-------------|---------------|----------------------|
+| Node.js + React | Playwright or Cypress | Supertest + Vitest |
+| Node.js + API only | - | Supertest + Jest/Vitest |
+| Next.js | Playwright | Next.js test utils |
+| Python + Django/Flask | Playwright | pytest + httpx |
+| Python + FastAPI | Playwright | pytest + httpx |
+| Go | - | go test + httptest |
+| Rust | - | reqwest + tokio::test |
+
+## E2E Test Structure
+
+\`\`\`
+tests/e2e/
+  {journey-name}.test.{ext}     # One file per user journey
+  fixtures/                      # Test data
+  helpers/                       # Page objects, utilities
+\`\`\`
+
+### User Journey Test Template
+
+\`\`\`
+describe("{Journey Name}", () => {
+  test("happy path: {description}", async () => {
+    // Given: {precondition from AC}
+    // When: {action from AC}
+    // Then: {outcome from AC}
+  });
+
+  test("error: {error scenario}", async () => {
+    // Given: {invalid state}
+    // When: {action}
+    // Then: {error handling}
+  });
+
+  test("edge: {edge case}", async () => {
+    // Given: {boundary condition}
+    // When: {action}
+    // Then: {expected behavior}
+  });
+});
+\`\`\`
+
+## Integration Test Structure
+
+\`\`\`
+tests/integration/
+  {endpoint-or-service}.test.{ext}
+  fixtures/
+  helpers/
+\`\`\`
+
+### API Test Template
+
+\`\`\`
+describe("{Endpoint/Service}", () => {
+  test("POST /api/resource - creates resource", async () => {
+    // Arrange: valid payload
+    // Act: POST request
+    // Assert: 201, response body, DB state
+  });
+
+  test("POST /api/resource - 400 on invalid input", async () => {
+    // Arrange: invalid payload
+    // Act: POST request
+    // Assert: 400, error message
+  });
+
+  test("GET /api/resource/:id - 404 on missing", async () => {
+    // Arrange: non-existent ID
+    // Act: GET request
+    // Assert: 404
+  });
+
+  test("auth: rejects unauthenticated requests", async () => {
+    // Arrange: no auth header
+    // Act: request
+    // Assert: 401
+  });
+});
+\`\`\`
+
+## Test Coverage Goals
+
+| Category | Target | How to verify |
+|----------|--------|---------------|
+| AC coverage | 100% of ACs have tests | Map each AC → test |
+| Happy paths | Every user journey | 1 E2E test per journey |
+| Error paths | All error states | 1 test per error scenario |
+| Auth boundaries | All protected routes | Unauthorized + forbidden |
+| Edge cases | Empty, null, max values | Boundary value analysis |
+
+## Anti-Patterns
+
+- **Flaky tests**: Don't depend on timing. Use waitFor, retries, explicit waits.
+- **Shared state**: Each test must be independent. Reset DB/state before each.
+- **Hardcoded selectors**: Use data-testid or accessible roles, not CSS classes.
+- **Testing implementation**: Test behavior, not internal structure.
+- **No assertions**: Every test must assert something. \`expect(true).toBe(true)\` is not a test.
 `;

package/src/templates/scripts.js

@@ -338,6 +338,105 @@ if [[ \${#IN_STORY_NOT_GIT[@]} -gt 0 ]]; then
   exit 1
 fi
 
+exit 0
+`,
+    },
+    {
+      path: `${a}/aped-ux/scripts/validate-ux.sh`,
+      executable: true,
+      content: `#!/usr/bin/env bash
+# Validate UX design spec completeness
+# Usage: validate-ux.sh <ux-dir>
+# Exit 0 if valid, exit 1 with missing items listed
+
+set -euo pipefail
+
+if [[ $# -ne 1 ]]; then
+  echo "Usage: $0 <ux-directory>"
+  exit 1
+fi
+
+UX_DIR="$1"
+
+if [[ ! -d "$UX_DIR" ]]; then
+  echo "ERROR: Directory not found: $UX_DIR"
+  exit 1
+fi
+
+ISSUES=()
+
+# Check required output files
+REQUIRED_FILES=(
+  "design-spec.md"
+  "screen-inventory.md"
+  "components.md"
+  "flows.md"
+)
+
+for file in "\${REQUIRED_FILES[@]}"; do
+  if [[ ! -f "$UX_DIR/$file" ]]; then
+    ISSUES+=("MISSING FILE: $UX_DIR/$file")
+  fi
+done
+
+# Check design-spec.md has required sections
+if [[ -f "$UX_DIR/design-spec.md" ]]; then
+  SPEC_SECTIONS=(
+    "## Tech Stack"
+    "## Architecture"
+    "## Conventions"
+    "## Dependencies"
+  )
+
+  # Reuse pattern: check for sections about design tokens and UI library
+  if ! grep -q "color\\|Color\\|palette\\|token" "$UX_DIR/design-spec.md" 2>/dev/null; then
+    ISSUES+=("MISSING CONTENT: design-spec.md has no color/token definitions")
+  fi
+
+  if ! grep -q "typography\\|Typography\\|font\\|Font" "$UX_DIR/design-spec.md" 2>/dev/null; then
+    ISSUES+=("MISSING CONTENT: design-spec.md has no typography definitions")
+  fi
+fi
+
+# Check screen-inventory.md has content
+if [[ -f "$UX_DIR/screen-inventory.md" ]]; then
+  SCREEN_COUNT=$(grep -cE '^\\|.*\\|.*\\|' "$UX_DIR/screen-inventory.md" 2>/dev/null || echo 0)
+  if [[ "$SCREEN_COUNT" -lt 3 ]]; then
+    ISSUES+=("LOW SCREEN COUNT: Found $SCREEN_COUNT screens (expected at least 3)")
+  fi
+fi
+
+# Check components.md has component entries
+if [[ -f "$UX_DIR/components.md" ]]; then
+  COMP_COUNT=$(grep -cE '^#{2,3} ' "$UX_DIR/components.md" 2>/dev/null || echo 0)
+  if [[ "$COMP_COUNT" -lt 3 ]]; then
+    ISSUES+=("LOW COMPONENT COUNT: Found $COMP_COUNT components (expected at least 3)")
+  fi
+fi
+
+# Check preview app exists
+PREVIEW_DIR="\${UX_DIR}-preview"
+if [[ -d "$PREVIEW_DIR" ]]; then
+  if [[ ! -f "$PREVIEW_DIR/package.json" ]]; then
+    ISSUES+=("MISSING: Preview app has no package.json")
+  fi
+  if [[ ! -d "$PREVIEW_DIR/src" ]]; then
+    ISSUES+=("MISSING: Preview app has no src/ directory")
+  fi
+else
+  ISSUES+=("WARNING: No preview app at $PREVIEW_DIR (optional but recommended)")
+fi
+
+# Report
+if [[ \${#ISSUES[@]} -gt 0 ]]; then
+  echo "UX VALIDATION FAILED — Issues found:"
+  for issue in "\${ISSUES[@]}"; do
+    echo "  - $issue"
+  done
+  exit 1
+fi
+
+echo "UX VALIDATION PASSED — All required files and content present"
 exit 0
 `,
     },

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 + Dark Mode
 
-### F2: Responsive + Accessibility
+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
+
+### F3: Accessibility Pass
+
+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
 
-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
+### F4: Pre-Delivery Checklist
 
-### F3: User Review Cycle
+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\`
 
@@ -682,6 +860,14 @@ mkdir -p ${o}/ux
 5. Write \`${o}/ux/flows.md\` — navigation flow diagrams
 6. Take **screenshots** of each screen at desktop resolution → \`${o}/ux/screenshots/\`
 
+## Validation
+
+\`\`\`bash
+bash ${a}/aped-ux/scripts/validate-ux.sh ${o}/ux
+\`\`\`
+
+If validation fails: fix missing files or content and re-validate.
+
 ## State Update
 
 Update \`${o}/state.yaml\`:
@@ -706,6 +892,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 +908,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
@@ -723,6 +921,7 @@ allowed-tools: Read, Grep, Glob, Bash
 
 1. Read \`${a}/config.yaml\` — extract \`communication_language\`, \`ticket_system\`
 2. Read \`${o}/state.yaml\` — load full pipeline and sprint state
+3. Read \`${a}/aped-s/references/status-format.md\` for display conventions
 
 ## Pipeline Overview
 
@@ -776,6 +975,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 +998,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
@@ -796,6 +1013,7 @@ Use when requirements change, priorities shift, or the current approach needs re
 1. Read \`${a}/config.yaml\` — extract config
 2. Read \`${o}/state.yaml\` — understand current pipeline state
 3. Read existing artifacts: brief, PRD, epics, stories
+4. Read \`${a}/aped-c/references/scope-change-guide.md\` for impact matrix and process
 
 ## Impact Assessment
 
@@ -858,6 +1076,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 +1100,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
@@ -877,6 +1115,7 @@ Use on existing codebases to generate project context before running the APED pi
 
 1. Read \`${a}/config.yaml\` — extract config
 2. Verify this is a brownfield project (existing code, not greenfield)
+3. Read \`${a}/aped-ctx/references/analysis-checklist.md\` for the full analysis checklist
 
 ## Codebase Analysis
 
@@ -959,6 +1198,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 +1220,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
@@ -977,6 +1234,7 @@ Generate comprehensive end-to-end and integration tests for completed stories or
 
 1. Read \`${a}/config.yaml\` — extract config
 2. Read \`${o}/state.yaml\` — find completed stories/epics
+3. Read \`${a}/aped-qa/references/test-patterns.md\` for framework selection and test templates
 
 ## Scope Selection
 
@@ -1069,6 +1327,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 +1348,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 +1415,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 +1438,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 +1487,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
 `,
     },
   ];