@birdie_moblie/open_spec 2.1.7

package/presets/flutter-mobile/plugin-hooks.json

@@ -0,0 +1,68 @@
+{
+  "schema": "spec-product",
+  "hooks": [
+    {
+      "id": "yapi-guidance-parse",
+      "stage": "parse",
+      "type": "skill",
+      "use": "yapi-source-guidance@mobile-marketplace",
+      "capability": "interfaces",
+      "required": true
+    },
+    {
+      "id": "yapi-guidance-tech",
+      "stage": "tech",
+      "type": "skill",
+      "use": "yapi-source-guidance@mobile-marketplace",
+      "capability": "interfaces",
+      "required": true
+    },
+    {
+      "id": "yapi-preview",
+      "stage": "tech",
+      "type": "command",
+      "use": "yapi-discovery@mobile-marketplace",
+      "operation": "preview",
+      "capability": "interfaces",
+      "required": true
+    },
+    {
+      "id": "yapi-plan-coverage",
+      "stage": "plan",
+      "type": "command",
+      "use": "yapi-plan-coverage@mobile-marketplace",
+      "capability": "interfaces",
+      "required": true
+    },
+    {
+      "id": "yapi-generation",
+      "stage": "execute",
+      "type": "skill",
+      "use": "yapi-codegen@mobile-marketplace",
+      "taskCategories": [
+        "api-codegen"
+      ],
+      "required": true
+    },
+    {
+      "id": "intl-workflow",
+      "stage": "execute",
+      "type": "skill",
+      "use": "intl-workflow@mobile-marketplace",
+      "taskCategories": [
+        "ui"
+      ],
+      "required": true
+    },
+    {
+      "id": "i18n-inline",
+      "stage": "execute",
+      "type": "command",
+      "use": "intl-locales-check@mobile-marketplace",
+      "taskCategories": [
+        "ui"
+      ],
+      "required": true
+    }
+  ]
+}

package/presets/flutter-mobile/ui-conventions.md

@@ -0,0 +1,122 @@
+<!-- openspec:fill-me -->
+<!-- 本模板只记录宿主事实。逐节核查实现与有效约定后填写；不适用项明确注明。填写完成删除首行标记。 -->
+
+# UI 约定（<项目名>）
+
+维护人：<团队>。组件、路径、命令与默认行为必须来自本项目；以下占位内容不是既定技术选型。
+
+## 0. 以宿主为准的项（覆盖设计稿）
+
+下列项按宿主约定实现与验收，设计稿上的对应值只作参考：scout 在复用清单标记「以宿主为准」，build 按约定实现并在 result.notes 写明，verify 不把它们与设计稿的差异登记为问题。没有这类项写「无」。
+
+| 项 | 宿主标准 | 与设计稿差异的处理 |
+|---|---|---|
+| 字体族 | <pubspec 已声明的字体族与字重档> | <只取设计稿字号与字重；其它字体族不下载、不注册> |
+| 导航栏 | <共享导航栏组件及构造参数> | <高度、返回键、标题样式由组件负责机型适配，不按设计稿调整> |
+| <其它，如安全区、状态栏> | <标准> | <处理> |
+
+## 1. 页面状态容器
+
+状态管理与规范：<实际技术、规范路径及可复用实现>。
+
+| 组件 / 范式 | 用途 | 位置 | 约束 |
+|---|---|---|---|
+| <已有状态容器> | <加载、成功、空数据、失败与恢复> | <路径及符号> | <默认行为与适用范围> |
+| <结果模型> | <结果、业务错误和网络错误传播> | <路径及符号> | <消息展示、重试与状态更新约定> |
+| <跨模块交互入口> | <刷新、通知或共享状态> | <公开接口路径> | <调用责任与生命周期> |
+
+- 初始状态、订阅及结果传播：<实际接法、初值和时序>。
+- 对象所有权与释放：<创建、借用、取消与释放责任>。
+- 防重复操作、并发与竞态处理：<已有组件或规则>。
+
+## 2. 弹窗与底部面板
+
+| 组件 | 用途 | 位置 | 约束 |
+|---|---|---|---|
+| <标准提示或确认组件> | <适用交互> | <路径及符号> | <默认样式、按钮与关闭行为> |
+| <面板或其他浮层> | <适用交互> | <路径及符号> | <默认布局和生命周期> |
+
+页面与浮层形态词表：<项目实际形态、命名及来源>。
+
+## 3. 分享与媒体
+
+| 组件 | 用途 | 位置 | 约束 |
+|---|---|---|---|
+| <实际入口或不适用> | <内容生成、系统分享、保存或复制> | <路径及符号> | <权限、默认样式和错误处理> |
+
+## 4. 偏好与本地存储
+
+| 入口 | 用途 | 位置 | 约束 |
+|---|---|---|---|
+| <实际存储入口> | <设置、筛选或共享偏好> | <路径及符号> | <键命名、作用域与一致性> |
+
+## 5. 主题与颜色
+
+- 主题与颜色的唯一来源：<主题扩展、token 或常量定义路径>。
+- 主题切换入口与测试驱动入口：<实际机制与调用位置>。
+- 固定色、渐变及历史兼容约束：<适用来源和定义位置>。
+
+## 6. 国际化
+
+- 是否适用及实际工具：<项目选择或不适用>。
+- 资源格式、源语言与路径：<真实格式和路径>；键命名：<真实约定>。
+- 代码读取入口：<实际 API 和示例路径>。
+- 翻译、增量合入、生成与校验：<所选插件 Hook、宿主命令及参数来源>。
+- 运行参数：<项目配置、本机环境或显式临时覆盖的来源>；模板不指定个人凭据、模型或服务地址。
+- 必需语言、占位符规则、忽略范围与历史文案保护：<配置与验证入口>。
+- 文案来源优先级：<设计、需求和实际决定的适用关系>。
+
+## 7. 网络与接口
+
+- 客户端、请求封装、地址配置与数据模型：<实际路径和符号>。
+- 路径参数、查询参数、请求体及序列化约定：<实际实现与公开调用示例>。
+- 生成器或手写实现：<项目选择及配置来源>；原始生成证据位置：<不进入业务源码编译的产物路径>。
+- 动态或未展开对象、错误和恢复策略：<数据保留、解析、鉴权与重试约定>。
+
+## 8. 数值与文案格式化
+
+百分比、精度、单位、时间及其他格式化：<现有工具、路径及业务约束>。
+
+## 9. 设计资产
+
+资源目录、注册方式与缺失资产占位组件：<项目事实>。
+已声明的 assets 目录：<pubspec.yaml 中的每一行>。Flutter 的目录声明不递归子目录，为新页面新建的子目录必须在 pubspec.yaml 单独登记，UI task 范围须含 pubspec.yaml。
+资源来源与 TODO 标识：<设计节点或缺失说明的记录方式>。
+
+- 结合页面截图与节点 Meta 核对图片的用途、显示尺寸、背景和主题。分别记录节点设计值与导出件已含效果；opacity、渐变、阴影已包含在导出件时不再重复叠加，不根据 alpha 通道是否存在推断效果是否已包含。
+- 下载成功后核对实际资源。底板或主题不符时优先选择合适节点、透明导出或宿主资源；应用保留原件，显示按设计与宿主适配。
+- 小图供模型查看时优先使用父级组件或页面截图及对应 Meta。模型输入限制按当前提供商处理，不把某个提供商的阈值写成宿主通用标准，不为模型查看而改动生产切图，也不把模型拒收当成下载失败。
+
+## 10. Figma 变量 → 项目 token 映射
+
+| Figma 变量 | 项目 token / 定义位置 | 主题与用途 |
+|---|---|---|
+| <实际变量> | <实际 token 和路径> | <适用主题和语义> |
+
+业务数值或状态的着色规则：<实际规则或不适用>。
+无变量的固定强调色或渐变：<来源与具名定义>。
+
+## 11. 字体规格 → TextStyle 约定
+
+实际字体族与已打包字重：<字体资源和配置路径>。
+
+| 语义规格 | 字号 / 设计字重 | TextStyle / 定义位置 | 用途 |
+|---|---|---|---|
+| <实际规格> | <设计值> | <项目样式及路径> | <适用范围> |
+
+## 12. 主题资源命名
+
+| 资源 / 节点 | 各主题资源名与路径 | 选择入口与调用位置 |
+|---|---|---|
+| <实际节点> | <项目支持的主题资源> | <实际方法及路径> |
+
+## 13. 页面验证入口
+
+| 入口 | 命令 / 路径 | 产出 |
+|---|---|---|
+| 页面契约与导航测试 | <实际可执行命令> | <日志位置> |
+| 主题切换测试 | <实际可执行命令或不适用> | <日志及截图位置> |
+| 整页截图 | <命令及实际视口、缩放、语言> | <截图路径> |
+| 静态检查 | <宿主实际命令及既定失败阈值> | <完整日志位置> |
+
+受保护文件（固定断言、夹具和 manifest，Worker 不得修改）：<路径清单>。

package/presets/flutter-mobile.yaml

@@ -0,0 +1,205 @@
+schemaVersion: openspec.team-preset.v1
+version: 2.2.4
+id: flutter-mobile
+title: Flutter Mobile
+description: Flutter 移动应用团队的 spec-product 默认配置
+marketplaces:
+  - name: mobile-marketplace
+    repo: git@gitlab.bitrue.com:flutter_app/mobile_marketplace.git
+    ref: 06081ec27a557d8f5e4d443aa8549ab026173f94
+plugins:
+  - name: lark-cli
+    marketplace: mobile-marketplace
+  - name: yapi-dart-coding
+    marketplace: mobile-marketplace
+    minVersion: 0.2.1
+  - name: project-review
+    marketplace: mobile-marketplace
+  - name: intl-utils
+    marketplace: mobile-marketplace
+    minVersion: 0.2.3
+scaffold:
+  - path: docs/agent/ui-conventions.md
+    template: flutter-mobile/ui-conventions.md
+    description: 项目 UI 约定清单，parse/tech/plan/ui Worker 的 required file hook 目标
+configPatch:
+  schema: spec-product
+  taskCategories:
+    ui:
+      notes: >-
+        项目事实以 docs/agent/ui-conventions.md 为准；scout 抽取本 task 用到的行进 context.md，缺项按节补读；
+        不自造替代组件、颜色或文案。
+    logic:
+      notes: 防重复提交、pending 互斥、异步竞态与关闭后回调必须用真实状态测试验证，异常后可重试；保持业务逻辑内聚；跨页面联动用显式契约接口，不依赖库私有 State。异步恢复后再失败也须结束公开 Future，并保持约定异常与状态。局部响应按请求作用域合并并保留未涉及项；互斥按业务键区分，同键防重不应吞掉不同键操作。测试覆盖局部响应保留、同键重复、不同键同时触发及全量刷新与局部响应乱序。
+    api-codegen:
+      notes: >-
+        仅通过已声明的接口源生成代码。生成后核对路径占位符与 replaceAll 匹配串一致、GET 参数走 queryParameters。
+        字段与需求不符、缺字段或注释枚举与 schema wire type 冲突即 blocked，不自造字段/转换。
+        成功码按各接口 description 原文逐个映射到宿主已有判定 getter（如 0 与 200 各有入口），不统一口径、不改共享默认。
+        生成物形状与空类处理以所选生成插件的 Skill 为准；开放对象丢数据即 blocked，回工具项目修复，不手写解析器绕过。
+        原始 Dart 证据用 .dart.txt 等非源码文件名，保存字节与来源摘要；普通根分析不得新增错误。
+  hooks:
+    - id: lark-requirements
+      stage: collect
+      capability: requirements
+      use: lark-doc-fetch@mobile-marketplace
+    - id: yapi-interfaces
+      stage: collect
+      capability: interfaces
+      use: yapi-discovery@mobile-marketplace
+    - id: figma-design
+      stage: collect
+      capability: design
+      type: skill
+      name: figma-design-capture
+      purpose: >-
+        mobile-marketplace 暂无 figma adapter：定位级采集每页节点 id、形态、变体节点、深浅 section/frame 映射及需求冲突，保留含 fileKey 的 URL；
+        collect 不展开内部；tech 先定向核对影响组件复用及范围的设计事实，完整字号/颜色/间距与切图清单留给 apply。写成 markdown，
+        再以 sources add --source-file design=<path> 登记后重新 collect。
+    - id: parse-ui-conventions
+      stage: parse
+      type: file
+      path: docs/agent/ui-conventions.md
+      purpose: 项目平台组件与范式清单；写「能力与入口清单」时对照可复用组件与状态容器
+    - id: parse-spec-structure
+      stage: parse
+      type: check
+      category: spec
+      description: spec.md 已含「能力与入口清单」「状态与交互」「来源冲突与缺口」三章；每个有设计的界面形态（page / dialog / bottom-sheet / tab 子页）有设计节点依据，不从需求措辞推定；影响页面形态或入口的冲突已 blocked 提问而非自选口径
+    - id: tech-ui-conventions
+      stage: tech
+      type: file
+      path: docs/agent/ui-conventions.md
+      purpose: 写「复用清单」时逐项对照，能复用的写具体路径
+    - id: tech-reuse-inventory
+      stage: tech
+      type: check
+      category: tech
+      description: 复用清单已对照宿主优先项、目标截图/必要 Meta 与组件 API，区分直接复用、扩展后复用、新建；记录参数依据或能力缺口、修改文件及旧调用默认行为，未知不当作可直接复用
+    - id: plan-ui-conventions
+      stage: plan
+      type: file
+      path: docs/agent/ui-conventions.md
+      purpose: 按清单拆 task
+    - id: yapi-plan-coverage
+      stage: plan
+      type: command
+      use: yapi-plan-coverage@mobile-marketplace
+      capability: interfaces
+      required: true
+    - id: plan-crosscutting
+      stage: plan
+      type: notes
+      notes: 国际化文案、主题色、四态与错误提示不得拆成独立 task，必须包含在对应 UI task 内；UI task 的 notes 必须引用 spec 页面清单条目与形态，并包含实际 S 接线、翻译、生成与语言切换；不能以 raw_ 或固定文案作为普通文案豁免。UI task 的精确范围还须列出本页切图目录、pubspec.yaml 的 assets 注册、经适配确认需要扩展的共享 widget 文件（宿主优先项不因设计差异扩展；已有参数足够只改调用方）以及页面所属弹层文件，漏列会在 Gate-A 后触发边界失败。Flutter 的 assets 目录声明不递归子目录：为本页新建的资源子目录必须在 pubspec.yaml 单独登记一行，已声明父目录不覆盖它，因此 pubspec.yaml 几乎总在 UI task 范围内。API 生成任务按插件预演的完整生成物清单列出精确范围，覆盖检查输入见插件 Hook 说明，不用目录放开代替。
+    - id: ui-conventions
+      stage: execute
+      type: file
+      path: docs/agent/ui-conventions.md
+      taskCategories: [ui]
+      purpose: 项目事实清单；scout 抽取相关行进 context.md，缺项按节补读
+    - id: ui-states-complete
+      stage: execute
+      type: check
+      category: ui-states
+      description: 四态有状态测试或可读截图；按钮防重、pending 互斥、竞态、异常重试与关闭后回调必须有真实状态测试，截图不能替代，路径写在 result.notes
+      taskCategories: [ui, logic]
+    - id: theme-color-correct
+      stage: execute
+      type: check
+      category: theme
+      description: 核对深浅截图颜色与设计变量映射 token；无变量用约定具名固定色。普通视觉偏差记 advisory 并披露，主题切换功能失败仍阻断
+      taskCategories: [ui]
+    - id: i18n-inline
+      stage: execute
+      type: command
+      use: intl-locales-check@mobile-marketplace
+      taskCategories: [ui]
+      required: true
+      purpose: 真实 locale 校验；可见文案来源、截图无硬编码及历史语义仍由 intl-workflow 和 verify 文案 Hook 核对
+    - id: design-structure-match
+      stage: execute
+      type: check
+      category: design
+      description: 最终截图按 scout 设计清单逐项对照 Figma 与 Meta：形态、区块顺序与排列、尺寸间距圆角、背景边框、按钮、切图、深浅两套；§0 以宿主为准。passed 表示完成核对；普通视觉偏差记 advisory 并披露，字体或图片不可读不得通过
+      taskCategories: [ui]
+    - id: typography-match
+      stage: execute
+      type: check
+      category: design
+      description: 截图/样式核对：字号按设计，字重在宿主 §11 声明映射时按映射验收，字体族以 ui-conventions §0 的宿主约定为准；共享组件旧默认样式未改。普通视觉偏差记 advisory 并披露后可继续
+      taskCategories: [ui]
+    - id: flutter-analyze-changed
+      stage: verify
+      type: command
+      command: fvm flutter analyze --no-fatal-infos --no-fatal-warnings {files}
+      target: inScopeChangedFiles
+      include:
+        - "**/*.dart"
+      allowEmpty: true
+      required: true
+      purpose: 仅对变更 Dart 文件做静态检查
+    - id: flutter-review
+      stage: verify
+      type: skill
+      name: project-review
+      required: true
+      purpose: 按当前 change 契约与项目约定审查范围内改动
+    - id: visible-copy-and-locale
+      stage: verify
+      type: check
+      category: copy
+      description: 核对可见文案、占位符、locale 资源与项目业务术语一致性
+      required: true
+    - id: pending-work
+      stage: verify
+      type: check
+      category: todo
+      description: 引用 openspec todo 分类输出；非阻塞待办
+      required: false
+    - id: yapi-guidance-parse
+      stage: parse
+      type: skill
+      use: yapi-source-guidance@mobile-marketplace
+      capability: interfaces
+      required: true
+    - id: yapi-guidance-tech
+      stage: tech
+      type: skill
+      use: yapi-source-guidance@mobile-marketplace
+      capability: interfaces
+      required: true
+    - id: yapi-preview
+      stage: tech
+      type: command
+      use: yapi-discovery@mobile-marketplace
+      operation: preview
+      capability: interfaces
+      required: true
+    - id: yapi-generation
+      stage: execute
+      type: skill
+      use: yapi-codegen@mobile-marketplace
+      taskCategories: [api-codegen]
+      required: true
+    - id: intl-workflow
+      stage: execute
+      type: skill
+      use: intl-workflow@mobile-marketplace
+      taskCategories: [ui]
+      required: true
+  verify:
+    reviewScope:
+      includeDirs:
+        - lib
+        - test
+      excludeDirs:
+        - lib/generated
+notes:
+  - 假定 fvm 管理 Flutter。marketplace ref 是本 preset 发布时验证过的基线；宿主可在兼容范围内独立升级插件，实际使用的版本以宿主 openspec/config.yaml 与 marketplace-lock.json 为准（步骤见 docs/guides/plugin-migration.md）。
+  - init 会把 UI 约定清单模板生成到 docs/agent/ui-conventions.md（只创建不覆盖）；填写后删除首行 openspec:fill-me 标记，否则 parse/tech/plan/ui Worker 会以 blocked 停下。改路径时需同时修改四个 *-ui-conventions hook 与 scaffold.path。
+  - 约定文件只写项目事实（组件、路径、token、字体、资源、命令、受保护文件）；流程规则由 skill 节点承担，不在此重复。
+  - 不对整文件 grep 文案或颜色；宿主有真实行为/文案检查入口时配置 execute command Hook。check 描述是 verify 子代理逐条对照截图的闭合条件，Worker 回执只表示「已按此实现」。
+warnings:
+  - 本 preset 引用的插件入口最低需要 yapi-dart-coding 0.2.1（yapi-plan-coverage）与 intl-utils 0.2.3（任务快照翻译），已写入 plugins[].minVersion，安装与 doctor 会检查。当前基线 ref 中两者分别为 0.2.0、0.2.1，发布前须更新为包含新版本的已发布提交。各插件所需的工具版本与能力由插件 Skill 声明并在运行前核对。
+  - 既有宿主按 Hook ID 精确迁移，不能直接覆盖配置。preset apply 与 init --preset 保留宿主已声明的 marketplace ref；升级插件用 openspec marketplace upgrade。
+  - init --yes 才会安装 marketplace 插件；lark-cli、Dart/FVM 与认证仍是运行时前置条件。

package/presets/web-product.yaml

@@ -0,0 +1,23 @@
+schemaVersion: openspec.team-preset.v1
+version: 2.0.0
+id: web-product
+title: Web Product
+description: Web 产品团队的 spec-product 默认配置
+configPatch:
+  schema: spec-product
+  hooks:
+    - id: ui-task-notes
+      stage: execute
+      type: notes
+      taskCategories: [ui]
+      notes: 复用现有设计系统与可达性约定。
+    - id: unit-test
+      stage: verify
+      type: command
+      command: pnpm test
+      required: true
+    - id: build
+      stage: verify
+      type: command
+      command: pnpm build
+      required: true

package/skills/opsx-apply/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: opsx-apply
+description: 批准 Gate-A 后逐个执行 code worker，停在 Gate-B。
+---
+
+# opsx-apply
+
+把用户参数当作 change 名称（可空）。每次循环都以 CLI 状态为准，不要凭记忆继续。
+
+## 项目 CLI 预检
+
+从当前目录向上找到含 `openspec/config.yaml` 的项目根。确认 `openspec --version` 与 `openspec/install-cli.mjs` 中 `@openspec-installer` 的 `packageVersion` 一致。不一致则停止，请用户执行 `node openspec/install-cli.mjs`。不要自动安装全局 CLI。
+
+## 循环
+
+1. `openspec instructions opsx-apply --change "<name>" --json`
+2. 按 `next.action` 查路由表，读取 `nodeFile` 后执行
+3. 优先复用变更命令返回的 `next` / `nodeFile`；无此字段或外部状态变化时才重新取 instructions
+
+## 路由表
+
+| next.action | 读取 |
+|---|---|
+| await_gate + gate-A | nodes/gate-a.md |
+| create_worker / retry_worker 且 step 以 code- 开头 | nodes/code-task.md |
+| await_gate + gate-B | nodes/stop.md |
+| need_user_input / 其他 | nodes/blocked.md |
+
+`code-task.md` 是控制会话的编排节点，它按阶段派发 `nodes/task-scout.md`、`task-build.md`、`task-verify.md`、`task-repair.md` 给子代理；控制会话本身不读源码、设计稿或截图。
+
+## 退出条件
+
+到达 Gate-B、blocked、需要用户输入、或某 task 返修达到上限时停止。不要批准 Gate-B，不要 commit，不要 archive。
+
+summary 中的 `packetPath` 指向完整 packet；控制会话只把路径交给子代理，不读取、不回显全文。

package/skills/opsx-apply/nodes/blocked.md

@@ -0,0 +1,7 @@
+# 受阻
+
+展示 `status` 中的 `lastIssue`、`next` 与任何 questions。需要用户输入或授权时等待。不要猜测下一阶段。
+
+用户答复 questions 后执行 `openspec worker answer --change "<name>" --answer "<答复>" [--answer ...] --view summary --json`，答复写入原 packet 的 `decisions`；再回到循环头，`worker create` 同一 step 复用该 packet，Worker 按 `decisions` 继续。
+
+答复改变产品行为、技术选择或任务要求时，同步相关 spec、tech 或 plan，后续任务引用这些依据；不重复抄写项目通用约定。

package/skills/opsx-apply/nodes/code-task.md

@@ -0,0 +1,29 @@
+# Code task（控制会话）
+
+一次只推进一个 task。控制会话只做编排：调 CLI、派发子代理、读 result / issues JSON、按响应路由。**不读源码、设计稿、截图、svg，不做视觉判断，不改代码。** 宿主没有 subagent 时，主 agent 按各阶段节点文件依次亲自执行，契约不变。
+
+派发 prompt 只传节点文件路径与本节列出的少量路径，不复述规则；子代理返回 ≤200 字摘要，不回显 result / issues 全文。
+
+## 流程
+
+1. `openspec worker create --change "<name>" --step code-<taskId> --view summary --json`，记下 `packetPath`、`resultPath`、`category`、`reviewRounds`、`repairRounds`。
+2. 使用响应 `taskContextPath` 作为 scout 输出路径（按 task id，不是 workerId）。`taskContext` 为空 → 派发 scout（`nodes/task-scout.md` + packetPath + 明确的 taskContextPath）。完成后确认该文件存在，再 create 同 step 使 `refs.taskContext` 可复用；缺失则让原 scout 修正输出路径，不绕过契约传入另一文件名。
+3. 派发 build（`nodes/task-build.md` + packetPath + context.md 路径）。
+4. `category` 为 `ui` → 派发 verify（`nodes/task-verify.md` + packetPath + context.md + resultPath）；它写出 `<taskId>.review-<n>.json`。运行 `openspec worker review --change "<name>" --file <该文件>`；实际代码返修后的审查加 `--repair`，首轮及只刷新证据时省略。读响应 `blocking`、`advisory` 与 `repairRounds`（`open` 仍含全部未修项）：
+   - `blocking` 非空 → 未到两轮实际返修上限时再次 create 同 step 并派发 repair（`nodes/task-repair.md` + packetPath + context.md + 上轮 changedFiles），回到第 4 步；`repairRounds` ≥ 2 → 停止并汇报，不能把行为、构建或证据不可用改成普通视觉偏差。
+   - 只有 `advisory` → 可尝试返修，但不强制。根据问题是否明确可修及成本选择；不返修或达到两轮后，保持 open，在 result.notes 和最终汇报列出偏差、原因与截图路径，然后进入第 5 步。不得为了通过把未修问题写成 resolved。
+   - 无 open → 第 5 步。
+5. `openspec worker accept --change "<name>" --result <resultPath> --view summary --json`。失败按 `details.failures` 一次处理全部：
+   - 只有 `worker_check_stale` 且无代码改动 → 本会话按 id 重跑 `openspec worker check --change "<name>" --id <id> [--input <既有输入文件>]`；插件检查沿用已成功调用的输入路径，不省略动态参数，再 accept。
+   - `worker_review_stale`（返修重跑测试后旧证据摘要变化）→ 派发 verify 复核全部 resolved 与 advisory 项，`worker review` 后再 accept；不加 `--repair`，不算返修轮次。
+   - `unknown_execute_hook_result` → 让 result 只保留 packet hooks 的 id 后再 accept，不改 status 与其他字段。
+   - `required_execute_hooks_incomplete` / `worker_check_failed` → `ui` task 未达到两轮实际返修上限时派发 repair（附 failures 原文），回到第 4 步；非 `ui` task 只派发一次 repair，仍失败则停止，向用户列出 failures 与日志路径。达到上限则停止。
+6. accept 成功后以响应 `next` / `nodeFile` 回到 SKILL.md 循环。
+
+## 边界
+
+- 不同时创建多个 code worker；不手改 `.opsx/state.json` 或 `.opsx/execution`。
+- review 文件只登记 verify 对本 task 范围的判定；用户或独立审查提出的其他 task 缺陷、verify 摘要里的「跨任务」条目，汇报用户后等待其决定归属，不并入当前 task 的 review。
+- 控制会话保存的审查材料、截图只能放在 `openspec/changes/<name>/.opsx/controller-review/`；放在 change 目录之外会被计入业务变更集。
+- 子代理 `blocked` → 展示 questions 等用户；答复后 `openspec worker answer --change "<name>" --answer "<答复>" [--answer ...] --view summary --json`，再 create 同 step 复用 packet 并重派原阶段。
+- 子代理异常退出（超时、无 result）→ 视为该阶段未完成，重派同一阶段一次；沿用 packet、taskContextPath 与已有 check 日志路径，让该阶段核对当前差异后续做未完成部分，不重跑 scout；再失败则停止汇报，不猜测结果。build 内失败/重跑与正式 repair 分别报告，不能用 repairRounds=0 表示首尝试成功。

package/skills/opsx-apply/nodes/gate-a.md

@@ -0,0 +1,9 @@
+# Gate-A
+
+`/opsx-apply` 视为批准意图。执行：
+
+```bash
+openspec gate approve gate-A --change "<name>" --comment "approved via /opsx-apply" --json
+```
+
+立即重读 `status`。不要在本节点写应用代码。

package/skills/opsx-apply/nodes/stop.md

@@ -0,0 +1,5 @@
+# 停止
+
+已到达 Gate-B。汇报已完成 task 进度与下一步（通常是 `/opsx-verify`）。不要批准 Gate-B。
+
+先执行 `openspec todo --change "<name>" --json`，按 design / product / 其他分类向用户汇报文件:行:文案。Worker 历史「未能满足/占位」声明单列，说明是否已解决；同时说明未扫描文件。待办本身不阻塞引擎，不代表可绕过 spec 或 required Hook。用户决定剩余事项的处置。

package/skills/opsx-apply/nodes/task-build.md

@@ -0,0 +1,50 @@
+# Task build（实现）
+
+只做本 task。先完整读 packet 与 context.md（`packet.refs.taskContext` 或 prompt 给出的路径），再按其中具名路径 Read 源码；不做目录级检索，摘要缺项才 Grep。遵守 `task.notes`、`initContext.rules`。
+
+context.md 是定位索引，不替代原始要求。按需读取 spec / tech、file Hook 和设计原文，核对关键约束；不加载 Hook 未列出的 skill。required file / skill 不可用或含 `openspec:fill-me` → status `blocked`，写 questions。
+
+## UI 编码前必做
+
+UI/UX 页面实现必须同时结合设计页面截图、Meta 元数据及样式、变量信息，按设计稿 1:1 还原；实现前主动下载并验证所需切图，并在实际页面中使用。不得只凭文字摘要实现页面。
+
+- 编码前实际读入目标截图的图像内容和对应元数据文件；只取得 URL、路径或工具提示不算已看图。按 context.md 第 4 节设计清单逐项核对形态、布局、间距、字号字重、颜色、资源、动态字段与交互入口。在 result.notes 逐项列出已读取的证据路径与已使用资源路径。
+- 几何与间距取设计清单中的 Meta 数值，不目测估算；清单缺某区块数值时补读元数据，不猜。
+- 切图直接使用设计源导出的文件，不做二次图像处理（去底、裁切、重着色），也不再叠加导出件已包含的透明度、渐变或阴影；带装饰的品牌 / 图标组按整组切图使用，不用文字或近似图形代替。
+- 节点仍是候选、截图不对应或关键资源无法取得时，补充定位和下载；无法补齐则 blocked，不以占位图或猜测布局通过。
+- 宿主约定声明「以宿主为准」的项（如字体族、导航栏组件）按约定实现，不为贴合设计稿下载字体、改组件默认或复刻设计尺寸；在 result.notes 写明约定出处。
+- 其余共享组件不符合本页设计时，通过本次调用的显式样式参数覆盖，保留其他调用的默认值。例如设计字号 14，不能因组件默认 18 而忽略；第 2 节已标出的差异必须逐个处理。
+
+
+## 实现
+
+- `refScope` 是定位入口不是白名单；跨文件改动如实写进 changedFiles，不提前实现后续 task。changedFiles 按真实 Git 差异申报，不列被忽略且未跟踪的工具缓存；已跟踪文件即使匹配 ignore 仍需申报。不要删除缓存来修正申报。
+- 优先复用 context.md 列出的组件与入口；确认不能复用才新建，并在 notes 说明理由。
+- 横切要求（状态、主题、文案、字号）在本 task 内完成，不留 TODO、常量占位或后续豁免。
+- 不修改 context.md 第 5 节列出的受保护文件与固定断言。
+- 实现者对照原稿与实际页面自检，独立 verify 负责验收。截图必须加载真实字体和图片，覆盖对应数据状态与深浅主题。
+- 适用的 logic/UI 异步操作必须用真实状态测试验证防重复提交、异常可重试、竞态与关闭后回调；截图不能证明这些行为。
+
+## 检查
+
+实现与测试代码完成后集中执行，失败沿同 id 修复重跑；不要先直接运行同一命令再为登记重复执行：
+
+- command Hook：`openspec worker check --change "<name>" --id <hookId>`（省略 `--command`）
+- 其他检查：`openspec worker check --change "<name>" --id <稳定id> --command "<命令>"`
+
+回执只含退出码、短摘要、日志路径；需要细节时读日志文件的相关行。只验证本 task 及必要依赖，不清理宿主历史 lint。
+
+## result（必写；completed / failed / blocked 都写）
+
+写到 `packet.expectedResult`，严格 JSON，未知字段拒收：
+
+```json
+{"workerId":"<packet.workerId>","stepId":"<packet.stepId>",
+ "status":"completed | failed | blocked",
+ "changedFiles":["lib/..."],
+ "notes":"实现要点；截图等证据文件路径；未满足项",
+ "questions":[],
+ "executeHookResults":[{"id":"<hook id>","status":"passed | failed | skipped","notes":"..."}]}
+```
+
+`executeHookResults` 只列 `packet.initContext.hooks` 里的 id（多列会被拒收）；自己额外登记的 check（如整页截图）只在 notes 写 id 与证据路径。completed 时 required 必须 passed，未执行或已知不满足不得 passed。check 类回执含义是「已按此实现」，是否达标由 verify 与引擎回执判定。返回控制会话 ≤200 字：status、changedFiles 数、证据路径。

package/skills/opsx-apply/nodes/task-repair.md

@@ -0,0 +1,20 @@
+# Task repair（返修）
+
+先读 packet、`packet.refs.executionEvidence` 索引（open / resolved 问题）、context.md、控制会话给出的上轮 `changedFiles` 或 accept failures。实际读入问题涉及的原始设计截图、Meta 元数据、实际页面截图及必要 spec / tech / 源码；不加载 Hook 未列出的 skill；不从头重做 task，不重写无关区域。
+
+## 修复
+
+- 按控制会话选定的 open 问题（阻断项及本轮选择尝试的普通视觉偏差）的「期望」改代码；「疑似位置」只是提示，以实际代码为准。
+- 保留 resolved 项已确认的行为；必须触碰时补跑对应 check。
+- 不修改 context.md 第 5 节的受保护文件与固定断言。
+- 不得删除、弱化或改写既有测试断言与可见状态检查来让检查通过；测试装配（挂载、卸载、夹具）失败先修装配。同一 check 连续两次修复后仍失败 → status `failed`，在 notes 写明失败原因与已尝试的修改，不再改测试期望。
+- 对照原稿和当前页面的真实差异修复，按 context.md 第 4 节设计清单核对完整页面要求；几何取 Meta 数值。切图直接使用设计源导出文件，不做二次图像处理，也不叠加导出件已含效果；需要不同变体时重新从设计源导出。独立 verify 决定问题是否关闭。
+- 缺关键依据、问题相互矛盾或需要改变已确认决定 → status `blocked` 并写 questions，不猜。
+
+## 检查与 result
+
+修完集中重跑受影响的检查（同 id）：`openspec worker check --change "<name>" --id <id> [--command "<命令>"]`；含截图 / 主题测试，以产出新的证据文件。
+
+写 `packet.expectedResult`（格式同 `task-build.md`，completed / failed / blocked 都必写）。`notes` 对每个处理的问题一行：`<id>: 改了 <文件 / 位置>；满足期望的依据；证据 <路径>`。未处理的 open 问题写明原因。
+
+返回控制会话 ≤200 字：status、处理的问题 id、证据路径。

package/skills/opsx-apply/nodes/task-scout.md

@@ -0,0 +1,28 @@
+# Task scout（设计与代码定位）
+
+目标：为本 task 生成简短索引和可直接读取的完整证据。摘要建议约 4KB，不是硬限制，不为字节数反复改写。**可以保存设计截图、元数据和资源索引；不得修改业务代码。** 证据文件只能写入 `openspec/changes/<name>/.opsx/workers/<taskId>.*`（如 `<taskId>.design/`）；放在 change 目录之外会被计入业务变更集。
+
+## 输入
+
+packet（`task`、`refs`、`initContext`）及控制会话传入的 taskContextPath。先读 packet，核对输出名为 `packet.task.id`，不能用 workerId 或从 resultPath 替换后缀。同一 change 内已有其他 task 的 context.md 时先读其「复用清单」「约定」两节，复用代码库事实。
+
+## 只读来源
+
+1. `initContext.hooks` 中 file Hook 指向的文件；含 `openspec:fill-me` 时在第 7 节记 blocked 原因。
+2. `refs.spec` / `refs.tech` 中 `task.notes` 引用的章节（按标题定位，只读该节）；`refs.taskPlan` 中本 task 条目。复用前置适配结论及其原始证据，补齐本任务完整实现清单，不重复采集未变化的截图和元数据。
+3. `task.designRefs` 非空：同时读取目标页面截图、Meta 元数据、`get_design_context` 与变量定义；确认页面、弹层、状态和主题的准确节点映射，不能把候选节点列表当成确认。优先引用或直接复制工具/宿主已保存的完整原始响应，不手工誊写整份 XML、JSON 或设计代码；完整证据保存在上述 change 内路径并在摘要中引用。无 MCP 时核对 `refs.design[].artifact` 是否包含同等证据。定位所需切图的下载入口和应用路径。
+4. Grep / Glob 确认复用组件、状态容器、数据入口、测试宿主、夹具的真实路径与关键签名。
+
+## 输出 `openspec/changes/<name>/.opsx/workers/<taskId>.context.md`
+
+固定七节，缺则写「无」：
+
+1. **范围**：task 目标一句话；spec / tech 关键条目原文摘录，各 ≤3 行。
+2. **复用清单**：组件或类 → 路径 → 构造 / 关键方法签名 → 设计值 / 组件默认值 / 是否为宿主约定声明「以宿主为准」的项。以宿主为准的项写明约定出处，按约定实现、不覆盖；其余不一致处核对已有参数能否覆盖，并沿用直接复用 / 扩展后复用 / 新建结论；新发现的必要文件超出计划范围时在第 7 节写 blocked 及依据，不能悄悄扩大范围或降级设计。
+3. **约定**：本 task 用到的以宿主为准项、token 映射行、字体规格行、双主题资源行、状态容器接法（只抄用到的行）。
+4. **设计清单**（build 的实现依据，也是 verify 的核对依据，两端用同一份）：节点 id；文本样式表（元素 / 字号 / 字重 / 颜色变量→token）；布局清单：每个关键区块的 Meta 几何数值（尺寸 / 间距 / 圆角 / 排列方向）、背景与边框、按钮几何；以宿主为准的项在清单中标注「按宿主约定」，不列设计数值作核对目标；切图清单：需整组导出的品牌 / 图标组节点 → 导出文件 → 项目目标路径，并注明导出件已包含的透明度 / 渐变 / 阴影；设计截图路径；资源需要转换格式时本机可用的转换命令（先 `which` 核实）。
+5. **检查**：必过 command Hook id 与命令或插件入口、参数文件和输入说明；截图 / 主题测试产出的文件路径；受保护文件清单（file / command Hook 覆盖的夹具、manifest、固定断言文件）。
+6. **i18n**：适用时记录宿主资源格式与路径、键命名、所选 Hook 的翻译、合入与校验入口；无国际化需求写「不适用」。
+7. **风险与未决**：来源冲突、缺失资源、需 blocked 的问题。
+
+摘要以「路径 + 章节标题或节点」索引完整证据，不丢弃精确布局、样式与资源信息。返回控制会话 ≤200 字：摘要与设计证据路径、第 7 节条目数。