contextos-agents 1.5.0

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

@@ -0,0 +1,148 @@
+---
+name: FastAPI
+description: >
+  ContextOS skill for FastAPI
+---
+
+# 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.

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

@@ -0,0 +1,19 @@
+# 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/core/skills/fastapi/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/core/skills/fastapi/fastapi.md

@@ -0,0 +1,112 @@
+# 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

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

@@ -0,0 +1,10 @@
+id: fastapi
+name: FastAPI
+category: backend
+tags: [backend, python, api, async, pydantic]
+requires: []
+optional: [postgres, redis, docker]
+conflicts: [nestjs, express]
+weight: 8
+documents:
+  - fastapi.md

package/.agents/core/skills/gemini-precision/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: gemini-precision
+description: >
+  High-precision engineering and execution guardrails optimized for Google Gemini models.
+  Enforces zero-assumption file inspection, complete non-lazy implementations, surgical
+  blast-radius containment, and mandatory proof-of-work execution.
+---
+
+# gemini-precision
+
+## Overview
+
+High-precision operational standard designed specifically to harness the high speed and expansive context window of Google Gemini models while eliminating common LLM failure modes: hasty assumptions, partial code placeholders (`// ...`), unverified assertions, and scope creep.
+
+## When to Use
+
+Activate whenever:
+
+- Executing non-trivial code modifications, refactoring, bug fixes, or architecture design.
+- The user requires maximum rigor, reliability, and precision from Gemini.
+- Handling complex multi-file changes where accidental side-effects must be zero.
+
+## Rules & Patterns
+
+### 1. The Read-Before-Write Invariant (Zero Assumptions)
+
+**Never write code based on assumptions about the codebase.**
+
+- Before modifying a function or creating an integration, **always inspect the actual files** using `view_file` or `grep_search`.
+- Check the exact runtime, framework version, and installed dependencies (e.g. React 19 vs 18, Next.js 15 vs 14, Tailwind v4 vs v3, Zod vs Joi) in `package.json` or config files before generating code.
+- Verify imported symbol names and parameter signatures directly from source files.
+
+### 2. The Zero-Placeholder Invariant (Complete Code Only)
+
+**Never produce lazy, incomplete, or stubbed output.**
+
+- ❌ **Forbidden**:
+  - `// TODO: implement logic here`
+  - `// ... rest of existing code ...`
+  - `// ... existing imports ...`
+  - Mock stub returns when real integration is required
+- ✅ **Mandatory**:
+  - Provide **100% complete, fully-implemented, compilable, and drop-in ready** code.
+  - When replacing a block of code, include all necessary imports, type definitions, and edge-case handling.
+
+### 3. The Proof-of-Work Invariant (Verification Before Completion)
+
+**Never claim a task is complete without tool-verified evidence.**
+
+- When modifying code or configuration:
+  1. Run the project validator or compiler (`node .agents/ctx.js validate`, `tsc --noEmit`, etc.).
+  2. Run unit and integration tests (`npm test`, `pytest`, etc.).
+  3. Run linter and formatting checks (`npm run lint:md`, `eslint`, etc.).
+- If a test or validation fails, do not guess: read the exact error trace, fix the root cause, and re-run until green.
+
+### 4. Surgical Blast Radius Containment
+
+**Modify ONLY what is strictly necessary.**
+
+- Keep edits isolated to the exact lines, functions, and files specified in the plan.
+- Do not reformat, reorder, or alter indentation of unrelated code blocks.
+- Preserve existing comments, docstrings, and project conventions unless explicitly asked to change them.
+
+### 5. Ponytail Minimalism (YAGNI)
+
+- Prioritize native platform APIs (standard library, browser built-ins) over new npm/pip packages.
+- Follow the "Rule of Three": inline on first use, duplicate cleanly on second, abstract only on third.
+- Keep solutions obvious to a mid-level developer without requiring multi-layered wrapper classes.
+
+### 6. Targeted Tool-Specific Modifications
+
+**Prevent accidental code loss during file updates.**
+
+- For existing files requiring localized updates (< 50% change), always prefer surgical targeted replacement chunks over destructive full-file rewrites.
+- Never discard unrelated file sections, existing comments, or helper utilities.
+
+### 7. Persistent Context & Plan Tracking
+
+**Prevent context drift during multi-step tasks.**
+
+- When an operation requires more than 3 sequential steps, write and maintain a persistent plan or checklist on disk.
+- Never rely exclusively on volatile conversational memory for tracking complex multi-file refactorings.
+
+### 8. Progressive Step Narration (Transparent Pair Programming)
+
+**Eliminate the "black box" by narrating technical decisions.**
+
+- Avoid executing long, silent chains of tool calls without user visibility.
+- Provide a concise 1–2 sentence transparent status update before key operations:
+  - State what was inspected or verified from the code.
+  - State the architectural decision made and the immediate next action.
+- Keep narration crisp and actionable without excessive verbosity.
+
+---
+
+## Code Examples
+
+### Bad (Lazy Model Output) vs Good (Precision Model Output)
+
+**❌ Bad (Lazy AI Output)**:
+
+```javascript
+// user.service.js
+export async function updateUser(id, data) {
+  // ... existing auth check ...
+  // TODO: validate data with zod
+  return await db.user.update({ where: { id }, data });
+}
+```
+
+**✅ Good (Gemini Precision Output)**:
+
+```javascript
+// user.service.js
+import { z } from 'zod';
+import { db } from '../lib/db.js';
+import { ValidationError, UnauthorizedError } from '../errors/index.js';
+
+const UpdateUserSchema = z.object({
+  name: z.string().min(1).max(100).optional(),
+  email: z.string().email().optional(),
+}).strict();
+
+export async function updateUser(id, data, session) {
+  if (!session?.userId || session.userId !== id) {
+    throw new UnauthorizedError('Access denied: cannot update another user');
+  }
+
+  const parsed = UpdateUserSchema.safeParse(data);
+  if (!parsed.success) {
+    throw new ValidationError('Invalid update payload', parsed.error.format());
+  }
+
+  return await db.user.update({
+    where: { id },
+    data: parsed.data,
+    select: { id: true, name: true, email: true, updatedAt: true }
+  });
+}
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Inspected active codebase files before writing code.
+- [ ] Delivered 100% complete code with zero `// TODO` or `// ...` placeholders.
+- [ ] Ran automated tests and validation with green status.
+- [ ] Confined changes to the minimal required blast radius.
+- [ ] Preserved existing code via targeted edits rather than full-file overwrites.
+- [ ] Persisted multi-step task state and milestones to disk.
+- [ ] Narrated progress with concise, transparent step-by-step updates.
+- [ ] Reported final status with verifiable evidence.
+
+---
+
+## Common Mistakes
+
+- **Assuming API contracts**: Guessing function parameters without opening the file.
+- **Premature completion**: Declaring "fixed" without running the test suite.
+- **Uncontrolled refactoring**: Rewriting adjacent components while fixing a 1-line bug.
+
+---
+
+## Integration Notes
+
+- Pairs with `engineering-workflow` to enforce the 6-phase pipeline.
+- Enforces the 7-rung ladder of `ponytail-mindset`.
+- Acts as the baseline behavioral guardrail across all Gemini and Antigravity operations.

package/.agents/core/skills/gemini-precision/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/core/skills/gemini-precision/skill.yaml

@@ -0,0 +1,9 @@
+name: gemini-precision
+description: High-precision engineering and execution guardrails optimized for Google Gemini models. Enforces zero-assumption file inspection, complete non-lazy implementations, surgical blast-radius containment, and mandatory proof-of-work execution.
+tags:
+  - gemini
+  - precision
+  - quality
+  - workflow
+  - antigravity
+version: 1.0.0

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

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

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

@@ -0,0 +1,112 @@
+---
+name: document-generator
+description: >
+  Generates project documentation from a single idea. Creates PRD, Architecture,
+  Database, API, UI, Roadmap, Tasks, Decision Records, and Project Graph
+  using templates. Supports incremental updates.
+---
+
+# 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.

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

@@ -0,0 +1,7 @@
+# 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/core/skills/generators/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/core/skills/generators/skill.yaml

@@ -0,0 +1,10 @@
+name: generators
+description: >
+  Generates complete project documentation (PRD, Architecture, Database, API, UI,
+  Roadmap, Tasks) from ideas and templates with incremental update support.
+tags:
+  - documentation
+  - generators
+  - architecture
+  - templates
+version: 1.0.0