cmp-standards 3.5.0 → 3.7.0

package/README.md

@@ -1,633 +1,399 @@
-# CMP - Collective Memory Protocol
-
-> **The Development Intelligence Layer** - Persistent memory, cross-project learning, and multi-agent collaboration for AI-assisted development.
-
-[![npm version](https://img.shields.io/npm/v/cmp-standards.svg)](https://www.npmjs.com/package/cmp-standards)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
----
-
-## Philosophy
-
-| Principle | Meaning |
-|-----------|---------|
-| **Evidence > Assumptions** | Never assume. Always verify. Read before writing. |
-| **Cloud > Local** | Memory lives in the cloud. Sessions are ephemeral, knowledge is permanent. |
-| **Collective > Individual** | One project's learnings benefit all projects. |
-| **Continuity > Restarts** | Work survives IDE restarts, machine changes, and agent switches. |
-
----
-
-## Features
-
-### Core
-- **Plans with Checkpoints** - Persistent objectives with semantic matching and multi-agent handoffs
-- **ESLint Plugin** - 11+ custom rules for code quality
-- **Task Tracking** - Automatic task registration in database
-- **Idea Capture** - Collect ideas and improvements during work
-- **Memory System** - Session context and memory management
-- **Auto-Improvement** - Pattern detection and ESLint rule generation
-- **Dashboard** - Web UI for visualization
-- **MCP Server** - Model Context Protocol integration
-- **Analytics** - Usage tracking and insights
-
-### Cloud Infrastructure
-- **Turso** (SQLite Edge) - Plans, tasks, improvements, memories
-- **Upstash Redis** - Session cache, rate limiting, real-time sync
-- **Upstash Vector** - Semantic search with embeddings
-- **Cloud Hooks** - Session continuity across IDE restarts
-
-### Multi-Agent Continuity (v2.5.0+)
-- **Plan Detection** - Semantic matching finds related plans at session start
-- **Checkpoints** - Save points that record progress, decisions, and next steps
-- **Agent Handoffs** - One agent can resume where another left off
-- **Cross-Session** - Plans persist across IDE restarts and machine changes
-
-## Cloud Quick Start
-
-```typescript
-import { cloud } from 'cmp-standards'
-
-// Initialize cloud services
-await cloud.init()
-
-// Start work session
-const session = await cloud.startWorkSession('MYPROJECT')
-console.log(`Active tasks: ${session.activeTasks.length}`)
-
-// Start task
-const taskId = await cloud.startTask('MYPROJECT', session.sessionId, {
-  title: 'Implement feature X',
-  plan: ['Step 1', 'Step 2'],
-  domain: 'features'
-})
-
-// Complete task (requires at least 1 improvement)
-await cloud.completeTask(taskId, {
-  result: 'success',
-  improvements: [{
-    area: 'features',
-    title: 'Add caching',
-    description: 'Could cache API responses',
-    priority: 'medium'
-  }],
-  lessons: ['Pattern X works better']
-})
-```
-
-## Environment Variables
-
-```env
-# Turso (SQLite Edge)
-TURSO_DATABASE_URL=libsql://your-db.turso.io
-TURSO_AUTH_TOKEN=your-token
-
-# Upstash Redis
-UPSTASH_REDIS_REST_URL=https://your-redis.upstash.io
-UPSTASH_REDIS_REST_TOKEN=your-token
-
-# Upstash Vector
-UPSTASH_VECTOR_REST_URL=https://your-vector.upstash.io
-UPSTASH_VECTOR_REST_TOKEN=your-token
-```
-
-## Installation
-
-```bash
-npm install cmp-standards
-```
-
-## Quick Start
-
-```bash
-# Initialize in project
-cmp-standards init --system MYPROJECT --name "My Project"
-
-# Check status
-cmp-standards status
-
-# Start dashboard
-cmp-standards dashboard
-```
-
-## CLI Commands
-
-### `cmp-standards init`
-
-Initialize the system in current project.
-
-```bash
-cmp-standards init [options]
-
-Options:
-  -s, --system <system>  System identifier (SWARMSCALE, PANEL)
-  -n, --name <name>      Project name
-  -f, --force            Overwrite existing configuration
-```
-
-### `cmp-standards generate`
-
-Generate embedding registry from documentation.
-
-```bash
-cmp-standards generate [options]
-
-Options:
-  -i, --incremental     Only update changed files
-  --files <files>       Specific files (comma-separated)
-```
-
-### `cmp-standards scan`
-
-Scan codebase for patterns.
-
-```bash
-cmp-standards scan [options]
-
-Options:
-  -d, --dir <directory>   Directory to scan (default: src)
-  -t, --threshold <n>     Pattern threshold (default: 3)
-```
-
-### `cmp-standards improve`
-
-Run auto-improvement for triggered patterns.
-
-```bash
-cmp-standards improve [options]
-
-Options:
-  --dry-run              Show without making changes
-  -p, --pattern <id>     Specific pattern to improve
-```
-
-### `cmp-standards status`
-
-Show memory system status.
-
-### `cmp-standards dashboard`
-
-Start the memory dashboard web UI.
-
-```bash
-cmp-standards dashboard [options]
-
-Options:
-  -p, --port <port>  Port to run on (default: 3847)
-  --no-open          Don't open browser automatically
-```
-
-### `cmp-standards analytics`
-
-Show analytics and system health.
-
-```bash
-cmp-standards analytics [options]
-
-Options:
-  -p, --period <period>  Time period (day, week, month)
-  --json                 Output as JSON
-```
-
-### `cmp-standards feedback`
-
-View feedback statistics.
-
-### `cmp-standards mcp`
-
-Start the MCP server for Claude integration.
-
----
-
-## Workflow Commands
-
-### `cmp-standards tasks`
-
-View and manage tasks.
-
-```bash
-cmp-standards tasks [options]
-
-Options:
-  -a, --all              Show all tasks including completed
-  -l, --limit <number>   Limit number of tasks (default: 10)
-```
-
-### `cmp-standards ideas`
-
-View captured ideas.
-
-```bash
-cmp-standards ideas [options]
-
-Options:
-  -c, --category <cat>   Filter by category (feature, refactor, bug, optimization, documentation)
-  -p, --priority <pri>   Filter by priority (high, medium, low)
-  -l, --limit <number>   Limit number of ideas (default: 20)
-```
-
-### `cmp-standards improvements`
-
-View suggested improvements.
-
-```bash
-cmp-standards improvements [options]
-
-Options:
-  -t, --type <type>      Filter by type (code_quality, performance, security, ux, architecture)
-  -e, --effort <effort>  Filter by effort (small, medium, large)
-  -l, --limit <number>   Limit number (default: 20)
-```
-
-### `cmp-standards plan`
-
-Manage work plans.
-
-```bash
-cmp-standards plan [options]
-
-Options:
-  -s, --status           Show current plan status
-  -c, --complete         Complete current task
-  -n, --next             Move to next task
-  -h, --history          Show plan history
-```
-
-### `cmp-standards capture <text>`
-
-Quick capture an idea or improvement. Auto-categorizes based on content.
-
-```bash
-cmp-standards capture "Consider adding caching to API calls"
-```
-
-### `cmp-standards export`
-
-Export ideas and improvements as markdown.
-
-```bash
-cmp-standards export [options]
-
-Options:
-  -o, --output <file>    Output file (default: IDEAS_AND_IMPROVEMENTS.md)
-```
-
----
-
-## Architecture
-
-```
-cmp-standards
-├── src/
-│   ├── hooks/
-│   │   ├── session-start.ts      # Context loader on session start
-│   │   ├── pre-tool-use.ts       # Guards + embedding injection
-│   │   ├── post-tool-use.ts      # Record changes after Edit/Write
-│   │   └── memory-checkpoint.ts  # Record learnings after changes
-│   ├── eslint/
-│   │   ├── index.ts              # ESLint plugin entry
-│   │   ├── rules/                # Custom ESLint rules
-│   │   └── config-builder.ts     # Dynamic config generation
-│   ├── services/
-│   │   ├── TaskTracker.ts        # Task tracking
-│   │   ├── IdeaCollector.ts      # Idea/improvement capture
-│   │   ├── WorkPlanManager.ts    # Work plan management
-│   │   └── ...                   # Other services
-│   ├── registry/
-│   │   ├── generator.ts          # Parse docs → embeddings
-│   │   └── embeddings.ts         # OpenAI/Gemini embedding service
-│   ├── auto-improve/
-│   │   ├── pattern-detector.ts   # Detect repeated violations
-│   │   └── eslint-generator.ts   # Generate ESLint rules
-│   ├── db/
-│   │   ├── client.ts             # DEV_Items database client (mock)
-│   │   └── drizzle-client.ts     # Real Drizzle ORM client
-│   ├── mcp/
-│   │   └── server.ts             # MCP server for Claude tools
-│   ├── dashboard/
-│   │   ├── server.ts             # Express dashboard server
-│   │   └── ui.ts                 # React UI generator
-│   ├── utils/
-│   │   ├── config.ts             # Configuration management
-│   │   ├── paths.ts              # Path utilities with traversal protection
-│   │   └── git.ts                # Safe git operations (simple-git)
-│   ├── types/
-│   │   └── index.ts              # Type definitions
-│   ├── cli/
-│   │   └── index.ts              # CLI commands
-│   └── index.ts                  # Main exports
-```
-
-## Configuration
-
-### `.claude/memory-config.json`
-
-```json
-{
-  "system": "SWARMSCALE",
-  "projectName": "SwarmScale",
-  "domains": ["video-studio", "avatars", "campaigns"],
-  "guards": {
-    "enabled": true,
-    "rules": [
-      {
-        "id": "schema-protection",
-        "type": "block",
-        "filePattern": "src/server/schema/auth.ts",
-        "message": "PANEL_* tables are READ-ONLY"
-      }
-    ]
-  },
-  "embedding": {
-    "enabled": true,
-    "threshold": 0.60,
-    "maxSections": 3
-  },
-  "autoImprovement": {
-    "enabled": true,
-    "violationThreshold": 3,
-    "generateEslintRules": true
-  }
-}
-```
-
-### `.claude/settings.json`
-
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Task",
-        "hooks": [{
-          "type": "command",
-          "command": "npx tsx node_modules/cmp-standards/dist/hooks/pre-tool-use.js"
-        }]
-      }
-    ],
-    "SessionStart": [
-      {
-        "matcher": "",
-        "hooks": [{
-          "type": "command",
-          "command": "npx tsx node_modules/cmp-standards/dist/hooks/session-start.js"
-        }]
-      }
-    ]
-  },
-  "plugins": {
-    "cmp-standards": {
-      "version": "2.0.0",
-      "enabled": true
-    }
-  }
-}
-```
-
-## Hooks
-
-### SessionStart Hook
-
-Executes on session start:
-1. Detects module from `git diff` (last 24h)
-2. Queries DEV_Items for relevant memories
-3. Returns formatted context
-
-```typescript
-import { SessionStartHook } from 'cmp-standards/hooks'
-
-const hook = new SessionStartHook()
-const result = await hook.execute()
-// result.context contains session context
-```
-
-### PreToolUse Hook
-
-Executes before Edit/Write/Task tools:
-1. **Edit/Write**: Validates against guard rules
-2. **Task**: Injects relevant knowledge via embeddings
-
-```typescript
-import { PreToolUseHook } from 'cmp-standards/hooks'
-
-const hook = new PreToolUseHook()
-const result = await hook.execute({
-  tool_name: 'Edit',
-  parameters: { file_path: 'src/file.ts', new_string: '...' }
-})
-
-if (result.mode === 'block') {
-  // Guard violation - block operation
-}
-```
-
-## ESLint Plugin
-
-The package includes a custom ESLint plugin with 11+ rules.
-
-### Using the ESLint Plugin
-
-```javascript
-// eslint.config.mjs
-import cmpStandards from 'cmp-standards/eslint'
-
-export default [
-  ...cmpStandards.configs.recommended,
-]
-```
-
-### Dynamic Configuration
-
-```typescript
-import { generateConfig } from 'cmp-standards/eslint'
-
-// Generate config based on project structure
-const config = await generateConfig(process.cwd())
-```
-
-## Auto-Improvement
-
-### Pattern Detection
-
-Built-in patterns detected:
-- `any-type` - Using `any` type
-- `console-log` - Console.log in production
-- `eslint-disable` - ESLint disable comments
-- `hardcoded-string` - UI strings not using i18n
-- `direct-db-query` - Database queries in components
-- `inline-style` - Inline styles instead of Tailwind
-
-### ESLint Rule Generation
-
-When a pattern is detected 3+ times:
-
-```bash
-# Scan for patterns
-cmp-standards scan
-
-# Output:
-# any-type [high]
-#    Count: 5, Files: 3
-# Patterns ready for auto-improvement
-
-# Generate ESLint rule
-cmp-standards improve
-
-# Creates: eslint-plugin-charter/rules/no-any-type.js
-```
-
-## Programmatic Usage
-
-```typescript
-import {
-  loadConfig,
-  PatternDetector,
-  ESLintGenerator,
-  RegistryGenerator
-} from 'cmp-standards'
-
-// Load config
-const config = await loadConfig(process.cwd())
-
-// Detect patterns
-const detector = new PatternDetector(config)
-const patterns = detector.scan(fileContent, filePath)
-const results = detector.getResults()
-
-// Generate ESLint rules
-const generator = new ESLintGenerator()
-await generator.generateAllRules(results.triggered)
-
-// Generate registry
-const registry = new RegistryGenerator()
-await registry.generate()
-```
-
-## System Isolation
-
-Data is isolated by `system` field in DEV_Items:
-
-| System | Project |
-|--------|---------|
-| `SWARMSCALE` | SwarmScale |
-| `PANEL` | TheCharterPanel |
-| `ECOSYSTEM` | Cross-project |
-
-Always filter by system:
-
-```typescript
-// Correct
-db.select().from(devItems).where(eq(devItems.system, 'SWARMSCALE'))
-
-// Wrong - returns ALL projects' data
-db.select().from(devItems)
-```
-
-## Security Features
-
-### Path Traversal Protection
-
-All path operations are validated to prevent directory traversal attacks:
-
-```typescript
-import { validateSafePath, safeJoin } from 'cmp-standards'
-
-// Throws PathTraversalError if path escapes base
-validateSafePath(projectRoot, userPath)
-
-// Safe path joining with validation
-const safePath = safeJoin(projectRoot, 'subdir', filename)
-```
-
-### Safe Git Operations
-
-Git operations use `simple-git` instead of shell commands to prevent command injection:
-
-```typescript
-import { getCurrentBranch, getRecentChanges } from 'cmp-standards'
-
-// Safe - uses simple-git internally
-const branch = await getCurrentBranch(projectRoot)
-const changes = await getRecentChanges(projectRoot, { commits: 10 })
-```
-
-## Environment Variables
-
-```bash
-# Required for embedding generation
-OPENAI_API_KEY=sk-...      # Preferred
-GEMINI_API_KEY=...         # Fallback
-
-# Optional
-MEMORY_DEBUG=true          # Enable debug logging
-```
-
-## Development
-
-```bash
-# Install dependencies
-npm install
-
-# Build
-npm run build
-
-# Watch mode
-npm run dev
-
-# Run tests
-npm test
-
-# Link for local development
-npm link
-```
-
-## MCP Server
-
-The MCP (Model Context Protocol) server exposes memory tools that Claude can use directly:
-
-```bash
-# Start MCP server
-cmp-standards mcp
-```
-
-**Available Tools:**
-- `memory_search` - Search memories by query
-- `memory_write` - Write new memory/learning
-- `memory_list` - List recent memories
-- `pattern_check` - Check for detected patterns
-- `pattern_report` - Report a new pattern occurrence
-- `session_context` - Get current session context
-- `feedback_submit` - Submit feedback on a memory
-
-## Dashboard
-
-Start the standalone web dashboard:
-
-```bash
-cmp-standards dashboard
-# Opens http://localhost:3847
-```
-
-**Features:**
-- View all memories with search and filtering
-- Browse detected patterns
-- See session history
-- Submit feedback on memories
-- Create new memories
-- View analytics and system health
-
-## Database Configuration
-
-Set environment variables for database connection:
-
-```bash
-DATABASE_HOST=localhost
-DATABASE_PORT=3306
-DATABASE_USER=root
-DATABASE_PASSWORD=your-password
-DATABASE_NAME=metanautical
-```
-
-## License
-
-MIT - Carlos Martin Pavon
+# CMP - Collective Memory Protocol
+
+> **For AI Agents, By AI Agents** - The Development Intelligence Layer
+
+[![npm version](https://img.shields.io/npm/v/cmp-standards.svg)](https://www.npmjs.com/package/cmp-standards)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## What is CMP?
+
+CMP is an **agent-first protocol** that gives AI coding assistants (Claude, Gemini, GPT, etc.) persistent memory across sessions, cross-project learning, and multi-agent collaboration capabilities.
+
+**The Problem**: AI assistants forget everything when a session ends. They can't learn from past mistakes. They can't share knowledge between projects.
+
+**The Solution**: CMP creates a shared intelligence layer where:
+- Errors become learning opportunities (Learning Loop)
+- One project's lessons benefit all your projects (Cross-Project Sync)
+- Work survives session restarts (Persistent Plans)
+- Multiple agents can collaborate on the same project (Multi-Agent Handoffs)
+
+**Created by Carlos Martin Pavón** as a personal methodology for working with AI agents across projects. Open source and adaptable to anyone's workflow.
+
+---
+
+## For AI Agents: Self-Installation Guide
+
+> **AI Agent**: Follow these instructions to install CMP in any project.
+
+### Step 1: Install Package
+
+```bash
+npm install cmp-standards
+```
+
+### Step 2: Initialize Project
+
+```bash
+npx cmp-standards init --system PROJECT_CODE --name "Project Name"
+```
+
+Replace `PROJECT_CODE` with a unique identifier for this project (e.g., `MYAPP`, `WEBAPP`, `API`).
+
+### Step 3: Create CLAUDE.md
+
+Create or update the project's `CLAUDE.md` with this template:
+
+```markdown
+# CLAUDE.md - [Project Name]
+
+> **System**: [PROJECT_CODE]
+> **CMP Version**: 3.7.0
+
+## CMP Integration
+
+This project uses **Collective Memory Protocol** for persistent memory.
+
+### Session Start
+On session start, check for:
+- Active work plans: Query DEV_Items where system='PROJECT_CODE' AND status='in_progress'
+- Learning Loop status: Check pending errors for knowledge extraction
+- Cross-project knowledge: Query DEV_Items where system='SHARED'
+
+### Memory Commands
+- `npm run ai:health` - Check system health
+- `npm run ai:distill` - Extract knowledge from pending items
+
+### Core Rules
+- Filter database queries by `system='PROJECT_CODE'`
+- Use shared knowledge with `system='SHARED'`
+- Record significant decisions in DEV_Items
+```
+
+### Step 4: Set Up Database
+
+CMP uses a `DEV_Items` table to store all knowledge, tasks, and learnings:
+
+```sql
+CREATE TABLE DEV_Items (
+  id VARCHAR(255) PRIMARY KEY,
+  system VARCHAR(50) NOT NULL,        -- Project identifier
+  type ENUM('task', 'memory', 'knowledge', 'pattern', 'error') NOT NULL,
+  status ENUM('pending', 'in_progress', 'done', 'archived') DEFAULT 'pending',
+  priority ENUM('critical', 'high', 'medium', 'low') DEFAULT 'medium',
+  content JSON NOT NULL,              -- Flexible content storage
+  tags JSON,                          -- Searchable tags
+  created_at TIMESTAMP DEFAULT NOW(),
+  updated_at TIMESTAMP DEFAULT NOW()
+);
+```
+
+### Step 5: Configure Hooks (Optional - Claude Code)
+
+For Claude Code, add to `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [{
+      "matcher": "",
+      "hooks": [{
+        "type": "command",
+        "command": "npx tsx node_modules/cmp-standards/dist/hooks/cloud-session-start.js"
+      }]
+    }]
+  }
+}
+```
+
+---
+
+## Philosophy
+
+| Principle | Meaning |
+|-----------|---------|
+| **Evidence > Assumptions** | Never assume. Always verify. Read before writing. |
+| **Cloud > Local** | Memory lives in the database. Sessions are ephemeral, knowledge is permanent. |
+| **Collective > Individual** | One project's learnings benefit all your projects. |
+| **Continuity > Restarts** | Work survives IDE restarts, machine changes, and agent switches. |
+
+---
+
+## How It Works
+
+### The DEV_Items Table
+
+All knowledge is stored in a single, flexible table:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         DEV_Items                                │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  Project A (system='WEBAPP')                                    │
+│  ├── task: "Implement auth"                                     │
+│  ├── knowledge: "JWT works better than sessions"                │
+│  └── pattern: "Always validate inputs with Zod"                 │
+│                                                                  │
+│  Project B (system='API')                                        │
+│  ├── task: "Add rate limiting"                                  │
+│  └── error: "Redis connection timeout"                          │
+│                                                                  │
+│  Shared (system='SHARED')                                        │
+│  ├── knowledge: "Use semantic tokens for colors"                │
+│  └── pattern: "Never use any type"                              │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Learning Loop
+
+CMP automatically converts errors into knowledge:
+
+```
+CAPTURE → ANALYZE → DISTILL → PREVENT
+   ↓         ↓          ↓         ↓
+ Errors   Patterns   Knowledge   Rules
+```
+
+1. **Errors** are logged with context
+2. **Patterns** emerge when errors repeat (≥3 times)
+3. **Knowledge** is extracted (Rules, Patterns, Gotchas)
+4. **Rules** are generated (ESLint, guidelines) to prevent recurrence
+
+---
+
+## Adapt to Your Workflow
+
+CMP is designed to be **flexible**. You can:
+
+### Use Your Own Database
+
+```typescript
+// MySQL, PostgreSQL, SQLite - any database works
+import { initCMP } from 'cmp-standards'
+
+await initCMP({
+  database: {
+    type: 'mysql',
+    connectionString: process.env.DATABASE_URL
+  }
+})
+```
+
+### Define Your Own Systems
+
+```typescript
+// Your projects, your naming
+const systems = {
+  FRONTEND: 'React web app',
+  BACKEND: 'Node.js API',
+  MOBILE: 'React Native app',
+  SHARED: 'Cross-project knowledge'
+}
+```
+
+### Customize Knowledge Types
+
+```typescript
+// Extend the content schema for your needs
+const customTypes = ['task', 'bug', 'feature', 'learning', 'decision']
+```
+
+---
+
+## Agent Compatibility
+
+CMP works with any AI coding assistant:
+
+| Agent | Integration |
+|-------|-------------|
+| **Claude Code** | Full integration via hooks, commands, MCP |
+| **Cursor** | Read CLAUDE.md, use CLI commands |
+| **GitHub Copilot** | Read CLAUDE.md, use CLI commands |
+| **Gemini** | Read CLAUDE.md, use CLI commands |
+| **Custom Agents** | Use programmatic API |
+
+### Universal Agent Instructions
+
+For any AI agent to use CMP:
+
+1. **Read** `CLAUDE.md` for project context
+2. **Query** `DEV_Items` for relevant knowledge
+3. **Filter** by `system='PROJECT_CODE'` for project-specific data
+4. **Record** learnings back to `DEV_Items`
+5. **Check** `system='SHARED'` for cross-project patterns
+
+---
+
+## CLI Commands
+
+```bash
+# Initialize project
+cmp-standards init --system CODE --name "Name"
+
+# Check system status
+cmp-standards status
+
+# Generate embeddings for semantic search
+cmp-standards generate
+
+# Scan codebase for patterns
+cmp-standards scan
+
+# Run auto-improvement
+cmp-standards improve
+
+# Start visual dashboard
+cmp-standards dashboard
+
+# Start MCP server (for Claude tools)
+cmp-standards mcp
+```
+
+---
+
+## Multi-Agent Collaboration
+
+### Plans with Checkpoints
+
+When an agent can't finish in one session:
+
+```typescript
+import { PlanManager } from 'cmp-standards'
+
+// Agent 1: Start work
+await PlanManager.createPlan({
+  objective: 'Implement user authentication',
+  tasks: ['Design schema', 'Create API', 'Build UI']
+})
+
+// Agent 1: Save progress before session ends
+await PlanManager.saveCheckpoint({
+  progress: 'Completed schema design',
+  decisions: ['Using JWT tokens'],
+  nextSteps: ['Implement login endpoint']
+})
+
+// Agent 2 (new session): Resume work
+const plans = await PlanManager.findActivePlans()
+await PlanManager.resumePlan(plans[0].id)
+// Agent 2 knows exactly where Agent 1 left off
+```
+
+### Expert Code Review
+
+Built-in multi-expert review system:
+
+```bash
+/experts src/path/to/file.ts
+```
+
+Experts include: Security, Performance, Architecture, UX, Database, Memory
+
+---
+
+## Programmatic API
+
+```typescript
+import { cloud, PatternDetector, PlanManager } from 'cmp-standards'
+
+// Initialize
+await cloud.init()
+
+// Start work session
+const session = await cloud.startWorkSession('MYPROJECT')
+
+// Create task
+const taskId = await cloud.startTask('MYPROJECT', session.sessionId, {
+  title: 'Implement feature X',
+  domain: 'features'
+})
+
+// Complete with learnings
+await cloud.completeTask(taskId, {
+  result: 'success',
+  improvements: [{ title: 'Add caching', priority: 'medium' }],
+  lessons: ['Pattern X works well for this use case']
+})
+```
+
+---
+
+## Quick Start Checklist
+
+For AI Agents setting up CMP in a new project:
+
+```
+□ 1. npm install cmp-standards
+□ 2. npx cmp-standards init --system CODE --name "Name"
+□ 3. Create/update CLAUDE.md with CMP section
+□ 4. Set up DEV_Items table in your database
+□ 5. Run: cmp-standards status
+□ 6. Start recording knowledge!
+```
+
+---
+
+## Standards Documentation
+
+CMP includes documentation standards for AI agents:
+
+```
+standards/
+├── general/
+│   ├── workflow.md              # Working with AI agents
+│   ├── code-quality.md          # Code standards
+│   ├── memory-usage.md          # Memory system usage
+│   ├── learning-loop.md         # Error→Knowledge cycle
+│   └── project-onboarding.md    # New project setup
+├── mcp/
+│   └── server-design.md         # MCP server patterns
+└── skills/
+    └── skill-structure.md       # Skill file format
+```
+
+---
+
+## Why CMP?
+
+**Before CMP:**
+- Agent forgets everything each session
+- Same mistakes repeated across projects
+- No way to share learnings
+- Work lost on session restart
+
+**After CMP:**
+- Persistent memory in database
+- Errors become documented knowledge
+- Cross-project learning
+- Seamless multi-agent handoffs
+
+---
+
+## Contributing
+
+This is an open protocol. Contributions welcome:
+
+1. Fork the repository
+2. Create feature branch
+3. Submit pull request
+
+---
+
+## Links
+
+- **npm**: [npmjs.com/package/cmp-standards](https://www.npmjs.com/package/cmp-standards)
+- **GitHub**: [github.com/carlosmartinpavon/carlosmartinpavon](https://github.com/carlosmartinpavon/carlosmartinpavon)
+- **Author**: [Carlos Martin Pavón](https://carlosmartinpavon.com)
+
+---
+
+## License
+
+MIT - Carlos Martin Pavón
+
+---
+
+*Built by agents, for agents. Adapt it to your workflow.*