Deprecation Plan

Last reviewed 2026-09-09.

This document defines the deprecation path from the original videoclaw (v0.11.x) and the intermediate vclaw-video-core rebuild to videoclaw-v3 — the merged successor (npm package: videoclaw).

Goal

Make videoclaw-v3 the primary execution surface without pretending the predecessor repos never existed.

Current decision

Primary:

1. videoclaw-v3 (npm: videoclaw)

Reference/fallback only:

1. videoclaw v0.11.x (the original repo) — legacy reference / migration source
2. vclaw-video-core — intermediate clean-room rebuild whose foundation was merged into videoclaw-v3

Deprecation boundaries

What should stop growing in the old repo:

1. new user-facing workflow surfaces
2. new canonical artifact contracts
3. new reporting layers
4. new migration-target state models

What can still be consulted in the old repo:

1. legacy scripts
2. older provider behaviors
3. reference patterns not yet ported

Cutover criteria

The clean repo is considered the primary product surface once these are true:

1. provider status works
2. produce / execute-status works
3. clone-execute works
4. template and prompt-library surfaces exist
5. migration docs exist
6. core tests are green

Those conditions are now satisfied.

Remaining non-blocking work

1. richer provider-specific options
2. better automatic prompt guidance during execution
3. user education and release communication

Operational policy

When a user asks to create or run video work:

1. prefer videoclaw-v3 (vclaw CLI)
2. fall back to the legacy videoclaw v0.11.x runtime only when the missing feature is clearly identified
3. track every such fallback as a porting task

Suggested release language

Use this internal framing:

1. videoclaw-v3 (npm: videoclaw) is now the recommended runtime
2. videoclaw v0.11.x and vclaw-video-core remain available as migration/reference sources
3. old workflows should not be expanded further unless they are being ported

Command lifecycle

Individual vclaw video commands and spellings follow a three-step ladder that is encoded in the schema, not remembered:

1. Declared alias. A second spelling of a command is an aliases entry on the canonical CommandSpec in src/video/cli-schema.ts — one schema entry, one handler, and src/tests/cli-dispatch-table.test.ts fails on a dispatch key that shares a handler but is declared nowhere. Supported aliases (execute, execution-plan) print nothing and stay.
2. Deprecated. A whole command carries deprecated: { since, replacement?, note? }; one spelling carries deprecatedAliases: [{ name, since, replacement?, note? }] (an alias's replacement defaults to the canonical name). From that release, every invocation prints exactly one line to stderr — vclaw: 'video X' is deprecated since <version>; use 'video Y' when a command replaces it, vclaw: 'video X' is deprecated since <version> and will be removed; <note> when nothing does — and then runs unchanged — same stdout, same exit code — so agents reading JSON are never broken and vclaw schema --json shows the mark.
3. Removed. After at least one minor release with the notice, the dispatch key and the schema mark go together. A historical-only command (one that reads data an older release wrote — the legacy batch queue, import-legacy, cinema-migrate, cinema-history-import) needs a documented data-migration exit before step 3, not just the notice.

Marked as of 3.0.0-alpha.13

Notice-only spellings (the canonical command is unchanged): template-create → template-save, clone-ad → clone-execute, analyze-template → analyze, preflight → director-preflight, library find → find-library.

Deprecated commands (still run; removal needs the data-migration exit above for the historical ones): approve → produce --approve (it forwards to the one produce handler, adding --mode director when no mode is typed); batch-monitor → cinema-sync and batch-status → cinema-status (they only read a legacy batch-queue.json); candidates-migrate-from-assets and migrate-home (one-shot consolidations, honoured while there is still something to move); import-legacy, cinema-migrate, cinema-history-import (historical-only imports with no successor — they read what older releases wrote; docs/MIGRATION.md is the path). execute and execution-plan are NOT deprecated: the product emits them.

Sunset rule

Do not archive or delete the old repo until:

1. migration of active users is complete
2. no critical workflow depends exclusively on the old runtime
3. the clean repo has been stable through multiple real runs