feat(pr-ready): add doc-check step to the workflow

hooks/pr-gate.sh

@@ -36,7 +36,7 @@ jq -n '{
   hookSpecificOutput: {
     hookEventName: "PreToolUse",
     permissionDecision: "ask",
-    permissionDecisionReason: "PR creation detected — want to run the pr-ready pipeline first? (lint, test, security, DRY review, changelog, monitor). Say yes to run it, or approve to skip and create the PR directly."
+    permissionDecisionReason: "PR creation detected — want to run the pr-ready pipeline first? (lint, test, security, changelog, doc-check, monitor). Say yes to run it, or approve to skip and create the PR directly."
   }
 }'
 exit 0

skills/pr-ready/SKILL.md

@@ -5,7 +5,7 @@ description: Full PR pipeline — use when asked to submit a PR, create a pull r
 
 # PR Ready
 
-Deterministic PR pipeline: validate → necessity → lint (loop) → test (loop) → security → changelog → create PR → monitor (loop).
+Deterministic PR pipeline: validate → necessity → lint (loop) → test (loop) → security → doc-check → changelog → create PR → monitor (loop).
 
 ## Invoke
 
@@ -22,9 +22,10 @@ Then follow each step the engine returns. Call `devkit_advance` after completing
 3. **lint** — runs linter, fixes violations, loops until clean
 4. **test** — runs test suite, fixes failures, loops until passing
 5. **security** — scans for hardcoded secrets, injection, XSS, traversal, insecure deps
-6. **changelog** — generates entry from git diff
-7. **create-pr** — pushes branch, creates PR via gh pr create with title/summary/changelog/test plan
-8. **monitor** — waits for CI, classifies reviewer comments (code_fix/style_nit/question/false_positive/out_of_scope), applies fixes, replies, pushes, loops until all resolved
+6. **doc-check** — classifies the diff (feature/bugfix/breaking/internal/docs-only) and decides per-file whether README, ROADMAP, CLAUDE.md, docs/, `skills/*/SKILL.md`, plugin.json, or `workflows/*.yml` need updates. Applies mechanical edits directly (moving roadmap bullets, adding command rows, syncing SKILL.md step lists); flags ambiguous updates as `[!]` in the output checklist. Commits applied edits with `docs: update ...` so they land in the PR alongside the code. CHANGELOG.md is intentionally skipped — it is managed by the release pipeline. Runs **before** `changelog` so any doc commit it creates is captured in the PR description.
+7. **changelog** — generates entry from git diff (now includes any doc-check commits)
+8. **create-pr** — pushes branch, creates PR via gh pr create with title/summary/changelog/test plan
+9. **monitor** — waits for CI, classifies reviewer comments (code_fix/style_nit/question/false_positive/out_of_scope), applies fixes, replies, pushes, loops until all resolved
 
 ## Rules
 

workflows/pr-ready.yml

@@ -57,11 +57,105 @@ steps:
 
       Report findings with severity and file:line references.
 
+  - id: doc-check
+    model: smart
+    prompt: |
+      Classify the diff (git diff main...HEAD) and decide which project
+      docs need updating so the user does not have to ask every PR.
+
+      This step runs BEFORE `changelog` so any `docs: update ...` commit
+      it creates is included in the changelog summary that `create-pr`
+      uses for the PR body.
+
+      STEP 1 — Classify the change as exactly one of:
+        - feature         (new user-visible capability)
+        - bugfix          (fixes existing behaviour)
+        - breaking        (removes/renames public surface, bumps required version, changes CLI/flag semantics)
+        - internal        (refactor, test, CI, build, infra — no user impact)
+        - docs-only       (README/CHANGELOG/ROADMAP/comments only)
+
+      STEP 2 — Enumerate candidate docs that exist at repo root and
+      decide per-file whether this PR requires an update. Use these
+      rules (each rule lists the classifications that force an update;
+      internal/docs-only PRs default to "not affected" unless stated):
+
+        - README.md
+          * feature: update if user-facing commands, install steps, or
+            the feature table changed.
+          * breaking: always update — migration note + changed surface.
+          * bugfix/internal: not affected unless README directly
+            describes the broken behaviour.
+
+        - ROADMAP.md
+          * feature: move the corresponding entry from "Planned" to
+            "Implemented", or add a new Implemented bullet.
+          * breaking: update if a roadmap item is now removed.
+          * bugfix/internal: not affected.
+
+        - CHANGELOG.md
+          * Managed by the release pipeline, not individual PRs. Never
+            write to it here unless the PR is an explicit release bump
+            (plugin.json version change).
+
+        - CLAUDE.md (or AGENTS.md)
+          * feature/breaking: update if project conventions, tool
+            selection rules, or workflow patterns changed.
+          * bugfix/internal: not affected.
+
+        - docs/ or *.md under docs/
+          * feature: update if an existing doc describes the subsystem
+            you touched.
+          * breaking: always update.
+
+        - skills/*/SKILL.md
+          * feature: update the affected skill's SKILL.md if a new
+            step, capability, or contract is added.
+          * breaking: update if a skill's invocation shape, step list,
+            or frontmatter description changed.
+          * If a `workflows/*.yml` file was edited, the matching
+            `skills/<workflow-name>/SKILL.md` step list MUST be kept
+            in sync — treat mismatches as a needs-update.
+
+        - plugin.json / manifest.json / .claude-plugin/
+          * breaking: update if commands, skills, agents, or MCP
+            servers were added/removed/renamed.
+          * feature: update if a new command/skill/agent is exposed.
+          * bugfix/internal: not affected unless the bug was a missing
+            manifest entry.
+
+        - workflows/*.yml
+          * feature: add/update if a workflow step was added or its
+            contract changed. When you edit a workflow, re-check the
+            matching SKILL.md rule above.
+          * internal: only if a workflow file itself was refactored.
+
+      STEP 3 — For each doc decided "needs update", either apply the
+      edit directly (Edit/Write tool) if the change is mechanical and
+      unambiguous (moving a roadmap bullet, adding a README command
+      row, renaming a manifest entry, syncing a SKILL.md step list),
+      OR emit a one-line TODO with the exact edit the user needs to
+      make.
+
+      STEP 4 — Output a markdown checklist of ALL candidate docs:
+          - [x] README.md — updated: <one-line summary>
+          - [ ] ROADMAP.md — not affected (bugfix)
+          - [ ] CHANGELOG.md — managed by release pipeline
+          - [!] CLAUDE.md — needs manual update: <TODO>
+      Use [x] for applied updates, [ ] for not-affected, [!] for
+      needs-manual-update.
+
+      Commit any applied edits with message
+          docs: update <files> for <classification>
+      so the doc changes land in the PR alongside the code and the
+      subsequent `changelog` step picks them up.
+
   - id: changelog
     model: fast
     prompt: |
       Generate a changelog entry from git diff main...HEAD.
-      Summarize what changed and why.
+      Summarize what changed and why. Any `docs: update ...` commit
+      created by the preceding `doc-check` step is in HEAD now and
+      must be reflected in this summary.
 
   - id: create-pr
     model: smart