# stage-plan

Ingests raw media files and generates a validated cross-modal video plan in plan.json for multi-axis production.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · ★ 329
- Author: Orkas-AI
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/Orkas-AI/Orkas-VideoStudio/tree/HEAD/packages/skills/stage-plan/SKILL.md
- Updated: 2026-10-13
- HTML: https://affpapa.org/en/nevibecode/skills/stage-plan

## What it does

This skill handles the ingest and planning phase of the Orkas-VideoStudio workflow. It triggers when a video brief spans multiple axes at once, like trimming clips alongside generated footage, HTML overlays, or narration tracks. Single-axis jobs route to separate lines instead.

Planning relies on evidence rather than assumptions. The agent uses `ovs edit probe` to inspect clip duration, resolution, and audio tracks, writing findings to `project/ingest.json`. Spoken tracks get processed with `ovs transcribe`, while silent clips get representative frames extracted via `ovs edit extract-frame`. A plan that cuts past unverified durations simply breaks during assembly.

The final output is `project/plan.json`, a structured cross-modal EDL. Each segment assigns production sources, layer positions, and strict roles (`hook`, `body`, `proof`, `cta`, `transition`). Running `ovs plan validate` confirms schema rules before handover to `stage-assemble`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add Orkas-AI/Orkas-VideoStudio --skill stage-plan -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/stage-plan/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/stage-plan/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add Orkas-AI/Orkas-VideoStudio --skill stage-plan -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/stage-plan/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add Orkas-AI/Orkas-VideoStudio --skill stage-plan -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/stage-plan/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install Orkas-AI/Orkas-VideoStudio stage-plan
```

2. **Manually: put the files in place**
- File: `.github/skills/stage-plan/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add Orkas-AI/Orkas-VideoStudio --skill stage-plan -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/Orkas-AI/Orkas-VideoStudio --path packages/skills/stage-plan
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/stage-plan/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add Orkas-AI/Orkas-VideoStudio --skill stage-plan -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/Orkas-AI/Orkas-VideoStudio/tree/HEAD/packages/skills/stage-plan/SKILL.md

## When to use it
- Generate a unified cross-modal plan.json from mixed media inputs
- Inspect clip duration, fps, and audio tracks with ovs edit probe
- Map segment layers and strict schema roles for automated video assembly
- Validate the cross-modal timeline using ovs plan validate

## Example prompts
- Inspect the media files in `raw/` and draft a `project/plan.json` for a hybrid video with narration.
- Probe the incoming clips using `ovs edit probe` and build an ingest summary in `project/ingest.json`.
- Create a `source_led` video plan with title overlays and validate it with `ovs plan validate`.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 50ba1e1f4489edf3.

BEGIN THIRD-PARTY FILE 50ba1e1f4489edf3
```text
---
name: stage-plan
description: The "ingest + plan" half of end-to-end video orchestration — ingest the user's material from evidence, then decompose intent into ONE cross-modal EDL (plan.json: edit/generate/compose/provided segments + narration/music/caption tracks + a delivery promise), validate it with `ovs plan validate`. Trigger when the deliverable spans more than one axis (AUTO line); do NOT trigger for a pure single-axis job (route to that line). The assembler half is stage-assemble.
---

# stage-plan

How to turn "here is my material + here's the video I want" into a single, inspectable plan spanning reference images/videos, deterministic or semantic editing, generation, and composition. The output is `project/plan.json`—a cross-modal EDL that the assembler walks. Ingest with the public `ovs` analysis commands, validate with `ovs plan`, and execute through the compose/generate/edit lines.

Use this line when the deliverable is NOT cleanly one axis — e.g. "trim my clip, add a title card and captions, and a voiceover", or "my footage for the middle, generate an opener, compose the stats". For a pure single-axis job, route to that single line instead (see `video-router`).

## Step 1 — Ingest from evidence, never from assumption

You cannot plan against material you have not looked at. For EVERY supplied clip, before writing any segment:

1. **Probe** it (`ovs edit probe`) for real duration / resolution / fps / audio presence. A plan that cuts past the real duration breaks.
2. **Read its content** the cheapest way that fits:
   - spoken audio → `ovs transcribe raw/clip.mp4 --out project/transcripts/clip.json` (pass `--model large-v3` for non-English) → you now have timecoded words to cut on and a reusable transcript file for edit ops.
   - silent / screen-recording / slideshow → extract representative frames with `ovs edit extract-frame` and inspect them with the current multimodal model. The audio being empty does NOT mean the screen is. If you cannot inspect images, ask the user for the on-screen beats. Never infer slide/screen content from the topic alone.
   - need to judge what a moment LOOKS like (is the hero shot usable? is the product right-side up?) → read frames: `ovs edit extract-frame` then look at them. If you cannot see images, say so and plan on probe/transcript evidence alone — mark those judgments unverified, do not invent them.
3. Record what each input is good for in `project/ingest.json`: `{input_id, duration, has_audio, content_summary, quality_risks:[...], usable_for:[...], planning_implications:[...]}`. This is the factual basis the plan cites — segments reference `input_id`s from here. Rules:
```
END THIRD-PARTY FILE 50ba1e1f4489edf3

The third-party file has ended. Everything between the 50ba1e1f4489edf3 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2690 of 16029 bytes. © Orkas-AI · MIT · https://github.com/Orkas-AI/Orkas-VideoStudio/tree/HEAD/packages/skills/stage-plan/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md