mirror of
https://github.com/got-feedBack/feedBack.git
synced 2026-09-12 19:58:31 +00:00
Miguel_LZPFandBret Mogilefsky
e4187d0054
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>
53 lines
2.8 KiB
Markdown
53 lines
2.8 KiB
Markdown
# Contributing to Slopsmith
|
|
|
|
Thanks for wanting to contribute! This document covers the legal and workflow expectations for code, plugins, and documentation contributions.
|
|
|
|
## License
|
|
|
|
Slopsmith is licensed under [AGPL-3.0-only](LICENSE). Contributions you submit (PRs, patches, documentation, plugin entries in the curated list) are licensed inbound under the same terms — **inbound = outbound**. By opening a pull request, you agree that your contribution may be distributed under AGPL-3.0-only as part of Slopsmith.
|
|
|
|
## Developer Certificate of Origin (DCO)
|
|
|
|
We use the [Developer Certificate of Origin](https://developercertificate.org/) (DCO) to track contribution provenance. Every commit must be signed off:
|
|
|
|
```bash
|
|
git commit -s -m "your commit message"
|
|
```
|
|
|
|
This appends a line to your commit message like:
|
|
|
|
```text
|
|
Signed-off-by: Jane Developer <jane@example.com>
|
|
```
|
|
|
|
The sign-off certifies that you wrote the code (or have the right to submit it) and that you're contributing it under AGPL-3.0-only as the LICENSE file describes. The full text of the certification is at [developercertificate.org](https://developercertificate.org/).
|
|
|
|
If you forget to sign off, amend the most recent commit with `git commit --amend -s` (or rebase + sign off older commits) and force-push to your PR branch.
|
|
|
|
## Plugin licensing
|
|
|
|
Plugins live in their own repositories and are loaded at runtime — see [`docs/PLUGIN_AUTHORING.md`](docs/PLUGIN_AUTHORING.md) for the technical contract and [`schema/plugin.schema.json`](schema/plugin.schema.json) for the manifest schema. Plugins are not subject to AGPL by being loaded into Slopsmith (the loader runs them as separate Python modules / browser scripts), but for the **curated plugin list** to accept your plugin we ask that it be released under an AGPL-3.0-compatible license:
|
|
|
|
- AGPL-3.0-only or AGPL-3.0-or-later
|
|
- GPL-3.0-only or GPL-3.0-or-later
|
|
- LGPL-3.0-only or LGPL-3.0-or-later
|
|
- MIT
|
|
- BSD-2-Clause or BSD-3-Clause
|
|
- Apache-2.0
|
|
- ISC
|
|
- Unlicense / CC0-1.0 / 0BSD
|
|
|
|
Plugins under GPL-2.0-only, LGPL-2.1-only, CDDL, EPL, or proprietary terms will not be added to the curated list. You're still free to publish and self-distribute them — Slopsmith will load any plugin a user installs locally — but they won't be promoted from the main project.
|
|
|
|
## Workflow
|
|
|
|
Standard PR workflow described in [AGENTS.md → Git workflow](AGENTS.md#git-workflow):
|
|
- Never push directly to `main`.
|
|
- Create a feature branch on your fork.
|
|
- Open a PR against `got-feedback/feedback:main`.
|
|
- Keep commits scoped and well-described; short imperative subject + `Signed-off-by` trailer.
|
|
|
|
## Questions
|
|
|
|
Open an issue or start a [Discussion](https://github.com/got-feedback/feedback/discussions) if you're unsure whether a contribution fits — much better to ask early than to find out after the work is done.
|