bluekiwi 0.2.4 → 0.3.0

package/dist/assets/skills/bk-design/SKILL.md

@@ -16,9 +16,11 @@ Design a structured workflow from a natural language goal and register it on the
 ## Core Principles
 
 - One node = **one agent action**. Split overly large chunks.
-- `auto_advance: true` = proceeds without user intervention. Suitable for data collection and transformation steps.
-- `auto_advance: false` = requires user confirmation or judgment.
-- `node_type` must be either `"agent"` (agent execution) or `"gate"` (user decision).
+- `node_type: "action"` = regular agent step; auto-advances unless `hitl: true`.
+- `node_type: "gate"` = user decision point; always pauses for human approval.
+- `node_type: "loop"` = repeating step; set `loop_back_to` to the target step order.
+- `hitl: true` = action node that requires explicit human approval before advancing. Default: `false`.
+- `visual_selection: true` = gate node where the agent renders an HTML UI and the user makes a selection by clicking (instead of typing). Only valid on `gate` nodes. Default: `false`.
 
 ## Execution Steps
 
@@ -64,8 +66,8 @@ Analyze the goal and design the nodes.
 {
   "title": "Clarify Goal",
   "instruction": "Analyze the user's stated goal and extract the 3 most important clarifying questions.",
-  "node_type": "agent",
-  "auto_advance": true,
+  "node_type": "action",
+  "hitl": false,
   "order": 1
 }
 ```
@@ -75,11 +77,11 @@ Show the design to the user:
 ```
 Designed workflow: <title>
 ━━━━━━━━━━━━━━━━━━━━━━━━━
-1. [Clarify Goal]     (auto)
-2. [Collect Data]     (auto)
-3. [Run Analysis]     (auto)
-4. [Review Results]   ← pauses here
-5. [Generate Report]  (auto)
+1. [Clarify Goal]     action
+2. [Collect Data]     action
+3. [Run Analysis]     action
+4. [Review Results]   gate ← pauses for human approval
+5. [Generate Report]  action
 ━━━━━━━━━━━━━━━━━━━━━━━━━
 5 steps total
 ```
@@ -106,22 +108,226 @@ Call `create_workflow`:
 }
 ```
 
-### Step 6: Report Result
+### Step 6: Report Result + Open in Browser
 
-On success:
+On success, open the workflow detail page in the browser:
+
+```bash
+open "${BLUEKIWI_URL:-http://localhost:3100}/workflows/${WORKFLOW_ID}"
+```
+
+Then display:
 
 ```
 ✅ Workflow registered
 Name: <title> (ID: <id>)
 Steps: <n>
 Version: 1.0
+🔗 ${BLUEKIWI_URL}/workflows/${WORKFLOW_ID}
 
 Type `/bk-run` to execute it now.
 ```
 
+## Node Type Reference
+
+### action — Auto-executing agent step
+
+- `auto_advance=1` (automatic). The agent executes the instruction, saves the result, and automatically proceeds to the next step.
+- Set `hitl: true` to require human approval after execution. Use only for security-sensitive or irreversible operations.
+
+### gate — User decision point
+
+- `auto_advance=0`. Must receive a user response before proceeding.
+- Set `visual_selection: true` to have the agent render an HTML UI where the user selects by clicking.
+- Used for final result review, direction choices, approval/rejection, etc.
+
+### loop — Conditional repetition
+
+- `auto_advance=0`. Repeats the same step until the termination condition is met.
+- `loop_back_to`: target step_order to loop back to. Usually points to itself (self-loop).
+- **The instruction MUST include a clear termination condition** so the agent can decide `loop_continue=true/false`.
+
+**Loop node design patterns:**
+
+```json
+{
+  "title": "Clarifying Questions",
+  "node_type": "loop",
+  "loop_back_to": 4,
+  "instruction": "Ask one question at a time. Use multiple choice when possible.\n\nGather:\n- Purpose: What problem does this feature solve?\n- Constraints: Tech stack, performance, security limitations?\n- Success criteria: What defines completion?\n\nTermination: End when purpose, scope, constraints, and success criteria are all clear."
+}
+```
+
+```json
+{
+  "title": "Design Section Presentation",
+  "node_type": "loop",
+  "loop_back_to": 7,
+  "instruction": "Present the design section by section.\nEach section scales with complexity: a few sentences if simple, 200-300 words if nuanced.\nCover: architecture, components, data flow, error handling, testing.\nAfter each section, ask the user for confirmation.\n\nTermination: End when all design sections have been approved by the user."
+}
+```
+
+**When to use loop nodes:**
+
+- Information gathering (question → answer repetition)
+- Section-by-section presentation/review (present → approve repetition)
+- Iterative refinement (result → feedback → revision repetition)
+
 ## Node Design Guidelines
 
 - 3–7 steps is ideal. Consider splitting if more than 10.
-- The first step should always be `auto_advance: false` (user provides initial context).
-- Insert a `gate` node (result review) before the final step.
+- Use `node_type: "gate"` before the final step to let the user review results.
+- Use `node_type: "loop"` when a step needs iterative user interaction. Always include a clear termination condition in the instruction.
+- Use `hitl: true` on `action` nodes only when the step requires explicit human judgment mid-flow (e.g., security-sensitive operations, irreversible actions).
+- Use `visual_selection: true` on `gate` nodes when the selection is best expressed visually — e.g., choosing a layout, picking a chart type, selecting a UI template. The agent must call `set_visual_html` with interactive HTML before executing the step; the user's click supplies the response.
 - For nodes requiring external API calls, specify `credential_id`. Create credentials first with `/bk-credential`.
+
+#### 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.
+
+<HARD-RULE>
+- VS content shown to the user must be written in the user's language.
+- Labels, option descriptions, helper text, slider units, ranking item names, and matrix axis labels must all follow the user's language.
+- Keep component class names and JSON keys in their canonical English forms (`bk-options`, `selections`, `values`, `ranking`, `matrix`).
+</HARD-RULE>
+
+**Dialog size directive — add as the first line of the HTML:**
+
+```html
+<!-- @bk size=sm -->
+<!-- default 448px: simple options, checklist -->
+<!-- @bk size=md -->
+<!-- 672px: cards, code-compare -->
+<!-- @bk size=lg -->
+<!-- 896px: pros-cons, ranking, timeline -->
+<!-- @bk size=xl -->
+<!-- 1152px: mockups, matrix, side-by-side wireframes -->
+<!-- @bk size=full -->
+<!-- 95vw: dashboard previews, complex layouts -->
+```
+
+Rule: choose `xl` or `full` whenever content benefits from horizontal space (side-by-side comparisons, wireframe mockups, multi-column layouts). Omit or use `sm` for simple single-column choices.
+
+**Component → Use Case mapping:**
+
+| Component         | Recommended size | Best for                                                       |
+| ----------------- | ---------------- | -------------------------------------------------------------- |
+| `bk-options`      | `sm`             | Mutually exclusive choices with descriptions (A/B/C decisions) |
+| `bk-cards`        | `md`             | Visual previews (layout, chart type, UI template selection)    |
+| `bk-checklist`    | `sm`             | Feature toggles, multi-select from a list                      |
+| `bk-code-compare` | `lg`             | Comparing code approaches side by side                         |
+| `bk-slider`       | `sm`             | Budget allocation, confidence levels, thresholds               |
+| `bk-ranking`      | `md`             | Priority ordering (requirements, features)                     |
+| `bk-matrix`       | `xl`             | Urgency/importance mapping, risk assessment                    |
+| `bk-split`        | `xl`             | Two-option comparison (A vs B)                                 |
+| `bk-pros-cons`    | `lg`             | Pros and cons review                                           |
+| `bk-mockup`       | `xl` or `full`   | UI wireframe / layout previews                                 |
+| `bk-timeline`     | `lg`             | Roadmap / milestone review                                     |
+
+**Instruction template patterns:**
+
+```text
+Present the alternatives using bk-options with data-recommended on the suggested choice.
+(dialog: sm — default, no directive needed)
+```
+
+```text
+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 -->
+```
+
+```text
+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 -->)
+```
+
+```text
+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 -->
+```
+
+```text
+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
+
+<HARD-RULE>
+- Update a single node → `update_node(workflow_id, node_id, ...only changed fields)`
+- Append a node (at the end) → `append_node(workflow_id, title, instruction, node_type, loop_back_to?, visual_selection?)`
+- Insert a node (in the middle) → `insert_node(workflow_id, after_step=N, title, instruction, node_type, loop_back_to?, visual_selection?)`
+- Delete a node → `remove_node(workflow_id, node_id)`
+- Never use `update_workflow(nodes=[...])` for full replacement unless a complete redesign is intended
+</HARD-RULE>
+
+## 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`:
+   ```json
+   { "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`:
+   ```json
+   { "name": "<name>", "description": "<desc>", "visibility": "personal" }
+   ```
+3. Report: `✅ Folder '{name}' created.`
+
+### Rename a Folder
+
+Call `update_folder`:
+
+```json
+{ "folder_id": <id>, "name": "<new name>" }
+```
+
+### Delete an Empty Folder
+
+Call `delete_folder`:
+
+```json
+{ "folder_id": <id> }
+```
+
+> Note: `delete_folder` fails with `FOLDER_NOT_EMPTY` if the folder contains any workflows, instructions, credentials, or sub-folders. Empty the folder first.

package/dist/assets/skills/bk-improve/SKILL.md

@@ -35,6 +35,16 @@ If "Type my own" → accept free-text improvement direction.
 
 ### Step 3: Analyze the Current Workflow
 
+## Leveraging Feedback Data
+
+When improving a workflow, call `advance(peek=true)` on a past task to check for `feedback_data`.
+If `feedback_data` exists, use it as the primary input for improvement analysis:
+
+1. Read each feedback item's `question` and `answer`
+2. Identify negative responses (unsatisfied, insufficient, etc.)
+3. Prioritize steps related to that feedback for improvement
+4. Explicitly note "based on user feedback" when proposing changes
+
 Display the current workflow node structure:
 
 ```
@@ -52,28 +62,72 @@ Review each node against the improvement direction:
 - Oversized steps → split them
 - Missing validation → add it
 - Unnecessary steps → remove them
+- Missing attachments → add the required script, reference doc, or config file
+- Stale attachments → remove outdated files and replace them with the current version
+- Unclear attachment usage → update the instruction so it references the attachment by filename and explains when to use it
+- Legacy VS nodes using inline onclick/postMessage → migrate to bk-\* component fragments
+- VS nodes missing component specification in instruction → add which bk-\* components to use
+- VS response format mismatch → verify downstream steps parse JSON `{selections, values, ranking, matrix}` instead of plain strings
 
-### Step 4: Design Improved Nodes
+### Step 4: Propose Changes
 
-Design the full improved node set.
-
-Show a diff of the changes:
+Design the improvements and show a diff:
 
 ```
-Improvements:
+Proposed improvements:
 ━━━━━━━━━━━━━━━━━━━━━━━━━
 ✏️  Step 1: "Collect keywords" → "Collect top 10 keywords (by search volume)"
+✏️  Step 3: instruction refined (add termination criteria)
 ➕  Step 4 added: "Quantitative validation (retry if below threshold)"
+🗑️  Step 6 removed: redundant summary
 ━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
+### Step 5: Choose Modification Strategy
+
 Ask via AskUserQuestion:
 
-- header: "Confirm"
-- "Create a new version (v<x.y>) with these improvements?"
-- options: ["Create new version", "Adjust more", "Cancel"]
+- header: "How to apply?"
+- options: ["Edit in place (patch current version)", "Create new version (v<x.y>)", "Adjust more", "Cancel"]
+
+**Edit in place** — for minor tweaks (instruction wording, adding/removing 1-2 nodes). Modifies the current active version directly.
+
+**Create new version** — for substantial restructuring (reordering steps, changing node types, major logic changes). Creates a new version in the same family; old version is archived.
+
+### Step 5a: Edit in Place (update_node)
+
+Apply changes one by one using granular MCP tools:
+
+```
+# Update inline instruction for a single node
+update_node(workflow_id=67, node_id=109, instruction="new instruction text")
+
+# Update node title
+update_node(workflow_id=67, node_id=110, title="New Title")
+
+# Change node type or add loop
+update_node(workflow_id=67, node_id=112, node_type="loop", loop_back_to=7)
+
+# Add a new node after step 3
+insert_node(workflow_id=67, after_step=3, title="Validation", instruction="...", node_type="action")
+
+# Remove a node
+remove_node(workflow_id=67, node_id=115)
+```
+
+<HARD-RULE>
+When editing in place, apply each change as a separate `update_node`, `insert_node`, `append_node`, or `remove_node` call. Never use `update_workflow(nodes=[...])` for in-place edits — it replaces ALL nodes and loses node IDs.
+</HARD-RULE>
+
+After all changes, report:
+
+```
+✅ Workflow updated in place
+Workflow: <title> v<version>
+Changes: <n> nodes modified, <n> added, <n> removed
+```
 
-### Step 5: Create New Version
+### Step 5b: Create New Version
 
 Call `update_workflow` with `create_new_version: true`:
 
@@ -82,25 +136,57 @@ Call `update_workflow` with `create_new_version: true`:
   "workflow_id": <existing id>,
   "create_new_version": true,
   "version": "<new version>",
-  "nodes": [<improved node array>]
+  "nodes": [<full improved node array>]
 }
 ```
 
-### Step 6: Offer Immediate Execution
+Report:
+
+```
+✅ New version created
+Workflow: <title>
+Previous: v<old>  →  New: v<new>
+Changed steps: <n>
+```
+
+### Step 6: Open in Browser + Offer Execution
+
+Open the workflow detail page in the browser:
+
+```bash
+open "${BLUEKIWI_URL:-http://localhost:3100}/workflows/${WORKFLOW_ID}"
+```
 
 Ask via AskUserQuestion:
 
 - header: "Run now?"
-- "New version v<x.y> created. Run it now to check results?"
+- "Run the updated workflow now to verify changes?"
 - options: ["Run now", "Run later"]
 
-If "Run now" → switch to `/bk-run` flow and start a task with the new version.
+If "Run now" → switch to `/bk-run` flow.
 
-### Step 7: Report Result
+## Attachment Management
 
-```
-✅ New version created
-Workflow: <title>
-Previous: v<old>  →  New: v<new>
-Improved steps: <n>
-```
+- Add new text attachments with `upload_attachment(workflow_id, node_id, filename, content)` when a node needs reusable execution context.
+- Remove obsolete files with `delete_attachment(workflow_id, node_id, attachment_id)` instead of leaving stale materials attached.
+- When improving a node, keep its attachments aligned with the revised instruction. If the instruction changes, verify the referenced filenames and file contents still match.
+- Prefer replacing outdated text attachments with a freshly uploaded version rather than keeping multiple conflicting variants on the same node.
+
+### VS Node Improvement
+
+When improving a node with `visual_selection: true`:
+
+- Check whether the node still uses legacy inline HTML or full `<!DOCTYPE html>` documents. If so, migrate it to bk-\* component fragments.
+- Verify the instruction explicitly names the `bk-*` components to render, for example: `Use bk-options for the primary choice and bk-slider for confidence.`
+- Check that the instruction text and the selected components align. Do not pair a ranking task with `bk-options` only, or a numeric threshold task without `bk-slider`.
+- Check that downstream steps reading `get_web_response` parse the structured JSON object (`{selections, values, ranking, matrix}`) correctly instead of treating it as a plain string.
+
+## Node Modification Strategy
+
+<HARD-RULE>
+- Update a single node → `update_node(workflow_id, node_id, ...only changed fields)`
+- Append a node (at the end) → `append_node(workflow_id, title, instruction, node_type, loop_back_to?, visual_selection?)`
+- Insert a node (in the middle) → `insert_node(workflow_id, after_step=N, title, instruction, node_type, loop_back_to?, visual_selection?)`
+- Delete a node → `remove_node(workflow_id, node_id)`
+- Never use `update_workflow(nodes=[...])` for full replacement unless a complete redesign is intended
+</HARD-RULE>

package/dist/assets/skills/bk-instruction/SKILL.md

@@ -93,6 +93,27 @@ Based on the goal and agent type, write a draft using this format:
 
 Show the draft and ask if the user wants to modify it.
 
+#### VS Component Directives
+
+When writing instructions for `visual_selection: true` gate nodes, include a VS directive block that tells the execution agent which components to render:
+
+```text
+## VS Components
+Use bk-options for the main selection. Add data-recommended to the suggested choice.
+Include a bk-slider named "confidence" (0-100, default 75, unit "%").
+Add a bk-section break before the slider.
+```
+
+The execution agent reads this directive and composes the corresponding bk-\* HTML fragment. Available components: `bk-options`, `bk-cards`, `bk-checklist`, `bk-code-compare`, `bk-slider`, `bk-ranking`, `bk-matrix`, `bk-split`, `bk-pros-cons`, `bk-mockup`, `bk-timeline`.
+
+Write the directive in concrete terms. Specify:
+
+- which component(s) to use
+- which option should be marked `data-recommended`, if any
+- names, ranges, defaults, and units for sliders
+- which items must appear in rankings, checklists, or matrix plots
+- the user's language for all visible text
+
 **Credential linking (natural language)**:
 
 Ask: "Does this instruction use an external service?" via AskUserQuestion:

package/dist/assets/skills/bk-report/SKILL.md

@@ -58,6 +58,24 @@ Build the report from the collected data:
 
 ---
 
+## VS Responses
+
+{for each step with web_response data}
+
+### Step {N}: {title}
+
+{format the JSON response as readable text}
+
+- **Selected**: {selections joined with ", "}
+- **Values**: {key = value for each entry in values}
+- **Priority ranking**: {ranking as numbered list}
+- **Matrix placement**: {item -> quadrant description for each entry}
+
+{if no VS responses}
+No visual selection responses recorded.
+
+---
+
 ## Artifacts
 
 | Type       | Title      | Location                          |

package/dist/assets/skills/bk-rewind/SKILL.md

@@ -59,12 +59,12 @@ Show the result:
 Going back to Step [N]/[Total]: [{node title}] [{node_type}]
 (Previous execution logs are preserved)
 ━━━━━━━━━━━━━━━━━━━━━━━━━
-Type `/bk-next` to re-execute this step.
+Type `/bk-start` to resume from this step.
 ━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
 ## Rules
 
 - Always ask the user for additional requirements before rewinding.
-- If requirements are provided, save them as a comment so `/bk-next` can reference them.
+- If requirements are provided, save them as a comment so the next execution can reference them.
 - Handle all choices via AskUserQuestion.

package/dist/assets/skills/bk-share/SKILL.md

@@ -6,7 +6,7 @@ user_invocable: true
 
 # BlueKiwi Share
 
-Share a folder with a user group at a specified access level (viewer or editor).
+Share a folder with a user group at a specified access level (reader or contributor).
 
 ## Argument Handling
 
@@ -16,7 +16,7 @@ Share a folder with a user group at a specified access level (viewer or editor).
 ## Core Principles
 
 - Sharing is applied at the **folder level**. Workflows and instructions inside the folder inherit the visibility.
-- Access levels: `viewer` (read-only) or `editor` (can modify contents).
+- Access levels: `reader` (read-only) or `contributor` (can create/edit contents).
 - Only the folder owner or an admin can share.
 
 ## Execution Steps
@@ -46,7 +46,7 @@ Ask via AskUserQuestion:
 Ask via AskUserQuestion:
 
 - header: "Access level"
-- options: ["Viewer (read-only)", "Editor (can modify)"]
+- options: ["Reader (read-only)", "Contributor (can create/edit)"]
 
 ### Step 4: Confirm and Apply
 
@@ -57,7 +57,7 @@ Share settings:
 ━━━━━━━━━━━━━━━━━━━━━━━━━
 Folder: {folder name}
 Group:  {group name}
-Access: {viewer | editor}
+Access: {reader | contributor}
 ━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
@@ -72,7 +72,7 @@ Call `share_folder`:
 {
   "folder_id": <id>,
   "group_id": <id>,
-  "access_level": "viewer" | "editor"
+  "access_level": "reader" | "contributor"
 }
 ```