Git Workflow Skill

Structured development workflow using git, conventional commits, and work logging.

Core Principles

Principle Description

Issue-First All work starts with an issue (bd or GitHub)

Feature Branches One branch per issue/feature

Conventional Commits Structured commit messages

Semver Versioning Semantic version numbers

Work Logging Document all changes in .worklog/

UAT Workflow Human acceptance testing before merge

Workflow Overview

┌─────────────────────────────────────────────────────────────┐ │ 1. Create/claim issue (bd create or bd update --status) │ │ ↓ │ │ 2. Create feature branch (git checkout -b type/issue-id) │ │ ↓ │ │ 3. Make changes, commit with conventional format │ │ ↓ │ │ 4. Create worklog entry documenting changes │ │ ↓ │ │ 5. Request UAT (/uat request <feature>) │ │ ↓ │ │ 6. Human tests and approves (/uat approve) or denies │ │ ↓ │ │ 7. Merge to main, close issue, tag if release │ └─────────────────────────────────────────────────────────────┘

Branch Naming Convention

<type>/<issue-id>-<short-description>

Type Use Case Example

feature/

New functionality feature/proj-123-dark-mode

fix/

Bug fixes fix/proj-456-form-validation

chore/

Maintenance, deps chore/proj-789-update-deps

docs/

Documentation only docs/proj-101-api-reference

refactor/

Code restructuring refactor/proj-202-simplify-auth

Conventional Commits

Format: <type>(<scope>): <description>

Types

Type When to Use

feat

New feature for the user

fix

Bug fix for the user

docs

Documentation changes

style

Formatting, missing semicolons (no code change)

refactor

Refactoring production code

test

Adding tests (no production code change)

chore

Build tasks, package manager configs

Examples

Feature

git commit -m "feat(auth): add OAuth2 login support"

Bug fix

git commit -m "fix(forms): correct email validation regex"

Documentation

git commit -m "docs(readme): add installation instructions"

Breaking change (add ! after type)

git commit -m "feat(api)!: change response format to JSON:API"

Commit Body for Complex Changes

git commit -m "$(cat <<'EOF' feat(validation): add incremental file validation

• Add git-aware file detection
• Implement MD5-based result caching
• Support staged-only mode for pre-commit hooks

Closes: proj-59l EOF )"

Semantic Versioning (Semver)

Format: MAJOR.MINOR.PATCH

Version Part When to Bump Example

MAJOR Breaking changes 1.0.0 → 2.0.0

MINOR New features (backward compatible) 1.0.0 → 1.1.0

PATCH Bug fixes (backward compatible) 1.0.0 → 1.0.1

Tagging Releases

Create annotated tag

git tag -a v1.2.0 -m "Release v1.2.0: Add dark mode support"

Push tags

git push origin --tags

Work Logging

Every significant change creates a worklog entry in .worklog/ .

Worklog File Format

File: .worklog/YYYY-MM-DD-issue-id-description.md

Worklog: [Issue ID] - Short Description

Date: YYYY-MM-DD HH:MM Issue: {issue-id} Branch: feature/{issue-id}-description Status: in_progress | complete | blocked

Summary

Brief description of what was done.

Changes Made

• List of files modified
• Key decisions made
• Problems solved

Files Modified

• path/to/file1.js - Description of change
• path/to/file2.css - Description of change

Testing Done

• Unit tests pass
• Manual testing complete
• UAT requested

Notes

Any additional context for future reference.

Recovery Instructions

If this work needs to be recovered:

1. Checkout branch: git checkout feature/{issue-id}
2. Key commits: abc1234, def5678

Git Commands Reference

Starting Work

Sync with remote

git fetch origin git checkout main git pull origin main

Create feature branch

git checkout -b feature/{issue-id}-description

Claim the issue

bd update {issue-id} --status in_progress

During Work

Stage changes

git add <files>

Commit with conventional format

git commit -m "feat(scope): description"

Push to remote (first time)

git push -u origin feature/{issue-id}-description

Push subsequent changes

git push

Completing Work

Ensure all tests pass

npm test

Update worklog

Create/update .worklog/YYYY-MM-DD-xxx.md

Request UAT

/uat request <feature-name>

After UAT approval, merge to main

git checkout main git pull origin main git merge --no-ff feature/{issue-id}-description git push origin main

Close the issue

bd close {issue-id} --reason "Implemented and merged"

Delete feature branch

git branch -d feature/{issue-id}-description git push origin --delete feature/{issue-id}-description

UAT (User Acceptance Testing)

Requesting UAT

After completing work, request human testing:

/uat request <feature-name>

This creates a uat-<feature-name>.md file with testing instructions.

UAT Response

Human reviews and responds:

/uat approve <feature-name> # Feature accepted /uat deny <feature-name> # Feature needs work

Handling Denied UAT

If UAT is denied:

• Review feedback in the UAT file

• Make necessary changes

• Update worklog

• Request UAT again

Pre-Session Checklist

When starting an AI assistant session:

• Check git status: Any uncommitted changes?

• Review open issues: bd ready or bd list --status open

• Check current branch: On main or a feature branch?

• Review recent worklogs: .worklog/ for context

Red Flags

Situation Action

Working without an issue Create issue first with bd create

Commits directly to main Use feature branch

No worklog entry Create before requesting UAT

Large uncommitted changes Commit incrementally

Merge conflicts Resolve carefully, test after

Quick Reference

Start work on issue

bd update <id> --status in_progress git checkout -b feature/<id>-description

Commit change

git add . && git commit -m "feat(scope): description"

Complete work

git push -u origin HEAD

Create worklog entry

/uat request <feature>

After approval: merge, close issue, cleanup

Related Skills

• pre-flight-check - "INVOKE FIRST before any code work

• ci-cd - Configure GitHub Actions for automated testing, building,...