@synity/bitrix-skills 1.3.0

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

@@ -0,0 +1,254 @@
+# Bitrix Task Sync — Setup Guide
+
+> **Recommended for brownfield projects:** Install via `npx @synity/bitrix-task-sync install` (see [packages/bitrix-task-sync/README.md](../packages/bitrix-task-sync/README.md)).
+> Manual steps below for greenfield setup or reference.
+>
+> Quy trình bắt buộc: [.claude/rules/00-bitrix-task-sync.md](../.claude/rules/00-bitrix-task-sync.md)
+> Reference cho agent (fields, hierarchy, checklist API): [bitrix-task-reference.md](bitrix-task-reference.md)
+
+## Yêu cầu
+
+- `curl` và `jq` đã cài trên máy dev
+- Quyền tạo Incoming Webhook trên Bitrix24 portal (hoặc xin từ admin)
+
+## Phân công Webhook vs MCP
+
+| Mục đích | Công cụ |
+|----------|---------|
+| Hook tự động post comment / log time khi skill chạy | curl + Incoming Webhook → `bitrix-lib.sh` |
+| GitHub Action post commit/PR notification | curl + Incoming Webhook (`BITRIX_WEBHOOK_URL` secret) |
+| Agent query task data trong session | `bitrix-synity-mcp` |
+| Agent sync plan phases → Bitrix checklist | `b24_sync_checklist()` — xem [reference §5](bitrix-task-reference.md#5-checklist-sync-api-plan-phases-bitrix) |
+
+Shell scripts (hooks) không thể gọi MCP — MCP chỉ available trong Claude Code context.
+
+## 1. Tạo Bitrix Incoming Webhook
+
+1. Mở Bitrix24 portal → **Applications** → **Webhooks** → **Add Incoming Webhook**
+2. Scope cần cấp: `task` (đọc/ghi task + comment + time log)
+3. Copy URL dạng: `https://xxx.bitrix24.com/rest/1/abc123token/`
+
+## 2. Set env var trên máy dev
+
+```bash
+# ~/.zshrc hoặc ~/.bashrc
+export BITRIX_WEBHOOK_URL="https://xxx.bitrix24.com/rest/1/abc123token/"
+```
+
+Reload shell: `source ~/.zshrc`
+
+Verify: `echo $BITRIX_WEBHOOK_URL`
+
+## 3. Cấp quyền execute cho hook scripts
+
+Chạy 1 lần sau khi clone repo:
+
+```bash
+chmod +x .claude/scripts/bitrix-*.sh
+```
+
+## 4. Thêm Task ID vào CLAUDE.md của project
+
+Đặt ở root project hoặc feature folder — hook tự walk up để tìm. Feature folder override root.
+
+```markdown
+## Bitrix Task
+PORTAL: https://xxx.bitrix24.com    # optional — agent dùng để build link
+GROUP_ID: 106                        # optional — Bitrix Project/Workgroup ID (from URL /workgroups/group/{ID}/)
+TASK_ID: 67890                       # bắt buộc — hooks parse field này
+CREATOR_ID: 6                        # optional — agent dùng khi tạo task mới (default portal tamgiac: 6)
+RESPONSIBLE_ID: 29                   # optional — agent dùng khi assign; null → hỏi user
+```
+
+Parent task không cần khai báo — Bitrix đã lưu quan hệ parent/child trong task.
+
+## 5. GitHub Actions — sync commit về Bitrix
+
+Thêm secret vào GitHub repo settings:
+- Key: `BITRIX_WEBHOOK_URL`
+- Value: Incoming Webhook URL ở bước 1
+
+Copy workflow template vào project:
+
+```
+packages/create-bitrix-app/templates/.github/workflows/bitrix-sync.yml
+```
+
+→ Đặt vào: `.github/workflows/bitrix-sync.yml`
+
+Workflow gồm 2 job:
+- `preflight` — verify secret tồn tại + format URL hợp lệ. Thiếu/sai format → fail rõ ràng qua `::error::` annotation.
+- `notify-bitrix` (`needs: preflight`) — parse `[B24:nnn]` từ PR body / branch name, post message vào task chat.
+
+Format URL secret bắt buộc: `https://<portal>.bitrix24.<tld>/rest/<user_id>/<token>/`
+
+## 6. Verify hoạt động
+
+### Test hooks thủ công
+
+```bash
+# Simulate PreToolUse payload
+echo '{"session_id":"test123","tool_name":"Skill","tool_input":{"skill":"debug","args":"test"}}' \
+  | bash .claude/scripts/bitrix-skill-start.sh
+```
+
+Mở Bitrix task → tab Chat → kiểm tra có comment `🐛 [Claude] debug bắt đầu: test`.
+
+### Test session sync
+
+```bash
+echo '{"session_id":"test123"}' | bash .claude/scripts/bitrix-session-sync.sh
+```
+
+## 7. Commit message format
+
+Mọi commit phải có `[B24:TASK_ID]` ở cuối message:
+
+```bash
+git commit -m "feat: add crm deal sync [B24:67890]"
+git commit -m "fix: handle rate limit [B24:67890]"
+git commit -m "refactor: extract sync service [B24:67890]"
+```
+
+## 8. Bật commit-msg hook (enforce Hard Rule #18)
+
+Chạy 1 lần sau khi clone:
+
+```bash
+bash .githooks/install.sh
+```
+
+Hook reject commit không có `[B24:\d+]`. Bypass tạm thời (chỉ cho infra/scaffold):
+
+```bash
+ALLOW_NO_B24=1 git commit -m "chore: scaffold"
+```
+
+Merge / revert / fixup commits được bỏ qua tự động.
+
+## 9. SessionStart warning (enforce Hard Rule #17)
+
+`SessionStart` hook tự động warn nếu CLAUDE.md không có `TASK_ID`:
+
+```
+⚠️  Hard Rule #17 violation: TASK_ID chưa set trong CLAUDE.md
+Bitrix Task Sync sẽ KHÔNG hoạt động trong session này.
+```
+
+Hook không block — chỉ in stderr. Wired sẵn trong `.claude/settings.json`.
+
+## 10. E2E test (live webhook)
+
+Test suite gọi webhook Bitrix24 thật để verify hooks end-to-end (skill-start, skill-end, session-sync, checklist parser, commit-msg, session-check).
+
+### Yêu cầu
+
+```bash
+export BITRIX_WEBHOOK_URL="https://<portal>.bitrix24.com/rest/<user_id>/<token>/"
+export TEST_TASK_ID=<dedicated-test-task-id>
+export TEST_PORTAL="https://<portal>.bitrix24.com"
+export TEST_USER_ID=<your-user-id>
+```
+
+⚠️ Tạo Bitrix task **dedicated cho test** (không dùng task production). Comments + checklist items sẽ được tạo và xóa nhiều lần.
+
+### Chạy
+
+```bash
+# Toàn bộ suite
+bash .claude/scripts/tests/e2e-bitrix-sync.sh
+
+# Filter theo substring tên case
+bash .claude/scripts/tests/e2e-bitrix-sync.sh case-a
+bash .claude/scripts/tests/e2e-bitrix-sync.sh commit-msg
+```
+
+### Output mẫu
+
+```
+Bitrix Sync — E2E Tests
+Webhook: https://tamgiac.bitrix24.com/rest/1/.../
+Task: 2048
+Session: e2e-1715251200-12345
+
+Pre-cleanup...
+
+Case: case-a-skill-start
+  skill-start posts comment to Bitrix
+    ✓ hook exit 0
+    ✓ file exists: ...
+    ✓ state task_id matches
+    ...
+
+Post-cleanup...
+─────────────────────────────
+PASS · 24 assertions
+```
+
+### Khi nào fail
+
+- Webhook URL hết hạn → recreate trên portal, update env
+- TASK_ID không tồn tại / không thuộc portal → preflight fail rõ ràng
+- Bitrix API rate limit → retry sau 1 phút
+- case-d skip nếu `bitrix-checklist` parser chưa merge vào `bitrix-skill-end.sh`
+
+Chi tiết: [.claude/scripts/tests/README.md](../.claude/scripts/tests/README.md)
+
+## Troubleshooting
+
+| Vấn đề | Kiểm tra |
+|--------|---------|
+| Không có comment trong Bitrix | `echo $BITRIX_WEBHOOK_URL` — đã set chưa? |
+| Task ID không tìm thấy | `grep -r "TASK_ID" ./CLAUDE.md` |
+| Hook không chạy | `cat .claude/settings.json` — có hook config chưa? |
+| `jq: command not found` | `brew install jq` hoặc `apt install jq` |
+| Webhook 401 error | Webhook token hết hạn — tạo lại trên portal |
+| GitHub Action không trigger | Verify commit message có `[B24:\d+]` đúng format |
+| Comment API 404 / method not found | `task.commentitem.add` deprecated — dùng `tasks.task.chat.message.send` (xem `bitrix-lib.sh`) |
+| commit-msg hook không reject | `git config core.hooksPath` — phải = `.githooks`. Chạy `bash .githooks/install.sh` |
+| SessionStart không warn | Verify `cat .claude/settings.json \| grep SessionStart` |
+
+## v0.2 Features
+
+### Token Tracking
+
+Every session automatically tracks input + output token consumption. Stop hook reads the session transcript JSONL and sums all messages, then writes the total to a `UF_AI_TOKENS_TOTAL` custom field on the task (created on first run). Session digest displays: `🪙 Xk in / Yk out`.
+
+**Setup:** No manual action required. The custom field is auto-created on first session with permissions for creator_id.
+
+### Time Tracking Lifecycle
+
+SessionStart hook automatically enables time tracking (`ALLOW_TIME_TRACKING = true`) on the task. First skill run calls `tasks.task.start` (status → in_progress); last skill run calls `tasks.task.pause`. Uses atomic flock counter to prevent race conditions across multiple concurrent hooks.
+
+**Your responsibility:** The task status and elapsed time counter are maintained automatically. If manually closed in Bitrix, Stop hook force-pauses to prevent lingering running state.
+
+### File Attachment
+
+PostToolUse hook uploads artifact files (`.md`) for skills: plan, brainstorm, cook. Looks for a `\`\`\`bitrix-artifact\`\`\`` block in skill output with metadata:
+```json
+{
+  "path": "plans/260510-0247-feature-name/plan.md",
+  "title": "Feature Plan"
+}
+```
+
+Files upload to **Bitrix Drive** (scope: group or user). The `verify` command now reports detected disk scope.
+
+**Your responsibility:** Skills that emit artifact blocks must specify valid file paths relative to repo root. Files must exist on disk before upload.
+
+### Session Digest
+
+Stop hook renders a comprehensive digest combining:
+- Plan phase progress (if active plan detected)
+- All skills run (with emoji, duration, result preview)
+- Token consumption line
+- Attached files list
+- Recent commits matching `[B24:TASK_ID]`
+- Task link (clickable)
+
+Rendered via pure bash + `bitrix-render-digest.sh` (no external dependencies). Digest posted as single comment to task chat.
+
+## Tiếp theo
+
+- Agent runtime cần đọc field/hierarchy/epic/checklist API → [bitrix-task-reference.md](bitrix-task-reference.md)
+- Quy trình bắt buộc + NEVER/ALWAYS → [.claude/rules/00-bitrix-task-sync.md](../.claude/rules/00-bitrix-task-sync.md)

package/src/features/task-sync/assets/githooks/commit-msg

@@ -0,0 +1,44 @@
+#!/bin/bash
+# commit-msg hook — enforces Hard Rule #18: every commit must include [B24:<task-id>]
+# Bypass: ALLOW_NO_B24=1 git commit -m "..."  (chỉ dùng cho infra/scaffold trước khi có TASK_ID)
+
+set -e
+
+MSG_FILE="$1"
+MSG=$(cat "$MSG_FILE")
+
+# Skip merge / revert / fixup auto-messages
+case "$MSG" in
+  Merge\ *|Revert\ *|fixup!\ *|squash!\ *|amend!\ *) exit 0 ;;
+esac
+
+# Allow explicit bypass via env var (logs to stderr)
+if [[ "${ALLOW_NO_B24:-0}" == "1" ]]; then
+  echo "[commit-msg] ALLOW_NO_B24=1 — skipping [B24:nnn] check" >&2
+  exit 0
+fi
+
+# Match [B24:123] anywhere in message (subject or body)
+if echo "$MSG" | grep -qE '\[B24:[0-9]+\]'; then
+  exit 0
+fi
+
+cat >&2 <<EOF
+
+❌ Hard Rule #18 violation: commit message thiếu [B24:<task-id>]
+
+Format yêu cầu:
+  feat: mô tả ngắn [B24:12345]
+  fix: bug X [B24:12345]
+
+Cách fix:
+  1. Đọc TASK_ID từ CLAUDE.md (root hoặc feature folder)
+  2. Sửa commit message hiện tại bằng:
+       git commit --amend
+  3. Hoặc bypass tạm thời (chỉ cho infra/scaffold):
+       ALLOW_NO_B24=1 git commit -m "..."
+
+Setup chi tiết: docs/bitrix-task-sync.md
+EOF
+
+exit 1

package/src/features/task-sync/assets/githooks/install.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+# Install .githooks/* as the active git hook path for this repo.
+# Run once per clone: bash .githooks/install.sh
+set -e
+
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || {
+  echo "Error: not a git repository" >&2
+  exit 1
+}
+
+cd "$REPO_ROOT"
+git config core.hooksPath .githooks
+echo "✓ git core.hooksPath = .githooks"
+echo "  Active hooks:"
+ls -1 .githooks | grep -v '^install\.sh$' | sed 's/^/    /'

package/src/features/task-sync/assets/manifest.json

@@ -0,0 +1,108 @@
+{
+  "version": "0.3.0-pre",
+  "generatedAt": "2026-05-11T08:35:30.111Z",
+  "files": [
+    {
+      "src": "docs/bitrix-task-reference.md",
+      "sha256": "4f36e961f85012ce7cf29b5f655e005ea2625c62140e7fabf804d9c0a907a646",
+      "size": 13309,
+      "mode": 420
+    },
+    {
+      "src": "docs/bitrix-task-sync.md",
+      "sha256": "7775183fe22fc2062d80efecd3e5a00f21ba82a17251231b7d60e1a819f3bbdf",
+      "size": 9441,
+      "mode": 420
+    },
+    {
+      "src": "githooks/commit-msg",
+      "sha256": "de51341fbbdde7ccc48c626f3d33b4fff574f71fb7d7e4dba2605afe17cf89b6",
+      "size": 1147,
+      "mode": 493
+    },
+    {
+      "src": "githooks/install.sh",
+      "sha256": "400f38ab13bf3561f75d0680bc7c7c8b2b86ce601a1f9b297b71a7c12bf9c79f",
+      "size": 423,
+      "mode": 493
+    },
+    {
+      "src": "rules/00-bitrix-task-sync.md",
+      "sha256": "8aeebf844c49e8a483ad838e6458cad5b8c8fbe7bf87a6e159169f819e1cf7e9",
+      "size": 7396,
+      "mode": 420
+    },
+    {
+      "src": "scripts/bitrix-attach-files.sh",
+      "sha256": "6cc520367e5b0d32da39a63a37f509e6f9908d36d03bbbc47a86c9df7d2e53aa",
+      "size": 1597,
+      "mode": 493
+    },
+    {
+      "src": "scripts/bitrix-lib.sh",
+      "sha256": "bd9340cb3664ec8cf4def21e26cb2ac671e182663b1d05599b2f492a962f05aa",
+      "size": 19831,
+      "mode": 493
+    },
+    {
+      "src": "scripts/bitrix-render-digest.sh",
+      "sha256": "4bcb8dd33405e76a6e11a3adc6e252e10f384292a13fcb10976d35837c1e7869",
+      "size": 4593,
+      "mode": 493
+    },
+    {
+      "src": "scripts/bitrix-session-check.sh",
+      "sha256": "a505cb5989385b8d3fe4a88cffc4e529b4f624e87c37bdd30f5d57977648bfbb",
+      "size": 1593,
+      "mode": 493
+    },
+    {
+      "src": "scripts/bitrix-session-sync.sh",
+      "sha256": "8438bb873d1f494620c8a6303a93940c2565100056a4ef78a1b225ea53728a2e",
+      "size": 3352,
+      "mode": 493
+    },
+    {
+      "src": "scripts/bitrix-skill-end.sh",
+      "sha256": "fa45949889b9d0eac59ff7513cf9716097ba9c9276b4623245e7010410da1b33",
+      "size": 5891,
+      "mode": 493
+    },
+    {
+      "src": "scripts/bitrix-skill-start.sh",
+      "sha256": "ae60b1278bcc89743c2bea2efa674f28ea7095e6f33abde50fc9c0e5e66965ba",
+      "size": 2013,
+      "mode": 493
+    },
+    {
+      "src": "scripts/lib/bb-formatter.sh",
+      "sha256": "cda67373549b02a635d748648180fbcea56c38988b2bd3dc5e6a384254a4b7d0",
+      "size": 3098,
+      "mode": 493
+    },
+    {
+      "src": "scripts/lib/bitrix-lib.sh",
+      "sha256": "bd9340cb3664ec8cf4def21e26cb2ac671e182663b1d05599b2f492a962f05aa",
+      "size": 19831,
+      "mode": 493
+    },
+    {
+      "src": "scripts/lib/time-helpers.sh",
+      "sha256": "6c25ad1e32307147bee383ce34681a5ba5910d2c8a1ab83e4a00161dae41e774",
+      "size": 1371,
+      "mode": 493
+    },
+    {
+      "src": "workflows/bitrix-sync.yml",
+      "sha256": "2eb583e6cad3d2c076994e5e3f477f8b653c1a510b29e5cf7056aa399fe57f9f",
+      "size": 3291,
+      "mode": 420
+    },
+    {
+      "src": "skill/SKILL.md",
+      "sha256": "e9e4072710b43695354b4d1d31d002625778e8f1330b4e5666d0c0f9d6cd2303",
+      "size": 5208,
+      "mode": 420
+    }
+  ]
+}

package/src/features/task-sync/assets/rules/00-bitrix-task-sync.md

@@ -0,0 +1,161 @@
+# Bitrix Task Sync — AI Workflow Protocol
+
+> Quy trình bắt buộc cho mọi nhân sự Synity.
+> Mục tiêu: toàn bộ quá trình phát triển với AI được lưu vào Bitrix Task
+> để tracking timeline, không mất sau khi kết thúc session.
+> Setup hooks: [docs/bitrix-task-sync.md](../../docs/bitrix-task-sync.md)
+> Agent reference (fields/hierarchy/checklist API): [docs/bitrix-task-reference.md](../../docs/bitrix-task-reference.md)
+
+## Tại sao bắt buộc
+
+Khi làm việc với AI (brainstorm, research, cook, debug...):
+- Kết quả chỉ tồn tại trong session chat → mất sau khi đóng
+- Không có timeline cụ thể trong Bitrix → progress mơ hồ
+- Không tracking được thời gian thực tế AI đã làm gì
+
+Giải pháp: hooks tự động sync mọi AI activity → Bitrix Task chat.
+
+## Phân công giữa Webhook và MCP
+
+| Mục đích | Công cụ |
+|----------|---------|
+| Hook auto-post comment / log time khi skill chạy | curl + Incoming Webhook (`BITRIX_WEBHOOK_URL`) |
+| GitHub Action post commit/PR notification | curl + Incoming Webhook (`BITRIX_WEBHOOK_URL` secret) |
+| Agent query task data trong session | `bitrix-synity-mcp` |
+
+Shell scripts (hooks) không thể gọi MCP — MCP chỉ available trong Claude Code context.
+
+## Cơ chế hoạt động
+
+```
+Skill chạy (brainstorm/research/cook/debug/fix/review/plan)
+    │
+    ├── PreToolUse hook  → curl → Bitrix: "bắt đầu" + args
+    ├── [Skill thực thi]
+    ├── PostToolUse hook → curl → Bitrix: kết quả preview + log time
+    └── Stop hook        → curl → Bitrix: session summary (tất cả skills + tổng giờ)
+
+git push (commit có [B24:TASK_ID])
+    └── GitHub Action    → curl → Bitrix: link commit/PR vào task chat
+```
+
+## NEVER
+
+- `NEVER` bắt đầu AI work session mà không có TASK_ID trong CLAUDE.md
+- `NEVER` push commit mà không có `[B24:{TASK_ID}]` trong message
+- `NEVER` tắt hooks Bitrix sync khi làm việc trên dự án Synity
+- `NEVER` dùng TASK_ID của task khác — mỗi feature → đúng task của nó
+- `NEVER` dùng curl/incoming webhook khi agent cần query task data — dùng `bitrix-synity-mcp`
+
+## ALWAYS
+
+- `ALWAYS` đặt TASK_ID trong CLAUDE.md trước khi bắt đầu session
+- `ALWAYS` dùng format commit: `feat: mô tả [B24:{TASK_ID}]`
+- `ALWAYS` đảm bảo env var `BITRIX_WEBHOOK_URL` được set trên máy dev (hooks dùng curl)
+- `ALWAYS` dùng `bitrix-synity-mcp` khi agent cần query/đọc task data trong session
+- `ALWAYS` verify Bitrix task nhận được comment sau session kết thúc
+
+## CLAUDE.md Format — Task ID per project/feature
+
+Root project CLAUDE.md:
+```markdown
+## Bitrix Task
+PORTAL: https://xxx.bitrix24.com
+GROUP_ID: 106
+TASK_ID: 12345
+```
+
+Feature folder (`apps/my-app/features/{feature-name}/CLAUDE.md`) override root:
+```markdown
+## Bitrix Task
+TASK_ID: 67890
+```
+
+Hook đọc từ thư mục hiện tại, walk up cho đến khi tìm được `TASK_ID`.
+Parent task không cần khai báo — Bitrix đã lưu quan hệ parent/child trong task.
+
+## Commit Message Format
+
+```
+feat: implement crm deal sync webhook [B24:67890]
+fix: handle 429 rate limit on deal batch [B24:67890]
+refactor: extract sync service to dedicated module [B24:67890]
+docs: update crm-sync setup guide [B24:67890]
+```
+
+`67890` = TASK_ID trong CLAUDE.md của feature đang làm.
+GitHub Action tự parse `[B24:\d+]` → post link commit/PR vào Bitrix task chat.
+
+## Skill → Bitrix Comment Mapping
+
+Format thống nhất do `bitrix-skill-start.sh` / `bitrix-skill-end.sh` sinh:
+- Bắt đầu: `${EMOJI} [Claude] ${skill} bắt đầu: ${args}`
+- Xong: `${EMOJI} [Claude] ${skill} xong (Xm)\n\n${result_preview_1500_chars}`
+
+PostToolUse cũng log elapsed minutes vào `task.elapseditem.add` (rounded up, min 1 phút).
+
+| Skill | Emoji | Bắt đầu | Xong |
+|-------|:-----:|---------|------|
+| brainstorm | 🧠 | brainstorm bắt đầu: [args] | brainstorm xong (Xm) + result preview |
+| research | 🔍 | research bắt đầu: [args] | research xong (Xm) + result preview |
+| cook | 👨‍🍳 | cook bắt đầu: [args] | cook xong (Xm) + result preview |
+| debug | 🐛 | debug bắt đầu: [args] | debug xong (Xm) + result preview |
+| fix | 🔧 | fix bắt đầu: [args] | fix xong (Xm) + result preview |
+| review | 👀 | review bắt đầu: [args] | review xong (Xm) + result preview |
+| plan / planner | 📋 | plan bắt đầu: [args] | plan xong (Xm) + result preview |
+| test / tester | 🧪 | test bắt đầu: [args] | test xong (Xm) + result preview |
+| security-review | 🔒 | security-review bắt đầu: [args] | security-review xong (Xm) + result preview |
+| _khác (default)_ | ⚡ | ${skill} bắt đầu: [args] | ${skill} xong (Xm) + result preview |
+
+Mapping emoji được định nghĩa trong `bitrix-lib.sh::skill_emoji()`. Thêm skill mới → cập nhật cả case statement và bảng này.
+
+## Plan output → checklist auto-sync
+
+Khi skill `plan` / `planner` chạy, agent PHẢI emit fenced block `bitrix-checklist` ở cuối plan output để hook PostToolUse tự sync sang Bitrix checklist.
+
+````markdown
+```bitrix-checklist
+[
+  {"name":"Phase 1: Backend","items":["DB schema","Route handler","Tests"]},
+  {"name":"Phase 2: Frontend","items":["ListShell","Composable"]}
+]
+```
+````
+
+Spec đầy đủ: [docs/bitrix-task-reference.md §5](../../docs/bitrix-task-reference.md#5-checklist-sync-api-plan-phases-bitrix).
+
+## Hook Files
+
+```
+.claude/
+├── settings.json                   — wiring SessionStart/PreToolUse/PostToolUse/Stop
+└── scripts/
+    ├── bitrix-lib.sh               — shared helpers
+    │     _b24_preflight, _b24_md_field, find_task_id, find_task_meta,
+    │     b24_call, b24_batch, b24_comment, b24_log_time,
+    │     b24_sync_checklist, skill_emoji
+    ├── bitrix-session-check.sh     — SessionStart: warn nếu thiếu TASK_ID
+    ├── bitrix-skill-start.sh       — PreToolUse: Skill → post "bắt đầu"
+    ├── bitrix-skill-end.sh         — PostToolUse: Skill → log time + post "xong"
+    └── bitrix-session-sync.sh      — Stop: session summary
+```
+
+Git hooks:
+
+```
+.githooks/
+├── commit-msg                      — enforce [B24:nnn] tag (Hard Rule #18)
+└── install.sh                      — set core.hooksPath = .githooks
+```
+
+Chi tiết function signatures: xem [docs/bitrix-task-reference.md §5](../../docs/bitrix-task-reference.md#5-checklist-sync-api-plan-phases-bitrix).
+
+## Skill Triggers
+
+- Keywords: "bắt đầu feature", "start task" → đặt TASK_ID vào CLAUDE.md trước
+- Keywords: "push", "commit" → verify commit có `[B24:TASK_ID]`
+- Keywords: "session xong" → mở Bitrix task → verify có comment summary
+- Keywords: "xem task", "đọc task", "task info" → dùng `bitrix-synity-mcp`
+- Keywords: "field task", "task field", "deal field", "contact field", "structure", "shape", "schema portal" → BẮT BUỘC `bitrix-synity-mcp` để verify (Hard Rule #13). Annotate: `// MCP-DERIVED: <source> @ <ISO-timestamp>`
+- Keywords: "list epic", "list workgroup", "tasks.api.scrum", "epic.list", "workgroup.list" → dùng `bitrix-synity-mcp` (KHÔNG curl/fetch)
+- Keywords: "get task", "task #", "task detail" → dùng `bitrix-synity-mcp.task.get`

package/src/features/task-sync/assets/scripts/bitrix-attach-files.sh

@@ -0,0 +1,55 @@
+#!/bin/bash
+# Standalone artifact attach orchestrator — can be called manually or by hooks.
+# Usage: bitrix-attach-files.sh <task_id> <session_id> <file1> [<file2> ...]
+# Each file is uploaded to the task's group drive under AI Sessions/<repo>/<rel_dir>/
+# and attached to the task. Prints drive file IDs to stdout (one per line).
+# Exit 0 always — individual file failures are logged to stderr and skipped.
+
+set -euo pipefail
+source "$(dirname "$0")/bitrix-lib.sh"
+
+_b24_preflight || exit 0
+
+TASK_ID="${1:-}"
+SESSION_ID="${2:-default}"
+shift 2 2>/dev/null || true
+
+if [[ -z "$TASK_ID" ]]; then
+  echo "Usage: bitrix-attach-files.sh <task_id> <session_id> <file1> [<file2> ...]" >&2
+  exit 1
+fi
+
+[[ "$#" -eq 0 ]] && exit 0
+
+ATTACHED=()
+for FILE_PATH in "$@"; do
+  if [[ ! -f "$FILE_PATH" ]]; then
+    echo "[bitrix-attach-files] skip (not found): $FILE_PATH" >&2
+    continue
+  fi
+
+  REL_DIR=$(dirname "$FILE_PATH")
+  DRIVE_ID=$(b24_attach_artifact "$TASK_ID" "$FILE_PATH" "$SESSION_ID" "$REL_DIR") || {
+    echo "[bitrix-attach-files] failed to attach: $FILE_PATH" >&2
+    continue
+  }
+
+  if [[ -n "$DRIVE_ID" ]]; then
+    echo "$DRIVE_ID"
+    ATTACHED+=("$FILE_PATH")
+  fi
+done
+
+# Update session attach registry
+if [[ ${#ATTACHED[@]} -gt 0 ]]; then
+  ATTACH_LOG="$SESSION_DIR/attached-${SESSION_ID}.json"
+  ATTACHED_JSON=$(printf '%s\n' "${ATTACHED[@]}" | jq -R . | jq -s .)
+  if [[ -f "$ATTACH_LOG" ]]; then
+    EXISTING=$(cat "$ATTACH_LOG")
+    echo "$EXISTING $ATTACHED_JSON" | jq -s '.[0] + .[1] | unique' > "$ATTACH_LOG"
+  else
+    echo "$ATTACHED_JSON" > "$ATTACH_LOG"
+  fi
+fi
+
+exit 0