Problem
Shared skills assumed PLUGIN_ROOT or CLAUDE_PLUGIN_ROOT existed. Codex can load a skill without either variable, so a helper path could collapse to an invalid root-level /scripts path. See references/runtime-compatibility.md:10.
Change brief · Git Workflow v2.5.2
PR #23 — Git Workflow resources now work in Codex
The package resolves helpers from the skill that was actually loaded, keeps Claude compatibility, and turns review requests into identifiable desktop notifications and decision-ready HTML.
Executive answer
Root cause
Executable resources lived at package root while the runtime reliably exposes the loaded skill location. Instructions did not treat the physical SKILL.md path as the starting point. See skills/review-watch/SKILL.md:16.
Fix
Deterministic helpers now live beside their owning skill. SKILL_DIR is authoritative; package-wide roots are derived only when necessary, and root scripts remain compatibility wrappers.
Verdict
Ready for owner review. Installed-plugin, checkout-local, Claude fallback, paths-with-spaces, wrapper, notification, queue, HTML, status, SARIF, setup, and update checks passed at this snapshot.
Business rules
| Condition | Decision | Observable result |
|---|---|---|
| The host exposes the loaded skill path | Resolve resources from SKILL_DIR | The helper comes from the exact plugin or checkout that loaded the skill. |
| The loaded path is unavailable | Try verified PLUGIN_ROOT, then CLAUDE_PLUGIN_ROOT | Existing Claude and integration flows remain compatible. |
| A new review-request SHA appears | Queue and notify once | The banner identifies repository, PR, author, and title; the same SHA stays quiet. |
| A clean reviewed SHA has no blocking findings | Approve or comment as policy allows, then create the brief | The human receives a “Ready for merge” notification and a self-contained HTML decision brief. |
Configuration remains canonical under .git-workflow; legacy .claude files are read-only fallbacks. Review posting still follows review.postToGitHub. See references/runtime-compatibility.md:19 and skills/review-watch/SKILL.md:127.
How the workflow behaves
The daemon deliberately stays lightweight: one GraphQL query discovers up to 50 PRs, de-duplicates by head SHA, queues, and notifies. Review and HTML generation happen in the active session. See skills/review-watch/scripts/review-watch.sh:115 and skills/review-watch/SKILL.md:91.
Observed notification evidence
Observed on macOS. Both banners were emitted by skills/review-watch/scripts/notify.sh. Linux uses the desktop’s native notify-send presentation. The generic notifier interface remains notify.sh "<title>" "<message>".
Focused before and after
Resource resolution
The same rule now applies to setup, update, status, review, review-watch, and change-brief.
Before
python3 "${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/validate-self-contained-html.py" index.html
# With neither variable:
/scripts/validate-self-contained-html.pyAfter
python3 "{SKILL_DIR}/scripts/validate-self-contained-html.py" index.html
# SKILL_DIR is the physical directory of the loaded skill.
# Host variables are verified fallbacks only.Notifications and queue metadata
The watcher now carries the author from GitHub through console output, queue state, and both notifications.
Before
gh search prs --json ... headRefOid title: Review requested body: test
After
gh api graphql # repo, PR, title, URL, author, SHA title: owner/repo · PR #42 body: @alice — Fix login redirect
Local Codex discovery
The checkout exposes all 19 shared skills without copying them into a global directory.
Before
.agents/skills (missing — checkout-local Codex discovery was unavailable)
After
.agents/skills -> ../skills $review-watch --doctor $change-brief 23
Risk and delivery
Main risk
An incorrectly derived path could execute the wrong helper or make a skill fail. Physical file verification, paths-with-spaces coverage, and the ban on silent root-wrapper fallback reduce that risk.
Rollout
Version 2.5.2 can run as an installed plugin or through checkout-local discovery. Users should enable only one mode per session to avoid duplicate skills.
Rollback
Reinstall 2.5.1 or revert the PR commits. Root wrappers preserve existing command paths, and no data migration is required.
Verification
| Evidence | Result | What it proves |
|---|---|---|
bash scripts/validate.sh | Passed | Manifests, wrappers, hooks, skill resources, watcher, queue, HTML, state, synchronization, status, and agents. |
| Installed Codex plugin smoke | Passed | $review-watch --doctor returned RESULT: ready and daemon-command resolved the installed absolute path. |
| Checkout-local Codex smoke | Passed | .agents/skills exposed the same 19 skills in a fresh session. |
| Notification tests | Passed | Exact title/body, nullable author fallback, old queue compatibility, malformed-record rejection, and SHA de-duplication without system notifications. |
Changed areas
Show the snapshot inventory
- Skill-local scripts and assets
- Root compatibility wrappers
- Runtime compatibility contract
- Codex plugin manifest
- Checkout-local discovery symlink
- Generated Codex agents
- Review event and SARIF helpers
- Review Watch daemon and notifier
- Change Brief HTML validator
- Status HTML renderer
- Setup/update synchronizer
- Claude/Codex installation docs
- Version 2.5.2 metadata
- Deterministic regression tests
Decision
Claude and Codex now execute the same workflow package.
The loaded skill path is the source of truth, compatibility wrappers remain available, review notifications identify the work and author, and a clean PR produces a decision-ready HTML artifact.