bluekiwi 0.2.5 → 0.3.1

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

@@ -27,26 +27,84 @@ Select a registered workflow, create a task, and immediately execute the first s
 - `header` must be 12 characters or fewer.
 - `multiSelect` must be `false`.
 
-## Session Restore (Resume In-Progress Task)
+## Session Restore (Resume In-Progress or Timed-Out Task)
 
-Before starting, check for running tasks using `advance(task_id, peek=true)` if a task ID is known, or prompt the user.
+<HARD-RULE>
+Follow all steps in order before proceeding to workflow selection.
+
+### Step A — Mark zombie tasks
+
+Call `POST /api/tasks/timeout-stale` with `{"timeout_minutes": 120}`.
+This converts any `running` tasks idle for over 2 hours to `timed_out`.
+
+### 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.
 
-If an in-progress task is found, ask via AskUserQuestion:
+### 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]
+```
 
-- header: "Resume?"
-- "Task #{id} ({workflow name}, Step {N}/{total}) is in progress. Resume or start a new workflow?"
-- options: "Resume (Recommended)" / "Start new workflow"
+### Step D — Ask what to do
 
-If resuming → call `advance(task_id, peek=true)`, read `task_context`, then switch to `/bk-next` flow.
+**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.
+</HARD-RULE>
 
 ## execute_step Required Parameters
 
 <HARD-RULE>
 Always populate these parameters when calling execute_step:
 - `context_snapshot`: JSON string. Store decisions made, key findings, and hints for the next step.
-- `agent_id`: Model name in use (e.g., "claude-opus-4-6")
+- `model_id`: Current LLM model ID (e.g., "claude-opus-4-6"). Check your system prompt.
 - `user_name`: User name (omit if unknown)
 
+Note: `provider_slug` (coding tool identity) is auto-injected by the MCP server from the connection handshake. Do not send it manually.
+
 If files were created or modified, record them in the `artifacts` array:
 
 - File created: `{artifact_type: "file", title: "Design Doc", file_path: "docs/specs/design.md"}`
@@ -65,15 +123,31 @@ echo "GIT_REMOTE: $(git remote get-url origin 2>/dev/null || echo 'none')"
 echo "GIT_BRANCH: $(git branch --show-current 2>/dev/null || echo 'unknown')"
 echo "USER: $(whoami 2>/dev/null || echo 'unknown')"
 echo "OS: $(uname -s 2>/dev/null || echo 'unknown') $(uname -m 2>/dev/null)"
+# Detect CLI tool by walking up the process tree (up to 4 levels)
+_AGENT=unknown; _PID=$PPID
+for _L in 1 2 3 4; do
+  _C=$(ps -o comm= -p $_PID 2>/dev/null | tr '[:upper:]' '[:lower:]')
+  case "$_C" in
+    *claude*)   _AGENT=claude-code; break ;;
+    *gemini*)   _AGENT=gemini-cli;  break ;;
+    *codex*)    _AGENT=codex-cli;   break ;;
+    *cursor*)   _AGENT=cursor;      break ;;
+    *windsurf*) _AGENT=windsurf;    break ;;
+    *opencode*) _AGENT=opencode;    break ;;
+  esac
+  _PID=$(ps -o ppid= -p $_PID 2>/dev/null | tr -d ' ')
+  [ -z "$_PID" ] || [ "$_PID" = "0" ] || [ "$_PID" = "1" ] && break
+done
+echo "AGENT: $_AGENT"
 ```
 
 Build a JSON object:
 
 ```json
 {
+  "agent": "claude-code",
   "project_dir": "/Users/dante/workspace/project",
   "user_name": "dante",
-  "agent": "claude-code",
   "model_id": "claude-opus-4-6",
   "git_remote": "git@github.com:user/repo.git",
   "git_branch": "main",
@@ -82,7 +156,7 @@ Build a JSON object:
 }
 ```
 
-- `agent`: always "claude-code" when running in Claude Code
+- `agent`: detected CLI tool name (from AGENT output above)
 - `model_id`: current model ID (check system prompt)
 - `started_at`: current UTC time
   </HARD-RULE>
@@ -104,17 +178,37 @@ Record only results (URL, status code, response summary).
 
 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-design` skill. Pass the user's original argument (if any) as the goal so `bk-design` can pre-fill the design step. After `bk-design` 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.
 
-### 2. Create Task
+If the user selects "Create new workflow" from the selection UI → invoke `bk-design`, then continue as above.
+
+### 2. Create Task + Open Monitoring Page
 
 Call `start_workflow`. Pass any argument as `context`.
 
-### 3. Execute First Step + auto_advance Loop
+<HARD-RULE>
+After `start_workflow` returns the task_id, immediately open the task monitoring page in the user's browser:
+
+```bash
+open "${BLUEKIWI_URL:-http://localhost:3100}/tasks/${TASK_ID}"
+```
+
+Use `open` on macOS, `xdg-open` on Linux. Derive `BLUEKIWI_URL` from the MCP connection or default to `http://localhost:3100`.
+</HARD-RULE>
+
+### 3. Execute First Step + Auto-Advance Loop
 
 Read the first step's instruction as an **internal directive and execute immediately**.
 
@@ -127,19 +221,188 @@ Starting: {workflow title} ({n} steps)
 ━━━━━━━━━━━━━━━━━━━━━━━━━
 **1** → 2 → 3 → 4 → 5 → 6 → 7
 ━━━━━━━━━━━━━━━━━━━━━━━━━
+📺 Live: ${BLUEKIWI_URL}/tasks/${TASK_ID}
+━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-**auto_advance loop**: If the next step has `auto_advance: true`, continue executing without pausing.
+**Auto-advance loop**: If execute_step returns no `next_action`, continue executing the next step without pausing.
 
 <HARD-RULE>
-After executing an auto_advance=true step, always proceed to the next step automatically.
+After executing a step with no next_action, always proceed to the next step automatically.
 Show a brief inline update: "✅ [{title}] done → continuing to next step..."
-Repeat the loop until reaching an auto_advance=false step.
+Repeat the loop until reaching a gate step or a hitl=true action step.
 </HARD-RULE>
 
 ### 4. When Pausing
 
-- **HITL** (execute_step returned `next_action: "wait_for_human_approval"`):
-  Call `request_approval`, then immediately show the HITL approval AskUserQuestion (same as bk-next HITL Pause). Do NOT stop and tell the user to type `/bk-approve`.
-- After completing an action step (auto_advance=false, no HITL): "Type `/bk-next` to proceed."
-- After showing a gate question: Wait for user response. Do not show `/bk-next` hint.
+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)
+
+<HARD-RULE>
+Write all VS content text (titles, descriptions, option labels, button text)
+in the user's language. The frame UI (Submit button, status) is auto-localized,
+but agent-authored content must match the user's locale.
+</HARD-RULE>
+
+- If `visual_selection: true`:
+  1. Compose a VS content **fragment** using `bk-*` component classes. Write **only the inner HTML** - do not include `<html>`, `<head>`, or `<body>` tags. The frame (CSS, JS, submit button) is injected automatically by the web UI.
+
+     **Component quick reference:**
+     - Selection: `bk-options` (A/B/C cards, single), `bk-cards` (visual cards, single), `bk-checklist` (multi-select), `bk-code-compare` (code blocks, single)
+     - Input: `bk-slider` (numeric range), `bk-ranking` (drag reorder), `bk-matrix` (2x2 drag placement)
+     - Display: `bk-split`, `bk-pros-cons`, `bk-mockup`, `bk-timeline`
+     - Layout: `h2`, `.bk-subtitle`, `.bk-section`, `.bk-label`
+
+     Every selection/input element needs a `data-value` attribute. Example fragment:
+
+     ```html
+     <h2>Choose an approach</h2>
+     <p class="bk-subtitle">
+       Select the architecture that best fits your needs
+     </p>
+     <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:
+     ```bash
+     open "${BLUEKIWI_URL:-http://localhost:3100}/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:
+
+     ```json
+     {
+       "selections": ["monolith"],
+       "values": { "budget": 70 },
+       "ranking": ["security", "ux"]
+     }
+     ```
+
+     - `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)
+       Only populated fields appear.
+
+  6. 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
+
+<HARD-RULE>
+When `advance` returns `node.attachments`:
+1. Review the list (filename, mime_type, size_bytes)
+2. Call `get_attachment(workflow_id, node_id, attachment_id)` for each text file the instruction references
+3. Use downloaded content as context when executing the instruction
+4. For binary files, note their existence but do not download unless explicitly required
+</HARD-RULE>
+
+#### Loop (next_action: "loop_back")
+
+<HARD-RULE>
+Loop nodes repeat until a termination condition is met. The instruction contains the termination condition.
+
+**Execution flow:**
+
+1. Read the instruction and execute one iteration (e.g., ask one clarifying question).
+2. Present the result/question to the user via AskUserQuestion.
+3. Based on user response, decide: is the termination condition met?
+   - **NOT met** → call `execute_step(loop_continue=true)` → server creates a new pending log on the same node → re-execute the loop step (go back to step 1)
+   - **Met** → call `execute_step(loop_continue=false)` → loop ends → call `advance` to move to next step
+
+**Example — "Clarifying Questions" loop (loop_back_to=self):**
+
+```
+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
+```
+
+**Example — "Design Section Presentation" loop:**
+
+```
+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
+```
+
+</HARD-RULE>
+
+#### 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:
+
+```json
+{
+  "task_id": 19,
+  "node_id": 109,
+  "history": [
+    {
+      "iteration": 1,
+      "web_response": { "selections": ["a"] },
+      "created_at": "..."
+    },
+    {
+      "iteration": 2,
+      "web_response": { "selections": ["b"], "values": { "confidence": 80 } },
+      "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, or skipping already-confirmed items.
+
+## Graceful Interruption (중단 처리)
+
+<HARD-RULE>
+Whenever the user requests a stop mid-workflow — phrases like "stop", "pause", "cancel", "잠깐", "중단", "그만", "멈춰", or presses Ctrl+C — you MUST ask before exiting:
+
+Ask via AskUserQuestion:
+
+- header: "작업 중단"
+- "현재 Step {N}에서 중단합니다. 어떻게 처리할까요?"
+- options:
+  - "일시 중지 (나중에 이어서)" — leave task as `running`; it will auto-timeout after 2 hours of inactivity, and can be resumed next session
+  - "태스크 종료 (완전히 닫기)" — call `complete_task(task_id, summary="사용자 요청으로 중단됨")` to mark the task finished
+  - "계속 진행" — dismiss and continue the current step
+
+If "일시 중지":
+
+- Save the current progress to `context_snapshot` via `execute_step` (mark output as "작업이 일시 중지되었습니다. 다음 세션에서 이어서 진행 가능합니다.")
+- Remind the user: "Task #{id}은 Step {N}에서 일시 중지되었습니다. 다음에 `/bk-start`를 실행하면 이어서 진행할 수 있습니다."
+
+If "태스크 종료":
+
+- Call `complete_task(task_id, summary="사용자 요청으로 중단됨. 마지막 완료 스텝: {N}")`.
+- Remind the user: "태스크가 종료되었습니다. 처음부터 다시 시작하려면 `/bk-start`를 실행하세요."
+
+**When not to prompt**: If ALL steps are already completed and `complete_task` is about to be called, skip this dialog — the workflow is naturally finishing.
+</HARD-RULE>
+
+## Feedback Survey (before calling complete_task)
+
+When the workflow finishes, run the feedback survey flow.
+Follow the sequence: `save_feedback` → `complete_task` → suggest improvements.

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

@@ -8,27 +8,57 @@ user_invocable: true
 
 View the progress of active and completed tasks.
 
+## Argument Handling
+
+- `/bk-status` → Show all running tasks. If none, show recent completed tasks.
+- `/bk-status <task_id>` → Show detailed step-by-step log for that task.
+- `/bk-status running` → Show only running tasks.
+- `/bk-status completed` → Show only completed tasks.
+
 ## Execution Steps
 
 ### 1. Fetch Tasks
 
-Call `advance` with `peek: true` on any known active task, or check the server for running tasks.
+Call `list_tasks` with optional filters:
+
+- No argument: `list_tasks()` (all tasks) or `list_tasks(status="running")`
+- With status filter: `list_tasks(status="running")` or `list_tasks(status="completed")`
+- With task_id: `advance(task_id=<id>, peek=true)` for detailed view
 
-### 2. Display Results
+### 2. Display Task List
 
 ```
 BlueKiwi Task Status
 ━━━━━━━━━━━━━━━━━━━━━━━━━
   #1  [completed] Feature Brainstorm   8/8 steps   2026-04-07
   #2  [running]   PR Security Review   2/4 steps   2026-04-07  ← active
+  #3  [running]   DB Migration Plan    5/7 steps   2026-04-08  ← active
 ━━━━━━━━━━━━━━━━━━━━━━━━━
+Active: 2 tasks
 ```
 
 ### 3. Detailed View
 
-If a task number is given as an argument (`/bk-status 2`), show the step-by-step log for that task.
+If a task number is given, call `advance(task_id=<id>, peek=true)` and show the step-by-step log:
+
+```
+Task #2: PR Security Review (running)
+━━━━━━━━━━━━━━━━━━━━━━━━━
+  ✅ 1. Code Analysis          completed  12s
+  ✅ 2. Dependency Check        completed  8s
+  ⏸ 3. Security Review         pending    ← current (gate)
+  ○  4. Report Generation       —
+━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### 4. Offer Actions
+
+After displaying, ask via AskUserQuestion:
+
+- header: "Actions"
+- options: ["Resume active task (/bk-start)", "View detailed task", "Done"]
 
 ## Notes
 
-- Web UI: http://localhost:3000/tasks
-- Real-time monitoring: Requires WebSocket Relay (`npm run ws`)
+- `list_tasks` respects RBAC — only tasks on workflows the user can read are returned.
+- For real-time monitoring, use the web UI: http://localhost:3000/tasks

package/dist/commands/dev-link.js

@@ -11,7 +11,7 @@ export async function devLinkCommand() {
     for (const adapter of detectInstalledAdapters()) {
         const target = adapter.getSkillsDir();
         mkdirSync(target, { recursive: true });
-        for (const skill of ["bk-start", "bk-next", "bk-status", "bk-rewind"]) {
+        for (const skill of ["bk-start", "bk-status", "bk-rewind"]) {
             const link = join(target, skill);
             if (existsSync(link)) {
                 rmSync(link, { recursive: true, force: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bluekiwi",
-  "version": "0.2.5",
+  "version": "0.3.1",
   "description": "BlueKiwi CLI — install MCP client and skills into your agent runtime",
   "license": "MIT",
   "repository": {

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

@@ -1,228 +0,0 @@
----
-name: bk-next
-description: BlueKiwi next step skill. Completes the current step and executes the next one. This skill should be used when the user says "/bk-next", "next step", "next", "continue", "proceed", or wants to advance to the next step in a running BlueKiwi task.
-user_invocable: true
----
-
-# BlueKiwi Next Step
-
-Complete the current step and execute the next one in a running task.
-
-## Core Principles
-
-- **Instructions are internal agent directives. Never expose raw instruction text to the user.**
-- Show only execution results (analysis, questions, suggestions) to the user.
-- Never use system terms like "node", "node_type" with the user.
-
-## Natural Language Triggers
-
-If the user says "proceed", "next", "continue", "let's go", "OK", "go ahead" — treat it the same as `/bk-next`.
-
-## Session Restore (Context Injection)
-
-The `advance` response includes `task_context`. Use it to resume seamlessly in a new session.
-
-1. `task_context.running_context` — Accumulated decisions and project state. Read and internalize it.
-2. `task_context.completed_steps` — Summary of completed steps. Understand where we are.
-3. `task_context.artifacts` — List of available artifacts. Use the Read tool on `file_path` entries when needed.
-4. `task_context.last_session` — Last execution session info. Note if a different session/user progressed it.
-
-When resuming in a new session (no prior conversation context), use `task_context` to reconstruct the situation before proceeding.
-
-## execute_step Required Parameters
-
-<HARD-RULE>
-Always populate these parameters when calling execute_step:
-- `context_snapshot`: JSON string. Store decisions made, key findings, and hints for the next step.
-  Example: `{"decisions":[{"question":"tech stack","chosen":"Next.js","reason":"team experience"}],"key_findings":["RLS required"],"next_step_hint":"write implementation plan"}`
-- `session_id`: Current session ID (omit if unknown)
-- `agent_id`: Agent identifier (e.g., "claude-code")
-- `model_id`: Current LLM model ID (e.g., "claude-opus-4-6", "gpt-5.2"). Check system prompt.
-- `user_name`: User name (omit if unknown)
-
-If files were created or modified, record in the `artifacts` array:
-
-- File created: `{artifact_type: "file", title: "Design Doc", file_path: "docs/specs/design.md"}`
-- Git commit: `{artifact_type: "git_commit", title: "Phase 1 Implementation", git_ref: "<hash>"}`
-- URL: `{artifact_type: "url", title: "PR", url: "https://..."}`
-  </HARD-RULE>
-
-## Credential Handling (API Service Nodes)
-
-If the `advance` response includes a `credentials` field, the node requires external API integration.
-
-<HARD-RULE>
-Use key-value pairs from `credentials.secrets` to make API calls.
-Example: `credentials.secrets.ACCESS_TOKEN` → `curl -H "Authorization: Bearer $TOKEN"`
-Never include raw secret values (tokens, keys) in `execute_step` output.
-Record only results (URL, status code, response summary).
-</HARD-RULE>
-
-## Execution Loop
-
-```
-LOOP:
-  1. If the current step is pending → extract response from conversation, save with execute_step
-     → Check execute_step response for next_action field (see HITL section below)
-  2. Call advance(peek=false) to fetch the next step
-  3. If finished → call complete_task, then end
-  4. Execute the next step (see step-type handling below)
-  5. Check auto_advance:
-     - true  → show brief inline result, then go back to step 2
-     - false → HITL pause (see below)
-```
-
-<HARD-RULE>
-After executing an auto_advance=true step, always proceed to the next step automatically.
-Do not show "type /bk-next to continue" hint.
-Show a brief one-line update: "✅ [{title}] done → continuing to next step..."
-Repeat the loop until reaching an auto_advance=false step.
-</HARD-RULE>
-
-## HITL Pause (auto_advance=false steps)
-
-<HARD-RULE>
-When execute_step returns `next_action: "wait_for_human_approval"`:
-
-1. Call `request_approval` with a brief message summarizing what was done.
-2. Show a summary of what was completed:
-   ```
-   ━━━━━━━━━━━━━━━━━━━━━━━━━
-   ⏸ Awaiting Approval: {step title}
-   ━━━━━━━━━━━━━━━━━━━━━━━━━
-   {brief summary of the step's output}
-   ━━━━━━━━━━━━━━━━━━━━━━━━━
-   ```
-3. Immediately ask via AskUserQuestion — do NOT tell the user to type `/bk-approve`:
-   - header: "Approve?"
-   - options: ["Approve — proceed to next step (Recommended)", "Approve with edits", "Reject — redo this step", "Rewind to earlier step"]
-
-4. Handle the response:
-   - **Approve**: Call `approve_step(task_id=<id>)`, then call `advance` and continue the execution loop.
-   - **Approve with edits**: Ask the user what to change, apply the edits, then approve and continue.
-   - **Reject**: Ask the user for the reason, call `rewind` to return to this step, tell the user "Rewound. Type `/bk-next` to retry."
-   - **Rewind to earlier step**: Switch to `/bk-rewind` flow.
-     </HARD-RULE>
-
-## Step-Type Handling
-
-### action step
-
-1. Read the instruction and execute it. Reference task context.
-2. **Use heartbeat actively**: For tasks taking 30+ seconds, send heartbeat regularly.
-   Example: "Analyzing architecture section...", "Designing API endpoints...", "Writing design doc line 119..."
-3. Show the result to the user.
-4. Save with `execute_step`.
-
-### gate step
-
-1. Check `get_web_response` for a web response first.
-2. If none, ask naturally via `AskUserQuestion`.
-3. **Partial edit option**: For approve/modify questions, offer 3 options: "Approve (Recommended)" / "Partial edit" / "Full rewrite".
-4. Save the response with `execute_step`.
-
-### loop step
-
-1. Execute the instruction.
-2. **Confirm before stopping**: When the stop condition is met, do not auto-stop — ask via AskUserQuestion:
-   - "Enough information collected. Do you have anything else to add?"
-   - "That's enough (Recommended)" / "I have more to add"
-3. **Call execute_step once per loop iteration.** Do not merge multiple answers into one. Each iteration is a separate log entry.
-4. Pass `loop_continue` true/false to execute_step.
-
-## Progress Display
-
-Show progress at the start of each step as a single line:
-
-```
-✅1 → ✅2 → ✅3 → **4** → 5 → 6 → 7 → 8 → 9 → 10 → 11
-```
-
-## When Pausing (auto_advance=false only)
-
-- **HITL approval required** (execute_step returned `next_action: "wait_for_human_approval"`):
-  Call `request_approval`, then immediately show AskUserQuestion for approval (see HITL Pause section). Do NOT stop and wait for `/bk-approve`.
-- **Gate step**: Wait for user response via AskUserQuestion.
-- **Other action step pausing without HITL**: "Type `/bk-next` to proceed."
-
-## Completion Message
-
-<HARD-RULE>
-When the workflow finishes, call `complete_task` with a non-empty `summary`.
-The summary must include decisions made, artifact paths, and suggested next actions, formatted in Markdown.
-</HARD-RULE>
-
-```
-complete_task(task_id=N, status="completed", summary="## Decisions\n- Goal: ...\n- Approach: ...\n\n## Artifacts\n- Design doc: `docs/specs/...`\n\n## Next Steps\nStart implementation from Phase 1.")
-```
-
-Show completion message to user:
-
-```
-🎉 Workflow complete!
-━━━━━━━━━━━━━━━━━━━━━━━━━
-
-## Summary
-[key decisions table]
-
-## Artifacts
-- 📄 Design doc: `docs/specs/YYYY-MM-DD-xxx-design.md`
-
-## Next Steps
-Start implementation from Phase 1.
-━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-## output Format
-
-<HARD-RULE>
-All output must be at least 200 characters. Do not send one-line summaries only.
-Always use ## heading structure.
-Write in past-tense declarative form ("I analyzed...", "I generated...").
-Include absolute paths for any files created.
-</HARD-RULE>
-
-action:
-
-```markdown
-## Actions Taken
-
-Analyzed the project context.
-
-## Results
-
-- **Project name**: recipe-sharing-app
-- **Current state**: Initial stage (no code yet)
-- **Tech stack**: TBD
-- **Key findings**: ...
-
-## Artifacts
-
-Saved design doc to `/tmp/or-test-verify/docs/specs/2026-04-08-recipe-design.md`.
-```
-
-gate:
-
-```markdown
-## Question
-
-What is the core problem this project management tool aims to solve?
-
-## Options
-
-1. Personal task management (Recommended)
-2. Team collaboration
-3. Educational use
-
-## Response
-
-Selected "Personal task management" — proceeding as a personal productivity task tracker.
-```
-
-## Comment Check
-
-If comments are present, notify the user before executing and ask how to handle them via AskUserQuestion.
-
-## Failure Handling
-
-Ask via AskUserQuestion: Skip / Retry / Previous step / Abort.