swe-workflow-skills 0.1.0

package/skills/containerization/references/dockerfile-patterns.md

@@ -0,0 +1,168 @@
+# Dockerfile Patterns
+
+## Contents
+- Node.js patterns
+- Python patterns
+- Go patterns
+- Docker Compose patterns
+- Common anti-patterns
+
+## Node.js Multi-Stage Build
+
+```dockerfile
+# Stage 1: Build
+FROM node:20.11-alpine AS builder
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci --ignore-scripts
+COPY . .
+RUN npm run build
+
+# Stage 2: Production
+FROM node:20.11-alpine AS production
+RUN addgroup -g 1001 -S appgroup && adduser -S appuser -u 1001 -G appgroup
+WORKDIR /app
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/package.json ./
+USER appuser
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s \
+  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
+CMD ["node", "dist/main.js"]
+```
+
+## Python Multi-Stage Build
+
+```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
+RUN pip install --no-cache-dir --prefix=/install -r requirements.txt
+COPY . .
+
+# Stage 2: Production
+FROM python:3.12-slim AS production
+RUN groupadd -r appgroup && useradd -r -g appgroup -d /app appuser
+WORKDIR /app
+COPY --from=builder /install /usr/local
+COPY --from=builder /app .
+USER appuser
+EXPOSE 8000
+HEALTHCHECK --interval=30s --timeout=3s --start-period=15s \
+  CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')" || exit 1
+CMD ["gunicorn", "app:create_app()", "--bind", "0.0.0.0:8000", "--workers", "4"]
+```
+
+## Go (Distroless)
+
+```dockerfile
+FROM golang:1.22-alpine AS builder
+WORKDIR /app
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /server ./cmd/server
+
+FROM gcr.io/distroless/static-debian12
+COPY --from=builder /server /server
+USER nonroot:nonroot
+EXPOSE 8080
+ENTRYPOINT ["/server"]
+```
+
+Go produces a static binary — the final image can be distroless (no shell, no package manager) for a minimal attack surface. Image size: ~10-20 MB.
+
+## Docker Compose for Local Development
+
+```yaml
+services:
+  app:
+    build:
+      context: .
+      target: builder  # Use the build stage for development
+    volumes:
+      - .:/app
+      - /app/node_modules  # Prevent overwriting container's node_modules
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=development
+      - DATABASE_URL=postgresql://postgres:postgres@db:5432/appdb
+      - REDIS_URL=redis://redis:6379
+    depends_on:
+      db:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    command: npm run dev  # Override CMD for hot-reload
+
+  db:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: appdb
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    ports:
+      - "5432:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+volumes:
+  pgdata:
+```
+
+## .dockerignore Template
+
+```
+.git
+.github
+node_modules
+dist
+*.log
+.env
+.env.*
+!.env.example
+docker-compose*.yml
+Dockerfile*
+.dockerignore
+README.md
+docs/
+tests/
+__pycache__
+*.pyc
+.pytest_cache
+.coverage
+```
+
+## Common Anti-patterns
+
+**Running as root**: Every container should run as a non-root user. If the base image runs as root by default, create a user.
+
+**Using `latest` tag**: Tags can be overwritten. Pin to a specific version or SHA digest for reproducibility.
+
+**Installing dev dependencies in production**: Use multi-stage builds. Keep test frameworks, linters, and build tools out of the final image.
+
+**Copying everything before installing deps**: This busts the Docker layer cache on every code change. Copy dependency manifests first, install, then copy application code.
+
+**Large images**: A Node.js app shouldn't be 1.5 GB. Use Alpine bases, multi-stage builds, and .dockerignore. Target: <200 MB for most apps.
+
+**Secrets in build args**: Build args are visible in `docker history`. Use runtime env vars or mounted secrets for sensitive data. Never `ARG DB_PASSWORD`.

package/skills/containerization/templates/dockerfile.md

@@ -0,0 +1,154 @@
+# Dockerfile Templates
+
+Copy the appropriate template, then replace placeholder values (`APP_NAME`, port numbers, etc.).
+
+---
+
+## Node.js — Multi-Stage
+
+```dockerfile
+# syntax=docker/dockerfile:1
+FROM node:20.11-alpine3.19 AS deps
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev
+
+FROM node:20.11-alpine3.19 AS build
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:20.11-alpine3.19 AS production
+WORKDIR /app
+ENV NODE_ENV=production
+# Non-root user
+RUN addgroup -S appgroup && adduser -S appuser -G appgroup
+COPY --from=deps --chown=appuser:appgroup /app/node_modules ./node_modules
+COPY --from=build --chown=appuser:appgroup /app/dist ./dist
+USER appuser
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD wget -qO- http://localhost:3000/health || exit 1
+CMD ["node", "dist/index.js"]
+```
+
+---
+
+## Python — Multi-Stage
+
+```dockerfile
+# syntax=docker/dockerfile:1
+FROM python:3.12-slim AS build
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir --prefix=/install -r requirements.txt
+
+FROM python:3.12-slim AS production
+WORKDIR /app
+ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1
+RUN addgroup --system appgroup && adduser --system --ingroup appgroup appuser
+COPY --from=build --chown=appuser:appgroup /install /usr/local
+COPY --chown=appuser:appgroup . .
+USER appuser
+EXPOSE 8000
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
+  CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"
+CMD ["python", "-m", "gunicorn", "app.main:app", "--bind", "0.0.0.0:8000"]
+```
+
+---
+
+## Go — Binary (Minimal Runtime)
+
+```dockerfile
+# syntax=docker/dockerfile:1
+FROM golang:1.22-alpine AS build
+WORKDIR /app
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /app/server ./cmd/server
+
+FROM gcr.io/distroless/static-debian12 AS production
+WORKDIR /app
+# distroless runs as nonroot (uid 65532) by default
+COPY --from=build /app/server .
+EXPOSE 8080
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
+  CMD ["/app/server", "healthcheck"]
+ENTRYPOINT ["/app/server"]
+```
+
+---
+
+## .dockerignore
+
+```
+.git
+.gitignore
+*.md
+.env*
+node_modules/
+dist/
+build/
+coverage/
+**/*.test.*
+**/*.spec.*
+Dockerfile*
+docker-compose*
+```
+
+---
+
+## docker-compose.yml — Local Development
+
+```yaml
+services:
+  app:
+    build:
+      context: .
+      target: build          # Use build stage for hot-reload; swap to production for prod-parity testing
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=development
+      - DATABASE_URL=postgres://app:secret@db:5432/appdb
+      - REDIS_URL=redis://cache:6379
+    volumes:
+      - .:/app               # Hot-reload mount
+      - /app/node_modules    # Prevent host node_modules overwrite
+    depends_on:
+      db:
+        condition: service_healthy
+      cache:
+        condition: service_started
+
+  db:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_DB: appdb
+      POSTGRES_USER: app
+      POSTGRES_PASSWORD: secret
+    volumes:
+      - db-data:/var/lib/postgresql/data
+    ports:
+      - "5432:5432"          # Remove in production
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U app -d appdb"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  cache:
+    image: redis:7-alpine
+    volumes:
+      - cache-data:/data
+
+volumes:
+  db-data:
+  cache-data:
+```
+
+> **Key rules:** Never put real secrets in docker-compose.yml. Use a `.env` file (git-ignored) or a secrets manager. The `.env.example` file documents required variables without values.

package/skills/data-modeling/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: data-modeling
+description: "Design database schemas, relationships, indexes, and migration strategies — relational and document stores. Triggers: data model, schema design, ER diagram, database schema, table design, foreign key, index strategy, normalization, denormalization, migration plan, document model, partition key."
+model: sonnet
+allowed-tools: Read, Grep, Glob, Write, Edit
+---
+
+# Data Modeling
+
+Guide the user through designing data models that are normalized, consistent, and evolvable. Good data models make the right things easy and the wrong things hard.
+
+## Workflow
+
+### Step 1: Understand the Domain
+
+Before touching schemas, understand the business domain:
+
+- **What are the core entities?** (nouns in the requirements: User, Order, Product)
+- **What are the relationships?** (verbs: User *places* Order, Order *contains* Products)
+- **What are the cardinalities?** (one-to-one, one-to-many, many-to-many)
+- **What are the access patterns?** (how will the data be queried most often)
+- **What are the invariants?** (rules that must always hold: "an order must have at least one item")
+
+If the user describes a feature rather than a domain, extract the entities from the feature description first.
+
+### Step 2: Design the Conceptual Model
+
+Produce an entity-relationship description listing:
+
+- Each entity with its key attributes
+- Relationships with cardinality (1:1, 1:N, M:N)
+- Business rules that constrain the model
+
+Present this as a structured list or ASCII diagram. Don't jump to SQL yet — validate the conceptual model with the user first.
+
+### Step 3: Apply Normalization
+
+Design tables following normalization principles:
+
+- **1NF**: No repeating groups; every column holds atomic values
+- **2NF**: Every non-key column depends on the whole primary key
+- **3NF**: No transitive dependencies (non-key → non-key)
+
+Denormalize only with explicit justification (specific read performance requirement with measured data). Document every denormalization decision and the access pattern it serves.
+
+### Step 4: Define the Physical Schema
+
+Produce SQL DDL or ORM model definitions. For each table include:
+
+- Primary key strategy (auto-increment, UUID, ULID — justify the choice)
+- Foreign keys with ON DELETE/ON UPDATE behavior
+- Indexes based on identified access patterns
+- Constraints (NOT NULL, UNIQUE, CHECK) that enforce business rules
+- Timestamps (created_at, updated_at) as appropriate
+
+Use [templates/schema.md](templates/schema.md) as a starting point for table DDL, index naming, enum patterns, and migration file structure.
+
+### Step 5: Plan the Migration
+
+If modifying an existing schema:
+
+- **Backwards-compatible changes**: Add columns with defaults, add tables, add indexes
+- **Breaking changes**: Require a migration strategy (expand-contract pattern)
+- **Data backfills**: Script them, don't do them manually
+
+Produce migration files appropriate to the ORM/framework in use. Each migration should be independently reversible.
+
+### Step 6: Validate
+
+Cross-check the schema against:
+
+- [ ] Every acceptance criterion from the feature plan can be served by the schema
+- [ ] Every identified access pattern has an appropriate index
+- [ ] Every business invariant is enforced by constraints
+- [ ] No data can be orphaned (foreign keys and cascades are correct)
+- [ ] The migration is reversible
+
+## Principles Applied
+
+- **DRY**: Single source of truth for each piece of data
+- **KISS**: Start normalized; denormalize only when measured performance demands it
+- **Functional Independence**: Each table represents one concept
+- **YAGNI**: Don't add columns or tables "just in case"

package/skills/data-modeling/evals/evals.json

@@ -0,0 +1,43 @@
+{
+  "skill_name": "data-modeling",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I'm building an e-commerce platform and need to design the schema for products, categories, orders, and inventory. Products can belong to multiple categories. We're using PostgreSQL with Django ORM. Estimated scale: 10K products, 1K orders/day.",
+      "expected_output": "Should start with conceptual model (entities + relationships), then produce normalized schema with proper foreign keys, indexes for common queries, and Django model definitions.",
+      "assertions": [
+        "Identifies M:N relationship between products and categories",
+        "Creates a join table for product-category relationship",
+        "Schema is at least 3NF normalized",
+        "Includes indexes for common access patterns (order lookup by user, product search)",
+        "Foreign keys have explicit ON DELETE behavior",
+        "Includes created_at/updated_at timestamps",
+        "Validates schema against likely access patterns"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "I need to add a comments feature to our blog. Users can comment on posts and reply to other comments. We need to track who edited comments and when. Using Prisma with PostgreSQL.",
+      "expected_output": "Should model the self-referential relationship for threaded comments, include audit fields, and produce Prisma schema.",
+      "assertions": [
+        "Models the self-referential parent_comment_id relationship",
+        "Includes ON DELETE strategy for nested comments",
+        "Tracks edit history (edited_at or separate edit_history table)",
+        "Produces Prisma schema syntax, not raw SQL",
+        "Considers soft delete for comment moderation"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "We need to rename our 'username' column to 'display_name' in the users table. We have 2M users and the column is used in about 15 places in the codebase. We can't have downtime. How should I approach this?",
+      "expected_output": "Should recommend the expand-contract migration pattern, not a simple column rename. Should produce multiple migration steps with deployment coordination.",
+      "assertions": [
+        "Does NOT suggest a simple ALTER TABLE RENAME",
+        "Recommends expand-contract (add new column, dual-write, backfill, cut over, drop old)",
+        "Addresses the zero-downtime requirement explicitly",
+        "Warns about table locking on 2M rows",
+        "Produces reversible migration steps"
+      ]
+    }
+  ]
+}

package/skills/data-modeling/references/conventions.md

@@ -0,0 +1,57 @@
+# Data Modeling Conventions
+
+## Contents
+- Naming conventions
+- Primary key strategies
+- Common column types
+- Index naming
+- Migration best practices
+
+## Naming Conventions
+
+- **Tables**: plural, snake_case (`users`, `order_items`, `payment_methods`)
+- **Columns**: singular, snake_case (`email`, `created_at`, `user_id`)
+- **Foreign keys**: `{referenced_table_singular}_id` (e.g., `user_id`, `order_id`)
+- **Join tables**: alphabetical concatenation (`product_tags`, `role_users`)
+- **Boolean columns**: prefix with `is_` or `has_` (`is_active`, `has_verified_email`)
+- **Timestamps**: suffix with `_at` (`created_at`, `deleted_at`, `last_login_at`)
+
+## Primary Key Strategies
+
+| Strategy | Use When | Avoid When |
+|----------|----------|------------|
+| Auto-increment integer | Single-database apps, simple CRUD | Distributed systems, public-facing IDs |
+| UUID v4 | Distributed generation needed, merge safety | Storage-sensitive, need sortable IDs |
+| ULID / UUID v7 | Need sortable + distributed + compact | Legacy systems that expect integers |
+| Natural key | Data has a true natural identifier | Natural key might change |
+
+Default recommendation: auto-increment for internal apps, ULID for APIs and distributed systems.
+
+## Common Column Patterns
+
+**Soft deletes**: Add `deleted_at TIMESTAMP NULL` instead of physically deleting rows. Add a partial index: `CREATE INDEX idx_active_users ON users(id) WHERE deleted_at IS NULL;`
+
+**Polymorphic associations**: Prefer dedicated join tables over `type`/`id` column pairs. Polymorphic columns lose foreign key enforcement.
+
+**JSON columns**: Use for truly schemaless data (user preferences, external API payloads). Never for data you query by — that data belongs in proper columns with indexes.
+
+**Enums**: Prefer check constraints or reference tables over database-level enums. Enums are hard to modify in most databases.
+
+## Index Naming
+
+Pattern: `idx_{table}_{columns}_{type}`
+
+- `idx_users_email_unique`
+- `idx_orders_user_id_created_at`
+- `idx_products_name_gin` (for full-text search)
+
+## Migration Best Practices
+
+1. **One concern per migration**: Don't mix schema changes with data changes
+2. **Always reversible**: Every `up` must have a corresponding `down`
+3. **Expand-contract for breaking changes**:
+   - Migration 1: Add new column, backfill data
+   - Deploy: Update code to write to both old and new columns
+   - Migration 2: Remove old column
+4. **Test migrations on production-like data**: A migration that works on 100 rows might lock the table on 10 million rows
+5. **Avoid renaming columns in production**: Add new column, migrate data, drop old column

package/skills/data-modeling/templates/schema.md

@@ -0,0 +1,120 @@
+# Database Schema Templates
+
+PostgreSQL-focused. MySQL notes marked inline. Copy, rename, and remove the columns you don't need.
+
+---
+
+## Table Template
+
+```sql
+CREATE TABLE orders (
+  -- Primary key: use BIGSERIAL for high-volume tables, UUID for distributed/exposed IDs
+  id          BIGSERIAL    PRIMARY KEY,
+  -- id       UUID         PRIMARY KEY DEFAULT gen_random_uuid(),  -- UUID alternative
+
+  -- Foreign keys: explicit names, explicit ON DELETE behavior
+  user_id     BIGINT       NOT NULL REFERENCES users(id) ON DELETE RESTRICT,
+  status      TEXT         NOT NULL DEFAULT 'pending'
+                           CHECK (status IN ('pending', 'confirmed', 'cancelled', 'refunded')),
+  total_cents BIGINT       NOT NULL CHECK (total_cents >= 0),  -- store money as integer cents
+  notes       TEXT,                                            -- nullable: OK for optional fields
+
+  -- Audit timestamps: always include, always have defaults
+  created_at  TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
+  updated_at  TIMESTAMPTZ  NOT NULL DEFAULT NOW()
+  -- MySQL equivalent: DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+);
+
+-- updated_at trigger (PostgreSQL)
+CREATE OR REPLACE FUNCTION set_updated_at()
+RETURNS TRIGGER LANGUAGE plpgsql AS $$
+BEGIN NEW.updated_at = NOW(); RETURN NEW; END;
+$$;
+CREATE TRIGGER orders_set_updated_at
+  BEFORE UPDATE ON orders
+  FOR EACH ROW EXECUTE FUNCTION set_updated_at();
+```
+
+---
+
+## Index Conventions
+
+```sql
+-- Foreign key indexes: idx_<table>_<column>
+CREATE INDEX idx_orders_user_id ON orders (user_id);
+
+-- Composite index: match the query's WHERE + ORDER BY column order
+CREATE INDEX idx_orders_user_status ON orders (user_id, status);
+
+-- Partial index: index only the rows the query targets
+CREATE INDEX idx_orders_pending ON orders (created_at)
+  WHERE status = 'pending';
+
+-- Unique constraint (preferred over CREATE UNIQUE INDEX for constraints)
+ALTER TABLE orders ADD CONSTRAINT uq_orders_external_id UNIQUE (external_id);
+```
+
+> **Naming pattern:** `idx_<table>_<columns>` for regular indexes, `uq_<table>_<columns>` for unique constraints, `fk_<table>_<referenced_table>` for named FK constraints.
+
+---
+
+## Enum Patterns
+
+**Option A — PostgreSQL enum type** (fast, type-safe; hard to add values without migration):
+
+```sql
+CREATE TYPE order_status AS ENUM ('pending', 'confirmed', 'cancelled', 'refunded');
+ALTER TABLE orders ADD COLUMN status order_status NOT NULL DEFAULT 'pending';
+
+-- Adding a value later: ALTER TYPE order_status ADD VALUE 'on_hold';  (irreversible)
+```
+
+**Option B — Constrained VARCHAR** (flexible; tradeoff: constraint must be updated for new values):
+
+```sql
+ALTER TABLE orders ADD COLUMN status TEXT NOT NULL DEFAULT 'pending'
+  CHECK (status IN ('pending', 'confirmed', 'cancelled', 'refunded'));
+-- To add a value: ALTER TABLE orders DROP CONSTRAINT <constraint_name>, ADD CONSTRAINT ...
+```
+
+> **Rule of thumb:** Use Option A when the set is truly fixed (e.g., gender: M/F/other). Use Option B when the list may grow over time (e.g., order status, notification type).
+
+---
+
+## Migration File Template
+
+```sql
+-- migrations/20240315120000_add_orders_table.up.sql
+
+BEGIN;
+
+CREATE TABLE orders (
+  id         BIGSERIAL    PRIMARY KEY,
+  user_id    BIGINT       NOT NULL REFERENCES users(id) ON DELETE RESTRICT,
+  status     TEXT         NOT NULL DEFAULT 'pending'
+                          CHECK (status IN ('pending', 'confirmed', 'cancelled')),
+  total_cents BIGINT      NOT NULL CHECK (total_cents >= 0),
+  created_at TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ  NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX idx_orders_user_id ON orders (user_id);
+
+COMMIT;
+```
+
+```sql
+-- migrations/20240315120000_add_orders_table.down.sql
+
+BEGIN;
+
+DROP TABLE IF EXISTS orders;
+
+COMMIT;
+```
+
+> **Migration rules:**
+> - Filename: `<timestamp>_<description>.up.sql` / `.down.sql` — timestamp prefix ensures ordered application.
+> - Wrap in `BEGIN`/`COMMIT` so partial failures roll back.
+> - Down migration must completely undo the up migration.
+> - Backwards-compatible changes (ADD COLUMN with default) are safe to apply before deploying code. Breaking changes (DROP COLUMN, rename) require expand-contract: add new → migrate data → remove old.