promo-scout

name	promo-scout
description	Verify-first promotion intelligence for ANY repo or org. Pulls live GitHub state, runs sshx multi-perspective consensus over it, and returns an evidence-backed board of what is genuinely promotable, how items connect, and what is unverifiable. Use when an agent or operator asks "what's worth promoting / what connects / what's real" for a target repo or org.
version	2.0
license	MIT
metadata	{"category":"mixed","output-type":"text","runtime":["python"],"tool-list":["gh","sshx"],"runtime-env-var":["GH_TOKEN"],"tag":["repo-research","promotion","consensus"]}

promo-scout

Generic, verify-first promotion intelligence. It is the opposite of a hype scraper: nothing reaches the board unless live GitHub state backs it, and the judgment is made by sshx consensus (isolated perspectives + truth table), not by one model's say-so.

Requires: gh authenticated with your existing GitHub auth, either via gh auth login or GH_TOKEN, and the sshx skill available to the caller.

When to use

An agent or operator wants, for a target repo/org: what is genuinely promotable right now, how the pieces connect across repos, and what tempting claims are NOT verifiable.

Step 0 — confirm explicit scope WITH THE USER

There is no broad account-wide default. Require the user to name:

• a whole org (public repos only by default),
• one or more specific repos (owner/repo), or
• a mixed list. Also confirm REPO_LIMIT for org targets (default 12 most-recently-active public repos). Private repo collection requires explicit opt-in with --include-private; do not use that flag unless the user has confirmed it.

Step 1 — fetch live state (deterministic; runs from anywhere)

Run the bundled fetcher with an explicit target:

python3 scripts/promo_scout_fetch.py <org | owner/repo> [more...]   # public/default scope
python3 scripts/promo_scout_fetch.py --include-private <org | owner/repo> [more...]   # only after explicit confirmation

It writes /tmp/promo_scout_bundle.json: per-repo README head, recent commits, releases, open PRs, recent issues. This is the ONLY evidence the consensus step may use.

Step 2 — run real sshx consensus over the bundle

Invoke the sshx skill (worker-delegated, isolated perspectives, codex-cli workers) with this decision, feeding the bundle as the fixed input:

Given ONLY this live GitHub state bundle, produce three lists. (1) Promotable: items genuinely worth promoting now — each MUST cite concrete bundle evidence (a release tag, a dated commit, a README capability). (2) Connections: cross-repo links where one repo's work composes with another's, each backed by a real signal in the bundle (shared PRs, dependency mentions, complementary capability). (3) Dropped: tempting claims that the bundle does NOT support, with the missing evidence. No overclaim; if evidence is absent, it goes to Dropped, not Promotable.

Use distinct sshx thinking-perspectives, e.g.: a promotability lens, a cross-repo connection lens, and a skeptic / overclaim-hunter lens. Require convergence per the sshx truth table; honor abstain when workers can't establish a claim.

Step 3 — emit the board

Write the agreed result as a board (markdown + optional JSON): ## Promotable now, ## Connections, ## Dropped (unverifiable). Each promotable/connection item carries its bundle evidence inline. The Dropped list is mandatory — it is the credibility of the board.

Guardrails

• Evidence or it doesn't ship. Live bundle is the only source; no outside memory, no inflated numbers.
• The connections/synthesis must EMERGE from the consensus over live state — do not inject a pre-written narrative.
• Honest by construction: unverifiable → Dropped; when consensus can't be reached, report abstain, not a guess.