// Build project truth from repo evidence. Use when steering is missing or stale.
| name | auto-onboard |
| description | Build project truth from repo evidence. Use when steering is missing or stale. |
| metadata | {"stage":"frame"} |
Repository discovery. Builds bounded project truth from evidence, not guessing.
First action: run scripts/get-context.mjs → JSON {activeChange, stage, canonicalSpec, canonicalDesign, canonicalPlan, productReview, engineeringReview, diagnostics} (missing state normalizes to "none"/null). If any diagnostic has level "error", stop and report it before proceeding.
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.
Before writing steering artifacts:
references/quality.md (~36 lines: anti-patterns, better shape, prose hygiene scan patterns) when artifacts turn into broad inventory.Three cases:
get-context.mjs returned no state or steering files are scaffold placeholders (e.g., "..." or template prompts). Proceed to scan..agent/steering/PROJECT.md contains real project truth and the user did not ask for a refresh. Report what exists and route by state:
auto-resumenone → auto-office-hourssync-status.mjs, and report what changed. Read additional files when needed to produce an accurate update.When handling ROADMAP.md during first-time setup, always keep the short placeholder. Do not create roadmap phases on a first run. On refresher runs, write roadmap phases only when strong repo evidence shows an existing or ongoing roadmap and the user confirms importing or refreshing it in chat; then use references/ROADMAP-CONTRACT.md (~63 lines: canonical phase format, status values, update rules by skill, matching rule, single-file invariant).
Read README.md, package.json or equivalent, and up to 3 config files (e.g., .gitignore, tsconfig.json, Makefile). Stop at 5 files.
Read references/topology-scan.md (~56 lines: 7-layer read order, budget rules, REPO-MAP.md output requirements) for the scan protocol. Identify:
If ambiguity affects the steering output, ask ≤ 3 questions. Read references/question-patterns.md (~39 lines: 4 good evidence→assumption→decision patterns, 3 anti-patterns) for how to ask. If the answer can be inferred from the repo with one more targeted read, do that instead.
For ROADMAP.md specifically: on first-time onboarding, do not ask and do not create phases. On refresher runs, if strong evidence of an ongoing roadmap exists but user confirmation is missing, ask whether to import/refresh it, leave the current roadmap alone, or route to auto-office-hours for a fresh decomposition. If there is no strong evidence, do not ask; keep the placeholder or existing roadmap unchanged.
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.agent/steering/STATUS.md: current state and next stepRun sync-status.mjs from this skill's scripts directory.
Summarize what you found, what you wrote, and what remains uncertain.
Do NOT proceed past scanning if:
README.md, no package.json equivalent, and no recognizable directory structure after reading 10 files.If the repo is empty or unrecognizable, report this and stop.
Halt and report when:
README.md, root config) exists but cannot be parsed.Do not guess. Do not proceed.
| Artifact | Location | Purpose |
|---|---|---|
| REPO-MAP.md | .agent/wiki/ | Bounded import record: surfaces, stack, boundaries, hotspots |
| PROJECT.md | .agent/steering/ | What this repo owns, why it exists, major surfaces |
| REQUIREMENTS.md | .agent/steering/ | Constraints, non-goals, risks, evidence anchors |
| ROADMAP.md | .agent/steering/ | High-signal placeholder on first run; refresher-only phases after strong roadmap evidence and chat confirmation |
| STATUS.md | .agent/steering/ | Current state, what is true now, next step |
.agent/.automaton/state/current.json initialized when missing; auto-onboard does not overwrite an existing active_change or stageerror-level diagnostics block the onboard; warning-level findings surface to the steering artifactsauto-office-hours (when scale or shape is undefined) or auto-frame (when the user already has a bounded goal). The user or host invokes the next skill; auto-onboard does not chain.Read references/topology-scan.md for runtime surfaces, package boundaries, stack conventions. (~56 lines: 7-layer read order from existing Automaton state through delivery surfaces, budget rules, REPO-MAP.md output requirements.)
Read references/artifact-contract.md for exact format and required sections. (~92 lines: progressive disclosure structure for 5 artifacts, writing standard, confidence model with Observed/Inferred/Needs Confirmation, per-artifact expectations and required sections.)
Read references/question-patterns.md for good and bad follow-up questions. (~39 lines: 4 good patterns with evidence→assumption→decision structure, 3 bad open-ended anti-patterns, escalation rule.)
Product go/no-go on a framed spec. Use after auto-frame, before planning.
Engineering go/no-go on a plan. Use after auto-plan, before execution.
Implement approved plan slices. Use as the execute-stage entry point.
Bound and de-risk a request into SPEC.md. Use when the objective is clear but scope needs constraining.
Sharpen a vague idea into a bounded objective. Use before framing when scope is undefined.
Turn an approved spec into ordered slices. Use when framing is accepted and planning begins.