| 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.
