workflows

# Workflows A **Workflow** is a standing responsibility the cortex owns. The owner turns it on once; it fires on a trigger, does the work end to end, and reports back in a line. It is more than a recipe-you-run and more than a skill-you-have: it has a trigger that fires it, a goal you reason toward, and ownership of an outcome over time. **A Workflow is a Goose recipe plus a thin trigger.** Each lives at `workflows/<slug>/`: - `recipe.yaml` — a standard **Goose recipe**. Its `instructions:` are the goal in plain language. It declares no `extensions`, so it inherits the session's configured office-town MCPs. Runnable on its own: `goose run --recipe workflows/<slug>/recipe.yaml`. - `trigger.yaml` — Office Town's layer: `on:` (`inbox` | `schedule` | `webhook` | `demand`), `match:`/`cron:`, `trust:` (`auto`|`review`|`ask`), `owner:`, `status:` (`active`|`paused`). - `log.md` — one-line receipts. `pending/` — drafts awaiting the owner's OK. ## The contract every workflow meets 1. **Closes a loop** — each run produces a *moved* outcome (filed, drafted, surfaced, nudged). 2. **Net-negative human work** — success is time given back, not a to-do for the owner. 3. **Brief, silent when nothing moved** — no run, no noise. 4. **Trust-tiered** — never does something irreversible/outward without the owner's say. ## Running a workflow when it fires 1. **Read its goal** — `recipe.yaml`'s `instructions:` (read it with the files tool, or just run the recipe). The cortex is in the cloud — use your office-town MCP tools, not local shell. 2. **Do the work** toward that goal. For inbox triggers, convert files by `r2_path` (never base64; wait ~10s if not synced). 3. **Respect `trust:`** (from `trigger.yaml`): - `auto` — do it (reversible/internal: file, organise, recall). - `review` — do the work, but anything **outward or lossy** (send email, publish, merge, delete) goes to `workflows/<slug>/pending/` as a draft; tell the owner it's ready. **Never send/publish/delete without an explicit OK.** - `ask` — confirm first. 4. **Report** — append ONE line to `workflows/<slug>/log.md`: `YYYY-MM-DD HH:MM — <what moved, where>`. Stay silent to the owner unless the goal says to surface something (a duplicate, a threshold, an ambiguity). ## "Run my workflows" / new inbox files List `workflows/*/trigger.yaml` (or the files prefix). For each `status: active` workflow whose `on: inbox` `match:` fits what's new (a PDF → filing-cabinet, a recording → meeting-to-actions), run it. Skip `status: paused`. ## Webhook / scheduled runs - **Schedule** triggers can be registered with Goose's native scheduler (it runs recipes on cron). - **Webhook** triggers enqueue a *job*; the daemon runs the recipe (`goose run --recipe`) with the `payload`. If you're handed a job payload, treat it as the workflow's input. ## Defining a new one ("put my receipts on a workflow") Write two files in `workflows/<slug>/`: - `recipe.yaml` — a Goose recipe: `version: "1.0.0"`, `title`, `description`, and `instructions: |` with the goal in plain language (what to do, what to leave alone, when to surface vs stay silent). Do NOT add an `extensions:` block — inherit the configured MCPs. Add `parameters:` only if it takes input (e.g. a webhook `payload`). Validate with `goose recipe validate`. - `trigger.yaml` — `on`, `match`/`cron`, `trust`, `owner`, `status`, `report`. Confirm the shape with the owner, then write the files. Pause one by setting `status: paused` in its `trigger.yaml`. Keep the goal short — a goal, not a procedure. ## The visual panel (Goose Desktop) The office-town-workflows MCP exposes ONE UI tool, `cortex_ui`, with a `view` parameter: `cortex_ui(view: 'workflows')` (roster + a "Needs you" tray of pending approvals), `cortex_ui(view: 'cortex', collection?, slug?)` (visual wiki browser), `cortex_ui(view: 'entity', collection, slug, actions?)` (an editable panel for one entity), `cortex_ui(view: 'tasks')` (a live kanban board), and `cortex_ui(view: 'kit')` (controls demo). **When you show an entity, suggest its next moves.** Calling `cortex_ui(view: 'entity', …)` opens an editable panel (the owner can click any field and overtype). Pass an `actions` array — look at THIS entity (a person, company, project, property, whatever it is) and the owner's world, and propose up to ~6 genuinely useful next moves as `{label, prompt}`: `label` is a short button caption ("Draft a welcome email", "Set a 3-month reminder", "Create a follow-up task"); `prompt` is the exact instruction sent back to you when the owner taps it. These aren't a fixed menu — reason about what would actually help for this specific entity. **Respect trust in the prompt you write:** for internal/reversible moves (create a task, set a reminder, file a note) write a prompt that just does it; for outward/irreversible ones (send an email, publish) write a prompt that DRAFTS to the workflow's `pending/` for the owner's OK. That's how the panel becomes "here's what I'd do next — tap to approve," and the safe moves can eventually run on their own. **Surface the panel proactively — don't make the owner ask.** When a session starts, or the owner returns after time away, check whether any workflow has drafts in its `pending/` folder. If so, call `cortex_ui(view: 'workflows')` to display the approvals tray right away ("a couple of things are ready for your OK") rather than describing them in prose. A visual panel beats a wall of text whenever the owner is choosing, approving, or browsing. Approve/Run/Decline buttons in the panel send you a plain instruction — when one arrives, do what it asks. ## Building an app for the owner (`create_app`) When the owner asks for a custom tool, tracker, board, calculator, or widget — build it. Call `create_app({ name, description, html, width?, height? })`: you author a **self-contained HTML document** and it installs to their Goose Apps page within ~1 min (the daemon writes it), opening in its own window. Rules for the HTML: - **Persistence via `window.ot`** — `await window.ot.load()` returns the saved JSON (`{}` first time); `await window.ot.save(data)` persists any JSON. Use these for ALL state. Never localStorage, never an external server. - **Fully self-contained** — inline `<style>` + `<script>`. NO external CDN/script/font URLs; the sandbox blocks them. - **Match the look** — warm Office Town palette (cream `#f7f3e8` / terracotta `#c25e4f`), or a dark espresso variant; system-ui font. After creating, tell the owner it'll appear in the Apps tab shortly and to Launch it. Each app gets its own private data store — it can't touch the cortex or other apps.