Skip to content

dvy1987/agent-loom / .agents/skills/git-workflow-and-versioning

git-workflow-and-versioning

Verified

Structure git work with atomic commits, conventional messages, short-lived branches, and pre-commit hygiene. Load when committing, branching, resolving merge conflicts, organizing parallel work, or reviewing git history. Also triggers on "git workflow", "commit message", "conventional commits", "atomic commit", "branch strategy", "git worktree", "how should I commit this". Does not replace project-specific hook policies — complements them.

Git Workflow and Versioning

You keep git history reviewable, reversible, and honest. Commits are save points; messages document intent.

Hard Rules

One logical change per commit — never mix feature + refactor + formatting. Commit messages explain why, not only what the diff shows. Never commit secrets — scan staged diff for password, secret, api_key, token patterns. Never force-push to shared main/master without explicit user request. Tests should pass before commit when the project has a test command.


Workflow

Step 1 — Review what's changing

Run git status and git diff (staged if committing). Confirm scope matches one logical change.

Step 2 — Pre-commit hygiene

Run project tests/lint if applicable. Reject staged secrets. Split if mixed concerns.

Step 3 — Write the message

<type>: <short imperative description>

<optional body — why, tradeoffs, links to spec/task>

Types: feat | fix | refactor | test | docs | chore

Step 4 — Commit or advise the user

If the user's environment allows commits, commit. Otherwise output the exact message for them to run.

Step 5 — Summarize for reviewers

Emit a short change summary (see Output Format).

Step 6 — Finish the branch (when the task is complete)

Verify tests are green before offering to finish. Present exactly these options: 1) merge locally, 2) push and open a PR, 3) keep the branch as-is, 4) discard. Destructive cleanup (branch delete, worktree removal) requires the user to explicitly confirm the discard choice — never delete on an inferred or unconfirmed "yes."


Branching defaults

  • Trunk-based: keep default branch deployable; merge feature branches within 1–3 days.
  • Naming: feature/<slug>, fix/<slug>, chore/<slug>, refactor/<slug>
  • Parallel agents: prefer git worktree add over constant branch switching.
  • Incomplete features: feature flags on main beat month-long branches.

Gotchas

  • Squashing everything at the end destroys the slice narrative — commit incrementally.
  • Formatting-only commits mixed with behavior changes make review and bisect painful.
  • Missing .gitignore until .env lands in history.
  • git reset --hard on shared branches loses others' work — warn first.
  • Never delete a branch or worktree as part of "finishing up" without the user explicitly picking that option — an assumed cleanup can discard unmerged work.

Common Rationalizations

ExcuseReality
"I'll commit when the feature is done"One giant commit can't be reviewed or reverted safely.
"Message doesn't matter"History is documentation for future you and agents.
"I'll squash later"Prefer clean incremental commits from the start.
"Branches are overhead"Short-lived branches isolate work; long-lived branches are the cost.
"Tests pass, I'll just clean up the branch"Cleanup (merge/discard) is the user's call — present options, don't act unilaterally.

Output Format

## Git summary

Commits recommended:
- `<type>: <description>`

CHANGES:
- path: one-line what/why

NOT TOUCHED (intentional):
- path: reason out of scope

CONCERNS:
- [risk or question for human]

Examples

Exposes validate-skills checks for CI; refs task validate-api.

Run: `npm test` → pass, then commit.
    </output>
  </example>
</examples>

---

## Verification

- [ ] Commit message follows convention
- [ ] Scope is single logical change
- [ ] Handoff completed if user triggered via commit/push
- [ ] No secrets in committed files

## Red Flags

- All work squashed into one commit losing slice narrative
- Formatting-only changes mixed with behavior commits
- .env or secrets committed before gitignore exists
- Conventional commit type mismatches actual change nature

## Prune Log
Last pruned: 2026-07-09
- Added branch-finishing flow (merge/PR/keep/discard) with confirm-before-destroy gate (agent-loom Phase 4, obra/superpowers)


## Impact Report

Git workflow: [commit advised / committed / review-only] Commits: N | Concerns flagged: N

planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 117kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall