swe-workflow-skills 0.1.0

package/skills/git-workflow/references/conventions.md

@@ -0,0 +1,142 @@
+# Git Conventions
+
+## Contents
+- Conventional Commits types
+- Branch naming conventions
+- Commit message examples
+- When to squash vs keep history
+- Interactive rebase patterns
+
+## Conventional Commits Types
+
+| Type | When to Use | Triggers Version Bump |
+|------|-------------|----------------------|
+| `feat` | New feature visible to users | Minor (0.X.0) |
+| `fix` | Bug fix | Patch (0.0.X) |
+| `refactor` | Code change that neither fixes a bug nor adds a feature | None |
+| `test` | Adding or correcting tests | None |
+| `docs` | Documentation only changes | None |
+| `chore` | Maintenance (deps, configs, scripts) | None |
+| `perf` | Performance improvement | Patch (0.0.X) |
+| `ci` | CI/CD pipeline changes | None |
+| `build` | Build system or dependency changes | None |
+| `style` | Formatting, whitespace (no logic change) | None |
+| `revert` | Reverts a previous commit | Depends on reverted type |
+
+`BREAKING CHANGE:` in the footer bumps the major version (X.0.0) regardless of type.
+
+## Branch Naming Conventions
+
+Pattern: `<type>/<short-description>`
+
+- `feat/user-notifications` — new feature
+- `fix/login-redirect-loop` — bug fix
+- `refactor/extract-payment-service` — code improvement
+- `docs/api-endpoint-reference` — documentation
+- `chore/upgrade-node-20` — maintenance
+- `hotfix/payment-double-charge` — urgent production fix
+- `release/2.1.0` — release preparation
+
+Rules:
+- Lowercase, kebab-case
+- Short but descriptive (3-5 words max)
+- Include ticket number if your team uses one: `feat/PROJ-123-user-notifications`
+
+## Commit Message Examples
+
+**Good: Simple feature**
+```
+feat(auth): add password reset via email
+
+Users can now request a password reset link sent to their registered
+email address. The link expires after 1 hour.
+
+Closes #234
+```
+
+**Good: Bug fix with context**
+```
+fix(orders): prevent duplicate charge on retry
+
+When a payment API call timed out, the retry logic would create a
+second charge because it didn't check for an existing pending charge.
+Added idempotency key to prevent duplicate transactions.
+
+Fixes #456
+```
+
+**Good: Refactoring with rationale**
+```
+refactor(api): extract validation middleware from controllers
+
+Controller files were growing large because each one duplicated
+request validation logic. Extracted shared validation into middleware
+that runs before the controller, reducing average controller size
+by ~40%.
+```
+
+**Good: Breaking change**
+```
+feat(api): require API key for all endpoints
+
+Previously, read-only endpoints were public. Now all endpoints
+require authentication via API key header.
+
+BREAKING CHANGE: All API requests must include X-API-Key header.
+Existing integrations will receive 401 until they add the header.
+
+Closes #567
+```
+
+**Bad examples and why:**
+```
+# Too vague — what was updated?
+chore: update stuff
+
+# Describes WHAT not WHY — the diff shows what
+fix: change line 42 in user.js
+
+# Too many things in one commit
+feat: add login, registration, password reset, and profile page
+
+# Useless body that repeats the subject
+fix: fix the bug
+This commit fixes the bug that was reported.
+```
+
+## When to Squash vs Keep History
+
+**Squash into a single commit when:**
+- The branch has "WIP", "fix typo", "oops" commits
+- The intermediate commits are meaningless on their own
+- The change is a single logical unit
+
+**Keep multiple commits when:**
+- Each commit represents a meaningful step (e.g., "add migration", "add model", "add API endpoint")
+- The commits tell a useful story about the development process
+- Reviewers might want to review step-by-step
+
+**Recommendation**: Default to squash-merge for PRs, unless the author deliberately structured commits for readability.
+
+## Interactive Rebase Patterns
+
+Clean up history before requesting review:
+
+```bash
+# Rebase the last N commits
+git rebase -i HEAD~N
+
+# In the editor:
+pick abc1234 feat(auth): add login endpoint        # keep
+squash def5678 fix typo                             # fold into previous
+squash ghi9012 WIP                                  # fold into previous
+pick jkl3456 feat(auth): add registration endpoint  # keep as separate commit
+drop mno7890 debugging leftovers                    # delete entirely
+```
+
+Common operations:
+- `pick` — keep the commit as-is
+- `squash` — merge into the previous commit (combine messages)
+- `fixup` — merge into the previous commit (discard this message)
+- `reword` — keep the commit but edit the message
+- `drop` — delete the commit entirely

package/skills/git-workflow/templates/pull-request.md

@@ -0,0 +1,57 @@
+# Pull Request Description Template
+
+```markdown
+## What
+
+[1-2 sentences: what this PR does. Complete the sentence "This PR..."]
+
+## Why
+
+[Why is this change needed? Link to issue, task, or feature plan.]
+
+Closes #[issue-number]
+
+## How
+
+[Brief description of the approach. Highlight key decisions, trade-offs,
+or anything non-obvious about the implementation.]
+
+## Changes
+
+[Bullet list of the main changes, grouped logically. Not every file —
+just the meaningful changes.]
+
+- Added `OrderService.calculateDiscount()` for percentage-based discounts
+- Updated `Order` model with `discount_code` field and migration
+- Added validation for discount codes in `POST /orders` endpoint
+
+## Testing
+
+[How were these changes tested? Be specific.]
+
+- Unit tests for discount calculation (including edge cases: 0%, 100%, expired codes)
+- Integration test for the order creation endpoint with discount
+- Manual testing on staging with real Stripe test keys
+
+## Screenshots
+
+[For UI changes — before/after. Delete this section if not applicable.]
+
+| Before | After |
+|--------|-------|
+| [screenshot] | [screenshot] |
+
+## Checklist
+
+- [ ] Tests pass
+- [ ] No linting errors
+- [ ] Documentation updated (if applicable)
+- [ ] Migration is reversible
+- [ ] No hardcoded secrets or environment-specific values
+- [ ] PR is a reasonable size (< 400 lines changed)
+
+## Notes for Reviewers
+
+[Optional: anything the reviewer should pay special attention to,
+areas of uncertainty, or questions you have about the approach.]
+```

package/skills/gitops-delivery/SKILL.md

@@ -0,0 +1,319 @@
+---
+name: gitops-delivery
+description: "Design GitOps continuous delivery with ArgoCD or Flux — declarative reconciliation, cross-repo CI/CD triggers, drift detection, progressive delivery. Triggers: ArgoCD, Flux, FluxCD, GitOps, git-based deployment, declarative delivery, auto-sync, drift detection, cross-repo trigger, reconciliation loop, pull-based deployment, canary GitOps."
+model: sonnet
+allowed-tools: Read, Grep, Glob, Write, Edit, Bash
+---
+
+# GitOps Delivery
+
+GitOps makes Git the single source of truth for deployment state. An operator watches a Git repository and continuously reconciles the cluster to match what's declared in Git. The deployment repo defines the desired state — the GitOps operator enforces it.
+
+## Step 1: Choose the GitOps Model
+
+**Pull-based (recommended):** An operator running in the cluster watches the deployment repo and applies changes. No CI system needs cluster credentials.
+- **ArgoCD**: Application-centric, strong UI, sync waves for ordering, multi-cluster support
+- **Flux**: Toolkit-based, composable, native Kustomize/Helm support, image automation
+
+**Push-based (simpler but less robust):** CI pipeline runs `kubectl apply` or `helm upgrade` after building. Simpler to set up but has drawbacks: CI needs cluster credentials, no drift detection, no self-healing.
+
+**Decision guide:**
+
+| Factor | Push-based | Pull-based (GitOps) |
+|--------|-----------|-------------------|
+| **Setup complexity** | Lower | Higher initial setup |
+| **Cluster credentials** | CI needs them | Only operator needs them |
+| **Drift detection** | None | Automatic |
+| **Self-healing** | None | Operator reverts manual changes |
+| **Audit trail** | CI logs | Git history (stronger) |
+| **Multi-cluster** | Duplicated CI jobs | Native support |
+
+**When push-based is fine:** Single cluster, single environment, small team, no compliance requirements. See `cicd-pipeline` for push-based patterns.
+
+**When GitOps is worth it:** Multiple environments, compliance/audit needs, multi-cluster, or you want drift detection and self-healing.
+
+## Step 2: Design Cross-Repo Triggers
+
+The critical bridge: when an app repo builds a new image, the deployment repo must be updated. This is the most common source of friction in GitOps setups.
+
+**Pattern A: Automated PR via GitHub Actions `repository_dispatch`**
+
+App repo CI triggers a workflow in the deployment repo:
+
+```yaml
+# In app repo: .github/workflows/release.yml
+- name: Trigger deployment repo update
+  uses: peter-evans/repository-dispatch@v3
+  with:
+    token: ${{ secrets.DEPLOY_REPO_TOKEN }}
+    repository: org/deployment-repo
+    event-type: version-bump
+    client-payload: |
+      {
+        "service": "user-service",
+        "version": "v1.8.0",
+        "image": "ghcr.io/org/user-service:v1.8.0"
+      }
+```
+
+```yaml
+# In deployment repo: .github/workflows/version-bump.yml
+on:
+  repository_dispatch:
+    types: [version-bump]
+
+jobs:
+  update-version:
+    steps:
+      - uses: actions/checkout@v4
+      - name: Update versions.yaml
+        run: |
+          yq e ".services.${{ github.event.client_payload.service }}.version = \"${{ github.event.client_payload.version }}\"" \
+            -i environments/dev/versions.yaml
+      - name: Create PR
+        uses: peter-evans/create-pull-request@v6
+        with:
+          title: "bump ${{ github.event.client_payload.service }} to ${{ github.event.client_payload.version }}"
+          branch: "bump/${{ github.event.client_payload.service }}-${{ github.event.client_payload.version }}"
+```
+
+**Pattern B: Renovate / Dependabot for image tags**
+
+Configure Renovate to watch container registries and create PRs when new tags appear:
+
+```json
+{
+  "packageRules": [
+    {
+      "matchDatasources": ["docker"],
+      "matchPackagePatterns": ["ghcr.io/org/*"],
+      "automerge": false,
+      "labels": ["version-bump"]
+    }
+  ]
+}
+```
+
+**Pattern C: GitLab CI downstream pipeline**
+
+```yaml
+# In app repo: .gitlab-ci.yml
+trigger-deployment:
+  stage: deploy
+  trigger:
+    project: org/deployment-repo
+    branch: main
+    strategy: depend
+  variables:
+    SERVICE_NAME: user-service
+    SERVICE_VERSION: $CI_COMMIT_TAG
+```
+
+**Recommendation:** Pattern A (repository_dispatch + PR) for most teams. It creates an auditable PR, allows contract tests to run before merge, and doesn't require additional tooling. Use Pattern B (Renovate) if you want fully automated version tracking without custom workflows.
+
+## Step 3: Configure the GitOps Operator
+
+### ArgoCD Setup
+
+**Application per service per environment:**
+
+```yaml
+# argocd/staging/user-service.yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: user-service-staging
+  namespace: argocd
+  labels:
+    environment: staging
+    service: user-service
+spec:
+  project: default
+  source:
+    repoURL: https://github.com/org/deployment-repo
+    targetRevision: main
+    path: helm/user-service
+    helm:
+      valueFiles:
+        - ../../environments/staging/user-service-values.yaml
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: staging
+  syncPolicy:
+    automated:              # Auto-sync for staging
+      prune: true           # Remove resources not in Git
+      selfHeal: true        # Revert manual changes
+    syncOptions:
+      - CreateNamespace=true
+    retry:
+      limit: 3
+      backoff:
+        duration: 5s
+        factor: 2
+```
+
+**Production — manual sync with approval:**
+
+```yaml
+# argocd/production/user-service.yaml
+spec:
+  syncPolicy: {}            # No automated sync — requires manual sync or CI trigger
+  # Add sync windows to restrict when syncs can happen:
+  syncPolicy:
+    syncOptions:
+      - CreateNamespace=true
+    # Sync windows defined in the ArgoCD project
+```
+
+**App of Apps pattern (manage all Applications as a single unit):**
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: platform-staging
+spec:
+  source:
+    repoURL: https://github.com/org/deployment-repo
+    path: argocd/staging       # Directory containing all Application YAMLs
+  destination:
+    server: https://kubernetes.default.svc
+```
+
+**Sync waves (control deployment order):**
+
+```yaml
+# Database migration job runs first (wave 0), then services (wave 1), then ingress (wave 2)
+metadata:
+  annotations:
+    argocd.argoproj.io/sync-wave: "0"   # Lower runs first
+```
+
+### Flux Setup
+
+```yaml
+# flux/staging/kustomization.yaml
+apiVersion: kustomize.toolkit.fluxcd.io/v1
+kind: Kustomization
+metadata:
+  name: staging-apps
+  namespace: flux-system
+spec:
+  interval: 5m
+  sourceRef:
+    kind: GitRepository
+    name: deployment-repo
+  path: ./overlays/staging
+  prune: true
+  healthChecks:
+    - apiVersion: apps/v1
+      kind: Deployment
+      name: user-service
+      namespace: staging
+  timeout: 3m
+```
+
+**Flux image automation (auto-update image tags):**
+
+```yaml
+apiVersion: image.toolkit.fluxcd.io/v1beta2
+kind: ImagePolicy
+metadata:
+  name: user-service
+spec:
+  imageRepositoryRef:
+    name: user-service
+  policy:
+    semver:
+      range: ">=1.0.0"
+```
+
+See [references/gitops-patterns.md](references/gitops-patterns.md) for complete manifests and [templates/gitops-config.md](templates/gitops-config.md) for ready-to-use templates.
+
+## Step 4: Implement Progressive Delivery
+
+Layer progressive delivery on top of GitOps for safer production rollouts. This step is optional for lightweight setups but critical at scale.
+
+**Argo Rollouts (works with ArgoCD):**
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Rollout
+metadata:
+  name: user-service
+spec:
+  strategy:
+    canary:
+      steps:
+        - setWeight: 10       # Send 10% of traffic to new version
+        - pause: { duration: 5m }
+        - analysis:
+            templates:
+              - templateName: success-rate
+        - setWeight: 50
+        - pause: { duration: 10m }
+        - analysis:
+            templates:
+              - templateName: success-rate
+      # Auto-rollback if analysis fails
+```
+
+**Analysis template (gate on metrics):**
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: AnalysisTemplate
+metadata:
+  name: success-rate
+spec:
+  metrics:
+    - name: success-rate
+      interval: 1m
+      successCondition: result[0] >= 0.99
+      provider:
+        prometheus:
+          address: http://prometheus:9090
+          query: |
+            sum(rate(http_requests_total{service="user-service",status=~"2.."}[5m]))
+            /
+            sum(rate(http_requests_total{service="user-service"}[5m]))
+```
+
+**Flagger (works with Flux):** Similar concept — canary analysis using Prometheus, Datadog, or other metrics providers. Flagger automatically manages the canary/primary services and traffic splitting.
+
+**When to skip progressive delivery:** Dev and staging environments (just deploy directly). Small teams with low traffic. Services with comprehensive E2E tests that catch issues before deploy.
+
+## Step 5: Validate End-to-End
+
+Test the full GitOps pipeline:
+
+- [ ] **Trigger flow**: Merge a change in an app repo -> verify a PR appears in the deployment repo
+- [ ] **Contract validation**: The deployment repo PR CI runs contract tests against the new version combination
+- [ ] **GitOps sync**: After merging the deployment repo PR, the operator detects the change and syncs
+- [ ] **Health checks**: The operator reports healthy status after sync
+- [ ] **Drift detection**: Manually modify a resource in the cluster -> verify the operator reverts it
+- [ ] **Rollback**: Revert a commit in the deployment repo -> verify the operator rolls back the cluster
+- [ ] **Sync windows** (if configured): Verify syncs are blocked outside allowed windows
+- [ ] **Progressive delivery** (if configured): Verify canary analysis runs and gates promotion
+
+**Monitoring the GitOps pipeline:**
+- ArgoCD: Built-in UI shows sync status, health, and history per Application
+- Flux: `flux get kustomizations` shows reconciliation status
+- Both: Export metrics to Prometheus for alerting on sync failures
+
+## Principles Applied
+
+- **Git is the source of truth**: If it's not in Git, it doesn't exist. No `kubectl edit` in production, no manual Helm upgrades.
+- **Pull over push**: The cluster pulls desired state from Git rather than CI pushing to the cluster. This inverts the security model — the cluster needs Git read access, not the other way around.
+- **KISS**: Start with a single ArgoCD Application per environment. Add App of Apps, sync waves, and progressive delivery as complexity demands.
+- **YAGNI**: Don't set up Argo Rollouts for a service with 10 requests per minute. Don't configure multi-cluster GitOps for a single cluster.
+- **Declarative over imperative**: Define the desired state, let the operator figure out how to get there. Avoid custom sync scripts.
+
+## Cross-Skill References
+
+- `deployment-repo` — the Git repository that the GitOps operator watches; design the repo structure first
+- `cicd-pipeline` — cross-repo trigger pipelines that update the deployment repo on new builds
+- `rollback-strategy` — in GitOps, rollback = revert a Git commit; the operator handles the rest
+- `observability-design` — metrics and dashboards for monitoring sync status, drift, and progressive delivery analysis
+- `containerization` — Helm chart structure and Kustomize overlay patterns used by the operator
+- `infrastructure-as-code` — Terraform for cluster and infrastructure provisioning (separate from app deployment)

package/skills/gitops-delivery/evals/evals.json

@@ -0,0 +1,44 @@
+{
+  "skill_name": "gitops-delivery",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "We have a deployment repo with Helm charts for our 5 services. We want to set up ArgoCD to automatically deploy to our staging cluster when the deployment repo is updated, but require manual sync for production. How should we configure this?",
+      "expected_output": "Should create ArgoCD Application resources per service per environment, with automated sync policy for staging and no automated sync for production. Should include health checks, sync waves if ordering matters, and RBAC considerations.",
+      "assertions": [
+        "Creates ArgoCD Application manifests for each service in staging with automated sync (prune + selfHeal)",
+        "Creates ArgoCD Application manifests for production WITHOUT automated sync",
+        "Uses the deployment repo as the source (repoURL points to the deployment repo)",
+        "Configures per-environment value files (staging vs production Helm values)",
+        "Includes health checks in sync policy",
+        "Recommends App of Apps pattern for managing all Applications as a unit",
+        "References deployment-repo for the repo structure itself"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Our app repo CI builds a Docker image and pushes it to GHCR. How do I automatically update the deployment repo when a new image is built?",
+      "expected_output": "Should present cross-repo trigger patterns with concrete workflow YAML, recommending the PR-based approach for auditability.",
+      "assertions": [
+        "Presents at least 2 cross-repo trigger patterns (repository_dispatch + PR, Renovate, or similar)",
+        "Recommends the pattern that creates a PR (not direct push) for auditability",
+        "Shows concrete GitHub Actions workflow YAML for both the app repo trigger and deployment repo receiver",
+        "Explains that the deployment repo PR triggers contract/E2E tests before merge",
+        "Does not assume the user already has ArgoCD — the trigger pattern works regardless of the delivery mechanism"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Should I use ArgoCD or just keep deploying from our CI pipeline with kubectl apply? We have a single Kubernetes cluster and 3 services.",
+      "expected_output": "Should present an honest trade-off analysis rather than assuming GitOps is always the answer. Should help the user decide based on their scale and needs.",
+      "assertions": [
+        "Does NOT assume GitOps is always the right answer",
+        "Presents trade-offs: setup complexity vs. drift detection, audit trail, self-healing",
+        "Acknowledges that push-based (kubectl apply from CI) is simpler and may be sufficient for this scale",
+        "Identifies signals that would make GitOps worth it (compliance, multi-env, drift concerns)",
+        "References cicd-pipeline for push-based deployment patterns if that's the better fit",
+        "References deployment-repo regardless — version pinning is valuable even without GitOps operators"
+      ]
+    }
+  ]
+}