/sync-from-repos

name: sync-from-repos
description: Analyze reference repos and recommend skill/agent/command improvements based on cross-repo patterns
argument-hint: "[optional: specific skill or repo to focus on]"

Sync from reference repos

Scan reference repositories, compare against plugin skills/agents/commands, and recommend improvements. Read-only analysis — no changes without explicit approval.

Configuration

REPOS_DIR=~/ai/repos
PLUGIN_DIR=plugins/whetstone
SYNC_LOG=docs/audit/audit-log.md

Phase 0: Pre-flight — read prior decision log

Read `$SYNC_LOG` in full before any analysis. Two things come out of it.

First, the **Retired sources** table above the `## Log` marker: repos exhausted by a prior run, each pinned to the HEAD SHA it was retired at. Carry it into Phase 2, which defines the check and the un-retire rule.

Second, build an in-memory set of already-evaluated findings keyed by `(component, pattern-signature)` across every run entry. Use it as a filter during Phase 3 and Phase 4:

• **Previously applied, exact match** — drop silently.
• **Previously rejected, exact match** — drop silently unless new evidence contradicts the prior reason; if so, surface with a `RE-EVALUATE` flag and quote the prior rejection reason.
• **Previously deferred, exact match** — surface with a `PREVIOUSLY DEFERRED` tag and the original defer reason so the user can judge whether conditions have changed.
• **No match** — present normally.

While reading, also detect prune triggers. These three buckets match `/prune-sync-log`'s taxonomy exactly (a missing external repo is a stale-ref, not its own bucket). Emit a one-line reminder at the end of Phase 4 if any fire:

• **age** — any entry older than 30 days.
• **stale-ref** — any entry referencing a component that no longer exists under `$PLUGIN_DIR` (skill, agent, or command path missing), OR an external repo no longer present in `$REPOS_DIR`.
• **superseded** — any entry whose rejection reason duplicates a rule now in `MEMORY.md`.

Reminder format: "Sync log has N prune candidates (age: X, stale-ref: Y, superseded: Z) — run `/prune-sync-log`."

If `$SYNC_LOG` doesn't exist, note it and continue — the post-apply step in Phase 5b creates it.

Phase 1: Pull latest and refresh eval data

cd ~/ai/repos && bash pull-all.sh

If `pull-all.sh` doesn't exist, `git pull` each repo directory individually.

Launch `harvest-sessions` as a background subagent in parallel with Phase 2. This refreshes eval data so `discover-signals` (Phase 6) and `/audit-plugin` both operate on current session data.

Use the absolute script path — the `cd ~/ai/repos` above leaves the shell outside the plugin repo, so a repo-relative `distillery/...` path would not resolve:

python3 /home/ilia/ai/whetstone/distillery/scripts/distiller.py harvest-sessions

Phase 2: Inventory

**Optional pre-pass — similarity report.** Before fanning out the per-repo subagents, `scripts/compare-repos.py` can generate a name/keyword similarity report (skills and agents only) to prioritize which repos and components the subagents examine first — high-similarity pairs are the likely-overlap candidates worth reading closely; repos flagged "layout not recognized" scanned to zero components and can be deprioritized. Invocation (writes the report to a temp path; the run also drops a scratch `.compare-cache/` at the repo root — do not commit it, remove it after):

python3 scripts/compare-repos.py --output /tmp/whetstone-cmp.md ~/ai/repos/*/

Build two inventories in parallel:

**Ours** — read frontmatter (name + description) from every file in:

• `$PLUGIN_DIR/skills/*/SKILL.md`
• `$PLUGIN_DIR/agents/**/*.md`
• `$PLUGIN_DIR/commands/**/*.md`

**Theirs** — for EVERY repo in `$REPOS_DIR/`, find skill/agent/command content using parallel subagents (one per repo). Each subagent must:

1. **Discover all content files**: `SKILL.md`, `*.md` in `skills/`, `agents/`, `commands/`, `.claude/`, `.agents/`, `plugins/`, `categories/`, `specialized/`, `engineering/`, `strategy/`, `integrations/`, and any other non-standard directories. Also check root-level `.md` files (CLAUDE.md, AGENTS.md) for embedded rules and patterns. 2. **Read promising files in full** (not just first 50 lines). Read at minimum the 15-20 most substantial files per repo. For repos with fewer files, read all of them. 3. **Extract**: name, description, specific actionable patterns/rules/techniques, quality assessment, and whether it adds value over our existing content. 4. **Analyze agents and commands** with the same rigor as skills. Agent frontmatter patterns (tools, model, maxTurns, paths, memory), command orchestration workflows, and hook configurations are all in scope. 5. **Skip**: README, LICENSE, CONTRIBUTING, CHANGELOG, config files, and generic persona descriptions without actionable rules.

Every repo must be analyzed. Do not skip repos based on surface-level impressions. Repos that look simple may contain high-quality patterns in non-obvious locations.

**The one sanctioned exception is the Retired sources table in `$SYNC_LOG`** (above the `## Log` marker), read during Phase 0. A retired repo is exhausted, not uninteresting — it earned the entry by being fully mined once. Skipping it still costs one command: `git -C $REPOS_DIR/<repo> rev-parse HEAD`. If the SHA matches the pinned one, note the repo as retired-unchanged in the Phase 5b entry and spend no subagent on it. **If the SHA moved, the retirement is void** — scan the delta like any other repo, then either re-pin at the new SHA or strike the entry, and say which in the run entry. Never skip on the table alone without checking.

**Loose notes at `$REPOS_DIR/` root** — also scan `*.md` files sitting directly in `$REPOS_DIR/` (not inside a repo subdirectory). These are reference docs Ilia dropped in for cross-repo harvesting. Read each in full, extract actionable patterns, and feed them into Phase 3 the same way as repo content. Source