@locksmithdon/dons-flow 2.0.0 → 2.1.0

package/README.md

@@ -1,69 +1,139 @@
 # @locksmithdon/dons-flow
 
-**Don's Flow v2** — a developer-specific Pi Agent workflow package that combines:
+**Don's Flow v2** is a way of composing three distinct approaches to agentic software development into one developer-owned workflow:
 
-- **[RPIV](https://www.npmjs.com/package/@juicesharp/rpiv-pi)** — the observable, artifact-chained delivery pipeline (`discover → research → design → plan → implement → validate → review → commit`).
-- **[Superpowers](https://github.com/obra/superpowers)** — scope control, verification-before-claims, and TDD/subagent execution patterns.
-- **A structured cycle closeout (`land`)** — the 10-step ritual that turns a verified branch into a clean, navigable, documented codebase ready for the next cycle.
+1. **[Superpowers](https://github.com/obra/superpowers)** — the methodology you already trust. Socratic design (`brainstorming`), bite-sized plans (`writing-plans`), red/green TDD (`test-driven-development`), and subagent-driven execution (`subagent-driven-development`). It is fast, opinionated, and proven.
+2. **[RPIV](https://www.npmjs.com/package/@juicesharp/rpiv-pi)** — Juice Sharp's observable, artifact-chained delivery pipeline: `discover → research → design → plan → implement → validate → review → commit`. It adds deliberate checkpoints, self-reflection, and a durable paper trail.
+3. **Don's closeout discipline** — the `land` ritual, `epiphany-tabling`, as-built documentation, retros, and memory reconciliation. It closes the cycle so the next one starts clean.
 
-This package is opinionated. It assumes a particular doc layout and a particular philosophy about what belongs in the codebase vs. what belongs in the developer's tooling.
+None of these replaces the others. Superpowers excels at the inner loop of design and execution. RPIV excels at observable, reviewable delivery. Don's discipline excels at cycle boundaries and learning capture. Together they form a workflow that is fast *and* reflective *and* humane.
 
-> **Why v2?** The first iteration of Don's Flow was a Superpowers-based workflow with a custom landing ritual. This version integrates RPIV's observable delivery pipeline while keeping the closeout, scope-control, and learning-capture practices that made v1 work.
+> **Why v2?** The first iteration of Don's Flow was Superpowers plus a custom landing ritual. v2 keeps that landing ritual and adds RPIV's pipeline as a first-class partner rather than a replacement.
 
-## Install
+## What each system contributes
 
+| System | Core gift | Typical entry points |
+|---|---|---|
+| **Superpowers** | Auto-triggering, opinionated software development methodology | `brainstorming`, `writing-plans`, `test-driven-development`, `subagent-driven-development`, `verification-before-completion` |
+| **RPIV** | Observable, artifact-chained delivery pipeline with built-in reflection | `discover`, `research`, `blueprint`, `implement`, `validate`, `code-review` |
+| **Don's Flow** | Cycle boundaries, scope control, and learning capture | `land`, `epiphany-tabling`, `capturing-learnings`, `as-built-documentation`, `writing-retros` |
+
+## Installation
+
+Install in each repo where you want the workflow, or install once in your global Pi configuration if you want it everywhere.
+
+### 1. Install Superpowers
+
+Superpowers is a harness plugin, not an npm package. Install it for the agent you are using:
+
+**Claude Code**
 ```bash
-pi install npm:@locksmithdon/dons-flow
+/plugin install superpowers@claude-plugins-official
+```
+Or register the Superpowers marketplace first:
+```bash
+/plugin marketplace add obra/superpowers-marketplace
+/plugin install superpowers@superpowers-marketplace
+```
+
+**Codex CLI / Codex App**
+```bash
+/plugins
+# search "Superpowers" and select Install Plugin
+```
+
+**Gemini CLI**
+```bash
+gemini extensions install https://github.com/obra/superpowers
 ```
 
-This package peer-depends on RPIV, the Pi subagent runtime, and Superpowers:
+**Factory Droid**
+```bash
+droid plugin marketplace add https://github.com/obra/superpowers
+droid plugin install superpowers@superpowers
+```
+
+**OpenCode**
+```bash
+# Fetch and follow instructions from:
+# https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md
+```
+
+**Cursor**
+```bash
+/add-plugin superpowers
+# or search "superpowers" in the plugin marketplace
+```
+
+**GitHub Copilot CLI**
+```bash
+copilot plugin marketplace add obra/superpowers-marketplace
+copilot plugin install superpowers@superpowers-marketplace
+```
+
+Full instructions are at [obra/superpowers](https://github.com/obra/superpowers).
+
+### 2. Install RPIV and this package
 
 ```bash
 pi install npm:@juicesharp/rpiv-pi
 pi install npm:@tintinweb/pi-subagents
+pi install npm:@locksmithdon/dons-flow
 ```
 
-Superpowers is not published to npm under a name we can resolve cleanly, so it is declared as an **optional git peer dependency** (`github:obra/superpowers`). You have three ways to satisfy it:
+If RPIV's `/rpiv-setup` command is available, run it once and restart Pi to install RPIV's sibling plugins.
 
-1. **Install via your agent harness's plugin system** (most common):
-   - Claude Code: `/plugin install superpowers@superpowers-marketplace`
-   - Codex CLI: `/plugins` → search "Superpowers"
-   - Gemini CLI: `gemini extensions install https://github.com/obra/superpowers`
-   - See [obra/superpowers](https://github.com/obra/superpowers) for other harnesses.
+### 3. Onboard the repo
 
-2. **Install from GitHub directly** (if your Pi/npm setup supports git URLs):
-   ```bash
-   pi install github:obra/superpowers
-   # or
-   npm install github:obra/superpowers
-   ```
+```bash
+/skill:setup-dons-flow
+```
+
+This checks prerequisites, detects Superpowers, and creates the repo-owned conventions listed below.
+
+## Three ways to work
+
+Don's Flow is not a single mandatory pipeline. It is a score you can conduct in different ways depending on the work.
+
+### Mode A — Superpowers-led
+
+Best when the problem is well-shaped and you want autonomous, TDD-driven execution.
 
-3. **Fork and publish under your own scope** (cleanest long-term):
-   Fork `obra/superpowers`, publish it as `@locksmithdon/superpowers`, then update this package's `peerDependencies` to point at your scoped package. This is the closest analog to how we track RPIV.
+```
+brainstorming → writing-plans → subagent-driven-development → verification-before-completion → land
+```
 
-If RPIV's `/rpiv-setup` command is available, it can install the RPIV sibling plugins in one go.
+Use RPIV only if you hit a research or validation gap that Superpowers does not cover on its own.
 
-## Relationship to Superpowers
+### Mode B — RPIV-led
 
-This package does not replace Superpowers. It treats Superpowers as the upstream methodology for:
+Best when the problem needs discovery, research, or a durable decision trail.
 
-- `brainstorming` — Socratic design refinement before code.
-- `writing-plans` — bite-sized, code-complete implementation plans.
-- `subagent-driven-development` / `executing-plans` — task execution with review.
-- `test-driven-development` — red/green/refactor discipline.
-- `verification-before-completion` — evidence-before-claims.
+```
+discover → research → blueprint → implement → validate → code-review → commit → land
+```
 
-Where RPIV provides an equivalent or stronger mechanism, this package routes through RPIV (e.g., `discover`/`research`/`blueprint` for design and planning, `implement`/`validate` for execution). Where Superpowers has no RPIV equivalent, this package ports or keeps the Superpowers skill (e.g., `land`, `epiphany-tabling`, `capturing-learnings`).
+Use Superpowers inside `implement` for TDD and subagent execution if you want its inner-loop discipline.
 
-## What this package adds to RPIV
+### Mode C — The mixed default
 
-RPIV gives you a strong delivery pipeline. This package adds the seams around it:
+Best for substantial work where you want both reflection and autonomy.
+
+```
+discover → research → blueprint → implement (with Superpowers TDD + subagents) → validate → code-review → commit → land
+```
+
+Between every major artifact, run `capturing-learnings`. During execution, keep `epiphany-tabling` active. If you stop mid-work, use `create-handoff` / `resume-handoff`.
+
+## What this package adds
+
+This package provides the seams between the three systems:
 
 | Skill | Purpose |
 |---|---|
-| `dons-flow` | The map. Tells you which skill to invoke when, and how the workflow fits together. |
+| `dons-flow` | The map. Helps you choose Mode A, B, or C for a given piece of work. |
 | `setup-dons-flow` | Onboarding: checks prerequisites, detects Superpowers, creates repo conventions. |
-| `land` | The 10-step cycle closeout: code review → arch review → security review → as-built docs → doc/knowledge-graph review → AGENTS.md updates → memory reconcile → retro → status review → integrate. |
+| `land` | The 10-step cycle closeout: code review → architectural review → security review → as-built docs → doc/knowledge-graph review → AGENTS.md updates → memory reconcile → retro → status review → integrate. |
 | `epiphany-tabling` | Capture mid-flight realizations in `docs/tabled.md` without derailing current work. |
 | `as-built-documentation` | Replace spec/plan scaffolding with a permanent `docs/changes/` record of what shipped. |
 | `capturing-learnings` | End-of-artifact checkpoints + the "once is a moment; twice is a pattern" promotion rule. |
@@ -72,24 +142,9 @@ RPIV gives you a strong delivery pipeline. This package adds the seams around it
 | `finishing-a-development-branch` | Merge / PR / cleanup decisions at cycle end. |
 | `using-git-worktrees` | Isolated workspaces for parallel workstreams. |
 
-## The integrated workflow
-
-```
-/skill:discover "..."
-/skill:research .rpiv/artifacts/discover/<latest>.md
-/skill:blueprint .rpiv/artifacts/research/<latest>.md   # or design → plan
-/skill:implement .rpiv/artifacts/plans/<latest>.md
-/skill:validate .rpiv/artifacts/plans/<latest>.md
-/skill:code-review
-/skill:commit
-/skill:land
-```
-
-Between every major artifact, run `capturing-learnings`. During execution, keep `epiphany-tabling` active. If you stop mid-work, use `create-handoff` / `resume-handoff`.
-
 ## Repo conventions
 
-This workflow expects the following project-owned files and folders in the codebase:
+These documents live in the codebase because they are shared context for the whole team. The skills that produce and maintain them live in this package.
 
 | Path | Purpose |
 |---|---|
@@ -101,8 +156,6 @@ This workflow expects the following project-owned files and folders in the codeb
 | `docs/runbooks/` | Multi-skill processes |
 | `AGENTS.md` | Repo-level agent guidance |
 
-These documents live in the codebase because they are shared context for the whole team. The skills that produce and maintain them live in this package.
-
 ## Philosophy: what lives where
 
 **In the codebase (shared):**
@@ -120,7 +173,7 @@ This separation lets the same workflow travel with you across repos while keepin
 
 ## Monitoring upstream evolution
 
-The dependency relationship with Superpowers is intentionally deferred. We review monthly whether to keep the git peer dependency, fork Superpowers, or drop it.
+The dependency relationship with Superpowers is intentionally deferred. Superpowers is installed via your harness, so we do not need to resolve it as an npm dependency. We review monthly whether to keep this arrangement, fork Superpowers, or drop the peer dependency entirely.
 
 - Memory: `docs/memory/monitor_upstream_evolution.md`
 - Runbook: `docs/runbooks/monitor-upstream-evolution.md`
@@ -129,11 +182,15 @@ Set a monthly calendar reminder for the 13th, or run the runbook after every 2
 
 ## Typical first use
 
-1. Install this package and its peer dependencies in a repo.
-2. Run `/skill:setup-dons-flow` to check prerequisites and scaffold repo conventions.
-3. Start a feature with `/skill:discover "[feature description]"`.
-4. When implementation is validated and reviewed, run `/skill:land` to close the cycle.
-5. After 2–3 projects, run `docs/runbooks/monitor-upstream-evolution.md` and decide whether to fork Superpowers.
+1. Install Superpowers for your harness.
+2. Install `npm:@juicesharp/rpiv-pi`, `npm:@tintinweb/pi-subagents`, and `npm:@locksmithdon/dons-flow`.
+3. Run `/skill:setup-dons-flow` to scaffold repo conventions.
+4. Choose a mode:
+   - Superpowers-led: start with `brainstorming`.
+   - RPIV-led: start with `/skill:discover "[feature description]"`.
+   - Mixed: start with `discover`, then use Superpowers inside `implement`.
+5. Close the cycle with `/skill:land`.
+6. After 2–3 projects, run the upstream monitoring runbook.
 
 ## License
 

package/docs/memory/monitor_upstream_evolution.md

@@ -9,14 +9,14 @@ next-review: 2026-07-13
 
 How should `@locksmithdon/dons-flow` track its upstream projects?
 
-- **RPIV** (`@juicesharp/rpiv-pi`) is published to npm and already declared as a normal peer dependency.
-- **Superpowers** (`obra/superpowers`) is a GitHub-only skills framework, not published to npm under a resolvable name. The `superpowers` name on npm is taken by an unrelated package.
+- **RPIV** (`@juicesharp/rpiv-pi`) is published to npm and declared as a normal peer dependency.
+- **Superpowers** (`obra/superpowers`) is a harness plugin, not an npm package. It is installed via Claude, Codex, Gemini, Cursor, Copilot, or other agent harnesses, not via `pi install` or `npm install`.
 
-We are not forking or publishing Superpowers yet. Instead, we declared it as an optional git peer dependency (`github:obra/superpowers`) and will monitor both projects for 2–3 months before deciding whether to:
+We are not forking or publishing Superpowers yet. Instead, we document it as a harness-plugin dependency and will monitor both projects for 2–3 months before deciding whether to:
 
-1. Keep the optional git peer dependency.
+1. Keep the harness-plugin arrangement.
 2. Fork Superpowers and publish it under `@locksmithdon/superpowers` as a normal npm peer dependency.
-3. Remove the Superpowers peer dependency entirely and rely on this package's ported closeout skills + RPIV's pipeline.
+3. Drop Superpowers integration entirely and rely on this package's ported closeout skills + RPIV's pipeline.
 4. Some hybrid we haven't thought of yet.
 
 ## Why we deferred
@@ -28,20 +28,20 @@ The integration is new. We want real usage data — at least 2–3 projects run
 | Project | URL | What to check |
 |---|---|---|
 | RPIV | https://github.com/juicesharp/rpiv-mono | New skills that overlap with our closeout workflow; changes to `implement`, `validate`, `code-review`; new onboarding commands. |
-| Superpowers | https://github.com/obra/superpowers | New closeout/landing skills; npm publishing; changes to `brainstorming`, `writing-plans`, `verification-before-completion`; license changes. |
+| Superpowers | https://github.com/obra/superpowers | New closeout/landing skills; npm publishing; changes to `brainstorming`, `writing-plans`, `verification-before-completion`; license changes; new harness install paths. |
 
 ## Decision criteria
 
 Fork and publish Superpowers if:
 - We find ourselves needing its upstream entry points (`brainstorming`, `test-driven-development`, `subagent-driven-development`) in projects where RPIV equivalents don't fit.
 - Superpowers still isn't on npm after 3 months of monitoring.
-- The maintenance burden of a fork feels smaller than the friction of the git dependency.
+- The maintenance burden of a fork feels smaller than the friction of the harness-plugin install path.
 
-Keep the git peer dependency if:
-- The optional install path works reliably across harnesses.
-- We rarely need Superpowers-specific entry points because RPIV covers the pipeline.
+Keep the harness-plugin arrangement if:
+- The plugin install path works reliably across harnesses.
+- We value staying on the upstream release channel.
 
-Remove it if:
+Drop Superpowers integration if:
 - RPIV adds equivalent closeout/landing skills.
 - We stop using Superpowers entry points entirely.
 

package/docs/runbooks/monitor-upstream-evolution.md

@@ -1,6 +1,6 @@
 # Runbook: Monitor Upstream Evolution
 
-Check RPIV and Superpowers monthly to decide how `@locksmithdon/dons-flow` should track them.
+Check RPIV and Superpowers monthly to decide how `@locksmithdon/dons-flow` should track them. Superpowers is a harness plugin; RPIV is an npm package.
 
 ## Schedule
 
@@ -31,7 +31,7 @@ Record findings in `docs/memory/monitor_upstream_evolution.md` under a dated hea
 Visit https://github.com/obra/superpowers and look at:
 
 - **Releases / RELEASE-NOTES.md** — new versions.
-- **Skills** — has Superpowers added a `land`, `closeout`, or `as-built` skill? Has it published to npm?
+- **Skills** — has Superpowers added a `land`, `closeout`, or `as-built` skill? Has it published to npm or added new harness install paths?
 - **Brainstorming / writing-plans / subagent-driven-development** — have these changed in ways that make them more or less attractive than RPIV equivalents?
 - **License** — still MIT and forkable?
 
@@ -42,7 +42,7 @@ Record findings in `docs/memory/monitor_upstream_evolution.md` under the same da
 Review recent projects that used this workflow:
 
 - Did we use Superpowers-specific entry points (`brainstorming`, `writing-plans`, `subagent-driven-development`) or RPIV entry points (`discover`, `blueprint`, `implement`)?
-- Did the optional git peer dependency cause install friction?
+- Did the harness-plugin install path for Superpowers cause friction?
 - Did RPIV's pipeline cover everything we needed?
 - Did our `land` skill feel like the right cycle boundary?
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@locksmithdon/dons-flow",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Don's Flow v2 — a developer-specific Pi Agent workflow built on RPIV's observable pipeline, Superpowers' discipline, and a structured landing closeout.",
   "keywords": [
     "pi-package",
@@ -41,13 +41,7 @@
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
     "@tintinweb/pi-subagents": "*",
-    "@juicesharp/rpiv-pi": "*",
-    "superpowers": "github:obra/superpowers"
-  },
-  "peerDependenciesMeta": {
-    "superpowers": {
-      "optional": true
-    }
+    "@juicesharp/rpiv-pi": "*"
   },
   "scripts": {
     "lint": "echo 'No lint configured yet'",

package/skills/dons-flow/SKILL.md

@@ -1,37 +1,37 @@
 ---
 name: dons-flow
-description: Use when starting or navigating a major piece of work to apply the integrated RPIV + Superpowers-style workflow — discovery, research, design/plan, implement, validate, review, commit, and land
+description: Use when starting or navigating a major piece of work to apply the integrated Superpowers + RPIV + Don's closeout workflow
 ---
 
 # Don's Flow
 
-**Version 2** of the integrated workflow for developer `@locksmithdon`: **RPIV's observable, artifact-chained delivery pipeline** plus **Superpowers' scope control, verification discipline, and cycle closeout**, with the `land` ritual that neither provides on its own.
+**Version 2** of the developer workflow for `@locksmithdon`. It composes three independent systems into one working practice:
 
-v1 was Superpowers-based with a custom landing ritual. v2 adds RPIV's pipeline while keeping the closeout, scope-control, and learning-capture practices.
+1. **Superpowers** — Jesse Vincent's agentic methodology: Socratic design, bite-sized plans, red/green TDD, and subagent-driven execution. It is the system that got Don here.
+2. **RPIV** — Juice Sharp's observable, artifact-chained delivery pipeline. It adds deliberate checkpoints, self-reflection, and a durable paper trail.
+3. **Don's closeout discipline** — the `land` ritual, `epiphany-tabling`, as-built documentation, retros, and memory reconciliation. It closes the cycle so the next one starts clean.
 
-This skill is the map. It does not replace the skills it references — it tells you which skill to invoke when, and which conventions must stay true across all of them.
-
-Superpowers is the upstream methodology at [obra/superpowers](https://github.com/obra/superpowers). It is not published to npm under a resolvable name, so this package declares it as an optional git peer dependency (`github:obra/superpowers`). Install it via your agent harness's plugin system, via the git URL, or by forking and publishing it under your own scope.
+This skill is the map. It does not replace the skills it references — it helps you choose which path to take for a given piece of work, and reminds you which conventions must stay true across all of them.
 
 ## Announce at start
 
-> "I'm using the `dons-flow` skill to run the integrated RPIV + Superpowers workflow."
+> "I'm using the `dons-flow` skill to run the Superpowers + RPIV + closeout triad."
 
 ## When to use this skill
 
-- At the **start** of a new piece of work, to pick the right entry point.
+- At the **start** of a new piece of work, to choose Superpowers-led, RPIV-led, or mixed mode.
 - When you are **mid-work** and unsure whether to keep going, hand off, revise, or close out.
 - At the **end** of a validated implementation, to begin the `land` closeout ritual.
 - When onboarding a fresh repo to this workflow.
 
 ## Required installed packages
 
-This skill assumes the following Pi packages are installed:
+This skill assumes the following are available:
 
-- `@juicesharp/rpiv-pi` — the RPIV pipeline skills
-- `@tintinweb/pi-subagents` — subagent runtime used by RPIV
-- `@locksmithdon/dons-flow` — this package, which adds closeout and discipline skills
-- `superpowers` — the upstream Superpowers methodology (optional, via harness plugin or `github:obra/superpowers`)
+- **Superpowers** — the upstream methodology. Installed as a harness plugin (Claude, Codex, Gemini, Cursor, Copilot, etc.), not via npm. See `setup-dons-flow` for per-harness commands.
+- **RPIV** (`@juicesharp/rpiv-pi`) — the observable delivery pipeline.
+- **Pi subagent runtime** (`@tintinweb/pi-subagents`) — runtime used by RPIV.
+- **Don's Flow** (`@locksmithdon/dons-flow`) — this package, which adds closeout and discipline skills.
 
 If RPIV or the subagent runtime is missing, stop and install them before proceeding. If Superpowers is missing, this package's ported skills still provide the closeout workflow, but you will not have access to the upstream Superpowers entry points like `brainstorming` or `test-driven-development`.
 
@@ -45,13 +45,47 @@ If this repo has not been onboarded yet, run:
 
 That skill checks prerequisites, detects Superpowers, and creates the repo-owned conventions (`docs/tabled.md`, `docs/status.md`, `docs/memory/`, `docs/changes/`, `docs/retros/`, `docs/runbooks/`, `AGENTS.md`).
 
-## Integrated workflow
+## Three modes of working
+
+Don's Flow is not a single mandatory pipeline. Choose the mode that fits the work.
+
+### Mode A — Superpowers-led
+
+Best when the problem is well-shaped and you want autonomous, TDD-driven execution.
 
 ```
-Discover → Research → Design/Blueprint → Plan → Implement → Validate → Review → Commit → Land
+brainstorming → writing-plans → subagent-driven-development → verification-before-completion → land
+```
+
+Use RPIV only if you hit a research or validation gap that Superpowers does not cover on its own.
+
+### Mode B — RPIV-led
+
+Best when the problem needs discovery, research, or a durable decision trail.
+
+```
+discover → research → blueprint → implement → validate → code-review → commit → land
 ```
 
-Each arrow is a skill invocation. Each skill produces or updates an artifact. Nothing is unilateral: every boundary is a conversation or a checkpoint.
+Use Superpowers inside `implement` for TDD and subagent execution if you want its inner-loop discipline.
+
+### Mode C — Mixed default
+
+Best for substantial work where you want both reflection and autonomy.
+
+```
+discover → research → blueprint → implement (with Superpowers TDD + subagents) → validate → code-review → commit → land
+```
+
+Between every major artifact, run `capturing-learnings`. During execution, keep `epiphany-tabling` active. If you stop mid-work, use `create-handoff` / `resume-handoff`.
+
+## The RPIV path in detail
+
+When you choose Mode B or C, the pipeline below is the default. Each arrow is a skill invocation. Each skill produces or updates an artifact.
+
+```
+Discover → Research → Design/Blueprint → Plan → Implement → Validate → Review → Commit → Land
+```
 
 ### 1. Discover — capture intent
 
@@ -121,6 +155,7 @@ Each arrow is a skill invocation. Each skill produces or updates an artifact. No
 - Apply `verification-before-completion` discipline: no success claim without fresh verification evidence.
 - If a session ends mid-implementation, run `/skill:create-handoff`.
 - If code reality diverges from the plan, surface it via implement's mismatch flow or run `/skill:revise <plan-path>` first.
+- In mixed mode, invoke Superpowers `test-driven-development` and `subagent-driven-development` inside this phase for the inner loop.
 
 ### 6. Validate — verify against the plan
 
@@ -171,7 +206,7 @@ Each arrow is a skill invocation. Each skill produces or updates an artifact. No
 9. Status review + resolve `docs/tabled.md`
 10. Integrate (`finishing-a-development-branch`)
 
-**Integration note:** `land` is the cycle boundary RPIV does not provide. It is the most important addition this package makes.
+**Integration note:** `land` is the cycle boundary neither Superpowers nor RPIV provides. It is the most important addition this package makes.
 
 ## Monitoring the relationship
 
@@ -180,7 +215,7 @@ We intentionally deferred deciding how to track Superpowers long-term. Review mo
 - `docs/memory/monitor_upstream_evolution.md` — decision context and last review date
 - `docs/runbooks/monitor-upstream-evolution.md` — the check-in process
 
-After 2–3 projects, decide whether to keep the git peer dependency, fork Superpowers, or drop it.
+After 2–3 projects, decide whether to keep the harness-plugin arrangement, fork Superpowers, or drop the peer dependency.
 
 ## Cross-cutting practices
 
@@ -228,6 +263,7 @@ Your codebase should contain these documents and folders. They are owned by the
 
 - **Skipping `land`.** `validate` is not the finish line. Close the cycle.
 - **Carrying `docs/tabled.md` across cycles.** Resolve every entry during `land` step 9.
+- **Treating one system as the only system.** Superpowers, RPIV, and Don's closeout each have a zone of excellence. Choose deliberately.
 - **Editing source files during discover/research/design/plan.** Those skills produce artifacts; `implement` edits code.
 - **Recomposing RPIV slice boundaries.** `design`/`blueprint` owns decomposition; `plan` inherits slices 1:1.
 - **Letting verification become a rubber stamp.** Evidence first, claims second.
@@ -237,12 +273,17 @@ Your codebase should contain these documents and folders. They are owned by the
 | I want to... | Invoke |
 |---|---|
 | Onboard a repo | `/skill:setup-dons-flow` |
-| Capture intent | `/skill:discover "..."` |
+| Choose a workflow mode | `/skill:dons-flow` |
+| Ideate / refine a design | `brainstorming` |
+| Capture intent (RPIV) | `/skill:discover "..."` |
 | Understand the codebase | `/skill:research <artifact-or-topic>` |
 | Compare options | `/skill:explore "..."` |
 | Design + plan separately | `/skill:design <research>` → `/skill:plan <design>` |
 | Design + plan together | `/skill:blueprint <research>` |
-| Execute the plan | `/skill:implement <plan> [Phase N]` |
+| Write a Superpowers plan | `writing-plans` |
+| Execute the plan (RPIV) | `/skill:implement <plan> [Phase N]` |
+| Execute with subagents (Superpowers) | `subagent-driven-development` |
+| Run TDD | `test-driven-development` |
 | Verify implementation | `/skill:validate <plan>` |
 | Review changes | `/skill:code-review [scope]` |
 | Commit changes | `/skill:commit` |
@@ -254,6 +295,7 @@ Your codebase should contain these documents and folders. They are owned by the
 
 ## See also
 
+- Superpowers: [obra/superpowers](https://github.com/obra/superpowers)
 - RPIV README: `@juicesharp/rpiv-pi`
 - `setup-dons-flow` — onboarding skill
 - `land` — the 10-step closeout

package/skills/setup-dons-flow/SKILL.md

@@ -5,17 +5,29 @@ description: Use when installing or onboarding @locksmithdon/dons-flow in a repo
 
 # Setup Don's Flow
 
-Onboard a repo to the integrated RPIV + Superpowers + `land` workflow. This skill checks prerequisites, detects what is already installed, creates the repo-owned conventions, and tells you what still needs to be done.
+Onboard a repo to the Don's Flow v2 triad: **Superpowers** + **RPIV** + **Don's closeout discipline**. This skill checks prerequisites, detects what is already installed, creates the repo-owned conventions, and tells you what still needs to be done.
 
 ## Announce at start
 
-> "I'm using the `setup-dons-flow` skill to onboard this repo to the integrated workflow."
+> "I'm using the `setup-dons-flow` skill to onboard this repo to Don's Flow v2."
 
 ## When to use
 
 - Right after installing `@locksmithdon/dons-flow` in a repo.
 - When you suspect prerequisites are missing.
 - When setting up a fresh repo for this workflow.
+- After switching to a new agent harness.
+
+## What Don's Flow needs
+
+| Component | What it is | How it is installed |
+|---|---|---|
+| **Superpowers** | Agentic methodology (brainstorming, TDD, subagent-driven development) | Harness plugin (Claude, Codex, Gemini, Cursor, etc.) |
+| **RPIV** | Observable delivery pipeline (`discover → ... → commit`) | `pi install npm:@juicesharp/rpiv-pi` |
+| **Pi subagent runtime** | Runtime used by RPIV | `pi install npm:@tintinweb/pi-subagents` |
+| **Don's Flow** | This package: closeout, scope control, learning capture | `pi install npm:@locksmithdon/dons-flow` |
+
+Superpowers is not an npm package and cannot be installed via `pi install` or `npm install`. It must be installed as a harness plugin.
 
 ## Process
 
@@ -39,20 +51,72 @@ If RPIV is installed, also run `/rpiv-setup` once and restart Pi to install RPIV
 
 ### Step 2: Detect Superpowers
 
-Superpowers is installed via your agent harness, not as a Pi npm package. Check one of:
+Superpowers is installed via your agent harness, not as a Pi npm package. Check the appropriate method for your harness:
 
-- **Claude Code:** `/plugin list` should show `superpowers`
-- **Codex CLI:** `/plugins` should list Superpowers
-- **Gemini CLI:** `gemini extensions list` should show it
-- **Skills directory:** `ls ~/.pi/agent/skills/` may contain Superpowers skills if they were copied manually
+**Claude Code**
+```bash
+/plugin list
+```
+Look for `superpowers`. If missing:
+```bash
+/plugin install superpowers@claude-plugins-official
+```
+Or via the Superpowers marketplace:
+```bash
+/plugin marketplace add obra/superpowers-marketplace
+/plugin install superpowers@superpowers-marketplace
+```
+
+**Codex CLI / Codex App**
+```bash
+/plugins
+```
+Search for "Superpowers" and install it.
 
-If Superpowers is not installed, ask the user which path they prefer:
+**Gemini CLI**
+```bash
+gemini extensions list
+```
+If missing:
+```bash
+gemini extensions install https://github.com/obra/superpowers
+```
+
+**Factory Droid**
+```bash
+droid plugin list
+```
+If missing:
+```bash
+droid plugin marketplace add https://github.com/obra/superpowers
+droid plugin install superpowers@superpowers
+```
+
+**OpenCode**
+```bash
+# Fetch and follow instructions from:
+# https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md
+```
+
+**Cursor**
+```bash
+/add-plugin superpowers
+```
+Or search "superpowers" in the plugin marketplace.
+
+**GitHub Copilot CLI**
+```bash
+copilot plugin list
+```
+If missing:
+```bash
+copilot plugin marketplace add obra/superpowers-marketplace
+copilot plugin install superpowers@superpowers-marketplace
+```
 
-1. **Harness plugin** (recommended for most users)
-2. **Git URL** — `pi install github:obra/superpowers` if their Pi supports git URLs
-3. **Skip for now** — the closeout workflow still works without Superpowers entry points
+If you are unsure which harness is active, ask the user. Do not guess.
 
-Record the choice in `docs/memory/MEMORY.md` if this is a long-lived project.
+If Superpowers is not installed, explain that the closeout workflow in this package still works, but the upstream Superpowers entry points (`brainstorming`, `test-driven-development`, `subagent-driven-development`) will not be available.
 
 ### Step 3: Check repo conventions
 
@@ -120,8 +184,8 @@ Seed `AGENTS.md` with a minimal entry pointing at this workflow:
 # AGENTS.md
 
 This project uses the `@locksmithdon/dons-flow` workflow:
+- Superpowers for design, planning, TDD, and subagent-driven development.
 - RPIV pipeline for discovery, research, design/plan, implement, validate, review, commit.
-- Superpowers-style scope control and verification discipline.
 - `land` skill for 10-step cycle closeout.
 
 See `docs/runbooks/` for detailed processes and `docs/memory/` for project context.
@@ -137,7 +201,7 @@ Setup status for <repo>:
 ✓ RPIV installed
 ✗ @tintinweb/pi-subagents missing — run: pi install npm:@tintinweb/pi-subagents
 ✓ Repo conventions created
-? Superpowers — not detected; install via harness plugin if desired
+✓ Superpowers detected (Claude Code plugin)
 
 Next step: /skill:dons-flow to see the workflow map.
 ```
@@ -145,7 +209,8 @@ Next step: /skill:dons-flow to see the workflow map.
 ## Anti-patterns
 
 - **Creating conventions without asking.** The repo belongs to the team; don't mutate its doc structure unilaterally.
-- **Assuming Superpowers is installed.** It is optional and harness-specific. Always detect or ask.
+- **Guessing the harness.** Always detect or ask which agent harness is in use before giving Superpowers install instructions.
+- **Treating Superpowers as optional decoration.** It is one of the three pillars of this workflow. Detect it accurately and install it if possible.
 - **Installing packages without confirmation.** Present the install commands; let the human run them.
 
 ## Integration