ai-dev-setup 1.0.0

package/src/core/vendors.js

@@ -0,0 +1,354 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { assertSafeGitRef } from './git-ref.js';
+import { createReadStream } from 'node:fs';
+import { createInterface } from 'node:readline';
+
+export const SUPERPOWERS_GIT_URL = 'https://github.com/obra/superpowers.git';
+export const AGENCY_GIT_URL = 'https://github.com/msitarzewski/agency-agents.git';
+
+export const VENDOR_SUPERPOWERS = path.join('vendor', 'superpowers');
+export const VENDOR_AGENCY = path.join('vendor', 'agency-agents');
+
+/** Same division roots as agency-agents `scripts/install.sh` install_claude_code */
+export const AGENCY_CLAUDE_DIVISIONS = [
+  'academic',
+  'design',
+  'engineering',
+  'game-development',
+  'marketing',
+  'paid-media',
+  'sales',
+  'product',
+  'project-management',
+  'testing',
+  'support',
+  'spatial-computing',
+  'specialized',
+];
+
+/**
+ * @param {string} command
+ * @param {string[]} args
+ * @param {{ cwd?: string }} [opts]
+ */
+export function runProcess(command, args, opts = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: opts.cwd,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout?.on('data', (c) => {
+      stdout += c;
+    });
+    child.stderr?.on('data', (c) => {
+      stderr += c;
+    });
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve({ stdout, stderr });
+      } else {
+        reject(
+          new Error(
+            `${command} ${args.join(' ')} exited with code ${code}\n${stderr || stdout}`.trim(),
+          ),
+        );
+      }
+    });
+  });
+}
+
+async function assertGitAvailable() {
+  try {
+    await runProcess('git', ['--version']);
+  } catch {
+    throw new Error('git is required on PATH to vendor Superpowers and Agency Agents.');
+  }
+}
+
+async function assertBashAvailable() {
+  try {
+    await runProcess('bash', ['--version']);
+  } catch {
+    throw new Error('bash is required on PATH to run vendor/agency-agents/scripts/convert.sh.');
+  }
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} relDir
+ * @param {string} url
+ * @param {string} ref
+ * @param {boolean} force
+ */
+async function gitShallowClone(cwd, relDir, url, ref, force) {
+  const target = path.join(cwd, relDir);
+  try {
+    await fs.access(target);
+    if (force) {
+      await fs.rm(target, { recursive: true, force: true });
+    } else {
+      return { skipped: true, path: relDir };
+    }
+  } catch {
+    /* missing */
+  }
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  await runProcess('git', ['clone', '--depth', '1', '--branch', ref, url, target], { cwd });
+  return { skipped: false, path: relDir };
+}
+
+/**
+ * Rewrite Superpowers .cursor-plugin paths for workspace-root install.
+ * @param {Record<string, unknown>} plugin
+ * @param {string} posixPrefix e.g. ./vendor/superpowers/
+ */
+export function rewriteSuperpowersCursorPlugin(plugin, posixPrefix) {
+  const out = { ...plugin };
+  for (const key of ['skills', 'agents', 'commands', 'hooks']) {
+    const v = out[key];
+    if (typeof v === 'string' && v.startsWith('./')) {
+      const rest = v.slice(2);
+      out[key] = `${posixPrefix}${rest}`.replace(/\/{2,}/g, '/');
+    }
+  }
+  return out;
+}
+
+/**
+ * @param {string} filePath
+ */
+export async function markdownStartsWithFrontmatter(filePath) {
+  const rl = createInterface({ input: createReadStream(filePath), crlfDelay: Infinity });
+  try {
+    for await (const line of rl) {
+      return line.trimStart().startsWith('---');
+    }
+  } finally {
+    rl.close();
+  }
+  return false;
+}
+
+/**
+ * @param {string} agencyRepoRoot vendor/agency-agents absolute
+ * @param {string} projectRoot
+ * @param {boolean} force
+ */
+export async function copyAgencyClaudeAgents(agencyRepoRoot, projectRoot, force) {
+  const dest = path.join(projectRoot, '.claude', 'agents');
+  await fs.mkdir(dest, { recursive: true });
+  let count = 0;
+  for (const division of AGENCY_CLAUDE_DIVISIONS) {
+    const divPath = path.join(agencyRepoRoot, division);
+    let stat;
+    try {
+      stat = await fs.stat(divPath);
+    } catch {
+      continue;
+    }
+    if (!stat.isDirectory()) continue;
+    count += await copyMarkdownAgentsFromTree(divPath, dest, force);
+  }
+  return count;
+}
+
+/**
+ * @param {string} dir
+ * @param {string} destDir
+ * @param {boolean} force
+ */
+async function copyMarkdownAgentsFromTree(dir, destDir, force) {
+  let n = 0;
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  for (const ent of entries) {
+    const full = path.join(dir, ent.name);
+    if (ent.isDirectory()) {
+      n += await copyMarkdownAgentsFromTree(full, destDir, force);
+    } else if (ent.isFile() && ent.name.endsWith('.md')) {
+      if (!(await markdownStartsWithFrontmatter(full))) continue;
+      const destFile = path.join(destDir, ent.name);
+      if (!force) {
+        try {
+          await fs.access(destFile);
+          continue;
+        } catch {
+          /* ok */
+        }
+      }
+      await fs.copyFile(full, destFile);
+      n++;
+    }
+  }
+  return n;
+}
+
+/**
+ * @param {string} integrationsRulesDir
+ * @param {string} projectRulesDir .cursor/rules
+ * @param {boolean} force overwrite agency-*.mdc
+ */
+export async function copyAgencyCursorRules(integrationsRulesDir, projectRulesDir, force) {
+  let count = 0;
+  try {
+    await fs.access(integrationsRulesDir);
+  } catch {
+    return 0;
+  }
+  const files = await fs.readdir(integrationsRulesDir);
+  for (const name of files) {
+    if (!name.endsWith('.mdc')) continue;
+    const prefixed = name.startsWith('agency-') ? name : `agency-${name}`;
+    const src = path.join(integrationsRulesDir, name);
+    const dest = path.join(projectRulesDir, prefixed);
+    if (!force) {
+      try {
+        await fs.access(dest);
+        continue;
+      } catch {
+        /* copy */
+      }
+    }
+    await fs.mkdir(projectRulesDir, { recursive: true });
+    await fs.copyFile(src, dest);
+    count++;
+  }
+  return count;
+}
+
+/**
+ * @param {string} skillsRoot vendor/superpowers/skills
+ * @param {string} destRoot .claude/skills
+ * @param {boolean} force
+ */
+export async function copySuperpowersSkills(skillsRoot, destRoot, force) {
+  let count = 0;
+  let rootStat;
+  try {
+    rootStat = await fs.stat(skillsRoot);
+  } catch {
+    throw new Error(`Superpowers skills directory missing: ${skillsRoot}`);
+  }
+  if (!rootStat.isDirectory()) {
+    throw new Error(`Superpowers skills path is not a directory: ${skillsRoot}`);
+  }
+  const skillDirs = await fs.readdir(skillsRoot, { withFileTypes: true });
+  for (const ent of skillDirs) {
+    if (!ent.isDirectory()) continue;
+    const src = path.join(skillsRoot, ent.name);
+    const dest = path.join(destRoot, ent.name);
+    if (!force) {
+      try {
+        await fs.access(dest);
+        continue;
+      } catch {
+        /* copy */
+      }
+    } else {
+      await fs.rm(dest, { recursive: true, force: true });
+    }
+    await fs.cp(src, dest, { recursive: true });
+    count++;
+  }
+  return count;
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {string} superpowersRoot absolute vendor/superpowers
+ */
+export async function writeSuperpowersCursorPluginFile(projectRoot, superpowersRoot) {
+  const pluginSrc = path.join(superpowersRoot, '.cursor-plugin', 'plugin.json');
+  const raw = await fs.readFile(pluginSrc, 'utf8');
+  const plugin = JSON.parse(raw);
+  const rewritten = rewriteSuperpowersCursorPlugin(plugin, './vendor/superpowers/');
+  const hooksRel = rewritten.hooks;
+  if (typeof hooksRel === 'string') {
+    const rel = hooksRel.replace(/^\.\//, '');
+    const hooksAbs = path.join(projectRoot, rel);
+    try {
+      await fs.access(hooksAbs);
+    } catch {
+      throw new Error(`Superpowers Cursor hooks file missing after clone: ${hooksRel}`);
+    }
+  }
+  const outDir = path.join(projectRoot, '.cursor-plugin');
+  await fs.mkdir(outDir, { recursive: true });
+  await fs.writeFile(path.join(outDir, 'plugin.json'), `${JSON.stringify(rewritten, null, 2)}\n`, 'utf8');
+}
+
+/**
+ * @param {object} options
+ * @param {string[]} options.platformKeys
+ * @param {boolean} options.force
+ * @param {string} options.superpowersRef
+ * @param {string} options.agencyRef
+ * @returns {Promise<string[]>} log lines
+ */
+export async function installVendors(projectRoot, options) {
+  const { platformKeys, force } = options;
+  const superpowersRef = assertSafeGitRef(
+    options.superpowersRef != null && options.superpowersRef !== ''
+      ? String(options.superpowersRef)
+      : 'main',
+  );
+  const agencyRef = assertSafeGitRef(
+    options.agencyRef != null && options.agencyRef !== '' ? String(options.agencyRef) : 'main',
+  );
+  const wantClaude = platformKeys.includes('claude');
+  const wantCursor = platformKeys.includes('cursor');
+  const lines = [];
+
+  await assertGitAvailable();
+
+  const spRel = VENDOR_SUPERPOWERS;
+  const agRel = VENDOR_AGENCY;
+
+  const sp = await gitShallowClone(projectRoot, spRel, SUPERPOWERS_GIT_URL, superpowersRef, force);
+  lines.push(sp.skipped ? `${sp.path} (already present, skipped clone — use --force to refresh)` : `+ ${sp.path} (cloned)`);
+
+  const ag = await gitShallowClone(projectRoot, agRel, AGENCY_GIT_URL, agencyRef, force);
+  lines.push(ag.skipped ? `${ag.path} (already present, skipped clone — use --force to refresh)` : `+ ${ag.path} (cloned)`);
+
+  const superAbs = path.join(projectRoot, spRel);
+  const agencyAbs = path.join(projectRoot, agRel);
+
+  if (wantCursor) {
+    await writeSuperpowersCursorPluginFile(projectRoot, superAbs);
+    lines.push('+ .cursor-plugin/plugin.json (Superpowers paths → vendor/superpowers)');
+  }
+
+  if (wantClaude) {
+    const n = await copySuperpowersSkills(path.join(superAbs, 'skills'), path.join(projectRoot, '.claude', 'skills'), force);
+    lines.push(`+ .claude/skills (${n} skill trees from Superpowers)`);
+  }
+
+  if (wantCursor) {
+    await assertBashAvailable();
+    lines.push('… running vendor/agency-agents/scripts/convert.sh (may take a minute)');
+    await runProcess('bash', ['scripts/convert.sh'], { cwd: agencyAbs });
+    const rulesSrc = path.join(agencyAbs, 'integrations', 'cursor', 'rules');
+    const rulesDest = path.join(projectRoot, '.cursor', 'rules');
+    const n = await copyAgencyCursorRules(rulesSrc, rulesDest, force);
+    if (n === 0) {
+      throw new Error(
+        'Agency Cursor rules not found after convert.sh. Expected integrations/cursor/rules/*.mdc',
+      );
+    }
+    lines.push(`+ .cursor/rules (agency-*.mdc × ${n})`);
+  }
+
+  if (wantClaude) {
+    const n = await copyAgencyClaudeAgents(agencyAbs, projectRoot, force);
+    if (n === 0) {
+      throw new Error('No Agency agent markdown files were copied to .claude/agents/. Check vendor/agency-agents layout.');
+    }
+    lines.push(`+ .claude/agents (${n} agent files from Agency)`);
+  }
+
+  return lines;
+}

package/src/core/writer.js

@@ -0,0 +1,67 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+
+function isPathInsideRoot(root, target) {
+  const r = path.resolve(root);
+  const t = path.resolve(target);
+  const prefix = r.endsWith(path.sep) ? r : r + path.sep;
+  return t === r || t.startsWith(prefix);
+}
+
+/**
+ * @param {Array<{ path: string, content: string }>} files
+ * @param {{ cwd?: string, force?: boolean }} [options]
+ */
+export async function writeFiles(files, { cwd = process.cwd(), force = false } = {}) {
+  const root = path.resolve(cwd);
+  /** @type {Array<{ path: string, status: 'written'|'skipped'|'error', error?: string }>} */
+  const results = [];
+
+  for (const file of files) {
+    const target = path.resolve(root, file.path);
+    if (!isPathInsideRoot(root, target)) {
+      results.push({
+        path: file.path,
+        status: 'error',
+        error: 'Path escapes working directory',
+      });
+      continue;
+    }
+
+    try {
+      await fs.mkdir(path.dirname(target), { recursive: true });
+    } catch (err) {
+      results.push({
+        path: file.path,
+        status: 'error',
+        error: err instanceof Error ? err.message : String(err),
+      });
+      continue;
+    }
+
+    try {
+      let exists = false;
+      try {
+        await fs.access(target);
+        exists = true;
+      } catch {
+        exists = false;
+      }
+      if (exists && !force) {
+        results.push({ path: file.path, status: 'skipped' });
+        continue;
+      }
+      await fs.writeFile(target, file.content, 'utf8');
+      results.push({ path: file.path, status: 'written' });
+    } catch (err) {
+      results.push({
+        path: file.path,
+        status: 'error',
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  return results;
+}

package/src/platforms/claude-code.js

@@ -0,0 +1,33 @@
+import path from 'node:path';
+import { renderFile } from '../core/renderer.js';
+import { Platform } from './platform.js';
+import { register, TEMPLATES_DIR } from './registry.js';
+
+function tpl(rel) {
+  return path.join(TEMPLATES_DIR, rel);
+}
+
+export class ClaudeCodePlatform extends Platform {
+  constructor() {
+    super('claude', 'Claude Code');
+  }
+
+  /** @param {Record<string, unknown>} config */
+  async getFiles(config) {
+    const pairs = [
+      ['claude-code/claude.md.tmpl', 'CLAUDE.md'],
+      ['claude-code/settings.json.tmpl', '.claude/settings.json'],
+      ['claude-code/commands/kickoff.md.tmpl', '.claude/commands/kickoff.md'],
+      ['claude-code/commands/review.md.tmpl', '.claude/commands/review.md'],
+      ['claude-code/commands/ship.md.tmpl', '.claude/commands/ship.md'],
+    ];
+    const out = [];
+    for (const [rel, dest] of pairs) {
+      const content = await renderFile(tpl(rel), config);
+      out.push({ path: dest, content });
+    }
+    return out;
+  }
+}
+
+register(new ClaudeCodePlatform());

package/src/platforms/cursor.js

@@ -0,0 +1,33 @@
+import path from 'node:path';
+import { renderFile } from '../core/renderer.js';
+import { Platform } from './platform.js';
+import { register, TEMPLATES_DIR } from './registry.js';
+
+function tpl(rel) {
+  return path.join(TEMPLATES_DIR, rel);
+}
+
+export class CursorPlatform extends Platform {
+  constructor() {
+    super('cursor', 'Cursor');
+  }
+
+  /** @param {Record<string, unknown>} config */
+  async getFiles(config) {
+    const pairs = [
+      ['cursor/cursorrules.tmpl', '.cursorrules'],
+      ['cursor/rules/core-rules.mdc.tmpl', '.cursor/rules/core-rules.mdc'],
+      ['cursor/rules/workflow.mdc.tmpl', '.cursor/rules/workflow.mdc'],
+      ['cursor/rules/review.mdc.tmpl', '.cursor/rules/review.mdc'],
+      ['cursor/rules/agents.mdc.tmpl', '.cursor/rules/agents.mdc'],
+    ];
+    const out = [];
+    for (const [rel, dest] of pairs) {
+      const content = await renderFile(tpl(rel), config);
+      out.push({ path: dest, content });
+    }
+    return out;
+  }
+}
+
+register(new CursorPlatform());

package/src/platforms/platform.js

@@ -0,0 +1,18 @@
+/**
+ * Strategy base: each assistant platform implements `getFiles(config)`.
+ */
+export class Platform {
+  /**
+   * @param {string} key
+   * @param {string} label
+   */
+  constructor(key, label) {
+    this.key = key;
+    this.label = label;
+  }
+
+  /** @param {Record<string, unknown>} _config */
+  async getFiles(_config) {
+    throw new Error(`${this.key}: getFiles() not implemented`);
+  }
+}

package/src/platforms/registry.js

@@ -0,0 +1,56 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { renderFile } from '../core/renderer.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const TEMPLATES_DIR = path.join(__dirname, '..', 'templates');
+
+/** @type {Map<string, import('./platform.js').Platform>} */
+const platforms = new Map();
+
+/** @param {import('./platform.js').Platform} platform */
+export function register(platform) {
+  platforms.set(platform.key, platform);
+}
+
+/** @param {string} key */
+export function getPlatform(key) {
+  return platforms.get(key);
+}
+
+export function getAllPlatforms() {
+  return [...platforms.values()];
+}
+
+/** @param {string} rel */
+function tpl(rel) {
+  return path.join(TEMPLATES_DIR, rel);
+}
+
+/**
+ * Shared artifacts for every run (.ai/, docs/, ignore files).
+ * @param {Record<string, unknown>} config
+ */
+export async function getSharedFiles(config) {
+  /** @type {Array<{ template: string, out: string }>} */
+  const map = [
+    { template: 'shared/rules.md.tmpl', out: '.ai/rules.md' },
+    { template: 'shared/workflow.md.tmpl', out: '.ai/workflow.md' },
+    { template: 'shared/agents.md.tmpl', out: '.ai/agents.md' },
+    { template: 'shared/docs/architecture.md.tmpl', out: 'docs/ARCHITECTURE.md' },
+    { template: 'shared/docs/conventions.md.tmpl', out: 'docs/CONVENTIONS.md' },
+    { template: 'shared/docs/testing.md.tmpl', out: 'docs/TESTING-STRATEGY.md' },
+    { template: 'shared/docs/api-patterns.md.tmpl', out: 'docs/API-PATTERNS.md' },
+    { template: 'shared/docs/error-handling.md.tmpl', out: 'docs/ERROR-HANDLING.md' },
+    { template: 'shared/docs/security.md.tmpl', out: 'docs/SECURITY.md' },
+    { template: 'ignore/claudeignore.tmpl', out: '.claudeignore' },
+    { template: 'ignore/cursorignore.tmpl', out: '.cursorignore' },
+  ];
+
+  const out = [];
+  for (const { template, out: dest } of map) {
+    const content = await renderFile(tpl(template), config);
+    out.push({ path: dest, content });
+  }
+  return out;
+}

package/src/templates/claude-code/claude.md.tmpl

@@ -0,0 +1,58 @@
+# {{PROJECT_NAME}} — Claude Code
+
+## Identity
+
+| Field | Value |
+|-------|-------|
+| Language | {{LANGUAGE}} |
+| Framework | {{FRAMEWORK}} |
+| Database | {{DATABASE}} |
+
+## Core stack (required)
+
+| System | Location | Role |
+|--------|----------|------|
+| Superpowers (obra) | `vendor/superpowers/`, skills in `.claude/skills/` | Workflow engine: brainstorming → design → plans → TDD → review — use these skills for every non-trivial task |
+| Agency Agents | `vendor/agency-agents/`, agents in `.claude/agents/` | Specialist execution: pick the agent that matches the task from `.ai/agents.md` |
+
+Do not treat Superpowers or Agency as optional add-ons. If `vendor/` is missing, run `npx ai-dev-setup init` without `--skip-vendor`.
+
+## Read first (onboarding)
+
+| Order | File |
+|-------|------|
+| 1 | `.ai/rules.md` |
+| 2 | `.ai/workflow.md` |
+| 3 | `docs/ARCHITECTURE.md` (fill if empty) |
+
+Load other `docs/*` only when the task touches that area.
+
+## Operating rules
+
+- Prefer repo scripts: test `{{TEST_CMD}}`, lint `{{LINT_CMD}}`, build `{{BUILD_CMD}}`
+- Keep replies short; point to paths instead of pasting large files
+- After structural change, update `docs/ARCHITECTURE.md` in the same PR when behavior crosses modules
+- Let Superpowers skills drive phase gates; align with `.ai/workflow.md` without duplicating long prose here
+
+## Slash commands
+
+| Command | Use |
+|---------|-----|
+| `/kickoff` | New feature: scope, risks, plan |
+| `/review` | Pre-merge review checklist |
+| `/ship` | Release/merge readiness |
+
+## Docs index
+
+| Topic | Path |
+|-------|------|
+| Conventions | `docs/CONVENTIONS.md` |
+| Testing | `docs/TESTING-STRATEGY.md` |
+| API | `docs/API-PATTERNS.md` |
+| Errors | `docs/ERROR-HANDLING.md` |
+| Security | `docs/SECURITY.md` |
+
+## Out of scope for this file
+
+- Do not duplicate `.ai/rules.md`
+- Do not paste long examples—add them under `docs/` and link

package/src/templates/claude-code/commands/kickoff.md.tmpl

@@ -0,0 +1,18 @@
+# /kickoff — {{PROJECT_NAME}}
+
+## Goal
+
+Turn a feature request into a bounded plan aligned with `.ai/workflow.md`.
+
+## Steps
+
+1. Restate objective and **non-goals** (3–7 bullets)
+2. List unknowns; ask **one** blocking question if needed
+3. Propose architecture touchpoints with links to `docs/ARCHITECTURE.md` sections to update
+4. Emit a task list: each item has **path**, **change**, **verify** (`{{TEST_CMD}}` / manual check)
+
+## Output format
+
+- ### Summary
+- ### Risks
+- ### Tasks (numbered)

package/src/templates/claude-code/commands/review.md.tmpl

@@ -0,0 +1,20 @@
+# /review — {{PROJECT_NAME}}
+
+## Goal
+
+Catch correctness, safety, and maintainability issues before merge.
+
+## Checklist
+
+- [ ] Matches stated acceptance checks
+- [ ] Errors handled at boundaries per `docs/ERROR-HANDLING.md`
+- [ ] Tests updated or gap documented (`{{TEST_CMD}}`)
+- [ ] No secrets / PII in logs
+- [ ] Public API or behavior change reflected in docs
+- [ ] `{{LINT_CMD}}` clean or waivers explained inline
+
+## Output format
+
+- ### Findings (severity: high/med/low)
+- ### Suggested patches (file-scoped)
+- ### Merge verdict: approve | changes requested

package/src/templates/claude-code/commands/ship.md.tmpl

@@ -0,0 +1,19 @@
+# /ship — {{PROJECT_NAME}}
+
+## Goal
+
+Confirm release/merge readiness.
+
+## Verify
+
+- [ ] `{{LINT_CMD}}` passes
+- [ ] `{{TEST_CMD}}` passes
+- [ ] `{{BUILD_CMD}}` passes (if applicable)
+- [ ] Changelog / release notes updated when user-visible
+- [ ] Migrations or feature flags documented
+
+## Output format
+
+- ### Ship status: ready | blocked
+- ### Blockers (if any)
+- ### Rollback notes