loom-plan-execution

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/loom-plan-execution

Guide-first plan execution skill.

以指南为先导的计划执行 skill。

Mission

使命

This skill does not hide package setup behind its own template. It first points the user to the package and guide surface that matches the current CI/CD-managed skill package version block, then routes execution through the applicable Loom Agent Execution Orchestrator runtime surface.

Once the skill-bound package version or runtime source is chosen, this skill must first prove that the selected Loom Agent Execution Orchestrator runtime for that source is runnable and can execute the bare

dotnet ao.dll --guide

command successfully. The command reads the version-matched English docs shipped beside the executable in the runtime package and returns JSON containing the actual

version

docs_root

, and

guide_path

paths. Guide pages are not embedded in the executable. Before that proof exists, do not proceed to planning, authoring, validation, compile,

prompt-plan

prompt-replan

, run, resume, or any downstream input collection. Once the JSON result and readable

guide_path

exist, treat that guide as a hard governance handoff back onto the corresponding published AO package runtime surface for official execution. Do not let

--guide

become a detour that drifts back to repository builds, hand-assembled runtimes, or other non-governed paths.

When the caller is explicitly debugging this skill inside the current repository and asks to use the current source tree, this skill may build and use the local Loom Agent Execution Orchestrator repo output instead of downloading package assets. That local-source override is for repository debugging only and does not create a second official execution authority.

This skill also enforces Loom Agent Execution Orchestrator-strong governance for official plan execution. In that governance model, Loom Agent Execution Orchestrator is the only official execution authority for this skill, only explicit

dotnet ao.dll run

and

dotnet ao.dll resume

count as official skill runs, and any direct non-Loom Agent Execution Orchestrator path stays outside official skill execution.

Business-outcome-first rule: when the caller request or plan content (for example

testplan.md

) clearly targets business execution outputs, this skill must treat that business outcome as the primary completion target and must not drift into AO meta-execution-only activity.

本 skill 不会将包设置隐藏在自己的模板后面。它首先将用户指向与当前 CI/CD 管理的 skill 包版本块相匹配的包和指南表面，然后通过适用的 Loom Agent Execution Orchestrator 运行时表面路由执行。

一旦选择了绑定到 skill 的包版本或运行时源，本 skill 必须首先证明该源所选的 Loom Agent Execution Orchestrator 运行时可以运行，并且能够成功执行裸命令

dotnet ao.dll --guide

。该命令读取随运行时包中可执行文件一起提供的、版本匹配的英文文档，并返回包含实际

version

、

docs_root

和

guide_path

路径的 JSON。指南页面不嵌入可执行文件中。在该证明存在之前，不要继续进行规划、编写、验证、编译、

prompt-plan

、

prompt-replan

、运行、恢复或任何下游输入收集。一旦 JSON 结果和可读的

guide_path

存在，将该指南视为严格的治理交接，回到相应的已发布 AO 包运行时表面进行官方执行。不要让

--guide

变成一条偏离回仓库构建、手工组装运行时或其他非治理路径的迂回路线。

当调用者明确在当前仓库中调试此 skill，并要求使用当前源代码树时，本 skill 可以构建并使用本地 Loom Agent Execution Orchestrator 仓库输出，而不是下载包资源。该本地源覆盖仅用于仓库调试，不会创建第二个官方执行权威。

本 skill 还为官方计划执行强制实施 Loom Agent Execution Orchestrator 强治理。在该治理模型中，Loom Agent Execution Orchestrator 是本 skill 唯一的官方执行权威，只有明确的

dotnet ao.dll run

和

dotnet ao.dll resume

才算官方 skill 运行，任何直接的、非 Loom Agent Execution Orchestrator 的路径都保持在官方 skill 执行之外。

业务结果优先规则：当调用者请求或计划内容（例如

testplan.md

）明确针对业务执行输出时，本 skill 必须将该业务结果视为主要完成目标，并且不得偏离到仅进行 AO 元执行的活动。

Read This First

首先阅读

Shared terminology authority:
```
../../../docs/en/architecture/workflow-terminology.md
```
(bilingual human-friendly status mapping; read it before any user-facing output).
Runtime binding authority: this skill records only the exact bound runtime version. The platform-aware resolver selects channel, package, RID, executable, cache location, and launch path at runtime; do not hardcode or persist those details in skill-owned state.

共享术语权威：
```
../../../docs/en/architecture/workflow-terminology.md
```
（双语、人性化的状态映射；在任何面向用户的输出之前阅读）。
运行时绑定权威：本 skill 仅记录确切绑定的运行时版本。平台感知解析器在运行时选择渠道、包、RID、可执行文件、缓存位置和启动路径；不要将这些细节硬编码或持久化在 skill 拥有的状态中。

Workflow File Language

工作流文件语言

Workflow definition files are the canonical English information carrier across AO, SO, and Loom-governanced target skills. Keep workflow-owned schema keys, node and transition names/descriptions, workflow phases, expressions, hints, failure guidance, evidence references, and control metadata in English. Keep user/business payload values and localized user-facing output in their source or requested language; localization belongs in the presentation layer and must not change workflow keys or control semantics.

工作流定义文件是跨 AO、SO 和 Loom 治理的目标 skill 的规范英文信息载体。保持工作流拥有的 schema 键、节点和转换名称/描述、工作流阶段、表达式、提示、失败指导、证据引用和控制元数据为英文。将用户/业务负载值和本地化的面向用户输出保持为其源语言或请求的语言；本地化属于表示层，不得更改工作流键或控制语义。

Caller File Preparation Contract

调用者文件准备契约

Before one CLI call, the caller must prepare the complete input set on disk and close every input file. Pass paths only for

--script-file

--input-file

--base-workflow-file

--verify-script

--reference-workflow-file

--patch-content-file

--patch-target

--workflow-file

--objective-file

--context-file

--instance-file

, and

--result-file

Do not pass script source, JSON, patch replacement text, or reference content inline. Do not ask the CLI or a later step to create a missing input or repair an earlier partial file. The CLI preflights all required input files before reading or writing. Destination files such as candidate, verification, and audit outputs may be created by the CLI.

在每一次 CLI 调用之前，调用者必须在磁盘上准备完整的输入集，并关闭每个输入文件。仅传递

--script-file

、

--input-file

、

--base-workflow-file

、

--verify-script

、

--reference-workflow-file

、

--patch-content-file

、

--patch-target

、

--workflow-file

、

--objective-file

、

--context-file

、

--instance-file

和

--result-file

的路径。

不要内联传递脚本源代码、JSON、补丁替换文本或参考内容。不要要求 CLI 或后续步骤创建缺失的输入或修复先前的不完整文件。CLI 在读取或写入之前会对所有必需的输入文件进行预检。候选、验证和审计输出等目标文件可以由 CLI 创建。

Guide Hub Structure

指南中心结构

The authoritative AO guide pages live under

../../../docs/en/guides/

and are packaged recursively into the runtime docs bundle. The extracted package uses

guides/ao-guide.md

as the

--guide

entry, with adjacent

ao-guide-flow.md

ao-guide-reference.md

, and

ao-guide-reference-<chapter>.md

pages. This skill publishes no AO guide files; use

reference/ao-skill-reference.md

for runtime acquisition and the fresh extracted guide for version-specific authority.

Current published AO package runtime version:
```
0.3.288
```
.
This block is refreshed by the publish workflows whenever AO package versions change, so the skill contract stays aligned with the latest published stable package set.

Follow the current skill package version block first, then derive the matching package surface:

Package indexes remain skill-local references. The authoritative AO guide source is
```
../../../docs/en/guides/ao-guide.md
```
; the extracted runtime entry is
```
guides/ao-guide.md
```
. The target-local AO copies are complete package guide pages extracted from the exact bound runtime package; they support local inspection but never replace the fresh published-runtime
```
guide_path
```
.
Do not add or publish any AO guide file under this skill; use the fresh guide returned by
```
dotnet ao.dll --guide
```
.

Workflow designer subagent:

assets/agents/loom-plan-execution-workflow-designer.agent.md

SO governance baseline assets for AO enhancement:

Per-run plan output:
```
<execution-output-root>/plan/skill-plan.md
```
(runtime-owned; not a stable skill asset)
```
assets/so-workflow/so-template.json
```
```
assets/so-workflow/so-package-lock.json
```
```
assets/so-workflow/node-to-file-map.md
```

assets/so-workflow/reference/ao/runtime-contracts.md

assets/so-workflow/reference/ao/runtime-behavior.md

assets/so-workflow/reference/document-copy-manifest.json

权威 AO 指南页面位于

../../../docs/en/guides/

下，并递归打包到运行时文档包中。提取的包使用

guides/ao-guide.md

作为

--guide

入口，旁边有

ao-guide-flow.md

、

ao-guide-reference.md

和

ao-guide-reference-<chapter>.md

页面。本 skill 不发布任何 AO 指南文件；使用

reference/ao-skill-reference.md

获取运行时，并使用新提取的指南作为版本特定的权威。

当前已发布的 AO 包运行时版本：
```
0.3.288
```
。
每当 AO 包版本更改时，此块会由发布工作流刷新，因此 skill 契约与最新的已发布稳定包组保持一致。

首先遵循当前的 skill 包版本块，然后推导匹配的包表面：

包索引仍然是 skill 本地引用。权威 AO 指南源是
```
../../../docs/en/guides/ao-guide.md
```
；提取的运行时入口是
```
guides/ao-guide.md
```
。目标本地的 AO 副本是从确切绑定的运行时包中提取的完整包指南页面；它们支持本地检查，但永远不会取代新鲜的已发布运行时
```
guide_path
```
。
不要在此 skill 下添加或发布任何 AO 指南文件；使用
```
dotnet ao.dll --guide
```
返回的新鲜指南。

工作流设计者子代理：

assets/agents/loom-plan-execution-workflow-designer.agent.md

用于 AO 增强的 SO 治理基线资产：

每次运行的计划输出：
```
<execution-output-root>/plan/skill-plan.md
```
（运行时拥有；不是稳定的 skill 资产）
```
assets/so-workflow/so-template.json
```
```
assets/so-workflow/so-package-lock.json
```
```
assets/so-workflow/node-to-file-map.md
```

assets/so-workflow/reference/ao/runtime-contracts.md

assets/so-workflow/reference/ao/runtime-behavior.md

assets/so-workflow/reference/document-copy-manifest.json

Plain-Language Feedback For Every Language

每种语言的平实反馈

All user-facing progress, blocked, error, and completion updates from this skill must be understandable to a high-school reader with no workflow background, in the language requested by the user. English is not automatically plain language, and the rule applies equally to every supported language.

Use short sentences, familiar words, and direct verbs. Say four things in order: what happened, whether the user's work or data is still safe or what result remains valid, why it happened, and exactly what will happen next.

Do not make the reader translate status values, step kinds, node IDs, gate names, handoff terms, runtime details, or audit jargon. Explain a necessary technical word in ordinary language before showing its exact name. Keep commands, paths, IDs, and payload fields in a separate

Technical details

line only when they help the user act or verify the result. The same rule and the term examples below apply to any target-skill feedback reported through AO; target-skill-facing instructions should carry a compact version of them.

来自本 skill 的所有面向用户的进度、阻塞、错误和完成更新，都必须让没有工作流背景的高中读者能够理解，并使用用户请求的语言。英语不自动等于平实语言，这条规则同样适用于所有支持的语言。

使用短句、熟悉的词汇和直接的动词。按顺序说明四件事：发生了什么，用户的工作或数据是否仍然安全或哪些结果仍然有效，为什么发生，以及接下来将确切发生什么。

不要让读者翻译状态值、步骤种类、节点 ID、门名称、交接术语、运行时细节或审计行话。在显示必要技术词的准确名称之前，先用通俗语言解释它。仅当命令、路径、ID 和负载字段有助于用户操作或验证结果时，才将它们放在单独的

Technical details

行中。同样的规则和下面的术语示例适用于通过 AO 报告的任何目标 skill 反馈；面向目标 skill 的指令应包含这些规则的紧凑版本。

Plain-Language Term Examples

平实语言术语示例

The left column is for machine records. The right column shows the meaning to express to a user. These English sentences are examples, not fixed output: translate the meaning into the user's requested language. English is not a substitute for simple language in another locale.

Internal wording	Say this in the user's language
`Done`	"The requested work is complete."
`WaitResume`	"I need your information or confirmation before I can continue."
`SubagentCall`	"A specialist is checking this part."
`gate`	"A required check has not passed yet."
`transition`	"The next step is to ..."
`seam` or `boundary`	"The work is waiting at a handoff point."
`frontier`	"There are a few possible next actions."
`runtime`	"the program that is running the task"
`render unchanged`	"The earlier diagram is still valid; no new diagram was needed."

左列用于机器记录。右列显示要向用户表达的含义。这些英文句子是示例，不是固定输出：将含义翻译成用户请求的语言。英语不能替代其他语言环境中的简单语言。

内部措辞	用用户的语言这样说
`Done`	“请求的工作已完成。”
`WaitResume`	“在继续之前，我需要你的信息或确认。”
`SubagentCall`	“专家正在检查此部分。”
`gate`	“必需的检查尚未通过。”
`transition`	“下一步是……”
`seam` 或 `boundary`	“工作正在等待交接点。”
`frontier`	“有几个可能的下一步操作。”
`runtime`	“正在运行任务的程序”
`render unchanged`	“之前的图表仍然有效；不需要新图表。”

Example: output folder already has a record

示例：输出文件夹已有记录

Internal note:

step-0008-compiled

already exists; the render is unchanged.

User-facing update: "The task itself is fine. The output folder already has the earlier record, so this run did not overwrite it. The earlier diagram and report are still valid. I will use a new output folder and continue the same saved run."

内部说明：

step-0008-compiled

已存在；渲染未更改。

面向用户的更新：“任务本身没问题。输出文件夹已有先前的记录，因此本次运行没有覆盖它。先前的图表和报告仍然有效。我将使用新的输出文件夹并继续相同的已保存运行。”

Example: the review found unresolved problems

示例：审查发现了未解决的问题

Internal note: the review returned four findings, but the clean-review check was claimed before classification and repair.

User-facing update: "The review found four problems. The process stopped too early because it treated the review as finished instead of checking whether the problems were fixed. I will sort and fix the four problems, then check again."

内部说明：审查返回了四个发现，但在分类和修复之前就声称通过了干净审查检查。

面向用户的更新：“审查发现了四个问题。过程过早停止，因为它将审查视为已完成，而不是检查问题是否已修复。我将分类并修复这四个问题，然后再次检查。”

Example: waiting for a decision

示例：等待决策

Internal note: the task is waiting at a user-input step.

User-facing update: "I need one decision from you before I can continue: [state the decision in one short sentence]."

Do not copy the internal note into the user-facing update. Keep exact commands, paths, IDs, and evidence fields in a separate

Technical details

section when they are needed for action or verification.

内部说明：任务正在等待用户输入步骤。

面向用户的更新：“在继续之前，我需要你做一个决定：[用一句简短的话说明这个决定]。”

不要将内部说明复制到面向用户的更新中。当需要操作或验证时，将确切的命令、路径、ID 和证据字段放在单独的

Technical details

部分。

Input Contract

输入契约

Preferred input: a rich plan with at least 10 non-empty lines
Fallback input: a file path to a detailed plan document
Runtime version authority: the current CI/CD-managed skill package version block; derive
```
released
```
versus
```
beta
```
from that bound version when needed
Guide input: run bare
```
dotnet ao.dll --guide
```
; it is English-only and returns JSON with
```
version
```
,
```
docs_root
```
, and
```
guide_path
```
instead of accepting a language flag
Optional input: runtime source mode (
```
package-channel
```
by default, or explicit
```
repo-src-debug
```
when debugging this skill inside the current repository and intentionally using current source output)
Optional input: explicit audit output root

If the request is too short, redirect the user into plan mode or require a detailed plan file before proceeding.

首选输入：至少 10 个非空行的丰富计划
后备输入：详细计划文档的文件路径
运行时版本权威：当前 CI/CD 管理的 skill 包版本块；需要时从该绑定版本推导
```
released
```
与
```
beta
```
指南输入：运行裸命令
```
dotnet ao.dll --guide
```
；它仅支持英文，并返回包含
```
version
```
、
```
docs_root
```
和
```
guide_path
```
的 JSON，而不是接受语言标志
可选输入：运行时源模式（默认为
```
package-channel
```
，或当在当前仓库中调试此 skill 并有意使用当前源输出时显式指定
```
repo-src-debug
```
）
可选输入：显式审计输出根目录

如果请求太短，将用户重定向到计划模式，或要求提供详细的计划文件后再继续。

Default Assumptions

默认假设

Apply these defaults during Loom Agent Execution Orchestrator-based plan execution:

Loom Agent Execution Orchestrator is the only official execution authority for this skill; only explicit
```
dotnet ao.dll run
```
and
```
dotnet ao.dll resume
```
count as official skill runs.
Business-outcome-first is mandatory when plan content clearly targets business deliverables; runtime/meta-only mode requires explicit user intent.
Official AO runtime uses the exact version supplied by this skill and delegates channel, platform/RID, package identity, executable, cache location, and launch path to the platform-aware resolver. Self-contained is the resolver default;
```
.NET CLI mode
```
(
```
dotnet ao.dll
```
) and repository-source debug mode are opt-in only.
In Windows PowerShell 5.1 package-channel mode, treat
```
.nupkg
```
as ZIP content and do not use
```
Expand-Archive
```
directly on the
```
.nupkg
```
; use ZIP APIs or an equivalent ZIP-based extraction path.
In Windows PowerShell 5.1, add
```
-UseBasicParsing
```
to package-channel HTTP probes that use
```
Invoke-WebRequest
```
or
```
Invoke-RestMethod
```
so runtime acquisition does not stall on legacy browser-engine prompts.
If runtime extraction, startup-contract checks, or guide execution fail, stop immediately and keep
```
runtime_preflight_result
```
and guide-refresh evidence in a failed state. Do not write success proof or treat failed command stderr as a guide; record only the successful JSON result and the readable
```
guide_path
```
returned by the runtime.
In repo-src-debug mode, build and use the current repository Loom Agent Execution Orchestrator output only as an explicit debug override.
Keep checked-in source plans/snapshots immutable and keep mutable runtime state under
```
session_dir
```
or explicit execution-output roots.
Write valid workflow, template, schema, demo, runtime-copy, audit-backup, and compile-feedback JSON outputs as indented multi-line JSON. Keep compact JSON only for JSONL, MCP/CLI wire payloads, and explicit canonical hash projections.
Output targets may be outside the Git worktree or ignored by Git. Return normalized real paths, verify each output exists and is readable, and use a verified workspace-relative mirror for direct editor opening when
```
--workspace-root
```
is available; Git tracking is never a delivery condition.
After every AO CLI call or audit-producing step, including
```
dotnet ao.dll
```
and self-contained
```
ao.exe
```
(or
```
ao
```
) calls, follow Mermaid artifact delivery: read the actual
```
audit_artifacts.mermaid_file
```
and
```
audit_artifacts.html_file
```
, verify existence and readability, and never guess an audit path. If
```
--workspace-root
```
was supplied, use only the hash-verified
```
workspace_relative_mermaid_file
```
and
```
workspace_relative_html_file
```
values for clickable workspace links. If the card tool is available, pass
```
card_input_file
```
directly to it without asking another agent to return the file contents; a card is not proof of artifact delivery. Otherwise show the verified Mermaid link first and the HTML link second. When no fresh render exists, reuse only a previously verified link and state that the render is unchanged. On
```
delivery_failed
```
, report the failure and do not emit a guessed link.

在基于 Loom Agent Execution Orchestrator 的计划执行期间应用以下默认值：

Loom Agent Execution Orchestrator 是本 skill 唯一的官方执行权威；只有明确的
```
dotnet ao.dll run
```
和
```
dotnet ao.dll resume
```
才算官方 skill 运行。
当计划内容明确针对业务交付物时，业务结果优先是强制性的；仅运行时/元模式需要明确的用户意图。
官方 AO 运行时使用本 skill 提供的确切版本，并将渠道、平台/RID、包标识、可执行文件、缓存位置和启动路径委托给平台感知解析器。自包含是解析器的默认值；
```
.NET CLI 模式
```
（
```
dotnet ao.dll
```
）和仓库源调试模式仅为可选加入。
在 Windows PowerShell 5.1 包渠道模式下，将
```
.nupkg
```
视为 ZIP 内容，不要直接在
```
.nupkg
```
上使用
```
Expand-Archive
```
；使用 ZIP API 或等效的基于 ZIP 的提取路径。
在 Windows PowerShell 5.1 中，向使用
```
Invoke-WebRequest
```
或
```
Invoke-RestMethod
```
的包渠道 HTTP 探测添加
```
-UseBasicParsing
```
，以便运行时获取不会在旧版浏览器引擎提示上停滞。
如果运行时提取、启动契约检查或指南执行失败，立即停止，并将
```
runtime_preflight_result
```
和指南刷新证据保持在失败状态。不要写入成功证明，也不要将失败的命令 stderr 视为指南；仅记录运行时返回的成功 JSON 结果和可读的
```
guide_path
```
。
在 repo-src-debug 模式下，仅作为明确的调试覆盖来构建和使用当前仓库的 Loom Agent Execution Orchestrator 输出。
保持已检入的源计划/快照不可变，并将可变的运行时状态保留在
```
session_dir
```
或明确的执行输出根目录下。
将有效的工作流、模板、schema、演示、运行时副本、审计备份和编译反馈 JSON 输出编写为缩进的多行 JSON。仅为 JSONL、MCP/CLI 线上负载和明确的规范哈希投影保留紧凑 JSON。
输出目标可能在 Git 工作树之外或被 Git 忽略。返回规范化的真实路径，验证每个输出存在且可读，并在
```
--workspace-root
```
可用时使用经过验证的工作区相对镜像以便直接打开编辑器；Git 跟踪绝不是交付条件。
在每次 AO CLI 调用或产生审计的步骤之后，包括
```
dotnet ao.dll
```
和自包含的
```
ao.exe
```
（或
```
ao
```
）调用，遵循 Mermaid 工件交付：读取实际的
```
audit_artifacts.mermaid_file
```
和
```
audit_artifacts.html_file
```
，验证存在性和可读性，绝不要猜测审计路径。如果提供了
```
--workspace-root
```
，则仅使用经过哈希验证的
```
workspace_relative_mermaid_file
```
和
```
workspace_relative_html_file
```
值作为可点击的工作区链接。如果卡片工具可用，直接将
```
card_input_file
```
传递给它，而不要要求另一个 agent 返回文件内容；卡片不是工件交付的证明。否则，首先显示已验证的 Mermaid 链接，然后显示 HTML 链接。当没有新的渲染时，仅重用先前验证的链接，并说明渲染未更改。在
```
delivery_failed
```
时，报告失败，不要发出猜测的链接。

Non-Negotiable Official Execution Gate

不可协商的官方执行门

For every full-delivery execution of this skill itself,
```
dotnet ao.dll compile
```
is never an end state. It is only a validation checkpoint;
```
--guide
```
,
```
prompt-plan
```
,
```
prompt-replan
```
, and helper scripts are preparation or recovery surfaces only.
After the guide handoff, create or reuse one fresh external runtime workflow instance copy and record its immutable instance identity, workflow-file path, and persisted runtime-state/session path. Run
```
dotnet ao.dll compile
```
against that exact external copy, then immediately dispatch the public
```
dotnet ao.dll run
```
against the same copy. Every later
```
dotnet ao.dll resume
```
must reference the same persisted instance and state; never switch to a new workflow copy between compile, run, or a block. Do not stop at a preflight explanation, local-source debug output, planning output, compile output, or a blocked-state description when the user has required execution.
If
```
run
```
returns a runtime-owned block, continue with
```
dotnet ao.dll resume
```
against that exact workflow instance and persisted state. If the runtime reports a recoverable failure, preserve its evidence and resume from the previous state on the same persisted instance. Repeat until the AO runtime reaches its terminal completed state; a blocked payload alone is never a terminal outcome. Stop only when the failed instance has no recoverable previous state or the official runtime cannot start, and preserve that failure evidence.
Never claim AO-governed completion from local orchestration, direct scripts, repo-source debug execution, compile success, guide success, prompt planning, prompt replanning, or an unresumed block. The completion report must state the official command chain, final runtime status/frontier, and the event-log and audit evidence paths.
When the official runtime cannot be started, the result is failed preflight, not governed completion. Preserve the failure evidence and do not substitute a local or helper execution path.

Detailed assumptions, startup contracts, output matrices, and anti-drift rules live in the reference docs:

Local skill reference:
```
reference/ao-skill-reference.md
```

Workflow generation or revision for this skill must use the local workflow-designer subagent with context-rich relative links, not a freeform generic agent call:

assets/agents/loom-plan-execution-workflow-designer.agent.md

When using that workflow-designer route, enforce deterministic workflow authoring contracts instead of descriptive-only prose:

each transition must declare executable
```
guardExpression
```
and
```
succeedExpression
```
predicates, explicit evidence outputs, and explicit seam ownership
each gate must declare machine-checkable pass predicates, required evidence references, and route coverage mapping
weave-out hints must preserve resume continuity contract fields and expected payload/evidence shapes
final workflow proposals must include transition, gate, and ownership preflight checklists before JSON output is accepted
fail closed: reject vague transition/gate wording that lacks concrete predicates or evidence paths

That exact

.agent.md

file is the authoritative behavior source for the workflow-designer subagent. Do not require it to be mirrored into

.github/agents/

, a user-profile agent folder, or any other discoverable agent root before use. If the runtime can resolve the exact subagent name directly, invoke that name directly while keeping the declared

.agent.md

file as the contract. If direct name resolution is unavailable, resolve the declared path from the current repository/workspace copy first and the corresponding global installed-skill copy second, then pass the resolved file path plus the full file content into the subagent-driving call. Do not replace this route with a freeform approximate agent role.

对于本 skill 自身的每次完整交付执行，
```
dotnet ao.dll compile
```
绝不是最终状态。它只是一个验证检查点；
```
--guide
```
、
```
prompt-plan
```
、
```
prompt-replan
```
和辅助脚本仅是准备或恢复表面。
在指南交接后，创建或重用一个新的外部运行时工作流实例副本，并记录其不可变的实例标识、工作流文件路径和持久化的运行时状态/会话路径。针对该确切的外部副本运行
```
dotnet ao.dll compile
```
，然后立即针对同一副本调度公开的
```
dotnet ao.dll run
```
。以后的每次
```
dotnet ao.dll resume
```
都必须引用相同的持久化实例和状态；切勿在编译、运行或阻塞之间切换到新的工作流副本。当用户要求执行时，不要停留在预检说明、本地源调试输出、规划输出、编译输出或阻塞状态描述上。
如果
```
run
```
返回运行时拥有的阻塞，继续对该确切的工作流实例和持久化状态执行
```
dotnet ao.dll resume
```
。如果运行时报告可恢复的失败，请保留其证据并从同一持久化实例上的先前状态恢复。重复直到 AO 运行时达到其最终完成状态；单独的阻塞负载绝不是最终结果。仅当失败的实例没有可恢复的先前状态或官方运行时无法启动时停止，并保留该失败证据。
永远不要从本地编排、直接脚本、仓库源调试执行、编译成功、指南成功、提示规划、提示重新规划或未恢复的阻塞中声称 AO 治理的完成。完成报告必须说明官方命令链、最终运行时状态/frontier，以及事件日志和审计证据路径。
当官方运行时无法启动时，结果是预检失败，而不是治理完成。保留失败证据，不要用本地或辅助执行路径替代。

详细的假设、启动契约、输出矩阵和防漂移规则位于参考文档中：

本地 skill 参考：
```
reference/ao-skill-reference.md
```

本 skill 的工作流生成或修订必须使用本地工作流设计者子代理并附带上下文丰富的相对链接，而不是自由形式的通用 agent 调用：

assets/agents/loom-plan-execution-workflow-designer.agent.md

使用该工作流设计者路由时，强制执行确定性的工作流编写契约，而不是仅描述性的散文：

每个转换必须声明可执行的
```
guardExpression
```
和
```
succeedExpression
```
谓词、明确的证据输出和明确的接缝所有权
每个门必须声明可机器检查的通过谓词、所需的证据引用和路由覆盖映射
weave-out 提示必须保留恢复连续性契约字段以及预期的负载/证据形状
最终工作流提案必须在接受 JSON 输出之前包含转换、门和所有权预检清单
失败关闭：拒绝缺乏具体谓词或证据路径的模糊转换/门措辞

确切的

.agent.md

文件是工作流设计者子代理的权威行为来源。在使用之前，不需要将其镜像到

.github/agents/

、用户配置文件 agent 文件夹或任何其他可发现的 agent 根目录。如果运行时可以直接解析确切的子代理名称，则直接调用该名称，同时将声明的

.agent.md

文件作为契约。如果直接名称解析不可用，则先从当前仓库/工作区副本解析声明的路径，再从相应的全局已安装 skill 副本解析，然后将解析的文件路径和完整文件内容传递到驱动子代理的调用中。不要用自由形式的近似 agent 角色替换此路由。

Workflow Designer Reference Pack

工作流设计者参考包

Before dispatching

assets/agents/loom-plan-execution-workflow-designer.agent.md

, the caller must provide a bounded

referencePackManifest

and fresh

schemaDemoInput

from the exact AO runtime. The pack must include the successful guide JSON and returned guide file, same-runtime schema/demo/demo compile audit, current target contract and requirements, current workflow source, applicable

AGENTS.md

, and latest compile feedback when revising. Every entry carries a normalized path, SHA-256, exact runtime version, authority role, read status, and validation result. An older workflow is

previous_runnable_reference

only and requires a version/hash/difference/rejected-item disposition.

The designer must return runtime-owned

<execution-output-root>/workflow-design/reference-manifest.json

static-contract-review.json

, and

semantic-probe-report.json

with schema versions

workflow-designer.reference-manifest.v1

workflow-designer.static-contract-review.v1

, and

workflow-designer.semantic-probe-report.v1

. Keep descriptors with path, SHA-256, schemaVersion, verdict, and exact runtime version. A required semantic probe that is failed or unknown prevents readiness; compile success alone is not semantic evidence.

在派发

assets/agents/loom-plan-execution-workflow-designer.agent.md

之前，调用者必须提供有界的

referencePackManifest

和来自确切 AO 运行时的新鲜

schemaDemoInput

。该包必须包括成功的指南 JSON 和返回的指南文件、同运行时 schema/演示/演示编译审计、当前目标契约和需求、当前工作流源、适用的

AGENTS.md

，以及在修订时最新的编译反馈。每个条目都带有规范化路径、SHA-256、确切的运行时版本、权威角色、读取状态和验证结果。较旧的工作流仅是

previous_runnable_reference

，需要版本/哈希/差异/被拒项目的处置。

设计者必须返回运行时拥有的

<execution-output-root>/workflow-design/reference-manifest.json

、

static-contract-review.json

和

semantic-probe-report.json

，其 schema 版本分别为

workflow-designer.reference-manifest.v1

、

workflow-designer.static-contract-review.v1

和

workflow-designer.semantic-probe-report.v1

。使用路径、SHA-256、schemaVersion、verdict 和确切的运行时版本保留描述符。必需的语义探测如果失败或未知，则阻止就绪；仅编译成功不是语义证据。

Runtime Mode Separation

运行时模式分离

Resolve the runtime mode before any package-cache lookup or network request. The two package paths are independent and must not be combined.

```
self-contained
```
mode is the default package-channel path. It validates and acquires only one exact-RID package for the selected product and platform:
```
Techne.Loom.AgentOrchestrator.Runtime.<rid>
```
for AO or
```
Techne.Loom.SkillOrchestrator.Runtime.<rid>
```
for SO. It launches the validated
```
ao.exe
```
or
```
so.exe
```
directly. It must not download, validate, extract, or assemble the
```
.NET CLI mode
```
.NET runtime bundle.
```
.NET CLI mode
```
is explicit. Only this mode validates and acquires the same exact-version .NET runtime bundle (a NuGet restore set that includes the embedded Roslyn compiler assemblies used by the C# expression evaluator), checks the
```
.dll
```
,
```
.deps.json
```
,
```
.runtimeconfig.json
```
, Roslyn, and dependency closure, then launches through the shared .NET host.
Once a mode is selected, a failure stays in that mode and fails closed. Do not fall back from
```
.NET CLI mode
```
to self-contained or from self-contained to
```
.NET CLI mode
```
after startup or package acquisition begins.
Runtime evidence must identify
```
runtime_mode
```
, exact version, package ids, RID, cache validation, launch descriptor, and failure category. Never report a self-contained RID package as a .NET runtime bundle.

在任何包缓存查找或网络请求之前解析运行时模式。两条包路径是独立的，不得组合。

```
self-contained
```
（自包含）模式是默认的包渠道路径。它仅为所选产品和平台验证和获取一个确切 RID 的包：AO 的
```
Techne.Loom.AgentOrchestrator.Runtime.<rid>
```
或 SO 的
```
Techne.Loom.SkillOrchestrator.Runtime.<rid>
```
。它直接启动经过验证的
```
ao.exe
```
或
```
so.exe
```
。它不得下载、验证、提取或组装
```
.NET CLI 模式
```
的 .NET 运行时包。
```
.NET CLI 模式
```
是明确的。只有此模式验证和获取相同确切版本的 .NET 运行时包（一个 NuGet 还原集，包含 C# 表达式求值器使用的嵌入式 Roslyn 编译器程序集），检查
```
.dll
```
、
```
.deps.json
```
、
```
.runtimeconfig.json
```
、Roslyn 和依赖闭包，然后通过共享的 .NET 主机启动。
一旦选择了模式，失败就留在该模式中并失败关闭。在启动或包获取开始后，不要从
```
.NET CLI 模式
```
回退到自包含模式，或从自包含模式回退到
```
.NET CLI 模式
```
。
运行时证据必须标识
```
runtime_mode
```
、确切版本、包 ID、RID、缓存验证、启动描述符和失败类别。永远不要将自包含的 RID 包报告为 .NET 运行时包。

Runtime Flow

运行时流程

Classify intent first: business execution versus explicit runtime verification. Lock business-first mode when objectives clearly request business deliverables.
Confirm the current skill-bound package version, derive channel from its version shape when needed, and confirm runtime source (
```
package-channel
```
or explicit
```
repo-src-debug
```
).
Prepare runtime:
- ```
repo-src-debug
```
  : build Loom Agent Execution Orchestrator from
```
src/dotnet/Techne.Loom.AgentOrchestrator
```
  .
- ```
package-channel
```
  : restore the full Loom Agent Execution Orchestrator bundle into one unified runtime, use ZIP-based extraction for
```
.nupkg
```
  on Windows PowerShell 5.1, run startup-contract preflight, and use explicit launch mode.
Prove the selected runtime can run the bare
```
--guide
```
command, parse its JSON result, and read the returned
```
guide_path
```
and
```
docs_root
```
before proceeding.
Only after that guide result exists, run planning surfaces (
```
prompt-plan
```
) and capture required prompt blocks.
When creating or revising a workflow, invoke the local workflow-designer subagent and give it the relevant skill files, guide files, plan files, and audit artifacts through relative links.
Materialize one external WorkflowInstance copy outside skill paths, record its immutable instance identity and persisted runtime-state/session path, then run
```
compile
```
against that exact copy.
Run Loom Agent Execution Orchestrator with that same external WorkflowInstance copy; every later
```
resume
```
must reuse its persisted runtime state.
On blocked state, use payload signals plus
```
prompt-replan
```
to update seam nodes, then
```
resume
```
with structured envelope payload.
When the current route is confirmed blocked, persist the current workflow state, blocker report, all attempted remedies and their outcomes, and the relevant event/audit references before asking the AO planner to replan.
Replan from the retained history by selecting an explicit strategy: continue from the current state, roll back to an unconfirmed design node, redesign from the current state, replace the whole plan, or apply a smallest reversible workaround.
Require the planner to return a viable path to the terminal business outcome, including a rollback or workaround path when selected, before resuming execution.
Repeat replan/resume until Loom Agent Execution Orchestrator reaches completed state.
Report completion only when Loom Agent Execution Orchestrator is completed and requested business deliverables are verifiable.

For AO workflow design and AO weave-out planning, prefer existing capable subagents whenever they can already complete the weave-out goal instead of emitting generic agent placeholders.

Operational details for prompt blocks, payload conventions, and blocked-state handling are defined in reference docs.

首先对意图进行分类：业务执行与显式运行时验证。当目标明确请求业务交付物时，锁定业务优先模式。
确认当前绑定到 skill 的包版本，需要时从其版本形态推导渠道，并确认运行时源（
```
package-channel
```
或显式
```
repo-src-debug
```
）。
准备运行时：
- ```
repo-src-debug
```
  ：从
```
src/dotnet/Techne.Loom.AgentOrchestrator
```
  构建 Loom Agent Execution Orchestrator。
- ```
package-channel
```
  ：将完整的 Loom Agent Execution Orchestrator 包还原到一个统一的运行时中，在 Windows PowerShell 5.1 上对
```
.nupkg
```
  使用基于 ZIP 的提取，运行启动契约预检，并使用显式启动模式。
证明所选运行时可以运行裸
```
--guide
```
命令，解析其 JSON 结果，并在继续之前读取返回的
```
guide_path
```
和
```
docs_root
```
。
只有在该指南结果存在之后，才运行规划表面（
```
prompt-plan
```
）并捕获所需的提示块。
在创建或修订工作流时，调用本地工作流设计者子代理，并通过相对链接为其提供相关的 skill 文件、指南文件、计划文件和审计工件。
在 skill 路径之外物化一个外部 WorkflowInstance 副本，记录其不可变的实例标识和持久化的运行时状态/会话路径，然后针对该确切副本运行
```
compile
```
。
使用相同的外部 WorkflowInstance 副本运行 Loom Agent Execution Orchestrator；以后的每次
```
resume
```
都必须重用其持久化的运行时状态。
在阻塞状态时，使用负载信号加上
```
prompt-replan
```
更新接缝节点，然后使用结构化信封负载
```
resume
```
。
当确认当前路由被阻塞时，在要求 AO 规划者重新规划之前，持久化当前工作流状态、阻塞报告、所有尝试过的补救措施及其结果，以及相关的事件/审计引用。
通过选择明确的策略从保留的历史中重新规划：从当前状态继续、回滚到未确认的设计节点、从当前状态重新设计、替换整个计划，或应用最小的可逆变通方案。
要求规划者在恢复执行之前返回一条通向最终业务结果的可行路径，包括所选的回滚或变通路径。
重复重新规划/恢复，直到 Loom Agent Execution Orchestrator 达到完成状态。
仅当 Loom Agent Execution Orchestrator 已完成且请求的业务交付物可验证时，才报告完成。

对于 AO 工作流设计和 AO weave-out 规划，只要现有有能力的子代理已经能够完成 weave-out 目标，就优先使用它们，而不是发出通用 agent 占位符。

提示块、负载约定和阻塞状态处理的运营细节在参考文档中定义。

Required Outputs

必需输出

bound runtime version confirmation with derived released/beta evidence and matching canonical links
runtime source selection and version-derived channel resolution metadata
package-channel runtime facts: version, bundle list, unified runtime directory, preflight result, and launch mode
package-channel runtime acquisition facts when Windows PowerShell 5.1 is involved: ZIP-based
```
.nupkg
```
extraction path, HTTP probe mode, and fail-fast evidence when extraction or guide generation fails
workflow/session/event paths and audit artifact links
```
workflow.compile-feedback.json
```
and the shared
```
workflow.compile-feedback.v1
```
result, including parse/validation status, counts, phase blockers, candidate path/hash, and AO runtime identity/version.
Verified real paths for every output artifact, including workflow, feedback, audit, Mermaid, and HTML files outside the Git worktree or under ignored workspace mirrors.
guide hub, flow, and reference paths, with the fixed
```
guide_path
```
hub kept at or below 200 lines
required think-out-loud fields for runtime and audit updates
After every AO CLI call or audit-producing step, including
```
dotnet ao.dll
```
and self-contained
```
ao.exe
```
(or
```
ao
```
) calls, follow Mermaid artifact delivery: read the actual
```
audit_artifacts.mermaid_file
```
and
```
audit_artifacts.html_file
```
, verify existence and readability, and never guess an audit path. If
```
--workspace-root
```
was supplied, use only the hash-verified
```
workspace_relative_mermaid_file
```
and
```
workspace_relative_html_file
```
values for clickable workspace links. If the card tool is available, pass
```
card_input_file
```
directly to it without asking another agent to return the file contents; a card is not proof of artifact delivery. Otherwise show the verified Mermaid link first and the HTML link second. When no fresh render exists, reuse only a previously verified link and state that the render is unchanged. On
```
delivery_failed
```
, report the failure and do not emit a guessed link.
business deliverable verification summary when business-first mode applies

For the full output matrix and field-level contracts, use reference docs.

绑定的运行时版本确认，包含推导出的 released/beta 证据和匹配的规范链接
运行时源选择和版本推导的渠道解析元数据
包渠道运行时事实：版本、包列表、统一运行时目录、预检结果和启动模式
涉及 Windows PowerShell 5.1 时的包渠道运行时获取事实：基于 ZIP 的
```
.nupkg
```
提取路径、HTTP 探测模式，以及提取或指南生成失败时的快速失败证据
工作流/会话/事件路径和审计工件链接
```
workflow.compile-feedback.json
```
和共享的
```
workflow.compile-feedback.v1
```
结果，包括解析/验证状态、计数、阶段阻塞者、候选路径/哈希，以及 AO 运行时标识/版本。
每个输出工件的已验证真实路径，包括位于 Git 工作树之外或被忽略的工作区镜像下的工作流、反馈、审计、Mermaid 和 HTML 文件。
指南中心、流程和参考路径，且固定的
```
guide_path
```
中心保持在 200 行或以下
运行时和审计更新所需的思维外显字段
在每次 AO CLI 调用或产生审计的步骤之后，包括
```
dotnet ao.dll
```
和自包含的
```
ao.exe
```
（或
```
ao
```
）调用，遵循 Mermaid 工件交付：读取实际的
```
audit_artifacts.mermaid_file
```
和
```
audit_artifacts.html_file
```
，验证存在性和可读性，绝不要猜测审计路径。如果提供了
```
--workspace-root
```
，则仅使用经过哈希验证的
```
workspace_relative_mermaid_file
```
和
```
workspace_relative_html_file
```
值作为可点击的工作区链接。如果卡片工具可用，直接将
```
card_input_file
```
传递给它，而不要要求另一个 agent 返回文件内容；卡片不是工件交付的证明。否则，首先显示已验证的 Mermaid 链接，然后显示 HTML 链接。当没有新的渲染时，仅重用先前验证的链接，并说明渲染未更改。在
```
delivery_failed
```
时，报告失败，不要发出猜测的链接。
当业务优先模式适用时，业务交付物验证摘要

完整的输出矩阵和字段级契约，请使用参考文档。

Prohibited Results

禁止的结果

Reject or mark invalid any execution result that says or implies any of these:

AO is optional for official skill execution
AO and another path are parallel official execution modes for this skill
AO runtime artifacts alone are accepted as final completion when the caller explicitly requested business outputs
business-output requests are silently downgraded to runtime/meta-only execution without explicit user approval
```
compile
```
,
```
--guide
```
, or helper shell steps are normal skill run modes
```
compile
```
,
```
--guide
```
,
```
prompt-plan
```
,
```
prompt-replan
```
, or helper shell steps are normal skill run modes
non-AO output can count as official skill execution history
non-AO tests can count as official skill execution evidence
prose flow or examples are official execution authority by themselves

拒绝或标记任何表明或暗示以下内容的执行结果为无效：

AO 对于官方 skill 执行是可选的
AO 和另一条路径是本 skill 的并行官方执行模式
当调用者明确请求业务输出时，仅 AO 运行时工件被接受为最终完成
业务输出请求在未经用户明确批准的情况下被静默降级为仅运行时/元执行
```
compile
```
、
```
--guide
```
或辅助 shell 步骤是正常的 skill 运行模式
```
compile
```
、
```
--guide
```
、
```
prompt-plan
```
、
```
prompt-replan
```
或辅助 shell 步骤是正常的 skill 运行模式
非 AO 输出可以算作官方 skill 执行历史
非 AO 测试可以算作官方 skill 执行证据
散文式流程或示例本身就是官方执行权威

Completion Criteria

完成标准

Do not treat execution as properly governed until all of these conditions hold:

only explicit
```
dotnet ao.dll run
```
or
```
dotnet ao.dll resume
```
counts as an official skill run

dotnet ao.dll compile

dotnet ao.dll --guide

dotnet ao.dll prompt-plan

, and

dotnet ao.dll prompt-replan

are documented as preparation, validation, or authority-supporting surfaces only

skill-level history only comes from AO workflow state, session state, event logs, or audit artifacts
blocker history must retain the blocked node, blocker reason, attempted actions, outcomes, evidence references, and the selected replan anchor/strategy
the planner must receive that retained history as input and must not silently discard failed attempts or prior route decisions
a replan is invalid unless it declares a path from its selected anchor to the terminal business outcome and preserves a one-step rollback plan for any workaround
skill-level checklist only comes from AO workflow nodes, frontiers, transitions, blocked states, and resume points
skill-level run map only comes from the AO runtime
```
workflow_file
```
,
```
next_frontier
```
, blocked state, and audit artifacts
skill-level evidence only comes from AO-owned runtime state and audit artifacts
non-AO tests do not count as official skill execution evidence
prose flow and helper command examples are explanatory only, not execution authority
when caller objectives explicitly request business outputs, AO completion state alone is insufficient without the corresponding business deliverables

Detailed prohibited/acceptance examples are maintained in reference docs.

在以下所有条件成立之前，不要将执行视为已正确治理：

只有明确的
```
dotnet ao.dll run
```
或
```
dotnet ao.dll resume
```
才算官方 skill 运行

dotnet ao.dll compile

、

dotnet ao.dll --guide

、

dotnet ao.dll prompt-plan

和

dotnet ao.dll prompt-replan

被记录为仅用于准备、验证或权威支持表面

skill 级历史仅来自 AO 工作流状态、会话状态、事件日志或审计工件
阻塞者历史必须保留阻塞节点、阻塞原因、尝试的操作、结果、证据引用和所选的重规划锚点/策略
规划者必须接收该保留历史作为输入，并且不得静默丢弃失败的尝试或先前的路由决策
除非重规划声明了从其选定锚点到最终业务结果的路径，并为任何变通方案保留了一步回滚计划，否则重规划无效
skill 级检查清单仅来自 AO 工作流节点、frontier、转换、阻塞状态和恢复点
skill 级运行地图仅来自 AO 运行时
```
workflow_file
```
、
```
next_frontier
```
、阻塞状态和审计工件
skill 级证据仅来自 AO 拥有的运行时状态和审计工件
非 AO 测试不算官方 skill 执行证据
散文式流程和辅助命令示例仅用于解释，不是执行权威
当调用者目标明确请求业务输出时，仅 AO 完成状态是不够的，必须提供相应的业务交付物

详细的禁止/接受示例在参考文档中维护。