feat: Add linked scene/chapter templates with planning-draft file references
- Updated Plot scene template with YAML frontmatter for metadata tracking - Updated First Draft scene template with YAML frontmatter - Added _template.md files in both Plot and First Draft folders - Added create_scene.py script for automatic file creation and linking - Planning files reference draft files via 'draft_file' field - Draft files reference planning files via 'planning_template' field - Word count targets tracked in planning, current count in draft - Added comprehensive scripts/README.md with usage guide - Supports --from-planning and --from-draft for creating missing counterparts Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
This commit is contained in:
landon
@@ -0,0 +1,314 @@
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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)
|
||||
```bash
|
||||
python scripts/create_scene.py --scene 3
|
||||
```
|
||||
Creates scene 3 in act 1, chapter 1 with title "Chapter 1: Scene 3"
|
||||
|
||||
### Full specification
|
||||
```bash
|
||||
python scripts/create_scene.py \
|
||||
--act 2 \
|
||||
--chapter 3 \
|
||||
--scene 5 \
|
||||
--title "Chapter Three: The Revelation" \
|
||||
--type chapter
|
||||
```
|
||||
|
||||
### Batch create multiple scenes
|
||||
```bash
|
||||
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`):**
|
||||
```yaml
|
||||
---
|
||||
draft_file: "../../06-First Draft/Act 1/scene01.md"
|
||||
---
|
||||
```
|
||||
|
||||
**Draft file (`06-First Draft/Act 1/scene01.md`):**
|
||||
```yaml
|
||||
---
|
||||
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)
|
||||
```bash
|
||||
# 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:
|
||||
```bash
|
||||
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"
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
python scripts/create_scene.py --scene 1 --custom_field "value"
|
||||
```
|
||||
|
||||
### Bulk Operations
|
||||
|
||||
Create multiple scenes at once:
|
||||
|
||||
```bash
|
||||
# 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:**
|
||||
```yaml
|
||||
---
|
||||
draft_file: "../../06-First Draft/Act 1/scene01.md"
|
||||
---
|
||||
```
|
||||
|
||||
**Draft file:**
|
||||
```yaml
|
||||
---
|
||||
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
|
||||
Reference in New Issue
Block a user