Ship a Claude Code plugin

[mindsocket]

Overview

Ship structured-content as a Claude Code plugin — a structured, installable package that enables AI-assisted authoring and validation workflows for spaces.

Claude Code plugins can include:

• Skills — reusable agent skills (we already ship one in skills/structured-context/)
• Rules — project-level guidance for Claude on how to work with spaces
• Commands — slash commands that users can invoke directly in Claude Code
• Hooks — shell commands that fire on Claude Code events (e.g. before/after file edits)

Core idea: file-level validation via hooks

The most compelling use case is automatic validation on file save. If we add a validate-file command that accepts a path and resolves the space it belongs to, we can wire it into Claude Code's PostToolUse hook (fires after Write, Edit, MultiEdit) to:

1. Detect if the edited file belongs to a known space
2. Run validation against that file (and any nodes it references)
3. Surface errors back to the agent so it can self-correct

This closes a tight feedback loop: the agent edits → hook validates → errors flow back → agent fixes, without the user needing to manually run sctx validate.

A PreToolUse hook (fires before Write, Edit, MultiEdit) provides a baseline: the agent sees which errors already existed before its edit. This prevents it from trying to fix pre-existing issues that aren't its responsibility — it should only be accountable for errors it introduced.

Scoped validation (analogous to lint-on-changed-files)

Full space validation after every edit is expensive and noisy. The hook use case calls for scoped validation — running only against the file(s) touched by an edit, similar to how linters run over changed files only in a coding workflow.

This raises design questions to work through:

• A single edited .md file may be one node, but validation errors can involve related nodes (e.g. a broken wikilink affects the referencing file, not the target). What's the right scope?
• The pre-edit baseline needs to use the same scope as the post-edit check so the diff is meaningful.
• Consider: validate-file <path> validates the file plus any nodes that reference it or that it references (1-hop neighbourhood), rather than the full space.

Ideas to capture (to be broken down)

• validate-file <path> CLI command — resolves space from path, validates single file, machine-readable output
• Scoped validation design — define what "nodes affected by an edit" means for pre/post hook diffing
• PostToolUse hook config (Write/Edit/MultiEdit) wired to validate-file
• PreToolUse hook — capture baseline errors before edit so the agent only addresses issues it introduced
• Plugin manifest / installable package structure
• Bundled permissions (e.g. allow bunx structured-content) so consumer repos don't configure manually
• Bundled rules (e.g. "always check schemas before authoring content")
• Bundled commands (e.g. /validate, /dump-node)
• Existing skills/structured-context/ skill folded into plugin as canonical source

References

• Claude Code hooks docs
• Claude Code plugins ship as npm packages with a claude entry in package.json

[mindsocket]

Initial plugin created in #81

[mindsocket]

Initial plugin done. Separate issues to be created for future needs