---
name: release-watch
description: Use when an agent needs to monitor watched software releases, classify version updates, avoid duplicate release notifications, or decide whether a watched tool should be upgraded.
---

# Release Watch

## Overview

Use this skill when the user asks whether watched software, frameworks, tools, or repositories have new versions and whether those versions are worth upgrading.

Keep this workflow separate from public trend discovery. GitHub releases are upgrade-monitoring signals, not Trend Radar inputs.

## Workflow Selection

- For watched software version updates, use this skill.
- For public ecosystem trend cards, use `public-trend-radar`.
- For ordinary subscribed RSS daily news, use `rss-ai-digest`.
- For source quality and registry maintenance, use `rss-source-curator`.
- For deep research synthesis from evidence, use `subscription-research-agent`.

## Runtime Command

Examples use `subscription-research` as a compatibility command. Before running commands, resolve the runtime command:

- Use `DIGESTPILOT_RUNTIME_CMD` when the environment provides a custom runtime command.
- Use `digestpilot-runtime` when it is available on `PATH`.
- Use `subscription-research` when only the legacy compatibility command is available on `PATH`.
- From a repository checkout without a linked command, replace `subscription-research` with `node packages/research-cli/dist/src/cli.js`.
- Run `node scripts/doctor.mjs` from the repository root to diagnose local runtime setup.
- If no runtime command is available but this repository or plugin package includes runtime source, run `node scripts/bootstrap-runtime.mjs`, then retry the command.

## Core Command

Prepare a watchlist:

```json
{
  "repos": [
    {
      "id": "vercel/ai",
      "importance": "high",
      "current_version": "v5.1.0",
      "used_capabilities": ["streaming", "tool-calling"]
    }
  ]
}
```

Fetch live GitHub releases and render upgrade cards:

```bash
subscription-research release watch \
  --watchlist release-watchlist.json \
  --state release-seen.json \
  --mark-seen \
  --format markdown \
  --output release-watch.md
```

By default, the runtime fetches recent GitHub releases for each watched repository. Set `GITHUB_TOKEN` when higher GitHub API limits are needed, or pass `--github-token-env NAME` to read a different token variable.

For offline tests or exported data, pass prepared GitHub release JSON:

```bash
subscription-research release watch \
  --watchlist release-watchlist.json \
  --github-releases github-releases.json \
  --state release-seen.json \
  --format markdown
```

Prepared release JSON uses this shape:

```json
{
  "repositories": [
    {
      "repo": "vercel/ai",
      "releases": [
        {
          "tag_name": "v5.1.1",
          "name": "v5.1.1",
          "html_url": "https://github.com/vercel/ai/releases/tag/v5.1.1",
          "published_at": "2026-06-12T00:00:00Z",
          "body": "Release notes..."
        }
      ]
    }
  ]
}
```

## Output Guidance

Release Watch output should be an upgrade queue, not a trend list.

Use these priorities:

- `upgrade-now`: security fixes or urgent fixes that affect watched capabilities.
- `review`: breaking changes, major updates, or updates touching watched capabilities.
- `watch`: prereleases or unclear impact.
- `ignore`: maintenance-only or documentation-only releases.

Markdown output should focus on actionable releases. JSON preserves all cards, including ignored releases, for automation.

When `current_version` is present in the watchlist, Release Watch adds `version_delta`, `upgrade_action`, and current-version context. Use this to distinguish patch upgrades from minor upgrades and major migration reviews.

## Boundaries

Do not modify user dependencies, create upgrade PRs, or publish notifications automatically. Produce reviewable upgrade cards and let the user decide the next action.