- Commands block's inline comment on `npx skills add` still said
"symlink this repo into every detected harness's skill dir" — the
exact misconception the PR set out to correct. Rewrite to describe
the frozen-copy behavior and point at the Rules section for the
full explanation.
- Structure section had SKILL.md listed twice (the original line 6
entry plus a new line 13 entry added in this PR). Fold the
SKILL-original.md context into line 6 and drop the duplicate.
AGENTS.md said "edits in the working tree propagate live to every harness"
after `npx skills add . -g -y`, but the install actually drops a real
(frozen-at-install-time) copy at ~/.agents/skills/<name>/ and per-host
symlinks point at *that copy*, not at the working tree. Clarify the
mechanism and offer two ways forward: re-run `npx skills add` to sync,
or replace the install copy with a working-tree symlink for live-edit.
Also fill in two gaps a fresh agent hits on entry:
- `uv run pytest` commands for the ~89-file test suite (no test runner
was documented before)
- Python 3.12+ / `uv` / `.venv/` convention
- Brief doc map: CONFIGURATION.md, SKILL.md vs SKILL-original.md,
CHANGELOG.md / release-notes.md, HERMES_SETUP.md
Documents the cascade pattern surfaced during this session's install-modernization
arc: a `test_sync_cache_path_uses_skill_version` test asserted that a hardcoded
version pin in `sync.sh` matched the version frontmatter in SKILL.md. When a
release bumped SKILL.md, every open PR's CI failed simultaneously on the
unrelated stale-pin assertion. Affected at least 5 PRs across the 2026-05-13
to 2026-05-15 window (#400, #390, #392, and two others) plus required hotfix
PR #397 to unblock the queue.
The permanent fix shipped in PR #405 (deleted sync.sh + the test). This doc
captures the design lesson so the pattern doesn't reappear: don't write
consistency tests that read two files and assert one matches a value derived
from the other. Either derive at runtime from a single source of truth, or
self-skip / merge-base-scope the test so deletion is a non-event.
Created via /ce-compound. Includes:
- docs/solutions/workflow-issues/release-consistency-test-cascade-2026-05-16.md
(the new learning — first entry under docs/solutions/)
- CONCEPTS.md (new — 4 entries: Skill, Engine, Harness, Beta channel,
capturing project-specific vocabulary that surfaced across the session)
- AGENTS.md (added one-line Structure entries surfacing docs/solutions/ and
CONCEPTS.md so fresh agents discover them)
- docs/plans/2026-04-22-{002,003,005,006}-*-plan.md (added deprecation banner
to each, pointing readers at PR #405 and the new docs/solutions entry —
these 4 historical plans still reference the deleted sync.sh inline)
Also: closed PR #379 (j-sperling's workaround for the same cascade,
superseded by PR #405's permanent fix).
Mirrors the multi-harness reframing of the project itself. CLAUDE.md is
Claude-Code-specific by name; AGENTS.md is the multi-harness convention
that Codex, Cursor, Gemini CLI, GitHub Copilot, and most other Agent
Skills hosts also read. The canonical content belongs in the file
multi-harness tooling expects.
git mv preserves history — the Orientation section and everything else
that was in CLAUDE.md is now tracked under AGENTS.md, with full blame
continuity. The new CLAUDE.md is a one-line `@AGENTS.md` reference so
Claude Code continues to load the content (it follows @ references).
Codex CLI reads AGENTS.md for repo-level context the way Claude Code reads CLAUDE.md. Delegate to the existing CLAUDE.md so both harnesses share one source of project instructions.
Julius Smith