@devcxl/opencode-cabbage 1.1.0 → 1.3.0

package/.codex-plugin/plugin.json

@@ -0,0 +1,36 @@
+{
+  "name": "opencode-cabbage",
+  "version": "1.3.0",
+  "description": "全流程开发编排插件 — 需求→设计→任务→编码→测试→审查→自动合并，支持 OpenCode 与 Codex 双平台",
+  "author": {
+    "name": "devcxl",
+    "url": "https://github.com/devcxl"
+  },
+  "homepage": "https://devcxl.github.io/opencode-cabbage/",
+  "repository": "https://github.com/devcxl/opencode-cabbage",
+  "license": "MIT",
+  "keywords": [
+    "development-workflow",
+    "orchestration",
+    "tdd",
+    "codex",
+    "codex-plugin",
+    "opencode",
+    "opencode-plugin"
+  ],
+  "skills": "./codex-skills/",
+  "interface": {
+    "displayName": "OpenCode Cabbage",
+    "shortDescription": "全流程开发编排 — 需求到自动合并，双平台兼容",
+    "longDescription": "覆盖需求、设计、DAG 任务拆解、并行编码（TDD）、审查与自动合并的全流程开发编排插件。兼容 OpenCode 与 Codex 双平台，提供 9 个 flow skills 和 6 个 agent skills。",
+    "developerName": "devcxl",
+    "category": "Developer Tools",
+    "capabilities": ["Read", "Write"],
+    "defaultPrompt": [
+      "使用 OpenCode Cabbage 初始化项目开发环境 — 加载 flow-setup skill",
+      "使用 OpenCode Cabbage 的 flow-setup skill 初始化项目开发环境",
+      "使用 OpenCode Cabbage 的 agent-dev-lifecycle skill 编排全流程"
+    ],
+    "brandColor": "#00bcd4"
+  }
+}

package/README.md

@@ -2,8 +2,11 @@
   <h1>@devcxl/opencode-cabbage</h1>
   <p>A full-lifecycle development plugin for OpenCode, covering requirements, design, tasks, coding, testing, review, and release with automated orchestration and parallel subagents.</p>
   <p>
-    <a href="https://www.npmjs.com/package/@devcxl/opencode-cabbage"><img src="https://img.shields.io/npm/v/@devcxl/opencode-cabbage" alt="npm version"></a>
     <a href="https://github.com/devcxl/opencode-cabbage/actions/workflows/ci.yml"><img src="https://github.com/devcxl/opencode-cabbage/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
+    <a href="https://github.com/devcxl/opencode-cabbage/actions/workflows/release-draft.yml"><img src="https://github.com/devcxl/opencode-cabbage/actions/workflows/release-draft.yml/badge.svg" alt="Release"></a>
+    <a href="https://github.com/devcxl/opencode-cabbage/actions/workflows/release-publish.yml"><img src="https://github.com/devcxl/opencode-cabbage/actions/workflows/release-publish.yml/badge.svg" alt="Publish to npm"></a>
+    <a href="https://www.npmjs.com/package/@devcxl/opencode-cabbage"><img src="https://img.shields.io/npm/v/@devcxl/opencode-cabbage" alt="npm version"></a>
+    <a href="https://www.npmjs.com/package/@devcxl/opencode-cabbage"><img src="https://img.shields.io/npm/dm/@devcxl/opencode-cabbage" alt="npm downloads"></a>
     <a href="https://devcxl.github.io/opencode-cabbage"><img src="https://github.com/devcxl/opencode-cabbage/actions/workflows/pages.yml/badge.svg?branch=main" alt="GitHub Pages"></a>
   </p>
   <p>English | <a href="README.zh.md">简体中文</a></p>
@@ -11,6 +14,10 @@
 
 ---
 
+## OpenCode Compatibility
+
+> **OpenCode v2 is not currently supported.** This plugin still uses the OpenCode v1 plugin API (`@opencode-ai/plugin` 1.x). OpenCode v2 introduces breaking changes to its plugin API and SDK, and this plugin has not yet been migrated or end-to-end tested on v2. If you rely on cabbage, stay on OpenCode v1 for now; do not upgrade to OpenCode v2 until support is announced.
+
 ## Installation
 
 ```json
@@ -20,7 +27,33 @@
 }
 ```
 
-Once started, the plugin automatically injects 7 slash commands, 8 flow skills, 5 agents, and 5 deterministic lifecycle tools.
+Once started, the plugin automatically injects 7 slash commands, 9 flow skills, 6 agents, and 1 goal tool.
+
+> **⚠️ Plugin conflict — do not combine with other goal plugins.** cabbage ships its own `goal` tool with an idle-driven auto-continuation loop. Installing it together with another goal / auto-continue plugin (e.g. `@prevalentware/opencode-goal-plugin`, `opencode-goal-mode`) risks both loops listening for session idle events and injecting continuation prompts: work gets continued twice, continuation counts and token budgets drift out of sync, and abort handling interferes across plugins. Use exactly one goal engine per session — if you rely on an external goal plugin, do not trigger cabbage's goal tool (it is restricted to the `dev-lifecycle` / `goal-verify` agents).
+
+## Codex Installation (Compatibility Layer)
+
+This package also ships a Codex plugin compatibility layer (`codex-skills/` + `hooks/` + `.codex-plugin/`) so the flow skills and agent prompts work in Codex as well.
+
+The repository is a Codex marketplace: add it as a marketplace source, then install the plugin from it.
+
+```bash
+# 1. Add this repository as a Codex marketplace
+codex plugin marketplace add devcxl/opencode-cabbage
+
+# 2. Confirm the plugin is available
+codex plugin list --available
+
+# 3. Install the plugin (pulled from the npm package, which bundles all Codex files)
+codex plugin add opencode-cabbage@cabbage
+```
+
+Notes:
+
+- **Build artifact included**: the SessionStart hook (`dist/hooks/session-start.js`) ships inside the published npm package — no local build required.
+- **Hook trust review**: Codex requires interactive trust approval for hooks (`/hooks` command) on first run — approve the `SessionStart` hook to enable context injection.
+- **Marketplace name**: the marketplace is named `cabbage` (see `.agents/plugins/marketplace.json`); use `opencode-cabbage@cabbage` as the plugin selector.
+- **Platform differences**: the Codex layer is a pure-Prompt downgrade — no `goal` tool, no slash commands, no automatic continuation. Agents are plain skills (referenced as `@agent-*`), and flow state is tracked via GitHub Issue checklists. See `codex-skills/agent-dev-lifecycle/SKILL.md` for details.
 
 ## Command Overview
 
@@ -30,8 +63,8 @@ Once started, the plugin automatically injects 7 slash commands, 8 flow skills,
 | `/requirements` | Requirements | PRD → `docs/prd/` + Draft Parent Issue |
 | `/design` | Design | Technical specification + necessary ADR → `docs/dev/specs/` + `docs/adr/` |
 | `/tasks` | Task decomposition | DAG tasks + Sub Issues (GitHub 权威源) |
-| `/code` | Coding | Task + Runtime TDD evidence + PR |
-| `/review` | Review | Dual-axis review + automatic merge |
+| `/code` | Coding | Task + PR (TDD enforced by CI) |
+| `/review` | Review | Dual-axis review + merge |
 | `/release` | ⚠️ Manual release | Version proposal → Release PR → tag push → workflow monitor |
 
 ## Quick Start
@@ -58,37 +91,32 @@ npm install @devcxl/opencode-cabbage
 src/                          # Thin TypeScript layer
 ├── index.ts                  # Plugin entry point
 ├── plugin.ts                 # Package root resolution
-├── plugin/                   # Loaders + tool factories
-│   ├── server.ts             # Main factory: injects skills, commands, agents, 5 lifecycle tools
+├── plugin/                   # Loaders + goal tool
+│   ├── server.ts             # Main factory: injects skills/commands/agents, goal tool, context, auto-continuation
+│   ├── goal.ts               # goal tool (status + goal-verify authorization)
 │   ├── commands.ts           # Command loader
 │   ├── skills.ts             # Skill loader
 │   ├── prompts.ts            # Prompt loader
 │   ├── bootstrap.ts          # Startup guidance
 │   ├── agents.ts             # Agent injection
-│   ├── setup-control.ts      # setup_control tool
-│   ├── flow-control.ts       # flow_control tool
-│   ├── task-control.ts       # task_control tool
-│   ├── tdd-checkpoint.ts     # tdd_checkpoint tool
-│   └── release-control.ts    # release_control tool
-└── kernel/                   # Deterministic thin kernel
-    ├── slug.ts               # Functional slug derivation/validation
-    ├── records.ts            # Flow/Task Record CRUD (GitHub authoritative)
-    ├── worktree.ts           # Worktree lifecycle (no --force)
-    ├── tdd/                  # Runtime TDD pure functions + evidence
-    ├── review.ts             # Merge gates (CI/protection/risk/approval)
-    ├── release.ts            # Version proposal + tag immutability
-    ├── context.ts            # Root CONTEXT.md discovery/injection
+│   ├── shell.ts              # Agent shell env isolation
+│   └── prompt-lint.ts        # Prompt asset consistency checks
+└── kernel/                   # Minimal supporting modules
+    ├── context.ts            # root CONTEXT.md discovery/injection
     ├── profile.ts            # AGENTS.md Project Profile parsing
-    ├── session-index.ts      # Flow→session index + takeover
-    ├── caller.ts             # Caller role matrix
+    ├── session-index.ts      # Flow→session index (goal binding + auto-resume)
     ├── permission.ts         # Permission matching semantics
-    └── legacy.ts             # Legacy FlowRun detection
+    └── mutex.ts              # Keyed async mutex
 
-assets/                       # Runtime assets
+assets/                       # Runtime assets (pure Prompt flows)
 ├── commands/                 # 7 slash commands
-├── skills/                   # 8 flow-* skills
-├── agents/                   # 5 agent definitions
+├── skills/                   # 9 flow-* skills (Prompt-driven, direct git/gh)
+├── agents/                   # 6 agent definitions
 └── prompts/                  # Guidance prompts and templates
+
+codex-skills/                 # Codex compatibility layer (mirrors assets/, agent-* prefixed)
+hooks/                        # Codex SessionStart hook (hooks.json + compiled dist/hooks/)
+.codex-plugin/                # Codex plugin manifest (plugin.json)
 ```
 
 ## Documentation

package/README.zh.md

@@ -2,8 +2,11 @@
   <h1>@devcxl/opencode-cabbage</h1>
   <p>全流程开发 OpenCode 插件 — 覆盖需求、设计、任务、编码、测试、审查和发布完整开发生命周期，支持自动编排与并行 Subagent。</p>
   <p>
-    <a href="https://www.npmjs.com/package/@devcxl/opencode-cabbage"><img src="https://img.shields.io/npm/v/@devcxl/opencode-cabbage" alt="npm version"></a>
     <a href="https://github.com/devcxl/opencode-cabbage/actions/workflows/ci.yml"><img src="https://github.com/devcxl/opencode-cabbage/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
+    <a href="https://github.com/devcxl/opencode-cabbage/actions/workflows/release-draft.yml"><img src="https://github.com/devcxl/opencode-cabbage/actions/workflows/release-draft.yml/badge.svg" alt="Release"></a>
+    <a href="https://github.com/devcxl/opencode-cabbage/actions/workflows/release-publish.yml"><img src="https://github.com/devcxl/opencode-cabbage/actions/workflows/release-publish.yml/badge.svg" alt="Publish to npm"></a>
+    <a href="https://www.npmjs.com/package/@devcxl/opencode-cabbage"><img src="https://img.shields.io/npm/v/@devcxl/opencode-cabbage" alt="npm version"></a>
+    <a href="https://www.npmjs.com/package/@devcxl/opencode-cabbage"><img src="https://img.shields.io/npm/dm/@devcxl/opencode-cabbage" alt="npm downloads"></a>
     <a href="https://devcxl.github.io/opencode-cabbage"><img src="https://github.com/devcxl/opencode-cabbage/actions/workflows/pages.yml/badge.svg?branch=main" alt="GitHub Pages"></a>
   </p>
   <p><a href="README.md">English</a> | 简体中文</p>
@@ -11,6 +14,10 @@
 
 ---
 
+## OpenCode 兼容性
+
+> **目前暂不支持 OpenCode v2。** 本插件当前仍使用 OpenCode v1 插件 API（`@opencode-ai/plugin` 1.x）。OpenCode v2 的插件 API 和 SDK 存在不兼容变更，本插件尚未完成迁移，也未通过 v2 端到端验证。依赖本插件时请暂时继续使用 OpenCode v1；在正式公布支持前，请勿升级到 OpenCode v2。
+
 ## 安装
 
 ```json
@@ -20,7 +27,9 @@
 }
 ```
 
-插件启动后自动注入 7 个 slash command、8 个 flow skill、5 个 agent 与 5 个确定性生命周期工具。
+插件启动后自动注入 7 个 slash command、9 个 flow skill、6 个 agent 与 1 个 goal 工具。
+
+> **⚠️ 插件冲突——不要与其他 goal 插件同时安装。** cabbage 自带 `goal` 工具与 idle 驱动的自动续接循环。若与其他 goal / 自动续接类插件（如 `@prevalentware/opencode-goal-plugin`、`opencode-goal-mode`）同时安装，存在双方都监听会话 idle 事件并注入续接 prompt 的风险：任务被重复续接、续接计数与 token 预算互不同步、abort 处理互相干扰。同一会话只能保留一个 goal 引擎——若使用外部 goal 插件，请勿触发 cabbage 的 goal 工具（仅 `dev-lifecycle` / `goal-verify` agent 可调用）。
 
 ## 命令一览
 
@@ -30,7 +39,7 @@
 | `/requirements` | 需求 | PRD → `docs/prd/` + Draft Parent Issue |
 | `/design` | 设计 | 技术方案 + 必要 ADR → `docs/dev/specs/` + `docs/adr/` |
 | `/tasks` | 任务拆解 | DAG 任务 + Sub Issues（GitHub 权威源） |
-| `/code` | 编码 | Task + Runtime TDD evidence + PR |
+| `/code` | 编码 | Task + PR（TDD 由 CI 把关） |
 | `/review` | 审查 | 双轴审查 + 自动合并 |
 | `/release` | ⚠️ 手动发布 | 版本提议 → Release PR → tag push → workflow 监控 |
 
@@ -58,36 +67,27 @@ npm install @devcxl/opencode-cabbage
 src/                          # TypeScript 薄层
 ├── index.ts                  # 插件入口
 ├── plugin.ts                 # 包路径解析
-├── plugin/                   # 加载器 + 工具工厂
-│   ├── server.ts             # 主工厂：注入 skills/commands/agents/5 个生命周期工具
+├── plugin/                   # 加载器 + goal 工具
+│   ├── server.ts             # 主工厂：注入 skills/commands/agents、goal 工具、Context、自动续接
+│   ├── goal.ts               # goal 工具（状态管理 + goal-verify 授权）
 │   ├── commands.ts           # Command 加载器
 │   ├── skills.ts             # Skill 加载器
 │   ├── prompts.ts            # Prompt 加载器
 │   ├── bootstrap.ts          # 启动引导
 │   ├── agents.ts             # Agent 注入
-│   ├── setup-control.ts      # setup_control 工具
-│   ├── flow-control.ts       # flow_control 工具
-│   ├── task-control.ts       # task_control 工具
-│   ├── tdd-checkpoint.ts     # tdd_checkpoint 工具
-│   └── release-control.ts    # release_control 工具
-└── kernel/                   # 确定性薄内核
-    ├── slug.ts               # Functional Slug 派生/校验
-    ├── records.ts            # Flow/Task Record CRUD（GitHub 权威源）
-    ├── worktree.ts           # Worktree 生命周期（无 --force）
-    ├── tdd/                  # Runtime TDD 纯函数 + evidence
-    ├── review.ts             # 合并门禁（CI/分支保护/风险/approval）
-    ├── release.ts            # 版本提议 + tag 不可变校验
+│   ├── shell.ts              # Agent shell 环境隔离
+│   └── prompt-lint.ts        # Prompt 资产一致性检查
+└── kernel/                   # 最小支撑模块
     ├── context.ts            # 根 CONTEXT.md 发现/注入
     ├── profile.ts            # AGENTS.md Project Profile 解析
-    ├── session-index.ts      # Flow→session 索引 + takeover
-    ├── caller.ts             # 调用者角色矩阵
+    ├── session-index.ts      # Flow→session 索引（goal 绑定 + 重启恢复）
     ├── permission.ts         # 权限匹配语义
-    └── legacy.ts             # 旧 FlowRun 检测
+    └── mutex.ts              # 按键异步互斥
 
-assets/                       # 运行时资源
+assets/                       # 运行时资源（纯 Prompt 流程）
 ├── commands/                 # 7 个 slash command
-├── skills/                   # 8 个 flow-* skill
-├── agents/                   # 5 个 agent 定义
+├── skills/                   # 9 个 flow-* skill（Prompt 驱动，直接 git/gh）
+├── agents/                   # 6 个 agent 定义
 └── prompts/                  # 引导提示词 + 模板
 ```
 

package/assets/agents/dev-lifecycle.md

@@ -1,55 +1,62 @@
 ---
 name: dev-lifecycle
-description: 全流程开发编排器 — 需求确认后自动完成设计→任务拆解→并行实现→审查→自动合并
+description: 全流程开发编排器 — 按输入场景分诊并编排（功能/Bug/紧急修复/业务调整/重构/技术债/基础设施/文档/回滚）
 mode: primary
 color: '#00bcd4'
 permission:
   bash:
     "*": "allow"
-    "git push*": "deny"
-    "git worktree remove*": "deny"
-    "git worktree add*": "deny"
-    "git checkout -b*": "deny"
-    "git tag*": "deny"
-    "gh pr create*": "deny"
-    "gh pr merge*": "deny"
-    "gh issue close*": "deny"
-    "gh issue create*": "deny"
-    "gh release create*": "deny"
-    "npm publish*": "deny"
 ---
 
 <system-reminder>
 你是全流程开发编排器（dev-lifecycle）。
 
-你的目标：在用户确认需求方向后，自动串联设计 → 任务拆解 → Sub Issues 创建 → 并行编码实现 → 审查 → 自动合并的全流程。
+你的目标：先对用户输入做场景分诊，选择对应流程路径；功能流自动串联设计 → 任务拆解 → Sub Issues 创建 → 并行编码实现 → 审查 → 合并，其余场景按对应轻量路径执行。
 
 使用 `goal` 工具管理 flow 状态。Plugin 会在你每次 idle 时自动注入 continuation prompt，你只需做好当前 step 即可。
 
 无需用户逐步骤确认，仅在遇到非预期错误时暂停并告知。
 
-**TDD 约束**：编码阶段引用 `flow-tdd` skill 作为 TDD 协议唯一来源。
+**TDD 约束**：编码阶段引用 `flow-tdd` skill 作为 TDD 协议唯一来源（advisory，测试质量由 CI 把关）。
 </system-reminder>
 
 ## 开始工作
 
-1. 调用 `goal({op:"create", parent_issue_number:<Flow Record 编号>})` 建立会话运行控制（目标/验收从 Flow Record 读取）
-2. 调用 `flow_control{op:"status"}` 读取当前 Flow 进度，按下方 Phase 顺序继续
-3. 每个阶段完成后，Plugin 会自动 continuation，进入下一阶段
-4. 最终全部完成后，直接使用 Task 工具派发 `@goal-verify` 做独立验证
+1. 场景分诊：按 Phase 0 判定用户输入所属场景，选择流程路径
+2. 调用 `goal({op:"create", parent_issue_number:<Flow Record 编号>})` 建立会话运行控制（目标/验收从 Flow Record 读取）
+3. 读取 Flow Record（Parent Issue body）获取目标与验收标准，按选定路径推进
+4. 每个阶段完成后，Plugin 会自动 continuation，进入下一阶段
+5. 最终全部完成后，直接使用 Task 工具派发 `@goal-verify` 做独立验证
 
 ## 调度团队
 
 - @architect：技术方案、ADR、DAG 任务拆解
-- @developer：技术栈无关代码 TDD 实现（加载 `flow-tdd` skill，遵循 RED→GREEN cycle，编码 + 测试 + 本地 commit，不 push、不创建 PR）
+- @developer：技术栈无关代码 TDD 实现（加载 `flow-tdd` skill，遵循 RED→GREEN cycle，编码 + 测试 + 本地 commit）
 - @reviewer：只读代码审查，输出结构化审查报告（不操作 git/GitHub，不写文件）
 - @goal-verify：独立验证 Goal 完成状态（**只有它可以调用 goal({op:"complete"})**）
 
 ## 全局约束
 
-### 阶段契约（单一来源）
-- 阶段推进遵循 `stage-contract`（assets/prompts/stage-contract.md）：阶段完成 = Flow Record body checklist `- [x] <stage>`，门禁与顺序以该契约为准
-- 阶段推进调用 `flow_control{op:"stage-start"|"stage-complete"}`（requirements 完成需用户确认；高风险 Flow 的 design→tasks 需确认）
+### 阶段契约
+- 阶段顺序：requirements → design → tasks → code → review → release
+- 每个阶段完成后，在 Flow Record body 的 checklist 勾选对应阶段（`- [x] <stage>`）
+- requirements 完成需用户确认；高风险 Flow 的 design→tasks 需用户确认
+- 上述阶段顺序与 checklist 适用于功能流；非功能路径按 Phase 0 轻量路径执行，完成标准见各路径要点
+
+### Testing Decisions 存量兼容门
+
+功能流进入或恢复 tasks、code、review 时，先检查相关行为是否在技术方案中具有完整的 `Testing Decisions`。
+
+如果完整，直接继续当前步骤。如果缺失：
+
+1. 记录当前 stage，不调用 goal 改回 design，也不修改已完成阶段的 checklist。
+2. 在创建 Sub Issue、派发 developer 或输出 review 结论前停止当前动作，汇总一个 Design Gap：Design 文件、缺失行为、已有 Interface / 测试惯例、需要补充的决策。
+3. 在**当前 stage 内**委派 `@architect` 加载 `flow-design` 执行 Design Amendment：只向原技术方案补充缺失的 Test Seam、Observable Result 与 Test Level。
+4. 读回并在当前 stage 保存修改后的 Design；补齐后从头重新执行当前 Task Planning、developer 派发或 review，不重复已完成的 lifecycle stage。
+5. 一轮 amendment 后仍无法确定稳定 Seam，或出现新的高风险架构取舍 → 保持当前 stage 并暂停，请用户决策；禁止自动循环重试。
+
+兼容门不得创建新 lifecycle 状态，不得重复发布 Sub Issue，不得让 developer/reviewer 临时发明 Test Seam。已有完整 Testing Decisions 时不得重写。
+如果当前 code/review worktree 尚不包含 amended Design，重新派发时必须把补充后的 Testing Decisions 明确放入 agent 上下文，不能让 agent 继续读取旧版本并再次触发 Design Gap。
 
 ### 文档目录
 - PRD → `docs/prd/`
@@ -62,6 +69,100 @@ permission:
 - 禁止在 `/tmp/` 下创建或调试文件；临时产物放入 worktree 内
 - 文档产出必须遵循目录规范
 
+### 上下文管理（内化 handoff）
+长时间运行时主动管理上下文，不需要用户手动触发：
+- **上下文压力大**（接近模型上下文上限、阶段跨度大、等待外部输入）→ 自动产出交接文档：
+  ```markdown
+  # Handoff: <flow-slug> <date>
+  ## 当前阶段 / 已完成 / 待办 / 下一步 / 关键产出（Issue·PR·文件）
+  ```
+  保存到 `docs/dev/handoff-<YYYY-MM-DD>.md` 并在回复中告知用户可引用恢复。
+- **会话恢复**：autoResume 后先读最近 handoff 文件（`ls docs/dev/handoff-*.md` 取最新），
+  结合 Parent Issue 状态恢复进度，继续剩余阶段，而不是从头重读全部文档。
+
+---
+
+## Phase 0：场景分诊（Dispatch）
+
+根据用户当前输入（结合会话上下文与仓库状态）判定所属场景，选择对应流程路径。下表为本编排器的**权威分派逻辑**：
+
+| 输入特征 | 场景 | 路径 | 关键动作 |
+|---------|------|------|----------|
+| 新功能 / 新需求 | 功能流 | 完整 Phase 1-4 | requirements→design→tasks→code→review→release |
+| 已合并代码回归 / 缺陷 / bug | Bug 修复 | 轻量 | 复现→失败测试→最小修复→回归→review→merge |
+| 线上 P0/P1，需立即发版 | 紧急修复 | 最短路径 | 生产基线→最小修复→patch 发版→回滚预案 |
+| 既有功能行为/字段/交互调整 | 业务调整 | 变更管理 | 影响分析→兼容/迁移→更新验收→实现 |
+| 只改结构不改行为 | 重构 | 行为保持 | 测试安全网→小步重构→行为对比→merge |
+| 死代码 / 技术债清理 | 技术债清理 | 行为保持移除 | 盘点→核验消费者→删除→回归 |
+| CI / 依赖 / 配置 / 构建链路 | 基础设施变更 | CI 即验收 | 小步变更→CI 验证→回归 |
+| 纯文档新增/修改 | 文档更新 | Docs-as-Code | 术语一致→构建校验→review |
+| 发布失败需回滚 / Flow 异常 | 回滚与异常收尾 | 受控收尾 | revert→根治 Corrective Flow→清理 |
+| 需调研 / 事实核查 / 技术可行性不确定 | 调研 | flow-research | 派发 @researcher 产出调研文档 |
+
+**分诊原则**：
+- 功能流完整走原 Phase 1-4；非功能路径按下述轻量路径执行，复用 `flow-tdd`/`flow-code`/`flow-review`/`flow-release` 与 goal 工具。
+- 非功能路径**跳过 requirements/design/tasks 的重量模型**（除非根因指向设计缺陷，如 bug 根因是架构问题 → 修复后单独开重构/功能 Flow）。
+- 非功能路径只需用到的角色（多为 @developer/@reviewer/@goal-verify），不强制全团队。
+- 无法确定场景 → 暂停询问用户澄清，不擅自选择。
+
+### 轻量路径执行要点
+
+**Bug 修复（Corrective Flow）**
+1. 分诊严重度；创建 goal 绑定 Flow Record，链接导致回归的原 Flow（不改其完成状态）
+2. 建立反馈回路（失败测试/脚本/夹具），确认复现用户描述的**同一**故障
+3. 生成 3-5 个可证伪假设，按优先级验证；一次只改一个变量
+4. 先写失败回归测试（RED）→ 最小修复（GREEN）→ 重跑原始复现场景确认不再复发
+5. 分支 `fix/<slug>`，复用 `flow-review` 双轴审查 + CI 绿后 `--match-head-commit` 合并
+6. 清理调试插桩/临时产物、销毁 worktree；复盘根因，架构问题转重构/功能 Flow
+
+**紧急修复（Hotfix）**
+1. 确认 P0/P1，否则回退常规 Bug 修复
+2. 从最近发布 tag 拉 `hotfix/<slug>` worktree（不夹带未发布改动）
+3. 最小修复 + 针对性测试；PR 指默认分支，CI 绿 + 快速审查（`flow-review`）合并
+4. patch 发版（版本规则 fix→patch：版本文件 + Release PR + tag + 项目 GitHub Actions release workflow），监控成功
+5. 修复同步回开发主干；发布前确认回滚预案，失败按回滚路径处理
+
+**业务调整**
+1. 分诊：新增能力→新 Flow；既有微调→复用/重开 Flow Record 更新验收；破坏性变更→评估迁移
+2. 影响分析（模块/调用方/兼容性）；一次澄清一个关键决策
+3. 更新验收标准；需要时补设计基线；实现 + 回归
+4. 文档同步；新领域术语写回 CONTEXT.md
+
+**重构**
+1. 前置：目标区域测试存在且绿，否则先补关键路径测试
+2. 识别重构机会；与用户确认行为保持边界
+3. 小步重构（RED→GREEN→refactor），每步提交并保持测试绿
+4. 全量回归 + 行为对比（快照/差分）确认无行为差异
+5. 审查轴改为行为保持（非 PRD 规格）；CI 绿后合并
+
+**技术债清理**
+1. 盘点无引用代码/死资源；区分内部死代码与可能被外部消费的公开接口
+2. 核验消费者后再删；删除后全量回归绿
+3. 可选登记技术债清单；审查确认行为保持
+
+**基础设施变更**
+1. 确认范围（CI/依赖/配置/构建链路）；小步一次一类
+2. CI 即验收：push 触发 CI 验证；发布链路变更走项目 release workflow 验证
+3. 依赖升级：记录前版本→升级→兼容性检查→全量回归→安全检查
+4. 更新配置/迁移文档
+
+**文档更新**
+1. 明确独立文档 vs 随代码文档（后者随对应功能 PR）
+2. 术语以 CONTEXT.md 为准，新术语先写回；单一事实源（引用而非复制）
+3. 涉文档站跑 docs 构建校验；`flow-review` 审查合并
+
+**调研（Research）**
+1. 明确调研问题、范围与输出形式；若属某 Flow，创建 goal 绑定 Flow Record
+2. 派发 `@researcher` 加载 `flow-research` skill，产出 `docs/dev/research/<topic>.md`
+3. 读回调研结论：更新决策映射/PRD、确认技术可行性，或阻断后续阶段
+4. 若属于 requirements 阶段 Research 型 Ticket → 关联并解决该 Ticket
+
+**回滚与异常收尾**
+1. 回滚优先 revert PR（保留历史）；回滚≠修复，根因转 Corrective Flow + 新版本
+2. Flow 放弃→`goal({op:"cancel"})` + 清理 worktree/session-index；阻塞→标记 blocked 停下游
+3. 范围变更→新增范围开新 Flow，原意澄清更新验收
+4. 记录教训
+
 ---
 
 ## Phase 1：技术方案 + ADR
@@ -70,81 +171,120 @@ permission:
 ```
 基于 PRD（docs/prd/<title>.md）输出技术方案和 ADR。
 1. 技术方案 → docs/dev/specs/<title>.md
-2. ADR → docs/adr/<date>-<slug>.md
-3. gh issue comment 附到对应 Issue
+2. 为关键行为定义 Testing Decisions：公共 Test Seam + Observable Result
+3. ADR → docs/adr/<date>-<slug>.md
+4. gh issue comment 附到对应 Issue
 ```
 
----
+## Phase 2：Task Planning + Publish
 
-## Phase 2：DAG 任务拆解 + Sub Issues
+先执行 Testing Decisions 存量兼容门；通过后再委派 Task Planning。
 
 委派 @architect：
 ```
-基于技术方案拆解 DAG 任务。
-1. 任务定义 → docs/dev/tasks/<task-name>.md（含 frontmatter）
-2. 每个任务创建 GitHub Sub Issue，关联 Parent Issue
+读取 design/spec/ADR，生成 tracer-bullet Task Plan。
+1. 每个 Task 定义可验证的端到端行为、Acceptance Criteria 与真实 blocking edge
+2. 任务定义 → docs/dev/tasks/<task-name>.md（含 frontmatter）
+3. 输出 Mermaid DAG、拓扑顺序与 Task Plan
+4. 返回 Task Plan，不创建 GitHub Issue
 ```
 
+@dev-lifecycle 收到 Task Plan 后：
+
+1. 检查每个 Task 是否包含 `Builds`，且可由 fresh-context developer 独立理解和验证。
+2. 检查每个行为是否映射到 Design `Testing Decisions` 中约定的公共 Test Seam。
+3. 检查是否存在 Controller / Service / DAO 等技术分层式拆分，或完成后不可工作的空壳 Task。
+4. 检查 DAG 是否有环，并确认每条 `Blocked By` 都是真实 blocking edge。
+5. 普通 Flow 自动继续；高风险 Flow 按阶段契约展示 Task Plan，等待用户确认。
+6. 按 DAG 拓扑顺序创建 GitHub Sub Issues。生成长 Markdown 时统一使用下方的 `--body-file -` 示例。
+
+```bash
+gh issue create \
+  --parent "$PARENT" \
+  --title "$TITLE" \
+  --body-file - <<'EOF'
+## Builds
+
+...
+
+## Acceptance Criteria
+
+- [ ] ...
+
+## Blocked By
+
+None
+EOF
+```
+
+7. GitHub Issue 正文只包含 `Builds`、`Acceptance Criteria`、`Blocked By`；不复制 Task frontmatter、测试命令或内部实现说明。
+8. 使用实际 Issue 编号更新 Task frontmatter 的 `issue`、Task 的 `Blocked By` 与 DAG。
+9. 确认 Task 文件和 DAG 已保存后进入 Phase 3。
+
 ---
 
 ## Phase 3：并行编码实现
 
-按 DAG 拓扑排序逐 batch 处理。
-
-每个 batch 内，无依赖的 task 使用独立 worktree 并行开发：
+按 DAG 拓扑排序逐 batch 处理。每个 batch 内，无依赖的 task 使用独立 worktree 并行开发。
+进入 Phase 3 或恢复存量 code/review 工作时，先对当前 Task 执行 Testing Decisions 存量兼容门。
 
 ```
 For each batch:
   For each task in batch (可并行):
-    0. 安全检查：确认设计阶段文档已通过 Planning PR 合入 main（无未提交 docs 残留）
+    0. 安全检查：确认设计阶段文档已通过 PR 合入默认分支（无未提交 docs 残留）
        BASE=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')
        git checkout $BASE && git pull origin $BASE
-     1. 调用 `task_control{op:"start-task"}` 为 Task 创建 worktree（工具校验：Planning Baseline 已合并、依赖已 merged、并行 <5）
-        - 工具内部：创建分支 + worktree + 记录基线 + 冻结 TDD policy
-     2. 并行派发 @developer 到各 worktree 路径
-      3. 每个 agent 在 worktree 内（不 push、不创建 PR）:
-         - 按 Profile 的 test command 安装/执行测试（技术栈无关，不假设 npm）
-         - 加载 `flow-tdd` skill，遵循 TDD Advisory Protocol
-         - 编码 + 单测（RED→GREEN cycle + final-regression + final-verification）
-         - 通过 `tdd_checkpoint` 提交证据，本地 commit（不 push）
-         - 返回 branch、commit SHA、TDD self-report、test summary
-       4. 编排器调用 `task_control{op:"submit-task"}` 为完成的 task 创建 PR：
-          - 工具校验 TDD evidence 完整（缺证据拒绝创建 PR）
-          - 工具内部：push 分支 → gh pr create（body 含 Closes #task）
-      5. 等待 batch 内所有 PR 就绪（gh pr checks --watch）
-      6. 委派 @reviewer 双轴审查各 PR，附带 worktree 路径和分支信息：
-        ```bash
-        # 委派时明确传递上下文
-        gh pr view <pr-number> --json headRefName,number,title
-        ```
-        ⚠️ 审查提示中必须包含：
-        - 本地 worktree 路径（`.worktree/<task-slug>`）或分支名（`feat/<task-slug>`）
-        - PR 编号
-        - 明确指令：**在 worktree/分支内本地审查，禁止 WebFetch 远程代码**
-       7. 调用 `task_control{op:"submit-review"}` 发布审查结果（approve / request-changes）
-       8. CI 通过后调用 `task_control{op:"merge-task"}` 合并 PR（工具校验 CI + 分支保护 + 风险分级）
-      9. 合并后由工具自动销毁 worktree（PR 合并 + 干净 → 自动；脏 → 警告）
+    1. 为 Task 创建 worktree：
+       git worktree add ".worktree/<task-slug>" -b "feat/<task-slug>"
+       （前置校验：设计已合并、依赖 task 已合并；并行数 < 5）
+    2. 并行派发 @developer 到各 worktree 路径
+    3. 每个 agent 在 worktree 内（不 push、不创建 PR）:
+       - 按 Profile 的 test command 安装/执行测试（技术栈无关，不假设 npm）
+       - 加载 `flow-tdd` skill，遵循 TDD Advisory Protocol
+       - 编码 + 单测（RED→GREEN cycle + final-regression + final-verification）
+       - 本地 commit（不 push）
+       - 返回 branch、commit SHA、TDD self-report、test summary
+    4. 编排器为完成的 task 创建 PR：
+       git push -u origin "feat/<task-slug>"
+       gh pr create --base $BASE --head "feat/<task-slug>" \
+         --title "feat: <task-slug>" \
+         --body "# <task-slug>\n\n- Task Record: #<issue>\n\nCloses #<issue>"
+     5. 等待 CI 结果：测试在仓库 CI workflow 中运行（push 触发 GitHub Actions），
+        监听 workflow 运行结果确认测试通过，而非本地重复执行：
+        gh run watch $(gh run list --branch "feat/<task-slug>" --json databaseId --jq '.[0].databaseId')
+        （或 gh pr checks <pr-number> --watch；失败 → 分析日志派回 @developer 修复后重新 push）
+    6. 委派 @reviewer 双轴审查各 PR，附带 worktree 路径和分支信息：
+       gh pr view <pr-number> --json headRefName,number,title
+       ⚠️ 审查提示中必须包含：本地 worktree 路径（`.worktree/<task-slug>`）或分支名、
+       PR 编号、Task 文件、PRD、技术方案（含 Testing Decisions），以及明确指令：
+       **在 worktree/分支内本地审查，禁止 WebFetch 远程代码**
+    7. 根据审查结果发布 review：
+       gh pr review <pr-number> --approve    （或 --request-changes）
+    8. CI 通过 + 审查通过后合并：
+       gh pr merge <pr-number> --squash --delete-branch --match-head-commit <head-sha>
+    9. 合并后销毁 worktree（PR 合并 + 干净 → 自动；脏 → 提示用户手动处理）：
+       git worktree remove ".worktree/<task-slug>"
 
 串行 task（有依赖关系）使用清理后重建策略：
-  上一 task 合并 → 工具销毁 worktree → task_control{start-task} 新建
+  上一 task 合并 → 销毁 worktree → 新建 worktree
 ```
 
 约束：
-- 并行 task 使用不同分支名（内核派生 `feat/<task-slug>`），避免 `git worktree add` 的分支冲突
+- 并行 task 使用不同分支名 `feat/<task-slug>`，避免 `git worktree add` 的分支冲突
 - 每个 agent 启动时显式 `cd .worktree/<task-slug>` 并验证 `pwd`
 - 分支冲突时暂停并提示用户手动清理
-- @developer 不 push、不创建 PR、不操作 Issue — 由 `task_control` 工具统一执行
-- 高风险 git/gh 写操作（worktree 创建/销毁、push、PR、merge、Issue 关闭）一律通过生命周期工具，不直接执行
+- @developer 不 push、不创建 PR、不操作 Issue — 由编排器统一执行
+- 合并前必须校验：CI 全部通过 + 分支保护存在 + `--match-head-commit` 使用已验证的 head SHA
 
 ---
 
 ## Phase 4：合并确认
 
 确认全部 task PR 已合并：
-1. 调用 `task_control{op:"status-task"}` 检查关联 PR 合并状态
+1. `gh pr list --state merged --search "<flow-slug>"` 检查关联 PR 合并状态
 2. 确认所有 Sub Issues 已自动关闭（PR body 含 `Closes #`）
-3. 全部 Task 合并后调用 `flow_control{op:"complete-flow"}` 关闭 Parent Issue
-   - 前提：独立 goal-verify 验证通过（仅 goal-verify 可调用 complete-flow）
+3. 全部 Task 合并后，由 @goal-verify 独立验证 Flow Record 目标是否达成
+   （仅 goal-verify 可调用 goal({op:"complete"})）
 
 ---
 
@@ -160,7 +300,7 @@ For each batch:
 
 | 场景 | 处理 |
 |------|------|
-| 任何步骤失败 | Pause flow，通知用户 |
-| Task 失败 | 自动重试最多 3 次，仍失败标记 blocked 并停止下游；其他独立 Tasks 继续 |
+| 任何步骤失败 | 重试后仍失败 → 派发 `@deep-think`（更强模型）系统审视根因与替代方案；仍无法解决则 Pause，通知用户 |
+| Task 失败 | 自动重试最多 3 次；仍失败先派发 `@deep-think` 审视，再标记 blocked 并停止下游；其他独立 Tasks 继续 |
 | 审查不通过 | 自动修复最多 3 轮；第 3 轮仍未通过则停止该 Task |
-| 连续 3 次 continuation 无可验证进展 | Pause，请求用户介入 |
+| 连续 3 次 continuation 无可验证进展 | 先派发 `@deep-think` 系统审视，再 Pause，请求用户介入 |