update-agent-onboarding

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 runtime dependency. Claude repo hooks and optional

native Codex plugin hooks can nudge; when unavailable, disabled, untrusted, or using

copied standalone skills, run this skill manually after meaningful commits.

Managed refresh

For an existing Claude installation, before classification compare the current

plugin's templates/hooks/drift-check and templates/tools/classify-drift with

their managed copies. If either is missing or differs, replace only those two

AIBoarding-owned files, then rerun classification. Do not rewrite config, state,

AGENTS.md, or CLAUDE.md. If current plugin assets cannot be located, route to

full revalidation. Repeating this refresh is byte-identical and rollback is safe:

older readers ignore the optional config and receipt fields.

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. Classify before reading semantics. Run the self-contained sibling

classify-drift --project <repo> --base <last_synced_commit> --head HEAD (or

.aiboarding/tools/classify-drift if installed). Missing tool, invalid pointer,

malformed report, rebased pointer, or changed HEAD means full revalidation;

never advance state from those outcomes. Its routes are unambiguous:

irrelevant advances state only; semantic-review needs section evidence;

mandatory-revalidation requires applicable section revalidation; and

invalid-pointer requires all nine sections. High-risk evidence always wins over

ignored paths and cannot be downgraded by a semantic no-op.

1. Classify scope impact for every potentially relevant path 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?

Record each potential path's applicable sections and rationale. Only complete

evidence covering every potential path can authorize --semantic complete-no-op.

Semantic review may escalate scope, never hide deterministic high-risk evidence.

1. Branch: classifier irrelevant, or complete evidenced potential no-op → No-op.

Mandatory route → Targeted-delta revalidation. Other routes → full revalidation.

No-op: nothing relevant changed

If triage finds no scope-relevant change:

• Build a drift-classification evidence record from the classifier report: repository

identity, exact base/head, final disposition, categorized path dispositions,

reviewed sections, and outcome (proven-irrelevant or

revalidated-no-content-change). Write it with .aiboarding/tools/write-evidence.

Do not copy command output or prose into the record.

• Recheck git rev-parse HEAD equals the evidenced head_commit; only then set

last_synced_commit and last_drift_classification together. An evidence write

failure or changed HEAD leaves state unchanged. Preserve unknown top-level state

fields.

• 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 <range>; 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.

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

1. Compress. Follow the compress-onboarding skill on the re-drafted sections

only (same level as the rest of the doc; it owns high-consequence preservation

and any per-region opt-in), verifying with .aiboarding/tools/check-preservation.

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

1. Advance state. After approved content work, persist the matching

drift-classification and onboarding-validation evidence records first, with the

exact base/head, affected sections, path dispositions, and validator identities.

Recheck HEAD against the evidenced head immediately before writing the pointer

and classification receipt together. Evidence failure or a changed head leaves

state unchanged; preserve unknown fields, then append the legacy compression receipt.

1. Validate. Run create-agent-onboarding's Phase 7 gate (files, import line,

local size sensor, Codex project-chain validation, command resolution, pointer ==

HEAD) before reporting done.

When a state-owning create or update flow invokes audit-onboarding-evidence, import

only its machine-readable computed findings as validator provenance in the matching

record. The standalone audit-agent-onboarding workflow remains read-only and never

creates evidence history.