multi-repo-git-ops

What this skill does

# Multi-Repo Git Operations

This skill handles git operations in **multi-repo systems** that use git submodules. The parent repo orchestrates multiple service repos, each an independent git repository with its own branches, history, and CI/CD.

Understanding this structure is essential — git operations here always involve deciding **which repos** are affected and operating in each one correctly.

## Discovery Protocol

Before performing any git operations, discover the project structure dynamically. Never assume service names, branch mappings, or directory layout — always read from `.gitmodules`.

### Step 1: Identify submodules and their paths

```bash
# List all submodules with their paths
git config -f .gitmodules --get-regexp '\.path$'
```

### Step 2: Identify each submodule's tracked branch

```bash
# List all submodule branch mappings
git config -f .gitmodules --get-regexp '\.branch$'

# Get a specific service's default branch
git config -f .gitmodules submodule."{submodule-path}".branch
```

If a submodule has no branch configured in `.gitmodules`, check the remote:
```bash
cd {submodule-path}
git remote show origin | grep 'HEAD branch'
```

### Step 3: Detect project methodology

- **BMAD**: Check if `_bmad-output/implementation-artifacts/` directory exists
- If BMAD is detected, the BMAD Integration section applies

### Step 4: Cache discovered info for the session

After discovery, the agent knows:
- All submodule names and paths
- Each submodule's default branch
- Whether BMAD is in use
- The submodule directory prefix (commonly `services/`)

Use this cached information for all subsequent operations in the session.

## Repository Structure

A typical multi-repo project looks like this:

```
{parent-repo}/                       (parent repo — planning & orchestration only)
├── .gitmodules                      (submodule definitions with tracked branches)
├── services/                        (submodule repos — directory name may vary)
│   ├── auth-service/                (branch: develop)
│   ├── booking-service/             (branch: dev)
│   ├── config-repo/                 (branch: main)
│   └── ...
└── [project methodology dirs]       (e.g., _bmad-output/ if using BMAD)
```

**Key principle**: The parent repo tracks **commit pointers** to each submodule, not the submodule code itself. When you change code in a service, you commit in the service repo, then update the parent's pointer.

## Branch Conventions

### Default Branches by Service

Services may track different default branches — always look up the correct one before branching:

```bash
# Get a service's default branch (always use this — never assume)
git config -f .gitmodules submodule."{submodule-path}".branch
```

Different services in the same project often use different default branches (e.g., `develop`, `dev`, `main`). The only reliable source of truth is `.gitmodules`.

### Feature Branch Naming

**For ticket-based work** (JIRA/project tracker):
```
{type}/{TICKET-ID}-{short-description}
```
Examples: `feat/PROJ-1234-add-search-by-date`, `bugfix/PROJ-5678-fix-null-pointer`

**For BMAD story work** (derived from story file name):
```
feat/{story-key}
```
The story key comes from the story file name. A story file named `1-2-user-authentication.md` (representing Epic 1, Story 2) produces branch name `feat/1-2-user-authentication`.

**Branch type prefixes**: `feat/`, `fix/`, `bugfix/`, `chore/`, `base/`

## BMAD Integration (If Applicable)

This section applies only if the project uses the BMAD methodology. Detect this by checking for the `_bmad-output/implementation-artifacts/` directory.

BMAD manages work through story files and sprint status tracking. This section explains how git operations map to the BMAD lifecycle.

### How Stories Reference Services

BMAD story files live at `_bmad-output/implementation-artifacts/{story-key}.md`. Stories reference affected services in several ways — check all of these:

1. **Service tags in story title or body**: `[auth-service]`, `[scheduler-service]`
2. **Dev Notes section**: Lists "Source tree components to touch" with service paths
3. **Project Structure Notes**: References paths like `services/{service-name}/src/...`
4. **Tasks/Subtasks**: Individual tasks may reference different services

When a story doesn't explicitly tag services, look at the file paths mentioned in Dev Notes and Tasks to determine which submodule directories are involved.

### BMAD Status and Git Operations Mapping

BMAD tracks story status in `_bmad-output/implementation-artifacts/sprint-status.yaml`. Each status transition has corresponding git operations:

| Story Status Change | Git Operations Required |
|---|---|
| `backlog` → `ready-for-dev` | No git ops (story file creation only) |
| `ready-for-dev` → `in-progress` | Create feature branches in affected services |
| `in-progress` (ongoing work) | Commit changes in service repos |
| `in-progress` → `review` | Push all service branches, ensure clean state |
| `review` → `in-progress` (fixes) | Continue on same branches, commit fixes |
| `review` → `done` | PRs merged, update parent submodule pointers |

### Starting a BMAD Story (Git Setup)

When beginning work on a BMAD story, perform these git operations:

**Step 1: Read the story and identify services**
```bash
# Story files follow pattern: {epic_num}-{story_num}-{slug}.md
# Example: _bmad-output/implementation-artifacts/1-2-user-authentication.md
```

Read the story file. Extract affected services from:
- Service tags like `[auth-service]`
- File paths in Dev Notes (e.g., `services/{service-name}/src/...`)
- Task descriptions referencing specific services

**Step 2: Derive the branch name from the story key**
```bash
# Story file: 1-2-user-authentication.md → branch: feat/1-2-user-authentication
STORY_KEY="1-2-user-authentication"  # from the story file name (without .md)
BRANCH_NAME="feat/${STORY_KEY}"
```

**Step 3: Create branches in all affected services**
```bash
# For each affected service (replace with actual discovered service names):
for SERVICE in auth-service scheduler-service; do
  DEFAULT_BRANCH=$(git config -f .gitmodules submodule."services/$SERVICE".branch)
  cd services/$SERVICE
  git checkout $DEFAULT_BRANCH
  git pull origin $DEFAULT_BRANCH
  git checkout -b $BRANCH_NAME
  git push -u origin $BRANCH_NAME
  cd ../..
done
```

Use the **same branch name** across all affected services for traceability. This makes it easy to find all changes related to a story across the system.

**Step 4: Verify setup**
```bash
# Confirm all affected services are on the correct branch
git submodule foreach --quiet 'BRANCH=$(git branch --show-current); echo "$(basename $(pwd)): $BRANCH"'
```

### During Story Implementation

**Committing changes** — always commit inside the service directory:
```bash
cd services/{service-name}
git add {specific-files}
git commit -m "feat({scope}): add validation for booking dates

Story: {story-key}"
```

**Working across multiple services** — commit in each separately:
```bash
# Service A
cd services/auth-service
git add src/auth/jwt.service.ts src/auth/jwt.service.spec.ts
git commit -m "feat(auth): add JWT validation endpoint

Story: 1-2-user-authentication"

# Service B
cd ../bff-service
git add src/middleware/auth.middleware.ts
git commit -m "feat(middleware): add JWT auth middleware

Story: 1-2-user-authentication"
```

All commits must follow the **Commit Message Format** section below — this is critical for release-please to generate correct changelogs and version bumps.

### Completing a Story (Push & PR)

When story is ready for review:

**Step 1: Run quality checks in each affected service**
```bash
cd services/{service-name}
npm run lint
npm run format
npm run typecheck
npm test
```

**Step 2: Push each service's feature branch**
```bash
# Push services first — always before parent
cd services/{service-name}
git push origin feat/{story-key}
```

**Step 3: Create PR per service**
Each service gets its own P