contextos-agents 2.1.0 → 2.2.0

package/catalog/skills/docker/TROUBLESHOOTING.md

@@ -0,0 +1,18 @@
+# Docker Troubleshooting Guide
+
+## Common Issues & Fixes
+
+### 1. Slow Docker builds rebuilding node_modules every time
+
+- **Cause**: Copying the entire directory (`COPY . .`) before running `npm ci`.
+- **Fix**: Copy `package.json` and `package-lock.json` separately first, run `npm ci`, and only then copy application source code.
+
+### 2. Permission Denied Errors with Non-Root Users
+
+- **Cause**: Files copied from builder without changing ownership.
+- **Fix**: Always use `--chown=appuser:appgroup` when copying files in Dockerfile.
+
+### 3. Missing native build dependencies on Alpine Linux
+
+- **Cause**: Packages requiring C bindings (e.g. `sharp`, `bcrypt`) fail on musl libc.
+- **Fix**: Add `RUN apk add --no-cache libc6-compat python3 make g++` in the builder stage.

package/catalog/skills/docker/VALIDATION.json

@@ -0,0 +1,11 @@
+{
+  "skill": "docker",
+  "version": "1.0.0",
+  "checks": [
+    "Multi-stage Dockerfile architecture",
+    "Non-root USER directive present",
+    "Layer caching optimization (lockfiles copied first)",
+    "Specific image version tags (no :latest)",
+    ".dockerignore excludes node_modules and secrets"
+  ]
+}

package/catalog/skills/docker/skill.yaml

@@ -0,0 +1,13 @@
+schemaVersion: 2
+name: docker
+description: Docker containerization, multi-stage builds, non-root security, layer caching optimization, and docker-compose standards.
+version: 1.0.0
+category: devops
+type: instruction-only
+requires:
+  - security
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json

package/catalog/skills/fastapi/EXAMPLES.md

@@ -0,0 +1,36 @@
+# 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"}
+```

package/catalog/skills/fastapi/SKILL.md

@@ -0,0 +1,171 @@
+---
+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, ConfigDict
+
+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 typing import AsyncGenerator
+from fastapi import Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer
+from sqlalchemy.ext.asyncio import AsyncSession
+import jwt
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="api/v1/auth/token")
+
+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:
+    try:
+        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
+        user_id: str = payload.get("sub")
+        if user_id is None:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Could not validate credentials",
+                headers={"WWW-Authenticate": "Bearer"},
+            )
+    except jwt.PyJWTError:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid token signature or expired token",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    user = await user_repo.get_by_id(db, user_id=user_id)
+    if user is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found")
+    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** - use `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/catalog/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/catalog/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/catalog/skills/fastapi/skill.yaml

@@ -0,0 +1,14 @@
+schemaVersion: 2
+id: fastapi
+name: FastAPI
+category: backend
+type: instruction-only
+requires: []
+optional: [postgres, redis, docker]
+conflicts: [nestjs, express]
+weight: 8
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json

package/catalog/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/catalog/skills/generators/SKILL.md

@@ -0,0 +1,110 @@
+---
+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.
+
+## Workflows & CLI Commands
+
+### Project Initialization (`contextos init`)
+
+Full project initialization. From one user prompt, generate foundational documentation:
+
+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 (optional, when backend API layer is present)
+   - `docs/UI.md` - UI/UX Specification (optional, when UI layer is present)
+   - `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 configuration via Adapters skill (`contextos export all`)
+
+### Incremental Updates
+
+When project requirements or schemas change:
+
+1. Identify which documents are affected
+2. Update only affected documents
+3. Show diff of changes to user
+4. Update Project Graph if structure changed
+
+### Task Breakdown & Planning (`contextos resolve` & `/plan`)
+
+Generate vertical development tasks from existing PRD and architecture:
+
+1. Read `docs/PRD.md` and `docs/ARCHITECTURE.md`
+2. Run `contextos resolve "<task description>"` to resolve minimal required skills
+3. Break modules into vertical features and tasks (< 2 hours each)
+4. Estimate complexity (S/M/L/XL)
+5. Output to `docs/TASKS.md` or task implementation plan
+
+## 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/catalog/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/catalog/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/catalog/skills/generators/skill.yaml

@@ -0,0 +1,22 @@
+schemaVersion: 2
+name: generators
+category: engineering
+type: compiler
+description: >
+  Generates complete project documentation (PRD, Architecture, Database, API, UI,
+  Roadmap, Tasks) from ideas and templates with incremental update support.
+version: 1.0.0
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json
+  - templates/API.md
+  - templates/ARCHITECTURE.md
+  - templates/DATABASE.md
+  - templates/DECISION.md
+  - templates/PRD.md
+  - templates/PROJECT_GRAPH.md
+  - templates/ROADMAP.md
+  - templates/TASKS.md
+  - templates/UI.md

package/catalog/skills/generators/templates/API.md

@@ -0,0 +1,77 @@
+# {{Project Name}} - API Specification
+
+## Base URL
+
+`{{base_url}}` (e.g., `https://api.example.com/v1`)
+
+## Authentication
+
+{{auth_method}} (e.g., Bearer token via JWT)
+
+## Endpoints
+
+### {{Module Name}}
+
+#### `{{METHOD}} {{path}}`
+
+{{description}}
+
+**Request:**
+
+```json
+{{request_body}}
+```
+
+**Response (200):**
+
+```json
+{{response_body}}
+```
+
+**Errors:**
+
+| Code | Description |
+| --- | --- |
+| 400 | {{bad_request_reason}} |
+| 401 | Unauthorized |
+| 404 | {{not_found_reason}} |
+
+---
+
+## Error Format
+
+All errors follow this format:
+
+```json
+{
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "Human-readable message",
+    "details": {}
+  }
+}
+```
+
+## Pagination
+
+```json
+{
+  "data": [...],
+  "pagination": {
+    "page": 1,
+    "per_page": 20,
+    "total": 100,
+    "total_pages": 5
+  }
+}
+```
+
+## Rate Limiting
+
+- {{rate_limit}} requests per {{window}}
+- Headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
+
+## Versioning
+
+- URL-based: `/v1/`, `/v2/`
+- Breaking changes require new version

package/catalog/skills/generators/templates/ARCHITECTURE.md

@@ -0,0 +1,70 @@
+# {{Project Name}} - System Architecture
+
+## Architecture Overview
+<!-- High-level architecture description and diagram -->
+
+```
+{{architecture_diagram}}
+```
+
+## Tech Stack
+
+| Layer | Technology | Reason |
+| --- | --- | --- |
+| Frontend | {{e.g., Next.js + React}} | {{reason}} |
+| Backend | {{e.g., Node.js + Express}} | {{reason}} |
+| Database | {{e.g., PostgreSQL}} | {{reason}} |
+| Cache | {{e.g., Redis}} | {{reason}} |
+| Auth | {{e.g., JWT + OAuth2}} | {{reason}} |
+| Hosting | {{e.g., Vercel + Railway}} | {{reason}} |
+
+## System Components
+
+### {{Component 1 Name}}
+
+- **Responsibility:** {{what it does}}
+- **Interfaces:** {{what it exposes}}
+- **Dependencies:** {{what it depends on}}
+
+### {{Component 2 Name}}
+
+- **Responsibility:** {{what it does}}
+- **Interfaces:** {{what it exposes}}
+- **Dependencies:** {{what it depends on}}
+
+## Data Flow
+
+```
+User → Frontend → API Gateway → Service Layer → Database
+                                      ↓
+                                 Cache Layer
+```
+
+## Directory Structure
+
+```
+{{project_root}}/
+├── src/
+│   ├── modules/           # Feature modules
+│   │   ├── {{module_1}}/
+│   │   └── {{module_2}}/
+│   ├── shared/            # Shared utilities
+│   ├── config/            # Configuration
+│   └── types/             # Type definitions
+├── tests/
+├── docs/
+└── infrastructure/
+```
+
+## Security Architecture
+<!-- Authentication, authorization, data protection -->
+
+## Scalability Considerations
+<!-- How will this scale? What are the bottlenecks? -->
+
+## Error Handling Strategy
+<!-- How are errors propagated, logged, and reported? -->
+
+## Key Architectural Decisions
+<!-- Reference to ADRs in docs/decisions/ -->
+- See `docs/decisions/` for all architectural decisions with rationale

package/catalog/skills/generators/templates/DATABASE.md

@@ -0,0 +1,42 @@
+# {{Project Name}} - Database Schema
+
+## Database Engine
+
+{{e.g., PostgreSQL 16}}
+
+## Entity Relationship Diagram
+
+```
+{{ER_diagram}}
+```
+
+## Tables
+
+### {{table_name}}
+
+| Column | Type | Constraints | Description |
+| --- | --- | --- | --- |
+| id | UUID | PK, DEFAULT gen_random_uuid() | Primary key |
+| {{column}} | {{type}} | {{constraints}} | {{description}} |
+| created_at | TIMESTAMPTZ | NOT NULL, DEFAULT NOW() | Creation timestamp |
+| updated_at | TIMESTAMPTZ | NOT NULL, DEFAULT NOW() | Last update timestamp |
+
+**Indexes:**
+
+- `idx_{{table}}_{{column}}` ON ({{column}})
+
+**Relations:**
+
+- {{table_name}}.{{fk_column}} → {{related_table}}.id
+
+## Migrations Strategy
+<!-- How are schema changes applied? -->
+- Tool: {{e.g., Prisma Migrate, Alembic, Knex}}
+- Naming: `YYYYMMDD_HHMMSS_description`
+- Rule: Never modify existing migrations, always create new ones
+
+## Seed Data
+<!-- What data needs to exist for the app to work? -->
+
+## Performance Considerations
+<!-- Indexes, query optimization, connection pooling -->