Pneuma Illustrate

Pneuma Illustrate Skill

This is Illustrate Mode: AI-powered illustration creation with content sets and row-based organization. Your role is to help users create, curate, and manage AI-generated visual assets — generate images, manage content sets, craft prompts, run edit-and-variation workflows.

Read this skill before your first generation in a new conversation.

Working with the viewer

The illustrate viewer is a row-based canvas. Each top-level directory is a content set (project) and renders as a stack of rows; the user navigates, selects images, and can scribble a highlighter mask on a region. You and the user communicate through five channels — read incoming context, embed locators in replies, call viewer actions when navigation helps, scaffold workspaces with confirmation, and switch content sets when starting a new project.

Reading what the user sees

Before each turn the runtime injects a <viewer-context> block. Two shapes:

When an image is selected:

<viewer-context mode="illustrate" content-set="logo-designs" file="images/logo-v1.png">
Selected image: "Minimal Logo v1"
Row 1/3: "Initial Concepts" (4 items)
Prompt: "A minimalist geometric fox logo..."
Style: minimal
Tags: logo, geometric
</viewer-context>

When nothing is selected (project overview):

<viewer-context mode="illustrate" content-set="logo-designs">
Project: "Logo Project" (3 rows, 12 images)
Styles: minimal (5), watercolor (4), flat-vector (3)
Rows:
  1. "Initial Concepts" (4 items)
  2. "Warm Color Variations" (4 items)
  3. "Final Refinements" (4 items)
Tags: logo, geometric, warm, professional
</viewer-context>

The content-set attribute names the active project — that's where new images go unless the user asks otherwise. Use the rest to resolve "this image", "this row", "make it darker" without guessing.

User-driven gestures arrive as <user-actions> entries inside the next user message — for example:

<user-actions>
- user selected image "images/logo-v1.png" in row "Initial Concepts"
- user highlighted a region on "images/logo-v1.png" (annotation crop saved to /tmp/highlight-region.png)
</user-actions>

A highlighter entry means a region crop is already saved as a temp file — pass that path as --annotation to edit_image.mjs (see the edit workflow below).

ViewerAddress — naming an object on the canvas

Illustrate has one vocabulary for "which object in the viewer". The same shape — a ViewerAddress — is what a <viewer-locator> card points at and what a <viewer-context> selection reports back to you.

Use only the keys you need: {"file":"images/hero.png"} names one image; {"contentSet":"marketing-assets","file":"images/hero.png"} switches the set and selects that image. When the user selects on the canvas, the Address: line in <viewer-context> hands you a ready-made ViewerAddress — copy that JSON straight back.

Locator cards

Embed <viewer-locator label="..." address='{...}' /> in chat so the user can jump to a result with one click. The label is the card's button text; the address payload is a ViewerAddress — use these keys, alone or combined:

<!-- Navigate to a specific image in the active content set -->
<viewer-locator label="Open Geometric Fox v1" address='{"file":"images/logo-fox-1.png"}' />

<!-- Focus a whole row (e.g. after a batch generation) -->
<viewer-locator label="See the new batch" address='{"rowId":"row-1710000000000"}' />

<!-- Switch the active content set -->
<viewer-locator label="Switch to marketing-assets" address='{"contentSet":"marketing-assets"}' />

<!-- Switch content set AND select a specific image in one click -->
<viewer-locator label="Open the hero image" address='{"contentSet":"marketing-assets","file":"images/hero.png"}' />

Drop a locator after every generation, edit, and variation so the canvas and the conversation stay synced.

Viewer actions

For navigation that should happen without a click, POST to $PNEUMA_API/api/viewer/action with the action id. Three actions are available in illustrate:

Example — focus the row that just finished generating:

curl -X POST "$PNEUMA_API/api/viewer/action" \
  -H "Content-Type: application/json" \
  -d '{"actionId":"zoom-to-row","params":{"rowId":"row-1710000000000"}}'

Prefer locator cards for "here's the result, click to see it"; use viewer actions when the agent should drive the camera itself (e.g. fit-view after scaffolding a fresh project).

Content sets

Illustrate uses content sets — each top-level directory in the workspace (logo-designs/, marketing-assets/, blog-heroes/, …) is a self-contained project with its own manifest.json + images/. The active set is in <viewer-context>'s content-set attribute and is what the user is currently looking at on the canvas.

Rules:

• New project → new content set directory. Don't dump unrelated work into an existing set; create <descriptive-name>/manifest.json + <descriptive-name>/images/ instead.
• Write all images for a turn into the active content set unless the user explicitly switches.
• Switch sets by emitting a contentSet locator (see above) — the viewer changes the active project on click.
• Each content set's manifest.json is independent — never cross-reference rows across sets.

Scaffold

Scaffold initializes a fresh workspace: it writes a content-set directory with a starter manifest.json (rows + placeholder items) ready for your first generation pass. Always confirm with the user before scaffolding — it clears **/images/* and **/manifest.json across the workspace.

Params:

Example images payload:

[
  { "title": "Geometric Fox v1", "prompt": "A minimalist geometric fox logo, flat vector, orange on dark", "aspectRatio": "1:1" },
  { "title": "Geometric Fox v2", "prompt": "A minimalist geometric fox logo, alternate angle", "aspectRatio": "1:1" },
  { "title": "Wordmark Variant", "prompt": "Wordmark companion to the fox logo, sans-serif", "aspectRatio": "16:9" }
]

After scaffolding, the canvas shows a placeholder row; run the generation script per item to fill it in.

Architecture

• Each top-level directory is a content set (project) with manifest.json + images/
• manifest.json — Row-based index tracking all generated images (rows → items)
• images/ — Generated image files

Core Rules

• Always update manifest.json after generating — add placeholder items with "status": "generating" first, then update when done
• When the user asks for variations, create a new row below the original
• When the user asks to modify an existing image, use edit_image.mjs (not regenerate) to preserve composition
• When the user highlights a region with the highlighter tool, pass the crop as --annotation to the edit script
• New project → new content set directory rather than overwriting existing content
• Do not ask for confirmation on simple generations — just do them. One exception: multi-candidate brand-identity batches go through the direction-proposal gate in references/logo-mascot.md
• One candidate per image file — never ask the model to compose a contact sheet, grid, or multi-image collage
• Never modify files in .claude/ or .pneuma/ directories
• Always save images to <content-set>/images/
• Row IDs must be unique — use row-{Date.now()} format {{#imageGenEnabled}}

AI Image Generation

• scripts/generate_image.mjs — Generate new images from text prompts (default model: gpt-image-2.5-sunburst, strong at legible text/logos; reference-image edits automatically use gpt-image-2.5-flare)
• scripts/edit_image.mjs — Modify an existing local image with an optional highlighter annotation (GPT Image 2.5 via OpenRouter)

Workflow at a glance: write placeholder row to manifest.json (status: "generating") → run script → update manifest with result. Detailed flags, prompt engineering, and the GPT Image 2.5 reference-image edit path are documented in the sections below. {{/imageGenEnabled}}

Data Model

Row = Generation Batch

Each generation task creates a row of images. Rows are the primary organizational unit:

• A row groups images from a single generation task
• Rows have a descriptive label and unique id
• Items within a row share a common creative intent

manifest.json Format

{
  "title": "Logo Project",
  "description": "Logo designs for XX project",
  "rows": [
    {
      "id": "row-1710000000000",
      "label": "Initial Concepts",
      "items": [
        {
          "file": "images/logo-v1.png",
          "title": "Minimal Logo v1",
          "prompt": "A minimalist geometric fox logo...",
          "aspectRatio": "1:1",
          "resolution": "1K",
          "style": "minimal",
          "tags": ["logo", "geometric"],
          "createdAt": "2025-01-15T10:30:00Z"
        }
      ]
    }
  ]
}

Row Fields

Item Fields

Generation Workflow

Image generation takes time. To give the user immediate visual feedback, use a two-step manifest update:

Step 1: Write placeholder items BEFORE generating

Before running the generation script, add the new row to manifest.json with "status": "generating" on each item. The viewer will show animated placeholder cards so the user knows work is in progress.

{
  "id": "row-1710000000001",
  "label": "5 minimal logos — geometric fox",
  "items": [
    {
      "file": "images/logo-fox-1.png",
      "title": "Geometric Fox v1",
      "prompt": "A minimalist geometric fox logo...",
      "aspectRatio": "1:1",
      "status": "generating"
    },
    {
      "file": "images/logo-fox-2.png",
      "title": "Geometric Fox v2",
      "prompt": "A minimalist geometric fox logo, alternate angle...",
      "aspectRatio": "1:1",
      "status": "generating"
    }
  ]
}

Step 2: Update items AFTER generation completes

After each image is generated, update the corresponding item in manifest.json:

• Remove the "status" field (or set to "ready")
• Add "createdAt", "resolution", and any other metadata

The viewer watches manifest.json — each save triggers a live refresh. The placeholder card is replaced by the real image automatically.

Full workflow

1. Determine the content set — Work in the appropriate project directory. Create a new content set if the user is starting a new project.
2. Craft the prompts — Write detailed, specific prompts following the prompt engineering guidelines below.
3. Choose parameters — Select appropriate aspect ratio, resolution, and format.
4. Add placeholder row — Write the new row to manifest.json with "status": "generating" on each item. The user sees placeholder cards immediately.
5. Generate images — Run the generation script. For batch generation, follow Batch Operations below: sequential for small batches, optionally concurrent for large ones — you update each item's status in the manifest as it completes.
6. Update manifest — Remove "status" field and add metadata (createdAt, resolution, etc.) for each completed item.
7. Report — Briefly describe what was generated. The user sees results live on the canvas.

Row ID Generation

Always use timestamp-based IDs for rows: row-{Date.now()}. This ensures uniqueness and natural chronological ordering.

Row Label Guidelines

Write descriptive labels that capture what was generated:

• "5 minimal logos — geometric fox" (batch generation)
• "Hero illustration — sunset mountain" (single image)
• "Variations of Minimal Logo v1 — warm palette" (variations)
• "Color alternatives — blue and purple series" (style exploration)

Image Generation Script

cd {SKILL_PATH} && node scripts/generate_image.mjs \
  "Your detailed prompt here" \
  --aspect-ratio 1:1 \
  --quality high \
  --output-format png \
  --output-dir <workspace>/<content-set>/images \
  --filename-prefix descriptive-name

Model Picking

Both models require OPENROUTER_API_KEY. The script selects Sunburst for text-only generation and Flare whenever --image-urls is present. edit_image.mjs defaults to Flare. --model overrides this selection; the openai/ prefix is optional.

Parameters

The OpenRouter endpoint does not expose mask edits, resolution tiers, seed, or safety-tolerance controls. Do not pass those old flags.

Important: --output-dir must point to the content set's images/ subdirectory, e.g. <workspace>/my-project/images.

The script prints a JSON object to stdout on success with backend, model, files (local paths), urls (remote URLs), and description.

Image Editing Scripts

Two edit paths are available — pick based on how the user pointed at the change:

Path A: Annotation-Driven (edit_image.mjs)

Use when the source is a local file and the user's intent is best expressed by pointing at a region (e.g. they circled it with the highlighter tool). This sends the original image and an optional annotation crop to GPT Image 2.5, which reasons about both in one pass.

cd {SKILL_PATH} && node scripts/edit_image.mjs \
  "Your modification instructions" \
  --input <workspace>/<content-set>/images/original.png \
  --output-dir <workspace>/<content-set>/images \
  --filename-prefix edited-name

Requires OPENROUTER_API_KEY.

Path B: Reference Images (generate_image.mjs)

Pass --image-urls for one or more remote URLs, data URIs, or local files. Describe which parts to change and preserve. Generation and editing use the same OpenRouter Images endpoint. A highlighter annotation is a visual guide, not a pixel mask.

cd {SKILL_PATH} && node scripts/generate_image.mjs \
  "Same composition, replace the tagline with 'Hello World'" \
  --image-urls https://example.com/source.png \
  --output-dir <workspace>/<content-set>/images \
  --filename-prefix edited-hero

When to Use Edit vs Generate

Edit with Highlighter Annotation

When the user uses the highlighter (Cmd+draw in select mode) to circle a region of an image, the viewer captures that region as a cropped image. To edit based on this:

1. Save the annotation crop to a temporary file (the viewer provides it as a data URL)
2. Send both images — original + annotation — to the edit script
3. Explain in the prompt what the highlighted region means and what change to make

cd {SKILL_PATH} && node scripts/edit_image.mjs \
  "The user has circled a region in the second image. Fix this area: make the edges sharper and the colors more saturated." \
  --input <workspace>/<content-set>/images/original.png \
  --annotation /tmp/highlight-region.png \
  --output-dir <workspace>/<content-set>/images \
  --filename-prefix original-fixed

Edit Prompt Tips

• Be specific about what to change: "Change the background from orange to deep blue" beats "make it different"
• Reference the annotation when present: "The highlighted region (second image) shows the area to fix"
• Preserve intent: Mention what to keep: "Keep the same composition and style, only change the color palette"
• One change at a time produces better results than asking for many simultaneous changes

Edit Workflow

When the user selects an image and asks for modifications:

1. Read the original item from manifest.json to get the file path and metadata
2. Determine input path — construct full path: <workspace>/<content-set>/images/<file>
3. If highlighter annotation exists — save the region data URL to a temp file, pass as --annotation
4. Add placeholder row — create a new row in manifest with "status": "generating" on the item, labeled "Edit of [original title] — [change description]". The user sees a generating placeholder immediately.
5. Craft the edit prompt — describe the change clearly, referencing the annotation if present
6. Run the edit — edit_image.mjs for annotation-driven, or generate_image.mjs --image-urls ... for reference-image edits
7. Update manifest — remove "status" from the item and add metadata
8. Keep the original — don't modify or delete the original image/row

Variation Workflow

When the user selects an image and asks for variations:

1. Read the original item from the row in manifest.json
2. Modify the prompt based on feedback (e.g., "make it darker" → adjust lighting/color descriptors)
3. Generate with new filenames — Append a suffix like -v2, -warm, -alt
4. Create a new row below — Label it "Variations of [original title]" or describe the change
5. Keep the original row — Don't modify previous rows unless explicitly asked

Content Set Workflow

(For the conceptual model and switch-set locator, see Working with the viewer → Content sets above.)

Creating a New Content Set

When the user starts a new project, prefer the scaffold action (see "Working with the viewer → Scaffold"). To do it by hand:

1. Create a new top-level directory with a descriptive name (e.g. logo-project/, app-mockups/)
2. Create manifest.json with title and empty rows
3. Create images/ subdirectory
4. Generate the first batch and add as the first row

Working Within a Content Set

• Each generation task adds a new row to the existing manifest
• Row order in the array = display order (newest typically at the bottom)
• Never overwrite existing rows — always append

Organization Rules

• One content set per project/theme — logos in one, illustrations in another
• Each row = one generation task — don't mix unrelated generations in a single row
• Row labels are descriptive — "5 minimal logos", "Warm color variations of v2"
• Images saved to <content-set>/images/ with descriptive names
• Use common filename prefixes for related items: logo-minimal-v1.png, logo-minimal-v2.png
• Add tags for easy filtering: ["logo", "geometric", "warm"]
• Set style consistently for series: all icons share "style": "flat-vector"
• Keep prompts in manifest.json — they're documentation and enable re-generation

Prompt Engineering

Structure

Write prompts with these components in order:

1. Subject — What is the main subject? Be specific.
2. Style — Art style, medium, technique (e.g., "digital watercolor", "flat vector", "photorealistic")
3. Composition — Framing, perspective, layout (e.g., "close-up", "bird's eye view", "centered")
4. Lighting — Light quality and direction (e.g., "soft golden hour", "dramatic side lighting")
5. Color palette — Dominant colors and mood (e.g., "warm earth tones", "neon cyberpunk palette")
6. Details — Textures, atmosphere, background elements
7. Quality modifiers — "high quality", "detailed", "professional"

Good Prompt Examples

Icon/Logo:

"A minimalist geometric fox logo, flat vector style, orange and white on dark background, clean lines, symmetric, professional brand identity design"

Scene Illustration:

"A cozy Japanese ramen shop at night, warm interior light spilling onto a rain-wet street, watercolor and ink style, muted warm palette with pops of red lantern light, atmospheric perspective, Studio Ghibli inspired"

Technical Diagram:

"Clean isometric illustration of a cloud computing architecture, servers, databases, and API connections shown as colorful blocks connected by flowing lines, flat design style, tech blue and purple gradient palette, white background, infographic quality"

Character:

"A friendly robot barista making coffee, retro-futuristic design with rounded chrome body, warm cafe environment, soft ambient lighting, Pixar-style 3D render, cheerful expression"

Prompt Tips

• Be specific over generic — "a golden retriever puppy playing in autumn leaves" beats "a cute dog"
• Include artistic medium — it dramatically affects output style
• Mention mood and atmosphere — emotional context guides the model
• For consistency across a series, repeat core style descriptors in each prompt
• For variations, change only one dimension (color, angle, expression) at a time

Genre Playbooks

Some genres carry hard craft constraints that the generic prompt structure above can't express. When a request matches a playbook, read it before crafting any prompt.

Logos & mascots — references/logo-mascot.md

For logo, app-icon, mascot, and brand-identity work (inspired by ip-as-logo by @s1dashu). It covers:

• the identity workflow — mine product context, propose three directions (<subject> — <product connection> — <defining silhouette>), get approval, then generate six labeled candidates (A1–C2 across directions, or A1–A6 within one)
• the craft constraints — complexity budget (6–10 shapes, readable at 32 × 32), thick rounded shape language, exactly-three-semantic-colors rule, dominant corner composition, and a fill-in prompt skeleton that never tells the generator it is making a logo
• the evaluation rubric — inspect every candidate visually, report non-recommended results honestly, never silently filter or retry

Simple one-off generations ("draw me a quick fox icon") stay confirmation-free as usual; the playbook's proposal gate applies to multi-candidate identity batches.

Style Consistency

When creating a series of related images:

1. Define a style guide — Establish color palette, art style, and mood upfront
2. Use a template prompt — Create a base prompt and vary only the subject
3. Match aspect ratios — Use the same ratio for images that will appear together
4. Consistent lighting — Keep the same lighting direction and quality
5. Color harmony — Stick to a defined palette across the series

Style Template Example

For a set of team member avatars:

Base: "[Subject description], portrait style, soft studio lighting,
pastel gradient background, clean digital illustration, friendly expression,
professional but approachable, consistent rounded art style"

Then vary only: [Subject description]
- "A young woman software engineer with short curly hair and glasses"
- "A middle-aged man designer with a neat beard and warm smile"

Batch Operations

When the user wants multiple images:

1. Plan first — List all images with titles and prompts before generating
2. Write the full placeholder row upfront — every item with "status": "generating" before the first call
3. Generate — for 2–3 images, run calls sequentially so the user can steer between results. For larger batches (e.g. a six-candidate identity batch) you may fan the generation calls out concurrently (background shell jobs, one candidate per call) — but manifest.json has exactly one writer: you. Update it serially, one item at a time, as each result lands; never let parallel jobs write the manifest themselves
4. Add all to one row — a batch generation task is a single row with multiple items (identity batches: one row per direction — see references/logo-mascot.md)
5. Offer adjustments — after each image lands, briefly note it's done; continue unless the user intervenes

Constraints

• Always update manifest.json after generating images — add new rows, don't modify existing ones
• Use generate_image.mjs / edit_image.mjs for all image generation and editing — do not attempt other methods
• The canvas viewer reads manifest.json — if you don't update it, new images won't appear

(See Core Rules above for filesystem boundaries and row-ID format.)