State the purpose as agent enablement, not orchestration - #492
Merged
Conversation
The tagline described the repo by its contents: governance, orchestration and workflow audit. That names the machinery and not what the machinery is for, so a reader learns what is in here without learning why any of it exists. The purpose is agent enablement. An agent is fast and inconsistent, so a fleet built by one drifts a different way in every repository, and the drift stays invisible until something breaks where it matters. What this repo makes repeatable is the outcome, so an agent stands a repository up, changes it and releases it on its own, and lands in the same known-good shape every time. Framing the rules as guardrails rather than governance also states their direction correctly. They exist to widen what an agent may do unattended, by removing a decision it would otherwise make differently every time or by making a failure loud that would otherwise pass green. Write safety, the review loop and the audit are what make the autonomy safe to grant, and autonomy extends exactly as far as the verification reaches. The third paragraph records that none of it is finished. Every rule traces to a specific failure, nearly all observed in this fleet rather than imagined, and a procedure that lets a new one through is corrected as part of the work that found it. The same sentence opens README.md, HISTORY.md and AGENTS.md, so all three move together. The GitHub About description is derived from the README line and is updated after this merges. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the repository’s “tagline” framing across the main entry-point docs to clearly state that ProjectTemplate’s purpose is agent enablement (guardrails + verification that make autonomous agent work repeatable and safe), rather than describing the repo primarily by its internal machinery.
Changes:
- Replaces the old “governance / orchestration / audit hub” tagline with an “agent enablement” purpose statement in
README.mdandHISTORY.md. - Expands the opening “What This Repo Is” section in
README.mdto explain the motivation (repeatable outcomes, guardrails, verification). - Updates
AGENTS.md’s opening description to align with the new purpose framing for agents reading it first.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| README.md | Reframes the repo’s purpose as agent enablement, updates the release summary bullet, and expands “What This Repo Is” intro prose. |
| HISTORY.md | Updates the top-level tagline to match the new purpose framing. |
| AGENTS.md | Updates the opening repo description to describe ProjectTemplate as the agent-enablement/enablement hub. |
spec/readme-structure.md item 1 caps the one-line description at 100 characters, link-free and single-sentence, because it doubles as the GitHub About description and, for a repo publishing an image, the Docker Hub short description, where the cap is tightest. The audit checks the length. The sentence this branch introduced ran to 167 and would have failed its own readme-structure dimension. The short form keeps what has to survive compression, agent enablement and autonomy at repeatable quality inside guardrails, and drops the harm clause, which the second paragraph of What This Repo Is states at length. HISTORY.md carries the identical sentence, since the audit checks the two match. AGENTS.md now opens on the same noun phrase rather than a hyphenated adjective, so the tagline reads as one term across the three files. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
ptr727
added a commit
that referenced
this pull request
Aug 1, 2026
Moves the running backlog out of `README.md` into `TODO.md`, and makes that placement the fleet standard rather than a hub preference. ## Why the README was the wrong home `spec/readme-structure.md` lists twelve README sections and **TODO is not one of them**, so the hub's own README deviated from the structure its audit checks every fleet README against. Beyond conformance, open work does not belong on the adoption surface a reader lands on, and it changes on a different cadence from everything around it. ## What makes it a standard - **`spec/readme-structure.md` gains a `TODO.md` section**, stating that a README carries no backlog section and that the backlog lives in a root `TODO.md` with a defined shape. This is the file the `readme-structure` audit dimension reads, so the rule lands where the check already looks. - **`STANDUP.md` step 2 lists it as the fourth topical destination**, alongside `CODESTYLE.md`, `ARCHITECTURE.md`, and `OPERATIONS.md`. **It is a declared destination, not a required file**, the same footing as `ARCHITECTURE.md`, so a repo with no backlog carries no file rather than an empty one. Say the word if you would rather it be required by a selector, which would mean a `spec/files.json` entry and an empty `TODO.md` in every repo. ## Fleet impact is small, and measured Surveyed live across twelve repos: **no repo has a `TODO.md`**, and exactly **three** carry a README `## TODO` section, all of them operational config repos (HomeAssistant-Config, Vantage-Config, HomeAutomation-Config). The other nine have neither, so they are already conformant. Those three are a follow-up, not this PR. ## Two things fixed while in these files 1. **`spec/readme-structure.md` instructed authors to use the construction `GOVERNANCE.md` bans.** Its Style list said "ASCII only (no em-dash; use a spaced hyphen)", against `GOVERNANCE.md` "No spaced hyphen joining or interrupting a sentence", so an agent following the more specific file produced prose the prose gate then flagged. The bullet now defers to the tiered character rule, and the file's other 8 `dash` and `semicolon` findings are fixed in the same pass. This closes finding 1 of #489. 2. **Three real backlog items were added while moving**, rather than the list being copied unchanged: the `.editorconfig` / `.gitattributes` / `.gitignore` comment cleanup (44 findings), the `repo-config/configure.sh` sweep (54 findings, and that file is carried `verbatim` so downstream cannot fix them locally, which is finding 6 of #489), and the README's own 13 prose findings. ## The README sweep is deferred, deliberately `README.md` carries 13 `dash` and `semicolon` findings, none on lines this PR touches. Two other changes to that file are in flight (#492), so a third overlapping edit would conflict with both for no gain. It is recorded in `TODO.md` rather than left to memory, which is what that file now exists for. ## Verification - Fleet survey run live against the GitHub API, so the three-repo number is measured rather than recalled. - `prose_lint` blocking set clean tree-wide. `TODO.md`, `STANDUP.md`, and `spec/readme-structure.md` clean on the warn set too. - markdownlint clean over all four files, including the removed ToC entry and the link fragments. - No orphaned reference definitions: `[reports]` and `[repos]` are still used elsewhere in the README. - cspell clean, editorconfig-checker clean, all files CRLF-only by byte scan. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
ptr727
added a commit
that referenced
this pull request
Aug 1, 2026
…to main (#498) Promotes eight commits from `develop`. Every one traces to a defect found in use rather than to a planned change, and five came from downstream agents reporting what the procedure did not cover. ## What lands | Commit | Change | | --- | --- | | `a0f6f24` (#487) | `docs/content-import.md`, the three capture-pass findings from the Blog migration: an export is not a media capture, a sitemap is not the URL contract, and an HTTP fetch is not the original | | `8bdfa22` (#494) | The write-guard scopes by **owner** rather than exact origin, with `GH_WRITE_GUARD_ALLOW` for a different owner. Four target-flag spellings that silently bypassed rule 3 are closed | | `981d92f` (#492) | The purpose is restated as agent enablement, in `README.md`, `HISTORY.md` and `AGENTS.md` | | `275705b` (#493) | `TODO.md` becomes the fleet backlog destination, and `spec/readme-structure.md` stops mandating the construction `GOVERNANCE.md` bans | | `b6ab6db` (#491) | `STANDUP.md` step 0A names the maintainer-only prerequisites, and step 4 asserts the remote | | `89e3868` (#488) | The `version.json` floor is chosen at standup rather than inherited | | `eed2e00` (#495) | `README.md` gains "What It Achieves", the objectives and the fidelity ladder | | `f6dc5e6` (#497) | `CODESTYLE.md` stops claiming CI runs the same checks as the clean-compile | ## Provenance Five of the eight answer issues filed by downstream agents: #456 (Blog intake), #489 and #490 (the Blog carry), and #496 (Financial-Modeling). That loop is the one "What It Achieves" now describes, and this promotion is it closing. ## Divergence, checked rather than assumed `main...develop` reports `8 ahead, 102 behind, diverged`. **The 102 are topology, not content.** They are 79 promotion merge commits, which are main-only by construction because a promotion is a two-parent merge, plus 23 `Update codegen files` bot commits from this repo's pre-2.0 life as a .NET sample template. `git diff --name-status origin/develop origin/main` returns exactly the 12 files these 8 commits touch, so there is **no main-only content** to reconcile. ## Verification on the merged `develop` Every gate re-run after the last merge, not inherited from the individual PRs: - `prose_lint.py . --check charset --check dupword --check spelling` clean tree-wide. - `repo_gate.py` clean (`eol`, `sha-pin`). - `spec/validate.py` clean, 21 cataloged repos classify. - `gh-write-guard.py --selftest` passes, including the nine new repository-scope cases. - `python3 -m unittest discover -s scripts`, 180 tests pass. - The `README.md` objectives list verified as one continuous list of 8 bullets with the fidelity table nested, since an unindented table split it in review. ## Merge mechanics This is a promotion, so it merges as a **merge commit** with two parents, never a squash. Its head **is** `develop`, so `--delete-branch` must not be used. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Restates what this project is for. The tagline described the repo by its contents, governance and orchestration and workflow audit, which names the machinery without saying what the machinery is for. A reader learned what is in here without learning why any of it exists.
The framing
The purpose is agent enablement. An agent is fast and inconsistent, so a fleet built by one drifts a different way in every repository, and the drift stays invisible until something breaks where it matters. What this repo makes repeatable is the outcome: an agent stands a repository up, changes it, and releases it on its own, and lands in the same known-good shape every time.
The guardrails are what make granting that autonomy sound rather than reckless, and they are stated as enabling rather than restraining. A rule earns its place by removing a decision an agent would otherwise make differently every time, or by making a failure loud that would otherwise pass green. Write safety bounds what an agent can reach outside the project in front of it, the review loop closes before anything merges, and the audit proves the result instead of accepting the agent's report of it. Autonomy extends exactly as far as the verification reaches.
Nothing here is finished. Every rule traces to a specific failure, nearly all of them observed in this fleet rather than imagined, and a procedure that lets a new one through is corrected as part of the work that found it.
Where it lands
The same sentence opens three files, so all three move together:
README.mdHISTORY.mdAGENTS.mdTwo follow-ups this creates
README.mdcarries 16 warn-only prose findings (9dash, 7semicolon), none of them on the lines this PR touches. The standing rule corrects existing prose as a file is next edited, so they are owed. They are deliberately not in this diff, because a 16-line sweep would bury the wording you are meant to be reading. Offered as an immediate follow-up PR.Verification
prose_lintblocking set clean tree-wide, and the new prose carries nodashorsemicolonfinding of its own.README.mdandHISTORY.md, the gated scope.🤖 Generated with Claude Code