# Feature: bx-task

Installs the `bx-task` Claude Code skill globally (`~/.claude/skills/bx-task/`).

## What gets installed

```
~/.claude/skills/bx-task/
├── SKILL.md              # router (v2.0 — 7 subcommands)
├── lib/                  # 5 bash libs (api, resolve-task, state, tasks, checklist)
└── references/           # 7 subcommand specs + 6 init templates
    └── init-templates/   # per-project-type BB-code shapes
```

## Requirements

- MCP server `bitrix-synity-mcp` configured in Claude Code settings
- `BITRIX_WEBHOOK_URL` env var
- `jq`, `curl`, `python3` on PATH

## Install

```bash
npx @synity/bitrix-skills install bx-task
```

## Subcommands

Two tiers:

**Project lifecycle (state-aware):** Uses `.claude/bitrix-task-state.json` for multi-feature tracking.

| Command | Action |
|---------|--------|
| `/bx:task bootstrap [--type T] [--dry-run]` | Rich project init — main task + per-phase subtasks + Done/Doing/Plan checklists, description rendered from per-project-type template |
| `/bx:task feature <name> [desc] [--no-branch]` | Create subtask + checklist item in Doing + git branch `feature/{taskId}-{slug}` |
| `/bx:task roadmap add <group> <item>` | Add item to Done/Doing/Plan group |
| `/bx:task roadmap move <item> <from> <to>` | Move item between groups |

**Per-task ops (single TASK_ID, stateless):**

| Command | Action |
|---------|--------|
| `/bx:task summary [type]` | Post curated KB entry (release / discovery / bug-postmortem / adr / failed-experiment) |
| `/bx:task time-log <duration> [comment]` | Manual time entry (e.g., `1h30m`) |
| `/bx:task sync [--task-id N]` | Post session digest as task comment |
| `/bx:task init [--task-id N]` | Insert `TASK_ID:` block in nearest CLAUDE.md |

## Prerequisite for `bootstrap`

`bootstrap` requires these docs to exist before running:

- `docs/project-overview-pdr.md`
- `docs/system-architecture.md`
- `docs/codebase-summary.md`

If missing, skill blocks with hint: **`Run first: /ck:docs init`** (parallel codebase scan
→ generates all 3 docs). Then re-run `/bx:task bootstrap`.

No fallback to thin description — prerequisite-first design.

## Init templates (per project type)

`bootstrap` auto-detects project type, or accepts `--type` to skip detection:

| Type | Detector | Sections |
|------|----------|----------|
| `npm-package` | `package.json:bin + files + publishConfig` | Install / Commands / Architecture / Feature Matrix / Phase Timeline / Open Issues / Success / Liên kết |
| `web-app` | `next.config.*` / `vite.config.*` / `pages/` | Dev-Build-Deploy / Routes / Architecture / Components+State / API / Deploy Targets / Phase Timeline / Liên kết |
| `library` | `package.json:main+types` (no `bin`) | Install / Usage / Public API / Architecture / Versioning / Phase Timeline / Liên kết |
| `monorepo` | `pnpm-workspace.yaml` / `lerna.json` / `package.json:workspaces` | Setup / Workspaces / Architecture / Build Matrix / Phase Timeline / Liên kết |
| `cli-tool` | `package.json:bin + commander/yargs/citty` | Install / Commands+Flags / Exit Codes / Architecture / Subcommands / Phase Timeline / Liên kết |
| `generic` | fallback | Purpose / Architecture / Components / Phase Timeline / Open Issues / Success / Liên kết |

All templates render rich BB-code (sections, `[code]` blocks, `[table]` comparisons, ASCII
diagrams, phase timeline with emoji icons). See `references/init-templates/` for source.

## Feature + roadmap workflow

See [bx-task-feature-workflow.md](bx-task-feature-workflow.md) for the full subtask + 3-checklist-group lifecycle (Done/Doing/Plan).

## Note

This is a **manual** sync skill. Since the hook-based `bx-task-sync` auto-sync feature was
removed in v3.0.0, `bx-task` is the primary way to sync AI session activity to Bitrix. Run
`/bx:task sync` (or `summary`/`time-log`) at the end of a session. It reads `BITRIX_WEBHOOK_URL`
and follows the `TASK_ID` walk-up convention.

The state file (`.claude/bitrix-task-state.json`) is project-local and gitignored — never
commit it.