sudacode/SubMiner
1
0
Fork 0
mirror of https://github.com/ksyasuda/SubMiner.git synced 2026-03-20 03:16:46 -07:00
Code Issues Packages Projects Releases Wiki Activity

Document AUR install flow and add backlog planning artifacts

Browse Source 
- Add Arch Linux `subminer-bin` install instructions to README and docs-site installation guide
- Add Hyprland troubleshooting guidance for transparency and global shortcut passthrough
- Add TASK-159..164 backlog records and skill design plans; include changelog fragment
- Apply formatting-only update to `src/release-workflow.test.ts`
This commit is contained in:
Kyle Yasuda
2026-03-11 02:08:59 -07:00
parent 9c7e02cbf0
commit 2f17859b7b
13 changed files with 660 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
README.md
View File

@@ -35,6 +35,22 @@ SubMiner is an Electron overlay that sits on top of mpv. It turns your video pla
### 1. Install ### 1. Install
**Arch Linux (AUR):**
Install [`subminer-bin`](https://aur.archlinux.org/packages/subminer-bin) from the AUR. It installs the packaged AppImage plus the `subminer` wrapper:
```bash
paru -S subminer-bin
```
Or manually:
```bash
git clone https://aur.archlinux.org/subminer-bin.git
cd subminer-bin
makepkg -si
```
**Linux (AppImage):** **Linux (AppImage):**
```bash ```bash

58
backlog/tasks/task-159 - Create-SubMiner-automated-testing-skill-for-agents.md Normal file
View File

@@ -0,0 +1,58 @@
---
id: TASK-159
title: Create SubMiner automated testing skill for agents
status: Done
assignee:
- codex
created_date: '2026-03-11 05:55'
updated_date: '2026-03-11 06:13'
labels:
- tooling
- testing
- skills
dependencies: []
priority: medium
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Design and implement a SubMiner-specific skill that agents can use to verify code changes with automated checks across launcher, mpv, overlay, and related workflows.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Define the skill trigger surface and intended use cases for SubMiner change verification.
- [x] #2 Implement a SubMiner-specific skill package with concise workflow guidance and any required helper scripts or references.
- [x] #3 Document how agents should run automated verification for common SubMiner change types, including launcher/mpv/overlay-sensitive changes.
- [x] #4 Verify the skill itself is usable in this repo context.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add a design doc at `docs/plans/2026-03-10-subminer-change-verification-design.md` capturing the approved skill contract, lane selection rules, helper script design, and trigger/workflow guidance.
2. Create an in-repo source package for the new SubMiner-specific verification skill with `SKILL.md` plus helper shell scripts for diff classification and coordinated verification/artifact capture.
3. Implement cheap-first verification logic: map changed paths to verification lanes, run repo-native commands, capture stdout/stderr and metadata under `.tmp/skill-verification/<timestamp>/`, and report pass/fail/skipped states with artifact paths.
4. Encode repo-specific heuristics for docs/config, launcher/plugin, runtime/dist, and optional real-GUI escalation guidance without making GUI launch the default.
5. Verify the skill locally by running the classifier/verifier against representative paths and confirming artifact generation and summaries.
6. Optionally install the finished skill to `~/.codex/skills/subminer-change-verification/` after user approval because that target is outside the writable sandbox.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Planned outputs: SKILL.md plus small helper shell scripts for diff classification and coordinated verification/artifact capture. Default to repo-native commands; only escalate to real GUI/mpv verification when affected paths or requested behavior require it.
2026-03-10: Brainstorming completed with user approval for a SubMiner-specific automated verification skill. Chosen shape: auto-triggering, cheap-first verification workflow with optional real GUI/mpv escalation and artifact capture.
2026-03-10: Added design doc at docs/plans/2026-03-10-subminer-change-verification-design.md and created the in-repo skill source at tools/skills/subminer-change-verification/.
2026-03-10: Verified classifier output with representative launcher/runtime/config/docs paths and ran the verifier in dry-run mode plus one real config lane (`bun run test:config`). Artifacts written under .tmp/skill-verification/20260310-231320 and .tmp/skill-verification/20260310-231326.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Implemented a SubMiner-specific change verification skill source with a concise SKILL.md, a diff classifier, and a cheap-first verifier that captures artifacts under `.tmp/skill-verification/`. Verified the flow with representative path classification, a dry-run multi-lane plan, and a passing real config verification run.
<!-- SECTION:FINAL_SUMMARY:END -->

57
backlog/tasks/task-160 - Create-repo-local-scrum-master-orchestration-skill.md Normal file
View File

@@ -0,0 +1,57 @@
---
id: TASK-160
title: Create repo-local scrum master orchestration skill
status: Done
assignee:
- codex
created_date: '2026-03-11 06:32'
updated_date: '2026-03-11 06:45'
labels:
- skills
- workflow
- backlog
- subagents
- automation
dependencies: []
priority: high
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Design and implement a repo-local skill that can turn incoming requests/issues into well-scoped Backlog tasks, then coordinate one or more subagents to implement and verify the resulting work using the repo's established skills and verification workflow.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Define the trigger surface, responsibilities, and limits of the scrum master skill for request intake, backlog updates, and execution orchestration.
- [x] #2 Implement the skill package with concise guidance for intake, task search/create/update, planning, and subagent dispatch.
- [x] #3 Specify how the skill coordinates with existing repo workflows, including Backlog.md requirements and SubMiner change verification.
- [x] #4 Verify the skill is usable in this repo context for at least one representative request flow.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add a design doc at `docs/plans/2026-03-10-subminer-scrum-master-design.md` capturing the approved contract, backlog decision rules, orchestration policy, and verification handoff.
2. Create the repo-local skill at `.agents/skills/subminer-scrum-master/` with a concise `SKILL.md`.
3. Keep v1 instruction-heavy: backlog-or-not decision first, search/create/update task structure when needed, require planning before dispatch, use parent + subtasks for multi-part work, dispatch conservatively with explicit ownership, and require `subminer-change-verification` before handoff.
4. Include representative flows for trivial no-ticket work, single-task implementation, and multi-part parent+subtask execution.
5. Verify the skill in-repo with one representative request flow and update `TASK-160` with results.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
V1 will be instruction-heavy rather than script-heavy. The skill will decide whether backlog is warranted, record plans before dispatch, create parent+subtasks when needed, dispatch conservatively with explicit ownership, and require `subminer-change-verification` before handoff.
2026-03-10: Added design doc at docs/plans/2026-03-10-subminer-scrum-master-design.md and created the repo-local skill at .agents/skills/subminer-scrum-master/.
2026-03-10: Verified the skill against a representative request flow ('Fix launcher auto-start pause bug and make sure it is verified') by checking that the instructions cover backlog decisioning, planning-before-dispatch, single-task execution, explicit worker ownership, and verification via subminer-change-verification.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Implemented a repo-local `subminer-scrum-master` skill that assesses whether backlog tracking is needed, manages task structure and planning when appropriate, dispatches subagents conservatively, and requires verification before handoff. Verified the skill in-repo against a representative launcher bug workflow.
<!-- SECTION:FINAL_SUMMARY:END -->

68
backlog/tasks/task-161 - Add-Arch-Linux-PKGBUILD-and-.SRCINFO-for-SubMiner-release-artifacts.md Normal file
View File

@@ -0,0 +1,68 @@
---
id: TASK-161
title: Add Arch Linux PKGBUILD and .SRCINFO for SubMiner release artifacts
status: Done
assignee:
- codex
created_date: '2026-03-11 07:50'
updated_date: '2026-03-11 07:56'
labels:
- packaging
- linux
- docs
dependencies: []
references:
- package.json
- .github/workflows/release.yml
- README.md
documentation:
- docs-site/development.md
- docs-site/installation.md
- docs/RELEASING.md
priority: medium
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Add repo-maintained Arch packaging metadata so Arch/AUR users can install the packaged SubMiner release artifacts without relying on npm. Cover the binary package flow that matches the current GitHub Releases distribution model and document the install path for Arch users.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 A dedicated Arch packaging directory exists with a PKGBUILD and matching .SRCINFO for the SubMiner binary release flow.
- [x] #2 The package installs the shipped Linux release artifact and wrapper in paths consistent with current runtime auto-detection expectations.
- [x] #3 Package metadata declares the required Arch runtime dependencies for the packaged workflow.
- [x] #4 The packaging files remain isolated from the main app/release/docs surfaces so they can be moved to a separate repository later.
- [x] #5 The packaging metadata is validated with an appropriate local Arch packaging check or an explicitly documented limitation if the tool is unavailable in this environment.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add isolated Arch packaging under packaging/arch/subminer-bin for the binary release flow that matches current GitHub Releases artifacts.
2. Install the Linux AppImage to /opt/SubMiner/SubMiner.AppImage, add PATH symlinks for SubMiner.AppImage and subminer, and ship optional plugin/theme/config assets under /usr/share/subminer.
3. Generate and commit matching .SRCINFO metadata in the same packaging directory.
4. Validate the PKGBUILD metadata locally with shell parsing plus makepkg --printsrcinfo and namcap if available.
5. Leave the new files isolated so they can be moved to a separate packaging repository later.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
User requested no commit and no broad repo integration; keep the Arch packaging files isolated in a dedicated directory for later extraction.
Created isolated Arch packaging under packaging/arch/subminer-bin with PKGBUILD and generated .SRCINFO only; no docs or release workflow changes.
Validation run: bash -n PKGBUILD, makepkg --printsrcinfo > .SRCINFO, namcap PKGBUILD.
PKGBUILD uses current v0.5.6 GitHub release assets and recorded SHA-256 values for SubMiner-0.5.6.AppImage, subminer, and subminer-assets.tar.gz.
Per user follow-up, moved packaging/arch/subminer-bin out of the repo to /home/sudacode/packages/maintaining/subminer-bin for separate maintenance. Repo docs/workflows were still left untouched.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Added an isolated Arch Linux packaging directory at packaging/arch/subminer-bin containing a `subminer-bin` PKGBUILD and generated `.SRCINFO`. The package installs the current GitHub release AppImage to `/opt/SubMiner/SubMiner.AppImage`, adds PATH access for `SubMiner.AppImage` and `subminer`, and ships optional plugin/theme/config assets under `/usr/share/subminer`. Verified locally with `bash -n PKGBUILD`, `makepkg --printsrcinfo`, and `namcap PKGBUILD`.
<!-- SECTION:FINAL_SUMMARY:END -->

47
backlog/tasks/task-162 - Normalize-packaged-Linux-paths-to-canonical-SubMiner-directories.md Normal file
View File

@@ -0,0 +1,47 @@
---
id: TASK-162
title: Normalize packaged Linux paths to canonical SubMiner directories
status: In Progress
assignee:
- codex
created_date: '2026-03-11 08:28'
updated_date: '2026-03-11 08:29'
labels:
- linux
- packaging
- docs
dependencies: []
references:
- launcher/mpv.ts
- launcher/picker.ts
- plugin/subminer/binary.lua
- plugin/subminer.conf
- docs-site/installation.md
- docs-site/launcher-script.md
- README.md
priority: medium
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Align packaged Linux path conventions so system-installed assets use canonical `SubMiner` directories and match runtime auto-detection. Cover AppImage binary discovery, rofi theme discovery/docs, and related path references while preserving lowercase names only for the launcher wrapper, rofi theme filename, and mpv Lua plugin/conf.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [ ] #1 Launcher/runtime path discovery prefers canonical packaged Linux locations that use `SubMiner` casing for shared data and config directories.
- [ ] #2 Tests cover the expected packaged Linux discovery paths for the AppImage and rofi theme search behavior.
- [ ] #3 User-facing docs reference the canonical packaged Linux locations consistently.
- [ ] #4 Lowercase names remain only where intentionally required for the launcher wrapper, rofi theme filename, and mpv Lua plugin/conf.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add failing launcher tests for canonical packaged Linux discovery paths: /usr/lib/subminer/SubMiner.AppImage via PATH symlink flow and /usr/share/SubMiner/themes/subminer.rasi for rofi theme lookup.
2. Update launcher runtime path discovery to prefer canonical packaged Linux shared-data locations using SubMiner casing.
3. Update plugin auto-detection comments and binary search defaults so packaged Linux paths stay consistent with launcher/runtime expectations.
4. Update user-facing docs to reference canonical SubMiner-cased config/share paths while keeping lowercase names only for the launcher wrapper, rofi theme filename, and mpv Lua plugin/conf.
5. Run targeted launcher tests plus docs checks.
<!-- SECTION:PLAN:END -->

73
backlog/tasks/task-163 - Resolve-current-lint-format-and-style-check-failures.md Normal file
View File

@@ -0,0 +1,73 @@
---
id: TASK-163
title: 'Resolve current lint, format, and style check failures'
status: Done
assignee:
- Codex
created_date: '2026-03-11 08:48'
updated_date: '2026-03-11 08:49'
labels:
- maintenance
- tooling
dependencies: []
references:
- /home/sudacode/projects/japanese/SubMiner/package.json
- /home/sudacode/projects/japanese/SubMiner/docs-site/development.md
- /home/sudacode/projects/japanese/SubMiner/docs-site/architecture.md
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Run the repo's maintained static/style gates, fix any failures they report, and leave the working tree with those checks passing without disturbing unrelated in-progress work.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 The repo's maintained static/style commands for this cleanup are identified and recorded.
- [x] #2 Any failures from those commands are fixed in-scope in the codebase.
- [x] #3 The same static/style commands pass after the fixes.
- [x] #4 Verification results and any skipped checks are documented before handoff.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Run the maintained static/style gates for this repo: `bun run typecheck` and `bun run format:check:src`.
2. Inspect each failure and patch only the files implicated by the failing command, preserving unrelated user changes.
3. Re-run the failing gate after each fix until both commands pass.
4. Run one final consolidated verification pass, record exact commands/results, and note any intentionally skipped broader gates outside lint/style scope.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Identified maintained commands from repo docs/scripts: `bun run typecheck` and `bun run format:check:src`. `changelog:lint` exists but is release-fragment specific, not a general lint/style gate for this request.
Ran `bun run typecheck` at 2026-03-11 01:48 PDT: passed.
Ran `bun run format:check:src` at 2026-03-11 01:48 PDT: failed on `src/release-workflow.test.ts`.
Applied a scoped Prettier rewrite with `./node_modules/.bin/prettier --write src/release-workflow.test.ts`.
Re-ran `bun run format:check:src` at 2026-03-11 01:49 PDT: passed.
Re-ran `bun run typecheck` at 2026-03-11 01:49 PDT: passed.
Skipped broader test/build/docs gates because the user asked specifically for lint/format/style cleanup and the only required change was a formatting-only update in one test file.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Resolved the repo's current static/style failure by reformatting `src/release-workflow.test.ts` to match the maintained Prettier scope. The only code change was line wrapping in the `generate:config-example` assertion; behavior did not change.
Verification run:
- `bun run typecheck`
- `bun run format:check:src`
- `./node_modules/.bin/prettier --write src/release-workflow.test.ts`
- `bun run format:check:src`
- `bun run typecheck`
Result: both maintained gates requested for this cleanup now pass. Broader build/test/docs lanes were intentionally not run because this task was limited to lint/format/style checks and required a formatting-only fix.
<!-- SECTION:FINAL_SUMMARY:END -->

68
backlog/tasks/task-164 - Run-maintained-test-gate-and-fix-failing-regressions.md Normal file
View File

@@ -0,0 +1,68 @@
---
id: TASK-164
title: Run maintained test gate and fix failing regressions
status: Done
assignee:
- Codex
created_date: '2026-03-11 08:52'
updated_date: '2026-03-11 08:54'
labels:
- maintenance
- testing
dependencies: []
references:
- /home/sudacode/projects/japanese/SubMiner/package.json
- /home/sudacode/projects/japanese/SubMiner/docs-site/development.md
- /home/sudacode/projects/japanese/SubMiner/docs-site/architecture.md
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Execute the repo's maintained test verification flow, fix any regressions surfaced by those commands, and leave the requested test gate passing without disturbing unrelated in-progress work.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 The maintained test commands chosen for this pass are recorded in the task plan.
- [x] #2 Any test failures encountered in that gate are fixed in-scope with appropriate regression coverage when needed.
- [x] #3 The same maintained test gate passes after the fixes.
- [x] #4 Verification results, skips, and remaining risks are documented before handoff.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Run the maintained verification gate documented for local handoff: `bun run test:fast`, `bun run test:env`, `bun run build`, and `bun run test:smoke:dist`.
2. Stop at the first failing command, inspect the exact failure, and use a red/green loop with the smallest targeted failing test before writing any production-code fix.
3. Re-run the targeted failing test, then the original failing command, and continue through the remaining gate.
4. Record results, any skips, and residual risks before handoff.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Using the docs-site recommended local gate as the maintained test/build verification flow for this request.
Ran `bun run test:fast` at 2026-03-11 01:52 PDT: passed.
Ran `bun run test:env` at 2026-03-11 01:53 PDT: passed.
Ran `bun run build` at 2026-03-11 01:53 PDT: passed.
Ran `bun run test:smoke:dist` at 2026-03-11 01:53 PDT: passed.
No failing tests surfaced in the maintained gate, so no production-code or test changes were required in this pass.
Working tree still includes unrelated user edits plus the previously-applied formatting change in `src/release-workflow.test.ts`; this task did not add new source changes.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Executed the repo's maintained local verification gate from the development docs: `bun run test:fast`, `bun run test:env`, `bun run build`, and `bun run test:smoke:dist`.
Result: every command passed. No failing tests surfaced, so no additional fixes or new regression tests were required for this task.
Working tree note: existing unrelated user changes remain in place, along with the prior formatting-only change to `src/release-workflow.test.ts` from TASK-163. This task introduced no new code changes.
<!-- SECTION:FINAL_SUMMARY:END -->

4
changes/aur-install-docs.md Normal file
View File

@@ -0,0 +1,4 @@
type: docs
area: install
- Added Arch Linux AUR install docs for `subminer-bin` in the README and installation guide.

16
docs-site/installation.md
View File

@@ -39,6 +39,22 @@
## Linux ## Linux
### Arch Linux (AUR)
Install [`subminer-bin`](https://aur.archlinux.org/packages/subminer-bin) from the AUR if you want the packaged Linux release managed by pacman. The package installs the official SubMiner AppImage plus the `subminer` wrapper.
```bash
paru -S subminer-bin
```
Or manually:
```bash
git clone https://aur.archlinux.org/subminer-bin.git
cd subminer-bin
makepkg -si
```
### AppImage (Recommended) ### AppImage (Recommended)
Download the latest AppImage from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest): Download the latest AppImage from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest):

33
docs-site/troubleshooting.md
View File

@@ -280,6 +280,39 @@ The Jimaku API has rate limits. If you see 429 errors, wait for the retry durati
- **X11**: Requires `xdotool` and `xwininfo`. If missing, the overlay cannot track the mpv window position. - **X11**: Requires `xdotool` and `xwininfo`. If missing, the overlay cannot track the mpv window position.
- **Mouse passthrough**: On Linux, Electron's mouse passthrough is unreliable. SubMiner keeps pointer events enabled, meaning you may need to toggle the overlay off to interact with mpv controls underneath. - **Mouse passthrough**: On Linux, Electron's mouse passthrough is unreliable. SubMiner keeps pointer events enabled, meaning you may need to toggle the overlay off to interact with mpv controls underneath.
### Hyprland
SubMiner's overlay is a transparent, frameless, always-on-top Electron window. Hyprland needs window rules to keep it transparent and borderless, and `pass` bindings to forward global shortcuts to SubMiner.
**Overlay is not transparent or has a visible border**
Add these window rules to your `hyprland.conf`:
```ini
windowrule = float on, match:class SubMiner
windowrule = border_size 0, match:class SubMiner
windowrule = xray off override, match:class SubMiner
windowrule = no_shadow on, match:class SubMiner
windowrule = no_blur on, match:class SubMiner
```
Without `xray off override`, the compositor may render the transparent overlay incorrectly — you might see a solid background or visual artifacts instead of the mpv video underneath.
**Global shortcuts not working**
On Hyprland, Electron cannot register global shortcuts on its own. You must explicitly pass keybindings to SubMiner using `pass` rules:
```ini
bind = ALT SHIFT, O, pass, class:^(SubMiner)$
bind = ALT SHIFT, Y, pass, class:^(SubMiner)$
```
Add a `pass` rule for each global shortcut you configure. The defaults are `Alt+Shift+O` (toggle overlay) and `Alt+Shift+Y` (Yomitan settings). If you remap `shortcuts.toggleVisibleOverlayGlobal` to a different key, update the `pass` rule to match.
Without these rules, Hyprland intercepts the keypresses before they reach SubMiner, and the shortcuts silently do nothing.
For more details, see the Hyprland docs on [global keybinds](https://wiki.hypr.land/Configuring/Binds/#global-keybinds) and [window rules](https://wiki.hypr.land/Configuring/Window-Rules/).
### macOS ### macOS
- **Accessibility permission**: Required for window tracking. Grant it in System Settings > Privacy & Security > Accessibility. - **Accessibility permission**: Required for window tracking. Grant it in System Settings > Privacy & Security > Accessibility.

105
docs/plans/2026-03-10-subminer-change-verification-design.md Normal file
View File

@@ -0,0 +1,105 @@
# SubMiner Change Verification Skill Design
**Date:** 2026-03-10
**Status:** Approved
## Goal
Create a SubMiner-specific skill that agents can use to verify code changes with automated checks. The skill must support both targeted regression testing during debugging and pre-handoff verification before final response.
## Skill Contract
- **Name:** `subminer-change-verification`
- **Trigger:** Use when working in the SubMiner repo and you need to verify code changes actually work, especially for launcher, mpv, plugin, overlay, runtime, Electron, or env-sensitive behavior.
- **Default posture:** cheap-first; prefer repo-native tests and narrow lanes before broader or GUI-dependent verification.
- **Outputs:**
- verification summary
- exact commands run
- artifact paths for logs, captured summaries, and preserved temp state on failures
- skipped lanes and blockers
- **Non-goals:**
- replacing the repo's native tests
- launching real GUI apps for every change
- default visual regression or pixel-diff workflows
## Lane Selection
The skill chooses lanes from the diff or explicit file list.
- **`docs`**
- For `docs-site/`, `docs/`, and similar documentation-only changes.
- Prefer `bun run docs:test` and `bun run docs:build`.
- **`config`**
- For `src/config/`, config example generation/verification paths, and config-template-sensitive changes.
- Prefer `bun run test:config`.
- **`core`**
- For general source-level changes where type safety and the fast maintained lane are the best cheap signal.
- Prefer `bun run typecheck` and `bun run test:fast`.
- **`launcher-plugin`**
- For `launcher/`, `plugin/subminer/`, plugin gating scripts, and wrapper/mpv routing work.
- Prefer `bun run test:launcher:smoke:src` and `bun run test:plugin:src`.
- **`runtime-compat`**
- For runtime/composition/bundled behavior where dist-sensitive validation matters.
- Prefer `bun run build`, `bun run test:runtime:compat`, and `bun run test:smoke:dist`.
- **`real-gui`**
- Reserved for cases where actual Electron/mpv/window behavior must be validated.
- Not part of the default lane set; the classifier marks these changes as candidates so the agent can escalate deliberately.
## Escalation Rules
1. Start with the narrowest lane that credibly exercises the changed behavior.
2. If a narrow lane fails in a way that suggests broader fallout, expand once.
3. If a change touches launcher/mpv/plugin/runtime/overlay/window tracking paths, include the relevant specialized lanes before falling back to broad suites.
4. Treat real GUI/mpv verification as opt-in escalation:
- use only when cheaper evidence is insufficient
- allow for platform/display/permission blockers
- report skipped/blocker states explicitly
## Helper Script Design
The skill uses two small shell helpers:
- **`scripts/classify_subminer_diff.sh`**
- Accepts explicit paths or discovers local changes from git.
- Emits lane suggestions and flags in a simple line-oriented format.
- Marks real GUI-sensitive paths as `flag:real-gui-candidate` instead of forcing GUI execution.
- **`scripts/verify_subminer_change.sh`**
- Creates an artifact directory under `.tmp/skill-verification/<timestamp>/`.
- Selects lanes from the classifier unless lanes are supplied explicitly.
- Runs repo-native commands in a stable order and captures stdout/stderr per step.
- Writes a compact `summary.json` and a human-readable `summary.txt`.
- Skips real GUI verification unless explicitly enabled.
## Artifact Contract
Each invocation should create:
- `summary.json`
- `summary.txt`
- `classification.txt`
- `env.txt`
- `lanes.txt`
- `steps.tsv`
- `steps/<step>.stdout.log`
- `steps/<step>.stderr.log`
Failures should preserve the artifact directory and identify the exact failing command and log paths.
## Agent Workflow
1. Inspect changed files or requested area.
2. Classify the change into verification lanes.
3. Run the cheapest sufficient lane set.
4. Escalate only if evidence is insufficient.
5. Escalate to real GUI/mpv only for actual Electron/mpv/window behavior claims.
6. Return a short report with:
- pass/fail/skipped per lane
- exact commands run
- artifact paths
- blockers/gaps
## Initial Implementation Scope
- Ship the skill entrypoint plus the classifier/verifier helpers.
- Make real GUI verification an explicit future hook rather than a default workflow.
- Verify the new skill locally with representative classifier output and artifact generation.

111
docs/plans/2026-03-10-subminer-scrum-master-design.md Normal file
View File

@@ -0,0 +1,111 @@
# SubMiner Scrum Master Skill Design
**Date:** 2026-03-10
**Status:** Approved
## Goal
Create a repo-local skill that can take incoming requests, bugs, or issues in the SubMiner repo, decide whether backlog tracking is warranted, create or update backlog work when appropriate, plan the implementation, dispatch one or more subagents, and ensure verification happens before handoff.
## Skill Contract
- **Name:** `subminer-scrum-master`
- **Location:** `.agents/skills/subminer-scrum-master/`
- **Use when:** the user gives a feature request, bug report, issue, refactor, or implementation ask in the SubMiner repo and the agent should own intake, planning, backlog hygiene, dispatch, and completion flow.
- **Responsibilities:**
- assess whether backlog tracking is warranted
- if needed, search/update/create proper backlog structure
- write a plan before dispatching coding work
- choose sequential vs parallel execution
- assign explicit ownership to workers
- require verification before final handoff
- **Limits:**
- not the default code implementer unless delegation would be wasteful
- no overlapping parallel write scopes
- no skipping planning before dispatch
- no skipping verification
- must pause for ambiguous, risky, or external side-effect work
## Backlog Decision Rules
Backlog use is conditional, not mandatory.
- **Skip backlog when:**
- question only
- obvious mechanical edit
- tiny isolated change with no real planning
- **Use backlog when:**
- implementation requires planning
- scope/approach needs decisions
- multiple phases or subsystems
- likely subagent dispatch
- work should remain traceable
When backlog is used:
- search first
- update existing matching work when appropriate
- otherwise create standalone task or parent task
- use parent + subtasks for multi-part work
- record the implementation plan before coding starts
## Orchestration Policy
The skill orchestrates; workers implement.
- **No dispatch** for trivial/mechanical work
- **Single worker** for focused single-scope work
- **Parallel workers** only for clearly disjoint scopes
- **Sequential flow** for shared files, runtime coupling, or unclear boundaries
Every worker should receive:
- owned files/modules
- explicit reminder not to revert unrelated edits
- requirement to report changed files, tests run, and blockers
## Verification Policy
Every nontrivial code task gets verification.
- prefer `subminer-change-verification`
- use cheap-first lanes
- escalate only when needed
- accept worker-run verification only if it is clearly relevant and sufficient
- run a consolidating final verification pass when the scrum master needs stronger evidence
## Representative Flows
### Trivial fix, no backlog
1. assess request as mechanical or narrowly reversible
2. skip backlog
3. keep a short internal plan
4. implement directly or use one worker if helpful
5. run targeted verification
6. report concise summary
### Single-task implementation
1. search backlog
2. create/update one task
3. record plan
4. dispatch one worker
5. integrate result
6. run verification
7. update task and report outcome
### Multi-part feature
1. search backlog
2. create/update parent task
3. create subtasks for distinct deliverables/phases
4. record sequencing in the plan
5. dispatch workers only where write scopes do not overlap
6. integrate
7. run consolidated verification
8. update task state and report outcome
## V1 Scope
- instruction-heavy `SKILL.md`
- no helper scripts unless orchestration becomes too repetitive
- strong coordination with existing Backlog workflow and `subminer-change-verification`

5
src/release-workflow.test.ts
View File

@@ -52,7 +52,10 @@ test('release package scripts disable implicit electron-builder publishing', ()
}); });
test('config example generation runs directly from source without unrelated bundle prerequisites', () => { test('config example generation runs directly from source without unrelated bundle prerequisites', () => {
assert.equal(packageJson.scripts['generate:config-example'], 'bun run src/generate-config-example.ts'); assert.equal(
packageJson.scripts['generate:config-example'],
'bun run src/generate-config-example.ts',
);
}); });
test('windows release workflow publishes unsigned artifacts directly without SignPath', () => { test('windows release workflow publishes unsigned artifacts directly without SignPath', () => {