Addresses 12 of 13 review comments from Copilot and CodeRabbit on
PR #332. One comment (no-manifests in validate-plugins.yml) is
declined and answered inline; the rest are applied here.
Substantive fixes:
- .github/workflows/validate-plugins.yml — add --noconftest to the
schema-tests step. tests/conftest.py imports structlog at module
level, but the CI job only installs requirements-test.txt
(pytest/httpx/jsonschema), so pytest collection would fail at
conftest import. The schema tests don't use shared fixtures, so
skipping conftest is safe and avoids dragging the full runtime
requirements into a 2 KB validation job. (Copilot)
- schema/plugin.schema.json — tighten the server_files regex on both
settings.server_files and diagnostics.server_files to match the
runtime _validate_relpath rules in plugins/__init__.py. The
previous regex only blocked absolute paths, drive letters,
backslashes, and "..". The runtime also rejects "//", "./",
"/./", and leading-dotfile segments. Schema-valid manifests are
now also load-time-valid. Verified the regex against 12 cases:
the 3 in-tree manifests still validate. (Copilot)
- .claude/skills/plugin-validate/SKILL.md — add a per-iteration
plugin_ok flag so we no longer print "OK <path>" after an earlier
FAIL in the same manifest. Schema-pass + id-mismatch previously
produced both FAIL and OK lines for one plugin. (CodeRabbit)
- docs/websocket-protocol.md — clarify song_info.tuning array length
is source-dependent (typically 6 guitar, 4 bass, but extended-range
GP imports can be 7/8/5/6). Recommend highway.getStringCount() for
the authoritative count. Line 30 already said this; the table row
on line 12 was the stale half. (CodeRabbit)
Trivial fixes:
- .claude/rules/plugin-author.md — "wants included" -> "wants to
include" in the settings.server_files rule. (CodeRabbit)
- Markdown MD040 — add `text` language tags to 7 bare-fence code
blocks across AGENTS.md, docs/PLUGIN_AUTHORING.md,
docs/testing-plugins.md, docs/plugin-logging.md, .claude/README.md,
.claude/agents/slopsmith-reviewer.md, and
.claude/skills/plugin-validate/SKILL.md (two fences). (CodeRabbit)
Declined:
- .github/workflows/validate-plugins.yml no-manifests -> exit 0
(CodeRabbit suggested exit 1). Plugins in this repo are in-tree,
not submodules (no .gitmodules, git submodule status empty), and
the workflow has a path filter on plugins/**/plugin.json so it
only runs when a manifest actually changes. Exit 0 is correct.
Answered inline on the PR.
Verification:
pytest tests/test_plugin_schema.py -v --noconftest # 8 passed
python -c "import json,glob,jsonschema; s=json.load(open('schema/plugin.schema.json')); [jsonschema.validate(json.load(open(p)), s) for p in sorted(glob.glob('plugins/*/plugin.json'))]"
# ok — all 3 in-tree manifests validate against tightened schema
Signed-off-by: Miguel_LZPF <mgcdreamer@gmail.com>
Adds the contributor- and AI-tool-facing infrastructure on top of the
modular docs from the previous commit. Lands AGENTS.md as the canonical
cross-tool orientation (read natively by Cursor, Copilot, Codex, Aider,
Cline, Continue, Cody, Devin, Replit Agent, and Claude Code), flips
CLAUDE.md to a 22-line pointer that uses Claude Code's @-import to
inline AGENTS.md, wires up plugin.json validation in CI, and adds the
Claude-specific automation surfaces under .claude/.
Cross-tool orientation:
AGENTS.md (178 lines) — single source of truth: architecture, running
the app, testing, git workflow, versioning, song formats, frontend
and backend conventions, plugin authoring index, first-hour
pitfalls, verification, house rules.
CLAUDE.md (22 lines) — Claude Code memory file. Uses @AGENTS.md
import (recursion depth 5) so the canonical content is inlined
without duplication. Lists .claude/ surfaces.
.github/copilot-instructions.md — Copilot custom instructions
format; points at AGENTS.md and docs/PLUGIN_AUTHORING.md.
.cursorrules — not added. Cursor reads AGENTS.md natively in 2026
and .cursorrules is legacy.
Contribution hygiene (.github/):
PULL_REQUEST_TEMPLATE.md — summary, linked issue, test plan, DCO
and conventional-commit reminders. No AI-disclosure section.
ISSUE_TEMPLATE/bug.yml — version, deployment, OS, plugins enabled,
repro, logs (linked to docs/diagnostics-bundle-spec.md for
redaction guidance).
ISSUE_TEMPLATE/feature.yml — problem, proposed, alternatives,
surface, plugin-author impact, license check.
ISSUE_TEMPLATE/config.yml — disables blank issues; redirects
plugin issues to plugin repos and security to the private
advisory flow.
CI:
.github/workflows/validate-plugins.yml — runs on changes to
plugins/*, schema/, CONTRIBUTING.md, the test file, or the
workflow itself. Installs jsonschema and pytest, validates every
plugins/*/plugin.json against schema/plugin.schema.json, and runs
the license-allowlist subset check.
tests/test_plugin_schema.py — 8 parametrized tests: schema is
well-formed, the 3 in-tree manifests validate, manifest id
matches its parent directory name, schema license enum is a
subset of CONTRIBUTING's curated allowlist.
requirements-test.txt — append jsonschema>=4.0.
.github/workflows/sync-version.yml — comment retargeted to
AGENTS.md "Versioning" section.
Claude Code surfaces (.claude/):
README.md — layout explanation. Spec-kit owns skills/speckit-*;
repo-specific skills sit alongside. Hooks off by default;
settings.json carries a commented opt-in example.
skills/plugin-scaffold/SKILL.md — generates a plugin skeleton for
type in {visualization, overlay, settings-only, routes-only}.
skills/plugin-validate/SKILL.md — local pre-push check: validates
plugin.json against schema, asserts declared files exist,
enforces license allowlist.
rules/plugin-author.md — globs scoped to plugins/**. Encodes the
contracts from docs/PLUGIN_AUTHORING.md so AI suggestions don't
drift from them (manifest required, context[\"log\"] over print,
load_sibling over bare imports, playSong await discipline,
settings.server_files conventions).
agents/slopsmith-reviewer.md — plugin-aware reviewer subagent;
invoke with @slopsmith-reviewer. 12-item checklist mirrors the
rule and the schema.
settings.json — empty hooks block plus a commented PostToolUse
example for opt-in plugin.json validation on save.
Inbound-ref updates (files we own):
README.md — \"AI Agent Guide\" points at AGENTS.md and notes
.claude/ and copilot-instructions are tool-specific.
CONTRIBUTING.md — \"Plugin System in CLAUDE.md\" -> docs/ and
schema/; \"Git Workflow\" -> AGENTS.md#git-workflow.
docs/sloppak-spec.md — plugin-system table cell -> docs/.
Out of scope (intentionally untouched):
plugins/highway_3d/README.md (gitlink — plugin owns its docs).
.specify/memory/constitution.md and other spec-kit artefacts
(spec-kit owns that surface; CLAUDE.md still resolves
transitively via the @-import).
Verification:
pytest -q # backend + schema tests pass
python -c \"import json,glob,jsonschema; s=json.load(open('schema/plugin.schema.json')); [jsonschema.validate(json.load(open(p)), s) for p in sorted(glob.glob('plugins/*/plugin.json'))]\"
Signed-off-by: Miguel_LZPF <mgcdreamer@gmail.com>
CLAUDE.md had grown to 545 lines / 50 KB — most of it plugin-author
content that other AI tools (Cursor, Copilot, Codex, Aider) and humans
without AI never reach. Extract the plugin surface into 10 focused
docs and a JSON Schema for plugin.json, then slim CLAUDE.md to a
156-line navigable index.
New docs (~999 lines total, all self-contained):
docs/PLUGIN_AUTHORING.md — entry point and quickstart
docs/plugin-manifest.md — plugin.json field reference
docs/plugin-visualization-contracts.md — setRenderer / overlay / note-state
docs/plugin-audio-mixer.md — fader registration
docs/plugin-logging.md — context["log"] + env vars
docs/plugin-diagnostics.md — server_files / callable
docs/plugin-keyboard-shortcuts.md — registerShortcut + scopes
docs/plugin-sibling-imports.md — load_sibling pattern
docs/websocket-protocol.md — /ws/highway message reference
docs/testing-plugins.md — pytest fixtures + Playwright
schema/plugin.schema.json — Draft 2020-12 schema for
plugin.json; license enum
mirrors CONTRIBUTING's curated
allowlist. Backs CI validation
and the plugin-validate skill.
CLAUDE.md slim (581 lines changed, -485):
- Removed ~300 lines of plugin-author prose (now in docs/).
- Kept architecture quick reference, running the app, testing,
git workflow, versioning, song formats, frontend/backend
conventions, plugin authoring INDEX (table → docs/), first-hour
pitfalls, "For AI agents" footer.
- Anchor stubs preserved next to the new index entries so deep
links from specs/001-slopsmith-platform/analyze.md still resolve.
Verification:
python -c "import json,glob,jsonschema; s=json.load(open('schema/plugin.schema.json')); [jsonschema.validate(json.load(open(p)), s) for p in sorted(glob.glob('plugins/*/plugin.json'))]"
# ok — validates highway_3d, app_tour_library, app_tour_settings
Signed-off-by: Miguel_LZPF <mgcdreamer@gmail.com>
