feat(release): version badges + release hardening (patch-floor + CHANGELOG)

.github/workflows/release.yml

@@ -145,6 +145,15 @@ jobs:
             sed -i "s|version \".*\"|version \"${NEW_VERSION}\"|" Formula/devflow.rb
           fi
 
+          # 3b. Prepend this release's notes to CHANGELOG.md
+          CHANGELOG_BODY="$(awk '/^## Install/{exit} !/^## What.?s New/{print}' /tmp/release-notes.md)"
+          {
+            printf '## v%s — %s\n' "${NEW_VERSION}" "$(date -u +%Y-%m-%d)"
+            printf '%s\n\n' "${CHANGELOG_BODY}"
+            [[ -f CHANGELOG.md ]] && cat CHANGELOG.md
+          } > CHANGELOG.md.tmp
+          mv CHANGELOG.md.tmp CHANGELOG.md
+
           # 4. Single commit + tag + push
           git add -A
           git commit -m "chore(release): v${NEW_VERSION} [skip release]"

CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to devflow. New entries are prepended automatically by the
+release workflow (`.github/workflows/release.yml`).
+
+## v0.2.1 — 2026-05-30
+
+### Features
+- `render-diagram` skill / `devflow visualizations render`: pure-node Excalidraw → PNG export (no browser, no MCP), shown inline via the Read tool; wired into review, spec-feature, codebase-walkthrough, update-visualizations, architecture-decision.
+
+### Other Changes
+- docs: record export-pipeline + release-pipeline gotchas (render-diagram maintenance notes + Release Process).
+
+## v0.2.0 — 2026-05-30
+
+### Features
+- `/devflow:render-diagram` — author + render Excalidraw diagrams from a description or codebase analysis; embed in docs.
+- visualizations: opt-in `format: mermaid|excalidraw` config.
+
+### Fixes
+- release pipeline: guard `check_version_consistency` badge grep under `pipefail`; create an annotated tag so `git push --follow-tags` pushes it.

devflow-plugin/commands/architecture-decision.md

@@ -1,5 +1,5 @@
 ---
-description: Document an architectural decision — record the decision and rationale, retain into Hindsight, and update CLAUDE.md if needed.
+description: [0.2.1] Document an architectural decision — record the decision and rationale, retain into Hindsight, and update CLAUDE.md if needed.
 ---
 
 You are documenting an architectural decision. This command ensures decisions are properly recorded and available for future recall.

devflow-plugin/commands/best-roi-task.md

@@ -1,5 +1,5 @@
 ---
-description: Find the best ROI task in a Jira Epic — highest story points for least effort, filtered to unassigned To Do tasks only.
+description: [0.2.1] Find the best ROI task in a Jira Epic — highest story points for least effort, filtered to unassigned To Do tasks only.
 ---
 
 You are analyzing a Jira Epic to find the task with the best return on investment (highest story points relative to effort/size) that is available to pick up.

devflow-plugin/commands/brainstorming.md

@@ -1,5 +1,5 @@
 ---
-description: Devflow wrapper for the upstream brainstorming skill. Use when starting any creative work — creating features, building components, adding functionality, or modifying behavior — to explore user intent, requirements, and design before implementation. Always invoke `/devflow:brainstorming` rather than the upstream skill directly so devflow can layer in project-specific behavior (recall hooks, phase-handoff entry points) without callers ever needing to know about the upstream.
+description: [0.2.1] Devflow wrapper for the upstream brainstorming skill. Use when starting any creative work — creating features, building components, adding functionality, or modifying behavior — to explore user intent, requirements, and design before implementation. Always invoke `/devflow:brainstorming` rather than the upstream skill directly so devflow can layer in project-specific behavior (recall hooks, phase-handoff entry points) without callers ever needing to know about the upstream.
 ---
 
 You are the devflow wrapper for the upstream brainstorming workflow. The wrapper exists so the rest of the devflow pipeline (new-feature, spec-feature, etc.) has a single canonical entry point (`/devflow:brainstorming`) and never reaches past it to the upstream skill directly.

devflow-plugin/commands/codebase-walkthrough.md

@@ -1,5 +1,5 @@
 ---
-description: Deep codebase walkthrough before implementation — trace the full flow, explain architecture, and build understanding.
+description: [0.2.1] Deep codebase walkthrough before implementation — trace the full flow, explain architecture, and build understanding.
 ---
 
 Guide the user through a deep technical walkthrough of the codebase areas affected by their task, BEFORE any implementation begins. This builds architectural understanding so the user can meaningfully review code during implementation.

devflow-plugin/commands/create-pr.md

@@ -1,5 +1,5 @@
 ---
-description: Full PR creation pipeline — self-review, code review checks, and PR creation with a structured template.
+description: [0.2.1] Full PR creation pipeline — self-review, code review checks, and PR creation with a structured template.
 ---
 
 You are creating a pull request. This command runs the full PR pipeline.

devflow-plugin/commands/dependency-update.md

@@ -1,5 +1,5 @@
 ---
-description: Check if Brewfile, Formula, or install script need updating when project dependencies change.
+description: [0.2.1] Check if Brewfile, Formula, or install script need updating when project dependencies change.
 ---
 
 You are checking whether devflow's dependency manifests are in sync with code changes.

devflow-plugin/commands/executing-plans.md

@@ -1,5 +1,5 @@
 ---
-description: Devflow wrapper for the upstream executing-plans skill. Use when you have a written implementation plan to execute task-by-task. ALWAYS invoke `/devflow:executing-plans` rather than the upstream skill directly — this wrapper guarantees that the post-implementation handoff goes to `/devflow:finish-feature` (devflow's verification + PR/MR creation flow) instead of `superpowers:finishing-a-development-branch` (the upstream default, which doesn't integrate with devflow's VCS-coherent finish flow).
+description: [0.2.1] Devflow wrapper for the upstream executing-plans skill. Use when you have a written implementation plan to execute task-by-task. ALWAYS invoke `/devflow:executing-plans` rather than the upstream skill directly — this wrapper guarantees that the post-implementation handoff goes to `/devflow:finish-feature` (devflow's verification + PR/MR creation flow) instead of `superpowers:finishing-a-development-branch` (the upstream default, which doesn't integrate with devflow's VCS-coherent finish flow).
 ---
 
 You are the devflow wrapper for the upstream executing-plans workflow. The wrapper exists for TWO reasons:

devflow-plugin/commands/finish-feature.md

@@ -1,5 +1,5 @@
 ---
-description: Finish a feature — run verification, create PR, retain learnings, and hand off cleanup to the terminal.
+description: [0.2.1] Finish a feature — run verification, create PR, retain learnings, and hand off cleanup to the terminal.
 ---
 
 You are finishing a feature. Run the full completion pipeline before handing off to the developer for worktree cleanup.

devflow-plugin/commands/lock-tests.md

@@ -1,5 +1,5 @@
 ---
-description: Lock the full test inventory before any implementation code is written. Reads spec+plan+AC, writes ALL failing tests in a batch, emits a Test Inventory doc, and gates with user approval.
+description: [0.2.1] Lock the full test inventory before any implementation code is written. Reads spec+plan+AC, writes ALL failing tests in a batch, emits a Test Inventory doc, and gates with user approval.
 ---
 
 > **Attribution:** Base TDD workflow vendored and adapted from [haletothewood/behavioural-tdd v1.8](https://tessl.io/registry/haletothewood/behavioural-tdd), Apache-2.0. Modifications: Phase 1 widened from single-test to batch; added Phase 0 (read artefacts) and Phase 1.7 (Test Inventory) and Phase 1.8 (user-approval gate); Phases 2-3 delegated to `/devflow:executing-plans` (the devflow wrapper that delegates to upstream `superpowers:executing-plans` for the per-task red/green/refactor loop AND forces the post-implementation handoff to `/devflow:finish-feature`).

devflow-plugin/commands/new-feature.md

@@ -1,5 +1,5 @@
 ---
-description: Post-launch setup for a new feature worktree — detect context, recall memories, and transition to brainstorming.
+description: [0.2.1] Post-launch setup for a new feature worktree — detect context, recall memories, and transition to brainstorming.
 ---
 
 You have been launched inside a feature worktree. Your job is to orient yourself, load context, and start the feature.

devflow-plugin/commands/phase-handoff.md

@@ -1,5 +1,5 @@
 ---
-description: Hand off between phases of the devflow new-feature pipeline. Writes a frozen-state file, marks a chapter, sets the terminal title, gates on a one-click AskUserQuestion, then spawns a new session for the next phase via `mcp__ccd_session__spawn_task` so it shows up in the Claude Desktop sidebar with a deterministic title.
+description: [0.2.1] Hand off between phases of the devflow new-feature pipeline. Writes a frozen-state file, marks a chapter, sets the terminal title, gates on a one-click AskUserQuestion, then spawns a new session for the next phase via `mcp__ccd_session__spawn_task` so it shows up in the Claude Desktop sidebar with a deterministic title.
 ---
 
 You are at a phase boundary in devflow's new-feature pipeline. Capture the current state to disk, mark the transition in the CURRENT session, then spawn a NEW session (`mcp__ccd_session__spawn_task`) for the next phase. The new session starts cold — its only context is the prompt you hand it, which points at the frozen-state file plus absolute artefact paths.

devflow-plugin/commands/pre-push-check.md

@@ -1,5 +1,5 @@
 ---
-description: Run the full pre-push review pipeline — code review checks, self-review against CLAUDE.md, and a final report.
+description: [0.2.1] Run the full pre-push review pipeline — code review checks, self-review against CLAUDE.md, and a final report.
 ---
 
 You are about to push code. Run the full pre-push quality pipeline before pushing.

devflow-plugin/commands/recall-before-task.md

@@ -1,5 +1,5 @@
 ---
-description: Recall relevant memories from Hindsight before starting a task. Injects past learnings, decisions, and context into the current session.
+description: [0.2.1] Recall relevant memories from Hindsight before starting a task. Injects past learnings, decisions, and context into the current session.
 ---
 
 You are about to start a task. Before doing anything else, recall relevant memories so you have full context.

devflow-plugin/commands/reflect-session.md

@@ -1,5 +1,5 @@
 ---
-description: Reflect on the current session, extract learnings, and consolidate them into Hindsight for future recall.
+description: [0.2.1] Reflect on the current session, extract learnings, and consolidate them into Hindsight for future recall.
 ---
 
 You are wrapping up a session. Reflect on what happened and consolidate the valuable learnings.

devflow-plugin/commands/render-diagram.md

@@ -1,5 +1,5 @@
 ---
-description: Create and render an Excalidraw diagram from a description or codebase analysis — exports to PNG via a pure-node pipeline (no browser/MCP), shows it inline via the Read tool, and embeds it in docs. Use when asked to diagram, visualize, or draw an architecture/flow, or when another skill needs a rendered diagram.
+description: [0.2.1] Create and render an Excalidraw diagram from a description or codebase analysis — exports to PNG via a pure-node pipeline (no browser/MCP), shows it inline via the Read tool, and embeds it in docs. Use when asked to diagram, visualize, or draw an architecture/flow, or when another skill needs a rendered diagram.
 ---
 
 # Render Diagram

devflow-plugin/commands/resolve-repo.md

@@ -1,5 +1,5 @@
 ---
-description: Resolve the correct repository for a task — detect VCS platform, match ticket to repo, clone if missing. Run this in a sub-agent to avoid filling main context.
+description: [0.2.1] Resolve the correct repository for a task — detect VCS platform, match ticket to repo, clone if missing. Run this in a sub-agent to avoid filling main context.
 ---
 
 You are resolving which repository a task should be worked on. This skill handles VCS platform detection, scoped repo discovery, and cloning when needed.

devflow-plugin/commands/retain-learning.md

@@ -1,5 +1,5 @@
 ---
-description: Retain a new learning, discovery, or hard-won insight into Hindsight so it's available in future sessions.
+description: [0.2.1] Retain a new learning, discovery, or hard-won insight into Hindsight so it's available in future sessions.
 ---
 
 You need to retain a new learning into long-term memory via Hindsight.

devflow-plugin/commands/review-document.md

@@ -1,5 +1,5 @@
 ---
-description: Use when reviewing a prose document — KB article, RFC, spike, runbook, PRD, design doc, knowledge-base page — hosted on Google Docs, Confluence, a local file path, or an arbitrary URL. Checks correctness, internal consistency, audience-fit, prose clarity, and external-claim verification; cross-checks against existing platform comments to avoid re-flagging; returns severity-tagged findings with anchor + quote + concrete fix. Use when asked to "review this doc / KB / RFC / spike / runbook / PRD" and the target is prose, not a code diff. Counterpart to /devflow:write-spike. NOT for code diffs — use /devflow:review for those.
+description: [0.2.1] Use when reviewing a prose document — KB article, RFC, spike, runbook, PRD, design doc, knowledge-base page — hosted on Google Docs, Confluence, a local file path, or an arbitrary URL. Checks correctness, internal consistency, audience-fit, prose clarity, and external-claim verification; cross-checks against existing platform comments to avoid re-flagging; returns severity-tagged findings with anchor + quote + concrete fix. Use when asked to "review this doc / KB / RFC / spike / runbook / PRD" and the target is prose, not a code diff. Counterpart to /devflow:write-spike. NOT for code diffs — use /devflow:review for those.
 ---
 
 # /devflow:review-document — Multi-perspective prose document review

devflow-plugin/commands/review.md

@@ -1,5 +1,5 @@
 ---
-description: Use when reviewing a PR/MR by URL or the local working-tree diff — runs multi-perspective parallel agents (bug scanner, CLAUDE.md compliance, test coverage, plan alignment, git history, sibling MR/epic coherence) with confidence scoring and optional draft inline comments on the MR. Triggers for `/devflow:review` or any "review this PR/MR" request.
+description: [0.2.1] Use when reviewing a PR/MR by URL or the local working-tree diff — runs multi-perspective parallel agents (bug scanner, CLAUDE.md compliance, test coverage, plan alignment, git history, sibling MR/epic coherence) with confidence scoring and optional draft inline comments on the MR. Triggers for `/devflow:review` or any "review this PR/MR" request.
 ---
 
 # /devflow:review — Consolidated multi-perspective code review

devflow-plugin/commands/session-summary.md

@@ -1,5 +1,5 @@
 ---
-description: Generate a session summary for Langfuse tracing — capture what happened, decisions made, and metrics for observability.
+description: [0.2.1] Generate a session summary for Langfuse tracing — capture what happened, decisions made, and metrics for observability.
 ---
 
 You are generating a session summary for observability via Langfuse.

devflow-plugin/commands/spec-feature.md

@@ -1,5 +1,5 @@
 ---
-description: Spec a new feature — recall architecture knowledge, create a spec document, build an implementation plan, and break into tasks.
+description: [0.2.1] Spec a new feature — recall architecture knowledge, create a spec document, build an implementation plan, and break into tasks.
 ---
 
 You are speccing a new feature. This command enforces a structured planning process before any code is written.

devflow-plugin/commands/task-complete.md

@@ -1,5 +1,5 @@
 ---
-description: Mark a devflow task as done — update status, move to done/ folder, and retain learnings.
+description: [0.2.1] Mark a devflow task as done — update status, move to done/ folder, and retain learnings.
 ---
 
 You are completing a task from the devflow task backlog. This skill handles the lifecycle transition from in-progress/open to done.

devflow-plugin/commands/task-prioritize.md

@@ -1,5 +1,5 @@
 ---
-description: Reprioritize a devflow task — move between priority folders (P0-P4) and update frontmatter.
+description: [0.2.1] Reprioritize a devflow task — move between priority folders (P0-P4) and update frontmatter.
 ---
 
 You are reprioritizing a task in the devflow task backlog.

devflow-plugin/commands/update-visualizations.md

@@ -1,5 +1,5 @@
 ---
-description: Analyze recent changes and update affected architecture visualizations
+description: [0.2.1] Analyze recent changes and update affected architecture visualizations
 ---
 
 # Update Visualizations

devflow-plugin/commands/visualizations-config.md

@@ -1,5 +1,5 @@
 ---
-description: Configure visualization location, style presets, and output preferences
+description: [0.2.1] Configure visualization location, style presets, and output preferences
 ---
 
 # Configure Visualizations

devflow-plugin/commands/writing-plans.md

@@ -1,5 +1,5 @@
 ---
-description: Extends superpowers:writing-plans with devflow's phase-handoff at the end.
+description: [0.2.1] Extends superpowers:writing-plans with devflow's phase-handoff at the end.
 ---
 
 This skill extends `superpowers:writing-plans`. Follow the superpowers skill completely.

lib/release.sh

@@ -75,6 +75,13 @@ _parse_conventional_commits() {
   done < <(git -C "$project_dir" log "$log_target" --format='%B%x00' 2>/dev/null)
   IFS="$IFS_SAVE"
 
+  # Patch floor: any non-[skip release] merge that has commits cuts AT LEAST a
+  # patch, so docs/chore/refactor/etc. merges still release (keeps "merge =
+  # release"). The empty-range and [skip release] cases already returned "none".
+  if [[ "$bump" == "none" ]]; then
+    bump="patch"
+  fi
+
   # Output
   echo "$bump"
   [[ -n "$feat_msgs" ]] && printf "%b" "$feat_msgs"
@@ -143,11 +150,11 @@ bump_all_versions() {
     _sed_inplace "s/\"version\": \"[^\"]*\"/\"version\": \"${new_version}\"/" "$proj/devflow-plugin/.claude-plugin/marketplace.json"
   fi
 
-  # Command description badges: [devflow vX.Y.Z]
+  # Command description badges: [X.Y.Z] prepended to the description: line
   local cmd_file
   for cmd_file in "$proj"/devflow-plugin/commands/*.md; do
     [[ -f "$cmd_file" ]] || continue
-    _sed_inplace "s/\[devflow v[0-9][0-9]*\.[0-9][0-9]*\.[0-9][0-9]*\]/[devflow v${new_version}]/" "$cmd_file"
+    _sed_inplace "s/^description: \[[0-9][0-9]*\.[0-9][0-9]*\.[0-9][0-9]*\] /description: [${new_version}] /" "$cmd_file"
   done
 
   echo "All version files updated to ${new_version}"

lib/watch.sh

@@ -140,7 +140,7 @@ check_version_consistency() {
   for cmd_file in "$proj"/devflow-plugin/commands/*.md; do
     [[ -f "$cmd_file" ]] || continue
     local badge_ver
-    badge_ver="$(grep '\[devflow v' "$cmd_file" | head -1 | sed 's/.*\[devflow v//;s/\].*//' || true)"
+    badge_ver="$(grep -oE '^description: \[[0-9]+\.[0-9]+\.[0-9]+\]' "$cmd_file" | head -1 | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' || true)"
     if [[ -n "$badge_ver" ]] && [[ "$badge_ver" != "$makefile_version" ]]; then
       echo "MISMATCH: $(basename "$cmd_file") badge has $badge_ver (expected $makefile_version)" >&2
       mismatches=$((mismatches + 1))