feat: add cross-tool orientation, CI schema validation, and Claude Code surfaces

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>

tests/test_plugin_schema.py

@@ -0,0 +1,111 @@
+"""Plugin manifest schema sanity tests.
+
+Three independent guarantees:
+
+1. `schema/plugin.schema.json` is itself a well-formed JSON Schema
+   (Draft 2020-12) and accepts every in-tree `plugins/*/plugin.json`.
+2. Each in-tree manifest's `id` matches its parent directory name —
+   the loader assumes this and silent drift would break plugin
+   discovery.
+3. The `license` enum in the schema is a subset of the SPDX identifiers
+   listed in `CONTRIBUTING.md`'s "Plugin licensing" curated allowlist.
+   If you edit the allowlist in `CONTRIBUTING.md`, run pytest locally
+   and update the schema enum to match — these two files must stay in
+   sync because the same allowlist is referenced from both human-facing
+   docs and from CI manifest validation.
+"""
+
+from __future__ import annotations
+
+import glob
+import json
+import re
+from pathlib import Path
+
+import jsonschema
+import pytest
+
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SCHEMA_PATH = REPO_ROOT / "schema" / "plugin.schema.json"
+CONTRIBUTING_PATH = REPO_ROOT / "CONTRIBUTING.md"
+PLUGINS_GLOB = str(REPO_ROOT / "plugins" / "*" / "plugin.json")
+
+
+@pytest.fixture(scope="module")
+def schema() -> dict:
+    with SCHEMA_PATH.open() as f:
+        return json.load(f)
+
+
+def test_schema_is_well_formed(schema: dict) -> None:
+    """The schema file must itself validate as a Draft 2020-12 schema."""
+    jsonschema.Draft202012Validator.check_schema(schema)
+
+
+@pytest.mark.parametrize("manifest_path", sorted(glob.glob(PLUGINS_GLOB)))
+def test_in_tree_manifest_validates(manifest_path: str, schema: dict) -> None:
+    """Every plugin.json under plugins/ must pass schema validation."""
+    with open(manifest_path) as f:
+        manifest = json.load(f)
+    jsonschema.validate(manifest, schema)
+
+
+@pytest.mark.parametrize("manifest_path", sorted(glob.glob(PLUGINS_GLOB)))
+def test_in_tree_manifest_id_matches_directory(manifest_path: str) -> None:
+    """The `id` field must match the parent directory name."""
+    with open(manifest_path) as f:
+        manifest = json.load(f)
+    expected = Path(manifest_path).parent.name
+    assert manifest["id"] == expected, (
+        f"Plugin id {manifest['id']!r} in {manifest_path} does not match "
+        f"directory name {expected!r}. The loader keys plugin lookup by "
+        f"directory; drift would silently break discovery."
+    )
+
+
+def _extract_allowlist_from_contributing() -> set[str]:
+    """Pull the curated-license allowlist out of CONTRIBUTING.md.
+
+    Looks at the "Plugin licensing" section: any bullet line whose text
+    starts with a recognized SPDX-shape identifier is considered part of
+    the allowlist. Forms like "AGPL-3.0-only or AGPL-3.0-or-later" are
+    split on " or ".
+    """
+    text = CONTRIBUTING_PATH.read_text(encoding="utf-8")
+    section = text.split("## Plugin licensing", 1)
+    if len(section) < 2:
+        pytest.fail("'## Plugin licensing' section not found in CONTRIBUTING.md")
+    body = section[1].split("\n## ", 1)[0]
+
+    spdx_re = re.compile(r"^[A-Za-z0-9.+-]+$")
+    allowlist: set[str] = set()
+    for line in body.splitlines():
+        if not line.lstrip().startswith("- "):
+            continue
+        rest = line.lstrip()[2:].strip()
+        # Strip trailing punctuation / parenthetical notes.
+        rest = re.split(r"\s*\(|\s*—|\s*--", rest)[0].strip().rstrip(".,;")
+        for token in re.split(r"\s+or\s+|\s*/\s+|\s*,\s+", rest):
+            token = token.strip().rstrip(".,;").strip()
+            if token and spdx_re.match(token):
+                allowlist.add(token)
+    return allowlist
+
+
+def test_schema_license_enum_subset_of_contributing_allowlist(schema: dict) -> None:
+    """Schema's license enum must be ⊆ CONTRIBUTING.md curated allowlist.
+
+    If you add a license to the schema enum, also list it in
+    CONTRIBUTING.md "Plugin licensing". Direction matters: schema ⊆
+    allowlist (the schema can be stricter than what CONTRIBUTING.md
+    documents — typically the schema *equals* the allowlist).
+    """
+    license_enum = set(schema["properties"]["license"]["enum"])
+    allowlist = _extract_allowlist_from_contributing()
+    missing = license_enum - allowlist
+    assert not missing, (
+        f"License enum values present in schema/plugin.schema.json but "
+        f"not listed in CONTRIBUTING.md 'Plugin licensing' section: {sorted(missing)}. "
+        f"Update CONTRIBUTING.md or remove from the schema enum."
+    )