Synchronizing skills from Penelope into the seam
Define how skills that reach production are synchronized from the source of truth into the GEB seam (skills/) so that both planes — Paperclip (governance) and Fusion (execution) — can consume them when a trigger fires.
It expands §6 ("Skills are consumed from the seam and synced from Penelope") and §10 (open items) of the high-level architecture proposal. The same mechanism is intended to be reused for Octaflow.
In scope: the synchronization mechanism (source → seam), its invariants, and a comparison of feasible options with a phased recommendation.
Out of scope: how skills are authored, their internal file architecture, and the run-time resolution of a skill during a mandate.
The current approach
Skills are authored across the company and then "deployed" by copying them into a shared Google Drive folder. To use them, the mechanism today is manual download: someone pulls the folder from Drive and drops the skill into the folder that needs it.
Penelope — the intended long-term source of truth, a vertical factory of skills and agents, is still under construction. It is not yet a production system and exposes no export path. Until it is ready, the company keeps producing skills and dropping them on Drive, so the near-term source of truth is effectively "Drive + the authoring repos," not Penelope.
Zero infrastructure and no dependency on Penelope being finished. The high-level proposal explicitly names this as the interim approach.
What it costs us (limits of manual Drive copy)
| Limit | Consequence |
|---|---|
| No versioning / pinning | We can't say which version of a skill a given run used; two machines can diverge. |
| No provenance / integrity | No record of where a skill came from or that it wasn't altered in transit. |
| No promotion boundary | "In the folder" is the only signal of "production"; anyone editing the folder ships to prod. |
| No scan gate | Nothing forces an agentshield scan before a skill goes live (a shared skill is a shared supply-chain surface). |
| No rollback | Reverting to a previous good version is manual and error-prone. |
| Not auditable | No log of what synced, when, or with what result. |
| Doesn't scale / two planes | Manual placement into Fusion and the Paperclip package is easy to get wrong. |
The mandate & future direction
Even though the mechanism is not yet chosen, skills that reach production must be synchronized from the source of truth into the seam through an automated, pinned, scanned, auditable path. Manual copy is a stopgap, not the destination.
Two horizons
- Interim (now): the source is Drive + the authoring repos; Penelope is not ready and there is no defined promotion-to-production signal. We need a mechanism that works today and already adds pinning, scanning, and auditability.
- Target (when Penelope is ready): the source becomes Penelope's export (an API, a registry, or a repository it publishes to). The seam-side machinery should not have to change, only the source connector does.
What makes both horizons the same architecture: a stable consumer contract at the seam, a swappable source.
Design invariants
These are the requirements that make the options comparable. Any chosen mechanism has to meet all of them.
SKILL.md + GATES.md + SECURITY.md + modules + evals as configured), not a single file. A sync may carry multiple bundles; each is applied all-or-nothing and pinned independently.skills.lock records the exact version (commit / tag / semver / checksum) of every bundle currently live in the seam. A run is reproducible from the lock.agentshield before it goes live; a failing scan blocks promotion.skills/; the sync lands each bundle where both planes read it. Sync is not "done" until both planes see the bundle.production tag/branch/folder or a manifest listing production bundles + versions) is a prerequisite, independent of which transport we pick.The alternatives
Each option is a source connector; all of them feed the same seam-side pipeline (verify → scan → pin → project → audit). Options are ordered from smallest delta over today to most capable.
What it is: the status quo — download the Drive folder, drop bundles into the seam by hand.
How it works: human pulls Drive → copies bundle → manually places into each plane.
Advantages: zero infrastructure; works today; no dependency on Penelope.
Risks: every limit in §2 — no pinning, provenance, scan, rollback, or audit; per-plane placement done by hand; drift between machines.
Maintainability: poor — entirely manual, doesn't scale past a handful of skills.
Cost: ~$0 infra, high recurring labor and high error cost.
Integrity & rollback: none / manual.
What it is: keep Drive as the deploy target, but automate the pull.
How it works: a scheduled + on-demand job authenticates with a Google service account, watches the production Drive folder (Drive API change list or polling), mirrors changed bundles into the seam, runs agentshield, and updates skills.lock.
Advantages: smallest delta from today; preserves the team's existing "deploy to Drive" habit; adds pinning, scanning, and audit without changing anyone's workflow.
Risks: Drive is not an artifact store — folders are mutable, versioning/provenance are weak, and "production" is just "in the folder" (weak promotion boundary); API quotas; service-account key management/rotation; harder to pin an exact immutable version.
Maintainability: medium — a Drive API client, quota handling, and key rotation to own.
Cost: infra ~$0 (Drive + a small job); moderate build effort for the connector.
Integrity & rollback: checksums yes; rollback only if the job keeps prior versions (Drive won't do it for us).
What it is: a Git repository is the distribution point; the seam pulls a pinned ref. Because skills are already authored in git repos, this is available now — a dedicated "skills mirror" repo can be the promotion boundary before Penelope exists (merge to it = promotion).
How it works: production bundles live on a production branch/tag (or a dedicated mirror repo); the seam pulls the pinned ref (fetch-tag script / git submodule / git subtree / sparse-checkout), read-only, scheduled + on-demand; skills.lock = the commit/tag; agentshield runs before promotion.
Advantages: versioning, provenance, diff, and rollback are native to git; trivial pinning; PR review gives a real promotion gate and audit trail; ubiquitous tooling; effectively free; aligns with the companies.sh direction in the operating manual.
Risks: needs a clean production boundary in git (branch/tag or mirror repo), which we'd have to set up; submodule ergonomics; credentials for a private repo.
Maintainability: low–medium — mostly a pull script + a branch/tag convention.
Cost: infra ~$0 (GitHub); low build effort.
Integrity & rollback: commit hashes give integrity + provenance; rollback = check out the previous pinned ref. (Add tag signing for stronger integrity.)
What it is: each production bundle (or a bundle-of-bundles) is published as a versioned, immutable package; the seam installs pinned versions.
How it works: a publish pipeline (Penelope's CI, or an interim CI over the authoring repos) packages a bundle and pushes it to a registry (npm / GitHub Packages / GHCR as an OCI artifact via oras); the seam installs by semver into skills/, pinned in skills.lock; scan on install.
Advantages: immutability + semver + provenance/signing out of the box; clean rollback (install the prior version); decouples the consumer from the source's internals; this is the "catalogue / registry" target named in §10.
Risks: requires a publish pipeline and a packaging format for a skill bundle; more moving parts than git; overkill until there's a steady stream of production skills.
Maintainability: medium — a pipeline + a registry to run and version.
Cost: infra low (GitHub Packages / GHCR are ~free at our scale); medium build effort.
Integrity & rollback: strongest — immutable versions, checksums, optional signing; rollback is a version pin.
What it is: when Penelope's backend is ready, it exposes a read-only export: a manifest of production bundles and a download-by-id@version endpoint. Optionally, Penelope pushes a webhook on promotion.
How it works (pull): the seam job fetches the manifest, diffs it against skills.lock, downloads changed bundles, verifies + scans, projects into both planes. Push variant: Penelope fires a webhook to the node's gateway on promotion → the node triggers the same pull (low latency), reusing the ingress that already receives Shopify webhooks.
Advantages: decoupled from Penelope's internal storage; Penelope owns the promotion boundary centrally; supports event-driven low-latency sync; a clean contract that survives Penelope's internal changes.
Risks: depends on Penelope being built and on an API being designed (auth, availability, versioning), not available today; an API is a product surface to own; the node must authenticate to it.
Maintainability: medium–high — a real API on the Penelope side plus the seam client.
Cost: dev cost to build the export (Penelope side); hosting minor.
Integrity & rollback: good if the manifest carries versions + checksums; rollback = pin the prior manifest entry.
Comparison matrix
Legend: ●●● strong · ●● adequate · ● weak. "Available now" = feasible before Penelope is production-ready.
| Dimension | A · Manual Drive | B · Auto Drive | C · Git mirror | D · Registry | E · Penelope API |
|---|---|---|---|---|---|
| Available now | ●●● | ●●● | ●●● | ●● | ✕ |
| Pinning / versioning | ✕ | ●● | ●●● | ●●● | ●●● |
| Integrity & provenance | ✕ | ● | ●● | ●●● | ●● |
| Rollback | ✕ | ● | ●●● | ●●● | ●● |
| Promotion boundary | ✕ | ● | ●●● (PR) | ●●● (publish) | ●●● (central) |
| Review / audit gate | ✕ | ● | ●●● | ●● | ●● |
| Event-driven capable | ✕ | ● | ● | ● | ●●● |
| Maintainability | ●●● (trivial, manual) | ●● | ●●● | ●● | ● |
| Infra cost | ●●● (~$0) | ●●● | ●●● | ●●● | ●● |
| Build effort (lower = better) | ●●● | ●● | ●●● | ●● | ● |
| Fit as long-term target | ✕ | ✕ | ●● | ●●● | ●●● |
C (git mirror) leads for what we can do now — pinning, review, rollback, and audit at ~$0 — while D (registry) and E (Penelope API) lead as long-term targets. A and B trade capability for a smaller delta from today.
Recommendation & phasing
The recommendation follows the thesis: keep the seam-side pipeline fixed, phase the source connector.
Stand up a dedicated skills-mirror repo (or a production branch of an existing one) as the explicit promotion boundary; the seam pulls a pinned ref, runs agentshield, writes skills.lock, and projects into both planes. Where a skill only exists on Drive today, promoting it = a PR into the mirror. This gives us pinning, review, rollback, and audit immediately, at ~$0 infra. Use Option B only if keeping Drive as the entry point is a hard requirement (see open question) — B can feed the git mirror.
Option E (API/manifest, webhook-driven), or Option D (registry) as its publishing substrate. Penelope becomes the source of truth and owns the promotion boundary; promotion in Penelope drives the sync. Only the source connector changes — the verify → scan → pin → project → audit pipeline built in Phase 0 stays.
Why this shape: every phase reuses the same seam-side machinery, so Phase 0 is not throwaway work — it is the consumer half of the target architecture. The decision we defer (Drive vs. git vs. Penelope) is isolated to one swappable component.
What must be true to adopt Phase 0
- A promotion boundary is defined (the mirror repo/branch is the minimum viable one).
- The projection step into the seam's skills folder is implemented and tested on one skill end-to-end.
agentshieldruns in the path and can block.
Open items & questions
Decisions and prerequisites that shape the exact Phase 0 build and the eventual target.
Do we keep Drive as the authoring/deploy entry point (org standard) and put a mechanism on top of it (Option B feeding C), or replace it with git as the distribution layer? This is unresolved and affects Phase 0's exact shape.
There is no defined signal today. It must be defined regardless of transport — the minimum viable version is "merged into the skills-mirror repo/branch"; Penelope should later own it natively.
Once Penelope is built: API pull vs. registry publish vs. repo push, and whether promotion emits a webhook. Tracked from §10 of the high-level proposal.
Whether to sign bundles (tag signing for C, artifact signing for D) for stronger supply-chain integrity beyond checksums.
What an agentshield scan consists of
The scan gate (invariant 4, the SCAN step of the §5 pipeline) is where agentshield runs. Because every synced skill becomes part of what an agent will read and act on, a skill bundle is treated as untrusted code from outside the trust boundary until it passes.
A skill is not passive content — it is instructions an agent will follow and tool permissions it may exercise. A shared skill library is therefore a shared supply-chain surface: one poisoned or careless bundle, synced once, is inherited by every agent and every run on both planes. The scan is the last check between "someone published a bundle upstream" and "our agents execute it."
What the scan inspects (bundle-level)
The scan reads the whole bundle (SKILL.md, modules, GATES.md, SECURITY.md, evals, and any scripts or assets) and looks for:
- Injected or hidden instructions. Prompt-injection payloads in the skill text or modules that try to redirect the agent (e.g. "ignore your instructions", "exfiltrate…", instructions hidden in comments, zero-width or homoglyph text, or content that tells the agent to treat retrieved data as commands).
- Tool use beyond the declared blast radius. Directives that push the agent to act outside what the bundle's own
SECURITY.mddeclares — unexpected file writes outside scope, destructive operations, privilege or scope escalation. - Network egress & untrusted fetches. URLs the skill would fetch, calls to external endpoints, or instructions to send data out — anything that could exfiltrate context or pull remote, unvetted instructions at run time.
- Secrets & credentials. Hard-coded tokens, keys, or credentials that must never ship in a bundle.
- Unsafe executable content. Inline shell, scripts, or commands that run with side effects, especially anything destructive or that reaches outside the workspace.
- Manifest consistency. Whether the bundle's behaviour matches its declared
SECURITY.md— blast radius, side effects, trust boundaries, and the stated invariants. A skill that does more than it declares fails here. - Integrity drift. That the bundle content matches its checksum/expected version from the source (works together with the Verify step, invariant 5).
How it runs in this pipeline
- It sits between Verify and Pin (§5): a bundle is only pinned in
skills.lockand projected into the planes after it passes. - The scan produces a pass/fail plus a findings report. A failing scan blocks promotion — the bundle does not go live, and the failure is written to the audit log (invariant 9).
- It runs on every bundle on every sync, not once at onboarding — an upstream change can introduce a problem a later version didn't have.
agentshield is the name of the scan gate in this architecture; the exact rule set and tooling are a configuration detail to be specified when the gate is implemented. What is fixed here is its place and contract in the pipeline (untrusted-by-default, blocks on fail, runs every sync, findings audited), not a final list of checks.