contextos-agents 1.7.0 → 2.0.0-beta.2

package/.agents/generated/claude/skills/fastapi/SKILL.md

@@ -1,200 +0,0 @@
-# FastAPI
-
-## Overview
-
-High-performance Python backend engineering using FastAPI, Pydantic v2, and async SQLAlchemy/Tortoise ORM. Enforces type-driven request validation, OpenAPI contracts, and async non-blocking endpoints.
-
-## When to Use
-
-Activate when building Python REST APIs, microservices, asynchronous background jobs, or integrating Python ML services into web backends.
-
-## Rules & Patterns
-<!-- Source: fastapi.md -->
-
-## FastAPI — Best Practices
-
-## Project Structure
-
-```
-app/
-├── main.py              # App entry, CORS, middleware
-├── config.py            # Settings with Pydantic BaseSettings
-├── database.py          # Database session, engine
-├── models/              # SQLAlchemy models
-│   ├── __init__.py
-│   └── user.py
-├── schemas/             # Pydantic schemas (request/response)
-│   ├── __init__.py
-│   └── user.py
-├── api/                 # Route handlers
-│   ├── __init__.py
-│   ├── deps.py          # Dependency injection
-│   └── v1/
-│       ├── __init__.py
-│       └── users.py
-├── services/            # Business logic
-│   └── user_service.py
-├── repositories/        # Database access
-│   └── user_repo.py
-└── tests/
-    └── test_users.py
-```
-
-## Pydantic Models
-
-```python
-from pydantic import BaseModel, EmailStr, Field
-
-class UserCreate(BaseModel):
-    email: EmailStr
-    name: str = Field(..., min_length=1, max_length=100)
-    
-class UserResponse(BaseModel):
-    id: int
-    email: str
-    name: str
-    
-    model_config = ConfigDict(from_attributes=True)
-```
-
-## Dependency Injection
-
-```python
-from fastapi import Depends
-from sqlalchemy.ext.asyncio import AsyncSession
-
-async def get_db() -> AsyncGenerator[AsyncSession, None]:
-    async with async_session() as session:
-        yield session
-
-async def get_current_user(
-    token: str = Depends(oauth2_scheme),
-    db: AsyncSession = Depends(get_db)
-) -> User:
-    # Verify token, return user
-    ...
-```
-
-## Async
-
-- **Use async** for all I/O operations (database, HTTP calls, file I/O)
-- **Never block the event loop** — no sync I/O in async endpoints
-- **Use `asyncio.gather`** for parallel async operations
-- **Background tasks** — `BackgroundTasks` for non-critical work
-
-## Error Handling
-
-```python
-from fastapi import HTTPException
-
-class AppException(HTTPException):
-    def __init__(self, status_code: int, detail: str, code: str):
-        super().__init__(status_code=status_code, detail=detail)
-        self.code = code
-```
-
-## Security
-
-- **OAuth2 with JWT** — use `python-jose`
-- **Password hashing** — bcrypt via `passlib`
-- **CORS** — configure explicitly
-- **Rate limiting** — use `slowapi`
-- **Input validation** — Pydantic handles this automatically
-
-## Testing
-
-```python
-import pytest
-from httpx import AsyncClient
-
-@pytest.mark.asyncio
-async def test_create_user(client: AsyncClient):
-    response = await client.post("/api/v1/users", json={
-        "email": "test@example.com",
-        "name": "Test User"
-    })
-    assert response.status_code == 201
-```
-
-## Anti-Patterns
-
-- [FAIL] Business logic in route handlers — use services
-- [FAIL] Raw SQL without ORM — use SQLAlchemy
-- [FAIL] Sync database calls — use async drivers
-- [FAIL] Hardcoded settings — use Pydantic BaseSettings
-- [FAIL] No schema validation — always use Pydantic models
-
-
-## 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.
-
-
-# fastapi Examples — Anti-patterns vs ContextOS Standard
-
-## Example 1: Asynchronous Route Handlers
-
-### Anti-pattern: Blocking I/O inside `async def`
-
-```python
-# BAD: time.sleep or synchronous requests blocks the entire asyncio event loop!
-import time
-import requests
-
-@app.get("/slow")
-async def slow_route():
-    time.sleep(5)  # BLOCKS ALL CONCURRENT USERS!
-    return {"status": "done"}
-```
-
-### Best practice: ContextOS Standard (Non-blocking Async or Def Offload)
-
-```python
-# GOOD: Use async non-blocking client (httpx) or standard def for sync CPU work
-import asyncio
-import httpx
-
-@app.get("/fast")
-async def fast_route():
-    async with httpx.AsyncClient() as client:
-        response = await client.get("https://api.example.com/data")
-    return response.json()
-
-# Or standard def (FastAPI automatically runs it in a background threadpool):
-@app.get("/sync-worker")
-def sync_worker():
-    time.sleep(5)  # Runs in worker thread without blocking event loop
-    return {"status": "done"}
-```
-
-# fastapi Troubleshooting & Common Mistakes
-
-## 1. Pydantic v1 vs v2 Deprecations
-
-- **Symptom**: Warnings or crashes regarding @validator or .dict() methods.
-- **Root Cause**: FastAPI projects upgrading to Pydantic v2.
-- **Fix**: Use @field_validator instead of @validator, and .model_dump() instead of .dict().
-
-## 2. Database Session Leaks
-
-- **Symptom**: Database pool runs out of connections after a few requests.
-- **Root Cause**: Database sessions opened manually without proper try...finally or dependency injection.
-- **Fix**: Always provide database sessions via Depends(get_db) with a yield block.
-
-## 3. Unhandled Validation Errors Returning Inconsistent JSON
-
-- **Symptom**: Frontend receives raw 422 arrays without matching standard API error response envelope.
-- **Root Cause**: Missing custom RequestValidationError handler.
-- **Fix**: Register an app-level exception handler for RequestValidationError that normalizes error shapes.

package/.agents/generated/claude/skills/generators/SKILL.md

@@ -1,133 +0,0 @@
-# document-generator
-
-## Overview
-
-Automated technical documentation generator. Transforms initial project ideas and specs into comprehensive PRDs, architecture schemas, API contracts, database ERDs, and roadmap task breakdowns.
-
-## When to Use
-
-Activate during project kickoff (ctx init), new service scaffolding, or when generating baseline technical specs from high-level user requirements.
-
-## Rules & Patterns
-
-You generate project documentation from a user's idea. Use the templates in `templates/` as the structure for each document.
-
-## Commands
-
-### `ctx init`
-
-Full project initialization. From one user prompt, generate ALL documents:
-
-1. Ask clarifying questions (see Context OS SKILL.md)
-2. Select profile and skill pack
-3. Generate documents in this order:
-   - `docs/PRD.md` — Product Requirements (from template)
-   - `docs/ARCHITECTURE.md` — System Architecture
-   - `docs/DATABASE.md` — Database Schema
-   - `docs/API.md` — API Specification
-   - `docs/UI.md` — UI/UX Specification
-   - `docs/ROADMAP.md` — Development Roadmap
-   - `docs/TASKS.md` — Task Breakdown
-   - `docs/PROJECT_GRAPH.md` — Project Graph
-4. Create `docs/decisions/` directory for future ADRs
-5. Generate agent config via Adapters skill
-
-### `ctx update`
-
-Incremental update. When requirements change:
-
-1. Identify which documents are affected
-2. Update only affected documents
-3. Show diff of changes
-4. Ask user to confirm
-5. Update Project Graph if structure changed
-
-### `ctx plan`
-
-Generate development plan from existing PRD:
-
-1. Read `docs/PRD.md`
-2. Break into modules (Project Graph)
-3. Break modules into features
-4. Break features into tasks
-5. Estimate complexity (S/M/L/XL)
-6. Output to `docs/TASKS.md`
-
-## Template Usage
-
-Each template contains:
-
-- **Section headers** — required sections for the document
-- **Placeholder prompts** — `{{description}}` markers that guide content generation
-- **Examples** — sample content to illustrate the expected format
-- **Validation rules** — what must be present for the document to be valid
-
-When generating a document:
-
-1. Read the template
-2. Fill in each section based on the user's idea and clarifying answers
-3. Replace all `{{placeholders}}` with real content
-4. Remove the template comments (lines starting with `<!-- -->`)
-5. Validate: ensure all required sections are present
-
-## Document Dependencies
-
-```
-PRD.md
-  ├── ARCHITECTURE.md
-  │     ├── DATABASE.md
-  │     ├── API.md
-  │     └── DEPLOYMENT.md
-  ├── UI.md
-  ├── ROADMAP.md
-  │     └── TASKS.md
-  └── PROJECT_GRAPH.md
-```
-
-When updating a parent document, check if child documents need updates too.
-
-
-## 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.
-
-
-# generators Examples — Anti-patterns vs ContextOS Standard
-
-## Example 1: Technical Documentation Generation
-
-### Anti-pattern: Scaffolding from Scratch Without Templates
-
-```text
-Agent drafts a 2-paragraph "architecture overview" missing databases, security, and hosting models.
-```
-
-### Best practice: ContextOS Standard (ctx init Template Generation)
-
-```text
-Generates complete engineering suite:
-- PRD.md (User personas, in-scope, out-of-scope, acceptance criteria)
-- ARCHITECTURE.md (C4 model, data flow, scaling boundaries)
-- DATABASE.md (ERD, indexing strategy, migration plans)
-- API.md (OpenAPI 3.1 endpoints, error codes, authentication)
-```
-
-# generators Troubleshooting & Common Mistakes
-
-## 1. Generic Boilerplate Generation
-
-- **Symptom**: Generated documentation contains placeholders like [Insert DB Name here].
-- **Root Cause**: Generating docs before clarifying core project constraints.
-- **Fix**: Run the interview-me protocol before generating technical documentation.

package/.agents/generated/claude/skills/graphify/SKILL.md

@@ -1,198 +0,0 @@
-# graphify
-
-## Overview
-
-**Graphify** is an instruction-only codebase mapping and context optimization guide. Instead of feeding raw directory trees or entire source files into an agent's context window, Graphify instructs agents on how to construct a deterministic, queryable knowledge graph (`graph.json`, `GRAPH_REPORT.md`, `graph.html`) using external companion analyzers (such as the TypeScript AST analyzer in `contextos-mcp` or the external `graphifyy` CLI), keeping the core package 100% zero-dependency without bundled native Tree-sitter binaries.
-
-This skill instructs agents how to build, query, and maintain codebase graphs to navigate complex architectures with near-zero token overhead.
-
-## When to Use
-
-Activate whenever:
-
-- Working in large repositories (10k+ LOC) where full-file reads cause context overflow.
-- Performing cross-module refactorings and needing to determine exact dependency **blast radius**.
-- Onboarding onto an unfamiliar codebase or mapping legacy service boundaries.
-- The user asks to "map the codebase", "show dependency graph", "find central components", or "run graphify".
-- Working alongside `context-manager` to supply an automated `PROJECT_GRAPH.md` / `graph.json`.
-
-## Rules & Patterns
-
-### 1. The Graph-First Navigation Protocol
-
-Before opening and reading arbitrary source files in a large project:
-
-1. **Check for Existing Artifacts**:
-   - Inspect if `graph.json` or `GRAPH_REPORT.md` exists in the project root or `.graphify/`.
-   - If present, query `graph.json` or read `GRAPH_REPORT.md` first to locate target modules.
-2. **Deterministic CLI Execution**:
-   - If missing or stale, generate the graph using the Python package (`pip install graphifyy`):
-
-     ```bash
-     graphify run .
-     ```
-
-   - For live development sessions, run in watch mode:
-
-     ```bash
-     graphify watch .
-     ```
-
-3. **Inspect God Nodes**:
-   - Always check the "God Nodes" section of `GRAPH_REPORT.md`. These represent high-centrality modules (e.g., core configs, base models, central dispatchers). Changes to god nodes have the highest blast radius.
-
-### 2. Context Safety Rules
-
-- **Never load `graph.html` into agent context**: `graph.html` is an interactive visualization for humans in the browser; reading it burns tokens needlessly.
-- **Selective JSON Querying**: Do not dump the entire `graph.json` into prompt context if it exceeds 50KB. Use targeted grep/jq queries to extract specific node neighbors.
-- **Git Hygiene**: Add `graph.html` and `.graphify/cache` to `.gitignore`. Keep `GRAPH_REPORT.md` committed only if the team uses it as shared documentation.
-
-### 3. Blast Radius Verification
-
-When modifying a function, class, or interface:
-
-1. Locate the symbol's node in `graph.json`.
-2. Extract all inbound edges (`dependents` / `callers`).
-3. Formulate the verification plan specifically around those dependent call sites.
-
----
-
-## Code Examples
-
-### Installing and Running Graphify
-
-```bash
-# Install graphify CLI (package name is graphifyy on PyPI)
-pip install graphifyy
-
-# Generate knowledge graph and markdown architectural report
-graphify run ./src --output .graphify/
-
-# View interactive visualization locally
-open .graphify/graph.html
-```
-
-### Querying Node Dependencies via Shell
-
-```bash
-# Find dependents of a critical module in graph.json without loading entire file
-node -e "
-const g = require('./.graphify/graph.json');
-const target = 'UserService';
-const inbound = g.edges.filter(e => e.target === target).map(e => e.source);
-console.log('Modules dependent on ' + target + ':', inbound);
-"
-```
-
-### Git Pre-Commit Hook Integration
-
-```bash
-#!/bin/sh
-# .git/hooks/pre-commit: ensure GRAPH_REPORT.md remains fresh
-if command -v graphify >/dev/null 2>&1; then
-  graphify run . --report-only
-  git add GRAPH_REPORT.md
-fi
-```
-
----
-
-## Validation Checklist
-
-- [ ] `graph.json` and `GRAPH_REPORT.md` are generated without syntax errors.
-- [ ] Central "God Nodes" are identified and accounted for in the implementation plan.
-- [ ] No heavy visualization artifacts (`graph.html`, raw SVG dumps) are ingested into agent prompt context.
-- [ ] Inbound dependencies (callers) are checked before modifying exported signatures.
-- [ ] `.gitignore` properly excludes local graph caches and visualization outputs.
-
----
-
-## Common Mistakes
-
-- **Context Window Flooding**: Ingesting the complete `graph.json` of a 500k LOC repository into agent context instead of slicing target subgraphs.
-- **Stale Graph Fallacy**: Assuming `graph.json` is up to date after heavy code refactorings without re-running `graphify run` or using `--watch`.
-- **Ignoring Semantic Non-Code Files**: Neglecting SQL migrations, OpenAPI specs, and docker configs during graph extraction.
-- **Mistaking Package Name**: Trying to install `pip install graphify` instead of the official PyPI package `graphifyy`.
-
----
-
-## Integration Notes
-
-- **Synergy with `context-manager`**: Graphify serves as the automated backend engine for `context-manager`. Instead of manually maintaining `docs/PROJECT_GRAPH.md`, run Graphify to keep `graph.json` current.
-- **Synergy with `system-design`**: Use `GRAPH_REPORT.md` to ground architectural proposals in actual codebase topology.
-- **Synergy with `architecture-diagrams`**: The nodes and edges extracted in `graph.json` can be directly mapped into animated SVG C4 architecture diagrams.
-
-
-# Graphify Examples — Anti-patterns vs ContextOS Standard
-
-## Example 1: Codebase Exploration & Architecture Mapping
-
-### Anti-pattern: Context Window Flooding (Dumping source directories into prompt)
-
-```bash
-# BAD: Reading 150 TypeScript files into context to understand system architecture.
-# Burns 200k+ tokens, causes model hallucinations, and loses attention span.
-cat src/**/*.ts | llm "explain the architecture and component connections"
-```
-
-### Best practice: ContextOS Standard (Deterministic Tree-sitter AST Graph)
-
-```bash
-# GOOD: Generate queryable AST knowledge graph and compact architecture summary
-graphify run ./src --output .graphify/
-
-# Inspect high-level architecture and god nodes with minimal tokens (<2k tokens)
-cat .graphify/GRAPH_REPORT.md
-```
-
----
-
-## Example 2: Refactoring Blast-Radius Analysis
-
-### Anti-pattern: String Grep Guesswork
-
-```bash
-# BAD: Grepping for common symbol names returns hundreds of false positives (comments, logs, unrelated types)
-grep -rn "PaymentService" src/
-```
-
-### Best practice: ContextOS Standard (Inbound Dependency Traversal via graph.json)
-
-```javascript
-// GOOD: Precise AST-level callers extracted directly from knowledge graph edges
-const fs = require('fs');
-const graph = JSON.parse(fs.readFileSync('.graphify/graph.json', 'utf8'));
-
-const targetNode = 'PaymentService';
-const dependents = graph.edges
-  .filter(edge => edge.target === targetNode && edge.type === 'imports')
-  .map(edge => edge.source);
-
-console.log(`Modules directly broken by modifying ${targetNode}:`, dependents);
-```
-
----
-
-## Example 3: Keeping Graph Fresh in CI / Pre-commit
-
-### Anti-pattern: Relying on Outdated Graphs
-
-```bash
-# BAD: Developing against a graph generated two months ago.
-# Dependencies drift, leading to false safety assumptions.
-```
-
-### Best practice: ContextOS Standard (Git Hook & Automated Watch)
-
-```bash
-# Option A: Active development in watch mode
-graphify watch ./src --output .graphify/
-
-# Option B: Pre-commit hook to verify fresh GRAPH_REPORT.md
-#!/bin/sh
-# .git/hooks/pre-commit
-if command -v graphify >/dev/null 2>&1; then
-  graphify run ./src --report-only
-  git add GRAPH_REPORT.md
-fi
-```