# Explore Source

> Explore and explain an unfamiliar codebase for onboarding. Use when a developer joins a project, when asked to "understand the codebase", "explain the architecture", "how does this project work", "where is X handled", or before making changes in code you haven't seen yet. Produces a structured map of stack, architecture, entry points, conventions, and how to run/test.

- **Type:** Skill
- **Install:** `agentstack add skill-bonnguyenitc-specship-explore-source`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [bonnguyenitc](https://agentstack.voostack.com/s/bonnguyenitc)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [bonnguyenitc](https://github.com/bonnguyenitc)
- **Source:** https://github.com/bonnguyenitc/specship/tree/main/skills/explore-source

## Install

```sh
agentstack add skill-bonnguyenitc-specship-explore-source
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 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.

## 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.

### 1. Identify the stack & how to run it
Read manifests and docs first — they encode the intended setup.
- Manifests: `package.json`, `pyproject.toml`/`requirements.txt`, `go.mod`, `Cargo.toml`, `pom.xml`, `Gemfile`.
- Docs: `README.md`, `CONTRIBUTING.md`, `ARCHITECTURE.md`, `docs/`.
- Ops: `Dockerfile`, `docker-compose.yml`, `Makefile`, `.env.example`, CI files (`.github/workflows/`).
- Extract: language + version, framework, package manager, **the exact commands to install / run / test / lint**.
- **Run the commands before documenting them.** The cheap ones (test, lint, type-check, build) get executed and their real outcome observed — these are the gate commands `coding` and `review` will inherit from your docs, so a wrong one poisons every later stage. Anything too heavy or environment-dependent to run now (deploy, infra) gets documented from source but marked `(unverified)`.

```bash
ls -la
find . -maxdepth 2 \( -name "package.json" -o -name "*.toml" -o -name "Makefile" \) -not -path "*/node_modules/*"
```

### 2. Map the structure
- Get the directory tree (skip `node_modules`, `.git`, `dist`, `vendor`, `target`).
- Name the role of each top-level dir (e.g. `src/`, `api/`, `web/`, `migrations/`, `tests/`).

```bash
ls -la ; tree -L 2 2>/dev/null || find . -maxdepth 2 -type d -not -path "*/node_modules/*"
```

### 3. Find entry points & wiring
- App entry: `main.*`, `index.*`, `app.*`, `server.*`, `cmd/`, the `scripts`/`bin` in the manifest.
- Routing/config: route definitions, DI/container setup, config loading, env var usage.
- Trace one real request/flow end-to-end (entry → handler → service → data layer) to see how layers connect.

### 4. Read the conventions
- Lint/format config (`.eslintrc`, `ruff`, `.prettierrc`, `.editorconfig`).
- **Read a few representative tests** — tests are the best behavior documentation a repo has: they show how the code is meant to be called, what the fixtures/helpers are, and the test structure `coding` must copy. Pick one unit and one integration/E2E test if both exist.
- Naming, folder, and test patterns — copy them, don't invent new ones.
- Git workflow: branch naming, commit/PR conventions if documented.

### 5. Locate the data & external edges
- Models/schema, migrations, ORM usage.
- External integrations: DB, cache, queues, third-party APIs, auth.

## Searching effectively
- Use `grep`/`rg ` to find where a concept lives; for broad multi-location sweeps across naming conventions, spawn the **Explore** agent and ask only for conclusions.
- To answer "where is X handled?", grep the user-facing string or endpoint, then follow the call chain.

## Output: write the onboarding docs

This skill produces **four Markdown files** in `docs/onboarding/`. Create the directory if missing, and overwrite existing files (they are regenerated docs). Use the **exact templates below** — fixed frontmatter and headings — so the docs stay consistent across regenerations and other skills (`spec`, `plan`, `coding`) can rely on their structure.

**If the docs already exist, read them first** — regeneration is a refresh, not a blind rewrite. Verify each existing claim against the current code (cheap: the citations make every claim checkable), rewrite what drifted, and **carry over still-open Open Questions** instead of losing them.

Rules for all four files:
- Every claim must come from files you actually read — cite sources as `path/to/file.ext`, plus a named anchor (`function`/`class`/config key) when pointing inside a file. **Never cite line numbers** — they drift as soon as the code changes. Never invent paths.
- **Mechanically verify every citation before writing** — each cited path must exist (`ls`) and each cited symbol must be greppable in that file. This is non-negotiable for claims that came from a subagent: an agent's confident wrong path becomes a "verified" doc the moment you write it down.
- Set `updated:` in the frontmatter to the current date-time (`YYYY-MM-DD HH:MM +TZ`, from `date` — don't guess).
- Keep every template heading, in order. If a section has nothing, write `_None found._` instead of deleting it.
- Mark anything you couldn't confirm with `(unverified)` rather than guessing.

### `docs/onboarding/what-is-stack.md`
The tech overview: what the project is, what it's built with, and how a request moves through it.

```markdown
---
doc: what-is-stack
updated: 
---

# What Is the Stack

## Overview

## Stack
| Layer | Choice | Version | Source |
|---|---|---|---|
| Language |  |  | `package.json` (`devDependencies.typescript`) |
| Framework | | | |
| Package manager | | | |
| Runtime / infra | | | |

## Architecture

### A typical flow

1.  — `path` (`symbol`)
2.  — `path` (`symbol`)
3.  — `path` (`symbol`)

## External Dependencies
| Dependency | Kind | Used for | Where wired |
|---|---|---|---|
|  | DB |  | `path` (`symbol`) |

## Open Questions
- 
```

### `docs/onboarding/source-structure.md`
The folder map — so a new dev knows where things live.

```markdown
---
doc: source-structure
updated: 
---

# Source Structure

## Directory Tree

## Folder Roles
| Path | Role | What belongs here |
|---|---|---|
| `src/` |  |  |

## Entry Points
| Entry | File | Triggered by |
|---|---|---|
|  | `src/index.ts` | `npm start` |

## Special Conventions
- `/` — 
```

### `docs/onboarding/how-to-code.md`
The day-to-day dev guide. It must answer three questions concretely: **where to put code, how to write it cleanly, and which rules to follow.** Conventions are learned from the actual code, not generic advice — each one needs a real example (`path` + named symbol). When the repo's own conventions are unclear, say so and recommend a sensible default rather than inventing a rule — but always prefer matching existing code over imposing a new style.

```markdown
---
doc: how-to-code
updated: 
---

# How to Code Here

## Local Setup

1.  — ``
2.  — ``
3.  — ``

## Daily Commands
| Action | Command | Notes |
|---|---|---|
| Run | | |
| Test | | |
| Lint | | |
| Format | | |

## Where to Put Code
| Task | Location | Copy the pattern from |
|---|---|---|
| New feature | `` | `path` (`symbol`) |
| API endpoint | | |
| Model / schema | | |
| Shared util | | |
| Test | | |

## Code Style & Conventions
### Formatting

### Naming

### Module size & responsibility

### Layer separation

### Errors, logging, typing

### Imports & path aliases

## Enforced Rules
| Rule | Config | Check command | Enforcement |
|---|---|---|---|
|  | `.eslintrc` | `npm run lint` |  |

## Git Workflow
- Branch naming: 
- Commits / PRs: 
- Review process: 
```

### `docs/onboarding/how-to-deploy.md`
The release path.

```markdown
---
doc: how-to-deploy
updated: 
---

# How to Deploy

## Environments
| Env | Where it runs | How it differs |
|---|---|---|
| dev | | |
| prod | | |

## Build & Deploy Pipeline

1.  — `.github/workflows/` (``)

## Required Env Vars / Secrets
Names only — **never values**.
| Name | Used by | Required in |
|---|---|---|
| `DATABASE_URL` | `path` (`symbol`) | all envs |

## Rollback / On-call
- 
```

After writing, give the user a short summary of what each file covers and list any **open questions** — undocumented or ambiguous areas worth confirming with the team.

## Next step
These four docs are the convention reference every task skill hydrates from (`spec`, `plan`, `coding`, `review` all read `docs/onboarding/*`). Once they're written, **ask the user whether there's a feature/ticket to start** — e.g. "Bạn có muốn bắt đầu một task với /spec không?".

- If yes, **immediately invoke the `spec` skill** (via the Skill tool) — it opens `tasks/TASK-/` and builds on these docs.
- If not, stop here — the docs stand alone as onboarding material.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [bonnguyenitc](https://github.com/bonnguyenitc)
- **Source:** [bonnguyenitc/specship](https://github.com/bonnguyenitc/specship)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-bonnguyenitc-specship-explore-source
- Seller: https://agentstack.voostack.com/s/bonnguyenitc
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.