@chenmk/superflow 0.4.0 → 0.5.0

package/INSTALL.en.md

@@ -3,8 +3,7 @@
 [中文教程](./INSTALL.md)
 
 SuperBridge Flow installs OpenSpec, Superpowers, skills, hooks or command
-aliases, scripts, rules, and handoff state for Claude Code, Codex, and
-OpenCode.
+aliases, scripts, rules, and handoff state for Claude Code and Codex.
 
 ## 1. Install
 
@@ -12,6 +11,11 @@ OpenCode.
 npm install -g @chenmk/superflow
 ```
 
+The repository `install.sh` and `install.ps1` scripts detect the Codex/Claude
+Hosts actually installed and register their managed MCP entries together with
+CLI, Skills, and Hooks. Single and non-default Host combinations are not forced
+through `both`; only restart the detected Hosts after installation.
+
 ## 2. Initialize A Project
 
 ```bash
@@ -43,9 +47,50 @@ SUPERFLOW_LANG=en superflow init
 7. Register hooks and rules.
 8. Scaffold `docs/sdd-context/`.
 
-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.
+### 2.1 Register The Managed MCP (Recommended)
+
+To start managed delivery directly from the current Codex or Claude host while
+Superflow launches only the peer executor in the background, register the stdio
+MCP server:
+
+```bash
+superflow mcp install --agent both
+superflow mcp status --agent both
+```
+
+Restart Codex and Claude after registration. The current host remains responsible
+for user interaction and independent review. MCP-created tasks always use
+`external_host`, so Superflow does not launch another supervisor CLI of the same
+type. This avoids duplicated context, nested-session authentication retries, and
+duplicate supervisor token usage.
+
+Use `superflow_managed_wait` for a local wait of up to twelve hours by default.
+An active request exposes healthy progress through standard MCP progress
+notifications. One checkpoint does not wake Host; two consecutive checkpoints
+without an effective milestone return for attention, without repeating large
+evidence payloads. When a task reaches `waiting_for_host_review`, the current host performs
+one complete review and submits the structured result. Superflow then enters a
+three-stage delivery state and never commits, pushes, deploys, or writes to production automatically.
+
+To remove the registration:
+
+```bash
+superflow mcp remove --agent both
+```
+
+Superflow no longer provides a background supervisor CLI mode. Historical tasks
+are migrated to direct host review on resume, and no entry point starts a second
+supervisor Agent process.
+
+Verify the registrations with:
+
+```bash
+codex mcp get superflow
+claude mcp get superflow
+```
+
+OpenSpec and Superpowers are required for the full workflow. understand-anything
+is best-effort.
 
 ## 3. Daily Workflow
 
@@ -61,12 +106,6 @@ In Claude Code:
 /superflow-pipeline
 ```
 
-In OpenCode:
-
-```text
-/superflow-pipeline
-```
-
 The workflow phases are:
 
 ```text
@@ -120,13 +159,16 @@ export SUPERFLOW_UPDATE_MIN_INTERVAL_SECONDS=21600
 ```
 
 Team environments should keep `check`. Personal machines may choose `apply`.
+In `apply` mode, package upgrades are followed by the newly installed CLI, which
+redeploys Skills, Hooks, rules, scripts, and managed MCP registrations. Partial
+failure removes the throttle stamp and remains eligible for the next-session retry.
+Restart the Agent after success to load the new MCP process.
 
 ## 6. Uninstall
 
 ```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 和 OpenCode 的 SDD 开发工作流 CLI。它把
+`@chenmk/superflow` 是面向 Claude Code 和 Codex 的 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 或 OpenCode 至少一个 | `claude --version` / `codex --version` / `opencode --version` |
+| Agent | Claude Code、Codex 至少一个 | `claude --version` / `codex --version` |
 | Shell | macOS/Linux 原生 shell；Windows 使用 Git Bash 或兼容 shell | `bash --version` |
 | Python | hook 中的 Python 脚本需要 | `python3 --version` |
 
@@ -68,6 +68,9 @@ macOS/Linux 也可以使用仓库里的脚本：
 bash install.sh
 ```
 
+源码安装脚本会自动检测本机已有的 Codex/Claude，完成 CLI、Skills/Hooks 和对应
+托管 MCP 注册；任意单侧或组合安装都不会被强行注册成 `both`。完成后只需重启检测到的 Agent。
+
 Windows PowerShell：
 
 ```powershell
@@ -83,7 +86,7 @@ cd your-project
 superflow init
 ```
 
-CLI 会弹出工具选择列表。你可以只选 Codex、只选 Claude Code、只选 OpenCode，
+CLI 会弹出工具选择列表。你可以只选 Codex、只选 Claude Code，
 也可以选择多个工具。
 选择结果会替代手写 `--agent codex` / `--agent claude`。
 
@@ -94,13 +97,12 @@ CLI 会弹出工具选择列表。你可以只选 Codex、只选 Claude Code、
 3. 在当前项目目录执行 OpenSpec 原生初始化，并把你选择的工具下发给
    OpenSpec，例如 `openspec init <project> --tools claude,codex --profile custom`。
 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/command 脚本；Codex 写入 `hooks.json`，Claude Code 写入
-   `settings.json`，OpenCode 写入 `.opencode/commands`。
+   `settings.json`。
 8. 部署 SuperBridge Flow 防漂移规则。
 9. 初始化 `docs/sdd-context/` 项目上下文模板，并提示
    understand-anything 扫描状态。
@@ -111,9 +113,8 @@ CLI 会弹出工具选择列表。你可以只选 Codex、只选 Claude Code、
 请选择要初始化的 agent 工具（可多选）：
   1) Claude Code
   2) Codex
-  3) OpenCode
-  a) 安装 Claude Code + Codex（默认）；输入 all 会包含 OpenCode
-输入序号，例如 1,2 / 2,3 / all / a：
+  a) 安装 Claude Code + Codex（默认）
+输入序号，例如 1,2 / all / a：
 ```
 
 选择结果会同时影响：
@@ -128,10 +129,8 @@ CLI 会弹出工具选择列表。你可以只选 Codex、只选 Claude Code、
 
 | 命令 | 说明 |
 |------|------|
-| `superflow init` | 交互式初始化，可多选 Codex / Claude Code / OpenCode |
+| `superflow init` | 交互式初始化，可多选 Codex / Claude Code |
 | `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 |
@@ -165,14 +164,42 @@ superflow scan --language en --force
 `scan` 默认保留已经编辑过的文件；加 `--force` 才会覆盖
 `docs/sdd-context/` 下的 4 个模板文件。
 
-初始化后建议重启 Claude Code、Codex 或 OpenCode，让 agent 重新加载技能列表。
+初始化后建议重启 Claude Code 或 Codex，让 agent 重新加载技能列表。
+
+### 3.1 注册托管 MCP（推荐）
+
+如果希望直接在当前 Codex 或 Claude 主 Agent 会话中发起托管，并由 Superflow
+在后台只启动对端研发 Agent，请注册 stdio MCP：
+
+```bash
+superflow mcp install --agent both
+superflow mcp status --agent both
+```
+
+注册完成后重启 Codex/Claude。当前主 Agent 继续负责与用户沟通和独立评审，MCP
+创建的任务固定使用 `external_host`，不会再额外启动一个同类型 Supervisor CLI。
+因此可以避免重复传递完整上下文、嵌套会话 401 重试，以及监督侧 Token 重复消耗。
+
+托管期间应使用 `superflow_managed_wait` 默认最长等待 12 小时；活动请求通过标准 MCP
+progress notification 展示健康进度，单个监督点不会唤醒，连续两个无有效里程碑才返回，
+不会通过模型回合做固定频率轮询或重复回传大段证据。任务进入
+`waiting_for_host_review` 后，当前主 Agent 一次性完成全量
+评审并提交结构化结果。进入三段交付状态之一后停止，不会自动提交、推送、部署或写入生产环境。
+
+如需移除注册：
+
+```bash
+superflow mcp remove --agent both
+```
+
+Superflow 不再提供后台 Supervisor CLI 模式。历史任务恢复时会自动迁移为当前 Host
+直接评审，任何入口都不会再启动第二个监督 Agent 进程。
 
 ## 4. 验证安装
 
 ```bash
 superflow doctor --agent codex
 superflow doctor --agent claude
-superflow doctor --agent opencode
 ```
 
 也可以同时检查两侧：
@@ -181,6 +208,13 @@ superflow doctor --agent opencode
 superflow doctor
 ```
 
+若已注册托管 MCP，还可以检查两侧配置：
+
+```bash
+codex mcp get superflow
+claude mcp get superflow
+```
+
 `doctor` 会检查：
 
 - `superflow` CLI 是否在 PATH。
@@ -188,7 +222,7 @@ superflow doctor
 - Superpowers、understand-anything、api-doc-changelog 是否可检测。
 - SuperBridge Flow skills 是否完整。
 - hook 脚本是否存在。
-- hook 是否已注册；OpenCode 当前检查 command alias，不把原生 hook 作为硬门禁。
+- hook 是否已注册。
 - SDD rule 是否已部署。
 - 当前项目里的 `.sdd/state.yaml` 是否符合状态机字段约束。
 
@@ -196,7 +230,6 @@ superflow doctor
 
 ```bash
 superflow pipeline --agent codex
-superflow pipeline --agent opencode
 superflow docs --agent codex
 superflow design --agent codex
 superflow implement --agent codex
@@ -208,21 +241,18 @@ superflow archive --agent codex
 
 ### 5.1 开始一个完整需求
 
-Codex、Claude Code 和 OpenCode 的触发方式不同：
+Codex、Claude Code 的触发方式不同：
 
 - 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` 等阶段命令。
@@ -239,12 +269,6 @@ Codex、Claude Code 和 OpenCode 的触发方式不同：
 /superflow-pipeline 处理这个需求：……
 ```
 
-在 OpenCode 会话里同样可以运行：
-
-```text
-/superflow-pipeline 处理这个需求：……
-```
-
 两种方式都会从 SDD 总入口路由，通常按下面阶段推进。
 
 #### 示例：读取飞书在线文档中的某个小节
@@ -491,7 +515,7 @@ Claude Code 里也可以直接用当前阶段命令继续，例如：
 
 - `@chenmk/superflow`
 - `@fission-ai/openspec`
-- Claude Code / Codex 的 Superpowers 插件；OpenCode 侧刷新 SuperBridge Flow assets
+- Claude Code / Codex 的 Superpowers 插件
 
 同一会话只检查一次；默认只提示，不自动安装。至少间隔 6 小时才真正访问
 npm/plugin 源，避免每次 prompt 都联网。可用：
@@ -503,7 +527,7 @@ export SUPERFLOW_AUTO_UPDATE=check
 # 关闭自动检查
 export SUPERFLOW_AUTO_UPDATE=0
 
-# 个人机器可选：检查到新版本后自动安装
+# 个人机器可选：自动完整更新 CLI、Skills、Hooks、规则、脚本和托管 MCP
 export SUPERFLOW_AUTO_UPDATE=apply
 
 # 调整最小检查间隔，默认 21600 秒（6 小时）
@@ -514,6 +538,10 @@ export SUPERFLOW_UPDATE_MIN_INTERVAL_SECONDS=21600
 `superflow update --with-package` 更新；个人机器如果接受自动升级风险，再设置
 `SUPERFLOW_AUTO_UPDATE=apply`。
 
+显式更新和 Hook `apply` 使用同一闭环：先更新依赖包，再由新版本 CLI 重新部署全部 Agent
+资产并刷新 MCP 注册。任一步失败会记录日志、删除本轮节流戳并允许下次会话重试；成功后需
+重启 Agent 才会加载新的 MCP 进程。
+
 ### 8.2 手动更新
 
 只刷新已安装技能、脚本、规则和 hook：
@@ -529,8 +557,8 @@ superflow update --agent claude
 superflow update --with-package
 ```
 
-该命令会统一更新 `@chenmk/superflow`、`@fission-ai/openspec` 和已选择
-agent 的 Superpowers 插件。
+该命令会统一更新 `@chenmk/superflow`、`@fission-ai/openspec`、已选择 agent 的
+Superpowers 插件、Skills、Hooks、规则、脚本和托管 MCP 注册。
 
 只查看更新计划：
 
@@ -599,13 +627,11 @@ python3 --version
 
 ### 技能装好了，但 agent 没触发
 
-重启 Claude Code、Codex 或 OpenCode。若仍不触发：
+重启 Claude Code 或 Codex。若仍不触发：
 
 ```bash
 superflow doctor --agent codex
-superflow doctor --agent opencode
 superflow pipeline --agent codex
-superflow pipeline --agent opencode
 ```
 
 然后在会话里明确说：

package/README.md

@@ -44,14 +44,16 @@ real verified delivery. SuperBridge Flow makes that gap explicit:
   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.
+state, and dependency guards for Claude Code and Codex.
 
 ## Highlights
 
-- **Dual-Agent managed delivery.** The current Agent supervises while the peer
-  Agent develops, starts, and verifies through a non-interactive CLI. Repair
-  rounds resume exact sessions and are capped at 5 reviews, 7 executor calls,
-  and 12 total calls. Durable journals allow recovery after terminal or network
+- **Dual-Agent managed delivery.** The current host Agent reviews directly while
+  the peer Agent develops, starts, and verifies in one CLI session without a
+  tool-turn limit, then actively returns one structured result. A later session
+  is created only for review repair, process failure, or human recovery. Review
+  and execution default to 5 reviews, 7 executor calls, and 12 total calls.
+  Durable journals allow recovery after terminal or network
   interruption, and passing work stops for explicit Git approval.
 - **9 catalogued failure modes, blocked at the gate.** Nine real ways AI breaks
   in production — swallowing the whole PRD then forgetting details, editing
@@ -86,17 +88,50 @@ state, and dependency guards for Claude Code, Codex, and OpenCode.
   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.
-- **`superflow check` audits document completeness.** Runs against a 13-item
-  required-file checklist per change. Missing a required doc? Exit 1. No more
-  surprises at the implement phase — the gate catches gaps while you're still
-  in docs.
+- **`superflow check` audits delivery readiness by level.** `files` checks the
+  required set, `docs` adds every-prompt links, independent reviews, and complex
+  diagrams, while `coding-ready` adds environment preflight plus the complete
+  docs/design/implement gates and writes a receipt bound to the current handoff hash.
 - **`superflow config` tunes review depth per change.** `--review-mode
-  off|standard|thorough` controls code-review intensity; `--auto-transition`
+off|standard|thorough` controls code-review intensity; `--auto-transition`
   controls automatic phase progression. Match the rigor to the risk.
 - **Startup version check.** Every superflow command silently compares your
   installed version against the npm registry. A new version triggers a
   non-blocking upgrade hint on stderr.
 
+## Managed delivery: a bounded review loop
+
+![A bounded review loop: task and contract enter, review returns fixes to
+implementation, and only a passing result reaches delivery.](./assets/brand/managed-review-loop.png)
+
+Give Superflow a straightforward development task or a frozen Superflow / SDD
+contract. The peer Agent implements and verifies; the current Host reviews the
+workspace, gates, and evidence.
+
+```text
+Task or frozen contract
+          ↓
+Peer Agent builds and verifies
+          ↓
+Current Host reviews source, gates, and evidence
+     ├─ needs_fix → findings + prior evidence → Peer Agent ↺
+     └─ pass → delivery-ready state → waits for your Git / release approval
+```
+
+The loop is deliberately bounded, not an unattended agent swarm:
+
+- The Host owns semantic review; the peer owns source changes and verification.
+- A failed review returns precise findings and durable evidence, so the peer
+  repairs the current workspace instead of restarting from a blank prompt.
+- Default budgets cap the work at 5 Host reviews, 7 peer invocations, and 12
+  total Agent calls. Journals make interruption recovery auditable.
+- A pass means the frozen delivery contract is satisfied. It never means an
+  absolute risk guarantee, and it never auto-commits, pushes, deploys, or
+  writes to production.
+
+Read the [managed delivery loop guide](./docs/managed-delivery-loop.en.md) for
+the role boundary, transition rules, and recovery behavior.
+
 ## Workflow
 
 ```text
@@ -105,13 +140,13 @@ 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 |
+| 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
 
@@ -119,6 +154,10 @@ Each phase has a clear owner and an exit gate:
 npm install -g @chenmk/superflow
 ```
 
+For a source checkout, `bash install.sh` detects installed Codex, Claude, and
+Codex and Claude Hosts and installs CLI, Skills/Hooks, and their managed MCP registrations
+in one pass. Restart the detected Hosts afterwards.
+
 Then initialize a project:
 
 ```bash
@@ -127,7 +166,7 @@ superflow init
 
 Interactive init lets you select:
 
-- target agent tools: Claude Code, Codex, OpenCode, or selected combinations
+- target agent tools: Claude Code, Codex, or both
 - language: English or Chinese
 - install scope: global or project
 
@@ -150,11 +189,97 @@ Manage an implementation prompt, OpenSpec change, or direct development task:
 
 ```bash
 superflow pipeline "<prompt path, change directory, or task>" --managed \
-  --project "<project root>"
+  --project "<project root>" --supervisor current --executor peer
 ```
 
 The selected language is frozen into the task contract and reused by Agent
 prompts, reviews, journals, reports, notifications, and resumed rounds.
+The first executor invocation runs continuously without a Superflow tool-turn
+limit, while the current host agent reviews directly instead of the service
+spawning a nested copy. The first invocation receives the frozen task prompt;
+later repair or recovery invocations receive a condensed handoff so a new
+session can continue from the workspace, pending tasks, and complete review
+findings. When the
+task reports `external_supervisor_review_required`, submit the review and resume:
+
+```bash
+superflow pipeline --resume-task <task-id> --submit-host-review <review.json>
+```
+
+### Interact from the current host Agent (recommended MCP path)
+
+Register the bundled local stdio MCP server for Codex or Claude:
+
+```bash
+superflow mcp install --agent both
+```
+
+After restarting the host Agent session, keep talking to the current Codex or
+Claude Agent. The host uses MCP to supervise while Superflow starts only the
+peer executor:
+
+- `superflow_managed_start` freezes the task and always uses `external_host`.
+- `superflow_managed_status` and `superflow_managed_list` expose state and evidence.
+- `superflow_managed_wait` defaults to a 240-second compatible transport window;
+  Hosts with longer tool limits may explicitly request up to twelve hours. Window
+  expiry continues compactly from `latestSequence`. Active requests expose healthy
+  progress through standard MCP notifications, while two checkpoints without an
+  effective milestone return for semantic attention.
+- `superflow_managed_message` carries user guidance to the current execution
+  boundary or the next handoff.
+- `superflow_managed_authorize_executor` freezes task-scoped repository consent without bypassing host DLP.
+- `superflow_managed_pause` and `superflow_managed_resume` interrupt the active executor, persist pause, and resume from state.
+- `superflow_managed_submit_review` submits one complete structured host review.
+- `superflow_managed_record_validation` records environment/release evidence and recomputes three-stage delivery.
+
+Claude Executors receive neither `--max-turns` nor `--max-budget-usd`, so normal
+work is not split by a fixed tool-step count or an inaccurate provider-dollar
+estimate. The defaults stop a process after 60 minutes with no output or a
+two-hour single-invocation deadline. Repeated provider failures,
+token/invocation budgets, safety boundaries, and user pause still stop
+execution. Safe Java, Maven, Node, and npm executable paths found during
+preflight are written into the executor policy to avoid redundant environment
+discovery.
+To prevent a 1M context window from multiplying input tokens across hundreds of
+tool turns, Claude Executors default to early auto-compaction at 70 percent of a
+200K effective window. Explicit Claude environment settings win, and the frozen
+prompt plus handoff are reloaded after compaction.
+
+MCP mode never starts a nested supervisor CLI. Host conversation and review do
+not consume the background Agent invocation budget; only real executor calls do.
+Passing delivery enters `environment_validation_blocked`, `local_delivery_ready`,
+or `release_ready` according to three-track progress, without automatic commit,
+push, deployment, or production writes.
+
+Managed work uses three default circuit breakers: the same mechanical delivery
+error receives only one automatic repair, no more than two automatic repairs run
+before escalation to the current host, and the next executor call is stopped at
+two million cumulative token units. Dollar pricing is not comparable across
+model providers, so the default contract has no USD circuit and Claude receives
+no `--max-budget-usd`. Three or more permission denials in one invocation also
+suppress another executor retry. The Runner derives changedFiles, baseline task
+evidence, and verification categories from the real workspace and commands
+instead of spending full executor rounds repairing JSON.
+
+Inspect or remove the integration with:
+
+```bash
+superflow mcp status --agent both
+superflow mcp remove --agent both
+```
+
+MCP is the communication channel between the host Agent and the local managed
+state machine, not a third model. Host data-disclosure policy for an external
+executor provider remains separate from local filesystem access.
+An existing task prompt uses a full contract, a direct engineering request gets a
+standard execution contract, and even a one-line request receives a minimal
+implementation and verification plan before the executor starts.
+
+Design and field evidence:
+
+- [Cross-Agent Managed Work implementation plan](docs/cross-agent-development-implementation-plan.en.md)
+- [Managed Work design principles](docs/managed-work-design-principles.en.md)
+- [Managed Agent protocol](docs/managed-agent-protocol.en.md)
 
 ## What Init Installs
 
@@ -176,29 +301,28 @@ best-effort and does not block initialization.
 
 ## Commands
 
-| 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 pipeline "<task>" --managed --project <path>` | Run Dual-Agent managed development to a terminal delivery state |
-| `superflow docs` | Check docs-phase skill deployment |
-| `superflow design` | Check design-phase skill deployment |
-| `superflow implement` | Check implement-phase skill deployment |
-| `superflow verify` | Check verify-phase skill deployment |
-| `superflow archive` | Check archive-phase skill deployment |
-| `superflow check <change>` | Audit 13-file SDD document completeness |
-| `superflow config <change> --review-mode <mode>` | Set review depth (off/standard/thorough) |
-| `superflow config <change> --auto-transition <bool>` | Toggle automatic phase progression |
-| `superflow status` | List active changes with phase, tasks, and doc gaps |
-| `superflow update --with-package` | Update superflow, OpenSpec, and Superpowers |
+| Command                                                      | Purpose                                                                  |
+| ------------------------------------------------------------ | ------------------------------------------------------------------------ |
+| `superflow init`                                             | Install and configure SuperBridge Flow interactively                     |
+| `superflow update`                                           | Refresh installed skills, hooks, scripts, and rules                      |
+| `superflow update --with-package`                            | Also update `@chenmk/superflow`, OpenSpec, and Superpowers               |
+| `superflow doctor`                                           | Diagnose CLIs, MCP runtime paths, 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 pipeline "<task>" --managed --project <path>`     | Run short-session execution with direct review by the current host agent |
+| `superflow docs [change]`                                    | Run the docs gate and check the phase skill                              |
+| `superflow design`                                           | Check design-phase skill deployment                                      |
+| `superflow implement [change]`                               | Create a current Coding Ready receipt before implementation              |
+| `superflow verify`                                           | Check verify-phase skill deployment                                      |
+| `superflow archive`                                          | Check archive-phase skill deployment                                     |
+| `superflow check <change> --level files\|docs\|coding-ready` | Audit file, document-delivery, or coding readiness                       |
+| `superflow config <change> --review-mode <mode>`             | Set review depth (off/standard/thorough)                                 |
+| `superflow config <change> --auto-transition <bool>`         | Toggle automatic phase progression                                       |
+| `superflow status`                                           | List active changes with phase, tasks, and doc gaps                      |
+| `superflow eval <taskPath> [--json]`                         | Evaluate managed quality, calls, tokens, cache, and time offline         |
+| `superflow update --with-package`                            | Update superflow, OpenSpec, and Superpowers                              |
 
 ## Agent Usage
 
@@ -214,16 +338,6 @@ 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. The total router automatically uses embedded deep clarification when a
 feature needs an owner decision; it investigates available facts first and asks
@@ -253,13 +367,18 @@ export SUPERFLOW_AUTO_UPDATE=check
 # Disable automatic checks
 export SUPERFLOW_AUTO_UPDATE=0
 
-# Optional for personal machines: install automatically when updates are found
+# Optional: update packages, Skills, Hooks, rules, scripts, and managed MCP
 export SUPERFLOW_AUTO_UPDATE=apply
 
 # Minimum check interval in seconds; default is 21600
 export SUPERFLOW_UPDATE_MIN_INTERVAL_SECONDS=21600
 ```
 
+`apply` re-enters the newly installed CLI after package upgrade and refreshes all
+detected Agent assets plus managed MCP registrations. A partial failure keeps its
+log and removes the throttle stamp so the next session can retry. Restart the
+Agent after success because an existing MCP process cannot hot-load the upgrade.
+
 ## Language Support
 
 SuperBridge Flow supports English and Chinese installation modes.
@@ -275,10 +394,15 @@ keeps the same workflow contracts.
 ## Requirements
 
 - Node.js 20+
-- Claude Code, Codex, or OpenCode
+- Claude Code or Codex
 - npm access to install OpenSpec and Superpowers
 - Git Bash or a compatible shell on Windows for hook scripts
 
+On Windows, managed work resolves Agent `.exe/.cmd/.bat` shims and stops the
+complete Agent process tree on pause or timeout. macOS/Linux keep detached
+process groups; none of the three Agent launch paths concatenates commands in a
+general-purpose shell.
+
 ## Star History
 
 The chart is generated by Star History from public GitHub star data. It may stay