Lifecycle manager for AI configs.
onboard analyzes a codebase with deep, verified research and generates evidence-grounded Claude tooling on day one — CLAUDE.md, path-scoped rules, skills, agents, hooks, a project .mcp.json, and a verify backlog. It offers companion LSP and MCP plugins by name and installs only the ones you accept. Then it detects code-vs-config drift as the project evolves and updates the tooling to match.
claude plugin install onboard@apurvbazari-pluginsThen run /onboard:start to launch the grounded, research-first guided workflow.
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. No tooling file is written until you approve a full preview; before that, only the research notes and the preview page exist. After that, the drift loop takes over — or, when an orchestrator drives the work, the maintain entry keeps tooling current after each change it lands.
Not just generation — alignment
The differentiator is the lifecycle: every generated artifact carries a self-maintaining header, and /onboard:evolve watches code-vs-config drift and brings the tooling back in line. Most drift is applied directly and shown as a diff; anything that installs a plugin waits for your answer.
CLAUDE.md, .claude/rules/, .claude/skills/, .claude/agents/, hook entries in .claude/settings.json, and its own state files under .claude/. /onboard:start previews every one and writes none until you approve.
Servers matched to your stack — context7 on every project, others (GitHub, Vercel, Supabase, Chrome DevTools) when the stack calls for them. Prisma's server ships inside the prisma plugin, so it gets no entry and is offered as a plugin. An existing .mcp.json is never overwritten.
LSP plugins, the plugins that go with those MCP servers, walkthrough and notify. The MCP-plugin rows start unchecked, a skipped question installs nothing, and the preview lists every plugin that will be installed.
Claude can start /onboard:evolve and /onboard:verify, and both write to your project. Neither installs a plugin without asking (§03, §06).
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. The wizard also offers plugins by name — LSP plugins, and the plugins that go with detected MCP servers, every MCP row unchecked — and only the ones you select are installed. 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 updates.
FileChanged hooks on package.json, tsconfig.json, pyproject.toml, lockfiles, and structural anchors log diffs to .claude/onboard-drift.json (a legacy greenfield-drift.json is still read, and evolve migrates it); 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), and applies the matching tooling updates. Most are applied without asking and shown as a diff afterwards; the snapshots then update so the next run is incremental.
What evolve applies, and what it asks
It applies most drift directly: CLAUDE.md, rules, hook scripts and settings.json entries, and newly relevant MCP servers in .mcp.json. It also removes tooling that no longer applies — rules for a package you removed, the CLAUDE.md of a deleted directory, hook scripts for an uninstalled plugin, generated files an installed plugin made redundant — and in CLAUDE.md it changes only the affected sections and keeps your own additions. It stops and asks before installing any plugin (including the one behind a new MCP server), adding a built-in-skill recommendation, or creating a new subdirectory CLAUDE.md; if nobody answers, none of those happen. A plugin you declined is not asked about again; on a project onboarded with 3.2.x or earlier, the plugins of existing servers count as already offered, so a plugin you removed is not reinstalled. For per-item approval of every change, use /onboard:update.
The maintain entry, for orchestrators
/onboard:evolve is the loop you drive. The maintain entry is the same upkeep for an orchestrator running a pipeline: after a change lands, it reports only the tooling drift that change's git range caused, writes the safe part, and hands back a result. No wizard, no prompts.
Two scripts and one internal skill make up the entry. maintain-detect.sh runs with no model in about a second; the orchestrator's own model then runs the onboard:maintain skill over its report, fenced by maintain-guard.sh. Callers find the scripts with claude plugin list --json (installPath, version ≥ 3.2.0). Click a step for detail.
Detect labels every item by a fixed per-kind table. Only one kind is ever written; everything else is a to-do or context.
| Label | What detect reports | What happens to it |
|---|---|---|
| apply | A new package.json script (script-added). | Written as one line in the nearest fitting commands section of a CLAUDE.md, in that section's own style — list, fenced block, table row or inline — then re-checked. A line detect cannot recognise is removed and deferred. |
| defer | Thirteen kinds: removed scripts or dependencies still named in tooling, backticked paths the diff deleted or renamed, broken rule paths: globs and hook scripts, new directories and languages, MCP and built-in-skill signals, config and non-JS manifest changes, stale research, an oversized lessons.md, and a project onboard never set up. | Copied into the result as a to-do with a command or hint. Nothing is written. |
| inform | A new dependency, and tooling lines that mention a changed path or dependency (recheck-line, ranked and capped at 8). | Context for the owner's lesson decisions. Never written, and never in the result. |
Lessons the owner approved arrive as a separate input and go into .claude/rules/lessons*.md or a marked section, verbatim. An exact repeat, by id or text, is skipped; a near-duplicate is deferred for a person, never merged.
Writes tooling, and only tooling
The apply step never prompts, never commits, and never rewrites or deletes an existing line. It writes only CLAUDE.md files, .claude/rules/ and its own result; the guard restores or reports anything else that changed during the run. .claude/ is a protected path Claude Code's own tools may not write unattended, so lesson and result entries go through maintain-write.sh. start, update, evolve, generate and the drift hooks are unchanged.
Written by maintain-detect.sh alone: the git range, the project, and every item with its kind and label — or an error object with a code.
Written by the caller: only lessons the owner approved, each with its text, an optional target, and evidence. Apply writes the text verbatim.
applied, deferred and skipped per item or lesson, plus filesWritten — what the caller stages for its tooling commit — and preDirty.
The eight-phase start pipeline
/onboard:start runs a fixed, model-before-markup pipeline. No tooling file is written, and none of the plugins on the preview's install line is installed, until Phase 5's hard gate is approved; before it, only the research notes and the preview page exist. 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.
Eleven skills, five agents
The six user-facing skills use the /onboard:<name> slash syntax. Claude can start check, which writes nothing, and verify and evolve, which write to your project; the three destructive entry points — start, update, and adopt — require explicit invocation; the five internal steps are hidden from the menu entirely.
| Skill | Invocation | What it does |
|---|---|---|
| /onboard:start | user-only | Main entry point — the grounded, research-first guided workflow: recon → research → wizard → preview gate → generation → handoff. Includes the empty-repo guard. |
| /onboard:update | user-only | Re-aligns tooling against onboard's bundled best-practice guides and offers each change for approval, preserving your manual customisations. It lists Claude Code features newer than those guides from the live docs as information only — that list never supplies what gets written. A plugin is installed only if you select its own row, and “Apply all” names the plugins it would install. A saved offer read back from .claude/onboard-pending-updates.json is dropped if its plugin is not in onboard's catalog. |
| /onboard:adopt | user-only | Retrofits hand-crafted tooling into an onboard baseline (mode:retrofit + snapshots) so update works — without modifying any hand-crafted file. Every adopted artifact is tracked origin:adopted. Installs nothing, so it offers no plugin. |
| /onboard:evolve | auto | The drift loop. Reads onboard-drift.json, compares against the snapshots, applies most updates directly and shows a diff, and asks before installing a plugin, adding a built-in-skill recommendation or creating a subdirectory CLAUDE.md (§03). |
| /onboard:verify | auto | Independent feature verification — spawns the feature-evaluator agent in worktree isolation to test features against docs/feature-list.json. Single-feature, sprint, or all-incomplete modes. Writes its results to docs/feature-list.json (passing only on a PASS), docs/progress.md and docs/verification-reports/. |
| /onboard:check | auto | Quick health check — last run date, generated artifacts, integrity status, and recommendations. Writes nothing. |
| /onboard:generate | Internal generation step invoked by start / update / evolve. Consumes the v3 context; mode:plan computes the manifest for the gate without writing, mode:write runs the full pipeline. | |
| research | The v3 research engine. Fans out one read-only specialist per dimension, adversarially verifies every claim against the codebase, then synthesizes the canonical research dossier the generation step consumes. Claims that cannot be proven are dropped, not softened. | |
| wizard | The adaptive Q&A flow that gathers developer preferences during start. A building block, never invoked on its own. | |
| generation | Shared generation building block backing generate — the artifact recipes the config-generator agent writes from. | |
| maintain | The apply step of the maintain entry (§04), run non-interactively by an orchestrator's model over a maintain-detect.sh report. Writes each new package.json script as one line in the nearest commands section of a CLAUDE.md, plus owner-approved lessons, and returns maintain-result.json. Never prompts, never commits. |
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). The research engine dispatches the other two: the research-specialist (a read-only deep-dive, one per research dimension) and the research-verifier (the adversarial skeptic that tries to refute each claim against the real code).
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.
| Profile | Research depth | Generation scope |
|---|---|---|
| Minimal | Shallow research | Core tooling only |
| Standard recommended | Balanced research | Balanced tooling |
| Comprehensive | Full research | Enriched tooling |
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.
- Root
CLAUDE.md— overview, tech stack, commands, conventions, critical rules. - Subdirectory
CLAUDE.mdfiles — context-specific guidance for major directories. .claude/rules/*.md— path-scoped rules for testing, APIs, components, security..claude/skills/+.claude/agents/— stack-specific skills and plugin-aware agents (skips capabilities an installed plugin already covers)..claude/output-styles/— a project-scoped output style tuned to archetype (onboarding / teaching / production-ops / research / solo).- Hook entries in
.claude/settings.json— auto-format and lint checks tailored to your tooling. .mcp.json— project MCP servers matched to your stack (an existing file is never overwritten).- PR template + commit conventions and
.claude/onboard-meta.json— the generation manifest.
- CI/CD pipelines — GitHub Actions: ci, tooling-audit, pr-review. The tooling audit flags a rule whose
paths:pattern matches no file, judged the way Claude Code matches it (gitignore semantics; a block list, flow list or comma-separated string), on macOS as on Linux. If the check cannot run becausepython3is missing or fails, it reports that as drift instead of passing. A project generated before onboard 3.2.1 keeps its own copy at.github/scripts/audit-tooling.sh; replace it with the current script to get this check. - Harness artifacts —
docs/progress.md,docs/HARNESS-GUIDE.md. - Auto-evolution hooks — FileChanged + SessionStart plus the drift-detection scripts that power
/onboard:evolve. - Sprint contracts —
docs/sprint-contracts/. - Agent team support — quality hooks and env vars.
Supported project types & prerequisites
onboard handles single-language, mixed-language, and monorepo projects across the common stacks. Recon itself is script-free; the evolution, CI-audit, and maintain scripts need bash, and the maintain scripts need python3 as well.
React, Next.js, Express, NestJS, and more.
Django, Flask, FastAPI, and more.
Go and Rust projects.
Java / Kotlin and Ruby on Rails.
npm / yarn / pnpm workspaces, Turborepo, Nx, Lerna.
Projects spanning several languages at once.
Evolution, CI-audit, and maintain scripts, and generated hooks. Ships on macOS and Linux.
Repository analysis and contributor detection.
Installs the plugins you accept.
The maintain entry's maintain-* scripts — standard library only.
Directory visualisation — falls back to find.
JSON parsing in hooks — generated hooks include a python3 fallback.
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)
Plugins that go with the MCP servers I'll add — install any? (all unchecked)
[ ] context7 [ ] chrome-devtools-mcp [ ] github
> (none)
Phase 5: Preview & Gate
━━━━━━━━━━━━━━━━━━━━━━━
research: 3 risks, architecture map, glossary
+ 12 files (CLAUDE.md, 3 rules, 1 skill, 1 agent, settings.json, .mcp.json, …)
MCP servers: context7, chrome-devtools-mcp, github
Plugins to install: none
Approve & generate? [Approve / Adjust / Cancel] > Approve
Phase 6: Generation → 12 artifacts written · plugins: none installed
Phase 7: Handoff → "Your project is set up. Try /onboard:check anytime."
# ── two weeks later — team added Playwright, Supabase and 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
+ new stack signal supabase/ directory → supabase MCP server
Updates applied:
• CLAUDE.md added @playwright/test, marked monorepo, documented workspace boundaries
• .claude/rules/typescript.md updated for the new paths
• .mcp.json added supabase server
One question:
New MCP server: supabase. Install the plugin that goes with it?
[ ] supabase
> (none)
Not applied (needs your input):
• New directory packages/shared — create a CLAUDE.md for it?
Snapshots updated.