create-universal-ai-context 2.0.0

package/templates/AI_CONTEXT.md.template

@@ -0,0 +1,245 @@
+# AI_CONTEXT.md - {{PROJECT_NAME}}
+
+This file provides guidance to AI coding assistants when working with code in this repository.
+
+---
+
+## Project Identity
+
+**Platform:** {{PROJECT_DESCRIPTION}}
+**Domain:** {{PRODUCTION_URL}}
+**Tech Stack:** {{TECH_STACK}}
+**Status:** {{PROJECT_STATUS}}
+
+**Quick Reference:**
+- **API:** {{API_URL}}
+- **Repo:** {{REPO_URL}}
+- **Deploy:** {{DEPLOYMENT_PLATFORM}}
+
+---
+
+## Essential Commands
+
+### Development
+```bash
+{{INSTALL_COMMAND}}
+{{DEV_START_COMMAND}}
+```
+
+### Testing
+```bash
+{{TEST_COMMAND}}                    # All tests
+{{TEST_E2E_COMMAND}}               # E2E only
+{{TEST_COVERAGE_COMMAND}}          # With coverage
+```
+
+### Database
+```bash
+{{MIGRATION_CREATE_COMMAND}}
+{{MIGRATION_RUN_COMMAND}}
+```
+
+### Deployment
+```bash
+{{DEPLOY_COMMAND}}
+```
+
+---
+
+## Navigation Rules
+
+### High-Level Task (Refactoring a Flow)
+**Example:** "{{EXAMPLE_REFACTOR_TASK}}"
+
+**Chain:**
+1. Start: [.ai-context/indexes/workflows/CATEGORY_INDEX.md](./.ai-context/indexes/workflows/CATEGORY_INDEX.md)
+2. Find: Relevant category
+3. Load: Domain index
+4. Detail: Workflow file
+5. Code: [.ai-context/indexes/code/DOMAIN_LAYER_INDEX.md](./.ai-context/indexes/code/DOMAIN_LAYER_INDEX.md)
+6. Implement: Use appropriate specialized agent
+
+**Context Budget:** ~40k tokens (20% of 200k window)
+
+---
+
+### Low-Level Task (Fix Hardcoded Value)
+**Example:** "{{EXAMPLE_LOWLEVEL_TASK}}"
+
+**Chain:**
+1. Start: Search Patterns section below
+2. Pattern: Use grep/find
+3. Verify: [.ai-context/indexes/code/REVERSE_INDEXES.md](./.ai-context/indexes/code/REVERSE_INDEXES.md)
+4. Fix: Direct file edits
+5. Validate: Run tests
+
+**Context Budget:** ~15k tokens (7.5% of 200k window)
+
+---
+
+### Feature Task (Add New Feature)
+**Example:** "{{EXAMPLE_FEATURE_TASK}}"
+
+**Chain:**
+1. Start: [.ai-context/indexes/routing/CATEGORY_INDEX.md](./.ai-context/indexes/routing/CATEGORY_INDEX.md)
+2. Route: [.ai-context/indexes/routing/HIGH_LEVEL_ROUTER.md](./.ai-context/indexes/routing/HIGH_LEVEL_ROUTER.md)
+3. Research: /rpi-research
+4. Plan: /rpi-plan
+5. Implement: /rpi-implement
+
+**Context Budget:** ~50k tokens (25% of 200k window)
+
+---
+
+## Search Patterns
+
+### Finding Configuration Values
+
+**Environment variables:**
+```bash
+{{CONFIG_SEARCH_PATTERN}}
+```
+
+**Hardcoded URLs/domains:**
+```bash
+{{URL_SEARCH_PATTERN}}
+```
+
+---
+
+### Finding Business Logic
+
+**Core Files:**
+{{CORE_FILES_LIST}}
+
+---
+
+### Finding Database Schema
+
+**Models:** {{MODELS_PATH}}
+**Migrations:** {{MIGRATIONS_PATH}}
+
+---
+
+### Finding External Integrations
+
+{{EXTERNAL_INTEGRATIONS_LIST}}
+
+---
+
+## System Architecture Mini-Map
+
+{{ARCHITECTURE_DIAGRAM}}
+
+---
+
+## Index Directory
+
+**3-Level Chain:** AI_CONTEXT.md → Category (5) → Domain (15) → Detail (53)
+
+**Level 1 - Categories:** [.ai-context/indexes/*/CATEGORY_INDEX.md](./.ai-context/indexes/)
+- Workflows, Code, Search, Agents, Routing
+
+**Level 2 - Domains:** [.ai-context/indexes/workflows/*.md](./.ai-context/indexes/workflows/)
+- {{WORKFLOW_DOMAINS_COUNT}} workflow domains, {{CODE_DOMAINS_COUNT}} code domains
+
+**Level 3 - Details:** [.ai-context/context/workflows/](./.ai-context/context/workflows/), [.ai-context/agents/](./.ai-context/agents/), [.ai-context/commands/](./.ai-context/commands/)
+- {{WORKFLOWS_COUNT}} workflows, {{AGENTS_COUNT}} agents, {{COMMANDS_COUNT}} commands
+
+---
+
+## Critical Constants
+
+### Domain & URLs
+{{CRITICAL_URLS}}
+
+### Business Constants
+{{BUSINESS_CONSTANTS}}
+
+---
+
+## Quick Reference
+
+**Understanding:** [ARCHITECTURE_SNAPSHOT.md](./.ai-context/context/ARCHITECTURE_SNAPSHOT.md), [workflows/CATEGORY_INDEX.md](./.ai-context/indexes/workflows/CATEGORY_INDEX.md), [KNOWN_GOTCHAS.md](./.ai-context/context/KNOWN_GOTCHAS.md)
+
+**Implementing:** [workflows/*.md](./.ai-context/context/workflows/), [CODE_TO_WORKFLOW_MAP.md](./.ai-context/context/CODE_TO_WORKFLOW_MAP.md)
+
+**Debugging:** {{DEBUGGING_QUICK_REFS}}
+
+---
+
+## Agent & Command Routing
+
+**Agents:** {{AGENT_ROUTING_TABLE}}
+**Full matrix:** [.ai-context/indexes/agents/router.md](./.ai-context/indexes/agents/router.md)
+
+**Commands:** /rpi-research, /rpi-plan, /rpi-implement, /verify-docs-current, /validate-all, /help, /collab, /analytics
+**All commands:** [.ai-context/commands/](./.ai-context/commands/)
+
+---
+
+## Gotcha Quick Reference
+
+### {{GOTCHA_CATEGORY_1}}
+{{GOTCHA_1_ITEMS}}
+
+### {{GOTCHA_CATEGORY_2}}
+{{GOTCHA_2_ITEMS}}
+
+**Full gotchas:** [.ai-context/context/KNOWN_GOTCHAS.md](./.ai-context/context/KNOWN_GOTCHAS.md)
+
+---
+
+## Documentation System
+
+**Navigation:** 3-level chain (AI_CONTEXT.md → Category → Domain → Detail)
+**Self-maintaining:** CODE_TO_WORKFLOW_MAP.md guides updates after code changes
+**Validation:** Run /verify-docs-current [file_path] after modifications
+**RPI Workflow:** /rpi-research → /rpi-plan → /rpi-implement
+
+**See:** [.ai-context/RPI_WORKFLOW_PLAN.md](./.ai-context/RPI_WORKFLOW_PLAN.md), [.ai-context/README.md](./.ai-context/README.md)
+
+---
+
+## Production
+
+**Platform:** {{PRODUCTION_PLATFORM}}
+**Services:** {{PRODUCTION_SERVICES}}
+**Monitoring:** {{MONITORING_COMMANDS}}
+
+---
+
+## Key Constraints
+
+**Migrations:** {{MIGRATION_CONSTRAINTS}}
+**Testing:** {{TESTING_CONSTRAINTS}}
+**Security:** {{SECURITY_CONSTRAINTS}}
+
+---
+
+## Maintenance
+
+**After changes:** Check CODE_TO_WORKFLOW_MAP.md → Update workflows → Run /verify-docs-current
+**Docs hub:** [.ai-context/README.md](./.ai-context/README.md)
+**RPI:** [.ai-context/RPI_WORKFLOW_PLAN.md](./.ai-context/RPI_WORKFLOW_PLAN.md)
+
+---
+
+## AI Tools Configuration
+
+This context is optimized for:
+- **Claude Code** - Full context reading
+- **GitHub Copilot** - See `.github/copilot-instructions.md`
+- **Cline** - See `.clinerules`
+- **Antigravity** - See `.agent/` directory
+
+---
+
+## Contact
+
+{{CONTACT_INFO}}
+
+---
+
+**Version:** 2.0 | **Last Updated:** {{DATE}} | **Context Target:** 200k
+**Architecture:** 3-Level Chain-of-Index | **Index Files:** {{INDEX_FILES_COUNT}}

package/templates/base/README.md

@@ -0,0 +1,257 @@
+# .claude Configuration - {{PROJECT_NAME}}
+
+This directory contains a comprehensive context engineering system for the {{PROJECT_NAME}} repository.
+
+**Configuration Summary**:
+- **Agents**: {{AGENTS_COUNT}} specialized agents (workflow-aligned)
+- **Commands**: {{COMMANDS_COUNT}} custom commands
+- **Workflows**: {{WORKFLOWS_COUNT}} documented workflows
+- **Context Budget**: 200k tokens max, target <40% utilization
+- **Output Budget**: 30k tokens max per response
+- **Last Updated**: {{DATE}}
+
+**System Benefits**:
+- <40% context utilization (vs 60%+ without this system)
+- 10× faster issue resolution with pre-computed knowledge
+- Self-maintaining documentation (zero drift)
+- Proactive bug discovery through validation
+
+---
+
+## Table of Contents
+
+1. [Agent Architecture](#agent-architecture)
+2. [Custom Commands](#custom-commands)
+3. [Context Documentation](#context-documentation)
+4. [RPI Workflow](#rpi-workflow)
+5. [Quick Start Guide](#quick-start-guide)
+6. [Self-Maintaining Documentation](#self-maintaining-documentation)
+
+---
+
+## Agent Architecture
+
+### Specialized Agents (Workflow-Aligned)
+
+| Agent | Primary Workflows | Use For |
+|-------|------------------|---------|
+| `context-engineer` | INITIALIZATION | Transform this template for any codebase |
+| {{AGENT_TABLE_ROWS}} |
+
+**Agent Location:** `.ai-context/agents/*.md`
+
+---
+
+## Custom Commands
+
+### RPI Workflow Commands (3)
+| Command | Description |
+|---------|-------------|
+| `/rpi-research` | Research phase - codebase exploration |
+| `/rpi-plan` | Plan phase - implementation blueprint |
+| `/rpi-implement` | Implement phase - execution with doc updates |
+
+### Validation Commands
+| Command | Description |
+|---------|-------------|
+| `/validate-all` | Complete validation suite |
+| `/verify-docs-current` | Documentation freshness validation |
+
+### System Commands (NEW in v1.1)
+| Command | Description |
+|---------|-------------|
+| `/help` | Comprehensive help system |
+| `/collab` | Team collaboration (handoffs, sync) |
+| `/analytics` | Local usage statistics |
+
+**Command Location:** `.ai-context/commands/*.md`
+
+---
+
+## Context Documentation
+
+### 3-Level Chain-of-Index Architecture
+
+**Purpose:** Minimize context usage through progressive loading
+
+**Level 1 - Category Indexes (5 files in `indexes/`):**
+| Category | Purpose | Load When |
+|----------|---------|-----------|
+| `workflows/CATEGORY_INDEX.md` | Workflow categories | Starting workflow task |
+| `code/CATEGORY_INDEX.md` | Domain × Layer overview | Finding code files |
+| `search/CATEGORY_INDEX.md` | Search strategies | Low-level debugging |
+| `agents/CATEGORY_INDEX.md` | Agent selection matrix | Choosing agent |
+| `routing/CATEGORY_INDEX.md` | Task routing | Classifying task type |
+
+**Level 2 - Domain Indexes:** See `indexes/workflows/*.md`, `indexes/code/*.md`
+
+**Level 3 - Detail Files:** workflows/, agents/, commands/
+
+### Pre-Computed Knowledge
+
+| File | Purpose |
+|------|---------|
+| `ARCHITECTURE_SNAPSHOT.md` | High-level system map |
+| `FILE_OWNERSHIP.md` | What each file does |
+| `INTEGRATION_POINTS.md` | External APIs |
+| `KNOWN_GOTCHAS.md` | Documented fixes and lessons |
+| `TESTING_MAP.md` | Test coverage mapping |
+
+---
+
+## RPI Workflow
+
+**Research-Plan-Implement** methodology for structured development.
+
+### Phases
+
+1. **RESEARCH** (`/rpi-research`)
+   - Use sub-agents to investigate
+   - Output: Research document in `research/active/`
+   - Context budget: 25-30%
+
+2. **PLAN** (`/rpi-plan`)
+   - Create implementation blueprint with file:line precision
+   - Output: Plan document in `plans/active/`
+   - Context budget: 20-25%
+
+3. **IMPLEMENT** (`/rpi-implement`)
+   - Execute with atomic changes
+   - ONE CHANGE → ONE TEST → ONE COMMIT
+   - Update documentation (mandatory)
+   - Context budget: 30-40%
+
+### Directory Structure
+
+```
+.ai-context/
+├── research/
+│   ├── active/           # Current research
+│   ├── completed/        # Archived research
+│   └── RESEARCH_TEMPLATE.md
+├── plans/
+│   ├── active/           # Current plans
+│   ├── completed/        # Archived plans
+│   └── PLAN_TEMPLATE.md
+├── context/
+│   ├── WORKFLOW_INDEX.md     # Primary entry point
+│   ├── CODE_TO_WORKFLOW_MAP.md
+│   └── workflows/            # Workflow detail files
+├── indexes/
+│   ├── workflows/        # Workflow category indexes
+│   ├── code/            # Code domain indexes
+│   ├── agents/          # Agent selection indexes
+│   ├── routing/         # Task routing indexes
+│   └── search/          # Search pattern indexes
+├── agents/              # Specialized agent definitions
+├── commands/            # Custom command definitions
+├── tools/               # CLI tooling (NEW v1.1)
+├── schemas/             # JSON validation schemas (NEW v1.1)
+├── config/              # Environment configurations (NEW v1.1)
+├── team/                # Team collaboration config (NEW v1.1)
+├── knowledge/           # Shared knowledge base (NEW v1.1)
+├── standards/           # Community standards (NEW v1.1)
+└── ci-templates/        # CI/CD workflow templates (NEW v1.1)
+```
+
+---
+
+## Quick Start Guide
+
+### 1. Session Initialization
+```bash
+# Load workflow index (~15k tokens)
+Read: .ai-context/context/WORKFLOW_INDEX.md
+
+# Load specific workflows as needed (~20-50k each)
+Read: .ai-context/context/workflows/[relevant_workflow].md
+```
+
+### 2. Debugging an Issue
+```
+1. Scan WORKFLOW_INDEX.md → Find relevant workflow
+2. Load workflow file → Get file:line references
+3. Fix issue with complete context
+4. Update documentation (CODE_TO_WORKFLOW_MAP guides)
+5. Run /verify-docs-current
+```
+
+### 3. Implementing a Feature
+```
+1. Run /rpi-research → Explore codebase
+2. Run /rpi-plan → Create implementation blueprint
+3. Run /rpi-implement → Execute with doc updates
+```
+
+---
+
+## Self-Maintaining Documentation
+
+### Automatic Documentation Updates
+
+After every code change, update documentation:
+
+1. Check `CODE_TO_WORKFLOW_MAP.md` for affected workflows
+2. Update workflow files with new line numbers
+3. Verify function signatures match code
+4. Update diagrams if state machine changed
+5. Run `/verify-docs-current` for validation
+6. Commit documentation updates with code changes
+
+### Post-Implementation Checklist (Embedded in All Agents)
+
+```markdown
+## Post-Implementation Checklist
+
+**MANDATORY:** After making ANY code changes, update documentation.
+
+1. Check CODE_TO_WORKFLOW_MAP.md for affected workflows
+2. Update workflows with new line numbers
+3. Verify function signatures match
+4. Run /verify-docs-current
+5. Commit doc updates with code changes
+```
+
+---
+
+## Context Budget Limits
+
+**Hard Caps (Non-Negotiable):**
+- **Maximum Context:** 200,000 tokens
+- **Maximum Output:** 30,000 tokens per response
+- **Target Utilization:** <40% (80,000 tokens)
+- **Compaction Trigger:** 35% (70,000 tokens)
+
+**Budget Allocation:**
+```
+Workflow Indexes:      ~15k tokens (7.5%)
+Workflow Details:      ~40k tokens (20%)
+Active Code:           ~30k tokens (15%)
+Tool Results:          ~15k tokens (7.5%)
+─────────────────────────────────────────
+Typical Session:       ~100k tokens (50%)
+Buffer:                ~100k tokens (50%)
+```
+
+---
+
+## Initialization
+
+To transform this template for your codebase, use:
+
+```bash
+@context-engineer "Initialize context engineering for this repository"
+```
+
+This agent will:
+1. Analyze your codebase structure
+2. Identify major workflows (8-15)
+3. Create workflow documentation
+4. Set up index hierarchy
+5. Configure specialized agents
+6. Validate the system
+
+---
+
+*Configuration updated: {{DATE}}*
+*Version: 1.2.0 (Template)*