Agent-Loom Sync

You merge upstream agent-loom library improvements into a consumer project's .agents/skills/ without deleting or overwriting skills that belong only to this project.

Hard Rules

Never delete local-only skills. A skill directory present in the project but absent from upstream is project-local — keep it forever unless the user explicitly asks to remove it.

Never overwrite protected or forked skills without explicit user approval. Protection sources: metadata.origin: project-local in SKILL.md, .agents/agent-loom-sync.json → protected_skills / forked_skills, or skills that exist only locally.

Always dry-run before apply. Present the plan (add / update / unchanged / local-only / forked) and wait for confirmation before --apply.

Never sync the project root AGENTS.md from upstream. That file is project-specific (from project-setup). Sync .agents/skills/, and hooks/ when present upstream, optionally .agents/ROUTING.md when the user opts in.

Never run rsync on the whole .agents/skills/ tree with --delete. Sync per library skill directory only — bulk delete would remove project-local skills.

Ensure metadata.origin: project-local on every local-only skill. After --apply, sync_agent_loom.py stamps missing origin on skills absent from upstream. Report stamped skills in the impact report. Same-name upstream forks use forked_skills in config instead.

Workflow

Step 1 — Resolve upstream path

Default: ../agent-loom relative to project root. Override via:

User-provided path argument
.agents/agent-loom-sync.json → "upstream"

Verify upstream exists and contains .agents/skills/. If missing, stop with the exact path checked.

Bootstrap config if absent: copy templates/agent-loom-sync.json → .agents/agent-loom-sync.json.

Step 2 — Build sync plan

python3 .agents/skills/agent-loom-sync/scripts/sync_agent_loom.py --dry-run

Classify each skill — read references/sync-policy.md for protection rules. Summarize for the user:

Bucket	Meaning
Add	New upstream skill not in project
Update	Upstream skill differs; safe to rsync
Unchanged	Already matches upstream hash
Local-only	Project skill with no upstream counterpart — protected
Forked	Modified library skill — skipped until user merges

Step 3 — Confirm with user

Show counts and name lists for Add and Update. Ask: "Apply sync?" One confirmation for apply; forked skills need per-skill decision if user wants upstream version.

Step 4 — Apply

python3 .agents/skills/agent-loom-sync/scripts/sync_agent_loom.py --apply

Updates .agents/agent-loom-sync.json with last_sync and upstream_commit. Script stamps metadata.origin: project-local on local-only skills missing it — report which skills were stamped.

Step 5 — Optional ROUTING.md

Only if user asks: rsync upstream .agents/ROUTING.md when project has not forked it (no local diff). Never auto-overwrite without asking.

Step 6 — Post-sync validation

Invoke validate-skills (or run Step 4e craft gates) on updated skills. Report P0/P1 before user commits. Regenerate host routing adapters: python3 .agents/skills/project-setup/scripts/gen_host_adapters.py (refreshes .cursor/rules/ from the synced skill set).

Step 7 — Log and handoff

Append to docs/skill-outputs/SKILL-OUTPUTS.md. Recommend commit message: chore: sync agent-loom library @ <commit>. Offer memory-handoff if session ends.

Project-local origin (this skill's job)

Responsibility	Owner
Write `metadata.origin: project-local` when creating skills	`universal-skill-creator` (Step 4 + Step 7b)
Stamp missing origin on local-only skills after sync	`agent-loom-sync` (`--apply` via `sync_agent_loom.py`)
Protect skills with that metadata from overwrite	`agent-loom-sync` sync plan
Same-name customized upstream skill	`forked_skills` in `.agents/agent-loom-sync.json`

Every project-local SKILL.md should carry origin: project-local. These skills ensure it — not the user.

Gotchas

Copying all of .agents/ once ≠ ongoing sync. This skill is the ongoing path; re-copying blindly deletes project-local skills.
../agent-loom is relative to project root, not the skill directory — run the script from repo root.
rsync --delete is per-skill, removing stale files inside an updated library skill dir only.
Global install (install.sh) is different — that symlinks to ~/.agents/skills; this skill targets project-copied .agents/.
Upstream must be pulled first — remind user to git pull in agent-loom before sync if they want latest.

Common Rationalizations

Excuse	Reality
"Just rsync the whole .agents folder"	Deletes project-local skills and project config
"Skip dry-run, I trust upstream"	Forked/custom skills get wiped without a plan
"Overwrite my fork — upstream is always right"	Require explicit per-skill opt-in to replace forked
"Sync AGENTS.md from agent-loom"	Project AGENTS.md is from project-setup — merge manually
"Delete skills removed upstream"	Local-only stays; upstream removals don't delete local skills

Verification

Dry-run plan shown before apply
All local-only skills listed under protected
No protected/forked skill in Update list without user approval
agent-loom-sync.json updated after apply
Local-only skills have metadata.origin: project-local (stamped by apply if missing)
SKILL-OUTPUTS.md appended when files changed

Red Flags

Whole-tree rsync with delete on .agents/skills/
Local-only skill missing from protected list in plan
Forked skill overwritten without user opt-in
Upstream path points at wrong repo or missing .agents/skills

Example

<examples> <example> <input>sync agent-loom from ../agent-loom without losing my custom skills</input> <output>Plan: 15 add, 22 update, 3 local-only protected. Awaiting confirm before --apply.</output> </example> </examples>

Read references/examples.md for full session walkthroughs.

Prune Log

Last pruned: 2026-07-04

No changes — citation audit passed; content current (improve-skills full pass 2026-07-04)

Impact Report

agent-loom-sync

SKILL.md.agents/skills/agent-loom-sync/SKILL.md