compound-workflow 1.6.17 → 1.7.1

package/.claude-plugin/plugin.json

@@ -1,23 +1,7 @@
 {
   "name": "compound-workflow",
-  "version": "1.6.17",
   "description": "Clarify -> plan -> execute -> verify -> capture workflow: commands, skills, and agents for Claude Code",
   "author": {
     "name": "Compound Workflow"
-  },
-  "keywords": [
-    "workflow",
-    "planning",
-    "agents",
-    "skills",
-    "commands",
-    "claude"
-  ],
-  "license": "MIT",
-  "repository": "https://github.com/cjerochim/compound-workflow",
-  "commands": "./src/.agents/commands",
-  "agents": [
-    "./src/.agents/agents"
-  ],
-  "skills": "./src/.agents/skills"
+  }
 }

package/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "compound-workflow",
-  "version": "1.6.17",
+  "version": "1.7.1",
   "description": "Clarify -> plan -> execute -> verify -> capture workflow for Cursor",
   "author": {
     "name": "Compound Workflow"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "compound-workflow",
-  "version": "1.6.17",
+  "version": "1.7.1",
   "description": "Clarify → plan → execute → verify → capture. One Install action for Cursor, Claude, and OpenCode.",
   "license": "MIT",
   "repository": {

package/scripts/check-version-parity.mjs

@@ -19,12 +19,18 @@ const claudePlugin = JSON.parse(
 );
 
 const expected = pkg.version;
-if (cursorPlugin.version !== expected || claudePlugin.version !== expected) {
+
+// Claude Code's plugin.json is intentionally minimal (see scripts/generate-platform-artifacts.mjs)
+// and may not include a version field. When absent, treat it as not applicable.
+const claudeVersion = claudePlugin.version;
+const claudeOk = claudeVersion == null || claudeVersion === expected;
+
+if (cursorPlugin.version !== expected || !claudeOk) {
   console.error(
     "Version mismatch: package.json=%s, .cursor-plugin/plugin.json=%s, .claude-plugin/plugin.json=%s",
     expected,
     cursorPlugin.version,
-    claudePlugin.version
+    claudeVersion
   );
   process.exit(1);
 }

package/scripts/generate-platform-artifacts.mjs

@@ -152,17 +152,12 @@ function main() {
   const agentRoot = roots.agents || "node_modules/compound-workflow/src/.agents/agents";
   const skillsPath = roots.skills || "node_modules/compound-workflow/src/.agents/skills";
 
+  // Claude Code only accepts name, description, author in plugin.json.
+  // Agents are discovered from the adjacent agents/ directory (must be flat .md files).
   const claudePlugin = {
     name: pkg.name,
-    version: pkg.version,
     description: "Clarify -> plan -> execute -> verify -> capture workflow: commands, skills, and agents for Claude Code",
     author: { name: "Compound Workflow" },
-    keywords: ["workflow", "planning", "agents", "skills", "commands", "claude"],
-    license: pkg.license,
-    repository: repositoryUrl,
-    commands: "./src/.agents/commands",
-    agents: ["./src/.agents/agents"],
-    skills: "./src/.agents/skills",
   };
 
   const cursorPlugin = {
@@ -191,6 +186,36 @@ function main() {
   writeJson(path.join(repoRoot, ".cursor-plugin", "plugin.json"), cursorPlugin, checkOnly, changed);
   writeJson(path.join(repoRoot, "src", "generated", "opencode.managed.json"), openCodeManaged, checkOnly, changed);
 
+  // Generate flat agent symlinks in .claude-plugin/agents/ so Claude Code discovers them.
+  // Claude Code only scans the root of the agents/ directory (not subdirectories).
+  const claudeAgentsDir = path.join(repoRoot, ".claude-plugin", "agents");
+  const agentsDirAbs = path.join(agentsRoot, "agents");
+  if (!checkOnly) {
+    fs.mkdirSync(claudeAgentsDir, { recursive: true });
+    // Prune stale symlinks no longer in the agent list
+    const agentBasenames = new Set(agents.map((a) => path.basename(a.rel)));
+    if (fs.existsSync(claudeAgentsDir)) {
+      for (const entry of fs.readdirSync(claudeAgentsDir, { withFileTypes: true })) {
+        if (!agentBasenames.has(entry.name)) {
+          fs.rmSync(path.join(claudeAgentsDir, entry.name), { force: true });
+        }
+      }
+    }
+    for (const agent of agents) {
+      const linkPath = path.join(claudeAgentsDir, path.basename(agent.rel));
+      const targetPath = path.relative(claudeAgentsDir, path.join(agentsDirAbs, agent.rel));
+      try {
+        if (fs.existsSync(linkPath) || fs.lstatSync(linkPath).isSymbolicLink()) {
+          fs.rmSync(linkPath, { force: true });
+        }
+      } catch { /* doesn't exist */ }
+      fs.symlinkSync(targetPath, linkPath);
+    }
+    if (agents.length) {
+      console.log(`Synced ${agents.length} agent symlinks to .claude-plugin/agents/`);
+    }
+  }
+
   if (checkOnly && changed.length) {
     console.error("Generated artifacts are stale:");
     for (const abs of changed) console.error("-", path.relative(repoRoot, abs));

package/scripts/install-cli.mjs

@@ -42,13 +42,14 @@ When Cursor is detected (~/.cursor), registers the plugin so skills/commands app
 }
 
 function parseArgs(argv) {
-  const out = { root: process.cwd(), dryRun: false, noConfig: false, noRegisterCursor: false, registerCursor: false };
+  const out = { root: process.cwd(), dryRun: false, noConfig: false, noRegisterCursor: false, registerCursor: false, verify: false };
   for (let i = 2; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === "--dry-run") out.dryRun = true;
     else if (arg === "--no-config") out.noConfig = true;
     else if (arg === "--no-register-cursor") out.noRegisterCursor = true;
     else if (arg === "--register-cursor") out.registerCursor = true;
+    else if (arg === "--verify") out.verify = true;
     else if (arg === "--root") {
       const value = argv[i + 1];
       if (!value) usage(1);
@@ -335,20 +336,26 @@ function ensureDirs(targetRoot, dryRun) {
  */
 function writePluginManifests(targetRoot, dryRun, isSelfInstall) {
   const pathsBase = isSelfInstall ? "./src/.agents" : "./node_modules/compound-workflow/src/.agents";
-  const pathOverrides = {
-    commands: `${pathsBase}/commands`,
-    agents: `${pathsBase}/agents`,
-    skills: `${pathsBase}/skills`,
-  };
   const cursorSrc = path.join(PACKAGE_ROOT, ".cursor-plugin", "plugin.json");
   const claudeSrc = path.join(PACKAGE_ROOT, ".claude-plugin", "plugin.json");
   const cursorManifest = readJsonMaybe(cursorSrc);
   const claudeManifest = readJsonMaybe(claudeSrc);
   if (!cursorManifest || !claudeManifest) return;
 
-  const cursorOut = { ...cursorManifest, ...pathOverrides };
-  // Claude Code validator requires agents as array; Cursor uses string (unchanged).
-  const claudeOut = { ...claudeManifest, ...pathOverrides, agents: [`${pathsBase}/agents`] };
+  // Cursor supports full manifest with commands/agents/skills path overrides.
+  const cursorOut = {
+    ...cursorManifest,
+    commands: `${pathsBase}/commands`,
+    agents: `${pathsBase}/agents`,
+    skills: `${pathsBase}/skills`,
+  };
+  // Claude Code only accepts name, description, author in plugin.json.
+  // Agents are discovered from the adjacent agents/ directory (flat .md files).
+  const claudeOut = {
+    name: claudeManifest.name,
+    description: claudeManifest.description,
+    author: claudeManifest.author,
+  };
   const cursorDir = path.join(targetRoot, ".cursor-plugin");
   const claudeDir = path.join(targetRoot, ".claude-plugin");
 
@@ -369,6 +376,37 @@ function writePluginManifests(targetRoot, dryRun, isSelfInstall) {
   fs.writeFileSync(path.join(claudeDir, "plugin.json"), JSON.stringify(claudeOut, null, 2) + "\n", "utf8");
   fs.writeFileSync(path.join(cursorDir, "registration.json"), JSON.stringify(registrationDescriptor, null, 2) + "\n", "utf8");
 
+  // Sync flat agent symlinks into .claude-plugin/agents/ so Claude Code discovers them.
+  // Claude Code only scans the root of the agents/ directory (not subdirectories).
+  const claudeAgentsDir = path.join(claudeDir, "agents");
+  const packageAgentsDirAbs = isSelfInstall
+    ? path.join(PACKAGE_ROOT, "src", ".agents", "agents")
+    : path.join(targetRoot, "node_modules", "compound-workflow", "src", ".agents", "agents");
+  if (fs.existsSync(packageAgentsDirAbs)) {
+    fs.mkdirSync(claudeAgentsDir, { recursive: true });
+    const agentBasenames = new Set(GENERATED_MANIFEST.agents.map((a) => path.basename(a.rel)));
+    // Prune stale symlinks
+    try {
+      for (const entry of fs.readdirSync(claudeAgentsDir, { withFileTypes: true })) {
+        if (!agentBasenames.has(entry.name)) {
+          fs.rmSync(path.join(claudeAgentsDir, entry.name), { force: true });
+        }
+      }
+    } catch { /* ignore */ }
+    for (const agent of GENERATED_MANIFEST.agents) {
+      const linkPath = path.join(claudeAgentsDir, path.basename(agent.rel));
+      const targetPath = path.join(packageAgentsDirAbs, agent.rel);
+      try {
+        if (fs.lstatSync(linkPath)) fs.rmSync(linkPath, { force: true });
+      } catch { /* doesn't exist */ }
+      try {
+        fs.symlinkSync(targetPath, linkPath);
+      } catch (err) {
+        console.warn("[claude] Could not symlink agent", agent.id, err.message);
+      }
+    }
+  }
+
   // Claude Code 2.1.x+ no longer loads from installed_plugins.json; it requires marketplace flow.
   // Write a project-level marketplace so user can: /plugin marketplace add . then /plugin install compound-workflow@compound-workflow-local
   if (!isSelfInstall) {
@@ -467,10 +505,307 @@ function syncCursorSkills(targetRoot, dryRun, isSelfInstall) {
   console.log("Synced", skillDirs.length, "skills to .cursor/skills/");
 }
 
+/**
+ * Cursor discovers commands from .cursor/commands.
+ * Populate .cursor/commands/ with symlinks to the package commands so Cursor finds them.
+ */
+function syncCursorCommands(targetRoot, dryRun, isSelfInstall) {
+  const packageCommandsAbs = isSelfInstall
+    ? path.join(PACKAGE_ROOT, "src", ".agents", "commands")
+    : path.join(targetRoot, "node_modules", "compound-workflow", "src", ".agents", "commands");
+  if (!fs.existsSync(packageCommandsAbs)) return;
+
+  const cursorCommandsDir = path.join(targetRoot, ".cursor", "commands");
+  let entries;
+  try {
+    entries = fs.readdirSync(packageCommandsAbs, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  // Filter .md files that are commands
+  const commandFiles = entries.filter((e) => e.isFile() && e.name.endsWith(".md")).map((e) => e.name);
+  if (commandFiles.length === 0) return;
+
+  if (dryRun) {
+    console.log("[dry-run] Would symlink", commandFiles.length, "commands into .cursor/commands/");
+    return;
+  }
+
+  fs.mkdirSync(cursorCommandsDir, { recursive: true });
+  const packageCommandsReal = realpathSafe(packageCommandsAbs);
+  const commandSet = new Set(commandFiles);
+
+  // Prune: remove symlinks that point at our package but are no longer in the package
+  try {
+    for (const entry of fs.readdirSync(cursorCommandsDir, { withFileTypes: true })) {
+      if (!entry.isSymbolicLink()) continue;
+      const linkPath = path.join(cursorCommandsDir, entry.name);
+      try {
+        const resolved = realpathSafe(linkPath);
+        if (!resolved.startsWith(packageCommandsReal + path.sep) && resolved !== packageCommandsReal) continue;
+        const base = path.basename(resolved);
+        if (commandSet.has(base)) continue;
+        fs.rmSync(linkPath);
+      } catch {
+        /* ignore broken symlinks or permission errors */
+      }
+    }
+  } catch {
+    /* .cursor/commands not readable */
+  }
+
+  for (const name of commandFiles) {
+    const linkPath = path.join(cursorCommandsDir, name);
+    const targetPath = path.join(packageCommandsAbs, name);
+    try {
+      if (fs.existsSync(linkPath)) {
+        const stat = fs.lstatSync(linkPath);
+        if (!stat.isSymbolicLink()) continue;
+        try {
+          if (realpathSafe(linkPath) !== realpathSafe(targetPath)) continue;
+        } catch {
+          continue;
+        }
+        fs.rmSync(linkPath);
+      }
+      fs.symlinkSync(targetPath, linkPath, "file");
+    } catch (err) {
+      console.warn("[cursor] Could not symlink command", name, err.message);
+    }
+  }
+  console.log("Synced", commandFiles.length, "commands to .cursor/commands/");
+}
+
+/**
+ * Cursor discovers agents from .cursor/agents.
+ * Populate .cursor/agents/ with symlinks to the package agents so Cursor finds them.
+ * Preserves subdirectory structure (research/, workflow/, review/).
+ */
+function syncCursorAgents(targetRoot, dryRun, isSelfInstall) {
+  const packageAgentsAbs = isSelfInstall
+    ? path.join(PACKAGE_ROOT, "src", ".agents", "agents")
+    : path.join(targetRoot, "node_modules", "compound-workflow", "src", ".agents", "agents");
+  if (!fs.existsSync(packageAgentsAbs)) return;
+
+  const cursorAgentsDir = path.join(targetRoot, ".cursor", "agents");
+
+  // Get all agent files from manifest (these include subdir paths like "research/repo-research-analyst.md")
+  const agentRels = GENERATED_MANIFEST.agents.map((a) => a.rel);
+  if (agentRels.length === 0) return;
+
+  if (dryRun) {
+    console.log("[dry-run] Would symlink", agentRels.length, "agents into .cursor/agents/");
+    return;
+  }
+
+  fs.mkdirSync(cursorAgentsDir, { recursive: true });
+  const packageAgentsReal = realpathSafe(packageAgentsAbs);
+  const agentSet = new Set(agentRels);
+
+  // Build set of valid subdirectories to preserve structure
+  const validSubdirs = new Set();
+  for (const rel of agentRels) {
+    const subdir = path.dirname(rel);
+    if (subdir !== ".") validSubdirs.add(subdir);
+  }
+
+  // Prune: remove symlinks that point at our package but are no longer in the manifest
+  try {
+    for (const entry of fs.readdirSync(cursorAgentsDir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        // Check if this subdir is still valid
+        if (!validSubdirs.has(entry.name)) {
+          // Remove the entire stale subdirectory
+          fs.rmSync(path.join(cursorAgentsDir, entry.name), { recursive: true, force: true });
+          continue;
+        }
+        // Prune stale symlinks within valid subdirectories
+        const subdirPath = path.join(cursorAgentsDir, entry.name);
+        for (const subEntry of fs.readdirSync(subdirPath, { withFileTypes: true })) {
+          if (!subEntry.isSymbolicLink()) continue;
+          const linkPath = path.join(subdirPath, subEntry.name);
+          try {
+            const resolved = realpathSafe(linkPath);
+            if (!resolved.startsWith(packageAgentsReal + path.sep) && resolved !== packageAgentsReal) continue;
+            const relFromPackage = path.relative(packageAgentsAbs, resolved);
+            if (agentSet.has(relFromPackage)) continue;
+            fs.rmSync(linkPath);
+          } catch {
+            /* ignore broken symlinks */
+          }
+        }
+      } else if (entry.isSymbolicLink()) {
+        // Handle flat symlinks (if any were created at root level)
+        const linkPath = path.join(cursorAgentsDir, entry.name);
+        try {
+          const resolved = realpathSafe(linkPath);
+          if (!resolved.startsWith(packageAgentsReal + path.sep) && resolved !== packageAgentsReal) continue;
+          const relFromPackage = path.relative(packageAgentsAbs, resolved);
+          if (agentSet.has(relFromPackage)) continue;
+          fs.rmSync(linkPath);
+        } catch {
+          /* ignore broken symlinks */
+        }
+      }
+    }
+  } catch {
+    /* .cursor/agents not readable */
+  }
+
+  // Create symlinks preserving subdirectory structure
+  for (const rel of agentRels) {
+    const targetPath = path.join(packageAgentsAbs, rel);
+    const linkPath = path.join(cursorAgentsDir, rel);
+
+    // Ensure subdirectory exists
+    const subdir = path.dirname(rel);
+    if (subdir !== ".") {
+      fs.mkdirSync(path.join(cursorAgentsDir, subdir), { recursive: true });
+    }
+
+    try {
+      if (fs.existsSync(linkPath)) {
+        const stat = fs.lstatSync(linkPath);
+        if (!stat.isSymbolicLink()) continue;
+        try {
+          if (realpathSafe(linkPath) !== realpathSafe(targetPath)) continue;
+        } catch {
+          continue;
+        }
+        fs.rmSync(linkPath);
+      }
+      fs.symlinkSync(targetPath, linkPath, "file");
+    } catch (err) {
+      console.warn("[cursor] Could not symlink agent", rel, err.message);
+    }
+  }
+  console.log("Synced", agentRels.length, "agents to .cursor/agents/");
+}
+
 function cursorDetected() {
   return fs.existsSync(path.join(os.homedir(), ".cursor"));
 }
 
+/**
+ * Verifies plugin integrity by checking all symlinks in .cursor/ directories
+ * match the expected state from GENERATED_MANIFEST.
+ * Returns { ok: boolean, issues: string[] }
+ */
+function verifyPluginIntegrity(targetRoot, isSelfInstall) {
+  const issues = [];
+  const packageRoot = isSelfInstall
+    ? PACKAGE_ROOT
+    : path.join(targetRoot, "node_modules", "compound-workflow");
+
+  // Verify skills
+  const cursorSkillsDir = path.join(targetRoot, ".cursor", "skills");
+  const packageSkillsDir = path.join(packageRoot, "src", ".agents", "skills");
+  if (fs.existsSync(packageSkillsDir)) {
+    const expectedSkills = new Set(
+      fs.readdirSync(packageSkillsDir, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && fs.existsSync(path.join(packageSkillsDir, e.name, "SKILL.md")))
+        .map((e) => e.name)
+    );
+    if (fs.existsSync(cursorSkillsDir)) {
+      const actualSkills = fs.readdirSync(cursorSkillsDir, { withFileTypes: true })
+        .filter((e) => e.isSymbolicLink())
+        .map((e) => e.name);
+      for (const skill of expectedSkills) {
+        if (!actualSkills.includes(skill)) {
+          issues.push(`Missing skill symlink: .cursor/skills/${skill}`);
+        }
+      }
+      for (const skill of actualSkills) {
+        if (!expectedSkills.has(skill)) {
+          issues.push(`Stale skill symlink: .cursor/skills/${skill}`);
+        }
+      }
+    } else if (expectedSkills.size > 0) {
+      issues.push(`Missing .cursor/skills/ directory (${expectedSkills.size} expected)`);
+    }
+  }
+
+  // Verify commands
+  const cursorCommandsDir = path.join(targetRoot, ".cursor", "commands");
+  const packageCommandsDir = path.join(packageRoot, "src", ".agents", "commands");
+  if (fs.existsSync(packageCommandsDir)) {
+    const expectedCommands = new Set(
+      fs.readdirSync(packageCommandsDir, { withFileTypes: true })
+        .filter((e) => e.isFile() && e.name.endsWith(".md"))
+        .map((e) => e.name)
+    );
+    if (fs.existsSync(cursorCommandsDir)) {
+      const actualCommands = fs.readdirSync(cursorCommandsDir, { withFileTypes: true })
+        .filter((e) => e.isSymbolicLink())
+        .map((e) => e.name);
+      for (const cmd of expectedCommands) {
+        if (!actualCommands.includes(cmd)) {
+          issues.push(`Missing command symlink: .cursor/commands/${cmd}`);
+        }
+      }
+      for (const cmd of actualCommands) {
+        if (!expectedCommands.has(cmd)) {
+          issues.push(`Stale command symlink: .cursor/commands/${cmd}`);
+        }
+      }
+    } else if (expectedCommands.size > 0) {
+      issues.push(`Missing .cursor/commands/ directory (${expectedCommands.size} expected)`);
+    }
+  }
+
+  // Verify agents
+  const cursorAgentsDir = path.join(targetRoot, ".cursor", "agents");
+  const packageAgentsDir = path.join(packageRoot, "src", ".agents", "agents");
+  if (fs.existsSync(packageAgentsDir)) {
+    // Recursively get all .md files from package agents dir
+    const expectedAgents = [];
+    function collectAgents(dir, prefix = "") {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+          collectAgents(path.join(dir, entry.name), relPath);
+        } else if (entry.isFile() && entry.name.endsWith(".md")) {
+          expectedAgents.push(relPath);
+        }
+      }
+    }
+    collectAgents(packageAgentsDir);
+    const expectedSet = new Set(expectedAgents);
+
+    if (fs.existsSync(cursorAgentsDir)) {
+      const actualAgents = [];
+      function collectActualAgents(dir, prefix = "") {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+          const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
+          if (entry.isDirectory()) {
+            collectActualAgents(path.join(dir, entry.name), relPath);
+          } else if (entry.isSymbolicLink()) {
+            actualAgents.push(relPath);
+          }
+        }
+      }
+      collectActualAgents(cursorAgentsDir);
+      const actualSet = new Set(actualAgents);
+
+      for (const agent of expectedAgents) {
+        if (!actualSet.has(agent)) {
+          issues.push(`Missing agent symlink: .cursor/agents/${agent}`);
+        }
+      }
+      for (const agent of actualAgents) {
+        if (!expectedSet.has(agent)) {
+          issues.push(`Stale agent symlink: .cursor/agents/${agent}`);
+        }
+      }
+    } else if (expectedAgents.length > 0) {
+      issues.push(`Missing .cursor/agents/ directory (${expectedAgents.length} expected)`);
+    }
+  }
+
+  return { ok: issues.length === 0, issues };
+}
+
 function applyCursorRegistration(targetRoot, dryRun, noRegisterCursor, forceRegister, isSelfInstall) {
   const claudePluginsDir = path.join(os.homedir(), ".claude", "plugins");
   const installedPath = path.join(claudePluginsDir, "installed_plugins.json");
@@ -485,87 +820,56 @@ function applyCursorRegistration(targetRoot, dryRun, noRegisterCursor, forceRegi
     }
   })();
 
-  const targetRootReal = realpathSafe(isSelfInstall ? PACKAGE_ROOT : targetRoot);
+  const projectRoot = isSelfInstall ? PACKAGE_ROOT : targetRoot;
   const pluginId = "compound-workflow@local";
-  const scope = isSelfInstall ? "user" : "project";
-
-  let installed = {};
-  if (fs.existsSync(installedPath)) {
-    try {
-      installed = readJsonMaybe(installedPath) ?? {};
-    } catch {
-      installed = {};
-    }
-  }
-  const plugins = ensureObject(installed.plugins);
-  const existingEntries = Array.isArray(plugins[pluginId]) ? plugins[pluginId] : [];
-  const cleanedEntries = scope === "project"
-    ? existingEntries.filter((e) => e.scope !== "user")
-    : existingEntries;
-  const pruned = cleanedEntries.filter((e) => {
-    const manifest = path.join(e.installPath || "", ".claude-plugin", "plugin.json");
-    return fs.existsSync(manifest);
-  });
-  const matchIndex = pruned.findIndex((e) =>
-    scope === "user" ? e.scope === "user" : e.scope === "project" && e.projectPath === targetRootReal
-  );
-  const existingEntry = matchIndex >= 0 ? pruned[matchIndex] : {};
-  const now = new Date().toISOString();
-  const newEntry = {
-    scope,
-    ...(scope === "project" ? { projectPath: targetRootReal } : {}),
-    installPath: targetRootReal,
-    version: pluginVersion,
-    installedAt: existingEntry.installedAt || now,
-    lastUpdated: now,
-  };
-  plugins[pluginId] = matchIndex >= 0
-    ? pruned.map((e, i) => (i === matchIndex ? newEntry : e))
-    : [...pruned, newEntry];
-  installed.plugins = plugins;
-
-  let settings = {};
-  if (fs.existsSync(settingsPath)) {
-    try {
-      settings = readJsonMaybe(settingsPath) ?? {};
-    } catch {
-      settings = {};
-    }
-  }
-  settings.enabledPlugins = ensureObject(settings.enabledPlugins);
-  settings.enabledPlugins[pluginId] = true;
 
   if (dryRun) {
-    console.log("[dry-run] Would register Claude plugin:", JSON.stringify(newEntry, null, 2));
+    console.log("[dry-run] Would register Claude plugin (project-scoped) at:", projectRoot);
     return;
   }
 
-  fs.mkdirSync(claudePluginsDir, { recursive: true });
-  fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
-  fs.writeFileSync(installedPath, JSON.stringify(installed, null, 2) + "\n", "utf8");
-  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
+  // Registration is always project-scoped: write only to <project>/.claude/settings.json.
+  // Claude Code manages ~/.claude/plugins/installed_plugins.json itself via marketplace flow;
+  // writing to user-level files causes "unregistered local marketplace" errors on startup.
+  const projectSettingsPath = path.join(projectRoot, ".claude", "settings.json");
+  let projectSettings = {};
+  if (fs.existsSync(projectSettingsPath)) {
+    try { projectSettings = readJsonMaybe(projectSettingsPath) ?? {}; } catch { projectSettings = {}; }
+  }
+  projectSettings.enabledPlugins = ensureObject(projectSettings.enabledPlugins);
+  projectSettings.enabledPlugins[pluginId] = true;
+  // Remove stale/invalid marketplace keys left by earlier install methods
+  if (projectSettings.extraKnownMarketplaces?.["compound-workflow"]) {
+    delete projectSettings.extraKnownMarketplaces["compound-workflow"];
+  }
+  projectSettings.extraKnownMarketplaces = ensureObject(projectSettings.extraKnownMarketplaces);
+  projectSettings.extraKnownMarketplaces["compound-workflow-local"] = {
+    source: { source: "file", path: ".claude-plugin/marketplace.json" },
+  };
+  fs.mkdirSync(path.join(projectRoot, ".claude"), { recursive: true });
+  fs.writeFileSync(projectSettingsPath, JSON.stringify(projectSettings, null, 2) + "\n", "utf8");
 
-  if (!isSelfInstall) {
-    const projectSettingsPath = path.join(targetRoot, ".claude", "settings.json");
-    let projectSettings = {};
-    if (fs.existsSync(projectSettingsPath)) {
-      try { projectSettings = readJsonMaybe(projectSettingsPath) ?? {}; } catch { projectSettings = {}; }
-    }
-    projectSettings.enabledPlugins = ensureObject(projectSettings.enabledPlugins);
-    projectSettings.enabledPlugins[pluginId] = true;
-    // Remove invalid "local" entry if present; then register local marketplace via "file" so it appears without slash commands
-    if (projectSettings.extraKnownMarketplaces?.["compound-workflow"]) {
-      delete projectSettings.extraKnownMarketplaces["compound-workflow"];
-    }
-    projectSettings.extraKnownMarketplaces = ensureObject(projectSettings.extraKnownMarketplaces);
-    projectSettings.extraKnownMarketplaces["compound-workflow-local"] = {
-      source: { source: "file", path: ".claude-plugin/marketplace.json" },
-    };
-    fs.mkdirSync(path.join(targetRoot, ".claude"), { recursive: true });
-    fs.writeFileSync(projectSettingsPath, JSON.stringify(projectSettings, null, 2) + "\n", "utf8");
+  // Clean up any stale user-level enabledPlugins entries left by previous install versions.
+  // These cause "unregistered local marketplace" errors on every Claude Code startup.
+  if (fs.existsSync(settingsPath)) {
+    try {
+      let userSettings = readJsonMaybe(settingsPath) ?? {};
+      const staleIds = ["compound-workflow@local", "compound-workflow@compound-workflow-local"];
+      let changed = false;
+      for (const id of staleIds) {
+        if (userSettings?.enabledPlugins?.[id] !== undefined) {
+          delete userSettings.enabledPlugins[id];
+          changed = true;
+        }
+      }
+      if (changed) {
+        fs.writeFileSync(settingsPath, JSON.stringify(userSettings, null, 2) + "\n", "utf8");
+        console.log("Cleaned up stale compound-workflow entries from ~/.claude/settings.json");
+      }
+    } catch { /* ignore */ }
   }
 
-  console.log("Registered compound-workflow with Claude Code.");
+  console.log("Registered compound-workflow with Claude Code (project-scoped).");
   if (!isSelfInstall) {
     console.log("  Claude Code 2.1+: open /plugin, go to Discover; install 'compound-workflow' from marketplace 'compound-workflow-local', or run: claude --plugin-dir ./node_modules/compound-workflow");
   }
@@ -604,6 +908,31 @@ function main() {
   const args = parseArgs(process.argv);
   const targetRoot = realpathSafe(args.root);
 
+  // Handle verification mode early (no manifest needed)
+  if (args.verify) {
+    console.log("Verifying plugin integrity...");
+    const isSelfInstall = realpathSafe(targetRoot) === realpathSafe(PACKAGE_ROOT);
+    // Try to read manifest for accurate verification, but continue without it
+    try {
+      GENERATED_MANIFEST = readGeneratedManifest();
+    } catch {
+      console.warn("Warning: Could not read generated manifest, using filesystem scan only");
+      GENERATED_MANIFEST = { commands: [], agents: [] };
+    }
+    const result = verifyPluginIntegrity(targetRoot, isSelfInstall);
+    if (result.ok) {
+      console.log("Plugin integrity: OK (all symlinks present and valid)");
+      process.exit(0);
+    } else {
+      console.error("Plugin integrity issues found:");
+      for (const issue of result.issues) {
+        console.error(`  - ${issue}`);
+      }
+      console.error("\nRun 'npx compound-workflow install' to fix.");
+      process.exit(1);
+    }
+  }
+
   const genScript = path.join(PACKAGE_ROOT, "scripts", "generate-platform-artifacts.mjs");
   if (fs.existsSync(genScript)) {
     console.log("[compound-workflow] Regenerating manifest from package source...");
@@ -647,6 +976,8 @@ function main() {
   writeOpenCodeJson(targetRoot, args.dryRun, isSelfInstall);
   writePluginManifests(targetRoot, args.dryRun, isSelfInstall);
   syncCursorSkills(targetRoot, args.dryRun, isSelfInstall);
+  syncCursorCommands(targetRoot, args.dryRun, isSelfInstall);
+  syncCursorAgents(targetRoot, args.dryRun, isSelfInstall);
   applyCursorRegistration(targetRoot, args.dryRun, args.noRegisterCursor, args.registerCursor, isSelfInstall);
   reportOpenCodeIntegration(targetRoot, args.dryRun);
   writeAgentsMd(targetRoot, args.dryRun);

package/src/.agents/commands/workflow-work.md

@@ -361,6 +361,105 @@ The input must be a plan file path.
 
    Trigger: you cannot proceed safely due to ambiguity, missing info, failing approach, or environment/tooling issue.
 
+   **Stuck Guard (auto-research pre-step)**
+
+   When the Blocker Protocol triggers, evaluate whether the guard should fire:
+
+   **Trigger 1 — Unknown territory:** The agent explicitly cannot identify a clear next step after consulting available context and codebase patterns. Requires agent self-declaration (e.g. "required API behavior is not in context," "no codebase pattern exists for this operation").
+
+   **Trigger 2 — Repeated failures:** ≥2 distinct failed approaches on the same todo step, OR ≥3 total failures on the same todo regardless of step or approach variety. Failure = a test, lint, type, or runtime check produces an error the agent cannot resolve within one further attempt.
+
+   **Guard suppression:** The Stuck Guard MUST NOT fire for todos tagged `tags: [spike]`. If a Spike is inconclusive, surface through standard Spike completion flow.
+
+   **When guard fires (steps 1–10, mandatory order):**
+
+   1. Guard trigger detected (unknown_territory OR repeated_failure)
+   2. Announce to user: "Pausing to investigate..."
+   3. **Immediately** transition todo: `ready` → `pending + tags: [blocker]`
+   4. Add placeholder Work Log entry: `"Stuck Guard triggered. Investigation in progress. [stuck_type]. [timestamp]. Partial changes may exist — review working directory before resuming."`
+   5. Dispatch sub-agents in **parallel**:
+      - **Mandatory (always):** `Task repo-research-analyst(<context>)`, `Task learnings-researcher(<context>)`
+      - **Conditional (by signal, not discretion):**
+        - If failure mentions external library/package/API → add `Task framework-docs-researcher(<context>)`
+        - If stuck on approach/pattern/architecture choice → add `Task best-practices-researcher(<context>)`
+        - If modifying existing code (not creating new) → add `Task git-history-analyzer(<context>)`
+   6. Collect findings (single-pass; no recursive guard firing)
+   7. Synthesize enriched output (format below)
+   8. Update Work Log `Blocker Decision` section with full enriched output
+   9. Present decision prompt to user
+   10. After user decision: apply existing Blocker Protocol after-decision steps (convert to todos; triage re-approval before returning to `ready`)
+
+   **Context payload for each sub-agent:**
+   ```
+   {
+     todo_title: <title>,
+     todo_description: <problem statement>,
+     stuck_type: "unknown_territory" | "repeated_failure",
+     failure_description: <specific error/blocker>,
+     working_directory: <worktree path>
+   }
+   ```
+
+   **Fallback when Task dispatch unavailable:** Announce: "Research sub-agents unavailable — proceeding with agent-reasoned options only." Produce standard Blocker output (no enrichment). Do NOT silently present unresearched options as researched.
+
+   **Enriched output format (replaces standard Blocker output):**
+
+   ```markdown
+   ## Stuck Guard Triggered
+
+   **Detected:** [unknown_territory | repeated_failure]
+   **Investigating...** Launching: repo-research-analyst, learnings-researcher[, framework-docs-researcher][, best-practices-researcher][, git-history-analyzer]
+
+   ---
+
+   ## Research Findings
+
+   - **repo-research-analyst:** [2–5 sentence summary, or "no findings returned"]
+   - **learnings-researcher:** [2–5 sentence summary, or "no findings returned"]
+   - **framework-docs-researcher:** [2–5 sentence summary, or "not invoked" | "no findings returned"]
+   - **best-practices-researcher:** [2–5 sentence summary, or "not invoked" | "no findings returned"]
+   - **git-history-analyzer:** [2–5 sentence summary, or "not invoked" | "no findings returned"]
+
+   **Synthesis confidence:** `high` | `medium` | `low` (low when all agents return empty)
+
+   ---
+
+   ## Blocker Summary
+
+   [1–2 sentences describing what blocked execution]
+
+   ## Constraints Discovered
+
+   - [constraint 1]
+   - [constraint 2]
+
+   ## Options
+
+   **Option 1: [Name]** *(source: [agent name(s)] | agent-reasoned)*
+   - Pros: ...
+   - Cons: ...
+   - Risk: ...
+   - Effort: ...
+
+   **Option 2: [Name]** *(source: [agent name(s)] | agent-reasoned)*
+   - ...
+
+   **Option 3: [Name]** *(source: [agent name(s)] | agent-reasoned)*
+   - ...
+
+   ## Recommendation
+
+   [One option + 2–4 bullets citing research findings]
+
+   ---
+
+   *Which option should we take?*
+   ```
+
+   **When findings are empty:** Produce ≥3 options marked `*(agent-reasoned — research returned no findings)*`. Set synthesis confidence to `low`. Do not fabricate citations.
+
+   **When a Spike is recommended:** Use standard Spike Candidate format from Spike Protocol (Initial priority, Depends on, Unblocks, Timebox, Deliverable, Parallelizable metadata).
+
    Rules:
    - Pause implementation. Do not “push through” with guesses.
    - Timebox investigation to reach options (not a full rewrite).

package/src/.agents/skills/presentation-composability/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: presentation-composability
+description: Enforce folder-per-component structure for tapesv3 presentation modules. Use when creating or refactoring components under src/features/tapesv3/presentation/.
+---
+
+# Presentation Composability
+
+Enforce folder-per-component structure for tapesv3 presentation modules.
+
+## When to Use
+
+- Adding new presentation components to tapesv3
+- Refactoring existing tapesv3 presentation into composable pieces
+- Aligning new UI with established tapesv3 patterns
+
+## Structure Rules
+
+### One folder per composable
+
+Each logical UI element gets its own subfolder (PascalCase):
+
+```
+presentation/FeatureName/
+├── index.ts              # barrel
+├── SubComponentA/
+│   ├── index.tsx
+│   └── styles.ts
+├── SubComponentB/
+│   ├── index.tsx
+│   └── styles.ts
+└── SubComponentC/
+    └── index.tsx         # styles.ts optional if no styled components
+```
+
+### Barrel (`index.ts`)
+
+Re-export from subfolders. Two patterns:
+
+**Flat exports** (simple feature, independent components):
+
+```typescript
+export { SubComponentA } from "./SubComponentA";
+export { SubComponentB } from "./SubComponentB";
+```
+
+**Compound component** (Root + subcomponents used together):
+
+```typescript
+export const FeatureName = Object.assign(RootComponent, {
+  SubA: SubComponentA,
+  SubB: SubComponentB,
+});
+```
+
+### Component + styles
+
+- `index.tsx`: component logic and JSX
+- `styles.ts`: styled-components (or emotion) only
+- Import: `import * as S from "./styles"` or `import { Root, Item } from "./styles"`
+
+### Reference implementations
+
+- `SharedTabsHeader` – compound pattern (Root.Action, Root.BackgroundPicker)
+- `PanelClipsArtist`, `FolderSelector` – compound pattern
+- `MultiSourceThreads` – flat exports (FilterBar, Message, Input, List)
+- `TapesTabBarTabOptions` – flat exports
+
+## Anti-patterns
+
+- Single file with multiple components and inline styles
+- `ComponentName.styles.ts` – use `styles.ts` in the component folder
+- Barrel re-exporting from sibling files instead of subfolders

package/src/AGENTS.md

@@ -172,7 +172,7 @@ worktree_bootstrap_notes:
 ## Implemented Components (Current Scope)
 
 - Commands: `workflow:brainstorm`, `workflow:plan`, `workflow:triage`, `workflow:work`, `workflow:review`, `workflow:tech-review`, `workflow:compound` (under `.agents/commands/` as `workflow-*.md`), plus `test-browser`, `metrics`, `assess`, `install` (root commands)
-- Skills: `brainstorming`, `document-review`, `technical-review`, `compound-docs` (alias: `compound_doc`), `capture-skill`, `file-todos`, `agent-browser`, `git-worktree`, `process-metrics`, `react-ddd-mvc-frontend`, `xstate-actor-orchestration`, `standards`, `pii-protection-prisma`, `financial-workflow-integrity`, `audit-traceability`, `data-foundations`
+- Skills: `brainstorming`, `document-review`, `technical-review`, `compound-docs` (alias: `compound_doc`), `capture-skill`, `file-todos`, `agent-browser`, `git-worktree`, `process-metrics`, `react-ddd-mvc-frontend`, `xstate-actor-orchestration`, `standards`, `pii-protection-prisma`, `financial-workflow-integrity`, `audit-traceability`, `data-foundations`, `presentation-composability`
 - Agents:
   - `repo-research-analyst`
   - `learnings-researcher`
@@ -237,6 +237,7 @@ Maintenance:
 | `react-ddd-mvc-frontend` | You need React frontend architecture guidance (DDD + MVC hybrid) during planning or review to enforce feature structure, layer boundaries, composable pure components, container/controller responsibilities, and maintainable patterns. |
 | `xstate-actor-orchestration` | You are evaluating complexity and need explicit state orchestration: React container-as-orchestrator for UI flows, or actor/state-machine orchestration for backend/internal workflows (especially multi-step async branching, retries/timeouts/cancellation, receptionist/child-actor coordination, or boolean-flag sprawl). |
 | `standards` | You need Altai coding standards for implementation and refactoring, including domain entity patterns, XState conventions, type usage, and feature code organization. |
+| `presentation-composability` | You are creating or refactoring presentation components in tapesv3 and need folder-per-component structure with barrel exports and styles separation. |
 
 ### Reference standards (guardrails)