@synity/bitrix-skills 1.3.1 → 1.3.2

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.