@chenmk/superflow 0.3.0 → 0.4.0

package/assets/skills/superflow-pipeline/references/managed-work.md

@@ -0,0 +1,58 @@
+# 托管任务执行规则
+
+## 入口
+
+托管任务属于 `superflow-pipeline` 内建能力。用户只需说“用 Superflow 托管完成”并给出
+implementation prompt、change 目录或简单任务，不需要知道内部 Skill 名和 CLI 参数。
+简单任务生成最小合同；SDD 任务冻结 Superflow 已生成的 implementation prompt，不以
+`tasks.md` 代替执行 Prompt。
+
+## 角色
+
+- 当前主 Agent：提交任务、查看结果、向用户汇总并申请 Git 批准。
+- 监督 Agent：固定会话、只读检查、生成结构化问题和整改要求。
+- 执行 Agent：固定会话、唯一写入者、实现并完成验证。
+- 后台服务：状态、预算、队列、会话恢复和证据的唯一写入者。
+
+## 必须通过 CLI
+
+不要由聊天中的 Agent 手工启动另一 CLI。调用：
+
+```bash
+superflow pipeline "<implementation-prompt|change-dir|task>" --managed --project "<root>" \
+  --supervisor <codex|claude> --executor <claude|codex> --language <zh|en>
+```
+
+查看：
+
+```bash
+superflow status <root>
+```
+
+托管命令默认启动独立后台服务并监听本地事件账本，直到任务进入交付、阻塞或预算耗尽等
+终态。监听进程退出不影响后台任务。命令返回后，当前 Agent 读取任务报告并在原会话汇总。
+
+## 硬门槛
+
+- 5/7/12 调用上限由状态机先占用后调用，Prompt 无权上调。
+- 语言写入冻结合同；执行 Prompt、账本、报告、通知、错误和恢复轮次始终使用同一语言。
+- 每次启动和恢复都重新校验冻结合同哈希、不可覆盖权限及 5/7/12 硬上限；磁盘文件被
+  改写时按失败关闭，不能继续调用 Agent。
+- change 目录必须通过 `.sdd/state.yaml` 的 `implementation_prompt` 定位执行入口；
+  `tasks.md` 仅作清单。Prompt 原文复制为托管快照并冻结 SHA-256，执行和评审使用同一份。
+- 两个 session ID 必须落盘，禁止 `--last` / `--continue` 猜测。
+- `.superflow/tasks/<task-id>/runs/<run-id>/progress.jsonl` 是追加式事实账本。
+- 执行角色禁止修改托管目录、Git 提交/推送、发布、生产写入、跳过沙箱。
+- 监督角色禁止修改目标文件。
+- Agent 非零退出、非法 JSON、缺 session ID、工作区在检查期间变化都不能判通过。
+- 工程和 SDD 任务至少提供构建、测试、启动/真实调用中的两类成功命令证据；只编译或
+  只跑单元测试不能进入正式检查。
+- 最终通过前运行 `superflow-managed-work-check.mjs <root> <task-id>`。
+- 完整性脚本必须先通过，后台才允许写入唯一的 `run.delivery_ready` 事件；脚本失败时
+  转入等待人工处理，不得留下“已可交付”的假证据。
+- 通过后只进入等待 Git 批准，不能自动提交。
+
+## 恢复
+
+后台异常后读取任务合同、事件账本、运行状态、最近检查结果和两个 session ID。恢复原
+会话并从最后确认动作继续。监督会话丢失可在完整接管后显式重建；执行会话丢失默认暂停。

package/assets/skills/superflow-pipeline/references/quality-gate.md

@@ -65,6 +65,7 @@
 | 47   | **金额精度边界**                   | **涉及金额、费用、优惠、抵扣、退款、分账、支付、发票、余额、电费、服务费、套餐结算、比例分摊、明细分配、对账或财务展示时强制** | Superpowers 技术详设包含 `Money Precision Boundary` 及金额恒等式、权威总额、独立计算项、差额反推项与公式、计算态来源、中间精度、舍入边界、scale/rounding mode、分配/对账规则、禁止提前舍入点和测试证据；存在加法恒等式且总额是真源时，最后一个组成项必须由权威总额减去其余组成项合计得到，禁止所有组成项分别计算和舍入后重建总额；测试必须覆盖半分、尾差或多明细分配场景 |
 | 48   | **外部集成配置与部署合同**         | **涉及第三方平台/工具、SDK、MQ/Kafka、回调、支付渠道、云服务或其他外部集成时强制** | api.md、sdd-quality-gate.md、Superpowers 技术详设和实现 prompt 包含 `外部集成配置与部署合同` / `External Integration Configuration And Deployment Contract`；列出 endpoint、应用/租户/项目 ID、Topic/Tag/Consumer Group、namespace、webhook、ACL/role、开关、超时和凭据引用在本地/测试/生产的来源与创建方式，以及注入方式、运行 owner、创建 owner/时点、就绪证据、回滚、密钥处理和阻塞项；环境相关值不得只硬编码在注解/常量/业务代码；测试自动创建、历史资源或本地启动成功不能证明生产就绪，缺少生产创建证据必须阻塞发布 |
 | 49   | **并发与幂等归属**                 | **涉及并发、批量下发/开通/续费、重复提交/回调/消费或重复外部调用时强制** | sdd-quality-gate.md、Superpowers 技术详设和实现 prompt 包含 `Concurrency And Idempotency Ownership` / `并发与幂等归属`；明确业务幂等键、应用层原子占用 owner、短事务边界、PENDING/SUCCESS/FAILED 状态流转、重试复用原业务编码、外部调用边界和不确定结果对账；唯一索引不作为默认方案，只能在自然唯一、历史数据、NULL/软删除和冲突处理合同明确后作为可选兜底；测试覆盖并发、重复和重试 |
+| 50   | **复杂度减法评审**                 | **完整 workflow 的 docs/design 阶段强制** | `design.md` 与 Superpowers 技术详设包含 `复杂度减法评审`，逐项记录现有能力/复用证据、必要性、最简实现、删除/拒绝项和证据/阻塞；统计新增表、字段、API、Service/组件、缓存、异步/MQ/事件、定时任务和兼容层；能扩展现有模块、由字段推导或用单事务同步闭环时不得另建平行实现；`sdd-quality-gate.md` 必须给出 PASS/BLOCKED 结论，只有 PASS/通过才能离开 docs/design，存在无证据抽象或未决更简方案时阻塞 |
 
 ### 文档完整性强制检查（新增，全部项目必做）
 

package/assets/skills/superflow-pipeline/references/superpower-technical-design-template.md

@@ -35,6 +35,16 @@ canonical_sources:
 | -------------------- | --------------- | ---------------- | ------------------------- | ------------- | ------ |
 | <R1/S1>              | `<file>:<line>` | <observed fact>  | <implementation approach> | <files>       | <risk> |
 
+## 复杂度减法评审
+
+| 设计项 | 现有能力/复用证据 | 是否必要 | 最简实现 | 删除/拒绝项 | 证据/阻塞 |
+| ------ | ----------------- | -------- | -------- | ----------- | --------- |
+| `<表/API/Service/组件/同步机制>` | `<现有源码/API/表/依赖>` | `保留/删除/阻塞` | `<最小闭环实现>` | `<不新增的平行抽象/缓存/异步/兼容层>` | `<锚点或阻塞>` |
+
+新增项统计：表 0；字段 0；API 0；Service/组件 0；缓存 0；MQ/事件 0；定时任务 0；兼容层 0。按实际设计替换数量，不适用时保留 0。优先扩展
+现有模块；可安全推导的状态不重复持久化；单事务同步可闭环时不引入异步、补偿或
+缓存。每个保留项都要说明更简单方案为何不能满足合同，没有证据则删除。
+
 ## Architecture Boundary And Call Direction
 
 Use this whenever the change crosses repositories, services, SDKs, MQ,

package/assets/skills/superflow-pipeline/scripts/superflow-archive.sh

@@ -131,7 +131,7 @@ GUARD="$SCRIPT_DIR/superflow-guard.sh"
 VALIDATE="$SCRIPT_DIR/superflow-yaml-validate.sh"
 CHANGE_DIR="$(cd "$CHANGE_DIR" && pwd)"
 CHANGE_NAME="$(basename "$CHANGE_DIR")"
-PROJECT_ROOT="$(cd "$CHANGE_DIR/../.." && pwd)"
+PROJECT_ROOT="$(cd "$CHANGE_DIR/../../.." && pwd)"
 ARCHIVE_ROOT="$PROJECT_ROOT/openspec/changes/archive"
 ARCHIVE_NAME="$CHANGE_NAME"
 

package/assets/skills/superflow-pipeline/scripts/superflow-guard.sh

@@ -24,6 +24,7 @@ VALIDATE="$SCRIPT_DIR/superflow-yaml-validate.sh"
 CHANGE_DIR="${1:-}"
 PHASE="${2:-}"
 MODE="${3:-}"
+CHANGE_DIR_INPUT="${CHANGE_DIR%/}"
 
 [[ -n "$CHANGE_DIR" && -n "$PHASE" ]] || {
   usage
@@ -35,6 +36,25 @@ MODE="${3:-}"
 CHANGE_DIR="$(cd "$CHANGE_DIR" && pwd)"
 issues=()
 
+require_canonical_change_layout() {
+  local suffix
+
+  if [[ -L "$CHANGE_DIR_INPUT" ]]; then
+    issues+=("symlinked OpenSpec change directory is forbidden; keep one physical openspec/changes/<change-name> directory")
+  fi
+
+  [[ "$CHANGE_DIR" == */openspec/changes/* ]] || return 0
+  suffix="${CHANGE_DIR#*/openspec/changes/}"
+  case "$suffix" in
+    archive/*|*/embedded-changes/*) return 0 ;;
+  esac
+  if [[ "$suffix" == */* ]]; then
+    issues+=("non-canonical OpenSpec change directory: encode the version in <change-name> and use openspec/changes/<change-name>")
+  fi
+}
+
+require_canonical_change_layout
+
 require_file() {
   local path="$1"
   [[ -f "$CHANGE_DIR/$path" ]] || issues+=("missing file: $path")
@@ -313,15 +333,30 @@ change_has_external_enum_risk() {
     "$CHANGE_DIR"/specs/*/spec.md 2>/dev/null
 }
 
+change_contract_docs_without_complexity_budget() {
+  local path
+  for path in proposal.md api.md design.md tests.md spec.md; do
+    [[ -f "$CHANGE_DIR/$path" ]] || continue
+    sed -E '/新增项统计|复杂度预算|New-item counts|Complexity budget/d' \
+      "$CHANGE_DIR/$path"
+  done
+  if [[ -d "$CHANGE_DIR/specs" ]]; then
+    find "$CHANGE_DIR/specs" -path '*/spec.md' -type f \
+      -exec sed -E '/新增项统计|复杂度预算|New-item counts|Complexity budget/d' {} +
+  fi
+}
+
+change_all_docs_without_complexity_budget() {
+  find "$CHANGE_DIR" -maxdepth 2 -name '*.md' -type f \
+    -exec sed -E '/新增项统计|复杂度预算|New-item counts|Complexity budget/d' {} +
+}
+
 change_has_external_config_risk() {
-  grep -RIEiq \
+  local content
+  content="$(change_contract_docs_without_complexity_budget)"
+  grep -Eiq \
     '第三方|外部平台|外部工具|外部集成|third[- ]party|external (platform|tool|integration|system)|SDK|MQ|Kafka|RocketMQ|TDMQ|callback|回调|webhook|支付渠道|payment gateway|cloud service|云服务' \
-    "$CHANGE_DIR/proposal.md" \
-    "$CHANGE_DIR/api.md" \
-    "$CHANGE_DIR/design.md" \
-    "$CHANGE_DIR/tests.md" \
-    "$CHANGE_DIR/spec.md" \
-    "$CHANGE_DIR"/specs/*/spec.md 2>/dev/null
+    <<< "$content"
 }
 
 change_has_concurrency_idempotency_risk() {
@@ -358,9 +393,11 @@ change_has_fx_precision_risk() {
 }
 
 change_has_architecture_boundary_risk() {
-  grep -RIEiq \
+  local content
+  content="$(change_all_docs_without_complexity_budget)"
+  grep -Eiq \
     '跨仓|跨服务|sibling|SDK|MQ|topic|consumer|scheduler|定时|device|设备|callback|回调|third[- ]party|第三方|mini[- ]program|小程序|gateway|网关|adapter|适配|protocol|协议|interconnect|互联互通|调用链|入口|出口' \
-    "$CHANGE_DIR"/*.md "$CHANGE_DIR"/**/*.md 2>/dev/null
+    <<< "$content"
 }
 
 first_prompt_rel() {
@@ -482,6 +519,29 @@ require_money_precision_evidence() {
   fi
 }
 
+require_minimal_design_review() {
+  local path="$1"
+  local label="$2"
+  require_grep '复杂度减法评审|反过度设计评审|Minimal Design Review|Complexity Reduction Review' "$path" "$label"
+  require_grep '复用|reuse|existing capability|existing module' "$path" "$label reuse evidence"
+  require_grep '最简|最小实现|simplest|minimum design|minimal implementation' "$path" "$label simplest implementation"
+  require_grep '删除|拒绝|不新增|移出范围|removed|rejected|do not add|out of scope' "$path" "$label removed or rejected complexity"
+  require_grep '新增项统计|复杂度预算|New-item counts|Complexity budget' "$path" "$label complexity budget"
+  require_grep '表|table' "$path" "$label table count"
+  require_grep '字段|field' "$path" "$label field count"
+  require_grep 'API' "$path" "$label API count"
+  require_grep 'Service|服务|组件|service|component' "$path" "$label service/component count"
+  require_grep '缓存|cache' "$path" "$label cache count"
+  require_grep 'MQ|事件|异步|event|async' "$path" "$label async/event count"
+  require_grep '定时任务|scheduled job|scheduler' "$path" "$label scheduled-job count"
+  require_grep '兼容层|compatibility layer' "$path" "$label compatibility-layer count"
+}
+
+require_minimal_design_pass() {
+  local path="$1"
+  require_grep '(复杂度减法评审|反过度设计评审|Minimal Design Review|Complexity Reduction Review).*(PASS|通过)|(PASS|通过).*(复杂度减法评审|反过度设计评审|Minimal Design Review|Complexity Reduction Review)' "$path" "complexity reduction review PASS verdict"
+}
+
 transition_event=""
 
 if [[ -x "$VALIDATE" && -f "$CHANGE_DIR/.sdd/state.yaml" ]]; then
@@ -511,6 +571,12 @@ case "$PHASE" in
     require_grep 'RED|红绿|GREEN' tests.md "RED/GREEN test contract"
     require_grep 'curl|Postman|Newman|pytest|RestAssured|自动化命令' tests.md "interface automation command"
     require_grep 'handoff_hash|sdd-context|上下文包|防漂移' sdd-quality-gate.md "handoff/context-drift gate"
+    workflow="$(state_get workflow)"
+    if [[ "$workflow" == "full" ]]; then
+      require_minimal_design_review design.md "complexity reduction review"
+      require_grep '复杂度减法评审|反过度设计评审|Minimal Design Review|Complexity Reduction Review' sdd-quality-gate.md "complexity reduction quality gate"
+      require_minimal_design_pass sdd-quality-gate.md
+    fi
     if change_has_external_enum_risk; then
       require_external_enum_contract api.md "external enum binding contract"
       require_external_enum_contract sdd-quality-gate.md "external enum binding quality gate"
@@ -546,6 +612,9 @@ case "$PHASE" in
     require_hash_recorded
     workflow="$(state_get workflow)"
     if [[ "$workflow" == "full" ]]; then
+      require_minimal_design_review design.md "complexity reduction review"
+      require_grep '复杂度减法评审|反过度设计评审|Minimal Design Review|Complexity Reduction Review' sdd-quality-gate.md "complexity reduction quality gate"
+      require_minimal_design_pass sdd-quality-gate.md
       require_optional_state_path technical_design "technical_design"
       technical_design_rel="$(state_get technical_design)"
       if [[ -n "${technical_design_rel:-}" && "$technical_design_rel" != "null" ]]; then
@@ -569,6 +638,7 @@ case "$PHASE" in
         if change_has_money_precision_risk; then
           require_money_precision_contract "$technical_design_rel" "money precision boundary"
         fi
+        require_minimal_design_review "$technical_design_rel" "technical design minimal design review"
       fi
     fi
     require_grep 'Superpowers Technical Design Handoff|Superpower 技术详设|technical_design|源码级 HOW' design.md "Superpowers technical design handoff"

package/assets/skills-en/openspec-propose/SKILL.md

@@ -22,6 +22,20 @@ When ready to implement, run /opsx:apply
 
 **Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
 
+### Canonical OpenSpec Change Directory (Blocking)
+
+- A change must have exactly one physical directory:
+  `openspec/changes/<name>/`.
+- Encode the release version in `<name>`. For example, an account-permission
+  change for `v1.1.1` must use `v1-1-1-account-permission-optimization`.
+- Do not create nested version directories such as
+  `openspec/changes/v1.1.1/<feature>/`.
+- Do not create a flat symlink, copied directory, or second canonical document
+  tree to work around OpenSpec CLI discovery.
+- Creation, status, validation, and apply must use the same `<name>` in
+  `openspec new change`, `openspec status --change`, and
+  `openspec validate <name> --strict`.
+
 **Steps**
 
 1. **If no clear input provided, ask what they want to build**

package/assets/skills-en/superflow-design/SKILL.md

@@ -46,7 +46,17 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
 4. Write:
    `docs/superpowers/specs/YYYY-MM-DD-<change-id>-technical-design.md`
    using `../superflow-pipeline/references/superpower-technical-design-template.md`.
-5. For cross-repository, service-to-service, SDK, MQ, scheduler, device,
+5. Complete `Minimal Design Review` before expanding source-level HOW. For
+   every new table, field, API, service/component, abstraction, cache,
+   async/MQ/event flow, scheduled job, or compatibility layer, prove existing
+   reuse options, necessity, and why the simplest direct implementation is
+   insufficient. Prefer one owner, one write path, one transaction, and
+   set-based operations when they satisfy the contract. Remove speculative
+   extension points, duplicate DTO/API layers, derivable persistence,
+   premature caches, and async compensation without measured need. Record
+   retained and removed counts; unresolved simpler alternatives keep the
+   design blocked.
+6. For cross-repository, service-to-service, SDK, MQ, scheduler, device,
    callback, third-party, mini-program, gateway, or adapter changes, include
    `Architecture Boundary And Call Direction`. Prove owner module, call
    direction, existing entry/exit points, proposed entry/exit points, evidence
@@ -54,7 +64,7 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
    adapter/protocol translator/device gateway into a business-entry
    orchestrator, stop and return to `$superflow-docs` unless the OpenSpec/SDD
    contract explicitly grants that ownership with approval evidence.
-6. For third-party platforms/tools, SDKs, MQ/Kafka, callbacks, payment
+7. For third-party platforms/tools, SDKs, MQ/Kafka, callbacks, payment
    gateways, cloud services, or other external integrations, include
    `External Integration Configuration And Deployment Contract`. Inventory
    every endpoint, app/tenant/project ID, Topic, Tag, Consumer Group,
@@ -66,7 +76,7 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
    auto-creation or pre-existing resources must not be treated as proof that
    production will provision them. Missing production provisioning evidence
    blocks design completion.
-7. For concurrent requests, batch issue/activation/renewal, duplicate callbacks,
+8. For concurrent requests, batch issue/activation/renewal, duplicate callbacks,
    duplicate consumption, or repeated external delivery, include
    `Concurrency And Idempotency Ownership`. Use a stable business idempotency
    key and an application-layer atomic claim in a short transaction; persist
@@ -76,10 +86,10 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
    optional fallback with proven natural uniqueness, historical cleanup,
    NULL/soft-delete semantics, and a conflict contract. Check-then-insert,
    process-local locks, and random IDs alone are blocked.
-8. For field/status/enum/sync changes, include `Field And Status Reverse
+9. For field/status/enum/sync changes, include `Field And Status Reverse
    Impact` and prove writers, readers, filters, derived sync paths, consumers,
    and tests. Direct setter-only design is blocked.
-9. For amount, fee, discount, deduction, refund, sharing, payment, invoice,
+10. For amount, fee, discount, deduction, refund, sharing, payment, invoice,
    balance, electricity fee, service fee, package settlement, proration,
    allocation, reconciliation, or financial display changes,
    include `Money Precision Boundary`. Prove calculation-state fields,
@@ -98,12 +108,12 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
    level and policy source, deterministic residual strategy with stable
    tie-breaker, and positive/zero/negative evidence. For FX changes, freeze the
    directional rate metadata and one canonical conversion path.
-10. Record state:
+11. Record state:
    ```bash
    ../superflow-pipeline/scripts/superflow-state.sh set <change-dir> technical_design docs/superpowers/specs/YYYY-MM-DD-<change-id>-technical-design.md
    ../superflow-pipeline/scripts/superflow-state.sh set <change-dir> design_doc design.md
    ```
-11. Update `design.md` with `Superpowers Technical Design Handoff`, update
+12. Update `design.md` with `Superpowers Technical Design Handoff`, update
    `sdd-quality-gate.md` with the technical design path and hash, then run
    `../superflow-pipeline/scripts/superflow-handoff.sh <change-dir> --refresh`.
    If the guard reports a stale or missing hash, record the printed hash in
@@ -111,7 +121,7 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
    `--refresh` again. Do not set `design_doc` to the Superpowers document;
    `design_doc` is the OpenSpec/SDD contract design, while `technical_design`
    is the Superpowers HOW document.
-12. Run:
+13. Run:
    ```bash
    ../superflow-pipeline/scripts/superflow-yaml-validate.sh <change-dir>
    ../superflow-pipeline/scripts/superflow-guard.sh <change-dir> design --apply

package/assets/skills-en/superflow-docs/SKILL.md

@@ -103,6 +103,17 @@ For complex requirements, verify these before writing docs:
   chain, no-fallback/no-guessing boundary, and pre-coding agent self-check. If
   any gate is missing from `design.md`, `tests.md`, or quality gate, stop and
   complete the docs first.
+- For full workflow changes, `design.md` must include a `Minimal Design Review`
+  before docs freeze. Inventory every proposed table, field, API,
+  service/component, cache, async/MQ/event flow, scheduled job, compatibility
+  layer, and abstraction. Record existing reuse evidence, necessity, the
+  simplest implementation, removed/rejected complexity, and blockers.
+  Prefer extending current modules and synchronous transactions. Do not keep a
+  layer only for hypothetical future flexibility; remove it without evidence.
+- `sdd-quality-gate.md` must record the minimal-design verdict as `PASS` or
+  `BLOCKED`; only `PASS` may leave docs/design. Missing reuse evidence, parallel APIs/models, redundant persisted
+  fields, speculative cache/async/compensation, or an unresolved simpler option
+  blocks docs completion.
 - `design.md` stays the OpenSpec/SDD design contract: requirement mapping,
   API/DB/field semantics, source facts, real-entry call chain, no-fallback
   boundary, risks, and acceptance hooks. It must not try to own all source-level
@@ -251,6 +262,11 @@ Use references only as needed:
   the relationship judgment as `confirmed/partially confirmed/unknown` when a bug fix hinges on
   existing data or call-chain behavior.
 - `design.md` must reference the frozen `api.md` fields and errors.
+- `design.md` must include `Minimal Design Review` with:
+  `Design item | Existing capability/reuse evidence | Necessary? | Simplest implementation | Removed/rejected complexity | Evidence/blocker`.
+  Count new tables, fields, APIs, services/components, caches, async flows,
+  jobs, and compatibility layers. A zero count is valid and preferred when
+  existing capabilities close the contract.
 - `design.md` must include a "Field Semantic Contract" table for every risky field:
   `Field | Source table/DTO/event | Real semantics | Target field | Target semantics | Equivalent? |
   Evidence anchor | Forbidden usage | Unknowns/owner`.

package/assets/skills-en/superflow-pipeline/SKILL.md

@@ -19,6 +19,38 @@ other:
 - Handoff files and state files are the memory boundary. Do not rely on chat
   memory after compaction.
 
+## Managed Work And Dual-Agent Closure
+
+When the user says to use Superflow for managed delivery and provides an
+implementation prompt, change directory, or direct task, use built-in managed
+mode. Do not require the user to name `superflow-pipeline`, roles, or CLI flags:
+
+```bash
+superflow pipeline "<implementation prompt, change directory, or direct task>" --managed --project "<project root>" \
+  --supervisor codex --executor claude --language en
+```
+
+Swap the roles when Claude is the current entry agent. The command always uses
+the independent background service while following the local task journal to a
+terminal state, then the current agent reads the report and summarizes in the
+same conversation. Losing the follower does not stop the task. Read
+`references/managed-work.md` before dispatch. Do not spawn the peer CLI by hand.
+
+Hard gates:
+
+- Persist one supervisor session and one executor session per task; resume exact IDs.
+- Task contract, event journal, review results, and evidence are authoritative.
+- Maximum 5 reviews, 7 executor calls, and 12 total agent calls.
+- Revalidate the frozen contract and hard limits on every start or resume. Engineering work cannot enter review with only one verification category.
+- Resolve a change directory through `.sdd/state.yaml` `implementation_prompt`, reject `tasks.md` as an execution entry, and freeze one prompt snapshot plus SHA-256 for both agents.
+- Supervisor is read-only; executor cannot edit `.superflow/tasks` or commit/push/publish.
+- A passing run stops at `awaiting_git_approval`; Git requires the user's approval.
+- Use `superflow status <project-root>` instead of model polling.
+- `superflow-managed-work-check.mjs` must pass before delivery-ready status.
+- Record the single delivery-ready event only after the integrity script passes.
+- After the managed command returns a terminal state, read the task report and summarize it to the user instead of returning only a task ID.
+- Freeze the selected language into the task contract. Executor and reviewer prompts, resumed rounds, journals, reports, notifications, and errors must inherit that language without switching mid-run.
+
 ## Phase Order
 
 Always route work through this order unless the task is explicitly a tweak or
@@ -79,6 +111,22 @@ When the router selects embedded deep clarification, follow these rules inside
 
 ## Required Artifacts
 
+### Canonical OpenSpec Change Directory (Blocking)
+
+- Superflow must use the OpenSpec CLI single-level layout:
+  `openspec/changes/<change-name>/`.
+- The release version belongs in the change name, not an intermediate
+  directory. Encode `v1.1.1` as `v1-1-1-<feature-slug>` and never create
+  `changes/v1.1.1/<feature-slug>/`.
+- Keep exactly one physical directory for each change. Do not create a
+  compatibility symlink, copied directory, or second canonical document tree.
+- Run `openspec new change <change-name>` first, then reuse that same physical
+  directory for status, instructions, strict validation, state, handoff, and
+  every Superflow guard.
+- If a nested version directory or symlinked change is found, stop document
+  generation, migrate it to one flat physical directory, and rerun
+  `openspec validate <change-name> --strict`.
+
 For a full change, the docs phase must create or refresh:
 
 - proposal.md

package/assets/skills-en/superflow-pipeline/references/document-templates.md

@@ -22,6 +22,11 @@
 - Source-of-truth contracts
 - Architecture boundary
 - Data model
+- Minimal Design Review: reuse evidence, necessity, simplest implementation,
+  removed/rejected complexity, and blockers
+- Count every new table, field, API, service, cache, async flow, scheduled job,
+  and compatibility layer; remove items without evidence
+- New-item counts: tables 0; fields 0; APIs 0; services/components 0; caches 0; MQ/events 0; scheduled jobs 0; compatibility layers 0. Replace each count.
 - Field semantics
 - Write/read loop
 - No-fallback decisions

package/assets/skills-en/superflow-pipeline/references/managed-work.md

@@ -0,0 +1,34 @@
+# Managed Work Rules
+
+Managed work is built into `superflow-pipeline`. The user only says to use
+Superflow and provides an implementation prompt, change directory, or direct
+task. Direct tasks receive a minimal contract. SDD work freezes the generated
+implementation prompt and never substitutes `tasks.md` for the execution prompt.
+
+Always dispatch through:
+
+```bash
+superflow pipeline "<implementation-prompt|change-dir|task>" --managed --project "<root>" \
+  --supervisor <codex|claude> --executor <claude|codex> --language <en|zh>
+```
+
+The command always starts the independent background service and follows the
+local event journal to a terminal state. Losing the follower does not stop the
+task. After return, the current agent reads the report and summarizes it in the
+original conversation.
+
+Hard gates:
+
+- Claim the 5/7/12 budgets before an Agent call.
+- Freeze the selected language into the contract; prompts, journals, reports, notifications, errors, and resumed rounds must use that same language.
+- Revalidate the frozen contract hash, non-overridable permissions, and 5/7/12 hard limits on every start and resume. Fail closed if persisted contract data changed.
+- Resolve change directories through `.sdd/state.yaml` `implementation_prompt`; treat `tasks.md` as a checklist only. Copy the prompt into a managed snapshot and freeze its SHA-256 for both agents.
+- Persist and resume exact supervisor and executor session IDs.
+- Treat `progress.jsonl`, the task contract, review results, and evidence as truth.
+- Executor cannot edit managed state or commit, push, publish, deploy, or bypass sandbox.
+- Supervisor cannot modify target files.
+- Non-zero exits, invalid JSON, missing session IDs, and review-time workspace drift block pass.
+- Engineering and SDD tasks need successful command evidence from at least two categories among build, test, and runtime/real invocation. Compile-only or unit-test-only delivery cannot enter formal review.
+- Run `superflow-managed-work-check.mjs <root> <task-id>` before delivery-ready.
+- Append the single `run.delivery_ready` event only after the integrity script passes. On failure, require human attention without leaving false delivery-ready evidence.
+- A passing run waits for explicit Git approval.

package/assets/skills-en/superflow-pipeline/references/quality-gate.md

@@ -9,10 +9,18 @@
 - Handoff files exist and hash is current.
 - design.md records OpenSpec/SDD as WHAT and Superpowers as HOW.
 - sdd-quality-gate.md records guard command and result.
+- design.md and sdd-quality-gate.md include a Minimal Design Review with reuse
+  evidence, necessity, simplest implementation, removed/rejected complexity,
+  counts of new tables/fields/APIs/services/caches/async flows/jobs/compatibility
+  layers, and a PASS/BLOCKED verdict. Only PASS may leave docs/design.
 
 ## Design Gate
 
 - Technical design exists for full workflow.
+- Technical design repeats the Minimal Design Review at source level. It extends
+  existing modules first and rejects speculative abstractions, parallel APIs or
+  models, derivable persistence, premature caches, and async compensation when
+  a direct synchronous design satisfies the contract.
 - Field/status reverse impact matrix exists when risky fields or states change.
 - Architecture boundary and call-direction matrix exists for cross-service or
   external flows.

package/assets/skills-en/superflow-pipeline/references/superpower-technical-design-template.md

@@ -35,6 +35,17 @@ canonical_sources:
 |---|---|---|---|---|---|
 | <R1/S1> | `<file>:<line>` | <observed fact> | <implementation approach> | <files> | <risk> |
 
+## Minimal Design Review
+
+| Design item | Existing capability/reuse evidence | Necessary? | Simplest implementation | Removed/rejected complexity | Evidence/blocker |
+| ----------- | ---------------------------------- | ---------- | ----------------------- | --------------------------- | ---------------- |
+| `<table/API/service/component/sync>` | `<existing source/API/table/dependency>` | `keep/remove/blocked` | `<minimum implementation>` | `<no parallel abstraction/cache/async/compat layer>` | `<anchor or blocker>` |
+
+New-item counts: tables 0; fields 0; APIs 0; services/components 0; caches 0; MQ/events 0; scheduled jobs 0; compatibility layers 0. Replace each count with the actual design total. Extend existing modules first. Do not persist values
+that can be derived safely, and do not add async compensation or caching when a
+single synchronous transaction closes the contract. Every retained item must
+explain why a simpler option fails; remove it when there is no evidence.
+
 ## Architecture Boundary And Call Direction
 
 Use this whenever the change crosses repositories, services, SDKs, MQ,

package/assets/skills-en/superflow-pipeline/scripts/superflow-archive.sh

@@ -131,7 +131,7 @@ GUARD="$SCRIPT_DIR/superflow-guard.sh"
 VALIDATE="$SCRIPT_DIR/superflow-yaml-validate.sh"
 CHANGE_DIR="$(cd "$CHANGE_DIR" && pwd)"
 CHANGE_NAME="$(basename "$CHANGE_DIR")"
-PROJECT_ROOT="$(cd "$CHANGE_DIR/../.." && pwd)"
+PROJECT_ROOT="$(cd "$CHANGE_DIR/../../.." && pwd)"
 ARCHIVE_ROOT="$PROJECT_ROOT/openspec/changes/archive"
 ARCHIVE_NAME="$CHANGE_NAME"