docs(cli): require /printing-press-publish skill for CLI publish PRs (#1145)

403341c7f1f6e25892c7aa43326db9a45ad8f582 · 2026-05-11 21:16:02 -0700 · Trevin Chow

* docs(cli): require /printing-press-publish skill for CLI publish PRs

Agents running /printing-press in this repo have been hand-rolling
publish PRs against the public library, skipping the preflight checks
that /printing-press-publish enforces. The public library's own
AGENTS.md isn't loaded because the agent's CWD is cli-printing-press,
so those rules are invisible unless the skill is the entry point.

Add a "Publishing to the Public Library" section to AGENTS.md scoping
the rule to "publishing a generated CLI" (not all PRs against that
repo) and pointing at /printing-press-publish as the only supported
flow. Phrase the prohibitions about improvising the flow rather than
the specific gh/git commands, since the skill itself runs those
commands internally.

Mirror the rule at the actual handoff point in skills/printing-press/
SKILL.md Phase 6 "If Publish now" with a back-reference to AGENTS.md,
so agents in the generation flow see the policy where they make the
decision. Align the invocation form with sibling slash commands
(/printing-press-publish, matching /printing-press-polish and
/printing-press-retro).

* docs(cli): align remaining /printing-press publish reference to hyphen form

Files touched

M AGENTS.md
M skills/printing-press/SKILL.md

Diff

commit 403341c7f1f6e25892c7aa43326db9a45ad8f582
Author: Trevin Chow <trevin@trevinchow.com>
Date:   Mon May 11 21:16:02 2026 -0700

    docs(cli): require /printing-press-publish skill for CLI publish PRs (#1145)
    
    * docs(cli): require /printing-press-publish skill for CLI publish PRs
    
    Agents running /printing-press in this repo have been hand-rolling
    publish PRs against the public library, skipping the preflight checks
    that /printing-press-publish enforces. The public library's own
    AGENTS.md isn't loaded because the agent's CWD is cli-printing-press,
    so those rules are invisible unless the skill is the entry point.
    
    Add a "Publishing to the Public Library" section to AGENTS.md scoping
    the rule to "publishing a generated CLI" (not all PRs against that
    repo) and pointing at /printing-press-publish as the only supported
    flow. Phrase the prohibitions about improvising the flow rather than
    the specific gh/git commands, since the skill itself runs those
    commands internally.
    
    Mirror the rule at the actual handoff point in skills/printing-press/
    SKILL.md Phase 6 "If Publish now" with a back-reference to AGENTS.md,
    so agents in the generation flow see the policy where they make the
    decision. Align the invocation form with sibling slash commands
    (/printing-press-publish, matching /printing-press-polish and
    /printing-press-retro).
    
    * docs(cli): align remaining /printing-press publish reference to hyphen form
---
 AGENTS.md                      | 10 ++++++++++
 skills/printing-press/SKILL.md |  6 ++++--
 2 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index fadfcf0c..592184cc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -179,6 +179,16 @@ Run `govulncheck` in default mode only, scoped to the generated or publishing CL
 ## Local Artifacts
 Generated artifacts live under `~/printing-press/`, not in this repo: `library/<api-slug>/`, `manuscripts/<api-slug>/`, and `.runstate/<scope>/`. The API slug is derived by the generator from the spec title (`cleanSpecName`), and the binary name is `<api-slug>-pp-cli`. Never hardcode an API slug when the generator can derive it. See [`docs/ARTIFACTS.md`](docs/ARTIFACTS.md) for local-vs-public flow and divergence rules.
 
+## Publishing to the Public Library
+The only supported path for **publishing a generated CLI** (adding or updating an entry under `library/<category>/<api-slug>/` in [mvanhorn/printing-press-library](https://github.com/mvanhorn/printing-press-library)) is to invoke the `/printing-press-publish` skill. The skill runs the required `gh`/`git` commands itself; do not reproduce them by hand.
+- Invoke `/printing-press-publish` and let it drive the fork, branch, manifest checks, `cli-skills/pp-<api-slug>/SKILL.md` regen, push, and PR creation. Following its prompts is the supported flow.
+- Do not skip the skill and improvise the same steps from scratch (manual `gh repo fork` / `cp -r` into a library clone / `gh pr create --repo mvanhorn/printing-press-library …` / branch push to a fork without the skill driving it). The commands look similar; the difference is the preflight checks and conventions the skill enforces before they run.
+- Do not edit `registry.json` or README catalog cells in a publish PR — the public library refreshes those post-merge from `.printing-press.json` / `manifest.json`.
+
+Why this matters: the publish skill enforces preflight checks (printer sentinel validation, manifest shape, vendor-spec PII scope, govulncheck scoped to the changed module) and mirrors the public library's own `AGENTS.md` requirements. An agent operating in this repo's CWD never loads the public library's `AGENTS.md`, so those rules are invisible unless the skill is the entry point.
+
+If `/printing-press-publish` fails, fix the underlying issue (or report it as a machine bug) — do not bypass the skill to land a CLI-publish PR.
+
 ## Internal Skills
 `.claude/skills/` contains internal skills for developing the Printing Press itself (for example `printing-press-retro`). These load automatically when Claude Code is started from inside this repo.
 If you are running Claude Code from a different directory and need these skills available, install them globally:
diff --git a/skills/printing-press/SKILL.md b/skills/printing-press/SKILL.md
index 5a154c94..2a086df7 100644
--- a/skills/printing-press/SKILL.md
+++ b/skills/printing-press/SKILL.md
@@ -2989,7 +2989,9 @@ If the shipcheck report contains a `## Known Gaps` block, prepend: "Note: shipch
 
 ### If "Publish now"
 
-Invoke `/printing-press publish <api>`. The publish skill handles everything from there.
+Invoke `/printing-press-publish <api>`. The publish skill handles everything from there — fork, branch, manifest checks, `cli-skills/pp-<api-slug>/SKILL.md` regen, push, and PR creation.
+
+**Do not improvise the publish flow.** Even though the publish skill itself runs `gh repo fork`, `git push`, and `gh pr create --repo mvanhorn/printing-press-library …` internally, running those commands by hand from this phase skips the preflight checks (printer sentinel validation, manifest shape, vendor-spec PII scope, govulncheck on the changed module) and the public library's own `AGENTS.md` requirements that the skill mirrors. The CWD here is `cli-printing-press`, so the public library's `AGENTS.md` is not loaded — the skill is the only entry point that brings those rules into context. If the publish skill fails, fix the underlying issue (or report it as a machine bug); do not bypass it. See [`AGENTS.md`](AGENTS.md) "Publishing to the Public Library" for the full rule.
 
 **After publish returns success**, offer retro as a soft tail. This is where retro lives on the ship-path — it has no business being a peer of publish on the headline menu, but a post-publish optional offer lets users compound learnings without forcing the choice up front. Retro at this point sees the publish step as part of the session it analyzes.
 
@@ -3008,7 +3010,7 @@ Invoke `/printing-press-polish <api>`. The polish skill runs another diagnostic-
 
 ### If "Done for now"
 
-End normally. The CLI is in `$PRESS_LIBRARY/<api>` and the user can run `/printing-press publish`, `/printing-press-polish`, or `/printing-press-retro` later.
+End normally. The CLI is in `$PRESS_LIBRARY/<api>` and the user can run `/printing-press-publish`, `/printing-press-polish`, or `/printing-press-retro` later.
 
 ### Hold-path menu

← 44e7efe4 docs(cli): refresh solution docs (#1146) · back to Cli Printing Press · feat(skills): add native code review phase to printing-press 88c5b696 →