@marcomigozzi/trailhead 0.4.0 → 0.5.1

package/bin/trailhead.test.js

@@ -74,7 +74,7 @@ ok('codex: SKILL.md still carries the adapter header', skillMainContent.includes
 const engineBody = skillMainContent.slice(skillMainContent.indexOf('</codex_skill_adapter>'));
 ok('codex: SKILL.md engine body has no /trailhead: substring', !engineBody.includes('/trailhead:'));
 
-ok('codex: references/techniques/grilling.md exists', fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'references', 'techniques', 'grilling.md')));
+ok('codex: _shared/techniques/grilling.md exists', fs.existsSync(path.join(codexDir, 'skills', '_shared', 'techniques', 'grilling.md')));
 
 const agentsYamlPath = path.join(codexDir, 'skills', 'trailhead', 'agents', 'openai.yaml');
 ok('codex: agents/openai.yaml exists', fs.existsSync(agentsYamlPath));
@@ -90,13 +90,29 @@ ok('codex: no settings.json file', !fs.existsSync(path.join(codexDir, 'settings.
 // #46: per-verb discoverability now projects one Codex SKILL per verb
 // (skills/trailhead-<verb>/), invocable as $trailhead-<verb>. The old
 // ~/.codex/prompts/ shims never surfaced as slash commands on Codex.
-ok('codex: per-verb skills/trailhead-work/SKILL.md exists', fs.existsSync(path.join(codexDir, 'skills', 'trailhead-work', 'SKILL.md')));
+// #46 per-verb discoverability skills. `work` collides with the work CLUSTER
+// dir, so its discoverability is the cluster itself; use a non-colliding verb.
 ok('codex: per-verb skills/trailhead-bug/SKILL.md exists', fs.existsSync(path.join(codexDir, 'skills', 'trailhead-bug', 'SKILL.md')));
-ok('codex: trailhead-work SKILL.md frontmatter is at byte 0', fs.readFileSync(path.join(codexDir, 'skills', 'trailhead-work', 'SKILL.md'), 'utf8').startsWith('---\nname: trailhead-work\n'));
-ok('codex: trailhead-work skill delegates to $trailhead work', fs.readFileSync(path.join(codexDir, 'skills', 'trailhead-work', 'SKILL.md'), 'utf8').includes('$trailhead work'));
-ok('codex: per-verb skill is explicit-only', fs.readFileSync(path.join(codexDir, 'skills', 'trailhead-work', 'agents', 'openai.yaml'), 'utf8').includes('allow_implicit_invocation: false'));
+ok('codex: trailhead-bug SKILL.md frontmatter is at byte 0', fs.readFileSync(path.join(codexDir, 'skills', 'trailhead-bug', 'SKILL.md'), 'utf8').startsWith('---\nname: trailhead-bug\n'));
+ok('codex: trailhead-bug skill delegates to $trailhead bug', fs.readFileSync(path.join(codexDir, 'skills', 'trailhead-bug', 'SKILL.md'), 'utf8').includes('$trailhead bug'));
+ok('codex: per-verb skill is explicit-only', fs.readFileSync(path.join(codexDir, 'skills', 'trailhead-bug', 'agents', 'openai.yaml'), 'utf8').includes('allow_implicit_invocation: false'));
+// The trailhead-work dir is the WORK CLUSTER skill (not a thin verb delegator).
+ok('codex: trailhead-work is the cluster skill (frontmatter name at byte 0)', fs.readFileSync(path.join(codexDir, 'skills', 'trailhead-work', 'SKILL.md'), 'utf8').startsWith('---\nname: trailhead-work\n'));
+ok('codex: trailhead-work cluster carries the adapter header', fs.readFileSync(path.join(codexDir, 'skills', 'trailhead-work', 'SKILL.md'), 'utf8').includes('<codex_skill_adapter>'));
+ok('codex: NO thin trailhead-work verb-delegator (cluster occupies the name)', !fs.readFileSync(path.join(codexDir, 'skills', 'trailhead-work', 'SKILL.md'), 'utf8').includes('This is a thin discoverability entry'));
 ok('codex: no ~/.codex/prompts shims left (old mechanism dropped)', !fs.existsSync(path.join(codexDir, 'prompts', 'trailhead.md')) && !fs.existsSync(path.join(codexDir, 'prompts', 'trailhead-work.md')));
 
+// The split ships all sibling engine skills so the ../_shared/ relative refs resolve.
+ok('codex: _shared/ projected', fs.existsSync(path.join(codexDir, 'skills', '_shared', 'substrate.md')));
+for (const cl of ['trailhead-chart', 'trailhead-work', 'trailhead-view', 'trailhead-capture', 'trailhead-manage']) {
+  ok(`codex: cluster ${cl} SKILL.md projected`, fs.existsSync(path.join(codexDir, 'skills', cl, 'SKILL.md')));
+  ok(`codex: cluster ${cl} carries the adapter header`, fs.readFileSync(path.join(codexDir, 'skills', cl, 'SKILL.md'), 'utf8').includes('<codex_skill_adapter>'));
+  ok(`codex: cluster ${cl} frontmatter precedes the adapter header`, (() => { const c = fs.readFileSync(path.join(codexDir, 'skills', cl, 'SKILL.md'), 'utf8'); return c.startsWith('---\n') && c.indexOf('name:') < c.indexOf('<codex_skill_adapter>'); })());
+  ok(`codex: cluster ${cl} agents/openai.yaml explicit-only`, fs.readFileSync(path.join(codexDir, 'skills', cl, 'agents', 'openai.yaml'), 'utf8').includes('allow_implicit_invocation: false'));
+}
+// A cluster's ../_shared/ reference target actually resolves as a sibling.
+ok('codex: trailhead-work/../_shared/substrate.md resolves', fs.existsSync(path.join(codexDir, 'skills', 'trailhead-work', '..', '_shared', 'substrate.md')));
+
 // --- codex hooks (#29) --------------------------------------------------------
 const codexHooksJsonPath = path.join(codexDir, 'hooks.json');
 ok('codex: hooks.json exists', fs.existsSync(codexHooksJsonPath));
@@ -115,18 +131,59 @@ ok('codex: skills/trailhead/hooks/lib/commit-message-check.js exists (commit-gua
 const codexConfigTomlPath = path.join(codexDir, 'config.toml');
 ok('codex: config.toml exists', fs.existsSync(codexConfigTomlPath));
 ok('codex: config.toml enables hooks feature', fs.readFileSync(codexConfigTomlPath, 'utf8').includes('hooks = true'));
-// v2 is gated on projected pins: this install (repoRoot, no models.codex.*)
-// projects none, so multi_agent_v2 stays OFF (base multi_agent still fans out;
-// adapter §D expects no trailhead agent_type registry in the no-pins case).
-ok('codex: config.toml does NOT enable multi_agent_v2 when no models.codex.* pins are projected',
-  !fs.readFileSync(codexConfigTomlPath, 'utf8').includes('multi_agent_v2 = true'));
+// All 7 agents are always projected uniformly (pinned or pin-less), so
+// multi_agent_v2 is ON even with no models.codex.* set (this install,
+// repoRoot, sets none): the adapter §D registry is always present.
+ok('codex: config.toml enables multi_agent_v2 even with no models.codex.* pins projected',
+  fs.readFileSync(codexConfigTomlPath, 'utf8').includes('multi_agent_v2 = true'));
+
+const codexAgentsDirPath = path.join(codexDir, 'agents');
+const noPinFixTomlPath = path.join(codexAgentsDirPath, 'trailhead-fix.toml');
+const noPinMapTomlPath = path.join(codexAgentsDirPath, 'trailhead-codebase-map.toml');
+ok('codex: trailhead-fix.toml is projected with no models.codex.* set', fs.existsSync(noPinFixTomlPath));
+ok('codex: trailhead-codebase-map.toml is projected with no models.codex.* set', fs.existsSync(noPinMapTomlPath));
+ok('codex: trailhead-fix.toml is pin-less (no model = line) with no models.codex.* set',
+  fs.existsSync(noPinFixTomlPath) && !/^model = /m.test(fs.readFileSync(noPinFixTomlPath, 'utf8')));
 
-// --- codex agent TOML projection (#38) -----------------------------------------
+// --- codex --symlink: link verbatim artifacts (hooks + templates), keep skills projected ---
+const codexSymDir = mktmp();
+runInstaller([`--codex`, `--symlink`, `--dir=${codexSymDir}`]);
+ok('codex symlink: skills/trailhead/hooks/trailhead-secret-guard.js is a symlink',
+  fs.lstatSync(path.join(codexSymDir, 'skills', 'trailhead', 'hooks', 'trailhead-secret-guard.js')).isSymbolicLink());
+ok('codex symlink: skills/trailhead/hooks/lib/commit-message-check.js is a symlink',
+  fs.lstatSync(path.join(codexSymDir, 'skills', 'trailhead', 'hooks', 'lib', 'commit-message-check.js')).isSymbolicLink());
+ok('codex symlink: skills/trailhead/templates is a symlink',
+  fs.lstatSync(path.join(codexSymDir, 'skills', 'trailhead', 'templates')).isSymbolicLink());
+ok('codex symlink: a hook symlink resolves into the package source',
+  fs.realpathSync(path.join(codexSymDir, 'skills', 'trailhead', 'hooks', 'trailhead-secret-guard.js')) ===
+  fs.realpathSync(path.join(repoRoot, 'plugins', 'trailhead', 'hooks', 'trailhead-secret-guard.js')));
+ok('codex symlink: converted SKILL.md stays a regular file (projected, not linked)',
+  !fs.lstatSync(path.join(codexSymDir, 'skills', 'trailhead', 'SKILL.md')).isSymbolicLink());
+// Reinstall over the existing symlink install must not throw (EEXIST guard).
+runInstaller([`--codex`, `--symlink`, `--dir=${codexSymDir}`]);
+ok('codex symlink: reinstall over existing symlinks succeeds',
+  fs.lstatSync(path.join(codexSymDir, 'skills', 'trailhead', 'hooks', 'trailhead-secret-guard.js')).isSymbolicLink());
+// Default (copy) codex install keeps hooks/templates as real files, not symlinks.
+ok('codex copy: hooks are regular files (not symlinks)',
+  !fs.lstatSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', 'trailhead-secret-guard.js')).isSymbolicLink());
+ok('codex copy: templates is a regular dir (not a symlink)',
+  !fs.lstatSync(path.join(codexDir, 'skills', 'trailhead', 'templates')).isSymbolicLink());
+
+// --- codex agent TOML projection (#38, #88) -------------------------------------
 // repoRoot's own .trailhead/config.json has no models.codex.*, so a plain
-// install (cwd: repoRoot, no models.codex anywhere) projects no agent TOMLs.
-ok('codex: no trailhead-*.toml under agents/ when models.codex.* is unset',
-  !fs.existsSync(path.join(codexDir, 'agents')) ||
-  !fs.readdirSync(path.join(codexDir, 'agents')).some((f) => /^trailhead-.*\.toml$/.test(f)));
+// install (cwd: repoRoot, no models.codex anywhere) still projects all 7
+// agents pin-less (uniform projection, #88), never zero.
+ok('codex: all 7 trailhead-*.toml exist under agents/ even with models.codex.* unset', (() => {
+  const dir = path.join(codexDir, 'agents');
+  if (!fs.existsSync(dir)) return false;
+  const tomls = fs.readdirSync(dir).filter((f) => /^trailhead-.*\.toml$/.test(f));
+  return tomls.length === 7;
+})());
+ok('codex: every trailhead-*.toml is pin-less when models.codex.* is unset', (() => {
+  const dir = path.join(codexDir, 'agents');
+  const tomls = fs.readdirSync(dir).filter((f) => /^trailhead-.*\.toml$/.test(f));
+  return tomls.every((f) => !/^model = /m.test(fs.readFileSync(path.join(dir, f), 'utf8')));
+})());
 
 // --- codex migration (#46): install over old prompt shims sweeps them --------
 const migCodexDir = mktmp();
@@ -138,12 +195,26 @@ ok('codex migration: stale prompts/trailhead.md swept on install', !fs.existsSyn
 ok('codex migration: stale prompts/trailhead-work.md swept on install', !fs.existsSync(path.join(migCodexDir, 'prompts', 'trailhead-work.md')));
 ok('codex migration: per-verb skill projected in its place', fs.existsSync(path.join(migCodexDir, 'skills', 'trailhead-work', 'SKILL.md')));
 
+// codex migration: a stale trailhead-owned skill dir (pre-split monolith /
+// removed cluster) is swept on reinstall; a co-tenant skill is preserved.
+const migCodexSkillDir = mktmp();
+runInstaller([`--codex`, `--dir=${migCodexSkillDir}`]);
+fs.mkdirSync(path.join(migCodexSkillDir, 'skills', 'trailhead-monolith'), { recursive: true });
+fs.writeFileSync(path.join(migCodexSkillDir, 'skills', 'trailhead-monolith', 'SKILL.md'), 'stale\n');
+fs.mkdirSync(path.join(migCodexSkillDir, 'skills', 'other-plugin'), { recursive: true });
+fs.writeFileSync(path.join(migCodexSkillDir, 'skills', 'other-plugin', 'SKILL.md'), 'co-tenant\n');
+runInstaller([`--codex`, `--dir=${migCodexSkillDir}`]);
+ok('codex migration: stale trailhead-monolith skill dir swept on reinstall', !fs.existsSync(path.join(migCodexSkillDir, 'skills', 'trailhead-monolith')));
+ok('codex migration: co-tenant skill preserved', fs.existsSync(path.join(migCodexSkillDir, 'skills', 'other-plugin')));
+
 // --- codex uninstall (same tmp) ----------------------------------------------
 runInstaller([`--codex`, `--dir=${codexDir}`, '--uninstall']);
 ok('codex uninstall: skills/trailhead gone', !fs.existsSync(path.join(codexDir, 'skills', 'trailhead')));
 ok('codex uninstall: legacy trailhead engine dir gone', !fs.existsSync(path.join(codexDir, 'trailhead')));
 ok('codex uninstall: per-verb skills/trailhead-work gone', !fs.existsSync(path.join(codexDir, 'skills', 'trailhead-work')));
 ok('codex uninstall: per-verb skills/trailhead-bug gone', !fs.existsSync(path.join(codexDir, 'skills', 'trailhead-bug')));
+ok('codex uninstall: _shared gone', !fs.existsSync(path.join(codexDir, 'skills', '_shared')));
+ok('codex uninstall: cluster trailhead-view gone', !fs.existsSync(path.join(codexDir, 'skills', 'trailhead-view')));
 ok('codex uninstall: hooks.json no longer contains trailhead commands', (() => {
   const h = JSON.parse(fs.readFileSync(codexHooksJsonPath, 'utf8'));
   const str = JSON.stringify(h);
@@ -157,6 +228,12 @@ runInstaller([`--claude`, `--dir=${claudeDir}`]);
 
 const claudeSkillPath = path.join(claudeDir, 'skills', 'trailhead', 'SKILL.md');
 ok('claude: skills/trailhead/SKILL.md exists', fs.existsSync(claudeSkillPath));
+// The split ships all sibling engine skills on Claude too.
+ok('claude: skills/_shared/substrate.md exists', fs.existsSync(path.join(claudeDir, 'skills', '_shared', 'substrate.md')));
+for (const cl of ['trailhead-chart', 'trailhead-work', 'trailhead-view', 'trailhead-capture', 'trailhead-manage']) {
+  ok(`claude: skills/${cl}/SKILL.md exists`, fs.existsSync(path.join(claudeDir, 'skills', cl, 'SKILL.md')));
+}
+ok('claude: cluster ../_shared/ reference resolves', fs.existsSync(path.join(claudeDir, 'skills', 'trailhead-work', '..', '_shared', 'substrate.md')));
 ok('claude: commands/trailhead/work.md exists', fs.existsSync(path.join(claudeDir, 'commands', 'trailhead', 'work.md')));
 ok('claude: hooks/trailhead-commit-guard.js exists', fs.existsSync(path.join(claudeDir, 'hooks', 'trailhead-commit-guard.js')));
 ok('claude: hooks/lib/commit-message-check.js exists (commit-guard require target)',
@@ -176,6 +253,90 @@ ok('claude: trailhead-commit-guard.js loads without MODULE_NOT_FOUND', (() => {
 })());
 ok('claude: SKILL.md does not start with the codex adapter header', !fs.readFileSync(claudeSkillPath, 'utf8').startsWith('<codex_skill_adapter>'));
 
+// --- claude: engine agents registered as user subagents -----------------------
+// Without these under <configDir>/agents/, every technique dispatch fails and
+// falls back to running inline on the session model, so the per-technique
+// config.models.* split silently never applies.
+const claudeAgentsDir = path.join(claudeDir, 'agents');
+const expectedAgents = ['trailhead-plan', 'trailhead-executor', 'trailhead-research', 'trailhead-code-review', 'trailhead-debug', 'trailhead-fix', 'trailhead-codebase-map'];
+for (const a of expectedAgents) {
+  ok(`claude: agents/${a}.md placed`, fs.existsSync(path.join(claudeAgentsDir, `${a}.md`)));
+}
+ok('claude: agent file registers its subagent name in frontmatter',
+  fs.readFileSync(path.join(claudeAgentsDir, 'trailhead-executor.md'), 'utf8').startsWith('---\nname: trailhead-executor\n'));
+ok('claude: agents are real files on a copy install (not symlinks)',
+  !fs.lstatSync(path.join(claudeAgentsDir, 'trailhead-plan.md')).isSymbolicLink());
+
+// --- claude --symlink: dev install links hooks live too (not just skills/commands) ---
+const symDir = mktmp();
+runInstaller([`--claude`, `--symlink`, `--dir=${symDir}`]);
+ok('claude symlink: skills/trailhead is a symlink',
+  fs.lstatSync(path.join(symDir, 'skills', 'trailhead')).isSymbolicLink());
+ok('claude symlink: hooks/trailhead-secret-guard.js is a symlink',
+  fs.lstatSync(path.join(symDir, 'hooks', 'trailhead-secret-guard.js')).isSymbolicLink());
+ok('claude symlink: hooks/lib/commit-message-check.js is a symlink',
+  fs.lstatSync(path.join(symDir, 'hooks', 'lib', 'commit-message-check.js')).isSymbolicLink());
+ok('claude symlink: hook symlink resolves into the package source',
+  fs.realpathSync(path.join(symDir, 'hooks', 'trailhead-secret-guard.js')) ===
+  fs.realpathSync(path.join(repoRoot, 'plugins', 'trailhead', 'hooks', 'trailhead-secret-guard.js')));
+ok('claude symlink: a symlinked commit-guard still loads its lib (no MODULE_NOT_FOUND)', (() => {
+  let out = '';
+  try {
+    out = String(execFileSync(process.execPath, [path.join(symDir, 'hooks', 'trailhead-commit-guard.js')],
+      { input: '{"tool_name":"Bash","tool_input":{"command":"echo hi"}}', stdio: 'pipe' }));
+  } catch (e) { out = String(e.stdout || '') + String(e.stderr || ''); }
+  return !out.includes('MODULE_NOT_FOUND') && !out.includes('Cannot find module');
+})());
+// Reinstalling over an existing symlink install must not throw (EEXIST guard).
+runInstaller([`--claude`, `--symlink`, `--dir=${symDir}`]);
+ok('claude symlink: reinstall over existing symlinks succeeds',
+  fs.lstatSync(path.join(symDir, 'hooks', 'trailhead-secret-guard.js')).isSymbolicLink());
+ok('claude symlink: agents/trailhead-plan.md is a symlink',
+  fs.lstatSync(path.join(symDir, 'agents', 'trailhead-plan.md')).isSymbolicLink());
+ok('claude symlink: agent symlink resolves into the package source',
+  fs.realpathSync(path.join(symDir, 'agents', 'trailhead-plan.md')) ===
+  fs.realpathSync(path.join(repoRoot, 'plugins', 'trailhead', 'agents', 'trailhead-plan.md')));
+// Default (copy) install keeps hooks as real files, not symlinks.
+ok('claude copy: hooks/trailhead-secret-guard.js is a regular file (not a symlink)',
+  !fs.lstatSync(path.join(claudeDir, 'hooks', 'trailhead-secret-guard.js')).isSymbolicLink());
+
+// --- claude migration: reinstall over an old layout sweeps stale skill dirs ---
+// An old install may carry a pre-split monolith (skills/trailhead-monolith) or a
+// removed cluster (skills/trailhead-legacy) the current install no longer ships.
+// Reinstalling must sweep every stale trailhead-owned skill dir, while leaving a
+// co-tenant plugin's own skill (skills/other-plugin) untouched.
+const migClaudeDir = mktmp();
+runInstaller([`--claude`, `--dir=${migClaudeDir}`]);
+fs.mkdirSync(path.join(migClaudeDir, 'skills', 'trailhead-monolith'), { recursive: true });
+fs.writeFileSync(path.join(migClaudeDir, 'skills', 'trailhead-monolith', 'SKILL.md'), 'stale monolith\n');
+fs.mkdirSync(path.join(migClaudeDir, 'skills', 'trailhead-legacy'), { recursive: true });
+fs.writeFileSync(path.join(migClaudeDir, 'skills', 'trailhead-legacy', 'SKILL.md'), 'stale cluster\n');
+fs.mkdirSync(path.join(migClaudeDir, 'skills', 'other-plugin'), { recursive: true });
+fs.writeFileSync(path.join(migClaudeDir, 'skills', 'other-plugin', 'SKILL.md'), 'co-tenant\n');
+runInstaller([`--claude`, `--dir=${migClaudeDir}`]);
+ok('claude migration: stale trailhead-monolith swept on reinstall', !fs.existsSync(path.join(migClaudeDir, 'skills', 'trailhead-monolith')));
+ok('claude migration: stale trailhead-legacy cluster swept on reinstall', !fs.existsSync(path.join(migClaudeDir, 'skills', 'trailhead-legacy')));
+ok('claude migration: co-tenant skill preserved (only trailhead names swept)', fs.existsSync(path.join(migClaudeDir, 'skills', 'other-plugin')));
+ok('claude migration: current dispatcher present after reinstall', fs.existsSync(path.join(migClaudeDir, 'skills', 'trailhead', 'SKILL.md')));
+ok('claude migration: current cluster present after reinstall', fs.existsSync(path.join(migClaudeDir, 'skills', 'trailhead-work', 'SKILL.md')));
+// The agents dir gets the same name-only sweep on reinstall: a stale trailhead
+// agent (renamed/removed) is swept, a co-tenant agent left alone.
+fs.writeFileSync(path.join(migClaudeDir, 'agents', 'trailhead-oldagent.md'), '---\nname: trailhead-oldagent\n---\n');
+fs.writeFileSync(path.join(migClaudeDir, 'agents', 'other-plugin-agent.md'), '---\nname: other-plugin-agent\n---\n');
+runInstaller([`--claude`, `--dir=${migClaudeDir}`]);
+ok('claude migration: stale trailhead-oldagent.md swept on reinstall', !fs.existsSync(path.join(migClaudeDir, 'agents', 'trailhead-oldagent.md')));
+ok('claude migration: co-tenant agent preserved on reinstall', fs.existsSync(path.join(migClaudeDir, 'agents', 'other-plugin-agent.md')));
+ok('claude migration: engine agents present after reinstall', fs.existsSync(path.join(migClaudeDir, 'agents', 'trailhead-executor.md')));
+
+// Uninstall also sweeps a stale trailhead-owned dir the current package no
+// longer ships (monolith), not just the current engineSkillDirs() set.
+const uninstMigDir = mktmp();
+runInstaller([`--claude`, `--dir=${uninstMigDir}`]);
+fs.mkdirSync(path.join(uninstMigDir, 'skills', 'trailhead-monolith'), { recursive: true });
+fs.writeFileSync(path.join(uninstMigDir, 'skills', 'trailhead-monolith', 'SKILL.md'), 'stale\n');
+runInstaller([`--claude`, `--dir=${uninstMigDir}`, '--uninstall']);
+ok('claude uninstall: stale trailhead-monolith swept too', !fs.existsSync(path.join(uninstMigDir, 'skills', 'trailhead-monolith')));
+
 // --- claude uninstall: remove trailhead's lib, keep a co-tenant's -------------
 // The Claude hooks/lib dir is shared with other plugins. Drop a fake co-tenant
 // lib next to trailhead's, uninstall, and assert only trailhead's own lib file
@@ -188,6 +349,25 @@ runInstaller([`--claude`, `--dir=${coTenantDir}`, '--uninstall']);
 ok('claude uninstall: trailhead lib removed', !fs.existsSync(path.join(coTenantDir, 'hooks', 'lib', 'commit-message-check.js')));
 ok('claude uninstall: co-tenant lib preserved (no recursive wipe)', fs.existsSync(coTenantLib));
 
+// The agents dir is shared too: a co-tenant's own agent survives uninstall,
+// while trailhead's are removed by name.
+const coTenantAgentDir = mktmp();
+runInstaller([`--claude`, `--dir=${coTenantAgentDir}`]);
+const foreignAgent = path.join(coTenantAgentDir, 'agents', 'other-plugin-agent.md');
+fs.writeFileSync(foreignAgent, '---\nname: other-plugin-agent\n---\n');
+ok('claude: engine agent present before uninstall', fs.existsSync(path.join(coTenantAgentDir, 'agents', 'trailhead-plan.md')));
+runInstaller([`--claude`, `--dir=${coTenantAgentDir}`, '--uninstall']);
+ok('claude uninstall: trailhead agents removed by name', !fs.existsSync(path.join(coTenantAgentDir, 'agents', 'trailhead-plan.md')));
+ok('claude uninstall: co-tenant agent preserved (no recursive wipe)', fs.existsSync(foreignAgent));
+
+// Uninstall removes every split skill (dispatcher + clusters + _shared) by name.
+const splitDir = mktmp();
+runInstaller([`--claude`, `--dir=${splitDir}`]);
+runInstaller([`--claude`, `--dir=${splitDir}`, '--uninstall']);
+for (const nm of ['trailhead', 'trailhead-chart', 'trailhead-work', 'trailhead-view', 'trailhead-capture', 'trailhead-manage', '_shared']) {
+  ok(`claude uninstall: skills/${nm} removed`, !fs.existsSync(path.join(splitDir, 'skills', nm)));
+}
+
 const settingsPath = path.join(claudeDir, 'settings.json');
 ok('claude: settings.json exists', fs.existsSync(settingsPath));
 const settingsContent = fs.readFileSync(settingsPath, 'utf8');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marcomigozzi/trailhead",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Start and drive large projects as a map of tickets on GitHub Issues. Map-based onboarding + a discuss→plan→execute→verify engine, all on the Issues. Installs the trailhead skill, commands, and hooks into your agent's config dir.",
   "bin": {
     "trailhead": "bin/trailhead.js"

package/plugins/trailhead/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "trailhead",
-  "version": "0.4.0",
-  "description": "Start and drive large projects as a map of tickets on GitHub Issues, resolving one at a time. Map-based onboarding + a discuss→plan→execute→verify engine with atomic commits, all on the Issues. Self-contained: depends on nothing beyond an authenticated gh CLI.",
+  "version": "0.5.1",
+  "description": "Start and drive large projects as a map of tickets on GitHub Issues, resolving one at a time. Map-based onboarding + a discuss→plan→execute→verify engine with atomic commits, all on the Issues. Ships as a dispatcher plus cohesion-clustered skills over a shared core; depends on nothing beyond an authenticated gh CLI.",
   "author": {
     "name": "Marco Migozzi",
     "url": "https://github.com/ToRvaLDz"
@@ -17,7 +17,12 @@
     "capture"
   ],
   "skills": [
-    "./skills/trailhead"
+    "./skills/trailhead",
+    "./skills/trailhead-chart",
+    "./skills/trailhead-work",
+    "./skills/trailhead-view",
+    "./skills/trailhead-capture",
+    "./skills/trailhead-manage"
   ],
   "hooks": "./hooks/hooks.json"
 }

package/plugins/trailhead/agents/trailhead-code-review.md

@@ -0,0 +1,9 @@
+---
+name: trailhead-code-review
+description: "trailhead code-review subagent: adversarially reviews a ticket's diff and reports; never edits or commits."
+tools: Read, Grep, Glob, Bash, WebFetch, WebSearch, TodoWrite
+---
+
+trailhead's code-review subagent. Review the ticket's diff adversarially on the Code review technique's axes, verifying each finding before reporting. Do not defer to a convention or a settled-decision memory.
+
+The full protocol is injected at spawn from the trailhead skill's single source (`_shared/techniques/code-review.md`); follow that, not any embedded copy. Read-only by policy: it reviews and reports into trailhead's `VERIFY` comment, it must never Edit/Write or commit. Model-agnostic by design: the engine passes the `config.models.review` model as the spawn-time override, so config stays authoritative.

package/plugins/trailhead/agents/trailhead-codebase-map.md

@@ -0,0 +1,9 @@
+---
+name: trailhead-codebase-map
+description: "trailhead codebase-map reader subagent: maps one non-overlapping facet of the repo. Read-only."
+tools: Read, Grep, Glob, Bash, WebFetch, WebSearch, TodoWrite
+---
+
+trailhead's codebase-map reader subagent. Map ONE non-overlapping facet of the repo for the distilled `trailhead:codebase` issue; do not read another reader's territory.
+
+The full protocol is injected at spawn from the trailhead skill's single source (`_shared/techniques/codebase-map.md`); follow that, not any embedded copy. Read-only by policy: read-only by construction. Model-agnostic by design: the engine passes the session model at spawn (no dedicated model key), so config stays authoritative.

package/plugins/trailhead/agents/trailhead-debug.md

@@ -0,0 +1,9 @@
+---
+name: trailhead-debug
+description: "trailhead debug subagent: finds a defect's root cause by the scientific method."
+tools: Read, Write, Edit, Grep, Glob, Bash, WebFetch, WebSearch, TodoWrite
+---
+
+trailhead's debug subagent. Find the root cause of the ticket's defect by the scientific method: reproduce, localise, falsifiable hypotheses, confirm cause, verify.
+
+The full protocol is injected at spawn from the trailhead skill's single source (`_shared/techniques/debug.md`); follow that, not any embedded copy. Full tools by policy: it adds instrumentation and regression tests, so it needs Write. Model-agnostic by design: the engine passes the `config.models.debug` model as the spawn-time override, so config stays authoritative.

package/plugins/trailhead/agents/trailhead-executor.md

@@ -0,0 +1,9 @@
+---
+name: trailhead-executor
+description: "trailhead execute subagent: implements an approved PLAN with atomic conventional commits (each carrying a Refs: #<n> trailer)."
+tools: Read, Write, Edit, Grep, Glob, Bash, WebFetch, WebSearch, TodoWrite
+---
+
+trailhead's execute subagent. Implement the approved PLAN for a build ticket with atomic conventional commits, each carrying a `Refs: #<n>` trailer for the ticket, following the repo's `trailhead:conventions`.
+
+The full protocol is injected at spawn from the trailhead skill's single source (the Execute step in `trailhead-work/references/ticket-engines.md`); follow that, not any embedded copy. Full tools by policy: it can Edit/Write/commit. Model-agnostic by design: the engine passes the `config.models.execute` model as the spawn-time override, so config stays authoritative.

package/plugins/trailhead/agents/trailhead-fix.md

@@ -0,0 +1,9 @@
+---
+name: trailhead-fix
+description: "trailhead fix subagent: implements a bug fix with atomic commits (each carrying a Refs: #<n> trailer)."
+tools: Read, Write, Edit, Grep, Glob, Bash, WebFetch, WebSearch, TodoWrite
+---
+
+trailhead's fix subagent. Implement the correction for a bug ticket with atomic conventional commits, each carrying a `Refs: #<n>` trailer for the ticket, following the repo's `trailhead:conventions`; where sensible, a test that fails before and passes after.
+
+The full protocol is injected at spawn from the trailhead skill's single source (the Fix step in `trailhead-work/references/ticket-engines.md`); follow that, not any embedded copy. Full tools by policy: it can Edit/Write/commit. Model-agnostic by design: the engine passes the `config.models.execute` model as the spawn-time override (fix tracks the execute key), so config stays authoritative.

package/plugins/trailhead/agents/trailhead-plan.md

@@ -0,0 +1,9 @@
+---
+name: trailhead-plan
+description: "trailhead planning subagent: produces a build ticket's PLAN (steps, seams, files touched, verification criteria). Read-only, never implements."
+tools: Read, Grep, Glob, Bash, WebFetch, WebSearch, TodoWrite
+---
+
+trailhead's planning subagent. Produce the PLAN for a build ticket: the steps, the seams, the files touched, and the verification criteria, applying TDD per the ticket's config.
+
+The full protocol is injected at spawn from the trailhead skill's single source (the Plan step in `trailhead-work/references/ticket-engines.md`); follow that, not any embedded copy. Read-only by policy: plan, do not implement or commit. Model-agnostic by design: the engine passes the `config.models.plan` model as the spawn-time override, so config stays authoritative.

package/plugins/trailhead/agents/trailhead-research.md

@@ -0,0 +1,9 @@
+---
+name: trailhead-research
+description: "trailhead research subagent: gathers a decision-ready fact from primary sources."
+tools: Read, Write, Edit, Grep, Glob, Bash, WebFetch, WebSearch, TodoWrite
+---
+
+trailhead's research subagent. Gather the decision-ready fact a ticket waits on from primary sources, recording findings with citations to a throwaway `research/<name>` branch; change no product code beyond the research artifact.
+
+The full protocol is injected at spawn from the trailhead skill's single source (`_shared/techniques/research.md`); follow that, not any embedded copy. Full tools by policy: it needs Write for the research artifact. Model-agnostic by design: the engine passes the `config.models.research` model as the spawn-time override, so config stays authoritative.

package/plugins/trailhead/commands/adopt.md

@@ -3,4 +3,4 @@ description: "Adopt an existing project: map the codebase once, then go lean"
 argument-hint: ""
 ---
 
-Invoke the `trailhead` skill for the **adopt** action: call the Skill tool with skill name `trailhead` and arguments `adopt $ARGUMENTS`, then carry out the skill's instructions for that verb. Do not re-implement the behaviour here. The skill is the single source of truth.
+Invoke the `trailhead` skill for the **adopt** action: call the Skill tool with skill name `trailhead-chart` and arguments `adopt $ARGUMENTS`, then carry out the skill's instructions for that verb. Do not re-implement the behaviour here. The skill is the single source of truth.

package/plugins/trailhead/commands/bug.md

@@ -3,4 +3,4 @@ description: Capture a bug ticket (use --of <ticket> for a regression)
 argument-hint: "[--of <ticket>] <text>"
 ---
 
-Invoke the `trailhead` skill for the **bug** action: call the Skill tool with skill name `trailhead` and arguments `bug $ARGUMENTS`, then **read the skill's `references/capture.md` and follow it**: that file holds the full protocol for the capture verbs. Do not re-implement the behaviour here. The skill is the single source of truth.
+Invoke the `trailhead` skill for the **bug** action: call the Skill tool with skill name `trailhead-capture` and arguments `bug $ARGUMENTS`, then **read the skill's `references/capture.md` and follow it**: that file holds the full protocol for the capture verbs. Do not re-implement the behaviour here. The skill is the single source of truth.

package/plugins/trailhead/commands/config.md

@@ -3,4 +3,4 @@ description: Guided menu setup, or get/set trailhead config
 argument-hint: "[get|set …]"
 ---
 
-Invoke the `trailhead` skill for the **config** action: call the Skill tool with skill name `trailhead` and arguments `config $ARGUMENTS`, then **read the skill's `references/configuration.md` and follow it**: that file holds the keys, their semantics, and the guided setup. Do not re-implement the behaviour here. The skill is the single source of truth.
+Invoke the `trailhead` skill for the **config** action: call the Skill tool with skill name `trailhead-manage` and arguments `config $ARGUMENTS`, then **read the skill's `references/configuration.md` and follow it**: that file holds the keys, their semantics, and the guided setup. Do not re-implement the behaviour here. The skill is the single source of truth.

package/plugins/trailhead/commands/dashboard.md

@@ -3,4 +3,4 @@ description: "Show the repo dashboard: the pinned index of every open map, the w
 argument-hint: ""
 ---
 
-Invoke the `trailhead` skill for the **dashboard** action: call the Skill tool with skill name `trailhead` and arguments `dashboard $ARGUMENTS`, then carry out the skill's instructions for that verb (regenerate the pinned `trailhead:dashboard` index issue from the live tracker, creating and pinning it if missing, and show it). Do not re-implement the behaviour here. The skill is the single source of truth.
+Invoke the `trailhead` skill for the **dashboard** action: call the Skill tool with skill name `trailhead-view` and arguments `dashboard $ARGUMENTS`, then carry out the skill's instructions for that verb (regenerate the pinned `trailhead:dashboard` index issue from the live tracker, creating and pinning it if missing, and show it). Do not re-implement the behaviour here. The skill is the single source of truth.

package/plugins/trailhead/commands/grill.md

@@ -3,4 +3,4 @@ description: Run a standalone grilling session on a decision or topic
 argument-hint: "[topic|ticket]"
 ---
 
-Invoke the `trailhead` skill for the **grill** action: call the Skill tool with skill name `trailhead` and arguments `grill $ARGUMENTS`, then **read the skill's `references/techniques/grilling.md` (and `references/techniques/domain-vocabulary.md`) and follow them**: they hold the full protocol for this action. Do not re-implement the behaviour here. The skill is the single source of truth.
+Invoke the `trailhead` skill for the **grill** action: call the Skill tool with skill name `trailhead-chart` and arguments `grill $ARGUMENTS`, then carry out the skill's instructions for that verb (they run the Grilling and Domain vocabulary techniques). Do not re-implement the behaviour here. The skill is the single source of truth.

package/plugins/trailhead/commands/idea.md

@@ -3,4 +3,4 @@ description: Capture an idea into the fog (Not yet specified)
 argument-hint: "<text>"
 ---
 
-Invoke the `trailhead` skill for the **idea** action: call the Skill tool with skill name `trailhead` and arguments `idea $ARGUMENTS`, then **read the skill's `references/capture.md` and follow it**: that file holds the full protocol for the capture verbs. Do not re-implement the behaviour here. The skill is the single source of truth.
+Invoke the `trailhead` skill for the **idea** action: call the Skill tool with skill name `trailhead-capture` and arguments `idea $ARGUMENTS`, then **read the skill's `references/capture.md` and follow it**: that file holds the full protocol for the capture verbs. Do not re-implement the behaviour here. The skill is the single source of truth.

package/plugins/trailhead/commands/inbox.md

@@ -3,4 +3,4 @@ description: Triage issues opened by others and integrate the worthwhile ones in
 argument-hint: "[issue]"
 ---
 
-Invoke the `trailhead` skill for the **inbox** action: call the Skill tool with skill name `trailhead` and arguments `inbox $ARGUMENTS`, then **read the skill's `references/inbox.md` and follow it**: that file holds the full protocol for this action. Do not re-implement the behaviour here. The skill is the single source of truth.
+Invoke the `trailhead` skill for the **inbox** action: call the Skill tool with skill name `trailhead-chart` and arguments `inbox $ARGUMENTS`, then **read the skill's `references/inbox.md` and follow it**: that file holds the full protocol for this action. Do not re-implement the behaviour here. The skill is the single source of truth.

package/plugins/trailhead/commands/map.md

@@ -3,4 +3,4 @@ description: Show the low-res map (destination, decisions, frontier, fog)
 argument-hint: ""
 ---
 
-Invoke the `trailhead` skill for the **map** action: call the Skill tool with skill name `trailhead` and arguments `map $ARGUMENTS`, then carry out the skill's instructions for that verb. Do not re-implement the behaviour here. The skill is the single source of truth.
+Invoke the `trailhead` skill for the **map** action: call the Skill tool with skill name `trailhead-view` and arguments `map $ARGUMENTS`, then carry out the skill's instructions for that verb. Do not re-implement the behaviour here. The skill is the single source of truth.

package/plugins/trailhead/commands/new.md

@@ -3,4 +3,4 @@ description: Chart a new trailhead map from a loose idea
 argument-hint: "[idea]"
 ---
 
-Invoke the `trailhead` skill for the **new** action: call the Skill tool with skill name `trailhead` and arguments `new $ARGUMENTS`, then carry out the skill's instructions for that verb. Do not re-implement the behaviour here. The skill is the single source of truth.
+Invoke the `trailhead` skill for the **new** action: call the Skill tool with skill name `trailhead-chart` and arguments `new $ARGUMENTS`, then carry out the skill's instructions for that verb. Do not re-implement the behaviour here. The skill is the single source of truth.

package/plugins/trailhead/commands/note.md

@@ -3,4 +3,4 @@ description: Capture a verbatim note
 argument-hint: "<text>"
 ---
 
-Invoke the `trailhead` skill for the **note** action: call the Skill tool with skill name `trailhead` and arguments `note $ARGUMENTS`, then **read the skill's `references/capture.md` and follow it**: that file holds the full protocol for the capture verbs. Do not re-implement the behaviour here. The skill is the single source of truth.
+Invoke the `trailhead` skill for the **note** action: call the Skill tool with skill name `trailhead-capture` and arguments `note $ARGUMENTS`, then **read the skill's `references/capture.md` and follow it**: that file holds the full protocol for the capture verbs. Do not re-implement the behaviour here. The skill is the single source of truth.

package/plugins/trailhead/commands/pause.md

@@ -3,4 +3,4 @@ description: Checkpoint the ticket in play so it can be resumed later
 argument-hint: "[note]"
 ---
 
-Invoke the `trailhead` skill for the **pause** action: call the Skill tool with skill name `trailhead` and arguments `pause $ARGUMENTS`, then **read the skill's `references/teamwork.md` and follow it**: that file holds the pausing & resuming protocol (including, under `isolation: worktree`/`clone`, committing the work-in-progress in the ticket's isolated workspace and recording its path in the checkpoint). Do not re-implement the behaviour here. The skill is the single source of truth.
+Invoke the `trailhead` skill for the **pause** action: call the Skill tool with skill name `trailhead-work` and arguments `pause $ARGUMENTS`, then **read the teamwork reference the skill points to (`../_shared/teamwork.md`) and follow it**: that file holds the pausing & resuming protocol (including, under `isolation: worktree`/`clone`, committing the work-in-progress in the ticket's isolated workspace and recording its path in the checkpoint). Do not re-implement the behaviour here. The skill is the single source of truth.

package/plugins/trailhead/commands/quick.md

@@ -3,4 +3,6 @@ description: Work one ticket whole, off the map (whiteboard); grills only if nee
 argument-hint: "[ticket | \"text\"]"
 ---
 
-Invoke the `trailhead` skill for the **quick** action: call the Skill tool with skill name `trailhead` and arguments `quick $ARGUMENTS`, then carry out the skill's instructions for that verb (open a `trailhead:whiteboard` ticket from the `"text"`, or take the existing ticket you name, then run the full engine on it without splitting and without map book-keeping). Do not re-implement the behaviour here. The skill is the single source of truth.
+Invoke the `trailhead` skill for the **quick** action: call the Skill tool with skill name `trailhead-work` and arguments `quick $ARGUMENTS`, then carry out the skill's instructions for that verb (open a `trailhead:whiteboard` ticket from the `"text"`, or take the existing ticket you name, then run the full engine on it without splitting and without map book-keeping). Do not re-implement the behaviour here. The skill is the single source of truth.
+
+**When `quick "<text>"` opens a NEW whiteboard ticket, refresh the pinned `trailhead:dashboard` right after the ticket exists** (a structural event: the whiteboard has no native progress bar, so the dashboard is the only place the ticket shows). This is a required step of the create path, not optional; do not skip it. `quick <n>` on an existing *map* ticket does not refresh. See the skill's *quick* section and the dashboard freshness rule.

package/plugins/trailhead/commands/resume.md

@@ -3,4 +3,4 @@ description: Resume a paused ticket from its checkpoint
 argument-hint: "[ticket]"
 ---
 
-Invoke the `trailhead` skill for the **resume** action: call the Skill tool with skill name `trailhead` and arguments `resume $ARGUMENTS`, then **read the skill's `references/teamwork.md` and follow it**: that file holds the pausing & resuming protocol (including, under `isolation: worktree`/`clone`, re-entering the ticket's isolated workspace recorded in its checkpoint). Do not re-implement the behaviour here. The skill is the single source of truth.
+Invoke the `trailhead` skill for the **resume** action: call the Skill tool with skill name `trailhead-work` and arguments `resume $ARGUMENTS`, then **read the teamwork reference the skill points to (`../_shared/teamwork.md`) and follow it**: that file holds the pausing & resuming protocol (including, under `isolation: worktree`/`clone`, re-entering the ticket's isolated workspace recorded in its checkpoint). Do not re-implement the behaviour here. The skill is the single source of truth.

package/plugins/trailhead/commands/seed.md

@@ -3,4 +3,4 @@ description: "Capture a seed: work gated on a future trigger"
 argument-hint: "<text>"
 ---
 
-Invoke the `trailhead` skill for the **seed** action: call the Skill tool with skill name `trailhead` and arguments `seed $ARGUMENTS`, then **read the skill's `references/capture.md` and follow it**: that file holds the full protocol for the capture verbs. Do not re-implement the behaviour here. The skill is the single source of truth.
+Invoke the `trailhead` skill for the **seed** action: call the Skill tool with skill name `trailhead-capture` and arguments `seed $ARGUMENTS`, then **read the skill's `references/capture.md` and follow it**: that file holds the full protocol for the capture verbs. Do not re-implement the behaviour here. The skill is the single source of truth.

package/plugins/trailhead/commands/split.md

@@ -3,4 +3,4 @@ description: Split an oversized ticket into children and supersede it
 argument-hint: "[ticket]"
 ---
 
-Invoke the `trailhead` skill for the **split** action: call the Skill tool with skill name `trailhead` and arguments `split $ARGUMENTS`, then **read the skill's `references/teamwork.md` and follow it**: that file holds the splitting protocol. Do not re-implement the behaviour here. The skill is the single source of truth.
+Invoke the `trailhead` skill for the **split** action: call the Skill tool with skill name `trailhead-work` and arguments `split $ARGUMENTS`, then **read the teamwork reference the skill points to (`../_shared/teamwork.md`) and follow it**: that file holds the splitting protocol. Do not re-implement the behaviour here. The skill is the single source of truth.

package/plugins/trailhead/commands/ticket.md

@@ -3,4 +3,4 @@ description: Open a ticket of any type on the fly (diverges briefly first)
 argument-hint: "<type> <title>"
 ---
 
-Invoke the `trailhead` skill for the **ticket** action: call the Skill tool with skill name `trailhead` and arguments `ticket $ARGUMENTS`, then carry out the skill's instructions for that verb. Do not re-implement the behaviour here. The skill is the single source of truth.
+Invoke the `trailhead` skill for the **ticket** action: call the Skill tool with skill name `trailhead-chart` and arguments `ticket $ARGUMENTS`, then carry out the skill's instructions for that verb. Do not re-implement the behaviour here. The skill is the single source of truth.

package/plugins/trailhead/commands/todo.md

@@ -3,4 +3,4 @@ description: "Capture a small build ticket: defined work you will do now"
 argument-hint: "<text>"
 ---
 
-Invoke the `trailhead` skill for the **todo** action: call the Skill tool with skill name `trailhead` and arguments `todo $ARGUMENTS`, then **read the skill's `references/capture.md` and follow it**: that file holds the full protocol for the capture verbs. Do not re-implement the behaviour here. The skill is the single source of truth.
+Invoke the `trailhead` skill for the **todo** action: call the Skill tool with skill name `trailhead-capture` and arguments `todo $ARGUMENTS`, then **read the skill's `references/capture.md` and follow it**: that file holds the full protocol for the capture verbs. Do not re-implement the behaviour here. The skill is the single source of truth.

package/plugins/trailhead/commands/update.md

@@ -2,4 +2,4 @@
 description: Check for a newer trailhead and install it
 ---
 
-Invoke the `trailhead` skill for the **update** action: call the Skill tool with skill name `trailhead` and arguments `update $ARGUMENTS`, then **read the skill's `references/updating.md` and follow it**: that file holds the update protocol (detect the install channel, compare versions, install the newer one where it is safe). Do not re-implement the behaviour here. The skill is the single source of truth.
+Invoke the `trailhead` skill for the **update** action: call the Skill tool with skill name `trailhead-manage` and arguments `update $ARGUMENTS`, then **read the skill's `references/updating.md` and follow it**: that file holds the update protocol (detect the install channel, compare versions, install the newer one where it is safe). Do not re-implement the behaviour here. The skill is the single source of truth.

package/plugins/trailhead/commands/whiteboard.md

@@ -3,4 +3,4 @@ description: "Show the whiteboard: loose (map-less) tickets, their frontier and
 argument-hint: ""
 ---
 
-Invoke the `trailhead` skill for the **whiteboard** action: call the Skill tool with skill name `trailhead` and arguments `whiteboard $ARGUMENTS`, then carry out the skill's instructions for that verb (render the read-only whiteboard dashboard: the frontier, in-progress, and blocked `trailhead:whiteboard` tickets). Do not re-implement the behaviour here. The skill is the single source of truth.
+Invoke the `trailhead` skill for the **whiteboard** action: call the Skill tool with skill name `trailhead-view` and arguments `whiteboard $ARGUMENTS`, then carry out the skill's instructions for that verb (render the read-only whiteboard dashboard: the frontier, in-progress, and blocked `trailhead:whiteboard` tickets). Do not re-implement the behaviour here. The skill is the single source of truth.

package/plugins/trailhead/commands/work.md

@@ -3,4 +3,4 @@ description: Work the next frontier ticket, or the one you name
 argument-hint: "[ticket]"
 ---
 
-Invoke the `trailhead` skill for the **work** action: call the Skill tool with skill name `trailhead` and arguments `work $ARGUMENTS`, then carry out the skill's instructions for that verb (under the repo's `trailhead:conventions` `isolation: worktree` or `clone`, work the ticket in its own isolated workspace on a `trailhead/t<n>` branch, set up at work-start, per `references/teamwork.md`). Do not re-implement the behaviour here. The skill is the single source of truth.
+Invoke the `trailhead` skill for the **work** action: call the Skill tool with skill name `trailhead-work` and arguments `work $ARGUMENTS`, then carry out the skill's instructions for that verb (under the repo's `trailhead:conventions` `isolation: worktree` or `clone`, work the ticket in its own isolated workspace on a `trailhead/t<n>` branch, set up at work-start, per the skill's teamwork reference). Do not re-implement the behaviour here. The skill is the single source of truth.

package/plugins/trailhead/hooks/hooks.json

@@ -11,6 +11,10 @@
           {
             "type": "command",
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/trailhead-secret-guard.js\""
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/trailhead-install-guard.js\""
           }
         ]
       }

package/plugins/trailhead/hooks/trailhead-commit-guard.js

@@ -56,7 +56,7 @@ process.stdin.on('end', () => {
 
     const msg = extractMessage(cmd);
     if (msg) {
-      // stripComments:false — this is the literal `-m` value, where git keeps
+      // stripComments:false, this is the literal `-m` value, where git keeps
       // `#` lines as message text (cleanup=whitespace), so a `#…` first line is
       // a real subject to validate, not a comment to skip.
       const verdict = checkCommitMessage(msg, { stripComments: false });