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