Repository navigation
Agent surface: document the standing-PR body as an interface, plus AGENTS.md snippet and safety docs #549
Description
From the July 2026 direction review (§1.3b). The MCP question was investigated and answered: no MCP server (ADR-0002) — the agent surface is the CLI contract (#544) plus the items here.
Rescoped from "ship a releasekit skill". Review found the skill was the weakest item in the original scope and the strongest one was unstated. The ordering is now docs → snippet → skill, so each step is justified by the one before it rather than assumed.
Gap
The standing-PR body is not prose. Marker-delimited regions in it are machine inputs read back at publish time:
| Marker | What an edit does |
|---|---|
<!-- releasekit-notes --> … <!-- releasekit-notes-end --> (keyed :<pkg> when multi-package) |
Text inside overrides the generated release notes — extractNotesRegions → editedNotes, applied in both standing-pr update and publishFromManifest |
<!-- rk-sel:NAME --> |
The row's [x]/[ ] glyph decides whether that package releases |
<!-- rk-pre:NAME --> |
Ship that package as a prerelease |
<!-- rk-grad:NAME --> |
Graduate that package off its prerelease line |
<!-- releasekit-manifest ... --> |
Bot-owned. Drives the entire publish; author-bound and validated against source |
An agent that tidies the PR body, reflows the markdown, or strips HTML comments silently changes what ships or destroys a region. Agents edit PR bodies constantly, and the damage is invisible in review — the prose still reads correctly.
Nothing in docs/ says the body is an interface. Standing PRs are referenced across the docs, but no page states where a human or agent may write, what an edit does, and what is bot-owned.
This gap is not what the original scope led with. "What an agent must never do" (publish directly, create tags) is enforced by branch rulesets + OIDC + CI-publishes — advisory text adds nothing there.
Scope
- Docs page — the standing-PR body as an interface. The editable regions, what each edit does at publish time, what must be preserved (marker comments; the glyph is the only thing a human toggles), and what is bot-owned and will be overwritten on the next update run. Serves humans as much as agents; this is the load-bearing deliverable.
- AGENTS.md snippet (~10 lines) consumers paste into their own
AGENTS.md, pointing at (1). Highest value per byte — it is what an agent actually reads before touching a release PR. - Agent-safety docs. The boundary: agent proposes (feeder PRs / standing-PR edits) → human approves (merge, enforced by rulesets) → CI publishes via OIDC with short-lived tokens. releasekit's standing-PR mode is already the topology the post-incident security literature converged on; say so explicitly.
- Positioning. A short "why not have an AI write your release script?" section with the incident receipts — Ultralytics, s1ngularity, GhostAction were all bespoke release workflows; npm's classic-token revocation broke every pre-Dec-2025 hand-rolled script silently.
Deferred — not in this issue's DoD
- A
SKILL.md. Ship only if (1)+(2) prove insufficient in practice. The sampo precedent doesn't transfer: sampo needs a skill because changesets requires authoring a file in a bespoke format; releasekit is commit-first on conventional commits, which agents already know. Re-open as its own issue if the validation below says otherwise.
Validation
Dogfood against the real consumers (wdio-desktop-mobile, zubridge): let an agent work a repo with an open standing PR, with (1)+(2) in place, and see whether it damages a region. That observation — not assumption — decides whether (5) ships.
Non-goal
An MCP server — see ADR-0002.
Activity
[-]Agent surface: ship a releasekit skill, AGENTS.md snippet, and agent-safety docs[/-][+]Agent surface: document the standing-PR body as an interface, plus AGENTS.md snippet and safety docs[/+]