compound-workflow 1.7.0 → 1.7.2

package/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "compound-workflow",
-  "version": "1.7.0",
+  "version": "1.7.2",
   "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.7.0",
+  "version": "1.7.2",
   "description": "Clarify → plan → execute → verify → capture. One Install action for Cursor, Claude, and OpenCode.",
   "license": "MIT",
   "repository": {

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);
@@ -342,10 +343,12 @@ function writePluginManifests(targetRoot, dryRun, isSelfInstall) {
   if (!cursorManifest || !claudeManifest) return;
 
   // Cursor supports full manifest with commands/agents/skills path overrides.
+  // For commands/agents, use .cursor/ directories where symlinks are created
+  // so Cursor can discover them properly. Skills still use source path.
   const cursorOut = {
     ...cursorManifest,
-    commands: `${pathsBase}/commands`,
-    agents: `${pathsBase}/agents`,
+    commands: "./.cursor/commands",
+    agents: "./.cursor/agents",
     skills: `${pathsBase}/skills`,
   };
   // Claude Code only accepts name, description, author in plugin.json.
@@ -504,10 +507,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");
@@ -610,6 +910,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...");
@@ -653,6 +978,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/test-browser.md

@@ -6,7 +6,7 @@ argument-hint: "[PR number, branch name, or 'current' for current branch]"
 
 # Browser Test Command
 
-<command_purpose>Run end-to-end browser tests on pages affected by a PR or branch changes using agent-browser CLI.</command_purpose>
+Run end-to-end browser tests on pages affected by a PR or branch changes using agent-browser CLI.
 
 ## CRITICAL: Use agent-browser CLI Only
 

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

@@ -7,8 +7,9 @@ argument-hint: "[feature idea or problem to explore]"
 
 # Brainstorm a Feature or Improvement
 
-**Note: The current year is 2026.** Use this when dating brainstorm
-documents.
+Explore requirements and approaches through collaborative dialogue before planning implementation.
+
+**Note: The current year is 2026.** Use this when dating brainstorm documents.
 
 Brainstorming helps answer **WHAT** to build through collaborative
 dialogue. It precedes `/workflow:plan`, which answers **HOW** to build

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

@@ -7,6 +7,8 @@ argument-hint: "[feature description, bug report, improvement idea, or brainstor
 
 # Create a plan for a new feature or bug fix
 
+Transform feature descriptions into well-structured project plans using an explicit fidelity and confidence model.
+
 ## Introduction
 
 **Note: The current year is 2026.** Use this when dating plans and searching for recent documentation.

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)