254 lines
8.9 KiB
Markdown
254 lines
8.9 KiB
Markdown
%{
|
|
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 projects. This is the second project I have used it in. It helped me earlier do a fairly large architectural spike for an enterprise client, 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: "<feature-name> [--scenario <description>] [--plan <path>]"
|
|
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: `<feature-name>` (required) — short name or description of the feature to demo
|
|
- `--scenario <description>`: Explicit demo scenario describing what to show. If omitted, infer from the plan and recent commits.
|
|
- `--plan <path>`: 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)-<slug>.md" "Demo: <Feature Name>"
|
|
```
|
|
|
|
Store the demo file path for use in all subsequent steps.
|
|
|
|
### 6. Narrative introduction
|
|
|
|
```bash
|
|
showboat note <demo-file> "## Feature Overview
|
|
|
|
<2-3 sentence description derived from the plan or commits.>
|
|
|
|
**Branch**: $(git branch --show-current)
|
|
**Commits**: <N> commits ahead of main
|
|
**Plan**: <plan file path or 'none'>
|
|
"
|
|
```
|
|
|
|
### 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 <demo-file> "## Test Suite"
|
|
showboat exec <demo-file> bash "mix test <relevant-test-files> --color"
|
|
showboat note <demo-file> "All <N> tests pass, confirming <specific criterion>."
|
|
```
|
|
|
|
**Compilation check**:
|
|
```bash
|
|
showboat note <demo-file> "## Compilation Check"
|
|
showboat exec <demo-file> bash "mix compile --warnings-as-errors"
|
|
```
|
|
|
|
**Database state** (if relevant to the feature):
|
|
```bash
|
|
showboat note <demo-file> "## Database State"
|
|
showboat exec <demo-file> bash "mix run -e '<query expression>'"
|
|
```
|
|
|
|
### 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/<route>
|
|
rodney waitidle
|
|
rodney screenshot demos/screenshots/<feature>-<page-name>.png
|
|
|
|
showboat note <demo-file> "### <Page Name>
|
|
|
|
<What this page shows and why it proves the feature works.>"
|
|
|
|
showboat image <demo-file> ''
|
|
```
|
|
|
|
**Interactive flow** (form submissions, navigation):
|
|
```bash
|
|
showboat note <demo-file> "### Interactive Flow: <Flow Name>"
|
|
|
|
# Before state
|
|
rodney screenshot demos/screenshots/<feature>-before.png
|
|
showboat image <demo-file> ''
|
|
|
|
# Perform interaction
|
|
rodney click "<selector>"
|
|
rodney input "<selector>" "<value>"
|
|
rodney click "<submit-selector>"
|
|
rodney waitidle
|
|
|
|
# After state
|
|
rodney screenshot demos/screenshots/<feature>-after.png
|
|
showboat image <demo-file> ''
|
|
```
|
|
|
|
### 9. Acceptance criteria checklist
|
|
|
|
If a plan file exists, map each acceptance criterion to evidence:
|
|
|
|
```bash
|
|
showboat note <demo-file> "## Acceptance Criteria Verification
|
|
|
|
- [x] <Criterion 1> -- see Test Suite output above
|
|
- [x] <Criterion 2> -- see <Page Name> screenshot
|
|
- [x] <Criterion 3> -- 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/<filename>.md
|
|
- **Screenshots**: <N> captured in demos/screenshots/
|
|
- **Evidence**: <N> backend commands, <N> UI screenshots
|
|
- **Acceptance criteria**: <N>/<M> 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`)
|