t1k:sync-back
| Field | Value |
|---|---|
| Module | t1k-kit-feedback |
| Version | 2.14.39 |
| Effort | high |
| Tools | AskUserQuestion, Bash, Edit, Glob, Grep, Read, Skill, Task, Write |
Keywords: contribute, gotcha, pr, propagate, push, sync, upstream
How to invoke
Section titled “How to invoke”/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 nextt1k 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:
- Always run the full scan. Walk
$HOME/.claude/AND<cwd>/.claude/perreferences/routing-and-paths.mdStep 0. Do NOT short-circuit on an empty lesson queue — the queue is one input among many, never the only one. - Sync every candidate found. Group by origin kit/repo per
references/routing-and-paths.mdStep 3 and open one PR per repo, multi-skill if needed. - 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 committreats no args — process everything. - If the full scan finds zero candidates, exit cleanly with:
This is success, not a prompt for input.No pending changes to sync. Scanned: $HOME/.claude/ and <cwd>/.claude/. Lesson queue: empty. Working tree: clean vs origin.
- Anti-pattern: the sub-agent fork seeing
/t1k:sync-backwith 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.
Argument parsing (when an arg IS given)
Section titled “Argument parsing (when an arg IS given)”The first non-flag token is the target. Resolution order:
- Skill name — if
$HOME/.claude/skills/<token>/OR<cwd>/.claude/skills/<token>/exists, sync everything under that directory only. - File path — if the token resolves to a file under a scan root (with or without the
$HOME/.claude/prefix), sync just that file. - 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):
| Intent | Load |
|---|---|
| Check if CWD is a consumer project (first step, always) | references/consumer-guard.md |
| Sub-agent invocation template + auto-lesson writeback contract | references/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 main | references/crossref-health-precheck.md |
Created-artifact completeness — the diff CREATES a skill dir, an agent file, a tests/ dir, or a script | references/created-artifact-completeness.md |
| Pre-triage block — gate pre-checks always; review fields only if asked | references/pre-triage-review.md |
| Three-round self-review — only if the user asked for a review | references/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/*.md | references/ctx-budget-headroom.md |
| Resolve file origin + compute target path in kit repo | references/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 queue | references/queue-writeback.md |
| Error table, cross-platform notes, what gets synced / excluded | references/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 shape | Tier |
|---|---|
One kit, ≤3 files, no .claude/rules/*.md, no skill/agent create or rename, no module.json | fast |
Anything else — multi-kit, >3 files, touches rules/*.md, creates/renames a skill or agent, touches module.json | full |
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:
-
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 updateextracts 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. Seerules/prefer-local-over-global-edits.md§ “Gotcha”. -
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). Recordkit-freshness: skipped (local ahead)in the PR body and jump to step 4. -
Otherwise refresh local kits — NON-INTERACTIVELY. Run
t1k modules update --yesto pull every installed kit to its latest published tag — on the nothing-pending path this itself printsAll modules are up to date.(that string ist1k modules update’s own confirmation, nott1k --version’s). Then runt1k --versionas a SECOND confirmation: it prints one badge PER installed kit (<kit>@<tag> ... ✓ up to dateor⚠ 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 daterather than looking for a matching string. The--yes(-y) flag is required, not optional: without it the command ends at anApply 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. -
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 withgit -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-remotecannot 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 viagh 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-currentbefore every sync-back commit) and the real instance:skills/t1k-rsi/ledger/gotchas/t1k-sync-back.md. -
Cross-ref health check against
main(MANDATORY). Before pushing the branch, runcheck-skill-cross-refs.cjsagainst the target kit’s currentmaintree (in the kit clone you opened for the PR). Ifmainalready 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-brokenmain. Full procedure + decision table + PR-body record:references/crossref-health-precheck.md. -
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:
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 theholderandprNumber, 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:
bun .claude/scripts/t1k-issue-claim.cjs acquire <owner/repo#N> --pr <new-PR-number>Include in the PR body:
Fixes #N(thebodyTrailerreturned byacquire)- The
markerLinereturned byacquire(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.
Operational notes
Section titled “Operational notes”- 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. Seereferences/routing-and-paths.mdStep 0 for the rules. Related: #168. - Pre-flight: requires t1k CLI v4.17.0+. The
require-current-cli.cjsPreToolUse hook will block stale-CLI invocations oft1k sync-back(and other state-mutating commands) when the cachedlatestversion 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 runcheck-skill-cross-refs.cjsagainstmain). detail (references/operational-notes.md) - Module-registry-sync: if the edit touches
module.json, the sub-agent must also regeneratet1k-modules.jsonin 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 everyt1k-activation-*.jsonfragment whosesessionBaseline[]or … detail (references/operational-notes.md) - Rules ctx-budget headroom — if the diff CREATES or MODIFIES any
.claude/rules/*.mdin the receiver kit, the sub-agent MUST runbun .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/.tsfile, the sub-agent MUST runbun $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
MERGEDin the same run (references/babysit-until-merged.md) — runningt1k-pr-watch.cjs --cleanup-worktree(nevert1k-ci-watcherfor 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.mdor$HOME/.claude/skills/*/references/*.md, the sub-agent invokest1k-skill-creatorto 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)
Contribution Scoring
Section titled “Contribution Scoring”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.