1# Detailed Workflow Procedures
2 
3## Step 1: Pre-check
4 
5### 1.0 Detect & Save Reference Images ⚠️ REQUIRED if images provided
6 
7Check if user provided reference images. Handle based on input type:
8 
9| Input Type | Action |
10|------------|--------|
11| Image file path provided | Copy to `references/` subdirectory → can use `--ref` |
12| Image in conversation (no path) | **ASK user for file path** with AskUserQuestion |
13| User can't provide path | Extract style/palette verbally → append to prompts (NO frontmatter references) |
14 
15**CRITICAL**: Only add `references` to prompt frontmatter if files are ACTUALLY SAVED to `references/` directory.
16 
17**If user provides file path**:
181. Copy to `references/NN-ref-{slug}.png`
192. Create description: `references/NN-ref-{slug}.md`
203. Verify files exist before proceeding
21 
22**If user can't provide path** (extracted verbally):
231. Analyze image visually, extract: colors, style, composition
242. Create `references/extracted-style.md` with extracted info
253. DO NOT add `references` to prompt frontmatter
264. Instead, append extracted style/colors directly to prompt text
27 
28**Description File Format** (only when file saved):
29```yaml
30---
31ref_id: NN
32filename: NN-ref-{slug}.png
33---
34[User's description or auto-generated description]
35```
36 
37**Verification** (only for saved files):
38```
39Reference Images Saved:
40- 01-ref-{slug}.png ✓ (can use --ref)
41- 02-ref-{slug}.png ✓ (can use --ref)
42```
43 
44**Or for extracted style**:
45```
46Reference Style Extracted (no file):
47- Colors: #E8756D coral, #7ECFC0 mint...
48- Style: minimal flat vector, clean lines...
49→ Will append to prompt text (not --ref)
50```
51 
52---
53 
54### 1.1 Determine Input Type
55 
56| Input | Output Directory | Next |
57|-------|------------------|------|
58| File path | EXTEND.md `default_output_dir` (default: `imgs-subdir`). If not configured, confirm in 1.2. | → 1.2 |
59| Pasted content | `illustrations/{topic-slug}/` | → 1.4 |
60 
61**Backup rule for pasted content**: If `source.md` exists in target directory, rename to `source-backup-YYYYMMDD-HHMMSS.md` before saving.
62 
63### 1.2-1.4 Configuration (file path input only)
64 
65Check preferences and existing state, then ask ALL needed questions in ONE AskUserQuestion call (max 4 questions).
66 
67**Questions to include** (skip if preference exists or not applicable):
68 
69| Question | When to Ask | Options |
70|----------|-------------|---------|
71| Output directory | No `default_output_dir` in EXTEND.md | `{article-dir}/imgs/` (Recommended), `{article-dir}/`, `{article-dir}/illustrations/`, `illustrations/{topic-slug}/` |
72| Existing images | Target dir has `.png/.jpg/.webp` files | `supplement`, `overwrite`, `regenerate` |
73| Article update | Always (file path input) | `update`, `copy` |
74 
75**Preference Values** (if configured, skip asking):
76 
77| `default_output_dir` | Path |
78|----------------------|------|
79| `same-dir` | `{article-dir}/` |
80| `imgs-subdir` | `{article-dir}/imgs/` |
81| `illustrations-subdir` | `{article-dir}/illustrations/` |
82| `independent` | `illustrations/{topic-slug}/` |
83 
84### 1.5 Load Preferences (EXTEND.md) ⛔ BLOCKING
85 
86**CRITICAL**: If EXTEND.md not found, MUST complete first-time setup before ANY other questions or steps. Do NOT proceed to reference images, do NOT ask about content, do NOT ask about type/style — ONLY complete the preferences setup first.
87 
88```bash
89# macOS, Linux, WSL, Git Bash
90test -f .baoyu-skills/baoyu-article-illustrator/EXTEND.md && echo "project"
91test -f "${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-article-illustrator/EXTEND.md" && echo "xdg"
92test -f "$HOME/.baoyu-skills/baoyu-article-illustrator/EXTEND.md" && echo "user"
93```
94 
95```powershell
96# PowerShell (Windows)
97if (Test-Path .baoyu-skills/baoyu-article-illustrator/EXTEND.md) { "project" }
98$xdg = if ($env:XDG_CONFIG_HOME) { $env:XDG_CONFIG_HOME } else { "$HOME/.config" }
99if (Test-Path "$xdg/baoyu-skills/baoyu-article-illustrator/EXTEND.md") { "xdg" }
100if (Test-Path "$HOME/.baoyu-skills/baoyu-article-illustrator/EXTEND.md") { "user" }
101```
102 
103| Result | Action |
104|--------|--------|
105| Found | Read, parse, display summary → Continue |
106| Not found | ⛔ **BLOCKING**: Run first-time setup ONLY ([config/first-time-setup.md](config/first-time-setup.md)) → Complete and save EXTEND.md → Then continue |
107 
108**Supports**: Watermark | Preferred type/style | Custom styles | Language | Output directory
109 
110---
111 
112## Step 2: Setup & Analyze
113 
114### 2.1 Analyze Content
115 
116| Analysis | Description |
117|----------|-------------|
118| Content type | Technical / Tutorial / Methodology / Narrative |
119| Illustration purpose | information / visualization / imagination |
120| Core arguments | 2-5 main points to visualize |
121| Visual opportunities | Positions where illustrations add value |
122| Recommended type | Based on content signals and purpose |
123| Recommended density | Based on length and complexity |
124 
125### 2.2 Extract Core Arguments
126 
127- Main thesis
128- Key concepts reader needs
129- Comparisons/contrasts
130- Framework/model proposed
131 
132**CRITICAL**: If article uses metaphors (e.g., "电锯切西瓜"), do NOT illustrate literally. Visualize the **underlying concept**.
133 
134### 2.3 Identify Positions
135 
136**Illustrate**:
137- Core arguments (REQUIRED)
138- Abstract concepts
139- Data comparisons
140- Processes, workflows
141 
142**Do NOT Illustrate**:
143- Metaphors literally
144- Decorative scenes
145- Generic illustrations
146 
147### 2.4 Analyze Reference Images (if provided in Step 1.0)
148 
149For each reference image:
150 
151| Analysis | Description |
152|----------|-------------|
153| Visual characteristics | Style, colors, composition |
154| Content/subject | What the reference depicts |
155| Suitable positions | Which sections match this reference |
156| Style match | Which illustration types/styles align |
157| Usage recommendation | `direct` / `style` / `palette` |
158 
159| Usage | When to Use |
160|-------|-------------|
161| `direct` | Reference matches desired output closely |
162| `style` | Extract visual style characteristics only |
163| `palette` | Extract color scheme only |
164 
165---
166 
167## Step 3: Confirm Settings ⚠️
168 
169**Do NOT skip.** Use ONE AskUserQuestion call with max 4 questions. **Q1, Q2, Q3 are ALL REQUIRED.**
170 
171### Q1: Preset or Type ⚠️ REQUIRED
172 
173Based on Step 2 content analysis, recommend a preset first (sets both type & style). Look up [style-presets.md](style-presets.md) "Content Type → Preset Recommendations" table.
174 
175- [Recommended preset] — [brief: type + style + why] (Recommended)
176- [Alternative preset] — [brief]
177- Or choose type manually: infographic / scene / flowchart / comparison / framework / timeline / mixed
178 
179**Default**: if Step 2 found no strong content signal, the recommended preset MUST be `hand-drawn-edu` (infographic + sketch-notes + macaron — warm cream paper, black hand-drawn lines, soft pastel blocks). This is the universal fallback.
180 
181**If user picks a preset → skip Q3** (type & style both resolved).
182**If user picks a type → Q3 is REQUIRED.**
183 
184### Q2: Density ⚠️ REQUIRED - DO NOT SKIP
185- minimal (1-2) - Core concepts only
186- balanced (3-5) - Major sections
187- per-section - At least 1 per section/chapter (Recommended)
188- rich (6+) - Comprehensive coverage
189 
190### Q3: Style ⚠️ REQUIRED (skip if preset chosen in Q1)
191 
192If EXTEND.md has `preferred_style`:
193- [Custom style name + brief description] (Recommended)
194- [Top compatible core style 1]
195- [Top compatible core style 2]
196- Other (see full Style Gallery)
197 
198If no `preferred_style` (present Core Styles first):
199- [Best compatible core style] (Recommended)
200- [Other compatible core style 1]
201- [Other compatible core style 2]
202- Other (see full Style Gallery)
203 
204**Core Styles** (simplified selection):
205 
206| Core Style | Maps To | Best For |
207|------------|---------|----------|
208| `hand-drawn` | sketch-notes | **Default.** Warm cream paper, black hand-drawn lines, pastel blocks — educational infographics, concept explainers, onboarding, general knowledge articles |
209| `minimal-flat` | notion | General, knowledge sharing, SaaS |
210| `sci-fi` | blueprint | AI, frontier tech, system design |
211| `editorial` | editorial | Processes, data, journalism |
212| `scene` | warm/watercolor | Narratives, emotional, lifestyle |
213| `poster` | screen-print | Opinion, editorial, cultural, cinematic |
214 
215**Default recommendation**: when Step 2 surfaces no strong content signal, recommend **`hand-drawn-edu`** preset (→ infographic + sketch-notes + macaron) as the primary option in Q1. When the user picks a type manually without a preferred_style, recommend `sketch-notes` first in Q3.
216 
217Style selection based on Type × Style compatibility matrix (styles.md).
218**In Step 5.1**, read `styles/<style>.md` for visual elements and rendering rules.
219 
220### Q4: Palette (optional)
221 
222If preset did not specify a palette, and the user may benefit from a palette override, offer available palettes:
223 
224- Default (use style's built-in colors) (Recommended)
225- `macaron` — soft pastel blocks on warm cream
226- `warm` — warm earth tones, no cool colors
227- `neon` — vibrant neon on dark backgrounds
228 
229**Skip if**: preset already resolved palette, or `preferred_palette` set in EXTEND.md.
230 
231See Palette Gallery in [styles.md](styles.md#palette-gallery) and full specs in `palettes/<palette>.md`.
232 
233### Q5: Image Text Language ⚠️ REQUIRED when article language ≠ EXTEND.md `language`
234 
235Detect article language from content. If different from EXTEND.md `language` setting, MUST ask:
236- Article language (match article content) (Recommended)
237- EXTEND.md language (user's general preference)
238 
239**Skip only if**: Article language matches EXTEND.md `language`, or EXTEND.md has no `language` setting.
240 
241### Display Reference Usage (if references detected in Step 1.0)
242 
243When presenting outline preview to user, show reference assignments:
244 
245```
246Reference Images:
247| Ref | Filename | Recommended Usage |
248|-----|----------|-------------------|
249| 01 | 01-ref-diagram.png | direct → Illustration 1, 3 |
250| 02 | 02-ref-chart.png | palette → Illustration 2 |
251```
252 
253---
254 
255## Step 4: Generate Outline
256 
257Save as `{output-dir}/outline.md` (all paths below are relative to the output directory determined in Step 1.1/1.2):
258 
259```yaml
260---
261type: infographic
262density: balanced
263style: blueprint
264image_count: 4
265references:                    # Only if references provided
266  - ref_id: 01
267    filename: 01-ref-diagram.png
268    description: "Technical diagram showing system architecture"
269  - ref_id: 02
270    filename: 02-ref-chart.png
271    description: "Color chart with brand palette"
272---
273 
274## Illustration 1
275 
276**Position**: [section] / [paragraph]
277**Purpose**: [why this helps]
278**Visual Content**: [what to show]
279**Type Application**: [how type applies]
280**References**: [01]                    # Optional: list ref_ids used
281**Reference Usage**: direct             # direct | style | palette
282**Filename**: 01-infographic-concept-name.png
283 
284## Illustration 2
285...
286```
287 
288**Requirements**:
289- Each position justified by content needs
290- Type applied consistently
291- Style reflected in descriptions
292- Count matches density
293- References assigned based on Step 2.4 analysis
294 
295---
296 
297## Step 5: Generate Images
298 
299### 5.1 Create Prompts ⛔ BLOCKING
300 
301**Every illustration MUST have a saved prompt file before generation begins. DO NOT skip this step.**
302 
303For each illustration in the outline:
304 
3051. **Create prompt file**: `{output-dir}/prompts/NN-{type}-{slug}.md`
3062. **Include YAML frontmatter**:
307   ```yaml
308   ---
309   illustration_id: 01
310   type: infographic
311   style: custom-flat-vector
312   ---
313   ```
3143. **Load style specs**: Read `styles/<style>.md` for visual elements, style rules, and rendering instructions
3154. **Load palette specs** (if palette specified): Read `palettes/<palette>.md` for colors and background. Palette colors **replace** the style's default Color Palette. If no palette specified, use the style's built-in colors.
3165. **Follow type-specific template** from [prompt-construction.md](prompt-construction.md), using rendering from style + colors from palette (or style default)
3176. **Prompt quality requirements** (all REQUIRED):
318   - `Layout`: Describe overall composition (grid / radial / hierarchical / left-right / top-down)
319   - `ZONES`: Describe each visual area with specific content, not vague descriptions
320   - `LABELS`: Use **actual numbers, terms, metrics, quotes from the article** — NOT generic placeholders
321   - `COLORS`: Specify hex codes from palette (or style default) with semantic meaning
322   - `STYLE`: Describe line treatment, texture, mood, character rendering per style rules
323   - `ASPECT`: Specify ratio (e.g., `16:9`)
3247. **Apply defaults**: composition requirements, character rendering, text guidelines, watermark
3258. **Backup rule**: If prompt file exists, rename to `prompts/NN-{type}-{slug}-backup-YYYYMMDD-HHMMSS.md`
326 
327**Verification** ⛔: Before proceeding to 5.2, confirm ALL prompt files exist:
328```
329Prompt Files:
330- prompts/01-infographic-overview.md ✓
331- prompts/02-infographic-distillation.md ✓
332...
333```
334 
335**DO NOT** pass ad-hoc inline text to `--prompt` without first saving prompt files. The generation command should either use `--promptfiles prompts/NN-{type}-{slug}.md` or read the saved file content for `--prompt`.
336 
337**Execution choice**:
338- If multiple illustrations already have saved prompt files and the task is now plain generation, use batch generation by default.
339- Prefer the chosen backend's native batch / multi-task interface when available.
340- If the backend has no native batch interface but the runtime can issue parallel tool calls, dispatch up to `generation_batch_size` tasks at a time. Default: `4`. The current user request overrides EXTEND.md.
341- Generate sequentially only when neither backend batch nor runtime parallel calls are available.
342- Use subagents only when each illustration still needs separate prompt rewriting, style exploration, or other per-image reasoning before generation. Do not use subagents just to parallelize rendering.
343 
344**CRITICAL - References in Frontmatter**:
345- Only add `references` field if files ACTUALLY EXIST in `references/` directory
346- If style/palette was extracted verbally (no file), append info to prompt BODY instead
347- Before writing frontmatter, verify: `test -f references/NN-ref-{slug}.png`
348 
349### 5.2 Select Generation Skill
350 
351Follow the `## Image Generation Tools` rule at the top of `SKILL.md`. Concretely:
352 
353- If `imagegen` is in your available-skills list (Codex), use it — invoke via the `Skill` tool with `skill: "imagegen"`.
354- Else if the EXTEND.md pin is available, use it.
355- Else if exactly one non-native backend is installed, use it.
356- Else, ask the user.
357 
358**Do not generate SVG, HTML, or any code-based vector as a substitute for the raster image.** If no raster backend can be resolved, ask the user how to proceed.
359 
360### 5.3 Process References ⚠️ REQUIRED if references saved in Step 1.0
361 
362**DO NOT SKIP if user provided reference images.** For each illustration with references:
363 
3641. **VERIFY files exist first**:
365   ```bash
366   test -f references/NN-ref-{slug}.png && echo "exists" || echo "MISSING"
367   ```
368   - If file MISSING but in frontmatter → ERROR, fix frontmatter or remove references field
369   - If file exists → proceed with processing
370 
3712. Read prompt frontmatter for reference info
3723. Process based on usage type:
373 
374| Usage | Action | Example |
375|-------|--------|---------|
376| `direct` | Add reference path to `--ref` parameter | `--ref references/01-ref-brand.png` |
377| `style` | Analyze reference, append style traits to prompt | "Style: clean lines, gradient backgrounds..." |
378| `palette` | Extract colors from reference, append to prompt | "Colors: #E8756D coral, #7ECFC0 mint..." |
379 
3804. Check image generation skill capability:
381 
382| Skill Supports `--ref` | Action |
383|------------------------|--------|
384| Yes (e.g., baoyu-image-gen with Google) | Pass reference images via `--ref` |
385| No | Convert to text description, append to prompt |
386 
387**Verification**: Before generating, confirm reference processing:
388```
389Reference Processing:
390- Illustration 1: using 01-ref-brand.png (direct) ✓
391- Illustration 2: extracted palette from 02-ref-style.png ✓
392```
393 
394### 5.4 Apply Watermark (if enabled)
395 
396Add: `Include a subtle watermark "[content]" at [position].`
397 
398### 5.5 Generate
399 
4001. Build a generation task list from saved prompt files:
401   - `prompt_file`: `{output-dir}/prompts/NN-{type}-{slug}.md`
402   - `output_file`: `{output-dir}/NN-{type}-{slug}.png`
403   - `aspect_ratio`: from prompt frontmatter or prompt body
404   - `refs`: only verified `direct` references from prompt frontmatter
4052. **Backup rule**: Before dispatching a task, if its output image already exists, rename it to `NN-{type}-{slug}-backup-YYYYMMDD-HHMMSS.{ext}`.
4063. Dispatch tasks in batches:
407   - Native batch backend: send all eligible tasks, or chunks of `generation_batch_size` if the backend has a practical limit.
408   - Runtime parallel calls: issue up to `generation_batch_size` image calls concurrently, then continue with the next chunk.
409   - Sequential fallback: process one task at a time.
4104. After each completed task, record: "Generated X/N: filename".
4115. On failure: retry the failed task once from the same saved prompt file. Keep successful outputs and continue.
412 
413---
414 
415## Step 6: Finalize
416 
417### 6.1 Update Article
418 
419Insert after corresponding paragraph, using path relative to article file:
420 
421| `default_output_dir` | Insert Path |
422|----------------------|-------------|
423| `imgs-subdir` | `![description](imgs/NN-{type}-{slug}.png)` |
424| `same-dir` | `![description](NN-{type}-{slug}.png)` |
425| `illustrations-subdir` | `![description](illustrations/NN-{type}-{slug}.png)` |
426| `independent` | `![description](illustrations/{topic-slug}/NN-{type}-{slug}.png)` (relative to cwd) |
427 
428Alt text: concise description in article's language.
429 
430### 6.2 Output Summary
431 
432```
433Article Illustration Complete!
434 
435Article: [path]
436Type: [type] | Density: [level] | Style: [style]
437Location: [directory]
438Images: X/N generated
439 
440Positions:
441- 01-xxx.png → After "[Section]"
442- 02-yyy.png → After "[Section]"
443 
444[If failures]
445Failed:
446- NN-zzz.png: [reason]
447```
448