@slamb2k/mad-skills 2.0.51 → 2.0.55

package/.claude-plugin/plugin.json

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

package/hooks/lib/banner.cjs

@@ -2,28 +2,61 @@
 
 const config = require('./config.cjs');
 
+// Unicode banner (Delta Corps Priest 1) — used when the terminal supports UTF-8.
 // prettier-ignore
-const BANNER_LINES = [
-  '::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::',
-  ":::::'##::::'##::::'###::::'########::::::'######::'##:::'##:'####:'##:::::::'##::::::::'######::::::::",
-  "::::: ###::'###:::'## ##::: ##.... ##::::'##... ##: ##::'##::. ##:: ##::::::: ##:::::::'##... ##:::::::",
-  "::::: ####'####::'##:. ##:: ##:::: ##:::: ##:::..:: ##:'##:::: ##:: ##::::::: ##::::::: ##:::..::::::::",
-  "::::: ## ### ##:'##:::. ##: ##:::: ##::::. ######:: #####::::: ##:: ##::::::: ##:::::::. ######::::::::",
-  "::::: ##. #: ##: #########: ##:::: ##:::::..... ##: ##. ##:::: ##:: ##::::::: ##::::::::..... ##:::::::",
-  "::::: ##:.:: ##: ##.... ##: ##:::: ##::::'##::: ##: ##:. ##::: ##:: ##::::::: ##:::::::'##::: ##:::::::",
-  "::::: ##:::: ##: ##:::: ##: ########:::::. ######:: ##::. ##:'####: ########: ########:. ######::::::::",
-  "::::::..:::::..::..:::::..::........:::::::......:::..::::..::....::........::........:::......:::::::::",
+const BANNER_UNICODE = [
+  "  ▄▄▄▄███▄▄▄▄      ▄████████ ████████▄",
+  "▄██▀▀▀███▀▀▀██▄   ███    ███ ███   ▀███",
+  "███   ███   ███   ███    ███ ███    ███",
+  "███   ███   ███   ███    ███ ███    ███",
+  "███   ███   ███ ▀███████████ ███    ███",
+  "███   ███   ███   ███    ███ ███    ███",
+  "███   ███   ███   ███    ███ ███   ▄███",
+  " ▀█   ███   █▀    ███    █▀  ████████▀",
+  "",
+  "   ▄████████    ▄█   ▄█▄  ▄█   ▄█        ▄█          ▄████████",
+  "  ███    ███   ███ ▄███▀ ███  ███       ███         ███    ███",
+  "  ███    █▀    ███▐██▀   ███▌ ███       ███         ███    █▀",
+  "  ███         ▄█████▀    ███▌ ███       ███         ███",
+  "▀███████████ ▀▀█████▄    ███▌ ███       ███       ▀███████████",
+  "         ███   ███▐██▄   ███  ███       ███                ███",
+  "   ▄█    ███   ███ ▀███▄ ███  ███▌    ▄ ███▌    ▄    ▄█    ███",
+  " ▄████████▀    ███   ▀█▀ █▀   █████▄▄██ █████▄▄██  ▄████████▀",
+  "               ▀              ▀         ▀",
 ];
 
-const SEPARATOR = '\u2500'.repeat(70);
+// ASCII fallback (Rowan Cap) — used when the terminal locale is not UTF-8.
+// prettier-ignore
+const BANNER_ASCII = [
+  "    dMMMMMMMMb  .aMMMb  dMMMMb",
+  "   dMP\"dMP\"dMP dMP\"dMP dMP VMP",
+  "  dMP dMP dMP dMMMMMP dMP dMP",
+  " dMP dMP dMP dMP dMP dMP.aMP",
+  "dMP dMP dMP dMP dMP dMMMMP\"",
+  "",
+  "   .dMMMb  dMP dMP dMP dMP     dMP    .dMMMb",
+  "  dMP\" VP dMP.dMP amr dMP     dMP    dMP\" VP",
+  "  VMMMb  dMMMMK\" dMP dMP     dMP     VMMMb",
+  "dP .dMP dMP\"AMF dMP dMP     dMP    dP .dMP",
+  "VMMMP\" dMP dMP dMP dMMMMMP dMMMMMP VMMMP\"",
+];
+
+// True when the terminal locale advertises UTF-8, so box-drawing glyphs render.
+function supportsUnicode() {
+  const locale = process.env.LC_ALL || process.env.LC_CTYPE || process.env.LANG || '';
+  return /utf-?8/i.test(locale);
+}
 
 function getBanner() {
+  const unicode = supportsUnicode();
+  const lines = unicode ? BANNER_UNICODE : BANNER_ASCII;
+  const separator = (unicode ? '─' : '-').repeat(70);
   return [
-    ...BANNER_LINES,
-    SEPARATOR,
+    ...lines,
+    separator,
     ` Session Guard v${config.version}`,
-    SEPARATOR,
+    separator,
   ].join('\n');
 }
 
-module.exports = { getBanner, BANNER_MARKER: '::::::::::::::::::::' };
+module.exports = { getBanner, supportsUnicode, BANNER_MARKER: 'Session Guard' };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slamb2k/mad-skills",
-  "version": "2.0.51",
+  "version": "2.0.55",
   "description": "Claude Code skills collection — full lifecycle development tools",
   "type": "module",
   "repository": {
@@ -11,6 +11,8 @@
     "skills/",
     "agents/",
     "hooks/",
+    "scripts/lib/",
+    "references/",
     ".claude-plugin/"
   ],
   "scripts": {
@@ -22,7 +24,8 @@
     "build:skills": "node scripts/package-skills.js",
     "build": "npm run build:manifests && npm run build:skills",
     "prepublishOnly": "npm run validate && npm run build:manifests",
-    "test": "npm run validate && npm run lint && npm run eval"
+    "test:unit": "node --test scripts/lib/superpowers.test.js",
+    "test": "npm run validate && npm run lint && npm run test:unit && npm run eval"
   },
   "keywords": [
     "claude",

package/references/azdo-cli-reference.md

@@ -0,0 +1,342 @@
+# Azure DevOps CLI Reference for Claude Code
+
+This document provides guidance for LLM agents constructing Azure DevOps CLI
+commands. It addresses common pitfalls, inconsistent flag support across
+subcommands, and REST API authentication patterns.
+
+## Critical: `--project` Flag Is NOT Universal
+
+The `--project` flag is **only supported by some `az devops` subcommands**.
+Using it where it is not supported produces `ERROR: unrecognized arguments`.
+
+### Commands that accept `--project`
+
+| Command | `--project` | Notes |
+|---------|------------|-------|
+| `az repos pr create` | YES | Required if not configured via defaults |
+| `az repos pr list` | YES | Filters by project |
+| `az pipelines list` | YES | |
+| `az pipelines runs list` | YES | |
+| `az pipelines run` | YES | Queue a new run |
+| `az repos policy list` | YES | |
+
+### Commands that DO NOT accept `--project`
+
+| Command | `--project` | Use instead |
+|---------|------------|------------|
+| `az repos pr update` | NO | `--org` only, or configure defaults |
+| `az repos pr show` | NO | `--org` only, or configure defaults |
+| `az devops invoke` | NO | Pass project in `--route-parameters` |
+
+### Safe pattern
+
+Always configure defaults at the start of a session, then omit `--project`
+from commands that don't support it:
+
+```bash
+az devops configure --defaults \
+  organization="$AZDO_ORG_URL" \
+  project="$AZDO_PROJECT"
+```
+
+After this, commands that support `--project` will use the default, and
+commands that don't (like `pr update` and `pr show`) will detect the project
+from the `--org` URL or the PR ID.
+
+For `az devops invoke`, pass the project via route parameters:
+
+```bash
+az devops invoke \
+  --area build --resource timeline \
+  --route-parameters buildId=12345 project="$AZDO_PROJECT" \
+  --org "$AZDO_ORG_URL" -o json
+```
+
+---
+
+## PR Merge Pattern
+
+The correct command to squash-merge a PR:
+
+```bash
+az repos pr update \
+  --id "$PR_NUMBER" \
+  --status completed \
+  --squash true \
+  --delete-source-branch true \
+  --merge-commit-message "commit message here" \
+  --org "$AZDO_ORG_URL"
+```
+
+If the PR has branch policies that haven't been satisfied (e.g., no CI checks
+registered, no required reviewers), add:
+
+```bash
+  --bypass-policy true \
+  --bypass-policy-reason "Reason for bypass"
+```
+
+**Important:** After calling `pr update --status completed`, the merge may be
+asynchronous. Poll with:
+
+```bash
+az repos pr show --id "$PR_NUMBER" --query status -o tsv --org "$AZDO_ORG_URL"
+```
+
+Expected result: `completed`. If still `active`, wait 5-10 seconds and retry.
+
+---
+
+## CI Pipeline Monitoring
+
+### Branch name mismatch
+
+Azure DevOps PR builds have `sourceBranch` set to `refs/pull/<N>/merge`, NOT
+the feature branch name. When listing runs for a PR:
+
+```bash
+# WRONG — will return no results
+az pipelines runs list --branch "feat/my-feature" ...
+
+# CORRECT — match the PR merge ref
+az pipelines runs list --branch "refs/pull/$PR_NUMBER/merge" \
+  --org "$AZDO_ORG_URL" --project "$AZDO_PROJECT" \
+  --top 1 -o json
+```
+
+Alternatively, list without branch filter and filter in `jq`:
+
+```bash
+az pipelines runs list --top 10 \
+  --org "$AZDO_ORG_URL" --project "$AZDO_PROJECT" -o json \
+  | jq "[.[] | select(.sourceBranch == \"refs/pull/$PR_NUMBER/merge\")]"
+```
+
+### Polling for completion
+
+```bash
+RESULT=$(az pipelines runs show --id "$RUN_ID" \
+  --org "$AZDO_ORG_URL" --project "$AZDO_PROJECT" \
+  --query result -o tsv)
+
+# RESULT is one of: succeeded, failed, canceled, (empty if still running)
+```
+
+### Getting failed job details
+
+Use the timeline API to find which jobs/steps failed:
+
+```bash
+az devops invoke \
+  --area build --resource timeline \
+  --route-parameters buildId="$RUN_ID" project="$AZDO_PROJECT" \
+  --org "$AZDO_ORG_URL" -o json \
+  | jq '[.records[] | select(.result=="failed") | {name, type}]'
+```
+
+To get log output from a failed step, extract the log URL from the timeline
+record and fetch it with `curl` using PAT auth (see REST API section below).
+
+---
+
+## URL Formats and Org Detection
+
+Azure DevOps has two URL formats. Both are valid, but REST API calls via
+`curl` may only work with one depending on org configuration.
+
+| Format | Example |
+|--------|---------|
+| Modern | `https://dev.azure.com/{ORG}/{PROJECT}/_git/{REPO}` |
+| Legacy | `https://{ORG}.visualstudio.com/{PROJECT}/_git/{REPO}` |
+| SSH | `{ORG}@vs-ssh.visualstudio.com:v3/{ORG}/{PROJECT}/{REPO}` |
+
+### Preserve the original URL format
+
+When the remote uses `visualstudio.com`, keep that format for REST API calls.
+Do NOT normalize to `dev.azure.com` — some legacy organizations only respond
+to the original domain.
+
+```bash
+REMOTE_URL=$(git remote get-url origin 2>/dev/null)
+
+if echo "$REMOTE_URL" | grep -q 'dev\.azure\.com'; then
+  AZDO_ORG=$(echo "$REMOTE_URL" | sed -n 's|.*dev\.azure\.com/\([^/]*\)/.*|\1|p')
+  AZDO_ORG_URL="https://dev.azure.com/$AZDO_ORG"
+elif echo "$REMOTE_URL" | grep -q 'visualstudio\.com'; then
+  AZDO_ORG=$(echo "$REMOTE_URL" | sed -n 's|.*//\([^.]*\)\.visualstudio\.com.*|\1|p')
+  # Keep the original domain for REST API compatibility
+  AZDO_ORG_URL="https://${AZDO_ORG}.visualstudio.com"
+fi
+```
+
+### URL-decoding project names
+
+Project names with spaces are URL-encoded in remote URLs (e.g.,
+`Velrada%20AI%20Agents`). The common `printf '%b'` approach fails when
+`%20` is followed by hex characters (A-F, 0-9):
+
+```bash
+# BROKEN — fails on "Velrada%20AI%20Agents" (interprets %20A as \x20A)
+AZDO_PROJECT=$(printf '%b' "${AZDO_PROJECT//%/\\x}")
+
+# CORRECT — use Python for reliable URL decoding
+AZDO_PROJECT=$(python3 -c "import urllib.parse; print(urllib.parse.unquote('$AZDO_PROJECT_URL_SAFE'))")
+```
+
+Keep both the URL-safe and decoded versions:
+
+```bash
+AZDO_PROJECT_URL_SAFE="Velrada%20AI%20Agents"  # for REST API URL paths
+AZDO_PROJECT="Velrada AI Agents"                # for CLI --project flags
+```
+
+---
+
+## REST API via `curl`
+
+### Authentication
+
+Use the `AZURE_DEVOPS_EXT_PAT` environment variable (this is the standard env
+var that `az devops login` also reads):
+
+```bash
+TOKEN=$(printf ":%s" "$AZURE_DEVOPS_EXT_PAT" | base64 -w0)
+AUTH="Authorization: Basic $TOKEN"
+```
+
+### DO NOT use `az rest` for Azure DevOps
+
+`az rest` is designed for Azure Resource Manager (ARM) APIs. It cannot
+automatically derive the correct Azure AD resource for Azure DevOps endpoints.
+Even with `--resource "499b84ac-1321-427f-aa17-267ca6975798"` (the Azure DevOps
+resource ID), it often fails for legacy organizations.
+
+**Always use `curl` with PAT-based Basic auth for Azure DevOps REST APIs.**
+
+### Common REST API patterns
+
+```bash
+# Build timeline (get failed steps)
+curl -s -H "$AUTH" \
+  "${AZDO_ORG_URL}/${AZDO_PROJECT_URL_SAFE}/_apis/build/builds/${BUILD_ID}/timeline?api-version=7.1"
+
+# Build logs (get log content for a specific log ID)
+curl -s -H "$AUTH" \
+  "${AZDO_ORG_URL}/${AZDO_PROJECT_URL_SAFE}/_apis/build/builds/${BUILD_ID}/logs/${LOG_ID}?api-version=7.1"
+
+# PR details
+curl -s -H "$AUTH" \
+  "${AZDO_ORG_URL}/${AZDO_PROJECT_URL_SAFE}/_apis/git/repositories/${REPO_NAME}/pullRequests/${PR_NUMBER}?api-version=7.1"
+
+# Complete a PR (REST fallback)
+curl -s -X PATCH -H "$AUTH" -H "Content-Type: application/json" \
+  "${AZDO_ORG_URL}/${AZDO_PROJECT_URL_SAFE}/_apis/git/repositories/${REPO_NAME}/pullRequests/${PR_NUMBER}?api-version=7.1" \
+  -d '{
+    "status": "completed",
+    "completionOptions": {
+      "squashMerge": true,
+      "deleteSourceBranch": true,
+      "mergeCommitMessage": "commit message"
+    }
+  }'
+```
+
+---
+
+## JSON Safety: Validate Before Piping to `jq`
+
+Azure CLI commands can output warnings, error messages, or HTML instead of
+JSON. Always validate before piping:
+
+```bash
+# Pattern 1: Capture output, validate, then parse
+OUTPUT=$(az pipelines runs show --id "$RUN_ID" --org "$AZDO_ORG_URL" -o json 2>&1)
+if echo "$OUTPUT" | jq empty 2>/dev/null; then
+  echo "$OUTPUT" | jq '.result'
+else
+  echo "ERROR: Non-JSON response: $OUTPUT" >&2
+fi
+
+# Pattern 2: Use --output json and redirect stderr
+RESULT=$(az repos pr show --id "$PR_NUMBER" --query status -o tsv 2>/dev/null)
+
+# Pattern 3: For curl, check HTTP status
+HTTP_CODE=$(curl -s -o /tmp/response.json -w "%{http_code}" -H "$AUTH" "$URL")
+if [ "$HTTP_CODE" = "200" ]; then
+  jq '.' /tmp/response.json
+else
+  echo "ERROR: HTTP $HTTP_CODE" >&2
+fi
+```
+
+**Never swallow stderr with `2>/dev/null` on commands that might fail.**
+Capture stderr to a variable instead:
+
+```bash
+OUTPUT=$(az repos pr update --id "$PR_NUMBER" --status completed 2>&1)
+EXIT_CODE=$?
+if [ $EXIT_CODE -ne 0 ]; then
+  echo "MERGE FAILED: $OUTPUT" >&2
+fi
+```
+
+---
+
+## Quick Reference: Common Operations
+
+### Create PR
+
+```bash
+az repos pr create \
+  --title "feat: description" \
+  --description "## Summary ..." \
+  --source-branch "$BRANCH" \
+  --target-branch main \
+  --org "$AZDO_ORG_URL" \
+  --project "$AZDO_PROJECT" \
+  --output json
+```
+
+### List runs for a PR
+
+```bash
+az pipelines runs list \
+  --branch "refs/pull/$PR_NUMBER/merge" \
+  --top 1 \
+  --org "$AZDO_ORG_URL" \
+  --project "$AZDO_PROJECT" \
+  -o json
+```
+
+### Queue a pipeline run
+
+```bash
+az pipelines run \
+  --id "$PIPELINE_ID" \
+  --branch "$BRANCH" \
+  --org "$AZDO_ORG_URL" \
+  --project "$AZDO_PROJECT" \
+  -o json
+```
+
+### Complete (merge) a PR
+
+```bash
+az repos pr update \
+  --id "$PR_NUMBER" \
+  --status completed \
+  --squash true \
+  --delete-source-branch true \
+  --merge-commit-message "message" \
+  --org "$AZDO_ORG_URL"
+```
+
+### Check PR status
+
+```bash
+az repos pr show \
+  --id "$PR_NUMBER" \
+  --query status \
+  -o tsv \
+  --org "$AZDO_ORG_URL"
+```

package/references/azdo-platform.md

@@ -0,0 +1,88 @@
+# Azure DevOps Platform Support
+
+Shared procedures for AzDO tooling detection and configuration validation.
+Referenced by SKILL.md during pre-flight when `PLATFORM == azdo`.
+
+## AzDO Tooling Detection
+
+When `PLATFORM == azdo`, determine which tooling is available. Set `AZDO_MODE`
+for use in all subsequent phases:
+
+```bash
+if az devops -h &>/dev/null; then
+  AZDO_MODE="cli"
+else
+  AZDO_MODE="rest"
+fi
+```
+
+- **`cli`**: Use `az repos` / `az pipelines` commands (preferred)
+- **`rest`**: Use Azure DevOps REST API via `curl`. Requires a PAT (personal
+  access token) in `AZURE_DEVOPS_EXT_PAT` or `AZDO_PAT` env var. If no PAT
+  is found, prompt the user to either install the CLI or set the env var.
+
+Report in pre-flight:
+- ✅ `az devops cli` — version found
+- ⚠️ `az devops cli` — not found → using REST API fallback
+- ❌ `az devops cli` — not found, no PAT configured → halt with setup instructions
+
+## AzDO Configuration Validation
+
+When `PLATFORM == azdo`, extract organization and project from the remote URL
+and validate they are usable. These values are needed by every `az repos` /
+`az pipelines` command and every REST API call.
+
+```bash
+# Extract org and project from remote URL patterns:
+#   https://dev.azure.com/{ORG}/{PROJECT}/_git/{REPO}
+#   https://{ORG}@dev.azure.com/{ORG}/{PROJECT}/_git/{REPO}
+#   {ORG}@vs-ssh.visualstudio.com:v3/{ORG}/{PROJECT}/{REPO}
+
+REMOTE_URL=$(git remote get-url origin 2>/dev/null)
+
+if echo "$REMOTE_URL" | grep -q 'dev\.azure\.com'; then
+  AZDO_ORG=$(echo "$REMOTE_URL" | sed -n 's|.*dev\.azure\.com/\([^/]*\)/.*|\1|p')
+  AZDO_PROJECT=$(echo "$REMOTE_URL" | sed -n 's|.*dev\.azure\.com/[^/]*/\([^/]*\)/.*|\1|p')
+  AZDO_ORG_URL="https://dev.azure.com/$AZDO_ORG"
+elif echo "$REMOTE_URL" | grep -q 'vs-ssh\.visualstudio\.com'; then
+  AZDO_ORG=$(echo "$REMOTE_URL" | sed -n 's|.*vs-ssh\.visualstudio\.com:v3/\([^/]*\)/.*|\1|p')
+  AZDO_PROJECT=$(echo "$REMOTE_URL" | sed -n 's|.*vs-ssh\.visualstudio\.com:v3/[^/]*/\([^/]*\)/.*|\1|p')
+  AZDO_ORG_URL="https://dev.azure.com/$AZDO_ORG"
+elif echo "$REMOTE_URL" | grep -q 'visualstudio\.com'; then
+  AZDO_ORG=$(echo "$REMOTE_URL" | sed -n 's|.*//\([^.]*\)\.visualstudio\.com.*|\1|p')
+  AZDO_PROJECT=$(echo "$REMOTE_URL" | sed -n 's|.*/\([^/]*\)/_git/.*|\1|p')
+  # Preserve the original domain for REST API compatibility
+  AZDO_ORG_URL="https://${AZDO_ORG}.visualstudio.com"
+fi
+
+# URL-decode for CLI/display; keep URL-safe versions for REST API paths
+AZDO_PROJECT_URL_SAFE="$AZDO_PROJECT"
+AZDO_PROJECT=$(python3 -c "import urllib.parse; print(urllib.parse.unquote('$AZDO_PROJECT'))")
+
+if [ -z "$AZDO_ORG" ] || [ -z "$AZDO_PROJECT" ]; then
+  echo "❌ Could not extract organization/project from remote URL"
+  echo "   Remote: $REMOTE_URL"
+  echo ""
+  echo "Ensure the remote URL follows one of these formats:"
+  echo "  https://dev.azure.com/{ORG}/{PROJECT}/_git/{REPO}"
+  echo "  https://{ORG}.visualstudio.com/{PROJECT}/_git/{REPO}"
+  echo "  {ORG}@vs-ssh.visualstudio.com:v3/{ORG}/{PROJECT}/{REPO}"
+  # HALT — cannot proceed without org/project context
+fi
+```
+
+When `AZDO_MODE == cli`, also configure the defaults so commands work correctly:
+```bash
+az devops configure --defaults organization="$AZDO_ORG_URL" project="$AZDO_PROJECT"
+```
+
+When `AZDO_MODE == rest`, store these for API calls:
+- Base URL: `$AZDO_ORG_URL/$AZDO_PROJECT_URL_SAFE/_apis`
+- Auth header: `Authorization: Basic $(printf ":%s" "$PAT" | base64 | tr -d '\n')`
+
+Report in pre-flight:
+- ✅ `azdo context` — org: `{AZDO_ORG}`, project: `{AZDO_PROJECT}`
+- ❌ `azdo context` — could not parse from remote URL → halt with instructions
+
+Pass `{AZDO_MODE}`, `{AZDO_ORG}`, `{AZDO_PROJECT}`, `{AZDO_ORG_URL}` into
+all phase prompts alongside `{PLATFORM}`.

package/references/superpowers-deferral.md

@@ -0,0 +1,51 @@
+# Superpowers Deferral Contract
+
+Shared deferral behavior for `speccy`, `build`, and `ship`. Superpowers is a
+soft/recommended dependency (runtime-detected, like claude-mem) — never required.
+When it is absent, every skill runs its standalone pipeline unchanged.
+
+## Detection
+
+Detection is a bounded on-disk anchor check via `scripts/lib/superpowers.js`
+(anchor file: `using-superpowers/SKILL.md`). Run it from a SKILL.md pre-flight
+step with an ESM-safe dynamic import. `LIB` resolves to the plugin's
+`scripts/lib` directory using the same `CLAUDE_PLUGIN_ROOT` fallback the other
+skills use, so it works for plugin installs and degrades gracefully otherwise:
+
+```bash
+LIB="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/marketplaces/slamb2k}/scripts/lib"
+SP=$(node -e "import('$LIB/superpowers.js').then(m=>process.stdout.write(m.detectSuperpowers().installed?'1':'0')).catch(()=>process.stdout.write('0'))")
+```
+
+`SP` is `1` when Superpowers is detected, `0` otherwise. If the helper is not
+present at runtime (e.g. a single-skill install), the `.catch` yields `0` so the
+skill safely runs its standalone pipeline. Passing `--no-superpowers`
+short-circuits `SP` to `0` before this check runs.
+
+## Announcement format
+
+When deferring, print exactly one line (GUD-002):
+
+```
+⚡ Superpowers detected — deferring {stage} to superpowers:{skill}
+```
+
+## `--no-superpowers` flag
+
+Parsed alongside each skill's existing flags. Forces the standalone pipeline even
+when Superpowers is installed. Treat it as setting `SP=0` for the whole run.
+
+## Absent-fallback rule (REQ-007)
+
+When Superpowers is not installed (or `--no-superpowers` is set), the skill runs
+its current standalone pipeline with byte-for-byte identical user-facing output.
+No announcement is printed — the deferral logic is purely additive.
+
+## Per-skill deferral map
+
+| Skill / stage | Defers to (when present) | Retained by mad-skills |
+|---|---|---|
+| `speccy` requirements interview | `superpowers:brainstorming` | writes `specs/*.md` + pending-build marker |
+| `build` plan/implement core | `superpowers:executing-plans` / `superpowers:subagent-driven-development` | explore, 3× code-review, verify, ship gate |
+| `ship` final integration | `superpowers:finishing-a-development-branch` | sync, branch, commit, PR, CI-poll, auto-fix |
+| `prime` graphify awareness | — (hint only) | context summary |

package/scripts/lib/frontmatter.js

@@ -0,0 +1,33 @@
+/**
+ * Shared YAML frontmatter parser for SKILL.md files.
+ * Used by validate-skills.js and build-manifests.js.
+ */
+
+export function parseFrontmatter(content) {
+  // Normalise line endings (CRLF → LF) for cross-platform support
+  const normalised = content.replace(/\r\n/g, "\n");
+  const match = normalised.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+
+  const result = {};
+  let currentKey = null;
+  let currentValue = "";
+
+  for (const line of match[1].split("\n")) {
+    // Continuation line (indented)
+    if (currentKey && (line.startsWith("  ") || line.startsWith("\t"))) {
+      currentValue += " " + line.trim();
+      result[currentKey] = currentValue;
+      continue;
+    }
+
+    const colonIdx = line.indexOf(":");
+    if (colonIdx === -1) continue;
+
+    currentKey = line.slice(0, colonIdx).trim();
+    currentValue = line.slice(colonIdx + 1).trim();
+    result[currentKey] = currentValue;
+  }
+
+  return result;
+}

package/scripts/lib/superpowers.js

@@ -0,0 +1,61 @@
+/**
+ * Shared Superpowers detection helper.
+ * Soft-dependency, on-disk anchor check — used by speccy/build/ship pre-flight.
+ */
+
+import os from "node:os";
+import fs from "node:fs";
+import path from "node:path";
+
+const ANCHOR = "using-superpowers/SKILL.md";
+const MAX_DEPTH = 7;
+
+function anchorExists(dir) {
+  try {
+    return fs.existsSync(path.join(dir, ANCHOR));
+  } catch {
+    return false;
+  }
+}
+
+function findAnchorDir(root, depth = 0) {
+  if (depth > MAX_DEPTH) return null;
+
+  if (anchorExists(root)) return root;
+
+  let entries;
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const child = path.join(root, entry.name);
+    const hit = findAnchorDir(child, depth + 1);
+    if (hit) return hit;
+  }
+
+  return null;
+}
+
+export function detectSuperpowers({
+  homedir = os.homedir(),
+  cwd = process.cwd(),
+} = {}) {
+  const roots = [
+    path.join(homedir, ".claude", "plugins"),
+    path.join(homedir, ".claude", "skills", "superpowers"),
+    path.join(cwd, ".claude", "skills"),
+  ];
+
+  for (const root of roots) {
+    const hit = findAnchorDir(root);
+    if (hit) {
+      return { installed: true, basePath: hit };
+    }
+  }
+
+  return { installed: false, basePath: null };
+}

package/scripts/lib/superpowers.test.js

@@ -0,0 +1,76 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { detectSuperpowers } from "./superpowers.js";
+
+function mkTmp() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "sp-"));
+}
+
+function writeAnchor(dir, rel) {
+  const file = path.join(dir, rel);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, "# anchor\n");
+}
+
+test("installed: anchor under plugins cache", () => {
+  const tmp = mkTmp();
+  try {
+    writeAnchor(
+      tmp,
+      ".claude/plugins/somepkg/superpowers/skills/using-superpowers/SKILL.md",
+    );
+    const result = detectSuperpowers({ homedir: tmp, cwd: tmp });
+    assert.equal(result.installed, true);
+    assert.ok(result.basePath);
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test("not installed: empty tree", () => {
+  const tmp = mkTmp();
+  try {
+    const result = detectSuperpowers({ homedir: tmp, cwd: tmp });
+    assert.equal(result.installed, false);
+    assert.equal(result.basePath, null);
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test("partial install: anchor missing → not installed", () => {
+  const tmp = mkTmp();
+  try {
+    writeAnchor(
+      tmp,
+      ".claude/plugins/somepkg/superpowers/skills/writing-plans/SKILL.md",
+    );
+    const result = detectSuperpowers({ homedir: tmp, cwd: tmp });
+    assert.equal(result.installed, false);
+    assert.equal(result.basePath, null);
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test("project-local: anchor under cwd .claude/skills", () => {
+  const tmp = mkTmp();
+  try {
+    writeAnchor(
+      tmp,
+      ".claude/skills/superpowers-foo/using-superpowers/SKILL.md",
+    );
+    const result = detectSuperpowers({
+      homedir: path.join(tmp, "nohome"),
+      cwd: tmp,
+    });
+    assert.equal(result.installed, true);
+    assert.ok(result.basePath);
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});

package/skills/brace/SKILL.md

@@ -87,6 +87,7 @@ Before starting, check all dependencies in this table:
 |-----------|------|-------|----------|------------|--------|
 | claude-mem | plugin | — | no | ask | `claude plugin install claude-mem` |
 | oh-my-claudecode | plugin | — | no | ask | `claude plugin install oh-my-claudecode` |
+| superpowers | plugin | on-disk glob via scripts/lib/superpowers.js | no | ask | `claude plugin install superpowers` |
 
 For each row, in order:
 1. Run the Check command (for cli/npm) or test file existence (for agent/skill)
@@ -104,6 +105,11 @@ For each row, in order:
 name set to `true`. Store results as `PLUGIN_STATE` (`claude_mem_installed`,
 `omc_installed`) for use in Phase 4 and Phase 7.
 
+**Superpowers detection differs:** Superpowers is a soft dependency detected via
+the on-disk glob helper `scripts/lib/superpowers.js` (anchor file
+`using-superpowers/SKILL.md`), **not** the `enabledPlugins` settings.json check
+used for claude-mem and OMC — see `references/superpowers-deferral.md`.
+
 1. Capture **FLAGS** from the user's request
 
 ---

package/skills/brace/references/claude-md-template.md

@@ -53,6 +53,16 @@ MCP tools for search, timeline, and observation management. Claude Code's
 built-in auto memory (`~/.claude/projects/<project>/memory/MEMORY.md`)
 handles curated facts.
 
+For the methodology layer (plan → build → finish), install the **superpowers**
+plugin:
+```
+claude plugin install superpowers
+```
+
+mad-skills defers its overlapping `/speccy`, `/build`, and `/ship` stages to
+superpowers when it is present, and falls back to its own standalone pipeline
+when it is absent.
+
 {PLUGIN_ROLE_SEPARATION}
 
 {UNIVERSAL_PRINCIPLES}

package/skills/build/SKILL.md

@@ -75,6 +75,7 @@ Parse optional flags from the request:
 - `--skip-review`: Skip Stage 5 (code review)
 - `--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
 
 ---
 
@@ -89,6 +90,7 @@ Before starting, check all dependencies in this table:
 | feature-dev:code-explorer | agent | — | no | fallback | Uses general-purpose agent |
 | 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 |
 
 For each row, in order:
 1. Run the Check command (for cli/npm) or test file existence (for agent/skill)
@@ -241,6 +243,16 @@ If rejected, incorporate feedback and re-run.
 
 ## Stage 4: Implementation
 
+**Superpowers deferral (soft dependency):** When Superpowers is detected (per the
+pre-flight check) and `--no-superpowers` is not set, announce
+`⚡ Superpowers detected — deferring plan/implement core to superpowers:executing-plans`
+and route the plan-execution/implementation core through
+`superpowers:executing-plans` / `superpowers:subagent-driven-development` instead
+of the general-purpose subagents below. Stage 1 (explore), Stage 5 (3× review),
+and Stage 7 (verify) remain unchanged either way. When Superpowers is absent or
+`--no-superpowers` is set, run the standalone implementation below unchanged.
+See `references/superpowers-deferral.md`.
+
 If ARCH_REPORT identifies independent `parallel_groups`, launch **multiple
 general-purpose subagents in parallel** — one per group. Do NOT wait for
 `--parallel-impl` flag; parallel execution is the **default** when the

package/skills/build/tests/evals.json

@@ -32,5 +32,21 @@
       { "type": "contains", "value": "██" },
       { "type": "semantic", "value": "Acknowledges the --skip-questions flag (skipping clarifying questions) and the --no-ship flag (stopping before committing/pushing/creating PR)" }
     ]
+  },
+  {
+    "name": "build-superpowers-present",
+    "prompt": "The superpowers plugin is installed. Run build on specs/rate-limiter.md. Which superpowers skill does build route its implementation core through?",
+    "assertions": [
+      { "type": "regex", "value": "(executing-plans|subagent-driven-development)", "flags": "i" },
+      { "type": "contains", "value": "Superpowers detected" }
+    ]
+  },
+  {
+    "name": "build-superpowers-absent",
+    "prompt": "Superpowers is NOT installed. How does build implement a plan?",
+    "assertions": [
+      { "type": "regex", "value": "(explore|architect|implement|review)", "flags": "i" },
+      { "type": "semantic", "value": "Runs the standalone feature-dev pipeline (explore, architect, implement, review, verify) using its own subagents, with no deferral to superpowers" }
+    ]
   }
 ]

package/skills/manifest.json

@@ -1,12 +1,12 @@
 {
-  "generated": "2026-04-20T03:16:08.071Z",
+  "generated": "2026-07-06T02:10:36.483Z",
   "count": 11,
   "skills": [
     {
       "name": "brace",
       "directory": "brace",
       "description": "'Initialize any project directory with a standard scaffold for AI-assisted development. Creates specs/ and context/ directories, a project CLAUDE.md with development workflow and guardrails, .gitignore, and branch protection. Recommends claude-mem for persistent memory. Idempotent — safe to run on existing projects. Triggers: \"init project\", \"setup brace\", \"brace\", \"initialize\", \"bootstrap\", \"scaffold\".'",
-      "lines": 430,
+      "lines": 436,
       "hasScripts": false,
       "hasReferences": true,
       "hasAssets": true,
@@ -16,7 +16,7 @@
       "name": "build",
       "directory": "build",
       "description": "Context-isolated feature development pipeline. Takes a detailed design/plan as argument and executes the full feature-dev lifecycle (explore, question, architect, implement, review, ship) inside subagents so the primary conversation stays compact. Use when you have a well-defined plan and want autonomous execution with minimal context window consumption.",
-      "lines": 456,
+      "lines": 468,
       "hasScripts": false,
       "hasReferences": true,
       "hasAssets": false,
@@ -66,7 +66,7 @@
       "name": "prime",
       "directory": "prime",
       "description": "\"Load project context before implementing features or making architectural decisions. Invoke proactively at the start of significant work on any project. Scans CLAUDE.md, README, specs/, docs/, and source structure to build a context summary. Supports optional domain hints to focus on specific areas of the codebase. Use when you need project conventions, architecture understanding, or domain context before coding.\"",
-      "lines": 148,
+      "lines": 165,
       "hasScripts": false,
       "hasReferences": true,
       "hasAssets": false,
@@ -86,7 +86,7 @@
       "name": "ship",
       "directory": "ship",
       "description": "\"Ship changes through the full PR lifecycle. Use after completing feature work to commit, push, create PR, wait for checks, and merge. Handles the entire workflow: syncs with main, creates feature branch if needed, groups commits logically with semantic messages, creates detailed PR, monitors CI, fixes issues, squash merges, and cleans up. Invoke when work is ready to ship.\"",
-      "lines": 495,
+      "lines": 499,
       "hasScripts": true,
       "hasReferences": true,
       "hasAssets": false,
@@ -96,7 +96,7 @@
       "name": "speccy",
       "directory": "speccy",
       "description": "Deep-dive interview skill for creating comprehensive specifications. Reviews existing code and docs, then interviews the user through multiple rounds of targeted questions covering technical implementation, UI/UX, concerns, and tradeoffs. Produces a structured spec in specs/. Use when starting a new feature, system, or major change that needs a spec.",
-      "lines": 260,
+      "lines": 275,
       "hasScripts": false,
       "hasReferences": true,
       "hasAssets": false,

package/skills/prime/SKILL.md

@@ -108,6 +108,13 @@ For each file:
 - If it exists: read and summarise (2-3 lines max per domain)
 - If it doesn't exist: record as NOT FOUND and continue
 
+## Graphify Awareness (existence check only)
+
+Check whether a `graphify-out/` directory exists at the project root
+(existence only — do NOT run any graphify query, read its contents, or treat
+it as a dependency). Record the boolean in the report. This is purely additive:
+when absent, the report is unchanged.
+
 ## Output Format
 
 PRIME_REPORT:
@@ -117,6 +124,7 @@ PRIME_REPORT:
 - per_domain_summary:
   - {domain}: {2-3 line summary}
 - branch: {current branch from git branch --show-current}
+- graphify_out_present: {true|false}
 - ready_for: {inferred from loaded context}
 ```
 
@@ -143,5 +151,14 @@ Parse PRIME_REPORT and present a clean summary to the user:
 └─────────────────────────────────────────────────
 ```
 
+If `graphify_out_present` is true, add a single passive line after the report
+box (omit entirely when false):
+
+```
+graphify-out/ detected — codebase questions can be answered via /graphify
+```
+
+This is a hint only — never execute a graphify query on the user's behalf.
+
 If CLAUDE.md was missing, warn the user and note that only domain context
 was loaded.

package/skills/prime/tests/evals.json

@@ -24,5 +24,14 @@
       { "type": "contains", "value": "██" },
       { "type": "semantic", "value": "Recognizes 'dashboard' and 'routing' as valid domain-specific contexts and describes loading files relevant to those domains" }
     ]
+  },
+  {
+    "name": "prime-graphify-hint",
+    "prompt": "Prime me for this project. The repository root contains a graphify-out/ directory alongside CLAUDE.md and specs/.",
+    "assertions": [
+      { "type": "contains", "value": "██" },
+      { "type": "contains", "value": "/graphify" },
+      { "type": "semantic", "value": "Detects the graphify-out/ directory by existence only and surfaces a passive hint that codebase questions can be answered via /graphify, without running any graphify query" }
+    ]
   }
 ]

package/skills/ship/SKILL.md

@@ -70,6 +70,7 @@ Parse optional flags from the request:
 - `--pr-only`: Stop after creating the PR
 - `--no-squash`: Use regular merge instead of squash
 - `--keep-branch`: Don't delete the source branch after merge
+- `--no-superpowers`: Force standalone merge even when Superpowers is installed
 
 ---
 
@@ -113,6 +114,7 @@ Before starting, check all dependencies in this table. The table contains
 | git | cli | `git --version` | yes | stop | Install from https://git-scm.com |
 | gh | cli | `gh --version` | yes | url | https://cli.github.com |
 | az devops | cli | `az devops -h 2>/dev/null` | no | fallback | Falls back to REST API with PAT; see AzDO tooling below |
+| superpowers | plugin | on-disk glob via scripts/lib/superpowers.js | no | fallback | Replaces final merge with superpowers:finishing-a-development-branch when present; see references/superpowers-deferral.md |
 
 **Platform-conditional rules:**
 - **`gh`**: Only required when `PLATFORM == github`. Skip for AzDO repos.
@@ -374,6 +376,8 @@ defaults (override via `--no-squash` and `--keep-branch` flags only).
 
 ### 5a. Merge the PR
 
+**Superpowers deferral:** When Superpowers is detected and `--no-superpowers` is not set, after CI is green and auto-fix, announce `⚡ Superpowers detected — deferring final integration to superpowers:finishing-a-development-branch` and invoke that skill to present merge/PR/cleanup options instead of calling merge.sh directly (CI-poll + auto-fix and the no-manual-CI-trigger rule still apply); otherwise run merge.sh below.
+
 Run the merge script directly (no LLM needed):
 
 ```bash

package/skills/ship/tests/evals.json

@@ -26,5 +26,21 @@
       { "type": "regex", "value": "(script|sync\\.sh|ci-watch\\.sh|merge\\.sh|general.purpose)", "flags": "i" },
       { "type": "semantic", "value": "Uses deterministic scripts for sync, CI monitoring, and merge stages, with LLM subagents only for commit/PR authoring and CI fix analysis" }
     ]
+  },
+  {
+    "name": "ship-superpowers-present",
+    "prompt": "The superpowers plugin is installed. Run ship. Once CI is green, which superpowers skill handles the final integration instead of an auto squash-merge?",
+    "assertions": [
+      { "type": "contains", "value": "finishing-a-development-branch" },
+      { "type": "contains", "value": "Superpowers detected" }
+    ]
+  },
+  {
+    "name": "ship-superpowers-absent",
+    "prompt": "Superpowers is NOT installed. How does ship merge the PR after CI passes?",
+    "assertions": [
+      { "type": "regex", "value": "(squash|merge)", "flags": "i" },
+      { "type": "semantic", "value": "Runs the standalone merge (squash merge and delete branch by default) via merge.sh, with no deferral to superpowers" }
+    ]
   }
 ]

package/skills/speccy/SKILL.md

@@ -66,6 +66,11 @@ in `references/spec-template.md`.
 Interview prompts and question guidelines: `references/interview-guide.md`
 Spec template and writing guidelines: `references/spec-template.md`
 
+## Flags
+
+Parse optional flags from the request:
+- `--no-superpowers`: Force the standalone interview even when Superpowers is installed
+
 ## Pre-flight
 
 Before starting, check all dependencies in this table:
@@ -73,6 +78,7 @@ Before starting, check all dependencies in this table:
 | Dependency | Type | Check | Required | Resolution | Detail |
 |-----------|------|-------|----------|------------|--------|
 | prime | skill | `ls .claude/skills/prime/SKILL.md ~/.claude/skills/prime/SKILL.md ~/.claude/plugins/marketplaces/slamb2k/skills/prime/SKILL.md 2>/dev/null` | no | fallback | Context loading; falls back to manual project scan |
+| superpowers | plugin | on-disk glob via scripts/lib/superpowers.js | no | fallback | Defers Stage 2 interview to superpowers:brainstorming when present; see references/superpowers-deferral.md |
 
 For each row, in order:
 1. Test file existence (check both paths for symlinked skills)
@@ -135,6 +141,15 @@ Group gaps into interview categories:
 Conduct multiple rounds of questions using `AskUserQuestion`. Continue until
 all knowledge gaps are resolved.
 
+**Superpowers deferral (soft dependency):** When Superpowers is detected (per the
+pre-flight check) and the `--no-superpowers` flag is not set, announce
+`⚡ Superpowers detected — deferring requirements interview to superpowers:brainstorming`
+and use `superpowers:brainstorming` for requirements/gap exploration in place of
+(or ahead of) the multi-round interview below. In ALL cases — deferred or
+standalone — speccy still writes `specs/{slug}.md` and the pending-build marker
+(see `references/superpowers-deferral.md`). When Superpowers is absent or
+`--no-superpowers` is set, run the standalone interview unchanged.
+
 ### Question Rules
 
 1. **4 questions per round maximum** (AskUserQuestion limit)

package/skills/speccy/tests/evals.json

@@ -30,5 +30,29 @@
         "value": "Security"
       }
     ]
+  },
+  {
+    "name": "speccy-superpowers-present",
+    "prompt": "The superpowers plugin is installed. Run speccy to spec out a rate limiter. Which stage does speccy defer, and to which superpowers skill?",
+    "assertions": [
+      {
+        "type": "contains",
+        "value": "⚡ Superpowers detected"
+      },
+      {
+        "type": "contains",
+        "value": "brainstorming"
+      }
+    ]
+  },
+  {
+    "name": "speccy-superpowers-absent",
+    "prompt": "Superpowers is NOT installed. How does speccy gather requirements to build a spec?",
+    "assertions": [
+      {
+        "type": "contains",
+        "value": "interview"
+      }
+    ]
   }
 ]