onboard

name	onboard
description	Use to bring a project into the DAE methodology, or to check an onboarded project for gaps. Triggers — "/engineer.onboard", "onboard this project", "set up DAE here", "adopt the methodology", or when a DAE skill fails because no manifest exists.

onboard

Checkpoint 0 — the DAE adoption ceremony. Establishes the charter, manifest, storage layout, and tracker. Project-scope, run once. Every other DAE skill depends on what it produces.

The goal. Onboarding a project to DAE succeeds when there is a clear path to full ATDD coverage of every feature — existing and new. A new feature is born covered by going through the pipeline. An existing feature is covered retroactively.

Onboarding is discovery and goal-setting — not the ATDD adoption itself. It discovers what's there (documented and undocumented), triages it by importance, assigns each feature a status, and produces a consolidation backlog. Bringing any one feature to full ATDD coverage is a follow-up task per feature — bounded, automatable, and a good candidate for remote-agent dispatch. Onboarding sets the path; it does not walk it.

A feature is fully ATDD-covered when its folder has feature.md, acs.md, spec.md (+ .build/spec.json IR), and generated acceptance tests that pass against the code.

When to use

• No .engineer/manifest.yml → full onboard (Steps 1–11)
• Manifest exists → gap-check mode (validate, report gaps, don't re-onboard)

Not for: starting a feature (discuss / feature-init, after onboard); changing an existing charter (edit it directly, PR'd).

Human-decision checkpoints

Onboarding is a ceremony, not a mechanical scaffold. Three of its outputs are design decisions reserved for the human — the agent drafts, the human decides:

• The charter (Step 3) — architecture, conventions, scope, quality and autonomy stance.
• The tracking decision (Step 5) — which tracker the project uses.
• The roadmap decision (Step 5b) — which platform hosts the strategic roadmap, and (if one already exists) how it's migrated in. Strategy is a human call, like the charter.

Pre-filling from an existing codebase is encouraged. Rubber-stamping is not. Onboarding does NOT complete until the human has explicitly signed off on the charter and chosen the tracker and roadmap host — exactly as plan does for architecture (agent proposes, human confirms before proceeding). If the human is not available to decide, stop and emit a handoff with human_action_needed: decision — do not auto-decide and move on.

Workflow (full onboard)

Before the steps below, create one TodoWrite todo per workflow step (the full list up front, as a roadmap) — see ${CLAUDE_PLUGIN_ROOT}/references/progress-indicator.md, Indicator 2. onboard is project-scope and has no feature folder, so it does not show the pipeline breadcrumb.

1. Repo topology — ask single- vs multi-repo. Set methodology_root (and repos[] for multi-repo).
2. Discover validation infrastructure. Before drafting the charter, probe what's available — the findings inform the autonomy stance.

   • LSP probe. Walk the repo for language signals (file extensions; package files: requirements.txt, pyproject.toml, package.json, Cargo.toml, go.mod, pom.xml, *.csproj, …). Aggregate primary languages. Inspect the agent's available tool list for an LSP capability (per ${CLAUDE_PLUGIN_ROOT}/references/code-lookup.md). Report per-language: LSP backing reachable? For absent ones, suggest the standard install (pyright, gopls, typescript-language-server, rust-analyzer, etc.). Inform-only — never blocks. Record the per-language map in manifest.validation.lsp.servers (languages the user skips are omitted; the fallback ladder handles them).

   • CLI probe. Walk the repo for tooling signals → likely CLIs (gh, aws, gcloud, az, kubectl, helm, terraform, docker, …) per ${CLAUDE_PLUGIN_ROOT}/references/cli-probe.md. which-check each candidate. Report two lists: available (found on PATH) and suggested (project signals indicate it'd be useful but it's missing — surface the install command from the reference). Record both in manifest.validation.clis.{available, suggested}. Inform-only — never blocks; the human installs. Don't suggest CLIs without project signals (no aws smell → don't ask about aws). The CLI probe runs before the environments interview because the available CLIs can help with that next step.

   • Environments interview (all optional, batched in one AskUserQuestion): staging URL + deploy process; prod URL + deploy process + monitoring dashboards + alerting; feature-flag tool (launchdarkly | unleash | flagsmith | growthbook | other) + rollout policy. Record in manifest.validation.{staging, prod, feature_flags}. "Not yet" / "n/a" is a valid answer that omits the field. Where a relevant CLI from the probe is available, the agent should ask (consent-gated) whether to use it to discover or confirm env info — gh for deploy workflows, gcloud for GCP envs, kubectl for namespaces, etc. — rather than asking the human to type everything.

   • Remote-agent readiness. Probe whether the project can delegate checkpoints to cloud Claude agents (vs. local subagents only):

     • Automatable signals: git remote get-url origin — is the repo on a clonable host (github.com / a connected GHES)? Scan the repo's .mcp.json for type: stdio servers — a project-wide cloud blocker (stdio MCPs don't exist in the cloud VM), so flag it. These mirror the per-feature dae_delegable.py gate.
     • Human one-time setup (DAE cannot automate this — surface it as a checklist the human confirms once): connect GitHub to claude.ai (/web-setup); create a cloud environment at claude.ai/code. Optional: install the Claude GitHub App on the repo (for PR/webhook triggers); create a routine (for RemoteTrigger-fired async/scheduled work — there is no create API, only the claude.ai UI).
     • Record manifest.remote: ready: <true|false> (human confirms the one-time setup is done), channel: <isolation-remote | routine | none> (primary cloud vehicle; default isolation-remote — it needs no pre-created routine), stdio_mcp_blocker: <true|false>, and free-text notes. Inform-only — never blocks onboarding; when ready is false the dispatch router simply stays local (see references/handoff-dispatch.md).

   • Autonomy proposal for Step 3's charter draft, based on what was found:

     • staging + monitoring + feature flags → "high autonomy is well-supported by the validation infrastructure"
     • staging + monitoring, no feature flags → "medium-to-high; pre-declare rollout paths in plans"
     • staging only, no monitoring → "medium; add monitoring to expand the ceiling"
     • none of the above → "low-to-medium until validation surface grows; recommend setting up staging + monitoring as an upstream backlog item"

     The proposal is a recommendation — the human signs off (or overrides) at Step 3.

   • Probe for project infrastructure. Before drafting the manifest, scan the repo for declarable infra dependencies and propose entries the human can accept/edit:

     Signal in repo	Suggested infra entry
     firebase.json present	One entry per emulator group (firebase emulators:start --only <group>), health probe on the documented port (auth: 9099, firestore: 8080, functions: 5001)
     docker-compose.yml / compose.yml	One entry per published service, health probe on the published port
     package.json scripts matching dev*, start:dev, emulator*, serve*	Entry using npm run <script>, with health probe on the documented port
     Makefile targets matching dev, up, start-*, emulator*	Entry using make <target>
     chromedriver-related deps in package.json / requirements.txt / Gemfile	Entry for chromedriver with TCP probe on 9515

     Present each draft entry to the human for confirmation, then add the approved entries to the manifest's infra: section per the schema (see engineer/references/handoff-dispatch.md + the schema in engineer/scripts/dae_resolve.py:_validate_infra).

     Discovery is best-effort. If a project's infra doesn't fit the patterns above, ask the human to declare it manually — the declaration discipline is what makes downstream skills reliable.

   • Capture infra quirks. After the infra entries are confirmed, batch one AskUserQuestion covering project-level runtime quirks that downstream skills need to know but can't discover from files:

     Quirk	Why it matters
     runtime_pins (e.g. java: 21, node: 20.x)	Wrong version → silent runtime failures (nexthq: Java 21 was rediscovered every session).
     port_map_file (path or "none")	If the user keeps a port-allocation file (e.g. ~/.<project>-ports.md), record its path so fix/atdd consult it before booting (nexthq).
     framework_constraints (free-text list)	Things like "Flutter web has no hot-reload", "Apache opcache requires cold restart after schema changes" — surface to the agent before it loops on confusing symptoms (mmc Apache, nexthq Flutter).
     recovery_commands (map of symptom: command)	Known fixes for known hangs (e.g. coresimulator_wedged: killall -9 com.apple.CoreSimulator.CoreSimulatorService).

     Write the answers into manifest.infra_quirks — a project-level block consulted by engineer:fix Step 4, atdd:atdd test runs, and engineer:onboard gap-check. dae_resolve.py validates schema. Quirks are advisory metadata, not health probes — they exist so the next agent doesn't rediscover the same friction.

3. Draft the charter, get sign-off — draft CHARTER.md's 7 mandatory sections (methodology, architecture, conventions, scope, agent team, quality stance, autonomy stance). For an existing codebase, pre-fill what's inferable from the repo. Then present it and get the human's explicit confirmation — section by section for the judgment-heavy ones (scope, quality stance, autonomy stance + path overrides). Do not proceed to Step 4 until the charter is signed off.
4. Create the manifest — fill .engineer/manifest.yml (paths, roadmap/tracker, team, repos, quality thresholds, mutation, verification, autonomy, remote, agentic_summary). Optional introversion: block tunes the harden-time vacuous-test scan (backend: = a test-introversion analyzer command like deintroverter; skip: true to opt out) — see engineer/scripts/dae_introvert.py.
5. Tracking decision — this is a human decision, not an agent default. Surface what the project appears to use (e.g. a repo full of Notion links → Notion) and ask the human to choose: notion | github-projects | linear | jira | local. notion: requires a connected Notion MCP — use it to create the tracker database (the TrackedFeature schema) or validate an existing one; DAE stores no API key (the MCP owns auth). local: feature folders are the tracker. Others: reserved — emit "not yet implemented". Never silently default to local to keep things moving. When creating or validating the schema, include a Type column (bug | idea | task, optional) and an Inbox value in the status options, and tell the human the capture flow: add a task directly to the tracker as a row with no Slug (and optionally Status: Inbox) and next will triage it — see Tracker-as-intake in references/tracker.md. See references/tracker.md. 5b. Roadmap decision — the strategic feature-list altitude, chosen independently of the tracker (see references/roadmap.md). A human design decision.
   • Reachability precondition first. A roadmap is onboardable only if DAE can reach its host programmatically — a connected MCP, an installed CLI, or a usable API (reuse the Step 2 CLI/MCP probe results). A manual-only host cannot be onboarded: record roadmap.type: none and tell the human exactly what to connect to enable it later. No half-support.
   • Choose & record the host — surface what the repo appears to use, then ask the human to pick roadmap.type: local | notion | confluence | gdoc | github-projects | other | none. local (a managed block in .engineer/roadmap.md) is always reachable and the greenfield default — don't force a host prompt on an empty project. notion needs the Notion MCP. confluence | gdoc | github-projects are onboardable iff their MCP/CLI is present (else none). other requires platform: + url: + access: mcp|cli|api in the manifest. Write the chosen block to manifest.roadmap.
   • Then link / migrate / create (see Migration in references/roadmap.md):
     • Discover roadmap-shaped sources read-only — ROADMAP.md / docs/roadmap.md / a ## Roadmap README section; a Notion page or DB named "Roadmap"; GitHub milestones / Projects / epic-labelled issues; an existing manifest.roadmap ref.
     • Link if a source is already in DAE shape on the chosen host. Migrate if a source exists elsewhere/in another shape — parse it into RoadmapItems (human confirms/edits), write to the chosen host; cross-host is fine; join items to discovered features so shipped/in-progress work back-links its feature_slug instead of re-listing as "planned"; leave the source in place as migrated_from (never delete). Create (seed from the Step 8 triage) if nothing is found — for local, dae_roadmap.py init then upsert the seeds.
6. Bootstrap layout — create features/, empty .engineer/discussions.log; ensure .build/ is gitignored.
7. Discover features — walk the repo (read-only) for every feature-shaped chunk, documented and undocumented:
   • Documented — Speckit specs/NNN-slug/, feature branches, docs/specs/*.md, GitHub Issues used as specs, informal README specs.
   • Undocumented — feature-shaped code with no spec at all: scan the packages/modules for coherent capabilities (a route group, a service, a UI surface) that no document covers. For each, record: source (or "code-only"), slug, state (spec-only / in-progress / shipped / merged), code co-locations (which packages/dirs the code lives in), and current DAE coverage (which of feature.md / acs.md / spec.md / acceptance tests exist — usually none). Greenfield project → discovery is empty; skip to Step 11.
8. Triage — with the human, rank the discovered features by importance to the project, and assign each a status (done shipped / in-progress / ready spec-only / parked dormant). Triage order drives the consolidation backlog's priority and which features get formalized first. Importance is a human judgement — surface a proposed ranking, let the human reorder.
9. Write the consolidation backlog + seed the tracker — two views of the triaged inventory:
   • .engineer/consolidation.md: the inventory as a coverage table (one row per feature, a column per coverage artifact) plus consolidation tasks in triage-priority order. Goal stated at the top: every row all-✅. Each task — "bring feature X to full ATDD coverage" — is bounded and dispatchable to a remote agent; note the suggested execution mode per task.
   • Seed the tracker — upsert a TrackedFeature row for every discovered feature (driver per references/tracker.md), not just the formalized ones, so the tracker shows the whole consolidation effort at a glance from day one. status from triage; checkpoint blank for features not yet in the DAE pipeline (consolidation.md tracks their coverage until they enter it).
10. Formalize the starting features — with the human, pick the 1–2 highest-triage features and run feature-init (onboarding-intake mode) on each now, so the project leaves onboarding with momentum. The rest stay as backlog tasks — do NOT formalize all of them in one onboard run.
11. Handoff — emit a summary; recommended_next points at the top consolidation-backlog task.

Migration is not done inside onboard. Moving specs/NNN-slug/ → features/NNN-slug/, backfilling acs.md/spec.md, and generating acceptance tests are consolidation tasks — worked down feature by feature after onboarding, via the pipeline (feature-init → discover-acs reverse-engineer mode → atdd:atdd → pipeline generation), and dispatchable to remote agents. onboard only discovers, triages, and plans.

Gap-check mode

Manifest exists → don't re-onboard. Validate: CHARTER.md has all 7 sections; manifest.yml schema-valid; features/ numbering monotonic; tracker config resolves; roadmap config resolves and its host is still reachable (MCP/CLI/API present; if it went unreachable, flag it — next will be running blind to the roadmap); charter roles == manifest.team.default_roles. If a new external roadmap source has appeared since onboarding (e.g. a ROADMAP.md was added), surface it as a re-migration offer rather than acting. Report gaps with suggested fixes (mirrors consistency-check --project).

Strictly read-only. Forbidden:

• git checkout, git pull, git fetch, git merge, git rebase, git branch -d/-D — no git state mutations of any kind.
• git stash — even apparently-safe stashing changes working-tree state.
• Writing, editing, or deleting any file outside /tmp (no charter edits, no .engineer/ writes, no feature-folder touches).

If gap-check would benefit from a sync (e.g. the user is on a feature branch with merged remote), surface the suggestion in the report and stop. The caller invokes /engineer.post-merge or the manual git commands themselves. Do not infer "the user wants a sync" from "the user typed /engineer.onboard".

Full-onboard precondition

Full-onboard mutates the repo: writes CHARTER.md, .engineer/, features/. It must start from a clean state:

• HEAD on main/master (or the repo's default branch — read from git symbolic-ref refs/remotes/origin/HEAD).
• Clean working tree (git status --porcelain empty).
• Either: no current branch is a feature branch with unpushed work, or the user explicitly confirms "onboard on this branch".

If those conditions don't hold, stop and surface the situation — never auto-checkout, never auto-stash. Suggested wording: "Onboarding writes new files into the repo root. You're on <branch> with <N> unpushed commits — confirm you want to onboard here, or switch to main yourself first."

Handoff

Emit per ${CLAUDE_PLUGIN_ROOT}/references/handoff-summary.md. onboard is project-scope — its handoff goes to .engineer/handoffs/ (no feature folder exists). checkpoint: 0; artifacts: CHARTER.md, .engineer/manifest.yml. recommended_next: "per feature, /engineer.prime-context then /engineer.discover-acs; new ideas, /engineer.discuss".

If onboarding stopped because the human wasn't available to sign off the charter or choose the tracker, emit status: interrupted with human_action_needed: decision — naming exactly which decisions are outstanding.

References

• Foundation Design — charter format (§3), manifest schema (§2), storage layout (§1)
• Discuss & Upstream Funnel — methodology_root, onboarding intake
• references/tracker.md — the tracker drivers, setup, the Notion mapping
• references/roadmap.md — the roadmap drivers, the reachability precondition, link/migrate/create
• Tracker Integration — the full contract
• engineer/scripts/dae_infra.py — what the manifest infra entries feed