compound-workflow 1.6.17 → 1.7.0

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.0",
   "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.0",
   "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

@@ -335,20 +335,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 +375,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) {
@@ -485,87 +522,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");
   }

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).