aped-method 1.0.0 → 1.3.0

package/package.json

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

package/src/index.js

@@ -1,7 +1,14 @@
 import { createInterface } from 'node:readline';
+import { existsSync, readFileSync, writeFileSync as writeFS } from 'node:fs';
 import { stdin, stdout } from 'node:process';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { scaffold } from './scaffold.js';
 
+// ── CLI version (read from package.json) ──
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CLI_VERSION = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8')).version;
+
 const DEFAULTS = {
   apedDir: '.aped',
   outputDir: 'docs/aped',
@@ -10,8 +17,13 @@ const DEFAULTS = {
   projectName: '',
   communicationLang: 'english',
   documentLang: 'english',
+  ticketSystem: 'none',
+  gitProvider: 'github',
 };
 
+const TICKET_OPTIONS = ['none', 'jira', 'linear', 'github-issues', 'gitlab-issues'];
+const GIT_OPTIONS = ['github', 'gitlab', 'bitbucket'];
+
 // ── ANSI helpers ──
 const ESC = '\x1b';
 const a = {
@@ -27,24 +39,16 @@ const a = {
   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
+  lime:      `${ESC}[38;5;118m`,
+  emerald:   `${ESC}[38;5;42m`,
+  mint:      `${ESC}[38;5;48m`,
+  forest:    `${ESC}[38;5;34m`,
+  spring:    `${ESC}[38;5;82m`,
 };
 
 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 = `
@@ -69,7 +73,7 @@ function createSpinner(text) {
   let interval;
   return {
     start() {
-      process.stdout.write('\x1b[?25l'); // hide cursor
+      process.stdout.write('\x1b[?25l');
       interval = setInterval(() => {
         const frame = SPINNER_FRAMES[i % SPINNER_FRAMES.length];
         process.stdout.write(`\r  ${a.emerald}${frame}${a.reset} ${text}`);
@@ -79,7 +83,7 @@ function createSpinner(text) {
     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
+      process.stdout.write('\x1b[?25h');
     },
     fail(finalText) {
       clearInterval(interval);
@@ -93,7 +97,6 @@ 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}`);
@@ -104,12 +107,55 @@ function sectionEnd() {
   console.log(`  ${a.emerald}${a.bold}└──────────────────────────────────${a.reset}`);
 }
 
+// ── Semver compare (1=a>b, -1=a<b, 0=equal) ──
+function semverCompare(va, vb) {
+  const pa = va.split('.').map(Number);
+  const pb = vb.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) > (pb[i] || 0)) return 1;
+    if ((pa[i] || 0) < (pb[i] || 0)) return -1;
+  }
+  return 0;
+}
+
+// ── Detect existing install & read config ──
+function detectExisting(apedDir) {
+  const cwd = process.cwd();
+  const configPath = join(cwd, apedDir, 'config.yaml');
+  if (!existsSync(configPath)) return null;
+
+  // Parse existing config.yaml (simple key: value)
+  const existing = {};
+  try {
+    const content = readFileSync(configPath, 'utf-8');
+    for (const line of content.split('\n')) {
+      const match = line.match(/^(\w[\w_]*)\s*:\s*(.+)$/);
+      if (match) existing[match[1]] = match[2].trim().replace(/^["']|["']$/g, '');
+    }
+  } catch { /* ignore */ }
+
+  return {
+    projectName: existing.project_name || '',
+    authorName: existing.user_name || '',
+    communicationLang: existing.communication_language || DEFAULTS.communicationLang,
+    documentLang: existing.document_output_language || DEFAULTS.documentLang,
+    apedDir: existing.aped_path || apedDir,
+    outputDir: existing.output_path || DEFAULTS.outputDir,
+    ticketSystem: existing.ticket_system || DEFAULTS.ticketSystem,
+    gitProvider: existing.git_provider || DEFAULTS.gitProvider,
+    installedVersion: existing.aped_version || '0.0.0',
+  };
+}
+
 // ── 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; }
+    if (arg === '--update' || arg === '-u') { args.mode = 'update'; continue; }
+    if (arg === '--fresh' || arg === '--force') { args.mode = 'fresh'; continue; }
+    if (arg === '--version' || arg === '-v') { args.version = true; continue; }
     const match = arg.match(/^--(\w[\w-]*)=(.+)$/);
     if (match) {
       const key = match[1].replace(/-([a-z])/g, (_, ch) => ch.toUpperCase());
@@ -147,33 +193,65 @@ export async function run() {
 
   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();
   }
 
+  // ── Version flag ──
+  if (args.version) {
+    console.log(`aped-method v${CLI_VERSION}`);
+    return;
+  }
+
   // ── Banner ──
   console.log(LOGO);
+  console.log(`${a.dim}    v${CLI_VERSION}${a.reset}`);
+  console.log('');
   console.log(PIPELINE);
   console.log('');
 
+  // ── Detect existing installation ──
+  const apedDir = args.aped || args.apedDir || DEFAULTS.apedDir;
+  const existing = detectExisting(apedDir);
+
+  // ── Version upgrade detection ──
+  if (existing && existing.installedVersion !== '0.0.0') {
+    if (existing.installedVersion === CLI_VERSION) {
+      console.log(`  ${a.lime}${a.bold}✓${a.reset} ${dim(`Installed: v${existing.installedVersion} — up to date`)}`);
+    } else if (semverCompare(CLI_VERSION, existing.installedVersion) > 0) {
+      console.log(`  ${a.yellow}${a.bold}↑${a.reset} ${bold(`Upgrade available: v${existing.installedVersion} → v${CLI_VERSION}`)}`);
+      console.log(`  ${dim('  Run with --update to upgrade engine files')}`);
+    } else {
+      console.log(`  ${a.yellow}${a.bold}!${a.reset} ${dim(`Installed v${existing.installedVersion} is newer than CLI v${CLI_VERSION}`)}`);
+    }
+    console.log('');
+  }
+
   if (args.yes) {
+    // Non-interactive mode
+    let mode = args.mode || (existing ? 'update' : 'install');
+
+    const defaults = existing || DEFAULTS;
     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,
+      projectName: args.project || args.projectName || defaults.projectName || detectedProject || 'my-project',
+      authorName: args.author || args.authorName || defaults.authorName || '',
+      communicationLang: args.lang || args.communicationLang || defaults.communicationLang,
+      documentLang: args.docLang || args.documentLang || defaults.documentLang,
+      apedDir: args.aped || args.apedDir || defaults.apedDir || DEFAULTS.apedDir,
+      outputDir: args.output || args.outputDir || defaults.outputDir || DEFAULTS.outputDir,
       commandsDir: args.commands || args.commandsDir || DEFAULTS.commandsDir,
+      ticketSystem: args.tickets || args.ticketSystem || defaults.ticketSystem || DEFAULTS.ticketSystem,
+      gitProvider: args.git || args.gitProvider || defaults.gitProvider || DEFAULTS.gitProvider,
+      cliVersion: CLI_VERSION,
     };
 
-    await runScaffold(config);
+    await runScaffold(config, mode);
     return;
   }
 
+  // ── Interactive mode ──
   const rl = createInterface({ input: stdin, output: stdout });
 
   const prompt = stdinLines
@@ -186,20 +264,58 @@ export async function run() {
     : (question, def) => ask(rl, question, def);
 
   try {
+    let mode = 'install';
+
+    // ── Existing install detected ──
+    if (existing) {
+      const vInfo = existing.installedVersion !== '0.0.0'
+        ? ` | v${existing.installedVersion}`
+        : '';
+      console.log(`  ${a.yellow}${a.bold}⚠${a.reset}  ${bold('Existing APED installation detected')}`);
+      console.log(`  ${dim(`   Project: ${existing.projectName}${vInfo}`)}`);
+      console.log('');
+      console.log(`  ${a.emerald}│${a.reset}  ${bold('1')} ${dim('Update engine')}  ${dim('— upgrade skills, scripts, hooks. Preserve config & artifacts')}`);
+      console.log(`  ${a.emerald}│${a.reset}  ${bold('2')} ${dim('Fresh install')} ${dim('— delete everything and start from zero')}`);
+      console.log(`  ${a.emerald}│${a.reset}  ${bold('3')} ${dim('Cancel')}`);
+      console.log(`  ${a.emerald}│${a.reset}`);
+
+      const choice = await prompt(`${bold('Choice')}`, '1');
+
+      if (choice === '3' || choice.toLowerCase() === 'n') {
+        console.log(`\n  ${yellow('Cancelled.')}\n`);
+        return;
+      }
+
+      mode = choice === '2' ? 'fresh' : 'update';
+    }
+
+    // ── Config prompts ──
+    // For update: pre-fill with existing values
+    const defaults = (mode === 'update' && existing) ? existing : DEFAULTS;
+
     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);
+    if (mode === 'update') {
+      // In update mode, show current config and only ask what to change
+      console.log(`  ${a.emerald}│${a.reset}  ${dim('Current config loaded. Press Enter to keep, or type new value.')}`);
+      console.log(`  ${a.emerald}│${a.reset}`);
+    }
+
+    config.projectName = await prompt(`${bold('Project name')}`, defaults.projectName || 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 || DEFAULTS.apedDir);
+    config.outputDir = await prompt(`${bold('Output dir')} ${dim('(artifacts)')}`, defaults.outputDir || DEFAULTS.outputDir);
     config.commandsDir = await prompt(`${bold('Commands dir')}`, DEFAULTS.commandsDir);
+    config.ticketSystem = await prompt(`${bold('Ticket system')} ${dim(`(${TICKET_OPTIONS.join('/')})`)}`, defaults.ticketSystem || DEFAULTS.ticketSystem);
+    config.gitProvider = await prompt(`${bold('Git provider')} ${dim(`(${GIT_OPTIONS.join('/')})`)}`, defaults.gitProvider || DEFAULTS.gitProvider);
+    config.cliVersion = CLI_VERSION;
 
     sectionEnd();
     console.log('');
-    printConfig(config);
+    printConfig(config, mode);
     console.log('');
 
     const confirm = await prompt(`${bold('Proceed?')}`, 'Y');
@@ -208,50 +324,78 @@ export async function run() {
       return;
     }
 
-    await runScaffold(config);
+    await runScaffold(config, mode);
   } finally {
     rl.close();
   }
 }
 
-async function runScaffold(config) {
-  // ── Phase 1: Validating config ──
+async function runScaffold(config, mode) {
+  const modeLabel = mode === 'update' ? 'Updating' : mode === 'fresh' ? 'Fresh installing' : 'Installing';
+  const modeTag = mode === 'update'
+    ? `${a.yellow}${a.bold}UPDATE${a.reset}`
+    : mode === 'fresh'
+      ? `${a.red}${a.bold}FRESH${a.reset}`
+      : `${a.lime}${a.bold}INSTALL${a.reset}`;
+
+  console.log(`  ${modeTag}  ${dim(modeLabel + ' APED Method...')}`);
+  console.log('');
+
+  // ── Phase 1: Clean if fresh ──
+  if (mode === 'fresh') {
+    const s0 = createSpinner('Removing existing installation...');
+    s0.start();
+    const { rmSync } = await import('node:fs');
+    const cwd = process.cwd();
+    try { rmSync(join(cwd, config.apedDir), { recursive: true, force: true }); } catch { /* ok */ }
+    try { rmSync(join(cwd, config.outputDir), { recursive: true, force: true }); } catch { /* ok */ }
+    // Don't delete commands dir — may have non-aped commands
+    // Delete only aped-* command files
+    const { readdirSync } = await import('node:fs');
+    try {
+      const cmdDir = join(cwd, config.commandsDir);
+      for (const f of readdirSync(cmdDir)) {
+        if (f.startsWith('aped-')) {
+          rmSync(join(cmdDir, f), { force: true });
+        }
+      }
+    } catch { /* ok */ }
+    await sleep(300);
+    s0.stop('Previous installation removed');
+  }
+
+  // ── Phase 2: Validate ──
   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');
+  // ── Phase 3: Scaffold ──
+  sectionHeader(`Scaffolding Pipeline ${dim(`(${mode})`)}`);
   console.log(`  ${a.emerald}│${a.reset}`);
 
-  const count = await scaffoldWithCheckpoints(config);
+  const { created, updated, skipped } = await scaffoldWithCheckpoints(config, mode);
 
   sectionEnd();
 
-  // ── Phase 4: Setting up hooks ──
+  // ── Phase 4: Hooks ──
   const s3 = createSpinner('Installing guardrail hook...');
   s3.start();
   await sleep(350);
   s3.stop('Guardrail hook installed');
 
-  // ── Phase 5: Final verification ──
+  // ── Phase 5: Verify ──
+  const total = created + updated;
   const s4 = createSpinner('Verifying installation...');
   s4.start();
   await sleep(300);
-  s4.stop(`Installation verified — ${bold(String(count))} files`);
+  s4.stop(`Verified — ${bold(String(total))} files`);
 
   // ── Done ──
-  printDone(count);
+  printDone(created, updated, skipped, mode);
 }
 
-async function scaffoldWithCheckpoints(config) {
+async function scaffoldWithCheckpoints(config, mode) {
   const { getTemplates } = await import('./templates/index.js');
   const { mkdirSync, writeFileSync, chmodSync, existsSync } = await import('node:fs');
   const { join, dirname } = await import('node:path');
@@ -280,7 +424,14 @@ async function scaffoldWithCheckpoints(config) {
     else                                                     groups.config.items.push(tpl);
   }
 
-  let count = 0;
+  // Paths to preserve during update (user data, not engine)
+  const preserveOnUpdate = new Set([
+    join(config.outputDir, 'state.yaml'),
+  ]);
+
+  let created = 0;
+  let updated = 0;
+  let skipped = 0;
 
   for (const [, group] of Object.entries(groups)) {
     if (group.items.length === 0) continue;
@@ -289,31 +440,108 @@ async function scaffoldWithCheckpoints(config) {
     sp.start();
     await sleep(200);
 
-    let groupCount = 0;
+    let groupCreated = 0;
+    let groupUpdated = 0;
+    let groupSkipped = 0;
+
     for (const tpl of group.items) {
       const fullPath = join(cwd, tpl.path);
+      const fileExists = existsSync(fullPath);
+
       mkdirSync(dirname(fullPath), { recursive: true });
-      if (!existsSync(fullPath)) {
+
+      if (!fileExists) {
+        // New file — always create
         writeFileSync(fullPath, tpl.content, 'utf-8');
         if (tpl.executable) chmodSync(fullPath, 0o755);
-        groupCount++;
-        count++;
+        groupCreated++;
+        created++;
+      } else if (mode === 'update') {
+        // File exists + update mode
+        if (preserveOnUpdate.has(tpl.path)) {
+          // Preserve user artifacts
+          groupSkipped++;
+          skipped++;
+        } else if (tpl.path.endsWith('settings.local.json')) {
+          // Merge settings instead of overwrite
+          mergeSettings(fullPath, tpl.content);
+          groupUpdated++;
+          updated++;
+        } else {
+          // Engine file — overwrite with new version
+          writeFileSync(fullPath, tpl.content, 'utf-8');
+          if (tpl.executable) chmodSync(fullPath, 0o755);
+          groupUpdated++;
+          updated++;
+        }
+      } else if (mode === 'fresh') {
+        // Fresh mode — overwrite everything
+        writeFileSync(fullPath, tpl.content, 'utf-8');
+        if (tpl.executable) chmodSync(fullPath, 0o755);
+        groupCreated++;
+        created++;
+      } else {
+        // Install mode — skip existing
+        groupSkipped++;
+        skipped++;
       }
     }
 
-    sp.stop(`${group.icon}  ${group.label}  ${dim(`(${groupCount} files)`)}`);
+    const parts = [];
+    if (groupCreated > 0) parts.push(`${a.lime}+${groupCreated}${a.reset}`);
+    if (groupUpdated > 0) parts.push(`${a.yellow}↑${groupUpdated}${a.reset}`);
+    if (groupSkipped > 0) parts.push(`${a.dim}=${groupSkipped}${a.reset}`);
+    const stats = parts.length > 0 ? parts.join(' ') : `${a.dim}0${a.reset}`;
+
+    sp.stop(`${group.icon}  ${group.label}  ${dim('(')}${stats}${dim(')')}`);
   }
 
-  return count;
+  return { created, updated, skipped };
+}
+
+function mergeSettings(filePath, newContent) {
+  try {
+    const existing = JSON.parse(readFileSync(filePath, 'utf-8'));
+    const incoming = JSON.parse(newContent);
+
+    // Merge hooks: add guardrail if not already present
+    if (incoming.hooks) {
+      if (!existing.hooks) existing.hooks = {};
+      for (const [event, handlers] of Object.entries(incoming.hooks)) {
+        if (!existing.hooks[event]) {
+          existing.hooks[event] = handlers;
+        } else {
+          // Check if guardrail hook already exists
+          for (const handler of handlers) {
+            const hookCmds = handler.hooks || [];
+            for (const hook of hookCmds) {
+              const alreadyExists = existing.hooks[event].some((h) =>
+                (h.hooks || []).some((hk) => hk.command === hook.command)
+              );
+              if (!alreadyExists) {
+                existing.hooks[event].push(handler);
+              }
+            }
+          }
+        }
+      }
+    }
+
+    writeFS(filePath, JSON.stringify(existing, null, 2) + '\n', 'utf-8');
+  } catch {
+    // If can't parse existing, overwrite
+    writeFS(filePath, newContent, 'utf-8');
+  }
 }
 
-function printConfig(config) {
+function printConfig(config, mode) {
   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')}`);
+  const modeTag = mode === 'update' ? ` ${a.yellow}${a.bold}UPDATE${a.reset}` : mode === 'fresh' ? ` ${a.red}${a.bold}FRESH${a.reset}` : '';
+  console.log(`  ${a.emerald}${a.bold}┌─${a.reset} ${bold('Summary')}${modeTag}`);
   console.log(`  ${a.emerald}│${a.reset}`);
   box('Project',       config.projectName);
   box('Author',        config.authorName || dim('(not set)'));
@@ -322,15 +550,33 @@ function printConfig(config) {
   box('APED',          config.apedDir + '/',    'engine');
   box('Output',        config.outputDir + '/',  'artifacts');
   box('Commands',      config.commandsDir + '/');
+  box('Tickets',       config.ticketSystem,       config.ticketSystem === 'none' ? '' : 'integrated');
+  box('Git',           config.gitProvider);
+
+  if (mode === 'update') {
+    console.log(`  ${a.emerald}│${a.reset}`);
+    console.log(`  ${a.emerald}│${a.reset}  ${a.yellow}${a.bold}↑${a.reset} ${dim('Engine files will be overwritten')}`);
+    console.log(`  ${a.emerald}│${a.reset}  ${a.lime}${a.bold}=${a.reset} ${dim('Config, state & artifacts preserved')}`);
+  } else if (mode === 'fresh') {
+    console.log(`  ${a.emerald}│${a.reset}`);
+    console.log(`  ${a.emerald}│${a.reset}  ${a.red}${a.bold}!${a.reset} ${dim('All existing files will be deleted and recreated')}`);
+  }
+
   console.log(`  ${a.emerald}│${a.reset}`);
   console.log(`  ${a.emerald}${a.bold}└──────────────────────────────────${a.reset}`);
 }
 
-function printDone(count) {
+function printDone(created, updated, skipped, mode) {
+  const total = created + updated;
   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}`);
+  if (mode === 'update') {
+    console.log(`  ${a.emerald}${a.bold}║${a.reset}  ${a.lime}${a.bold}✓${a.reset} ${bold('Update complete')}                   ${a.emerald}${a.bold}║${a.reset}`);
+    console.log(`  ${a.emerald}${a.bold}║${a.reset}  ${dim(`  +${created} created  ↑${updated} updated  =${skipped} kept`)} ${a.emerald}${a.bold}║${a.reset}`);
+  } else {
+    console.log(`  ${a.emerald}${a.bold}║${a.reset}  ${a.lime}${a.bold}✓${a.reset} ${bold(`${total} 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('');
 
@@ -341,6 +587,8 @@ function printDone(count) {
   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.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

@@ -49,6 +49,16 @@ description: 'Adversarial code review for completed story. Use when user says "r
 ---
 
 Read and follow the SKILL.md at $PROJECT_ROOT/${a}/aped-r/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"'
+---
+
+Read and follow the SKILL.md at $PROJECT_ROOT/${a}/aped-quick/SKILL.md
 `,
     },
     {

package/src/templates/config.js

@@ -1,6 +1,9 @@
 export function configFiles(c) {
   const a = c.apedDir;
   const o = c.outputDir;
+  const ts = c.ticketSystem || 'none';
+  const gp = c.gitProvider || 'github';
+  const ver = c.cliVersion || '0.0.0';
   return [
     {
       path: `${a}/config.yaml`,
@@ -11,10 +14,15 @@ communication_language: ${c.communicationLang}
 document_output_language: ${c.documentLang}
 aped_path: ${a}
 output_path: ${o}
+aped_version: ${ver}
+
+# Integrations
+ticket_system: ${ts}
+git_provider: ${gp}
 `,
     },
     {
-      path: `${a}/state.yaml`,
+      path: `${o}/state.yaml`,
       content: `# APED Pipeline State
 pipeline:
   current_phase: "none"
@@ -224,6 +232,35 @@ sprint:
 ### Completion Notes
 
 ### File List
+`,
+    },
+    {
+      path: `${a}/templates/quick-spec.md`,
+      content: `# Quick Spec: {{title}}
+
+**Date:** {{date}}
+**Author:** {{user_name}}
+**Type:** {{fix|feature|refactor}}
+
+## What
+
+<!-- 1-2 sentences: what needs to change -->
+
+## Why
+
+<!-- 1 sentence: why this change matters now -->
+
+## Acceptance Criteria
+
+- [ ] {{criterion}}
+
+## Files to Change
+
+- {{file_path}} — {{what to change}}
+
+## Test Plan
+
+- {{test description}}
 `,
     },
   ];

package/src/templates/guardrail.js

@@ -13,7 +13,7 @@ export function guardrail(c) {
 set -euo pipefail
 
 PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
-STATE_FILE="$PROJECT_ROOT/${a}/state.yaml"
+STATE_FILE="$PROJECT_ROOT/${o}/state.yaml"
 CONFIG_FILE="$PROJECT_ROOT/${a}/config.yaml"
 OUTPUT_DIR="$PROJECT_ROOT/${o}"
 
@@ -56,6 +56,9 @@ WANTS_CODE=false
 [[ "$PROMPT_LOWER" =~ (aped-d|/aped-d|dev|implement|code|build|create.*component|create.*service) ]] && WANTS_DEV=true
 [[ "$PROMPT_LOWER" =~ (aped-r|/aped-r|review|audit) ]] && WANTS_REVIEW=true
 [[ "$PROMPT_LOWER" =~ (aped-all|/aped-all|full.pipeline|start.from.scratch) ]] && WANTS_ALL=true
+WANTS_QUICK=false
+
+[[ "$PROMPT_LOWER" =~ (aped-quick|/aped-quick|quick.fix|quick.feature|hotfix) ]] && WANTS_QUICK=true
 [[ "$PROMPT_LOWER" =~ (code|implement|write.*function|create.*file|add.*feature|fix.*bug|refactor) ]] && WANTS_CODE=true
 
 # ── Check artifact existence ──
@@ -84,6 +87,11 @@ phase_index() {
 
 CURRENT_IDX=$(phase_index "$CURRENT_PHASE")
 
+# Rule 0: Quick mode bypasses pipeline checks
+if [[ "$WANTS_QUICK" == "true" ]]; then
+  exit 0
+fi
+
 # Rule 1: Trying to code without epics/stories
 if [[ "$WANTS_CODE" == "true" || "$WANTS_DEV" == "true" ]] && [[ "$CURRENT_PHASE" != "dev" && "$CURRENT_PHASE" != "review" ]]; then
   if [[ "$HAS_EPICS" == "false" ]]; then

package/src/templates/skills.js

@@ -1,6 +1,6 @@
 export function skills(c) {
   const a = c.apedDir;   // .aped  (engine: skills, config, templates)
-  const o = c.outputDir; // docs/aped (output: generated artifacts)
+  const o = c.outputDir; // docs/aped (output: generated artifacts + state)
   return [
     // ── aped-a ──────────────────────────────────────────────
     {
@@ -14,8 +14,8 @@ description: 'Analyze project idea through parallel market, domain, and technica
 
 ## Setup
 
-1. Read \`${a}/config.yaml\` — extract \`user_name\`, \`communication_language\`
-2. Read \`${a}/state.yaml\` — check \`pipeline.phases.analyze\`
+1. Read \`${a}/config.yaml\` — extract \`user_name\`, \`communication_language\`, \`ticket_system\`, \`git_provider\`
+2. Read \`${o}/state.yaml\` — check \`pipeline.phases.analyze\`
    - If status is \`done\`: ask user — redo analysis or skip to next phase?
    - If user skips: invoke Skill tool with \`skill: "aped-p"\` and stop
 
@@ -80,7 +80,7 @@ If validation fails: fix missing sections and re-validate.
 
 ## State Update
 
-Update \`${a}/state.yaml\`:
+Update \`${o}/state.yaml\`:
 \`\`\`yaml
 pipeline:
   current_phase: "analyze"
@@ -108,7 +108,7 @@ description: 'Generate PRD autonomously from product brief. Use when user says "
 ## Setup
 
 1. Read \`${a}/config.yaml\` — extract \`user_name\`, \`communication_language\`, \`document_output_language\`
-2. Read \`${a}/state.yaml\` — check pipeline state
+2. Read \`${o}/state.yaml\` — check pipeline state
    - If \`pipeline.phases.prd.status\` is \`done\`: ask user — redo PRD or skip?
    - If user skips: invoke Skill tool with \`skill: "aped-e"\` and stop
 
@@ -162,7 +162,7 @@ bash ${a}/aped-p/scripts/validate-prd.sh ${o}/prd.md
 ## Output & State
 
 1. Write PRD to \`${o}/prd.md\`
-2. Update \`${a}/state.yaml\`:
+2. Update \`${o}/state.yaml\`:
 \`\`\`yaml
 pipeline:
   current_phase: "prd"
@@ -189,8 +189,8 @@ description: 'Create epics and stories from PRD with full FR coverage. Use when
 
 ## Setup
 
-1. Read \`${a}/config.yaml\` — extract config
-2. Read \`${a}/state.yaml\` — check pipeline state
+1. Read \`${a}/config.yaml\` — extract config including \`ticket_system\`
+2. Read \`${o}/state.yaml\` — check pipeline state
    - If \`pipeline.phases.epics.status\` is \`done\`: ask user — redo or skip?
    - If user skips: invoke Skill tool with \`skill: "aped-d"\` and stop
 
@@ -225,6 +225,16 @@ Story files: \`${o}/stories/{story-key}.md\`
 - ACs in **Given/When/Then** format
 - Tasks as checkboxes: \`- [ ] task [AC: AC#]\`
 
+## Ticket System Integration
+
+Read \`ticket_system\` from config. If not \`none\`:
+- Add ticket reference in each story header: \`**Ticket:** {{ticket_id}}\`
+- If \`jira\`: format as \`PROJ-###\` placeholder
+- If \`linear\`: format as \`TEAM-###\` placeholder
+- If \`github-issues\`: format as \`#issue_number\` placeholder
+- If \`gitlab-issues\`: format as \`#issue_number\` placeholder
+- Note: actual ticket creation is manual — these are reference placeholders
+
 ## FR Coverage Map
 
 Every FR from PRD mapped to exactly one epic. No orphans, no phantoms.
@@ -243,7 +253,7 @@ mkdir -p ${o}/stories
 
 1. Write epics to \`${o}/epics.md\`
 2. Create story files in \`${o}/stories/\` using \`${a}/templates/story.md\`
-3. Update \`${a}/state.yaml\` with sprint section and pipeline phase
+3. Update \`${o}/state.yaml\` with sprint section and pipeline phase
 
 ## Chain
 
@@ -262,8 +272,8 @@ description: 'Dev sprint - implement next story with TDD red-green-refactor. Use
 
 ## Setup
 
-1. Read \`${a}/config.yaml\` — extract config
-2. Read \`${a}/state.yaml\` — find next story
+1. Read \`${a}/config.yaml\` — extract config including \`ticket_system\`, \`git_provider\`
+2. Read \`${o}/state.yaml\` — find next story
 
 ## Story Selection
 
@@ -278,7 +288,7 @@ If story has \`[AI-Review]\` items: address them BEFORE regular tasks.
 
 ## State Update (start)
 
-Update \`${a}/state.yaml\`: story — \`in-progress\`, epic — \`in-progress\` if first story.
+Update \`${o}/state.yaml\`: story — \`in-progress\`, epic — \`in-progress\` if first story.
 
 ## Context Gathering
 
@@ -308,10 +318,16 @@ Mark \`[x]\` ONLY when: tests exist, pass 100%, implementation matches, ACs sati
 
 **STOP and ask user if:** new dependency, 3 consecutive failures, missing config, ambiguity.
 
+## Git Commit Convention
+
+Read \`git_provider\` and \`ticket_system\` from config:
+- Commit message format: \`type(scope): description\`
+- If ticket system configured, append ticket ref: \`type(scope): description [TICKET-ID]\`
+
 ## Completion
 
 1. Update story: mark tasks \`[x]\`, fill Dev Agent Record
-2. Update \`${a}/state.yaml\`: story — \`review\`
+2. Update \`${o}/state.yaml\`: story — \`review\`
 3. Chain to \`/aped-r\`
 `,
     },
@@ -327,8 +343,8 @@ description: 'Adversarial code review for completed stories. Use when user says
 
 ## Setup
 
-1. Read \`${a}/config.yaml\` — extract config
-2. Read \`${a}/state.yaml\` — find first story with status \`review\`
+1. Read \`${a}/config.yaml\` — extract config including \`git_provider\`
+2. Read \`${o}/state.yaml\` — find first story with status \`review\`
    - If none: report "No stories pending review" and stop
 
 ## Load Story
@@ -367,7 +383,78 @@ Severity: CRITICAL > HIGH > MEDIUM > LOW. Format: \`[Severity] Description [file
 
 ## State Update
 
-Update \`${a}/state.yaml\`. If more stories — chain to \`/aped-d\`. If all done — report completion.
+Update \`${o}/state.yaml\`. If more stories — chain to \`/aped-d\`. If all done — report completion.
+`,
+    },
+    // ── aped-quick ────────────────────────────────────────────
+    {
+      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.'
+---
+
+# APED Quick — Fast Track for Small Changes
+
+Use this for isolated fixes, small features, or refactors that don't warrant the full A→P→E→D→R pipeline.
+
+## Setup
+
+1. Read \`${a}/config.yaml\` — extract config
+2. Read \`${o}/state.yaml\` — note current phase for context
+
+## Scope Check
+
+This mode is for changes that:
+- Touch **5 files or fewer**
+- Can be completed in **1 session**
+- Don't introduce **new architectural patterns**
+- Don't require **new dependencies**
+
+If any of these are violated, recommend the full pipeline instead.
+
+## Quick Spec (2 minutes)
+
+Ask the user:
+1. **What?** — What needs to change (1-2 sentences)
+2. **Why?** — Why now, what breaks without it
+3. **Type?** — fix | feature | refactor
+
+Generate a quick spec using \`${a}/templates/quick-spec.md\`:
+- Fill: title, type, what, why, acceptance criteria, files to change, test plan
+- Write to \`${o}/quick-specs/{date}-{slug}.md\`
+
+## Implementation (TDD)
+
+Same TDD cycle as aped-d but compressed:
+
+1. **RED** — Write test for the expected behavior
+2. **GREEN** — Minimal implementation to pass
+3. **REFACTOR** — Clean up while green
+
+Run tests: \`bash ${a}/aped-d/scripts/run-tests.sh\`
+
+## Self-Review (30 seconds)
+
+Quick checklist — no full adversarial review:
+- [ ] Tests pass
+- [ ] No security issues introduced
+- [ ] No regressions in existing tests
+- [ ] AC from quick spec satisfied
+
+## Git Commit
+
+Read \`ticket_system\` and \`git_provider\` from config.
+- Format: \`type(scope): description\`
+- Append ticket ref if configured
+- If \`git_provider\` is \`github\`: suggest PR creation with \`gh pr create\`
+- If \`git_provider\` is \`gitlab\`: suggest MR creation with \`glab mr create\`
+
+## Output
+
+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
 `,
     },
     // ── aped-all ─────────────────────────────────────────────
@@ -382,7 +469,7 @@ description: 'Run full APED pipeline from Analyze through Review. Use when user
 
 ## Resume Logic
 
-1. Read \`${a}/state.yaml\`
+1. Read \`${o}/state.yaml\`
 2. Determine resume point:
 
 | State | Action |
@@ -397,11 +484,11 @@ description: 'Run full APED pipeline from Analyze through Review. Use when user
 ## Execution
 
 Use the Skill tool to invoke each phase: aped-a, aped-p, aped-e, aped-d, aped-r.
-Each phase updates \`${a}/state.yaml\` and chains automatically.
+Each phase updates \`${o}/state.yaml\` and chains automatically.
 
 ## Interruption Handling
 
-State persists in \`${a}/state.yaml\`. Next \`/aped-all\` resumes from last incomplete phase.
+State persists in \`${o}/state.yaml\`. Next \`/aped-all\` resumes from last incomplete phase.
 
 ## Completion Report