create-universal-ai-context 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 SireJeff
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,171 @@
+# create-universal-ai-context
+
+Universal AI context engineering for any codebase. Generates optimized context for **Claude Code**, **GitHub Copilot**, **Cline**, **Antigravity**, and more.
+
+![npm](https://img.shields.io/npm/v/create-universal-ai-context)
+![npm downloads](https://img.shields.io/npm/dm/create-universal-ai-context)
+
+## Quick Start
+
+```bash
+npx create-universal-ai-context
+```
+
+That's it. The CLI automatically:
+1. Detects your tech stack (Express, FastAPI, Next.js, Django, Rails, NestJS, etc.)
+2. Analyzes entry points and workflows
+3. Generates context files for all supported AI tools
+
+## AI Tools Supported
+
+| Tool | Output | Description |
+|------|--------|-------------|
+| **Claude Code** | `AI_CONTEXT.md` + `.ai-context/` | Full context engineering system |
+| **GitHub Copilot** | `.github/copilot-instructions.md` | Copilot workspace instructions |
+| **Cline** | `.clinerules` | Cline rules file |
+| **Antigravity** | `.agent/` | Identity, architecture, workflows, skills |
+
+## CLI Options
+
+```bash
+# Basic usage
+npx create-ai-context                    # Auto-detect and generate for all tools
+
+# Select specific AI tools
+npx create-ai-context --ai claude        # Claude Code only
+npx create-ai-context --ai copilot       # GitHub Copilot only
+npx create-ai-context --ai cline         # Cline only
+npx create-ai-context --ai antigravity   # Antigravity only
+npx create-ai-context --ai all           # All tools (default)
+
+# Analysis modes
+npx create-ai-context --static           # Force static analysis only
+npx create-ai-context --force-ai         # Require Claude Code session
+
+# Other options
+npx create-ai-context --yes              # Accept all defaults
+npx create-ai-context --dry-run          # Preview without changes
+npx create-ai-context my-project         # Create in new directory
+```
+
+## Subcommands
+
+```bash
+# Generate context for specific tools
+npx create-ai-context generate --ai copilot
+
+# Check installation status
+npx create-ai-context status
+
+# Migrate from v1.x
+npx create-ai-context migrate
+```
+
+## What Gets Analyzed
+
+| Analysis | Description |
+|----------|-------------|
+| **Entry Points** | API routes, CLI handlers, event listeners |
+| **Workflows** | Business logic patterns (auth, payments, etc.) |
+| **Architecture** | Directory structure, layers, dependencies |
+| **Tech Stack** | Languages, frameworks, package managers |
+| **LOC** | Lines of code with code/comments/blank breakdown |
+
+## Execution Modes
+
+| Mode | Condition | Capabilities |
+|------|-----------|--------------|
+| **full-ai** | Claude Code + API key | AI-enhanced analysis |
+| **hybrid** | Claude Code (no API) | Static + AI handoff |
+| **standalone** | No Claude Code | Static analysis only |
+
+## Generated Structure
+
+```
+your-project/
+├── AI_CONTEXT.md                    # Universal entry point
+├── .ai-context/                     # Context engineering system
+│   ├── agents/                      # 6 specialized agents
+│   ├── commands/                    # 11 slash commands
+│   ├── context/
+│   │   ├── workflows/               # Auto-generated workflow docs
+│   │   ├── ARCHITECTURE_SNAPSHOT.md
+│   │   └── CODE_TO_WORKFLOW_MAP.md
+│   └── indexes/                     # Navigation hierarchy
+├── .github/
+│   └── copilot-instructions.md      # GitHub Copilot
+├── .clinerules                      # Cline
+└── .agent/                          # Antigravity
+    ├── rules/
+    ├── workflows/
+    └── skills/
+```
+
+## Tech Stack Presets
+
+```bash
+npx create-ai-context -t python-fastapi
+npx create-ai-context -t python-django
+npx create-ai-context -t node-express
+npx create-ai-context -t node-nestjs
+npx create-ai-context -t typescript-nextjs
+npx create-ai-context -t go-gin
+npx create-ai-context -t rust-actix
+npx create-ai-context -t ruby-rails
+```
+
+## Features
+
+### RPI Workflow
+- `/rpi-research` - Systematic codebase exploration
+- `/rpi-plan` - Implementation blueprints with file:line precision
+- `/rpi-implement` - Atomic changes with continuous testing
+
+### Specialized Agents
+- `@context-engineer` - Setup and maintenance
+- `@core-architect` - System design
+- `@database-ops` - Database operations
+- `@api-developer` - API development
+- `@integration-hub` - External services
+- `@deployment-ops` - CI/CD and infrastructure
+
+## Migration from v1.x
+
+If you have an existing `.claude/` directory:
+
+```bash
+npx create-ai-context migrate
+```
+
+This will:
+- Rename `.claude/` to `.ai-context/`
+- Rename `CLAUDE.md` to `AI_CONTEXT.md`
+- Generate additional AI tool outputs
+
+## Requirements
+
+- Node.js 18+
+
+## Related Packages
+
+- [`claude-context`](https://www.npmjs.com/package/claude-context) - CLI tools for validation, sync, and diagnostics
+- [`claude-context-plugin`](https://www.npmjs.com/package/claude-context-plugin) - Claude Code plugin with RPI workflow
+
+## Development
+
+```bash
+git clone https://github.com/SireJeff/claude-context-engineering-template.git
+cd claude-context-engineering-template/packages/create-ai-context
+npm install
+npm test
+```
+
+## License
+
+MIT
+
+## Links
+
+- [GitHub](https://github.com/SireJeff/claude-context-engineering-template)
+- [Documentation](https://github.com/SireJeff/claude-context-engineering-template#readme)
+- [Issues](https://github.com/SireJeff/claude-context-engineering-template/issues)

package/bin/create-ai-context.js

@@ -0,0 +1,337 @@
+#!/usr/bin/env node
+
+/**
+ * create-ai-context CLI
+ *
+ * Universal AI Context Engineering - Set up context for Claude, Copilot, Cline, Antigravity, and more.
+ *
+ * Usage:
+ *   npx create-ai-context                      # Initialize in current directory
+ *   npx create-ai-context my-project           # Initialize in new directory
+ *   npx create-ai-context --yes                # Skip prompts
+ *   npx create-ai-context --ai copilot         # Generate for specific tool
+ *   npx create-ai-context generate             # Regenerate context files
+ *   npx create-ai-context generate --ai cline  # Regenerate for specific tool
+ *   npx create-ai-context migrate              # Migrate from v1.x
+ */
+
+const { program } = require('commander');
+const chalk = require('chalk');
+const path = require('path');
+const fs = require('fs');
+const { run } = require('../lib');
+const { generateAll, getSupportedTools } = require('../lib/ai-context-generator');
+const { migrateV1ToV2, getMigrationStatus } = require('../lib/migrate');
+const { detectTechStack } = require('../lib/detector');
+const { analyzeCodebase } = require('../lib/static-analyzer');
+const { createSpinner } = require('../lib/spinner');
+const packageJson = require('../package.json');
+
+// ASCII Banner
+const banner = `
+${chalk.cyan('╔═══════════════════════════════════════════════════════════╗')}
+${chalk.cyan('║')}  ${chalk.bold.white('AI Context Engineering')} ${chalk.gray('v' + packageJson.version)}                        ${chalk.cyan('║')}
+${chalk.cyan('║')}  ${chalk.gray('Universal context for Claude, Copilot, Cline & more')}      ${chalk.cyan('║')}
+${chalk.cyan('╚═══════════════════════════════════════════════════════════╝')}
+`;
+
+// Supported AI tools
+const AI_TOOLS = ['claude', 'copilot', 'cline', 'antigravity', 'all'];
+
+// Parse AI tools helper
+function parseAiTools(toolsString) {
+  const tools = toolsString.split(',').map(t => t.trim().toLowerCase());
+  const invalid = tools.filter(t => !AI_TOOLS.includes(t));
+  if (invalid.length > 0) {
+    console.error(chalk.red(`\n✖ Error: Invalid AI tools: ${invalid.join(', ')}`));
+    console.error(chalk.gray(`  Valid options: ${AI_TOOLS.join(', ')}`));
+    process.exit(1);
+  }
+  return tools.includes('all') ? ['claude', 'copilot', 'cline', 'antigravity'] : tools;
+}
+
+program
+  .name('create-ai-context')
+  .description('Universal AI Context Engineering - Set up context for multiple AI coding assistants')
+  .version(packageJson.version);
+
+// Main init command (default)
+program
+  .argument('[project-name]', 'Name of the project (defaults to current directory name)')
+  .option('-y, --yes', 'Skip prompts and use defaults')
+  .option('--no-plugin', 'Skip plugin installation')
+  .option('-t, --template <preset>', 'Use a tech stack preset (python-fastapi, node-express, etc.)')
+  .option('--no-git', 'Skip git initialization')
+  .option('-n, --dry-run', 'Show what would be done without making changes')
+  .option('-v, --verbose', 'Show detailed output')
+  .option('--ai <tools>', 'Generate for specific AI tools (comma-separated: claude,copilot,cline,antigravity,all)', 'all')
+  .option('--force-ai', 'Force AI-enhanced mode (creates INIT_REQUEST.md)')
+  .option('--static', 'Force standalone mode (static analysis only, no AI setup)')
+  .option('--analyze-only', 'Run codebase analysis without installation')
+  .option('--monorepo', 'Initialize in monorepo mode with federation support')
+  .option('--federate', 'Run federation to generate context for subprojects')
+  .action(async (projectName, options) => {
+    console.log(banner);
+
+    const aiTools = parseAiTools(options.ai);
+
+    if (options.forceAi && options.static) {
+      console.error(chalk.red('\n✖ Error: --force-ai and --static are mutually exclusive'));
+      process.exit(1);
+    }
+
+    try {
+      await run({
+        projectName,
+        skipPrompts: options.yes,
+        installPlugin: options.plugin !== false,
+        template: options.template,
+        initGit: options.git !== false,
+        dryRun: options.dryRun,
+        verbose: options.verbose,
+        aiTools,
+        forceAi: options.forceAi,
+        forceStatic: options.static,
+        analyzeOnly: options.analyzeOnly,
+        monorepo: options.monorepo,
+        federate: options.federate
+      });
+    } catch (error) {
+      console.error(chalk.red('\n✖ Error:'), error.message);
+      if (options.verbose) {
+        console.error(chalk.gray(error.stack));
+      }
+      process.exit(1);
+    }
+  });
+
+// Generate subcommand - regenerate context files
+program
+  .command('generate')
+  .description('Regenerate AI context files for an existing project')
+  .option('--ai <tools>', 'Generate for specific AI tools (comma-separated)', 'all')
+  .option('-d, --dryRun', 'Show what would be done without making changes')
+  .option('-v, --verbose', 'Show detailed output')
+  .option('-p, --path <dir>', 'Project directory (defaults to current)', '.')
+  .action(async (options) => {
+    console.log(banner);
+
+    const projectRoot = path.resolve(options.path);
+    const aiTools = parseAiTools(options.ai);
+    const spinner = createSpinner();
+
+    // Check if project has .ai-context
+    const contextDir = path.join(projectRoot, '.ai-context');
+    if (!fs.existsSync(contextDir)) {
+      console.error(chalk.red('\n✖ Error: No .ai-context directory found.'));
+      console.error(chalk.gray('  Run `npx create-ai-context` first to initialize.'));
+      process.exit(1);
+    }
+
+    try {
+      // Detect tech stack
+      spinner.start('Detecting technology stack...');
+      const techStack = await detectTechStack(projectRoot);
+      spinner.succeed(`Detected: ${techStack.summary || 'Generic project'}`);
+
+      // Analyze codebase
+      spinner.start('Analyzing codebase...');
+      const analysis = await analyzeCodebase(projectRoot, { techStack });
+      analysis.techStack = techStack;
+      spinner.succeed(`Analyzed: ${analysis.summary?.totalFiles || 0} files`);
+
+      // Generate context files
+      spinner.start('Generating AI context files...');
+      const config = {
+        projectName: path.basename(projectRoot),
+        aiTools,
+        verbose: options.verbose
+      };
+
+      if (options.dryRun) {
+        spinner.info('Dry run - no files will be written');
+        console.log(chalk.gray('\nWould generate for:'));
+        aiTools.forEach(tool => {
+          console.log(chalk.gray(`  • ${tool}`));
+        });
+      } else {
+        const results = await generateAll(analysis, config, projectRoot, {
+          aiTools,
+          verbose: options.verbose
+        });
+
+        if (results.success) {
+          spinner.succeed(`Generated ${results.summary.files} files for ${results.summary.successful} AI tools`);
+
+          console.log(chalk.bold('\nGenerated files:'));
+          results.generated.forEach(g => {
+            console.log(chalk.green(`  ✓ ${g.displayName}`));
+            g.files.forEach(f => {
+              console.log(chalk.gray(`      ${f.relativePath}`));
+            });
+          });
+        } else {
+          spinner.warn(`Generated ${results.summary.successful}/${results.summary.total} tools`);
+          results.errors.forEach(e => {
+            console.error(chalk.red(`  ✖ ${e.adapter}: ${e.message || e.errors?.[0]?.message}`));
+          });
+        }
+      }
+    } catch (error) {
+      spinner.fail('Generation failed');
+      console.error(chalk.red('\n✖ Error:'), error.message);
+      if (options.verbose) {
+        console.error(chalk.gray(error.stack));
+      }
+      process.exit(1);
+    }
+  });
+
+// Migrate subcommand - upgrade from v1.x
+program
+  .command('migrate')
+  .description('Migrate from v1.x (.claude/) to v2.0 (.ai-context/)')
+  .option('-d, --dryRun', 'Show what would be done without making changes')
+  .option('--force', 'Overwrite existing v2.0 installation')
+  .option('--backup', 'Create backup of existing files')
+  .option('--no-update-refs', 'Skip updating internal references')
+  .option('-p, --path <dir>', 'Project directory (defaults to current)', '.')
+  .action(async (options) => {
+    console.log(banner);
+
+    const projectRoot = path.resolve(options.path);
+    const spinner = createSpinner();
+
+    // Check migration status
+    spinner.start('Checking installation...');
+    const status = getMigrationStatus(projectRoot);
+    spinner.succeed(`Status: ${status.message}`);
+
+    if (!status.needsMigration) {
+      console.log(chalk.green('\n✓ No migration needed.'));
+      process.exit(0);
+    }
+
+    // Show what will happen
+    console.log(chalk.bold('\nMigration plan:'));
+    if (status.details?.oldDir) {
+      console.log(chalk.cyan(`  • Rename .claude/ → .ai-context/`));
+    }
+    if (status.details?.oldFile) {
+      console.log(chalk.cyan(`  • Rename CLAUDE.md → AI_CONTEXT.md`));
+    }
+    if (options.updateRefs !== false) {
+      console.log(chalk.cyan(`  • Update internal references in files`));
+    }
+
+    if (options.dryRun) {
+      console.log(chalk.yellow('\n[dry-run] No changes will be made'));
+      process.exit(0);
+    }
+
+    // Perform migration
+    spinner.start('Migrating...');
+    try {
+      const result = await migrateV1ToV2(projectRoot, {
+        dryRun: false,
+        force: options.force,
+        backup: options.backup,
+        updateReferences: options.updateRefs !== false
+      });
+
+      if (result.success) {
+        spinner.succeed('Migration completed successfully');
+
+        console.log(chalk.bold('\nChanges made:'));
+        result.changes.forEach(change => {
+          if (change.type === 'rename') {
+            console.log(chalk.green(`  ✓ ${change.action} ${change.from} → ${change.to}`));
+          } else if (change.type === 'update') {
+            console.log(chalk.green(`  ✓ ${change.action} ${change.file}`));
+          } else if (change.type === 'backup') {
+            console.log(chalk.blue(`  ↺ ${change.action} ${change.from} → ${change.to}`));
+          }
+        });
+
+        if (result.warnings.length > 0) {
+          console.log(chalk.yellow('\nWarnings:'));
+          result.warnings.forEach(w => console.log(chalk.yellow(`  ⚠ ${w}`)));
+        }
+
+        console.log(chalk.bold('\nNext steps:'));
+        console.log(chalk.gray('  1. Review AI_CONTEXT.md for any needed updates'));
+        console.log(chalk.gray('  2. Run `npx create-ai-context generate` to regenerate AI tool files'));
+        console.log(chalk.gray('  3. Commit the changes'));
+      } else {
+        spinner.fail('Migration failed');
+        result.errors.forEach(e => {
+          console.error(chalk.red(`  ✖ ${e}`));
+        });
+        process.exit(1);
+      }
+    } catch (error) {
+      spinner.fail('Migration failed');
+      console.error(chalk.red('\n✖ Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+// Status subcommand - show current installation status
+program
+  .command('status')
+  .description('Show current AI context installation status')
+  .option('-p, --path <dir>', 'Project directory (defaults to current)', '.')
+  .action(async (options) => {
+    console.log(banner);
+
+    const projectRoot = path.resolve(options.path);
+
+    // Check migration status
+    const migrationStatus = getMigrationStatus(projectRoot);
+
+    console.log(chalk.bold('Installation Status:\n'));
+
+    // Version status
+    if (migrationStatus.status === 'none') {
+      console.log(chalk.yellow('  ○ Not initialized'));
+      console.log(chalk.gray('    Run `npx create-ai-context` to initialize\n'));
+    } else if (migrationStatus.status === 'v1') {
+      console.log(chalk.yellow('  ○ v1.x installation found'));
+      console.log(chalk.gray('    Run `npx create-ai-context migrate` to upgrade to v2.0\n'));
+    } else if (migrationStatus.status === 'v2') {
+      console.log(chalk.green('  ✓ v2.0 installation'));
+    } else if (migrationStatus.status === 'mixed') {
+      console.log(chalk.yellow('  ⚠ Mixed v1.x and v2.0 installation'));
+      console.log(chalk.gray('    Run `npx create-ai-context migrate --force` to clean up\n'));
+    }
+
+    // Check AI tool outputs
+    if (migrationStatus.status === 'v2' || migrationStatus.status === 'mixed') {
+      console.log(chalk.bold('\nAI Tool Outputs:'));
+
+      const tools = getSupportedTools();
+      for (const tool of tools) {
+        let outputPath;
+        if (tool.name === 'claude') {
+          outputPath = path.join(projectRoot, 'AI_CONTEXT.md');
+        } else if (tool.name === 'copilot') {
+          outputPath = path.join(projectRoot, '.github', 'copilot-instructions.md');
+        } else if (tool.name === 'cline') {
+          outputPath = path.join(projectRoot, '.clinerules');
+        } else if (tool.name === 'antigravity') {
+          outputPath = path.join(projectRoot, '.agent');
+        }
+
+        const exists = fs.existsSync(outputPath);
+        if (exists) {
+          console.log(chalk.green(`  ✓ ${tool.displayName} (${tool.outputPath})`));
+        } else {
+          console.log(chalk.gray(`  ○ ${tool.displayName} (not generated)`));
+        }
+      }
+
+      console.log(chalk.gray('\n  Run `npx create-ai-context generate` to regenerate'));
+    }
+  });
+
+program.parse();

package/lib/adapters/antigravity.js

@@ -0,0 +1,160 @@
+/**
+ * Antigravity Adapter
+ *
+ * Generates .agent/ directory with multiple files for Google Antigravity.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { renderMultiFileTemplate, buildContext } = require('../template-renderer');
+
+/**
+ * Adapter metadata
+ */
+const adapter = {
+  name: 'antigravity',
+  displayName: 'Antigravity',
+  description: 'Multi-file context for Google Antigravity',
+  outputType: 'multi-file',
+  outputPath: '.agent/'
+};
+
+/**
+ * Get output directory for Antigravity files
+ * @param {string} projectRoot - Project root directory
+ * @returns {string} Output directory path
+ */
+function getOutputPath(projectRoot) {
+  return path.join(projectRoot, '.agent');
+}
+
+/**
+ * Check if Antigravity output already exists
+ * @param {string} projectRoot - Project root directory
+ * @returns {boolean}
+ */
+function exists(projectRoot) {
+  return fs.existsSync(getOutputPath(projectRoot));
+}
+
+/**
+ * Generate Antigravity context files
+ * @param {object} analysis - Analysis results from static analyzer
+ * @param {object} config - Configuration from CLI
+ * @param {string} projectRoot - Project root directory
+ * @returns {object} Generation result
+ */
+async function generate(analysis, config, projectRoot) {
+  const result = {
+    success: false,
+    adapter: adapter.name,
+    files: [],
+    errors: []
+  };
+
+  try {
+    // Build context from analysis
+    const context = buildContext(analysis, config);
+
+    // Get template path
+    const templatePath = path.join(__dirname, '..', '..', 'templates', 'handlebars', 'antigravity.hbs');
+
+    // Render multi-file template
+    const files = renderMultiFileTemplate(templatePath, context);
+
+    // Create output directory
+    const outputDir = getOutputPath(projectRoot);
+    if (!fs.existsSync(outputDir)) {
+      fs.mkdirSync(outputDir, { recursive: true });
+    }
+
+    // Write each file
+    for (const file of files) {
+      const filePath = path.join(outputDir, file.filename);
+      const fileDir = path.dirname(filePath);
+
+      // Ensure directory exists
+      if (!fs.existsSync(fileDir)) {
+        fs.mkdirSync(fileDir, { recursive: true });
+      }
+
+      // Write file
+      fs.writeFileSync(filePath, file.content, 'utf-8');
+
+      result.files.push({
+        path: filePath,
+        relativePath: `.agent/${file.filename}`,
+        size: file.content.length
+      });
+    }
+
+    result.success = true;
+  } catch (error) {
+    result.errors.push({
+      message: error.message,
+      stack: error.stack
+    });
+  }
+
+  return result;
+}
+
+/**
+ * Validate Antigravity output
+ * @param {string} projectRoot - Project root directory
+ * @returns {object} Validation result
+ */
+function validate(projectRoot) {
+  const outputDir = getOutputPath(projectRoot);
+
+  if (!fs.existsSync(outputDir)) {
+    return {
+      valid: false,
+      error: '.agent/ directory not found'
+    };
+  }
+
+  // Check for required subdirectories
+  const requiredDirs = ['rules', 'workflows', 'skills'];
+  const missingDirs = [];
+
+  for (const dir of requiredDirs) {
+    if (!fs.existsSync(path.join(outputDir, dir))) {
+      missingDirs.push(dir);
+    }
+  }
+
+  if (missingDirs.length > 0) {
+    return {
+      valid: false,
+      error: `Missing directories: ${missingDirs.join(', ')}`
+    };
+  }
+
+  // Count files
+  let fileCount = 0;
+  const countFiles = (dir) => {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        countFiles(path.join(dir, entry.name));
+      } else {
+        fileCount++;
+      }
+    }
+  };
+  countFiles(outputDir);
+
+  return {
+    valid: true,
+    fileCount
+  };
+}
+
+module.exports = {
+  ...adapter,
+  getOutputPath,
+  exists,
+  generate,
+  validate
+};