Lifecycle manager for AI configs.

From evidence-grounded setup to continuous upkeep

Generating a CLAUDE.md is well-covered in 2026 — Claude Code's /init, Copilot, Codex, Cursor, and several web tools all do it. onboard's focus is the step after: grounding the configs in verified research, and keeping them aligned as your code grows.

The first run does not cold-prompt you. A read-only analyzer scans the codebase, a research engine fans out specialists and adversarially verifies their claims, and the wizard asks you to confirm or override what the research already inferred. Nothing is written until you approve a full preview. After that, the drift loop takes over.

A grounded, research-first first run

/onboard:start is the main entry point. Instead of a cold questionnaire, it recons the code, researches it, and lets you confirm what the research inferred — behind a hard write gate.

Recon runs the codebase-analyzer agent (read-only, script-free — native Glob/Grep/Read plus git one-liners) to detect languages, frameworks, testing, CI/CD, and structure; its output stays in context, never on disk. Deep Research (onboard:research) fans out specialists per dimension, adversarially verifies their claims, and synthesizes a research dossier plus four artifacts — research-dossier, architecture, risk-register, and glossary. The grounded wizard then surfaces research.wizardInferences for you to confirm or override — autonomy level is always asked cold, never inferred. An empty-repo guard offers a 3-option menu (abort / placeholder / canonical stub) before any of this runs.

The drift-detection loop

/onboard:evolve is the heart of the lifecycle. When /onboard:start runs in enriched mode it installs auto-evolution hooks that quietly track change, and evolve drains them into targeted, approve-by-item updates.

FileChanged hooks on package.json, tsconfig.json, pyproject.toml, lockfiles, and structural anchors log diffs to .claude/greenfield-drift.json; a SessionStart hook summarises pending drift at the start of each session. Then /onboard:evolve reads that log, compares against the original snapshot, categorises the change (new dependencies, structural shifts, config diffs, missing hooks, stale rules), and proposes updates. You decide which to apply; the snapshot then updates so the next run is incremental.

The seven-phase start pipeline

/onboard:start runs a fixed, model-before-markup pipeline. Nothing is written to disk until Phase 5's hard gate is approved. Click a phase for detail.

The work is split across components: the codebase-analyzer agent recons read-only; the research engine grounds the wizard with verified claims; the wizard is the confirm/override surface; the config-generator agent takes the combined v3 context (recon + research + wizard) and writes every artifact.

Ten skills, five agents

The six user-facing skills use the /onboard:<name> slash syntax. Read-only helpers can auto-invoke; the three destructive entry points — start, update, and adopt — require explicit invocation; the four internal steps are hidden from the menu entirely.

Three agents do the heavy lifting: the codebase-analyzer (read-only recon), the config-generator (writes all artifacts from the v3 context), and the feature-evaluator (independent feature testing, spawned by verify).

Three research profiles

During start you pick a profile. It sets how deep the research goes and how much tooling is generated — there is no Custom path.

Autonomy level is a separate, always-cold question — never inferred from the codebase. It decides whether Claude only suggests (always ask), runs a balanced set of auto-format + advisory-lint + blocking pre-commit gates, or fully enforces them (autonomous).

What it generates

Generation has two tiers. Core artifacts are always produced; Enriched artifacts are added only when the wizard enables them. Every file carries a self-maintaining version + date header.

Supported project types & prerequisites

onboard handles single-language, mixed-language, and monorepo projects across the common stacks. Recon itself is script-free; only the evolution and CI-audit scripts need bash.

A run, then drift two weeks later

/onboard:start on an existing Next.js 15 project, then /onboard:evolve two weeks later detecting drift after the team added Playwright and extracted a workspace.

> /onboard:start

Phase 1: Recon
━━━━━━━━━━━━━━
Scanning codebase… (script-free — native search + git)

  Languages    TypeScript (94%), CSS (6%)
  Framework    Next.js 15 (App Router)
  Testing      Vitest + React Testing Library
  CI/CD        GitHub Actions (1 workflow)
  Size         48 files, 3,200 LOC

Phase 2: Research — profile select
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  (a) Minimal   (b) Standard  ← recommended   (c) Comprehensive
> b

Fanning out specialists → verifying → synthesizing dossier…
  Wrote research-dossier, architecture, risk-register, glossary

Phase 3: Grounded Wizard
━━━━━━━━━━━━━━━━━━━━━━━━
From the research I inferred — confirm or override:
  Testing philosophy   TDD   (vitest + RTL, co-located)   > confirm
  Autonomy level?  (asked cold)  > b (Balanced)

Phase 5: Preview & Gate
━━━━━━━━━━━━━━━━━━━━━━━
  research: 3 risks, architecture map, glossary
  + 12 files (CLAUDE.md, 3 rules, 1 skill, 1 agent, settings.json, …)
  Approve & generate?  [Approve / Adjust / Cancel]   > Approve

Phase 6: Generation → 12 artifacts written
Phase 7: Handoff → "Your project is set up. Try /onboard:check anytime."

# ── two weeks later — team added Playwright + extracted packages/shared ──

> /onboard:evolve

Drift detected:
  + new dependency     @playwright/test in apps/web
  + structural change  packages/shared workspace appeared
  ~ tsconfig changes   paths added for @repo/shared

Proposed updates:
  • Add rule        testing/e2e-conventions.md (Playwright)
  • Update CLAUDE.md → mark monorepo, document workspace boundaries
Apply all? [Y/n]  > Y

Snapshot updated. AI configs realigned to current code.