gaia-framework 1.57.0 → 1.57.2

package/_gaia/dev/skills/database-design.md

@@ -1,172 +0,0 @@
----
-name: database-design
-version: '1.0'
-applicable_agents: [java-dev, python-dev]
-test_scenarios:
-  - scenario: Table naming convention
-    expected: Table names are snake_case, plural
-  - scenario: Migration file creation
-    expected: Migration includes up and down methods with version timestamp
-  - scenario: Index optimization
-    expected: Indexes cover frequently queried columns and composite patterns
----
-
-<!-- SECTION: schema-design -->
-## Schema Design
-
-### Naming Conventions
-- Tables: `snake_case`, plural: `users`, `order_items`, `payment_methods`
-- Columns: `snake_case`, singular: `first_name`, `created_at`, `is_active`
-- Primary keys: `id` (auto-increment or UUID)
-- Foreign keys: `{singular_table}_id`: `user_id`, `order_id`
-- Junction tables: `{table1}_{table2}`: `user_roles`, `product_categories`
-- Indexes: `idx_{table}_{columns}`: `idx_users_email`
-- Constraints: `{type}_{table}_{columns}`: `uq_users_email`, `chk_orders_amount`
-
-### Normalization
-- **1NF**: No repeating groups, atomic values
-- **2NF**: No partial dependencies (every non-key depends on whole key)
-- **3NF**: No transitive dependencies (non-key depends only on key)
-- Normalize to 3NF by default; denormalize only with measured justification
-
-### Denormalization
-When to denormalize:
-- Read-heavy queries with complex joins (measure first)
-- Reporting tables / materialized views
-- Caching computed values that rarely change
-
-Techniques:
-- Materialized views for complex aggregations
-- Computed columns for derived values
-- Denormalized read models (CQRS pattern)
-
-### Standard Columns
-Every table should include:
-```sql
-id          BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
-created_at  TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
-updated_at  TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
-```
-Add `deleted_at TIMESTAMP` for soft deletes when needed.
-
-<!-- SECTION: migrations -->
-## Migrations
-
-### Forward-Only Strategy
-- Prefer forward-only migrations in production environments
-- Rollback via compensating migrations rather than reversing schema changes
-- Keep a `down` script for development/testing but never rely on it in production
-
-### Versioned Migrations
-- One migration per change set
-- Timestamp-based ordering: `20260303120000_create_users_table`
-- Each migration has `up` (apply) and `down` (rollback)
-
-### Migration Template
-```sql
--- Migration: 20260303120000_create_users_table
--- Description: Create users table with authentication fields
-
--- UP
-CREATE TABLE users (
-    id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
-    email VARCHAR(255) NOT NULL,
-    password_hash VARCHAR(255) NOT NULL,
-    display_name VARCHAR(100),
-    is_active BOOLEAN DEFAULT true,
-    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
-    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
-);
-
-CREATE UNIQUE INDEX idx_users_email ON users (email);
-
--- DOWN
-DROP TABLE IF EXISTS users;
-```
-
-### Migration Safety Rules
-- Every migration MUST have a working rollback for dev/staging
-- Test rollbacks in staging before production
-- Data migrations need special care -- backup before running
-- Never drop columns in the same release they stop being used
-- Use expand-contract pattern: add new column, migrate data, remove old column
-
-### Seed Data
-- Keep seed data separate from schema migrations
-- Use seed files for development/testing reference data
-- Never seed production with test data
-- Idempotent seeds: check existence before inserting
-
-<!-- SECTION: indexing -->
-## Indexing
-
-### Index Types
-| Type | Use Case |
-|------|----------|
-| B-tree (default) | Equality and range queries |
-| Hash | Equality-only lookups |
-| GIN | Full-text search, JSONB, arrays |
-| GiST | Geometric, spatial data |
-| Partial | Subset of rows matching condition |
-
-### Query Plan Analysis
-```sql
-EXPLAIN ANALYZE SELECT * FROM users WHERE email = 'test@example.com';
-```
-- Look for `Seq Scan` on large tables -- usually needs an index
-- `Index Scan` or `Index Only Scan` is the goal
-- Check `actual time` vs `estimated time` for accuracy
-
-### Composite Indexes
-- Column order matters: most selective column first
-- Follow the "left prefix" rule: `(a, b, c)` covers queries on `a`, `(a, b)`, and `(a, b, c)`
-- Do not create single-column indexes that are prefixes of existing composites
-
-### Index Guidelines
-- Index all foreign keys
-- Index columns used in WHERE, ORDER BY, GROUP BY
-- Do not over-index: each index slows writes
-- Monitor unused indexes and remove them
-- Use partial indexes for common filtered queries: `WHERE is_active = true`
-
-<!-- SECTION: orm-patterns -->
-## ORM Patterns
-
-### Repository Pattern
-```
-Repository (data access) -> Service (business logic) -> Controller (HTTP)
-```
-- Repositories encapsulate query logic
-- Services orchestrate business rules
-- Controllers handle HTTP concerns only
-
-### N+1 Prevention
-The N+1 problem: loading a list, then loading related data one-by-one.
-
-Prevention strategies:
-- **Eager loading**: Load related data in the initial query
-- **Batch loading**: Collect IDs, load all related in one query
-- **Join queries**: Use SQL joins for single-query loading
-- **DataLoader pattern**: Batch and cache within a request
-
-Example of N+1 (bad):
-```python
-users = db.query(User).all()           # 1 query
-for user in users:
-    orders = user.orders                # N queries
-```
-
-Fixed with eager loading:
-```python
-users = db.query(User).options(
-    joinedload(User.orders)
-).all()                                 # 1 query with JOIN
-```
-
-### ORM Best Practices
-- Use query builders for complex queries instead of raw SQL
-- Map database types to domain types explicitly
-- Use database transactions for multi-table operations
-- Log generated SQL in development to catch inefficiencies
-- Avoid putting business logic in ORM models
-- Prefer explicit loading strategies over global defaults

package/_gaia/dev/skills/docker-workflow.md

@@ -1,222 +0,0 @@
----
-name: docker-workflow
-version: '1.0'
-applicable_agents: [typescript-dev, angular-dev, java-dev, python-dev, mobile-dev]
-test_scenarios:
-  - scenario: Multi-stage Dockerfile creation
-    expected: Dockerfile uses separate build and runtime stages with minimal final image
-  - scenario: Docker Compose for local development
-    expected: Compose file includes app, database, and volume mounts for hot reload
-  - scenario: Image security scanning
-    expected: CI pipeline includes image scan step and fails on critical vulnerabilities
----
-
-<!-- SECTION: multi-stage-builds -->
-## Multi-Stage Builds
-
-### Why Multi-Stage
-- Separate build dependencies from runtime dependencies
-- Smaller final images (no compilers, build tools, source code)
-- Reduced attack surface in production containers
-- Faster deployments due to smaller image size
-
-### Node.js Example
-```dockerfile
-# Stage 1: Build
-FROM node:20-alpine AS builder
-WORKDIR /app
-COPY package*.json ./
-RUN npm ci --ignore-scripts
-COPY . .
-RUN npm run build
-
-# Stage 2: Runtime
-FROM node:20-alpine AS runtime
-WORKDIR /app
-RUN addgroup -g 1001 appgroup && adduser -u 1001 -G appgroup -s /bin/sh -D appuser
-COPY --from=builder /app/dist ./dist
-COPY --from=builder /app/node_modules ./node_modules
-COPY --from=builder /app/package.json ./
-USER appuser
-EXPOSE 3000
-CMD ["node", "dist/main.js"]
-```
-
-### Java Example
-```dockerfile
-# Stage 1: Build
-FROM eclipse-temurin:21-jdk-alpine AS builder
-WORKDIR /app
-COPY gradle/ gradle/
-COPY gradlew build.gradle.kts settings.gradle.kts ./
-RUN ./gradlew dependencies --no-daemon
-COPY src/ src/
-RUN ./gradlew bootJar --no-daemon
-
-# Stage 2: Runtime
-FROM eclipse-temurin:21-jre-alpine AS runtime
-WORKDIR /app
-RUN addgroup -g 1001 appgroup && adduser -u 1001 -G appgroup -s /bin/sh -D appuser
-COPY --from=builder /app/build/libs/*.jar app.jar
-USER appuser
-EXPOSE 8080
-ENTRYPOINT ["java", "-jar", "app.jar"]
-```
-
-### Python Example
-```dockerfile
-# Stage 1: Build
-FROM python:3.12-slim AS builder
-WORKDIR /app
-RUN pip install --no-cache-dir poetry
-COPY pyproject.toml poetry.lock ./
-RUN poetry export -f requirements.txt -o requirements.txt --without-hashes
-COPY . .
-
-# Stage 2: Runtime
-FROM python:3.12-slim AS runtime
-WORKDIR /app
-RUN groupadd -g 1001 appgroup && useradd -u 1001 -g appgroup -s /bin/bash appuser
-COPY --from=builder /app/requirements.txt ./
-RUN pip install --no-cache-dir -r requirements.txt
-COPY --from=builder /app/src ./src
-USER appuser
-EXPOSE 8000
-CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000"]
-```
-
-### Best Practices
-- Use specific base image tags, never `latest`
-- Copy dependency files first for layer caching
-- Run as non-root user in the final stage
-- Use `.dockerignore` to exclude unnecessary files
-
-<!-- SECTION: compose -->
-## Docker Compose for Development
-
-### Standard Compose File
-```yaml
-services:
-  app:
-    build:
-      context: .
-      dockerfile: Dockerfile
-      target: builder
-    ports:
-      - "3000:3000"
-    volumes:
-      - .:/app
-      - /app/node_modules
-    environment:
-      - NODE_ENV=development
-      - DATABASE_URL=postgres://user:pass@db:5432/appdb
-    depends_on:
-      db:
-        condition: service_healthy
-
-  db:
-    image: postgres:16-alpine
-    ports:
-      - "5432:5432"
-    environment:
-      POSTGRES_USER: user
-      POSTGRES_PASSWORD: pass
-      POSTGRES_DB: appdb
-    volumes:
-      - pgdata:/var/lib/postgresql/data
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U user -d appdb"]
-      interval: 5s
-      timeout: 3s
-      retries: 5
-
-  redis:
-    image: redis:7-alpine
-    ports:
-      - "6379:6379"
-
-volumes:
-  pgdata:
-```
-
-### Development Patterns
-- Mount source code as volume for hot reload
-- Exclude `node_modules` with anonymous volume to avoid host/container conflicts
-- Use `depends_on` with health checks to ensure service ordering
-- Keep environment variables in `.env` file (git-ignored)
-- Use `profiles` to group optional services (e.g., monitoring, mail)
-
-### Useful Commands
-```bash
-docker compose up -d              # Start all services detached
-docker compose logs -f app        # Follow app logs
-docker compose exec app sh        # Shell into running container
-docker compose down -v            # Stop and remove volumes
-docker compose build --no-cache   # Force rebuild
-```
-
-<!-- SECTION: security-scanning -->
-## Security Scanning
-
-### .dockerignore
-Always include a `.dockerignore` to prevent sensitive files from entering the image:
-```
-.git
-.env
-.env.*
-node_modules
-*.md
-docker-compose*.yml
-.github/
-coverage/
-tests/
-**/*.test.*
-**/*.spec.*
-```
-
-### Image Scanning
-Integrate scanning into your CI pipeline:
-```yaml
-# GitHub Actions example
-- name: Build image
-  run: docker build -t myapp:${{ github.sha }} .
-
-- name: Scan image
-  uses: aquasecurity/trivy-action@master
-  with:
-    image-ref: myapp:${{ github.sha }}
-    severity: CRITICAL,HIGH
-    exit-code: 1
-```
-
-### Vulnerability Management
-| Severity | Action | Timeline |
-|----------|--------|----------|
-| Critical | Block deployment, fix immediately | 24 hours |
-| High | Fix before next release | 1 week |
-| Medium | Plan fix in next sprint | 2 weeks |
-| Low | Track and batch fix | Next quarter |
-
-### Secrets Handling
-- Never use `ENV` for secrets -- they persist in image layers
-- Use Docker BuildKit secrets for build-time secrets:
-```dockerfile
-# syntax=docker/dockerfile:1
-RUN --mount=type=secret,id=npm_token \
-    NPM_TOKEN=$(cat /run/secrets/npm_token) npm ci
-```
-- Use runtime secrets via orchestrator (Docker Swarm, Kubernetes)
-- Mount secrets as files, not environment variables when possible
-
-### Container Hardening
-- Use `USER` directive to run as non-root
-- Set `read_only: true` in compose for immutable root filesystem
-- Drop all capabilities and add only what is needed:
-```yaml
-security_opt:
-  - no-new-privileges:true
-cap_drop:
-  - ALL
-```
-- Scan base images regularly for CVEs
-- Pin base image digests for reproducible builds in production

package/_gaia/dev/skills/documentation-standards.md

@@ -1,256 +0,0 @@
----
-name: documentation-standards
-version: '1.0'
-applicable_agents: [typescript-dev, angular-dev, flutter-dev, java-dev, python-dev, mobile-dev, tech-writer, analyst, pm]
-test_scenarios:
-  - scenario: README creation for new project
-    expected: README includes all template sections with project-specific content
-  - scenario: Architecture Decision Record
-    expected: ADR follows status/context/decision/consequences format with unique ID
-  - scenario: Inline code documentation
-    expected: Public APIs have docstrings with parameter descriptions and return types
----
-
-<!-- SECTION: readme-template -->
-## README Template
-
-### Standard Structure
-Every project README should include these sections:
-
-```markdown
-# Project Name
-
-Brief one-line description of what this project does.
-
-## Overview
-
-2-3 paragraphs explaining the project's purpose, who it's for,
-and the problem it solves.
-
-## Getting Started
-
-### Prerequisites
-- Node.js >= 20
-- PostgreSQL >= 16
-- Docker (optional)
-
-### Installation
-1. Clone the repository
-2. Install dependencies: `npm install`
-3. Copy environment file: `cp .env.example .env`
-4. Run migrations: `npm run db:migrate`
-5. Start development server: `npm run dev`
-
-### Environment Variables
-| Variable | Description | Required | Default |
-|----------|-------------|----------|---------|
-| DATABASE_URL | PostgreSQL connection string | Yes | - |
-| PORT | Server port | No | 3000 |
-| LOG_LEVEL | Logging verbosity | No | info |
-
-## Usage
-
-Show common usage examples with code snippets.
-
-## Architecture
-
-Brief description of the system architecture, with a link
-to detailed ADRs and diagrams if available.
-
-## Testing
-
-How to run the test suite:
-- `npm test` -- run all tests
-- `npm run test:unit` -- unit tests only
-- `npm run test:e2e` -- end-to-end tests
-
-## Contributing
-
-Link to CONTRIBUTING.md or inline contribution guidelines.
-
-## License
-
-Specify the project license.
-```
-
-### README Guidelines
-- Keep the README under 300 lines; link to detailed docs for depth
-- Update the README when setup steps or prerequisites change
-- Include a "Quick Start" path that gets developers running in under 5 minutes
-- Add badges for CI status, test coverage, and version only if meaningful
-
-<!-- SECTION: adr-format -->
-## Architecture Decision Records
-
-### What Is an ADR
-An ADR captures a significant architectural decision along with its context and consequences. ADRs form a decision log that helps future team members understand why the system is built the way it is.
-
-### ADR Template
-```markdown
-# ADR-{NNN}: {Title of Decision}
-
-**Status**: Proposed | Accepted | Deprecated | Superseded by ADR-{NNN}
-**Date**: YYYY-MM-DD
-**Deciders**: List of people involved
-
-## Context
-
-What is the issue or problem that motivates this decision?
-What constraints or requirements apply?
-
-## Decision
-
-What is the change that we are proposing or have agreed to?
-State the decision clearly and concisely.
-
-## Consequences
-
-### Positive
-- Benefit one
-- Benefit two
-
-### Negative
-- Trade-off one
-- Trade-off two
-
-### Neutral
-- Side-effect that is neither good nor bad
-
-## Alternatives Considered
-
-### Alternative A: {Name}
-- Description of the alternative
-- Why it was rejected
-
-### Alternative B: {Name}
-- Description of the alternative
-- Why it was rejected
-```
-
-### ADR Conventions
-- Number ADRs sequentially: `ADR-001`, `ADR-002`, etc.
-- Store in `docs/adr/` or `docs/planning-artifacts/adr/`
-- Never delete ADRs; mark as `Deprecated` or `Superseded`
-- Write ADRs before or during implementation, not after
-- One decision per ADR; split compound decisions into separate records
-
-### When to Write an ADR
-- Choosing a framework, library, or language
-- Changing the database or data storage approach
-- Defining API communication patterns
-- Establishing authentication/authorization strategy
-- Making infrastructure or deployment decisions
-- Any decision that would surprise a new team member
-
-<!-- SECTION: inline-comments -->
-## Inline Code Comments
-
-### JSDoc / TSDoc (TypeScript/JavaScript)
-```typescript
-/**
- * Calculates the total price for an order including applicable discounts.
- *
- * @param items - Line items in the order
- * @param discountCode - Optional promotional discount code
- * @returns The final price after discounts, rounded to 2 decimal places
- * @throws {InvalidDiscountError} If the discount code is expired or invalid
- *
- * @example
- * const total = calculateTotal(items, 'SAVE10');
- * // returns 90.00 for a $100 order with 10% discount
- */
-function calculateTotal(items: LineItem[], discountCode?: string): number {
-  // ...
-}
-```
-
-### Python Docstrings
-```python
-def calculate_total(items: list[LineItem], discount_code: str | None = None) -> Decimal:
-    """Calculate the total price for an order including applicable discounts.
-
-    Args:
-        items: Line items in the order.
-        discount_code: Optional promotional discount code.
-
-    Returns:
-        The final price after discounts, rounded to 2 decimal places.
-
-    Raises:
-        InvalidDiscountError: If the discount code is expired or invalid.
-
-    Example:
-        >>> total = calculate_total(items, 'SAVE10')
-        >>> total
-        Decimal('90.00')
-    """
-```
-
-### Comment Guidelines
-- Document **why**, not **what** (the code shows what)
-- Every public function, class, and module needs a docstring
-- Skip docstrings on trivial getters, setters, and one-line functions
-- Use `TODO(name):` for planned work and `FIXME(name):` for known issues
-- Never leave orphaned TODO comments without an owner
-- Remove commented-out code; use version control for history
-
-<!-- SECTION: api-docs -->
-## API Documentation
-
-### What to Document
-- Every public endpoint with URL, method, and description
-- Request parameters (path, query, headers, body) with types and constraints
-- Response structure with example payloads for success and error cases
-- Authentication requirements per endpoint
-- Rate limits and quotas
-
-### API Documentation Tools
-| Tool | Best For |
-|------|----------|
-| OpenAPI / Swagger | REST APIs with auto-generated docs |
-| GraphQL Playground | GraphQL APIs with schema introspection |
-| Redoc | Beautiful static docs from OpenAPI spec |
-| Postman Collections | Interactive request examples |
-
-### Endpoint Documentation Example
-```markdown
-## Create User
-
-`POST /api/v1/users`
-
-Creates a new user account.
-
-**Authentication**: Bearer token (admin role required)
-
-**Request Body**:
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| email | string | Yes | Valid email address |
-| name | string | Yes | Display name (2-100 chars) |
-| role | string | No | User role (default: "member") |
-
-**Response 201**:
-{
-  "data": {
-    "id": "usr_abc123",
-    "email": "user@example.com",
-    "name": "Jane Doe",
-    "role": "member",
-    "created_at": "2026-03-03T12:00:00Z"
-  }
-}
-
-**Response 422**:
-{
-  "type": "https://api.example.com/errors/validation-error",
-  "title": "Validation Error",
-  "status": 422,
-  "errors": [{ "field": "email", "code": "INVALID_FORMAT" }]
-}
-```
-
-### Documentation Maintenance
-- Generate docs from code annotations when possible (keeps docs in sync)
-- Include a "last updated" date on manually written docs
-- Review API docs as part of the PR review process
-- Test documented examples in CI to prevent drift