dramaclaw/dramaclaw/dramaclaw-workflows

DramaClaw Workflows

Build one coherent workflow transaction, not a sequence of standalone canvas edits.

Required behavior

• Planning authors topology, Recipe selection, dependencies, confirmed parameters, and short

node task briefs. Each node prompt should state its task, scope, upstream outputs, and reference roles in one or two concise sentences. Preserve user-provided story facts and source material. In a compact Intent, keep every user-confirmed quantity, named object, exclusion, and visual continuity anchor in user_goal; planner.units may distribute steps but must not replace those shared facts with a short summary. Do not invent details the user did not provide. Carry a confirmed visual style into each image/video task brief, or supply it through an actual consumed upstream text output; a Skill title or an unrelated node does not carry that style into a media node by itself. When a video consumes upstream images through media_input_for, select a reference-capable generation mode supported by its chosen Catalog model and reference count. Do not leave the mode unset or use textToVideo; an edge alone cannot make a text-only mode consume images. If no compatible mode is available, stop on the catalog/preflight blocker instead of dropping the media input or silently changing an explicit user choice. Do not invent finished scripts, detailed shot-by-shot storyboards, dialogue, camera choreography, sound cues, or final media prompts before upstream stages execute. Execution-time Recipe compilation uses actual upstream outputs to produce executable prompts.

• Read this Skill and its references only through the exact locator advertised by the current host.

Never invent project:// paths. Use a canvas summary already supplied by the host; if current canvas data must be refreshed, call freezone_get_canvas_ontology instead of inventing a canvas:// resource. MCP clients must use only resource URIs returned by resources/list or resources/templates/list. The Workflow MCP intentionally returns an empty static resources/list; this is supported and does not mean the catalog is unavailable. Discover accessible Skill/Recipe IDs with workflow_catalog_search, then use the advertised templates for resource reads. Do not enumerate or guess another user's private catalog IDs.

• The Skill package/server display name does not determine a host's MCP registration key. Use the

exact server returned by the host. In DramaClaw's Codex adapter, filesystem-backed Skill files are read from dramaclaw; workflow catalog resources use dramaclaw_workflows (underscore). Never call resources/read with an inferred dramaclaw-workflows server key.

• Use the portable dramaclaw-workflows MCP server for catalog discovery and deterministic

compilation when it is available. Use the authorized DramaClaw MCP server for draft persistence, approval, canvas commit, and execution. Tool names are host-neutral; call them through the MCP mechanism supported by the current agent.

• dramaclaw-workflows is this Agent Skill package/server name, not a Workflow catalog skill_id.

Never pass it to workflow_skill_get, freezone_get_workflow_skill, or an intent's skill_id. Select the matching production Workflow Skill returned by the catalog instead.

• Route an ordinary pure-image workflow to text-to-image. Use text-to-image-video only when

the user asks for a video stage, and use social-content-campaign only for an explicit social platform image-set request. Do not report a Skill conflict or ask the user to accept video merely because the older general video Skill also contains an image stage.

• Never implement a multi-node request by repeatedly calling freezone_create_node,

freezone_create_edge, freezone_group_nodes, or other single-operation tools.

• Never fall back to repeated single-operation writes after a workflow validation or schema error.

Correct the workflow intent/plan or report the blocking error.

• Never offer direct canvas commands or standalone node writes as a clarification choice for

bypassing WorkflowPlan validation. A user selection cannot authorize that bypass. When a Skill's required stage conflicts with an exact node-only constraint, report the conflict or ask whether the required stage may be added; do not offer an invalid direct-write alternative.

• During exact-Plan recovery, preserve the user's explicit media/result cardinality and existing

external-input edges. If the planning contract says a stage accepts_external_media, a connected input of that kind fills the stage; never add a generated replacement anchor for it. Add only the genuinely missing stage named by preflight (for example a required planning text node).

• Never resubmit an unchanged workflow payload. After one correction, if the same validation path

fails again in the same turn, stop retrying and report that blocker instead of increasing the failure counter.

• Treat the Workflow Intent schema as the serialization allowlist. Recipe discovery fields such as

requires_source_media are selection metadata only: use them to choose and connect Recipes, but never copy them into intent.items[]. The server derives authoritative Recipe constraints from recipe_id.

• For short-drama-quick, preserve screenplay-first planning: when narration/dialogue will be

produced by an upstream shot/script Recipe, keep the drama-shot-voice item and reference that text item. Do not invent literal narration at draft time, and never delete requested voiceover merely to pass validation; the runtime resolves the spoken text through the prompt_for edge.

• A failure from an earlier chat turn is diagnostic history, not proof that the current adapter is

still blocked. When the user repeats the original create/run request, explicitly asks to retry, or has restarted the service, retry the same complete workflow write once in the current turn. Never declare the current environment blocked without a same-turn write result showing the same failure.

• A confirmed workflow must be committed as one operation and must produce one approval surface.
• The deterministic workflow compiler owns node IDs, same-batch references, grouping, layout,

selection, and the final canvas_chat_commands.v1 batch.

• An explicit imperative to create or run authorizes submission to the protected canvas write tool.

Do not ask for a duplicate create/run confirmation and do not claim that the host cannot display the approval surface; the write tool emits it. In auto_execute, the host applies the ordinary approval event after required image/video parameters are known.

• Use freezone_request_user_clarification for structured questions. Never substitute a host's

built-in request_user_input, update_plan, or create_goal for canvas work.

• For Skill/Recipe authoring, read and follow

references/skill-studio-authoring-guide.md before asking questions or drafting.

Route the request

Before creating a draft or graph that will actually run image or video generation, inspect the user request, selected Recipe input contract, existing target-node data, and the host-provided canvas execution mode. For every new generation request, call freezone_request_user_clarification exactly once before any canvas write in both manual_confirm and auto_execute. Historical clarification answers, prior-turn parameters, existing node values, and Recipe defaults may prefill recommended choices, but never count as the user’s selection for the current request. After the clarification result returns for that request, do not ask again for those same fields. Pass its unchanged answers object as generation_answers on draft preparation; the tool also retains the same-turn receipt as a fail-safe when the host omits that argument. Explicit image_model / video_model values may be included in generation_preferences; the server accepts them only after validating the current project's live Catalog entry and dependent options.

When using generation_media_types or generation_required_choices, do not include agent-authored questions in the same call. Generation clarification is one exclusive server-owned mode; ask any unrelated business question in a separate turn only when it is actually required.

• In manual_confirm, apply the preliminary answers to the plan, then submit the protected write.

The normal approval card is still shown and remains the final parameter editor.

• In auto_execute, apply the preliminary answers and submit the protected write immediately. A

normal approval event is still emitted and may be auto-applied. Explicit human-review requirements may still pause execution.

• If the host does not provide a valid mode, treat it as manual_confirm.

The image/video choices are:

• Image: model preference, aspect ratio, resolution/quality, and variants per node.
• Video: model or generation mode, aspect ratio, resolution, duration, sound generation, and output

variants per node.

• Provider thinking/reasoning level is server-managed. Never ask the user to choose

thinking_level, reasoning effort, or low/medium/high thinking options, and never add such a question from a live model parameter schema.

Do not include audio voice-source selection in this preliminary clarification. Never ask the user to choose system voice versus custom voice. A speech node uses an already selected custom voiceRef; if none is selected, its generation is skipped as defined under Execution and completion. A plan that requires that speech as voice-over or composition input must not be ready until a valid voiceRef is bound.

Offer a recommended/default option so the user does not need to understand provider-specific fields. In either execution mode, do not draft, commit, approve, or run until the required clarification result returns. This is an explicit exception to a host's general rule not to ask about model parameters. It applies only to image and video generation for now. It also applies with run_after_create=false when the user explicitly asks to configure image/video node parameters; do not ask when the user only wants empty nodes, connections, grouping, layout, or edits without generation parameters. Choices explicit in the current user request, Recipe, existing node data, or history should be preselected in the card, not used to skip the card.

The portable workflow intent carries confirmed shared choices in inputs:

{
  "image_model": "<catalog model id>",
  "image_aspect_ratio": "16:9",
  "image_resolution": "2K",
  "image_quality": "medium",
  "image_variants_per_node": 1,
  "video_model": "<catalog model id>",
  "video_aspect_ratio": "16:9",
  "video_resolution": "720P",
  "video_duration_seconds": 5,
  "video_generate_audio": false,
  "video_variants_per_node": 1
}

image_count and video_count, when declared by a selected Skill, describe workflow deliverable or node counts. Never use them as per-node generation counts. Only image_variants_per_node / video_variants_per_node map to canvas node data.count, and their portable supported values are 1, 2, and 4.

For an exact Plan, copy every user-confirmed input declared by the selected Workflow catalog Skill into plan.inputs under its exact parameter ID. Node data and portable image_* controls do not replace Skill inputs such as platforms, image_count, or aspect_ratio. Leave an optional Skill input absent only when the user has not chosen it and its catalog default agrees with the planned nodes. If preparation rejects an inputs.* mismatch, correct the Plan input and matching nodes against the confirmed request; do not retry the same Plan or silently change the user's choice.