plugin: han-communication - extracting a new plugin from han-core, and consolidating guidance

.agents/plugins/marketplace.json

@@ -4,6 +4,18 @@
     "displayName": "Han"
   },
   "plugins": [
+    {
+      "name": "han-communication",
+      "source": {
+        "source": "local",
+        "path": "./han-communication"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Developer Tools"
+    },
     {
       "name": "han-core",
       "source": {

.claude-plugin/marketplace.json

@@ -10,9 +10,15 @@
     {
       "name": "han",
       "source": "./han",
-      "description": "Meta-plugin that installs the bundled Han suite. Has no components of its own; it depends on han-core, han-planning, han-coding, han-github, and han-reporting so installing it pulls them all in. Does not bundle the opt-in han-feedback, han-atlassian, or han-plugin-builder plugins.",
+      "description": "Meta-plugin that installs the bundled Han suite. Has no components of its own; it depends on han-communication, han-core, han-planning, han-coding, han-github, and han-reporting so installing it pulls them all in. Does not bundle the opt-in han-feedback, han-atlassian, or han-plugin-builder plugins.",
       "version": "4.5.1"
     },
+    {
+      "name": "han-communication",
+      "source": "./han-communication",
+      "description": "Foundational communication plugin for the Han suite. Owns the single canonical readability standard and writing-voice profile, the readability-guidance skill that surfaces them into a calling skill's context for in-voice drafting, the readability-editor agent that runs the adversarial rewrite, and the edit-for-readability skill. Depends on nothing and sits beneath every other plugin; the plugins that produce prose output depend on it.",
+      "version": "1.0.0"
+    },
     {
       "name": "han-core",
       "source": "./han-core",
@@ -28,7 +34,7 @@
     {
       "name": "han-coding",
       "source": "./han-coding",
-      "description": "Code-writing and execution skills for the Han suite. Home of the tdd skill, which drives a feature or behavior through a BDD-framed red-green-refactor loop with an enforced observed-failure gate. Depends on han-core; bundled by the han meta-plugin.",
+      "description": "Code-writing and execution skills for the Han suite. Home of the tdd skill, which drives a feature or behavior through a BDD-framed red-green-refactor loop with an enforced observed-failure gate. Depends on han-core and han-communication; bundled by the han meta-plugin.",
       "version": "2.5.1"
     },
     {
@@ -52,7 +58,7 @@
     {
       "name": "han-atlassian",
       "source": "./han-atlassian",
-      "description": "Atlassian-facing extensions to the Han suite. Adds markdown-to-confluence, which publishes a local Markdown file to a user-specified Confluence page; project-documentation-to-confluence, which runs the core project-documentation skill and then publishes the result there; investigate-to-confluence, which runs the core investigate skill and publishes the resulting investigation report there; code-overview-to-confluence, which runs the core code-overview skill and publishes the resulting overview there; plan-a-feature-to-confluence, which runs the core plan-a-feature skill and publishes the spec and its companion artifacts there as a page tree; and work-items-to-jira, which creates one Jira ticket per slice from a work-items file. All work through the Atlassian MCP server. Depends on han-core, han-planning, and han-coding (its wrapper skills run skills from each) and requires a configured Atlassian MCP server. Opt-in: installed on its own, not pulled in by the han meta-plugin.",
+      "description": "Atlassian-facing extensions to the Han suite. Adds markdown-to-confluence, which publishes a local Markdown file to a user-specified Confluence page; project-documentation-to-confluence, which runs the core project-documentation skill and then publishes the result there; investigate-to-confluence, which runs the core investigate skill and publishes the resulting investigation report there; code-overview-to-confluence, which runs the core code-overview skill and publishes the resulting overview there; plan-a-feature-to-confluence, which runs the core plan-a-feature skill and publishes the spec and its companion artifacts there as a page tree; and work-items-to-jira, which creates one Jira ticket per slice from a work-items file. All work through the Atlassian MCP server. Depends on han-core, han-planning, and han-coding (its wrapper skills run skills from each), and on han-communication (its wrapped prose-producing skills source the shared readability standard), and requires a configured Atlassian MCP server. Opt-in: installed on its own, not pulled in by the han meta-plugin.",
       "version": "2.2.0"
     },
     {

.claude/skills/han-release/references/changelog-rules.md

@@ -123,7 +123,7 @@ Full changelog: {compare-or-blob link — see release-notes-format.md}
 
 Match the register of the existing `## v{X.Y.Z}` entries already in `CHANGELOG.md`: neutral, descriptive, technical present tense ("The `/gap-analysis` swarm flips from opt-in to opt-out..."). This is **not** the first-person blog voice; it is the clipped changelog register those entries already use. The two newest existing sections are pasted into the dispatch prompt as the register model — follow them.
 
-Hard constraints from [`han-core/references/writing-voice.md`](../../../../han-core/references/writing-voice.md), applied verbatim to generated changelog prose:
+Hard constraints from [`han-communication/references/writing-voice.md`](../../../../han-communication/references/writing-voice.md), applied verbatim to generated changelog prose:
 
 - No em-dash (`—`) anywhere, ever. Use a colon, comma, parentheses, or two sentences.
 - `use`, never `leverage` or `utilize`.

.claude/skills/han-update-documentation/SKILL.md

@@ -128,7 +128,7 @@ Apply every finding from Steps 3 and 4 in place.
 
 **Creating a missing long-form doc.** Copy `docs/templates/skill-long-form-template.md` (for a skill) or `docs/templates/agent-long-form-template.md` (for an agent) into the target path. Fill in the orientation frame, TL;DR, and Key concepts from the entity's frontmatter description and step body. Leave a `<!-- TODO: human review -->` marker only at sections that require operator judgment (Sources, In more detail, examples). Surface those markers in Step 6's report so the operator can finish them.
 
-**Apply the writing voice.** Every edit follows `han-core/references/writing-voice.md`: no em-dashes, direct second person, no flattery or hype words, no `actually`, `just`, `leverage`, `utilize`, `showcase`, `robust` (as a vague positive), `It's worth noting`, or `Importantly`. When fixing a doc, do not introduce voice violations even if the surrounding doc has them.
+**Apply the writing voice.** Every edit follows `han-communication/references/writing-voice.md`: no em-dashes, direct second person, no flattery or hype words, no `actually`, `just`, `leverage`, `utilize`, `showcase`, `robust` (as a vague positive), `It's worth noting`, or `Importantly`. When fixing a doc, do not introduce voice violations even if the surrounding doc has them.
 
 **Apply YAGNI to documentation edits.** Do not add speculative sections, *for-future-flexibility* warnings, or examples for behavior the skill does not have. The YAGNI rule that gates plan steps also gates docs (see `docs/yagni.md`).
 

.claude/skills/han-update-documentation/references/scope-mapping.md

@@ -13,7 +13,7 @@ A single changed file can pull multiple entities into scope. Always add every en
 | `{plugin}/skills/{name}/SKILL.md` | skill `{name}` |
 | `{plugin}/skills/{name}/references/**` | skill `{name}` |
 | `{plugin}/skills/{name}/scripts/**` | skill `{name}` |
-| `han-core/agents/{name}.md` | agent `{name}` |
+| `{plugin}/agents/{name}.md` | agent `{name}` |
 | `docs/skills/{name}.md` | skill `{name}` |
 | `docs/skills/README.md` | skills-index |
 | `docs/agents/{name}.md` | agent `{name}` |
@@ -22,7 +22,7 @@ A single changed file can pull multiple entities into scope. Always add every en
 | `docs/quickstart.md` | quickstart |
 | `docs/sizing.md` | sizing |
 | `docs/yagni.md` | yagni |
-| `han-core/references/writing-voice.md` | writing-voice |
+| `han-communication/references/writing-voice.md` | writing-voice |
 | `han-plugin-builder/skills/guidance/references/**/*.md` | the guidance file itself |
 | `docs/templates/**/*.md` | the template file itself |
 | `README.md` | root-readme |

.github/pull_request_template.md

@@ -15,7 +15,7 @@ Work through this checklist before marking the PR ready. Leave it in the PR body
 
 - [ ] Read [CONTRIBUTING.md](../CONTRIBUTING.md) and confirm the changes follow the rules for the entity being touched (skill, agent, long-form doc, index, template).
 - [ ] Walk the [self-review checklist in CONTRIBUTING.md](../CONTRIBUTING.md#reviewing-your-own-changes): frontmatter validity, `allowed-tools` accuracy, context-injection simplicity, template adherence, index placement, link resolution, voice compliance.
-- [ ] Confirm the writing follows [`han-core/references/writing-voice.md`](../han-core/references/writing-voice.md). No em-dashes. No banned words ("actually", "just", "leverage", "utilize", "showcase", "robust" as vague positive, "It's worth noting", "Importantly").
+- [ ] Confirm the writing follows [`han-communication/references/writing-voice.md`](../han-communication/references/writing-voice.md). No em-dashes. No banned words ("actually", "just", "leverage", "utilize", "showcase", "robust" as vague positive, "It's worth noting", "Importantly").
 - [ ] If a new skill or agent was added or renamed, confirm the [coverage rule](../docs/templates/coverage-rule.md) is satisfied: long-form doc exists at `docs/skills/{plugin}/{name}.md` or `docs/agents/han-core/{name}.md`, and the index in `docs/skills/README.md` or `docs/agents/README.md` has a one-sentence scent line.
 - [ ] If a skill or agent was added, removed, or renamed, confirm the indexes ([`docs/skills/README.md`](../docs/skills/README.md), [`docs/agents/README.md`](../docs/agents/README.md)), and [`docs/concepts.md`](../docs/concepts.md) each list every current entity.
 - [ ] If the change touches plugin behavior, run the affected skill or agent locally and confirm it still works end-to-end.

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Han Release Notes
 
+## Unreleased
+
+The readability capability moves into a new foundational plugin, `han-communication`, so the suite has one owner for its writing standard and no duplicated copies. `han-communication` depends on nothing and owns the single canonical `readability-rule.md` and `writing-voice.md`, the `readability-editor` agent, the `edit-for-readability` skill, and a new inline `readability-guidance` skill that surfaces the standard into a calling skill's own context. The three vendored reference copies in `han-coding`, `han-github`, and `han-reporting`, and the four `han-core` originals, are gone; `find` returns exactly one copy of each reference file. All 13 consumer skills now source the standard by invoking `han-communication:readability-guidance`; the 9 synthesis skills additionally dispatch `han-communication:readability-editor` with no rule-path argument. Six manifests declare the new dependency edge (`han-core` takes its first-ever dependency), both marketplaces list the plugin, and the docs, indexes, and dependency narration are swept to match. No version is bumped; the bumps are deferred to release, with `han-core` flagged as a MAJOR candidate because the `han-core:readability-editor` and `han-core:edit-for-readability` namespaces are removed.
+
 ## v4.5.1
 
 han 4.5.1 is a maintenance release that guards context-injection commands against absent tools and references, normalizes user-reference wording, and sweeps the operator-facing documentation for readability. `han-core` (2.2.1) guards the `project-discovery`, `research`, and `runbook` skills and normalizes wording in the `research-analyst` agent, `issue-triage`, and `research`; `han-planning` (2.0.3) normalizes wording in its references; `han-coding` (2.5.1) guards six skills and normalizes wording in `code-overview` and `code-review`; `han-github` (2.2.1) guards `post-code-review-to-pr` and `update-pr-description` and normalizes its references; `han-reporting` (2.1.1) normalizes its references; `han-linear` (1.0.2) normalizes `work-items-to-linear` and its templates; and `han-plugin-builder` (2.0.4) guards the `guidance` skill and finishes the guarding in its command-example references. `han-feedback` (2.0.0) and `han-atlassian` (2.2.0) are unchanged.