design-protocol 1.0.0

package/bin/install.js

@@ -0,0 +1,464 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { execSync } = require('child_process');
+
+const VERSION = '1.0.0';
+const PACKAGE_NAME = 'design-protocol';
+const PACKAGE_DIR = path.join(__dirname, '..');
+let VERBOSE = false;
+
+// ANSI colors
+const c = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  red: '\x1b[31m'
+};
+
+function log(msg, color = 'reset') {
+  console.log(`${c[color]}${msg}${c.reset}`);
+}
+
+function logStep(step, total, msg) {
+  console.log(`${c.cyan}[${step}/${total}]${c.reset} ${msg}`);
+}
+
+function logSuccess(msg) {
+  console.log(`  ${c.green}✓${c.reset} ${msg}`);
+}
+
+function logSkip(msg) {
+  console.log(`  ${c.yellow}○${c.reset} ${msg}`);
+}
+
+function logError(msg) {
+  console.log(`  ${c.red}✗${c.reset} ${msg}`);
+}
+
+function logVerbose(msg) {
+  if (VERBOSE) console.log(`  ${c.dim}  → ${msg}${c.reset}`);
+}
+
+function printBanner() {
+  console.log(`\n${c.magenta}${c.bright}  DP ${c.reset}${c.cyan}Design Protocol${c.reset} ${c.dim}v${VERSION}${c.reset}`);
+  console.log(`${c.dim}  Complete design workflow for Claude Code${c.reset}\n`);
+}
+
+function getClaudeDir(location) {
+  if (location === 'global') {
+    const homeDir = process.env.HOME || process.env.USERPROFILE;
+    return process.env.CLAUDE_CONFIG_DIR || path.join(homeDir, '.claude');
+  }
+  return path.join(process.cwd(), '.claude');
+}
+
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) {
+    logVerbose(`mkdir ${dir}`);
+    try {
+      fs.mkdirSync(dir, { recursive: true });
+    } catch (err) {
+      if (err.code === 'EACCES') {
+        throw new Error(`Permission denied creating directory: ${dir}\n  Try running with sudo or check folder permissions.`);
+      }
+      throw new Error(`Failed to create directory: ${dir}\n  ${err.message}`);
+    }
+  }
+}
+
+const MAX_COPY_DEPTH = 10;
+const SKIP_ENTRIES = new Set(['.git', '.DS_Store', '.env', 'node_modules', '.next']);
+
+function copyRecursive(src, dest, depth = 0) {
+  if (!fs.existsSync(src)) return 0;
+  if (depth > MAX_COPY_DEPTH) {
+    logError(`Skipping deeply nested path (>${MAX_COPY_DEPTH} levels): ${src}`);
+    return 0;
+  }
+
+  // Skip symlinks — only copy real files
+  const lstats = fs.lstatSync(src);
+  if (lstats.isSymbolicLink()) return 0;
+
+  let count = 0;
+
+  if (lstats.isDirectory()) {
+    ensureDir(dest);
+    const files = fs.readdirSync(src);
+    for (const file of files) {
+      if (SKIP_ENTRIES.has(file)) continue;
+      count += copyRecursive(
+        path.join(src, file),
+        path.join(dest, file),
+        depth + 1
+      );
+    }
+  } else {
+    try {
+      fs.copyFileSync(src, dest);
+      logVerbose(`${path.basename(src)}`);
+    } catch (err) {
+      if (err.code === 'EACCES') {
+        throw new Error(`Permission denied writing file: ${dest}`);
+      }
+      throw new Error(`Failed to copy ${path.basename(src)} → ${dest}\n  ${err.message}`);
+    }
+    count = 1;
+  }
+  return count;
+}
+
+function countFiles(dir) {
+  if (!fs.existsSync(dir)) return 0;
+  let count = 0;
+  const items = fs.readdirSync(dir);
+  for (const item of items) {
+    const itemPath = path.join(dir, item);
+    const stats = fs.statSync(itemPath);
+    if (stats.isDirectory()) {
+      count += countFiles(itemPath);
+    } else {
+      count++;
+    }
+  }
+  return count;
+}
+
+async function prompt(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase());
+    });
+  });
+}
+
+function getLatestVersion() {
+  try {
+    const result = execSync(`npm view ${PACKAGE_NAME} version`, { encoding: 'utf8' });
+    return result.trim();
+  } catch (err) {
+    return null;
+  }
+}
+
+function compareVersions(v1, v2) {
+  const parts1 = v1.split('.').map(Number);
+  const parts2 = v2.split('.').map(Number);
+
+  for (let i = 0; i < Math.max(parts1.length, parts2.length); i++) {
+    const p1 = parts1[i] || 0;
+    const p2 = parts2[i] || 0;
+    if (p1 > p2) return 1;
+    if (p1 < p2) return -1;
+  }
+  return 0;
+}
+
+async function checkForUpdate() {
+  log('\nChecking for updates...', 'dim');
+
+  const latest = getLatestVersion();
+  if (!latest) {
+    logError('Could not check for updates. Are you online?');
+    return false;
+  }
+
+  const comparison = compareVersions(latest, VERSION);
+
+  if (comparison > 0) {
+    log(`\n${c.yellow}Update available!${c.reset} ${VERSION} → ${c.green}${latest}${c.reset}\n`);
+    return latest;
+  } else if (comparison === 0) {
+    log(`\n${c.green}✓${c.reset} You have the latest version (${VERSION})\n`);
+    return false;
+  } else {
+    log(`\n${c.green}✓${c.reset} You have a newer version (${VERSION}) than npm (${latest})\n`);
+    return false;
+  }
+}
+
+async function performUpdate(location) {
+  log(`\nUpdating DP...`, 'bright');
+
+  try {
+    // Run npx with latest version
+    log('Downloading latest version...', 'dim');
+    execSync(`npx ${PACKAGE_NAME}@latest --${location} --auto`, {
+      stdio: 'inherit',
+      encoding: 'utf8'
+    });
+    return true;
+  } catch (err) {
+    logError(`Update failed: ${err.message}`);
+    return false;
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  // Parse arguments
+  const isGlobal = args.includes('--global') || args.includes('-g');
+  const isLocal = args.includes('--local') || args.includes('-l');
+  const isAuto = args.includes('--auto');
+  const isUninstall = args.includes('--uninstall') || args.includes('-u');
+  const isUpdate = args.includes('--update') || args.includes('--upgrade');
+  const isCheckUpdate = args.includes('--check-update');
+  const isHelp = args.includes('--help') || args.includes('-h');
+  const showVersion = args.includes('--version') || args.includes('-v');
+  VERBOSE = args.includes('--verbose');
+
+  if (showVersion) {
+    console.log(`dp v${VERSION}`);
+    process.exit(0);
+  }
+
+  if (isHelp) {
+    console.log(`
+${c.bright}DP - Design Protocol v${VERSION}${c.reset}
+
+Usage: npx design-protocol [options]
+
+Options:
+  --global, -g     Install to ~/.claude/ (all projects)
+  --local, -l      Install to ./.claude/ (current project only)
+  --auto           Non-interactive install (default: global)
+  --update         Update to the latest version
+  --check-update   Check if updates are available
+  --uninstall, -u  Remove DP from specified location
+  --verbose        Show detailed output for troubleshooting
+  --version, -v    Show version number
+  --help, -h       Show this help message
+
+Examples:
+  npx design-protocol              # Interactive installation
+  npx design-protocol --global     # Install globally
+  npx design-protocol --local      # Install to current project
+  npx design-protocol --update     # Update to latest version
+  npx design-protocol -g -u        # Uninstall from global
+
+${c.bright}What Gets Installed:${c.reset}
+  ~/.claude/skills/      10 design skills (dp-discovery, dp-prd, dp-journey, dp-roadmap, dp-ux, dp-color, dp-ui, dp-eng_review, dp-research, dp-storytell)
+  ~/.claude/commands/    7 workflow commands (dp:start, dp:execute, etc.)
+  ~/.claude/agents/      2 specialized agents
+
+${c.bright}Workflow:${c.reset}
+  /dp:start → /dp:discovery → /dp:ux → /dp:execute → /dp:ui → /dp:execute → /dp:eng_review → /dp:verify
+`);
+    process.exit(0);
+  }
+
+  // Check for updates only
+  if (isCheckUpdate) {
+    printBanner();
+    await checkForUpdate();
+    process.exit(0);
+  }
+
+  // Update mode
+  if (isUpdate) {
+    printBanner();
+    const latest = await checkForUpdate();
+    if (latest) {
+      const location = isLocal ? 'local' : 'global';
+      const answer = await prompt(`Update to v${latest}? [Y/n]: `);
+      if (answer !== 'n' && answer !== 'no') {
+        await performUpdate(location);
+      } else {
+        log('Update cancelled.', 'yellow');
+      }
+    }
+    process.exit(0);
+  }
+
+  printBanner();
+
+  // Determine installation location
+  let location;
+  if (isGlobal || isAuto) {
+    location = 'global';
+  } else if (isLocal) {
+    location = 'local';
+  } else {
+    log('\nWhere would you like to install DP?\n', 'bright');
+    console.log('  1. Global (~/.claude/) - Available in all projects');
+    console.log('  2. Local  (./.claude/) - Current project only\n');
+    const answer = await prompt('Choose [1/2] (default: 1): ');
+    location = answer === '2' ? 'local' : 'global';
+  }
+
+  const claudeDir = getClaudeDir(location);
+  const skillsDir = path.join(claudeDir, 'skills');
+  const commandsDir = path.join(claudeDir, 'commands');
+  const agentsDir = path.join(claudeDir, 'agents');
+
+  if (VERBOSE) {
+    log('', 'dim');
+    log('  Resolved paths:', 'dim');
+    log(`    PACKAGE_DIR:     ${PACKAGE_DIR}`, 'dim');
+    log(`    claudeDir:       ${claudeDir}`, 'dim');
+    log(`    CLAUDE_CONFIG_DIR: ${process.env.CLAUDE_CONFIG_DIR || '(not set)'}`, 'dim');
+    log(`    HOME:            ${process.env.HOME || process.env.USERPROFILE}`, 'dim');
+    log('', 'dim');
+  }
+
+  if (isUninstall) {
+    await runUninstall(location, { skillsDir, commandsDir, agentsDir, claudeDir });
+  } else {
+    await runInstall(location, { skillsDir, commandsDir, agentsDir, claudeDir }, isAuto);
+  }
+}
+
+// ─── Uninstall ────────────────────────────────────────────────────────────────
+
+async function runUninstall(location, dirs) {
+  log(`\nUninstalling from ${location} location...`, 'yellow');
+  log(`Target: ${dirs.claudeDir}`, 'dim');
+
+  let removed = 0;
+
+  const skillNames = ['dp-discovery', 'dp-prd', 'dp-journey', 'dp-roadmap', 'dp-ux', 'dp-color', 'dp-ui', 'dp-eng_review', 'dp-research', 'dp-storytell'];
+  for (const name of skillNames) {
+    const skillPath = path.join(dirs.skillsDir, name);
+    if (fs.existsSync(skillPath)) {
+      fs.rmSync(skillPath, { recursive: true, force: true });
+      logSuccess(`Removed skill: ${name}`);
+      removed++;
+    }
+  }
+
+  const commandFiles = fs.readdirSync(path.join(PACKAGE_DIR, 'commands')).filter(f => f.endsWith('.md'));
+  for (const file of commandFiles) {
+    const cmdPath = path.join(dirs.commandsDir, file);
+    if (fs.existsSync(cmdPath)) {
+      fs.unlinkSync(cmdPath);
+      logSuccess(`Removed command: ${file}`);
+      removed++;
+    }
+  }
+
+  const agentFiles = fs.readdirSync(path.join(PACKAGE_DIR, 'agents')).filter(f => f.endsWith('.md'));
+  for (const file of agentFiles) {
+    const agentPath = path.join(dirs.agentsDir, file);
+    if (fs.existsSync(agentPath)) {
+      fs.unlinkSync(agentPath);
+      logSuccess(`Removed agent: ${file}`);
+      removed++;
+    }
+  }
+
+  if (removed > 0) {
+    log(`\n${c.green}DP uninstalled successfully!${c.reset}\n`);
+  } else {
+    log(`\n${c.yellow}No DP installation found at ${dirs.claudeDir}${c.reset}\n`);
+  }
+}
+
+// ─── Install ──────────────────────────────────────────────────────────────────
+
+async function runInstall(location, dirs, isAuto) {
+  const totalSteps = 4;
+  log(`\nInstalling to ${location} location...`, 'bright');
+  log(`Target: ${dirs.claudeDir}\n`, 'dim');
+
+  // Step 1: Skills
+  logStep(1, totalSteps, 'Installing skills...');
+  const srcSkills = path.join(PACKAGE_DIR, 'skills');
+  const skillDirs = fs.readdirSync(srcSkills).filter(f =>
+    fs.statSync(path.join(srcSkills, f)).isDirectory()
+  );
+
+  for (const skill of skillDirs) {
+    const src = path.join(srcSkills, skill);
+    const dest = path.join(dirs.skillsDir, skill);
+
+    if (fs.existsSync(dest) && !isAuto) {
+      const answer = await prompt(`  Overwrite ${skill}? [y/N]: `);
+      if (answer !== 'y' && answer !== 'yes') {
+        logSkip(skill);
+        continue;
+      }
+      fs.rmSync(dest, { recursive: true, force: true });
+    }
+
+    const count = copyRecursive(src, dest);
+    logSuccess(`${skill} (${count} files)`);
+  }
+
+  // Step 2: Commands
+  logStep(2, totalSteps, 'Installing commands...');
+  ensureDir(dirs.commandsDir);
+  const srcCommands = path.join(PACKAGE_DIR, 'commands');
+  const commandFiles = fs.readdirSync(srcCommands).filter(f => f.endsWith('.md'));
+
+  for (const file of commandFiles) {
+    fs.copyFileSync(path.join(srcCommands, file), path.join(dirs.commandsDir, file));
+    logSuccess(file.replace('.md', ''));
+  }
+
+  // Step 3: Agents
+  logStep(3, totalSteps, 'Installing agents...');
+  ensureDir(dirs.agentsDir);
+  const srcAgents = path.join(PACKAGE_DIR, 'agents');
+  const agentFiles = fs.readdirSync(srcAgents).filter(f => f.endsWith('.md'));
+
+  for (const file of agentFiles) {
+    fs.copyFileSync(path.join(srcAgents, file), path.join(dirs.agentsDir, file));
+    logSuccess(file.replace('.md', ''));
+  }
+
+  // Step 4: Summary
+  logStep(4, totalSteps, 'Installation complete!');
+  printSummary(
+    { skills: skillDirs.length, commands: commandFiles.length, agents: agentFiles.length },
+    dirs
+  );
+}
+
+// ─── Summary ──────────────────────────────────────────────────────────────────
+
+function printSummary(counts, dirs) {
+  console.log(`
+${c.green}${c.bright}DP ${VERSION} installed successfully!${c.reset}
+
+${c.bright}Installed:${c.reset}
+  ${c.cyan}${counts.skills}${c.reset} skills      → ${dirs.skillsDir}
+  ${c.cyan}${counts.commands}${c.reset} commands   → ${dirs.commandsDir}
+  ${c.cyan}${counts.agents}${c.reset} agents     → ${dirs.agentsDir}
+
+${c.bright}Quick Start:${c.reset}
+  ${c.cyan}/dp:start${c.reset}       Start a new design workflow
+  ${c.cyan}/dp:progress${c.reset}    Check workflow status
+  ${c.cyan}/dp:execute${c.reset}     Generate implementation
+
+${c.bright}Design Skills:${c.reset}
+  ${c.cyan}/dp:discovery${c.reset}        Discovery & requirements
+  ${c.cyan}/dp:ux${c.reset}              UX principles & states
+  ${c.cyan}/dp:ui${c.reset}              Visual design & tokens
+  ${c.cyan}/dp:eng_review${c.reset} Code review & a11y
+
+${c.bright}Workflow:${c.reset}
+  Discovery → UX → ${c.yellow}Execute(wireframe)${c.reset} → UI → ${c.yellow}Execute(polished)${c.reset} → Review
+
+${c.dim}Restart Claude Code to load DP.${c.reset}
+`);
+}
+
+main().catch((err) => {
+  logError(`Installation failed: ${err.message}`);
+  console.error(err);
+  process.exit(1);
+});

package/commands/dp-back.md

@@ -0,0 +1,221 @@
+---
+name: dp-back
+description: Go back to a previous DP workflow phase. Use to revisit decisions, update context, or re-run a phase with new information.
+---
+
+# /dp:back — Return to Previous Phase
+
+You are navigating back in the DP workflow. This allows revisiting earlier phases to update or refine design work.
+
+## When to Use
+
+- New information invalidates earlier decisions
+- Need to update discovery based on research findings
+- Want to refine UX decisions after UI work revealed issues
+- Stakeholder feedback requires earlier phase changes
+- Review found issues that need design-level fixes
+
+## Workflow
+
+### Step 1: Check Workflow Exists
+
+```bash
+ls .design/config.json 2>/dev/null
+```
+
+### Step 2: Get Current Position
+
+Read `.design/STATE.md` and `.design/config.json` to determine:
+- Current phase number
+- Completed phases
+- Available phases to return to
+
+### Step 3: Present Options
+
+**If current phase > 1:**
+```
+CURRENT POSITION: Phase [N] — [Phase Name]
+
+Go back to:
+  1. Discovery — Update problem/users/requirements
+  2. UX — Revise user flows and states
+  [3. UI — Adjust visual specs]
+
+Or enter phase number (1-[N-1])
+
+Which phase? (1-[N-1] or cancel)
+```
+
+**If on first phase:**
+```
+You're on Phase 1 (Discovery) — can't go back further.
+
+Options:
+• Run /dp:discovery to start/redo discovery
+• Run /dp:progress to see status
+```
+
+### Step 4: Handle Navigation
+
+**When user selects a phase:**
+
+1. Confirm the action:
+```
+Going back to: Phase [X] — [Phase Name]
+
+This will:
+✓ Set Phase [X] as current
+✓ Keep existing [Phase X] output for reference
+○ Later phases remain but may need updates
+
+Continue? (y/n)
+```
+
+2. Update `.design/STATE.md`:
+   - Set current phase to selected phase
+   - Add navigation to activity log
+   - Note any context about why going back
+
+3. Update `.design/config.json`:
+   - Set `current_phase` to selected phase number
+   - Don't remove later phases from `phases_completed` (they exist but may be stale)
+
+4. Rename existing phase file (if exists):
+   - `.design/phases/DISCOVERY.md` → `.design/phases/DISCOVERY.v1.md`
+   - Allows fresh start while preserving history
+
+**Output:**
+```
+✓ Returned to: Phase [X] — [Phase Name]
+
+Previous output preserved as: [PHASE_NAME].v1.md
+
+Current Position:
+  Phase: [X] of 4 ([Phase Name])
+  Status: Ready
+  Progress: [██░░░░░░░░] [X]%
+
+Note: Phases [X+1] through [N] may need updates after you modify this phase.
+
+Next: Run /[skill] to redo this phase
+      Or /dp:discuss to capture new context first
+```
+
+### Step 5: Provide Context
+
+When going back, remind user of relevant context:
+
+**Going back to Discovery:**
+```
+CONTEXT FOR DISCOVERY REDO
+────────────────────────────────────────────────────────────────────────────────
+What triggered going back:
+• [from user or inferred]
+
+Existing outputs that may be affected:
+• UX-DECISIONS.md — May need updates
+• UI-SPEC.md — May need updates
+
+Key questions to reconsider:
+• Is the problem statement still accurate?
+• Has our understanding of users changed?
+• Do requirements need reprioritization?
+```
+
+**Going back to UX:**
+```
+CONTEXT FOR UX REDO
+────────────────────────────────────────────────────────────────────────────────
+From Discovery (unchanged):
+• Problem: [problem statement]
+• User: [primary user]
+
+What may need updating:
+• User flows
+• State definitions
+• Accessibility requirements
+
+Existing UI spec may need realignment after UX changes.
+```
+
+### Step 6: Edge Cases
+
+**Going back with uncommitted changes:**
+```
+Note: You have changes in progress for Phase [N].
+
+Options:
+1. Go back anyway (current progress will be marked incomplete)
+2. Complete current phase first, then go back
+3. Cancel
+
+Choice?
+```
+
+**Going back to a skipped phase:**
+```
+Phase [X] was previously skipped.
+
+Going back will:
+• Set Phase [X] as current
+• Allow you to complete it properly
+
+This is a good way to fill in a skipped phase.
+
+Continue? (y/n)
+```
+
+**Multiple iterations:**
+
+Track version history in STATE.md:
+```markdown
+## Iteration History
+
+| Phase | Version | Date | Reason |
+|-------|---------|------|--------|
+| Discovery | v1 | 2024-01-15 | Initial |
+| Discovery | v2 | 2024-01-18 | Updated after research |
+| UX | v1 | 2024-01-16 | Initial |
+```
+
+## Version Management
+
+When going back, preserve history:
+
+```
+.design/phases/
+├── DISCOVERY.md        # Current version (v2)
+├── DISCOVERY.v1.md     # Previous version
+├── UX-DECISIONS.md     # Current (may be stale)
+└── UI-SPEC.md          # Current (may be stale)
+```
+
+Maximum versions to keep: 3 (oldest auto-deleted)
+
+## State Updates
+
+**STATE.md activity log:**
+```markdown
+### Last Activity
+- **Date:** [TIMESTAMP]
+- **Action:** Returned to Discovery phase (was on UI)
+- **Reason:** Research findings changed user understanding
+```
+
+## Integration Notes
+
+- Skills should check STATE.md to see if they're running as a redo
+- If redoing, skill can offer to show diff from previous version
+- Later phases should be flagged as "may need update" in progress view
+
+---
+
+## Workflow Navigation
+
+| | |
+|---|---|
+| **This command** | `/dp:back` — Return to previous phase |
+| **Use when** | New information invalidates earlier decisions |
+| **Returns to** | The previous phase (or a specific phase if specified) |
+| **Then run** | The phase skill for that phase to redo it |
+| **Related** | `/dp:skip` — Skip forward if redo isn't needed after all |