analyze-oss

Analyze OSS — What/Why-focused open source analyzer

Clone an open-source repo locally, analyze it through multiple lenses in parallel via subagents, and deliver a What/Why-focused report in chat.

The goal is not to produce an implementation deep-dive. The goal is to help the user quickly decide "is this what I need, and why would I use it?" and then answer any custom questions they have about the repo.

When to use

• User gives a GitHub URL and wants to understand what it is / why it exists
• User asks "what does this repo do?", "이거 뭐하는거야?", "이거 왜 쓰는거야?"
• User is evaluating whether to adopt a library
• User wants a quick intellectual onboarding to an OSS project

Input

Accept any of:

• GitHub URL: https://github.com/owner/repo (or git@github.com:...)
• owner/repo shorthand
• Optional custom questions appended: analyze-oss owner/repo "X 대비 어떤지, Y 유스케이스 맞는지"

If the URL is ambiguous, ask the user to confirm before cloning.

Execution

Phase 1 — Fetch repo

Target directory: ~/opensource-analysis/<repo-name>/

BASE=~/opensource-analysis
REPO_NAME=<derived from URL>
TARGET=$BASE/$REPO_NAME
mkdir -p $BASE
if [ -d "$TARGET/.git" ]; then
  cd "$TARGET" && git pull --ff-only
else
  git clone --depth 50 <repo-url> "$TARGET"
fi

Notes:

• --depth 50 keeps clone fast; enough for recent commit signals.
• If git pull fails (local changes, diverged), warn the user — don't force.
• Capture the absolute path of $TARGET; all subagents must use this absolute path.

Phase 2 — Quick recon (main agent, before dispatch)

Read these in parallel to build dispatch context (don't deep-read, just skim):

• README* (pick the most prominent)
• package.json / pyproject.toml / Cargo.toml / go.mod (whichever exist)
• Top-level directory listing
• docs/ top-level listing if present
• Recent 10 commits: git log --oneline -10

Extract: repo name, elevator pitch (if README has one), primary language, rough size.

This recon is only to brief subagents well — do not write the report yet.

Phase 3 — Parallel subagent dispatch

Spawn the following subagents in one message, in parallel. Each gets:

• Absolute path to the cloned repo
• The recon summary from Phase 2
• Instructions to read only what they need (not the whole repo)
• Instruction to return a structured markdown block

Subagents (4 default lenses):

1. what-lens — "What is this?"

   • Read: README, top-level docs, package descriptions
   • Produce: one-line definition (≤25 words), 3–5 core capabilities (one sentence each), the repo's own self-description verbatim if useful
   • Avoid implementation detail. Stay at the "capabilities the user gets" layer.

2. why-lens — "Why does this exist?"

   • Read: README motivation/intro sections, CHANGELOG for origin context, any MOTIVATION.md / docs/why*
   • Produce: the problem it solves (in plain language), what you'd have to do without it, 2–3 named alternatives and how this differs, the distinct value proposition
   • If motivation is not explicit, infer from the examples and features — but mark inferences as "[inferred]".

3. who-when-lens — "Who uses this, and when?"

   • Read: README use-cases/examples, examples/, showcase/users sections, issues labeled "question" or similar for real-world usage signals
   • Produce: target user personas (2–4), concrete use cases (with short scenarios), situations where you'd not use this / known limitations

4. how-used-lens — "How does a user actually use this?" (user-perspective, not implementation)

   • Read: Quickstart in README, examples/, minimal usage snippets
   • Produce: install step, minimal "hello world", typical usage flow from zero → first success (as a narrative, not code walkthrough), main interaction touchpoints (CLI? API? config file? SDK?)
   • Explicitly exclude internal architecture, source-level design, class diagrams.

If the user provided custom questions, spawn one more subagent per distinct question:

5. custom-Q{n}-lens — answer one specific user question
   • Brief it with the full question verbatim and the recon summary
   • Tell it to read whatever files it needs (grep liberally) to answer, and to cite file paths in its answer
   • If it cannot answer from the repo alone, say so — don't fabricate

Phase 4 — Synthesize

Main agent takes all subagent outputs and composes the final report in chat.

Output template (strict):

## Analyze OSS: <repo-name>

**Repo:** <url>  ·  **Language:** <lang>  ·  **Cloned at:** <abs path>

### What
<one-line definition>

**Core capabilities:**
- …
- …

### Why
**Problem:** <plain language>
**Without it:** <what you'd do otherwise>
**Alternatives & differentiator:** <named alternatives, 1 line each, then what makes this different>

### Who / When
**Target users:** …
**Use cases:** …
**Not a good fit when:** …

### How it's used (user perspective)
**Install:** `…`
**Minimal example:** <short snippet or description — keep brief>
**Typical flow:** <zero-to-first-success narrative, 3–6 steps>
**Interaction surface:** <CLI / HTTP API / SDK / config / etc.>

### Custom Q&A   ← only if user provided questions
**Q: <question>**
A: <answer with file path citations>

### Notes
- [inferred] markers if any
- Anything surprising / red flags / caveats worth surfacing

Phase 5 — Offer follow-ups

After delivering the report, ask:

"Anything you want me to dig into further? (e.g. compare with X, how auth works, licensing details, etc.)"

For follow-ups, dispatch additional subagents with the same pattern — one question, one subagent — and extend the Custom Q&A section.

Principles

• What/Why over How. The user does not want an architecture lecture. Unless they explicitly ask "how is X implemented", stay at the user-facing layer.
• Parallel by default. All independent lenses go in one message. Sequential dispatch wastes wall-clock time.
• Cite file paths when claiming something about the repo. "README says X" is better than just "X".
• Mark inferences. If something isn't stated in the repo, say [inferred].
• Don't overclaim popularity or quality. You have shallow clone + local info; avoid "this is widely used" unless README/shields show it.
• Chat output only. Do not write a report file unless the user explicitly asks.

Edge cases

• Private or 404 repo: git clone will fail — surface the error and ask the user.
• Huge repo (>500MB): --depth 50 already helps; if still slow, warn the user and proceed.
• Monorepo: if the repo contains multiple packages, ask the user which sub-package to focus on before dispatching subagents (or offer an overview of all packages).
• Non-code repos (awesome-lists, docs): adapt — the "how it's used" lens becomes "how do you navigate/consume this".
• Stale clone with local changes: don't overwrite. Report to user, ask whether to re-clone fresh into a sibling directory.