Skip to content

docs(agents): attach PR images with gh --attach and adopt the Pwr family's PR conventions - #11

Merged
Harold Hunt (huntharo) merged 1 commit into
mainfrom
docs/agent-guidance
Oct 30, 2026
Merged

Harold Hunt (huntharo) merged 1 commit into
mainfrom
docs/agent-guidance

Conversation

@huntharo

Copy link
Copy Markdown

Brings PwrDisk's agent guidance up to the Pwr family's conventions. Above all, PR screenshots and videos are now attached with gh --attach. A previous agent here believed gh could not upload images and hosted them on a side branch, so the rule is linked from the top of AGENTS.md.

What changed

  • AGENTS.md: a pointer under the intro ("Opening a PR? Read Pull requests first"), and three new sections at the end. The working contract, house rules, invariants and the "where changes belong" table are untouched.
    • Pull requests: gh --attach, never a side branch, gist or commit; before/after screenshots of a contrived tree; scans are private data (user names in paths, volume names, the chooser's mounts and SSH hosts), and anything not contrived goes to the operator first; Conventional Commit titles with PwrDisk scopes and the (port of tobi/disktree#N) suffix the fork's ports already use; no CHANGELOG.md edits in feature PRs; push only to pwrdrvr/PwrDisk.
    • PwrAgent threads: check that the workspace holds the PR's head before attaching; attach the PR and watch it with notifyOn: ["merged", "closed"]; deferred work goes on an add_todo card, not into the PR body; reuse an open PwrDisk window.
    • Agent instruction files: guidance lives in the smallest AGENTS.md that needs it, long procedures go in docs/, and every AGENTS.md has a CLAUDE.md symlink.
  • CLAUDE.md: a symlink to AGENTS.md, as in PwrGit, PwrRoute and PwrAgent.
  • docs/pr-screenshots.md (new): how to make screenshots without leaking a real disk, and the full --attach procedure.
    • Making them: a fixture tree with invented names, written with real bytes because sizes come from allocated blocks. It can sit on a disk image named Fixtures so the status bar doesn't show the real volume. The app is run as pwrdisk <root>, which skips the chooser, and "before" comes from main in a second worktree.
    • Attaching them: byte-identical paths in the body and in --attach; fetching the live body with gh pr view <n> --json body -q .body before every later edit; a loop that checks each image link is a user-attachments URL that returns HTTP 200 with the right size.
    • I ran the fixture and link-check snippets on macOS. The check came back 200 for both of macOS: Icon Composer bundle icon and a Dock icon for unbundled runs (port of tobi/disktree#103) #7's images.

Ported from

Convention From
gh --attach, the three silent failures, the link check, the routes table's shape PwrGit docs/pr-screenshots.md, PwrAgent AGENTS.md › Pull Requests
Short pointer in AGENTS.md, full procedure in docs/ PwrGit, PwrRoute
Contrived data; show non-contrived images to the operator first PwrGit, PwrAgent, PwrRoute (whose "URLs are private data" became "scans are private data")
Conventional Commit titles with scopes PwrAgent, plus PwrRoute's and PwrGit's history
No CHANGELOG.md in feature PRs; release prep writes it PwrRoute
Attach the PR and watch with notifyOn: ["merged", "closed"] PwrRoute, PwrAgent
Deferred work on add_todo cards PwrAgent › Deferred work
Reuse an open window before launching PwrRoute › Launch the app, PwrGit
CLAUDE.md → AGENTS.md, smallest scope, procedures in docs/ All three

Left out

  • Node, nvm, pnpm and Electron setup and launch rules (PwrGit, PwrAgent).
  • Sandboxer verification. PwrDisk has no sandbox snapshot, so cargo xtask lint still runs locally. Only the notifyOn watch rule came over.
  • Release, packaging, signing, icon and license-gate sections. The Velopack + DMG PR (feat(release): ship a DMG and Velopack installers with in-app updates #8) and the signing-environment work own those, and this PR doesn't touch release docs.
  • PwrAgent's product direction, SQLite budgets, command-output and Codex data-boundary rules, and PwrRoute's crate map. They're specific to those apps.

Reconcile with #8

#8 adds CHANGELOG.md, and its docs/releasing.md says to "move CHANGELOG.md's Unreleased entries" under the version heading. This PR says feature PRs don't edit the changelog and the release-prep PR writes the section. The two fit if release prep writes the entries and then moves them, but whichever PR lands second should make releasing.md say who writes them. The new sections sit at the end of AGENTS.md, away from the Commands block and table rows #8 edits, so the two should merge cleanly.

Verified

  • cargo xtask lint passes. This PR only changes docs.
  • No UI changes, so no screenshots.

…ily's PR conventions

Ports the PR, screenshot, PwrAgent-thread and agent-file conventions from PwrRoute, PwrAgent and PwrGit. A previous agent hosted screenshots on a side branch because it believed gh could not upload them; the gh --attach procedure is now linked from the top of AGENTS.md.
@huntharo
Harold Hunt (huntharo) merged commit 3102ea6 into main Oct 30, 2026
6 checks passed
@huntharo
Harold Hunt (huntharo) deleted the docs/agent-guidance branch November 9, 2026 03:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant