Repository navigation
feat(implement): bring the writing rules to target repositories (v0.3.6) - #113
Merged
Merged
Conversation
A confirmed finding triggers each step. The owner can also ask for it by name in Stage 1 (extra.agt-12, extra.doc-05); that change has no finding for the re-audit to confirm, so the pull request says so. Roadmap-Step: I1 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…gents-md Closes AGT-12. A new step adds the section from the greenfield AGENTS.md section 8.1 template: the reader persona the owner confirmed, bottom line first, plain language, the report layouts and the decision layout. The Inputs ask for the persona and the docs language and offer a long-form rules file. A reader persona is a communication rule, so the AGT-11 moves and the Do-not-do list leave it alone. Roadmap-Step: I2 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Closes DOC-05 as far as rules go. The greenfield style guide gains section 8 (plain language: rules 1 to 6 with the DOC-05 limits) and section 9 (diagrams). establish-docs-contract step 3 adds the two sections from that template, keeps an existing guide's text, and holds the pages the theme writes to the rules. Prose debt on other pages is recorded, not rewritten. Roadmap-Step: I3 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
implement/playbooks/templates/docs_prose_check.py carries the three rules of dev/prose_check.py and adds --max-issues (exit 1 above a count, for a ratchet) and --diagram-dir. establish-docs-contract flags it and offers two answers: skip (the default; the DOC-05 counts become debt), or copy it under a licence the owner names. A copy never carries this repository's licence. A parity test holds the template equal to dev/prose_check.py and the engine's DOC-05 port. The implement skill bundle carries the template beside the playbooks. The stack profiles say how each stack runs it. Roadmap-Step: I4 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ication Conflicts resolved by keeping both sides: - establish-docs-contract: dev's ADR policy page and lean ADRs, plus the DOC-05 rows, Inputs 6 (prose check) and the step 3 plain-language rules. NAV-03 findings became Inputs 7. - build_skills.py docstring: the ADR policy and template, plus the playbook templates. - implement-master.md regenerated. The markdownlint count fell to 646; the baseline follows. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ad0e4b5 left "## 8. ADR life## 8. ADR lifecycle" and cut the heading of section 9 to "s not go in docs/", so its table had no heading. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ADR 0004 reversed a ratchet that counted every long sentence: a sentence of 26 to 40 words is often the clearest one. The target's copy now runs with --min-severity warning on both ratchet runs, and a third run shows the notices as advice. Roadmap-Step: I4 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
establish-docs-contract records one debt entry per DOC-05 measure, with the worst pages in the note. No page is rewritten, even with format.mass_reformat=yes: a rewrite needs the owner to name the pages (extra.prose-rewrite), one commit per page. A page the theme edits joins the clean list only once it passes. adapt-agents-md rewords nothing in AGENTS.md beyond the new section and records no prose debt for it. Roadmap-Step: I5 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The AGT-12 and prose-check questions become numbered questions with lettered options and a default, as the decision-request layout asks. Each "say so in the pull request" line now names its done-report heading: What changed, How it was checked or What was not done. Roadmap-Step: I6 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A comm report variant audits stockroom with a small overlay: an AGENTS.md with no rules for writing to people, and docs pages with prose debt. build-reports --variant comm builds it alone, so the base and planted reports stay as they are. Two scenarios, comm-docs-contract (T6) and comm-agents-md (T7), and four assertions: A9 the AGENTS.md section names the confirmed reader and AGT-12 passes on re-audit; A10 the style guide has both sections and DOC-05 cites no page the theme wrote; A11 the prose check copy carries the owner's licence and its ratchet holds; A12 no earlier docs page was rewritten. Each runs on hand-made good and bad outcomes in make check. No headless run yet. Roadmap-Step: I7 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… target The implement how-to and the recipes overview now say what the AGENTS.md and docs themes add for AGT-12 and DOC-05, that existing pages are counted as debt, and that the prose check is copied only under a licence the owner names. The greenfield templates already carry both sections (I3, v0.3.4 T1). Roadmap-Step: I8 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…-communication The one conflict, .secrets.baseline, is regenerated: dev's entries plus the comm report's two commit-hash lines. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A copy of the prose check template carries MIT, Apache-2.0 or BSD-3-Clause, as the owner picks, and keeps the template's copyright line. Any other licence falls back to skip, so no owner labels the file as their own proprietary code. Where the target keeps a third-party notices file, the copy is listed there. A11 now fails when the copyright line is replaced. implement/AGENTS.md: code in playbooks/templates/ is relicensed on copy, so only its copyright holder changes it, or a contributor who agrees in writing. Roadmap-Step: I4 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…-communication Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This was referenced Nov 10, 2026
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.
The implement recipe now brings the framework's writing rules to the repositories it fixes (v0.3.6, items I1 to I8). It closes
AGT-12andDOC-05findings, records existing prose debt instead of rewriting pages, and offers a prose check only under a permissive licence the owner picks.What changed
31f9a9a): a confirmed finding triggers theAGT-12andDOC-05steps; the owner can also ask by name (extra.agt-12,extra.doc-05).87940ae):adapt-agents-mdwrites a "How to write for people" section from greenfieldAGENTS.md§8.1, with the reader persona the owner confirms. A reader persona is no longer treated as generic text underAGT-11.4d78aea):establish-docs-contractadds "Plain language" and "Diagrams" sections to the style guide; greenfield style guide §8 and §9.b4e5fbe,9c7ba80,d2bf4ca):implement/playbooks/templates/docs_prose_check.py, with--max-issuesand--diagram-dir. By default no tool is added. A copy is made only underMIT,Apache-2.0orBSD-3-Clause, never this repository's licence, and it keeps the copyright line. Its ratchet counts warnings only (ADR 0004). A parity test holds it equal todev/prose_check.pyand the engine'sDOC-05. The implement skill bundle carries it.4a1f495): existing prose is recorded as debt (one entry per measure, worst pages in the note), never rewritten, even withformat.mass_reformat=yes.2aa044e): the new questions use lettered options; pull request notes name their done-report heading.ce0eeda): a smallcommreport variant, scenarioscomm-docs-contractandcomm-agents-md, and assertions A9 to A12, each run on hand-made good and bad outcomes inmake check.907fd76): the implement how-to and the recipes overview.c9dc09f): twodocs/STYLE_GUIDE.mdheadings thatad0e4b5(docs: an agent-tuned ADR policy, a lean template and every ADR converted #110) damaged are restored.implement/AGENTS.md: code inplaybooks/templates/is relicensed on copy, so only its copyright holder changes it, or a contributor who agrees in writing.How it was checked
make check,make security,make docs-lint: passed after each item and on the last merge (origin/dev feat(dev): adr-lint checks the engine index and mentions of missing ADRs #112).make coverageandmake self-audit: passed on the I8 merge;make coveragepassed again after the licence commit.make commit-lint RANGE=origin/dev..HEAD: 11 subjects pass.What was not done
comm-docs-contract,comm-agents-md, and the A8 re-run ofapply-with-debt) were not run, sodocs/reference/eval-results.mdhas no new row.🤖 Generated with Claude Code