@curdx/flow 2.2.4 → 2.2.5

package/cli/install-companions.js

@@ -1,14 +1,14 @@
 /**
- * Re-export barrel preserving the pre-Stage-7 import surface. New callers
- * should import directly from the concern-specific modules below instead
- * of going through this barrel. Kept in place so existing imports in
- * cli/install.js and cli/install-workflow.js keep working unchanged.
+ * Re-export barrel preserving the stable import surface. New callers should
+ * import directly from the concern-specific modules below instead of going
+ * through this barrel. Kept in place so existing imports in cli/install.js
+ * and cli/install-workflow.js keep working unchanged.
  *
- * Concern split (see docs/refactor-plan.md Stage 7):
- *   install-required-plugins.js   — required Claude Code companion plugins
- *   install-bundled-mcps.js       — user-level MCP registration
+ * Concern split:
+ *   install-required-plugins.js    — required Claude Code companion plugins
+ *   install-bundled-mcps.js        — user-level MCP registration
  *   install-recommended-plugins.js — optional recommended plugins
- *   install-context7-config.js    — context7 API-key prompt (private to required)
+ *   install-context7-config.js     — context7 API-key prompt (private to required)
  */
 
 export {

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.4",
-  "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.

package/skills/browser-qa/SKILL.md

@@ -15,45 +15,25 @@ paths:
 
 # Browser QA
 
-You are invoked when the user wants real-browser QA of a UI flow.
+This skill orchestrates real-browser validation, not a generic UI review. Keep
+the entrypoint focused on prerequisites, QA artifact requirements, and the
+handoff after findings. Detailed rules live in:
 
-## Preconditions
-
-1. `chrome-devtools` MCP is available (`mcp__chrome_devtools__*`). If missing, fall back to a manual checklist.
-2. A URL (dev server or deployed) is available. Prompt for it if not provided.
-
-## Workflow
-
-### Step 1: Clarify scope
+- `references/prerequisites.md`
+- `references/qa-contract.md`
+- `references/handoff.md`
 
-Confirm with the user:
-- **URL under test** (local `http://localhost:3000` or remote)
-- **Flow to test** (e.g., "sign up → dashboard → logout")
-- **What success looks like** (accessibility / performance / zero console errors / visual match)
-
-### Step 2: Run via `flow-qa-engineer`
-
-This skill executes in a forked context through `flow-qa-engineer`. The agent will:
-1. Open the target URL via `mcp__chrome_devtools__new_page`
-2. Drive the flow with `mcp__chrome_devtools__click` / `fill` / `navigate_page`
-3. Capture `list_console_messages`, `list_network_requests`, `take_screenshot`, optionally `lighthouse_audit`
-4. Compare against expected behavior
-
-### Step 3: Report findings
+## Preconditions
 
-Produce `.flow/specs/<active>/qa-report.md` with:
-- **Bugs** (reproducible, severity P1/P2/P3)
-- **Performance** (LCP / INP / CLS from Lighthouse)
-- **Accessibility** (axe violations with WCAG references)
-- **Console errors** (full stack traces)
-- **Screenshots** (attached)
+Use `references/prerequisites.md` to confirm browser MCP availability and the
+URL or flow under test. Real browser execution in this skill depends on
+`mcp__chrome_devtools__*`.
 
-### Step 4: Hand off
+## QA Contract
 
-If bugs found: suggest `/curdx-flow:debug "<bug title>"` for systematic root-cause analysis.
-If accessibility violations: suggest fixes inline with WCAG refs.
+`flow-qa-engineer` should execute the browser workflow in
+`references/qa-contract.md`.
 
-## References
+## Handoff
 
-- `flow-qa-engineer` agent: `@${CLAUDE_PLUGIN_ROOT}/agents/flow-qa-engineer.md`
-- chrome-devtools MCP docs: https://github.com/ChromeDevTools/chrome-devtools-mcp
+Post-QA routing and bug follow-up live in `references/handoff.md`.

package/skills/browser-qa/references/handoff.md

@@ -0,0 +1,6 @@
+# Browser QA Handoff — Where Findings Go Next
+
+- if reproducible bugs are found -> `/curdx-flow:debug "<bug title>"`
+- if accessibility issues are found -> report concrete WCAG-linked fixes
+- if the flow is clean -> hand off `qa-report.md` as additional evidence, not a
+  replacement for `verify` or `review`

package/skills/browser-qa/references/prerequisites.md

@@ -0,0 +1,10 @@
+# Browser QA Prerequisites — Browser and URL Required
+
+Before dispatching:
+
+- confirm `mcp__chrome_devtools__*` is available
+- confirm a URL under test exists
+- confirm the flow and success criteria
+
+If browser MCP is missing, fall back to a manual checklist rather than
+pretending a real-browser run happened.

package/skills/browser-qa/references/qa-contract.md

@@ -0,0 +1,20 @@
+# Browser QA Contract — What the QA Agent Must Do
+
+`flow-qa-engineer` should:
+
+1. open the target URL
+2. drive the flow in a real browser
+3. collect console, network, screenshot, and optional Lighthouse evidence
+4. compare observed behavior to expected behavior
+
+## Required Artifacts
+
+- `.flow/specs/<active>/qa-report.md`
+- `.flow/specs/<active>/qa-screenshots/`
+
+The report should include:
+
+- bugs by severity
+- performance metrics
+- accessibility findings
+- console errors

package/skills/cancel/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cancel
-description: Stop the active CurDX-Flow execution loop safely. Optional --delete-spec --yes removes the spec directory.
+description: Cancel the active execution loop or delete a spec with explicit confirmation.
 when_to_use: Use when the user wants to stop the current execution loop, abort a stuck run, or delete the active spec intentionally.
 argument-hint: "[spec-name] [--delete-spec --yes]"
 disable-model-invocation: true
@@ -9,74 +9,33 @@ allowed-tools: [Read, Bash]
 
 # CurdX-Flow Cancel
 
-Safely stop an active execution loop. Default behavior is non-destructive: preserve spec files, tasks, progress, and artifacts.
+`cancel` is a recovery control, not an execution path. Keep this entrypoint
+focused on target selection, destructive-mode gating, and the final recovery
+message. Detailed cancel rules live in:
 
-## Target Resolution
-
-1. If `$ARGUMENTS` includes a spec name, use `.flow/specs/<name>`.
-2. Otherwise read `.flow/.active-spec`.
-3. If no target exists, print `No active spec to cancel` and stop.
-
-## Default: Cancel Execution Loop Only
-
-Default mode removes stop-hook/subagent execution state while preserving all human-readable artifacts:
-
-1. Read `.flow/specs/<target>/.state.json`.
-2. Use `Edit` or `Write` to set `phase` to `tasks`.
-3. Set `phase_status.execute` to `cancelled`.
-4. Remove `execute_state` and `strategy`.
-5. If the state file is missing, print `No execution state for <target>. Nothing to cancel.` and stop.
-
-Do not rewrite `.state.json` with a Bash heredoc or ad-hoc Python writer; use checkpoint-tracked `Edit`/`Write` operations.
-
-Append to `.progress.md`:
+- `references/target-resolution.md`
+- `references/state-recovery.md`
+- `references/destructive-mode.md`
+- `references/reporting.md`
 
-```markdown
-## Execution Cancelled YYYY-MM-DD
-- Cancelled by: /curdx-flow:cancel
-- Preserved: research.md, requirements.md, design.md, tasks.md, progress, reports
-- Resume: /curdx-flow:implement --strategy=subagent or /curdx-flow:spec --phase=tasks --regenerate
-```
+## Target Resolution
 
-## Destructive Mode
+Use `references/target-resolution.md` to resolve the target spec.
 
-Only delete the spec directory when both flags are present:
+## Default Behavior
 
-```bash
-/curdx-flow:cancel <spec-name> --delete-spec --yes
-```
+Default mode is non-destructive. Use `references/state-recovery.md` to:
 
-If `--delete-spec` is present without `--yes`, do not delete. Print the exact command required.
+- roll execution state back safely
+- preserve spec artifacts and reports
+- append a recovery note to `.progress.md`
+- recommend the best resume command
 
-Destructive mode:
+## Destructive Behavior
 
-1. Print target path and files that will be removed.
-2. Delete `.flow/specs/<target>`.
-3. If it was active, remove `.flow/.active-spec`.
-4. Do not delete `.flow/PROJECT.md`, `.flow/CONTEXT.md`, `.flow/STATE.md`, or other specs.
+Delete a spec only when both `--delete-spec` and `--yes` are present. The
+deletion rules live in `references/destructive-mode.md`.
 
 ## Output
 
-Default mode:
-
-```markdown
-✓ Cancelled execution loop: <spec-name>
-  State: execute → cancelled, phase → tasks
-  Preserved: spec artifacts and progress
-  Resume: /curdx-flow:implement --strategy=subagent
-```
-
-Destructive mode:
-
-```markdown
-✓ Deleted spec: <spec-name>
-  Removed: .flow/specs/<spec-name>
-  Active spec cleared: yes|no
-```
-
-## Safety Rules
-
-- Never delete a spec unless `--delete-spec --yes` is present.
-- Never delete project-level `.flow` files.
-- If state JSON is corrupt, rename it to `.state.json.corrupt.<timestamp>` instead of deleting it.
-- Prefer `/curdx-flow:status` after cancel to confirm recovery state.
+Use `references/reporting.md` for the default and destructive-mode summaries.

package/skills/cancel/references/destructive-mode.md

@@ -0,0 +1,17 @@
+# Cancel Destructive Mode — Explicit and Narrow
+
+Delete the spec directory only when both flags are present:
+
+```text
+/curdx-flow:cancel <spec-name> --delete-spec --yes
+```
+
+## Destructive Flow
+
+1. print the target path and removal scope
+2. delete `.flow/specs/<target>`
+3. if it was active, clear `.flow/.active-spec`
+4. leave all project-level `.flow` files untouched
+
+If `--delete-spec` appears without `--yes`, stop and print the exact command
+required.

package/skills/cancel/references/reporting.md

@@ -0,0 +1,18 @@
+# Cancel Reporting — Recovery vs Deletion Summary
+
+Default mode:
+
+```text
+✓ Cancelled execution loop: <spec-name>
+  State: execute → cancelled, phase → tasks
+  Preserved: spec artifacts and progress
+  Resume: /curdx-flow:implement --strategy=subagent
+```
+
+Destructive mode:
+
+```text
+✓ Deleted spec: <spec-name>
+  Removed: .flow/specs/<spec-name>
+  Active spec cleared: yes|no
+```