Git Workflow Helper

Git Workflow Skill

Expert guidance for git operations in the tempo-demo workflow. This skill is the ONLY way commands should perform git operations to ensure 100% commit consistency across all workflows.

Purpose

Provide consistent git operations across all workflow commands:

• Read conventions from .env for commit format, branch naming
• Execute atomic commits with proper formatting
• Create feature branches following naming conventions
• Create PRs with Linear integration
• Ensure working directory cleanliness

Core Responsibility

CRITICAL: This skill is the single source of truth for git operations. All commands must use this skill's functions rather than calling git directly. This guarantees:

• ✅ All commits follow project conventions
• ✅ All commits reference issue IDs
• ✅ All commits are atomic and well-scoped
• ✅ All branches follow naming patterns
• ✅ Consistency across all workflows

Project Conventions

Conventions are stored in .env at project root. Default values if not specified:

# Commit Format
COMMIT_FORMAT=conventional  # Options: conventional, simple

# Branch Naming
BRANCH_PREFIX_FEATURE=feature
BRANCH_PREFIX_BUG=fix
BRANCH_PREFIX_CHORE=chore
BRANCH_PREFIX_EPIC=feature

# GitHub
GITHUB_ORG=your-org
GITHUB_REPO=your-repo

# Linear
PROJECT_TEAM_KEY=TEMPO

Functions

1. ensure_clean_state()

Purpose: Verify working directory is clean before starting work

Usage:

Use git-workflow skill to ensure working directory is clean

Implementation:

# Check for uncommitted changes
if ! git diff --quiet || ! git diff --cached --quiet; then
  echo "❌ Working directory has uncommitted changes"
  git status --short
  exit 1
fi

# Check for untracked files that might matter
UNTRACKED=$(git ls-files --others --exclude-standard)
if [ -n "$UNTRACKED" ]; then
  echo "⚠️  Warning: Untracked files exist:"
  echo "$UNTRACKED"
  # Don't fail, just warn
fi

echo "✅ Working directory is clean"

Returns: Success/failure status

2. create_feature_branch(issue_id, issue_title)

Purpose: Create feature branch following project naming conventions

Parameters:

• issue_id: Issue ID (e.g., "TEMPO-123")
• issue_title: Issue title for branch name

Usage:

Use git-workflow skill to create feature branch for TEMPO-123

Implementation:

# Load conventions from .env
source .env 2>/dev/null || true
BRANCH_PREFIX=${BRANCH_PREFIX_FEATURE:-feature}

# Generate branch name from issue title
# Convert to kebab-case, max 40 chars
BRANCH_SUFFIX=$(echo "$ISSUE_TITLE" | \
  tr '[:upper:]' '[:lower:]' | \
  sed 's/[^a-z0-9]/-/g' | \
  sed 's/--*/-/g' | \
  sed 's/^-//' | \
  sed 's/-$//' | \
  cut -c1-40)

BRANCH_NAME="${BRANCH_PREFIX}/${ISSUE_ID}-${BRANCH_SUFFIX}"

# Create and checkout branch
git checkout -b "$BRANCH_NAME"

echo "✅ Created branch: $BRANCH_NAME"

Returns: Branch name

Example: feature/TEMPO-123-add-user-authentication

3. commit_changes(type, scope, message, issue_id)

Purpose: Create atomic commit with conventional format and issue reference

Parameters:

• type: Commit type (feat, fix, docs, test, refactor, style, chore)
• scope: Scope of change (e.g., "atoms/cache", "features/users", "commands")
• message: Description of change
• issue_id: Linear issue ID (e.g., "TEMPO-123")

Usage:

Use git-workflow skill to commit changes:
- Type: feat
- Scope: atoms/cache
- Message: add Redis cache adapter
- Issue: TEMPO-123

Implementation:

# Load conventions
source .env 2>/dev/null || true
COMMIT_FORMAT=${COMMIT_FORMAT:-conventional}
TEAM_KEY=${PROJECT_TEAM_KEY:-TEMPO}

# Format commit message based on convention
case "$COMMIT_FORMAT" in
  conventional)
    # Format: type(scope): message (ISSUE-ID)
    COMMIT_MSG="${TYPE}(${SCOPE}): ${MESSAGE} (${ISSUE_ID})"
    ;;
  simple)
    # Format: message (ISSUE-ID)
    COMMIT_MSG="${MESSAGE} (${ISSUE_ID})"
    ;;
  *)
    # Default to conventional
    COMMIT_MSG="${TYPE}(${SCOPE}): ${MESSAGE} (${ISSUE_ID})"
    ;;
esac

# Create commit
git add .
git commit -m "$COMMIT_MSG"

echo "✅ Committed: $COMMIT_MSG"

Returns: Commit hash and message

Commit Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• test: Adding tests
• refactor: Code restructuring
• style: Formatting, no code change
• chore: Maintenance, dependency updates

Scope Examples:

• Backend: atoms/cache, features/users, molecules/apis, organisms/api
• Frontend: atoms/button, organisms/header, pages/dashboard
• Commands: commands/plan, skills/git-workflow
• Specs: specs, backend/specs

Example Commits:

feat(atoms/security): add JWT utilities (TEMPO-123)
test(atoms/security): add JWT utility tests (TEMPO-123)
feat(features/users): add login/register methods (TEMPO-123)
docs(specs): add implementation spec for user auth (TEMPO-123)
style: auto-format code (TEMPO-123)

4. create_pr(issue_id, pr_title, pr_body)

Purpose: Create pull request with Linear integration

Parameters:

• issue_id: Linear issue ID
• pr_title: PR title
• pr_body: PR description (markdown)

Usage:

Use git-workflow skill to create PR for TEMPO-123 with title and body

Implementation:

# Load conventions
source .env 2>/dev/null || true

# Get current branch
CURRENT_BRANCH=$(git branch --show-current)

# Push branch to remote
git push -u origin "$CURRENT_BRANCH"

# Determine base branch (usually main or working-files)
BASE_BRANCH=${GITHUB_BASE_BRANCH:-main}

# Call /pr command (primitive that handles gh CLI)
# The /pr command will:
# - Fetch issue details from Linear
# - Read strategy comment if exists
# - Read spec file if exists
# - Generate PR description with full context
# - Create PR via gh CLI
# - Link Linear issue to PR

# For now, delegate to /pr command
echo "Delegating to /pr command for full PR creation..."
# This is a skill, so we instruct the agent to use the /pr command

Note: This function primarily delegates to the /pr command primitive which handles:

• Fetching Linear issue details
• Reading strategy + spec files
• Generating comprehensive PR description
• Creating PR via gh CLI
• Linking Linear issue

Returns: PR URL

Usage Patterns

Pattern 1: Clean Branch → Implementation → Commit Loop

## Workflow

1. Use git-workflow skill to ensure clean state
2. Use git-workflow skill to create feature branch for TEMPO-123
3. Implement feature (write code)
4. Use git-workflow skill to commit changes:
   - Type: feat
   - Scope: atoms/security
   - Message: add JWT utilities
   - Issue: TEMPO-123
5. Write tests
6. Use git-workflow skill to commit changes:
   - Type: test
   - Scope: atoms/security
   - Message: add JWT utility tests
   - Issue: TEMPO-123
7. Repeat steps 3-6 for each logical unit of work
8. Use git-workflow skill to create PR for TEMPO-123

Pattern 2: Spec → Implementation Workflow

## Implementation with Spec-First Pattern

1. Generate spec file (via /plan:generate-spec or manually)
2. Use git-workflow skill to commit changes:
   - Type: docs
   - Scope: specs
   - Message: add implementation spec for TEMPO-123
   - Issue: TEMPO-123
3. Implement following spec
4. For each logical step in spec:
   a. Write code
   b. Use git-workflow skill to commit (type: feat, fix, refactor, etc.)
   c. Write tests
   d. Use git-workflow skill to commit (type: test)
5. Use git-workflow skill to create PR

Result: PR shows spec commit first, then implementation commits. Clear traceability.

Pattern 3: Auto-Fix Quality Gates

## Quality Gate Auto-Fix Pattern

1. Run quality gates (format, lint)
2. If auto-fixes applied:
   - Use git-workflow skill to commit changes:
     - Type: style
     - Scope: (empty or specific area)
     - Message: auto-format code
     - Issue: TEMPO-123
3. Run tests
4. If test failures require fixes:
   - Make fixes
   - Use git-workflow skill to commit changes:
     - Type: fix
     - Scope: (specific area)
     - Message: fix failing test
     - Issue: TEMPO-123

Integration with Commands

Commands Using This Skill

1. /implement - Primary consumer

   • Creates feature branch
   • Commits at every logical step
   • Creates PR at end

2. /plan:generate-spec - Spec generation

   • Commits spec file
   • Updates Linear with spec location

3. /analyze-implementation - Strategy generation

   • Commits strategy document

4. /test - Quality gates

   • Commits auto-fixes from format/lint

5. /plan:decompose - Planning

   • Commits YAML plan file

Prohibited Direct Git Usage

Commands should NEVER call git directly. Instead:

❌ BAD (in command):

git add .
git commit -m "feat(atoms): add cache (TEMPO-123)"

✅ GOOD (in command):

Use git-workflow skill to commit changes:
- Type: feat
- Scope: atoms/cache
- Message: add cache adapter
- Issue: TEMPO-123

Benefits

100% Commit Consistency

All commits across all workflows follow the same format:

<type>(<scope>): <message> (ISSUE-ID)

Traceability

Every commit references a Linear issue, enabling:

• Full audit trail from issue → commits → PR
• Easy filtering by issue
• Clear accountability

Convention Enforcement

Conventions are read from .env, ensuring:

• Single source of truth
• Easy to update conventions project-wide
• Override support for different projects

Atomic Commits

Pattern encourages small, focused commits:

• One logical change per commit
• Tests committed separately
• Auto-fixes committed separately
• Clear git history

Examples

Example 1: Feature Implementation

## /implement TEMPO-123

1. Use git-workflow skill to ensure clean state
2. Use git-workflow skill to create feature branch for TEMPO-123: "Add user authentication"

# Implement JWT utilities
3. Write atoms/security/jwt.py
4. Use git-workflow skill to commit:
   - Type: feat
   - Scope: atoms/security
   - Message: add JWT utilities
   - Issue: TEMPO-123

# Write tests
5. Write tests/atoms/security/test_jwt.py
6. Use git-workflow skill to commit:
   - Type: test
   - Scope: atoms/security
   - Message: add JWT utility tests
   - Issue: TEMPO-123

# Implement service methods
7. Update features/users/service.py
8. Use git-workflow skill to commit:
   - Type: feat
   - Scope: features/users
   - Message: add login/register methods
   - Issue: TEMPO-123

# Create PR
9. Use git-workflow skill to create PR for TEMPO-123

Result: 3 atomic commits, clear PR with Linear integration

Example 2: Quality Gate Workflow

## /test

1. Run format (ruff format)
2. If changes made:
   Use git-workflow skill to commit:
   - Type: style
   - Scope: (empty)
   - Message: auto-format code
   - Issue: TEMPO-123

3. Run lint (ruff check --fix)
4. If changes made:
   Use git-workflow skill to commit:
   - Type: style
   - Scope: (empty)
   - Message: auto-fix lint issues
   - Issue: TEMPO-123

5. Run tests (pytest)
6. Report results

Error Handling

Uncommitted Changes

If skill reports uncommitted changes:
1. Review changes: git status
2. Decide:
   - Commit them via this skill
   - Stash them: git stash
   - Discard them: git restore .
3. Retry operation

Branch Already Exists

If branch exists:
1. Check if you want to continue on existing branch
2. Or create new branch with different name
3. Or delete old branch: git branch -D branch-name

Push Failures

If push fails:
1. Pull latest: git pull origin main
2. Resolve conflicts if any
3. Retry push

Configuration

Project .env Example

# Git Workflow Conventions
COMMIT_FORMAT=conventional
BRANCH_PREFIX_FEATURE=feature
BRANCH_PREFIX_BUG=fix
BRANCH_PREFIX_CHORE=chore

# GitHub
GITHUB_ORG=dugshub
GITHUB_REPO=tempo-demo
GITHUB_BASE_BRANCH=main

# Linear
PROJECT_TEAM_KEY=TEMPO

Per-Command Overrides

Commands can override conventions by setting environment variables before calling skill:

COMMIT_FORMAT=simple git-workflow-skill commit ...

Testing

Test Commit Formatting

# Test conventional format
TYPE=feat SCOPE=atoms MESSAGE="add cache" ISSUE_ID=TEMPO-1
# Should produce: "feat(atoms): add cache (TEMPO-1)"

# Test simple format
COMMIT_FORMAT=simple MESSAGE="add cache" ISSUE_ID=TEMPO-1
# Should produce: "add cache (TEMPO-1)"

Test Branch Naming

ISSUE_ID=TEMPO-123 ISSUE_TITLE="Add User Authentication"
# Should produce: "feature/TEMPO-123-add-user-authentication"

Best Practices

1. Always use this skill for git operations - Never call git directly from commands
2. Commit frequently - After each logical unit of work
3. Use atomic commits - One change per commit
4. Separate concerns - Tests in separate commits from implementation
5. Include issue ID - Always reference Linear issue
6. Use proper types - Choose correct commit type
7. Scope accurately - Use path-based scopes for clarity
8. Keep messages concise - Describe what, not why (use commit body for why)

Troubleshooting

Skill not found

Ensure skill is at .claude/skills/git-workflow/SKILL.md

Conventions not loaded

Check .env file exists at project root and is readable

Commits don't follow format

Verify command is using this skill, not calling git directly

PR creation fails

Check gh CLI is installed and authenticated:

gh auth status
gh auth login