@synity/bitrix-skills 1.3.0

package/src/features/bx-crm/assets/onboard.md

@@ -0,0 +1,127 @@
+# bx:crm — Onboard (Write SOP)
+
+Covers: contact, company (VN), deal, lead creation.
+
+---
+
+## Phone Normalization (CRITICAL)
+
+`upsertContact` auto-normalizes — **pass raw phone, never pre-format**.
+
+| Input | Stored as |
+|-------|-----------|
+| `0977680550` | `+84977680550` |
+| `0977 68 0550` | `+84977680550` |
+| `84977680550` | `+84977680550` |
+| `+84977680550` | `+84977680550` (idempotent) |
+| `+6591234567` | `+6591234567` (non-VN: keep) |
+
+---
+
+## HONORIFIC
+
+| Input | Value |
+|-------|-------|
+| Anh / Mr | `Anh` |
+| Chị / Ms / Mrs | `Chị` |
+| Ông (senior male) | `Ông` |
+| Bà (senior female) | `Bà` |
+| Unknown | omit field |
+
+---
+
+## Contact — Minimum Fields + Dedup
+
+```js
+upsertContact({
+  name: "Nguyen Van A",
+  phone: "0977680550",      // raw — helper normalizes
+  email: "a@example.com",
+  HONORIFIC: "Anh",
+  match: { phone }          // dedup check before create
+})
+```
+
+Minimum: `name` + (`phone` OR `email`) + `HONORIFIC` (if determinable).
+
+---
+
+## Company — VN Rule (CRITICAL)
+
+**NEVER `crm.company.add` directly for VN companies with MST.**
+
+`upsertCompanyByTaxCode` auto-does:
+1. VietQR lookup → legal name + address from GDT tax registry
+2. Sets `RQ_INN` = `RQ_VAT_ID` = taxCode on requisite
+3. Creates address entity (needed for `{CompanyAddressLegal}` in document templates)
+
+```js
+upsertCompanyByTaxCode({
+  taxCode: "0315427733",   // MST — REQUIRED
+  title: "Pegasus Realty", // optional, VietQR fills if missing
+  phone: "...",
+  email: "...",
+})
+```
+
+**Verify checklist for company:**
+- `RQ_INN` populated
+- `RQ_VAT_ID` populated (same value)
+- `RQ_COMPANY_FULL_NAME` populated (legal name from registry)
+- Address entity exists (ENTITY_TYPE_ID=8)
+
+---
+
+## Deal — Required Fields
+
+Use `createDealWithParties` for atomic contact + company + deal in one call.
+
+| Field | How to get | Example |
+|-------|-----------|---------|
+| `STAGE_ID` | `codemode.entityIds()` → dealStageSemanticId | **never hardcode** |
+| `CURRENCY_ID` | from user input | `USD`, `VND` |
+| `OPPORTUNITY` | from user input (number) | `588` |
+| `SOURCE_ID` | see mapping below | `OTHER` |
+
+**SOURCE_ID mapping:**
+
+| Context | Value |
+|---------|-------|
+| Event / offline meeting | `OTHER` |
+| Website / form | `WEB` |
+| Referral / partner | `PARTNER` |
+| Cold call / outreach | `CALL` |
+| Social / ad | `ADVERTISING` |
+
+**COMMENTS — BANT template:**
+```
+Budget: <amount or range, or "unknown">
+Authority: <who makes the decision>
+Need: <specific problem / goal>
+Timeline: <when they want to start>
+Notes: <additional context>
+```
+
+> **Omit `idempotencyKey`** — causes D1 table error at runtime.
+
+---
+
+## Verify Checklist (mandatory after every write op)
+
+- [ ] Contact: `PHONE[0].VALUE` starts with `+84` for VN numbers
+- [ ] Company: `RQ_VAT_ID` populated, address entity exists
+- [ ] Deal: `STAGE_ID` set, `OPPORTUNITY > 0`, payer linked
+- [ ] Lead: `SOURCE_ID` set, phone/email present
+
+---
+
+## Known Pitfalls
+
+| Mistake | Symptom | Fix |
+|---------|---------|-----|
+| Used `bx-task` for CRM | Creates project task, not CRM record | Use `/bx:crm` |
+| `crm.contact.add` directly | No dedup, phone not normalized | `upsertContact` |
+| `crm.company.add` directly | Requisite missing RQ_VAT_ID + no address | `upsertCompanyByTaxCode` |
+| Passed `idempotencyKey` | D1 table error at runtime | Omit the field |
+| Pre-formatted phone `+84977...` | Helper double-normalizes (idempotent, fine) | Pass raw anyway |
+| Skipped verify step | Bugs discovered sessions later | Always verify |

package/src/features/bx-crm/assets/report.md

@@ -0,0 +1,98 @@
+# bx:crm — Report (Reporting Templates)
+
+Covers: dealForecast, stuckInStage, overdueActivities, arReport, teamReport.
+
+---
+
+## Helper Selection
+
+| Report | Helper | Typical Frequency |
+|--------|--------|-------------------|
+| Pipeline forecast month/quarter | `dealForecast` | Weekly |
+| Deals stuck too long in stage | `stuckInStage` | Weekly |
+| Overdue activities | `overdueActivities` | Daily |
+| AR aging + receivables | `arReport` | Monthly |
+| Cross-rep performance | `teamReport` | Monthly |
+| Per-entity payment history | `entityPayments` | On demand |
+
+---
+
+## Output Template — dealForecast
+
+```
+| Month  | Predicted | Won | At Risk | # Deals |
+|--------|-----------|-----|---------|---------|
+| T5/26  | $X        | $Y  | $Z      | N       |
+```
+
+Red flags: deals in same stage > 30 days with no activity → highlight with 🔴.
+
+---
+
+## Output Template — stuckInStage
+
+Group by pipeline stage → sort by days stuck DESC within each group.
+
+**Top 5 per stage:**
+```
+Stage: [Stage Name]
+  1. [dealId] "[title]" — [owner] — [N] days — last activity: [date]
+  2. ...
+```
+
+---
+
+## Output Template — overdueActivities
+
+```
+| Deal/Contact | Activity | Assigned | Due | Days Overdue |
+|-------------|----------|----------|-----|--------------|
+| ...         | ...      | ...      | ... | N            |
+```
+
+Sort by days overdue DESC. Group by assignee if > 10 items.
+
+---
+
+## Output Template — arReport (Aging Buckets)
+
+```
+| Bucket   | Amount | % of Total | # Invoices |
+|----------|--------|------------|------------|
+| Current  | $X     | X%         | N          |
+| 1–30d    | $X     | X%         | N          |
+| 31–60d   | $X     | X%         | N          |
+| 61–90d   | $X     | X%         | N          |
+| 90d+     | $X     | X%         | N          |  ← highlight if > 20%
+```
+
+For 90d+ bucket: list each debtor individually below the table.
+
+---
+
+## Interpretation Thresholds
+
+| Metric | Yellow ⚠️ | Red 🔴 | Action |
+|--------|----------|--------|--------|
+| stuckInStage | > 14 days | > 30 days | Assign follow-up activity |
+| AR 90d+ bucket | > 10% total AR | > 20% total AR | Escalate to account manager |
+| teamReport response_time | > 12h | > 24h | Flag for coaching |
+| overdueActivities per rep | > 5 | > 10 | Manager review |
+
+---
+
+## Common Report Calls
+
+```js
+// Weekly pipeline review
+dealForecast({ period: "month", includeAtRisk: true })
+
+// Stuck deals
+stuckInStage({ minDays: 14, pipelineId: null })  // null = all pipelines
+
+// Daily overdue check
+overdueActivities({ assignedTo: null })  // null = all reps
+
+// Monthly AR
+arReport({ groupByBucket: true, listDebtors90Plus: true })
+```

package/src/features/bx-crm/assets/research.md

@@ -0,0 +1,71 @@
+# bx:crm — Research (Analysis Protocol)
+
+Covers: customer360, contactSignals, dealSignals, customerJourney, chatHistory.
+
+---
+
+## Helper Selection
+
+| Need | Helper | Returns |
+|------|--------|---------|
+| Full customer overview | `customer360` | profile + deals + comms + invoices |
+| Quick risk signals | `contactSignals` | 8 sections raw context |
+| Deal health check | `dealSignals` | pipeline + activities + AR |
+| Historical narrative | `customerJourney` | stage transitions + communications |
+| Chat/Zalo transcript | `chatHistory` | multi-channel messages |
+| Next best action | `nextAction` | prioritized action recommendation |
+| Behavior pattern | `behaviorWindow` | engagement pattern last N days |
+
+---
+
+## Output Protocol — customer360
+
+Always present in this order:
+
+1. **Profile** — name, company, lifecycle stage, assigned rep
+2. **Deals** — active deals (stage, value, days in stage)
+3. **Last contact** — channel + date + 1-line content summary
+4. **Pending actions** — overdue activities, unpaid invoices
+5. **Recommendation** — next action in 1 concrete sentence
+
+---
+
+## Output Protocol — contactSignals / dealSignals
+
+1. **Risk level** — `HIGH` / `MEDIUM` / `LOW` + 1-line reason
+2. **Top 3 signals** — bulleted, most critical first
+3. **Next action** — specific, with suggested deadline
+4. **Reference** — contactId / dealId for traceability
+
+---
+
+## Output Protocol — customerJourney
+
+1. **Timeline** — chronological: stage changes + key communications
+2. **Turning points** — when did deal get stuck or advance?
+3. **Sentiment trend** — Positive / Neutral / Negative
+4. **Gap analysis** — longest silence period (in days)
+
+---
+
+## chatHistory Access Pattern
+
+```js
+chatHistory({
+  entityType: "contact",  // or "deal"
+  entityId: 123,
+  channels: ["chat", "zalo", "email"],  // optional filter
+  limit: 50
+})
+```
+
+Present as: `[date] [channel]: <1-line summary>` per message block.
+
+---
+
+## Pre-Research Checklist
+
+Before calling any intelligence helper:
+- [ ] Have contactId or dealId ready
+- [ ] Know the goal (overview / risk check / history / next action)
+- [ ] Use `codemode.search({ intent: "read" })` if unsure which helper fits

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

@@ -0,0 +1,10 @@
+{
+  "name": "bx-crm",
+  "displayName": "Bitrix CRM Skill",
+  "version": "2.0.0",
+  "target": "global",
+  "description": "Claude Code skill for Bitrix24 CRM: contacts, companies, deals, leads, estimates, invoices, customer analysis, pipeline reports",
+  "requires": {
+    "mcp": ["bitrix-synity-mcp"]
+  }
+}

package/src/features/bx-task/assets/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: bx:task
+description: "Synity Bitrix24 task ops — bootstrap project, manage features+roadmap, KB summaries, time-log, session sync, TASK_ID init. Subcommands: bootstrap, feature, roadmap, summary, time-log, sync, init. Self-contained, project-agnostic."
+argument-hint: "<subcommand> [args...]"
+version: "2.0.0"
+---
+
+# /bx:task — Bitrix24 Task Operations (Synity)
+
+Global Claude Code skill for Bitrix task ops. v2.0 = 7 subcommands grouped into 2 tiers:
+
+**Project lifecycle (state-aware, multi-feature):**
+
+| Subcommand | Purpose | Reference |
+|------------|---------|-----------|
+| `bootstrap [--type T] [--dry-run] [--main-task-id N]` | Rich project init: main task + per-phase subtasks + Done/Doing/Plan checklists | `references/bootstrap.md` |
+| `feature <name> [desc] [--no-branch]` | Create subtask + checklist item (Doing) + git branch | `references/feature.md` |
+| `roadmap add\|move <args>` | Manage Done/Doing/Plan checklist groups on main task | `references/roadmap.md` |
+
+**Per-task ops (single TASK_ID, project-agnostic):**
+
+| Subcommand | Purpose | API |
+|------------|---------|-----|
+| `summary [type]` | Post curated KB entry as Bitrix Task Result (5 templates) | `tasks.task.result.add` (v3) |
+| `time-log <duration> [comment]` | Manual time entry on task | `task.elapseditem.add` (v1) |
+| `sync [--task-id N]` | Post session digest (git log + context) as task comment | `task.commentitem.add` (v1) |
+| `init [--task-id N]` | Detect/insert `TASK_ID:` block in nearest CLAUDE.md | filesystem only |
+
+**Triggers:** `/bx:task <subcommand>`, "bootstrap bitrix project", "create feature subtask", "add to roadmap", "post task summary", "log time to bitrix", "sync session to bitrix", "init task id".
+
+## Pre-flight (mandatory)
+
+Before any subcommand:
+
+1. **`BITRIX_WEBHOOK_URL`** env var set (format: `https://<portal>.bitrix24.com/rest/<user>/<token>/`).
+2. **`jq`** + **`curl`** + **`python3`** on PATH (python3 used for safe multiline-JSON payloads).
+3. **TASK_ID** resolution priority (for per-task ops only):
+   `--task-id` arg > nearest `CLAUDE.md` with `^TASK_ID: <num>` > error.
+4. **Project-state ops** (`bootstrap`, `feature`, `roadmap`) read state from
+   `.claude/bitrix-task-state.json` (project-local, gitignored).
+
+Common preamble:
+
+```bash
+source ~/.claude/skills/bx-task/lib/bx-api.sh
+source ~/.claude/skills/bx-task/lib/bx-resolve-task.sh
+bx_preflight || exit 1
+# For project-state ops, also:
+source ~/.claude/skills/bx-task/lib/bx-state.sh
+source ~/.claude/skills/bx-task/lib/bx-tasks.sh
+source ~/.claude/skills/bx-task/lib/bx-checklist.sh
+bx_state_migrate           # one-shot: strip deprecated 'webhook' field if present
+```
+
+## Routing
+
+Parse first positional arg as `subcommand`:
+
+| First arg | Action |
+|-----------|--------|
+| _(empty)_ or `help` | Print usage (all 7 subcommands) |
+| `bootstrap` | Load `references/bootstrap.md` → follow its algorithm |
+| `feature` | Load `references/feature.md` → follow its algorithm |
+| `roadmap` | Load `references/roadmap.md` → follow its algorithm |
+| `summary` | Load `references/summary.md` |
+| `time-log` | Load `references/time-log.md` |
+| `sync` | Load `references/sync.md` |
+| `init` | Load `references/init.md` (TASK_ID block in CLAUDE.md — NOT project bootstrap) |
+| anything else | Error: `Unknown subcommand. Use: bootstrap \| feature \| roadmap \| summary \| time-log \| sync \| init` |
+
+The skill orchestrates via instructions to Claude — no shell dispatcher in `SKILL.md`. Claude reads the appropriate reference file and follows the algorithm written there.
+
+**Naming note:** `init` (here) = lightweight TASK_ID block insertion into CLAUDE.md.
+`bootstrap` = rich project bootstrap (main task + checklists + state). Do not confuse.
+
+## State file (project-state subcommands)
+
+Path: `.claude/bitrix-task-state.json` (project-local, gitignored)
+
+```json
+{
+  "claudeUserId": 614,
+  "responsibleId": 614,
+  "userMapping": { "github-username": <bitrix-uid> },
+  "mainTaskId": <number>,
+  "features": { "<name>": { "taskId": N, "status": "active|done|planned" } },
+  "checklists": {
+    "done":  { "parentId": N },
+    "doing": { "parentId": N },
+    "plan":  { "parentId": N }
+  }
+}
+```
+
+**Migration**: old skill stored `webhook` in this file. New skill REJECTS `webhook` field — use `BITRIX_WEBHOOK_URL` env. `bx_state_migrate()` strips the field on first run, with `.bak` backup.
+
+## Hard constraints
+
+- **BB code only** in text posted to Bitrix. See `.claude/rules/00-bitrix-task-sync.md` in Synity projects for BB↔markdown table.
+- **Chat/comment messages**: NEVER use `[LIST]`, `[TABLE]`, `[IMG]` — crashes Bitrix24 mobile. Use `\n• ` bullets. (Task DESCRIPTION fields tolerate full BB-code including `[table]`.)
+- **Self-contained**: NO dependency on project-level `.claude/scripts/bitrix-lib.sh`. Only `lib/bx-*.sh` shipped with this skill.
+- **Confirm before POST**: ask user via `AskUserQuestion` with raw BB preview before any write call (KISS — exact text fidelity, no pseudo-render).
+- **Fail-fast**: on network/5xx error → print error, exit 1. User re-runs manually. No automatic retry (avoids dup risk).
+- **Hard rule #11**: any new Bitrix REST method MUST be verified via `bitrix-dev-mcp` before adding.
+- **Prerequisite docs for `bootstrap`**: `docs/{project-overview-pdr,system-architecture,codebase-summary}.md` MUST exist. Missing → hard block + hint to run `/ck:docs init`. NO fallback to thin description.
+
+## Errors (UX)
+
+- TASK_ID missing (per-task ops) → hint: `Run inside a Bitrix project (CLAUDE.md with 'TASK_ID: N') or pass --task-id N.`
+- Webhook env missing → `ERROR: BITRIX_WEBHOOK_URL not set. Export it (e.g. https://portal.bitrix24.com/rest/USER_ID/TOKEN/).`
+- Missing docs for `bootstrap` → `Run first: /ck:docs init (parallel codebase scan → generates docs/)`
+- State not bootstrapped (for feature/roadmap) → `Run /bx:task bootstrap first.`
+- Unknown subcommand → see routing table above
+
+## Out of scope (v3+)
+
+- Auto-detect summary type from session context (git log, journal, transcript)
+- Auto-update phase status across plan.md + Bitrix from filesystem state
+- Cross-task batch summary
+- Browser-based Bitrix portal embed
+
+## Files
+
+```
+~/.claude/skills/bx-task/
+├── SKILL.md                       — this file (router + intro)
+├── references/
+│   ├── bootstrap.md               — /bx:task bootstrap spec
+│   ├── feature.md                 — /bx:task feature spec
+│   ├── roadmap.md                 — /bx:task roadmap spec
+│   ├── summary.md                 — /bx:task summary spec
+│   ├── time-log.md                — /bx:task time-log spec
+│   ├── sync.md                    — /bx:task sync spec
+│   ├── init.md                    — /bx:task init spec (TASK_ID block, not bootstrap)
+│   └── init-templates/            — per-project-type BB-code templates
+│       ├── npm-package.md
+│       ├── web-app.md
+│       ├── library.md
+│       ├── monorepo.md
+│       ├── cli-tool.md
+│       └── generic.md
+└── lib/
+    ├── bx-api.sh                  — bx_preflight, bx_call_v1, bx_call_v3
+    ├── bx-resolve-task.sh         — bx_resolve_task_id()
+    ├── bx-state.sh                — state file CRUD + migration + user mapping
+    ├── bx-tasks.sh                — task CRUD (create/update/complete/comment/notify/elapsed)
+    └── bx-checklist.sh            — Done/Doing/Plan helpers (init/add/move/toggle)
+```

package/src/features/bx-task/assets/lib/bx-api.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# bx-api.sh — Minimal Bitrix24 webhook caller for /bx:task skill.
+#
+# Provides:
+#   bx_preflight       — verify env + tools (BITRIX_WEBHOOK_URL, curl, jq)
+#   bx_call_v1 method body  — POST to /rest/{user}/{token}/{method}
+#   bx_call_v3 method body  — POST to /rest/api/{user}/{token}/{method}
+#                              (rewrites /rest/ → /rest/api/ for v3 family)
+#
+# Both wrappers: 10s timeout, JSON content-type, raw JSON to stdout.
+
+bx_preflight() {
+  if [[ -z "${BITRIX_WEBHOOK_URL:-}" ]]; then
+    echo "ERROR: BITRIX_WEBHOOK_URL not set. Export it (e.g. https://portal.bitrix24.com/rest/USER_ID/TOKEN/)." >&2
+    return 1
+  fi
+  command -v curl >/dev/null 2>&1 || { echo "ERROR: curl required on PATH" >&2; return 1; }
+  command -v jq   >/dev/null 2>&1 || { echo "ERROR: jq required on PATH"   >&2; return 1; }
+  return 0
+}
+
+bx_call_v1() {
+  local method="$1" body="$2"
+  curl -sS -m 10 -X POST "${BITRIX_WEBHOOK_URL%/}/${method}" \
+    -H "Content-Type: application/json" \
+    -d "$body"
+}
+
+bx_call_v3() {
+  local method="$1" body="$2"
+  local url="${BITRIX_WEBHOOK_URL%/}"
+  # Rewrite /rest/ → /rest/api/ via split (portable across bash/zsh; \/ escape behaves differently between shells)
+  local prefix="${url%%/rest/*}"
+  local suffix="${url#*/rest/}"
+  url="${prefix}/rest/api/${suffix}"
+  curl -sS -m 10 -X POST "${url}/${method}" \
+    -H "Content-Type: application/json" \
+    -d "$body"
+}

package/src/features/bx-task/assets/lib/bx-checklist.sh

@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+# bx-checklist.sh — High-level helpers for the Done/Doing/Plan checklist groups.
+#
+# Depends on:
+#   bx-state.sh   — state read/write for checklist parentIds
+#   bx-tasks.sh   — _bx_post for raw POST
+#   jq, curl, BITRIX_WEBHOOK_URL
+#
+# Public functions:
+#   bx_checklist_init <mainTaskId>          — create 3 root-level groups Done/Doing/Plan,
+#                                              return parentIds via state file
+#   bx_checklist_add <mainTaskId> <group> <title>
+#                                            — group ∈ {done, doing, plan}; print new item ID
+#   bx_checklist_toggle <mainTaskId> <itemId> <Y|N>
+#                                            — mark complete/incomplete
+#   bx_checklist_find_item <mainTaskId> <group> <title>
+#                                            — print first matching item ID or empty
+#   bx_checklist_move <mainTaskId> <title> <from> <to>
+#                                            — close in <from>, add (checked if to=done) in <to>
+#
+# Root group creation uses the "BX_CHECKLIST_1 rename" trick (see SKILL.md docs):
+# Bitrix24 auto-creates BX_CHECKLIST_1 wrapper on first item add. We rename it
+# to "Done", then add Doing/Plan with explicit PARENT_ID: 0.
+
+# Add a checklist node (item OR group depending on parent_id presence)
+_checklist_add_raw() {
+  local task_id="$1"; local title="$2"; local parent_id="${3:-}"
+  local body
+  if [[ -n "$parent_id" ]]; then
+    body=$(jq -n --arg id "$task_id" --arg t "$title" --arg p "$parent_id" \
+      '{TASKID: ($id|tonumber), FIELDS: {TITLE: $t, PARENT_ID: ($p|tonumber)}}')
+  else
+    body=$(jq -n --arg id "$task_id" --arg t "$title" \
+      '{TASKID: ($id|tonumber), FIELDS: {TITLE: $t}}')
+  fi
+  local resp; resp=$(_bx_post "task.checklistitem.add" "$body")
+  echo "$resp" | jq -r '.result'
+}
+
+_checklist_update_title() {
+  local task_id="$1"; local item_id="$2"; local title="$3"
+  local body; body=$(jq -n --arg id "$task_id" --arg i "$item_id" --arg t "$title" \
+    '{TASKID: ($id|tonumber), ITEMID: ($i|tonumber), FIELDS: {TITLE: $t}}')
+  _bx_post "task.checklistitem.update" "$body" > /dev/null
+}
+
+_checklist_delete() {
+  local task_id="$1"; local item_id="$2"
+  local body; body=$(jq -n --arg id "$task_id" --arg i "$item_id" \
+    '{TASKID: ($id|tonumber), ITEMID: ($i|tonumber)}')
+  _bx_post "task.checklistitem.delete" "$body" > /dev/null
+}
+
+_checklist_list() {
+  local task_id="$1"
+  local body; body=$(jq -n --arg id "$task_id" '{TASKID: ($id|tonumber)}')
+  _bx_post "task.checklistitem.getlist" "$body"
+}
+
+bx_checklist_init() {
+  local main_id="$1"
+
+  # Step 1: add placeholder → triggers auto BX_CHECKLIST_1 wrapper
+  local placeholder_id; placeholder_id=$(_checklist_add_raw "$main_id" "placeholder")
+
+  # Find the auto-created root (PARENT_ID == 0)
+  local list; list=$(_checklist_list "$main_id")
+  local done_root; done_root=$(echo "$list" | jq -r '.result[]? | select(.PARENT_ID == 0) | .ID' | head -1)
+
+  # Delete placeholder, rename root → "Done"
+  _checklist_delete "$main_id" "$placeholder_id"
+  _checklist_update_title "$main_id" "$done_root" "Done"
+
+  # Step 2: add Doing + Plan at root (PARENT_ID: 0 explicit)
+  local doing_id; doing_id=$(_checklist_add_raw "$main_id" "Doing" "0")
+  local plan_id;  plan_id=$(_checklist_add_raw  "$main_id" "Plan"  "0")
+
+  # Persist parentIds in state
+  bx_state_write "checklists.done.parentId"  "$done_root"
+  bx_state_write "checklists.doing.parentId" "$doing_id"
+  bx_state_write "checklists.plan.parentId"  "$plan_id"
+
+  echo "done=$done_root doing=$doing_id plan=$plan_id"
+}
+
+bx_checklist_add() {
+  local main_id="$1"; local group="$2"; local title="$3"
+  local parent_id; parent_id=$(bx_state_get "checklists.${group}.parentId")
+  if [[ -z "$parent_id" ]]; then
+    echo "ERROR: checklist group '$group' not initialized. Run bx_checklist_init first." >&2
+    return 1
+  fi
+  _checklist_add_raw "$main_id" "$title" "$parent_id"
+}
+
+bx_checklist_toggle() {
+  local main_id="$1"; local item_id="$2"; local complete="$3"
+  local body; body=$(jq -n --arg id "$main_id" --arg i "$item_id" --arg c "$complete" \
+    '{TASKID: ($id|tonumber), ITEMID: ($i|tonumber), FIELDS: {IS_COMPLETE: $c}}')
+  _bx_post "task.checklistitem.update" "$body" > /dev/null
+}
+
+bx_checklist_find_item() {
+  local main_id="$1"; local group="$2"; local title="$3"
+  local parent_id; parent_id=$(bx_state_get "checklists.${group}.parentId")
+  [[ -z "$parent_id" ]] && return 0
+  local list; list=$(_checklist_list "$main_id")
+  echo "$list" | jq -r --arg p "$parent_id" --arg t "$title" \
+    '.result[]? | select((.PARENT_ID == ($p|tonumber)) and (.TITLE == $t)) | .ID' | head -1
+}
+
+bx_checklist_move() {
+  local main_id="$1"; local title="$2"; local from="$3"; local to="$4"
+
+  # Mark item in <from> as complete (preserves history visibility)
+  local from_id; from_id=$(bx_checklist_find_item "$main_id" "$from" "$title")
+  if [[ -n "$from_id" ]]; then
+    bx_checklist_toggle "$main_id" "$from_id" "Y"
+  fi
+
+  # Add to <to>; if destination is "done", also toggle complete
+  local new_id; new_id=$(bx_checklist_add "$main_id" "$to" "$title")
+  if [[ "$to" == "done" && -n "$new_id" ]]; then
+    bx_checklist_toggle "$main_id" "$new_id" "Y"
+  fi
+  echo "$new_id"
+}

package/src/features/bx-task/assets/lib/bx-resolve-task.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# bx-resolve-task.sh — TASK_ID resolution helper for /bx:task skill.
+#
+# Resolution priority:
+#   1. Explicit arg (e.g. --task-id 9999)
+#   2. CLAUDE.md walk-up from $PWD (first '^TASK_ID: <num>' wins)
+#   3. Error + exit 1 with friendly hint
+#
+# Usage:
+#   source ~/.claude/skills/bx-task/lib/bx-resolve-task.sh
+#   TASK_ID=$(bx_resolve_task_id "${EXPLICIT_TASK_ID:-}") || exit 1
+
+bx_resolve_task_id() {
+  local explicit="${1:-}"
+  if [[ -n "$explicit" ]]; then
+    # Validate explicit --task-id is a positive integer. Without this guard,
+    # bx_resolve_task_id "abc" or "2776; rm -rf /" would return the raw string
+    # and surface only via cryptic 'jq: invalid JSON text passed to --argjson'.
+    if [[ ! "$explicit" =~ ^[0-9]+$ ]]; then
+      echo "ERROR: --task-id must be a positive integer (got: '$explicit')." >&2
+      return 1
+    fi
+    echo "$explicit"
+    return 0
+  fi
+  local dir="$PWD"
+  while [[ "$dir" != "/" && -n "$dir" ]]; do
+    if [[ -f "$dir/CLAUDE.md" ]]; then
+      local id
+      id=$(grep -m1 -E '^TASK_ID:[[:space:]]+[0-9]+' "$dir/CLAUDE.md" \
+           | awk '{print $2}')
+      if [[ -n "$id" ]]; then
+        echo "$id"
+        return 0
+      fi
+    fi
+    dir=$(dirname "$dir")
+  done
+  echo "ERROR: TASK_ID not found. Run inside a Bitrix project (CLAUDE.md with 'TASK_ID: N') or pass --task-id N." >&2
+  return 1
+}