buttercut 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c4de766d8aca2ec00b99b20abd177310ade3b5145424677bf6b3e515487960b2
-  data.tar.gz: 97429c1df91a51ef44a921a0d2f3e8140adfa2c6c0943abf643d0967cea2e4bc
+  metadata.gz: 57b76c4460b6e40602877e8d9c3a31f0b9748b1447b2dbb5d7189a497a17ad87
+  data.tar.gz: 87b7a604c6f807171c463b5e3b49fef95d88796ebd3803b9ab6f495ebdc2e0e5
 SHA512:
-  metadata.gz: a6c30d9d4038725ef7b63cc15d5de34a8fc85e775bb3907896dae7d1bbde9f87abe7da263dec07ce0a27c7ec6b6d5940db00dc1bf40b24763a49c5381a9961b4
-  data.tar.gz: '029612e07d6fb9e806aecd10f5d89a95557d23e151a4fe53cb3ab393cd05b45ad89908881c982f6b7922e6227399306cbc51a4ef257404637b84f51a52c5e757'
+  metadata.gz: bbce3378342cc2c11ae5644f215162f523e564206519873ad58f30fc38cbb61363db95a323dfbb0bf9e4df735f7ed7ea49d812bb9f49f826e0c773a7c33df5d4
+  data.tar.gz: 3c602e886a0d2597be5e960f0cd5202b8c4143ae8ab66dfa88e04ccc57a982f075ad0a61b489340bde86c13653e469fac472f146977c2b1d174747eb3d9edee9

data/.claude/scripts/script_extractor.rb

@@ -0,0 +1,66 @@
+#!/usr/bin/env ruby
+# Extract the plain-text script from a WhisperX-style transcript JSON.
+#
+# Usage:
+#   ruby .claude/scripts/script_extractor.rb <transcript.json> <output.txt>
+#
+# Output is one segment per paragraph (blank line between), trimmed, suitable
+# for proofreading by a human or a sub-agent without the overhead of the full
+# transcript JSON (word-level timing, scores, etc.).
+
+require 'json'
+
+class ScriptExtractor
+  def self.extract(transcript_path, output_path)
+    new(transcript_path, output_path).extract
+  end
+
+  def initialize(transcript_path, output_path)
+    raise ArgumentError, "transcript_path is required" if transcript_path.nil? || transcript_path.empty?
+    raise ArgumentError, "output_path is required" if output_path.nil? || output_path.empty?
+    @transcript_path = transcript_path
+    @output_path = output_path
+  end
+
+  def extract
+    write_output(format_script)
+    report
+  end
+
+  private
+
+  attr_reader :transcript_path, :output_path
+
+  def data
+    @data ||= JSON.parse(File.read(transcript_path))
+  end
+
+  def segments
+    data["segments"] or raise "transcript JSON has no 'segments' key: #{transcript_path}"
+  end
+
+  def format_script
+    paragraphs = segments.map { |s| s["text"].to_s.strip }.reject(&:empty?)
+    paragraphs.join("\n\n") + "\n"
+  end
+
+  def write_output(text)
+    File.write(output_path, text)
+  end
+
+  def report
+    in_kb = (File.size(transcript_path) / 1024.0).round(1)
+    out_kb = (File.size(output_path) / 1024.0).round(1)
+    puts "Extracted script: #{output_path} (#{out_kb} KB from #{in_kb} KB source, #{segments.size} segments)"
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  transcript_path, output_path = ARGV
+  abort("usage: script_extractor.rb <transcript.json> <output.txt>") unless transcript_path && output_path
+  abort("file not found: #{transcript_path}") unless File.file?(transcript_path)
+  if File.expand_path(output_path) == File.expand_path(transcript_path)
+    abort("output path must differ from transcript path: #{transcript_path}")
+  end
+  ScriptExtractor.extract(transcript_path, output_path)
+end

data/.claude/settings.local.json

@@ -1,6 +1,9 @@
 {
   "permissions": {
     "allow": [
+      "Agent",
+      "Read(tmp/**)",
+      "Write(tmp/**)",
       "Bash(./.claude/skills/roughcut/combine_visual_transcripts.rb:*)",
       "Bash(./.claude/skills/roughcut/export_to_fcpxml.rb:*)",
       "Skill(backup-library)",
@@ -22,7 +25,10 @@
       "Bash(git worktree add:*)",
       "Bash(cat:*)",
       "Bash(python3:*)",
-      "Bash(gh api:*)"
+      "Bash(gh api:*)",
+      "Bash(gh pr:*)",
+      "Bash(cp *)",
+      "Bash(chmod +x .claude/skills/export-video/export_video.rb)"
     ],
     "deny": [],
     "ask": []

data/.claude/skills/analyze-video/SKILL.md

@@ -3,87 +3,28 @@ name: analyze-video
 description: Adds visual descriptions to transcripts by extracting and analyzing video frames with ffmpeg. Creates visual transcript with periodic visual descriptions of the video clip. Use when all files have audio transcripts present (transcript) but don't yet have visual transcripts created (visual_transcript).
 ---
 
-# Skill: Analyze Video
+# Skill: Analyze Video (parent brief)
 
-Add visual descriptions to audio transcripts by extracting JPG frames with ffmpeg and analyzing them. **Never read video files directly** - extract frames first.
+Adds visual descriptions to a video's audio transcript by extracting JPG frames with ffmpeg and analyzing them.
 
-## Prerequisites
-
-Videos must have audio transcripts. Run **transcribe-audio** skill first if needed.
-
-## Workflow
-
-### 1. Copy & Clean Audio Transcript
-
-Don't read the audio transcript, just copy it and then prepare it by using the prepare_visual_script.rb file. This removes word-level timing data and prettifies the JSON for easier editing:
-
-```bash
-cp libraries/[library]/transcripts/video.json libraries/[library]/transcripts/visual_video.json
-ruby .claude/skills/analyze-video/prepare_visual_script.rb libraries/[library]/transcripts/visual_video.json
-```
-
-### 2. Extract Frames (Binary Search)
+`SKILL.md` is the parent's dispatch brief. The sub-agent's working prompt lives in `agent_prompt.md` — inline its contents when launching the Task agent. Don't pass `SKILL.md`.
 
-Create frame directory: `mkdir -p tmp/frames/[video_name]`
-
-**Videos ≤30s:** Extract one frame at 2s
-**Videos >30s:** Extract start (2s), middle (duration/2), end (duration-2s)
-
-```bash
-ffmpeg -ss 00:00:02 -i video.mov -vframes 1 -vf "scale=1280:-1" tmp/frames/[video_name]/start.jpg
-```
-
-**Subdivide when:** Footage start, middle and end have different subjects, setting or angle changes
-**Stop when:** The footage no longer seems to be changing or only has minor changes
-**Never sample** more frequently than once per 30 seconds
-
-### 3. Add Visual Descriptions
-
-Read the visual video json file that you created earlier.
-
-**Read the JPG frames** from `tmp/frames/[video_name]/` using Read tool, then **Edit** `visual_video.json`:
+## Prerequisites
 
-Do these incrementally. You don't need to create a program or script to do this, just incrementally edit the json whenever you read new frames.
+Each video must already have an audio transcript. Run `transcribe-audio` first if any are missing.
 
-**Dialogue segments - add `visual` field:**
-```json
-{
-  "start": 2.917,
-  "end": 7.586,
-  "text": "Hey, good afternoon everybody.",
-  "visual": "Man in red shirt speaking to camera in medium shot. Home office with bookshelf. Natural lighting.",
-  "words": [...]
-}
-```
+## Parallelism
 
-**B-roll segments - insert new entries:**
-```json
-{
-  "start": 35.474,
-  "end": 56.162,
-  "text": "",
-  "visual": "Green bicycle parked in front of building. Urban street with trees.",
-  "b_roll": true,
-  "words": []
-}
-```
+Launch at most **8 in parallel**. ffmpeg frame extraction is a brief CPU burst at the start; the rest of the runtime is LLM API calls. 8 is a comfortable middle ground that won't saturate older machines.
 
-**Guidelines:**
-- Descriptions should be 3 sentences max.
-- First segment: detailed (subject, setting, shot type, lighting, camera style)
-- Continuing shots: brief if similar, otherwise can be up to 3 sentences if drastically different.
+## Inputs to gather and pass inline
 
-### 4. Cleanup & Return
+- `video_path` — absolute path to the video file
+- `audio_transcript_path` — absolute path to the prepared audio transcript JSON
+- `visual_transcript_path` — absolute path to write the visual transcript JSON
 
-```bash
-rm -rf tmp/frames/[video_name]
-```
+After the agent returns, update `library.yaml` with `visual_transcript: <filename>.json`.
 
-Return structured response:
-```
-✓ [video_filename.mov] analyzed successfully
-  Visual transcript: libraries/[library]/transcripts/visual_video.json
-  Video path: /full/path/to/video_filename.mov
-```
+## Next step
 
-**DO NOT update library.yaml** - parent agent handles this to avoid race conditions in parallel execution.
+Once all videos have visual transcripts, dispatch `summarize-video` (Haiku model) to produce summaries.

data/.claude/skills/analyze-video/agent_prompt.md

@@ -0,0 +1,84 @@
+# Analyze Video (sub-agent prompt)
+
+You are a sub-agent. Add visual descriptions to one video's audio transcript by extracting JPG frames with ffmpeg and analyzing them. **Never read the video file directly** — extract frames first.
+
+## Inputs (passed inline by the parent)
+
+- `video_path` — absolute path to the video file
+- `audio_transcript_path` — absolute path to the prepared audio transcript JSON
+- `visual_transcript_path` — absolute path to write the visual transcript JSON
+
+Do NOT read `library.yaml` or `settings.yaml`.
+
+## 1. Copy & clean audio transcript
+
+Don't read the audio transcript — just copy it, then prepare it via `prepare_visual_script.rb`. This removes word-level timing data and prettifies the JSON for easier editing:
+
+```bash
+cp <audio_transcript_path> <visual_transcript_path>
+ruby .claude/skills/analyze-video/prepare_visual_script.rb <visual_transcript_path>
+```
+
+## 2. Extract frames (binary search)
+
+Create frame directory: `mkdir -p tmp/frames/[video_name]`
+
+**Videos ≤30s:** extract one frame at 2s
+**Videos >30s:** extract start (2s), middle (duration/2), end (duration-2s)
+
+```bash
+ffmpeg -ss 00:00:02 -i video.mov -vframes 1 -vf "scale=1280:-1" tmp/frames/[video_name]/start.jpg
+```
+
+**Subdivide when:** start, middle, and end have different subjects, settings, or angle changes
+**Stop when:** the footage no longer seems to be changing or only has minor changes
+**Never sample** more frequently than once per 30 seconds
+
+## 3. Add visual descriptions
+
+Read the visual transcript JSON you created in step 1.
+
+**Read the JPG frames** from `tmp/frames/[video_name]/` using the Read tool, then **Edit** the file at `<visual_transcript_path>`. Do this incrementally — no script needed; just edit the JSON each time you read new frames.
+
+**Dialogue segments — add `visual` field:**
+```json
+{
+  "start": 2.917,
+  "end": 7.586,
+  "text": "Hey, good afternoon everybody.",
+  "visual": "Man in red shirt speaking to camera in medium shot. Home office with bookshelf. Natural lighting.",
+  "words": [...]
+}
+```
+
+**B-roll segments — insert new entries:**
+```json
+{
+  "start": 35.474,
+  "end": 56.162,
+  "text": "",
+  "visual": "Green bicycle parked in front of building. Urban street with trees.",
+  "b_roll": true,
+  "words": []
+}
+```
+
+**Guidelines:**
+- Descriptions: 3 sentences max
+- First segment: detailed (subject, setting, shot type, lighting, camera style)
+- Continuing shots: brief if similar; up to 3 sentences if drastically different
+
+## 4. Cleanup & return
+
+```bash
+rm -rf tmp/frames/[video_name]
+```
+
+Return:
+```
+✓ [video_filename.mov] analyzed successfully
+  Visual transcript: <visual_transcript_path>
+  Video path: <video_path>
+```
+
+**Do NOT update library.yaml** — parent handles this to avoid race conditions in parallel execution.

data/.claude/skills/backup-library/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: backup-library
-description: Creates compressed ZIP backups of libraries directory. Backs up library.yaml, transcripts, and roughcuts (not video files). This skill can also be useful when you need to restore a library.
+description: Backs up user libraries and all their contents (external video excluded). This skill can also be useful when you need to restore a library.
 ---
 
 # Skill: Backup Library

data/.claude/skills/backup-library/backup_libraries.rb

@@ -29,7 +29,7 @@ class LibraryBackup
 
     files = Dir.glob(File.join(@libraries_dir, '**', '*')).select { |f| File.file?(f) }
 
-    Zip::File.open(backup_path, Zip::File::CREATE) do |zipfile|
+    Zip::File.open(backup_path, create: true) do |zipfile|
       files.each do |file|
         zipfile.add(file.sub("#{File.dirname(@libraries_dir)}/", ''), file)
       end

data/.claude/skills/cut-planner/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: cut-planner
+description: Plans a cut (roughcut, sequence, or scene) from a library's clip summaries. Reads all clip summaries, then talks with the user and iteratively creates a plan markdown file until both agent and user are happy and understand the plan.
+---
+
+# Skill: Cut Planner
+
+## Overview
+
+In the cut-planner skill, the main thread reads clip summaries from a library to understand footage coverage, then asks the user about the footage to confirm its understanding. It confirms who the characters and locations are, then updates the library.yaml's footage_summary and user_context as it learns more about the footage. If it determines summaries are wrong or missing details, it also updates the summary markdowns.
+
+After confirming its understanding of the footage, it works with the user to create a narrative plan markdown file.
+
+This skill runs in the main thread and does not use a sub-agent.
+
+## Cut Planner Process
+
+### 1. Verify all clips have visual transcripts and summaries
+Read `libraries/[library-name]/library.yaml`. Every clip must have `visual_transcript` and `summary` populated. If either is missing for any clip, stop and tell the user which clips still need processing — don't try to plan from incomplete footage. Then ask if they want to resume processing the library.
+
+### 2. Read summaries
+
+#### Sequences
+If the user explicitly says they want something short like a short sequence (60 seconds or less), consider asking them about what they want and then grepping through summaries to find the handful of files they might need.
+
+#### Rough Cuts
+If the user wants a full roughcut, read every `libraries/[library-name]/summaries/summary_*.md` file. This will give you full knowledge of the library.
+
+### 3. Confirm the footage knowledge and update incorrect summaries
+Tell the user what you've learned about the footage, then confirm you understand the Five W's of all the footage: Who, What, When, Where, Why.
+
+Don't tell them "Five W's" or label out Who, What, When, Where, Why, just talk with them conversationally like an assistant editor getting a grip on the footage.
+
+If they want a full roughcut, spend more time. If they just want a sequence, be brief.
+
+Talk with the user until you confirm you understand the footage. Update library.yaml based on the user's responses as you work through questions.
+
+Update footage_summary (locations, characters, narrative, dialogue, clips) and user_context (preferences, goals, etc.) as you iteratively learn more about the footage.
+
+Updating user_context and footage_summary helps future agents understand the footage and the user.
+
+For example, if a summary mentions a generic man or woman but you learn the person is actually the user, replace man/woman with the user's name. Ask the user's name if you don't know it already.
+
+### 4. Ask target length
+If available, use the `AskUserQuestion` tool or similar to ask the user what length of video they want to create. Use your judgement based on the footage — options like short sequence (30–60s), medium cut (5–8 min), or longer roughcut (9+ min) make good starting points. Podcast footage will likely require a longer option.
+
+### 5. If creating a roughcut, propose 2–3 concepts (titles only)
+Give the user 2–3 genuinely distinct narrative concepts. Keep this round short — it's about picking a direction, not approving a full plan. For each concept, write only:
+- **Title** — short, evocative
+- **Concept** — 1–2 sentences explaining the angle, tone, or arc
+
+Do **not** include beats, footage suggestions, runtime breakdowns, or format notes yet. Those come in step 6 once a direction is chosen.
+
+Make the options genuinely distinct — different angles, tones, or arcs. End with: "Which feels right, or want me to explore something different?"
+
+If the user just wants a short sequence, give them information about what the sequence will contain.
+
+### 6. Flesh out the chosen concept
+Once the user picks a direction for a full roughcut, expand it into a full plan and present that for approval. Now include:
+- **Format** — vlog, YouTube Short, long-form, documentary, etc.
+- **Beats** — 3–6 beats, each with editorial intent and a rough share of the runtime ("open with ~3 min of X", "montage of Y", "close on Z")
+- **Footage suggestions per beat** — name a few videos likely to feed each beat, ie DJI_123, panasonic_1234, etc. Include rough or specific dialogue if you think it will be helpful.
+- **Approx. duration**
+
+Iterate on the fleshed-out plan until the user explicitly signals go.
+
+If the user wants a short sequence, be brief, just a few sentences, including dialogue if that makes sense.
+
+### 7. Save the plan
+Copy `templates/plan_template.md` to `libraries/[library-name]/plans/plan_[short-name]_[YYYYMMDD_HHMMSS].md` and fill in every section. The template is the canonical structure — Concept, Format, Target Duration, Beats (with intent / approx. share / footage suggestions), Required Dialogue, Notes for the Build.
+
+The plan is direction. The build agent confirms specific clips inside each beat.
+
+Tell the user the plan is ready and confirm they want to move forward, then invoke the `roughcut` skill, passing the full plan path (`libraries/[library-name]/plans/plan_[short-name]_[YYYYMMDD_HHMMSS].md`) as a skill argument — `roughcut` hard-stops if it isn't given one.

data/.claude/skills/release/SKILL.md

@@ -59,7 +59,17 @@ class ButterCut
 end
 ```
 
-### 5. Gather Changelog Notes
+### 5. Update Gemfile.lock
+
+Run `bundle install` so `Gemfile.lock` reflects the new version:
+
+```bash
+bundle install
+```
+
+Verify the version updated in `Gemfile.lock` before proceeding.
+
+### 6. Gather Changelog Notes
 
 Ask user for release notes. Prompt with:
 - What changed in this release?
@@ -67,7 +77,7 @@ Ask user for release notes. Prompt with:
 - Any bug fixes?
 - Any breaking changes?
 
-### 6. Update or Create CHANGELOG.md
+### 7. Update or Create CHANGELOG.md
 
 If `CHANGELOG.md` exists, prepend new entry. Otherwise create it:
 
@@ -89,14 +99,14 @@ All notable changes to ButterCut will be documented in this file.
 - Improved W
 ```
 
-### 7. Commit Version Bump
+### 8. Commit Version Bump
 
 ```bash
-git add lib/buttercut/version.rb CHANGELOG.md
+git add lib/buttercut/version.rb Gemfile.lock CHANGELOG.md
 git commit -m "Bump version to 0.2.0"
 ```
 
-### 8. Create and Push Git Tag
+### 9. Create and Push Git Tag
 
 ```bash
 git tag v0.2.0
@@ -104,7 +114,7 @@ git push origin main
 git push origin v0.2.0
 ```
 
-### 9. Build Gem
+### 10. Build Gem
 
 ```bash
 gem build buttercut.gemspec
@@ -112,7 +122,7 @@ gem build buttercut.gemspec
 
 This creates `buttercut-0.2.0.gem` file.
 
-### 10. Publish to RubyGems
+### 11. Publish to RubyGems
 
 **First time setup check:**
 
@@ -133,7 +143,7 @@ gem push buttercut-0.2.0.gem
 
 This makes the gem available for `gem install buttercut` worldwide.
 
-### 11. Create GitHub Release
+### 12. Create GitHub Release
 
 **Using GitHub CLI:**
 ```bash
@@ -155,21 +165,21 @@ Guide user through manual release creation:
 
 Then wait for user confirmation that release is created before proceeding to cleanup.
 
-### 12. Cleanup
+### 13. Cleanup
 
 ```bash
 # Remove local gem file (it's on RubyGems and GitHub now)
 rm buttercut-0.2.0.gem
 ```
 
-### 13. Verify Release
+### 14. Verify Release
 
 Check that everything worked:
 - RubyGems page: https://rubygems.org/gems/buttercut
 - GitHub releases: https://github.com/andrewford/buttercut/releases
 - Git tags: `git tag -l`
 
-### 14. Return Success Response
+### 15. Return Success Response
 
 Provide summary:
 ```

data/.claude/skills/roughcut/SKILL.md

@@ -1,71 +1,65 @@
 ---
 name: roughcut
-description: Creates video rough cut yaml file for use with Buttercut gem. Concatenates visual transcripts with file markers, creates a roughcut yaml with clip selections, then exports to XML format. Use this skill when users want a "roughcut", "sequence" or "scene" generated. These are all the same thing, just with different lengths.
+description: Builds a roughcut YAML and exported XML (Final Cut, Premiere, or Resolve) from an approved plan markdown file produced by `cut-planner`. Spins up a sub-agent that reads the library directly, builds the cut iteratively, reviews against format conventions, then returns paths plus conversational editorial notes. If the user asks for a "roughcut", "sequence", or "scene" and no plan exists yet, run `cut-planner` first.
 ---
 
-# Skill: Create Rough Cut
+# Skill: Roughcut Build
 
-This skill handles the editorial process of creating rough cut timeline scripts from transcribed video footage. It launches a specialized agent that analyzes transcripts, makes editorial decisions, outputs a structured YAML rough cut, and exports it to Final Cut Pro XML format.
+Turns an approved plan into a working roughcut YAML and exported XML. The sub-agent runs async — it commits to a complete cut and returns with notes you can dialogue about.
 
-**Note:** This skill is used for both full-length rough cuts (multiple minutes) and short sequences (30-60 seconds).
+## 1. Locate the Plan
+A plan path **must** be passed in as a skill argument (the format produced by `cut-planner` step 7: `libraries/[library-name]/plans/plan_[short-name]_[timestamp].md`). If no plan path is passed in, stop immediately and return a message to the parent saying a plan path is required and `cut-planner` should be run first. Do not search for plans, do not pick one, do not proceed without one.
 
-## Prerequisites Check
+## 2. Resolve the Editor (Parent Only)
+The sub-agent receives a final editor value:
+1. If `library.yaml` has `editor` set, use it.
+2. Otherwise fall back to `libraries/settings.yaml`'s `editor` and write the value back to `library.yaml`.
+3. If neither has one, ask the user (Final Cut Pro X / Adobe Premiere Pro / DaVinci Resolve), then save the choice to both `library.yaml` and `libraries/settings.yaml`.
 
-Before launching the roughcut agent, verify all transcripts are complete:
-
-1. **Check library exists:**
-   ```bash
-   ls libraries/[library-name]/library.yaml
-   ```
-
-2. **Verify visual transcripts:**
-   Read `libraries/[library-name]/library.yaml` and check that every video entry has both:
-   - `transcript` populated (audio transcript filename)
-   - `visual_transcript` populated (visual descriptions filename)
-
-   If any visual transcripts are missing:
-   - Inform user that transcript processing must be completed first
-   - Ask if they want Claude to finish transcript processing using the `transcribe-audio` and `analyze-video` skills
-   - Do not proceed with roughcut creation until all transcripts are complete
-
-## Launch Roughcut Agent
-
-Once prerequisites are verified, launch the roughcut creation agent using the Task tool:
+## 3. Launch Build Agent
 
 ```
-Task tool with:
+Agent tool with:
 - subagent_type: "general-purpose"
-- description: "Create rough cut from visual transcripts"
-- prompt: [See agent prompt template below]
+- description: "Build roughcut YAML and XML from approved plan"
+- prompt: [see template below]
 ```
 
 ### Agent Prompt Template
 
-When launching the agent, provide a detailed prompt with all necessary context:
-
 ```
-You are a video editor AI agent creating a rough cut or sequence for the "{library_name}" library.
+You are a video editor AI agent for the "{library_name}" library. The plan below is approved direction — beats, intent, rough length, format. The specific clips are yours to find inside the library. Work iteratively, then review and refine before returning.
+
+LIBRARY YAML: libraries/{library_name}/library.yaml
 
-USER REQUEST: {what_user_asked_for}
+APPROVED PLAN:
+{paste full plan markdown}
 
-LIBRARY CONTEXT:
-{paste relevant content from library.yaml - footage_summary, user_context, etc.}
+EDITOR: {editor}
 
-YOUR TASK:
-1. Read the roughcut creation instructions from .claude/skills/roughcut/agent_instructions.md
-2. Follow those instructions to create the rough cut
-3. Return the paths to the created YAML and XML files when complete
+TASK:
+1. Read `.claude/skills/roughcut/agent_prompt.md`
+2. Follow the steps there in order (the plan is already approved — don't re-propose)
+3. Return paths to the YAML and XML, plus your editorial notes (alternatives, judgment calls, plan deviations) in conversational prose
+```
 
-DELIVERABLES:
-- Rough cut YAML file at: libraries/{library_name}/roughcuts/{roughcut_name}_{datetime}.yaml
-- Exported XML file for user's chosen video editor
-- Backup created via backup-library skill
+## 4. Context Contract
+This sub-agent reads `library.yaml` directly — it needs the full inventory plus `footage_summary` and `user_context`. This is a deliberate carve-out from the parallel-skill contract: `roughcut` runs as a single agent (no race risk), and editorial work needs broader library context than inline-passing comfortably supports.
 
-Begin by reading the agent instructions file.
+## 5. Copy XML to Desktop (if enabled)
+Check `libraries/settings.yaml` for `save_to_desktop_after_export`:
+1. If the key is `true`, copy the exported XML to `~/Desktop/` so it's easy to grab and import into the editor.
+2. If the key is `false`, skip this step.
+3. If the key is missing, ask the user whether to drop a copy of every export on the Desktop, save their answer (`true`/`false`) to `libraries/settings.yaml`, then act on it.
+
+```bash
+cp [library xml path] ~/Desktop/
 ```
 
-## After Agent Completes
+The library copy stays as the canonical artifact; the desktop copy is a convenience drop.
+
+## 6. Backup the Library
+Run the `backup-library` skill. This snapshots the library (yaml, transcripts, summaries, plans, roughcuts) so progress can be restored if needed.
 
-When the agent returns:
-1. Inform the user of the created roughcut file (the xml file, not the yaml file) and its location
-2. Confirm the rough cut is ready to import into their video editor
+## 7. Report Results
+Surface the agent's return message to the user — the YAML path, the library XML path, the desktop XML path (only if step 5 actually copied one), plus the editorial notes. The notes are the conversational hook for what comes next; small fixes you can do directly in the YAML, larger restructures relaunch this skill with a revised plan.