---
name: release-source-capture
description: Watch trusted GitHub release and RSS/Atom sources, dedupe them with a state file, and emit normalized JSON events for a Hermes/Codex content brief.
---

# Release Source Capture

Use this skill when a user wants a low-cost watcher for Codex, Hermes, OpenAI, or other trusted release sources, with the output routed into article briefs, course updates, or skill maintenance tasks.

Keep this step deterministic. The script does not call an LLM, draft copy, create issues, send Discord messages, or publish anything. It captures source events, writes a local state file for dedupe, and prints normalized JSON for the next agent step.

## Workflow

1. Create a trusted source registry JSON file.
2. Include only official or primary sources: GitHub releases, official RSS/Atom feeds, docs changelogs, and vendor blogs.
3. Install the skill and `cd` into the installed directory.
4. Run `node scripts/release-source-capture.mjs capture --registry ~/release-sources.json --state ~/.release-source-capture/state.json --dry-run`.
5. Inspect the normalized JSON events.
6. Remove `--dry-run` only after the registry is trusted.
7. Run once without `--dry-run` to seed the state file before alerting.
8. Run the script hourly from cron or a Hermes scheduled job.
9. Pass non-empty events into a second Hermes/Codex prompt that verifies primary sources and prepares a research brief for a possible 2000-word implementation article.
10. Require human approval before publishing or updating live course content.

## Registry shape

```bash
cat > ~/release-sources.json <<'JSON'
[
  {
    "id": "hermes-agent-releases",
    "type": "github-releases",
    "url": "https://api.github.com/repos/NousResearch/hermes-agent/releases",
    "product": "Hermes Agent",
    "importance": "high"
  },
  {
    "id": "openai-news",
    "type": "rss",
    "url": "https://openai.com/news/rss.xml",
    "product": "OpenAI",
    "importance": "medium"
  }
]
JSON
```

## Behavior

- Supports source types `github-releases` and `rss`.
- Uses simple RSS/Atom parsing in v1; prefer official feeds with canonical links.
- Fetches each source URL with Node's built-in `fetch`.
- Requires Node 18+; Node 20+ is recommended for server installs.
- Converts each item into normalized JSON.
- Computes a SHA-256 hash from the source id, item URL, title, publication time, and summary.
- Uses a state file to dedupe events by source id and hash.
- Prints only new events.
- Writes state unless `--dry-run` is set.
- Fails closed on unsupported source types instead of guessing a parser.
- Returns exit code `2` when any source fails, even if other sources produced events. Treat partial failures as something to inspect.
- Does not publish, draft final copy, create CMS entries, or mutate remote systems.

## Normalized JSON

```json
{
  "sourceId": "hermes-agent-releases",
  "sourceType": "github-releases",
  "product": "Hermes Agent",
  "importance": "high",
  "title": "v0.9.4",
  "url": "https://github.com/NousResearch/hermes-agent/releases/tag/v0.9.4",
  "publishedAt": "2026-05-13T14:00:00.000Z",
  "summary": "Release body or feed summary excerpt",
  "hash": "sha256:..."
}
```

## Commands

Dry run from the installed skill directory:

```bash
cd ~/.codex/skills/content/release-source-capture
node scripts/release-source-capture.mjs capture \
  --registry ~/release-sources.json \
  --state ~/.release-source-capture/state.json \
  --dry-run
```

Before writing state, check that the URLs are canonical, the summaries are useful enough for triage, and repeated dry runs do not produce surprise duplicates.

Write state once to seed current items before alerting:

```bash
node scripts/release-source-capture.mjs capture \
  --registry ~/release-sources.json \
  --state ~/.release-source-capture/state.json
```

Cron:

```bash
mkdir -p ~/logs
```

```cron
7 * * * * cd $HOME/.codex/skills/content/release-source-capture && /usr/bin/env node scripts/release-source-capture.mjs capture --registry $HOME/release-sources.json --state $HOME/.release-source-capture/state.json >> $HOME/logs/release-source-capture.log 2>&1
```

## Writing brief handoff

When stdout contains new events, ask Hermes or Codex:

```text
Research these trusted release events and prepare a sourced research brief for a possible implementation article.
Start with primary sources: release notes, docs, changelog entries, commits, issues, and official announcements.
For each event, explain what changed, who needs to care, compatibility or migration risk, local verification steps, tutorial angle, and source links.
Do not draft final copy, update course content, or publish until a human approves the angle.
```

## Pitfalls

- Do not add noisy scraped social feeds to the registry in v1.
- Do not auto-publish from this skill.
- Do not call an LLM from the hourly detector.
- Do not trust generated summaries, RSS excerpts, or copied changelog blurbs without checking the canonical release page or docs.
- Do not treat every release as content. Low-impact events should be logged and ignored.
- Keep the state file backed up if the watcher is part of a production content workflow.
- Watch GitHub API rate limits if you monitor many repositories. Unauthenticated API requests are limited; reduce the source count or add token support before scaling.