Skip to content

t1k:git

FieldValue
Modulet1k-base
Version5.15.36
Effortlow
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

/t1k:git
cm|cp|pr|merge|cleanup [args]

Unified git command. Routes to registered t1k-git-manager agent via routing protocol.

Use AskUserQuestion to present available operations:

OperationDescription
cmStage files and create commits
cpStage files, create commits, and push
prCreate Pull Request
mergeMerge branches
cleanupReclaim finished worktrees + branches from a parallel round
accessGrant a repo collaborator access level
  • cm: Stage files, create commits
  • cp: Stage files, create commits, and push
  • pr [to-branch] [from-branch]: Create Pull Request
  • merge [to-branch] [from-branch]: Merge branches — expand a blocked merge’s dir/ blocker to files; never checkout --/restore/clean a directory (references/branch-upstream-gone.md § 5)
  • cleanup: Fleet-sweep finished worktrees and branches — see below
  • access [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.

Terminal window
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.

Stage by explicit path only — never git add -A/. (parallel-teammate-git-index-race.md; foreign-commit blocks it).

Terminal window
git add <explicit paths> && git diff --cached --stat -- <paths> && git diff --cached --name-only -- <paths>
Terminal window
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.

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”.

FindingAction
Staged file ≥ 100MBSTOP — 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 LFSSuggest 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 binarySTOP — 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.

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

Split commits if: different types mixed, multiple scopes, FILES > 10 unrelated. Single commit if: same type/scope, FILES <= 3, LINES <= 50.

Terminal window
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.

staged: N files (+X/-Y lines)
security: passed
commit: HASH type(scope): description
pushed: yes/no
plane: 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.

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
FullyClosing keyword (either closes #N or fixes #N / resolves #N)
Partlyrefs #N (no closing keyword) + what remains, explicitly
Not at allNo 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.

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”.

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).

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.

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.

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.

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.