aped-method 1.0.0

package/bin/aped-method.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

@@ -0,0 +1,31 @@
+{
+  "name": "aped-method",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Scaffold the APED pipeline (Analyze, PRD, Epics, Dev, Review) into any Claude Code project",
+  "bin": {
+    "aped-method": "./bin/aped-method.js"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "keywords": [
+    "claude-code",
+    "skills",
+    "pipeline",
+    "tdd",
+    "code-review",
+    "product-development",
+    "aped"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yabafre/aped-claude.git"
+  },
+  "author": "yabafre",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/index.js

@@ -0,0 +1,348 @@
+import { createInterface } from 'node:readline';
+import { stdin, stdout } from 'node:process';
+import { scaffold } from './scaffold.js';
+
+const DEFAULTS = {
+  apedDir: '.aped',
+  outputDir: 'docs/aped',
+  commandsDir: '.claude/commands',
+  authorName: '',
+  projectName: '',
+  communicationLang: 'english',
+  documentLang: 'english',
+};
+
+// ── ANSI helpers ──
+const ESC = '\x1b';
+const a = {
+  reset:     `${ESC}[0m`,
+  bold:      `${ESC}[1m`,
+  dim:       `${ESC}[2m`,
+  italic:    `${ESC}[3m`,
+  underline: `${ESC}[4m`,
+  red:       `${ESC}[31m`,
+  green:     `${ESC}[32m`,
+  yellow:    `${ESC}[33m`,
+  blue:      `${ESC}[34m`,
+  magenta:   `${ESC}[35m`,
+  cyan:      `${ESC}[36m`,
+  white:     `${ESC}[37m`,
+  // 256-color greens for richer palette
+  lime:      `${ESC}[38;5;118m`,  // bright lime
+  emerald:   `${ESC}[38;5;42m`,   // emerald
+  mint:      `${ESC}[38;5;48m`,   // mint
+  forest:    `${ESC}[38;5;34m`,   // forest
+  spring:    `${ESC}[38;5;82m`,   // spring green
+};
+
+const bold    = (s) => `${a.bold}${s}${a.reset}`;
+const dim     = (s) => `${a.dim}${s}${a.reset}`;
+const green   = (s) => `${a.green}${s}${a.reset}`;
+const lime    = (s) => `${a.lime}${s}${a.reset}`;
+const emerald = (s) => `${a.emerald}${s}${a.reset}`;
+const mint    = (s) => `${a.mint}${s}${a.reset}`;
+const yellow  = (s) => `${a.yellow}${s}${a.reset}`;
+const magenta = (s) => `${a.magenta}${s}${a.reset}`;
+const red     = (s) => `${a.red}${s}${a.reset}`;
+const cyan    = (s) => `${a.cyan}${s}${a.reset}`;
+
+// ── ASCII Art Logo ──
+const LOGO = `
+${a.emerald}${a.bold}     █████╗ ██████╗ ███████╗██████╗
+    ██╔══██╗██╔══██╗██╔════╝██╔══██╗
+    ███████║██████╔╝█████╗  ██║  ██║
+    ██╔══██║██╔═══╝ ██╔══╝  ██║  ██║
+    ██║  ██║██║     ███████╗██████╔╝
+    ╚═╝  ╚═╝╚═╝     ╚══════╝╚═════╝${a.reset}
+${a.dim}    ─────────────────────────────────${a.reset}
+${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}`;
+
+// ── Spinner ──
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+
+function createSpinner(text) {
+  let i = 0;
+  let interval;
+  return {
+    start() {
+      process.stdout.write('\x1b[?25l'); // hide cursor
+      interval = setInterval(() => {
+        const frame = SPINNER_FRAMES[i % SPINNER_FRAMES.length];
+        process.stdout.write(`\r  ${a.emerald}${frame}${a.reset} ${text}`);
+        i++;
+      }, 80);
+    },
+    stop(finalText) {
+      clearInterval(interval);
+      process.stdout.write(`\r  ${a.lime}${a.bold}✓${a.reset} ${finalText}\x1b[K\n`);
+      process.stdout.write('\x1b[?25h'); // show cursor
+    },
+    fail(finalText) {
+      clearInterval(interval);
+      process.stdout.write(`\r  ${a.red}${a.bold}✗${a.reset} ${finalText}\x1b[K\n`);
+      process.stdout.write('\x1b[?25h');
+    },
+  };
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// ── Section display ──
+function sectionHeader(title) {
+  console.log('');
+  console.log(`  ${a.emerald}${a.bold}┌─${a.reset} ${a.bold}${title}${a.reset}`);
+  console.log(`  ${a.emerald}│${a.reset}`);
+}
+
+function sectionEnd() {
+  console.log(`  ${a.emerald}${a.bold}└──────────────────────────────────${a.reset}`);
+}
+
+// ── Args ──
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 2; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--yes' || arg === '-y') { args.yes = true; continue; }
+    const match = arg.match(/^--(\w[\w-]*)=(.+)$/);
+    if (match) {
+      const key = match[1].replace(/-([a-z])/g, (_, ch) => ch.toUpperCase());
+      args[key] = match[2];
+    }
+  }
+  return args;
+}
+
+function ask(rl, question, defaultVal) {
+  return new Promise((resolve) => {
+    const suffix = defaultVal ? ` ${dim(`(${defaultVal})`)}` : '';
+    rl.question(`  ${a.emerald}│${a.reset}  ${question}${suffix}: `, (answer) => {
+      resolve(answer.trim() || defaultVal || '');
+    });
+  });
+}
+
+async function readStdinLines() {
+  if (stdin.isTTY) return null;
+  return new Promise((resolve) => {
+    let data = '';
+    stdin.setEncoding('utf-8');
+    stdin.on('data', (chunk) => { data += chunk; });
+    stdin.on('end', () => resolve(data.split('\n')));
+    setTimeout(() => resolve(null), 100);
+  });
+}
+
+// ── Main ──
+export async function run() {
+  const args = parseArgs(process.argv);
+  const stdinLines = await readStdinLines();
+  let lineIndex = 0;
+
+  let detectedProject = '';
+  try {
+    const { readFileSync } = await import('node:fs');
+    const pkg = JSON.parse(readFileSync('package.json', 'utf-8'));
+    detectedProject = pkg.name || '';
+  } catch {
+    detectedProject = process.cwd().split('/').pop();
+  }
+
+  // ── Banner ──
+  console.log(LOGO);
+  console.log(PIPELINE);
+  console.log('');
+
+  if (args.yes) {
+    const config = {
+      projectName: args.project || args.projectName || detectedProject || 'my-project',
+      authorName: args.author || args.authorName || '',
+      communicationLang: args.lang || args.communicationLang || DEFAULTS.communicationLang,
+      documentLang: args.docLang || args.documentLang || DEFAULTS.documentLang,
+      apedDir: args.aped || args.apedDir || DEFAULTS.apedDir,
+      outputDir: args.output || args.outputDir || DEFAULTS.outputDir,
+      commandsDir: args.commands || args.commandsDir || DEFAULTS.commandsDir,
+    };
+
+    await runScaffold(config);
+    return;
+  }
+
+  const rl = createInterface({ input: stdin, output: stdout });
+
+  const prompt = stdinLines
+    ? (question, def) => {
+        const val = (stdinLines[lineIndex++] || '').trim();
+        const result = val || def || '';
+        console.log(`  ${a.emerald}│${a.reset}  ${question}: ${result}`);
+        return Promise.resolve(result);
+      }
+    : (question, def) => ask(rl, question, def);
+
+  try {
+    sectionHeader('Configuration');
+
+    const config = {};
+    config.projectName = await prompt(`${bold('Project name')}`, detectedProject);
+    config.authorName = await prompt(`${bold('Author')}`, DEFAULTS.authorName);
+    config.communicationLang = await prompt(`${bold('Communication language')}`, DEFAULTS.communicationLang);
+    config.documentLang = await prompt(`${bold('Document language')}`, DEFAULTS.documentLang);
+    config.apedDir = await prompt(`${bold('APED dir')} ${dim('(engine)')}`, DEFAULTS.apedDir);
+    config.outputDir = await prompt(`${bold('Output dir')} ${dim('(artifacts)')}`, DEFAULTS.outputDir);
+    config.commandsDir = await prompt(`${bold('Commands dir')}`, DEFAULTS.commandsDir);
+
+    sectionEnd();
+    console.log('');
+    printConfig(config);
+    console.log('');
+
+    const confirm = await prompt(`${bold('Proceed?')}`, 'Y');
+    if (confirm.toLowerCase() === 'n') {
+      console.log(`\n  ${yellow('Cancelled.')}\n`);
+      return;
+    }
+
+    await runScaffold(config);
+  } finally {
+    rl.close();
+  }
+}
+
+async function runScaffold(config) {
+  // ── Phase 1: Validating config ──
+  const s1 = createSpinner('Validating configuration...');
+  s1.start();
+  await sleep(400);
+  s1.stop('Configuration validated');
+
+  // ── Phase 2: Creating directory structure ──
+  const s2 = createSpinner('Creating directory structure...');
+  s2.start();
+  await sleep(300);
+  s2.stop('Directory structure ready');
+
+  // ── Phase 3: Scaffolding ──
+  sectionHeader('Scaffolding Pipeline');
+  console.log(`  ${a.emerald}│${a.reset}`);
+
+  const count = await scaffoldWithCheckpoints(config);
+
+  sectionEnd();
+
+  // ── Phase 4: Setting up hooks ──
+  const s3 = createSpinner('Installing guardrail hook...');
+  s3.start();
+  await sleep(350);
+  s3.stop('Guardrail hook installed');
+
+  // ── Phase 5: Final verification ──
+  const s4 = createSpinner('Verifying installation...');
+  s4.start();
+  await sleep(300);
+  s4.stop(`Installation verified — ${bold(String(count))} files`);
+
+  // ── Done ──
+  printDone(count);
+}
+
+async function scaffoldWithCheckpoints(config) {
+  const { getTemplates } = await import('./templates/index.js');
+  const { mkdirSync, writeFileSync, chmodSync, existsSync } = await import('node:fs');
+  const { join, dirname } = await import('node:path');
+
+  const cwd = process.cwd();
+  const templates = getTemplates(config);
+
+  const groups = {
+    config:     { label: 'Config & State',    icon: '⚙', items: [] },
+    templates:  { label: 'Templates',         icon: '📄', items: [] },
+    commands:   { label: 'Slash Commands',     icon: '⚡', items: [] },
+    skills:     { label: 'Skills (SKILL.md)',  icon: '🧠', items: [] },
+    scripts:    { label: 'Validation Scripts', icon: '🔧', items: [] },
+    references: { label: 'Reference Docs',    icon: '📚', items: [] },
+    hooks:      { label: 'Hooks & Settings',  icon: '🛡', items: [] },
+  };
+
+  for (const tpl of templates) {
+    const p = tpl.path;
+    if (p.includes('/hooks/') || p.includes('settings'))     groups.hooks.items.push(tpl);
+    else if (p.includes('/scripts/'))                        groups.scripts.items.push(tpl);
+    else if (p.includes('/references/'))                     groups.references.items.push(tpl);
+    else if (p.includes('SKILL.md'))                         groups.skills.items.push(tpl);
+    else if (p.includes('/commands/'))                       groups.commands.items.push(tpl);
+    else if (p.includes('/templates/'))                      groups.templates.items.push(tpl);
+    else                                                     groups.config.items.push(tpl);
+  }
+
+  let count = 0;
+
+  for (const [, group] of Object.entries(groups)) {
+    if (group.items.length === 0) continue;
+
+    const sp = createSpinner(`${group.label}...`);
+    sp.start();
+    await sleep(200);
+
+    let groupCount = 0;
+    for (const tpl of group.items) {
+      const fullPath = join(cwd, tpl.path);
+      mkdirSync(dirname(fullPath), { recursive: true });
+      if (!existsSync(fullPath)) {
+        writeFileSync(fullPath, tpl.content, 'utf-8');
+        if (tpl.executable) chmodSync(fullPath, 0o755);
+        groupCount++;
+        count++;
+      }
+    }
+
+    sp.stop(`${group.icon}  ${group.label}  ${dim(`(${groupCount} files)`)}`);
+  }
+
+  return count;
+}
+
+function printConfig(config) {
+  const box = (label, value, extra) => {
+    const e = extra ? `  ${dim(extra)}` : '';
+    console.log(`  ${a.emerald}│${a.reset}  ${dim(label.padEnd(16))}${bold(value)}${e}`);
+  };
+
+  console.log(`  ${a.emerald}${a.bold}┌─${a.reset} ${bold('Summary')}`);
+  console.log(`  ${a.emerald}│${a.reset}`);
+  box('Project',       config.projectName);
+  box('Author',        config.authorName || dim('(not set)'));
+  box('Communication', config.communicationLang);
+  box('Documents',     config.documentLang);
+  box('APED',          config.apedDir + '/',    'engine');
+  box('Output',        config.outputDir + '/',  'artifacts');
+  box('Commands',      config.commandsDir + '/');
+  console.log(`  ${a.emerald}│${a.reset}`);
+  console.log(`  ${a.emerald}${a.bold}└──────────────────────────────────${a.reset}`);
+}
+
+function printDone(count) {
+  console.log('');
+  console.log(`  ${a.emerald}${a.bold}╔══════════════════════════════════════╗${a.reset}`);
+  console.log(`  ${a.emerald}${a.bold}║${a.reset}  ${a.lime}${a.bold}✓${a.reset} ${bold(`${count} files scaffolded`)}              ${a.emerald}${a.bold}║${a.reset}`);
+  console.log(`  ${a.emerald}${a.bold}║${a.reset}  ${dim('Pipeline ready to use')}               ${a.emerald}${a.bold}║${a.reset}`);
+  console.log(`  ${a.emerald}${a.bold}╚══════════════════════════════════════╝${a.reset}`);
+  console.log('');
+
+  console.log(`  ${a.bold}Available 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.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')}`);
+  console.log('');
+}

package/src/scaffold.js

@@ -0,0 +1,21 @@
+import { mkdirSync, writeFileSync, chmodSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { getTemplates } from './templates/index.js';
+
+export async function scaffold(config) {
+  const cwd = process.cwd();
+  const templates = getTemplates(config);
+  let count = 0;
+
+  for (const tpl of templates) {
+    const fullPath = join(cwd, tpl.path);
+    mkdirSync(dirname(fullPath), { recursive: true });
+    if (!existsSync(fullPath)) {
+      writeFileSync(fullPath, tpl.content, 'utf-8');
+      if (tpl.executable) chmodSync(fullPath, 0o755);
+      count++;
+    }
+  }
+
+  return count;
+}

package/src/templates/commands.js

@@ -0,0 +1,65 @@
+export function commands(c) {
+  const a = c.apedDir;
+  return [
+    {
+      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"'
+---
+
+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"'
+---
+
+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"'
+---
+
+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"'
+---
+
+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"'
+---
+
+Read and follow the SKILL.md at $PROJECT_ROOT/${a}/aped-r/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"'
+---
+
+Read and follow the SKILL.md at $PROJECT_ROOT/${a}/aped-all/SKILL.md
+`,
+    },
+  ];
+}

package/src/templates/config.js

@@ -0,0 +1,230 @@
+export function configFiles(c) {
+  const a = c.apedDir;
+  const o = c.outputDir;
+  return [
+    {
+      path: `${a}/config.yaml`,
+      content: `# APED Project Configuration
+project_name: ${c.projectName}
+user_name: ${c.authorName}
+communication_language: ${c.communicationLang}
+document_output_language: ${c.documentLang}
+aped_path: ${a}
+output_path: ${o}
+`,
+    },
+    {
+      path: `${a}/state.yaml`,
+      content: `# APED Pipeline State
+pipeline:
+  current_phase: "none"
+  phases: {}
+
+# Sprint state (generated by aped-e, consumed by aped-d and aped-r)
+sprint:
+  project: ""
+  stories: {}
+`,
+    },
+    {
+      path: `${a}/templates/product-brief.md`,
+      content: `# Product Brief: {{project_name}}
+
+## Executive Summary
+
+<!-- 2-3 sentences: what we're building and why it matters -->
+
+## Core Vision
+
+### Problem Statement
+
+<!-- What specific problem exists today? -->
+
+### Problem Impact
+
+<!-- Who is affected and how? Quantify where possible. -->
+
+### Proposed Solution
+
+<!-- High-level description of the solution approach -->
+
+### Key Differentiators
+
+<!-- What makes this different from existing solutions? -->
+
+## Target Users
+
+### Primary Users
+
+<!-- Who are the main users? Demographics, behaviors, technical level -->
+
+### Secondary Users
+
+<!-- Other stakeholders who interact with the product -->
+
+### User Journey
+
+<!-- Key touchpoints from discovery to daily usage -->
+
+## Success Metrics
+
+### Business Objectives
+
+<!-- What business outcomes define success? -->
+
+### KPIs
+
+<!-- Measurable indicators with targets and timeframes -->
+
+## MVP Scope
+
+### Core Features
+
+<!-- Minimum feature set for first viable release -->
+
+### Out of Scope
+
+<!-- Explicitly excluded from MVP -->
+
+### Success Criteria
+
+<!-- How we know MVP succeeded -->
+
+### Future Vision
+
+<!-- Post-MVP direction and growth areas -->
+`,
+    },
+    {
+      path: `${a}/templates/prd.md`,
+      content: `# Product Requirements Document — {{project_name}}
+
+**Author:** {{user_name}}
+**Date:** {{date}}
+
+## Executive Summary
+
+## Success Criteria
+
+### User Outcomes
+
+### Business Outcomes
+
+### Technical Outcomes
+
+### Measurable Outcomes
+
+## Product Scope
+
+### MVP (Phase 1)
+
+### Growth (Phase 2)
+
+### Vision (Phase 3)
+
+## User Journeys
+
+## Domain Requirements
+
+<!-- Conditional: only if domain-complexity.csv flags high/medium complexity -->
+
+## Functional Requirements
+
+<!-- Format: FR#: [Actor] can [capability] [context/constraint] -->
+<!-- Target: 10-80 FRs -->
+
+## Non-Functional Requirements
+
+### Performance
+
+### Security
+
+### Scalability
+
+### Accessibility
+
+### Integration
+`,
+    },
+    {
+      path: `${a}/templates/epics.md`,
+      content: `# Epics & Stories — {{project_name}}
+
+**Generated:** {{date}}
+**Source PRD:** {{prd_path}}
+
+## Requirements Inventory
+
+### Functional Requirements
+
+### Non-Functional Requirements
+
+### Additional Requirements
+
+## FR Coverage Map
+
+<!-- Every FR mapped to exactly one epic. Format: FR# -> Epic N -->
+
+## Epics
+
+### Epic 1: {{epic_title}}
+
+**Goal:** {{user-value-focused goal}}
+
+#### Story 1.1: {{story_title}}
+
+**As a** {{role}}, **I want** {{capability}}, **so that** {{benefit}}.
+
+**Acceptance Criteria:**
+- **Given** {{context}}, **When** {{action}}, **Then** {{outcome}}
+
+**Tasks:**
+- [ ] {{task description}} [AC: {{ac_ref}}]
+
+**Dev Notes:**
+- Architecture: {{relevant patterns}}
+- Files: {{files to create/modify}}
+- Testing: {{test approach}}
+`,
+    },
+    {
+      path: `${a}/templates/story.md`,
+      content: `# Story: {{story_key}} — {{story_title}}
+
+**Epic:** {{epic_title}}
+**Status:** {{status}}
+
+## User Story
+
+**As a** {{role}}, **I want** {{capability}}, **so that** {{benefit}}.
+
+## Acceptance Criteria
+
+- **Given** {{context}}, **When** {{action}}, **Then** {{outcome}}
+
+## Tasks
+
+- [ ] {{task description}} [AC: {{ac_ref}}]
+
+## Dev Notes
+
+- **Architecture:** {{relevant architecture decisions and patterns}}
+- **Files:** {{files to create or modify}}
+- **Testing:** {{test approach and framework}}
+- **Dependencies:** {{external libs, APIs, services}}
+
+## Dev Agent Record
+
+- **Model:** {{model used}}
+- **Started:** {{timestamp}}
+- **Completed:** {{timestamp}}
+
+### Debug Log
+
+### Completion Notes
+
+### File List
+`,
+    },
+  ];
+}