ss-explore-source

Explore Source

Goal: turn an unfamiliar repo into a clear mental model fast. Read before you change.

When to use

• A new dev is onboarding and needs the lay of the land.
• You're asked "how does this work?", "where is X?", "explain the architecture".
• You're about to modify code in an area you haven't read yet.

Delegate heavy exploration to a subagent

For anything beyond a tiny repo, don't read the whole codebase in the main thread — it floods the context. Spawn the ss-explorer agent if your platform can — it ships with specship for Claude Code (.claude/agents/), prefers the codebase-memory MCP when the project has it, and falls back to plain search — else the built-in Explore agent (or general-purpose for multi-step research), to do the wide fan-out reads and return only conclusions, keeping this thread clean.

• When: a large/unfamiliar repo, or a broad question ("where is X handled across the codebase?", "what are all the entry points?").
• How: run the steps below as a brief for the agent. Give it a focused goal and ask for a structured result, not file dumps — e.g. "List every top-level dir with its role and the key entry file (path + entry symbol)" or "Find where auth is enforced; return the call chain."
• Parallelize independent sweeps (structure, entry points, conventions) as separate agent runs when it speeds things up.
• Then synthesize the agents' findings into the onboarding docs yourself. You own the writing and the verification — spot-check anything an agent claims before citing it.
• For a small repo, just do it inline; spawning an agent isn't worth the cold-start cost. Likewise if your platform can't spawn subagents at all: do the full exploration inline in the main thread (../WORKFLOW.md → In-stage subagents — delegation is an optimization, never a precondition).

Method

Work top-down: stack → structure → entry points → data flow → conventions. Don't read every file; read enough to build an accurate map, then verify the gaps.