/figure-spec

name: figure-spec
description: "Generate deterministic publication-quality architecture, workflow, and pipeline diagrams from structured JSON (FigureSpec) into editable SVG. Use when user says \"架构图\", \"workflow 图\", \"pipeline 图\", \"确定性矢量图\", \"figure spec\", \"draw architecture\", or needs precise, editable, publication-ready vector diagrams. Preferred over AI illustration for formal architecture/workflow figures."
argument-hint: "[description-of-diagram]"
allowed-tools: Bash(*), Read, Write, Edit, mcp__codex__codex, mcp__antigravity__antigravity, mcp__antigravity__antigravity-reply, mcp__grok__grok, mcp__grok__grok-reply, mcp__claude-review__review, mcp__claude-review__review_reply, mcp__claude-review__review_start, mcp__claude-review__review_reply_start, mcp__claude-review__review_status

FigureSpec: Deterministic JSON → SVG Figure Generation

> **Before each reviewer slot**, follow [Selectable Reviewers](../shared-references/reviewer-backends.md): > resolve invocation → `.aris/reviewer.json` → Claude Code default (Codex MCP) > with `reviewer_route.py` through the canonical helper resolver, preserving this > slot's tier, fresh contexts, source/image inputs and deterministic gates. > Codex examples/pins below apply only to `backend=codex`; other routes use their > own first-call/reply contract. Save the route and actual returned identity; > unavailable selections are `REVIEW_UNAVAILABLE`. Classify acceptance from actual > families/completion/scope. Forward invocation reviewer/model/effort overrides > to reviewer-bearing children. Generation workers are unchanged.

Generate publication-quality **architecture diagrams**, **workflow pipelines**, **audit cascades**, and **system topology** figures as editable SVG vector graphics using a deterministic JSON → SVG renderer.

When to Use This Skill

**Use `figure-spec`** for:

• System architecture diagrams (layered, hub-and-spoke, multi-plane)
• Workflow / pipeline figures
• Audit cascade / flow-control diagrams
• Any structured diagram where node positions, connections, and groupings are semantically important
• Figures that need to be edited/tweaked later (SVG is plain text)
• Figures where determinism matters (same spec → same SVG)

**Do NOT use for:**

• Data plots (bar/line/scatter) — use `/paper-figure`
• Natural/qualitative illustrations — use `/paper-illustration`
• Quick state-machine / flowchart — use `/mermaid-diagram` (lighter syntax)

Core Properties

• **Deterministic**: identical FigureSpec JSON always produces identical SVG output (for a fixed renderer version + fonts)
• **Editable**: SVG output is plain-text, can be post-edited by hand or programmatically
• **Validated**: renderer enforces schema, rejects malformed specs with clear error messages
• **Shape-aware**: edge clipping works correctly for rect/rounded/circle/ellipse/diamond
• **CJK support**: multi-line labels with proper Chinese character width estimation
• **No external API**: runs fully local, no network, no API keys

Tool Location

Phase 3.1 (Arch C) move: the canonical implementation now lives at `skills/figure-spec/scripts/figure_renderer.py` (this SKILL's own `scripts/` subdirectory). A backwards-compatible shim at `tools/figure_renderer.py` forwards to the canonical file via `os.execv`, so existing users with `.aris/tools/figure_renderer.py` or a manually copied `tools/figure_renderer.py` keep working unchanged.

Resolve `$FIGURE_RENDERER` with the hybrid chain (layer 0 prefers the self-contained location for the owning SKILL; layers 1-4 are the shared-runtime chain documented in [`shared-references/integration-contract.md`](../shared-references/integration-contract.md) §2, Policy A — skill-local gate):

# Layer 0: self-contained (CC 1.0+ exposes $CLAUDE_SKILL_DIR).
FIGURE_RENDERER=""
if [ -n "${CLAUDE_SKILL_DIR:-}" ] && [ -f "$CLAUDE_SKILL_DIR/scripts/figure_renderer.py" ]; then
  FIGURE_RENDERER="$CLAUDE_SKILL_DIR/scripts/figure_renderer.py"
fi
# Layers 1-4: shared-runtime chain (legacy compatibility + non-CC hosts).
if [ -z "$FIGURE_RENDERER" ]; then
  cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1
  if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills.txt ]; then
      ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills.txt 2>/dev/null) || true
  fi
  if [ -z "${ARIS_REPO:-}" ] && [ -f "$HOME/.aris/repo" ]; then
      ARIS_REPO=$(cat "$HOME/.aris/repo" 2>/dev/null) || true
  fi
  FIGURE_RENDERER=".aris/tools/figure_renderer.py"
  [ -f "$FIGURE_RENDERER" ] || FIGURE_RENDERER="tools/figure_renderer.py"
  [ -f "$FIGURE_RENDERER" ] || { [ -n "${ARIS_REPO:-}" ] && FIGURE_RENDERER="$ARIS_REPO/tools/figure_renderer.py"; }
  [ -f "$FIGURE_RENDERER" ] || FIGURE_RENDERER=""
fi
[ -z "$FIGURE_RENDERER" ] && {
  echo "ERROR: figure_renderer.py not resolved (layer 0: \$CLAUDE_SKILL_DIR/scripts/; layers 1-4: .aris/tools/, tools/, \$ARIS_REPO/tools/, \$ARIS_REPO/tools/ via ~/.aris/repo)." >&2
  echo "       /figure-spec cannot produce SVG output. Fix: rerun bash tools/install_aris.sh or smart_update.sh (refreshes ~/.aris/repo), or copy the helper from \$ARIS_REPO/skills/figure-spec/scripts/." >&2
  exit 1
}

Invoke:

python3 "$FIGURE_RENDERER" render <spec.json> --output <out.svg>
python3 "$FIGURE_RENDERER" validate <spec.json>
python3 "$FIGURE_RENDERER" schema

Workflow

Step 1: Understand the Diagram Goal

From `$ARGUMENTS` (description or path to `PAPER_PLAN.md` / `NARRATIVE_REPORT.md`), identify:

• **Purpose**: architecture, workflow, pipeline, audit cascade, topology?
• **Main entities**: what are the boxes?
• **Relationships**: how do they connect? (uses, produces, calls, verifies, chains)
• **Grouping**: do entities cluster into named regions?
• **Hierarchy vs network**: stacked layers, left-to-right flow, or central hub?

Step 2: Draft the FigureSpec JSON

Canvas sizing guide:

• Single-column figure: ~500×350 px
• Two-column (full-width): ~900×500 px
• Ta