Git Workflow

Git Workflow Skill

This skill teaches you the correct git workflow conventions for the business-automation repository.

Branch Naming Convention

Pattern: NNN-feature-name

• NNN: 3-digit zero-padded number (001, 002, etc.)
• feature-name: lowercase, hyphen-separated description

Examples:

• 001-tui-error-handling
• 002-reliable-email-detection
• 006-opencode-skills

To find the next number:

git branch -a | grep -oE '^[0-9]{3}' | sort -n | tail -1
# Then increment by 1

Commit Message Format

Pattern: [subfolder] description

• [subfolder]: The folder where most changes occurred
• description: Brief, lowercase description of changes

Examples:

• [recruitment-automation] fix email detection logic
• [.opencode] add shakudo-microservice skill
• [specs] create 006-opencode-skills specification

Rules:

• Start with lowercase (except for the bracketed prefix)
• Use present tense ("add", "fix", "update", not "added", "fixed")
• Keep under 72 characters
• Be specific about what changed

Standard Workflow

Creating a New Branch

# 1. Ensure you're on main and up-to-date
git checkout main
git pull origin main

# 2. Create and switch to new branch
git checkout -b NNN-feature-name

# 3. Make your changes
# ...

# 4. Stage changes
git add .

# 5. Commit with proper format
git commit -m "[subfolder] description"

# 6. Push to origin
git push -u origin NNN-feature-name

Updating an Existing Branch

# 1. Ensure you have latest main
git checkout main
git pull origin main

# 2. Switch back to your branch
git checkout NNN-feature-name

# 3. Rebase onto main (preferred) or merge
git rebase main
# OR
git merge main

# 4. Push updates (use --force-with-lease after rebase)
git push --force-with-lease origin NNN-feature-name

Before Creating a PR

1. Pull latest main to avoid conflicts:

   git checkout main && git pull origin main
   git checkout NNN-feature-name && git rebase main
   

2. Run tests if applicable:

   npm test && npm run lint
   

3. Push final changes:

   git push origin NNN-feature-name
   

Commit Best Practices

DO:

• Make atomic commits (one logical change per commit)
• Write descriptive commit messages
• Include the subfolder prefix
• Commit frequently during development

DON'T:

• Commit sensitive data (.env files, credentials)
• Use git commit --amend after pushing (unless you know what you're doing)
• Force push to shared branches without coordination
• Commit generated files (node_modules, dist, pycache)

Common Git Operations

Check Status

git status

View Changes

# Unstaged changes
git diff

# Staged changes
git diff --staged

# Compare with main
git diff main...HEAD

Stage Specific Files

git add path/to/file.ts
git add folder/

Unstage Files

git reset HEAD path/to/file.ts

Discard Local Changes

# Single file
git checkout -- path/to/file.ts

# All changes (CAREFUL!)
git checkout -- .

View Commit History

# Recent commits
git log --oneline -10

# With graph
git log --oneline --graph --all

Stash Changes

# Save current changes
git stash

# Restore changes
git stash pop

# List stashes
git stash list

Working with Specs (Speckit Integration)

When working on features with Speckit:

1. Spec location: specs/NNN-feature-name/
2. Branch should match spec: Branch 006-opencode-skills -> Spec specs/006-opencode-skills/
3. Commit specs separately:

   git add specs/006-opencode-skills/
   git commit -m "[specs] create 006-opencode-skills specification"
   

Gitignore Patterns

Ensure these are ignored (check .gitignore):

# Dependencies
node_modules/
.venv/

# Build outputs
dist/
build/
*.pyc
__pycache__/

# Environment
.env
.env.local
*.local

# IDE
.vscode/
.idea/

# OS
.DS_Store
Thumbs.db

Troubleshooting

Merge Conflicts

1. Open conflicted files
2. Look for conflict markers: <<<<<<<, =======, >>>>>>>
3. Edit to resolve, keeping desired code
4. Stage resolved files: git add <file>
5. Continue: git rebase --continue or git merge --continue

Undo Last Commit (Not Pushed)

# Keep changes staged
git reset --soft HEAD~1

# Keep changes unstaged
git reset HEAD~1

# Discard changes completely (CAREFUL!)
git reset --hard HEAD~1

Fix Commit Message

# Only if not pushed!
git commit --amend -m "[subfolder] corrected message"

Recover Deleted Branch

# Find the commit hash
git reflog

# Recreate branch
git checkout -b branch-name <commit-hash>