k0ntext 3.7.0 → 3.8.1

package/docs/plans/2026-02-11-context-engineering-enhancement.md

@@ -0,0 +1,1402 @@
+# Context Engineering System Enhancement Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Build a unified `.claude/` context engineering system with commands, agents, sync, and TodoList tracking for AI coding sessions.
+
+**Architecture:** Agent-Dispatcher pattern with TodoList tracking, timestamp-aware sync, and RPI workflow orchestration.
+
+**Tech Stack:** Node.js, TypeScript, SQLite, Handlebars, Commander.js, Inquirer, Vitest
+
+---
+
+## Executive Summary
+
+This enhancement transforms k0ntext's **AI session interface** (`.claude/` folder) into a cohesive context engineering platform. The system will:
+
+1. **Add `.claude/commands/`** - Slash commands for AI to invoke during coding sessions
+2. **Enhance `.claude/agents/`** - New agents for cleanup, sync, optimization
+3. **Synchronize context files** - claude.md ↔ ai_context.md stay in sync automatically
+4. **TodoList tracking** - Session tasks survive compactions
+5. **Index-aware operations** - All agents/commands aware of indexes folder
+6. **Timestamp-aware cleanup** - Interactive file management with snapshots
+
+---
+
+## Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                    AI Coding Session Interface (.claude/)                    │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                              │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │                    Commands Layer (/command-name)                 │    │
+│  │  /context-opt     /context-sync     /snapshot:create               │    │
+│  │  /cleanup:scan   /cleanup:interactive /todo:create               │    │
+│  │  /dispatch-rpi    /context:status   /workflow:route              │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│                                    │                                         │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │                     Agents Layer (@agent-name)                    │    │
+│  │  @context-optimizer  @cleanup-agent    @sync-agent                  │    │
+│  │  @todo-manager      @snapshot-manager  @workflow-router               │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│                                    │                                         │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │                   Core Services Layer                              │    │
+│  │  TodoList Manager    Timestamp Tracker    Context Generator          │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│                                    │                                         │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │                      Data & Context Layer                         │    │
+│  │  .claude/context/    .claude/indexes/    .claude/plans/            │    │
+│  │  claude.md            ai_context.md       CLAUDE.md                  │    │
+│  │  SQLite DB           File System         Git History                 │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│                                                                              │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Phase 1: Foundation (TodoList & Timestamp Tracking)
+
+**Objective:** Build core services that agents and commands will depend on
+
+### New Files to Create
+
+**1.1 `.claude/commands/todo-create.md`**
+```yaml
+---
+name: todo-create
+version: "1.0.0"
+displayName: "Todo Create"
+description: "Create a new todo list for current session with optional tasks"
+category: "session-management"
+arguments:
+  - name: "tasks"
+    description: "Optional comma-separated task descriptions"
+    required: false
+  - name: "--session <name>"
+    description: "Session name for grouping"
+    required: false
+examples:
+  - invocation: '/todo-create "Review PR #123"'
+    description: "Create todo list for PR review"
+  - invocation: '/todo-create "Refactor context system" --session v3.8.0'
+    description: "Create named session todo list"
+---
+```
+
+**1.2 `.claude/commands/todo-status.md`**
+```yaml
+---
+name: todo-status
+version: "1.0.0"
+displayName: "Todo Status"
+description: "Show current session todo list with task statuses"
+category: "session-management"
+arguments:
+  - name: "--session <name>"
+    description: "Show specific session todo"
+    required: false
+  - name: "--format <type>"
+    description: "Output format (table|json|markdown)"
+    required: false
+examples:
+  - invocation: '/todo-status'
+    description: "Show current session todos"
+---
+```
+
+**1.3 `.claude/agents/todo-manager.md`**
+```markdown
+---
+name: todo-manager
+version: "1.0.0"
+displayName: "Todo Manager"
+description: "Agent for managing session todo lists that survive compactions"
+category: "session-management"
+complexity: "low"
+context_budget: "~5K tokens"
+capabilities:
+  - "todo-list-creation"
+  - "task-tracking"
+  - "session-persistence"
+  - "compaction-survival"
+workflows:
+  - "session-management"
+commands: ["/todo-create", "/todo-status", "/todo-update"]
+examples:
+  - invocation: '@todo-manager "Create todo list for implementing snapshot system"'
+    description: "Generate structured todo list"
+  - invocation: '@todo-manager "Update todo: mark task 3 as complete"'
+    description: "Update specific task status"
+---
+```
+
+**1.4 `src/agent-system/todolist-manager.ts`**
+```typescript
+// Backend service for todo lists
+export class TodoListManager {
+  private db: DatabaseClient;
+
+  async createList(sessionId: string, tasks: Task[]): Promise<TodoList>;
+  async updateTask(sessionId: string, taskId: string, status: TaskStatus): Promise<void>;
+  async getList(sessionId: string): Promise<TodoList>;
+  async exportMarkdown(sessionId: string): Promise<string>;
+  async importFromMarkdown(content: string): Promise<TodoList>;
+  async archiveSession(sessionId: string): Promise<void>;
+}
+```
+
+**1.5 `src/agent-system/timestamp-tracker.ts`**
+```typescript
+// Track file timestamps for sync operations
+export class TimestampTracker {
+  async recordSnapshot(path: string): Promise<FileTimestamp>;
+  async getChangedFiles(since: Date): Promise<ChangedFile[]>;
+  async compareTimestamps(file1: string, file2: string): Promise<TimestampDiff>;
+  async syncTimestampsFromGit(): Promise<void>;
+}
+```
+
+### Files to Modify
+
+**1.6 `src/db/schema.ts`** - Add new tables (after line 200)
+
+```sql
+-- Schema version update
+SCHEMA_VERSION = '1.6.0'
+
+-- Add to existing schema:
+CREATE TABLE IF NOT EXISTS todo_sessions (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  parent_session TEXT,  -- For linking related sessions
+  metadata JSON
+);
+
+CREATE TABLE IF NOT EXISTS todo_tasks (
+  id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL,
+  subject TEXT NOT NULL,
+  description TEXT,
+  status TEXT NOT NULL DEFAULT 'pending',
+  dependencies TEXT,  -- JSON array of task IDs
+  assigned_to TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  completed_at TEXT,
+  FOREIGN KEY (session_id) REFERENCES todo_sessions(id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS file_timestamps (
+  path TEXT PRIMARY KEY,
+  modified_time TEXT NOT NULL,
+  size INTEGER NOT NULL,
+  hash TEXT NOT NULL,
+  last_checked TEXT NOT NULL DEFAULT (datetime('now')),
+  git_commit TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_todo_sessions_created ON todo_sessions(created_at);
+CREATE INDEX IF NOT EXISTS idx_todo_tasks_session ON todo_tasks(session_id);
+CREATE INDEX IF NOT EXISTS idx_todo_tasks_status ON todo_tasks(status);
+CREATE INDEX IF NOT EXISTS idx_file_timestamps_checked ON file_timestamps(last_checked);
+```
+
+**1.7 `src/db/client.ts`** - Add database methods (after line 700)
+
+```typescript
+// TodoList operations
+public createTodoSession(name: string, metadata?: Record<string, unknown>): Promise<string>;
+public createTodoTask(sessionId: string, task: Task): Promise<string>;
+public updateTodoTask(taskId: string, updates: Partial<Task>): Promise<void>;
+public getTodoSession(sessionId: string): Promise<TodoSession>;
+public getCurrentTodoSession(): Promise<TodoSession | null>;
+public getTodoTasks(sessionId: string): Promise<Task[]>;
+public getPendingTodos(sessionId: string): Promise<Task[]>;
+
+// Timestamp operations
+public recordTimestamp(path: string): Promise<void>;
+public batchRecordTimestamps(paths: string[]): Promise<void>;
+public getChangedFiles(since: Date): Promise<string[]>;
+public getFileTimestamp(path: string): Promise<FileTimestamp | null>;
+public syncTimestampsFromGit(): Promise<void>;
+```
+
+**1.8 `tests/agent-system/todolist-manager.test.ts`** - Test file
+
+**1.9 `tests/agent-system/timestamp-tracker.test.ts`** - Test file
+
+---
+
+## Phase 2: Context File Commands & Agents
+
+**Objective:** Dedicated commands and agents for claude.md and ai_context.md with fixed structure and auto-sync
+
+### New Files to Create
+
+**2.1 `.claude/commands/context-opt.md`**
+```yaml
+---
+name: context-opt
+version: "1.0.0"
+displayName: "Context Optimize"
+description: "Analyze and optimize context files (claude.md, ai_context.md)"
+category: "context-management"
+arguments:
+  - name: "--analyze"
+    description: "Analyze current context state without changes"
+    action: "store_true"
+  - name: "--generate"
+    description: "Regenerate context files from database"
+    action: "store_true"
+  - name: "--sync"
+    description: "Sync claude.md and ai_context.md"
+    action: "store_true"
+  - name: "--workflow <name>"
+    description: "Optimize for specific workflow"
+    required: false
+examples:
+  - invocation: '/context-opt --analyze'
+    description: "Check context health"
+  - invocation: '/context-opt --generate --sync'
+    description: "Regenerate and sync both context files"
+---
+```
+
+**2.2 `.claude/commands/context-sync.md`**
+```yaml
+---
+name: context-sync
+version: "1.0.0"
+displayName: "Context Sync"
+description: "Bidirectional sync between claude.md and ai_context.md"
+category: "context-management"
+arguments:
+  - name: "--to <target>"
+    description: "Sync target: claude|ai|both"
+    required: false
+  - name: "--force"
+    description: "Sync even with conflicts"
+    action: "store_true"
+  - name: "--resolve <strategy>"
+    description: "Conflict resolution: newer|older|merge"
+    required: false
+examples:
+  - invocation: '/context-sync --to both'
+    description: "Sync both context files"
+---
+```
+
+**2.3 `.claude/commands/context-status.md`**
+```yaml
+---
+name: context-status
+version: "1.0.0"
+displayName: "Context Status"
+description: "Check sync status between claude.md and ai_context.md"
+category: "context-management"
+arguments:
+  - name: "--detailed"
+    description: "Show detailed diff"
+    action: "store_true"
+  - name: "--json"
+    description: "Output as JSON"
+    action: "store_true"
+examples:
+  - invocation: '/context-status'
+    description: "Check if context files are in sync"
+---
+```
+
+**2.4 `.claude/commands/context-diff.md`**
+```yaml
+---
+name: context-diff
+version: "1.0.0"
+displayName: "Context Diff"
+description: "Show differences between context files"
+category: "context-management"
+arguments:
+  - name: "--json"
+    description: "Output as JSON"
+    action: "store_true"
+examples:
+  - invocation: '/context-diff'
+    description: "Show unified diff of context files"
+---
+```
+
+**2.5 `.claude/agents/context-optimizer.md`**
+```markdown
+---
+name: context-optimizer
+version: "1.0.0"
+displayName: "Context Optimizer"
+description: "Agent for analyzing and optimizing context files with index-awareness"
+category: "context-management"
+complexity: "medium"
+context_budget: "~15K tokens"
+capabilities:
+  - "context-analysis"
+  - "redundancy-detection"
+  - "index-awareness"
+  - "recent-changes-detection"
+  - "optimization-recommendations"
+workflows:
+  - "context-management"
+  - "documentation-optimization"
+commands: ["/context-opt", "/context-sync", "/context-status"]
+examples:
+  - invocation: '@context-optimizer "Analyze and optimize current context"'
+    description: "Full context analysis and optimization"
+  - invocation: '@context-optimizer "Sync context files and resolve conflicts"'
+    description: "Bidirectional sync with conflict resolution"
+---
+```
+
+**2.6 `.claude/agents/context-sync-agent.md`**
+```markdown
+---
+name: context-sync-agent
+version: "1.0.0"
+displayName: "Context Sync Agent"
+description: "Specialized agent for bidirectional sync between claude.md and ai_context.md"
+category: "context-management"
+complexity: "medium"
+context_budget: "~10K tokens"
+capabilities:
+  - "bidirectional-sync"
+  - "conflict-detection"
+  - "timestamp-awareness"
+  - "merge-resolution"
+  - "backup-creation"
+workflows:
+  - "context-management"
+  - "synchronization"
+commands: ["/context-sync", "/context-diff", "/context-status"]
+examples:
+  - invocation: '@context-sync-agent "Sync all context files"'
+    description: "Full bidirectional sync"
+  - invocation: '@context-sync-agent "Resolve conflicts in context files"'
+    description: "Detect and merge divergent changes"
+---
+```
+
+**2.7 `src/context/generator.ts`**
+```typescript
+// Generate context files from database + indexes
+export class ContextGenerator {
+  constructor(private db: DatabaseClient, private projectRoot: string) {}
+
+  async generateClaudeMD(): Promise<string>;
+  async generateAIContextMD(): Promise<string>;
+  async getIndexBasedContext(workflow?: string): Promise<ContextData>;
+  async getRecentChanges(since?: Date): Promise<RecentChanges>;
+  private generateQuickReference(data: ContextData): string;
+  private generateRecentChanges(since?: Date): Promise<string>;
+  private generateIndexBasedLookup(data: ContextData): Promise<string>;
+}
+```
+
+**2.8 `src/context/sync-manager.ts`**
+```typescript
+// Bidirectional sync between claude.md and ai_context.md
+export class ContextSyncManager {
+  constructor(
+    private db: DatabaseClient,
+    private projectRoot: string,
+    private timestampTracker: TimestampTracker
+  ) {}
+
+  async syncToAIContext(): Promise<SyncResult>;
+  async syncToClaudeMD(): Promise<SyncResult>;
+  async syncBoth(): Promise<SyncResult>;
+  async detectDivergence(): Promise<DivergenceReport>;
+  async resolveConflict(strategy: ConflictStrategy): Promise<void>;
+  async createBackup(): Promise<string>;
+}
+```
+
+**2.9 `src/context/types.ts`**
+```typescript
+export interface ContextData {
+  project: ProjectInfo;
+  techStack: TechStackInfo;
+  architecture: ArchitectureInfo;
+  workflows: WorkflowInfo[];
+  commands: CommandInfo[];
+  recentChanges: RecentChanges;
+  indexes: IndexInfo;
+}
+
+export interface RecentChanges {
+  commits: CommitInfo[];
+  uncommitted: FileChange[];
+  lastSync: Date;
+}
+
+export interface SyncResult {
+  success: boolean;
+  filesChanged: string[];
+  conflicts: Conflict[];
+  backupCreated?: string;
+}
+```
+
+**2.10 `src/context/template.ts`** - Handlebars template for context files
+
+**2.11 `tests/context/generator.test.ts`** - Test file
+
+**2.12 `tests/context/sync-manager.test.ts`** - Test file
+
+---
+
+## Phase 3: Snapshots & Cleanup Commands
+
+**Objective:** Timestamp-aware snapshot system with interactive cleanup agent
+
+### New Files to Create
+
+**3.1 `.claude/commands/snapshot-create.md`**
+```yaml
+---
+name: snapshot-create
+version: "1.0.0"
+displayName: "Snapshot Create"
+description: "Create a timestamped snapshot of context files and directories"
+category: "snapshot-management"
+arguments:
+  - name: "<name>"
+    description: "Snapshot name/description"
+    required: true
+  - name: "--paths <paths>"
+    description: "Paths to include (comma-separated, defaults: .claude/ context/)"
+    required: false
+  - name: "--tag <tags>"
+    description: "Tags to add (comma-separated)"
+    required: false
+examples:
+  - invocation: '/snapshot-create "Before refactoring"'
+    description: "Create snapshot before major work"
+  - invocation: '/snapshot-create "Weekly backup" --tag weekly,manual'
+    description: "Create tagged snapshot"
+---
+```
+
+**3.2 `.claude/commands/snapshot-restore.md`**
+```yaml
+---
+name: snapshot-restore
+version: "1.0.0"
+displayName: "Snapshot Restore"
+description: "Restore context files and directories from a snapshot"
+category: "snapshot-management"
+arguments:
+  - name: "<id>"
+    description: "Snapshot ID, name, or partial match"
+    required: true
+  - name: "--dry-run"
+    description: "Show what would be restored"
+    action: "store_true"
+  - name: "--paths <paths>"
+    description: "Only restore specific paths"
+    required: false
+examples:
+  - invocation: '/snapshot-restore "Before refactoring"'
+    description: "Restore by name"
+  - invocation: '/snapshot-restore snap-abc123 --dry-run'
+    description: "Preview restoration"
+---
+```
+
+**3.3 `.claude/commands/snapshot-list.md`**
+```yaml
+---
+name: snapshot-list
+version: "1.0.0"
+displayName: "Snapshot List"
+description: "List all available snapshots with filtering options"
+category: "snapshot-management"
+arguments:
+  - name: "--tag <tag>"
+    description: "Filter by tag"
+    required: false
+  - name: "--since <date>"
+    description: "Filter snapshots created after date"
+    required: false
+  - name: "--limit <n>"
+    description: "Limit results"
+    required: false
+  - name: "--json"
+    description: "Output as JSON"
+    action: "store_true"
+examples:
+  - invocation: '/snapshot-list --tag weekly --limit 5'
+    description: "List recent weekly snapshots"
+---
+```
+
+**3.4 `.claude/commands/snapshot-diff.md`**
+```yaml
+---
+name: snapshot-diff
+version: "1.0.0"
+displayName: "Snapshot Diff"
+description: "Compare two snapshots to see changes"
+category: "snapshot-management"
+arguments:
+  - name: "<id1>"
+    description: "First snapshot"
+    required: true
+  - name: "<id2>"
+    description: "Second snapshot"
+    required: true
+examples:
+  - invocation: '/snapshot-diff "Before" "After"'
+    description: "Compare by name match"
+---
+```
+
+**3.5 `.claude/commands/cleanup-scan.md`**
+```yaml
+---
+name: cleanup-scan
+version: "1.0.0"
+displayName: "Cleanup Scan"
+description: "Scan for files that can be cleaned up (snapshots, docs, contexts)"
+category: "maintenance"
+arguments:
+  - name: "--area <name>"
+    description: "Focus on: snapshots|docs|contexts|all"
+    required: false
+  - name: "--older-than <days>"
+    description: "Only show items older than N days"
+    required: false
+  - name: "--larger-than <mb>"
+    description: "Only show items larger than N MB"
+    required: false
+examples:
+  - invocation: '/cleanup-scan --area snapshots --older-than 30'
+    description: "Find old snapshots to clean"
+---
+```
+
+**3.6 `.claude/commands/cleanup-interactive.md`**
+```yaml
+---
+name: cleanup-interactive
+version: "1.0.0"
+displayName: "Cleanup Interactive"
+description: "Interactive cleanup with prompts and snapshot backup"
+category: "maintenance"
+arguments:
+  - name: "--snapshot-before"
+    description: "Create snapshot before cleanup"
+    action: "store_true"
+  - name: "--yes"
+    description: "Auto-confirm all prompts"
+    action: "store_true"
+examples:
+  - invocation: '/cleanup-interactive --snapshot-before'
+    description: "Interactive cleanup with backup"
+---
+```
+
+**3.7 `.claude/agents/snapshot-manager.md`**
+```markdown
+---
+name: snapshot-manager
+version: "1.0.0"
+displayName: "Snapshot Manager"
+description: "Agent for managing context file snapshots with timestamp awareness"
+category: "snapshot-management"
+complexity: "medium"
+context_budget: "~10K tokens"
+capabilities:
+  - "snapshot-creation"
+  - "snapshot-restoration"
+  - "snapshot-comparison"
+  - "retention-policy"
+  - "diff-generation"
+workflows:
+  - "snapshot-management"
+  - "backup-restore"
+commands: ["/snapshot-create", "/snapshot-restore", "/snapshot-list", "/snapshot-diff"]
+examples:
+  - invocation: '@snapshot-manager "Create snapshot before major refactoring"'
+    description: "Snapshot current state"
+  - invocation: '@snapshot-manager "Compare current state with last week"'
+    description: "Diff snapshots for change analysis"
+---
+```
+
+**3.8 `.claude/agents/cleanup-agent.md`**
+```markdown
+---
+name: cleanup-agent
+version: "1.0.0"
+displayName: "Cleanup Agent"
+description: "Interactive cleanup agent for snapshots, docs, and contexts with timestamp awareness"
+category: "maintenance"
+complexity: "medium"
+context_budget: "~15K tokens"
+capabilities:
+  - "timestamp-aware-scanning"
+  - "interactive-prompts"
+  - "snapshot-backup"
+  - "retention-policy"
+  - "size-analysis"
+  - "orphaned-file-detection"
+workflows:
+  - "maintenance"
+  - "cleanup"
+commands: ["/cleanup-scan", "/cleanup-interactive"]
+examples:
+  - invocation: '@cleanup-agent "Scan and clean old snapshots"'
+    description: "Find and remove old snapshots"
+  - invocation: '@cleanup-agent "Clean up orphaned docs with backup"'
+    description: "Interactive docs cleanup with safety"
+---
+```
+
+**3.9 `src/snapshots/manager.ts`**
+```typescript
+export class SnapshotManager {
+  constructor(private db: DatabaseClient, private projectRoot: string) {}
+
+  async createSnapshot(name: string, options: SnapshotOptions): Promise<Snapshot>;
+  async restoreSnapshot(id: string, options: RestoreOptions): Promise<RestoreResult>;
+  async listSnapshots(filter?: SnapshotFilter): Promise<Snapshot[]>;
+  async diffSnapshots(id1: string, id2: string): Promise<SnapshotDiff>;
+  async deleteSnapshot(id: string): Promise<void>;
+  async autoCleanup(policy: RetentionPolicy): Promise<CleanupResult>;
+  async getSnapshotSize(id: string): Promise<number>;
+}
+```
+
+**3.10 `tests/snapshots/manager.test.ts`** - Test file
+
+**3.11 `tests/cleanup/agent.test.ts`** - Test file
+
+---
+
+## Phase 4: Cross-Tool Sync Agent
+
+**Objective:** Sync context to all AI tools with conflict resolution
+
+### New Files to Create
+
+**4.1 `.claude/commands/cross-tool-sync.md`**
+```yaml
+---
+name: cross-tool-sync
+version: "1.0.0"
+displayName: "Cross-Tool Sync"
+description: "Synchronize context changes to all AI tool configs (Copilot, Cursor, Cline, etc.)"
+category: "synchronization"
+arguments:
+  - name: "--to <tools>"
+    description: "Target tools: copilot,cursor,cline,windsurf,aider,continue,gemini"
+    required: false
+  - name: "--from <source>"
+    description: "Source: claude|ai|both"
+    required: false
+  - name: "--check"
+    description: "Only check for conflicts, don't sync"
+    action: "store_true"
+examples:
+  - invocation: '/cross-tool-sync --to copilot,cursor'
+    description: "Sync to specific tools"
+---
+```
+
+**4.2 `.claude/agents/cross-tool-sync-agent.md`**
+```markdown
+---
+name: cross-tool-sync-agent
+version: "1.0.0"
+displayName: "Cross-Tool Sync Agent"
+description: "Propagate context changes to all AI tool configurations with conflict resolution"
+category: "synchronization"
+complexity: "high"
+context_budget: "~20K tokens"
+capabilities:
+  - "multi-tool-sync"
+  - "adapter-management"
+  - "conflict-resolution"
+  - "tool-config-detection"
+  - "backup-creation"
+workflows:
+  - "synchronization"
+  - "cross-tool-management"
+commands: ["/cross-tool-sync"]
+examples:
+  - invocation: '@cross-tool-sync-agent "Sync latest context to all tools"'
+    description: "Full cross-tool synchronization"
+  - invocation: '@cross-tool-sync-agent "Check and resolve cross-tool conflicts"'
+    description: "Conflict detection and resolution"
+---
+```
+
+**4.3 `src/sync/cross-tool-engine.ts`**
+```typescript
+// Bidirectional sync across all AI tools
+export class CrossToolSyncEngine {
+  private adapters: Map<string, ContextAdapter>;
+
+  registerAdapter(tool: string, adapter: ContextAdapter): void;
+  async syncTo(targets: string[]): Promise<SyncResult[]>;
+  async detectConflicts(): Promise<ConflictInfo[]>;
+  async resolveConflicts(resolutions: ConflictResolution[]): Promise<void>;
+}
+
+export interface ContextAdapter {
+  toolName: string;
+  configPaths: string[];
+  readContext(): Promise<string>;
+  writeContext(content: string): Promise<void>;
+  detectCustomChanges(): Promise<Change[]>;
+}
+```
+
+**4.4 `src/sync/adapters/claude-code.ts`** - Claude Code adapter
+
+**4.5 `src/sync/adapters/copilot.ts`** - GitHub Copilot adapter
+
+**4.6 `src/sync/adapters/cursor.ts`** - Cursor adapter
+
+**4.7 `src/sync/adapters/cline.ts`** - Cline adapter
+
+**4.8 `src/sync/adapters/windsurf.ts`** - Windsurf adapter
+
+**4.9 `src/sync/adapters/aider.ts`** - Aider adapter
+
+**4.10 `src/sync/adapters/gemini.ts`** - Gemini adapter
+
+**4.11 `src/sync/conflict-resolver.ts`**
+```typescript
+export class ConflictResolver {
+  async resolve(conflict: ConflictInfo, strategy: ResolveStrategy): Promise<ResolvedContent>;
+  async merge(contents: string[], strategies: MergeStrategy[]): Promise<string>;
+}
+```
+
+**4.12 `tests/sync/cross-tool-engine.test.ts`** - Test file
+
+---
+
+## Phase 5: Integration & RPI Dispatch
+
+**Objective:** Auto-invocation hooks and parallel RPI agent dispatcher
+
+### New Files to Create
+
+**5.1 `.claude/commands/dispatch-rpi.md`**
+```yaml
+---
+name: dispatch-rpi
+version: "1.0.0"
+displayName: "Dispatch RPI"
+description: "Dispatch up to 6 parallel RPI workflow agents (research/plan/implement)"
+category: "agent-orchestration"
+arguments:
+  - name: "--workflow <name>"
+    description: "RPI workflow to execute"
+    required: true
+  - name: "--parallel <n>"
+    description: "Number of parallel agents (1-6, default: 6)"
+    required: false
+  - name: "--tasks <tasks>"
+    description: "Comma-separated task descriptions"
+    required: false
+examples:
+  - invocation: '/dispatch-rpi --workflow context-engineering --parallel 6'
+    description: "Full parallel RPI workflow"
+  - invocation: '/dispatch-rpi --workflow cleanup --parallel 3'
+    description: "Focused parallel dispatch"
+---
+```
+
+**5.2 `.claude/commands/workflow-route.md`**
+```yaml
+---
+name: workflow-route
+version: "1.0.0"
+displayName: "Workflow Route"
+description: "Route commands based on workflow context with automatic file detection"
+category: "navigation"
+arguments:
+  - name: "<file>"
+    description: "File path to detect workflow for"
+    required: true
+  - name: "--list"
+    description: "List all workflow mappings"
+    action: "store_true"
+examples:
+  - invocation: '/workflow-route src/db/schema.ts'
+    description: "Detect workflow and show relevant commands"
+  - invocation: '/workflow-route --list'
+    description: "Show all workflow-to-command mappings"
+---
+```
+
+**5.3 `.claude/agents/rpi-dispatcher.md`**
+```markdown
+---
+name: rpi-dispatcher
+version: "1.0.0"
+displayName: "RPI Dispatcher"
+description: "Dispatch up to 6 parallel RPI workflow agents with consolidated results"
+category: "agent-orchestration"
+complexity: "high"
+context_budget: "~25K tokens"
+capabilities:
+  - "parallel-execution"
+  - "result-consolidation"
+  - "todolist-integration"
+  - "workflow-routing"
+  - "session-management"
+workflows:
+  - "rpi-workflow"
+  - "parallel-execution"
+commands: ["/dispatch-rpi", "/workflow-route"]
+examples:
+  - invocation: '@rpi-dispatcher "Research and plan context sync system"'
+    description: "Parallel research and planning"
+  - invocation: '@rpi-dispatcher "Full RPI cycle: research→plan→implement"'
+    description: "Complete RPI workflow with 6 parallel agents"
+---
+```
+
+**5.4 `.claude/agents/workflow-router.md`**
+```markdown
+---
+name: workflow-router
+version: "1.0.0"
+displayName: "Workflow Router"
+description: "Route commands based on workflow context and index awareness"
+category: "navigation"
+complexity: "medium"
+context_budget: "~8K tokens"
+capabilities:
+  - "workflow-detection"
+  - "index-awareness"
+  - "command-routing"
+  - "file-categorization"
+workflows:
+  - "navigation"
+  - "context-lookup"
+commands: ["/workflow-route"]
+examples:
+  - invocation: '@workflow-router "What workflow handles database schema?"'
+    description: "Route question to correct workflow"
+  - invocation: '@workflow-router "Show me all workflow commands"'
+    description: "Display workflow-command mappings"
+---
+```
+
+**5.5 `src/agent-system/dispatcher.ts`**
+```typescript
+// Parallel agent dispatcher (up to 6 concurrent)
+export class AgentDispatcher {
+  private maxConcurrent: number = 6;
+  private activeAgents: Map<string, Agent>;
+
+  async dispatch(agents: AgentConfig[]): Promise<AgentResult[]>;
+  async dispatchRPI(workflow: string, options: RPIOptions): Promise<RPIResult>;
+  private createTodoList(workflow: string, tasks: string[]): Promise<string>;
+  private consolidateResults(results: AgentResult[]): Promise<ConsolidatedResult>;
+}
+```
+
+**5.6 `src/integration/workflow-router.ts`**
+```typescript
+// Route commands based on workflow context
+export class WorkflowRouter {
+  async detectWorkflow(filePath: string): Promise<string>;
+  async routeCommand(command: string, context: WorkflowContext): Promise<RouteResult>;
+  async getWorkflowCommands(workflow: string): Promise<string[]>;
+  async listAllWorkflows(): Promise<WorkflowMapping[]>;
+}
+```
+
+**5.7 `tests/agent-system/dispatcher.test.ts`** - Test file
+
+**5.8 `tests/integration/workflow-router.test.ts`** - Test file
+
+---
+
+## Database Migration
+
+**File:** `src/db/migrations/0016_add_context_system_tables.sql`
+
+```sql
+-- Migration 0016: Context System and TodoList Support
+-- From: 1.5.0
+-- To: 1.6.0
+
+-- Todo sessions (for tracking across compactions)
+CREATE TABLE IF NOT EXISTS todo_sessions (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  parent_session TEXT,
+  metadata JSON
+);
+
+-- Todo tasks
+CREATE TABLE IF NOT EXISTS todo_tasks (
+  id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL,
+  subject TEXT NOT NULL,
+  description TEXT,
+  status TEXT NOT NULL DEFAULT 'pending',
+  dependencies TEXT,
+  assigned_to TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  completed_at TEXT,
+  FOREIGN KEY (session_id) REFERENCES todo_sessions(id) ON DELETE CASCADE
+);
+
+-- Snapshots for context files
+CREATE TABLE IF NOT EXISTS snapshots (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  file_hashes TEXT NOT NULL,
+  metadata JSON,
+  tags TEXT
+);
+
+-- File timestamps for sync tracking
+CREATE TABLE IF NOT EXISTS file_timestamps (
+  path TEXT PRIMARY KEY,
+  modified_time TEXT NOT NULL,
+  size INTEGER NOT NULL,
+  hash TEXT NOT NULL,
+  last_checked TEXT NOT NULL DEFAULT (datetime('now')),
+  git_commit TEXT
+);
+
+-- Cross-tool sync state
+CREATE TABLE IF NOT EXISTS cross_tool_sync_state (
+  tool TEXT PRIMARY KEY,
+  context_path TEXT NOT NULL,
+  last_synced TEXT,
+  last_hash TEXT,
+  last_sync_status TEXT,
+  sync_count INTEGER DEFAULT 0,
+  conflict_count INTEGER DEFAULT 0
+);
+
+-- Indexes
+CREATE INDEX IF NOT EXISTS idx_snapshots_created ON snapshots(created_at);
+CREATE INDEX IF NOT EXISTS idx_snapshots_tags ON snapshots(tags);
+CREATE INDEX IF NOT EXISTS idx_todo_sessions_created ON todo_sessions(created_at);
+CREATE INDEX IF NOT EXISTS idx_todo_tasks_session ON todo_tasks(session_id);
+CREATE INDEX IF NOT EXISTS idx_todo_tasks_status ON todo_tasks(status);
+CREATE INDEX IF NOT EXISTS idx_file_timestamps_checked ON file_timestamps(last_checked);
+```
+
+---
+
+## Fixed Structure for claude.md / ai_context.md
+
+Both files will follow this template structure:
+
+```markdown
+# {Project Name} - AI Context
+
+> **Generated by k0ntext v{version}**
+> **Last Updated:** {timestamp}
+> **Sync Status:** {sync_status}
+
+---
+
+## Quick Reference
+
+**Platform:** {platform_description}
+**Tech Stack:** {primary_technologies}
+**Repository:** {repo_url}
+**Status:** {status}
+
+---
+
+## Essential Commands
+
+{commands_table}
+
+---
+
+## Project Identity
+
+{project_details}
+
+---
+
+## Recent Changes
+
+> **Auto-generated from git commits and uncommitted changes**
+
+### Latest Commits (Last 7)
+
+{recent_commits}
+
+### Uncommitted Changes
+
+{uncommitted_changes}
+
+---
+
+## Architecture
+
+{architecture_overview}
+
+---
+
+## Index-Based Context Lookup
+
+### Workflows ({workflow_count})
+
+{workflow_index}
+
+### Code Domains ({code_domain_count})
+
+{code_index}
+
+### Agents ({agent_count})
+
+{agent_index}
+
+### Commands ({command_count})
+
+{command_index}
+
+---
+
+## Key Files by Workflow
+
+{workflow_file_mapping}
+
+---
+
+## Gotchas & Patterns
+
+{gotchas}
+
+---
+
+## Sync Metadata
+
+```json
+{
+  "generated_at": "{timestamp}",
+  "k0ntext_version": "{version}",
+  "claude_hash": "{hash}",
+  "ai_context_hash": "{hash}",
+  "last_commit": "{commit_sha}",
+  "synced_tools": ["claude", "copilot", "cursor"]
+}
+```
+```
+
+---
+
+## User Interaction Flows
+
+### Flow 1: Context Optimization
+
+```
+User: /context-opt --analyze
+       |
+       v
+[Scanning context files...]
+       |
+       v
+[Context Analysis Report]
+┌─────────────────────────────────────┐
+│ Current Size: 85,234 tokens (42%)   │
+│ Status: ⚠ Needs optimization        │
+│                                     │
+│ Issues Found:                       │
+│ • Redundant sections (3)            │
+│ • Outdated workflows (2)            │
+│ • Missing recent changes (12)       │
+└─────────────────────────────────────┘
+       |
+       v
+? Apply optimizations? (Y/n)
+       |
+       +--Yes--> [Generating and syncing...]
+```
+
+### Flow 2: TodoList During Session
+
+```
+User: /todo-create "Implement snapshot system"
+       |
+       v
+[✓ Todo session created: sess-abc123]
+[ ] Research snapshot requirements
+[ ] Design snapshot schema
+[ ] Implement snapshot manager
+[ ] Create snapshot commands
+[ ] Write tests
+       |
+       v
+[Session continues...]
+[User completes tasks, compaction happens]
+       |
+       v
+User: /todo-status
+       |
+       v
+[Current Todo Session: sess-abc123]
+[X] Research snapshot requirements ✓
+[X] Design snapshot schema ✓
+[ ] Implement snapshot manager
+[ ] Create snapshot commands
+[ ] Write tests
+       |
+       v
+[Session continues from where it left off]
+```
+
+### Flow 3: Parallel RPI Dispatch
+
+```
+User: /dispatch-rpi --workflow context-engineering --parallel 6
+       |
+       v
+[Initializing RPI workflow: context-engineering]
+       |
+       v
+[Dispatching 6 parallel agents...]
+
+Agent 1: @researcher (exploring/.claude/indexes)
+Agent 2: @architect (analyzing workflows)
+Agent 3: @database-ops (checking schema)
+Agent 4: @integration-hub (examining MCP)
+Agent 5: @context-optimizer (auditing context files)
+Agent 6: @workflow-router (mapping commands)
+
+       |
+       v
+[Creating TodoList for session: rpi-xyz]
+┌────────────────────────────────────────────┐
+│ [ ] Research current architecture          │
+│ [ ] Design enhanced system                 │
+│ [ ] Plan database changes                  │
+│ [ ] Implement agent dispatcher             │
+│ [ ] Test snapshot system                   │
+│ [ ] Update context sync                   │
+│ [ ] Verify cross-tool integration            │
+└────────────────────────────────────────────┘
+       |
+       v
+[All agents running in parallel...]
+       |
+       v
+Agent 1: ✓ Found 15 workflow files
+Agent 2: ✓ Identified 3 integration points
+Agent 3: ✓ Schema v1.6.0 ready
+Agent 4: ✓ 5 MCP tools to add
+Agent 5: ✓ 2 context files diverged
+Agent 6: ✓ 23 workflow-command mappings
+       |
+       v
+[Consolidating results...]
+       |
+       v
+[TodoList updated: 6/8 tasks completed]
+```
+
+---
+
+## Verification Steps
+
+### Manual Testing
+
+1. **TodoList System:**
+   ```bash
+   # In AI session, invoke command
+   /todo-create "Test session"
+
+   # Check status
+   /todo-status
+
+   # Verify compaction survival
+   # (Trigger compaction, then run /todo-status again)
+   ```
+
+2. **Context Files:**
+   ```bash
+   # In AI session
+   /context-opt --analyze
+   /context-sync --to both
+   /context-status --detailed
+   ```
+
+3. **Snapshots:**
+   ```bash
+   /snapshot-create "Test snapshot"
+   /snapshot-list
+   /snapshot-restore <id>
+   ```
+
+4. **Cross-Tool Sync:**
+   ```bash
+   /cross-tool-sync --to copilot,cursor
+   ```
+
+5. **Parallel Dispatch:**
+   ```bash
+   /dispatch-rpi --workflow test --parallel 3
+   ```
+
+### Automated Tests
+
+```bash
+npm test                           # Run all tests
+npm test -- agent-system          # Test agent system
+npm test -- context               # Test context management
+npm test -- snapshots             # Test snapshot system
+npm test -- sync                  # Test cross-tool sync
+```
+
+---
+
+## Rollback Plan
+
+If issues arise:
+
+1. **Per-phase rollback:** Git revert specific commits
+2. **Database fallback:** Migration can be reversed
+3. **Feature flags:** Add `K0NTEXT_EXPERIMENTAL_*` env vars
+
+---
+
+## Implementation Order
+
+### Week 1: Foundation
+- Day 1-2: TodoList manager, timestamp tracker
+- Day 3-4: Database schema v1.6.0 and migration
+- Day 5: Core service tests
+
+### Week 2: Context System
+- Day 1-2: Context generator, sync manager, types
+- Day 3-4: Commands and agents (context:opt, sync, status, diff)
+- Day 5: Testing and integration
+
+### Week 3: Snapshots & Cleanup
+- Day 1-2: Snapshot manager service
+- Day 3-4: Commands and agents (snapshot:*, cleanup:*)
+- Day 5: Testing and documentation
+
+### Week 4: Cross-Tool Sync
+- Day 1-3: Sync engine, adapters, conflict resolver
+- Day 4-5: Commands, agents, and testing
+
+### Week 5: Integration
+- Day 1-2: Agent dispatcher, workflow router
+- Day 3-4: Commands and agents (dispatch-rpi, workflow-route)
+- Day 5: Final testing, MCP tools, documentation
+
+---
+
+## Estimation
+
+- **Phase 1 (Foundation):** 4-6 hours
+- **Phase 2 (Context System):** 6-8 hours
+- **Phase 3 (Snapshots & Cleanup):** 5-7 hours
+- **Phase 4 (Cross-Tool Sync):** 6-8 hours
+- **Phase 5 (Integration):** 5-7 hours
+
+**Total: 26-36 hours** for all five phases
+
+---
+
+## Files Summary by Phase
+
+### Phase 1: Foundation
+| Type | Files |
+|-------|--------|
+| Commands | `.claude/commands/todo-create.md`, `.claude/commands/todo-status.md` |
+| Agents | `.claude/agents/todo-manager.md` |
+| Services | `src/agent-system/todolist-manager.ts`, `src/agent-system/timestamp-tracker.ts` |
+| Tests | `tests/agent-system/todolist-manager.test.ts`, `tests/agent-system/timestamp-tracker.test.ts` |
+
+### Phase 2: Context System
+| Type | Files |
+|-------|--------|
+| Commands | `.claude/commands/context-opt.md`, `.claude/commands/context-sync.md`, `.claude/commands/context-status.md`, `.claude/commands/context-diff.md` |
+| Agents | `.claude/agents/context-optimizer.md`, `.claude/agents/context-sync-agent.md` |
+| Services | `src/context/generator.ts`, `src/context/sync-manager.ts`, `src/context/types.ts`, `src/context/template.ts` |
+| Tests | `tests/context/generator.test.ts`, `tests/context/sync-manager.test.ts` |
+
+### Phase 3: Snapshots & Cleanup
+| Type | Files |
+|-------|--------|
+| Commands | `.claude/commands/snapshot-create.md`, `.claude/commands/snapshot-restore.md`, `.claude/commands/snapshot-list.md`, `.claude/commands/snapshot-diff.md`, `.claude/commands/cleanup-scan.md`, `.claude/commands/cleanup-interactive.md` |
+| Agents | `.claude/agents/snapshot-manager.md`, `.claude/agents/cleanup-agent.md` |
+| Services | `src/snapshots/manager.ts` |
+| Tests | `tests/snapshots/manager.test.ts`, `tests/cleanup/agent.test.ts` |
+
+### Phase 4: Cross-Tool Sync
+| Type | Files |
+|-------|--------|
+| Commands | `.claude/commands/cross-tool-sync.md` |
+| Agents | `.claude/agents/cross-tool-sync-agent.md` |
+| Services | `src/sync/cross-tool-engine.ts`, `src/sync/adapters/*.ts` (7 adapters), `src/sync/conflict-resolver.ts` |
+| Tests | `tests/sync/cross-tool-engine.test.ts` |
+
+### Phase 5: Integration
+| Type | Files |
+|-------|--------|
+| Commands | `.claude/commands/dispatch-rpi.md`, `.claude/commands/workflow-route.md` |
+| Agents | `.claude/agents/rpi-dispatcher.md`, `.claude/agents/workflow-router.md` |
+| Services | `src/agent-system/dispatcher.ts`, `src/integration/workflow-router.ts` |
+| Tests | `tests/agent-system/dispatcher.test.ts`, `tests/integration/workflow-router.test.ts` |
+
+---
+
+## Index & Context Folder Integration
+
+All agents and commands will be **index-aware**, meaning they:
+
+1. **Read from `.claude/indexes/`** to understand project structure
+2. **Reference `.claude/context/`** for project context data
+3. **Update indexes** when new workflows/agents/commands are added
+4. **Maintain cross-references** between related files
+5. **Use semantic RAG** when database is available for context lookup
+
+---
+
+## Sync Strategy: claude.md ↔ ai_context.md
+
+### Bidirectional Sync Rules:
+
+1. **Timestamp Awareness:** Track modification time and git commit for each file
+2. **Conflict Detection:** Compare hashes to detect divergence
+3. **Merge Strategy:** Offer options: newer, older, manual merge, both
+4. **Backup Before Sync:** Always create timestamped backup before overwriting
+5. **Sync Metadata:** JSON footer with sync status for verification
+
+### Git Hook Integration:
+
+- **pre-commit:** Check if claude.md or ai_context.md is staged → trigger sync
+- **post-commit:** Record sync state in database
+- **post-merge:** Run conflict resolution and auto-sync
+
+---
+
+**Next Steps:** User reviews plan, asks questions, requests approval → ExitPlanMode