Skip to content

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.md
index 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 Safety
diff --git a/plugins/worktrunk/plugin.json b/plugins/worktrunk/.claude-plugin/plugin.json
similarity index 76%
rename from plugins/worktrunk/plugin.json
rename to plugins/worktrunk/.claude-plugin/plugin.json
index 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.md
index 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 root
Path 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.rs
index 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"],