@curdx/flow 2.2.4 → 2.3.0

package/CHANGELOG.md

@@ -1,569 +1,14 @@
 # Changelog
 
-All notable changes to CurdX-Flow will be documented here.
+## 2.3.0
 
-## [2.2.0] - 2026-04-24
+- added a default `flow-orchestrator` main-thread agent through plugin-level `settings.json`
+- added a plugin `flow-state` monitor plus `userConfig` runtime knobs for stop-hook blocking, dependency reminders, and monitor cadence
+- made the manifest explicit about `outputStyles` and `monitors`, shipped the monitor assets in npm tarballs, and strengthened pack/plugin contract tests
+- updated doctor/runtime guidance and public docs to reflect the new main-agent + monitor architecture
 
-### Added
+## 2.2.4
 
-- **Plugin manifest dependency declaration** — `.claude-plugin/plugin.json` declares `skills/`, `agents/`, `hooks/hooks.json`, and a cross-marketplace dependency on `context7-plugin`. `marketplace.json` opts into `allowCrossMarketplaceDependenciesOn: ["context7-marketplace"]` and mirrors the dependency on the plugin entry. Claude Code resolves the dependency during install.
-- **Plugin `bin/` PATH wrapper** — new `bin/curdx-flow` POSIX `sh` wrapper exposes the CLI on the Claude Code plugin `bin/` PATH, so the in-session Bash tool can invoke `curdx-flow` without `npx`.
-- **Extension contract layer** — five JSON schemas (`plugin-manifest`, `skill-frontmatter`, `agent-frontmatter`, `gate-frontmatter`, `hooks`) plus `scripts/validate-plugin-contracts.mjs` and four contract test suites enforce structural correctness in CI. `prepublishOnly` runs the validator before `npm test`.
-- **`addRequiredPluginMarketplaces`** — split out of `installRequiredPlugins`. The install flow now pre-registers required companion marketplaces immediately after `curdx-flow-marketplace`, so the cross-marketplace dependency resolves cleanly during the curdx-flow plugin install step.
-- **Doctor: stale Claude Code warning + plugin error surfacing** — `curdx-flow doctor` warns when the local `claude` CLI is below `2.1.110` (the minimum version with modern plugin dependency resolution and `bin/` PATH support), and surfaces per-plugin load errors propagated from `claude plugin list --json`.
-- **`cli/lib/semver.js`** — extracted from `install-self-update.js`. Adds `isVersionAtLeast` for the doctor warning. The updater re-exports for backward compat.
-
-### Changed
-
-- **Skill spec alignment** — primary slash workflows (`init`, `start`, `spec`, `implement`, `verify`, `review`, `fast`, `debug`, `help`) gain `disable-model-invocation: true` so the model cannot auto-trigger them outside an explicit slash. Specialty skills (`epic`, `browser-qa`, `ui-sketch`, `security-audit`, `brownfield-index`) split trigger phrases into `when_to_use` and keep `description` short.
-- **`Task` → `Agent` tool naming** — every `allowed-tools`, `Task(...)` call site, and prose mention in `skills/`, `knowledge/`, and `templates/` updated to the current Claude Code `Agent` tool nomenclature.
-- **chrome-devtools MCP namespace** — `agents/flow-{qa-engineer,ui-researcher,verifier}.md` and `skills/{browser-qa,verify}` updated to `mcp__chrome_devtools__*` (underscore namespace) and the renamed tool surface (`new_page`, `navigate_page`, `take_screenshot`, `list_console_messages`, `list_network_requests`, `take_snapshot`, `lighthouse_audit`).
-- **Doctor: duplicate-MCP section** renamed from "Legacy plugin-bundled MCPs still present" to "Duplicate MCP registrations", with ownership-aware remediation (the official Context7 plugin gets `claude mcp remove --scope user` guidance, the migrated curdx-flow MCPs get the `claude plugin update` guidance).
-- **Templates** — `templates/{CONTEXT,PROJECT,progress,config}.md.tmpl` reference the current `/curdx-flow:*` slash names; `templates/config.json.tmpl` removes the retired `sketch` / `autonomous` modes and the retired `simplicity-gate` / `hard-gate` gates, and adds `wave_fail_policy`.
-- **`schemas/config.schema.json`** — new `gateName` definition enumerates the eight real gates; `gates.always_on / standard_mode / enterprise_mode` switch to `$ref` on it. Added `execution.wave_fail_policy`.
-- **`schemas/spec-state.schema.json`** — added `quickMode` boolean (the hook-controlled no-ask flag); fixed `goal` description to reference `/curdx-flow:start`.
-- **`hooks/scripts/quick-mode-guard.sh`** — stop treating the retired `mode=autonomous` as quick mode. Only `quickMode=true` denies `AskUserQuestion`. Regression test added.
-- **`agent-preamble/preamble.md`** — drops the "commands" wording and documents the quick-mode `AskUserQuestion` behavior.
-
-### Removed
-
-- **`CLAUDE.md`** — blanked. The L1 mind baseline now lives in `hooks/scripts/inject-karpathy.sh` (injected on every SessionStart) and the protocol section that the installer writes to `~/.claude/CLAUDE.md`. The repo file added drift surface without adding signal. The matching `language-rule-scan` allow-list entry is removed.
-- **`mode=autonomous`** — fully retired. The hook no longer treats it as quick mode, the templates no longer advertise it, and `schema-drift.test.js` regression-locks both.
-
-### Required
-
-- **Claude Code 2.1.110+** — the plugin dependency resolution and the plugin `bin/` PATH support require this baseline. The installer warns if your local `claude` is older.
-
-## [2.0.21] - 2026-04-23
-
-### Fixed
-
-- `cli/install-workflow.js` + `cli/install-self-update.js` — after `npm install -g @curdx/flow@latest`, the self-update restart spawned a bare `curdx-flow`, which fails under `npx` (PATH not guaranteed) or when the global bin dir isn't on PATH, surfacing as `sh: curdx-flow: command not found`. `checkAndUpdateSelf` now returns the absolute entry path of the freshly installed package, and the restart re-launches with `process.execPath` + that absolute script path. No PATH dependency, no shell involvement. Two new unit tests assert the spawn contract.
-- `README.zh.md` — corrected the `smart-ralph` credit URL. The previously listed `Nibzard/smart-ralph` 404s; the repo matching the described feature set ("Spec-driven + Ralph Wiggum loop + Claude Code plugin") is `tzachbon/smart-ralph`.
-
-## [2.1.0] - 2026-04-23
-
-### Changed (commands → skills migration; zero user-visible change)
-
-All 9 slash workflows migrate from `commands/*.md` to
-`skills/<name>/SKILL.md`, per Anthropic's recommended plugin layout.
-`/curdx-flow:<name>` still resolves to the same slash paths with the
-same arguments and output. File history is preserved via `git mv`.
-
-- `skills/implement/SKILL.md` — progressive-disclosure split to
-  `skills/implement/references/wave-execution.md`; body reduced
-  from 381 to 240 lines.
-- `/curdx-flow:verify` and `/curdx-flow:debug` — route via
-  Anthropic's native `context: fork + agent:` mechanism instead of
-  hand-rolled `Task()` dispatch prose. `agents/flow-verifier.md`
-  and `agents/flow-debugger.md` are unchanged.
-- `/curdx-flow:review --devex` — new optional flag; wires the
-  previously caller-less `gates/devex-gate.md` into the reviewer
-  dispatch.
-- `cli/install-companions.js` — split by concern into four modules
-  (`install-required-plugins.js`, `install-bundled-mcps.js`,
-  `install-recommended-plugins.js`, `install-context7-config.js`).
-  `install-companions.js` becomes a re-export barrel; callers in
-  `cli/install.js` and `cli/install-workflow.js` unchanged.
-- `package.json.files` — drops `"commands/"` (directory removed);
-  `"skills/"` retained.
-- `.gitignore` — anchors the `references/` pattern to the repo root
-  (`/references/`) so `skills/<name>/references/` progressive-disclosure
-  directories ship with the plugin.
-
-### Added (internal test coverage)
-
-- `test/skill-surface-parity.test.js` — snapshot of 14 unqualified
-  slash names (9 migrated + 5 pre-existing); pins the public
-  command surface across every refactor stage.
-- `test/schema-drift.test.js` — strict equality between
-  `schemas/*.json` mode enum and documented v2 modes.
-- `test/registry-session-start-parity.test.js` — strict equality
-  between `hooks/scripts/session-start.sh` plugin list and
-  `cli/registry.js` RECOMMENDED_PLUGINS.
-- `test/language-rule-scan.test.js` — no CJK characters outside
-  `cli/**` and an explicit small allow-list.
-- `test/install-required-plugins.test.js`,
-  `test/install-bundled-mcps.test.js`,
-  `test/install-recommended-plugins.test.js`,
-  `test/install-context7-config.test.js` — module-import smoke
-  tests for the four split install modules.
-- `test/pack-tarball-smoke.test.js` — `npm pack --dry-run`
-  assertions that `commands/` is absent, 14 SKILL.md files and
-  `skills/implement/references/` ship, and every top-level
-  infrastructure directory is present in the tarball (Acceptance
-  #18 from `docs/refactor-plan.md`).
-
-Total test count: 85 → 104, all green.
-
-### Fixed (drift cleanup)
-
-- `schemas/spec-state.schema.json`, `schemas/config.schema.json` —
-  remove unreachable `sketch` and `autonomous` mode enum values.
-  Both were retired on the user-facing surface in v2 but never
-  cleaned from the schemas (see `MIGRATION.md`).
-- `hooks/scripts/session-start.sh` — adds `chrome-devtools-mcp` to
-  the dependency-check list, closing the beta.8 drift that
-  `cli/registry.js` was supposed to prevent.
-- `agent-preamble/preamble.md` — removes an empty
-  `| Task | Guideline |` table header left behind by a prior edit.
-- `README.zh.md` — masthead paragraph rewritten from the pre-v2
-  "meta-framework" positioning to the current "discipline layer"
-  framing, parallel to `README.md`.
-- `cli/protocols-body.md` — explicit carve-out paragraph allowing
-  `cli/` installer menus to be bilingual; every other layer stays
-  English for AI / agent adaptation.
-
-### Fixed (hooks — previously pending)
-
-- `hooks/hooks.json` + `hooks/scripts/inject-karpathy.sh` — migrated the L1 baseline injector from the `InstructionsLoaded` event to `SessionStart` with `matcher: "startup|clear|compact"`. Per the Claude Code hooks docs (code.claude.com/docs/en/hooks), `InstructionsLoaded` is an observability-only event: its hook schema has no `hookSpecificOutput` field, so the injector's `{"hookSpecificOutput":{"hookEventName":"InstructionsLoaded","additionalContext":…}}` payload was rejected at session boot with `Hook JSON output validation failed — (root): Invalid input`, producing the `SessionStart:startup hook error` banner on every Claude Code launch. The `startup|clear|compact` matcher preserves the original "baseline survives compaction" intent. Also updated `docs/architecture.md` and `README.zh.md` hook-event inventories.
-
-### BREAKING
-
-- **`context7` and `sequential-thinking` moved from plugin-bundled MCPs to user-level MCPs.** Previously `.claude-plugin/plugin.json` declared both in `mcpServers`, so Claude Code auto-registered them as `plugin:curdx-flow:context7` and `plugin:curdx-flow:sequential-thinking` when the plugin installed. This is no longer the case — the `mcpServers` block is gone. Instead, `curdx-flow install` now runs `claude mcp add context7 …` + `claude mcp add sequential-thinking …` against the user's `~/.claude.json`, which keeps them as standard user-level registrations named `context7` and `sequential-thinking`.
-
-  **Why**: every early adopter who ran `claude mcp add context7 -- npx -y @upstash/context7-mcp --api-key ctx7sk-…` before installing curdx-flow ended up with *both* entries side-by-side — doubling MCP processes, making API-key routing unpredictable (random between free-tier plugin copy and paid user copy), and forcing an awkward env-var migration path. User-level registration matches the way every other MCP in the ecosystem is installed, keeps tool names standard (`mcp__context7__*` instead of `mcp__plugin_curdx-flow_context7__*`), and lets users put an `--api-key` directly in their own entry without any env-var indirection. Every agent / knowledge doc / command in the repo already calls the standard tool-name form, so this is a **zero-change-for-callers** migration.
-
-  **Migration for existing users**:
-
-  ```bash
-  # Upgrade the plugin — this removes the plugin-bundled MCPs and
-  # registers them at user-level (preserving any existing user-level entry
-  # with a custom --api-key).
-  npx @curdx/flow@latest upgrade
-
-  # Restart Claude Code so the plugin manifest reloads.
-  ```
-
-  After upgrade, `claude mcp list` will show `context7` and
-  `sequential-thinking` (user-level) but NOT `plugin:curdx-flow:context7` etc.
-  `npx @curdx/flow doctor` confirms with "user-level (standard)" in the
-  "MCP Servers" section.
-
-### Added
-
-- `cli/registry.js` exports a new `BUNDLED_MCPS` constant — the source-of-truth list of MCPs that `install` registers at user-level and `uninstall` optionally removes.
-- `cli/install.js` Step 3.5 — registers the required MCPs via `claude mcp add`. Detects pre-existing user-level entries (e.g. your hand-configured context7 with an API key) and preserves them instead of overwriting.
-- `cli/uninstall.js` Step 4.5 — asks whether to `claude mcp remove` the registered MCPs (default: no, because other tools may depend on them).
-- `cli/doctor.js` — now reports "user-level (standard)" for each required MCP when it's registered the right way, and "(legacy)" with a migration hint when the old plugin-bundled form is still active.
-
-### Changed
-
-- The "Duplicate MCP" warning in `doctor` (added in beta.11) is now framed as "Legacy plugin-bundled MCPs still present" with a concrete migration command, since the new architecture reserves duplication strictly for the upgrade-transition window.
-- `docs/getting-started.md` "Optional: use your paid context7 API key" section rewritten around the user-level path (add `--api-key` to your `claude mcp add` command) since env-var indirection is no longer the only way to route a key to the plugin copy.
-
-## [2.0.0-beta.11] - 2026-04-22
-
-### Added
-
-- `cli/doctor.js` detects when a user-level MCP in `~/.claude.json` (typically `context7` added via `claude mcp add …`) duplicates a plugin-bundled MCP from `plugin.json` (`plugin:curdx-flow:context7`). Backed by `cli/utils.js:readUserMcpConfig()` + `findDuplicateMcps()` and 3 new tests in `test/utils.test.js`.
-- `docs/getting-started.md` "Optional: use your paid context7 API key" section documenting the env-var path.
-
-## [2.0.0-beta.10] - 2026-04-21
-
-### Fixed
-
-- `cli/utils.js` — `listMcps` rewritten to handle the actual `claude mcp list` format captured from claude 2.1.117. The previous regex matched only a single kebab-case token before the first colon, so `plugin:curdx-flow:context7: npx ...` parsed as name=`plugin` and silently dropped the rest. New parser exports `{ name, plugin, fullName, status, command }` and is fixture-tested in `test/utils.test.js`.
-- `cli/doctor.js` — MCP presence check now accepts both standalone (`context7`) and plugin-bundled (`plugin:curdx-flow:context7`) registrations, with source in the status line. Fixes the same class of false-positive that bit `chrome-devtools` in beta.7. Also gated `--verbose` raw-plugin dump behind `claude` being on PATH, so it no longer runs a meaningless empty child when the CLI is absent.
-- `cli/install.js` — step counter was `1/4`..`4/4` but there are five steps; `Step 5: inject global protocols` was emitted via bare `console.log` so the progress display lied. All five steps now use `log.step(N, 5, ...)`. Also switched `⏳ Installing` and `✅ Install complete` glyphs to the `▸` / `✓` symbols used elsewhere in the project's `log.*` helpers.
-- `cli/uninstall.js` — same `⏳` → `▸` glyph normalisation.
-- `cli/protocols.js` + `cli/utils.js` + `cli/uninstall.js` — switched from `process.env.HOME || ""` to `os.homedir()`. `$HOME` is only guaranteed in interactive login shells; CI containers, some `docker exec` invocations, and non-login spawns can leave it empty, which resolved `GLOBAL_CLAUDE_MD` to `/.claude/CLAUDE.md` and broke `ensureRuntimeInPath` runtime candidate lookup.
-- `bin/curdx-flow.js` — `main()` was called unconditionally at module scope, so `import()` from a test would spawn the CLI, parse the test runner's argv, and `exit(1)`. Now guarded by the ESM direct-invocation idiom (`import.meta.url === pathToFileURL(process.argv[1]).href`). Added one real-import test.
-- `.claude-plugin/plugin.json` — `homepage` and `repository` pointed at `github.com/wdx/curdx-flow` but the authoritative remote is `github.com/curdx/curdx-flow`. Plugin-marketplace UI clicks previously 404'd. Aligned to the real owner.
-- `.github/workflows/npm-publish.yml` — bumped `actions/setup-node` from Node 20 to Node 22 LTS ahead of the 2026-06-02 Node 20 removal.
-- `scripts/release.sh` — lockstep bump of `plugin.json` + `marketplace.json` now parses both files in memory before writing either, with `git checkout -- package.json` auto-revert on failure. Previously the second file could fail to write while the first was already disk-committed.
-
-### Changed
-
-- `commands/start.md` — replaced the brittle `xargs`/`awk`/`sed` flag-parsing block with a model-directed parse that tolerates quoted strings in `$ARGUMENTS` (e.g. `my-feature "Fix user's login bug"` no longer hits `xargs: unmatched quote`).
-- `commands/init.md` — Step 5 used to say "Run `npx @curdx/flow doctor`" but the slash command runs inside Claude Code where a spawned CLI's output doesn't render cleanly. Reframed as "verify inline + suggest the user run the CLI in a separate terminal if they want the full report."
-- `commands/implement.md` — replaced `❌` emoji with `✗` to match the project's own `log.err` helper.
-- `docs/architecture.md` — Hook System section and CLI layout were **entirely fabricated** (listed non-existent hooks `pre-spec.sh` / `post-implement.sh` / `pre-verify.sh` / `post-review.sh` / `on-gate-fail.sh` and bogus paths `cli/bin/flow` / `cli/commands/install.js` / `cli/lib/…`). Rewritten to match the real `hooks/scripts/` layout (4 hooks: session-start / inject-karpathy / quick-mode-guard / stop-watcher) and real `bin/` + `cli/` paths including `cli/registry.js` and the `test/` directory.
-
-### Added
-
-- `test/utils.test.js` grew 5 fixture tests for the new `parseMcpList` against a captured `claude mcp list` output.
-- `test/cli-entrypoints.test.js` — 5 smoke tests that each dynamically-import `cli/doctor.js` / `cli/install.js` / `cli/upgrade.js` / `cli/uninstall.js` and assert the expected top-level function exports. Guards against the "deleted an import but forgot the consumer" class of regression at CI time. Plus one test that imports `bin/curdx-flow.js` now that it no longer runs `main()` at module load.
-
-### Removed (docs compliance)
-
-- Chinese trigger phrases from `skills/*/SKILL.md` descriptions (5 files). Keeping bilingual triggers violated the project's own language-separation rule (`CLAUDE.md`: "Documentation layer = English"). Semantic matching on the English phrases plus the model's own bilingual understanding covers the same invocation surface.
-
-## [2.0.0-beta.9] - 2026-04-21
-
-### Fixed (P0)
-
-- `cli/utils.js` — `findRuntime()` referenced `existsSync` without importing it; any user whose `bun`/`uv` was not on PATH hit `ReferenceError` during install or doctor.
-- `hooks/scripts/stop-watcher.sh` — `export STATE_FILE` was placed after the python heredoc, so the stop-hook execution strategy never activated. Moved the export before the heredoc.
-- `package.json` — `skills/` directory was missing from `files[]`; the 5 bundled skills were stripped from the published tarball.
-- `cli/uninstall.js` + `cli/upgrade.js` — `chrome-devtools-mcp` (added as a recommended plugin in beta.8) was missing from uninstall/upgrade lists, making it installable but uninstallable.
-- `cli/protocols.js` — `injectGlobalProtocols()` returned action `"created"` on both ternary branches, silently collapsing the append-to-existing-file case. Atomic write + corrupted-block detection added.
-
-### Changed (structural)
-
-- New `cli/registry.js` is the single source of truth for recommended plugins. `install.js`, `uninstall.js`, `upgrade.js`, and `doctor.js` all import from it.
-- `commands/start.md` and `commands/spec.md` now produce `.state.json` files that match `schemas/spec-state.schema.json` (field names: `spec_name` / `created` / `updated` / `version`; initial phase is `research`, not the undefined `created`).
-- All python heredocs inside hook scripts use quoted delimiters (`<<'PY'`) and read `STATE_FILE` via `os.environ`, closing a shell→python code-injection surface triggered by unusual spec names.
-
-### Added
-
-- First real test suite — `node --test`-based, 18 regression tests covering `cli/protocols.js`, `cli/registry.js`, and `cli/utils.js`. Wired into `package.json` `scripts.test` and the CI `publish` job so a failing test blocks `npm publish`.
-
-### Removed
-
-- `hooks/scripts/fail-tracker.sh` and its `PostToolUseFailure` registration — the counter was written but never read by any consumer (the intended pua escalation was never implemented). Can be reintroduced when the consumer exists.
-
-## [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
-- **Plugin load failure** — removed the explicit `"hooks": "./hooks/hooks.json"` declaration from `plugin.json`.
-  Claude Code auto-loads the default path `hooks/hooks.json`; declaring it explicitly caused a duplicate-hook-file
-  error. Symptom: `claude plugin list` showed `Status: ✘ failed to load`.
-- The local `claude --plugin-dir` mode does not trigger duplicate detection, so all 8 rounds of dev-time validation
-  passed; only a real marketplace install exposed this bug (lesson from the first publish).
-
-## [1.1.0] - 2026-04-20
-
-### Changed — **BREAKING**: command namespacing
-
-All 31 commands moved from `/flow-<name>` to **`/curdx-flow:<name>`** (Claude Code's native plugin namespace).
-
-**Migration map (old → new)**:
-- `/flow-init` → `/curdx-flow:init`
-- `/flow-start` → `/curdx-flow:start`
-- `/flow-research` → `/curdx-flow:research`
-- `/flow-requirements` → `/curdx-flow:requirements`
-- `/flow-design` → `/curdx-flow:design`
-- `/flow-tasks` → `/curdx-flow:tasks`
-- `/flow-spec` → `/curdx-flow:spec`
-- `/flow-implement` → `/curdx-flow:implement`
-- `/flow-verify` → `/curdx-flow:verify`
-- `/flow-review` → `/curdx-flow:review`
-- `/flow-audit` → `/curdx-flow:audit`
-- `/flow-debug` → `/curdx-flow:debug`
-- `/flow-triage` → `/curdx-flow:triage`
-- `/flow-discuss` → `/curdx-flow:discuss`
-- `/flow-party` → `/curdx-flow:party`
-- `/flow-qa` → `/curdx-flow:qa`
-- `/flow-sketch` → `/curdx-flow:sketch`
-- `/flow-security` → `/curdx-flow:security`
-- `/flow-index` → `/curdx-flow:index`
-- `/flow-doctor` → `/curdx-flow:doctor`
-- `/flow-status` → `/curdx-flow:status`
-- `/flow-switch` → `/curdx-flow:switch`
-- `/flow-help` → `/curdx-flow:help`
-- `/flow-install-deps` → `/curdx-flow:install-deps`
-- `/flow-fast` → `/curdx-flow:fast`
-- `/flow-spike` → `/curdx-flow:spike`
-- `/flow-plan-ceo` → `/curdx-flow:plan-ceo`
-- `/flow-plan-eng` → `/curdx-flow:plan-eng`
-- `/flow-plan-design` → `/curdx-flow:plan-design`
-- `/flow-plan-dx` → `/curdx-flow:plan-dx`
-- `/flow-autoplan` → `/curdx-flow:autoplan`
-
-### Changed
-- Renamed `commands/flow-*.md` to `commands/*.md` (history preserved via `git mv`)
-- Each command's `name: flow:xxx` frontmatter changed to `name: xxx`
-- 78 doc files updated for a total of 594 + 38 command references
-- Template strings that dynamically generate command names (help/switch/start/spec) updated in lockstep
-- `plugin.json` / `marketplace.json` version: 1.0.0 → 1.1.0
-
-### Unchanged (intentional)
-- `agents/flow-*.md` file paths (agent internal namespace, not commands)
-- `CHANGELOG.md` historical entries (history is not rewritten)
-- References to future Phase 6+ commands (e.g. `/curdx-flow:ship`, marked "not implemented")
-
-### Why
-Claude Code natively supports the `<plugin-name>:<command>` namespace, which avoids collisions with other plugins'
-`/flow-*` commands and makes provenance clearer. When users see `/curdx-flow:start` they immediately know it
-belongs to curdx-flow.
-
-### Migration
-Old commands no longer work. If your scripts or docs reference the old names, do a global replace
-`/flow-` → `/curdx-flow:` (note: agent file paths `agents/flow-*.md` stay unchanged).
-
-## [1.0.0] - 2026-04-20
-
-### Added — Phase 7: Polish & Release
-
-- **7 complete user docs** (`docs/*.md`):
-  - `getting-started.md` — 5-minute on-ramp
-  - `command-reference.md` — all 31 commands grouped by family
-  - `agent-reference.md` — all 24 agents (15 functional + 9 personas)
-  - `workflows.md` — 5 typical workflows (greenfield/brownfield/epic/fast/ui-heavy)
-  - `architecture.md` — technical architecture (hook system / strategy router / gate composition / extension points)
-  - `ethos.md` — design philosophy (five pillars / credits / trade-offs / anti-patterns)
-  - `troubleshoot.md` — symptom-indexed troubleshooting
-- **README upgrade** (English + Chinese) — added badges / overview list / Quick Start / credits / explicit "skipped" notes
-
-### Changed
-- `plugin.json` version: 0.6.0 → **1.0.0** (Polish complete = official 1.0 release)
-
-### Design Decision
-- v1.0 marks "feature-complete + publishable"
-- Subsequent versioning is semantic:
-  - 1.0.x patch — doc fixes, hook fixes
-  - 1.x.0 minor — new commands / new agents / new gates
-  - 2.0.0 major — breaking changes (e.g. frontmatter schema change)
-- **Phase 6 intentionally skipped** (ship/land/canary/retro) — low ROI for private repos
-
-## [0.6.0] - 2026-04-19
-
-### Added — Phase 5: Tools & UI
-
-- **4 tool-class agents** (`agents/*.md`):
-  - `flow-qa-engineer` — runs real-browser QA via the chrome-devtools MCP, capturing bugs / performance / accessibility
-  - `flow-ux-designer` — invokes the frontend-design skill to generate HTML variants
-  - `flow-security-auditor` — OWASP Top 10 + STRIDE + npm audit
-  - `flow-ui-researcher` — UI pattern research; scans codebase + WebSearch + screenshots
-- **2 new gates** (`gates/*.md`):
-  - `security-gate` — SR blocking red lines (hard-coded credentials, injection, sensitive logging) + SW warnings + SM mandatory items
-  - `devex-gate` — 8 dimensions (naming/comments/structure/error-handling/setup/types/tests/dev loop)
-- **4 tool commands**:
-  - `/curdx-flow:qa [--url=...]` — dispatches Oliver for browser QA
-  - `/curdx-flow:sketch "<description>"` — dispatches Emma to generate UI variants
-  - `/curdx-flow:security` — dispatches Serena for security audit
-  - `/curdx-flow:index [--force]` — scans a brownfield codebase and generates an index
-- **5 Planning Review commands** (inherited from gstack and extended):
-  - `/curdx-flow:plan-ceo` — strategic-layer review (scope / ROI / opportunity cost)
-  - `/curdx-flow:plan-eng` — engineering-layer review (architecture lock / risks)
-  - `/curdx-flow:plan-design` — UI/UX review (accessibility / design system)
-  - `/curdx-flow:plan-dx` — DevEx review (8-dimension scoring)
-  - `/curdx-flow:autoplan` — runs the 4 reviews above in parallel and aggregates findings
-- **New knowledge doc** (`knowledge/planning-reviews.md`) — 4-dimension methodology + when to use + when to skip
-
-### Changed
-- `plugin.json` version: 0.5.1 → 0.6.0
-
-## [0.5.1] - 2026-04-19
-
-### Added — Wave Execution complete (Phase 2 follow-up)
-
-- **`knowledge/wave-execution.md`** — DAG analysis algorithm, parallel dispatch mechanism,
-  conflict detection (pre + post), failure strategy, configuration notes, 3 file-conflict scenarios
-- **`commands/curdx-flow:implement.md`** wave section expanded from a 20-line concept sketch
-  to a complete 6-step execution flow: DAG analysis → pre-conflict check → single-message
-  parallel Task dispatch → result aggregation → failure handling → progress feedback
-
-### Changed
-- `plugin.json` version: 0.5.0 → 0.5.1
-
-## [0.5.0] - 2026-04-19
-
-### Added — Phase 4: Advanced (Triage / Party / Debug / Personas)
-
-- **2 new functional agents**:
-  - `flow-triage-analyst` — Epic vertical-slice decomposition, splitting by user value (not technical layer); produces a dependency graph + frozen shared interfaces
-  - `flow-debugger` — systematic 4-stage debugging (root cause → pattern → hypothesis → fix); ≥3 failures triggers an architecture challenge
-- **9 persona agents** (`agents/persona-*.md`) — BMAD-style personalization:
-  - Mary (Senior Analyst → flow-researcher)
-  - John (Product Manager → flow-product-designer)
-  - Winston (Architect → flow-architect)
-  - Amelia (Developer → flow-executor)
-  - Rachel (Code Reviewer → flow-reviewer)
-  - David (Debugger → flow-debugger)
-  - Oliver (QA Engineer → flow-edge-hunter + Phase 5+ flow-qa-engineer)
-  - Serena (Security Auditor → Phase 5+ flow-security-auditor)
-  - Emma (UX Designer → Phase 5+ flow-ux-designer)
-- **4 new commands**:
-  - `/curdx-flow:triage "<epic goal>"` — dispatches flow-triage-analyst to slice the Epic vertically
-  - `/curdx-flow:discuss` — captures key decisions (D-NN), writes to STATE.md + .progress.md
-  - `/curdx-flow:party <personas...> "<question>"` — multiple personas reason in parallel and independently (true multi-agent, not single-LLM role-play)
-  - `/curdx-flow:debug "<bug>"` — dispatches David / flow-debugger for systematic 4-stage debugging
-- **2 new knowledge docs**:
-  - `knowledge/epic-decomposition.md` — vertical slice vs horizontal layer, dependency types, shared-interface freeze
-  - `knowledge/systematic-debugging.md` — full 4-stage methodology + forbidden anti-patterns
-
-### Changed
-- `plugin.json` version: 0.4.0 → 0.5.0
-
-## [0.4.0] - 2026-04-19
-
-### Added — Phase 3: Gates & Review
-
-- **6 core gates** (`gates/*.md`) — composable quality-gate definitions:
-  - `karpathy-gate` (always-on, blocking) — code-level checks for the 4 principles
-  - `verification-gate` (always-on, blocking) — completion claims require fresh evidence
-  - `tdd-gate` (standard, blocking) — RED → GREEN → YELLOW enforcement + exemption paths
-  - `coverage-audit-gate` (standard, blocking) — 4-source (FR/AD/Research/D-NN) coverage audit
-  - `adversarial-review-gate` (enterprise, warning) — zero-findings forbidden + minimum findings across 3 categories
-  - `edge-case-gate` (enterprise, warning) — 7 categories of edge cases + test-gap checklist
-- **4 review agents** (`agents/*.md`):
-  - `flow-verifier` — goal-backward verification; detects stubs / fake completions
-  - `flow-reviewer` — Two-Stage Review (Stage 1 spec compliance + Stage 2 code quality)
-  - `flow-adversary` — adversarial review; 6 dimensions × 2 rounds of sequential-thinking
-  - `flow-edge-hunter` — hunts 7 categories of edge cases; generates a test-gap checklist
-- **3 new commands** (`commands/*.md`):
-  - `/curdx-flow:verify` — goal-backward verification (dispatches flow-verifier)
-  - `/curdx-flow:review [--adversarial|--edge-case|--both]` — Two-Stage Review with optional adversarial / edge-case scan
-  - `/curdx-flow:audit` — multi-source coverage audit (tasks-vs-specs cross-check)
-- **New knowledge doc** (`knowledge/two-stage-review.md`) — Stage 1/2 design principles + typical anti-patterns
-
-### Changed
-- `plugin.json` version: 0.3.0 → 0.4.0
-
-## [0.3.0] - 2026-04-19
-
-### Added — Phase 2: Execution Engine
-
-- **flow-executor agent** (`agents/flow-executor.md`) — core execution agent:
-  - Executes a single task with POC-First + TDD
-  - Verify must pass
-  - Atomic commits in conventional-commit format
-  - Emits `TASK_COMPLETE` / `TASK_FAILED` / `ALL_TASKS_COMPLETE` markers
-  - 5-round retry mechanism (pua-style pressure escalation)
-- **2 new knowledge docs**:
-  - `knowledge/execution-strategies.md` — 4 execution strategies in detail (linear / subagent / stop-hook / wave / auto)
-  - `knowledge/atomic-commits.md` — atomic-commit rules + conventional-commit format
-- **2 new hook scripts**:
-  - `hooks/scripts/stop-watcher.sh` — StopHookLoop implementation (detects `ALL_TASKS_COMPLETE`, tracks failure count, prevents infinite loops)
-  - `hooks/scripts/quick-mode-guard.sh` — Quick Mode blocks AskUserQuestion (so the autonomous loop does not stall)
-- **`hooks.json`** registers the new hooks:
-  - `Stop` → stop-watcher.sh
-  - `PreToolUse(AskUserQuestion)` → quick-mode-guard.sh
-- **3 new commands**:
-  - `/curdx-flow:implement` — main execute command, with Strategy Router (`--strategy=auto|linear|subagent|stop-hook|wave`, `--task=X.Y`, `--quick`)
-  - `/curdx-flow:fast` — skip the spec, implement directly (one-shot tasks)
-  - `/curdx-flow:spike` — feasibility experiment (2–5 small tests to validate a hypothesis)
-
-### Changed
-- `plugin.json` version: 0.2.0 → 0.3.0
-
-## [0.2.0] - 2026-04-19
-
-### Added — Phase 1: Spec Engine
-
-- **5 spec templates** (`templates/*.tmpl`):
-  - `research.md.tmpl` — research report structure
-  - `requirements.md.tmpl` — user stories + acceptance criteria + FR/NFR
-  - `design.md.tmpl` — architecture decisions + component boundaries + mermaid diagrams
-  - `tasks.md.tmpl` — POC-First 5 Phases + coverage audit
-  - `progress.md.tmpl` — progress log + learnings
-- **3 JSON Schemas** (`schemas/*.schema.json`):
-  - `spec-state.schema.json` — cross-session state
-  - `config.schema.json` — project configuration
-  - `spec-frontmatter.schema.json` — spec file YAML frontmatter
-- **2 knowledge docs** (`knowledge/*.md`):
-  - `spec-driven-development.md` — SDD methodology
-  - `poc-first-workflow.md` — POC-First 5 Phases
-- **4 functional agents** (`agents/*.md`):
-  - `flow-researcher` — deep research (context7 + claude-mem + sequential-thinking ≥5 rounds + WebSearch)
-  - `flow-product-designer` — user stories + acceptance criteria + FR/NFR
-  - `flow-architect` — architecture design (sequential-thinking ≥8 rounds + context7 to validate technology choices)
-  - `flow-planner` — POC-First decomposition + multi-source coverage audit
-- **7 new commands** (`commands/*.md`):
-  - `/curdx-flow:start` — intelligent entry (new spec / resume spec)
-  - `/curdx-flow:switch` — switch the active spec
-  - `/curdx-flow:research` — dispatches flow-researcher
-  - `/curdx-flow:requirements` — dispatches flow-product-designer
-  - `/curdx-flow:design` — dispatches flow-architect
-  - `/curdx-flow:tasks` — dispatches flow-planner
-  - `/curdx-flow:spec` — runs the 4 phases sequentially in one shot
-
-### Changed
-- `plugin.json` version: 0.1.0 → 0.2.0
-
-## [0.1.0] - 2026-04-19
-
-### Added — Phase 0: Foundation
-
-- Project skeleton for Claude Code plugin
-- `plugin.json` with inline `mcpServers` declaring 3 auto-installed MCPs:
-  - `context7` — latest documentation fetcher
-  - `sequential-thinking` — structured reasoning
-  - `chrome-devtools` — browser automation
-- `marketplace.json` for future plugin market publishing
-- Hook system:
-  - `SessionStart` — dependency check + project state load
-  - `InstructionsLoaded` — inject Karpathy L1 baseline
-  - `PostToolUseFailure` — fail counter (pua integration prep)
-- Shared agent preamble (`agent-preamble/preamble.md`) — enforces `context7` / `sequential-thinking` / `claude-mem` usage in all agents
-- Core commands:
-  - `/curdx-flow:init` — initialize `.flow/` project structure
-  - `/curdx-flow:install-deps` — one-click install of recommended plugins (pua, claude-mem, frontend-design)
-  - `/curdx-flow:doctor` — dependency health check
-  - `/curdx-flow:status` — project & spec status
-  - `/curdx-flow:help` — smart help
-- Document templates (`templates/*.tmpl`) for PROJECT/CONTEXT/STATE/ROADMAP/config
-- Knowledge base (`knowledge/karpathy-guidelines.md`) for agents to `@`-reference
-- CLAUDE.md with L1-L4 rules
-- README (English + Chinese) + LICENSE (MIT)
+- aligned the public docs surface with the current skill-first plugin layout
+- kept thin entry docs while moving detailed workflow logic into skill references
+- locked command summaries to workflow skill descriptions with tests