From 51b7064ef0a02642393bab1d2eea0f4dbd8414d2 Mon Sep 17 00:00:00 2001 From: Ogulcan Celik Date: Sun, 16 Aug 2026 01:11:09 +0300 Subject: fix: keep agent skill aligned with stable releases refs #2847 --- .githooks/pre-commit | 13 +++++++++++++ AGENTS.md | 2 ++ justfile | 11 +++++++---- skills/herdr/SKILL.md | 4 ++-- 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: -- cgit v1.2.3