compound-workflow 1.6.6 → 1.6.8

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "compound-workflow",
-  "version": "1.6.6",
+  "version": "1.6.8",
   "description": "Clarify -> plan -> execute -> verify -> capture workflow: commands, skills, and agents for Claude Code",
   "author": {
     "name": "Compound Workflow"

package/.cursor-plugin/plugin.json

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

package/scripts/check-workflow-contracts.mjs

@@ -58,93 +58,93 @@ const requiredChecks = [
     description: "README standards baseline guardrail",
   },
   {
-    file: "src/.agents/commands/workflow/plan.md",
+    file: "src/.agents/commands/workflow-plan.md",
     pattern: "Contract precedence:",
     description: "plan command precedence note",
   },
   {
-    file: "src/.agents/commands/workflow/triage.md",
+    file: "src/.agents/commands/workflow-triage.md",
     pattern: "Contract precedence:",
     description: "triage command precedence note",
   },
   {
-    file: "src/.agents/commands/workflow/triage.md",
+    file: "src/.agents/commands/workflow-triage.md",
     pattern: "independently runnable",
     description: "triage command explicitly standalone while work auto-runs triage",
   },
   {
-    file: "src/.agents/commands/workflow/work.md",
+    file: "src/.agents/commands/workflow-work.md",
     pattern: "Contract precedence:",
     description: "work command precedence note",
   },
   {
-    file: "src/.agents/commands/workflow/plan.md",
+    file: "src/.agents/commands/workflow-plan.md",
     pattern: "Start `/workflow:work`",
     description: "plan command default next-step routes to work",
   },
   {
-    file: "src/.agents/commands/workflow/work.md",
+    file: "src/.agents/commands/workflow-work.md",
     pattern: "HARD GATE - WORKTREE FIRST",
     description: "worktree hard-gate wording in work command",
   },
   {
-    file: "src/.agents/commands/workflow/work.md",
+    file: "src/.agents/commands/workflow-work.md",
     pattern: "required prompt/create gate",
     description: "mandatory worktree decision prompt/create gate in work command",
   },
   {
-    file: "src/.agents/commands/workflow/work.md",
+    file: "src/.agents/commands/workflow-work.md",
     pattern: "Do not infer or assume an answer when the user has not answered.",
     description: "worktree decision cannot be silently assumed",
   },
   {
-    file: "src/.agents/commands/workflow/work.md",
+    file: "src/.agents/commands/workflow-work.md",
     pattern:
       "No file writes, implementation commands, test/lint/typecheck commands, or dependency-install commands may run before this gate passes.",
     description: "pre-gate write/command prohibition in work command",
   },
   {
-    file: "src/.agents/commands/workflow/work.md",
+    file: "src/.agents/commands/workflow-work.md",
     pattern: "workflow_complete: false (pending /workflow:review current)",
     description: "implementation-complete pending-review status in work command",
   },
   {
-    file: "src/.agents/commands/workflow/work.md",
+    file: "src/.agents/commands/workflow-work.md",
     pattern: "Standards Compliance Gate (REQUIRED for code/config changes)",
     description: "required standards gate in work command",
   },
   {
-    file: "src/.agents/commands/workflow/work.md",
+    file: "src/.agents/commands/workflow-work.md",
     pattern: "This gate cannot run until the isolation/worktree gate is passed and recorded (`gate_status: passed`).",
     description: "standards gate ordering with worktree gate",
   },
   {
-    file: "src/.agents/commands/workflow/review.md",
+    file: "src/.agents/commands/workflow-review.md",
     pattern: "Contract precedence:",
     description: "review command precedence note",
   },
   {
-    file: "src/.agents/commands/workflow/review.md",
+    file: "src/.agents/commands/workflow-review.md",
     pattern: "Independent Reviewer Pass (REQUIRED)",
     description: "required independent reviewer pass in review command",
   },
   {
-    file: "src/.agents/commands/workflow/review.md",
+    file: "src/.agents/commands/workflow-review.md",
     pattern: "review_independence_mode: independent|degraded",
     description: "explicit review independence mode in review command",
   },
   {
-    file: "src/.agents/commands/workflow/review.md",
+    file: "src/.agents/commands/workflow-review.md",
     pattern: "what was skipped and why",
     description: "review skipped-pass disclosure requirement",
   },
   {
-    file: "src/.agents/commands/workflow/review.md",
+    file: "src/.agents/commands/workflow-review.md",
     pattern: "standards_compliance: pass|pass-with-notes|fail",
     description: "review standards compliance output field",
   },
   {
-    file: "src/.agents/commands/workflow/review.md",
+    file: "src/.agents/commands/workflow-review.md",
     pattern: "standards `MUST` violations => blocking finding and review recommendation `fail`",
     description: "review must-violation fail criteria",
   },
@@ -162,22 +162,22 @@ const requiredChecks = [
 
 const forbiddenChecks = [
   {
-    file: "src/.agents/commands/workflow/work.md",
+    file: "src/.agents/commands/workflow-work.md",
     pattern: "## When to Use Reviewer Agents",
     description: "legacy optional reviewer section in work command",
   },
   {
-    file: "src/.agents/commands/workflow/work.md",
+    file: "src/.agents/commands/workflow-work.md",
     pattern: "**Don't use by default.**",
     description: "legacy skip-by-default reviewer wording in work command",
   },
   {
-    file: "src/.agents/commands/workflow/work.md",
+    file: "src/.agents/commands/workflow-work.md",
     pattern: "skip specialist reviewers by default",
     description: "legacy skip-by-default specialist reviewer wording",
   },
   {
-    file: "src/.agents/commands/workflow/work.md",
+    file: "src/.agents/commands/workflow-work.md",
     pattern: "Follow project coding standards (see AGENTS.md)",
     description: "legacy advisory-only coding standards wording in work command",
   },

package/scripts/install-cli.mjs

@@ -1,8 +1,17 @@
 #!/usr/bin/env node
 /**
  * compound-workflow install
+ *
  * Native-only install: writes opencode.json from package metadata,
  * merges AGENTS.md, and ensures standard docs/todo directories.
+ *
+ * DECLARATIVE SOURCE OF TRUTH (no manual wiring):
+ * - Commands: add/remove .md under src/.agents/commands/ (frontmatter: invocation, name, description).
+ *   Registry (src/.agents/registry.json) + generate-platform-artifacts → opencode.managed.json → install.
+ * - Agents: add/remove .md under src/.agents/agents/ (frontmatter: name, description). Same pipeline.
+ * - Skills: add/remove dir src/.agents/skills/<name>/SKILL.md. OpenCode uses skills path; install syncs
+ *   each skill into .cursor/skills/ (symlinks) so Cursor discovers them. Prune removes stale symlinks.
+ * Run install (or npm install compound-workflow) after any change; no other registration needed.
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -356,33 +365,102 @@ function writePluginManifests(targetRoot, dryRun, isSelfInstall) {
   console.log("Wrote: .cursor-plugin/plugin.json, .claude-plugin/plugin.json, .cursor-plugin/registration.json");
 }
 
-function cursorDetected() {
-  return fs.existsSync(path.join(os.homedir(), ".cursor"));
-}
+/**
+ * Cursor discovers skills only from .agents/skills, .cursor/skills, ~/.cursor/skills.
+ * Populate .cursor/skills/ with symlinks to the package skills so Cursor finds them.
+ */
+function syncCursorSkills(targetRoot, dryRun, isSelfInstall) {
+  const packageSkillsAbs = isSelfInstall
+    ? path.join(PACKAGE_ROOT, "src", ".agents", "skills")
+    : path.join(targetRoot, "node_modules", "compound-workflow", "src", ".agents", "skills");
+  if (!fs.existsSync(packageSkillsAbs)) return;
+
+  const cursorSkillsDir = path.join(targetRoot, ".cursor", "skills");
+  let entries;
+  try {
+    entries = fs.readdirSync(packageSkillsAbs, { withFileTypes: true });
+  } catch {
+    return;
+  }
 
-function applyCursorRegistration(targetRoot, dryRun, noRegisterCursor, forceRegister) {
-  if (dryRun) return;
-  if (noRegisterCursor && !forceRegister) return;
-  const shouldApply = forceRegister || (cursorDetected() && !noRegisterCursor);
-  if (!shouldApply) {
-    console.log("[cursor] Cursor not detected; skipped plugin registration. Use --register-cursor to force.");
+  const skillDirs = entries.filter((e) => e.isDirectory() && fs.existsSync(path.join(packageSkillsAbs, e.name, "SKILL.md"))).map((e) => e.name);
+  if (skillDirs.length === 0) return;
+
+  if (dryRun) {
+    console.log("[dry-run] Would symlink", skillDirs.length, "skills into .cursor/skills/");
     return;
   }
 
-  const registrationPath = path.join(targetRoot, ".cursor-plugin", "registration.json");
-  if (!fs.existsSync(registrationPath)) return;
-  let descriptor;
+  fs.mkdirSync(cursorSkillsDir, { recursive: true });
+  const packageSkillsReal = realpathSafe(packageSkillsAbs);
+  const skillSet = new Set(skillDirs);
+
+  // Prune: remove symlinks that point at our package but are no longer in the package
   try {
-    descriptor = readJsonMaybe(registrationPath);
+    for (const entry of fs.readdirSync(cursorSkillsDir, { withFileTypes: true })) {
+      if (!entry.isSymbolicLink()) continue;
+      const linkPath = path.join(cursorSkillsDir, entry.name);
+      try {
+        const resolved = realpathSafe(linkPath);
+        if (!resolved.startsWith(packageSkillsReal + path.sep) && resolved !== packageSkillsReal) continue;
+        const base = path.basename(resolved);
+        if (skillSet.has(base)) continue;
+        fs.rmSync(linkPath);
+      } catch {
+        /* ignore broken symlinks or permission errors */
+      }
+    }
   } catch {
-    return;
+    /* .cursor/skills not readable */
+  }
+
+  for (const name of skillDirs) {
+    const linkPath = path.join(cursorSkillsDir, name);
+    const targetPath = path.join(packageSkillsAbs, 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, "dir");
+    } catch (err) {
+      if (err.code === "EPERM" && process.platform === "win32") {
+        try {
+          fs.symlinkSync(targetPath, linkPath, "junction");
+        } catch {
+          console.warn("[cursor] Could not symlink skill", name, err.message);
+        }
+      } else {
+        console.warn("[cursor] Could not symlink skill", name, err.message);
+      }
+    }
   }
-  if (!descriptor?.pluginId || !descriptor?.installPath) return;
+  console.log("Synced", skillDirs.length, "skills to .cursor/skills/");
+}
+
+function cursorDetected() {
+  return fs.existsSync(path.join(os.homedir(), ".cursor"));
+}
+
+function applyCursorRegistration(targetRoot, dryRun, noRegisterCursor, forceRegister) {
+  if (dryRun) return;
 
   const claudePluginsDir = path.join(os.homedir(), ".claude", "plugins");
   const installedPath = path.join(claudePluginsDir, "installed_plugins.json");
   const settingsPath = path.join(os.homedir(), ".claude", "settings.json");
 
+  const pluginDescriptor = {
+    pluginId: "compound-workflow@local",
+    scope: "user",
+    installPath: realpathSafe(targetRoot),
+  };
+
   let installed = {};
   if (fs.existsSync(installedPath)) {
     try {
@@ -392,7 +470,7 @@ function applyCursorRegistration(targetRoot, dryRun, noRegisterCursor, forceRegi
     }
   }
   const plugins = ensureObject(installed.plugins);
-  plugins[descriptor.pluginId] = [{ scope: descriptor.scope || "user", installPath: descriptor.installPath }];
+  plugins[pluginDescriptor.pluginId] = [{ scope: pluginDescriptor.scope || "user", installPath: pluginDescriptor.installPath }];
   installed.plugins = plugins;
 
   let settings = {};
@@ -404,12 +482,23 @@ function applyCursorRegistration(targetRoot, dryRun, noRegisterCursor, forceRegi
     }
   }
   settings.enabledPlugins = ensureObject(settings.enabledPlugins);
-  settings.enabledPlugins[descriptor.pluginId] = true;
+  settings.enabledPlugins[pluginDescriptor.pluginId] = true;
 
   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");
+  console.log("Registered compound-workflow with Claude Code. Restart Claude Code; enable 'Include third-party Plugins, Skills, and other configs' in Settings if needed.");
+
+  if (noRegisterCursor && !forceRegister) return;
+  const shouldApply = forceRegister || (cursorDetected() && !noRegisterCursor);
+  if (!shouldApply) {
+    console.log("[cursor] Cursor not detected; skipped Cursor plugin registration. Use --register-cursor to force.");
+    return;
+  }
+
+  const registrationPath = path.join(targetRoot, ".cursor-plugin", "registration.json");
+  if (!fs.existsSync(registrationPath)) return;
   console.log("Registered compound-workflow with Cursor. Restart Cursor; enable 'Include third-party Plugins, Skills, and other configs' in Settings if needed.");
 }
 
@@ -477,6 +566,7 @@ function main() {
 
   writeOpenCodeJson(targetRoot, args.dryRun, isSelfInstall);
   writePluginManifests(targetRoot, args.dryRun, isSelfInstall);
+  syncCursorSkills(targetRoot, args.dryRun, isSelfInstall);
   applyCursorRegistration(targetRoot, args.dryRun, args.noRegisterCursor, args.registerCursor);
   reportOpenCodeIntegration(targetRoot, args.dryRun);
   writeAgentsMd(targetRoot, args.dryRun);

package/src/.agents/scripts/self-check.mjs

@@ -12,7 +12,7 @@ Checks:
   - Managed entries in opencode.json point to existing source files
   - Flags missing required frontmatter fields:
     - commands: description (all)
-    - commands/workflow/**: invocation (recommended/expected)
+    - commands/workflow-*.md: invocation (recommended/expected)
     - agents: description (all)
 `;
   (exitCode === 0 ? console.log : console.error)(msg.trimStart());
@@ -178,7 +178,7 @@ function main() {
   for (const c of cmds) {
     if (!c.id) errors.push(`Command missing id (name/invocation): ${c.rel}`);
     if (!c.fm.description) errors.push(`Command missing frontmatter description: ${c.rel} (${c.id || "?"})`);
-    if (c.rel.startsWith(".agents/commands/workflow/") && !c.fm.invocation) {
+    if (c.rel.includes("commands/workflow-") && !c.fm.invocation) {
       errors.push(`Workflow command missing frontmatter invocation: ${c.rel} (${c.id || "?"})`);
     }
     if (c.id && !commandsReg[c.id]) errors.push(`Command not registered in opencode.json: ${c.id} (source: ${c.rel})`);

package/src/.agents/skills/standards/SKILL.md

@@ -9,8 +9,11 @@ description: General coding practices, implementation styles, and patterns for t
 
 These rules are mandatory for code/config implementation work. They are pass/fail gates, not advisory guidance.
 
+**Declarative over imperative:** Prefer declarative solutions by requirement. Describe *what* should hold (state, transitions, invariants) and let the runtime or framework determine *how*; avoid imperative step-by-step control that mutates shared state in place.
+
 ### MUST
 
+- **MUST prefer declarative over imperative:** Orchestration and data flow MUST be expressed declaratively (state/events/transitions, pure transforms) rather than imperative sequences (mutating variables, step-by-step handlers). When both are feasible, choose the declarative option.
 - **MUST keep orchestration declarative** in containers/controllers: describe state transitions and event flow explicitly instead of imperative step-by-step control logic.
 - **MUST use immutable transforms** for domain and controller data operations (`input -> output`), returning new values instead of mutating existing objects/arrays.
 - **MUST keep domain logic in pure entity functions** (no side effects, no hidden mutable module state, no IO in entity transforms/predicates).
@@ -22,6 +25,7 @@ These rules are mandatory for code/config implementation work. They are pass/fai
 
 ### MUST NOT
 
+- **MUST NOT choose imperative over declarative** when a declarative solution is feasible (e.g. state machine + events over manual flags and step counters; pure transforms over in-place mutation).
 - **MUST NOT implement mutation-heavy imperative handlers** that modify shared state in-place across multiple steps.
 - **MUST NOT use hidden mutable accumulators** (`let` variables mutated through control flow) when a pure transform is feasible.
 - **MUST NOT mix business decision logic into containers/presentation** when it belongs in domain entities/controllers.
@@ -34,6 +38,7 @@ Use this format when reporting standards compliance in execution or review evide
 
 ```markdown
 standards_compliance:
+- declarative_over_imperative: pass|fail (evidence: file:line)  # Declarative solutions required; no imperative choice when declarative feasible
 - declarative_flow: pass|fail (evidence: file:line)
 - immutable_transforms: pass|fail (evidence: file:line)
 - maintainability_boundaries: pass|fail (evidence: file:line)

package/src/AGENTS.md

@@ -54,7 +54,7 @@ If workflow documents conflict, resolve them in this order:
 
 1. `docs/principles/workflow-baseline-principles.md`
 2. This file (`src/AGENTS.md`) non-negotiables and repo config
-3. Workflow command specs (`src/.agents/commands/workflow/*.md`)
+3. Workflow command specs (`src/.agents/commands/workflow-*.md`)
 4. Skill docs (`src/.agents/skills/*/SKILL.md`)
 
 ## Non-negotiables (Structure Integrity)
@@ -161,15 +161,17 @@ worktree_bootstrap_notes:
 
 ## Directory Layout
 
-- Commands: `.agents/commands/*.md` and `.agents/commands/workflow/*.md` (workflow namespace)
+- Commands: `.agents/commands/*.md` and `.agents/commands/workflow-*.md` (workflow namespace)
 - Skills: `.agents/skills/*/SKILL.md`
 - Skills may optionally include tool-specific agent metadata under `.agents/skills/*/agents/` (for example `openai.yaml`) when required by that skill's validator/runtime.
 - References: `.agents/references/**`
 - Agents: `.agents/agents/**/*.md`
 
+**Single source of truth (declarative):** Commands and agents are discovered from the registry and `generate-platform-artifacts`; skills are discovered by scanning `skills/` for `*/SKILL.md`. Add or remove files/dirs, then run install—no other registration. See install-cli header comment for the full pipeline.
+
 ## Implemented Components (Current Scope)
 
-- Commands: `workflow:brainstorm`, `workflow:plan`, `workflow:triage`, `workflow:work`, `workflow:review`, `workflow:tech-review`, `workflow:compound` (under `.agents/commands/workflow/`), plus `test-browser`, `metrics`, `assess`, `install` (root commands)
+- 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`
 - Agents:
   - `repo-research-analyst`

package/src/generated/opencode.managed.json

@@ -27,37 +27,37 @@
     {
       "id": "workflow:brainstorm",
       "description": "Explore requirements and approaches through collaborative dialogue before planning implementation",
-      "rel": "workflow/brainstorm.md"
+      "rel": "workflow-brainstorm.md"
     },
     {
       "id": "workflow:compound",
       "description": "Document a durable learning (solved problem or implementation insight) into docs/solutions/ to compound institutional knowledge",
-      "rel": "workflow/compound.md"
+      "rel": "workflow-compound.md"
     },
     {
       "id": "workflow:plan",
       "description": "Transform feature descriptions into well-structured project plans using an explicit fidelity and confidence model",
-      "rel": "workflow/plan.md"
+      "rel": "workflow-plan.md"
     },
     {
       "id": "workflow:review",
       "description": "Review a PR/branch/diff with structured findings. Does not implement fixes unless explicitly requested.",
-      "rel": "workflow/review.md"
+      "rel": "workflow-review.md"
     },
     {
       "id": "workflow:tech-review",
       "description": "Run technical review on a plan (technical correctness before build). Optional plan path or latest in docs/plans/.",
-      "rel": "workflow/tech-review.md"
+      "rel": "workflow-tech-review.md"
     },
     {
       "id": "workflow:triage",
       "description": "Manual triage command to prioritize todo files into an executable ready queue (priority, dependencies, recommended action)",
-      "rel": "workflow/triage.md"
+      "rel": "workflow-triage.md"
     },
     {
       "id": "workflow:work",
       "description": "Execute a plan file systematically (implementation + verification) without auto-shipping",
-      "rel": "workflow/work.md"
+      "rel": "workflow-work.md"
     }
   ],
   "agents": [