@curdx/flow 2.3.0 → 2.3.2

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Claude Code Discipline Layer — spec-driven workflow + goal-backward verification + Karpathy 4 principles enforced via gates. Stops Claude from faking \"done\" on non-trivial features.",
-    "version": "2.3.0"
+    "version": "2.3.2"
   },
   "allowCrossMarketplaceDependenciesOn": [
     "context7-marketplace"
@@ -16,7 +16,7 @@
       "name": "curdx-flow",
       "source": "./",
       "description": "Claude Code Discipline Layer — spec-driven workflow + goal-backward verification + Karpathy 4 principles enforced via gates. Stops Claude from faking \"done\" on non-trivial features.",
-      "version": "2.3.0",
+      "version": "2.3.2",
       "author": {
         "name": "wdx",
         "email": "bydongxin@gmail.com"

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "curdx-flow",
-  "version": "2.3.0",
+  "version": "2.3.2",
   "description": "Claude Code Discipline Layer — spec-driven workflow + goal-backward verification + Karpathy 4 principles enforced via gates. Stops Claude from faking \"done\" on non-trivial features.",
   "author": {
     "name": "wdx",

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 2.3.1
+
+- expanded `doctor` to report CurDX-Flow’s bundled main-thread agent, monitor surface, and plugin option defaults
+- documented where Claude Code stores CurDX-Flow non-sensitive `userConfig` values in `pluginConfigs`
+- added troubleshooting guidance for stop-hook blocking and plugin monitor behavior
+
 ## 2.3.0
 
 - added a default `flow-orchestrator` main-thread agent through plugin-level `settings.json`

package/README.md

@@ -22,6 +22,10 @@ Requires modern Claude Code and Node 18+. The install flow registers the plugin,
 required reasoning/doc tools, and recommended companion plugins. Run
 `npx @curdx/flow doctor` after install if anything looks off.
 
+After restart, CurDX-Flow routes the main thread through `flow-orchestrator`
+by default and starts the bundled `.flow` progress monitor in interactive
+Claude Code sessions.
+
 ## 11 slash commands, that's it
 
 ```text

package/cli/doctor-workflow.js

@@ -1,5 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 
 import { readProjectClaudeSettings } from "./lib/doctor-claude-settings.js";
 import { inspectRuntimeEnvironment } from "./lib/doctor-runtime-environment.js";
@@ -19,6 +20,8 @@ import {
 export { readProjectClaudeSettings };
 export { inspectRuntimeEnvironment };
 
+const PACKAGE_ROOT = fileURLToPath(new URL("../", import.meta.url));
+
 export function createDoctorContext(args = []) {
   return {
     fix: args.includes("--fix"),
@@ -150,6 +153,78 @@ export async function readProjectTeamConfig(cwd = process.cwd()) {
   return state;
 }
 
+export async function readBundledPluginRuntimeDefaults(packageRoot = PACKAGE_ROOT) {
+  const pluginSettingsPath = path.join(packageRoot, "settings.json");
+  const pluginManifestPath = path.join(packageRoot, ".claude-plugin", "plugin.json");
+  const monitorsPath = path.join(packageRoot, "monitors", "monitors.json");
+
+  const state = {
+    exists: false,
+    defaultAgent: null,
+    subagentStatusLineCommand: null,
+    monitorCount: 0,
+    monitors: [],
+    userConfig: [],
+  };
+
+  let pluginSettings = null;
+  let pluginManifest = null;
+  let monitors = null;
+
+  try {
+    pluginSettings = JSON.parse(await fs.readFile(pluginSettingsPath, "utf-8"));
+  } catch {
+    pluginSettings = null;
+  }
+
+  try {
+    pluginManifest = JSON.parse(await fs.readFile(pluginManifestPath, "utf-8"));
+  } catch {
+    pluginManifest = null;
+  }
+
+  try {
+    monitors = JSON.parse(await fs.readFile(monitorsPath, "utf-8"));
+  } catch {
+    monitors = null;
+  }
+
+  if (!pluginSettings && !pluginManifest && !monitors) {
+    return state;
+  }
+
+  state.exists = true;
+  state.defaultAgent = typeof pluginSettings?.agent === "string" ? pluginSettings.agent : null;
+  state.subagentStatusLineCommand =
+    typeof pluginSettings?.subagentStatusLine?.command === "string"
+      ? pluginSettings.subagentStatusLine.command
+      : null;
+
+  if (Array.isArray(monitors)) {
+    state.monitorCount = monitors.length;
+    state.monitors = monitors
+      .filter((entry) => entry && typeof entry === "object")
+      .map((entry) => ({
+        name: typeof entry.name === "string" ? entry.name : null,
+        when: typeof entry.when === "string" ? entry.when : "always",
+      }))
+      .filter((entry) => entry.name);
+  }
+
+  if (pluginManifest?.userConfig && typeof pluginManifest.userConfig === "object") {
+    state.userConfig = Object.entries(pluginManifest.userConfig)
+      .filter(([, value]) => value && typeof value === "object" && !Array.isArray(value))
+      .map(([key, value]) => ({
+        key,
+        type: value.type ?? null,
+        default: Object.prototype.hasOwnProperty.call(value, "default") ? value.default : undefined,
+        sensitive: value.sensitive === true,
+      }));
+  }
+
+  return state;
+}
+
 export async function readProjectState(cwd = process.cwd()) {
   const flowDir = path.join(cwd, ".flow");
   try {
@@ -185,6 +260,7 @@ export async function collectDoctorData(
     readProjectMcpConfigImpl = readProjectMcpConfig,
     readProjectTeamConfigImpl = readProjectTeamConfig,
     readProjectClaudeSettingsImpl = readProjectClaudeSettings,
+    readBundledPluginRuntimeDefaultsImpl = readBundledPluginRuntimeDefaults,
   } = {}
 ) {
   const claudeVersionValue = claudeVersionImpl();
@@ -212,6 +288,7 @@ export async function collectDoctorData(
     projectMcpConfig: await readProjectMcpConfigImpl(cwd),
     projectTeamConfig: await readProjectTeamConfigImpl(cwd),
     projectClaudeSettings: await readProjectClaudeSettingsImpl(cwd),
+    bundledPluginRuntimeDefaults: await readBundledPluginRuntimeDefaultsImpl(),
   };
 }
 

package/cli/install-next-steps.js

@@ -11,6 +11,8 @@ export function printNextSteps() {
   console.log(`${color.bold("Next steps")}:\n`);
   console.log(`  ${color.dim("# Verify health")}`);
   console.log(`  ${cliCmd} doctor\n`);
+  console.log(`  ${color.dim("# Review the bundled main-agent / monitor defaults")}`);
+  console.log(`  ${color.dim("# (doctor now prints CurDX-Flow runtime defaults and plugin option keys)")}\n`);
   console.log(`  ${color.dim("# Inside any project, initialize and start a feature spec")}`);
   console.log(`  ${color.cyan("cd ~/your-project")}`);
   console.log(`  ${color.cyan("claude")}`);

package/cli/lib/doctor-claude-settings.js

@@ -99,6 +99,23 @@ const CURDX_FLOW_REQUIRED_TOOLS = [
   "Glob",
 ];
 const CURDX_FLOW_PLUGIN_ID = "curdx-flow@curdx-flow-marketplace";
+const CURDX_FLOW_PLUGIN_OPTIONS = {
+  autonomous_blocking: {
+    type: "boolean",
+    default: true,
+  },
+  daily_dependency_check: {
+    type: "boolean",
+    default: true,
+  },
+  monitor_interval_seconds: {
+    type: "number",
+    default: 8,
+    integer: true,
+    min: 3,
+    max: 60,
+  },
+};
 const CURDX_FLOW_REQUIRED_PLUGIN_IDS = ["context7-plugin@context7-marketplace"];
 const HTTP_HOOK_SETTINGS = ["allowedHttpHookUrls", "httpHookAllowedEnvVars"];
 const PERSISTED_EFFORT_LEVELS = ["low", "medium", "high", "xhigh"];
@@ -171,6 +188,171 @@ function pushScopedWarning(target, kind, message, scope = "project") {
   target.push(warning);
 }
 
+function createCurdxFlowPluginOptionsState() {
+  const definitions = Object.entries(CURDX_FLOW_PLUGIN_OPTIONS).map(([key, value]) => ({
+    key,
+    type: value.type,
+    default: value.default,
+    min: value.min,
+    max: value.max,
+    integer: value.integer === true,
+  }));
+
+  const repoEffective = Object.fromEntries(
+    definitions.map((definition) => [
+      definition.key,
+      { value: definition.default, source: "default" },
+    ])
+  );
+
+  return {
+    pluginId: CURDX_FLOW_PLUGIN_ID,
+    definitions,
+    project: {
+      pluginConfigsPresent: false,
+      pluginConfigPresent: false,
+      optionsPresent: false,
+      overrides: {},
+    },
+    local: {
+      pluginConfigsPresent: false,
+      pluginConfigPresent: false,
+      optionsPresent: false,
+      overrides: {},
+    },
+    repoEffective,
+  };
+}
+
+function pluginScopeLabel(scope) {
+  return scope === "local" ? "settings.local.json" : "settings.json";
+}
+
+function auditCurdxFlowPluginOptions(parsed, warnings, pluginOptionsState, scope = "project") {
+  if (!isNonArrayObject(parsed) || !("pluginConfigs" in parsed)) {
+    return;
+  }
+
+  const target = scope === "local" ? pluginOptionsState.local : pluginOptionsState.project;
+  const settingsLabel = pluginScopeLabel(scope);
+  target.pluginConfigsPresent = true;
+
+  if (!isNonArrayObject(parsed.pluginConfigs)) {
+    pushScopedWarning(
+      warnings,
+      scope === "local" ? "invalid-local-setting" : "invalid-project-setting",
+      `pluginConfigs in ${settingsLabel} must be an object keyed by plugin@marketplace id`,
+      scope
+    );
+    return;
+  }
+
+  const pluginConfig = parsed.pluginConfigs[CURDX_FLOW_PLUGIN_ID];
+  if (pluginConfig === undefined) {
+    return;
+  }
+
+  target.pluginConfigPresent = true;
+
+  if (!isNonArrayObject(pluginConfig)) {
+    pushScopedWarning(
+      warnings,
+      scope === "local" ? "invalid-local-setting" : "invalid-project-setting",
+      `pluginConfigs[${CURDX_FLOW_PLUGIN_ID}] in ${settingsLabel} must be an object when set`,
+      scope
+    );
+    return;
+  }
+
+  if (!("options" in pluginConfig)) {
+    return;
+  }
+
+  target.optionsPresent = true;
+
+  if (!isNonArrayObject(pluginConfig.options)) {
+    pushScopedWarning(
+      warnings,
+      scope === "local" ? "invalid-local-setting" : "invalid-project-setting",
+      `pluginConfigs[${CURDX_FLOW_PLUGIN_ID}].options in ${settingsLabel} must be an object when set`,
+      scope
+    );
+    return;
+  }
+
+  for (const [key, value] of Object.entries(pluginConfig.options)) {
+    const definition = CURDX_FLOW_PLUGIN_OPTIONS[key];
+
+    if (!definition) {
+      pushScopedWarning(
+        warnings,
+        "unknown-plugin-option",
+        `unknown CurDX-Flow plugin option in ${settingsLabel}: ${key}`,
+        scope
+      );
+      continue;
+    }
+
+    if (definition.type === "boolean" && typeof value !== "boolean") {
+      pushScopedWarning(
+        warnings,
+        scope === "local" ? "invalid-local-setting" : "invalid-project-setting",
+        `CurDX-Flow plugin option ${key} in ${settingsLabel} must be boolean`,
+        scope
+      );
+      continue;
+    }
+
+    if (definition.type === "number") {
+      if (typeof value !== "number" || Number.isNaN(value)) {
+        pushScopedWarning(
+          warnings,
+          scope === "local" ? "invalid-local-setting" : "invalid-project-setting",
+          `CurDX-Flow plugin option ${key} in ${settingsLabel} must be a number`,
+          scope
+        );
+        continue;
+      }
+
+      if (definition.integer && !Number.isInteger(value)) {
+        pushScopedWarning(
+          warnings,
+          scope === "local" ? "invalid-local-setting" : "invalid-project-setting",
+          `CurDX-Flow plugin option ${key} in ${settingsLabel} must be an integer`,
+          scope
+        );
+        continue;
+      }
+
+      if (typeof definition.min === "number" && value < definition.min) {
+        pushScopedWarning(
+          warnings,
+          scope === "local" ? "invalid-local-setting" : "invalid-project-setting",
+          `CurDX-Flow plugin option ${key} in ${settingsLabel} must be between ${definition.min} and ${definition.max}`,
+          scope
+        );
+        continue;
+      }
+
+      if (typeof definition.max === "number" && value > definition.max) {
+        pushScopedWarning(
+          warnings,
+          scope === "local" ? "invalid-local-setting" : "invalid-project-setting",
+          `CurDX-Flow plugin option ${key} in ${settingsLabel} must be between ${definition.min} and ${definition.max}`,
+          scope
+        );
+        continue;
+      }
+    }
+
+    target.overrides[key] = value;
+    pluginOptionsState.repoEffective[key] = {
+      value,
+      source: scope,
+    };
+  }
+}
+
 function auditLocalClaudeSettings(parsed, warnings) {
   const scope = "local";
   const permissions = parsed?.permissions && typeof parsed.permissions === "object"
@@ -374,6 +556,7 @@ export async function readProjectClaudeSettings(cwd = process.cwd()) {
     localInvalid: false,
     localParseError: null,
     localWarnings: [],
+    pluginOptions: createCurdxFlowPluginOptionsState(),
   };
 
   try {
@@ -407,6 +590,8 @@ export async function readProjectClaudeSettings(cwd = process.cwd()) {
     const allow = Array.isArray(permissions.allow) ? permissions.allow : [];
     const deny = Array.isArray(permissions.deny) ? permissions.deny : [];
 
+    auditCurdxFlowPluginOptions(parsed, state.warnings, state.pluginOptions, "project");
+
     if ("enabledPlugins" in parsed && (
       !parsed.enabledPlugins ||
       typeof parsed.enabledPlugins !== "object" ||
@@ -726,6 +911,7 @@ export async function readProjectClaudeSettings(cwd = process.cwd()) {
   if (state.localExists) {
     try {
       const localParsed = JSON.parse(await fs.readFile(localSettingsPath, "utf-8"));
+      auditCurdxFlowPluginOptions(localParsed, state.localWarnings, state.pluginOptions, "local");
       auditLocalClaudeSettings(localParsed, state.localWarnings);
     } catch (error) {
       state.localInvalid = true;

package/cli/lib/doctor-report.js

@@ -14,6 +14,26 @@ function pluginErrorDetails(plugin) {
 
 function projectSettingsWarningDetails(warning) {
   if (warning?.scope === "local") {
+    if (warning.kind === "unknown-plugin-option") {
+      return [
+        "settings.local.json overrides shared project settings on this machine",
+        "remove the unknown key or rename it to a supported CurDX-Flow plugin option under pluginConfigs[curdx-flow@curdx-flow-marketplace].options",
+      ];
+    }
+
+    if (
+      warning.kind === "invalid-local-setting" &&
+      (
+        warning.message?.includes("pluginConfigs[curdx-flow@curdx-flow-marketplace]") ||
+        warning.message?.includes("CurDX-Flow plugin option")
+      )
+    ) {
+      return [
+        "CurDX-Flow plugin options in settings.local.json override project and user settings on this machine",
+        "use boolean values for autonomous_blocking and daily_dependency_check, and keep monitor_interval_seconds as an integer between 3 and 60",
+      ];
+    }
+
     if (warning.kind === "invalid-local-setting") {
       return [
         "settings.local.json is the highest-precedence repo-scoped settings surface on this machine",
@@ -41,6 +61,26 @@ function projectSettingsWarningDetails(warning) {
     ];
   }
 
+  if (warning.kind === "unknown-plugin-option") {
+    return [
+      "CurDX-Flow only reads keys declared in the plugin manifest",
+      "remove the unknown key or rename it under pluginConfigs[curdx-flow@curdx-flow-marketplace].options",
+    ];
+  }
+
+  if (
+    warning.kind === "invalid-project-setting" &&
+    (
+      warning.message?.includes("pluginConfigs[curdx-flow@curdx-flow-marketplace]") ||
+      warning.message?.includes("CurDX-Flow plugin option")
+    )
+  ) {
+    return [
+      "CurDX-Flow non-sensitive plugin options belong under pluginConfigs[curdx-flow@curdx-flow-marketplace].options in .claude/settings.json",
+      "use boolean values for autonomous_blocking and daily_dependency_check, and keep monitor_interval_seconds as an integer between 3 and 60",
+    ];
+  }
+
   if (!warning?.kind) {
     return [
       "project settings are shared with collaborators",
@@ -116,6 +156,11 @@ function projectSettingsWarningDetails(warning) {
   ];
 }
 
+function formatInlineValue(value) {
+  if (typeof value === "string") return `"${value}"`;
+  return String(value);
+}
+
 export function buildDoctorReport({
   claudeVersionValue,
   nodeVersion,
@@ -130,6 +175,7 @@ export function buildDoctorReport({
   projectMcpConfig,
   projectTeamConfig,
   projectClaudeSettings,
+  bundledPluginRuntimeDefaults,
 }) {
   const lines = [];
   const sections = [];
@@ -345,6 +391,154 @@ export function buildDoctorReport({
     }
   }
 
+  if (bundledPluginRuntimeDefaults?.exists) {
+    const bundledRuntimeSection = createSection("CurDX-Flow bundled runtime:");
+
+    if (bundledPluginRuntimeDefaults.defaultAgent) {
+      pushSectionLine(
+        bundledRuntimeSection,
+        "ok",
+        `Main thread agent     ${bundledPluginRuntimeDefaults.defaultAgent}`,
+        [
+          "plugin-level settings route the main Claude thread through this agent by default",
+        ]
+      );
+    }
+
+    if (bundledPluginRuntimeDefaults.subagentStatusLineCommand) {
+      pushSectionLine(
+        bundledRuntimeSection,
+        "info",
+        `Subagent status line  configured`,
+        [bundledPluginRuntimeDefaults.subagentStatusLineCommand]
+      );
+    }
+
+    if (bundledPluginRuntimeDefaults.monitorCount > 0) {
+      const monitorSummary = bundledPluginRuntimeDefaults.monitors
+        .map((monitor) => `${monitor.name} (${monitor.when})`)
+        .join(", ");
+      pushSectionLine(
+        bundledRuntimeSection,
+        "ok",
+        `Plugin monitors       ${bundledPluginRuntimeDefaults.monitorCount} configured`,
+        [
+          monitorSummary,
+          "official docs: plugin monitors run only in interactive Claude Code sessions where the Monitor tool is available",
+        ]
+      );
+    }
+
+    if ((bundledPluginRuntimeDefaults.userConfig || []).length > 0) {
+      const optionSummary = bundledPluginRuntimeDefaults.userConfig
+        .map((option) => {
+          const suffix = option.default === undefined ? "" : `=${String(option.default)}`;
+          return `${option.key}${suffix}`;
+        })
+        .join(", ");
+      pushSectionLine(
+        bundledRuntimeSection,
+        "info",
+        `Plugin options        ${bundledPluginRuntimeDefaults.userConfig.length} available`,
+        [
+          optionSummary,
+          "non-sensitive values are stored under pluginConfigs[curdx-flow@curdx-flow-marketplace].options in Claude settings.json",
+        ]
+      );
+    }
+  }
+
+  if (
+    bundledPluginRuntimeDefaults?.exists ||
+    projectClaudeSettings?.pluginOptions
+  ) {
+    const configuredOptionsSection = createSection("CurDX-Flow configured options:");
+    const optionState = projectClaudeSettings?.pluginOptions;
+    const projectOverrides = optionState?.project?.overrides || {};
+    const localOverrides = optionState?.local?.overrides || {};
+    const repoEffective = optionState?.repoEffective || {};
+    const definitions = bundledPluginRuntimeDefaults?.userConfig?.length
+      ? bundledPluginRuntimeDefaults.userConfig
+      : (optionState?.definitions || []);
+
+    pushSectionLine(
+      configuredOptionsSection,
+      "info",
+      "Scope precedence      settings.local.json > settings.json > bundled default",
+      [
+        "this section audits repo-scoped CurDX-Flow plugin options only",
+        "user-level ~/.claude/settings.json is not inspected here",
+      ]
+    );
+
+    if (Object.keys(projectOverrides).length > 0) {
+      const summary = Object.entries(projectOverrides)
+        .map(([key, value]) => `${key}=${formatInlineValue(value)}`)
+        .join(", ");
+      pushSectionLine(
+        configuredOptionsSection,
+        "info",
+        `.claude/settings.json ${Object.keys(projectOverrides).length} valid override(s)`,
+        [
+          summary,
+          "path: pluginConfigs[curdx-flow@curdx-flow-marketplace].options",
+        ]
+      );
+    } else {
+      pushSectionLine(
+        configuredOptionsSection,
+        "info",
+        ".claude/settings.json no CurDX-Flow repo override"
+      );
+    }
+
+    if (projectClaudeSettings?.localExists) {
+      if (Object.keys(localOverrides).length > 0) {
+        const summary = Object.entries(localOverrides)
+          .map(([key, value]) => `${key}=${formatInlineValue(value)}`)
+          .join(", ");
+        pushSectionLine(
+          configuredOptionsSection,
+          "info",
+          `.claude/settings.local.json ${Object.keys(localOverrides).length} valid override(s)`,
+          [
+            summary,
+            "local overrides have higher precedence than .claude/settings.json on this machine",
+          ]
+        );
+      } else {
+        pushSectionLine(
+          configuredOptionsSection,
+          "info",
+          ".claude/settings.local.json present without valid CurDX-Flow overrides"
+        );
+      }
+    } else {
+      pushSectionLine(
+        configuredOptionsSection,
+        "info",
+        ".claude/settings.local.json not present"
+      );
+    }
+
+    for (const definition of definitions) {
+      const effective = repoEffective[definition.key] || {
+        value: definition.default,
+        source: "default",
+      };
+      const sourceLabel = effective.source === "local"
+        ? "local"
+        : effective.source === "project"
+          ? "project"
+          : "bundled default";
+      pushSectionLine(
+        configuredOptionsSection,
+        "ok",
+        `${definition.key.padEnd(22)} ${formatInlineValue(effective.value)} (${sourceLabel})`
+      );
+    }
+  }
+
   const localProjectSection = createSection("Local project:");
   if (projectState?.exists) {
     pushSectionLine(localProjectSection, "ok", `.flow/                ${cwd}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@curdx/flow",
-  "version": "2.3.0",
+  "version": "2.3.2",
   "description": "Skill-first discipline layer and CLI installer for Claude Code",
   "type": "module",
   "bin": {