@slamb2k/mad-skills 2.0.55 → 2.0.57

package/skills/dock/references/pipeline-templates.md

@@ -19,12 +19,14 @@ Template variables:
 
 ## GitHub Actions
 
-### Build & Deploy Workflow
+### Build & Deploy Workflow (hardened)
 
-File: `.github/workflows/deploy.yml`
+Placeholders: `{REGISTRY}` (e.g. `ghcr.io/OWNER/REPO`), `{IMAGE_NAME}`.
+GHCR uses the ephemeral `GITHUB_TOKEN`; cloud registries use OIDC (see the
+commented block). Deployment is by digest and gated on signature verification.
 
 ```yaml
-name: Build & Deploy
+name: Release
 
 on:
   pull_request:
@@ -33,8 +35,8 @@ on:
     tags: ["v*"]
 
 concurrency:
-  group: deploy-${{ github.ref }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
 
 env:
   REGISTRY: {REGISTRY}
@@ -42,155 +44,112 @@ env:
 
 permissions:
   contents: read
-  packages: write
+  packages: write      # GHCR push
+  id-token: write       # OIDC: cloud login + keyless cosign
 
 jobs:
-  # ── Build & Test ──────────────────────────────────────────────
   build:
     runs-on: ubuntu-latest
-    # Skip for release tags — we retag, not rebuild
-    if: ${{ !startsWith(github.ref, 'refs/tags/v') }}
     outputs:
-      image_tag: ${{ steps.meta.outputs.tags }}
-      sha_short: ${{ steps.vars.outputs.sha_short }}
+      image: ${{ steps.digest.outputs.ref }}   # REGISTRY/IMAGE@sha256:...
     steps:
       - uses: actions/checkout@v4
 
-      - name: Set variables
-        id: vars
-        run: echo "sha_short=$(git rev-parse --short HEAD)" >> "$GITHUB_OUTPUT"
-
-      - name: Docker meta
-        id: meta
-        uses: docker/metadata-action@v5
-        with:
-          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
-          tags: |
-            type=sha,prefix=
-            type=ref,event=pr,prefix=pr-
-            type=raw,value=latest,enable=${{ github.ref == format('refs/heads/{0}', '{DEFAULT_BRANCH}') }}
-
       - uses: docker/setup-buildx-action@v3
 
-      - name: Login to registry
+      - uses: imjasonh/setup-crane@v0.4
+
+      # Idempotency guard: skip build if this commit's image already exists.
+      - name: Check existing image
+        id: guard
+        run: |
+          TAG="${REGISTRY}/${IMAGE_NAME}:${GITHUB_SHA}"
+          if crane manifest "$TAG" >/dev/null 2>&1; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+            echo "::notice::$TAG already present — reusing digest."
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      # GHCR login (ephemeral token). For cloud registries, replace with OIDC:
+      #   AWS ECR:  aws-actions/configure-aws-credentials@v4 (role-to-assume) + aws ecr get-login-password
+      #   Azure ACR: azure/login@v2 (WIF client-id/tenant-id/subscription-id) + az acr login
+      #   GAR:      google-github-actions/auth@v2 (workload_identity_provider + service_account) + gcloud auth configure-docker
+      - name: Login to GHCR
+        if: steps.guard.outputs.exists == 'false' && github.event_name == 'push'
         uses: docker/login-action@v3
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Build and test
-        uses: docker/build-push-action@v6
-        with:
-          context: .
-          target: test
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
-
-      - name: Build and push production image
-        if: github.event_name == 'push'
+      - name: Build and push
+        id: build
+        if: steps.guard.outputs.exists == 'false'
         uses: docker/build-push-action@v6
         with:
           context: .
           target: production
-          push: true
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
+          push: ${{ github.event_name == 'push' }}
+          tags: |
+            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}
+            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
+          provenance: true
+          sbom: true
 
-  # ── Deploy to Dev ─────────────────────────────────────────────
-  deploy-dev:
-    needs: build
-    if: github.ref == 'refs/heads/{DEFAULT_BRANCH}'
-    runs-on: ubuntu-latest
-    environment: dev
-    steps:
-      - uses: actions/checkout@v4
+      - uses: sigstore/cosign-installer@v3
 
-      - name: Deploy to dev
-        run: |
-          # {DEV_DEPLOY_COMMANDS}
-          echo "Deploying ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ needs.build.outputs.sha_short }} to dev"
+      - name: Sign image (keyless)
+        if: steps.guard.outputs.exists == 'false' && github.event_name == 'push'
+        run: cosign sign --yes "${REGISTRY}/${IMAGE_NAME}@${{ steps.build.outputs.digest }}"
 
-      - name: Smoke test
+      - name: Resolve digest reference
+        id: digest
         run: |
-          # Poll the health endpoint until ready (bounded deadline so a
-          # genuinely broken deploy still fails fast). Do not use a blind
-          # `sleep N && curl` — it flakes on slow cold starts and wastes
-          # time on fast ones.
-          deadline=$((SECONDS + 120))
-          until curl -fs "$DEV_URL/healthz" >/dev/null; do
-            if [ $SECONDS -ge $deadline ]; then
-              echo "Health check failed to pass within 120s" >&2
-              exit 1
-            fi
-            sleep 2
-          done
-
-  # ── Promote to Staging (on release tag) ───────────────────────
-  promote-staging:
-    if: startsWith(github.ref, 'refs/tags/v')
+          if [ "${{ steps.guard.outputs.exists }}" = "true" ]; then
+            DIG=$(crane digest "${REGISTRY}/${IMAGE_NAME}:${GITHUB_SHA}")
+          else
+            DIG="${{ steps.build.outputs.digest }}"
+          fi
+          echo "ref=${REGISTRY}/${IMAGE_NAME}@${DIG}" >> "$GITHUB_OUTPUT"
+
+  deploy-dev:
+    needs: build
+    if: github.event_name == 'push' && github.ref == 'refs/heads/{DEFAULT_BRANCH}'
     runs-on: ubuntu-latest
-    environment: staging
-    outputs:
-      version: ${{ steps.version.outputs.tag }}
+    permissions:
+      contents: read
+      id-token: write
     steps:
-      - uses: actions/checkout@v4
-
-      - name: Extract version
-        id: version
-        run: echo "tag=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
-
-      - name: Login to registry
-        uses: docker/login-action@v3
-        with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Retag image (no rebuild)
+      - uses: sigstore/cosign-installer@v3
+      - name: Verify signature before deploy
         run: |
-          SHA=$(git rev-parse --short HEAD)
-          docker buildx imagetools create \
-            --tag "${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ steps.version.outputs.tag }}" \
-            "${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${SHA}"
-
-      - name: Deploy to staging
-        run: |
-          # {STAGING_DEPLOY_COMMANDS}
-          echo "Deploying ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ steps.version.outputs.tag }} to staging"
-
-      - name: Run staging tests
-        run: |
-          # Integration and e2e tests against staging
-          echo "Running staging gate tests..."
-
-  # ── Promote to Production ─────────────────────────────────────
-  promote-prod:
-    needs: promote-staging
+          cosign verify \
+            --certificate-identity-regexp "https://github.com/${{ github.repository }}/.*" \
+            --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
+            "${{ needs.build.outputs.image }}"
+      - name: Deploy to dev (by digest — never rebuild)
+        run: echo "Deploy ${{ needs.build.outputs.image }} to dev"
+
+  promote:
+    needs: build
     if: startsWith(github.ref, 'refs/tags/v')
     runs-on: ubuntu-latest
-    environment: production
+    permissions:
+      contents: read
+      id-token: write
     steps:
-      - uses: actions/checkout@v4
-
-      - name: Deploy to production
-        run: |
-          # {PROD_DEPLOY_COMMANDS}
-          echo "Deploying ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ needs.promote-staging.outputs.version }} to production"
-
-      - name: Post-deploy smoke test
+      - uses: sigstore/cosign-installer@v3
+      - name: Verify signature
         run: |
-          # Poll until healthy, bounded deadline. Never `sleep N && curl`.
-          deadline=$((SECONDS + 120))
-          until curl -fs "$PROD_URL/healthz" >/dev/null; do
-            if [ $SECONDS -ge $deadline ]; then
-              echo "Production health check failed to pass within 120s" >&2
-              exit 1
-            fi
-            sleep 2
-          done
+          cosign verify \
+            --certificate-identity-regexp "https://github.com/${{ github.repository }}/.*" \
+            --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
+            "${{ needs.build.outputs.image }}"
+      - name: Promote to staging (by digest)
+        run: echo "Deploy ${{ needs.build.outputs.image }} to staging"
+      - name: Promote to prod (by digest)
+        run: echo "Deploy ${{ needs.build.outputs.image }} to prod"
 ```
 
 ### Reusable deploy step patterns
@@ -201,112 +160,80 @@ deployment steps.
 
 ---
 
-## Azure DevOps Pipelines
+## Azure DevOps Pipelines (hardened)
 
-File: `azure-pipelines.yml`
+Uses a **Workload Identity Federation** service connection (`azureSubscription`)
+for keyless ACR auth — no stored registry password. Images are signed and
+deployed by digest.
 
 ```yaml
 trigger:
-  branches:
-    include: [{DEFAULT_BRANCH}]
-  tags:
-    include: ["v*"]
-
-pr:
-  branches:
-    include: [{DEFAULT_BRANCH}]
+  branches: { include: [main] }
+  tags: { include: ["v*"] }
 
 variables:
+  azureSubscription: "<WIF-service-connection-name>"   # Workload Identity Federation
   registry: {REGISTRY}
   imageName: {IMAGE_NAME}
-  vmImageName: ubuntu-latest
 
 stages:
-  # ── Build & Test ──────────────────────────────────────────────
   - stage: Build
-    condition: not(startsWith(variables['Build.SourceBranch'], 'refs/tags/v'))
     jobs:
-      - job: BuildAndTest
-        pool:
-          vmImage: $(vmImageName)
+      - job: BuildSignPush
+        pool: { vmImage: ubuntu-latest }
         steps:
-          - task: Docker@2
-            displayName: Build test image
-            inputs:
-              command: build
-              dockerfile: Dockerfile
-              arguments: --target test -t $(imageName):test
-
-          - task: Docker@2
-            displayName: Build production image
+          - task: AzureCLI@2
+            displayName: ACR login (WorkloadIdentityFederation)
             inputs:
-              command: build
-              dockerfile: Dockerfile
-              arguments: --target production -t $(registry)/$(imageName):$(Build.SourceVersion)
-
-          - task: Docker@2
-            displayName: Push to registry
-            condition: eq(variables['Build.SourceBranch'], 'refs/heads/{DEFAULT_BRANCH}')
-            inputs:
-              command: push
-              containerRegistry: $(dockerRegistryServiceConnection)
-              repository: $(imageName)
-              tags: |
-                $(Build.SourceVersion)
-                latest
-
-  # ── Deploy to Dev ─────────────────────────────────────────────
-  - stage: DeployDev
-    condition: eq(variables['Build.SourceBranch'], 'refs/heads/{DEFAULT_BRANCH}')
+              azureSubscription: $(azureSubscription)
+              scriptType: bash
+              scriptLocation: inlineScript
+              inlineScript: az acr login --name $(echo $(registry) | cut -d. -f1)
+
+          - script: |
+              TAG="$(registry)/$(imageName):$(Build.SourceVersion)"
+              if docker manifest inspect "$TAG" >/dev/null 2>&1; then
+                echo "##vso[task.setvariable variable=exists]true"
+              else
+                echo "##vso[task.setvariable variable=exists]false"
+              fi
+            displayName: Idempotency guard
+
+          - script: |
+              docker buildx build --target production \
+                --provenance=true --sbom=true --push \
+                -t $(registry)/$(imageName):$(Build.SourceVersion) .
+            condition: ne(variables.exists, 'true')
+            displayName: Build, provenance, push
+
+          - script: |
+              DIG=$(docker buildx imagetools inspect $(registry)/$(imageName):$(Build.SourceVersion) --format '{{.Manifest.Digest}}')
+              echo "##vso[task.setvariable variable=digestRef;isOutput=true]$(registry)/$(imageName)@$DIG"
+            name: build
+            displayName: Resolve digest (both paths)
+
+          - script: cosign sign --yes $(build.digestRef)
+            condition: ne(variables.exists, 'true')
+            displayName: Sign image (keyless)
+
+  - stage: Promote
     dependsOn: Build
-    jobs:
-      - deployment: DeployDev
-        environment: dev
-        pool:
-          vmImage: $(vmImageName)
-        strategy:
-          runOnce:
-            deploy:
-              steps:
-                - script: |
-                    echo "Deploying $(registry)/$(imageName):$(Build.SourceVersion) to dev"
-                    # {DEV_DEPLOY_COMMANDS}
-
-  # ── Promote to Staging ────────────────────────────────────────
-  - stage: PromoteStaging
     condition: startsWith(variables['Build.SourceBranch'], 'refs/tags/v')
     jobs:
-      - deployment: DeployStaging
-        environment: staging
-        pool:
-          vmImage: $(vmImageName)
-        strategy:
-          runOnce:
-            deploy:
-              steps:
-                - script: |
-                    TAG=${BUILD_SOURCEBRANCH#refs/tags/}
-                    echo "Retagging and deploying $TAG to staging"
-                    # Retag — do NOT rebuild
-                    # {STAGING_DEPLOY_COMMANDS}
-
-  # ── Promote to Production ─────────────────────────────────────
-  - stage: PromoteProd
-    condition: startsWith(variables['Build.SourceBranch'], 'refs/tags/v')
-    dependsOn: PromoteStaging
-    jobs:
-      - deployment: DeployProd
-        environment: production
-        pool:
-          vmImage: $(vmImageName)
-        strategy:
-          runOnce:
-            deploy:
-              steps:
-                - script: |
-                    TAG=${BUILD_SOURCEBRANCH#refs/tags/}
-                    echo "Deploying $TAG to production"
-                    # {PROD_DEPLOY_COMMANDS}
+      - job: VerifyAndDeploy
+        pool: { vmImage: ubuntu-latest }
+        variables:
+          digestRef: $[ stageDependencies.Build.BuildSignPush.outputs['build.digestRef'] ]
+        steps:
+          # Set identity + issuer to your signing identity — see deploy/SETUP.md.
+          - script: |
+              cosign verify \
+                --certificate-identity-regexp "<CERT_IDENTITY_REGEXP>" \
+                --certificate-oidc-issuer "<OIDC_ISSUER>" \
+                $(digestRef)
+            displayName: Verify signature (by sha256 digest)
+          - script: echo "Deploy $(digestRef) to staging then prod (no rebuild)"
+            displayName: Promote by digest
 ```
 
 ---

package/skills/dock/tests/evals.json

@@ -41,5 +41,15 @@
       { "type": "semantic", "value": "Suggests Azure Container Registry rather than ghcr.io as the default registry" },
       { "type": "semantic", "value": "References Azure Pipelines as the CI system for the generated workflow" }
     ]
+  },
+  {
+    "name": "hardened-pipeline",
+    "prompt": "/dock --skip-interview for a Node.js app deploying to AWS ECR",
+    "assertions": [
+      { "type": "semantic", "value": "Uses OIDC / keyless federated authentication to the container registry rather than stored long-lived credentials" },
+      { "type": "semantic", "value": "Signs the built image (cosign) and verifies the signature before promoting to an environment" },
+      { "type": "semantic", "value": "Promotes images by immutable sha256 digest rather than a mutable tag" },
+      { "type": "semantic", "value": "Generates a deploy/SETUP.md describing the cloud-side federated-identity setup required before first run" }
+    ]
   }
 ]

package/skills/handover/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: handover
+description: Persist a session handover document and signal the next fresh session to resume from it. Use when the user types /handover, says they want to hand off, checkpoint, wrap up, clear context, or start fresh while preserving state, or asks to carry work into a new session with clean optimised context. Captures everything a brand-new session needs — task, status, next steps, key files, decisions, gotchas, git state — writes it to disk, arms a one-shot signal, and tells the user to /clear so the next session auto-loads it.
+argument-hint: repo, tmp, commit (optional target; default repo)
+allowed-tools: Bash, Read, Write
+---
+
+# Handover - Clean-Context Session Handoff
+
+When this skill is invoked, IMMEDIATELY output the banner below before doing anything else.
+Pick ONE tagline at random — vary your choice each time.
+CRITICAL: Reproduce the banner EXACTLY character-for-character, preserving all leading spaces.
+
+```
+{tagline}
+
+██╗  ██╗ █████╗ ███╗   ██╗██████╗  ██████╗ ██╗   ██╗███████╗██████╗
+██║  ██║██╔══██╗████╗  ██║██╔══██╗██╔═══██╗██║   ██║██╔════╝██╔══██╗
+███████║███████║██╔██╗ ██║██║  ██║██║   ██║██║   ██║█████╗  ██████╔╝
+██╔══██║██╔══██║██║╚██╗██║██║  ██║██║   ██║╚██╗ ██╔╝██╔══╝  ██╔══██╗
+██║  ██║██║  ██║██║ ╚████║██████╔╝╚██████╔╝ ╚████╔╝ ███████╗██║  ██║
+╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝╚═════╝  ╚═════╝   ╚═══╝  ╚══════╝╚═╝  ╚═╝
+```
+
+Taglines:
+- 🪂 Packing the parachute for a clean landing...
+- 🧳 Bagging up the context, checking out...
+- 🤝 Passing the baton to a fresh runner!
+- 📦 Boxing up everything the next session needs!
+- 🧹 Clearing the desk, leaving a tidy note!
+- 🛟 Nobody loses the thread on my watch!
+- 🌅 Fresh session, same mission!
+
+---
+
+## What this does
+
+Capture the live state of this session into a handover document, arm a one-shot
+signal, and hand the user off to a clean session that will automatically resume
+from the document. The point is to **reset the context window without losing the
+thread** — the next session starts lean but fully briefed.
+
+Long sessions accumulate noise: dead ends, superseded plans, stale file reads. A
+fresh session is faster and sharper, but naively starting over loses hard-won
+context. `/handover` distills only what the *next* session needs, persists it, and
+signals that session to pick it up — once. It will not re-read old handovers on
+unrelated future sessions, because the signal is consumed on first read.
+
+## Usage
+
+```
+/handover            # default: HANDOVER.md in repo root, kept OUT of git
+/handover repo       # same as default (explicit)
+/handover tmp        # write under /tmp — never touches the repo at all
+/handover commit     # write docs/handovers/HANDOVER-<timestamp>.md, meant to be committed
+```
+
+Read the argument from what the user typed. If none given, use `repo`.
+
+## Pre-flight
+
+Before starting, check dependencies:
+
+| Dependency | Type | Check | Required | Resolution | Detail |
+|-----------|------|-------|----------|------------|--------|
+| git | cli | `git rev-parse --show-toplevel` | no | fallback | Not in a git repo → use cwd for `repo` mode; skip `.git/info/exclude` step |
+| jq | cli | `command -v jq` | no | fallback | Signal loader falls back to sed + raw-stdout injection; no behavior change |
+
+Resolve the plugin root once for the signal command:
+
+```bash
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/marketplaces/slamb2k}"
+```
+
+## What to do
+
+Work through these steps in order. Don't skip the verification at the end.
+
+### 1. Resolve the target path
+
+First get the repo root and a timestamp:
+
+```bash
+git rev-parse --show-toplevel 2>/dev/null   # repo root, or empty if not a git repo
+date +%Y-%m-%d-%H%M
+```
+
+Then pick the path based on the argument:
+
+- **`repo`** (default): `<repo_root>/HANDOVER.md`. If not inside a git repo, use the
+  current working directory instead. After writing, keep it out of version control
+  by appending `HANDOVER.md` to `<repo_root>/.git/info/exclude` if it's a git repo
+  and not already listed there. This is a *local* ignore — it never modifies the
+  tracked `.gitignore`, so it won't show up in anyone else's checkout or your diffs.
+- **`tmp`**: `/tmp/claude-handover/<key>/HANDOVER.md` where `<key>` is
+  `printf '%s' "$(pwd)" | cksum | cut -d' ' -f1`. Create the directory first.
+  Nothing is written inside the repo.
+- **`commit`**: `<repo_root>/docs/handovers/HANDOVER-<timestamp>.md`. Create the
+  `docs/handovers/` directory if needed. Do **not** ignore it — this variant exists
+  precisely so the handover lands in git history as a durable checkpoint. Mention to
+  the user that they'll want to commit it.
+
+### 2. Write the handover document
+
+This is the core of the skill — the document quality determines whether the next
+session is productive or lost. Follow the structure in
+`references/handover-template.md`. Read that file now if you haven't.
+
+Fill it from the **actual conversation and repo state**, not generic boilerplate.
+Be concrete: real file paths, real function names, real commands, real decisions.
+Write for a competent engineer who has *zero* memory of this session — every
+assumption in your head right now is invisible to them unless you write it down.
+
+Gather git state to embed in the document:
+
+```bash
+git -C <repo_root> branch --show-current
+git -C <repo_root> status --short
+git -C <repo_root> log --oneline -8
+```
+
+Optimise for *their* context budget: include what unblocks action, link to files
+rather than pasting large code, and cut the narrative of how you got here unless a
+dead end is a genuine landmine worth a warning.
+
+### 3. Arm the one-shot signal
+
+After the document is written, run (using the `PLUGIN_ROOT` resolved in pre-flight):
+
+```bash
+bash "$PLUGIN_ROOT/skills/handover/scripts/handover.sh" signal "<absolute_path_to_handover>"
+```
+
+This drops a signal keyed to the current project directory. The next session's
+`SessionStart` hook — shipped with this plugin in `hooks/hooks.json` — detects it,
+injects the handover as context, and deletes the signal so it fires exactly once.
+Use the **absolute** path.
+
+### 4. Hand off to a fresh session
+
+Tell the user plainly that the handover is ready and they should start the fresh
+session themselves. You **cannot** trigger `/clear` programmatically — it is a
+user-only command — so the final step is theirs. Say something like:
+
+> Handover written to `<path>` and the next session is armed. Type **`/clear`**
+> (or **`/new`**) now — the fresh session will automatically load this handover and
+> pick up where we left off. Nothing else gets auto-loaded; the signal is consumed
+> on first read.
+
+Keep this final message short. The work is done; don't bury the one action they
+need to take.
+
+## Important constraints
+
+- **`/clear` is the user's to type.** No skill, hook, or command can clear the
+  context window automatically. Always end by asking them to do it.
+- **The signal is one-shot and project-scoped.** It's keyed to the working
+  directory and deleted on first read, so handovers never leak into unrelated
+  sessions. A `HANDOVER.md` left sitting in a repo is inert unless re-armed.
+- **Don't pollute git by default.** Only the `commit` variant is meant to be
+  tracked. `repo` mode relies on `.git/info/exclude`; `tmp` mode stays entirely
+  outside the repo.
+- **If `/handover` is run again later**, overwrite the existing document and
+  re-arm the signal — the latest state wins.