┌──────────────────────────────────────────────────────────────────────────┐
│                    MULTI-STAGE ITERATIVE WORKFLOW                        │
├──────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│   User Request                                                           │
│       │                                                                  │
│       ▼                                                                  │
│   ┌─────────────┐                                                        │
│   │   Claude    │ ◄─── Step 1: Parse request, create initial prompt     │
│   │  (Planner)  │      - Extract components, labels, and data flow       │
│   │             │      - Write a paper-ready figure brief                │
│   └──────┬──────┘                                                        │
│          │                                                               │
│          ▼                                                               │
│   ┌─────────────┐                                                        │
│   │Claude/Codex │ ◄─── Step 2: Optimize layout description               │
│   │   Layout    │      - Refine component positioning                    │
│   │   Review    │      - Optimize spacing and grouping                   │
│   └──────┬──────┘                                                        │
│          │                                                               │
│          ▼                                                               │
│   ┌─────────────┐                                                        │
│   │Claude/Codex │ ◄─── Step 3: CVPR/NeurIPS style verification           │
│   │   Style     │      - Check palette, arrows, and label standards      │
│   │   Check     │      - Tighten the prompt before rendering             │
│   └──────┬──────┘                                                        │
│          │                                                               │
│          ▼                                                               │
│   ┌─────────────┐                                                        │
│   │ codex-image2│ ◄─── Step 4: Native image generation via bridge        │
│   │ MCP bridge  │      - Call generate_start / generate_status           │
│   │ + app-server│      - Accept only native imageGeneration output       │
│   └──────┬──────┘                                                        │
│          │                                                               │
│          ▼                                                               │
│   ┌─────────────┐                                                        │
│   │   Claude    │ ◄─── Step 5: STRICT visual review + SCORE (1-10)      │
│   │  (Reviewer) │      - Verify logic, labels, arrows, and aesthetics    │
│   │   STRICT!   │      - Reject unclear or non-paper-ready figures       │
│   └──────┬──────┘                                                        │
│          │                                                               │
│          ▼                                                               │
│   Score ≥ 9? ──YES──► Accept & Output                                    │
│          │                                                               │
│          NO                                                              │
│          │                                                               │
│          ▼                                                               │
│   Generate SPECIFIC improvement feedback ──► Loop back to Step 2        │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘

Constants

RENDERER = codex-image2 — Native image generation bridge exposed through local Codex app-server
OPTIONAL_TEXT_CRITIC = mcp__codex__codex — Optional text-only second opinion for layout/style checks
MAX_ITERATIONS = 5 — Maximum refinement rounds
TARGET_SCORE = 9 — Minimum acceptable score (1-10)
OUTPUT_DIR = figures/ai_generated/ — Output directory
TEXT_LANGUAGE = English — Default figure text language unless the user requests otherwise
NATIVE_IMAGE_REQUIREMENT = strict — Accept only native imageGeneration output; reject shell/Python fallbacks

IMAGE2_HELPER — canonical name paper_illustration_image2.py, resolved per shared-references/integration-contract.md §2 (Policy A — skill-local gate). Phase 3.2 (Arch C) moved the canonical implementation into skills/paper-illustration-image2/scripts/; tools/paper_illustration_image2.py remains as an os.execv shim so legacy resolver layers keep working without a re-install. Resolve via:

# Layer 0: self-contained (CC 1.0+ exposes $CLAUDE_SKILL_DIR).
IMAGE2_HELPER=""
if [ -n "${CLAUDE_SKILL_DIR:-}" ] && [ -f "$CLAUDE_SKILL_DIR/scripts/paper_illustration_image2.py" ]; then
  IMAGE2_HELPER="$CLAUDE_SKILL_DIR/scripts/paper_illustration_image2.py"
fi
# Layers 1-3: shared-runtime chain via shim at tools/paper_illustration_image2.py.
if [ -z "$IMAGE2_HELPER" ]; 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
  IMAGE2_HELPER=".aris/tools/paper_illustration_image2.py"
  [ -f "$IMAGE2_HELPER" ] || IMAGE2_HELPER="tools/paper_illustration_image2.py"
  [ -f "$IMAGE2_HELPER" ] || { [ -n "${ARIS_REPO:-}" ] && IMAGE2_HELPER="$ARIS_REPO/tools/paper_illustration_image2.py"; }
  [ -f "$IMAGE2_HELPER" ] || IMAGE2_HELPER=""
fi
[ -z "$IMAGE2_HELPER" ] && {
  echo "ERROR: paper_illustration_image2.py not resolved (layer 0: \$CLAUDE_SKILL_DIR/scripts/; layers 1-3: .aris/tools/, tools/, \$ARIS_REPO/tools/)." >&2
  echo "       /paper-illustration-image2 cannot proceed. Fix: rerun bash tools/install_aris.sh, or copy the canonical script from \$ARIS_REPO/skills/paper-illustration-image2/scripts/." >&2
  exit 1
}

All invocations below use python3 "$IMAGE2_HELPER" <subcommand>.

CVPR/ICLR/NeurIPS Top-Tier Conference Style Guide

What "CVPR Style" Actually Means:

Visual Standards

Clean white background — No decorative patterns or gradients unless extremely subtle
Sans-serif fonts — Arial, Helvetica, or similarly clean paper-friendly typography
Subtle color palette — Use 3-5 coordinated colors, not rainbow colors
Print-friendly — Must remain understandable in grayscale
Professional borders — Thin to medium, clean, and consistent

Layout Standards

Horizontal flow — Left-to-right is the default for pipelines
Clear grouping — Use spacing or subtle grouping boxes for related modules
Consistent sizing — Similar components should have similar sizes
Balanced whitespace — Avoid both cramped and overly sparse layouts

Arrow Standards (MOST CRITICAL)

Thick strokes — Arrows must remain visible after paper scaling
Clear arrowheads — Large, unmistakable arrowheads
Dark colors — Prefer black or dark gray arrows
Labeled — Important arrows should show what flows through them
No crossings — Reorganize the figure to avoid crossings where possible
CORRECT DIRECTION — Arrows must point to the right target

Visual Appeal (Academic Professional Style)

目标：既不保守也不花哨，找到平衡点

✅ Should have

Subtle gradients — Gentle same-family gradients are acceptable
Rounded corners — Modern but restrained rounded blocks
Clear hierarchy — Main modules larger, secondary modules smaller
Consistent color coding — Stable mapping between module types and colors
Professional typography — Clean labels with readable size hierarchy

❌ Avoid

❌ Rainbow gradients
❌ Heavy drop shadows
❌ 3D perspective effects
❌ Glowing effects
❌ Decorative clip-art icons
❌ Slide-deck styling that feels flashy rather than paper-ready

✓ Ideal effect

Looks intentional, professional, and immediately readable
Has moderate visual appeal without becoming decorative
Feels appropriate for a top-tier conference paper figure
Survives PDF scaling and grayscale printing

What to AVOID (CRITICAL)

❌ Thin, hairline arrows
❌ Unlabeled or ambiguous connections
❌ Tiny unreadable text
❌ Flat, boring box soup with no hierarchy
❌ Over-decorated figures with shadows/glows/icons
❌ Wrong arrow directions

Scope

Figure Type	Quality	Examples
Architecture diagrams	Excellent	Model architecture, pipeline, encoder-decoder
Method illustrations	Excellent	Conceptual diagrams, algorithm flowcharts
Conceptual figures	Good	Comparison diagrams, taxonomy trees

Not for: Statistical plots (use /paper-figure), deterministic vector topology figures (prefer /figure-spec), photo-realistic scenes

Workflow: MUST EXECUTE ALL STEPS

Step 0: Pre-flight Check

Render this checklist explicitly before starting:

📋 paper-illustration-image2 integration checklist:
   [ ] 1. python3 "$IMAGE2_HELPER" preflight --workspace <cwd> --json-out figures/ai_generated/preflight.json
   [ ] 2. Confirm preflight JSON says ok=true before rendering
   [ ] 3. Render via mcp__codex-image2__generate_start + generate_status
   [ ] 4. Finalize via python3 "$IMAGE2_HELPER" finalize --workspace <cwd> --best-image <best_png>
   [ ] 5. Verify artifacts via python3 "$IMAGE2_HELPER" verify --workspace <cwd> --json-out figures/ai_generated/verify.json

Create figures/ai_generated/ if it does not exist.
Confirm the request is suitable for a raster illustration:
- architecture diagram
- conceptual method figure
- workflow illustration
Prefer English figure text unless the user asked otherwise.
Run:

python3 "$IMAGE2_HELPER" preflight \
  --workspace <cwd> \
  --json-out figures/ai_generated/preflight.json

If preflight is not ok=true, stop and say so clearly.

Step 1: Claude Plans the Figure

Turn the user request into a fully specified image prompt. Include:

figure type
exact modules / stages
flow direction
labels to show
data-flow arrows
style constraints
what to avoid

When the input is a method note or a paper section, summarize it first into a clean figure brief before writing the final image prompt.

Step 2: Layout Optimization

This step is required. Before rendering, refine the prompt into a concrete layout plan:

exact module order
spacing and grouping
relative module prominence
arrow routing and likely collision points

If mcp__codex__codex is available, you may ask it for a short second-opinion layout critique here, but Claude should still complete this step even without Codex.

Use Codex layout critique for:

missing components
confusing layout
weak flow hierarchy
likely arrow-direction ambiguity or clutter

Step 3: Style Verification

This step is also required. Check the prompt against the intended paper style before rendering:

palette is restrained and academic
arrows are thick, dark, and readable
labels are concise and in English unless requested otherwise
the figure will read clearly in grayscale / print
no glow, rainbow gradient, or slide-deck decoration slips in

If mcp__codex__codex is available, you may ask it for a short text-only style audit, but do not block on it.

Step 4: Generate Through the Bridge

Call mcp__codex-image2__generate_start with:

prompt: the final image prompt
cwd: current project root or paper workspace
outputPath: figures/ai_generated/figure_v1.png
system: a short instruction like Academic paper figure. Prefer crisp English labels.
timeoutSeconds: a bounded render timeout such as 180

Then call mcp__codex-image2__generate_status with bounded waits until:

done=true and status=completed, or
done=true and status=failed

If generation fails, report the bridge error directly instead of hiding it.

Step 5: Review the Output

Review the generated image with a strict checklist:

are all major components present?
is the logical flow obvious?
are labels readable?
do arrows point the right way?
does the figure look paper-ready rather than like a slide?

Score it from 1-10.

Step 6: Refine if Needed

If score < 9, write a targeted refinement prompt:

say exactly what was wrong
say what to preserve
regenerate to figure_v2.png, figure_v3.png, etc.

Keep refinement feedback concrete:

Increase spacing between genome scan and scoring modules
Make the off-target branch thinner and secondary
Use cleaner English labels: "Candidate sgRNA library", not "sgRNA library 23 bp"

Step 7: Finalize And Verify

When accepted:

run the canonical helper to promote the best image to figure_final.png
let the helper write latex_include.tex
let the helper write review_log.json
run helper verification before claiming success

python3 "$IMAGE2_HELPER" finalize \
  --workspace <cwd> \
  --best-image figures/ai_generated/figure_vN.png \
  --score 9 \
  --review-summary "Accepted after strict review; labels and arrows are paper-ready."

python3 "$IMAGE2_HELPER" verify \
  --workspace <cwd> \
  --json-out figures/ai_generated/verify.json

Suggested LaTeX:

\begin{figure*}[t]
    \centering
    \includegraphics[width=0.95\textwidth]{figures/ai_generated/figure_final.png}
    \caption{[Replace with a paper-ready caption].}
    \label{fig:[replace-me]}
\end{figure*}

Key Rules

Never skip Step 2 or Step 3; layout and style checks are required.
Never skip the final visual review.
Never accept a figure that is logically wrong just because it looks attractive.
Use the codex-image2 bridge only for native image generation.
If the bridge says native image generation is unavailable, surface that honestly.
Reject any shell/Python/manual bitmap fallback masquerading as image generation.
Keep figure text in English unless the user requested another language.
Prefer 1-3 strong refinement rounds over many shallow ones.
Use specific, actionable refinement feedback instead of vague comments.
Review arrow direction, label clarity, and visual hierarchy every round.
Accept only figures that look paper-ready, not slide-ready.
Always use tools/paper_illustration_image2.py finalize to emit the final artifacts.
Always use tools/paper_illustration_image2.py verify before claiming success.

Repair Path

If rendering succeeded but final artifacts were skipped, repair the integration explicitly:

python3 "$IMAGE2_HELPER" finalize \
  --workspace <cwd> \
  --best-image figures/ai_generated/figure_vN.png

python3 "$IMAGE2_HELPER" verify \
  --workspace <cwd> \
  --json-out figures/ai_generated/verify.json

Output Structure

figures/ai_generated/
├── preflight.json         # Helper preflight receipt
├── figure_v1.png          # Iteration 1
├── figure_v2.png          # Iteration 2
├── figure_v3.png          # Iteration 3
├── figure_final.png       # Accepted version (copy of best, score ≥ 9)
├── latex_include.tex      # LaTeX snippet
├── review_log.json        # Review notes and refinement history
└── verify.json            # Helper verification diagnostic

Model Summary

Stage	Agent / Tool	Purpose
Step 0	`python3 "$IMAGE2_HELPER" preflight`	Observable activation predicate and preflight receipt
Step 1	Claude	Parse request and create the initial figure prompt
Step 2	Claude (+ optional Codex critique)	Refine layout, grouping, spacing, and arrow routing
Step 3	Claude (+ optional Codex critique)	Verify academic visual style before rendering
Step 4	`mcp__codex-image2__generate_start` + `generate_status`	Native raster image generation through Codex app-server
Step 5	Claude	Strict visual review and scoring
Step 7	`python3 "$IMAGE2_HELPER" finalize` + `verify`	Emit canonical artifacts and external verification receipt

paper-illustration-image2

Paper Illustration Image2

Core Design Philosophy