Skip to content

TAKEOFF69/codex-skills-kit / skills/git-under-contention

git-under-contention

Unverified

Operate Git safely when multiple humans or coding agents may share a repository, checkout, index, branches, or worktrees. Use before staging, committing, pushing, merging, rebasing, creating or removing worktrees, recovering apparently lost edits, handling staged files you did not touch, or preserving unfinished agent work under parallel-session contention.

Git Under Contention

Preserve every participant's work when repository state may change concurrently.

Core rule

Treat shared checkout as contested state. Stage exact paths, commit only owned changes, and leave unfamiliar hunks untouched.

Preflight

Run bundled detector before first commit in shared checkout:

python <skill-dir>/scripts/contention_preflight.py
python <skill-dir>/scripts/contention_preflight.py --mine path/owned-by-task

Signals include registered worktrees, recent HEAD movement, pre-staged files, and dirty paths outside owned pathspecs. CONTENTION is not automatic failure – it means use isolated worktree or stricter path ownership.

Skip detector only inside isolated worktree created for current task and still run normal status checks.

Shared-checkout rules

  • Inspect git status --porcelain, current branch, top-level path, and staged diff before mutation.
  • Stage with git add <path>...; avoid git add ., git add -A, and git commit -a.
  • Review git diff --cached --name-only and git diff --cached before commit.
  • Commit with explicit pathspec when repository conventions allow it.
  • Leave changes outside owned paths unchanged, staged or unstaged.
  • Avoid stash in contested checkout because stash captures shared state. Use task worktree or WIP commit on owned branch.
  • Fetch before deciding branch freshness; do not reset shared checkout to match remote.
  • Push durable work promptly so recovery does not depend on one disk.

Worktree lifecycle

Prefer worktree per task when work is multi-file, long-running, risky, or parallel.

  1. Fetch remote and create short-lived branch from intended base.
  2. Create worktree at explicit validated path.
  3. Record absolute root, branch, and base commit in handoff.
  4. Edit, stage exact paths, commit, and push as one durable sequence.
  5. Recheck dirty state and unpushed commits before cleanup.
  6. Remove worktree only through repository helper when one exists.

Before recursive worktree cleanup, inspect symlinks, junctions, mounts, and dependency links. Remove links safely before recursive deletion so cleanup cannot traverse into another checkout.

When state moves unexpectedly

  • File disappears: verify git rev-parse --show-toplevel, branch, and HEAD before recreating it.
  • HEAD changes during read-only audit: re-anchor findings to new HEAD.
  • Staged files appear: inspect and preserve; do not unstage unless ownership is known.
  • Push rejected as behind remote: fetch, inspect divergence, and integrate only owned branch.
  • Worktree vanishes: recover from pushed branch or commits; do not guess from stale local paths.
  • Generated file conflicts: regenerate once at repository-defined integration point instead of hand-merging machine output.

Safe handoff

Report:

Repo root: <absolute path>
Branch: <name>
Base: <sha>
Pushed tip: <sha or not pushed>
Owned paths: <list>
Dirty paths remaining: <list>
Other work preserved: <summary>
Next command: <single concrete action>

Checklist before push

  • Current root, branch, and HEAD confirmed.
  • Staged paths belong only to current task.
  • Cached diff reviewed.
  • Unfamiliar working-tree changes preserved.
  • Generated artifacts handled at canonical integration point.
  • Branch pushed and remote tip confirmed.
  • Cleanup skipped until worktree is clean and durable.

Stop conditions

  • Destructive reset, force-push, branch deletion, or worktree deletion could affect unowned state.
  • Required file contains fresh hunks from another active task and safe merge cannot be proven.
  • Target path for recursive cleanup contains unresolved links, junctions, mounts, or escapes intended workspace.

Ask owner for coordination rather than racing these conditions.

Bundled resource

scripts/contention_preflight.py provides deterministic CLEAR or CONTENTION verdict, JSON output, and hermetic --selftest.

Related skills

  • session-close makes work durable before session ends.
  • verify-honestly prevents false claims about pushed or merged state.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 319kUpdated Claude CodeCodexVerifiedInstall