← back to Cli Printing Press
fix(cli): drop // PATCH marker instruction from generated AGENTS.md
caa68801e2c387f89489f9c32c6bd78a1526dcc4 · 2026-05-17 10:21:12 -0700 · Trevin Chow
The patches index manifest is the single recorded artifact for library-side
customizations. Pairs with the library-side relaxation at
mvanhorn/printing-press-library#644 which drops the verifier check
requiring bidirectional pairing between .printing-press-patches.json
entries and // PATCH source comments.
The template's "Local Customizations" section now describes a single step
(catalog the change in the patches manifest) rather than two (mark every
source site AND catalog). A closing note clarifies that inline // PATCH
comments are optional navigation aids if an agent wants them, but the CI
no longer requires them.
Golden fixtures updated for generate-golden-api and
generate-golden-api-rich-auth (the two cases whose expected AGENTS.md
include the customizations section); all 20 golden cases pass verify.
Existing printed CLIs keep their old AGENTS.md until they regen. No
retrofit needed because the library verifier (post-#644) doesn't check
the source markers either way.
Files touched
M internal/generator/templates/agents.md.tmplM testdata/golden/expected/generate-golden-api-rich-auth/printing-press-rich-auth/AGENTS.mdM testdata/golden/expected/generate-golden-api/printing-press-golden/AGENTS.md
Diff
commit caa68801e2c387f89489f9c32c6bd78a1526dcc4
Author: Trevin Chow <trevin@trevinchow.com>
Date: Sun May 17 10:21:12 2026 -0700
fix(cli): drop // PATCH marker instruction from generated AGENTS.md
The patches index manifest is the single recorded artifact for library-side
customizations. Pairs with the library-side relaxation at
mvanhorn/printing-press-library#644 which drops the verifier check
requiring bidirectional pairing between .printing-press-patches.json
entries and // PATCH source comments.
The template's "Local Customizations" section now describes a single step
(catalog the change in the patches manifest) rather than two (mark every
source site AND catalog). A closing note clarifies that inline // PATCH
comments are optional navigation aids if an agent wants them, but the CI
no longer requires them.
Golden fixtures updated for generate-golden-api and
generate-golden-api-rich-auth (the two cases whose expected AGENTS.md
include the customizations section); all 20 golden cases pass verify.
Existing printed CLIs keep their old AGENTS.md until they regen. No
retrofit needed because the library verifier (post-#644) doesn't check
the source markers either way.
---
internal/generator/templates/agents.md.tmpl | 48 ++++++++++------------
.../printing-press-rich-auth/AGENTS.md | 48 ++++++++++------------
.../printing-press-golden/AGENTS.md | 48 ++++++++++------------
3 files changed, 63 insertions(+), 81 deletions(-)
diff --git a/internal/generator/templates/agents.md.tmpl b/internal/generator/templates/agents.md.tmpl
index 91d8851e..7411d49e 100644
--- a/internal/generator/templates/agents.md.tmpl
+++ b/internal/generator/templates/agents.md.tmpl
@@ -37,35 +37,29 @@ For install, auth, examples, and longer product guidance, read `README.md` and `
## Local Customizations
-If you modify this CLI beyond what the generator produced, record each customization so it isn't lost on the next regen and is visible to the next reader.
+If you modify this CLI beyond what the generator produced, record each customization in a `.printing-press-patches.json` at this CLI's root (parallel to `.printing-press.json`) so the change isn't lost on the next regen and is visible to the next reader.
-1. **Mark every changed site** in source with a comment summarizing the deviation:
+Minimum shape:
- ```
- // PATCH: <one-line summary>
- ```
-
- Include an upstream reference inline when there is one (e.g. `// PATCH(upstream cli-printing-press#<issue>): ...`). `grep -rn 'PATCH' .` from this directory then surfaces every customization.
-
-2. **Catalog the change** in a `.printing-press-patches.json` at this CLI's root (parallel to `.printing-press.json`). Minimum shape:
-
- ```json
+```json
+{
+ "schema_version": 1,
+ "applied_at": "YYYY-MM-DD",
+ "base_run_id": "<copy from .printing-press.json>",
+ "base_printing_press_version": "<copy from .printing-press.json>",
+ "patches": [
{
- "schema_version": 1,
- "applied_at": "YYYY-MM-DD",
- "base_run_id": "<copy from .printing-press.json>",
- "base_printing_press_version": "<copy from .printing-press.json>",
- "patches": [
- {
- "id": "short-identifier",
- "summary": "What changed (one sentence).",
- "reason": "Why this customization was needed (one or two sentences).",
- "files": ["internal/cli/foo.go"],
- "validated_outcome": "Optional: non-obvious test result that confirms the fix.",
- "upstream_issue": "Optional: https://github.com/mvanhorn/cli-printing-press/issues/<n>"
- }
- ]
+ "id": "short-identifier",
+ "summary": "What changed (one sentence).",
+ "reason": "Why this customization was needed (one or two sentences).",
+ "files": ["internal/cli/foo.go"],
+ "validated_outcome": "Optional: non-obvious test result that confirms the fix.",
+ "upstream_issue": "Optional: https://github.com/mvanhorn/cli-printing-press/issues/<n>"
}
- ```
+ ]
+}
+```
+
+This file is an **index of customizations**, not a second copy of the diff. Diffs live in `git`; the manifest is what tells the next agent (or regeneration tooling) what was customized and why. Keep `summary` and `reason` short -- if you find yourself writing tables of field renames or code transformations, that detail belongs in the commit message, not here.
-This file is an **index of customizations**, not a second copy of the diff. Diffs live in `git`; code lives in the source files; the inline `// PATCH:` comment carries the local semantics. Keep `summary` and `reason` short -- if you find yourself writing tables of field renames or code transformations, that detail belongs in the source comment or commit message, not here.
+Inline `// PATCH:` source comments are optional. If you find them helpful as a navigation aid (`grep -rn 'PATCH' .` surfaces customized sites), feel free to add them -- but they aren't required and aren't enforced by any CI.
diff --git a/testdata/golden/expected/generate-golden-api-rich-auth/printing-press-rich-auth/AGENTS.md b/testdata/golden/expected/generate-golden-api-rich-auth/printing-press-rich-auth/AGENTS.md
index 1e2f28c0..66b31c6c 100644
--- a/testdata/golden/expected/generate-golden-api-rich-auth/printing-press-rich-auth/AGENTS.md
+++ b/testdata/golden/expected/generate-golden-api-rich-auth/printing-press-rich-auth/AGENTS.md
@@ -37,35 +37,29 @@ For install, auth, examples, and longer product guidance, read `README.md` and `
## Local Customizations
-If you modify this CLI beyond what the generator produced, record each customization so it isn't lost on the next regen and is visible to the next reader.
+If you modify this CLI beyond what the generator produced, record each customization in a `.printing-press-patches.json` at this CLI's root (parallel to `.printing-press.json`) so the change isn't lost on the next regen and is visible to the next reader.
-1. **Mark every changed site** in source with a comment summarizing the deviation:
+Minimum shape:
- ```
- // PATCH: <one-line summary>
- ```
-
- Include an upstream reference inline when there is one (e.g. `// PATCH(upstream cli-printing-press#<issue>): ...`). `grep -rn 'PATCH' .` from this directory then surfaces every customization.
-
-2. **Catalog the change** in a `.printing-press-patches.json` at this CLI's root (parallel to `.printing-press.json`). Minimum shape:
-
- ```json
+```json
+{
+ "schema_version": 1,
+ "applied_at": "YYYY-MM-DD",
+ "base_run_id": "<copy from .printing-press.json>",
+ "base_printing_press_version": "<copy from .printing-press.json>",
+ "patches": [
{
- "schema_version": 1,
- "applied_at": "YYYY-MM-DD",
- "base_run_id": "<copy from .printing-press.json>",
- "base_printing_press_version": "<copy from .printing-press.json>",
- "patches": [
- {
- "id": "short-identifier",
- "summary": "What changed (one sentence).",
- "reason": "Why this customization was needed (one or two sentences).",
- "files": ["internal/cli/foo.go"],
- "validated_outcome": "Optional: non-obvious test result that confirms the fix.",
- "upstream_issue": "Optional: https://github.com/mvanhorn/cli-printing-press/issues/<n>"
- }
- ]
+ "id": "short-identifier",
+ "summary": "What changed (one sentence).",
+ "reason": "Why this customization was needed (one or two sentences).",
+ "files": ["internal/cli/foo.go"],
+ "validated_outcome": "Optional: non-obvious test result that confirms the fix.",
+ "upstream_issue": "Optional: https://github.com/mvanhorn/cli-printing-press/issues/<n>"
}
- ```
+ ]
+}
+```
+
+This file is an **index of customizations**, not a second copy of the diff. Diffs live in `git`; the manifest is what tells the next agent (or regeneration tooling) what was customized and why. Keep `summary` and `reason` short -- if you find yourself writing tables of field renames or code transformations, that detail belongs in the commit message, not here.
-This file is an **index of customizations**, not a second copy of the diff. Diffs live in `git`; code lives in the source files; the inline `// PATCH:` comment carries the local semantics. Keep `summary` and `reason` short -- if you find yourself writing tables of field renames or code transformations, that detail belongs in the source comment or commit message, not here.
+Inline `// PATCH:` source comments are optional. If you find them helpful as a navigation aid (`grep -rn 'PATCH' .` surfaces customized sites), feel free to add them -- but they aren't required and aren't enforced by any CI.
diff --git a/testdata/golden/expected/generate-golden-api/printing-press-golden/AGENTS.md b/testdata/golden/expected/generate-golden-api/printing-press-golden/AGENTS.md
index 98c40b0f..1118ae0e 100644
--- a/testdata/golden/expected/generate-golden-api/printing-press-golden/AGENTS.md
+++ b/testdata/golden/expected/generate-golden-api/printing-press-golden/AGENTS.md
@@ -37,35 +37,29 @@ For install, auth, examples, and longer product guidance, read `README.md` and `
## Local Customizations
-If you modify this CLI beyond what the generator produced, record each customization so it isn't lost on the next regen and is visible to the next reader.
+If you modify this CLI beyond what the generator produced, record each customization in a `.printing-press-patches.json` at this CLI's root (parallel to `.printing-press.json`) so the change isn't lost on the next regen and is visible to the next reader.
-1. **Mark every changed site** in source with a comment summarizing the deviation:
+Minimum shape:
- ```
- // PATCH: <one-line summary>
- ```
-
- Include an upstream reference inline when there is one (e.g. `// PATCH(upstream cli-printing-press#<issue>): ...`). `grep -rn 'PATCH' .` from this directory then surfaces every customization.
-
-2. **Catalog the change** in a `.printing-press-patches.json` at this CLI's root (parallel to `.printing-press.json`). Minimum shape:
-
- ```json
+```json
+{
+ "schema_version": 1,
+ "applied_at": "YYYY-MM-DD",
+ "base_run_id": "<copy from .printing-press.json>",
+ "base_printing_press_version": "<copy from .printing-press.json>",
+ "patches": [
{
- "schema_version": 1,
- "applied_at": "YYYY-MM-DD",
- "base_run_id": "<copy from .printing-press.json>",
- "base_printing_press_version": "<copy from .printing-press.json>",
- "patches": [
- {
- "id": "short-identifier",
- "summary": "What changed (one sentence).",
- "reason": "Why this customization was needed (one or two sentences).",
- "files": ["internal/cli/foo.go"],
- "validated_outcome": "Optional: non-obvious test result that confirms the fix.",
- "upstream_issue": "Optional: https://github.com/mvanhorn/cli-printing-press/issues/<n>"
- }
- ]
+ "id": "short-identifier",
+ "summary": "What changed (one sentence).",
+ "reason": "Why this customization was needed (one or two sentences).",
+ "files": ["internal/cli/foo.go"],
+ "validated_outcome": "Optional: non-obvious test result that confirms the fix.",
+ "upstream_issue": "Optional: https://github.com/mvanhorn/cli-printing-press/issues/<n>"
}
- ```
+ ]
+}
+```
+
+This file is an **index of customizations**, not a second copy of the diff. Diffs live in `git`; the manifest is what tells the next agent (or regeneration tooling) what was customized and why. Keep `summary` and `reason` short -- if you find yourself writing tables of field renames or code transformations, that detail belongs in the commit message, not here.
-This file is an **index of customizations**, not a second copy of the diff. Diffs live in `git`; code lives in the source files; the inline `// PATCH:` comment carries the local semantics. Keep `summary` and `reason` short -- if you find yourself writing tables of field renames or code transformations, that detail belongs in the source comment or commit message, not here.
+Inline `// PATCH:` source comments are optional. If you find them helpful as a navigation aid (`grep -rn 'PATCH' .` surfaces customized sites), feel free to add them -- but they aren't required and aren't enforced by any CI.
← 875d64e9 fix(cli): detect partial-failure response shape in :mutate h
·
back to Cli Printing Press
·
feat(cli): emit .printing-press-patches.json on every genera c3e1b87a →