Onboard New Repo

Onboard New Repo

The "I just cloned this, what is it" workflow. Replaces 30 minutes of poking around with one chained pass that builds the full picture and surfaces issues before you make changes.

Auto-invocation triggers

• User says "I just cloned X", "let's look at this repo", "what is this codebase"
• Working in a repo with no CLAUDE.md, .claude/ directory, or recent session history
• After a git clone from a fresh shell

Workflow

Phase 1 — Understand (always)

Invoke adt-repo-intake for the structural picture:

• Languages + frameworks detected
• Entry points (CLI, server, lib)
• Test runner + framework
• Build / dev / test commands
• Workspace layout (monorepo? single?)

Phase 2 — Health check (always)

Invoke audit-deep for the across-the-board state:

• Test count vs proportionality
• Coverage vs threshold
• Security audit (deps, secrets, OWASP)
• Hook effectiveness if .claude/ present
• MCP usage
• Plugin usage

This catches "this repo is in rough shape" up front so you don't merge into it blind.

Phase 3 — Gate audit (always)

Invoke config-drift-detect to surface gates that conflict with sane defaults:

• Coverage thresholds incompatible with proportionality
• TypeScript strictness vs codebase reality
• Husky pre-commit running too much
• Branch protection vs solo-dev workflow

Output: ranked list of gate adjustments with effort estimates.

Phase 4 — Bootstrap CLAUDE.md (if missing)

If no CLAUDE.md at repo root:

• Invoke init to generate one from the codebase
• Include: build commands, test commands, key conventions, project structure
• Stage but don't commit (let user review first)

Phase 5 — Permission prune (if .claude/settings.json exists)

Invoke fewer-permission-prompts to scan recent transcripts and propose an allowlist of routine tool calls (Bash patterns, MCP tools) that should auto-allow. Reduces friction in the first day of work.

Phase 6 — Save the briefing

• Write a memory note ~/.claude/projects/<slug>/memory/repo_briefing.md with the Phase 1-3 summary so future sessions in this repo bootstrap faster
• Update MEMORY.md index

Reconciliation

Single onboarding brief:

ONBOARDING — <repo> @ <branch>

Stack:           <languages, frameworks>
Layout:          <monorepo / single / workspace>
Build:           <command>
Test:            <command, framework>
Entry points:    <list>

Health (audit-deep):
  Tests:         X (target Y-Z)
  Coverage:      X% (threshold Y%)
  Security:      <N findings>
  Hooks:         <state>

Gate conflicts (config-drift):
  CRITICAL: <list>
  HIGH:     <list>

CLAUDE.md:       <created / present / patched>
Permissions:     <X auto-allows proposed>

Recommended first move:
  <specific action with skill suggestion>

Outputs / Evidence

• Onboarding brief (1 page)
• Memory file repo_briefing.md for next-session pickup
• Optional new CLAUDE.md staged
• Optional permission allowlist staged

Failure / Stop Conditions

• Repo is not a git repo → minimal brief, recommend git init first
• Repo build fails on Phase 1 detection → mark as PARTIAL, surface the build error for fix before continuing
• Never make changes (commits, file edits) without explicit user OK — onboarding is read-only by default

Memory Hooks

• Read existing repo memory if present (skip Phase 1 if briefing exists and is recent)
• Write the briefing as the primary output