/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 `analyze-outcomes` (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.

**Unchanged since the last full scan — narrow the pass with proof.** Before pulling in Phase 1, record each repo's HEAD (`git -C $REPOS_DIR/<repo> rev-parse HEAD`). A repo counts as unchanged when its HEAD did not move in the pull and the most recent full-scope sync scanned it at that same SHA. Proof is the SHA listed under that run's `### Scanned SHAs`; for runs that predate the list, `git -C $REPOS_DIR/<repo> reflog -1 --date=short` must show the last HEAD change on or before that run's date. Without proof, treat the repo as changed. Loose notes follow the same rule, using the file's mtime.

An unchanged source still yields new findings when the plugin moved under it: the same text now meets different gaps, and no other command re-reads external sources against the current plugin. So take the plugin diff since that scan (`git diff --name-only <whetstone SHA from Scanned SHAs>..HEAD -- $PLUGIN_DIR`; for older runs, the run's last recorded