evaluate

/evaluate — teardown a product from a URL and decide what's worth keeping

Given one URL, produce an evidence-backed verdict plus a report. Subagents crawl the code in chunks; the calling session keeps only conclusions.

Two questions, every time

Judge both — don't collapse to "lift code":

1. ADOPT AS-IS — is the product itself worth keeping/running, slotted into your Claude Code workflow (a CLI on PATH, an MCP server, a /skill or hook pattern, a dotfile)? Judged from docs + how it runs, not a code port. Note install/runtime cost and whether it's handy at the workstation even if Worker-irrelevant.
2. LIFT — features/code/patterns worth pulling into this repo, or worth keeping as a reference snippet. The code-crawl axis.

A product can win on one, both, or neither — the verdict names which.

Operating principles

• Subagents protect the main context — orchestrate and synthesize only; never read the clone file-by-file yourself; pull conclusions, not file dumps.
• Evidence or it didn't happen — every claimed feature cites path:line; no evidence, no claim.
• Portability is the point — score findings against this repo's runtime, deps, license.
• Docs-only is valid for closed-source — skip cloning, deliver a docs-based verdict, say so explicitly. Read-only rules: see Guardrails.

Steps

0. Resolve the URL → find the source

Locate the product's docs/README and source repo. Try WebFetch first; if blocked (Reddit, some blogs), fall back to mcp__fetch__fetch against old.reddit.com/... (www.reddit.com/.json 403, old.reddit.com works). For HN, fetch the linked article + repo, not just comments. No GitHub/GitLab URL found → mark closed-source, jump to step 5.

1. Characterize from docs (before cloning)

Read README + landing page + launch post. Capture, in your own words: the pitch (one sentence); headline claims (benchmarks, "works with X" — note which are testable); architecture (runtime/platform, language, deployment, deps); license (flag copyleft — GPL/AGPL — loudly: lifting code carries obligations, lifting ideas doesn't; gates step 4). Then make the axis-1 call (mostly from docs): install/runtime cost, blockers (hosted service, heavy runtime, paid tier). Often answerable from docs alone — skip straight to step 5 if so.

Write a 4-6 line repo-context block describing this repo (from local CLAUDE.md/ README.md: what it is, runtime/platform constraints, architecture, what's worth lifting). Paste it into every subagent prompt to pre-filter findings for portability — drives axis 2; axis 1 stays with the calling session.

2. Clone & inventory (read-only)

bash .claude/skills/evaluate/survey.sh <git-url> <slug>

Shallow-clones to /tmp/evaluate/<slug>/, prints tree/LOC/languages/manifests/entry points. Do not cd in and run anything. Large tree → partition harder in step 3.

3. Partition the codebase into subsets

Carve into coherent, non-overlapping subsets — one subagent each — by concern/module, not file count. Group by top-level dir/subsystem (connectors/, auth/, ui/, etc.); size each for close reading (a handful of files to a few thousand LOC, split fat dirs, merge thin ones); skip noise (node_modules, lockfiles, dist/, .github/, generated/vendored code, test fixtures unless tests are the point). Typical eval = 3-7 subagents; see "Scaling" for a genuinely large codebase.

4. Dispatch subagents (parallel, read-only)

Send all subagents in a single message, Explore or general-purpose type. Give each: scratch path, its assigned file/dir list, the repo-context block, the license note, any focus hint. Prompt template:

You are evaluating a third-party codebase to find features worth lifting into OUR repo.
READ-ONLY: read and grep files; never run, install, or build anything.

OUR REPO (what we'd be lifting INTO):
<repo-context block from step 1 — runtime, platform constraints, architecture, license>

THE PRODUCT'S LICENSE: <license> — <if copyleft: lifting code carries obligations; focus
on patterns/ideas we'd reimplement, not copy-paste>.

YOUR SUBSET (read closely; ignore everything else in the clone):
  scratch path: /tmp/evaluate/<slug>/
  files/dirs:   <the assigned subset>
FOCUS HINT (if any): <hint>

For THIS subset, report back as a list of candidate findings. For each:
  - name + one-line description
  - evidence: the key file:line locations
  - what it does (mechanism, briefly)
  - liftability into OUR repo: drop-in | adapt | incompatible — and WHY (name the
    concrete blocker: runtime mismatch, heavy dep, license, host constraint, etc.)
  - dependencies it drags in
  - rough effort to port (S/M/L)
Then one line: your overall read of this subset (is there anything here for us?).
Return ONLY this digest — no preamble. If the subset has nothing liftable, say so plainly.

For 2+ subagents, invoke superpowers:dispatching-parallel-agents.

5. Synthesize the verdict & write the report

The calling session, not a subagent, produces the verdict — only it sees all subsets at once and holds the repo's strategic context. Deliver in chat AND write docs/evaluations/<date>-<slug>.md, answering both axes:

• One-line verdict per axis — Adopt as-is: ADOPT AS-IS / TRY IT / SKIP, with the install/run path if adopt/try (e.g. npm i -g X, "wire MCP endpoint Y", "drop in ~/.claude/skills/"). Lift: LIFT / PARTIAL / SKIP.
• Why — 2-4 sentences tied to real wins/blockers.
• Findings table (LIFT) — feature · value · liftability · effort · blocker, sorted by value.
• What to lift now — concrete shortlist with porting notes.
• What to adopt/try as-is — exact setup step, cost/auth/runtime caveats; offer to install/wire it.
• What to park — good ideas not a fit today but findable later (pointer in roadmap/ADR, or /idea) — often the most valuable output, capturing the pattern even when the code doesn't port.
• What to skip & why.

A product can land ADOPT-AS-IS + SKIP-lift, SKIP-as-is + LIFT, both, or neither — make the combination clear. Closed-source → note no code was reviewed; axis 1 still applies.

Scaling

Default is the Agent-tool fan-out above, no opt-in needed. For a very large codebase, or on explicit request for a workflow/"ultracode", use a Workflow pipeline — pipeline(subsets, crawl, verify) — adding a stage that adversarially verifies top findings exist as described before they reach the verdict.

Guardrails

• Never execute the clone — no install/build/run. Findings confirmable only by running are marked "claimed, unverified," not run to check.
• License before copy-paste — no verbatim lifts from GPL/AGPL/unlicensed repos; reimplement the pattern instead. MIT/Apache/BSD: reuse fine with attribution.
• Don't pollute the repo tree — clone stays in /tmp/evaluate/<slug>/; the only repo artifact is the report under docs/evaluations/.
• Stay honest about fit — SKIP with one parked idea beats an inflated "adopt"; anchor findings to a real portability story.
• Clean up (optional) — rm -rf /tmp/evaluate/<slug> once the report is written, unless the user wants to keep poking at the clone.