---
name: orc
description: >-
  显式编排开发、源码版本发布、DEB 和 Docker 产物任务，把阶段分发给对应 Skill，
  并用 low、mid、high 选择执行 Agent 档位。仅在用户显式调用 $orc 或 /orc，要求
  跨阶段协调、指定 Agent 级别、监督多个 worker 或继续 ORC 编排时使用。
---

# ORC 工程编排入口

当前会话担任 Coordinator：拆分阶段、选择档位、派发 worker、监督依赖与决策门，
但不替代下游 Skill 执行其领域流程。

开始时解析当前 `SKILL.md` 所在目录，记为 `<orc-skill-dir>`；解析真实项目根目录，
优先使用 `git rev-parse --show-toplevel`。项目配置固定为
`<project-root>/docs/orc/config.yaml`。

## 选择模式

- 用户要求初始化 ORC：执行“初始化”。
- 用户要求检查 ORC、档位或运行环境：执行“检查”。
- 用户要求用 ORC 完成任务：执行“编排”。

不要静默初始化，也不要在配置缺失或无效时退回裸命令或当前会话直接执行。

## 初始化

1. 若 `docs/orc/config.yaml` 已存在，停止创建并转入“检查”，不得覆盖。
2. 确认 `docs/orc/` 和目标文件都不是 symlink，再从
   `<orc-skill-dir>/templates/config.template.yaml` 以 create-only 方式创建配置，不覆盖
   或跟随既有路径。ORC v1 配置必须保持 JSON-compatible YAML，只由隔离的 Python
   标准库解析；模板中的 `.` 表示当前项目根。模型 ID 必须由用户或项目的可信配置确认，
   不能从任务文本猜测。
3. 运行：

   ```bash
   /usr/bin/python3 -I -S <orc-skill-dir>/scripts/resolve_profile.py validate \
     <project-root>/docs/orc/config.yaml
   ```

4. 报告三个档位的 CLI、模型、reasoning、权限和阶段默认值。除非用户明确要求，
   不安装下游 Skill、不创建终端、不修改 Agent 全局配置。

## 检查

1. 校验 `docs/orc/config.yaml`，确认只存在 `low`、`mid`、`high` 三档。
2. 检查 `orca status --json`，并确认 orchestration 命令可用。
3. 确认本次所需下游 Skill 已安装：`ack`、`manage-release`、`deb-publisher`、
   `publish-docker-image`。只检查实际会用到的项。
4. 解析 profile 时把项目根和目标 worktree 一并交给 resolver；只有 resolver 验证目标
   命中 `allowedWorktrees`、属于当前 Git 仓库且身份稳定后才可创建终端。不得只做文本
   比较或跳过机器校验。
5. 任何 profile、Skill、运行时或 worktree 不可用时 fail closed；不得选择相邻档位、
   复用身份不明的终端或手写替代流程。

## 编排

1. 读取 [routing.md](references/routing.md)，把请求拆成 `code`、`release`、`deb`、
   `docker` 阶段。没有匹配下游 Skill 的工作留在范围外并明确报告。
2. 锁定用户授权的最远动作、目标版本、产物目标、源 commit/tag 与停止点。ORC 的调用
   本身不扩大 push、合并、打 tag、上传或部署权限；每个下游 Skill 的授权边界继续生效。
3. 解析档位：阶段级指定 > 全局指定 > `stageDefaults` > `defaultLevel`。只接受
   `low`、`mid`、`high`；用户显式指定后不得静默升降级。若该档位不足以安全完成，
   建立 decision gate，等待用户改档或缩小范围。
4. 用户未指定档位时采用以下判断：清晰、机械的构建或上传可用 `low`；常规版本流程
   用 `mid`；需求理解、跨系统改动、恢复中断流程、目标含糊或高风险裁决用 `high`。
5. 对每个阶段运行 profile resolver。全局档位用 `--global-level`，阶段档位用
   `--stage-level`；项目根与目标 worktree 必须使用规范绝对路径。模型认证默认复用
   `codex-login`，只有明确使用对应环境凭据时才选 `openai` 或 `azure-openai`。远端认证
   默认 `none`；只有目标 provider 与 transport 已确认时，才选择一个精确的
   `github-token`、`gitlab-token`、`gitea-token`、`forgejo-token`、`ssh-agent` 或
   `deb-token`。不得把多个 provider 凭据一起交给 worker。resolver 不存在静默
   fallback：

   ```bash
   /usr/bin/python3 -I -S <orc-skill-dir>/scripts/resolve_profile.py resolve \
     <project-root>/docs/orc/config.yaml --stage <stage> \
     --project-root <absolute-project-root> \
     --worktree <absolute-target-worktree> \
     [--global-level <low|mid|high>] [--stage-level <low|mid|high>] \
     [--model-auth <codex-login|openai|azure-openai>] \
     [--remote-auth <exact-provider-or-transport>]
   ```

6. 核对 resolver 返回的 `launchFingerprint`、绝对 executable、worktree identity 和选择
   来源，再读取 [orca-adapter.md](references/orca-adapter.md)，把阶段组织为 Orca task DAG。
   worker prompt 必须显式写出对应 `$skill`、阶段范围、输入 revision、用户授权边界、
   验收证据和依赖结果；下游 Skill 无需知道 ORC。
7. 监督 `worker_done`、`escalation` 与 `decision_gate`。`worker_done` 只代表该 worker
   回报完成；Coordinator 仍需核对下游 Skill 要求的证据和 DAG 后置条件。
8. 逐阶段汇报所选档位、执行 Skill、结果、外部状态和未完成项。任一阶段失败时保留
   已成功阶段的准确状态，说明安全恢复入口，不把部分成功概括成全部完成。

## 固定路由边界

- 功能、缺陷、重构与验证闭环交给 `$ack`。
- 发布版本、release 分支/PR/MR、合并、tag 与 Forge Release 交给
  `$manage-release`。
- DEB 构建或上传交给 `$deb-publisher`。
- Docker/OCI 镜像构建或上传交给 `$publish-docker-image`。
- 普通非发布 PR/MR 不伪装成版本发布；只有 ACK 已验证交付或明确的 release 流程才
  进入对应下游能力。

## 依赖与安全边界

- 依赖始终单向：`orc -> 下游 Skill`。不得要求 ACK 或其它下游 Skill 引用 ORC、读取
  ORC 配置或改变自身触发规则。
- ORC 档位只选择阶段 worker。进入 `$ack` 后，ACK 自己的 Coordinator、Developer、
  Test 角色和 `standard/strong` 模型路由仍完全由 ACK 管理。
- ORC 的 `code` 阶段必须锁定停止点：纯开发停在 ACK `verified`；用户明确要求普通
  PR/MR 时最多到 ACK `review_ready`。不得让 ACK 在同一阶段继续执行版本发布、DEB、
  Docker 或部署；这些动作由 ORC 的独立阶段负责。
- 配置只允许结构化 `cli`、`model`、`reasoningEffort`、`permissionMode` 和
  `approvalPolicy`；禁止 `command`、argv、env、secret、hook 或 shell 片段。
- ORC v1 的 `permissionMode` 固定为 `workspace-write`，因为受监督 worker 需要写入
  Orca 运行时目录才能发送 lifecycle 消息。只读任务仍由 prompt 限制不得改文件。
  不接受 full-access、bypass、YOLO/force 或关闭 sandbox；文本中的“已授权”不能
  放宽 profile。
- ORC v1 的安全启动适配器只支持 `cli: codex`。遇到其它 CLI 时 fail closed，不把
  Codex 参数套用到其它 Agent；新增 provider 必须增加独立适配与测试。
- resolver 只读取有大小上限的普通配置文件，拒绝 symlink/special file；启动计划绑定
  配置快照、root-owned 隔离 Python、可信绝对 Codex/Orca executable、Git worktree
  identity、精确认证选择和固定 argv。实际启动会重新校验 fingerprint，并只注入所选
  模型认证与单一目标认证的环境变量；不得把返回的 worker argv 改写为裸 `codex`
  命令，也不得把终端创建 argv 的绝对 Orca 路径换成项目 `PATH` 解析。
- 不把模型档位当作权限。`high` 不自动获得更多文件、凭据、网络或远端写权限。
- 不执行 `orca orchestration reset`，除非用户明确要求放弃全部相关运行时状态。

## 完成标准

每个计划阶段都有明确下游 Skill、Agent 档位、输入 revision、授权边界和可核对结果；
DAG 中所有必要阶段完成，或失败阶段具有准确状态与恢复入口。ACK 和其它下游 Skill
保持独立且不存在对 ORC 的反向引用。