orchestrating-story-pipeline

name	orchestrating-story-pipeline
description	Coordinates the ADK story pipeline, manages state, retries, and fallbacks, and is used when the Showrunner Orchestrator runs the end-to-end story flow.

Runs the full multi-agent story loop from emotional intake to render-ready scene output.

Use this skill when

• The Showrunner Orchestrator is controlling the full story experience.
• The system needs to move work between agents with typed JSON handoffs.
• A scene must be retried, repaired, or gracefully degraded.
• The backend needs simple, reliable workflow control for the 6-day MVP.

Capabilities

• Starts and continues stories through the fixed pipeline:
  1. Emotional Cartographer
  2. Story Architect
  3. Choice Designer
  4. Visual Motion Director (provides style bible + character refs as input context)
  5. Scene Director (uses Gemini interleaved output: text + images in one call — satisfies mandatory hackathon requirement)
  6. Voice & Sound Designer
  7. Continuity & Meaning Editor
• Maintains shared story state:
  • current anchor (A1–A5)
  • decision index (D1–D4)
  • hidden variables (courage, compassion, truth, attachment, self_trust)
  • story bible
  • scene history
  • asset readiness
  • retry counts
• Validates every agent response as typed JSON before handoff.
• Retries only the failing step instead of regenerating the whole story.
• Applies graceful fallback:
  • motion plan fails → static image
  • image fails → text-only panel metadata
  • voice fails → captions only
• Explains orchestration choices in plain language when they affect product behavior.

Workflow

1. Explain the plan simply. Before major product-impacting behavior, briefly explain what the pipeline is about to do and why.
2. Start with intake. On POST /story/start, send the user's first text/voice transcript to the Emotional Cartographer.
3. Gate on confidence. If emotional confidence is too low, allow one clarifying follow-up before story generation.
4. Create the macro plan. Send the emotional map to the Story Architect to produce the story bible with 5 anchor nodes and 4 endings.
5. Enter the scene loop. For each anchor:
   • get choices if this anchor contains a decision point
   • generate scene panels
   • generate visual prompt/motion plan
   • generate voice/music plan
   • pass all of it through the Continuity Editor
6. Validate each handoff. If JSON is malformed or missing fields, reject it immediately and route back to the offending agent with precise feedback.
7. Retry narrowly. Allow up to 2 targeted retries per failing stage. Do not restart the entire pipeline unless the story bible itself is invalid.
8. Degrade gracefully. Preserve the story experience even when media generation is partial.
9. Return a clean response. Always return the next scene package plus updated session state.

Orchestration rules

• Keep the branching model hybrid and reconverging.
• Never let downstream agents invent new anchor nodes.
• Never skip evaluation before handoff.
• Do not add database complexity for MVP.
• Prefer browser-carried session state or lightweight in-memory state for demo simplicity.

Example state payload

{
  "session_id": "sess_123",
  "current_anchor": "A2",
  "current_decision": "D2",
  "hidden_state": {
    "courage": 1,
    "compassion": 2,
    "truth": 0,
    "attachment": 1,
    "self_trust": -1
  },
  "asset_status": {
    "images": "ready",
    "motion": "fallback_static",
    "voice": "ready"
  },
  "retry_counts": {
    "scene_director": 0,
    "visual_motion_director": 1,
    "voice_sound_designer": 0
  },
  "next_step": "render_scene"
}

Success checklist

• Every handoff is typed JSON.
• The story remains inside 5 anchors and 4 decision points.
• Failures route back to one agent, not the full chain.
• Story quality stays higher priority than fancy media.
• Fallbacks keep the demo alive.

Project references

• AGENTS.md — multi-agent roles, typed JSON rule, fallback rules, user-context guidance.
• docs/PRD.md — pipeline order, hidden state variables, 5 anchor nodes, 4 endings.
• docs/roadmap.md — MVP scope; avoid Phase 2 features like accounts, Firestore, or replay systems.