@marcomigozzi/trailhead 0.5.0 → 0.6.0

package/bin/trailhead.js

@@ -172,10 +172,11 @@ function claudePaths(configDir) {
     commands: path.join(configDir, 'commands', 'trailhead'),
     hooksDir: path.join(configDir, 'hooks'),
     templates: path.join(configDir, 'trailhead', 'templates'),
+    agents: path.join(configDir, 'agents'),
     settings: path.join(configDir, 'settings.json'),
   };
 }
-const HOOK_FILES = ['trailhead-commit-guard.js', 'trailhead-issue-injection-scanner.js', 'trailhead-secret-guard.js', 'trailhead-check-update.js'];
+const HOOK_FILES = ['trailhead-commit-guard.js', 'trailhead-issue-injection-scanner.js', 'trailhead-secret-guard.js', 'trailhead-install-guard.js', 'trailhead-check-update.js'];
 // Runtime libs the hook scripts require (trailhead-commit-guard.js does
 // require('./lib/commit-message-check.js')). Copied by name, never a recursive
 // sweep: the Claude hooks/lib dir is shared with other plugins, so we must not
@@ -217,6 +218,43 @@ function place(src, dest, symlink) {
   else fs.cpSync(src, dest, { recursive: true });
 }
 
+// The committed engine agents (plugins/trailhead/agents/trailhead-*.md). On a
+// Claude install they must register as user subagent types under
+// <configDir>/agents/, so the engine can dispatch each technique to its
+// trailhead-<technique> agent and honour config.models.<key>; without them
+// every technique falls back to running inline on the session model (the
+// per-technique model split silently never applies). The agents dir is shared
+// with the user's own agents and other plugins, so touch trailhead's own files
+// by name only, never the whole dir (mirrors the skills/hooks discipline).
+function agentFileNames() {
+  const dir = path.join(SRC, 'agents');
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).filter((f) => f.startsWith('trailhead-') && f.endsWith('.md'));
+}
+function sweepTrailheadAgents(agentsDir) {
+  if (!fs.existsSync(agentsDir)) return;
+  for (const f of fs.readdirSync(agentsDir)) {
+    if (f.startsWith('trailhead-') && f.endsWith('.md')) rmrf(path.join(agentsDir, f));
+  }
+}
+// Place the engine agents into destAgentsDir by name (copy, or per-file symlink
+// under a --symlink dev install so agent edits are live). Returns the names
+// placed. rmrf each dest first so a reinstall over a file or symlink never
+// hits EEXIST.
+function copyAgentFiles(destAgentsDir, { useSymlink = false } = {}) {
+  const names = agentFileNames();
+  if (!names.length) return names;
+  ensure(destAgentsDir);
+  for (const f of names) {
+    const src = path.join(SRC, 'agents', f);
+    const dest = path.join(destAgentsDir, f);
+    rmrf(dest);
+    if (useSymlink) fs.symlinkSync(src, dest, 'file');
+    else fs.copyFileSync(src, dest);
+  }
+  return names;
+}
+
 function addHook(s, event, matcher, command) {
   s.hooks = s.hooks || {};
   s.hooks[event] = s.hooks[event] || [];
@@ -239,6 +277,9 @@ function uninstallClaude(configDir) {
   // layout left that this package no longer ships), never the shared dir itself.
   sweepTrailheadSkills(path.join(configDir, 'skills'));
   [P.commands, path.join(configDir, 'trailhead')].forEach(rmrf);
+  // Remove trailhead's own agents by name; the agents dir is shared, so never
+  // rmrf the whole dir (same discipline as skills/hooks).
+  sweepTrailheadAgents(P.agents);
   HOOK_FILES.forEach((f) => rmrf(path.join(P.hooksDir, f)));
   // Remove only trailhead's own lib files by name: the hooks/lib dir is shared
   // with other plugins, so never rmrf the whole dir.
@@ -246,6 +287,7 @@ function uninstallClaude(configDir) {
   const s = readJSON(P.settings);
   stripHook(s, 'PreToolUse', 'trailhead-commit-guard.js');
   stripHook(s, 'PreToolUse', 'trailhead-secret-guard.js');
+  stripHook(s, 'PreToolUse', 'trailhead-install-guard.js');
   stripHook(s, 'PostToolUse', 'trailhead-issue-injection-scanner.js');
   stripHook(s, 'SessionStart', 'trailhead-check-update.js');
   writeJSON(P.settings, s);
@@ -271,6 +313,14 @@ function installClaude(configDir, { useSymlink }) {
   place(path.join(SRC, 'commands'), P.commands, useSymlink);
   place(path.join(SRC, 'templates'), P.templates, useSymlink);
   copyHookScripts(P.hooksDir, { useSymlink });
+  // Register the engine agents as Claude subagents: sweep any stale
+  // trailhead-*.md first (a removed/renamed agent), then place the current set
+  // by name. This is what makes config.models.<key> take effect on the
+  // skills/npm channel; without it every technique runs inline (see
+  // agentFileNames above). The agents dir is shared, so only our names are
+  // touched.
+  sweepTrailheadAgents(P.agents);
+  const agentFiles = copyAgentFiles(P.agents, { useSymlink });
   // version marker: serve al check-update hook per la versione installata (canale npm)
   const pkgVersion = (readJSON(path.join(SRC, '.claude-plugin', 'plugin.json')).version || '').trim();
   if (pkgVersion) {
@@ -282,6 +332,7 @@ function installClaude(configDir, { useSymlink }) {
   const added = [
     addHook(s, 'PreToolUse', 'Bash', hookCmd('trailhead-commit-guard.js')),
     addHook(s, 'PreToolUse', 'Bash', hookCmd('trailhead-secret-guard.js')),
+    addHook(s, 'PreToolUse', 'Bash', hookCmd('trailhead-install-guard.js')),
     addHook(s, 'PostToolUse', 'Bash', hookCmd('trailhead-issue-injection-scanner.js')),
     addHook(s, 'SessionStart', '', hookCmd('trailhead-check-update.js')),
   ].some(Boolean);
@@ -290,6 +341,7 @@ function installClaude(configDir, { useSymlink }) {
   console.log(`✓ trailhead installed for Claude Code → ${configDir}`);
   console.log(`  skills    → ${path.join(configDir, 'skills')}/  (${skillDirs.join(', ')})${useSymlink ? '  (symlink)' : ''}`);
   console.log(`  commands  → ${P.commands}  (/trailhead:*)`);
+  console.log(`  agents    → ${P.agents}/  (${agentFiles.length} agent(s): trailhead-*)${useSymlink ? '  (symlink)' : ''}`);
   console.log(`  hooks     → ${P.hooksDir}/  (${added ? 'registered' : 'already present'} in settings.json)`);
   console.log(`  templates → ${P.templates}`);
   console.log('\nRestart or reload your agent to pick up the commands, then run /trailhead to start.');
@@ -349,6 +401,39 @@ function readCommandVerbs() {
     .sort((a, b) => a.verb.localeCompare(b.verb));
 }
 
+// Unquote a YAML double-quoted scalar (unlike commands/*.md, the agent .md
+// frontmatter wraps `description:` in double quotes). Leaves a plain/
+// unquoted scalar untouched, so this is safe to apply unconditionally.
+function unquoteYamlScalar(v) {
+  if (typeof v !== 'string' || v.length < 2 || v[0] !== '"' || v[v.length - 1] !== '"') return v;
+  return v.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+}
+
+// Read the 8 committed agent sources from plugins/trailhead/agents/*.md: each
+// file's basename is the agent's name; frontmatter description/tools ride
+// along, and `body` is the markdown after the closing frontmatter `---`.
+// Single-sources the Codex agent-TOML projection so it never drifts from the
+// committed agent prose. Mirrors readCommandVerbs's shape. Pure fs; kept out
+// of codex-projection.js, which must stay fs-free.
+function readAgentDefs() {
+  const dir = path.join(SRC, 'agents');
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((f) => f.startsWith('trailhead-') && f.endsWith('.md'))
+    .map((f) => {
+      const raw = fs.readFileSync(path.join(dir, f), 'utf8');
+      const fm = /^---\r?\n[\s\S]*?\r?\n---[ \t]*\r?\n?/.exec(raw);
+      const body = fm ? raw.slice(fm[0].length) : raw;
+      return {
+        name: f.slice(0, -3),
+        description: unquoteYamlScalar(fmValue(raw, 'description')),
+        tools: fmValue(raw, 'tools'),
+        body,
+      };
+    })
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
 // Extract one frontmatter scalar's raw value verbatim (an already-valid YAML
 // scalar re-serialises unchanged). Looks only inside the leading ---...--- block.
 // Returns undefined when the key is absent or its value is empty.
@@ -464,9 +549,13 @@ function installCodex(configDir, { useSymlink }) {
     featureManual = true;
   }
 
-  // Per-technique model pins: project models.codex.* (merged project + global
-  // config) into trailhead-<technique>.toml under the real ~/.codex/agents/
-  // dir. Sweep only trailhead's own files first, so a stale pin from a prior
+  // Per-technique agent registry: project ALL 8 committed agents
+  // (readAgentDefs, sourced from plugins/trailhead/agents/*.md) as
+  // trailhead-<technique>.toml under the real ~/.codex/agents/ dir, uniformly.
+  // A keyed technique (plan/execute/research/review/debug/verify/codebase-map)
+  // carries its models.codex.<key> pin (merged project + global config) when
+  // set, else is pin-less; the 1 keyless agent (fix) is always pin-less.
+  // Sweep only trailhead's own files first, so a stale pin from a prior
   // install (or a removed technique) never lingers, without touching the
   // user's other custom-agent TOMLs.
   const codexModels = readCodexModels(configDir);
@@ -474,16 +563,15 @@ function installCodex(configDir, { useSymlink }) {
   for (const f of fs.readdirSync(L.codexAgentsDir)) {
     if (/^trailhead-.*\.toml$/.test(f)) rmrf(path.join(L.codexAgentsDir, f));
   }
-  const plan = codexAgentTomlPlan(configDir, codexModels);
+  const plan = codexAgentTomlPlan(configDir, codexModels, readAgentDefs());
   for (const w of plan.writes) fs.writeFileSync(w.path, w.content);
 
   // Feature flag: Codex gates per-subagent model pinning behind
-  // features.multi_agent_v2 = true. Enable it ONLY when we actually projected
-  // pins: with no models.codex.* set, base multi_agent already fans out and the
-  // adapter's §D runtime detection expects no trailhead agent_type registry, so
-  // leaving v2 off keeps that contract sound. (A reinstall that drops all pins
-  // sweeps the TOMLs above but leaves any prior v2 flag in place; harmless, as
-  // no trailhead-* agents remain for the runtime to dispatch to.)
+  // features.multi_agent_v2 = true. All 7 agent TOMLs are normally projected
+  // (pinned or pin-less), so v2 is enabled on every healthy Codex install: the
+  // adapter's §D runtime detection expects a trailhead agent_type registry,
+  // pins or not. Still guarded on writes so a degenerate case (no agent .md
+  // found, zero writes) never flips the flag on with an empty registry.
   let featureManualV2 = false;
   if (plan.writes.length > 0) {
     const updatedTomlV2 = enableCodexMultiAgentV2Feature(current);
@@ -500,10 +588,12 @@ function installCodex(configDir, { useSymlink }) {
   console.log(`  templates → ${L.templatesDir}/`);
   console.log(`  verb skills → ${L.skillsRoot}/trailhead-<verb>/  (${verbSkillPlan.dirs.length} discoverability skills: invoke $trailhead-<verb>)`);
   console.log(`  hooks     → ${L.hooksScriptsDir}/  (registered in hooks.json)`);
-  if (plan.writes.length > 0) {
-    console.log(`  agents    → ${L.codexAgentsDir}/  (${plan.writes.length} model pin(s): ${plan.writes.map((w) => w.name + '.toml').join(', ')})`);
-  } else {
-    console.log('  agents    → no models.codex.* set, subagents inherit the session model');
+  {
+    const pinned = plan.writes.filter((w) => w.content.includes('\nmodel = '));
+    const pinsNote = pinned.length > 0
+      ? `${pinned.length} pinned: ${pinned.map((w) => w.name + '.toml').join(', ')}`
+      : 'no models.codex.* set, all pin-less (session model)';
+    console.log(`  agents    → ${L.codexAgentsDir}/  (${plan.writes.length} agent(s) projected; ${pinsNote})`);
   }
   console.log('\nRestart or reload Codex to pick up the skill, then run $trailhead to start.');
   // The trust prompt only fires once the feature flag is on. When we could not
@@ -545,6 +635,7 @@ function uninstallCodex(configDir) {
     const h = readJSON(L.hooksJson);
     stripHook(h, 'PreToolUse', 'trailhead-commit-guard.js');
     stripHook(h, 'PreToolUse', 'trailhead-secret-guard.js');
+    stripHook(h, 'PreToolUse', 'trailhead-install-guard.js');
     stripHook(h, 'PostToolUse', 'trailhead-issue-injection-scanner.js');
     stripHook(h, 'SessionStart', 'trailhead-check-update.js');
     writeJSON(L.hooksJson, h);

package/bin/trailhead.test.js

@@ -131,11 +131,19 @@ 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 8 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 --symlink: link verbatim artifacts (hooks + templates), keep skills projected ---
 const codexSymDir = mktmp();
@@ -161,12 +169,31 @@ ok('codex copy: hooks are regular files (not symlinks)',
 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) -----------------------------------------
-// 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)));
+// --- codex agent TOML projection (#38, #88) -------------------------------------
+// With NO models.codex.* set, a codex install still projects all 8 agents
+// uniformly, pin-less (uniform projection, #88), never zero. Install from an
+// isolated cwd whose .trailhead/config.json sets no models.codex.*, not
+// repoRoot (whose own config now pins models.codex.*, so it would project
+// pinned TOMLs rather than pin-less ones).
+const unsetProjectDir = mktmp();
+fs.mkdirSync(path.join(unsetProjectDir, '.trailhead'), { recursive: true });
+fs.writeFileSync(
+  path.join(unsetProjectDir, '.trailhead', 'config.json'),
+  JSON.stringify({ models: {} }, null, 2) + '\n'
+);
+const unsetCodexHomeDir = mktmp();
+runInstaller([`--codex`, `--dir=${unsetCodexHomeDir}`], { cwd: unsetProjectDir });
+ok('codex: all 8 trailhead-*.toml exist under agents/ even with models.codex.* unset', (() => {
+  const dir = path.join(unsetCodexHomeDir, 'agents');
+  if (!fs.existsSync(dir)) return false;
+  const tomls = fs.readdirSync(dir).filter((f) => /^trailhead-.*\.toml$/.test(f));
+  return tomls.length === 8;
+})());
+ok('codex: every trailhead-*.toml is pin-less when models.codex.* is unset', (() => {
+  const dir = path.join(unsetCodexHomeDir, '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();
@@ -236,6 +263,20 @@ 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}`]);
@@ -260,6 +301,11 @@ ok('claude symlink: a symlinked commit-guard still loads its lib (no MODULE_NOT_
 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());
@@ -283,6 +329,14 @@ ok('claude migration: stale trailhead-legacy cluster swept on reinstall', !fs.ex
 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.
@@ -305,6 +359,17 @@ 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}`]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marcomigozzi/trailhead",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "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"
@@ -30,5 +30,5 @@
     "type": "git",
     "url": "git+https://github.com/ToRvaLDz/trailhead.git"
   },
-  "homepage": "https://github.com/ToRvaLDz/trailhead"
+  "homepage": "https://trailhead.marcomigozzi.it"
 }

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

@@ -1,6 +1,6 @@
 {
   "name": "trailhead",
-  "version": "0.4.0",
+  "version": "0.6.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. Ships as a dispatcher plus cohesion-clustered skills over a shared core; depends on nothing beyond an authenticated gh CLI.",
   "author": {
     "name": "Marco Migozzi",

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

@@ -0,0 +1,10 @@
+---
+name: trailhead-code-review
+color: purple
+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,10 @@
+---
+name: trailhead-codebase-map
+color: yellow
+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,10 @@
+---
+name: trailhead-debug
+color: red
+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,10 @@
+---
+name: trailhead-executor
+color: orange
+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,10 @@
+---
+name: trailhead-fix
+color: green
+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,10 @@
+---
+name: trailhead-plan
+color: blue
+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,10 @@
+---
+name: trailhead-research
+color: cyan
+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/agents/trailhead-verify.md

@@ -0,0 +1,10 @@
+---
+name: trailhead-verify
+color: pink
+description: "trailhead verify subagent: goal-backward check that a ticket's change delivers what it promised. Read-only, never edits or commits."
+tools: Read, Grep, Glob, Bash, WebFetch, WebSearch, TodoWrite
+---
+
+trailhead's verification subagent. Run the Goal-backward verification: check that the ticket's implemented change actually delivers what the ticket promised (its `Question` and the `PLAN`'s verification criteria), not merely that steps ran or the tests are green. Report the verdict into trailhead's `VERIFY` comment with a leading `status:` tag.
+
+The full protocol is injected at spawn from the trailhead skill's single source (`_shared/techniques/verify.md`); follow that, not any embedded copy. Read-only by policy: it verifies and reports, it must never Edit/Write or commit. Model-agnostic by design: the engine passes the `config.models.verify` model as the spawn-time override, so config stays authoritative.

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\""
           }
         ]
       }