/Workflows

name: Workflows
evals:
  suites: [workflows-authoring]
  manual:
    reason: "the authoring suite runs a model per request and the real workflow validate scoring happens over its persisted run, so it is run on demand rather than in the fast lane"
    falsifier: "bun skills/Workflows/Tools/CheckEvalOutput.ts reports fewer than 9 of 10 cases whose produced definitions pass workflow validate"
metadata:
  short-description: "Create, validate, run, schedule and link Workflows v2 definitions through the workflow CLI. Excludes the job inventory and Cloudflare deploys."
version: 1.1.3
description: Authors and operates Workflows v2 definitions through the `workflow` CLI: scaffold a definition, validate it until clean, graph it, run it locally, put a schedule on it, link workflows with after triggers or workflow steps, and inspect definitions and runs. USE WHEN new workflow, create a workflow, make a workflow, I want a workflow for, workflow for doing this, define a workflow, remind me, set a reminder, follow up on, check back on, scheduled task, recurring job, schedule this, run this every, run it nightly, run workflow, run the workflow, link these workflows, chain workflows, run after, when this finishes run, validate workflow, workflow graph, list workflows, what workflows do I have, did the workflow run, pause workflow. NOT FOR the inventory of everything LifeOS runs, missing or orphaned jobs and acknowledgements (use Workflows.ts in LIFEOS/WORKFLOWS), Cloudflare Worker deploys (Cloudflare), or building a whole skill (CreateSkill).

Workflows

The principal says "I want a new workflow for doing this." This skill turns that into a definition in the definitions home, validated by the `workflow` CLI, and visible on the Workflows page in Pulse.

The CLI is the source of truth: `bun LIFEOS/WORKFLOWS/workflow.ts help --json` lists the commands that exist, their usage strings and exit codes. The format and the system doctrine are in `LIFEOS/DOCUMENTATION/Workflows/WorkflowsSystem.md`. This skill names only commands that `help --json` lists, plus `LIFEOS/WORKFLOWS/engine/schedule-install.ts`, which after a hand edit checks the schedule compiles and the dispatcher is loaded, and is not in that catalog.

Ideal State

• Every definition passes `workflow validate` (exit 0) before it is reported done, and any deploy, send or pay step declares its `side_effects` and sits under a `human` approval upstream.
• A scheduled or reminder request becomes a `<name>.workflow.yaml` definition with its trigger enabled for the dispatcher, never an issue alone, and shows in `workflow list` and Pulse.
• Every report states the validate-vs-run distinction that applies: `validate` checks shape, `run` executes for real and may spend money or park on a human gate.

Intent Routing

| Workflow | Trigger | File | |----------|---------|------| | **Create** | "new workflow", "I want a workflow for", "make a workflow that", "define a workflow" | `Intents/Create.md` | | **Run** | "run workflow", "run it", "run the workflow", "dry run" | `Intents/Run.md` | | **Reminder** | "remind me to", "set a reminder", "follow up on", "check back on", any one-off thing due later | `Intents/Reminder.md` | | **Schedule** | "schedule this", "run this every night", "run it once at", "pause workflow" | `Intents/Schedule.md` | | **Link** | "link these workflows", "run B after A", "chain workflows", "call a workflow from a workflow" | `Intents/Link.md` | | **Inspect** | "list workflows", "did it run", "what does this workflow do", "why did it fail" | `Intents/Inspect.md` |

| File | Read when | |------|-----------| | `Format.md` | authoring reference — load before writing any definition | | `EvalState.md` | the latest authoring-eval scores (auto-generated, machine-owned) |

Quick Reference

• Definitions live in `LIFEOS/USER/WORKFLOWS/` as `<name>.workflow.yaml`; the file stem equals `name:`.
• Core commands: `new`, `list`, `validate`, `graph`, `next`, `run`, `runs`, `schedule`, `pause`, `resume`, `link`, `show`, `step`, `put`, `remove`; `help --json` has the full catalog. Every one takes `--json`. Exit 0 success, 1 invalid or failed, 2 usage.
• Every `command` step declares `side_effects` (`[none]` when it touches nothing). A command line that deploys, sends or pays (any `deploy` subcommand or deploy script, a git push, `gmail.ts send`, Relay `send.ts`, `YouTubeUpload` upload, `dd-cli order` and the ordering skill's maintainer-side submit wrapper) must declare the matching effect, or `validate` refuses it.
• Money, deploy and outbound steps need a `human` approval upstream (a human step with the default output, `{approved, note}`). Outbound to the principal only (`recipient: principal`) is exempt. At run time a decline stops the gated step even without a `when`; add `when: { ref: steps.<human>.output.approved, equals: true }` so a decline skips it and the run ends cleanly.
• Local `run` executes all seven step kinds (`RUNNABLE_KINDS` in `engine/runner.ts`). A `human` step parks the run on disk and texts a 👍/👎 approval; `model` and `agent` steps call the OpenAI lanes and cost money; a `workflow` step runs the child as its own ledger run. Only `runs_on: cloud` is refused locally.
• Scratch runs use `LIFEOS_WORKFLOWS_DIR` and `LIFEOS_WORKFLOWS_LEDGER` so they leave the real home and ledger alone.

Data & Config

Customizations, when present: `<configRoot>/LIFEOS/USER/CUSTOMIZATIONS/SKILLS/Workflows/` (configRoot is `$CLAUDE_CONFIG_DIR` when set, else `~/.claude`).

Setup

Nothing to configure for authoring. The skill needs `bun` and the `LIFEOS/WORKFLOWS/` engine that ships with LifeOS. Definitions go in `LIFEOS/USER/WORKFLOWS/` (create the folder if it is missing; `LIFEOS_WORKFLOWS_DIR` points the CLI at another one). Status check: `bun LIFEOS/WORKFLOWS/workflow.ts help --json` prints the command catalog and exits 0. Local schedules are evaluated by one launchd job, `com.lifeos.workflows-dispatcher`, so scheduled and reminder w