@synity/bitrix-skills 1.3.0 → 1.3.2

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

@@ -1,13 +1,13 @@
 # bx:crm — Research (Analysis Protocol)
 
-Covers: customer360, contactSignals, dealSignals, customerJourney, chatHistory.
+Covers: customer360, contactSignals, dealSignals, customerJourney, chatHistory, nextAction, behaviorWindow.
 
 ---
 
 ## 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 |
@@ -20,31 +20,47 @@ Covers: customer360, contactSignals, dealSignals, customerJourney, chatHistory.
 
 ## 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
+1. **Profile** — name, company, lifecycle stage, assigned rep.
+2. **Deals** — active deals (stage, value, days in stage).
+3. **Last contact** — channel + date + 1-line 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
+1. **Risk level** — `HIGH` / `MEDIUM` / `LOW` + 1-line reason.
+2. **Top 3 signals** — 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)
+1. **Timeline** — stage changes + key communications.
+2. **Turning points** — when deal got stuck or advanced.
+3. **Sentiment trend** — Positive / Neutral / Negative.
+4. **Gap analysis** — longest silence period in days.
+
+---
+
+## Output Protocol — nextAction
+
+1. **Action** — one imperative sentence.
+2. **Reasoning** — 1-2 bullets explaining why now.
+3. **Deadline** — exact date/time when possible.
+4. **Reference** — source contactId/dealId.
+
+---
+
+## Output Protocol — behaviorWindow
+
+1. **Window** — date range and interaction count.
+2. **Trend** — Increasing / Stable / Declining.
+3. **Last 3 events** — date + channel + 1-line summary.
+4. **Recommendation** — next action tied to the trend.
 
 ---
 
@@ -52,20 +68,42 @@ Always present in this order:
 
 ```js
 chatHistory({
-  entityType: "contact",  // or "deal"
+  entityType: "contact",
   entityId: 123,
-  channels: ["chat", "zalo", "email"],  // optional filter
+  channels: ["chat", "zalo", "email"],
   limit: 50
 })
 ```
 
-Present as: `[date] [channel]: <1-line summary>` per message block.
+Present as: `[date] [channel]: <1-line summary>`.
+
+---
+
+## Example Dialog — customer360
+
+User: "phân tích contact #123 trước cuộc họp 2pm"
+
+LLM behavior: call `customer360({ contactId: 123 })`, then follow the customer360 output protocol.
+
+Sample output:
+```text
+Profile: Nguyen Van A, ABC Training, assigned to Linh.
+Deals: 2 active; main deal 80M VND stuck 18 days.
+Last contact: Zalo 2026-05-14, asked for contract terms.
+Pending actions: proposal follow-up overdue 1 day.
+Recommendation: Call before 14:00 and confirm decision timeline.
+```
 
 ---
 
 ## 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
+- [ ] Have contactId or dealId ready.
+- [ ] Know the goal: overview, risk check, history, next action, or behavior.
+- [ ] Use `codemode.search({ intent: "read" })` if unsure which helper fits.
+
+## Verify Checklist
+
+- [ ] Output cites source contactId/dealId.
+- [ ] Recommendations are based on returned signals, not invented context.
+- [ ] PII is summarized only as needed for the user's stated purpose.

package/src/features/bx-crm/assets/vn-norms.md

@@ -0,0 +1,50 @@
+# bx:crm — VN Normalization Reference
+
+Vietnam-specific normalization for phone, honorific, address, and MST.
+
+---
+
+## Phone Normalization
+
+`upsertContact` auto-normalizes. Pass raw user input.
+
+| Input | Stored as |
+|---|---|
+| `0977680550` | `+84977680550` |
+| `0977 68 0550` | `+84977680550` |
+| `84977680550` | `+84977680550` |
+| `+84977680550` | `+84977680550` |
+| `+6591234567` | `+6591234567` |
+
+Rules: strip spaces/dashes; VN leading `0` becomes `+84`; existing country code stays; non-VN numbers stay unchanged.
+
+---
+
+## HONORIFIC
+
+| Input | Value |
+|---|---|
+| Anh / Mr | `Anh` |
+| Chị / Ms / Mrs | `Chị` |
+| Em | `Em` |
+| Cô | `Cô` |
+| Chú | `Chú` |
+| Bác | `Bác` |
+| Ông (senior male) | `Ông` |
+| Bà (senior female) | `Bà` |
+| Unknown | omit field |
+
+---
+
+## Address + MST
+
+VN legal address should preserve: street, ward, district, province/city, country. Do not invent missing parts. Prefer GDT/VietQR registry data from `upsertCompanyByTaxCode`.
+
+- Company MST: usually 10 digits.
+- Branch MST: 13 digits, often `10-digit-parent-3-digit-branch`.
+- Store in Bitrix requisites as `RQ_INN` and `RQ_VAT_ID`.
+
+## Verify Checklist
+
+- [ ] Raw phone was passed to helper, not preformatted.
+- [ ] Missing address/MST parts were not invented.

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

@@ -4,7 +4,11 @@
   "version": "2.0.0",
   "target": "global",
   "description": "Claude Code skill for Bitrix24 CRM: contacts, companies, deals, leads, estimates, invoices, customer analysis, pipeline reports",
+  "status": "planned",
   "requires": {
-    "mcp": ["bitrix-synity-mcp"]
-  }
-}
+    "mcp": [
+      "bitrix-synity-mcp"
+    ]
+  },
+  "tier": 0
+}

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

@@ -5,6 +5,9 @@
   "target": "global",
   "description": "Claude Code skill for Bitrix24 task management",
   "requires": {
-    "mcp": ["bitrix-synity-mcp"]
-  }
-}
+    "mcp": [
+      "bitrix-synity-mcp"
+    ]
+  },
+  "tier": 0
+}

package/src/features/task-sync/assets/skill/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: bitrix-sync-install
+description: |
+  Install Bitrix Task Sync vào brownfield project (existing repo).
+  Wraps `npx @synity/bitrix-task-sync` với interactive TASK_ID setup,
+  webhook env var detection, và live verify smoke test.
+
+  Use when:
+  - User says "install bitrix sync", "setup task tracking", "thêm bitrix sync vào dự án"
+  - User asks how to enable AI session sync to Bitrix24 task chat
+  - Brownfield project not scaffolded by `create-bitrix-app`
+tools: [Bash, Read, Edit, AskUserQuestion]
+---
+
+# /bitrix-sync-install — Install Bitrix Task Sync (interactive)
+
+Orchestrate installation of [@synity/bitrix-task-sync](https://www.npmjs.com/package/@synity/bitrix-task-sync) into the current project. **Skill = thin wrapper** — all file copy / settings merge / githook setup is delegated to the npm CLI. Skill only handles interactive bits CLI cannot do (CLAUDE.md edit, env var detection, user confirmation gates).
+
+## Workflow (7 steps with user confirmation)
+
+### Step 1 — Detect project state
+
+Run via Bash to inspect current dir:
+
+```bash
+pwd && ls -la .claude .githooks docs CLAUDE.md 2>/dev/null
+```
+
+Show user what already exists. **Decision:**
+- If `.claude/scripts/bitrix-*.sh` already exists → skip to Step 7 (verify only)
+- Else → proceed Step 2
+
+### Step 2 — Preflight check
+
+Confirm bash deps present:
+
+```bash
+command -v jq && command -v curl && command -v awk && echo "OK"
+```
+
+If any missing → abort, instruct user to install (`brew install jq` on macOS).
+
+### Step 3 — Dry-run install
+
+```bash
+npx -y @synity/bitrix-skills install --dry-run
+```
+
+Show planned actions. **Always pin exact version** (never `@latest`).
+
+### Step 4 — Confirm + install
+
+Use `AskUserQuestion`:
+
+```
+Question: "Proceed with install? (review the dry-run plan above)"
+Options:
+  - "Yes, install" — runs `npx ... install`
+  - "No, abort" — exit skill
+```
+
+If yes:
+
+```bash
+npx -y @synity/bitrix-skills install
+```
+
+### Step 5 — TASK_ID setup
+
+Read `CLAUDE.md` (project root). Search for `TASK_ID:` pattern.
+
+**Missing case:**
+1. `AskUserQuestion` for `PORTAL` URL (e.g. `https://yourname.bitrix24.com`)
+2. `AskUserQuestion` for `TASK_ID` (numeric task ID from Bitrix24 task URL)
+3. Validate `TASK_ID` is numeric (reject `1234abc`)
+4. Use `Edit` to insert at end of CLAUDE.md:
+
+```markdown
+
+## Bitrix Task
+
+PORTAL: {portal_url}
+TASK_ID: {task_id}
+
+<!-- AI session activity auto-syncs to this task via .claude/scripts/bitrix-*.sh hooks -->
+<!-- See docs/bitrix-task-sync.md for setup details -->
+```
+
+**Present case:** display existing TASK_ID + ask user to confirm or update.
+
+### Step 6 — Webhook env var
+
+Check current shell env:
+
+```bash
+[ -n "$BITRIX_WEBHOOK_URL" ] && echo SET || echo UNSET
+```
+
+If `UNSET`, `AskUserQuestion`:
+
+```
+Question: "Where to add BITRIX_WEBHOOK_URL?"
+Options:
+  - ".envrc (direnv)"
+  - "~/.zshrc"
+  - "~/.bashrc"
+  - "Skip — I'll do it manually"
+```
+
+Print the exact `export` command. Wait for user to confirm they ran `source <file>` (or restarted shell). **NEVER auto-edit shell rc files** — could conflict with user's setup.
+
+Example output:
+```
+Add this line to ~/.zshrc:
+  export BITRIX_WEBHOOK_URL="https://yourname.bitrix24.com/rest/USER_ID/TOKEN/"
+Then run: source ~/.zshrc
+
+(Press confirm when done)
+```
+
+### Step 7 — Verify
+
+```bash
+npx -y @synity/bitrix-skills verify
+```
+
+Interpret exit codes:
+
+| Code | Meaning | User Action |
+|------|---------|-------------|
+| 0 | Success — comment posted | Done. |
+| 1 | TASK_ID missing in CLAUDE.md | Re-run Step 5 |
+| 2 | BITRIX_WEBHOOK_URL not set | Re-run Step 6 |
+| 3 | Webhook call failed (network/token error) | Verify webhook URL is correct + has perms |
+| 4 | Manifest drift detected | Run `npx @synity/bitrix-task-sync update` to repair |
+
+## Final summary
+
+On success, print:
+
+```
+✓ Bitrix Task Sync installed and verified
+
+Next: every commit must include [B24:{TASK_ID}] tag, e.g.:
+  feat: implement deal sync [B24:{task_id}]
+
+AI activity (skills) auto-syncs to: {portal_url}/company/personal/user/USER/tasks/task/view/{task_id}/
+```
+
+## Failure modes
+
+| Symptom | Likely cause | Fix |
+|---------|--------------|-----|
+| `command not found: jq` | macOS without homebrew | `brew install jq curl` |
+| `npx: not found` | Node not installed | Install Node 20+ from nodejs.org |
+| `git: not a repository` | Not in git repo | `git init` first |
+| Webhook returns 401 | Bad token | Regenerate webhook in Bitrix24 → Apps → Webhooks |
+| `TASK_ID: 1234abc` rejected | Non-numeric value | Use ID from task URL, e.g. `12345` |
+
+## Re-run behavior
+
+Re-running on already-installed project:
+- Step 1 detects existing `.claude/scripts/bitrix-*.sh`
+- Skips to Step 7 (verify only)
+- If verify passes → "Already installed and working"
+- If verify fails → suggests `update` command
+
+## Notes
+
+- **Pin version**: every `npx` example uses `@0.1.0` exact pin. Never `@latest`. User must explicitly bump after reading CHANGELOG.
+- **Project-scope only**: skill operates on current cwd's git root. Does NOT touch other projects.
+- **Idempotent**: re-run = no-op if state is good.
+- **No secrets logged**: skill never echoes `BITRIX_WEBHOOK_URL` value, only its set/unset status.

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

@@ -4,9 +4,14 @@
   "version": "0.3.0-pre",
   "target": "project",
   "description": "AI session sync to Bitrix task chat via hooks",
-  "needs": ["bash-lib"],
+  "needs": [
+    "bash-lib"
+  ],
   "requires": {
-    "env": ["BITRIX_WEBHOOK_URL"],
+    "env": [
+      "BITRIX_WEBHOOK_URL"
+    ],
     "task_id": true
-  }
-}
+  },
+  "tier": 0
+}