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.
- 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.
- 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.
- 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 ; 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; it owns high-consequence preservation
and any per-region opt-in), 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 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.
- 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.
1---2name: update-agent-onboarding3description: 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.4metadata:5 source: https://skillmd.com/skills/hashgraph-online/update-agent-onboarding6---78# Updating agent onboarding files910Keep `AGENTS.md` current as the project evolves, without re-grilling the whole repo.1112**Announce at start:** "Using update-agent-onboarding to triage onboarding drift."1314## Runtime awareness15Works under Claude Code, Codex, Copilot CLI, or any SKILL.md-compatible agent - the16triage and patch logic below has no runtime dependency. Claude repo hooks and optional17native Codex plugin hooks can nudge; when unavailable, disabled, untrusted, or using18copied standalone skills, run this skill manually after meaningful commits.1920## Managed refresh21For an existing Claude installation, before classification compare the current22plugin's `templates/hooks/drift-check` and `templates/tools/classify-drift` with23their managed copies. If either is missing or differs, replace only those two24AIBoarding-owned files, then rerun classification. Do not rewrite config, state,25`AGENTS.md`, or `CLAUDE.md`. If current plugin assets cannot be located, route to26full revalidation. Repeating this refresh is byte-identical and rollback is safe:27older readers ignore the optional config and receipt fields.2829## Triage30Read `last_synced_commit` from `.aiboarding/state.json` (NOT from any instruction31file - the pointer lives only in the sidecar).3233**If `state.json` is missing or the pointer is missing/empty**, the repo was never34properly synced or the state was lost (fresh clone of a repo where state was35gitignored, hand-edited state, or the drift hook fired as a repair signal). Do NOT36take the No-op branch - go straight to the Targeted-delta patch for a full37re-validation of all nine sections, then reseed `state.json`.3839**If the repo has `AIBOARDING.md` and no `AGENTS.md`**, it is on the legacy layout:40stop and run `migrate-aiboarding` instead.41421. **Classify before reading semantics.** Run the self-contained sibling43 `classify-drift --project <repo> --base <last_synced_commit> --head HEAD` (or44 `.aiboarding/tools/classify-drift` if installed). Missing tool, invalid pointer,45 malformed report, rebased pointer, or changed `HEAD` means full revalidation;46 never advance state from those outcomes. Its routes are unambiguous:47 `irrelevant` advances state only; `semantic-review` needs section evidence;48 `mandatory-revalidation` requires applicable section revalidation; and49 `invalid-pointer` requires all nine sections. High-risk evidence always wins over50 ignored paths and cannot be downgraded by a semantic no-op.512. **Classify scope impact** for every potentially relevant path against the52 `AGENTS.md` sections:53 - `Stack and Runtime` / `Build, Test, Run` - stack, tooling, or commands changed?54 - `Architecture Map` - boundaries, directories, data flow moved?55 - `Project Purpose` / `Domain Model` - new concepts or changed behavior?56 - `Agent Guardrails` / `Known Failure Modes` - new gotchas or constraints?57 - `Verification Before Completion` / `Escalation` - done-criteria or stop-and-ask58 cases changed?59 Record each potential path's applicable sections and rationale. Only complete60 evidence covering every potential path can authorize `--semantic complete-no-op`.61 Semantic review may escalate scope, never hide deterministic high-risk evidence.623. **Branch:** classifier `irrelevant`, or complete evidenced potential no-op → No-op.63 Mandatory route → Targeted-delta revalidation. Other routes → full revalidation.6465## No-op: nothing relevant changed66If triage finds no scope-relevant change:67- Build a `drift-classification` evidence record from the classifier report: repository68 identity, exact base/head, final disposition, categorized path dispositions,69 reviewed sections, and outcome (`proven-irrelevant` or70 `revalidated-no-content-change`). Write it with `.aiboarding/tools/write-evidence`.71 Do not copy command output or prose into the record.72- Recheck `git rev-parse HEAD` equals the evidenced `head_commit`; only then set73 `last_synced_commit` and `last_drift_classification` together. An evidence write74 failure or changed `HEAD` leaves state unchanged. Preserve unknown top-level state75 fields.76- **Hard invariant: do not touch `AGENTS.md` or `CLAUDE.md`.** Not even whitespace.77 The pointer advance is a state-only write; this is what keeps the drift hook from78 ever re-nudging on its own bookkeeping.79- Do **not** ask the user - this advance is automatic.80- Briefly report: "No onboarding-relevant changes in <range>; advanced sync pointer."8182## Targeted-delta patch: scope changed83Reuse create-agent-onboarding's Phases 1–3 (background crawl + grilling style,84architectural interrogation, reconciliation), scoped to the affected sections only.85861. **Scoped grill.** Ask focused, one-at-a-time questions about ONLY the changed87 scope, seeded by the diff. Skip sections the delta does not touch.882. **Synthesize.** Re-draft only the affected sections, using the exact H2 heading89 text from the existing `AGENTS.md` to avoid duplicate headings. Leave untouched90 sections byte-for-byte intact. Keep commands/identifiers/paths backtick-quoted.913. **Compress.** Follow the `compress-onboarding` skill on the re-drafted sections92 only (same level as the rest of the doc; it owns high-consequence preservation93 and any per-region opt-in), verifying with `.aiboarding/tools/check-preservation`.944. **Approval gate.** Show the user a diff of the patched sections against the prior95 `AGENTS.md`. Content changes ALWAYS require approval before writing. Only the96 no-op pointer advance is automatic.975. **Advance state.** After approved content work, persist the matching98 `drift-classification` and `onboarding-validation` evidence records first, with the99 exact base/head, affected sections, path dispositions, and validator identities.100 Recheck `HEAD` against the evidenced head immediately before writing the pointer101 and classification receipt together. Evidence failure or a changed head leaves102 state unchanged; preserve unknown fields, then append the legacy compression receipt.1036. **Validate.** Run create-agent-onboarding's Phase 7 gate (files, import line,104 local size sensor, Codex project-chain validation, command resolution, pointer ==105 HEAD) before reporting done.106107When a state-owning create or update flow invokes `audit-onboarding-evidence`, import108only its machine-readable computed findings as validator provenance in the matching109record. The standalone `audit-agent-onboarding` workflow remains read-only and never110creates evidence history.