File Structure¶

The pipeline lives across many folders, but you only ever touch one of them directly: manager/. Everything else is read by Claude on your behalf. This page maps the layout so you know where things are when you need to find them — and what you can safely leave alone.

The top level¶

Everything sits under claude-projects/, a folder that holds the manager and every specialized agent as sibling folders.

claude-projects/
├── manager/                ← YOU EDIT FILES HERE
├── manager-wiki/           ← This wiki you're reading
│
├── script-writer/          ← Agent: writes scripts
├── visual-planner/         ← Agent: produces storyboards
├── nanobanana-prompter/    ← Agent: writes image prompts
├── veo-prompter/           ← Agent: writes Veo 3.1 prompts
├── seedance-prompter/      ← Agent: writes Seedance prompts
├── strategist/             ← Agent: content strategy
├── viral-scanner/          ← Agent: trend research
├── generation-runner/      ← Agent: executes workflows
├── knowledge-updater/      ← Agent: updates agent knowledge
└── patchwork-importer/     ← Agent: builds .nbflow files

Only manager/ is your editing surface. When you ask Claude to write a script, it routes that to script-writer/ for you — but you don't open files there. The agents read their own CLAUDE.md and reference material automatically; your end of the conversation happens through chat + files in manager/.

Why the agent folders are separate¶

Each agent is its own Claude project with its own CLAUDE.md rules, its own reference material, and its own narrow specialty. Keeping them as sibling folders means:

Updates to one agent don't risk regressing another
Each agent's context is self-contained (no cross-contamination)
New agents can be added or swapped without touching the others

For day-to-day work this is invisible. You ask the Manager for something; the Manager delegates to the right specialist. The fact that there are 10+ folders involved doesn't affect what you do.

You'd open a non-manager folder only if you wanted to change how an agent behaves — e.g., update the Image Prompter's rules for a new model. That's a knowledge-updater task, and even then, you describe what you want and Claude does the file work.

Inside `manager/`¶

This is where you'll spend all your file-editing time.

manager/
├── CLAUDE.md                       Manager's orchestration rules
│
├── reference/                      Source-of-truth data files
│   ├── brands/                       One .md per brand (voice, banned/approved angles)
│   ├── products/                     One .md per product (ingredients, claims)
│   ├── accounts.md                   All accounts with archetypes + settings
│   ├── avatar-sheets/                3-panel avatar reference photos
│   ├── version-registry.json         Canonical "what's where" record
│   ├── agent-briefs/                 Specialized agent guidance
│   ├── creator-scans/                Researcher outputs
│   ├── video-plan-framework.md       Decision logic for what to create
│   └── ...
│
├── projects/                       Where the work happens
│   └── {month}/                      e.g. may/
│       └── {brand}/                    e.g. salvora/
│           ├── growth/                   Growth-content .nbflow workflows
│           │   ├── testing/                Work-in-progress V0-N files
│           │   ├── approved/               V1+ shipped files
│           │   └── backups/                Pre-edit snapshots
│           ├── sales/                    Sales-content .nbflow workflows
│           │   ├── testing/
│           │   ├── approved/
│           │   └── backups/
│           ├── Generations/              Generation Runner outputs (auto)
│           ├── Assets/                   Supporting files per workflow
│           │   └── {workflow}/             video-plan, storyboard, prompts,
│           │                               contact_sheets, reference_frames,
│           │                               generated-images, generated-videos
│           └── misc/                     Utility .nbflows (e.g. avatar refresh)
│
└── scripts/                        Local Python helpers
                                    (fan-out scripts, sheet sync, etc.)

What you write vs. what's auto-generated¶

A common point of confusion early on: which files do you edit, and which does the pipeline produce?

You write or edit	The pipeline auto-generates
`reference/brands/{brand}.md`	`.nbflow` files in `projects/.../testing/` or `approved/`
`reference/products/{product}.md`	`-generated.nbflow` files in `Generations/`
`reference/accounts.md`	Script + storyboard + prompt files under `Assets/{workflow}/`
Avatar reference photos in `reference/avatar-sheets/`	`version-registry.json` history entries
Brief / direction in chat (not as files)	`.bak-{date}` backups before destructive edits
Occasional `version-registry.json` corrections	R2 uploads of every generated image / video

The general rule: anything under projects/ is auto-generated. Everything under reference/ is yours.

You will sometimes patch a .nbflow directly — usually for a small surgical edit. But it's the Manager that does the patching; you describe the change in chat. If you find yourself manually editing JSON inside a .nbflow, stop and describe the change to Claude instead.

Finding things you need¶

A reference table for the most common "where is X?" questions. Every path below is relative to manager/.

Workflows (the `.nbflow` files)¶

Looking for	Path
Growth workflows you've shipped	`projects/{month}/{brand}/growth/approved/`
Growth workflows still in testing	`projects/{month}/{brand}/growth/testing/`
Sales workflows you've shipped	`projects/{month}/{brand}/sales/approved/`
Sales workflows still in testing	`projects/{month}/{brand}/sales/testing/`
Backups before destructive edits	`projects/{month}/{brand}/{growth\\|sales}/backups/{workflow}-V{N}.nbflow.bak-{YYYY-MM-DD}-{reason}`
Generation Runner outputs (`-generated.nbflow`)	`projects/{month}/{brand}/Generations/{workflow}-V{N}-generated-{date}-{time}.nbflow`
One-off utility workflows (not growth/sales)	`projects/{month}/{brand}/misc/`

The {month} part is lowercase month name (april, may, june). The {brand} is the brand slug (e.g. salvora).

Reference / source-of-truth files¶

Looking for	Path
Brand rules (voice, approved/banned angles, CTA style)	`reference/brands/{brand}.md`
Product details (ingredients, claims, competitor positioning)	`reference/products/{product}.md`
All accounts (archetypes, settings, video types, current scripts)	`reference/accounts.md`
Avatar reference photo files (3-panel JPGs/PNGs)	`reference/avatar-sheets/{account}.{jpg\\|png}`
R2 URLs for avatar refs (canonical registry)	`reference/avatar-sheets/r2-urls.md`
Version registry (every workflow's current version, status, fan-out state)	`reference/version-registry.json`
Agent briefs (specialized guidance for the agents)	`reference/agent-briefs/`
Creator scans (Researcher outputs)	`reference/creator-scans/`
Video plan framework (decision logic for what to create, copy vs. original ratios)	`reference/video-plan-framework.md`

Per-workflow supporting files¶

These all live under projects/{month}/{brand}/Assets/{workflow}/. Each workflow gets its own subfolder.

Looking for	Path inside `Assets/{workflow}/`
Video plan (script + Schwartz framework)	`video-plan.md`
Visual storyboard	`storyboard.md`
Source video (for copy workflows)	`source.mp4`
Contact sheets (from source video)	`contact_sheets/sheet_NN.jpg`
Reference frames (best frame per scene from source)	`reference_frames/scene_NN.jpg`
Per-scene image prompts	`main-body/scene-NN-image-start.json`
Per-scene Veo video prompts	`main-body/scene-NN-video.txt`
B-roll prompts (image + video)	`broll/broll-NN-image.json`, `broll/broll-NN-video.txt`
Prehook prompts	`prehooks/prehook-NN-image.json`, `prehooks/prehook-NN-video.txt`
Generated images (final picks, organized by version)	`generated-images/v0-N/scene-NN.png`
Generated videos (final picks)	`generated-videos/v0-N/scene-NN.mp4`
Prompt-tuning iteration outputs	`qa_loop/v0-N/scene-NN-rN.png`
Variant checklist (STANDARD vs CUSTOMIZED per account)	`variant-checklist.md`

Configuration files¶

Looking for	Path
Manager's orchestration rules	`CLAUDE.md` (root of `manager/`)
An agent's behavior rules	`../{agent-name}/CLAUDE.md` (in the sibling folder, e.g. `../script-writer/CLAUDE.md`)
Local helper scripts (fan-out, sheet sync, etc.)	`scripts/`

Quick lookup patterns¶

If you ever forget, these are the patterns to remember:

reference/ = source-of-truth files you write (brands, products, accounts, version registry, avatar refs)
projects/{month}/{brand}/ = where workflows live, organized by month and brand
growth/ vs sales/ = content type — growth content lives here, sales content lives there
testing/ vs approved/ = lifecycle — V0-N work-in-progress vs V1+ shipped
Assets/{workflow}/ = everything ABOUT a workflow (scripts, prompts, generated outputs, QA loop) lives in its own subfolder
Generations/ = where the Generation Runner drops -generated.nbflow files

You'll absorb this pattern quickly once you've worked through Chapter 9 (adding a product / account) and Chapter 12 (creating from scratch) — both walk through producing real files in real folders.

What never goes in `manager/`¶

API keys, .env files, credentials — these live outside the repo, configured per-machine
Generated raw video files — Veo outputs go to R2, not your local drive (the .nbflow references the R2 URLs)
Drafts / experiments outside the pipeline — if you want to play around, do it in a separate folder

The .gitignore already covers most accidents, but it's worth knowing.

Where this wiki lives¶

manager-wiki/ is a separate sibling folder from manager/. It's its own git repo, its own deployable site. You're reading the built version at https://manager-wiki.pages.dev/. The source markdown is under manager-wiki/docs/.

You don't normally edit the wiki — but if you do (typo fix, new section), it's a normal markdown file and the GitHub Pages workflow rebuilds the site on push.

Try this¶

Open manager/ in your file browser and locate three specific things — without help.

Steps:

Find the brand file for the brand you're working on (reference/brands/{brand}.md). Confirm it exists and has the banned/approved angles you expect.
Find the version registry (reference/version-registry.json). Open it. Find one workflow you've shipped recently — confirm its current_version and fanned_out_to_accounts match what you remember.
Find the latest .nbflow for one of your workflows. Path is projects/{month}/{brand}/{growth|sales}/approved/{workflow}-V{N}.nbflow. Open it (it's JSON) just to confirm it looks like a workflow file — don't edit anything.

If you hit:

You can't find the brand file — it may not exist yet. See Chapter 9 — Add a new product / account for setting up a new brand
The version registry shows a different version than you expected — registry is the source of truth. Trust it; what you remember is probably stale
The .nbflow is huge JSON that's hard to read — that's normal. The file isn't meant to be human-read; it's PatchWork's serialization format. See .nbflow schema reference only if you're improving the system
You're tempted to manually edit a .nbflow — don't. Describe the change to Claude; the Manager has helpers that patch + back up safely

When you're ready¶

→ Next: Ground Rules — operational ground rules around security, cost awareness, and how to handle multiple workflows without dropping context.