story_development_run
BUILD new structured story material that does not exist yet — beats, scenes, sequences, treatments, trailer cards, episodes, weave plans, or the staged Novel adaptation lifecycle. Novel manuscript generation is the explicit exception: it WRITES empty Chapters or REWRITES existing Chapter prose into editable, revision-checked review candidates. Use this for concept-to-outline work; for a raw concept or brand-new project, prefer the `story_bootstrap` path first and let BeatBandit own the template-native beat-and-outline bootstrap workflow internally. The outline step is resolved from the project template: scenes for scene-oriented templates, episodes for episodic templates, or an explicit weave handoff for season-planning templates. For `story_bootstrap`, call `phase=readiness` before `phase=start` to inspect beat-style choices, the curated default start payload, any advisory style suggestion, and estimated credits. Then call `phase=start` with `payload.idea` and explicit `payload.options.style_template_id` if you choose a non-default beat style, then poll `job_get` until completion instead of switching to low-level card, scene, or episode mutations. `story_bootstrap` auto-applies its internal stages. Standalone jobs such as `treatment_wizard`, `sequence_wizard`, `beat_wizard`, `scene_wizard`, and `episode_wizard` still require their explicit `phase=finalize` follow-up when `job_get` says `finalize_required`. `target_scene_count` is a pacing hint rather than a hard guarantee, and `append` is only supported for movie-project scene finalization.
When to use
The structured material does not exist yet — the verb is BUILD — except for Novel manuscript generation, whose verbs are WRITE and REWRITE through review candidates.
Use for beat, scene, sequence, treatment, trailer, episode, and weave development flows.
Use `workflow=novel_adaptation` with `payload.novel_operation` for source creation/import, Blueprint, Chapter Outline, Voice Lab, manuscript generation, or candidate review. Manuscript readiness returns one exact word-volume price and `quote_hash`; start must carry that hash with the same scope and `payload.instructions`. Existing Chapters become editable candidates; a valid delivered rewrite is charged before review, while accept or reject is an unmetered author decision that may resume the same parent job. Accept with exact `expected_revisions` and optional complete edited `candidate_plain_texts`, or reject to leave canon unchanged.
For source-project readiness, include the intended `target_name`; readiness returns an executable start action locked to that name and the inspected source revision.
Poll Novel parent jobs through `job_get`. Completed Blueprint and Chapter Outline parents already saved their artifacts; completed Writer and Audit parents point to manuscript/candidate or audit reads. Completed Voice parents return the proposal resource and revision-current profile apply actions.
Use `story_bootstrap` when the caller has a raw idea and wants BeatBandit to turn it into initial story structure plus the template's canonical outline with sane defaults.
For `story_bootstrap`, call `phase=readiness` before `start`; readiness returns `available_beat_styles`, `default_beat_style_id`, optional `suggested_beat_style_id`, `estimated_credits`, and a `start_payload_template`.
Treat `suggested_beat_style_id` as advisory. `start` uses the default style unless the caller explicitly passes `payload.options.style_template_id`.
For `treatment_wizard`, call `phase=readiness` before `start`; readiness returns `available_templates` and `default_template_id` to use as `payload.template_id`.
For `one_scene` projects, `story_bootstrap` routes through Beat Wizard because the template already owns exactly one scene; Scene Wizard is not needed.
For episodic templates, use `episode_wizard` readiness to discover `available_approaches`, `default_approach_id`, valid episode counts, and an executable start payload before generating episode lists.
`beat_wizard` is always ready. Use `phase=readiness` to discover the default `template_id` and required placeholders such as `FULL_TEXT`.
For `beat_wizard` with the `free_text` template, callers may provide `payload.idea`; MCP will normalize it into `filled_text` and `placeholder_values.FULL_TEXT`.
When not to use
Do not use for screenplay document reads or direct story mutations.
Do not start with low-level card/scene mutation when the real intent is concept-to-outline development.
Do not manually drive the internal beat->outline chain once `story_bootstrap` is running; use `job_get` until the parent bootstrap job completes.
Do not skip `story_bootstrap` readiness before a paid bootstrap run; use readiness to choose or confirm the beat style and estimate credits.
Do not use to **change or polish** existing story material — use `story_revision_run` (change_wizard, polish_wizard, creative_canvas) instead.
Do not use to **get editorial feedback** on existing material — use `story_review_run` (room_review, analysis_wizard, continuity_audit) instead.
Do not use to **write actual screenplay prose** from an existing outline — use `screenplay_generation_run` (screenplay_writer, episode_screenplay, scene_screenplay) instead.
Do not use Novel operations to overwrite canonical Chapter prose directly; manuscript generation produces revision-checked candidates.
Examples
“Run a sequence wizard for this project.”
“Generate a new scene list for this project with the scene wizard.”
“Run the episode wizard on this project.”
“Run weave planning for this episodic project.”
“Bootstrap a short-movie project from one idea into initial story structure and a tight scene outline.”
“Bootstrap a micro-drama project from one idea into series cards and a template-native episode outline.”
“Bootstrap a one-scene short from a raw idea; BeatBandit will use Beat Wizard to populate the story cards and the single scene outline.”
“Start one-scene Beat Wizard with `payload={"idea":"..."}` or with `payload={"template_id":"free_text","placeholder_values":{"FULL_TEXT":"..."}}`.”
“Boundary - "Generate a fresh scene outline for this project." Use `scene_wizard` here because the scenes do not exist yet; this is BUILD, not CHANGE.”
“Boundary - "Bootstrap a movie project from one concept." Use `story_bootstrap` here because the caller wants structured outline first, not screenplay prose.”
“Check Story Bootstrap readiness with `workflow=story_bootstrap`, `phase=readiness`, and `payload.idea`; review `available_beat_styles`, then start with the returned payload.”
“Run Novel Blueprint readiness with `workflow=novel_adaptation`, `phase=readiness`, and `payload.novel_operation=blueprint`.”
“Start Novel Wizard or Chapter Wizard with the exact typed `payload.wizard_settings` returned by readiness, changing only the author-directed fields requested for that run.”
“After a Novel Wizard or Chapter Wizard job completes, follow `job_get` to the saved Blueprint or Chapter artifacts; no caller finalize is required.”
“Rewrite one existing Novel Chapter with `novel_operation=manuscript_generation`, carrying the exact `quote_hash`, Chapter scope, and instructions returned by readiness into start; poll `job_get`, then inspect candidates with `project_query(mode=novel, novel_mode=candidates)` when author review is required.”
“Accept an edited Novel candidate with `phase=accept`, `novel_operation=candidate_review`, its `child_job_id`, exact `expected_revisions`, and `candidate_plain_texts` keyed by Chapter card id; continue polling the returned parent job when the response is async.”
Anti-examples
- List my projects.
- Polishing dialogue rhythm in an existing scene — that is `story_revision_run` with `polish_wizard`.
- Generating screenplay prose from an already-finished outline — that is `screenplay_generation_run` with `screenplay_writer`.
- Asking for editorial scores or notes on the current story without changing it — that is `story_review_run` with `analysis_wizard` or `room_review`.
Workflows
Switch behavior by setting the workflow input field.
story_bootstrap
beat_wizard
scene_wizard
sequence_wizard
treatment_wizard
trailer_wizard
episode_wizard
weave
novel_adaptation
Linked resources
Tool calls may return resource_links pointing at these resource families.
Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"workflow",
"phase"
],
"properties": {
"workflow": {
"type": "string",
"enum": [
"beat_wizard",
"scene_wizard",
"sequence_wizard",
"treatment_wizard",
"trailer_wizard",
"episode_wizard",
"weave",
"story_bootstrap",
"novel_adaptation"
],
"description": "Use story_bootstrap for raw ideas; call phase=readiness first to inspect beat-style options, the default start payload, and estimated credits. Bootstrap resolves the template-native outline step (scenes, episodes, or explicit weave handoff) from the project template."
},
"phase": {
"type": "string",
"enum": [
"readiness",
"start",
"finalize",
"apply",
"accept",
"reject"
],
"description": "For story_bootstrap, use readiness before start; start still requires payload.idea."
},
"project_id": {
"type": "integer"
},
"job_id": {
"type": "string"
},
"reservation_id": {
"type": "string"
},
"payload": {
"type": "object",
"properties": {
"idea": {
"type": "string",
"description": "Raw story idea. Required for story_bootstrap start. For beat_wizard start, MCP normalizes this into the template's required placeholder values when possible."
},
"template_id": {
"type": "string",
"description": "Template id for template-driven workflows. Use phase=readiness to discover available treatment templates and defaults."
},
"filled_text": {
"type": "string",
"description": "Filled text passed to the wizard. For free_text beat_wizard templates, this can be the same story idea text used for placeholder_values.FULL_TEXT."
},
"placeholder_values": {
"type": "object",
"description": "Placeholder values required by the selected wizard template. For one_scene/free_text Beat Wizard, provide FULL_TEXT; if omitted, MCP can derive it from payload.idea or payload.filled_text.",
"additionalProperties": {
"type": "string"
}
},
"include_context": {
"type": "boolean"
},
"options": {
"type": "object",
"description": "Workflow-specific options. For story_bootstrap start, set options.style_template_id only after choosing from available_beat_styles returned by readiness."
},
"llm_identifier": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Optional provider/model override for this run, for example openai/gpt-5.6-sol. Uses the caller's saved default when omitted."
},
"approach_id": {
"type": "string"
},
"custom_prompt": {
"type": "string"
},
"target_scene_count": {
"type": "integer",
"description": "Preferred scene-count target for scene-oriented workflows. This is a pacing hint, not a strict requirement."
},
"target_episode_count": {
"type": "integer"
},
"episode_count": {
"type": "integer"
},
"sequence_numbers": {
"type": "array",
"items": {
"type": "integer"
}
},
"locked_episode_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"mode": {
"type": "string"
},
"target_episode_id": {
"type": "string"
},
"preview": {
"type": "boolean"
},
"idempotency_key": {
"type": "string"
},
"append": {
"type": "boolean",
"description": "When finalizing scene generation, append to the existing scene list instead of replacing it. Currently supported only for movie projects."
},
"novel_operation": {
"type": "string",
"enum": [
"source_project",
"source_import",
"blueprint",
"chapter_outline",
"voice_lab",
"manuscript_generation",
"candidate_review"
]
},
"target_name": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"source_revision": {
"type": "string",
"pattern": "^[0-9a-f]{64}quot;
},
"template_settings": {
"type": "object"
},
"wizard_settings": {
"description": "Typed pre-generation direction for Novel Wizard or Chapter Wizard.",
"oneOf": [
{
"type": "object",
"required": [
"adaptation_brief",
"novel_genre",
"prose_style",
"target_category",
"target_word_count",
"fidelity",
"pov_approach",
"tense"
],
"properties": {
"adaptation_brief": {
"type": "string",
"maxLength": 6000
},
"novel_genre": {
"type": "string",
"enum": [
"inherit_source",
"contemporary_drama",
"mystery_crime",
"thriller_suspense",
"romance",
"horror",
"fantasy",
"science_fiction",
"historical",
"adventure",
"comic_satirical"
]
},
"prose_style": {
"type": "string",
"enum": [
"balanced",
"propulsive",
"intimate",
"spare_precise",
"lyrical",
"atmospheric",
"comic"
]
},
"target_category": {
"type": "string",
"enum": [
"adult",
"young_adult",
"middle_grade"
]
},
"target_word_count": {
"type": "integer",
"enum": [
45000,
60000,
75000,
90000,
105000
]
},
"fidelity": {
"type": "string",
"enum": [
"wizard_decide",
"faithful",
"balanced",
"transformative"
]
},
"pov_approach": {
"type": "string",
"enum": [
"wizard_decide",
"single_character",
"multiple_character",
"omniscient"
]
},
"tense": {
"type": "string",
"enum": [
"wizard_decide",
"past",
"present"
]
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"planning_guidance",
"chapter_rhythm"
],
"properties": {
"planning_guidance": {
"type": "string",
"maxLength": 6000
},
"chapter_rhythm": {
"type": "string",
"enum": [
"story_led",
"shorter_propulsive",
"longer_immersive"
]
}
},
"additionalProperties": false
}
]
},
"screenplay_text": {
"type": "string",
"maxLength": 1500000
},
"story_outline_text": {
"type": "string",
"maxLength": 1500000
},
"screenplay_filename": {
"type": "string",
"maxLength": 240
},
"story_outline_filename": {
"type": "string",
"maxLength": 240
},
"screenplay_file": {
"type": "object",
"required": [
"filename",
"media_type",
"base64"
],
"properties": {
"filename": {
"type": "string"
},
"media_type": {
"type": "string"
},
"base64": {
"type": "string",
"maxLength": 20000000
}
},
"additionalProperties": false
},
"story_outline_file": {
"type": "object",
"required": [
"filename",
"media_type",
"base64"
],
"properties": {
"filename": {
"type": "string"
},
"media_type": {
"type": "string"
},
"base64": {
"type": "string",
"maxLength": 20000000
}
},
"additionalProperties": false
},
"representative_chapter_ids": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"profile_id": {
"type": "string"
},
"expected_contract_revision": {
"type": "integer",
"minimum": 0
},
"expected_proof_revision": {
"type": "integer",
"minimum": 0
},
"scope_kind": {
"type": "string",
"enum": [
"chapter",
"range",
"full"
]
},
"quote_hash": {
"type": "string",
"pattern": "^[0-9a-f]{64}quot;,
"description": "Exact immutable manuscript price/input quote returned by readiness. Required unchanged at start."
},
"start_chapter_card_id": {
"type": "integer",
"minimum": 1
},
"end_chapter_card_id": {
"type": "integer",
"minimum": 1
},
"instructions": {
"type": "string",
"maxLength": 10000,
"description": "Run-specific direction for Novel manuscript generation. Readiness and start must receive the same value."
},
"child_job_id": {
"type": "string"
},
"expected_revisions": {
"type": "object",
"description": "Current manuscript revisions keyed by Chapter card id. Required when accepting a Novel manuscript candidate.",
"propertyNames": {
"pattern": "^[1-9][0-9]*quot;
},
"additionalProperties": {
"type": "integer",
"minimum": 0
}
},
"candidate_plain_texts": {
"type": "object",
"description": "Optional edited Chapter prose keyed by Chapter card id. Send the complete proposed prose for every edited Chapter when accepting a candidate; BeatBandit materializes the canonical manuscript document.",
"minProperties": 1,
"propertyNames": {
"pattern": "^[1-9][0-9]*quot;
},
"additionalProperties": {
"type": "string",
"minLength": 1,
"maxLength": 1000000
}
}
},
"additionalProperties": false
}
},
"allOf": [
{
"if": {
"not": {
"properties": {
"workflow": {
"const": "novel_adaptation"
},
"payload": {
"properties": {
"novel_operation": {
"const": "source_import"
}
},
"required": [
"novel_operation"
]
}
},
"required": [
"workflow",
"payload"
]
}
},
"then": {
"required": [
"project_id"
]
}
},
{
"if": {
"properties": {
"workflow": {
"const": "story_bootstrap"
}
}
},
"then": {
"properties": {
"phase": {
"enum": [
"readiness",
"start"
]
}
}
}
},
{
"if": {
"properties": {
"workflow": {
"const": "story_bootstrap"
},
"phase": {
"const": "start"
}
}
},
"then": {
"required": [
"payload"
],
"properties": {
"phase": {
"enum": [
"readiness",
"start"
]
},
"payload": {
"type": "object",
"required": [
"idea"
]
}
}
}
},
{
"if": {
"properties": {
"workflow": {
"const": "sequence_wizard"
}
}
},
"then": {
"properties": {
"phase": {
"enum": [
"start",
"finalize"
],
"description": "sequence_wizard does not support readiness; use start directly, then poll job_get and finalize."
}
}
}
},
{
"if": {
"properties": {
"workflow": {
"const": "novel_adaptation"
}
},
"required": [
"workflow"
]
},
"then": {
"required": [
"payload"
],
"properties": {
"payload": {
"required": [
"novel_operation"
]
}
}
}
},
{
"if": {
"properties": {
"workflow": {
"const": "novel_adaptation"
},
"payload": {
"properties": {
"novel_operation": {
"const": "source_project"
}
},
"required": [
"novel_operation"
]
}
},
"required": [
"workflow",
"payload"
]
},
"then": {
"required": [
"project_id",
"payload"
],
"properties": {
"payload": {
"required": [
"target_name"
]
}
}
}
},
{
"if": {
"properties": {
"workflow": {
"const": "novel_adaptation"
},
"phase": {
"const": "start"
},
"payload": {
"properties": {
"novel_operation": {
"const": "source_project"
}
},
"required": [
"novel_operation"
]
}
},
"required": [
"workflow",
"phase",
"payload"
]
},
"then": {
"properties": {
"payload": {
"required": [
"source_revision"
]
}
}
}
},
{
"if": {
"properties": {
"workflow": {
"const": "novel_adaptation"
},
"payload": {
"properties": {
"novel_operation": {
"const": "source_import"
}
},
"required": [
"novel_operation"
]
}
},
"required": [
"workflow",
"payload"
]
},
"then": {
"properties": {
"phase": {
"const": "start"
},
"payload": {
"required": [
"target_name"
],
"anyOf": [
{
"required": [
"screenplay_text"
]
},
{
"required": [
"story_outline_text"
]
},
{
"required": [
"screenplay_file"
]
},
{
"required": [
"story_outline_file"
]
}
],
"allOf": [
{
"not": {
"required": [
"screenplay_text",
"screenplay_file"
]
}
},
{
"not": {
"required": [
"story_outline_text",
"story_outline_file"
]
}
}
]
}
}
}
},
{
"if": {
"properties": {
"workflow": {
"const": "novel_adaptation"
},
"phase": {
"const": "start"
},
"payload": {
"properties": {
"novel_operation": {
"const": "voice_lab"
}
},
"required": [
"novel_operation"
]
}
},
"required": [
"workflow",
"phase",
"payload"
]
},
"then": {
"required": [
"project_id",
"payload"
],
"properties": {
"payload": {
"required": [
"representative_chapter_ids"
]
}
}
}
},
{
"if": {
"properties": {
"workflow": {
"const": "novel_adaptation"
},
"phase": {
"const": "start"
},
"payload": {
"properties": {
"novel_operation": {
"enum": [
"blueprint",
"chapter_outline"
]
}
},
"required": [
"novel_operation"
]
}
},
"required": [
"workflow",
"phase",
"payload"
]
},
"then": {
"required": [
"project_id",
"payload"
],
"properties": {
"payload": {
"required": [
"wizard_settings"
]
}
}
}
},
{
"not": {
"properties": {
"workflow": {
"const": "novel_adaptation"
},
"phase": {
"const": "apply"
},
"payload": {
"properties": {
"novel_operation": {
"enum": [
"blueprint",
"chapter_outline"
]
}
},
"required": [
"novel_operation"
]
}
},
"required": [
"workflow",
"phase",
"payload"
]
}
},
{
"if": {
"properties": {
"workflow": {
"const": "novel_adaptation"
},
"phase": {
"const": "apply"
},
"payload": {
"properties": {
"novel_operation": {
"const": "voice_lab"
}
},
"required": [
"novel_operation"
]
}
},
"required": [
"workflow",
"phase",
"payload"
]
},
"then": {
"required": [
"project_id",
"job_id",
"payload"
],
"properties": {
"payload": {
"required": [
"profile_id",
"expected_contract_revision",
"expected_proof_revision"
]
}
}
}
},
{
"if": {
"properties": {
"workflow": {
"const": "novel_adaptation"
},
"phase": {
"enum": [
"readiness",
"start"
]
},
"payload": {
"properties": {
"novel_operation": {
"const": "manuscript_generation"
}
},
"required": [
"novel_operation"
]
}
},
"required": [
"workflow",
"phase",
"payload"
]
},
"then": {
"required": [
"project_id",
"payload"
],
"properties": {
"payload": {
"required": [
"scope_kind"
]
}
}
}
},
{
"if": {
"properties": {
"workflow": {
"const": "novel_adaptation"
},
"phase": {
"const": "start"
},
"payload": {
"properties": {
"novel_operation": {
"const": "manuscript_generation"
}
},
"required": [
"novel_operation"
]
}
},
"required": [
"workflow",
"phase",
"payload"
]
},
"then": {
"properties": {
"payload": {
"required": [
"quote_hash"
]
}
}
}
},
{
"if": {
"properties": {
"workflow": {
"const": "novel_adaptation"
},
"phase": {
"enum": [
"readiness",
"start"
]
},
"payload": {
"properties": {
"novel_operation": {
"const": "manuscript_generation"
},
"scope_kind": {
"enum": [
"chapter",
"range"
]
}
},
"required": [
"novel_operation",
"scope_kind"
]
}
},
"required": [
"workflow",
"phase",
"payload"
]
},
"then": {
"properties": {
"payload": {
"required": [
"start_chapter_card_id"
]
}
}
}
},
{
"if": {
"properties": {
"workflow": {
"const": "novel_adaptation"
},
"phase": {
"enum": [
"readiness",
"start"
]
},
"payload": {
"properties": {
"novel_operation": {
"const": "manuscript_generation"
},
"scope_kind": {
"const": "range"
}
},
"required": [
"novel_operation",
"scope_kind"
]
}
},
"required": [
"workflow",
"phase",
"payload"
]
},
"then": {
"properties": {
"payload": {
"required": [
"end_chapter_card_id"
]
}
}
}
},
{
"if": {
"properties": {
"workflow": {
"const": "novel_adaptation"
},
"payload": {
"properties": {
"novel_operation": {
"const": "candidate_review"
}
},
"required": [
"novel_operation"
]
}
},
"required": [
"workflow",
"payload"
]
},
"then": {
"required": [
"project_id",
"payload"
],
"properties": {
"phase": {
"enum": [
"accept",
"reject"
]
},
"payload": {
"required": [
"child_job_id"
]
}
}
}
},
{
"if": {
"properties": {
"workflow": {
"const": "novel_adaptation"
},
"phase": {
"const": "accept"
},
"payload": {
"properties": {
"novel_operation": {
"const": "candidate_review"
}
},
"required": [
"novel_operation"
]
}
},
"required": [
"workflow",
"phase",
"payload"
]
},
"then": {
"properties": {
"payload": {
"required": [
"expected_revisions"
]
}
}
}
},
{
"if": {
"properties": {
"workflow": {
"const": "novel_adaptation"
},
"phase": {
"const": "finalize"
},
"payload": {
"properties": {
"novel_operation": {
"enum": [
"blueprint",
"chapter_outline",
"voice_lab",
"manuscript_generation"
]
}
},
"required": [
"novel_operation"
]
}
},
"required": [
"workflow",
"phase",
"payload"
]
},
"then": {
"required": [
"project_id",
"job_id"
]
}
},
{
"if": {
"properties": {
"phase": {
"const": "finalize"
}
}
},
"then": {
"required": [
"job_id"
]
}
}
],
"additionalProperties": false
}Output schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"workflow",
"phase"
],
"properties": {
"workflow": {
"type": "string"
},
"phase": {
"type": "string"
},
"async": {
"type": "boolean"
},
"job_id": {
"type": "string"
},
"reservation_id": {
"type": "string"
},
"bootstrap_stage": {
"type": "string"
},
"project_id": {
"type": "integer"
},
"project_name": {
"type": "string"
},
"project_mode": {
"type": "string"
},
"append_supported": {
"type": "boolean"
},
"actual_scene_count": {
"type": "integer"
},
"bootstrap_context": {
"type": "object"
},
"readiness": {
"type": "object"
},
"result": {
"type": "object"
},
"resource_links": {
"type": "array",
"items": {
"type": "object"
}
},
"pipeline_state": {
"$ref": "./_common/pipeline_state.schema.json"
},
"next_actions": {
"type": "array",
"items": {
"$ref": "./_common/next_action.schema.json"
}
},
"credits_charged": {
"type": "number",
"minimum": 0
},
"credits_previously_committed": {
"type": "number",
"minimum": 0
},
"credit_status": {
"type": "string",
"enum": [
"quoted",
"reserved",
"committed",
"refunded",
"not_metered",
"unavailable"
]
},
"credits_quoted": {
"type": "number",
"minimum": 0
},
"credits_reserved": {
"type": "number",
"minimum": 0
},
"credits_refunded": {
"type": "number",
"minimum": 0
},
"credits_skipped_reason": {
"type": "string"
}
},
"additionalProperties": true
}