claude-blueprint 1.0.0

package/src/claude-md.js

@@ -0,0 +1,57 @@
+import { readFile, writeFile } from 'fs/promises';
+
+const BEGIN = '<!-- BEGIN blueprint -->';
+const END = '<!-- END blueprint -->';
+
+const SECTION = `${BEGIN}
+## blueprint
+
+Architecture Decision Records with teeth. Cranky senior engineer persona.
+
+### Commands
+
+| Command | What it does |
+|---------|-------------|
+| \`/blueprint:help\` | Full reference + contextual suggestions |
+| \`/blueprint:list\` | ADR table + next actions |
+| \`/blueprint:new "topic"\` | Create ADR (add \`--research\` for evidence) |
+| \`/blueprint:review N\` | Devil's advocate challenge before acceptance |
+| \`/blueprint:transition accept N\` | Accept / reject / defer / deprecate |
+| \`/blueprint:search "term"\` | Find decisions by topic |
+| \`/blueprint:impact N\` | Check for cross-ADR conflicts |
+| \`/blueprint:audit\` | Verify codebase follows accepted decisions |
+| \`/blueprint:retro\` | Post-fix retrospective (band-aid or systemic?) |
+| \`/blueprint:evaluate\` | 5-agent architecture evaluation team |
+| \`/blueprint:rearchitect "topic"\` | Research + supersede a decision |
+
+### Architecture Evaluation Dimensions
+
+| Dimension | Command |
+|-----------|---------|
+| Structural consistency | \`/blueprint:evaluate consistency\` |
+| Bug surface mapping | \`/blueprint:evaluate bugs\` |
+| Long-term maintainability | \`/blueprint:evaluate maintainability\` |
+| Testing strategy | \`/blueprint:evaluate testing\` |
+| Conway's Law alignment | \`/blueprint:evaluate conways\` |
+${END}`;
+
+export async function updateClaudeMd(claudeMdPath) {
+  let content = '';
+  try {
+    content = await readFile(claudeMdPath, 'utf-8');
+  } catch {
+    // File doesn't exist yet
+  }
+
+  const regex = new RegExp(
+    `${BEGIN.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`,
+  );
+
+  if (regex.test(content)) {
+    content = content.replace(regex, SECTION);
+  } else {
+    content = content ? content.trimEnd() + '\n\n' + SECTION + '\n' : SECTION + '\n';
+  }
+
+  await writeFile(claudeMdPath, content, 'utf-8');
+}

package/src/install.js

@@ -0,0 +1,83 @@
+import { readdir, copyFile, mkdir } from 'fs/promises';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { getTargetPaths } from './paths.js';
+import { updateClaudeMd } from './claude-md.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PLUGIN_ROOT = join(__dirname, '..');
+
+export async function install(opts) {
+  let scope = opts.global ? 'global' : opts.project ? 'project' : null;
+
+  if (!scope) {
+    const { select } = await import('@inquirer/prompts');
+    scope = await select({
+      message: 'Where should blueprint be installed?',
+      choices: [
+        { name: 'Global (~/.claude/) — available in all projects', value: 'global' },
+        { name: 'Project (.claude/) — this project only', value: 'project' },
+      ],
+    });
+  }
+
+  const { default: ora } = await import('ora');
+  const paths = getTargetPaths(scope);
+
+  // Create directories
+  const spinner = ora('Creating directories...').start();
+  for (const subDir of ['', 'help', 'list', 'new', 'review', 'transition', 'search', 'impact', 'audit', 'retro', 'evaluate', 'rearchitect', 'agents', 'config']) {
+    await mkdir(join(paths.commands, subDir), { recursive: true });
+  }
+  spinner.succeed('Directories created');
+
+  // Copy root command (router)
+  spinner.start('Installing router...');
+  await copyFile(
+    join(PLUGIN_ROOT, 'commands', 'blueprint.md'),
+    join(paths.commands, 'SKILL.md'),
+  );
+  spinner.succeed('Router installed');
+
+  // Copy sub-commands as SKILL.md in their directories
+  spinner.start('Installing commands...');
+  const commands = ['help', 'list', 'new', 'review', 'transition', 'search', 'impact', 'audit', 'retro', 'evaluate', 'rearchitect'];
+  for (const cmd of commands) {
+    await copyFile(
+      join(PLUGIN_ROOT, 'commands', `${cmd}.md`),
+      join(paths.commands, cmd, 'SKILL.md'),
+    );
+  }
+  spinner.succeed(`${commands.length} commands installed`);
+
+  // Copy agents
+  spinner.start('Installing agents...');
+  const agentFiles = await readdir(join(PLUGIN_ROOT, 'agents'));
+  for (const file of agentFiles) {
+    await copyFile(
+      join(PLUGIN_ROOT, 'agents', file),
+      join(paths.agents, file),
+    );
+  }
+  spinner.succeed(`${agentFiles.length} agents installed`);
+
+  // Copy config
+  spinner.start('Installing config...');
+  const configFiles = await readdir(join(PLUGIN_ROOT, 'config'));
+  for (const file of configFiles) {
+    await copyFile(
+      join(PLUGIN_ROOT, 'config', file),
+      join(paths.config, file),
+    );
+  }
+  spinner.succeed(`${configFiles.length} config files installed`);
+
+  // Update CLAUDE.md
+  spinner.start('Updating CLAUDE.md...');
+  await updateClaudeMd(paths.claudeMd);
+  spinner.succeed('CLAUDE.md updated');
+
+  console.log(`\n✓ blueprint installed (${scope})`);
+  console.log(`  Commands: ${paths.commands}`);
+  console.log(`  Run /blueprint:help to get started\n`);
+}

package/src/paths.js

@@ -0,0 +1,25 @@
+import { homedir } from 'os';
+import { join } from 'path';
+
+export function getTargetPaths(scope) {
+  if (scope === 'global') {
+    const base = join(homedir(), '.claude');
+    return {
+      commands: join(base, 'commands', 'blueprint'),
+      agents: join(base, 'commands', 'blueprint', 'agents'),
+      config: join(base, 'commands', 'blueprint', 'config'),
+      claudeMd: join(base, 'CLAUDE.md'),
+      scope: 'global',
+    };
+  }
+
+  // Project scope
+  const base = join(process.cwd(), '.claude');
+  return {
+    commands: join(base, 'commands', 'blueprint'),
+    agents: join(base, 'commands', 'blueprint', 'agents'),
+    config: join(base, 'commands', 'blueprint', 'config'),
+    claudeMd: join(process.cwd(), 'CLAUDE.md'),
+    scope: 'project',
+  };
+}

package/src/verify.js

@@ -0,0 +1,95 @@
+import { access } from 'fs/promises';
+import { join } from 'path';
+import { getTargetPaths } from './paths.js';
+
+const EXPECTED_COMMANDS = [
+  'SKILL.md',
+  'help/SKILL.md',
+  'list/SKILL.md',
+  'new/SKILL.md',
+  'review/SKILL.md',
+  'transition/SKILL.md',
+  'search/SKILL.md',
+  'impact/SKILL.md',
+  'audit/SKILL.md',
+  'retro/SKILL.md',
+  'evaluate/SKILL.md',
+  'rearchitect/SKILL.md',
+];
+
+const EXPECTED_AGENTS = [
+  'persona.md',
+  'adr-researcher.md',
+  'adr-devils-advocate.md',
+  'adr-impact-analyzer.md',
+  'adr-compliance-auditor.md',
+  'adr-consistency-auditor.md',
+  'adr-bug-surface-mapper.md',
+  'adr-maintainability-assessor.md',
+  'adr-testing-strategy-evaluator.md',
+  'adr-conways-law-analyzer.md',
+  'adr-retrospective.md',
+];
+
+const EXPECTED_CONFIG = [
+  'lifecycle.toml',
+  'taxonomy.toml',
+  'state.toml',
+  'relationships.toml',
+];
+
+async function fileExists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function verify(opts) {
+  const scopes = opts.scope ? [opts.scope] : ['global', 'project'];
+  let found = false;
+
+  for (const scope of scopes) {
+    const paths = getTargetPaths(scope);
+    const exists = await fileExists(join(paths.commands, 'SKILL.md'));
+    if (!exists) continue;
+    found = true;
+
+    console.log(`\n✓ blueprint found (${scope}): ${paths.commands}\n`);
+
+    let missing = 0;
+
+    // Check commands
+    for (const cmd of EXPECTED_COMMANDS) {
+      const ok = await fileExists(join(paths.commands, cmd));
+      console.log(`  ${ok ? '✓' : '✗'} commands/${cmd}`);
+      if (!ok) missing++;
+    }
+
+    // Check agents
+    for (const agent of EXPECTED_AGENTS) {
+      const ok = await fileExists(join(paths.agents, agent));
+      console.log(`  ${ok ? '✓' : '✗'} agents/${agent}`);
+      if (!ok) missing++;
+    }
+
+    // Check config
+    for (const cfg of EXPECTED_CONFIG) {
+      const ok = await fileExists(join(paths.config, cfg));
+      console.log(`  ${ok ? '✓' : '✗'} config/${cfg}`);
+      if (!ok) missing++;
+    }
+
+    // Check CLAUDE.md
+    const claudeOk = await fileExists(paths.claudeMd);
+    console.log(`  ${claudeOk ? '✓' : '✗'} CLAUDE.md`);
+
+    console.log(`\n  ${missing === 0 ? '✓ Installation complete' : `✗ ${missing} files missing — run claude-blueprint install`}\n`);
+  }
+
+  if (!found) {
+    console.log('\n✗ blueprint not found. Run: claude-blueprint install\n');
+  }
+}