@buildinternet/releases-skills 0.18.0 → 0.19.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/releases-skills",
-  "version": "0.18.0",
+  "version": "0.19.1",
   "description": "Agent skills bundled with the Releases CLI. Markdown playbooks for changelog ingest, discovery, and analysis.",
   "type": "module",
   "license": "MIT",

package/skills/analyzing-releases/SKILL.md

@@ -18,7 +18,7 @@ Turn changelog data into competitive intelligence by analyzing release patterns
 | Operation | CLI | Typed tool |
 |-----------|-----|------------|
 | Check existing sources | `releases list --query <company> --json` | `list_sources` with query param |
-| Fetch releases | `releases admin source fetch <slug> --max 50` | `fetch_source` with identifier (ID or slug) |
+| Fetch releases | `releases admin source fetch <slug> --max 50` | `manage_source` action "fetch" with identifier (ID or slug) |
 | Get latest releases | `releases tail <slug> --json` | `get_latest_releases` with source/org and limit |
 | Search releases | `releases search <query> --json` | `search_releases` with query |
 | Summarize | `releases summary <slug> --json` | (not available as typed tool) |

package/skills/finding-changelogs/SKILL.md

@@ -154,7 +154,7 @@ If evaluation returns `confidence: low` or `recommendedMethod: scrape`, you may
 
 When evaluating multiple changelog sources for an org, identify which one is the company's **primary changelog** — the top-level, platform-wide changelog that covers the product as a whole. This is typically a website changelog page (e.g., `example.com/changelog`) rather than individual GitHub repos or product-specific pages.
 
-After adding sources, mark the primary one. CLI: `releases admin source edit <identifier> --primary`. Typed tool: `edit_source` with identifier (ID or slug) and is_primary: true. Only one source per org should be primary. If there's no clear top-level changelog, don't mark any as primary.
+After adding sources, mark the primary one. CLI: `releases admin source edit <identifier> --primary`. Typed tool: `manage_source` action "edit" with identifier (ID or slug) and is_primary: true. Only one source per org should be primary. If there's no clear top-level changelog, don't mark any as primary.
 
 ## When to Use Crawl
 
@@ -229,7 +229,7 @@ When in doubt, add and pause rather than skip entirely. A focused index with 3 c
 
 When you find a source that matches the staleness or ecosystem criteria above, **still add it to the database** but immediately set it to `--priority paused`. This prevents future onboard runs from rediscovering the same source and re-evaluating it. The source record serves as documentation that "we know about this, and we decided not to track it."
 
-Add the source and immediately set it to paused priority. CLI: `releases admin source add <name> --url <url> --org <org> --type github` then `releases admin source edit <identifier> --priority paused`. Typed tools: `add_source` then `edit_source` with identifier (ID or slug) and fetch_priority: "paused".
+Add the source and immediately set it to paused priority. CLI: `releases admin source add <name> --url <url> --org <org> --type github` then `releases admin source edit <identifier> --priority paused`. Typed tools: `manage_source` action "add" then `manage_source` action "edit" with identifier (ID or slug) and fetch_priority: "paused".
 
 Do the same for ecosystem plugins, deprecated products, and low-value repos. The goal is to capture the discovery decision, not to lose the knowledge.
 
@@ -237,6 +237,6 @@ Do the same for ecosystem plugins, deprecated products, and low-value repos. The
 
 Organizations can have multiple distinct products (e.g., Vercel → Next.js, Turborepo, v0). When discovering sources for an org, consider whether they belong to separate products.
 
-Use product and org management operations to organize what you find. CLI: `releases admin product add`, `releases admin org tag add`, `releases categories`. Typed tools: `manage_product`, `manage_org`, `list_categories`. The full list of valid categories is provided in your system prompt.
+Use product and org management operations to organize what you find. CLI: `releases admin product add`, `releases admin org tag add`, `releases categories`. Typed tools: `manage_product`, `manage_org` — each carries the valid category list in its description (also provided in your system prompt).
 
 Don't force product groupings when sources are ambiguous — leave them at the org level and note suggestions in the state file.

package/skills/managing-sources/SKILL.md

@@ -14,10 +14,10 @@ Operations can be performed via CLI commands or typed MCP/agent tools. Use which
 | Operation | CLI | Typed tool |
 |-----------|-----|------------|
 | List sources | `releases list [slug] --json [--org <org>] [--query <text>] [--has-feed] [--category <c>] [--compact] [--limit <n>] [--page <n>]` | `list_sources` with query, organization, category, has_feed params |
-| Add source | `releases admin source add <name> --url <url> [--type <type>] [--org <org>] [--feed-url <url>]` | `add_source` with name, url, type, organization, feed_url params |
-| Edit source | `releases admin source edit <identifier> [--primary] [--priority <p>]` | `edit_source` with identifier (ID or slug), is_primary, fetch_priority params |
-| Remove source | `releases admin source remove <slug> [--ignore --reason <reason>]` | `remove_source` with identifier (ID or slug) param |
-| Fetch releases | `releases admin source fetch <slug> [--dry-run] [--max <n>]` | `fetch_source` with identifier (ID or slug) param |
+| Add source | `releases admin source add <name> --url <url> [--type <type>] [--org <org>] [--feed-url <url>] [--primary]` | `manage_source` action "add" with name, url, type, organization, feed_url, **is_primary** (type auto-detected if omitted; only pass is_primary=true when the source is the org's primary changelog — see "Primary Sources") |
+| Edit source | `releases admin source edit <identifier> [--primary] [--priority <p>]` | `manage_source` action "edit" with identifier, is_primary, fetch_priority, name, url, type (use only when changing an already-added source; prefer setting flags on "add") |
+| Remove source | `releases admin source remove <slug> [--ignore --reason <reason>]` | `manage_source` action "remove" with identifier |
+| Fetch releases | `releases admin source fetch <slug> [--dry-run] [--max <n>]` | `manage_source` action "fetch" with identifier |
 | Get latest releases | `releases tail [slug] --json [--org <org>]` | `get_latest_releases` with source, organization, limit params |
 | Search releases | `releases search <query> --json` | `search_releases` with query, limit params |
 | Evaluate URL | `releases admin discovery evaluate <url> --json` | `evaluate_url` with url param |
@@ -29,9 +29,10 @@ Operations can be performed via CLI commands or typed MCP/agent tools. Use which
 | Add product | `releases admin product add <name> --org <org> [--category <c>] [--tags <t>]` | `manage_product` action "add" with name, organization, category, tags |
 | Ignore URL | `releases admin policy ignore add --org <org> <url>` | `exclude_url` action "ignore" with url, organization |
 | Block URL | `releases admin policy block add <url>` | `exclude_url` action "block" with url |
-| List categories | `releases categories --json` | `list_categories` |
-| Get playbook | `releases admin content playbook <org>` | `get_playbook` with organization param |
-| Update playbook notes | `releases admin content playbook <org> --notes "..."` | `update_playbook_notes` with organization, notes params |
+| Get playbook | `releases admin playbook <org>` | `manage_playbook` action "get" with organization |
+| Update playbook notes | `releases admin playbook <org> --notes "..."` | `manage_playbook` action "update_notes" with organization, notes |
+
+Valid categories (pass to `manage_org`/`manage_product`): see the enum in those tool descriptions or your system prompt. `list_categories` (now retired) has been folded into the two tool descriptions.
 
 ## Listing Sources
 
@@ -48,6 +49,8 @@ Use `--json` (CLI) for structured output. Typed tools always return JSON.
 
 Required: **name** and **url**. Optional: **type** (github, scrape, feed, agent — auto-detected from URL if omitted), **organization** (org ID or slug to associate with), **feed_url** (direct feed URL if known).
 
+On slug collision the API auto-suffixes (`changelog` → `changelog-2`, `-3`, …) and the created row in the response tells you the resolved slug — no rename-and-retry needed.
+
 ### Naming sources and products
 
 **Don't prefix names with the org name.** The org is already shown as context on every page — repeating it in each child source produces noise like "Datadog › Datadog dd-trace-py". Pick the bare, recognizable name instead.
@@ -72,7 +75,7 @@ Adding or editing an org, product, or source triggers an entity embedding into t
 
 ## Removing Sources
 
-When removing discovery results, also ignore the URL to prevent re-discovery. In CLI: `releases admin source remove <slug> --ignore --reason "..."`. With typed tools: call `remove_source` then `exclude_url` with action "ignore".
+When removing discovery results, also ignore the URL to prevent re-discovery. In CLI: `releases admin source remove <slug> --ignore --reason "..."`. With typed tools: call `manage_source` action "remove" then `exclude_url` action "ignore".
 
 ## Ignored URLs (org-scoped)
 
@@ -87,25 +90,41 @@ For spam domains and known-bad URLs that should never be added for any org. Use
 After adding a source, validate it:
 
 1. **Add the source** — provide name and URL
-2. **Fetch** — trigger a fetch (CLI: `--dry-run` for preview, then real fetch; typed tools: `fetch_source`)
+2. **Fetch** — trigger a fetch (CLI: `--dry-run` for preview, then real fetch; typed tools: `manage_source` action "fetch")
 3. **Check results** — get latest releases and verify they have titles, dates, content
 4. **If bad:** remove the source and ignore the URL
 5. **If good:** the source is ready for production fetches
 
 ## Primary Sources
 
-An org can have one source marked as its **primary changelog** — the main, company-wide changelog. Mark it with `--primary` (CLI) or `is_primary: true` (typed tool).
+An org can have one source marked as its **primary changelog** — the main, company-wide changelog.
+
+`is_primary` is conditional, not default. Only set it when the source you are adding is clearly the org's primary changelog:
+
+- Onboarding a new org with a single top-level changelog (e.g. `example.com/changelog`) — set `is_primary=true` on the add.
+- Adding a supplementary or secondary source to an existing org (an engineering blog, a per-product changelog, an RSS feed alongside an already-primary page) — **do not** set `is_primary`. Leave the existing primary alone.
+- The task prompt doesn't mention "primary" or similar — default to not setting it.
 
-When onboarding an org, if you find a single top-level changelog alongside product-specific or GitHub sources, mark the top-level one as primary.
+When it does apply, set it on the `add` call in one step, not via a follow-up edit:
+
+```
+manage_source(action="add", name="Changelog", url="https://example.com/changelog", organization="example-corp", is_primary=true)
+```
+
+The same applies on CLI: pass `--primary` to `releases admin source add`, not a follow-up `source edit`.
+
+Use `manage_source(action="edit", is_primary=true)` only when promoting a source you added in a prior session — never in the same flow as the add.
 
 ## Playbooks
 
-Each org has a **playbook** — a README that tells any agent how to efficiently work with that org's changelog sources. The playbook has two layers:
+**A playbook is a per-org skill for fetching that org's releases.** Same mental model as the global skills in this corpus, scoped to one organization. Agents load the playbook into context alongside global skills whenever they fetch from this org — the playbook overrides general rules with the org's specific behavior (naming conventions, what counts as a release, cross-source dedup, rollup cadence).
+
+Each playbook has two layers:
 
 - **Header** — auto-generated from source metadata. Shows source types, URLs, priorities, parseInstructions, and product groupings. Regenerates automatically on every source mutation. You never edit this directly.
-- **Agent notes** — free-form markdown that you fully control. This is the most important part of the playbook. Write it like a README for a teammate who needs to fetch releases from this org without asking questions.
+- **Agent notes** — free-form markdown that you fully control. This is the most important part of the playbook. Write it like a skill an agent will follow — imperative, action-oriented, concise — not like human documentation.
 
-**Always read the playbook before fetching or working with an org's sources.** Typed tool: `get_playbook` with organization param. CLI: `releases admin content playbook <org>`. If no playbook exists yet, one will be auto-generated on the next source mutation (add/edit/remove).
+**Always read the playbook before fetching or working with an org's sources.** Typed tool: `manage_playbook` action "get" with organization param. CLI: `releases admin playbook <org>`. If no playbook exists yet, one will be auto-generated on the next source mutation (add/edit/remove).
 
 ### Writing good agent notes
 
@@ -151,9 +170,9 @@ Use the verified approach for high-value orgs, when onboarding new orgs with scr
 
 Write notes during onboarding after you've fetched and validated sources. Update them when you discover new quirks or when source behavior changes. If notes are empty or stale, write them before doing fetch work — future agents (including yourself in later sessions) will benefit.
 
-**Updating notes:** Use `update_playbook_notes` with the complete notes content — it replaces the entire notes section. You can rewrite, reorganize, or clear notes at any time.
+**Updating notes:** Use `manage_playbook` action "update_notes" with the complete notes content — it replaces the entire notes section. You can rewrite, reorganize, or clear notes at any time.
 
-**Changing source configuration:** The header reflects current source metadata. To change things like `parseInstructions`, `fetchPriority`, or `crawlEnabled`, use `edit_source` with metadata — the header updates automatically.
+**Changing source configuration:** The header reflects current source metadata. To change things like `parseInstructions`, `fetchPriority`, or `crawlEnabled`, use `manage_source` action "edit" with metadata — the header updates automatically.
 
 **Product context:** Playbooks group sources by product when products are configured. Some sources (like an org's engineering blog) aren't tied to a specific product but may contain content relevant to any product under that org — the playbook calls these out as "Organization-Level Sources" with a note about which products they may cover.
 

package/skills/parsing-changelogs/SKILL.md

@@ -22,7 +22,7 @@ After fetching content, the pipeline parses it:
 
 ## Fetching
 
-Trigger a fetch for a source by ID or slug. CLI: `releases admin source fetch <slug> [--dry-run] [--max <n>]`. Typed tool: `fetch_source` with identifier (ID or slug) param.
+Trigger a fetch for a source by ID or slug. CLI: `releases admin source fetch <slug> [--dry-run] [--max <n>]`. Typed tool: `manage_source` action "fetch" with identifier (ID or slug) param.
 
 Key CLI flags (not available via typed tool — the typed tool always does a full server-side fetch):
 - `--dry-run` — parse but don't persist. Essential for validation.
@@ -72,8 +72,8 @@ Do NOT fetch release URLs in the parent agent — always delegate to a subagent
 **What to do based on the result:**
 
 If pages are richer than feed content (more text, images, videos, or code examples):
-1. Record the assessment and enable crawl mode. CLI: `releases admin source edit <identifier> --metadata '{"feedContentDepth":"summary-only","crawlEnabled":true}'`. Typed tool: `edit_source` with the same metadata. Subsequent fetches will follow links to per-release pages and extract full content in one pass.
-2. Re-fetch the source once to backfill. CLI: `releases admin source fetch <slug> --full`. Typed tool: `fetch_source`.
+1. Record the assessment and enable crawl mode. CLI: `releases admin source edit <identifier> --metadata '{"feedContentDepth":"summary-only","crawlEnabled":true}'`. Typed tool: `manage_source` action "edit" with the same metadata. Subsequent fetches will follow links to per-release pages and extract full content in one pass.
+2. Re-fetch the source once to backfill. CLI: `releases admin source fetch <slug> --full`. Typed tool: `manage_source` action "fetch".
 3. Verify results. CLI: `releases list <slug> --json` or `releases tail <slug>`. Typed tool: `get_latest_releases` — check content is richer after the re-fetch.
 
 If feed already provides full content with no meaningful additions on the page:
@@ -87,7 +87,7 @@ Once `feedContentDepth` is set, skip the sampling step on future encounters. Cra
 
 Engineering blogs and news pages mix product announcements with educational content, opinion pieces, and corporate news. They can be useful supplementary sources but require aggressive filtering via `parseInstructions` to avoid noise.
 
-**Before working with blog sources:** Check the org's playbook (`releases admin content playbook <org>`) for notes about how existing blog sources perform, what filtering works, and which products they cover.
+**Before working with blog sources:** Check the org's playbook (`releases admin playbook <org>`) for notes about how existing blog sources perform, what filtering works, and which products they cover.
 
 **When to add a blog source:**
 - The org's primary changelogs don't cover major product announcements (new models, new services)
@@ -160,7 +160,7 @@ Most releases are **features** — individual version bumps, single product anno
 
 **How to recognize rollup sources:**
 
-Before parsing, **always read the playbook** (CLI: `releases admin content playbook <org>`, typed tool: `get_playbook` with organization param). If a company publishes rollups as its primary cadence — quarterly, seasonal, "every few months" — the playbook notes should say so explicitly. Example notes:
+Before parsing, **always read the playbook** (CLI: `releases admin playbook <org>`, typed tool: `manage_playbook` action "get" with organization param). If a company publishes rollups as its primary cadence — quarterly, seasonal, "every few months" — the playbook notes should say so explicitly. Example notes:
 
 - "Brex publishes quarterly seasonal rollup pages at `/product-announcements/{fall,spring,summer,winter}-release-YYYY`. Treat each as `type: rollup`."
 - "Ramp's blog series `/blog/new-on-ramp-*-edition` and `/new-on-ramp-q*-*` are quarterly/monthly rollups. Classify as `type: rollup`; individual features within are not separately indexed."
@@ -174,7 +174,7 @@ When you encounter a new rollup source during discovery or fetch, update the pla
 
 When adding a new source, always validate before committing:
 
-1. **Fetch** — CLI: `releases admin source fetch <slug> --dry-run` then `releases admin source fetch <slug>`. Typed tool: `fetch_source` with identifier (ID or slug).
+1. **Fetch** — CLI: `releases admin source fetch <slug> --dry-run` then `releases admin source fetch <slug>`. Typed tool: `manage_source` action "fetch" with identifier (ID or slug).
 2. **Verify** — CLI: `releases tail <slug> --json` or `releases admin source fetch-log <slug>`. Typed tool: `get_latest_releases` with source identifier.
-3. **If poor results** — try a different URL or type. CLI: `releases admin source edit <identifier> --type feed`. Typed tool: `edit_source` with identifier.
-4. **If no usable releases** — remove the source. CLI: `releases admin source remove <slug> --ignore --reason "..."`. Typed tool: `remove_source` with identifier, then `exclude_url`.
+3. **If poor results** — try a different URL or type. CLI: `releases admin source edit <identifier> --type feed`. Typed tool: `manage_source` action "edit" with identifier.
+4. **If no usable releases** — remove the source. CLI: `releases admin source remove <slug> --ignore --reason "..."`. Typed tool: `manage_source` action "remove" with identifier, then `exclude_url`.

package/skills/seeding-playbooks/SKILL.md

@@ -7,6 +7,14 @@ description: Coordinate bulk playbook writing using parallel sub-agents — cove
 
 Coordinate bulk creation or enrichment of playbook agent notes across many orgs using parallel sub-agents.
 
+## What a playbook is
+
+**A playbook is a per-org skill for fetching that org's releases.** Same mental model as the global skills in this corpus (`parsing-changelogs`, `managing-sources`, etc.) — but scoped to one organization. It tells a future agent (managed or local) how to pull updates from _this_ org: extraction quirks, naming conventions, which sources are canonical, what to skip, where rollups hide.
+
+Global skills teach general patterns; per-source `parseInstructions` teach source-specific hints; the playbook is the org-level layer between them. When agents fetch any of an org's sources, they should load that org's playbook into context alongside the global skills — the playbook overrides general rules with specific org behavior.
+
+Write notes as instructions to an LLM, not as human documentation. Imperative voice ("Set version=null", "Parse `<h2>` as version boundaries"), concrete examples from real data, and only observations that change future fetch behavior.
+
 **Local-only**: This skill requires Claude Code's Agent tool to dispatch sub-agents. Managed agents (discovery worker, Haiku worker) cannot spawn sub-agents — that capability is behind a private beta and not yet available. When sub-agent support ships for managed agents, this skill can be adapted into a managed session mode.
 
 ## When to Use
@@ -24,7 +32,7 @@ bun -e "
 const orgs = JSON.parse(Bun.spawnSync(['bun', 'src/index.ts', 'admin', 'org', 'list', '--json'], { stderr: 'ignore' }).stdout.toString());
 const active = orgs.filter(o => o.sourceCount > 0).sort((a,b) => b.releaseCount - a.releaseCount);
 for (const org of active) {
-  const playbook = JSON.parse(Bun.spawnSync(['bun', 'src/index.ts', 'admin', 'content', 'playbook', org.slug, '--json'], { stderr: 'ignore' }).stdout.toString());
+  const playbook = JSON.parse(Bun.spawnSync(['bun', 'src/index.ts', 'admin', 'playbook', org.slug, '--json'], { stderr: 'ignore' }).stdout.toString());
   const status = playbook.notes?.length > 100 ? 'has notes (' + playbook.notes.length + ' chars)' : 'NEEDS PLAYBOOK';
   console.log(org.slug.padEnd(25) + ' sources=' + String(org.sourceCount).padStart(2) + '  ' + status);
 }
@@ -101,15 +109,16 @@ Products: {product list or "none"}
 **Coverage**: 2-3 sentences. Which sources are canonical, whether there are gaps.
 
 Save by running:
-bun src/index.ts admin content playbook {slug} --regenerate 2>/dev/null
-bun src/index.ts admin content playbook {slug} --notes "$(cat <<'NOTES'
+releases admin playbook {slug} --notes "$(cat <<'NOTES'
 YOUR NOTES HERE
 NOTES
 )" 2>/dev/null
 
-Verify with: bun src/index.ts admin content playbook {slug} 2>/dev/null | tail -20
+Verify with: releases admin playbook {slug} 2>/dev/null | tail -20
 ```
 
+The playbook header regenerates automatically after any source add/edit/remove, and the `--notes` PATCH seeds a fresh header on first write — no separate regenerate step needed.
+
 ### Verified prompt template
 
 ```
@@ -147,13 +156,12 @@ Every claim must cite observed data. If uncertain, say so explicitly.
 
 ## Step 4: Save
 
-bun src/index.ts admin content playbook {slug} --regenerate 2>/dev/null
-bun src/index.ts admin content playbook {slug} --notes "$(cat <<'NOTES'
+releases admin playbook {slug} --notes "$(cat <<'NOTES'
 YOUR NOTES HERE
 NOTES
 )" 2>/dev/null
 
-Verify with: bun src/index.ts admin content playbook {slug} 2>/dev/null | tail -20
+Verify with: releases admin playbook {slug} 2>/dev/null | tail -20
 ```
 
 ### Dispatch pattern
@@ -176,8 +184,7 @@ Sub-agents may be blocked from saving notes via Bash (heredoc permission issues)
 2. The parent agent (you) saves the notes manually:
 
 ```bash
-bun src/index.ts admin content playbook {slug} --regenerate 2>/dev/null
-bun src/index.ts admin content playbook {slug} --notes "$(cat <<'NOTES'
+releases admin playbook {slug} --notes "$(cat <<'NOTES'
 {paste notes from agent result}
 NOTES
 )" 2>/dev/null
@@ -193,7 +200,7 @@ After all agents complete, verify coverage in bulk:
 bun -e "
 const orgs = [{target slugs}];
 for (const org of orgs) {
-  const proc = Bun.spawnSync(['bun', 'src/index.ts', 'admin', 'content', 'playbook', org, '--json'], { stderr: 'ignore' });
+  const proc = Bun.spawnSync(['releases', 'admin', 'playbook', org, '--json'], { stderr: 'ignore' });
   try {
     const d = JSON.parse(proc.stdout.toString());
     const len = d.notes?.length ?? 0;