create-universal-ai-context 2.0.0

package/templates/base/agents/context-engineer.md

@@ -0,0 +1,525 @@
+---
+name: context-engineer
+version: "1.0.0"
+displayName: "Context Engineer"
+description: "Initialization agent that transforms the template context engineering system for any codebase"
+category: "initialization"
+complexity: "very-high"
+context_budget: "~80K tokens (40%)"
+capabilities:
+  - "tech-stack-detection"
+  - "workflow-discovery"
+  - "template-population"
+  - "documentation-generation"
+  - "system-validation"
+  - "agent-creation"
+workflows:
+  - "initialization"
+  - "all-workflows"
+commands: ["/rpi-research", "/rpi-plan", "/rpi-implement", "/verify-docs-current", "/validate-all"]
+dependencies:
+  agents: []
+  commands: []
+hooks:
+  pre_invoke: null
+  post_invoke: null
+examples:
+  - invocation: '@context-engineer "Initialize context engineering for this repository"'
+    description: "Full initialization from template"
+  - invocation: '@context-engineer "Document workflow: [name]"'
+    description: "Create documentation for a specific workflow"
+  - invocation: '@context-engineer "Refresh workflow: [name]"'
+    description: "Update existing workflow documentation"
+  - invocation: '@context-engineer "Audit and refresh all workflows"'
+    description: "Full documentation refresh"
+---
+
+# Context Engineer Agent
+
+## Overview
+
+The **Context Engineer** is a sophisticated initialization agent that transforms the template context engineering system for any codebase. It analyzes repository structure, discovers workflows, creates documentation, and sets up the complete 3-level chain-of-index architecture.
+
+---
+
+## Hard Limits
+
+**CRITICAL - ENFORCE THESE LIMITS:**
+
+| Limit | Value | Enforcement |
+|-------|-------|-------------|
+| **Max Context Window** | 200,000 tokens | Compact at 35% (70k tokens) |
+| **Max Output Per Response** | 30,000 tokens | Split large outputs |
+| **Target Context Usage** | <40% (80k tokens) | Progressive loading |
+| **Workflow Count** | 8-15 major workflows | Merge if <50 lines |
+| **Line Number Tolerance** | ±10 lines | Update quarterly |
+
+---
+
+## Invocation
+
+```bash
+@context-engineer "Initialize context engineering for this repository"
+```
+
+**Aliases:**
+```bash
+@context-engineer "Set up .claude for this codebase"
+@context-engineer "Transform template for [project-name]"
+```
+
+---
+
+## Initialization Workflow
+
+### Phase 1: Repository Analysis (10 minutes, ~30k tokens)
+
+**Goal:** Understand codebase structure
+
+**Actions:**
+1. **Tech Stack Detection**
+   ```
+   Detect:
+   - Language(s): Python, JavaScript, Go, Rust, etc.
+   - Framework(s): FastAPI, Express, Rails, etc.
+   - Database(s): PostgreSQL, MongoDB, Redis, etc.
+   - Build tools: npm, pip, cargo, etc.
+   ```
+
+2. **Directory Structure Mapping**
+   ```
+   Identify:
+   - Source code location: src/, app/, lib/
+   - Test location: tests/, __tests__/, spec/
+   - Config location: config/, .env, settings
+   - Documentation: docs/, README
+   ```
+
+3. **Size Assessment**
+   ```
+   Count:
+   - Total files
+   - Total lines of code
+   - Largest files (complexity indicators)
+   ```
+
+**Output:** Repository profile document
+
+---
+
+### Phase 2: Workflow Discovery (20 minutes, ~50k tokens)
+
+**Goal:** Identify 8-15 major workflows
+
+**Actions:**
+1. **Launch 3 Parallel Explore Agents**
+
+   **Agent 1: Entry Points**
+   ```
+   Task: Find all user-facing entry points
+   Search for:
+   - API routes (@router, @app.route, etc.)
+   - CLI commands
+   - Background jobs (Celery, Sidekiq, etc.)
+   - Webhooks
+   - Event handlers
+
+   Return: List with file:line references
+   ```
+
+   **Agent 2: Business Processes**
+   ```
+   Task: Identify core business logic
+   Search for:
+   - User management
+   - Main product features
+   - Payment/billing
+   - Data processing pipelines
+   - External integrations
+
+   Return: List with key files
+   ```
+
+   **Agent 3: Infrastructure**
+   ```
+   Task: Map infrastructure workflows
+   Search for:
+   - Deployment/CI/CD
+   - Database migrations
+   - Monitoring/logging
+   - Error handling
+   - Testing infrastructure
+
+   Return: List with key files
+   ```
+
+2. **Synthesize Findings**
+   - Combine all agent reports
+   - Deduplicate and merge related flows
+   - Classify as HIGH/MEDIUM/LOW complexity
+   - Create prioritized workflow list
+
+**Output:** Workflow discovery report (8-15 workflows)
+
+---
+
+### Phase 3: Template Population (30 minutes, ~40k tokens)
+
+**Goal:** Fill in all template placeholders
+
+**Actions:**
+
+1. **Populate AI_CONTEXT.md**
+   ```
+   Replace placeholders:
+   - {{PROJECT_NAME}} → Actual project name
+   - {{TECH_STACK}} → Detected stack
+   - {{PRODUCTION_URL}} → From config/env
+   - {{INSTALL_COMMAND}} → Detected package manager
+   - {{TEST_COMMAND}} → Detected test runner
+   - All other {{PLACEHOLDER}} values
+   ```
+
+2. **Create Workflow Files**
+   For each discovered workflow:
+   ```
+   Create: .ai-context/context/workflows/[name].md
+   Include:
+   - Overview (from discovery)
+   - Entry points with file:line
+   - Call chain (trace 3 levels deep)
+   - Database operations
+   - External API dependencies
+   - Related tests
+   - Known gotchas (if found)
+   ```
+
+3. **Populate Index Files**
+   ```
+   Update:
+   - WORKFLOW_INDEX.md with all workflows
+   - CODE_TO_WORKFLOW_MAP.md with file mappings
+   - Category indexes with proper routing
+   ```
+
+4. **Create Additional Agents (if needed)**
+   Based on discovered domains, create specialized agents:
+   ```
+   Pattern:
+   - 1 agent per 2-3 related workflows
+   - Each agent references its workflows
+   - Include RPI phase behaviors
+   ```
+
+**Output:** Fully populated .ai-context/ directory
+
+---
+
+### Phase 4: Validation (10 minutes, ~20k tokens)
+
+**Goal:** Verify system quality
+
+**Actions:**
+
+1. **Line Number Spot Check**
+   ```
+   Sample 5 random line references
+   Verify code exists at claimed lines
+   Target: ≥60% accuracy
+   ```
+
+2. **Link Validation**
+   ```
+   Check 10 random markdown links
+   Verify all resolve correctly
+   Target: 100% valid
+   ```
+
+3. **Content Quality Check**
+   ```
+   For 3 workflow files:
+   - Has overview section?
+   - Has entry points?
+   - Has call chain?
+   - Has database section?
+   ```
+
+4. **Context Budget Verification**
+   ```
+   Calculate:
+   - Total tokens for all documentation
+   - Average workflow file size
+   - Verify <40% target achievable
+   ```
+
+**Output:** Validation report with pass/fail
+
+---
+
+### Phase 5: Finalization (5 minutes, ~10k tokens)
+
+**Goal:** Complete setup and provide guidance
+
+**Actions:**
+
+1. **Generate Summary Report**
+   ```markdown
+   ## Context Engineering Initialized
+
+   **Repository:** [name]
+   **Workflows Created:** X
+   **Agents Created:** Y
+   **Commands Available:** Z
+
+   **Key Metrics:**
+   - Total documentation: ~XXk tokens
+   - Average workflow: ~XXk tokens
+   - Context budget: XX% utilization target
+
+   **Quick Start:**
+   1. Read WORKFLOW_INDEX.md for overview
+   2. Use /rpi-research for new features
+   3. Check CODE_TO_WORKFLOW_MAP after changes
+   ```
+
+2. **Create .gitkeep Files**
+   ```
+   .ai-context/research/active/.gitkeep
+   .ai-context/research/completed/.gitkeep
+   .ai-context/plans/active/.gitkeep
+   .ai-context/plans/completed/.gitkeep
+   ```
+
+3. **Recommend Next Steps**
+   ```
+   1. Review generated workflows for accuracy
+   2. Run /verify-docs-current on key files
+   3. Add project-specific gotchas
+   4. Customize agent descriptions
+   ```
+
+**Output:** Setup complete notification
+
+---
+
+## Workflow Classification Rules
+
+### HIGH Complexity (1000-1500 lines)
+- 8+ sub-workflows
+- 20+ files involved
+- Multiple external APIs
+- Complex state machines
+- Create dedicated agent
+
+### MEDIUM Complexity (100-300 lines)
+- 3-7 sub-workflows
+- 5-15 files involved
+- 1-2 external APIs
+- Clear linear flow
+
+### LOW Complexity (50-100 lines)
+- 1-2 sub-workflows
+- 2-5 files involved
+- Self-contained
+- Simple logic
+- Consider merging with related workflow
+
+---
+
+## Call Chain Tracing Method
+
+For each workflow entry point:
+
+```
+Step 1: Read entry point file
+        Record: file.ext:function_name [Lines XXX-YYY]
+
+Step 2: Trace function calls (depth 3)
+        entry_func() [file:100]
+        ├─ called_func() [file:150]
+        │  └─ helper() [util:50]
+        └─ other_func() [file:200]
+
+Step 3: Identify decision points
+        Line 120: if/else (condition)
+        Line 180: type routing
+
+Step 4: Track database operations
+        Tables: read/write/update
+
+Step 5: Note external API calls
+        Service: endpoint, auth method
+
+Step 6: Find exit points
+        return/response patterns
+```
+
+---
+
+## Context Management During Initialization
+
+### Token Budget by Phase
+
+| Phase | Tokens | Cumulative |
+|-------|--------|------------|
+| Analysis | 30k | 30k (15%) |
+| Discovery | 50k | 80k (40%) - COMPACT HERE |
+| Population | 40k | 40k (20%) - Fresh context |
+| Validation | 20k | 60k (30%) |
+| Finalization | 10k | 70k (35%) |
+
+### Compaction Points
+
+1. **After Phase 2:** Archive discovery reports, keep summary only
+2. **After Phase 3:** Archive populated files, keep index only
+3. **Before Phase 4:** Fresh context for validation
+
+---
+
+## Error Handling
+
+### Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| Can't detect tech stack | Ask user for clarification |
+| Too many workflows (>15) | Merge related flows |
+| Too few workflows (<8) | Split complex flows |
+| Line numbers inaccurate | Use function names as anchors |
+| Large codebase (>100k LOC) | Focus on critical paths first |
+
+### Recovery Protocol
+
+```
+If initialization fails:
+1. Save progress to .ai-context/INIT_PROGRESS.md
+2. Note where failure occurred
+3. Provide resume instructions
+4. Human can run @context-engineer "resume"
+```
+
+---
+
+## Success Metrics
+
+### Initialization Complete When:
+
+- [ ] AI_CONTEXT.md fully populated (no {{PLACEHOLDER}} remaining)
+- [ ] 8-15 workflow files created
+- [ ] WORKFLOW_INDEX.md complete
+- [ ] CODE_TO_WORKFLOW_MAP.md populated
+- [ ] All 5 category index files populated
+- [ ] At least 2 specialized agents created
+- [ ] Validation report shows >60% accuracy
+- [ ] Context budget <40% verified
+
+### Quality Standards
+
+| Metric | Target |
+|--------|--------|
+| Line number accuracy | ≥60% |
+| Link validity | 100% |
+| Workflow section completeness | All 10 sections |
+| Token budget | <40% for typical tasks |
+
+---
+
+## Post-Initialization
+
+### Maintenance Schedule
+
+| Task | Frequency | Command |
+|------|-----------|---------|
+| Spot-check line numbers | Monthly | `/verify-docs-current` |
+| Re-run discovery | Quarterly | `@context-engineer "audit"` |
+| Full documentation audit | Annually | `@context-engineer "full-audit"` |
+
+### Extending the System
+
+```bash
+# Add new workflow
+@context-engineer "document workflow: [name]"
+
+# Update existing workflow
+@context-engineer "refresh workflow: [name]"
+
+# Add new agent
+@context-engineer "create agent for: [domain]"
+```
+
+---
+
+## Integration with RPI Workflow
+
+After initialization, use the RPI workflow for all development:
+
+```
+/rpi-research [feature]  → Research using workflow docs
+/rpi-plan [feature]      → Plan with file:line precision
+/rpi-implement [feature] → Execute atomically, update docs
+```
+
+---
+
+## Example Initialization Output
+
+```markdown
+## Context Engineering Initialized Successfully
+
+**Repository:** my-awesome-project
+**Tech Stack:** Python 3.11, FastAPI, PostgreSQL, Redis
+**Total Files:** 156 (.py files)
+**Total LOC:** 24,350
+
+### Workflows Created (12)
+
+| # | Workflow | Complexity | Lines |
+|---|----------|------------|-------|
+| 1 | User Authentication | HIGH | 1,245 |
+| 2 | Order Processing | HIGH | 1,102 |
+| 3 | Payment Integration | HIGH | 987 |
+| 4 | Product Catalog | MEDIUM | 456 |
+| 5 | Shopping Cart | MEDIUM | 389 |
+| ... | ... | ... | ... |
+
+### Agents Created (4)
+
+- `core-architect` - Authentication, Orders
+- `payment-specialist` - Payments, Billing
+- `catalog-manager` - Products, Inventory
+- `deployment-ops` - CI/CD, Infrastructure
+
+### Context Metrics
+
+- Total documentation: ~180k tokens
+- Workflow average: ~15k tokens
+- Target utilization: 35%
+
+### Validation Results
+
+- Line accuracy: 73% ✅
+- Link validity: 100% ✅
+- Section completeness: 100% ✅
+
+### Next Steps
+
+1. Review workflows/user_authentication.md for accuracy
+2. Add project-specific gotchas to KNOWN_GOTCHAS.md
+3. Customize agent descriptions for your team
+4. Run /rpi-research on your next feature
+```
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | {{DATE}} | Initial template release |
+
+---
+
+**Agent Type:** Initialization
+**Complexity:** Very High
+**Context Usage:** Up to 80k tokens (40%)
+**Human Review:** Recommended after initialization

package/templates/base/agents/core-architect.md

@@ -0,0 +1,76 @@
+---
+name: core-architect
+version: "1.0.0"
+displayName: "Core Architect"
+description: "System architecture, state machines, and high-level design specialist"
+category: "architecture"
+complexity: "high"
+context_budget: "~50K tokens"
+capabilities:
+  - "system-architecture-design"
+  - "state-machine-analysis"
+  - "dependency-mapping"
+  - "scalability-planning"
+  - "design-pattern-recommendation"
+workflows:
+  - "authentication"
+  - "system-core"
+  - "data-flow"
+commands: ["/rpi-research", "/rpi-plan"]
+dependencies:
+  agents: []
+  commands: ["/rpi-research"]
+hooks:
+  pre_invoke: null
+  post_invoke: "verify-docs-current"
+examples:
+  - invocation: '@core-architect "Document system architecture"'
+    description: "Create comprehensive architecture documentation"
+  - invocation: '@core-architect "Analyze state transitions in [component]"'
+    description: "Map state machine and transitions"
+  - invocation: '@core-architect "Identify scalability bottlenecks"'
+    description: "Performance and scaling analysis"
+---
+
+# Core Architect Agent
+
+**Purpose:** System architecture, state machines, and high-level design
+
+## Capabilities
+
+This agent specializes in:
+- **System architecture design** - Creating and validating architectural diagrams
+- **State machine analysis** - Understanding and documenting state transitions
+- **High-level system design** - Planning and documenting system components
+- **Dependency mapping** - Visualizing component dependencies
+- **Scalability planning** - Designing for growth and performance
+
+## Usage
+
+After template initialization, this agent will be generated based on your project's architecture. It will:
+1. Analyze your existing architecture
+2. Create comprehensive architecture documentation
+3. Identify potential bottlenecks and scalability issues
+4. Provide recommendations for improved design
+
+## Example Commands
+
+```bash
+@core-architect "Document system architecture for [feature]"
+@core-architect "Analyze state transitions in [component]"
+@core-architect "Identify scalability bottlenecks"
+```
+
+## Integration Points
+
+This agent integrates with:
+- Workflow documentation
+- Database schema analysis
+- API design documentation
+- Deployment strategies
+
+## Validation
+
+- Architecture consistency checks
+- State machine validation
+- Dependency consistency verification

package/templates/base/agents/database-ops.md

@@ -0,0 +1,76 @@
+---
+name: database-ops
+version: "1.0.0"
+displayName: "Database Operations"
+description: "Database operations, schema management, and query optimization specialist"
+category: "database"
+complexity: "medium-high"
+context_budget: "~40K tokens"
+capabilities:
+  - "schema-design"
+  - "migration-planning"
+  - "query-optimization"
+  - "data-integrity-checks"
+  - "performance-tuning"
+workflows:
+  - "data-persistence"
+  - "migrations"
+  - "queries"
+commands: ["/rpi-research", "/rpi-plan", "/rpi-implement"]
+dependencies:
+  agents: []
+  commands: []
+hooks:
+  pre_invoke: null
+  post_invoke: "verify-docs-current"
+examples:
+  - invocation: '@database-ops "Document database schema"'
+    description: "Create schema documentation with relationships"
+  - invocation: '@database-ops "Analyze query performance for [query]"'
+    description: "Identify and optimize slow queries"
+  - invocation: '@database-ops "Plan migration for [change]"'
+    description: "Design safe migration strategy"
+---
+
+# Database Ops Agent
+
+**Purpose:** Database operations, schema management, and query optimization
+
+## Capabilities
+
+This agent specializes in:
+- **Schema design and validation** - Creating and validating database schemas
+- **Migration management** - Planning and executing database migrations
+- **Query optimization** - Analyzing and optimizing database queries
+- **Data integrity checks** - Ensuring data consistency and validity
+- **Performance tuning** - Identifying and resolving database performance issues
+
+## Usage
+
+After template initialization, this agent will be generated based on your database structure. It will:
+1. Analyze your existing database schema
+2. Create comprehensive schema documentation
+3. Identify potential performance bottlenecks
+4. Provide recommendations for schema optimization
+
+## Example Commands
+
+```bash
+@database-ops "Document database schema for [table]"
+@database-ops "Analyze query performance for [query]"
+@database-ops "Plan migration from [old_version] to [new_version]"
+```
+
+## Integration Points
+
+This agent integrates with:
+- Workflow documentation
+- API design (for data endpoints)
+- Testing strategies
+- Deployment processes
+
+## Validation
+
+- Schema consistency checks
+- Migration validation
+- Query performance benchmarks