contextos-agents 1.7.0 → 2.0.0-beta.3

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

@@ -1,63 +0,0 @@
----
-name: docker
-description: Docker containerization, multi-stage builds, non-root security, layer caching optimization, and docker-compose standards.
----
-
-# Docker
-
-## Overview
-
-Containerization, Dockerfile architecture, security best practices, and container orchestration for production workloads.
-
-## When to Use
-
-Activate when creating or optimizing Dockerfiles, docker-compose configurations, container security audits, or CI/CD container builds.
-
-## Rules & Patterns
-
-### Negative Constraints (What NOT to Do)
-
-1. **NEVER run containers as `root` in production**: Always create and switch to an unprivileged non-root user (e.g. `USER node` or `USER nonroot`).
-2. **NEVER use the `latest` tag**: Always pin base images to specific immutable version digests or explicit minor tags (e.g. `node:20.12.2-alpine3.19`).
-3. **NEVER copy source code before `package.json`**: Always copy lockfiles and install dependencies first to leverage Docker's layer caching.
-4. **NEVER bake secrets, API keys, or `.env` files into image layers**: Pass secrets via build-time secret mounts (`--mount=type=secret`) or runtime environment variables.
-5. **NEVER include build tools or devDependencies in the final runner image**: Always use multi-stage builds to discard compilers and package managers from production images.
-
-### Multi-Stage Standard Pattern
-
-```dockerfile
-FROM node:20.12.2-alpine3.19 AS builder
-WORKDIR /app
-COPY package.json package-lock.json ./
-RUN npm ci
-COPY . .
-RUN npm run build && npm prune --production
-
-FROM node:20.12.2-alpine3.19 AS runner
-WORKDIR /app
-ENV NODE_ENV=production
-RUN addgroup -S -g 1001 appgroup && adduser -S -u 1001 appuser -G appgroup
-COPY --from=builder --chown=appuser:appgroup /app/dist ./dist
-COPY --from=builder --chown=appuser:appgroup /app/node_modules ./node_modules
-USER appuser
-CMD ["node", "dist/index.js"]
-```
-
-## Code Examples
-
-See `EXAMPLES.md` for production Dockerfiles and dockerignore patterns.
-
-## Validation Checklist
-
-- [ ] Multi-stage build separates build tools from runtime
-- [ ] Non-root `USER` directive active in final stage
-- [ ] Base images pinned to exact versions
-- [ ] `.dockerignore` file prevents leaking node_modules or secrets
-
-## Common Mistakes
-
-- Copying entire workspace before `npm ci`, breaking Docker cache. See `TROUBLESHOOTING.md`.
-
-## Integration Notes
-
-Interacts with `security` (container hardening) and `node` / `nextjs` / `fastapi`.

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

@@ -1,18 +0,0 @@
-# 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/.agents/core/skills/docker/VALIDATION.json

@@ -1,11 +0,0 @@
-{
-  "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/.agents/core/skills/docker/skill.yaml

@@ -1,29 +0,0 @@
-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
-triggers:
-  files:
-    - "Dockerfile"
-    - "Dockerfile.*"
-    - "docker-compose.yml"
-    - "docker-compose.yaml"
-    - "compose.yml"
-    - "compose.yaml"
-    - ".dockerignore"
-  keywords:
-    - "docker"
-    - "dockerfile"
-    - "container"
-    - "docker-compose"
-    - "image"
-    - "kubernetes"
-    - "k8s"
-resources:
-  - EXAMPLES.md
-  - SKILL.md
-  - TROUBLESHOOTING.md
-  - VALIDATION.json

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

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

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

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

@@ -1,12 +0,0 @@
-{
-  "$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

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

@@ -1,17 +0,0 @@
-id: fastapi
-name: FastAPI
-category: backend
-type: instruction-only
-tags: [backend, python, api, async, pydantic]
-requires: []
-optional: [postgres, redis, docker]
-conflicts: [nestjs, express]
-weight: 8
-documents:
-  - fastapi.md
-resources:
-  - EXAMPLES.md
-  - SKILL.md
-  - TROUBLESHOOTING.md
-  - VALIDATION.json
-  - fastapi.md

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

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

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

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

@@ -1,12 +0,0 @@
-{
-  "$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

@@ -1,25 +0,0 @@
-name: generators
-type: compiler
-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
-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