Repo Onboard

Turn a GitHub repository into the shortest path from "I have the repo" to "I have a commit that will pass review." The output is six sections, produced in order. Optimize for what do I type to land an accepted change, not for a complete tour of the codebase.

The input is a repo in any form: a GitHub URL, an org/repo slug, a local path on disk, or the current working directory when the user is already inside a checkout. Local repos are a first-class input — most onboarding happens on a checkout the user already has. If it's ambiguous which repo, ask (or infer from git remote -v) before starting.

Sibling skill: rapid-onboard does the same for a docs URL (learn an API). This one is for source code (contribute to it). If the user pastes docs, prefer that one.

Phase 1 — Acquire and orient

Get a local checkout, then map the stack from signals, not guesses.

• Acquire. If given a URL/slug, clone into a sensible location (git clone or gh repo clone); cloning is safe and reversible, so do it without asking. If given a local path or already inside a checkout, work in place — do not re-clone. Either way, confirm the repo with git remote -v and git status, and note the default branch (git remote show origin, or the local HEAD if there's no remote — a local-only repo is fine).
• Map the stack. Read the top-level README, then detect language and tooling from manifests actually present: package.json, pyproject.toml / requirements.txt, go.mod, Cargo.toml, pom.xml / build.gradle, Gemfile, composer.json, *.csproj, etc. Identify the primary language, framework, and package manager from these files — not from the repo name.
• Sketch the layout. List the top-level directories and name what each is (source, tests, docs, infra, examples). Keep it to one line each.

Report: repo, default branch, primary language/framework, package manager, and the one-line layout.

Phase 2 — Get to green

This is the crux. You cannot commit with confidence until you can reproduce the project's own definition of "working." A commit that fails local checks is a wasted round trip.

Find and actually run the loop — do not just read the commands off the README, execute them and report what really happened:

1. Install dependencies (npm ci, pnpm i, pip install -e ., go mod download, cargo build, make setup, a devcontainer, etc.).
2. Build if there's a build step.
3. Test — run the suite, or at least a fast subset. Note how long it takes and whether it's green before you touch anything (a pre-existing red baseline is critical to know).
4. Lint / format / typecheck — run whatever the repo uses (ruff, eslint, prettier, gofmt, cargo clippy, mypy, tsc). These are usually what actually blocks a PR.

Prefer discovering the canonical commands from Makefile, justfile, package.json scripts, CONTRIBUTING, or CI workflow files (.github/workflows/*.yml) over inventing them — CI is the source of truth for "what must pass." If a step fails for environment reasons, say so plainly and record the exact failure and the closest working fallback.

Report each command, whether it succeeded, and the baseline test/lint status.

Phase 3 — Learn the contribution rules

Extract the things that get a PR bounced, so the first commit clears them. Pull from CONTRIBUTING.md, .github/PULL_REQUEST_TEMPLATE*, CODEOWNERS, CI workflows, and existing merged history:

• Commit message convention — Conventional Commits? A required prefix/scope? Check git log --oneline -30 for the real pattern the maintainers use, not just what a doc claims.
• Branch naming and the correct base branch for PRs (often main/master, sometimes develop).
• Sign-off / legal — DCO (Signed-off-by, needs git commit -s)? A CLA bot? These silently block merges.
• Gating CI checks — which jobs must be green (lint, tests, typecheck, coverage threshold, changelog entry, license/format check).
• Required companions — does a code change require a test, a changelog fragment, a docs update, a generated-file refresh?

List each rule as one line: the rule, then how to satisfy it. Flag anything that fails silently.

Phase 4 — Map the core surface

Derive the 20% of the code a contributor must hold in their head, from centrality signals, not file size or impression:

1. Entry points — main, CLI entry, server bootstrap, the framework's app root.
2. Cross-reference recurrence — the modules/packages imported or referenced across many files are core; a leaf touched once is not. Rank by inbound references.
3. Where work happens — routes/handlers, domain models, the primary service layer, and the parallel test directory that mirrors it.
4. Config & wiring — where env/config is read and how the pieces are assembled.

Present the 5–8 highest-signal files/dirs with, for each: path, one line on its role, and why it's core (entry point / N inbound references / README-highlighted). Show the auditable signal, not just an assertion.

Phase 5 — Locate the change site

• If the user has a specific task: find the exact file(s) and function(s) where the change belongs, the sibling test file and the pattern to mirror, and one nearby example of the same kind of change (a similar handler, a similar migration) to imitate. Point at line numbers.
• If no task yet: identify a low-risk starting area (an open good-first-issue, a TODO, a thin missing test) and the conventions to copy. Do not invent scope.

The deliverable is: "the change goes here, mirror this existing code, and its test goes there."

Phase 6 — The commit path

The shortest sequence from clean tree to a commit that will pass. Write the exact commands for this repo:

1. Branch off the correct base with the correct name (git checkout -b <convention>).
2. Make the change, mirroring the nearby code identified in Phase 5.
3. Run the pre-commit gate from Phases 2–3 in order: format → lint → typecheck → the relevant tests. Fix until green locally — this is what makes the commit mergeable.
4. Commit with the correct message format (and -s sign-off if DCO applies).
5. Push and open the PR against the correct base — but stop and confirm with the user before pushing or opening a PR. Cloning and local commits are reversible; publishing to the remote is outward-facing, so get explicit go-ahead unless the user already told you to ship.

---

Output format

Produce the six sections under clear headers, in order:

1. Orientation (repo, branch, stack, layout)
2. Green build (the commands, run results, and baseline status)
3. Contribution rules (what gates a PR)
4. Core surface (5–8 files/dirs by centrality signal)
5. Change site (where the change goes + what to mirror)
6. Commit checklist (the pinnable artifact)

Lead with a one-line note on what you did (cloned vs. in-place, and whether the build/tests actually ran green). Keep prose minimal everywhere.

Verify, don't assume. The value of this skill is that the build/test/lint commands actually ran and the contribution rules are real (confirmed against CI and git history), not pattern-matched from a generic README. Where a step couldn't be executed (no network, missing secret, long build), say so explicitly and mark that part as unverified rather than presenting it as done.

Stay reversible until told otherwise. Clone freely, build freely, commit locally freely. Do not push, open a PR, or otherwise write to the remote without explicit user confirmation.

End with the commit checklist — a dense, scannable list the user pins while working: base branch, branch-name pattern, format/lint/test commands, commit-message format, sign-off requirement, and the gating CI checks. Each line one glance.