# Design: per-provider delivery + plugin-primary architecture (end goal)

Status: **Phase 2 implemented** (0.5.77); Phase 3 docs/matrix sync implemented
afterward; Phases 1 and 4 outstanding.
Fork: `redesign/per-provider-delivery`.

## Progress

- **Phase 2 (Claude plugin-primary) — done (0.5.77).** A `--claude` install no
  longer copies project `.claude/skills/`; skills come from the enabled plugin
  (the per-repo `enabledPlugins` config added in 0.5.76). The skeleton no longer
  plants `.claude/skills/` at all — `install_skills` is the canonical writer.
  Escape hatch: `--claude-skills` installs the project-level copy for repos that
  want a repo-pinned set. `.claude/commands` and `.claude/settings.json` (hooks)
  still install.
- Outstanding: Phase 1 (codex/opencode skeleton selection hygiene) and Phase 4
  (end-to-end marketplace verification on the desktop).

## The question

Should PRD Plugin ship **separate npm packages per provider** (`prd-plugin-claude`,
`prd-plugin-openai`, `prd-plugin-opencode`) or **one configurable package** that
installs only the selected provider(s)?

## Decision: one configurable package, install-time provider selection

Run through CRAFTE:

- **Correct** — both work. Tie.
- **Robust** — separate packages mean publishing/versioning/syncing N packages for
  every change, with guaranteed cross-package drift and version skew. We spent a
  whole release cycle fighting drift across mirror copies *inside one repo*; N
  packages multiplies that across release boundaries. One package = one source of
  truth. Decisive.
- **Aligned** — the method is host-agent neutral, so one configurable package
  matches the user's goal better than provider-specific package sprawl.
- **Faithful-to-method** — the repo is built around one canonical `skills/` +
  install-scope manifests that select what lands where. Separate packages blow
  that up.
- **Tested** — install-scope and release checks can verify one package and its
  provider-specific outputs; separate packages multiply the test matrix.
- **Efficient** — the only cost of one package is shipping a few KB of unused
  adapter templates in the tarball; install writes only the selected provider's
  files. Separate packages add maintenance without improving the delivered
  outcome.

**Verdict: single configurable package.** Providers are selected at install time
(the `--codex` / `--opencode` / `--claude` flags already do this — "OpenAI" =
Codex, `.agents/skills`). The end-goal work refines selection so a single-provider
install writes *only* that provider's files (no cross-provider cruft) and uses
each provider's **native** delivery.

## End goal: native, per-provider, plugin-primary

| Provider | Native delivery | Selected by |
| --- | --- | --- |
| Claude | **Plugin** (marketplace + `enabledPlugins` in `.claude/settings.json`), skills namespaced `prd-plugin:*` | `--claude` |
| OpenAI / Codex | `.agents/skills/` discovery | `--codex` |
| opencode | `.opencode/skill/` + `opencode.json` plugin spec | `--opencode` |

Per repo, a single committed config opts the provider in (done for Claude in
0.5.76: `extraKnownMarketplaces` + `enabledPlugins`). On/off is the provider's
native mechanism (Claude: `/plugin enable|disable prd-plugin@prd-plugin`).

## The resolved dual-delivery problem

Before 0.5.77, a `--claude` install delivered skills twice: as project skills in
`.claude/skills/` and as an enabled plugin (`prd-plugin:*`). That was redundant
and confusing. The implemented default is now **Claude plugin-primary**:
`--claude` delivers skills via the enabled plugin, while `--claude-skills` is the
explicit repo-pinned escape hatch for projects that want `.claude/skills/`.

Keep `.claude/commands/` (the `/prd-*` admin commands) and `.claude/settings.json`
(hooks) as project files; those are repo-scoped by design.

## Phased plan (each phase shippable + fully tested)

1. **Selection hygiene** — a single-provider install writes only that provider's
   discovery dirs; assert no cross-provider files are planted. (low risk)
2. **Claude plugin-primary** — done in 0.5.77: `--claude` wires the marketplace +
   `enabledPlugins` and skips copying `.claude/skills/`, relying on the plugin for
   skills. `--claude-skills` is the project-level copy escape hatch. (medium)
3. **Docs + matrix** — update INSTALL-MATRIX and README to the per-provider,
   native-delivery model. (low)
4. **Marketplace correctness** — verify `markusuk1/prd-plugin` resolves as a
   marketplace from the desktop and CLI end-to-end (trust prompt → install →
   `prd-plugin:*` skills appear). (verification)

## Out of scope / explicitly rejected

- Separate npm packages per provider (rejected above).
- A bespoke `/prd-plugin on|off` command (native `/plugin enable|disable` is the
  correct/proper/robust toggle; 0.5.76 + this design supersede it).

## Decision status

The load-bearing call has been made: Claude is plugin-primary by default. The
remaining work is selection hygiene for non-selected provider skeleton files and
live desktop marketplace verification.