@silverassist/agents-toolkit 2.0.0

package/bin/cli.js

@@ -0,0 +1,940 @@
+#!/usr/bin/env node
+
+/**
+ * CLI tool for installing and managing AI agent prompts
+ * @module agents-toolkit/cli
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const TEMPLATES_DIR = path.join(__dirname, '..', 'templates');
+const COLORS = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  red: '\x1b[31m',
+  cyan: '\x1b[36m',
+};
+
+const DEFAULT_CONFIG = {
+  stack: 'all',
+  tracker: 'all',
+  jira: {
+    projectKey: 'PROJECT',
+    baseUrl: 'https://your-org.atlassian.net'
+  },
+  git: {
+    defaultBranch: 'dev',
+    branchPrefix: {
+      feature: 'feature/',
+      bugfix: 'bugfix/',
+      hotfix: 'hotfix/'
+    }
+  },
+  pr: {
+    targetBranch: 'dev',
+    template: 'default'
+  }
+};
+
+/**
+ * File categorization for stack/tracker filtering
+ */
+const FILE_CATEGORIES = {
+  instructions: {
+    react: ['css-styling', 'react-components', 'server-actions', 'tests', 'typescript'],
+    wordpress: ['php-standards', 'wordpress-plugin-architecture', 'testing-standards'],
+    universal: ['documentation-language', 'github-workflow'],
+  },
+  prompts: {
+    react: [],
+    wordpress: ['new-wp-component', 'new-wp-plugin', 'quality-check'],
+    universal: [
+      'analyze-ticket', 'work-ticket', 'analyze-github-issue', 'work-github-issue',
+      'create-plan', 'create-pr', 'prepare-pr', 'finalize-pr',
+      'review-code', 'fix-issues', 'add-tests', 'prepare-release',
+    ],
+    jira: ['analyze-ticket', 'work-ticket', 'create-pr', 'finalize-pr'],
+    github: ['analyze-github-issue', 'work-github-issue'],
+  },
+  partials: {
+    jira: ['jira-integration'],
+    github: ['github-integration'],
+    universal: ['git-operations', 'pr-template', 'validations', 'documentation'],
+  },
+  skills: {
+    react: ['component-architecture', 'testing-patterns'],
+    wordpress: ['create-component', 'plugin-creation', 'quality-checks', 'testing'],
+    universal: ['domain-driven-design', 'release-management'],
+  },
+};
+
+/**
+ * Determine if a file should be included based on stack/tracker filters
+ * @param {string} filename - File basename without extension
+ * @param {string} category - Category: instructions, prompts, partials, or skills
+ * @param {{ stack: string, tracker: string }} filters - Active filters
+ * @returns {boolean} Whether to include the file
+ */
+function shouldIncludeFile(filename, category, { stack, tracker }) {
+  const cats = FILE_CATEGORIES[category];
+  if (!cats) return true;
+
+  if (cats.universal && cats.universal.includes(filename)) {
+    if (tracker !== 'all' && cats.jira && cats.jira.includes(filename) && tracker !== 'jira') return false;
+    if (tracker !== 'all' && cats.github && cats.github.includes(filename) && tracker !== 'github') return false;
+    return true;
+  }
+
+  if (stack !== 'all') {
+    if (cats.react && cats.react.includes(filename)) return stack === 'react';
+    if (cats.wordpress && cats.wordpress.includes(filename)) return stack === 'wordpress';
+  }
+
+  if (tracker !== 'all') {
+    if (cats.jira && cats.jira.includes(filename)) return tracker === 'jira';
+    if (cats.github && cats.github.includes(filename)) return tracker === 'github';
+  }
+
+  return true;
+}
+
+/**
+ * Print colored message to console
+ * @param {string} message - Message to print
+ * @param {string} color - Color key from COLORS
+ */
+function log(message, color = 'reset') {
+  console.log(`${COLORS[color]}${message}${COLORS.reset}`);
+}
+
+/**
+ * Print success message
+ * @param {string} message - Message to print
+ */
+function success(message) {
+  log(`✅ ${message}`, 'green');
+}
+
+/**
+ * Print warning message
+ * @param {string} message - Message to print
+ */
+function warn(message) {
+  log(`⚠️  ${message}`, 'yellow');
+}
+
+/**
+ * Print error message
+ * @param {string} message - Message to print
+ */
+function error(message) {
+  log(`❌ ${message}`, 'red');
+}
+
+/**
+ * Print info message
+ * @param {string} message - Message to print
+ */
+function info(message) {
+  log(`ℹ️  ${message}`, 'blue');
+}
+
+/**
+ * Get the target directory for Copilot installation
+ * @returns {string} Path to .github directory
+ */
+function getTargetDir() {
+  return path.join(process.cwd(), '.github');
+}
+
+/**
+ * Get the target directory for Claude Code installation
+ * @returns {string} Path to .claude directory
+ */
+function getClaudeTargetDir() {
+  return path.join(process.cwd(), '.claude');
+}
+
+/**
+ * Strip GitHub Copilot frontmatter from a prompt file
+ * Removes the ---\nagent: ...\ndescription: ...\n--- block
+ * @param {string} content - File content
+ * @returns {string} Content without Copilot frontmatter
+ */
+function stripCopilotFrontmatter(content) {
+  return content.replace(/^---\n(?:[\s\S]*?\n)?---\n\n?/, '');
+}
+
+/**
+ * Adapt path references in prompt content for Claude Code
+ * @param {string} content - File content
+ * @returns {string} Content with updated paths
+ */
+function adaptPathsForClaude(content) {
+  return content
+    .replace(/\.github\/copilot-instructions\.md/g, 'CLAUDE.md')
+    .replace(/\.github\/prompts\/_partials\//g, '.claude/commands/_partials/');
+}
+
+/**
+ * Copy a directory recursively
+ * @param {string} src - Source directory
+ * @param {string} dest - Destination directory
+ * @param {Object} options - Copy options
+ * @param {boolean} options.force - Overwrite existing files
+ * @param {boolean} options.dryRun - Only show what would be copied
+ * @param {(name: string) => string} [options.renameFile] - Optional file rename function
+ * @param {(content: string) => string} [options.transformContent] - Optional content transform
+ * @param {(name: string) => boolean} [options.filter] - Optional file filter function
+ * @returns {{ written: number, planned: number }} Number of written/planned files
+ */
+function copyDir(src, dest, options = {}) {
+  const {
+    force = false,
+    dryRun = false,
+    renameFile = (name) => name,
+    transformContent = null,
+    filter = null,
+    dirFilter = null,
+  } = options;
+  const totals = { written: 0, planned: 0 };
+
+  if (!fs.existsSync(src)) {
+    return totals;
+  }
+
+  if (!dryRun && !fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+
+    if (entry.isDirectory()) {
+      if (dirFilter && !dirFilter(entry.name)) {
+        continue;
+      }
+      const nestedOptions = { ...options };
+      if (entry.name === '_partials' && options.partialsFilter) {
+        nestedOptions.filter = options.partialsFilter;
+      }
+      const nested = copyDir(srcPath, path.join(dest, entry.name), nestedOptions);
+      totals.written += nested.written;
+      totals.planned += nested.planned;
+    } else {
+      if (filter && !filter(entry.name)) {
+        continue;
+      }
+
+      const destName = renameFile(entry.name);
+      const destPath = path.join(dest, destName);
+      const exists = fs.existsSync(destPath);
+
+      if (exists && !force) {
+        warn(`Skipping existing file: ${path.relative(process.cwd(), destPath)}`);
+        continue;
+      }
+
+      totals.planned++;
+
+      if (dryRun) {
+        info(`Would copy: ${path.relative(process.cwd(), destPath)}`);
+      } else {
+        if (transformContent) {
+          const rawContent = fs.readFileSync(srcPath, 'utf-8');
+          fs.writeFileSync(destPath, transformContent(rawContent));
+        } else {
+          fs.copyFileSync(srcPath, destPath);
+        }
+        totals.written++;
+      }
+    }
+  }
+
+  return totals;
+}
+
+function getInstallScope(options = {}) {
+  const {
+    promptsOnly = false,
+    partialsOnly = false,
+    skillsOnly = false,
+    instructionsOnly = false,
+  } = options;
+
+  const hasSpecificFlag = promptsOnly || partialsOnly || skillsOnly || instructionsOnly;
+
+  return {
+    shouldInstallPrompts: !hasSpecificFlag || promptsOnly || partialsOnly,
+    shouldInstallInstructions: !hasSpecificFlag || instructionsOnly,
+    shouldInstallSkills: !hasSpecificFlag || skillsOnly,
+  };
+}
+
+function getChangeCount(result, dryRun) {
+  return dryRun ? result.planned : result.written;
+}
+
+function ensureConfigFile({ dryRun = false } = {}) {
+  const configPath = path.join(process.cwd(), '.agents-toolkit.json');
+
+  if (fs.existsSync(configPath)) {
+    return { written: 0, planned: 0 };
+  }
+
+  if (dryRun) {
+    info('Would create .agents-toolkit.json');
+    return { written: 0, planned: 1 };
+  }
+
+  fs.writeFileSync(configPath, JSON.stringify(DEFAULT_CONFIG, null, 2));
+  success('Created .agents-toolkit.json config file');
+  return { written: 1, planned: 1 };
+}
+
+function installCopilotInstructions({ targetDir, dryRun = false } = {}) {
+  const result = { written: 0, planned: 0 };
+  const copilotInstructionsPath = path.join(targetDir, 'copilot-instructions.md');
+  const templatePath = path.join(TEMPLATES_DIR, 'agents', 'copilot-instructions.md');
+
+  if (!fs.existsSync(templatePath)) {
+    return result;
+  }
+
+  const templateContent = fs.readFileSync(templatePath, 'utf-8');
+
+  if (fs.existsSync(copilotInstructionsPath)) {
+    const existingContent = fs.readFileSync(copilotInstructionsPath, 'utf-8');
+    const marker = '## 🔄 Copilot Agent Workflow';
+
+    if (existingContent.includes(marker)) {
+      info('copilot-instructions.md already contains key sections');
+      return result;
+    }
+
+    result.planned++;
+    if (dryRun) {
+      info('Would append key sections to existing copilot-instructions.md');
+      return result;
+    }
+
+    const sectionsToAppend = templateContent.split('\n').slice(4).join('\n');
+    const newContent = `${existingContent}\n\n<!-- Added by agents-toolkit -->\n${sectionsToAppend}`;
+    fs.writeFileSync(copilotInstructionsPath, newContent);
+    success('Appended key sections to existing copilot-instructions.md');
+    result.written++;
+    return result;
+  }
+
+  result.planned++;
+  if (dryRun) {
+    info('Would create copilot-instructions.md');
+    return result;
+  }
+
+  fs.writeFileSync(copilotInstructionsPath, templateContent);
+  success('Created copilot-instructions.md with key sections');
+  result.written++;
+  return result;
+}
+
+function getAgentsTemplateBody(templateContent) {
+  const lines = templateContent.split('\n');
+  const dividerIndex = lines.indexOf('---');
+
+  if (dividerIndex === -1) {
+    return templateContent;
+  }
+
+  return lines.slice(dividerIndex + 1).join('\n').trimStart();
+}
+
+function installAgentsFile(options = {}) {
+  const {
+    templatePath,
+    force = false,
+    append = false,
+    dryRun = false,
+  } = options;
+
+  const result = { written: 0, planned: 0 };
+  const agentsPath = path.join(process.cwd(), 'AGENTS.md');
+
+  if (!fs.existsSync(templatePath)) {
+    return result;
+  }
+
+  const agentsExists = fs.existsSync(agentsPath);
+
+  if (!agentsExists || force) {
+    result.planned++;
+    if (dryRun) {
+      info(agentsExists ? 'Would update AGENTS.md in project root' : 'Would create AGENTS.md in project root');
+      return result;
+    }
+
+    fs.copyFileSync(templatePath, agentsPath);
+    success(agentsExists ? 'Updated AGENTS.md in project root' : 'Created AGENTS.md in project root');
+    result.written++;
+    return result;
+  }
+
+  if (!append) {
+    info('AGENTS.md already exists in project root (use --force to overwrite or --append to merge)');
+    return result;
+  }
+
+  const existingContent = fs.readFileSync(agentsPath, 'utf-8');
+  const mergeMarker = '## 🔄 Agent Workflow (Complex Tasks)';
+
+  if (existingContent.includes(mergeMarker)) {
+    info('AGENTS.md already contains workflow sections');
+    return result;
+  }
+
+  result.planned++;
+  if (dryRun) {
+    info('Would append missing sections to AGENTS.md');
+    return result;
+  }
+
+  const templateContent = fs.readFileSync(templatePath, 'utf-8');
+  const templateBody = getAgentsTemplateBody(templateContent);
+  const mergedContent = `${existingContent}\n\n<!-- Added by agents-toolkit (--append) -->\n\n${templateBody}`;
+  fs.writeFileSync(agentsPath, mergedContent);
+  success('Appended missing sections to AGENTS.md');
+  result.written++;
+  return result;
+}
+
+function installGitBasedTarget(options = {}, target = 'copilot') {
+  const {
+    force = false,
+    append = false,
+    dryRun = false,
+    filters = { stack: 'all', tracker: 'all' },
+  } = options;
+  const isCodex = target === 'codex';
+  const targetDir = getTargetDir();
+  const scope = getInstallScope(options);
+  let totalChanges = 0;
+
+  const makeFilter = (category) => (name) => {
+    const basename = name.replace(/\.(prompt\.md|instructions\.md|md)$/, '');
+    return shouldIncludeFile(basename, category, filters);
+  };
+
+  const promptsFilter = makeFilter('prompts');
+  const partialsFilter = makeFilter('partials');
+
+  log(isCodex ? '\n⚡ Codex Installer\n' : '\n📦 Agents Toolkit Installer\n', 'bright');
+
+  if (dryRun) {
+    info('Dry run mode - no files will be copied\n');
+  }
+
+  if (scope.shouldInstallPrompts) {
+    info('Installing prompts...');
+    const result = copyDir(path.join(TEMPLATES_DIR, 'shared', 'prompts'), path.join(targetDir, 'prompts'), { force, dryRun, filter: promptsFilter, partialsFilter });
+    totalChanges += getChangeCount(result, dryRun);
+
+    if (!dryRun && result.written > 0) {
+      success(`Installed ${result.written} prompt files`);
+    }
+  }
+
+  if (scope.shouldInstallInstructions) {
+    info('Installing instructions...');
+    const result = copyDir(path.join(TEMPLATES_DIR, 'shared', 'instructions'), path.join(targetDir, 'instructions'), { force, dryRun, filter: makeFilter('instructions') });
+    totalChanges += getChangeCount(result, dryRun);
+
+    if (!dryRun && result.written > 0) {
+      success(`Installed ${result.written} instruction files`);
+    }
+  }
+
+  if (scope.shouldInstallSkills) {
+    info('Installing skills...');
+    const result = copyDir(path.join(TEMPLATES_DIR, 'shared', 'skills'), path.join(targetDir, 'skills'), { force, dryRun, dirFilter: makeFilter('skills') });
+    totalChanges += getChangeCount(result, dryRun);
+
+    if (!dryRun && result.written > 0) {
+      success(`Installed ${result.written} skill files`);
+    }
+  }
+
+  const configResult = ensureConfigFile({ dryRun });
+  totalChanges += getChangeCount(configResult, dryRun);
+
+  if (scope.shouldInstallInstructions && !isCodex) {
+    const copilotInstructionsResult = installCopilotInstructions({ targetDir, dryRun });
+    totalChanges += getChangeCount(copilotInstructionsResult, dryRun);
+  }
+
+  if (scope.shouldInstallInstructions) {
+    const agentsTemplatePath = isCodex
+      ? path.join(TEMPLATES_DIR, 'agents', 'AGENTS.codex.md')
+      : path.join(TEMPLATES_DIR, 'agents', 'AGENTS.md');
+    const agentsResult = installAgentsFile({ templatePath: agentsTemplatePath, force, append, dryRun });
+    totalChanges += getChangeCount(agentsResult, dryRun);
+  }
+
+  console.log('');
+  if (dryRun) {
+    info(`Dry run complete. ${totalChanges} files would be installed.`);
+  } else if (totalChanges > 0) {
+    success(`Installation complete! ${totalChanges} files installed.`);
+    console.log('');
+    info('Next steps:');
+    console.log('  1. Update .agents-toolkit.json with your Jira project key');
+    if (isCodex) {
+      console.log('  2. Review AGENTS.md in the project root');
+      console.log('  3. Run Codex from this project root');
+    } else {
+      console.log('  2. Configure Atlassian MCP in VS Code');
+      console.log('  3. Run prompts via Command Palette > "GitHub Copilot: Run Prompt"');
+    }
+  } else {
+    warn('No new files installed. Use --force to overwrite existing files.');
+  }
+  console.log('');
+}
+
+/**
+ * Install prompts to target directory
+ * @param {Object} options - Install options
+ */
+function install(options = {}) {
+  installGitBasedTarget(options, 'copilot');
+}
+
+/**
+ * Install files for Codex
+ * @param {Object} options - Install options
+ */
+function installCodex(options = {}) {
+  installGitBasedTarget(options, 'codex');
+}
+
+/**
+ * Install Claude Code files (CLAUDE.md + .claude/commands/)
+ * @param {Object} options - Install options
+ */
+function installClaude(options = {}) {
+  const { force = false, dryRun = false, filters = { stack: 'all', tracker: 'all' } } = options;
+  const scope = getInstallScope(options);
+  const claudeDir = getClaudeTargetDir();
+  const githubDir = getTargetDir();
+  let totalChanges = 0;
+
+  const makeFilter = (category) => (name) => {
+    const basename = name.replace(/\.(prompt\.md|instructions\.md|md)$/, '');
+    return shouldIncludeFile(basename, category, filters);
+  };
+
+  const promptsFilter = makeFilter('prompts');
+  const partialsFilter = makeFilter('partials');
+
+  log('\n🤖 Claude Code Installer\n', 'bright');
+
+  if (dryRun) {
+    info('Dry run mode - no files will be copied\n');
+  }
+
+  if (scope.shouldInstallPrompts) {
+    info('Installing slash commands...');
+    const result = copyDir(path.join(TEMPLATES_DIR, 'shared', 'prompts'), path.join(claudeDir, 'commands'), {
+      force,
+      dryRun,
+      filter: promptsFilter,
+      partialsFilter,
+      renameFile: (name) => name.replace(/\.prompt\.md$/, '.md'),
+      transformContent: (content) => adaptPathsForClaude(stripCopilotFrontmatter(content)),
+    });
+    totalChanges += getChangeCount(result, dryRun);
+
+    if (!dryRun && result.written > 0) {
+      success(`Installed ${result.written} command files to .claude/commands/`);
+    }
+  }
+
+  if (scope.shouldInstallInstructions) {
+    info('Installing instructions...');
+    const result = copyDir(path.join(TEMPLATES_DIR, 'shared', 'instructions'), path.join(githubDir, 'instructions'), { force, dryRun, filter: makeFilter('instructions') });
+    totalChanges += getChangeCount(result, dryRun);
+
+    if (!dryRun && result.written > 0) {
+      success(`Installed ${result.written} instruction files`);
+    }
+  }
+
+  if (scope.shouldInstallSkills) {
+    info('Installing skills...');
+    const result = copyDir(path.join(TEMPLATES_DIR, 'shared', 'skills'), path.join(githubDir, 'skills'), { force, dryRun, dirFilter: makeFilter('skills') });
+    totalChanges += getChangeCount(result, dryRun);
+
+    if (!dryRun && result.written > 0) {
+      success(`Installed ${result.written} skill files`);
+    }
+  }
+
+  if (scope.shouldInstallInstructions) {
+    const claudeMdPath = path.join(process.cwd(), 'CLAUDE.md');
+    const claudeMdTemplate = path.join(TEMPLATES_DIR, 'agents', 'CLAUDE.md');
+
+    if (fs.existsSync(claudeMdTemplate)) {
+      const exists = fs.existsSync(claudeMdPath);
+      if (exists && !force) {
+        info('CLAUDE.md already exists (use --force to overwrite)');
+      } else {
+        totalChanges += 1;
+        if (dryRun) {
+          info(exists ? 'Would update CLAUDE.md' : 'Would create CLAUDE.md');
+        } else {
+          fs.copyFileSync(claudeMdTemplate, claudeMdPath);
+          success(exists ? 'Updated CLAUDE.md' : 'Created CLAUDE.md');
+        }
+      }
+    }
+  }
+
+  const configResult = ensureConfigFile({ dryRun });
+  totalChanges += getChangeCount(configResult, dryRun);
+
+  console.log('');
+  if (dryRun) {
+    info(`Dry run complete. ${totalChanges} files would be installed.`);
+  } else if (totalChanges > 0) {
+    success(`Installation complete! ${totalChanges} files installed.`);
+    console.log('');
+    info('Next steps:');
+    console.log('  1. Update .agents-toolkit.json with your Jira project key');
+    console.log('  2. Configure Atlassian MCP in Claude Code settings');
+    console.log('  3. Run slash commands with /analyze-ticket, /work-ticket, etc.');
+  } else {
+    warn('No new files installed. Use --force to overwrite existing files.');
+  }
+  console.log('');
+}
+
+/**
+ * List available prompts
+ */
+function list() {
+  log('\n📋 Available Prompts\n', 'bright');
+
+  const promptsDir = path.join(TEMPLATES_DIR, 'shared', 'prompts');
+  
+  if (!fs.existsSync(promptsDir)) {
+    error('Templates directory not found');
+    return;
+  }
+
+  const prompts = fs.readdirSync(promptsDir)
+    .filter(f => f.endsWith('.prompt.md'))
+    .map(f => f.replace('.prompt.md', ''));
+
+  log('Workflow Prompts:', 'cyan');
+  const workflowPrompts = ['analyze-ticket', 'create-plan', 'work-ticket', 'prepare-pr', 'create-pr', 'finalize-pr'];
+  workflowPrompts.forEach((p, i) => {
+    if (prompts.includes(p)) {
+      console.log(`  ${i + 1}. ${p}`);
+    }
+  });
+
+  console.log('');
+  log('Utility Prompts:', 'cyan');
+  const utilityPrompts = prompts.filter(p => !workflowPrompts.includes(p));
+  utilityPrompts.forEach(p => {
+    console.log(`  • ${p}`);
+  });
+
+  console.log('');
+  log('Partials:', 'cyan');
+  const partialsDir = path.join(promptsDir, '_partials');
+  if (fs.existsSync(partialsDir)) {
+    const partials = fs.readdirSync(partialsDir)
+      .filter(f => f.endsWith('.md') && f !== 'README.md');
+    partials.forEach(p => {
+      console.log(`  • ${p.replace('.md', '')}`);
+    });
+  }
+
+  console.log('');
+  log('Skills:', 'cyan');
+  const skillsDir = path.join(TEMPLATES_DIR, 'shared', 'skills');
+  if (fs.existsSync(skillsDir)) {
+    const skills = fs.readdirSync(skillsDir, { withFileTypes: true })
+      .filter(d => d.isDirectory())
+      .map(d => d.name);
+    skills.forEach(s => {
+      console.log(`  • ${s}`);
+    });
+  }
+  console.log('');
+}
+
+/**
+ * Show help message
+ */
+function showHelp() {
+  log('\n📦 Agents Toolkit\n', 'bright');
+  console.log('Usage: agents-toolkit <command> [options]\n');
+  
+  log('Commands:', 'cyan');
+  console.log('  install     Install prompts (default target: copilot)');
+  console.log('  list        List available prompts');
+  console.log('  update      Update existing prompts (alias for install --force)');
+  console.log('  help        Show this help message');
+  
+  console.log('');
+  log('Options:', 'cyan');
+  console.log('  --force, -f         Overwrite existing files');
+  console.log('  --target <name>     Target installer: copilot | claude | codex');
+  console.log('  --stack <name>      Filter by stack: react | wordpress | all (default: all)');
+  console.log('  --tracker <name>    Filter by tracker: jira | github | all (default: all)');
+  console.log('  --claude            Install for Claude Code (.claude/commands/ + CLAUDE.md)');
+  console.log('  --codex             Install for Codex (AGENTS.md + shared .github files)');
+  console.log('  --append            Append missing AGENTS.md sections instead of overwriting');
+  console.log('  --prompts-only      Only install prompts (no instructions/skills)');
+  console.log('  --instructions-only Only install instructions');
+  console.log('  --partials-only     Only install partials');
+  console.log('  --skills-only       Only install skills');
+  console.log('  --dry-run           Show what would be installed');
+
+  console.log('');
+  log('Examples:', 'cyan');
+  console.log('  npx agents-toolkit install                          # All content');
+  console.log('  npx agents-toolkit install --stack react            # React/TS only');
+  console.log('  npx agents-toolkit install --stack wordpress        # PHP/WordPress only');
+  console.log('  npx agents-toolkit install --tracker github         # GitHub Issues workflow');
+  console.log('  npx agents-toolkit install --tracker jira           # Jira workflow');
+  console.log('  npx agents-toolkit install --target codex');
+  console.log('  npx agents-toolkit install --target=claude');
+  console.log('  npx agents-toolkit install --force');
+  console.log('  npx agents-toolkit install --append --instructions-only');
+  console.log('  npx agents-toolkit install --claude --force');
+  console.log('  npx agents-toolkit install --codex --force');
+  console.log('  npx agents-toolkit install --prompts-only');
+  console.log('  npx agents-toolkit list');
+  console.log('');
+}
+
+/**
+ * Parse command line arguments
+ * @returns {Object} Parsed arguments
+ */
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const command = args[0] || 'help';
+  const flags = args.slice(1);
+
+  let target = null;
+  let stack = null;
+  let tracker = null;
+  for (let i = 0; i < flags.length; i++) {
+    const arg = flags[i];
+    if (arg === '--target') {
+      const value = flags[i + 1];
+      if (value && !value.startsWith('-')) {
+        target = value;
+        i++;
+      } else {
+        target = '';
+      }
+    } else if (arg.startsWith('--target=')) {
+      target = arg.split('=').slice(1).join('=');
+    } else if (arg === '--stack') {
+      const value = flags[i + 1];
+      if (value && !value.startsWith('-')) {
+        stack = value;
+        i++;
+      } else {
+        stack = '';
+      }
+    } else if (arg.startsWith('--stack=')) {
+      stack = arg.split('=').slice(1).join('=');
+    } else if (arg === '--tracker') {
+      const value = flags[i + 1];
+      if (value && !value.startsWith('-')) {
+        tracker = value;
+        i++;
+      } else {
+        tracker = '';
+      }
+    } else if (arg.startsWith('--tracker=')) {
+      tracker = arg.split('=').slice(1).join('=');
+    }
+  }
+
+  const options = {
+    force: flags.includes('--force') || flags.includes('-f'),
+    promptsOnly: flags.includes('--prompts-only'),
+    partialsOnly: flags.includes('--partials-only'),
+    skillsOnly: flags.includes('--skills-only'),
+    instructionsOnly: flags.includes('--instructions-only'),
+    dryRun: flags.includes('--dry-run'),
+    claude: flags.includes('--claude'),
+    codex: flags.includes('--codex'),
+    append: flags.includes('--append'),
+    target,
+    stack,
+    tracker,
+  };
+  
+  return { command, options };
+}
+
+function resolveInstallTarget(options = {}) {
+  const legacyTargets = [];
+
+  if (options.claude) {
+    legacyTargets.push('claude');
+  }
+  if (options.codex) {
+    legacyTargets.push('codex');
+  }
+
+  let explicitTarget = null;
+  if (options.target !== null && options.target !== undefined) {
+    explicitTarget = options.target.trim().toLowerCase();
+    if (!explicitTarget) {
+      error('Missing value for --target. Use copilot, claude, or codex.');
+      process.exit(1);
+    }
+    if (!['copilot', 'claude', 'codex'].includes(explicitTarget)) {
+      error(`Invalid --target value: ${options.target}. Use copilot, claude, or codex.`);
+      process.exit(1);
+    }
+  }
+
+  if (legacyTargets.length > 1) {
+    error('Use either --claude or --codex, not both.');
+    process.exit(1);
+  }
+
+  if (explicitTarget && legacyTargets.length > 0 && legacyTargets[0] !== explicitTarget) {
+    error(`Conflicting target flags: --target ${explicitTarget} and --${legacyTargets[0]}.`);
+    process.exit(1);
+  }
+
+  if (explicitTarget) {
+    return explicitTarget;
+  }
+
+  if (legacyTargets.length === 1) {
+    return legacyTargets[0];
+  }
+
+  return 'copilot';
+}
+
+/**
+ * Resolve stack and tracker filters from flags or config file
+ * @param {Object} options - Parsed CLI options
+ * @returns {{ stack: string, tracker: string }} Resolved filters
+ */
+function resolveFilters(options = {}) {
+  const validStacks = ['react', 'wordpress', 'all'];
+  const validTrackers = ['jira', 'github', 'all'];
+
+  let stack = 'all';
+  let tracker = 'all';
+
+  const configPath = path.join(process.cwd(), '.agents-toolkit.json');
+  if (fs.existsSync(configPath)) {
+    try {
+      const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+      if (config.stack) stack = config.stack;
+      if (config.tracker) tracker = config.tracker;
+    } catch {
+      // Ignore invalid config
+    }
+  }
+
+  if (options.stack !== null && options.stack !== undefined) {
+    const value = options.stack.trim().toLowerCase();
+    if (!value) {
+      error('Missing value for --stack. Use react, wordpress, or all.');
+      process.exit(1);
+    }
+    if (!validStacks.includes(value)) {
+      error(`Invalid --stack value: ${options.stack}. Use react, wordpress, or all.`);
+      process.exit(1);
+    }
+    stack = value;
+  }
+
+  if (options.tracker !== null && options.tracker !== undefined) {
+    const value = options.tracker.trim().toLowerCase();
+    if (!value) {
+      error('Missing value for --tracker. Use jira, github, or all.');
+      process.exit(1);
+    }
+    if (!validTrackers.includes(value)) {
+      error(`Invalid --tracker value: ${options.tracker}. Use jira, github, or all.`);
+      process.exit(1);
+    }
+    tracker = value;
+  }
+
+  return { stack, tracker };
+}
+
+/**
+ * Main CLI entry point
+ */
+function main() {
+  const { command, options } = parseArgs();
+  const target = (command === 'install' || command === 'update')
+    ? resolveInstallTarget(options)
+    : null;
+  const filters = (command === 'install' || command === 'update')
+    ? resolveFilters(options)
+    : { stack: 'all', tracker: 'all' };
+
+  switch (command) {
+    case 'install':
+      if (target === 'claude') {
+        installClaude({ ...options, filters });
+      } else if (target === 'codex') {
+        installCodex({ ...options, filters });
+      } else {
+        install({ ...options, filters });
+      }
+      break;
+    case 'update':
+      if (target === 'claude') {
+        installClaude({ ...options, force: true, filters });
+      } else if (target === 'codex') {
+        installCodex({ ...options, force: true, filters });
+      } else {
+        install({ ...options, force: true, filters });
+      }
+      break;
+    case 'list':
+      list();
+      break;
+    case 'help':
+    case '--help':
+    case '-h':
+      showHelp();
+      break;
+    default:
+      error(`Unknown command: ${command}`);
+      showHelp();
+      process.exit(1);
+  }
+}
+
+main();