Canonical PR description template for every PR shipped from this harness, with a validator that enforces the required sections. Use when opening or editing a PR (the /ship and /forge-ship steps), or when asked for the standard PR format or to check a PR body.
The English summary is being prepared. Showing the original description.
Review the instructions the agent will receive before you install.
The single source of truth for how every Agent Forge PR body is written. All ship paths
(/ship, /forge-ship, /forgemaster's ship phase) compose the PR body from this template and
validate it before gh pr create.
The template lives at references/pr-template.md — edit that file to change the standard; everything else references it.
Every PR body MUST contain these H2 headings, each filled (no leftover placeholders):
| Section | Holds |
|---|---|
## What Changed | The change in plain language + concrete edits |
## Why It's Needed | Motivation: the problem, need, or bug it addresses |
## How It Was Tested | Gates run, automated suites, manual steps |
## Test Evidence | Real proof — pasted command output / counts, not a claim |
## Risk & Rollback | Blast radius and the undo path |
## Linked Issues & AC Trace | Closes <beads-id> + acceptance-criterion → evidence table |
The first four are the harness baseline (what / why / how-tested / evidence). Risk & Rollback
and Linked Issues & AC Trace are the harness additions — they make a PR reviewable (knowable
blast radius) and traceable (every acceptance criterion mapped to evidence), matching the
Beads-first, test-evidence rules in CLAUDE.md.
cp .claude/skills/pr-description/references/pr-template.md .tmp/work/pr-body.md
Fill every section. For a /forge-ship run, the ship report (reports/<slug>-ship.md) already
contains the narrative and walkthrough — map it into the template sections rather than duplicating
prose. Paste actual test output into ## Test Evidence; never green-wash.
bun run .claude/skills/pr-description/scripts/check-pr-body.ts .tmp/work/pr-body.md
The validator emits { ok, data: { present, missing, empty }, error } and exits non-zero if any
required section is missing or left as a placeholder. Fix and re-run until ok: true.
gh pr create --base <base> --title "<title>" --body "$(cat .tmp/work/pr-body.md)"
# or, on an existing PR:
gh pr edit <n> --body "$(cat .tmp/work/pr-body.md)"
To check a PR that already exists:
gh pr view <n> --json body -q .body | bun run .claude/skills/pr-description/scripts/check-pr-body.ts -
## Test Evidence holds real output, not a promise.check-pr-body.ts reports ok: true.No reviews yet. Tell others what you thought.
No login needed. Share how it worked for you, ask a question, or note where it did not run.
No comments yet. Be the first to write one.
Capture free-text work as a tracked Beads issue. Use when the user runs /add-bead or wants to quickly file a Beads issue.
The English summary is being prepared. Showing the original description.
Register a new sub-repo in the knowledge base.
The English summary is being prepared. Showing the original description.
Add focused Bun unit tests for mission-critical behavior and edge cases — not blanket coverage.
The English summary is being prepared. Showing the original description.
Answer questions about the codebase from knowledge files. Use when the user runs /ask or asks a domain/knowledge question about the repos.
The English summary is being prepared. Showing the original description.
Meta-skill for creating Agent Forge skills under .claude/skills/ with SKILL.md, optional references/ and scripts/, and Bun scaffolds. Use when the user wants to add or author a skill, scaffold a new skill folder, or align skill docs with harness conventions (JSON script output, Beads for tasks).
The English summary is being prepared. Showing the original description.
Choose Beads issue priority (P0–P4, numeric, or named) from urgency, impact, and risk when creating or triaging work.
The English summary is being prepared. Showing the original description.