md-manuscript/templates/snowflake/{{ cookiecutter.project_name }}/scripts

Scene Management Scripts

Automate the creation and linking of planning and draft files.

---

Scripts Available

create_scene.py

Creates linked planning and draft files for new scenes.

---

Quick Start

1. Create a New Scene Pair

# Navigate to your project root
cd /path/to/your/project

# Create a new scene (act 1, chapter 1, scene 2)
python scripts/create_scene.py --act 1 --chapter 1 --scene 2 --title "Chapter Two: The Journey"

This creates:

• 05-Plot/act_1/scene_02.md (planning template)
• 06-First Draft/Act 1/scene02.md (draft file)
• Both files are automatically linked to each other

2. Create Draft from Existing Planning

# If you have an existing planning file but no draft
python scripts/create_scene.py --from-planning 05-Plot/act_1/scene_01.md

This creates the corresponding draft file and links it.

3. Create Planning from Existing Draft

# If you have an existing draft file but no planning
python scripts/create_scene.py --from-draft "06-First Draft/Act 1/scene01.md"

This creates the corresponding planning file and links it.

---

Usage Examples

Minimal (auto-generates title)

python scripts/create_scene.py --scene 3

Creates scene 3 in act 1, chapter 1 with title "Chapter 1: Scene 3"

Full specification

python scripts/create_scene.py \
    --act 2 \
    --chapter 3 \
    --scene 5 \
    --title "Chapter Three: The Revelation" \
    --type chapter

Batch create multiple scenes

for scene in {2..10}; do
    python scripts/create_scene.py --chapter 1 --scene $scene
Done

---

File Structure

Planning Files (05-Plot/)

05-Plot/
├── _template.md              # Template for new planning files
├── act_1/
│   ├── scene_01.md           # Planning for act 1, scene 1
│   ├── scene_02.md           # Planning for act 1, scene 2
│   └── ...
├── act_2/
│   ├── scene_01.md
│   └── ...
└── act_3/
    └── ...

Each planning file contains:

• YAML frontmatter with metadata (act, chapter, scene, word count targets, etc.)
• draft_file field pointing to the corresponding draft file
• Scene planning sections (setup, reveal, notes)

Draft Files (06-First Draft/)

06-First Draft/
├── _template.md              # Template for new draft files
├── Act 1/
│   ├── scene01.md           # Draft for act 1, scene 1
│   ├── scene02.md           # Draft for act 1, scene 2
│   └── ...
├── Act 2/
│   ├── scene01.md
│   └── ...
└── Act 3/
    └── ...

Each draft file contains:

• YAML frontmatter with metadata
• planning_template field pointing to the corresponding planning file
• Word count tracking (current, session, target from planning)
• Actual scene content

---

Linking System

The two files are linked via relative paths in their frontmatter:

Planning file (05-Plot/act_1/scene_01.md):

---
draft_file: "../../06-First Draft/Act 1/scene01.md"
---

Draft file (06-First Draft/Act 1/scene01.md):

---
planning_template: "../../05-Plot/act_1/scene_01.md"
---

This bidirectional linking allows:

• Navigating from planning to draft and vice versa
• Sharing metadata between files
• Tracking progress across both

---

Metadata Reference

Planning File Fields

Field	Type	Description
id	string	Unique identifier (e.g., scene_01_01_01)
title	string	Scene/chapter title
slug	string	URL-friendly identifier
act	int	Act number
chapter	int	Chapter number
scene	int	Scene number
type	string	scene | chapter | interlude
status	string	planning | ready | blocked
word_count_target	int	Target word count
word_count_min	int	Minimum acceptable words
word_count_max	int	Maximum acceptable words
pov	string	Point of view character
characters	list	Characters in this scene
setting	string	Primary location
date	string	Date in story timeline
time	string	Time of day
conflict	string	Central conflict
theme	string	Thematic focus
tone	string	Emotional tone
draft_file	string	Path to linked draft file
order	int	Sort order

Draft File Fields

Field	Type	Description
id	string	Unique identifier (e.g., draft_scene_01_01_01)
title	string	Scene/chapter title
slug	string	URL-friendly identifier
act	int	Act number
chapter	int	Chapter number
scene	int	Scene number
type	string	draft
status	string	not_started | in_progress | completed | needs_revision
word_count	int	Current word count
word_count_updated	string	Last word count update date
session_word_count	int	Words written in current session
last_session	string	Date of last writing session
total_sessions	int	Number of writing sessions
pov	string	Point of view character
version	int	Draft version
planning_template	string	Path to linked planning file

---

Integration with Your Workflow

With Drag-and-Drop Reordering

If your editor supports drag-and-drop chapter reordering, the order field in the frontmatter is available for sorting. Update this field when reordering scenes.

With File Watchers

To automatically create corresponding files when a new file is created:

1. Option A: Use the script manually (recommended)

   # After creating a planning file manually, run:
   python scripts/create_scene.py --from-planning 05-Plot/act_1/scene_05.md
   

2. Option B: Set up a file watcher Create a watcher script that triggers create_scene.py when new files are detected.

3. Option C: Editor integration If your editor supports custom commands, add a command that calls:

   python scripts/create_scene.py --from-draft "${file}"
   

---

Tips

1. Naming Convention

   • Planning: scene_{number:02d}.md (e.g., scene_01.md, scene_02.md)
   • Draft: scene{number:02d}.md (e.g., scene01.md, scene02.md)
   • Note the slight difference (underscore vs. no underscore)

2. Folder Structure

   • Planning: 05-Plot/act_{N}/
   • Draft: 06-First Draft/Act N/
   • Note the difference in folder naming (act_1 vs. Act 1)

3. ID Generation

   • Planning IDs: scene_{act:02d}_{chapter:02d}_{scene:02d}
   • Draft IDs: draft_scene_{act:02d}_{chapter:02d}_{scene:02d}

4. Word Count Targets

   • Set in planning file
   • Displayed in draft file
   • Not automatically synced (manual update or via script)

---

Troubleshooting

"Module not found: yaml"

pip install pyyaml

File paths not working

• Ensure you're running the script from the project root
• Check that the scripts/ directory is in your project
• Verify relative paths are correct for your folder structure

Frontmatter not parsing

• Ensure your files start with --- on the first line
• Ensure there's a closing --- after the frontmatter
• YAML is sensitive to indentation (use spaces, not tabs)

---

Advanced Usage

Custom Metadata

Add any additional fields to the frontmatter:

python scripts/create_scene.py --scene 1 --custom_field "value"

Bulk Operations

Create multiple scenes at once:

# Create scenes 1-10 for chapter 1
for i in {1..10}; do
    python scripts/create_scene.py --chapter 1 --scene $i
done

Sync Existing Files

If you have existing files without links, you can manually add the frontmatter:

Planning file:

---
draft_file: "../../06-First Draft/Act 1/scene01.md"
---

Draft file:

---
planning_template: "../../05-Plot/act_1/scene_01.md"
---

---

Related Files

• 05-Plot/_template.md - Planning file template
• 06-First Draft/_template.md - Draft file template
• 03-Story-Bible/ - Story Bible for character/location/lore tracking