From 1061a5a8b721c19f30bb908e70af9e3d80caf1c9 Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Tue, 23 Jun 2026 22:12:57 -0700 Subject: [PATCH 1/2] Codify orchestrated re-sync personas and full-replacement rule Re-syncing the downstream fleet from the hub needs a durable, committed playbook (per-machine memory is lost on a machine switch). Add an "Orchestrated Re-Sync: Hub and Downstream Personas" subsection defining the hub/orchestrator vs downstream/derived separation of duties, and make the full-replacement rule explicit in "Staying in Sync": carried artifacts are replaced whole, never partially hand-merged, and re-syncing is not an occasion to add or grow comments. Guards the two recurring downstream regressions (partial carries, comment accretion); the orchestrator validates each result by diffing against the template. Co-Authored-By: Claude Opus 4.8 (1M context) --- AGENTS.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index b359b296..4fbfbb38 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -277,10 +277,19 @@ When the template changes one of these, re-sync the derived repo from the new ve ### Staying in Sync and Reporting Drift Upstream -A derived repo is expected to **re-sync against the template periodically**, not just at creation: pull the current version of each verbatim-carry artifact above and re-apply it (adapting only the noted placeholders). For [`CODESTYLE.md`](./CODESTYLE.md), re-sync the whole file from the template and then drop the language section(s) you don't ship (always keeping the General section) - replacing the file wholesale and trimming whole sections is simpler to keep current than hand-editing per-language snippets. +A derived repo is expected to **re-sync against the template periodically**, not just at creation: pull the current version of each verbatim-carry artifact above and re-apply it by **full replacement** - replace the whole file or carried section, never reconcile a partial hand-merge - adapting only the noted placeholders. For [`CODESTYLE.md`](./CODESTYLE.md), re-sync the whole file from the template and then drop the language section(s) you don't ship (always keeping the General section) - replacing the file wholesale and trimming whole sections is simpler to keep current than hand-editing per-language snippets. Re-syncing is **not** an occasion to add or grow comments: the carried text is authoritative as-is (see [Comments](#comments)). **Drift flows back upstream as an issue, not a private fix.** When porting or re-syncing, if you find a discrepancy that should be fixed in the **template itself** - a gap, an outdated instruction, a missing rule, something that bit this repo and would bite the next derived repo too - **open an issue in [`ptr727/ProjectTemplate`](https://github.com/ptr727/ProjectTemplate)** describing it, rather than only patching it locally. A local fix realigns *this* repo; an upstream issue (then fix) corrects it *for every future derived repo* and keeps the template the single source of truth. This is exactly how the current review-loop / lint-config / brownfield-migration gaps were surfaced. +#### Orchestrated Re-Sync: Hub and Downstream Personas + +When one operator re-syncs the whole fleet from the hub (every derived repo checked out on one machine), the work splits into two personas with separated duties. This playbook lives **here, committed**, because per-machine agent memory does not survive a machine switch. + +- **Hub / orchestrator** (acting in this template repo): owns the source of truth and *drives* consolidation. It directs each downstream sync, then **validates the result against the template** - confirming carried artifacts were **fully replaced, not partially hand-merged**, that **no comments were added or grown** (see [Comments](#comments)), and that line endings and lint match spec. It collects the template gaps the syncs surface, fixes them in the template through the normal review gate, has affected downstreams re-pull, and **never merges without the maintainer's OK**. +- **Downstream / derived** (acting in a derived repo): performs the local re-sync **under the orchestrator's direction** - **full-replace** each carried artifact, **honor the [Comments](#comments) rules** (no new prose, no growth), and **report any template gap upstream** rather than patching the template's intent locally. + +This guards the two recurring downstream regressions: *partial* updates where carry means full replacement, and comment accretion against the comment rules. The orchestrator catches both by diffing every result against the template. + #### Known Downstream Projects Sync is **bidirectional**. The flow above is the downstream-to-upstream direction (derived repos report drift up). The reverse direction is the maintainer's: **when changing a verbatim-carry artifact or another cross-cutting contract in this template, file a heads-up issue in each affected downstream repo below** so it can re-sync, rather than letting the change be discovered only on the next ad-hoc port. Keep this table current as projects are derived from or retired from the template. From 5532497dcbafbf47acc9d47cc3d3f5465bac0d0e Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Tue, 23 Jun 2026 22:30:32 -0700 Subject: [PATCH 2/2] Fix grammar: separate duties --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 4fbfbb38..71e66292 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -283,7 +283,7 @@ A derived repo is expected to **re-sync against the template periodically**, not #### Orchestrated Re-Sync: Hub and Downstream Personas -When one operator re-syncs the whole fleet from the hub (every derived repo checked out on one machine), the work splits into two personas with separated duties. This playbook lives **here, committed**, because per-machine agent memory does not survive a machine switch. +When one operator re-syncs the whole fleet from the hub (every derived repo checked out on one machine), the work splits into two personas with separate duties. This playbook lives **here, committed**, because per-machine agent memory does not survive a machine switch. - **Hub / orchestrator** (acting in this template repo): owns the source of truth and *drives* consolidation. It directs each downstream sync, then **validates the result against the template** - confirming carried artifacts were **fully replaced, not partially hand-merged**, that **no comments were added or grown** (see [Comments](#comments)), and that line endings and lint match spec. It collects the template gaps the syncs surface, fixes them in the template through the normal review gate, has affected downstreams re-pull, and **never merges without the maintainer's OK**. - **Downstream / derived** (acting in a derived repo): performs the local re-sync **under the orchestrator's direction** - **full-replace** each carried artifact, **honor the [Comments](#comments) rules** (no new prose, no growth), and **report any template gap upstream** rather than patching the template's intent locally.