t1k:git
| Field | Value |
|---|---|
| Module | t1k-base |
| Version | 5.15.36 |
| Effort | low |
| Tools | — |
Keywords: binary-assets, branch, cleanup, closes, commit, fixes, git, issue-link, large-files, lfs, merge, prune, pull-request, push, reclaim, stage, stale-branch, worktree, worktrees
How to invoke
Section titled “How to invoke”/t1k:gitcm|cp|pr|merge|cleanup [args]TheOneKit Git — Git Operations
Section titled “TheOneKit Git — Git Operations”Unified git command. Routes to registered t1k-git-manager agent via routing protocol.
Default (No Arguments)
Section titled “Default (No Arguments)”Use AskUserQuestion to present available operations:
| Operation | Description |
|---|---|
cm | Stage files and create commits |
cp | Stage files, create commits, and push |
pr | Create Pull Request |
merge | Merge branches |
cleanup | Reclaim finished worktrees + branches from a parallel round |
access | Grant a repo collaborator access level |
Arguments
Section titled “Arguments”cm: Stage files, create commitscp: Stage files, create commits, and pushpr [to-branch] [from-branch]: Create Pull Requestmerge [to-branch] [from-branch]: Merge branches — expand a blocked merge’sdir/blocker to files; nevercheckout --/restore/cleana directory (references/branch-upstream-gone.md§ 5)cleanup: Fleet-sweep finished worktrees and branches — see belowaccess [owner/repo] [handle] [level]: Grant a repo collaborator access level — see below
MUST Pre-flight — Never Open a PR From a Worktree’s Home Branch
Section titled “MUST Pre-flight — Never Open a PR From a Worktree’s Home Branch”git rev-parse --git-common-dir ≠ .git ⇒ linked worktree, and git branch --show-current is its
HOME branch: branch a topic off it (git switch -c <type>/<topic>) and PR from that. --delete-branch
removes only a topic branch, never a home one. Pinned lane session: never git switch -c; delegate the PR to a sub-agent with its own worktree and topic branch (references/worktree-home-branch.md).
gh rate limit (one bucket per account): references/github-api-limits.md.
Any close/reopen/draft-ready/disable-auto/base-retarget/label/lock/transfer/branch-delete needs a comment first: skills/t1k-triage/references/status-change-requires-comment.md.
MUST Pre-flight — Claim the Issue Before Opening a PR
Section titled “MUST Pre-flight — Claim the Issue Before Opening a PR”Before pr for a branch that targets a GitHub issue, acquire the claim via the SSOT script — never
inline gh for claiming yourself. Full rule (hard-block on a live foreign claim, override, release):
references/issue-claim-discipline.md.
Where a Run ENDS (applies to pr / cp / merge alike)
Section titled “Where a Run ENDS (applies to pr / cp / merge alike)”The run ends at PR opened + auto-merge armed — gh pr merge <n> --auto --squash --delete-branch. --squash is the default only: a brief that asks for a multi-commit split or independently revertable commits gets --rebase instead (when allow_rebase_merge), and a squash-only repo is reported as having collapsed the split (core#2490).
Check allow_auto_merge and required checks before arming, and arm --delete-branch on a topic branch only: references/auto-merge-precheck.md.
Then take ONE bun "$S" pr <o/r> <n> snapshot (never --watch; references/gh-status-lookup.md), report the PR URL + auto-merge state +
the snapshot, and finish. The spawner finishes the PR: one background
t1k-pr-watch.cjs --repo <o/r> --pr <n> --json --timeout-min 60 run (a PR from a caller-created lane worktree is the same run with --cleanup-worktree <path>; never a t1k-ci-watcher, the pr-watcher-agent-guard hook denies it for a PR wait — skills/t1k-team/references/cook-template.md § “Finish the PR”). It reads and never merges, so the split moves no merge authority (see
rules/kit-pr-workflow-boundary.md § Carve-out). Never gh run watch, never a watch flag, never a
sleep/poll loop. A brief that explicitly asks for a CI wait gets the answer that waiting belongs
to the spawner’s script run, and the run stops there. Contract: agents/t1k-git-manager.md § “Close-Out Contract”.
On MERGED the spawner that created the worktree reaps it (clean tree, no live cwd, worktree.cjs remove); pinned lanes are never reaped: references/owner-reap-on-merge.md.
cleanup — Reclaim Finished Worktrees and Branches
Section titled “cleanup — Reclaim Finished Worktrees and Branches”Run at the end of a round that fanned out worktree lanes, and after any merge burst. Reads only; the sweep never deletes without an explicit apply decision.
bun .claude/scripts/worktree-cleanup-facts.cjs --json --finished-agent <id>An item is reclaimable only when ALL hold: merged into the primary branch · no REAL uncommitted
work · no process cwd inside · idle past the threshold · lock absent, held by a dead pid, or a
current-session lock on an agent the orchestrator named finished. Everything else is LIVE or
UNSAFE and is left alone with its reason. Unmerged branches are never deleted (sole exception: the closed-pr class below).
A locked worktree is not a busy one (the lock pid is a fact, never liveness): references/worktree-cleanup.md § “Locked worktrees are not busy”.
Apply (the per-item conditions above are always the gate; gitCleanup.autoApply colors whether
the [t1k:git-cleanup-dispatch] SessionStart frame suggests applying without asking — advisory
only, the session still decides):
git worktree remove --force <path> → git branch -D <branch> → git worktree prune.
Loose branches ([gone] upstream) and the closed-pr class, deleted only via bun .claude/scripts/worktree-reap-branch.cjs <branch>: references/worktree-cleanup.md.
A git cherry-pick -x lane (no PR, no upstream) is still reclaimable — landing is proven by patch-id, never ancestry (git cherry <base> <branch>, all -; never hardcode origin): references/owner-reap-on-merge.md § “No PR and no upstream”.
Full conditions, the merge-detection methods, the liveness trap, and the gotchas: references/worktree-cleanup.md.
access — Grant Repo Collaborator Permissions
Section titled “access — Grant Repo Collaborator Permissions”Grant a GitHub user access to a repo. Default cap is pull (Read); every level above it needs a
named, explicit confirmation — never infer a higher level from phrasing like “add them to the
repo”.
Procedure (handle resolution, org-membership check, silent-PUT read-back, incident): references/access-grant.md.
Core Workflow
Section titled “Core Workflow”Step 1: Stage + Analyze
Section titled “Step 1: Stage + Analyze”Stage by explicit path only — never git add -A/. (parallel-teammate-git-index-race.md; foreign-commit blocks it).
git add <explicit paths> && git diff --cached --stat -- <paths> && git diff --cached --name-only -- <paths>Step 2: Security Check
Section titled “Step 2: Security Check”git diff --cached | grep -iE "(api[_-]?key|token|password|secret|credential)"If secrets found: STOP, warn user, suggest .gitignore.
Step 2.5: Local Quality Gate — Lint + Typecheck
Section titled “Step 2.5: Local Quality Gate — Lint + Typecheck”Before commit, run the kit’s quality scripts if present. This catches CI-side failures (biome, eslint, ruff, tsc) that would otherwise bounce the PR.
Run typecheck/check, then lint: short-circuit on the first failure (STOP, fix, re-run). Discovery command, table, skip rules and rationale: references/quality-gate-scripts.md.
Step 2.7: Large-File / LFS Check
Section titled “Step 2.7: Large-File / LFS Check”Staged binaries must go through Git LFS before they are committed — LFS cannot be retrofitted onto an already-committed blob without a history rewrite.
Detection commands (staged files over 5MB, git check-attr filter): references/lfs-rules.md § “Detection commands”.
| Finding | Action |
|---|---|
| Staged file ≥ 100MB | STOP — GitHub hard-rejects the push. Track via LFS (or unstage) before committing. |
| Staged binary ≥ 5MB (art, audio, video, models, archives, ML weights) in a repo without LFS | Suggest enabling: git lfs install && git lfs track "*.<ext>", stage .gitattributes, THEN stage the binary. |
Repo has .gitattributes LFS patterns but git check-attr filter says unspecified for a staged binary | STOP — the pattern misses this path; fix the pattern first. A pattern miss commits the raw blob silently and is only noticed when the repo balloons. |
Full rules + gotchas: Large Binaries — Git LFS below.
Step 2.8: Sidecar Pairing (Unity .meta)
Section titled “Step 2.8: Sidecar Pairing (Unity .meta)”An asset and its .meta under Assets/ (or an embedded Packages/<pkg>/) are one unit — auto-stage the changed pair, and an orphan blocks the commit (STOP; never hand-write a .meta). Report sidecar: <N> .meta paired, <M> orphans. Full details: references/sidecar-pairing.md
Step 3: Split Decision
Section titled “Step 3: Split Decision”Split commits if: different types mixed, multiple scopes, FILES > 10 unrelated. Single commit if: same type/scope, FILES <= 3, LINES <= 50.
Step 4: Commit
Section titled “Step 4: Commit”git commit -m "type(scope): description"An explicit Co-Authored-By: trailer line from the caller wins over the default attribution; copy it verbatim, never your own model name.
Step 5: Plane Work-Item Update (after push)
Section titled “Step 5: Plane Work-Item Update (after push)”Full contract — do not restate or reimplement it here:
skills/t1k-plane/references/workflow-enforcement.md (../t1k-plane/references/workflow-enforcement.md)
§ Stage 4. Governing rule: modules/t1k-plane/rules/plane-workitem-workflow.md.
Comment the commit SHA(s) and branch on every work item bound to this session, then
apply doneTrigger: pr-merge-else-push:
Situation-to-Plane-action table (Done fires only at merge): references/plane-done-transitions.md.
Double-transition guard and the T1K_PLANE_MODE / --no-plane escapes: references/plane-done-transitions.md.
Output Format
Section titled “Output Format”staged: N files (+X/-Y lines)security: passedcommit: HASH type(scope): descriptionpushed: yes/noplane: PROJ-N → Done | commented | skipped (reason)Linking Commits / PRs / Branches to Issues
Section titled “Linking Commits / PRs / Branches to Issues”Associate work with the issue it resolves: Closes/Fixes/Resolves #N in the PR body auto-close on a default-branch merge, Refs #N does not. A branch name does not auto-link. A PR dependency goes in the body as Depends on #N, and an unmet dependency is never auto-merged. Keyword table and dependency detail: references/issue-linking.md.
PR body MUST carry the closing keyword
Section titled “PR body MUST carry the closing keyword”Every PR that resolves an issue MUST name it in the body with a closing keyword
(closes #N / fixes #N / resolves #N) so GitHub auto-closes it on merge. Three-way rule:
| PR resolves the issue… | Body MUST write |
|---|---|
| Fully | Closing keyword (either closes #N or fixes #N / resolves #N) |
| Partly | refs #N (no closing keyword) + what remains, explicitly |
| Not at all | No reference to any issue |
A partial fix MUST say what remains and NOT use a closing keyword; rationale and incidents: references/incident-trail.md.
The keyword that fires is the literal text, not the one you meant. GitHub parses the body’s
plain text — backticks, code fences, and negation sentences all still contain the literal closing
form and fire anyway (core#940). Don’t write the bare Keyword #N form when you mean to avoid
triggering it; describe it in prose instead and verify with grep. Details + the safe regex:
references/incident-trail.md § “Backticks don’t suppress the
closing-keyword parser” and § “Prefixed/hyphenated forms trigger too”.
PR body MUST carry ## Rollout Impact on a kit PR
Section titled “PR body MUST carry ## Rollout Impact on a kit PR”A PR touching a file matching TRIGGER_GLOBS in theonekit-release-action’s
validate-rollout-impact-section.cjs (read it — that array is the SSOT; CLAUDE.md Req #9) MUST
carry a ## Rollout Impact section, or the required gates / quality-gates check fails. It
covers transparent-vs-action-required, version skew both ways, migration/opt-out, rollback —
whether or not the PR also closes an issue. All required body sections and their conditions (this one, ## Cost & latency impact):
references/pr-body-required-sections.md (SSOT). Worked example + the edit-body-then-rerun recovery:
references/rollout-impact.md.
⚠ Wiki commits do NOT link to issues
Section titled “⚠ Wiki commits do NOT link to issues”A repo’s wiki is a separate git repo (<repo>.wiki.git) that lives OUTSIDE the issue/PR cross-reference graph. Fixes #N / Refs #N in a wiki commit message is inert — GitHub emits no timeline event and never auto-closes. To associate a wiki change with an issue:
Procedure and incident: references/issue-linking.md § “Wiki commits”.
Force-Push Safeguard
Section titled “Force-Push Safeguard”Enforcement is git’s own pre-push hook (installed at SessionStart); a fast-forward or your own rebase is allowed, discarding someone else’s commit or touching the default branch or a tag is blocked. Scenarios and overrides: references/force-push-safeguard.md.
Branch With No Upstream — : gone] or no bracket
Section titled “Branch With No Upstream — : gone] or no bracket”git branch -vv showing [origin/<b>: gone], or no bracket at all, is a state to CLASSIFY, not a
licence to delete — classify by CONTENT, never ancestry (--is-ancestor lies on squash merges).
Full detection table, classify procedure, and the linked-worktree git switch main gotcha:
references/branch-upstream-gone.md; post-merge return-to-main
procedure: references/branch-discipline.md (rule summary:
modules/t1k-base/rules/branch-discipline.md).
Rebase Over Merge
Section titled “Rebase Over Merge”Prefer rebase over merge when syncing a feature branch with its base. Default to git rebase <base> rather than git merge <base> — it keeps history linear and avoids merge commits that carry no information. Rebase rewrites commits, so the post-rebase push is forced; the 7-step procedure: references/rebase-over-merge.md.
Large Binaries — Git LFS
Section titled “Large Binaries — Git LFS”Game-studio repos (Unity, Cocos, art, audio) hit GitHub’s limits constantly: >100MB per file is hard-rejected, >50MB warns, and every large blob committed raw bloats the clone for everyone forever. LFS is the answer — but only when wired BEFORE the commit.
Enable, track and attribute rules: references/lfs-rules.md § “Enable and track”.
Commit TYPE in Skill/Doc Kits — Shipped .claude/ Content Is fix/feat, NOT docs
Section titled “Commit TYPE in Skill/Doc Kits — Shipped .claude/ Content Is fix/feat, NOT docs”NEVER docs(...) for files under .claude/ (skill bodies/references, agents, rules, registry fragments, or top-level docs/*.md, which also ships): docs/chore/style/test/ci are no-bump, so the edit never releases. Use fix (edits/gotchas), feat (new capability), feat! (breaking). Only README.md, CONTRIBUTING.md, plans/**, nested docs/** and code comments are docs. Table, ship test and incident: references/commit-type-in-kits.md.
Commit Scopes in Modular Kits — Must Map to Real Modules
Section titled “Commit Scopes in Modular Kits — Must Map to Real Modules”The commit scope MUST be an exact module name (or comma list), the kit repo name, a kit-wide / cross-cutting / payload-directory meta-scope (modules, all, meta, kit, agents, rules, hooks, skills, deps, …), or omitted. Anything else FAILS the release job. A skill name is NOT a module name (fix(t1k-doctor): is wrong unless a module of that name exists). Full allow-list, the bare-skill-name trap and examples: references/commit-scopes.md.
Commit Message — No CI-Skip Token
Section titled “Commit Message — No CI-Skip Token”Never write [skip ci]-style tokens in a PR head commit (BODY included, not just the subject), title or body, even quoted or in prose about another commit (BLOCKED PR / silently skipped release). Paraphrase instead: “skip-ci release commits”. Detail: references/ci-skip-token.md.
Contribution Scoring
Section titled “Contribution Scoring”After pr succeeds (not cm/cp — no artifact), invoke t1k:contribution-score with type=sync-back-pr + PR URL/title/body and target kit/repo. Fire-and-forget; SSOT gates non-T1K repos. See .claude/skills/t1k-contribution-score/SKILL.md.
Git operations, plus repo collaborator access grants (access, above). Never sync files
containing credentials, API keys, or secrets.