aped-method 1.8.0 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aped-method",
-  "version": "1.8.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,
+    },
   ];
 }
 
@@ -799,3 +815,299 @@ Rules ranked by impact. Apply in order — never skip a higher-priority rule for
 - [ ] 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

@@ -860,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\`:
@@ -913,6 +921,7 @@ metadata:
 
 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
 
@@ -1004,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
 
@@ -1105,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
 
@@ -1223,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