onboarding

name	onboarding
description	Analyze a repository `AGENTS.md` before broader work begins and improve it only when the user gives explicit approval. Use when the user wants a first-pass review of repo instructions, wants to tighten `AGENTS.md` quality, or needs a compact operating-rules and source-of-truth map for future agent turns.

onboarding

Trigger context

• the user wants an explicit first-turn onboarding pass for a repository
• AGENTS.md exists but may be too thin, stale, or missing key guidance
• the user asks to review, critique, or improve repo-level agent instructions
• Delano has just been introduced and AGENTS.md should be checked before deeper work starts

Required inputs

• repo-root AGENTS.md
• directly relevant source-of-truth docs referenced by AGENTS.md
• explicit user approval before analyzing AGENTS.md
• separate explicit user approval before editing AGENTS.md

Output schema

• concise gap analysis against references/agents-md-best-practices.md
• keep/add/remove recommendations tied to the repo's actual workflow
• if edit approval is given, an updated AGENTS.md that stays compact and retrieval-oriented
• explicit note when analysis or edits were skipped because approval was not given

Quality checks

• do not analyze AGENTS.md until the user explicitly approves the review
• do not edit AGENTS.md until the user explicitly approves changes
• preserve repo-specific truth instead of pasting generic boilerplate
• keep AGENTS.md compact and point to deeper docs instead of duplicating them
• make approval boundaries, order of operations, and verification expectations explicit

Failure behavior

• if approval is missing, stop and ask plainly
• if AGENTS.md is absent, report that and propose only a minimal skeleton
• if source-of-truth docs disagree, surface the conflict instead of flattening it
• if the repo intentionally keeps AGENTS.md thin, prefer the minimum coherent improvement

Allowed side effects

• read AGENTS.md and directly relevant source-of-truth docs
• update AGENTS.md only after explicit edit approval
• add concise retrieval hints that point to canonical docs

Script hooks

• delano onboarding
• bash .agents/scripts/pm/validate.sh

Execution assets

• references/agents-md-best-practices.md