Conversation
|
|
I manually ran through the test plan and all 5 items pass:
@statik Can we mark this as ready for review? |
|
@ian-flores thanks for looking at this! marked as ready |
|
@ian-flores I'm not sure I agree with the agent on not committing the demo.md - I think I want to start tracking plans/specs/demos somewhere in the repo. But, since I haven't come up with a design for that, I scoped this PR to not commit the demo.md |
There was a problem hiding this comment.
Pull request overview
This PR integrates “showboat” demo creation/verification into the agent workflow and CI, aiming to make changes verifiable via reproducible demo transcripts.
Changes:
- Documented a showboat-based demo workflow for coding agents in
AGENTS.md(and addedCLAUDE.mdcompatibility). - Added a new CI job (
verify-demo) to runshowboat verify demo.mdon pull requests when a demo is present. - Added convenience
justrecipes and updated setup/ignores to support demo usage.
Reviewed changes
Copilot reviewed 5 out of 6 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
justfile |
Adds demo-init / demo-verify helpers for showboat demos. |
CLAUDE.md |
Adds Claude Code compatibility by pointing to AGENTS.md. |
AGENTS.md |
Documents the expected showboat demo workflow and CI verification behavior. |
.gitignore |
Ignores demo.md (intended to avoid accumulation). |
.github/workflows/copilot-setup-steps.yml |
Installs showboat in the Copilot Agent setup environment. |
.github/workflows/ci.yml |
Adds verify-demo job to verify demos on PRs when demo.md exists. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| After completing work on a branch, create a showboat demo that proves | ||
| your changes work. The demo file is committed to the branch and its | ||
| contents are pasted into the PR body under a `## Demo` heading. | ||
|
|
||
| ### Getting started | ||
|
|
||
| Run `uvx showboat --help` at the start of a session to learn the tool. | ||
|
|
||
| ### Creating a demo | ||
|
|
||
| ```bash | ||
| uvx showboat init demo.md "Feature: <title>" | ||
| uvx showboat note demo.md "Explanation of what was done..." | ||
| uvx showboat exec demo.md bash "uv run pytest selftests/ -v" | ||
| uvx showboat exec demo.md bash "just check" | ||
| ``` | ||
|
|
||
| Use `uvx showboat image demo.md <path>` if screenshots are relevant. | ||
|
|
||
| ### What to demonstrate | ||
|
|
||
| - **New tests:** run the new tests and show them passing | ||
| - **New features:** exercise the feature with concrete examples | ||
| - **Bug fixes:** show the fix in action (before/after if feasible) | ||
| - **Refactors:** show that existing tests still pass | ||
| - **Always** include `just check` (lint/format) output | ||
|
|
||
| ### Before committing | ||
|
|
||
| ```bash | ||
| uvx showboat verify demo.md | ||
| ``` | ||
|
|
||
| Verification re-runs all `exec` blocks and confirms output matches. | ||
| If it fails, fix the demo before committing. | ||
|
|
||
| ### PR workflow | ||
|
|
||
| 1. Commit `demo.md` to the branch root | ||
| 2. Paste the contents of `demo.md` into the PR body under `## Demo` | ||
|
|
||
| CI will run `showboat verify demo.md` on PRs that include the file. |
There was a problem hiding this comment.
This section says demo.md should be committed to the branch root and will be verified in CI, but demo.md is also added to .gitignore in this PR. As written, most contributors won’t be able to git add demo.md without -f, and the CI job will usually skip because the file won’t be present in the checkout. Please reconcile the intended workflow (commit vs. don’t commit) and update these instructions accordingly.
| with: | ||
| enable-cache: true | ||
| - name: Install dependencies | ||
| run: uv sync |
There was a problem hiding this comment.
uv sync here likely won’t install the tooling that the recommended demo commands run (e.g., just check depends on ruff, which is only in the dev extra per pyproject.toml). If demos follow the AGENTS.md guidance, showboat verify will fail in CI due to missing tools. Consider using uv sync --all-extras (or at least --extra dev) for this job, and consider pinning/choosing a specific Python version (like the selftest matrix) to avoid ubuntu-latest Python drift affecting verification.
| run: uv sync | |
| run: uv sync --all-extras --python 3.12 |
| - name: Verify demo | ||
| if: steps.check.outputs.found == 'true' | ||
| run: uvx showboat verify demo.md |
There was a problem hiding this comment.
The suggested demo flow in AGENTS.md includes running just check, but this job doesn’t install just. Since showboat verify re-runs exec blocks, any demo that follows the documented guidance will fail in CI on the first just invocation. Either add an installation step for just (e.g., via apt) before verification, or update the recommended demo commands to avoid just in CI-verifiable demos.
| - name: Install showboat | ||
| run: pip install showboat |
There was a problem hiding this comment.
This installs showboat via bare pip (and unpinned), which conflicts with the repo guidance to run tooling through uv and makes the setup less reproducible over time. Consider installing uv in this workflow and then installing/pinning showboat via uv tool install/uvx --from (or otherwise pinning the showboat version) so the Copilot Agent environment matches how demos are run in CI (uvx showboat …).
| - name: Install showboat | |
| run: pip install showboat | |
| - name: Install uv | |
| run: | | |
| curl -LsSf https://astral.sh/uv/install.sh | sh | |
| - name: Install showboat via uv | |
| run: | | |
| export PATH="$HOME/.local/bin:$PATH" | |
| uv tool install showboat==0.5.0 |
| verify-demo: | ||
| name: Verify showboat demo | ||
| if: github.event_name == 'pull_request' | ||
| runs-on: ubuntu-latest |
There was a problem hiding this comment.
Since showboat verify executes arbitrary commands from demo.md, this job can hang or run unexpectedly long (intentionally or accidentally). Consider setting a timeout-minutes on the job or the verify step to keep CI usage bounded, especially because this runs on all pull requests that include a demo.
| runs-on: ubuntu-latest | |
| runs-on: ubuntu-latest | |
| timeout-minutes: 10 |
Summary
AGENTS.mdso coding agents create verifiable demos of their workverify-demoCI job that runsshowboat verify demo.mdon PRs (skips cleanly when no demo is present)copilot-setup-steps.yml)demo.mdto.gitignoreso demos don't accumulate on mainjust demo-initandjust demo-verifyconvenience recipesCLAUDE.mdtoAGENTS.mdfor Claude Code compatibilityTest plan
uvx showboat verify demo.mdand confirm it passesverify-demoCI job runs on this PR and skips (no demo.md committed)demo.mdis in.gitignore