cmp-standards 3.5.1 → 3.7.0

package/standards/general/project-onboarding.md

@@ -0,0 +1,339 @@
+# Project Onboarding Guide
+
+> **Purpose**: Set up CMP in a new project
+> **Audience**: AI agents and developers
+
+---
+
+## Quick Start Checklist
+
+```
+□ 1. Install cmp-standards
+□ 2. Run initialization
+□ 3. Configure CLAUDE.md
+□ 4. Set up database (DEV_Items table)
+□ 5. (Optional) Configure hooks
+□ 6. Verify with status command
+□ 7. Start recording knowledge!
+```
+
+---
+
+## Step 1: Install cmp-standards
+
+```bash
+npm install cmp-standards
+```
+
+Or with yarn/pnpm:
+```bash
+yarn add cmp-standards
+pnpm add cmp-standards
+```
+
+---
+
+## Step 2: Initialize Project
+
+```bash
+npx cmp-standards init --system MYPROJECT --name "My Project"
+```
+
+This creates:
+- `.claude/` directory structure
+- Initial configuration files
+
+---
+
+## Step 3: Configure CLAUDE.md
+
+Your `CLAUDE.md` should include this template:
+
+```markdown
+# CLAUDE.md - [Project Name]
+
+> **System**: [PROJECT_CODE]
+> **CMP Version**: 3.7.0
+
+---
+
+## Project Overview
+
+[Brief description of your project]
+
+### Tech Stack
+
+- **Framework**: [Next.js/React/etc]
+- **Language**: TypeScript
+- **Database**: [MySQL/PostgreSQL/etc]
+- **CMP**: cmp-standards (persistent memory)
+
+---
+
+## CMP Integration
+
+This project uses **Collective Memory Protocol** for persistent AI memory.
+
+### Session Start
+On session start, check for:
+- Active tasks: `WHERE system='PROJECT_CODE' AND status='in_progress'`
+- Pending knowledge: `WHERE system='PROJECT_CODE' AND type='knowledge'`
+- Shared patterns: `WHERE system='SHARED'`
+
+### Memory Commands
+```bash
+npm run ai:health      # Check system health
+npm run ai:distill     # Extract knowledge
+cmp-standards status   # Show status
+```
+
+### Core Rules
+- Filter database by `system='PROJECT_CODE'`
+- Check `system='SHARED'` for cross-project knowledge
+- Record significant decisions in DEV_Items
+
+---
+
+## Core Rules (Non-Negotiable)
+
+### Code Quality
+- NO `any`/`unknown` types
+- NO ESLint disable comments
+- Validate inputs with Zod
+
+### Database
+- ALWAYS filter by `system='PROJECT_CODE'`
+- Use transactions for multi-table operations
+
+---
+
+## Commands
+
+### Development
+```bash
+npm run dev
+npm run build
+npm run lint
+npm run typecheck
+```
+
+### AI/Memory
+```bash
+npm run ai:health
+npm run ai:distill
+cmp-standards status
+```
+
+---
+
+*Using CMP - Collective Memory Protocol*
+```
+
+---
+
+## Step 4: Set Up Database
+
+Create the DEV_Items table in your database:
+
+```sql
+CREATE TABLE DEV_Items (
+  id VARCHAR(255) PRIMARY KEY,
+  system VARCHAR(50) NOT NULL,
+  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,
+  tags JSON,
+  created_at TIMESTAMP DEFAULT NOW(),
+  updated_at TIMESTAMP DEFAULT NOW(),
+
+  INDEX idx_system (system),
+  INDEX idx_type (type),
+  INDEX idx_status (status)
+);
+```
+
+### For Drizzle ORM
+
+```typescript
+// schema/tables/dev.ts
+import { mysqlTable, varchar, mysqlEnum, json, timestamp } from 'drizzle-orm/mysql-core'
+
+export const devItems = mysqlTable('DEV_Items', {
+  id: varchar('id', { length: 255 }).primaryKey(),
+  system: varchar('system', { length: 50 }).notNull(),
+  type: mysqlEnum('type', ['task', 'memory', 'knowledge', 'pattern', 'error']).notNull(),
+  status: mysqlEnum('status', ['pending', 'in_progress', 'done', 'archived']).default('pending'),
+  priority: mysqlEnum('priority', ['critical', 'high', 'medium', 'low']).default('medium'),
+  content: json('content').notNull(),
+  tags: json('tags'),
+  createdAt: timestamp('created_at').defaultNow(),
+  updatedAt: timestamp('updated_at').defaultNow(),
+})
+```
+
+---
+
+## Step 5: Configure Hooks (Optional)
+
+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"
+      }]
+    }]
+  }
+}
+```
+
+### Custom SessionStart Hook
+
+```typescript
+// .claude/hooks/session-start.ts
+export async function onSessionStart() {
+  console.log('━'.repeat(50))
+  console.log('PROJECT: WAKING UP...')
+  console.log('━'.repeat(50))
+
+  // 1. Check active tasks
+  await showActiveTasks()
+
+  // 2. Check for pending knowledge
+  await checkPendingKnowledge()
+
+  console.log('━'.repeat(50))
+  console.log('✅ System Ready.')
+  console.log('━'.repeat(50))
+}
+
+async function showActiveTasks() {
+  // Query DEV_Items for active tasks
+  const tasks = await db.query.devItems.findMany({
+    where: and(
+      eq(devItems.system, 'MYPROJECT'),
+      eq(devItems.status, 'in_progress')
+    )
+  })
+
+  console.log(`\n📋 Active tasks: ${tasks.length}`)
+  tasks.forEach(t => console.log(`   - ${t.content.title}`))
+}
+
+async function checkPendingKnowledge() {
+  // Query for knowledge needing distillation
+  const pending = await db.query.devItems.findMany({
+    where: and(
+      eq(devItems.system, 'MYPROJECT'),
+      eq(devItems.type, 'knowledge'),
+      eq(devItems.status, 'pending')
+    )
+  })
+
+  if (pending.length > 5) {
+    console.log(`\n⚠️  ${pending.length} knowledge items pending distillation`)
+    console.log('   Consider running: npm run ai:distill')
+  }
+}
+```
+
+---
+
+## Step 6: Verify Setup
+
+Run the status command:
+
+```bash
+cmp-standards status
+```
+
+Expected output:
+```
+CMP Status
+──────────────────────────────────
+System: MYPROJECT
+Database: Connected
+DEV_Items: 0 entries
+Status: Ready
+──────────────────────────────────
+```
+
+---
+
+## Step 7: Initial Knowledge Dump
+
+Record your project's key patterns:
+
+```typescript
+// Via code
+await db.insert(devItems).values({
+  id: `knowledge_${Date.now()}`,
+  system: 'MYPROJECT',
+  type: 'knowledge',
+  status: 'done',
+  priority: 'high',
+  content: {
+    title: 'Important Pattern: [Name]',
+    body: '[Description of the pattern]',
+    domain: 'architecture',
+  },
+  tags: ['onboarding', 'architecture'],
+})
+```
+
+Or via CLI:
+```bash
+cmp-standards capture "Always validate user inputs with Zod schemas"
+```
+
+---
+
+## Verification Checklist
+
+After setup, verify:
+
+```
+□ CLAUDE.md has correct System code
+□ DEV_Items table exists in database
+□ cmp-standards status works
+□ Can insert a test knowledge entry
+□ Can query by system filter
+□ (Optional) SessionStart hook runs
+```
+
+---
+
+## Common Issues
+
+### "DEV_Items table not found"
+- Run the SQL migration
+- Check DATABASE_URL is correct
+
+### "Cannot connect to database"
+- Verify DATABASE_URL environment variable
+- Check network/firewall settings
+
+### "No knowledge found"
+- Make sure you're filtering by correct system code
+- Run initial knowledge dump
+
+---
+
+## Next Steps
+
+After onboarding:
+
+1. **Record patterns** as you work
+2. **Run distillation** periodically: `npm run ai:distill`
+3. **Check health**: `npm run ai:health`
+4. **Promote patterns** to SHARED when valuable
+
+---
+
+*CMP - Collective Memory Protocol*
+*Created by Carlos Martin Pavón*