Skill: Pipeline Orchestration
What
The definitive routing table for GatorSquare Studio. When a task arrives, this skill tells you: which agent handles it, what files they need, what they produce, and who runs next.
Why
Without this, agents duplicate work, skip steps, miss files, or run in wrong order. The pipeline is a chain — every link depends on the one before it.
The Pipeline Chain
┌─── LEGACY PROJECT? ───┐
│ │
▼ ▼
Format Migrator Standard Pipeline
(agents/format- (Steps 1-14)
migrator.md) │
│ │
▼ │
QA Patchup ◄─────────────────┘
(agents/qa-patchup.md)
│
▼
Gallery + Export
Step 0: Project Scaffolding (NON-NEGOTIABLE)
Before ANY agent touches a new project, scaffold the folder structure first.
python scripts/scaffold-project.py {project-id}
This creates:
projects/{project-id}/
├── memory/
│ └── memory.md ← empty template, ready for agents
├── learning-log.md ← empty template
├── STATUS.md ← initialized with "Pipeline: SCAFFOLDED"
└── panels/ ← empty, ready for images
Why this exists: Agents are unreliable at creating memory files. The QA audit found 3 out of 4 session-1 projects missing learning-log.md and memory/memory.md. Scaffolding guarantees the structure exists before any agent runs.
When to scaffold:
- Pipeline Manager creates the folder IMMEDIATELY after the investigation angle is approved
- Before spawning the Researcher agent
- The Researcher then READS
memory/memory.md (it exists, even if empty) and WRITES to it
Do NOT rely on agents to create these files. They will skip it under time pressure.
Agent Routing Table
| Signal | Agent | Reads | Produces | Next Agent |
|---|
| "New topic / investigation" | Pipeline Manager (you) | creator input | Angle proposal + scaffold project | Researcher |
| "Research this" | Researcher | users.csv, projects.csv, web | brief.md | Writer (after approval) |
| "Write the plot" | Writer | brief.md, template | plot.md | Writer-Script (after approval) |
| "Write the script" | Writer | brief.md, plot.md, template | script.md | Director (after approval) |
| "Direct the scenes" | Director | script.md | scene-plan.md | Editorial Design |
| "Design the viewer" | Editorial Design | script.md, scene-plan.md | presentation block | Prompter (or Assembler if text-only) |
| "Generate images" | Generator | scene-plan.md, prompts.json, objects/ | panels/*.png | Assembler |
| "Assemble investigation" | Assembler | script.md, scene-plan.md, panels/ | investigation.json | QA Patchup |
| "Validate everything" | QA Patchup | investigation.json, knowledge.json, metadata.json | .qa-pass, QA-REPORT.md, gallery build, export.zip | Learning Agent |
| "Learn from this project" | Learning Agent | learning-log.md, logs.md, skills/ | Updated skills, logs.md | — (end of pipeline) |
| "Migrate legacy format" | Format Migrator | investigation.json (legacy), objects/, script.md | investigation.json (canonical), knowledge.json, metadata.json | QA Patchup |
| "Something's broken" | QA Patchup | all project files | fixes + QA-REPORT.md | — |
| "Feedback from review" | Pipeline Manager | feedback.json | patched sources | QA Patchup (re-validate) |
Every Agent's Standing Orders
ALL agents MUST:
1. READ skills/INDEX.md before starting. Identify relevant skills. Load them.
2. READ skills/gatorsquare-voice.md if writing ANY content.
3. WRITE to projects/{id}/learning-log.md — what worked, what failed, what you'd do differently.
4. CHECK projects/{id}/memory/memory.md — read it if it exists, create it if it doesn't.
5. UPDATE projects/{id}/STATUS.md with current pipeline step.
Include in EVERY sub-agent brief:
"Before starting:
1. Read skills/INDEX.md and load skills relevant to your task.
2. Read skills/gatorsquare-voice.md if writing any content.
3. Read projects/{id}/memory/memory.md for project context.
4. Log learnings to projects/{id}/learning-log.md.
5. Update projects/{id}/STATUS.md when done."
Detection: Is This a Legacy Project?
Before running QA or export on ANY project, check:
# Quick detection — any of these = legacy format = needs Format Migrator first
legacy_signals = [
'"comic_id"' in investigation_json, # should be project_id
'"panels"' in investigation_json # should be moments (check it's the array, not a number)
and '"moments"' not in investigation_json,
'"narration"' in investigation_json, # should be text
'panel": ' in investigation_json # integer panel, not panel_id string
and '"panel_id"' not in investigation_json,
]
if any(legacy_signals):
→ Run Format Migrator FIRST
→ Then QA Patchup
→ Then proceed
File Requirements Per Project (Complete)
Every project folder MUST have after full pipeline:
projects/{id}/
├── investigation.json REQUIRED — viewer data (canonical format)
├── knowledge.json REQUIRED — entity/causal graph
├── metadata.json REQUIRED — platform metadata (25+ fields)
├── .qa-pass REQUIRED — validation stamp (gates gallery)
├── QA-REPORT.md REQUIRED — validation details
├── STATUS.md REQUIRED — pipeline state
├── memory/
│ └── memory.md REQUIRED — project working memory
├── learning-log.md REQUIRED — per-project learnings
│
├── brief.md IF RESEARCHED — research synthesis
├── plot.md IF PLOTTED — narrative structure
├── script.md IF SCRIPTED — panel narrations
├── scene-plan.md IF DIRECTED — visual direction
├── prompts.json IF ILLUSTRATED — image prompts
├── panels/{style}/*.png IF ILLUSTRATED — generated images
├── objects/{name}/ IF HAS CHARACTERS — reference sheets
├── export/{id}.zip IF EXPORTED — final package
│
├── investigation.json.legacy IF MIGRATED — original preserved
├── index.html.legacy IF MIGRATED — custom viewer preserved
├── migration-log.md IF MIGRATED — migration details
What Goes in Each JSON (Never Confuse)
investigation.json → FOR THE VIEWER
project_id, title, subtitle, author, layout, default_style
characters (with NARRATOR), moments[], presentation, cost_summary
Per-moment: panel_id, speaker, text, image, word_count, metadata{}
metadata.json → FOR THE PLATFORM
title, subtitle, summary, description, author, tags (10-20)
topic_categories (2-4), systems_mapped, key_figures
geographic_focus, historical_period, investigation_type
cross_references, research_summary, confidence_level
knowledge.json → FOR THE GRAPH — Generated by the GatorSquare platform after upload. NOT produced by the studio.
Rule: The viewer reads ONLY investigation.json. The platform reads ALL THREE. They never merge.
Common Mistakes (Avoid These)
- Running QA on a legacy project → QA can't fix format drift. Run Format Migrator first.
- Knowledge graphs are generated automatically by www.gatorsquare.com when you upload the export ZIP. The studio does not extract knowledge.
- Hand-editing investigation.json → Rebuild from sources instead. Hand edits get overwritten.
- Forgetting build-gallery.py → QA Patchup now runs this automatically after stamping .qa-pass (Post-QA Chain). If you skip QA, projects stay invisible.
- Auto-generating metadata in export → Use canonical metadata.json from Step 6. export.py already does this (fixed).
- Missing memory/memory.md → Next session has no project context. Always create.
- Spawning sub-agent without skills directive → Agent produces generic output. Always include INDEX.md instruction.
- Opening viewer directly instead of gallery → Creator should always enter via gallery.html.
- Writing .qa-pass manually → Only QA Patchup writes stamps. It validates first.
- Merging the three JSONs → investigation.json is story. metadata.json is project. knowledge.json is intelligence. NEVER combine.
When the user uploads a ZIP to www.gatorsquare.com, the platform extracts:
- Entities (8 categories)
- Causal links
- Causal chains
- Systems
- Themes
- Cross-references
This is proprietary extraction — the studio does not need knowledge extraction skills.