comic-adaptation

Comic Adaptation — Story-to-Comic Production Pipeline

Governance: Read and follow .github/RULE.md — it overrides all instructions below.

References: references/anime-archetypes.md, references/ip-adapter-face-lock.md Bundled scripts: scripts/gen_character_sheet.py Shared assets: Uses design skill's canvas-fonts/ for typography. Changelog: CHANGELOG.md — full development history, failed approaches, lessons learned.

This skill turns a source story into a production-ready comic adaptation package. The difference from a simple summary is fundamental: the goal is not to retell the story in text, but to prepare every element an artist or an AI illustration pipeline needs to produce consistent comic pages — cast definitions, visual prototypes, page breakdowns, and continuity rules.

The skill produces both planning artifacts (markdown) and visual artifacts (PDF prototype sheets) in a single workflow. This avoids the pattern where planning lives in one skill and production lives in another, forcing the user to bridge them manually.

All responses to the user are in Vietnamese.

---

Step 0: State Read-Back

Call save_state.py read-context comic-adaptation as first action. Check relevant_artifacts[] for upstream story content or previously generated character work.

---

Step 1: Analyze the Source Story

Read the source material. If the user dropped a file, use gather to read it. If the user named a well-known story, work from knowledge.

Extract:

1. Plot beats — the key narrative moments in order.
2. Cast list — every named or significant character.
3. Story functions — what each character DOES in the plot (trigger, obstacle, anchor, etc.).
4. Cultural identity — elements that must stay recognizable in the adaptation.

Report to user:

📖 Phân tích truyện gốc:
- {N} nhịp chính trong cốt truyện
- {M} nhân vật cần thiết kế
- Bản sắc cần giữ: {cultural_elements}

---

Step 2: Map Characters to Anime Archetypes

Load references/anime-archetypes.md and follow the mapping protocol:

1. For each character, match their story function to the closest archetype.
2. Override archetype defaults with story-specific or cultural details.
3. Verify no two characters share the same silhouette + color combo.
4. For characters with multiple states (e.g., child → hero), define shared identity first, then state-specific differences.

Output a character bible with these fields per character:

• Name and role
• Anime archetype
• Silhouette and body type
• Eye style (from archetype reference)
• Hair shape and color
• Clothing, props, signature accessories
• Color palette (3–5 hex values)
• Default expression + peak expression
• Signature pose
• Consistency rules (what must NOT change between pages)

Save as output/<project>/character-bible.md.

---

Step 3: Generate Prototype Sheet

This is where the skill produces a real visual artifact instead of just text.

Prepare the character data JSON:

Build a JSON file matching the schema expected by scripts/gen_character_sheet.py:

{
    "title": "Story Title",
    "subtitle": "Anime adaptation character prototype sheet",
    "characters": [
        {
            "name": "Character Name",
            "role": "Story role",
            "archetype": "shonen_hero",
            "palette": ["#C11F2C", "#E2BF54", "#1F4E8C"],
            "accent": "#E2BF54",
            "skin": "#E7C7A8",
            "hair_color": "#1A1822",
            "eye_style": "hero",
            "hair_shape": "long_flow",
            "notes": ["Visual note 1", "Visual note 2"]
        }
    ]
}

Run the generator:

python3 .github/skills/comic-adaptation/scripts/gen_character_sheet.py \
    --input tmp/<project>_characters.json \
    --output output/<project>/character-prototype-sheet.pdf

Verify output:

• File exists and > 5 KB
• Page count matches ceil(character_count / 6)
• Open with pypdf to confirm it renders

Register artifact:

python3 scripts/save_state.py register-artifact \
    --step comic-adaptation \
    --path output/<project>/character-prototype-sheet.pdf \
    --type draft_output \
    --summary "Character prototype sheet for <project>" \
    --retention keep

---

Step 4: Build the Page Plan

Translate story beats into pages. For each page define:

Field	Description
Page number	Sequential
Goal	What the page accomplishes narratively
Characters	Who appears (reference prototype sheet)
Key action	The main visual moment
Emotional beat	What the reader should feel
Composition notes	Camera angle, panel layout suggestions
Continuity deps	Which prototype rules apply here

Structure the page plan to follow a natural comic rhythm:

1. Establish the world (wide establishing shot)
2. Introduce protagonist in their normal state
3. Inciting incident (close-ups, dramatic shift)
4. Montage or escalation (panel rhythm speeds up)
5. Transformation or turning point (splash page or full-bleed)
6. Climax (dynamic action, speed lines, high contrast)
7. Resolution (slow down, wide shots, emotional close)

Save as output/<project>/page-plan.md.

---

Step 5: Self-Review

Before delivery, check:

1. Story identity preserved — is the source recognizable?
2. Cast consistency — does every character in the page plan match the bible?
3. Prototype reusability — could someone use the sheet without reading the bible?
4. Page rhythm — does the beat structure feel like a comic, not a list?
5. No placeholders — every character has concrete visual specs, not "TBD".
6. Cultural integrity — cultural elements are adapted, not erased.

If any check fails, fix it before delivery. Max 2 revision passes per RULE-2.

---

Step 6: Delivery

Present to user:

✅ Bộ chuyển thể truyện tranh hoàn tất:
- 📖 Character Bible: output/<project>/character-bible.md
- 🎨 Prototype Sheet: output/<project>/character-prototype-sheet.pdf
- 📋 Page Plan: output/<project>/page-plan.md

Bước tiếp theo có thể làm:
1. Chuyển từng page thành storyboard chi tiết (4-6 panel mỗi page)
2. Tạo prompt hình ảnh AI cho từng nhân vật hoặc từng page
3. Xuất thành slide hoặc PDF hoàn chỉnh

---

Downstream Handoffs

Need	Target Skill	How
Illustrated character art (AI)	gen-image	Pass character description + --style character-anime-male/female + --model quality
Consistent character set (recommended)	gen-image	IP-Adapter Face Lock — see protocol v4 below
Consistent character set (fallback)	gen-image	img2img: canonical view → --reference + --strength 0.55 for other poses
Designed reference poster	design	Pass character specs, use reportlab Canvas
Full comic pages (AI)	gen-image	Pass page plan scene descriptions as prompts
Presentation of the adaptation	gen-slide	Pass page plan + prototype sheet as source

Character Image Generation Protocol (v5.0) — IP-Adapter Face Lock

Reference: references/ip-adapter-face-lock.md for MPS gotchas and troubleshooting. Changelog: CHANGELOG.md for full version history and failed approaches to avoid.

The IP-Adapter Face Lock protocol replaces img2img for multi-pose character sets. It produces significantly better face consistency than img2img (--reference --strength) because it injects face identity via cross-attention embeddings, not pixel-level blending.

Architecture: 2-phase pipeline loading

IP-Adapter requires image_embeds for every generation call once loaded. Therefore the pipeline MUST be loaded in two phases:

Phase A: Load SDXL Base 1.0 (plain, no IP-Adapter)
Phase 0: Generate canonical face via txt2img (front view, bald, clear)
Phase B: Load IP-Adapter Plus Face on top of existing pipeline
Phase 1+: All subsequent images use face-locked generation

Pipeline setup rules (MPS-critical):

1. Use StableDiffusionXLPipeline — NOT AutoPipelineForText2Image
2. Keep default EulerDiscreteScheduler — DDIMScheduler is 50-100x slower on MPS
3. Image encoder: h94/IP-Adapter subfolder models/image_encoder (ViT-H, 1280 dim). Do NOT use sdxl_models/image_encoder (ViT-bigG, 1664 dim) — dimension mismatch.
4. IP-Adapter weights: ip-adapter-plus-face_sdxl_vit-h.safetensors from sdxl_models/
5. Load IP-Adapter BEFORE enable_attention_slicing(). Do NOT re-enable slicing after loading — it overwrites IPAdapterAttnProcessor2_0 and causes 'tuple' has no attribute 'shape'.
6. MPS NaN-safe sizes only: 1024x768, 768x1024. Square sizes (768x768, 1024x1024) cause NaN.

IP-Adapter scale tuning by sheet type (v5 tested):

Sheet type	IP scale	Rationale
Face turnaround	0.7	Strong face lock — sheet is about the face
Face closeup	0.7	Strong face lock — detailed face portrait
Expression sheet	0.55	Medium — face identity but allow expression changes
Body turnaround	0.4	Lower — let body/anatomy come through
Hair reference	0.45	Medium-low — face lock + hair detail balance
Costume reference	0.35	Low — costume needs room to express
Accessories reference	0.3	Lowest — accessories are the focus, not face
Composite (full body)	0.35	Low — hair/costume/pose need room to express

Canonical face generation:

# Phase 0 — plain SDXL, no IP-Adapter loaded yet
prompt = (
    "black and white ink lineart, manga style, white background, "
    "character portrait, ((front view)), ((bald)), "
    "<face_identity_description>, "
    "head and shoulders, centered, clean lineart"
)
# Size: 768x1024 (portrait, MPS-safe). Steps: 25-30. Guidance: 7.5-8.0

Face-locked generation:

# After IP-Adapter loaded + face reference set
pipe.set_ip_adapter_scale(scale)  # per-sheet type
image = pipe(
    prompt=prompt,
    negative_prompt=negativ

---

*Content truncated.*