k0ntext 3.0.0

package/templates/base/plans/PLAN_TEMPLATE.md

@@ -0,0 +1,316 @@
+# 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
+**Total Chunks:** N (from research)
+**Chunk Dependencies:** [See Chunk Dependency Graph]
+
+---
+
+## Research Summary
+
+[Paste 150-word summary from research document]
+
+---
+
+## Chunk Manifest
+
+> **INTER-PHASE CONTRACT:** This manifest is designed for RPI-Implement consumption.
+> RPI-Implement will process each chunk's todolist, marking chunks complete as it progresses.
+
+| Chunk ID | From Research | Status | Todos | Dependencies | Ready |
+|----------|---------------|--------|-------|--------------|-------|
+| CHUNK-P1 | CHUNK-R1 | READY | 4 | None | ✅ |
+| CHUNK-P2 | CHUNK-R2 | READY | 5 | CHUNK-P1 | ⏳ |
+| CHUNK-P3 | CHUNK-R3 | READY | 3 | CHUNK-P2 | ⏳ |
+| CHUNK-P4 | CHUNK-R4 | READY | 2 | None | ✅ |
+| CHUNK-P5 | CHUNK-R5 | READY | 6 | CHUNK-P1, P2 | ⏳ |
+
+### Chunk Dependency Graph
+
+```
+CHUNK-P1 (API) ─────┬───→ CHUNK-P2 (Logic) ───→ CHUNK-P3 (DB)
+                    │              │
+CHUNK-P4 (External) │              │
+                    │              ↓
+                    └───→ CHUNK-P5 (Tests) ←───┘
+                         (depends on P1 and P2)
+```
+
+**Execution Order:** P1 → P4 (parallel) → P2 → P3 → P5
+
+---
+
+## 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]
+
+---
+
+## CHUNK-P1: API/Routes (from CHUNK-R1)
+
+**Status:** DRAFT | READY | IMPLEMENTING | IMPLEMENTED | COMPLETE
+**Research Chunk:** CHUNK-R1
+**Dependencies:** None
+**Update Research Status When Complete:** Mark CHUNK-R1 as IMPLEMENTED
+
+### Todolist
+
+| # | Action | File | Lines | Risk | Test | Status |
+|---|--------|------|-------|------|------|--------|
+| 1 | [Action description] | `path/file.ext` | XXX-YYY | LOW | `test_name` | ⏳ |
+| 2 | [Action description] | `path/file.ext` | XXX-YYY | MED | `test_name` | ⏳ |
+| 3 | [Action description] | `path/file.ext` | XXX-YYY | LOW | `test_name` | ⏳ |
+| 4 | [Action description] | `path/file.ext` | XXX-YYY | LOW | `test_name` | ⏳ |
+
+### Todo 1: [Action Name]
+
+**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]
+```
+
+**Test After:**
+```bash
+[Test command to run]
+```
+
+### Chunk Completion Criteria
+- [ ] All todos in CHUNK-P1 complete
+- [ ] All tests passing
+- [ ] Update CHUNK-R1 status to IMPLEMENTED
+- [ ] Proceed to dependent chunks (CHUNK-P2, CHUNK-P5)
+
+---
+
+## CHUNK-P2: Business Logic (from CHUNK-R2)
+
+**Status:** DRAFT | READY | IMPLEMENTING | IMPLEMENTED | COMPLETE
+**Research Chunk:** CHUNK-R2
+**Dependencies:** CHUNK-P1
+**Update Research Status When Complete:** Mark CHUNK-R2 as IMPLEMENTED
+
+### Todolist
+
+| # | Action | File | Lines | Risk | Test | Status |
+|---|--------|------|-------|------|------|--------|
+| 1 | [Action description] | `path/file.ext` | XXX-YYY | LOW | `test_name` | ⏳ |
+| 2 | [Action description] | `path/file.ext` | XXX-YYY | HIGH | `test_name` | ⏳ |
+
+### Chunk Completion Criteria
+- [ ] All todos in CHUNK-P2 complete
+- [ ] All tests passing
+- [ ] Update CHUNK-R2 status to IMPLEMENTED
+
+---
+
+## Inter-Phase Contract (RPI-Implement Consumption)
+
+```
+EXPECTED_CONSUMER: rpi-implement
+CHUNK_PROCESSING_ORDER: dependency-ordered (see Chunk Dependency Graph)
+MARK_AS_IMPLEMENTED_WHEN: all chunk todos complete
+UPDATE_RESEARCH_STATUS: true (mark CHUNK-Rn as IMPLEMENTED)
+CONTEXT_RESET_TRIGGER: every 3 chunks or 35% utilization
+```
+
+**What RPI-Implement Should Do:**
+1. Load chunk manifest and dependency graph
+2. Process chunks in dependency order
+3. For each chunk:
+   a. Execute todos atomically (one change → one test → one commit)
+   b. Mark todos complete as they pass
+   c. When all todos done, mark chunk IMPLEMENTED
+   d. Update corresponding research chunk status
+   e. Proceed to next ready chunk
+4. Loop until all chunks IMPLEMENTED
+5. Run full test suite
+6. Archive documents
+
+---
+
+## 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 (Per Chunk)
+| Chunk | Test | Purpose | Command |
+|-------|------|---------|---------|
+| P1 | `test_file::test_name` | [What it verifies] | `pytest path -k name` |
+| P2 | `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` |
+
+---
+
+## Verification Checklist
+
+### Before Starting
+- [ ] Research document reviewed
+- [ ] Plan approved by human
+- [ ] Current branch is clean (`git status`)
+- [ ] Tests passing before changes
+- [ ] **Chunk manifest understood**
+
+### After Each Chunk
+- [ ] All chunk todos complete
+- [ ] Chunk tests passing
+- [ ] Commit created with descriptive message
+- [ ] Research chunk status updated
+- [ ] **Context reset if needed**
+
+### After All Chunks
+- [ ] All chunks marked IMPLEMENTED
+- [ ] All research chunks marked IMPLEMENTED
+- [ ] Full test suite passes
+- [ ] Documentation updated
+- [ ] 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
+
+### Per-Chunk Rollback
+| Chunk | Rollback Command | Safe Commit |
+|-------|------------------|-------------|
+| P1 | `git revert [hash]` | `[hash]` |
+| P2 | `git revert [hash]` | `[hash]` |
+
+### Full Rollback
+```bash
+git revert HEAD~N  # Revert last N commits
+```
+
+---
+
+## Context Budget Estimate
+
+| Phase | Tokens | Percentage |
+|-------|--------|------------|
+| Plan Loading | ~15k | 7.5% |
+| Active Code (per chunk) | ~10k | 5% |
+| Test Results (per chunk) | ~5k | 2.5% |
+| **Per Chunk Total** | **~15k** | **7.5%** |
+| **Max Active (3 chunks)** | **~45k** | **22.5%** |
+
+---
+
+## Human Review Required
+
+**Before approval, human should verify:**
+
+1. **Scope Check:** Are we solving the right problem?
+2. **Chunk Structure:** Are chunks properly ordered?
+3. **Dependencies:** Are chunk dependencies correct?
+4. **Impact Analysis:** What else might break?
+5. **Testing Strategy:** Is coverage adequate per chunk?
+6. **Rollback Path:** Can we undo each chunk safely?
+
+**Human Notes:**
+```
+[Space for human reviewer notes]
+```
+
+**Approved:** [ ] Yes / [ ] No / [ ] With modifications
+**Approved by:** [Name]
+**Date:** YYYY-MM-DD
+
+---
+
+## Execution Log
+
+### Chunk Progress
+
+| Chunk | Status | Todos Done | Commit | Research Updated |
+|-------|--------|------------|--------|------------------|
+| P1 | ⏳ Pending | 0/4 | - | - |
+| P2 | ⏳ Pending | 0/5 | - | - |
+| P3 | ⏳ Pending | 0/3 | - | - |
+| P4 | ⏳ Pending | 0/2 | - | - |
+| P5 | ⏳ Pending | 0/6 | - | - |
+
+### Issues Encountered
+
+| Chunk | Issue | Resolution |
+|-------|-------|------------|
+| - | - | - |
+
+---
+
+## Next Steps After Completion
+
+1. ✅ All chunks IMPLEMENTED
+2. ✅ All research chunks IMPLEMENTED
+3. ⏳ Run full test suite
+4. ⏳ Update documentation
+5. ⏳ Run `/verify-docs-current`
+6. ⏳ Move plan to `.ai-context/plans/completed/`
+7. ⏳ Move research to `.ai-context/research/completed/`
+8. ⏳ Create PR/merge to main
+
+---
+
+**Plan Version:** 2.0 (Chunk-Based with Inter-Phase Awareness)
+**Last Updated:** YYYY-MM-DD

package/templates/base/research/RESEARCH_TEMPLATE.md

@@ -0,0 +1,245 @@
+# Research: [Feature/Bug Name]
+
+**Date:** YYYY-MM-DD
+**Researcher:** Claude Code
+**Status:** IN_PROGRESS | COMPLETE | BLOCKED
+**Context Budget Used:** X% of 200k
+**Total Chunks:** N
+**Parallel Agents Used:** N (3 minimum, up to 5 for complex features)
+
+---
+
+## Objective
+
+[Clear statement of what we're trying to understand - 1-2 sentences]
+
+---
+
+## Chunk Manifest
+
+> **INTER-PHASE CONTRACT:** This manifest is designed for RPI-Plan consumption.
+> RPI-Plan will process each chunk sequentially, creating a CHUNK-Pn todolist per CHUNK-Rn.
+
+| Chunk ID | Domain | Status | Files | Ready for Planning |
+|----------|--------|--------|-------|-------------------|
+| CHUNK-R1 | API/Routes | COMPLETE | 3 | ✅ |
+| CHUNK-R2 | Business Logic | COMPLETE | 4 | ✅ |
+| CHUNK-R3 | Database/Storage | COMPLETE | 2 | ✅ |
+| CHUNK-R4 | External Integrations | COMPLETE | 1 | ✅ |
+| CHUNK-R5 | Test Coverage | COMPLETE | 3 | ✅ |
+
+---
+
+## CHUNK-R1: API/Routes
+
+**Status:** FOUND | COMPLETE | PLANNED | IMPLEMENTED
+**Parallel Agent:** Agent 1
+**Ready for Planning:** Yes/No
+
+### Files Explored
+
+| File | Lines | Key Findings |
+|------|-------|--------------|
+| `path/to/route.ext` | XXX-YYY | [Entry point for feature] |
+| `path/to/handler.ext` | XXX-YYY | [Request handling logic] |
+
+### Code Flow Analysis
+
+```
+entry_function() [file.ext:XXX]
+├─ validate_request() [file.ext:YYY]
+└─ route_to_handler() [file.ext:ZZZ]
+```
+
+### Dependencies (This Chunk)
+- **External:** [API Name]
+- **Internal:** [service.ext]
+
+---
+
+## CHUNK-R2: Business Logic
+
+**Status:** FOUND | COMPLETE | PLANNED | IMPLEMENTED
+**Parallel Agent:** Agent 2
+**Ready for Planning:** Yes/No
+
+### Files Explored
+
+| File | Lines | Key Findings |
+|------|-------|--------------|
+| `path/to/service.ext` | XXX-YYY | [Core business logic] |
+| `path/to/model.ext` | XXX-YYY | [Data models] |
+
+### Code Flow Analysis
+
+```
+process_request() [service.ext:XXX]
+├─ validate_data() [service.ext:YYY]
+├─ apply_rules() [rules.ext:ZZZ]
+└─ persist_result() [model.ext:AAA]
+```
+
+### Dependencies (This Chunk)
+- **External:** [None]
+- **Internal:** [crud.ext, utils.ext]
+
+---
+
+## CHUNK-R3: Database/Storage
+
+**Status:** FOUND | COMPLETE | PLANNED | IMPLEMENTED
+**Parallel Agent:** Agent 3
+**Ready for Planning:** Yes/No
+
+### Files Explored
+
+| File | Lines | Key Findings |
+|------|-------|--------------|
+| `path/to/crud.ext` | XXX-YYY | [Database operations] |
+| `path/to/schema.ext` | XXX-YYY | [Schema definitions] |
+
+### Database Schema Involved
+
+| Table | Operations | Purpose |
+|-------|------------|---------|
+| `table_name` | READ/WRITE/UPDATE | [What data] |
+
+### Dependencies (This Chunk)
+- **External:** [Database driver]
+- **Internal:** [config.ext]
+
+---
+
+## CHUNK-R4: External Integrations
+
+**Status:** FOUND | COMPLETE | PLANNED | IMPLEMENTED
+**Parallel Agent:** Agent 4
+**Ready for Planning:** Yes/No
+
+### Files Explored
+
+| File | Lines | Key Findings |
+|------|-------|--------------|
+| `path/to/client.ext` | XXX-YYY | [External API client] |
+
+### External Dependencies
+
+| Dependency | Type | Purpose |
+|------------|------|---------|
+| [API Name] | HTTP API | [What it does] |
+| [Library] | Package | [What it provides] |
+
+---
+
+## CHUNK-R5: Test Coverage
+
+**Status:** FOUND | COMPLETE | PLANNED | IMPLEMENTED
+**Parallel Agent:** Agent 5
+**Ready for Planning:** Yes/No
+
+### 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], organized into [N] research chunks.
+
+**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 by Chunk:**
+1. CHUNK-R1 (API): [file_path:line]
+2. CHUNK-R2 (Logic): [file_path:line]
+3. CHUNK-R3 (DB): [file_path:line]
+
+**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]
+
+---
+
+## Inter-Phase Contract (RPI-Plan Consumption)
+
+```
+EXPECTED_CONSUMER: rpi-plan
+CHUNK_PROCESSING_ORDER: sequential (R1 → R2 → R3 → R4 → R5)
+MARK_AS_PLANNED_WHEN: chunk todolist created
+REQUIRED_OUTPUT: CHUNK-Pn per CHUNK-Rn
+STATUS_UPDATE_FIELD: "Status" in each chunk section
+```
+
+**What RPI-Plan Should Do:**
+1. Read each CHUNK-Rn in order
+2. Create corresponding CHUNK-Pn with todolist
+3. Mark CHUNK-Rn status as `PLANNED`
+4. Proceed to next chunk
+5. Loop until all chunks are PLANNED
+
+---
+
+## Next Steps
+
+After research completes:
+1. ✅ Research document saved in `.ai-context/research/active/`
+2. ✅ All chunks marked as COMPLETE
+3. ⏳ Run `/rpi-plan [feature-name]` to create implementation plan
+4. ⏳ RPI-Plan will process chunks and create todolists
+5. ⏳ Human reviews plan before `/rpi-implement`
+
+---
+
+**Context Usage Report:**
+- Files read: X
+- Tokens used: ~Xk (X% of 200k)
+- Parallel agents spawned: 3-5
+- Chunks created: N
+- 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
+}