attacca-forge 0.5.0

package/plugins/attacca-forge/skills/web-fork-strategic-briefing/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: web-fork-strategic-briefing
+description: >
+  Produces a concise strategic briefing for leadership on how the agent web fork affects a
+  specific industry, company, or competitive landscape. Written in the language of business
+  strategy, not tech hype. Evidence-based and actionable. Triggers: "write an agent web
+  briefing", "strategic briefing on AI agents for my industry", "brief leadership on agent
+  web", "executive briefing on agent infrastructure", "how does the agent web affect my
+  industry", "web fork impact analysis", "agent strategy briefing for executives",
+  "board briefing on AI agents".
+---
+
+# Web Fork Strategic Briefing Generator
+
+## Role
+
+You are a strategic advisor who translates technology infrastructure shifts into business strategy. You understand the agent web fork — the emergence of a parallel web layer built for software clients (AI agents) alongside the existing human web — and can explain its implications for specific industries without resorting to jargon or hype. You write for senior leaders who are skeptical of tech trends but need to understand when an infrastructure shift is real. Your tone is direct, evidence-grounded, and actionable. You cite specific companies, protocols, and data points rather than making vague claims about "the future of AI."
+
+## Instructions
+
+1. CONTEXT GATHERING — Ask the user these questions:
+
+   a) "What industry are you in, and what's your company's role in it? (e.g., 'mid-market SaaS in healthcare,' 'DTC e-commerce in fashion,' 'B2B financial services')"
+   b) "Who is this briefing for? (e.g., CEO, board of directors, investment committee, product leadership team) — and what decision does it need to inform? (e.g., 'whether to invest in agent-ready infrastructure this year,' 'how to respond to a competitor's agent strategy,' 'whether this is real or hype')"
+   c) "What's your audience's current understanding of AI agents? (e.g., 'they've seen ChatGPT but don't understand agents,' 'they're technically sophisticated,' 'they're skeptical of AI hype after previous overpromises')"
+   d) "Are there any specific competitive threats or opportunities you're already aware of that I should address? (e.g., 'a competitor just launched an API for agent access,' 'our customers are asking about AI purchasing')"
+
+2. BRIEFING CONSTRUCTION — Build the briefing with these sections:
+
+   **EXECUTIVE SUMMARY** (3-4 sentences): What's happening, why it matters for this industry, and the one thing the reader needs to understand.
+
+   **WHAT'S HAPPENING** (1 page max): The agent web fork explained for this specific audience. Use the mobile web analogy from the article — the audience will understand it. Reference specific infrastructure moves (Coinbase Agentic Wallets, Stripe ACS, Cloudflare Markdown for Agents, OpenAI Skills/Shell) but explain them in terms of what they enable, not how they work technically. Ground claims in data: 13,000 agent wallets registered in 24 hours, $12B in Polymarket volume, Stripe retraining Radar from scratch.
+
+   **INDUSTRY IMPACT** (1 page): How specifically this affects the user's industry. Map each infrastructure layer to a concrete industry implication:
+   - How agent payments change purchasing in this industry
+   - How agent-readable content changes discovery and access
+   - How agent search changes competitive dynamics
+   - How agent execution changes service delivery
+   - How agent economics change the cost structure
+
+   **COMPETITIVE IMPLICATIONS**: Who benefits, who's threatened, what new entrants become possible. Use the article's framework: businesses that couldn't exist on the human web (like Uber couldn't exist on the desktop web) will emerge on the agent web. What do those businesses look like in this industry?
+
+   **THE HONEST ASSESSMENT**: Where on the hype-to-reality spectrum is this for the user's specific industry? Use the domain accuracy framework: is this industry in the high-accuracy zone (structured, data-driven — agents will impact it fast) or the low-accuracy zone (cultural, aesthetic — agents will take much longer)? What's the realistic timeline?
+
+   **RECOMMENDED POSTURE**: One of four strategic postures with specific actions:
+   - **Lead**: Build agent-native infrastructure now. First-mover advantage is real.
+   - **Fast follow**: Monitor, prepare technical foundation, deploy when standards stabilize.
+   - **Selective engagement**: Automate specific high-accuracy subtasks, keep core human-driven.
+   - **Watch and wait**: This doesn't affect your industry yet. Revisit in 12-18 months.
+
+   **THREE THINGS TO DO THIS QUARTER**: Regardless of posture, three specific actions.
+
+## Output
+
+Format as a clean strategic briefing document. Use headers, short paragraphs, and bullet points. No more than 3 pages equivalent. Include a one-paragraph "Bottom Line" at the very top that a busy executive can read in 30 seconds and get the key message.
+
+Every claim must be grounded in a specific reference point (company, data point, protocol, or market event). No sentences like "AI is transforming everything" or "the future is autonomous." Instead: "Stripe rebuilt its entire fraud detection system because agent traffic doesn't exhibit human behavioral signals — that's a $50B+ company acknowledging that agent clients are fundamentally different from human clients."
+
+## Guardrails
+
+- Match the language and framing to the audience the user described. A board briefing for a healthcare company reads very differently from a product strategy doc for a DTC brand.
+- If the user's industry is in a low-accuracy domain for agents (creative, cultural, relationship-driven), do NOT oversell the impact. The honest answer might be "this matters less for you than the headlines suggest, but here's the narrow slice where it does matter."
+- Do not use the word "transformative," "revolutionary," "paradigm shift," or "game-changing." Show the impact through specifics, not adjectives.
+- Include the security dimension. Every briefing should acknowledge that the same infrastructure that enables agent capability also enables agent-driven attacks, fraud, and failure modes. Leaders need to understand both sides.
+- If you don't have enough information about the user's industry to make specific claims, ask follow-up questions rather than generating vague generalities.
+- Distinguish between what is live in production today versus what is announced/planned/theoretical. Label each clearly.

package/src/commands/help.js

@@ -0,0 +1,44 @@
+// =============================================================================
+// attacca-forge help — CLI help (delegates to forge-help skill in Claude Code)
+// =============================================================================
+
+export default async function help({ cwd }) {
+  console.log(`
+  Attacca Forge — Spec-Driven AI Development Toolkit
+  ====================================================
+
+  Commands:
+    init        Set up a new project (.attacca/ config + context)
+    install     Install skills into Claude Code plugin directory
+    status      Show current pipeline phase, artifacts, and next steps
+    help        Show this help message
+
+  The 8-Phase Pipeline:
+    IDEA        Capture intent, classify trust tier
+    DISCOVER    Map existing codebase (brownfield only)
+    SPEC        Write behavioral specification + intent contract
+    BUILD       Execute implementation on deterministic rails
+    TEST        Factorial stress testing against scenarios
+    CERTIFY     Human sign-off (tier-appropriate)
+    DEPLOY      Production deployment with gates
+    MAINTAIN    Continuous flywheel + drift detection
+
+  Core Skills (invoke in Claude Code):
+    /spec-architect       Full spec with intent contracts + eval scenarios
+    /spec-writer          Streamlined spec (no intent, faster)
+    /stress-test          22 variation types × 4 failure modes
+    /intent-spec          Agent intent specification + Klarna checklist
+    /intent-audit         Organizational AI maturity audit
+    /codebase-discovery   Brownfield behavioral snapshot
+    /build-orchestrator   Build pipeline with 4-layer eval stack
+    /forge-help           "What should I do next?" (phase-aware)
+    /forge-start          IDEA phase onboarding
+
+  Getting Started:
+    1. npx attacca-forge init          Set up your project
+    2. npx attacca-forge install       Install skills to Claude Code
+    3. Open Claude Code and say:       "help me start"
+
+  Docs: https://github.com/attacca-ai/attacca-forge
+`);
+}

package/src/commands/init.js

@@ -0,0 +1,121 @@
+// =============================================================================
+// attacca-forge init — Interactive project setup wizard
+// =============================================================================
+
+import { basename } from 'node:path';
+import { ask, choose } from '../utils/prompt.js';
+import { isInitialized, writeConfig, writeContext } from '../utils/context.js';
+
+export default async function init({ args, cwd }) {
+  console.log('\n  Attacca Forge — Project Setup');
+  console.log('  ==============================\n');
+
+  // Check if already initialized
+  if (isInitialized(cwd)) {
+    const proceed = await ask('Project already initialized. Reinitialize? (y/N)', 'N');
+    if (proceed.toLowerCase() !== 'y') {
+      console.log('\n  Aborted.\n');
+      return;
+    }
+  }
+
+  // 1. Project name
+  const defaultName = args[0] || basename(cwd);
+  const name = await ask('Project name', defaultName);
+
+  // 2. Greenfield or Brownfield
+  const type = await choose('What kind of project?', [
+    {
+      label: 'Greenfield — building from scratch',
+      hint: 'No existing codebase. Starting from an idea.',
+      value: 'greenfield',
+    },
+    {
+      label: 'Brownfield — changing existing code',
+      hint: 'There is a codebase. You need to modify or extend it.',
+      value: 'brownfield',
+    },
+  ]);
+
+  // 3. Trust Tier
+  const tier = await choose('What happens if this system gets it wrong?', [
+    {
+      label: 'Tier 1 — Nothing bad happens',
+      hint: 'Hobby project, internal tool, prototype. Errors are annoying, not harmful.',
+      value: '1',
+    },
+    {
+      label: 'Tier 2 — We lose time or money',
+      hint: 'SaaS product, client deliverable, business tool. Errors cost real resources.',
+      value: '2',
+    },
+    {
+      label: 'Tier 3 — Legal, financial, or reputational risk',
+      hint: 'Compliance, financial decisions, public-facing. Errors have serious consequences.',
+      value: '3',
+    },
+    {
+      label: 'Tier 4 — Irreversible harm',
+      hint: 'Healthcare, safety-critical, regulatory. Errors can cause physical or legal harm.',
+      value: '4',
+    },
+  ]);
+
+  // 4. Experience level
+  const level = await choose('Your experience with AI-assisted development?', [
+    {
+      label: 'New — explain everything',
+      hint: 'First time using AI for development. Show me the ropes.',
+      value: 'new',
+    },
+    {
+      label: 'Comfortable — explain decisions, not basics',
+      hint: 'Used AI tools before. Know the workflow. Want methodology guidance.',
+      value: 'comfortable',
+    },
+    {
+      label: 'Expert — terse, just the framework',
+      hint: 'Deep experience. Skip explanations. Give me the structure.',
+      value: 'expert',
+    },
+  ]);
+
+  // Write config
+  const now = new Date().toISOString().split('T')[0];
+  const config = {
+    project: { name, type, tier, level, created: now },
+    phase: { current: 'IDEA' },
+    artifacts: { completed: [] },
+  };
+
+  writeConfig(cwd, config);
+
+  // Write initial context
+  const nextStep = type === 'brownfield'
+    ? 'Start with codebase discovery to map the existing system.\nInvoke: "discover this codebase" or /codebase-discovery'
+    : 'Start with the IDEA phase to capture your intent.\nInvoke: "help me start" or /forge-start';
+
+  writeContext(cwd, config, 'IDEA', [], [], nextStep);
+
+  // Summary
+  console.log('\n  ✓ Project initialized\n');
+  console.log(`    Name:       ${name}`);
+  console.log(`    Type:       ${type}`);
+  console.log(`    Trust Tier: ${tier}`);
+  console.log(`    Level:      ${level}`);
+  console.log(`    Config:     .attacca/config.yaml`);
+  console.log(`    Context:    .attacca/context.md`);
+  console.log('');
+
+  if (type === 'brownfield') {
+    console.log('  Next step: Run codebase discovery');
+    console.log('  In Claude Code, say: "discover this codebase" or /codebase-discovery');
+  } else {
+    console.log('  Next step: Capture your idea');
+    console.log('  In Claude Code, say: "help me start" or /forge-start');
+  }
+
+  console.log('');
+  console.log('  Run `attacca-forge status` anytime to see where you are.');
+  console.log('');
+}

package/src/commands/install.js

@@ -0,0 +1,77 @@
+// =============================================================================
+// attacca-forge install — Install skills into Claude Code plugin directory
+// =============================================================================
+
+import { cpSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { getClaudeDir, getPluginDir, isClaudeInstalled } from '../utils/detect-claude.js';
+
+export default async function install({ args, cwd, rootDir }) {
+  console.log('\n  Attacca Forge — Install Skills');
+  console.log('  ===============================\n');
+
+  // Check Claude Code
+  if (!isClaudeInstalled()) {
+    console.log('  ✗ Claude Code not found (~/.claude directory missing)');
+    console.log('');
+    console.log('  Install Claude Code first: https://claude.ai/claude-code');
+    console.log('  Then run this command again.');
+    console.log('');
+    process.exit(1);
+  }
+
+  console.log('  ✓ Claude Code detected');
+
+  // Source plugin directory (shipped with this package)
+  const sourcePlugin = join(rootDir, 'plugins', 'attacca-forge');
+  if (!existsSync(sourcePlugin)) {
+    console.error('  ✗ Plugin source not found. Package may be corrupted.');
+    process.exit(1);
+  }
+
+  // Target plugin directory
+  const targetDir = getPluginDir();
+  const localDir = join(getClaudeDir(), 'plugins', 'local');
+
+  // Create directories
+  if (!existsSync(localDir)) mkdirSync(localDir, { recursive: true });
+
+  // Copy plugin files
+  const existed = existsSync(targetDir);
+  cpSync(sourcePlugin, targetDir, { recursive: true, force: true });
+
+  // Also copy root marketplace plugin.json
+  const rootPluginJson = join(rootDir, '.claude-plugin');
+  const targetRootPlugin = join(getClaudeDir(), 'plugins', 'local', 'attacca-forge-root', '.claude-plugin');
+  if (existsSync(rootPluginJson)) {
+    mkdirSync(join(getClaudeDir(), 'plugins', 'local', 'attacca-forge-root'), { recursive: true });
+    cpSync(rootPluginJson, targetRootPlugin, { recursive: true, force: true });
+  }
+
+  // Count skills
+  const skillsDir = join(targetDir, 'skills');
+  let skillCount = 0;
+  if (existsSync(skillsDir)) {
+    const { readdirSync } = await import('node:fs');
+    skillCount = readdirSync(skillsDir).filter((f) => {
+      return existsSync(join(skillsDir, f, 'SKILL.md'));
+    }).length;
+  }
+
+  console.log(`  ✓ ${existed ? 'Updated' : 'Installed'} ${skillCount} skills to Claude Code`);
+  console.log(`    Location: ${targetDir}`);
+  console.log('');
+  console.log('  Restart Claude Code to load the new skills.');
+  console.log('');
+  console.log('  Available skills:');
+  console.log('    /spec-architect      Full behavioral spec with intent contracts');
+  console.log('    /spec-writer         Streamlined spec (no intent layer)');
+  console.log('    /stress-test         Factorial stress testing (22 variation types)');
+  console.log('    /intent-spec         Agent intent specification');
+  console.log('    /intent-audit        Organizational AI maturity audit');
+  console.log('    /codebase-discovery  Brownfield codebase discovery');
+  console.log('    /build-orchestrator  Build pipeline with 4-layer eval stack');
+  console.log('    /forge-help          Phase-aware guidance ("what\'s next?")');
+  console.log('    /forge-start         IDEA phase onboarding');
+  console.log('');
+}

package/src/commands/status.js

@@ -0,0 +1,87 @@
+// =============================================================================
+// attacca-forge status — Show current pipeline phase and next steps
+// =============================================================================
+
+import { readConfig, readContext, isInitialized } from '../utils/context.js';
+
+const PIPELINE = ['IDEA', 'DISCOVER', 'SPEC', 'BUILD', 'TEST', 'CERTIFY', 'DEPLOY', 'MAINTAIN'];
+
+const PHASE_SKILLS = {
+  IDEA: { skill: 'forge-start', desc: 'Capture your idea and classify risk' },
+  DISCOVER: { skill: 'codebase-discovery', desc: 'Map the existing codebase (brownfield only)' },
+  SPEC: { skill: 'spec-architect', desc: 'Write behavioral specification with intent contract' },
+  BUILD: { skill: 'build-orchestrator', desc: 'Execute implementation on deterministic rails' },
+  TEST: { skill: 'stress-test', desc: 'Run factorial stress testing against scenarios' },
+  CERTIFY: { skill: null, desc: 'Human sign-off (tier-appropriate review)' },
+  DEPLOY: { skill: 'build-orchestrator', desc: 'Production deployment with gates' },
+  MAINTAIN: { skill: null, desc: 'Continuous flywheel + drift detection' },
+};
+
+export default async function status({ cwd }) {
+  console.log('\n  Attacca Forge — Project Status');
+  console.log('  ===============================\n');
+
+  if (!isInitialized(cwd)) {
+    console.log('  No project initialized in this directory.');
+    console.log('  Run: npx attacca-forge init\n');
+    return;
+  }
+
+  const config = readConfig(cwd);
+  if (!config) {
+    console.log('  Config file corrupted. Reinitialize with: npx attacca-forge init\n');
+    return;
+  }
+
+  const { project, phase, artifacts } = config;
+  const currentPhase = phase?.current || 'IDEA';
+  const currentIdx = PIPELINE.indexOf(currentPhase);
+
+  console.log(`  Project:    ${project.name}`);
+  console.log(`  Type:       ${project.type}`);
+  console.log(`  Trust Tier: ${project.tier}`);
+  console.log(`  Level:      ${project.level}`);
+  console.log('');
+
+  // Pipeline visualization
+  console.log('  Pipeline:');
+  console.log('');
+  for (let i = 0; i < PIPELINE.length; i++) {
+    const p = PIPELINE[i];
+    const info = PHASE_SKILLS[p];
+
+    // Skip DISCOVER for greenfield
+    if (p === 'DISCOVER' && project.type === 'greenfield') continue;
+
+    let marker;
+    if (i < currentIdx) marker = '  ✓';
+    else if (i === currentIdx) marker = '  ▸';
+    else marker = '   ';
+
+    const line = `${marker} ${p.padEnd(10)} ${info.desc}`;
+    console.log(line);
+  }
+
+  console.log('');
+
+  // Next step
+  const phaseInfo = PHASE_SKILLS[currentPhase];
+  if (phaseInfo?.skill) {
+    console.log(`  Next: /${phaseInfo.skill}`);
+    console.log(`        ${phaseInfo.desc}`);
+  } else if (currentPhase === 'CERTIFY') {
+    console.log(`  Next: Human review required (Tier ${project.tier})`);
+  } else if (currentPhase === 'MAINTAIN') {
+    console.log('  System is in production. Monitoring for drift.');
+  }
+
+  // Artifacts
+  const completed = artifacts?.completed || [];
+  if (completed.length > 0) {
+    console.log('');
+    console.log('  Artifacts:');
+    completed.forEach((a) => console.log(`    - ${a}`));
+  }
+
+  console.log('');
+}

package/src/utils/context.js

@@ -0,0 +1,141 @@
+// =============================================================================
+// .attacca/ context management — read/write project state
+// =============================================================================
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const ATTACCA_DIR = '.attacca';
+const CONFIG_FILE = 'config.yaml';
+const CONTEXT_FILE = 'context.md';
+
+export function getAttaccaDir(cwd) {
+  return join(cwd, ATTACCA_DIR);
+}
+
+export function isInitialized(cwd) {
+  return existsSync(join(cwd, ATTACCA_DIR, CONFIG_FILE));
+}
+
+export function ensureDir(cwd) {
+  const dir = getAttaccaDir(cwd);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const artifacts = join(dir, 'artifacts');
+  if (!existsSync(artifacts)) mkdirSync(artifacts, { recursive: true });
+  return dir;
+}
+
+export function writeConfig(cwd, config) {
+  const dir = ensureDir(cwd);
+  const yaml = configToYaml(config);
+  writeFileSync(join(dir, CONFIG_FILE), yaml, 'utf-8');
+}
+
+export function readConfig(cwd) {
+  const file = join(cwd, ATTACCA_DIR, CONFIG_FILE);
+  if (!existsSync(file)) return null;
+  return yamlToConfig(readFileSync(file, 'utf-8'));
+}
+
+export function writeContext(cwd, config, phase, completedPhases, artifacts, nextStep) {
+  const dir = ensureDir(cwd);
+  const now = new Date().toISOString().split('T')[0];
+
+  const phases = completedPhases
+    .map((p) => `- [x] ${p.name} (${p.date}) — ${p.summary}`)
+    .join('\n');
+
+  const arts = artifacts.length > 0
+    ? artifacts.map((a) => `- \`${a.path}\` — ${a.description}`).join('\n')
+    : '_None yet_';
+
+  const content = `# Project Context — ${config.project.name}
+
+## Current Phase: ${phase}
+## Trust Tier: ${config.project.tier}
+## Type: ${config.project.type}
+## Experience: ${config.project.level}
+
+## Completed Phases
+${phases || '_None yet — run forge-start to begin_'}
+
+## Artifacts Generated
+${arts}
+
+## Next Step
+${nextStep}
+`;
+
+  writeFileSync(join(dir, CONTEXT_FILE), content, 'utf-8');
+}
+
+export function readContext(cwd) {
+  const file = join(cwd, ATTACCA_DIR, CONTEXT_FILE);
+  if (!existsSync(file)) return null;
+  return readFileSync(file, 'utf-8');
+}
+
+// Minimal YAML serializer (no dependencies)
+function configToYaml(config) {
+  const lines = [];
+  for (const [section, values] of Object.entries(config)) {
+    lines.push(`${section}:`);
+    if (typeof values === 'object' && values !== null) {
+      for (const [key, val] of Object.entries(values)) {
+        if (Array.isArray(val)) {
+          lines.push(`  ${key}:`);
+          val.forEach((item) => lines.push(`    - ${item}`));
+        } else {
+          lines.push(`  ${key}: ${val}`);
+        }
+      }
+    } else {
+      lines.push(`  ${values}`);
+    }
+  }
+  return lines.join('\n') + '\n';
+}
+
+// Minimal YAML parser (handles our flat config only)
+function yamlToConfig(yaml) {
+  const config = {};
+  let currentSection = null;
+  let currentKey = null;
+
+  for (const line of yaml.split('\n')) {
+    if (!line.trim() || line.trim().startsWith('#')) continue;
+
+    if (!line.startsWith(' ') && line.endsWith(':')) {
+      currentSection = line.slice(0, -1).trim();
+      config[currentSection] = {};
+      currentKey = null;
+    } else if (line.startsWith('  ') && !line.startsWith('    ')) {
+      const trimmed = line.trim();
+      if (trimmed.startsWith('- ')) {
+        if (currentKey && currentSection) {
+          if (!Array.isArray(config[currentSection][currentKey])) {
+            config[currentSection][currentKey] = [];
+          }
+          config[currentSection][currentKey].push(trimmed.slice(2));
+        }
+      } else if (trimmed.includes(': ')) {
+        const colonIdx = trimmed.indexOf(': ');
+        currentKey = trimmed.slice(0, colonIdx);
+        const val = trimmed.slice(colonIdx + 2);
+        if (currentSection) config[currentSection][currentKey] = val;
+      } else if (trimmed.endsWith(':')) {
+        currentKey = trimmed.slice(0, -1);
+        if (currentSection) config[currentSection][currentKey] = [];
+      }
+    } else if (line.startsWith('    ') && line.trim().startsWith('- ')) {
+      if (currentKey && currentSection) {
+        if (!Array.isArray(config[currentSection][currentKey])) {
+          config[currentSection][currentKey] = [];
+        }
+        config[currentSection][currentKey].push(line.trim().slice(2));
+      }
+    }
+  }
+
+  return config;
+}

package/src/utils/detect-claude.js

@@ -0,0 +1,23 @@
+// =============================================================================
+// Detect Claude Code installation and plugin directories
+// =============================================================================
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+export function getClaudeDir() {
+  return join(homedir(), '.claude');
+}
+
+export function getPluginDir() {
+  return join(getClaudeDir(), 'plugins', 'local', 'attacca-forge');
+}
+
+export function isClaudeInstalled() {
+  return existsSync(getClaudeDir());
+}
+
+export function isForgeInstalled() {
+  return existsSync(getPluginDir());
+}

package/src/utils/prompt.js

@@ -0,0 +1,44 @@
+// =============================================================================
+// Minimal interactive prompt utility — zero dependencies
+// =============================================================================
+
+import { createInterface } from 'node:readline';
+
+const rl = () =>
+  createInterface({ input: process.stdin, output: process.stdout });
+
+export async function ask(question, defaultValue) {
+  const r = rl();
+  const suffix = defaultValue ? ` (${defaultValue})` : '';
+  return new Promise((resolve) => {
+    r.question(`  ${question}${suffix}: `, (answer) => {
+      r.close();
+      resolve(answer.trim() || defaultValue || '');
+    });
+  });
+}
+
+export async function choose(question, options) {
+  console.log(`\n  ${question}\n`);
+  options.forEach((opt, i) => {
+    console.log(`    ${i + 1}. ${opt.label}`);
+    if (opt.hint) console.log(`       ${opt.hint}`);
+  });
+  console.log('');
+
+  const r = rl();
+  return new Promise((resolve) => {
+    const prompt = () => {
+      r.question(`  Choose [1-${options.length}]: `, (answer) => {
+        const idx = parseInt(answer, 10) - 1;
+        if (idx >= 0 && idx < options.length) {
+          r.close();
+          resolve(options[idx].value);
+        } else {
+          prompt();
+        }
+      });
+    };
+    prompt();
+  });
+}