mirror of https://github.com/got-feedBack/feedBack.git synced 2026-09-13 05:08:31 +00:00

Files

T

Miguel_LZPFandBret Mogilefsky e4187d0054 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>

2026-06-18 00:38:51 -07:00

4.4 KiB

Raw Blame History

name, description, globs

name

description

globs

plugin-author

Rules that apply when editing files under plugins/**. Enforces the plugin contracts documented in docs/PLUGIN_AUTHORING.md.

plugins/**

Plugin authoring rules

These rules apply only when editing files under plugins/**. They encode the contracts described in docs/PLUGIN_AUTHORING.md so AI suggestions don't drift from them.

Manifest

plugin.json is required and must validate against schema/plugin.schema.json. Required fields: id, name. The id must match the parent directory name (the loader keys discovery by directory; drift breaks plugin lookup).
License must come from the curated allowlist if the plugin is intended for the curated list. See CONTRIBUTING.md "Plugin licensing".
type: "visualization" requires a script field exporting window.slopsmithViz_<id>. See docs/plugin-visualization-contracts.md.

Backend (`routes.py`)

Use context["log"], never print() or traceback.print_exc(). The CI workflow blocks print( and traceback.print_exc( in server.py / lib/; plugin code should follow the same rule. The provided logger is a stdlib logging.Logger namespaced to slopsmith.plugin.<id> with correlation IDs, JSON mode, and rotation already wired. See docs/plugin-logging.md.
Multi-file plugins must use context["load_sibling"]("<module>"), not bare from <module> import X. Two plugins shipping a same-named helper collide via sys.modules. See docs/plugin-sibling-imports.md.
setup(app, context) is the required entry. Don't run side effects at import time.

Frontend (`screen.js`)

Wrap in an IIFE — (function () { 'use strict'; ... })();. Frontend scripts share global scope; leaking variables collides with other plugins.
Hook window.playSong carefully — always call the original, always await it. Wrappers run outermost-first; awaiting yields to the event loop and WebSocket messages can arrive before the outer wrapper finishes setup. Use highway.getSongInfo() as a fallback rather than relying solely on _onReady.
Hook window.showScreen — clean up your plugin's state when the user leaves the player screen.
Use window.slopsmith.emit / on for cross-plugin communication. Don't poll other plugins' globals.
Register shortcuts with window.registerShortcut({ key, scope, handler }) and clean up with window.unregisterShortcut(key, scope) — pass the same scope you registered with (default 'global' won't match 'player' / 'plugin-*'). For panel-scoped registries, prefer panel.clearShortcuts(). See docs/plugin-keyboard-shortcuts.md.

State and config

localStorage keys must be prefixed with the plugin id to avoid collisions.
settings.server_files declares config-dir paths the plugin wants included in the Settings export/import flow. Relpaths only — no .., no abs paths, no backslashes. See docs/plugin-manifest.md.
diagnostics.server_files / diagnostics.callable declares what enters the Export Diagnostics bundle. Keep payloads under 100 KB and don't include secrets. See docs/plugin-diagnostics.md.

Visualization specifics

When plugin.json declares "type": "visualization":

Factory must be window.slopsmithViz_<id> where <id> matches plugin.json.
Factory must return a fresh object on each call — splitscreen creates N instances.
The renderer owns its getContext() call. Declare contextType: '2d' or 'webgl2' on the returned object so the highway can swap the canvas element when needed (getContext is one-shot per canvas).
draw(bundle) receives difficulty-filtered arrays — never read from _filteredNotes or other internals.

See docs/plugin-visualization-contracts.md for the full lifecycle and the Overlay + Note-state-provider contracts.

Testing

When changing plugin internals, add or update a test under tests/ (Python) or tests/js/ (Node) or tests/browser/ (Playwright). See docs/testing-plugins.md for fixtures (isolate_logging, reset_plugin_state).

4.4 KiB Raw Blame History