compound-workflow 1.6.3 → 1.6.5

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "compound-workflow",
-  "version": "1.6.3",
+  "version": "1.6.5",
   "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.3",
+  "version": "1.6.5",
   "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.3",
+  "version": "1.6.5",
   "description": "Clarify → plan → execute → verify → capture. One Install action for Cursor, Claude, and OpenCode.",
   "license": "MIT",
   "repository": {
@@ -18,6 +18,7 @@
   ],
   "scripts": {
     "postinstall": "node scripts/postinstall.mjs",
+    "prepublishOnly": "npm run generate:artifacts",
     "generate:artifacts": "node scripts/generate-platform-artifacts.mjs",
     "check:artifacts": "node scripts/generate-platform-artifacts.mjs --check",
     "check:version-parity": "node scripts/check-version-parity.mjs",

package/scripts/generate-platform-artifacts.mjs

@@ -7,6 +7,14 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const repoRoot = path.resolve(__dirname, "..");
 const agentsRoot = path.join(repoRoot, "src", ".agents");
 
+function loadRegistry() {
+  const registryPath = path.join(agentsRoot, "registry.json");
+  if (!fs.existsSync(registryPath)) {
+    throw new Error(`Registry not found at ${registryPath}`);
+  }
+  return JSON.parse(fs.readFileSync(registryPath, "utf8"));
+}
+
 function walkFiles(dirAbs, predicate) {
   const out = [];
   const stack = [dirAbs];
@@ -42,44 +50,64 @@ function parseFrontmatter(md) {
   return out;
 }
 
-function discoverCommands() {
-  const commandsDir = path.join(agentsRoot, "commands");
-  const files = walkFiles(commandsDir, (p) => p.endsWith(".md"));
-  const commands = [];
-
-  for (const fileAbs of files) {
-    const relWithin = path.relative(commandsDir, fileAbs).replaceAll(path.sep, "/");
-    const frontmatter = parseFrontmatter(fs.readFileSync(fileAbs, "utf8"));
-    const id = (frontmatter.invocation || frontmatter.name || path.basename(fileAbs, ".md")).trim();
-    if (!id) continue;
-    commands.push({
-      id,
-      description: (frontmatter.description || id).trim(),
-      rel: relWithin,
-    });
+/**
+ * Resolve id from frontmatter and config. idFrom = list of frontmatter keys; idFallback = "basename" | "dirname".
+ */
+function resolveId(frontmatter, fileAbs, dirAbs, config) {
+  for (const key of config.idFrom || []) {
+    if (key === "dirname") {
+      const relDir = path.relative(dirAbs, path.dirname(fileAbs));
+      return (relDir ? relDir.replaceAll(path.sep, "/") : path.basename(path.dirname(fileAbs))).trim();
+    }
+    const v = frontmatter[key];
+    if (typeof v === "string" && v.trim()) return v.trim();
   }
+  if (config.idFallback === "basename") return path.basename(fileAbs, ".md").trim();
+  if (config.idFallback === "dirname") return path.basename(path.dirname(fileAbs)).trim();
+  return path.basename(fileAbs, ".md").trim();
+}
 
-  return commands.sort((a, b) => a.id.localeCompare(b.id));
+function resolveDescription(frontmatter, config, id) {
+  const key = config.descriptionFrom;
+  if (key && frontmatter[key] != null) return String(frontmatter[key]).trim();
+  if (config.descriptionFallback === "id") return id || "";
+  return id || "";
 }
 
-function discoverAgents() {
-  const agentDir = path.join(agentsRoot, "agents");
-  const files = walkFiles(agentDir, (p) => p.endsWith(".md"));
-  const agents = [];
+/**
+ * Discover assets of one type from registry config. Returns array of { id, description, rel }.
+ */
+function discoverByType(agentsRootAbs, typeKey, config) {
+  const dirAbs = path.join(agentsRootAbs, config.dir);
+  if (!fs.existsSync(dirAbs)) return [];
+
+  let files = [];
+  if (config.glob === "**/*.md") {
+    files = walkFiles(dirAbs, (p) => p.endsWith(".md"));
+  } else if (config.glob === "*/SKILL.md") {
+    const entries = fs.readdirSync(dirAbs, { withFileTypes: true });
+    for (const e of entries) {
+      if (e.isDirectory()) {
+        const skillMd = path.join(dirAbs, e.name, "SKILL.md");
+        if (fs.existsSync(skillMd)) files.push(skillMd);
+      }
+    }
+    files.sort();
+  } else {
+    files = walkFiles(dirAbs, (p) => p.endsWith(".md"));
+  }
 
+  const out = [];
   for (const fileAbs of files) {
-    const relWithin = path.relative(agentDir, fileAbs).replaceAll(path.sep, "/");
-    const frontmatter = parseFrontmatter(fs.readFileSync(fileAbs, "utf8"));
-    const id = (frontmatter.name || path.basename(fileAbs, ".md")).trim();
+    const rel = path.relative(dirAbs, fileAbs).replaceAll(path.sep, "/");
+    const raw = fs.readFileSync(fileAbs, "utf8");
+    const frontmatter = parseFrontmatter(raw);
+    const id = resolveId(frontmatter, fileAbs, dirAbs, config);
     if (!id) continue;
-    agents.push({
-      id,
-      description: (frontmatter.description || id).trim(),
-      rel: relWithin,
-    });
+    const description = resolveDescription(frontmatter, config, id);
+    out.push({ id, description, rel });
   }
-
-  return agents.sort((a, b) => a.id.localeCompare(b.id));
+  return out.sort((a, b) => a.id.localeCompare(b.id));
 }
 
 function normalizeRepoUrl(repoValue) {
@@ -105,13 +133,25 @@ function writeJson(absPath, value, checkOnly, changed) {
 
 function main() {
   const checkOnly = process.argv.includes("--check");
+  const registry = loadRegistry();
+  const roots = registry.roots?.consumer || {};
+  const assetTypes = registry.assetTypes || {};
+
+  const commands =
+    assetTypes.command != null
+      ? discoverByType(agentsRoot, "command", assetTypes.command)
+      : [];
+  const agents =
+    assetTypes.agent != null ? discoverByType(agentsRoot, "agent", assetTypes.agent) : [];
 
   const pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, "package.json"), "utf8"));
   const repositoryUrl = normalizeRepoUrl(pkg.repository);
-  const commands = discoverCommands();
-  const agents = discoverAgents();
   const changed = [];
 
+  const commandRoot = roots.commands || "node_modules/compound-workflow/src/.agents/commands";
+  const agentRoot = roots.agents || "node_modules/compound-workflow/src/.agents/agents";
+  const skillsPath = roots.skills || "node_modules/compound-workflow/src/.agents/skills";
+
   const claudePlugin = {
     name: pkg.name,
     version: pkg.version,
@@ -140,9 +180,9 @@ function main() {
 
   const openCodeManaged = {
     $schema: "https://opencode.ai/config.json",
-    skillsPath: "node_modules/compound-workflow/src/.agents/skills",
-    commandRoot: "node_modules/compound-workflow/src/.agents/commands",
-    agentRoot: "node_modules/compound-workflow/src/.agents/agents",
+    skillsPath,
+    commandRoot,
+    agentRoot,
     commands,
     agents,
   };

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

@@ -18,6 +18,8 @@ it.
 discussion-first facilitation (one-question-then-prompts), approach
 exploration patterns, and YAGNI principles.
 
+It is critical that you follow this workflow in order; do not skip or shortcut steps.
+
 ## Guardrails
 
 - Do not write or modify application code.

package/src/.agents/commands/workflow/compound.md

@@ -27,6 +27,8 @@ Do not create drafts, notes, or intermediate files.
 After the primary solution doc is written, optional post-capture actions (by explicit user choice) may update other references (e.g. patterns indexes).
 </critical_requirement>
 
+It is critical that you follow this workflow in order; do not skip or shortcut steps.
+
 ## Usage
 
 ```bash
@@ -49,14 +51,16 @@ After the primary solution doc is written, optional post-capture actions (by exp
 - **Implementation insight:** For feature work, confirm implementation is complete and there is a reusable learning or pattern to capture (no "problem solved" requirement for this path).
 - If critical context is missing, ask targeted questions and wait. Then **invoke the `compound-docs` skill** (it defines required fields, validation gates, and template).
 
-### 2. Optional enrichment (before write)
+### 2. Required research (before write)
+
+Research is required and must run in subagents. Do not perform research in-context. Run all research via Task (subagent). If the environment cannot run the Task, state that and perform a minimal in-context fallback, then proceed to capture.
 
-Run only agents that exist in this `.agents` workspace. **Enrichment is read-only**—it informs the doc content but must not write files.
+Run only agents that exist in this `.agents` workspace. **Research is read-only**—it informs the doc content but must not write files.
 
-- Related docs: `Task learnings-researcher(<symptom/module/root cause keywords>)`
-- Optional: `Task best-practices-researcher(<topic>)`, `Task framework-docs-researcher(<topic>)`
+- **Required:** `Task learnings-researcher(<symptom/module/root cause keywords>)` (related docs).
+- **Conditional** (when the topic warrants, e.g. framework usage or cross-cutting patterns): `Task best-practices-researcher(<topic>)`, `Task framework-docs-researcher(<topic>)`. When run, these must also run as Tasks.
 
-Complete enrichment before assembly. Report which ran vs skipped.
+Complete research before assembly. Report which enrichments ran (required: learnings-researcher; conditional: best-practices, framework-docs) and which were skipped.
 
 ### 3. Capture
 
@@ -105,14 +109,14 @@ User may optionally run `document-review` on the created doc. If the repo has do
 
 ## Success output (shape)
 
-Report which optional enrichments ran vs skipped. Then output the path of the created file. Present the **`compound-docs` decision menu** (see skill) and wait for user choice—do not substitute a shorter custom menu.
+Report which enrichments ran (required: learnings-researcher; conditional: best-practices, framework-docs) and which were skipped. Then output the path of the created file. Present the **`compound-docs` decision menu** (see skill) and wait for user choice—do not substitute a shorter custom menu.
 
 Example summary (generic, portable):
 
 ```
 ✓ Documentation complete
 
-Optional enrichments: related-docs ran|skipped, best-practices ran|skipped, framework-docs ran|skipped
+Enrichments: learnings-researcher (required) ran|skipped; best-practices ran|skipped; framework-docs ran|skipped
 
 File created: docs/solutions/<category>/YYYY-MM-DD-<module-slug>-<symptom-slug>.md
 

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

@@ -15,6 +15,8 @@ Transform feature descriptions, bug reports, or improvement ideas into well-stru
 
 Contract precedence: if this command conflicts with other workflow docs, follow `docs/principles/workflow-baseline-principles.md`, then `src/AGENTS.md`, then this command.
 
+It is critical that you follow this workflow in order; do not skip or shortcut steps.
+
 This workflow MUST choose a planning fidelity and confidence level before final plan construction:
 
 - Fidelity: `Low | Medium | High`
@@ -833,7 +835,7 @@ Write the complete plan file to `docs/plans/YYYY-MM-DD-<type>-<slug>-plan.md`. T
 
 Confirm: "Plan written to docs/plans/[filename]"
 
-**Auto technical review (when Fidelity is Medium or High):** After writing the plan file, if the declared **Fidelity is Medium or High**, automatically run technical review: run **Task planning-technical-reviewer(plan_path)** when the environment can run the Task, or load the `technical-review` skill so the subagent is used when available. Use the plan path just written. If Fidelity is Low, skip this step; the user can still choose "Technical review" from Post-Generation Options or call `/workflow:tech-review` later.
+**Technical review (required when Fidelity is Medium or High):** After writing the plan file, if the declared **Fidelity is Medium or High**, you **must** run technical review—it is not optional. Run **Task planning-technical-reviewer(plan_path)** using the plan path just written. Do not perform technical review in-context unless the environment cannot run the Task; if you fall back, state "planning-technical-reviewer unavailable; running direct technical review (degraded bias resistance)" and then load the `technical-review` skill and run it in-context. If Fidelity is Low, skip this step; the user can still choose "Technical review" from Post-Generation Options or call `/workflow:tech-review` later.
 
 **Non-interactive mode:** When the invocation is non-interactive (e.g., `workflow:plan` run by automation, CI, or with an explicit non-interactive flag/convention), skip AskQuestion calls and do not present Post-Generation Options. For determinism, the repo should define the flag or convention (e.g., in `AGENTS.md` Repo Config Block or a documented env var). Still **declare** Fidelity, Confidence, Solution scope, Spike evaluation, Spikes needed, Research mode, and Open questions in the required announcement format before writing the plan. Use these defaults when user input is unavailable: fidelity = Medium, confidence = Medium, solution_scope = full_remediation, spike evaluation = not-required unless risky-work triggers are present, spikes needed = n/a when spike evaluation is not required, research mode = local + external for Medium/High risk topics else local only. Proceed directly to writing the plan file and then exit or return the plan path as output.
 
@@ -863,6 +865,8 @@ Examples:
 
 ## Post-Generation Options
 
+Technical review (above) is required for Medium/High fidelity and must be run via subagent when available.
+
 After writing the plan file, use **AskQuestion** to present these options:
 
 **Question:** "Plan ready at `docs/plans/YYYY-MM-DD-<type>-<slug>-plan.md`. What would you like to do next?"

package/src/.agents/commands/workflow/review.md

@@ -13,6 +13,8 @@ Contract precedence: if this command conflicts with other workflow docs, follow
 
 **If the user provides a document path** (e.g. a plan or spec): redirect to the `technical-review` skill for technical correctness (no edits), and/or the `document-review` skill to refine the document. This command does not review documents.
 
+It is critical that you follow this workflow in order; do not skip or shortcut steps.
+
 Guardrails (unless explicitly requested):
 
 - Do not modify code or documents

package/src/.agents/commands/workflow/tech-review.md

@@ -11,6 +11,8 @@ Run technical review on a feature approach or plan document. Checks technical al
 
 Contract precedence: if this command conflicts with other workflow docs, follow `docs/principles/workflow-baseline-principles.md`, then `src/AGENTS.md`, then this command.
 
+It is critical that you follow this workflow in order; do not skip or shortcut steps.
+
 ## Inputs
 
 - **Plan path (optional):** `$ARGUMENTS` — path to the plan file (e.g. `docs/plans/YYYY-MM-DD-<type>-<slug>-plan.md`).

package/src/.agents/commands/workflow/triage.md

@@ -16,6 +16,8 @@ Output of this command is the only executable queue for `/workflow:work`.
 
 Contract precedence: if this command conflicts with other workflow docs, follow `docs/principles/workflow-baseline-principles.md`, then `src/AGENTS.md`, then this command.
 
+It is critical that you follow this workflow in order; do not skip or shortcut steps.
+
 ## Inputs
 
 - Default: triage all active todos under `todos/` (`pending` + `ready`)

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

@@ -15,6 +15,8 @@ This command takes a plan file and executes it systematically. The focus is on c
 
 Contract precedence: if this command conflicts with other workflow docs, follow `docs/principles/workflow-baseline-principles.md`, then `src/AGENTS.md`, then this command.
 
+It is critical that you follow this workflow in order; do not skip or shortcut steps.
+
 Non-goals (unless explicitly requested):
 
 - Creating commits

package/src/.agents/registry.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://compound-workflow.dev/registry.schema.json",
+  "roots": {
+    "package": {
+      "commands": "src/.agents/commands",
+      "agents": "src/.agents/agents",
+      "skills": "src/.agents/skills",
+      "references": "src/.agents/references"
+    },
+    "consumer": {
+      "commands": "node_modules/compound-workflow/src/.agents/commands",
+      "agents": "node_modules/compound-workflow/src/.agents/agents",
+      "skills": "node_modules/compound-workflow/src/.agents/skills",
+      "references": "node_modules/compound-workflow/src/.agents/references"
+    }
+  },
+  "assetTypes": {
+    "command": {
+      "dir": "commands",
+      "glob": "**/*.md",
+      "idFrom": ["invocation", "name"],
+      "idFallback": "basename",
+      "descriptionFrom": "description",
+      "descriptionFallback": "id",
+      "output": ["opencode.command", "plugin.commands"]
+    },
+    "agent": {
+      "dir": "agents",
+      "glob": "**/*.md",
+      "idFrom": ["name"],
+      "idFallback": "basename",
+      "descriptionFrom": "description",
+      "descriptionFallback": "id",
+      "output": ["opencode.agent", "plugin.agents"]
+    },
+    "skill": {
+      "dir": "skills",
+      "glob": "*/SKILL.md",
+      "idFrom": ["dirname"],
+      "output": ["opencode.skillsPath", "plugin.skills"]
+    },
+    "reference": {
+      "dir": "references",
+      "glob": "**/*.md",
+      "output": ["path"]
+    }
+  }
+}