contextos-agents 2.2.0 → 2.3.1

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

@@ -0,0 +1,19 @@
+# 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.
+```

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

@@ -2,6 +2,7 @@
 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
 
@@ -121,36 +122,3 @@ 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-manager/TROUBLESHOOTING.md

@@ -0,0 +1,7 @@
+# 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-manager/VALIDATION.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "rules_followed": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "rules_followed"
+  ]
+}

package/.agents/generated/gemini/skills/context-manager/references/context-rules.md

@@ -0,0 +1,59 @@
+# Context Loading Rules
+
+Guidelines and deterministic decision tables for selecting, prioritizing, and budgeting context during AI agent execution.
+
+## Task Type to 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 to 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 Budgeting
+
+To prevent context window saturation and retain maximum LLM reasoning capacity, adhere strictly to the following 4-tier token budget:
+
+| Priority Level | Max Tokens | Contents |
+| --- | --- | --- |
+| 1 (Critical) | 2,000 | Current task description, active brief, and primary skill rules |
+| 2 (Important) | 3,000 | System architecture and API contracts for affected modules |
+| 3 (Context) | 2,000 | Architectural Decision Records (ADRs) and relevant graph nodes |
+| 4 (Background) | 1,000 | PRD summary and global project conventions |
+
+**Total target context budget: ~8,000 tokens per subtask.**
+
+### Degradation Strategy When Over Budget
+
+If accumulated context exceeds the 8,000 token limit:
+
+1. **Trim Level 1 documents** to high-level executive summaries.
+2. **Slice Level 2 documents** to extract only sections matching touched module signatures.
+3. **Preserve Level 3 skills** at full fidelity, as they contain non-negotiable operational instructions and validation guardrails.
+
+## Module-Based Filtering via Dependency Graph
+
+When `PROJECT_GRAPH.md` or `.graphify/graph.json` is present, traverse dependency edges to filter candidate documents:
+
+1. Identify the primary module for the task from the symbol/path mapping.
+2. Resolve immediate inbound and outbound dependencies (`dependencies` and `dependents`).
+3. Include documents solely for the identified module and its immediate dependencies.
+4. Exclude orthogonal domain documents (for example, omit database schemas during purely presentation-layer CSS/layout tasks).

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

@@ -0,0 +1,21 @@
+# 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)
+```

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

@@ -160,38 +160,3 @@ 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/context-os/TROUBLESHOOTING.md

@@ -0,0 +1,7 @@
+# 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/context-os/VALIDATION.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "rules_followed": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "rules_followed"
+  ]
+}

package/.agents/generated/gemini/skills/context-os/packs.yaml

@@ -0,0 +1,59 @@
+# Skill Packs — pre-configured skill bundles
+# Users select a pack instead of individual skills
+
+packs:
+  fullstack-next:
+    name: "Next.js Full-Stack"
+    description: "Full-stack web app with Next.js, React, TypeScript, Tailwind, Prisma"
+    skills: [nextjs, react, typescript, tailwind, prisma, testing, security]
+    profile: startup
+    generates: [PRD, ARCHITECTURE, DATABASE, API, UI, TASKS, PROJECT_GRAPH]
+
+  fastapi-backend:
+    name: "FastAPI Backend"
+    description: "Python backend with FastAPI, PostgreSQL, Docker"
+    skills: [fastapi, python, pydantic, postgres, docker, testing, security, rest]
+    profile: startup
+    generates: [PRD, ARCHITECTURE, DATABASE, API, TASKS, PROJECT_GRAPH]
+
+  react-spa:
+    name: "React SPA"
+    description: "Single Page Application with React, TypeScript, Tailwind"
+    skills: [react, typescript, tailwind, performance, web-accessibility, testing]
+    profile: startup
+    generates: [PRD, ARCHITECTURE, API, UI, TASKS, PROJECT_GRAPH]
+
+  nestjs-enterprise:
+    name: "NestJS Enterprise"
+    description: "Enterprise-grade Node.js backend with NestJS, DDD, full testing"
+    skills: [nestjs, typescript, node, postgres, ddd, security, testing, cicd, docker]
+    profile: enterprise
+    generates: [PRD, ARCHITECTURE, DATABASE, API, TASKS, ROADMAP, PROJECT_GRAPH]
+
+  design-system:
+    name: "Design System"
+    description: "UI/UX design system with accessibility and performance"
+    skills: [ui-design, ux-design, web-accessibility, performance]
+    profile: startup
+    generates: [PRD, UI, TASKS]
+
+  mobile-react-native:
+    name: "React Native Mobile"
+    description: "Cross-platform mobile app with React Native"
+    skills: [react, typescript, react-native, performance, web-accessibility]
+    profile: startup
+    generates: [PRD, ARCHITECTURE, API, UI, TASKS, PROJECT_GRAPH]
+
+  hackathon-fast:
+    name: "Hackathon Quick Start"
+    description: "Fastest possible setup — SQLite, minimal architecture"
+    skills: [react, typescript, node, sqlite]
+    profile: hackathon
+    generates: [TASKS, PROJECT_GRAPH]
+
+  ai-saas:
+    name: "AI SaaS Platform"
+    description: "SaaS with AI features, auth, payments, analytics"
+    skills: [nextjs, react, typescript, tailwind, prisma, security, stripe, openai]
+    profile: startup
+    generates: [PRD, ARCHITECTURE, DATABASE, API, UI, ROADMAP, TASKS, PROJECT_GRAPH]

package/.agents/generated/gemini/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/generated/gemini/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/generated/gemini/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"