repo-onboarding

Repository Onboarding

Trigger Signals

• the repository is unfamiliar, mixed, legacy, or monorepo-shaped
• the next safe step is blocked on understanding layout, ownership, or workflow
• docs are sparse, stale, or scattered across many entrypoints

Inspect First

• repo root files such as README.md, top-level manifests, CI config, container config, and deployment hints
• AGENTS.md, .agents/skills/, .specify/, or other repo-native guidance surfaces when present
• top-level source, app, package, service, infra, and test directories
• CODEOWNERS, contribution docs, issue or PR templates, and other health signals when present

Workflow

1. identify the repo archetype and dominant implementation surfaces
2. map build, test, run, deploy, and validation entrypoints
3. infer ownership, boundaries, and high-risk hotspots from structure and metadata
4. call out drift, missing validation, generated code, or conflicting conventions
5. recommend the next best action and the best repo surfaces to load before changing code

Output Contract

• repository summary with dominant languages, runtimes, and repo shape
• key commands and entrypoints for build, test, run, and release
• hotspots, blockers, and missing information that affect safe changes
• recommended next action with the specific files or dirs to inspect next

Failure Modes

• repo layout is too large to inspect safely in one pass
• generated or vendored code hides the real ownership boundaries
• no reliable build or validation entrypoints can be found

Escalation

• escalate when ownership or architecture cannot be inferred safely
• escalate when there is no trustworthy validation path for a risky change
• escalate when docs and code disagree about the active workflow

References

• skills/repo-onboarding/references/output-template.md
• skills/repo-onboarding/references/discovery-checklist.md
• skills/repo-onboarding/references/repo-archetypes.md
• skills/repo-onboarding/references/ownership-and-health-signals.md
• skills/repo-onboarding/references/command-discovery.md
• skills/repo-onboarding/references/monorepo-signals.md
• skills/repo-onboarding/references/examples.md