tikz-draw

name	tikz-draw
description	Use when the user asks to draw, refactor, extract, compile, or review a TikZ/PGF figure, especially structural diagrams such as flowcharts, DAGs, trees, commutative diagrams, finite graphs, automata, or research-derived summary figures. Prefer this skill when the output should follow a structure-first workflow like figure brief to spec to render to check to compile to review, and when document-facing output should use adjustbox width fitting.
metadata	{"short-description":"Draw and refine structural TikZ figures"}

TikZ Draw

Windows Runtime Commands

On native Windows, use the managed Windows runner and the native runtime command target. Set $runtime to the installed runtime root. Multi-agent installs usually use %LOCALAPPDATA%\ai-agents-skills\runtime. Then run:

$runtime = if ($env:AAS_RUNTIME_ROOT) { $env:AAS_RUNTIME_ROOT } else { "$env:LOCALAPPDATA\ai-agents-skills\runtime" }
& "$runtime\run_skill.ps1" "skills/tikz-draw/tikz_draw.py" <args>

POSIX examples below use run_skill.sh and .sh command targets; use the Windows command target above on native Windows.

Use this skill when the task is specifically about producing or repairing TikZ.

Typical cases:

• draw a new TikZ picture to illustrate a statement or research finding
• turn a figure-brief.json into a structural diagram spec first
• refactor coordinate-heavy TikZ into structural placement
• extract an existing tikzpicture, forest, or tikzcd block into standalone and embeddable artifacts
• run a deterministic compile and review loop on TikZ output

Runtime helper

The runtime helper exposes one stable verb set:

• doctor
• contract
• design
• spec
• render
• force-check
• check
• compile
• review-visual
• verify-design
• verify-semantic
• approve
• review
• extract

Run it through the shared runtime wrapper:

bash "${AAS_RUNTIME_ROOT:-$HOME/.local/share/ai-agents-skills/runtime}/run_skill.sh" \
  skills/tikz-draw/run_tikz_draw.sh doctor

On Windows, use:

$runtime = if ($env:AAS_RUNTIME_ROOT) { $env:AAS_RUNTIME_ROOT } else { "$env:LOCALAPPDATA\ai-agents-skills\runtime" }
& "$runtime\run_skill.ps1" `
  "skills/tikz-draw/tikz_draw.py" doctor

bash "${AAS_RUNTIME_ROOT:-$HOME/.local/share/ai-agents-skills/runtime}/run_skill.sh" \
  skills/tikz-draw/run_tikz_draw.sh render \
  --brief /abs/path/to/figure-brief.json

Direct bootstrap without prewriting a brief:

bash "${AAS_RUNTIME_ROOT:-$HOME/.local/share/ai-agents-skills/runtime}/run_skill.sh" \
  skills/tikz-draw/run_tikz_draw.sh render \
  --request "Draw a validation pipeline for statement X"

render is structurally guarded: after writing the brief/spec/Tex/manifest it automatically runs the forced overlap/symmetry loop. The command returns success only when there are no rendered-overlap findings and the declared symmetry_contract passes. If issues remain, it repairs layout-only geometry and reruns the check until one of the forced-loop stop conditions fires.

If --out-dir is omitted in direct mode, the helper allocates:

• a target-specific run directory for direct Codex installs
• ${AAS_RUNS_ROOT:-~/.local/share/ai-agents-skills/runs}/tikz-draw/<run_id>/ for shared runtime installs

For research or mathematical figures, first let the runtime write the intent contract or provide one explicitly:

bash "${AAS_RUNTIME_ROOT:-$HOME/.local/share/ai-agents-skills/runtime}/run_skill.sh" \
  skills/tikz-draw/run_tikz_draw.sh contract \
  --out /abs/path/to/F1.figure-contract.json \
  --request "Draw a graph hardness reduction where an edge is replaced by a gadget"

The contract records the inferred figure family, required objects, required relations, forbidden simplifications, notation that must be preserved, and the approval criteria. spec and render enforce this contract. If a request says to illustrate a graph hardness reduction, the contract must require graph vertices and graph edges; a box-only flowchart is a contract violation.

Required workflow

1. Establish the semantic intent contract before raw TikZ. Direct mode may infer and write the contract for you, but it must still be present in the generated brief and spec.
2. For manuscript-facing semantic figures, establish a semantic design checkpoint before drawing or editing visual marks. This is mandatory for graph/proof/reduction figures, extracted figures intended for semantic approval, and any figure whose boxes, fills, regions, callouts, labels, or correspondence marks carry mathematical meaning. The checkpoint records the inspected source/caption/prose, affected visual marks, intended role of each mark, alternatives considered, chosen encoding, and caption/prose alignment.
3. Route the figure to the right backend:
   • flowchart, dag: positioning
   • tree: forest
   • commutative: tikz-cd
   • graph: baseline graph path first, with Sage-assisted routing when the request exceeds the baseline shorthand/layout surface
4. Reject a requested or inferred backend family that contradicts the contract. Do not downgrade a graph request into a schematic diagram unless the contract explicitly says that a schematic is intended.
5. Keep document-facing output inside the adjustbox environment with max width=\textwidth.
6. For standalone compile targets, use plain \documentclass[border=...]{standalone} rather than standalone[tikz].
7. After creating, extracting, refactoring, or modifying any TikZ figure, run the forced structural loop (render does this automatically for generated figures; use force-check for existing artifacts). Then run the strict approval gate before saying the figure is done, fixed, ready, passed, verified, or approved.

Forced structural loop:

bash "${AAS_RUNTIME_ROOT:-$HOME/.local/share/ai-agents-skills/runtime}/run_skill.sh" \
  skills/tikz-draw/run_tikz_draw.sh force-check \
  --artifacts /abs/path/to/F1.artifacts.json \
  --work-dir /abs/path/to/work-dir

The loop is not optional for generated figures. It may stop only when one of these conditions is true:

• issue_free_no_overlap_and_no_symmetry_failures: rendered overlap findings are gone and symmetry_status=PASS.
• credit_budget_exhausted: the repair/checking credit budget is exhausted or the required checking resources are unavailable.
• user_stop_requested: the user explicitly asks to stop, represented locally by TIKZ_DRAW_FORCE_STOP, tikz-draw-force-stop, or STOP_TIKZ_DRAW in the work directory, or by the TIKZ_DRAW_FORCE_STOP environment variable.

The loop repairs layout-only geometry: spacing, node dimensions, label anchoring, and absolute-position symmetry alignment. It must not change node labels, edge endpoints, graph meaning, captions, or semantic contracts to make a broken figure appear correct.

Strict approval command:

bash "${AAS_RUNTIME_ROOT:-$HOME/.local/share/ai-agents-skills/runtime}/run_skill.sh" \
  skills/tikz-draw/run_tikz_draw.sh approve \
  --artifacts /abs/path/to/F1.artifacts.json \
  --work-dir /abs/path/to/work-dir

On native Windows, use the same verb through run_skill.ps1 and tikz_draw.py.

The only final approval is approve exiting 0 with:

• final_verdict=APPROVED
• overlap_status=PASS
• design_status=PASS for scoped semantic figures, or design_status=SKIPPED when the design gate is out of scope
• symmetry_status=PASS

render, force-check, extract, compile, check, review --tex, review-visual, and verify-semantic are structural/preflight or artifact commands. Never cite them as final approval. Source inspection, compile success, screenshot review, PDF preview, or human visual inspection alone never constitute final approval.

If approve fails, fix the reported issue and rerun approve. Repeat until it passes, or report the exact blocked state such as BLOCKED_INPUT, BLOCKED_ENVIRONMENT, or UNSUPPORTED_FAMILY. Do not use approval-style wording for blocked or unsupported states.

Graph routing

• The current graph lane keeps a trusted baseline path for already-supported requests such as Petersen and J(n,k).
• Richer graph requests may route to a Sage-assisted path.
• In the current slice, both paths may still use Sage for graph realization; the difference is in request routing, validation, and reporting.
• For direct graph bootstrap, the helper now accepts optional graph fields such as:
  • --graph-mode auto|local|sage
  • --graph-constructor
  • --graph-param
  • --graph-layout
  • --show-labels true|false
• Render manifests and semantic-review reports now carry routing fields including baseline vs Sage-assisted path selection and backend used.

Strict Approval Surface

• approve is the authoritative final gate for supported render-generated figures.
• review --semantic delegates to the strict approval path for compatibility.
• review --tex remains source-only preflight and must not be treated as approval.
• render runs the forced structural loop by default before returning.
• force-check reruns the same forced structural loop for existing artifacts.
• review-visual runs through the rendered-artifact extractor and refreshes render-semantics.json from the compiled PDF, but remains a component gate.
• verify-design checks the visual-semantic design layer for scoped figures: mark roles, graph-object vs metadata separation, region/fill semantics, label/callout ownership, and declared caption/prose claim bindings.
• verify-semantic now supports the current render-generated flowchart, dag, tree, supported-square commutative, and Sage-backed graph families.
• verify-semantic still fails closed with UNSUPPORTED_FAMILY for an unsupported family and unsupported inputs outside the current renderer assumptions.
• Strict approval is fail-closed for unsupported families, arbitrary extracted TikZ without a semantic target/spec, stale extracted sources, missing dependencies, missing render artifacts, failed overlap checks, and missing or failed symmetry contracts.
• Strict approval also fails closed when a generated spec is missing its semantic intent contract or contradicts it.
• Strict approval also fails closed when a scoped semantic figure is missing a required visual-semantic design contract or when verify-design reports role, metadata, region, label, correspondence, or caption/prose mismatches.

For semantic design, visual marks are not decorative by default. A box, fill, outline, color, arrow, brace, callout, label, or region must have a declared role such as graph object, annotation, callout, correspondence, gadget region, highlight region, or legend. Metadata such as list constraints should default to adjacent text or callouts, not graph-object styling. If the user correction shows that a previous design assumption was wrong, reopen the design checkpoint before editing again.

Every generated spec carries a symmetry_contract. The checker verifies the declared contract:

• required: declared pair/axis/alignment symmetry must pass.
• not_required: accepted only with a justification.
• intentionally_asymmetric: accepted only with a justification.

Comments such as % Symmetry: ... are human hints only; they do not satisfy the machine-readable contract.

Regression runner

For implementation-level verification, use the persistent regression suite instead of ad hoc /tmp smokes:

python3 $AAS_RUNTIME_WORKSPACE/skills/tikz-draw/semantic_regression_runner.py --platform both --strict-approval

The current suite covers supported good cases for flowchart, dag, tree, commutative, and Sage-backed graph, plus mutation cases and intent-contract cases that guard against graph-hardness requests becoming flowcharts.

On Windows, use:

$runtime = if ($env:AAS_RUNTIME_ROOT) { $env:AAS_RUNTIME_ROOT } else { "$env:LOCALAPPDATA\ai-agents-skills\runtime" }
& "$runtime\run_python.ps1" `
  "skills/tikz-draw/semantic_regression_runner.py" --platform codex

References

Read these when the task needs tighter guardrails:

• backend-routing.md
• quality-gates.md
• tikz-prevention.md
• tikz-measurement.md

Boundaries

• Use this skill for TikZ-specific work, not for generic image generation.
• Keep the workflow narrow and structural in phase 1.
• Preserve figure_id and source_ids when the request came from deep research.
• Direct-use bootstrap may emit an empty source_ids list; research-driven briefs should keep real S* ids.

Recommended templates

When this skill is involved, consider this workflow template (install via the workflow-templates artifact profile, or --with-deps to pull backing skills):

• tikz-figure-verification-runbook -- Bounded draw-compile-verify-redraw loop for a TikZ figure that guarantees it is free of overlap, wrong meaning, and bad layout, with Sage-assisted graph realization and fresh-agent visual confirmation before the strict approval gate.