sync

# Sync Maintenance Guide (main thread)

You, the main thread, read and follow this at write time (Step 3). Read each ALL_CAPS placeholder as the matching input you gathered in the earlier steps.

---

You maintain a project's durable knowledge after a code change. Your job is narrow: the steps below define all of it. Be conservative: when in doubt, flag rather than write.

**Canonical file:** durable context lives in the tool agnostic **`AGENTS.md`**; **`CLAUDE.md` is only a pointer** importing its sibling AGENTS.md via Claude Code's `@` directive. Never write content into a CLAUDE.md, never overwrite an existing AGENTS.md. When you create a new nested `AGENTS.md`, also create its sibling `CLAUDE.md` containing only:
```markdown
# CLAUDE.md

This project's context for all AI tools lives in [AGENTS.md](./AGENTS.md).
Claude Code loads it via the import below:

@AGENTS.md
```

## The change

- **Scope mode**: MODE
- **Base / merge base**: BASE / MERGE_BASE
- **Changed source files (with status A/M/R)**: CHANGED_FILES
- **Deleted paths (status D, for orphan cleanup only)**: DELETED_PATHS

See exactly what changed with:

```
DIFF_COMMAND
```

**Default to doing nothing.** Code that doesn't alter a command, convention, constraint, dependency, or structural layout does not belong in durable knowledge; a line that just narrates what this change did is churn, not maintenance. A `NOTHING_TO_SYNC` run is a normal, good outcome.

## Existing context files (you may EDIT these; you may CREATE a nested AGENTS.md + its CLAUDE.md pointer for a net new area only)

- **Root AGENTS.md (inlined)**:

ROOT_AGENTS_MD

- **Nested AGENTS.md paths**: NESTED_PATHS
- **Changed file → nearest context file**: FILE_TO_CONTEXT_MAP

## Specs (you may reconcile ONLY the `**Status**:` line; you may FLAG staleness, you must NOT edit any other spec content)

SPEC_PATHS

## Feature scope for the relevant workspace(s) the diff touches, NOT all of docs/scope/ (you may RECONCILE status only, never add/remove/reorder features)

SCOPE_PATH_OR_NONE

## Tool discovery result from the main model

- **Installed Agent Skills**: INSTALLED_SKILLS_OR_NONE
- **MCP servers selected or recommended**: MCP_SERVERS_OR_NONE
- **Declined or skipped tools**: DECLINED_TOOLS_OR_NONE

---

## What to do

### 1. Update existing AGENTS.md files (only where the change made them inaccurate)

Read the diff. For each existing root/nested AGENTS.md whose area was touched, check whether the change altered a command (build/test/run/scripts), a convention, constraint, or dependency, broke a file pointer (target moved or removed), or added a new durable rule that belongs in that existing doc.

Make the edit only if it is:
- **Surgical**: change or add specific lines, never rewrite sections.
- **Additive or corrective**: add a missing fact or fix a wrong one. Never delete curated guidance you don't fully understand.
- **Durable**: true beyond this one change. Skip one off notes, history, and feature summaries.

### The mirrored root fields

<!-- ROOT-FIELD-CONTRACT:START (identical in /audit and /sync; edit both or neither) -->
Root `AGENTS.md` carries two mirrored fields. Each has exactly one source of truth outside the file, and no skill may invent a value for either:

- `## Stack` mirrors the architecture spec, the one under `docs/specs/` with a `## Proposed stack` section.
- `## Build approach` mirrors the scope header's build approach line, the one `/scope` records.

Three rules bind every skill that touches them. Never overwrite curated prose in either field. Fill a field only when it is missing or still a placeholder. When a field and its source disagree, flag the divergence and name the file you read the source from, rather than picking a winner.
<!-- ROOT-FIELD-CONTRACT:END -->

What `/sync` does with them: reconcile, one line at a time.

- **Missing the value its source sets** (e.g. a greenfield root seeded before the architecture spec landed, or a root with no build approach line while the scope header names one): add that one line surgically, and record it under `AGENTS_UPDATED`.
- **Field and source disagree**, or root's version is elaborated curated prose, or you cannot tell which side is authoritative: do not overwrite. Flag it under `CONFLICTS`, naming the spec or scope file you compared against.

`/sync` never restructures root or creates it; that is `/audit`'s job (see the Boundaries table in `SKILL.md`).

**Agent Skill and MCP records:** if `INSTALLED_SKILLS_OR_NONE`, `MCP_SERVERS_OR_NONE`, or `DECLINED_TOOLS_OR_NONE` is not `none`, record it surgically in the most specific relevant AGENTS.md:
- Project wide tools (framework, ORM, styling, core DB, hosting, test runner) belong in root AGENTS.md.
- Area specific tools (payments, auth, email, uploads, search, queues) belong in that area's nested AGENTS.md when one exists; otherwise add a short root note and flag the area under `CONTEXT_GAPS`.
- An installed skill goes in the `## Agent skills` section as its own bullet so only needed skills load: `- [<skill>](<skills-dir>/<skill>/): `<owner>/<repo>`, <what it covers>`, using the project's real skills dir (`.claude/skills/`, `.agents/skills/`, or `skills/`, never a hardcoded Claude only path, since every tool reads this file) and keeping the registry source `<owner>/<repo>` as the tool agnostic identity. Create the `## Agent skills` section if the doc lacks one (append near the end, before `## Context files` in root); never fold skills back into a single dense line of names.
- A declined tool and a connected/recommended MCP server stay compact lines in that section (they have nothing to load): `Declined: <tool>` · `MCP servers: <server> (connected|recommended)`.
- Idempotent: if the same installed, recommended, connected, or declined item is already recorded (even worded differently), do not add it again.
- Record selected MCPs as recommended unless the main thread explicitly says connected.

**Design system pointer:** if this change added or established a `design.md` (the UI design system, art direction plus the build mandate) and the nearest AGENTS.md has no pointer to it, add one surgical line: `` - Design system: build all UI to `design.md` (art direction and the maximalist product bar); token values live in CSS. `` Put it in root AGENTS.md for a project-wide `design.md`, or the UI area's nested AGENTS.md if the system is area-scoped. Idempotent: skip if a `design.md` pointer already exists. Never paste design.md content into AGENTS.md; it is a pointer, not a copy.

Rules you must not break:
- **Idempotent, check before you add.** Read the target doc again now. If the fact, command, or pointer is already present, even worded differently, do not add it again: /sync run twice on the same change must make zero new edits the second time.
- **Never overwrite or rewrite curated prose.** If accuracy would require rewriting an author's curated paragraph, record it under `CONFLICTS` for a human instead.
- Keep root AGENTS.md short and globally relevant; area specific detail belongs in a nested doc.

### 2. Create a nested AGENTS.md: only for an area NET-NEW in this change

You may create **one** nested `<area>/AGENTS.md` for an area the change introduced wholesale. The test is **context, not policy**:

- **Create it** when every source file in that area carries status `A` (added) in CHANGED_FILES: the diff shows you the entire area. If any file in the area is `M` (modified), the area already existed: do NOT create. Write a focused doc: local file pointers, local commands, conventions/constraints visible in the new code, links to any governing spec. End it with the one line note: `_Drafted by /sync from the introducing change, worth a quick human pass._` Then add exactly one pointer line to root AGENTS.md under `## Context files`:
  ```
  - [<area>/AGENTS.md](<area>/AGENTS.md): <one-line description>
  ```
  **Idempotency + missing section**: skip the pointer if already present; if root has no `## Context files` heading, create it (append near the end of root) and add the pointer under it.

  Also create the sibling **`<area>/CLAUDE.md` pointer** (per the Canonical file block above) so Claude Code picks up the new area too.
- **Area that already exists, defer to /audit**: the diff shows only a slice of an area that predates this change, so you lack the whole area context to write a good doc. Record it under `CONTEXT_GAPS`.
- **Never create or restructure the root AGENTS.md.** If the repo has no root AGENTS.md at all, that's /audit's job; record under `CONTEXT_GAPS`.
- One nested doc per genuinely distinct new area, never one per folder.

### 3. Clean up orphans from deletions

For each path in DELETED_PATHS:
- A nested `<area>/AGENTS.md` describing code that no longer exists is orphaned. Remove it only if the whole area was deleted (the directory is gone); if only some files went, correct the now broken file pointers inside the doc instead.
- When you remove a nested doc, also remove its pointer line from root's `## Context files`.
- Fix any file pointer in any AGENTS.md that targets a deleted/moved path.
- Record removals under `ORPHANS_CLEANED`. If unsure a deletion is permanent, flag under `CONFLICTS` instead of deleting.

### 4. Reconcile linked specs' Status line (edit ONLY the `**Status**:` line, never spec content)

A spec's status mirrors its feature's build lifecycle:
- `Proposed`: not yet built (scope `planned`).
- `In Progress`: being built (scope `in-progress`).
- `Accepted`: built and verified (scope `done`); a spec is not `Accepted` until its feature ships.
- `Superseded`: replaced by a later spec (never set this from scope status; flag under `STALE_SPECS` instead).

For an **umbrella decision**, reconcile the linked `index.md` (child specs carry no status and are not reconciled).

This applies **only to specs that link to a buildable scope feature.** A **standalone decision spec** (a foundational/stack or cross cutting standard with no linked feature) is decision status: `Proposed` when written, `Accepted` once ratified, never feature mirrored. Leave it as is; do not reconcile or flag it under `STALE_SPECS` (e.g. "no linked feature found") merely for having no linked feature, that is expected, not a mismatch. Only genuinely stale/superseded standalone specs (Step 5) get flagged.

For each spec whose linked feature appears in the reconciled scope:
1. Find the feature this spec governs (its title/links reference a scope feature, which may link back).
2. Read the feature's current scope status and derive the target spec status from the mapping above.
3. **Read the spec again just before writing** (a teammate or another session may have edited it). If the `**Status**:` line already equals the target, do nothing (idempotent). Otherwise make a single surgical edit to that one line only.
4. Record the change under `SPEC_STATUS_RECONCILED`.

**Do not guess.** If a feature linked spec is ambiguous (no confident link to exactly one feature, unclear mapping, status already `Superseded`, or a downgrade you can't explain), do not edit; flag the mismatch under `STALE_SPECS` and leave the line as is.

### 5. Flag stale specs (do not edit their content)

Be **strict**, noise erodes trust. Read a spec only if the changed paths plausibly touch its subject (judge from its title/first lines; don't read all blindly). Flag it **only when you can name the specific decision the change contradicts**, e.g. the spec mandates one datastore and this change adds an adapter for a different one, or the spec fixes an interface/boundary the change breaks. Also flag a spec a **later spec supersedes** (its status should become `Superseded`, /architect's job, not a Status line reconciliation). Never flag vague "might be affected" cases; when in doubt, do not flag. Record genuine hits under `STALE_SPECS` with the contradicted point and recommend /architect to update or supersede; never edit spec content yourself.

### 6. Reconcile the feature scope (only if SCOPE_PATH_OR_NONE is a path)

**Scope:** only the scope file(s) you were handed. Never hunt for or reconcile other files under `docs/scope/`; one workspace's change does not license editing another's.

You are the **universal sub task reconciler**: `/develop` ticks its own sub tasks; `/test`, `/audit`, and `/sync` sub tasks have no one else. For **every feature the diff touched**, evaluate each of its sub tasks again against repo evidence (not just what this diff added) and tick the genuinely complete ones: the diff picks *which features* to check again, the repo state decides *which sub tasks are done*. Look directly with Read/Bash/Grep/Glob.

**Malformed scope** (no `At-a-glance` table or feature sections, a status that is not standard, broken headings, a bad hand edit): do not edit it; note `scope malformed: <file>, needs a human or /scope re-run` under `SCOPE_RECONCILED` and skip it. Never act on a misread.

> Step 1's source file filtering (dropping `*.test.*`, `docs/**`) governs what you sync AGENTS.md from; it does not limit reconciliation. Here you may and should inspect test files, AGENTS.md, and config to judge completion.

Evidence per sub task type (tick `[ ]` → `[x]` when the evidence is clearly present):
- **UI / data model / backend / integration / data integration** → the corresponding files exist in the feature's code area (components/pages, schema/migrations, services/endpoints, the mock replaced by a real query).
- **Build it (+ milestones)** → the feature's code exists in its area (milestone chunks present); `/develop` usually ticks these itself.
- **Verify it** → a `verify.md` beside the spec, or a recorded passing runtime verification for the feature.
- **Test it** → test files cover this feature's area (search the area + test dirs).
- **Review it (fresh model)** → a findings file for this feature under `docs/reviews/` (`/check review`'s output).
- **Document it** → a PR body, a `CHANGELOG.md` entry, or a release note covering this feature (`/document`'s output).
- **SEO & metadata** → metadata/structured data present on the feature's pages.
- **Sync (record conventions)** → the area's `AGENTS.md` exists and reflects the feature.
- **Coding standards / tooling** → linter/formatter/`pre-commit` config present in the repo.

Then update the feature's **status**, in the `At-a-glance` table AND beside its heading: keep it `in-progress` while a box the feature actually has (`Build it` + its milestones, plus `Verify it` / `Test it` when the tier includes them) is still unticked; set `done` once all of the feature's present boxes are ticked. Never downgrade a feature the engineer already marked `done` (a step they chose to skip is recorded as skipped, not a reason to reopen it).

- **Strictly status only.** Never add, remove, rename, or reorder features or checkboxes (that's /scope's). Skip `existing` and `dropped` features entirely. Never invent a feature for code that has no section; if shipped code clearly matches no feature, note "unmapped: <area>, run /scope to enroll this off plan work" under `SCOPE_RECONCILED`.
- **Attribution across features and workspaces.** Only tick a sub task when the file→feature mapping is **unambiguous** (the file lives in that feature's code area and matches that sub task). In a monorepo, a changed file's **workspace** (`apps/<x>/…`) selects the scope to update, `docs/scope/<x>/`; never tick a feature in the wrong workspace's scope. If an area maps to more than one feature, do not guess; note `ambiguous: <area> → <featureA> / <featureB>` under `SCOPE_RECONCILED`.
- **Idempotent**: a box already `[x]` stays `[x]`; running it again changes nothing.
- **Conservative**: tick only on clearly present evidence; when unsure, leave it.
- **Git**: if root `AGENTS.md` `## Git` says `integration: on` and `commit` is not `manual`, offer to commit the reconciliation with a one line subject (`chore(sync): reconcile docs`) plus the `Co-Authored-By` trailer; never push.

### 7. Report

Output exactly this block, verbatim, no extra prose. Omit any section that's empty.

```
SCOPE: <N> changed files

AGENTS_UPDATED:
- <path>, <what you added or corrected, one line>

AGENTS_CREATED:
- <area>/AGENTS.md, <conventions captured; root pointer added>

ORPHANS_CLEANED:
- <path>, <removed orphaned doc / fixed broken pointer after deletion>

SCOPE_RECONCILED:
- <feature>, <sub-tasks ticked / status advanced to match the diff; or "unmapped: <area>">

SPEC_STATUS_RECONCILED:
- <docs/specs/file>, <Status line: Proposed→In Progress→Accepted to match the feature's scope status>

STALE_SPECS:
- <docs/specs/file>, <why the change makes it stale, or a status mismatch you couldn't safely reconcile>

CONTEXT_GAPS:
- <area>, <pre-existing undocumented area only sliced by this change; suggest /audit>

CONFLICTS:
- <path>, <curated content that would need rewriting; left for a human>
```

If you made no edits and found nothing stale, output `SCOPE: <N> changed files` followed by `NOTHING_TO_SYNC: everything is already current`.

# OpenAI Codex adapter. This file supplies the interface metadata Codex shows in
# its agent picker. The skill's actual instructions live in ../SKILL.md, which the
# Agent Skills client installs alongside this file and loads when the skill runs.
interface:
  display_name: "Sync"
  short_description: "Refresh durable project knowledge"
  default_prompt: "Run the sync skill: read its SKILL.md, then update AGENTS.md, the scope, and spec statuses to match what the repo now shows."

---
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`, then `git diff --name-status <merge-base>`.

Either way, add untracked files from `git ls-files --others --exclude-standard`, each prefixed with an `A` status (matching the `--name-status` format). Note the mode, base, and merge base for the write step.

Remove duplicates, then **filter to source files** to sync *from*:
- **Drop documentation and config** (`AGENTS.md` at any level, `docs/**`, `*.md`, `test-preferences.json`, lock files, generated output); /sync reads these as targets/context, never as a change source.
- **Drop test files** (`*.test.*`, `*.spec.*`, `__tests__/`, etc.); tests aren't durable area conventions.
- **Keep the `D` (deleted) entries** in a separate list; they drive orphan cleanup (Step 3) though they aren't synced *from*.
- **Keep dependency manifest changes in a separate list** for tool discovery, even if they are config rather than source: `package.json`, `pyproject.toml`, `requirements*.txt`, `go.mod`, `Cargo.toml`, `composer.json`, `Gemfile`, `pubspec.yaml`, `mix.exs`, `*.csproj`, and equivalent package manifests. Lock files are signals only; do not pass lockfile contents.

**If no source files and no dependency manifest changes remain** (only docs/tests/lock/generated files changed), stop, nothing to sync. Do not spawn.

### 2. Locate the context files and specs (paths only, do NOT read them here)

Using your agent's file search/glob tools:
- Note whether a root `AGENTS.md` exists.
- Find every `AGENTS.md` (root + nested), excluding `node_modules/` and `.git/`.
- Find all specs under `docs/specs/` whose names start with a digit, sorted.
- Find the scope file(s) whose workspace/features the diff actually touches (in a monorepo, a changed file's workspace `apps/<x>/…` selects `docs/scope/<x>/`); never read or pass all of `docs/scope/`.

Note the **paths** plus the changed file list and diff command; read the files at write time. Read root AGENTS.md contents now (short and useful to anchor on). For each changed file, note its nearest enclosing directory with a `AGENTS.md` (root or nested); that's the context file most likely to need an update.

### 2.5 Discover Agent Skills and optional MCPs for newly added tools

Run only when dependency manifests changed or the diff clearly adds a significant external tool. Skip ordinary utility libraries unless they define a durable workflow or integration.

- Identify newly added significant packages/tools from the manifest diff, not the full lockfile: framework, router, styling/UI kit, database, ORM/query layer, auth/session, payments, email/notifications, storage/uploads, search, queue/background jobs, AI provider/vector DB, browser/runtime testing, observability, hosting/deploy. Include package names and common aliases from manifests. Do not stop after the first technology.
- Filter out anything already covered by installed skills, connected MCPs, or `AGENTS.md` declined entries.
- **Ask before you search.**

  <!-- TOOL-CONSENT:START (identical in /architect, /audit and /sync; edit all or none) -->
  **Asking is mandatory. Searching is not.** Nothing is searched, fetched, installed, or spawned for Agent Skill and MCP discovery until the engineer has picked. Offer four choices: find them for me, I will name the ones I want, no and record the decline, or not now. Only the first may run a search command. Never silently skip the offer, and never run a search before the engineer agrees to one.
  <!-- TOOL-CONSENT:END -->

  Name the tools this change added, say in one line that an Agent Skill gives the agent that tool's real conventions and an MCP server gives it live access to the real system, then ask: "Want me to find Agent Skills and MCP servers for the tools this change added?" (header `Agent skills`), with `Yes, find them for me` (recommended) · `I'll name the ones I want` · `No, skip it` · `Not now, later`. On `Yes` continue below. On `I'll name the ones I want`, take the list and go straight to the install step, searching for nothing. On `No, skip it` run nothing and record the decline. On `Not now, later` run nothing and note the candidate tools in the report.
- **Isolate the searches in a read only subagent (capability first, only after `Yes`).** Hand the remaining set to a discovery subagent rather than searching on the main thread: spawn it in the background (it does not block) if your agent supports that, else blocking; set its model explicitly to a fast, low cost tier (do not inherit the session model; on Claude Code spawn it as the `researcher` subagent type, which pins the model); it returns only the compact candidate list. This keeps the search output out of `/sync`'s bounded context. No subagent → search inline; no search capability → skip and note it. The offer panel stays on the main thread.
- For each remaining item, run `npx skills find <tool-or-package>`; if weak, retry aliases from package/org names. Collect every credible Agent Skill candidate and confirm with `npx skills add <owner>/<repo> --list` when practical. If the CLI is interactive/unavailable, search `"<tool>" "agent skill"` and confirm before offering.
- MCP search is optional: connector list first, else `"<tool>" "MCP server"` per item. MCP is recommended upside, not required.
- Keep discovery capped and cacheable: max 5 web searches and 8 fetched pages total, official registry/docs first. Reuse `docs/.agent-cache/tool-discovery/<slug>.md` when under 30 days old, after filtering installed/declined items.
- Offer all Agent Skill matches in one multi select panel, grouped by technology: "Install relevant Agent Skills for newly added tools?" plus skip/decline. Then offer MCPs separately: "Optional MCP servers that could help these tools" plus skip/decline. Never install or connect automatically.
- Install selected skills with `npx skills add <owner>/<repo> -y`. For MCPs, point to the user's connector/MCP settings; once connected the tools are used automatically.
- Carry the result as `INSTALLED_SKILLS_OR_NONE`, `MCP_SERVERS_OR_NONE`, and `DECLINED_TOOLS_OR_NONE` and record durable lines in the right `AGENTS.md` file when you write. If nothing was found or no capability exists, treat as `none`.

### 3. Do the maintenance (main thread)

The main thread does the maintenance itself; it never hands the `AGENTS.md` / scope / spec status edits to a subagent. Read `agent-prompt.md` now (only now, at write time) and follow it exactly; it is authoritative for the maintenance rules. The diff reading is the one thing you may offload, and only for a large change set, to a read only `scout` subagent on the cheapest model (Claude Code: `haiku`) that returns a compact map. Stay within the same boundaries the old tool grant expressed: `Edit` existing docs, scope, and spec `**Status**:` lines; `Write` strictly for a **net new area** nested AGENTS.md; no root creation, no spec *content* edits (Status line only), no shallow nested docs for established areas (these are rules in `agent-prompt.md`).

The inputs to apply:
  1. `MODE`, `BASE`, `MERGE_BASE`, `CHANGED_FILES` (name status changed source list), `DIFF_COMMAND` (exact `git diff` command)
  2. `DELETED_PATHS` (deleted paths, for orphan cleanup)
  3. `ROOT_AGENTS_MD` (root AGENTS.md contents), `NESTED_PATHS` (nested AGENTS.md paths)
  4. `SPEC_PATHS` (all spec paths, for Status line reconciliation and staleness flagging)
  5. `FILE_TO_CONTEXT_MAP` (changed file → nearest context file)
  6. `SCOPE_PATH_OR_NONE` (relevant workspace scope path(s), not all of `docs/scope/`; also the source of each linked feature's status for spec Status line reconciliation)
  7. `INSTALLED_SKILLS_OR_NONE`, `MCP_SERVERS_OR_NONE`, `DECLINED_TOOLS_OR_NONE` from Step 2.5

### 4. Relay the result

**If the maintenance failed or produced no parseable summary**, report that and do it again, don't fabricate a result (a genuine `NOTHING_TO_SYNC` is a valid success; a crash or empty output is not). Otherwise relay the compact summary:

Lead with what it reconciled in one line; then list only what needs the engineer (per `docs/conventions.md`). The edits themselves are in the files. Template:

```
## /sync complete · reconciled <N> changed files

**Updated <AGENTS.md files · scope features · spec statuses> to match the diff.**   (or "everything already current, nothing to sync")
Heads up (need you):
- Stale spec → /architect: `<file>` (<why, or a status mismatch /sync couldn't safely resolve>)
- Assumed, not ratified → /architect: `<file>` (<feature>; owes ratification, doesn't block `done`)
- Context gap → /audit: `<area>` (established area /sync can't document from the diff alone)
- Conflict, decide manually: `<path>` (<curated content that would need rewriting>)
```

Drop any Heads up bullet with no items, and drop the whole Heads up block if there are none. What `/sync` did (AGENTS.md lines, scope ticks, orphan cleanup, status reconciliation) is in the files; don't list it. `/sync` does not run `/architect` or `/audit` for you; it points, you decide.

---

## Subagent prompt template

See `agent-prompt.md`.