specpipe 1.0.0 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specpipe",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Spec-first development toolkit for agentic AI coding agents — installs skills + guardrails for Claude Code, Codex, Cursor, Antigravity, and more.",
   "bin": {
     "specpipe": "./bin/devkit.js",
@@ -15,6 +15,7 @@
     "node": ">=18"
   },
   "dependencies": {
+    "@clack/prompts": "^1.6.0",
     "chalk": "^5.4.1",
     "commander": "^13.1.0"
   },
@@ -51,7 +52,7 @@
     "url": "git+https://github.com/microvn/specpipe.git",
     "directory": "cli"
   },
-  "homepage": "https://github.com/microvn/specpipe#readme",
+  "homepage": "https://specpipe.vercel.app",
   "bugs": {
     "url": "https://github.com/microvn/specpipe/issues"
   },

package/src/cli.js

@@ -18,21 +18,29 @@ export function cli(argv) {
     .command('init [path]')
     .description('Initialize a project with the dev-kit')
     .option('-f, --force', 'Overwrite existing files')
-    .option('-g, --global', 'Install skills globally to ~/.claude/skills/ (available in all projects)')
+    .option('-g, --global', 'Install skills globally (per-agent user-level dirs, all projects); honors --agents, defaults to claude')
     .option('--agents <list>', 'Target agent(s): claude,codex,cursor,antigravity,openclaw,hermes or "all" (default: claude)')
-    .option('--only <components>', 'Install only specific components (comma-separated: hooks,skills,scripts,docs,config)')
+    .option('--skills <list>', 'Skills to install: all | core | comma list e.g. sp-build,sp-fix (default: all)')
+    .option('--hooks <list>', 'Guard hooks to install: all | none | comma list e.g. shell,read (default: all)')
+    .option('-y, --yes', 'Skip interactive prompts and use defaults (per-project, claude, all skills)')
+    .option('--only <components>', 'Install only specific components (comma-separated: hooks,skills,docs,config)')
     .option('--adopt', 'Adopt existing kit files without overwriting (migration from setup.sh)')
     .option('--dry-run', 'Show what would be done without making changes')
     .action(async (path, opts) => {
-      const { initCommand } = await import('./commands/init.js');
-      await initCommand(path || '.', opts);
+      try {
+        const { initCommand } = await import('./commands/init.js');
+        await initCommand(path || '.', opts);
+      } catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+      }
     });
 
   program
     .command('upgrade [path]')
     .description('Smart upgrade — preserves customized files')
     .option('-f, --force', 'Overwrite even customized files')
-    .option('-g, --global', 'Upgrade skills globally in ~/.claude/skills/')
+    .option('-g, --global', 'Upgrade the global install (every agent installed globally)')
     .option('--dry-run', 'Show what would be done without making changes')
     .action(async (path, opts) => {
       const { upgradeCommand } = await import('./commands/upgrade.js');
@@ -66,7 +74,9 @@ export function cli(argv) {
   program
     .command('remove [path]')
     .description('Uninstall dev-kit (preserves CLAUDE.md and docs/)')
-    .option('-g, --global', 'Remove global install (~/.claude/skills/, ~/.claude/hooks/, hook entries from ~/.claude/settings.json)')
+    .option('-g, --global', 'Remove global install (per-agent global sp-* skill dirs + Claude hooks/settings)')
+    .option('--agents <list>', 'Remove only these agent(s), keeping the rest (e.g. codex,cursor); shared files are kept while any remaining agent needs them')
+    .option('--dry-run', 'Show what would be removed without deleting anything')
     .action(async (path, opts) => {
       const { removeCommand } = await import('./commands/remove.js');
       await removeCommand(path || '.', opts);

package/src/commands/diff.js

@@ -16,7 +16,7 @@ export async function diffCommand(path) {
     process.exit(1);
   }
 
-  const desired = await computeDesired(getAgents(manifest));
+  const desired = await computeDesired(getAgents(manifest), manifest.skills ? new Set(manifest.skills) : null);
   let hasDiffs = false;
 
   for (const [file, d] of desired) {

package/src/commands/init-agents.js

@@ -7,10 +7,12 @@ import { detectProject } from '../lib/detector.js';
 import { createManifest, writeManifest, setFileEntry, readManifest, mergeAgents } from '../lib/manifest.js';
 import { hashContent } from '../lib/hasher.js';
 import {
-  COMPONENTS, PLACEHOLDER_DIRS, installFile, ensurePlaceholderDir,
-  setPermissions, fillTemplate, installAgentSkills, installAgentRules, installAgentHooks,
+  COMPONENTS,
+  fillTemplate, installAgentSkills, installAgentRules, installAgentHooks,
+  resolveSkills,
 } from '../lib/installer.js';
-import { resolveAgents, AGENTS } from '../lib/agents.js';
+import { resolveAgents, AGENTS, agentHasHooks } from '../lib/agents.js';
+import { resolveHooks } from '../lib/hooks.js';
 import { computeDesired } from '../lib/reconcile.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -36,6 +38,15 @@ export async function initMultiAgent(targetDir, opts, warnings = 0) {
   const claudeSelected = agents.includes('claude');
   const labels = agents.map((a) => AGENTS[a].label).join(', ');
 
+  // --only selects static COMPONENTS files, which only the single-agent (claude-
+  // only) path installs. Multi-agent emits skills/rules/hooks per agent and the
+  // reconcile model (computeDesired) has no component dimension, so honoring --only
+  // here wouldn't survive the next upgrade. Scope multi-agent installs with
+  // --skills / --hooks instead. Warn rather than silently ignore.
+  if (opts.only) {
+    log.warn(`--only is ignored with --agents (component selection applies to single-agent installs only). Use --skills / --hooks to scope a multi-agent install.`);
+  }
+
   if (opts.dryRun) {
     log.info('Dry run — no changes will be made');
     log.info(`Target agents: ${labels}`);
@@ -45,29 +56,29 @@ export async function initMultiAgent(targetDir, opts, warnings = 0) {
   log.blank();
   console.log(`--- Installing for: ${labels} ---`);
 
+  const skills = resolveSkills(opts.skills);
+  const hooks = resolveHooks(opts.hooks);
   const manifest = createManifest(pkg.version, null, Object.keys(COMPONENTS));
   manifest.agents = agents;
-
-  // Claude base: hooks + config + docs (only Claude has a native hook system).
-  if (claudeSelected) {
-    log.blank();
-    console.log('  Claude base (hooks, config, docs):');
-    for (const file of [...COMPONENTS.hooks, ...COMPONENTS.config, ...COMPONENTS.docs]) {
-      await installFile(file, targetDir, { force: opts.force });
-    }
-    for (const dir of PLACEHOLDER_DIRS) await ensurePlaceholderDir(dir, targetDir);
-    await setPermissions(targetDir);
-  }
+  if (skills) manifest.skills = [...skills];
+  if (hooks) manifest.hooks = [...hooks];
 
   // Skills + guardrails, emitted per agent into each agent's native location.
+  // (No static "Claude base" to copy — hooks/config/docs COMPONENTS are empty;
+  // everything is emitted from the registry in the per-agent loop below.)
   const results = [];
   for (const agent of agents) {
     log.blank();
     console.log(`  ${AGENTS[agent].label} skills:`);
-    results.push(await installAgentSkills(agent, targetDir, { force: opts.force }));
-    const rules = await installAgentRules(agent, targetDir, { force: opts.force });
-    if (rules?.mode === 'agents-md') manifest.agentsMdGuards = true;
-    await installAgentHooks(agent, targetDir, { force: opts.force }); // enforced hooks (Codex/Cursor)
+    results.push(await installAgentSkills(agent, targetDir, { force: opts.force, skills }));
+    // Option A: `--hooks none` turns guardrails off entirely — no enforced hooks AND
+    // no always-on advisory rules. A subset/all still installs the advisory rules.
+    const noGuards = hooks && hooks.size === 0;
+    if (!noGuards) {
+      const rules = await installAgentRules(agent, targetDir, { force: opts.force });
+      if (rules?.mode === 'merge') manifest.agentsMdGuards = true;
+    }
+    await installAgentHooks(agent, targetDir, { force: opts.force, hooks }); // enforced hooks (Claude/Codex/Cursor/Antigravity)
   }
 
   // Project detection only fills Claude's CLAUDE.md template.
@@ -77,13 +88,14 @@ export async function initMultiAgent(targetDir, opts, warnings = 0) {
       manifest.projectType = { lang: projectInfo.lang, framework: projectInfo.framework };
       await fillTemplate(targetDir, projectInfo);
     } else {
+      log.warn('Could not auto-detect project type — fill the Project Info section in .claude/CLAUDE.md manually.');
       warnings++;
     }
   }
 
   // Record every installed file (all agents) keyed by on-disk path, with the
   // hash of what's actually on disk so customization/skip is detected later.
-  const desired = await computeDesired(agents);
+  const desired = await computeDesired(agents, skills);
   for (const [relPath, d] of desired) {
     let installedHash = d.kitHash;
     try { installedHash = hashContent(await readFile(resolve(targetDir, relPath), 'utf-8')); } catch { /* skipped/missing */ }
@@ -106,7 +118,15 @@ export async function initMultiAgent(targetDir, opts, warnings = 0) {
     log.blank();
     console.log('  Claude hooks active via .claude/settings.json.');
   }
-  const noHook = agents.filter((a) => AGENTS[a].hooks !== 'native');
+  // Enforced = Claude's native .claude/hooks OR an agent with its own blocking
+  // hook config (Codex .codex/hooks.json, Cursor .cursor/hooks.json, Antigravity
+  // .agents/hooks.json). The rest get guards as always-on advisory rules only.
+  const enforced = agents.filter((a) => AGENTS[a].hooks === 'native' || agentHasHooks(a));
+  if (enforced.length) {
+    log.blank();
+    console.log(`  Guards hook-enforced (blocking) for: ${enforced.map((a) => AGENTS[a].label).join(', ')}.`);
+  }
+  const noHook = agents.filter((a) => AGENTS[a].hooks !== 'native' && !agentHasHooks(a));
   if (noHook.length) {
     log.blank();
     log.warn(`${noHook.map((a) => AGENTS[a].label).join(', ')}: guards installed as always-on rules (advisory — not hook-enforced like Claude).`);

package/src/commands/init-global.js

@@ -1,13 +1,17 @@
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, writeFile, unlink, rmdir } from 'node:fs/promises';
 import { log } from '../lib/logger.js';
 import {
-  COMPONENTS, installSkillGlobal, getGlobalSkillsDir,
+  COMPONENTS, installSkillGlobalForAgent, skillAllowed,
   installHookGlobal, getGlobalHooksDir, mergeGlobalSettings,
 } from '../lib/installer.js';
+import { AGENTS } from '../lib/agents.js';
+import { hookScriptsFor } from '../lib/hooks.js';
 
-// Global Claude install (~/.claude/skills + hooks) and its manifest.
+// Global install. Skills go per-agent into each agent's user-level dir (Claude
+// ~/.claude/skills, Codex ~/.codex/skills, …). Global hooks remain Claude-only —
+// Claude Code's native enforcement engine; other agents enforce per-project.
 
 const GLOBAL_MANIFEST = join(homedir(), '.claude', '.devkit-manifest.json');
 
@@ -24,66 +28,116 @@ export async function writeGlobalManifest(data) {
   await writeFile(GLOBAL_MANIFEST, JSON.stringify(data, null, 2) + '\n');
 }
 
-export async function initGlobal({ force = false, hooks = false } = {}) {
-  const globalSkillsDir = getGlobalSkillsDir();
-  await mkdir(globalSkillsDir, { recursive: true });
-
+export async function initGlobal({ agents = ['claude'], skills = null, hookSelection = null, force = false, hooks = false } = {}) {
   const existing = await readGlobalManifest() || {};
   const globalFiles = existing.files || {};
   const updatedFiles = { ...globalFiles };
-
-  log.blank();
-  console.log('--- Installing global skills ---');
-
-  let copied = 0; let skipped = 0; let identical = 0;
-  for (const relPath of COMPONENTS.skills) {
-    const { result, kitHash } = await installSkillGlobal(relPath, globalSkillsDir, { force, globalFiles });
-    if (result === 'copied') copied++;
-    else if (result === 'identical') identical++;
-    else skipped++;
-    if (result !== 'skipped') updatedFiles[relPath] = { kitHash };
+  const installedAgents = new Set(existing.globalAgents || (existing.globalInstalled ? ['claude'] : []));
+  const installedKeys = new Set(); // every file present after this run (for orphan pruning)
+
+  for (const agent of agents) {
+    const { label, globalSkillRoot } = AGENTS[agent];
+    if (!globalSkillRoot) {
+      // Cursor has no user-level skills dir; it reads ~/.claude/skills & ~/.codex/skills.
+      log.blank();
+      log.warn(`${label}: no user-level skills directory — install Claude or Codex globally and ${label} reads those. Skipping its global install.`);
+      continue;
+    }
+    log.blank();
+    console.log(`--- Installing global skills: ${label} (~/${globalSkillRoot}/) ---`);
+
+    let copied = 0; let skipped = 0; let identical = 0;
+    for (const relPath of COMPONENTS.skills) {
+      if (!skillAllowed(relPath, skills)) continue;
+      const r = await installSkillGlobalForAgent(agent, relPath, { force, globalFiles });
+      if (!r) continue;
+      if (r.result === 'copied') copied++;
+      else if (r.result === 'identical') identical++;
+      else skipped++;
+      installedKeys.add(r.key);
+      updatedFiles[r.key] = { kitHash: r.kitHash, agent };
+    }
+
+    const parts = [`${copied} copied`];
+    if (identical > 0) parts.push(`${identical} identical`);
+    if (skipped > 0) parts.push(`${skipped} customized (use --force to overwrite)`);
+    log.pass(`${label} global skills: ${parts.join(', ')} — available in all projects.`);
+    installedAgents.add(agent);
   }
 
-  const parts = [`${copied} copied`];
-  if (identical > 0) parts.push(`${identical} identical`);
-  if (skipped > 0) parts.push(`${skipped} customized (use --force to overwrite)`);
-  log.pass(`Global skills: ${parts.join(', ')}`);
-  log.info('Skills available in all projects via ~/.claude/skills/');
+  // Global hooks are Claude-only (its native enforcement engine).
+  const wantHooks = hooks && agents.includes('claude');
+  if (wantHooks) {
+    const hookKeys = await initGlobalHooks({ force, hooks: hookSelection, _globalFiles: updatedFiles, _skipManifestWrite: true });
+    for (const k of hookKeys) installedKeys.add(k);
+  }
 
-  if (hooks) {
-    await initGlobalHooks({ force, _globalFiles: updatedFiles, _skipManifestWrite: true });
+  // Prune orphans: files from a previous global install that are no longer desired
+  // (a removed/renamed hook like self-review.sh, or a deselected skill), but only
+  // within the scopes we just refreshed — never touch an agent we didn't reinstall.
+  let pruned = 0;
+  const prunedDirs = new Set();
+  for (const [key, entry] of Object.entries(globalFiles)) {
+    if (installedKeys.has(key)) continue;
+    const isHook = key.startsWith('.claude/hooks/');
+    const owner = entry.agent || (isHook ? 'claude' : null);
+    const inScope = isHook ? wantHooks : (owner && agents.includes(owner));
+    if (!inScope) continue;
+    const abs = join(homedir(), ...key.split('/'));
+    try {
+      await unlink(abs);
+      log.del(`~/${key} (no longer in kit)`);
+    } catch { /* already gone */ }
+    delete updatedFiles[key];
+    prunedDirs.add(dirname(abs));
+    pruned++;
+  }
+  // Remove dirs left empty by pruning (deepest first; rmdir no-ops on non-empty).
+  for (let d of [...prunedDirs].sort((a, b) => b.length - a.length)) {
+    while (d.startsWith(homedir()) && d !== homedir()) {
+      try { await rmdir(d); } catch { break; }
+      d = dirname(d);
+    }
   }
+  if (pruned) log.info(`Pruned ${pruned} stale global file(s).`);
 
   await writeGlobalManifest({
     ...existing,
-    globalInstalled: true,
-    globalHooksInstalled: hooks || existing.globalHooksInstalled || false,
+    globalInstalled: installedAgents.has('claude') || existing.globalInstalled || false,
+    globalAgents: [...installedAgents],
+    skills: skills ? [...skills] : existing.skills,
+    hooks: hookSelection ? [...hookSelection] : existing.hooks,
+    globalHooksInstalled: wantHooks || existing.globalHooksInstalled || false,
     files: updatedFiles,
     updatedAt: new Date().toISOString(),
   });
 }
 
-export async function initGlobalHooks({ force = false, _globalFiles, _skipManifestWrite = false } = {}) {
+export async function initGlobalHooks({ force = false, hooks = null, _globalFiles, _skipManifestWrite = false } = {}) {
   const globalHooksDir = getGlobalHooksDir();
   await mkdir(globalHooksDir, { recursive: true });
 
   const existing = _skipManifestWrite ? null : (await readGlobalManifest() || {});
   const globalFiles = _globalFiles || existing?.files || {};
   const updatedFiles = { ...globalFiles };
+  const keys = []; // home-relative keys installed this run (for the caller's orphan-prune)
 
   log.blank();
   console.log('--- Installing global hooks ---');
 
   let copied = 0; let skipped = 0; let identical = 0;
-  for (const relPath of COMPONENTS.hooks) {
-    const { result, kitHash } = await installHookGlobal(relPath, globalHooksDir, { force, globalFiles });
+  for (const s of hookScriptsFor('claude', globalHooksDir, hooks)) {
+    const base = s.src.split('/').pop();
+    const key = `.claude/hooks/${base}`;
+    const { result, kitHash } = await installHookGlobal(s.src, globalHooksDir, { force, globalFiles, key });
     if (result === 'copied') copied++;
     else if (result === 'identical') identical++;
     else skipped++;
-    if (result !== 'skipped') updatedFiles[relPath] = { kitHash };
+    if (result !== 'skipped') updatedFiles[key] = { kitHash };
+    keys.push(key);
   }
 
-  await mergeGlobalSettings(globalHooksDir);
+  await mergeGlobalSettings(globalHooksDir, hooks);
 
   const parts = [`${copied} copied`];
   if (identical > 0) parts.push(`${identical} identical`);
@@ -99,4 +153,5 @@ export async function initGlobalHooks({ force = false, _globalFiles, _skipManife
       updatedAt: new Date().toISOString(),
     });
   }
+  return keys;
 }

package/src/commands/init-interactive.js

@@ -0,0 +1,71 @@
+import { intro, outro, select, multiselect, isCancel, cancel } from '@clack/prompts';
+import { AGENT_IDS, AGENTS } from '../lib/agents.js';
+import { ALL_SKILL_NAMES, OPTIONAL_SKILLS } from '../lib/installer.js';
+import { HOOK_IDS, HOOKS } from '../lib/hooks.js';
+
+/**
+ * Interactive `specpipe init` picker (clack). Three questions: scope, agents, skills.
+ * Returns { scope: 'project'|'global', agents: string[], skills: string|null } where
+ * skills is a comma list, or null when every skill is selected (= the `all` default).
+ * Returns null if the user cancels (Ctrl-C / Esc).
+ */
+export async function runInteractiveInit() {
+  intro('specpipe init');
+
+  const scope = await select({
+    message: 'Install where?',
+    options: [
+      { value: 'project', label: 'This project', hint: 'default — ./.claude, ./.agents, …' },
+      { value: 'global', label: 'Globally', hint: 'available in every project (~/.claude/skills, …)' },
+    ],
+    initialValue: 'project',
+  });
+  if (isCancel(scope)) { cancel('Cancelled — nothing installed.'); return null; }
+
+  const agents = await multiselect({
+    message: 'Which agents? (space to toggle, enter to confirm)',
+    options: AGENT_IDS.map((id) => ({ value: id, label: AGENTS[id].label })),
+    initialValues: ['claude'],
+    required: true,
+  });
+  if (isCancel(agents)) { cancel('Cancelled — nothing installed.'); return null; }
+
+  const skills = await multiselect({
+    message: 'Which skills? (all on by default; deselect what you don\'t need)',
+    options: ALL_SKILL_NAMES.map((name) => ({
+      value: name,
+      label: name,
+      hint: OPTIONAL_SKILLS.includes(name) ? 'optional' : undefined,
+    })),
+    initialValues: [...ALL_SKILL_NAMES],
+    required: true,
+  });
+  if (isCancel(skills)) { cancel('Cancelled — nothing installed.'); return null; }
+
+  // Only offer guards at least one selected agent can hook-ENFORCE. Most guards are
+  // Claude-only (they hook Claude tool events like Edit/Glob/Write); Codex & Antigravity
+  // enforce shell-guard only, Cursor shell+read. The unsupported guards still reach a
+  // non-Claude agent as advisory rules in its rules file — just not as a blocking hook.
+  const enforceable = HOOK_IDS.filter((id) => agents.some((a) => !!HOOKS[id].wiring[a]));
+  const claudeOnly = HOOK_IDS.filter((id) => !enforceable.includes(id));
+  const hookMsg = claudeOnly.length
+    ? `Which guard hooks to ENFORCE for ${agents.map((a) => AGENTS[a].label).join(', ')}? (${claudeOnly.join(', ')} are Claude-only — they ship as advisory rules for the others)`
+    : 'Which guard hooks? (block secrets + wasteful-dir exploration; clear all to disable guardrails)';
+  const hooks = await multiselect({
+    message: hookMsg,
+    options: enforceable.map((id) => ({ value: id, label: id, hint: HOOKS[id].desc })),
+    initialValues: [...enforceable],
+    required: false,
+  });
+  if (isCancel(hooks)) { cancel('Cancelled — nothing installed.'); return null; }
+
+  const allSkills = skills.length === ALL_SKILL_NAMES.length;
+  // 'none' = explicitly cleared; null = every enforceable guard selected (the default);
+  // else the explicit subset. resolveHooks then re-filters per agent at emit time.
+  const hooksArg = hooks.length === 0 ? 'none'
+    : hooks.length === enforceable.length ? null
+    : hooks.join(',');
+  outro(`Installing ${skills.length} skill(s) + ${hooks.length} enforced hook(s) for ${agents.map((a) => AGENTS[a].label).join(', ')} (${scope}).`);
+
+  return { scope, agents, skills: allSkills ? null : skills.join(','), hooks: hooksArg };
+}

package/src/commands/init.js

@@ -11,11 +11,12 @@ import { readFile } from 'node:fs/promises';
 import { computeDesired } from '../lib/reconcile.js';
 import {
   getAllFiles, getFilesForComponents, installFile,
-  ensurePlaceholderDir, setPermissions, fillTemplate,
-  verifySettingsJson, PLACEHOLDER_DIRS, COMPONENTS,
-  getTemplateDir, installSkillForAgent,
+  setPermissions, fillTemplate,
+  verifySettingsJson, COMPONENTS,
+  getTemplateDir, installSkillForAgent, installAgentHooks, installAgentRules, resolveSkills, skillAllowed,
 } from '../lib/installer.js';
-import { AGENTS, parseSkillPath } from '../lib/agents.js';
+import { resolveHooks } from '../lib/hooks.js';
+import { AGENTS, parseSkillPath, resolveAgents } from '../lib/agents.js';
 import { initMultiAgent } from './init-agents.js';
 import { adoptExisting } from './init-adopt.js';
 import { readGlobalManifest, writeGlobalManifest, initGlobal } from './init-global.js';
@@ -36,9 +37,29 @@ export async function initCommand(path, opts) {
   log.info(`Target: ${targetDir}`);
   log.blank();
 
-  // --- Global mode ---
+  // --- Interactive picker --- (TTY only, and only when no selection flags were
+  // passed; -y / any of --global/--agents/--skills/--only/--adopt/--dry-run skips it)
+  const wantsInteractive = process.stdin.isTTY && !opts.yes && !opts.global
+    && !opts.agents && !opts.skills && !opts.only && !opts.adopt && !opts.dryRun;
+  if (wantsInteractive) {
+    const { runInteractiveInit } = await import('./init-interactive.js');
+    const choice = await runInteractiveInit();
+    if (!choice) return; // cancelled
+    if (choice.scope === 'global') opts.global = true;
+    opts.agents = choice.agents.join(',');
+    if (choice.skills) opts.skills = choice.skills;
+    if (choice.hooks) opts.hooks = choice.hooks;
+  }
+
+  // --- Global mode --- (honors --agents + --skills; defaults to claude + all skills)
   if (opts.global) {
-    await initGlobal({ force: opts.force, hooks: true });
+    await initGlobal({
+      agents: resolveAgents(opts.agents),
+      skills: resolveSkills(opts.skills),
+      hookSelection: resolveHooks(opts.hooks),
+      force: opts.force,
+      hooks: true,
+    });
     return;
   }
 
@@ -85,7 +106,10 @@ export async function initCommand(path, opts) {
     }
   }
 
-  const files = opts.only ? getFilesForComponents(components) : getAllFiles();
+  const skillsSet = resolveSkills(opts.skills);
+  const hooksSet = resolveHooks(opts.hooks);
+  const files = (opts.only ? getFilesForComponents(components) : getAllFiles())
+    .filter((f) => skillAllowed(f, skillsSet));
 
   // --- Dry run ---
   if (opts.dryRun) {
@@ -108,6 +132,8 @@ export async function initCommand(path, opts) {
   console.log('--- Installing ---');
 
   const manifest = createManifest(pkg.version, null, components);
+  if (skillsSet) manifest.skills = [...skillsSet];
+  if (hooksSet) manifest.hooks = [...hooksSet];
   let copied = 0;
   let skipped = 0;
   let identical = 0;
@@ -139,11 +165,24 @@ export async function initCommand(path, opts) {
     setFileEntry(manifest, outPath, kitHash, installedHash, { agent: 'claude', templateRel: file });
   }
 
+  // Enforced guard hooks + generated .claude/settings.json — emitted from the hook
+  // registry (not static files). Only when the hooks component is in scope.
+  if (components.includes('hooks')) {
+    await installAgentHooks('claude', targetDir, { force: opts.force, hooks: hooksSet });
+  }
+
+  // Claude's rules hub (CLAUDE.md) is a marked section emitted from the single rules
+  // source. It's part of the 'config' component; --hooks none (option A) skips it too.
+  const noGuards = hooksSet && hooksSet.size === 0;
+  if (!noGuards && components.includes('config')) {
+    await installAgentRules('claude', targetDir, { force: opts.force });
+  }
+
   // Accumulate: keep agents installed by an earlier run so a plain `init` doesn't
   // orphan files from a prior `init --agents …`. Record their on-disk files too.
   const prior = await readManifest(targetDir);
   manifest.agents = mergeAgents(prior?.agents, ['claude']);
-  for (const [relPath, d] of await computeDesired(manifest.agents.filter((a) => a !== 'claude'))) {
+  for (const [relPath, d] of await computeDesired(manifest.agents.filter((a) => a !== 'claude'), skillsSet)) {
     if (manifest.files[relPath]) continue;
     try {
       const installedHash = hashContent(await readFile(resolve(targetDir, relPath), 'utf-8'));
@@ -151,11 +190,6 @@ export async function initCommand(path, opts) {
     } catch { /* prior agent's file not on disk — don't record a phantom */ }
   }
 
-  // Placeholder directories
-  for (const dir of PLACEHOLDER_DIRS) {
-    await ensurePlaceholderDir(dir, targetDir);
-  }
-
   // --- Permissions ---
   await setPermissions(targetDir);
 
@@ -203,11 +237,10 @@ export async function initCommand(path, opts) {
   console.log('=== Setup Complete ===');
   log.blank();
   console.log('Installed:');
-  console.log('  .claude/CLAUDE.md          — Project rules (review and customize)');
-  console.log('  .claude/settings.json      — Hook configuration');
-  console.log('  .claude/hooks/             — 6 guards (file, path, glob, comment, sensitive, self-review)');
-  console.log('  .claude/skills/            — /sp-plan, /sp-challenge, /sp-build, /sp-fix, /sp-review, /sp-commit, /sp-voices');
-  console.log('  docs/WORKFLOW.md           — Workflow reference');
+  console.log('  .claude/CLAUDE.md          — rules hub (workflow + guardrails + project info)');
+  console.log('  .claude/settings.json      — hook configuration');
+  console.log('  .claude/hooks/             — 5 guards (shell, read, comment, glob, file)');
+  console.log('  .claude/skills/            — sp-* skills (/sp-explore … /sp-commit, /sp-voices)');
   log.blank();
   const parts = [`${copied} copied`];
   if (identical > 0) parts.push(`${identical} identical`);
@@ -225,14 +258,20 @@ export async function initCommand(path, opts) {
     console.log(`⚠ ${warnings} warning(s) above — review before proceeding.`);
   }
 
-  // --- Global install prompt (first-time only) ---
+  // --- Global install prompt (first-time only; never on -y or non-TTY) ---
   if (!opts.global) {
     const globalMeta = await readGlobalManifest();
-    if (globalMeta?.globalInstalled === undefined) {
+    if (globalMeta?.globalInstalled === undefined && process.stdin.isTTY && !opts.yes) {
       await promptGlobalInstall(opts);
     } else if (globalMeta?.globalInstalled === true) {
-      // Auto-upgrade global on init if previously installed
-      await initGlobal({ force: opts.force });
+      // Auto-upgrade global on init for every agent previously installed globally,
+      // preserving the skill selection recorded at global install time.
+      await initGlobal({
+        agents: globalMeta.globalAgents || ['claude'],
+        skills: globalMeta.skills ? new Set(globalMeta.skills) : null,
+        hookSelection: globalMeta.hooks ? new Set(globalMeta.hooks) : null,
+        force: opts.force,
+      });
     }
   }
 }