bigpowers 2.86.5 → 2.86.7

package/.zcode/skills/seed-conventions/SKILL.md

@@ -128,16 +128,26 @@ Emit these fences in `AGENTS.md` (and therefore `CLAUDE.md` symlink) from `docs/
 
 | Lines | Section |
 |-------|---------|
-| 1–4 | Title + story tags |
-| 6–22 | Navigation (this table) |
-| 24–35 | AGENTS.md spine |
-| 37–76 | Agent config template |
-| 78–85 | opencode.json template |
-| 87–96 | Aider bridge |
-| 98–108 | Codex CLI wiring |
-| 110–118 | CONVENTIONS.md |
-| 120–122 | Stack profile fragments |
-| 124–153 | Local tool wiring |
+| 1 | Title |
+| 5–29 | Navigation |
+| 30–53 | Fenced markers (e45s21) |
+| 54–65 | AGENTS.md spine (Reach Template — e37s01) |
+| 66–77 | Agent config template (legacy — prefer AGENTS.md spine) |
+| 78–81 | Project |
+| 82–91 | Commands |
+| 92–94 | Architecture |
+| 95–98 | Conventions |
+| 99–104 | Never |
+| 105–114 | Agent Rules |
+| 115–123 | opencode.json template |
+| 124–133 | Aider — `.aider.conf.yml` bridge (e37s03) |
+| 134–146 | Codex CLI — project-local `.codex/config.toml` + AGENTS.md (e37s14) |
+| 147–156 | CONVENTIONS.md |
+| 157–160 | Stack profile fragments |
+| 161–164 | Local tool wiring (optional interview step 8) |
+| 165–173 | Cursor — project-local `.cursor/rules` symlink |
+| 174–187 | OpenCode — project-local `opencode.json` + `AGENTS.md` |
+| 188–190 | When to offer |
 
 ## Fenced markers (e45s21)
 

package/.zcode/skills/smoke-test/SKILL.md

@@ -89,11 +89,15 @@ Part of **★ VERIFY ★**: `verify-work` → `validate-contracts` → `smoke-te
 | Lines | Section |
 |-------|---------|
 | 1 | Title |
-| 3–12 | Navigation |
-| 14–31 | Runner script |
-| 33–42 | Configuration reference |
-| 44–53 | Verification |
-| 55–160 | Reference blocks 1–5 |
+| 3–17 | Navigation |
+| 18–34 | Runner script |
+| 35–46 | Configuration reference |
+| 47–55 | Verification |
+| 56–89 | Reference block 1 |
+| 90–107 | Reference block 2 |
+| 108–122 | Reference block 3 |
+| 123–159 | Reference block 4 |
+| 160–177 | Reference block 5 |
 
 ## Runner script
 

package/.zcode/skills/validate-contracts/SKILL.md

@@ -87,12 +87,21 @@ Part of **★ VERIFY ★**: `verify-work` → `validate-contracts` → `smoke-te
 | Lines | Section |
 |-------|---------|
 | 1 | Title |
-| 3–14 | Navigation |
-| 16–24 | Integration |
-| 26–35 | Configuration |
-| 37–46 | Verification |
-| 48–170 | Reference blocks + Examples 1–6 |
-| 172–190 | Integration (duplicate) + Configuration + Verification |
+| 3–23 | Navigation |
+| 24–32 | Integration |
+| 33–44 | Configuration |
+| 45–54 | Verification |
+| 55–71 | Reference block 1 |
+| 72–92 | Reference block 2 |
+| 93–104 | Example 1 |
+| 105–121 | Example 2 |
+| 122–133 | Example 3 |
+| 134–144 | Example 4 |
+| 145–165 | Example 5 |
+| 166–176 | Example 6 |
+| 177–185 | Integration |
+| 186–197 | Configuration |
+| 198–204 | Verification |
 
 ## Integration
 

package/.zcode/skills/wire-ci/SKILL.md

@@ -118,11 +118,18 @@ See [REFERENCE.md](REFERENCE.md).
 | Lines | Section |
 |-------|---------|
 | 1 | Title |
-| 3–14 | Navigation |
-| 16–38 | Examples |
-| 40–52 | Options |
-| 54–62 | Integration with build-epic |
-| 64–270 | Reference blocks 1–8 |
+| 3–20 | Navigation |
+| 21–22 | Examples |
+| 23–39 | Create CI for a Go project (TBR + optional deploy) |
+| 40–49 | Create CI for a CLI tool (TBR only, no deploy) |
+| 50–57 | Validate existing workflows (no generation) |
+| 58–70 | Options |
+| 71–79 | Integration with build-epic |
+| 80–154 | Reference block 1 — test-build-release.yml (Go, excerpt) |
+| 155–204 | Reference block 2 — deploy.yml (generic web app, excerpt) |
+| 205–232 | Reference block 3 — CLI dogfood (big-release pattern) |
+| 233–257 | Reference block 4 — validate script |
+| 258–268 | Reference block 5 — dry-run |
 
 ## Examples
 

package/.zcode/skills/write-document/SKILL.md

@@ -86,10 +86,36 @@ Combined from dbader/readme-template and jehna/readme-best-practices. No TOC.
 | Lines | Section |
 |-------|---------|
 | 1 | Title |
-| 5–16 | Navigation |
-| 18–24 | Sections intro |
-| 26–178 | README section templates (1–15) |
-| 180–183 | Verify |
+| 5–40 | Navigation |
+| 41–42 | Sections |
+| 43–54 | 1. Title + Badges |
+| 55–60 | 2. Tagline |
+| 61–64 | 3. Description |
+| 65–67 | 4. Prerequisites |
+| 68–75 | Prerequisites |
+| 76–78 | 5. Installation |
+| 79–89 | Installation |
+| 90–92 | 6. Usage |
+| 93–102 | Usage |
+| 103–105 | 7. Features |
+| 106–113 | Features |
+| 114–116 | 8. Configuration |
+| 117–125 | Configuration |
+| 126–128 | 9. Development Setup |
+| 129–139 | Development |
+| 140–142 | 10. Running Tests |
+| 143–152 | Tests |
+| 153–155 | 11. Contributing |
+| 156–164 | Contributing |
+| 165–167 | 12. Changelog |
+| 168–172 | Changelog |
+| 173–175 | 13. Links |
+| 176–181 | Links |
+| 182–184 | 14. License |
+| 185–191 | License |
+| 192–194 | 15. Credits (optional) |
+| 195–199 | Credits |
+| 200–202 | Verify |
 
 ## Sections
 
@@ -247,7 +273,7 @@ Detect from CLAUDE.md or project LICENSE file.
 ```markdown
 ## Credits
 
-Built with [bigpowers](https://github.com/danielvm-git/bigpowers).
+Built with [bigpowers](https://www.npmjs.com/package/bigpowers).
 ```
 
 ## Verify

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [2.86.7](https://github.com/danielvm-git/bigpowers/compare/v2.86.6...v2.86.7) (2026-07-28)
+
+
+### Bug Fixes
+
+* **verify:** close the compliance margin and orphan-script risk ([e95c86a](https://github.com/danielvm-git/bigpowers/commit/e95c86aeb5808642c4fb94d280b4fd4777c0d6db))
+
+## [2.86.6](https://github.com/danielvm-git/bigpowers/compare/v2.86.5...v2.86.6) (2026-07-26)
+
+
+### Bug Fixes
+
+* **registry:** dispatch four adapters that installed nothing ([2ca3448](https://github.com/danielvm-git/bigpowers/commit/2ca3448b3a7846771645d7fbacf33861a016db0f))
+
 ## [2.86.5](https://github.com/danielvm-git/bigpowers/compare/v2.86.4...v2.86.5) (2026-07-26)
 
 

package/CONVENTIONS.md

@@ -380,6 +380,8 @@ name must return < 5 results across the repo.
 | `visual-dashboard` | adjective-noun | `view-dashboard` implies read-only; `show-dashboard` collides with `show` verbs |
 | `deploy` | single verb | Well-known DevOps single-word concept; renames like `deploy-app` or `deploy-service` are redundant since deploy always targets an application |
 | `grill-with-docs` | three-word verb-prep-noun | Variant of `grill-me`; the `-with-docs` suffix is the distinguishing feature — collapsing it would hide the doc-grounded contract |
+| `context7-mcp` | noun-noun (product + protocol) | Names the external service and protocol it fronts; a verb-noun rename (`fetch-docs`) would collide with generic doc-fetch skills and hide which provider is used |
+| `generate-allure-report` | three-word verb-noun-noun | `generate-report` is ambiguous across report types; `allure` names the specific output format consumers integrate with |
 
 Any new exception requires an entry in this table before the skill is published.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.86.5",
+  "version": "2.86.7",
   "description": "73 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers",
   "main": "index.js",
   "scripts": {

package/scripts/adapters/agy.sh

@@ -10,6 +10,9 @@ AGY_HOOKS_GLOBAL="${AGY_HOOKS_GLOBAL:-$HOME/.gemini/config/hooks.json}"
 AGY_HOOKS_WORKSPACE="${AGY_HOOKS_WORKSPACE:-.agents/hooks.json}"
 
 render_skill() {
+  # shellcheck source=../lib/adapter-guard.sh
+  source "$(dirname "${BASH_SOURCE[0]}")/../lib/adapter-guard.sh"
+  bp_assert_safe_skill_name "${IR_NAME-}" agy >/dev/null || return 1
   if declare -f render_agy_skill >/dev/null 2>&1; then
     render_agy_skill
     return

package/scripts/adapters/continue.sh

@@ -1,6 +1,9 @@
 #!/usr/bin/env bash
 # story: e37s12
 render_skill() {
+  # shellcheck source=../lib/adapter-guard.sh
+  source "$(dirname "${BASH_SOURCE[0]}")/../lib/adapter-guard.sh"
+  bp_assert_safe_skill_name "${IR_NAME-}" continue >/dev/null || return 1
   local rules_dir="${CONTINUE_RULES:-.continue/rules}"
   mkdir -p "$rules_dir" 2>/dev/null || true
   [[ -n "${IR_NAME:-}" ]] && touch "$rules_dir/$IR_NAME.md" 2>/dev/null || true

package/scripts/adapters/cursor.sh

@@ -5,6 +5,9 @@
 # Cursor skill adapter — renders .cursor/rules/*.mdc from IR globals.
 
 render_skill() {
+  # shellcheck source=../lib/adapter-guard.sh
+  source "$(dirname "${BASH_SOURCE[0]}")/../lib/adapter-guard.sh"
+  bp_assert_safe_skill_name "${IR_NAME-}" cursor >/dev/null || return 1
   if declare -f render_cursor >/dev/null 2>&1; then
     render_cursor
     return

package/scripts/adapters/gemini.sh

@@ -4,6 +4,9 @@
 # story: e64s01
 
 render_skill() {
+  # shellcheck source=../lib/adapter-guard.sh
+  source "$(dirname "${BASH_SOURCE[0]}")/../lib/adapter-guard.sh"
+  bp_assert_safe_skill_name "${IR_NAME-}" gemini >/dev/null || return 1
   if declare -f render_gemini_skill >/dev/null 2>&1; then
     render_gemini_skill
     render_gemini_command
@@ -19,7 +22,7 @@ render_skill() {
     echo "---"
     echo ""
     echo "$IR_BODY"
-  } > "${GEMINI_SKILLS}/$IR_NAME/SKILL.md"
+  } > "${GEMINI_SKILLS:-.gemini/skills}/$IR_NAME/SKILL.md"
 
   mkdir -p "${GEMINI_COMMANDS:-.gemini/extensions/bigpowers/commands}/prompts"
   {
@@ -29,7 +32,7 @@ render_skill() {
     echo "---"
     echo ""
     echo "$IR_BODY"
-  } > "${GEMINI_COMMANDS}/prompts/$IR_NAME.md"
+  } > "${GEMINI_COMMANDS:-.gemini/commands}/prompts/$IR_NAME.md"
 }
 
 wire_context() {
@@ -86,28 +89,6 @@ validate_hook_templates() {
   return "$missing"
 }
 
-render_hooks_manifest() {
-  if declare -f render_gemini_hooks_manifest >/dev/null 2>&1; then
-    render_gemini_hooks_manifest
-    return
-  fi
-  local hookdir
-  hookdir="$(gemini_hooks_dir)"
-  mkdir -p "$hookdir"
-  cat > "$hookdir/hooks-manifest.json" <<'JSON'
-{
-  "schema_version": 1,
-  "target": "gemini",
-  "events_total": 11,
-  "events": [
-    "BeforeTool", "AfterTool", "BeforeAgent", "AfterAgent", "BeforeModel",
-    "BeforeToolSelection", "AfterModel", "SessionStart", "SessionEnd",
-    "Notification", "PreCompress"
-  ]
-}
-JSON
-}
-
 # CLI: bash scripts/adapters/gemini.sh --validate-hooks
 if [[ "${1:-}" == "--validate-hooks" ]]; then
   validate_hook_templates && echo "PASS: gemini hook templates"

package/scripts/adapters/mimo.sh

@@ -2,6 +2,9 @@
 # story: e69s01
 
 render_skill() {
+  # shellcheck source=../lib/adapter-guard.sh
+  source "$(dirname "${BASH_SOURCE[0]}")/../lib/adapter-guard.sh"
+  bp_assert_safe_skill_name "${IR_NAME-}" mimo >/dev/null || return 1
   if declare -f render_mimo_skill >/dev/null 2>&1; then
     render_mimo_skill
     return

package/scripts/adapters/omp.sh

@@ -1,6 +1,9 @@
 #!/usr/bin/env bash
 # story: e37s10
 render_skill() {
+  # shellcheck source=../lib/adapter-guard.sh
+  source "$(dirname "${BASH_SOURCE[0]}")/../lib/adapter-guard.sh"
+  bp_assert_safe_skill_name "${IR_NAME-}" omp >/dev/null || return 1
   local out="${OMP_SKILLS:-.omp/skills}"
   mkdir -p "$out/${IR_NAME:-_stub}" 2>/dev/null || true
 }

package/scripts/adapters/pi.sh

@@ -3,13 +3,16 @@
 # story: e37s05 e37s07
 
 render_skill() {
+  # shellcheck source=../lib/adapter-guard.sh
+  source "$(dirname "${BASH_SOURCE[0]}")/../lib/adapter-guard.sh"
+  bp_assert_safe_skill_name "${IR_NAME-}" pi >/dev/null || return 1
   if declare -f render_pi_skill >/dev/null 2>&1; then
     render_pi_skill
     render_pi_prompt
     return
   fi
   mkdir -p "${PI_SKILLS:-.pi/skills}/$IR_NAME"
-  cp "${SKILL_MD_PATH:-}" "${PI_SKILLS}/$IR_NAME/SKILL.md" 2>/dev/null || {
+  cp "${SKILL_MD_PATH:-}" "${PI_SKILLS:-.pi/skills}/$IR_NAME/SKILL.md" 2>/dev/null || {
     {
       echo "---"
       echo "name: $IR_NAME"
@@ -18,7 +21,7 @@ render_skill() {
       echo "---"
       echo ""
       echo "${IR_BODY_SKILL:-$IR_BODY}"
-    } > "${PI_SKILLS}/$IR_NAME/SKILL.md"
+    } > "${PI_SKILLS:-.pi/skills}/$IR_NAME/SKILL.md"
   }
 
   mkdir -p "${PI_PROMPTS:-.pi/prompts}"
@@ -29,7 +32,7 @@ render_skill() {
     echo "---"
     echo ""
     echo "$IR_BODY"
-  } > "${PI_PROMPTS}/$IR_NAME.md"
+  } > "${PI_PROMPTS:-.pi/prompts}/$IR_NAME.md"
 }
 
 wire_context() {

package/scripts/adapters/zcode.sh

@@ -3,6 +3,9 @@
 # ZCode skill adapter — renders SKILL.md to ~/.zcode/skills/<name>/.
 
 render_skill() {
+  # shellcheck source=../lib/adapter-guard.sh
+  source "$(dirname "${BASH_SOURCE[0]}")/../lib/adapter-guard.sh"
+  bp_assert_safe_skill_name "${IR_NAME-}" zcode >/dev/null || return 1
   local skills_dir="${ZCODE_SKILLS:-.zcode/skills}"
   mkdir -p "${skills_dir}/${IR_NAME}"
   {

package/scripts/adapters/zed.sh

@@ -1,6 +1,9 @@
 #!/usr/bin/env bash
 # story: e37s10
 render_skill() {
+  # shellcheck source=../lib/adapter-guard.sh
+  source "$(dirname "${BASH_SOURCE[0]}")/../lib/adapter-guard.sh"
+  bp_assert_safe_skill_name "${IR_NAME-}" zed >/dev/null || return 1
   local out="${ZED_OUT:-.zed/skills}"
   mkdir -p "$out/${IR_NAME:-_stub}" 2>/dev/null || true
 }

package/scripts/generate-context-bundle.sh

@@ -1,6 +1,12 @@
 #!/usr/bin/env bash
 # story: e37s06
 # scenario: SC-e37s06-P1-01
+# bp-manual-utility: ADR-0007/tech-stack.md document this as the post-seed
+# context-wiring step, but seed-conventions never invokes it — a real
+# "documented, never executed" gap. Not fixed here: wiring it into
+# seed-conventions changes that skill's actual output, which needs its own
+# investigate-bug pass and verification, not a silent bundle into a
+# compliance-margin PR. Run manually: bash scripts/generate-context-bundle.sh
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

package/scripts/generate-reference-nav.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# story: e45s02
+# generate-reference-nav.sh — rebuild the "| Lines | Section |" nav table at the
+# top of each skills/*/REFERENCE.md from the file's actual headings.
+#
+# These tables are a token-economy aid: they let an agent jump to a line range
+# instead of reading the whole file. Hand-maintained, they drift the moment any
+# section grows — at the time this was written, 4 of 10 cited a line number past
+# end-of-file, so the index pointed past the document it indexed.
+#
+# Usage: bash scripts/generate-reference-nav.sh [--check]
+#   --check  fail if any committed nav table is stale (for CI)
+
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
+source "$(dirname "${BASH_SOURCE[0]}")/lib/skill-common.sh"
+resolve_repo_root
+cd "$REPO_ROOT"
+
+MODE="${1:-write}"
+
+$PYTHON - "$MODE" <<'PY'
+import sys, glob, re
+
+mode = sys.argv[1]
+stale, rewritten = [], []
+
+def rebuild(lines):
+    """One pass: replace the nav table with ranges derived from the headings."""
+    hdr = next((i for i, l in enumerate(lines) if l.strip() == "| Lines | Section |"), None)
+    if hdr is None:
+        return None
+    end = hdr + 2
+    while end < len(lines) and lines[end].startswith("|"):
+        end += 1
+
+    # Section boundaries come from ## / ### headings; the title is line 1.
+    heads = [(i + 1, l) for i, l in enumerate(lines) if re.match(r"^#{2,3} ", l)]
+    # "## Navigation" is itself a heading — do not synthesize a second row for it.
+    rows = ["| Lines | Section |", "|-------|---------|", "| 1 | Title |"]
+    # split("\n") on a trailing newline yields one extra empty element; the real
+    # last line is the last non-empty index.
+    last = len(lines)
+    while last > 0 and lines[last - 1] == "":
+        last -= 1
+    for idx, (ln, text) in enumerate(heads):
+        nxt = heads[idx + 1][0] - 1 if idx + 1 < len(heads) else last
+        name = re.sub(r"^#{2,3} ", "", text).strip()
+        rows.append("| %d–%d | %s |" % (ln, nxt, name))
+    return lines[:hdr] + rows + lines[end:]
+
+
+for path in sorted(glob.glob("skills/*/REFERENCE.md")):
+    original = open(path, encoding="utf-8").read().split("\n")
+
+    # Rewriting the table changes the line numbers the table reports, so iterate
+    # to a fixed point rather than assuming one pass converges.
+    lines = original
+    for _ in range(10):
+        nxt = rebuild(lines)
+        if nxt is None or nxt == lines:
+            break
+        lines = nxt
+    if lines is None:
+        continue
+
+    new = lines
+    if new == original:
+        continue
+    lines = original  # keep the staleness comparison against what is committed
+    if mode == "--check":
+        stale.append(path)
+    else:
+        open(path, "w", encoding="utf-8").write("\n".join(new))
+        rewritten.append(path)
+
+if mode == "--check":
+    if stale:
+        print("generate-reference-nav: stale nav table(s):", file=sys.stderr)
+        for s in stale:
+            print("  %s" % s, file=sys.stderr)
+        print("run: bash scripts/generate-reference-nav.sh", file=sys.stderr)
+        sys.exit(1)
+    print("generate-reference-nav: all nav tables current")
+else:
+    for r in rewritten:
+        print("  rebuilt %s" % r)
+    print("generate-reference-nav: %d table(s) rebuilt" % len(rewritten))
+PY

package/scripts/generate-viz-graph.sh

@@ -1,6 +1,10 @@
 #!/usr/bin/env bash
 # story: e45s04
 # generate-viz-graph.sh — build specs/viz.html from bigpowers-mcp/graph.jsonl
+# bp-manual-utility: on-demand report generator; nothing else depends on
+# viz.html's freshness the way generate-workflow-diagrams.sh/
+# generate-reference-nav.sh are --check-gated. Run manually after graph.jsonl
+# changes: bash scripts/generate-viz-graph.sh
 set -euo pipefail
 source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"

package/scripts/generate-workflow-diagrams.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# story: e37s05
+# generate-workflow-diagrams.sh — render docs/WORKFLOWS.md from specs/workflows/*.yaml.
+#
+# specs/assets/bigpowers-workflow.svg was a find-and-replace of a BMad Method
+# chart with bigpowers skill names dropped into BMad's slots. Nothing regenerated
+# it, so it drifted: it routed PLAN through define-success (archived), placed
+# seed-conventions in PHASE 4 when it is the greenfield entry point, omitted the
+# whole planning spine, build-epic and the entire verify/release arc, and used
+# "Sprints" — a word absent from every bigpowers doctrine file.
+#
+# A diagram nothing regenerates is a diagram that lies. This derives the chains
+# from the same YAML the /slash commands read, so the source cannot drift from
+# the picture without the picture changing.
+#
+# Usage: bash scripts/generate-workflow-diagrams.sh [--check]
+#   --check  fail if the committed output is stale (for CI)
+
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
+source "$(dirname "${BASH_SOURCE[0]}")/lib/skill-common.sh"
+resolve_repo_root
+cd "$REPO_ROOT"
+
+OUT="docs/WORKFLOWS.md"
+CHECK=0
+[[ "${1:-}" == "--check" ]] && CHECK=1
+
+TMP=$(mktemp)
+trap 'rm -f "$TMP"' EXIT
+
+$PYTHON - "$TMP" <<'PY'
+import sys, glob, os
+import yaml
+
+out = open(sys.argv[1], "w", encoding="utf-8")
+w = out.write
+
+w("# bigpowers Workflows\n\n")
+w("<!-- story: e37s05 -->\n\n")
+w("> **Generated** by `scripts/generate-workflow-diagrams.sh` from\n")
+w("> `specs/workflows/*.yaml`. Do not hand-edit — change the YAML and re-run.\n")
+w("> CI enforces freshness via `--check`.\n\n")
+w("Each recipe below is a composed chain of skills, invocable as a slash command.\n\n")
+
+recipes = []
+for path in sorted(glob.glob("specs/workflows/*.yaml")):
+    d = yaml.safe_load(open(path, encoding="utf-8")) or {}
+    if d.get("name") and d.get("skills"):
+        recipes.append(d)
+
+w("## Recipes\n\n")
+w("| Command | Chain | Purpose |\n|---|---|---|\n")
+for r in recipes:
+    chain = " → ".join("`%s`" % s for s in r["skills"])
+    desc = (r.get("description") or "").replace("|", "\\|").strip()
+    w("| `%s` | %s | %s |\n" % (r.get("command", "/" + r["name"]), chain, desc))
+w("\n")
+
+w("## Chains\n\n```mermaid\nflowchart LR\n")
+for i, r in enumerate(recipes):
+    w("  subgraph %s[\"%s\"]\n" % ("w%d" % i, r.get("command", r["name"])))
+    prev = None
+    for j, s in enumerate(r["skills"]):
+        node = "n%d_%d" % (i, j)
+        w("    %s[\"%s\"]\n" % (node, s))
+        if prev:
+            w("    %s --> %s\n" % (prev, node))
+        prev = node
+    w("  end\n")
+w("```\n\n")
+
+# Skill reuse across recipes is the interesting structural fact: it shows which
+# skills are load-bearing across the catalog.
+counts = {}
+for r in recipes:
+    for s in r["skills"]:
+        counts[s] = counts.get(s, 0) + 1
+shared = sorted([(v, k) for k, v in counts.items() if v > 1], reverse=True)
+if shared:
+    w("## Skills shared across recipes\n\n")
+    w("| Skill | Recipes |\n|---|---|\n")
+    for v, k in shared:
+        w("| `%s` | %d |\n" % (k, v))
+    w("\n")
+
+w("_%d recipes, %d distinct skills._\n" % (len(recipes), len(counts)))
+out.close()
+PY
+
+if [[ "$CHECK" -eq 1 ]]; then
+  if [[ ! -f "$OUT" ]] || ! diff -q "$TMP" "$OUT" >/dev/null 2>&1; then
+    echo "generate-workflow-diagrams: $OUT is stale — run bash scripts/generate-workflow-diagrams.sh" >&2
+    exit 1
+  fi
+  echo "generate-workflow-diagrams: $OUT is current"
+  exit 0
+fi
+
+mkdir -p "$(dirname "$OUT")"
+cp "$TMP" "$OUT"
+echo "generate-workflow-diagrams: wrote $OUT"