onboard v3 — research-grounded onboarding
A design session that rearchitects the onboard plugin so understanding a repo is driven by a deep, parallel, adversarially-verified research phase — not a single-pass analyzer. Research runs first and deep: it collapses the wizard into a confirm/override surface, grounds richer generation, and emits four new foundational artifacts. The engine is portable-first on subagents (Workflow tool as a power-up), the roster is extensible, recon is script-free, and every artifact is a render of one model — markdown always, interactive HTML when the walkthrough plugin is present.
Why single-pass analysis falls short
Today onboard understands a repo in one pass: the codebase-analyzer agent runs three scripts and skims files into one flat report, which — with wizard answers — feeds generation.
A single context window can only skim a large repo, nobody cross-checks the analyzer's claims, and the 6-phase wizard then asks the developer questions the codebase could already answer. Plausible-but-wrong findings flow straight into the rules and CLAUDE.md the tool writes.
The core insight
The analysis is breadth-first and self-attested — one agent skims everything and grades its own work. The newer Claude Code primitives (the Workflow tool, parallel subagents, the deep-research fan-out then verify then synthesize pattern) are built precisely for deep, parallel, verified investigation.
Three altitudes, one chosen
All three share the same heart — a portable research panel. They differ in how much of onboard gets rearchitected around it. We designed to B.
A · Research Panel (bolt-on)
Add the panel beside today's pipeline; keep the wizard and the v2 context shape intact.
- Lower risk, ships fast (2.1)
- No reorder of the flow
- Research and wizard duplicate effort
- Wizard stays a cold interrogation
B · Research-Grounded v3
Reorder onboard around research: Recon then Research then Dossier then a grounded Wizard then Generation. v3 context shape, dual-backend engine, all four artifacts first-class.
- Wizard collapses to confirm/override
- Generation is evidence-grounded
- Four artifacts first-class
- Major redesign
- 3.0 version bump
C · Dual-Engine Platform
B plus a standalone /onboard:research, drift-aware re-research wired into evolve, and Workflow-native multi-vote verification as the default.
- Re-runnable and self-maintaining
- Deepest verification
- Largest scope
- Best as a follow-on to B
The research-grounded pipeline
Research runs first and deep, so everything downstream is grounded in evidence instead of asking the developer cold. Click a stage for detail.
The empty-repo guard still fires before research — a zero-source repo skips straight to the existing stub path, untouched.
Inside the research engine
One internal orchestrator, two interchangeable backends behind the same roster and verification logic. Specialist subagents each go deep on one dimension; an adversarial verifier refutes weak claims; a synthesizer merges what survives.
Portable by design
The Workflow tool is not guaranteed in every user's environment, so subagents are the default substrate. The engine detects the Workflow tool at runtime and uses it only as a power-up — deeper fan-out and multi-vote verification — degrading gracefully where it is absent.
A floor, not a fixed set
Teams add custom specialists (accessibility, i18n, a GraphQL-schema audit) and enable/disable built-ins via .claude/onboard-research.config.json. Custom findings follow the same schema, so they flow through the same verifier and synthesizer — extension never lowers the quality bar.
Depth is dialed by the existing presets, so the expensive part stays opt-in:
Essentially today's fast, cheap path — now script-free.
Core dimensions, single adversarial pass.
Whole roster + any custom specialists; Workflow multi-vote when available.
The choices that shaped it
Beyond picking approach B, nine decisions were ratified across the brainstorm.
✓ Scope — both, integrated (v3)›
✓ Portability — portable-first, optional power-up›
✓ Recon — script-free (native tools)›
analyze-structure / detect-stack / measure-complexity; recon uses native Glob/Grep/Read plus the odd inline git ls-files. Pure markdown+JSON, cross-platform, no shellcheck/path-bug surface. The generated target-repo drift hooks are unaffected.✓ Roster — extensible + tunable›
.claude/onboard-research.config.json. Custom findings follow the same schema and flow through the same verifier + synthesizer.✓ Artifacts — markdown + optional interactive HTML›
onboard-research.json also renders to self-contained interactive HTML via walkthrough:render, markdown fallback if absent. Mirrors the lens pattern.± Artifact location — ask per-run, no default›
docs/onboard/, local .claude/ only, or none. This overrode the recommended committed-by-default.✓ Verify backlog — seed feature-list.json›
docs/feature-list.json so findings become checkable items onboard:verify can act on — staying within the register's scope, no new subsystem.✓ Research depth — tied to existing presets›
✓ Context shape — v3 primary, v2 via adapter›
generate accepts v3 (primary) and v2 through an adapter (research-absent mode = today's behavior); v1 is still rejected. Keeps the internal contract migratable.Four new foundational artifacts
Human-readable docs plus one machine-readable companion — and every doc is a render of that one model. Location is chosen per run, but the research object always flows to the wizard and generation regardless.
Per-dimension findings, each with file:line evidence + confidence. The re-runnable evidence base.
Layers, entry points, persistence, external deps.
Fragile / under-tested / security hotspots — seeds the verify backlog.
Domain terms + ADRs seeded as proposed for the team to ratify.
What the wizard + generation actually read; the docs render from it.
One model, many renders
.claude/onboard-research.json is the single source of truth. Markdown stays canonical — diffable, committable, ADRs ratifiable. When the walkthrough plugin is present, the same model also renders to a self-contained interactive HTML (architecture → live diagram, risk register → filterable cards, findings → clickable evidence) via walkthrough:render; markdown-only if it is absent.
What changes in the plugin
A new research skill, two specialist agents, three schemas (incl. the custom-roster config), and the v3 context shape — plus reorders to the existing skills and the retirement of the three recon scripts. Writes are additive, so rollback is clean.
The marketplace entry (.claude-plugin/marketplace.json) bumps to 3.0.0 in lockstep. The retired recon scripts go script-free; the generated target-repo drift hooks (detect-*-changes.sh) are unaffected. Rollback = delete the additive docs/onboard/ + .claude/onboard-research.json and restore the existing CLAUDE.md.pre-onboard backup, or pin onboard@2.0.1 for the old single-pass flow.
What we deferred — the C roadmap
Three capabilities are explicitly out of scope for 3.0; each is a natural follow-on once the spine is proven.
/onboard:research decoupled from setup.onboard:evolve, so the dossier stays live.