swe-workflow-skills 0.1.0

package/skills/code-reviewing/references/review-checklist.md

@@ -0,0 +1,144 @@
+# Code Review Checklist
+
+## Contents
+- Design principles checklist
+- Security checklist
+- Testing checklist
+- Common patterns to flag
+- Language-specific patterns
+
+## Design Principles Checklist
+
+### DRY (Don't Repeat Yourself)
+Flag when you see:
+- Same logic in multiple places (even if slightly different — the variations often indicate a missing abstraction)
+- Copy-pasted code blocks with minor modifications
+- Same validation rules implemented in multiple layers without a shared source
+
+Don't flag:
+- Similar code that represents genuinely different concepts (false DRY is worse than repetition)
+- Test code that repeats setup (test readability trumps DRY)
+
+### KISS (Keep It Simple, Stupid)
+Flag when you see:
+- Abstraction without a second consumer (premature abstraction)
+- Design patterns used where a simple function would suffice
+- Complex type gymnastics when a straightforward type would work
+- Nested ternaries or complex boolean expressions that need a comment to understand
+- Over-engineered configuration when values could be constants
+
+### YAGNI (You Aren't Gonna Need It)
+Flag when you see:
+- Unused parameters, methods, classes, or exports
+- Configuration for hypothetical future features
+- Abstraction layers "in case we swap implementations"
+- Generic solutions for a problem that currently has one case
+- Comments like "we might need this later"
+
+### SRP (Single Responsibility Principle)
+Flag when you see:
+- Functions longer than ~30 lines (not a hard rule, but a signal)
+- Functions that do AND/THEN logic: "validate AND save AND notify"
+- Classes with methods that use disjoint subsets of the class's fields
+- Files that are the go-to place for "anything related to X"
+- Mix of business logic and I/O in the same function
+
+### Naming Quality
+Flag when you see:
+- Names that require reading the implementation to understand (`data`, `info`, `temp`, `result`, `handle`)
+- Disinformation: names that imply something incorrect (`accountList` when it's actually a map, `hp` that could mean hypotenuse or hit points)
+- Single-letter variables outside of tiny lambda/loop scopes
+- Abbreviations that aren't universally understood in the domain
+- Class names that aren't nouns or noun phrases (`ProcessData`, `ManageStuff`)
+- Method names that aren't verb phrases (`data()` instead of `fetchData()`, `valid()` instead of `isValid()`)
+- Inconsistent vocabulary: `fetch` in one place, `get` in another, `retrieve` in a third for the same concept
+- Names that differ only in capitalization or by a number suffix (`user1`, `user2`)
+
+Don't flag:
+- Short names in tiny scopes where context is obvious (`i` in a 3-line loop, `e` in a catch block)
+- Domain abbreviations the team has agreed on (`DTO`, `API`, `URL`)
+
+### Function Size and Structure
+Flag when you see:
+- Functions that do more than one thing — look for sections separated by blank lines or comments, each doing a different job
+- Mixed levels of abstraction in one function: high-level orchestration mixed with low-level bit manipulation or string parsing
+- More than 2-3 function arguments — flag especially if several are the same type (easy to mix up)
+- Side effects hidden behind the function name: a function called `checkPermission` that also logs analytics and updates a timestamp
+- **Command-Query Separation violations**: A method that both changes state AND returns a value. Methods should either be commands (do something, return void) or queries (return something, change nothing). Mixing them surprises callers and makes code harder to reason about.
+
+### Functional Independence
+Flag when you see:
+- Modules reaching into other modules' internals
+- Shared mutable state between components
+- Functions that require knowledge of the caller's context
+- Temporal coupling (function A must be called before function B with nothing enforcing this)
+
+## Security Checklist
+
+- [ ] User input is validated/sanitized before use
+- [ ] SQL queries use parameterized statements (no string concatenation)
+- [ ] Auth checks are present on protected endpoints
+- [ ] Sensitive data is not logged or exposed in error messages
+- [ ] No hardcoded secrets, API keys, or credentials
+- [ ] File paths are validated (no path traversal)
+- [ ] Rate limiting considered for public endpoints
+- [ ] CORS configuration is explicit, not wildcard
+
+## Testing Checklist
+
+- [ ] New behavior has corresponding tests
+- [ ] Tests cover the happy path
+- [ ] Tests cover at least one error/edge case
+- [ ] Tests are independent (no shared mutable state)
+- [ ] Test names describe the behavior being tested
+- [ ] No logic in tests (no if/else, no loops)
+- [ ] No tests that merely re-verify third-party library behavior (e.g. asserting a compression lib's magic bytes or compression ratio, or that an ORM persists a row) — tests target our own logic and our boundary with the library, not what the vendor's own tests already cover
+- [ ] Mocks/stubs are used appropriately (not over-mocked)
+- [ ] Integration tests exist for cross-boundary interactions
+
+## Common Patterns to Flag
+
+**Boolean blindness**: A function taking multiple boolean parameters. Prefer named options or enum types.
+
+**Stringly typed**: Using strings where enums, constants, or types would prevent errors at compile time.
+
+**Train wreck**: Long method chains like `user.getProfile().getAddress().getCity().toLowerCase()`. Each dot is a coupling point.
+
+**Primitive obsession**: Passing raw strings/numbers when a domain type (EmailAddress, Money, UserId) would add safety and clarity.
+
+**Feature envy**: A method that uses more data from another class than from its own. The method probably belongs in the other class.
+
+**Shotgun surgery**: One logical change requires modifications across many files. Indicates poor encapsulation.
+
+**Data clumps**: The same group of variables appears together in multiple places (e.g., `x, y, z` or `street, city, zip`). Extract them into a class or struct.
+
+**Middle man**: A class that delegates almost everything to another class without adding value. Inline the delegation.
+
+**Inappropriate intimacy**: Two classes that access each other's private details excessively. Restructure to restore proper boundaries.
+
+## Comments: Good vs Bad
+
+**Good comments** (keep them):
+- Intent explanation: *why* a non-obvious approach was chosen
+- Consequence warnings: "changing this format breaks the mobile parser"
+- TODO with ticket reference: `// TODO(PROJ-123): replace with batch API when available`
+- Legal or licensing notices required by policy
+
+**Bad comments** (flag them):
+- Redundant comments that restate the code: `// increment counter` above `counter++`
+- Commented-out code — it lives in version control, delete it
+- Journal comments ("added on 2024-01-15 by Alice") — git log handles this
+- Mandated javadoc/docstrings on every function regardless of complexity — these go stale and add noise
+- Misleading comments that don't match what the code does
+
+**Rule**: If code needs a comment to explain *what* it does, refactor the code so it doesn't need one. Comments should explain *why*, not *what*.
+
+## Language-Specific Patterns
+
+These are loaded contextually based on the codebase language. If reviewing:
+
+- **JavaScript/TypeScript**: Watch for `any` types, missing null checks, callback hell, missing async error handling, loose equality (== vs ===)
+- **Python**: Watch for mutable default arguments, bare except clauses, circular imports, missing type hints on public APIs
+- **Go**: Watch for ignored errors, goroutine leaks, missing context propagation, sync issues
+- **Rust**: Watch for unnecessary clones, unwrap in non-test code, missing error context
+- **Java**: Watch for null returns without Optional, checked exception abuse, mutable shared state

package/skills/configuration-strategy/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: configuration-strategy
+description: "Design environment configuration, secrets management, and feature-flag hierarchy for a service or feature. Triggers: config strategy, environment variables, .env, secrets management, feature flag, config hierarchy, config precedence, twelve-factor config, environment-specific settings."
+model: haiku
+allowed-tools: Read, Grep, Glob, Write, Edit
+---
+
+# Configuration Strategy
+
+Design configuration that is safe, auditable, and easy to change. Most configuration problems (hardcoded secrets, production config in dev, feature flags with no off-switch) come from not designing the system upfront.
+
+## Step 1: Identify All Configuration Needed
+
+List every piece of configuration the feature or service requires:
+
+- **Service endpoints**: URLs for external APIs, internal services, databases
+- **Credentials and secrets**: API keys, database passwords, signing keys, certificates
+- **Behavior toggles**: Feature flags, A/B test parameters, rate limits, timeouts
+- **Static config**: Timeouts, retry counts, pagination defaults, log levels
+- **Environment-specific values**: Different database URLs for dev/staging/prod
+
+Don't leave any implicit. "We'll hard-code the staging URL for now" is the start of a production incident.
+
+## Step 2: Classify Each Configuration Item
+
+For each item, determine:
+
+**Sensitivity:**
+- **Secret**: Must never appear in logs, code, or non-encrypted storage (API keys, passwords, tokens)
+- **Sensitive**: Not a secret but not public (internal service URLs, customer IDs)
+- **Non-sensitive**: Safe to log, safe in version control (log levels, timeouts, feature flag names)
+
+**Mutability:**
+- **Static**: Set at deploy time, doesn't change without a redeploy (database schema version, service name)
+- **Runtime-mutable**: Can change without redeploy (feature flags, rate limits, A/B test parameters)
+
+**Scope:**
+- **Global**: Same value in all environments (timeout constants, algorithm parameters)
+- **Environment-specific**: Different per env (database URLs, API endpoints, log levels)
+- **Per-tenant/per-user**: Different per customer (feature entitlements, custom limits)
+
+## Step 3: Design the Configuration Hierarchy
+
+Based on classification, assign each item to the right storage:
+
+| Storage | For | Examples |
+|---------|-----|---------|
+| Environment variables | Environment-specific non-secrets | DATABASE_URL, SERVICE_ENV, LOG_LEVEL |
+| Secrets manager | All secrets | Database passwords, API keys, signing keys |
+| Feature flag service | Runtime-mutable toggles | Feature flags, A/B variants, rollout percentages |
+| Config file in repo | Non-sensitive static config | Timeout constants, retry policies, allowed values |
+| Database (config table) | Per-tenant/per-user config | Customer-specific rate limits, feature entitlements |
+
+**Hierarchy principle**: More specific overrides less specific. Per-tenant overrides environment which overrides global default.
+
+See [references/config-patterns.md](references/config-patterns.md) for feature flag design patterns and secrets management tool guidance.
+
+## Step 4: Plan Safe Config Rollout
+
+Configuration changes can cause outages just like code changes. Plan rollout for each type:
+
+**Secrets rotation:**
+1. Generate new secret while old one remains valid
+2. Deploy application with new secret
+3. Verify application uses new secret correctly
+4. Revoke old secret (after 24-hour overlap window)
+
+**Feature flag rollout:**
+1. Start at 0% — verify flag infrastructure works
+2. Enable for internal users — catch obvious breakage
+3. Enable for small percentage (5-10%) — monitor metrics
+4. Ramp up gradually — verify metrics hold at each step
+5. Full rollout — verify, then clean up the flag
+
+**Environment variable changes:**
+- New variables: set in target environment *before* deploying code that reads them
+- Changed values: consider backward compatibility with old code during rolling deploys
+- Removed variables: remove from code *before* removing from environment config
+
+## Step 5: Audit Existing Code for Anti-patterns
+
+Review the codebase for common configuration mistakes:
+
+**Hardcoded values to find and fix:**
+- IP addresses, hostnames, port numbers (search: `localhost`, `127.0.0.1`, regex for IP patterns)
+- Credentials (search: `password`, `secret`, `api_key`, `token` in string literals)
+- Environment-specific constants (search for strings that differ between environments)
+- Magic numbers that should be configurable (search for hardcoded timeouts, limits, batch sizes)
+
+**Config anti-patterns:**
+- Feature flags that have been "on" everywhere for 6+ months (dead code risk — remove the flag)
+- Config values read but never validated (add startup validation that fails fast on missing config)
+- Different config loading paths for test vs production (leads to "works in tests but not prod")
+- Secrets passed via command-line arguments (visible in process lists)
+
+## Principles Applied
+
+- **DRY**: Single source of truth for each config value. If the same value appears in multiple places, it will drift.
+- **KISS**: Flat config beats deeply nested config. Environment variables beat custom config DSLs.
+- **Least privilege**: Services should only have access to the secrets they need. Database credentials shouldn't be shared across services.
+- **YAGNI**: Don't create config variables for things that will never change. Hard-code what's truly constant.
+- **Fail fast**: Validate all required config on startup. A crash at startup is better than a mysterious failure 10 minutes in.
+
+## Cross-Skill References
+
+- `feature-planning` — decide which behaviors will be feature-flagged during planning, before implementation
+- `security-audit` — review secrets handling and access control as part of security review
+- `deployment-checklist` — verify all config is set before deploying
+- `rollback-strategy` — feature flags are the simplest rollback mechanism; design them accordingly

package/skills/configuration-strategy/evals/evals.json

@@ -0,0 +1,41 @@
+{
+  "skill_name": "configuration-strategy",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I'm adding a payment integration to our app. We'll need a Stripe API key, a webhook secret, and a flag to enable the new checkout flow for a gradual rollout. How should I manage this configuration?",
+      "expected_output": "Configuration strategy covering secrets (Stripe key, webhook secret → secrets manager), feature flag (new checkout → percentage rollout), and environment variable design with a phased rollout plan",
+      "assertions": [
+        "Identifies Stripe API key and webhook secret as secrets, recommends secrets manager not env var",
+        "Recommends feature flag for the checkout rollout, not a hard env var switch",
+        "Suggests percentage-based rollout for the feature flag",
+        "Warns against committing any credential to version control",
+        "Recommends startup validation to fail fast if secrets are missing",
+        "Notes different values needed for dev/staging/production"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Audit this Python file for configuration anti-patterns:\n\nDB_URL = 'postgresql://admin:password123@prod-db.internal:5432/myapp'\nAPI_TIMEOUT = 30\nDEBUG = True\nSTRIPE_KEY = 'sk_live_abc123xyz'\nRATELIMIT = 100",
+      "expected_output": "Identifies hardcoded credentials (DB_URL with password, STRIPE_KEY), hardcoded production hostname, and DEBUG=True as anti-patterns, with specific remediation for each",
+      "assertions": [
+        "Flags DB_URL as critical: contains hardcoded password and production hostname",
+        "Flags STRIPE_KEY as critical: live API key hardcoded in source",
+        "Flags DEBUG=True as problematic for production environments",
+        "Notes that API_TIMEOUT and RATELIMIT are acceptable as constants or could be made configurable",
+        "Recommends secrets manager or environment variables for the credentials",
+        "Recommends .env.example to document these variables without committing values"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "What's the best way to set up Terraform configuration for our infrastructure?",
+      "expected_output": "Recognizes this is an infrastructure-as-code question, not primarily a configuration strategy question — may address env var and secrets aspects but should note that IaC configuration patterns are covered by infrastructure-as-code skill",
+      "assertions": [
+        "Addresses the secrets/variable management aspects that overlap with config strategy",
+        "Recognizes that Terraform-specific patterns (workspaces, modules, state management) are better handled by the infrastructure-as-code skill",
+        "Does not attempt to be a comprehensive Terraform guide"
+      ]
+    }
+  ]
+}

package/skills/configuration-strategy/references/config-patterns.md

@@ -0,0 +1,161 @@
+# Configuration Patterns
+
+## Feature Flag Patterns
+
+### Boolean flags (on/off)
+Simplest form. Use for new features, kill switches, and emergency toggles.
+
+```python
+if feature_flags.is_enabled("new_checkout_flow"):
+    return new_checkout()
+return legacy_checkout()
+```
+
+**Cleanup discipline**: Set a removal date when creating the flag. Flags that are "on everywhere" for 6+ months are dead code. Schedule a cleanup sprint quarterly.
+
+### Percentage rollout flags
+For gradual rollouts. Route by user ID (not random) to ensure consistent experience per user.
+
+```python
+def should_show_feature(user_id: int, flag_name: str, percentage: int) -> bool:
+    # Consistent hash ensures same user always gets same result
+    bucket = hash(f"{flag_name}:{user_id}") % 100
+    return bucket < percentage
+```
+
+### Targeting flags
+Enable for specific users, accounts, or segments. Common for:
+- Beta testers / early access
+- Internal employees
+- Enterprise customers with specific entitlements
+- A/B test groups
+
+### Config flags (non-boolean)
+For tunable parameters: rate limits, batch sizes, timeout values. Enable runtime tuning without redeploys.
+
+```python
+RATE_LIMIT_PER_MINUTE = config.get_int("api_rate_limit_per_minute", default=100)
+```
+
+---
+
+## Secrets Management
+
+### What counts as a secret
+- Database credentials (username + password)
+- API keys and tokens (any key that grants access to an external service)
+- Signing keys and certificates (JWT signing keys, TLS private keys, HMAC secrets)
+- Encryption keys
+- OAuth client secrets
+
+**Not secrets** (but still environment-specific): Database hostnames, service URLs, log levels, feature flag names.
+
+### Secrets manager tools
+
+| Tool | Best for | Notes |
+|------|----------|-------|
+| AWS Secrets Manager | AWS-hosted apps | Native AWS integration, automatic rotation support |
+| HashiCorp Vault | Multi-cloud, self-hosted | Most flexible; steeper ops overhead |
+| GCP Secret Manager | GCP-hosted apps | Native GCP integration |
+| Azure Key Vault | Azure-hosted apps | Native Azure integration |
+| Doppler | Any cloud, simpler UX | Good for small teams, syncs to env vars |
+
+### Accessing secrets at runtime
+
+**Preferred: inject as environment variables at container/process startup**
+```bash
+# Kubernetes (via external-secrets operator or equivalent)
+env:
+  - name: DATABASE_PASSWORD
+    valueFrom:
+      secretKeyRef:
+        name: db-credentials
+        key: password
+```
+
+**Acceptable: read from secrets manager SDK at startup, cache in memory**
+```python
+import boto3
+secrets = boto3.client('secretsmanager')
+DB_PASSWORD = secrets.get_secret_value(SecretId='prod/db/password')['SecretString']
+```
+
+**Never: hardcode in source, store in `.env` files committed to version control, pass via CLI argument**
+
+### Startup validation pattern
+Fail fast on missing config at application startup:
+
+```python
+def validate_config():
+    required = ['DATABASE_URL', 'API_KEY', 'JWT_SECRET']
+    missing = [key for key in required if not os.environ.get(key)]
+    if missing:
+        raise EnvironmentError(f"Missing required config: {', '.join(missing)}")
+
+# Call before any application code runs
+validate_config()
+```
+
+---
+
+## Environment Hierarchy
+
+### Typical environment chain
+```
+local dev → CI → staging → production
+```
+
+Each environment should have a complete, independent configuration. Avoid sharing config between environments — shared config leads to "it works in staging because staging reads prod's config."
+
+### Config loading priority (highest to lowest)
+1. Environment variables (set by the runtime environment)
+2. `.env.local` (local developer overrides, never committed)
+3. `.env.[environment]` (environment-specific committed defaults, no secrets)
+4. `.env` (shared defaults, no secrets)
+5. Hard-coded defaults in application code
+
+### What belongs in version control
+
+| File | Purpose | Secrets? | Commit? |
+|------|---------|---------|---------|
+| `.env.example` | Documents all required vars with example values | No | Yes |
+| `.env.development` | Dev defaults, no real secrets | No | Yes |
+| `.env.staging` | Staging non-secrets | No | Yes |
+| `.env` | Local overrides | No | No (add to .gitignore) |
+| `.env.local` | Personal dev overrides | No | No |
+| `.env.production` | Never — use secrets manager | — | Never |
+
+---
+
+## Config Validation Patterns
+
+### Type-safe config with validation
+
+```typescript
+// TypeScript example with runtime validation
+const config = {
+  port: parseInt(process.env.PORT ?? '3000', 10),
+  databaseUrl: requireEnv('DATABASE_URL'),
+  jwtSecret: requireEnv('JWT_SECRET'),
+  logLevel: process.env.LOG_LEVEL ?? 'info',
+  featureFlagServiceUrl: process.env.FEATURE_FLAG_URL ?? null,
+};
+
+function requireEnv(key: string): string {
+  const value = process.env[key];
+  if (!value) throw new Error(`Required environment variable ${key} is not set`);
+  return value;
+}
+```
+
+### Config schema documentation
+
+Document every config variable. Keep this in sync with `.env.example`:
+
+```
+DATABASE_URL            Required. PostgreSQL connection string.
+                        Format: postgres://user:pass@host:port/dbname
+JWT_SECRET              Required. Min 32 chars. Used to sign auth tokens.
+LOG_LEVEL               Optional. Default: 'info'. Values: debug|info|warn|error
+FEATURE_FLAG_URL        Optional. LaunchDarkly SDK URL. Feature flags disabled if unset.
+```

package/skills/containerization/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: containerization
+description: "Write production-grade Dockerfiles, docker-compose, and Kubernetes manifests following security and reliability best practices. Triggers: Dockerfile, docker-compose, containerize, Docker image, Kubernetes, k8s manifest, container, pod, deployment yaml, multi-stage build, docker build, image size, container security."
+model: sonnet
+allowed-tools: Read, Grep, Glob, Write, Edit, Bash
+---
+
+# Containerization
+
+Write production-quality container configurations — Dockerfiles, compose files, and Kubernetes manifests — that are secure, efficient, and reproducible.
+
+## Workflow: Dockerfile
+
+### Step 1: Understand the Application
+
+Before writing a Dockerfile, establish:
+
+- **Runtime**: Node.js, Python, Go, Java, etc. and specific version
+- **Build process**: Does it need compilation, asset bundling, dependency installation?
+- **Runtime dependencies**: System packages, native libraries
+- **Entry point**: What command starts the application?
+- **Configuration**: Environment variables, config files, secrets
+
+### Step 2: Write the Dockerfile
+
+Follow these principles in order of importance:
+
+**1. Use multi-stage builds** — Separate build dependencies from the runtime image. Build artifacts in one stage, copy only what's needed to a slim final stage.
+
+**2. Pin base image versions** — Never use `latest`. Use specific digests or version tags: `node:20.11-alpine3.19`, not `node:latest`.
+
+**3. Minimize layers and image size** — Combine related RUN commands with `&&`. Use Alpine or distroless base images. Remove package manager caches after install.
+
+**4. Order for cache efficiency** — Place infrequently changing instructions (system deps) before frequently changing ones (application code). Copy dependency manifests before source code.
+
+**5. Run as non-root** — Create a dedicated user and switch to it. Never run production containers as root.
+
+**6. Use .dockerignore** — Exclude node_modules, .git, .env, test files, docs from the build context.
+
+Use [templates/dockerfile.md](templates/dockerfile.md) as a starting point for Node.js, Python, Go, and docker-compose configurations.
+
+### Step 3: Validate
+
+- [ ] Image builds successfully
+- [ ] Image size is reasonable for the application type
+- [ ] Container runs as non-root user
+- [ ] No secrets baked into the image (check with `docker history`)
+- [ ] Health check is defined
+- [ ] .dockerignore excludes unnecessary files
+
+## Workflow: Docker Compose (Local Development)
+
+Design compose files that give developers a one-command local environment:
+
+- All services defined (app, database, cache, queue)
+- Volumes for hot-reload development
+- Named volumes for data persistence across restarts
+- Environment variables with sensible defaults via `.env.example`
+- Health checks and dependency ordering (`depends_on` with `condition: service_healthy`)
+- Port mappings that avoid common conflicts
+
+See [references/dockerfile-patterns.md](references/dockerfile-patterns.md) for compose patterns.
+
+## Workflow: Kubernetes Manifests
+
+When creating K8s deployments:
+
+1. **Define resource requests and limits** — Always. Without them, a single pod can starve the cluster.
+2. **Configure health probes** — Liveness (is the process alive?), readiness (can it serve traffic?), startup (for slow-starting apps).
+3. **Use ConfigMaps and Secrets** — Never hardcode configuration in manifests.
+4. **Set pod disruption budgets** — For availability during upgrades.
+5. **Use namespaces** — Isolate environments (dev, staging, prod) and teams.
+6. **Define HPA** — Horizontal pod autoscaling based on CPU/memory or custom metrics.
+
+## When to Use Helm or Kustomize
+
+For multi-environment deployments or when using a deployment repo pattern, plain manifests become hard to manage. Choose based on your needs:
+
+- **Plain manifests**: Single environment, few resources, no templating needed. Start here.
+- **Kustomize**: Multiple environments with small differences (replicas, resource limits, image tags). Uses patches over a base — no templating language to learn.
+- **Helm**: Complex deployments with many configurable parameters, or when you need to package charts for reuse. More powerful but more complexity.
+
+See `deployment-repo` for organizing Helm charts and Kustomize overlays in a deployment repo, and `gitops-delivery` for using them with ArgoCD or Flux.
+
+## Principles Applied
+
+- **KISS**: Start with the simplest configuration that works. Single-stage Docker build before multi-stage. Docker Compose before Kubernetes.
+- **DRY**: Use build args and env vars to parameterize, not duplicate Dockerfiles per environment.
+- **Security by default**: Non-root, minimal image, no secrets in layers, read-only filesystem where possible.
+- **YAGNI**: Don't add Kubernetes if Docker Compose serves your scale. Don't add Helm charts if plain manifests suffice.

package/skills/containerization/evals/evals.json

@@ -0,0 +1,36 @@
+{
+  "skill_name": "containerization",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Containerize my Express.js API. It uses Node 20, has a build step (TypeScript), connects to PostgreSQL and Redis, and needs to run in production on Kubernetes.",
+      "expected_output": "Should produce a multi-stage Dockerfile, .dockerignore, docker-compose for local dev, and basic K8s deployment manifest. All following security and efficiency best practices.",
+      "assertions": [
+        "Uses multi-stage build (builder + production stages)",
+        "Pins Node version (not latest)",
+        "Copies package files before source code for cache efficiency",
+        "Uses npm ci (not npm install)",
+        "Runs as non-root user",
+        "Includes HEALTHCHECK",
+        "Creates .dockerignore excluding node_modules, .git, tests",
+        "Docker-compose includes PostgreSQL and Redis with health checks",
+        "K8s manifest includes resource limits, liveness/readiness probes"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Review this Dockerfile:\n\nFROM node:latest\nWORKDIR /app\nCOPY . .\nRUN npm install\nRUN npm run build\nENV DB_PASSWORD=mysecret123\nEXPOSE 3000\nCMD [\"node\", \"dist/index.js\"]",
+      "expected_output": "Should identify all issues: latest tag, no multi-stage, copies everything before deps, npm install not ci, secret in ENV, runs as root, no healthcheck, no .dockerignore.",
+      "assertions": [
+        "Flags 'latest' tag as unreproducible",
+        "Flags secret in ENV layer as critical security issue",
+        "Flags running as root",
+        "Recommends multi-stage build",
+        "Recommends copying package files before source",
+        "Recommends npm ci over npm install",
+        "Recommends adding HEALTHCHECK",
+        "Provides a corrected Dockerfile"
+      ]
+    }
+  ]
+}