Skip to content

Commit 69bb43c

Browse files
committed
docs(agents): move documentation out of AGENTS.md and tighten rules
Plugin description moves to architecture.md, the definition-of-done table to its own doc. Blast-radius rule becomes architecture first; settings and testing sections shortened. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019XphpcEV7rUeT4eXfKRGWV
1 parent 16d110a commit 69bb43c

4 files changed

Lines changed: 51 additions & 45 deletions

File tree

‎.claude/skills/doc-review/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,5 +44,5 @@ Code comments and messages:
4444
## Output
4545

4646
List findings as `file:line, check number, proposed rewrite`, then apply them. Run `bun run lint` and, if
47-
`plugin/` changed, `bun run test:hook`. Finish by checking the "Definition of done" table in `AGENTS.md` for files
47+
`plugin/` changed, `bun run test:hook`. Finish by checking `docs/definition-of-done.md` for files
4848
the change affects but does not touch.

‎AGENTS.md‎

Lines changed: 15 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -16,53 +16,24 @@ Before starting new work, review [docs/concepts.md](docs/concepts.md) for canoni
1616

1717
Space names (e.g. `personal`, `politics`) are resolved via a config file - `$SCTX_CONFIG`, `$XDG_CONFIG_HOME/structured-context/config.json`, `--config <file>` param, or the nearest `.sctx.json` or `.sctx/config.json` walking up from the working directory. Relative paths resolve from the config root, and local plugins, schemas and map views sit in `.sctx/` (`src/config/layout.ts`)
1818

19-
The lefthook pre-commit hook syncs the plugin version (below), then runs biome (`--write`, re-staged) and the typecheck.
19+
The lefthook pre-commit hook syncs the plugin version, then runs biome (`--write`, re-staged) and the typecheck.
2020

2121
## Claude Code Plugin
2222

23-
A Claude Code plugin lives at `plugin/`. It includes skills, commands and hooks used when working with collections of Obsidian markdown content (aka a space) in a vault.
24-
25-
The command hooks in `plugin/hooks/hooks.json` baseline each turn and gate it at Stop. The mod (`plugin/hooks/register.tsx`, a hooks module) adds to them: a line under the answer and a band above the prompt for the turn's new issues, a status line, the schemas of the spaces in the working directory in the system prompt, and `spaces`, `validate` and `schema` tools. It never validates per tool call, because a space can be invalid partway through a multi-file change. A mod has no Node, so it reaches the hooks' state and the CLI through `plugin/scripts/mod-bridge.ts`. `plugin/types/index.d.ts` declares the mod's `$.state`.
26-
27-
The map pane (`plugin/hooks/map-pane.tsx`, `/sctx-map`) draws a space's hierarchy with each node's validation results. A mod can't import packages, so the code it runs from core and `structured-context-map-views` is bundled into the committed `plugin/hooks/projection.js` by `bun run build:mod-projection`. The same command inlines the core types the mod shares (`scripts/mod-contract.ts`) into `plugin/types/index.d.ts`, which must be self-contained.
28-
29-
The plugin version in `plugin/.claude-plugin/plugin.json` is managed by git hooks (`lefthook.yml`, `scripts/sync-plugin-version.ts`); never edit it by hand:
30-
- **pre-commit:** bumps the patch version for any commit touching `plugin/`, so the plugin version runs ahead of `package.json` between releases by design. It also syncs major.minor up when `package.json` moves ahead (i.e. a release).
31-
- **pre-push:** fails if a commit since the last tag changed `plugin/` without bumping the version.
23+
`plugin/` is a Claude Code plugin for working with spaces. [docs/architecture.md](docs/architecture.md#claude-code-plugin) describes its hooks, mod and map pane. Never edit the version in `plugin/.claude-plugin/plugin.json`, because git hooks bump it.
3224

3325
## Definition of done
3426

35-
There are several places that need reviewing and updating with any new feature or change added:
36-
37-
- README.md - overview, kept brief; detail belongs in docs/. Shown by `sctx docs`
38-
- AGENTS.md - this file
39-
- docs/* - `sctx docs <topic>` shows concepts.md, config.md, schemas.md (`schema`), rules.md and semantic-rules.md; also architecture.md, api.md
40-
- plugin/* - skills, commands, hooks, and scripts; update any affected parts
41-
42-
"Affected" includes files the change does not touch. Search for old names, then reread each file below for meaning, not only for renamed words:
43-
44-
| Change | Check |
45-
|---|---|
46-
| CLI command, flag or output | `docs/*` for the command; `plugin/skills/structured-context/references/commands.md`; the command list in `plugin/skills/structured-context/SKILL.md`; `plugin/commands/*` |
47-
| Rule, schema or `$metadata` shape | `docs/schemas.md`, `docs/rules.md`, `docs/semantic-rules.md`; `references/schema-authoring.md`, `references/schema-design.md`; bundled `schemas/` |
48-
| Bundled semantic rule | its eval in `evals/semantic/` |
49-
| User-visible error or warning message | the troubleshooting table in `SKILL.md` |
50-
| Config key or space config | `docs/config.md`; the config example in `references/commands.md` |
51-
| `validate --json` output | `plugin/scripts/state.ts` (the hooks parse it), `scripts/mod-contract.ts` and `bun run test:hook` |
52-
| Hook state or `schemas show` output | `plugin/scripts/mod-bridge.ts`, `plugin/types/index.d.ts` and `bun run test:mod` |
53-
| `src/browser.ts`, the space graph format, the types in `scripts/mod-contract.ts`, or the `structured-context-map-views` version | `bun run build:mod-projection` |
54-
| Parsing or node content | `docs/concepts.md`; the embedded nodes section in `SKILL.md` |
55-
| New term | `docs/concepts.md` |
56-
| New module, or a module taking on another's concern | Module Boundaries in `docs/architecture.md`; `tests/module-boundaries.test.ts` |
27+
A change is done when everything it affects is updated, including files it does not touch. See [docs/definition-of-done.md](docs/definition-of-done.md).
5728

5829
## Planning & Design Principles
5930

6031
- **Simplicity first:** Strive for the simplest design that completely solves the problem. Prefer conventions and established filesystem patterns over adding new configuration, programmatic APIs, or abstractions.
6132
- **Explicitly state alternatives:** When planning or making architectural decisions, do not anchor to the first familiar mechanism. Formulate and state at least one alternative approach, weighing trade-offs, complexity, and ergonomic impact.
62-
- **Minimise blast radius:** Protect established boundaries and interfaces. Treat unnecessary ripple effects (such as making synchronous APIs asynchronous or adding dual APIs) as a design smell indicating the approach should be re-evaluated.
33+
- **Architecture first:** Before 1.0, choose the design that keeps the architecture right, even when it changes interfaces across modules. Replace the old way instead of keeping both.
6334
- **Module boundaries:** Each module owns one concern ([docs/architecture.md](docs/architecture.md#module-boundaries)). Pass what you have to the owning module and let it derive what it needs, instead of building its data for it.
6435
- **Public API surface:** Do not add exports to `src/api.ts`, `src/browser.ts` or `src/types.ts` (the `structured-context/api`, `/browser` and `/types` entry points), or add types or hooks to the plugin interface, without the maintainer's explicit agreement on that specific surface. Exporting something to make docs complete, to tidy up, or because a feature has a public-looking class is not a reason. Agreement on a function covers that function only: its option and result types are separate exports, so derive them in the consumer (`Parameters`, `ReturnType`) instead. If a change seems to need a new export, stop and propose it, with the consumer that needs it. Internal modules can change freely.
65-
- **Where a setting lives:** Config says *what* to use, CLI flags override it for one run, and the environment holds secrets and the config location only (`apiKeyEnv` names a secret; `SCTX_CONFIG` locates the config). Do not add env vars that set config values, and never infer a choice (such as a judge provider) from a variable that happens to be set: a key present for another tool must not be spent silently. Config also never switches on costly or outward-facing behaviour (such as semantic judging): each run asks for it, through a flag or an API option.
36+
- **Where a setting lives:** Settings go in config. The environment holds only secrets and the config location. Costly or outward-facing behaviour, such as semantic judging, is opt-in on each run.
6637
- **Reuse types:** Derive a type from the real one (`Pick`, `Partial`) instead of restating its shape. Keep CLI wording (flags, commands) out of library errors and the public API; the CLI adds its own hint. Once a feature has many files, give it a directory. Comments explain why, never restate the code.
6738
- **Failures are visible:** A rule or expression that cannot be evaluated is reported as a violation, never skipped or treated as a pass. Likewise a misconfiguration fails before any work or spend.
6839

@@ -87,16 +58,16 @@ There are several places that need reviewing and updating with any new feature o
8758
- `src/judge/` — semantic rules ([docs/semantic-rules.md](docs/semantic-rules.md)).
8859

8960
## Testing
90-
For most development only the main unit tests need re-running regularly.
91-
- `bun run test` — unit tests (fixtures in `tests/`)
92-
- `bun run test:hook` — unit test plugin hooks (`hook-test/unit/`) - hook development only
93-
- `bun run test:mod` — test the mod (`plugin/hooks/*.test.tsx`, with `claude plugin test`) - mod development only. CI runs it, and `claude plugin validate plugin`
94-
- `bun run test:hook:e2e` — test plugin hooks in Claude Code (`hook-test/`) - hook development only
95-
- `bun run test:smoke` — smoke tests run against locally configured spaces - only use when changes could affect compatibility.
96-
- `bun run test:package` — builds and packs the package, installs the tarball, and runs the installed CLI. Runs in CI and before every version bump; run it after changing the build, `tsconfig*.json` or `files`.
97-
- `bun run test:judge` — live judge tests (`tests/judge/live.test.ts`): one real provider call per provider whose API key is set. Costs money; use sparingly when changing judges or semantic rule behaviour.
98-
- `bun run test:models` — check that every bundled provider's configured model exists (no API keys)
99-
- `bun run eval:semantic --provider <name>` — semantic evals (`evals/`): how often a provider's verdicts match labelled cases. Costs money (`--check` doesn't). Run it when changing a bundled semantic rule, the schema descriptions it draws on, or a judge.
61+
62+
Run `bun run test` during development. Run the others with `bun run` when a change touches their area:
63+
64+
- `test:hook`, `test:hook:e2e` — plugin hooks
65+
- `test:mod` — the mod
66+
- `test:smoke` — compatibility with locally configured spaces
67+
- `test:package` — the build, `tsconfig*.json` or `files`
68+
- `test:judge` — judges; makes live provider calls, which cost money
69+
- `test:models` — the bundled providers' models
70+
- `eval:semantic --provider <name>` — bundled semantic rules, the schema descriptions they use, or a judge; costs money unless run with `--check`
10071

10172
## Debugging
10273

‎docs/architecture.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,18 @@ These rules keep the boundaries:
103103

104104
---
105105

106+
## Claude Code Plugin
107+
108+
The Claude Code plugin in `plugin/` has skills, commands and hooks for working with spaces.
109+
110+
The command hooks in `plugin/hooks/hooks.json` baseline each turn and gate it at Stop. The mod (`plugin/hooks/register.tsx`, a hooks module) adds to them: a line under the answer and a band above the prompt for the turn's new issues, a status line, the schemas of the spaces in the working directory in the system prompt, and `spaces`, `validate` and `schema` tools. It never validates per tool call, because a space can be invalid partway through a multi-file change. A mod has no Node, so it reaches the hooks' state and the CLI through `plugin/scripts/mod-bridge.ts`. `plugin/types/index.d.ts` declares the mod's `$.state`.
111+
112+
The map pane (`plugin/hooks/map-pane.tsx`, `/sctx-map`) draws a space's hierarchy with each node's validation results. A mod can't import packages, so `bun run build:mod-projection` bundles the code it runs from core and `structured-context-map-views` into the committed `plugin/hooks/projection.js`. The same command inlines the core types the mod shares (`scripts/mod-contract.ts`) into `plugin/types/index.d.ts`, which must be self-contained.
113+
114+
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.
115+
116+
---
117+
106118
## Field Remapping
107119

108120
Spaces may use different frontmatter field names than the canonical names expected by the schema (e.g. `record_type` instead of `type`). The `fieldMap` config option handles this transparently:

‎docs/definition-of-done.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
title: "Definition of done"
3+
---
4+
5+
# Definition of done
6+
7+
A change is done when the README, AGENTS.md, docs/ and plugin/ describe what the code now does. The README stays brief; detail belongs in docs/.
8+
9+
"Affected" includes files the change does not touch. Search for old names, then reread each file below for meaning, not only for renamed words:
10+
11+
| Change | Check |
12+
|---|---|
13+
| CLI command, flag or output | `docs/*` for the command; `plugin/skills/structured-context/references/commands.md`; the command list in `plugin/skills/structured-context/SKILL.md`; `plugin/commands/*` |
14+
| Rule, schema or `$metadata` shape | `docs/schemas.md`, `docs/rules.md`, `docs/semantic-rules.md`; `references/schema-authoring.md`, `references/schema-design.md`; bundled `schemas/` |
15+
| Bundled semantic rule | its eval in `evals/semantic/` |
16+
| User-visible error or warning message | the troubleshooting table in `SKILL.md` |
17+
| Config key or space config | `docs/config.md`; the config example in `references/commands.md` |
18+
| `validate --json` output | `plugin/scripts/state.ts` (the hooks parse it), `scripts/mod-contract.ts` and `bun run test:hook` |
19+
| Hook state or `schemas show` output | `plugin/scripts/mod-bridge.ts`, `plugin/types/index.d.ts` and `bun run test:mod` |
20+
| `src/browser.ts`, the space graph format, the types in `scripts/mod-contract.ts`, or the `structured-context-map-views` version | `bun run build:mod-projection` |
21+
| Parsing or node content | `docs/concepts.md`; the embedded nodes section in `SKILL.md` |
22+
| New term | `docs/concepts.md` |
23+
| New module, or a module taking on another's concern | Module Boundaries in `docs/architecture.md`; `tests/module-boundaries.test.ts` |

0 commit comments

Comments
 (0)