Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
4 changes: 4 additions & 0 deletions .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,10 @@
{
"name": "structured-context",
"source": "./plugin"
},
{
"name": "sctx-dev",
"source": "./dev-plugin"
}
]
}
12 changes: 8 additions & 4 deletions .claude/settings.json
Original file line number Diff line number Diff line change
@@ -1,15 +1,19 @@
{
"extraKnownMarketplaces": {
"structured-context": {
"source": { "source": "github", "repo": "mindsocket/structured-context" }
}
},
"enabledPlugins": {
"sctx-dev@structured-context": true
},
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.agents/hooks/lint-and-test.sh"
},
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/scripts/prose-check.sh"
}
]
}
Expand Down
5 changes: 5 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -0,0 +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
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 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)).
7 changes: 7 additions & 0 deletions dev-plugin/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"name": "sctx-dev",
"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"
}
26 changes: 26 additions & 0 deletions dev-plugin/hooks/hooks.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/on-stop.sh\"",
"timeout": 120
}
]
}
],
"SubagentStop": [
{
"hooks": [
{
"type": "command",
"command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/on-stop.sh\"",
"timeout": 120
}
]
}
]
}
}
23 changes: 23 additions & 0 deletions dev-plugin/scripts/on-stop.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
#!/usr/bin/env bash
# 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

status=0
for dir in */; do
[ -e "$dir.git" ] || continue
(cd "$dir" && bash "$check")
[ $? -eq 2 ] && status=2
done
exit "$status"
90 changes: 90 additions & 0 deletions dev-plugin/scripts/review-check.sh
Original file line number Diff line number Diff line change
@@ -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 <kind>
# 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 "file<TAB>label<TAB>line" 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"
Original file line number Diff line number Diff line change
@@ -1,33 +1,35 @@
---
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

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 `references/` or `sctx docs`.
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.
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").
Expand All @@ -45,6 +47,8 @@ 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`.
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`.
42 changes: 42 additions & 0 deletions dev-plugin/skills/test-review/SKILL.md
Original file line number Diff line number Diff line change
@@ -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`.
4 changes: 4 additions & 0 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Comment thread
mindsocket marked this conversation as resolved.
Resolved

`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.

---

## Field Remapping
Expand Down
4 changes: 2 additions & 2 deletions lefthook.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
44 changes: 0 additions & 44 deletions scripts/prose-check.sh

This file was deleted.

4 changes: 2 additions & 2 deletions tests/docs/references.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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|\.\.\./;
Expand Down
Loading