Plan implementation of plugin way discovery (ADR-133)

[aaronsb]

Goal

Plan and implement plugin way discovery per ADR-133 (Proposed). Plugins that ship a ways/ directory are currently invisible to the ways system; this makes them discoverable alongside project-local and global ways.

Background

ADR-133 was salvaged from the discarded feat/plugin-way-discovery exploration (PR #76, closed) and re-filed as Proposed. The design is sound and its load-bearing assumption — claude plugin list --json returning id/enabled/installPath/lastUpdated — is verified current (2026-06). What it lacks is a fresh implementation against today's ways-cli, since the original branch's code predated several refactors.

Design (per ADR-133)

Hybrid: resolve once at session start, scan many.

1. SessionStart hook runs claude plugin list --json, filters to enabled == true, checks for $installPath/ways/, dedups by latest lastUpdated, writes $SESSION_DIR/plugin-ways.json.
2. ways scan reads the manifest and adds plugin dirs as a third candidate source, between project-local and global (precedence: project > plugin > global).
3. Corpus generation reads the same manifest so semantic matching covers plugin ways.
4. Plugin way IDs namespaced plugin:{id}/... to avoid collisions.
5. Plugin macros follow the project-macro trust model (disabled by default).

Why this shape

ways scan runs on every prompt and tool-use, so per-invocation claude plugin list --json (~100-200ms) is a non-starter — hence resolve-once-at-session-start. Reading the manifest is cheap; the CLI is the stable public interface, avoiding coupling to Claude Code's internal plugin storage.

Planning tasks (this issue)

• Re-map ADR-133's Implementation section onto the current ways-cli structure — the listed touch points (candidates.rs::collect_candidates(), cmd/corpus.rs, the SessionStart chain) predate refactors and need re-verification
• Confirm session-dir location and lifecycle for the plugin-ways.json manifest
• Decide manifest staleness handling (mid-session plugin install/toggle) — ADR accepts "stale until next session"
• Decide ID-namespacing and precedence test coverage (the old branch had a simulation suite worth referencing)
• Decide macro-trust mechanism: new trusted-plugin-macros file vs. extend trusted-project-macros
• Break implementation into branch-able tasks and flip ADR-133 Proposed → Accepted when work starts

References

• ADR-133 (Proposed)
• Closed exploration: PR WIP - feat(ways): plugin way discovery (ADR-129) #76 (full diff + original simulation test design preserved there)
• Related: ADR-108, ADR-111