# Microdrama V2 - Wrapper + Grid Test Plan

## Goal
Build a **Claude Code wrapper** for iterative video generation with human feedback, plus test the **3x3 grid technique** for visual consistency.

## Core Problem
Every step needs human review:
- Character references need approval
- Character sheets need approval
- Scenes/frames need review
- Videos may need regeneration

A simple CLI doesn't solve this. We need Claude Code sessions that:
1. Remember conversation context
2. Accept feedback (text/voice via Telegram)
3. Create new iterations without deleting previous work

## What We ARE Building

### Part 1: Claude Code Wrapper
Minimal wrapper that manages:
- Story directories with session IDs
- Iteration tracking (never delete, always new version)
- Entry points for Claude Code runs

### Part 2: Grid Technique Test
Test 3x3 grid generation with airport-reaper example.

---

## Part 1: Claude Code Wrapper Architecture

### How It Works

```
User (Telegram/CLI) → Wrapper → Claude Code (with session) → AI Tools
                         ↓
                  Story Directory (Claude has FULL access)
                  /mnt/video/microdrama-v2/{story}/
                  ├── CLAUDE.md         # Instructions for Claude
                  ├── story.md          # Source story
                  ├── session_id        # Claude session ID
                  ├── script/001/, 002/, current → ...
                  ├── references/character_*/001/, 002/, current → ...
                  ├── sheets/character_*/001/, 002/, current → ...
                  ├── grids/001/, 002/, current → ...
                  ├── frames/001/, 002/, current → ...
                  ├── videos/scene_*/001/, 002/, current → ...
                  └── assembly/001/, current → ...
```

### Wrapper Script

**`run_story.sh`** - Run Claude with session in story directory:
```bash
#!/bin/bash
# Usage: ./run_story.sh <story_dir> [prompt]
STORY_DIR=$1
PROMPT=${2:-"Continue with the story"}

# Get or create session
SESSION_FILE="$STORY_DIR/session_id"
if [ -f "$SESSION_FILE" ]; then
    SESSION_ID=$(cat "$SESSION_FILE")
else
    SESSION_ID=$(uuidgen)
    echo "$SESSION_ID" > "$SESSION_FILE"
fi

# Run Claude in story directory (full access to all iterations)
cd "$STORY_DIR"
claude --session "$SESSION_ID" -p "$PROMPT"
```

### Iteration Management

**Claude manages iterations** (not wrapper):
- Claude creates new iteration when modifying: `sheets/character_pilot/002/`
- Claude updates symlink: `current → 002`
- Claude can reference older iterations: "use reference from 001 but regenerate sheet"

**Wrapper only manages**:
- Session ID persistence
- Working directory (story root)

### Story CLAUDE.md Template

Each story directory gets a CLAUDE.md that tells Claude:
- What the story is about
- Available tools (yandex search, nanobanana, veo3)
- **Per-artifact iteration structure** (how to create new iterations)
- **Prompt archiving** (save prompt.txt in each iteration)
- File structure expected

### Terminology

- **Story** = Source text (the joke/anecdote) - doesn't change
- **Script** = Claude's interpretation (scenes, characters, visual style) - can have multiple versions
- **Artifact** = Any generated asset (reference, sheet, grid, frame, video)

### Per-Artifact Iteration Structure

Claude sees the **full directory** and can reference any iteration when creating new ones:

```
/mnt/video/microdrama-v2/{story}/
├── story.md                    # Source text (immutable)
├── script/                     # Script = scenes + characters + style
│   ├── 001/                    # First script iteration
│   │   ├── script.json
│   │   └── prompt.txt          # Prompt used to generate
│   ├── 002/                    # After feedback "change scene 3"
│   └── current → 002
├── references/
│   ├── character_pilot/
│   │   ├── 001/                # First search + selection
│   │   │   ├── search/         # Yandex results
│   │   │   ├── selected.jpg
│   │   │   └── prompt.txt
│   │   └── current → 001
│   └── character_reaper/
│       ├── 001/
│       └── current → 001
├── sheets/
│   ├── character_pilot/
│   │   ├── 001/                # First sheet
│   │   │   ├── sheet.jpg
│   │   │   └── prompt.txt
│   │   ├── 002/                # After "make him look younger"
│   │   └── current → 002
│   └── ...
├── grids/
│   ├── 001/                    # First 3x3 grid
│   │   ├── grid.jpg
│   │   └── prompt.txt
│   └── current → 001
├── frames/
│   ├── 001/                    # Frames from grid iteration 001
│   │   ├── frame_001.jpg
│   │   ├── frame_002.jpg
│   │   └── ...
│   └── current → 001
├── videos/
│   ├── scene_001/
│   │   ├── 001/                # First video attempt
│   │   │   ├── video.mp4
│   │   │   └── prompt.txt
│   │   └── current → 001
│   └── ...
└── assembly/
    ├── 001/                    # First assembly
    │   └── final.mp4
    └── current → 001
```

**Key principle**: Each artifact type has its own iterations. Claude can:
- Create new iteration of a specific artifact (e.g., "regenerate sheet for pilot")
- Reference older iterations (e.g., "use pilot reference from iteration 1 but sheet from iteration 2")
- See all history without deleting anything

---

## Part 2: Grid Technique Test

## Key Technique (from Dan Kieft)

**3x3 Grid Generation:**
```
"A cinematic 3×3 storyboard. Label each frame with 'frame 1, frame 2' etc in small text.
Frame 1: [description]
Frame 2: [description]
...
Style: cinematic lighting, ultra-realistic skin and textures, shallow depth of field"
```

**Frame Extraction:**
```
"Extract frame N and upscale it, maintaining cinematic and realistic details"
```

**Video Prompting (4 elements):**
- A. Camera & framing (e.g., "tight close-up", "slow push-in")
- B. Primary motion (main action)
- C. Secondary motion (background, environment)
- D. Details (style, mood, quality)

**Method:** Start frame + motion description → Kling 2.6 / Veo3 (5-10 seconds)

---

## File Structure

```
microdrama-v2/
├── run_story.sh              # Run Claude: ./run_story.sh <story_dir> [prompt]
├── init_story.sh             # Initialize: ./init_story.sh <name> <source.md>
├── templates/
│   └── CLAUDE.md             # Template for story CLAUDE.md (per-artifact iteration rules)
├── prompts/
│   ├── grid_template.md      # 3x3 grid prompt template
│   └── video_template.md     # 4-element video prompt template
└── docs/
    └── README.md             # Documentation
```

Story directory structure is shown in "Per-Artifact Iteration Structure" section above.

---

## MVP Scope

**Part 1**: Wrapper with session management (can run Claude interactively)
**Part 2**: Grid test with 9 frames from airport-reaper

**Test story**: airport-reaper (wasn't fully assembled, good test case)

---

## Commands

```bash
# Initialize new story
./microdrama-v2/init_story.sh my-story /path/to/story.md

# Run Claude on story (starts or continues session)
./microdrama-v2/run_story.sh /mnt/video/microdrama-v2/my-story "Create script with 9 frames"

# Continue with feedback
./microdrama-v2/run_story.sh /mnt/video/microdrama-v2/my-story "Make the pilot look more tired"

# View current script
ls -la /mnt/video/microdrama-v2/my-story/script/current/

# View all iterations of a specific artifact
ls -la /mnt/video/microdrama-v2/my-story/sheets/character_pilot/
```

---

## Implementation Order

### Step 1: Grid Test (First Priority)

1. **Grid prompt template** - `microdrama-v2/prompts/grid_template.md`
2. **Manual grid test** - Generate 3x3 grid for airport-reaper using NanoBanana
3. **Frame extraction test** - Extract individual frames from grid
4. **Compare quality** - vs. existing individual frame approach from `/mnt/video/microdrama/airport-reaper/`
5. **Document results** - Save to `microdrama-v2/docs/grid-test-results.md`

### Step 2: Wrapper + Template (After Grid Test)

6. **Run wrapper** - `microdrama-v2/run_story.sh` (session + run Claude in story dir)
7. **Init helper** - `microdrama-v2/init_story.sh` (setup story directory structure)
8. **CLAUDE.md template** - `microdrama-v2/templates/CLAUDE.md` (per-artifact iteration rules)
9. **Test wrapper** - Initialize airport-reaper-v2, test session continuity

### Step 3: Full Pipeline (Later)

10. **Video generation** - Add 4-element prompting for Kling/Veo3
11. **Assembly** - Wire up FFmpeg logic
12. **Telegram integration** - Bridge user feedback to Claude sessions

---

## Documentation

**After implementation, copy this plan to:**
`microdrama-v2/docs/architecture.md`

This serves as reference documentation for the project.

---

## Questions Resolved

- **Grid aspect ratio**: 1:1 (square) for 3x3, ~1536x1536 total
- **Frame count**: 9 frames (one grid) = ~63 seconds video
- **Video duration**: 5-10 sec (Kling) or 8 sec (Veo3) per frame
- **Character consistency**: Grid technique + reference images
- **Reference images**: Keep Yandex search for real persons & objects
- **Frame extraction**: Use NanoBanana "upscale frame N" technique

---

## Verification

### Step 1: Grid Test (First)
1. Create grid prompt from airport-reaper script (9 scenes)
2. Run NanoBanana to generate 3x3 grid image
3. Check: Grid image has 9 distinct labeled frames
4. Run NanoBanana to extract each frame ("extract frame N and upscale")
5. Check: 9 individual frames with consistent characters
6. Compare: Visual consistency vs. existing frames from `/mnt/video/microdrama/airport-reaper/20260130_222029_airport-reaper/scenes/`
7. Document: Results in `microdrama-v2/docs/grid-test-results.md`

### Step 2: Wrapper Test (After Grid Success)
8. Run: `./microdrama-v2/init_story.sh airport-reaper-v2 /mnt/video/microdrama/airport-reaper/20260130_222029_airport-reaper/article.md`
9. Check: Story directory created with CLAUDE.md, story.md, session_id, empty artifact dirs
10. Run: `./microdrama-v2/run_story.sh /mnt/video/microdrama-v2/airport-reaper-v2 "Read story and create script with 9 frames"`
11. Check: Claude creates `script/001/script.json` and `script/001/prompt.txt`
12. Run: `./microdrama-v2/run_story.sh /mnt/video/microdrama-v2/airport-reaper-v2 "Change scene 3 to show closer view"`
13. Check: Claude creates `script/002/` with modified script, updates `script/current → 002`

## Critical Files to Create

**Wrapper (Part 1):**
- `microdrama-v2/run_story.sh` - Run Claude with session in story directory
- `microdrama-v2/init_story.sh` - Initialize new story directory with structure
- `microdrama-v2/templates/CLAUDE.md` - Per-artifact iteration rules for Claude

**Grid Test (Part 2):**
- `microdrama-v2/prompts/grid_template.md` - 3x3 grid prompt template

**Reference from existing:**
- `/mnt/video/microdrama/airport-reaper/20260130_222029_airport-reaper/` - Source + existing outputs for comparison
- `microdrama/yandex_image_search.py` - Reference search patterns
- `scripts/laozhang_proxy.py` - NanoBanana API
