bk-create

1. Role/context (first line or heading): who or what performs this step — e.g., "## Market Analyst", "You are acting as a senior code reviewer"
2. Numbered sub-steps: at minimum 2 explicit steps describing HOW to perform the action, not just WHAT to produce
3. Output specification: exactly what is produced — file path + format, structured data shape, or required fields
4. Verification: one line stating how to confirm the step succeeded
5. Loop nodes only: termination condition as the final line — "Termination: end when X"

Minimum instruction length: 80 words. If an instruction is shorter, it is not specific enough — expand it.

Anti-patterns → Prescriptive Rewrites

Instruction Templates by Node Type

action — data / research step:

## <Expert Role>

<One sentence: what this step accomplishes and why it matters here.>

1. <First concrete action — tool call, file read, calculation>
2. <Second concrete action — transformation, filtering, aggregation>
3. <Third action if needed>

**Output**: <Exact file path or data structure>
**Verification**: <Command or check that confirms success>

gate — user decision:

<Brief context: what was just produced and what the user must decide.>

Present options using bk-options (size=sm):
- A) <Option> — <one-sentence consequence>
- B) <Option> — <one-sentence consequence>
- C) <Option> — <one-sentence consequence>

Mark the recommended option with `data-recommended`.

loop — iterative interaction:

## <Role>

<What is being iterated and why iteration is needed.>

Each iteration:
1. <What to present or ask>
2. <How to process the response>
3. <How to update state>

**Termination**: End when <specific, measurable condition>.

VS Component Selection Guide

When designing a visual_selection: true gate node, specify which bk-* components the agent should use in the node instruction. This keeps VS screens consistent and prevents vague "make a selection UI" instructions.

Dialog size directive — optional first line of the HTML: <!-- @bk size=sm|md|lg|xl|full -->. Default is sm (single-column choices). Step up to md (cards, code-compare), lg (pros-cons, ranking, timeline), xl (mockups, matrix, side-by-side wireframes), or full (dashboard previews, complex layouts) whenever content benefits from horizontal space.

Component → Use Case mapping:

Instruction template patterns:

Present the alternatives using bk-options with data-recommended on the suggested choice.
(dialog: sm — default, no directive needed)

Show the layout candidates using bk-cards (size=md), then add a bk-slider named "confidence" (0-100, unit "%").
Start the HTML with: <!-- @bk size=md -->

If the user may want to approve with edits, add a bk-textarea with data-name="comment" and data-response-key="comment" so they can leave a global memo.

If a specific option requires justification or revision notes, add data-requires-comment to that selectable item.
Use data-comment-name="change_request" when the memo should be persisted into response.fields.change_request.

Feedback-friendly gate design rules:

• For review/approval gates, default to selection + memo, not selection alone.
• If one option means "approve with edits", make that option require a comment.
• Use bk-input for short structured constraints (owner, budget cap, deadline).
• Use bk-textarea for open-ended revision requests or free-form reviewer notes.
• When designing downstream steps, explicitly instruct the agent to parse and honor comment, fields, and option_comments, not just selections.

Collect optional capabilities with bk-checklist and ask the user to rank the top three priorities using bk-ranking.
(dialog: sm or md — omit directive or use <!-- @bk size=md -->)

Compare the two implementation approaches using bk-code-compare (size=lg), then capture risk posture in a bk-matrix (size=xl).
If both appear on the same screen, use the larger size: <!-- @bk size=xl -->

Show a UI wireframe mockup or dashboard layout preview using bk-mockup with inline styles.
Start the HTML with: <!-- @bk size=xl --> or <!-- @bk size=full -->
Place two mockup cards side by side using display:grid;grid-template-columns:1fr 1fr.

Attachments

• Use node attachments for scripts, reference docs, prompts, and config files that the agent should load during execution.
• Add attachments only after the workflow and target node exist, using upload_attachment(workflow_id, node_id, filename, content).
• Prefer text-based files so the execution skill can download and use their contents directly.
• Mention the attachment by filename in the node instruction when the agent is expected to read it.
• Keep attachments node-specific. Shared reusable logic belongs in an instruction template or a separate workflow step, not duplicated across many nodes.
• Use binary attachments only when necessary. Execution agents may only inspect their metadata unless the task explicitly requires the binary asset.

Node Modification Strategy

Inline vs Template Instructions

Nodes can have two types of instructions:

• Template reference: Node has instruction_id set. References a shared instruction template. Use update_instruction to modify the template — affects all nodes that reference it.
• Inline instruction: Node has no instruction_id and stores text directly in the instruction field. Use update_node(workflow_id, node_id, instruction="new text") to modify — affects only that node.

# Update inline instruction — affects only this node
update_node(workflow_id=67, node_id=109, instruction="new instruction text")

# Update instruction template — affects all referencing nodes
update_instruction(instruction_id=5, content="new template text")

Folder & Workflow Organization

Triggered when the user says "move workflow", "change folder", "organize", or "create folder".

Move an Existing Workflow to a Different Folder

1. Call list_workflows to identify the target workflow (or use the name the user mentioned).
2. Call list_folders to get the folder list.
3. Ask via AskUserQuestion:
   • header: "Move to"
   • "Which folder should '{workflow title}' be moved to?"
   • options: folder name list + "My Workspace (default)"
4. Call move_workflow:

   { "workflow_id": <id>, "folder_id": <destination folder id> }
   

5. Report: ✅ Moved '{workflow title}' → '{folder name}'

Create a Standalone Folder

1. Ask for name and optional visibility (personal / group / public).
2. Call create_folder:

   { "name": "<name>", "description": "<desc>", "visibility": "personal" }
   

3. Report: ✅ Folder '{name}' created.

Rename a Folder

Call update_folder:

{ "folder_id": <id>, "name": "<new name>" }

Delete an Empty Folder

Call delete_folder:

{ "folder_id": <id> }

Note: delete_folder fails with FOLDER_NOT_EMPTY if the folder contains any workflows, instructions, or sub-folders. Empty the folder first. Credentials are not filed in folders and do not affect this check.