@curdx/flow 2.2.3 → 2.2.5

package/cli/uninstall.js

@@ -2,48 +2,22 @@
  * uninstall command — remove curdx-flow plugin (and optionally recommended plugins / artifacts).
  */
 
-import { existsSync, lstatSync, unlinkSync, rmSync, readlinkSync } from "node:fs";
-import { join } from "node:path";
-import { homedir } from "node:os";
-
-import {
-  color,
-  log,
-  resultLastLine,
-  resultOutput,
-  confirm,
-  listPlugins,
-} from "./utils.js";
-import { REQUIRED_PLUGINS, RECOMMENDED_PLUGINS, BUNDLED_MCPS } from "./registry.js";
-import {
-  removeMcp,
-  removePluginMarketplace,
-  uninstallPlugin,
-} from "./lib/claude-ops.js";
+import { log } from "./utils.js";
 import {
   createUninstallContext,
   ensureClaudeCliAvailableForUninstall,
-  getInstalledTargets,
-  getManagedMarketplaceIds,
   printUninstallSummary,
   removeProtocolsStep,
-  selectRecommendedPluginsToRemove,
-  shouldKeepBundledMcps,
-  shouldKeepRequiredPlugins,
-  UNINSTALL_STEP_COUNT,
   confirmUninstallStep,
 } from "./uninstall-workflow.js";
-
-const HOME = homedir();
-
-const RECOMMENDED = RECOMMENDED_PLUGINS.map(toUninstallTarget);
-const REQUIRED = REQUIRED_PLUGINS.map(toUninstallTarget);
-
-// Symlinks created by install.js (only cleaned with --purge)
-const MANAGED_SYMLINKS = [
-  join(HOME, ".local", "bin", "bun"),
-  join(HOME, ".local", "bin", "uv"),
-];
+import {
+  maybePurgeRuntimeArtifacts,
+  maybeRemoveBundledMcps,
+  maybeRemoveProjectState,
+  maybeUninstallRecommendedPlugins,
+  maybeUninstallRequiredPlugins,
+  uninstallCurdxFlowPlugin,
+} from "./uninstall-actions.js";
 
 export async function uninstall(args = []) {
   const context = createUninstallContext(args);
@@ -66,221 +40,3 @@ export async function uninstall(args = []) {
 
   printUninstallSummary(context);
 }
-
-async function uninstallCurdxFlowPlugin() {
-  log.blank();
-  log.step(1, UNINSTALL_STEP_COUNT, "Uninstalling curdx-flow plugin...");
-  const curdx = listPlugins().find((plugin) => plugin.name === "curdx-flow");
-  if (!curdx) {
-    log.info("curdx-flow not installed, skipping");
-    return;
-  }
-
-  const result = await uninstallPlugin({
-    scope: "user",
-    uninstallSpec: "curdx-flow@curdx-flow-marketplace",
-  });
-  if (result.code === 0) {
-    log.ok("curdx-flow uninstalled");
-    return;
-  }
-
-  log.err(`Uninstall failed: ${resultOutput(result)}`);
-}
-
-async function maybeUninstallRecommendedPlugins({ yes, keepRecommended }) {
-  log.blank();
-  log.step(2, UNINSTALL_STEP_COUNT, "Recommended plugins");
-  if (keepRecommended) {
-    log.info("Keeping recommended plugins (--keep-recommended)");
-    return;
-  }
-
-  const present = getInstalledTargets(RECOMMENDED);
-  if (present.length === 0) {
-    log.info("No installed recommended plugins");
-    return;
-  }
-
-  const selected = await selectRecommendedPluginsToRemove({ yes, present });
-  for (const name of selected) {
-    const entry = present.find((plugin) => plugin.name === name);
-    if (!entry) continue;
-    await uninstallNamedPlugin(entry);
-  }
-}
-
-async function uninstallNamedPlugin(entry) {
-  log.blank();
-  console.log(`  ${color.cyan("▸")} Uninstalling ${color.bold(entry.name)}...`);
-  const result = await uninstallPlugin(entry);
-  if (result.code === 0) {
-    console.log(`  ${color.green("✓")} ${entry.name} uninstalled`);
-    return;
-  }
-
-  console.log(
-    `  ${color.red("✗")} ${entry.name} uninstall failed: ${resultLastLine(result)}`
-  );
-}
-
-async function maybeRemoveBundledMcps({ yes, keepRecommended }) {
-  log.blank();
-  log.info("Required MCP servers (context7, sequential-thinking)");
-  if (shouldKeepBundledMcps({ yes, keepRecommended })) {
-    log.info(
-      color.dim("--yes or --keep-recommended: keeping user-level MCPs (remove manually with `claude mcp remove <name>`)")
-    );
-    return;
-  }
-
-  const removeMcps = await confirm(
-    `Remove user-level MCPs registered by install (${BUNDLED_MCPS.map((mcp) => mcp.name).join(", ")})? ${color.dim("(keeps them if other tools depend on them)")}`,
-    false
-  );
-  if (!removeMcps) {
-    log.info("Keeping user-level MCPs");
-    return;
-  }
-
-  for (const mcp of BUNDLED_MCPS) {
-    const result = await removeMcp({ name: mcp.name });
-    if (result.code === 0) {
-      log.ok(`  ${mcp.name.padEnd(22)} removed`);
-    } else {
-      log.info(`  ${mcp.name.padEnd(22)} ${color.dim("not present or already removed")}`);
-    }
-  }
-}
-
-async function maybeUninstallRequiredPlugins({ yes }) {
-  log.blank();
-  log.info("Required companion plugins");
-  if (shouldKeepRequiredPlugins({ yes })) {
-    log.info(
-      color.dim("--yes mode: keeping required companion plugins (use --purge to remove them)")
-    );
-    return;
-  }
-
-  const removeRequired = await confirm(
-    `Remove required companion plugins (${REQUIRED.map((plugin) => plugin.name).join(", ")})? ${color.dim("(keeps shared tools available if other workflows depend on them)")}`,
-    false
-  );
-  if (!removeRequired) {
-    log.info("Keeping required companion plugins");
-    return;
-  }
-
-  for (const plugin of REQUIRED) {
-    const result = await uninstallPlugin(plugin);
-    if (result.code === 0) {
-      log.ok(`  ${plugin.name.padEnd(22)} uninstalled`);
-    } else {
-      log.info(`  ${plugin.name.padEnd(22)} ${color.dim("not present or already removed")}`);
-    }
-  }
-}
-
-async function maybePurgeRuntimeArtifacts({ purge }) {
-  log.blank();
-  log.step(3, UNINSTALL_STEP_COUNT, "Runtime symlinks and marketplaces");
-  if (!purge) {
-    log.info(
-      color.dim("Keeping ~/.local/bin/bun, ~/.local/bin/uv (use --purge to remove)")
-    );
-    log.info(
-      color.dim("Reason: these bun/uv binaries may be used by other tools — confirm before deleting")
-    );
-    return;
-  }
-
-  await purgeManagedMarketplaces();
-  removeManagedSymlinks();
-}
-
-async function purgeManagedMarketplaces() {
-  const marketplaceIds = getManagedMarketplaceIds(RECOMMENDED.concat(REQUIRED));
-
-  for (const marketplaceId of marketplaceIds) {
-    const result = await removePluginMarketplace(marketplaceId);
-    if (result.code === 0) {
-      log.ok(`Removed marketplace ${marketplaceId}`);
-    } else if (!result.stderr.includes("not found")) {
-      log.warn(`Failed to remove marketplace ${marketplaceId}: ${resultLastLine(result)}`);
-    }
-  }
-}
-
-function removeManagedSymlinks() {
-  for (const link of MANAGED_SYMLINKS) {
-    if (!existsSync(link) && !isBrokenSymlink(link)) {
-      continue;
-    }
-    try {
-      const stat = lstatSync(link);
-      if (!stat.isSymbolicLink()) {
-        log.warn(
-          `${link} is not a symlink (likely a real file placed by the user), skipping`
-        );
-        continue;
-      }
-      const target = readlinkSync(link);
-      unlinkSync(link);
-      log.ok(`Removed symlink ${link} ${color.dim(`(was → ${target})`)}`);
-    } catch (err) {
-      log.warn(`Failed to remove ${link}: ${err.message}`);
-    }
-  }
-}
-
-async function maybeRemoveProjectState({ yes }) {
-  log.blank();
-  log.step(4, UNINSTALL_STEP_COUNT, "Project state directory");
-  const flowDir = join(process.cwd(), ".flow");
-  if (!existsSync(flowDir)) {
-    log.info(".flow/ does not exist, skipping");
-    return;
-  }
-
-  if (yes) {
-    log.info(
-      color.dim("--yes mode: keeping .flow/ (contains specs & decisions — confirm by hand before deleting)")
-    );
-    return;
-  }
-
-  const ok = await confirm(
-    `${color.red("DANGER:")} delete the ${color.bold(".flow/")} directory of the current project? ${color.dim("(includes all specs / decisions, not recoverable)")}`,
-    false
-  );
-  if (!ok) {
-    log.info("Keeping .flow/");
-    return;
-  }
-
-  try {
-    rmSync(flowDir, { recursive: true, force: true });
-    log.ok(`Removed ${flowDir}`);
-  } catch (err) {
-    log.err(`Removal failed: ${err.message}`);
-  }
-}
-
-function toUninstallTarget(entry) {
-  return {
-    name: entry.name,
-    uninstallSpec: entry.uninstallSpec,
-    uninstallArgs: entry.uninstallArgs || [],
-    marketplaceId: entry.marketplaceId,
-    scope: entry.scope,
-  };
-}
-
-function isBrokenSymlink(pathname) {
-  try {
-    return lstatSync(pathname).isSymbolicLink();
-  } catch {
-    return false;
-  }
-}

package/gates/coverage-audit-gate.md

@@ -7,8 +7,6 @@ depends_on: []
 
 # Coverage Audit Gate — Multi-Source Coverage Audit
 
-> Derived from get-shit-done's "Multi-Source Coverage Audit".
->
 > Rule: every claim in the spec must be covered by implementation/tests. Uncovered = missed = future bug.
 
 ---
@@ -181,4 +179,4 @@ Fix recommendations:
 
 ---
 
-_Source: get-shit-done's multi-source coverage audit._
+_Source: CurDX-Flow multi-source coverage audit contract._

package/gates/tdd-gate.md

@@ -8,8 +8,6 @@ depends_on: []
 # TDD Gate — Red/Green/Yellow Cycle Enforcement
 
 > **Iron rule**: NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST.
->
-> Source: superpowers' test-driven-development skill.
 
 ---
 
@@ -182,7 +180,3 @@ Compliant: 4
 Fix recommendations:
   T2: add test test(auth): red - password hashing, verify it fails, then redo GREEN
 ```
-
----
-
-_Source: superpowers' test-driven-development skill._

package/gates/verification-gate.md

@@ -7,7 +7,7 @@ depends_on: []
 
 # Verification Gate — Verification Required Before Completion
 
-> **Always enabled**. No evidence = no completion. This is the Superpowers "Verification Before Completion" iron rule.
+> **Always enabled**. No evidence = no completion. Verification must be based on observed proof, not claimed completion.
 
 ---
 
@@ -177,7 +177,3 @@ Warnings: 1
 Fix recommendations:
   V1: dispatch flow-executor to run tests, add evidence to the commit message body
 ```
-
----
-
-_Source: superpowers' verification-before-completion skill. CurdX-Flow turns it into a gate._

package/knowledge/artifact-output-discipline.md

@@ -0,0 +1,24 @@
+# Artifact Output Discipline
+
+Use this discipline for artifact-producing agents that write canonical files
+such as `research.md`, `requirements.md`, `design.md`, `tasks.md`, or
+`codebase-index.md`.
+
+## Core Rules
+
+1. Write the artifact first. The first substantive action should be the `Write`
+   tool call for the final file content.
+2. Do not preview or paraphrase the artifact inline. The file is the
+   deliverable.
+3. Keep status updates minimal: short bullets or fixed summary lines only.
+4. End with the exact compact output contract defined by the agent-specific
+   section. No extra explanation before or after it.
+5. If something blocks the write, report the blocker directly instead of
+   emitting a fake success summary.
+
+## Why
+
+- Prevents context waste from duplicating the artifact in chat
+- Makes the written file the canonical output surface
+- Keeps artifact-producing subagents consistent across research, product,
+  architecture, planning, and brownfield mapping

package/knowledge/artifact-summary-contracts.md

@@ -0,0 +1,50 @@
+# Artifact Summary Contracts
+
+Use these compact summary contracts after an artifact lands successfully. Pair
+them with `artifact-output-discipline.md`: write first, no preview, then emit
+the exact contract below and stop.
+
+## research.md
+
+```text
+✓ research.md generated
+Recommendations: N
+Next: /curdx-flow:spec --phase=requirements
+```
+
+## requirements.md
+
+```text
+✓ requirements.md generated
+User stories: N
+Functional requirements: N
+Next: /curdx-flow:spec --phase=design
+```
+
+## design.md
+
+```text
+✓ design.md generated
+Architecture decisions: N
+Components: N
+Next: /curdx-flow:spec --phase=tasks
+```
+
+## tasks.md
+
+```text
+✓ tasks.md generated
+Total tasks: N
+Coverage audit: PASS
+Phases: 1-5
+Next: /curdx-flow:implement
+```
+
+## codebase-index.md
+
+```text
+✓ codebase-index.md generated
+Modules: N
+Entry points: N
+Next: /curdx-flow:start <feature-name>
+```

package/knowledge/execution-strategies.md

@@ -76,7 +76,7 @@ main agent
 - ✓ Quality-first (every task must be high-quality, avoid context pollution)
 - ✓ Moderate task size (2-15 minutes)
 - ✓ Tasks relatively independent, no complex shared context needed
-- ✓ Superpowers style
+- ✓ Stable per-task quality matters more than dispatch overhead
 
 ### Advantages
 - Each subagent uses at most ~30% context → stable quality
@@ -127,7 +127,7 @@ Safety invariant: `ALL_TASKS_COMPLETE` is advisory, not authoritative. If `tasks
 - ✓ Long task chains (20+)
 - ✓ Unattended execution (overnight automation)
 - ✓ You don't want to trigger each step manually
-- ✓ smart-ralph style
+- ✓ Long-running sequential work with checkpointed continuation
 
 ### Advantages
 - Truly autonomous execution — the user can walk away
@@ -169,7 +169,7 @@ main agent
 - ✓ Many `[P]` markers in tasks.md
 - ✓ Tasks are independent (different files, different components)
 - ✓ Time-pressured (parallelism is faster)
-- ✓ get-shit-done style
+- ✓ Parallel-safe delivery work
 
 ### Advantages
 - Wall-clock time greatly reduced (N parallel tasks at once)
@@ -298,4 +298,6 @@ Claude Code checkpoints plus `.flow/specs/<name>/.progress.md` are the current r
 
 ---
 
-_Adapted from smart-ralph (stop-hook), superpowers (subagent), get-shit-done (wave)._
+This document defines CurDX-Flow's shipped strategy semantics: stop-hook for
+checkpointed continuation, subagent for serial isolated execution, and wave for
+parallel batches.

package/knowledge/poc-first-workflow.md

@@ -114,7 +114,7 @@ Commit: `refactor(scope): yellow - <what was cleaned up>`
 ### Pitfalls
 - **Code first, tests after** → not TDD, this is post-hoc testing. Easily misses edge cases.
 - **Tests only cover happy path** → no error handling coverage; the common cause of production issues.
-- **Too much mocking** → tests disconnected from real behavior. See Superpowers' "integration tests hit real DB" lesson.
+- **Too much mocking** → tests disconnected from real behavior. Keep primary evidence anchored to real integrations at system boundaries.
 
 ---
 
@@ -211,7 +211,7 @@ Feature is verified, reviewed, and ready for a human PR/release decision.
 
 ## Relationship to the TDD Iron Rule
 
-**TDD iron rule inherited from Superpowers**: "NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST"
+**TDD iron rule**: "NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST"
 
 **POC-First's compromise**: Phase 1 allows skipping tests because the purpose of POC is to validate the idea, not to deliver.
 
@@ -221,7 +221,3 @@ Feature is verified, reviewed, and ready for a human PR/release decision.
 - Newly added **production code**: must be covered by Phase 3 TDD loop
 
 The two don't conflict: POC is not production code; production code starts at Phase 2.
-
----
-
-_Adapted from smart-ralph's POC-First workflow, extended with superpowers' TDD discipline._

package/knowledge/spec-driven-development.md

@@ -178,7 +178,3 @@ The two complement each other:
 - Agents `mcp__claude_mem__search` the history before starting research
 - What gets written into research.md is filtered, retention-worthy conclusions
 - Subsequent sessions: claude-mem auto-injects recent context; spec files provide the structured overview
-
----
-
-_Adapted from smart-ralph's spec engine, extended with get-shit-done's multi-source audit._

package/knowledge/systematic-debugging.md

@@ -1,7 +1,5 @@
 # Systematic Debugging — 4-Stage Methodology
 
-> Inherited from superpowers' systematic-debugging skill.
->
 > Agents reference this via `@${CLAUDE_PLUGIN_ROOT}/knowledge/systematic-debugging.md`.
 
 ---
@@ -378,7 +376,3 @@ The value of systematic debugging:
 Unsystematic → fixes fast but fragile → bitten again by the same bug
 Systematic  → fixes slow but thorough → solved once, never looked back
 ```
-
----
-
-_Source: superpowers' systematic-debugging skill._

package/knowledge/two-stage-review.md

@@ -1,6 +1,6 @@
 # Two-Stage Review — Two-Stage Code Review
 
-> CurdX-Flow version of Superpowers' code review skill.
+> CurDX-Flow runtime contract for two-stage review.
 >
 > Agents reference this via `@${CLAUDE_PLUGIN_ROOT}/knowledge/two-stage-review.md`.
 
@@ -129,6 +129,12 @@ Stage 2 applies all enabled Gates (from `.flow/config.json`):
 - Each applicable edge-case category addressed (N/A noted for the rest)?
 - Gap list has priorities?
 
+#### 2.8 (enterprise) DevEx review (devex-gate)
+
+- Are naming, comments, and structure maintainable for the next engineer?
+- Is setup, typing, and test ergonomics acceptable without tribal knowledge?
+- Does the developer loop stay fast enough to keep future changes safe?
+
 ### Stage 2 verdict
 
 - **EXCELLENT**: all enabled Gates pass, adversarial review clean or only low-severity findings
@@ -232,7 +238,7 @@ Some reviewers list 50 minor improvements — the user can't process.
      ↓                     ↓
      ↓              review-report.md
      ↓
-(optional) /curdx-flow:review --adversarial --edge-case
+(optional) /curdx-flow:review --adversarial --edge-case --devex
                     ↓
                     adversarial-review.md
                     edge-cases.md
@@ -241,7 +247,3 @@ Ready for human PR/release handoff with verification + review evidence
 ```
 
 Verify is "did we implement the right thing", Review is "is the implementation good", Audit is "what else could be better". CurdX-Flow currently stops at evidence-backed handoff; do not reference non-existent ship/land commands.
-
----
-
-_Source: superpowers' code-review two-stage design, extended with CurdX-Flow's Gate system._

package/knowledge/wave-execution.md

@@ -399,4 +399,5 @@ As in "Case 3" above. Solutions:
 
 ---
 
-_Source: get-shit-done's wave execution. CurdX-Flow turns it from a concept into executable logic._
+_Source: CurDX-Flow wave execution contract. This file defines the executable
+parallel-delivery rules used by the plugin runtime._

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@curdx/flow",
-  "version": "2.2.3",
-  "description": "CLI installer for CurdX-Flow — AI engineering workflow meta-framework for Claude Code",
+  "version": "2.2.5",
+  "description": "Skill-first discipline layer and CLI installer for Claude Code",
   "type": "module",
   "bin": {
     "curdx-flow": "bin/curdx-flow.js"

package/schemas/agent-frontmatter.schema.json

@@ -54,6 +54,10 @@
     "isolation": {
       "type": "string",
       "enum": ["worktree"]
+    },
+    "color": {
+      "type": "string",
+      "enum": ["red", "blue", "green", "yellow", "purple", "orange", "pink", "cyan"]
     }
   }
 }

package/skills/brownfield-index/SKILL.md

@@ -30,30 +30,24 @@ paths:
 
 # Brownfield Index
 
-You are invoked when the user needs a structural map of an existing codebase they are not yet familiar with.
+This is a fast structural mapping skill for inherited codebases. Keep the
+entrypoint focused on when to index, what the analyst must produce, and where
+to route the user next. Detailed rules live in:
 
-## Preconditions
-
-1. The repository root is the current working directory (or a path the user specifies).
-2. The project is not a new `/curdx-flow:init`-ed greenfield project (if it is, direct the user to `/curdx-flow:start` instead).
-
-## Workflow
+- `references/applicability.md`
+- `references/index-contract.md`
+- `references/handoff.md`
 
-This skill runs in a forked context through `flow-brownfield-analyst`, which will:
-
-1. Detect the actual stack from the repo's manifests.
-2. Scan structure, entry points, module boundaries, and developer-loop commands.
-3. Map API / CLI surfaces when they exist.
-4. Write `.flow/codebase-index.md` with concrete next actions.
+## Preconditions
 
-### Hand off
+Use `references/applicability.md` to decide whether the repository actually
+needs a brownfield index first.
 
-Point the user at the next useful action:
-- "Looking to add a feature here? Run `/curdx-flow:start <name>` to begin a spec."
-- "Debugging something specific? Run `/curdx-flow:debug '<symptom>'`."
+## Index Contract
 
-## Notes
+`flow-brownfield-analyst` writes the structural map defined in
+`references/index-contract.md`.
 
-The index is meant to be quick and decision-useful, not exhaustive.
+## Handoff
 
-For deep research into a specific library or framework, use `context7` MCP directly.
+Use `references/handoff.md` to route the user to the next relevant command.

package/skills/brownfield-index/references/applicability.md

@@ -0,0 +1,12 @@
+# Brownfield Applicability — When to Index First
+
+Use this skill when:
+
+- the repository is unfamiliar, inherited, or legacy
+- the user needs a quick structural map before feature work
+
+Do not use it for a fresh greenfield repo that should start directly with:
+
+```text
+/curdx-flow:start <name> "<goal>"
+```

package/skills/brownfield-index/references/handoff.md

@@ -0,0 +1,8 @@
+# Brownfield Handoff — What to Do After Indexing
+
+Route to the next concrete action:
+
+- feature work -> `/curdx-flow:start <name> "<goal>"`
+- targeted bug work -> `/curdx-flow:debug "<symptom>"`
+
+For deep framework or library research, use Context7 directly.

package/skills/brownfield-index/references/index-contract.md

@@ -0,0 +1,10 @@
+# Brownfield Index Contract — What the Analyst Must Produce
+
+`flow-brownfield-analyst` should:
+
+1. detect the actual stack from manifests
+2. scan structure, entry points, boundaries, and developer-loop commands
+3. map API or CLI surfaces when they exist
+4. write `.flow/codebase-index.md`
+
+The index should be quick and decision-useful, not exhaustive.