boom

Author: Kasper Junge

.gitignore

@@ -7,3 +7,8 @@ __pycache__/
 .claude/
 .worktrees/
 site/
+video-edit-projects/
+work/
+workspaces/
+docs/diary/
+.DS_Store

docs/concepts.md

@@ -78,6 +78,12 @@ derived artifact in `workspace.json`. Sources are referred to by manifest id
 (`src-1`, `src-2`, …) in plans and notes, and can carry a `--role` label
 (`camera-a`, `screen`, `mic-guest`).
 
+The companion agent skill defaults new jobs to
+`<project-root>/video-edit-projects/YYYY-MM-DD-<source-id-or-slug>/`, with the CLI
+workspace in its `edit/` directory. This is a visible agent convention; the CLI
+itself continues to require explicit paths and honors any location chosen by the
+user.
+
 ## Edit plans
 
 A plan is an ordered keep-list, compiled deterministically to FFmpeg. Each

skills/video-edit-cli/SKILL.md

@@ -34,8 +34,11 @@ installed separately.
    capabilities apply.
    Resolve failed dependency checks before expensive work.
 3. **Set up a workspace.** Read [references/workspace.md](references/workspace.md),
-   then `video-edit-cli workspace init`. Done when `workspace.json` lists every
-   source with its hash.
+   announce the chosen project path, then reuse a matching project or run
+   `video-edit-cli workspace init`. Default to
+   `<project-root>/video-edit-projects/YYYY-MM-DD-<source-id-or-slug>/edit/`
+   unless the user specifies another location. Done when `workspace.json` lists
+   every source with its hash.
 4. **Inspect the media.** `probe` every source; gather audio, proxies, frames,
    filmstrips, waveforms, or range previews as decisions require. For dialogue
    media read [references/transcription.md](references/transcription.md) and

skills/video-edit-cli/references/workspace.md

@@ -1,5 +1,32 @@
 # Workspace conventions
 
+## Default project location
+
+Unless the user specifies another destination, keep each editing job under the
+current project root:
+
+```text
+<project-root>/video-edit-projects/YYYY-MM-DD-<source-id-or-slug>/
+  source/        downloaded or copied immutable source media
+  edit/          video-edit-cli workspace root
+  deliverables/  optional handoff copies and accompanying text
+```
+
+Prefix the job directory with its local creation date in ISO format, then append
+a stable, filesystem-safe external identifier when one exists (for example,
+`2026-07-14-r1Kh5WssSPg` for a YouTube video); otherwise append a concise
+source-derived slug. Before initializing, tell the user which path you will use.
+Search existing `video-edit-projects/*/edit/workspace.json` manifests first and
+reuse a project whose registered source path or SHA-256 matches, even on a later
+date, instead of creating a duplicate. Never silently combine unrelated sources
+into an existing project.
+
+This location is an agent convention, not hidden CLI state: continue to pass the
+explicit `--root`, `--workspace`, input, and output paths to every command. A
+user-provided location always overrides the convention.
+
+## CLI workspace layout
+
 `video-edit-cli workspace init --root <path> --source <file>...` creates:
 
 ```text