Plan: plugin-centric documentation reorganization (#115) - #137
Merged
Conversation
Initial feature specification for issue #115: per-plugin READMEs, in-plugin long-form docs, slimmed alphabetized indexes, plugin catalog folded into the choosing doc, and a workflows page with mermaid diagrams.
Incorporate information-architect, junior-developer, and gap-analyzer findings: widen the change scope to the full ~37-file blast radius plus relative-link recomputation and a link-integrity gate; declare the plugin README canonical for plugin purpose and slim the catalog to a plugin index; bring the plugin-README standard, template, and the stale meta-plugin README into scope; correct the shared-agent dispatch note; frame bundled-vs-opt-in in each README. Six new decisions (D13-D18), sixteen major findings, two minor.
Project-manager synthesis reconciled cross-references (F/D reciprocity, Referenced-in-spec fields, and the trivial-decision anchors). Readability editor rewrote the spec prose: main point first, one idea per paragraph, shorter sentences, em-dashes removed, every fact and citation preserved.
Tier 1 of the plugin-centric docs reorg. Rewrite the plugin-README
standard and template to the light front-door model (D18), and update
the skill/agent long-form templates and coverage rule to the new
in-plugin {plugin}/docs/{skills,agents}/{name}.md paths and the
link-up-to-plugin-README convention (D14).
…links
Tier 2. Move each skill and agent long-form doc from docs/{skills,agents}/{plugin}/
to {plugin}/docs/{skills,agents}/ (D1), recomputing every relative link by
resolving to an absolute repo path and re-expressing from the new location (D-3,
D16). Each doc's first up-link now points to its adjacent plugin README, then the
repository root (D14). Only han-core and han-communication gain a docs/agents/
subfolder. Links inside inline-code examples are left untouched.
Tier 3. Author fresh light front-door READMEs for han-communication, han-core, han-planning, han-coding, han-github, han-reporting, han-feedback, han-atlassian, han-linear, and han-plugin-builder: a one-paragraph what/how/why, a bundled-vs-opt-in and dependencies line (D13), scent-line skills lists reusing each long-form doc's canonical summary line (D15), an owned-agents list for han-core and han-communication with the shared-agent-dispatch note for the rest (D8), and lateral navigation (D14). han-core groups its skills and agents by purpose (D12). Rewrite the stale han/README.md to the meta-plugin shape with no skills or agents sections (D17).
Tier 4. Create the workflows page (D6): the map of which skills chain together, with a distinct-job statement versus quickstart, how-to, and concepts (all four cross-linked), the composition scenarios relocated from the skills index, and three mermaid flow diagrams for the branching chains (planning-to-delivery, gap-to-plan, working-in-code) that GitHub renders natively (T1). Its four inbound links land with the indexes, plugin index, and root README in later tiers (D-8).
Tier 5. Rewrite docs/skills/README.md and docs/agents/README.md to flat alphabetized lists (D5): one scent line per entry reusing each long-form doc's canonical summary line (D15) and linking to its new in-plugin location. Drop the by-purpose grouping, the how-skills-compose section (now docs/workflows.md), and the sizing/YAGNI summaries (now their own canonical docs) per D6. Each index cross-links the workflows page and labels the choosing doc as the plugin index (D4).
Tier 6. Rewrite docs/choosing-a-han-plugin.md as the scent-and-link plugin index (D4): each plugin gets a one-line scent and a link to its README, with the per-skill deep-links and restated full purposes removed so the plugin READMEs and skills index stay canonical. Label the doc as the plugin index and cross-link the workflows page; keep the install-decision table and dependency explanation.
Tier 7. Point every active reader-facing description and cross-reference at the new in-plugin locations (D9): the root README, CLAUDE.md project map and conventions, CONTRIBUTING.md contributor flow, all how-to guides, the standalone docs pages (concepts, evidence, quickstart, sizing, yagni, readability, why-solo-and-small-teams), the PR template blob URL and checklist (D-6), and the han-update-documentation maintenance tooling (SKILL.md, audit-checklist, scope-mapping). Add the workflows inbound links from the root README and both indexes (D-8). CHANGELOG.md and the frozen docs/plans and docs/research archives are left unchanged (D-5, D10).
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.
What this is
A feature specification (not an implementation) for the plugin-centric documentation reorganization requested in #115, produced with
/plan-a-feature. It plans moving the docs to a plugin-first layout without breaking the "one canonical source per concept" convention.Targets
han-v5.0.0-alpha-1, per the request.The plan, in one paragraph
Every plugin gets its own light README front door (what/how/why + scent-line links, bundled-vs-opt-in status, and dependencies). Each skill and agent long-form doc moves out of the repository-root
docs/folder and into the plugin it describes, at{plugin}/docs/skills/{name}.mdand{plugin}/docs/agents/{name}.md. The skills and agents indexes stay but shrink to alphabetized scent-and-link lists.docs/choosing-a-han-plugin.mdbecomes the plugin index (and keeps its install-decision role). A newdocs/workflows.mdcarries the composition scenarios plus mermaid flow diagrams that render on GitHub with no build step. A rendered docs site (mkdocs/sphinx/readthedocs) is deferred under YAGNI.Key decisions settled with the maintainer
{plugin}/docs/...), not a central folder.choosing-a-han-plugin.mdrather than a new file.docs/workflows.md; the rendered site is deferred.Review
Three specialists reviewed the draft (
information-architect,junior-developer,gap-analyzer); 16 major + 2 minor findings were resolved by evidence. The most consequential adjustments:han/README.mdand zero-skill meta-plugin edge case were brought into scope.readability-editorlives inhan-communication, nothan-core).A project-manager synthesis pass reconciled all cross-references, and a readability pass rewrote the spec prose.
Files
docs/plans/plugin-centric-docs-reorg/feature-specification.md— the behavioral specdocs/plans/plugin-centric-docs-reorg/artifacts/decision-log.md— 18 decisions (D1–D18)docs/plans/plugin-centric-docs-reorg/artifacts/team-findings.md— 18 findings and resolutionsdocs/plans/plugin-centric-docs-reorg/artifacts/feature-technical-notes.md— T1 (GitHub mermaid rendering)Open item
han-core's README keeps by-purpose grouping or goes flat. A default is recorded.Closes #115 once the plan is implemented.