k0ntext 3.0.0

package/templates/base/README.md

@@ -0,0 +1,260 @@
+# .claude Configuration - {{PROJECT_NAME}}
+
+This directory contains a comprehensive context engineering system for the {{PROJECT_NAME}} repository.
+
+**Configuration Summary**:
+- **Agents**: {{AGENTS_COUNT}} specialized agents (workflow-aligned)
+- **Commands**: {{COMMANDS_COUNT}} custom commands
+- **Workflows**: {{WORKFLOWS_COUNT}} documented workflows
+- **Context Budget**: 200k tokens max, target <40% utilization
+- **Output Budget**: 30k tokens max per response
+- **Last Updated**: {{DATE}}
+
+**System Benefits**:
+- <40% context utilization (vs 60%+ without this system)
+- 10× faster issue resolution with pre-computed knowledge
+- Self-maintaining documentation (zero drift)
+- Proactive bug discovery through validation
+
+---
+
+## Table of Contents
+
+1. [Agent Architecture](#agent-architecture)
+2. [Custom Commands](#custom-commands)
+3. [Context Documentation](#context-documentation)
+4. [RPI Workflow](#rpi-workflow)
+5. [Quick Start Guide](#quick-start-guide)
+6. [Self-Maintaining Documentation](#self-maintaining-documentation)
+
+---
+
+## Agent Architecture
+
+### Specialized Agents (Workflow-Aligned)
+
+| Agent | Primary Workflows | Use For |
+|-------|------------------|---------|
+| `context-engineer` | INITIALIZATION | Transform this template for any codebase |
+| {{AGENT_TABLE_ROWS}} |
+
+**Agent Location:** `.ai-context/agents/*.md`
+
+---
+
+## Custom Commands
+
+### RPI Workflow Commands (3)
+| Command | Description |
+|---------|-------------|
+| `/rpi-research` | Research phase - codebase exploration |
+| `/rpi-plan` | Plan phase - implementation blueprint |
+| `/rpi-implement` | Implement phase - execution with doc updates |
+
+### Validation Commands
+| Command | Description |
+|---------|-------------|
+| `/validate-all` | Complete validation suite |
+| `/verify-docs-current` | Documentation freshness validation |
+
+### System Commands (NEW in v1.1)
+| Command | Description |
+|---------|-------------|
+| `/context-optimize` | Generate RPI TODO list with interactive scoping |
+| `/help` | Comprehensive help system |
+| `/collab` | Team collaboration (handoffs, sync) |
+| `/analytics` | Local usage statistics |
+| `/session-save` | Save current Claude Code session state |
+| `/session-resume` | Restore previously saved session |
+
+**Command Location:** `.ai-context/commands/*.md`
+
+---
+
+## Context Documentation
+
+### 3-Level Chain-of-Index Architecture
+
+**Purpose:** Minimize context usage through progressive loading
+
+**Level 1 - Category Indexes (5 files in `indexes/`):**
+| Category | Purpose | Load When |
+|----------|---------|-----------|
+| `workflows/CATEGORY_INDEX.md` | Workflow categories | Starting workflow task |
+| `code/CATEGORY_INDEX.md` | Domain × Layer overview | Finding code files |
+| `search/CATEGORY_INDEX.md` | Search strategies | Low-level debugging |
+| `agents/CATEGORY_INDEX.md` | Agent selection matrix | Choosing agent |
+| `routing/CATEGORY_INDEX.md` | Task routing | Classifying task type |
+
+**Level 2 - Domain Indexes:** See `indexes/workflows/*.md`, `indexes/code/*.md`
+
+**Level 3 - Detail Files:** workflows/, agents/, commands/
+
+### Pre-Computed Knowledge
+
+| File | Purpose |
+|------|---------|
+| `ARCHITECTURE_SNAPSHOT.md` | High-level system map |
+| `FILE_OWNERSHIP.md` | What each file does |
+| `INTEGRATION_POINTS.md` | External APIs |
+| `KNOWN_GOTCHAS.md` | Documented fixes and lessons |
+| `TESTING_MAP.md` | Test coverage mapping |
+
+---
+
+## RPI Workflow
+
+**Research-Plan-Implement** methodology for structured development.
+
+### Phases
+
+1. **RESEARCH** (`/rpi-research`)
+   - Use sub-agents to investigate
+   - Output: Research document in `research/active/`
+   - Context budget: 25-30%
+
+2. **PLAN** (`/rpi-plan`)
+   - Create implementation blueprint with file:line precision
+   - Output: Plan document in `plans/active/`
+   - Context budget: 20-25%
+
+3. **IMPLEMENT** (`/rpi-implement`)
+   - Execute with atomic changes
+   - ONE CHANGE → ONE TEST → ONE COMMIT
+   - Update documentation (mandatory)
+   - Context budget: 30-40%
+
+### Directory Structure
+
+```
+.ai-context/
+├── research/
+│   ├── active/           # Current research
+│   ├── completed/        # Archived research
+│   └── RESEARCH_TEMPLATE.md
+├── plans/
+│   ├── active/           # Current plans
+│   ├── completed/        # Archived plans
+│   └── PLAN_TEMPLATE.md
+├── context/
+│   ├── WORKFLOW_INDEX.md     # Primary entry point
+│   ├── CODE_TO_WORKFLOW_MAP.md
+│   └── workflows/            # Workflow detail files
+├── indexes/
+│   ├── workflows/        # Workflow category indexes
+│   ├── code/            # Code domain indexes
+│   ├── agents/          # Agent selection indexes
+│   ├── routing/         # Task routing indexes
+│   └── search/          # Search pattern indexes
+├── agents/              # Specialized agent definitions
+├── commands/            # Custom command definitions
+├── tools/               # CLI tooling (NEW v1.1)
+├── schemas/             # JSON validation schemas (NEW v1.1)
+├── config/              # Environment configurations (NEW v1.1)
+├── team/                # Team collaboration config (NEW v1.1)
+├── knowledge/           # Shared knowledge base (NEW v1.1)
+├── standards/           # Community standards (NEW v1.1)
+└── ci-templates/        # CI/CD workflow templates (NEW v1.1)
+```
+
+---
+
+## Quick Start Guide
+
+### 1. Session Initialization
+```bash
+# Load workflow index (~15k tokens)
+Read: .ai-context/context/WORKFLOW_INDEX.md
+
+# Load specific workflows as needed (~20-50k each)
+Read: .ai-context/context/workflows/[relevant_workflow].md
+```
+
+### 2. Debugging an Issue
+```
+1. Scan WORKFLOW_INDEX.md → Find relevant workflow
+2. Load workflow file → Get file:line references
+3. Fix issue with complete context
+4. Update documentation (CODE_TO_WORKFLOW_MAP guides)
+5. Run /verify-docs-current
+```
+
+### 3. Implementing a Feature
+```
+1. Run /rpi-research → Explore codebase
+2. Run /rpi-plan → Create implementation blueprint
+3. Run /rpi-implement → Execute with doc updates
+```
+
+---
+
+## Self-Maintaining Documentation
+
+### Automatic Documentation Updates
+
+After every code change, update documentation:
+
+1. Check `CODE_TO_WORKFLOW_MAP.md` for affected workflows
+2. Update workflow files with new line numbers
+3. Verify function signatures match code
+4. Update diagrams if state machine changed
+5. Run `/verify-docs-current` for validation
+6. Commit documentation updates with code changes
+
+### Post-Implementation Checklist (Embedded in All Agents)
+
+```markdown
+## Post-Implementation Checklist
+
+**MANDATORY:** After making ANY code changes, update documentation.
+
+1. Check CODE_TO_WORKFLOW_MAP.md for affected workflows
+2. Update workflows with new line numbers
+3. Verify function signatures match
+4. Run /verify-docs-current
+5. Commit doc updates with code changes
+```
+
+---
+
+## Context Budget Limits
+
+**Hard Caps (Non-Negotiable):**
+- **Maximum Context:** 200,000 tokens
+- **Maximum Output:** 30,000 tokens per response
+- **Target Utilization:** <40% (80,000 tokens)
+- **Compaction Trigger:** 35% (70,000 tokens)
+
+**Budget Allocation:**
+```
+Workflow Indexes:      ~15k tokens (7.5%)
+Workflow Details:      ~40k tokens (20%)
+Active Code:           ~30k tokens (15%)
+Tool Results:          ~15k tokens (7.5%)
+─────────────────────────────────────────
+Typical Session:       ~100k tokens (50%)
+Buffer:                ~100k tokens (50%)
+```
+
+---
+
+## Initialization
+
+To transform this template for your codebase, use:
+
+```bash
+@context-engineer "Initialize context engineering for this repository"
+```
+
+This agent will:
+1. Analyze your codebase structure
+2. Identify major workflows (8-15)
+3. Create workflow documentation
+4. Set up index hierarchy
+5. Configure specialized agents
+6. Validate the system
+
+---
+
+*Configuration updated: {{DATE}}*
+*Version: 1.2.0 (Template)*

package/templates/base/RPI_WORKFLOW_PLAN.md

@@ -0,0 +1,325 @@
+# RPI (Research, Plan, Implement) Workflow
+
+**Created:** {{DATE}}
+**Platform:** Claude Code
+**Context Budget:** 200k tokens max, target <40%
+**Output Budget:** 30k tokens max per response
+
+---
+
+## Executive Summary
+
+The RPI workflow prevents the "slop" and "dumb zone" problems in AI-assisted development. By separating research, planning, and implementation into distinct phases, we achieve:
+
+- **90% fewer cascading errors**
+- **3× faster feature implementation**
+- **5× faster issue resolution**
+- **Self-documenting changes**
+
+**Key Innovation: Parallel Agents with Chunked Todolists**
+
+Each RPI phase inherently utilizes parallel agents and produces chunk-based outputs designed for consumption by the next phase. This creates a self-aware pipeline where:
+- RPI-Research outputs chunks knowing RPI-Plan will consume them
+- RPI-Plan creates chunk-todolists knowing RPI-Implement will process them
+- Each phase loops through chunks, marking completion as it progresses
+
+---
+
+## Phase 1: RESEARCH
+
+### Purpose
+Understand the system, locate relevant components, prevent context pollution
+
+### Artifacts
+- Research document in `.ai-context/research/active/[feature]_research.md`
+- **Chunked Research Sections** (3-7 chunks based on complexity)
+- 150-word summary for parent context
+
+### Process
+1. Load WORKFLOW_INDEX.md first (saves 100k+ tokens)
+2. **Spawn 3-5 parallel Explore agents** (one per research domain)
+3. Each agent produces a **Research Chunk** with:
+   - Chunk ID (e.g., `CHUNK-R1`, `CHUNK-R2`)
+   - Explored files with line numbers
+   - Call chains traced
+   - Dependencies found
+   - Chunk status: `COMPLETE` | `IN_PROGRESS` | `BLOCKED`
+4. Aggregate chunks into unified research document
+5. Format output specifically for RPI-Plan consumption
+
+### Parallel Agent Strategy
+```
+┌─────────────────────────────────────────────────────────┐
+│ RPI-RESEARCH PARALLEL EXECUTION                         │
+├─────────────────────────────────────────────────────────┤
+│ Agent 1: API/Route Entry Points        → CHUNK-R1      │
+│ Agent 2: Business Logic & Models       → CHUNK-R2      │
+│ Agent 3: Database/Storage Layer        → CHUNK-R3      │
+│ Agent 4: External Integrations         → CHUNK-R4      │
+│ Agent 5: Test Coverage Analysis        → CHUNK-R5      │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Inter-Phase Awareness
+**RPI-Research KNOWS that RPI-Plan will:**
+- Read each chunk sequentially
+- Generate a planning todolist per chunk
+- Mark chunks as `PLANNED` when processed
+- Require: chunk IDs, file:line refs, dependency list
+
+### Context Budget
+- Starting: Up to 50k tokens for exploration
+- Ending: 20k tokens (research doc only)
+- Compaction: After each phase
+
+### Exit Criteria
+- [ ] Research document created with chunked structure
+- [ ] 3-20 relevant files identified per chunk
+- [ ] Call chains traced with line numbers
+- [ ] Dependencies mapped per chunk
+- [ ] 150-word summary generated
+- [ ] **Chunk manifest created for RPI-Plan**
+
+---
+
+## Phase 2: PLAN
+
+### Purpose
+Design implementation with file:line precision, get human alignment
+
+### Artifacts
+- Plan document in `.ai-context/plans/active/[feature]_plan.md`
+- **Chunk-Based Todolists** (one per research chunk)
+- Step-by-step implementation roadmap
+
+### Process
+1. Load research document with chunks
+2. **For each Research Chunk (CHUNK-Rn):**
+   a. Create corresponding Plan Chunk (CHUNK-Pn)
+   b. Generate specific todolist for that chunk
+   c. Mark research chunk as `PLANNED`
+   d. Record dependencies between plan chunks
+3. Reference workflow gotchas
+4. Create modification list with exact line numbers
+5. Plan testing strategy per chunk
+6. Define rollback plan
+7. **Loop until all research chunks are processed**
+
+### Chunk-Based Todolist Generation
+```
+┌─────────────────────────────────────────────────────────┐
+│ RPI-PLAN CHUNK PROCESSING LOOP                          │
+├─────────────────────────────────────────────────────────┤
+│ FOR each CHUNK-Rn in research_chunks:                   │
+│   1. Read CHUNK-Rn content                              │
+│   2. Create CHUNK-Pn todolist:                          │
+│      - [ ] Analyze files from CHUNK-Rn                  │
+│      - [ ] Define modifications with line numbers       │
+│      - [ ] Specify tests for this chunk                 │
+│      - [ ] Document rollback for this chunk             │
+│   3. Mark CHUNK-Rn as PLANNED                           │
+│   4. Link CHUNK-Pn dependencies                         │
+│   5. Proceed to next CHUNK-R(n+1)                       │
+│ END LOOP                                                │
+│ Generate unified plan document                          │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Inter-Phase Awareness
+**RPI-Plan KNOWS that:**
+- RPI-Research structured chunks for sequential processing
+- RPI-Implement will read each CHUNK-Pn as an atomic unit
+- Each CHUNK-Pn must be independently implementable
+- Chunk dependencies must be explicit for proper ordering
+
+### Context Budget
+- Research doc: 20k tokens
+- Plan creation: 15k tokens
+- Total: 35k tokens (17.5%)
+
+### Exit Criteria
+- [ ] Plan document created with file:line references
+- [ ] **All research chunks marked as PLANNED**
+- [ ] **Chunk-todolists created for each chunk**
+- [ ] All modifications listed with risk level
+- [ ] Test strategy defined per chunk
+- [ ] Rollback plan documented
+- [ ] Human review completed
+- [ ] **Chunk manifest created for RPI-Implement**
+
+---
+
+## Phase 3: IMPLEMENT
+
+### Purpose
+Execute atomically with continuous testing
+
+### Golden Rule
+```
+ONE CHUNK → COMPLETE TODOLIST → MARK DONE → NEXT CHUNK
+```
+
+### Process
+1. Load plan document with chunk-todolists
+2. **For each Plan Chunk (CHUNK-Pn):**
+   a. Load chunk-specific todolist
+   b. Execute each todo item atomically:
+      - Make single change
+      - Run chunk-specific test
+      - Commit if pass, stop if fail
+   c. Update documentation for this chunk
+   d. Mark CHUNK-Pn as `IMPLEMENTED`
+   e. Mark corresponding CHUNK-Rn in research as `IMPLEMENTED`
+   f. Proceed to next CHUNK-P(n+1)
+3. **Loop until all plan chunks are processed**
+4. Run full test suite after all chunks complete
+
+### Chunk-Based Implementation Loop
+```
+┌─────────────────────────────────────────────────────────┐
+│ RPI-IMPLEMENT CHUNK PROCESSING LOOP                     │
+├─────────────────────────────────────────────────────────┤
+│ FOR each CHUNK-Pn in plan_chunks:                       │
+│   1. Load CHUNK-Pn todolist                             │
+│   2. FOR each TODO item in CHUNK-Pn:                    │
+│      a. Make atomic change                              │
+│      b. Run specified test                              │
+│      c. If PASS: commit, mark TODO complete             │
+│      d. If FAIL: stop, investigate, fix                 │
+│   3. Update chunk documentation                         │
+│   4. Mark CHUNK-Pn as IMPLEMENTED                       │
+│   5. Update research CHUNK-Rn status to COMPLETE        │
+│   6. Context reset if >35% utilization                  │
+│   7. Proceed to CHUNK-P(n+1)                            │
+│ END LOOP                                                │
+│ Run full test suite                                     │
+│ Archive plan and research documents                     │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Inter-Phase Awareness
+**RPI-Implement KNOWS that:**
+- RPI-Plan structured chunks for atomic implementation
+- Each CHUNK-Pn contains a complete, ordered todolist
+- Chunk dependencies dictate execution order
+- Marking chunks updates both plan and research documents
+
+### Context Budget
+- Plan: 15k tokens
+- Active code: 30k tokens
+- Test results: 15k tokens
+- Total: 60k tokens (30%)
+
+### Context Reset (Every 3 Chunks or 35% Utilization)
+1. Update progress checklist
+2. Re-read plan document
+3. Verify scope alignment
+4. Compact if >35% utilization
+
+### Exit Criteria
+- [ ] **All plan chunks marked as IMPLEMENTED**
+- [ ] **All research chunks marked as COMPLETE**
+- [ ] All tests passing
+- [ ] Documentation updated per chunk
+- [ ] Changes committed
+
+---
+
+## Inter-Phase Communication Protocol
+
+The key innovation of the enhanced RPI workflow is **inter-phase awareness**. Each phase produces output specifically formatted for the next phase's consumption.
+
+### Research → Plan Communication
+```
+CHUNK_MANIFEST:
+├── CHUNK-R1: (status, files, dependencies, ready_for_planning)
+├── CHUNK-R2: (status, files, dependencies, ready_for_planning)
+└── CHUNK-Rn: ...
+
+INTER_PHASE_CONTRACT:
+├── expected_consumer: "rpi-plan"
+├── chunk_processing_order: "sequential"
+├── mark_as_planned_when: "chunk_todolist_created"
+└── required_output: "CHUNK-Pn per CHUNK-Rn"
+```
+
+### Plan → Implement Communication
+```
+CHUNK_MANIFEST:
+├── CHUNK-P1: (todolist, tests, rollback, dependencies)
+├── CHUNK-P2: (todolist, tests, rollback, dependencies)
+└── CHUNK-Pn: ...
+
+INTER_PHASE_CONTRACT:
+├── expected_consumer: "rpi-implement"
+├── chunk_processing_order: "dependency-ordered"
+├── mark_as_implemented_when: "all_todos_complete"
+└── update_research_status: true
+```
+
+---
+
+## Error Recovery Protocol
+
+| Error Type | Response |
+|------------|----------|
+| Syntax Error | STOP. Fix immediately in same session. |
+| Import Error | Check file paths, verify imports. |
+| Runtime Error | Create research subtask before fixing. |
+| Test Failure | Do NOT add more code. Investigate first. |
+| 3+ Failures | STOP. Compact context. Start new session. |
+| **Chunk Failure** | Mark chunk as BLOCKED, proceed to independent chunks, revisit later. |
+
+---
+
+## Context Management
+
+### Compaction Triggers
+- After 5+ file reads without tool use
+- Error loop (3+ failed attempts)
+- Session > 1 hour
+- Context > 35% utilization
+- **After every 3 chunks processed**
+
+### Compaction Actions
+1. Save progress to SESSION_HANDOFF.md
+2. Archive tool results
+3. Keep only essential context
+4. Continue or start fresh session
+5. **Preserve chunk manifest with current status**
+
+---
+
+## Key Principles
+
+1. **<40% Context Rule:** Performance degrades beyond 40% context utilization
+2. **Parallel Sub-Agents:** Use 3-5 parallel Explore agents for context isolation
+3. **Chunk-Based Processing:** All phases produce and consume chunk-structured data
+4. **Inter-Phase Awareness:** Each phase knows how the next phase reads its output
+5. **Atomic Changes:** Small, testable, reversible modifications per todo item
+6. **Loop-Based Completion:** Process chunks in loops, marking progress explicitly
+7. **Bidirectional Status Updates:** Implement updates plan AND research status
+
+---
+
+## Quick Reference: Chunk Status Flow
+
+```
+RESEARCH CHUNKS                 PLAN CHUNKS
+┌─────────────────┐            ┌─────────────────┐
+│ CHUNK-R1        │            │ CHUNK-P1        │
+│ Status: FOUND   │────────────│ Status: READY   │
+│ → COMPLETE      │            │ → IMPLEMENTING  │
+│ → PLANNED       │←───────────│ → IMPLEMENTED   │
+│ → IMPLEMENTED   │←───────────│ → COMPLETE      │
+└─────────────────┘            └─────────────────┘
+```
+
+**Status Transitions:**
+- Research: `FOUND` → `COMPLETE` → `PLANNED` → `IMPLEMENTED`
+- Plan: `DRAFT` → `READY` → `IMPLEMENTING` → `IMPLEMENTED` → `COMPLETE`
+
+---
+
+**Version:** 2.0 (Enhanced with Parallel Agents & Chunked Todolists)
+**Status:** TEMPLATE

package/templates/base/agents/api-developer.md

@@ -0,0 +1,76 @@
+---
+name: api-developer
+version: "1.0.0"
+displayName: "API Developer"
+description: "API design, contract definition, and endpoint implementation specialist"
+category: "api"
+complexity: "medium"
+context_budget: "~35K tokens"
+capabilities:
+  - "rest-api-design"
+  - "graphql-design"
+  - "contract-definition"
+  - "endpoint-documentation"
+  - "api-testing-strategy"
+workflows:
+  - "api-endpoints"
+  - "contracts"
+  - "versioning"
+commands: ["/rpi-research", "/rpi-plan", "/rpi-implement"]
+dependencies:
+  agents: []
+  commands: []
+hooks:
+  pre_invoke: null
+  post_invoke: "verify-docs-current"
+examples:
+  - invocation: '@api-developer "Document API endpoints for [resource]"'
+    description: "Create comprehensive API documentation"
+  - invocation: '@api-developer "Validate API contracts"'
+    description: "Check contract consistency and completeness"
+  - invocation: '@api-developer "Generate OpenAPI spec"'
+    description: "Create OpenAPI/Swagger specification"
+---
+
+# API Developer Agent
+
+**Purpose:** API design, contract definition, and endpoint implementation
+
+## Capabilities
+
+This agent specializes in:
+- **API design** - Creating RESTful and GraphQL APIs with proper conventions
+- **Contract definition** - Defining request/response schemas and validation rules
+- **Endpoint implementation** - Generating boilerplate for API endpoints
+- **Documentation generation** - Creating comprehensive API documentation
+- **Testing strategy** - Planning and implementing API tests
+
+## Usage
+
+After template initialization, this agent will be generated based on your API structure. It will:
+1. Analyze your existing API endpoints
+2. Create comprehensive API documentation
+3. Identify potential security vulnerabilities
+4. Provide recommendations for API optimization
+
+## Example Commands
+
+```bash
+@api-developer "Document API endpoints for [resource]"
+@api-developer "Validate API contracts for [endpoint]"
+@api-developer "Generate test cases for [API]"
+```
+
+## Integration Points
+
+This agent integrates with:
+- Workflow documentation
+- Database schema (for data endpoints)
+- Testing strategies
+- Security validation
+
+## Validation
+
+- API contract consistency
+- Endpoint security checks
+- Response schema validation