p-backlog 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.5.0
+
+Claude Code plugin and other agents:
+
+- The repository is a Claude Code plugin marketplace: `/plugin marketplace add expatriate/p-backlog`, then
+  `/plugin install p-backlog@p-backlog` (English skill) or `p-backlog-ru@p-backlog` (Russian). The plugin brings the
+  skill and the Stop hook; the CLI still comes from npm, and the plugin needs p-backlog CLI 0.5.0 or newer (older CLIs
+  reject `hook stop --agent`).
+- `backlog setup` connects Codex CLI and Cursor too: it finds them by `$CODEX_HOME`/`~/.codex` and `~/.cursor`, links
+  the skill and adds the Stop hook to their `hooks.json`; `--agent claude|codex|cursor` limits it to one agent. Codex
+  runs the new hook only after you approve it once in `/hooks`; `setup` reminds you.
+- `backlog hook stop --agent codex|cursor` reads their Stop events; Cursor gets the re-check request as a follow-up
+  message.
+- With the plugin enabled, `setup` leaves Claude Code alone; `backlog setup --remove-manual` removes the skill links
+  and Stop hooks installed earlier; it cannot be combined with `--service`. Two Stop hooks in one turn (plugin and
+  manual) answer once.
+- `backlog config language` switches the skill for every agent where `setup` installed it and, with the plugin, tells
+  which plugin to install.
+- Cost statistics note that Codex and Cursor usage is not counted.
+
 ## 0.4.0
 
 Bulk triage in the web UI:

package/README.md

@@ -46,24 +46,35 @@ It consists of the `backlog` CLI, the `backlog` skill and a Stop hook for Claude
 
 ## Getting started
 
-1. **Install** (needs Node.js 22.13 or newer):
+1. **Install the CLI** (needs Node.js 22.13 or newer):
 
    ```bash
    npm i -g p-backlog
-   backlog setup --service
    ```
 
-   `npm i -g p-backlog` installs the CLI globally; `backlog setup --service` installs the skill and the
-   Stop hook for Claude Code and starts the web app as an autostart service.
+2. **Connect your agent.**
 
-2. **Language** — defaults to Russian if a backlog already exists, otherwise to the system locale.
+   - **Claude Code — the plugin (recommended).** In Claude Code run:
+
+     ```
+     /plugin marketplace add expatriate/p-backlog
+     /plugin install p-backlog@p-backlog
+     ```
+
+     `p-backlog-ru@p-backlog` installs the Russian skill instead. The plugin brings the skill and the Stop hook
+     and updates with `/plugin marketplace update p-backlog`; the CLI itself still comes from npm, and the plugin
+     needs p-backlog CLI 0.5.0 or newer.
+   - **Without the plugin, and for Codex and Cursor:** `backlog setup` links the skill and adds the Stop hook
+     for every agent it finds — see [Other agents](#other-agents).
+
+3. **Language** — defaults to Russian if a backlog already exists, otherwise to the system locale.
    Change it any time:
 
    ```bash
    backlog config language en   # or ru
    ```
 
-3. **First project and task** — open Claude Code in your repository and ask it to log something to the
+4. **First project and task** — open Claude Code in your repository and ask it to log something to the
    backlog, or create a task yourself:
 
    ```bash
@@ -72,17 +83,36 @@ It consists of the `backlog` CLI, the `backlog` skill and a Stop hook for Claude
 
    `backlog new` creates the project for the current repository itself if it doesn't exist yet.
 
-4. **Web app** — already running at `http://localhost:4317`; check with:
+5. **Web app** — `backlog service install` runs it at `http://localhost:4317` and starts it on login; check with:
 
    ```bash
    backlog service status
    ```
 
-5. **The Stop hook and alerts** — after each of the agent's turns in a repository, the Stop hook checks
+6. **The Stop hook and alerts** — after each of the agent's turns in a repository, the Stop hook checks
    whether the code behind that project's open tasks changed, and if so asks the agent to re-check them.
    It also surfaces alerts — signals about the backlog's health (growing debt, stuck tasks, stale
    low-priority tasks, and so on); `backlog stats` shows the same summary.
 
+## Other agents
+
+`backlog setup` finds the agents installed on this machine and connects each of them; `--agent claude|codex|cursor`
+limits it to one:
+
+| Agent | Found by | Skill | Stop hook |
+|---|---|---|---|
+| Claude Code | always | `~/.claude/skills/backlog` | `~/.claude/settings.json` |
+| Codex CLI | `$CODEX_HOME` or `~/.codex` | `~/.agents/skills/backlog` | `<codex home>/hooks.json` |
+| Cursor | `~/.cursor` | `~/.cursor/skills/backlog` | `~/.cursor/hooks.json` |
+
+The skill is a link to the package's skill in the configured language; `backlog config language` switches it for
+every agent where `setup` installed it. Other hooks in those files stay as they are, and running `setup` again adds nothing twice. Codex asks
+you to review and approve the new hook once: open `/hooks` in Codex. In Cursor the re-check request arrives as a
+follow-up message. Token and cost statistics cover Claude Code only.
+
+If the Claude Code plugin is enabled, `setup` leaves Claude Code alone; `backlog setup --remove-manual` removes the
+skill links and Stop hooks that `setup` installed earlier (for all agents, or for `--agent`).
+
 ## Where tasks live
 
 The backlog directory is `~/backlog`, or the path from the `BACKLOG_DIR` variable. Inside it, one
@@ -115,9 +145,10 @@ If there's no project yet, `backlog new` creates it.
 | `backlog prune [--project id \| --all-projects] [--apply]` | Low-priority tasks older than 30 days; `--apply` cancels them |
 | `backlog stats [--project id \| --all-projects] [--json]` | Statistics summary and alerts |
 | `backlog project list \| status <id> active\|inactive \| delete <id> --confirm <id>` | Project activity and deleting a project with its tasks |
-| `backlog hook stop` | The Stop hook for Claude Code: asks the agent to re-check tasks whose code changed |
+| `backlog hook stop [--agent claude\|codex\|cursor]` | The Stop hook of Claude Code, Codex, or Cursor: asks the agent to re-check tasks whose code changed |
 | `backlog config language [ru\|en]` | With no value, prints the current backlog language; with a value, changes it |
-| `backlog setup [--service]` | Install the skill and the Stop hook; with `--service`, also the autostart service |
+| `backlog setup [--agent claude\|codex\|cursor] [--service]` | Skill and Stop hook for the agents found — Claude Code, Codex, Cursor (see [Other agents](#other-agents)); `--service` also the autostart service |
+| `backlog setup --remove-manual [--agent claude\|codex\|cursor]` | Removes the skill links and Stop hooks that `setup` installed |
 | `backlog serve [--port N]` | Runs the web server in the current process, on `PORT` or 4317 by default |
 | `backlog service install \| uninstall \| status` | Autostarts the web server at login: launchd on macOS, systemd --user on Linux, a Startup-folder script on Windows; `status` shows whether it is installed and responding |
 
@@ -229,30 +260,14 @@ service stores the path to the Node binary it was installed with.
 ## Uninstalling
 
 ```bash
+backlog setup --remove-manual
 backlog service uninstall
 npm uninstall -g p-backlog
 ```
 
-Run `backlog service uninstall` before removing the package — otherwise launchd's `KeepAlive` (or systemd's
-`Restart=on-failure`) keeps relaunching a `cli.js` that no longer exists. Then remove the skill link and
-the Stop hook by hand:
-
-```bash
-rm ~/.claude/skills/backlog   # or $CLAUDE_SKILLS_DIR / $CLAUDE_CONFIG_DIR/skills, if set
-```
-
-and delete the `Stop` hook entry from `~/.claude/settings.json` (or `$CLAUDE_SETTINGS_PATH`). On macOS/Linux
-it is
-
-```json
-{ "type": "command", "command": "command -v backlog >/dev/null && backlog hook stop || true" }
-```
-
-and on Windows
-
-```json
-{ "type": "command", "shell": "powershell", "command": "if (Get-Command backlog.cmd -ErrorAction SilentlyContinue) { backlog.cmd hook stop }" }
-```
+`backlog setup --remove-manual` removes the skill links and Stop hooks from every agent (a plugin is removed with
+`/plugin uninstall`). Run `backlog service uninstall` before removing the package — otherwise launchd's `KeepAlive`
+(or systemd's `Restart=on-failure`) keeps relaunching a `cli.js` that no longer exists.
 
 On Windows, the Startup-folder script does not restart a crashed server the way launchd `KeepAlive` or
 systemd `Restart=on-failure` do — after a crash, run `backlog service install` again or start it with
@@ -265,6 +280,7 @@ npm install
 npm run build
 npm link                # global backlog command
 npm run install-skill   # ~/.claude/skills/backlog → skill/backlog and the Stop hook in ~/.claude/settings.json
+npm run plugins         # after changing the skill or the version: regenerate plugins/
 ```
 
 ```bash

package/README.ru.md

@@ -45,24 +45,35 @@
 
 ## Как начать
 
-1. **Установка** (нужен Node.js 22.13 или новее):
+1. **Установка CLI** (нужен Node.js 22.13 или новее):
 
    ```bash
    npm i -g p-backlog
-   backlog setup --service
    ```
 
-   `npm i -g p-backlog` ставит CLI глобально; `backlog setup --service` ставит скилл и хук Stop для Claude
-   Code и запускает веб как службу автозапуска.
+2. **Подключите агента.**
 
-2. **Язык** — по умолчанию русский, если беклог уже есть, иначе язык берётся из локали системы. Сменить
+   - **Claude Code — плагин (рекомендуется).** В Claude Code выполните:
+
+     ```
+     /plugin marketplace add expatriate/p-backlog
+     /plugin install p-backlog-ru@p-backlog
+     ```
+
+     `p-backlog@p-backlog` ставит английский скилл. Плагин приносит скилл и хук Stop и обновляется командой
+     `/plugin marketplace update p-backlog`; сам CLI по-прежнему ставится из npm, и для плагина нужен CLI p-backlog
+     0.5.0 или новее.
+   - **Без плагина, а также для Codex и Cursor:** `backlog setup` ставит ссылку на скилл и хук Stop каждому
+     найденному агенту — см. [Другие агенты](#другие-агенты).
+
+3. **Язык** — по умолчанию русский, если беклог уже есть, иначе язык берётся из локали системы. Сменить
    можно в любой момент:
 
    ```bash
    backlog config language en   # или ru
    ```
 
-3. **Первый проект и первая задача** — откройте Claude Code в своём репозитории и попросите «запиши в
+4. **Первый проект и первая задача** — откройте Claude Code в своём репозитории и попросите «запиши в
    беклог …», либо создайте задачу сами:
 
    ```bash
@@ -71,17 +82,36 @@
 
    Проект для текущего репозитория `backlog new` создаст сам, если его ещё нет.
 
-4. **Веб-приложение** — уже работает на `http://localhost:4317`; проверить можно так:
+5. **Веб-приложение** — `backlog service install` запускает его на `http://localhost:4317` и при входе в систему;
+   проверить можно так:
 
    ```bash
    backlog service status
    ```
 
-5. **Хук Stop и тревоги** — после каждого ответа агента в репозитории хук Stop проверяет, не изменился ли
+6. **Хук Stop и тревоги** — после каждого ответа агента в репозитории хук Stop проверяет, не изменился ли
    код у открытых задач этого проекта, и просит агента перепроверить их, если да. Он же показывает
    тревоги — сигналы о состоянии беклога (растущий долг, зависшие задачи, старые задачи с низким
    приоритетом и т. п.); их сводку показывает и `backlog stats`.
 
+## Другие агенты
+
+`backlog setup` находит установленных агентов и подключает каждого; `--agent claude|codex|cursor` сужает до одного:
+
+| Агент | Как находится | Скилл | Хук Stop |
+|---|---|---|---|
+| Claude Code | всегда | `~/.claude/skills/backlog` | `~/.claude/settings.json` |
+| Codex CLI | `$CODEX_HOME` или `~/.codex` | `~/.agents/skills/backlog` | `<каталог codex>/hooks.json` |
+| Cursor | `~/.cursor` | `~/.cursor/skills/backlog` | `~/.cursor/hooks.json` |
+
+Скилл — ссылка на скилл пакета на выбранном языке; `backlog config language` переставляет её у всех
+агентов, которым её поставил `setup`. Чужие хуки в этих файлах остаются на месте, повторный `setup` ничего
+не дублирует. Codex один раз просит одобрить новый хук: откройте `/hooks` в Codex. В Cursor просьба перепроверить
+задачи приходит следующим сообщением. Статистика токенов и расходов считает только Claude Code.
+
+Если включён плагин для Claude Code, `setup` Claude Code не трогает; `backlog setup --remove-manual` снимает ссылки на
+скилл и хуки Stop, которые `setup` ставил раньше (у всех агентов или у `--agent`).
+
 ## Где лежат задачи
 
 Каталог беклога — `~/backlog` или путь из переменной `BACKLOG_DIR`. Внутри — по каталогу на проект:
@@ -113,9 +143,10 @@
 | `backlog prune [--project id \| --all-projects] [--apply]` | Задачи с низким приоритетом старше 30 дней; `--apply` отменяет их |
 | `backlog stats [--project id \| --all-projects] [--json]` | Сводка статистики и тревоги |
 | `backlog project list \| status <id> active\|inactive \| delete <id> --confirm <id>` | Активность проектов и удаление проекта вместе с задачами |
-| `backlog hook stop` | Хук Stop для Claude Code: просит агента перепроверить задачи, чей код изменился |
+| `backlog hook stop [--agent claude\|codex\|cursor]` | Хук Stop для Claude Code, Codex или Cursor: просит агента перепроверить задачи, чей код изменился |
 | `backlog config language [ru\|en]` | Без значения — печатает текущий язык беклога; со значением — меняет его |
-| `backlog setup [--service]` | Поставить скилл и Stop-хук; с `--service` — ещё и службу автозапуска |
+| `backlog setup [--agent claude\|codex\|cursor] [--service]` | Скилл и Stop-хук найденным агентам — Claude Code, Codex, Cursor (см. [Другие агенты](#другие-агенты)); с `--service` — ещё и служба автозапуска |
+| `backlog setup --remove-manual [--agent claude\|codex\|cursor]` | Снимает ссылки на скилл и хуки Stop, которые поставил `setup` |
 | `backlog serve [--port N]` | Запускает веб-сервер в текущем процессе, порт — из `PORT`, иначе 4317 |
 | `backlog service install \| uninstall \| status` | Автозапуск веб-сервера при входе: launchd на macOS, systemd --user на Linux, скрипт в папке «Автозагрузка» на Windows; `status` — установлена ли служба и отвечает ли сервер |
 
@@ -223,30 +254,14 @@ backlog service install
 ## Удаление
 
 ```bash
+backlog setup --remove-manual
 backlog service uninstall
 npm uninstall -g p-backlog
 ```
 
-Перед удалением пакета выполните `backlog service uninstall` — иначе `KeepAlive` у launchd (или
-`Restart=on-failure` у systemd) продолжит перезапускать несуществующий `cli.js`. Затем вручную уберите
-ссылку на скилл и хук Stop:
-
-```bash
-rm ~/.claude/skills/backlog   # или $CLAUDE_SKILLS_DIR / $CLAUDE_CONFIG_DIR/skills, если заданы
-```
-
-и удалите запись хука `Stop` из `~/.claude/settings.json` (или `$CLAUDE_SETTINGS_PATH`). На macOS/Linux
-это
-
-```json
-{ "type": "command", "command": "command -v backlog >/dev/null && backlog hook stop || true" }
-```
-
-а на Windows
-
-```json
-{ "type": "command", "shell": "powershell", "command": "if (Get-Command backlog.cmd -ErrorAction SilentlyContinue) { backlog.cmd hook stop }" }
-```
+`backlog setup --remove-manual` снимает ссылки на скилл и хуки Stop у всех агентов (плагин удаляется через
+`/plugin uninstall`). Перед удалением пакета выполните `backlog service uninstall` — иначе `KeepAlive` у launchd
+(или `Restart=on-failure` у systemd) продолжит перезапускать несуществующий `cli.js`.
 
 На Windows скрипт в папке «Автозагрузка» не перезапускает сервер после падения — в отличие от `KeepAlive`
 у launchd или `Restart=on-failure` у systemd; после сбоя запустите `backlog service install` заново или
@@ -259,6 +274,7 @@ npm install
 npm run build
 npm link            # глобальная команда backlog
 npm run install-skill   # ~/.claude/skills/backlog → skill/backlog и хук Stop в ~/.claude/settings.json
+npm run plugins         # после правки скилла или версии: пересобрать plugins/
 ```
 
 ```bash