0.10.1

Bug Fixes

• design-validate now reports the true number of hard-wrapped lines in a document. The detector capped its counter at five warnings per file and stopped counting there, so a document hard-wrapped end to end was indistinguishable from one with five bad lines — a 533-line doc that needed reflowing throughout reported the same "5" as a doc needing five edits, and readers scoped their fix to the five lines shown. Line-level detail is still capped at five to keep the report readable, but the count is now uncapped and a trailing N hard-wrapped lines total, first 5 shown summary fires whenever the cap is exceeded. The aggregate **Warnings:** tally reflects the true total as well, since the caller folds the same counter into it.

  This also resolves the companion report that wrapped list-item continuations were never flagged. They were in fact detected all along — the detector's block-marker heuristic treats an indented continuation under a list item exactly like a wrapped paragraph, while correctly skipping nested list items, fenced code, tables, and block quotes. What actually happened is that paragraph-level wraps earlier in the file exhausted the five-warning budget before any list-item wrap could print, so the list warnings were starved rather than missing. Making the total visible surfaces them. #76

Performance

• design-link classifies references in a single awk pass instead of forking per reference. The checker was subprocess-bound: it forked a grep per reference to test node-set membership, a subshell per path resolution, and re-parsed a target document's heading slugs once per anchor link pointing at it — upwards of 1,600 process spawns on a 22-document corpus, scaling with reference count rather than corpus size. A link checker only catches link rot if people are willing to run it, and at roughly 45 seconds it had stopped being something anyone ran casually.

  Collection now extracts raw reference records only, and one awk invocation classifies the whole corpus — path resolution, node membership, and the heading-anchor pipeline included, with heading slugs memoized per target file. Associative arrays are available inside the awk program regardless of the bash 3.2 constraint that governs shipped scripts. A synthetic 22-document corpus went from 29.6s to 2.0s, with byte-identical output. Detection semantics and report format are unchanged.

  The node list is passed to awk as a file argument rather than through -v, because the BWK awk that ships as /usr/bin/awk on macOS rejects a -v value containing a newline — which would have silently classified zero references on a stock Mac. #76

Patch Changes

Thanks to @spencerbeggs for their contributions!

This is a version-only release. No packages were published to a registry.

0.10.0

Features

• design-link now checks links that resolve outside the design tree. Its broken-reference check previously only fired for targets landing inside .claude/design/, and it only ever extracted links to .md files — so dead links to source files, READMEs and configs were invisible. Whether a dead link was caught depended solely on where its path happened to land. This mattered most for the docs that follow the style guide, since the guide tells authors to point at real source paths. Every relative link is now existence-checked wherever it resolves, broken references report the source line, and repeated occurrences are each reported instead of collapsing into one. The --format=json output gained a line field on broken references.

Bug Fixes

• design-validate now recurses into module subdirectories. It previously iterated a flat glob, so docs nested under a module (<module>/packages/*.md) were never validated and never reported as skipped — a partial run was indistinguishable from a complete one. On a 22-document corpus it had been validating 7. _archive/ is still pruned.

  The dependencies frontmatter field is now optional. It was in the validator's required set but in nothing else, so every doc not scaffolded from a template failed with an error no author could act on. A permanently red validator teaches readers to skip its genuine findings too. Templates still scaffold the field — declaring dependencies is worth doing, a doc is just not invalid without it.

  design-validate no longer aborts partway through a run. A design doc with no frontmatter made it exit mid-report, silently skipping every doc sorted after it while still returning a failing status.

Documentation

• design-validate's frontmatter-rules.md records dependencies as optional, and design-link's SKILL.md documents the broadened broken-reference check and the line numbers in its report. #66

Minor Changes

Thanks to @spencerbeggs for their contributions!

This is a version-only release. No packages were published to a registry.

0.9.0

Features

• quality.context.hardWrap config option

  Repos with an entrenched hard-wrapped CLAUDE.md convention can opt out of the single-line-per-paragraph rule. context-docs-style then enforces per-file consistency instead of flagging the wrapping. Defaults to forbid.

  {
  	"quality": {
  		"context": {
  			"hardWrap": "allow"
  		}
  	}
  }

  quality.context.requirePointerHashes was also added to the published config schema, controlling whether context-validate/context-audit treat a design-doc pointer with no recorded content hash in refs.json as a warning.

  Published JSON Schemas

  design-docs.schema.json (the design.config.json contract) and plan-frontmatter.schema.json (the plan frontmatter contract) are now published at the repository root with stable raw.githubusercontent.com URLs, so editors can validate and autocomplete plugin config files in consuming repos:

  {
  	"$schema": "https://raw.githubusercontent.com/spencerbeggs/design-docs-plugin/main/design-docs.schema.json"
  }

Bug Fixes

• design-link discovers design docs in module subdirectories -- packages/*.md docs were previously invisible, so every link to them was falsely reported broken -- and its anchor slugger now matches GitHub's algorithm exactly, preserving consecutive hyphens (closes #58)
• Skill docs reference shipped scripts and templates via ${CLAUDE_PLUGIN_ROOT} instead of nonexistent repo-local .claude/skills/ paths, so the design-validate script and the design-init/docs-generate templates resolve correctly in consuming repos (closes half of #59)
• All shipped bash scripts now run on stock macOS /bin/bash 3.2: plan-explore's explore-plans.sh no longer relies on mapfile/associative arrays -- which previously crashed outright without Homebrew bash, and also crashed on any plan missing an optional frontmatter field -- and works without jq; the design-audit workflow scripts received the same fix. A portability test guards against regressions.
• refs-record.sh resolves the repo root via DESIGN_DOCS_PROJECT_DIR/CLAUDE_PROJECT_DIR instead of bare pwd, so pointer recording works from any working directory
• Removed stale cross-references to nonexistent plan-update/design-list skills and the /rspress-page command; plan-* skill references are now namespace-qualified #60

Minor Changes

Thanks to @spencerbeggs for their contributions!

This is a version-only release. No packages were published to a registry.

0.8.2

Bug Fixes

• GitHub auth no longer requires an env token: review, finalize, merge-prep and gh-pr-review.sh now resolve credentials as DESIGN_DOCS_GH_TOKEN -> GH_TOKEN -> GITHUB_TOKEN -> gh keyring (gh auth login), scrubbing stale env tokens at each call site. Previously the script hard-errored and agents falsely reported "DESIGN_DOCS_GH_TOKEN is not set" even when the user was already logged in via gh.
• All skill, slash-command and agent references across the plugin are namespace-qualified (design-docs:<name> / /design-docs:<name>), fixing "Unknown skill" errors triggered when agents followed their own in-body instructions.
• Fixed references to two nonexistent skills (/plan-update, /design-list) and a stale path in design-link's SKILL.md.
• design-validate: recommended-section warnings now derive from design.config.json's minSections instead of a hardcoded list; heading matching is case-insensitive so sentence-case headings pass; the draft-completeness band widened to 21-90% with a pre-implementation carve-out that was producing false "promote to current" suggestions; added a new warning for hard-wrapped prose.
• design-link: validates #heading anchor links against GitHub's slug rules, including cross-file anchors and duplicate-heading suffixes; brokenAnchors added to the JSON output.
• design-doc-agent, context-doc-agent and user-docs agents declare SendMessage so orchestrators can reclaim them via shutdown_request.

Documentation

• README: documented the GitHub auth resolution order and the optional GITHUB_PERSONAL_ACCESS_TOKEN environment variable; corrected skill counts (48 -> 50 total, design-* 16 -> 18).
• CONTRIBUTING: corrected the minimum Bun version prerequisite. #56

Patch Changes

Thanks to @spencerbeggs for their contributions!

This is a version-only release. No packages were published to a registry.

0.8.1

Bug Fixes

• 5a194ea Fixed design-link: the skill now runs a deterministic script that reliably produces a cross-reference graph (references, broken links, orphans, bidirectional pairs; --format=text|json|mermaid). Previously the model could free-form and return unrelated output such as a code review instead of the graph.
• Fixed design-validate: recommended-section warnings now honor quality.designDocs.minSections from design.config.json instead of a hardcoded Overview/Current State/Rationale list. An empty array disables required-section checking entirely.
• Fixed refs-record.sh: the script is now idempotent. It preserves an entry's recordedAt when the target content hash is unchanged and only restamps the date when the body actually changed, making it safe to run repeatedly as a verification step.
• Removed the inert quality.designDocs.maxLineLength config key from design-docs.schema.json and the design-config documentation. The setting enforced nothing (markdownlint MD013 is disabled and design docs use one-sentence-per-line prose).

This is a version-only release. No packages were published to a registry.

0.8.0

Features

• f64cb63 ### Pointer Content-Drift Detection

context-validate and context-audit now detect when a design-doc pointer resolves to the right path but the target document's body has changed since the pointer's "Load when" guidance was written. Path resolution passing is no longer sufficient — the content behind the pointer is also verified.

The check works through a new shared script plugin/lib/ref-hash.sh, which produces a deterministic SHA-256 of the document body with frontmatter stripped. A turnkey recorder, plugin/lib/refs-record.sh, walks every @ pointer in a CLAUDE.md and upserts its .claude/design/refs.json entries in one shot (and ref-hash.sh --record <source> <target> emits a single dated entry), so the context-doc-agent no longer hand-assembles JSON. During validation, each @ pointer's current hash is compared against the recorded value:

• Hashes match — in sync, pass.
• Hashes differ — WARNING: "pointer may be stale (content drift)" — the link resolves, but the doc changed since guidance was written.
• No recorded hash — INFO by default; WARNING when quality.context.requirePointerHashes is true.

A new config flag, quality.context.requirePointerHashes (default false), controls the strictness level for untracked pointers:

{
  "quality": {
    "context": {
      "requirePointerHashes": true
    }
  }
}

When requirePointerHashes is true, any pointer without a recorded hash in refs.json produces a WARNING instead of INFO, pushing all pointers to become drift-tracked.

Bug Fixes

• f64cb63 ### Unified Word-Count Limit Across Context Skills

All context skills now measure the same thing when enforcing size limits. Previously, context-validate and context-audit measured words while context-review, context-split, context-update, and the context-doc-agent measured non-blank lines — causing the same file to pass one skill's check and fail another's.

The standard is now words across all skills and the agent, matching the defaults already used by context-validate and context-audit (root: 2000 words, child: 1000 words). If your design.config.json uses the old rootMaxLines / childMaxLines fields, migrate to rootMaxWords / childMaxWords:

{
  "quality": {
    "context": {
      "rootMaxWords": 2000,
      "childMaxWords": 1000
    }
  }
}

context-validate and context-audit also now emit a one-line note when default limits are in effect (no design.config.json found), so it is clear which threshold is being applied.

finalize --split-docs Flag

The finalize skill's squash step now accepts a --split-docs flag that produces two commits instead of one — a functional commit (review-focus: primary) and an ancillary docs/changeset commit (review-focus: ancillary) — as a review-time focus signal for agent reviewers. Without the flag, the default is a single squash commit (unchanged from before). The --split-docs flag has no effect when --no-squash is also set.

/design-docs:finalize --split-docs

Both commits collapse into one at squash-merge. The split is purely a signal for reviewer context, not a permanent history artifact.

finalize Runs on Branches With Only Uncommitted Work

finalize no longer stops at its empty-diff check when a branch has zero commits ahead of the base but a dirty working tree. It now treats the uncommitted changes as the work to finalize (committing them in the squash step) and only reports "nothing to finalize" when there are no commits ahead and the tree is clean.

Single-Package Repos No Longer Misdetected as Monorepos

user-docs-detect-shape previously classified any repo with a workspaces field as monorepo-root. A self-referential workspaces: ["."] on a private: true root with no real sub-packages (for example a Claude Code plugin repo) is now correctly classified as single, so downstream README and badge guidance is appropriate for the repo.

design-sync Flags Stale Config Snippets in Design Docs

design-sync now detects design-doc prose that transcribes design.config.json keys/values and flags it when it diverges from the live config, recommending a pointer to the file instead. The design-doc style rule discourages embedding config shape as a second source of truth.

This is a version-only release. No packages were published to a registry.

0.7.0

Features

• f3493ce /design-docs:design-groom — autonomous top-to-bottom design-doc overhaul: validates, restyles, resyncs against code, prunes stale context, splits oversized docs, reconciles cross-references, updates CLAUDE.md references, then commits (no push). Runs unattended.
• /design-docs:design-split — splits an oversized design doc into atomic, cross-referenced pieces; available to the design-doc-agent and on demand.

Bug Fixes

• f3493ce allow-design-writes hook now auto-approves CLAUDE.md writes, so the grooming pass can run unattended.
• Corrected the allow-design-writes hook path referenced by the context-doc-agent and user-docs agents.

• f3493ce finalize no longer errors with "Usage credits required for 1M context". Removed the model: sonnet override so the user-invoked skill inherits the session model instead of forcing a model switch.

This is a version-only release. No packages were published to a registry.

0.6.0

Features

• b63177a ### Session handoff skill

Adds the /design-docs:handoff skill for transferring task state between Claude Code sessions.

• In a failing or context-exhausted session, captures the current task state to .claude/handoffs/HANDOFF.md
• In a fresh session, reads an existing handoff back into context and archives it
• Flags: --resume, --update, --archive, --list, --dry-run
• The skill is listed in the SessionStart hook's skill catalog; pickup is manual — run /design-docs:handoff in the fresh session to resume

This is a version-only release. No packages were published to a registry.

0.5.0

Breaking Changes

• db0b640 The --docs-only flag has been removed from /design-docs:finalize. Replace it with the two new negative-form skip flags:

Old	New
--docs-only	(no equivalent — run the full pipeline or use the skip flags below)
(n/a)	--no-context-docs — skips CLAUDE.md updates
(n/a)	--no-user-docs — skips user-facing doc updates

--no-push and --no-pr are now separate flags with distinct semantics: --no-push keeps the work local (skip step 8 entirely), while --no-pr pushes the branch but skips PR creation (useful when CI or a separate tool opens the PR). --no-squash and --dry-run are unchanged.

Features

• db0b640 ### Model-invokable finalize skill

/design-docs:finalize now runs when the model recognizes end-of-branch phrases. Trigger phrases such as "finalize this branch", "wrap up", "ship it", "ready to merge — run the prep", and "I'm done with this work, prep it for merge" automatically route to the skill. /design-docs:review and /design-docs:merge-prep remain user-invocable only.

Agent-dispatch architecture for doc steps

Steps 3–5 of the finalize pipeline now dispatch the bundled documentation agents (design-doc-agent, context-doc-agent, user-docs) via the Agent tool instead of invoking individual sub-skills directly. Each agent loads its matching *-docs-style skill automatically, tightening style enforcement across the full pipeline.

Documentation agent color badges

design-doc-agent, context-doc-agent, and user-docs now carry color metadata for transcript badge identification (red, pink, and blue respectively). Each agent also declares its matching style skill so it auto-loads on dispatch.

This is a version-only release. No packages were published to a registry.

0.4.1

Features

• 878d8a2 ### PreToolUse now covers MultiEdit

The allow-design-writes matcher was extended from Write|Edit to Write|Edit|MultiEdit. MultiEdit operations against .claude/design/ and .claude/plans/ are now auto-approved on the same terms as Write and Edit, eliminating a permission prompt that previously interrupted multi-step doc edits.

Documentation

• 878d8a2 Synced the plugin architecture design doc with the new hook layout, shared lib/, and updated diagrams.
• Updated root and plugin CLAUDE.md to reflect the per-event subdirectory convention and the third lib/ helper.
• Corrected CONTRIBUTING.md hook-path convention to plugin/hooks/<event-kebab>/{name}.sh.
• Style-skill content (context-docs-style, design-docs-style) refined; finalize/review/merge-prep workflow SKILL.md files updated.

Refactoring

• 878d8a2 ### Per-event hook directory layout

Hook scripts now live in event-name subdirectories under plugin/hooks/, with shared helpers in a lib/ sibling. The flat layout (plugin/hooks/session-start.sh, plugin/hooks/allow-design-writes.sh) is gone.

• plugin/hooks/session-start/context-inject.sh — SessionStart context injection
• plugin/hooks/pre-tool-use/allow-design-writes.sh — PreToolUse auto-approve for .claude/design/ and .claude/plans/
• plugin/hooks/lib/ — shared helpers (hook-output.sh, hook-debug.sh, source-session-env.sh) sourced via relative paths

The new layout makes path-based plugin-bash-engineer skills auto-load when hook scripts are edited, and keeps shared code out of the registration surface. hooks.json was updated to point at the new paths and quotes ${CLAUDE_PLUGIN_ROOT} so paths with spaces survive expansion.

Skill script hardening

Bash scripts across design-audit/, design-validate/, design-update/, plan-complete/, plan-explore/, plan-validate/, and review/ were tightened — stricter shell options, clearer error reporting, safer path handling, and consistent exit-code semantics. No behavior change for existing successful invocations; failure modes are clearer.

This is a version-only release. No packages were published to a registry.