create-universal-ai-context 2.0.0

package/templates/base/context/KNOWN_GOTCHAS.md

@@ -0,0 +1,195 @@
+# Known Gotchas - {{PROJECT_NAME}}
+
+**Purpose:** Document lessons learned, common pitfalls, and their solutions
+**Use:** Before implementing features or debugging issues
+**Size:** ~15k tokens (grows over time)
+**Last Updated:** {{DATE}}
+
+---
+
+## How to Use This File
+
+1. **Before implementing:** Search for related gotchas
+2. **After fixing bugs:** Add new gotchas
+3. **During code review:** Reference relevant gotchas
+4. **Quarterly:** Review and archive resolved gotchas
+
+---
+
+## Gotcha Categories
+
+1. [Database](#database-gotchas)
+2. [API](#api-gotchas)
+3. [Authentication](#authentication-gotchas)
+4. [External Services](#external-services-gotchas)
+5. [Testing](#testing-gotchas)
+6. [Deployment](#deployment-gotchas)
+
+---
+
+## Database Gotchas
+
+### GOTCHA-DB-001: {{GOTCHA_TITLE}}
+
+**Severity:** CRITICAL / HIGH / MEDIUM / LOW
+**Discovered:** {{DATE}}
+**Workflow Impact:** [workflow_1.md](./workflows/workflow_1.md)
+
+**Symptom:**
+{{WHAT_GOES_WRONG}}
+
+**Root Cause:**
+{{WHY_IT_HAPPENS}}
+
+**Fix:**
+```
+{{CODE_OR_STEPS_TO_FIX}}
+```
+
+**Prevention:**
+- {{HOW_TO_AVOID_IN_FUTURE}}
+
+---
+
+### GOTCHA-DB-002: {{GOTCHA_TITLE}}
+
+[Same structure...]
+
+---
+
+## API Gotchas
+
+### GOTCHA-API-001: {{GOTCHA_TITLE}}
+
+**Severity:** CRITICAL / HIGH / MEDIUM / LOW
+**Discovered:** {{DATE}}
+**Workflow Impact:** [workflow_2.md](./workflows/workflow_2.md)
+
+**Symptom:**
+{{WHAT_GOES_WRONG}}
+
+**Root Cause:**
+{{WHY_IT_HAPPENS}}
+
+**Fix:**
+```
+{{CODE_OR_STEPS_TO_FIX}}
+```
+
+**Prevention:**
+- {{HOW_TO_AVOID_IN_FUTURE}}
+
+---
+
+## Authentication Gotchas
+
+### GOTCHA-AUTH-001: {{GOTCHA_TITLE}}
+
+[Same structure...]
+
+---
+
+## External Services Gotchas
+
+### GOTCHA-EXT-001: {{GOTCHA_TITLE}}
+
+[Same structure...]
+
+---
+
+## Testing Gotchas
+
+### GOTCHA-TEST-001: {{GOTCHA_TITLE}}
+
+[Same structure...]
+
+---
+
+## Deployment Gotchas
+
+### GOTCHA-DEPLOY-001: {{GOTCHA_TITLE}}
+
+[Same structure...]
+
+---
+
+## Quick Reference Table
+
+| ID | Title | Severity | Workflow |
+|----|-------|----------|----------|
+| DB-001 | {{TITLE}} | {{SEVERITY}} | workflow_1 |
+| API-001 | {{TITLE}} | {{SEVERITY}} | workflow_2 |
+| AUTH-001 | {{TITLE}} | {{SEVERITY}} | workflow_3 |
+
+---
+
+## Adding New Gotchas
+
+### Template
+
+```markdown
+### GOTCHA-[CATEGORY]-[NUMBER]: [Title]
+
+**Severity:** CRITICAL / HIGH / MEDIUM / LOW
+**Discovered:** YYYY-MM-DD
+**Workflow Impact:** [workflow_name.md](./workflows/workflow_name.md)
+
+**Symptom:**
+[What the user/developer observes going wrong]
+
+**Root Cause:**
+[Technical explanation of why it happens]
+
+**Fix:**
+```
+[Code or steps to fix]
+```
+
+**Prevention:**
+- [How to avoid this in future code]
+- [What patterns to use instead]
+```
+
+### Categories
+
+- **DB**: Database, migrations, queries
+- **API**: REST endpoints, request/response
+- **AUTH**: Authentication, authorization, sessions
+- **EXT**: External services, APIs, integrations
+- **TEST**: Testing, mocking, fixtures
+- **DEPLOY**: Deployment, CI/CD, infrastructure
+
+### Severity Levels
+
+| Level | Definition |
+|-------|------------|
+| CRITICAL | Production down, data loss possible |
+| HIGH | Feature broken, workaround difficult |
+| MEDIUM | Feature degraded, workaround exists |
+| LOW | Minor inconvenience, edge case |
+
+---
+
+## Archived Gotchas
+
+Gotchas that are fully resolved and no longer relevant:
+
+| ID | Title | Resolved Date | Resolution |
+|----|-------|---------------|------------|
+| - | - | - | - |
+
+---
+
+## Statistics
+
+- **Total Active Gotchas:** {{TOTAL_COUNT}}
+- **Critical:** {{CRITICAL_COUNT}}
+- **High:** {{HIGH_COUNT}}
+- **Medium:** {{MEDIUM_COUNT}}
+- **Low:** {{LOW_COUNT}}
+- **Last Added:** {{LAST_ADDED_DATE}}
+
+---
+
+**Version:** 1.0
+**Maintainer:** {{MAINTAINER}}

package/templates/base/context/TESTING_MAP.md

@@ -0,0 +1,95 @@
+# Testing Map
+
+> Maps source files to their corresponding tests.
+> **Last Updated:** {{LAST_UPDATED}}
+
+---
+
+## Overview
+
+This document provides a mapping between source files and their test coverage, helping developers find and update tests when modifying code.
+
+---
+
+## Test Structure
+
+```
+tests/
+├── unit/           # Unit tests
+├── integration/    # Integration tests
+├── e2e/            # End-to-end tests
+└── fixtures/       # Test data and mocks
+```
+
+---
+
+## Coverage Summary
+
+| Category | Files | Covered | Coverage |
+|----------|-------|---------|----------|
+| Unit | {{UNIT_COUNT}} | {{UNIT_COVERED}} | {{UNIT_PCT}}% |
+| Integration | {{INT_COUNT}} | {{INT_COVERED}} | {{INT_PCT}}% |
+| E2E | {{E2E_COUNT}} | {{E2E_COVERED}} | {{E2E_PCT}}% |
+
+---
+
+## File-to-Test Mapping
+
+### Core Application
+
+| Source File | Test File | Coverage |
+|-------------|-----------|----------|
+| `src/{{file}}.{{ext}}` | `tests/unit/{{file}}.test.{{ext}}` | {{PCT}}% |
+
+### Services
+
+| Source File | Test File | Coverage |
+|-------------|-----------|----------|
+| `src/services/{{service}}.{{ext}}` | `tests/unit/services/{{service}}.test.{{ext}}` | {{PCT}}% |
+
+### Utilities
+
+| Source File | Test File | Coverage |
+|-------------|-----------|----------|
+| `src/utils/{{util}}.{{ext}}` | `tests/unit/utils/{{util}}.test.{{ext}}` | {{PCT}}% |
+
+---
+
+## Critical Paths
+
+These files require comprehensive test coverage:
+
+| Path | Reason | Minimum Coverage |
+|------|--------|------------------|
+| `src/auth/` | Security-critical | 90% |
+| `src/payment/` | Financial transactions | 95% |
+| `src/api/` | Public interface | 85% |
+
+---
+
+## Test Commands
+
+```bash
+# Run all tests
+{{TEST_COMMAND}}
+
+# Run with coverage
+{{COVERAGE_COMMAND}}
+
+# Run specific test
+{{SPECIFIC_TEST_COMMAND}}
+```
+
+---
+
+## Maintenance
+
+Update this file when:
+- New source files are added
+- New test files are created
+- Coverage thresholds change
+- Test structure changes
+
+---
+
+*Template file - populate with actual test coverage data*

package/templates/base/context/WORKFLOW_INDEX.md

@@ -0,0 +1,129 @@
+# Workflow Index - {{PROJECT_NAME}}
+
+**Purpose:** Master catalog of all documented workflows
+**Load First:** Always load this file before debugging/implementing
+**Size:** ~15k tokens (7.5% of 200k context budget)
+**Last Updated:** {{DATE}}
+
+---
+
+## Quick Navigation
+
+| # | Workflow | Complexity | Entry Point | Use When |
+|---|----------|------------|-------------|----------|
+| 1 | {{WORKFLOW_1}} | HIGH/MED/LOW | [file:line] | [Scenario] |
+| 2 | {{WORKFLOW_2}} | HIGH/MED/LOW | [file:line] | [Scenario] |
+| 3 | {{WORKFLOW_3}} | HIGH/MED/LOW | [file:line] | [Scenario] |
+
+---
+
+## Workflow Categories
+
+### Category 1: {{CATEGORY_1_NAME}}
+
+**Workflows:** X
+**Total Lines:** ~XXX lines
+**Primary Agent:** {{AGENT_NAME}}
+
+| Workflow | Lines | Purpose |
+|----------|-------|---------|
+| [workflow_1.md](./workflows/workflow_1.md) | XXX | [Description] |
+
+**Use This Category For:**
+- [Scenario 1]
+- [Scenario 2]
+
+---
+
+### Category 2: {{CATEGORY_2_NAME}}
+
+[Same structure...]
+
+---
+
+## Cross-Reference Tables
+
+### External APIs × Workflows
+
+| API | Used By Workflows |
+|-----|-------------------|
+| {{API_1}} | workflow_1, workflow_2 |
+| {{API_2}} | workflow_3 |
+
+### Database Tables × Workflows
+
+| Table | Used By Workflows |
+|-------|-------------------|
+| {{TABLE_1}} | workflow_1, workflow_4 |
+| {{TABLE_2}} | workflow_2, workflow_3 |
+
+### Test Files × Workflows
+
+| Test File | Covers Workflows |
+|-----------|------------------|
+| `test_workflow_1.ext` | workflow_1 |
+| `test_e2e.ext` | workflow_1, workflow_2 |
+
+---
+
+## Issue Triage Quick Reference
+
+| Symptom | Check Workflow | Key File:Line |
+|---------|---------------|---------------|
+| [Issue type 1] | workflow_1 | file.ext:XXX |
+| [Issue type 2] | workflow_2 | file.ext:YYY |
+| [Issue type 3] | workflow_3 | file.ext:ZZZ |
+
+---
+
+## Context Engineering Usage
+
+### Loading Strategy
+
+```
+Step 1: Load this file (~15k tokens)
+Step 2: Identify relevant workflow(s)
+Step 3: Load specific workflow file (~20-50k tokens)
+Step 4: Read specific code sections as needed
+
+Total: ~50-80k tokens (25-40% of budget)
+```
+
+### When to Load Full Workflow
+
+- **Debugging:** Load the affected workflow immediately
+- **Feature:** Load 2-3 related workflows
+- **Refactoring:** Load primary + dependent workflows
+
+### When NOT to Load Full Workflow
+
+- **Simple fix:** Use this index + grep
+- **Configuration change:** Direct file edit
+- **Documentation update:** Direct doc edit
+
+---
+
+## Maintenance Schedule
+
+| Task | Frequency | Time Required |
+|------|-----------|---------------|
+| Spot-check 5 line numbers | Monthly | 15 minutes |
+| Re-run 3 discovery agents | Quarterly | 2 hours |
+| Full documentation audit | Annually | 4-6 hours |
+
+**Last Verification:** {{DATE}}
+**Next Verification:** {{NEXT_DATE}}
+
+---
+
+## See Also
+
+- **Detailed workflows:** [./workflows/](./workflows/)
+- **Code organization:** [../indexes/code/CATEGORY_INDEX.md](../indexes/code/CATEGORY_INDEX.md)
+- **Agent selection:** [../indexes/agents/CATEGORY_INDEX.md](../indexes/agents/CATEGORY_INDEX.md)
+- **Reverse lookup:** [./CODE_TO_WORKFLOW_MAP.md](./CODE_TO_WORKFLOW_MAP.md)
+
+---
+
+**Version:** 1.0
+**Total Workflows:** {{WORKFLOWS_COUNT}}

package/templates/base/context/workflows/WORKFLOW_TEMPLATE.md

@@ -0,0 +1,294 @@
+# [Workflow Name] Workflow
+
+**Last Updated:** YYYY-MM-DD
+**Last Verified Against Code:** YYYY-MM-DD (commit: HASH)
+**Complexity:** HIGH / MEDIUM / LOW
+**Token Estimate:** ~XX,XXX tokens (X% of 200k context)
+
+---
+
+## Quick Navigation
+
+- [Overview](#overview)
+- [Entry Points](#entry-points)
+- [Sub-Workflow 1: [Name]](#sub-workflow-1-name)
+- [Sub-Workflow 2: [Name]](#sub-workflow-2-name)
+- [Database Schema](#database-schema)
+- [External APIs](#external-apis)
+- [Test Coverage](#test-coverage)
+- [Known Gotchas](#known-gotchas)
+- [Complete Call Chain](#complete-call-chain)
+- [File Reference Table](#file-reference-table)
+
+---
+
+## Overview
+
+**User Journey:**
+[Describe what the user experiences from start to finish]
+
+**Key Features:**
+- [Feature 1]
+- [Feature 2]
+- [Feature 3]
+
+**Business Logic Summary:**
+[2-3 sentences explaining the core business rules]
+
+---
+
+## Entry Points
+
+### Entry Point 1: [Name]
+
+**File:** `path/to/file.ext` [Line XXX]
+**Function:** `function_name()` [Lines XXX-YYY]
+**Trigger:** [What triggers this entry point - API call, button click, scheduled job, etc.]
+
+```
+[Brief code snippet if helpful]
+```
+
+---
+
+### Entry Point 2: [Name]
+
+[Same structure as Entry Point 1...]
+
+---
+
+## Sub-Workflow 1: [Name]
+
+**Purpose:** [What this sub-workflow accomplishes]
+**Entry Point:** `file.ext:function_name()` [Line XXX]
+
+### Call Chain
+
+```
+function_name() [file.ext:XXX]
+├─ step_one() [file.ext:YYY]
+│  ├─ helper_a() [helper.ext:ZZZ]
+│  └─ helper_b() [helper.ext:AAA]
+├─ step_two() [file.ext:BBB]
+│  └─ database_query() [crud.ext:CCC]
+└─ step_three() [file.ext:DDD]
+   └─ external_api() [client.ext:EEE]
+```
+
+### Database Operations
+
+| Operation | Table | Purpose |
+|-----------|-------|---------|
+| READ | `table_name` | [Why reading] |
+| WRITE | `table_name` | [What writing] |
+| UPDATE | `table_name` | [What updating] |
+
+### External APIs
+
+| API | Endpoint | Purpose |
+|-----|----------|---------|
+| [API Name] | `POST /endpoint` | [What it does] |
+
+### Error Handling
+
+| Error | Handling | Recovery |
+|-------|----------|----------|
+| [Error type] | [How handled] | [How to recover] |
+
+---
+
+## Sub-Workflow 2: [Name]
+
+[Same structure as Sub-Workflow 1...]
+
+---
+
+## Database Schema
+
+### Tables Involved
+
+| Table | Purpose | Key Fields |
+|-------|---------|------------|
+| `table_1` | [Purpose] | `field_a`, `field_b` |
+| `table_2` | [Purpose] | `field_c`, `field_d` |
+
+### Relationships
+
+```
+table_1 ─┬─< table_2 (one-to-many via foreign_key)
+         └─< table_3 (one-to-many via other_key)
+```
+
+### Schema Notes
+
+[Any important schema considerations, constraints, indexes, etc.]
+
+---
+
+## External APIs
+
+### [API Name 1]
+
+**Base URL:** `https://api.example.com`
+**Authentication:** [Method - API Key, OAuth, etc.]
+**Rate Limits:** [If applicable]
+
+**Endpoints Used:**
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/endpoint` | POST | [What it does] |
+
+**Error Codes:**
+| Code | Meaning | Handling |
+|------|---------|----------|
+| 400 | [Meaning] | [How handled] |
+| 500 | [Meaning] | [How handled] |
+
+---
+
+## Test Coverage
+
+### E2E Tests
+
+| Test File | Test Name | Coverage |
+|-----------|-----------|----------|
+| `tests/e2e/test_file.ext` | `test_scenario` | Sub-workflows 1-3 |
+
+### Unit Tests
+
+| Test File | Coverage Area |
+|-----------|---------------|
+| `tests/unit/test_file.ext` | Function X, Function Y |
+
+### Coverage Gaps
+
+- ❌ [Missing test scenario 1]
+- ❌ [Missing test scenario 2]
+- ⚠️ [Edge case not covered]
+
+### Running Tests
+
+```bash
+# Run all tests for this workflow
+[test command]
+
+# Run specific test
+[specific test command]
+```
+
+---
+
+## Known Gotchas
+
+### Gotcha 1: [Title]
+
+**Severity:** CRITICAL / HIGH / MEDIUM / LOW
+**Symptom:** [What goes wrong]
+**Root Cause:** [Why it happens]
+
+**Fix:**
+```
+[Code or steps to fix]
+```
+
+**Prevention:**
+- [How to avoid in future]
+
+**Workflow Impact:** Sub-Workflow [X] is affected
+
+---
+
+### Gotcha 2: [Title]
+
+[Same structure as Gotcha 1...]
+
+---
+
+## Complete Call Chain
+
+### End-to-End Flow Diagram
+
+```
+[User Action / Trigger]
+         │
+         ▼
+┌─────────────────────┐
+│   Entry Point       │ file.ext:XXX
+│   function_name()   │
+└─────────┬───────────┘
+          │
+          ▼
+┌─────────────────────┐
+│   Sub-Workflow 1    │
+│   [Name]            │
+└─────────┬───────────┘
+          │
+          ▼
+┌─────────────────────┐
+│   Sub-Workflow 2    │ ──► [External API]
+│   [Name]            │
+└─────────┬───────────┘
+          │
+          ▼
+┌─────────────────────┐
+│   Database          │
+│   Operations        │
+└─────────┬───────────┘
+          │
+          ▼
+┌─────────────────────┐
+│   Response/         │
+│   Completion        │
+└─────────────────────┘
+```
+
+### State Transitions (if applicable)
+
+```
+[STATE_A] ──event──► [STATE_B] ──event──► [STATE_C]
+     │                                        │
+     └──────────── error ────────────────────►│
+                                              ▼
+                                         [STATE_ERROR]
+```
+
+---
+
+## File Reference Table
+
+| File | Size | Purpose | Key Functions |
+|------|------|---------|---------------|
+| `path/file_1.ext` | XX KB | [What it does] | `func_a:XXX`, `func_b:YYY` |
+| `path/file_2.ext` | XX KB | [What it does] | `func_c:ZZZ` |
+| `path/file_3.ext` | XX KB | [What it does] | `func_d:AAA` |
+
+---
+
+## Maintenance Schedule
+
+| Task | Frequency | Last Done | Next Due |
+|------|-----------|-----------|----------|
+| Verify line numbers | Monthly | YYYY-MM-DD | YYYY-MM-DD |
+| Full audit | Quarterly | YYYY-MM-DD | YYYY-MM-DD |
+
+---
+
+## Related Documentation
+
+- **Parent Index:** [WORKFLOW_INDEX.md](../WORKFLOW_INDEX.md)
+- **Related Workflows:** [workflow_2.md](./workflow_2.md)
+- **Responsible Agent:** [agent-name.md](../../agents/agent-name.md)
+
+---
+
+## Change Log
+
+| Date | Change | Commit |
+|------|--------|--------|
+| YYYY-MM-DD | Initial documentation | `hash` |
+
+---
+
+**Version:** 1.0
+**Word Count:** ~XXX words
+**Token Estimate:** ~XX,XXX tokens