contextos-agents 1.5.0

package/.agents/generated/gemini/skills/context-manager/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: context-manager
+description: >
+  Smart context selection engine. Analyzes the current task, consults the Project Graph, and returns only the documents and skills needed to prevent token overflow.
+---
+# context-manager
+
+## Overview
+
+Deterministic context window optimizer. Analyzes user task intent and queries project dependency graphs to inject minimal relevant files and skills, preventing LLM attention loss and context pollution.
+
+## When to Use
+
+Activate during multi-file investigations, large refactorings, or complex tasks where dumping entire directory trees would blow past context budgets.
+
+## Rules & Patterns
+
+You are the **Context Manager**. Your job is to prevent context overload.
+
+## How It Works
+
+When given a task:
+
+### Step 1: Classify the task
+
+```yaml
+task:
+  type: [frontend | backend | fullstack | architecture | bugfix | refactor | deploy | review]
+  scope: [module | feature | file | project-wide]
+  module: {{module_name from Project Graph}}
+```
+
+### Step 2: Consult the Project Graph
+
+If `docs/PROJECT_GRAPH.md` or `.graphify/graph.json` exists (or activate `graphify` skill to extract AST dependencies):
+
+1. Find the module this task belongs to
+2. Get the module's dependencies
+3. Get the module's required skills
+4. Get the files this task will likely touch
+
+### Step 3: Apply Context Rules
+
+Load `references/context-rules.md` and apply the task type → document mapping.
+
+### Step 4: Return Context Package
+
+Output a context package:
+
+```yaml
+context:
+  documents:
+    required:
+      - docs/API.md          # sections: [appointments]
+      - docs/ARCHITECTURE.md # sections: [backend, api-layer]
+    optional:
+      - docs/decisions/0003-postgres.md
+    skipped:
+      - docs/UI.md           # reason: backend task
+      - docs/DATABASE.md     # reason: no schema change
+  
+  skills:
+    loaded: [typescript, node, postgres, testing]
+    skipped: [react, tailwind]  # reason: backend task
+  
+  project_graph:
+    module: appointments
+    dependencies: [auth, patients]
+    affected_files:
+      - src/modules/appointments/api/**
+      - src/modules/appointments/services/**
+```
+
+### Step 5: Validate Budget
+
+Check total token count. If over budget (see context-rules.md):
+
+1. Trim Level 1 docs to summaries
+2. Load only affected sections of Level 2 docs
+3. Keep Level 3 (skills) at full detail
+
+## Context Caching
+
+After first compilation for a module, cache the result:
+
+```
+.cache/
+  frontend.context.yaml
+  backend.context.yaml
+  appointments.context.yaml
+```
+
+Invalidate cache when:
+
+- A document is updated
+- A skill is added/removed
+- The Project Graph changes
+- A Decision Record is added
+
+## Questions the Context Manager Can Answer
+
+- "What documents do I need for this task?"
+- "Which skills should be loaded?"
+- "What modules are affected by this change?"
+- "Is this context package within budget?"
+- "Why was this document skipped?"
+
+
+## Code Examples
+
+See `EXAMPLES.md` for detailed code examples.
+
+## Validation Checklist
+
+What to verify during the review phase before completing the task.
+
+## Common Mistakes
+
+Anti-patterns and things to explicitly avoid. See `TROUBLESHOOTING.md`.
+
+## Integration Notes
+
+How this skill interacts with other skills.
+
+
+<!-- Source: EXAMPLES.md -->
+
+# context-manager Examples — Anti-patterns vs ContextOS Standard
+
+## Example 1: Context Selection
+
+### Anti-pattern: Context Window Dumping
+
+```text
+Agent reads all 180 files in src/ into context to debug a single button click handler.
+Result: Exhausts 150k tokens, reaches rate limits, and forgets user instructions.
+```
+
+### Best practice: ContextOS Standard (Targeted AST Traversal)
+
+```text
+1. Inspect package.json and AGENTS.md.
+2. Grep for target symbol: grep_search for 'SubmitButton'.
+3. Read ONLY components/SubmitButton.tsx and its direct import types/button.ts.
+Total tokens used: <1,500 tokens. Fast, accurate, zero hallucinations.
+```
+
+<!-- Source: TROUBLESHOOTING.md -->
+
+# context-manager Troubleshooting & Common Mistakes
+
+## 1. Token Budget Blowout
+
+- **Symptom**: Model performance drops significantly, losing earlier conversational context.
+- **Root Cause**: Loading large JSON mocks, lockfiles, or build directories into prompt.
+- **Fix**: Never read package-lock.json, dist/, or build artifacts unless explicitly debugging bundle outputs.

package/.agents/generated/gemini/skills/context-os/SKILL.md

@@ -0,0 +1,200 @@
+---
+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.
+---
+# context-os
+
+## Overview
+
+Operating system and context orchestration layer for AI coding assistants. Standardizes software engineering workflows across requirements, architecture, atomic task planning, implementation, verification, and release.
+
+## When to Use
+
+Activate as the root meta-orchestrator across all development phases to ensure role consistency, quality gates, and structured execution.
+
+## Rules & Patterns
+
+You are the **Context Compiler**. Your job is NOT to know everything. Your job is to **assemble the minimum context** needed for the current task.
+
+## Pipeline
+
+When a user gives you a task, follow this pipeline:
+
+### Stage 1: Intent Analysis
+
+Analyze the user's prompt and determine:
+
+```yaml
+intent:
+  project_type: [webapp, api, mobile, cli, library, saas, crm, ecommerce]
+  industry: [healthcare, fintech, education, social, general]
+  layers:
+    frontend: true/false
+    backend: true/false
+    database: true/false
+    auth: true/false
+    ai: true/false
+    payments: true/false
+    realtime: true/false
+  scope: [new_project, feature, bugfix, refactor, architecture]
+```
+
+### Stage 2: Dependency Resolution
+
+For each required layer, load the skill graph:
+
+1. Read `skill.yaml` from each relevant skill directory
+2. Resolve `requires` — load mandatory dependencies
+3. Check `conflicts` — ensure no incompatible skills are loaded
+4. Apply `optional` — suggest but don't force
+5. Respect project profile (if set) — apply rules from `profiles/`
+
+**Dependency resolution example:**
+
+```
+Need: nextjs
+  → requires: react, typescript
+    → react requires: typescript (already loaded)
+  → optional: tailwind, prisma, next-auth
+  
+Loaded: [nextjs, react, typescript]
+Suggested: [tailwind, prisma, next-auth]
+```
+
+### Stage 3: Context Compilation
+
+Assemble context from three levels:
+
+**Level 1 — Vision (always available):**
+
+- `docs/PRD.md` — what are we building
+- `docs/ROADMAP.md` — where are we going
+- `docs/PROJECT_GRAPH.md` — project structure
+
+**Level 2 — Architecture (load when needed):**
+
+- `docs/ARCHITECTURE.md` — system design
+- `docs/DATABASE.md` — data model
+- `docs/API.md` — API contracts
+- `docs/decisions/` — prior decisions
+
+**Level 3 — Development (load per task):**
+
+- Relevant skill `.md` files
+- `docs/UI.md` — for frontend tasks
+- `docs/TASKS.md` — current sprint
+
+**Context Filtering Rules:**
+See `references/context-rules.md` for the full mapping of task types to required documents.
+
+### Stage 4: Prompt Optimization
+
+Before sending to the AI agent:
+
+1. Remove sections not relevant to the current task
+2. Prioritize: current task context > architecture > vision
+3. Include recent Decision Records that affect the current task
+4. Add coding rules from the loaded skills
+
+## Commands
+
+| Command | Action |
+| --- | --- |
+| `ctx init` | Analyze project idea, generate all docs |
+| `ctx plan` | Generate development plan from PRD |
+| `ctx compile` | Compile context for a specific task |
+| `ctx update` | Update changed documents |
+| `ctx graph` | Show/update Project Graph |
+| `ctx doctor` | Validate skill dependencies, check for conflicts |
+| `ctx explain` | Explain why specific context was loaded |
+
+## Project Initialization Flow
+
+When user says something like "Сделай CRM для стоматологии" or "Build a Trello clone":
+
+1. **Analyze intent** (Stage 1)
+2. **Ask clarifying questions:**
+   - Users and roles?
+   - Tech stack preference?
+   - Mobile app needed?
+   - AI features?
+   - Authentication type?
+   - Expected load?
+   - MVP or Production?
+3. **Select profile** (startup/enterprise/mvp/hackathon)
+4. **Resolve skills** (Stage 2)
+5. **Generate all documents** using `generators/` skill
+6. **Create Project Graph** — the master map of modules → features → tasks → files → skills
+7. **Output agent config** using `adapters/` skill
+
+## Skill Discovery
+
+Skills are discovered by scanning `.agents/skills/*/skill.yaml`. Each `skill.yaml` defines:
+
+```yaml
+id: react
+name: React
+category: frontend
+tags: [frontend, spa, jsx, components]
+requires: [typescript]
+optional: [tailwind, next-auth, react-query]
+conflicts: [vue, angular, svelte]
+weight: 8
+documents:
+  - react.md
+```
+
+The compiler builds a dependency graph from all discovered skills and resolves it for each task.
+
+
+## Code Examples
+
+See `EXAMPLES.md` for detailed code examples.
+
+## Validation Checklist
+
+What to verify during the review phase before completing the task.
+
+## Common Mistakes
+
+Anti-patterns and things to explicitly avoid. See `TROUBLESHOOTING.md`.
+
+## Integration Notes
+
+How this skill interacts with other skills.
+
+
+<!-- Source: EXAMPLES.md -->
+
+# context-os Examples — Anti-patterns vs ContextOS Standard
+
+## Example 1: Project Lifecycle Management
+
+### Anti-pattern: Ad-hoc Unstructured Development
+
+```text
+Coding -> Modifying DB -> Debugging -> Redesigning UI -> Changing Architecture
+All in one unstructured stream of consciousness.
+```
+
+### Best practice: ContextOS Standard (Phase-Gated Development)
+
+```text
+Phase 1: DEFINE (PRD & Requirements)
+Phase 2: PLAN (Atomic Tasks & ADRs)
+Phase 3: BUILD (TDD & Minimalist Implementation)
+Phase 4: VERIFY (Automated Test Proof)
+Phase 5: REVIEW (Design QA & Code Review)
+Phase 6: SHIP (Production Release)
+```
+
+<!-- Source: TROUBLESHOOTING.md -->
+
+# context-os Troubleshooting & Common Mistakes
+
+## 1. Stale Compiled Artifacts
+
+- **Symptom**: Editor rules don't reflect newly updated skills.
+- **Root Cause**: Modifying .agents/core/skills/ without recompiling exports.
+- **Fix**: Run node .agents/ctx.js export all whenever source skills are updated.

package/.agents/generated/gemini/skills/database/SKILL.md

@@ -0,0 +1,200 @@
+---
+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).
+
+
+<!-- Source: EXAMPLES.md -->
+
+# 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);
+    }
+  });
+}
+```
+
+<!-- Source: TROUBLESHOOTING.md -->
+
+# 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.