docs(013): add RFC 0001 for the skillrig mise backend plugin

[so0k]

What

Adds a research spike and an RFC for a skillrig mise backend plugin that co-installs multiple backing CLIs from one origin monorepo, plus a correction to ARCHITECTURE-v0 §8b. Resolves the investigation in #23.

The RFC is written to bootstrap a new, separate repo (skillrig/mise-skillrig — the plugin is Lua, not Go, so it does not belong in skillrig/cli).

The key finding (why this RFC matters)

#23 proposed the plugin to fix a multi-binary install collision. While researching open question #4, the premise shifted — and then a reviewer pushback sharpened it into the real justification:

• Layer A — install scheduler. The collision (two aliases → same github:org/repo@version deduped to one install) was a scheduler bug, fixed in mise 2026.4.12 (PR #9093). We require it, but it only fixes Layer A.
• Layer B — version resolution. PR #9093 explicitly does not touch version listing/resolution. The origin's strict-semver tag policy forbids prefix tags (iii-v0.1.0) and forces build-metadata streams (v0.5.0+iii). Per SemVer 2.0.0, build metadata is ignored for precedence, so those streams collapse to one version, and version_prefix (a leading-prefix stripper; there is no tag_regex) cannot select a + suffix.

Option	Indep. versions	Co-location	Strict-semver	Native mise
prefix streams + version_prefix	✅	✅	❌ forbidden	✅
build-metadata streams	✅	✅	✅	❌ broken (Layer B)
one release, all binaries	❌	✅	✅	✅ (post-#9093)
separate repo per CLI	✅	❌	✅	✅
skillrig backend plugin	✅	✅	✅	✅ (owns listing)

Only the plugin satisfies independent versioning + co-location + strict-semver together — because its BackendListVersions hook owns version listing. That is a capability justification, not just ergonomics.

Open questions answered (from #23)

• OQ4 (native coverage): partially — #9093 is scheduler-only; build-metadata streams stay native-unresolvable. Plugin justified.
• OQ1 (home/cadence): own repo skillrig/mise-skillrig, backend name skillrig, independent release cadence.
• OQ2 (origin metadata): new convention-versioned [[binaries]] block in .skillrig-origin.toml, mirrored into index.json (stream selector + asset template + checksums). Shared by plugin and CLI (AP-04).
• OQ3 (verification): checksum-only for v1 (origin already ships checksums.txt); treeSha/provenance parity is v2.

Contents

• specledger/013-mise-backend/research/2026-06-02-mise-backend-plugin.md — the spike (corrected after review).
• docs/rfcs/0001-mise-skillrig-backend.md — the RFC: how the origin template, mise + plugin, and skillrig CLI fit together; the [[binaries]] contract; the three Lua hooks (with snippets); auth (incl. the keyring-404 gotcha); verification depth; alternatives; phasing.
• docs/ARCHITECTURE-v0.md §8b — correction callout pointing to the RFC.

Notes for reviewers

• The RFC documents the native fallbacks honestly — an org that can relax its tag policy to prefix streams doesn't need the plugin.
• Docs-only; no code or CLI behavior change. The plugin itself is not built here.

https://claude.ai/code/session_01Nr5ZxzqTGefujhtEVPzMeV

---

Generated by Claude Code

[qodo-code-review]

Review Summary by Qodo

RFC 0001 and research spike for skillrig mise backend plugin

📝 Documentation ✨ Enhancement

Walkthroughs

Description

• Adds RFC 0001 defining a skillrig mise backend plugin for co-installing multiple backing CLIs
  from one origin monorepo with independent versioning under strict-semver tag policy
• Documents the origin-side contract ([[binaries]] block in .skillrig-origin.toml) that the
  plugin depends on, including stream selectors and asset templates
• Explains why native mise cannot resolve build-metadata streams (v0.5.0+iii) due to SemVer
  precedence rules, making the plugin a capability requirement not just ergonomics
• Includes comprehensive research spike validating that mise 2026.4.12 (PR #9093) fixes only the
  install scheduler layer, not version resolution layer
• Corrects ARCHITECTURE-v0 §8b to clarify version_prefix vs non-existent tag_regex, and notes
  that build-metadata streams remain natively unresolvable
• Specifies the three Lua hooks (BackendListVersions, BackendInstall, BackendExecEnv), auth
  token precedence, and v1 verification (checksum-only)

Diagram

flowchart LR
  A["Origin Monorepo<br/>cmd/iii cmd/console<br/>build-metadata tags<br/>v0.5.0+iii v0.2.0+console"] -->|"[[binaries]] contract<br/>index.json"| B["skillrig Backend Plugin<br/>BackendListVersions<br/>BackendInstall<br/>BackendExecEnv"]
  B -->|"skillrig:iii<br/>skillrig:console"| C["Consumer mise.toml<br/>independent versions<br/>per-stream resolution"]
  D["mise 2026.4.12<br/>Layer A: scheduler dedup<br/>PR #9093"] -.->|"necessary but<br/>insufficient"| B
  E["Native mise<br/>Layer B: version resolution<br/>SemVer precedence"] -.->|"cannot resolve<br/>build-metadata"| B

Loading

File Changes

1. docs/ARCHITECTURE-v0.md 📝 Documentation +11/-0

Correct mise backend realities and justify plugin

• Adds correction callout to §8b clarifying that tag_regex does not exist; the real knob is
 version_prefix (leading-prefix stripper only)
• Documents that mise 2026.4.12 (PR #9093) fixes only the install scheduler layer (Layer A), not
 version resolution (Layer B)
• Explains that build-metadata streams (v0.5.0+iii) remain natively unresolvable because SemVer
 precedence collapses them and version_prefix cannot select + suffixes
• Points to RFC 0001 and the research spike as the justification for the skillrig backend plugin
 on capability grounds

docs/ARCHITECTURE-v0.md

---

2. docs/rfcs/0001-mise-skillrig-backend.md 📝 Documentation +377/-0

RFC 0001 for skillrig mise backend plugin

• Defines the skillrig mise backend plugin (new repo skillrig/mise-skillrig, Lua-based) for
 co-installing N backing CLIs as distinct skillrig: tools
• Specifies the origin-side contract: convention-versioned [[binaries]] block in
 .skillrig-origin.toml with stream selector, asset template, checksums, and platform mappings
• Documents the three Lua hooks: BackendListVersions (owns version listing, filters build-metadata
 streams), BackendInstall (downloads, verifies checksums, extracts), BackendExecEnv (sets PATH)
• Explains why native mise cannot satisfy independent versioning + co-location + strict-semver
 together; only the plugin's BackendListVersions can parse and filter build-metadata tags
• Details auth token precedence (reuses mise's native resolver), the keyring-404 gotcha workaround,
 and CLI auto-wiring for skillrig add
• Covers verification depth (v1 checksum-only; v2 treeSha/provenance binding), alternatives
 considered, open questions, and phasing (P0–P4)

docs/rfcs/0001-mise-skillrig-backend.md

---

3. specledger/013-mise-backend/research/2026-06-02-mise-backend-plugin.md 📝 Documentation +257/-0

Research spike validating mise backend plugin necessity

• Research spike answering four open questions from issue #23 about multi-binary co-install from one
 origin monorepo
• Finding 1: Corrects earlier conclusion that mise 2026.4.12 fully resolves the problem; PR #9093
 fixes only the install scheduler (Layer A), not version resolution (Layer B)
• Finding 1b: Proves build-metadata streams (v0.5.0+iii) are structurally unresolvable natively
 because SemVer precedence ignores build metadata and version_prefix cannot select + suffixes
• Finding 2: Clarifies that tag_regex does not exist; per-stream selection uses version_prefix
 (leading-prefix stripper only)
• Finding 3: Documents backend-plugin hook surface (vfox-style Lua) with three hooks, ctx fields,
 and that plugins must re-implement checksum verification
• Finding 4: Validates the keyring-404 gotcha and confirms mise's token precedence already
 centralizes auth via credential_command and env vars
• Finding 5: Establishes plugin justification on capability (owns version listing for build-metadata
 streams), not just ergonomics
• Decisions and recommendations: build the plugin in its own repo, land the origin-metadata contract
 first, document native fallbacks, verify checksums in v1, correct §8b

specledger/013-mise-backend/research/2026-06-02-mise-backend-plugin.md

---

ⓘ You are approaching your monthly quota for Qodo. Upgrade your plan

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (2) 📘 Rule violations (0) 📎 Requirement gaps (0)

Context used

✅ Tickets: 🎫 Feat: custom mise backend for consuming multiple backing CLIs from one origin monorepo

✅ Compliance rules (platform): 152 rules

1. Stale tag_regex guidance 🐞 Bug ⚙ Maintainability

Description

docs/ARCHITECTURE-v0.md now says mise has no tag_regex, but the same section and later “open
questions”/roadmap text still refer to tag_regex as an option to stamp/use, creating contradictory
implementation guidance.

Code

docs/ARCHITECTURE-v0.md[R298-307]

Evidence

The new correction explicitly states tag_regex does not exist, but the same doc still mentions
“tag-regex options” and an open question about stamping tag_regex, and the roadmap repeats
tag_regex language—contradicting the correction.

docs/ARCHITECTURE-v0.md[296-307]
docs/ARCHITECTURE-v0.md[313-314]
docs/ARCHITECTURE-v0.md[439-449]
docs/ROADMAP.md[72-77]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/ARCHITECTURE-v0.md` adds a correction stating mise has no `tag_regex`, but other parts of the doc (including immediately below the correction, plus the open-questions section) still discuss stamping/using `tag_regex` as if it exists. This contradiction will confuse readers and can lead to attempted implementations/config generation using a non-existent option.

## Issue Context
The section is explicitly labeled “retained for history”, which helps, but the doc still uses `tag_regex` language in places that read like current planning items (e.g., open technical questions).

## Fix Focus Areas
- docs/ARCHITECTURE-v0.md[311-314]
- docs/ARCHITECTURE-v0.md[433-449]
- docs/ROADMAP.md[72-77]

(Replace `tag_regex` references with `version_prefix`/"version filters" where applicable, or explicitly label them as historical/outdated and not to be implemented.)

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. SLSA/GPG docs conflict 🐞 Bug ≡ Correctness

Description

The RFC/spike state SLSA/GPG verification is not a current mise github-backend feature (deferred to
v2), but docs/ARCHITECTURE-v0.md still claims mise supports SLSA provenance and GPG asset
verification, leaving the documented verification posture inconsistent.

Code

docs/rfcs/0001-mise-skillrig-backend.md[318]

Evidence

The RFC and spike both state SLSA/GPG are not currently supported (and deferred), while ARCHITECTURE
states mise supports SLSA provenance and GPG asset verification—two incompatible assertions within
this repo’s docs.

docs/rfcs/0001-mise-skillrig-backend.md[309-318]
specledger/013-mise-backend/research/2026-06-02-mise-backend-plugin.md[183-187]
docs/ARCHITECTURE-v0.md[320-322]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The new RFC/spike explicitly says SLSA/GPG verification is not a current mise github-backend feature (and is v2 work), while ARCHITECTURE asserts mise supports SLSA provenance and GPG asset verification. These statements conflict, so readers won’t know what guarantees exist today.

## Issue Context
This PR adds the RFC/spike and also updates ARCHITECTURE §8b with a correction block; it’s a good opportunity to reconcile the remaining verification claims in ARCHITECTURE with the newer RFC/spike position (or adjust the RFC/spike if ARCHITECTURE is the canonical/verified claim).

## Fix Focus Areas
- docs/ARCHITECTURE-v0.md[320-322]
- docs/rfcs/0001-mise-skillrig-backend.md[309-318]
- specledger/013-mise-backend/research/2026-06-02-mise-backend-plugin.md[183-187]

(Choose one accurate statement and update the other docs to match; if unsure, qualify ARCHITECTURE’s claim as "unverified/aspirational" or move it into v2.)

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

ⓘ You are approaching your monthly quota for Qodo. Upgrade your plan

[so0k]

✅ The plugin this RFC proposes is now built, published, and validated end-to-end

The skillrig backend plugin RFC 0001 specifies now exists:

👉 https://github.com/skillrig/mise-skillrig (public)

It was built against a real origin (so0k/skillrig-origin-demo, private) rather than a fixture, and proven end-to-end: two backing CLIs co-installed from one monorepo as distinct, independently-versioned tools — exactly the capability the RFC argues native mise cannot provide.

mise settings experimental=true
mise plugin install skillrig https://github.com/skillrig/mise-skillrig
export MISE_GITHUB_TOKEN=$(gh auth token)
mise use skillrig:my-org/our-skills/jira@1.7.0
mise use skillrig:my-org/our-skills/tfc@latest   # two tools, one repo, distinct versions

---

How it works

Hook	Behavior
BackendListVersions	Lists the origin's tags, keeps only those in the addressed binary's stream, returns clean semver cores ascending. This is the load-bearing capability — it owns version listing, which is precisely why native mise can't resolve build-metadata streams.
BackendInstall	Resolves the exact stream tag → release → downloads <bin>_<ver>_<os>_<arch>.tar.gz → sha256-verifies against the per-tool <bin>_checksums.txt → extracts → normalizes the binary into install_path/bin/<bin>.
BackendExecEnv	Puts install_path/bin on PATH.

• Addressing: skillrig:<owner>/<repo>/<bin> (the GitHub coordinate is in the address; bare skillrig:<bin> + an origin option / SKILLRIG_ORIGIN also works).
• Stream selection supports both schemes: semver build-metadata <core>+<bin> (e.g. 1.7.0+jira) and prefix <bin>-v<core>. latest resolves to the newest version within the stream.
• Auth: reuses mise's GitHub token precedence (MISE_GITHUB_TOKEN → … → gh); no new credential surface. Private-repo asset downloads use the asset API + Accept: application/octet-stream.
• Convention gate: best-effort check of skillrigConvention from index.json (currently 1); the origin name is deliberately never checked (it's an identity label that legitimately differs from the hosting coordinate — see divergence feat(001): support optional branch/ref in origin reference (OWNER/REPO[@REF]) #4 below).
• Targets: Linux + macOS (Windows fails fast with a clear message).

Verification: 54 offline unit tests, stylua + lua-language-server clean, CI green on ubuntu + macOS, an opus adversarial multi-lens review (Lua correctness / mise-API + security / contract fidelity), and the live two-tool co-install above.

---

How it addresses the two Qodo Review findings

Qodo raised exactly two findings, both doc-consistency bugs. Building the plugin against a real origin produced the empirical ground truth that settles both — note these are edits owed in this repo's docs; the plugin repo itself is already consistent with the resolution.

① Stale tag_regex guidance (ARCHITECTURE-v0.md:314,449, ROADMAP.md:76, contradicting the §8b correction at :299)

The implementation makes this stronger than a terminology nit. The demo origin's own mise.toml literally tried per-tool github:<repo>[tag_regex=<tool>$], and it empirically fails — mise keys a github-backend tool by owner/repo and tracks one version per tool, so all N entries collapse into a single install (documented in the origin's docs/BINARY-DISTRIBUTION.md §1). So tag_regex is not merely "not a suffix selector that exists" — even its backend-option form cannot co-install from a monorepo at all. The actual mechanism is the plugin's BackendListVersions owning the listing.
→ Resolution: the lingering tag_regex references should be replaced with "the skillrig plugin owns version listing" (not version_prefix, which also can't select build-metadata streams). The implementation is the proof.

② SLSA/GPG verification conflict (ARCHITECTURE-v0.md:320 claims mise supports SLSA + GPG, vs RFC/spike deferring them to v2)

Settled by what shipped: the plugin verifies checksum-only (sha256 vs <bin>_checksums.txt), confirming the RFC/spike position. Critically — and this sharpens the doc fix — mise does not verify anything for a custom backend (unlike the native github backend), so a skillrig: tool gets no mise-side SLSA/GPG today regardless of what the native backend supports. SLSA/attestation is therefore plugin-side v2 work.
→ Resolution: qualify ARCHITECTURE-v0.md:320 as applying to the native github backend only (and as aspirational/unverified there), and state explicitly that the custom skillrig backend is checksum-only in v1.

---

Implementation ↔ RFC divergences worth folding back into this RFC

Building against the real origin surfaced four places where reality differs from §5–§6. None block the plugin, but the RFC should be updated:

1. No [[binaries]] contract is required. §5/§12 frame the [[binaries]] block as a P1 prerequisite (P1 before P2). The shipped plugin is convention-driven — it derives stream/asset/checksum names from the goreleaser convention (<bin>_<ver>_<os>_<arch>.tar.gz, <bin>_checksums.txt) and reads the binary from the tag's build metadata. The real origin has no [[binaries]] block, and the plugin works without one. P1 becomes an optional enhancement (metadata-driven overrides), not a blocker.
2. Addressing is skillrig:<owner>/<repo>/<bin>, not §6's skillrig:<tool> + separate origin option. Embedding the coordinate in the address is what the origin's docs/BINARY-DISTRIBUTION.md §4 specifies and avoids per-tool origin config.
3. Tags have no leading v and the build metadata is the bare tool name: real tags are 1.7.0+jira / 0.0.6+tfc (not v0.5.0+iii). Checksums are per-tool <bin>_checksums.txt, not a shared checksums.txt as the §5 example shows.
4. The origin field is an identity label, not the coordinate. The demo's files say origin = "foo-org-sports/local-devops-scripts" while it's hosted at so0k/skillrig-origin-demo. The plugin therefore keys off the address coordinate and verifies only skillrigConvention, never the origin name.

Happy to open follow-up PRs for the two doc reconciliations (§8b/ROADMAP tag_regex, and the SLSA/GPG qualification) and the RFC updates above.

_{🤖 Posted on behalf of the implementation work; plugin built + tested with Claude Code.}

[so0k]

Folded everything into this PR — no separate follow-up PRs needed. Rebased onto main (picks up the 1.0.3 release) and pushed.

Both Qodo findings resolved in-repo:

• ① Stale tag_regex — neutralized every lingering reference (ARCHITECTURE-v0 §8b prose, open-Q15, §13 vNext; ROADMAP.md vNext). Per your point, the fix is stronger than "use version_prefix": the §8b correction now states the per-tool github:<repo>[tag_regex=…] form empirically cannot co-install at all, and stream selection is owned by the plugin's BackendListVersions (not version_prefix, which also can't select build-metadata).
• ② SLSA/GPG conflict — §8b finding (3) now qualifies SLSA/GPG as native-github-backend-only and aspirational, and adds the sharper point: mise verifies nothing for a custom backend, so skillrig: is checksum-only (sha256) in v1; SLSA is plugin-side v2. RFC/spike already agreed; they now match.

Conclusion merged (plugin built):

• RFC 0001 → status Accepted/built (links skillrig/mise-skillrig + the quickstart), and all four implementation↔RFC divergences folded in as inline "Shipped:" notes: (1) [[binaries]] not required — plugin is convention-driven; (2) addressing skillrig:<owner>/<repo>/<bin>; (3) tags 1.7.0+jira (no leading v, bare tool name) + per-tool <bin>_checksums.txt; (4) origin is an identity label, plugin keys off the address coordinate and verifies only skillrigConvention. Hooks, verification, template, and phasing reconciled to match.
• README → new "Backing CLIs (mise backend)" section linking the plugin + RFC.

CLI roadmap (your requested next step), clearly defined in docs/ROADMAP.md → v1 "mise backend integration — CLI side", and mirrored in RFC §12:

• P1 — add the [[binaries]] block to .skillrig-origin.toml + emit it into index.json from skillrig index, so resolution becomes metadata-driven (the plugin already works convention-driven; this is the optional override, no longer a prerequisite).
• P3 — skillrig add auto-wiring of skillrig:<owner>/<repo>/<bin> entries from each skill's metadata.x-skillrig.requires.

Ready for re-review.

---

Generated by Claude Code

[sakul-learning]

Post-merge follow-up from the automated review: this PR was merged before the contract-shape findings were addressed, so I’m recording them here as non-blocking follow-up work rather than trying to block the merged PR.

Issues identified

1. .skillrig-origin.toml convention key mismatch

   RFC 0001’s origin-side contract example documents:

   skillrig-convention = 1

   The current CLI parser and fixtures use:

   convention_version = 1

   Following the RFC literally would produce an origin config that the current CLI treats as missing/zero convention version, causing convention-gate failures.

2. index.json.skills shape mismatch

   RFC 0001 shows:

   "skills": { /* unchanged */ }

   The current catalog contract is an array:

   Skills []CatalogEntry `json:"skills"`

   Existing generated/golden catalogs use:

   "skills": [ ... ]

Suggested fixes

• Update RFC 0001’s .skillrig-origin.toml example to use convention_version = 1, unless this is intended to be a contract migration.
• Update RFC 0001’s index.json example to keep "skills": [ /* unchanged */ ], unless this is intended to be a catalog schema migration.
• If either is intentionally a migration, add the matching CLI implementation, tests/fixtures, design-doc compatibility notes, and convention-version handling.

I’m creating a tracking issue that links back to this comment so the merged docs can be corrected in a follow-up PR.