plankit-cli 1.0.0 → 1.2.0

package/src/cli.js

@@ -1,235 +1,655 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import { spawnSync } from 'node:child_process';
 import {
-  AGENTS_MD_TEMPLATE,
-  CURSORRULES_TEMPLATE,
-  GEMINI_INSTRUCTIONS_TEMPLATE,
-  OPENCODE_COMMAND_PLAN,
-  OPENCODE_COMMAND_CLARIFY,
-  OPENCODE_COMMAND_IMPLEMENT,
-  OPENCODE_COMMAND_REVIEW,
-  OPENCODE_COMMAND_MASTER,
-  PLANKIT_SPEC_TEMPLATE
-} from './templates.js';
-
-export function runCli(args) {
-  const command = args[0];
-  const target = args[1];
-
-  switch (command) {
-    case 'init':
-      initProject();
-      break;
-    case 'plan':
-      if (!target) {
-        console.error('Error: Please specify a feature name. Example: npx plankit plan my-feature');
-        process.exit(1);
-      }
-      planFeature(target);
-      break;
-    case 'status':
-      showStatus();
-      break;
-    case 'archive':
-      if (!target) {
-        console.error('Error: Please specify a feature name. Example: npx plankit archive my-feature');
-        process.exit(1);
-      }
-      archiveFeature(target);
-      break;
-    case 'help':
-    case '--help':
-    case '-h':
-    default:
-      showHelp();
-      break;
+  assertSafeName,
+  createDefaultConfigFile,
+  ensureDir,
+  listDirectories,
+  loadConfig,
+  normalizePhases,
+  parsePhaseFlag,
+  resolveConfiguredAgent,
+  safeJoin,
+  writeManagedFile
+} from './config.js';
+import { renderList, renderTemplate, packageRoot } from './templates.js';
+import { DEFAULT_AGENT, GEMINI_SKILL_ENTRIES, getAgent, listAgents, validAgentNames } from './agents.js';
+import { bundleEntry, bundleSourceExists } from './commandBundles.js';
+
+export async function runCli(args, context = {}) {
+  const io = createIo(context);
+
+  try {
+    const parsed = parseArgs(args);
+    const command = parsed.command;
+
+    switch (command) {
+      case 'init':
+        await initProject(parsed, io);
+        break;
+      case 'plan':
+        planFeature(parsed, io);
+        break;
+      case 'clarify':
+        clarifyFeature(parsed, io);
+        break;
+      case 'implement':
+        prepareImplementation(parsed, io);
+        break;
+      case 'review':
+        reviewFeature(parsed, io);
+        break;
+      case 'status':
+        showStatus(parsed, io);
+        break;
+      case 'archive':
+        archiveFeature(parsed, io);
+        break;
+      case 'help':
+      case '--help':
+      case '-h':
+      case undefined:
+        showHelp(io);
+        break;
+      default:
+        throw new Error(`Unknown command "${command}". Run "plankit help" for usage.`);
+    }
+  } catch (error) {
+    io.stderr(`Error: ${error.message}`);
+    io.exit(1);
   }
 }
 
-function ensureDir(dirPath) {
-  if (!fs.existsSync(dirPath)) {
-    fs.mkdirSync(dirPath, { recursive: true });
+async function initProject(parsed, io) {
+  const { config, path: configPath } = loadConfig(io.cwd);
+  const options = writeOptions(parsed, config);
+  const agent = await resolveAgent(parsed, config, io, configPath);
+  const results = [];
+  const artifactsDir = safeJoin(io.cwd, config.artifactsDir);
+
+  ensureDir(path.join(artifactsDir, 'current'), options);
+  ensureDir(path.join(artifactsDir, 'archived'), options);
+
+  results.push(writeManagedFile(
+    path.join(artifactsDir, 'PLANKIT.md'),
+    renderTemplate(config, 'PLANKIT.md', { artifactsDir: config.artifactsDir }, io.cwd),
+    options
+  ));
+  results.push(writeManagedFile(path.join(artifactsDir, 'current', '.gitkeep'), '', options));
+  results.push(writeManagedFile(path.join(artifactsDir, 'archived', '.gitkeep'), '', options));
+  results.push(createDefaultConfigFile(io.cwd, options));
+
+  for (const binding of agent.bindings) {
+    results.push(writeManagedFile(
+      safeJoin(io.cwd, ...binding.dest),
+      renderTemplate(config, binding.template, { artifactsDir: config.artifactsDir, agent: agent.id }, io.cwd),
+      options
+    ));
+  }
+
+  for (const bundleName of agent.commandBundles) {
+    results.push(installCommandBundle(agent, bundleName, config, options, io));
   }
+
+  if (parsed.flags['global-gemini-skills'] && agent.id === 'gemini') {
+    results.push(...installGlobalGeminiSkills(config, options));
+  }
+
+  io.stdout(`PlanKit initialized for agent "${agent.id}".`);
+  printResults(results, io);
 }
 
-function writeFile(filePath, content) {
-  ensureDir(path.dirname(filePath));
-  fs.writeFileSync(filePath, content, 'utf8');
+function installCommandBundle(agent, bundleName, config, options, io) {
+  const entry = bundleEntry(bundleName);
+  if (!entry) {
+    return { action: 'info', path: bundleName, message: `unknown bundle for ${agent.id}` };
+  }
+  if (!bundleSourceExists(bundleName, io.cwd, config)) {
+    return {
+      action: 'info',
+      path: bundleName,
+      message: `${entry.label} for ${agent.id} not shipped yet`
+    };
+  }
+
+  if (entry.global && options.dryRun) {
+    return { action: 'info', path: bundleName, message: 'would install to user profile (dry run)' };
+  }
+
+  const targetRoot = entry.global
+    ? path.join(os.homedir(), ...entry.dest)
+    : safeJoin(io.cwd, ...entry.dest);
+
+  const sourceRoot = resolveBundleSource(entry.src, io.cwd, config);
+  ensureDir(targetRoot, options);
+  return copyBundleRecursive(sourceRoot, targetRoot, options);
 }
 
-function initProject() {
-  console.log('🚀 Initializing PlanKit Command Suite in project...');
+function resolveBundleSource(src, cwd, config) {
+  const customPath = config.templatesDir
+    ? path.resolve(cwd, config.templatesDir, src)
+    : null;
+  if (customPath && fs.existsSync(customPath)) {
+    return customPath;
+  }
+  return path.join(packageRoot, 'templates', src);
+}
+
+function copyBundleRecursive(sourceRoot, targetRoot, options) {
+  const copyResults = [];
+  const files = collectFiles(sourceRoot);
+  for (const rel of files) {
+    const srcFile = path.join(sourceRoot, rel);
+    const destFile = path.join(targetRoot, rel);
+    const rendered = renderTemplateFromFile(srcFile);
+    copyResults.push(writeManagedFile(destFile, rendered, options));
+  }
+  const wroteAny = copyResults.some((result) => result && result.action !== 'skipped' && result.action !== 'unchanged');
+  return {
+    action: wroteAny ? 'copied' : 'unchanged',
+    path: targetRoot,
+    copies: copyResults
+  };
+}
 
-  const cwd = process.cwd();
+function collectFiles(dir) {
+  const results = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...collectFiles(full).map((rel) => path.join(entry.name, rel)));
+    } else {
+      results.push(entry.name);
+    }
+  }
+  return results;
+}
+
+function renderTemplateFromFile(filePath) {
+  return fs.readFileSync(filePath, 'utf8')
+    .replace(/\{\{([a-zA-Z0-9_.-]+)\}\}/g, (_, key) => {
+      const maps = { artifactsDir: 'artifacts' };
+      return key in maps ? maps[key] : '';
+    });
+}
 
-  // 1. Artifacts directories & spec files
-  ensureDir(path.join(cwd, 'artifacts', 'current'));
-  ensureDir(path.join(cwd, 'artifacts', 'archived'));
-  writeFile(path.join(cwd, 'artifacts', 'PLANKIT.md'), PLANKIT_SPEC_TEMPLATE);
-  writeFile(path.join(cwd, 'artifacts', 'current', '.gitkeep'), '');
-  writeFile(path.join(cwd, 'artifacts', 'archived', '.gitkeep'), '');
+function planFeature(parsed, io) {
+  const featureName = parsed.positionals[0];
+  if (!featureName) {
+    throw new Error('Please specify a feature name. Example: plankit plan my-feature');
+  }
+  assertSafeName(featureName, 'feature name');
 
-  // 2. Gemini / Antigravity instructions
-  writeFile(path.join(cwd, '.gemini', 'instructions.md'), GEMINI_INSTRUCTIONS_TEMPLATE);
+  const { config } = loadConfig(io.cwd);
+  const phases = parsePhaseFlag(parsed.flags.phases) || normalizePhases(config.defaultPhases);
+  const requirements = parsed.flags.requirements || parsed.positionals.slice(1).join(' ') || 'Detailed description of the feature goal and scope.';
+  const options = writeOptions(parsed, config);
+  const featureDir = safeJoin(io.cwd, config.artifactsDir, 'current', featureName);
 
-  // 3. Cursor rules
-  writeFile(path.join(cwd, '.cursorrules'), CURSORRULES_TEMPLATE);
+  if (fs.existsSync(featureDir)) {
+    throw new Error(`Feature "${featureName}" already exists at ${path.join(config.artifactsDir, 'current', featureName)}`);
+  }
 
-  // 4. AGENTS.md
-  writeFile(path.join(cwd, 'AGENTS.md'), AGENTS_MD_TEMPLATE);
+  ensureDir(path.join(featureDir, 'phases'), options);
+  ensureDir(path.join(featureDir, 'outputs'), options);
+
+  const phaseChecklist = renderList(phases, (phase, index) => (
+    `- [ ] Phase ${index + 1}: ${phase.title} — ([Spec](phases/${phaseFileName(index + 1, phase)}))`
+  ));
+  const phaseMatrix = renderList(phases, (phase, index) => {
+    const phaseNumber = index + 1;
+    const specPath = `phases/${phaseFileName(phaseNumber, phase)}`;
+    const outputPath = `outputs/phase-${phaseNumber}-output.md`;
+    return `| Phase ${phaseNumber} | ${phase.title} | \`${specPath}\` | \`${outputPath}\` | **PENDING** |`;
+  });
+
+  const results = [];
+  results.push(writeManagedFile(
+    path.join(featureDir, 'README.md'),
+    renderTemplate(config, 'feature-readme.md', {
+      featureName,
+      requirements,
+      phaseChecklist,
+      phaseMatrix
+    }, io.cwd),
+    options
+  ));
+
+  results.push(writeManagedFile(
+    path.join(featureDir, 'plankit.json'),
+    `${JSON.stringify(createFeatureState(featureName, phases), null, 2)}\n`,
+    options
+  ));
+
+  phases.forEach((phase, index) => {
+    const phaseNumber = index + 1;
+    const tasks = phase.tasks.map((task) => `- [ ] ${task}`).join('\n');
+    results.push(writeManagedFile(
+      path.join(featureDir, 'phases', phaseFileName(phaseNumber, phase)),
+      renderTemplate(config, 'phase-spec.md', {
+        phaseNumber,
+        previousPhaseNumber: Math.max(phaseNumber - 1, 0),
+        phaseTitle: phase.title,
+        objective: phase.objective,
+        tasks
+      }, io.cwd),
+      options
+    ));
+  });
+
+  results.push(writeManagedFile(path.join(featureDir, 'outputs', '.gitkeep'), '', options));
+
+  io.stdout(`Feature "${featureName}" planned with ${phases.length} phase(s).`);
+  printResults(results, io);
+}
 
-  // 5. OpenCode command markdown files
-  const opencodeDir = path.join(cwd, '.opencode', 'commands');
-  writeFile(path.join(opencodeDir, 'plankit-plan.md'), OPENCODE_COMMAND_PLAN);
-  writeFile(path.join(opencodeDir, 'plankit-clarify.md'), OPENCODE_COMMAND_CLARIFY);
-  writeFile(path.join(opencodeDir, 'plankit-implement.md'), OPENCODE_COMMAND_IMPLEMENT);
-  writeFile(path.join(opencodeDir, 'plankit-review.md'), OPENCODE_COMMAND_REVIEW);
-  writeFile(path.join(opencodeDir, 'plankit.md'), OPENCODE_COMMAND_MASTER);
+function clarifyFeature(parsed, io) {
+  const { featureName, phaseNumber } = readFeatureAndPhaseArgs(parsed, { phaseOptional: true });
+  const { config } = loadConfig(io.cwd);
+  const options = writeOptions(parsed, config);
+  const featureDir = requireFeatureDir(io.cwd, config, featureName);
+  const phaseLabel = phaseNumber ? `Phase ${phaseNumber}` : 'Unspecified phase';
+
+  const result = writeManagedFile(
+    path.join(featureDir, 'clarifications.md'),
+    renderTemplate(config, 'clarifications.md', { featureName, phaseLabel }, io.cwd),
+    options
+  );
+
+  io.stdout(`Clarification artifact prepared for "${featureName}".`);
+  printResults([result], io);
+}
 
-  // 6. Global Gemini Skills setup
-  try {
-    const userHome = os.homedir();
-    const globalSkillsDir = path.join(userHome, '.gemini', 'skills');
-
-    const skillsToCreate = [
-      { name: 'plankit', desc: 'PlanKit Command Suite master skill.' },
-      { name: 'plankit-plan', desc: 'Initialize feature under artifacts/current/<feature-name>/.' },
-      { name: 'plankit-clarify', desc: 'Analyze requirements and ask targeted clarifying questions.' },
-      { name: 'plankit-implement', desc: 'Execute Phase N reading spec and previous outputs.' },
-      { name: 'plankit-review', desc: 'Run test & build verification, validate DoD, and archive feature.' }
-    ];
-
-    for (const skill of skillsToCreate) {
-      const skillPath = path.join(globalSkillsDir, skill.name, 'SKILL.md');
-      const skillContent = `---\nname: ${skill.name}\ndescription: ${skill.desc}\n---\n\n# ${skill.name}\n${skill.desc}\n`;
-      writeFile(skillPath, skillContent);
+function prepareImplementation(parsed, io) {
+  const { featureName, phaseNumber } = readFeatureAndPhaseArgs(parsed);
+  const { config } = loadConfig(io.cwd);
+  const options = writeOptions(parsed, config);
+  const featureDir = requireFeatureDir(io.cwd, config, featureName);
+  const phaseSpec = findPhaseSpec(featureDir, phaseNumber);
+  const previousMissing = [];
+
+  for (let index = 1; index < phaseNumber; index += 1) {
+    const outputPath = path.join(featureDir, 'outputs', `phase-${index}-output.md`);
+    if (!fs.existsSync(outputPath)) {
+      previousMissing.push(path.relative(featureDir, outputPath));
     }
-    console.log('  ✓ Installed global Gemini skills in ~/.gemini/skills/');
-  } catch (e) {
-    // Ignore global home dir write errors if restricted
   }
 
-  console.log('\n✅ PlanKit successfully initialized!');
-  console.log('\nCreated / Updated configuration files:');
-  console.log('  - artifacts/PLANKIT.md');
-  console.log('  - .gemini/instructions.md');
-  console.log('  - .cursorrules');
-  console.log('  - AGENTS.md');
-  console.log('  - .opencode/commands/*.md');
-  console.log('\nNext steps:');
-  console.log('  Run "npx plankit plan <feature-name>" to start a new feature.');
+  if (previousMissing.length > 0) {
+    throw new Error(`Cannot prepare Phase ${phaseNumber}; missing previous output(s): ${previousMissing.join(', ')}`);
+  }
+
+  const phaseTitle = readPhaseTitle(phaseSpec, phaseNumber);
+  const outputPath = path.join(featureDir, 'outputs', `phase-${phaseNumber}-output.md`);
+  const result = writeManagedFile(
+    outputPath,
+    renderTemplate(config, 'output-report.md', { phaseNumber, phaseTitle }, io.cwd),
+    options
+  );
+
+  io.stdout(`Implementation context validated for "${featureName}" Phase ${phaseNumber}.`);
+  io.stdout(`Phase spec: ${path.relative(io.cwd, phaseSpec)}`);
+  printResults([result], io);
 }
 
-function planFeature(featureName) {
-  const cwd = process.cwd();
-  const featureDir = path.join(cwd, 'artifacts', 'current', featureName);
+function reviewFeature(parsed, io) {
+  const featureName = parsed.positionals[0];
+  if (!featureName) {
+    throw new Error('Please specify a feature name. Example: plankit review my-feature');
+  }
+  assertSafeName(featureName, 'feature name');
+
+  const { config } = loadConfig(io.cwd);
+  const featureDir = requireFeatureDir(io.cwd, config, featureName);
+  const testCommand = parsed.flags['test-command'] ?? config.verification.testCommand;
+  const buildCommand = parsed.flags['build-command'] ?? config.verification.buildCommand;
 
-  if (fs.existsSync(featureDir)) {
-    console.log(`⚠️ Feature folder "${featureName}" already exists at artifacts/current/${featureName}`);
+  if (!parsed.flags['skip-test'] && testCommand) {
+    runVerificationCommand(testCommand, io);
+  }
+  if (!parsed.flags['skip-build'] && buildCommand) {
+    runVerificationCommand(buildCommand, io);
+  }
+
+  markReadmeArchived(path.join(featureDir, 'README.md'), parsed.dryRun);
+  moveFeatureToArchive(io.cwd, config, featureName, parsed.dryRun);
+  io.stdout(`Feature "${featureName}" reviewed and archived.`);
+}
+
+function showStatus(parsed, io) {
+  const { config } = loadConfig(io.cwd);
+  const currentDir = safeJoin(io.cwd, config.artifactsDir, 'current');
+  const archivedDir = safeJoin(io.cwd, config.artifactsDir, 'archived');
+  const status = {
+    active: listDirectories(currentDir),
+    archived: listDirectories(archivedDir)
+  };
+
+  if (parsed.flags.json) {
+    io.stdout(JSON.stringify(status, null, 2));
     return;
   }
 
-  console.log(`🚀 Creating new feature workspace for "${featureName}"...`);
+  io.stdout('PlanKit Feature Status Summary:');
+  io.stdout('');
+  io.stdout(`ACTIVE FEATURES (${path.join(config.artifactsDir, 'current')}/):`);
+  io.stdout(status.active.length ? status.active.map((feature) => `  - ${feature}`).join('\n') : '  (none)');
+  io.stdout('');
+  io.stdout(`ARCHIVED FEATURES (${path.join(config.artifactsDir, 'archived')}/):`);
+  io.stdout(status.archived.length ? status.archived.map((feature) => `  - ${feature}`).join('\n') : '  (none)');
+}
 
-  ensureDir(path.join(featureDir, 'phases'));
-  ensureDir(path.join(featureDir, 'outputs'));
+function archiveFeature(parsed, io) {
+  const featureName = parsed.positionals[0];
+  if (!featureName) {
+    throw new Error('Please specify a feature name. Example: plankit archive my-feature');
+  }
+  assertSafeName(featureName, 'feature name');
 
-  const readmeContent = `# Feature: ${featureName}
+  const { config } = loadConfig(io.cwd);
+  moveFeatureToArchive(io.cwd, config, featureName, parsed.dryRun);
+  io.stdout(`Feature "${featureName}" archived.`);
+}
 
-## Overview
-Detailed description of the feature goal and scope.
+function moveFeatureToArchive(cwd, config, featureName, dryRun = false) {
+  const sourceDir = requireFeatureDir(cwd, config, featureName);
+  const targetDir = safeJoin(cwd, config.artifactsDir, 'archived', featureName);
 
-## Phase Breakdown & Progress Status
+  if (fs.existsSync(targetDir)) {
+    throw new Error(`Archived feature "${featureName}" already exists.`);
+  }
 
-- [ ] Phase 1: Foundation & Setup — ([Spec](phases/phase-1-foundation.md))
-- [ ] Phase 2: Core Implementation
-- [ ] Phase 3: Testing & Verification
+  if (!dryRun) {
+    ensureDir(path.dirname(targetDir));
+    fs.renameSync(sourceDir, targetDir);
+  }
+}
 
-## Phase Execution Matrix
+function requireFeatureDir(cwd, config, featureName) {
+  assertSafeName(featureName, 'feature name');
+  const featureDir = safeJoin(cwd, config.artifactsDir, 'current', featureName);
 
-| Phase # | Phase Title | Spec Path | Output Path | Status |
-|---|---|---|---|---|
-| Phase 1 | Foundation & Setup | \`phases/phase-1-foundation.md\` | \`outputs/phase-1-output.md\` | **PENDING** |
-`;
+  if (!fs.existsSync(featureDir)) {
+    throw new Error(`Active feature "${featureName}" not found in ${path.join(config.artifactsDir, 'current')}/`);
+  }
 
-  const phase1Spec = `# Phase 1: Foundation & Setup
+  return featureDir;
+}
 
-## 1. Objective
-Establish base structure and foundational dependencies for ${featureName}.
+function findPhaseSpec(featureDir, phaseNumber) {
+  const phasesDir = path.join(featureDir, 'phases');
+  const prefix = `phase-${phaseNumber}-`;
+  const file = fs.readdirSync(phasesDir).find((name) => name.startsWith(prefix) && name.endsWith('.md'));
 
-## 2. Tasks
-- [ ] Initial setup
-- [ ] Basic implementation
-`;
+  if (!file) {
+    throw new Error(`Phase ${phaseNumber} spec not found under ${path.relative(process.cwd(), phasesDir)}`);
+  }
 
-  writeFile(path.join(featureDir, 'README.md'), readmeContent);
-  writeFile(path.join(featureDir, 'phases', 'phase-1-foundation.md'), phase1Spec);
-  writeFile(path.join(featureDir, 'outputs', '.gitkeep'), '');
+  return path.join(phasesDir, file);
+}
 
-  console.log(`\n✅ Feature "${featureName}" initialized successfully!`);
-  console.log(`  - Spec: artifacts/current/${featureName}/phases/phase-1-foundation.md`);
-  console.log(`  - Overview: artifacts/current/${featureName}/README.md`);
+function readPhaseTitle(phaseSpec, phaseNumber) {
+  const firstLine = fs.readFileSync(phaseSpec, 'utf8').split(/\r?\n/, 1)[0];
+  return firstLine.replace(/^#\s*Phase\s+\d+:\s*/i, '') || `Phase ${phaseNumber}`;
 }
 
-function showStatus() {
-  const cwd = process.cwd();
-  const currentDir = path.join(cwd, 'artifacts', 'current');
-  const archivedDir = path.join(cwd, 'artifacts', 'archived');
+function markReadmeArchived(readmePath, dryRun = false) {
+  if (!fs.existsSync(readmePath) || dryRun) {
+    return;
+  }
+
+  const content = fs.readFileSync(readmePath, 'utf8');
+  const updated = content.replace(/^# Feature: (.+?)(?: \[ARCHIVED\])?$/m, '# Feature: $1 [ARCHIVED]');
+  fs.writeFileSync(readmePath, updated, 'utf8');
+}
 
-  console.log('📊 PlanKit Feature Status Summary:\n');
+function runVerificationCommand(command, io) {
+  io.stdout(`Running: ${command}`);
+  const result = spawnSync(command, {
+    cwd: io.cwd,
+    shell: true,
+    stdio: 'inherit'
+  });
 
-  if (fs.existsSync(currentDir)) {
-    const currentFeatures = fs.readdirSync(currentDir).filter(f => !f.startsWith('.'));
-    console.log('📌 ACTIVE FEATURES (artifacts/current/):');
-    if (currentFeatures.length === 0) {
-      console.log('  (none)');
-    } else {
-      currentFeatures.forEach(f => console.log(`  - 🟡 ${f}`));
+  if (result.status !== 0) {
+    throw new Error(`Verification command failed: ${command}`);
+  }
+}
+
+function installGlobalGeminiSkills(config, options) {
+  const globalSkillsDir = path.join(os.homedir(), '.gemini', 'skills');
+
+  return GEMINI_SKILL_ENTRIES.map(([name, description]) => writeManagedFile(
+    path.join(globalSkillsDir, name, 'SKILL.md'),
+    `---\nname: ${name}\ndescription: ${description}\n---\n\n# ${name}\n\n${description}\n\nSpecification: ${config.artifactsDir}/PLANKIT.md\n`,
+    options
+  ));
+}
+
+function createFeatureState(featureName, phases) {
+  return {
+    feature: featureName,
+    status: 'active',
+    createdAt: new Date().toISOString(),
+    phases: phases.map((phase, index) => ({
+      number: index + 1,
+      title: phase.title,
+      specPath: `phases/${phaseFileName(index + 1, phase)}`,
+      outputPath: `outputs/phase-${index + 1}-output.md`,
+      status: 'pending'
+    }))
+  };
+}
+
+function phaseFileName(phaseNumber, phase) {
+  return `phase-${phaseNumber}-${phase.slug}.md`;
+}
+
+function readFeatureAndPhaseArgs(parsed, options = {}) {
+  const featureName = parsed.positionals[0];
+  const rawPhase = parsed.positionals[1] || parsed.flags.phase;
+
+  if (!featureName) {
+    throw new Error('Please specify a feature name.');
+  }
+  assertSafeName(featureName, 'feature name');
+
+  if (!rawPhase && options.phaseOptional) {
+    return { featureName, phaseNumber: null };
+  }
+
+  const phaseNumber = Number.parseInt(rawPhase, 10);
+  if (!Number.isInteger(phaseNumber) || phaseNumber <= 0) {
+    throw new Error('Please specify a positive phase number.');
+  }
+
+  return { featureName, phaseNumber };
+}
+
+async function resolveAgent(parsed, config, io, configPath = null) {
+  const fromFlag = parsed.flags.agent || parsed.flags.agents;
+  if (fromFlag) {
+    const parts = String(fromFlag).split(',').map((item) => item.trim()).filter(Boolean);
+    if (parts.length > 1) {
+      throw new Error(`Select a single agent, got ${parts.length}. Use --agent <name>. Valid agents: ${validAgentNames()}.`);
     }
+    const agent = getAgent(parts[0]);
+    io.stdout(`Using agent from --agent flag: "${agent.id}".`);
+    return agent;
   }
 
-  console.log('');
+  if (configPath) {
+    const configured = resolveConfiguredAgent(config);
+    if (configured) {
+      io.stdout(`Using configured agent "${configured.id}" from plan config.`);
+      return configured;
+    }
+  }
 
-  if (fs.existsSync(archivedDir)) {
-    const archivedFeatures = fs.readdirSync(archivedDir).filter(f => !f.startsWith('.'));
-    console.log('📦 ARCHIVED FEATURES (artifacts/archived/):');
-    if (archivedFeatures.length === 0) {
-      console.log('  (none)');
-    } else {
-      archivedFeatures.forEach(f => console.log(`  - 🟢 ${f}`));
+  if (io.isTTY && io.promptChoice) {
+    const agent = await promptAgent(io);
+    if (agent) {
+      io.stdout(`Selected agent: "${agent.id}".`);
+      return agent;
     }
   }
+
+  const agent = getAgent(DEFAULT_AGENT);
+  io.stdout(`No agent selected — using default agent "${agent.id}". Pass --agent <name> to change it.`);
+  return agent;
 }
 
-function archiveFeature(featureName) {
-  const cwd = process.cwd();
-  const sourceDir = path.join(cwd, 'artifacts', 'current', featureName);
-  const targetDir = path.join(cwd, 'artifacts', 'archived', featureName);
+async function promptAgent(io) {
+  const agents = listAgents();
+  const header = agents.map((agent, index) => (
+    `  ${index + 1}. ${agent.label} — ${agent.description}`
+  )).join('\n');
+  const answer = await io.promptChoice(
+    `Select your coding agent:\n${header}\n\nEnter a number 1-${agents.length} or a name`,
+    agents.map((agent) => agent.id)
+  );
+  if (!answer) {
+    return null;
+  }
+  const trimmed = answer.trim().toLowerCase();
+  const num = Number.parseInt(trimmed, 10);
+  if (Number.isInteger(num) && num >= 1 && num <= agents.length) {
+    return agents[num - 1];
+  }
+  return getAgent(trimmed) || null;
+}
+
+function writeOptions(parsed, config) {
+  return {
+    force: Boolean(parsed.flags.force) || config.overwrite === 'force',
+    dryRun: Boolean(parsed.flags['dry-run'])
+  };
+}
+
+function printResults(results, io) {
+  for (const result of results.filter(Boolean)) {
+    if (result.action === 'info') {
+      io.stdout(`  ${'info'.padEnd(9)} ${path.relative(io.cwd, result.path) || result.path} (${result.message || ''})`);
+      continue;
+    }
+    if (result.action === 'copied' && Array.isArray(result.copies)) {
+      io.stdout(`  ${'copied'.padEnd(9)} ${path.relative(io.cwd, result.path) || result.path}/`);
+      for (const copy of result.copies.filter(Boolean)) {
+        io.stdout(`  ${' '.padEnd(9)} ${path.relative(io.cwd, copy.path) || copy.path}`);
+      }
+      continue;
+    }
+    io.stdout(`  ${result.action.padEnd(9)} ${path.relative(io.cwd, result.path) || result.path}`);
+  }
+}
+
+function parseArgs(args) {
+  const [command, ...rest] = args;
+  const flags = {};
+  const positionals = [];
+
+  for (let index = 0; index < rest.length; index += 1) {
+    const arg = rest[index];
 
-  if (!fs.existsSync(sourceDir)) {
-    console.error(`Error: Active feature "${featureName}" not found in artifacts/current/`);
-    process.exit(1);
+    if (!arg.startsWith('--')) {
+      positionals.push(arg);
+      continue;
+    }
+
+    const flag = arg.slice(2);
+    const [inlineName, inlineValue] = flag.split('=', 2);
+    if (inlineValue !== undefined) {
+      flags[inlineName] = inlineValue;
+      continue;
+    }
+
+    const next = rest[index + 1];
+    if (next && !next.startsWith('--')) {
+      flags[inlineName] = next;
+      index += 1;
+    } else {
+      flags[inlineName] = true;
+    }
   }
 
-  ensureDir(path.dirname(targetDir));
-  fs.renameSync(sourceDir, targetDir);
+  return {
+    command,
+    flags,
+    positionals,
+    dryRun: Boolean(flags['dry-run'])
+  };
+}
+
+function createIo(context) {
+  const input = context.input || process.stdin;
+  const output = context.output || process.stdout;
+  const io = {
+    cwd: context.cwd || process.cwd(),
+    stdout: context.stdout || ((message) => console.log(message)),
+    stderr: context.stderr || ((message) => console.error(message)),
+    exit: context.exit || ((code) => process.exit(code)),
+    isTTY: context.isTTY !== undefined ? context.isTTY : Boolean(output && output.isTTY)
+  };
+
+  if (context.promptResponses !== undefined || input && input.isTTY) {
+    io.promptChoice = makePromptChoice(input, io.stdout, context.promptResponses);
+  }
+
+  return io;
+}
+
+function makePromptChoice(input, write, promptResponses) {
+  if (Array.isArray(promptResponses)) {
+    let index = 0;
+    return (prompt) => {
+      write(prompt);
+      const answer = promptResponses[index];
+      index += 1;
+      return answer === undefined ? '' : String(answer);
+    };
+  }
 
-  console.log(`✅ Archived feature "${featureName}" -> artifacts/archived/${featureName}`);
+  return async (prompt) => {
+    write(prompt);
+    const readline = (await import('node:readline/promises')).default;
+    const rl = readline.createInterface({ input, output: process.stdout });
+    const answer = await rl.question('');
+    rl.close();
+    return answer;
+  };
 }
 
-function showHelp() {
-  console.log(`
+function showHelp(io) {
+  io.stdout(`
 PlanKit CLI — Command Suite for AI Coding Assistants
 
 Usage:
-  npx plankit <command> [options]
+  plankit <command> [options]
 
 Commands:
-  init                     Initialize PlanKit rules & commands in the current project
-  plan <feature-name>      Create a new feature workspace under artifacts/current/<feature-name>/
-  status                   Show status of all active and archived features
-  archive <feature-name>   Move a completed feature to artifacts/archived/<feature-name>/
-  help                     Show this help message
+  init                              Initialize PlanKit rules, config, templates, and artifact folders
+  plan <feature> [requirements]     Create a feature workspace under artifacts/current/<feature>/
+  clarify <feature> [phase]         Create a clarification artifact for a feature
+  implement <feature> <phase>       Validate phase context and prepare phase output artifact
+  review <feature>                  Run verification and archive a completed feature
+  status [--json]                   Show active and archived features
+  archive <feature>                 Move a feature to archived without running verification
+  help                              Show this help message
+
+Options:
+  --force                           Overwrite generated files where safe
+  --dry-run                         Show intended actions without writing
+  --agent <name>                    Select your coding agent during init
+                                    (opencode, gemini, codex, cursor; default: opencode)
+  --global-gemini-skills            Also install Gemini skills under the user profile
+  --phases 3                        Generate N default phases during plan
+  --phases "Design,Build,Test"      Generate named phases during plan
+  --requirements "text"             Set feature requirements during plan
+  --test-command "command"          Override review test command
+  --build-command "command"         Override review build command
+  --skip-test                       Skip review test command
+  --skip-build                      Skip review build command
 `);
 }