update-agent-onboarding

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.

1. 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).
2. 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?
3. 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.

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. Validate. Run create-agent-onboarding's Phase 7 gate (files, import line, size budget, command resolution, pointer == HEAD) before reporting done.