visual-storytelling

Visual Storytelling — Visual Storytelling Full Production Pipeline

An agent team collaborates to produce a visual story through story design → text writing → AI image generation → HTML layout → integrated editing.

Execution Mode

Agent Team — 5 members communicate directly via SendMessage and cross-verify.

Agent Composition

Agent	File	Role	Type
story-architect	.claude/agents/story-architect.md	Narrative structure, scene design	general-purpose
essay-writer	.claude/agents/essay-writer.md	Write body text, captions, pull quotes	general-purpose
image-prompter	.claude/agents/image-prompter.md	Gemini image prompts, generation	general-purpose
layout-builder	.claude/agents/layout-builder.md	HTML/CSS layout production	general-purpose
editorial-reviewer	.claude/agents/editorial-reviewer.md	Cross-verification, consistency check	general-purpose

Workflow

Phase 1: Preparation (performed directly by the orchestrator)

1. Extract from user input:
   • Story topic: Topic/material of the visual story
   • Type (optional): essay/photo essay/brand story/travelogue
   • Tone & mood (optional): lyrical/documentary/dreamlike/intense
   • Number of scenes (optional): desired length
   • Existing files (optional): text, images, reference materials
2. _workspace/ Create the _workspace/images/ directory
3. Organize the input and save it to _workspace/00_input.mdSave to
4. If existing files are present, copy them to _workspace/and skip the corresponding Phase
5. Determine the execution modeaccording to the request scope (see "Mode by Work Scale" below)

Phase 2: Team Composition and Execution

Compose the team and assign tasks. The dependencies between tasks are as follows:

Order	Task	Owner	Depends on	Deliverable
1	Story design	architect	None	_workspace/01_story_blueprint.md
2a	Text writing	writer	Task 1	_workspace/02_essay_text.md
2b	Image prompt · generation	prompter	Task 1	_workspace/03_image_prompts.md, images/
3	HTML layout	builder	Tasks 2a, 2b	_workspace/04_layout.html
4	Editorial review	reviewer	Tasks 2a, 2b, 3	_workspace/05_review_report.md

Tasks 2a (text) and 2b (image) run in parallel. Both depend only on Task 1 (story design), so they can start simultaneously.

Communication flow among team members:

• architect completes → relay scene-by-scene text roles and emotions to writer, visual motifs and image concepts to prompter, and scene structure and ratios to builder
• writer complete → deliver text sentiment and image improvement direction to prompter, deliver text placement guide to builder
• prompter complete → deliver image files, aspect ratio, and placement information to builder
• reviewer cross-validates all deliverables. 🔴 When mandatory fixes are found, request fixes from the corresponding agent → rework → re-verify (up to 2 times)

Phase 3: Integration and Final Deliverables

Organize the final deliverables based on the reviewer's report:

1. _workspace/ Check all files in
2. Verify that all 🔴 mandatory fixes from the review report have been reflected
3. Report the final summary to the user:
   • Story blueprint — 01_story_blueprint.md
   • Essay text — 02_essay_text.md
   • Image prompts — 03_image_prompts.md
   • HTML layout — 04_layout.html
   • Review report — 05_review_report.md
   • Generated images — images/ directory

Modes by Task Scale

Adjust the agents involved according to the scope of the user's request:

User request pattern	Execution mode	Agents involved
"Make me a visual story", "full production"	Full pipeline	All 5 agents
"Just plan the story for me"	Planning mode	architect + reviewer
"Generate images for this text" (existing text)	Image mode	prompter + reviewer
"Make an HTML with text and images" (existing materials)	Layout mode	builder + reviewer
"Review this visual story"	Review mode	reviewer only

Using existing files: If the user provides existing text or images, copy those files to _workspace/and skip the agent for that step.

Data Transfer Protocol

Strategy	Method	Purpose
File-based	_workspace/ directory	Store and share main deliverables
Message-based	SendMessage	Real-time delivery of key information, fix requests
Task-based	TaskCreate/TaskUpdate	Progress tracking, dependency management

File naming convention: {순번}_{에이전트}_{산출물}.{확장자}

Error Handling

Error type	Strategy
Image generation failure	Retry once with an alternative prompt → on failure, placeholder + prompt text
Ambiguous topic	Story designer proposes 3 directions, then proceeds
Agent failure	Retry once → on failure, proceed without that deliverable, note the omission in the review report
🔴 found in review	Request fixes from the corresponding agent → rework → re-verify (up to 2 times)
Image-Text Emotional Conflict	Modify image prompt or adjust text tone

Test Scenarios

Normal Flow

Prompt: "Create a lyrical visual essay on the theme of 'Dawn in the City.' About 8 scenes" Expected Result:

• Story blueprint: 8-scene narrative arc, emotional curve, visual motif (dawn light gradient)
• Essay text: per-scene narrative + captions + quotes, rhythmic prose style
• Images: 8 watercolor-style dawn landscapes, consistent color palette
• HTML: responsive layout, combination of full-bleed + text + quote patterns
• Review: all items in the consistency matrix confirmed

Existing File Utilization Flow

Prompt: "Generate images that match this essay text and turn them into HTML" + text file Expected Result:

• Copy the existing text to _workspace/02_essay_text.mdCopy to
• Architect generates a brief blueprint through text analysis
• Deploy prompter + builder + reviewer

Error Flow

Prompt: "Create a visual story, theme is free" Expected Result:

• Architect proposes 3 theme directions (seasons/travel/daily life, etc.)
• Proceed with the most universal theme, reduced to a 6-scene composition
• State "automatic theme selection" in the review report

Per-Agent Extension Skills

Extension skills that strengthen the domain expertise of individual agents:

Skill	Target Agent	Role
image-prompt-engineering	image-prompter	5-Layer prompt structure, style keywords, consistency techniques
narrative-structure-patterns	story-architect	3-act/5-act/hero's journey structure, emotional curve, visual rhythm