fix: keep agent skill aligned with stable releases

refs #2847

4 files changed, 24 insertions, 6 deletions

diff --git a/.githooks/pre-commit b/.githooks/pre-commit
index d8b05146..166820c0 100755
--- a/.githooks/pre-commit
+++ b/.githooks/pre-commit
@@ -4,5 +4,18 @@ set -euo pipefail
 repo_root="$(git rev-parse --show-toplevel)"
 cd "$repo_root"
 
+if ! git diff --cached --quiet -- skills/herdr/SKILL.md; then
+    head_version="$(git show HEAD:Cargo.toml | sed -n 's/^version = "\(.*\)"/\1/p' | head -1)"
+    staged_version="$(git show :Cargo.toml | sed -n 's/^version = "\(.*\)"/\1/p' | head -1)"
+    staged_skill="$(git rev-parse :skills/herdr/SKILL.md 2>/dev/null || true)"
+    released_skill="$(git rev-parse "v${staged_version}:skills/herdr/SKILL.md" 2>/dev/null || true)"
+
+    if [[ "$head_version" == "$staged_version" && "$staged_skill" != "$released_skill" ]]; then
+        echo "error: skills/herdr/SKILL.md may only change in a release commit" >&2
+        echo "update it while preparing the release and stage it with the Cargo.toml version bump" >&2
+        exit 1
+    fi
+fi
+
 echo "pre-commit: running just lint"
 just lint
diff --git a/AGENTS.md b/AGENTS.md
index 221b3aff..f5ae308a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -184,6 +184,8 @@ When updating libghostty-vt, check every active patch in `vendor/libghostty-vt.p
 
 ## Docs
 
+`skills/herdr/SKILL.md` tracks the latest stable Herdr release because the unversioned `npx skills add herdrdev/herdr --skill herdr -g` command installs it from `master`. Do not update this file in feature or preview work. Review and update it only during stable release preparation, and include the change in the release commit with the `Cargo.toml` version bump. Preview builds keep the latest stable skill.
+
 Unreleased docs live in `docs/next/website/src/content/docs/`. Update those when a user-facing change needs docs before the next release. They are committed drafts but are never production website input. `docs/next/README.md` and `docs/next/CHANGELOG.md` stage root README and changelog changes.
 
 The active preview release docs live in `docs/preview/website/`. Preview CI owns this mutable snapshot and commits it atomically with `website/preview.json`; never edit it manually. Validate it with `node website/scripts/docs-preview.mjs check`.
diff --git a/justfile b/justfile
index a23c6d7d..3d2bbbb9 100644
--- a/justfile
+++ b/justfile
@@ -135,7 +135,8 @@ pre-release-check:
     just release-docs-check
     just bench-render-scale
     @echo "release review required: investigate material render-scaling regressions before publishing."
-    @echo "release review required: verify skills/herdr/SKILL.md matches the current CLI, IDs, agent lifecycle semantics, and safety guidance."
+    @echo "release review required: update skills/herdr/SKILL.md for this stable release so it matches the current CLI, IDs, agent lifecycle semantics, and safety guidance."
+    @echo "release policy: do not update skills/herdr/SKILL.md between stable releases; preview builds keep the latest stable skill."
 
 # Prepare the release commit without tagging or pushing (usage: just release-prepare 0.1.1)
 release-prepare version:
@@ -143,8 +144,10 @@ release-prepare version:
         echo "error: version must look like 0.6.6 without a v prefix"; \
         exit 1; \
     }
-    @if [ -n "$(git status --porcelain)" ]; then \
-        echo "error: commit your changes first"; \
+    @if ! git diff --quiet -- . ':(exclude)skills/herdr/SKILL.md' || \
+        ! git diff --cached --quiet -- . ':(exclude)skills/herdr/SKILL.md' || \
+        [ -n "$(git ls-files --others --exclude-standard)" ]; then \
+        echo "error: commit all changes except skills/herdr/SKILL.md first"; \
         exit 1; \
     fi
     @git fetch origin master --tags
@@ -158,7 +161,7 @@ release-prepare version:
     sed -i.bak 's/^version = ".*"/version = "{{version}}"/' Cargo.toml && rm -f Cargo.toml.bak
     cargo update -p herdr --offline
     just check
-    git add CHANGELOG.md docs/next/CHANGELOG.md Cargo.toml Cargo.lock
+    git add CHANGELOG.md docs/next/CHANGELOG.md Cargo.toml Cargo.lock skills/herdr/SKILL.md
     git diff --cached --quiet || git commit -m "release: v{{version}}"
     @echo "v{{version}} release commit prepared. Review it, then run: just release-publish {{version}}"
 
diff --git a/skills/herdr/SKILL.md b/skills/herdr/SKILL.md
index 494fe685..fafea549 100644
--- a/skills/herdr/SKILL.md
+++ b/skills/herdr/SKILL.md
@@ -125,9 +125,9 @@ Submit work through the agent surface:
 herdr agent prompt reviewer "Review the current diff and report only actionable findings." --wait --timeout 120000
 ```
 
-`agent prompt` sends text, then encoded Enter after a short delay, while honoring the pane's live bracketed-paste mode. If the agent is already `blocked`, it returns `agent_blocked` without sending input; inspect the dialog and use `agent send-keys` for a deliberate response. For normal agent work, `--wait` is enough: it waits for the first settled `idle`, `done`, or `blocked` state reached after an accepted submission. Do not repeat those defaults with `--until`.
+`agent prompt` atomically submits text and encoded Enter while honoring the pane's live bracketed-paste mode. For normal agent work, `--wait` is enough: it waits for the first settled `idle`, `done`, or `blocked` state. Do not repeat those defaults with `--until`.
 
-An accepted prompt sent from another non-working state must produce an observed lifecycle change within five seconds. Otherwise Herdr returns `agent_prompt_stalled` instead of waiting indefinitely; if the caller sets `--timeout` to five seconds or less, Herdr returns the normal `timeout` error instead. This wait tracks lifecycle state, not an individual turn; if the agent is already working, completion of the active turn may satisfy it.
+A prompt sent from a non-working state must produce an observed lifecycle change within five seconds. Otherwise Herdr returns `agent_prompt_stalled` instead of waiting indefinitely. This wait tracks lifecycle state, not an individual turn; if the agent is already working, completion of the active turn may satisfy it.
 
 Use `--until` only for a state-specific workflow, such as waiting for an already-running agent to request input: