plankit-cli 1.0.0 → 1.0.1

package/src/cli.js

@@ -1,235 +1,533 @@
 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;
-  }
-}
-
-function ensureDir(dirPath) {
-  if (!fs.existsSync(dirPath)) {
-    fs.mkdirSync(dirPath, { recursive: true });
-  }
-}
-
-function writeFile(filePath, content) {
-  ensureDir(path.dirname(filePath));
-  fs.writeFileSync(filePath, content, 'utf8');
-}
-
-function initProject() {
-  console.log('🚀 Initializing PlanKit Command Suite in project...');
-
-  const cwd = process.cwd();
-
-  // 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'), '');
-
-  // 2. Gemini / Antigravity instructions
-  writeFile(path.join(cwd, '.gemini', 'instructions.md'), GEMINI_INSTRUCTIONS_TEMPLATE);
-
-  // 3. Cursor rules
-  writeFile(path.join(cwd, '.cursorrules'), CURSORRULES_TEMPLATE);
-
-  // 4. AGENTS.md
-  writeFile(path.join(cwd, 'AGENTS.md'), AGENTS_MD_TEMPLATE);
-
-  // 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);
-
-  // 6. Global Gemini Skills setup
+  assertSafeName,
+  createDefaultConfigFile,
+  ensureDir,
+  listDirectories,
+  loadConfig,
+  normalizePhases,
+  parsePhaseFlag,
+  safeJoin,
+  writeManagedFile
+} from './config.js';
+import { renderList, renderTemplate } from './templates.js';
+
+export function runCli(args, context = {}) {
+  const io = createIo(context);
+
   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);
+    const parsed = parseArgs(args);
+    const command = parsed.command;
+
+    switch (command) {
+      case 'init':
+        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 initProject(parsed, io) {
+  const { config } = loadConfig(io.cwd);
+  const options = writeOptions(parsed, config);
+  const agents = selectedAgents(parsed, config);
+  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));
+
+  if (agents.gemini) {
+    results.push(writeManagedFile(
+      safeJoin(io.cwd, '.gemini', 'instructions.md'),
+      renderTemplate(config, 'gemini-instructions.md', { artifactsDir: config.artifactsDir }, io.cwd),
+      options
+    ));
+  }
+
+  if (agents.cursor) {
+    results.push(writeManagedFile(
+      safeJoin(io.cwd, '.cursorrules'),
+      renderTemplate(config, 'cursorrules', { artifactsDir: config.artifactsDir }, io.cwd),
+      options
+    ));
+  }
+
+  if (agents.codex) {
+    results.push(writeManagedFile(
+      safeJoin(io.cwd, 'AGENTS.md'),
+      renderTemplate(config, 'AGENTS.md', { artifactsDir: config.artifactsDir }, io.cwd),
+      options
+    ));
+  }
+
+  if (agents.opencode) {
+    const commandsDir = safeJoin(io.cwd, '.opencode', 'commands');
+    for (const fileName of [
+      'plankit-plan.md',
+      'plankit-clarify.md',
+      'plankit-implement.md',
+      'plankit-review.md',
+      'plankit.md'
+    ]) {
+      results.push(writeManagedFile(
+        path.join(commandsDir, fileName),
+        renderTemplate(config, path.join('opencode', fileName), { artifactsDir: config.artifactsDir }, io.cwd),
+        options
+      ));
     }
-    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 (parsed.flags['global-gemini-skills']) {
+    results.push(...installGlobalGeminiSkills(config, options));
+  }
+
+  io.stdout('PlanKit initialized.');
+  printResults(results, io);
 }
 
-function planFeature(featureName) {
-  const cwd = process.cwd();
-  const featureDir = path.join(cwd, 'artifacts', 'current', featureName);
+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');
+
+  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);
 
   if (fs.existsSync(featureDir)) {
-    console.log(`⚠️ Feature folder "${featureName}" already exists at artifacts/current/${featureName}`);
+    throw new Error(`Feature "${featureName}" already exists at ${path.join(config.artifactsDir, 'current', featureName)}`);
+  }
+
+  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);
+}
+
+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);
+}
+
+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));
+    }
+  }
+
+  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 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 (!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;
+  }
 
-  console.log('📊 PlanKit Feature Status Summary:\n');
+  const content = fs.readFileSync(readmePath, 'utf8');
+  const updated = content.replace(/^# Feature: (.+?)(?: \[ARCHIVED\])?$/m, '# Feature: $1 [ARCHIVED]');
+  fs.writeFileSync(readmePath, updated, 'utf8');
+}
 
-  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}`));
-    }
+function runVerificationCommand(command, io) {
+  io.stdout(`Running: ${command}`);
+  const result = spawnSync(command, {
+    cwd: io.cwd,
+    shell: true,
+    stdio: 'inherit'
+  });
+
+  if (result.status !== 0) {
+    throw new Error(`Verification command failed: ${command}`);
   }
+}
 
-  console.log('');
+function installGlobalGeminiSkills(config, options) {
+  const globalSkillsDir = path.join(os.homedir(), '.gemini', 'skills');
+  const skills = [
+    ['plankit', 'PlanKit Command Suite master skill.'],
+    ['plankit-plan', 'Initialize a feature workspace.'],
+    ['plankit-clarify', 'Analyze requirements and ask targeted clarifying questions.'],
+    ['plankit-implement', 'Prepare phase implementation context and output artifacts.'],
+    ['plankit-review', 'Run verification and archive completed features.']
+  ];
+
+  return skills.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
+  ));
+}
 
-  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}`));
-    }
+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 };
+}
+
+function selectedAgents(parsed, config) {
+  if (!parsed.flags.agents) {
+    return config.agents;
+  }
+
+  const requested = new Set(String(parsed.flags.agents).split(',').map((item) => item.trim()).filter(Boolean));
+  return {
+    codex: requested.has('codex'),
+    cursor: requested.has('cursor'),
+    opencode: requested.has('opencode'),
+    gemini: requested.has('gemini') || requested.has('antigravity')
+  };
+}
+
+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)) {
+    io.stdout(`  ${result.action.padEnd(9)} ${path.relative(io.cwd, result.path) || result.path}`);
   }
 }
 
-function archiveFeature(featureName) {
-  const cwd = process.cwd();
-  const sourceDir = path.join(cwd, 'artifacts', 'current', featureName);
-  const targetDir = path.join(cwd, 'artifacts', 'archived', featureName);
+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 (!arg.startsWith('--')) {
+      positionals.push(arg);
+      continue;
+    }
+
+    const flag = arg.slice(2);
+    const [inlineName, inlineValue] = flag.split('=', 2);
+    if (inlineValue !== undefined) {
+      flags[inlineName] = inlineValue;
+      continue;
+    }
 
-  if (!fs.existsSync(sourceDir)) {
-    console.error(`Error: Active feature "${featureName}" not found in artifacts/current/`);
-    process.exit(1);
+    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'])
+  };
+}
 
-  console.log(`✅ Archived feature "${featureName}" -> artifacts/archived/${featureName}`);
+function createIo(context) {
+  return {
+    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))
+  };
 }
 
-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
+  --agents codex,cursor,opencode    Select generated agent integrations during init
+  --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
 `);
 }