@curdx/flow 1.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wdx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,161 @@
+# 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.
+
+[![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-purple)](https://code.claude.com)
+[![Chinese (中文)](https://img.shields.io/badge/docs-Chinese%20(中文)-red)](./README.zh.md)
+
+---
+
+## What It Is
+
+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).
+
+**It doesn't reinvent wheels. It orchestrates good ones.**
+
+## At a Glance (v1.1.0)
+
+- **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:
+
+| 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
+
+### Recommended: one-shot via npm (works in any project, fast on Chinese npm mirrors)
+```bash
+# Interactive (picks recommended plugins)
+npx @curdx/flow install
+
+# Or install everything automatically
+npx @curdx/flow install --all
+
+# Health check
+npx @curdx/flow doctor
+```
+
+### 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
+```
+
+3 MCPs auto-install. Then run:
+
+```
+/curdx-flow:install-deps    # interactive install of pua / claude-mem / frontend-design
+/curdx-flow:doctor          # verify health
+/curdx-flow:init            # initialize your project
+```
+
+See [`docs/getting-started.md`](./docs/getting-started.md) for a 5-minute walkthrough.
+
+## Quick Start
+
+```bash
+# 1. In your project
+/curdx-flow:init
+
+# 2. Start a feature
+/curdx-flow:start jwt-auth "Add JWT authentication to REST API"
+
+# 3. Generate full spec (research → requirements → design → tasks)
+/curdx-flow:spec
+
+# 4. Execute (auto-picks best strategy)
+/curdx-flow:implement
+
+# 5. Verify + review
+/curdx-flow:verify
+/curdx-flow:review
+
+# Done. git push.
+```
+
+For more scenarios (brownfield, epic, fast, UI-heavy), see [`docs/workflows.md`](./docs/workflows.md).
+
+## Five Pillars
+
+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)
+
+See [`docs/ethos.md`](./docs/ethos.md) for design philosophy.
+
+## Documentation
+
+| 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 |
+
+## What's Not Here (Yet)
+
+**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.
+
+See [`CHANGELOG.md`](./CHANGELOG.md) for full version history.
+
+## Credits
+
+CurDX-Flow is a distillation, not an invention. Deeply indebted to:
+
+- [**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
+- [**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)
+
+## License
+
+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
+
+---
+
+_CurDX = "Current Developer eXperience" in the AI-coding era._

package/README.zh.md

@@ -0,0 +1,149 @@
+# CurDX-Flow
+
+> **Claude Code 的 AI 工程工作流元框架**
+> 把 Claude Code 变成有工程纪律的 AI 团队 — 编排 MCP 和插件，强制 Karpathy 4 原则，用规格驱动工作流交付高质量软件。
+
+[![Version](https://img.shields.io/badge/version-1.1.0-blue)](./CHANGELOG.md)
+[![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
+[![Plugin](https://img.shields.io/badge/claude--code-plugin-purple)](https://code.claude.com)
+[![English](https://img.shields.io/badge/doc-English-red)](./README.md)
+
+---
+
+## 是什么
+
+CurDX-Flow 是一个 Claude Code 插件，把 6 个验证过的 AI 工程工作流（Karpathy guidelines / BMAD / get-shit-done / gstack / smart-ralph / superpowers）蒸馏成一个可组合系统，然后把基础设施委托给专业的第三方插件（context7 / sequential-thinking / chrome-devtools / claude-mem / pua / frontend-design）。
+
+**不重造轮子。编排好轮子。**
+
+## 一览（v1.1.0）
+
+- **31 个命令** — 初始化 / 研究 / 设计 / 执行 / 验证 / 审查 / 调试 / QA / 安全 / ...
+- **24 个代理** — 15 职能 + 9 人格（Mary / John / Winston / Amelia / Rachel / David / Oliver / Serena / Emma）
+- **8 个可组合 Gate** — Karpathy / Verification / TDD / Coverage / Adversarial / Edge-Case / Security / DevEx
+- **4 种执行策略** — linear / subagent / stop-hook / wave（自动路由）
+- **10 个知识文档** — 规格驱动 / POC-First / 原子提交 / 执行策略 / ...
+- **5 个 hook 事件** — SessionStart / InstructionsLoaded / Stop / PreToolUse / PostToolUseFailure
+- **3 个自动安装的 MCP** — context7 / sequential-thinking / chrome-devtools
+- **优雅降级** — 依赖缺失时进入 fallback 模式并清晰告知
+
+## 为什么用
+
+现有 AI 编程工作流常见问题：
+
+| 问题 | CurDX-Flow 的答案 |
+|-----|-----------------|
+| 上下文腐烂（长会话质量下降） | Subagent 隔离 + stop-hook 循环 + claude-mem |
+| 无工程纪律（AI 跳步、幻觉） | Karpathy L1 + verification-gate + TDD-gate |
+| 最佳实践分散 | 6 个工作流蒸馏到一个元框架 |
+| 验证薄弱（无证据声称"完成"） | 目标反向验证 + 禁用词检测 |
+| 单视角决策 | Party Mode（真正多代理，非角色扮演）+ 对抗审查 |
+
+## 安装
+
+### 从 marketplace（发布后）
+```
+/plugin marketplace add wdx/curdx-flow
+/plugin install curdx-flow
+```
+
+### 本地 dev
+```bash
+git clone https://github.com/wdx/curdx-flow
+claude --plugin-dir ./curdx-flow
+```
+
+3 个 MCP 自动装。然后运行：
+
+```
+/curdx-flow:install-deps    # 交互式安装 pua / claude-mem / frontend-design
+/curdx-flow:doctor          # 验证健康
+/curdx-flow:init            # 初始化你的项目
+```
+
+详细教程见 [`docs/getting-started.md`](./docs/getting-started.md)（5 分钟上手）。
+
+## 快速开始
+
+```bash
+# 1. 在你的项目
+/curdx-flow:init
+
+# 2. 启动一个功能
+/curdx-flow:start jwt-auth "给 REST API 加 JWT 认证"
+
+# 3. 生成完整规格（研究 → 需求 → 设计 → 任务）
+/curdx-flow:spec
+
+# 4. 执行（自动选最佳策略）
+/curdx-flow:implement
+
+# 5. 验证 + 审查
+/curdx-flow:verify
+/curdx-flow:review
+
+# 完成。git push.
+```
+
+更多场景（棕地 / Epic / Fast / UI 重）见 [`docs/workflows.md`](./docs/workflows.md)。
+
+## 五根支柱
+
+1. **Mind（L1 基线）** — Karpathy 4 原则 + 必用工具规则 + 三条红线
+2. **Spec（规格）** — 研究 → 需求 → 设计 → 任务（可伸缩，4 文件 lite 到 12 文件 enterprise）
+3. **Agents（代理）** — 15 职能 + 9 人格（Mary / John / Winston / ...）
+4. **Flow（流程）** — 4 种执行策略，自动路由
+5. **Memory（记忆）** — claude-mem（隐式）+ `.flow/STATE.md`（显式决策 D-NN）
+
+设计哲学详见 [`docs/ethos.md`](./docs/ethos.md)。
+
+## 文档
+
+| 文档 | 何时读 |
+|-----|------|
+| [`docs/getting-started.md`](./docs/getting-started.md) | 首次使用，5 分钟上手 |
+| [`docs/command-reference.md`](./docs/command-reference.md) | 31 个命令完整参考 |
+| [`docs/agent-reference.md`](./docs/agent-reference.md) | 24 个代理 + 人格 |
+| [`docs/workflows.md`](./docs/workflows.md) | 5 种典型场景（greenfield/brownfield/epic/fast/UI） |
+| [`docs/architecture.md`](./docs/architecture.md) | 内部设计（给扩展者） |
+| [`docs/ethos.md`](./docs/ethos.md) | 设计决策的理由 |
+| [`docs/troubleshoot.md`](./docs/troubleshoot.md) | 故障排查 |
+
+## 当前不做的（故意）
+
+**v1.0 故意跳过**：
+- **Phase 6**（ship / land / canary / retro） — 私有仓库场景 ROI 低。未来社区反馈需要再补。
+- **集成检查代理** — Epic 跨子规格验证。暂时手动。
+- **Checkpoint save/restore** — 当前 `.flow/STATE.md` 覆盖多数需求。
+- **多运行时支持** — 仅 Claude Code。其他工具的插件 API 成熟后再考虑。
+
+完整版本历史见 [`CHANGELOG.md`](./CHANGELOG.md)。
+
+## 致谢
+
+CurDX-Flow 是蒸馏，不是原创。深深致谢：
+
+- [**andrej-karpathy-skills**](https://github.com/forrestchang/andrej-karpathy-skills) — 4 原则
+- [**smart-ralph**](https://github.com/Nibzard/smart-ralph) — 规格引擎 + stop-hook 循环
+- [**superpowers**](https://github.com/obra/superpowers) — Subagent 纪律 + TDD + 两阶段审查
+- [**BMAD-METHOD**](https://github.com/bmad-code-org/BMAD-METHOD) — 人格 + Party Mode + 对抗审查
+- [**get-shit-done**](https://github.com/ryangentry/get-shit-done) — 波形执行 + 决策锁定 + 多源审计
+- [**gstack**](https://github.com/garrytan/gstack)（Garry Tan） — 规划审查 + DX 哲学
+- [**pua**](https://github.com/tanweai/pua) — 持续性 + 三条红线
+- [**claude-mem**](https://github.com/thedotmack/claude-mem) — 自动跨会话记忆
+- [**frontend-design skill**](https://claude.ai/skills/frontend-design) — distinctive UI（Anthropic 官方）
+- **context7**（Upstash）+ **sequential-thinking**（Anthropic）+ **chrome-devtools-mcp**（Chrome 团队）
+
+## 许可
+
+MIT。见 [`LICENSE`](./LICENSE)。
+
+## 贡献
+
+- Issues: https://github.com/wdx/curdx-flow/issues
+- 欢迎 PR，但请先用 `/curdx-flow:spec` 自己走一遍（吃自己的狗粮）
+- 社区准则：友善 + 具体 + 不对着 LLM 发火
+
+---
+
+_CurDX = AI 编程时代的 "Current Developer eXperience"。_

package/bin/curdx-flow.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/**
+ * curdx-flow CLI entry
+ *
+ * Usage:
+ *   npx github:curdx/curdx-flow <command> [args]
+ *   (or after npm publish: npx @curdx/flow <command> [args])
+ *
+ * Commands:
+ *   install   Install curdx-flow plugin + optional recommended plugins
+ *   doctor    Check health (claude CLI, plugin, MCPs, recommended plugins)
+ *   init      Initialize .flow/ in current project (external version)
+ *   upgrade   Update curdx-flow + recommended plugins to latest
+ *   help      Show this help
+ *   --version / -v
+ */
+
+import { install } from "../cli/install.js";
+import { doctor } from "../cli/doctor.js";
+import { init } from "../cli/init.js";
+import { upgrade } from "../cli/upgrade.js";
+import { uninstall } from "../cli/uninstall.js";
+import { VERSION, color } from "../cli/utils.js";
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+const rest = args.slice(1);
+
+function printHelp() {
+  console.log(`
+${color.bold("curdx-flow")} ${color.dim(`v${VERSION}`)}
+CurDX-Flow installer & helper for Claude Code
+
+${color.bold("USAGE")}
+  curdx-flow <command> [options]
+
+${color.bold("COMMANDS")}
+  ${color.cyan("install")}   Install curdx-flow plugin + optional recommended plugins
+            --all       Install all recommended (skip prompt)
+            --no-deps   Only install curdx-flow, skip recommendations
+
+  ${color.cyan("doctor")}    Check health (claude CLI, plugin, MCPs, recommended)
+
+  ${color.cyan("init")}      Initialize .flow/ in current project (no Claude Code needed)
+            [path]      Target directory (default: cwd)
+            --force     Overwrite existing .flow/
+
+  ${color.cyan("upgrade")}   Update curdx-flow and recommended plugins to latest
+
+  ${color.cyan("uninstall")} Remove curdx-flow plugin (and optionally recommended / artifacts)
+            -y, --yes           Skip confirmation, keep recommended + .flow/
+            --keep-recommended  Don't ask about pua/claude-mem/frontend-design
+            --purge             Also remove ~/.local/bin/bun, ~/.local/bin/uv symlinks
+
+  ${color.cyan("help")}      Show this help (same as --help / -h)
+
+${color.bold("OPTIONS")}
+  -v, --version       Print version
+  -h, --help          Show help
+
+${color.bold("EXAMPLES")}
+  ${color.dim("# First-time install with recommended plugins")}
+  npx github:curdx/curdx-flow install --all
+
+  ${color.dim("# Check what's installed")}
+  npx github:curdx/curdx-flow doctor
+
+  ${color.dim("# Initialize your project")}
+  cd ~/my-project && npx github:curdx/curdx-flow init
+
+  ${color.dim("# Update everything")}
+  npx github:curdx/curdx-flow upgrade
+
+${color.bold("LEARN MORE")}
+  https://github.com/curdx/curdx-flow
+`);
+}
+
+async function main() {
+  // Version flags
+  if (cmd === "--version" || cmd === "-v") {
+    console.log(VERSION);
+    return;
+  }
+
+  // Help flags
+  if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
+    printHelp();
+    return;
+  }
+
+  // Route
+  try {
+    switch (cmd) {
+      case "install":
+        await install(rest);
+        break;
+      case "doctor":
+        await doctor(rest);
+        break;
+      case "init":
+        await init(rest);
+        break;
+      case "upgrade":
+        await upgrade(rest);
+        break;
+      case "uninstall":
+      case "remove":
+        await uninstall(rest);
+        break;
+      default:
+        console.error(color.red(`Unknown command: ${cmd}`));
+        console.error(`Run ${color.cyan("curdx-flow help")} for usage.`);
+        process.exit(1);
+    }
+  } catch (err) {
+    console.error(color.red(`\n✗ ${err.message || err}`));
+    if (process.env.CURDX_DEBUG) {
+      console.error(err.stack || "");
+    }
+    process.exit(1);
+  }
+}
+
+main();

package/cli/README.md

@@ -0,0 +1,87 @@
+# curdx-flow CLI
+
+One-shot installer + external diagnostics + external init. Zero npm deps, pure Node.js.
+
+## Quick Start
+
+```bash
+# Interactive install (pick recommended plugins)
+npx github:curdx/curdx-flow install
+
+# Or install everything automatically
+npx github:curdx/curdx-flow install --all
+
+# Health check
+npx github:curdx/curdx-flow doctor
+
+# Initialize a project (creates .flow/ in cwd)
+cd ~/your-project
+npx github:curdx/curdx-flow init
+
+# Update all plugins
+npx github:curdx/curdx-flow upgrade
+```
+
+## Commands
+
+### `install [--all] [--no-deps]`
+
+Steps:
+1. Verify the `claude` CLI is installed
+2. `claude plugin marketplace add curdx/curdx-flow`
+3. `claude plugin install curdx-flow@curdx-flow-marketplace` (auto-installs 3 MCPs)
+4. Interactively (or automatically) install recommended plugins: **pua**, **claude-mem**, **frontend-design**
+
+| Flag | Purpose |
+|------|---------|
+| `--all` | Install all recommended plugins, no prompt |
+| `--no-deps` | Install only curdx-flow itself |
+
+### `doctor [--verbose]`
+
+External diagnostics: claude CLI / curdx-flow / 3 MCPs / 3 recommended plugins / current directory `.flow/` state.
+
+### `init [path] [--force]`
+
+In `path` (default cwd) creates `.flow/` directory: PROJECT.md / CONTEXT.md / STATE.md / ROADMAP.md / config.json + updates `.gitignore`.
+
+If the curdx-flow plugin is installed, reads templates from the plugin cache; otherwise uses embedded fallback templates.
+
+### `upgrade`
+
+`claude plugin marketplace update` + `claude plugin update` for every installed curdx-flow-related plugin.
+
+### `uninstall [-y] [--keep-recommended] [--purge]`
+
+Inverse of `install`. By default removes only the curdx-flow plugin. With `--purge`, also removes the `~/.local/bin/bun` and `~/.local/bin/uv` symlinks created by install.
+
+## Why a CLI?
+
+The **core workflow** still lives inside Claude Code (`/curdx-flow:*` commands). The CLI provides:
+
+- **One-line install**: Docker/CI friendly (`RUN npx github:curdx/curdx-flow install --all`)
+- **External diagnostics**: check health without entering Claude Code
+- **Batch deployment**: write a script for your team — `for host in ...; do ssh $host npx github:curdx/curdx-flow install; done`
+
+## Zero-dependency design
+
+- Pure ES Modules (Node 18+)
+- Only Node built-ins (`child_process`, `fs/promises`, `readline`)
+- No `chalk` / `commander` / `inquirer` / `execa`
+- Fast `npx` (no `node_modules` to download)
+
+## Local development
+
+```bash
+# clone
+git clone https://github.com/curdx/curdx-flow
+cd curdx-flow
+
+# run directly
+node bin/curdx-flow.js --help
+node bin/curdx-flow.js doctor
+```
+
+## License
+
+MIT