bk-start

Step A — Mark zombie tasks

Call the sweep_stale_tasks MCP tool (defaults to timeout_minutes=120). This converts any running tasks idle for over 2 hours to timed_out so they can be surfaced for resume/cleanup in Step B.

Step B — Fetch existing tasks

Call list_tasks with status=running and again with status=timed_out. Collect all results into a combined candidate list sorted by updated_at descending (most recent first).

If the list is empty → skip to workflow selection.

Step C — Build the task summary

For each candidate, compute age from updated_at to now. Format: "Task #{id} — {workflow_name} (Step {current_step}/{total_steps}, {age}전)"

Example output:

미완료 태스크 2건이 있습니다:
① Task #31 — 코드 리뷰 워크플로 (Step 3/6, 3시간 전) [timed_out]
② Task #28 — 보안 점검 (Step 1/4, 30분 전) [running]

Step D — Ask what to do

Case 1: exactly 1 candidate

Ask via AskUserQuestion:

• header: "미완료 태스크"
• preview: "Task #{id} — {workflow_name}\nStep {N}/{total} · {age}전 중단"
• options (pick the most appropriate 3–4):
  • "이어서 진행" — resume this task
  • "종료하고 새로 시작" — close this task then start fresh
  • "닫지 않고 새로 시작" — leave as-is, open a new task
  • (only if status=running) "계속 실행 중" — another agent is handling it, do nothing

Case 2: 2 or more candidates

Ask via AskUserQuestion:

• header: "미완료 태스크"
• preview: the task summary list built above
• options:
  • "가장 최근 태스크 이어서" — resume the most recent one
  • "모두 종료하고 새로 시작" — close all candidates, then start fresh
  • "새 태스크 시작 (기존 유지)" — leave existing as-is, open a new task

Step E — Execute the choice

"이어서 진행" / "가장 최근 태스크 이어서": Call advance(task_id, peek=true), read task_context, then continue with the auto-advance loop.

"종료하고 새로 시작" / "모두 종료하고 새로 시작": For each task to close, call complete_task(task_id, summary="사용자 요청으로 종료됨"). Confirm: "기존 태스크를 종료했습니다. 새 워크플로를 선택하세요." → proceed to workflow selection.

"닫지 않고 새로 시작" / "새 태스크 시작 (기존 유지)": Proceed to workflow selection without touching existing tasks.

execute_step Parameters

When calling execute_step:

Always provide:

• context_snapshot (object): decisions made, key findings, next-step hints. The only reliable way to carry state across steps.
• model_id (string): current LLM model (e.g. claude-opus-4-6). Read from your system prompt.

Provide when known:

• user_name (string)
• session_id, agent_id (strings): optional identifiers, server stores them for audit.

Do NOT send manually: provider_slug — the MCP server injects it from the connection handshake.

Record file/commit outputs in the artifacts array on the same call:

• File created: {artifact_type: "file", title: "Design Doc", file_path: "docs/specs/design.md"}
• Git commit: {artifact_type: "git_commit", title: "Implementation", git_ref: "<hash>"}
• URL: {artifact_type: "url", title: "PR", url: "https://..."}

Session Metadata

When calling start_workflow, pass a session_meta JSON string carrying project context the server can't otherwise see. The MCP server auto-fills provider_slug from the client handshake, so you only need to supply what the agent knows:

{
  "project_dir": "/Users/dante/workspace/project",
  "user_name": "dante",
  "model_id": "claude-opus-4-6",
  "git_remote": "git@github.com:user/repo.git",
  "git_branch": "main",
  "os": "Darwin arm64",
  "started_at": "<current UTC ISO timestamp>"
}

Collect git_remote / git_branch / os via short shell calls (git remote get-url origin, git branch --show-current, uname -s -m). model_id comes from your system prompt; user_name from whoami if unknown; started_at is the current UTC time. Do not walk the process tree to guess the agent name — the MCP handshake tells the server which client is connected.

Credential Handling (API Service Nodes)

If the advance response includes a credentials field, the node requires external API integration.

Execution Steps

1. Fetch and Select Workflow

Call list_workflows to retrieve the list.

No workflows exist: Ask via AskUserQuestion:

• header: "No workflows"
• "No workflows found. Would you like to create one now?"
• options: "Create new workflow" / "Cancel"

If "Create new workflow" → immediately invoke the bk-create skill. Pass the user's original argument (if any) as the goal so bk-create can pre-fill the design step. After bk-create completes and the workflow is registered, return here and proceed with Step 2 using the newly created workflow.

Single workflow: Skip the selection UI, just confirm:

• "Start the '{title}' workflow?" (AskUserQuestion: "Start" / "Cancel")

Multiple workflows: Show selection via AskUserQuestion.

If the user selects "Create new workflow" from the selection UI → invoke bk-create, then continue as above.

2. Create Task + Open Monitoring Page

Call start_workflow. Pass any argument as context.

Derive a short title (≤60 chars) from the user's goal and pass it alongside context. If the argument is already short, use it; otherwise distill it to a noun phrase (e.g. "Hermes AI 아티클 생성", not the full paragraph). The raw prompt becomes context; only the short label goes into title.

After start_workflow returns the task_id, open the monitoring page in the user's browser (open "${WEBUI_URL}/tasks/${TASK_ID}" on macOS, xdg-open on Linux — WEBUI_URL is the webui_url field in the response).

3. Execute First Step + Auto-Advance Loop

Read the first step's instruction as an internal directive and execute immediately.

After execution, save with execute_step, then check the response for next_action before calling advance.

Show roadmap at start (#20):

Starting: {workflow title} ({n} steps)
━━━━━━━━━━━━━━━━━━━━━━━━━
**1** → 2 → 3 → 4 → 5 → 6 → 7
━━━━━━━━━━━━━━━━━━━━━━━━━
📺 Live: ${WEBUI_URL}/tasks/${TASK_ID}
━━━━━━━━━━━━━━━━━━━━━━━━━

Auto-advance loop: if execute_step returns no next_action, proceed to the next step automatically. Show a brief inline update (✅ [{title}] done → continuing to next step…). Repeat until a gate step or hitl=true action step is reached — do not pause to ask the user to type /bk-next.

4. When Pausing

Check the next_action field in the execute_step response and handle accordingly:

HITL (next_action: "wait_for_human_approval")

Call request_approval, then immediately show the HITL approval AskUserQuestion (inline HITL approval). Do NOT stop and tell the user to type /bk-approve.

Gate step (no next_action, node_type=gate)

Write VS content text (titles, descriptions, option labels) in the user's language. The frame UI (Submit button, status) is auto-localized; only agent-authored content needs matching locale.

• If visual_selection: true:

  1. Compose a VS content fragment (inner HTML only — no <html>/<head>/<body>, the frame is injected automatically). Component classes: bk-options, bk-cards, bk-checklist, bk-code-compare (selection); bk-slider, bk-input, bk-textarea, bk-ranking, bk-matrix (input); bk-split, bk-pros-cons, bk-mockup, bk-timeline (display).

     Required attributes (server validates these):

     • Selection items (.bk-option, .bk-card, .bk-check-item, .bk-code-option): data-value="<id>" on each item. Optional data-recommended on the suggested choice.
     • Input components: data-name="<id>" for keying the response. bk-slider also needs data-min, data-max, data-value, optional data-unit. bk-input/bk-textarea accept data-label, data-placeholder, optional data-required and data-response-key="comment" (stores into top-level comment).
     • Per-item memo: add data-requires-comment to force a memo before submit. Optional data-comment-name="<key>" stores it into response.fields[<key>].
     • Optional first line: <!-- @bk size=sm|md|lg|xl|full --> (default sm).

     Full catalog with template patterns and per-component examples: see bk-create § VS Component Selection Guide.

     Minimal example:

     <h2>Choose an approach</h2>
     <div class="bk-options">
       <div class="bk-option" data-value="monolith" data-recommended>
         <div class="bk-option-letter">A</div>
         <div class="bk-option-body">
           <h3>Monolith</h3>
           <p>Simple deployment</p>
         </div>
       </div>
       <div class="bk-option" data-value="microservices">
         <div class="bk-option-letter">B</div>
         <div class="bk-option-body">
           <h3>Microservices</h3>
           <p>Independent scaling</p>
         </div>
       </div>
     </div>
     

  2. Call set_visual_html(task_id, node_id, html) with the fragment.

  3. Open the VS deep link so the user sees the selection UI immediately:

     open "${WEBUI_URL}/tasks/${TASK_ID}?step=${STEP_ORDER}&vs=true"
     

  4. Poll get_web_response(task_id) every 3-5 seconds until a response arrives (max 120 seconds).

  5. The response is a JSON object (not a plain string). Parse it to read the user's choices and feedback:

     {
       "selections": ["monolith"],
       "values": { "budget": 70 },
       "ranking": ["security", "ux"],
       "comment": "Keep this direction but tighten rollout scope",
       "fields": { "change_request": "Add a rollback plan" },
       "option_comments": {
         "monolith": "Prefer this if we can phase deployment"
       }
     }
     

     • selections: chosen option values (from bk-options, bk-cards, bk-checklist, bk-code-compare)
     • values: numeric inputs (from bk-slider, keyed by data-name)
     • ranking: ordered list (from bk-ranking)
     • matrix: placement coordinates (from bk-matrix)
     • comment: free-form global memo from bk-textarea/bk-input with data-response-key="comment" (or data-name="comment")
     • fields: named text inputs from bk-input / bk-textarea, plus any option-level memo stored via data-comment-name
     • option_comments: per-option free-text notes attached to selected choices Only populated fields appear.

  6. When forming the gate answer, never ignore free-text feedback:

     • If comment exists, summarize it in the gate output.
     • If fields.change_request or similar named fields exist, treat them as authoritative revision instructions.
     • If option_comments exists, preserve the mapping between the selected option and its note.
     • A response like "select B + add changes" must not be collapsed into just "selections": ["b"].

  7. Use the parsed response to form the gate answer and call advance.

• If visual_selection: false → present the gate question to the user via AskUserQuestion. Use the response as gate answer, call execute_step with the answer, then advance.

Attachments

Loop (next_action: "loop_back")

Iteration 1: "Who is the primary user of this feature?" → user answers → purpose clear, constraints unclear → loop_continue=true
Iteration 2: "Are there tech stack limitations?" → user answers → constraints clear, success criteria unclear → loop_continue=true
Iteration 3: "What defines completion?" → user answers → all items clear → loop_continue=false → advance

Iteration 1: Present architecture section → user "looks good" → more sections remain → loop_continue=true
Iteration 2: Present data flow section → user "needs revision" → revise and re-present → loop_continue=true
Iteration 3: Present final section → user approves → all sections done → loop_continue=false → advance

Loop + VS History Pattern

When a loop node uses visual_selection: true, each iteration presents a VS screen and collects a response. Use get_web_response(task_id, node_id) to access all previous iteration responses for that node:

{
  "task_id": 19,
  "node_id": 109,
  "history": [
    {
      "iteration": 1,
      "web_response": { "selections": ["a"] },
      "created_at": "..."
    },
    {
      "iteration": 2,
      "web_response": {
        "selections": ["b"],
        "values": { "confidence": 80 },
        "fields": { "change_request": "Need more detail on error handling" }
      },
      "created_at": "..."
    }
  ]
}

Use the history to adapt subsequent VS screens - for example, pre-selecting the user's previous choice, adjusting slider defaults based on past values, carrying forward fields.change_request into the next revision prompt, or skipping already-confirmed items.

Web UI State Synchronization (웹 UI 상태 동기화)