dvy1987/agent-loom / .agents/skills/git-workflow-and-versioning
git-workflow-and-versioning
VerifiedStructure 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 addover 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
.gitignoreuntil.envlands in history. git reset --hardon 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
| Excuse | Reality |
|---|---|
| "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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |
| 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: 117k | Updated | Claude CodeCodex | Verified | Install |
| 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: 108k | Updated | Claude CodeCodex | Verified | Install |
| 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: 108k | Updated | Claude CodeCodex | Verified | Install |