From 7251c6c7df6733711e326a77be6a05edd0249954 Mon Sep 17 00:00:00 2001 From: Roger Barnes Date: Wed, 18 Nov 2026 15:50:08 +1100 Subject: [PATCH 1/4] feat(dev-plugin): sctx-dev contributor plugin with doc-review, test-review and the review check Adds a second plugin to the marketplace, for contributors to the structured-context repositories rather than users: - doc-review moves out of .claude/skills and refers to the repo's own AGENTS.md and definition of done, so it works in any of the repos. - test-review checks new and changed tests for duplication, schema re-testing, repeated code paths, self-fulfilling assertions, hard-coded lists and tests a change leaves redundant. - scripts/review-check.sh replaces scripts/prose-check.sh. It checks two kinds, prose and tests, each with its own review stamp and --mark, skips paths marked linguist-generated, and gives its fetch of origin/main 10 seconds. - The Stop hook runs the check in the session's repo, or in each checkout directly under the folder a session starts in. This repo enables the plugin in .claude/settings.json and calls the script from pre-push. --- .claude-plugin/marketplace.json | 5 ++ .claude/settings.json | 12 ++- .gitattributes | 3 + AGENTS.md | 2 +- dev-plugin/.claude-plugin/plugin.json | 7 ++ dev-plugin/hooks/hooks.json | 15 ++++ dev-plugin/scripts/on-stop.sh | 18 ++++ dev-plugin/scripts/review-check.sh | 90 +++++++++++++++++++ .../skills/doc-review/SKILL.md | 22 ++--- dev-plugin/skills/test-review/SKILL.md | 42 +++++++++ docs/architecture.md | 4 + lefthook.yml | 4 +- scripts/prose-check.sh | 44 --------- tests/docs/references.test.ts | 4 +- 14 files changed, 209 insertions(+), 63 deletions(-) create mode 100644 .gitattributes create mode 100644 dev-plugin/.claude-plugin/plugin.json create mode 100644 dev-plugin/hooks/hooks.json create mode 100755 dev-plugin/scripts/on-stop.sh create mode 100755 dev-plugin/scripts/review-check.sh rename {.claude => dev-plugin}/skills/doc-review/SKILL.md (66%) create mode 100644 dev-plugin/skills/test-review/SKILL.md delete mode 100755 scripts/prose-check.sh diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 3094d36e..81990dbb 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -9,6 +9,11 @@ { "name": "structured-context", "source": "./plugin" + }, + { + "name": "sctx-dev", + "source": "./dev-plugin", + "description": "For contributors to the structured-context repositories, not for users: review skills and a Stop hook that enforce each repo's documentation and test standards." } ] } diff --git a/.claude/settings.json b/.claude/settings.json index 566b31db..00e0bec3 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -1,4 +1,12 @@ { + "extraKnownMarketplaces": { + "structured-context": { + "source": { "source": "github", "repo": "mindsocket/structured-context" } + } + }, + "enabledPlugins": { + "sctx-dev@structured-context": true + }, "hooks": { "Stop": [ { @@ -6,10 +14,6 @@ { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.agents/hooks/lint-and-test.sh" - }, - { - "type": "command", - "command": "\"$CLAUDE_PROJECT_DIR\"/scripts/prose-check.sh" } ] } diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..db52d9b6 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,3 @@ +# Generated files: collapsed in GitHub diffs and left out of the sctx-dev review check. +plugin/hooks/projection.js linguist-generated +plugin/types/index.d.ts linguist-generated diff --git a/AGENTS.md b/AGENTS.md index 65eb247e..6d7c0fd5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -75,4 +75,4 @@ Run `bun run test` during development. Run the others with `bun run` when a chan ## Hooks Address issues related to change you made if a Stop hook reports them. -The Stop hook and pre-push block while the branch adds docs or code comments that `doc-review` has not seen (`scripts/prose-check.sh`). +The Stop hook and pre-push block while the branch adds docs, code comments or tests that the `doc-review` or `test-review` skill has not seen. Both come from the contributor plugin, `sctx-dev` ([docs/architecture.md](docs/architecture.md#contributor-plugin)). diff --git a/dev-plugin/.claude-plugin/plugin.json b/dev-plugin/.claude-plugin/plugin.json new file mode 100644 index 00000000..e2f3f0b8 --- /dev/null +++ b/dev-plugin/.claude-plugin/plugin.json @@ -0,0 +1,7 @@ +{ + "name": "sctx-dev", + "description": "For contributors to structured-context repositories: doc-review and test-review skills, and a Stop hook that blocks while a branch adds prose or tests no review has seen.", + "homepage": "https://github.com/mindsocket/structured-context", + "repository": "https://github.com/mindsocket/structured-context", + "license": "MIT" +} diff --git a/dev-plugin/hooks/hooks.json b/dev-plugin/hooks/hooks.json new file mode 100644 index 00000000..c473bb7b --- /dev/null +++ b/dev-plugin/hooks/hooks.json @@ -0,0 +1,15 @@ +{ + "hooks": { + "Stop": [ + { + "hooks": [ + { + "type": "command", + "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/on-stop.sh\"", + "timeout": 120 + } + ] + } + ] + } +} diff --git a/dev-plugin/scripts/on-stop.sh b/dev-plugin/scripts/on-stop.sh new file mode 100755 index 00000000..781ba97b --- /dev/null +++ b/dev-plugin/scripts/on-stop.sh @@ -0,0 +1,18 @@ +#!/usr/bin/env bash +# Runs the review check for the session's repo. A session started in a folder above +# several checkouts gets the check for each git checkout directly under it. +set -uo pipefail + +check="$(dirname "$0")/review-check.sh" + +if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then + exec bash "$check" +fi + +status=0 +for dir in */; do + [ -e "$dir.git" ] || continue + (cd "$dir" && bash "$check") + [ $? -eq 2 ] && status=2 +done +exit "$status" diff --git a/dev-plugin/scripts/review-check.sh b/dev-plugin/scripts/review-check.sh new file mode 100755 index 00000000..551973e3 --- /dev/null +++ b/dev-plugin/scripts/review-check.sh @@ -0,0 +1,90 @@ +#!/usr/bin/env bash +# Exits 2 while the branch adds prose (docs and code comments) or tests that no review +# has seen. A kind argument (prose or tests) checks that kind only. --mark +# records the current additions of that kind as reviewed. +# +# Paths with the linguist-generated attribute in .gitattributes are left out. +set -uo pipefail + +script="$(cd "$(dirname "$0")" && pwd)/$(basename "$0")" + +mark= +if [ "${1:-}" = "--mark" ]; then + mark=1 + shift + if [ $# -ne 1 ]; then + echo "usage: $script --mark prose|tests" >&2 + exit 1 + fi +fi +kinds="${*:-prose tests}" +for kind in $kinds; do + case "$kind" in + prose | tests) ;; + *) + echo "unknown kind: $kind (expected prose or tests)" >&2 + exit 1 + ;; + esac +done + +root="$(git rev-parse --show-toplevel 2>/dev/null)" || exit 0 +cd "$root" || exit 0 + +# A slow or unreachable remote must not hold up a hook, so the fetch gets 10 seconds. +git fetch --quiet origin main >/dev/null 2>&1 & +fetch=$! +(sleep 10 && kill "$fetch") >/dev/null 2>&1 & +watch=$! +wait "$fetch" 2>/dev/null +kill "$watch" 2>/dev/null + +base="$(git merge-base origin/main HEAD 2>/dev/null)" || exit 0 + +# Prints "filelabelline" for each added line of the kind, untracked files included. +added() { + local specs + case "$1" in + prose) specs=('*.md' '*.ts' '*.tsx' '*.js' '*.mjs' '*.cjs' '*.sh' '*.yml' '*.yaml' '*.json5' '*.jsonc') ;; + tests) specs=('*.test.*' '*.spec.*') ;; + esac + specs+=(':(exclude,attr:linguist-generated)') + { + git diff -U0 --no-color "$base" -- "${specs[@]}" + git ls-files -z --others --exclude-standard -- "${specs[@]}" | + xargs -0 -r -n1 git diff -U0 --no-color --no-index /dev/null + } | awk -v kind="$1" ' + /^\+\+\+ b\// { file = substr($0, 7); doc = file ~ /\.md$/; next } + /^\+/ { + line = substr($0, 2) + if (line !~ /[^[:space:]]/) next + if (kind == "tests") print file "\ttest\t" line + else if (doc) print file "\tdoc\t" line + else if (line ~ /^[[:space:]]*(\/\/|\/\*|\*|#)/ && line !~ /^#!/) print file "\tcomment\t" line + }' +} + +status=0 +for kind in $kinds; do + lines="$(added "$kind")" + stamp="$(git rev-parse --git-path "$kind-reviewed")" + hash="$(printf '%s' "$lines" | git hash-object --stdin)" + if [ -n "$mark" ]; then + echo "$hash" >"$stamp" + continue + fi + [ -z "$lines" ] && continue + [ "$(cat "$stamp" 2>/dev/null)" = "$hash" ] && continue + + case "$kind" in + prose) what="Prose" skill="doc-review" ;; + tests) what="Tests" skill="test-review" ;; + esac + { + echo "$what added in $root since the last $skill:" + printf '%s\n' "$lines" | awk -F'\t' '{ n[$1 " (" $2 ")"]++ } END { for (f in n) printf " %4d %s\n", n[f], f }' | sort -rn + echo "Run the $skill skill on this diff, apply its findings, then run $script --mark $kind." + } >&2 + status=2 +done +exit "$status" diff --git a/.claude/skills/doc-review/SKILL.md b/dev-plugin/skills/doc-review/SKILL.md similarity index 66% rename from .claude/skills/doc-review/SKILL.md rename to dev-plugin/skills/doc-review/SKILL.md index 79647a29..abf321e7 100644 --- a/.claude/skills/doc-review/SKILL.md +++ b/dev-plugin/skills/doc-review/SKILL.md @@ -1,15 +1,16 @@ --- name: doc-review -description: Review written content in this repo (README, docs/, AGENTS.md, plugin skills and references, CLI help and error text) against the project's documentation standards, then fix what it finds. Use after writing or changing any prose, before committing or opening a PR. +description: Review written content in a structured-context (sctx) repo (README, docs/, AGENTS.md, skills and references, code comments, CLI help and error text) against the repo's documentation standards, then fix what it finds. Use after writing or changing any prose, before committing or opening a PR. +allowed-tools: Bash(${CLAUDE_PLUGIN_ROOT}/scripts/review-check.sh --mark prose) --- ## Task Review the prose in the target named by `$ARGUMENTS`: a PR number, branch, commit, or list of files. With no argument, use uncommitted changes, or if there are none, the branch against `main` (`git diff main...HEAD`). -Look at `*.md`, `plugin/**`, and user-facing strings in `src/` and tests. Apply the **Documentation Principles** in -`AGENTS.md`, then fix the findings. Re-read each finding in context: a flagged phrase is sometimes the right -wording. +Look at `*.md`, skills, code comments, and user-facing strings in source and tests. Apply the documentation +principles in the repo's `AGENTS.md`, then fix the findings. Re-read each finding in context: a flagged phrase is +sometimes the right wording. ## Checks @@ -21,13 +22,13 @@ For every changed passage, ask: implication the reader can work out, or describe what is not the case without a likely wrong assumption to correct. Flag error codes and flags the output already shows. 3. **Is it in the right place?** Flag duplicated explanations (owned once, linked elsewhere). A README section is - a sentence or two pointing to docs/. Detail used rarely belongs in `references/` or `sctx docs`. + a sentence or two pointing to docs/. Detail used rarely belongs in a skill's `references/` or a linked doc. 4. **Is a recommendation labelled as one?** "It is recommended to..." rather than a rule stated as fact. 5. **Follows the doc's convention:** a new entry matches its neighbours in size and shape. Do not describe call signatures, options, fields or types that the code already defines, since they go stale; say what it is for. -6. **Names:** `structured-context` in prose, `sctx` only in commands. Terms match `docs/concepts.md`. +6. **Names** follow the naming rules in `AGENTS.md`, and terms match the repo's glossary (`docs/concepts.md`). -Skills and references (`plugin/skills/**`), also: +Skills and references (a `SKILL.md` and its `references/`), also: 7. **Trigger:** the `description` names structured-context (sctx) and the task in words a user or agent would use, briefly. It does not rely on terms an agent session may not know (such as "space"). @@ -45,6 +46,7 @@ Code comments and messages: ## Output -List findings as `file:line, check number, proposed rewrite`, then apply them. Run `bun run lint` and, if -`plugin/` changed, `bun run test:hook`. Finish by checking `docs/definition-of-done.md` for files -the change affects but does not touch, then run `scripts/prose-check.sh --mark`. +List findings as `file:line, check number, proposed rewrite`, then apply them. Run the repo's lint and any check +its definition of done names for the area changed. Finish by checking the definition of done (in `AGENTS.md` or +the doc it links) for files the change affects but does not touch, then run +`${CLAUDE_PLUGIN_ROOT}/scripts/review-check.sh --mark prose`. diff --git a/dev-plugin/skills/test-review/SKILL.md b/dev-plugin/skills/test-review/SKILL.md new file mode 100644 index 00000000..d567388b --- /dev/null +++ b/dev-plugin/skills/test-review/SKILL.md @@ -0,0 +1,42 @@ +--- +name: test-review +description: Review new or changed tests in a structured-context (sctx) repo for tests that duplicate others, re-test a schema, or assert what their own setup makes true, then fix what it finds. Use after adding or changing tests, before committing or opening a PR. +allowed-tools: Bash(${CLAUDE_PLUGIN_ROOT}/scripts/review-check.sh --mark tests) +--- + +## Task + +Review the tests in the target named by `$ARGUMENTS`: a PR number, branch, commit, or list of files. With no +argument, use uncommitted changes, or if there are none, the branch against `main` (`git diff main...HEAD`). +Apply the test principles in the repo's `AGENTS.md`, then fix the findings. Read the code under test and the +neighbouring test files before judging a test: coverage is a property of the whole suite. + +## Checks + +For every added or changed test, ask: + +1. **Does it prove something no other test does?** Search the suite for a test that already covers the + behaviour. Flag the newer or weaker one. +2. **Does it re-test a JSON Schema?** A schema's own constraints (types, required keys, enums, patterns) are the + validator's job. Test only the checks the schema can't express. +3. **Is it a second input down a covered code path?** One input per path. Flag cases, `each` rows or fixtures + that take a branch another case already takes. +4. **Does it assert what its own setup makes true?** Flag assertions that hold because of the test's config, + fixture or mock, whatever the code under test does. +5. **Are expected values derived?** Expected values come from the fixture or the code under test, not from a + copy of the output pasted in. +6. **Will it grow with the code?** Flag hard-coded lists (layouts, exports, files, schema keys) that a new entry + elsewhere makes stale. +7. **Does it assert the behaviour its name states?** Flag names that promise more or other than the assertions + check, and assertions on things that only happen to be true. + +For the change as a whole: + +8. **Did it make a test redundant?** When a change moves or narrows behaviour, flag the tests it leaves proving + nothing new, including ones the diff doesn't touch. + +## Output + +List findings as `file:line, check number, proposed change` (a rewrite, a merge into another test, or a deletion +naming the test that covers it), then apply them. Run the repo's test, typecheck and lint commands from +`AGENTS.md`. Finish with `${CLAUDE_PLUGIN_ROOT}/scripts/review-check.sh --mark tests`. diff --git a/docs/architecture.md b/docs/architecture.md index ca72c27a..8febdda5 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -113,6 +113,10 @@ The map pane (`plugin/hooks/map-pane.tsx`, `/sctx-map`) draws a space's hierarch Git hooks (`lefthook.yml`, `scripts/sync-plugin-version.ts`) manage the version in `plugin/.claude-plugin/plugin.json`. Pre-commit bumps the patch version for any commit touching `plugin/`, so the plugin version runs ahead of `package.json` between releases. It also raises major.minor to match `package.json` after a release. Pre-push fails if a commit since the last tag changed `plugin/` without a version bump. +### Contributor plugin + +`dev-plugin/` is `sctx-dev`, a second plugin in the same marketplace. It is for contributors to the structured-context repositories, not for users. It has the `doc-review` and `test-review` skills and `dev-plugin/scripts/review-check.sh`, which exits 2 while a branch adds prose (docs and code comments) or tests that no review has marked. Its Stop hook runs the check in the session's repo, or in each checkout directly under the folder the session started in. A repository opts in by enabling the plugin in its `.claude/settings.json` and calling the script from pre-push. The check skips paths that `.gitattributes` marks `linguist-generated`. The plugin has no version, so installs follow the marketplace's commits. + --- ## Field Remapping diff --git a/lefthook.yml b/lefthook.yml index 1d971e00..e0c04a50 100644 --- a/lefthook.yml +++ b/lefthook.yml @@ -29,5 +29,5 @@ pre-push: run: bash scripts/sync-plugin-version.sh --check pushed-tree: run: bash scripts/git-hooks/check-pushed-tree.sh - prose-check: - run: bash scripts/prose-check.sh + review-check: + run: bash dev-plugin/scripts/review-check.sh diff --git a/scripts/prose-check.sh b/scripts/prose-check.sh deleted file mode 100755 index d13b109b..00000000 --- a/scripts/prose-check.sh +++ /dev/null @@ -1,44 +0,0 @@ -#!/usr/bin/env bash -# Exits 2 while the branch adds docs or code comments that no doc-review has seen. -# --mark records the current additions as reviewed. -set -uo pipefail - -root="$(git rev-parse --show-toplevel)" || exit 0 -cd "$root" || exit 0 -base="$(git merge-base origin/main HEAD 2>/dev/null)" || exit 0 -stamp="$(git rev-parse --git-path prose-reviewed)" - -code='*.ts *.tsx *.js *.mjs *.cjs *.sh *.yml *.yaml' -generated=':!plugin/hooks/projection.js :!plugin/types/index.d.ts :!schemas/generated' - -# Prints "filekindline" for each added prose line, untracked files included. -added() { - { - git diff -U0 --no-color "$base" -- '*.md' $code $generated - git ls-files -z --others --exclude-standard -- '*.md' $code $generated | - xargs -0 -r -n1 git diff -U0 --no-color --no-index /dev/null - } | awk ' - /^\+\+\+ b\// { file = substr($0, 7); doc = file ~ /\.md$/; next } - /^\+/ { - line = substr($0, 2) - if (doc) { if (line ~ /[^[:space:]]/) print file "\tdoc\t" line } - else if (line ~ /^[[:space:]]*(\/\/|\/\*|\*|#)/ && line !~ /^#!/) print file "\tcomment\t" line - }' -} - -lines="$(added)" -[ -z "$lines" ] && exit 0 -hash="$(printf '%s' "$lines" | git hash-object --stdin)" - -if [ "${1:-}" = "--mark" ]; then - echo "$hash" >"$stamp" - exit 0 -fi -[ "$(cat "$stamp" 2>/dev/null)" = "$hash" ] && exit 0 - -{ - echo "Prose added since the last doc-review:" - printf '%s\n' "$lines" | awk -F'\t' '{ n[$1 " (" $2 ")"]++ } END { for (f in n) printf " %4d %s\n", n[f], f }' | sort -rn - echo "Run the doc-review skill on this diff, apply its cuts, then run scripts/prose-check.sh --mark." -} >&2 -exit 2 diff --git a/tests/docs/references.test.ts b/tests/docs/references.test.ts index 46e43ae6..71e7b378 100644 --- a/tests/docs/references.test.ts +++ b/tests/docs/references.test.ts @@ -14,10 +14,10 @@ import { join, resolve } from 'node:path'; const ROOT = resolve(import.meta.dir, '../..'); /** Docs that describe the current tree: agent instructions, README, top-level docs, and plugin skills. */ -const SCANNED = ['README.md', 'AGENTS.md', 'docs', 'plugin']; +const SCANNED = ['README.md', 'AGENTS.md', 'docs', 'plugin', 'dev-plugin']; /** Repo-relative paths appear in backticks; these are the roots worth checking. */ -const PATH_PATTERN = /`\/?((?:src|tests|schemas|plugin|docs|scripts|hook-test|smoke)\/[^`\s]*)`/g; +const PATH_PATTERN = /`\/?((?:src|tests|schemas|plugin|dev-plugin|docs|scripts|hook-test|smoke)\/[^`\s]*)`/g; /** Illustrative paths, not real ones: placeholders, globs, and naming-convention examples. */ const PLACEHOLDER = /YYYY|<[^>]+>|\[[^\]]+\]|\*|PascalCase|kebab-case|\bNN\b|\.\.\./; From b17b31cefa2d08e8faf8047be65e13300d17f190 Mon Sep 17 00:00:00 2001 From: Roger Barnes Date: Wed, 18 Nov 2026 22:40:34 +1100 Subject: [PATCH 2/4] feat(dev-plugin): check the repo holding the hook's cwd, on Stop and SubagentStop A subagent in its own worktree now gets the review check for that worktree when it stops; measured: SubagentStop's cwd is the subagent's worktree. Also marks schemas/generated and bun.lock as generated. --- .gitattributes | 2 ++ AGENTS.md | 2 +- dev-plugin/.claude-plugin/plugin.json | 2 +- dev-plugin/hooks/hooks.json | 11 +++++++++++ dev-plugin/scripts/on-stop.sh | 9 +++++++-- docs/architecture.md | 2 +- 6 files changed, 23 insertions(+), 5 deletions(-) diff --git a/.gitattributes b/.gitattributes index db52d9b6..5e0f892e 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,3 +1,5 @@ # Generated files: collapsed in GitHub diffs and left out of the sctx-dev review check. plugin/hooks/projection.js linguist-generated plugin/types/index.d.ts linguist-generated +schemas/generated/** linguist-generated +bun.lock linguist-generated diff --git a/AGENTS.md b/AGENTS.md index 6d7c0fd5..00e8433d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -75,4 +75,4 @@ Run `bun run test` during development. Run the others with `bun run` when a chan ## Hooks Address issues related to change you made if a Stop hook reports them. -The Stop hook and pre-push block while the branch adds docs, code comments or tests that the `doc-review` or `test-review` skill has not seen. Both come from the contributor plugin, `sctx-dev` ([docs/architecture.md](docs/architecture.md#contributor-plugin)). +The Stop and SubagentStop hooks and pre-push block while the branch adds docs, code comments or tests that the `doc-review` or `test-review` skill has not seen. Both come from the contributor plugin, `sctx-dev` ([docs/architecture.md](docs/architecture.md#contributor-plugin)). diff --git a/dev-plugin/.claude-plugin/plugin.json b/dev-plugin/.claude-plugin/plugin.json index e2f3f0b8..c46fb44d 100644 --- a/dev-plugin/.claude-plugin/plugin.json +++ b/dev-plugin/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "sctx-dev", - "description": "For contributors to structured-context repositories: doc-review and test-review skills, and a Stop hook that blocks while a branch adds prose or tests no review has seen.", + "description": "For contributors to structured-context repositories: doc-review and test-review skills, and Stop and SubagentStop hooks that block while a branch adds prose or tests no review has seen.", "homepage": "https://github.com/mindsocket/structured-context", "repository": "https://github.com/mindsocket/structured-context", "license": "MIT" diff --git a/dev-plugin/hooks/hooks.json b/dev-plugin/hooks/hooks.json index c473bb7b..016291d0 100644 --- a/dev-plugin/hooks/hooks.json +++ b/dev-plugin/hooks/hooks.json @@ -10,6 +10,17 @@ } ] } + ], + "SubagentStop": [ + { + "hooks": [ + { + "type": "command", + "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/on-stop.sh\"", + "timeout": 120 + } + ] + } ] } } diff --git a/dev-plugin/scripts/on-stop.sh b/dev-plugin/scripts/on-stop.sh index 781ba97b..7f330361 100755 --- a/dev-plugin/scripts/on-stop.sh +++ b/dev-plugin/scripts/on-stop.sh @@ -1,10 +1,15 @@ #!/usr/bin/env bash -# Runs the review check for the session's repo. A session started in a folder above -# several checkouts gets the check for each git checkout directly under it. +# Runs the review check for the repo holding the hook's cwd: the session's checkout, or a +# subagent's own worktree on SubagentStop. Where cwd is a folder above several checkouts, +# each git checkout directly under it gets the check. set -uo pipefail check="$(dirname "$0")/review-check.sh" +# Without jq the hook stays in the directory Claude Code ran it from. +cwd="$(jq -r '.cwd // empty' 2>/dev/null)" +[ -n "$cwd" ] && cd "$cwd" 2>/dev/null + if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then exec bash "$check" fi diff --git a/docs/architecture.md b/docs/architecture.md index 8febdda5..ed793a6f 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -115,7 +115,7 @@ Git hooks (`lefthook.yml`, `scripts/sync-plugin-version.ts`) manage the version ### Contributor plugin -`dev-plugin/` is `sctx-dev`, a second plugin in the same marketplace. It is for contributors to the structured-context repositories, not for users. It has the `doc-review` and `test-review` skills and `dev-plugin/scripts/review-check.sh`, which exits 2 while a branch adds prose (docs and code comments) or tests that no review has marked. Its Stop hook runs the check in the session's repo, or in each checkout directly under the folder the session started in. A repository opts in by enabling the plugin in its `.claude/settings.json` and calling the script from pre-push. The check skips paths that `.gitattributes` marks `linguist-generated`. The plugin has no version, so installs follow the marketplace's commits. +`dev-plugin/` is `sctx-dev`, a second plugin in the same marketplace. It is for contributors to the structured-context repositories, not for users. It has the `doc-review` and `test-review` skills and `dev-plugin/scripts/review-check.sh`, which exits 2 while a branch adds prose (docs and code comments) or tests that no review has marked. Its Stop and SubagentStop hooks run the check in the repo holding the hook's working directory, which for a subagent with its own worktree is that worktree. Where that directory is a folder above several checkouts, each checkout directly under it is checked. A repository opts in by enabling the plugin in its `.claude/settings.json` and calling the script from pre-push. The check skips paths that `.gitattributes` marks `linguist-generated`. The plugin has no version, so installs follow the marketplace's commits. --- From 09f20a2a6635af5d960458baec3a7aafeb3749d9 Mon Sep 17 00:00:00 2001 From: Roger Barnes Date: Wed, 18 Nov 2026 22:53:10 +1100 Subject: [PATCH 3/4] docs(dev-plugin): architecture says what the contributor plugin is for and links the check The section repeated what review-check.sh and on-stop.sh document. The marketplace entry no longer repeats the plugin manifest's description. --- .claude-plugin/marketplace.json | 3 +-- docs/architecture.md | 2 +- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 81990dbb..368a1c4a 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -12,8 +12,7 @@ }, { "name": "sctx-dev", - "source": "./dev-plugin", - "description": "For contributors to the structured-context repositories, not for users: review skills and a Stop hook that enforce each repo's documentation and test standards." + "source": "./dev-plugin" } ] } diff --git a/docs/architecture.md b/docs/architecture.md index ed793a6f..37b1b1e1 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -115,7 +115,7 @@ Git hooks (`lefthook.yml`, `scripts/sync-plugin-version.ts`) manage the version ### Contributor plugin -`dev-plugin/` is `sctx-dev`, a second plugin in the same marketplace. It is for contributors to the structured-context repositories, not for users. It has the `doc-review` and `test-review` skills and `dev-plugin/scripts/review-check.sh`, which exits 2 while a branch adds prose (docs and code comments) or tests that no review has marked. Its Stop and SubagentStop hooks run the check in the repo holding the hook's working directory, which for a subagent with its own worktree is that worktree. Where that directory is a folder above several checkouts, each checkout directly under it is checked. A repository opts in by enabling the plugin in its `.claude/settings.json` and calling the script from pre-push. The check skips paths that `.gitattributes` marks `linguist-generated`. The plugin has no version, so installs follow the marketplace's commits. +`dev-plugin/` is `sctx-dev`, a second plugin in the same marketplace, for contributors to the structured-context repositories. Its skills review a change against each repo's documentation and test standards. Its hooks and each repo's pre-push block while a branch adds prose or tests that no review has seen. `dev-plugin/scripts/review-check.sh` describes the check. A repository opts in by enabling the plugin in its `.claude/settings.json` and calling that script from pre-push. The plugin has no version, so installs follow the marketplace's commits. --- From 0d88ea1d5679f5eaf26c9484b8c4a3532e8d4ab3 Mon Sep 17 00:00:00 2001 From: Roger Barnes Date: Wed, 18 Nov 2026 22:57:07 +1100 Subject: [PATCH 4/4] feat(dev-plugin): doc-review reads whole passages and what they describe, and reports every check A review that looked only at changed lines, without reading the code a passage described, passed a section that duplicated the scripts' own comments. --- dev-plugin/skills/doc-review/SKILL.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/dev-plugin/skills/doc-review/SKILL.md b/dev-plugin/skills/doc-review/SKILL.md index abf321e7..6c04ebd0 100644 --- a/dev-plugin/skills/doc-review/SKILL.md +++ b/dev-plugin/skills/doc-review/SKILL.md @@ -14,15 +14,16 @@ sometimes the right wording. ## Checks -For every changed passage, ask: +Read each changed paragraph or section in full, not only its changed lines, and ask: 1. **Would someone new to the project understand it?** Flag decision history and internal jargon ("never merged by location", "A′", phase names). Say what does happen. 2. **Does it earn its place?** Flag sentences that restate the previous one, state the obvious, spell out an implication the reader can work out, or describe what is not the case without a likely wrong assumption to correct. Flag error codes and flags the output already shows. -3. **Is it in the right place?** Flag duplicated explanations (owned once, linked elsewhere). A README section is - a sentence or two pointing to docs/. Detail used rarely belongs in a skill's `references/` or a linked doc. +3. **Is it in the right place?** Read the code and docs the passage describes, then flag duplicated explanations + (owned once, linked elsewhere). A README section is a sentence or two pointing to docs/. Detail used rarely + belongs in a skill's `references/` or a linked doc. 4. **Is a recommendation labelled as one?** "It is recommended to..." rather than a rule stated as fact. 5. **Follows the doc's convention:** a new entry matches its neighbours in size and shape. Do not describe call signatures, options, fields or types that the code already defines, since they go stale; say what it is for. @@ -46,7 +47,8 @@ Code comments and messages: ## Output -List findings as `file:line, check number, proposed rewrite`, then apply them. Run the repo's lint and any check -its definition of done names for the area changed. Finish by checking the definition of done (in `AGENTS.md` or -the doc it links) for files the change affects but does not touch, then run +Go through the checks in order. List each finding as `file:line, check number, proposed rewrite`, and write "none" +for a check with no findings. Then apply them. Run the repo's lint and any check its definition of done names for +the area changed. Finish by checking the definition of done (in `AGENTS.md` or the doc it links) for files the +change affects but does not touch, then run `${CLAUDE_PLUGIN_ROOT}/scripts/review-check.sh --mark prose`.