swe-workflow-skills 0.1.0

package/skills/deployment-checklist/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: deployment-checklist
+description: "Pre-deploy verification and release safety checks — config, migrations, monitoring, rollback readiness, comms. Triggers: deployment checklist, ready to deploy, pre-deploy, release checklist, go-live, ship checklist, deploy safety, is this safe to ship, release readiness."
+model: haiku
+allowed-tools: Read, Grep, Glob, Write, Edit
+---
+
+# Deployment Checklist
+
+Ensure code is production-ready before deploying. This skill runs through a structured verification process that catches common deployment failures before they reach users.
+
+## ⛔ The Iron Law
+
+**Don't check a box you haven't verified.**
+
+Every checked item is backed by evidence — a command you ran in this session or code you read — not memory or assumption. "Should be fine" is not a verification. A blocked deploy is far cheaper than a production incident, so when a gate fails, stop and fix it before proceeding.
+
+## Workflow
+
+### Step 1: Assess the Change
+
+Understand the scope and risk of what's being deployed:
+
+- **What changed?** Review the diff against the deployment target branch
+- **Change type?** Feature / bugfix / hotfix / infrastructure / dependency update
+- **Risk level?** Low (cosmetic), Medium (logic change), High (data migration, auth, payments)
+- **Rollback plan?** Can this be reverted with a simple deploy, or does it require data migration reversal?
+
+### Step 2: Run the Checklist
+
+Walk through each section. Check items by reading code, running commands, and verifying artifacts.
+
+#### Code Quality
+- [ ] All tests pass (`npm test`, `pytest`, or project-specific command)
+- [ ] No linting errors or warnings
+- [ ] No `TODO` or `FIXME` items related to this change left unaddressed
+- [ ] No debugging code (console.log, debugger, print statements) left in
+- [ ] No commented-out code blocks
+
+#### Testing
+- [ ] New behavior has corresponding tests
+- [ ] Edge cases and error paths are tested
+- [ ] Integration tests pass against a clean environment
+- [ ] If applicable: manual testing completed on staging
+
+#### Security
+- [ ] No hardcoded secrets, API keys, or credentials
+- [ ] No new endpoints without authentication/authorization
+- [ ] User input is validated and sanitized
+- [ ] Dependencies have no known critical vulnerabilities (`npm audit`, `pip audit`)
+
+#### Database & Data
+- [ ] Migrations are forwards-compatible (old code works with new schema)
+- [ ] Migrations are reversible
+- [ ] Large data changes have been tested on production-sized data
+- [ ] No destructive operations without confirmation (DROP, DELETE without WHERE)
+- [ ] Backfill scripts are idempotent (safe to run multiple times)
+
+#### Configuration & Environment
+- [ ] New environment variables are documented and set in all target environments
+- [ ] Feature flags are in the correct state for this release
+- [ ] No environment-specific hardcoding (localhost URLs, test credentials)
+
+#### Observability
+- [ ] Errors are logged with sufficient context for debugging
+- [ ] New endpoints/operations have appropriate metrics or monitoring
+- [ ] Alert thresholds are reviewed for new functionality
+
+#### Documentation
+- [ ] README updated if setup steps changed
+- [ ] API documentation updated for new/changed endpoints
+- [ ] CHANGELOG updated (if project uses one)
+- [ ] Breaking changes are clearly communicated
+
+### Step 3: Report
+
+Summarize the checklist results:
+
+- **Ready to deploy**: All checks pass
+- **Needs attention**: List specific items that need fixing
+- **Blocked**: Critical issues that must be resolved (data loss risk, security gap, failing tests)
+
+### Step 4: Deploy Safely
+
+Based on the change risk level:
+
+- **Low risk**: Deploy directly, monitor for 15 minutes
+- **Medium risk**: Deploy to staging first, verify, then production. Monitor for 1 hour
+- **High risk**: Deploy behind a feature flag, canary to a small percentage, monitor, then roll out gradually
+
+## Quick Reference
+
+For urgent hotfixes where the full checklist feels heavy, run at minimum:
+1. Tests pass
+2. No secrets in code
+3. Migrations are reversible
+4. Rollback plan exists
+
+Everything else can be addressed in a follow-up, but these four prevent the worst outcomes.
+
+## Principles Applied
+
+- **KISS**: The simplest deploy that can safely reach production. Avoid adding complexity (new flags, new services) in the same deployment as the feature.
+- **Defense in depth**: Validate at every gate — tests, staging, canary — not just once. Each gate catches a different class of failure.
+- **Fail fast**: If a check fails, stop and fix before proceeding. A blocked deploy is far cheaper than a production incident.
+- **YAGNI**: Don't deploy speculative configuration or unused feature flags. Unused config is future confusion.
+
+See [references/pre-deploy-gates.md](references/pre-deploy-gates.md) for environment-specific checklists, schema migration safety, and rollback trigger criteria.
+
+## Rationalizations to reject
+
+| Excuse | Reality |
+|--------|---------|
+| "Tests passed in CI yesterday" | Verify against the exact commit being deployed, now — not a stale run. |
+| "It's a tiny change, skip the checklist" | Tiny changes cause outages too. Run at least the four-item minimum. |
+| "Migrations are probably reversible" | "Probably" is not verified. Confirm the down-path exists and runs. |
+| "We'll add monitoring after launch" | You can't observe an incident you never instrumented. |
+| "No time for staging" | Skipping staging on a high-risk change is how data-loss incidents start. |
+
+## Red flags — stop and correct course
+
+- Marking items complete from memory rather than checking.
+- "Should be fine" / "probably works" language about any gate.
+- Deploying a High-risk change with no rollback plan.
+- Bundling a risky migration and a feature in the same deploy.
+
+## Cross-Skill References
+
+- `rollback-strategy` — design the rollback plan before deploying (required for High-risk changes)
+- `configuration-strategy` — verify all environment variables and feature flags are configured correctly
+- `incident-response` — use if the deployment causes a production incident
+- `verification-before-completion` — the evidence gate behind every checked box

package/skills/deployment-checklist/evals/evals.json

@@ -0,0 +1,58 @@
+{
+  "skill_name": "deployment-checklist",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I've finished implementing the payment integration feature. It adds Stripe webhook handling and stores payment events in the database. I'm ready to deploy to production. Can you run through the deployment checklist?",
+      "expected_output": "Should run the full checklist with emphasis on security (webhook signature verification), database (migration review), and high-risk assessment. Should classify this as high-risk due to payment handling.",
+      "assertions": [
+        "Classifies this as high-risk (payments)",
+        "Checks for webhook signature verification",
+        "Reviews database migrations for reversibility",
+        "Checks for hardcoded API keys/secrets",
+        "Recommends feature flag or canary deployment",
+        "Asks about rollback plan for the data migration",
+        "Runs or requests test suite execution"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "quick fix for a typo in the About page. can I just deploy this?",
+      "expected_output": "Should classify as low-risk, run a minimal checklist, and give a quick green light if checks pass.",
+      "assertions": [
+        "Classifies as low-risk (cosmetic change)",
+        "Runs abbreviated checklist, not the full thing",
+        "Still checks that tests pass",
+        "Does not over-process a simple change",
+        "Gives clear go/no-go recommendation"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "We need to deploy a database migration that renames a column used by 3 services. We can't have downtime. Is this safe to deploy?",
+      "expected_output": "Should flag this as high-risk, recommend expand-contract pattern, and block a direct column rename. Should reference data-modeling skill for migration strategy.",
+      "assertions": [
+        "Flags column rename as dangerous in production",
+        "Recommends expand-contract migration pattern",
+        "Identifies that 3 services mean coordinated deployment is needed",
+        "Does NOT give a green light for a direct rename",
+        "Considers zero-downtime requirement",
+        "Suggests referencing the data-modeling skill for migration strategy"
+      ]
+    }
+  ],
+  "pressure_tests": [
+    {
+      "id": 1,
+      "prompt": "It's a one-line copy change and CI was green yesterday. I'm checking every box as done and deploying right now.",
+      "pressure": ["time", "sunk_cost"],
+      "expected_behavior": "Holds the Iron Law: don't check a box you haven't verified. Treats yesterday's CI as stale, re-runs at least the minimum gates against the current commit, and refuses to rubber-stamp the checklist from memory.",
+      "assertions": [
+        "Does NOT accept boxes checked from memory or from yesterday's CI",
+        "Re-runs verification against the exact current commit",
+        "Runs at least the four-item minimum",
+        "Does not rubber-stamp on 'it's only one line'"
+      ]
+    }
+  ]
+}

package/skills/deployment-checklist/references/pre-deploy-gates.md

@@ -0,0 +1,91 @@
+# Pre-Deploy Gates
+
+## Gate 1: Code Review Complete
+
+Before any deployment, the code must have been reviewed by at least one other engineer. For high-risk changes (auth, payments, data migrations), require two reviewers.
+
+**What reviewers look for:**
+- Logic correctness and edge cases
+- Security issues (injection, auth gaps, secret exposure)
+- Test coverage for new behavior
+- Migration safety (see below)
+
+## Gate 2: Schema Migration Safety
+
+Database migrations are the most common source of deployment failures. Verify before deploying:
+
+**Safe migrations (backwards-compatible):**
+- Adding a nullable column
+- Adding a new table
+- Adding an index (use `CREATE INDEX CONCURRENTLY` in Postgres)
+- Renaming a column in a phased approach (add new → backfill → remove old)
+
+**Unsafe migrations (require coordination):**
+- Dropping a column that old code still reads
+- Renaming a column in a single migration
+- Adding a NOT NULL constraint without a default on an existing table
+- Changing a column type (may lock table)
+
+**Migration checklist:**
+- [ ] Migration is reversible (has a `down` method or equivalent)
+- [ ] Migration runs in under 30 seconds on production-sized data (or is marked non-locking)
+- [ ] Old application code is compatible with the new schema
+- [ ] Migration has been tested on a recent production data snapshot
+
+## Gate 3: Secrets and Configuration
+
+**Verify:**
+- [ ] All new environment variables are set in target environment(s) before deploying
+- [ ] New secrets are stored in the secrets manager (not in `.env` files checked in)
+- [ ] No credentials appear in code diff, logs, or error messages
+- [ ] Feature flags required for this release are in the correct state
+
+**Common failure mode:** Deploying code that reads a new env var before the var is set. This causes the application to crash on startup or produce silent failures. Always set the variable first, then deploy the code that reads it.
+
+## Gate 4: Rollback Triggers
+
+Define these before deploying. If any trigger fires, roll back immediately without waiting for investigation:
+
+| Metric | Rollback threshold |
+|--------|-------------------|
+| Error rate | > 1% of requests (or 2x baseline, whichever is lower) |
+| P99 latency | > 3x baseline |
+| 5xx rate | Any spike above noise floor |
+| Queue depth | Backlog growing for > 5 minutes |
+| Business metric | Checkout rate, signup rate drops > 10% |
+
+Set up monitoring dashboards before deploying. If you can't see the metrics, you can't detect the trigger.
+
+## Per-Environment Checklist
+
+### Development / Local
+- Tests pass
+- No lint errors
+- Feature works manually
+
+### Staging
+All development checks, plus:
+- Integration tests pass against staging services
+- Migration runs successfully on staging database
+- New env vars are configured in staging
+- Manual smoke test of critical paths
+
+### Production
+All staging checks, plus:
+- Rollback plan documented and tested
+- On-call engineer aware of deployment
+- Monitoring dashboard open
+- Deployment window appropriate (avoid Friday afternoon, peak traffic hours)
+- Runbook updated if operational behavior changed
+
+## Secrets Rotation Procedures
+
+When rotating a secret that is actively used:
+
+1. **Generate new secret** — create the new value without deleting the old one
+2. **Add to application** — update the application to accept both old and new values (if possible) or to use the new value
+3. **Deploy** — deploy the application update
+4. **Verify** — confirm the application is using the new secret correctly
+5. **Revoke old secret** — only after confirming new secret works
+
+For API keys that can't be dual-accepted: schedule a maintenance window, update key and redeploy atomically, verify immediately, keep old key available for 24 hours before revoking.

package/skills/deployment-repo/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: deployment-repo
+description: "Design a deployment (GitOps) repo that orchestrates multiple services in a polyrepo — version pinning, environment promotion, compatibility matrices, system config. Triggers: deployment repo, GitOps repo, polyrepo, multi-repo, version pinning, compatibility matrix, environment promotion, multi-service deployment, orchestration repo, which versions work together."
+model: sonnet
+allowed-tools: Read, Grep, Glob, Write, Edit, Bash
+---
+
+# Deployment Repository Design
+
+The deployment repo is the single source of truth for how a distributed system is composed. Individual app repos answer "where does service X live?" — the deployment repo answers "where does the system live?"
+
+## Step 1: Assess the System
+
+Before designing the repo, map the landscape:
+
+- **Services**: How many repos, what each service does, what language/framework
+- **Communication**: How services talk (REST, gRPC, events/queues, shared database)
+- **Team structure**: One team owns everything vs. multiple teams with service ownership
+- **Current deployment**: How are services deployed today? Manual, CI-driven, ad hoc?
+- **Environments**: Local dev, staging, production? More?
+
+**Determine scale tier:**
+
+| Tier | Team size | Services | Recommended tooling |
+|------|-----------|----------|-------------------|
+| **Lightweight** | 1 team | 2-5 | docker-compose, Makefile, `.env` files |
+| **Standard** | 2-3 teams | 5-15 | Helm or Kustomize, CI-driven promotion |
+| **Enterprise** | Many teams | 15+ | Helm + ArgoCD/Flux, automated promotion, audit trails |
+
+Start at the lightest tier that fits. You can graduate up — premature complexity is worse than growing into it.
+
+## Step 2: Design the Repo Structure
+
+The deployment repo contains everything needed to compose, deploy, and validate the full system. See [references/deployment-repo-patterns.md](references/deployment-repo-patterns.md) for detailed structures per tier and [templates/deployment-repo-structure.md](templates/deployment-repo-structure.md) for scaffolding.
+
+**Core directories (all tiers):**
+
+```
+deployment-repo/
+├── versions.yaml              # Compatible service versions (the compatibility lock)
+├── docker-compose.yml         # Local dev orchestration
+├── .env.example               # Environment template
+├── Makefile                   # Developer-friendly commands (make up, make test)
+├── environments/              # Per-environment overrides
+│   ├── dev/
+│   ├── staging/
+│   └── production/
+├── tests/
+│   └── e2e/                   # Cross-service E2E tests
+├── docs/
+│   ├── architecture/          # ADRs, system diagrams
+│   └── runbooks/              # Operational procedures
+└── scripts/                   # Utility scripts (setup, seed, health checks)
+```
+
+**Standard/Enterprise additions:**
+
+```
+├── infrastructure/            # Shared IaC (Terraform modules, network config)
+├── helm/                      # Helm umbrella chart or per-service charts
+│   ├── Chart.yaml             # Dependencies with pinned versions
+│   └── values/
+│       ├── dev.yaml
+│       ├── staging.yaml
+│       └── production.yaml
+├── contracts/                 # API contracts (OpenAPI specs, Pact contracts)
+└── ci/                        # System-level CI/CD pipelines
+```
+
+**Choose the manifest format based on tier:**
+- **Lightweight**: `docker-compose.yml` with image tags pinned in `versions.yaml` or `.env`
+- **Standard**: Helm charts with `values-<env>.yaml` overrides, or Kustomize with base + overlays
+- **Enterprise**: Helm umbrella chart with sub-charts per service, or Kustomize with ApplicationSets
+
+## Step 3: Define the Version Pinning Strategy
+
+This is the core mechanism. The deployment repo acts as a **compatibility lock** — analogous to `package-lock.json` but at the system level.
+
+**Semantic versioning is the contract.** Each app repo tags releases with semver (`v1.2.3`). The deployment repo's `versions.yaml` records which versions have been validated together:
+
+```yaml
+# versions.yaml — the compatibility lock
+services:
+  api-gateway:
+    image: registry.example.com/api-gateway
+    version: v2.3.1
+  user-service:
+    image: registry.example.com/user-service
+    version: v1.7.0
+  billing-service:
+    image: registry.example.com/billing-service
+    version: v3.1.2
+
+validated:
+  timestamp: "2025-01-15T14:30:00Z"
+  e2e_result: pass
+  contract_result: pass
+```
+
+**Version pinning rules:**
+
+1. **Pin exact versions, not ranges** — `v1.7.0`, not `v1.x` or `latest`. The deployment repo records what was tested, not what might work.
+2. **Promote version sets, not individual services** — When staging's version set passes validation, the entire set promotes to production. This prevents "it worked in staging" failures caused by version drift.
+3. **Breaking changes require coordinated bumps** — If `api-gateway` v3.0.0 requires `user-service` v2.0.0, both versions update in the same deployment repo commit.
+4. **Every version combination that reaches an environment is recorded** — The deployment repo's git history IS the audit trail of what ran where and when.
+
+See [references/version-compatibility.md](references/version-compatibility.md) for semver contract details, compatibility matrices, and breaking change coordination patterns.
+
+## Step 4: Design Contract Tests
+
+Version pinning is only trustworthy if compatibility is actually tested. Contract tests validate that pinned versions can talk to each other.
+
+**Consumer-driven contracts (recommended for HTTP APIs):**
+- Each consumer service defines its expectations of a provider's API (a "contract")
+- Contracts live in the deployment repo's `contracts/` directory or are published to a Pact Broker
+- The deployment repo CI runs contract verification: for each service pair, verify that the pinned provider version satisfies the pinned consumer's contract
+- The **`can-i-deploy`** check (Pact Broker) answers: "are these specific versions compatible?"
+
+**Schema validation (recommended for event-driven systems):**
+- Event schemas (Avro, Protobuf, JSON Schema) live in the deployment repo or a schema registry
+- CI validates that producer schemas are backward-compatible with what consumers expect
+- Schema evolution rules: additive changes are safe, field removal/rename is breaking
+
+**What to test in the deployment repo CI:**
+1. Contract compatibility between all pinned service versions
+2. E2E smoke tests against the composed system (docker-compose up + test suite)
+3. Database migration compatibility (if services share a database)
+
+## Step 5: Set Up Environment Promotion
+
+The deployment repo PR is the promotion mechanism. No version reaches any environment without going through it.
+
+**Promotion flow:**
+
+```
+App repo tags v1.8.0
+    → Automated PR to deployment repo: "bump user-service to v1.8.0 in dev"
+        → CI runs contract tests + E2E in dev
+            → Merge → dev deploys automatically
+                → Manual PR: "promote dev version set to staging"
+                    → CI runs full E2E in staging
+                        → Merge → staging deploys
+                            → Manual PR with approval gate: "promote to production"
+                                → Merge → production deploys (canary optional)
+```
+
+**Key design decisions:**
+- **Dev**: auto-promote on merge, fast feedback
+- **Staging**: manual promotion trigger, full E2E validation
+- **Production**: approval gate (require N reviewers), optional canary rollout
+- **Rollback**: revert the deployment repo commit — the previous version set is restored
+
+For automated cross-repo triggers (app repo build -> deployment repo PR), see `gitops-delivery`.
+
+## Step 6: Validate and Document
+
+Verify the full lifecycle works:
+
+- [ ] A version bump in an app repo triggers an update in the deployment repo (manual or automated)
+- [ ] Contract tests catch an intentionally incompatible version combination
+- [ ] E2E tests run against the composed system in CI
+- [ ] Promotion from dev to staging works via PR
+- [ ] Rollback works by reverting a deployment repo commit
+- [ ] A new developer can `make up` and get the full system running locally
+- [ ] Adding a new service to the deployment repo is documented
+
+**Document for the team:**
+- How to add a new service to the deployment repo
+- How to bump a service version (manual process or automated trigger)
+- How to promote across environments
+- How to rollback
+- How to run E2E tests locally
+
+## Principles Applied
+
+- **Single source of truth**: The deployment repo is THE place to understand what's running where. Don't split this knowledge across wikis, Slack threads, and CI configs.
+- **KISS**: Start lightweight (docker-compose + versions.yaml). Graduate to Helm/ArgoCD when the pain of the simple approach exceeds the cost of the complex one.
+- **Explicit over implicit**: Pin exact versions. Record test results. Make the compatibility lock visible, not assumed.
+- **YAGNI**: Don't set up Helm umbrella charts for 3 services. Don't add ArgoCD before you have multiple environments. Scale the tooling to the problem.
+- **Promote sets, not services**: The fundamental principle — a validated version set moves together through environments.
+
+## Cross-Skill References
+
+- `gitops-delivery` — automate delivery from the deployment repo using ArgoCD/Flux and cross-repo triggers
+- `containerization` — Helm chart structure, Kustomize overlays, and Dockerfile patterns for services
+- `infrastructure-as-code` — Terraform modules for shared infrastructure in the deployment repo
+- `cicd-pipeline` — system-level CI pipelines and cross-repo pipeline design
+- `dependency-impact-analysis` — map blast radius of breaking changes across services before updating version pins
+- `rollback-strategy` — rollback in a deployment repo context is a git revert of the version set
+- `architecture-design` — ADR for adopting the deployment repo pattern itself

package/skills/deployment-repo/evals/evals.json

@@ -0,0 +1,44 @@
+{
+  "skill_name": "deployment-repo",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "We have 5 microservices in separate GitHub repos (auth-service, user-service, billing-service, notification-service, api-gateway). They communicate via REST APIs and a shared event bus (RabbitMQ). We deploy to Kubernetes with 3 environments (dev, staging, prod). How should we set up a deployment repo to coordinate them?",
+      "expected_output": "Should produce a standard-tier deployment repo structure with Helm or Kustomize for K8s, a versions.yaml pinning all 5 services, contract testing strategy for REST APIs and event schemas, environment promotion flow, and E2E test orchestration.",
+      "assertions": [
+        "Recommends a separate deployment repository, not embedding deployment config in app repos",
+        "Produces a directory structure with version pins, per-environment configs, and E2E tests",
+        "Designs a versions.yaml (or equivalent) pinning exact versions of all 5 services",
+        "Recommends Helm or Kustomize for multi-environment K8s manifests (not plain manifests)",
+        "Includes contract testing strategy for both REST APIs and event schemas",
+        "Defines environment promotion flow: dev -> staging -> prod with appropriate gates",
+        "Addresses how a version bump in an app repo reaches the deployment repo",
+        "Cross-references containerization for Helm chart details and gitops-delivery for automation"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "We're a small team with 3 services (FastAPI backend, Next.js frontend, PostgreSQL), all using Docker Compose for local dev and a single staging server. Is a deployment repo overkill for us?",
+      "expected_output": "Should validate the lightweight tier, recommend a simple deployment repo with docker-compose and version pinning, and explain how it scales up when needed. Should NOT push Kubernetes, Helm, or ArgoCD.",
+      "assertions": [
+        "Validates that a deployment repo is NOT overkill even for small teams",
+        "Recommends the lightweight tier with docker-compose and a simple version manifest",
+        "Does NOT recommend Kubernetes, Helm, or GitOps operators for this scale",
+        "Shows a minimal but useful repo structure (docker-compose, versions file, Makefile, .env.example)",
+        "Explains the immediate value: one command to run the full system, version tracking, onboarding",
+        "Acknowledges the pattern scales up as the team grows without requiring a rewrite"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "How do I write Pact contract tests between my frontend and backend API?",
+      "expected_output": "Should recognize this as a contract testing question that overlaps with but is not the core of the deployment-repo skill. Should provide brief context on how contract tests fit into the deployment repo pattern, then redirect to test-suite-design for implementation details.",
+      "assertions": [
+        "Recognizes this is primarily a testing question, not a deployment repo design question",
+        "Provides brief context on how contract tests relate to the deployment repo (they validate version compatibility)",
+        "References test-suite-design for detailed contract test implementation guidance",
+        "Does not attempt to be a full Pact tutorial within the deployment-repo skill"
+      ]
+    }
+  ]
+}