aevatar-workflow-authoring

Authoring an executable aevatar workflow

You turn a user's natural-language request into a valid, test-run, reusable aevatar workflow. A workflow is a YAML document of roles + steps that the engine executes; once validated you persist it as a skill so the user can re-run it and watch it in the observatory.

The core DSL, engine rules, and tool protocol are here. Load the linked REST or worked-example reference only when that surface is relevant. Follow the protocol in order.

Two execution surfaces — know which one you are before step 3. Steps 3 / 5 / 6 below call the server-side agent tools nyxid_services, aevatar_start_workflow, and ornn_publish_skill. Those exist only when you are the model running inside an aevatar session with the nyxid MCP connected. If instead you are an external client holding only a NyxID bearer token — driving the aevatar backend through the NyxID broker (nyxid proxy request aevatar), the same identity the sibling skills (aevatar-team-builder, aevatar-service-publisher, aevatar-scheduler) assume — those three tools are not callable. Read references/client-rest.md for the client dry-run, publication, and invocation path; the core DSL and engine rules below apply to both surfaces.

Protocol (follow in order)

1. Confirm the intent is authoring. The user wants a new runnable workflow. If they want to run something that already exists, stop and search for it instead.
2. Clarify just enough. Pin down: the trigger/input, how that ingress authenticates its source, the ordered steps, the desired output, and which external services (if any) are involved. Ask only what you cannot reasonably infer; do not over-interrogate.
3. Select the exact external capability (only if external calls are needed). Prefer a published operation: call list_external_workflow_capabilities, copy its exact user_service_id + endpoint_id selector, then inspect readiness for interactive or durable. The YAML/proto selector has no operation_id field. Use typed capability.nyxid_request only when no published operation represents a required HTTP request; it needs an exact UserService selected from authoritative /api/v1/keys, a typed method/path/body contract, and bind-time authenticated confirmation/grant. One step carries exactly one of nyxid_operation or nyxid_request, never both. /api/v1/user-services is only a routing projection and is never execution authority.
4. Author the YAML. Apply the DSL below and obey every rule in Engine rules (must obey). Prefer the reliable-core primitives; use advanced primitives only when the task truly needs them.
5. Preview before execution. Use the explicit-request preview or draft-run readiness surface. Confirm unique call sites, read/write classification, approval requirements, exact workflow/revision identity, and every blocker. Preview/readiness proves admission readiness only; it does not prove runtime credential propagation or downstream authorization.
6. Run once when authorized, then observe the same run. Never use another mutation as a status check. For a real acceptance run, require terminal completion, lastSuccess=true, non-empty required step outputs, and non-empty final output. On failure, read run detail and audit, find the first failed step, and diagnose before any rerun. Do not blindly retry a mutation or a failed workflow. If the original definition is blocked by a stale or inaccessible external resource, a separately authorized feature-equivalent probe may substitute an accessible sanitized resource while preserving the relevant step, selector, transform, file, and fan-out shapes. Its success proves only those platform features; the original workflow remains blocked or unproven. Never add sends, approvals, external mutations, or schedules merely to broaden a probe.
7. Persist as a reusable workflow. After structural validation and any required execution proof, call ornn_publish_skill with the final workflow in workflow_yamls (see Persisting). This creates a private skill in the user's account containing the workflow.
8. Report evidence honestly. Separate preview-ready, accepted, completed, business-verified, blocked by policy, and failed. Do not call accepted or an opened SSE stream a successful run.
9. Iterate on request. To change an existing workflow: load it with use_skill, edit the YAML, repeat preview and validation, and publish a new version.