han-core restructure: split into han-documentation and han-research#141
Merged
Conversation
…plementation plan
Five-part plugin shape for both: README front door, .claude-plugin and .codex-plugin manifests at 1.0.0, empty skills/ and docs/ trees, and vendored evidence-rule.md + yagni-rule.md copies. Both are bundled by the han meta-plugin and registered in the marketplace.
…plugin homes han-documentation receives project-documentation, architectural-decision-record, and runbook; han-research receives research, gap-analysis, and issue-triage plus the research-analyst agent. Each move is the atomic unit from the plan: skill directory with references/, its long-form doc, and (research only) the agent definition and agent doc. Pure git mv; reference rewrites land next.
Per-entity rewrites, never a blunt han-core: prefix replace: the research skill and research-analyst doc now dispatch han-research:research-analyst, the gap-analysis report template self-identifies as han-research:gap-analysis, and han-atlassian's wrapper plus the han-plugin-builder composition example invoke han-documentation:project-documentation. In the six moved long-form docs, 22 of 23 relative agent links rewrite to the cross-plugin han-core/docs/agents form; research.md's research-analyst link stays relative because that agent moved with the doc. Every live surface that linked a moved skill's doc or the research-analyst doc at its old han-core home now points at the new plugin home, including han-core's own staying agent and project-discovery docs.
han-reporting, han-feedback, and han-linear drop their vestigial han-core dependencies (han-reporting keeps han-communication; the other two now depend on nothing). han-atlassian adds han-documentation for its project-documentation wrapper and keeps its direct han-core dependency. han-core's claude, codex, and marketplace descriptions now describe the slimmed plugin: the shared agent roster, project-discovery, and the canonical rule files. han-core's codex keywords and default prompts no longer name moved skills. han-atlassian and han-linear descriptions match their new dependency edges on both surfaces. Verified with a scripted marketplace/manifest consistency sweep: names, versions, dependency closure, and no manifest advertising a skill its plugin no longer carries.
CLAUDE.md's intro, layout tree, shipped-plugins paragraph, and indexes-stay-complete convention now describe the twelve-plugin family with han-documentation and han-research. CONTRIBUTING's plugin-placement guide, dependency rules, and scaffolding steps match the new homes, including the two agent-home exceptions. The choosing guide, root README, meta-plugin README, concepts, and the extend-han how-to present the new topology, and the extend-han worked example now uses han-documentation and han-atlassian so every claim it makes about the real suite is true. The three vestigial plugins' READMEs (han-reporting, han-linear, han-feedback) drop the false 'its skills dispatch shared han-core agents' claim and state their real dependencies; han-core's front door describes the slimmed plugin; the agents index prose admits han-research as an agent-owning plugin. All five acceptance grep sweeps and the manifest consistency sweep pass.
mxriverlynn
changed the title
The test-planning skill split into automated-test-planning and manual-test-planning, and han-research now owns the research-analyst agent. Update the guidance canonical examples, the disambiguation table, the plugin README rules and template, and the coverage rule to match.
…spec The code-overview long-form doc carried an em-dash the writing voice bans, and the code-overview-to-confluence doc dropped the TMPDIR fallback from its scratch-path examples.
…lings The plan-work-items and stakeholder-summary long-form docs carried em-dashes the writing voice bans. The investigate skill was the only han-coding skill without an argument-hint and the only one quoting its name field.
…ries The research-analyst long-form doc carried seven em-dashes the writing voice bans. Three boundary pointers ran one direction only: investigate pointed at automated-test-planning, code-overview pointed at architectural-analysis, and readability-guidance pointed at edit-for-readability, with nothing pointing back. Each reverse pointer is now in place.
readability-guidance, plan-implementation, and the runbook citation heading carried prose em-dashes the writing voice bans. Em-dashes that mirror literal output formats (jira and linear slice headings, the OWASP citation shape, the runbook section name) stay, because the docs must match what the skills actually write.
mxriverlynn
marked this pull request as ready for review
July 22, 2026 20:23
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.
Summary
This PR splits the
han-coreplugin into three, extracting the documentation skills into a newhan-documentationplugin and the pre-planning research skills plus theresearch-analystagent into a newhan-researchplugin, so that each plugin owns a coherent slice of the suite and can be installed on its own without pulling in unrelated skills.Behavior changes
The
han-coreplugin now carries only the shared specialist agent roster and theproject-discoveryskill. Its three documentation skills (project-documentation,architectural-decision-record,runbook) move to the newhan-documentationplugin. Its three research skills (research,gap-analysis,issue-triage) plus theresearch-analystagent move to the newhan-researchplugin. Both new plugins depend onhan-communicationandhan-core.Slash-command namespaces change for every moved entity, because a skill's namespace follows its plugin. For example,
/han-core:researchbecomes/han-research:research, and the documentation skills move under/han-documentation:. Anyone who installed those skills throughhan-coredirectly, or who scripted the old command names, needs to update to the new namespaces.The
hanmeta-plugin still brings in everything: its dependency list now addshan-documentationandhan-research, so/plugin install haninstalls the full suite as before. The marketplace manifest lists both new plugins. Users who installed individual plugins instead of the meta-plugin need to install the two new plugins themselves to keep the same coverage.What to look at first
docs/plans/han-core-restructure/feature-specification.mdandfeature-implementation-plan.mdhold the reasoning behind the split boundary (why documentation and research separate cleanly from the shared agent core).han/.claude-plugin/plugin.jsonand.claude-plugin/marketplace.jsonare the manifest changes that keep the meta-plugin whole and register the new plugins.