| name | upstream-ai-sync |
| description | Trigger: update skills, commands, agents, orchestrator assets. Sync upstream AI into the @ai canonical tree while preserving local policy. |
| license | Apache-2.0 |
| metadata | {"author":"iperez","version":"3.0"} |
Activation Contract
Load this skill when updating local skills, commands, agents, SDD prompts, AGENTS files, or orchestrator assets from upstream AI toolkits into the canonical Home Manager tree at /home/iperez/.config/home-manager/ai/ (referred to as @ai).
Two upstream sources participate:
~/.cache/tabularium-ai/upstream-ai-toolkit/ — gentle-ai (multi-client meta-toolkit; per-client assets under internal/assets/{claude,codex,opencode,generic,skills,gga,gemini,antigravity,windsurf,cursor,kimi,qwen,kiro,hermes}).~/.cache/tabularium-ai/gentle-pi/ — gentle-pi (Pi-specific npm package; assets under assets/{agents,chains,support,orchestrator.md}, extensions/, prompts/, skills/).
Canonical Source vs Runtime — Read First
@ai (/home/iperez/.config/home-manager/ai/) is the single source of truth. It is git-tracked inside the Home Manager repository. Every sync write lands here and nowhere else.
The old Tabularium AI hub is dead. The Tabularium notes dir (NOTES_DIR) is now only Obsidian notes, not a harness hub. Never sync harness assets into it and never treat it as a client tree.
Runtime install is by Nix projection, NOT by this skill. Home Manager (home-manager/global/ai-harness.nix) is the authoritative projection map: it symlinks each ai/<...> source to its runtime location from /nix/store, or renders secret templates at activation. This skill edits @ai sources only; home-manager switch deploys them.
Hard consequence — never write into runtime dirs (~/.claude, ~/.config/opencode, ~/.codex, ~/.agents, ~/.pi/agent). They are Nix-managed (read-only store symlinks or activation-rendered files). Edits there either fail or are clobbered on the next home-manager switch. A projection preflight also aborts switch if a projection target is an unmanaged file/symlink, so never create stray files at any target path.
Projected resources (source under ai/ -> runtime target)
Taken verbatim from ai-harness.nix projectedResources:
Source under ai/ | Runtime target |
|---|
skills | .agents/skills (shared/canonical skills) |
opencode/AGENTS.md | .config/opencode/AGENTS.md |
opencode/ORCHESTRATOR.md | .config/opencode/ORCHESTRATOR.md |
opencode/agent | .config/opencode/agent |
opencode/commands | .config/opencode/commands |
command | .config/opencode/command |
opencode/prompts | .config/opencode/prompts |
opencode/skills | .config/opencode/skills |
opencode/tui.json | .config/opencode/tui.json |
claude/CLAUDE.md | .claude/CLAUDE.md |
claude/sdd-orchestrator.md | .claude/sdd-orchestrator.md |
claude/engram-protocol.md | .claude/engram-protocol.md |
claude/agents | .claude/agents |
claude/commands | .claude/commands |
claude/skills | .claude/skills |
codex/AGENTS.md | .codex/AGENTS.md |
codex/sdd-orchestrator.md | .codex/sdd-orchestrator.md |
codex/engram-instructions.md | .codex/engram-instructions.md |
codex/engram-compact-prompt.md | .codex/engram-compact-prompt.md |
codex/commands | .codex/commands |
codex/agents | .codex/agents |
codex/skills | .codex/skills |
Secret-bearing configs (NEVER hold real tokens)
These carry @VAR@ placeholders and are rendered or merged at activation from the secret env files. Preserve the placeholder form; never expand or commit a secret value.
- Rendered whole-file:
opencode/opencode.jsonc -> .config/opencode/opencode.jsonc; pi/mcp.json -> .pi/agent/mcp.json.
- Merged (MCP/section-only into an agent-owned file):
claude/mcp-servers.json -> .claude.json; codex/mcp-servers.toml -> .codex/config.toml; claude/settings-merge.json -> .claude/settings.json.
Managed provider subset
@ai mirrors only claude, codex, opencode, plus the shared ai/skills and ai/command, plus ai/pi/mcp.json (secret template only). Upstream gentle-ai ships many more providers (claude, opencode, codex, generic, gemini, cursor, kimi, kiro, qwen, windsurf, antigravity, gga, hermes, skills — the current //go:embed roots in internal/assets/assets.go). Map upstream onto the user subset only:
| Upstream | User target |
|---|
claude | ai/claude |
codex | ai/codex |
opencode | ai/opencode |
skills (and root skills/) | ai/skills and per-client mirrors ai/{claude,codex,opencode}/skills |
generic / shared-agnostic behavior | ai/shared authoring layer |
The other upstream providers (gemini, cursor, kimi, kiro, qwen, windsurf, antigravity, gga, hermes) are intentionally NOT managed. Do not create them.
ai/shared/ is an authoring layer, not projected
Only the per-client files in the projection table are deployed. ai/shared/ORCHESTRATOR.md, ai/shared/AGENTS.md, and ai/shared/engram-protocol.md are the canonical behavioral contract that the per-client copies (ai/opencode/ORCHESTRATOR.md, ai/claude/sdd-orchestrator.md, ai/codex/sdd-orchestrator.md, and the rendered engram files) MUST stay in parity with. Nothing auto-generates the per-client copies from shared; parity is enforced by keeping them aligned by hand.
Pi boundary
~/dev/personal/pi-harness and ~/.pi/agent remain valid Pi targets, handled separately. Pi's runtime comes from the external pi-harness flake input, not from @ai. The only Pi asset that lives in @ai is ai/pi/mcp.json (a secret template projected to .pi/agent/mcp.json). Keep Pi handling, but do not fold pi-harness assets into the @ai projection.
Core Principle — 1:1 + Customization Layer
Upstream is the source of truth for structure, asset surface, and content. Local customizations layer on top. Order of operations: mirror upstream -> strip persona/branding -> re-apply known user customizations. Never silently drop an upstream asset; never silently overwrite a user customization.
Stripped from upstream during sync
- "Gentleman" persona text,
persona-gentleman.md, output-style-gentleman.md, persona-mode switching prompts.
- Branding strings:
el Gentleman, gentleman-programming, @Gentleman-Programming, Gentle AI, gentle-orchestrator. Replace identifiers with neutral equivalents (sdd-orchestrator, iperez, etc.). Keep gentle-ai/gentle-pi only when referring to the upstream toolkit by name in documentation.
- Startup banner branding text in gentle-pi's
extensions/startup-banner.ts (keep any functional behavior; remove only the branded text).
Preserved as user customizations (layer back on after upstream copy)
| Customization | Where it applies |
|---|
.agents/ paths instead of .atl/ | every skill-registry, sdd-init, and orchestrator reference |
Obsidian as 5th artifact_store.mode | sdd-init, orchestrator, skills/_shared/persistence-contract.md, skills/_shared/obsidian-convention.md |
Pi model assignments (openai-codex/gpt-5.4 for SDD agents, etc.) | pi-harness assets/agents/*.md frontmatter |
Engram + Obsidian as default persistence, no openspec/ in repos | skills/_shared/persistence-contract.md, orchestrator artifact-store text |
| Inlined Engram protocol in per-client orchestrators | claude/sdd-orchestrator.md, codex/sdd-orchestrator.md, opencode/ORCHESTRATOR.md, pi-harness assets/orchestrator.md |
User-authored skills not present upstream: obsidian, dbflux-release, find-skills, upstream-ai-sync | canonical ai/skills + every client mirror |
User-authored agents: bug-hunter, pr-reviewer (claude/opencode) | claude/agents/, opencode/agent/ |
author: iperez in skill frontmatter | every skill SKILL.md |
Current gentle-ai (v2.0) awareness — runtime-only caveat
Current gentle-ai (v2.0) introduced a runtime-backed review/delegation lifecycle enforced by the gentle-ai Go binary: bounded review transactions (internal/components/reviewtransaction), receipts/CAS, a frozen-ledger validation lifecycle, and native OpenCode general/explore agent routing. These CANNOT be reproduced by prompt assets alone.
Rule: when syncing behavior from these areas, port only the prompt-expressible portion into @ai's prompt/orchestrator assets, and explicitly document the runtime-only remainder as not-reproducible instead of faking it with sub-agent gymnastics. This prevents the harness from inheriting gate rules it cannot actually execute.
Hard Rules
- Work only in
/home/iperez/.config/home-manager/ai (@ai), the pi-harness repo, and the upstream caches under /home/iperez/.cache/tabularium-ai/, unless the user names another target.
- Never write into runtime dirs (
~/.claude, ~/.config/opencode, ~/.codex, ~/.agents, ~/.pi/agent). They are Nix-managed. Edit @ai sources; home-manager switch deploys them.
- Never create a stray file at any projection target path; the projection preflight aborts
switch on unmanaged targets.
- Do not run
home-manager or any mutating deployment command as part of this skill unless the user explicitly asks.
- Do not modify either upstream checkout except
git clone, git fetch, git pull --ff-only, or read-only inspection.
- Snapshot before writing, OUTSIDE the nix git repo: copy current state of every target directory to
~/.cache/tabularium-ai/sync-snapshots/YYYYMMDD-HHMMSS/ before any modification. Never snapshot into @ai; that would pollute the git-tracked config.
- For secret-bearing configs, preserve
@VAR@ placeholder form; never expand or commit a real secret value.
- For PRESENT_DRIFT files: classify the drift before acting. If drift is in the "preserved customizations" table above, KEEP local. If drift is in a section the user has not touched (visible from snapshot history) and upstream changed, ADOPT upstream content while re-applying preserved customizations. If drift is ambiguous, ASK the user.
- For MISSING_IN_USER files: only when the asset maps into the managed subset (claude/codex/opencode/shared skills/command). Copy from upstream, strip persona, apply customizations, write to the
@ai source. Mirror to each relevant client tree. Do NOT create providers outside the managed subset.
- For USER_ONLY files: if listed in "preserved customizations", KEEP. Otherwise flag for user decision; do not auto-delete.
- Sync whole skill packages, not only
SKILL.md; preserve every file under the skill directory, including assets/, references/, and direct companion files (strict-TDD guides, etc.).
- Before syncing skills, inspect upstream
docs/skill-style-guide.md if present and preserve new frontmatter fields such as disable-model-invocation and user-invocable.
- Resulting instruction assets must use neutral personality and remove visible branding/persona references unless the identifier is technically required.
- Obsidian and Engram are always the planning/spec persistence backends; do not write OpenSpec artifacts into a normal repo tree unless explicitly requested.
- An orchestrator must never delegate to another orchestrator; prefer non-blocking sub-agent delegation.
- Do not sync generated validation fixtures, local runtime state, user backups, auth files, caches, or project planning artifacts unless the user explicitly asks for that exact target.
- Do not sync the pi-harness Engram extension surface from gentle-pi; engram is handled separately. Touching
pi-harness/extensions/ requires explicit user instruction.
- Enforce provider parity: when upstream changes a behavior (engram protocol, SDD orchestrator rule, persona/branding contract), inspect every parallel file listed in
references/provider-parity.md so the same behavior is present in all managed provider copies and reported for the pi-harness orchestrator.
Provider Parity Protocol
The upstream toolkit ships one behavioral contract rendered as per-provider variants. @ai keeps a per-client copy for claude, codex, and opencode, with ai/shared/ as the canonical contract. The sync skill MUST keep the managed variants in lockstep when a behavior changes, and MUST flag pi-harness assets/orchestrator.md updates (pi-harness is not in this skill's write scope, but its orchestrator is the runtime union of all provider variants). See references/provider-parity.md for the asset matrix, parallel file sets, per-provider formatting rules, and the pi-harness handling rule.
Decision Gates
| Situation | Action |
|---|
| MISSING_IN_USER, maps into managed subset | Copy upstream -> strip persona -> apply preserved customizations -> write to @ai source and every relevant client mirror. |
| MISSING_IN_USER, outside managed subset | Do NOT create; note as intentionally unmanaged. |
| PRESENT_1to1 (byte-identical) | No action. |
| PRESENT_DRIFT, drift matches preserved-customization table | KEEP local. |
| PRESENT_DRIFT, upstream-only changes in untouched sections | RESYNC content from upstream; re-apply preserved customizations. |
| PRESENT_DRIFT, both changed same section | ASK before writing unless purely mechanical (whitespace, em-dash normalization). |
| USER_ONLY in preserved-customization table | KEEP. |
| USER_ONLY not in table | FLAG for user decision; do not auto-delete. |
| Branding/persona content in upstream | STRIP during sync; never propagate to user files. |
| Persistence conflict | Obsidian + Engram wins. |
| Runtime-only behavior (v2.0 review/ledger/CAS/native agent routing) | Port prompt-expressible portion only; document the runtime remainder as not-reproducible. |
Execution Steps
- Prepare/update both upstream caches; record commit SHAs for
upstream-ai-toolkit and gentle-pi.
- Snapshot every target tree under
~/.cache/tabularium-ai/sync-snapshots/YYYYMMDD-HHMMSS/ BEFORE any write. Never snapshot into @ai.
- Inspect
internal/assets/assets.go in gentle-ai to discover currently embedded asset roots. Inspect assets/, extensions/, prompts/, skills/ in gentle-pi to discover its surface.
- Map each relevant upstream asset onto the managed
@ai subset (claude/codex/opencode/shared skills/command). Ignore providers outside the subset.
- Inventory upstream surfaces:
- gentle-ai:
internal/assets/skills/**, root skills/**, docs/skill-style-guide.md, docs/agents.md, and the claude/codex/opencode/generic per-client assets.
- gentle-pi:
assets/agents/**, assets/chains/**, assets/support/**, assets/orchestrator.md, extensions/**, prompts/**, skills/**.
- Compare against the local
@ai sources: ai/{claude,codex,opencode}/, ai/skills/, ai/command/, ai/shared/, and ai/pi/mcp.json; plus pi-harness assets/ handled separately.
- For each file, classify as PRESENT_1to1 / PRESENT_DRIFT / MISSING_IN_USER / USER_ONLY and apply the Decision Gates table.
- After applying upstream updates, verify behavior changes are reflected across ALL managed provider files per
references/provider-parity.md. Walk each parallel file set for the changed surface (engram, SDD orchestrator, persona, commands), including ai/shared/ as the canonical contract. Where pi-harness assets/orchestrator.md would need an update, emit an explicit "pi-harness update required" line with the exact paragraph(s) to add.
- For any behavior originating in v2.0 runtime areas (review transactions, receipts/CAS, frozen-ledger validation, native
general/explore routing), port only the prompt-expressible portion and record the runtime-only remainder as not-reproducible.
- Validate skill frontmatter against upstream tests, recursive skill package copying, branding policy, neutral policy, Obsidian+Engram policy, no orchestrator-to-orchestrator delegation, non-blocking delegation preference, and
@VAR@ placeholder integrity.
- Final validation: grep
@ai (and, if in scope, pi-harness) for residual persona/branding strings (target: zero hits). Grep for .atl/skill-registry (target: zero hits). Confirm no real secret values leaked into secret-bearing configs. Confirm preserved customizations are intact.
Output Contract
Return upstream cache path and commit, compared counts for skills/references/commands/agents/orchestrators, updated @ai source files, kept-local files, conflicts requiring decision, any runtime-only behavior noted as not-reproducible, and validation results. Remind the user that changes take effect only after home-manager switch.
References
references/sync-details.md — canonical @ai paths, projection targets, upstream locations, secret-config rules, snapshot location, merge rules, and report template.references/provider-parity.md — per-provider standardization pattern, asset matrix for the managed subset, behavior contract rule, parallel file sets, pi-harness handling, and provider-specific adaptation rules (markdown dialect, tool surface, loader mechanism).
