SKILL.md

skills/bitrix-task-router/SKILL.md

1. ---
2. name: bitrix-task-router
3. description: >-
4. Auto-assign Bitrix24 tasks by a routing rule so nobody has to babysit the queue. Pulls open tasks
5. via the Bitrix REST API, decides who each one belongs to based on the task ID's parity and whether
6. the title contains a keyword (default "RUSH"), shows a preview table, and writes the assignments
7. back only after confirmation. Use when someone wants tasks distributed automatically between team
8. members, mentions "assign tasks", "route tasks", "even/odd task assignment", "RUSH tasks", or
9. wants to stop manually checking the Bitrix queue to hand work out. Built for Marco's
10. even-to-me/odd-to-Rafael rule but the routing is fully configurable.
11. ---
13. # Bitrix Task Router
15. Assign Bitrix24 tasks to the right person automatically, by rule, with a human check before anything is written.
17. ## What it does
19. 1. Reads open tasks from Bitrix24 via an inbound webhook.
20. 2. Applies a routing rule to decide the responsible person for each task.
21. 3. Prints a preview of every proposed change (task → new owner, and why).
22. 4. Writes the assignments back to Bitrix **only** when run with `--commit`. Default is a dry run.
24. Writing to the CRM is a real change to live data, so the script never writes on its own. Preview first, confirm, then commit. Once the team trusts the output, it can be wired to a scheduled task.
26. ## The routing rule
28. Default rule:
30. - Decide **parity** from the numeric task ID: even ID vs. odd ID.
31. - If the task **title contains the keyword** (default `RUSH`, case-insensitive): even → Hazel, odd → Matt.
32. - Otherwise (no keyword): even → Marco, odd → Rafael.
34. **Assumptions baked in that need confirming:**
36. - "Ending in an even/odd number" is read as the task **ID** being even/odd. If Marco means a different number (an order number in the title, a custom field), change `parity_source` in the config.
37. - The `RUSH` keyword is matched against the task **title**. If it lives in a tag, group, or custom field instead, change `keyword_field` in the config.
38. - A `RUSH` match **fully overrides** the default Marco/Rafael split. If instead it should be an additional filter on top, that's a different rule, so flag it.
40. All of this is in `config.json`, so tuning the rule does not mean touching the code.
42. ## Setup
44. 1. Copy `config.example.json` to `config.json` and fill in:
45. - `user_ids`: the Bitrix user IDs for Marco, Rafael, Hazel, Matt.
46. - `parity_source`, `keyword`, `keyword_field`: leave as defaults unless the assumptions above are wrong.
47. - `task_filter`: which tasks to consider (default: open and not closed).
48. 2. Copy `.env.example` to `.env` and set `BITRIX_WEBHOOK_URL` to the inbound webhook base URL (the `https://<domain>.bitrix24.com/rest/<user_id>/<token>/` one). The webhook needs **task** scope (read + write).
50. The webhook URL carries its own auth, so treat `.env` like a password. Don't commit it.
52. ## Running it
54. Dry run (the default: shows the plan, writes nothing):
56. ```bash
57. python scripts/bitrix_router.py
58. ```
60. Try the rule with no Bitrix connection, using bundled fake data:
62. ```bash
63. python scripts/bitrix_router.py --mock
64. ```
66. Commit the assignments to Bitrix (after you've eyeballed the dry run):
68. ```bash
69. python scripts/bitrix_router.py --commit
70. ```
72. ## Output
74. A table, one row per task: ID, title, current owner, proposed owner, and the reason ("RUSH + even -> hazel"). In dry-run mode it ends with a count of what *would* change. With `--commit` it reports each write and any failures.
76. ## How to read failures
78. - `BITRIX_WEBHOOK_URL not set` → `.env` missing or empty.
79. - HTTP 401 / "Invalid token" → webhook URL wrong or revoked.
80. - "INVALID_USER" on write → a user ID in `config.json` doesn't exist in Bitrix.
81. - Tasks come back empty → check `task_filter`; the default only pulls open tasks.
83. ## Going automatic
85. Once the dry runs look right and the team trusts it, this can run on a schedule (e.g. every 30 minutes) with `--commit`. Don't schedule the commit step until the preview has been validated against live data for a few days. An unsupervised mis-route is annoying to unwind.