workflow-setup · diff

git:20260810.8efee9a to git:20260812.68f64b6

30 added, 31 removed. Audit A to A.

---

name: workflow-setup

- description: Create, edit, inspect, run, schedule, pause, or delete Zero workflows and automations.

+ description: Create, edit, inspect, run, schedule, pause, or delete vm0 workflows and automations.

---

- # Zero Workflow Setup

+ # Okou Workflow Setup

- Use this skill to help users create and manage Zero workflows and their

+ Use this skill to help users create and manage vm0 workflows and their

automations. A workflow is the reusable SOP/skill body. An automation is a

trigger attached to a workflow. The CLI represents automations as

- `zero workflow trigger ...`; the user-facing conversation should usually call

+ `okou workflow trigger ...`; the user-facing conversation should usually call

them "automations" or "triggers" in plain language, not CLI objects.

Prefer workflow triggers over legacy automations unless the user explicitly asks

for the old automation system.

- Run Zero CLI commands as:

+ Run Okou CLI commands as:

```bash

- npx -p @vm0/cli zero <command>

+ okou <command>

```

- If `zero` is already installed in the environment, `zero <command>` is also

- fine.

+ The Okou binary is provided by the current agent runtime.

## User Experience Contract

Hide implementation details by default. Do not show raw commands, workflow IDs,

trigger IDs, cron expressions, JSON configs, webhook signing material, or

verification output unless the user asks for technical details, auditability, or

debugging context.

Speak in terms the user understands:

- "workflow" = the reusable instructions or SOP.

- "automation" = when and how that workflow should run automatically.

- "trigger" = the condition that starts the automation.

- "run now" = manually start the workflow once.

- "pause" / "turn back on" = disable / enable the automation while preserving

its settings.

Default to a requirements-first conversation. Ask only for missing information

needed for the next action, and keep questions short. Prefer one question with

2-4 concrete choices over a generic template.

For built-in templates, use a draft-first setup path. If the template already

defines a clear job, save the reusable workflow before asking about connector

setup or automation details. Keep it without an automation until the user

confirms the trigger and any safety-sensitive side effects. If permission to

send, merge, edit, spend, delete, or contact people is unclear, make the draft

prepare or recommend the action and require approval instead of blocking draft

creation.

Good user-facing questions:

- "What should this workflow do each time it runs?"

- "When should it run: on a schedule, every few minutes, when an email arrives,

when a Gmail label is applied, from a webhook, from a GitHub label, or when a

calendar event is created?"

- "Should it only draft changes, or is it allowed to send messages / edit data /

create issues?"

- "Do you want this paused for now, or enabled immediately after I create it?"

Avoid user-facing phrasing like:

- "Give me the cron expression."

- "Which workflow ID should I use?"

- - "Should I call `zero workflow trigger add`?"

+ - "Should I call `okou workflow trigger add`?"

- "Send me the JSON config."

## Product Model

Follow the Automation x Workflow model:

- A workflow is a pure definition: name, description, instructions, optional

supplementary files, and the agent that owns it.

- A workflow does not run automatically by itself.

- An automation is one trigger attached to one workflow.

- A workflow can have zero or more automations.

- Enabled cron, loop, and event automations persist beyond this conversation and

can start future runs until disabled or removed. A `once` automation has one

fire time.

- Editing the instructions means editing the workflow.

- Editing schedule, email matching, labels, webhook, enable/disable, or delete

means managing the automation/trigger.

When a user says "make this automatic", "set this to run every day", "notify me

when...", or "turn this workflow into an automation", create or update a trigger

on a workflow.

When a user says "save these steps", "create a workflow", "make a reusable SOP",

"edit the instructions", or "use this template", create or edit a workflow.

## Fast Path

1. Identify whether the request is about the workflow body, an automation, or

both.

2. If the request mentions an existing workflow by name, list workflows when

needed to resolve the name. If ambiguous, ask the user to choose by friendly

name/description, not by ID.

3. If creating an automation and no suitable workflow exists, offer to create

- one with Zero first, then attach the automation.

+ one with Okou first, then attach the automation.

4. Collect the minimum missing requirements for the next command. A connector,

schedule, destination, or trigger setting is not required to save a workflow

draft when the reusable job is already clear.

- 5. Execute the Zero CLI command(s) in the background. For a template, create and

+ 5. Execute the Okou CLI command(s) in the background. For a template, create and

verify the workflow draft before asking the next activation question.

6. Verify with `workflow view` and/or `workflow trigger list` after create or

update operations.

7. Report the result in plain language, including what will happen next and any

safety limits. After creating a new automation, proactively name the model it

will use. Keep technical IDs out of the normal response.

Do not inspect connector authorization or request permissions as part of the

default setup path. If the command reports connector authorization or permission

failure, stop the blocked action and use the relevant connector doctor or

permission flow requested by the platform instructions.

## Creation Flows

- ### Create Workflow With Zero

+ ### Create Workflow With Okou

Use this when the user wants a new reusable workflow, has no suitable workflow

- for an automation, or chooses "Create with Zero".

+ for an automation, or chooses "Create with Okou".

Collect:

- The workflow's job: what it should do when run.

- Inputs or sources it should use.

- Output or final deliverable.

- Allowed side effects.

- Any approval gates, safety limits, or recipients.

- Whether it should be enabled automatically later, and on what trigger.

Then draft concise workflow instructions and create the workflow:

```bash

- zero workflow create <name> --agent <agent-id> --display-name "<display name>" --description "<description>" --instruction "<workflow instructions>"

+ okou workflow create <name> --agent <agent-id> --display-name "<display name>" --description "<description>" --instruction "<workflow instructions>"

```

Use `--instruction-file <path>` for longer instructions. Use `--dir <path>` only

for supplementary files. Never include a root `SKILL.md` in `--dir`; the workflow

upload synthesizes it from workflow metadata and instruction.

After creation, stay in the conversation. Say that the workflow has been saved

and offer the natural next action, such as setting when it should run.

### Save Conversation As Workflow

Use this when the user wants to preserve steps from a completed conversation.

Summarize the actual steps into reusable instructions, ask the user to confirm or

adjust the name/instructions, then create a workflow under the current agent

unless they specify another agent.

Do not add a trigger unless the user explicitly asks to automate it.

### Create Automation For Existing Workflow

Use this when the user wants a workflow to run automatically.

Collect:

- Which workflow should be automated.

- The trigger type and required trigger settings.

- Whether to enable it immediately.

- Whether the workflow is allowed to send messages, modify systems, spend money,

delete data, or contact customers.

Check existing triggers for that workflow before creating a new one. If a similar

automation already exists, ask whether to keep both, update the existing one, or

disable the old one.

After adding a new automation, read its thread model from the creation result.

If the result does not include the model, inspect the created automation or its

chat thread before responding. Proactively tell the user the friendly model name

the automation will use; include the model ID only when the user asks for

technical details. Automations use their chat thread's current model rather than

storing an independent model, so phrase this as the model the automation will

use and do not imply that the model is pinned to the automation itself.

### Template Or Uploaded Workflow

If the user starts from a built-in template, treat the selected template as

enough approval to save a reusable workflow draft when its job is clear. Infer

the name and description from the template, create it without an automation,

and verify it. Do not inspect connector authorization first.

When trigger details or destinations are missing, ask one short question only

after the draft exists. Do not add or enable an automation until the user has

confirmed its trigger and safety-sensitive side effects. For destructive or

external actions that are not yet confirmed, keep the draft in

recommend/draft-only mode with an approval gate.

For an uploaded file whose job is ambiguous, ask only the next question needed

to understand the reusable workflow body. Do not expose file packaging details

unless import fails.

## Trigger Setup

Before creating or updating an automation trigger, read

[references/trigger-setup.md](references/trigger-setup.md) for trigger-specific

requirements and command shapes.

## Management Flows

### Inspect

Use:

```bash

- zero workflow list

- zero workflow list --agent <agent-id>

- zero workflow view <workflow-id>

- zero workflow trigger list <workflow>

- zero workflow trigger show <trigger-id>

+ okou workflow list

+ okou workflow list --agent <agent-id>

+ okou workflow view <workflow-id>

+ okou workflow trigger list <workflow>

+ okou workflow trigger show <trigger-id>

```

Summarize in product language: what the workflow does, whether it has

automations, when it next runs, whether it is enabled, and what it is allowed to

do.

### Edit Workflow Instructions

When the user asks to change what the workflow does, edit the workflow

instruction:

```bash

- zero workflow edit <workflow-id> --instruction-file ./instruction.md

- zero workflow edit <workflow-id> --display-name "<name>" --description "<text>"

+ okou workflow edit <workflow-id> --instruction-file ./instruction.md

+ okou workflow edit <workflow-id> --display-name "<name>" --description "<text>"

```

Ask for confirmation before making changes that broaden side effects.

### Edit Automation

When the user asks to change when or how it runs, update the trigger. Keep the

conversation inline: ask for the new schedule, interval, label, email matching,

GitHub matching, or replacement behavior, then run the update command.

Do not imply that workflow instructions changed when only the trigger changed.

### Run Now

When the user wants to test or manually run once:

```bash

- zero workflow run <workflow-id>

+ okou workflow run <workflow-id>

```

Tell the user it has started in a new thread. Include the log command only when

they ask for technical details or progress debugging.

### Pause Or Resume

Use disable/enable for an automation. This preserves its settings:

```bash

- zero workflow trigger disable <trigger-id>

- zero workflow trigger enable <trigger-id>

+ okou workflow trigger disable <trigger-id>

+ okou workflow trigger enable <trigger-id>

```

Ask before pausing broad or business-critical automations if the impact is not

obvious.

### Delete

Only delete a workflow or trigger when the user explicitly asks and confirms the

target.

Use trigger removal when deleting one automation:

```bash

- zero workflow trigger remove <trigger-id>

+ okou workflow trigger remove <trigger-id>

```

Use workflow deletion when deleting the workflow itself:

```bash

- zero workflow delete <workflow-id> -y

+ okou workflow delete <workflow-id> -y

```

Explain the effect in plain language: deleting an automation stops that one

automatic run path; deleting a workflow removes the reusable SOP and its attached

triggers.

### Copy Or Fork

Only copy/fork a workflow when the user asks to reuse it on another agent:

```bash

- zero workflow copy <workflow-id> --to-agent <agent-id>

+ okou workflow copy <workflow-id> --to-agent <agent-id>

```

Tell the user the workflow has been copied to the target agent.

### Run History

If the user asks for run history, first inspect the trigger details for last run

and next run. If they need full execution logs, use the available logs/search

tooling with a known run ID or relevant workflow context. Do not claim full

- history is available from `zero workflow trigger` if the CLI only returns summary

+ history is available from `okou workflow trigger` if the CLI only returns summary

fields.

## Safety Rules

- Ask before enabling or testing workflows that send external messages, modify

production systems, spend money, delete data, or contact customers.

- For broad triggers, say the scope plainly, e.g. "This would run for every

incoming email. Should I narrow it down?"

- Treat webhook secrets as sensitive. Preserve the creation output, but do not

expose full secrets in normal responses unless the user explicitly needs the

creation-time secret.

- Disable or remove triggers only when the user explicitly approves that action.

- Do not fork/copy a workflow unless the user explicitly asks to copy, fork,

move, or reuse an existing workflow on another agent.

## Verification

After creating or updating a workflow:

```bash

- zero workflow view <workflow-id>

+ okou workflow view <workflow-id>

```

After creating, updating, enabling, disabling, or removing a trigger:

```bash

- zero workflow trigger list <workflow-id>

- zero workflow trigger show <trigger-id>

+ okou workflow trigger list <workflow-id>

+ okou workflow trigger show <trigger-id>

```

For a newly created automation, verification is incomplete until its thread

model is known. Read it from the creation result or inspect the automation or

chat thread before replying to the user.

Keep verification output internal unless the user needs technical detail.

## Final Response Defaults

Default final response:

- State the outcome in plain language.

- Name the workflow and the automation behavior.

- Mention enabled/paused status.

- For a newly created automation, proactively state the model it will use.

- Mention important safety behavior, such as "draft only, never sends".

- Tell the user the natural next action, such as applying a Gmail label or using

the webhook URL.

Do not include workflow IDs, trigger IDs, raw commands, cron expressions, JSON,

or check lists by default.

Technical final response format, when needed:

- Workflow: name and id.

- Automation/trigger: kind, id, enabled status, and match/schedule summary.

- Checks run: list/view/trigger list/show.

- Blockers: missing user criteria, command failure, or permission denial.