| name | rv:update-version |
| install | true |
| description | Check whether the installed riverflow framework is out of date against the latest on GitHub, and offer to update. Canonical trigger is the prefix "rv:update-version". Clones https://github.com/phidn/riverflow into a temp dir, reads its docs/framework/VERSION, semver-compares it with the version installed in this repo, shows the changelog delta, and — only if the user confirms — copies the newer framework (templates included) and skills over (never touching the user's own docs instances). Use when the user types "rv:update-version" or otherwise asks to check/apply riverflow updates (e.g. "is riverflow up to date?", "update riverflow", "/rv:update-version"). |
rv:update-version
Tells an installed repo whether its riverflow framework is behind upstream, shows what
changed, and — on confirmation — applies the update. The source of truth for "latest" is the
Git repo itself (no registry, no infra). See ADR-0003.
The version lives at docs/framework/VERSION, namespaced under the framework dir so it travels
with the install and never collides with the host project's own version.
When to use
Canonical trigger: the prefix rv:update-version. Also fires on natural phrasing — "check for
riverflow updates", "is riverflow up to date?", "update riverflow", "/rv:update-version". Do NOT run
on every session — only when triggered.
Procedure
1. Find the installed version
Look for the local VERSION file in these candidate paths, first match wins (covers the standard
and embedded install shapes — same detection style as rv:recap):
docs/framework/VERSION (standard riverflow install)framework/VERSION (embedded install)VERSION (last resort)
If none exists → this repo predates self-versioning. Treat the local version as 0.0.0 and tell
the user their install is from before versioning existed (so any upstream version is an update).
Read the file; trim whitespace. Call it LOCAL.
2. Fetch the latest version from GitHub
Shallow-clone into a temp dir, read the remote VERSION, then clean up. Do not leave the temp dir
behind.
TMP="$(mktemp -d)"
git clone --depth 1 https://github.com/phidn/riverflow "$TMP" >/dev/null 2>&1 \
|| { echo "clone-failed"; }
REMOTE="$(tr -d '[:space:]' < "$TMP/docs/framework/VERSION" 2>/dev/null)"
echo "REMOTE=$REMOTE"
Keep $TMP around until step 4 (you reuse its files to show the changelog and to apply the
update). If the clone fails (no network / no git), report that and stop — do not guess.
3. Compare (semver) and report
LATEST="$(printf '%s\n%s\n' "$LOCAL" "$REMOTE" | sort -V | tail -n1)"
LOCAL = REMOTE → up to date. Report the version and stop (delete $TMP).LOCAL = REMOTE is false and LATEST = REMOTE → update available (LOCAL → REMOTE).- otherwise (
LATEST = LOCAL, versions differ) → local is ahead of upstream (a dev/unreleased
copy). Report it, no action needed.
When an update is available, show the user what changed: read the upstream changelog at
$TMP/docs/framework/CHANGELOG.md and quote the entries newer than LOCAL (every section
above the ## [LOCAL] heading). This is the value — the version number alone is not enough.
Then read out a short block, e.g.:
riverflow: 0.1.0 installed → 0.2.0 available
What's new:
0.2.0 — Added: retro template; Changed: intake Output block adds a Proof line
...
Update now? (copies framework + templates + skills; leaves your docs/ instances untouched)
4. Apply the update — only on explicit confirmation
Updating is the irreversible part. Ask first; do not auto-apply. When the user confirms, copy
only the framework (templates ride inside it at docs/framework/templates/) and the shipped
skills from $TMP — never the example instances
(docs/decisions/, docs/stories/, docs/plans/ — or docs/specs/ in a pre-0.3.0 install —
docs/wiki/, docs/backlogs/, docs/worklogs/), which hold the user's own work.
Crossing 0.3.0: the framework renamed spec → plan (docs/specs/ → docs/plans/, template
spec.md → plan.md) and dropped the task type. After copying, point the migration out and
offer to git mv docs/specs docs/plans and remove the stale docs/templates/{spec,task}.md —
only with the user's confirmation, since it touches their instances. See the 0.3.0 CHANGELOG
entry for the full migration note.
Crossing 0.6.0: templates moved from the top-level docs/templates/ to docs/framework/templates/.
The copy below brings the new templates in inside docs/framework/, so the old top-level
docs/templates/ is left orphaned — the cleanup line removes it. Templates are riverflow-owned
(the user copies but never authors them), so this is safe; only run it once, when the old dir
still exists.
cp -R "$TMP/docs/framework/." docs/framework/
for d in "$TMP"/.claude/skills/*/; do
grep -qE '^install:[[:space:]]*true\b' "$d/SKILL.md" 2>/dev/null || continue
name=$(basename "$d")
mkdir -p ".claude/skills/$name"
cp -R "$d." ".claude/skills/$name/"
done
[ -d docs/templates ] && rm -rf docs/templates
- This overwrites the framework docs (templates included) and the riverflow skills (the parts the
user does not author) and bumps
docs/framework/VERSION to REMOTE as a side effect of copying it.
- CLAUDE.md: do not blindly overwrite — the host may have customized it. If the upstream
CLAUDE.md changed, tell the user and offer to show a diff rather than clobbering theirs.
- If the changelog lists a MAJOR bump (a breaking convention change), call that out explicitly
and point the user at the relevant changelog section before/after applying — they may need to
migrate existing artifacts.
5. Clean up + confirm
rm -rf "$TMP"
Summarize: old version → new version, which directories were refreshed, and anything (CLAUDE.md,
a MAJOR migration) left for the user to handle. Offer to write a worklog recording the update
(lane tiny, input_type: maintenance). Don't commit/push on your own — ask.
Boundaries
- Read-only check by default. The version check never modifies anything; only step 4 writes,
and only after the user confirms.
- Never overwrite the user's docs instances — only the framework (templates included) and the
skills are riverflow's to update.
- Always delete the temp clone, even on failure.
- If
git or the network is unavailable, say so plainly — do not fabricate a version.
