--- name: ss-explore-source description: 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. --- # 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. ### 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 `ss-coding` and `ss-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 `ss-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 **`ss-explorer`** agent if your platform can (or the built-in **Explore**) 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 (`ss-spec`, `ss-plan`, `ss-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 <1–3 sentences: what this project is and does> ## Stack | Layer | Choice | Version | Source | |---|---|---|---| | Language | | <5.x> | `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. <.env setup> — `` 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 (`ss-spec`, `ss-plan`, `ss-coding`, `ss-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 /ss-spec không?". - If yes, **immediately invoke the `ss-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.