diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..491d0c7 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,41 @@ +# Working in the Workato Labs hub + +This repo is the **Workato Labs hub**: a Jekyll static site (the public front door — `index.html`, +`principles.html`, `README.md`, `assets/`, `downloads/`) **and** the home of **cross-project +decision records** under `docs/adrs/`. + +Two audiences, kept deliberately separate: + +- The **site** is the curated front door. Anything that renders is visitor-facing. +- The **ADRs** are governance docs for contributors and agents. They are **excluded from the Jekyll + build** (`docs` is in `_config.yml`'s `exclude`). Don't move them into the site or link them from + site pages without a deliberate decision — keeping them repo-only is what lets them stay candid + (see LABS-0000 §7). + +## Cross-Project Decision Records (ADRs) + +Architectural decisions that span **two or more** Workato Labs repos live in `docs/adrs/` (index: +`docs/adrs/README.md`). A decision internal to a single repo belongs in *that repo's* `docs/adrs/`, +not here. These are **living records** — written as hypotheses to be checked against the code, not +settled truth. + +- **Verify before relying.** Treat an ADR's claims as a hypothesis to check against the current code + in the affected repos — even one marked `Accepted`. If reality and the ADR disagree, reality wins. +- **The cross-repo amend rule.** If a change in *any* affected repo contradicts a cross-project ADR, + amend that ADR here — in place, as a dated `> **Amendment (Month Year): …**` blockquote that + preserves the original text — and cross-link the two changes. The amendment lands as its own + labs-repo change. (This replaces the linter's single-repo "amend in the same PR" rule.) +- **The ADR owns its dependency map.** Each cross-project ADR lists its `Affected repos` in the + header. That's the authoritative statement of the relationship — keep it complete. We do **not** + rely on every affected repo carrying a back-reference; back-references are per-repo and optional, + and we never force ADR machinery onto a repo that doesn't have it (LABS-0000 §5). +- **IDs carry the `LABS-` prefix** so a reference from another repo is never confused with that + repo's own ADR numbers. New ADR: copy `docs/adrs/TEMPLATE.md` to + `docs/adrs/LABS-NNNN-kebab-case-title.md` and add a row to `docs/adrs/README.md`. +- **Attribution is point-in-time.** `Author(s)` is frozen to who made the *original* decision; if you + join by amending, add yourself to `Amended-by` (with your `role`/`harness`/`model` and the date), + never to `Author(s)`. + +See `docs/adrs/LABS-0000-how-we-use-cross-project-adrs.md` for the full convention. It adopts +`recipe-lint`'s `docs/adrs/0000-how-we-use-adrs.md` by reference and records only the cross-repo +deltas. diff --git a/README.md b/README.md index b4d8a66..1c573ee 100644 --- a/README.md +++ b/README.md @@ -4,13 +4,15 @@ An open-source developer toolkit for building, validating, visualizing, and managing Workato recipes — designed for humans and coding agents alike. -> 🟢 **Beta — Design Partner Program** - --- ## The workflow -Four tools that replace the loop of guess, push, break, repeat. +Four tools that replace the loop of guess, push, break, repeat — one quality loop shared by a human developer and a coding agent. + +

+ The Developer Loop: Recipe Skills feeds context to the AI Agent and lint rules to wk lint. The AI Agent writes a recipe, the Developer inspects it in the Recipe Visualizer, wk lint validates it; on pass it ships via wk push, on fail it routes to Fix and re-lint. +

**Agent writes recipe** (recipe-skills) → **Developer inspects** (visualizer) → **Linter validates** (`wk lint`) → **CLI pushes** (`wk push`) @@ -42,7 +44,7 @@ wk version
Manual install -Download and extract the binary for your platform from [Releases](https://github.com/workato-devs/wk-cli-beta/releases), then: +Download and extract the binary for your platform from [Releases](https://github.com/workato-devs/wk/releases), then: ```bash xattr -d com.apple.quarantine /path/to/wk # macOS: allow the binary to run @@ -75,7 +77,7 @@ wk plugins install recipe-lint
Manual install -Download and extract the archive for your platform from [Releases](https://github.com/workato-devs/wk-lint-beta/releases). The binary inside is named `recipe-lint` (not `wk-lint`). +Download and extract the archive for your platform from [Releases](https://github.com/workato-devs/recipe-lint/releases). The binary inside is named `recipe-lint` (not `wk-lint`). ```bash sudo mv /path/to/extracted-folder /usr/local/lib/recipe-lint # move to a permanent location @@ -101,16 +103,28 @@ git clone https://github.com/workato-devs/recipe-skills.git IDE extension that renders recipe JSON as interactive workflow graphs. Works in VS Code, Cursor, and Windsurf. -Download the `.vsix` from this repo's [`downloads/`](https://github.com/workato-devs/labs/tree/main/downloads) folder, then: +Install from your editor's marketplace — search **Recipe Visualizer** in the Extensions panel ([VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=WorkatoLabs.recipe-visualizer) · [Open VSX](https://open-vsx.org/extension/WorkatoLabs/recipe-visualizer)), or from the command line: ```bash # VS Code -code --install-extension ./recipe-visualizer-0.5.3.vsix +code --install-extension WorkatoLabs.recipe-visualizer + +# Cursor / Windsurf use the same command +cursor --install-extension WorkatoLabs.recipe-visualizer +``` + +
+Manual install (.vsix) + +Download the latest `.vsix` from the [recipe-visualizer releases](https://github.com/workato-devs/recipe-visualizer/releases), then: -# Cursor -cursor --install-extension ./recipe-visualizer-0.5.3.vsix +```bash +# VS Code — replace code with cursor or windsurf as needed +code --install-extension ./recipe-visualizer-1.0.0.vsix ``` +
+ --- ## What's in the box @@ -123,10 +137,10 @@ A unified CLI for Workato platform operations and recipe development. `wk pull`, **Recipe Linter** · Go Deterministic validation via `wk lint`. Catches datapill syntax errors, schema mismatches, and structural issues that agents can't self-validate. -**Recipe Skills** · 7 connectors +**Recipe Skills** · Markdown Agent-consumable knowledge for recipe authoring. Connector config, datapill syntax, control flow, error handling. Also home to connector-specific lint rules. Point your coding agent at the skills directory. -**Recipe Visualizer** · .vsix +**Recipe Visualizer** · VS Code extension IDE extension rendering recipe JSON as interactive workflow graphs. Click a node, navigate to the source. Export graphs as images. VS Code, Cursor, Windsurf. --- @@ -135,10 +149,11 @@ IDE extension rendering recipe JSON as interactive workflow graphs. Click a node | Repo | Description | |------|-------------| -| [workato-labs](https://github.com/workato-devs/labs) | Hub — docs, downloads, .vsix extensions | -| [wk](https://github.com/workato-devs/wk-cli-beta) | CLI — Go binary, workspace ops | -| [recipe-skills](https://github.com/workato-devs/recipe-skills) | Agent knowledge — 7 connector skill sets | -| [wk-lint](https://github.com/workato-devs/wk-lint-beta) | Recipe linter — deterministic validation | +| [workato-labs](https://github.com/workato-devs/labs) | Hub — landing site, docs, install guide | +| [wk](https://github.com/workato-devs/wk) | CLI — Go binary, workspace ops | +| [recipe-skills](https://github.com/workato-devs/recipe-skills) | Agent knowledge — connector skill sets | +| [recipe-lint](https://github.com/workato-devs/recipe-lint) | Recipe linter — deterministic validation | +| [recipe-visualizer](https://github.com/workato-devs/recipe-visualizer) | IDE extension — interactive recipe graphs | --- diff --git a/_config.yml b/_config.yml index 29ff30e..a4f9c77 100644 --- a/_config.yml +++ b/_config.yml @@ -8,3 +8,4 @@ exclude: - Gemfile - Gemfile.lock - vendor + - docs diff --git a/assets/dewy-waving.png b/assets/dewy-waving.png new file mode 100644 index 0000000..cffaf5f Binary files /dev/null and b/assets/dewy-waving.png differ diff --git a/assets/dot-gradient.png b/assets/dot-gradient.png new file mode 100644 index 0000000..b0d8fa7 Binary files /dev/null and b/assets/dot-gradient.png differ diff --git a/assets/favicon.svg b/assets/favicon.svg new file mode 100644 index 0000000..90bd3a4 --- /dev/null +++ b/assets/favicon.svg @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/assets/og-image.png b/assets/og-image.png new file mode 100644 index 0000000..971d003 Binary files /dev/null and b/assets/og-image.png differ diff --git a/docs/adrs/LABS-0000-how-we-use-cross-project-adrs.md b/docs/adrs/LABS-0000-how-we-use-cross-project-adrs.md new file mode 100644 index 0000000..f6eb572 --- /dev/null +++ b/docs/adrs/LABS-0000-how-we-use-cross-project-adrs.md @@ -0,0 +1,136 @@ +# How We Use Cross-Project ADRs + +**Author(s):** Zayne Turner, Claude [role: assistant; harness: Claude Code; model: Opus 4.8] +**Status:** Accepted +**Date:** June 17, 2026 + +**Affected repos:** +- `labs` (this hub) — home of cross-project ADRs. +- Any Workato Labs repo whose architecture is constrained by, or constrains, a decision recorded here (currently `recipe-lint`, `recipe-skills`). + +--- + +## New to ADRs? + +An **Architecture Decision Record** is a short, dated note capturing one significant decision — what +we chose, and *why* — at the moment we made it. If you've never used one, start with the linter's +[`docs/adrs/0000-how-we-use-adrs.md`](https://github.com/workato-devs/recipe-lint) in the +`recipe-lint` repo: it is the parent convention, and this document **adopts it by reference** rather +than restating it. What follows records only the things that are *different* because the decision +spans more than one repository. + +## Context + +Most architectural decisions belong to a single repo and live in that repo's `docs/adrs/`. But some +decisions govern a **relationship between repos** — a contract, a dependency, or a shared capability +one repo provides and another consumes. Those have no good home in either repo alone: put it in the +provider and the consumer can't see it; put it in the consumer and it's invisible to the next +consumer. Recorded in neither, the relationship is reconstructed from code each time someone touches +it — exactly the failure the linter's ADR-0004 documents. + +So **cross-project decisions live here, in the labs hub**, and are referenced from the repos they +affect. The labs hub is already the place that describes the toolkit as a whole; the decisions that +bind its pieces together belong alongside it. + +This document defines how we keep that record trustworthy across repo boundaries. The first such +decision is [LABS-0001](LABS-0001-skills-lint-rules-as-data.md). + +## Decision + +### 1. Scope — what belongs here vs. in a repo + +Record an ADR here when the decision **governs a relationship across two or more labs repos**: a +data/API contract between them, a capability one provides and another depends on, or a shared +constraint that no single repo's ADRs can own. A decision internal to one repo stays in *that repo's* +`docs/adrs/`. When in doubt, ask "if I only read one repo, would I miss why this is the way it is?" — +if yes, it's cross-project. + +### 2. Inherit the linter's `0000` by reference; the deltas are below + +The parent conventions from `recipe-lint`'s `0000-how-we-use-adrs.md` apply **unchanged** here: +ADRs are living hypotheses (verify against code before relying on a claim); corrections are +**in-place, dated amendments**, never history rewrites; the status vocabulary is +`Proposed` / `Accepted` / `Superseded`, with implementation tracked separately via an optional +`Implemented:` line; and the **authorship & attribution schema** (`Author(s)` frozen to original +deciders, `Amended-by` for later contributors, a named human always accountable, agent provenance as +bracketed `role` / `harness` / `model` keys) is identical. The deltas — §3–§6 — exist only because +the record now crosses repo boundaries. + +### 3. IDs and filenames carry a `LABS-` prefix + +Cross-project ADRs are numbered `LABS-NNNN` (zero-padded, incremental; this meta-ADR is `LABS-0000`) +and filed as `LABS-NNNN-kebab-case-title.md`. The prefix is **load-bearing**: a reference from +another repo says "see `LABS-0001`," which can never be confused with that repo's own `0001`. Repo- +local ADRs keep their bare numbers; only cross-project ADRs are prefixed. + +### 4. The ADR owns its own dependency map + +Every cross-project ADR carries an **`Affected repos`** block in its header listing each repo it +governs and that repo's role (provider / consumer / constrained-by). This is the single authoritative +statement of the relationship. **We do not rely on every affected repo maintaining a back-reference** +— see §5 — so the map must be complete and current *here*. When the set of affected repos changes, +that's an amendment. + +### 5. Back-references are per-repo and heterogeneous — never a forced convention + +Labs repos are not uniform, and we do **not** impose ADR machinery on a repo that doesn't have it. +How an affected repo points back to a cross-project ADR is decided **per repo, in whatever form is +already natural there**: + +- A repo **with** ADR infrastructure (e.g. `recipe-lint`) references the `LABS-NNNN` ADR in its own + style — a `References:` line, an index row, or a note on the related local ADR. +- A repo **without** ADR infrastructure (e.g. `recipe-skills`) is **not** required to adopt ADRs to + participate. At most it gets a lightweight link wherever documentation already lives. The decision + is still fully recorded — here — because §4 makes this ADR self-contained. + +Designing identical child-repo updates "for consistency" is a non-goal; the consistency we want is in +*the hub's* record, not in every repo's layout. + +### 6. The cross-repo amend rule (replaces "same PR") + +The linter's hard rule — *code that contradicts an ADR amends it in the same PR* — assumes the code +and the ADR live in one repo. Across repos they don't, so the rule becomes: + +> **A change in any affected repo that contradicts a cross-project ADR must update that ADR (here), +> and cross-link the two changes.** The amendment lands as its own labs-repo change; reference it +> from the originating PR, and reference the originating PR from the amendment. + +The labs ADR is the **source of truth**. If a repo's code and the ADR disagree, reality wins and the +ADR is amended per the inherited in-place-amendment rule (§2). Schema or contract fields that one repo +*reads* from another are the most common trigger: changing them is a cross-repo breaking change and +always warrants an amendment. + +### 7. Repo-only, not published + +These ADRs are governance docs, not site content. They live as Markdown under `docs/adrs/` and are +**excluded from the Jekyll build** (`_config.yml`). Keeping them out of the published site also avoids +entangling them with the hub site's licensing; they are decision records for contributors, not pages. + +### 8. Template and index + +- **Template:** copy [`TEMPLATE.md`](TEMPLATE.md) to `LABS-NNNN-kebab-case-title.md`. +- **Index:** [`README.md`](README.md) lists every cross-project ADR with status, affected repos, and a + one-line summary; update it when adding an ADR. + +## Alternatives considered + +- **Keep the decision in the provider repo's ADRs** (e.g. record the skills relationship inside + `recipe-lint`). Rejected: invisible to other consumers and to the skills repo itself; the provider + becomes a dumping ground for relationships it doesn't own. +- **Duplicate the ADR into each affected repo.** Rejected: guarantees drift, and violates the single- + source-of-truth principle the linter's `0000` is built on. +- **A standalone `decisions/` repo.** Rejected as premature: the hub already exists and already + describes the toolkit as a whole. Revisit if the volume of cross-project ADRs outgrows the hub. + +## Consequences + +- Cross-cutting decisions have one trustworthy home, and an agent or contributor in any affected repo + can find *why* a relationship is the way it is without reverse-engineering two codebases. +- The dependency map (§4) makes each ADR self-contained, which is what lets us honor heterogeneous + repos (§5) instead of forcing uniform structure on them. +- The cost is a small cross-repo dance on amendments (§6) — two linked changes instead of one PR. The + convention is kept deliberately light (a prefix, a header block, an index, one amend rule) so it's + followed rather than routed around. This mirrors the linter's stance: lightweight on purpose. +- Supports the labs core principles — **Open** (a portable record, not buried in one tool), **Agent- + First** (the dependency is legible to agents working in any affected repo), and **Contribute** (a + contributor to one repo can see, and argue with, the decisions that constrain it). diff --git a/docs/adrs/LABS-0001-skills-lint-rules-as-data.md b/docs/adrs/LABS-0001-skills-lint-rules-as-data.md new file mode 100644 index 0000000..686f2f2 --- /dev/null +++ b/docs/adrs/LABS-0001-skills-lint-rules-as-data.md @@ -0,0 +1,126 @@ +# Recipe Skills Declare Lint Rules as Data + +**Author(s):** Zayne Turner, Claude [role: assistant; harness: Claude Code; model: Opus 4.8] +**Status:** Accepted +**Date:** June 17, 2026 +**Implemented:** June 17, 2026 — retroactive record of behavior already shipping (see Consequences) +**References:** ADR 0004 (Rules Are Data, Not Code) in `recipe-lint`; ADR 0001 (Tiered Validation) in `recipe-lint` + +**Affected repos:** +- `recipe-skills` (producer) — authors a `lint-rules.json` per skill: the connector's valid action/trigger catalog, shipped as data. +- `recipe-lint` (provider/consumer) — exposes `--skills-path`, discovers those files, and feeds their data into three rules. + +--- + +## Context + +`recipe-lint`'s [ADR 0004 — *Rules Are Data, Not Code*] set a load-bearing bar inherited from the +linter's original PRD: + +> **Changing the rules a customer runs must not require cutting a new Go binary.** + +ADR-0004 names three load paths for rule data: embedded `builtin_rules.json`, project +`.wklint/rules/*.json`, and **skills `lint-rules.json` via `--skills-path`**. This ADR records the +third one — and the repo on the other side of it. + +`recipe-skills` packages connector knowledge for AI coding agents. A skill teaches an agent *how* and +*when* to use a connector's actions; but an agent left to its own devices will **hallucinate action +and trigger names**. The skills repo's answer is a single source of truth per connector: a list of +the names that actually exist, audited against the live Workato connector. That list is exactly the +kind of artifact ADR-0004 says should be *data* — owned and shipped by the people closest to the +connector, on their own cadence, not bottlenecked behind a linter release. + +Because this relationship lives in the seam between two repos, it had no decision record. A reader of +`recipe-lint` sees a `--skills-path` flag; a reader of `recipe-skills` sees `lint-rules.json` files; +neither repo alone explains that they are two ends of ADR-0004's "rules are data" contract. This ADR +makes that dependency explicit. + +## Decision + +**Each skill ships a `lint-rules.json` that declares its connector's lint rule data, and the linter +consumes it as data via `--skills-path`.** The governing principle, stated in the skills repo, is +*"lint rules own the **what**, instructions own the **how**."* + +**What the skills repo produces.** Every skill directory contains a `lint-rules.json`. Its schema: + +```json +{ + "version": "0.1.0", + "connector": "gmail", + "connector_internals": [], + "valid_action_names": ["__adhoc_http_action", "download_attachment", "send_mail", "..."], + "valid_trigger_names": ["new_email"], + "action_rules": [] +} +``` + +- `connector` — the provider this file describes. +- `valid_action_names` / `valid_trigger_names` — the audited, authoritative catalog. `SKILL.md`, + `validation-checklist.md`, and templates **defer** to this file and never re-enumerate names. +- `connector_internals` — provider/field names that are connector-internal (skipped or flagged). +- `action_rules` — reserved slot for per-connector **declarative** assertions (ADR-0004's assertion + vocabulary); currently empty in practice. This is the forward path, not yet exercised. + +Files may be nested (e.g. `slack-recipes/slack_bot/lint-rules.json`, +`workato-recipes/variable/lint-rules.json`); each contributes its own catalog. + +**What the linter does with it.** When invoked with `--skills-path `, the linter walks the tree +for `lint-rules.json` files and uses their data — and *only* that data — for three rules: + +- `ACTION_NAME_VALID` — rejects action names not in `valid_action_names` for that provider. +- `CONFIG_PROVIDER_MATCH` — skips providers listed in `connector_internals`. +- `EIS_NO_CONNECTOR_INTERNAL` — flags connector-internal fields that appear in `extended_input_schema`. + +The linter deliberately **does not** read `SKILL.md`, `validation-checklist.md`, templates, or +patterns. Those are for agents and humans; the data contract is `lint-rules.json` alone. + +## Alternatives considered + +- **Hardcode each connector's action/trigger lists in the linter binary.** Rejected — this directly + violates ADR-0004's bar: every connector update would force a `recipe-lint` release, and connector + teams would be blocked on the linter's cadence rather than shipping their own data. This is an + *architectural* no. +- **Enumerate valid names in `SKILL.md` or other prose docs.** Rejected: duplication that drifts, + isn't machine-checkable, and gives agents two sources to disagree on. `lint-rules.json` is the + single source of truth precisely so the prose can defer to it. +- **A bespoke per-connector rule plugin/binary.** Rejected: reintroduces the binary-release coupling + ADR-0004 exists to remove, for data that is fundamentally a list. + +## Consequences + +- **A connector team adds, renames, or audits an action by editing data** — `lint-rules.json` — with + no `recipe-lint` release. For the action/trigger-catalog class of rules, the ADR-0004 bar is met, + and `recipe-skills` is its primary realized consumer. This serves the labs **Contribute** principle + (contribute connector coverage as data, not Go) and **Agent-First** (the catalog is what stops + agents hallucinating names). + +- **Honest scope of "rules are data" here.** The *data* (the catalogs) is shipped by skills; the + *rule logic* — the three checks above — lives in the linter binary. So adding a new connector + **name** is pure data, but a genuinely new *kind* of check is not: it needs either a Go change in + the linter or population of the declarative `action_rules` slot, which today is empty. In ADR-0004's + terms, skills exercise the declarative/data path for catalogs and parameters, not yet for novel rule + logic. Stated plainly so the gap isn't mistaken for full coverage. + +- **The `lint-rules.json` schema is a cross-repo contract.** The fields the linter reads — + `connector`, `valid_action_names`, `valid_trigger_names`, `connector_internals`, and (when used) + `action_rules` — are an interface between the two repos. Changing or removing any of them is a + cross-repo breaking change and **must amend this ADR** per [LABS-0000](LABS-0000-how-we-use-cross-project-adrs.md) §6, + cross-linking the change in whichever repo drove it. + +- **Discovery is directory-walk, not a manifest.** The linter finds catalogs by walking + `--skills-path` for `lint-rules.json`, so new and nested skills are picked up automatically — but a + skill with no `lint-rules.json`, or one the path doesn't cover, is silently un-linted for names. The + skills repo's `CONTRIBUTING.md` treats the file as REQUIRED for this reason. + +- **Two surfaces to keep aligned.** This relationship is documented operationally in + `recipe-skills/docs/cli-guidance.md` and `recipe-skills/README.md`; this ADR is the *decision* + behind that documentation. If they diverge, this ADR and the linter's behavior are the sources of + truth. + +**Follow-on work (surfaced, not decided here):** + +- Whether to populate `action_rules` with declarative assertions so skills can ship genuinely new + *checks* as data — closing the gap above — or to keep skills limited to name catalogs. Either is a + real decision and should get its own ADR or an amendment, not a silent default. + + diff --git a/docs/adrs/README.md b/docs/adrs/README.md new file mode 100644 index 0000000..f7a17f7 --- /dev/null +++ b/docs/adrs/README.md @@ -0,0 +1,27 @@ +# Cross-Project Architecture Decision Records + +Decisions that govern a **relationship between two or more Workato Labs repos** — a contract, a +dependency, or a shared capability one repo provides and another consumes. Decisions internal to a +single repo live in *that repo's* `docs/adrs/`, not here. + +These are **living records**: many are written as a hypothesis ahead of (or alongside) +implementation and carry dated amendments showing how the decision evolved. Verify an ADR's claims +against the current code in the affected repos before relying on them, and amend the ADR when a +change contradicts it. The conventions — including the cross-repo amend rule — are in +[LABS-0000 — How We Use Cross-Project ADRs](LABS-0000-how-we-use-cross-project-adrs.md). They adopt +`recipe-lint`'s `0000-how-we-use-adrs.md` by reference and record only the cross-repo deltas. + +These records are repo-only Markdown and are **excluded from the published labs site**. + +Start a new one by copying [`TEMPLATE.md`](TEMPLATE.md) to `LABS-NNNN-kebab-case-title.md` (next +number). IDs carry the `LABS-` prefix so a reference from another repo is never confused with that +repo's own ADR numbers. + +| ADR | Title | Status | Affected repos | Summary | +|-----|-------|--------|----------------|---------| +| [LABS-0000](LABS-0000-how-we-use-cross-project-adrs.md) | How We Use Cross-Project ADRs | Accepted | `labs` + all | Conventions for hub-hosted cross-repo ADRs: scope, `LABS-` IDs, self-contained dependency map, heterogeneous per-repo back-references, and the cross-repo amend rule. Inherits `recipe-lint` 0000. | +| [LABS-0001](LABS-0001-skills-lint-rules-as-data.md) | Recipe Skills Declare Lint Rules as Data | Accepted | `recipe-skills` (producer), `recipe-lint` (consumer) | Each skill ships a `lint-rules.json` connector catalog as data; the linter consumes it via `--skills-path` for `ACTION_NAME_VALID`, `CONFIG_PROVIDER_MATCH`, `EIS_NO_CONNECTOR_INTERNAL`. The realized consumer of `recipe-lint` ADR-0004 — honest about where the data bar is and isn't met. | + +**Status vocabulary:** `Proposed` (drafted) · `Accepted` (agreed, in effect) · `Superseded` +(replaced by a later ADR). Implementation is tracked separately via an optional `Implemented:` date +in each ADR's header. diff --git a/docs/adrs/TEMPLATE.md b/docs/adrs/TEMPLATE.md new file mode 100644 index 0000000..728d9ad --- /dev/null +++ b/docs/adrs/TEMPLATE.md @@ -0,0 +1,64 @@ + + +# Title + +**Author(s):** Name + + +**Status:** Proposed +**Date:** Month D, YYYY + + +**Affected repos:** + +- `repo-a` (provider) — what it provides. +- `repo-b` (consumer) — what it depends on. + + + +--- + +## Context + +What cross-repo problem prompted this? Why does it belong in the hub rather than in one repo's ADRs +(LABS-0000 §1)? Capture the honest state of knowledge now — it may be a hypothesis later amendments +refine. + +## Decision + +What we decided, and why this option over the alternatives. Name the contract/dependency precisely +(schemas, flags, fields one repo reads from another) so a contributor or agent can act on it and +verify it against the code in each affected repo. + +## Alternatives considered + +What else was on the table, and why it lost. Keep *architectural* rejections inline so they aren't +re-litigated; a *scope* deferral belongs in a roadmap, not here. + +## Consequences + +What this makes easier, harder, or riskier across the affected repos. Call out the schema/contract +surface whose change would be a cross-repo breaking change (and thus trigger an amendment per +LABS-0000 §6). Note follow-on work and anything deliberately deferred. + + diff --git a/docs/diagrams/README.md b/docs/diagrams/README.md new file mode 100644 index 0000000..47c40f2 --- /dev/null +++ b/docs/diagrams/README.md @@ -0,0 +1,56 @@ +# The Developer Loop diagram + +The canonical diagram of Labs tools in action — supporting both a **human developer** +and an **agent developer** in one quality loop. Used across launch assets (exec decks, +site, social/OG, talks). + +## Files + +| File | Role | +|---|---| +| `developer-loop.svg` | **Source of truth.** Hand-crafted, design-iterated. This is the artifact the designer edits and what ships in assets. Figma-importable, git-diffable. | +| `developer-loop.mmd` | Text-native **fallback** (Mermaid). For Arc `diagram` blocks and anywhere a plain-text source is wanted. Keep in sync with the SVG when the structure changes. | + +The SVG is the master because the diagram outgrew Mermaid's auto-layout — the dual +human/agent track can't be expressed cleanly in `flowchart` syntax. The Arc spec +sanctions exactly this: "where Mermaid's auto-layout is insufficient, use a hand-crafted +SVG." The `.mmd` exists so docs/decks still have an accurate semantic source. + +## What it shows + +Recipe Skills feeds two things — grounding **context** to the AI Agent and **lint rules** +to `wk lint`. The loop: AI Agent → Write Recipe → Developer (reviews in Recipe Visualizer) +→ `wk lint` → Pass? → **Yes** ships via `wk push`; **No** routes to Fix → re-lint. `wk push` +loops back to the agent (ship + learn). Both a person and an agent are first-class actors +in the same loop; the Labs tools are the shared rails. + +## Brand + +Colors map to the canonical Labs tokens (see `index.html` / `principles.html`): + +- **Labs tools** (Recipe Skills, wk lint, wk push) — royal blue `#1D60CA` on `#D3EEFA` +- **Human developer** (Recipe Visualizer) — teal `#0b8378` on `#B3FEF7` +- **Agent developer** (AI Agent) — purple `#6932ff` on `#efeaff` +- **Fix path** — icecream `#FC9867`, text `#b3500f` +- **Neutral / shared steps** — ink `#083763` on white + +If brand tokens change, update both files together (per the brand-tokens convention). + +## Provenance + +Brought in from `~/Github/arc` for launch iteration: +- SVG: `arc/workflow-diagram.svg` (also embedded in `labs-exec-deck.html`) +- Mermaid: reconciled from `arc/labs-exec-deck.arc.md` (the original `flowchart LR` + lacked the human/agent split — this version adds it to match the SVG) + +The arc copies are decks-in-flight; this folder is the working source for the launch. + +## Open questions for design collaboration + +- **Dual entry lanes?** Today the human and agent share one loop with the human as a + mid-flow gate. For a launch asset claiming both are first-class, consider symmetric + entry lanes so neither reads as subordinate. +- **Product framing.** Should the tool nodes be visually grouped/labeled as the Labs + product surface (wk · linter · Recipe Skills · Recipe Visualizer) rather than implied? +- **Standalone vs. slide scale.** It needs to read both at slide size and as a standalone + social/OG asset. May need a captioned, higher-contrast variant. diff --git a/docs/diagrams/developer-loop.mmd b/docs/diagrams/developer-loop.mmd new file mode 100644 index 0000000..4fa4ccb --- /dev/null +++ b/docs/diagrams/developer-loop.mmd @@ -0,0 +1,36 @@ +%% The Developer Loop — Labs tools supporting a human developer and an agent developer. +%% Text-native fallback for docs/decks. The canonical, design-iterated artifact is +%% developer-loop.svg — keep this in sync with it (see README.md). Class colors map to +%% Labs brand tokens: tools = royal blue, human = teal, agent = purple, fix = icecream. +flowchart LR + RS["Recipe Skills
context + lint rules"] + AGENT["AI Agent
Claude · Cursor · Codex"] + WR["Write Recipe"] + DEV["Developer
Recipe Visualizer"] + LINT["wk lint"] + PASS{"Pass?"} + PUSH["wk push"] + FIX["Fix → re-lint"] + + RS -- context --> AGENT + RS -. lint rules .-> LINT + AGENT --> WR + WR --> DEV + DEV --> LINT + LINT --> PASS + PASS -- Yes --> PUSH + PASS -- No --> FIX + FIX -. re-lint .-> LINT + PUSH -. ship + learn .-> AGENT + + classDef tool fill:#D3EEFA,stroke:#1D60CA,color:#1D60CA; + classDef human fill:#B3FEF7,stroke:#0b8378,color:#0b8378; + classDef agent fill:#efeaff,stroke:#6932ff,color:#6932ff; + classDef fix fill:#FDEFE4,stroke:#FC9867,color:#b3500f; + classDef neutral fill:#FFFFFF,stroke:#bcd0de,color:#083763; + + class RS,LINT,PUSH tool; + class DEV human; + class AGENT agent; + class FIX fix; + class WR,PASS neutral; diff --git a/docs/diagrams/developer-loop.svg b/docs/diagrams/developer-loop.svg new file mode 100644 index 0000000..e658dd7 --- /dev/null +++ b/docs/diagrams/developer-loop.svg @@ -0,0 +1,92 @@ + + + + + + + + + + + + + + + + + + + + + + + + context + + + + lint rules + + + + + + + + + + + + + + + + Yes + + + + No + + + + + + + + + + + + Recipe Skills + context + lint rules + + + + AI Agent + Claude · Cursor · Codex + + + + Write Recipe + + + + Developer + Recipe Visualizer + + + + wk lint + + + + Pass? + + + + wk push + + + + Fix → re-lint + diff --git a/docs/quickstart-runbook.md b/docs/quickstart-runbook.md new file mode 100644 index 0000000..5b8a112 --- /dev/null +++ b/docs/quickstart-runbook.md @@ -0,0 +1,295 @@ +# Quickstart Runbook — test script for `quickstart.html` + +> **Status:** Fresh-machine test companion to `quickstart.html`. This is **not** site content +> (`docs/` is excluded from the Jekyll build). The page is the source of truth for copy; this +> runbook mirrors its arc for running the flow end-to-end and capturing real values. +> +> **Acceptance test (Principle 3):** run this start-to-finish on a clean laptop, ideally with a +> stranger. If the first five minutes feel rough, that's a bug — fix the page/runbook, not the tester. + +--- + +## The story we're telling + +**One sentence of intent → a deployed, proven `onboard_new_hire` API endpoint.** + +The Workato difference we land at least once: anyone can wrap *one* API as a tool. Composing a +**governed, multi-system** orchestration — Salesforce + Slack — into a single agent-callable tool +is what only Workato's platform underneath makes possible. + +**Portability framing (Principle 2 / 1.8):** every command can be shown in one agent (e.g. Claude +Code), but the copy says **"your agent"** — Claude, Cursor, Windsurf, Codex, or any agent. One named +tool among many, never the assumed entrypoint. + +**Where the loop runs:** the build-and-test loop runs entirely in the terminal — the dev authorizes +the created connections once in the Workato UI. The self-test is a real HTTP call against the live, +governed endpoint (no mockups), made by the agent. + +### The scenario (decisions locked) +Given a new hire's email, the automation: +1. Looks up their **Salesforce `User` record** (named persona end-to-end, e.g. *Avery Chen*). +2. Adds them to the **`#team-welcome`** Slack channel. +3. Posts a **welcome message** introducing them to the team. + +Exposed through an **API-endpoint trigger** named **`onboard_new_hire`**, which **your agent calls +over HTTP and verifies** — the moment nobody else can show. + +--- + +## The arc (9 beats — matches the page order) + +| # | Beat | Surface | Who acts | +|---|------|---------|----------| +| 0 | Install + verify (recap → homepage) | brew / scoop | dev | +| 1 | Authenticate | `wk auth login --region trial` | dev | +| 2 | Load the recipe skills | recipe-skills (clone + load) | dev | +| 3 | Create your project | `wk init` | dev | +| 4 | Prompt the agent — one sentence | your agent | dev → agent | +| 5 | Compose the recipe | recipe-skills | agent | +| 6 | Lint-fix loop | `wk lint` | agent | +| 7 | Inspect the graph (optional) | visualizer | dev | +| 8 | Push / deploy | `wk push` | agent/dev | +| 9 | Expose as an API endpoint + agent self-test | `wk api …` + `curl` | agent | +| F | Footers — "if your agent gets stuck" + "what to build next" | — | — | + +--- + +## Beat 0 — Install + verify (recap) + +Don't re-teach install; link to the homepage `#install`. The page shows the macOS commands inline +plus a verify step. The two "things you might see" notes that strand newcomers: + +- **Homebrew tap trust** — first `brew install workato-devs/tap/...` may prompt to tap/trust the + third-party tap. Expected. +- **macOS publisher / quarantine** — manual binaries trip Gatekeeper ("cannot verify the developer"). + Fix: `xattr -d com.apple.quarantine /path/to/wk`. (Already in homepage manual tab.) + +```bash +brew install workato-devs/tap/wk +brew install workato-devs/tap/recipe-lint +wk plugins install recipe-lint +code --install-extension WorkatoLabs.recipe-visualizer # or cursor / windsurf +wk version +wk plugins list # should list recipe-lint +``` + +**No Workato account?** Sign up free: `https://app.trial.workato.com/users/sign_up_trial?utm_term=sign_in` +— a Developer Sandbox workspace. Trial users authenticate with `--region trial` in Beat 1. + +--- + +## Beat 1 — Authenticate (`wk auth login`) + +```bash +# --region MUST be a flag — running `wk auth login` bare fails (401s) before the prompts. +# Use trial for the free Developer Sandbox (paid: us|eu|jp|au|sg|il|cn). +wk auth login --region trial +# Interactive prompts, in order: +# API token: (paste your wrk_… token) +# Environment: name it yourself (e.g. dev) +# Profile name: [--] ← enter to accept, or type your own +# (this is the profile alias stored in your keychain) + +wk auth status # verify connectivity (calls GET /users/me under the hood) +``` + +Token comes from the Workato UI: **Workspace admin → API clients** → create a Client Role (recipe / +connection / lifecycle perms) → create an API Client → copy the token (starts with `wrk`, shown once). +Walkthrough: `https://docs.workato.com/en/platform-cli.html#authentication`. CLI auth doc: +`wk` README → "Authenticate"; CI flags in `wk` `docs/ci-setup.md`. + +--- + +## Beat 2 — Load the recipe skills + +`git clone` recipe-skills, then load per the **skills repo's own instructions** (the canonical, +maintained source). The Labs quickstart links out rather than duplicating per-agent mechanics, so it +never drifts: `https://github.com/workato-devs/recipe-skills#quick-start`. For this build, load the +base skill plus **Salesforce** and **Slack**. + +> Multi-agent loading (Claude Code / Codex / Cursor / Windsurf) and a root `AGENTS.md` for +> standard-aware auto-discovery are owned by recipe-skills — +> [recipe-skills#5](https://github.com/workato-devs/recipe-skills/issues/5). Labs quickstart has +> **no dependency** on it; it links to whatever the skills repo documents. + +--- + +## Beat 3 — Create your project (`wk init`) + +Scaffold the project **before** prompting, so the agent writes the recipe straight into a folder +already mapped to the workspace — no moving files mid-build. Run `wk init` from wherever you keep +working projects (e.g. `~/github`); it creates a project directory there with a `wk.toml`. + +```bash +cd ~/github # or wherever you keep working projects +wk init +# prompts (both are free-text you type — no picker): +# Project name: type a name (becomes the new directory) +# Auth profile: type the profile name from Beat 1 (run `wk auth list` if unsure) +cd # work from inside the new project +``` + +`wk.toml` maps local `*.recipe.json` files to a workspace folder. Everything the agent builds from +here lands in the project, so Beat 8 is just `wk push`. + +--- + +## Beat 4 — Prompt the agent (one sentence) + +With skills loaded and a project in place, state intent. The verbatim prompt on the page: + +> "Build a Workato automation that takes a new hire's email, looks up their **User** record in +> **Salesforce**, adds them to the **#team-welcome** Slack channel, and posts a welcome message +> introducing them to the team. Expose it through an **API-endpoint trigger named `onboard_new_hire`**, +> then deploy it and call the live endpoint to confirm it works end to end." + +**The agent grounds before it writes** (read-local + ask-you — there is *no* live workspace +introspection): it confirms exact **connection names**, verifies the `User` object/fields exist, and +reads 1–2 existing `*.recipe.json` for conventions. Answer with your real connection names. + +--- + +## Beat 5 — Compose (`onboard_new_hire.recipe.json`) + +> **Name the file `onboard_new_hire.recipe.json`** — the visualizer only opens on `*.recipe.json` +> (Beat 7 silently breaks otherwise). + +Actions (all in the skills' `lint-rules.json` = source of truth): + +- **Salesforce — find the user:** `search_sobjects` on `User`, filtered by email (no get-by-id action). +- **Slack (native, `provider: "slack"`):** `get_user_by_email` → `invite_user_to_conversation` → + `post_message_to_channel`. Use `invite_user_to_conversation`, **not** `invite_user_to_channel` + (linter rejects the latter). +- **Callable trigger:** an **API-endpoint trigger** so the recipe can be wrapped in an API collection + (Beat 9). See `skills/workato-recipes/triggers/callable-recipe.md`. + +--- + +## Beat 6 — Lint-fix loop (`wk lint`) + +```bash +wk lint onboard_new_hire.recipe.json --skills-path ./recipe-skills/skills +# Exit codes: 0 = pass (warnings OK) 1 = lint error(s) 2 = invalid input +``` + +Agent reads structured diagnostics (`rule_id`, `level`, `message`, source pointer), fixes, re-lints +until exit `0`. Also runs automatically as a **`wk push` pre-push gate** (errors block). Fix-loop +*pattern* is in **recipe-skills `docs/cli-guidance.md`**, not the linter README. + +--- + +## Beat 7 — Inspect the graph (optional human checkpoint) + +Open `onboard_new_hire.recipe.json`, then any of: click the **preview icon** in the top-right of the +editor (same spot as Markdown preview; Cursor / Windsurf have the equivalent), **`Cmd+Shift+V`** / +**`Ctrl+Shift+V`**, or right-click → **"Visualize Recipe."** Click a node → details → **"Go to Code."** +Visualizer v1.0.0, purely human — no agent hook. An agent-confident dev can skip straight to deploy. + +--- + +## Beat 8 — Push / deploy (`wk push`) + +The project from Beat 3 already maps the recipe to the workspace, so deploy is one command. `wk push` +lints, then imports the recipe through Workato's **packaging APIs**. + +```bash +wk push --dry-run # preview what will be created +wk push # lints, then deploys +``` + +**Connections are created by the platform, not pre-built by the dev.** Because push imports through +the packaging APIs, the platform creates any missing Salesforce/Slack connections (and folders) as +part of the import. The dev's only hands-on bit is to authorize them *after* the push — open the recipe, +click the **Connections** tab, click each connection, and complete its sign-in in the right-hand panel. + +Starting the recipe is the **agent's** job, not the dev's — it runs `wk recipes start` in Beat 9 once the +connections are live. (The recipe is API-endpoint-triggered, so there's no run/job to inspect until the +self-test actually calls the endpoint.) + +--- + +## Beat 9 — Expose as an API endpoint + agent self-test + +**The headline moment, terminal-only.** With connections authorized, the agent starts the recipe, wraps +it in an API collection + endpoint, mints a client key (printed once at creation — the agent captures it), +and calls the live endpoint. + +```bash +wk recipes start # connections are live now → agent starts it (id from `wk status`) + +wk api collections create --name "Onboarding API" --json # prints the collection's base URL +wk api endpoints create endpoint.json --collection # bind POST /onboard → your recipe +wk api endpoints enable +wk api clients create --name "Onboarding" --collections +wk api clients keys create --name selftest --json # ← auth token, shown once +``` + +`endpoint.json` = four fields the agent writes: `name`, `method` (`POST`), `path` (e.g. `onboard`), +`flow_id` (the recipe's ID). + +The self-test — agent calls the live, governed endpoint and reads the result: + +```bash +curl -X POST /onboard \ + -H "API-TOKEN: " -H "Content-Type: application/json" \ + -d '{"email":"newhire@example.com"}' +# → {"success":true,"slack_user_id":"U…","channel_id":"C…","message_ts":"…"} +``` + +That call produces the recipe's first job — now there's a run to inspect: +`wk recipes jobs get --json` (full step traces, invaluable when the response +wasn't `success:true`). + +✅ **Success criterion for the whole runbook:** `success:true` back over HTTP, new hire in +`#team-welcome` with a welcome message — no human in the loop. + +**Optional — also expose as an MCP tool** (for chat-based agent clients): the same collection can back +an MCP server. + +```bash +wk mcp servers create --name "Onboarding" --folder-id --collection +# Reveal its token in the UI: AI Hub → MCP Servers → User access → Developer MCP Token +claude mcp add onboarding # or your editor's MCP config +``` + +The curl self-test already proved the tool works — MCP just makes it callable from chat clients. + +--- + +## Footer A — If your agent gets stuck (tested redirects) + +One line of redirection puts the agent back on track. Real snags from the test run: + +1. **Built a "callable recipe" / "genie skill" instead of an endpoint** → *"Rebuild it with an + API-endpoint trigger."* A recipe-function or genie skill can't be self-tested over plain HTTP, and + genie skills force identity-based MCP auth the CLI can't hand a token for. +2. **Salesforce search fails `MALFORMED_QUERY` / "field not present"** → *"Keep `sobject_name`, + `limit`, and `field_list` out of the action's `extended_input_schema` — list only the SObject's real + fields."* Those are reserved config keys; in the schema they leak into the SOQL `WHERE` clause. +3. **Can't add the new hire to `#team-welcome`** → *"Use `invite_user_to_conversation` (not + `…_to_channel`), and resolve the channel to an ID via `conversations.list` — there's no add-by-name."* +4. **A Slack step returns `nil` / "no method 'where' for nil"** → *"Native Slack adhoc output isn't + body-wrapped — reference `["channels"]`, not `["body","channels"]`."* (Only Workbot `slack_bot` adhoc + uses a `body` wrapper.) +5. **`wk auth login` 401s before you can paste the token** → *"Pass `--region` as a flag (e.g. + `--region trial`)"* — it can't be answered at a prompt, and a token from one region 401s against another. + +--- + +## Footer B — What to build next + +- More connector skills (Asana, Gmail, Jira, Stripe, Datatable) — the next build is one connector away. +- Community examples gallery — eventual home (roadmap 5.7). +- Discussions link; principles page. + +--- + +## Pre-test checklist (the stranger's fresh machine) + +- [ ] Install + verify done: `wk version`, `wk plugins list` shows recipe-lint, `recipe-skills` cloned, + visualizer installed. +- [ ] A Workato workspace (free trial at app.trial.workato.com if needed; auth with `--region trial`) + + API token. **Connections do NOT need pre-building** — `wk push` creates them; you authorize after. +- [ ] A Salesforce `User` record for the persona (e.g. Avery Chen) exists. +- [ ] A `#team-welcome` Slack channel exists; the Slack connection can invite + post. +- [ ] Self-test reaches `success:true` over HTTP against the live endpoint. diff --git a/downloads/recipe-visualizer-0.5.2.vsix b/downloads/recipe-visualizer-0.5.2.vsix deleted file mode 100644 index 0487905..0000000 Binary files a/downloads/recipe-visualizer-0.5.2.vsix and /dev/null differ diff --git a/downloads/recipe-visualizer-0.5.3.vsix b/downloads/recipe-visualizer-0.5.3.vsix deleted file mode 100644 index 321cbae..0000000 Binary files a/downloads/recipe-visualizer-0.5.3.vsix and /dev/null differ diff --git a/index.html b/index.html index 6003235..4b313fb 100644 --- a/index.html +++ b/index.html @@ -4,25 +4,53 @@ Workato Labs — Developer Toolkit - + + + + + + + + + + + + + + + + + + + + + - + +
-
-
+ +

- Build recipes with the
+ Build recipes with the
AI coding tools you already use

- An open-source developer toolkit for building, validating, visualizing, and managing Workato recipes — designed for humans and coding agents alike. + Build, validate, and visualize Workato recipes in your own editor — with deterministic checks your agent can't fake.

Get started - + - GitHub + Star on GitHub +
+ +
+ Works with +
    +
  • VS Code
    • +
  • Cursor
    • +
  • Windsurf
    • +
  • Claude Code
    • +
  • Codex
    • +
+
- Beta — Design Partner Program + Open source · any agent, any IDE, any OS
+
- + +
@@ -690,9 +977,62 @@

From prompt to production

+ +
+
+ What's in the box +

Four tools, one workflow

+

+ Each tool covers a piece of the developer lifecycle. Together, they replace manual recipe wrangling with an agent-native development flow. +

+ +
+ +
+
+
⌘
+

wk CLI

+ Go +
+

A unified CLI for Workato platform operations and recipe development. wk pull, wk push, wk diff, and wk status across workspaces. Plugin system for extending with custom commands.

+
+ +
+
+
✓
+

Recipe Linter

+ Go +
+

Deterministic validation compiled into wk lint. Catches datapill syntax errors, schema mismatches, and structural issues that agents can't self-validate.

+
+ +
+
+
✎
+

Recipe Skills

+ Markdown +
+

Agent-consumable knowledge for recipe authoring. Connector config, datapill syntax, control flow, error handling. Also home to connector-specific lint rules. Point your coding agent at the skills directory.

+
+ +
+
+
+

Recipe Visualizer

+ VS Code extension +
+

IDE extension rendering recipe JSON as interactive workflow graphs. Click a node, navigate to the source. Export graphs as images. VS Code, Cursor, Windsurf.

+
+ +
+
+
+
+
- + +
Get started @@ -734,7 +1074,7 @@

Install the CLI

$ wk version

Tip: Right-click the extracted binary in Finder and hold Option to copy its full path.

-

Download from Releases →

+

Download from Releases →

@@ -772,7 +1112,7 @@

Install the recipe linter

$ which recipe-lint

Tip: Right-click the extracted binary in Finder and hold Option to copy its full path.

-

Download from Releases →

+

Download from Releases →

@@ -793,77 +1133,42 @@

Clone the recipe skills

Install the recipe visualizer

IDE extension that renders recipe JSON as interactive workflow graphs. Works in VS Code, Cursor, and Windsurf.

-
- # Download the .vsix from this repo's downloads folder, then:
- $ code --install-extension ./recipe-visualizer-0.5.3.vsix
-
- # Or for Cursor:
- $ cursor --install-extension ./recipe-visualizer-0.5.3.vsix +
+ + +
+
+
+ # Search "Recipe Visualizer" in your editor's Extensions panel, or:
+ $ code --install-extension WorkatoLabs.recipe-visualizer
+
+ # Cursor and Windsurf use the same command:
+ $ cursor --install-extension WorkatoLabs.recipe-visualizer +
+

VS Code Marketplace → · Open VSX →

+
+
+
+ # Download the .vsix from the recipe-visualizer releases, then:
+ $ code --install-extension ./recipe-visualizer-1.0.0.vsix
+
+ # Or for Cursor / Windsurf:
+ $ cursor --install-extension ./recipe-visualizer-1.0.0.vsix +
+

Download from Releases →

-

Download .vsix →

-
-
- - - - - -
- - -
-
- What's in the box -

Four tools, one workflow

-

- Each tool covers a piece of the developer lifecycle. Together, they replace manual recipe wrangling with an agent-native development flow. -

- -
- -
-
-
⌘
-

wk CLI

- Go -
-

A unified CLI for Workato platform operations and recipe development. wk pull, wk push, wk diff, and wk status across workspaces. Plugin system for extending with custom commands.

-
- -
-
-
✓
-

Recipe Linter

- Go -
-

Deterministic validation compiled into wk lint. Catches datapill syntax errors, schema mismatches, and structural issues that agents can't self-validate.

-
- -
-
-
✎
-

Recipe Skills

- 7 connectors -
-

Agent-consumable knowledge for recipe authoring. Connector config, datapill syntax, control flow, error handling. Also home to connector-specific lint rules. Point your coding agent at the skills directory.

-
- -
-
-
-

Recipe Visualizer

- .vsix
-

IDE extension rendering recipe JSON as interactive workflow graphs. Click a node, navigate to the source. Export graphs as images. VS Code, Cursor, Windsurf.

+
- + +
Source @@ -874,11 +1179,11 @@

Repositories

workato-labs
-
Hub — docs, downloads, .vsix extensions
+
Hub — landing site, docs, install guide
- +
+ + + +
+ Why we build this way +

Open by default. Built for agents. Shipped fast, in the open.

+
+ Read our guiding principles → +
+
-