specpipe 1.0.0 → 1.0.2

package/src/lib/agent-install.js

@@ -2,8 +2,8 @@ import { existsSync } from 'node:fs';
 import { mkdir, readFile, writeFile, unlink, chmod, rmdir } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
 import { log } from './logger.js';
-import { getTemplateDir, COMPONENTS } from './installer.js';
-import { emitSkillFile, emitRules, emitHooks, AGENTS, GUARDS_BEGIN, GUARDS_END } from './agents.js';
+import { getTemplateDir, COMPONENTS, skillAllowed } from './installer.js';
+import { emitSkillFile, emitRules, emitHooks, AGENTS, RULES_BEGIN, RULES_END } from './agents.js';
 
 /**
  * Emit one canonical skill file for a target agent and write it to targetDir.
@@ -38,10 +38,16 @@ export async function installSkillForAgent(agentId, canonicalRel, targetDir, { f
  * Install the full skill set for one agent into targetDir.
  * @returns {{ agent: string, copied: number, skipped: number, identical: number, paths: string[] }}
  */
-export async function installAgentSkills(agentId, targetDir, { force = false } = {}) {
+export async function installAgentSkills(agentId, targetDir, { force = false, skills = null } = {}) {
   let copied = 0, skipped = 0, identical = 0;
   const paths = [];
+  // Hermes (and any perProjectSkills:false agent) reads skills only from its global dir,
+  // never the project — emitting per-project skill files here would be dead. Skip them.
+  if (AGENTS[agentId]?.perProjectSkills === false) {
+    return { agent: agentId, label: AGENTS[agentId].label, copied, skipped, identical, paths };
+  }
   for (const relPath of COMPONENTS.skills) {
+    if (!skillAllowed(relPath, skills)) continue;
     const { result, path } = await installSkillForAgent(agentId, relPath, targetDir, { force });
     if (result === 'copied') copied++;
     else if (result === 'identical') identical++;
@@ -51,31 +57,32 @@ export async function installAgentSkills(agentId, targetDir, { force = false } =
   return { agent: agentId, label: AGENTS[agentId].label, copied, skipped, identical, paths };
 }
 
-const GUARDS_TEMPLATE_REL = 'rules/specpipe-guards.md';
+const RULES_TEMPLATE_REL = 'rules/specpipe-rules.md';
 
-function guardsSectionRegex() {
+function rulesSectionRegex() {
   const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  return new RegExp(esc(GUARDS_BEGIN) + '[\\s\\S]*?' + esc(GUARDS_END) + '\\n?', '');
+  return new RegExp(esc(RULES_BEGIN) + '[\\s\\S]*?' + esc(RULES_END) + '\\n?', '');
 }
 
-/** Merge (or replace) the specpipe guards section in a shared AGENTS.md. */
-export async function mergeAgentsMdGuards(targetDir, section) {
-  const p = join(targetDir, 'AGENTS.md');
+/** Merge (or replace) the specpipe rules section in a shared file (CLAUDE.md / AGENTS.md). */
+export async function mergeRulesSection(targetDir, fileRel, section) {
+  const p = join(targetDir, fileRel);
   let existing = '';
   try { existing = await readFile(p, 'utf-8'); } catch { /* new file */ }
-  const re = guardsSectionRegex();
+  const re = rulesSectionRegex();
   existing = re.test(existing)
     ? existing.replace(re, section)
     : (existing.trim() ? existing.trimEnd() + '\n\n' : '') + section;
+  await mkdir(dirname(p), { recursive: true });
   await writeFile(p, existing);
 }
 
-/** Remove the specpipe guards section from AGENTS.md (deletes file if now empty). */
-export async function stripAgentsMdGuards(targetDir) {
-  const p = join(targetDir, 'AGENTS.md');
+/** Remove the specpipe rules section from a shared file (deletes it if now empty). */
+export async function stripRulesSection(targetDir, fileRel) {
+  const p = join(targetDir, fileRel);
   let existing;
   try { existing = await readFile(p, 'utf-8'); } catch { return false; }
-  const stripped = existing.replace(guardsSectionRegex(), '').trim();
+  const stripped = existing.replace(rulesSectionRegex(), '').trim();
   if (stripped === existing.trim()) return false;
   if (stripped) await writeFile(p, stripped + '\n');
   else await unlink(p);
@@ -83,19 +90,19 @@ export async function stripAgentsMdGuards(targetDir) {
 }
 
 /**
- * Install an agent's guardrails: an owned rules file (Cursor/Antigravity/
- * OpenClaw/Hermes) or a merged section in a shared AGENTS.md (Codex).
- * Claude returns null — it uses native hooks instead.
+ * Install an agent's guardrails: a merged section in a shared file (Claude →
+ * .claude/CLAUDE.md, Codex → AGENTS.md) or an owned rules file (Cursor/
+ * Antigravity/OpenClaw/Hermes). Returns null only if the agent has no rules entry.
  */
 export async function installAgentRules(agentId, targetDir, { force = false } = {}) {
-  const body = await readFile(join(getTemplateDir(), GUARDS_TEMPLATE_REL), 'utf-8');
+  const body = await readFile(join(getTemplateDir(), RULES_TEMPLATE_REL), 'utf-8');
   const r = emitRules(agentId, body);
   if (!r) return null;
 
-  if (r.mode === 'agents-md') {
-    await mergeAgentsMdGuards(targetDir, r.content);
+  if (r.mode === 'merge') {
+    await mergeRulesSection(targetDir, r.path, r.content);
     log.copy(`${r.path} (specpipe operating-rules section)`);
-    return { mode: 'agents-md', path: r.path };
+    return { mode: 'merge', path: r.path };
   }
 
   const dst = join(targetDir, r.path);
@@ -117,12 +124,13 @@ export async function installAgentRules(agentId, targetDir, { force = false } =
 
 /**
  * Install an agent's ENFORCED (blocking) hooks: the guard scripts + the agent's
- * hook config file. Codex/Cursor only (verified payloads). Returns null otherwise.
+ * hook config file. Agents with a verified hook config (Claude/Codex/Cursor/
+ * Antigravity); returns null for agents without one.
  * The hook config is specpipe-owned; if a different one already exists, we skip
  * unless --force (don't clobber a user's hooks).
  */
-export async function installAgentHooks(agentId, targetDir, { force = false } = {}) {
-  const h = emitHooks(agentId);
+export async function installAgentHooks(agentId, targetDir, { force = false, hooks = null } = {}) {
+  const h = emitHooks(agentId, hooks);
   if (!h) return null;
 
   for (const { src, dst } of h.scripts) {
@@ -151,11 +159,16 @@ export async function installAgentHooks(agentId, targetDir, { force = false } =
   return { configPath: h.configPath };
 }
 
-/** Remove an agent's enforced-hook scripts + config (+ empty hooks dir). */
+/** Remove an agent's enforced-hook scripts + config (+ empty hooks/agent dirs). */
 export async function removeAgentHooks(agentId, targetDir) {
   const h = emitHooks(agentId);
   if (!h) return;
   for (const { dst } of h.scripts) { try { await unlink(join(targetDir, dst)); } catch { /* */ } }
   try { await unlink(join(targetDir, h.configPath)); } catch { /* */ }
   try { await rmdir(join(targetDir, h.hooksDir)); } catch { /* not empty / missing */ }
+  // Tidy the agent's container dir too (e.g. .codex/, .agents/) — its only specpipe
+  // content was the hook config + hooks/. rmdir is a no-op when the dir still holds
+  // other content (.claude/CLAUDE.md, .cursor/rules/, .agents/skills/ for a kept agent).
+  const agentDir = dirname(h.configPath);
+  if (agentDir && agentDir !== '.') { try { await rmdir(join(targetDir, agentDir)); } catch { /* not empty / missing */ } }
 }

package/src/lib/agents.js

@@ -91,7 +91,8 @@ export const AGENTS = {
     label: 'Claude Code',
     // Verified: code.claude.com/docs/en/skills
     skillTarget: (name, inner) => `.claude/skills/${name}/${inner}`,
-    globalRoot: '.claude/skills',
+    // Global (user-level) skills dir, relative to home. Verified: ~/.claude/skills/.
+    globalSkillRoot: '.claude/skills',
     skillFile: 'SKILL.md',
     hooks: 'native',
     capabilities: 'full',
@@ -104,9 +105,12 @@ export const AGENTS = {
     label: 'Antigravity',
     // Verified: official Google Codelab — .agents/skills/<name>/SKILL.md
     skillTarget: (name, inner) => `.agents/skills/${name}/${inner}`,
-    globalRoot: '.agents/skills',
+    // Global differs from the project path: Antigravity CLI reads ~/.gemini/antigravity-cli/skills/
+    // (the IDE uses ~/.gemini/config/skills/ and also reads ~/.agents/skills/). Verified: Google
+    // Antigravity codelab. We target the CLI's global dir.
+    globalSkillRoot: '.gemini/antigravity-cli/skills',
     skillFile: 'SKILL.md',
-    hooks: 'rules', // guards emitted to .agent/rules/ (plain markdown)
+    hooks: 'rules', // guards emitted to .agents/rules/ (plain markdown)
     capabilities: 'router-no-hooks',
     emitFrontmatter: fmNameDesc,
   },
@@ -114,7 +118,9 @@ export const AGENTS = {
     label: 'OpenClaw',
     // Verified: github.com/openclaw/openclaw  skills/<name>/SKILL.md
     skillTarget: (name, inner) => `skills/${name}/${inner}`,
-    globalRoot: 'skills',
+    // Verified (docs.openclaw.ai): global skills live in ~/.openclaw/skills/ (the `--global`
+    // target; OpenClaw also reads ~/.agents/skills/).
+    globalSkillRoot: '.openclaw/skills',
     skillFile: 'SKILL.md',
     hooks: 'none',
     capabilities: 'router-no-hooks',
@@ -122,9 +128,14 @@ export const AGENTS = {
   },
   hermes: {
     label: 'Hermes-Agent',
-    // Verified: github.com/NousResearch/hermes-agent  optional-skills/<cat>/<name>/SKILL.md
-    skillTarget: (name, inner) => `optional-skills/specpipe/${name}/${inner}`,
-    globalRoot: 'optional-skills/specpipe',
+    // Hermes discovers skills ONLY from ~/.hermes/skills/ ("the primary directory and source
+    // of truth") + explicitly-configured external_dirs — it does NOT scan the project/workspace.
+    // So per-project skill files are dead (never read); Hermes is global-only for skills. The
+    // skillTarget is still used to shape the GLOBAL emission (globalSkillRoot + name + inner).
+    // Source: hermes-agent.nousresearch.com/docs/user-guide/features/skills
+    skillTarget: (name, inner) => `${name}/${inner}`,
+    perProjectSkills: false,
+    globalSkillRoot: '.hermes/skills',
     skillFile: 'SKILL.md',
     hooks: 'none',
     capabilities: 'router-no-hooks',
@@ -136,7 +147,10 @@ export const AGENTS = {
     // Skills live in the vendor-neutral `.agents/skills/` (NOT `.codex/skills/`, which
     // is a known non-working path — openai/codex#15136). Custom-prompts are deprecated.
     skillTarget: (name, inner) => `.agents/skills/${name}/${inner}`,
-    globalRoot: '.agents/skills',
+    // Global differs from the project path: Codex reads user skills from ~/.codex/skills/
+    // (ships system skills in ~/.codex/skills/.system), NOT ~/.agents/skills/. Verified:
+    // developers.openai.com/codex/skills.
+    globalSkillRoot: '.codex/skills',
     skillFile: 'SKILL.md',
     hooks: 'agents-md', // guards fold into AGENTS.md (plain markdown, no frontmatter)
     capabilities: 'router-no-hooks',
@@ -149,7 +163,10 @@ export const AGENTS = {
     // Skills are on-demand (/skill, @skill) — the correct home, not always-on .mdc rules.
     // Guards stay an always-on .cursor/rules/*.mdc (see RULES.cursor).
     skillTarget: (name, inner) => `.cursor/skills/${name}/${inner}`,
-    globalRoot: '.cursor/skills',
+    // Cursor reads a user-level skills dir at ~/.cursor/skills/ (verified: cursor.com/docs/skills
+    // — it loads .cursor/skills, .agents/skills, ~/.cursor/skills, ~/.agents/skills, plus
+    // .claude/.codex for compat). So `--global` installs Cursor's own global skills here.
+    globalSkillRoot: '.cursor/skills',
     skillFile: 'SKILL.md',
     hooks: 'rules', // advisory now; Cursor DOES support blocking hooks (.cursor/hooks.json) — roadmapped
     capabilities: 'router-no-hooks',
@@ -205,6 +222,26 @@ export function emitSkillFile(agentId, canonicalRel, content) {
   return { path, content: compose(agent.emitFrontmatter(parsed, skill), body) };
 }
 
+/**
+ * Emit one skill file for an agent's GLOBAL (user-level) install. Same per-agent
+ * content transformation as emitSkillFile, but the returned path is rooted at the
+ * agent's home-relative globalSkillRoot — which differs from the project skillTarget
+ * for Codex (~/.codex/skills), Antigravity (~/.gemini/antigravity-cli/skills), etc.
+ * Returns null when the agent has no native global skills dir (Cursor) or the input
+ * isn't a skill file.
+ * @returns {{ path: string, content: string } | null} path is relative to the user's home dir
+ */
+export function emitSkillFileGlobal(agentId, canonicalRel, content) {
+  const agent = AGENTS[agentId];
+  if (!agent) throw new Error(`Unknown agent: ${agentId}`);
+  if (!agent.globalSkillRoot) return null;
+  const parts = parseSkillPath(canonicalRel);
+  if (!parts) return null;
+  const emitted = emitSkillFile(agentId, canonicalRel, content);
+  if (!emitted) return null;
+  return { path: `${agent.globalSkillRoot}/${parts.skill}/${parts.inner}`, content: emitted.content };
+}
+
 /** Tools a canonical skill declares (from its `allowed-tools` frontmatter). */
 function toolsOf(parsed) {
   const block = getKeyBlock(parsed, 'allowed-tools');
@@ -251,7 +288,12 @@ function adaptBody(agentId, body, tools) {
   let out = rewriteAsk(body);
 
   if (has('Agent') || has('Task')) {
-    out = `${out.replace(/\s*$/, '')}\n\n---\n\n## Running on ${AGENTS[agentId].label}\n\n` +
+    // Header is agent-NEUTRAL on purpose: codex and antigravity share the same
+    // emit path (.agents/skills/<name>/), so the caveat must be byte-identical
+    // between them or computeDesired's Map sees divergent content and a clean
+    // install false-flags the file as "customized". The caveat text is already
+    // runtime-agnostic, so a fixed heading loses nothing.
+    out = `${out.replace(/\s*$/, '')}\n\n---\n\n## Running outside Claude Code\n\n` +
       '- **Subagents:** parts of this skill describe Claude subagent orchestration ' +
       '(parallel waves, worktrees, auto-mode dispatch). If your runtime has no ' +
       'subagents, do that work yourself — one item at a time, sequentially, in this ' +
@@ -275,6 +317,6 @@ export function emitFile(agentId, templateRel, content) {
 // Guardrails (advisory rules) + enforced (blocking) hooks live in agent-guards.js;
 // re-exported here so callers keep importing them from agents.js.
 export {
-  GUARDS_BEGIN, GUARDS_END, HOOKS_SRC_DIR,
+  RULES_BEGIN, RULES_END, HOOKS_SRC_DIR,
   agentRulesMode, emitRules, agentHasHooks, emitHooks,
 } from './agent-guards.js';

package/src/lib/claude-global.js

@@ -4,14 +4,12 @@ import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { log } from './logger.js';
 import { getTemplateDir } from './installer.js';
+import { emitSkillFileGlobal } from './agents.js';
+import { buildHookConfig } from './hooks.js';
+import { hashContent } from './hasher.js';
 
-// Claude's global install (~/.claude/skills, ~/.claude/hooks, ~/.claude/settings.json).
-// Claude-only: it's Claude Code's own enforcement engine; other agents have no equivalent.
-
-/** Global skills directory: ~/.claude/skills/ */
-export function getGlobalSkillsDir() {
-  return join(homedir(), '.claude', 'skills');
-}
+// Global install. Skills install per-agent via installSkillGlobalForAgent (below);
+// hooks + settings stay Claude-only (Claude Code's native enforcement engine).
 
 /** Global hooks directory: ~/.claude/hooks/ */
 export function getGlobalHooksDir() {
@@ -19,14 +17,14 @@ export function getGlobalHooksDir() {
 }
 
 /**
- * Copy a hook to the global ~/.claude/hooks/ directory.
- * Strips the '.claude/hooks/' prefix so path-guard.sh lands at ~/.claude/hooks/path-guard.sh.
+ * Copy one guard script (kit-relative src, e.g. 'hooks/specpipe-shell-guard.sh') into
+ * the global ~/.claude/hooks/ dir. `key` is the home-relative manifest key.
  * @returns {{ result: 'copied'|'skipped'|'identical', kitHash: string }}
  */
-export async function installHookGlobal(hookRelPath, globalHooksDir, { force = false, globalFiles = {} } = {}) {
-  const stripped = hookRelPath.replace(/^\.claude\/hooks\//, '');
-  const src = join(getTemplateDir(), hookRelPath);
-  const dst = join(globalHooksDir, stripped);
+export async function installHookGlobal(srcRel, globalHooksDir, { force = false, globalFiles = {}, key } = {}) {
+  const base = srcRel.split('/').pop();
+  const src = join(getTemplateDir(), srcRel);
+  const dst = join(globalHooksDir, base);
 
   const { hashFile } = await import('./hasher.js');
   const srcHash = await hashFile(src);
@@ -35,14 +33,12 @@ export async function installHookGlobal(hookRelPath, globalHooksDir, { force = f
     try {
       const dstHash = await hashFile(dst);
       if (srcHash === dstHash) {
-        log.same(`~/.claude/hooks/${stripped} (identical)`);
+        log.same(`~/.claude/hooks/${base} (identical)`);
         return { result: 'identical', kitHash: srcHash };
       }
-      const savedKitHash = globalFiles[hookRelPath]?.kitHash;
-      if (savedKitHash && dstHash === savedKitHash) {
-        // fall through to copy
-      } else {
-        log.skip(`~/.claude/hooks/${stripped} (customized — use --force to overwrite)`);
+      const savedKitHash = globalFiles[key]?.kitHash;
+      if (!(savedKitHash && dstHash === savedKitHash)) {
+        log.skip(`~/.claude/hooks/${base} (customized — use --force to overwrite)`);
         return { result: 'skipped', kitHash: srcHash };
       }
     } catch { /* hash failed */ }
@@ -51,43 +47,15 @@ export async function installHookGlobal(hookRelPath, globalHooksDir, { force = f
   await mkdir(dirname(dst), { recursive: true });
   await fsCopyFile(src, dst);
   await chmod(dst, 0o755);
-  log.copy(`~/.claude/hooks/${stripped}`);
+  log.copy(`~/.claude/hooks/${base}`);
   return { result: 'copied', kitHash: srcHash };
 }
 
-/** Build hook entries for ~/.claude/settings.json pointing to globalHooksDir. */
-function buildGlobalHookEntries(globalHooksDir) {
-  // Normalize to forward slashes — bash on all platforms (WSL, Git Bash, macOS, Linux)
-  // requires forward slashes even when the host OS is Windows.
+/** Claude settings.json hook entries pointing to the absolute global hooks dir. */
+function buildGlobalHookEntries(globalHooksDir, hooksSet) {
+  // Forward slashes — bash needs them on every host (WSL, Git Bash, macOS, Linux).
   const dir = globalHooksDir.replace(/\\/g, '/');
-  const h = (file) => `"${dir}/${file}"`;
-  return {
-    PreToolUse: [
-      { matcher: 'Bash', hooks: [
-        { type: 'command', command: `bash ${h('path-guard.sh')}` },
-        { type: 'command', command: `bash ${h('sensitive-guard.sh')}` },
-      ]},
-      { matcher: 'Read|Write|Edit|MultiEdit|Grep', hooks: [
-        { type: 'command', command: `bash ${h('sensitive-guard.sh')}` },
-      ]},
-      { matcher: 'Edit|MultiEdit', hooks: [
-        { type: 'command', command: `node ${h('comment-guard.js')}` },
-      ]},
-      { matcher: 'Glob', hooks: [
-        { type: 'command', command: `node ${h('glob-guard.js')}` },
-      ]},
-    ],
-    PostToolUse: [
-      { matcher: 'Write|Edit|MultiEdit', hooks: [
-        { type: 'command', command: `node ${h('file-guard.js')}` },
-      ]},
-    ],
-    Stop: [
-      { matcher: '', hooks: [
-        { type: 'command', command: `bash ${h('self-review.sh')}` },
-      ]},
-    ],
-  };
+  return buildHookConfig('claude', dir, hooksSet)?.hooks || {};
 }
 
 function isDevkitHookCommand(command) {
@@ -113,7 +81,7 @@ function stripDevkitHooks(existingHooks) {
  * Merge devkit hook registrations into ~/.claude/settings.json.
  * Preserves any existing non-devkit hooks the user may have.
  */
-export async function mergeGlobalSettings(globalHooksDir) {
+export async function mergeGlobalSettings(globalHooksDir, hooksSet = null) {
   const settingsPath = join(homedir(), '.claude', 'settings.json');
   let existing = {};
   try {
@@ -121,7 +89,7 @@ export async function mergeGlobalSettings(globalHooksDir) {
   } catch { /* file doesn't exist yet — start fresh */ }
 
   const cleanedHooks = stripDevkitHooks(existing.hooks);
-  const newEntries = buildGlobalHookEntries(globalHooksDir);
+  const newEntries = buildGlobalHookEntries(globalHooksDir, hooksSet);
   const mergedHooks = { ...cleanedHooks };
   for (const [event, entries] of Object.entries(newEntries)) {
     mergedHooks[event] = [...(mergedHooks[event] || []), ...entries];
@@ -147,37 +115,42 @@ export async function removeGlobalHooksFromSettings() {
 }
 
 /**
- * Copy a skill to the global ~/.claude/skills/ directory.
- * Strips the 'skills/' prefix so sp-plan/SKILL.md lands at ~/.claude/skills/sp-plan/SKILL.md.
- * @returns {{ result: 'copied'|'skipped'|'identical', kitHash: string }}
+ * Install one skill file into an agent's GLOBAL (user-level) dir, with the agent's
+ * own content transformation (frontmatter, AskUserQuestion rewrite, subagent caveat).
+ * Works for every agent with a globalSkillRoot — Claude emits identity content, others
+ * get their own frontmatter. Idempotency is keyed on the EMITTED content (which differs
+ * from the kit source for non-Claude agents). The manifest key is the home-relative
+ * emitted path, unique per agent.
+ * @returns {{ result: 'copied'|'skipped'|'identical', kitHash: string, key: string } | null}
+ *   null when the agent has no global dir (Cursor) or the path isn't a skill file.
  */
-export async function installSkillGlobal(skillRelPath, globalSkillsDir, { force = false, globalFiles = {} } = {}) {
-  const stripped = skillRelPath.replace(/^skills\//, '');
-  const src = join(getTemplateDir(), skillRelPath);
-  const dst = join(globalSkillsDir, stripped);
+export async function installSkillGlobalForAgent(agentId, skillRelPath, { force = false, globalFiles = {} } = {}) {
+  const srcContent = await readFile(join(getTemplateDir(), skillRelPath), 'utf-8');
+  const emitted = emitSkillFileGlobal(agentId, skillRelPath, srcContent);
+  if (!emitted) return null;
 
-  const { hashFile } = await import('./hasher.js');
-  const srcHash = await hashFile(src);
+  const dst = join(homedir(), ...emitted.path.split('/'));
+  const display = `~/${emitted.path}`;
+  const key = emitted.path;
+  const srcHash = hashContent(emitted.content);
 
   if (existsSync(dst) && !force) {
     try {
-      const dstHash = await hashFile(dst);
-      if (srcHash === dstHash) {
-        log.same(`~/.claude/skills/${stripped} (identical)`);
-        return { result: 'identical', kitHash: srcHash };
+      const dstHash = hashContent(await readFile(dst, 'utf-8'));
+      if (dstHash === srcHash) {
+        log.same(`${display} (identical)`);
+        return { result: 'identical', kitHash: srcHash, key };
       }
-      const savedKitHash = globalFiles[skillRelPath]?.kitHash;
-      if (savedKitHash && dstHash === savedKitHash) {
-        // fall through to copy
-      } else {
-        log.skip(`~/.claude/skills/${stripped} (customized — use --force to overwrite)`);
-        return { result: 'skipped', kitHash: srcHash };
+      const savedKitHash = globalFiles[key]?.kitHash;
+      if (!(savedKitHash && dstHash === savedKitHash)) {
+        log.skip(`${display} (customized — use --force to overwrite)`);
+        return { result: 'skipped', kitHash: srcHash, key };
       }
-    } catch { /* hash failed, treat as conflict */ }
+    } catch { /* hash failed, treat as conflict → overwrite below */ }
   }
 
   await mkdir(dirname(dst), { recursive: true });
-  await fsCopyFile(src, dst);
-  log.copy(`~/.claude/skills/${stripped}`);
-  return { result: 'copied', kitHash: srcHash };
+  await writeFile(dst, emitted.content);
+  log.copy(display);
+  return { result: 'copied', kitHash: srcHash, key };
 }

package/src/lib/hooks.js

@@ -0,0 +1,203 @@
+// Hook registry — the single source of truth for guard hooks and how each agent
+// declares them. Scripts live in kit/hooks/ and are emitted into each agent's hook
+// dir; each agent's native config file is generated from this map. Formats verified
+// 2026-06-28 against each agent's docs (see docs/multi-agent.md § Sources).
+//
+// Enforced (blocking) agents and their config shapes differ:
+//   claude      .claude/settings.json   {hooks:{Event:[{matcher,hooks:[{type,command}]}]}}
+//   codex       .codex/hooks.json       (same nested shape)              matcher "Bash"
+//   cursor      .cursor/hooks.json      {version:1,hooks:{beforeX:[{command,failClosed}]}}
+//   antigravity .agents/hooks.json      {enabled:true,Event:[{matcher,command,timeout}]}  matcher "run_command"
+//
+// Command payloads the guard scripts read (multi-payload in specpipe-shell-guard.sh):
+//   .tool_input.command (Claude/Codex) · .command (Cursor) · .tool_args.CommandLine (Antigravity)
+
+export const HOOKS_DIR = 'hooks'; // kit-relative source dir for every script
+
+// Each guard hook: its script + which agents wire it, and where.
+//   shell/read run on bash; the JS guards are Claude-only (no equivalent event elsewhere).
+export const HOOKS = {
+  'shell-guard': {
+    script: 'specpipe-shell-guard.sh', run: 'bash',
+    desc: 'block wasteful-dir exploration + secret access in shell commands',
+    wiring: {
+      claude:      { event: 'PreToolUse', matcher: 'Bash', env: { SECRET_POLICY: 'warn' } },
+      codex:       { event: 'PreToolUse', matcher: 'Bash' },
+      cursor:      { event: 'beforeShellExecution' },
+      antigravity: { event: 'PreToolUse', matcher: 'run_command' },
+    },
+  },
+  'read-guard': {
+    script: 'specpipe-read-guard.sh', run: 'bash',
+    desc: 'block reads of secret files',
+    wiring: {
+      claude: { event: 'PreToolUse', matcher: 'Read|Write|Edit|MultiEdit|Grep' },
+      cursor: { event: 'beforeReadFile' },
+    },
+  },
+  'comment-guard': {
+    script: 'comment-guard.js', run: 'node',
+    desc: 'block placeholder-comment replacements',
+    wiring: { claude: { event: 'PreToolUse', matcher: 'Edit|MultiEdit' } },
+  },
+  'glob-guard': {
+    script: 'glob-guard.js', run: 'node',
+    desc: 'block overly broad globs',
+    wiring: { claude: { event: 'PreToolUse', matcher: 'Glob' } },
+  },
+  'file-guard': {
+    script: 'file-guard.js', run: 'node',
+    desc: 'warn on large source files',
+    wiring: {
+      claude: { event: 'PostToolUse', matcher: 'Write|Edit|MultiEdit' },
+      // Cursor: generic postToolUse fires for every tool (no matcher) — the guard
+      // self-filters to writes by tool_name and injects its warning via
+      // `additional_context`. Advisory (never blocks), so no failClosed. Verified
+      // live on Cursor 2026.06: postToolUse payload carries tool_name + tool_input.file_path.
+      cursor: { event: 'postToolUse', advisory: true },
+    },
+  },
+};
+
+export const HOOK_IDS = Object.keys(HOOKS);
+export const ALL_HOOK_NAMES = HOOK_IDS;
+
+/** Agents with a droppable, verified blocking-hook config. */
+export const HOOK_AGENTS = ['claude', 'codex', 'cursor', 'antigravity'];
+
+/**
+ * Resolve a `--hooks` value into a Set of selected hook ids, or null = all.
+ * 'none' → empty Set (option A: install no guard hooks). Accepts ids with or
+ * without the `-guard` suffix (e.g. `shell` or `shell-guard`).
+ */
+export function resolveHooks(spec) {
+  if (spec === undefined || spec === null || spec === 'all') return null;
+  if (spec === 'none') return new Set();
+  const norm = (n) => (HOOKS[n] ? n : (HOOKS[`${n}-guard`] ? `${n}-guard` : n));
+  const names = spec.split(',').map((s) => s.trim()).filter(Boolean).map(norm);
+  const unknown = names.filter((n) => !HOOKS[n]);
+  if (unknown.length) {
+    throw new Error(`Unknown hook(s): ${unknown.join(', ')}. Valid: ${HOOK_IDS.join(', ')}, all, none`);
+  }
+  return new Set(names);
+}
+
+/** Whether a hook id is selected (null = all). */
+export function hookSelected(id, hooksSet) {
+  return !hooksSet || hooksSet.has(id);
+}
+
+/** The hook ids an agent wires, filtered by selection. */
+function wiredHookIds(agentId, hooksSet) {
+  return HOOK_IDS.filter((id) => HOOKS[id].wiring[agentId] && hookSelected(id, hooksSet));
+}
+
+/** Scripts an agent installs (kit-relative src + on-disk dst), filtered by selection. */
+export function hookScriptsFor(agentId, hooksDir, hooksSet = null) {
+  return wiredHookIds(agentId, hooksSet).map((id) => ({
+    src: `${HOOKS_DIR}/${HOOKS[id].script}`,
+    dst: `${hooksDir}/${HOOKS[id].script}`,
+    run: HOOKS[id].run,
+  }));
+}
+
+// Build the command string an agent's config runs for a hook.
+// `ref` is how the agent references the script path (e.g. "$CLAUDE_PROJECT_DIR"/.claude/hooks).
+function commandFor(id, agentId, ref) {
+  const h = HOOKS[id];
+  const env = h.wiring[agentId].env
+    ? Object.entries(h.wiring[agentId].env).map(([k, v]) => `${k}=${v} `).join('')
+    : '';
+  return `${env}${h.run} ${ref}/${h.script}`;
+}
+
+// Where each agent's scripts + config live, and how its config references the
+// scripts. `ref` is per-project; the global Claude install passes an absolute ref.
+export const HOOK_TARGETS = {
+  claude:      { dir: '.claude/hooks', configPath: '.claude/settings.json', ref: '"$CLAUDE_PROJECT_DIR"/.claude/hooks' },
+  codex:       { dir: '.codex/hooks',  configPath: '.codex/hooks.json',     ref: '.codex/hooks' },
+  cursor:      { dir: '.cursor/hooks', configPath: '.cursor/hooks.json',    ref: '.cursor/hooks' },
+  // Antigravity runs hook commands with cwd = <project>/.agents (verified live on 1.0.13),
+  // so the command path is relative to .agents → `hooks/<script>`, NOT `.agents/hooks/<script>`.
+  antigravity: { dir: '.agents/hooks', configPath: '.agents/hooks.json',    ref: 'hooks' },
+};
+
+/**
+ * Generate an agent's native hook-config object from the registry, honoring the
+ * hook selection. `ref` is the path prefix the agent uses to reach the installed
+ * scripts. Returns null when the agent wires no hooks (or selection is empty).
+ * Shapes are per-agent and verified; see the table at the top of the file.
+ */
+export function buildHookConfig(agentId, ref, hooksSet = null) {
+  const ids = wiredHookIds(agentId, hooksSet);
+  if (!ids.length) return null;
+
+  if (agentId === 'claude' || agentId === 'codex') {
+    // { hooks: { Event: [ { matcher, hooks: [ { type:'command', command } ] } ] } }
+    const events = {};
+    for (const id of ids) {
+      const w = HOOKS[id].wiring[agentId];
+      (events[w.event] ??= []).push({
+        matcher: w.matcher,
+        hooks: [{ type: 'command', command: commandFor(id, agentId, ref) }],
+      });
+    }
+    return { hooks: events };
+  }
+
+  if (agentId === 'cursor') {
+    // { version:1, hooks: { beforeShellExecution:[{command,failClosed}], postToolUse:[{command}] } }
+    // Blocking before-hooks use failClosed (deny if the hook errors); advisory post-hooks
+    // (file-guard, which only injects a warning) must NOT — failClosed there would block writes.
+    const events = {};
+    for (const id of ids) {
+      const w = HOOKS[id].wiring.cursor;
+      const entry = { command: `${ref}/${HOOKS[id].script}` };
+      if (!w.advisory) entry.failClosed = true;
+      (events[w.event] ??= []).push(entry);
+    }
+    return { version: 1, hooks: events };
+  }
+
+  if (agentId === 'antigravity') {
+    // { "<hook-name>": { Event: [ { matcher, hooks: [ { type:'command', command, timeout } ] } ] } }
+    // Top level is a MAP of hook-NAME → spec; events nest inside, each an ARRAY of matcher
+    // groups with a nested `hooks` array. NO top-level `enabled` (a bool there makes
+    // Antigravity's Go parser reject the whole file → no hooks load). Verified live against
+    // Antigravity CLI 1.0.13 (jsonhook schema).
+    const events = {};
+    for (const id of ids) {
+      const w = HOOKS[id].wiring.antigravity;
+      (events[w.event] ??= []).push({
+        matcher: w.matcher,
+        hooks: [{ type: 'command', command: commandFor(id, agentId, ref), timeout: 15 }],
+      });
+    }
+    return { 'specpipe-guards': events };
+  }
+
+  return null;
+}
+
+/** Whether an agent has a droppable, verified enforced-hook config. */
+export function agentHasHooks(agentId) {
+  return !!HOOK_TARGETS[agentId];
+}
+
+/**
+ * Emit an agent's enforced-hook artifacts: the scripts to copy (kit-relative src +
+ * on-disk dst) and the generated config file. Honors the hook selection (null=all,
+ * empty Set=none). Returns null when the agent wires no hooks for this selection.
+ */
+export function emitHooks(agentId, hooksSet = null) {
+  const t = HOOK_TARGETS[agentId];
+  if (!t) return null;
+  const cfg = buildHookConfig(agentId, t.ref, hooksSet);
+  if (!cfg) return null;
+  return {
+    hooksDir: t.dir,
+    scripts: hookScriptsFor(agentId, t.dir, hooksSet),
+    configPath: t.configPath,
+    configContent: JSON.stringify(cfg, null, 2) + '\n',
+  };
+}