| name | update-agent-onboarding |
| description | Use when commits have landed since the onboarding files were last synced (the drift-check hook nudges for this), or the user asks to refresh AGENTS.md. Triages whether the change touches onboarding scope and patches only the affected sections; on no-op it advances the state pointer only. |
Updating agent onboarding files
Keep AGENTS.md current as the project evolves, without re-grilling the whole repo.
Announce at start: "Using update-agent-onboarding to triage onboarding drift."
Runtime awareness
Works under Claude Code, Codex, Copilot CLI, or any SKILL.md-compatible agent - the
triage and patch logic below has no Claude Code dependency. Only the drift nudge
that usually leads here is a Claude Code hook; on other runtimes, run this skill
manually after meaningful commits.
Triage
Read last_synced_commit from .aiboarding/state.json (NOT from any instruction
file - the pointer lives only in the sidecar).
If state.json is missing or the pointer is missing/empty, the repo was never
properly synced or the state was lost (fresh clone of a repo where state was
gitignored, hand-edited state, or the drift hook fired as a repair signal). Do NOT
take the No-op branch - go straight to the Targeted-delta patch for a full
re-validation of all nine sections, then reseed state.json.
If the repo has AIBOARDING.md and no AGENTS.md, it is on the legacy layout:
stop and run migrate-aiboarding instead.
- Gather the delta. Run
git diff <last_synced_commit>..HEAD and
git diff --name-only <last_synced_commit>..HEAD. Drop paths matching
config.json:ignored_paths plus the always-ignored set (AGENTS.md,
CLAUDE.md, .aiboarding/*). Reflect on the current conversation - it is the
"chat log" and is already in your context (after compaction, use the summary).
- Classify scope impact against the
AGENTS.md sections:
Stack and Runtime / Build, Test, Run - stack, tooling, or commands changed?Architecture Map - boundaries, directories, data flow moved?Project Purpose / Domain Model - new concepts or changed behavior?Agent Guardrails / Known Failure Modes - new gotchas or constraints?Verification Before Completion / Escalation - done-criteria or stop-and-ask
cases changed?
- Branch: no relevant change → No-op (below). Relevant change → Targeted-delta patch.
No-op: nothing relevant changed
If triage finds no scope-relevant change:
- Set
last_synced_commit in .aiboarding/state.json to the current
git rev-parse HEAD.
- Hard invariant: do not touch
AGENTS.md or CLAUDE.md. Not even whitespace.
The pointer advance is a state-only write; this is what keeps the drift hook from
ever re-nudging on its own bookkeeping.
- Do not ask the user - this advance is automatic.
- Briefly report: "No onboarding-relevant changes in ; advanced sync pointer."
Targeted-delta patch: scope changed
Reuse create-agent-onboarding's Phases 1–3 (background crawl + grilling style,
architectural interrogation, reconciliation), scoped to the affected sections only.
- Scoped grill. Ask focused, one-at-a-time questions about ONLY the changed
scope, seeded by the diff. Skip sections the delta does not touch.
- Synthesize. Re-draft only the affected sections, using the exact H2 heading
text from the existing
AGENTS.md to avoid duplicate headings. Leave untouched
sections byte-for-byte intact. Keep commands/identifiers/paths backtick-quoted.
- Compress. Follow the
compress-onboarding skill on the re-drafted sections
only (same level as the rest of the doc; Guardrails/Escalation capped at lite),
verifying with .aiboarding/tools/check-preservation.
- Approval gate. Show the user a diff of the patched sections against the prior
AGENTS.md. Content changes ALWAYS require approval before writing. Only the
no-op pointer advance is automatic.
- Advance state. After the approved write, set
last_synced_commit to the
current git rev-parse HEAD in state.json and append the compression receipt.
- Validate. Run create-agent-onboarding's Phase 7 gate (files, import line,
size budget, command resolution, pointer == HEAD) before reporting done.
