create-claude-context 1.0.0

package/lib/index.js

@@ -0,0 +1,170 @@
+/**
+ * Main orchestrator for create-claude-context
+ *
+ * Handles the full installation flow:
+ * 1. Interactive prompts (or defaults)
+ * 2. Directory structure creation
+ * 3. Template copying
+ * 4. Tech stack detection
+ * 5. Placeholder replacement
+ * 6. Validation
+ * 7. Plugin installation (optional)
+ */
+
+const path = require('path');
+const fs = require('fs');
+const chalk = require('chalk');
+const { runPrompts, getDefaults } = require('./prompts');
+const { createSpinner } = require('./spinner');
+const {
+  createDirectoryStructure,
+  copyTemplates,
+  createClaudeMd
+} = require('./installer');
+const { detectTechStack } = require('./detector');
+const { replacePlaceholders } = require('./placeholder');
+const { validateInstallation } = require('./validate');
+
+/**
+ * Main entry point
+ */
+async function run(options = {}) {
+  const {
+    projectName,
+    skipPrompts = false,
+    installPlugin = true,
+    template,
+    initGit = true,
+    dryRun = false,
+    verbose = false
+  } = options;
+
+  // Determine target directory
+  const targetDir = projectName
+    ? path.resolve(process.cwd(), projectName)
+    : process.cwd();
+
+  const projectNameResolved = projectName || path.basename(targetDir);
+
+  // Get configuration (prompts or defaults)
+  let config;
+  if (skipPrompts) {
+    config = await getDefaults(targetDir, template);
+  } else {
+    config = await runPrompts(targetDir, template);
+  }
+
+  config.projectName = projectNameResolved;
+  config.targetDir = targetDir;
+  config.installPlugin = installPlugin && config.installPlugin;
+  config.initGit = initGit;
+  config.dryRun = dryRun;
+  config.verbose = verbose;
+
+  if (dryRun) {
+    console.log(chalk.yellow('\n--dry-run mode: No changes will be made\n'));
+    console.log('Configuration:', JSON.stringify(config, null, 2));
+    return;
+  }
+
+  // Phase 1: Create target directory if needed
+  const spinner = createSpinner();
+
+  if (projectName && !fs.existsSync(targetDir)) {
+    spinner.start('Creating project directory...');
+    fs.mkdirSync(targetDir, { recursive: true });
+    spinner.succeed(`Created project directory: ${projectNameResolved}`);
+  }
+
+  // Phase 2: Create .claude directory structure
+  spinner.start('Creating .claude directory structure...');
+  const dirsCreated = await createDirectoryStructure(targetDir, config);
+  spinner.succeed(`Created .claude directory structure (${dirsCreated} directories)`);
+
+  // Phase 3: Copy template files
+  spinner.start('Copying template files...');
+  const filesCopied = await copyTemplates(targetDir, config);
+  spinner.succeed(`Copied ${filesCopied} template files`);
+
+  // Phase 4: Detect technology stack
+  spinner.start('Detecting technology stack...');
+  const techStack = await detectTechStack(targetDir);
+  spinner.succeed(`Detected: ${techStack.summary || 'Generic project'}`);
+
+  // Phase 5: Replace placeholders
+  spinner.start('Populating templates with project info...');
+  const placeholdersReplaced = await replacePlaceholders(targetDir, {
+    ...config,
+    techStack
+  });
+  spinner.succeed(`Replaced ${placeholdersReplaced} placeholders`);
+
+  // Phase 6: Create CLAUDE.md at root
+  spinner.start('Creating CLAUDE.md...');
+  await createClaudeMd(targetDir, config, techStack);
+  spinner.succeed('Created CLAUDE.md at project root');
+
+  // Phase 7: Validate installation
+  spinner.start('Validating installation...');
+  const validation = await validateInstallation(targetDir);
+  if (validation.passed) {
+    spinner.succeed('All validations passed');
+  } else {
+    spinner.warn(`Validation completed with ${validation.warnings} warnings`);
+  }
+
+  // Phase 8: Install Claude Code plugin (optional)
+  if (config.installPlugin) {
+    spinner.start('Installing Claude Code plugin...');
+    // Plugin installation would use: npx claude-plugins install claude-context-engineering
+    // For now, we'll note it as a next step
+    spinner.succeed('Plugin ready (install with: /plugin install claude-context-engineering)');
+  }
+
+  // Phase 9: Initialize git (optional)
+  if (config.initGit && !fs.existsSync(path.join(targetDir, '.git'))) {
+    spinner.start('Initializing git repository...');
+    try {
+      const { execSync } = require('child_process');
+      execSync('git init', { cwd: targetDir, stdio: 'pipe' });
+      spinner.succeed('Initialized git repository');
+    } catch (e) {
+      spinner.warn('Could not initialize git (git may not be installed)');
+    }
+  }
+
+  // Success message
+  showSuccess(config, techStack);
+}
+
+/**
+ * Display success message with next steps
+ */
+function showSuccess(config, techStack) {
+  const boxWidth = 59;
+
+  console.log(`
+${chalk.green('╔' + '═'.repeat(boxWidth) + '╗')}
+${chalk.green('║')}  ${chalk.bold.white('✓ Context Engineering Initialized Successfully!')}        ${chalk.green('║')}
+${chalk.green('╚' + '═'.repeat(boxWidth) + '╝')}
+
+${chalk.bold('Created:')}
+  ${chalk.cyan('•')} .claude/          ${chalk.gray('(context engineering system)')}
+  ${chalk.cyan('•')} CLAUDE.md         ${chalk.gray('(AI navigation guide)')}
+
+${chalk.bold('Available Commands:')}
+  ${chalk.cyan('•')} /rpi-research     ${chalk.gray('Research a feature')}
+  ${chalk.cyan('•')} /rpi-plan         ${chalk.gray('Create implementation plan')}
+  ${chalk.cyan('•')} /rpi-implement    ${chalk.gray('Execute with documentation')}
+  ${chalk.cyan('•')} /validate-all     ${chalk.gray('Run validation suite')}
+
+${chalk.bold('Next Steps:')}
+  ${chalk.white('1.')} Review ${chalk.cyan('CLAUDE.md')} and customize for your project
+  ${chalk.white('2.')} Run: ${chalk.cyan('@context-engineer "Discover workflows for this codebase"')}
+  ${chalk.white('3.')} Use ${chalk.cyan('/rpi-research')} for your first feature
+
+${chalk.gray('Documentation: https://github.com/SireJeff/claude-context-engineering-template')}
+`);
+}
+
+module.exports = { run };

package/lib/installer.js

@@ -0,0 +1,362 @@
+/**
+ * Claude Context Engineering - File Installer
+ *
+ * Handles copying template files and creating directory structure.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Directory structure for .claude/
+ */
+const DIRECTORY_STRUCTURE = [
+  'agents',
+  'commands',
+  'config',
+  'config/environments',
+  'context',
+  'context/workflows',
+  'indexes',
+  'indexes/agents',
+  'indexes/code',
+  'indexes/routing',
+  'indexes/search',
+  'indexes/workflows',
+  'knowledge',
+  'knowledge/sessions',
+  'knowledge/shared',
+  'knowledge/shared/decisions',
+  'knowledge/shared/patterns',
+  'plans',
+  'plans/active',
+  'plans/completed',
+  'research',
+  'research/active',
+  'research/completed',
+  'schemas',
+  'standards',
+  'team',
+  'ci-templates',
+  'ci-templates/github-actions',
+  'tools',
+  'tools/bin',
+  'tools/lib',
+];
+
+/**
+ * Create the .claude directory structure
+ */
+async function createDirectoryStructure(targetDir, config = {}) {
+  const claudeDir = path.join(targetDir, '.claude');
+
+  // Create main .claude directory
+  if (!fs.existsSync(claudeDir)) {
+    fs.mkdirSync(claudeDir, { recursive: true });
+  }
+
+  let dirsCreated = 0;
+
+  // Filter directories based on features
+  let dirsToCreate = [...DIRECTORY_STRUCTURE];
+
+  if (!config.features?.ci) {
+    dirsToCreate = dirsToCreate.filter(d => !d.startsWith('ci-templates'));
+  }
+  if (!config.features?.team) {
+    dirsToCreate = dirsToCreate.filter(d => !d.startsWith('team') && !d.includes('knowledge'));
+  }
+  if (!config.features?.analytics) {
+    dirsToCreate = dirsToCreate.filter(d => !d.startsWith('analytics'));
+  }
+
+  // Create each directory
+  for (const dir of dirsToCreate) {
+    const fullPath = path.join(claudeDir, dir);
+    if (!fs.existsSync(fullPath)) {
+      fs.mkdirSync(fullPath, { recursive: true });
+      dirsCreated++;
+    }
+  }
+
+  return dirsCreated;
+}
+
+/**
+ * Copy template files from the bundled templates
+ */
+async function copyTemplates(targetDir, config = {}) {
+  const claudeDir = path.join(targetDir, '.claude');
+  const templatesDir = path.join(__dirname, '..', 'templates', 'base');
+
+  let filesCopied = 0;
+
+  // Check if templates exist
+  if (!fs.existsSync(templatesDir)) {
+    // If no bundled templates, create minimal files
+    filesCopied = await createMinimalFiles(claudeDir, config);
+    return filesCopied;
+  }
+
+  // Copy all files from templates
+  filesCopied = await copyDirectory(templatesDir, claudeDir);
+
+  return filesCopied;
+}
+
+/**
+ * Recursively copy a directory
+ */
+async function copyDirectory(src, dest) {
+  let count = 0;
+
+  if (!fs.existsSync(src)) {
+    return count;
+  }
+
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      if (!fs.existsSync(destPath)) {
+        fs.mkdirSync(destPath, { recursive: true });
+      }
+      count += await copyDirectory(srcPath, destPath);
+    } else {
+      // Copy file
+      fs.copyFileSync(srcPath, destPath);
+      count++;
+    }
+  }
+
+  return count;
+}
+
+/**
+ * Create minimal files when no templates are bundled
+ */
+async function createMinimalFiles(claudeDir, config = {}) {
+  let count = 0;
+
+  // README.md
+  const readmeContent = `# .claude Configuration - ${config.projectName || 'Project'}
+
+This directory contains the Claude Context Engineering system.
+
+## Quick Start
+
+1. Load workflow index: Read \`.claude/context/WORKFLOW_INDEX.md\`
+2. Use RPI workflow: /rpi-research → /rpi-plan → /rpi-implement
+3. Validate changes: /verify-docs-current
+
+## Configuration
+
+- **Agents**: ${config.features?.agents ? '6 specialized agents' : 'disabled'}
+- **Commands**: ${config.features?.rpi ? 'RPI workflow + validation' : 'basic'}
+- **Context Budget**: 200k tokens max, target <40%
+
+*Generated by create-claude-context*
+`;
+  fs.writeFileSync(path.join(claudeDir, 'README.md'), readmeContent);
+  count++;
+
+  // settings.json
+  const settingsContent = {
+    '$schema': './schemas/settings.schema.json',
+    version: '1.0.0',
+    project: {
+      name: config.projectName || 'my-project',
+      status: 'development'
+    },
+    context: {
+      maxTokens: 200000,
+      targetUtilization: 0.4
+    },
+    validation: {
+      lineAccuracyThreshold: 60,
+      onCommit: true
+    }
+  };
+  fs.writeFileSync(
+    path.join(claudeDir, 'settings.json'),
+    JSON.stringify(settingsContent, null, 2)
+  );
+  count++;
+
+  // WORKFLOW_INDEX.md
+  const workflowIndexContent = `# Workflow Index
+
+## Primary Workflows
+
+| Workflow | Entry Point | Description |
+|----------|-------------|-------------|
+| *To be discovered* | - | Run @context-engineer to populate |
+
+## Quick Reference
+
+- Use \`/rpi-research\` to discover workflows
+- Use \`@context-engineer\` for initial setup
+
+*Run @context-engineer "Discover workflows for this codebase" to populate this index.*
+`;
+  fs.writeFileSync(
+    path.join(claudeDir, 'context', 'WORKFLOW_INDEX.md'),
+    workflowIndexContent
+  );
+  count++;
+
+  // RPI_WORKFLOW_PLAN.md
+  const rpiContent = `# RPI (Research, Plan, Implement) Workflow
+
+## Phase 1: RESEARCH (/rpi-research)
+- Explore codebase using parallel agents
+- Output: Research document in \`.claude/research/active/\`
+
+## Phase 2: PLAN (/rpi-plan)
+- Create implementation blueprint with file:line precision
+- Output: Plan document in \`.claude/plans/active/\`
+
+## Phase 3: IMPLEMENT (/rpi-implement)
+- Execute with atomic changes
+- ONE CHANGE → ONE TEST → ONE COMMIT
+
+## Context Budget
+- Research: 25-30%
+- Plan: 20-25%
+- Implement: 30-40%
+`;
+  fs.writeFileSync(path.join(claudeDir, 'RPI_WORKFLOW_PLAN.md'), rpiContent);
+  count++;
+
+  // Create placeholder files for research and plans
+  const researchTemplate = `# Research Template
+
+Use this template for RPI Research phase.
+
+## Objective
+[What you're researching]
+
+## Files Explored
+| File | Lines | Findings |
+|------|-------|----------|
+
+## Summary
+[150 words max]
+`;
+  fs.writeFileSync(
+    path.join(claudeDir, 'research', 'RESEARCH_TEMPLATE.md'),
+    researchTemplate
+  );
+  count++;
+
+  const planTemplate = `# Plan Template
+
+Use this template for RPI Plan phase.
+
+## Research Summary
+[From Phase 1]
+
+## Files to Modify
+| File | Lines | Change | Risk |
+|------|-------|--------|------|
+
+## Steps
+1. Step 1
+2. Step 2
+
+## Rollback Plan
+- Revert: \`git revert HEAD\`
+`;
+  fs.writeFileSync(
+    path.join(claudeDir, 'plans', 'PLAN_TEMPLATE.md'),
+    planTemplate
+  );
+  count++;
+
+  return count;
+}
+
+/**
+ * Create CLAUDE.md at project root
+ */
+async function createClaudeMd(targetDir, config = {}, techStack = {}) {
+  const claudeMdPath = path.join(targetDir, 'CLAUDE.md');
+
+  // Check for template
+  const templatePath = path.join(__dirname, '..', 'templates', 'CLAUDE.md.template');
+
+  let content;
+
+  if (fs.existsSync(templatePath)) {
+    content = fs.readFileSync(templatePath, 'utf8');
+  } else {
+    // Create minimal CLAUDE.md
+    content = `# CLAUDE.md - ${config.projectName || 'Project'}
+
+This file provides guidance to Claude Code when working with this repository.
+
+---
+
+## Project Identity
+
+**Platform:** ${config.projectName || 'Project'} application
+**Tech Stack:** ${techStack.summary || techStack.stack || 'Not detected'}
+**Status:** Development
+
+---
+
+## Essential Commands
+
+### Development
+\`\`\`bash
+${techStack.commands?.install || 'npm install'}
+${techStack.commands?.dev || 'npm run dev'}
+\`\`\`
+
+### Testing
+\`\`\`bash
+${techStack.commands?.test || 'npm test'}
+\`\`\`
+
+---
+
+## Navigation Rules
+
+### High-Level Task
+1. Start: [.claude/context/WORKFLOW_INDEX.md](./.claude/context/WORKFLOW_INDEX.md)
+2. Load relevant workflow
+3. Implement with context
+
+### Feature Development
+1. /rpi-research - Explore codebase
+2. /rpi-plan - Create blueprint
+3. /rpi-implement - Execute with tests
+
+---
+
+## Documentation System
+
+**Navigation:** 3-level chain (CLAUDE.md → Category → Domain → Detail)
+**Validation:** Run /verify-docs-current after modifications
+**RPI Workflow:** /rpi-research → /rpi-plan → /rpi-implement
+
+See: [.claude/RPI_WORKFLOW_PLAN.md](./.claude/RPI_WORKFLOW_PLAN.md)
+
+---
+
+*Generated by create-claude-context*
+`;
+  }
+
+  fs.writeFileSync(claudeMdPath, content);
+}
+
+module.exports = {
+  createDirectoryStructure,
+  copyTemplates,
+  createClaudeMd,
+  DIRECTORY_STRUCTURE,
+};