@curdx/flow 3.0.0 → 3.2.0

package/CHANGELOG.md

@@ -1,97 +1,48 @@
 # Changelog
 
-## 3.0.0
+All notable changes to `@curdx/flow` are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/) and the project follows [Semantic Versioning](https://semver.org/).
 
-The modernization release. No breaking changes for end users — internal
-manifest reshape, schema realignment, and platform-feature uptake.
+## 3.2.0 — 2026-04-26
 
-- aligned `schemas/agent-frontmatter.schema.json` with the canonical field
-  list documented at <https://code.claude.com/docs/en/sub-agents.md>; reversed
-  the P1 contract validator's misjudgement that flagged `effort`,
-  `maxTurns`, `background`, and `color` as non-canonical, and replaced it
-  with a strict-mode threshold check on combined `description + when_to_use`
-  length (1536-char skill listing cap)
-- collapsed `plugin.json#agents` from a 17-entry explicit array to the
-  directory pointer `"./agents/"`, matching `skills` and `outputStyles` and
-  eliminating per-agent manifest drift
-- explicitly forbade plugin-ignored fields (`hooks`, `mcpServers`,
-  `permissionMode`) at schema validation time so misconfigurations surface
-  before install instead of being silently dropped at runtime
-- shipped a plugin root `bin/` directory: `bin/curdx-flow-state` emits a
-  one-line snapshot of the active spec and is added to the Bash tool's
-  `PATH` whenever the plugin is enabled (Claude Code v2.1.91+); agents,
-  skills, and hooks can call it as a bare command instead of duplicating
-  Python/Bash snippets
-- added `subagentStatusLine.refreshInterval: 5` so the worktree-aware
-  status line refreshes automatically (Claude Code Week 15 statusline
-  feature)
-- shipped two new output styles, `CurdX Spec Mode` (verbose, artifact-first)
-  and `CurdX Fast Mode` (low-ceremony surgical work), alongside the
-  default evidence-first style
-- expanded the test suite from 10 to 110+ assertions across five new files:
-  every skill frontmatter parses with name/description/length contract,
-  every hook script invoked from `hooks.json` is executable + bash-parsable,
-  every output style has frontmatter + non-trivial body, the
-  `RECOMMENDED_PLUGINS` registry stays in lockstep with `session-start.sh`,
-  and every plugin `bin/` executable parses + runs without crashing
-- restored the README and CHANGELOG that were dropped during the
-  P1 slate-clearing (commits 0dee423 / 8b14aba) and updated them to v3.0.0
+### Added
 
-## 2.3.11
+- **Version-aware install** — `flow install` now detects already-installed items with newer versions available upstream and presents a third state `↑ installed v3.0.0 → v3.2.3 available` in the multiselect. Items with updates are pre-selected by default alongside not-installed items, so a single Enter ships "install missing + upgrade outdated".
+- **Smart dispatch** — selected items route to the right operation:
+  - not installed → `install` (full)
+  - update available → `update` (incremental, via `claude plugin update <id>`)
+  - already installed but selected → reinstall confirmation prompt (uninstall + install)
+- **Marketplace cache refresh** — install flow runs `claude plugin marketplace update <name>` for each pkg's marketplace before reading `latestVersion`. Skipped per-marketplace if its cache mtime is within 1 hour. New flag `--no-refresh` to opt out entirely (CI / offline use).
+- **`flow status --json` enriched** — now includes `installedVersion`, `latestVersion`, and `updateAvailable` fields for each item, so external scripts can detect upgrade candidates without parsing the multiselect UI.
+- **`Pkg.installedVersion` / `Pkg.latestVersion` / `Pkg.marketplaces`** — optional methods on the registry interface. Implemented for `pua` and `claude-mem` (the two items whose marketplaces declare `version` in `.claude-plugin/marketplace.json`). Other items gracefully fall back to the boolean installed/not-installed display when versions aren't available.
 
-- internal-only patches; no user-facing behavior change
+### Notes
 
-## 2.3.10
+Of the 6 bundled items, only `pua` and `claude-mem` expose comparable versions. `chrome-devtools-mcp` and `frontend-design` (Anthropic official marketplace) don't declare `version` in marketplace metadata and so always render as "installed" without version. Both MCP servers (`sequential-thinking`, `context7`) have no installed-version concept (`npx -y` auto-fetches latest each launch / remote HTTP) and behave the same way.
 
-- auto-heal legacy Context7 state on upgrade; doctor reports "all healthy" once
-  the legacy user-level Context7 MCP entry has been reconciled
+## 3.1.0 — 2026-04-26
 
-## 2.3.9
+Major rewrite preserving the same goal (one-command installer for Claude Code plugins and MCP servers) with a cleaner internal architecture and broader coverage.
 
-- aligned Claude runtime hooks with the official auto-discovery contract
-  (`hooks.json` is loaded automatically; manifest `hooks` field is reserved
-  for non-standard locations only) and resolved the `context7-plugin
-  unknown version` install failure that blocked upgrades
+### Added
 
-## 2.3.8
+- **Bilingual UI** — every interactive run starts with a 中文 / English picker; default is auto-detected from `$LANG`. No config file is written.
+- **Two new MCP servers**:
+  - `sequential-thinking` (`@modelcontextprotocol/server-sequential-thinking`)
+  - `context7` (Upstash HTTP MCP) with optional API key prompt at install time
+- **`citty` subcommand mode** — `npx @curdx/flow install|uninstall|update|status` for non-interactive / CI use, alongside the original interactive menu.
+- **`status --json`** — machine-readable install state for scripting.
+- **`install --all --yes`** — non-interactive bulk install.
+- **`Pkg` registry abstraction** (`src/registry/types.ts`) — every installable item declares `isInstalled / install / uninstall / update / prereqCheck / configPrompts` once, and the four flows (install / uninstall / update / status) use the same interface. Future additions are a single file in `src/registry/`.
+- **Idempotency layer** — every flow pre-checks state via cached `claude plugin list --json` / `claude mcp list` parsing, so re-running after a partial install is safe.
+- **`prereqCheck` for `chrome-devtools-mcp`** — detects Node ≥ 20.19 and a locally installed Chrome before attempting install.
+- **GitHub Actions CI + Release workflows** — Node 20 + 22 matrix on PRs; `v*` tag triggers `npm publish --provenance --access public` and an auto-noted GitHub Release.
 
-- taught `doctor` to detect dirty CurDX-Flow source checkouts, so plugin developers immediately see when Claude cannot possibly be running their latest local edits yet
-- surfaced bundled source repo metadata (`branch`, `shortSha`, `exactTag`, `dirty`) alongside bundled plugin body version in diagnostics and JSON output
-- documented the reinstall workflow for "same version, but local source changed" plugin-development scenarios
+### Changed
 
-## 2.3.7
+- `@clack/prompts` upgraded **0.8.x → 1.2.x** (Node ≥ 20.12 required).
+- Bundler: now `tsup` producing a single 35 KB ESM file (`dist/index.mjs`) with shebang banner — no more multi-file dist.
+- Plugin registry now uses the **real marketplace name** from `.claude-plugin/marketplace.json`, not the GitHub repo path. Specifically `chrome-devtools-mcp` lives in marketplace `chrome-devtools-plugins`, not `chrome-devtools-mcp`.
 
-- taught `doctor` to detect source/package-vs-installed plugin version drift so local plugin development and release validation no longer silently run against stale Claude plugin cache state
-- exposed bundled plugin body version in the runtime report and machine-readable doctor payload for automation consumers
-- documented the reinstall/restart recovery path when Claude is still loading an older CurDX-Flow build
+### Removed
 
-## 2.3.6
-
-- taught `doctor` to inspect file-based Claude Code managed settings and apply them at the correct highest-precedence layer for CurDX-Flow plugin options
-- upgraded the `doctor --json` contract to v2 so wrappers can distinguish inspected `managed-file` scope from uninspected server-managed / MDM / CLI overrides
-- added report and workflow coverage for managed-settings fragments, invalid managed JSON, and managed-vs-local/project/user precedence
-
-## 2.3.5
-
-- added a versioned `doctor --json` contract for CI/wrappers, including applied-fix metadata and explicit settings-inspection scope metadata
-- added CLI-level regression coverage so `doctor --json` stays silent except for JSON stdout and exit code
-- locked runtime env consumer drift checks against manifest `userConfig` keys and the actual bundled hook/monitor scripts
-
-## 2.3.1
-
-- expanded `doctor` to report CurDX-Flow's bundled main-thread agent, monitor surface, and plugin option defaults
-- documented where Claude Code stores CurDX-Flow non-sensitive `userConfig` values in `pluginConfigs`
-- added troubleshooting guidance for stop-hook blocking and plugin monitor behavior
-
-## 2.3.0
-
-- added a default `flow-orchestrator` main-thread agent through plugin-level `settings.json`
-- 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
-
-## 2.2.4
-
-- 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
+- `~/.curdx-flow/config.json` — language preference is no longer persisted; the picker runs every interactive session.

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 wdx
+Copyright (c) 2026 bydongxin
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,145 +1,44 @@
-# CurdX-Flow
+# @curdx/flow
 
-> Stop Claude Code from faking "done".
-> Spec-driven workflow, goal-backward verification, and Karpathy discipline for real feature delivery.
-
-[![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)
-[![Plugin](https://img.shields.io/badge/claude--code-plugin-blue)](https://code.claude.com)
-
-CurdX-Flow is a skill-first Claude Code plugin. The public surface stays small:
-11 slash commands, 5 auto-invoked skills, 17 internal agents, and a thin set of
-runtime contracts. The heavy workflow detail lives in `skills/*/references/`,
-`knowledge/`, and the `agent-preamble/`.
-
-v3.0.0 is the modernization release: the plugin manifest, agent/skill schemas,
-and contract validator are aligned with the latest Claude Code plugin spec
-([sub-agents.md](https://code.claude.com/docs/en/sub-agents.md),
-[plugins-reference.md](https://code.claude.com/docs/en/plugins-reference.md)),
-and the plugin now ships a `bin/` directory whose executables are added to the
-Bash tool's `PATH` while CurdX-Flow is enabled (Claude Code v2.1.91+).
-
-## Install
-
-```bash
-npx @curdx/flow install --all
-```
-
-Requires modern Claude Code and Node 18+. The install flow registers the plugin,
-required reasoning/doc tools, and recommended companion plugins. Run
-`npx @curdx/flow doctor` after install if anything looks off. For CI or wrapper
-automation, use `npx @curdx/flow doctor --json`, which reports file-based
-managed settings at their correct precedence layer.
-
-After restart, CurdX-Flow routes the main thread through `flow-orchestrator`
-by default and starts the bundled `.flow` progress monitor in interactive
-Claude Code sessions.
-
-## 11 slash commands, that's it
-
-```text
-/curdx-flow:init           Initialize the .flow scaffold for the current repository.
-/curdx-flow:start          Create, resume, list, or switch the active feature spec.
-/curdx-flow:status         Show active spec health, progress, artifacts, and recovery hints.
-/curdx-flow:spec           Generate or refresh research, requirements, design, and tasks for the active spec.
-/curdx-flow:implement      Execute active-spec tasks with strategy routing and atomic progress.
-/curdx-flow:cancel         Cancel the active execution loop or delete a spec with explicit confirmation.
-/curdx-flow:verify         Verify the active spec against code, tests, and browser evidence.
-/curdx-flow:review         Run two-stage review with optional adversarial, edge-case, and DevEx passes.
-/curdx-flow:fast           Execute a one-shot small task without creating a spec.
-/curdx-flow:debug          Debug a bug or failing test with the root-cause workflow.
-/curdx-flow:help           Show command detail, workflow guidance, and troubleshooting.
-```
-
-Plus 5 auto-invoked skills: `/curdx-flow:epic`, `/curdx-flow:browser-qa`,
-`/curdx-flow:ui-sketch`, `/curdx-flow:security-audit`,
-`/curdx-flow:brownfield-index`.
+Interactive installer for Claude Code plugins and MCP servers.
 
 ## Quick start
 
 ```bash
-cd ~/your-project
-claude
-/curdx-flow:init
-/curdx-flow:start jwt-auth "Add JWT authentication to the REST API"
-/curdx-flow:spec
-/curdx-flow:implement
-/curdx-flow:verify
-/curdx-flow:review
-
-# Main artifacts:
-#   .flow/specs/jwt-auth/verification-report.md
-#   .flow/specs/jwt-auth/review-report.md
+npx @curdx/flow
 ```
 
-This produces a durable audit trail instead of a chat-only claim of completion.
-
-## What ships
-
-- 11 slash commands and 5 auto-invoked skills
-- 17 internal agents wired through `flow-orchestrator`
-- 3 output styles: default, `CurdX Spec Mode`, `CurdX Fast Mode`
-- a `flow-state` background monitor that streams spec progress changes back into Claude
-- 9 composable gates and 14 knowledge docs referenced by every agent
-- 4 execution strategies for `/curdx-flow:implement` (linear, subagent, stop-hook, wave)
-- a plugin `bin/` directory: `curdx-flow-state` is PATH-mounted while the plugin is enabled, so agents and hooks can call it as a bare command
-- thin public docs, thick supporting references
+On first run you'll be asked to pick a language (中文 / English). Then choose what to install, update, uninstall, or just check status.
 
-## Plugin layout
+## Subcommands
 
+```bash
+npx @curdx/flow              # interactive menu
+npx @curdx/flow install      # interactive install (current state-aware)
+npx @curdx/flow install --all --yes
+npx @curdx/flow uninstall
+npx @curdx/flow update
+npx @curdx/flow status
+npx @curdx/flow status --json
+npx @curdx/flow --lang en    # override language
 ```
-.claude-plugin/
-  plugin.json          plugin manifest (agents/skills/outputStyles point at directories, not file lists)
-  marketplace.json
-agents/                17 specialist subagents
-skills/                16 skills (commands + auto-invoked)
-hooks/
-  hooks.json           SessionStart, UserPromptSubmit, Stop, SubagentStop, …
-  scripts/             shell handlers (sourced helpers in common.sh, invoked scripts +x)
-gates/                 9 composable review gates
-knowledge/             14 long-form references @-included by agents
-monitors/
-  monitors.json        background watchers (flow-state)
-output-styles/         default + spec-mode + fast-mode
-agent-preamble/        shared preamble all agents @-include
-schemas/               JSON Schemas for plugin manifest, agent / skill frontmatter, hooks
-templates/             scaffold templates the CLI installer copies into .flow/
-bin/                   plugin executables on PATH (curdx-flow-state, plus the npm CLI bin)
-cli/                   npm-published CLI installer (install / upgrade / doctor / uninstall)
-test/                  node:test suite + plugin contract validator regression baseline
-scripts/               release.sh + validate-plugin-contracts.mjs + npm-dist-tag
-```
-
-## Compatibility notes
 
-- **Skill shell execution** — CurdX-Flow skills rely on Bash tool calls. If your
-  Claude Code settings have `disableSkillShellExecution: true`, the spec
-  workflow will not run; remove that setting or scope it away from CurdX-Flow.
-- **Plugin agent fields** — agent frontmatter follows the canonical fields
-  documented at
-  [sub-agents.md](https://code.claude.com/docs/en/sub-agents.md). The fields
-  `hooks`, `mcpServers`, and `permissionMode` are silently ignored by the
-  Claude Code plugin runtime; CurdX-Flow's schema rejects them at validation
-  time so misconfigurations surface before install.
-- **Plugin executables on PATH** — the plugin root `bin/` directory lands on
-  the Bash tool's `PATH` while CurdX-Flow is enabled (Claude Code v2.1.91+).
+## What it installs
 
-## Development
+| id | type | source |
+| --- | --- | --- |
+| `pua` | plugin | `tanweai/pua` → `pua@pua-skills` |
+| `claude-mem` | plugin | `thedotmack/claude-mem` |
+| `chrome-devtools-mcp` | plugin | `ChromeDevTools/chrome-devtools-mcp` |
+| `frontend-design` | plugin | `claude-plugins-official` (built-in) |
+| `sequential-thinking` | mcp | `@modelcontextprotocol/server-sequential-thinking` |
+| `context7` | mcp | HTTP — `https://mcp.context7.com/mcp` (optional API key) |
 
-```bash
-npm test                              # 110+ tests
-npm run validate:contracts            # lenient validator
-npm run validate:contracts:strict     # strict validator (skill description-length cap is fatal)
-claude plugin validate .              # ground-truth gate
-```
+## Requirements
 
-`scripts/release.sh major|minor|patch` bumps `package.json`, `plugin.json`,
-`marketplace.json`, and the lockfile in lockstep, commits, tags, and pushes.
-The tag push triggers `.github/workflows/npm-publish.yml`.
+- Node.js >= 20.12
+- `claude` CLI installed and on `PATH` (this tool shells out to `claude plugin` and `claude mcp`)
 
-## Notes
+## License
 
-- `enterprise` mode turns on adversarial, edge-case, security, and DevEx gates.
-- `subagent` is serial; `wave` is the parallel execution strategy.
-- Headless usage should favor `claude --bare -p` and explicit `--plugin-dir`,
-  `--settings`, and `--mcp-config` wiring.
+MIT