Git Workflow

Standard Git workflow for all tasks in this repository.

⚠️ MANDATORY: Check Branch Before Starting ANY Task

This is the FIRST step for ANY task that involves code changes.

Before writing any code or making any changes, you MUST check the current branch:

git branch --show-current

Decision Flow

Current Branch? │ ├─ main → ❌ DO NOT work here │ → Create a new branch first (see "Creating a New Branch") │ ├─ Feature branch for this task → ✅ Continue working │ └─ Different feature branch → ⚠️ Ask user which branch to use

If on main Branch

NEVER make changes directly on main . Always create a new branch first:

1. Ensure main is up to date

git fetch origin git reset --hard origin/main

2. Create new branch

git checkout -b {type}/{brief-description}-{issue-number}

If on Wrong Feature Branch

Ask the user:

"You are currently on branch {current-branch} . Should I:

• Continue working on this branch?

• Switch to main and create a new branch for this task?"

Example Check Output

$ git branch --show-current main

→ Must create new branch before any work!

$ git branch --show-current feature/add-taproot-support-123

→ OK to continue if this is the correct branch for the task

Branch Management

Creating a New Branch

Always create from latest main :

git fetch origin git checkout main git reset --hard origin/main git checkout -b {type}/{brief-description}-{issue-number}

Branch Naming Convention

Format: {type}/{brief-description}-{issue-number}

• Description should be short and meaningful (use kebab-case)

• Issue number at the end (just the number, no "issue-" prefix)

Type Prefix Example

Feature feature/

feature/add-taproot-support-123

Bug fix fix/

fix/db-connection-error-456

Refactoring refactor/

refactor/clean-arch-layer-789

Documentation docs/

docs/update-readme-311

DevOps/CI ci/

ci/add-lint-workflow-100

Chore chore/

chore/update-deps-200

Branch Rules

• Always from main : Never branch from feature branches

• One issue = One branch: Create only one branch per issue

• Short-lived: Merge within days, not weeks

• Delete after merge: Keep repository clean

⚠️ Important: No Multiple Branches Per Issue

Do NOT create multiple branches for the same issue.

❌ Prohibited Pattern: issue-123 → fix/first-attempt-123 → fix/second-attempt-123 ← Do NOT create this → fix/another-fix-123 ← Do NOT create this either

✅ Correct Pattern: issue-123 → fix/description-123 → Create PR → Review → Merge → (If needed) Create new issue with new branch

Pre-Work Verification

Before creating a new branch, always check the following:

1. Check for existing branches

git branch -a | grep "{issue-number}"

2. Check for existing PRs

gh pr list --search "{issue-number}"

• If existing branch exists: Continue working on that branch

• If existing PR exists: Merge the PR before starting new work

• If nothing exists: OK to create a new branch

Commit Conventions

This project uses Conventional Commits format. Commit messages are validated by lefthook commit-msg hook.

Format

{type}({scope}): {brief description}

• {detail 1}
• {detail 2}

Closes #{issue_number}

Types (Required)

Type Description Release Impact

feat

New feature MINOR

fix

Bug fix PATCH

docs

Documentation only

refactor

Code refactoring (no feature/fix)

test

Adding or updating tests

ci

CI/CD changes

chore

Maintenance tasks

build

Build system changes

perf

Performance improvements PATCH

style

Code style (formatting, etc.)

revert

Revert a previous commit

Breaking Changes

Add ! after type/scope to indicate breaking changes:

feat(btc)!: change address format to bech32m only fix!: remove deprecated API endpoint

Scope (Optional)

The following are suggested scopes, but other alphanumeric scopes are also permitted.

Scope Description

btc

Bitcoin-related

bch

Bitcoin Cash-related

eth

Ethereum-related

xrp

XRP-related

db

Database

api

API changes

cli

CLI changes

pr

PR review fixes

Examples

Feature with scope

git commit -m "feat(btc): add taproot address support

• Add bech32m encoding
• Update address validation

Closes #123"

Bug fix without scope

git commit -m "fix: resolve database connection timeout

• Increase pool timeout
• Add retry logic

Closes #456"

Documentation

git commit -m "docs: update architecture guide

• Add layer diagram
• Clarify dependency rules

Closes #789"

Breaking change

git commit -m "feat(btc)!: require bech32m for all taproot addresses

BREAKING CHANGE: Legacy address format no longer supported

Closes #999"

Validation Error

If commit message validation fails:

ERROR: Commit message does not follow Conventional Commits format.

Expected format: <type>(<scope>): <description>

Types: feat, fix, docs, refactor, test, ci, chore, build, perf, style, revert

Examples: feat(btc): add taproot address support fix: resolve database connection timeout docs: update architecture guide refactor(api): reorganize endpoint handlers

Your commit message: <your-invalid-commit-message>

Pull Request Creation

⚠️ MANDATORY: Ask Before Creating PR

Always ask the user before creating a PR.

Multi-phase tasks create multiple commits on a single branch. Do not create a PR until all commits are complete.

After commits are pushed, ALWAYS ask:

"Would you like me to create a PR? Or is there additional work to do?"

When to Ask

Situation Action

Single commit task Ask before creating PR

Multi-phase task Ask after ALL phases are complete

User explicitly requests PR Create PR without asking

Create PR

git push -u origin {branch-name}

Ask user: "Would you like me to create a PR?"

Only proceed if user confirms

gh pr create --title "{type}: {description}" --body "$(cat <<'EOF'

Summary

• {change 1}
• {change 2}

Test plan

• Verification commands pass
• Manual testing completed

Closes #{issue_number} EOF )"

PR Title Format

{type}: {description} (Closes #{issue_number})

Examples:

• feat: add taproot address support (Closes #123)

• fix: resolve database connection timeout (Closes #456)

• docs: update architecture guide (Closes #789)

PR Description Template

Summary

• Brief description of changes

Changes

• Change 1
• Change 2

Test plan

• Unit tests pass
• Integration tests pass (if applicable)
• Manual testing completed

Related

• Closes #{issue_number}
• Related to #{other_issue}

Pre-Commit Self-Review (Required)

Before EVERY commit, you MUST complete self-review:

Step 1: Run Verification Commands

Execute verification commands for the modified file types:

File Type Required Commands

Go (*.go ) make go-lint && make tidy && make check-build && make go-test

TypeScript (*.ts ) See typescript-development skill (Bun for xrpl-grpc-server, npm for eth-contracts)

Shell (*.sh ) make shfmt

Makefile make mk-lint

SQL/HCL make atlas-fmt && make atlas-lint

Step 2: Complete Self-Review Checklist

Read the applicable language skill and verify ALL checklist items:

File Type Skill Section to Check

Go (*.go ) go-development

Self-Review Checklist

TypeScript/JS typescript-development

Self-Review Checklist

Shell (*.sh ) shell-scripts

Verification Checklist

Makefile makefile-update

Verification Checklist

SQL/HCL db-migration

Verification Checklist

Step 3: Confirm Before Commit

Only proceed to commit after:

• All verification commands pass

• Self-review checklist is complete

• No unresolved linter errors

⚠️ DO NOT commit until all steps are verified.

Safety Rules

Allowed Operations

• git add

• Stage changes

• git commit

• Create commits

• git push

• Push to remote

• git checkout -b

• Create branches

NOT Allowed Operations

• git push --force

• Never force push

• git merge

• Don't merge locally

• git rebase on shared branches - Avoid rebasing

• Direct commits to main

• Always use PRs

Quick Reference

New Issue Workflow

0. Check for existing branches/PRs (Required)

git branch -a | grep "{issue-number}" gh pr list --search "{issue-number}"

→ If exists, continue working on that branch

1. Update main

git fetch origin && git checkout main && git reset --hard origin/main

2. Create branch (only if none exists)

git checkout -b {type}/{brief-description}-{issue-number}

3. Make changes...

4. Self-Review (REQUIRED - see "Pre-Commit Self-Review" section)

- Run verification commands for modified file types

- Complete self-review checklist from language skill

- Confirm no linter errors

5. Commit (only after self-review is complete)

git add <files> git commit -m "{type}: {description}

Closes #{number}"

6. Push

git push -u origin {branch-name}

7. Ask user before creating PR (REQUIRED)

"Would you like me to create a PR? Or is there additional work?"

Only create PR if user confirms

gh pr create --title "{type}: {description}"

PR Review Fixes

Already on PR branch

1. Make fixes...

2. Self-Review (REQUIRED)

Run verification commands & complete checklist

3. Commit and push

git add <files> git commit -m "fix(pr): address review comments" git push