@synity/bitrix-skills 1.3.0

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

@@ -0,0 +1,131 @@
+#!/usr/bin/env bash
+# bx-state.sh — Project-local state file helpers for /bx:task skill.
+#
+# State file: .claude/bitrix-task-state.json (gitignored, project-local)
+#
+# Schema:
+#   {
+#     "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 }
+#     }
+#   }
+#
+# IMPORTANT: This schema deliberately omits a `webhook` field. Webhook URL must
+# come from `BITRIX_WEBHOOK_URL` env var. If an old state file with `webhook`
+# is detected, `bx_state_migrate` strips it (one-shot, backed up to .bak).
+#
+# Public functions:
+#   bx_state_file         — print path to state file (respects $BX_TASK_STATE_FILE override)
+#   bx_state_exists       — return 0 if state file exists, 1 otherwise
+#   bx_state_read         — print full JSON (or "{}" if missing)
+#   bx_state_get <key>    — print value at dot-path (jq filter), or empty
+#   bx_state_write <key> <value>       — set scalar value (auto numberify if numeric)
+#   bx_state_write_json <key> <json>   — set value from raw JSON
+#   bx_state_init         — create skeleton state file if missing
+#   bx_state_migrate      — strip deprecated `webhook` field (one-shot, with .bak)
+
+bx_state_file() {
+  echo "${BX_TASK_STATE_FILE:-.claude/bitrix-task-state.json}"
+}
+
+bx_state_exists() {
+  local f; f=$(bx_state_file)
+  [[ -f "$f" ]]
+}
+
+bx_state_read() {
+  local f; f=$(bx_state_file)
+  if [[ -f "$f" ]]; then cat "$f"; else echo '{}'; fi
+}
+
+bx_state_get() {
+  local key="$1"
+  bx_state_read | jq -r ".${key} // empty"
+}
+
+bx_state_write() {
+  local key="$1" value="$2"
+  local f; f=$(bx_state_file)
+  mkdir -p "$(dirname "$f")"
+  local tmp; tmp=$(mktemp)
+  # Strip outer quotes (prevents "\"x\"" double-wrap)
+  value="${value#\"}"; value="${value%\"}"
+  if bx_state_read | jq --arg v "$value" ".${key} = (\$v | try tonumber catch \$v)" > "$tmp" 2>/dev/null; then
+    mv "$tmp" "$f"
+  else
+    rm -f "$tmp"; return 1
+  fi
+}
+
+bx_state_write_json() {
+  local key="$1" json_value="$2"
+  local f; f=$(bx_state_file)
+  mkdir -p "$(dirname "$f")"
+  local tmp; tmp=$(mktemp)
+  if bx_state_read | jq --argjson v "$json_value" ".${key} = \$v" > "$tmp" 2>/dev/null; then
+    mv "$tmp" "$f"
+  else
+    rm -f "$tmp"; return 1
+  fi
+}
+
+bx_state_init() {
+  if bx_state_exists; then return 0; fi
+  local f; f=$(bx_state_file)
+  mkdir -p "$(dirname "$f")"
+  cat > "$f" <<'EOF'
+{
+  "claudeUserId": 614,
+  "responsibleId": 614,
+  "userMapping": {},
+  "mainTaskId": null,
+  "features": {},
+  "checklists": {}
+}
+EOF
+}
+
+bx_state_migrate() {
+  if ! bx_state_exists; then return 0; fi
+  local f; f=$(bx_state_file)
+  local has_webhook; has_webhook=$(jq -r 'has("webhook")' "$f" 2>/dev/null)
+  if [[ "$has_webhook" != "true" ]]; then return 0; fi
+
+  echo "⚠️  Detected deprecated 'webhook' field in $f — migrating to BITRIX_WEBHOOK_URL env var." >&2
+  echo "    Backup written to $f.bak" >&2
+  cp "$f" "$f.bak"
+  local tmp; tmp=$(mktemp)
+  jq 'del(.webhook)' "$f" > "$tmp" && mv "$tmp" "$f"
+}
+
+# --- User mapping (Bitrix uid lookup) ---
+
+_BX_GITHUB_USER=""
+bx_get_github_user() {
+  if [[ -z "$_BX_GITHUB_USER" ]]; then
+    _BX_GITHUB_USER=$(gh api user --jq '.login' 2>/dev/null || echo "")
+  fi
+  echo "$_BX_GITHUB_USER"
+}
+
+bx_get_claude_user_id() {
+  local id; id=$(bx_state_get "claudeUserId")
+  echo "${id:-614}"
+}
+
+# Returns Bitrix uid for current GitHub user, falls back to responsibleId in state
+bx_get_bitrix_user_id() {
+  local gh_user="${1:-$(bx_get_github_user)}"
+  if [[ -n "$gh_user" ]]; then
+    local mapped; mapped=$(bx_state_get "userMapping.\"$gh_user\"")
+    if [[ -n "$mapped" ]]; then echo "$mapped"; return; fi
+  fi
+  bx_state_get "responsibleId"
+}

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

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+# bx-tasks.sh — Task CRUD + comment helpers for /bx:task skill.
+#
+# Depends on:
+#   bx-api.sh     — bx_call_v1, bx_call_v3, bx_preflight
+#   bx-state.sh   — bx_get_claude_user_id, bx_get_bitrix_user_id
+#
+# Public functions:
+#   bx_task_get <id>                       — GET /tasks.task.get → raw JSON
+#   bx_task_create <title> <desc> [parentId] [responsibleId]
+#                                          — create task or subtask; returns task ID
+#   bx_task_update <taskId> <fieldsJson>   — patch DESCRIPTION/STATUS/etc.
+#   bx_task_complete <taskId>              — mark complete
+#   bx_task_comment <taskId> <message>     — task.commentitem.add as Claude
+#   bx_task_notify <taskId> <message>      — comment with [USER=N] mention prepended
+#   bx_task_elapsed <taskId> <seconds> [comment]
+#                                          — manual time entry
+#   bx_task_find_by_title <title>          — search; print first matching ID or empty
+
+# --- Internal: build temp JSON file, POST, clean up ---
+_bx_post() {
+  local method="$1"; local body="$2"
+  local tmp; tmp=$(mktemp)
+  echo "$body" > "$tmp"
+  local resp; resp=$(curl -sS -m 15 -X POST "${BITRIX_WEBHOOK_URL%/}/${method}" \
+    -H "Content-Type: application/json" -d @"$tmp" 2>/dev/null)
+  rm -f "$tmp"
+  echo "$resp"
+}
+
+bx_task_get() {
+  local id="$1"
+  local body; body=$(jq -n --arg id "$id" '{taskId: ($id | tonumber)}')
+  _bx_post "tasks.task.get" "$body"
+}
+
+bx_task_create() {
+  local title="$1"; local desc="${2:-}"; local parent="${3:-0}"
+  local rid="${4:-$(bx_get_claude_user_id)}"
+
+  local body
+  if [[ "$parent" != "0" && -n "$parent" ]]; then
+    body=$(jq -n --arg t "$title" --arg d "$desc" --arg r "$rid" --arg p "$parent" \
+      '{fields: {TITLE: $t, DESCRIPTION: $d, RESPONSIBLE_ID: ($r|tonumber),
+                 PARENT_ID: ($p|tonumber), ALLOW_TIME_TRACKING: "Y"}}')
+  else
+    body=$(jq -n --arg t "$title" --arg d "$desc" --arg r "$rid" \
+      '{fields: {TITLE: $t, DESCRIPTION: $d, RESPONSIBLE_ID: ($r|tonumber),
+                 ALLOW_TIME_TRACKING: "Y"}}')
+  fi
+
+  local resp; resp=$(_bx_post "tasks.task.add" "$body")
+  # Description fields contain literal newlines → invalid JSON for jq.
+  # Use Python regex extraction (proven pattern from old skill).
+  echo "$resp" | python3 -c "import sys,re; m=re.search(r'\"id\":\"(\d+)\"', sys.stdin.read()); print(m.group(1) if m else '')"
+}
+
+# Update task fields. fieldsJson = JSON object (e.g., '{"DESCRIPTION":"..."}')
+# Uses Python json.dumps to safely encode multiline BB-code (avoids jq newline parse errors).
+bx_task_update() {
+  local id="$1"; local fields_json="$2"
+  python3 - "$id" "$fields_json" <<'PYEOF'
+import sys, json, os, urllib.request
+task_id = int(sys.argv[1])
+fields = json.loads(sys.argv[2])
+webhook = os.environ["BITRIX_WEBHOOK_URL"].rstrip("/")
+payload = json.dumps({"taskId": task_id, "fields": fields}).encode("utf-8")
+req = urllib.request.Request(f"{webhook}/tasks.task.update",
+    data=payload, headers={"Content-Type": "application/json"}, method="POST")
+with urllib.request.urlopen(req, timeout=15) as r:
+    print(r.read().decode("utf-8")[:200])
+PYEOF
+}
+
+bx_task_complete() {
+  local id="$1"
+  local body; body=$(jq -n --arg id "$id" '{taskId: ($id | tonumber)}')
+  _bx_post "tasks.task.complete" "$body" > /dev/null
+}
+
+bx_task_comment() {
+  local id="$1"; local msg="$2"
+  local aid; aid=$(bx_get_claude_user_id)
+  local body; body=$(jq -n --arg id "$id" --arg m "$msg" --arg a "$aid" \
+    '{TASKID: ($id|tonumber), FIELDS: {POST_MESSAGE: $m, AUTHOR_ID: ($a|tonumber)}}')
+  _bx_post "task.commentitem.add" "$body" > /dev/null
+}
+
+bx_task_notify() {
+  local id="$1"; local msg="$2"
+  local owner; owner=$(bx_get_bitrix_user_id)
+  local mention; mention=$(printf '[USER=%s][/USER] ' "$owner")
+  bx_task_comment "$id" "${mention}${msg}"
+}
+
+bx_task_elapsed() {
+  local id="$1"; local seconds="$2"; local comment="${3:-}"
+  local body; body=$(jq -n --arg id "$id" --arg s "$seconds" --arg c "$comment" \
+    '{TASKID: ($id|tonumber), ARFIELDS: {SECONDS: ($s|tonumber), COMMENT_TEXT: $c}}')
+  _bx_post "task.elapseditem.add" "$body" > /dev/null
+}
+
+# Search for task by title (exact %TITLE filter). Print first matching ID, or empty.
+bx_task_find_by_title() {
+  local title="$1"
+  local body; body=$(jq -n --arg t "$title" '{filter: {"%TITLE": $t}, select: ["ID"]}')
+  local resp; resp=$(_bx_post "tasks.task.list" "$body")
+  echo "$resp" | jq -r '.result.tasks[0].id // empty' 2>/dev/null
+}

package/src/features/bx-task/assets/references/bootstrap.md

@@ -0,0 +1,184 @@
+# /bx:task bootstrap — Rich project init in Bitrix24
+
+Creates the **main task** + per-phase **subtasks** + 3 root-level **checklist groups**
+(Done / Doing / Plan) on Bitrix24, then writes a project-local state file at
+`.claude/bitrix-task-state.json`. Description is rendered from a per-project-type
+BB-code template.
+
+## Args
+
+```
+/bx:task bootstrap [--type <npm-package|web-app|library|monorepo|cli-tool|generic>] [--dry-run] [--main-task-id N]
+```
+
+| Flag | Purpose |
+|------|---------|
+| `--type` | Skip auto-detection; force template choice |
+| `--dry-run` | Render preview + show payload; NO Bitrix writes, NO state file |
+| `--main-task-id` | Reuse an existing task (skip create); only adds subtasks + checklists + state |
+
+## Prerequisite check (MANDATORY)
+
+```bash
+MISSING=()
+[[ ! -f docs/project-overview-pdr.md ]] && MISSING+=("project-overview-pdr.md")
+[[ ! -f docs/system-architecture.md ]]  && MISSING+=("system-architecture.md")
+[[ ! -f docs/codebase-summary.md ]]     && MISSING+=("codebase-summary.md")
+if [[ ${#MISSING[@]} -gt 0 ]]; then
+  echo "⛔ Missing docs: ${MISSING[*]}"
+  echo "   Run first: /ck:docs init   (parallel codebase scan → generates docs/)"
+  echo "   Then re-run: /bx:task bootstrap"
+  exit 1
+fi
+```
+
+Hard block. Never fall back to thin description. Skill chaining: `/ck:docs init` → `/bx:task bootstrap`.
+
+## Project-type detection
+
+If `--type` not provided, run this decision tree in `$PROJECT_ROOT`:
+
+| Detector | Type |
+|----------|------|
+| `pnpm-workspace.yaml` OR `lerna.json` OR `.workspaces` in `package.json` | `monorepo` |
+| `next.config.*` / `vite.config.*` / `astro.config.*` / `pages/` or `app/` (Next-style) | `web-app` |
+| `package.json` has `bin` + no web framework deps + has CLI deps (`commander`/`yargs`/`citty`) | `cli-tool` |
+| `package.json` has `bin` + `files` + `publishConfig` (or `bin` + `main`) | `npm-package` |
+| `package.json` has `main`+`types` but no `bin` | `library` |
+| _else_ | `generic` |
+
+Print detected type and **confirm via `AskUserQuestion`** before render:
+
+> "Detected project type: **<type>**. Use template `init-templates/<type>.md`?"
+> Options: Yes / Choose other / Generic fallback
+
+## Data collection (fill template placeholders)
+
+| Placeholder | Source |
+|-------------|--------|
+| `{{PACKAGE_NAME}}` | `package.json:name` or repo dir name |
+| `{{ONE_LINE_VALUE_PROP}}` | `docs/project-overview-pdr.md` first H2/H3 paragraph, or `package.json:description` |
+| `{{INSTALL_COMMANDS}}` | `README.md` "Install" section block, or `package.json:scripts` |
+| `{{KEY_COMMANDS_OR_USAGE}}` | `README.md` "Commands" / "Usage" block |
+| `{{ASCII_DIAGRAM}}` | `docs/system-architecture.md` first `[code]` or ```` ``` ```` block; if none → generic 3-layer placeholder |
+| `{{FEATURE_MATRIX_ROWS}}` | `docs/codebase-summary.md` module table rows |
+| `{{PHASE_TIMELINE}}` | iterate `plans/<active>/phase-*.md`: emoji + title + 2-3 wins from "Success criteria" / completed items |
+| `{{OPEN_ISSUES}}` | `gh issue list --state open --limit 5 --json title,number` + grep `TODO\|FIXME` (top 5) |
+| `{{SUCCESS_CRITERIA}}` | Active phase's "Success criteria" section |
+| `{{REPO_URL}}` | `git config --get remote.origin.url` → normalize |
+| `{{PLAN_DIR}}` | Latest `plans/<date>-*/` by mtime |
+| `{{ACTIVE_PHASE_PATH}}` | Active phase from plan.md frontmatter `status: in_progress` |
+
+Emoji bank for phase timeline: 🏷️ rename · 🛠 fix · 🧪 test · 🔒 security · 🧰 ux · ⭐ quality · 🚀 release · 📦 package · 🪙 cost · ⏱ time · 🎬 ui · 📚 docs · 🔍 research
+
+## Algorithm
+
+```bash
+source ~/.claude/skills/bx-task/lib/bx-api.sh
+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
+
+# 0. Preflight
+bx_preflight || exit 1
+bx_state_migrate          # strip deprecated webhook field if present
+bx_state_init             # create skeleton if missing
+
+# 1. Prerequisite docs check (above)
+
+# 2. Project type detection (above) → $TYPE
+
+# 3. Read template
+TEMPLATE="$(dirname "$0")/../references/init-templates/${TYPE}.md"
+[[ ! -f "$TEMPLATE" ]] && { echo "ERROR: template not found: $TEMPLATE"; exit 1; }
+
+# 4. Data collection (above) → write rendered description to /tmp/bx-desc.bb
+
+# 5. Confirm preview (AskUserQuestion with first 30 lines of /tmp/bx-desc.bb)
+
+# 6. Branch on --dry-run
+if [[ "$DRY_RUN" == "1" ]]; then
+  echo "=== DRY RUN — rendered description ==="
+  cat /tmp/bx-desc.bb
+  echo "=== END (no Bitrix writes, no state changes) ==="
+  exit 0
+fi
+
+# 7. Duplicate check
+EXISTING=$(bx_state_get "mainTaskId")
+if [[ -n "$EXISTING" && "$EXISTING" != "null" ]]; then
+  echo "Main task already exists: #$EXISTING — skipping create"
+  MAIN_ID="$EXISTING"
+elif [[ -n "$MAIN_TASK_ID_FLAG" ]]; then
+  MAIN_ID="$MAIN_TASK_ID_FLAG"
+  bx_state_write "mainTaskId" "$MAIN_ID"
+else
+  FOUND=$(bx_task_find_by_title "$PACKAGE_NAME")
+  if [[ -n "$FOUND" ]]; then
+    echo "Found existing task #$FOUND with same title — reusing"
+    MAIN_ID="$FOUND"
+    bx_state_write "mainTaskId" "$MAIN_ID"
+  else
+    DESC=$(cat /tmp/bx-desc.bb)
+    MAIN_ID=$(bx_task_create "$PACKAGE_NAME" "$DESC")
+    bx_state_write "mainTaskId" "$MAIN_ID"
+    echo "Created main task #$MAIN_ID"
+  fi
+fi
+
+# 8. Update description if main existed (always refresh to latest)
+bx_task_update "$MAIN_ID" "{\"DESCRIPTION\": $(jq -Rs . < /tmp/bx-desc.bb)}"
+
+# 9. Per-phase subtasks
+for PHASE_FILE in plans/*/phase-*.md; do
+  PHASE_TITLE=$(grep -m1 '^# Phase' "$PHASE_FILE" | sed 's/^# //')
+  EXISTING_SUB=$(bx_state_get "features.\"$PHASE_TITLE\".taskId")
+  if [[ -z "$EXISTING_SUB" || "$EXISTING_SUB" == "null" ]]; then
+    SUB_ID=$(bx_task_create "$PHASE_TITLE" "See $PHASE_FILE" "$MAIN_ID")
+    STATUS=$(grep -m1 '^status:' "$PHASE_FILE" | awk '{print $2}')
+    bx_state_write "features.\"$PHASE_TITLE\".taskId" "$SUB_ID"
+    bx_state_write "features.\"$PHASE_TITLE\".status" "$STATUS"
+    [[ "$STATUS" == "complete" || "$STATUS" == "done" ]] && bx_task_complete "$SUB_ID"
+    echo "Subtask #$SUB_ID — $PHASE_TITLE ($STATUS)"
+  fi
+done
+
+# 10. Initialize 3 root checklists (Done/Doing/Plan) — idempotent: skip if state.checklists populated
+if [[ -z "$(bx_state_get 'checklists.done.parentId')" ]]; then
+  bx_checklist_init "$MAIN_ID"
+fi
+
+# 11. Populate checklist items per phase status
+for PHASE_FILE in plans/*/phase-*.md; do
+  PHASE_TITLE=$(grep -m1 '^# Phase' "$PHASE_FILE" | sed 's/^# //')
+  STATUS=$(grep -m1 '^status:' "$PHASE_FILE" | awk '{print $2}')
+  case "$STATUS" in
+    complete|done)     GROUP=done ;;
+    in_progress|active) GROUP=doing ;;
+    *)                 GROUP=plan ;;
+  esac
+  EXISTING_ITEM=$(bx_checklist_find_item "$MAIN_ID" "$GROUP" "$PHASE_TITLE")
+  if [[ -z "$EXISTING_ITEM" ]]; then
+    ITEM_ID=$(bx_checklist_add "$MAIN_ID" "$GROUP" "$PHASE_TITLE")
+    [[ "$GROUP" == "done" ]] && bx_checklist_toggle "$MAIN_ID" "$ITEM_ID" "Y"
+  fi
+done
+
+# 12. Notify
+bx_task_notify "$MAIN_ID" "[B]Bootstrap complete[/B] — Type: ${TYPE}, Phases: $(ls plans/*/phase-*.md | wc -l)"
+```
+
+## Errors / UX
+
+- Missing docs → exit 1 with explicit `/ck:docs init` hint (see prerequisite section)
+- Template file missing → exit 1 with path
+- Webhook not set → bx_preflight prints clear error
+- Existing mainTaskId → reuse, refresh description only
+- `--dry-run` → render + show, no side effects
+
+## What NOT to do
+
+- ❌ Auto-fill missing docs with placeholder text (defeats the prerequisite check)
+- ❌ Skip `AskUserQuestion` confirmation before POST (KISS — show raw BB to user)
+- ❌ Hardcode webhook URL (always env var)
+- ❌ Use `[LIST]` / `[TABLE]` / `[IMG]` in chat comments (crashes mobile app — but OK in DESCRIPTION)

package/src/features/bx-task/assets/references/feature.md

@@ -0,0 +1,97 @@
+# /bx:task feature — Create a new feature subtask + checklist item + git branch
+
+Spawns a child task under `state.mainTaskId`, adds a checklist item under the **Doing**
+group, optionally creates a git branch `feature/{taskId}-{slug}`, and records the
+feature in state.
+
+## Args
+
+```
+/bx:task feature <name> [description] [--no-branch] [--description-file <path>]
+```
+
+| Flag | Purpose |
+|------|---------|
+| `--no-branch` | Skip `git checkout -b`. Useful for non-git projects or doc-only work. |
+| `--description-file` | Read description from file (multiline BB-code). Overrides `[description]` arg. |
+
+`<name>` is the human-readable feature name (used as task title + checklist item). Slug
+for branch is `name | tr ' /' '-' | tr '[:upper:]' '[:lower:]'` (kebab-case lowercase).
+
+## Prerequisite
+
+State must contain `mainTaskId` and `checklists.doing.parentId`. If missing, run
+`/bx:task bootstrap` first. Skill prints clear error and exits 1.
+
+## Algorithm
+
+```bash
+source ~/.claude/skills/bx-task/lib/bx-api.sh
+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_preflight || exit 1
+bx_state_migrate
+
+MAIN_ID=$(bx_state_get "mainTaskId")
+DOING_PID=$(bx_state_get "checklists.doing.parentId")
+
+if [[ -z "$MAIN_ID" || -z "$DOING_PID" ]]; then
+  echo "⛔ State not bootstrapped. Run /bx:task bootstrap first." >&2
+  exit 1
+fi
+
+# Resolve description
+if [[ -n "$DESCRIPTION_FILE" ]]; then
+  DESC=$(cat "$DESCRIPTION_FILE")
+elif [[ -n "$DESCRIPTION_ARG" ]]; then
+  DESC="$DESCRIPTION_ARG"
+else
+  DESC="Feature: $NAME"
+fi
+
+# Confirm before POST (KISS — show what gets created)
+# AskUserQuestion: "Create subtask under #$MAIN_ID with title '$NAME'?"
+# Options: Yes / Cancel
+
+# 1. Create subtask
+TASK_ID=$(bx_task_create "$NAME" "$DESC" "$MAIN_ID")
+[[ -z "$TASK_ID" ]] && { echo "ERROR: task create failed" >&2; exit 1; }
+
+# 2. Add checklist item under Doing
+ITEM_ID=$(bx_checklist_add "$MAIN_ID" "doing" "$NAME")
+
+# 3. Record in state
+bx_state_write "features.\"$NAME\".taskId" "$TASK_ID"
+bx_state_write "features.\"$NAME\".status" "active"
+
+# 4. Git branch (unless --no-branch)
+if [[ "$NO_BRANCH" != "1" ]] && command -v git >/dev/null 2>&1 && [[ -d .git || -f .git ]]; then
+  SLUG=$(echo "$NAME" | tr ' /' '--' | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9-]//g')
+  BRANCH="feature/${TASK_ID}-${SLUG}"
+  git checkout -b "$BRANCH" 2>&1 || echo "(branch exists or not in git repo)"
+fi
+
+# 5. Notify main task
+bx_task_notify "$MAIN_ID" "[B]New feature:[/B] ${NAME} → subtask #${TASK_ID}"
+
+# 6. Notify subtask (start marker)
+bx_task_comment "$TASK_ID" "[B]Started[/B] — feature workflow active"
+
+echo "✓ Created feature '$NAME' → task #$TASK_ID, branch ${BRANCH:-<skipped>}"
+```
+
+## Errors / UX
+
+- Missing mainTaskId / checklists.doing → exit 1, hint to run `bootstrap`
+- Webhook not set → bx_preflight handles
+- Feature already exists in state → warn + ask if user wants to overwrite or reuse taskId
+- Git branch create fails (e.g., branch exists) → continue, print warning (task is still created)
+- Name with special chars → slug strips to `[a-z0-9-]`; empty slug after strip → error
+
+## What NOT to do
+
+- ❌ Skip the `mainTaskId` precondition (creates orphan tasks)
+- ❌ Auto-overwrite existing feature in state (always confirm)
+- ❌ Push the new branch (user controls when to push — `git push -u origin` is manual)

package/src/features/bx-task/assets/references/init-templates/cli-tool.md

@@ -0,0 +1,47 @@
+[B]{{PACKAGE_NAME}}[/B] — {{ONE_LINE_VALUE_PROP}}
+
+[B]Install[/B]
+[code]
+{{INSTALL_COMMANDS}}
+[/code]
+
+[B]Commands & Flags[/B]
+[code]
+{{KEY_COMMANDS_OR_USAGE}}
+[/code]
+
+[B]Exit Codes[/B]
+[table]
+[tr][th]Code[/th][th]Meaning[/th][/tr]
+[tr][td]0[/td][td]Success[/td][/tr]
+[tr][td]1[/td][td]Generic error / failed precondition[/td][/tr]
+[tr][td]2[/td][td]Usage error (bad flag / missing arg)[/td][/tr]
+{{EXTRA_EXIT_CODES}}
+[/table]
+
+[B]Architecture[/B]
+[code]
+{{ASCII_DIAGRAM}}
+[/code]
+
+[B]Subcommands[/B]
+[table]
+[tr][th]Command[/th][th]Action[/th][th]Args[/th][/tr]
+{{FEATURE_MATRIX_ROWS}}
+[/table]
+
+[B]Phase Timeline[/B]
+{{PHASE_TIMELINE}}
+
+[B]Open Issues[/B]
+{{OPEN_ISSUES}}
+
+[B]Success Criteria[/B]
+{{SUCCESS_CRITERIA}}
+
+[B]Liên kết[/B]
+• Repo: [URL={{REPO_URL}}]{{REPO_SHORT}}[/URL]
+• Plan dir: {{PLAN_DIR}}
+• Active phase: {{ACTIVE_PHASE_PATH}}
+• Docs: docs/project-overview-pdr.md, docs/system-architecture.md, docs/codebase-summary.md
+• README: README.md

package/src/features/bx-task/assets/references/init-templates/generic.md

@@ -0,0 +1,31 @@
+[B]{{PACKAGE_NAME}}[/B] — {{ONE_LINE_VALUE_PROP}}
+
+[B]Purpose[/B]
+{{PURPOSE_PARAGRAPH}}
+
+[B]Architecture[/B]
+[code]
+{{ASCII_DIAGRAM}}
+[/code]
+
+[B]Components[/B]
+[table]
+[tr][th]Module[/th][th]Role[/th][/tr]
+{{FEATURE_MATRIX_ROWS}}
+[/table]
+
+[B]Phase Timeline[/B]
+{{PHASE_TIMELINE}}
+
+[B]Open Issues[/B]
+{{OPEN_ISSUES}}
+
+[B]Success Criteria[/B]
+{{SUCCESS_CRITERIA}}
+
+[B]Liên kết[/B]
+• Repo: [URL={{REPO_URL}}]{{REPO_SHORT}}[/URL]
+• Plan dir: {{PLAN_DIR}}
+• Active phase: {{ACTIVE_PHASE_PATH}}
+• Docs: docs/project-overview-pdr.md, docs/system-architecture.md, docs/codebase-summary.md
+• README: README.md

package/src/features/bx-task/assets/references/init-templates/library.md

@@ -0,0 +1,45 @@
+[B]{{PACKAGE_NAME}}[/B] — {{ONE_LINE_VALUE_PROP}}
+
+[B]Install[/B]
+[code]
+{{INSTALL_COMMANDS}}
+[/code]
+
+[B]Usage[/B]
+[code]
+{{KEY_COMMANDS_OR_USAGE}}
+[/code]
+
+[B]Public API[/B]
+[table]
+[tr][th]Export[/th][th]Type[/th][th]Description[/th][/tr]
+{{FEATURE_MATRIX_ROWS}}
+[/table]
+
+[B]Architecture[/B]
+[code]
+{{ASCII_DIAGRAM}}
+[/code]
+
+[B]Versioning & Compat[/B]
+• Semver: {{SEMVER_POLICY}}
+• Node: {{NODE_VERSION}}
+• Breaking changes: see CHANGELOG.md
+
+[B]Phase Timeline[/B]
+{{PHASE_TIMELINE}}
+
+[B]Open Issues[/B]
+{{OPEN_ISSUES}}
+
+[B]Success Criteria[/B]
+{{SUCCESS_CRITERIA}}
+
+[B]Liên kết[/B]
+• Repo: [URL={{REPO_URL}}]{{REPO_SHORT}}[/URL]
+• npm: [URL=https://www.npmjs.com/package/{{PACKAGE_NAME}}]{{PACKAGE_NAME}}[/URL]
+• Plan dir: {{PLAN_DIR}}
+• Active phase: {{ACTIVE_PHASE_PATH}}
+• Docs: docs/project-overview-pdr.md, docs/system-architecture.md, docs/codebase-summary.md
+• README: README.md
+• CHANGELOG: CHANGELOG.md

package/src/features/bx-task/assets/references/init-templates/monorepo.md

@@ -0,0 +1,38 @@
+[B]{{PACKAGE_NAME}}[/B] — {{ONE_LINE_VALUE_PROP}}
+
+[B]Setup[/B]
+[code]
+{{INSTALL_COMMANDS}}
+[/code]
+
+[B]Workspaces[/B]
+[table]
+[tr][th]Package[/th][th]Path[/th][th]Role[/th][/tr]
+{{FEATURE_MATRIX_ROWS}}
+[/table]
+
+[B]Architecture[/B]
+[code]
+{{ASCII_DIAGRAM}}
+[/code]
+
+[B]Build Matrix[/B]
+[code]
+{{BUILD_COMMANDS}}
+[/code]
+
+[B]Phase Timeline[/B]
+{{PHASE_TIMELINE}}
+
+[B]Open Issues[/B]
+{{OPEN_ISSUES}}
+
+[B]Success Criteria[/B]
+{{SUCCESS_CRITERIA}}
+
+[B]Liên kết[/B]
+• Repo: [URL={{REPO_URL}}]{{REPO_SHORT}}[/URL]
+• Plan dir: {{PLAN_DIR}}
+• Active phase: {{ACTIVE_PHASE_PATH}}
+• Docs: docs/project-overview-pdr.md, docs/system-architecture.md, docs/codebase-summary.md
+• README: README.md