video-workspace-conventions

Files (1)

• SKILL.md

SKILL.md (first lines)

# AI Video Production Workspace Conventions

A workspace produced by `/install-video-workspace` follows the conventions below. All other commands in this plugin assume this structure.

## Lifecycle and where things live

| Phase | Folder | Contents |
|-------|--------|----------|
| Brief | `brief/` | Creative brief, target spec, model/tool selection, vibe references |
| Characters | `characters/` | One markdown file per recurring character/subject — appearance, voice, reference image links |
| Script | `scripts/` | `drafts/` (working), `final/` (locked), `storyboards/` (shot-by-shot breakdowns), `tts/<model>/` (TTS-ready VO chunks) |
| Source assets | `assets/` | Reference images, voice samples, voice-clone source audio, SFX, music, fonts, LUTs, overlays |
| Generation output | `generation/` | Raw model output by modality: `text-to-image/`, `image-to-image/`, `image-to-video/`, `text-to-video/`, `voice/`, `lip-sync/`, `upscale/`. Prompts that produced each artefact go in `generation/prompts/` |
| Pipelines | `pipelines/` | One directory per pipeline; see [Pipeline layout](#pipeline-layout) |
| Clips | `clips/` | `raw/`, `selected/`, `edited/`, `b-roll/`, `normalised/` (loudness/framerate-conformed copies), `converted/` (aspect/resolution-converted copies) |
| Timeline | `timeline/` | Shot list, edit decision list, sequencing notes |
| Exports | `exports/` | Thumbnails, captions, subtitle files (.srt/.vtt) |
| Output | `output/` | `drafts/` (rough cuts), `proofs/` (review copies), `final/` (locked deliverable) |
| Budgets | `budgets/` | Cost estimates from `budget-estimator` (`estimate-<YYYY-MM-DD>.md`) |
| Research | `research/` | Model shortlists and recommendations (`models-*.md`, `recommendations-*.md`) |
| Logs | `logs/` | Per-session production logs, model-call records, cost tracking |

## Pipeline layout

Every pipeline is a directory. Commands, agents and skills all read and write this layout:

```
pipelines/<name>/
  SPEC.md                  — the plan: stages, models, inputs/outputs, cost envelope, open questions
  run.md                   — numbered steps `/run-pipeline <name> <shot#>` follows
  README.md                — optional: how to invoke, expected runtime and cost
  stages/NN-<stage>.md     — optional: prompt template + parameters per stage
  parameters.example.json  — optional: template parameters; copy to parameters.json per shot
  runs/                    — per-run records
  comfy/                   — optional: ComfyUI workflow and manifest
```

- `ai-video-producer-pipeline-scaffolder` writes `SPEC.md`, `stages/` and `runs/`.
- `ai-video-producer-pipeline-builder` writes `run.md`, `README.md`, `stages/*.md` and `parameters.example.json`.
- `/run-pipeline` needs `run.md`. A pipeline with only `SPEC.md` is not built yet.

## Working principles

- **Brief before generation.** Don't fire model calls until `brief/creative-brief.md` exists with target runtime, format, aspect ratio, and model selection. If generation starts without a brief, prompt the user to run `/onboard`.
- **Pair every artefact with its prompt.** Whenever a generated image/clip/voice take is saved, also save the prompt + model + seed in `generation/prompts/` with a matching filename stem so a take can be reproduced or iterated.
- **Raw vs selected.** Everything the model produces lands in `generation/<modality>/` and `clips/raw/`. Only takes the user explicitly approves get copied into `clips/selected/`. Never delete raw output without asking — iteration loops back to it.
- **Pipelines are recipes, not magic.** A pipeline file describes a chain (e.g. Flux text-to-image → Kling image-to-video → ElevenLabs voice → lip-sync). When a pipeline is invoked, walk through it step-by-step, surfacing the intermediate outputs for approval.
- **Tools are user-chosen.** Model selection is per-project. Read `brief/tools-and-models.md` for the active selection — don't assume defaults.
- **Log model calls.** Append a one-line entry to `logs/production-log.md` for each non-trivial generation: timestamp, model, cost estimate, output path.

## Naming conventions

- Generated artefacts: `NN-shortname-vN.ext` — e.g. `03-rooftop-establish-v2.mp4`. The `NN` orders shots, `vN` tracks iterations.
- Prompts: matching stem in `generation/prompts/` — e.g. `03-rooftop-establish-v2.md` containing prompt + model + parameters.
- Characters: `characters/<name>.md`.
- Pipelines: `pipelines/<kebab-name>/` (see [Pipeline layout](#pipeline-layout)).

## Slash commands (typical order)

1. `/install-video-workspace` — scaffold this structure into a new directory.
2. `/onboard` — capture the creative brief and tools-and-models selection.
3. `/define-character` — add recurring characters/subjects.
4. `/draft-script` — produce a script draft from the brief.
5. `/storyboard` — break the locked script into a shot list.
6. `/run-pipeline <name> <shot#> [--dry-run]` — execute a pipeline for a shot.
7. `/log-take` — record a generated artefact.
8. `/promote-take` — promote a raw take into `clips/selected/`.
9. `/assemble` — propose an ffmpeg edit plan into `output/drafts/`.
10. `/export-final` — encode locked draft to spec, write to `output/final/`.

## What NOT to do

- Don't generate cover art, script, or clips before the brief exists.
- Don't overwrite files in `clips/selected/` or `output/final/` — version with `-v2` suffix instead.
- Don't invoke a model the user hasn't listed in `brief/tools-and-models.md` without asking.
- Don't delete from `generation/` or `clips/raw/` — discarded takes often get revisited.

From shotcowboystyle/ag-skills, MIT.

More from shotcowboystyle/ag-skills