@chenmk/superflow 0.3.0 → 0.5.0

package/README.md

@@ -44,10 +44,17 @@ 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 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
   only the setter while missing consumers, SQL drift across dev/test/DB
@@ -81,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
@@ -100,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
 
@@ -114,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
@@ -122,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
 
@@ -141,12 +185,111 @@ superflow --language en --help
 SUPERFLOW_LANG=en superflow init
 ```
 
+Manage an implementation prompt, OpenSpec change, or direct development task:
+
+```bash
+superflow pipeline "<prompt path, change directory, or task>" --managed \
+  --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
 
 `superflow init` installs and configures:
 
 - OpenSpec CLI, then runs `openspec init <project> --tools ...`
-- Superpowers for the selected agent tools
+- Superpowers for the selected agent tools. Codex uses the official
+  `superpowers@openai-api-curated` plugin, including
+  `verification-before-completion`, `requesting-code-review`, and
+  `finishing-a-development-branch`.
 - SuperBridge Flow/OpenSpec skills
 - hooks, scripts, and anti-drift rules
 - Codex prompt aliases
@@ -158,28 +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 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
 
@@ -195,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
@@ -234,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.
@@ -256,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

package/README.zh-CN.md

@@ -27,7 +27,7 @@
 
 # SuperBridge Flow
 
-通用 SDD 开发工作流 CLI，支持 Claude Code、Codex 和 OpenCode。
+通用 SDD 开发工作流 CLI，支持 Claude Code 和 Codex。
 
 SuperBridge Flow 不是简单“装两个工具”，而是把 OpenSpec/SDD 和
 Superpowers 编排成一个有状态的研发流程：前者负责需求、合同和验收口径，
@@ -38,11 +38,14 @@ CLI 会把 SuperBridge Flow 技能、配套 hook/command 脚本整合为单一 n
 
 - Claude Code：`~/.claude/skills/`、`~/.claude/scripts/`，并注册 `~/.claude/settings.json` hook
 - Codex：`~/.codex/skills/`、`~/.codex/hooks/`
-- OpenCode：`.opencode/skills/`、`.opencode/commands/`、`.opencode/scripts/`
-  或全局 `~/.config/opencode/`
 
 ## 亮点
 
+- **双 Agent 托管到真实交付。** 当前 Host Agent 直接监督，另一个 Agent 在一次不限制工具
+  轮数的 CLI 会话中持续开发、启动和验证，完成后主动返回结构化结果；只有评审整改、进程异常
+  或人工恢复才创建后续会话。工作区与落盘 finding 负责交接，默认最多 5 轮评审、7 次执行、
+  12 次总调用。
+  状态和证据全部落盘，终端或网络中断后可恢复，最终停在等待 Git 批准。
 - **9 类翻车场景，沉淀成门禁。** 我们见过的 AI 翻车——需求一次吞、字段漏查消费者、SQL 漂移、mock-only 报告、跨服务只看到"能调"……9 种典型形态都被固化成 guard，AI 想跳过都不行。
 - **跨服务代码必须先答架构 6 问。** 涉及跨仓、跨服务、SDK、MQ、设备、回调、网关的改动，技术详设里必须先回答：owner 是谁、调用方向、新入口是否允许、禁止路径、证据锚点——答不全不让进入实现。
 - **改字段之前先填"字段与状态反向影响"矩阵。** 任何 schema、状态、枚举的改动，必须枚举写入点、读取点、过滤点、派生 / 同步点、跨模块消费者、测试覆盖，还要列反向恢复场景（下线后重上线、旧值不可用但上游没传字段、历史脏数据被新过滤条件消费）。
@@ -50,47 +53,78 @@ CLI 会把 SuperBridge Flow 技能、配套 hook/command 脚本整合为单一 n
 - **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 全是流程强制，不靠用户自觉。
-- **`superflow check` 一键诊断文档缺口。** 对照 13 项必备 SDD 文件逐项核验，缺失即 exit 1。再也不会进了 implement 才发现 proposal 没写——check 在 docs 阶段就拦住你。
+- **`superflow check` 分级诊断交付就绪度。** `files` 检查必备文件，`docs` 增加逐 Prompt 链接、多轮评审和复杂流程图检查，`coding-ready` 再执行环境预检及 docs/design/implement 全门禁，并生成绑定当前 handoff hash 的可编码凭证。
 - **`superflow config` 按需调整审查强度。** `--review-mode off|standard|thorough` 控制代码审查深度；`--auto-transition` 控制阶段自动流转。不同改动匹配不同强度，省 token 不省质量。
 - **启动自动检查新版本。** 每次执行 superflow 命令，后台静默对比 npm registry。发现新版本时 stderr 输出升级提示，不阻塞、不拖慢。
 
+## 托管交付：有上限的评审—整改闭环
+
+![有上限的评审闭环：任务或合同进入，评审把问题送回实现，只有通过才进入交付。](./assets/brand/managed-review-loop.png)
+
+你可以给 Superflow 一条简单开发任务，也可以给它一份冻结的 Superflow / SDD
+合同。对端 Agent 负责实现和验证；当前正在与你对话的 Host 负责审查工作区、门禁和证据。
+
+```text
+简单任务或冻结合同
+        ↓
+对端 Agent 实现并验证
+        ↓
+当前 Host 审查源码、门禁与证据
+   ├─ 未通过 → finding + 历史证据 → 对端 Agent 整改 ↺
+   └─ 通过 → 进入交付就绪状态 → 等待你决定 Git / 发布
+```
+
+这是一个刻意有上限的工程闭环，不是无人看管的 Agent 群：
+
+- Host 只负责语义评审；对端只负责改源码和做验证，职责不混淆。
+- 评审未通过时，系统会带着精确 finding 和已经有效的证据回到对端；它在当前工作区整改，不会拿一份空 Prompt 从头猜。
+- 默认最多 5 轮 Host 评审、7 次对端调用、12 次总调用；账本让中断后的恢复可审计。
+- 通过只表示满足冻结的交付合同，不表示“绝对无风险”；系统也绝不会自动提交、推送、部署或写生产。
+
+完整角色边界、状态流转与恢复规则见[托管交付闭环说明](./docs/managed-delivery-loop.md)。
+
 ## 工作流
 
 ```text
 docs -> design -> implement -> verify -> archive
 ```
 
-| 阶段 | 主责 | 产物 |
-|------|------|------|
-| `docs` | OpenSpec/SDD | 需求、接口、数据库、测试和验收合同 |
-| `design` | Superpowers | 源码级技术详设、影响面分析和 TDD 计划 |
+| 阶段        | 主责                           | 产物                                   |
+| ----------- | ------------------------------ | -------------------------------------- |
+| `docs`      | OpenSpec/SDD                   | 需求、接口、数据库、测试和验收合同     |
+| `design`    | Superpowers                    | 源码级技术详设、影响面分析和 TDD 计划  |
 | `implement` | Superpowers + SuperBridge Flow | 分批任务 prompt、review 门禁和执行状态 |
-| `verify` | SuperBridge Flow hooks | 有证据的测试报告、真实入口和联调校验 |
-| `archive` | OpenSpec/SDD | 归档后的 spec 状态和生命周期闭环 |
+| `verify`    | SuperBridge Flow hooks         | 有证据的测试报告、真实入口和联调校验   |
+| `archive`   | OpenSpec/SDD                   | 归档后的 spec 状态和生命周期闭环       |
 
 ## 安装
 
 ```bash
 npm install -g @chenmk/superflow
+# 或本地源码：
+# git clone https://github.com/.../superflow-cli && cd superflow-cli && bash install.sh
 ```
 
 完整安装、初始化和日常使用教程见 [INSTALL.md](./INSTALL.md)。
 
+从源码执行 `bash install.sh` 时，会检测本机已有的 Codex、Claude，并一次完成
+CLI、Skills/Hooks 与对应托管 MCP 注册；安装后重启检测到的 Agent 即可。
+
+> **💡 装完即全局生效，无需逐项目 init**：`npm install -g @chenmk/superflow`（或 `bash install.sh`）会自动把 superflow hooks 注册到 `~/.claude/settings.json`（全局），**本机上所有项目仓库**都获得 superflow 守门。钩子内部靠 `.sdd-enforced` 标记懒激活（没跑 `superflow clarify` 之前所有钩子静默放行，零干扰）。
+>
+> 只有需要项目级产物（OpenSpec change 目录 / `.sdd/` 任务文件 / 团队约定）时，才在项目根目录跑 `superflow init`。**绝大多数项目不需要这一步**——hooks 已经在全局生效了。
+
 ## 快速开始
 
+> ⚠️ `superflow init` **通常不需要再跑**——参见上文「装完即全局生效」。下面这些命令只在你想加项目级产物或显式重置时使用。
+
 ```bash
-# 交互式选择 Claude Code / Codex / OpenCode（可多选）
+# 交互式选择 Claude Code / Codex（可多选）
 superflow init
 
-# 非交互模式，默认同时安装 Claude Code + Codex
+# 非交互模式，默认同时安装 Claude Code + Codex（默认 --scope global）
 superflow init --yes
 
-# 显式安装 OpenCode
-superflow init --agent opencode
-
-# 同时安装 Claude Code + Codex + OpenCode
-superflow init --agent all
-
 # 跳过 hook 注册（手工管理）
 superflow init --no-hooks
 
@@ -115,6 +149,83 @@ export SUPERFLOW_LANG=en
 superflow init
 ```
 
+托管一个 implementation prompt、OpenSpec change 或简单开发任务：
+
+```bash
+superflow pipeline "<prompt 路径、change 目录或任务>" --managed \
+  --project "<项目根目录>" --supervisor current --executor peer
+```
+
+语言会冻结进任务合同；执行 Prompt、评审、账本、报告、通知和恢复轮次保持一致。
+执行 Agent 每轮使用全新短会话；当前 Host Agent 直接评审，不再由后台启动第二个同名
+CLI。首轮自动使用冻结任务 Prompt，后续每轮生成压缩交接包，因此旧会话或新会话均能从
+当前工作区、剩余任务和完整评审意见继续。任务提示 `external_supervisor_review_required`
+后，提交结构化评审并恢复：
+
+```bash
+superflow pipeline --resume-task <任务编号> --submit-host-review <review.json>
+```
+
+### 在主 Agent 中直接交互（MCP，推荐）
+
+安装 Superflow 后，将本地 stdio MCP 注册到 Codex、Claude：
+
+```bash
+superflow mcp install --agent both
+```
+
+重启主 Agent 会话后，用户继续直接与当前 Codex/Claude 对话。主 Agent 通过 MCP
+创建和监督任务，Superflow 后台只启动对端研发 Agent：
+
+- `superflow_managed_start`：冻结任务并启动研发执行；固定为 `external_host`。
+- `superflow_managed_status` / `superflow_managed_list`：读取状态、调用账本和证据。
+- `superflow_managed_wait`：默认用 240 秒兼容传输窗口，支持长调用的 Host 可显式提高到
+  12 小时；窗口超时只按 `latestSequence` 紧凑续接。活动请求用标准 MCP progress
+  notification 展示健康进度，连续两个无有效里程碑才返回语义监督。
+- `superflow_managed_message`：把用户补充、环境授权和澄清写入当前运行边界或下一轮交接。
+- `superflow_managed_authorize_executor`：冻结任务级仓库范围和源码处理授权，不绕过宿主 DLP。
+- `superflow_managed_pause` / `superflow_managed_resume`：中断当前研发 Agent、持久化暂停并恢复。
+- `superflow_managed_submit_review`：当前主 Agent 一次性提交全量结构化评审。
+- `superflow_managed_record_validation`：记录环境/发布证据并重算三段交付状态。
+
+MCP 模式禁止启动嵌套 Supervisor CLI。当前主 Agent 的对话、监督和评审不计入
+Superflow 后台 Agent 调用；只有研发 Agent 的真实调用计入执行预算。任务通过后按实际
+进度进入 `environment_validation_blocked`、`local_delivery_ready` 或 `release_ready`，
+MCP 不自动 commit、push、部署或写生产环境。
+
+托管默认使用三层止损：同类机械交付错误只自动整改一次、累计最多两次自动整改后转当前
+Host；累计 200 万 Token 单位后停止下一次调用；单轮出现 3 次及以上权限拒绝时直接交由
+Host 判断。不同模型供应商的美元计价不可比，因此默认不使用美元预算熔断，也不向 Claude
+传 `--max-budget-usd`。changedFiles、基础 taskEvidence 和验证类别由 Runner 根据工作区与
+真实命令补全，不再消耗完整研发轮次修 JSON 格式。
+
+Claude Executor 默认不传 `--max-turns` 或 `--max-budget-usd`，不会因为固定工具步数或不准确
+的美元估值拆断正常研发。默认连续 60 分钟完全无输出或单次执行达到 2 小时才终止进程；
+连续供应商错误、Token/调用预算、安全边界和用户暂停仍会止损。启动前会把可安全发现的
+Java、Maven、Node 和 npm 可执行路径写入执行策略，减少研发 Agent 重复寻找环境。
+为避免 1M 上下文在数百工具轮次中持续放大输入 Token，Claude Executor 默认按 200K 有效
+窗口、70% 阈值提前自动压缩；用户显式 Claude 环境配置优先，压缩后会重读冻结 Prompt 和
+handoff。
+
+检查或移除配置：
+
+```bash
+superflow mcp status --agent both
+superflow mcp remove --agent both
+```
+
+MCP 是主 Agent 与本地托管状态机的通信通道，不会把 Superflow 变成第三个模型。
+已有任务 Prompt 使用完整合同；直接输入普通工程需求时自动生成标准执行合同；一句简单
+需求也会先生成最小实现与验证任务，不会以空任务清单直接启动研发 Agent。
+宿主仍可能对外部研发 Agent 的模型供应商执行数据披露策略；本机完全访问权限与供应商
+信任是两类独立门禁。
+
+设计与实战证据：
+
+- [跨 Agent 托管实现方案](docs/cross-agent-development-implementation-plan.md)
+- [托管功能设计原则](docs/managed-work-design-principles.md)
+- [托管 Agent 通信协议](docs/managed-agent-protocol.md)
+
 ## SDD 分工
 
 - OpenSpec/SDD 负责 WHAT 和合同：需求、API、DB、SQL、字段语义、tests、真实入口验收和质量门禁。
@@ -126,30 +237,31 @@ superflow init
 
 ## 命令
 
-| 命令 | 说明 |
-|------|------|
-| `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 阶段技能部署 |
-| `superflow implement [task]` | 校验 SuperBridge Flow implement 阶段技能部署 |
-| `superflow pipeline` | 校验 SuperBridge Flow pipeline 阶段技能部署 |
-| `superflow check <change>` | 对照 13 项必备文件清单检查文档完整性 |
-| `superflow config <change> --review-mode <mode>` | 设置代码审查强度（off/standard/thorough） |
-| `superflow config <change> --auto-transition <bool>` | 控制阶段自动流转（true/false） |
-| `superflow status` | 展示所有 active change 的阶段、任务、文档缺口 |
-| `superflow update --with-package` | 更新 superflow 自身和 openspec/superpowers 依赖 |
+| 命令                                                         | 说明                                                        |
+| ------------------------------------------------------------ | ----------------------------------------------------------- |
+| `superflow init`                                             | 一站式安装；交互终端中可多选 Claude Code / Codex |
+| `superflow init --yes`                                       | 非交互安装，默认 `--agent both`                             |
+| `superflow init --dry-run`                                   | 只打印计划不执行                                            |
+| `superflow init --resume`                                    | 从失败步骤继续                                              |
+| `superflow init --no-hooks`                                  | 只装技能 + 脚本，跳过 Codex/Claude hook 注册                |
+| `superflow init --no-openspec-init`                          | 跳过当前项目 OpenSpec 原生初始化                            |
+| `superflow doctor`                                           | 诊断 CLI / MCP / 第三方 / 脚本 / skills                     |
+| `superflow doctor --agent codex`                             | 只诊断 Codex 侧                                             |
+| `superflow doctor --agent both --language en`                | 英文诊断 Codex、Claude 与 MCP 路径                           |
+| `superflow --language en --help`                             | 查看英文 CLI help                                           |
+| `superflow scan --language en`                               | 重新生成英文项目上下文模板                                  |
+| `superflow clarify [feature]`                                | 校验 SuperBridge Flow clarify 阶段技能部署                  |
+| `superflow docs [change]`                                    | 执行 docs 门禁并校验阶段技能                                |
+| `superflow design [change]`                                  | 校验 SuperBridge Flow design 阶段技能部署                   |
+| `superflow implement [change]`                               | 生成当前 Coding Ready 凭证后进入实现阶段                    |
+| `superflow pipeline`                                         | 校验 SuperBridge Flow pipeline 阶段技能部署                 |
+| `superflow pipeline "<任务>" --managed --project <目录>`     | 执行 Agent 短会话开发，当前 Host Agent 直接评审             |
+| `superflow check <change> --level files\|docs\|coding-ready` | 分级检查文件、文档交付或可直接编码就绪度                    |
+| `superflow config <change> --review-mode <mode>`             | 设置代码审查强度（off/standard/thorough）                   |
+| `superflow config <change> --auto-transition <bool>`         | 控制阶段自动流转（true/false）                              |
+| `superflow status`                                           | 展示所有 active change 的阶段、任务、文档缺口               |
+| `superflow eval <taskPath> [--json]`                         | 离线统计托管质量、调用、Token、缓存与耗时                   |
+| `superflow update --with-package`                            | 更新 superflow 自身和 openspec/superpowers 依赖             |
 
 ## 系统支持
 
@@ -157,13 +269,17 @@ superflow init
 - Linux（Ubuntu 20.04+ / 其它主流发行版）
 - Windows 10+（CLI 本体支持；hook 脚本需要 Git Bash 或兼容 shell）
 
+托管运行时会在 Windows 解析 Agent 的 `.exe/.cmd/.bat` shim，并在暂停或超时时终止完整
+Agent 进程树；macOS/Linux 继续使用独立进程组。三端均不通过通用 shell 拼接启动命令。
+
 ## 依赖
 
 - Node.js 20+
-- Claude Code、Codex 或 OpenCode（按 `--agent` 选择）
+- Claude Code、Codex（按 `--agent` 选择）
 - 第三方（`superflow init` 自动装）：
   - openspec CLI（硬依赖，npm 全局）并在当前项目执行 `openspec init --tools ...`
-  - superpowers（Claude Code / Codex 为硬依赖；OpenCode 侧通过已部署 skills/commands 使用流程）
+  - superpowers（Claude Code / Codex 为硬依赖；Codex 自动安装官方
+    `superpowers@openai-api-curated`，确保包含验证、代码评审和分支收尾三个强制技能）
   - understand-anything（尽力安装，失败只警告）
   - api-doc-changelog（辅助 skill，复制到目标 agent skills 目录）
 
@@ -173,7 +289,7 @@ superflow init
 
 - `@chenmk/superflow`
 - `@fission-ai/openspec`
-- Claude Code / Codex 的 Superpowers 插件；OpenCode 侧的 SuperBridge Flow assets
+- Claude Code / Codex 的 Superpowers 插件
 
 推荐策略是“自动检查，手动更新”：默认只提示，不自动安装；执行
 `superflow update --with-package` 才会统一更新。
@@ -186,13 +302,17 @@ export SUPERFLOW_AUTO_UPDATE=check
 # 关闭自动检查
 export SUPERFLOW_AUTO_UPDATE=0
 
-# 个人机器可选：检查到新版本后自动安装
+# 个人机器可选：检查到新版本后完整更新包、Skills、Hooks、规则、脚本和托管 MCP
 export SUPERFLOW_AUTO_UPDATE=apply
 
 # 调整最小检查间隔，默认 21600 秒（6 小时）
 export SUPERFLOW_UPDATE_MIN_INTERVAL_SECONDS=21600
 ```
 
+`apply` 会在包升级后重新进入新版本 CLI，统一刷新所有已检测到的 Agent 资产和 MCP 注册。
+任一步失败都会保留日志和下次会话重试资格，不会把半升级状态标记为成功。升级完成后需要
+重启 Agent，旧会话不会热加载新的 MCP 运行时。
+
 ## Star History
 
 下图由 Star History 根据 GitHub 公开 star 数据动态生成。仓库保持 private