# v3.0.0 Planning - Current State (2026-05-24)

> **Start here.** This is the orientation map for the v3.0.0 marketplace-migration planning folder: what each file is, where things stand, and what is needed from the maintainer to move forward. Point-in-time snapshot; the "what's needed" list changes as decisions land.

---

## Where things stand (one paragraph)

v2.19.0 shipped on 2026-05-23 (tag `a18e4d5`), so the pre-promotion-hardening entrance gate for v3 is **met**. The target marketplace registry already exists: `product-on-purpose/agent-plugins` (private, well-formed `marketplace.json` with the locked `product-on-purpose` identity), but its pin is **stale** (points at pm-skills v2.17.0) and it has **no validation CI**. The planning set in this folder is **drafted and committed** (pushed to origin/main). The release has **not started**. Everything is gated on one keystone decision: **the launch approach (A / B / C)**, which determines whether v3 is a breaking 3.0.0 migration or an additive minor launch, and reshapes the plan and migration guide accordingly.

---

## File index

| File | What it is | Status |
|---|---|---|
| `current_2026-05-24.md` | This orientation snapshot | You are here |
| `plan_v3.0.0.md` | Master release plan: current->target state, 6 phases, 5 decision briefs, acceptance criteria, dependencies | Drafted; decision briefs have open maintainer slots |
| `decision-worksheet.md` | Plain-language decision tracker (the 5 briefs + the sequencing question) plus the verified Claude Code mechanics | Drafted; reflects current leanings |
| `launch-and-notification-playbook.md` | The launch-approach options (A additive / B soft / C hard) + the complete user-notification channel inventory + best practices | Drafted; recommends Approach B |
| `registry-ci-spec.md` | Spec for the registry-validation CI (schema, required fields, pinned-sha-on-tag, installability) | Drafted spec; to be implemented in the agent-plugins repo at execution |
| `upgrade-smoke-test-matrix.md` | The 6-scenario install/upgrade verification gate (incl. the duplicate-install negative test) | Drafted; run at Phase 4, before going public |
| `migration-guide-draft.md` | User-facing migration content (3 user situations, command sequence, timeline) | Draft; framed around Approach B, with bracketed Approach C notes; finalize once the approach is locked |
| `marketplace-repo-skeleton/` (3 files) | Early draft of the marketplace repo (README, marketplace.json, plugin-repo-checklist) | **SUPERSEDED** by the live `agent-plugins` repo; kept for provenance only |

---

## What is already decided (do not re-litigate)

- **Naming (locked).** Host repo `product-on-purpose/agent-plugins`; marketplace identity `product-on-purpose`; install `pm-skills@product-on-purpose`. Already reflected in the live registry.
- **Scope = migration only.** The second plugin (`thinking-framework-skills`, an empty stub) is deferred to a future release.
- **Authoring boundary.** All agent-plugins-side artifacts are staged here as specs; the live private registry is not mutated until execution.
- **D-V3-4 = enforcing registry CI.**
- **Entrance gate met** (v2.19.0 shipped).

---

## What is needed from you (maintainer)

Prioritized. Item 1 unblocks most of the rest.

1. **[KEYSTONE] Pick the launch approach: A, B, or C.** (See `launch-and-notification-playbook.md` Part 1.)
   - **A - Additive:** publish the new marketplace, keep the old path alive, never force migration. Non-breaking, likely a **minor** release.
   - **B - Soft migration (recommended):** A, but retire the old path on a trigger (plugin #2 / adoption), not a fixed date.
   - **C - Hard migration:** deprecate the old path on a fixed window; breaking; **3.0.0**.
   - This decides the version framing and whether the plan/migration-guide are reshaped to "additive launch" or kept as "breaking migration."

2. **Confirm the 5 decision briefs in `plan_v3.0.0.md`** (most are settled given the approach):
   - D-V3-1 keep self-hosted marketplace (dual-home) - leaning locked.
   - D-V3-2 retirement trigger - leaning trigger-based (B).
   - D-V3-3 go public at launch - leaning A.
   - D-V3-4 enforcing registry CI - locked.
   - D-V3-5 version framing - follows from the approach (additive = minor; converge = major).

3. **Authorize the execution actions** (agent-plugins side, staged here) when ready:
   - bump the stale registry pin (v2.17.0 -> current release) + `metadata.version`.
   - implement the registry CI (`registry-ci-spec.md`).
   - run the smoke matrix (`upgrade-smoke-test-matrix.md`).
   - flip the agent-plugins repo public.
   - repoint pm-skills install docs (README + docs-site).

4. **(Optional) sequencing vs v2.20.0.** The promotion-facing hygiene (MCP description drift, workflow-command coverage) was reframed as ordinary commits, not a separate release; confirm if you want any of it before v3.

---

## Suggested reading order

1. This file.
2. `plan_v3.0.0.md` - the plan and its decision briefs.
3. `decision-worksheet.md` - the decisions in plain language, plus the verified Claude Code facts.
4. `launch-and-notification-playbook.md` - the approach options and the notification toolbox.
5. Companions as needed: `registry-ci-spec.md`, `upgrade-smoke-test-matrix.md`, `migration-guide-draft.md`.

---

## Once the approach is locked

- Reconcile `plan_v3.0.0.md`, `decision-worksheet.md`, and `migration-guide-draft.md` into one consistent story (including the version framing).
- Then run the writing-plans step to turn the chosen-approach plan into a step-by-step implementation plan for execution.
