Git Workflow

Git Workflow

Git is the safety net for agentic development: branches isolate work, commits are save points, and history explains why changes happened.

For coding-related git work, load engineering-principles before this skill so atomic commits and hooks preserve the local engineering standards.

Default posture:

main/master/dev branch -> stays clean and stable
feature/fix work       -> happens in a branch or worktree when non-trivial
commits                -> small, verified, atomic, and descriptive

This skill gives defaults. User instructions, project conventions, host rules, and repository-specific workflows override them.

Operating Principles

Repository Setup Policy

Before serious edits, understand where you are.

Is this a git repo?
│
├─ yes
│  └─ continue with branch/worktree/commit policy
│
└─ no
   ├─ project directory?        -> initialize git, then set hooks/ignore if current scope fits
   └─ generic user location?    -> do NOT init; warn user that edits are not versioned

Project-shaped locations:

/home/user/projects/my-app/
/home/user/Desktop/my-tool/
/repo/customer-api/

Generic or personal locations:

~
~/Desktop
~/Downloads
~/.config/something
/tmp/random-edit

If editing a generic location, do not initialize git by surprise. Say that the files are outside a project repo and changes will not have normal versioned rollback unless the user chooses a repo location.

Branch And Worktree Decision Map

Need isolation?
│
├─ tiny fast edit / one obvious file
│  └─ work in place, inspect diff carefully
│
├─ medium/big edit, risky refactor, feature, or multi-agent work
│  └─ prefer branch/worktree isolation
│
├─ already in branch or worktree?
│  └─ do not create another one unless explicitly needed
│
└─ platform has native workspace/worktree support?
   └─ use native tool first; manual git worktree only as fallback

Worktrees are preferred for medium/big work when isolation matters. They can be skipped for small fast edits or when the prompt/context clearly asks to work in place.

Parallel agents do not always need distinct worktrees. Use separate worktrees only when agents need isolation from each other: overlapping files, risky experiments, or clean fresh state. If agents are read-only or working on non-overlapping checks, separate worktrees may be unnecessary overhead.

Detect Existing Isolation

Before creating a worktree, check whether the current workspace is already a linked worktree.

git rev-parse --show-toplevel
git rev-parse --git-dir
git rev-parse --git-common-dir
git branch --show-current

Interpretation:

git-dir == git-common-dir
  -> normal checkout

git-dir != git-common-dir
  -> likely linked worktree

Submodule guard:

git rev-parse --show-superproject-working-tree 2>/dev/null

If this returns a path, you are inside a submodule, not simply a worktree. Treat it according to the submodule/project context.

Never create a nested worktree just because a plan says "use worktree." Detect first.

Worktree Location Policy

Prefer existing project conventions over inventing a new layout.

1. User/project instructions
2. Existing project-local .worktrees/ or worktrees/
3. Mature project with no worktree config -> external hidden location
4. Small/new/greenfield project -> create project-local .worktrees/ carefully

Small Or Greenfield Projects

For small/new projects, a hidden project-local worktree directory is often best:

proj_root/
  src/
  .worktrees/
    feat1/
    feat2/
  .gitignore

If creating .worktrees/, also update ignore/configuration so tooling does not scan it.

Check likely files:

.gitignore
package.json
eslint.config.js / eslint.config.mjs / .eslintrc*
tsconfig.json
pyproject.toml
ruff.toml
.vscode/settings.json
tool-specific config files

After adding ignores, run the appropriate build/lint/typecheck health check and confirm the project is not worse than before.

Mature Projects

For mature projects with no worktree convention, avoid adding new project-local tooling noise. Use an external hidden location such as:

~/.config/myai/worktrees/<project>/<branch>/

This avoids breaking build, lint, search, test discovery, and editor tooling in large repositories.

Baseline Health Check

Running tests/lint/typecheck before work in new worktree can be useful, but it is a health check, not always a gate.

Baseline check passes
  -> good, proceed with a known-clean starting point

Baseline check fails
  -> record existing failure; decide whether it blocks this work

Baseline failures may already exist on main. Do not treat every baseline failure as caused by the current work. Record the command and failure summary so future verification can distinguish new regressions from existing problems.

Commit Policy

Default workflow: commit meaningful verified increments.

Exceptions and overrides:

• User, project, or platform instructions may override commit behavior.
• If current runtime says not to commit without explicit request, make the work commit-ready and report that instead of committing.
• Do not commit edits in generic locations such as ~, ~/Desktop, ~/Downloads, or random ~/.config/... directories; warn the user instead.

Work in real project repo
  -> commit meaningful verified increments

Work in generic location
  -> no commits; warn user edits are outside normal project history

Atomic Commits

Each commit should do one logical thing.

Good history:
  feat: add task creation endpoint
  test: cover task validation errors
  refactor: extract task validation helper

Bad history:
  update stuff
  fix
  add task feature and refactor auth and update prettier

Separate these concerns when practical:

Commit Messages

Default format, unless user/project conventions say otherwise:

<type>: <short imperative summary>

<optional body explaining why>

Common types:

feat      new behavior
fix       bug fix
refactor  behavior-preserving code change
test      tests only or test infrastructure
docs      documentation only
chore     tooling, dependencies, maintenance

Before choosing a message style, check recent commits and match the repository.

git log --oneline -10

Good message:

fix: validate emails before persisting users

Prevents invalid email formats from reaching the database and keeps API error
semantics consistent with existing auth validation.

Weak message:

update user stuff

Pre-Commit Hygiene

Before committing, inspect what will be committed.

1. Check status and diff
2. Confirm no unrelated files are staged
3. Confirm no secrets or local env files are included
4. Run right-sized verification
5. Commit with repository-style message

Reference skills:

Generated Files, Ignores, And Hooks

Generated-file and hook setup should happen when it naturally fits your current task scope.

Good times to update gitignore/hooks/config:

• bootstrapping a project
• editing project configuration
• adding generated outputs or build tooling
• setting up CI/lint/typecheck/test workflows
• creating project-local .worktrees/

Bad time:

• fixing a backend bug in a mature monorepo where ignore/hook changes are unrelated to the task

Commit generated files only if the project expects them, such as lockfiles, migrations, generated clients, or checked-in schemas. Do not commit build output, local env files, secret material, or editor-local noise unless the project has an explicit convention.

Create git hooks when the project language/environment supports them and the task scope includes project setup or quality gates. Keep hooks fast and aligned with the project's toolchain.

Change Summaries

After meaningful work, provide a summary that helps review and catches scope drift.

CHANGES MADE
  - src/routes/tasks.ts: added validation to POST /tasks
  - src/lib/task-schema.ts: introduced TaskCreateSchema

VERIFICATION
  - npm run lint: passed
  - npm run typecheck: passed
  - npm test -- tasks: passed

INTENTIONALLY NOT TOUCHED
  - auth routes have similar validation gaps, but are out of scope

CONCERNS / FOLLOW-UPS
  - schema rejects extra fields; confirm this matches API policy

Git For Debugging

Git is also a diagnostic tool.

# See recent changes
git log --oneline -20

# Inspect a range
git diff HEAD~5..HEAD -- src/

# Find when a bug appeared
git bisect start
git bisect bad HEAD
git bisect good <known-good-commit>

# Check line history
git blame path/to/file

Use this with systematic-debugging when the introducing change is not obvious.

Common Mistakes

Handoff

Use related skills depending on where the work goes next:

Need incremental execution discipline -> incremental-implementation
Need independent parallel work         -> when-and-how-to-run-parallel-agents
Need diff/PR readiness review          -> doing-code-review
Need verification before commit/PR     -> verification-before-completion
Need CI hooks or quality gates         -> ci-cd-and-automation

This skill sets up sane git discipline and isolation. Use platform git safety rules, doing-code-review, and verification-before-completion for final handoff readiness.