/sync

name: sync
allowed-tools: Bash, Read, Grep, Glob, Write, Edit, Agent
description: "Run /sync as the last step after a change is complete, around merge, to keep durable knowledge current. Updates root and nested AGENTS.md, reconciles the scope from repo evidence, and flags specs the change made stale. Surgical edits only: it adds lines, and rewrites single lines it owns. Never a whole section, never curated prose."

Output style (plain words, no dashes, no hyphens)

<!-- OUTPUT-STYLE:START --> Write everything this skill produces, files and messages alike, in plain simple language. Talk to the reader as `you`, warm and direct like a colleague, and present every step as a recommendation they may run or skip, never an order. Keep technical terms that carry real meaning; explain each in plain words. Never use a dash or a hyphen as punctuation: no em dash, no en dash, and no hyphenated compounds. Write `read only`, not `read-only`. Say it in simple words, or reword the sentence. Code, file paths, command flags, and values other skills match on keep their hyphens. Use short sentences, commas, or parentheses. Clear beats clever. <!-- OUTPUT-STYLE:END -->

What this skill does

Closes the loop on a completed change: syncs AGENTS.md files, the scope, and linked spec `**Status**:` lines to what the repo now shows, and flags what it must not edit (stale specs, curated prose). The Boundaries table below is the exact contract.

**`agent-prompt.md`** is the single source of truth for the maintenance rules; SKILL.md covers only orchestration. The main thread reads it and does the maintenance itself (see Step 3).

**Canonical file:** durable context lives in the tool agnostic **`AGENTS.md`**; **`CLAUDE.md` is only a pointer** to it. /sync edits/creates both, treating them only as targets, never as a change source.

Boundaries

| Action | /sync | Owner | |---|---|---| | Edit existing root/nested AGENTS.md | ✅ maintains | /sync | | Reconcile root AGENTS.md's `## Build approach` line to the scope header's approach (surgical single line edit, like the stack) | ✅ maintains; flags a curated divergence | /sync | | Add a one line pointer to `design.md` (the UI design system) in the nearest AGENTS.md when a change establishes one | ✅ maintains (pointer only) | /sync | | Create nested `<area>/AGENTS.md` for an area **net new in this change** | ✅ creates (diff = full area context) + adds root pointer | /sync | | Create nested doc for an **already existing** undocumented area (only sliced by the diff) | ❌ flags "run /audit" | /audit | | Create or restructure the **root** AGENTS.md | ❌ flags "run /audit" | /audit | | Reconcile a spec's `**Status**:` line to its feature's scope status (`planned`→`Proposed`, `in-progress`→`In Progress`, `done`→`Accepted`; an `Assumed` spec is the exception: leave it `Assumed` and surface it, never reconcile it to `Accepted`) | ✅ Status line only | /sync | | Clear an `Assumed` spec (move it out of `Assumed`) | ❌ flags as decision debt "run /architect to ratify" (never reconciled to the feature status; only ratification clears it) | /architect | | Edit a spec's **content** / supersede it | ❌ flags as stale | /architect | | Reconcile the scope, for the **relevant workspace's** scope file only (not all of `docs/scope/`), tick **any** completed sub task from repo **evidence** (code, tests, AGENTS.md), advance status | ✅ corrects | /sync | | Add / reorder features or sub tasks in the scope | ❌ leaves alone | /scope | | Overwrite or rewrite curated AGENTS.md prose | ❌ flags conflict instead | human |

The dividing line on creation is **context, not policy**: create only when this change shows you the whole area; defer to /audit when the area predates the change and you've seen only a slice. When unsure, **flag instead of creating**.

Asks vs acts

**Acts.** Pauses only when there is **nothing to sync** (empty change set). Every edit to curated files is listed in the report so you can review or revert.

Artifact ownership

Owns exactly what the Boundaries table grants and writes nothing else. As the **universal sub task reconciler** it ticks any scope sub task it can verify from repo evidence (sweeping the `/test`/`/audit`/`/sync` sub tasks other skills don't tick) and advances feature status; exact rules in `agent-prompt.md`.

**Artifact base.** specs and the scope live under `docs/` by default, or `.workflow/` if `docs/` is a published docs site; use whichever base exists in the repo (paths here assume `docs/`).

---

Portability (any OS, any agent)

• **Commands**: `git` is the only required CLI and behaves the same on every OS, run the `git` lines as shown. Other shell snippets are POSIX **reference**, not literal scripts: don't assume `find`, `grep`, `sed`, `cat`, `test`/`[ ]`, `ls`, or `xargs` exist; use your agent's cross platform file tools and apply branching logic yourself rather than shell `if`/variables/redirects.
• **Bundled files**: referenced by paths relative to this skill's folder. Resolve the folder to an absolute path (you already resolve these relative paths) and read `agent-prompt.md` yourself at write time (Step 3), not during the earlier steps.
• The whole maintenance runs inline on the main thread, following the exact rules in **`agent-prompt.md`** (authoritative).

Execution

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

**Freshness first (teams):** `git fetch --quiet`; if `git rev-list --count HEAD..origin/$BASE` > 0 you are behind `origin/$BASE`, warn the engineer to pull first, a teammate may have already synced these docs.

Base: `main` if `git rev-parse --verify main` succeeds, else `master`. Current branch: `git rev-parse --abbrev-ref HEAD`. Use `--name-status` (not `--name-only`); the net new area and orphan cleanup logic need **A**dded vs **M**odified vs **D**eleted per file.

• Current branch **is** the base, mode `uncommitted`: `git diff --name-status HEAD`.
• Otherwise, mode `branch`: `git merge-base "$BASE" HEAD`,