Package Comment and Doc Style as a Skill

[ptr727]

Package Comment and Doc Style as a Skill

Phase 3 of the hub-docs-to-Skills conversion (Phase 0/1 shipped in #676,
Phase 2 in #677).

What this adds

• comment-and-doc-style, extracted from CODESTYLE.md's General section
  (Tooling Names and Casing, Markdown and Spelling) plus GOVERNANCE.md's
  Documentation Style Conventions and Pull Request Title and Commit
  Message Conventions sections: naming tools in prose, Markdown linting
  and spelling, Markdown formatting, comment philosophy, the ASCII
  character-set tiers, line endings, the carried-file coordination
  reference ban, and PR title/commit message conventions.
• Three references/ files for progressive disclosure: line-endings.md
  (the full CRLF/LF policy), carried-doc-references.md (the full
  coordination-reference rule and its two exceptions), and
  markdown-links.md (the full reference-style-link convention).

What changed in existing files

• CODESTYLE.md's General section: Tooling Names and Casing and Markdown
  and Spelling shrink to pointers at the skill. Clean-Compile
  Verification and Analyzer Diagnostics and Suppressions are untouched,
  they are build-gate topics, not comment or doc style.
• GOVERNANCE.md's Pull Request Title and Commit Message Conventions and
  Documentation Style Conventions sections shrink to pointers, per this
  project's standing decision that a skill becomes the sole canonical
  content for its topic once one exists. The Comments, Character Set,
  and Line Endings headings stay in place (spec/files.json and
  spec/project-types.json anchor to them by name), their content is now
  a one-line pointer each.
• AGENTS.md's Where the Rules Live table routes both rows to the new
  skill.
• .claude-plugin/fleet-skills/ regenerated via scripts/build_dist.py to
  carry the new skill alongside the three from Phases 1 and 2.

Verification performed

• scripts/prose_lint.py, CRLF byte-integrity (all touched files remain
  100% CRLF), editorconfig-checker (docker), spec/validate.py,
  markdownlint-cli2, scripts/test_build_dist.py +
  scripts/test_skills_install.py (46 tests) all clean.
• scripts/build_dist.py --check confirms the generated plugin is
  current relative to .agents/skills/.

🤖 Generated with Claude Code
Co-Authored-By: Claude Sonnet 5 noreply@anthropic.com

[Copilot]

Pull request overview

Packages the fleet’s comment/doc/prose conventions into a new comment-and-doc-style Skill, then updates hub documentation to point to that Skill as the canonical source and includes the Skill in the generated Claude plugin distribution.

Changes:

• Add the new comment-and-doc-style Skill (plus three “references/” docs) under .agents/skills/ and in the generated .claude-plugin/fleet-skills/ distribution.
• Replace the detailed prose in GOVERNANCE.md and parts of CODESTYLE.md with concise pointers to the Skill.
• Update AGENTS.md routing and register the new skill in the Claude plugin manifest + digest.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
GOVERNANCE.md	Replaces PR-title/doc-style rule text with pointers to the new Skill while keeping anchored headings.
CODESTYLE.md	Shrinks general “Tooling Names and Casing” + “Markdown and Spelling” to point at the Skill.
AGENTS.md	Routes “PR title/commit message” and “doc/comment style” rows to the new Skill.
.agents/skills/comment-and-doc-style/SKILL.md	Adds canonical Skill content for comment/doc/prose conventions.
.agents/skills/comment-and-doc-style/references/markdown-links.md	Adds reference-style-link deep-dive reference doc.
.agents/skills/comment-and-doc-style/references/line-endings.md	Adds line-ending policy deep-dive reference doc.
.agents/skills/comment-and-doc-style/references/carried-doc-references.md	Adds carried-doc “no coordination references” deep-dive reference doc.
.claude-plugin/fleet-skills/skills/comment-and-doc-style/SKILL.md	Generated Skill copy for Claude plugin distribution.
.claude-plugin/fleet-skills/skills/comment-and-doc-style/references/markdown-links.md	Generated reference doc copy for Claude plugin distribution.
.claude-plugin/fleet-skills/skills/comment-and-doc-style/references/line-endings.md	Generated reference doc copy for Claude plugin distribution.
.claude-plugin/fleet-skills/skills/comment-and-doc-style/references/carried-doc-references.md	Generated reference doc copy for Claude plugin distribution.
.claude-plugin/fleet-skills/.claude-plugin/plugin.json	Registers comment-and-doc-style in the plugin’s skills list.
.claude-plugin/fleet-skills/.source-digest	Updates the dist source digest to reflect the new Skill content.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.

Suppressed comments (2)

scripts/test_prose_lint.py:1352

• This docstring splits a sentence across lines ("That makes a" / "finding ..."), leaving a fragment line and violating the project’s one-sentence-per-line comment style. Reflow so each line is a complete sentence.

 correct-as-you-next-edit assumes someone able to edit the file, and a downstream repo cannot
edit a verbatim one, since its copy is byte-matched against the hub's. So the hub sweeps the
class and re-vendors. That makes a
finding in a verbatim file different in kind from the tree-wide backlog: it is not a
correction owed by whoever next edits the file, it is one no downstream repo can make at all.

scripts/test_prose_lint.py:136

• The docstring sentence uses a comma splice (two independent clauses joined by a comma), which reads as a grammatical error. Split into two sentences (or add a conjunction) to keep the prose clear.

This issue also appears on line 1348 of the same file.

 The Character Set rule text lives in the comment-and-doc-style Skill, GOVERNANCE.md's own
section is a pointer at it, per the "skill becomes sole canonical content" decision. These are

[ptr727]

Answering the 2 suppressed findings from round 2 (#678 (review), commit 9542bef):

scripts/test_prose_lint.py:1352
This docstring splits a sentence across lines ("That makes a" / "finding ..."), leaving a fragment line and violating the project's one-sentence-per-line comment style. Reflow so each line is a complete sentence.

Fixed in 23057d2: rewrapped the paragraph so no line ends on an orphaned fragment.

scripts/test_prose_lint.py:136
The docstring sentence uses a comma splice (two independent clauses joined by a comma), which reads as a grammatical error. Split into two sentences (or add a conjunction) to keep the prose clear.

Fixed in 23057d2: split into two sentences.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.

Suppressed comments (3)

GOVERNANCE.md:148

• This paragraph says the section "only points" to the skill, but the section also includes a summary of the contract in the preceding line. Rewording this avoids a self-contradiction and keeps the pointer text accurate.

This is packaged as the `comment-and-doc-style` Skill at `.agents/skills/comment-and-doc-style/SKILL.md` in the hub, not a repo-relative link since that path is hub-local and not carried into every fleet repo. Read the skill for the full rules, since this section only points to it now rather than carrying the contract text itself.

scripts/test_prose_lint.py:132

• The test class name is now misleading: it no longer couples to GOVERNANCE.md (it parses the comment-and-doc-style Skill). Renaming the class will keep intent clear and make future greps/CI output easier to understand.

class TestGovernanceCoupling(unittest.TestCase):

GOVERNANCE.md:142

• This paragraph says the section "only points" to the skill, but the preceding line still states the contract rules. Reword to avoid contradicting the section contents and reduce the risk of the summary drifting from the skill over time.

This issue also appears on line 148 of the same file.

This is packaged as the `comment-and-doc-style` Skill at `.agents/skills/comment-and-doc-style/SKILL.md` in the hub, not a repo-relative link since that path is hub-local and not carried into every fleet repo. Read the skill for the full format, rules, and examples, since this section only points to it now rather than carrying the contract text itself.

[ptr727]

Answering the 3 suppressed findings from round 3 (#678 (review), commit 23057d2):

GOVERNANCE.md:148
This paragraph says the section "only points" to the skill, but the section also includes a summary of the contract in the preceding line. Rewording this avoids a self-contradiction and keeps the pointer text accurate.

Fixed in 83e510d: reworded to "the summary above sketches the contract, read the skill for the full rules" and swept the same construction elsewhere in the file (see below).

scripts/test_prose_lint.py:132
The test class name is now misleading: it no longer couples to GOVERNANCE.md (it parses the comment-and-doc-style Skill). Renaming the class will keep intent clear and make future greps/CI output easier to understand.

Fixed in 83e510d: renamed to TestCommentAndDocStyleSkillCoupling.

GOVERNANCE.md:142
This paragraph says the section "only points" to the skill, but the preceding line still states the contract rules. Reword to avoid contradicting the section contents and reduce the risk of the summary drifting from the skill over time.
This issue also appears on line 148 of the same file.

Fixed in 83e510d: same reword as above. Also swept and fixed the same pre-existing construction in the "PR Review Etiquette" section (merged in #677), since it is the identical pattern in the same file, not just the two instances flagged.

Also confirming, from round 2: the two prose findings on scripts/test_prose_lint.py (the fragment line at what was then line 1352, and the comma splice at what was then line 136) were fixed in 23057d2 and answered in #678 (comment), they are still showing as "earlier round, unanswered" in the status digest quoting stale pre-fix text, the fix and the answer both predate this round's review.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.

Suppressed comments (2)

.agents/skills/comment-and-doc-style/SKILL.md:91

• The comment guidance says governance lives in GOVERNANCE.md, but this PR moves the canonical comment/doc rules into the comment-and-doc-style Skill. To avoid the pointer going stale again (or reading as a contradiction inside the skill), rephrase this to refer to the canonical instruction set rather than a specific file.

- State only the non-obvious *why*, for the human reading *this* project's code now. No
cross-project references, no historic or design narrative, no rule citations (governance lives
in `GOVERNANCE.md`, not echoed inline).

.claude-plugin/fleet-skills/skills/comment-and-doc-style/SKILL.md:91

• Same as the source skill: this sentence hard-codes GOVERNANCE.md as the sole governance location, but the PR makes the skill canonical for this topic. Rephrase to avoid a file-specific claim that will drift again.

- State only the non-obvious *why*, for the human reading *this* project's code now. No
cross-project references, no historic or design narrative, no rule citations (governance lives
in `GOVERNANCE.md`, not echoed inline).

[ptr727]

Answering the 2 new suppressed findings from round 4 (#678 (review), commit 83e510d), plus confirming round 2/3's findings are all fixed and answered (the digest keeps re-quoting stale pre-fix text since none of these ever had a thread to resolve):

.agents/skills/comment-and-doc-style/SKILL.md:91 and .claude-plugin/fleet-skills/skills/comment-and-doc-style/SKILL.md:91
The comment guidance says governance lives in GOVERNANCE.md, but this PR moves the canonical comment/doc rules into the comment-and-doc-style Skill. Rephrase to refer to the canonical instruction set rather than a specific file.

Fixed in 7496b7b: reworded to "governance lives in the fleet's own instruction set, not echoed inline", so it does not name a specific file that can go stale the next time content moves.

Round 2 findings (scripts/test_prose_lint.py:1352 fragment line, :136 comma splice) were fixed in 23057d2, answered in #issuecomment-5281713654.
Round 3 findings (GOVERNANCE.md:142/148 pointer self-contradiction, test class rename) were fixed in 83e510d, answered in #issuecomment-5281786109.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.