sync

name	sync
compatibility	Built for Claude Code (subagents). Installs on any Agent Skills client.
allowed-tools	Bash, Read, Grep, Glob, Edit, Write, Task
description	Keep durable knowledge current after a change ships. Run /sync as the last step on medium/full work, around merge. Updates AGENTS.md context files (root + nested) to reflect what changed, reconciles the feature's roadmap row and its ADR Status line, creates a nested AGENTS.md for a genuinely new area, and cleans orphans after deletions.

Read ../conventions.md first (once per session). It carries the session start gate, model routing (this skill: mid or small tier; the subagent runs a fast model), subagent rules, and output style. Apply the start gate before anything below.

What this skill does

The librarian. After code ships, it makes the docs tell the truth again: conventions that changed land in the nearest AGENTS.md, the shipped feature's roadmap row and its ADR **Status**: line get reconciled, deletions clean their orphaned docs and pointers. Bounded maintenance, run by a cheap subagent.

Boundaries: never creates a root AGENTS.md (/audit owns bootstrap) · never edits ADR content, only the one Status line · never writes a shallow nested doc for an established area (nested docs are for genuinely net-new areas) · never syncs a doc from a doc.

Execution

1. Scope the change set (with per-file status)

Freshness first (teams): git fetch --quiet; behind origin/$BASE → warn to pull first (a teammate may have synced already). Base = main else master. On the base (mode uncommitted): git diff --name-status HEAD plus untracked as Added. On a branch: merge base, git diff --name-status <merge-base>, plus untracked as Added. De-duplicate, then filter to source files to sync from: drop docs and config (AGENTS.md, docs/**, *.md, test-preferences.json, locks, generated) and test files; keep Deleted entries in a separate list (they drive orphan cleanup). No source files remain → stop, nothing to sync; do not spawn.

2. Locate targets (paths only, do not read here)

Glob: every AGENTS.md (root + nested; note whether root exists) · all docs/adr/ ADRs (digit-prefixed, sorted) · the roadmap file(s) for only the workspace(s) the diff touches (a changed apps/<x>/… file selects docs/roadmap/<x>/; never pass all of docs/roadmap/). Map each changed file to its nearest enclosing AGENTS.md. The one inline read: root AGENTS.md contents (short anchor for the subagent).

3. Spawn the subagent

Read agent-prompt.md (lazy), fill, spawn: fast low-cost model · tools Read, Bash, Grep, Glob, Edit, Write (Write strictly for a net-new-area nested AGENTS.md; the no-root-creation and Status-line-only boundaries are rules in the prompt) · prompt carries the name-status list + exact diff command, the deleted-paths list, root AGENTS.md inline + nested paths, the full ADR path list, the changed-file → nearest-context map, and the relevant roadmap path(s) (the source of each linked feature's status for ADR Status reconciliation).

4. Relay

Errored or no parseable summary → report, offer a re-run (a genuine NOTHING_TO_SYNC is a valid success; a crash is not). Otherwise relay: which AGENTS.md were updated (one line each) · created (new area, + root pointer) · orphans cleaned · roadmap and ADR statuses reconciled · staleness flags for the engineer. Close: "Next: /clear, then whatever the roadmap's first unticked box says."

Reference files (lazy)

agent-prompt.md (the maintenance subagent's prompt and boundaries).