/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. 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.

**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 tag: `loose:<filename>`. Skip if the file is obviously not a reference doc (e.g., a stray export, a tarball listing).

If `$ARGUMENTS` specifies a skill or repo, narrow scope to that.

Phase 2b: Skills.sh marketplace scan

**Skip gate.** Judge the delta since the last full marketplace scan from the decision log (the most recent entry whose Run context ran Phase 2b, not one that skipped it). Skip this phase on short-delta runs — under 14 days since that last full scan — because marketplace churn over a week or two is almost entirely SHA bumps and yields no net-new patterns. But run it at least every 4 weeks regardless of delta, so a long streak of short-delta syncs can't starve the scan indefinitely. When skipping, record it in the Phase 5b decision-log entry ("Phase 2b skipped — N-day delta, last full scan YYYY-MM-DD").

For each existing skill in the plugin inventory, search f