SuperAPI AI Directory
Partner中文AI newsFavorites
Skillscocosketch

cocosketch

Design & creation

View repository

Updated 10-23 23:07

About this skill

CocoSketch — Visual Artifact Generation Pipeline

Core Principle

Diagram quality requires a pipeline, not a single prompt. The AI generates XML; deterministic scripts validate and repair. Never skip validation or repair steps.

Seven-Step Pipeline (ALL modes)

Step 1: Resolve style preset
Step 2: Check draw.io CLI availability (resolve binary once, use verbatim)
Step 3: Plan layout — shapes, relationships, groups; run cocosketch/sketch-autolayout for >15 nodes
Step 4: Generate draw.io XML → run cocosketch/sketch-validate → STOP pipeline if FAIL
Step 5: Export PREVIEW PNG (NO -e flag) capped at 2000px
Step 6: Self-check preview via vision — auto-fix overlaps/clipped labels (max 2 rounds)
Step 7: Export FINAL PNG (WITH -e flag) → run cocosketch/sketch-repair → deliver to developer

NEVER skip Steps 4 or 7. NEVER add -e to Step 5. NEVER omit -e from Step 7.

Step 1 — Resolve Style Preset

Check ~/.cocoplus/sketch-styles/ first, then .cortex/sketch/styles/built-in/. Available built-in styles: default, corporate, handdrawn. Default: default.json. Load and apply to all generated cells.

Step 2 — Check draw.io CLI

Try in order: drawio --version, draw.io --version, OS-specific paths. Resolve binary name ONCE. Store as DRAWIO_BIN. Use DRAWIO_BIN verbatim in Steps 5 and 7.

Fallback chain (if draw.io unavailable):

  1. Generate Mermaid markup → write <name>.mmd, inform developer
  2. If Mermaid not applicable: deliver raw .drawio XML with open-in-browser instructions

Step 3 — Plan Layout

  • Direction: LR for sequences/pipelines, TB for hierarchies/schemas
  • For >15 nodes: run invoke cocosketch/sketch-autolayout <input.json> <layout.json>
  • For ≤15 nodes: hand-place coordinates with reasonable spacing (120px wide × 60px tall, 50px H-gap, 40px V-gap)
  • Groups: use swimlane cells to visually cluster related nodes

Step 4 — Generate XML + Validate

Required XML structure:

<mxGraphModel>
  <root>
    <mxCell id="0" />
    <mxCell id="1" parent="0" />
    <!-- shape cells: parent="1", unique id each -->
  </root>
</mxGraphModel>

Run: invoke cocosketch/sketch-validate <file.drawio> If FAIL: stop immediately. Report structural errors. Do not proceed to Step 5.

Step 5 — Export Preview PNG (NO -e)

$DRAWIO_BIN -x -f png --width 2000 -o <name>-preview.png <file.drawio>

No -e flag. Preview is for agent vision API — embedded XML produces a truncated IEND that vision APIs reject.

Step 6 — Self-Check

Read <name>-preview.png using vision capability. Identify: overlapping nodes, clipped labels, missing edge connections. Auto-fix in the .drawio XML source. Maximum 2 correction rounds. After round 2: proceed and note any remaining issues in output.

Step 7 — Final Export + Repair

$DRAWIO_BIN -x -f png -e --width 2000 -o <name>.png <file.drawio>
invoke cocosketch/sketch-repair <name>.png

-e flag embeds diagram XML in PNG — developer can open in draw.io directly. cocosketch/sketch-repair restores truncated IEND chunk that -e can produce. Output: <name>.png and <name>.drawio written to .cocoplus/diagrams/.

Record the exact final PNG path in the command output. If Mermaid fallback is used, output the .mmd path instead and clearly state that PNG export was unavailable.

Mode: $sketch schema [--tables <list>]

  1. Query Snowflake: SHOW TABLES (full schema) or scoped to --tables list
  2. Query: SHOW COLUMNS IN TABLE <name> for each table
  3. Build table relationship graph:
    • FK references → directed edges
    • Shared key column names → undirected edges (dashed)
    • View dependencies → directed edges (dotted)
  4. Apply transitive reduction to relationship graph
  5. Execute seven-step pipeline
  6. Output: .cocoplus/diagrams/schema-[timestamp].png

Mode: $sketch flow [file]

  1. Read flow.json (default: .cocoplus/flow.json; use [file] if provided)
  2. Map each stage → node (label = stage name, subtitle = persona + model)
  3. Map stage dependencies → directed edges
  4. Mark HITL gates with ⊛ on the connecting edge label
  5. Mark MANDATORY checkpoints with double-border on nodes
  6. Execute seven-step pipeline
  7. Output: .cocoplus/diagrams/flow-[timestamp].png

Mode: $sketch deps [--reduce]

  1. Read .cocoplus/map/coco-map.json structural dependency view
  2. Build node/edge graph from function dependencies
  3. Default (--reduce on): run invoke cocomap/map-reduce <input.json> <reduced.json> before layout
  4. --reduce off: use full transitive closure
  5. Execute seven-step pipeline
  6. Compute and report dependency metrics: node count, edge count before reduction, edge count after reduction, and reduction percentage
  7. Output: .cocoplus/diagrams/deps-[timestamp].png

Mode: $sketch diff <from> <to>

Compare two schema/dependency snapshots, git refs, or diagram metadata files.

Output:

  • Added objects
  • Removed objects
  • Modified relationships
  • Changed policies or roles when that metadata exists

Write .cocoplus/diagrams/diff-[from]-[to]-[timestamp].md and, when draw.io is available, a PNG using the standard seven-step pipeline. If either side cannot be resolved, stop with a clear missing-ref message.

Mode: $sketch view [diagram-path]

Generate a self-contained HTML viewer for a CocoSketch diagram with pan, zoom, filtering, and object metadata. The committed .drawio/PNG remains the source artifact; the viewer is a convenience export written to .cocoplus/diagrams/viewer-[timestamp].html.

For Markdown/HTML/PDF packaging of generated diagram notes, use:

invoke reporting/report-export --source <diagram-report.md> --format <markdown|html|pdf> --out-dir .cocoplus/diagrams/exports

Exit Criteria

  • cocosketch/sketch-validate runs before Step 5 on every invocation; pipeline stops on FAIL
  • cocosketch/sketch-repair runs after Step 7 on every invocation
  • Preview PNG (Step 5) has NO -e flag
  • Final PNG (Step 7) HAS -e flag
  • $sketch deps applies transitive reduction by default; --reduce off skips it
  • $sketch deps reports node count, original edge count, reduced edge count, and reduction percentage
  • Command output includes the final PNG path or fallback .mmd path
  • User style in ~/.cocoplus/sketch-styles/ takes precedence over built-in styles
  • For >15 nodes, cocosketch/sketch-autolayout is called in Step 3
  • Fallback chain (Mermaid → raw XML) executes when draw.io CLI unavailable
  • $sketch diff reports added, removed, modified relationship, and policy/role changes when available
  • $sketch view writes a self-contained HTML viewer without replacing the committed diagram artifact

Anti-Rationalization

Temptation Why Wrong
Skip cocosketch/sketch-validate Invalid XML produces blank or corrupt diagrams without error
Use -e for preview PNG -e truncates IEND; vision APIs reject the PNG
Skip cocosketch/sketch-repair Truncated IEND corrupts the PNG in several common viewers
Generate in one LLM shot without pipeline Single-shot generation produces bad layouts and structural errors
Reuse draw.io binary name without checking Binary name varies by OS and install method — resolve once
Say "diagram generated" without a path Users need the exact artifact path to inspect or attach the diagram