create-universal-ai-context 2.4.0 → 2.6.0-final

package/README.md

@@ -1,294 +1,331 @@
-# 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-universal-ai-context                    # Auto-detect and generate for all tools
-
-# Select specific AI tools
-npx create-universal-ai-context --ai claude        # Claude Code only
-npx create-universal-ai-context --ai copilot       # GitHub Copilot only
-npx create-universal-ai-context --ai cline         # Cline only
-npx create-universal-ai-context --ai antigravity   # Antigravity only
-npx create-universal-ai-context --ai all           # All tools (default)
-
-# Analysis modes
-npx create-universal-ai-context --static           # Force static analysis only
-npx create-universal-ai-context --force-ai         # Require Claude Code session
-
-# Other options
-npx create-universal-ai-context --yes              # Accept all defaults
-npx create-universal-ai-context --dry-run          # Preview without changes
-npx create-universal-ai-context my-project         # Create in new directory
-```
-
-## Subcommands
-
-```bash
-# Generate context for specific tools
-npx create-universal-ai-context generate --ai copilot
-
-# Check installation status
-npx create-universal-ai-context status
-
-# Migrate from v1.x
-npx create-universal-ai-context migrate
-
-# Check documentation drift
-npx create-universal-ai-context drift --all           # Check all docs
-npx create-universal-ai-context drift --file README.md  # Check specific file
-npx create-universal-ai-context drift --fix           # Auto-fix issues
-npx create-universal-ai-context drift --strict        # Exit 1 on issues (CI)
-```
-
-## Cross-Tool Sync
-
-Keep all AI tool contexts synchronized automatically:
-
-```bash
-# Check sync status
-npx create-universal-ai-context sync:check
-
-# Sync all tools from codebase
-npx create-universal-ai-context sync:all
-
-# Propagate from specific tool
-npx create-universal-ai-context sync:from claude --strategy source_wins
-
-# Resolve conflicts
-npx create-universal-ai-context sync:resolve --strategy regenerate_all
-
-# View sync history
-npx create-universal-ai-context sync:history
-
-# Install git hooks for automatic sync
-npx create-universal-ai-context hooks:install
-```
-
-**Conflict Strategies:**
-- `source_wins` - Changed tool's context wins
-- `regenerate_all` - Regenerate all from codebase
-- `newest` - Most recently modified wins
-- `manual` - Require manual resolution
-
-## Automation Scripts
-
-The generated `.ai-context/` directory includes automation that keeps documentation synchronized:
-
-### Generators
-
-**Code Mapper** (`.ai-context/automation/generators/code-mapper.js`)
-- Scans workflow files for file:line references
-- Builds CODE_TO_WORKFLOW_MAP.md (reverse index of code → docs)
-- Shows which workflows reference each file
-- Helps identify what needs updating after code changes
-
-**Index Builder** (`.ai-context/automation/generators/index-builder.js`)
-- Regenerates category indexes automatically
-- Updates navigation indexes with accurate counts
-- Scans workflows, agents, and commands for metadata
-
-### Git Hooks
-
-**Pre-Commit Hook**
-- Validates before allowing commits
-- Warns if code changes might affect documentation
-- Optionally blocks commits if docs are stale
-
-**Post-Commit Hook**
-- Rebuilds CODE_TO_WORKFLOW_MAP.md in background
-- Updates file hashes for change tracking
-- Keeps indexes synchronized
-
-### Install Hooks
-
-```bash
-# Copy hooks to .git/hooks/
-cp .ai-context/automation/hooks/pre-commit.sh .git/hooks/pre-commit
-cp .ai-context/automation/hooks/post-commit.sh .git/hooks/post-commit
-chmod +x .git/hooks/pre-commit .git/hooks/post-commit
-```
-
-### Run Manually
-
-```bash
-# Regenerate code-to-workflow map
-node .ai-context/automation/generators/code-mapper.js
-
-# Rebuild all indexes
-node .ai-context/automation/generators/index-builder.js
-
-# Dry-run to preview
-node .ai-context/automation/generators/code-mapper.js --dry-run
-```
-
-### Configuration
-
-Control automation via `.ai-context/automation/config.json`:
-- Enable/disable generators
-- Configure hook behavior
-- Set drift check sensitivity
-- Toggle blocking on stale documentation
-
----
-
-## Existing Documentation Detection
-
-The CLI automatically detects existing AI context files:
-
-```bash
-npx create-universal-ai-context
-
-# Found existing documentation: Claude context (v1), README.md
-# ? How would you like to proceed?
-#   > Merge: Use existing docs as base, add new structure (recommended)
-#     Fresh: Start fresh but import key values
-#     Overwrite: Replace everything with new templates
-#     Skip: Cancel initialization
-```
-
-### Merge Mode Options
-
-```bash
-npx create-universal-ai-context --mode merge          # Preserve customizations (default)
-npx create-universal-ai-context --mode fresh          # New structure, keep values
-npx create-universal-ai-context --mode overwrite      # Replace everything
-npx create-universal-ai-context --preserve-custom     # Keep user customizations
-npx create-universal-ai-context --update-refs         # Auto-fix line numbers
-npx create-universal-ai-context --backup              # Create backup first
-```
-
-## 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-universal-ai-context -t python-fastapi
-npx create-universal-ai-context -t python-django
-npx create-universal-ai-context -t node-express
-npx create-universal-ai-context -t node-nestjs
-npx create-universal-ai-context -t typescript-nextjs
-npx create-universal-ai-context -t go-gin
-npx create-universal-ai-context -t rust-actix
-npx create-universal-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-universal-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)
+# create-universal-ai-context
+
+> **⚠️ DEPRECATION NOTICE**
+>
+> This package is **deprecated** as of v3.0.0. Please migrate to the unified [`ai-context`](../ai-context/) package.
+>
+> **Migration Guide:** [docs/MIGRATE_TO_UNIFIED.md](../../docs/MIGRATE_TO_UNIFIED.md)
+>
+> **Support:** Security updates only until **2026-06-01**
+>
+> ---
+
+Universal AI context engineering for any codebase. Generates optimized context for **Claude Code**, **GitHub Copilot**, **Cline**, **Antigravity**, **Windsurf**, **Aider**, and **Continue**.
+
+![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 |
+| **Windsurf** | `.windsurf/rules.md` | XML-tagged rules for Windsurf Cascade AI |
+| **Aider** | `.aider.conf.yml` | Configuration for terminal-based pair programming |
+| **Continue** | `.continue/config.json` | Configuration with slash commands for VS Code autopilot |
+| **MCP Server** | `.ai-context.db` | SQLite + vector database for MCP integrations |
+
+## CLI Options
+
+```bash
+# Basic usage
+npx create-universal-ai-context                    # Auto-detect and generate for all tools
+
+# Select specific AI tools
+npx create-universal-ai-context --ai claude        # Claude Code only
+npx create-universal-ai-context --ai copilot       # GitHub Copilot only
+npx create-universal-ai-context --ai cline         # Cline only
+npx create-universal-ai-context --ai antigravity   # Antigravity only
+npx create-universal-ai-context --ai windsurf      # Windsurf only
+npx create-universal-ai-context --ai aider         # Aider only
+npx create-universal-ai-context --ai continue      # Continue only
+npx create-universal-ai-context --ai all           # All tools (default)
+
+# Analysis modes
+npx create-universal-ai-context --static           # Force static analysis only
+npx create-universal-ai-context --force-ai         # Require Claude Code session
+
+# Other options
+npx create-universal-ai-context --yes              # Accept all defaults
+npx create-universal-ai-context --dry-run          # Preview without changes
+npx create-universal-ai-context my-project         # Create in new directory
+```
+
+## Subcommands
+
+```bash
+# Generate context for specific tools
+npx create-universal-ai-context generate --ai copilot
+
+# Check installation status
+npx create-universal-ai-context status
+
+# Generate MCP server artifacts from database
+npx create-ai-context mcp:sync --force
+
+# Migrate from v1.x
+npx create-universal-ai-context migrate
+
+# Check documentation drift
+npx create-universal-ai-context drift --all           # Check all docs
+npx create-universal-ai-context drift --file README.md  # Check specific file
+npx create-universal-ai-context drift --fix           # Auto-fix issues
+npx create-universal-ai-context drift --strict        # Exit 1 on issues (CI)
+```
+
+## Cross-Tool Sync
+
+Keep all AI tool contexts synchronized automatically:
+
+```bash
+# Check sync status
+npx create-universal-ai-context sync:check
+
+# Sync all tools from codebase
+npx create-universal-ai-context sync:all
+
+# Propagate from specific tool
+npx create-universal-ai-context sync:from claude --strategy source_wins
+
+# Resolve conflicts
+npx create-universal-ai-context sync:resolve --strategy regenerate_all
+
+# View sync history
+npx create-universal-ai-context sync:history
+
+# Install git hooks for automatic sync
+npx create-universal-ai-context hooks:install
+```
+
+**Conflict Strategies:**
+- `source_wins` - Changed tool's context wins
+- `regenerate_all` - Regenerate all from codebase
+- `newest` - Most recently modified wins
+- `manual` - Require manual resolution
+
+## Automation Scripts
+
+The generated `.ai-context/` directory includes automation that keeps documentation synchronized:
+
+### Generators
+
+**Code Mapper** (`.ai-context/automation/generators/code-mapper.js`)
+- Scans workflow files for file:line references
+- Builds CODE_TO_WORKFLOW_MAP.md (reverse index of code → docs)
+- Shows which workflows reference each file
+- Helps identify what needs updating after code changes
+
+**Index Builder** (`.ai-context/automation/generators/index-builder.js`)
+- Regenerates category indexes automatically
+- Updates navigation indexes with accurate counts
+- Scans workflows, agents, and commands for metadata
+
+### Git Hooks
+
+**Pre-Commit Hook**
+- Validates before allowing commits
+- Warns if code changes might affect documentation
+- Optionally blocks commits if docs are stale
+
+**Post-Commit Hook**
+- Rebuilds CODE_TO_WORKFLOW_MAP.md in background
+- Updates file hashes for change tracking
+- Keeps indexes synchronized
+
+### Install Hooks
+
+```bash
+# Copy hooks to .git/hooks/
+cp .ai-context/automation/hooks/pre-commit.sh .git/hooks/pre-commit
+cp .ai-context/automation/hooks/post-commit.sh .git/hooks/post-commit
+chmod +x .git/hooks/pre-commit .git/hooks/post-commit
+```
+
+### Run Manually
+
+```bash
+# Regenerate code-to-workflow map
+node .ai-context/automation/generators/code-mapper.js
+
+# Rebuild all indexes
+node .ai-context/automation/generators/index-builder.js
+
+# Dry-run to preview
+node .ai-context/automation/generators/code-mapper.js --dry-run
+```
+
+### Configuration
+
+Control automation via `.ai-context/automation/config.json`:
+- Enable/disable generators
+- Configure hook behavior
+- Set drift check sensitivity
+- Toggle blocking on stale documentation
+
+---
+
+## Existing Documentation Detection
+
+The CLI automatically detects existing AI context files:
+
+```bash
+npx create-universal-ai-context
+
+# Found existing documentation: Claude context (v1), README.md
+# ? How would you like to proceed?
+#   > Merge: Use existing docs as base, add new structure (recommended)
+#     Fresh: Start fresh but import key values
+#     Overwrite: Replace everything with new templates
+#     Skip: Cancel initialization
+```
+
+### Merge Mode Options
+
+```bash
+npx create-universal-ai-context --mode merge          # Preserve customizations (default)
+npx create-universal-ai-context --mode fresh          # New structure, keep values
+npx create-universal-ai-context --mode overwrite      # Replace everything
+npx create-universal-ai-context --preserve-custom     # Keep user customizations
+npx create-universal-ai-context --update-refs         # Auto-fix line numbers
+npx create-universal-ai-context --backup              # Create backup first
+```
+
+## MCP Server (Database-Backed Context)
+
+The MCP server provides a SQLite + vector database backend for AI context, with cross-tool exports and semantic search.
+
+```bash
+# Initialize the database
+npx create-ai-context mcp:init
+
+# Start the MCP server (for Claude Desktop)
+npx create-ai-context mcp:start
+
+# Export to all AI tools
+npx create-ai-context mcp:sync --force
+```
+
+See the MCP server docs in [`packages/ai-context-mcp-server`](../ai-context-mcp-server/README.md) for full configuration details.
+
+## 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-universal-ai-context -t python-fastapi
+npx create-universal-ai-context -t python-django
+npx create-universal-ai-context -t node-express
+npx create-universal-ai-context -t node-nestjs
+npx create-universal-ai-context -t typescript-nextjs
+npx create-universal-ai-context -t go-gin
+npx create-universal-ai-context -t rust-actix
+npx create-universal-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-universal-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)