OpenSpec-Video (OpsV) — Summary

OpenSpec-Video (CLI: opsv, npm: videospec) is a spec-driven cinematic AI automation framework that compiles narrative Markdown specifications into production-ready media via a multi-provider pipeline. Users write AI media production specs (characters, scenes, shots) as Markdown files with YAML frontmatter; OpsV builds dependency graphs via topological sort, compiles provider-specific task JSON files, executes them against AI image/video/audio APIs (Volcengine, SiliconFlow, MiniMax, ComfyUI, browser automation), and manages the review loop. A physical state machine tracks asset status (drafting → syncing → approved); all outputs are append-only. A visual review server runs at port 3100. With 2 stars and active development (v0.10.1, last commit May 2026), this is the most complex and distinctive framework in the batch.

Compared to seeds: no seed covers AI media production. The closest structural parallels are taskmaster-ai (dependency graph + task execution) and openspec (spec artifacts → implementation). But OpsV adds a circle-based dependency layering system, multi-provider model routing, physical state machine, and a local web review UI — architectural elements found in none of the seeds.

OpenSpec-Video (OpsV) — Overview

Origin

Created by GitHub user mr7thing. Published and actively maintained May 2026, v0.10.1. npm package: videospec. The description says "a suit of spec system for AI video production based antigravity" — referencing the antigravity framework.

Philosophy

From README:

"OpsV is a spec-driven cinematic AI automation framework. You write narrative specifications in Markdown with YAML frontmatter; OpsV builds dependency graphs, compiles provider-specific tasks, executes them, and manages the review loop."

Eight key design principles:

1. Spec-as-Code: Markdown is the single source of truth
2. Intent-Execution Decoupling: Produce commands compile; opsv run executes
3. Physical State Machine: Task state = file existence
4. CLI Does Only Deterministic Actions: CLI never modifies content fields
5. By-Provider Parallelism: Same provider serial, different providers parallel
6. Incremental Preservation: Queue outputs are never deleted
7. Manifest-First: Produce commands read from manifest only
8. Circle-Bound Execution: Produce commands run within a specific circle

Domain Vocabulary

Supported Providers

Volcengine (SeedDream5 image, SeedDance2 video), SiliconFlow (image+video), MiniMax (image+video), RunningHub (ComfyUI), ComfyUI Local, Browser (Gemini webapp automation).

OpenSpec-Video (OpsV) — Architecture

Distribution

• Type: npm-package (videospec)
• Binary: opsv
• Version: 0.10.1
• Install: npm install -g videospec

Runtime Requirements

• Node.js >= 16
• Git (for opsv init)
• API keys for providers (configured in .opsv/api_config.yaml)
• Ollama (optional, for webapp Gemini browser automation)

Directory Structure

videospec/
├── elements/          # Characters, props, locations (upstream assets)
├── scenes/            # Scene compositions (reference elements)
└── shots/             # Shot specifications (reference scenes/elements)

opsv-queue/            # ALL OUTPUTS — append-only, never deleted
└── {target}_circle1/
    ├── _manifest.json  # Circle manifest
    └── {provider}_{seq}/  # Model queue directory
        ├── @assetId.json   # Compiled task JSON
        └── @assetId_1.png  # Generated output

.opsv/                 # Configuration
├── api_config.yaml    # Model aliases + API credentials
├── input_types.yaml   # Allowed input types registry
└── category_validate.yaml  # Per-category validation rules

Source Structure

src/
├── cli.ts
├── commands/
│   ├── init.ts
│   ├── validate.ts
│   ├── circle/create.ts, refresh.ts
│   ├── imagen.ts, animate.ts, comfy.ts, webapp.ts
│   ├── run.ts
│   ├── review.ts
│   └── iterate.ts
├── review-ui/
│   └── ReviewServer.ts    # Express web server
└── tunnel/
    ├── CloudClient.ts
    └── TunnelClient.ts    # Optional cloud review tunnel

Spec Asset Format

---
status: drafting
category: character
refs:
  image:
    "@style:armor": [opsv-queue/circle1/volc_001/@armor.png]
---
# Hero Character

## Prompt

@style:armor A medieval warrior with silver armor.

OpenSpec-Video (OpsV) — Components

CLI Binary: opsv (11 commands)

Review Server

• Local web dashboard at port 3100
• Visual review of generated images/videos
• Status management (drafting → syncing → approved)
• Optional cloud tunnel (--cloud flag) for remote review

Asset Categories

Model Providers (aliases)

OpenSpec-Video (OpsV) — Uniqueness

differs_from_seeds

No seed covers AI media production. The closest structural parallels: taskmaster-ai (dependency graph, task execution pipeline) and openspec (spec artifacts as source of truth). But OpsV departs from both in architecturally significant ways: (1) Circle-based dependency layering via topological sort — assets cannot be compiled until all dependencies are approved, creating a DAG execution model no seed implements; (2) Physical state machine where task state = file existence (not a database or YAML flag file); (3) Multi-provider model routing with zero hardcoded logic — all provider/model configuration lives in api_config.yaml, making OpsV the only framework with explicit per-asset model routing (different models for image vs. video vs. ComfyUI vs. browser automation); (4) Append-only output queue where every compilation is versioned with _001, _002 suffixes — no output ever deleted; (5) Local web review server (port 3100) with optional cloud tunnel — the only framework in the batch with a built-in visual review UI.

Positioning

The most architecturally distinctive framework in the batch. OpsV takes spec-driven development principles from software and applies them to AI media production with domain-specific adaptations (visual review, provider routing, dependency circles for assets that depend on approved upstream images). The "antigravity" reference in the description suggests it emerged from a broader AI media production ecosystem.

Observable Failure Modes

1. No AI agent integration: despite being in the OpenSpec ecosystem cluster, OpsV has no Claude Code commands, no slash commands, no AI agent skills — it is a pure CLI tool that the human operates. AI is the consumer (generating images), not the operator.
2. Append-only storage grows unboundedly: opsv-queue/ never deletes outputs. A production project with hundreds of iterations will accumulate gigabytes of files. The README says "Delete manually only when you are certain."
3. api_config.yaml required: all model aliases must be configured before any compilation. Zero hardcoded defaults means a fresh install can't compile anything without manual config.
4. Cloud review coupling: the tunnel/cloud features require OPSV_CLOUD_URL and OPSV_CLOUD_API_KEY environment variables — suggesting a paid cloud service that may not be available to all users.
5. Bidirectional ref validation strictness: opsv validate --category shot --strict fails on prompt-refs misalignment, which may block workflows when specs are iteratively drafted.