create-universal-ai-context 2.0.0

package/templates/base/plans/PLAN_TEMPLATE.md

@@ -0,0 +1,250 @@
+# Implementation Plan: [Feature/Fix Name]
+
+**Date:** YYYY-MM-DD
+**Based on:** `.ai-context/research/active/[feature]_research.md`
+**Status:** DRAFT | APPROVED | IMPLEMENTING | COMPLETE
+**Estimated Changes:** X files, ~XXX lines
+**Context Budget:** Target <40% of 200k tokens
+
+---
+
+## Research Summary
+
+[Paste 150-word summary from research document]
+
+---
+
+## Scope Definition
+
+### In Scope
+- [ ] [Specific deliverable 1]
+- [ ] [Specific deliverable 2]
+- [ ] [Specific deliverable 3]
+
+### Out of Scope
+- [What we are NOT touching]
+- [Related but deferred work]
+- [Future enhancements]
+
+---
+
+## Files to Modify
+
+**CRITICAL:** All file references MUST include explicit line numbers
+
+| File | Lines | Change Description | Risk Level | Test Required |
+|------|-------|-------------------|------------|---------------|
+| `path/file.ext` | XXX-YYY | [What changes] | LOW/MED/HIGH | `test_name` |
+| `path/other.ext` | XXX-YYY | [What changes] | LOW/MED/HIGH | `test_name` |
+
+---
+
+## Step-by-Step Implementation
+
+### Step 1: [Action Name]
+
+**Priority:** 1 of N
+**File:** `path/to/file.ext`
+**Lines:** XXX-YYY
+**Risk:** LOW/MEDIUM/HIGH
+
+**Current Code:**
+```
+[Existing code that will be changed]
+```
+
+**Proposed Change:**
+```
+[New code after modification]
+```
+
+**Rationale:**
+[Why this change is needed - 1-2 sentences]
+
+**Test After:**
+```bash
+[Test command to run]
+```
+
+**Success Criteria:**
+- [ ] [What should work after this step]
+
+---
+
+### Step 2: [Action Name]
+
+**Priority:** 2 of N
+**File:** `path/to/file.ext`
+**Lines:** XXX-YYY
+**Risk:** LOW/MEDIUM/HIGH
+
+[Same structure as Step 1...]
+
+---
+
+## Workflow Impact Analysis
+
+### Affected Workflows
+Check `.ai-context/context/CODE_TO_WORKFLOW_MAP.md`:
+
+| Workflow | Impact | Update Required |
+|----------|--------|-----------------|
+| `workflow_name.md` | [How affected] | Yes/No |
+
+### Backward Compatibility
+- [ ] No breaking changes to public APIs
+- [ ] Database migrations are reversible
+- [ ] Configuration changes are backward compatible
+
+---
+
+## Testing Strategy
+
+### Unit Tests
+| Test | Purpose | Command |
+|------|---------|---------|
+| `test_file::test_name` | [What it verifies] | `pytest path -k name` |
+
+### Integration Tests
+| Test | Purpose | Command |
+|------|---------|---------|
+| `test_file::test_name` | [What it verifies] | `pytest path -k name` |
+
+### E2E Tests (if applicable)
+| Scenario | Purpose | Command |
+|----------|---------|---------|
+| [User flow] | [What it verifies] | `pytest path -k name` |
+
+---
+
+## Verification Checklist
+
+### Before Starting
+- [ ] Research document reviewed
+- [ ] Plan approved by human
+- [ ] Current branch is clean (`git status`)
+- [ ] Tests passing before changes (`pytest`)
+
+### After Each Step
+- [ ] Syntax check passes
+- [ ] Step-specific test passes
+- [ ] Commit created with descriptive message
+
+### After All Steps
+- [ ] All unit tests pass
+- [ ] All integration tests pass
+- [ ] Documentation updated (see below)
+- [ ] No linting errors
+
+---
+
+## Documentation Updates Required
+
+**MANDATORY:** Update after code changes
+
+### Workflow Files
+- [ ] `.ai-context/context/workflows/[name].md` - Update line numbers
+- [ ] Update function signatures if changed
+
+### Index Files
+- [ ] `.ai-context/context/CODE_TO_WORKFLOW_MAP.md` - Add new files if created
+
+### Agent Files
+- [ ] `.ai-context/agents/[name].md` - Update if capabilities changed
+
+### AI_CONTEXT.md
+- [ ] Update if architecture changed
+- [ ] Update if new commands added
+
+### Validation
+```bash
+/verify-docs-current [modified_file]
+```
+
+---
+
+## Rollback Plan
+
+### Quick Rollback
+```bash
+git revert HEAD~N  # Revert last N commits
+```
+
+### Safe State
+- **Commit:** `[hash]`
+- **Description:** Last known working state before changes
+
+### Recovery Steps
+1. [Step to recover if rollback needed]
+2. [Step to verify recovery]
+
+---
+
+## Context Budget Estimate
+
+| Phase | Tokens | Percentage |
+|-------|--------|------------|
+| Plan Loading | ~15k | 7.5% |
+| Active Code | ~30k | 15% |
+| Test Results | ~15k | 7.5% |
+| **Total** | **~60k** | **30%** |
+
+**Compaction Strategy:**
+- After Step 3: Archive completed step results
+- After Step 6: Full compaction, reload plan
+- On 35% trigger: Save progress, compact, continue
+
+---
+
+## Human Review Required
+
+**Before approval, human should verify:**
+
+1. **Scope Check:** Are we solving the right problem?
+2. **Impact Analysis:** What else might break?
+3. **Prior Art:** Did we check KNOWN_GOTCHAS.md?
+4. **Testing Strategy:** Is coverage adequate?
+5. **Rollback Path:** Can we undo safely?
+
+**Human Notes:**
+```
+[Space for human reviewer notes]
+```
+
+**Approved:** [ ] Yes / [ ] No / [ ] With modifications
+**Approved by:** [Name]
+**Date:** YYYY-MM-DD
+
+---
+
+## Execution Log
+
+### Step Progress
+
+| Step | Status | Commit | Notes |
+|------|--------|--------|-------|
+| 1 | ⏳ Pending | - | - |
+| 2 | ⏳ Pending | - | - |
+| 3 | ⏳ Pending | - | - |
+
+### Issues Encountered
+
+| Step | Issue | Resolution |
+|------|-------|------------|
+| - | - | - |
+
+---
+
+## Next Steps After Completion
+
+1. ✅ All steps completed
+2. ⏳ Run full test suite
+3. ⏳ Update documentation
+4. ⏳ Run `/verify-docs-current`
+5. ⏳ Move plan to `.ai-context/plans/completed/`
+6. ⏳ Create PR/merge to main
+
+---
+
+**Plan Version:** 1.0
+**Last Updated:** YYYY-MM-DD

package/templates/base/research/RESEARCH_TEMPLATE.md

@@ -0,0 +1,153 @@
+# Research: [Feature/Bug Name]
+
+**Date:** YYYY-MM-DD
+**Researcher:** Claude Code
+**Status:** IN_PROGRESS | COMPLETE | BLOCKED
+**Context Budget Used:** X% of 200k
+
+---
+
+## Objective
+
+[Clear statement of what we're trying to understand - 1-2 sentences]
+
+---
+
+## Relevant Files Explored
+
+| File | Lines | Key Findings |
+|------|-------|--------------|
+| `path/to/file.ext` | XXX-YYY | [What this file does for the feature] |
+| `path/to/other.ext` | XXX-YYY | [What this file does for the feature] |
+
+---
+
+## Code Flow Analysis
+
+**Entry Point → Exit Point Trace:**
+
+```
+entry_function() [file.ext:XXX]
+├─ step_one() [file.ext:YYY]
+│  └─ helper_function() [helper.ext:ZZZ]
+├─ step_two() [file.ext:AAA]
+│  ├─ database_query() [crud.ext:BBB]
+│  └─ external_api_call() [client.ext:CCC]
+└─ return_result() [file.ext:DDD]
+```
+
+**Decision Points:**
+- Line XXX: Condition check (if/else)
+- Line YYY: Type routing (switch/match)
+- Line ZZZ: Error handling (try/except)
+
+---
+
+## Dependencies Identified
+
+### External Dependencies
+| Dependency | Type | Purpose |
+|------------|------|---------|
+| [API Name] | HTTP API | [What it does] |
+| [Library] | Package | [What it provides] |
+
+### Internal Dependencies
+| File | Purpose |
+|------|---------|
+| `service.ext` | [What it provides to this feature] |
+| `utils.ext` | [What utilities are used] |
+
+---
+
+## Database Schema Involved
+
+| Table | Operations | Purpose |
+|-------|------------|---------|
+| `table_name` | READ/WRITE/UPDATE | [What data] |
+
+---
+
+## Test Files & Coverage
+
+### Existing Tests
+| Test File | Coverage Area |
+|-----------|---------------|
+| `tests/test_feature.ext` | [What scenarios] |
+
+### Coverage Gaps
+- ❌ [Missing test scenario 1]
+- ❌ [Missing test scenario 2]
+- ⚠️ [Edge case not covered]
+
+---
+
+## Known Gotchas
+
+Check `.ai-context/context/KNOWN_GOTCHAS.md` for:
+- [ ] Similar past issues
+- [ ] Related workarounds
+- [ ] Anti-patterns to avoid
+
+**Found Gotchas:**
+1. [Gotcha 1 if applicable]
+2. [Gotcha 2 if applicable]
+
+---
+
+## Open Questions
+
+### Technical Questions
+- [ ] [Question about implementation detail]
+- [ ] [Question about architecture choice]
+
+### Business Logic Questions
+- [ ] [Question about requirements]
+- [ ] [Question about edge cases]
+
+---
+
+## Summary (for Plan Phase)
+
+**Word Count Target: 150 words max**
+
+[Feature/Bug Name] is implemented across [X] files in [system area].
+
+**Entry Points:**
+- [Primary entry point with file:line]
+- [Secondary entry point if applicable]
+
+**Core Logic:**
+[1-2 sentences describing what the feature does]
+
+**Key Files:**
+1. [file_path] - [role in feature]
+2. [file_path] - [role in feature]
+3. [file_path] - [role in feature]
+
+**Dependencies:**
+- External: [API names]
+- Internal: [Service names]
+
+**Test Coverage:** [Good/Partial/Missing]
+
+**Recommended Approach:**
+[1 sentence on how to implement/fix]
+
+**Known Risks:**
+[1 sentence on primary risk]
+
+---
+
+## Next Steps
+
+After research completes:
+1. ✅ Research document saved in `.ai-context/research/active/`
+2. ⏳ Run `/rpi-plan [feature-name]` to create implementation plan
+3. ⏳ Human reviews plan before `/rpi-implement`
+
+---
+
+**Context Usage Report:**
+- Files read: X
+- Tokens used: ~Xk (X% of 200k)
+- Compaction needed: Yes/No

package/templates/base/schemas/agent.schema.json

@@ -0,0 +1,141 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://claude-context.dev/schemas/agent.schema.json",
+  "title": "Claude Context Agent",
+  "description": "Schema for agent manifest files",
+  "type": "object",
+  "required": ["name", "version", "description"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference"
+    },
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z0-9-]+$",
+      "minLength": 1,
+      "maxLength": 50,
+      "description": "Agent identifier (lowercase, hyphens allowed)"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Agent version (semver)"
+    },
+    "displayName": {
+      "type": "string",
+      "maxLength": 100,
+      "description": "Human-readable agent name"
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 500,
+      "description": "Brief description of agent capabilities"
+    },
+    "author": {
+      "type": "string",
+      "description": "Agent author"
+    },
+    "license": {
+      "type": "string",
+      "description": "SPDX license identifier"
+    },
+    "keywords": {
+      "type": "array",
+      "items": { "type": "string" },
+      "maxItems": 10,
+      "description": "Keywords for agent discovery"
+    },
+    "category": {
+      "type": "string",
+      "enum": [
+        "initialization",
+        "architecture",
+        "database",
+        "api",
+        "integration",
+        "deployment",
+        "testing",
+        "documentation",
+        "custom"
+      ],
+      "description": "Agent category"
+    },
+    "complexity": {
+      "type": "string",
+      "enum": ["low", "medium", "high", "very-high"],
+      "description": "Task complexity this agent handles"
+    },
+    "capabilities": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "List of capabilities (e.g., diagram-generation, dependency-analysis)"
+    },
+    "workflows": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Workflows this agent specializes in"
+    },
+    "commands": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Commands this agent can invoke"
+    },
+    "dependencies": {
+      "type": "object",
+      "properties": {
+        "agents": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Required agents"
+        },
+        "commands": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Required commands"
+        }
+      }
+    },
+    "config": {
+      "type": "object",
+      "properties": {
+        "context_budget": {
+          "type": "string",
+          "description": "Typical context usage (e.g., '~50k tokens')"
+        },
+        "timeout_minutes": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 120,
+          "description": "Execution timeout in minutes"
+        }
+      }
+    },
+    "hooks": {
+      "type": "object",
+      "properties": {
+        "pre_invoke": {
+          "type": ["string", "null"],
+          "description": "Command to run before agent invocation"
+        },
+        "post_invoke": {
+          "type": ["string", "null"],
+          "description": "Command to run after agent completion"
+        }
+      }
+    },
+    "examples": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "invocation": { "type": "string" },
+          "description": { "type": "string" }
+        },
+        "required": ["invocation", "description"]
+      },
+      "description": "Example invocations"
+    }
+  },
+  "additionalProperties": false
+}

package/templates/base/schemas/anchors.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://claude-context.dev/schemas/anchors.schema.json",
+  "title": "Claude Context Semantic Anchors",
+  "description": "Schema for sync/anchors.json - maps function signatures to workflow references",
+  "type": "object",
+  "required": ["version"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "description": {
+      "type": "string"
+    },
+    "generatedAt": {
+      "type": ["string", "null"],
+      "format": "date-time"
+    },
+    "files": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "anchors": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "object",
+              "properties": {
+                "line": { "type": "integer" },
+                "type": { "type": "string" },
+                "signature": { "type": "string" },
+                "hash": { "type": "string" },
+                "workflows": {
+                  "type": "array",
+                  "items": { "type": "string" }
+                }
+              }
+            }
+          },
+          "updatedAt": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/templates/base/schemas/automation.schema.json

@@ -0,0 +1,93 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://claude-context.dev/schemas/automation.schema.json",
+  "title": "Claude Context Automation Configuration",
+  "description": "Schema for automation/config.json",
+  "type": "object",
+  "required": ["version"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Configuration version"
+    },
+    "generators": {
+      "type": "object",
+      "description": "Auto-generation settings",
+      "properties": {
+        "code_mapper": {
+          "type": "object",
+          "properties": {
+            "enabled": { "type": "boolean", "default": true },
+            "output": { "type": "string" },
+            "include_patterns": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "exclude_patterns": {
+              "type": "array",
+              "items": { "type": "string" }
+            }
+          }
+        },
+        "index_builder": {
+          "type": "object",
+          "properties": {
+            "enabled": { "type": "boolean", "default": true },
+            "rebuild_on_change": { "type": "boolean", "default": true },
+            "indexes": {
+              "type": "array",
+              "items": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "hooks": {
+      "type": "object",
+      "description": "Git hook settings",
+      "properties": {
+        "pre_commit": {
+          "type": "object",
+          "properties": {
+            "enabled": { "type": "boolean", "default": true },
+            "check_drift": { "type": "boolean", "default": true },
+            "block_on_stale": { "type": "boolean", "default": false }
+          }
+        },
+        "post_commit": {
+          "type": "object",
+          "properties": {
+            "enabled": { "type": "boolean", "default": true },
+            "rebuild_code_map": { "type": "boolean", "default": true },
+            "update_hashes": { "type": "boolean", "default": true }
+          }
+        }
+      }
+    },
+    "sync": {
+      "type": "object",
+      "description": "Synchronization settings",
+      "properties": {
+        "semantic_anchors": { "type": "boolean", "default": true },
+        "hash_algorithm": {
+          "type": "string",
+          "enum": ["md5", "sha1", "sha256"],
+          "default": "md5"
+        },
+        "staleness_thresholds": {
+          "type": "object",
+          "properties": {
+            "warning_days": { "type": "integer", "default": 30 },
+            "stale_days": { "type": "integer", "default": 90 }
+          }
+        }
+      }
+    }
+  },
+  "additionalProperties": false
+}