contextos-agents 1.5.0

package/.agents/core/skills/context-os/references/context-rules.md

@@ -0,0 +1,68 @@
+# Context Loading Rules
+
+## Task Type → Document Mapping
+
+| Task Type | Level 1 (Always) | Level 2 (If exists) | Level 3 (Per task) |
+| --- | --- | --- | --- |
+| **New project** | PRD, ROADMAP | ARCHITECTURE, DATABASE, API | UI, TASKS, all relevant skills |
+| **New feature** | PRD | ARCHITECTURE, API | PROJECT_GRAPH, relevant skills |
+| **Frontend** | — | ARCHITECTURE, API | UI, frontend skills |
+| **Backend** | — | ARCHITECTURE, DATABASE, API | backend skills |
+| **Database** | — | ARCHITECTURE, DATABASE | — |
+| **Bugfix** | — | — | PROJECT_GRAPH (affected module only) |
+| **Refactor** | — | ARCHITECTURE | PROJECT_GRAPH, affected skills |
+| **Review** | PRD | ARCHITECTURE | TASKS, all loaded skills |
+| **Deploy** | — | ARCHITECTURE | DEPLOYMENT, infrastructure skills |
+
+## Skill Category → Document Mapping
+
+| Skill Category | Required Documents | Optional Documents |
+| --- | --- | --- |
+| `frontend` | UI.md, API.md | ARCHITECTURE.md |
+| `backend` | API.md, DATABASE.md | ARCHITECTURE.md |
+| `design` | UI.md | PRD.md |
+| `architecture` | ARCHITECTURE.md, DATABASE.md | PRD.md, API.md |
+| `infrastructure` | ARCHITECTURE.md | — |
+| `security` | ARCHITECTURE.md, API.md | DATABASE.md |
+| `testing` | API.md | ARCHITECTURE.md |
+
+## Context Budget
+
+To prevent context window overflow, apply these limits:
+
+| Priority | Max tokens | Content |
+| --- | --- | --- |
+| 1 (Critical) | 2000 | Current task description + relevant skill instructions |
+| 2 (Important) | 3000 | Architecture + API contracts for affected modules |
+| 3 (Context) | 2000 | Decision records + project graph (affected branch) |
+| 4 (Background) | 1000 | PRD summary + coding rules |
+
+**Total budget: ~8000 tokens of context per task.**
+
+If context exceeds budget:
+
+1. Trim Level 1 docs to summaries only
+2. Load only affected sections of Level 2 docs
+3. Keep Level 3 (skills) at full detail — they contain the actual instructions
+
+## Module-Based Filtering
+
+When the Project Graph is available, use it to filter context:
+
+```
+Task: "Fix appointment reminder bug"
+  ↓
+Project Graph lookup: "reminder" → module: appointments
+  ↓
+Appointments depends_on: [patients, auth]
+  ↓
+Load only:
+  - appointments module docs
+  - auth module docs (dependency)
+  - API.md (appointments section only)
+  ↓
+Skip:
+  - patients module docs (not a dependency for this task)
+  - DATABASE.md (no schema change expected)
+  - UI.md (backend task)
+```

package/.agents/core/skills/context-os/references/pipeline.md

@@ -0,0 +1,119 @@
+# Development Pipeline
+
+## The ContextOS Lifecycle
+
+```
+  ┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
+  │  DEFINE  │ ──▶ │   PLAN   │ ──▶ │  BUILD   │ ──▶ │  VERIFY  │ ──▶ │  REVIEW  │ ──▶ │   SHIP   │
+  │          │     │          │     │          │     │          │     │          │     │          │
+  │ What to  │     │ How to   │     │ Write    │     │ Test &   │     │ Quality  │     │ Deploy & │
+  │ build    │     │ build it │     │ code     │     │ validate │     │ gates    │     │ document │
+  └──────────┘     └──────────┘     └──────────┘     └──────────┘     └──────────┘     └──────────┘
+       │                │                │                │                │                │
+  PRD.md           ARCHITECTURE.md  source code      tests           code review      DECISION.md
+  UI.md            DATABASE.md      components       coverage        self-review      changelog
+  ROADMAP.md       API.md           API routes       edge cases      security scan    deploy
+  PROJECT_GRAPH    TASKS.md         migrations       performance     a11y audit       release notes
+```
+
+## Stage Details
+
+### 1. DEFINE — "What are we building?"
+
+**Input:** User idea or feature request
+**Output:** PRD.md, UI.md, ROADMAP.md, PROJECT_GRAPH.md
+
+Process:
+
+1. Intent Analysis — parse the user's request
+2. Clarifying questions — fill gaps
+3. Generate PRD with clear requirements
+4. Generate UI spec if frontend is involved
+5. Create initial Project Graph
+
+**Context loaded:** None (this is the starting point)
+
+### 2. PLAN — "How will we build it?"
+
+**Input:** PRD.md
+**Output:** ARCHITECTURE.md, DATABASE.md, API.md, TASKS.md
+
+Process:
+
+1. Choose architecture based on profile + requirements
+2. Design database schema
+3. Define API contracts
+4. Break work into atomic tasks
+5. Update Project Graph with modules and features
+
+**Context loaded:** PRD.md, profiles/
+
+### 3. BUILD — "Write the code"
+
+**Input:** TASKS.md + relevant architecture docs
+**Output:** Source code, migrations, configurations
+
+Process:
+
+1. Pick next task from TASKS.md
+2. Context Compiler loads only relevant skills and docs
+3. Write code following loaded skill instructions
+4. Commit after each completed task
+5. Update Project Graph if structure changes
+
+**Context loaded:** Task-specific (via Context Manager)
+
+### 4. VERIFY — "Prove it works"
+
+**Input:** Source code
+**Output:** Tests, coverage reports
+
+Process:
+
+1. Write tests for new code
+2. Run existing tests — ensure nothing broke
+3. Check edge cases
+4. Verify performance (if applicable)
+
+**Context loaded:** Testing skills + API.md
+
+### 5. REVIEW — "Quality check"
+
+**Input:** Code changes (diff)
+**Output:** Review comments, approved changes
+
+Process:
+
+1. Self-review against coding standards
+2. Security scan (if security skill loaded)
+3. Accessibility audit (if frontend)
+4. Check against ARCHITECTURE.md — does this align?
+5. Check against Decision Records — does this contradict anything?
+
+**Context loaded:** ARCHITECTURE.md + relevant skills + decisions/
+
+### 6. SHIP — "Deploy and document"
+
+**Input:** Reviewed, tested code
+**Output:** Deployment, decision records, release notes
+
+Process:
+
+1. Record any architectural decisions made (ADR)
+2. Update ROADMAP.md — mark completed items
+3. Update TASKS.md — close completed tasks
+4. Deploy (if deployment skill loaded)
+5. Update Project Graph
+
+**Context loaded:** ROADMAP.md, TASKS.md, deployment skills
+
+## Profiles and Pipeline
+
+Different profiles customize the pipeline:
+
+| Profile | Skips | Adds |
+| --- | --- | --- |
+| **Hackathon** | REVIEW, detailed PLAN | Speed shortcuts |
+| **MVP** | Detailed REVIEW, DEPLOY | Quick iterations |
+| **Startup** | Heavy docs | Balance of speed and quality |
+| **Enterprise** | Nothing | ADR enforcement, security gates, full testing |

package/.agents/core/skills/context-os/references/project-graph.md

@@ -0,0 +1,103 @@
+# Project Graph
+
+The Project Graph is the **central nervous system** of ContextOS. It maps the entire project as a hierarchy:
+
+```
+Project
+  └── Module
+        └── Feature
+              └── Task
+                    └── File
+                          └── Skill
+```
+
+## Why Project Graph?
+
+Without a Project Graph, an AI agent sees a flat list of files. With it, the agent understands:
+
+1. **Impact analysis** — changing `calendar.ts` affects the Appointments module, which affects Patients
+2. **Scope detection** — a task touching `api/patients/` only needs Patient-related context
+3. **Skill selection** — files in `components/` need React skills, files in `api/` need backend skills
+4. **Dependency tracking** — the Calendar feature depends on the Auth module
+
+## Structure
+
+The Project Graph lives in `docs/PROJECT_GRAPH.md` and follows this format:
+
+```yaml
+project:
+  name: "DentalCRM"
+  type: crm
+  
+modules:
+  patients:
+    description: "Patient management"
+    features:
+      - patient-list
+      - patient-profile
+      - medical-history
+    files:
+      - src/modules/patients/**
+    skills: [react, typescript, postgres]
+    depends_on: [auth]
+    
+  appointments:
+    description: "Appointment scheduling"
+    features:
+      - appointment-calendar
+      - appointment-booking
+      - notifications
+    files:
+      - src/modules/appointments/**
+    skills: [react, typescript, postgres]
+    depends_on: [patients, auth]
+    
+  auth:
+    description: "Authentication and authorization"
+    features:
+      - login
+      - registration
+      - role-management
+    files:
+      - src/modules/auth/**
+    skills: [security, typescript, jwt]
+    depends_on: []
+```
+
+## How the Context Compiler Uses It
+
+### Task: "Add a reminder notification for appointments"
+
+1. **Locate module**: `appointments`
+2. **Check dependencies**: `appointments` → `patients`, `auth`
+3. **Load relevant files**: `src/modules/appointments/**`, `src/modules/notifications/**`
+4. **Load relevant skills**: `react`, `typescript`, notification patterns
+5. **Load relevant docs**: `ARCHITECTURE.md` (notifications section), `API.md` (endpoints)
+6. **Skip irrelevant**: `DATABASE.md` (no schema change), `UI.md` (if backend-only)
+
+### Task: "Refactor the database schema"
+
+1. **Affected modules**: ALL (schema change is cross-cutting)
+2. **Load**: `DATABASE.md`, `ARCHITECTURE.md`, `PROJECT_GRAPH.md`
+3. **Show impact**: which modules/features are affected by each table change
+4. **Load skills**: `postgres` (or relevant DB skill)
+
+## Automatic Updates
+
+The Project Graph should be updated when:
+
+- New modules are added
+- Features are completed
+- File structure changes significantly
+- Dependencies between modules change
+
+Use `ctx graph` to regenerate the Project Graph from the current codebase.
+
+## Graph Queries
+
+The Context Compiler can answer questions like:
+
+- "What modules does this file belong to?"
+- "What skills are needed for this module?"
+- "What other modules will be affected if I change this?"
+- "Show me the dependency chain from here"

package/.agents/core/skills/context-os/rules.yaml

@@ -0,0 +1,135 @@
+# Rule Engine
+# Conditional logic for context compilation based on project profile and task type
+
+rules:
+  # ═══════════════════════════════════════
+  # Profile-based rules
+  # ═══════════════════════════════════════
+
+  - name: mvp-minimal
+    description: MVP projects skip heavy infrastructure
+    if:
+      profile: mvp
+    then:
+      exclude_skills: [microservices, ddd, kubernetes, monitoring, cicd]
+      exclude_docs: [DEPLOYMENT.md]
+      prefer_skills: [sqlite, simple-auth, minimal-architecture]
+      max_doc_depth: 2  # Only Level 1 + Level 2
+
+  - name: enterprise-strict
+    description: Enterprise projects require full documentation and rigor
+    if:
+      profile: enterprise
+    then:
+      require_skills: [ddd, security, testing, cicd]
+      require_docs: [ARCHITECTURE.md, DATABASE.md, API.md, DECISIONS]
+      enforce_adr: true  # Every architectural decision must be recorded
+      enforce_testing: true
+      min_doc_depth: 3  # All levels required
+
+  - name: hackathon-speed
+    description: Hackathon mode — maximum speed, minimum ceremony
+    if:
+      profile: hackathon
+    then:
+      exclude_skills: [kubernetes, monitoring, cicd, ddd, microservices]
+      exclude_docs: [DEPLOYMENT.md, ROADMAP.md]
+      prefer_skills: [sqlite, simple-auth]
+      skip_review: true
+      max_doc_depth: 1  # Vision only
+
+  - name: startup-balanced
+    description: Startup balance between speed and quality
+    if:
+      profile: startup
+    then:
+      exclude_skills: [kubernetes, ddd]
+      prefer_skills: [postgres, jwt-auth, docker]
+      enforce_adr: false
+      max_doc_depth: 2
+
+  # ═══════════════════════════════════════
+  # Task-based rules
+  # ═══════════════════════════════════════
+
+  - name: frontend-task
+    description: Frontend tasks don't need database or deployment docs
+    if:
+      task_type: frontend
+    then:
+      load_docs: [UI.md, ARCHITECTURE.md, API.md]
+      skip_docs: [DATABASE.md, DEPLOYMENT.md]
+      load_skill_categories: [frontend, design]
+      skip_skill_categories: [backend, infrastructure]
+
+  - name: backend-task
+    description: Backend tasks don't need UI docs
+    if:
+      task_type: backend
+    then:
+      load_docs: [ARCHITECTURE.md, DATABASE.md, API.md]
+      skip_docs: [UI.md]
+      load_skill_categories: [backend, architecture]
+      skip_skill_categories: [design]
+
+  - name: architecture-task
+    description: Architecture tasks load everything at high level
+    if:
+      task_type: architecture
+    then:
+      load_docs: [PRD.md, ARCHITECTURE.md, DATABASE.md, API.md, PROJECT_GRAPH.md]
+      load_skill_categories: [architecture]
+      skip_skill_categories: [design]
+
+  - name: bugfix-task
+    description: Bugfixes need minimal context — focus on affected module
+    if:
+      task_type: bugfix
+    then:
+      load_docs: [PROJECT_GRAPH.md]  # Find affected module
+      max_doc_depth: 1
+      skip_docs: [PRD.md, ROADMAP.md]
+
+  - name: refactor-task
+    description: Refactoring needs architecture context
+    if:
+      task_type: refactor
+    then:
+      load_docs: [ARCHITECTURE.md, PROJECT_GRAPH.md]
+      load_skill_categories: [architecture]
+
+  # ═══════════════════════════════════════
+  # Stack-based rules
+  # ═══════════════════════════════════════
+
+  - name: react-ecosystem
+    description: React projects auto-load TypeScript
+    if:
+      skill_loaded: react
+    then:
+      auto_load: [typescript]
+      suggest: [tailwind, react-query]
+
+  - name: nextjs-ecosystem
+    description: Next.js implies React + TypeScript + SSR patterns
+    if:
+      skill_loaded: nextjs
+    then:
+      auto_load: [react, typescript]
+      suggest: [prisma, next-auth, tailwind]
+
+  - name: fastapi-ecosystem
+    description: FastAPI implies Python + Pydantic
+    if:
+      skill_loaded: fastapi
+    then:
+      auto_load: [python, pydantic]
+      suggest: [postgres, docker, testing]
+
+  - name: no-conflicts
+    description: Prevent incompatible frameworks
+    if:
+      any_loaded: [react, vue, angular, svelte]
+    then:
+      conflict_check: true
+      max_frontend_frameworks: 1

package/.agents/core/skills/context-os/skill.yaml

@@ -0,0 +1,10 @@
+name: context-os
+description: >
+  AI Project Operating System context compiler that transforms user intent into
+  minimal, relevant context for any AI agent across the full development lifecycle.
+tags:
+  - workflow
+  - orchestration
+  - architecture
+  - context
+version: 1.0.0

package/.agents/core/skills/database/EXAMPLES.md

@@ -0,0 +1,74 @@
+# Database Examples — Anti-patterns vs ContextOS Standard
+
+## Example 1: Solving the N+1 Query Problem
+
+### Anti-pattern: Anti-pattern (N+1 database queries in a loop)
+
+```typescript
+// BAD: 1 query for users + N queries for posts!
+const users = await prisma.user.findMany();
+const usersWithPosts = [];
+for (const user of users) {
+  const posts = await prisma.post.findMany({ where: { userId: user.id } }); // N queries!
+  usersWithPosts.push({ ...user, posts });
+}
+```
+
+### Best practice: ContextOS Standard (Batch query or relational include)
+
+```typescript
+// GOOD: 1 single optimized batch query
+const usersWithPosts = await prisma.user.findMany({
+  where: { isActive: true },
+  select: {
+    id: true,
+    name: true,
+    email: true,
+    posts: {
+      where: { published: true },
+      select: { id: true, title: true, createdAt: true },
+      take: 5
+    }
+  }
+});
+```
+
+---
+
+## Example 2: Safe Atomic Transactions with Locking
+
+### Anti-pattern: Anti-pattern (Unprotected read-modify-write race condition)
+
+```typescript
+// BAD: race condition between reading balance and updating
+const account = await prisma.account.findUnique({ where: { id } });
+if (account.balance >= amount) {
+  await prisma.account.update({
+    where: { id },
+    data: { balance: account.balance - amount }
+  });
+}
+```
+
+### Best practice: ContextOS Standard (Atomic conditional update in transaction)
+
+```typescript
+// GOOD: atomic database transaction with invariant check
+export async function deductBalance(accountId: string, amount: number) {
+  return await prisma.$transaction(async (tx) => {
+    const updated = await tx.account.updateMany({
+      where: {
+        id: accountId,
+        balance: { gte: amount }
+      },
+      data: {
+        balance: { decrement: amount }
+      }
+    });
+
+    if (updated.count === 0) {
+      throw new InsufficientFundsError(accountId);
+    }
+  });
+}
+```

package/.agents/core/skills/database/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: database
+description: Database architecture, schema design, Prisma, Drizzle ORM, indexing strategies, migrations, and N+1 query resolution.
+---
+
+# database
+
+## Overview
+
+Relational database design, query optimization, migration safety, connection pooling in serverless environments, and ORM usage across PostgreSQL, Prisma, and Drizzle.
+
+## When to Use
+
+Activate for tasks involving database schema design, migrations, indexing, relational models, ORM queries, transactions, or query performance tuning.
+
+## Rules & Patterns
+
+### Negative Constraints (What NOT to Do)
+
+1. **NEVER do `SELECT *` in production**: Always select explicit columns required by the caller to minimize memory bandwidth and lock footprint.
+2. **NEVER run destructive migrations without backward compatibility**: Always follow expand-and-contract (Phase 1: add new column as nullable; Phase 2: backfill; Phase 3: make non-nullable & remove old column).
+3. **NEVER execute queries in loops (The N+1 Anti-Pattern)**: Always use batch loading (`inArray`, `DataLoader`, or relational `include` / `JOIN`).
+4. **NEVER leave foreign keys without indexes**: In PostgreSQL/MySQL, child foreign key columns must always have an index to prevent table-level locking on cascade deletes.
+5. **NEVER perform multi-entity writes without a database transaction**: Any operation touching multiple records must use `prisma.$transaction` or `db.transaction`.
+6. **NEVER open unpooled database connections in Serverless / Edge functions**: Serverless scale-outs will instantly exhaust PostgreSQL's `max_connections`.
+
+---
+
+### Zero-Downtime Migrations (Expand-and-Contract)
+
+When modifying schemas with zero downtime:
+
+1. **Phase 1 (Expand)**: Add the new column as `NULLABLE` (or with a default value). Deploy the application code that reads from old column and writes to both old and new.
+2. **Phase 2 (Backfill)**: Run an asynchronous batch migration job in chunks (e.g. 1000 rows at a time) to populate data from old column to new column.
+3. **Phase 3 (Contract)**: Update application code to read and write exclusively from the new column.
+4. **Phase 4 (Cleanup)**: Once traffic is fully shifted, remove the old column and mark the new column as `NOT NULL` in a separate migration.
+
+---
+
+### Serverless & Edge Connection Pooling
+
+In serverless environments (AWS Lambda, Vercel Functions):
+
+- Always connect via a connection pooler:
+  - **Prisma**: Use Prisma Accelerate or configure transaction mode connection URLs.
+  - **Drizzle / Node-Postgres**: Use `@neondatabase/serverless` or connect to PgBouncer pooler port (`6543`) with `max: 1` per serverless container.
+- Set strict statement timeouts (e.g. `statement_timeout = '5000'`) to prevent hanging queries from exhausting pool capacity.
+
+---
+
+### Indexing & Performance Rules
+
+- **B-Tree Indexes**: For high-cardinality filters (`status`, `user_id`, `created_at`).
+- **Composite Indexes**: When querying multiple columns together (`WHERE organization_id = ? AND status = ?`), order columns in index by equality first, range second.
+- **Partial Indexes**: For sparse boolean flags (`WHERE is_processed = false`).
+- **Covering Indexes**: Include frequently selected columns (`INCLUDE (title, created_at)`) to enable index-only scans without table heap access.
+
+---
+
+## Code Examples
+
+### Zero-Downtime Column Rename (Drizzle ORM)
+
+```typescript
+// Step 1 (Expand): Keep old column, add new column
+export const users = pgTable('users', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  fullName: varchar('full_name', { length: 255 }), // new column
+  name: varchar('name', { length: 255 }),           // old column kept during transition
+});
+
+// App write logic during transition:
+await db.insert(users).values({
+  name: input.name,
+  fullName: input.name
+});
+```
+
+---
+
+## Validation Checklist
+
+- [ ] All database queries select explicit required columns (no `SELECT *`).
+- [ ] Foreign keys have matching indexes on child tables.
+- [ ] Multi-table writes wrapped in ACID transactions.
+- [ ] No N+1 queries in loops.
+- [ ] Schema migrations tested against expand-and-contract pattern.
+- [ ] Serverless database connection string uses pooling proxy.
+
+---
+
+## Common Mistakes
+
+- **Missing pagination limits**: Unbounded `findMany()` calls leading to Out-Of-Memory crashes under production volume.
+- **Locking entire tables**: Adding `NOT NULL` columns with heavy compute defaults in PostgreSQL without concurrent index creation.
+
+---
+
+## Integration Notes
+
+- Interacts with `system-design`, `ddd`, and `security` (multi-tenant tenantId scoping).

package/.agents/core/skills/database/TROUBLESHOOTING.md

@@ -0,0 +1,18 @@
+# Database Troubleshooting Guide
+
+## Common Issues & Fixes
+
+### 1. Connection Pool Exhaustion in Serverless / Edge
+
+- **Cause**: Creating a new PrismaClient / DB connection instance on every serverless function invocation.
+- **Fix**: Declare PrismaClient as a global singleton across warm lambdas, and enable PgBouncer or Prisma Accelerate.
+
+### 2. Slow Queries on Large Tables
+
+- **Cause**: Missing composite index on filtered and ordered columns.
+- **Fix**: Run `EXPLAIN ANALYZE <query>` and add targeted indexes matching the WHERE and ORDER BY columns.
+
+### 3. Database Deadlocks during Concurrent Transactions
+
+- **Cause**: Different transactions updating resources in different orders.
+- **Fix**: Always acquire locks and update entities in a deterministic alphabetical or ID-ordered sequence.

package/.agents/core/skills/database/VALIDATION.json

@@ -0,0 +1,11 @@
+{
+  "skill": "database",
+  "version": "1.0.0",
+  "checks": [
+    "No SELECT * in application queries",
+    "All foreign keys indexed",
+    "Multi-table writes enclosed in database transactions",
+    "No N+1 queries in loops",
+    "Safe expand-and-contract migration strategy"
+  ]
+}

package/.agents/core/skills/database/skill.yaml

@@ -0,0 +1,25 @@
+name: database
+description: Database architecture, schema design, Prisma, Drizzle ORM, indexing strategies, migrations, and N+1 query resolution.
+version: 1.0.0
+category: backend
+requires:
+  - system-design
+  - typescript
+triggers:
+  files:
+    - "*.prisma"
+    - "schema.prisma"
+    - "drizzle.config.*"
+    - "migrations/*"
+    - "*.sql"
+  keywords:
+    - "database"
+    - "prisma"
+    - "drizzle"
+    - "postgres"
+    - "postgresql"
+    - "sql"
+    - "migration"
+    - "index"
+    - "transaction"
+    - "orm"