plugin: han-communication - extracting a new plugin from han-core, and consolidating guidance#114
Draft
mxriverlynn wants to merge 21 commits into
Draft
plugin: han-communication - extracting a new plugin from han-core, and consolidating guidance#114mxriverlynn wants to merge 21 commits into
mxriverlynn wants to merge 21 commits into
Conversation
Extract readability-editor, edit-for-readability, and their reference docs into a new foundational han-communication plugin; consuming skills delegate to it rather than reading vendored copies.
Full delegation (user choice) replaces all three inline uses of the standard; D4 rescoped, D5 gains opt-in dependency fallback, D7 expands to the full docs/tooling inventory; 11 findings recorded.
Resolve dead spec anchors, add missing inline D1/D5 links, complete cross-reference fields on all decisions and findings.
…ndency Every plugin that hosts or triggers a delegating skill (han-core, han-coding, han-github, han-reporting, han meta, han-atlassian) declares han-communication directly; no transitive-resolution reliance. Closes OI-1 and cleans up han-planning exclusion wording.
…findings Team (junior-developer, adversarial-validator, evidence-based-investigator, gap-analyzer) confirmed the plan's foundations and surfaced: step-order preservation risk under forced delegation (D4), dependency-graph narration scope (D7 class 5), manifest description updates (D8), the Codex packaging surface (new D10), plus delegation-scope wording and future-wrapper rule.
…me doc scope Resolve 9 findings: split Preconditions for the Codex surface (F23), widen D4's step-preservation commitment to renumber/split/heading cases (F28), qualify D10 Codex parity + opt-in install path + OI-2 (F29), and reframe D7 doc classes as a comprehensive grep so the recurring missed-file class is closed (F25-F27, F30, F31).
Final round (Large cap): junior-developer clean; adversarial-validator reproduced the D5/D10 inventories and confirmed no file-discovery gap. Resolved 4 refinements (F32-F35): rewrite-depth for docs/readability.md, order-significant non-numbered lists in the preservation commitment, OI-2 blast-radius correction, and the mandated Review History section.
…guidance skill) Adopt the readability-guidance skill approach after evidence gathering (Claude Code docs + in-repo): skills invoked via the Skill tool run in the same context, so han-communication exposes a resource-surfacing readability-guidance skill that sources the standard cross-plugin for in-voice drafting. D3 reframed (source cross-plugin), D4 reframed (staged model, editor retained for synthesis only), D11 added (the guidance mechanism), OI-3 added (prototype gate). Preserves docs/readability.md's staged model that full delegation collapsed; rehabilitates the F3 hybrid.
…ated Adversarial R4 found readability-guidance is the repo's documented data-fetch composition anti-pattern (skill-composition.md). Per user direction (option 3): built and ran an inline prototype (resumed 3/3 — weak signal, not reliability), did NOT update skill-composition.md, hardened OI-3 into a rigorous blocking spike with a named fallback, and captured the risk + inline-vs-fork distinction on D11. Fixed revision propagation: stale D7 'abolished staged model' (F36), editor rule-path break (F37), impossible edge-case examples (F40), decision counts (F43), and refreshed the Review History for R4.
…ualified Rigorous subagent-harness spike (46 trials, 4 arms): 34/34 same-context Skill-call invocations completed with zero early exits, including a worst-case adversarial arm. Forked context:fork disqualified because it isolates the guidance so its content never reaches the caller. api_retry could not be induced (infra-level fault), so that path is reduced by inference, not measured. D11 known-risk resolved and prototype gate cleared; skill-composition.md to record the inline variant as a supported exception.
Records the spike outcome in the spec: OI-3 marked resolved, the inline readability-guidance mechanism validated (34/34 same-context runs, zero early exits) and the forked variant disqualified. Bakes the inline (no context:fork) requirement into the Primary Flow, updates the open-item count 2 -> 1, and notes the unmeasured api_retry residual risk plus the documented fallbacks.
…ption The OI-3 spike validated one narrow shape that looks like data-fetch but is supported: an inline (never context:fork) sub-skill that surfaces a whole shared standard into the caller's context and hands control back. Carves it out of the data-fetch section with its three defining properties, adds it to the decision guide, and keeps the honest limit that api_retry was not directly exercised.
Move the spike report, incident fixture, all 46 trial artifacts, and the 8 harness skill definitions from the session scratchpad into artifacts/oi-3-spike/ so the spike is reproducible independent of the session that ran it. Add a pointer from the research note.
…anic graduated to T1 Lightweight self-review round confirming the post-spike edits are internally consistent (open-item count, trial counts, cross-file claims all agree). One finding (F46): the OI-3 edit had leaked the context:fork frontmatter mechanic into a Primary Flow behavioral sentence. Since the spike settled that mechanic, it graduates from the OI-3 open item to a new technical note T1; Primary Flow restated behaviorally. No blocking open items remain (OI-2 non-blocking); spec ready for plan-implementation.
…ation) Medium team (PM + junior-developer + structural-analyst + devops-engineer + test-engineer), 2 rounds. Produces feature-implementation-plan.md plus the implementation decision log (8 full + 1 trivial decision) and iteration history, and a discovery-notes inventory. Key outcomes: 6-phase copy-first/delete-last sequencing with a hard pre-delete grep gate; the exact 6-plugin direct-dependency edge list (confirming D5 from scratch); editor invocation-contract change (rename + drop rule-path arg); the Codex surface is EXTENDED not built (RECON-1), with zero Codex dependency/description edits; version bumps listed but deferred to release (han-core a MAJOR candidate); a grep-driven docs sweep including the 'agents live in han-core' exception; manual verification (static grep/diff + one light smoke, no CI). 3 YAGNI deferrals. Open items OI-2 and the semver call are both non-blocking.
…(Phase 1) Stand up the new han-communication plugin additively — the suite still runs on the existing vendored copies until later phases rewire and delete them. - Both manifests: .claude-plugin/plugin.json (no dependencies) and .codex-plugin/plugin.json mirroring han-core's Codex schema - Co-located canonical references/readability-rule.md + writing-voice.md - readability-editor agent and edit-for-readability skill (byte copies) - New inline readability-guidance skill (no context: fork) that surfaces the standard into the caller's context - han-communication entries added to both marketplaces Refs feature-implementation-plan.md D-4, D-7, T1.
…e 2) Add the han-communication dependency edge to the six declaring Claude manifests before any consumer rewire, so the capability resolves by qualified name once Phase 3 lands. - han-core gains its first-ever dependencies key (["han-communication"]) - han-coding, han-github, han-reporting prepend han-communication - han meta and han-atlassian prepend han-communication - Update dependency-narrating descriptions for han, han-coding, han-atlassian in both plugin.json and the marketplace.json mirror - han-planning, han-linear, han-feedback, han-plugin-builder untouched - Zero Codex edits (schema has no dependencies field) Refs feature-implementation-plan.md D-1, D-4.
…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.
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
1 participant
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.
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-communicationplugin 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.mdandwriting-voice.mdwere vendored intohan-core,han-github, andhan-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 inhan-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. Thereadability-editoragent and theedit-for-readabilityskill also moved intohan-communication. The adversarial rewrite pass they perform is unchanged.For anyone installing the suite,
han-communicationis a new dependency edge beneath everything. Thehanmeta-plugin now bundles it, andhan-core,han-coding,han-github,han-reporting, and the opt-inhan-atlassianeach declare a direct dependency on it. This ishan-core's first-ever dependency. Installing any prose-producing plugin now pulls inhan-communicationautomatically.What to look at first
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.plugin.jsonmanifests and.claude-plugin/marketplace.json. Verify that the newhan-communicationdependency 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.SKILL.mdfiles, for examplehan-core/skills/research/SKILL.mdandhan-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.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.