Skip to content

t1k:sync-back

FieldValue
Modulet1k-kit-feedback
Version2.14.39
Efforthigh
ToolsAskUserQuestion, Bash, Edit, Glob, Grep, Read, Skill, Task, Write

Keywords: contribute, gotcha, pr, propagate, push, sync, upstream

/t1k:sync-back
[<skill-name>|<file-path>] [--dry-run|--force|--already-pushed=pr=N]

TheOneKit Sync-Back — Push Changes to Kit Repos

Section titled “TheOneKit Sync-Back — Push Changes to Kit Repos”

Push $HOME/.claude/ changes (skills, agents, rules) back to their origin kit repos as PRs. Uses GitHub MCP tools — no local clone needed.

This skill is the canonical mechanism for the kit-wide-fix discipline. See rules/kit-wide-fix-discipline.md — local-only edits regress on next t1k modules update; sync-back closes the loop by opening a kit-source PR.

/t1k:sync-back # NO ARGS = sync EVERYTHING (all unsynced files under both scan roots)
/t1k:sync-back <skill-name> # Scope to one skill, e.g. /t1k:sync-back t1k-unity-docs
/t1k:sync-back <file-path> # Scope to one file (relative to a scan root)
/t1k:sync-back <target> --dry-run # Plan + diff only, no PR
/t1k:sync-back --force # Skip confirmation. Diff is ALWAYS shown.
/t1k:sync-back <target> --already-pushed=pr=N
# Branch+PR already exist (manual or prior sync);
# skip clone/push/PR-create; verify + record telemetry only.

No-args mode = sync everything (MANDATORY default)

Section titled “No-args mode = sync everything (MANDATORY default)”

When invoked with no positional arg and no flags:

  1. Always run the full scan. Walk $HOME/.claude/ AND <cwd>/.claude/ per references/routing-and-paths.md Step 0. Do NOT short-circuit on an empty lesson queue — the queue is one input among many, never the only one.
  2. Sync every candidate found. Group by origin kit/repo per references/routing-and-paths.md Step 3 and open one PR per repo, multi-skill if needed.
  3. Never ask “what task did you mean?” A no-args invocation is an explicit instruction to sync the entire pending set. Treat it the same way git status && git add -A && git commit treats no args — process everything.
  4. If the full scan finds zero candidates, exit cleanly with:
    No pending changes to sync. Scanned: $HOME/.claude/ and <cwd>/.claude/. Lesson queue: empty. Working tree: clean vs origin.
    This is success, not a prompt for input.
  5. Anti-pattern: the sub-agent fork seeing /t1k:sync-back with no args and replying “I’ll wait for your actual task” — this happened in the May 2026 sessions. The skill MUST proceed with the full scan; clarification questions are forbidden in no-args mode.

The first non-flag token is the target. Resolution order:

  1. Skill name — if $HOME/.claude/skills/<token>/ OR <cwd>/.claude/skills/<token>/ exists, sync everything under that directory only.
  2. File path — if the token resolves to a file under a scan root (with or without the $HOME/.claude/ prefix), sync just that file.
  3. No match → HARD-FAIL: "Target '<token>' is neither a skill name nor a file under $HOME/.claude/ or $(pwd)/.claude/. Did you mean: <5 nearest skill names>?" Do NOT silently fall back to full-tree discovery — that mis-reports scope and surprises the user.

Tokens starting with - are flags, never targets.

Sub-agent context loss: sync-back invoked from a sub-agent fork loses the parent’s conversation context. The skill MUST work from arg + filesystem state alone — never assume conversation memory. No-args = scan everything; explicit-target = scope to that target. Both modes are self-contained.

Scope — Consumer Projects Only (MANDATORY)

Section titled “Scope — Consumer Projects Only (MANDATORY)”

Do NOT invoke when CWD is a kit source repo (theonekit-core, theonekit-unity, theonekit-cli, theonekit-designer, theonekit-cocos, theonekit-rn, theonekit-web, theonekit-nakama, theonekit-release-action, t1k-telemetry-worker). Those repos ARE the origin — commit directly. See references/consumer-guard.md.

Invocation Mode (MANDATORY — Background Sub-Agent)

Section titled “Invocation Mode (MANDATORY — Background Sub-Agent)”

This skill MUST run as a background sub-agent via the Task tool, NEVER inline. Exception: explicit user request (“sync this now”) → run inline so the diff is visible.

See references/sub-agent-invocation.md for the required Task call template, required fields (kitVersion, moduleVersion, cliVersion, platform, rationale), and the auto-lesson writeback protocol (submitted: true, prUrl, fingerprint).

Transport: GitHub MCP first, gh CLI fallback (sandbox-asymmetry-safe)

Section titled “Transport: GitHub MCP first, gh CLI fallback (sandbox-asymmetry-safe)”

Probe BOTH GitHub MCP and gh at sub-agent start (parent access does not guarantee child access). MCP preferred, gh fallback; if neither works DO NOT silently fail: refuse, report submitted: false reason transport-unavailable-in-child-sandbox. Full procedure: references/transport.md.

Decision tree — which reference do I load?

Section titled “Decision tree — which reference do I load?”

Load only the reference you need (each is self-contained):

IntentLoad
Check if CWD is a consumer project (first step, always)references/consumer-guard.md
Sub-agent invocation template + auto-lesson writeback contractreferences/sub-agent-invocation.md
Pre-flight checks (MCP, repo access, staleness, missing-target structural-stall guard)references/preflight-checks.md
Cross-ref health pre-check — don’t inherit red CI from a pre-existing-broken mainreferences/crossref-health-precheck.md
Created-artifact completeness — the diff CREATES a skill dir, an agent file, a tests/ dir, or a scriptreferences/created-artifact-completeness.md
Pre-triage block — gate pre-checks always; review fields only if askedreferences/pre-triage-review.md
Three-round self-review — only if the user asked for a reviewreferences/three-round-review.md
Self-watch to MERGED after the PR opens (arm auto-merge, run t1k-pr-watch.cjs --cleanup-worktree, react to red)references/babysit-until-merged.md
Ctx-budget headroom check — diff touches any .claude/rules/*.mdreferences/ctx-budget-headroom.md
Resolve file origin + compute target path in kit reporeferences/routing-and-paths.md
Carry a blind-edit shape pack (no-origin fixture trees, new-file 404s)references/shape-pack-carry.md
Open the PR (branch → push → create, fork flow, PR body template)references/open-pr.md (required body sections: skills/t1k-git/references/pr-body-required-sections.md)
Writeback submitted: true to the lesson queuereferences/queue-writeback.md
Error table, cross-platform notes, what gets synced / excludedreferences/error-handling.md

Gate tier — scale the ceremony to the diff

Section titled “Gate tier — scale the ceremony to the diff”

Resolve the tier ONCE, from the captured payload, before loading any conditional reference. A one-line diff must not pay the ceremony of a 20-file multi-kit sync.

Diff shapeTier
One kit, ≤3 files, no .claude/rules/*.md, no skill/agent create or rename, no module.jsonfast
Anything else — multi-kit, >3 files, touches rules/*.md, creates/renames a skill or agent, touches module.jsonfull

Fast tier skips: references/ctx-budget-headroom.md (n-a — no rules/*.md in the diff), t1k-skill-creator validate when the diff touches no SKILL.md / references/*.md, and the naming-prefix + modules-registry gates (n-a by construction). Steps 3–4 of references/pre-triage-review.md collapse to one line each: generic: <1 sentence> and adversarial: n/a — trivial diff.

Fast tier never skips: Pre-flight Step 0 in full, and the secret / absolute-path / empty-file scans. In particular the main cross-ref pre-check is NOT tiered — it validates the target kit’s main tree, not your diff, so a one-line PR inherits a red main exactly like a large one; it is one sub-second script run, not agent reasoning.

Record the resolved tier in the PR body: **Gate tier:** {fast | full}.

Created-Artifact Completeness — MANDATORY when the diff CREATES a path

Section titled “Created-Artifact Completeness — MANDATORY when the diff CREATES a path”

Adding a file to a kit moves the kit’s registry shape, and the kit’s own CI gates assert that shape — so a diff that creates a skill dir, an agent file, a tests/ dir, or a script owes more than the file itself. Two shapes land red silently: a new tests/ directory whose package-lock.json was never committed (the receiver’s bun install --frozen-lockfile gate hard-fails EUSAGE), and a new skill whose doc projections were never updated (the receiver’s registry-consistency gate fails on a hand-edited count across README.md, CLAUDE.md, docs/module-system.md and the per-module page — which also needs the new skill’s own row).

Enumerate created paths, run the receiver kit’s own gates, and refuse to push on red. That one step subsumes both shapes and any kit whose bullet nobody has written yet. Obligations + worked reproduction: references/created-artifact-completeness.md.

Pre-Triage Review — gate pre-checks mandatory, review fields opt-in

Section titled “Pre-Triage Review — gate pre-checks mandatory, review fields opt-in”

Every sync-back PR MUST contain a ## Pre-Triage Review block: risk classification and gate pre-check results (mandatory, mechanical). Its review fields (generic rationale, adversarial self-review, triage disposition) are filled only when the user asked for a review (docs/no-unrequested-review.md); otherwise each reads skipped (no review requested).

Procedure + body template + failure modes (refuse-to-PR cases): references/pre-triage-review.md. The block sits AFTER ## Changed files in references/open-pr.md’s PR body template.

Three-Round Self-Review — only when the user asked for a review

Section titled “Three-Round Self-Review — only when the user asked for a review”

No review runs on sync-back’s own initiative (docs/no-unrequested-review.md). When the user asked, the PR body carries ## Three-Round Self-Review (Round 1 correctness/scope, Round 2 consumer blast radius, Round 3 adversarial); otherwise the block reads skipped (no review requested). Rounds come from t1k-verify-tier.cjs classify --classes (rounds); unknown means all three. Procedure + PR body template: references/three-round-review.md.

If this run ever closes, reopens, or retargets its own PR instead of merging it (e.g. superseded by a fresher sync-back PR), the same comment discipline as a merge applies — skills/t1k-triage/references/status-change-requires-comment.md.

Watch to Green and Merged — sync-back owns its own PR

Section titled “Watch to Green and Merged — sync-back owns its own PR”

After gh pr merge <N> --auto --squash --delete-branch (topic-branch head only — never a linked worktree’s home branch: skills/t1k-git/references/worktree-home-branch.md), this run does not return yet. It watches its own PR until every required check is green and the PR is MERGED, fixing a red check its own diff caused, retrying a pre-existing/flaky one once, and stopping to report otherwise — bounded so a routed hop degrades to a named “still pending: <checks>” report instead of hanging or mis-reporting. Full procedure, the two invocation shapes (native sub-agent vs routed hop), and the stop conditions: references/babysit-until-merged.md.

Routed hop — write the merge argv fully literal. A hop arming the merge with the repo in a shell variable (-R $R, --repo $REPO) is denied gh-pr-merge-shape: the guard reads the command text, cannot resolve the variable, and so cannot prove the argv holds no --admin. Name the repo literally (--repo <owner>/<repo>); the same rule applies to every gh verb a hop runs.

The watch polls GitHub: keep a 60 s or longer interval, never loop on a rate-limit 403, and treat it as “waiting on GitHub quota”, not a failed check (skills/t1k-git/references/github-api-limits.md).

After it merges, do NOT reflexively t1k modules update

Section titled “After it merges, do NOT reflexively t1k modules update”

The local file is now correct but the published tag may not be: update before the next tag is cut overwrites your fix. Read the file AT THE TAG first, not at main; pre-fix content means wait for the next release. Procedure, commands and follow-on notes: references/after-merge-update-hazard.md.

Pre-flight Step 0 — Kit-Freshness Guard (MANDATORY)

Section titled “Pre-flight Step 0 — Kit-Freshness Guard (MANDATORY)”

Before ANY other sync-back step (scan, routing, pre-triage, branch creation), the sub-agent MUST run these IN ORDER — the payload is captured before anything can overwrite it:

  1. Capture the payload FIRST. Read every file in the sync-back diff and hold its content (copy to a temp dir) BEFORE running any update. t1k modules update extracts the release ZIP without a per-file content diff, so a local file that has diverged ahead of the kit is silently reverted by it — including the very edit you are here to sync. See rules/prefer-local-over-global-edits.md § “Gotcha”.

  2. Skip the refresh when the payload is ahead of the kit. If a captured file differs from the kit-shipped content it was installed from, do NOT update: sync-back FIRST, let the kit re-release, then update (rules/prefer-local-over-global-edits.md § “Gotcha”, #367 EXCEPTION). Record kit-freshness: skipped (local ahead) in the PR body and jump to step 4.

  3. Otherwise refresh local kits — NON-INTERACTIVELY. Run t1k modules update --yes to pull every installed kit to its latest published tag — on the nothing-pending path this itself prints All modules are up to date. (that string is t1k modules update’s own confirmation, not t1k --version’s). Then run t1k --version as a SECOND confirmation: it prints one badge PER installed kit (<kit>@<tag> ... ✓ up to date or ⚠ update available), never a single global “all clear” line, and local-scope and global-scope installs report separately and can disagree — confirm every kit badge reads ✓ up to date rather than looking for a matching string. The --yes (-y) flag is required, not optional: without it the command ends at an Apply N update(s)? confirm prompt that a background sub-agent can never answer — with stdin closed it exits in ~1s having applied nothing (a silent no-op indistinguishable from “already current”), and with stdin held open it stalls until the Bash tool timeout.

  4. Check GitHub HEAD for unreleased commits — PER FILE. For EACH file in this sync-back diff, run a per-file commit query against the target kit repo:

    Terminal window
    gh api 'repos/The1Studio/<target-kit>/commits?path=<file>&per_page=5' \
    --jq '.[] | {sha: .sha[0:8], date: .commit.author.date, msg: (.commit.message | split("\n")[0])}'

    The ?path= filter is mandatory — the global top-5 view drops per-file commits when the kit is active and unrelated commits push them off the top, producing a silent false-clear. The ?path= value MUST be the kit repo’s real nested path (.claude/modules/<module>/skills/<name>/...), never the consumer-flattened one (.claude/skills/<name>/...) — ?path= returns [] for BOTH “genuinely no commits” and “wrong path”, so a flattened-path guess produces a silent false-clear, and for an “already exists upstream?” check reads as “no upstream home” (duplicate-skill risk). Ground-truth the real path first with git -C <target-kit-clone> ls-tree -r origin/main --name-only | grep -i '<name>', THEN query ?path= with it; if no clone is handy, clone shallow (--depth 1) — git ls-remote cannot substitute (it lists refs, not paths). If the top result for any path is newer than the SHA your local file is based on, READ that commit’s diff via gh api repos/.../commits/<sha> and either rebase local edits onto kit HEAD (clone the kit, cherry-pick) BEFORE opening the PR, or abort the sync-back. Never silently push a stale-base branch.

    Per-file loop example, the naive-3-way-merge-base gotcha (it silently drops corrections that predate your reconciliation commit), the REQUIRED detection step (diff the merge OUTPUT against local-current before every sync-back commit) and the real instance: skills/t1k-rsi/ledger/gotchas/t1k-sync-back.md.

  5. Cross-ref health check against main (MANDATORY). Before pushing the branch, run check-skill-cross-refs.cjs against the target kit’s current main tree (in the kit clone you opened for the PR). If main already has broken skill cross-refs, every new sync-back PR inherits that red gate. Pre-existing breakage → either bundle the fix in this PR or refuse + surface (submitted: false, error: "main-crossref-broken: <refs>"). NEVER open a PR you know will land red on a pre-existing-broken main. Full procedure + decision table + PR-body record: references/crossref-health-precheck.md.

  6. Only after steps 1–5 pass clean, proceed to the normal sync-back flow (scan, routing, pre-triage, etc.).

See references/step0-rationale.md for why Step 0 exists and its narrow exceptions (do not skip Step 0 on your own judgment).

Step 0.6 — Issue Claim Check (when sync-back is for an issue-linked change)

Section titled “Step 0.6 — Issue Claim Check (when sync-back is for an issue-linked change)”

Before opening any sync-back PR for a change that is linked to a GitHub issue (owner/repo#N), run:

Terminal window
bun .claude/scripts/t1k-issue-claim.cjs check <owner/repo#N>
  • If state == "held" by another user: do NOT open a duplicate sync-back PR. Surface the holder and prNumber, report them to the caller, and stop.
  • If state == "free" or "stale" or "skip": proceed to open the PR.

When the sync-back PR IS opened: the PR itself becomes the claim. Use the acquire subcommand to self-assign the issue and get the body marker:

Terminal window
bun .claude/scripts/t1k-issue-claim.cjs acquire <owner/repo#N> --pr <new-PR-number>

Include in the PR body:

  • Fixes #N (the bodyTrailer returned by acquire)
  • The markerLine returned by acquire (e.g., t1k-claim: owner/repo#N)
  • Apply the label returned as labelToApply (e.g., t1k:claim)

The sync-back PR with these three elements IS the durable claim — no separate claim step needed. Do NOT run gh issue edit or gh pr create for claiming; the script and PR body carry the claim.

Write Fixes #N exactly as returned, nowhere else in the body wrapped or negated. GitHub’s closing-keyword parser matches the literal text regardless of Markdown formatting — backticks around a different mention of the same keyword elsewhere in the body (a disclaimer, a “not X” aside) still triggers the close. See skills/t1k-git/SKILL.md § “PR body MUST carry the closing keyword” for the full rule and incident.

This step is additive: the Kit-Freshness Guard (Step 0 above) MUST still run first.

  • Scan BOTH user-scope and project-scope. Walk $HOME/.claude/ AND <cwd>/.claude/ when collecting candidate files. Project-scope modules/skills (e.g., a wiki repo shipping its own module) are invisible if you only scan user-scope. See references/routing-and-paths.md Step 0 for the rules. Related: #168.
  • Pre-flight: requires t1k CLI v4.17.0+. The require-current-cli.cjs PreToolUse hook will block stale-CLI invocations of t1k sync-back (and other state-mutating commands) when the cached latest version is newer than the local binary. detail (references/operational-notes.md)
  • Run pre-flight checks BEFORE any file write — verify GitHub MCP is connected.
  • Staleness check is MANDATORY. Never push a stale branch silently.
  • Worktree, never checkout, in the kit clone. Steps 3 and 5 above both send you into a kit clone (to rebase a stale base, and to run check-skill-cross-refs.cjs against main). detail (references/operational-notes.md)
  • Module-registry-sync: if the edit touches module.json, the sub-agent must also regenerate t1k-modules.json in the kit repo (gate #validate-modules-registry-sync).
  • Skill-rename + activation-fragment sync — when a sync-back diff includes a skill directory rename (e.g., t1k-rn-rn-base-old → t1k-rn-rn-base-new), the sub-agent must ALSO update every t1k-activation-*.json fragment whose sessionBaseline[] or … detail (references/operational-notes.md)
  • Rules ctx-budget headroom — if the diff CREATES or MODIFIES any .claude/rules/*.md in the receiver kit, the sub-agent MUST run bun .claude/scripts/sync-back-ctx-budget.cjs --rules-dir <receiver-rules-dir> --change <relpath>=<contentfile> ... BEFORE … detail (references/operational-notes.md)
  • Marker-namespace sync — if the changeset adds any [t1k:<name> emission in a .cjs/.js/.ts file, the sub-agent MUST run bun $HOME/.claude/scripts/sync-marker-namespaces.cjs --root <kit-root> in the local kit clone before pushing the branch. detail (references/operational-notes.md)
  • PR is created and auto-merge is armed; the sub-agent then WATCHES it to MERGED in the same run (references/babysit-until-merged.md) — running t1k-pr-watch.cjs --cleanup-worktree (never t1k-ci-watcher for a PR wait), fixing a red check its own diff caused, reporting and stopping otherwise. “Auto-merge … detail (references/operational-notes.md)
  • Security: never sync .env, settings.local.json, memory files, or files with secrets. Sanitize absolute paths before writing.
  • Skill-touching syncs MUST consult t1k-skill-creator. If any path in the diff matches $HOME/.claude/skills/*/SKILL.md or $HOME/.claude/skills/*/references/*.md, the sub-agent invokes t1k-skill-creator to validate Skillmark structure (frontmatter … detail (references/operational-notes.md)
  • Naming-prefix gate on creates AND renames. If the diff CREATES or RENAMES a skill directory or agent file, the sub-agent MUST verify the new name conforms to the universal t1k- prefix rule (skills/t1k-skill-creator/references/architecture-rules.md § … detail (references/operational-notes.md)
  • CI-prefix lookup BEFORE computing target path (consumer→kit name asymmetry). Skill names in the consumer-side install are CI-prefixed at release time by auto-prefix-skills.cjs — e.g., a kit-source path of … detail (references/operational-notes.md)

Do NOT score the PR at create time. type=sync-back-pr earns merged-tier credit, so the worker requires the PR to be MERGED and returns 403 {"error":"author_attribution_failed","reason":"pr_not_merged"} for a just-opened one. A sync-back PR is open by definition at the moment gh pr create returns, so an immediate POST can only ever be rejected.

Credit is recorded on merge by contribution-flush.cjs reconcile (nothing to do here). Detail: references/contribution-scoring.md; rubric/POST contract SSOT: $HOME/.claude/skills/t1k-contribution-score/SKILL.md — do NOT inline it here. See $HOME/.claude/skills/t1k-contribution-score/SKILL.md for the full invocation contract (rubric, endpoint resolution, POST contract). Do NOT inline rubric or POST logic here — the SSOT lives in that skill.