# Author a Workflow V1 bundle

Guide URL: `https://docs.usefulmachinery.com/agent/workflow-authoring.md`

Language reference: `https://docs.usefulmachinery.com/reference/workflow-v1.md`

Raw schema: `https://docs.usefulmachinery.com/schemas/workflow-v1.schema.json`

Use this guide when a customer asks a cooperating coding agent to add or revise a
Workflow V1 bundle in an existing repository. It is an authoring procedure, not
permission to execute the workflow or change source-control state. For one guarded
onboarding scenario, use the [first-workflow guide](first-workflow.md). For the complete
field and semantics summary, use the [Workflow V1 reference](../reference/workflow-v1.md).

## Safety boundaries

- Begin with read-only inspection. Do not activate an untrusted repository environment
  merely to inspect it.
- Find and follow every applicable repository instruction file, source-control
  convention, development-tool owner, and documented command wrapper.
- Preserve existing and partial workflow assets. Never overwrite a collision or
  unrelated customer content without showing the exact change and receiving approval.
- Treat workflow authoring, supporting-file authoring, validation, execution, and
  source-control mutation as separate authority boundaries.
- Do not run a workflow, command step, agent harness, repository check, installer, or
  network operation unless the customer separately authorizes that effect.
- Do not create, switch, commit, describe, squash, abandon, or publish a change, branch,
  worktree, workspace, pull request, or equivalent source-control object unless the
  customer separately authorizes that operation.
- Never inspect or reproduce provider credentials. A valid definition does not prove
  that a harness, model, credential, or execution environment is ready.
- Pass paths and commands through an argument-vector process interface. Do not
  interpolate customer text or paths into shell source.

## 1. Inspect before proposing files

Resolve these facts without changing the repository:

1. the repository root and every applicable instruction file;
2. the active source-control client, working-copy state, and unrelated customer changes;
3. the established workflow source root and the repository's workflow, prompt, schema,
   script, and artifact conventions;
4. all existing or partial assets at the proposed paths;
5. the environment that owns the supported `um` executable; and
6. the exact source root and workflow path that validation would receive.

Do not assume `.um/workflows/` is correct when the repository already uses another
layout. Do not infer the workflow source root from the version-control checkout or the
workflow file's directory: it is an explicit validation boundary.

If a suitable existing workflow already validates, report it and write nothing. If an
asset is partial, invalid, or collides with customer content, preserve it and propose a
bounded repair rather than replacing it automatically.

## 2. Design the bundle

Read the [Workflow V1 reference](../reference/workflow-v1.md), then identify:

- ordinary command and agent steps;
- explicit control ordering and output references that infer data dependencies;
- required named Text, JSON, File, or attachment-collection inputs, including any exact File media-type constraint;
- static system prompts, message files, and JSON output schemas;
- semantic Text, JSON, File, and Git-branch outputs with explicit acquisition sources;
- required versus advisory failure behavior;
- any explicit ordinary-step recovery, including whether immediate recheck, a command
  handler, or a fresh-agent handler is safe for at-least-once effects; and
- any finalizers, their ordinary-phase triggers, and their finalizer-only ordering.

Prefer direct `command.argv` arrays. Put pipelines, redirection, conditionals, and other
complex process logic in a repository-owned script rather than shell text embedded in
YAML. Use only documented Workflow V1 fields; unknown fields are invalid. Recovery is
step-local only, uses 1 through 10 rounds, and gives handlers no DAG inputs, outputs,
failure policy, or nested recovery. A command handler reads the engine-owned bounded
context path from `UM_RECOVERY_CONTEXT` and must write one closed `recheck` or
`gave_up` decision document to the fresh private `UM_RECOVERY_RESULT` path. An
agent handler's profile and compatible installed harness are admission and runner
placement requirements even if recovery never activates. For repeated external effects,
use a stable domain idempotency key supplied by an existing explicit input or admitted
environment; Useful Machinery invocation and round identities are not stable author keys.

For an agent profile, record one exact native harness configuration supplied by the
repository or customer. Do not guess a model, translate effort settings between
harnesses, or add fallback profiles. Definition validation checks configuration syntax,
not model availability or provider access.

## 3. Propose one coherent change

Before writing, present:

- the behavior and graph in plain language;
- every file to create or modify;
- the selected harness, model, and thinking or effort value, when agents are present;
- declared outputs, exports, failure policies, recovery behavior, and finalizer behavior;
  and
- the exact definition-validation command.

State explicitly that the proposal authors and validates files only. Approval for this
proposal is not approval to run the workflow, mutate source-control state, or execute
repository checks. If any path, behavior, profile, command, or supporting file changes,
refresh the proposal before writing.

## 4. Author supporting files and YAML

Immediately before each write, check that the destination still has the approved state.
Create only the approved files.

Author referenced support files together with the workflow:

- `systemPrompt`, recovery-agent `handler.prompt`, and message `file` values must be
  UTF-8 text;
- every JSON output schema must be a self-contained UTF-8 JSON Schema Draft 2020-12
  document with the required root dialect declaration;
- command scripts should follow the repository's interpreter and executable-file
  conventions; and
- source-relative paths must remain inside the explicit workflow source root.

Configure YAML language-server schema selection with a comment, not workflow data:

```yaml
# yaml-language-server: $schema=https://docs.usefulmachinery.com/schemas/workflow-v1.schema.json
schemaVersion: 1
steps:
  check:
    kind: cmd
    command:
      argv: ["./scripts/check"]
```

Do **not** add a root `$schema` property to a workflow document. Workflow V1 has a closed
root vocabulary, so that property makes the workflow invalid. A root `$schema` is
required in each separate JSON output schema file; that is a different document.

## 5. Validate without running

Use the supported CLI from its owning environment and invoke it through an argument
vector equivalent to:

```text
execute([
  "um", "workflow", "validate",
  "--source-root", source_root,
  workflow_path,
  "--json"
])
```

`workflow_path` is the ordinary host path to the YAML file. `source_root` is the explicit
boundary containing that file and every static prompt, message file, attachment, and
result schema.

Accept success only when the process returns one schema-version-1 result whose command
is `um workflow validate` and whose closed `outcome` is `valid`. An `invalid`
outcome is a bounded CLI-owned diagnosis. A process or output failure proves neither
validity nor invalidity.

The [raw JSON Schema](../schemas/workflow-v1.schema.json) checks document structure.
`workflow validate` is authoritative for a complete bundle because it additionally
checks graph semantics, types, references, path containment, policy, and resolved static
files. Validation does not execute a command or agent, inspect credentials, check model
access, or contact Useful Machinery.

If validation reports `invalid`, preserve the files, explain the structured diagnostic,
and propose the smallest correction. Do not silently broaden the change or substitute a
schema-only check.

## 6. Report and stop at the approved boundary

Report the repository-relative workflow path, the `valid` or `invalid` structured
outcome, and a concise summary of its steps, outputs, exports, and finalizers. Mention
that execution readiness remains unproven for any configured harness or command.

Do not run the workflow or mutate source control merely because authoring validation
succeeded. Continue only after a separate request and an exact disclosure of the next
operation's authority, environment, paths, and side effects.