@slamb2k/mad-skills 2.0.55 → 2.0.57

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "mad-skills",
   "description": "AI-assisted planning, development and governance tools",
-  "version": "2.0.55",
+  "version": "2.0.57",
   "author": {
     "name": "slamb2k",
     "url": "https://github.com/slamb2k"

package/hooks/hooks.json

@@ -2,7 +2,10 @@
   "hooks": {
     "SessionStart": [{
       "matcher": "startup|clear|compact",
-      "hooks": [{ "type": "command", "command": "_R=\"${CLAUDE_PLUGIN_ROOT}\"; [ -z \"$_R\" ] && _R=\"$HOME/.claude/plugins/marketplaces/slamb2k\"; node \"$_R/hooks/session-guard.cjs\" check", "timeout": 30 }]
+      "hooks": [
+        { "type": "command", "command": "_R=\"${CLAUDE_PLUGIN_ROOT}\"; [ -z \"$_R\" ] && _R=\"$HOME/.claude/plugins/marketplaces/slamb2k\"; node \"$_R/hooks/session-guard.cjs\" check", "timeout": 30 },
+        { "type": "command", "command": "_R=\"${CLAUDE_PLUGIN_ROOT}\"; [ -z \"$_R\" ] && _R=\"$HOME/.claude/plugins/marketplaces/slamb2k\"; bash \"$_R/skills/handover/scripts/handover.sh\" load", "timeout": 10 }
+      ]
     }],
     "UserPromptSubmit": [{
       "hooks": [{ "type": "command", "command": "_R=\"${CLAUDE_PLUGIN_ROOT}\"; [ -z \"$_R\" ] && _R=\"$HOME/.claude/plugins/marketplaces/slamb2k\"; node \"$_R/hooks/session-guard.cjs\" remind", "timeout": 10 }]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slamb2k/mad-skills",
-  "version": "2.0.55",
+  "version": "2.0.57",
   "description": "Claude Code skills collection — full lifecycle development tools",
   "type": "module",
   "repository": {

package/skills/build/SKILL.md

@@ -76,6 +76,8 @@ Parse optional flags from the request:
 - `--no-ship`: Stop after Stage 8 docs update
 - `--parallel-impl`: Split implementation into parallel agents when independent
 - `--no-superpowers`: Force the standalone pipeline even when Superpowers is installed
+- `--handoff`: Skip the execution-mode question and hand off to a clean session
+- `--no-handoff`: Skip the execution-mode question and run here now
 
 ---
 
@@ -91,6 +93,7 @@ Before starting, check all dependencies in this table:
 | feature-dev:code-architect | agent | — | no | fallback | Uses general-purpose agent |
 | feature-dev:code-reviewer | agent | — | no | fallback | Uses general-purpose agent |
 | superpowers | plugin | on-disk glob via scripts/lib/superpowers.js | no | fallback | Routes Stage 4 impl core to superpowers:executing-plans / subagent-driven-development when present; see references/superpowers-deferral.md |
+| handover | skill | `ls .claude/skills/handover/SKILL.md ~/.claude/skills/handover/SKILL.md ~/.claude/plugins/marketplaces/slamb2k/skills/handover/SKILL.md 2>/dev/null` | no | fallback | Powers the "hand off to a clean session" execution mode; ships with mad-skills, so normally present |
 
 For each row, in order:
 1. Run the Check command (for cli/npm) or test file existence (for agent/skill)
@@ -193,6 +196,67 @@ Before starting Stage 1, verify the working tree is suitable for building:
 
 ---
 
+## Execution Mode
+
+`/build` runs every heavy stage in subagents, so the primary conversation stays
+compact *during* the build. The one thing subagents can't fix is a context
+window that's **already** large when you invoke `/build` — the orchestrator
+(this thread) still reads reports and runs the review/ship loop on top of
+whatever came before. For that, a clean start beats a clean middle.
+
+So there is exactly one execution-mode decision, and subagents are always on
+underneath either choice:
+
+- **Run here now** — orchestrate the build in this session, stages in subagents.
+- **Hand off to a clean session** — write a handover, arm the resume signal, and
+  let a fresh session run the *same* `/build` with its own subagents.
+
+These are mutually exclusive — one stops here, one continues here. Do **not**
+offer a "clear? yes/no" toggle on top of run-now; the handover mode *replaces*
+the run-now decision.
+
+**Resolve the mode:**
+
+1. If `--no-handoff` → run here now. Skip to Stage 1.
+2. If `--handoff` → hand off (only if the handover skill exists; else warn it's
+   unavailable and run here now).
+3. If the handover skill is **not** installed (pre-flight) → run here now
+   silently. No question.
+4. Otherwise, decide whether to *offer* the hand-off at all. Only offer it when a
+   clean start would actually help **and** the plan can survive the reset:
+   - **Context already large** — this session has had substantial prior work
+     before `/build` (long conversation, many file reads, a prior task), so the
+     orchestrator would start bloated. A fresh `/build` invocation in an empty
+     session does not need this — just run here now.
+   - **Plan is self-contained** — PLAN is a spec file or a complete written plan
+     that a handover doc can capture losslessly. If the plan leans on nuance from
+     *this* conversation (decisions made live, things looked at together), a
+     handover is lossy — prefer run-here-now so that context isn't thrown away.
+
+   If **both** hold, ask via `AskUserQuestion`:
+   ```
+   "This session already carries significant context. Hand this build off to a
+   clean session, or run it here now?"
+   ```
+   Options:
+   - **"Run here now (Recommended)"** — orchestrate in this session (subagents underneath).
+   - **"Hand off to a clean session"** — reset context, resume the build fresh.
+
+   If either condition fails, don't ask — run here now.
+
+**If handing off:** capture the resolved PLAN and any Stage-2 clarifications
+gathered so far, then invoke the `handover` skill. The handover document's
+"next steps" MUST be a single resume action: re-run this exact build in the
+fresh session, e.g. `/build {original PLAN argument}` (plus any active flags,
+minus `--handoff`). Include the resolved plan content and PROJECT_CONFIG so the
+fresh session doesn't re-derive them. The handover skill arms the one-shot
+signal and tells the user to `/clear`. **Stop here** — do not run Stage 1; the
+fresh session does.
+
+**If running here now:** continue to Stage 1 unchanged.
+
+---
+
 ## Stage 1: Explore
 
 Launch **feature-dev:code-explorer** (fallback: general-purpose):

package/skills/dock/SKILL.md

@@ -280,6 +280,14 @@ with development overrides (volume mounts, hot reload, debug ports).
 Detect CI system from Phase 1 (GitHub Actions / Azure Pipelines / GitLab CI).
 Read the appropriate template from `references/pipeline-templates.md`.
 
+For GitHub Actions and Azure Pipelines, the templates are **hardened by default**
+— read `references/hardening.md` for the OIDC auth, keyless cosign signing,
+idempotency guards, and digest-pinned promotion these templates implement. The
+generated workflow MUST include `id-token: write`, `provenance: true`, a cosign
+`sign` in the build job and `verify` in every promotion job, an existence guard
+before build, and deploy steps that reference the image by `@sha256:` digest.
+(GitLab CI remains credential-based.)
+
 Generate a workflow that implements:
 
 **On pull request:**
@@ -349,6 +357,14 @@ If the detected framework doesn't already have a health endpoint, add a comment
 in the generated workflow noting that a `/healthz` or `/health` endpoint is
 recommended for deployment readiness probes.
 
+### 3.7 — Deployment Setup Guide (deploy/SETUP.md)
+
+Because the pipelines are secure by default, first-run requires one-time
+cloud-side trust. Generate `deploy/SETUP.md` from the **Generated deploy/SETUP.md**
+section of `references/hardening.md`, substituting the target repo (`OWNER/REPO`),
+chosen registry, and cloud identifiers. This file lists the federated-credential
+/ IAM-trust steps and the cosign verification command.
+
 ---
 
 ## Phase 4: Verify
@@ -366,6 +382,10 @@ Also validate generated workflow files:
 - GitHub Actions: check YAML syntax
 - Azure Pipelines: check YAML syntax
 - GitLab CI: check YAML syntax
+- For the GitHub workflow, confirm it sets `id-token: write`; for Azure Pipelines,
+  confirm it authenticates via a Workload Identity Federation service connection
+  (`azureSubscription`). Both must contain a cosign `sign`+`verify` pair and
+  reference deploy images by `@sha256:` digest. Flag any absence as a generation error.
 
 Present the user with a summary of all generated files before writing.
 
@@ -396,6 +416,11 @@ After all files are generated and verified, present:
 │     Merge → build + test → push → deploy dev → smoke
 │     Tag   → retag (no rebuild) → staging → e2e → prod
 │
+│  🔐 Required cloud setup
+│     • Configure federated identity (see deploy/SETUP.md)
+│     • {registry-specific: IAM role / ACR federated cred / GCP WIP}
+│     • First run fails until trust is configured — this is expected
+│
 │  🔗 Links
 │     Dockerfile:  {path}
 │     Workflow:    {path}

package/skills/dock/references/hardening.md

@@ -0,0 +1,104 @@
+# Pipeline Hardening Reference
+
+How `/dock` hardens the pipelines it generates. These patterns mirror
+mad-skills' own release workflow, translated from npm publishing to OCI
+containers. Hardened is the only mode for GitHub Actions and Azure Pipelines.
+
+## OIDC Registry Auth
+
+Never store long-lived cloud registry credentials in CI. Authenticate with the
+CI provider's OIDC identity, federated to a cloud role/identity.
+
+- **GHCR** — keep the ephemeral `GITHUB_TOKEN` (already short-lived, OIDC-backed).
+  Requires `permissions: packages: write`.
+- **AWS ECR** — `aws-actions/configure-aws-credentials@v4` with `role-to-assume`
+  (an IAM role trusting the GitHub OIDC provider). No access keys.
+- **Azure ACR** — `azure/login@v2` with Workload Identity Federation
+  (`client-id` + `tenant-id` + `subscription-id`, federated credential scoped to
+  the repo). No client secret. Then `az acr login`.
+- **Google Artifact Registry** — `google-github-actions/auth@v2` with a Workload
+  Identity Provider + service account. No SA key JSON.
+
+All jobs that need OIDC set `permissions: id-token: write` (plus
+`contents: read`). Azure Pipelines uses a **Workload Identity Federation service
+connection** (`azureSubscription:`) instead of a stored password.
+
+## Signing & Provenance
+
+- Build with `provenance: true` and `sbom: true` (buildx emits SLSA provenance +
+  SBOM attestations attached to the image).
+- Sign the image **by digest** with keyless cosign (Fulcio certificate + Rekor
+  transparency log, authorized by the `id-token: write` OIDC token — no signing
+  key in secrets).
+- Every promotion job runs `cosign verify` against the digest, asserting the
+  certificate identity matches the workflow's OIDC issuer and
+  `repo:OWNER/REPO`. Verification failure blocks promotion.
+
+> **Private-infra note:** keyless cosign writes to the public Rekor log. Orgs
+> that cannot use public transparency infra can switch to a key pair
+> (`cosign generate-key-pair`, private key in a CI secret,
+> `cosign sign --key`). This is a documented fallback — dock does not generate it.
+
+## Idempotency Guards
+
+- Before build, guard with `crane manifest <ref>` (fallback:
+  `docker manifest inspect`). If the artifact already exists, skip build+push and
+  reuse the existing digest — the container analog of mad-skills' `npm view`
+  publish-guard.
+- Promote/retag steps are check-then-act and tolerate an already-promoted digest
+  ("recovery mode") so a re-run exits cleanly instead of failing.
+- A `concurrency:` group keyed on workflow + ref (`cancel-in-progress`) prevents
+  overlapping release runs from racing.
+
+## Digest-Pinned Promotion
+
+- The build job outputs `IMAGE@sha256:<digest>` as a job output.
+- Dev, staging, and prod deploy by that **digest**, never a mutable tag. Tags
+  like `latest` / `vX.Y.Z` may be attached for humans, but deploys resolve the
+  digest.
+- `deploy/environments.yml` records the deployed digest so the matrix captures
+  exactly what shipped.
+
+## Generated deploy/SETUP.md
+
+`/dock` writes `deploy/SETUP.md` into the target repo, tailored to the chosen
+registry. Template body (substitute `OWNER/REPO`, registry, cloud identifiers):
+
+```markdown
+# Deployment Setup — Required Before First Run
+
+This pipeline uses keyless OIDC and image signing. Complete the cloud-side
+trust below once; no long-lived credentials are stored in CI.
+
+## 1. Federated identity (pick your registry)
+
+### AWS ECR
+- Create an IAM role trusting the GitHub OIDC provider
+  (`token.actions.githubusercontent.com`), condition
+  `token.actions.githubusercontent.com:sub = repo:OWNER/REPO:ref:refs/heads/main`
+  (add tag refs for releases).
+- Attach a policy allowing `ecr:*` push to your repository.
+- Put the role ARN in the workflow `role-to-assume`.
+
+### Azure ACR
+- Register an app / user-assigned managed identity.
+- Add a **federated credential** scoped to `repo:OWNER/REPO` (branch `main` and
+  tag refs), subject `repo:OWNER/REPO:ref:refs/heads/main`.
+- Grant it `AcrPush` on the registry.
+- Set `client-id` / `tenant-id` / `subscription-id` in the workflow.
+
+### Google Artifact Registry
+- Create a Workload Identity Pool + provider for GitHub.
+- Bind a service account with `artifactregistry.writer`, allowing
+  `principalSet://…/attribute.repository/OWNER/REPO`.
+- Set `workload_identity_provider` + `service_account` in the workflow.
+
+## 2. Signing
+
+Keyless cosign needs no setup — it uses the workflow OIDC token and the public
+Rekor log. To verify locally:
+`cosign verify --certificate-identity-regexp 'https://github.com/OWNER/REPO/.*' --certificate-oidc-issuer https://token.actions.githubusercontent.com REGISTRY/IMAGE@sha256:...`
+
+If public transparency logging is not allowed, switch to a key pair (see the
+Signing & Provenance note in the dock hardening reference).
+```