scout-peers

Find the public repos most comparable to this project, determine whether any one of them is uniformly superior (does everything this repo does, but better), and otherwise harvest their best ideas — adapting each one into this repo only after clearing its license and recording attribution.

This is a research-and-adapt loop, not a blind copy. The output is a ranked, license-checked, attributed list of borrowable ideas plus (on the user’s go-ahead) the implementations.

When this fires

  • User says /scout-peers, “are there other repos like this”, “scan similar projects”, “borrow ideas from comparable repos”, “competitive scan”, “what can we learn from peer projects”, “how do others solve this”.
  • After building something with an established category of prior art, when you want to sanity-check the design against the field.

Procedure

1. Characterize this repo

Read the local repo enough to write a tight one-paragraph “reference profile”: what it is, its structure (top-level dirs), its distinctive features, and its intended use. This profile is what every comparison is measured against, so be specific about the things that make this repo itself (its workflows, its data model, its niche) — not just generic category membership. Write it once; hand the same profile to every research agent so verdicts are comparable.

2. Find the peer set

Use WebSearch (2–4 queries from different angles — by category, by “awesome-X list”, by the repo’s distinctive feature) to assemble a candidate list. Pull in curated “awesome” lists too: they surface peers a direct search misses. Dedupe into a flat list of repo URLs, then bucket them:

  • Closest analogs — same shape and purpose. These get the deepest look.
  • Adjacent / larger — same category, different emphasis (e.g. a broad marketplace vs. a personal config). Mine for structural/tooling ideas.
  • Directories / lists — not configs themselves; mine for pointers to notable individual projects and for organization conventions.

3. Fan out research agents (parallel)

Spawn subagents (the Agent tool) — one per small bucket of 1–4 repos — so the reads run concurrently. Give every agent the same reference profile plus this fixed reporting contract:

  1. What it is — one paragraph on structure & purpose.
  2. License — exact license, and whether it permits reuse-with-attribution. The agent MUST fetch the actual license file (see §4), not guess. If none is found: NO LICENSE FOUND — reuse not permitted by default.
  3. Borrowable ideas — concrete, specific features/patterns this repo lacks that would improve it. Each: what it is, why it’s good, adoption difficulty (Low/Med/High). Demand specificity (“a /heal-skill command that repairs a skill based on where the session got confused”, not “good commands”).
  4. Verdict — is it uniformly superior to this repo? Almost always no — the agent must name what this repo has that the peer lacks.

Tell agents WebFetch summaries come from a small model, so they should flag any mechanic they’re paraphrasing rather than verifying against source.

4. License gate (do this before borrowing ANYTHING)

For each repo you intend to borrow from, confirm the license from the source, not from memory. Fetch in order until one resolves:

https://raw.githubusercontent.com/<owner>/<repo>/main/LICENSE
https://raw.githubusercontent.com/<owner>/<repo>/master/LICENSE
https://raw.githubusercontent.com/<owner>/<repo>/HEAD/LICENSE
gh api repos/<owner>/<repo>/license   # returns license.spdx_id, or 404/null

Then apply:

License found What you may do
MIT / BSD / Apache-2.0 / ISC Copy or adapt code/text with attribution — retain the copyright + permission notice. Apache-2.0: also preserve NOTICE if present.
GPL / AGPL / LGPL / MPL (copyleft) Do not copy into a permissive/unlicensed repo without flagging the license-compatibility consequence to the user first. Prefer reimplementing the idea independently.
CC-BY / CC-BY-SA Fine for prose/docs with attribution; SA imposes share-alike — flag it. Not meant for code.
No license / “all rights reserved” Read-only. You may learn from it and reimplement the idea from scratch in your own words/code, but you may not copy its files, text, or structure verbatim.

When in doubt, treat it as “no license” and reimplement independently. A clean-room reimplementation of an idea is always allowed — copyright protects expression, not concepts.

5. Decide “uniformly superior”

A peer is uniformly superior only if it is a strict superset: it does everything this repo does, at least as well, with no meaningful capability this repo has that it lacks. This is rare — collect the disqualifier for each (the thing this repo does that the peer doesn’t). If one genuinely dominates, say so plainly and recommend adopting it wholesale rather than cherry-picking.

6. Synthesize a ranked borrow list

Merge all agents’ findings, dedupe overlapping ideas, and rank by impact ÷ effort (best bang-for-buck first). For each item give:

  • Idea — one line.
  • Source — repo + its license (the borrow basis: “MIT, attribute” / “no license — reimplement idea”).
  • Why — the gap it closes here.
  • Effort — Low / Med / High.

Lead the report with the headline verdict: is anything uniformly superior? (usually no, with the one-line reason), then the ranked list.

7. Implement — with attribution

Don’t restructure the repo unprompted. Present the ranked list and ask which items to implement (mirror tidy’s close-out). For each item the user greenlights:

  • MIT/BSD/Apache borrow: adapt it, and record attribution. Maintain a CREDITS.md (or NOTICE) at repo root with an entry per source: - <feature> — adapted from [<owner>/<repo>](url) (<SPDX license>). For a copied file, also keep the original copyright header inline.
  • No-license idea: reimplement from scratch; still credit the inspiration in CREDITS.md as “idea inspired by …” (courtesy, not a legal requirement).
  • File deferred items as issues so they aren’t lost.

Output format

  1. Verdict — uniformly-superior? yes/no + one-line reason.
  2. Peer map — short table: repo · bucket · license · 1-line “what”.
  3. Ranked borrow list — as in §6, best-bang-for-buck first.
  4. What this repo uniquely owns — the capabilities no peer replicated (reassurance + positioning).

Relationship to other skills

  • opposition-research (alias oppo) — the mirror image. scout-peers reads a competitor’s code / repo to borrow license-checked implementations; oppo reads its users’ discourse (issue trackers, feature-request boards, subreddits, reviews) for demanded features, regardless of whether anyone built them. Use oppo to learn what to build, scout-peers to learn how others built it.
  • deep-research — the general multi-source web-research harness; scout-peers is the repo-survey-and-adapt specialization.
  • prefer-upstream — before hand-rolling something, both skills push toward reusing what the ecosystem already maintains.

What NOT to do

  • Don’t copy from a repo whose license you haven’t fetched and verified this session. “Probably MIT” is not a license check.
  • Don’t copy verbatim from an unlicensed repo — reimplement the idea instead.
  • Don’t strip a copyright/permission notice when adapting permissively-licensed code.
  • Don’t make the borrow-implementations unilaterally — audit, then ask which to adopt (these are opinionated changes to the user’s repo).
  • Don’t trust a WebFetch paraphrase of a peer’s internals as fact when it matters — fetch the actual source file before relying on the mechanic.
  • Don’t over-weight raw size/star count; a bigger catalog is not “superior” to a focused tool that does its job well.
Back to top