From a97bcbe4cd22e344a208f62e85b449c2bccf4b33 Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Thu, 13 Aug 2026 08:38:57 -0700 Subject: [PATCH 1/4] Package Resync a Repo and Fleet Conformance Check as Skills Phase 4 of the hub-docs-to-Skills conversion. resync-a-repo packages RESYNC.md section 3's apply order for a hub-context session driving a named repo's resync, with the carried-instruction-file-guard skill's distinctive-phrase probe made a mandatory, non-skippable step before any verbatim re-vendor of an instruction file. fleet-conformance-check is the new downstream-facing counterpart: run from inside a repo's own session with no hub checkout and no named target, it confirms the local Skills install is current, confirms AGENTS.md's pointer text matches the hub, self-applies what is safe, and escalates anything ambiguous to a hub-driven resync-a-repo run. RESYNC.md section 3 step 1 gains the mandatory probe requirement and the AGENTS.md skill-dependency pointer as one more verbatim-carried unit, sitting alongside the existing instruction-set-first step. AGENTS.md's Where the Rules Live table and pointer paragraph route to both new skills. .claude-plugin/fleet-skills/ rebuilt via build_dist.py. Co-Authored-By: Claude Sonnet 5 --- .../skills/fleet-conformance-check/SKILL.md | 63 +++++++++++++++ .agents/skills/resync-a-repo/SKILL.md | 79 +++++++++++++++++++ .../fleet-skills/.claude-plugin/plugin.json | 4 +- .claude-plugin/fleet-skills/.source-digest | 2 +- .../skills/fleet-conformance-check/SKILL.md | 63 +++++++++++++++ .../skills/resync-a-repo/SKILL.md | 79 +++++++++++++++++++ AGENTS.md | 4 +- RESYNC.md | 2 +- 8 files changed, 291 insertions(+), 5 deletions(-) create mode 100644 .agents/skills/fleet-conformance-check/SKILL.md create mode 100644 .agents/skills/resync-a-repo/SKILL.md create mode 100644 .claude-plugin/fleet-skills/skills/fleet-conformance-check/SKILL.md create mode 100644 .claude-plugin/fleet-skills/skills/resync-a-repo/SKILL.md diff --git a/.agents/skills/fleet-conformance-check/SKILL.md b/.agents/skills/fleet-conformance-check/SKILL.md new file mode 100644 index 00000000..b40cfbac --- /dev/null +++ b/.agents/skills/fleet-conformance-check/SKILL.md @@ -0,0 +1,63 @@ +--- +name: fleet-conformance-check +description: >- + Checks, from inside a downstream repo's own session, whether this repo and this machine are + current against the ptr727/ProjectTemplate hub, and safely self-applies what it can. Use this + whenever asked to check if this repo is up to date with the hub, whenever a fleet rule or Skill + seems to not be applying and the cause is unclear, or whenever about to work in a fleet repo and + wanting to confirm the ground under that work is current before trusting it. Runs with no hub + checkout required and no named target repo other than the one the session is already in, the + counterpart to resync-a-repo, which needs both and drives change from the hub side instead. Also + triggers on "why do I have to keep restating this rule every session," since a stale or missing + Skills install is the most common cause and the cheapest one to rule out first. +--- + +# Fleet Conformance Check + +## Why this exists + +A downstream repo today only finds out it has drifted when someone runs a hub-driven resync +against it by name. Nothing notices from the inside on its own. This skill is that inside check, +run with no hub-side operator watching, so a stale Skills install or an out-of-date `AGENTS.md` +pointer gets noticed and fixed without waiting for a fleet-wide sweep to reach this particular +repo. + +## What it checks + +1. **Is the Skills install current on this machine.** `scripts/` is hub-hosted and reached rather + than carried, per GOVERNANCE.md "Hub-Hosted Tooling", so fetch a hub checkout + (`github.com/ptr727/ProjectTemplate`, `main` branch, fetched fresh) and run + `python3 scripts/skills_install.py --report` from it. A stale or missing stamp is very often + the direct answer to "why isn't a fleet rule applying": the harness never loaded the current + content in the first place, and no amount of re-reading `GOVERNANCE.md` fixes that. +2. **Does this repo's own carried content still match the hub.** Compare `AGENTS.md`'s + "Where the Rules Live" pointer text, and any other verbatim `AGENTS.md`/`GOVERNANCE.md` section + this repo carries, against the same hub checkout's current wording, by reading the text rather + than by feel. + +## What it is safe to fix on its own + +- **Re-run the installer**, `python3 scripts/skills_install.py`, when the stamp reports stale. + This is a per-machine, local-only change, nothing in it touches this repo's git history or + needs a review. + +Nothing else. This skill never re-vendors a carried file, never deletes one, and never applies a +setting or ruleset. Those are `resync-a-repo`'s job, driven from the hub with a named target, +never a downstream repo acting on itself. + +## What it escalates instead of touching + +- **A carried section that differs from the hub in a way that reads as a genuine local addition** + rather than plain staleness, the exact case `carried-instruction-file-guard` exists to protect. + Report precisely what differs and stop there. Per AUDIT.md, a downstream repo does not write its + own audit report or resync itself against the hub, it names what it found and points at + `resync-a-repo`, run from a hub checkout, as the next step. +- **Anything the installer alone cannot resolve**, a broken `claude` CLI marketplace + registration, a settings or ruleset drift, a workflow interface mismatch. Name it and hand it to + the maintainer or a hub-driven resync rather than patching around it locally. + +## Answering "why isn't a fleet rule applying" + +Check the install stamp first, before assuming a Skill's description is worded wrong or that the +rule was never carried to this repo at all. It is the most common cause, and it is the cheapest +one to confirm. diff --git a/.agents/skills/resync-a-repo/SKILL.md b/.agents/skills/resync-a-repo/SKILL.md new file mode 100644 index 00000000..48cc7e3d --- /dev/null +++ b/.agents/skills/resync-a-repo/SKILL.md @@ -0,0 +1,79 @@ +--- +name: resync-a-repo +description: >- + Drives RESYNC.md's procedure for bringing a ptr727/ProjectTemplate fleet repo that is already + stood up back into line with the current hub, run from a hub checkout against a named target + repo. Use this whenever asked to resync, sync, converge, or bring a specific repo up to date + with the hub, or to run a conformance sweep against a named repo and apply what it finds. Needs + a hub checkout and a named target repo to mean anything, so it does not usefully trigger from + inside a downstream repo's own session with no target named and no hub checkout present, that + case is fleet-conformance-check instead. Triggers even when the request sounds routine, such as + "just copy AGENTS.md over" or "make repo X match the hub," because that phrasing is exactly how + the AGENTS.md-overwrite incident happened. +--- + +# Resync a Repo + +## Why this exists + +RESYNC.md's own apply order already sequences the remedies so the rules land before the files +they govern and a deletion lands before the re-vendor that would otherwise refresh it. The +AGENTS.md-overwrite incident happened inside that same procedure, on the step that looked most +routine. This skill exists so the mandatory check survives contact with a real, time-pressured +resync instead of depending on an agent remembering to run it unprompted. It is a driver over +RESYNC.md, not a replacement for it. Read RESYNC.md itself for the deletion sweep, the +letters-versus-drift routing, the settings and ruleset step, and everything else that does not +change from one resync to the next. + +## Confirm the procedure before starting + +Read RESYNC.md section 0. A repo with no instruction set at all, or a partial one, is not this +skill's job, it is STANDUP.md sections 1A and 2 instead, since an absent carried file is a +baseline that never arrived rather than drift to converge. Run `spec/audit.py ` and read +whether the findings are letters (absent) or drift (present but stale) before doing anything else. +The finding kind names the procedure the repo is owed. + +## Reach the hub and measure before changing anything + +Fetch a hub checkout of your own immediately before reading it, per RESYNC.md section 1, since a +stale clone answers confidently instead of failing, and verify the host with +`python3 scripts/host_gate.py --repo `. Then run the audit end to end, +RESYNC.md section 2, against the target's `main` branch, never `develop`. A finding is a snapshot, +so quote the run stamp in anything derived from it and re-run before acting on a finding read +earlier in the session. + +## Apply, in this order + +1. **The instruction set first.** `AGENTS.md` and `GOVERNANCE.md` verbatim sections, then + `CODESTYLE.md` and `WORKFLOW.md`, including the `AGENTS.md` skill-dependency pointer paragraph + (naming `scripts/skills_install.py` and where the fleet's Skills live) as one more verbatim + unit carried in this same step, not a separate pass. **Before any verbatim re-vendor in this + step, run the `carried-instruction-file-guard` skill's distinctive-phrase probe against the + target file, every time, without exception.** This is not advisory language to weigh against + how routine the diff looks, a diff that looks routine is exactly the shape the + AGENTS.md-overwrite incident took. Do not proceed to the re-vendor until the probe has run and + any local addition it finds has a destination, per that skill's own procedure. +2. **Deletions second, before any re-vendor.** Only a `retire` disposition in + `spec/divergences.json` authorizes removing a file, and the removal is swept tree-wide, per + RESYNC.md section 4, before the deletion counts as done. +3. **Verbatim re-vendors** for everything the probe in step 1 cleared. A finding classified + modified rather than stale gets its diff read before being overwritten, since it may be an + improvement the hub should adopt instead of a mistake to erase. +4. **Interface workflows.** Honor the named contract, required jobs, the ruleset-bound check name, + the artifact-name handoff, rather than copying bytes. +5. **Settings, rulesets, and secrets.** Run `repo-config/configure.sh check / + release|operational` against the repo by name, then `apply` for what it reports, never from a + carried copy. +6. **Intent files last, and by hand,** since nothing mechanical judges these. + +Reconcile the registry entry (`status`, `types`, `releaseTrigger`, `workflowModel`, +`driftNotes`) in the same pass, and delete a `driftNote` describing work this pass just finished +rather than leaving it standing. + +## Ship it + +One focused pull request per drift class, branched from the target's `develop`, never a direct +push to a protected branch and never a hand edit outside a pull request. Close the review loop, +per the `pr-review-conduct` skill, before asking the maintainer for merge permission. The +maintainer merges, the agent drives to green and stops. Re-run the audit after the merge and +commit the report, done means measured, not applied. diff --git a/.claude-plugin/fleet-skills/.claude-plugin/plugin.json b/.claude-plugin/fleet-skills/.claude-plugin/plugin.json index 6a31752b..0ae7e721 100644 --- a/.claude-plugin/fleet-skills/.claude-plugin/plugin.json +++ b/.claude-plugin/fleet-skills/.claude-plugin/plugin.json @@ -9,6 +9,8 @@ "./skills/carried-instruction-file-guard", "./skills/comment-and-doc-style", "./skills/copilot-instructions-keeper", - "./skills/pr-review-conduct" + "./skills/fleet-conformance-check", + "./skills/pr-review-conduct", + "./skills/resync-a-repo" ] } diff --git a/.claude-plugin/fleet-skills/.source-digest b/.claude-plugin/fleet-skills/.source-digest index 53a36c89..e473d1f1 100644 --- a/.claude-plugin/fleet-skills/.source-digest +++ b/.claude-plugin/fleet-skills/.source-digest @@ -1 +1 @@ -1d466f7f6d091eb9 +3dcf4120b8c55db3 diff --git a/.claude-plugin/fleet-skills/skills/fleet-conformance-check/SKILL.md b/.claude-plugin/fleet-skills/skills/fleet-conformance-check/SKILL.md new file mode 100644 index 00000000..b40cfbac --- /dev/null +++ b/.claude-plugin/fleet-skills/skills/fleet-conformance-check/SKILL.md @@ -0,0 +1,63 @@ +--- +name: fleet-conformance-check +description: >- + Checks, from inside a downstream repo's own session, whether this repo and this machine are + current against the ptr727/ProjectTemplate hub, and safely self-applies what it can. Use this + whenever asked to check if this repo is up to date with the hub, whenever a fleet rule or Skill + seems to not be applying and the cause is unclear, or whenever about to work in a fleet repo and + wanting to confirm the ground under that work is current before trusting it. Runs with no hub + checkout required and no named target repo other than the one the session is already in, the + counterpart to resync-a-repo, which needs both and drives change from the hub side instead. Also + triggers on "why do I have to keep restating this rule every session," since a stale or missing + Skills install is the most common cause and the cheapest one to rule out first. +--- + +# Fleet Conformance Check + +## Why this exists + +A downstream repo today only finds out it has drifted when someone runs a hub-driven resync +against it by name. Nothing notices from the inside on its own. This skill is that inside check, +run with no hub-side operator watching, so a stale Skills install or an out-of-date `AGENTS.md` +pointer gets noticed and fixed without waiting for a fleet-wide sweep to reach this particular +repo. + +## What it checks + +1. **Is the Skills install current on this machine.** `scripts/` is hub-hosted and reached rather + than carried, per GOVERNANCE.md "Hub-Hosted Tooling", so fetch a hub checkout + (`github.com/ptr727/ProjectTemplate`, `main` branch, fetched fresh) and run + `python3 scripts/skills_install.py --report` from it. A stale or missing stamp is very often + the direct answer to "why isn't a fleet rule applying": the harness never loaded the current + content in the first place, and no amount of re-reading `GOVERNANCE.md` fixes that. +2. **Does this repo's own carried content still match the hub.** Compare `AGENTS.md`'s + "Where the Rules Live" pointer text, and any other verbatim `AGENTS.md`/`GOVERNANCE.md` section + this repo carries, against the same hub checkout's current wording, by reading the text rather + than by feel. + +## What it is safe to fix on its own + +- **Re-run the installer**, `python3 scripts/skills_install.py`, when the stamp reports stale. + This is a per-machine, local-only change, nothing in it touches this repo's git history or + needs a review. + +Nothing else. This skill never re-vendors a carried file, never deletes one, and never applies a +setting or ruleset. Those are `resync-a-repo`'s job, driven from the hub with a named target, +never a downstream repo acting on itself. + +## What it escalates instead of touching + +- **A carried section that differs from the hub in a way that reads as a genuine local addition** + rather than plain staleness, the exact case `carried-instruction-file-guard` exists to protect. + Report precisely what differs and stop there. Per AUDIT.md, a downstream repo does not write its + own audit report or resync itself against the hub, it names what it found and points at + `resync-a-repo`, run from a hub checkout, as the next step. +- **Anything the installer alone cannot resolve**, a broken `claude` CLI marketplace + registration, a settings or ruleset drift, a workflow interface mismatch. Name it and hand it to + the maintainer or a hub-driven resync rather than patching around it locally. + +## Answering "why isn't a fleet rule applying" + +Check the install stamp first, before assuming a Skill's description is worded wrong or that the +rule was never carried to this repo at all. It is the most common cause, and it is the cheapest +one to confirm. diff --git a/.claude-plugin/fleet-skills/skills/resync-a-repo/SKILL.md b/.claude-plugin/fleet-skills/skills/resync-a-repo/SKILL.md new file mode 100644 index 00000000..48cc7e3d --- /dev/null +++ b/.claude-plugin/fleet-skills/skills/resync-a-repo/SKILL.md @@ -0,0 +1,79 @@ +--- +name: resync-a-repo +description: >- + Drives RESYNC.md's procedure for bringing a ptr727/ProjectTemplate fleet repo that is already + stood up back into line with the current hub, run from a hub checkout against a named target + repo. Use this whenever asked to resync, sync, converge, or bring a specific repo up to date + with the hub, or to run a conformance sweep against a named repo and apply what it finds. Needs + a hub checkout and a named target repo to mean anything, so it does not usefully trigger from + inside a downstream repo's own session with no target named and no hub checkout present, that + case is fleet-conformance-check instead. Triggers even when the request sounds routine, such as + "just copy AGENTS.md over" or "make repo X match the hub," because that phrasing is exactly how + the AGENTS.md-overwrite incident happened. +--- + +# Resync a Repo + +## Why this exists + +RESYNC.md's own apply order already sequences the remedies so the rules land before the files +they govern and a deletion lands before the re-vendor that would otherwise refresh it. The +AGENTS.md-overwrite incident happened inside that same procedure, on the step that looked most +routine. This skill exists so the mandatory check survives contact with a real, time-pressured +resync instead of depending on an agent remembering to run it unprompted. It is a driver over +RESYNC.md, not a replacement for it. Read RESYNC.md itself for the deletion sweep, the +letters-versus-drift routing, the settings and ruleset step, and everything else that does not +change from one resync to the next. + +## Confirm the procedure before starting + +Read RESYNC.md section 0. A repo with no instruction set at all, or a partial one, is not this +skill's job, it is STANDUP.md sections 1A and 2 instead, since an absent carried file is a +baseline that never arrived rather than drift to converge. Run `spec/audit.py ` and read +whether the findings are letters (absent) or drift (present but stale) before doing anything else. +The finding kind names the procedure the repo is owed. + +## Reach the hub and measure before changing anything + +Fetch a hub checkout of your own immediately before reading it, per RESYNC.md section 1, since a +stale clone answers confidently instead of failing, and verify the host with +`python3 scripts/host_gate.py --repo `. Then run the audit end to end, +RESYNC.md section 2, against the target's `main` branch, never `develop`. A finding is a snapshot, +so quote the run stamp in anything derived from it and re-run before acting on a finding read +earlier in the session. + +## Apply, in this order + +1. **The instruction set first.** `AGENTS.md` and `GOVERNANCE.md` verbatim sections, then + `CODESTYLE.md` and `WORKFLOW.md`, including the `AGENTS.md` skill-dependency pointer paragraph + (naming `scripts/skills_install.py` and where the fleet's Skills live) as one more verbatim + unit carried in this same step, not a separate pass. **Before any verbatim re-vendor in this + step, run the `carried-instruction-file-guard` skill's distinctive-phrase probe against the + target file, every time, without exception.** This is not advisory language to weigh against + how routine the diff looks, a diff that looks routine is exactly the shape the + AGENTS.md-overwrite incident took. Do not proceed to the re-vendor until the probe has run and + any local addition it finds has a destination, per that skill's own procedure. +2. **Deletions second, before any re-vendor.** Only a `retire` disposition in + `spec/divergences.json` authorizes removing a file, and the removal is swept tree-wide, per + RESYNC.md section 4, before the deletion counts as done. +3. **Verbatim re-vendors** for everything the probe in step 1 cleared. A finding classified + modified rather than stale gets its diff read before being overwritten, since it may be an + improvement the hub should adopt instead of a mistake to erase. +4. **Interface workflows.** Honor the named contract, required jobs, the ruleset-bound check name, + the artifact-name handoff, rather than copying bytes. +5. **Settings, rulesets, and secrets.** Run `repo-config/configure.sh check / + release|operational` against the repo by name, then `apply` for what it reports, never from a + carried copy. +6. **Intent files last, and by hand,** since nothing mechanical judges these. + +Reconcile the registry entry (`status`, `types`, `releaseTrigger`, `workflowModel`, +`driftNotes`) in the same pass, and delete a `driftNote` describing work this pass just finished +rather than leaving it standing. + +## Ship it + +One focused pull request per drift class, branched from the target's `develop`, never a direct +push to a protected branch and never a hand edit outside a pull request. Close the review loop, +per the `pr-review-conduct` skill, before asking the maintainer for merge permission. The +maintainer merges, the agent drives to green and stops. Re-run the audit after the merge and +commit the report, done means measured, not applied. diff --git a/AGENTS.md b/AGENTS.md index d78357dc..194a1e4f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -74,7 +74,7 @@ Every rule below is a level-two section of [`GOVERNANCE.md`](./GOVERNANCE.md). R | Branch choice, promotion, keeping branches in sync | `Branching Model` | | Releasing, version bumps, publishing | `Release Model` | | A live config repo rather than a code repo | `Operational Repositories` | -| Onboarding a repo or running a conformance sweep | `Repository Onboarding and Conformance` (hub only, not carried) | +| Onboarding a repo or running a conformance sweep | `Repository Onboarding and Conformance` (hub only, not carried). Resyncing a named repo from a hub checkout is packaged as the `resync-a-repo` Skill (hub-context only) | | Running a fleet gate, the review digest, or the config script | `Hub-Hosted Tooling` | | Writing a commit message or pull request title | `Pull Request Title and Commit Message Conventions`, packaged as the `comment-and-doc-style` Skill | | Any prose, comment, doc, or line-ending change | `Documentation Style Conventions`, packaged as the `comment-and-doc-style` Skill | @@ -88,4 +88,4 @@ Every rule below is a level-two section of [`GOVERNANCE.md`](./GOVERNANCE.md). R | The About panel, description, or repo toggles | `Repository Details` | | Where a file belongs in the tree | `Repository Layout` | -Some of the rules above are also packaged as Claude Code / opencode / Codex Skills, hand-authored at `.agents/skills/` in the hub (not a repo-relative link here, since that path is hub-local and not carried into every fleet repo), so they surface automatically instead of needing to be re-read every session. `scripts/` is hub-hosted and reached rather than carried, per "Hub-Hosted Tooling", so run the installer from a hub checkout: `python3 scripts/skills_install.py` (or the `.sh`/`.ps1` wrapper) once per machine, from `github.com/ptr727/ProjectTemplate`, installs them for every repo touched from that machine. `python3 scripts/skills_install.py --report`, also from a hub checkout, says whether this machine is current. A rule that keeps needing to be restated is a sign the install is missing or stale, not that the rule does not exist. Keeping a repo's own carried `.github/copilot-instructions.md` in sync with the hub, without losing that repo's own "Disproved Claims" ledger entries in the process, is `copilot-instructions-keeper`, a skill about maintaining that file rather than a rule extracted from it, since the file itself is read directly by the Copilot bot and stays fully intact everywhere it is carried. +Some of the rules above are also packaged as Claude Code / opencode / Codex Skills, hand-authored at `.agents/skills/` in the hub (not a repo-relative link here, since that path is hub-local and not carried into every fleet repo), so they surface automatically instead of needing to be re-read every session. `scripts/` is hub-hosted and reached rather than carried, per "Hub-Hosted Tooling", so run the installer from a hub checkout: `python3 scripts/skills_install.py` (or the `.sh`/`.ps1` wrapper) once per machine, from `github.com/ptr727/ProjectTemplate`, installs them for every repo touched from that machine. `python3 scripts/skills_install.py --report`, also from a hub checkout, says whether this machine is current. A rule that keeps needing to be restated is a sign the install is missing or stale, not that the rule does not exist. Keeping a repo's own carried `.github/copilot-instructions.md` in sync with the hub, without losing that repo's own "Disproved Claims" ledger entries in the process, is `copilot-instructions-keeper`, a skill about maintaining that file rather than a rule extracted from it, since the file itself is read directly by the Copilot bot and stays fully intact everywhere it is carried. Checking, from inside this repo's own session with no hub checkout and no operator watching, whether this repo and this machine are actually current against the hub is `fleet-conformance-check`, new content rather than a rule extracted from a section, the counterpart to `resync-a-repo` that runs with no named target other than the repo the session is already in. diff --git a/RESYNC.md b/RESYNC.md index db7e763e..63fcd3d0 100644 --- a/RESYNC.md +++ b/RESYNC.md @@ -55,7 +55,7 @@ python3 spec/fidelity_honesty.py --report # regenerate reports/divergences The order is load-bearing. Each step below either changes the rules the later steps are judged against, or removes something a later step would otherwise refresh. -1. **The instruction set first.** `AGENTS.md` and `GOVERNANCE.md` verbatim sections, then `CODESTYLE.md` and `WORKFLOW.md`. These are the rules for producing every other file, so carrying them last means everything touched beforehand was judged against the previous revision. This is the same closing-window shape as [`STANDUP.md`][standup] section 1A, and the cost of getting it wrong is rework proportional to how much was changed first. +1. **The instruction set first.** `AGENTS.md` and `GOVERNANCE.md` verbatim sections, then `CODESTYLE.md` and `WORKFLOW.md`. `AGENTS.md`'s skill-dependency pointer paragraph, naming `scripts/skills_install.py` and where the fleet's Skills live, carries as one more verbatim unit in this same step, not a separate pass. These are the rules for producing every other file, so carrying them last means everything touched beforehand was judged against the previous revision. This is the same closing-window shape as [`STANDUP.md`][standup] section 1A, and the cost of getting it wrong is rework proportional to how much was changed first. **Run the `carried-instruction-file-guard` skill's distinctive-phrase probe before any verbatim re-vendor in this step, every time, without exception.** A diff that looks routine is exactly the shape the AGENTS.md-overwrite incident took, so the probe is not weighed against how routine the request sounds, it runs regardless. `resync-a-repo` packages this whole step, and the rest of this section, as a Skill for a hub-context session driving the resync. 2. **Deletions second, before any re-vendor.** A `hub-only:` finding names a file the hub hosts rather than carries, and its remedy removes the file. Doing it after the re-vendors means refreshing a copy that is about to be deleted, which is wasted work that also reads as a deliberate update in the diff. See section 4, which is the whole of what deletion means here. 3. **Verbatim re-vendors.** Copy the current hub canonical down, whole file or the one named `## heading` region. A finding classified **stale** matches a past hub revision and needs no judgment. One classified **modified** matches no revision, so the repository changed fixed content and the change is read before it is overwritten, since it may be an improvement the hub should adopt instead. 4. **Interface workflows.** Honor the named contract (required jobs, the ruleset-bound check name, the artifact-name handoff) rather than copying bytes. The body is the repository's own. From 5940154bf526495b2265af67a6b365151b81815a Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Thu, 13 Aug 2026 08:45:42 -0700 Subject: [PATCH 2/4] Fix self-contradicting hub-checkout wording in fleet-conformance-check The skill's description said it runs with no hub checkout required, while its own steps instruct fetching one to reach scripts/skills_install.py. Both are true at once: no *standing* checkout is needed to invoke the skill or name a target, but the check itself fetches one transiently to reach hub-hosted tooling, per Hub-Hosted Tooling. Reworded the skill's description and AGENTS.md's pointer paragraph to say both halves instead of only the first. Co-Authored-By: Claude Sonnet 5 --- .agents/skills/fleet-conformance-check/SKILL.md | 13 ++++++++----- .claude-plugin/fleet-skills/.source-digest | 2 +- .../skills/fleet-conformance-check/SKILL.md | 13 ++++++++----- AGENTS.md | 2 +- 4 files changed, 18 insertions(+), 12 deletions(-) diff --git a/.agents/skills/fleet-conformance-check/SKILL.md b/.agents/skills/fleet-conformance-check/SKILL.md index b40cfbac..bbf68f07 100644 --- a/.agents/skills/fleet-conformance-check/SKILL.md +++ b/.agents/skills/fleet-conformance-check/SKILL.md @@ -5,11 +5,14 @@ description: >- current against the ptr727/ProjectTemplate hub, and safely self-applies what it can. Use this whenever asked to check if this repo is up to date with the hub, whenever a fleet rule or Skill seems to not be applying and the cause is unclear, or whenever about to work in a fleet repo and - wanting to confirm the ground under that work is current before trusting it. Runs with no hub - checkout required and no named target repo other than the one the session is already in, the - counterpart to resync-a-repo, which needs both and drives change from the hub side instead. Also - triggers on "why do I have to keep restating this rule every session," since a stale or missing - Skills install is the most common cause and the cheapest one to rule out first. + wanting to confirm the ground under that work is current before trusting it. Needs no standing + hub checkout of its own and no named target repo, only the repo the session is already in, + though the check itself fetches a hub checkout to reach scripts/skills_install.py, since + scripts/ is hub-hosted rather than carried. This is the counterpart to resync-a-repo, which + needs both a hub checkout already in hand and a named external target to drive change from the + hub side instead. Also triggers on "why do I have to keep restating this rule every session," + since a stale or missing Skills install is the most common cause and the cheapest one to rule + out first. --- # Fleet Conformance Check diff --git a/.claude-plugin/fleet-skills/.source-digest b/.claude-plugin/fleet-skills/.source-digest index e473d1f1..3753b2c7 100644 --- a/.claude-plugin/fleet-skills/.source-digest +++ b/.claude-plugin/fleet-skills/.source-digest @@ -1 +1 @@ -3dcf4120b8c55db3 +fbe11ecba7636f46 diff --git a/.claude-plugin/fleet-skills/skills/fleet-conformance-check/SKILL.md b/.claude-plugin/fleet-skills/skills/fleet-conformance-check/SKILL.md index b40cfbac..bbf68f07 100644 --- a/.claude-plugin/fleet-skills/skills/fleet-conformance-check/SKILL.md +++ b/.claude-plugin/fleet-skills/skills/fleet-conformance-check/SKILL.md @@ -5,11 +5,14 @@ description: >- current against the ptr727/ProjectTemplate hub, and safely self-applies what it can. Use this whenever asked to check if this repo is up to date with the hub, whenever a fleet rule or Skill seems to not be applying and the cause is unclear, or whenever about to work in a fleet repo and - wanting to confirm the ground under that work is current before trusting it. Runs with no hub - checkout required and no named target repo other than the one the session is already in, the - counterpart to resync-a-repo, which needs both and drives change from the hub side instead. Also - triggers on "why do I have to keep restating this rule every session," since a stale or missing - Skills install is the most common cause and the cheapest one to rule out first. + wanting to confirm the ground under that work is current before trusting it. Needs no standing + hub checkout of its own and no named target repo, only the repo the session is already in, + though the check itself fetches a hub checkout to reach scripts/skills_install.py, since + scripts/ is hub-hosted rather than carried. This is the counterpart to resync-a-repo, which + needs both a hub checkout already in hand and a named external target to drive change from the + hub side instead. Also triggers on "why do I have to keep restating this rule every session," + since a stale or missing Skills install is the most common cause and the cheapest one to rule + out first. --- # Fleet Conformance Check diff --git a/AGENTS.md b/AGENTS.md index 194a1e4f..18d9c6e6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -88,4 +88,4 @@ Every rule below is a level-two section of [`GOVERNANCE.md`](./GOVERNANCE.md). R | The About panel, description, or repo toggles | `Repository Details` | | Where a file belongs in the tree | `Repository Layout` | -Some of the rules above are also packaged as Claude Code / opencode / Codex Skills, hand-authored at `.agents/skills/` in the hub (not a repo-relative link here, since that path is hub-local and not carried into every fleet repo), so they surface automatically instead of needing to be re-read every session. `scripts/` is hub-hosted and reached rather than carried, per "Hub-Hosted Tooling", so run the installer from a hub checkout: `python3 scripts/skills_install.py` (or the `.sh`/`.ps1` wrapper) once per machine, from `github.com/ptr727/ProjectTemplate`, installs them for every repo touched from that machine. `python3 scripts/skills_install.py --report`, also from a hub checkout, says whether this machine is current. A rule that keeps needing to be restated is a sign the install is missing or stale, not that the rule does not exist. Keeping a repo's own carried `.github/copilot-instructions.md` in sync with the hub, without losing that repo's own "Disproved Claims" ledger entries in the process, is `copilot-instructions-keeper`, a skill about maintaining that file rather than a rule extracted from it, since the file itself is read directly by the Copilot bot and stays fully intact everywhere it is carried. Checking, from inside this repo's own session with no hub checkout and no operator watching, whether this repo and this machine are actually current against the hub is `fleet-conformance-check`, new content rather than a rule extracted from a section, the counterpart to `resync-a-repo` that runs with no named target other than the repo the session is already in. +Some of the rules above are also packaged as Claude Code / opencode / Codex Skills, hand-authored at `.agents/skills/` in the hub (not a repo-relative link here, since that path is hub-local and not carried into every fleet repo), so they surface automatically instead of needing to be re-read every session. `scripts/` is hub-hosted and reached rather than carried, per "Hub-Hosted Tooling", so run the installer from a hub checkout: `python3 scripts/skills_install.py` (or the `.sh`/`.ps1` wrapper) once per machine, from `github.com/ptr727/ProjectTemplate`, installs them for every repo touched from that machine. `python3 scripts/skills_install.py --report`, also from a hub checkout, says whether this machine is current. A rule that keeps needing to be restated is a sign the install is missing or stale, not that the rule does not exist. Keeping a repo's own carried `.github/copilot-instructions.md` in sync with the hub, without losing that repo's own "Disproved Claims" ledger entries in the process, is `copilot-instructions-keeper`, a skill about maintaining that file rather than a rule extracted from it, since the file itself is read directly by the Copilot bot and stays fully intact everywhere it is carried. Checking, from inside this repo's own session with no operator watching, whether this repo and this machine are actually current against the hub is `fleet-conformance-check`, new content rather than a rule extracted from a section, the counterpart to `resync-a-repo` that needs no standing hub checkout or named target beyond the repo the session is already in, even though its own check fetches a hub checkout to reach `scripts/skills_install.py`. From 43fb9da21d8fef43f6e7057a8c58a850ad3af88a Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Thu, 13 Aug 2026 08:50:09 -0700 Subject: [PATCH 3/4] Fix inline code span broken across a line wrap in resync-a-repo CommonMark code spans cannot contain a line break, so the repo-config/configure.sh command wrapped mid-span rendered inconsistently and was easy to copy incorrectly. Moved the wrap point outside the backticks and regenerated the dist copy. Co-Authored-By: Claude Sonnet 5 --- .agents/skills/resync-a-repo/SKILL.md | 6 +++--- .claude-plugin/fleet-skills/.source-digest | 2 +- .claude-plugin/fleet-skills/skills/resync-a-repo/SKILL.md | 6 +++--- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/.agents/skills/resync-a-repo/SKILL.md b/.agents/skills/resync-a-repo/SKILL.md index 48cc7e3d..02fa1305 100644 --- a/.agents/skills/resync-a-repo/SKILL.md +++ b/.agents/skills/resync-a-repo/SKILL.md @@ -61,9 +61,9 @@ earlier in the session. improvement the hub should adopt instead of a mistake to erase. 4. **Interface workflows.** Honor the named contract, required jobs, the ruleset-bound check name, the artifact-name handoff, rather than copying bytes. -5. **Settings, rulesets, and secrets.** Run `repo-config/configure.sh check / - release|operational` against the repo by name, then `apply` for what it reports, never from a - carried copy. +5. **Settings, rulesets, and secrets.** Run + `repo-config/configure.sh check / release|operational` against the repo by name, + then `apply` for what it reports, never from a carried copy. 6. **Intent files last, and by hand,** since nothing mechanical judges these. Reconcile the registry entry (`status`, `types`, `releaseTrigger`, `workflowModel`, diff --git a/.claude-plugin/fleet-skills/.source-digest b/.claude-plugin/fleet-skills/.source-digest index 3753b2c7..f5baef10 100644 --- a/.claude-plugin/fleet-skills/.source-digest +++ b/.claude-plugin/fleet-skills/.source-digest @@ -1 +1 @@ -fbe11ecba7636f46 +83bed0a67451e3ff diff --git a/.claude-plugin/fleet-skills/skills/resync-a-repo/SKILL.md b/.claude-plugin/fleet-skills/skills/resync-a-repo/SKILL.md index 48cc7e3d..02fa1305 100644 --- a/.claude-plugin/fleet-skills/skills/resync-a-repo/SKILL.md +++ b/.claude-plugin/fleet-skills/skills/resync-a-repo/SKILL.md @@ -61,9 +61,9 @@ earlier in the session. improvement the hub should adopt instead of a mistake to erase. 4. **Interface workflows.** Honor the named contract, required jobs, the ruleset-bound check name, the artifact-name handoff, rather than copying bytes. -5. **Settings, rulesets, and secrets.** Run `repo-config/configure.sh check / - release|operational` against the repo by name, then `apply` for what it reports, never from a - carried copy. +5. **Settings, rulesets, and secrets.** Run + `repo-config/configure.sh check / release|operational` against the repo by name, + then `apply` for what it reports, never from a carried copy. 6. **Intent files last, and by hand,** since nothing mechanical judges these. Reconcile the registry entry (`status`, `types`, `releaseTrigger`, `workflowModel`, From 0a01dfee41fae9fbb2a23b4c8b2385ee7164f97a Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Thu, 13 Aug 2026 08:56:13 -0700 Subject: [PATCH 4/4] Disambiguate the spec/audit.py placeholder in resync-a-repo was used for spec/audit.py's registry-name argument, while / named an unrelated owner/repo slug a few lines later, so a reader could not tell whether the argument was a checkout path, a slug, or the registry name. Renamed to , matching the tool's own --help metavar, and named it as the registry name field explicitly. Regenerated the dist copy. Co-Authored-By: Claude Sonnet 5 --- .agents/skills/resync-a-repo/SKILL.md | 7 ++++--- .claude-plugin/fleet-skills/.source-digest | 2 +- .claude-plugin/fleet-skills/skills/resync-a-repo/SKILL.md | 7 ++++--- 3 files changed, 9 insertions(+), 7 deletions(-) diff --git a/.agents/skills/resync-a-repo/SKILL.md b/.agents/skills/resync-a-repo/SKILL.md index 02fa1305..011d68d4 100644 --- a/.agents/skills/resync-a-repo/SKILL.md +++ b/.agents/skills/resync-a-repo/SKILL.md @@ -29,9 +29,10 @@ change from one resync to the next. Read RESYNC.md section 0. A repo with no instruction set at all, or a partial one, is not this skill's job, it is STANDUP.md sections 1A and 2 instead, since an absent carried file is a -baseline that never arrived rather than drift to converge. Run `spec/audit.py ` and read -whether the findings are letters (absent) or drift (present but stale) before doing anything else. -The finding kind names the procedure the repo is owed. +baseline that never arrived rather than drift to converge. Run `spec/audit.py `, the +target's `registry/repos.json` `name` field rather than an `owner/repo` slug or a checkout path, +and read whether the findings are letters (absent) or drift (present but stale) before doing +anything else. The finding kind names the procedure the repo is owed. ## Reach the hub and measure before changing anything diff --git a/.claude-plugin/fleet-skills/.source-digest b/.claude-plugin/fleet-skills/.source-digest index f5baef10..0e5e9ed0 100644 --- a/.claude-plugin/fleet-skills/.source-digest +++ b/.claude-plugin/fleet-skills/.source-digest @@ -1 +1 @@ -83bed0a67451e3ff +5d298d74098bac47 diff --git a/.claude-plugin/fleet-skills/skills/resync-a-repo/SKILL.md b/.claude-plugin/fleet-skills/skills/resync-a-repo/SKILL.md index 02fa1305..011d68d4 100644 --- a/.claude-plugin/fleet-skills/skills/resync-a-repo/SKILL.md +++ b/.claude-plugin/fleet-skills/skills/resync-a-repo/SKILL.md @@ -29,9 +29,10 @@ change from one resync to the next. Read RESYNC.md section 0. A repo with no instruction set at all, or a partial one, is not this skill's job, it is STANDUP.md sections 1A and 2 instead, since an absent carried file is a -baseline that never arrived rather than drift to converge. Run `spec/audit.py ` and read -whether the findings are letters (absent) or drift (present but stale) before doing anything else. -The finding kind names the procedure the repo is owed. +baseline that never arrived rather than drift to converge. Run `spec/audit.py `, the +target's `registry/repos.json` `name` field rather than an `owner/repo` slug or a checkout path, +and read whether the findings are letters (absent) or drift (present but stale) before doing +anything else. The finding kind names the procedure the repo is owed. ## Reach the hub and measure before changing anything