contextos-agents 2.2.0 → 2.3.0

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

@@ -155,34 +155,3 @@ Anti-patterns and things to explicitly avoid. See `TROUBLESHOOTING.md`.
 ## Integration Notes
 
 How this skill interacts with other skills.
-
-
-# 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)
-```
-
-# 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/claude/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/claude/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/claude/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/claude/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/claude/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/claude/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/generated/claude/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/generated/claude/skills/engineering-workflow/EXAMPLES.md

@@ -0,0 +1,57 @@
+# engineering-workflow Examples — Anti-patterns vs ContextOS Standard
+
+## Example 1: Handling a New Feature Request
+
+### Anti-pattern: Jumping Straight to Code
+
+```text
+User: "Add a user referral system."
+Agent: Immediately creates src/referral.js, starts writing database queries, guesses schema,
+and misses requirements like rate limiting, expiry dates, and fraud prevention.
+```
+
+### Best practice: ContextOS Standard (DEFINE -> PLAN -> BUILD)
+
+```markdown
+[DOMAIN: Full-Stack] [PHASE: Define] [ROLE: Product Manager]
+Skills loaded: engineering-workflow, interview-me
+
+## Feature Spec: User Referral System
+### Why (Problem)
+Increase user acquisition through organic word-of-mouth incentives.
+
+### Scope
+In-Scope:
+- Unique referral code generation per registered user
+- Referral code attribution on signup
+- Credit reward trigger after first completed purchase
+Out-of-Scope:
+- Multi-tier MLM rewards
+- Cash payout integrations
+
+### Acceptance Criteria
+- [ ] Given a registered user, when visiting /referrals, then unique code is displayed.
+- [ ] Given a new user with code, when signing up, then referrer_id is stored with status 'pending'.
+```
+
+---
+
+## Example 2: Atomic Task Execution in PLAN Phase
+
+### Anti-pattern: Monolithic Mega-Task
+
+```text
+Task: "Implement entire referral system end-to-end in one shot."
+Result: 15 files modified simultaneously, uncompilable intermediate state, untestable diff.
+```
+
+### Best practice: ContextOS Standard (Atomic Tasks with Test Gate)
+
+```markdown
+[DOMAIN: Full-Stack] [PHASE: Plan] [ROLE: Architect]
+Atomic Tasks:
+1. Database migration: referrals and referral_rewards tables + indexes. (Test: Migration rollback & apply)
+2. Domain service: ReferralService.createCode() and ReferralService.claimCode(). (Test: Unit tests)
+3. API route: POST /api/referrals/claim with Zod validation. (Test: Supertest integration)
+4. UI component: <ReferralCard /> with copy button. (Test: RTL component test)
+```