Han v5.0.0 alpha 1 - #130
Open
mxriverlynn wants to merge 267 commits into
Open
Conversation
…s-plugin (Phase 3) All 13 consumer skills now source the shared readability standard by invoking han-communication:readability-guidance at their drafting point instead of reading a vendored ../../references/readability-rule.md file. - 9 synthesis skills: editor dispatch renamed han-core -> han-communication and the now-unresolvable rule-path argument dropped (the editor reads its own co-located canonical rule); gap-analysis's size-conditional skip preserved - 4 draft-and-self-check skills (runbook, issue-triage, ADR, html-summary): gain the guidance invocation, dispatch no editor - edit-for-readability (han-communication copy): editor rename + rule-path drop - self-check lead-ins repointed to the in-context standard; the six criteria blocks are unchanged - 6 secondary template/reference files repointed off the dead rule path Refs feature-implementation-plan.md D-3.
…s (Phase 4) With every consumer rewired and the pre-delete grep gate clean, remove the duplicated readability capability so han-communication owns the only copy. - 6 vendored references deleted (han-coding, han-github, han-reporting x readability-rule.md + writing-voice.md) - 4 han-core originals deleted (readability-editor agent, edit-for-readability skill, readability-rule.md, writing-voice.md) - find now returns exactly one copy of each reference file - no han-core:readability-editor / han-core:edit-for-readability name survives in plugin source Refs feature-implementation-plan.md D-2.
…ove (Phase 5) Repoint every doc, index, and dependency narration at the new han-communication home and reframe the invariants the move inverts. - Move long-form docs: readability-editor -> docs/agents/han-communication/, edit-for-readability -> docs/skills/han-communication/; fix their sibling links - New readability-guidance long-form doc, with the api_retry residual-risk troubleshooting note - Skills index gains a foundational han-communication section (readability-guidance + edit-for-readability); agents index entry repointed - Reframe "all agents live in han-core" to name the han-communication exception (CLAUDE.md, CONTRIBUTING.md); record han-core's first-ever dependency - Replace the vendoring instruction with cross-plugin sourcing via readability-guidance (CONTRIBUTING.md, docs/readability.md) - Repoint canonical readability-rule.md / writing-voice.md pointers, dependency narration (README, choosing-a-han-plugin, extend-han how-to), and the han-atlassian Codex co-requisite; add han-communication to both install lists - Repoint live .claude/ maintenance skills and the PR template at the new writing-voice.md location - CHANGELOG Unreleased entry records the extraction; history left untouched Refs feature-implementation-plan.md D-6, D-7, D-9.
The lint workflow added in #120 surfaced three pre-existing failures. This commit fixes the two shellcheck findings and the broken symlink. - init-guidance.sh: the first sed expression matches the literal text "${CLAUDE_PLUGIN_ROOT}" as it appears in the vendored SKILL.md, so the single quotes are required and SC2016 is a false positive. Disable the check at that call with a comment explaining why. - upload-screenshots.sh: verify_on's retry loop never reads its counter, so SC2034 fired on it. Use the conventional throwaway `_` instead. - .claude/rules/plugin-entity-taxonomy.md: the symlink still pointed at docs/guidance/, which ad6ee13 moved to han-plugin-builder/skills/guidance/references/. That commit rewrote the adjacent .claude/rules/ text references but could not catch a symlink target. Repoint it at the file's current home.
The lint workflow added in #120 runs Prettier over all files, but the repo had never been formatted with it, so the hook rewrote 279 files and failed the job. This commit lands that formatting so the hook is a no-op. Formatting only: prose is rewrapped to the 120-column width set in .prettierrc.json, emphasis markers are normalized, and table cells are padded. No prose was changed. The one non-whitespace change is in han-coding/skills/coding-standard/SKILL.md, where an ordered list was misnumbered 1, 2, 4, 5; Prettier owns ordered-list numbering per .pre-commit-config.yaml and renumbered it to 1, 2, 3, 4.
# Conflicts: # han-atlassian/.claude-plugin/plugin.json # han-coding/.claude-plugin/plugin.json # han-github/.claude-plugin/plugin.json # han-plugin-builder/skills/guidance/scripts/init-guidance.sh # han-reporting/.claude-plugin/plugin.json # han/.claude-plugin/plugin.json
…d consolidating guidance (#114) 140+ files, and +4K/-1K ... 😭 this may be the cause of a Han v5 release. still a WIP though. needs a lot of testing and fine tuning first. that said ... --- ## Summary **This PR extracts Han's readability standard into a new foundational `han-communication` plugin that every prose-producing plugin depends on, so the writing rule and voice profile live in one canonical place instead of being copy-pasted into each plugin.** ## Behavior changes The readability standard now has a single owner. Before this branch, `readability-rule.md` and `writing-voice.md` were vendored into `han-core`, `han-github`, and `han-reporting`. "Vendored" means the same files were duplicated on disk. Editing the standard meant editing several copies and hoping they stayed in sync. Now the two files live only in `han-communication/references/`, the duplicates are deleted, and there is one source of truth. Consuming skills reach the standard through a new inline skill, `han-communication:readability-guidance`. "Inline" means it runs in the calling skill's own context rather than in a separate agent. It reads the two canonical reference files and hands control straight back, so the standard stays loaded while the caller drafts and self-checks. Rewired skills (`code-review`, `research`, `update-pr-description`, `stakeholder-summary`, and others) now invoke that skill instead of reading a vendored copy. The `readability-editor` agent and the `edit-for-readability` skill also moved into `han-communication`. The adversarial rewrite pass they perform is unchanged. For anyone installing the suite, `han-communication` is a new dependency edge beneath everything. The `han` meta-plugin now bundles it, and `han-core`, `han-coding`, `han-github`, `han-reporting`, and the opt-in `han-atlassian` each declare a direct dependency on it. This is `han-core`'s first-ever dependency. Installing any prose-producing plugin now pulls in `han-communication` automatically. ## What to look at first 1. Start with `han-communication/skills/readability-guidance/SKILL.md`. It holds the new inline skill and the mechanism the whole PR turns on. Confirm that the "runs in the caller's context, does not produce a deliverable" contract reads clearly, since every consumer now depends on that behavior. 2. Check the dependency edges in the `plugin.json` manifests and `.claude-plugin/marketplace.json`. Verify that the new `han-communication` dependency is declared on each prose-producing plugin and that the meta-plugin bundles it, so no consumer sources the standard without depending on its owner. 3. Read one or two rewired consumer `SKILL.md` files, for example `han-core/skills/research/SKILL.md` and `han-github/skills/update-pr-description/SKILL.md`. Check that the cross-plugin invocation replaces the old vendored read cleanly and that nothing still points at a deleted copy. 4. Compare the Phase 4 deletions (`git show 563efec --stat`) against the Phase 3 rewiring. Confirm that every vendored copy that was removed had its consumers repointed first, so no skill is left reading a file that no longer exists.
New references/per-model-authoring.md teaches skill/agent authors how Sonnet 5, Opus 4.8, and Fable 5 differ in how you write instructions for them, anchored to a model-agnostic default. Wired into both routing maps (SKILL.md + portable copy) and the vendored rule index, with a reverse cross-reference from specialization-and-model-selection.md. Implements docs/plans/per-model-authoring-guidance/.
## Summary **This PR adds an author-time guidance doc that tells a skill or agent author how to phrase instructions when they know which Anthropic model (Sonnet 5, Opus 4.8, or Fable 5) will run them, so authoring choices match how each model actually reads instructions.** The new reference, `per-model-authoring.md`, lives in the `han-plugin-builder` guidance skill (the plugin that holds the how-to-build-plugins guidance). It leads with the default: when the target model is unknown, write model-agnostic. The one difference worth acting on is instruction style, and the models pull in opposite directions. Opus 4.8 and Sonnet 5 read instructions literally and want each behavior spelled out. Fable 5 does better with a short goal-based instruction, and degrades when handed an exhaustive checklist. The doc also flags one failure trap. On Fable 5, an instruction telling the model to echo its own internal reasoning verbatim into visible output can be refused outright. That claim rests on a single vendor source, and the doc says so. Shorter notes cover thinking-mode, effort, and subagent-eagerness defaults. The doc scopes itself to how you write instructions, not to which model tier to run; that second question belongs to the sibling doc, `specialization-and-model-selection.md`. An author reaches the doc through the guidance skill's routing list. Wiring it in adds a routing entry in the skill (`SKILL.md` and its portable copy), a line in the vendored rule index, and a cross-link back from the tier-selection doc. The rest of the branch holds the supporting research report and the plan artifacts (the spec, implementation plan, and decision logs) that produced the guidance.
…ency, split rationale, scope reconciliation)
… anchors and cross-refs
…fication in readability-guidance
…D4/D9, fix guidance-echo wording
…munication directly
…five full-pattern skills
…o two lightweight skills
## Summary **This PR wires Han's shared readability standard into seven planning and coding skills that previously skipped it. The specs, plans, standards, and test plans a human reads end to end now meet the same quality bar as every other prose deliverable in the suite.** ## Behavior changes The central mechanism is a shared "readability standard" (Han's Human-Readable Output Standard: a readability rule plus a writing-voice profile, both owned by the foundational `han-communication` plugin). Seven skills that produce human-read artifacts now source that standard while drafting and hold their output to it before presenting. This closes a gap where these artifact types slipped through unchecked. The seven skills split into two patterns. Five "full pattern" skills (`plan-a-feature`, `plan-implementation`, `plan-a-phased-build` in `han-planning`; `coding-standard`, `test-planning` in `han-coding`) gain three things: a guidance-source line before drafting, one dispatch to the `readability-editor` agent after their final content exists, and a six-point self-check before presenting. Two "lightweight pattern" skills (`plan-work-items`, `iterative-plan-review`) gain the guidance-source line and the self-check only, with no editor dispatch. To keep the editor from touching structure, each skill names its own downstream reader (for example, `plan-implementation` writes for "the engineer who will build the feature") and its own citation-ID scheme to leave alone (`D-N`, `W-N`, `TP-NNN`, phase and open-question anchors). That way, identifiers and structured fields are never rewritten. Two supporting changes make this work. The standard's own scope text was reconciled in `readability-rule.md` and the `readability-guidance` skill. Now a spec, plan, phased build, work-item list, coding standard, or test plan counts as reader-facing whenever a human reads it end to end. Only a pure pipeline artifact consumed solely by downstream skills is excluded. Previously that text read as excluding the exact artifacts these skills produce. Separately, `han-planning`'s manifest now declares `han-communication` as a direct dependency instead of reaching it transitively through `han-core`. Long-form doc updates, a version bump, and CHANGELOG edits are intentionally out of scope and handled later. The relevant files are the ten skill, manifest, and reference files listed above. The rest of the diff is planning artifacts under `docs/plans/readability-in-planning-coding/` (spec, decision logs, review findings, implementation plan). These record how the change was designed and are not part of the shipped behavior.
…g skills The readability-in-planning-coding work wired the standard into plan-a-feature, plan-implementation, plan-a-phased-build, plan-work-items, iterative-plan-review, coding-standard, and test-planning, and reconciled the canonical rule (D9). The operator-facing scope text was left stale: docs/readability.md, CONTRIBUTING.md, and docs/concepts.md still called these deliverables out of scope. - docs/readability.md: reconcile the Scope prose, add the seven skills to the authoritative table (five dispatch the editor, plan-work-items and iterative-plan-review self-check only), and drop the stale "one in-scope skill writes a committed file" claim. Also remove two branch-introduced em-dashes. - CONTRIBUTING.md: reconcile the wiring scope test; drop han-planning from the "no han-communication edge" list (it now carries the edge). - docs/concepts.md: extend the reader-facing enumeration and reconcile the carve-out.
… skills plan-a-feature, plan-implementation, plan-a-phased-build, coding-standard, and test-planning each now dispatch han-communication:readability-editor after their final content exists, but their long-form docs never mentioned it (peer in-scope docs reference it in Cost and latency, In more detail, and Related documentation). - Each of the five skill docs: add the readability-editor rewrite to Cost and latency and In more detail, and add the required readability-editor bullet to Related documentation (checklist: skills that dispatch an agent name it there). - readability-editor.md: add the five skills to its dispatcher list, which listed only the nine original synthesis skills.
## What this does
Han reads two configuration files instead of one. A personal
`.han/config.md` in your Claude Code configuration
directory supplies settings that follow you into every project, and a
project's own `.han/config.md` overrides them one
setting at a time.
Today a setting only takes effect in a project carrying its own file, so
applying one writing voice everywhere means
copying the same file into every repository and editing every copy when
you change your mind.
## Before you merge: one check this branch could not run
Only cases 1 and 2 of the probe gate were verified against the real
skill loader, because a running session cannot unset
its own `CLAUDE_CONFIG_DIR`. Cases 3 and 4 were verified at the shell
level only.
**In a session started with `CLAUDE_CONFIG_DIR` unset, invoke any Han
skill and confirm the `personal config directory`
line reads `~/.claude`** rather than an empty value or a literal
`${CLAUDE_CONFIG_DIR:-$HOME/.claude}`.
This matters because the failure is silent. An unexpanded variable still
exits 0, still injects nothing, and the feature
simply never works for anyone, with no error. Details in
[`artifacts/probe-check-result.md`](docs/plans/user-level-han-config/artifacts/probe-check-result.md).
## A shipped behavior changes, in both files
Han refuses a full path for `output-directory` today. That guard is
removed, and removal applies to project files too,
not only the new personal one. A project file that was refused before
starts being honored, and deliverables can now
land outside the repository.
Two consequences worth naming:
- A project already carrying an absolute `output-directory` sees a
fallback note on every run today. After upgrade it
starts writing there on the first run, with nobody editing a file.
- This is why the release recommendation below is a major bump.
The operator chose this over the narrower option of relaxing the rule
for the personal file alone, with the cost named.
Recorded as
[`D8`](docs/plans/user-level-han-config/artifacts/decision-log.md) in
the specification and
[`D-13`](docs/plans/user-level-han-config/artifacts/implementation-decision-log.md)
in the plan.
## What changed
| Surface | Change |
| --- | --- |
| 40 `SKILL.md` probes | Three probe lines replace one: the resolved
config directory, the personal file, the project file |
| 12 `config-rule.md` copies | Rewritten for two files, six precedence
sources, per-file path rooting, `~` expansion, no containment guard |
| `docs/configuration.md` | Rewritten around both files, with the guard
removal and a version note |
| 11 prose sites | Two writing-voice resolution sentences, four
size-band announcements, four Atlassian output-directory mentions, one
project-discovery intro |
| 8 further docs | Corrected where they described configuration as
project-local |
Verification, all passing on this branch:
```
40 skill files carry the personal read
0 skill files carry the old form without it
1 distinct hash across the 12 contract copies
0 containment-guard language left outside the plan folder
61 tests pass, lint clean
```
## Release recommendation, not applied here
All twelve skill-carrying plugins and the `han` meta-plugin should bump
together at a **major** bump. Versions currently
span 1.0.0 to 5.0.0, so a user upgrading some plugins and not others
gets settings that apply in some skills and not
others. This branch changes no version and no CHANGELOG entry;
`/han-release` owns both.
## Deliberately not done
- **`han-feedback`'s hardcoded `~/.claude/han-feedback/`** hits the same
hazard one skill over. Cut for scope: the
request covers config file loading, and that skill reads no config file.
Worth its own issue.
- **A project asking for Han's built-in writing voice** once a personal
one is set. No value means that today. Deferred
under YAGNI with a reopening trigger.
- **A Bats check for fan-out completeness.** The one documented incident
here was a byte-identical line that was wrong
everywhere, which a text-equality check would have passed. The four
greps above do the job with no new machinery.
## Open item
A personal `default-swarm-size` applies to every project you touch,
where `docs/adr/0001` weighed that cost at one
project. Someone should decide whether to amend the ADR or cover it in
the configuration guide. Does not block.
## Plan
[Specification](docs/plans/user-level-han-config/feature-specification.md)
·
[Implementation
plan](docs/plans/user-level-han-config/feature-implementation-plan.md)
The per-model authoring guidance named Opus 4.8 as the current Opus and stated its thinking is off unless enabled. Opus 5 reverses that: thinking is on by default and can be disabled only at effort high or below. Retarget the document to Sonnet 5, Opus 5, and Fable 5, and add the Opus 5 behaviors that have no equivalent in the older guidance: - Instructions to leave out, since Opus 5 verifies and self-corrects unprompted and the older phrasings compound with that behavior. - Calibration for conversational length, written deliverable length, progress and correction narration, and scope, none of which effort reaches. - The literalism trap where a "only report high-severity issues" review instruction is followed literally, so filtering belongs in its own step. Give multi-agent-economics.md the delegation policy a skill should state, because the model's default is eager: no delegating work finishable in a few tool calls, never an agent to verify the dispatching skill's own work, and prefer one agent to several. The Level 1 worker-plus-reviewer cascade is unchanged; a specialist reviewing from a different perspective is not a self-check. Sweep the four surfaces naming the model trio, and drop the pinned claude-opus-4-8 example from agent-model-selection.md in favor of the alias, which does not go stale.
Removes the external reference to evidence-rule.md and states the evidence content the agent acts on inline, per the agent-building guidance requirement that agent files be self-contained. Refs W-2.
Replaces every external reference to yagni-rule.md and evidence-rule.md with a plain-text naming of the rule, per the W-2 ruling. Each agent already stated the rule content it acts on inline, so no operative content moved and the net line change is zero. Refs W-3.
…arget Trims the nine over-length descriptions down the guidance's priority ladder, moving domain vocabulary and restated process prose into the body sections that already carry them. Restores twelve unique routing anchors the first pass dropped, and repairs all nineteen one-way boundary pairs across the roster. Refs W-4.
Records every agent's model tier against a named archetype so the assignment is auditable, and removes five git permissions no agent body exercised. Two tier mismatches are raised rather than changed, because model tier governs behavior on every future run. Refs W-5.
Splits fifteen over-length role identities at their sentence boundary so each fits the 50-token budget with no content lost, removes two flattery hits, and adds the four missing Domain Vocabulary and Anti-Patterns sections. Five agents exceeding the anti-pattern range are recorded with reasoning rather than cut. Refs W-6.
…uidance The tone anti-pattern sweep in on-call-engineer, and the matching directive in the code-review brief, were review passes over output the same run produced. Both now apply while findings are written. All four named anti-patterns survive. The readability-editor fact check is kept: its rule is scoped to Opus 5 and that agent is pinned to sonnet. Refs W-7.
…mespace a bare dispatch Adds the missing length-and-scope directive to the one file-writing skill that had neither its own nor a shared rule to cite, and qualifies the one bare agent name found across all forty skills. Refs W-8, W-9.
Frontmatter reaches the system prompt, where angle brackets carry meaning, so the security rule bans them in every field. Three argument-hints used <placeholder> syntax; each now uses the plain descriptive form the other skills already use. Refs W-10.
Six consolidation candidates recorded with confidence levels and no action taken; skill and agent counts unchanged at 40 and 24. The documentation sync found nothing stale: the sweep's description changes were compression, and every index entry and README scent line describes the agent rather than the description text. Refs W-19, W-20.
Sixty of 64 entities pass every mechanically checkable item. The four failures are all the 500-line body ceiling, owed by the trim work items that remain open. Refs W-21.
…ling Extracts the review-team roster and briefs, the per-finding resolution mechanics with the YAGNI paths and scope gate, the artifact cross-reference invariants, and the mechanic-routing rule into four new reference files. Compresses the operating principles, Step 1.5, and the size-override paragraph, and replaces the duplicated spec-section list and readability checklist with pointers to the template and the canonical rule that already carry them. 746 to 500 lines. No step loses a rule; each now reads it where it lives. Refs W-11.
…e ceiling Extracts team selection with its size bands and domain-scoped briefs, the deterministic round aggregation, the three-gate YAGNI and scope sweep, and the synthesis directives with their record invariants into four new reference files. 801 to 458 lines. No step loses a rule; each now reads it where it lives. Refs W-11.
Extracts agent selection, brief scoping, domain-scoped file lists, and the per-agent dispatch prompts into agent-dispatch.md, and the self-consistency and structural output checks into output-verification.md. Sub-step numbering is preserved where the content now lives, and Step 3 names the reference so every existing Step 3.2 to 3.5 citation still resolves. 770 to 497 lines. Refs W-12.
543 to 464 lines. All forty skill bodies are now under the 500-line ceiling. Refs W-13.
Nineteen skills carried the six-point self-check verbatim, each having already sourced the canonical rule that defines it. Each now runs the standardized check by name and keeps only the criteria that are its own, layered on top: the ADR heading caveat, research's A# registry check, manual-test-planning's category-parity check, stakeholder-summary's non-technical vocabulary list, and html-summary's supplementary terms. 109 net lines removed. Every skill verified to source the standard before the step that runs the check. Refs W-14, W-15, W-16, W-17.
…skills The paragraph restated precedence, relative-path resolution, and the degradation note that config-rule.md already owns and every copy already linked. Each skill keeps the load-bearing part inline, since it is the skill's first action, and cites the rule for the rest. 80 lines removed across the suite. Refs W-14, W-15, W-16, W-17, W-18.
…ce set The agent description-length doc carried a byte-identical copy of the skill doc's measuring snippet, and troubleshooting repeated the stale-script before-and-after that documentation-maintenance owns. Both now cite the file that holds it. No rule changed. 38 lines removed. The six uncited files are marketplace and plugin configuration guidance, outside the skill-and-agent set the checklists cover. Refs W-18, W-22.
All 64 entities pass every mechanically checkable item. The four 500-line ceiling failures from the first verification run are closed. Refs W-21.
… readability steps
## Summary **This PR brings every skill and agent definition into conformance with the updated authoring guidance and refreshes that guidance for Claude Opus 5, so agent routing, delegation cost, and output length behave predictably on the current model.** ## Behavior changes The authoring guidance now targets Opus 5 instead of Opus 4.8, and that changes what skills tell the model to do. It names instructions to delete because the model already does them unprompted, such as self-verification passes and "double-check your answer." It warns that limiting phrases such as "only report high-severity issues" are followed literally and shrink what a run reports. It adds direction on response length, progress narration, and scope, because Opus 5 runs longer and widens scope on its own judgment. And it tells any skill that dispatches sub-agents to state a delegation policy, since Opus 5 reaches for delegation more readily than earlier models. The sweep then applies that guidance to all forty skills and twenty-four agents. An agent's frontmatter description is the routing surface Claude reads when picking an agent. Nine descriptions ran over the 1024-character target; the fix moved domain vocabulary and restated process prose into the body while keeping the routing anchors. The sweep also repaired nineteen one-way boundary pairs, where one agent deferred to another that did not defer back. Agent files are now self-contained. An agent runs inside the user's project, where a relative link into the plugin folder resolves to nothing, so those links are gone, and each agent now states inline the slice of the shared rule it acts on. Four skill bodies over the 500-line ceiling moved reference material into `references/` files, with no step losing a rule. The remainder is duplication removal with no rule change. Nineteen skills stop restating the canonical readability self-check verbatim; they now run it by name, keeping only the criteria unique to them. Every skill also compresses the personal-config paragraph down to its load-bearing first action, plus a citation of the config rule. ## What to look at first 1. `han-plugin-builder/skills/guidance/references/per-model-authoring.md`. The Opus 5 material drives every other change in this PR, and its own Sources section flags it as single-vendor and not independently corroborated. Decide whether you accept it before evaluating what it caused. 2. `docs/plans/skill-agent-guidance-conformance-sweep/artifacts/self-verification-sweep.md`. Records a real tension: the per-model guidance says cut steps that re-check the model's own work, while the readability rule mandates a self-check. It explains why `readability-editor` keeps its fact check and the other skills keep theirs. 3. `docs/plans/skill-agent-guidance-conformance-sweep/artifacts/agent-self-containment-ruling.md`. The self-containment decision, the three alternatives rejected, and the drift it knowingly accepts: eleven agents each restating their slice of a shared rule in their own words. 4. The four extracted skill bodies (`plan-a-feature`, `plan-implementation`, `code-review`, `iterative-plan-review`) and their new `references/` files. The risk here is a rule lost or a cross-reference broken in the move; `code-review` in particular preserves sub-step numbering so existing citations still resolve.
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
3 participants
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.
Summary
This PR aggregates the Han v5.0.0-alpha-1 changes: it restructures the plugin suite so readability rules and documentation live in their own dedicated plugins, and it adds new coding and planning skills, so each plugin owns a single concern and installs only what it depends on.
How-to test these changes
There are a significant number of changes that have landed in this branch and PR. With that, it's difficult to know what to test and what expectations and outcomes to look for. To help resolve this issue, I've used the new
/manual-test-planningskill to build a test plan for this branch.If you want to take Han v5.0.0 for a spin, and would like to offer some feedback on how well it's doing, please check out the test plan. You can add comments directly to this PR, or open a new issue, with any feedback you have.
Installing Han v5 Alpha 1
First, uninstall any Han version you currently have, and remove the marketplace. Then, follow these instructions:
/marketplace add git@github.com:testdouble/han#han-v5.0.0-alpha-1/plugin install han@han(and/or any other plugin you want to test)Han v5 Alpha 1 Documentation:
Behavior changes
The central change is a new plugin topology. A new foundational plugin,
han-communication, is extracted fromhan-core. It owns the single canonical readability standard, the writing-voice profile, thereadability-guidanceandedit-for-readabilityskills, and thereadability-editoragent. It depends on nothing, and every prose-producing plugin now depends on it directly, so the readability rule has one home instead of vendored copies. In the same move,han-coresplits intohan-documentation(project-documentation, architectural-decision-record, runbook) andhan-research(research, gap-analysis, issue-triage, plus theresearch-analystagent), and thehanmeta-plugin's dependency list pulls in the new layers. Anyone installing from the marketplace should expect the new plugin names and dependency wiring.Two skill changes affect callers directly. The old
test-planningskill is renamed toautomated-test-planning, and a newmanual-test-planningskill joinshan-codingfor human-run test plans; any workflow or docs that referencetest-planningmust update the name. Separately,plan-work-itemsnow leads its output with plain-language summaries and acceptance criteria, and the GitHub issue, Jira, and Linear ticket templates are realigned to match, so generated tickets read differently.The rest of the PR is documentation and polish: docs move to a plugin-first layout (long-form docs relocate into each plugin, 10 new plugin READMEs, a new
docs/workflows.mdcomposition map, and a plugin index indocs/choosing-a-han-plugin.md),code-overviewnow lists the context it used with direct links,han-plugin-buildergains per-model authoring guidance, and Orwell's six writing rules are applied to the readability guidance with follow-up em-dash sweeps.What to look at first
.claude-plugin/marketplace.jsonand theplugin.jsonmanifests underhan-communication/,han-core/,han-documentation/,han-research/, andhan/. These define the new plugin split and dependency graph, the load-bearing decision of the whole PR.han-communication/references/readability-rule.mdandwriting-voice.md. These are now the canonical single copies; confirm no stale vendored copies remain in consuming plugins.han-coding/skills/manual-test-planning/SKILL.mdand the renamedautomated-test-planning/SKILL.md. These cover the new skill and the breaking rename callers must track.han-planning/skills/plan-work-items/SKILL.mdplus the GitHub, Jira, and Linear ticket templates. Check that the plain-language-first, acceptance-criteria output stays consistent across all three ticket targets.