@synity/bitrix-skills 1.3.0

package/src/features/bx-task/assets/references/time-log.md

@@ -0,0 +1,214 @@
+# /bx:task time-log — Manual Time Entry
+
+Log time manually to a Bitrix task via `task.elapseditem.add`. Use when the auto time-tracker (`bitrix-task-sync` hook) didn't catch the work — offline session, different machine, forgot to start, or filling in past sessions.
+
+Bitrix auto-emits a system message *"<user> activated time tracking. Duration: N seconds"* on every successful add — your time entry is visible in the task chat and time tab.
+
+## Args
+
+```
+/bx:task time-log <duration> [comment] [--task-id N]
+```
+
+| Arg | Required | Notes |
+|-----|----------|-------|
+| `<duration>` | yes | One of 4 formats. See "Duration formats" below. |
+| `[comment]` | optional | Free text. Default: `"Manual log via /bx:task time-log"`. |
+| `--task-id N` | optional | Override CLAUDE.md walk-up. |
+
+## Duration formats
+
+| Pattern | Example | Meaning | Seconds |
+|---------|---------|---------|--------:|
+| `^\d+$` | `30` | minutes | 1800 |
+| `^\d+h\d+m?$` | `1h30m` / `1h30` | hours + minutes | 5400 |
+| `^\d+h$` | `2h` | whole hours | 7200 |
+| `^\d+\.\d+h$` | `1.5h` | decimal hours (truncated to int seconds) | 5400 |
+| `^\d+:\d+(:\d+)?$` | `0:30:00` / `1:00:00` | HH:MM or HH:MM:SS | 1800 / 3600 |
+
+Anything else → error listing all 4 formats + exit 1.
+
+## Algorithm (Claude follows step by step)
+
+```
+1. Source helpers + pre-flight:
+     source ~/.claude/skills/bx-task/lib/bx-resolve-task.sh
+     source ~/.claude/skills/bx-task/lib/bx-api.sh
+     bx_preflight || abort
+
+2. Parse args:
+     - extract --task-id N if present, store in EXPLICIT_TASK_ID
+     - first positional = duration (REQUIRED, abort if empty)
+     - second positional = comment (optional)
+
+3. Resolve TASK_ID:
+     TASK_ID=$(bx_resolve_task_id "$EXPLICIT_TASK_ID") || abort
+
+4. Parse duration:
+     SECONDS_VAL=$(bx_parse_duration "$duration") || abort
+     # bx_parse_duration body — inline in this skill:
+
+     bx_parse_duration() {
+       # IMPORTANT: every arithmetic expansion uses 10# prefix to force decimal
+       # base. Without it, leading-zero minutes ('08', '1h08m', '0:09:30') trigger
+       # bash octal interpretation → 'value too great for base' error.
+       local input="$1"
+       if   [[ "$input" =~ ^([0-9]+)$ ]]; then
+         echo $(( 10#${BASH_REMATCH[1]} * 60 ))
+       elif [[ "$input" =~ ^([0-9]+)h([0-9]+)m?$ ]]; then
+         echo $(( 10#${BASH_REMATCH[1]} * 3600 + 10#${BASH_REMATCH[2]} * 60 ))
+       elif [[ "$input" =~ ^([0-9]+)h$ ]]; then
+         echo $(( 10#${BASH_REMATCH[1]} * 3600 ))
+       elif [[ "$input" =~ ^([0-9]+)\.([0-9]+)h$ ]]; then
+         awk -v h="${BASH_REMATCH[1]}.${BASH_REMATCH[2]}" 'BEGIN{printf "%d", h*3600}'
+       elif [[ "$input" =~ ^([0-9]+):([0-9]+)(:([0-9]+))?$ ]]; then
+         local h="${BASH_REMATCH[1]}" m="${BASH_REMATCH[2]}" s="${BASH_REMATCH[4]:-0}"
+         echo $(( 10#$h * 3600 + 10#$m * 60 + 10#$s ))
+       else
+         echo "ERROR: invalid duration. Use: '30' (min), '1h30m', '1.5h', '0:30:00'." >&2
+         return 1
+       fi
+     }
+
+5. If SECONDS_VAL <= 0 → abort with error "duration must be > 0".
+
+6. COMMENT="${comment:-Manual log via /bx:task time-log}"
+
+7. POST:
+     PAYLOAD=$(jq -n \
+       --argjson tid "$TASK_ID" \
+       --argjson sec "$SECONDS_VAL" \
+       --arg     c   "$COMMENT" \
+       '{TASKID:$tid, ARFIELDS:{SECONDS:$sec, COMMENT_TEXT:$c}}')
+     RESP=$(bx_call_v1 "task.elapseditem.add" "$PAYLOAD")
+
+8. Extract entry id (response is `{"result": NNN}` — usually clean JSON, but
+   we still use grep for parity with summary.md):
+     ENTRY_ID=$(echo "$RESP" | grep -oE '"result":[[:space:]]*[0-9]+' | grep -oE '[0-9]+')
+
+9. If ENTRY_ID non-empty:
+     echo "⏱️  Logged $(bx_format_duration $SECONDS_VAL) to task #${TASK_ID}"
+   Else:
+     echo "❌ POST failed: $RESP" >&2
+     exit 1
+```
+
+## Output formatter
+
+```bash
+bx_format_duration() {
+  local s="$1"
+  if   (( s < 60 ));   then echo "${s}s"
+  elif (( s < 3600 )); then echo "$((s/60))m"
+  else
+    local h=$((s/3600)) m=$(( (s%3600)/60 ))
+    if (( m == 0 )); then echo "${h}h"
+    else                  echo "${h}h ${m}m"
+    fi
+  fi
+}
+```
+
+Examples:
+- 30 sec → `30s`
+- 1800 sec → `30m`
+- 3600 sec → `1h`
+- 5400 sec → `1h 30m`
+- 7200 sec → `2h`
+
+## API payload shape
+
+```json
+{
+  "TASKID": 2776,
+  "ARFIELDS": {
+    "SECONDS": 1800,
+    "COMMENT_TEXT": "Manual log via /bx:task time-log"
+  }
+}
+```
+
+Endpoint: `task.elapseditem.add` on the v1 path (`/rest/<user>/<token>/`). `bx_call_v1` does NOT rewrite the URL.
+
+Response (success):
+
+```json
+{ "result": 12345, "time": {...} }
+```
+
+`12345` = the new elapsed-item ID.
+
+## Error handling
+
+| Failure | Behaviour |
+|---------|-----------|
+| `bx_preflight` fails | Exit 1, print env hint |
+| `bx_resolve_task_id` fails | Exit 1, print "TASK_ID not found" hint |
+| Duration arg missing | Exit 1, print usage |
+| Duration parse fails | Exit 1, list 4 valid formats |
+| Duration ≤ 0 | Exit 1, "duration must be > 0" |
+| Network/HTTP error | Print raw response to stderr, exit 1 (NO retry — fail-fast) |
+
+## Test matrix (parser + formatter)
+
+| Input | Seconds | Output |
+|-------|--------:|--------|
+| `30` | 1800 | `⏱️  Logged 30m to task #N` |
+| `1` | 60 | `⏱️  Logged 1m to task #N` |
+| `1h30m` | 5400 | `⏱️  Logged 1h 30m to task #N` |
+| `1h30` | 5400 | `⏱️  Logged 1h 30m to task #N` |
+| `1.5h` | 5400 | `⏱️  Logged 1h 30m to task #N` |
+| `2h` | 7200 | `⏱️  Logged 2h to task #N` |
+| `0:30:00` | 1800 | `⏱️  Logged 30m to task #N` |
+| `1:00:00` | 3600 | `⏱️  Logged 1h to task #N` |
+| `0:00:30` | 30 | `⏱️  Logged 30s to task #N` |
+| `08` | 480 | `⏱️  Logged 8m to task #N` (leading-zero — `10#` prefix prevents octal trap) |
+| `1h08m` | 4080 | `⏱️  Logged 1h 8m to task #N` (leading-zero minutes) |
+| `0:09:30` | 570 | `⏱️  Logged 9m to task #N` (leading-zero in HH:MM:SS) |
+| `abc` | — | error + exit 1 |
+| `30s` | — | error + exit 1 (raw seconds not supported v1) |
+| `-30` | — | error + exit 1 (regex rejects sign) |
+
+## Examples
+
+### Quick log
+
+```
+/bx:task time-log 30
+```
+→ Logs 1800s with default comment `"Manual log via /bx:task time-log"`.
+
+### With comment
+
+```
+/bx:task time-log 1h30m "Code review for crm-deal-sync"
+```
+→ Logs 5400s with custom comment.
+
+### Decimal hours
+
+```
+/bx:task time-log 1.5h "Architecture brainstorm"
+```
+→ Logs 5400s.
+
+### HH:MM:SS
+
+```
+/bx:task time-log 0:30:00
+```
+→ Logs 1800s.
+
+### Override task
+
+```
+/bx:task time-log 30 --task-id 9999
+```
+→ Logs 30 minutes against task 9999.
+
+## Notes
+
+- Bitrix auto-emits *"<user> activated time tracking. Duration: N seconds"* on success — that's why even short entries surface in the task chat.
+- Time entries are removable via `task.elapseditem.delete {TASKID, ITEMID}` if you need to undo. Skill does NOT auto-delete (audit value).
+- Decimal hour math truncates to int seconds via `awk` — `1.5h = 5400s exact`, `1.7h ≈ 6120s` (not `6120.0`).
+- If the task has time-tracking disabled, the API returns an error — surface it via the fail-fast path.

package/src/features/bx-task/feature.json

@@ -0,0 +1,10 @@
+{
+  "name": "bx-task",
+  "displayName": "Bitrix Task Skill (manual)",
+  "version": "1.1.0",
+  "target": "global",
+  "description": "Claude Code skill for Bitrix24 task management",
+  "requires": {
+    "mcp": ["bitrix-synity-mcp"]
+  }
+}

package/src/features/bx-task/install.ts

@@ -0,0 +1,117 @@
+import { homedir } from 'node:os';
+import { resolve, join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mkdir, copyFile, readdir, stat, rm, access } from 'node:fs/promises';
+import { assertNotSymlink, assertContainedIn } from '../../lib/fs-safety.js';
+
+export interface InstallOpts {
+  projectRoot: string;
+  onConflict?: 'overwrite' | 'skip';
+  force?: boolean;
+  /** @internal Override destination base for testing only — bypasses path-containment guard. Not wired to any CLI flag. */
+  _destOverride?: string;
+}
+
+export interface InstallResult {
+  installedFiles: string[];
+  skippedFiles: string[];
+  warnings: string[];
+}
+
+// Resolve assets directory. Code is inlined into dist/cli.js (__dirname = dist/) AND
+// compiled to dist/features/bx-task/install.js (__dirname = dist/features/bx-task/).
+// assets/ lives in src/features/bx-task/assets/ (included in package.json "files").
+async function getAssetsDir(): Promise<string> {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    // dist/ context (inlined in cli.js): ../src/features/bx-task/assets
+    resolve(here, '../src/features/bx-task/assets'),
+    // dist/features/bx-task/ context: ../../../src/features/bx-task/assets
+    resolve(here, '../../../src/features/bx-task/assets'),
+    // src/features/bx-task/ (dev)
+    resolve(here, 'assets'),
+  ];
+  for (const c of candidates) {
+    try {
+      await access(c);
+      return c;
+    } catch { /* continue */ }
+  }
+  return candidates[0]!;
+}
+
+function getSkillBase(): string {
+  return resolve(homedir(), '.claude', 'skills');
+}
+
+export async function install(opts: InstallOpts): Promise<InstallResult> {
+  const skillBase = getSkillBase();
+  const dest = opts._destOverride ?? resolve(skillBase, 'bx-task');
+  // Path traversal guard: dest must be absolute and not escape via ../
+  const resolvedDest = resolve(dest);
+  if (!opts._destOverride && !resolvedDest.startsWith(skillBase)) {
+    throw new Error(`Path traversal detected: ${resolvedDest}`);
+  }
+
+  const result: InstallResult = {
+    installedFiles: [],
+    skippedFiles: [],
+    warnings: [],
+  };
+
+  await installDir(await getAssetsDir(), resolvedDest, result, opts);
+
+  result.warnings.push(
+    '[bx-task] Requires MCP server "bitrix-synity-mcp" — verify it is configured in Claude Code settings.',
+  );
+
+  return result;
+}
+
+async function installDir(
+  srcDir: string,
+  destDir: string,
+  result: InstallResult,
+  opts: InstallOpts,
+): Promise<void> {
+  await mkdir(destDir, { recursive: true });
+  const entries = await readdir(srcDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = join(srcDir, entry.name);
+    const destPath = join(destDir, entry.name);
+
+    if (entry.isDirectory()) {
+      await installDir(srcPath, destPath, result, opts);
+      continue;
+    }
+
+    await assertNotSymlink(destPath);
+    const exists = await fileExists(destPath);
+    if (exists && !opts.force && opts.onConflict === 'skip') {
+      result.skippedFiles.push(destPath);
+      continue;
+    }
+
+    await copyFile(srcPath, destPath);
+    result.installedFiles.push(destPath);
+  }
+}
+
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await stat(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function uninstall(opts?: { _destOverride?: string }): Promise<void> {
+  const dest = resolve(opts?._destOverride ?? resolve(homedir(), '.claude', 'skills', 'bx-task'));
+  // Guard only applies to production paths; _destOverride is an internal test escape hatch.
+  if (!opts?._destOverride) {
+    assertContainedIn(dest, getSkillBase(), dest);
+  }
+  await rm(dest, { recursive: true, force: true });
+}

package/src/features/task-sync/assets/docs/bitrix-task-reference.md

@@ -0,0 +1,318 @@
+# Bitrix Task — Agent Reference
+
+> Reference cho agent khi query task hoặc lập plan structure trong Bitrix24.
+> Setup hooks: [bitrix-task-sync.md](bitrix-task-sync.md)
+> Quy trình bắt buộc: [.claude/rules/00-bitrix-task-sync.md](../.claude/rules/00-bitrix-task-sync.md)
+
+> **⚠️ Hard Rule #13:** Mọi query field/structure portal PHẢI qua `bitrix-synity-mcp` (KHÔNG curl/fetch trong agent runtime). Code derived từ MCP cần annotation: `// MCP-DERIVED: <source> @ <ISO-timestamp>`.
+
+Các tra cứu trong file này dành cho agent runtime (đọc/query qua `bitrix-synity-mcp`, sync checklist qua `bitrix-lib.sh`). Không dùng cho dev setup — nội dung setup ở file `bitrix-task-sync.md`.
+
+## 1. Bitrix Object Hierarchy
+
+```
+Portal (tamgiac.bitrix24.com)
+└── Project  (groupId)   ← "App" trong ngữ cảnh Synity
+    ├── Epic              (epicId)   ← nhóm tính năng (Scrum only)
+    │   ├── Task          (id)
+    │   │   ├── Subtask   (parentId → Task.id)
+    │   │   └── Checklist items (checklist[])
+    │   └── Task ...
+    └── Task (không thuộc Epic)
+```
+
+### Workgroup = "App" trong Synity
+
+Mỗi Bitrix24 app của Synity tương ứng với một **Project** trên portal:
+
+| Bitrix Field | Giá trị ví dụ | Ý nghĩa |
+|-------------|--------------|---------|
+| `groupId` | `12` | ID Project chứa task này |
+
+Agent đọc `groupId` → biết task thuộc app nào → không nhầm task giữa các dự án.
+
+### Mapping: App → Workgroup
+
+Agent xác định Project tương ứng với app theo 1 trong 2 flow:
+
+#### Greenfield — app mới, chưa có Project trên Bitrix
+
+```
+1. Agent hỏi user: "App này đã có Project trên portal chưa?"
+2. User: chưa
+3. Agent hỏi: "Tên Project là gì?" (gợi ý theo tên app, vd: "SynFinance")
+4. Agent → bitrix-synity-mcp: socintranet.workgroup.add
+        → input: NAME, DESCRIPTION (optional), VISIBLE=Y
+        → output: workgroup.id
+5. (Optional) Tạo Epic per nhóm tính năng — xem [Section 2](#2-epic--nhóm-tính-năng)
+6. Agent ghi vào CLAUDE.md root:
+        ## Bitrix Project
+        GROUP_ID: <workgroup.id>
+        GROUP_NAME: <name>           # tham chiếu nhanh, optional
+7. Cho mỗi feature task tiếp theo → tạo task với groupId = GROUP_ID, lưu TASK_ID
+```
+
+#### Brownfield — app đã có code + Project sẵn trên Bitrix
+
+```
+1. Agent đọc CLAUDE.md root → check GROUP_ID có chưa
+2. Nếu CHƯA có:
+   a. Agent hỏi: "Project ID trên Bitrix là gì?" hoặc
+   b. Agent → bitrix-synity-mcp: socintranet.workgroup.list (filter NAME)
+        → user xác nhận đúng project
+   c. Ghi GROUP_ID vào CLAUDE.md root
+3. Nếu ĐÃ có → dùng luôn, không hỏi
+4. Agent → bitrix-synity-mcp: tasks.api.scrum.epic.list (groupId)
+        → list Epic hiện có → user chọn hoặc tạo mới
+5. TASK_ID per feature đặt vào CLAUDE.md feature folder (override root)
+```
+
+#### CLAUDE.md keys reference
+
+| Key | Required | Owner | Mục đích |
+|-----|:--------:|-------|---------|
+| `TASK_ID` | ✅ | feature folder (preferred) hoặc root | Bắt buộc — hooks parse |
+| `PORTAL` | optional | root | Build task link trong session summary |
+| `GROUP_ID` | optional | root | Project ID — agent lookup epic/task list |
+| `GROUP_NAME` | optional | root | Tham chiếu nhanh, không dùng cho API call |
+| `EPIC_ID` | optional | feature folder | Pre-set epic cho feature task mới |
+| `CREATOR_ID` | optional | root | Default user khi agent tạo task mới |
+| `RESPONSIBLE_ID` | optional | feature folder | Assign default — agent fallback nếu user không chỉ định |
+
+## 2. Epic — Nhóm Tính Năng
+
+Epic là **nhóm tính năng** trong một Workgroup Scrum. Mỗi task có thể thuộc một Epic (`epicId`).
+
+### Khi nào dùng Epic
+
+- App có nhiều tính năng độc lập → tạo Epic per tính năng
+- Giúp filter task theo nhóm chức năng trên Bitrix board
+- `epicId = null` → task chưa được gắn vào Epic nào
+
+### Gợi ý đặt tên Epic theo app
+
+Agent gợi ý user đặt Epic dựa trên các tính năng của app:
+
+| App | Epic gợi ý |
+|-----|-----------|
+| SynFinance | Payment Integration / Expense Bot / Admin Dashboard |
+| SynCRM | Deal Pipeline / Contact Sync / Activity Log |
+| SynProject | Task Automation / Report Generator / Notification Engine |
+
+### Agent Flow với Epic
+
+```
+Đọc task → epicId = 42
+    → bitrix-synity-mcp: tasks.api.scrum.epic.get (id: 42)
+    → đọc epic.name → bổ sung context: "Feature group: Payment Integration"
+    → nếu user tạo task mới trong cùng nhóm → set epicId = 42
+```
+
+Nếu `epicId = null` và task có scope lớn → hỏi user: "Task này thuộc nhóm tính năng nào? Tôi sẽ tạo hoặc gắn Epic."
+
+## 3. Subtask vs Checklist — Decision Guide
+
+Cả hai đều dùng để chia nhỏ công việc, nhưng phục vụ mục đích khác nhau.
+
+### So sánh
+
+| Tiêu chí | Subtask | Checklist item |
+|---------|---------|---------------|
+| Có assignee riêng | ✅ | ❌ |
+| Có deadline riêng | ✅ | ❌ |
+| Có status riêng (pending/done) | ✅ | ✅ (checked/unchecked) |
+| Tạo git branch riêng | ✅ | ❌ |
+| Track trong Bitrix board | ✅ | ❌ |
+| Phù hợp cho | Work độc lập, dev khác nhau | Todo list trong 1 task |
+
+### Convention cho AI coding workflow
+
+**Dùng Subtask khi:**
+- Phase cần branch + PR riêng (ví dụ: backend vs frontend)
+- Developer khác nhau phụ trách
+- Có deadline hoặc estimate riêng
+- Cần track status độc lập trên Bitrix board
+
+**Dùng Checklist khi:**
+- Đây là plan steps của AI session (phases do AI thực hiện trong 1 branch)
+- Không cần assignee/deadline riêng
+- Muốn tick từng bước trong khi làm việc
+- Ví dụ: `/ck:plan` output → sync thành checklists qua `b24_sync_checklist()` (Section 5)
+
+### Quy tắc thực tế
+
+```
+1 feature task
+├── 📋 Checklist: Phase 1 Backend    ← AI làm trong 1 session
+│   ├── [x] DB schema migration
+│   └── [ ] Hono route handler
+├── 📋 Checklist: Phase 2 Frontend   ← AI làm trong session tiếp
+│   └── [ ] ListShell component
+└── Subtask: "QA Testing"            ← Tester khác review/test
+```
+
+## 4. Task Fields Reference
+
+Các trường quan trọng agent cần biết khi query task qua `bitrix-synity-mcp`.
+
+### Định danh & Navigation
+
+| Field | Type | Dùng khi |
+|-------|------|----------|
+| `id` | integer | Mọi API call |
+| `title` | string | Hiểu context task đang làm |
+| `description` | string | Đọc scope, yêu cầu đầy đủ |
+| `parentId` | integer | Xác nhận đây là subtask của task nào |
+| `link` | string | Mention trong commit/PR message |
+| `groupId` | integer | Biết task thuộc app/workgroup nào — xem [Section 1](#1-bitrix-object-hierarchy) |
+| `epicId` | integer | Thuộc nhóm tính năng nào (Scrum only) — xem [Section 2](#2-epic--nhóm-tính-năng) |
+
+### Trạng thái & Ưu tiên
+
+| Field | Giá trị |
+|-------|---------|
+| `status` | `pending` / `in_progress` / `supposedly_completed` / `completed` / `deferred` / `declined` |
+| `priority` | `high` / `average` / `low` |
+| `deadline` | ISO-8601 — agent cảnh báo nếu sắp hết |
+
+### Con người
+
+| Field | Dùng khi |
+|-------|----------|
+| `responsibleId` | Developer phụ trách — lưu trong CLAUDE.md `RESPONSIBLE_ID` |
+| `creatorId` | Phải = Claude user ID (`CREATOR_ID`) để được phép ghi task |
+| `accomplices` | Những người liên quan — agent thêm vào context |
+
+### Cấu trúc & Hierarchy
+
+| Field | Dùng khi |
+|-------|----------|
+| `parentId` | Subtask của task nào — null nếu là task gốc |
+| `containsSubTasks` | Check trước khi tạo subtask — tránh duplicate |
+| `containsRelatedTasks` | Xem flow bên dưới |
+| `checklist` | IDs checklist items — dùng để check/tick trạng thái |
+| `chatId` | Chat của task — `tasks.task.chat.message.send` dùng field này nội bộ |
+| `xmlId` | Agent ghi git branch name khi bắt đầu session → trace task↔branch |
+
+#### containsRelatedTasks — Agent Flow
+
+```
+Đọc task → containsRelatedTasks = true
+    → tasks.task.relation.get (taskId)  →  list [{taskId, relatedTaskId, relationType}]
+    → đọc title/status related tasks
+    → bổ sung vào context: "Task liên quan #456 (blocks) và #789 (related)"
+
+User yêu cầu "thêm related task #999":
+    → tasks.task.relation.add (taskId, relatedTaskId, relationType)
+```
+
+`relationType`: `"blocked_by"` / `"blocking"` / `"related"`
+
+### Time tracking
+
+| Field | Dùng khi |
+|-------|----------|
+| `elapsedTime` | Tổng thời gian đã log — agent tránh log trùng |
+| `actualDuration` | Thời gian thực tế tính toán bởi Bitrix |
+| `UF_AI_TOKENS_TOTAL` | Custom field (v0.2+) — cumulative AI token usage (input + output). Auto-created on first session. Read to check token budget. |
+
+### CRM links
+
+| Field | Dùng khi |
+|-------|----------|
+| `crmItemIds` | Task liên kết CRM object nào (`D_XX` deal, `C_XX` contact...) |
+
+## 5. Checklist Sync API — Plan Phases → Bitrix
+
+Khi agent lập plan, có thể sync từng phase thành một **named checklist** trong Bitrix task qua batch API.
+
+### Cơ chế batch API
+
+Batch API cho phép gọi tối đa 50 cmds trong 1 request và chain kết quả qua `$result[cmd_name]`:
+
+```bash
+# Tạo 2 named checklists + items trong 1 batch call
+POST /batch
+{
+  "halt": 1,
+  "cmd": {
+    "cl_0": "task.checklistitem.add?TASKID=123&FIELDS[TITLE]=Phase+1+Backend&FIELDS[PARENT_ID]=0",
+    "item_0_0": "task.checklistitem.add?TASKID=123&FIELDS[TITLE]=DB+schema&FIELDS[PARENT_ID]=$result[cl_0]",
+    "item_0_1": "task.checklistitem.add?TASKID=123&FIELDS[TITLE]=Route+handler&FIELDS[PARENT_ID]=$result[cl_0]",
+    "cl_1": "task.checklistitem.add?TASKID=123&FIELDS[TITLE]=Phase+2+Frontend&FIELDS[PARENT_ID]=0",
+    "item_1_0": "task.checklistitem.add?TASKID=123&FIELDS[TITLE]=ListShell+component&FIELDS[PARENT_ID]=$result[cl_1]"
+  }
+}
+```
+
+- `PARENT_ID=0` → tạo named checklist mới (tên = `TITLE`)
+- `PARENT_ID=$result[cl_0]` → thêm item vào checklist vừa tạo
+- `halt=1` → dừng nếu 1 cmd lỗi
+
+### Kết quả trong Bitrix UI
+
+```
+Task: "Implement CRM Sync"
+├── 📋 Phase 1 Backend
+│   ├── [ ] DB schema
+│   └── [ ] Route handler
+└── 📋 Phase 2 Frontend
+    └── [ ] ListShell component
+```
+
+### Plan output format — `bitrix-checklist` fenced block
+
+Planner agent emit JSON trong fenced code block với info-string `bitrix-checklist` để hook PostToolUse parse và sync tự động:
+
+````markdown
+```bitrix-checklist
+[
+  {"name":"Phase 1: Backend","items":["DB schema","Hono route","Tests"]},
+  {"name":"Phase 2: Frontend","items":["ListShell","Composable"]}
+]
+```
+````
+
+**Spec contract:**
+- Info-string PHẢI = `bitrix-checklist` (không phải `json` hoặc khác)
+- Top-level: array của objects, mỗi object có `name` (string) + `items` (array of string)
+- Tổng `phase_count + sum(items.length)` ≤ 50 (batch API limit)
+- Chỉ 1 block per plan output — block thứ 2 trong cùng output sẽ bị bỏ qua
+- Không emit block → no-op (planner muốn skip sync)
+
+**Hook behavior (`PostToolUse` cho skill `plan` / `planner`):**
+1. Regex extract block từ `tool_response`
+2. `jq` validate schema → silent skip nếu invalid (không tạo checklist rác)
+3. Đọc `TASK_ID` từ state file → call `b24_sync_checklist`
+4. Errors → stderr only, exit 0
+
+### Trigger qua shell script (manual)
+
+```bash
+# Agent gọi khi plan đã được approve
+PHASES='[
+  {"name":"Phase 1 Backend","items":["DB schema migration","Hono route handler","Unit tests"]},
+  {"name":"Phase 2 Frontend","items":["ListShell component","useAsyncData composable"]}
+]'
+source .claude/scripts/bitrix-lib.sh
+_b24_preflight || exit 0
+TASK_ID=$(find_task_id)
+b24_sync_checklist "$TASK_ID" "$PHASES"
+```
+
+**Limit:** Tối đa 50 cmds/batch. Script tự warn nếu vượt (phases × items + phase count > 50).
+
+### `bitrix-lib.sh` exports
+
+| Function | Mục đích |
+|----------|---------|
+| `_b24_preflight` | Check awk/jq/curl present; warn stderr nếu thiếu, return 1 (hooks dùng `\|\| exit 0`) |
+| `_b24_md_field <file> <key>` | POSIX awk parse `KEY: value` từ markdown — works trên macOS BSD / Linux / Windows Git Bash |
+| `find_task_id [dir]` | Walk up từ `dir` (default `pwd`), trả về `TASK_ID` đầu tiên trong CLAUDE.md |
+| `find_task_meta [dir]` | Walk up, parse 4 field (`task_id`, `creator_id`, `responsible_id`, `portal`) → JSON |
+| `b24_call <method> [body]` | POST JSON tới webhook (silent on error) |
+| `b24_batch <cmd_obj> [halt=1]` | Gọi `batch` với JSON cmd object, chain `$result[]` |
+| `b24_comment <task_id> <text>` | Post message vào task chat (`tasks.task.chat.message.send`) |
+| `b24_log_time <task_id> <minutes> [comment]` | Ghi elapsed time (`task.elapseditem.add`, params `{TASKID, ARFIELDS:{SECONDS, COMMENT_TEXT}}`) |
+| `b24_sync_checklist <task_id> <phases_json>` | Batch tạo named checklists + items |
+| `skill_emoji <skill_name>` | Map skill → emoji cho comment prefix |