Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
refactor(plugin): adopt Claude's canonical manifest layout, convention-only discovery (#3431)
Maximilian Roos6c122a5d085f
diff --git a/CLAUDE.md b/CLAUDE.mdindex bf2402b56..914e6ebd6 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -49,7 +49,7 @@ Design proposals live in `design/` and are review-only: open a PR to discuss, th## Plugin Layout-Per-tool layout and path resolution (Claude/Codex/Gemini), the Codex no-hooks re-enablement conditions, the accepted `wt-switch-create` tradeoff, and `test_plugin_layout_is_consolidated`: `plugins/worktrunk/CLAUDE.md`.+Per-tool layout and path resolution (Claude/Codex/Gemini), the convention-only Claude manifest, the Codex inline-hooks rationale, the accepted `wt-switch-create` tradeoff, and `test_plugin_layout_is_consolidated`: `plugins/worktrunk/CLAUDE.md`.## Data Safetydiff --git a/plugins/worktrunk/plugin.json b/plugins/worktrunk/.claude-plugin/plugin.jsonsimilarity index 76%rename from plugins/worktrunk/plugin.jsonrename to plugins/worktrunk/.claude-plugin/plugin.jsonindex 9c74683d7..ec82a3411 100644--- a/plugins/worktrunk/plugin.json+++ b/plugins/worktrunk/.claude-plugin/plugin.json@@ -3,10 +3,5 @@"description": "Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows. This plugin provides configuration guidance (LLM commit messages, project hooks, worktree paths) and automatic activity tracking (π€/π¬ indicators in `wt list` showing active Claude sessions).","author": {"name": "Worktrunk"- },- "hooks": "./hooks/hooks.json",- "skills": [- "./skills/worktrunk",- "./skills/wt-switch-create"- ]+ }}diff --git a/plugins/worktrunk/CLAUDE.md b/plugins/worktrunk/CLAUDE.mdindex 4a0d6ad96..5a5339ff8 100644--- a/plugins/worktrunk/CLAUDE.md+++ b/plugins/worktrunk/CLAUDE.md@@ -16,14 +16,14 @@ worktrunk/ β repo root = marketplace rootβββ hooks/hooks.json β Gemini activity hooks (call the wt.sh below)βββ skills -> (this dir) β Gemini reads ${extensionPath}/skills = repo-root skills/βββ plugins/worktrunk/ β plugin root (Claude + Codex resolve source here)- βββ plugin.json β Claude manifest (NO .claude-plugin/ wrapper β- β the wrapper is marketplace-root-only)+ βββ .claude-plugin/plugin.json β Claude manifest (metadata only β NO `hooks`+ β or `skills` keys; components load by+ β convention, see below)βββ .codex-plugin/plugin.json β Codex manifest (Codex's required wrapper)- βββ hooks/hooks.json β Claude activity + WorktreeCreate/Remove hooks- β (the conventional path Claude Code's loader- β discovers β a Claude-scoped filename is NOT- β honored by the string-path override, see #3417;- β Codex is kept off it by its inline manifest, #3362)+ βββ hooks/hooks.json β Claude activity + WorktreeCreate/Remove hooks,+ β discovered by convention at this exact path+ β (#3417; Codex is kept off it by its inline+ β manifest, #3362)βββ hooks/wt.sh β canonical hook shim; Claude reaches it viaβ $CLAUDE_PLUGIN_ROOT, Codex via $PLUGIN_ROOT,β Gemini via@@ -37,14 +37,22 @@ worktrunk/ β repo root = marketplace rootPath resolution differs by tool, all verified end-to-end against the real CLIs:-- **Claude**: `.claude-plugin/marketplace.json` `source: "./plugins/worktrunk"`.- Claude reads `plugins/worktrunk/plugin.json` (at the plugin root, *not* a- `.claude-plugin/` subdir). `skills` paths in `plugin.json` resolve from the- plugin root, so `./skills/worktrunk` follows the `skills` symlink to the- repo-root `skills/worktrunk`. Hooks are different: Claude's loader discovers- them by **convention** at `hooks/hooks.json` and does not honor the- string-path `hooks` override for plugin loads, so the file must sit at that- conventional path (#3417) even though `plugin.json` still names it.+- **Claude** (claude-cli 2.1.207): `.claude-plugin/marketplace.json` `source:+ "./plugins/worktrunk"`. Claude reads+ `plugins/worktrunk/.claude-plugin/plugin.json` β the same wrapper convention+ as the marketplace root, and the only manifest location `claude plugin+ validate` accepts (a bare `plugin.json` at the plugin root loads through an+ undocumented fallback but fails validation). Components load by+ **convention**, and the manifest must not name them:+ - Hooks are discovered at `hooks/hooks.json`. The loader does not honor the+ string-path `hooks` manifest override for plugin loads, so a renamed file+ silently loads nothing (#3417) and a `hooks` key pointing at the+ conventional path is dead config that can only mask a mislocated file.+ - Skills are auto-discovered by scanning `skills/` for `<dir>/SKILL.md`; a+ `skills` manifest array only *adds* directories to that scan, so listing+ the defaults is redundant. The installer dereferences the `skills` symlink+ into a real directory in the install cache.+`$CLAUDE_PLUGIN_ROOT` is the plugin root.- **Codex**: `.agents/plugins/marketplace.json` `source` object`{ "source": "local", "path": "./plugins/worktrunk" }`. Codex reads@@ -55,10 +63,12 @@ Path resolution differs by tool, all verified end-to-end against the real CLIs:directly and `hooks/hooks.json` (repo root) calls the canonical shim at`${extensionPath}/plugins/worktrunk/hooks/wt.sh`. No symlink or copy.-Each Claude skill directory must be listed in `plugin.json`'s `skills` array-(Claude has no auto-discovery β `test_plugin_layout_is_consolidated` enforces-that every repo-root skill is listed); Codex and Gemini pick up the whole-`skills/` dir (accepted tradeoff β see Known Limitations below).+All three tools pick up the whole `skills/` directory (Claude and Codex through+the symlink, Gemini directly), so a new repo-root skill ships everywhere with+no manifest change β provided its directory contains a `SKILL.md`+(`test_plugin_layout_is_consolidated` enforces that; a directory without one is+silently ignored). Claude-only skills reach the other tools too (accepted+tradeoff β see Known Limitations below).## Known Limitations@@ -77,10 +87,9 @@ The π¬ transitions overlap deliberately: `Notification` covers the documented### Codex activity hooks (marker persists after session end)-The Claude manifest carries `hooks: "./hooks/hooks.json"` (a path); the Codex manifest carries `hooks` as an **inline object**, `{ "hooks": { β¦ } }`, embedding a Codex-tailored hooks file directly. The distinction is deliberate:+Claude's hooks live in the standalone `hooks/hooks.json` its loader discovers by convention (see Directory Layout above); the Codex manifest carries `hooks` as an **inline object**, `{ "hooks": { β¦ } }`, embedding a Codex-tailored hooks file directly. The inline form is deliberate:-- **Why the Claude file sits at the conventional `hooks/hooks.json`.** Claude Code's loader discovers plugin hooks by convention at `hooks/hooks.json`; it does **not** honor the string-path `hooks` override in `plugin.json` for plugin loads. A Claude-scoped filename (`hooks/claude-hooks.json`) therefore loads *nothing* β `/hooks` shows no worktrunk handlers and the π€/π¬ markers stop updating, silently ([#3417](https://github.com/max-sixty/worktrunk/issues/3417)). So the file must live at the conventional path.-- **Why inline for Codex, not a path or an absent key.** Claude and Codex share one payload dir, and Codex *also* auto-discovers `hooks/hooks.json` at the plugin root by convention (`DEFAULT_HOOKS_CONFIG_FILE`, the `None` branch of `load_plugin_hooks`) β which once surfaced Worktrunk's *Claude* events in a Codex session ([#3362](https://github.com/max-sixty/worktrunk/issues/3362)). The Codex manifest carries its own hooks **inline**, taking Codex's `Some(Inline)` branch (`resolve_manifest_hooks` in `codex-rs/core-plugins/src/manifest.rs`), which **overrides** convention discovery. The inline object is both the functional definition of the Codex-native events and the thing that keeps Codex off the shared `hooks/hooks.json`, so the two toolchains coexist on one file: Claude discovers it, Codex ignores it. (An earlier revision Claude-scoped the filename as belt-and-suspenders against #3362, but that broke Claude's discovery β #3417 β and the inline override already made it redundant.)+- **Why inline for Codex, not a path or an absent key.** Claude and Codex share one payload dir, and Codex *also* auto-discovers `hooks/hooks.json` at the plugin root by convention (`DEFAULT_HOOKS_CONFIG_FILE`, the `None` branch of `load_plugin_hooks`) β which once surfaced Worktrunk's *Claude* events in a Codex session ([#3362](https://github.com/max-sixty/worktrunk/issues/3362)). The Codex manifest carries its own hooks **inline**, taking Codex's `Some(Inline)` branch (`resolve_manifest_hooks` in `codex-rs/core-plugins/src/manifest.rs`), which **overrides** convention discovery. The inline object is both the functional definition of the Codex-native events and the thing that keeps Codex off the shared `hooks/hooks.json`, so the two toolchains coexist on one file: Claude discovers it, Codex ignores it. (Scoping via the filename instead β `hooks/claude-hooks.json` β breaks Claude's discovery, [#3417](https://github.com/max-sixty/worktrunk/issues/3417); the inline override makes it unnecessary.)- **Why `$PLUGIN_ROOT`, not `$CLAUDE_PLUGIN_ROOT`.** Codex exports both to hook commands (`PLUGIN_ROOT` native, `CLAUDE_PLUGIN_ROOT` as an OOTB-compat alias β `codex-rs/hooks/src/engine/discovery.rs`). The Codex file uses the native `$PLUGIN_ROOT` so nothing Claude-branded appears in a Codex session.The events (Codex's `HookEventsToml` vocabulary, verified against `codex-rs/config/src/hook_config.rs`):diff --git a/tests/integration_tests/config_show.rs b/tests/integration_tests/config_show.rsindex d774cbd4d..fd48f5a20 100644--- a/tests/integration_tests/config_show.rs+++ b/tests/integration_tests/config_show.rs@@ -3977,21 +3977,24 @@ fn test_codex_plugin_metadata_is_valid_json() {/// third loader-mandated repo-root pointer (`gemini-extension.json` +/// `hooks/hooks.json` β Gemini hard-probes `${extensionPath}/{hooks,skills}/`/// at the extension root with no path indirection). Verified end-to-end-/// against the real CLIs: Claude (claude-cli 2.1.x) wants its manifest at the-/// plugin root with NO `.claude-plugin/` wrapper (`source:-/// "./plugins/worktrunk"` + `<subdir>/.claude-plugin/` fails "Plugin not-/// found"); Gemini (gemini-cli 0.42) resolves the extension at the repo root,-/// so `${extensionPath}/skills/` is the real single-sourced repo-root-/// `skills/` and its hooks call the canonical+/// against the real CLIs: Claude (claude-cli 2.1.207) reads the manifest at+/// `<plugin-root>/.claude-plugin/plugin.json` β the only location `claude+/// plugin validate` accepts β and discovers components by convention: hooks+/// at `hooks/hooks.json`, skills by scanning `skills/*/SKILL.md` (the+/// installer dereferences the `skills` symlink into a real directory in the+/// install cache). A marketplace install of exactly this shape loads the+/// skills and fires the hooks with no component keys in the manifest. Gemini+/// (gemini-cli 0.42) resolves the extension at the repo root, so+/// `${extensionPath}/skills/` is the real single-sourced repo-root `skills/`+/// and its hooks call the canonical/// `${extensionPath}/plugins/worktrunk/hooks/wt.sh` β no symlink, no bundled/// copy, and `gemini extensions install owner/repo` works natively.////// Duplicated strings can't be `include!`d into JSON, so this test is the/// drift guard: the Claude marketplace/manifest descriptions stay/// byte-identical, every product description shares the canonical opening-/// sentence, and every repo-root skill is listed in the Claude manifest-/// (Claude has no skill auto-discovery β an unlisted skill is silently-/// dropped).+/// sentence, and the Claude manifest carries no component-path keys+/// (conventions are the single loading mechanism).#[test]fn test_plugin_layout_is_consolidated() {let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));@@ -4007,9 +4010,26 @@ fn test_plugin_layout_is_consolidated() {let claude_mkt = json(".claude-plugin/marketplace.json");assert_eq!(claude_mkt["plugins"][0]["source"], "./plugins/worktrunk");- // Claude manifest at the plugin root (no wrapper); hooks relative to it.- let claude = json("plugins/worktrunk/plugin.json");- assert_eq!(claude["hooks"], "./hooks/hooks.json");+ // Claude manifest in the plugin's own `.claude-plugin/` wrapper β the+ // only manifest location `claude plugin validate` accepts (a bare+ // plugin.json at the plugin root loads through an undocumented runtime+ // fallback but fails validation).+ let claude = json("plugins/worktrunk/.claude-plugin/plugin.json");+ assert!(+ !root.join("plugins/worktrunk/plugin.json").exists(),+ "the Claude manifest lives at .claude-plugin/plugin.json; a root-level \+ plugin.json rides an undocumented fallback and fails `claude plugin validate`"+ );+ // The manifest carries metadata only; hooks and skills load by convention.+ // The override keys are worse than redundant: the string-path `hooks`+ // override is not honored for plugin loads (#3417), so a `hooks` key can+ // only mask a mislocated file, and a `skills` array re-adds directories+ // the default `skills/` scan already picks up.+ assert!(+ claude.get("hooks").is_none() && claude.get("skills").is_none(),+ "the Claude manifest must not carry `hooks`/`skills` keys β components \+ load by convention (hooks/hooks.json; skills/*/SKILL.md)"+ );assert!(root.join("plugins/worktrunk/hooks/hooks.json").exists()&& root.join("plugins/worktrunk/hooks/wt.sh").exists(),@@ -4042,7 +4062,8 @@ fn test_plugin_layout_is_consolidated() {// the Claude manifest β they must stay byte-identical.assert_eq!(claude_mkt["plugins"][0]["description"], claude["description"],- ".claude-plugin/marketplace.json and plugins/worktrunk/plugin.json descriptions drifted"+ ".claude-plugin/marketplace.json and plugins/worktrunk/.claude-plugin/plugin.json \+ descriptions drifted");// Gemini extension: manifest + hooks are loader-mandated repo-root@@ -4084,23 +4105,29 @@ fn test_plugin_layout_is_consolidated() {"no bundled Gemini wt.sh β hooks reference the canonical worktrunk shim");- // Claude has no skill auto-discovery, so every repo-root skill dir MUST be- // listed explicitly in plugin.json β otherwise a new skill is silently- // invisible to Claude while Codex/Gemini (whole-dir) pick it up.- let listed: std::collections::BTreeSet<&str> = claude["skills"]- .as_array()- .expect("plugin.json `skills` must be an array")- .iter()- .map(|v| v.as_str().unwrap())- .collect();+ // Claude auto-discovers skills by scanning skills/ for <dir>/SKILL.md, so+ // the invariants are structural: the plugin's skills/ is the symlink that+ // single-sources the repo-root skills/ (checked on unix only β a Windows+ // checkout without core.symlinks materializes it as a plain file), and+ // every repo-root skill dir carries a SKILL.md, since the scan silently+ // ignores a directory without one.+ if cfg!(unix) {+ let skills_link = root.join("plugins/worktrunk/skills");+ assert!(+ skills_link.is_symlink()+ && dunce::canonicalize(&skills_link).unwrap()+ == dunce::canonicalize(root.join("skills")).unwrap(),+ "plugins/worktrunk/skills must be the symlink single-sourcing the \+ repo-root skills/"+ );+ }for entry in fs::read_dir(root.join("skills")).unwrap() {let entry = entry.unwrap();if entry.file_type().unwrap().is_dir() {- let listed_form = format!("./skills/{}", entry.file_name().to_string_lossy());assert!(- listed.contains(listed_form.as_str()),- "repo-root skill {listed_form} is not in plugins/worktrunk/plugin.json \- `skills` (Claude has no auto-discovery β add it or it is silently dropped)"+ entry.path().join("SKILL.md").exists(),+ "skills/{} has no SKILL.md β Claude's convention scan silently ignores it",+ entry.file_name().to_string_lossy());}}@@ -4159,7 +4186,10 @@ fn test_plugin_layout_is_consolidated() {"Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows.";let codex = json("plugins/worktrunk/.codex-plugin/plugin.json");for (label, val) in [- ("plugins/worktrunk/plugin.json", &claude["description"]),+ (+ "plugins/worktrunk/.claude-plugin/plugin.json",+ &claude["description"],+ ),(".claude-plugin/marketplace.json",&claude_mkt["plugins"][0]["description"],