create-claude-context 1.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,146 @@
+# create-claude-context
+
+Set up Claude Context Engineering for any project with a single command.
+
+## Quick Start
+
+```bash
+npx create-claude-context
+```
+
+Or with npm init:
+
+```bash
+npm init claude-context
+```
+
+## What It Does
+
+This CLI tool sets up a complete context engineering system for your codebase:
+
+1. **Creates `.claude/` directory** - Context engineering documentation
+2. **Creates `CLAUDE.md`** - Entry point for Claude Code
+3. **Detects tech stack** - Auto-configures for your project
+4. **Installs plugin** - Adds ongoing commands (optional)
+
+## Options
+
+```bash
+npx create-claude-context [project-name] [options]
+
+Options:
+  -y, --yes          Skip prompts, use defaults
+  --no-plugin        Skip Claude Code plugin installation
+  -t, --template     Use a tech stack preset
+  --no-git           Skip git initialization
+  --dry-run          Show what would be done
+  -v, --verbose      Show detailed output
+  -V, --version      Output version number
+  -h, --help         Display help
+```
+
+## Tech Stack Presets
+
+```bash
+# Python
+npx create-claude-context -t python-fastapi
+npx create-claude-context -t python-django
+
+# JavaScript/TypeScript
+npx create-claude-context -t node-express
+npx create-claude-context -t node-nestjs
+npx create-claude-context -t typescript-nextjs
+npx create-claude-context -t typescript-remix
+
+# Other Languages
+npx create-claude-context -t go-gin
+npx create-claude-context -t rust-actix
+npx create-claude-context -t ruby-rails
+npx create-claude-context -t java-spring
+npx create-claude-context -t csharp-dotnet
+npx create-claude-context -t php-laravel
+```
+
+## Features
+
+After setup, you get:
+
+### 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
+
+### Documentation System
+- 3-level index hierarchy
+- File:line references
+- Self-maintaining documentation
+- Validation commands
+
+## Directory Structure
+
+```
+your-project/
+├── CLAUDE.md                 # Entry point for Claude
+└── .claude/
+    ├── agents/               # Specialized agents
+    ├── commands/             # Slash commands
+    ├── context/              # Pre-computed knowledge
+    │   ├── workflows/        # Workflow documentation
+    │   └── WORKFLOW_INDEX.md # Master index
+    ├── indexes/              # Navigation hierarchy
+    ├── plans/                # Implementation plans
+    ├── research/             # Research documents
+    └── schemas/              # JSON validation
+```
+
+## Requirements
+
+- Node.js 18+
+- Claude Code CLI
+
+## Development
+
+```bash
+# Clone the repo
+git clone https://github.com/SireJeff/claude-context-engineering-template.git
+cd claude-context-engineering-template/packages/create-claude-context
+
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Run tests in watch mode
+npm run test:watch
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Run tests (`npm test`)
+4. Commit your changes (`git commit -m 'Add amazing feature'`)
+5. Push to the branch (`git push origin feature/amazing-feature`)
+6. Open a Pull Request
+
+## 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-claude-context.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+
+/**
+ * create-claude-context CLI
+ *
+ * Set up Claude Context Engineering for any project with a single command.
+ *
+ * Usage:
+ *   npx create-claude-context
+ *   npx create-claude-context my-project
+ *   npx create-claude-context --yes
+ */
+
+const { program } = require('commander');
+const chalk = require('chalk');
+const { run } = require('../lib');
+const packageJson = require('../package.json');
+
+// ASCII Banner
+const banner = `
+${chalk.cyan('╔═══════════════════════════════════════════════════════════╗')}
+${chalk.cyan('║')}  ${chalk.bold.white('Claude Context Engineering')}                               ${chalk.cyan('║')}
+${chalk.cyan('║')}  ${chalk.gray('Optimize AI-assisted development with pre-computed')}       ${chalk.cyan('║')}
+${chalk.cyan('║')}  ${chalk.gray('system knowledge and structured documentation.')}           ${chalk.cyan('║')}
+${chalk.cyan('╚═══════════════════════════════════════════════════════════╝')}
+`;
+
+program
+  .name('create-claude-context')
+  .description('Set up Claude Context Engineering for your project')
+  .version(packageJson.version)
+  .argument('[project-name]', 'Name of the project (defaults to current directory name)')
+  .option('-y, --yes', 'Skip prompts and use defaults')
+  .option('--no-plugin', 'Skip Claude Code plugin installation')
+  .option('-t, --template <preset>', 'Use a tech stack preset (python-fastapi, node-express, etc.)')
+  .option('--no-git', 'Skip git initialization')
+  .option('--dry-run', 'Show what would be done without making changes')
+  .option('-v, --verbose', 'Show detailed output')
+  .action(async (projectName, options) => {
+    console.log(banner);
+
+    try {
+      await run({
+        projectName,
+        skipPrompts: options.yes,
+        installPlugin: options.plugin !== false,
+        template: options.template,
+        initGit: options.git !== false,
+        dryRun: options.dryRun,
+        verbose: options.verbose
+      });
+    } catch (error) {
+      console.error(chalk.red('\n✖ Error:'), error.message);
+      if (options.verbose) {
+        console.error(chalk.gray(error.stack));
+      }
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/lib/detector.js

@@ -0,0 +1,373 @@
+/**
+ * Claude Context Engineering - Tech Stack Detector
+ *
+ * Auto-detects technology stack from project files.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { glob } = require('glob');
+
+/**
+ * Tech stack detection signatures
+ */
+const TECH_SIGNATURES = {
+  // Languages
+  languages: {
+    python: {
+      files: ['requirements.txt', 'pyproject.toml', 'setup.py', 'Pipfile', 'poetry.lock'],
+      extensions: ['.py'],
+    },
+    javascript: {
+      files: ['package.json', 'yarn.lock', 'pnpm-lock.yaml'],
+      extensions: ['.js', '.mjs', '.cjs'],
+    },
+    typescript: {
+      files: ['tsconfig.json'],
+      extensions: ['.ts', '.tsx'],
+    },
+    go: {
+      files: ['go.mod', 'go.sum'],
+      extensions: ['.go'],
+    },
+    rust: {
+      files: ['Cargo.toml', 'Cargo.lock'],
+      extensions: ['.rs'],
+    },
+    java: {
+      files: ['pom.xml', 'build.gradle', 'build.gradle.kts'],
+      extensions: ['.java'],
+    },
+    csharp: {
+      files: ['*.csproj', '*.sln'],
+      extensions: ['.cs'],
+    },
+    ruby: {
+      files: ['Gemfile', 'Gemfile.lock'],
+      extensions: ['.rb'],
+    },
+    php: {
+      files: ['composer.json', 'composer.lock'],
+      extensions: ['.php'],
+    },
+  },
+
+  // Frameworks
+  frameworks: {
+    // Python
+    fastapi: {
+      language: 'python',
+      patterns: ['fastapi', 'FastAPI', '@router', 'APIRouter'],
+      files: [],
+    },
+    django: {
+      language: 'python',
+      patterns: ['django.conf', 'INSTALLED_APPS', 'from django'],
+      files: ['manage.py'],
+    },
+    flask: {
+      language: 'python',
+      patterns: ['Flask(__name__)', '@app.route', 'from flask'],
+      files: [],
+    },
+
+    // JavaScript/TypeScript
+    react: {
+      language: 'javascript',
+      patterns: ['react', 'React', 'useState', 'useEffect'],
+      packageDeps: ['react', 'react-dom'],
+    },
+    nextjs: {
+      language: 'javascript',
+      patterns: ['next/'],
+      files: ['next.config.js', 'next.config.mjs'],
+      packageDeps: ['next'],
+    },
+    express: {
+      language: 'javascript',
+      patterns: ['express()', 'app.use', 'app.get', 'router.'],
+      packageDeps: ['express'],
+    },
+    nestjs: {
+      language: 'typescript',
+      patterns: ['@nestjs/', '@Controller', '@Injectable'],
+      packageDeps: ['@nestjs/core'],
+    },
+    vue: {
+      language: 'javascript',
+      patterns: ['<template>', 'Vue.'],
+      packageDeps: ['vue'],
+    },
+
+    // Go
+    gin: {
+      language: 'go',
+      patterns: ['gin.', 'gin-gonic'],
+      files: [],
+    },
+    echo: {
+      language: 'go',
+      patterns: ['echo.', 'labstack/echo'],
+      files: [],
+    },
+
+    // Ruby
+    rails: {
+      language: 'ruby',
+      patterns: ['Rails.application', 'ActionController', 'ActiveRecord'],
+      files: ['config/routes.rb'],
+    },
+
+    // Rust
+    actix: {
+      language: 'rust',
+      patterns: ['actix_web', 'actix-web'],
+      files: [],
+    },
+    axum: {
+      language: 'rust',
+      patterns: ['axum::'],
+      files: [],
+    },
+  },
+
+  // Databases
+  databases: {
+    postgresql: {
+      patterns: ['postgresql', 'postgres', 'psycopg', 'pg'],
+      envVars: ['DATABASE_URL', 'POSTGRES_'],
+    },
+    mysql: {
+      patterns: ['mysql', 'mariadb'],
+      envVars: ['MYSQL_'],
+    },
+    mongodb: {
+      patterns: ['mongodb', 'mongoose', 'pymongo'],
+      envVars: ['MONGO_'],
+    },
+    redis: {
+      patterns: ['redis', 'ioredis'],
+      envVars: ['REDIS_'],
+    },
+    sqlite: {
+      patterns: ['sqlite', 'sqlite3'],
+      files: ['*.db', '*.sqlite'],
+    },
+  },
+};
+
+/**
+ * Detect technology stack
+ */
+async function detectTechStack(projectRoot, options = {}) {
+  const { hint = null } = options;
+
+  const result = {
+    stack: '',
+    summary: '',
+    languages: [],
+    frameworks: [],
+    databases: [],
+    projectName: path.basename(projectRoot),
+    fileCount: 0,
+    loc: 0,
+  };
+
+  // If hint provided, use it
+  if (hint) {
+    result.stack = hint;
+    result.summary = hint;
+    return result;
+  }
+
+  // Detect languages
+  for (const [lang, signature] of Object.entries(TECH_SIGNATURES.languages)) {
+    // Check for signature files
+    for (const sigFile of signature.files) {
+      if (fs.existsSync(path.join(projectRoot, sigFile))) {
+        if (!result.languages.includes(lang)) {
+          result.languages.push(lang);
+        }
+        break;
+      }
+    }
+
+    // Check for file extensions
+    if (signature.extensions) {
+      for (const ext of signature.extensions) {
+        try {
+          const files = await glob(`**/*${ext}`, {
+            cwd: projectRoot,
+            ignore: ['node_modules/**', 'vendor/**', '.git/**', 'dist/**', 'build/**'],
+            nodir: true,
+          });
+
+          if (files.length > 0) {
+            if (!result.languages.includes(lang)) {
+              result.languages.push(lang);
+            }
+            result.fileCount += files.length;
+            break;
+          }
+        } catch {
+          // Ignore glob errors
+        }
+      }
+    }
+  }
+
+  // Detect frameworks
+  for (const [framework, signature] of Object.entries(TECH_SIGNATURES.frameworks)) {
+    // Check for package.json dependencies
+    if (signature.packageDeps) {
+      const pkgPath = path.join(projectRoot, 'package.json');
+      if (fs.existsSync(pkgPath)) {
+        try {
+          const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+          const allDeps = {
+            ...pkg.dependencies,
+            ...pkg.devDependencies,
+          };
+
+          for (const dep of signature.packageDeps) {
+            if (allDeps[dep]) {
+              if (!result.frameworks.includes(framework)) {
+                result.frameworks.push(framework);
+              }
+              break;
+            }
+          }
+        } catch {
+          // Ignore JSON parse errors
+        }
+      }
+    }
+
+    // Check for signature files
+    if (signature.files) {
+      for (const sigFile of signature.files) {
+        if (fs.existsSync(path.join(projectRoot, sigFile))) {
+          if (!result.frameworks.includes(framework)) {
+            result.frameworks.push(framework);
+          }
+          break;
+        }
+      }
+    }
+
+    // Check for patterns in source files (sample)
+    if (signature.patterns && result.languages.includes(signature.language)) {
+      // Sample a few source files
+      const ext = TECH_SIGNATURES.languages[signature.language]?.extensions?.[0];
+      if (ext) {
+        try {
+          const sampleFiles = await glob(`**/*${ext}`, {
+            cwd: projectRoot,
+            ignore: ['node_modules/**', 'vendor/**', '.git/**'],
+            nodir: true,
+          });
+
+          // Check first 5 files
+          for (const file of sampleFiles.slice(0, 5)) {
+            try {
+              const content = fs.readFileSync(path.join(projectRoot, file), 'utf8');
+
+              for (const pattern of signature.patterns) {
+                if (content.includes(pattern)) {
+                  if (!result.frameworks.includes(framework)) {
+                    result.frameworks.push(framework);
+                  }
+                  break;
+                }
+              }
+            } catch {
+              // Ignore file read errors
+            }
+          }
+        } catch {
+          // Ignore glob errors
+        }
+      }
+    }
+  }
+
+  // Detect databases
+  for (const [db, signature] of Object.entries(TECH_SIGNATURES.databases)) {
+    // Check environment files
+    const envFiles = ['.env', '.env.example', '.env.local'];
+    for (const envFile of envFiles) {
+      const envPath = path.join(projectRoot, envFile);
+      if (fs.existsSync(envPath)) {
+        try {
+          const content = fs.readFileSync(envPath, 'utf8');
+
+          if (signature.envVars) {
+            for (const envVar of signature.envVars) {
+              if (content.includes(envVar)) {
+                if (!result.databases.includes(db)) {
+                  result.databases.push(db);
+                }
+                break;
+              }
+            }
+          }
+        } catch {
+          // Ignore read errors
+        }
+      }
+    }
+
+    // Check for patterns in config files
+    if (signature.patterns) {
+      const configFiles = ['package.json', 'requirements.txt', 'pyproject.toml', 'Cargo.toml'];
+      for (const configFile of configFiles) {
+        const configPath = path.join(projectRoot, configFile);
+        if (fs.existsSync(configPath)) {
+          try {
+            const content = fs.readFileSync(configPath, 'utf8').toLowerCase();
+
+            for (const pattern of signature.patterns) {
+              if (content.includes(pattern.toLowerCase())) {
+                if (!result.databases.includes(db)) {
+                  result.databases.push(db);
+                }
+                break;
+              }
+            }
+          } catch {
+            // Ignore read errors
+          }
+        }
+      }
+    }
+  }
+
+  // Build stack string
+  const stackParts = [];
+  if (result.languages.length > 0) {
+    stackParts.push(result.languages.map(l => capitalize(l)).join(', '));
+  }
+  if (result.frameworks.length > 0) {
+    stackParts.push(result.frameworks.map(f => capitalize(f)).join(', '));
+  }
+  if (result.databases.length > 0) {
+    stackParts.push(result.databases.map(d => capitalize(d)).join(', '));
+  }
+
+  result.stack = stackParts.join(' + ') || 'Unknown';
+  result.summary = result.stack;
+
+  return result;
+}
+
+/**
+ * Capitalize first letter
+ */
+function capitalize(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+module.exports = {
+  detectTechStack,
+  TECH_SIGNATURES,
+};