// Write engaging PR titles and descriptions for any forge (GitHub today; Bitbucket planned). Use when creating or updating PRs. Leads with narrative paragraphs and reaches for lists, tables, and diagrams when content is genuinely structured.
| name | forge-pr |
| description | Write engaging PR titles and descriptions for any forge (GitHub today; Bitbucket planned). Use when creating or updating PRs. Leads with narrative paragraphs and reaches for lists, tables, and diagrams when content is genuinely structured. |
Write PR descriptions that fellow devs actually want to read. The writing guidance below is forge-agnostic — only the gh commands in the "Updating existing PRs" section are GitHub-specific today. Bitbucket support is tracked in srid/agency#10.
foo parameter to bar function")Title: Short, specific, interesting. Convey what changed from a user/dev perspective, not which files were touched. Use imperative mood. Under 70 chars.
Body: Open with a paragraph. Structure:
Opening paragraph — What this PR does and why, in 2-3 sentences. Bold the key behavioral change. If there's a motivating problem, state it directly.
Details — paragraph(s), bullet list, table, or fenced diagram, whichever fits the shape of the content (see Use structure when content is structured below). Only include if the approach is non-obvious, has trade-offs worth calling out, or has discrete moving parts that benefit from being shown rather than described. Use italics for subtle points; keep it high-level.
Anything notable — Breaking changes, migration steps, or things reviewers should pay attention to. Only if applicable. Use > blockquote for callouts.
Narrative is the right tool for the opening "what changed and why" paragraph and for asides — but the moment you find yourself writing "three loaders", "two refinements landed", or "the data passes through X then Y then Z", that's structure asking to be made visible. A comma-separated list of five features in prose is harder to scan than five bullets; a table beats a paragraph that says "previously Foo did X, now it does Y, and Bar previously did Z, now it does W."
Reach for these when they earn their keep:
### subheaders — break long bodies into navigable sections (still avoid generic ## Summary / ## Changes)The rule is use structure when content is structured, not always add structure. A small PR with one paragraph of motivation is fine; don't reach for a table just to look thorough.
### subheaders are fine to break up long bodies; skip generic ## Summary / ## Changes headersCloses #123, See #456)End every PR body with a one-line italic footer naming:
/do), linked to its source repo (https://github.com/srid/agency),Claude Code, Codex, opencode), andclaude-opus-4-7, gpt-5-codex).Reviewers should be able to tell at a glance what produced the diff:
Generated by
/doon Claude Code (modelclaude-opus-4-7).
Use the values that are actually executing this run — do not guess or fabricate. If you genuinely cannot identify one of agent/model, write unknown rather than omitting the footer. If the PR is being written without an invoking workflow (forge-pr loaded directly, no /-command), drop the workflow phrase and lead with _Generated by Claude Code (model claude-opus-4-7)._. When updating an existing PR (see Updating existing PRs) and the current run's agent or model differs from what's already in the body, edit the existing footer in place rather than appending a second one.
If the repo is a GitHub Nix flake and the PR branch contains a buildable output (package, NixOS config, etc.), include a "Try it locally" section at the end of the body. Use the GitHub owner/repo and branch name to construct the command, and put it in a fenced sh code block (not inline backticks) so GitHub renders a copy button and the command doesn't line-wrap awkwardly:
### Try it locally
```sh
nix run github:<owner>/<repo>/<branch>
```
Adjust the command as needed — nix build for non-runnable outputs, add #<output> if the default package isn't the relevant one. Omit this section entirely if the change isn't meaningfully testable via nix run/build (e.g., CI-only changes, documentation, non-Nix repos, or non-GitHub forges where flake refs would be awkward).
gh safelyMANDATORY: Always pass --body to gh pr create / gh pr edit / gh pr comment via a single-quoted heredoc so backticks, $, and ! survive unescaped. Double-quoted --body "..." triggers shell command substitution on backticks, and escaping them with ``` produces literal backslashes in the rendered PR (breaking code fences — see juspay/kolu#402).
gh pr create --draft --title "..." --body "$(cat <<'EOF'
...body with ```sh fenced blocks``` intact...
EOF
)"
The 'EOF' (quoted delimiter) is load-bearing — it disables interpolation inside the heredoc. Never write backticks in the body as ```.
When the user pushes further changes to an already-PR'd branch:
gh pr edit on GitHub)Title: Update NixOS configuration and add new service
## Summary
- Added `kolu` service configuration
- Updated `flake.lock`
- Modified port from 8080 to 8090
- Added health check endpoint
- Updated README
## Testing
- Tested locally
Title: Add kolu service with health monitoring
**Kolu now runs as a standalone NixOS service** with its own systemd
unit and a dedicated health-check endpoint. Previously it was bolted
onto the main app process, which made restarts disruptive.
The service binds to port 8090 to avoid clashing with the dev server.
*Health checks hit `/healthz` every 30s — systemd restarts the
service on three consecutive failures.*
When the change has a flow, several discrete features, and a couple of before/after refinements, show those instead of writing them out as prose:
Title: Export agent session as a self-contained HTML file
**Kolu can now export the active agent session as a portable,
self-contained HTML file** — Claude Code, OpenCode, or Codex, no
matter which one is running. The server reads the on-disk transcript,
normalizes it through a unified vendor-opaque IR, and ships back one
HTML document the browser opens in a new tab.
### How it fits together
```
Claude JSONL ─┐
OpenCode SQLite ─┼─▶ loader ─▶ TranscriptEvent[] ─▶ renderer ─▶ HTML
Codex rollout ─┘ (discriminated union)
```
The IR (`Transcript` in `anyagent/schemas`) is the key seam. The
renderer dispatches **only** on `event.kind` — never on `agentKind`.
_Adding a fourth integration is one new loader plus one `match` arm._
### What you get in the exported page
- **Header pills** — agent name, model, context-token count, PR link
- **Hide tools** — collapses tool-call cards for narrative reading
- **Theme** — cycles auto → light → dark
- **<kbd>j</kbd>/<kbd>k</kbd> nav** — jump between user prompts
- **Per-event icons** — person, robot, brain, wrench
### Refinements during review
| What was off | Fix |
| --- | --- |
| Claude loader threw `ENOENT` for new sessions; OpenCode/Codex returned `null` | All three loaders return `Transcript \| null` uniformly |
| OpenCode loader did per-message N+1 SQLite fetches | Collapsed into one ordered `LEFT JOIN` (~501 statements → 1) |
> _No streaming, by design — end-of-session export reads the whole
> transcript in one pass._
The flow diagram replaces a paragraph that would have to enumerate "Claude JSONL, OpenCode SQLite, Codex rollout — all converge on a single loader interface...". The bullet list replaces a comma-jammed sentence. The table replaces "Two refinements landed: first, the Claude loader used to throw...; second, the OpenCode loader collapsed...". Each structural element is doing work prose couldn't do as cleanly.
Do a task end-to-end — implement, PR, CI loop, ship. ONLY invoke when the user explicitly types `/do` or `$do`; never auto-select from a natural-language request, even one that sounds like an end-to-end task.
Enter talk mode — conversation and research, no repo changes. ONLY invoke when the user explicitly types `/talk` or `$talk`; never auto-select from a natural-language question or design discussion.
Evaluate code (especially LLM-generated) for structural simplicity using Rich Hickey's "Simple Made Easy" framework. Use this skill whenever reviewing a PR, diff, or code snippet for accidental complexity — particularly when the code was generated by an AI coding assistant and line-by-line review isn't feasible. Also use when the user asks about complecting, simplicity vs. easiness, structural coupling, or concept deduplication. Trigger on phrases like "is this simple", "does this complect", "review for complexity", "structural analysis", or any reference to Hickey, Simple Made Easy, or grey-box review.
Evaluate architecture and module boundaries for volatility-based decomposition using Juval Lowy's framework (from "Righting Software", building on Parnas 1972). Use when reviewing module splits, service boundaries, new abstractions, or any decomposition decision. Trigger on phrases like "where should this boundary be", "how to split this", "module boundaries", "encapsulate change", "volatility", or references to Lowy, Parnas, or "Righting Software". Complements /hickey (interleaved concerns) with a different lens (change encapsulation).
Review code for quality, simplicity, and common mistakes before declaring work complete.
Iterative measurement-driven improvement loop. Measure, profile, mutate, re-measure, commit. Works for performance, bundle size, complexity, test coverage — anything quantifiable. Use when the user wants to systematically improve a metric through repeated cycles of profiling and targeted changes.