# Recoil Pipeline — Session SSOT (topography · tools · protocols)

> **Read this first.** One-screen orientation for any fresh session doing Recoil work
> (`/engine` loads it). It is a **map + pointer index**, not the detail — each line links to the
> canonical source that owns that detail. When this doc and a linked source disagree, the **linked
> source wins** and this doc is the bug. Keep it short; do not paste detail in here (that's how the
> old `WORKFLOW_SPEC.md` rotted — see Canonical Sources).
>
> Last verified: 2026-06-07.

---

## 1. Topography (what the system is)

```
NARRATIVE ENGINE                     VISUAL PIPELINE
recoil/                              recoil/pipeline/
develop→…→generate-script    ──►     scripts locked → frames → video
(text: episodes/, treatment)         (Recoil = brain/provenance/validation)
                                              │
                                     flora.py adapter
                                              ▼
                                     Flora  (models + canvas + hosting; execution target)
                                              ▼
                                     download → projects/<p>/renders/ep_NNN/*.mp4
```

- **Recoil is the brain.** It owns provenance, validation, prompt assembly, and the dispatch
  decision. **Flora is the commodity execution target** (models + canvas + hosting; ~30% cheaper
  than fal). Locked "Option D" — see `[[flora-architecture]]` memory + `recoil/pipeline/CLAUDE.md`.
- **EpisodeRunner** (`recoil/pipeline/orchestrator/episode_runner.py`, CP-10) is the **converged
  production path**. Every generation call routes through `dispatch()` →
  modality registry → `StepRunner` (never call API clients directly).
- **Workspace `127.0.0.1:8450`** (`recoil/workspace/server.py`) is the **active developer/review
  surface** (shot tree, take review, approve/reject, viewer). Console v2 is CANCELLED; ports
  8430/8420 are DEPRECATED — do not launch them.
- **Data lives outside the repo:** `projects_root` = `~/Dropbox/CLAUDE_DATA/recoil/projects/`
  (resolve via `recoil/core/paths.py` — `projects_root()` + the `ProjectPaths` class; **never hardcode**
  paths or layout). Per-project v3 layout: `scripting/{bible,episodes,development,compiled}/` +
  `scripting/treatment.md` (narrative), `_pipeline/{state,shot_plans,annotations,sessions,…}/` (pipeline
  state — visual state + `review_queue.jsonl` live under `_pipeline/state/visual/`),
  `assets/{char,loc,prop}/{subject}/{look}/`, `prep/ep_NNN/`, `renders/ep_NNN/`. **Canonical:
  `ProjectPaths` in `paths.py`** — resolve every path through it.
- **Overnight builds** run on the Mac Studio via the **dispatch chassis** (REC-77): detached tmux +
  `harness_orchestrator.sh`, per-run `status.json` SSOT, self-healing reaper. Entry: `/dispatch`.

## 2. The pipeline (phase flow; most phases have a validation gate)

**Narrative (recoil/):** `/develop` → `/validate` → `/promote` → `/treatment` →
`/generate-script` (or `/generate-script-orchestrated`) → `/finish` (script-doctor → revise → verify → `/compile`).
Per-episode rule: after every episode write, `python3 tools/episode_metrics.py <file> --json` must pass.

**Visual (recoil/pipeline/):** Script Lock → Camera Test → Global Bible → Enrichment → Plan Pass →
Casting → Location Refs → Previz → **Previz Review (Workspace)** → Keyframes → **Dailies Review
(Workspace)** → Video → Final Review + Export.

Operate the visual pipeline through `/engine` (operator session) + `/generate-video`; review/approve in
Workspace (8450). (`/pipeline` is **deprecated** as of 2026-06-07 — superseded by `/generate-video` +
Workspace; don't use it.) The **gate for a phase is its owning skill** (e.g. `/validate`, `/camera-test`),
not a single spec file. Coverage-pass strategy detail: `recoil/pipeline/docs/coverage-pass-strategy.md`;
phase order narrative: the "PIPELINE" section of `recoil/CLAUDE.md`.

## 3. Tools (the command set)

**The skill files are the per-command SSOT.** The live set lives in four dirs — `ls` them, don't trust
any enumerated table (they rot):
- `~/.claude/skills/` — global process/infra
- `~/CLAUDE_PROJECTS/.claude/skills/` — project ops
- `~/CLAUDE_PROJECTS/recoil/.claude/skills/` — narrative + visual engine commands
- `~/CLAUDE_PROJECTS/recoil/skills/` — engine knowledge (format_v12, dramatic_elements, treatment, …)

**Precedence when a command exists in more than one dir** (several do): the copy whose dir matches the
command's lane is canonical — process/infra (`/dispatch`, `/consult`, `/spec`, `/pause`…) → the **global
`~/.claude/skills/`** copy; engine commands (`/develop`, `/generate-video`, `/camera-test`…) → the
**in-repo `recoil/.claude/skills/`** copy. ⚠️ `/dispatch` specifically: only the global copy has the
REC-77 `status.json` chassis — use it, not a project copy. (Cross-dir duplicate skills are a known cleanup
debt; until deduped, follow this precedence.)

Most-used by lane (one-liners; open the skill for detail):
- **Session:** `/engine <project>` (operator bootstrap + this SSOT) · `/load-context` (narrative context) · `/workspace` (review UI).
- **Narrative:** `/develop` `/validate` `/promote` `/treatment` `/generate-script[-orchestrated]` `/finish` `/compile` `/script-doctor`.
- **Visual:** `/generate-video` `/camera-test` · review/approve via Workspace (8450). (`/pipeline` is **deprecated** — superseded by these.)
- **Build/decide:** `/consult` (dual-adversarial Codex↔Opus → SYNTHESIS) → `/spec` (SYNTHESIS → BUILD_SPEC) → `/dispatch` (overnight build on Studio) · `/spec-review`.
- **State/process:** `/pause` `/unpause` `/handoff` `/file` (→ Linear queue) `/report` `/log`.

## 4. Protocols (the hard rules)

1. **StepRunner-only.** All generation goes through `dispatch()` → registry → `StepRunner`/EpisodeRunner. Never call Kling/Flora/fal clients directly — not even for tests (`recoil/pipeline/CLAUDE.md`).
2. **No ad-hoc scripts.** Never bypass the unified pipeline with throwaway scripts. If the pipeline is broken, fix it (`CLAUDE_PROJECTS/CLAUDE.md`).
3. **No t2v in testing.** Always test with real shots/passes (r2v/i2v with refs), never text-to-video (`[[feedback-no-t2v-in-testing]]`).
4. **Validate before proceeding.** Every phase has a gate; every episode write is validated; don't claim done without running the live path (global `CLAUDE.md` rule 5).
5. **Spend gate.** Before any money-spending command, the `required_context.<domain>` files must be Read (PreToolUse hook enforces; `/engine` autoloads them). Builds on the OAuth subscription are $0 — don't gate on imaginary dollars.
6. **Supersede & retire.** When you replace a script/doc/config, retire the old one in the same change (delete or `_archive/` + tombstone). One live version only (global `CLAUDE.md` rule 8).
7. **Look first.** Before web/model research, search `consultations/`, both memory stores, and `roadmap/` (the prior-art hook auto-injects matches). Live API/probe beats public docs for tools we operate.
8. **SSOT, point don't copy.** Every piece of state has one canonical home; decisions point to their source, never restate the verdict (global `CLAUDE.md` Memory SSOT).
9. **Worktrees outside the repo only** (`~/Code/` or `/tmp`), never inside the tree.
10. **Director notes go to the owning layer.** JT's feedback on an output ("doesn't make physical sense", "X should be elsewhere") is fixed at its SSOT home (script / bible sublocation / blocking / motion_line), never by patching the artifact — procedure per note type: `recoil/docs/DIRECTOR_NOTES_PLAYBOOK.md`.

## 5. Canonical sources (the pointer index — go here for detail)

| For… | Canonical source |
|---|---|
| Capability → owning module/function | `recoil/architecture/ssot_manifest.yaml` |
| **Full pipeline workflow graph (every node · gate · fan-in input · rework loop)** | `recoil/architecture/topology/nodes/_render_overlay.yaml` — curated 4-agent audit projection (the Atlas render/flow SSOT); **not** auto-generated, drift-validated by `recoil/architecture/topology/tools/test_render_overlay_ssot.py`. Rendered via `tools/build_atlas_graph.py` → `generated/atlas.render.json` → the **recoil/docs/atlas.html** viewer. Retired the `pipeline_graph.yaml` + `build_pipeline_atlas.py` chain (2026-06-24). |
| **Director feedback → which layer to fix (verbal notes on outputs)** | `recoil/docs/DIRECTOR_NOTES_PLAYBOOK.md` |
| Visual pipeline topology, consoles, data locations | `recoil/pipeline/CLAUDE.md` |
| Narrative engine, V12 constraints, command list | `recoil/CLAUDE.md` |
| Coverage-pass / visual phase spec | `recoil/pipeline/docs/coverage-pass-strategy.md` |
| Path resolution (`RECOIL_ROOT`, `projects_root`) | `recoil/core/paths.py` |
| Models / pricing / routing | live tools `live_pricing()` / `live_model_status()`; `recoil/config/model_profiles.json` |
| Architectural laws (SSOT, theory-before-typing, build-the-loop) | `consultations/architectural-laws-general/SYNTHESIS.md` |
| Per-command behavior | the skill file itself (`ls` the four skill dirs above) |

> **Supersedes the orientation role of** `recoil/docs/WORKFLOW_SPEC.md` (1299 lines, stale for the
> visual pipeline — see its own staleness banner). That file is **retained for now only as the
> `/engine-check` audit target** (`recoil/agents/engine_check_agent.md` Section 5 reads it); fully
> archiving it requires repointing that audit first — tracked as a follow-up, not done here.