@brunosps00/dev-workflow 0.7.0 → 0.8.1

package/scaffold/skills/api-testing-recipes/references/openapi-driven.md

@@ -0,0 +1,97 @@
+# OpenAPI-driven mode — generating tests from a spec
+
+When the project exposes an OpenAPI spec (static `openapi.yaml`/`openapi.json`, or dynamic `/openapi.json` for FastAPI), `/dw-run-qa` can derive a baseline test suite directly from it. This catches contract drift between code and spec for free.
+
+## When to use this mode
+
+- The project already maintains an OpenAPI spec — either hand-written, generated from code annotations (FastAPI, NestJS + `@nestjs/swagger`, dotnet Swashbuckle), or synced via a code generator.
+- You want a quick "is this endpoint reachable AND does its response shape match the spec?" check.
+- You want to detect when code drifts ahead of (or behind) the spec.
+
+## What it generates
+
+For each path × method in the spec:
+
+1. A **happy-path test** using the spec's `requestBody` example (or schema-derived sample).
+2. A **contract-shape test** asserting the response matches the documented schema.
+3. Skips paths/methods marked with the `x-internal: true` extension or those without examples.
+
+The generated tests live alongside hand-written ones in `{{PRD_PATH}}/QA/scripts/api/`. Filename pattern: `openapi-RF-XX-[path-slug].http` (or stack-specific extension).
+
+## How to run it
+
+`/dw-run-qa --from-openapi <spec-path-or-url>` — explicit. The `<spec-path-or-url>` can be:
+
+- `./openapi.yaml`
+- `http://localhost:3000/openapi.json` (FastAPI default)
+- `http://localhost:3000/swagger/v1/swagger.json` (ASP.NET Core default)
+
+Without the flag, `/dw-run-qa` auto-detects:
+
+- File at repo root: `openapi.yaml`, `openapi.json`, `swagger.yaml`, `swagger.json`.
+- Project running locally: `GET /openapi.json`, `GET /swagger/v1/swagger.json`, `GET /api-docs`.
+
+If found, the agent asks: "OpenAPI spec detected at `<path>`. Generate baseline tests from it? [y/n]". On `y`, the baseline is added on top of the PRD-derived matrix.
+
+## Mapping spec endpoints to RFs
+
+The PRD names requirements (`RF-01`, `RF-02`); the spec names paths (`/users`, `/orders/{id}`). Two conventions for cross-referencing:
+
+- **By tag**: tests for a path tagged `users` map to the PRD section also tagged `users`. Cleanest if the project keeps tags consistent.
+- **By summary keyword**: the spec's `summary` field is matched against PRD requirement titles. Less reliable; only use as a fallback.
+
+If neither matches, the test lands as `openapi-no-rf-[slug].http` and the QA report flags it as "spec endpoint not mapped to any RF — possible documentation gap."
+
+## Contract drift detection
+
+For each response from a generated test, compare:
+
+1. **Status code** — does the actual status appear in the spec's `responses` block?
+2. **Required fields** — every field marked `required: true` in the schema must be present.
+3. **Type matching** — `email: string` in spec, but actual is `email: null`? Fail.
+4. **No leaked fields** — fields NOT in the spec but present in the response are flagged as **drift forward** (code added a field; spec is stale).
+5. **Sensitive defaults** — fields named `password*`, `secret*`, `token*`, `*_hash` in the response trigger an immediate FAIL with severity HIGH, even if they're "documented."
+
+## Generating example payloads
+
+If the spec has `example` or `examples`, use them verbatim. If only schemas exist, sample using a deterministic strategy:
+
+| JSON Schema type | Sample value |
+|-------|-------|
+| `string` | `"qa-string"` (or `"qa@example.com"` if `format: email`, ISO date if `format: date-time`, UUID v4 if `format: uuid`) |
+| `integer` | `1` (or value within `minimum`/`maximum` if set) |
+| `number` | `1.0` |
+| `boolean` | `true` |
+| `array` | one element of the inner type |
+| `object` | recurse on `properties`; only include `required` fields |
+| `enum` | first value |
+| `oneOf`/`anyOf` | first variant |
+
+Skip endpoints whose request shape can't be sampled deterministically (e.g., free-form JSON without schema, file uploads requiring real binary data).
+
+## What NOT to do
+
+- **Don't replace the PRD-derived matrix with OpenAPI-only tests.** OpenAPI tells you what the code claims to do; the PRD tells you what the product needs. Both matter. Keep both.
+- **Don't trust the spec implicitly.** If `dw-run-qa` finds 0 drift on day 1 and the team has been shipping for 6 months, the spec is probably stale, not the code. Flag the suspicion in the QA report.
+- **Don't generate tests for `x-internal: true` endpoints.** Those are behind an internal-network boundary; QA on them needs different credentials and risk profile.
+
+## Limitations
+
+- Doesn't generate authorization tests automatically (the spec doesn't say "this endpoint should reject other-tenant tokens"). Hand-write those per the cross-tenant pattern in `matrix-conventions.md`.
+- Doesn't generate state-mutating sequences (create → update → delete). Those need PRD context to know what state matters.
+- Treats the spec as authoritative for contract drift, but not for behavior. A spec that's wrong is still going to fail tests against correct code — and that's the right outcome. Update the spec.
+
+## What `dw-run-qa` produces
+
+When OpenAPI mode runs, the QA report gains a section:
+
+```markdown
+## OpenAPI baseline
+
+- Spec source: openapi.yaml (53 paths, 121 operations)
+- Endpoints sampled: 89 (32 skipped: missing examples, file uploads, `x-internal`)
+- Drift detected: 4 endpoints (see RF-12, RF-15, RF-22, openapi-no-rf-internal-metrics)
+- Contract issues:
+  - RF-12 — `email` documented as required, response returns null
+  - openapi-no-rf-internal-metrics — endpoint exists in spec but no PRD reference
+```

package/scaffold/skills/docker-compose-recipes/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: docker-compose-recipes
+description: Validated docker-compose service blocks (postgres, redis, mailhog, minio, meilisearch, jaeger, traefik, etc.) for dev and prod, composed by /dw-new-project and /dw-dockerize. Each service is a standalone YAML with healthcheck, named volume, and env conventions.
+allowed-tools:
+  - Read
+  - Write
+  - Grep
+  - Glob
+---
+
+# docker-compose-recipes
+
+This skill is a curated library of **validated `docker-compose` service blocks** that other dev-workflow commands (`/dw-new-project`, `/dw-dockerize`) merge into a final `docker-compose.dev.yml` or `docker-compose.prod.yml`.
+
+## Why a skill (not a template)
+
+- Each service file is independently maintainable. Bumping Postgres from 16 to 17 is a one-file change.
+- Discoverable by AI agents in any project the user installs dev-workflow into — they can read the recipes when reasoning about local infra.
+- Reusable by future commands (e.g., `dw-add-service`, `dw-bench-services`) without duplication.
+
+## When to Use
+
+Read this skill when:
+
+- Composing `docker-compose.*.yml` for a new project (`/dw-new-project`).
+- Adding services to an existing project (`/dw-dockerize`, `--audit` mode).
+- Answering user questions about which Docker image / version / healthcheck to use for a given service.
+- Producing `.env.example` entries that match the env vars expected by these services.
+
+Do NOT use when:
+
+- The user asks for a service NOT in `services/` — propose the user add a new recipe to this skill instead of inventing a one-off block.
+- The project does not need containerized infra (e.g., serverless-only, already-managed cloud DB).
+
+## How to Compose
+
+1. **Pick the services** the user selected during the interview (or detected by `/dw-dockerize`).
+2. **Read each `services/<name>.yml`** as a standalone block. Each file declares ONE top-level service.
+3. **Merge into the final compose file** by appending each block under a single `services:` map. Reuse the same volume name across services that share storage (rare).
+4. **Resolve port conflicts**: the recipes use widely-used defaults; if multiple services collide (e.g., two HTTP UIs on 8080), shift the second one in the merged compose and add a note in the README port table.
+5. **Wire env vars**: every recipe references `.env`-style variables. Consolidate them into the project's single `.env.example` using the conventions in `references/env-conventions.md`.
+6. **Healthchecks**: each recipe includes a healthcheck. Other services that depend on it should declare `depends_on: { <name>: { condition: service_healthy } }`. See `references/healthcheck-patterns.md`.
+7. **Dev vs Prod**: recipes default to dev (bind mounts, exposed ports, no restart policy). For prod, apply the transforms in `references/prod-vs-dev.md` (named volumes, internal ports, `restart: unless-stopped`, secrets via env, no UI exposure unless behind a proxy).
+
+## Available Services
+
+Each row points to `services/<name>.yml`.
+
+| Service | Use | Default port(s) | Recipe |
+|---------|-----|-----------------|--------|
+| Postgres 16 (alpine) | Relational DB | `5432` | `services/postgres.yml` |
+| MySQL 8 | Relational DB | `3306` | `services/mysql.yml` |
+| Redis 7 (alpine) | Cache, pub/sub, BullMQ backend | `6379` | `services/redis.yml` |
+| Memcached 1.6 (alpine) | Cache | `11211` | `services/memcached.yml` |
+| RabbitMQ 3 (management-alpine) | Message broker + UI | `5672`, UI `15672` | `services/rabbitmq.yml` |
+| LocalStack | AWS-compatible local (S3, SQS, SNS, DynamoDB) | `4566` | `services/localstack.yml` |
+| MailHog | Default email-in-dev (capture only, never sends) | SMTP `1025`, UI `8025` | `services/mailhog.yml` |
+| Mailpit | Modern MailHog alternative | SMTP `1025`, UI `8025` | `services/mailpit.yml` |
+| smtp4dev | Windows-friendly SMTP capture | SMTP `2525`, UI `5000` | `services/smtp4dev.yml` |
+| MinIO | S3-compatible local | API `9000`, UI `9001` | `services/minio.yml` |
+| Meilisearch | Search engine (lightweight) | `7700` | `services/meilisearch.yml` |
+| Typesense | Search engine alternative | `8108` | `services/typesense.yml` |
+| Elasticsearch 8 | Search engine (heavyweight) | `9200` | `services/elasticsearch.yml` |
+| Jaeger all-in-one | OTel collector + UI | OTLP `4317`/`4318`, UI `16686` | `services/jaeger.yml` |
+| Traefik 3 | Reverse proxy + dev TLS | HTTP `80`, HTTPS `443`, dashboard `8080` | `services/traefik.yml` |
+
+## References
+
+- `references/compose-composition.md` — how to merge recipes into a single `docker-compose.dev.yml`.
+- `references/env-conventions.md` — how env var names are normalized (e.g., `POSTGRES_USER` → also exposed as `DATABASE_URL` for app code).
+- `references/healthcheck-patterns.md` — what each service's healthcheck looks like and how to chain `depends_on`.
+- `references/prod-vs-dev.md` — what changes when a recipe goes to `docker-compose.prod.yml`.
+
+## Rules
+
+- **Pin major.minor** in every `image:` line. Patch updates are safe; major bumps are deliberate.
+- **Always include healthcheck**. No service is allowed to be opaque about readiness.
+- **Default to dev**. Prod transforms are explicit (see `prod-vs-dev.md`).
+- **Email-in-dev defaults to MailHog**. The user must opt OUT of capture-only email for dev — never silently route to a real SMTP.
+- **Secrets never in the recipe**. Env vars reference `.env`; defaults in the recipe are OK only for non-secret config.
+
+## Inspired by
+
+Hand-curated by dev-workflow. Service defaults follow upstream documentation (Docker Hub `postgres`, `redis`, `mailhog/mailhog`, `minio/minio`, `getmeili/meilisearch`, `jaegertracing/all-in-one`, `traefik`). Healthcheck patterns adapted from `docker-library/healthcheck` and the official compose docs.

package/scaffold/skills/docker-compose-recipes/references/compose-composition.md

@@ -0,0 +1,91 @@
+# Composing a final `docker-compose.dev.yml`
+
+This file describes how `/dw-new-project` and `/dw-dockerize` merge the standalone service blocks under `services/` into a single working compose file.
+
+## The merge algorithm
+
+1. **Pick the selected services.** From the interview answers (or from stack detection in `dw-dockerize`), get the list of services to include. Example: `[postgres, redis, mailhog, minio]`.
+2. **Read each `services/<name>.yml`** as a standalone fragment. Each file declares ONE top-level service block (e.g., `postgres:`) plus comments at the bottom describing the volumes block to merge.
+3. **Concatenate under a single `services:` map.** Indent each block under `services:` in the final file. Order does not matter for compose, but for readability sort by tier: storage → cache/queue → search → email → observability → proxy.
+4. **Collect the volumes.** Each recipe's comments list the named volumes it needs. Aggregate them under a top-level `volumes:` block. Example:
+
+   ```yaml
+   volumes:
+     postgres_data: {}
+     redis_data: {}
+     minio_data: {}
+   ```
+
+5. **Add a network (optional but recommended).** Default Docker compose creates one project network already, so explicit declaration is only needed if you want a custom name or external network.
+
+6. **Resolve port collisions.** The recipes use upstream defaults. If two selected services share a port (rare; mostly UIs on `8080`), shift the second one and document in the README port table.
+
+7. **Wire `depends_on` with health gates** for app services that depend on infra:
+
+   ```yaml
+   api:
+     depends_on:
+       postgres:
+         condition: service_healthy
+       redis:
+         condition: service_healthy
+   ```
+
+8. **Add the app service(s) at the end.** For monorepo projects, declare an `api` service (and `web` if backend serves the frontend) that builds from the local Dockerfile.dev and binds the source as a volume for hot reload.
+
+## Final file shape
+
+```yaml
+# Generated by /dw-new-project on YYYY-MM-DD
+# Edit freely. Recipes live in .agents/skills/docker-compose-recipes/
+
+services:
+  # --- storage tier ---
+  postgres:
+    # ... contents from services/postgres.yml
+
+  # --- cache tier ---
+  redis:
+    # ... contents from services/redis.yml
+
+  # --- email-in-dev (capture only) ---
+  mailhog:
+    # ... contents from services/mailhog.yml
+
+  # --- object storage ---
+  minio:
+    # ... contents from services/minio.yml
+
+  # --- application ---
+  api:
+    build:
+      context: ./apps/api
+      dockerfile: Dockerfile.dev
+    env_file: .env
+    volumes:
+      - ./apps/api:/app
+      - /app/node_modules     # avoid host node_modules clobbering container's
+    ports:
+      - "${API_PORT:-3001}:3001"
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+      mailhog:
+        condition: service_started
+      minio:
+        condition: service_healthy
+
+volumes:
+  postgres_data: {}
+  redis_data: {}
+  minio_data: {}
+```
+
+## Common mistakes to avoid
+
+- **Don't leave secrets as defaults in the compose file.** All recipes default to dev passwords; override via `.env` even in dev so a typo doesn't ship a default to a server.
+- **Don't omit healthchecks.** They drive `depends_on` correctness. An app starting before Postgres is ready is a class of flaky dev-day bugs.
+- **Don't share volumes across services with different ownership** (e.g., postgres + minio). Each gets its own named volume.
+- **Don't expose the management UI ports of brokers/search engines on `0.0.0.0` in dev environments shared with others.** Bind to `127.0.0.1:<port>:<port>` if multi-tenant.

package/scaffold/skills/docker-compose-recipes/references/env-conventions.md

@@ -0,0 +1,51 @@
+# Env var conventions
+
+All recipes reference env vars via `${VAR:-default}` so a project's `.env` (or `.env.example`) is the single source of truth.
+
+## Naming pattern
+
+- **Service-scoped** vars use the upstream image's convention: `POSTGRES_USER`, `MYSQL_ROOT_PASSWORD`, `MEILI_MASTER_KEY`, etc. This avoids surprises when reading the image's documentation.
+- **Application-scoped** vars use a generic name that spans implementations: `DATABASE_URL`, `REDIS_URL`, `SMTP_HOST`, `AWS_ENDPOINT_URL`. The application reads these, not the service-specific ones.
+- **Port overrides** use `<SERVICE>_PORT` (or `<SERVICE>_<ROLE>_PORT` when there are several): `POSTGRES_PORT`, `MAILHOG_SMTP_PORT`, `MAILHOG_UI_PORT`, `RABBITMQ_PORT`, `RABBITMQ_UI_PORT`.
+
+## Mapping between service vars and app vars
+
+When a project uses Postgres, the `.env.example` should declare BOTH the service-side vars (so the recipe works) AND the application-side derived URL (so app code reads one variable):
+
+```dotenv
+# Postgres (consumed by the postgres service)
+POSTGRES_USER=app
+POSTGRES_PASSWORD=app
+POSTGRES_DB=app
+POSTGRES_PORT=5432
+
+# Application-side connection string
+DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
+```
+
+Compose performs variable substitution in `.env` references, so the application sees `DATABASE_URL` already-resolved.
+
+## What goes in `.env.example` vs `.env`
+
+- `.env.example` — committed. Holds DEFAULTS that are safe for dev and template values for prod.
+- `.env` — gitignored. Real values for the user's local machine.
+
+Never commit a `.env`. Always commit a `.env.example`.
+
+## Common cross-service derivations
+
+| Use case | Derived variable | Source |
+|----------|------------------|--------|
+| Postgres URL | `DATABASE_URL` | `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB` |
+| MySQL URL | `DATABASE_URL` | `MYSQL_USER`, `MYSQL_PASSWORD`, `MYSQL_DATABASE` |
+| Redis URL | `REDIS_URL` | `REDIS_PASSWORD` (if set) |
+| RabbitMQ URL | `AMQP_URL` | `RABBITMQ_USER`, `RABBITMQ_PASSWORD` |
+| AWS-compatible | `AWS_ENDPOINT_URL`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` | LocalStack: `test`/`test`. MinIO: `MINIO_ROOT_USER`, `MINIO_ROOT_PASSWORD` |
+| SMTP | `SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASSWORD`, `SMTP_SECURE` | Service hostname (`mailhog`/`mailpit`/`smtp4dev`) + recipe's SMTP port |
+| OTel | `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://jaeger:4318` |
+
+## Reserved names
+
+The recipes use these env var names. Do NOT reuse them for unrelated config:
+
+`POSTGRES_*`, `MYSQL_*`, `MEILI_*`, `MINIO_*`, `RABBITMQ_*`, `MAILHOG_*`, `MAILPIT_*`, `SMTP4DEV_*`, `JAEGER_*`, `TRAEFIK_*`, `LOCALSTACK_*`, `ELASTIC_*`, `TYPESENSE_*`, `MEMCACHED_*`, `REDIS_*`.

package/scaffold/skills/docker-compose-recipes/references/healthcheck-patterns.md

@@ -0,0 +1,54 @@
+# Healthcheck patterns
+
+Every recipe ships a healthcheck. App services that depend on infra MUST gate startup on these via `depends_on: { <service>: { condition: service_healthy } }`.
+
+## Per-service shapes
+
+| Service | Test command | Why |
+|---------|--------------|-----|
+| Postgres | `pg_isready -U $USER -d $DB` | Distinguishes "process up" from "ready to accept queries" |
+| MySQL | `mysqladmin ping` | Same — process up != accepting connections |
+| Redis | `redis-cli ping` | Returns `PONG` only when the server is fully initialized |
+| Memcached | `echo stats | nc -w 1 localhost 11211 \| grep -q uptime` | Memcached has no native ping; stats command is the cheapest readiness signal |
+| RabbitMQ | `rabbitmq-diagnostics ping` | Built-in; takes ~30s to be ready, hence `start_period: 30s` |
+| LocalStack | `curl -sf http://localhost:4566/_localstack/health \| grep -q running` | Internal endpoint reports per-service readiness |
+| MailHog | `wget --spider http://localhost:8025` | UI port responds when SMTP is also ready |
+| Mailpit | `wget --spider http://localhost:8025` | Same |
+| smtp4dev | `wget --spider http://localhost:80` | UI on internal port 80 |
+| MinIO | `curl -f http://localhost:9000/minio/health/live` | Documented liveness endpoint |
+| Meilisearch | `curl -f http://localhost:7700/health` | Documented |
+| Typesense | `curl -f http://localhost:8108/health` | Documented |
+| Elasticsearch | Auth + `_cluster/health \| grep -E 'green|yellow'` | Yellow is OK in single-node dev (no replicas) |
+| Jaeger | `wget --spider http://localhost:14269/` | Admin/health port (separate from UI) |
+| Traefik | `wget --spider http://localhost:8080/ping` | Built-in ping endpoint |
+
+## Tuning
+
+Default values across recipes:
+- `interval: 5-10s` (how often the check runs)
+- `timeout: 3-5s` (how long the check is allowed to take)
+- `retries: 5-10` (how many failures before unhealthy)
+- `start_period: 5-60s` (grace window during initial boot — Elasticsearch and RabbitMQ get the most because they take longest to come up)
+
+Adjust upward only if your machine is slow or your image is custom-built and slow to start. Adjust downward only if you fully understand the startup curve.
+
+## Chaining `depends_on`
+
+```yaml
+api:
+  depends_on:
+    postgres:
+      condition: service_healthy   # waits for the healthcheck to pass
+    redis:
+      condition: service_healthy
+    mailhog:
+      condition: service_started   # MailHog is light enough that started == ready
+```
+
+`service_healthy` is the strictest gate — no traffic until the healthcheck has passed at least once. Use it for all data stores. Use `service_started` only for stateless services (proxy, mail capture).
+
+## Common mistakes
+
+- **Forgetting `start_period`** — without it, the first few healthcheck failures during boot count toward `retries` and the service is marked unhealthy before it ever had a chance.
+- **Using `tcp://host:port` checks** — they only test that the port is open, not that the application behind it is ready (e.g., Postgres accepts TCP before it accepts queries).
+- **Setting `retries: 0`** — this is "fail on first miss." Always allow at least 3 retries to absorb transient hiccups.

package/scaffold/skills/docker-compose-recipes/references/prod-vs-dev.md

@@ -0,0 +1,85 @@
+# Dev vs Prod — what changes in each recipe
+
+The recipes default to **dev**. When `/dw-dockerize --prod` (or `--both`) emits a production compose, apply these transforms.
+
+## Universal changes
+
+| Aspect | Dev | Prod |
+|--------|-----|------|
+| Image tag | `<image>:<major>-alpine` (e.g., `postgres:16-alpine`) | Pin to a patch (`postgres:16.4-alpine`); no `:latest` ever |
+| Restart policy | `unless-stopped` is fine | `always` for stateless, `unless-stopped` for stateful |
+| Public ports | Mapped (`5432:5432`) for host access | NOT mapped — services talk over the internal network only; access via bastion/VPN |
+| Bind mounts | Source code mounted for hot reload | NEVER. Code is baked into the image. |
+| Named volumes | OK with default driver | Use external volume drivers when running on swarm/k8s; back up regularly |
+| Env / secrets | `.env` is fine | Secrets via Docker secrets, AWS Parameter Store, Vault, or platform-native — NOT `.env` files committed anywhere |
+| Healthcheck | Same | Same — keep them, they drive orchestrator failover |
+| Logging | Default driver | `json-file` with rotation, or ship to a log aggregator (Loki, CloudWatch) |
+| Resource limits | None (machine has plenty) | `mem_limit`, `cpus` set per service to prevent runaway containers |
+
+## Per-service prod transforms
+
+### Postgres / MySQL / Redis (data tier)
+
+- Drop public port.
+- Move all credentials to secrets (compose's `secrets:` block, or Docker swarm secrets, or external vault).
+- Increase `start_period` to 60-120s (large data dirs take longer to recover).
+- Set up a logical backup (`pg_dump`/`mysqldump`) on a schedule, persisted off-host.
+- For Redis: enable AOF persistence (`appendonly yes`) and set `requirepass`.
+
+### RabbitMQ
+
+- Use `rabbitmq:3-alpine` (no management UI baked in) and run management as a separate service if needed.
+- Drop port `15672`. Drop default user; create real users via `rabbitmqctl add_user` on first boot.
+- Mount a custom `rabbitmq.conf` for clustering, queue limits, and TLS.
+
+### MinIO / S3
+
+- In prod, prefer real S3 (or another managed object store). MinIO in prod requires HA (4+ nodes), erasure coding tuning, and ongoing operational care.
+- If you keep MinIO, generate strong credentials and rotate them; never use defaults.
+
+### LocalStack
+
+- **Remove entirely from prod compose.** LocalStack is dev-only.
+- Replace with the real AWS endpoints; `AWS_ENDPOINT_URL` becomes unset (default to AWS).
+
+### MailHog / Mailpit / smtp4dev
+
+- **Remove entirely from prod compose.** Email-in-dev tools are dev-only.
+- Replace with a real provider via `SMTP_*` or API client (SendGrid, Resend, Postmark, SES).
+
+### Jaeger all-in-one
+
+- **Replace with split deployment** in prod: `jaeger-collector`, `jaeger-query`, plus Cassandra or Elasticsearch as storage. Or use a managed APM.
+
+### Traefik
+
+- Remove `--api.insecure=true`.
+- Use a file or KV provider; don't expose the Docker socket if you can avoid it.
+- Configure ACME (Let's Encrypt) for real TLS.
+- Bind dashboard to a private network, behind basic auth.
+
+### Meilisearch / Typesense
+
+- Set the prod env (`MEILI_ENV=production`) and a strong API/master key.
+- Consider clustering for HA (Typesense supports 3-node clusters; Meilisearch v1.x is single-instance — use replication carefully).
+
+### Elasticsearch
+
+- Single-node is dev-only. Run a 3-node cluster minimum.
+- Enable TLS on transport AND HTTP layers (`xpack.security.transport.ssl.enabled=true`, `xpack.security.http.ssl.enabled=true`).
+- Tune heap (`ES_JAVA_OPTS`) per host; don't exceed 50% of host RAM and don't exceed 31GB.
+
+## File-level conventions
+
+- **Dev compose:** `docker-compose.dev.yml` (or `docker-compose.yml` if there's only one).
+- **Prod compose:** `docker-compose.prod.yml`. Run with `docker compose -f docker-compose.prod.yml up`.
+- **Common base:** if both files share a lot, factor common service definitions into `docker-compose.yml` and use `-f` overrides per environment.
+
+## What `/dw-dockerize --prod` should NEVER do
+
+- Ship secrets in committed files.
+- Use `:latest` tags.
+- Expose data-tier ports publicly.
+- Include MailHog / Mailpit / smtp4dev / LocalStack.
+- Skip healthchecks.
+- Forget to set non-root `USER` in the application Dockerfile.

package/scaffold/skills/docker-compose-recipes/services/elasticsearch.yml

@@ -0,0 +1,34 @@
+# Elasticsearch 8 — full search + analytics. Heavyweight: only choose if you need ES specifically.
+# Env vars: ELASTIC_PASSWORD, ELASTICSEARCH_PORT (default 9200)
+# Application-side: ELASTICSEARCH_URL=http://elastic:${ELASTIC_PASSWORD}@elasticsearch:9200
+
+elasticsearch:
+  image: docker.elastic.co/elasticsearch/elasticsearch:8.15.0
+  restart: unless-stopped
+  environment:
+    discovery.type: single-node
+    xpack.security.enabled: "true"
+    ELASTIC_PASSWORD: ${ELASTIC_PASSWORD:-elastic}
+    ES_JAVA_OPTS: "-Xms512m -Xmx512m"
+  ports:
+    - "${ELASTICSEARCH_PORT:-9200}:9200"
+  volumes:
+    - elasticsearch_data:/usr/share/elasticsearch/data
+  healthcheck:
+    test: ["CMD-SHELL", "curl -fsu elastic:${ELASTIC_PASSWORD:-elastic} http://localhost:9200/_cluster/health | grep -E 'green|yellow'"]
+    interval: 10s
+    timeout: 5s
+    retries: 10
+    start_period: 60s
+  ulimits:
+    memlock:
+      soft: -1
+      hard: -1
+
+# volumes:
+#   elasticsearch_data: {}
+#
+# Prod notes:
+# - Single-node is for dev only. Run a 3-node cluster minimum in prod with proper data tiers.
+# - Tune ES_JAVA_OPTS per host; default 512m is enough for dev but too small for any real index.
+# - Enable TLS (xpack.security.transport.ssl.enabled=true) and rotate ELASTIC_PASSWORD.

package/scaffold/skills/docker-compose-recipes/services/jaeger.yml

@@ -0,0 +1,24 @@
+# Jaeger all-in-one — OTel collector + storage + UI. Easiest tracing setup for dev.
+# Env vars: JAEGER_UI_PORT (default 16686), JAEGER_OTLP_GRPC_PORT (default 4317), JAEGER_OTLP_HTTP_PORT (default 4318)
+# Application-side: OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4318 (HTTP) or http://jaeger:4317 (gRPC)
+
+jaeger:
+  image: jaegertracing/all-in-one:1.60
+  restart: unless-stopped
+  environment:
+    COLLECTOR_OTLP_ENABLED: "true"
+  ports:
+    - "${JAEGER_UI_PORT:-16686}:16686"
+    - "${JAEGER_OTLP_GRPC_PORT:-4317}:4317"
+    - "${JAEGER_OTLP_HTTP_PORT:-4318}:4318"
+  healthcheck:
+    test: ["CMD-SHELL", "wget --quiet --spider http://localhost:14269/ || exit 1"]
+    interval: 10s
+    timeout: 3s
+    retries: 5
+    start_period: 5s
+
+# Prod notes:
+# - all-in-one stores traces in memory. NEVER use for prod.
+# - In prod, run jaeger-collector + jaeger-query separately, with Cassandra/Elasticsearch as storage.
+# - Or replace Jaeger with a managed APM (Honeycomb, Datadog, Grafana Tempo, Sentry tracing).

package/scaffold/skills/docker-compose-recipes/services/localstack.yml

@@ -0,0 +1,30 @@
+# LocalStack — AWS-compatible local (S3, SQS, SNS, DynamoDB, etc.)
+# Env vars: LOCALSTACK_PORT (default 4566), LOCALSTACK_SERVICES (comma list, e.g., "s3,sqs,sns,dynamodb")
+# Application-side: AWS_ENDPOINT_URL=http://localstack:4566; AWS_ACCESS_KEY_ID=test; AWS_SECRET_ACCESS_KEY=test; AWS_REGION=us-east-1
+
+localstack:
+  image: localstack/localstack:3
+  restart: unless-stopped
+  environment:
+    SERVICES: ${LOCALSTACK_SERVICES:-s3,sqs,sns,dynamodb}
+    DEBUG: ${LOCALSTACK_DEBUG:-0}
+    LS_LOG: ${LOCALSTACK_LOG:-warn}
+    AWS_DEFAULT_REGION: us-east-1
+  ports:
+    - "${LOCALSTACK_PORT:-4566}:4566"
+  volumes:
+    - localstack_data:/var/lib/localstack
+    - /var/run/docker.sock:/var/run/docker.sock
+  healthcheck:
+    test: ["CMD-SHELL", "curl -sf http://localhost:4566/_localstack/health | grep -q '\"running\"'"]
+    interval: 10s
+    timeout: 5s
+    retries: 10
+    start_period: 20s
+
+# volumes:
+#   localstack_data: {}
+#
+# Prod notes:
+# - LocalStack is for DEV ONLY. In prod, point AWS_ENDPOINT_URL back to real AWS and remove this service.
+# - The Docker socket mount is required for Lambda emulation; remove if Lambda is not used.

package/scaffold/skills/docker-compose-recipes/services/mailhog.yml

@@ -0,0 +1,23 @@
+# MailHog — DEV-ONLY email capture (NEVER sends real mail)
+# This is the dev-workflow DEFAULT for email-in-dev so the project cannot accidentally email real users.
+# Env vars: MAILHOG_SMTP_PORT (default 1025), MAILHOG_UI_PORT (default 8025)
+# Application-side SMTP config:
+#   SMTP_HOST=mailhog ; SMTP_PORT=1025 ; SMTP_USER= ; SMTP_PASSWORD= ; SMTP_SECURE=false
+
+mailhog:
+  image: mailhog/mailhog:latest
+  restart: unless-stopped
+  ports:
+    - "${MAILHOG_SMTP_PORT:-1025}:1025"
+    - "${MAILHOG_UI_PORT:-8025}:8025"
+  healthcheck:
+    test: ["CMD", "wget", "--quiet", "--spider", "http://localhost:8025"]
+    interval: 10s
+    timeout: 3s
+    retries: 5
+    start_period: 5s
+
+# Prod notes:
+# - MailHog must NEVER ship to prod. Replace with a real SMTP relay or transactional email API
+#   (SendGrid, Resend, Postmark, SES) when promoting docker-compose.dev.yml to prod.
+# - Open the UI at http://localhost:8025 to inspect captured mail; nothing leaves the host.

package/scaffold/skills/docker-compose-recipes/services/mailpit.yml

@@ -0,0 +1,27 @@
+# Mailpit — modern alternative to MailHog (active maintenance, full-text search, REST API)
+# Env vars: MAILPIT_SMTP_PORT (default 1025), MAILPIT_UI_PORT (default 8025)
+# Application-side SMTP config: same as MailHog (drop-in replacement)
+
+mailpit:
+  image: axllent/mailpit:latest
+  restart: unless-stopped
+  ports:
+    - "${MAILPIT_SMTP_PORT:-1025}:1025"
+    - "${MAILPIT_UI_PORT:-8025}:8025"
+  environment:
+    MP_MAX_MESSAGES: ${MAILPIT_MAX_MESSAGES:-500}
+    MP_DATABASE: /data/mailpit.db
+  volumes:
+    - mailpit_data:/data
+  healthcheck:
+    test: ["CMD", "wget", "--quiet", "--spider", "http://localhost:8025"]
+    interval: 10s
+    timeout: 3s
+    retries: 5
+    start_period: 5s
+
+# volumes:
+#   mailpit_data: {}
+#
+# Prod notes:
+# - DEV ONLY. Do not ship to prod. See mailhog.yml notes for prod email guidance.

package/scaffold/skills/docker-compose-recipes/services/meilisearch.yml

@@ -0,0 +1,28 @@
+# Meilisearch — lightweight, opinionated search engine
+# Env vars: MEILI_MASTER_KEY, MEILISEARCH_PORT (default 7700)
+# Application-side: MEILI_HTTP_ADDR=http://meilisearch:7700; MEILI_MASTER_KEY=${MEILI_MASTER_KEY}
+
+meilisearch:
+  image: getmeili/meilisearch:v1.10
+  restart: unless-stopped
+  environment:
+    MEILI_MASTER_KEY: ${MEILI_MASTER_KEY:-meili-dev-key-change-me}
+    MEILI_ENV: ${MEILI_ENV:-development}
+    MEILI_NO_ANALYTICS: "true"
+  ports:
+    - "${MEILISEARCH_PORT:-7700}:7700"
+  volumes:
+    - meilisearch_data:/meili_data
+  healthcheck:
+    test: ["CMD", "curl", "-f", "http://localhost:7700/health"]
+    interval: 10s
+    timeout: 3s
+    retries: 5
+    start_period: 5s
+
+# volumes:
+#   meilisearch_data: {}
+#
+# Prod notes:
+# - Set MEILI_ENV=production and provide a strong MEILI_MASTER_KEY (≥16 chars).
+# - Never expose Meilisearch directly to the internet without auth + a reverse proxy.

package/scaffold/skills/docker-compose-recipes/services/memcached.yml

@@ -0,0 +1,19 @@
+# Memcached 1.6 — cache (no persistence)
+# Env vars: MEMCACHED_PORT (default 11211), MEMCACHED_MEMORY_MB (default 64)
+
+memcached:
+  image: memcached:1.6-alpine
+  restart: unless-stopped
+  command: -m ${MEMCACHED_MEMORY_MB:-64}
+  ports:
+    - "${MEMCACHED_PORT:-11211}:11211"
+  healthcheck:
+    test: ["CMD-SHELL", "echo stats | nc -w 1 localhost 11211 | grep -q uptime"]
+    interval: 5s
+    timeout: 3s
+    retries: 10
+    start_period: 3s
+
+# Prod notes:
+# - Memcached has no auth. NEVER expose its port publicly. Internal network only.
+# - For multi-host setups, use a managed cache (Redis, ElastiCache).