6f0df5a774
Stop tracking personal workflow artifacts at repo root, add CI and MIT license, align README and agent skills with artifacts/ defaults, and enable Ruff in dev/CI so releases are verifiable without local-only runs. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>
97 lines
5.1 KiB
Markdown
97 lines
5.1 KiB
Markdown
# Documentation Status
|
|
- Synced with artifacts/ baseline on 2026-06-01.
|
|
|
|
---
|
|
name: vlm-library-workflow
|
|
description: Operate and extend the Video Library Manager (`vlm`) with a safety-first, human-in-the-loop workflow across scan, parse, enrich, analyze, plan, review-plan, apply-review, execute, rollback, and developer verification. Use when requests involve organizing a video library, producing or reviewing `artifacts/inventory.csv`, `artifacts/identities.json`, `artifacts/analysis.json`, `artifacts/plan.json`, tuning VLM config templates, resolving duplicates or episode gaps, running dry-run/confirm execution, recovering changes via rollback, explaining VLM CLI usage, or developing/modifying VLM features (parser, providers, planner, executor, commands, tests).
|
|
---
|
|
|
|
# VLM Library Workflow
|
|
|
|
## Overview
|
|
|
|
Run the repository's built-in media organization pipeline with consistent safety checks and explicit output verification. Prefer incremental, reviewable steps and never skip dry-run and plan inspection before destructive operations.
|
|
|
|
**Do not commit** generated CSV/JSON under `artifacts/` or at the repository root.
|
|
|
|
## Workflow Order
|
|
|
|
Run commands in this default sequence unless the user asks for a specific stage:
|
|
|
|
1. `vlm config init` then set `library_root` in `~/.vlm/config.yaml`
|
|
2. `vlm scan` → `artifacts/inventory.csv`
|
|
3. `vlm parse --inventory artifacts/inventory.csv` → `artifacts/identities.json` (v2 schema)
|
|
4. `vlm enrich` when bilingual titles and reputation signals are needed
|
|
5. `vlm analyze --inventory artifacts/inventory.csv` → `artifacts/analysis.json`
|
|
6. `vlm plan --analysis artifacts/analysis.json` → `artifacts/plan.json`
|
|
7. `vlm review-plan` → `artifacts/plan_manual_review.csv` (use `--tui` only when Textual is installed)
|
|
8. Edit CSV if needed, then `vlm apply-review` to sync decisions into `plan.json`
|
|
9. `vlm execute` (dry-run) and inspect summary
|
|
10. `vlm execute --confirm` only after explicit user confirmation
|
|
11. `vlm rollback` if the user requests revert
|
|
|
|
If `vlm` is not on PATH, prefix commands with `uv run`.
|
|
|
|
## Preflight Checks
|
|
|
|
Run these checks before executing workflow commands:
|
|
|
|
1. Confirm current working directory is repository root.
|
|
2. Probe command availability: `vlm --help` or `uv run vlm --help`.
|
|
3. Run the target subcommand `--help` when options are uncertain.
|
|
4. Confirm config validity with `vlm config validate` after config edits.
|
|
5. Verify required input artifacts exist under `artifacts/` (or paths passed via flags).
|
|
6. Treat `execute --confirm` as destructive and require explicit user confirmation.
|
|
|
|
## Execution Rules
|
|
|
|
Follow these rules while executing tasks:
|
|
|
|
1. Prefer read-only stages first: scan, parse, enrich, analyze, plan.
|
|
2. Treat `artifacts/plan.json` as the reviewable contract; summarize counts and conflicts before execution.
|
|
3. Run `review-plan` and `apply-review` before `execute --confirm` when manual decisions are required.
|
|
4. Run dry-run (`vlm execute`) before `vlm execute --confirm`.
|
|
5. If execution is interrupted or results are incorrect, locate rollback logs and run `vlm rollback`.
|
|
6. Keep outputs explicit in responses: file path, record counts, and next command.
|
|
7. If the user asks for a partial workflow, run only required stages and state skipped dependencies.
|
|
8. Before `execute --confirm`, run `vlm review-plan` and report high-risk counts; pause if the user has not reviewed high-risk operations.
|
|
|
|
## Decision Points
|
|
|
|
Use these decision policies:
|
|
|
|
1. Duplicate handling: choose `plan.duplicate_keep` (`by_quality`, `by_reputation`, `by_reputation_quality_time`, `first_seen`, `manual`) per user preference.
|
|
2. Enrichment: skip `vlm enrich` only when translations/reputation are not needed or API keys are unavailable.
|
|
3. Metadata quality: prefer `vlm parse --inventory artifacts/inventory.csv` when duplicate quality ranking matters.
|
|
4. Analysis-assisted planning: prefer `vlm plan --analysis artifacts/analysis.json` for automatic duplicate quarantine decisions.
|
|
5. Parser boundary risk: treat resolution-like tokens (`1920x1080`) and `Sample` clips as high-risk; require review-plan output before confirmation.
|
|
|
|
## Output Contract
|
|
|
|
Return concise, operational summaries:
|
|
|
|
1. Commands executed.
|
|
2. Artifacts generated or updated (under `artifacts/` by default).
|
|
3. Key counts (files scanned, identities parsed, duplicate groups, plan operations).
|
|
4. Risk counts from `review-plan` (manual_review / sample_source / high_season / high_episode / conflicts).
|
|
5. Blocking errors and exact remediation command.
|
|
6. Safe next step.
|
|
|
|
## Developer Verification
|
|
|
|
When modifying VLM core logic:
|
|
|
|
1. **Full suite**: `uv run pytest -q`
|
|
2. **Core components**: `uv run pytest tests/test_scanner.py tests/test_planner.py tests/test_executor.py`
|
|
3. **Property tests**: `uv run pytest tests/test_analysis_properties.py`
|
|
4. **Lint** (with dev extras): `uv run ruff check src tests`
|
|
|
|
## References
|
|
|
|
Load these references on demand:
|
|
|
|
1. `references/command-recipes.md` — command syntax, artifact expectations, failure triage.
|
|
2. `references/workflow.md` — end-to-end operator workflow.
|
|
3. `references/cli-reference.md` — command and config quick reference.
|
|
4. `references/dev-guide.md` — architecture and developer modification patterns.
|