Skip to main content
I

openspec-agents

ifrankwang/openspec-agents

OpenSpec process plugin: proposals clarify requirements up front and get a dedicated review pass; implementation runs in an isolated worktree, grouped by task unit per round, leaving the main repo untouched; development and review are split across two agents — a change cannot finish while functional or quality issues remain open, they loop back to the developer agent; bundled standards define the review baseline, with Vue frontend and Java backend kits included.

Install

dsh plugin --profile web add github:ifrankwang/openspec-agents

README

openspec-agents

License: MIT Built for OpenSpec

openspec-agents 是 OpenSpec 的配套插件,兼容 Claude Code / Codex / ZCode / DeepSeek Harness / OpenCode:提案前先澄清需求,并对提案文档做一轮复核;实施在独立 worktree 中进行,不影响主仓库,每轮以一个任务组为单位推进;实施由开发与审核两个 Agent 分工,功能有问题或质量不通过时不允许结束,问题会退回开发 Agent 修复;内置多类规范 skill 作为质量审查基准,支持 Vue 前端与 Java 后端项目。

前提:项目正在使用 OpenSpec 管理需求。

适合变更需要真正落进代码库、有验收标准、需通过检查、过程可追溯的团队与项目
不适合希望快速产出 demo、不走检查与验收的场景
代价比单个 AI 直接修改更慢,Token 消耗更高
模型选型实施用 flash 类模型,提案用旗舰模型

常见痛点

  • AI 一次改一大片,改完声称「完成了」——能编译、测试也通过,但其中夹带的空实现与伪成功未被发现。
  • 共用逻辑被改动后,其他调用入口仍在使用旧写法,无人察觉。
  • 出了问题想复盘,只能翻到大量对话记录,看不出当时按什么标准放行。

与工具自带工作流的区别

Claude Code 和 DeepSeek Harness 自带的工作流能力擅长并行完成大量独立任务。这个插件解决的是另一件事,两者可以叠加使用。

工具自带的工作流本插件
擅长并行完成大量独立任务单个变更按阶段推进,逐层把关
如何放行由脚本中的判断决定由程序强制:检查未完成、问题未闭环时无法以「通过」提交
跨工具各家私有同一套流程跨工具通用
中断之后进度依附于对话或单次运行进度记录在仓库中,换会话、换工具均可继续

一句话:原生工作流负责把任务做完,这个插件负责判定产出是否达到可交付标准。

局限

使用前请先确认以下三条边界。

存量项目需要一次收敛成本。 判据按理想状态定义(方法不超过 50 行、类职责单一、核心域不依赖框架、构建产物需忽略、覆盖率需达标),且工具检查覆盖全量代码——存量违规同样按原级别上报并阻塞。存量项目首次运行会暴露大量存量问题,只能逐个修复,或逐个走豁免裁定;裁定通过的会沉淀进项目级清单,后续变更不再重复阻塞。

技术栈配套需覆盖到你的栈。 通用规范 skill 与技术栈无关;内置的 Java 后端与前端(Vue / React)配套在此之上补齐具体构建与检查命令(构建工具、格式、静态分析、覆盖率、质量扫描平台接入)。其他技术栈项目审查照常执行,但编译、格式、静态分析、覆盖率、端到端这几项确定性检查没有现成命令,需补一份技术栈 skill(在 frontmatter 声明 stacks / frameworks 即可被识别并加载),否则只能按降级申报跳过。

架构规范只有 DDD 一套。 包组织有两种等价的合法风格——四层分层(domain / application / infrastructure / interfaces)与六边形(内核 + 入站 / 出站适配器),采用哪种由项目声明,未声明时按四层认定。不按 DDD 组织的项目(例如 MVC + Service + DAO 直写)没有对应规范,会被判定为偏离规范并报出问题;项目已有自己的架构规范时以项目规范为准,但该规范需自行写入。

快速开始

项目还没用 OpenSpec 的话,先装 CLI(初始化由插件代做):

npm install -g @fission-ai/openspec

在项目里调用 /openspec-standard 时,项目还没有 openspec/ 就会先以 Core Profile 初始化,项目根随即出现 openspec/ 目录。

第一步:安装

按你用的工具选一种,装完重启该工具。

Claude Code
claude plugin marketplace add https://github.com/ifrankwang/claude-code-plugins
claude plugin install openspec-agents@ifrankwang
Codex
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 plugin --profile web add @ifrankwang/openspec-agents

web 是 profile 名,换成你自己的(~/.dsh/profiles/ 下的目录名)。装完重启该 profile;作用项目随当前会话所属项目自动确定,同一个 profile 下切换项目不必重装或改配置。编排工具需要在一个项目会话里使用。

要求 DSH 0.2.1 及以上。子代理的角色提示词与工具集由 Agent Preset 承载,profile 需包含 web 应用 bundle(desktop / web 模板都满足)。子代理委派为异步:分派返回后本轮即结束,收到完成通知再继续下一步。

OpenCode

要求 OpenCode 2.x(1.x 的插件接口不兼容)。

npm install -D @ifrankwang/openspec-agents

然后在 OpenCode 配置的 plugins 中登记 @ifrankwang/openspec-agents:

// opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "plugins": ["@ifrankwang/openspec-agents"]
}

配置项须写作 plugins(复数),旧版的 plugin(单数)在 OpenCode 2 中不被识别。

首次加载时,插件会在项目 .opencode/agents/ 下生成三个代理定义文件。这些文件带生成标记,插件每次加载都按当前版本重写;要自己改,先删掉文件里的生成标记。

第二步:确认安装成功

重启后查看可用 skill 列表:openspec-standard、orchestrator 是插件自带的两个入口,它们和一批规范类 skill 一起出现在列表里,就说明插件已经生效。这些 skill 可以像命令一样唤起(DSH 里输入 / 即可看到并调用)。

第三步:开始使用

  • 项目里还没提变更时,调用 /openspec-standard,把提案标准装进项目。
  • 提变更用 OpenSpec 官方命令:/openspec-propose {具体需求描述},生成 openspec/changes/<变更名>/ 下的文档;装过提案标准后,这些文档会按更严的标准产出。
  • 然后调用 /orchestrator {change-id} 开始编排。{change-id} 就是那个目录名,openspec list 能看到当前有哪些变更。

不同工具里 skill 的呈现形式可能不同,以各工具实际显示为准。

默认无人值守

各安装方式默认都开启无人值守:流程里需要人拍板的环节(方案怎么选、无法自动验证的部分)由编排 AI 自行决断,不会停下来问你——审查和门禁照常跑,变的只是「要不要来问你」。希望它在这些地方先问你,让它关掉无人值守模式即可。

项目级配置基线

编排在初始化时按会话声明的形态补齐项目的配置文件,不需要手动维护。两类配置共用一套写入语义:只补不覆盖——文件缺失时按模板创建,已存在时只追加缺失条目或键,已有的值一律不动;提交语义分会话——主仓库侧只写工作树、不 git add、不提交;change 会话在 worktree(.worktree/{changeId}/ws)创建或复用时补跑基线守卫,ignore 基线与扫描平台配置直接提交进 change 分支;独立审查(review)会话维持只写主仓库、不在 worktree 侧提交。

忽略配置(.gitignore / .prettierignore)有三个来源:

  • 编排产物(强制):.worktree/、openspec/states/ 始终写入 .gitignore,不因已有否定规则而跳过。
  • 框架通用基线:任何项目都补齐 .DS_Store、IDE 配置、日志、本地环境变量等通用条目。
  • 能力级基线:按声明的形态与框架,由对应能力声明自己的构建产物、依赖缓存、测试报告目录;前端项目同时补齐 .prettierignore。

忽略条目写入时,! 形式的显式保留会被尊重并写进报告;子路径否定(如 !dist/keep.txt)同样会被识别,此时不追加其父目录条目。主仓库侧改动可安全提交时(工作区该文件干净、当前分支与基准分支一致、非只审不修的独立审查会话)以独立提交落库;存在用户未提交改动、detached HEAD 或跨分支时只写工作树并说明原因。worktree 侧(change 会话)不受基准分支一致性限制——worktree 检出的必为 change 分支,基线守卫跳过分支校验直接提交;基线已在 change 分支中时守卫幂等重跑,不产生空提交。基线资产缺失时,返回体会显式提示「基线资产缺失」。

扫描平台配置(项目根的 sonar-project.properties 一类)由能力自带的模板提供,能否补齐取决于本机环境:初始化先按本机在跑的容器(docker 或 podman)匹配;没有命中时,无论本机没有容器运行时、还是运行时可用但没有匹配的容器在运行,都会退回仓库根 compose 文件的文本判断。compose 命中就按模板创建配置文件(已存在则只补缺失键),并在来源里标注按 compose 识别、以及容器是否在运行;只有 compose 也未命中才跳过、不建空文件,跳过文案按「无运行时」「运行时可用但零容器在运行」「有容器但无匹配平台」三种情况区分。配置文件里不写任何凭据,token 走环境变量或命令行。worktree 侧补齐时 project.key 一类身份键按主仓库根目录名计算,不取 worktree 子目录名。

豁免与抑制区块:审查视图把三件事收在同一个区块里——已豁免清单、本轮已抑制、配置一致性核对。已豁免清单只列与本次变更文件相关的条目(路径模式按 glob 匹配),最多列 50 条且超出时显式提示截断;全量代码库审查按总条数加前 50 条渲染。本轮已抑制列出本轮命中清单被丢弃的提报,另标历史存量条数。清单提到提报之前,让审查者先对照、不必靠记忆;三段都只做展示,不参与门禁判定。

抑制配置与豁免记录双向核对:扫描平台配置里的每条忽略(排除项)都要有对应的跨 change 豁免记录,豁免记录也要能在配置里找到落点——只改配置不登记豁免、或豁免记录在配置里没有对应忽略,都算不一致。核对段按必做清单是否含该检查项决定是否渲染(full 的 verify_tool 与 simple 的 quality_review 都会出现),不按 step 名判断;除「两侧一致 / 按方向列出缺失项」外,还有「未核对(会话未固化项目栈)」与「已跳过 N 条未识别声明」两种输出。核对段只做展示,不参与门禁判定,config_check 仍是必做项、其证据可对照核对结果。

提案标准化

OpenSpec 官方默认的流程是 proposal → specs → design → tasks,给出文档骨架与写作要求。这套标准在它前面加一道澄清与确认关,文档写完后加一道独立架构复核,并把改动范围、契约变更、文档语言钉得更死。另在 specs 与 design 之间插入一道条件化的 prototype(拟真原型)工件:涉及界面视觉 / 交互的变更先出可双击打开的单文件 HTML 原型,纯逻辑变更只写一页「不涉及用户可见界面」的声明。

OpenSpec 官方 spec-driven插件提供的 spec-driven-standard
阶段proposal → specs → design → tasksclarify → proposal → specs → prototype(原型,条件化)→ design → tasks;文档齐备后多一道 架构审查(Phase 3)
需求澄清澄清不强制,靠 explore 用法自行把握决策树逐轮提问,每题附推荐答案;事实类疑问自己查代码,不抛给你
动笔门禁无疑点问完 + 你确认方案,才允许开始写文档;确认必须文字回复,点选项不算
改动范围proposal 里一句 Impact 描述关联场景清点:把用到这块逻辑的入口、复用链路、数据上下游全列出来,每条附代码位置,逐条跟你确认纳入还是排除;共用逻辑的所有入口必须同一变更里一起改
规则边界推演无新增或改动规则、校验、拦截逻辑时,先推演这条规则本身站不站得住:该拦的条件与例外、功能上合法却会被误伤的合法反例(各对应 spec 一条「应当放行」场景)、同一业务意图的等价执行路径与判定挂载点(挂在业务意图层的动作上,不落在被别的流程复用的底层动作上);变更新增或改了执行路径时,逐条核对既有规则在新路径上是否仍该生效
方案复核无文档写完后由独立架构 reviewer 全面复核(Phase 3):架构方向合理性(与仓库既有架构脉络契合、长期演进、兼容性、平行实现与技术债)、跨文档一致性、design 架构合规、规则边界推演核对、关联场景覆盖、与主规格交叉核对;产出按任务组的执行边界(允许改动的目录与包)写入 clarify.md,实施初始化时读取并作为实施范围;问题涉及你已确认的架构方向时,回到你重新确认
契约变更无专门要求逐条列:建表到列(名/类型/可空/默认值/用途)、接口到字段与方法路径、兼容性影响
文档语言要求 spec 避免类名、函数名方案摘要与实施逻辑也必须用人话,禁止类名、方法名这类代码黑话(契约事实与技术设计文档除外)
任务划分分组 + 每条带验证方式追加:每组必须有真实代码改动(禁止「收尾组」凑数)、测试跟着实现同组、只覆盖本仓库
归档官方归档命令本身会同步主规格追加写作纪律:主规格只写终态,不留「原 X 改为 Y」;废弃项显式删除并补 REMOVED;同语义合并去重

用法:在目标项目的普通会话里调用 /openspec-standard(不要在被编排流程占用的会话里调用,那种会话不能改文件)。项目还没有 openspec/ 时,它先以 Core Profile 执行 openspec init --profile core --tools agents:建 openspec/ 骨架,并在 .agents/skills/ 下生成 propose、explore、apply、update、sync、archive 六个 workflow skill;随后写入 openspec/config.yaml(指定 spec-driven-standard schema)与 openspec/schemas/spec-driven-standard/(schema、文档模板与架构审查职责文本;文档模板含 templates/prototype.md 原型模板)。

装好之后提变更不必换命令,仍走 OpenSpec 官方用法:调用 /openspec-propose {具体需求描述},生成的 proposal / specs / prototype / design / tasks 就会按这套标准产出,再由 /orchestrator {change-id} 接手实施与把关。

已经装过标准的项目重跑就是升级:标准更新到插件当前版本,你自己加的规则条目和项目背景会保留。

质量把关机制

「生产级」不是靠提示词要求的,而是逐层校验出来的。

审查分工

完整模式  实现 → 工具检查 → 独立验收 → 五维质量审查 → 收尾验证 → 收口
精简模式  实现 → 合并审查(工具检查 + 独立验收 + 五维质量审查)→ 收口

精简模式的「合并审查」是把完整模式的三步审查合并到一名审查者身上,不是跳过:工具复验、独立验收、五维质量审查由同一名审查者一轮内做完。确定性检查由开发者执行并按本轮必做清单逐项申报(must_do_checks,每项附证据);审查者全量重跑分钟级低成本项(环境、编译、格式、架构约束、静态分析、单元测试、配置检查),深度扫描与全量接口测试改为核验开发者申报加核心链路抽样重放,申报缺证据、抽验不符、发现断言放水或修复轮波及接口契约时回退全量重跑。必做项申报口径分三类:工具实跑申报(低成本项,附执行命令与结果摘要)、核验申报(仅限白名单限定的深度扫描类高成本项,附核验方式与抽验样本)、人工核对申报(核对类项如维度规范逐 skill 核对,附核对对象与结论记录)。

最终判定不由实现者自己作出。完整模式下,检查、验收、质量审查由彼此独立的角色分步承担;精简模式由一名审查者独立承担这三项。

工具与 AI 的分工

确定性检查全部交给工具执行:编译、代码格式、架构约束、静态分析、单元测试与覆盖率、深度扫描,以及质量工具配置有没有被弱化。AI 审查只负责工具覆盖不到的部分——业务行为是否真实生效、关键数据是否真的落库、测试断言有没有放水、设计与规则边界是否站得住,并把其中可工具化的发现反过来沉淀成规则。判据锚在 skill 上,不是让模型现场发挥,所以非旗舰模型(flash 类)的产出下限同样有保障。

通过标准

  • 五级定级:Critical / High / Medium / Low / Info,各级判例锚定规范 skill;Info 仅为建议,Low 及以上未修复不得推进。
  • 问题闭环:审查报出的问题挂在变更上,修复后由报出该问题的审查者复核通过方为终结;确实无法修复的提交豁免申请,由同一审查者裁定,被驳回则退回重修,裁定通过的沉入项目级跨 change 清单,后续变更再报同一问题时直接抑制、不入库。本轮提报全被抑制、且没有任务驳回或边界扩展时按通过收口,必做清单与任务覆盖门禁照常校验。
  • 程序强制:检查未完成、问题未闭环时,无法以「通过」提交——由工具拦截,而非依赖提示词约束。需申报的必做项按 workflow 声明与项目形态栈动态生成,实现与审查两端同口径校验:完成项必须附证据(口径按必做项类型分三类——工具实跑、白名单限定的核验申报、人工核对申报),未完成项必须填结构化降级理由;实现侧声称「本轮无代码变更」时会按实际变更检测核对,不采信自述,且核对类必做项(维度规范逐 skill 核对)不被整体豁免覆盖,仍须单独申报。
  • 禁止规避:压制注解、关闭规则、修改扫描平台状态一律视为豁免申请,须写明理由并接受裁定;同一问题修复未过两次,须先完成根因分析再修改。
  • 规则沉淀:可由工具检出的问题,要求同时提交业务问题与规则草案,将本次判定口径沉淀为后续的自动拦截规则。

其他特性

  • 变更隔离:变更在独立分支与独立工作副本中进行,收口前基准分支上看不到这些改动;基准分支不要求是当前检出分支(多基准分支用法见「对仓库的写入范围」)。
  • 可续跑:进度记录在仓库中,查询当前状态即可恢复;关闭工具、跨天、更换工具都能从上次位置继续。
  • 规范驱动:直接消费 OpenSpec 的提案、规格、设计与任务清单,流程与规范一一对应。

初始化编排时选择流程模式,默认为精简模式。提案期由架构 reviewer 复核方案与文档并产出执行边界,实施首轮直接进入开发;精简模式省的是流程步骤,不是检查内容:工具检查、验收与五维质量审查由一名审查者一轮合并完成,收口直接合并、正常路径不做合并后的回归复验;完整模式三项审查由独立角色分步执行,收口前还会把基准分支合并进来跑一轮回归复验。实施中上报 blocker 需要回退时,回退落点是 analyze 步骤——只做 blocker 裁决并按需修订执行边界,不再承担文档复核,也不再初次产出执行边界。两种模式(完整 / 精简)都从 clarify.md 的「执行边界」小节读取本任务组的实施范围,缺失或解析失败时按整个 worktree 处理;主仓库里遗留的变更规划文档副本(污染)由兜底逻辑并入变更工作副本并清理主仓库工作树,触发点同样是两种模式首次 implement passed,且只执行一次。

内置的规范库

插件自带一套 skill(含两个流程入口),安装后即可使用,无需自行编写提示词;审查 AI 会按当前任务自动加载对应的一组,作为判据的最低基准——审查者还需结合自身领域知识扩展覆盖,不限于清单所列条目。

两个入口

  • orchestrator —— 编排准则,主代理按它分派子代理、推进流程。
  • openspec-standard —— 提案标准初始化。

通用规范:DDD 分层与六边形、REST 接口约定(含接口版本演进与废弃、时间与时区)、数据库设计约定、安全审查基线、确定性质量门、测试设计、技术债识别、架构演进审查、API 自动化测试、隔离环境清理。

Java 后端配套:在通用规范之上补齐 Java / Spring 的实现细节 —— Lombok、日志与命名约定、REST 接口的 Java 实现、MyBatisPlus 与 Flyway、DDD 的 Java 实现与 ArchUnit 规则、术语表落地检查、Maven / Spotless / PMD / 质量扫描平台接入、工具规则改进、Java 开发实践(事务与并发、消息与缓存一致性、可观测性、发布与回滚)、Java 安全实现(含依赖合规落地)、Java 性能与可维护性、Java 技术债形态。

前端配套:补齐 Vue / React 项目的实现细节 —— 组件与状态管理分层、错误码消费、TypeScript 严格度与可维护性、国际化落位、代码风格与 ESLint / Prettier、可访问性基线、响应式基线、设计系统与组件库治理、前端设计标准(用 DESIGN.md 固定视觉语言并定义字段状态语义)、依赖分层校验、性能预算与懒加载、Vitest 覆盖率、SonarJS 深度扫描、前端安全实现(含真实用户监测与错误上报)、前端开发实践(pnpm / MSW mock / 浏览器与设备基线)、前端技术债形态、前端 e2e(Playwright)与工具规则改进。

skill 用「形态标签」(stacks:backend / frontend)与「框架标签」(frameworks:java / vue / react)声明自己适配哪类项目。初始化编排会话时必传本项目的形态栈与框架栈(opx_orch_init 的 project_stacks / project_frameworks,独立审查入口同样必传),skill 清单与必做清单门禁都按这份声明过滤:skill 声明的标签与会话同通道取值有交集即加载,未声明该通道的 skill 视为通用、始终加载;两个值域分字段校验,跨字段混用或传入未声明的值会被直接拒绝。扩展新框架不需要改工具代码——新增或替换 skill 时在 frontmatter 写 stacks / frameworks 即可被动态识别。

规范覆盖对照

人工对照用的覆盖视图:说明标准规范里哪些类别由哪个 skill 承担、在什么前提下成立。非穷举清单,非门禁——skill 是判据的最低基准,审查者仍须结合领域知识扩展覆盖。

规范类别承担 skill适用前提
可访问性frontend-code-style直接核对(语义标签、表单标签、键盘可达、焦点样式、颜色非唯一载体);无障碍合规等级项目自定
国际化frontend-code-maintainability第一层(文案集中、统一格式化、显式时区)直接核对;第二层(key 规范、复数与语序、缺译回退)需已接入对应底座(语言包与翻译流程);多语言范围项目自定
响应式与浏览器基线frontend-code-style(响应式布局)、frontend-dev-practices(浏览器与设备基线)响应式布局(断点、溢出、hover 依赖、缩放场景)直接核对;浏览器基线的版本区间与构建目标需已接入对应底座(公司浏览器标准),公司电脑统一设置下的可用性直接核对
真实用户监测与错误上报frontend-security需已接入对应底座(监控平台或错误上报平台)
错误码消费frontend-architecture直接核对
设计系统与组件库治理frontend-code-style控件唯一实现直接核对;组件版本与升级口径需已接入对应底座(组件库与设计令牌来源)
事务与并发java-dev-practices直接核对
消息与缓存一致性java-dev-practices直接核对
可观测性java-dev-practices需已接入对应平台(监控平台)
发布与回滚java-dev-practices需已接入对应平台(发布流水线)
依赖合规java-security(Java 落地)、security-baseline(许可与漏洞扫描口径)直接核对(依赖树、BOM 收敛、私服顺序、依赖混淆防护);许可证策略与依赖漏洞扫描需已接入对应平台(许可策略 / 依赖扫描流水线)
API 版本演进与废弃api-conventions直接核对
术语表落地java-ddd-architecture直接核对
界面语义与交互一致性frontend-code-style直接核对(必填 / 禁用 / 只读的可见标识与程序属性同源,空 / 加载 / 出错三态可分辨,危险操作有确认)
前端设计标准(DESIGN.md)frontend-design-standard直接核对(DESIGN.md 令牌与 8 段正文,8 种状态的视觉与程序双承载)
  • 「直接核对」指不依赖额外底座,按仓库现状即可判定;「需已接入对应底座 / 平台」指判据建立在项目已接好的语言包、监控平台、组件库、发布流水线或公司浏览器标准之上,这些承载物不在项目里时该规范不成立(不属于可直接核对的类别)。
  • 公司统一浏览器时,只核对窗口尺寸、浏览器最低版本与公司电脑统一设置,不做跨浏览器种类兼容。
  • 无障碍合规等级、多语言范围、支持哪些浏览器种类属于项目自定项:由项目明确声明,未声明时按表中「直接核对」部分的最低基线核对。

维护要求:增删或重命名 skill 时同步核对此小节。

独立审查会话

除了绑定变更的编排,插件也支持不绑定任何变更的独立代码审查:对一个 PR 的改动区间、或整个代码库做一次完整审查。

初始化时说明以下事项:

  • 项目形态栈与框架栈:project_stacks(如 backend / frontend)与 project_frameworks(如 java / vue / react),两入口均必传;取值须为 skill 已声明的标签,形态与框架分字段不可混用。
  • 审查范围:pr(两个本地分支之间的改动区间,远端分支名会被拒)或 full(全量代码库)。
  • 颗粒度:thorough(工具检查 → 回归验证 → 风格 / 架构 / 性能 / 安全 / 可维护性五个维度的质量审查)或 simple(一个审查者合并完成全部检查)。
  • 修复策略:fix(发现问题自动修复再重审)或 none(只审不修,问题报告本身即交付物)。

审查在独立工作副本里进行。fix 模式全部通过后把工作分支合并回目标分支并清理环境;none 模式不合并,直接销毁工作环境并按严重级别、维度、文件位置归并给出审查结果。

对仓库的写入范围

编排流程只碰这几处,全在你的仓库内:

  • openspec/states/ —— 流程进度;
  • .worktree/<变更号>/ws —— 本次变更的独立工作副本(创建/复用时补跑基线守卫并提交进变更分支);
  • 一条 change/<变更号> 分支。

另外两处不在编排流程内:OpenCode 安装方式首次加载会在 .opencode/agents/ 放三个代理定义文件;调用 /openspec-standard 在项目尚未初始化时先以 Core Profile 建 openspec/ 骨架并生成 .agents/skills/ 下六个 workflow skill,再写 openspec/config.yaml 与 openspec/schemas/spec-driven-standard/。

变更的全部任务组完成后,才会把这条分支合并回基准分支,随后自动删掉工作副本和分支。收口合并前,工具会自动执行 openspec archive 把变更文档归档(移入 archive/)并把 delta 同步进主 specs,归档提交随合并带回基准分支;归档失败时回退到收尾验证,修复后重新收口。合并前如果基准分支已经往前走了,插件先比对两边改动:只有文档、规划文件或版本号这类无害变化时直接合并;有实质冲突时退回做一次收尾回归,通过后才合并。

多基准分支:基准分支默认取发起时主仓库的当前检出分支,也可以用 base_branch 显式指定其它本地分支。比如主仓库停在 next-release 上开发新功能、线上 bug 的变更要合回 main,发起时传 base_branch="main" 即可:主仓库始终停在原分支,插件用底层 git 命令从 main 切出 change/<变更号> 分支、收口时再把它合并回 main 并推进分支引用,不切换你的检出,也不动工作区。

跨分支发起时,openspec/changes/<变更号>/ 规划文档随工作副本创建自动同步进变更分支并单独提交,主仓库工作树里的未跟踪副本同步清理。工作副本可复用(切任务组重入)或主仓库已检出变更分支本身时,跳过规划文档预检直接复用——此时权威副本就在变更分支上,主仓库工作树的过时副本属正常态。规划文档已提交在当前检出分支、而基准分支上没有时,搬移会形成双份,工具不擅自处理,返回 blocked 并给出人工处理命令;基准分支已自带规划文档时,先与当前工作树逐文件比对:同一版本则跳过同步并在返回体说明;版本不一致则返回 blocked,不搬运也不覆盖。主仓库工作树里规划文档已暂存未提交、或主仓库处于 detached HEAD 且确实有文档待同步时,同样返回 blocked:前者先提交或用 git restore --staged 取消暂存,后者切到明确分支后重试。收口合并时,若基准分支正被另一个工作副本检出、或主仓库本地改动与合并将写入的文件重合(含部分暂存),同样返回 blocked 并保留工作副本与分支,按提示处理后重试即可。

中途放弃:删除工作副本与 change/<变更号> 分支即可,基准分支不会留下该变更的任何代码。

开发

bun install            # 安装依赖
bun test               # 运行测试
bun run typecheck      # 类型检查
bun run build:plugins  # 构建各平台的插件包(发布用)

贡献

欢迎提交 Issue 与 Pull Request,也欢迎 Star 支持。

致谢

本项目基于 OpenSpec(openspec.sh)构建 —— 感谢 OpenSpec 团队带来的规范驱动开发方法:先写规范、再写代码,让 AI 开发有据可依。

许可证

MIT © 2026 ifrankwang

Related plugins