harness-sync
Sjel is the source. Every harness holds a copy or a pointer, and the two drift.
For upstream skills or plugins, apply CONTRIBUTING.md#owned-agent-components before deployment:
classify an owned adaptation or an explicitly approved native dependency. Screening, store
membership, native packaging and a new name establish neither ownership nor approval.
Use the native host's lifecycle for approved dependencies, not Pack sync or promotion.
One tool answers all of it: tools/harnesses in the Sjel repository. This skill is the judgment
around it — which direction a change should travel, and when the answer is not sync.
The direction rule
Sjel Packs ──(sync, routine, one-way, overwrites)──▶ harness
Sjel Packs ◀──(promote / accept, manual, human decides)── harness
Sync is the normal move and it is destructive at the destination by design. The reverse moves are manual because an edit made inside a harness is a decision, and a tool that guessed would either lose good work or import junk into the source of truth.
| Situation | Move |
|---|---|
| The Pack changed; the harness is behind | sync |
| A deployed copy was edited in place and the edit is worth keeping | accept |
| A deployed copy was edited in place and the edit is not worth keeping | discard — replaces the copy with the Pack's text and keeps the replaced copy beside the ledger. It lists what it replaces, adds and removes, and refuses until given --force |
| A skill exists in a harness, no Pack owns it, and it should be shared | promote |
| An upstream skill exists outside Sjel ownership | check explicit native component/host approval; otherwise assess adaptation or leave it unapproved, not silently activated |
Procedure
- [ ] 1. Ask which harnesses are installed
- [ ] 2. Read the matrix
- [ ] 3. Resolve drift before deploying anything
- [ ] 4. Move in one direction at a time
- [ ] 5. Re-read the matrix
1 — Installed, not merely supported. tools/harnesses list. A harness with an adapter is not a
harness on this machine, and deploying to an absent one leaves skills in a directory nothing reads.
Every verb defaults to installed harnesses only; --all-harnesses overrides it and needs a reason.
2 — Read the matrix. tools/harnesses status [<pack>]. One row per Pack skill, one column per
harness: · current, o outdated, D drifted, M missing, blank not deployed. The GPUI
Packs view presents this matrix, read through sjel-status — and its controls
(sync/deploy/remove) invoke this skill's sync and the per-harness deploy, offered where the
defect is. Fixing a cell from the view is the same move as running the command: it invokes the
same launcher, so its refusals are the tool's own words. A D cell has no button there, because
sync refuses drift and the fix is the decision below, not a click.
Under it, each harness lists what sits at its destination that no Pack owns:
| Kind | What it means | What to do |
|---|---|---|
copy |
An ordinary directory nobody claims | A promote candidate. Read it first. |
external |
Carries .git or a similar installer marker |
Never promote. Another installer owns it and re-syncs from its own remote; a copy in Sjel is a fork that will silently pin it. Record it in upstreams.toml instead. |
symlink |
Points into a product install | Never promote. The target is the install; an upgrade updates it. |
3 — Resolve drift first. tools/harnesses drift [<pack>] [--diff] names the differing files and
prints the diff. sync refuses to run against a drifted copy — that refusal is the feature. Two verbs
clear the state, and each is a decision:
acceptkeeps the edit: it imports the destination's text into the Pack, so reviewgit diffafterwards and revert what should not have been imported.discarddrops the edit: it writes the Pack's text to the destination and keeps the replaced copy under~/.local/state/sjel/pack-deployments/discarded/. Run it without--forcefirst; it lists the files it would replace, add and remove, and refuses until given--force. The Pack is never written.
4 — One direction at a time. Do not run accept and sync for the same pack in one pass. Accept
first, review git diff, then deploy outward.
5 — Re-read. The matrix after the move is the receipt. accept re-records the ledger itself, so
a row still showing D afterwards means the copy and the source still differ.
What each harness actually does with a Pack
- Materialized (Claude Code, Codex, opencode, GitHub Copilot CLI): the adapter copies the
skill and records a digest. Drift is possible and detectable. Claude Code additionally takes a
Pack's
agents/directory as one unit at~/.claude/agents/<pack>. - Registry (pi): the harness reads the Pack source in place through a path list in its own
settings. There is no copy, so there is no drift — the only defect is a registered path that no
longer exists, which
statusreports asmissing.promoteandacceptare meaningless there and refuse. pi additionally auto-discovers~/.agents/skillsand every.agents/skillsup to the repository root, so a skill placed there by anybody else is loaded too.statuslists those as~discovered. Check native component/host approval before classifying an unowned entry as a violation; discovery is not approval. Approved upstream-managed entries stay with their installer, neverpromote. Duplicate names remain a defect because pi keeps the first.tools/skills auditnames discovered entries; project-scoped placement throughtools/skills adddoes not bypass approval.
When the hooks fire
Two hooks call tools/pack-drift-hook. They report; they never block.
- At session start, a list of drifted copies. Something edited a deployed skill since the last
session. Run
drift --diffbefore assuming it was a mistake. - When a SKILL.md under a harness skill root is written, a note that the file is a deployed copy
and not the source. Stop editing there. Edit the Pack and
sync, or finish the edit andacceptit.
Error handling
already owned by Pack 'X'— that destination belongs to another Pack. Rename, or remove the other Pack's copy first.is a symlink: another installer owns that skill— correct refusal. See the table above.- A Pack is deployed to a harness that is no longer installed. The copies are inert, not harmful. Remove them with that harness's own CLI, or leave them for a reinstall — but say which, because an unexplained skill root is what made this tool necessary.
- A skill should exist in every harness and only one has it. That is a deploy, not a sync:
tools/packs-<harness> deploy <pack>, then re-read the matrix.