@feimacode/open-design-agent-kit 0.2.0 → 0.3.0

package/assets/codex-skills/open-design-recurring/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: open-design-recurring
+description: Set up a design that rebuilds itself on a schedule (a weekly report deck, next week's social posts, a refreshed one-pager), or run one such job — one job file, one supervised run, then a one-line prompt for the scheduler — use whenever the user wants a design made again every day, every week or every month, on a schedule, or as a recurring job, or when a prompt says "Run the Open Design job <path>", even if they don't mention Open Design
+---
+
+<!-- generated:open-design-agent-kit -->
+
+Recurring Open Design jobs: one job file describes what to make each period, and a scheduler runs it.
+
+Request: the rest of the user's message (if there is none, ask the user: "What should be rebuilt, from which sources, and how often?")
+
+**How to talk to the user.** Many people using Open Design don't write code, so:
+- Use the user's own words. If they say "artifact", "design tokens" or give a file path, use those terms back; otherwise use the plain words below.
+- Keep the machinery out of replies: no tool names, no ids like `od:prototype:poster-hero`, no internal files (`.artifact.json`, `.comments.json`, `config.json`), and not the words "register", "manifest", "sidecar", "entry" or "surface", unless the user used them first.
+- Explain a print term the first time it comes up, in one short clause, and not again.
+- Say where a file is the way the user would find it ("in your Open Design folder, under seed-swap-flyer"). Give a raw path only where the user can click it (Claude Code, Claude Desktop's Code tab, VS Code) or asks for it.
+- End each reply that finishes a step with one line on what they can do next, with at most two options ("Want it in Instagram sizes too, or is it ready to print?").
+
+| Instead of | Say |
+|---|---|
+| artifact, entry, registered | your design, saved |
+| design system, active design system | your style (the first time: "a saved style: colours, fonts and spacing") |
+| surface, skill, template, recipe | kind of design, starting layout, or nothing |
+| workspace, output directory | your folder, your Open Design folder |
+| bleed | print edge ("a few millimetres extra that the printer trims off") |
+| trim size | final size |
+| preflight findings, errors | "I checked it and fixed…", "one thing to look at:" |
+| export | save as PDF, save as an image |
+| inline preview, MCP App | the preview above |
+
+If the request names a job file (".open-design/jobs/<id>.job.md", usually "Run the Open Design job …"), go to **Run**. Otherwise go to **Set up**.
+
+If `start_open_design_job_run` isn't one of your tools (VS Code has no scheduler, so it doesn't offer it), you can still write the job file in **Set up**, but say that scheduled runs need Claude Code or Claude Desktop with the Open Design MCP server, and stop there.
+
+## Run
+
+1. Call `start_open_design_job_run` with the job path (and `runNow: true` only when the person asked for a fresh run in this conversation, never from a scheduled prompt).
+2. If it returns `skip`, report the reason in one line and stop. Make no changes.
+3. If it asks you to check out the state branch, do that and call it again.
+4. Otherwise follow its steps in order. This run is unattended: don't ask questions, never publish publicly and never post to social networks.
+5. End with `finish_open_design_job_run`, follow the steps it returns, and reply with its summary.
+
+## Set up
+
+### 1. Agree the job
+
+With the person, settle:
+
+- **What** to make, and with which recipe: `open-design-deck-from-source` for a report deck or one-pager from data, `open-design-social-post` for a batch of posts, `open-design-poster` for a print piece, `open-design-docs` for pages from Markdown.
+- **Sources**: workspace files (a CSV, a CHANGELOG, a report), or data a connector pulls (a sheet in Google Drive, a Notion database). Each connector source needs a `snapshot` workspace path the pulled data is saved to, so every number stays traceable.
+- **How often**: `day`, `week` or `month`, and the time zone (an IANA name such as `Europe/Berlin`).
+- **One file or one per period**: `mode: update` rewrites the same design each period (a living report); `mode: series` keeps one file per period, with `{period}` in the target (a weekly social batch).
+- **Outputs**: export formats (`pdf`, `png`, `pptx`, `standalone` …). PNG, PDF, PowerPoint and video need a browser; runs without one record them as skipped.
+- **Delivery**: `preview` (the private Claude artifact, the default), `pr` (a pull request from the state branch), or a connector action such as "Post the preview link to #design in Slack". Never a public publish or a social post: the scheduler's prompt can't stand in for the person's yes, so the job tools refuse those.
+- **Checks**: `best-effort` (default) or `required`, which holds back the PR and connector deliveries when a run had no browser for the visual check.
+
+### 2. Write the job file
+
+Write `.open-design/jobs/<id>.job.md` (the id is lowercase with hyphens and matches the file name):
+
+```markdown
+---
+id: weekly-kpis
+title: Weekly KPI deck
+recipe: open-design-deck-from-source
+period: week
+timezone: Europe/Berlin
+mode: update
+target: .open-design/weekly-kpis/weekly-kpis.html
+outputs: [pdf]
+sources:
+  - data/kpis.csv
+  - connector: Pull last week's signups from the "Metrics" sheet in Google Drive
+    snapshot: data/snapshots/signups.csv
+deliver: [preview, pr]
+checks: best-effort
+---
+
+A five-slide KPI update for the leadership team: headline numbers first, then
+signups, revenue and churn against last week, with one takeaway per slide.
+```
+
+The brief is the body: write everything a run needs to decide without asking, since nobody answers questions mid-run.
+
+### 3. One supervised run
+
+Run it now, with the person watching: call `start_open_design_job_run` and follow **Run**. Here you may ask questions; fold the answers back into the brief so later runs don't need them. If the start result lists problems by field, fix the job file and start again.
+
+### 4. Schedule it
+
+Give the person the exact prompt to save, and the steps for where they work:
+
+> Run the Open Design job `.open-design/jobs/<id>.job.md`
+
+- **Claude Code cloud scheduled task** (claude.ai/code/routines, or `/schedule`): runs without their computer. The repository needs the Open Design MCP server and skills committed (`npx @feimacode/open-design-agent-kit init --tool claude`, then commit `.mcp.json` and `.claude/skills`, and the job file). There's no browser by default, so PNG, PDF and PowerPoint outputs are skipped unless the environment's setup script installs one. The run log lives on the state branch `claude/open-design-job-<id>`. Schedule a few minutes past the hour, mid-period.
+- **Claude Desktop local scheduled task** (Code tab, Routines, New, Local): runs on their computer with local files and Chrome, only while the app is open and the computer is awake; a missed run gets one catch-up run, which the job skips if the period is already done. Tell them to click **Run now** once and approve each tool, so later runs aren't stopped by a prompt.
+- **`/loop`** in an open session: only for trying the job out; it stops when the session closes.
+- **Cowork scheduled tasks** aren't supported yet: the Open Design server runs only on the desktop.
+
+Point them to the [recurring jobs guide](https://github.com/feimacode/open-design-agent-kit/blob/main/docs/guides/recurring-jobs.md) for details.

package/assets/codex-skills/open-design-social-post/SKILL.md

@@ -9,6 +9,25 @@ Design a social media post with Open Design and export files that are ready to u
 
 Brief: the rest of the user's message (if there is none, ask the user: "What should the post say, and for which platform?")
 
+**How to talk to the user.** Many people using Open Design don't write code, so:
+- Use the user's own words. If they say "artifact", "design tokens" or give a file path, use those terms back; otherwise use the plain words below.
+- Keep the machinery out of replies: no tool names, no ids like `od:prototype:poster-hero`, no internal files (`.artifact.json`, `.comments.json`, `config.json`), and not the words "register", "manifest", "sidecar", "entry" or "surface", unless the user used them first.
+- Explain a print term the first time it comes up, in one short clause, and not again.
+- Say where a file is the way the user would find it ("in your Open Design folder, under seed-swap-flyer"). Give a raw path only where the user can click it (Claude Code, Claude Desktop's Code tab, VS Code) or asks for it.
+- End each reply that finishes a step with one line on what they can do next, with at most two options ("Want it in Instagram sizes too, or is it ready to print?").
+
+| Instead of | Say |
+|---|---|
+| artifact, entry, registered | your design, saved |
+| design system, active design system | your style (the first time: "a saved style: colours, fonts and spacing") |
+| surface, skill, template, recipe | kind of design, starting layout, or nothing |
+| workspace, output directory | your folder, your Open Design folder |
+| bleed | print edge ("a few millimetres extra that the printer trims off") |
+| trim size | final size |
+| preflight findings, errors | "I checked it and fixed…", "one thing to look at:" |
+| export | save as PDF, save as an image |
+| inline preview, MCP App | the preview above |
+
 ## 1. Pick the platform and format
 
 If the brief names a platform or format, use it. Otherwise ask the user to pick one of the rows below before doing anything else. Don't guess.
@@ -30,7 +49,7 @@ For several platforms at once, run steps 2–4 once per format and keep each one
 
 ## 2. Generate
 
-Call `prepare_open_design_brief` with the row's `skillId`, the brief, and `format` set to the row's preset id (leave it out for the X post mock and YouTube video). Call `list_open_design_design_systems` first only if the user names a brand or visual direction. For the X post mock, say in the brief that it is one card element.
+Call `prepare_open_design_brief` with the row's `skillId`, the brief, and `format` set to the row's preset id (leave it out for the X post mock and YouTube video). Call `list_open_design_design_systems` first if the user names a brand or visual direction, or `recommend_open_design_design_systems` if they name none and no design system is active. For the X post mock, say in the brief that it is one card element.
 
 Author the files yourself with your own file-editing tools, following the returned instructions, and add these rules for social posts:
 

package/assets/codex-skills/poster-hero/SKILL.md

@@ -9,4 +9,4 @@ Use the Open Design skill `od:prototype:poster-hero` (Marketing Poster).
 
 Treat the rest of the user's message as the brief. If nothing more specific was given, use: "Use the Marketing Poster template to turn my content into a vertical poster or Moments-style share image with strong visual impact. Preserve the template's visual signature, use real content and data, and avoid lorem ipsum or placeholder images."
 
-Call `prepare_open_design_brief` (the open-design MCP server's tool) with skillId "od:prototype:poster-hero" and this brief — call `list_open_design_design_systems` first only if the user names a brand or visual direction. Author the files yourself with your own file-editing tools per the returned instructions, then call `register_open_design_artifact`.
+Call `prepare_open_design_brief` (the open-design MCP server's tool) with skillId "od:prototype:poster-hero" and this brief — call `list_open_design_design_systems` first if the user names a brand or visual direction, or `recommend_open_design_design_systems` if they name none and no design system is active. Author the files yourself with your own file-editing tools per the returned instructions, then call `register_open_design_artifact`.

package/assets/codex-skills/ppt-keynote/SKILL.md

@@ -9,4 +9,4 @@ Use the Open Design skill `od:deck:ppt-keynote` (Keynote-style Slides).
 
 Treat the rest of the user's message as the brief. If nothing more specific was given, use: "Use the Keynote-style Slides template to turn my content into Apple Keynote-quality slides with one card per screen and keyboard left/right navigation. Preserve the template's visual signature, use real content and data, and avoid lorem ipsum or placeholder images."
 
-Call `prepare_open_design_brief` (the open-design MCP server's tool) with skillId "od:deck:ppt-keynote" and this brief — call `list_open_design_design_systems` first only if the user names a brand or visual direction. Author the files yourself with your own file-editing tools per the returned instructions, then call `register_open_design_artifact`.
+Call `prepare_open_design_brief` (the open-design MCP server's tool) with skillId "od:deck:ppt-keynote" and this brief — call `list_open_design_design_systems` first if the user names a brand or visual direction, or `recommend_open_design_design_systems` if they name none and no design system is active. Author the files yourself with your own file-editing tools per the returned instructions, then call `register_open_design_artifact`.

package/assets/codex-skills/resume-modern/SKILL.md

@@ -9,4 +9,4 @@ Use the Open Design skill `od:prototype:resume-modern` (Modern Resume).
 
 Treat the rest of the user's message as the brief. If nothing more specific was given, use: "Use the Modern Resume template to turn my content into a modern minimal single-page A4 resume ready for print or PDF export. Preserve the template's visual signature, use real content and data, and avoid lorem ipsum or placeholder images."
 
-Call `prepare_open_design_brief` (the open-design MCP server's tool) with skillId "od:prototype:resume-modern" and this brief — call `list_open_design_design_systems` first only if the user names a brand or visual direction. Author the files yourself with your own file-editing tools per the returned instructions, then call `register_open_design_artifact`.
+Call `prepare_open_design_brief` (the open-design MCP server's tool) with skillId "od:prototype:resume-modern" and this brief — call `list_open_design_design_systems` first if the user names a brand or visual direction, or `recommend_open_design_design_systems` if they name none and no design system is active. Author the files yourself with your own file-editing tools per the returned instructions, then call `register_open_design_artifact`.

package/assets/codex-skills/social-carousel/SKILL.md

@@ -9,4 +9,4 @@ Use the Open Design skill `od:prototype:social-carousel` (social-carousel).
 
 Treat the rest of the user's message as the brief. If nothing more specific was given, use: "Design a 3-card cinematic social carousel — ‘onwards.’, ‘to the next one.’, ‘looking ahead.’. 1080×1080 squares, drop-into-Instagram ready."
 
-Call `prepare_open_design_brief` (the open-design MCP server's tool) with skillId "od:prototype:social-carousel" and this brief — call `list_open_design_design_systems` first only if the user names a brand or visual direction. Author the files yourself with your own file-editing tools per the returned instructions, then call `register_open_design_artifact`.
+Call `prepare_open_design_brief` (the open-design MCP server's tool) with skillId "od:prototype:social-carousel" and this brief — call `list_open_design_design_systems` first if the user names a brand or visual direction, or `recommend_open_design_design_systems` if they name none and no design system is active. Author the files yourself with your own file-editing tools per the returned instructions, then call `register_open_design_artifact`.

package/assets/codex-skills/social-reddit-card/SKILL.md

@@ -9,4 +9,4 @@ Use the Open Design skill `od:prototype:social-reddit-card` (Reddit Post Card).
 
 Treat the rest of the user's message as the brief. If nothing more specific was given, use: "Use the Reddit Post Card template to turn my content into a realistic Reddit post card with vote rail and comment count for a video overlay or story share. Preserve the template's visual signature, use real content and data, and avoid lorem ipsum or placeholder images."
 
-Call `prepare_open_design_brief` (the open-design MCP server's tool) with skillId "od:prototype:social-reddit-card" and this brief — call `list_open_design_design_systems` first only if the user names a brand or visual direction. Author the files yourself with your own file-editing tools per the returned instructions, then call `register_open_design_artifact`.
+Call `prepare_open_design_brief` (the open-design MCP server's tool) with skillId "od:prototype:social-reddit-card" and this brief — call `list_open_design_design_systems` first if the user names a brand or visual direction, or `recommend_open_design_design_systems` if they name none and no design system is active. Author the files yourself with your own file-editing tools per the returned instructions, then call `register_open_design_artifact`.

package/assets/codex-skills/social-spotify-card/SKILL.md

@@ -9,4 +9,4 @@ Use the Open Design skill `od:prototype:social-spotify-card` (Spotify Now-Playin
 
 Treat the rest of the user's message as the brief. If nothing more specific was given, use: "Use the Spotify Now-Playing Card template to turn my content into a Spotify Now Playing-style card with album art, progress bar, and playback controls for a video overlay or personal homepage. Preserve the template's visual signature, use real content and data, and avoid lorem ipsum or placeholder images."
 
-Call `prepare_open_design_brief` (the open-design MCP server's tool) with skillId "od:prototype:social-spotify-card" and this brief — call `list_open_design_design_systems` first only if the user names a brand or visual direction. Author the files yourself with your own file-editing tools per the returned instructions, then call `register_open_design_artifact`.
+Call `prepare_open_design_brief` (the open-design MCP server's tool) with skillId "od:prototype:social-spotify-card" and this brief — call `list_open_design_design_systems` first if the user names a brand or visual direction, or `recommend_open_design_design_systems` if they name none and no design system is active. Author the files yourself with your own file-editing tools per the returned instructions, then call `register_open_design_artifact`.

package/assets/codex-skills/social-x-post-card/SKILL.md

@@ -9,4 +9,4 @@ Use the Open Design skill `od:prototype:social-x-post-card` (X / Twitter Post Ca
 
 Treat the rest of the user's message as the brief. If nothing more specific was given, use: "Use the X / Twitter Post Card template to turn my content into a realistic X post card with engagement metrics for a video overlay or shareable image card. Preserve the template's visual signature, use real content and data, and avoid lorem ipsum or placeholder images."
 
-Call `prepare_open_design_brief` (the open-design MCP server's tool) with skillId "od:prototype:social-x-post-card" and this brief — call `list_open_design_design_systems` first only if the user names a brand or visual direction. Author the files yourself with your own file-editing tools per the returned instructions, then call `register_open_design_artifact`.
+Call `prepare_open_design_brief` (the open-design MCP server's tool) with skillId "od:prototype:social-x-post-card" and this brief — call `list_open_design_design_systems` first if the user names a brand or visual direction, or `recommend_open_design_design_systems` if they name none and no design system is active. Author the files yourself with your own file-editing tools per the returned instructions, then call `register_open_design_artifact`.

package/assets/codex-skills/social-youtube-thumbnail/SKILL.md

@@ -9,4 +9,4 @@ Use the Open Design skill `od:prototype:social-youtube-thumbnail` (YouTube Thumb
 
 Treat the rest of the user's message as the brief. If nothing more specific was given, use: "Use the YouTube Thumbnail template to design a thumbnail for my video. Make the promise of the video readable in under a second: one short hook line, one strong focal subject, high contrast. Use real content from my brief and avoid lorem ipsum or placeholder images."
 
-Call `prepare_open_design_brief` (the open-design MCP server's tool) with skillId "od:prototype:social-youtube-thumbnail" and this brief — call `list_open_design_design_systems` first only if the user names a brand or visual direction. Author the files yourself with your own file-editing tools per the returned instructions, then call `register_open_design_artifact`.
+Call `prepare_open_design_brief` (the open-design MCP server's tool) with skillId "od:prototype:social-youtube-thumbnail" and this brief — call `list_open_design_design_systems` first if the user names a brand or visual direction, or `recommend_open_design_design_systems` if they name none and no design system is active. Author the files yourself with your own file-editing tools per the returned instructions, then call `register_open_design_artifact`.

package/assets/codex-skills/vfx-text-cursor/SKILL.md

@@ -9,4 +9,4 @@ Use the Open Design skill `od:video:vfx-text-cursor` (VFX Text Cursor).
 
 Treat the rest of the user's message as the brief. If nothing more specific was given, use: "Use the VFX Text Cursor template to turn my content into a video-intro quote reveal with cursor light trails, chromatic rays, and directional flares. Preserve the template's visual signature, use real content and data, and avoid lorem ipsum or placeholder images."
 
-Call `prepare_open_design_brief` (the open-design MCP server's tool) with skillId "od:video:vfx-text-cursor" and this brief — call `list_open_design_design_systems` first only if the user names a brand or visual direction. Author the files yourself with your own file-editing tools per the returned instructions, then call `register_open_design_artifact`.
+Call `prepare_open_design_brief` (the open-design MCP server's tool) with skillId "od:video:vfx-text-cursor" and this brief — call `list_open_design_design_systems` first if the user names a brand or visual direction, or `recommend_open_design_design_systems` if they name none and no design system is active. Author the files yourself with your own file-editing tools per the returned instructions, then call `register_open_design_artifact`.

package/assets/codex-skills/video-hyperframes/SKILL.md

@@ -9,4 +9,4 @@ Use the Open Design skill `od:video:video-hyperframes` (Hyperframes Video).
 
 Treat the rest of the user's message as the brief. If nothing more specific was given, use: "Use the Hyperframes Video template to turn my content into a Hyperframes / Remotion-compatible continuous frame animation with autoplay support. Preserve the template's visual signature, use real content and data, and avoid lorem ipsum or placeholder images."
 
-Call `prepare_open_design_brief` (the open-design MCP server's tool) with skillId "od:video:video-hyperframes" and this brief — call `list_open_design_design_systems` first only if the user names a brand or visual direction. Author the files yourself with your own file-editing tools per the returned instructions, then call `register_open_design_artifact`.
+Call `prepare_open_design_brief` (the open-design MCP server's tool) with skillId "od:video:video-hyperframes" and this brief — call `list_open_design_design_systems` first if the user names a brand or visual direction, or `recommend_open_design_design_systems` if they name none and no design system is active. Author the files yourself with your own file-editing tools per the returned instructions, then call `register_open_design_artifact`.