swingerman/engineer/onboard

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)
• Manifest exists, no `verify_app` → run Step 10b only (generate + proof-run the verify skill); CP7 is blocked until it exists

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. Capture what actually ships, not a prose summary: read the real deploy config (deploy.yaml, the CI release job) and record the precise model — which artifact ships on which trigger (e.g. "ships master's latest build regardless of the release tag"). An inaccurate deploy summary once nearly shipped untested hotfix code. If the project has no staging, also record a safe-deploy recipe in manifest.validation.prod: verify the exact artifact/commit that will ship before shipping (cherry-pick or build-and-inspect) — there's no staging to catch a wrong artifact.
• 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:

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: