bluekiwi 0.1.7 → 0.2.0

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

@@ -0,0 +1,177 @@
+---
+name: bk-instruction
+description: BlueKiwi instruction template management skill. Creates, updates, and deletes agent instruction templates, and links credentials using natural language. This skill should be used when the user says "/bk-instruction", "create instruction", "manage instruction templates", or wants to manage BlueKiwi instruction templates.
+user_invocable: true
+---
+
+# BlueKiwi Instruction Management
+
+Create, update, and delete agent instruction templates. Optionally link credentials to instructions using natural language.
+
+## Argument Handling
+
+- `/bk-instruction` → Show action selection menu.
+- `/bk-instruction add <title>` → Start creating a new instruction.
+- `/bk-instruction list` → Show instruction list.
+
+## What is an Instruction?
+
+An instruction is an **execution directive** that a workflow node delivers to the agent at runtime.
+
+- Well-written instructions control agent behavior precisely.
+- **Credential binding happens at the workflow node level**, not at the instruction level.
+  To reference a credential in an instruction, include the service name in the `content` text.
+  Then link the `credential_id` to the node when designing the workflow in `/bk-design` or `/bk-improve`.
+
+## Execution Steps
+
+### Step 0: Select Action
+
+If no argument, ask via AskUserQuestion:
+
+- header: "Instructions"
+- options: ["List", "Create new", "Edit", "Delete"]
+
+---
+
+### Action: List
+
+Call `list_instructions` and display results:
+
+```
+Instruction Templates
+━━━━━━━━━━━━━━━━━━━━━━━━━
+ID   Title                   Agent Type    Active
+━━━━━━━━━━━━━━━━━━━━━━━━━
+1    SaaS Competitor Analysis  general       ✅
+2    Code Review Checklist     code-review   ✅
+━━━━━━━━━━━━━━━━━━━━━━━━━
+2 total
+```
+
+For folder-based filtering → call `list_folders`, then re-query with `list_instructions(folder_id)`.
+
+---
+
+### Action: Create New
+
+**Collect basic info**:
+
+1. Title: ask via AskUserQuestion.
+2. Agent type: ask via AskUserQuestion (options: ["general", "code-review", "data-analysis", "Type my own"])
+3. Tags: comma-separated keywords (optional)
+4. Priority: integer (default 0, higher = more important)
+
+**Write content**:
+
+Ask how to write the content via AskUserQuestion:
+
+- header: "Write content"
+- "How would you like to write the instruction content?"
+- options: ["I'll write it myself", "Generate AI draft for review"]
+
+**If "Generate AI draft"**:
+
+Based on the goal and agent type, write a draft using this format:
+
+```
+## Goal
+<1-sentence goal>
+
+## Instructions
+1. <specific action 1>
+2. <specific action 2>
+...
+
+## Output Format
+<expected output format>
+
+## Success Criteria
+- <quantitative criterion 1>
+- <quantitative criterion 2>
+```
+
+Show the draft and ask if the user wants to modify it.
+
+**Credential linking (natural language)**:
+
+Ask: "Does this instruction use an external service?" via AskUserQuestion:
+
+- options: ["Yes, specify a service", "No"]
+
+If "Yes":
+
+1. Ask the user to describe the service in natural language. Example: "Use the GitHub API to fetch the PR list."
+2. Call `list_credentials` to get registered credentials.
+3. Try to match the input against `service_name` (case-insensitive partial match).
+4. Show the match result and confirm:
+
+```
+Matched credentials for "GitHub":
+  → ID 2: github (GitHub PAT)
+
+Add this credential reference to the instruction content?
+```
+
+If matched: append the following block to the content automatically:
+
+```
+## Required Credentials
+- service: github (credential_id: 2)
+  purpose: GitHub API authentication
+```
+
+If no match: "Could not find a matching credential. Register it first with `/bk-credential add`."
+
+**Select folder**: Call `list_folders`, then ask via AskUserQuestion.
+
+**Register**:
+
+Call `create_instruction`:
+
+```json
+{
+  "title": "<title>",
+  "content": "<content>",
+  "agent_type": "<agent type>",
+  "tags": ["tag1", "tag2"],
+  "priority": 0,
+  "folder_id": <folder id>
+}
+```
+
+On success:
+
+```
+✅ Instruction registered
+Title: <title> (ID: <id>)
+
+To use this instruction in a workflow node, set instruction_id: <id>
+when designing nodes with `/bk-design`.
+```
+
+---
+
+### Action: Edit
+
+Call `list_instructions` → select target via AskUserQuestion.
+
+Ask what to change (AskUserQuestion):
+
+- options: ["Change title", "Edit content", "Change agent type", "Activate/Deactivate", "Cancel"]
+
+Call `update_instruction` with only the changed fields.
+
+---
+
+### Action: Delete
+
+Call `list_instructions` → select target via AskUserQuestion.
+
+Confirm via AskUserQuestion:
+
+- header: "Confirm delete"
+- "Delete '{title}'? This will fail if any workflow node is using it."
+- options: ["Delete", "Cancel"]
+
+Call `delete_instruction`. On 409 error, show which workflow is using it.

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

@@ -1,207 +1,219 @@
 ---
 name: bk-next
-description: BlueKiwi 다음 단계 진행 스킬. 현재 단계를 마무리하고 다음 단계를 실행합니다. This skill should be used when the user says "/bk-next", "다음 단계", "다음", "계속", "진행해", or wants to proceed to the next step.
+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
 
-- **instruction은 에이전트의 내부 동작 지침이다. 사용자에게 그대로 노출하지 않는다.**
-- 사용자에게는 실행 결과(분석, 질문, 제안)만 자연스럽게 보여준다.
-- "노드", "node_type" 등 시스템 용어를 절대 사용하지 않는다.
+- **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
 
-사용자가 `/bk-next` 대신 "진행해", "다음", "계속", "넘어가자", "OK" 등 자연어로 진행 의사를 표현하면 동일하게 다음 단계로 진행한다.
+If the user says "proceed", "next", "continue", "let's go", "OK", "go ahead" — treat it the same as `/bk-next`.
 
-## 세션 복원 (컨텍스트 주입)
+## Session Restore (Context Injection)
 
-advance 반환값에 `task_context`가 ���함된다. 이 데이터를 활용하여 새 세션에서도 이어 작업이 가능하다.
+The `advance` response includes `task_context`. Use it to resume seamlessly in a new session.
 
-1. `task_context.running_context` — 누적된 결정사항과 프로젝트 상태. 반드시 읽고 이해한다.
-2. `task_context.completed_steps` — 이전에 완료된 단계 요약. 어디까지 ��는지 파악한다.
-3. `task_context.artifacts` — 참조 가능한 산출물 목록. `file_path`가 있으면 필요할 때 Read 도구로 읽는다.
-4. `task_context.last_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.
 
-새 세션에서 이어가는 경우 (이전 대화 컨텍스트가 없�� 경우), task_context를 ���반으로 상황을 파악한 뒤 ��행한다.
+When resuming in a new session (no prior conversation context), use `task_context` to reconstruct the situation before proceeding.
 
-## execute_step 호출 시 필수 파라미터
+## execute_step Required Parameters
 
 <HARD-RULE>
-execute_step 호출 시 반드시 아래 파라미터를 채운다:
-- `context_snapshot`: JSON 문자열. 이 단계에서 내린 결정사항, 주요 발견, 다음 단계 힌트를 구조화하여 저장한다.
-  예: `{"decisions":[{"question":"기술 스택","chosen":"Next.js","reason":"팀 경험"}],"key_findings":["RLS 필요"],"next_step_hint":"구현 계획 작성"}`
-- `session_id`: 현재 세션 ID (알 수 없으면 생략 가능)
-- `agent_id`: 에이전트 식별자 (예: "claude-code")
-- `model_id`: 사용 중인 LLM 모델 ID (예: "claude-opus-4-6", "gpt-5.2"). system prompt에서 확인.
-- `user_name`: 사용자 이름 (알 수 없으면 생략 가능)
-
-파일을 생성하거나 수정한 경우, `artifacts` 배열에 기록한다:
-
-- 파일 생성: `{artifact_type: "file", title: "설계 문서", file_path: "docs/specs/design.md"}`
-- 커밋한 경우: `{artifact_type: "git_commit", title: "Phase 1 구현", git_ref: "커밋해시"}`
-- URL 생성: `{artifact_type: "url", title: "PR", url: "https://..."}`
+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>
 
-## Git 아티���트 저장
+## Credential Handling (API Service Nodes)
 
-코드나 문서를 생성/수정한 단계를 완료한 후, 사용자에게 `save_artifacts`로 Git 브랜치에 저장할지 물어본다:
-
-- "산출���을 Git 브랜치에 저장하시겠습니까?" (AskUserQuestion: "저장 (Recommended)" / "건너뛰기")
-- 저장 시 `save_artifacts(task_id, message, file_paths)` 호출
-
-## Credential 사용 (API 서비스 노드)
-
-advance 반환에 `credentials` 필드가 있으면 해당 노드는 외부 API 연동이 필요한 노드이다.
+If the `advance` response includes a `credentials` field, the node requires external API integration.
 
 <HARD-RULE>
-credentials.secrets의 키-값을 사용하여 API 호출을 수행한다.
-예: credentials.secrets.ACCESS_TOKEN → curl -H "Authorization: Bearer $TOKEN" 형태로 사용
-execute_step의 output에 시크릿 원본(토큰, 키 값)을 절대 포함하지 않는다.
-결과(URL, 상태코드, 응답 요약)만 기록한다.
+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. 현재 단계가 pending이면 → 대화에서 응답을 추출하여 execute_step으로 저장
-  2. advance(peek=false)로 다음 단계를 가져온다
-  3. 다음 단계가 finished이면 → complete_task 호출 후 종료
-  4. 다음 단계를 실행한다 (아래 타입별 처리 참고)
-  5. auto_advance를 확인한다:
-     - true → 중간 결과 간략 표시 후 LOOP의 2번으로 돌아간다
-     - false → 멈추고 결과를 표시한다
+  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>
-auto_advance=true인 단계를 실행한 후에는 반드시 다음 단계로 자동 진행한다.
-"다음 단계로 넘어가려면 /bk-next"를 안내하지 않는다.
-중간 결과를 간략히 한 줄로 표시한다: "✅ [제목] 완료 → 다음 단계 진행 중..."
-auto_advance=false인 단계를 만날 때까지 이 루프를 반복한다.
+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 the user:
+   ```
+   ⏸ Step [{title}] complete — waiting for approval before proceeding.
+   A notification has been sent. Use /bk-approve when ready.
+   ```
+3. STOP. Do NOT call `advance`. Do NOT proceed to the next step.
+
+The server will reject `advance` with 403 until a human approves via /bk-approve.
 </HARD-RULE>
 
-## 타입별 처리
+## Step-Type Handling
 
-### action 단계
+### action step
 
-1. instruction을 읽고 수행한다. 태스크 context를 참고한다.
-2. **heartbeat를 적극 사용한다**: 30초 이상 걸리는 작업에서는 반드시 heartbeat를 보낸다. 예: "아키텍처 섹션 분석 중...", "API 엔드포인트 설계 중...", "설계 문서 119행 작성 중..."
-3. 수행 결과를 사용자에게 보여준다.
-4. `execute_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 단계
+### gate step
 
-1. `get_web_response`로 웹 응답 먼저 확인.
-2. 없으면 `AskUserQuestion`으로 자연스럽게 질문.
-3. **부분 수정 옵션**: 승인/수정 질문에는 "승인 (Recommended)" / "부분 수정" / "전체 재작성" 3개 옵션.
-4. 응답을 `execute_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 단계
+### loop step
 
-1. instruction 수행.
-2. **종료 전 사용자 확인**: 종료 조건 충족 시 자동 종료하지 않고 AskUserQuestion으로 확인한다:
-   - "수집된 정보가 충분합니다. 추가로 확인할 사항이 있으신가요?"
-   - "충분합니다 (Recommended)" / "추가 질문이 있습니다"
-3. **loop 반복마다 개별 execute_step을 호출한다.** 여러 질문의 답변을 하나로 합치지 않는다. 각 반복이 별도 로그로 기록되어야 한다.
-4. `loop_continue` true/false로 execute_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
 ```
 
-## 멈출 때의 안내 (auto_advance=false일 때만)
+## When Pausing (auto_advance=false only)
 
-- action 완료 후: "다음 단계로 넘어가려면 `/bk-next`를 입력하세요."
-- gate 질문 후: 사용자 응답을 기다린다.
+- **HITL approval required** (execute_step returned `next_action: "wait_for_human_approval"`):
+  Call `request_approval`, show waiting message, stop. Resume only after `/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>
-워크플로 완료 시 `complete_task`를 호출할 때 `summary` 파라미터에 반드시 내용을 채운다. 빈 문자열로 보내지 않는다.
-summary에는 마크다운으로 결정 사항, 산출물 경로, 다음 단계 제안을 포함한다.
+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="## 결정 사항\n- 목적: ...\n- 접근 방식: ...\n\n## 산출물\n- 설계 문서: `docs/specs/...`\n- 구현 계획: `docs/specs/...`\n\n## 다음 단계\nPhase 1부터 구현을 시작하세요.")
+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]
 
-## 산출물
-- 📄 설계 문서: `docs/specs/YYYY-MM-DD-xxx-design.md`
-- 📋 구현 계획: `docs/specs/YYYY-MM-DD-xxx-implementation-plan.md`
+## Artifacts
+- 📄 Design doc: `docs/specs/YYYY-MM-DD-xxx-design.md`
 
-## 다음 단계
-구현을 시작하려면 Phase 1부터 진행하세요.
+## Next Steps
+Start implementation from Phase 1.
 ━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-## output 기록 형식
+## output Format
 
 <HARD-RULE>
-모든 output은 최소 200자 이상이어야 한다. 한 줄 요약만 보내지 않는다.
-반드시 ## 헤딩 구조를 사용한다.
-어투는 "~했습니다"체로 통일한다.
-생성된 파일이 있으면 절대경로를 포함한다.
+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
 
-- **프로젝트명**: recipe-sharing-app
-- **현재 상태**: 초기 단계 (코드 없음)
-- **기술 스택**: 미정
-- **주요 발견**: ...
+- **Project name**: recipe-sharing-app
+- **Current state**: Initial stage (no code yet)
+- **Tech stack**: TBD
+- **Key findings**: ...
 
-## 산출물
+## Artifacts
 
-설계 문서를 `/tmp/or-test-verify/docs/specs/2026-04-08-recipe-design.md`에 저장했습니다.
+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. 개인 태스크 관리 (추천)
-2. 팀 협업
-3. 교육용
+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
 
-코멘트가 있으면 실행 전에 사용자에게 알리고 처리 방법을 AskUserQuestion으로 물어본다.
+If comments are present, notify the user before executing and ask how to handle them via AskUserQuestion.
 
-## 실패 처리
+## Failure Handling
 
-AskUserQuestion으로: 건너뛰기 / 재시도 / 이전 단계 / 중단.
+Ask via AskUserQuestion: Skip / Retry / Previous step / Abort.

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

@@ -0,0 +1,97 @@
+---
+name: bk-report
+description: BlueKiwi task report skill. Generates a structured summary report of a completed or in-progress task, including decisions, artifacts, and findings. This skill should be used when the user says "/bk-report", "show task report", "summarize results", or wants a structured report of a BlueKiwi task.
+user_invocable: true
+---
+
+# BlueKiwi Task Report
+
+Generate a structured summary report of a completed or in-progress task.
+
+## Argument Handling
+
+- `/bk-report` → Report on the most recent active or completed task.
+- `/bk-report <task_id>` → Report on the specified task.
+
+## Execution Steps
+
+### Step 1: Load Task Data
+
+Call `advance` with `peek: true` to get the current task state and `task_context`.
+
+If a specific task_id is provided, use it directly.
+
+### Step 2: Load Artifacts and Findings
+
+Call `load_artifacts` to retrieve all artifacts for the task.
+
+If the workflow includes compliance steps, call `list_findings` to retrieve compliance findings.
+
+### Step 3: Generate Report
+
+Build the report from the collected data:
+
+```markdown
+# Task Report: {workflow title}
+
+**Task ID**: {id}
+**Status**: {running | completed | failed}
+**Started**: {started_at}
+**Completed**: {completed_at or "in progress"}
+**Steps**: {completed}/{total}
+
+---
+
+## Summary
+
+{task_context.running_context summary — key decisions and outcomes}
+
+---
+
+## Step-by-Step Log
+
+| Step | Title        | Status | Key Output                   |
+| ---- | ------------ | ------ | ---------------------------- |
+| 1    | Clarify Goal | ✅     | Defined target market as SMB |
+| 2    | Collect Data | ✅     | 15 competitors identified    |
+| 3    | Review       | ⏳     | Pending approval             |
+
+---
+
+## Artifacts
+
+| Type       | Title      | Location                          |
+| ---------- | ---------- | --------------------------------- |
+| file       | Design Doc | `docs/specs/2026-04-11-design.md` |
+| git_commit | Phase 1    | `a1b2c3d`                         |
+
+---
+
+## Compliance Findings
+
+{if findings exist}
+| ID | Severity | Description | File |
+|----|----------|-------------|------|
+| ISMS-001 | BLOCK | Hardcoded secret | src/config.ts:42 |
+
+{if no findings}
+No compliance issues found.
+
+---
+
+## Next Steps
+
+{task_context summary of recommended next actions}
+```
+
+### Step 4: Display and Offer Export
+
+Show the report.
+
+Ask via AskUserQuestion:
+
+- header: "Export?"
+- "Would you like to save this report to a file?"
+- options: ["Save as Markdown", "Skip"]
+
+If "Save as Markdown" → write to `reports/bk-report-{task_id}-{date}.md`.