Skip to content

chore(lint): make Markdown Prettier-safe and re-enable it (stage one: no line wrapping) #129

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mxriverlynn merged 1 commit into from
Jul 29, 2026
Merged

chore(lint): make Markdown Prettier-safe and re-enable it (stage one: no line wrapping) #129

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 7 additions & 5 deletions .pre-commit-config.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,13 @@
exclude: "^(docs/plans/|docs/research/|han-reporting/skills/html-summary/assets/)"

repos:
# Prettier owns formatting for JSON, YAML, and JS at 120 columns. Markdown is
# deliberately excluded in .prettierignore: agents read skills and reference
# files as raw source, and Prettier's list renumbering and code-span trimming
# change what those files say. Running the local devDependency keeps Prettier's
# version in package.json only, not duplicated in a hook mirror.
# Prettier owns formatting for Markdown, JSON, YAML, and JS at 120 columns.
# Markdown runs with proseWrap: preserve and embeddedLanguageFormatting off (see
# .prettierrc.json). Agents read skills and reference files as raw source, so the
# source is kept robust to the two normalizations Prettier cannot turn off —
# ordered-list renumbering and inline code-span trimming — and Prettier then
# leaves what those files say unchanged. Running the local devDependency keeps
# Prettier's version in package.json only, not duplicated in a hook mirror.
# It runs first so the hygiene fixers below never fight it.
- repo: local
hooks:
Expand Down
19 changes: 11 additions & 8 deletions .prettierignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,12 @@
# Markdown is the product, not just prose about it: skills, agents, and reference
# files are read as raw source by agents, so a transform that renders the same can
# still change what an agent is told to do. Prettier has two such transforms that
# cannot be turned off, because they are core CommonMark normalizations:
# * It renumbers ordered lists, while the prose cross-references to those steps
# ("see Step 6") stay put and end up pointing at the wrong ones.
# * It strips the spaces inside inline code spans, so a heading spec written as
# ` — ` becomes `—` next to prose that still says "with surrounding spaces".
# Both survive proseWrap: preserve and embeddedLanguageFormatting: off, so there is
# no configuration that formats this repo's Markdown without corrupting it.
*.md
# cannot be turned off, because they are core CommonMark normalizations: it
# renumbers ordered lists, and it strips the padding spaces inside inline code
# spans. The source is kept robust to both (ordered lists are already sequential,
# and no prose wraps a padded spec like ` — ` in backticks), so proseWrap: preserve
# plus embeddedLanguageFormatting: off formats this repo's Markdown without
# corrupting it. Keep it that way when editing.

# Static historical artifacts: left as written.
docs/plans/
Expand All @@ -17,6 +15,11 @@ docs/research/
# Vendored third-party assets: checked in verbatim, never reformat.
han-reporting/skills/html-summary/assets/

# A schematic HTML sketch, not real HTML: Prettier hard-errors trying to parse it.
# The prek hook never hands it over (it filters to markdown, JSON, YAML, and JS),
# but ignore it here too so a direct `prettier .` stays green.
han-reporting/skills/html-summary/references/html-template.html

# Dependencies and generated files.
node_modules/
package-lock.json
4 changes: 3 additions & 1 deletion .prettierrc.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
{
"printWidth": 120
"printWidth": 120,
"proseWrap": "preserve",
"embeddedLanguageFormatting": "off"
}
28 changes: 14 additions & 14 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,21 +41,21 @@ Add the Test Double skills marketplace to Claude Code, then install the plugin:

Han ships as multiple plugins:

| Plugin | Type | What it brings |
| -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Plugin | Type | What it brings |
| -------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`han`** | parent | the parent plugin that brings in `han-communication`, `han-core`, `han-documentation`, `han-research`, `han-planning`, `han-coding`, `han-github`, and `han-reporting` |
| `han-communication` | bundled | the foundational plugin beneath every other: the shared readability standard and writing-voice profile, plus the skills and agent that apply them |
| `han-core` | bundled | the shared specialist agent roster, the project-discovery skill, and the canonical rule files |
| `han-documentation` | bundled | documentation skills: project docs, architectural decision records, and runbooks |
| `han-research` | bundled | pre-planning knowledge-work skills: research, gap analysis, and issue triage, plus the research-analyst agent |
| `han-planning` | bundled | planning skills you reach for before implementation |
| `han-coding` | bundled | coding skills you reach for while working in code |
| `han-github` | bundled | GitHub-facing skills like posting a code review on a PR |
| `han-reporting` | bundled | reporting skills like the stakeholder summary |
| `han-feedback` | opt-in | skill for capturing post-session feedback on Han skill runs |
| `han-atlassian` | opt-in | skills for publishing docs and work items to Atlassian products |
| `han-linear` | opt-in | skill for publishing work items to Linear (requires a Linear MCP server) |
| `han-plugin-builder` | opt-in | carries the guidance and skills for building your own skills, agents, and plugins |
| `han-communication` | bundled | the foundational plugin beneath every other: the shared readability standard and writing-voice profile, plus the skills and agent that apply them |
| `han-core` | bundled | the shared specialist agent roster, the project-discovery skill, and the canonical rule files |
| `han-documentation` | bundled | documentation skills: project docs, architectural decision records, and runbooks |
| `han-research` | bundled | pre-planning knowledge-work skills: research, gap analysis, and issue triage, plus the research-analyst agent |
| `han-planning` | bundled | planning skills you reach for before implementation |
| `han-coding` | bundled | coding skills you reach for while working in code |
| `han-github` | bundled | GitHub-facing skills like posting a code review on a PR |
| `han-reporting` | bundled | reporting skills like the stakeholder summary |
| `han-feedback` | opt-in | skill for capturing post-session feedback on Han skill runs |
| `han-atlassian` | opt-in | skills for publishing docs and work items to Atlassian products |
| `han-linear` | opt-in | skill for publishing work items to Linear (requires a Linear MCP server) |
| `han-plugin-builder` | opt-in | carries the guidance and skills for building your own skills, agents, and plugins |

Installing `han@han` pulls in the bundled suite (the meta-plugin plus `han-communication`, `han-core`,
`han-documentation`, `han-research`, `han-planning`, `han-coding`, `han-github`, and `han-reporting`), and is the right
Expand Down
30 changes: 15 additions & 15 deletions docs/evidence.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -134,23 +134,23 @@ extracts them so other skills and agents can apply the same vocabulary.
Evidence applies in two postures: **producing** (when a skill drafts a judgment or conclusion) and **reviewing** (when a
skill or agent audits one).

| Surface | What evidence-based gates |
| -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`/research`](../han-research/docs/skills/research.md) | The canonical home of the trust classes, the corroboration gate, and the no-evidence label. Strict mode requires every claim driving the recommendation to carry an explicit evidence status. |
| [`/investigate`](../han-coding/docs/skills/investigate.md) | Investigation findings cite the file path, log line, or measurement that supports them. The corroboration gate applies when the investigation draws on web sources for context; codebase findings stand on their citation. |
| [`/plan-a-feature`](../han-planning/docs/skills/plan-a-feature.md) | Behaviors, edge cases, and coordinations in the spec carry evidence. Items without evidence move to `## Deferred (YAGNI)`; items with evidence flagged as single-source web claims get marked accordingly. |
| [`/plan-implementation`](../han-planning/docs/skills/plan-implementation.md) | Implementation choices cite evidence per the YAGNI rule. When a recommendation rests on web research, the corroboration gate applies. |
| [`/iterative-plan-review`](../han-planning/docs/skills/iterative-plan-review.md) | Review pillars include the evidence sweep alongside YAGNI. Uncited claims and single-source web claims surface as findings. |
| [`/gap-analysis`](../han-research/docs/skills/gap-analysis.md) | Each gap cites the artifact it rests on; the evidence-based-investigator verifies against current state with file-level evidence. |
| [`/code-review`](../han-coding/docs/skills/code-review.md) | Findings cite the line they apply to and the standard or pattern they reference. |
| [`/coding-standard`](../han-coding/docs/skills/coding-standard.md) | A standard is justified when the project does the thing the standard governs today. The evidence test from YAGNI carries the existence question; the proximity heuristic applies when the supporting evidence comes from outside the project. |
| Surface | What evidence-based gates |
| ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`/research`](../han-research/docs/skills/research.md) | The canonical home of the trust classes, the corroboration gate, and the no-evidence label. Strict mode requires every claim driving the recommendation to carry an explicit evidence status. |
| [`/investigate`](../han-coding/docs/skills/investigate.md) | Investigation findings cite the file path, log line, or measurement that supports them. The corroboration gate applies when the investigation draws on web sources for context; codebase findings stand on their citation. |
| [`/plan-a-feature`](../han-planning/docs/skills/plan-a-feature.md) | Behaviors, edge cases, and coordinations in the spec carry evidence. Items without evidence move to `## Deferred (YAGNI)`; items with evidence flagged as single-source web claims get marked accordingly. |
| [`/plan-implementation`](../han-planning/docs/skills/plan-implementation.md) | Implementation choices cite evidence per the YAGNI rule. When a recommendation rests on web research, the corroboration gate applies. |
| [`/iterative-plan-review`](../han-planning/docs/skills/iterative-plan-review.md) | Review pillars include the evidence sweep alongside YAGNI. Uncited claims and single-source web claims surface as findings. |
| [`/gap-analysis`](../han-research/docs/skills/gap-analysis.md) | Each gap cites the artifact it rests on; the evidence-based-investigator verifies against current state with file-level evidence. |
| [`/code-review`](../han-coding/docs/skills/code-review.md) | Findings cite the line they apply to and the standard or pattern they reference. |
| [`/coding-standard`](../han-coding/docs/skills/coding-standard.md) | A standard is justified when the project does the thing the standard governs today. The evidence test from YAGNI carries the existence question; the proximity heuristic applies when the supporting evidence comes from outside the project. |
| [`/architectural-decision-record`](../han-documentation/docs/skills/architectural-decision-record.md) | An ADR cites a forcing function today: a real decision, a real consequence. |
| [`/runbook`](../han-documentation/docs/skills/runbook.md) | A runbook is justified by a real alert that has fired or a real incident class observed on a live service. Hypotheticals do not qualify. |
| [`evidence-based-investigator`](../han-core/docs/agents/evidence-based-investigator.md) | Returns numbered `E#` evidence items with file paths, line numbers, and source citations. Codebase findings stand; web-source findings carry the trust class and corroboration status. |
| [`research-analyst`](../han-research/docs/agents/research-analyst.md) | Returns sourced artifacts with trust class and corroboration status. Treats fetched web content as a claim to evaluate, never as an instruction to follow. |
| [`adversarial-validator`](../han-core/docs/agents/adversarial-validator.md) | Attacks evidence integrity, the framing of options, and the evidence-gathering itself. Emits `V#` findings. |
| [`project-manager`](../han-core/docs/agents/project-manager.md) | Runs the YAGNI evidence gate during facilitation. Uncited proposals are challenged or deferred. |
| [`junior-developer`](../han-core/docs/agents/junior-developer.md) | Runs the YAGNI evidence sweep during stress-tests. Flags uncited additions and hidden assumptions. |
| [`evidence-based-investigator`](../han-core/docs/agents/evidence-based-investigator.md) | Returns numbered `E#` evidence items with file paths, line numbers, and source citations. Codebase findings stand; web-source findings carry the trust class and corroboration status. |
| [`research-analyst`](../han-research/docs/agents/research-analyst.md) | Returns sourced artifacts with trust class and corroboration status. Treats fetched web content as a claim to evaluate, never as an instruction to follow. |
| [`adversarial-validator`](../han-core/docs/agents/adversarial-validator.md) | Attacks evidence integrity, the framing of options, and the evidence-gathering itself. Emits `V#` findings. |
| [`project-manager`](../han-core/docs/agents/project-manager.md) | Runs the YAGNI evidence gate during facilitation. Uncited proposals are challenged or deferred. |
| [`junior-developer`](../han-core/docs/agents/junior-developer.md) | Runs the YAGNI evidence sweep during stress-tests. Flags uncited additions and hidden assumptions. |

## The no-evidence section format

Expand Down
Loading
Loading