@locksmithdon/dons-flow 2.1.2 → 2.2.0

package/README.md

@@ -22,82 +22,29 @@ None of these replaces the others. Superpowers excels at the inner loop of desig
 
 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
+### Install
 
-Superpowers is a harness plugin, not an npm package. Install it for the agent you are using:
-
-**Claude Code**
-```bash
-/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
-```
-
-**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
-
-RPIV and the Pi subagent runtime are declared as peer dependencies of this package. With npm 7+, they are installed automatically when you install `@locksmithdon/dons-flow`:
+One command installs the entire workflow:
 
 ```bash
 pi install npm:@locksmithdon/dons-flow
 ```
 
-If your Pi setup does not auto-install peer dependencies, install them explicitly:
+This single package includes:
 
-```bash
-pi install npm:@juicesharp/rpiv-pi
-pi install npm:@tintinweb/pi-subagents
-pi install npm:@locksmithdon/dons-flow
-```
+- **RPIV** skills and runtime extensions as npm dependencies.
+- **Superpowers** skills vendored directly into the package at `vendor/superpowers/skills/` (MIT licensed; see `vendor/superpowers/LICENSE`).
+- **Don's Flow** skills for closeout, scope control, and learning capture.
 
-If RPIV's `/rpiv-setup` command is available, `/skill:setup-dons-flow` runs it automatically to install RPIV's sibling plugins. Restart Pi when prompted so the new extensions load.
+If RPIV warns about missing sibling extensions during install, restart Pi once the install completes; the dependencies are already declared.
 
-### 3. Onboard the repo
+### Onboard the repo
 
 ```bash
 /skill:setup-dons-flow
 ```
 
-This checks prerequisites, detects Superpowers, and creates the repo-owned conventions listed below.
+This creates the repo-owned conventions listed below.
 
 ## Three ways to work
 
@@ -181,24 +128,25 @@ This separation lets the same workflow travel with you across repos while keepin
 
 ## Monitoring upstream evolution
 
-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.
+Superpowers, RPIV, and Don's Flow will evolve independently. The `sync-upstream` skill clones the Superpowers and RPIV repositories, diffs them against the last-synced hashes, and produces a decision report so you can choose what to incorporate into Don's Flow.
 
-- Memory: `docs/memory/monitor_upstream_evolution.md`
+- Skill: `/skill:sync-upstream`
+- Script: `scripts/sync-upstream.sh`
 - Runbook: `docs/runbooks/monitor-upstream-evolution.md`
+- Memory: `docs/memory/monitor_upstream_evolution.md`
 
-Set a monthly calendar reminder for the 13th, or run the runbook after every 2–3 completed projects.
+The default stance is to incorporate upstream improvements unless there is a clear reason not to. Run the sync monthly or after every 2–3 projects.
 
 ## Typical first use
 
-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:
+1. `pi install npm:@locksmithdon/dons-flow`.
+2. Run `/skill:setup-dons-flow` to scaffold repo conventions.
+3. 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.
+4. Close the cycle with `/skill:land`.
+5. After 2–3 projects, run `/skill:sync-upstream`.
 
 ## License
 

package/docs/conventions.md

@@ -1,4 +1,4 @@
-# Repo Conventions for RPIV + Superpowers Landing
+# Repo Conventions for Don's Flow
 
 This workflow expects a small set of project-owned documents in every repo that uses it. These are **not** part of the `@locksmithdon/dons-flow` package; they live in the codebase because they are shared by the whole team.
 
@@ -7,7 +7,6 @@ This workflow expects a small set of project-owned documents in every repo that
 ```
 docs/
   tabled.md              # Working memory for epiphanies and deferred work
-  tabled/                # Optional per-item tabled docs (keep .gitkeep)
   status.md              # Living status: Recently Completed, What's Next
   memory/
     MEMORY.md            # Index of memory entries

package/docs/memory/.upstream-last-sync.json

@@ -0,0 +1,4 @@
+{
+  "superpowers": "6fd4507659784c351abbd2bc264c7162cfd386dc",
+  "rpiv": "88f52084c408fdb50e9e57d31a80c8227f08de15"
+}

package/docs/memory/MEMORY.md

@@ -6,4 +6,5 @@ Cross-session context for `@locksmithdon/dons-flow`.
 
 | File | Type | Why it matters |
 |---|---|---|
-| [monitor_upstream_evolution.md](./monitor_upstream_evolution.md) | decision-deferred | We deferred choosing how to track Superpowers. Review monthly. |
+| [monitor_upstream_evolution.md](./monitor_upstream_evolution.md) | decision-deferred | How we track Superpowers and RPIV over time. Review monthly. |
+| [upstream-sync-2026-06-13.md](./upstream-sync-2026-06-13.md) | upstream-sync | First automated diff of Superpowers and RPIV. |

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 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`.
+- **RPIV** (`@juicesharp/rpiv-pi`) is published to npm and declared as a normal dependency. New versions are adopted by bumping `package.json`.
+- **Superpowers** (`obra/superpowers`) is not published to npm under a usable name. We vendor selected Superpowers skills directly into this package at `vendor/superpowers/skills/` and update them with `scripts/sync-upstream.sh`.
 
-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:
+The default stance is to incorporate upstream improvements into Don's Flow unless there is a clear reason not to. We will review both projects for 2–3 months before deciding whether to:
 
-1. Keep the harness-plugin arrangement.
-2. Fork Superpowers and publish it under `@locksmithdon/superpowers` as a normal npm peer dependency.
-3. Drop Superpowers integration entirely and rely on this package's ported closeout skills + RPIV's pipeline.
+1. Keep vendoring Superpowers skills.
+2. Fork Superpowers and publish it under `@locksmithdon/superpowers` as a normal npm dependency.
+3. Drop Superpowers integration entirely and rely on RPIV + Don's closeout skills.
 4. Some hybrid we haven't thought of yet.
 
 ## Why we deferred
@@ -48,5 +48,7 @@ Drop Superpowers integration if:
 ## Related
 
 - Runbook: `docs/runbooks/monitor-upstream-evolution.md`
+- Skill: `sync-upstream`
+- Script: `scripts/sync-upstream.sh`
 - Skill: `setup-dons-flow`
 - Package: `package.json` § `peerDependencies`

package/docs/memory/upstream-sync-2026-06-13.md

@@ -0,0 +1,61 @@
+# Upstream Sync: 2026-06-13
+
+type: upstream-sync
+superpowers-last: 6fd4507659784c351abbd2bc264c7162cfd386dc
+superpowers-current: 6fd4507659784c351abbd2bc264c7162cfd386dc
+rpiv-last: 88f52084c408fdb50e9e57d31a80c8227f08de15
+rpiv-current: 88f52084c408fdb50e9e57d31a80c8227f08de15
+
+## Superpowers (6fd4507659784c351abbd2bc264c7162cfd386dc → 6fd4507659784c351abbd2bc264c7162cfd386dc)
+
+Vendored skills: brainstorming,dispatching-parallel-agents,executing-plans,receiving-code-review,requesting-code-review,subagent-driven-development,systematic-debugging,test-driven-development,using-superpowers,writing-plans,writing-skills
+
+### Commits since last sync
+
+```bash
+
+```
+
+### Files changed
+
+```bash
+
+```
+
+### Decisions
+
+- **Incorporate:** _list Superpowers changes to pull into Don's Flow (already copied if in vendored list)_
+- **Add new skill to vendor list:** _new upstream skills worth including_
+- **Defer / Skip:** _changes that do not fit or are not yet needed_
+- **Notes:** _impact assessment, breaking changes, conflicts with Don's Flow skills_
+
+## RPIV (88f52084c408fdb50e9e57d31a80c8227f08de15 → 88f52084c408fdb50e9e57d31a80c8227f08de15)
+
+RPIV ships as an npm dependency. Review changes for version bumps or workflow impact.
+
+### Commits since last sync
+
+```bash
+
+```
+
+### Files changed
+
+```bash
+
+```
+
+### Decisions
+
+- **Bump dependency version:** _new RPIV version to pin in package.json_
+- **Workflow impact:** _changes that affect how Don's Flow uses RPIV skills_
+- **Defer / Skip:** _changes that do not affect Don's Flow_
+
+## Next steps
+
+1. Review the commits and diffs above.
+2. Edit the **Decisions** sections in this file.
+3. If Superpowers skills changed, the vendored copies are already updated in `vendor/superpowers/skills/`.
+4. If RPIV changed, update `package.json` dependency versions as needed.
+5. Run tests / install the package locally.
+6. Bump version, commit, push, and publish.

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

@@ -1,82 +1,111 @@
 # Runbook: Monitor Upstream Evolution
 
-Check RPIV and Superpowers monthly to decide how `@locksmithdon/dons-flow` should track them. Superpowers is a harness plugin; RPIV is an npm package.
+Check Superpowers and RPIV monthly to keep Don's Flow current with its upstream partners. Superpowers skills are vendored into the package; RPIV is an npm dependency. Both upstream repos are tracked in `vendor/`.
 
 ## Schedule
 
 - **Cadence:** Monthly, or after every 2–3 projects completed with this workflow.
-- **Duration:** 15–30 minutes.
+- **Duration:** 30–60 minutes.
 - **Owner:** Don Smith.
 
 ## Trigger
 
 - Calendar reminder on the 13th of each month.
-- After any project closeout where the dependency relationship felt awkward.
+- After any project closeout where upstream behavior felt different.
+- Before publishing a new version of `@locksmithdon/dons-flow`.
 
 ## Steps
 
-### 1. Check RPIV
+### 1. Run the upstream sync script
 
-Visit https://github.com/juicesharp/rpiv-mono and look at:
+From the root of the Don's Flow repo:
 
-- **Releases / CHANGELOG** — new versions of `@juicesharp/rpiv-pi`.
-- **Skills** — has RPIV added a `land`, `closeout`, `retro`, or `as-built` skill? If so, evaluate whether our port is still needed.
-- **Implement / validate / code-review** — have these skills changed in ways that affect our closeout sequence?
-- **Onboarding** — has RPIV added smoother setup commands we should mirror?
+```bash
+./scripts/sync-upstream.sh
+```
 
-Record findings in `docs/memory/monitor_upstream_evolution.md` under a dated heading.
+This clones or pulls:
 
-### 2. Check Superpowers
+- `https://github.com/obra/superpowers` → `vendor/superpowers-source`
+- `https://github.com/juicesharp/rpiv-mono` → `vendor/rpiv-mono`
 
-Visit https://github.com/obra/superpowers and look at:
+It then copies selected Superpowers skills into `vendor/superpowers/skills/`, compares each repo's current HEAD against the last-synced hash stored in `docs/memory/.upstream-last-sync.json`, and writes a dated report to `docs/memory/upstream-sync-YYYY-MM-DD.md`.
 
-- **Releases / RELEASE-NOTES.md** — new versions.
-- **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?
+If `jq` is missing, install it first:
 
-Record findings in `docs/memory/monitor_upstream_evolution.md` under the same dated heading.
+```bash
+brew install jq        # macOS
+apt-get install jq     # Debian/Ubuntu
+```
 
-### 3. Check our own usage
+### 2. Review the generated report
 
-Review recent projects that used this workflow:
+Open the latest report:
 
-- Did we use Superpowers-specific entry points (`brainstorming`, `writing-plans`, `subagent-driven-development`) or RPIV entry points (`discover`, `blueprint`, `implement`)?
-- 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?
+```bash
+ls docs/memory/upstream-sync-*.md | tail -1
+```
 
-Sources:
-- Recent `docs/retros/` files.
-- Recent `docs/changes/` files.
-- `docs/tabled.md` history.
+For each upstream project, the report shows:
 
-### 4. Decide or defer
+- Last-synced and current commit hashes.
+- Commits since the last sync.
+- Files changed and diff stats.
+- Empty **Decisions** sections.
 
-Ask:
+### 3. Decide what to incorporate
 
-1. Is Superpowers on npm yet?
-2. Does RPIV now provide closeout/landing?
-3. Are we actively hurt by the current dependency setup?
-4. Would a fork save more friction than it costs?
+Default stance: **incorporate upstream improvements** unless there is a clear reason not to.
 
-If the answer to any of 1–3 is **yes**, consider updating `package.json` and the workflow.
+For each change, label it:
 
-If the answer is **no**, bump `next-review` by one month and keep monitoring.
+- **Incorporate** — pull it into Don's Flow now.
+- **Defer** — relevant, but wait for the next cycle or a triggering project.
+- **Skip** — not relevant to Don's Flow.
 
-### 5. Capture the decision
+Edit the report in place with your decisions and any impact notes.
 
-If you make a change:
-- Update `docs/memory/monitor_upstream_evolution.md`.
-- Write a brief note in `docs/changes/` if the package behavior changed.
-- Update `README.md` and `skills/dons-flow/SKILL.md` if install instructions changed.
+### 4. Apply incorporated changes
 
-If you defer:
-- Update `last-reviewed` and `next-review` in `docs/memory/monitor_upstream_evolution.md`.
-- Add one paragraph summarizing the month's observations.
+Common actions:
+
+- **Superpowers skill changed** — the sync script already copied the selected skills into `vendor/superpowers/skills/`. Review and commit those changes.
+- **Superpowers adds a new skill** — add it to the `SUPERPOWERS_SKILLS` list in `scripts/sync-upstream.sh` if you want to vendor it.
+- **RPIV version changed** — bump the RPIV dependency versions in `package.json`.
+- **Workflow instructions changed** — update `README.md`, `skills/setup-dons-flow/SKILL.md`, and `skills/dons-flow/SKILL.md`.
+
+### 5. Update long-term memory
+
+Open `docs/memory/monitor_upstream_evolution.md` and:
+
+- Update `last-reviewed` and `next-review` dates.
+- Add a paragraph summarizing this month's sync and any deferred decisions.
+- Update decision criteria if your thinking has changed.
+
+### 6. Release Don's Flow
+
+If you applied changes:
+
+1. Bump the version in `package.json`.
+2. Write a brief `docs/changes/` entry if the package behavior changed.
+3. Commit and push.
+4. Publish to npm.
+
+If you deferred everything:
+
+1. Still commit the new sync report so the next run has a baseline.
+2. Update `last-reviewed` and `next-review`.
 
 ## Outputs
 
+- Updated `docs/memory/upstream-sync-YYYY-MM-DD.md`.
 - Updated `docs/memory/monitor_upstream_evolution.md`.
-- Optional `docs/changes/` entry if the package changed.
-- Optional update to install docs.
+- Updated `docs/memory/.upstream-last-sync.json`.
+- Optional `docs/changes/` entry.
+- Optional new version of `@locksmithdon/dons-flow` on npm.
+
+## Anti-patterns
+
+- **Syncing without deciding.** The script surfaces changes; a human must decide what to do.
+- **Updating `.last-sync.json` without applying changes.** This hides skipped changes from future diffs.
+- **Incorporating blindly.** Upstream changes may conflict with Don's Flow conventions. Review first.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@locksmithdon/dons-flow",
-  "version": "2.1.2",
-  "description": "Don's Flow v2 — a developer-specific Pi Agent workflow built on RPIV's observable pipeline, Superpowers' discipline, and a structured landing closeout.",
+  "version": "2.2.0",
+  "description": "Don's Flow v2 — a single Pi Agent workflow package combining RPIV's observable pipeline, Superpowers' discipline, and Don's landing closeout.",
   "keywords": [
     "pi-package",
     "pi-extension",
@@ -29,19 +29,35 @@
   },
   "files": [
     "skills/",
+    "vendor/superpowers/",
     "docs/",
+    "scripts/",
     "README.md",
     "LICENSE"
   ],
   "pi": {
     "skills": [
-      "./skills"
+      "./skills",
+      "./vendor/superpowers/skills"
     ]
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "dependencies": {
+    "@juicesharp/rpiv-pi": "*",
     "@tintinweb/pi-subagents": "*",
-    "@juicesharp/rpiv-pi": "*"
+    "@juicesharp/rpiv-ask-user-question": "*",
+    "@juicesharp/rpiv-todo": "*",
+    "@juicesharp/rpiv-advisor": "*",
+    "@juicesharp/rpiv-i18n": "*",
+    "@juicesharp/rpiv-web-tools": "*",
+    "@juicesharp/rpiv-args": "*",
+    "@juicesharp/rpiv-workflow": "*",
+    "yaml": "*",
+    "typebox": "*",
+    "jiti": "*",
+    "@standard-schema/spec": "*"
   },
   "scripts": {
     "lint": "echo 'No lint configured yet'",

package/scripts/sync-upstream.sh

@@ -0,0 +1,193 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# sync-upstream.sh
+#
+# Update Don's Flow's vendored Superpowers skills and track upstream changes.
+# RPIV is installed as a normal npm dependency, so this script only monitors
+# its repo for changes that might affect dependency versions or workflow.
+#
+# Usage:
+#   ./scripts/sync-upstream.sh
+#
+# Outputs:
+#   vendor/superpowers-source/  git mirror of obra/superpowers
+#   vendor/superpowers/skills/  selected Superpowers skills vendored into Don's Flow
+#   vendor/superpowers/LICENSE  Superpowers MIT license
+#   docs/memory/upstream-sync-YYYY-MM-DD.md  decision report
+#   docs/memory/.upstream-last-sync.json     last-synced commit hashes
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$REPO_ROOT"
+
+SOURCE_DIR="$REPO_ROOT/vendor/superpowers-source"
+VENDOR_DIR="$REPO_ROOT/vendor/superpowers"
+VENDOR_SKILLS_DIR="$VENDOR_DIR/skills"
+MEMORY_DIR="$REPO_ROOT/docs/memory"
+TODAY="$(date +%Y-%m-%d)"
+REPORT_FILE="$MEMORY_DIR/upstream-sync-$TODAY.md"
+LAST_SYNC_FILE="$MEMORY_DIR/.upstream-last-sync.json"
+
+# Skills from Superpowers that Don's Flow vendors directly.
+# Conflicting skills (finishing-a-development-branch, using-git-worktrees,
+# verification-before-completion) are intentionally excluded because Don's Flow
+# provides its own integrated versions.
+SUPERPOWERS_SKILLS=(
+  brainstorming
+  dispatching-parallel-agents
+  executing-plans
+  receiving-code-review
+  requesting-code-review
+  subagent-driven-development
+  systematic-debugging
+  test-driven-development
+  using-superpowers
+  writing-plans
+  writing-skills
+)
+
+mkdir -p "$SOURCE_DIR" "$VENDOR_SKILLS_DIR" "$MEMORY_DIR"
+
+# Ensure last-sync tracking file exists
+if [[ ! -f "$LAST_SYNC_FILE" ]]; then
+  echo '{}' > "$LAST_SYNC_FILE"
+fi
+
+# Read last-synced hashes
+SUPERPOWERS_LAST="$(jq -r '.superpowers // ""' "$LAST_SYNC_FILE")"
+RPIV_LAST="$(jq -r '.rpiv // ""' "$LAST_SYNC_FILE")"
+
+sync_repo() {
+  local name="$1"
+  local url="$2"
+  local dir="$3"
+
+  if [[ -d "$dir/.git" ]]; then
+    echo "Updating $name..." >&2
+    git -C "$dir" fetch origin --quiet
+    git -C "$dir" pull origin --quiet
+  else
+    echo "Cloning $name..." >&2
+    git clone --quiet "$url" "$dir"
+  fi
+
+  git -C "$dir" rev-parse HEAD
+}
+
+SUPERPOWERS_CURRENT="$(sync_repo "Superpowers" "https://github.com/obra/superpowers" "$SOURCE_DIR")"
+
+# Copy selected Superpowers skills into the package
+for skill in "${SUPERPOWERS_SKILLS[@]}"; do
+  if [[ -d "$SOURCE_DIR/skills/$skill" ]]; then
+    rm -rf "$VENDOR_SKILLS_DIR/$skill"
+    cp -R "$SOURCE_DIR/skills/$skill" "$VENDOR_SKILLS_DIR/$skill"
+  else
+    echo "Warning: Superpowers skill '$skill' not found" >&2
+  fi
+done
+
+# Copy attribution
+cp "$SOURCE_DIR/LICENSE" "$VENDOR_DIR/LICENSE"
+
+# For RPIV, just track the upstream repo for release notes / workflow changes.
+# The actual RPIV skills ship through the npm dependency chain.
+RPIV_CURRENT="$(sync_repo "RPIV" "https://github.com/juicesharp/rpiv-mono" "$REPO_ROOT/vendor/rpiv-mono")"
+
+# Build report
+cat > "$REPORT_FILE" <<EOF
+# Upstream Sync: $TODAY
+
+type: upstream-sync
+superpowers-last: ${SUPERPOWERS_LAST:-none}
+superpowers-current: $SUPERPOWERS_CURRENT
+rpiv-last: ${RPIV_LAST:-none}
+rpiv-current: $RPIV_CURRENT
+
+## Superpowers ($SUPERPOWERS_LAST → $SUPERPOWERS_CURRENT)
+
+Vendored skills: $(IFS=,; echo "${SUPERPOWERS_SKILLS[*]}")
+
+### Commits since last sync
+
+\`\`\`bash
+$(if [[ -n "$SUPERPOWERS_LAST" ]]; then
+  git -C "$SOURCE_DIR" log --oneline "$SUPERPOWERS_LAST..$SUPERPOWERS_CURRENT" -- || true
+else
+  git -C "$SOURCE_DIR" log --oneline -20 -- || true
+fi)
+\`\`\`
+
+### Files changed
+
+\`\`\`bash
+$(if [[ -n "$SUPERPOWERS_LAST" ]]; then
+  git -C "$SOURCE_DIR" diff --stat "$SUPERPOWERS_LAST..$SUPERPOWERS_CURRENT" -- || true
+else
+  echo "First sync — review the repository structure and recent commits."
+fi)
+\`\`\`
+
+### Decisions
+
+- **Incorporate:** _list Superpowers changes to pull into Don's Flow (already copied if in vendored list)_
+- **Add new skill to vendor list:** _new upstream skills worth including_
+- **Defer / Skip:** _changes that do not fit or are not yet needed_
+- **Notes:** _impact assessment, breaking changes, conflicts with Don's Flow skills_
+
+## RPIV ($RPIV_LAST → $RPIV_CURRENT)
+
+RPIV ships as an npm dependency. Review changes for version bumps or workflow impact.
+
+### Commits since last sync
+
+\`\`\`bash
+$(if [[ -n "$RPIV_LAST" ]]; then
+  git -C "$REPO_ROOT/vendor/rpiv-mono" log --oneline "$RPIV_LAST..$RPIV_CURRENT" -- || true
+else
+  git -C "$REPO_ROOT/vendor/rpiv-mono" log --oneline -20 -- || true
+fi)
+\`\`\`
+
+### Files changed
+
+\`\`\`bash
+$(if [[ -n "$RPIV_LAST" ]]; then
+  git -C "$REPO_ROOT/vendor/rpiv-mono" diff --stat "$RPIV_LAST..$RPIV_CURRENT" -- || true
+else
+  echo "First sync — review the repository structure and recent commits."
+fi)
+\`\`\`
+
+### Decisions
+
+- **Bump dependency version:** _new RPIV version to pin in package.json_
+- **Workflow impact:** _changes that affect how Don's Flow uses RPIV skills_
+- **Defer / Skip:** _changes that do not affect Don's Flow_
+
+## Next steps
+
+1. Review the commits and diffs above.
+2. Edit the **Decisions** sections in this file.
+3. If Superpowers skills changed, the vendored copies are already updated in \`vendor/superpowers/skills/\`.
+4. If RPIV changed, update \`package.json\` dependency versions as needed.
+5. Run tests / install the package locally.
+6. Bump version, commit, push, and publish.
+EOF
+
+# Update last-sync tracking
+jq -n \
+  --arg superpowers "$SUPERPOWERS_CURRENT" \
+  --arg rpiv "$RPIV_CURRENT" \
+  '{superpowers: $superpowers, rpiv: $rpiv}' > "$LAST_SYNC_FILE"
+
+echo ""
+echo "Upstream sync complete."
+echo "Report: $REPORT_FILE"
+echo "Last-sync tracking: $LAST_SYNC_FILE"
+echo ""
+echo "Current hashes:"
+echo "  Superpowers: $SUPERPOWERS_CURRENT"
+echo "  RPIV:        $RPIV_CURRENT"
+echo ""
+echo "Note: vendor/superpowers-source/ and vendor/rpiv-mono/ are gitignored."
+echo "      Vendored Superpowers skills are in vendor/superpowers/skills/ and should be committed."