create-universal-ai-context 2.0.0

package/templates/base/indexes/agents/CAPABILITY_MATRIX.md

@@ -0,0 +1,255 @@
+# Agent Capability Matrix
+
+Quick reference for selecting the right agent for your task.
+
+---
+
+## Decision Matrix
+
+| Task Type | Primary Agent | Support Agent | Notes |
+|-----------|---------------|---------------|-------|
+| **Initialization/Setup** | `@context-engineer` | - | Only for first-time setup |
+| **System Architecture** | `@core-architect` | `@database-ops` | High-level design |
+| **State Machines** | `@core-architect` | - | Flow analysis |
+| **Database Schema** | `@database-ops` | `@core-architect` | Schema design |
+| **Migrations** | `@database-ops` | - | Schema changes |
+| **Query Optimization** | `@database-ops` | - | Performance |
+| **API Design** | `@api-developer` | `@core-architect` | REST/GraphQL |
+| **API Contracts** | `@api-developer` | - | Request/response |
+| **API Documentation** | `@api-developer` | - | OpenAPI/Swagger |
+| **External Integrations** | `@integration-hub` | `@api-developer` | Third-party APIs |
+| **Webhooks** | `@integration-hub` | - | Incoming/outgoing |
+| **Authentication (External)** | `@integration-hub` | - | OAuth, API keys |
+| **CI/CD Pipelines** | `@deployment-ops` | - | Build/deploy |
+| **Infrastructure** | `@deployment-ops` | - | IaC, cloud |
+| **Deployment Strategy** | `@deployment-ops` | `@core-architect` | Blue-green, canary |
+| **Performance Tuning** | `@core-architect` | `@database-ops` | System-wide |
+| **Security Review** | `@core-architect` | All | Cross-cutting |
+
+---
+
+## Agent Selection Flowchart
+
+```
+START: What are you trying to do?
+│
+├─► Setting up for the first time?
+│   └─► @context-engineer
+│
+├─► Working with external services?
+│   ├─► Third-party APIs → @integration-hub
+│   ├─► Webhooks → @integration-hub
+│   └─► External auth → @integration-hub
+│
+├─► Working with the database?
+│   ├─► Schema design → @database-ops
+│   ├─► Migrations → @database-ops
+│   └─► Query performance → @database-ops
+│
+├─► Working with APIs?
+│   ├─► Endpoint design → @api-developer
+│   ├─► Contracts/schemas → @api-developer
+│   └─► API documentation → @api-developer
+│
+├─► Working with deployment?
+│   ├─► CI/CD pipelines → @deployment-ops
+│   ├─► Infrastructure → @deployment-ops
+│   └─► Rollback planning → @deployment-ops
+│
+└─► System design or architecture?
+    └─► @core-architect
+```
+
+---
+
+## Agent Profiles
+
+### @context-engineer
+
+| Attribute | Value |
+|-----------|-------|
+| **Category** | Initialization |
+| **Complexity** | Very High |
+| **Context Budget** | ~80K tokens (40%) |
+| **Primary Use** | First-time setup, documentation refresh |
+
+**Best For:**
+- Initial repository setup
+- Complete documentation generation
+- Workflow discovery
+- Template population
+
+**Not For:**
+- Day-to-day development
+- Specific domain tasks
+- Quick fixes
+
+---
+
+### @core-architect
+
+| Attribute | Value |
+|-----------|-------|
+| **Category** | Architecture |
+| **Complexity** | High |
+| **Context Budget** | ~50K tokens (25%) |
+| **Primary Use** | System design, state machines |
+
+**Best For:**
+- High-level system design
+- State machine analysis
+- Dependency mapping
+- Scalability planning
+- Cross-cutting concerns
+
+**Not For:**
+- Database-specific work
+- API implementation details
+- External service integration
+
+---
+
+### @database-ops
+
+| Attribute | Value |
+|-----------|-------|
+| **Category** | Database |
+| **Complexity** | Medium-High |
+| **Context Budget** | ~40K tokens (20%) |
+| **Primary Use** | Schema, migrations, queries |
+
+**Best For:**
+- Schema design and validation
+- Migration planning
+- Query optimization
+- Data integrity
+- Database performance
+
+**Not For:**
+- API design
+- External integrations
+- Deployment
+
+---
+
+### @api-developer
+
+| Attribute | Value |
+|-----------|-------|
+| **Category** | API |
+| **Complexity** | Medium |
+| **Context Budget** | ~35K tokens (17%) |
+| **Primary Use** | Endpoints, contracts |
+
+**Best For:**
+- REST API design
+- GraphQL schema
+- Contract definition
+- API documentation
+- Endpoint testing strategy
+
+**Not For:**
+- Database operations
+- External service integration
+- Infrastructure
+
+---
+
+### @integration-hub
+
+| Attribute | Value |
+|-----------|-------|
+| **Category** | Integration |
+| **Complexity** | Medium-High |
+| **Context Budget** | ~40K tokens (20%) |
+| **Primary Use** | External services, webhooks |
+
+**Best For:**
+- Third-party API integration
+- Webhook handling
+- External authentication
+- Rate limiting
+- Integration error handling
+
+**Not For:**
+- Internal API design
+- Database work
+- Deployment
+
+---
+
+### @deployment-ops
+
+| Attribute | Value |
+|-----------|-------|
+| **Category** | DevOps |
+| **Complexity** | High |
+| **Context Budget** | ~45K tokens (22%) |
+| **Primary Use** | CI/CD, infrastructure |
+
+**Best For:**
+- CI/CD pipeline design
+- Infrastructure as code
+- Deployment strategies
+- Environment management
+- Rollback planning
+
+**Not For:**
+- Application code
+- Database schema
+- API design
+
+---
+
+## Capability Overlap
+
+Some tasks benefit from multiple agents working together:
+
+### Architecture + Database
+When designing a new feature that involves both system architecture and data persistence:
+1. Start with `@core-architect` for high-level design
+2. Consult `@database-ops` for schema implications
+3. Return to `@core-architect` for integration
+
+### API + Integration
+When building an API that wraps external services:
+1. Start with `@api-developer` for your API design
+2. Consult `@integration-hub` for external service patterns
+3. Return to `@api-developer` for implementation
+
+### All Agents for Security Review
+Security reviews often require input from multiple perspectives:
+- `@core-architect` - System-level security
+- `@database-ops` - Data security
+- `@api-developer` - API security
+- `@integration-hub` - Integration security
+- `@deployment-ops` - Infrastructure security
+
+---
+
+## Quick Reference Card
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    AGENT QUICK SELECT                       │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  🚀 Setup/Init      → @context-engineer                     │
+│  🏗️  Architecture    → @core-architect                       │
+│  🗄️  Database        → @database-ops                         │
+│  🔌 API             → @api-developer                        │
+│  🔗 External        → @integration-hub                      │
+│  📦 Deploy          → @deployment-ops                       │
+│                                                             │
+├─────────────────────────────────────────────────────────────┤
+│  When unsure, start with @core-architect for guidance       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## See Also
+
+- [Agent Details](./../agents/) - Full agent documentation
+- [Commands Reference](./../../commands/help.md) - Available commands
+- [RPI Workflow](./../../RPI_WORKFLOW_PLAN.md) - Research-Plan-Implement methodology

package/templates/base/indexes/agents/CATEGORY_INDEX.md

@@ -0,0 +1,44 @@
+# Agents Category Index
+
+## Purpose
+Entry point for agent selection matrix
+
+## Agents Available
+
+| Agent | Primary Workflows | Use For |
+|-------|------------------|---------|
+| **`context-engineer`** | INITIALIZATION | Transform this template for any codebase |
+| **core-architect** | System architecture, state machines | High-level design and architecture |
+| **database-ops** | Migrations, schema, queries | Database operations and optimization |
+| **api-developer** | Endpoints, contracts | API design and implementation |
+| **integration-hub** | External services | Third-party service integration |
+| **deployment-ops** | CI/CD, infrastructure | Deployment and infrastructure management |
+
+## Detailed Selection Guide
+
+For detailed agent selection guidance including capabilities, workflows, and decision criteria, see:
+**[CAPABILITY_MATRIX.md](./CAPABILITY_MATRIX.md)**
+
+## Quick Start
+
+1. Load this category index first (~5k tokens)
+2. Check CAPABILITY_MATRIX.md for detailed selection guidance
+3. Load agent definition for detailed capabilities
+4. Use agent for specific tasks
+
+## Context Budget
+- Category Index: ~5k tokens (2.5% of context window)
+- Agent Definition: ~10k tokens (5% of context window)
+- Agent Session: ~50k tokens (25% of context window)
+
+## Getting Started
+
+```bash
+# Load category index first
+Read: .ai-context/indexes/agents/CATEGORY_INDEX.md
+
+# Then load relevant agent definition
+Read: .ai-context/agents/[agent].md
+
+# Finally use agent for specific tasks
+@agent-name "Task description"

package/templates/base/indexes/code/CATEGORY_INDEX.md

@@ -0,0 +1,38 @@
+# Code Category Index
+
+## Purpose
+Entry point for code organization and domain × layer overview
+
+## Domains & Layers Available
+
+| Domain | Layers | Description | When to Use |
+|--------|--------|-------------|-------------|
+| **core** | utils, services, models | Core application logic | When working with fundamental app components |
+| **api** | controllers, routes, middleware | API layer | When implementing or debugging APIs |
+| **infrastructure** | config, db, caching | Infrastructure components | When working with databases, caches, or configs |
+| **ui** | components, pages, styles | User interface | When building or modifying front-end features |
+| **testing** | unit, integration, e2e | Test suites | When writing or debugging tests |
+
+## Quick Start
+
+1. Load this category index first (~5k tokens)
+2. Identify relevant domain and layer
+3. Load domain index for detailed navigation
+4. Access code files for implementation
+
+## Context Budget
+- Category Index: ~5k tokens (2.5% of context window)
+- Domain Index: ~15k tokens (7.5% of context window)
+- Code Files: ~20k tokens (10% of context window)
+
+## Getting Started
+
+```bash
+# Load category index first
+Read: .ai-context/indexes/code/CATEGORY_INDEX.md
+
+# Then load relevant domain index
+Read: .ai-context/indexes/code/[domain].md
+
+# Finally load specific code files
+Read: [code_file_path]

package/templates/base/indexes/routing/CATEGORY_INDEX.md

@@ -0,0 +1,39 @@
+# Routing Category Index
+
+## Purpose
+Entry point for task routing and classification
+
+## Task Types Available
+
+| Task Type | Description | When to Use |
+|-----------|-------------|-------------|
+| **Feature** | New feature implementation | When building new functionality |
+| **Bug Fix** | Issue resolution | When fixing bugs or issues |
+| **Refactor** | Code improvement | When refactoring existing code |
+| **Documentation** | Doc updates | When updating documentation |
+| **Technical Debt** | Legacy improvements | When addressing technical debt |
+| **Performance** | Optimization | When improving performance |
+
+## Quick Start
+
+1. Load this category index first (~5k tokens)
+2. Identify relevant task type
+3. Load routing matrix for detailed classification
+4. Follow routing instructions for implementation
+
+## Context Budget
+- Category Index: ~5k tokens (2.5% of context window)
+- Routing Matrix: ~10k tokens (5% of context window)
+- Implementation Guidance: ~30k tokens (15% of context window)
+
+## Getting Started
+
+```bash
+# Load category index first
+Read: .ai-context/indexes/routing/CATEGORY_INDEX.md
+
+# Then load relevant routing matrix
+Read: .ai-context/indexes/routing/[task_type].md
+
+# Finally follow routing instructions
+Follow guidance in routing matrix

package/templates/base/indexes/search/CATEGORY_INDEX.md

@@ -0,0 +1,39 @@
+# Search Category Index
+
+## Purpose
+Entry point for search strategies and pattern recognition
+
+## Search Patterns Available
+
+| Pattern Type | Description | When to Use |
+|--------------|-------------|-------------|
+| **Configuration Values** | Environment variables, hardcoded settings | When searching for config values |
+| **Business Logic** | Core application logic files | When locating business rules |
+| **Database Schema** | Models, migrations, queries | When investigating data structures |
+| **External Integrations** | API calls, webhooks, Connectors | When examining third-party integrations |
+| **Error Handling** | Exception handling patterns | When debugging error scenarios |
+| **Performance Bottlenecks** | Heavy computations, slow queries | When optimizing performance |
+
+## Quick Start
+
+1. Load this category index first (~5k tokens)
+2. Identify relevant search pattern
+3. Load pattern details for specific implementation
+4. Use search strategies for investigation
+
+## Context Budget
+- Category Index: ~5k tokens (2.5% of context window)
+- Pattern Details: ~10k tokens (5% of context window)
+- Search Execution: ~30k tokens (15% of context window)
+
+## Getting Started
+
+```bash
+# Load category index first
+Read: .ai-context/indexes/search/CATEGORY_INDEX.md
+
+# Then load relevant pattern details
+Read: .ai-context/indexes/search/[pattern_type].md
+
+# Finally execute search strategy
+Follow pattern instructions for investigation

package/templates/base/indexes/workflows/CATEGORY_INDEX.md

@@ -0,0 +1,38 @@
+# Workflows Category Index
+
+## Purpose
+Entry point for workflow-related navigation and task classification
+
+## Categories Available
+
+| Category | Description | When to Use |
+|----------|-------------|-------------|
+| **jobs** | Job-related workflows (hiring, onboarding, payroll) | When working with HR or recruitment processes |
+| **payment** | Payment processing workflows | When implementing payment features |
+| **email** | Email-related workflows | When building email functionality |
+| **reporting** | Reporting and analytics workflows | When creating dashboards or reports |
+| **authentication** | Auth-related workflows | When implementing login/registration features |
+
+## Quick Start
+
+1. Load this category index first (~5k tokens)
+2. Identify relevant category
+3. Load domain index for detailed navigation
+4. Access workflow detail files for implementation
+
+## Context Budget
+- Category Index: ~5k tokens (2.5% of context window)
+- Domain Index: ~15k tokens (7.5% of context window)
+- Workflow Detail: ~40k tokens (20% of context window)
+
+## Getting Started
+
+```bash
+# Load category index first
+Read: .ai-context/indexes/workflows/CATEGORY_INDEX.md
+
+# Then load relevant domain index
+Read: .ai-context/indexes/workflows/[category].md
+
+# Finally load workflow detail file
+Read: .ai-context/context/workflows/[workflow].md

package/templates/base/knowledge/README.md

@@ -0,0 +1,98 @@
+# Shared Knowledge Base
+
+Central repository for team knowledge, decisions, patterns, and session handoffs.
+
+## Directory Structure
+
+```
+knowledge/
+├── shared/           # Team-shared knowledge
+│   ├── decisions/    # Architecture Decision Records (ADRs)
+│   └── patterns/     # Reusable code patterns
+├── sessions/         # Session handoff documents
+└── README.md         # This file
+```
+
+## Shared Knowledge
+
+### Architecture Decision Records (ADRs)
+
+Located in `shared/decisions/`, ADRs document significant architectural decisions.
+
+**Creating an ADR:**
+1. Copy `shared/decisions/TEMPLATE.md`
+2. Name it `NNNN-descriptive-title.md` (e.g., `0001-use-postgresql.md`)
+3. Fill in all sections
+4. Submit for team review
+
+**ADR Statuses:**
+- `proposed` - Under discussion
+- `accepted` - Approved and in effect
+- `deprecated` - Superseded by another ADR
+- `rejected` - Not approved
+
+### Reusable Patterns
+
+Located in `shared/patterns/`, patterns document proven solutions to common problems.
+
+**Pattern Categories:**
+- `api/` - API design patterns
+- `data/` - Data handling patterns
+- `ui/` - User interface patterns
+- `testing/` - Testing patterns
+- `security/` - Security patterns
+
+## Session Handoffs
+
+Located in `sessions/`, handoff documents enable continuity between Claude Code sessions.
+
+**Handoff Document Contents:**
+- Session summary
+- Work completed
+- Work in progress
+- Blockers and issues
+- Next steps
+- Relevant context
+
+**Creating a Handoff:**
+```
+/collab handoff
+```
+
+**Naming Convention:**
+`YYYY-MM-DD-HH-MM-member-id.md`
+
+## Usage
+
+### Adding Knowledge
+
+1. Create document in appropriate directory
+2. Follow the template structure
+3. Run `/collab sync` to notify team
+
+### Finding Knowledge
+
+1. Check category directories for relevant content
+2. Use grep/search for specific terms
+3. Review recent session handoffs for context
+
+### Updating Knowledge
+
+1. Edit the document
+2. Update the `last_updated` metadata
+3. Add to revision history if significant
+
+## Retention Policy
+
+| Content Type | Retention |
+|--------------|-----------|
+| ADRs | Permanent (archive deprecated) |
+| Patterns | Permanent (version updates) |
+| Session Handoffs | 90 days (archive important ones) |
+
+## Best Practices
+
+1. **Keep it Current** - Update knowledge when code changes
+2. **Be Specific** - Include concrete examples
+3. **Link to Code** - Reference file:line where applicable
+4. **Review Regularly** - Prune outdated content monthly

package/templates/base/knowledge/sessions/README.md

@@ -0,0 +1,88 @@
+# Session Handoffs
+
+This directory contains session handoff documents that enable continuity between Claude Code sessions.
+
+## Purpose
+
+Session handoffs capture:
+- Work completed during a session
+- Work in progress with current state
+- Blockers and issues encountered
+- Context needed for continuation
+- Recommended next steps
+
+## Creating a Handoff
+
+Use the `/collab handoff` command at the end of a session:
+
+```
+/collab handoff
+```
+
+This generates a handoff document from the current session state.
+
+## Manual Handoff
+
+If the command isn't available, copy `TEMPLATE.md` and fill in:
+
+1. Session metadata
+2. Completed work summary
+3. In-progress work state
+4. Any blockers or issues
+5. Context for next session
+6. Recommended next steps
+
+## Naming Convention
+
+Handoff files are named:
+```
+YYYY-MM-DD-HH-MM-member-id.md
+```
+
+Example: `2024-01-15-14-30-dev-1.md`
+
+## Finding Relevant Handoffs
+
+### Most Recent
+
+Sort by filename (most recent first):
+```bash
+ls -r sessions/*.md
+```
+
+### By Team Member
+
+```bash
+ls sessions/*-member-id.md
+```
+
+### By Date Range
+
+```bash
+ls sessions/2024-01-*.md
+```
+
+## Retention
+
+| Age | Action |
+|-----|--------|
+| < 7 days | Keep (active reference) |
+| 7-30 days | Review for archival |
+| 30-90 days | Archive important, delete routine |
+| > 90 days | Delete unless historically significant |
+
+## Archiving
+
+Important handoffs (major feature completions, incident resolutions) should be:
+
+1. Moved to `sessions/archive/`
+2. Renamed with descriptive suffix: `YYYY-MM-DD-feature-name.md`
+3. Referenced in relevant ADRs if applicable
+
+## Best Practices
+
+1. **Create handoffs proactively** - Don't wait until context is lost
+2. **Be specific** - Include file paths, line numbers, commit hashes
+3. **Note blockers clearly** - Help the next person avoid wasted effort
+4. **Include context** - Share discoveries that aren't in the code
+5. **Suggest next steps** - Prioritize what should happen next