@curdx/flow 1.1.11 → 2.0.0-beta.2

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
     "email": "bydongxin@gmail.com"
   },
   "metadata": {
-    "description": "CurDX-Flow marketplace — distributes the curdx-flow meta-framework plugin",
-    "version": "1.1.11"
+    "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.0.0-beta.2"
   },
   "plugins": [
     {
       "name": "curdx-flow",
       "source": "./",
-      "description": "AI engineering workflow meta-framework — spec-driven + autonomous execution + quality gates + multi-agent collaboration",
+      "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.",
       "keywords": [
         "workflow",
         "spec-driven",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "curdx-flow",
-  "version": "1.1.11",
-  "description": "AI engineering workflow meta-framework — spec-driven + autonomous execution + quality gates + multi-agent collaboration. Distills Karpathy + BMAD + GSD + Ralph + Superpowers + GStack and orchestrates context7 / sequential-thinking / chrome-devtools / frontend-design / claude-mem / pua dependencies.",
+  "version": "2.0.0-beta.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",
     "email": "bydongxin@gmail.com"

package/CHANGELOG.md

@@ -2,6 +2,85 @@
 
 All notable changes to CurDX-Flow will be documented here.
 
+## [2.0.0-beta.1] - 2026-04-20
+
+### BREAKING — Major redesign: Discipline Layer, not meta-framework
+
+v2 reframes the project from "AI engineering workflow meta-framework distilling 6 methodologies" into a focused **Claude Code Discipline Layer** — spec-driven workflow + goal-backward verification + Karpathy discipline. 30 slash commands became 9. 24 agents became 15.
+
+See [MIGRATION.md](./MIGRATION.md) for the full v1 → v2 command mapping.
+
+### Removed — 21 slash commands
+
+Folded into `/curdx-flow:spec` via flags:
+- `/research`, `/requirements`, `/design`, `/tasks` → `/spec --phase=<name>`
+- `/plan-ceo`, `/plan-eng`, `/plan-design`, `/plan-dx`, `/autoplan` → `/spec --review[=<dim>]`
+- `/audit` → `/verify --strict`
+
+Moved to auto-invoked skills (also slash-callable by their skill name):
+- `/triage` → `epic` skill
+- `/qa` → `browser-qa` skill
+- `/sketch` → `ui-sketch` skill
+- `/security` → `security-audit` skill
+- `/index` → `brownfield-index` skill
+
+Moved to CLI-only (outside Claude Code):
+- `/doctor` → `npx @curdx/flow doctor`
+- `/install-deps` → `npx @curdx/flow install --all`
+
+Removed outright:
+- `/party` — gimmick, no measured value. Ask Claude directly for multi-perspective discussion.
+- `/discuss` — edit `.flow/STATE.md` directly to log decisions.
+- `/status` — use `/curdx-flow:start --list`, or read `.flow/specs/<name>/.state.json` directly.
+- `/switch` — folded into `/curdx-flow:start <spec-name>`.
+- `/spike` — folded into `/curdx-flow:fast "spike: <hypothesis>"`.
+
+### Removed — 9 persona agents
+
+Mary, John, Winston, Amelia, Rachel, David, Oliver, Serena, Emma. Their voices merged into the corresponding `flow-*` functional agents. `/party` is gone too.
+
+### Added — 5 auto-invoked skills
+
+Each skill has extensive trigger keywords in English and Chinese so Claude auto-invokes based on context. All are also slash-callable (`/curdx-flow:<skill-name>`).
+
+- `skills/epic/` — vertical-slice decomposition of large features
+- `skills/browser-qa/` — real-browser testing via chrome-devtools MCP
+- `skills/ui-sketch/` — UI design variant generation (uses `frontend-design` skill)
+- `skills/security-audit/` — OWASP + STRIDE + CVE scan
+- `skills/brownfield-index/` — map unfamiliar / legacy codebases
+
+### Changed — expanded flag surface on core commands
+
+- `/curdx-flow:spec` gains `--phase=<X[,Y,...]>`, `--until=<phase>`, `--review[=<dim>]`, `--regenerate`, `--resume`
+- `/curdx-flow:start` gains `--resume`, `--list`, `--mode=<fast|standard|enterprise>` and now handles spec switching (absorbing v1 `/switch`)
+- `/curdx-flow:verify` gains `--strict` (multi-source coverage audit, absorbing v1 `/audit`)
+- `/curdx-flow:review` normalizes flags to `--stage=<1|2|both>`, `--adversarial`, `--edge-case`
+
+### Changed — mode semantics
+
+Modes reduced from 4 (`sketch / fast / standard / enterprise`) to 3 (`fast / standard / enterprise`). `sketch` folded into the `ui-sketch` skill which runs regardless of mode.
+
+### Unchanged (intentionally)
+
+- `.flow/` directory structure — fully backwards-compatible with v1 specs
+- 3 auto-installed MCPs (context7, sequential-thinking, chrome-devtools)
+- 5 hook events (SessionStart, InstructionsLoaded, Stop, PreToolUse, PostToolUseFailure)
+- 8 composable gates (karpathy, verification, tdd, coverage-audit, adversarial-review, edge-case, security, devex)
+- Templates (`templates/*.tmpl`) and their rendering pipeline
+- The CLI (install, doctor, upgrade, uninstall)
+- Global `~/.claude/CLAUDE.md` protocol injection
+
+### Why
+
+Field feedback on v1:
+- Users couldn't discover commands — 30 options in the slash menu exceeds working memory
+- Claude Code auto-truncates slash descriptions once they exceed ~8 KB, hitting us at 30 commands
+- Peer tools (Spec Kit ~7, BMAD ~15, Aider ~15) ship with far fewer commands
+- "Meta-framework distilling 6 methodologies" is a maintainer concept, not a user value prop
+- The real value is **Karpathy discipline + goal-backward verification** — everything else is scaffolding
+
+v2 keeps the scaffolding (agents, gates, hooks, knowledge docs) but hides it behind the 9 commands that real users use.
+
 ## [1.1.1] - 2026-04-20
 
 ### Fixed

package/README.md

@@ -1,7 +1,7 @@
 # CurDX-Flow
 
-> **AI Engineering Workflow Meta-Framework for Claude Code**
-> Turn Claude Code into a disciplined engineering team — orchestrate MCPs and plugins, enforce Karpathy's 4 principles, and ship quality software with spec-driven workflows.
+> **Stop Claude Code from faking "done".**
+> Spec-driven workflow + goal-backward verification + Karpathy discipline.
 
 [![npm version](https://img.shields.io/npm/v/@curdx/flow.svg)](https://www.npmjs.com/package/@curdx/flow)
 [![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
@@ -10,148 +10,120 @@
 
 ---
 
-## What It Is
+## Why this exists
 
-CurDX-Flow is a Claude Code plugin that distills six proven AI-engineering workflows (Karpathy guidelines, BMAD-METHOD, get-shit-done, gstack, smart-ralph, superpowers) into a single composable system — then delegates infrastructure to specialized third-party plugins (context7, sequential-thinking, chrome-devtools, claude-mem, pua, frontend-design).
+Claude Code drifts. It claims features work without running the tests. It uses stale library APIs from its training data. It takes three questions worth of code and squeezes in six.
 
-**It doesn't reinvent wheels. It orchestrates good ones.**
+CurDX-Flow is a thin **discipline layer** on top of Claude Code that makes non-trivial feature work actually work:
 
-## At a Glance (v1.1.0)
+1. **A spec workflow** (research → requirements → design → tasks) for features too big to vibe-code.
+2. **Goal-backward verification** that scans your implementation against your own FR / AC / AD and catches stubs, fake completions, and untested acceptance criteria.
+3. **Karpathy's 4 principles** (think-first, simplicity, surgical changes, goal-driven) enforced via always-on hooks and gates.
 
-- **31 commands** — initialize, research, design, execute, verify, review, debug, QA, security, ...
-- **24 agents** — 15 functional + 9 personas (Mary, John, Winston, Amelia, Rachel, David, Oliver, Serena, Emma)
-- **8 composable gates** — Karpathy / Verification / TDD / Coverage / Adversarial / Edge-Case / Security / DevEx
-- **4 execution strategies** — linear / subagent / stop-hook / wave (auto-routed)
-- **10 knowledge docs** — spec-driven dev, POC-first, atomic commits, execution strategies, ...
-- **5 hook events** — SessionStart / InstructionsLoaded / Stop / PreToolUse / PostToolUseFailure
-- **3 auto-installed MCPs** — context7, sequential-thinking, chrome-devtools
-- **Graceful degradation** — missing deps → fallback modes with clear notices
-
-## Why Use It
-
-Existing AI-coding workflows suffer from:
+Not a framework. Not a methodology library. A discipline layer.
 
-| Problem | CurDX-Flow's Answer |
-|---------|---------------------|
-| Context rot (long sessions degrade) | Subagent isolation + stop-hook loops + claude-mem |
-| No discipline (AI skips, hallucinates) | Karpathy L1 + verification-gate + TDD-gate enforcement |
-| Scattered best practices | Six workflows distilled into one meta-framework |
-| Weak verification (claim "done" without proof) | Goal-backward verification + forbidden-word detection |
-| Single-viewpoint decisions | Party Mode (real multi-agent, not role-play) + adversarial review |
+## Install (one command)
 
-## Install
-
-### Recommended: one-shot via npm (works in any project, fast on Chinese npm mirrors)
 ```bash
-# Interactive install (picks recommended plugins)
-npx @curdx/flow install
-
-# Or install everything automatically
 npx @curdx/flow install --all
-
-# After the one-time install, initialize your project INSIDE Claude Code:
-#   $ claude
-#   /curdx-flow:init
-#   /curdx-flow:start my-feature "<description>"
-
-# Other CLI lifecycle operations
-npx @curdx/flow doctor      # Health check
-npx @curdx/flow upgrade     # Update all plugins
-npx @curdx/flow uninstall   # Remove curdx-flow
-```
-
-### From the Claude Code marketplace
-```
-/plugin marketplace add curdx/curdx-flow
-/plugin install curdx-flow
 ```
 
-### Local dev
-```bash
-git clone https://github.com/curdx/curdx-flow
-claude --plugin-dir ./curdx-flow
-```
+This installs the Claude Code plugin (fully offline from the npm package — no GitHub fetch), the 3 auto-registered MCP servers, and three recommended companion plugins (pua, claude-mem, frontend-design).
 
-3 MCPs auto-install. Then run:
+## 9 slash commands, that's it
 
 ```
-/curdx-flow:install-deps    # interactive install of pua / claude-mem / frontend-design
-/curdx-flow:doctor          # verify health
-/curdx-flow:init            # initialize your project
+/curdx-flow:init           Initialize .flow/ in the current project
+/curdx-flow:start          Create / resume / switch a feature spec
+/curdx-flow:spec           Write or refresh the spec (--phase, --review flags)
+/curdx-flow:implement      Execute the tasks
+/curdx-flow:verify         Goal-backward check ← the moat
+/curdx-flow:review         Two-stage code review
+/curdx-flow:fast           Skip spec for one-off tasks
+/curdx-flow:debug          Systematic 4-stage debugging
+/curdx-flow:help           Reference
 ```
 
-See [`docs/getting-started.md`](./docs/getting-started.md) for a 5-minute walkthrough.
+Plus 5 auto-invoked skills (Claude picks them up from context): `epic`, `browser-qa`, `ui-sketch`, `security-audit`, `brownfield-index`.
 
-## Quick Start
+## Quick start
 
 ```bash
-# 1. In your project
+# 1. In your project, initialize
+cd ~/your-project
+claude
 /curdx-flow:init
 
 # 2. Start a feature
-/curdx-flow:start jwt-auth "Add JWT authentication to REST API"
+/curdx-flow:start jwt-auth "Add JWT authentication to the REST API"
 
-# 3. Generate full spec (research → requirements → design → tasks)
+# 3. Generate the spec (research → requirements → design → tasks)
 /curdx-flow:spec
 
-# 4. Execute (auto-picks best strategy)
+# 4. Execute
 /curdx-flow:implement
 
 # 5. Verify + review
 /curdx-flow:verify
 /curdx-flow:review
 
-# Done. git push.
+# Done.
 ```
 
-For more scenarios (brownfield, epic, fast, UI-heavy), see [`docs/workflows.md`](./docs/workflows.md).
+See [`docs/getting-started.md`](./docs/getting-started.md) for a five-minute walkthrough, or [`docs/workflows.md`](./docs/workflows.md) for typical scenarios (greenfield / brownfield / epic / fast / enterprise).
 
-## Five Pillars
+## The three modes
 
-1. **Mind (L1 baseline)** — Karpathy 4 principles + mandatory tool rules + 3 red lines
-2. **Spec** — Research → Requirements → Design → Tasks (scalable, 4-file lite to 12-file enterprise)
-3. **Agents** — 15 functional + 9 persona (Mary / John / Winston / ...)
-4. **Flow** — 4 execution strategies, auto-routed
-5. **Memory** — claude-mem (implicit) + `.flow/STATE.md` (explicit decisions as D-NN)
+Set when you run `/curdx-flow:start --mode=<mode>`. Each mode decides which gates are enforced.
 
-See [`docs/ethos.md`](./docs/ethos.md) for design philosophy.
+| Mode | Workflow | Gates |
+|------|----------|-------|
+| `fast` | Skip the spec — just execute | karpathy + verification |
+| `standard` (default) | Full 4-phase spec | + tdd + coverage-audit |
+| `enterprise` | Full spec + planning review + adversarial + edge-case + security audit | All gates |
 
-## Documentation
+## Upgrading from v1.x
 
-| Doc | When to read |
-|-----|--------------|
-| [`docs/getting-started.md`](./docs/getting-started.md) | First time, 5-minute walkthrough |
-| [`docs/command-reference.md`](./docs/command-reference.md) | All 31 commands with usage |
-| [`docs/agent-reference.md`](./docs/agent-reference.md) | All 24 agents + personas |
-| [`docs/workflows.md`](./docs/workflows.md) | 5 typical scenarios (greenfield/brownfield/epic/fast/UI) |
-| [`docs/architecture.md`](./docs/architecture.md) | Internal design for extenders |
-| [`docs/ethos.md`](./docs/ethos.md) | Why it's built this way |
-| [`docs/troubleshoot.md`](./docs/troubleshoot.md) | Fix common problems |
+v2 is a major rewrite. Thirty slash commands became nine. If you're coming from v1, see [`MIGRATION.md`](./MIGRATION.md) for the mapping table. If you'd rather stay on v1:
 
-## What's Not Here (Yet)
+```bash
+npm i -g @curdx/flow@^1.1
+```
 
-**Intentionally skipped in v1.0**:
-- **Phase 6** (ship / land / canary / retro) — Low ROI for private-repo use cases. Future release if community asks.
-- **Integration checker** — For Epic cross-spec validation. Manual for now.
-- **Checkpoint save/restore** — Current `.flow/STATE.md` covers most needs.
-- **Multi-runtime support** — Claude Code only. Other tools later if their plugin API matures.
+## What's in the box
 
-See [`CHANGELOG.md`](./CHANGELOG.md) for full version history.
+- **9 slash commands** + **5 auto-invoked skills** (the complete public surface)
+- **15 internal agents** that the commands dispatch (no user-visible personas — that was v1)
+- **8 composable gates** — Karpathy / Verification / TDD / Coverage / Adversarial / Edge-Case / Security / DevEx
+- **4 execution strategies** for `/curdx-flow:implement` (linear / subagent / stop-hook / wave, auto-routed)
+- **5 hook events** that enforce the discipline without user action
+- **3 auto-installed MCPs** — context7 (latest docs), sequential-thinking (structured reasoning), chrome-devtools (browser automation)
+- **Offline-capable install** — the npm package ships the full plugin body; zero GitHub round-trips during install
+
+## Documentation
+
+| Doc | When to read |
+|-----|--------------|
+| [`docs/getting-started.md`](./docs/getting-started.md) | First time — five-minute walkthrough |
+| [`docs/command-reference.md`](./docs/command-reference.md) | All 9 commands + 5 skills with flags |
+| [`docs/agent-reference.md`](./docs/agent-reference.md) | The 15 internal agents |
+| [`docs/workflows.md`](./docs/workflows.md) | Typical scenarios with exact command sequences |
+| [`docs/architecture.md`](./docs/architecture.md) | Internal design for contributors and extenders |
+| [`docs/ethos.md`](./docs/ethos.md) | Why we built it this way |
+| [`docs/troubleshoot.md`](./docs/troubleshoot.md) | Symptom-indexed fixes |
+| [`docs/releasing.md`](./docs/releasing.md) | Maintainer: how to cut a new version |
+| [`MIGRATION.md`](./MIGRATION.md) | v1 → v2 command mapping |
 
 ## Credits
 
-CurDX-Flow is a distillation, not an invention. Deeply indebted to:
+CurDX-Flow v2 is a distillation, not an invention. Ideas we depend on:
 
-- [**andrej-karpathy-skills**](https://github.com/forrestchang/andrej-karpathy-skills) — the 4 principles
-- [**smart-ralph**](https://github.com/Nibzard/smart-ralph) — spec engine + stop-hook loops
+- [**Andrej Karpathy's 4 principles**](https://github.com/forrestchang/andrej-karpathy-skills) — the discipline foundation
+- [**GitHub Spec Kit**](https://github.com/github/spec-kit) — spec-driven development boiled down
 - [**superpowers**](https://github.com/obra/superpowers) — subagent discipline + TDD + two-stage review
-- [**BMAD-METHOD**](https://github.com/bmad-code-org/BMAD-METHOD) — personas + party mode + adversarial review
-- [**get-shit-done**](https://github.com/ryangentry/get-shit-done) — wave execution + decision locking + multi-source audit
-- [**gstack**](https://github.com/garrytan/gstack) (Garry Tan) — planning reviews + DX philosophy
-- [**pua**](https://github.com/tanweai/pua) — persistence + 3 red lines
-- [**claude-mem**](https://github.com/thedotmack/claude-mem) — automatic cross-session memory
-- [**frontend-design skill**](https://claude.ai/skills/frontend-design) — distinctive UI (Anthropic official)
-- **context7** (Upstash) + **sequential-thinking** (Anthropic) + **chrome-devtools-mcp** (Chrome team)
+- [**pua**](https://github.com/tanweai/pua) — the three red lines
+- [**claude-mem**](https://github.com/thedotmack/claude-mem) — cross-session memory
+- **Anthropic official** — context7 (Upstash), sequential-thinking, chrome-devtools-mcp, frontend-design skill
 
 ## License
 
@@ -159,9 +131,9 @@ MIT. See [`LICENSE`](./LICENSE).
 
 ## Contributing
 
-- Issues: https://github.com/wdx/curdx-flow/issues
-- PRs welcome but please walk through `/curdx-flow:spec` yourself first (eat your own dogfood)
-- Code of conduct: be kind + specific + don't rage at the LLM
+- Issues: https://github.com/curdx/curdx-flow/issues
+- PRs: please eat your own dogfood — run `/curdx-flow:spec` on your own PR first
+- Be specific. No rage-at-the-LLM. The point is to make Claude reliable, not to whine about when it isn't.
 
 ---
 

package/agents/flow-adversary.md

@@ -164,7 +164,7 @@ Possible reasons:
 
 **Recommendations**:
 - Human review (walk through the diff)
-- /curdx-flow:qa for real browser/integration testing (Phase 5+)
+- the `browser-qa` skill for real browser/integration testing (Phase 5+)
 - Observe in staging
 ```
 

package/agents/flow-architect.md

@@ -186,5 +186,5 @@ Error paths: cover M scenarios
 
 Next:
   - Review the design (especially AD-01/02/03)
-  - /curdx-flow:tasks — break down tasks
+  - /curdx-flow:spec --phase=tasks — break down tasks
 ```

package/agents/flow-product-designer.md

@@ -142,5 +142,5 @@ Acceptance criteria: M total, covering X happy paths + Y edge cases
 
 Out of Scope: K items explicitly excluded
 
-Next step: /curdx-flow:design
+Next step: /curdx-flow:spec --phase=design
 ```

package/agents/flow-qa-engineer.md

@@ -22,7 +22,7 @@ Output: `.flow/specs/<name>/qa-report.md`.
 
 ## Prerequisites
 
-- `chrome-devtools` MCP is running (confirm with `/curdx-flow:doctor`)
+- `chrome-devtools` MCP is running (confirm with `npx @curdx/flow doctor`)
 - Dev server is reachable (e.g. localhost:3000)
 - The spec's `design.md` exists (so you know expected behavior)
 
@@ -216,7 +216,7 @@ Tester: flow-qa-engineer
 - Performance: pass
 - Accessibility: warnings
 
-Recommendation: fix Bug-001, Bug-004, then re-run /curdx-flow:qa.
+Recommendation: fix Bug-001, Bug-004, then re-run the `browser-qa` skill (or say "test this in a real browser").
 ```
 
 ### Step 8: Update .state.json
@@ -267,7 +267,7 @@ Report: .flow/specs/<name>/qa-report.md
 Screenshots: .flow/specs/<name>/qa-screenshots/
 
 Next:
-- Fix high bug → /curdx-flow:qa re-test
+- Fix high bug → re-run the `browser-qa` skill
 - Or append to tasks.md (Phase 3.X QA fixes)
 ```
 

package/agents/flow-researcher.md

@@ -151,5 +151,5 @@ Open questions (please answer before entering requirements phase):
   1. Q1
   2. Q2
 
-Next step: /curdx-flow:requirements
+Next step: /curdx-flow:spec --phase=requirements
 ```

package/agents/flow-security-auditor.md

@@ -390,7 +390,7 @@ Report: .flow/specs/<name>/security-audit.md
 
 Next:
 - Fix must-fix items → /curdx-flow:implement <task>
-- Then re-run /curdx-flow:security
+- Then re-run the `security-audit` skill (or say "audit for security issues")
 ```
 
 ---

package/agents/flow-triage-analyst.md

@@ -282,9 +282,9 @@ Sub-spec skeletons (N):
 Dependency graph: see epic.md
 
 Recommended execution order:
-  1. /curdx-flow:switch <sub-1> && /curdx-flow:spec
-  2. In parallel: /curdx-flow:switch <sub-2> && /curdx-flow:spec
-  3. After 1 is done: /curdx-flow:switch <sub-3> && /curdx-flow:spec
+  1. /curdx-flow:start <sub-1> && /curdx-flow:spec
+  2. In parallel: /curdx-flow:start <sub-2> && /curdx-flow:spec
+  3. After 1 is done: /curdx-flow:start <sub-3> && /curdx-flow:spec
 
 Estimated total duration: N weeks
 ```

package/agents/flow-ui-researcher.md

@@ -133,7 +133,7 @@ For this project (per CONTEXT.md):
 - Palette: follow project primary #6366F1
 - Font: keep Inter system
 
-## Suggested Direction for UX Designer (Emma / flow-ux-designer)
+## Suggested Direction for flow-ux-designer
 
 Generate 2-3 variants:
 1. Variant A: pure Stripe style (most conservative)
@@ -170,20 +170,20 @@ mkdir -p "$REF_DIR"
 /curdx-flow:ui-research "reference patterns for login form"
   ↓ outputs ui-research.md
   
-/curdx-flow:sketch
+the `ui-sketch` skill
   ↓ flow-ux-designer reads ui-research.md as input
   ↓ generates variants A/B/C based on research findings
 ```
 
 Division of labor:
 - **Me (UI Researcher)**: gather + classify, no design
-- **Emma (UX Designer)**: produces actual UI based on my research
+- **flow-ux-designer**: produces actual UI based on my research
 
 ---
 
 ## Forbidden
 
-- ✗ Doing actual UI design (that's Emma's job)
+- ✗ Doing actual UI design (that's flow-ux-designer's job)
 - ✗ Listing references from memory (must WebSearch or scan the codebase)
 - ✗ Providing only one reference (at least 3 categories)
 - ✗ Ignoring CONTEXT.md preferences
@@ -219,7 +219,7 @@ Report: .flow/specs/<name>/ui-research.md
 Assets: .flow/specs/<name>/ui-research/refs/
 
 Next step:
-  /curdx-flow:sketch — generate concrete UI variants based on research
+  the `ui-sketch` skill — generate concrete UI variants based on research
 ```
 
 ---

package/agents/flow-ux-designer.md

@@ -28,7 +28,7 @@ Output: HTML files under `.flow/specs/<name>/ui-sketch/` (multiple variants allo
 **Fallback when skill is unavailable**:
 - Switch to Tailwind CSS + shadcn/ui default style
 - Clearly tell the user "frontend-design skill not installed, using generic styles"
-- Suggest `/curdx-flow:install-deps` to install frontend-design
+- Suggest `npx @curdx/flow install --all` to install frontend-design
 
 ---
 
@@ -201,7 +201,7 @@ View:
 
 Next:
 - Pick a variant → tell me which one → I'll turn it into production components
-- Or /curdx-flow:qa to verify interactions in-browser (chrome-devtools)
+- Or the `browser-qa` skill to verify interactions in-browser (chrome-devtools)
 ```
 
 ---

package/cli/install.js

@@ -237,15 +237,26 @@ export async function install(args = []) {
 }
 
 function printNextSteps() {
+  // Detect whether the CLI is globally installed (curdx-flow on PATH) or
+  // the user ran us via npx. Tell them the right invocation each time.
+  const cliOnPath = has("curdx-flow");
+  const cliCmd = cliOnPath ? "curdx-flow" : "npx @curdx/flow";
+
   console.log(`\n${color.bold("✅ Install complete")}\n`);
+  console.log(`${color.bold("Restart Claude Code")} so the plugin registers all its commands and hooks.\n`);
   console.log(`${color.bold("Next steps")}:\n`);
   console.log(`  ${color.dim("# Verify health")}`);
-  console.log(`  curdx-flow doctor\n`);
-  console.log(`  ${color.dim("# Initialize .flow/ in your project")}`);
-  console.log(`  cd ~/your-project && curdx-flow init\n`);
-  console.log(`  ${color.dim("# Start using it (inside Claude Code)")}`);
+  console.log(`  ${cliCmd} doctor\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")}`);
-  console.log(`  ${color.cyan("/curdx-flow:start my-feature \"<describe what to build>\"")}\n`);
+  console.log(`  ${color.cyan("/curdx-flow:init")}`);
+  console.log(`  ${color.cyan("/curdx-flow:start my-feature \"<one-line goal>\"")}\n`);
+  if (!cliOnPath) {
+    console.log(
+      `${color.dim("Tip: install the CLI globally for shorter commands —")} ${color.cyan("npm i -g @curdx/flow")}\n`
+    );
+  }
   console.log(
     `${color.bold("Learn more")}: https://github.com/curdx/curdx-flow/blob/main/docs/getting-started.md\n`
   );

package/commands/debug.md

@@ -1,6 +1,6 @@
 ---
 name: debug
-description: Systematic debugging — 4-phase methodology (root cause → pattern → hypothesis → fix); ≥3 failures triggers architectural questioning. Dispatches flow-debugger (David).
+description: Systematic debugging — 4-phase methodology (root cause → pattern → hypothesis → fix); ≥3 failures triggers architectural questioning. Dispatches flow-debugger.
 argument-hint: "\"<bug description>\""
 allowed-tools: [Read, Write, Edit, Bash, Task, Grep, Glob]
 ---
@@ -9,7 +9,7 @@ allowed-tools: [Read, Write, Edit, Bash, Task, Grep, Glob]
 
 @${CLAUDE_PLUGIN_ROOT}/knowledge/systematic-debugging.md
 
-Dispatches the `flow-debugger` (David) agent to perform systematic 4-phase debugging.
+Dispatches the `flow-debugger` agent to perform systematic 4-phase debugging.
 
 ## When to use
 
@@ -21,7 +21,7 @@ Dispatches the `flow-debugger` (David) agent to perform systematic 4-phase debug
 ## When not to use
 
 - Still in coding phase → use the normal flow-executor flow
-- Question needs investigation → use /curdx-flow:spike
+- Question needs investigation → use `/curdx-flow:fast` with a prompt like "spike: verify X with minimal tests"
 - Performance issue needing benchmarks → performance tuning is not debug
 
 ## Step 1: Parse bug description
@@ -33,7 +33,7 @@ BUG_DESC="$ARGUMENTS"
 
 ## Step 2: Collect prerequisites (main agent, no dispatch)
 
-Before dispatching David, the main agent (you) collects first:
+Before dispatching the debugger, the main agent (you) collects first:
 
 ```bash
 # 1. Recent commit history (bug may be introduced by a new commit)
@@ -47,14 +47,14 @@ git diff --stat
 ACTIVE=$(cat .flow/.active-spec 2>/dev/null)
 ```
 
-## Step 3: Dispatch flow-debugger (David)
+## Step 3: Dispatch flow-debugger
 
 ```
 Task:
   subagent_type: general-purpose
   description: "Debug: $BUG_DESC"
   prompt: |
-    You are the flow-debugger agent (David). Full definition:
+    You are the flow-debugger agent. Full definition:
     ${CLAUDE_PLUGIN_ROOT}/agents/flow-debugger.md
     
     Methodology knowledge base:
@@ -150,7 +150,7 @@ Next steps:
 
 ## Special case: 3 failures
 
-If David reports 3 failures:
+If the debugger reports 3 failures:
 
 ```
 ⚠ Systematic debugging failed (3 attempts)
@@ -166,8 +166,8 @@ Possible root issues:
   - Data-layer issue
 
 Suggestions:
-  - Review David's detailed report analysis
-  - /curdx-flow:party winston david "what architectural issue does this bug hint at?"
+  - Review the debugger's detailed report analysis
+  - Ask Claude directly: "from an architect's and debugger's perspective, what architectural issue does this bug hint at?"
   - Or temporarily @ts-ignore / skip test and record as tech debt in STATE.md
 ```
 
@@ -175,7 +175,7 @@ Suggestions:
 
 - ✗ Omitting the bug description
 - ✗ Expecting "one-shot fix" (debug is a process, not an event)
-- ✗ Skipping David and editing code yourself (loses the systematic methodology)
+- ✗ Skipping the debugger and editing code yourself (loses the systematic methodology)
 - ✗ Accepting "maybe it's..." as a root cause
 
 ## Relationship to other commands