Skip to content

Commit d6483ea

Browse files
mayoalexanderclaude
andcommitted
feat(workflows): export a workflow as a runnable .claude/workflows/*.js (P4)
The other half of P4. `iris agents export` makes an agent forkable; this makes a workflow runnable somewhere else. IRIS stays the system of record and Claude Code becomes a runtime for it. Steps become phases: each IRIS step emits `phase(name)` + `agent(prompt)` in `order`, threading the previous step's result into the next. A stepless agentic workflow becomes a single labelled `agent()` call from agent_prompt or description. It is a TRANSLITERATION and the generated file says so in its own header rather than letting someone find out in production. Named there, per workflow: - allowed_tools — an IRIS step runs against an allowlist; a Claude Code agent() gets whatever its harness gives it. The script cannot enforce the narrower set, so it lists the tools the original was scoped to and says honouring them is on the reader. - require_human_approval — no counterpart. /workflows is ephemeral and session scoped, which is precisely the gap §03 says to sell into. - max_iterations — no equivalent ceiling. - script_content — emitted as a COMMENT, never wrapped in agent(). Pretending a shell payload is a prompt would produce a file that runs and does the wrong thing, which is worse than one that obviously does nothing. Verified by running it against real workflows: #196 (agentic, 3 steps) produces the three phases with their prompts intact and flags 3 unenforceable tools; #195 (code mode) comments its script and says so. Both outputs parse. Note the check that matters: `node --check` on the whole file FAILS, because Workflow scripts carry a top-level `return` and run inside an async wrapper supplied by the harness — so the file is verified the way the runtime reads it, meta as a module and body inside `(async () => { … })`. Checking it as a plain ES module would have reported working output as broken. Prompts are arbitrary text going into a template literal, so jsTemplate escapes backslashes, backticks and ${ — a single stray backtick in a prompt would otherwise close the literal and emit a file that looks right and does not parse. 13 tests, including one that plants backticks and asserts the body still compiles. Endpoint taken from `workflows pull` after the first guess 404'd — the same dead-path class routes:check exists to catch. Co-Authored-By: Claude Opus 5 <[email protected]>
1 parent fd7c43b commit d6483ea

4 files changed

Lines changed: 273 additions & 4 deletions

File tree

‎packages/opencode/capabilities.json‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
{
22
"generated_note": "GENERATED by script/build-capabilities.ts — do not edit by hand. Run `bun run capabilities` to refresh.",
33
"counts": {
4-
"command": 1264,
4+
"command": 1265,
55
"how-to": 39,
66
"playbook": 55,
77
"skill": 54,
8-
"total": 1412
8+
"total": 1413
99
},
1010
"terms": {
1111
"bespoke": [
@@ -10173,7 +10173,7 @@
1017310173
"describe": "manage and execute IRIS workflows — pull, push, diff, CRUD",
1017410174
"aliases": [],
1017510175
"run": "iris workflows",
10176-
"haystack": "workflows manage and execute iris workflows — pull, push, diff, crud list get create generate update pull push diff delete run status runs eval list add run history hub list import inspect run"
10176+
"haystack": "workflows manage and execute iris workflows — pull, push, diff, crud list get create generate update export pull push diff delete run status runs eval list add run history hub list import inspect run"
1017710177
},
1017810178
{
1017910179
"kind": "command",
@@ -10239,6 +10239,14 @@
1023910239
"run": "iris workflows eval run <workflowId>",
1024010240
"haystack": "workflows eval run view latest eval results for a workflow"
1024110241
},
10242+
{
10243+
"kind": "command",
10244+
"name": "workflows export",
10245+
"describe": "export a workflow as a runnable .claude/workflows/*.js",
10246+
"aliases": [],
10247+
"run": "iris workflows export <id>",
10248+
"haystack": "workflows export export a workflow as a runnable .claude/workflows/*.js"
10249+
},
1024210250
{
1024310251
"kind": "command",
1024410252
"name": "workflows generate",
@@ -10776,7 +10784,7 @@
1077610784
"describe": "Ship a bespoke (custom-HTML) Genesis /p/ page — a hand-designed HTML+CSS document published through the composable page builder. Two lanes — the CustomHtml component (raw HTML inside a composable page) and the standalone html template (full document via public-html blade). Handles the whole pipeline — write scoped HTML, build the page JSON, batch-publish, and verify the live /p/ render. Pass a subject brief or a slug as argument.",
1077710785
"aliases": [],
1077810786
"run": "iris playbook run bespoke",
10779-
"haystack": "bespoke ship a bespoke (custom-html) genesis /p/ page — a hand-designed html+css document published through the composable page builder. two lanes — the customhtml component (raw html inside a composable page) and the standalone html template (full document via public-html blade). handles the whole pipeline — write scoped html, build the page json, batch-publish, and verify the live /p/ render. pass a subject brief or a slug as argument. ---\nname: bespoke\ndescription: ship a bespoke (custom-html) genesis /p/ page — a hand-designed html+css document published through the composable page builder. two lanes — the customhtml component (raw html inside a composable page) and the standalone html template (full document via public-html blade). handles the whole pipeline — write scoped html, build the page json, batch-publish, and verify the live /p/ render. pass a subject brief or a slug as argument.\nallowed-tools:\n - read\n - edit\n - write\n - grep\n - glob\n - bash\n---\n\n# bespoke — custom-html genesis pages\n\n> ## stop — read the design standard before writing any html\n> `iris how-to view genesis-design-standard` · https://heyiris.io/p/design-philosophy-and-page-audit\n>\n> score the page against the **10-point audit** before publishing (9–10 ship · 6–8 revise · 0–5 redesign).\n> **check 01 predicts the rest:** could this design be moved onto a different subject unchanged?\n> if yes it is a template — restart from the subject, local fixes will not save it.\n>\n> three that silently break a genesis page:\n> 1. switch themes on **`html.dark`**, never `@media (prefers-color-scheme)` — the host owns the\n> theme, and a block that follows the os renders dark inside a light page.\n> 2. a customhtml block must **not paint its own `background`** — it becomes a floating slab.\n> 3. **namespace every selector** — `v-html` gives no isolation; bare `body`/`section`/`table` leak.\n>\n> and point 10: **render-verify in a browser.** grepping the served html is not verification.\n\n\npublish a hand-designed html page (audit report, one-pager, animated landing, spec sheet) as a live\ngenesis page at `https://heyiris.io/p/<slug>`. use this when the composable component catalog can't\nexpress the design and you want full html+css freedom.\n\n## arguments\n\n`$arguments` — a subject/brief (`\"bug-bounty payout audit\"`) or an existing slug to update.\n\n## two lanes — pick one\n\n| lane | what | when | how it renders |\n|------|------|------|----------------|\n| **customhtml component** | a raw-html block *inside* an otherwise-composable page (`components:[{type:customhtml,props:{html}}]`) | you want one bespoke section, or a full doc, but keep it in the normal page pipeline (tailwind loaded, theme toggle works) | iris-api renders the page; `customhtml.vue` injects your html via `v-html` **inline, no isolation** |\n| **standalone `html` template** | a *full* html document (`render_mode=html`, `iris pages create --template=html`) served by `public-html.blade.php` | a truly standalone page — arbitrary `<head>`, no framework, your own everything | the blade outputs your html with only a minimal baseline reset injected before your css |\n\ndefault to the **customhtml component** lane — it's what `pages:batch` supports cleanly and it inherits\nthe page shell + theme. reach for the standalone lane only when you need a bare document.\n\n## the recipe (customhtml lane) — proven\n\n### 1. write the html — scope every selector under a wrapper class\n\n`customhtml` injects via `v-html` **with no shadow dom / iframe**, so unscoped rules collide with the\ngenesis page shell in *both* directions. common class names (`.card`, `.tag`, `.status`, `.step`,\n`.meta`) and bare element selectors (`body`, `*`, `h1`, `table`) will clash.\n\n- wrap all content in one class: `<div class=\"xx\">…</div>`.\n- prefix **every** selector: `.xx .card{…}`, `.xx h2{…}`, `.xx *{box-sizing:border-box}`.\n- put css variables + base font/color on the wrapper: `.xx{--bg:…;background:var(--bg);…}` — **not** `:root`/`body`.\n- theme both modes at the wrapper: `@media (prefers-color-scheme:dark){.xx{--bg:…}}` **plus**\n `:root[data-theme=\"dark\"] .xx{…}` / `:root[data-theme=\"light\"] .xx{…}` (the viewer toggle stamps\n `data-theme` on the root).\n- fonts: **csp blocks font cdns** — use system stacks (`ui-monospace,…` / `-apple-system,…`), never a\n webfont `<link>`. use `font-variant-numeric:tabular-nums` for any column of figures.\n- design both light + dark; give heading custom html hand-designed page artifact branded page one-pager landing page report page custom css custom html hand-designed page artifact branded page one-pager landing page report page custom css custom html hand-designed page artifact branded page one-pager landing page report page custom css custom html hand-designed page artifact branded page one-pager landing page report page custom css custom html hand-designed page artifact branded page one-pager landing page report page custom css custom html hand-designed page artifact branded page one-pager landing page report page custom css custom html hand-designed page artifact branded page one-pager landing page report page custom css custom html hand-designed page artifact branded page one-pager landing page report page custom css custom html hand-designed page artifact branded page one-pager landing page report page custom css custom html hand-designed page artifact branded page one-pager landing page report page custom css"
10787+
"haystack": "bespoke ship a bespoke (custom-html) genesis /p/ page — a hand-designed html+css document published through the composable page builder. two lanes — the customhtml component (raw html inside a composable page) and the standalone html template (full document via public-html blade). handles the whole pipeline — write scoped html, build the page json, batch-publish, and verify the live /p/ render. pass a subject brief or a slug as argument. ---\nname: bespoke\ndescription: ship a bespoke (custom-html) genesis /p/ page — a hand-designed html+css document published through the composable page builder. two lanes — the customhtml component (raw html inside a composable page) and the standalone html template (full document via public-html blade). handles the whole pipeline — write scoped html, build the page json, batch-publish, and verify the live /p/ render. pass a subject brief or a slug as argument.\nallowed-tools:\n - read\n - edit\n - write\n - grep\n - glob\n - bash\n---\n\n# bespoke — custom-html genesis pages\n\n> ## stop — read the design standard before writing any html\n> `iris how-to view genesis-design-standard` · https://heyiris.io/p/design-philosophy-and-page-audit\n>\n> score the page against the **10-point audit** before publishing (9–10 ship · 6–8 revise · 0–5 redesign).\n> **check 01 predicts the rest:** could this design be moved onto a different subject unchanged?\n> if yes it is a template — restart from the subject, local fixes will not save it.\n>\n> three that silently break a genesis page:\n> 1. switch themes on **`html.dark`**, never `@media (prefers-color-scheme)` — the host owns the\n> theme, and a block that follows the os renders dark inside a light page.\n> 2. a customhtml block must **not paint its own `background`** — it becomes a floating slab.\n> 3. **namespace every selector** — `v-html` gives no isolation; bare `body`/`section`/`table` leak.\n>\n> and point 10: **render-verify in a browser.** grepping the served html is not verification.\n\n\npublish a hand-designed html page (audit report, one-pager, animated landing, spec sheet) as a live\ngenesis page at `https://heyiris.io/p/<slug>`. use this when the composable component catalog can't\nexpress the design and you want full html+css freedom.\n\n## arguments\n\n`$arguments` — a subject/brief (`\"bug-bounty payout audit\"`) or an existing slug to update.\n\n## two lanes — pick one\n\n| lane | what | when | how it renders |\n|------|------|------|----------------|\n| **customhtml component** | a raw-html block *inside* an otherwise-composable page (`components:[{type:customhtml,props:{html}}]`) | you want one bespoke section, or a full doc, but keep it in the normal page pipeline (tailwind loaded, theme toggle works) | iris-api renders the page; `customhtml.vue` injects your html via `v-html` **inline, no isolation** |\n| **standalone `html` template** | a *full* html document (`render_mode=html`, `iris pages create --template=html`) served by `public-html.blade.php` | a truly standalone page — arbitrary `<head>`, no framework, your own everything | the blade outputs your html with only a minimal baseline reset injected before your css |\n\ndefault to the **customhtml component** lane — it's what `pages:batch` supports cleanly and it inherits\nthe page shell + theme. reach for the standalone lane only when you need a bare document.\n\n## the recipe (customhtml lane) — proven\n\n### 1. write the html — scope every selector under a wrapper class\n\n`customhtml` injects via `v-html` **with no shadow dom / iframe**, so unscoped rules collide with the\ngenesis page shell in *both* directions. common class names (`.card`, `.tag`, `.status`, `.step`,\n`.meta`) and bare element selectors (`body`, `*`, `h1`, `table`) will clash.\n\n- wrap all content in one class: `<div class=\"xx\">…</div>`.\n- prefix **every** selector: `.xx .card{…}`, `.xx h2{…}`, `.xx *{box-sizing:border-box}`.\n- put css variables + base font/color on the wrapper: `.xx{--bg:…;background:var(--bg);…}` — **not** `:root`/`body`.\n- theme both modes at the wrapper: `@media (prefers-color-scheme:dark){.xx{--bg:…}}` **plus**\n `:root[data-theme=\"dark\"] .xx{…}` / `:root[data-theme=\"light\"] .xx{…}` (the viewer toggle stamps\n `data-theme` on the root).\n- fonts: **csp blocks font cdns** — use system stacks (`ui-monospace,…` / `-apple-system,…`), never a\n webfont `<link>`. use `font-variant-numeric:tabular-nums` for any column of figures.\n- design both light + dark; give heading custom html hand-designed page artifact branded page one-pager landing page report page custom css custom html hand-designed page artifact branded page one-pager landing page report page custom css custom html hand-designed page artifact branded page one-pager landing page report page custom css custom html hand-designed page artifact branded page one-pager landing page report page custom css custom html hand-designed page artifact branded page one-pager landing page report page custom css custom html hand-designed page artifact branded page one-pager landing page report page custom css custom html hand-designed page artifact branded page one-pager landing page report page custom css custom html hand-designed page artifact branded page one-pager landing page report page custom css custom html hand-designed page artifact branded page one-pager landing page report page custom css custom html hand-designed page artifact branded page one-pager landing page report page custom css custom html hand-designed page artifact branded page one-pager landing page report page custom css"
1078010788
},
1078110789
{
1078210790
"kind": "playbook",
Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
import { describe, expect, test } from "bun:test"
2+
import { buildScript, jsTemplate, scopedTools, slugify } from "./platform-workflows-export"
3+
4+
/**
5+
* The generated file's whole promise is that it RUNS. A prompt is arbitrary user text and
6+
* goes inside a template literal, so a stray backtick or ${ would close the literal early
7+
* and emit a file that looks fine and does not parse.
8+
*/
9+
describe("jsTemplate", () => {
10+
test("escapes a backtick so the literal cannot be closed early", () => {
11+
expect(jsTemplate("run `ls` now")).toBe("`run \\`ls\\` now`")
12+
})
13+
test("escapes ${ so nothing interpolates", () => {
14+
expect(jsTemplate("cost is ${total}")).toBe("`cost is \\${total}`")
15+
})
16+
test("escapes backslashes before anything else", () => {
17+
expect(jsTemplate("a\\b")).toBe("`a\\\\b`")
18+
})
19+
})
20+
21+
describe("buildScript", () => {
22+
const base = { id: 1, name: "My Flow", description: "d", execution_mode: "agentic" }
23+
24+
test("emits one phase and one agent call per step, in order", () => {
25+
const { code } = buildScript({ ...base, steps: [
26+
{ name: "Second", order: 2, prompt: "two" },
27+
{ name: "First", order: 1, prompt: "one" },
28+
]})
29+
expect(code.indexOf('phase("First")')).toBeLessThan(code.indexOf('phase("Second")'))
30+
expect(code).toContain("const step1 = await agent(")
31+
expect(code).toContain("const step2 = await agent(")
32+
expect(code).toContain("return { step1, step2 }")
33+
})
34+
35+
test("a stepless agentic workflow still produces a runnable single-agent script", () => {
36+
const { code } = buildScript({ ...base, steps: [], agent_prompt: "do the thing" })
37+
expect(code).toContain('phase("Run")')
38+
expect(code).toContain("return { result }")
39+
})
40+
41+
test("script_content is commented, never wrapped in agent()", () => {
42+
const { code, untranslated } = buildScript({ ...base, execution_mode: "code", script_content: "rm -rf /tmp/x", steps: [] })
43+
expect(code).toContain("/* Original script_content")
44+
expect(code).not.toContain("agent(`rm -rf")
45+
expect(untranslated.some((u) => u.startsWith("script_content"))).toBe(true)
46+
})
47+
48+
test("names what did not survive rather than dropping it quietly", () => {
49+
const { untranslated } = buildScript({ ...base, steps: [], require_human_approval: true, allowed_tools: ["a", "b"], max_iterations: 7 })
50+
expect(untranslated.join(" ")).toContain("require_human_approval")
51+
expect(untranslated.join(" ")).toContain("allowed_tools")
52+
expect(untranslated.join(" ")).toContain("max_iterations=7")
53+
})
54+
55+
test("a clean workflow reports nothing untranslated", () => {
56+
expect(buildScript({ ...base, steps: [{ name: "s", order: 1, prompt: "p" }] }).untranslated).toEqual([])
57+
})
58+
59+
test("a prompt full of backticks still yields a parseable body", () => {
60+
const { code } = buildScript({ ...base, steps: [{ name: "s", order: 1, prompt: "use `cmd` and ${x}" }] })
61+
const body = code.slice(code.indexOf("phase("))
62+
expect(() => new Function(`return (async () => {\n${body}\n})`)).not.toThrow()
63+
})
64+
})
65+
66+
describe("scopedTools", () => {
67+
test("merges every storage location, dedupes, sorts", () => {
68+
expect(scopedTools({ allowed_tools: ["b"], settings: { allowed_tools: ["a"] }, agent_config: { tools: [{ type: "c" }] } })).toEqual(["a", "b", "c"])
69+
})
70+
test("empty when nothing is scoped", () => {
71+
expect(scopedTools({})).toEqual([])
72+
})
73+
})
74+
75+
describe("slugify", () => {
76+
test("handles em-dashes and punctuation", () => {
77+
expect(slugify("Good Deals — Daily Deal Aggregator")).toBe("good-deals-daily-deal-aggregator")
78+
})
79+
test("never returns empty", () => {
80+
expect(slugify("!!!")).toBe("workflow")
81+
})
82+
})

0 commit comments

Comments
 (0)