aped-method 1.3.0 → 1.6.0

package/bin/create-aped.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { run } from '../src/index.js';
+
+run().catch((err) => {
+  console.error('\x1b[31mError:\x1b[0m', err.message);
+  process.exit(1);
+});

package/package.json

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

package/src/index.js

@@ -63,7 +63,7 @@ ${a.lime}${a.bold}          M  E  T  H  O  D${a.reset}
 ${a.dim}    ─────────────────────────────────${a.reset}
 `;
 
-const PIPELINE = `    ${a.emerald}${a.bold}A${a.reset}${a.dim}nalyze${a.reset}  ${a.dim}→${a.reset}  ${a.mint}${a.bold}P${a.reset}${a.dim}RD${a.reset}  ${a.dim}→${a.reset}  ${a.yellow}${a.bold}E${a.reset}${a.dim}pics${a.reset}  ${a.dim}→${a.reset}  ${a.lime}${a.bold}D${a.reset}${a.dim}ev${a.reset}  ${a.dim}→${a.reset}  ${a.red}${a.bold}R${a.reset}${a.dim}eview${a.reset}`;
+const PIPELINE = `    ${a.emerald}${a.bold}A${a.reset}${a.dim}nalyze${a.reset}  ${a.dim}→${a.reset}  ${a.mint}${a.bold}P${a.reset}${a.dim}RD${a.reset}  ${a.dim}→${a.reset}  ${a.magenta}${a.bold}UX${a.reset}  ${a.dim}→${a.reset}  ${a.yellow}${a.bold}E${a.reset}${a.dim}pics${a.reset}  ${a.dim}→${a.reset}  ${a.lime}${a.bold}D${a.reset}${a.dim}ev${a.reset}  ${a.dim}→${a.reset}  ${a.red}${a.bold}R${a.reset}${a.dim}eview${a.reset}`;
 
 // ── Spinner ──
 const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
@@ -580,15 +580,22 @@ function printDone(created, updated, skipped, mode) {
   console.log(`  ${a.emerald}${a.bold}╚══════════════════════════════════════╝${a.reset}`);
   console.log('');
 
-  console.log(`  ${a.bold}Available commands:${a.reset}`);
+  console.log(`  ${a.bold}Pipeline commands:${a.reset}`);
   console.log('');
-  console.log(`    ${a.emerald}${a.bold}/aped-a${a.reset}    ${dim('Analyze — parallel research → product brief')}`);
-  console.log(`    ${a.mint}${a.bold}/aped-p${a.reset}    ${dim('PRD — autonomous generation from brief')}`);
-  console.log(`    ${a.yellow}${a.bold}/aped-e${a.reset}    ${dim('Epics — requirements decomposition')}`);
-  console.log(`    ${a.lime}${a.bold}/aped-d${a.reset}    ${dim('Dev — TDD story implementation')}`);
-  console.log(`    ${a.red}${a.bold}/aped-r${a.reset}    ${dim('Review — adversarial code review')}`);
+  console.log(`    ${a.emerald}${a.bold}/aped-a${a.reset}     ${dim('Analyze — parallel research → product brief')}`);
+  console.log(`    ${a.mint}${a.bold}/aped-p${a.reset}     ${dim('PRD — autonomous generation from brief')}`);
+  console.log(`    ${a.magenta}${a.bold}/aped-ux${a.reset}    ${dim('UX — screen flows, wireframes, components')}`);
+  console.log(`    ${a.yellow}${a.bold}/aped-e${a.reset}     ${dim('Epics — requirements decomposition')}`);
+  console.log(`    ${a.lime}${a.bold}/aped-d${a.reset}     ${dim('Dev — TDD story implementation')}`);
+  console.log(`    ${a.red}${a.bold}/aped-r${a.reset}     ${dim('Review — adversarial code review')}`);
   console.log('');
-  console.log(`    ${a.spring}${a.bold}/aped-quick${a.reset} ${dim('Quick fix/feature — bypass full pipeline')}`);
+  console.log(`  ${a.bold}Utility commands:${a.reset}`);
+  console.log('');
+  console.log(`    ${a.spring}${a.bold}/aped-s${a.reset}     ${dim('Sprint status — progress dashboard')}`);
+  console.log(`    ${a.spring}${a.bold}/aped-c${a.reset}     ${dim('Correct course — manage scope changes')}`);
+  console.log(`    ${a.spring}${a.bold}/aped-ctx${a.reset}   ${dim('Project context — brownfield analysis')}`);
+  console.log(`    ${a.spring}${a.bold}/aped-qa${a.reset}    ${dim('QA — generate E2E & integration tests')}`);
+  console.log(`    ${a.spring}${a.bold}/aped-quick${a.reset} ${dim('Quick fix/feature — bypass pipeline')}`);
   console.log(`    ${a.spring}${a.bold}/aped-all${a.reset}   ${dim('Full pipeline A→P→E→D→R')}`);
   console.log('');
   console.log(`  ${dim('Guardrail hook active — pipeline coherence enforced')}`);

package/src/templates/commands.js

@@ -5,7 +5,7 @@ export function commands(c) {
       path: `${c.commandsDir}/aped-a.md`,
       content: `---
 name: aped-a
-description: 'Analyze project through parallel research. Use when user says "analyze", "research project", or "aped analyze"'
+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.'
 ---
 
 Read and follow the SKILL.md at $PROJECT_ROOT/${a}/aped-a/SKILL.md
@@ -15,7 +15,7 @@ Read and follow the SKILL.md at $PROJECT_ROOT/${a}/aped-a/SKILL.md
       path: `${c.commandsDir}/aped-p.md`,
       content: `---
 name: aped-p
-description: 'Generate PRD from product brief. Use when user says "create PRD", "generate PRD", or "aped prd"'
+description: 'Generates PRD autonomously from product brief. Use when user says "create PRD", "generate PRD", "aped prd", or invokes /aped-p.'
 ---
 
 Read and follow the SKILL.md at $PROJECT_ROOT/${a}/aped-p/SKILL.md
@@ -25,7 +25,7 @@ Read and follow the SKILL.md at $PROJECT_ROOT/${a}/aped-p/SKILL.md
       path: `${c.commandsDir}/aped-e.md`,
       content: `---
 name: aped-e
-description: 'Create epics and stories from PRD. Use when user says "create epics", "break into stories", or "aped epics"'
+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.'
 ---
 
 Read and follow the SKILL.md at $PROJECT_ROOT/${a}/aped-e/SKILL.md
@@ -35,7 +35,7 @@ Read and follow the SKILL.md at $PROJECT_ROOT/${a}/aped-e/SKILL.md
       path: `${c.commandsDir}/aped-d.md`,
       content: `---
 name: aped-d
-description: 'Dev sprint - implement next story with TDD. Use when user says "start dev", "implement story", or "aped dev"'
+description: 'Implements next story with TDD red-green-refactor cycle. Use when user says "start dev", "implement story", "aped dev", or invokes /aped-d.'
 ---
 
 Read and follow the SKILL.md at $PROJECT_ROOT/${a}/aped-d/SKILL.md
@@ -45,17 +45,67 @@ Read and follow the SKILL.md at $PROJECT_ROOT/${a}/aped-d/SKILL.md
       path: `${c.commandsDir}/aped-r.md`,
       content: `---
 name: aped-r
-description: 'Adversarial code review for completed story. Use when user says "review code", "run review", or "aped review"'
+description: 'Reviews completed stories adversarially with minimum 3 findings. Use when user says "review code", "run review", "aped review", or invokes /aped-r.'
 ---
 
 Read and follow the SKILL.md at $PROJECT_ROOT/${a}/aped-r/SKILL.md
+`,
+    },
+    {
+      path: `${c.commandsDir}/aped-ux.md`,
+      content: `---
+name: aped-ux
+description: 'Designs UX specifications from PRD — screen flows, wireframes, component inventory. Use when user says "design UX", "create wireframes", "UX spec", "aped ux", or invokes /aped-ux. Runs between PRD and Epics phases.'
+---
+
+Read and follow the SKILL.md at $PROJECT_ROOT/${a}/aped-ux/SKILL.md
+`,
+    },
+    {
+      path: `${c.commandsDir}/aped-s.md`,
+      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.'
+---
+
+Read and follow the SKILL.md at $PROJECT_ROOT/${a}/aped-s/SKILL.md
+`,
+    },
+    {
+      path: `${c.commandsDir}/aped-c.md`,
+      content: `---
+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.'
+---
+
+Read and follow the SKILL.md at $PROJECT_ROOT/${a}/aped-c/SKILL.md
+`,
+    },
+    {
+      path: `${c.commandsDir}/aped-ctx.md`,
+      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.'
+---
+
+Read and follow the SKILL.md at $PROJECT_ROOT/${a}/aped-ctx/SKILL.md
+`,
+    },
+    {
+      path: `${c.commandsDir}/aped-qa.md`,
+      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.'
+---
+
+Read and follow the SKILL.md at $PROJECT_ROOT/${a}/aped-qa/SKILL.md
 `,
     },
     {
       path: `${c.commandsDir}/aped-quick.md`,
       content: `---
 name: aped-quick
-description: 'Quick fix/feature bypassing full pipeline. Use when user says "quick fix", "quick feature", "aped quick", or "hotfix"'
+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.'
 ---
 
 Read and follow the SKILL.md at $PROJECT_ROOT/${a}/aped-quick/SKILL.md
@@ -65,7 +115,7 @@ Read and follow the SKILL.md at $PROJECT_ROOT/${a}/aped-quick/SKILL.md
       path: `${c.commandsDir}/aped-all.md`,
       content: `---
 name: aped-all
-description: 'Run full APED pipeline (Analyze>PRD>Epics>Dev>Review). Use when user says "run full pipeline", "aped all", or "start from scratch"'
+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.'
 ---
 
 Read and follow the SKILL.md at $PROJECT_ROOT/${a}/aped-all/SKILL.md

package/src/templates/guardrail.js

@@ -73,8 +73,8 @@ HAS_EPICS=false
 # ── Phase-aware guardrail logic ──
 WARNINGS=()
 
-# Phase transition map: none → analyze → prd → epics → dev ↔ review → done
-PHASE_ORDER="none analyze prd epics dev review done"
+# Phase transition map: none → analyze → prd → ux → epics → dev ↔ review → done
+PHASE_ORDER="none analyze prd ux epics dev review done"
 
 phase_index() {
   local i=0

package/src/templates/references.js

@@ -46,6 +46,10 @@ export function references(c) {
       path: `${a}/aped-r/references/review-criteria.md`,
       content: REVIEW_CRITERIA,
     },
+    {
+      path: `${a}/aped-ux/references/ux-patterns.md`,
+      content: UX_PATTERNS,
+    },
   ];
 }
 
@@ -547,3 +551,84 @@ web_app,"website,webapp,browser,SPA,PWA","SPA or MPA?;Browser support?;SEO neede
 mobile_app,"iOS,Android,app,mobile,iPhone,iPad","Native or cross-platform?;Offline needed?;Push notifications?;Device features?;Store compliance?","platform_reqs;device_permissions;offline_mode;push_strategy;store_compliance","desktop_features;cli_commands","app store guidelines;platform requirements","Gesture innovation;AR/VR features"
 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
+
+## Screen Types
+
+### Form Screens
+- **Login/Register**: email + password, social auth buttons, forgot link
+- **Settings**: grouped sections, save/cancel, inline validation
+- **Wizard/Multi-step**: progress indicator, back/next, step validation
+- **Search + Filters**: search bar, filter sidebar/chips, results list
+
+### List Screens
+- **Data Table**: sortable headers, row actions, pagination, bulk select
+- **Card Grid**: image + title + meta, responsive columns, load more
+- **Feed/Timeline**: chronological, infinite scroll, activity items
+
+### Detail Screens
+- **Profile/Entity**: header (avatar, name, stats), tabbed content, actions
+- **Article/Content**: title, meta, body, sidebar, related items
+
+### Dashboard Screens
+- **Analytics**: stat cards, charts, date range picker, export
+- **Admin**: sidebar nav, content area, notification badge
+
+### Utility Screens
+- **Empty State**: illustration, message, CTA button
+- **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
+`;

package/src/templates/skills.js

@@ -7,7 +7,7 @@ export function skills(c) {
       path: `${a}/aped-a/SKILL.md`,
       content: `---
 name: aped-a
-description: 'Analyze project idea through parallel market, domain, and technical research. Use when user says "analyze project", "research idea", "aped analyze", or invokes /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.'
 ---
 
 # APED Analyze — Parallel Research to Product Brief
@@ -29,13 +29,23 @@ Ask the user these questions (adapt to \`communication_language\`):
 
 Wait for answers before proceeding.
 
+## Task Tracking
+
+Create tasks to track this phase:
+\`\`\`
+TaskCreate: "Parallel research — Market, Domain, Technical"
+TaskCreate: "Synthesize research into product brief"
+TaskCreate: "Validate brief"
+\`\`\`
+
 ## Parallel Research
 
 Read \`${a}/aped-a/references/research-prompts.md\` for detailed agent prompts.
 
-Launch **3 Agent tool calls in parallel** with \`run_in_background: true\`:
+Launch **3 Agent tool calls in a single message** (parallel execution) with \`run_in_background: true\`:
 
 ### Agent 1: Market Research
+- \`subagent_type: "Explore"\`
 - Customer behavior and pain points in the target segment
 - Competitive landscape: direct and indirect competitors
 - Market size and growth trajectory
@@ -43,6 +53,7 @@ Launch **3 Agent tool calls in parallel** with \`run_in_background: true\`:
 - Use WebSearch for current data
 
 ### Agent 2: Domain Research
+- \`subagent_type: "Explore"\`
 - Industry analysis and key trends
 - Regulatory requirements and compliance needs
 - Technical trends shaping the domain
@@ -50,12 +61,15 @@ Launch **3 Agent tool calls in parallel** with \`run_in_background: true\`:
 - Use WebSearch for current data
 
 ### Agent 3: Technical Research
+- \`subagent_type: "Explore"\`
 - Technology stack overview and options
 - Integration patterns and APIs available
 - Architecture patterns for similar products
 - Open-source tools and frameworks relevant
 - Use WebSearch for current data
 
+Once all 3 agents return, update task: \`TaskUpdate: "Parallel research" → completed\`
+
 ## Synthesis
 
 Ensure output directory exists:
@@ -78,6 +92,12 @@ bash ${a}/aped-a/scripts/validate-brief.sh ${o}/product-brief.md
 
 If validation fails: fix missing sections and re-validate.
 
+Update tasks:
+\`\`\`
+TaskUpdate: "Synthesize research" → completed
+TaskUpdate: "Validate brief" → completed
+\`\`\`
+
 ## State Update
 
 Update \`${o}/state.yaml\`:
@@ -100,7 +120,7 @@ Invoke Skill tool with \`skill: "aped-p"\` to proceed to PRD phase.
       path: `${a}/aped-p/SKILL.md`,
       content: `---
 name: aped-p
-description: 'Generate PRD autonomously from product brief. Use when user says "create PRD", "generate PRD", "aped prd", or invokes /aped-p.'
+description: 'Generates PRD autonomously from product brief. Use when user says "create PRD", "generate PRD", "aped prd", or invokes /aped-p.'
 ---
 
 # APED PRD — Autonomous PRD Generation
@@ -127,6 +147,19 @@ description: 'Generate PRD autonomously from product brief. Use when user says "
    - Match against \`detection_signals\`
    - Note \`required_sections\`, \`skip_sections\`, \`key_questions\`
 
+## Task Tracking
+
+Create tasks for each generation phase:
+\`\`\`
+TaskCreate: "P1: Foundation — Executive Summary & Vision"
+TaskCreate: "P2: Scope & Journeys"
+TaskCreate: "P3: Domain Requirements (conditional)"
+TaskCreate: "P4: Functional & Non-Functional Requirements"
+TaskCreate: "Validate PRD"
+\`\`\`
+
+Update each task to \`completed\` as you finish each phase.
+
 ## PRD Generation (4 compressed phases)
 
 Generate the PRD autonomously using \`${a}/templates/prd.md\` as structure.
@@ -174,7 +207,9 @@ pipeline:
 
 ## Chain
 
-Invoke Skill tool with \`skill: "aped-e"\` to proceed to Epics phase.
+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
 `,
     },
     // ── aped-e ──────────────────────────────────────────────
@@ -182,7 +217,7 @@ Invoke Skill tool with \`skill: "aped-e"\` to proceed to Epics phase.
       path: `${a}/aped-e/SKILL.md`,
       content: `---
 name: aped-e
-description: 'Create epics and stories from PRD with full FR coverage. Use when user says "create epics", "break into stories", "aped epics", or invokes /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.'
 ---
 
 # APED Epics & Stories — Requirements Decomposition
@@ -200,6 +235,18 @@ description: 'Create epics and stories from PRD with full FR coverage. Use when
 - If no prd phase in state: ask user for PRD path
 - Extract ALL FRs and NFRs by number
 
+## Task Tracking
+
+\`\`\`
+TaskCreate: "Extract FRs and NFRs from PRD"
+TaskCreate: "Design epics (user-value grouping)"
+TaskCreate: "Create stories with ACs and tasks"
+TaskCreate: "FR coverage validation"
+TaskCreate: "Write story files"
+\`\`\`
+
+Update each to \`completed\` as you progress.
+
 ## Epic Design
 
 Read \`${a}/aped-e/references/epic-rules.md\` for design principles.
@@ -265,7 +312,8 @@ Invoke Skill tool with \`skill: "aped-d"\` to proceed to Dev Sprint.
       path: `${a}/aped-d/SKILL.md`,
       content: `---
 name: aped-d
-description: 'Dev sprint - implement next story with TDD red-green-refactor. Use when user says "start dev", "implement story", "aped dev", or invokes /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
 ---
 
 # APED Dev Sprint — TDD Story Implementation
@@ -290,17 +338,35 @@ If story has \`[AI-Review]\` items: address them BEFORE regular tasks.
 
 Update \`${o}/state.yaml\`: story — \`in-progress\`, epic — \`in-progress\` if first story.
 
+## Task Tracking
+
+Create a task for each story task checkbox:
+\`\`\`
+For each "- [ ] task description [AC: AC#]" in story:
+  TaskCreate: "task description" (status: todo)
+\`\`\`
+Update each to \`in_progress\` when starting RED, \`completed\` when GATE passes.
+
 ## Context Gathering
 
+Launch **2 Agent tool calls in parallel** for context:
+
+### Agent 1: Code Context
+- \`subagent_type: "Explore"\`
 - Read story Dev Notes for architecture, file paths, dependencies
-- Use MCP context7 for library docs mentioned in Dev Notes
 - Read existing code files mentioned in story
+- Map the current state of files to modify
+
+### Agent 2: Library Docs (if dependencies listed)
+- \`subagent_type: "general-purpose"\`
+- Use MCP context7 (\`resolve-library-id\` then \`query-docs\`) for libraries in Dev Notes
+- Extract relevant API patterns and usage examples
 
 ## TDD Implementation
 
 Read \`${a}/aped-d/references/tdd-engine.md\` for detailed rules.
 
-For each task:
+For each task (update TaskUpdate to \`in_progress\` when starting):
 
 ### RED
 Write failing tests first. Run: \`bash ${a}/aped-d/scripts/run-tests.sh\`
@@ -328,7 +394,7 @@ 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. Chain to \`/aped-r\`
+3. Invoke Skill tool with \`skill: "aped-r"\` to proceed to Review phase
 `,
     },
     // ── aped-r ──────────────────────────────────────────────
@@ -336,7 +402,8 @@ Read \`git_provider\` and \`ticket_system\` from config:
       path: `${a}/aped-r/SKILL.md`,
       content: `---
 name: aped-r
-description: 'Adversarial code review for completed stories. Use when user says "review code", "run review", "aped review", or invokes /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
 ---
 
 # APED Review — Adversarial Code Review
@@ -357,20 +424,33 @@ Read story from \`${o}/stories/{story-key}.md\`
 bash ${a}/aped-r/scripts/git-audit.sh ${o}/stories/{story-key}.md
 \`\`\`
 
+## Task Tracking
+
+\`\`\`
+TaskCreate: "Git audit"
+TaskCreate: "AC validation"
+TaskCreate: "Task audit"
+TaskCreate: "Code quality review"
+TaskCreate: "Generate review report"
+\`\`\`
+
 ## Adversarial Review
 
 Read \`${a}/aped-r/references/review-criteria.md\` for detailed criteria.
 
-### 1. AC Validation
-For each AC: search code for evidence (file:line). Rate: IMPLEMENTED / PARTIAL / MISSING.
+Launch **2 Agent tool calls in parallel** for the review:
+
+### Agent 1: AC & Task Validation (\`subagent_type: "feature-dev:code-explorer"\`)
+- For each AC: search code for evidence (file:line). Rate: IMPLEMENTED / PARTIAL / MISSING
+- For each \`[x]\` task: find proof in code. No evidence = **CRITICAL**
 
-### 2. Task Audit
-For each \`[x]\` task: find proof in code. No evidence = **CRITICAL**.
+### Agent 2: Code Quality (\`subagent_type: "feature-dev:code-reviewer"\`)
+- Security, Performance, Reliability, Test Quality
+- Focus on files listed in the story's File List section
 
-### 3. Code Quality
-Security, Performance, Reliability, Test Quality.
+Once both agents return, merge findings. Update tasks to \`completed\`.
 
-### 4. Minimum 3 findings enforced.
+### Minimum 3 findings enforced.
 
 ## Report
 
@@ -383,7 +463,545 @@ Severity: CRITICAL > HIGH > MEDIUM > LOW. Format: \`[Severity] Description [file
 
 ## State Update
 
-Update \`${o}/state.yaml\`. If more stories — chain to \`/aped-d\`. If all done — report completion.
+Update \`${o}/state.yaml\`. If more stories remain: invoke Skill tool with \`skill: "aped-d"\`. If all stories done: report pipeline completion.
+`,
+    },
+    // ── aped-ux ─────────────────────────────────────────────
+    {
+      path: `${a}/aped-ux/SKILL.md`,
+      content: `---
+name: aped-ux
+description: 'Designs UX specifications from PRD — screen flows, wireframes, component inventory. Use when user says "design UX", "create wireframes", "UX spec", "aped ux", or invokes /aped-ux. Runs between PRD and Epics phases.'
+---
+
+# APED UX — Spec-First UX Design
+
+Generates UX specifications from the PRD before epics creation. Produces screen flows, wireframes (ASCII), component inventories, and interaction specs that \`/aped-e\` consumes to enrich stories with visual context.
+
+## Setup
+
+1. Read \`${a}/config.yaml\` — extract config
+2. Read \`${o}/state.yaml\` — check pipeline state
+   - If \`pipeline.phases.ux.status\` is \`done\`: ask user — redo or skip?
+   - If user skips: invoke Skill tool with \`skill: "aped-e"\` and stop
+3. Read \`${a}/aped-ux/references/ux-patterns.md\` for design patterns catalog
+
+## Task Tracking
+
+\`\`\`
+TaskCreate: "Analyze PRD user journeys"
+TaskCreate: "Define screen inventory"
+TaskCreate: "Design screen flows"
+TaskCreate: "Create wireframes"
+TaskCreate: "Build component inventory"
+TaskCreate: "Write interaction specs"
+TaskCreate: "Validate UX spec"
+\`\`\`
+
+## Load PRD
+
+- Read PRD from \`pipeline.phases.prd.output\`
+- Extract: user journeys, FRs grouped by capability, actors, key workflows
+
+## Phase 1: Screen Inventory
+
+For each user journey in the PRD:
+
+1. **Map the journey** to concrete screens (1 journey = 1+ screens)
+2. **Name each screen** with a slug: \`{area}-{action}\` (e.g., \`auth-login\`, \`dashboard-overview\`, \`settings-profile\`)
+3. **Classify screen type**: form, list, detail, dashboard, wizard, modal, empty-state, error
+4. **Map FR coverage**: which FRs are satisfied by which screen
+
+Output: screen inventory table.
+
+## Phase 2: Screen Flows
+
+For each major workflow:
+
+1. **Draw flow diagram** in text format:
+\`\`\`
+[Landing] → [Login] → [Dashboard]
+                ↓              ↓
+           [Register]    [Settings]
+                ↓
+           [Verify Email] → [Dashboard]
+\`\`\`
+
+2. **Document transitions**: what triggers navigation (button click, form submit, auto-redirect)
+3. **Identify shared patterns**: navigation, auth guards, error states, loading states
+
+## Phase 3: Wireframes (ASCII)
+
+For each screen, produce an ASCII wireframe:
+
+\`\`\`
+┌─────────────────────────────────┐
+│ [Logo]          [Nav] [Avatar]  │
+├─────────────────────────────────┤
+│                                 │
+│  ┌──────────┐ ┌──────────────┐  │
+│  │ Sidebar  │ │   Content    │  │
+│  │          │ │              │  │
+│  │ • Item 1 │ │  ┌────────┐  │  │
+│  │ • Item 2 │ │  │ Card 1 │  │  │
+│  │ • Item 3 │ │  └────────┘  │  │
+│  │          │ │  ┌────────┐  │  │
+│  │          │ │  │ Card 2 │  │  │
+│  └──────────┘ │  └────────┘  │  │
+│               └──────────────┘  │
+├─────────────────────────────────┤
+│ [Footer]                        │
+└─────────────────────────────────┘
+\`\`\`
+
+Rules:
+- Use box drawing characters (┌ ─ ┐ │ └ ┘ ├ ┤)
+- Label every zone with its purpose
+- Show content hierarchy (headings, lists, cards, forms)
+- Annotate interactive elements: \`[Button]\`, \`(Input)\`, \`{Dropdown}\`
+- Include responsive notes: "sidebar collapses to hamburger on mobile"
+
+## Phase 4: Component Inventory
+
+Analyze all wireframes and extract:
+
+### Component Tree
+\`\`\`
+App
+├── Layout
+│   ├── Header (logo, nav, avatar)
+│   ├── Sidebar (nav items, collapsible)
+│   └── Footer
+├── Shared
+│   ├── Button (primary, secondary, ghost, danger)
+│   ├── Input (text, email, password, search)
+│   ├── Card (title, body, actions)
+│   ├── Modal (header, body, footer)
+│   └── Toast (success, error, warning, info)
+└── Feature-specific
+    ├── UserAvatar (image, initials fallback)
+    ├── DataTable (sortable, filterable, paginated)
+    └── StatsCard (value, label, trend)
+\`\`\`
+
+### Component Spec (for each)
+- **Props**: name, type, required, default
+- **States**: default, hover, active, disabled, loading, error
+- **Variants**: size (sm/md/lg), color (primary/secondary/danger)
+- **Accessibility**: ARIA role, keyboard navigation, focus management
+
+## Phase 5: Interaction Specs
+
+For each screen, document:
+
+1. **Loading states**: skeleton, spinner, progressive
+2. **Empty states**: first-use, no-results, error
+3. **Error handling**: inline validation, toast, error page
+4. **Animations**: page transitions, micro-interactions (optional)
+5. **Responsive behavior**: breakpoints, layout changes, touch targets
+
+## Validation
+
+Check completeness:
+- [ ] Every FR from PRD maps to at least one screen
+- [ ] Every screen has a wireframe
+- [ ] Every interactive element has states defined
+- [ ] Flows cover happy path + error paths
+- [ ] Component inventory covers all wireframe elements
+- [ ] No orphan screens (unreachable from any flow)
+
+## Output
+
+\`\`\`bash
+mkdir -p ${o}/ux
+\`\`\`
+
+Write to \`${o}/ux/\`:
+1. \`screen-inventory.md\` — table of all screens with FR mapping
+2. \`flows.md\` — all screen flow diagrams
+3. \`wireframes.md\` — ASCII wireframes for every screen
+4. \`components.md\` — component tree + specs
+5. \`interactions.md\` — states, errors, responsive, animations
+
+## State Update
+
+Update \`${o}/state.yaml\`:
+\`\`\`yaml
+pipeline:
+  current_phase: "ux"
+  phases:
+    ux:
+      status: "done"
+      output: "${o}/ux/"
+\`\`\`
+
+## Chain
+
+Invoke Skill tool with \`skill: "aped-e"\` to proceed to Epics phase.
+\`/aped-e\` will read UX specs to enrich stories with wireframe refs, component specs, and interaction requirements in Dev Notes.
+`,
+    },
+    // ── aped-s ──────────────────────────────────────────────
+    {
+      path: `${a}/aped-s/SKILL.md`,
+      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
+---
+
+# APED Status — Sprint Dashboard
+
+## Setup
+
+1. Read \`${a}/config.yaml\` — extract \`communication_language\`, \`ticket_system\`
+2. Read \`${o}/state.yaml\` — load full pipeline and sprint state
+
+## Pipeline Overview
+
+Display current pipeline phase and completion status:
+
+\`\`\`
+Pipeline: A[✓] → P[✓] → E[✓] → D[▶] → R[ ]
+\`\`\`
+
+For each completed phase, show the output artifact path.
+
+## Sprint Progress
+
+For each epic in \`sprint.stories\`:
+
+1. Count stories by status: \`done\`, \`in-progress\`, \`review\`, \`ready-for-dev\`, \`backlog\`
+2. Calculate completion percentage
+3. Display as progress bar:
+
+\`\`\`
+Epic 1: User Authentication     [████████░░] 80% (4/5 stories)
+  ✓ 1-1-project-setup           done
+  ✓ 1-2-user-registration       done
+  ✓ 1-3-login-flow              done
+  ✓ 1-4-password-reset          done
+  ▶ 1-5-session-management      in-progress
+\`\`\`
+
+## Blockers Detection
+
+Scan for:
+- Stories with \`[AI-Review]\` items → **Review blockers**
+- Stories \`in-progress\` for more than 1 session → **Stuck stories**
+- Missing dependencies between stories → **Dependency blockers**
+- HALT conditions logged in Dev Agent Record → **Dev halts**
+
+## Next Actions
+
+Based on current state, suggest the next logical command:
+- If stories \`ready-for-dev\`: suggest \`/aped-d\`
+- If stories in \`review\`: suggest \`/aped-r\`
+- If all stories \`done\`: suggest pipeline complete
+- If blockers found: describe resolution path
+
+## Ticket System Integration
+
+If \`ticket_system\` is not \`none\`:
+- Show ticket references alongside story statuses
+- Note any stories without ticket references
+
+## Output
+
+Display only — no file writes, no state changes. Pure read-only dashboard.
+`,
+    },
+    // ── aped-c ──────────────────────────────────────────────
+    {
+      path: `${a}/aped-c/SKILL.md`,
+      content: `---
+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
+---
+
+# APED Correct Course — Managed Pivot
+
+Use when requirements change, priorities shift, or the current approach needs rethinking mid-pipeline.
+
+## Setup
+
+1. Read \`${a}/config.yaml\` — extract config
+2. Read \`${o}/state.yaml\` — understand current pipeline state
+3. Read existing artifacts: brief, PRD, epics, stories
+
+## Impact Assessment
+
+Ask the user:
+1. **What changed?** — New requirement, removed feature, architectural pivot, priority shift
+2. **Why?** — User feedback, market shift, technical limitation, stakeholder decision
+
+Then analyze impact:
+
+### Scope Change Matrix
+
+| What changed | Artifacts affected | Action required |
+|---|---|---|
+| New feature added | PRD, Epics | Add FRs → create new stories |
+| Feature removed | PRD, Epics | Remove FRs → archive stories |
+| Architecture change | PRD NFRs, All stories | Update NFRs → review all Dev Notes |
+| Priority reorder | Epics, Sprint | Reorder stories → update sprint |
+| Complete pivot | Everything | Reset to /aped-a |
+
+## Change Execution
+
+### Minor change (new/removed feature)
+1. Update PRD: add/remove FRs, update scope
+2. Re-run validation: \`bash ${a}/aped-p/scripts/validate-prd.sh ${o}/prd.md\`
+3. Update epics: add/archive affected stories
+4. Re-run coverage: \`bash ${a}/aped-e/scripts/validate-coverage.sh ${o}/epics.md ${o}/prd.md\`
+5. Update \`${o}/state.yaml\`: mark affected stories as \`backlog\`
+
+### Major change (architecture/pivot)
+1. Confirm with user: "This invalidates in-progress work. Proceed?"
+2. Archive current artifacts to \`${o}/archive/{date}/\`
+3. Update PRD or restart from \`/aped-a\`
+4. Regenerate affected downstream artifacts
+
+## Story Impact Report
+
+For each in-progress or completed story:
+- **Safe**: story not affected by change
+- **Needs update**: story Dev Notes or ACs need modification
+- **Invalidated**: story no longer relevant — archive it
+
+## State Update
+
+Update \`${o}/state.yaml\`:
+- Reset affected stories to \`backlog\` or \`ready-for-dev\`
+- If major change: reset \`current_phase\` to appropriate earlier phase
+- Log the correction in pipeline phases:
+\`\`\`yaml
+corrections:
+  - date: "{date}"
+    type: "{minor|major}"
+    reason: "{user's reason}"
+    affected_stories: [...]
+\`\`\`
+
+## Guard Against Scope Creep
+
+After applying changes, verify:
+- Total FR count still within 10-80 range
+- No epic became too large (>8 stories)
+- No story became too large (>8 tasks)
+- Changed stories still fit single-session size
+`,
+    },
+    // ── aped-ctx ────────────────────────────────────────────
+    {
+      path: `${a}/aped-ctx/SKILL.md`,
+      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
+---
+
+# APED Context — Brownfield Project Analysis
+
+Use on existing codebases to generate project context before running the APED pipeline. Essential for brownfield projects where you're adding features to existing code.
+
+## Setup
+
+1. Read \`${a}/config.yaml\` — extract config
+2. Verify this is a brownfield project (existing code, not greenfield)
+
+## Codebase Analysis
+
+### Phase 1: Structure Discovery
+
+Scan the project root:
+- Detect language/framework from config files (package.json, Cargo.toml, go.mod, pyproject.toml, etc.)
+- Map directory structure (max 3 levels deep)
+- Identify entry points, main modules, config files
+- Count: files, LOC, languages used
+
+### Phase 2: Architecture Mapping
+
+- Identify architectural pattern (MVC, hexagonal, microservices, monolith, etc.)
+- Map data flow: entry point → processing → storage → response
+- List external dependencies and integrations (APIs, databases, queues, caches)
+- Identify test framework and coverage approach
+
+### Phase 3: Convention Extraction
+
+- Naming conventions (files, functions, variables, classes)
+- Code organization patterns (feature-based, layer-based, domain-based)
+- Error handling patterns
+- Logging approach
+- Config management (env vars, config files, secrets)
+
+### Phase 4: Dependency Audit
+
+- List production dependencies with versions
+- Flag outdated or deprecated packages
+- Identify security advisories (if available)
+- Note lock file type (package-lock, yarn.lock, pnpm-lock, etc.)
+
+## Output
+
+Write project context to \`${o}/project-context.md\`:
+
+\`\`\`markdown
+# Project Context: {project_name}
+
+## Tech Stack
+- Language: {lang} {version}
+- Framework: {framework} {version}
+- Database: {db}
+- Test Framework: {test_framework}
+
+## Architecture
+- Pattern: {pattern}
+- Entry Point: {entry}
+- Key Modules: {modules}
+
+## Conventions
+- File naming: {convention}
+- Code style: {style}
+- Error handling: {pattern}
+
+## Dependencies
+| Package | Version | Purpose |
+|---------|---------|---------|
+
+## Integration Points
+- {service}: {purpose}
+
+## Notes for Development
+- {important context for new feature development}
+\`\`\`
+
+## State Update
+
+Update \`${o}/state.yaml\`:
+\`\`\`yaml
+project_context:
+  generated: true
+  path: "${o}/project-context.md"
+  type: "brownfield"
+\`\`\`
+
+## Next Steps
+
+Suggest:
+- If no brief exists: run \`/aped-a\` with project context loaded
+- If brief exists: context will inform \`/aped-p\` and \`/aped-d\` decisions
+`,
+    },
+    // ── aped-qa ─────────────────────────────────────────────
+    {
+      path: `${a}/aped-qa/SKILL.md`,
+      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.'
+---
+
+# APED QA — E2E & Integration Test Generation
+
+Generate comprehensive end-to-end and integration tests for completed stories or epics. Complements the unit tests written during /aped-d TDD.
+
+## Setup
+
+1. Read \`${a}/config.yaml\` — extract config
+2. Read \`${o}/state.yaml\` — find completed stories/epics
+
+## Scope Selection
+
+Ask the user:
+1. **What to test?** — specific story, full epic, or all completed work
+2. **Test type?** — E2E (user journeys), Integration (API/service), or Both
+
+## Story/Epic Analysis
+
+For the selected scope:
+1. Read story files from \`${o}/stories/\`
+2. Extract all Acceptance Criteria (Given/When/Then)
+3. Map user journeys across stories (multi-step flows)
+4. Identify integration points (APIs, databases, external services)
+
+## Task Tracking
+
+\`\`\`
+TaskCreate: "Analyze stories and extract ACs"
+TaskCreate: "Generate E2E tests"
+TaskCreate: "Generate integration tests"
+TaskCreate: "Run and verify all tests"
+TaskCreate: "Write QA report"
+\`\`\`
+
+## Test Generation
+
+Launch **2 Agent tool calls in parallel**:
+
+### Agent 1: E2E Tests (\`subagent_type: "general-purpose"\`)
+
+For each user journey that spans one or more stories:
+
+1. Map the full flow: entry → steps → expected outcome
+2. Generate test using the project's test framework
+3. Each AC's Given/When/Then becomes a test step
+4. Include:
+   - Happy path (main flow)
+   - Error paths (invalid input, unauthorized, not found)
+   - Edge cases (empty data, concurrent access, timeouts)
+
+### Agent 2: Integration Tests (\`subagent_type: "general-purpose"\`)
+
+For each integration point:
+
+1. Test request/response contracts
+2. Test error handling (service down, timeout, malformed response)
+3. Test data consistency (DB state before/after)
+4. Test authentication/authorization boundaries
+
+Once both agents return, update tasks to \`completed\`.
+
+### Test Naming Convention
+
+\`\`\`
+{test-type}/{epic-slug}/{story-slug}.test.{ext}
+\`\`\`
+
+## Framework Detection
+
+Read project config to auto-detect:
+- **Node.js**: Playwright, Cypress, or Puppeteer for E2E; Supertest for API
+- **Python**: Pytest + httpx for API; Playwright for E2E
+- **Go**: Go test + httptest for API
+- **Rust**: reqwest for API tests
+
+Use \`bash ${a}/aped-d/scripts/run-tests.sh\` to verify tests pass.
+
+## Test Coverage Report
+
+After generation:
+- List ACs covered vs uncovered
+- List user journeys tested
+- List integration points tested
+- Flag any untestable ACs (and why)
+
+## Output
+
+1. Write tests to project test directory (detect convention)
+2. Write QA report to \`${o}/qa-report.md\`:
+   - Stories tested
+   - Tests generated (count by type)
+   - Coverage gaps
+   - Manual test suggestions (for things that can't be automated)
+
+## No State Change
+
+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.
 `,
     },
     // ── aped-quick ────────────────────────────────────────────
@@ -391,7 +1009,7 @@ Update \`${o}/state.yaml\`. If more stories — chain to \`/aped-d\`. If all don
       path: `${a}/aped-quick/SKILL.md`,
       content: `---
 name: aped-quick
-description: 'Quick feature/fix implementation bypassing full pipeline. Use when user says "quick fix", "quick feature", "aped quick", or invokes /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.'
 ---
 
 # APED Quick — Fast Track for Small Changes
@@ -462,7 +1080,8 @@ Read \`ticket_system\` and \`git_provider\` from config.
       path: `${a}/aped-all/SKILL.md`,
       content: `---
 name: aped-all
-description: 'Run full APED pipeline from Analyze through Review. Use when user says "run full pipeline", "aped all", "start from scratch", or invokes /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
 ---
 
 # APED Pipeline — Full Orchestrator
@@ -477,13 +1096,28 @@ description: 'Run full APED pipeline from Analyze through Review. Use when user
 | No state / \`current_phase: "none"\` | Start from \`/aped-a\` |
 | Any phase \`in-progress\` | Re-invoke that phase (ask user: resume or restart?) |
 | analyze \`done\`, prd missing | Invoke \`/aped-p\` |
-| prd \`done\`, epics missing | Invoke \`/aped-e\` |
+| prd \`done\`, ux missing | Invoke \`/aped-ux\` (optional — ask user: design UX or skip to epics?) |
+| ux \`done\` or skipped, epics missing | Invoke \`/aped-e\` |
 | epics \`done\` | Loop: \`/aped-d\` — \`/aped-r\` until all stories \`done\` |
 | All stories \`done\` | Report pipeline complete |
 
+## Task Tracking
+
+Create a task per pipeline phase:
+\`\`\`
+TaskCreate: "Phase A — Analyze"
+TaskCreate: "Phase P — PRD"
+TaskCreate: "Phase UX — UX Design (optional)"
+TaskCreate: "Phase E — Epics"
+TaskCreate: "Phase D — Dev Sprint"
+TaskCreate: "Phase R — Review"
+\`\`\`
+
+Update each to \`in_progress\` when invoking, \`completed\` when phase returns done.
+
 ## Execution
 
-Use the Skill tool to invoke each phase: aped-a, aped-p, aped-e, aped-d, aped-r.
+Use the Skill tool to invoke each phase: aped-a, aped-p, aped-ux (optional), aped-e, aped-d, aped-r.
 Each phase updates \`${o}/state.yaml\` and chains automatically.
 
 ## Interruption Handling