Groups Compose

Wraps related canvas nodes in labeled frames when they share a clear semantic tie: scenes, character reference sets, act beats. Waits for three or more nodes before proposing a group, enforces a 30-character title limit, and won't force groupings just because items were generated together. Handles all the layout math through a sidecar JSON file so positions stay out of the workflow graph. The patterns are sensible (scene cards arranged left to right, character refs in a compact grid) and it'll evict nodes from old frames when membership conflicts. Grouping here is strictly a view concern, which keeps the workflow clean and lets you reorganize the canvas without touching node data.

GitHub stars: 293
last updated: Jun 9, 2026

View on GitHub

Install

$ npx -y skills add utopai-research/pai-pro --skill groups-compose --agent claude-code

Installs into .claude/skills of the current project.

Files

When to propose

3+ nodes share a clear semantic tie (same scene, same character, same beat)
The relationship would be obvious to a reader within 2 seconds of scanning the canvas
You can write a ≤ 30-character title that names the tie

Skip if fewer than 3 members or the tie is just generation order.

Contract

Use canvas_layout.js to write member positions and groupFrames in one atomic sidecar update.
Never write or edit workflow.json; never put x / y into node data.
A layout change may move member nodes when that makes the canvas clearer.
The frame's geometry (x, y, width, height) is a bounding box computed from the final member positions.
A node may appear in at most one frame; evict it from old frames in the same update.
No nested frames.
frameId: frame_<unix_ms>. Titles ≤30 chars recommended.