contextos-agents 2.0.0 → 2.1.1

package/catalog/skills/decisions/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: decision-engine
+description: >
+  Architecture Decision Records (ADR) management. Creates, tracks, and queries
+  decisions so the AI agent understands WHY choices were made, not just WHAT was chosen.
+---
+
+# decision-engine
+
+## Overview
+
+Architecture Decision Record (ADR) system following Michael Nygard format. Captures context, options considered, tradeoffs, and consequences to prevent architectural regression and knowledge loss across AI sessions.
+
+## When to Use
+
+Activate when choosing or switching database engines, authentication strategies, state libraries, or significant architectural patterns.
+
+## Rules & Patterns
+
+You manage **Architecture Decision Records** (ADRs).
+
+## Why Decisions Matter
+
+Without ADRs, the AI agent sees:
+
+- "Database: PostgreSQL" - but doesn't know WHY
+- "Auth: JWT" - but doesn't know what alternatives were considered
+- "Framework: Next.js" - but doesn't know the tradeoffs
+
+With ADRs, the agent understands the reasoning and won't accidentally contradict prior decisions.
+
+## Commands
+
+### Create a Decision
+
+When an architectural choice is made during any pipeline stage:
+
+1. Auto-increment the decision number
+2. Use the template from `generators/templates/DECISION.md`
+3. Save to `docs/decisions/NNNN-decision-name.md`
+4. Update the Project Graph if the decision affects modules
+
+**Naming convention:** `docs/decisions/0001-use-postgresql.md`
+
+### Query Decisions
+
+Before making changes that touch architecture:
+
+1. Check `docs/decisions/` for related decisions
+2. If a decision exists, follow it
+3. If a decision needs to change, create a new ADR that **supersedes** the old one
+
+### Decision Lifecycle
+
+```
+proposed → accepted → [deprecated | superseded]
+```
+
+- **proposed**: Under discussion, not yet committed
+- **accepted**: The team agreed, this is the standard
+- **deprecated**: No longer relevant (project evolved)
+- **superseded**: Replaced by a newer decision (link to it)
+
+## Auto-Detection
+
+The Decision Engine should suggest creating an ADR when it detects:
+
+- A new database/ORM is introduced
+- A new framework is added
+- Authentication strategy changes
+- API versioning approach is chosen
+- Deployment strategy is decided
+- A significant library is added (state management, testing framework, etc.)
+
+
+## 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/decisions/TROUBLESHOOTING.md

@@ -0,0 +1,13 @@
+# decisions Troubleshooting & Common Mistakes
+
+## 1. Post-Hoc Justifications
+
+- **Symptom**: ADR written weeks after code is merged, omitting all rejected options.
+- **Root Cause**: Treating ADRs as paperwork rather than decision-making tools.
+- **Fix**: Write the ADR during the PLAN phase _before_ implementing the decision.
+
+## 2. Omitting Trade-offs
+
+- **Symptom**: ADR lists only benefits, claiming the chosen tech has zero downsides.
+- **Root Cause**: Confirmation bias.
+- **Fix**: Every architecture decision has costs. Explicitly document negative trade-offs and operational overhead.

package/catalog/skills/decisions/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/decisions/skill.yaml

@@ -0,0 +1,13 @@
+schemaVersion: 2
+name: decisions
+category: architecture
+type: instruction-only
+description: >
+  Architecture Decision Records (ADR) management. Creates, tracks, and queries
+  architectural decisions so AI assistants understand why choices were made.
+version: 1.0.0
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json

package/catalog/skills/docker/EXAMPLES.md

@@ -0,0 +1,56 @@
+# Docker Examples - Anti-patterns vs ContextOS Standard
+
+## Example 1: Multi-Stage Build & Layer Caching
+
+### Anti-pattern: Anti-pattern (Fat single-stage image running as root)
+
+```dockerfile
+# BAD: 1.2GB image, runs as root, breaks caching on every file edit
+FROM node:latest
+WORKDIR /app
+COPY . .
+RUN npm install
+RUN npm run build
+EXPOSE 3000
+CMD ["npm", "start"]
+```
+
+### Best practice: ContextOS Standard (Slim multi-stage build with non-root user)
+
+```dockerfile
+# GOOD: 95MB image, non-root user, optimized layer caching
+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/main.js"]
+```
+
+---
+
+## Example 2: Docker Ignore File (`.dockerignore`)
+
+### Best practice: ContextOS Standard `.dockerignore`
+
+```gitignore
+node_modules
+npm-debug.log
+.git
+.gitignore
+.env
+.env.*
+dist
+coverage
+.DS_Store
+*.md
+```

package/catalog/skills/docker/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: docker
+description: Docker containerization, multi-stage builds, non-root security, layer caching optimization, and docker-compose standards.
+---
+
+# Docker
+
+## Overview
+
+Containerization, Dockerfile architecture, multi-stage compilation, security hardening, and container orchestration for production workloads.
+
+## When to Use
+
+Activate when creating or optimizing Dockerfiles, docker-compose configurations, container security audits, CI/CD container build stages, or production container deployments.
+
+## 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:22-alpine3.20` or `python:3.12-slim-bookworm`).
+3. **NEVER copy source code before dependency manifests**: Always copy package manifests (`package.json`, `pnpm-lock.yaml`, `pyproject.toml`) and install dependencies first to maximize Docker layer cache hits.
+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 injected by the orchestrator.
+5. **NEVER include build tools or devDependencies in the final runner image**: Always use multi-stage builds to discard compilers, package managers, and temporary build caches from production images.
+6. **NEVER run without a `.dockerignore` file**: Always exclude `.git`, `node_modules`, `.env*`, and build outputs from the Docker build context.
+
+---
+
+### Pattern 1: Node.js / Next.js Standalone Multi-Stage Dockerfile
+
+Optimized multi-stage build producing minimal production images (<120MB) with non-root security:
+
+```dockerfile
+# ── Stage 1: Dependencies ─────────────────────────────────────────────
+FROM node:22-alpine3.20 AS deps
+RUN apk add --no-cache libc6-compat
+WORKDIR /app
+
+COPY package.json pnpm-lock.yaml* package-lock.json* yarn.lock* ./
+RUN \
+  if [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm i --frozen-lockfile; \
+  elif [ -f package-lock.json ]; then npm ci; \
+  else yarn --frozen-lockfile; \
+  fi
+
+# ── Stage 2: Builder ──────────────────────────────────────────────────
+FROM node:22-alpine3.20 AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+
+ENV NEXT_TELEMETRY_DISABLED=1
+ENV NODE_ENV=production
+RUN npm run build
+
+# ── Stage 3: Production Runner ────────────────────────────────────────
+FROM node:22-alpine3.20 AS runner
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV PORT=3000
+ENV HOSTNAME="0.0.0.0"
+
+RUN addgroup --system --gid 1001 nodejs && \
+    adduser --system --uid 1001 nextjs
+
+# Copy standalone output and static assets
+COPY --from=builder /app/public ./public
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+
+USER nextjs
+EXPOSE 3000
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
+  CMD wget --no-verbose --tries=1 --spider http://127.0.0.1:3000/api/health || exit 1
+
+CMD ["node", "server.js"]
+```
+
+---
+
+### Pattern 2: Python / FastAPI Multi-Stage Dockerfile (uv)
+
+High-performance Python build utilizing `uv` for sub-second installs and slim final layers:
+
+```dockerfile
+# ── Stage 1: Build virtual environment ────────────────────────────────
+FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim AS builder
+WORKDIR /app
+
+ENV UV_COMPILE_BYTECODE=1
+ENV UV_LINK_MODE=copy
+
+# Install dependencies before code to leverage layer cache
+RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=type=bind,source=uv.lock,target=uv.lock \
+    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+    uv sync --frozen --no-install-project --no-dev
+
+COPY . /app
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen --no-dev
+
+# ── Stage 2: Runtime Runner ───────────────────────────────────────────
+FROM python:3.12-slim-bookworm AS runner
+WORKDIR /app
+
+# Create unprivileged application user
+RUN groupadd -r appgroup && useradd -r -g appgroup appuser
+
+COPY --from=builder --chown=appuser:appgroup /app /app
+
+ENV PATH="/app/.venv/bin:$PATH"
+ENV PYTHONUNBUFFERED=1
+
+USER appuser
+EXPOSE 8000
+
+HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
+  CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health').read()" || exit 1
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "2"]
+```
+
+---
+
+### Pattern 3: Essential `.dockerignore` Template
+
+Every repository must include a `.dockerignore` to prevent uploading secrets and heavy cache folders:
+
+```text
+.git
+.github
+node_modules
+npm-debug.log
+.env
+.env.*
+!.env.example
+dist
+build
+.next
+.cache
+coverage
+*.md
+Dockerfile*
+docker-compose*.yml
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Multi-stage build separates build compilers from production runtime.
+- [ ] Non-root `USER` directive is active in the final image stage.
+- [ ] Base images are pinned to explicit, immutable release tags.
+- [ ] `HEALTHCHECK` directive is defined with reasonable interval and timeout.
+- [ ] `.dockerignore` prevents leaking local `.env` files and `node_modules`.
+- [ ] Dependencies are copied and installed before copying source code.
+
+## Common Mistakes
+
+- **Running as root**: Leaves the host system vulnerable if a container breakout vulnerability occurs.
+- **Copying entire source before install**: Invalidates the Docker layer cache on every code edit, slowing CI builds.
+- **Omitting HEALTHCHECK**: Orchestrators cannot detect frozen or zombie worker processes.
+
+## Integration Notes
+
+Interacts with `security` (container hardening) and `node` / `nextjs` / `fastapi`.

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)
+```