onboard

Overview

Structured codebase exploration that produces a navigable architecture overview and a "Start Here" guide. Designed for the first hour on a new project.

When to Use

• First session in a repository nobody on the current task has worked in.
• Joining a team, or picking up a take-home, an external repository, or untrusted source that needs the Phase 0 trust scan before anything else runs.
• Refreshing a mental model of a project whose structure moved since it was last read.
• For one file or function, use /explain; for a quality score, use /assessment; for a single diff, use /review.

Arguments

• No arguments: onboard the current working directory. Phase 0 prompts before running the trust scan.
• <path>: onboard the specified path as the project root.
• --trust: I trust this project. Skip the trust scan and the prompt. Recorded in the final Start Here guide as a deliberate skip.
• --verify: I do not trust this project. Run the trust scan without prompting. Useful for take-homes, external repos, and untrusted source.
• Passing both --trust and --verify together is a conflict. Reject with an error.

Process

Phase 0: Trust decision (asked first)

Before any other action, ask the user whether to trust the project. The trust scan is opt-in per invocation.

Decision flow:

Prompt wording:

Do you trust this project? Picking "No, scan it first" runs a read-only scan for install-time hooks, credential-theft patterns, and known supply-chain attack signatures. Takes under 30 seconds on most projects.

Options:

When the scan runs, map the verdict to action:

Phase 0 constraints, apply when the scan runs:

• Never install dependencies. Never run any command defined in the project.
• Never read .env, .env.local, or .env.production. Only .env.example.
• Never reveal actual secret values found during the scan. Show file, line, and pattern name only.
• The scan is read-only. The user's trust choice is recorded in the Start Here guide either way.

Step 1: Detect the project

Read the manifest file to determine language, framework, and runtime version. Check in order: package.json, go.mod, Cargo.toml, pyproject.toml, pom.xml, build.gradle, mix.exs, Gemfile. Record:

• Language and version
• Framework and version
• Package manager
• Runtime constraints

Step 2: Map directory structure

Run ls on the project root and each top-level directory. Classify each directory by purpose:

Step 3: Identify entry points

Find the files where execution begins:

• main field in package.json
• Files named main.ts, index.ts, app.ts, server.ts, main.go, main.rs
• Route definitions: search for router setup, controller decorators, API route files
• CLI entry points: bin field in package.json, files with shebang lines
• Worker or job entry points: queue consumers, cron handlers

Step 4: Read configuration

Read these files in parallel when they exist:

• TypeScript config: tsconfig.json
• Linter config: .eslintrc*, biome.json, .prettierrc*
• Docker: Dockerfile, docker-compose.yml
• CI: .github/workflows/*.yml, .gitlab-ci.yml, Jenkinsfile
• Environment: .env.example
• Database: prisma/schema.prisma, migration files

Step 5: Generate architecture diagram

Produce a Mermaid diagram showing:

• Modules and their responsibilities
• Dependencies between modules
• External services and integrations
• Data flow direction

Use graph TD for layered architectures, graph LR for pipeline architectures. Label edges with the type of interaction: HTTP, event, import, query.

Step 6: Identify patterns

Search the codebase for structural patterns:

Step 7: Read existing documentation

Read in parallel: README.md, CONTRIBUTING.md, ARCHITECTURE.md, docs/ directory contents, CLAUDE.md. Note what is documented and what is missing.

Step 8: Detect conventions

Identify the project's conventions by sampling 5-10 source files:

• Naming: camelCase vs snake_case, file naming patterns
• File structure: one export per file, barrel files, feature-based vs layer-based
• Test patterns: co-located tests vs separate test directory, naming convention
• Import style: relative vs absolute, path aliases
• Error handling: exceptions vs Result types, error classes

Step 9: Output the Start Here guide

Produce a structured guide with these sections:

1. What This Project Does: one paragraph summary of the project's purpose
2. Tech Stack: language, framework, database, key dependencies
3. Architecture: the Mermaid diagram from Step 5 with a brief explanation
4. Key Patterns: list each pattern found in Step 6 with an example file
5. How to Run: commands to install, configure, and start the project
6. How to Test: test commands, test database setup, coverage commands
7. Where to Start Reading: the 3-5 most important files to read first, ordered
8. Conventions to Follow: the conventions detected in Step 8

Step 10: Suggest next steps

Recommend running /retro discover to capture the detected conventions as durable rules in the project's configuration.

Rules

• Phase 0 prompts the user before any scan runs. The default option in the prompt is "No, scan it first", aligned with the protective intent for unknown projects.
• The user can pre-decide non-interactively with --trust, skip scan or --verify, run scan. Passing both is a conflict.
• When the scan runs and returns HIGH-RISK or MALICIOUS, abort onboarding even if the user pressures to continue. The HIGH-RISK override path requires the explicit phrase. MALICIOUS has no override.
• Never modify any project files during onboarding. This is a read-only exploration.
• Do not install dependencies or run build commands unless the user asks.
• When documentation is incomplete or contradicts the code, trust the code.
• Flag discrepancies between docs and code as findings.
• Keep the Start Here guide under 200 lines. Link to files instead of inlining code.
• The Start Here guide must include a "Safety verdict" line near the top, summarizing the trust decision and the scan result if applicable.

Common Rationalizations

• "The repository comes from a well-known organization, the trust question is noise": Phase 0 asks on every run without a flag, and the default focus is the scan.
• "An install would let me read the generated types": onboarding installs nothing and runs no project command unless the user asks.
• "The README says the service uses X, so it does": when the docs and the code disagree, the code wins, and the mismatch becomes a finding.
• "Inlining the key functions saves the reader a click": the guide links to files and stays under 200 lines.
• "The user insists, so the MALICIOUS verdict can be waived": MALICIOUS has no override, and HIGH-RISK continues only on the literal phrase I accept the risk.

Red Flags

• Stop and ask the trust question when no flag was passed and no other step has run.
• Stop and reject the invocation when both --trust and --verify were passed.
• Stop and wait for the literal phrase I accept the risk when the scan returns HIGH-RISK.
• Stop onboarding and recommend a Docker sandbox or deleting the directory when the scan returns MALICIOUS.
• Stop and read .env.example instead when the next read targets .env, .env.local, or .env.production.

Verification

• The Start Here guide carries a Safety verdict line near the top that matches the Phase 0 outcome.
• The guide has all eight sections from Step 9 and stays under 200 lines.
• Every file named under Where to Start Reading exists on disk.
• The Mermaid diagram labels every edge with its interaction type.
• git status shows no project file modified by the onboarding run.
• Every mismatch found between the docs and the code is listed as a finding.

Related skills

• /audit trust -- Untrusted-project safety scan. Runs automatically as Phase 0. Can also be invoked standalone before adding a new dependency or considering a third-party project.
• /explain -- Deep explanation of a specific file or function.
• /assessment -- Full quality assessment of the codebase.
• /retro discover -- Capture conventions as rules.
• /review -- Review specific code changes.