diff --git a/app/priv/blog/engineering/2026/04-02-automated-release-notes-with-showboat.md b/app/priv/blog/engineering/2026/04-02-automated-release-notes-with-showboat.md new file mode 100644 index 0000000..c8c3728 --- /dev/null +++ b/app/priv/blog/engineering/2026/04-02-automated-release-notes-with-showboat.md @@ -0,0 +1,253 @@ +%{ + title: "Automated release notes with 'demo' skill", + author: "Willem van den Ende", + tags: ~w(ai), + description: "Agents can make release notes, given the right tools and instructions. Showboat, Chrome DevTools MCP were quite easy to use. ", + published: true +} +--- + +Yesterday, I added scheduled posts to firehose. I let my coding agent write the [release notes](blog/releases/scheduled-publishing). It is fun to read the release notes like this, and see the screenshots. Do note that a coding agent might not care there is no navigation - it happily will remember the urls and navigate to them, so that is something you might want to double check with exploratory testing :-). + +I've included the full skill below. It is not in the repository, it went straight to my home directory so I can use it in other porjects. This is the second project I have used it in. It helped me earlier do a fairly large archiectural spike for an RFP response, and include screenshots of a working application in the response document. Working software is still a great measure of progress. + +# Demo skill - let your agent generate demos with screenshots for you + +--- +name: demo +description: >- + Generate a living demo document proving a feature works. Uses showboat + for Markdown assembly with captured command output and rodney for Chrome + browser screenshots. Use when the user says "demo this", "show me it works", + "create a demo", or after /build completes. +argument-hint: " [--scenario ] [--plan ]" +user-invocable: true +allowed-tools: Read, Write, Glob, Grep, Bash +--- + +# Demo + +Role: worker. This command generates a standalone Markdown demo document that proves a feature works, using showboat for document assembly and rodney for browser automation. + +You have been invoked with the `/demo` command. + +## Parse Arguments + +Arguments: $ARGUMENTS + +- Positional: `` (required) — short name or description of the feature to demo +- `--scenario `: Explicit demo scenario describing what to show. If omitted, infer from the plan and recent commits. +- `--plan `: Path to the plan file. If omitted, search `plans/` for the most recently modified `.md` file with status `implemented` or `approved`. + +## Steps + +### 1. Check tool availability + +Verify showboat and rodney are installed: + +```bash +showboat --help 2>/dev/null && echo "showboat: ok" || echo "showboat: missing" +rodney --help 2>/dev/null && echo "rodney: ok" || echo "rodney: missing" +``` + +If either tool is missing, tell the user: + +> One or more demo tools are missing. Install them with: +> ```bash +> go install github.com/simonw/showboat@latest +> go install github.com/simonw/rodney@latest +> ``` + +Do not proceed until both tools are confirmed available. + +### 2. Gather feature context + +Build an understanding of what to demo from these sources (in priority order): + +1. **Explicit scenario** (`--scenario`): If provided, use as primary guide. +2. **Plan file**: Read the plan's Goal, Acceptance Criteria, and completed Steps. +3. **Recent commits**: Run `git log --oneline -15` and `git diff main...HEAD --stat` to identify changed files and commit messages. +4. **Route map**: Cross-reference changed files against known LiveView routes in the router (`lib/hub_web/router.ex`). + +From these sources, produce a **demo outline**: +- **Narrative**: 2-3 sentence description of what the feature does +- **Backend evidence**: mix commands, test output, or database queries to run +- **UI pages**: which routes to visit and what to look for +- **Interactions**: any clicks, form fills, or navigation sequences to perform + +If no plan exists and commits are ambiguous, ask the user for a brief description of what to demo. + +### 3. Check dev server + +```bash +curl -s -o /dev/null -w "%{http_code}" http://localhost:4000/ 2>/dev/null +``` + +If the server is not reachable: + +> The Phoenix dev server is not running. Start it now? +> ```bash +> mix phx.server & +> ``` + +After starting, wait up to 10 seconds and verify connectivity. If it still fails, proceed with backend-only evidence (skip all browser screenshots) and note the limitation in the demo document. + +### 4. Handle authentication + +The app requires authentication for LiveView routes. Before capturing UI screenshots: + +1. Ensure a demo user exists: + ```bash + mix run -e " + alias Hub.Accounts + case Accounts.get_user_by_email(\"demo@example.com\") do + nil -> Accounts.register_user(%{email: \"demo@example.com\", password: \"demodemo1234\"}) + user -> {:ok, user} + end + " + ``` + +2. Log in via rodney: + ```bash + rodney start + rodney open http://localhost:4000/users/log-in + rodney wait "input[name='user[email]']" + rodney input "input[name='user[email]']" "demo@example.com" + rodney input "input[name='user[password]']" "demodemo1234" + rodney click "button[type='submit']" + rodney waitidle + ``` + +If login fails, warn and proceed with backend-only evidence. + +### 5. Initialize the demo document + +Slugify the feature name (lowercase, hyphens, no special chars). Then: + +```bash +showboat init "demos/demo-$(date +%Y%m%d-%H%M%S)-.md" "Demo: " +``` + +Store the demo file path for use in all subsequent steps. + +### 6. Narrative introduction + +```bash +showboat note "## Feature Overview + +<2-3 sentence description derived from the plan or commits.> + +**Branch**: $(git branch --show-current) +**Commits**: commits ahead of main +**Plan**: +" +``` + +### 7. Backend evidence + +Capture backend proof via `showboat exec`. Always include relevant tests. Add narrative notes between evidence blocks explaining what each proves. + +**Test output** (always include): +```bash +showboat note "## Test Suite" +showboat exec bash "mix test --color" +showboat note "All tests pass, confirming ." +``` + +**Compilation check**: +```bash +showboat note "## Compilation Check" +showboat exec bash "mix compile --warnings-as-errors" +``` + +**Database state** (if relevant to the feature): +```bash +showboat note "## Database State" +showboat exec bash "mix run -e ''" +``` + +### 8. UI screenshots + +For each UI page identified in step 2, navigate with rodney, screenshot, and embed via showboat. + +**Static page capture**: +```bash +rodney open http://localhost:4000/ +rodney waitidle +rodney screenshot demos/screenshots/-.png + +showboat note "### + +" + +showboat image '![](demos/screenshots/-.png)' +``` + +**Interactive flow** (form submissions, navigation): +```bash +showboat note "### Interactive Flow: " + +# Before state +rodney screenshot demos/screenshots/-before.png +showboat image '![Before: ](demos/screenshots/-before.png)' + +# Perform interaction +rodney click "" +rodney input "" "" +rodney click "" +rodney waitidle + +# After state +rodney screenshot demos/screenshots/-after.png +showboat image '![After: ](demos/screenshots/-after.png)' +``` + +### 9. Acceptance criteria checklist + +If a plan file exists, map each acceptance criterion to evidence: + +```bash +showboat note "## Acceptance Criteria Verification + +- [x] -- see Test Suite output above +- [x] -- see screenshot +- [x] -- see Database State output +" +``` + +If no plan, summarize what was demonstrated and what it proves. + +### 10. Clean up + +```bash +rodney stop 2>/dev/null || true +``` + +### 11. Report results + +Display: +``` +## Demo Complete + +- **Document**: demos/.md +- **Screenshots**: captured in demos/screenshots/ +- **Evidence**: backend commands, UI screenshots +- **Acceptance criteria**: / demonstrated +``` + +## Error Handling + +- **Tools not installed**: Show `go install` commands. Do not proceed without them. +- **Dev server not running**: Offer to start. If startup fails, produce backend-only demo and note the limitation. +- **Authentication failure**: Proceed with backend-only evidence. Note skipped UI screenshots in the document. +- **Screenshot failure**: Log the error as a note in the demo document, continue with remaining screenshots. +- **No plan found**: Infer from git commits and changed files. Ask the user for a description if commits are ambiguous. +- **Rodney/Chrome crash**: Run `rodney stop` then `rodney start` to reset. Retry once. If it fails again, degrade to backend-only. + +## Integration + +- `/build` can suggest running `/demo` after a successful build +- `/pr` can invoke `/demo` to generate evidence before or after PR creation +- `/plan` produces the acceptance criteria this command verifies visually +- Beads (`bd`) can reference demo documents as task completion evidence +- Reads plan files from `plans/` directory (same format as `/build`) diff --git a/scripts/new-post.sh b/scripts/new-post.sh new file mode 100755 index 0000000..c0ee59c --- /dev/null +++ b/scripts/new-post.sh @@ -0,0 +1,48 @@ +#!/usr/bin/env bash +set -euo pipefail + +usage() { + echo "Usage: $0 \"Post Title\" [blog]" + echo " blog: engineering (default) or release-notes" + exit 1 +} + +[[ $# -lt 1 ]] && usage + +title="$1" +blog="${2:-engineering}" + +# Title to slug: lowercase, spaces/underscores to hyphens, strip non-alphanumeric +slug=$(echo "$title" | tr '[:upper:]' '[:lower:]' | tr ' _' '-' | sed 's/[^a-z0-9-]//g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//') + +year=$(date +%Y) +month_day=$(date +%m-%d) +dir="app/priv/blog/${blog}/${year}" +file="${dir}/${month_day}-${slug}.md" + +# Find repo root +cd "$(dirname "$0")/.." + +mkdir -p "$dir" + +if [[ -f "$file" ]]; then + echo "File already exists: $file" + exit 1 +fi + +cat > "$file" <