workflow-orchestrator

工作流上下文中队列驱动编排的结构奇偶校验框架。

## Contract

This skill is intentionally skeleton-only. It provides structure parity with canonical queue orchestration without plugin hooks.

Wave 2 execution parity includes:
- Setup derivation phase ordering: `detection -> understanding -> derivation -> proposal -> generation -> validation`
- Required persisted setup artifacts: `ops/derivation.md`, `ops/derivation-manifest.md`, `ops/config.yaml`
- In-skill lifecycle emulation routines (not real hook execution):
  - session orient
  - write-time validation checklist
  - stop/session capture persistence

## Argument Parsing

Parse arguments in this order:
1. positional `target` (optional)
2. `--handoff` (boolean)
3. `--batch <id>` (optional)
4. `--type <phase>` (optional)
5. unknown flags are non-fatal; report and ignore

If no `target` is supplied, list candidate inbox files and request explicit selection.

## Runtime Loader Requirements

Before doing queue work, load runtime context from:
- `ops/derivation-manifest.md` (if present)
- `ops/config.yaml` (if present)
- queue file with fallback precedence:
  1. `ops/queue/queue.yaml`
  2. `ops/queue/queue.yml`
  3. `ops/queue/queue.json`

If no queue file exists, fail safely with actionable remediation.

## Safety Constraints

Never:
- execute arbitrary shell from user-provided strings
- continue processing after parse/load failures
- mutate tasks outside declared queue schema fields
- call external plugins/hooks (explicitly out of scope)

Always:
- validate queue structure before state transitions
- make state transitions explicit (`extract -> create -> reflect -> reweave -> verify -> done`)
- produce deterministic handoff text when `--handoff` is set
- preserve resumability by reading persisted queue state first

## Scope Boundary

No plugin hooks are implemented in this skeleton.
Lifecycle behavior is emulated in-skill to preserve deterministic execution semantics only.

## Installation

To install the workflow-engine and enable its hooks:

```bash
# Clone or navigate to the workflow-engine directory
cd workflow-engine

# Run the install script to set up hooks
./install-hooks.sh

# Or manually enable hooks via openclaw
openclaw hooks enable session-orient
openclaw hooks enable write-validate
openclaw hooks enable session-capture
```

---

## 中文说明

## 契约

本技能有意仅为骨架。它在不依赖插件钩子的情况下，提供与规范队列编排一致的结构。

Wave 2 执行一致性包括：
- 设置推导阶段排序：`detection -> understanding -> derivation -> proposal -> generation -> validation`
- 必需的持久化设置产物：`ops/derivation.md`、`ops/derivation-manifest.md`、`ops/config.yaml`
- 技能内生命周期模拟例程（非真正的钩子执行）：
  - 会话定向
  - 写入时验证检查清单
  - 停止/会话捕获持久化

## 参数解析

按以下顺序解析参数：
1. 位置参数 `target`（可选）
2. `--handoff`（布尔值）
3. `--batch <id>`（可选）
4. `--type <phase>`（可选）
5. 未知标志非致命；报告并忽略

如果未提供 `target`，列出候选收件箱文件并要求明确选择。

## 运行时加载器要求

在进行队列工作之前，从以下来源加载运行时上下文：
- `ops/derivation-manifest.md`（如果存在）
- `ops/config.yaml`（如果存在）
- 队列文件，按以下回退优先级：
  1. `ops/queue/queue.yaml`
  2. `ops/queue/queue.yml`
  3. `ops/queue/queue.json`

如果不存在队列文件，安全失败并提供可操作的修复建议。

## 安全约束

绝不：
- 从用户提供的字符串执行任意 shell
- 在解析/加载失败后继续处理
- 修改已声明队列模式字段之外的任务
- 调用外部插件/钩子（明确超出范围）

始终：
- 在状态转换前验证队列结构
- 使状态转换显式化（`extract -> create -> reflect -> reweave -> verify -> done`）
- 当设置 `--handoff` 时生成确定性的交接文本
- 通过先读取持久化的队列状态来保持可恢复性

## 范围边界

此骨架中未实现任何插件钩子。
生命周期行为在技能内模拟，仅为保持确定性执行语义。

## 安装

要安装 workflow-engine 并启用其钩子：

```bash
# Clone or navigate to the workflow-engine directory
cd workflow-engine

# Run the install script to set up hooks
./install-hooks.sh

# Or manually enable hooks via openclaw
openclaw hooks enable session-orient
openclaw hooks enable write-validate
openclaw hooks enable session-capture
```