onboard

name

onboard

description

Onboard Claude to an existing brownfield project. Discovers the stack, conventions, and architectural decisions from the codebase, surfaces and resolves genuine conflicts interactively, then produces CLAUDE.md plus context/ artifacts (conventions, decisions, onboard-report). Re-run aware — detects prior onboards and offers Refresh (carry forward resolved decisions) or Fresh (start from scratch). Use when a team lead wants to set Claude up on an existing repo.

onboard

Onboard Claude to an existing brownfield project. Run from the project root by the team lead — on first run or any time the codebase has changed significantly.

What this skill does

1. Detects whether this is a first run, a re-run, or a resume of an interrupted run — and routes each correctly.
2. Discovers the stack, conventions, and architectural decisions from the codebase — no interrogation required for things Claude can infer from files.
3. Surfaces conflicts where the codebase is genuinely inconsistent, pausing for you to resolve each one before producing output.
4. Analyzes six dimensions in parallel (routes, databases, async messaging, infrastructure, conventions, decisions) using independent agents.
5. Produces four artifacts for single-repo projects: CLAUDE.md, context/conventions.md, context/decisions.md, and context/onboard-report.md. For monorepos, also produces one <service>/CLAUDE.md per detected component (4 shared artifacts + N per-service files).

The produced CLAUDE.md contains no unresolved conflicts. Every pattern in it is the canonical one you confirmed.

---

Instructions

You are running the onboard skill. Follow these phases in order. Do not skip phases. Do not ask the user for information Claude can determine from the code.

Phase 0: Re-run Detection

Run this phase first, before Phase 1. Classify the run as exactly one of three states and route accordingly. Only one state applies per run — do not fire more than one prompt.

Step 0.1: Check for an interrupted run.

Check whether context/.onboard-checkpoint.md exists. If it does, read its Status line.

If Status is anything other than collection-complete: this is an interrupted run. Proceed directly to Phase 2 now — do not run Phase 1 first. Phase 2's opening checkpoint check will present the resume-or-restart prompt. Do not show the Refresh/Fresh prompt below.

Step 0.2: Check for a completed prior onboard.

If there is no checkpoint file, or the checkpoint Status is collection-complete: check whether both of these exist:

• CLAUDE.md (project root)
• context/onboard-report.md

If either is absent: this is a first run — proceed to Phase 1 now. Do not show any Phase 0 prompt.

If both exist: this is a re-onboard — continue to Step 0.3.

Step 0.3: Report state and ask Refresh or Fresh.

Read context/decisions.md if it exists and count the resolved decisions. Then report:

Prior onboard detected:
  CLAUDE.md                  — exists
  context/onboard-report.md  — exists
  context/decisions.md       — [N resolved decisions / not found]

Ask exactly this question and wait for the answer before proceeding:

Which mode?

• Refresh — Regenerate from the current codebase. Resolved decisions will be carried forward (conflicts you already resolved will not be re-asked).
• Fresh — Discard all prior artifacts and decisions. Regenerate from scratch, re-asking all conflicts.

Step 0.4: Set run mode and proceed.

Record the answer as the run mode (refresh or fresh). This is referenced by Phase 3 and Phase 6.

Delete context/.onboard-checkpoint.md if it exists (so Phase 2 starts a fresh checkpoint rather than offering an erroneous resume prompt).

Proceed to Phase 1.

Phase 1: Stack Detection

Read the project root for these files and identify the primary stack:

File	Stack
go.mod	Go
package.json	Node.js / TypeScript / JavaScript
pom.xml	Java (Maven)
build.gradle or build.gradle.kts	Java / Kotlin (Gradle)
Cargo.toml	Rust
requirements.txt / pyproject.toml / setup.py / setup.cfg	Python
Gemfile	Ruby
composer.json	PHP
*.csproj / *.sln	C# / .NET
mix.exs	Elixir

Read the identified manifest file(s) to extract:

• Language version
• Key frameworks and libraries (web framework, DB driver, test library, logging library)
• Build/tooling setup

If multiple stacks are present (monorepo), identify each service separately.

ast-grep check: The ast-grep-supported languages are: Go, TypeScript, JavaScript, Python, Java, Kotlin, Rust, Ruby, C, C++, C#, Swift. If at least one supported language was detected above, run which sg. If the command returns nothing, print this warning and continue — do not stop:

ast-grep not found. Install it to enable structural code search:
  npm install -g @ast-grep/cli
  brew install ast-grep          # macOS
  cargo install ast-grep         # if Rust toolchain present

Skip this check entirely if no supported languages were detected (e.g., a pure Terraform, Helm, or Nix repo).

Phase 2: Evidence Collection

Read skills/onboard/evidence-collection.md now and follow it exactly. It contains the full evidence collection protocol: checkpoint structure, global exclusions, monorepo detection, and all 6 batches. Do not proceed to Phase 3 until all 6 batches are complete and the checkpoint status is collection-complete.

Phase 3: Conflict Detection

A conflict is a case where two or more patterns exist in the codebase and both cannot be canonical — one of them is wrong or outdated. Examples:

• Two different error wrapping styles used in different files
• Two naming conventions for the same type of identifier
• Two different HTTP error response shapes
• Two different places where validation happens

Do not flag style differences that are not contradictory. Do not flag things where both patterns are acceptable. Only flag genuine inconsistencies where picking the wrong one would produce incorrect or inconsistent code.

In Refresh mode (run mode = refresh): Before surfacing any conflict, read context/decisions.md. For each genuine conflict you would otherwise surface, check whether its subject (error handling style, naming convention, response shape, etc.) maps semantically to an existing decision entry:

• Mapped and consistent: The canonical pattern recorded in that decision entry is still dominant in the current evidence — do not ask the question. Carry the recorded resolution forward silently and add it to an internal carried-forward list (decision title + canonical pattern). This list is used by Phase 6.
• Mapped but contradicted: The recorded canonical pattern is now contradicted by the majority of current evidence — re-surface this conflict only, prefacing it with: "A prior decision recorded '[prior canonical pattern]' as canonical, but the current codebase now predominantly shows '[contradicting pattern]'. Which should be canonical?" Then wait for the answer. Do not add it to the carried-forward list — it is being re-resolved. Add it to an internal re-surfaced list (conflict subject + prior canonical pattern + newly chosen canonical pattern).
• No mapping found: Ask the conflict as normal using steps 1–4 below.

In Fresh mode and first runs, skip the context/decisions.md check entirely and go directly to step 1 for every conflict. The carried-forward list remains empty.

For each genuine conflict found (or re-surfaced):

1. Show the user the two (or more) patterns, with file references.
2. Ask: "Which is the canonical pattern for this project?"
3. Wait for the answer before moving to the next conflict.
4. Record the resolution.

Ask one conflict at a time. Do not batch conflicts into a single question.

If no genuine conflicts are found, say so and proceed to Phase 4.

Phase 4: Dimension Analysis

Read skills/onboard/dimension-agents.md now and follow it exactly. It contains the full dimension analysis protocol: all 6 agent specifications with their prompts. Spawn all 6 agents in a single message and wait for all to complete before proceeding to Phase 5.

Phase 5: Produce Artifacts

Step 5.0: Git Guard

Before writing any file, check whether any target artifact paths already have uncommitted changes in git:

1. Determine target paths. The targets are always CLAUDE.md and context/. For a monorepo, also include each <service>/CLAUDE.md path from the component list in the checkpoint.

2. Check for a git working tree. Run git rev-parse --is-inside-work-tree. If the command fails (exit code non-zero) or returns something other than true:

   • Warn the team lead: "This directory does not appear to be a git repository. Existing artifacts cannot be diff-protected. Continuing will overwrite any existing files at the target paths. Proceed? (yes/no)"
   • If yes: continue. If no: stop — print "Aborting — no files written." and end the skill.

3. Check working-tree status. Run git status --porcelain -- CLAUDE.md context/ [each per-service CLAUDE.md path].

   • If output is empty: the working tree is clean (or no artifacts exist yet) — proceed to write with no new prompt.
   • If any lines appear: list the affected files and ask: "These files have uncommitted changes that would be overwritten:\n[list]\nPlease commit or stash your changes first, or confirm you want to overwrite them. Proceed? (yes/no)"
   • If yes: continue. If no: stop — print "Aborting — no files written. Commit or stash your changes and re-run." and end the skill.

Read skills/onboard/artifact-formats.md now and follow it exactly. It contains the format specifications for all four artifacts: CLAUDE.md, context/onboard-report.md, context/conventions.md, and context/decisions.md. For monorepos, also produce one <service>/CLAUDE.md per detected component as specified in the artifact-formats file. Write each file directly — do not display the full content in the chat first.

Phase 6: Report

If run mode is refresh: Before the main report, produce a "What changed since last onboard" section using the following steps:

1. Services added or removed: Run git diff HEAD -- context/onboard-report.md. Read the diff output and identify service names that appear only in removed lines (-) — these are removed services. Identify service names that appear only in added lines (+) — these are added services. If the command fails or shows no output, note "no prior artifact to compare".

2. New conventions: Run git diff HEAD -- context/conventions.md. Read the diff output and summarize any conventions that appear only in added lines (+). If the command fails or shows no output, note "no prior artifact to compare".

3. Conflicts re-surfaced: List each entry from the re-surfaced list (built in Phase 3): the conflict subject, the prior canonical pattern recorded in decisions.md, and the newly chosen canonical pattern. If the list is empty, write "none".

4. Decisions carried forward: List each entry from the carried-forward list (built in Phase 3): the decision title and canonical pattern. If the list is empty, write "none".

If no changes are detected across all four categories (empty diffs, empty re-surfaced list, empty carried-forward list), write instead: "No significant changes detected vs. prior onboard artifacts."

Present this change summary as a distinct block, then continue with the main report below.

Main report (all modes — fresh, refresh, and first run):

After writing all four files, report:

1. Files produced (with paths)
2. Conflicts resolved (summary of each, which pattern was chosen)
3. Things Claude could not confidently infer (list these explicitly so the team lead can fill them in manually)
4. What to do next: "Review the produced files. For monorepos, this includes the shared artifacts plus one CLAUDE.md per service. Edit anything Claude got wrong. Then commit them to the repo. Every future Claude session will load CLAUDE.md automatically."