auto-onboard

name	auto-onboard
description	Build project truth from repo evidence. Use when steering is missing or stale.
metadata	{"stage":"utility"}

auto-onboard

Repository discovery. Builds bounded project truth from evidence, not guessing.

First action: run node .agent/.automaton/scripts/get-context.mjs from the project root.

Preamble

auto-onboard builds bounded project truth from repository evidence, not training data, not conversation, not guessing. It does not write code or produce specs. Loading discipline: keep REPO-MAP.md under 150 lines; stop scanning once you have enough.

Quality Gate

Before writing steering artifacts:

• Separate observed, inferred, and unknown facts.
• Cite paths for repo-shape claims.
• Treat artifact writing as expensive: write only durable project truth and immediate blockers, not scratch notes.
• Stop scanning once the next action is clear.
• Read references/quality.md when artifacts turn into broad inventory.

Do

Detect State

Choose the smallest valid path:

• First-time or scaffold-level steering: scan and write the starter artifacts.
• Real steering, no refresh requested: do not rewrite; report what exists and route active work to auto-resume, otherwise auto-office-hours.
• Targeted refresh: read only evidence relevant to the requested steering update and rewrite only affected artifacts.

ROADMAP.md stays restrained. Do not create roadmap phases on a first run. On refresh, write phases only when strong repo evidence shows an existing or ongoing roadmap and the user confirms importing or refreshing it in chat; then use .agent/.automaton/references/ROADMAP-CONTRACT.md.

Scan Top-Level Files

Read README.md, package.json or equivalent, and up to 3 config files (e.g., .gitignore, tsconfig.json, Makefile). Stop at 5 files for this step. The overall scan budget lives in Rules.

Map Topology

Read references/topology-scan.md for the scan protocol. Identify:

• Runtime surfaces (CLI, API, UI, worker)
• Package boundaries (apps, packages, modules)
• Stack (language, framework, build tool, test runner)
• Commands that work today (install, build, test, lint)

Ask (if necessary)

Ask only when ambiguity changes steering output. Read references/question-patterns.md; if one targeted repo read can answer it, read instead. For ROADMAP.md, never ask on first-time onboarding; on refresh, ask only when strong roadmap evidence exists but confirmation is missing.

Write Artifacts

Apply references/artifact-contract.md for exact format and required sections. Use templates/ as scaffolds:

• .agent/wiki/REPO-MAP.md: bounded evidence index; no open-question parking, confidence verdict, or recommended next skill
• .agent/steering/PROJECT.md: compact identity record; what this repo owns and why
• .agent/steering/REQUIREMENTS.md: durable constraints only; no generic unknown parking
• .agent/steering/ROADMAP.md: compact placeholder on first run; refresher-only phase updates when strong roadmap evidence exists and the user confirms in chat

Update State

Do not overwrite an existing active_change or stage. current.json is initialized by install/scaffold when missing; auto-onboard writes steering truth, not active-change state.

Report

Summarize what you found, what you wrote, and what remains uncertain.

Do NOT proceed past scanning if:

• The repository has no README.md, no package.json equivalent, and no recognizable directory structure after reading 10 files.
• Real (non-scaffold) steering exists and the user has not confirmed whether to overwrite it. Scaffold-level steering proceeds without confirmation per Detect State.

If the repo is empty or unrecognizable, report this and stop.

Halt and report when:

• A required file (README.md, root config) exists but cannot be parsed.
• The repository contains multiple projects at the same level and you cannot determine which is primary.
• The scan reveals conflicting conventions (e.g., both npm and poetry in the same root) and the user cannot clarify.

Do not guess. Do not proceed.

Output

• Steering artifacts: .agent/wiki/REPO-MAP.md, .agent/steering/PROJECT.md, .agent/steering/REQUIREMENTS.md, .agent/steering/ROADMAP.md
• .agent/.automaton/state/current.json is initialized by install/scaffold when missing; auto-onboard does not overwrite an existing active_change or stage
• Warning-level findings surface to the steering artifacts.
• Orient and stop (utility skill): Next: auto-office-hours (scale or shape undefined) or Next: auto-frame (bounded goal in hand). The user picks the direction.

Rules

• Default scan budget: 10 files. Summarize, do not transcribe. Extend in small increments only while runtime surfaces, package boundaries, stack, or working commands remain unidentified, and name the overrun reason in the report.
• Cite a file path for every steering claim.
• Delete empty template sections; templates are prompts, not required headings.
• Keep durable artifacts free of speculative questions, verdict-style confidence sections, and routing chatter. The Observed, Inferred, and Needs Confirmation split from the artifact contract is required, not banned.
• Never create roadmap phases on first-time onboarding. On refresh, change roadmap phases only when evidence and user confirmation justify it.