@ifrankwang/openspec-agents 0.126.0 → 0.127.0

package/.mcp-server/cli.mjs

@@ -35738,6 +35738,15 @@ function assertValidRecovery(recovery) {
     }
   }
 }
+function otherTaskGroupsSettled(state, targetGroupId) {
+  return state.workItems.filter((w) => w.id.startsWith("task:") && w.id !== `task:${targetGroupId}`).every((item) => {
+    if (item.phase === "done" || item.metadata["completed_at"] !== undefined)
+      return true;
+    const noTags = Object.keys(item.tags).length === 0;
+    const childrenSettled = item.children.filter((c) => c.type === "task").every((c) => c.phase === "todo" || isTerminalPhase(c.phase));
+    return noTags && childrenSettled;
+  });
+}
 async function initExecute(params, ctx) {
   assertOrchestrator(ctx, "opx_orch_init");
   const args = { ...params };
@@ -35780,6 +35789,19 @@ async function initExecute(params, ctx) {
   const baseBranch = args.base_branch || await getCurrentBranch(ctx.worktree);
   let state = await readStateByChangeId(ctx.worktree, args.change_id);
   const wasCurrentGroup = state?.taskGroupId === args.task_group_id;
+  let modeSwitchNote = null;
+  if (state && args.mode !== undefined && args.mode !== (state.mode ?? "full")) {
+    const othersSettled = otherTaskGroupsSettled(state, args.task_group_id);
+    const withinWindow = (args.task_group_id !== state.taskGroupId || args.recovery?.phase === "task_analysis") && othersSettled;
+    if (!withinWindow) {
+      throw new Error(`mode 参数与已固化的流程模式不一致：已固化 mode="${state.mode ?? "full"}"${state.mode === undefined ? "（旧变更未固化，读取时兜底 full）" : ""}，传入值："${args.mode}"。
+` + `当前场景不允许切换流程模式：切换任务组须其他任务组均已完成或从未激活；重制当前组仅支持 recovery.phase="task_analysis"（其他任务组同样须已完成或从未激活）。
+` + `请去掉 mode 参数继续沿用固化模式，或满足上述窗口条件后再切换。`);
+    }
+    const prevMode = state.mode;
+    state.mode = args.mode;
+    modeSwitchNote = `流程模式已从 ${prevMode ?? "full"} 切换为 ${args.mode}。`;
+  }
   if (!state) {
     state = {
       changeId: args.change_id,
@@ -35880,7 +35902,12 @@ async function initExecute(params, ctx) {
   }
   state.taskGroupId = args.task_group_id;
   await writeState(ctx.worktree, state);
-  return args.recovery ? `编排会话已初始化。已恢复到 ${args.recovery.phase} 阶段。` : "编排会话已初始化。";
+  const parts = ["编排会话已初始化。"];
+  if (args.recovery)
+    parts.push(`已恢复到 ${args.recovery.phase} 阶段。`);
+  if (modeSwitchNote)
+    parts.push(modeSwitchNote);
+  return parts.join("");
 }
 async function bindWorktreeRefs(item, worktreePath, branch, baseBranch, opts = {}) {
   item.metadata["worktree_path"] = worktreePath;
@@ -36848,7 +36875,7 @@ var orchInitSchema = {
     mode: {
       type: "string",
       enum: ["full", "simple"],
-      description: "流程模式选择：full=完整流程（analyze→implement→三重审查+收尾验证）；simple=精简流程（implement→quality_review→done，缺省）。仅新建编排状态（首次 opx_orch_init）时生效；已开始的变更沿用固化模式，不支持中途切换。"
+      description: "流程模式选择：full=完整流程（analyze→implement→三重审查+收尾验证）；simple=精简流程（implement→quality_review→done，缺省）。首次新建编排状态时固化；已开始的变更仅在允许窗口内可更新：切换任务组（其他任务组均已完成或从未激活）或 recovery.phase=task_analysis 重制当前组（其他任务组同样须已完成或从未激活）；其余场景传不同 mode 将报错。"
     }
   },
   required: ["change_id", "task_group_id"],
@@ -37040,7 +37067,7 @@ function jsonSchemaToZod(schema2) {
 var AGENT_ARG = "_agent";
 var TOOL_SPECS = {
   opx_orch_init: {
-    description: "初始化编排会话。传入变更 ID 和任务组 ID，工具自动解析 tasks.md 提取全部任务组并解析目标组子任务。可通过 recovery 参数恢复到指定阶段。无 recovery 重复初始化当前任务组时保留其阶段和进度；切换到其它任务组时初始化该组。可选 mode 参数（full/simple，缺省 simple）选择流程模式，仅新建状态生效。",
+    description: "初始化编排会话。传入变更 ID 和任务组 ID，工具自动解析 tasks.md 提取全部任务组并解析目标组子任务。可通过 recovery 参数恢复到指定阶段。无 recovery 重复初始化当前任务组时保留其阶段和进度；切换到其它任务组时初始化该组。可选 mode 参数（full/simple，缺省 simple）选择流程模式：首次新建状态时固化；已开始的变更仅切组（其他任务组均已完成或从未激活）或 recovery.phase=task_analysis 重制当前组（其他任务组同样须已完成或从未激活）时可更新，其余场景传不同 mode 报错。",
     schema: orchInitSchema,
     execute: (args, ctx) => initExecute(args, ctx)
   },
@@ -37100,7 +37127,7 @@ async function ensureDefaultUnattended(args, ctx) {
     }
   } catch {}
 }
-var PKG_VERSION = "0.126.0";
+var PKG_VERSION = "0.127.0";
 function buildMcpServer(worktree, opts = {}) {
   const mcp = new McpServer({ name: "openspec-agents", version: PKG_VERSION });
   for (const [name, spec] of Object.entries(TOOL_SPECS)) {

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ifrankwang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,129 +1,110 @@
 # openspec-agents
 
-OpenSpec 流程的 Agent Team：面向实施阶段的多 Agent 工作流编排。
+![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)
+![Built for OpenSpec](https://img.shields.io/badge/built%20for-OpenSpec-6b46c1.svg)
 
-> 当前定位：把已确定的 OpenSpec change 落地为高质量代码。
-> 未来方向：向前扩展「探索 + 方案制定」，覆盖 OpenSpec 更早期环节。
+> 让多个 AI 智能体按规范流程协作，把 OpenSpec 变更规范落地为经过审查的高质量代码。
 
-## 它解决什么问题
+`openspec-agents` 是一组面向 AI 编码工具的插件，把 OpenSpec 的「需求 → 设计 → 任务拆分」成果，自动推进到「实现 → 验证 → 质量审查 → 收尾合并」的完整实施流程。主智能体负责调度，专职智能体分别承担实现、检查与质量把关，每一步都有门禁确认，全程可审计、可恢复。
 
-OpenSpec 把需求、设计、任务拆解成规范文档后，实施阶段仍然需要多步开发、验证、质量审查和收尾。本项目用一组 Agent 角色 + workflow 引擎，把这一过程编排成可重复、可审计的流水线：
+## 特性
 
-`analyze → implement → verify_tool → verify_task → verify_quality → verify_cleanup → done`（full 模式；simple 模式见「编排流程」）
+- **多工具支持**：Claude Code、Codex、ZCode、DeepSeek Harness（DSH）、OpenCode 均可原生接入。
+- **规范驱动**：直接消费 OpenSpec 变更规范（proposal / design / tasks / specs），流程与规范一一对应。
+- **智能体团队**：不再是单个 AI 从头写到尾，而是「实现者 + 审查者 + 质量把关者」分工协作，结果更稳。
+- **质量门禁**：实现之后经过工具检查、任务验证与多维度质量审查；发现的问题自动回退修复，也可按规则豁免并留痕。
+- **隔离执行**：每个变更在独立的环境中实施，互不干扰；变更完成后合并并清理。
+- **过程可审计**：进度、结论、豁免与恢复点全程记录，随时可以接着上次的进度继续。
 
-主代理负责调度，子代理负责实施、审查、质量验证和清理；所有裁决通过统一 `opx_*` 工具提交，状态持久化到仓库内。
+## 快速开始
 
-## 编排流程
+1. 准备环境：**Node.js ≥ 23.6**（或 Bun）与 **git**。
+2. 按下方「安装」选择你正在使用的 AI 工具完成安装。
+3. 重启该工具后，把下面「一句话接入」的提示词发给你的 AI 即可开始。
 
-实施流程按变更开始时固化的模式执行：模式经 `opx_orch_init` 的 `mode` 参数在变更开始时固化（`full` 完整流程 / `simple` 精简流程，不传缺省 simple）。已开始的变更不受后续参数影响；恢复（recovery）沿用固化模式；旧变更（状态无模式存档）一律按 full 处理，不支持中途切换。
+## 安装
 
-### full 模式
+按你使用的 AI 工具选择一种方式：
 
-`analyze → implement → verify_tool → verify_task → verify_quality → verify_cleanup → done`
+### Claude Code
 
-分析、实现、三层审查（工具检查 / 任务验证 / 五维质量审查）与收尾验证逐步推进，问题可回退、可豁免、可检查点决策。
+```bash
+claude plugin marketplace add https://github.com/ifrankwang/claude-code-plugins
+claude plugin install openspec-agents@ifrankwang
+```
+
+### Codex
+
+```bash
+codex plugin marketplace add https://github.com/ifrankwang/codex-plugins
+codex plugin add openspec-agents@ifrankwang
+```
+
+### ZCode
+
+打开 ZCode 插件页，添加市场 `ifrankwang/zcode-plugins`，然后安装 `openspec-agents`。
+
+### DeepSeek Harness（DSH）
+
+```bash
+dsh plugin --profile web add @ifrankwang/openspec-agents
+```
 
-### simple 模式
+安装后重启 `dsh web` 即可。
 
-`implement → quality_review → done`
+### OpenCode
 
-面向轻量变更的精简流程：无 analyze 环节（执行边界默认整个 worktree），无 verify_tool / verify_task / verify_cleanup 环节。implement 失败自循环重试；quality_review 由单一审查者合并承担工具检查、任务验证与质量审查（工具改进建议双报机制保留，由开发者实施），失败回 implement 整步重审；开发者实施时按已加载接口测试规范即时更新并执行 `.http` 接口测试自证变更有效（含关键数据产出断言）；开发者提交 implement 成果时强检查工作区干净（不干净拒绝并提示先 commit），收尾为直接合并分支并清理（裸合并，无回归；环境清理由审查者验证完成后自行完成——停止残留服务、清理隔离环境，收尾不单独承担环境清理；合并冲突由开发者解决后直接收尾）。tasks.md 复选框在任务组收尾（opx_orch_complete_task_group）时统一勾选当前任务组，勾选提交落在 worktree 分支、随合并带回主分支；full 与 simple 行为一致，任务完成状态以状态文件为准。
+```bash
+npm install -D @ifrankwang/openspec-agents
+```
+
+然后在 OpenCode 配置中加载 `@ifrankwang/openspec-agents` 插件，重启 OpenCode。
+
+## 让 AI 帮你接入（一句话）
+
+安装后（甚至还没安装时），直接把这句提示词发给你的 AI 编码工具：
+
+> 请帮我安装并启用 openspec-agents 插件，然后基于当前项目的 OpenSpec 变更规范，执行完整的变更实施编排流程。
 
-## 身份与角色
+英文版：
 
-物理 agent 定义收敛为两个子代理（`assets/agents/` 下的 `openspec-developer.md`、`openspec-reviewer.md`，主代理模板 `openspec-main.md` 保留），9 种逻辑身份（architect、reviewer-tool、reviewer-task、style / architecture / performance / security / maintainability 五维审查者、simple 审查者）不再有独立定义文件，统一经 `_agent` 参数承载：子代理调用 `opx_*` 工具时传自身角色名，系统按该逻辑身份路由状态视图、issue 来源与筛选、「谁提谁裁定」与状态标识。
+> Please install and enable the openspec-agents plugin for my current AI coding tool, then run the OpenSpec change orchestration workflow on this repository.
 
-- 开发者物理 agent 承载 developer 与 architect 两个逻辑身份；审查者物理 agent 承载 tool / task / 五维 / simple 审查者逻辑身份。full 模式的质量审查以 5 个逻辑身份并行执行——同一物理审查者被多次分派，每次以不同 `_agent` 参数承载对应逻辑身份。
-- 物理权限取各逻辑身份权限并集（维度审查者因此具备编辑与写入能力）；审查行为以「只报不改」指令约束兜底——文档/注释等不影响代码运行的问题可直接修改，逻辑类问题只上报，full 模式同样适用。
-- `_agent` 为纯自述、无硬校验：任何调用者可自报任意身份，裁定权与视图路由均信任自述值；冒认只能以自报身份行事，无法越出该身份自身的既有权限面。
+如果已经安装，只需说一句「请运行 openspec-agents 编排流程」即可开工。AI 会负责完成安装、初始化、任务分派与质量把关的全部步骤。
 
-## 特色
+## 工作原理（简述）
 
-- **Agent 无关**：内核不绑定具体 Agent，opencode / claude code / codex / zcode / deepseek harness 通过各自原生插件/适配器接入同一套状态机。
-- **Workflow 驱动**：步骤、角色、门禁在 workflow 中声明，`opx_status` 是下一步调度的唯一事实源。
-- **多 Agent 团队**：主代理编排，2 个物理子代理承载 9 种逻辑身份分工协作，避免单一大模型从头写到尾失控。
-- **强 Review 门禁**：full 模式 tool / task / quality 三层审查 + 收尾验证；simple 模式单一审查者合并审查。问题可回退、可豁免、可检查点决策。确定性质量工具问题以压制手段解决时视为豁免申请，须说明理由并经审查判定合理性。
-- **隔离与安全**：每个 change 使用独立 git worktree、资源隔离命名空间（数据库、mock 服务、消息队列/缓存等中间件、扫描分析平台均按隔离标识隔离），减少相互干扰。
-- **可观测**：内置进度看板，状态/豁免/并发锁持久化到 `openspec/states/`。
+1. **输入**：项目中的 OpenSpec 变更规范（变更说明、设计、任务清单、验收规格）。
+2. **分派**：主智能体把任务交给专职智能体——实现者负责写代码，审查者负责检查，质量把关者负责多维验证。
+3. **门禁**：每一步的结论通过检查后才进入下一步；不通过的结论自动回到实现环节修复。
+4. **收尾**：变更完成后自动合并分支并清理执行环境，全程留痕可审计。
 
-## 优缺点
+## 适用场景与代价
 
 | | |
 |---|---|
-| 优点 | 产出代码质量高；有明确流程和门禁，结果不会太过偏离目标；过程可审计、可恢复 |
-| 缺点 | 慢（多轮 Agent 调用 + 多级 review）；贵（token/API 消耗高于单 Agent 直接改） |
+| 适合 | 对代码质量、过程可控性要求高的团队与项目 |
+| 代价 | 比单个 AI 直接修改更慢，API 消耗更高 |
 
-适合对质量、可控性要求高，且愿意用成本换稳定产出的实施场景。
+如果你愿意用一点成本换取稳定、可复现、可审计的实施过程，这个项目就是为你准备的。
 
-## 接入方式
+## 开发
 
-项目已为各 Agent 工具提供官方插件/适配器，普通使用时直接按对应工具的原生机制接入即可，无需手动拼装或启动 MCP Server。
+```bash
+bun install            # 安装依赖
+bun test               # 运行测试
+bun run typecheck      # 类型检查
+bun run build:plugins  # 构建各平台的插件包（发布用）
+```
 
-依赖：Node.js ≥ 23.6（或 Bun）、git。
+## 贡献
 
-```bash
-# 安装依赖
-bun install
+欢迎提交 [Issue](https://github.com/ifrankwang/openspec-agents/issues) 与 Pull Request，也欢迎 Star 支持。
 
-# 测试 / 类型检查
-bun test
-bun run typecheck
-```
+## 致谢
 
-各 Agent 接入：
-
-- **OpenCode**：以 npm 插件形式加载，插件注入 agent/skill 与 MCP server 配置（`config.mcp` 的 stdio server，自包含 bundle，`--worktree` 指向当前项目根）。
-  ```bash
-  npm install -D @ifrankwang/openspec-agents
-  ```
-  然后在 OpenCode 配置中加载 `@ifrankwang/openspec-agents` 插件并重启 OpenCode（MCP server 配置在启动时加载）：`opx_*` 工具以 `mcp__opx__*` 形态出现（如 `mcp__opx__status`、`mcp__opx__agent_submit`，serverName=opx），身份经 `_agent` 参数承载（缺省视为编排视角）。
-
-- **Claude Code**：通过官方插件市场安装。
-  ```bash
-  claude plugin marketplace add https://github.com/ifrankwang/claude-code-plugins
-  claude plugin install openspec-agents@ifrankwang
-  ```
-
-- **Codex**：通过官方插件市场安装。
-  ```bash
-  codex plugin marketplace add https://github.com/ifrankwang/codex-plugins
-  codex plugin add openspec-agents@ifrankwang
-  ```
-
-- **ZCode**：在 ZCode 插件页添加市场 `ifrankwang/zcode-plugins`，然后安装 `openspec-agents`。
-
-- **DeepSeek Harness（DSH）**：通过 DSH 的 bundle 插件机制接入。发布到 npm 后可直接安装：
-  ```bash
-  dsh plugin --profile web add @ifrankwang/openspec-agents
-  ```
-  本地开发时也可使用构建产物：
-  ```bash
-  bun run build:plugins
-  dsh plugin --profile web add ./dist/deepseek-harness-plugin
-  ```
-  安装后重启 `dsh web`：
-  - `opx_*` 会以 `mcp__opx__*`（如 `mcp__opx__status`、`mcp__opx__agent_submit`） 原生工具出现；
-  - `assets/skills` 会作为额外 skill 根被扫描；
-  - 每个子代理会注册为 DSH 原生 subagent 工具：`openspec_developer` 与 `openspec_reviewer` 两个物理子代理，编排主代理可直接分派（9 种逻辑身份经 `_agent` 参数承载，同一物理子代理可被多次分派）。
-
-## 常用命令
-
-| 命令 | 说明 |
-|------|------|
-| `bun test` | 运行所有测试 |
-| `bun run typecheck` | TypeScript 类型检查 |
-| `bun run build:plugins` | 构建 Claude Code / Codex / ZCode / DeepSeek Harness 插件包（CI/内部使用） |
-| `bun run sync` | 同步本地最新开发版本到各 harness 插件缓存，并安装/刷新依赖 |
-
-## 项目结构
+本项目基于 [OpenSpec](https://github.com/Fission-AI/OpenSpec)（[openspec.sh](https://openspec.sh)）构建——感谢 OpenSpec 团队带来的规范驱动开发方法：先写规范、再写代码，让 AI 开发有据可依。本插件专注于补全 OpenSpec 变更的**实施与质量把关**环节，是对 OpenSpec 工作流的编排增强。
 
-```
-src/core/                  — Agent 无关内核（状态机、工具执行器、状态持久化）
-src/adapters/              — opencode / claude-code / codex / zcode / deepseek-harness / mcp 适配层
-assets/agents/             — Agent 定义
-assets/skills/             — 内置 skill（含 orchestrator）
-assets/workflows/          — workflow 定义
-tests/                     — 测试
-```
+## 许可证
 
-详细实现见 `AGENTS.md` 与 `src/core/`、`assets/workflows/`。
+[MIT](LICENSE) © 2025 ifrankwang

package/package.json

@@ -1,6 +1,13 @@
 {
   "name": "@ifrankwang/openspec-agents",
-  "version": "0.126.0",
+  "version": "0.127.0",
+  "description": "OpenSpec change orchestration plugin for AI coding agents (Claude Code, Codex, ZCode, DeepSeek Harness, OpenCode)",
+  "author": "ifrankwang",
+  "license": "MIT",
+  "homepage": "https://github.com/ifrankwang/openspec-agents#readme",
+  "bugs": {
+    "url": "https://github.com/ifrankwang/openspec-agents/issues"
+  },
   "type": "module",
   "main": "./src/core/index.ts",
   "exports": {

package/src/adapters/deepseek-harness/index.ts

@@ -25,6 +25,7 @@ import {
   buildAgents,
   buildSkills,
   copyWorkflows,
+  copyLicense,
   readPkgVersion,
   type PluginPackageResult,
 } from "../plugin-common/index.ts"
@@ -32,6 +33,9 @@ import {
 /** DSH bundle 的 npm 包名（与项目发布包一致，便于 `dsh plugin add` 与 sync 识别）。 */
 export const DSH_PLUGIN_NAME = "@ifrankwang/openspec-agents"
 
+/** DSH bundle 包的作者署名（与各插件包 plugin.json 的 author 保持一致）。 */
+export const PLUGIN_AUTHOR_STRING = "ifrankwang"
+
 /** 默认插件包输出目录（dist/ 已 gitignore，生成物不入库）。 */
 export const DEEP_SEEK_HARNESS_PLUGIN_DIR = resolve("dist", "deepseek-harness-plugin")
 /** 简写别名，便于与 `dsh` 缩写保持一致。 */
@@ -174,6 +178,7 @@ export function buildDeepSeekHarnessPlugin(outDir: string = DEEP_SEEK_HARNESS_PL
   const skills = buildSkills(join(outDir, "skills"))
   bundleMcpServer(outDir)
   copyWorkflows(outDir)
+  copyLicense(outDir)
 
   writeFileSync(
     join(outDir, "package.json"),
@@ -184,6 +189,8 @@ export function buildDeepSeekHarnessPlugin(outDir: string = DEEP_SEEK_HARNESS_PL
         description: PLUGIN_DESCRIPTION,
         type: "module",
         private: true,
+        author: PLUGIN_AUTHOR_STRING,
+        license: "MIT",
         dsh: {
           bundle: {
             patch: `./${MANIFEST_PATCH_FILENAME}`,

package/src/adapters/mcp-common/server.ts

@@ -37,7 +37,7 @@ interface ToolSpec {
 const TOOL_SPECS: Record<string, ToolSpec> = {
   opx_orch_init: {
     description:
-      "初始化编排会话。传入变更 ID 和任务组 ID，工具自动解析 tasks.md 提取全部任务组并解析目标组子任务。可通过 recovery 参数恢复到指定阶段。无 recovery 重复初始化当前任务组时保留其阶段和进度；切换到其它任务组时初始化该组。可选 mode 参数（full/simple，缺省 simple）选择流程模式，仅新建状态生效。",
+      "初始化编排会话。传入变更 ID 和任务组 ID，工具自动解析 tasks.md 提取全部任务组并解析目标组子任务。可通过 recovery 参数恢复到指定阶段。无 recovery 重复初始化当前任务组时保留其阶段和进度；切换到其它任务组时初始化该组。可选 mode 参数（full/simple，缺省 simple）选择流程模式：首次新建状态时固化；已开始的变更仅切组（其他任务组均已完成或从未激活）或 recovery.phase=task_analysis 重制当前组（其他任务组同样须已完成或从未激活）时可更新，其余场景传不同 mode 报错。",
     schema: orchInitSchema,
     execute: (args, ctx) => initExecute(args as any, ctx),
   },

package/src/adapters/plugin-common/index.ts

@@ -18,9 +18,9 @@ import { parseAgentMd, resolve, EXCLUDED_AGENTS } from "../agent-md.ts"
 
 export const PLUGIN_NAME = "openspec-agents"
 export const PLUGIN_DESCRIPTION =
-  "OpenSpec change 编排：opx_* 编排工具（MCP）+ 编排子代理 + orchestrator skill，非 OpenCode agent 默认无人值守"
-/** plugin.json author（package.json 无 author 字段，取固定值）。 */
-export const PLUGIN_AUTHOR = "openspec-agents maintainers"
+  "OpenSpec change orchestration for AI coding agents: turn OpenSpec change specs into reviewed, high-quality code."
+/** plugin.json author（各插件包统一署名项目作者）。 */
+export const PLUGIN_AUTHOR = "ifrankwang"
 
 export function readPkgVersion(): string {
   return (JSON.parse(readFileSync(resolve("package.json"), "utf-8")) as { version: string }).version
@@ -98,6 +98,14 @@ export function copyWorkflows(targetDir: string): void {
   cpSync(resolve("assets", "workflows"), join(targetDir, "assets", "workflows"), { recursive: true })
 }
 
+/** 复制 MIT 协议文件到插件包根目录（随插件与 marketplace 一起分发）。 */
+export function copyLicense(targetDir: string): void {
+  const license = resolve("LICENSE")
+  if (existsSync(license)) {
+    cpSync(license, join(targetDir, "LICENSE"))
+  }
+}
+
 export interface PluginPackageParams {
   /** 输出目录（如 dist/zcode-plugin/） */
   outDir: string
@@ -129,6 +137,7 @@ export function buildPluginPackage({ outDir, manifestDirName }: PluginPackagePar
   // workflow 定义随包分发：bundle 内 TASK_WORKFLOW_PATH 按部署深度逐级上溯探测
   // assets/workflows/task.yaml，插件根（dist/cache 形态）上溯 1 级即命中
   copyWorkflows(outDir)
+  copyLicense(outDir)
 
   writeFileSync(
     join(outDir, manifestDirName, "plugin.json"),

package/src/core/state.ts

@@ -271,8 +271,8 @@ export async function readStateByChangeId(worktree: string, changeId: string): P
     createdAt: legacy.createdAt,
     updatedAt: legacy.updatedAt,
     unattended: legacy.unattended,
-    // 透传固化模式：state 已存在（重复初始化/切换任务组/recovery）时沿用既有 mode，
-    // 缺 mode 的旧变更保持缺省（消费端读时兜底 full，不在此写回）
+    // 透传固化模式：读取不改动 mode（缺 mode 的旧变更保持缺省，消费端读时兜底 full，不在此写回）；
+    // init 在允许窗口（切组/重制当前组，其他任务组均终态或从未激活）内可显式更新 state.mode
     mode: legacy.mode,
   }
   if (needsUpgrade) {

package/src/core/tools/lifecycle.ts

@@ -1,5 +1,5 @@
 import path from "path"
-import type { TaskItem, TaskStatus, WorkflowMode } from "../types.ts"
+import type { OrchestrateState, TaskItem, TaskStatus, WorkflowMode } from "../types.ts"
 import { BUILD_PHASE_TARGETS, REVIEW_LAYERS, REVIEW_VERIFY_STEPS } from "../types.ts"
 import { agentToReviewLayer } from "../constants.ts"
 import { runGit, runGitChecked, getCurrentBranch, getMergeBase, isWorktreeClean, markTaskGroupCheckboxesComplete, mergeBranchToTarget, discoverDiskWorktrees, detectMainRepoPollution, detectChanges, type DetectChangesResult } from "../git.ts"
@@ -278,6 +278,25 @@ function assertValidRecovery(recovery: InitParams["recovery"]): void {
   }
 }
 
+/**
+ * 判断目标组以外的全部任务组（workItems 中 `task:` 前缀、非目标组）是否"终态或从未激活"，
+ * 即 mode 切换窗口（W1 切组 / W2 重制当前组）的共同前置条件：
+ * - 终态：item.phase === "done" 或 metadata.completed_at 已设置；
+ * - 从未激活：无执行痕迹——tags 为空且所有 task children 的 phase 均为 todo 或终态（isTerminalPhase）。
+ */
+function otherTaskGroupsSettled(state: OrchestrateState, targetGroupId: string): boolean {
+  return state.workItems
+    .filter((w) => w.id.startsWith("task:") && w.id !== `task:${targetGroupId}`)
+    .every((item) => {
+      if (item.phase === "done" || item.metadata["completed_at"] !== undefined) return true
+      const noTags = Object.keys(item.tags).length === 0
+      const childrenSettled = item.children
+        .filter((c) => c.type === "task")
+        .every((c) => c.phase === "todo" || isTerminalPhase(c.phase))
+      return noTags && childrenSettled
+    })
+}
+
 export async function initExecute(params: InitParams, ctx: ToolContext): Promise<string> {
   assertOrchestrator(ctx, "opx_orch_init")
 
@@ -326,6 +345,31 @@ export async function initExecute(params: InitParams, ctx: ToolContext): Promise
   let state = await readStateByChangeId(ctx.worktree, args.change_id)
   const wasCurrentGroup = state?.taskGroupId === args.task_group_id
 
+  // state 已存在时的 mode 变更窗口校验/更新（位于 for 循环前——循环内非活跃组新建 item 与
+  // applyRecoveryState 均读 state.mode；错误早于任何状态变更抛出，不落盘）：
+  // - 无变更意图（不传 mode 或与生效值一致——旧 state 缺 mode 时生效值兜底 full）→ 放行，保持既有行为；
+  // - W1 切组：task_group_id ≠ state.taskGroupId 且其他任务组均终态或从未激活；
+  // - W2 重制当前组：recovery.phase=task_analysis 且其他任务组均终态或从未激活
+  //   （reopenIssues 仅支持 dev_impl，与 W2 天然互斥，不构成冲突路径）；
+  // - 窗口外传不同 mode → 报错。
+  let modeSwitchNote: string | null = null
+  if (state && args.mode !== undefined && args.mode !== (state.mode ?? "full")) {
+    const othersSettled = otherTaskGroupsSettled(state, args.task_group_id)
+    const withinWindow =
+      ((args.task_group_id !== state.taskGroupId || args.recovery?.phase === "task_analysis") && othersSettled)
+    if (!withinWindow) {
+      throw new Error(
+        `mode 参数与已固化的流程模式不一致：已固化 mode="${state.mode ?? "full"}"${state.mode === undefined ? "（旧变更未固化，读取时兜底 full）" : ""}，传入值："${args.mode}"。\n` +
+        `当前场景不允许切换流程模式：切换任务组须其他任务组均已完成或从未激活；重制当前组仅支持 recovery.phase="task_analysis"（其他任务组同样须已完成或从未激活）。\n` +
+        `请去掉 mode 参数继续沿用固化模式，或满足上述窗口条件后再切换。`
+      )
+    }
+    const prevMode = state.mode
+    state.mode = args.mode
+    // 旧变更未固化 mode 时读取兜底 full，切换说明按 full 表述
+    modeSwitchNote = `流程模式已从 ${prevMode ?? "full"} 切换为 ${args.mode}。`
+  }
+
   if (!state) {
     state = {
       changeId: args.change_id,
@@ -335,8 +379,8 @@ export async function initExecute(params: InitParams, ctx: ToolContext): Promise
       workItems: [],
       createdAt: new Date().toISOString(),
       updatedAt: new Date().toISOString(),
-      // 新建 state 时固化模式：取 init 参数 mode（缺省 simple）；state 已存在不读参数，
-      // 沿用 state 既有 mode；旧 state 缺 mode 由消费端读时兜底 full，不写回。
+      // 新建 state 时固化模式：取 init 参数 mode（缺省 simple）；state 已存在时的 mode 变更
+      // 由上方窗口校验统一处理（W1 切组 / W2 重制当前组），旧 state 缺 mode 由消费端读时兜底 full，不写回。
       mode: args.mode ?? "simple",
     }
   } else {
@@ -443,9 +487,10 @@ export async function initExecute(params: InitParams, ctx: ToolContext): Promise
   state.taskGroupId = args.task_group_id
   await writeState(ctx.worktree, state)
 
-  return args.recovery
-    ? `编排会话已初始化。已恢复到 ${args.recovery.phase} 阶段。`
-    : "编排会话已初始化。"
+  const parts = ["编排会话已初始化。"]
+  if (args.recovery) parts.push(`已恢复到 ${args.recovery.phase} 阶段。`)
+  if (modeSwitchNote) parts.push(modeSwitchNote)
+  return parts.join("")
 }
 
 async function bindWorktreeRefs(

package/src/core/tools/schemas.ts

@@ -217,7 +217,7 @@ export const orchInitSchema: JSONSchema = {
       type: "string",
       enum: ["full", "simple"],
       description:
-        "流程模式选择：full=完整流程（analyze→implement→三重审查+收尾验证）；simple=精简流程（implement→quality_review→done，缺省）。仅新建编排状态（首次 opx_orch_init）时生效；已开始的变更沿用固化模式，不支持中途切换。",
+        "流程模式选择：full=完整流程（analyze→implement→三重审查+收尾验证）；simple=精简流程（implement→quality_review→done，缺省）。首次新建编排状态时固化；已开始的变更仅在允许窗口内可更新：切换任务组（其他任务组均已完成或从未激活）或 recovery.phase=task_analysis 重制当前组（其他任务组同样须已完成或从未激活）；其余场景传不同 mode 将报错。",
     },
   },
   required: ["change_id", "task_group_id"],

package/src/core/tools/types.ts

@@ -28,7 +28,9 @@ export interface InitParams {
      *  恢复后 currentStep 落在第一个未全部通过的 verify step，可能早于被重置的 step。 */
     reset_steps?: ReviewVerifyStep[]
   }
-  /** 流程模式（full/simple），仅新建编排状态时生效；已开始的变更沿用固化模式，不支持中途切换。 */
+  /** 流程模式（full/simple）：首次新建编排状态时固化；已开始的变更仅在切组（其他任务组均已完成
+   *  或从未激活）或 recovery.phase=task_analysis 重制当前组（其他任务组同样须已完成或从未激活）
+   *  时允许更新，窗口外传不同 mode 报错。 */
   mode?: WorkflowMode
 }
 

package/src/core/types.ts

@@ -136,6 +136,8 @@ export interface OrchestrateState {
   updatedAt: string
   unattended?: boolean
   /** 变更开始时固化的流程模式（经 opx_orch_init 的 mode 参数写入，缺省 simple）。
-   *  缺失即旧变更，一律按 full 处理（读时兜底，不写回）；已存在的 state 不再被参数改动覆盖。 */
+   *  缺失即旧变更，一律按 full 处理（读时兜底，不写回）；已存在的 state 仅在 init 允许窗口
+   *  （切组且其他任务组均已完成或从未激活，或 recovery.phase=task_analysis 重制当前组）内
+   *  可被 mode 参数更新。 */
   mode?: WorkflowMode
 }