@chenmk/superflow 0.1.1 → 0.1.3

package/INSTALL.en.md

@@ -2,8 +2,9 @@
 
 [中文教程](./INSTALL.md)
 
-SuperBridge Flow installs OpenSpec, Superpowers, skills, hooks, scripts, rules,
-and handoff state for Claude Code and Codex.
+SuperBridge Flow installs OpenSpec, Superpowers, skills, hooks or command
+aliases, scripts, rules, and handoff state for Claude Code, Codex, and
+OpenCode.
 
 ## 1. Install
 
@@ -24,18 +25,27 @@ superflow init --language en --yes
 superflow init --language zh --yes
 ```
 
+Global language selection is also supported:
+
+```bash
+superflow --language en --help
+SUPERFLOW_LANG=en superflow init
+```
+
 `superflow init` performs:
 
 1. Detect platform paths.
 2. Install OpenSpec CLI.
-3. Run native `openspec init <project> --tools claude,codex --profile custom`.
-4. Install Superpowers for selected agents.
+3. Run native `openspec init <project> --tools ... --profile custom`.
+4. Install Superpowers for selected Claude Code/Codex agents.
 5. Try understand-anything and api-doc-changelog.
 6. Deploy SuperBridge Flow/OpenSpec skills.
 7. Register hooks and rules.
 8. Scaffold `docs/sdd-context/`.
 
-OpenSpec and Superpowers are required. understand-anything is best-effort.
+OpenSpec and Superpowers are required for the full workflow. OpenCode receives
+skills and command aliases; native hook registration is not enabled for
+OpenCode yet. understand-anything is best-effort.
 
 ## 3. Daily Workflow
 
@@ -51,6 +61,12 @@ In Claude Code:
 /superflow-pipeline
 ```
 
+In OpenCode:
+
+```text
+/superflow-pipeline
+```
+
 The workflow phases are:
 
 ```text
@@ -70,6 +86,16 @@ superflow doctor
 was compressed or interrupted, ask the agent to continue the current SuperBridge
 Flow change. It will read `.sdd/state.yaml` and `.sdd/handoff`.
 
+To regenerate project context templates:
+
+```bash
+superflow scan --language en
+superflow scan --language en --force
+```
+
+`scan` keeps edited files by default. Use `--force` only when you want to
+overwrite the four files under `docs/sdd-context/`.
+
 ## 5. Updates
 
 Refresh installed skills, hooks, scripts, and rules:
@@ -100,6 +126,7 @@ Team environments should keep `check`. Personal machines may choose `apply`.
 ```bash
 superflow uninstall --agent codex --force
 superflow uninstall --agent claude --force
+superflow uninstall --agent opencode --force
 ```
 
 This removes SuperBridge Flow managed assets only. It does not remove unrelated

package/INSTALL.md

@@ -1,6 +1,6 @@
 # SuperBridge Flow 安装、初始化与日常使用教程
 
-`@chenmk/superflow` 是面向 Claude Code 和 Codex 的 SDD 开发工作流 CLI。它把
+`@chenmk/superflow` 是面向 Claude Code、Codex 和 OpenCode 的 SDD 开发工作流 CLI。它把
 OpenSpec、Superpowers、SuperBridge Flow 技能、状态机、handoff 上下文包、hook 脚本和
 质量门禁安装到你的 agent 环境里，让一个需求可以沿着固定阶段推进：
 
@@ -24,7 +24,7 @@ docs -> design -> implement -> verify -> archive
 | Node.js | 20+ | `node -v` |
 | npm | 9+ | `npm -v` |
 | Git | 已安装 | `git --version` |
-| Agent | Claude Code 或 Codex 至少一个 | `claude --version` / `codex --version` |
+| Agent | Claude Code、Codex 或 OpenCode 至少一个 | `claude --version` / `codex --version` / `opencode --version` |
 | Shell | macOS/Linux 原生 shell；Windows 使用 Git Bash 或兼容 shell | `bash --version` |
 | Python | hook 中的 Python 脚本需要 | `python3 --version` |
 
@@ -55,7 +55,7 @@ npm install -g @chenmk/superflow
 
 ```bash
 git clone <your-repo-url>
-cd code-cli-config/sdd-cli
+cd superflow
 npm install
 npm run build
 npm install -g .
@@ -83,7 +83,8 @@ cd your-project
 superflow init
 ```
 
-CLI 会弹出工具选择列表。你可以只选 Codex、只选 Claude Code，或两者都选。
+CLI 会弹出工具选择列表。你可以只选 Codex、只选 Claude Code、只选 OpenCode，
+也可以选择多个工具。
 选择结果会替代手写 `--agent codex` / `--agent claude`。
 
 `superflow init` 会执行：
@@ -92,13 +93,14 @@ CLI 会弹出工具选择列表。你可以只选 Codex、只选 Claude Code，
 2. 安装 OpenSpec CLI。
 3. 在当前项目目录执行 OpenSpec 原生初始化，并把你选择的工具下发给
    OpenSpec，例如 `openspec init <project> --tools claude,codex --profile custom`。
-4. 为目标 agent 安装 Superpowers；这是 Superflow 的核心 HOW/TDD 依赖，
-   安装失败会中断初始化。
+4. 为 Claude Code / Codex 安装 Superpowers；这是 Superflow 的核心 HOW/TDD
+   依赖，安装失败会中断初始化。OpenCode 侧会部署 SuperBridge Flow skills
+   和 commands，不注册原生 hook。
 5. 尝试安装 understand-anything，并复制 api-doc-changelog；失败只警告，
    不阻断初始化。
 6. 部署 SuperBridge Flow/OpenSpec skills。
-7. 部署 hook 脚本并注册到 Codex `hooks.json` 或 Claude
-   `settings.json`。
+7. 部署 hook/command 脚本；Codex 写入 `hooks.json`，Claude Code 写入
+   `settings.json`，OpenCode 写入 `.opencode/commands`。
 8. 部署 SuperBridge Flow 防漂移规则。
 9. 初始化 `docs/sdd-context/` 项目上下文模板，并提示
    understand-anything 扫描状态。
@@ -109,8 +111,9 @@ CLI 会弹出工具选择列表。你可以只选 Codex、只选 Claude Code，
 请选择要初始化的 agent 工具（可多选）：
   1) Claude Code
   2) Codex
-  a) 两者都安装（默认）
-输入序号，例如 1,2 / 2 / a：
+  3) OpenCode
+  a) 安装 Claude Code + Codex（默认）；输入 all 会包含 OpenCode
+输入序号，例如 1,2 / 2,3 / all / a：
 ```
 
 选择结果会同时影响：
@@ -125,8 +128,10 @@ CLI 会弹出工具选择列表。你可以只选 Codex、只选 Claude Code，
 
 | 命令 | 说明 |
 |------|------|
-| `superflow init` | 交互式初始化，可多选 Codex / Claude Code |
+| `superflow init` | 交互式初始化，可多选 Codex / Claude Code / OpenCode |
 | `superflow init --yes` | 非交互执行，默认初始化 Claude Code + Codex |
+| `superflow init --agent opencode` | 只初始化 OpenCode |
+| `superflow init --agent all` | 初始化 Claude Code + Codex + OpenCode |
 | `superflow init --scope global` | 安装到用户主目录，默认值 |
 | `superflow init --scope project` | 安装到当前项目目录 |
 | `superflow init --no-hooks` | 只安装技能和脚本，不注册 hook |
@@ -138,13 +143,36 @@ CLI 会弹出工具选择列表。你可以只选 Codex、只选 Claude Code，
 | `superflow init --overwrite` | 覆盖已安装的 SuperBridge Flow 技能 |
 | `superflow init --skip-existing` | 保留已存在技能，不覆盖 |
 
-初始化后建议重启 Claude Code 或 Codex，让 agent 重新加载技能列表。
+语言可以通过两种方式选择：
+
+```bash
+# 单次命令使用英文 help / 提示
+superflow --language en --help
+superflow init --language en
+
+# 当前 shell 默认使用英文提示
+export SUPERFLOW_LANG=en
+superflow init
+```
+
+如果只想重新生成项目上下文模板，可以使用：
+
+```bash
+superflow scan --language zh
+superflow scan --language en --force
+```
+
+`scan` 默认保留已经编辑过的文件；加 `--force` 才会覆盖
+`docs/sdd-context/` 下的 4 个模板文件。
+
+初始化后建议重启 Claude Code、Codex 或 OpenCode，让 agent 重新加载技能列表。
 
 ## 4. 验证安装
 
 ```bash
 superflow doctor --agent codex
 superflow doctor --agent claude
+superflow doctor --agent opencode
 ```
 
 也可以同时检查两侧：
@@ -160,7 +188,7 @@ superflow doctor
 - Superpowers、understand-anything、api-doc-changelog 是否可检测。
 - SuperBridge Flow skills 是否完整。
 - hook 脚本是否存在。
-- hook 是否已注册。
+- hook 是否已注册；OpenCode 当前检查 command alias，不把原生 hook 作为硬门禁。
 - SDD rule 是否已部署。
 - 当前项目里的 `.sdd/state.yaml` 是否符合状态机字段约束。
 
@@ -168,6 +196,7 @@ superflow doctor
 
 ```bash
 superflow pipeline --agent codex
+superflow pipeline --agent opencode
 superflow docs --agent codex
 superflow design --agent codex
 superflow implement --agent codex
@@ -179,18 +208,21 @@ superflow archive --agent codex
 
 ### 5.1 开始一个完整需求
 
-Codex 和 Claude Code 的触发方式不同：
+Codex、Claude Code 和 OpenCode 的触发方式不同：
 
 - Codex：通常用自然语言或 `$skill-name` 触发，例如“请使用 SuperBridge Flow 流程”或
   `$superflow-pipeline`。
 - Claude Code：安装后可以直接使用 slash command，例如
   `/superflow-pipeline`、`/superflow-clarify`、`/superflow-docs`、`/superflow-design`、
   `/superflow-implement`、`/superflow-verify`、`/superflow-archive`。
+- OpenCode：安装后使用 `.opencode/commands` 里的 slash command，例如
+  `/superflow-pipeline`、`/superflow-docs`、`/superflow-design`、`/superflow-verify`。
 
 普通使用建议始终先走总路由，让 SDD 自己判断阶段：
 
 - Codex：优先 `$superflow-pipeline` 或自然语言“请使用 SuperBridge Flow 流程”。
 - Claude Code：优先 `/superflow-pipeline`。
+- OpenCode：优先 `/superflow-pipeline`。
 
 只有你非常明确当前就是需求澄清、文档补齐、技术详设或实现阶段时，才直达
 `$superflow-clarify` / `/superflow-clarify`、`$superflow-docs` / `/superflow-docs` 等阶段命令。
@@ -207,6 +239,12 @@ Codex 和 Claude Code 的触发方式不同：
 /superflow-pipeline 处理这个需求：……
 ```
 
+在 OpenCode 会话里同样可以运行：
+
+```text
+/superflow-pipeline 处理这个需求：……
+```
+
 两种方式都会从 SDD 总入口路由，通常按下面阶段推进。
 
 #### 示例：读取飞书在线文档中的某个小节
@@ -453,7 +491,7 @@ Claude Code 里也可以直接用当前阶段命令继续，例如：
 
 - `@chenmk/superflow`
 - `@fission-ai/openspec`
-- Claude Code / Codex 的 Superpowers 插件
+- Claude Code / Codex 的 Superpowers 插件；OpenCode 侧刷新 SuperBridge Flow assets
 
 同一会话只检查一次；默认只提示，不自动安装。至少间隔 6 小时才真正访问
 npm/plugin 源，避免每次 prompt 都联网。可用：
@@ -538,7 +576,7 @@ which superflow
 如果是源码安装，也可以重新链接：
 
 ```bash
-cd code-cli-config/sdd-cli
+cd superflow
 npm run build
 npm install -g .
 ```
@@ -561,17 +599,20 @@ python3 --version
 
 ### 技能装好了，但 agent 没触发
 
-重启 Claude Code 或 Codex。若仍不触发：
+重启 Claude Code、Codex 或 OpenCode。若仍不触发：
 
 ```bash
 superflow doctor --agent codex
+superflow doctor --agent opencode
 superflow pipeline --agent codex
+superflow pipeline --agent opencode
 ```
 
 然后在会话里明确说：
 
 ```text
 请使用 $superflow-pipeline 处理这个需求。
+/superflow-pipeline 处理这个需求。
 ```
 
 ### 任务 prompt 偶发缺失

package/README.md

@@ -1,18 +1,102 @@
-# SuperBridge Flow
+<p align="center">
+  <img src="./assets/brand/superflow-banner.svg" alt="SuperBridge Flow banner">
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@chenmk/superflow"><img alt="npm version" src="https://img.shields.io/npm/v/@chenmk/superflow?style=flat-square"></a>
+  <a href="https://www.npmjs.com/package/@chenmk/superflow"><img alt="monthly downloads" src="https://img.shields.io/npm/dm/@chenmk/superflow?style=flat-square&label=Downloads/mo"></a>
+  <a href="https://www.npmjs.com/package/@chenmk/superflow"><img alt="weekly downloads" src="https://img.shields.io/npm/dw/@chenmk/superflow?style=flat-square&label=Downloads/wk"></a>
+  <a href="https://github.com/BasketballNotFound-ManKun/superflow-cli/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/BasketballNotFound-ManKun/superflow-cli?style=flat-square"></a>
+  <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square"></a>
+  <img alt="Node.js 20+" src="https://img.shields.io/badge/Node.js-20%2B-339933?style=flat-square">
+</p>
+
+<p align="center">
+  <strong>A workflow harness for turning OpenSpec/SDD contracts and
+  Superpowers engineering discipline into one delivery flow.</strong>
+</p>
+
+<p align="center">
+  <a href="./README.zh-CN.md">中文文档</a>
+  ·
+  <a href="#install">Install</a>
+  ·
+  <a href="#workflow">Workflow</a>
+  ·
+  <a href="#star-history">Star History</a>
+</p>
 
-[中文文档](./README.zh-CN.md)
+# SuperBridge Flow
 
 SuperBridge Flow is a workflow CLI for bringing OpenSpec/SDD and Superpowers
 together in real software delivery.
 
+## Why SuperBridge Flow
+
+Modern agentic coding often fails in the gap between a well-written spec and
+real verified delivery. SuperBridge Flow makes that gap explicit:
+
 - OpenSpec/SDD owns **WHAT**: requirements, API contracts, database and field
   semantics, tests, real-entry acceptance, and quality gates.
 - Superpowers owns source-level **HOW**: technical design, TDD order,
   worktree/team execution, review, and verification discipline.
-- The full lifecycle is `docs -> design -> implement -> verify -> archive`.
+- Handoff files, phase state, hooks, and guards reduce context drift when long
+  conversations get compacted or split across agent sessions.
+
+The CLI installs skills, hooks or command aliases, rules, scripts, handoff
+state, and dependency guards for Claude Code, Codex, and OpenCode.
+
+## Highlights
+
+- **9 catalogued failure modes, blocked at the gate.** Nine real ways AI breaks
+  in production — swallowing the whole PRD then forgetting details, editing
+  only the setter while missing consumers, SQL drift across dev/test/DB
+  layers, mock-only "已验证" reports, and more — each baked into a hard check
+  the agent cannot skip.
+- **Architecture 6-questions before cross-service code.** Any change crossing
+  service / SDK / MQ / device / callback / gateway boundaries must answer six
+  questions in the technical design: who owns the module, what is the call
+  direction, where are existing entry/exit points, are new ones allowed, which
+  paths are forbidden, what is the evidence anchor.
+- **Field And Status Reverse Impact matrix.** Every schema / status / enum
+  change must enumerate its write sites, read sites, filter conditions,
+  derived / sync sites, cross-module consumers, and test coverage — including
+  reverse-recovery scenarios (down then up again, deleted then re-created, old
+  value unavailable while upstream didn't send the field).
+- **6 productized lessons as gates, not reminders.** Full-impact discovery,
+  business semantics over HTTP 200, no default fallbacks, DB reconciliation,
+  real-entry evidence, code-data verification — each baked into a specific
+  phase and a specific hook. Missing evidence blocks the next phase.
+- **5 phases × 5+ guard scripts as hard gates.** `superflow-guard.sh` +
+  `superflow-hook-guard.sh` + `superflow-contract-hooks.sh` +
+  `superflow-sql-sync-hook.py` + `superflow-test-report-lint.py` +
+  `superflow-verify-integration.sh`. No handoff hash → no implementation. No
+  real-entry evidence → no "verified" report.
+- **Context-drift proof via handoff + state + sha256.** When long sessions
+  compress, when agents switch, when multiple workers parallelize —
+  `.sdd/handoff/sdd-context.{md,json}` + sha256 + `.sdd/state.yaml` keep
+  Worker / Tester / Reviewer on the same source of truth. Stale prompts
+  blocked by hash mismatch.
+- **User says one sentence, pipeline runs 9 steps.** No prompt engineering
+  required: `> use SuperFlow to handle this requirement` triggers clarify →
+  docs → design → implement → verify → archive. Phase progression, guards,
+  hashes, and hooks are flow-enforced, not user-discipline.
+
+## Workflow
 
-The CLI installs skills, hooks, rules, scripts, handoff state, and dependency
-guards for Claude Code and Codex.
+```text
+docs -> design -> implement -> verify -> archive
+```
+
+Each phase has a clear owner and an exit gate:
+
+| Phase | Owner | Output |
+| --- | --- | --- |
+| `docs` | OpenSpec/SDD | Requirements, contracts, API/DB/test docs |
+| `design` | Superpowers | Source-level technical design and TDD plan |
+| `implement` | Superpowers + SuperBridge Flow | Batched implementation prompts and review gates |
+| `verify` | SuperBridge Flow hooks | Evidence-backed test report and real-entry checks |
+| `archive` | OpenSpec/SDD | Final spec archive and lifecycle closure |
 
 ## Install
 
@@ -28,7 +112,7 @@ superflow init
 
 Interactive init lets you select:
 
-- target agent tools: Claude Code, Codex, or both
+- target agent tools: Claude Code, Codex, OpenCode, or selected combinations
 - language: English or Chinese
 - install scope: global or project
 
@@ -40,6 +124,13 @@ superflow init --language en --yes
 superflow init --language zh --yes
 ```
 
+CLI help and runtime prompts can also be switched globally:
+
+```bash
+superflow --language en --help
+SUPERFLOW_LANG=en superflow init
+```
+
 ## What Init Installs
 
 `superflow init` installs and configures:
@@ -60,10 +151,14 @@ best-effort and does not block initialization.
 | Command | Purpose |
 | --- | --- |
 | `superflow init` | Install and configure SuperBridge Flow interactively |
+| `superflow init --agent opencode` | Install OpenCode skills and command aliases |
+| `superflow init --agent all` | Install Claude Code, Codex, and OpenCode |
 | `superflow update` | Refresh installed skills, hooks, scripts, and rules |
 | `superflow update --with-package` | Also update `@chenmk/superflow`, OpenSpec, and Superpowers |
 | `superflow doctor` | Diagnose installed assets and project state |
 | `superflow status` | Show active changes, current phase, next command, and risks |
+| `superflow --language en --help` | Show English CLI help |
+| `superflow scan --language en` | Regenerate project context templates in English |
 | `superflow pipeline` | Check pipeline skill deployment |
 | `superflow docs` | Check docs-phase skill deployment |
 | `superflow design` | Check design-phase skill deployment |
@@ -85,6 +180,16 @@ In Claude Code:
 /superflow-pipeline
 ```
 
+In OpenCode:
+
+```text
+/superflow-pipeline
+```
+
+OpenCode receives `.opencode/skills` and `.opencode/commands` assets. Native
+hook registration is not enabled for OpenCode yet; use `/superflow-*` commands
+to run workflow gates explicitly.
+
 For large requirements, ask the agent to read one section or one feature at a
 time. SuperBridge Flow will route through clarification, OpenSpec docs,
 Superpowers technical design, implementation prompts, verification, and archive.
@@ -133,10 +238,19 @@ keeps the same workflow contracts.
 ## Requirements
 
 - Node.js 20+
-- Claude Code or Codex
+- Claude Code, Codex, or OpenCode
 - npm access to install OpenSpec and Superpowers
 - Git Bash or a compatible shell on Windows for hook scripts
 
+## Star History
+
+The chart is generated by Star History from public GitHub star data. It may stay
+empty while the repository is private.
+
+[![Star History Chart](https://api.star-history.com/svg?repos=basketballnotfound-mankun/superflow-cli&type=Date)](https://star-history.com/#basketballnotfound-mankun/superflow-cli&Date)
+
+[Open the Star History chart](https://star-history.com/#basketballnotfound-mankun/superflow-cli&Date)
+
 ## License
 
 MIT

package/README.zh-CN.md

@@ -1,13 +1,69 @@
+<p align="center">
+  <img src="./assets/brand/superflow-banner.svg" alt="SuperBridge Flow banner">
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@chenmk/superflow"><img alt="npm version" src="https://img.shields.io/npm/v/@chenmk/superflow?style=flat-square"></a>
+  <a href="https://www.npmjs.com/package/@chenmk/superflow"><img alt="monthly downloads" src="https://img.shields.io/npm/dm/@chenmk/superflow?style=flat-square&label=Downloads/mo"></a>
+  <a href="https://www.npmjs.com/package/@chenmk/superflow"><img alt="weekly downloads" src="https://img.shields.io/npm/dw/@chenmk/superflow?style=flat-square&label=Downloads/wk"></a>
+  <a href="https://github.com/BasketballNotFound-ManKun/superflow-cli/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/BasketballNotFound-ManKun/superflow-cli?style=flat-square"></a>
+  <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square"></a>
+  <img alt="Node.js 20+" src="https://img.shields.io/badge/Node.js-20%2B-339933?style=flat-square">
+</p>
+
+<p align="center">
+  <strong>把 OpenSpec/SDD 的合同约束和 Superpowers 的工程纪律，收束成一个可执行的交付工作流。</strong>
+</p>
+
+<p align="center">
+  <a href="./README.md">English</a>
+  ·
+  <a href="#安装">安装</a>
+  ·
+  <a href="#工作流">工作流</a>
+  ·
+  <a href="#star-history">Star History</a>
+</p>
+
 # SuperBridge Flow
 
-[English](./README.md)
+通用 SDD 开发工作流 CLI，支持 Claude Code、Codex 和 OpenCode。
 
-通用 SDD 开发工作流 CLI，支持 Claude Code 和 Codex。
+SuperBridge Flow 不是简单“装两个工具”，而是把 OpenSpec/SDD 和
+Superpowers 编排成一个有状态的研发流程：前者负责需求、合同和验收口径，
+后者负责源码级设计、TDD 顺序、实现分工、review 和真实验证。
 
-把 SuperBridge Flow 技能和配套 hook 脚本整合为单一 npm 包，通过 CLI 自动部署到：
+CLI 会把 SuperBridge Flow 技能、配套 hook/command 脚本整合为单一 npm 包，
+自动部署到：
 
 - Claude Code：`~/.claude/skills/`、`~/.claude/scripts/`，并注册 `~/.claude/settings.json` hook
 - Codex：`~/.codex/skills/`、`~/.codex/hooks/`
+- OpenCode：`.opencode/skills/`、`.opencode/commands/`、`.opencode/scripts/`
+  或全局 `~/.config/opencode/`
+
+## 亮点
+
+- **9 类翻车场景，沉淀成门禁。** 我们见过的 AI 翻车——需求一次吞、字段漏查消费者、SQL 漂移、mock-only 报告、跨服务只看到"能调"……9 种典型形态都被固化成 guard，AI 想跳过都不行。
+- **跨服务代码必须先答架构 6 问。** 涉及跨仓、跨服务、SDK、MQ、设备、回调、网关的改动，技术详设里必须先回答：owner 是谁、调用方向、新入口是否允许、禁止路径、证据锚点——答不全不让进入实现。
+- **改字段之前先填"字段与状态反向影响"矩阵。** 任何 schema、状态、枚举的改动，必须枚举写入点、读取点、过滤点、派生 / 同步点、跨模块消费者、测试覆盖，还要列反向恢复场景（下线后重上线、旧值不可用但上游没传字段、历史脏数据被新过滤条件消费）。
+- **6 条踩坑经验产品化，不是提醒是门禁。** 影响面要查全、业务语义 > 接口成功、禁止默认兜底、数据库收口、真实入口验证、代码与数据关系核实——每条绑定特定阶段和特定 hook，缺证据就阻断下一阶段。
+- **5 个阶段 × 5+ 门禁脚本硬阻断。** `superflow-guard.sh` + `superflow-hook-guard.sh` + `superflow-contract-hooks.sh` + `superflow-sql-sync-hook.py` + `superflow-test-report-lint.py` + `superflow-verify-integration.sh`。没有 handoff hash 不进实现，没有真实入口证据不写"通过"。
+- **用 handoff + state + sha256 治上下文漂移。** 长会话压缩、切 agent、并行 worktree——`.sdd/handoff/sdd-context.{md,json}` + sha256 + `.sdd/state.yaml` 让 Worker / Tester / Reviewer 始终基于同一份上下文，hash 对不上的旧 prompt 自动被 guard 拒绝。
+- **用户只说一句话，流水线跑 9 步。** 不用写复杂 prompt：`> 用 SuperFlow 处理这个需求` 触发 clarify → docs → design → implement → verify → archive。阶段推进、guard、hash、hook 全是流程强制，不靠用户自觉。
+
+## 工作流
+
+```text
+docs -> design -> implement -> verify -> archive
+```
+
+| 阶段 | 主责 | 产物 |
+|------|------|------|
+| `docs` | OpenSpec/SDD | 需求、接口、数据库、测试和验收合同 |
+| `design` | Superpowers | 源码级技术详设、影响面分析和 TDD 计划 |
+| `implement` | Superpowers + SuperBridge Flow | 分批任务 prompt、review 门禁和执行状态 |
+| `verify` | SuperBridge Flow hooks | 有证据的测试报告、真实入口和联调校验 |
+| `archive` | OpenSpec/SDD | 归档后的 spec 状态和生命周期闭环 |
 
 ## 安装
 
@@ -20,12 +76,18 @@ npm install -g @chenmk/superflow
 ## 快速开始
 
 ```bash
-# 交互式选择 Claude Code / Codex（可多选）
+# 交互式选择 Claude Code / Codex / OpenCode（可多选）
 superflow init
 
 # 非交互模式，默认同时安装 Claude Code + Codex
 superflow init --yes
 
+# 显式安装 OpenCode
+superflow init --agent opencode
+
+# 同时安装 Claude Code + Codex + OpenCode
+superflow init --agent all
+
 # 跳过 hook 注册（手工管理）
 superflow init --no-hooks
 
@@ -39,6 +101,17 @@ superflow init --resume
 superflow doctor
 ```
 
+语言也可以全局切换：
+
+```bash
+# 查看英文 CLI help
+superflow --language en --help
+
+# 当前 shell 默认使用英文提示
+export SUPERFLOW_LANG=en
+superflow init
+```
+
 ## SDD 分工
 
 - OpenSpec/SDD 负责 WHAT 和合同：需求、API、DB、SQL、字段语义、tests、真实入口验收和质量门禁。
@@ -51,14 +124,18 @@ superflow doctor
 
 | 命令 | 说明 |
 |------|------|
-| `superflow init` | 一站式安装；交互终端中可多选 Claude Code / Codex |
+| `superflow init` | 一站式安装；交互终端中可多选 Claude Code / Codex / OpenCode |
 | `superflow init --yes` | 非交互安装，默认 `--agent both` |
+| `superflow init --agent opencode` | 安装 OpenCode skills、commands、scripts 和 rules |
+| `superflow init --agent all` | 同时安装 Claude Code + Codex + OpenCode |
 | `superflow init --dry-run` | 只打印计划不执行 |
 | `superflow init --resume` | 从失败步骤继续 |
 | `superflow init --no-hooks` | 只装技能 + 脚本，跳过 Codex/Claude hook 注册 |
 | `superflow init --no-openspec-init` | 跳过当前项目 OpenSpec 原生初始化 |
 | `superflow doctor` | 诊断 CLI / 第三方 / 脚本 / skills |
 | `superflow doctor --agent codex` | 只诊断 Codex 侧 |
+| `superflow --language en --help` | 查看英文 CLI help |
+| `superflow scan --language en` | 重新生成英文项目上下文模板 |
 | `superflow clarify [feature]` | 校验 SuperBridge Flow clarify 阶段技能部署 |
 | `superflow docs [change]` | 校验 SuperBridge Flow docs 阶段技能部署 |
 | `superflow design [change]` | 校验 SuperBridge Flow design 阶段技能部署 |
@@ -74,10 +151,10 @@ superflow doctor
 ## 依赖
 
 - Node.js 20+
-- Claude Code 或 Codex（按 `--agent` 选择）
+- Claude Code、Codex 或 OpenCode（按 `--agent` 选择）
 - 第三方（`superflow init` 自动装）：
   - openspec CLI（硬依赖，npm 全局）并在当前项目执行 `openspec init --tools ...`
-  - superpowers（硬依赖，Claude Code / Codex 对应插件）
+  - superpowers（Claude Code / Codex 为硬依赖；OpenCode 侧通过已部署 skills/commands 使用流程）
   - understand-anything（尽力安装，失败只警告）
   - api-doc-changelog（辅助 skill，复制到目标 agent skills 目录）
 
@@ -87,7 +164,7 @@ superflow doctor
 
 - `@chenmk/superflow`
 - `@fission-ai/openspec`
-- Claude Code / Codex 的 Superpowers 插件
+- Claude Code / Codex 的 Superpowers 插件；OpenCode 侧的 SuperBridge Flow assets
 
 推荐策略是“自动检查，手动更新”：默认只提示，不自动安装；执行
 `superflow update --with-package` 才会统一更新。
@@ -107,10 +184,14 @@ export SUPERFLOW_AUTO_UPDATE=apply
 export SUPERFLOW_UPDATE_MIN_INTERVAL_SECONDS=21600
 ```
 
-## 设计文档
+## Star History
+
+下图由 Star History 根据 GitHub 公开 star 数据动态生成。仓库保持 private
+时，第三方服务通常读不到完整数据；切换为 public 后会正常展示趋势。
+
+[![Star History Chart](https://api.star-history.com/svg?repos=basketballnotfound-mankun/superflow-cli&type=Date)](https://star-history.com/#basketballnotfound-mankun/superflow-cli&Date)
 
-- 详细设计：`~/cmk-project/code-cli-config/sdd-cli-design.md`
-- 实施 plan：`~/cmk-project/code-cli-config/sdd-cli-plan.md`
+[打开 Star History 趋势图](https://star-history.com/#basketballnotfound-mankun/superflow-cli&Date)
 
 ## 许可证