From 299a075aa6a7354b19d194c085f1c5790dea0a85 Mon Sep 17 00:00:00 2001 From: "pullfrog[bot]" <226033991+pullfrog[bot]@users.noreply.github.com> Date: Sat, 17 Oct 2026 12:33:25 +0000 Subject: [PATCH 1/3] AGENTS.md: remove fork-specific instructions and define single agent completion workflow --- AGENTS.md | 79 +++++++++++++++++++++++++++++++------------------------ 1 file changed, 44 insertions(+), 35 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4116451..df7932c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -51,41 +51,50 @@ thread via `run_in_executor`, streamed to the client over shape — `feedpakr_validate.py` wraps this for the pipeline's own post-build check. -## PR Format - -If this plugin is a fork of a canonical upstream repo, structure PRs to -clarify scope. It isn't one yet — `got-feedBack`'s plugin ecosystem -(whose `feedpak-spec` and `feedBack-plugin-spec` this plugin follows) is -the intended upstream. - -### For PRs targeting this fork: -- **Fork-specific changes** — adapt for local use, integrate with local - infrastructure, or experiment with features not yet upstreamed -- **Candidate changes** — improvements that could eventually go upstream; - mark these clearly so maintainers can cherry-pick or fast-track them - -### For changes intended for the canonical repo: -- **Open the PR upstream first** — ensure alignment with the canonical - project's standards and roadmap -- **Link both PRs** — reference the upstream PR in your fork PR's - description so reviewers see the full context -- **Rebase after merge** — once the upstream PR merges, rebase your fork - onto the canonical main to avoid divergence - -When in doubt, ask: "Would this benefit the broader community, or is it -specific to this deployment?" Upstream changes raise the quality bar for -everyone. +## Repository & PR target + +This is the canonical `get-flashbacks/feedBack-plugin-feedpakr` repository. All changes should be opened as PRs against `get-flashbacks/feedBack-plugin-feedpakr` (default branch `main`). It is not a fork of another repo — `got-feedBack`'s plugin ecosystem (`feedpak-spec` and `feedBack-plugin-spec`) provides the specifications this plugin follows. Refer to those specs for normative requirements; host implementation details are noted where they differ. + +## Agent completion workflow + +Follow this single completion workflow for all agent tasks: + +1. **Understand the task**: Read the task requirements and related context (issue, PR, or instructions). Check AGENTS.md for repo-specific guidance. +2. **Plan**: Identify affected files, key changes, and verification steps. Create a concise todo list if the work spans multiple steps. +3. **Implement**: Make minimal, focused changes that follow existing code style, naming, and patterns. Use `context['load_sibling']` for cross-module imports, `context['log']` for logging, and respect the plugin's architecture (blocking work in plain `def` handlers). +4. **Test**: Run the test suite with `pytest` to catch regressions. Verify changes against the relevant specs when touching manifest shape or validation logic. +5. **Lint/format**: Follow repo conventions; no separate lint command is mandated beyond what tests/checks expect (see learnings). Ensure code matches surrounding style. +6. **Verify**: Confirm the implementation meets acceptance criteria from the task/issue. Run any targeted checks relevant to your changes. +7. **Finalize**: Ensure working tree is clean, summarize changes, and follow the run's reporting requirements. If the task involves creating a PR, ensure it targets `get-flashbacks/feedBack-plugin-feedpakr` (default `main`). + +## Reproducible setup + +- **Dependencies**: `pip install -r requirements.txt -r requirements-test.txt`. Host libraries (`pyguitarpro`, `PyYAML`) ship with the feedBack host in deployment; for local testing, ensure they are available. Tests that require ffmpeg will self-skip if `ffmpeg` isn't on PATH (imageio-ffmpeg can provide it). +- **Test command**: `pytest` (from repo root). Host-gated tests may skip if host `lib/` or required deps aren't present; see learnings for running with host lib on `PYTHONPATH`. +- **Specs**: `feedpak-spec/` and `feedBack-plugin-spec/` provide normative requirements referenced in this guide. + +## Verification + +- **Tests**: Always run `pytest` after making changes. Pay attention to skip counts — a green exit with all skips means environment lacks fixtures/host deps. +- **Validation**: When modifying manifest assembly or validation, verify against `feedpak-spec/tools/validate.py` or vendored schemas via `feedpakr_validate.py`. +- **Behavior**: For complex changes (sync/warp, audio, GP parsing), add/adjust tests or do targeted manual checks against existing fixtures. + +## Optional integrations + +- **Chordr**: Optional chord naming during import; failures degrade gracefully and emit warnings. +- **FFmpeg**: Required only for certain audio operations; tests gated behind availability and self-skip when missing. ## Versioning -Bump `version` in `plugin.json` whenever a change is user-visible — new -import capability, a fixed bug that affected real output, a changed UI -flow (best-practices rule 4: bump on every release — the version is used -for cache-busting the served JS/CSS URL, so an unbumped version means -users keep getting stale cached files after an update). It was left at -`0.1.0` from the very first commit through 9 subsequent commits (four -full feature phases) before anyone noticed — don't let it go stale -again. Patch (`0.1.x`) for fixes, -minor (`0.x.0`) for new features, matching normal semver-during-0.x -conventions. This is independent of `feedpak_version` (the *format* -version) — don't conflate the two. \ No newline at end of file +Bump `version` in `plugin.json` whenever a change is user-visible — new import capability, a fixed bug that affected real output, a changed UI flow. Patch (`0.x.y` with `0.x` series) for fixes, minor (`0.x.0`) for new features, matching semver during 0.x. This is independent of `feedpak_version` (the *format* version) — don't conflate the two. + +## Changelog policy + +Document notable changes in `CHANGELOG.md` following [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Include user-visible changes under appropriate sections (Added/Changed/Fixed/Removed/Security). Link or reference issues/PRs as appropriate. + +## Completion criteria + +- All tests pass (or expected skips are documented and justified) +- Changes meet acceptance criteria in the task/issue +- Code follows existing conventions and plugin/feedpak specs +- Working tree is clean; changes are minimal and focused \ No newline at end of file From 3061c859c9b7869556153e4b70a147ccf8d4887e Mon Sep 17 00:00:00 2001 From: "pullfrog[bot]" <226033991+pullfrog[bot]@users.noreply.github.com> Date: Sat, 17 Oct 2026 12:40:39 +0000 Subject: [PATCH 2/3] Align AGENTS.md setup/verification/policy guidance with actual CI Address review feedback on the canonical-repo guidance: - Reproducible setup now covers the host deps (PyYAML/pyguitarpro) whose absence aborts pytest collection, and the required `FEEDPAKR_REQUIRE=host,ffmpeg` test command linked to tests/SKIPS.md - Specs bullet links the upstream got-feedBack repos and distinguishes the vendored assets/schemas - Version and changelog policies now require a bump/entry for every functional source change (matching the live CI gates) - FFmpeg integration notes it is required in CI, not just optional - Workflow step 1 links CLAUDE.md/README.md architecture notes; step 7 and completion criteria keep requested edits instead of reverting them - Drop the fork/upstream "Repository Relevance" section from the PR template --- .github/PULL_REQUEST_TEMPLATE.md | 7 ------- AGENTS.md | 18 +++++++++--------- 2 files changed, 9 insertions(+), 16 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 5cb7c58..1a02ec0 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -10,13 +10,6 @@ Brief description of the changes in this PR. ## Testing Describe how you tested these changes. -## Repository Relevance -- [ ] This change is relevant for the **core repository** (get-flashbacks/feedBack-plugin-feedpakr) -- [ ] This change is relevant for **this fork only** -- [ ] This change is relevant for **both** core and fork - -Please indicate whether this PR should be upstreamed to the core repository or if it's specific to this fork's use case. - ## Checklist - [ ] My code follows the style guidelines of this project - [ ] I have performed a self-review of my own code diff --git a/AGENTS.md b/AGENTS.md index df7932c..54c6059 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -59,19 +59,19 @@ This is the canonical `get-flashbacks/feedBack-plugin-feedpakr` repository. All Follow this single completion workflow for all agent tasks: -1. **Understand the task**: Read the task requirements and related context (issue, PR, or instructions). Check AGENTS.md for repo-specific guidance. +1. **Understand the task**: Read the task requirements and related context (issue, PR, or instructions). Check AGENTS.md for repo-specific guidance; for detailed architecture notes (audio/chart sync, Chordr, dedupe) consult `CLAUDE.md`, and for test/setup detail see `README.md`. 2. **Plan**: Identify affected files, key changes, and verification steps. Create a concise todo list if the work spans multiple steps. 3. **Implement**: Make minimal, focused changes that follow existing code style, naming, and patterns. Use `context['load_sibling']` for cross-module imports, `context['log']` for logging, and respect the plugin's architecture (blocking work in plain `def` handlers). 4. **Test**: Run the test suite with `pytest` to catch regressions. Verify changes against the relevant specs when touching manifest shape or validation logic. 5. **Lint/format**: Follow repo conventions; no separate lint command is mandated beyond what tests/checks expect (see learnings). Ensure code matches surrounding style. 6. **Verify**: Confirm the implementation meets acceptance criteria from the task/issue. Run any targeted checks relevant to your changes. -7. **Finalize**: Ensure working tree is clean, summarize changes, and follow the run's reporting requirements. If the task involves creating a PR, ensure it targets `get-flashbacks/feedBack-plugin-feedpakr` (default `main`). +7. **Finalize**: Remove stray artifacts (test/tooling output) so only the task's intended changes remain, then commit and push those edits as your harness requires — never revert a requested change to satisfy a clean-tree check. Summarize changes and follow the run's reporting requirements. If the task involves creating a PR, ensure it targets `get-flashbacks/feedBack-plugin-feedpakr` (default `main`). ## Reproducible setup -- **Dependencies**: `pip install -r requirements.txt -r requirements-test.txt`. Host libraries (`pyguitarpro`, `PyYAML`) ship with the feedBack host in deployment; for local testing, ensure they are available. Tests that require ffmpeg will self-skip if `ffmpeg` isn't on PATH (imageio-ffmpeg can provide it). -- **Test command**: `pytest` (from repo root). Host-gated tests may skip if host `lib/` or required deps aren't present; see learnings for running with host lib on `PYTHONPATH`. -- **Specs**: `feedpak-spec/` and `feedBack-plugin-spec/` provide normative requirements referenced in this guide. +- **Dependencies**: `pip install -r requirements.txt -r requirements-test.txt` covers this plugin's own deps, but the host libraries (`pyguitarpro`, `PyYAML`) are deliberately not declared there. `tests/conftest.py` imports `feedpakr_pipeline` → `feedpakr_pack`, whose module-scope `import yaml` aborts collection without `PyYAML`, so install them (`pip install pyguitarpro PyYAML`) or add the host's requirements (`-r ../pakr/feedBack/requirements.txt`, which needs a sibling host checkout). See `README.md`'s Tests section. +- **Test command**: `FEEDPAKR_REQUIRE=host,ffmpeg python -m pytest` from repo root, with the host `lib/` on `sys.path` (a sibling `pakr/feedBack` checkout or `PYTHONPATH`) and `ffmpeg` on `PATH` (imageio-ffmpeg can supply a binary locally). A bare `pytest` leaves `FEEDPAKR_REQUIRE` unset, so host/ffmpeg regression tests silently self-skip and the exit code proves nothing — setting the requirement turns those skips into a failure. See [`tests/SKIPS.md`](tests/SKIPS.md) for the skip policy. +- **Specs**: the normative specs are the upstream `got-feedBack` repos [`feedpak-spec`](https://github.com/got-feedBack/feedpak-spec) and [`feedBack-plugin-spec`](https://github.com/got-feedBack/feedBack-plugin-spec); neither is vendored here. This repo ships only the `assets/schemas/*.json` schemas derived from `feedpak-spec`, so consult the upstream repos for the full normative text — local-looking paths below such as `feedpak-spec/tools/validate.py` denote files within those upstream repos, not a checkout here. ## Verification @@ -82,19 +82,19 @@ Follow this single completion workflow for all agent tasks: ## Optional integrations - **Chordr**: Optional chord naming during import; failures degrade gracefully and emit warnings. -- **FFmpeg**: Required only for certain audio operations; tests gated behind availability and self-skip when missing. +- **FFmpeg**: Required by certain audio operations. Its tests self-skip locally when `ffmpeg` isn't on `PATH`, but CI treats it as required (`FEEDPAKR_REQUIRE=host,ffmpeg`) and aborts the session if it's missing, so a broken provisioning step fails loudly instead of hiding behind skips. ## Versioning -Bump `version` in `plugin.json` whenever a change is user-visible — new import capability, a fixed bug that affected real output, a changed UI flow. Patch (`0.x.y` with `0.x` series) for fixes, minor (`0.x.0`) for new features, matching semver during 0.x. This is independent of `feedpak_version` (the *format* version) — don't conflate the two. +Bump `version` in `plugin.json` for **every** functional source change — any `.py`/`.js`/`.html`/`.css` file or schema JSON. CI's `version-bumped-on-change` check enforces this on every PR and fails when the version is unchanged from the base branch, so "not user-visible" is not an exemption (the version also cache-busts the served JS/CSS URL, so an unbumped release serves stale files). Docs, tests, fixtures, `.github/`, and a version-only bump are exempt. Patch (`0.x.y` with `0.x` series) for fixes, minor (`0.x.0`) for new features, matching semver during 0.x. This is independent of `feedpak_version` (the *format* version) — don't conflate the two. ## Changelog policy -Document notable changes in `CHANGELOG.md` following [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Include user-visible changes under appropriate sections (Added/Changed/Fixed/Removed/Security). Link or reference issues/PRs as appropriate. +Record every functional source change in `CHANGELOG.md` following [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) — CI's `changelog-updated` check requires a `CHANGELOG.md` diff on any PR that changes a functional path (the same set as the version bump), so "notable" is not a judgment call. Add entries under Added/Changed/Fixed/Removed/Security and link or reference issues/PRs as appropriate. ## Completion criteria - All tests pass (or expected skips are documented and justified) - Changes meet acceptance criteria in the task/issue - Code follows existing conventions and plugin/feedpak specs -- Working tree is clean; changes are minimal and focused \ No newline at end of file +- Working tree contains only the task's intended changes (stray test/tooling artifacts removed); requested edits are committed/pushed, never reverted \ No newline at end of file From b1d9d3926d6641f4dc6927a72d66fdce32db6a4c Mon Sep 17 00:00:00 2001 From: "pullfrog[bot]" <226033991+pullfrog[bot]@users.noreply.github.com> Date: Sat, 17 Oct 2026 12:53:09 +0000 Subject: [PATCH 3/3] docs: reconcile CLAUDE.md versioning policy with AGENTS.md --- CLAUDE.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 28eaac2..f229d92 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -265,14 +265,14 @@ re-selected. ## Versioning -Bump `version` in `plugin.json` whenever a change is user-visible — new -import capability, a fixed bug that affected real output, a changed UI -flow (best-practices rule 4: bump on every release — the version is used -for cache-busting the served JS/CSS URL, so an unbumped version means -users keep getting stale cached files after an update). It was left at -`0.1.0` from the very first commit through 9 subsequent commits (four -full feature phases) before anyone noticed — don't let it go stale -again. Patch (`0.1.x`) for fixes, -minor (`0.x.0`) for new features, matching normal semver-during-0.x -conventions. This is independent of `feedpak_version` (the *format* -version) — don't conflate the two. +Bump `version` in `plugin.json` for every functional source change (any +`.py`/`.js`/`.html`/`.css` file or schema JSON), matching the CI +`version-bumped-on-change` gate — docs, tests, fixtures, `.github/`, and +a version-only bump are exempt. The version also cache-busts the served +JS/CSS URL, so an unbumped version means users keep getting stale cached +files after an update (it was left at `0.1.0` from the very first commit +through 9 subsequent commits — four full feature phases — before anyone +noticed, so don't let it go stale again). Patch (`0.x.y` with `0.x` +series) for fixes, minor (`0.x.0`) for new features, matching normal +semver-during-0.x conventions. This is independent of `feedpak_version` +(the *format* version) — don't conflate the two.