git-integration git:20260507.8dfdcb4C

Immutable. This exact content is served forever at /api/v1/blob/6f8d35e730b8c6ac.

---
name: git-integration
description: Git commit patterns, formats, and conventions for GSD methodology. Provides atomic commits per task, structured commit messages, planning file commits, branch management, and milestone tag operations.
allowed-tools: Bash(*) Read Glob
metadata:
  author: babysitter-sdk
  version: "1.0.0"
  category: gsd-core
  backlog-id: SK-GSD-008
graph:
  domains: [domain:software-engineering]
  skillAreas: [skill-area:agentic-loops, skill-area:orchestration-loop]
  workflows: [workflow:feature-development]
  topics: [topic:developer-experience]
  roles: [role:tech-lead, role:backend-engineer]
1. **Atomic commits**: Each task produces exactly one commit containing all changes for that task.
2. **Separation of concerns**: Planning file changes (`.planning/`) are committed separately from code changes.

This corresponds to the patterns in the original `references/git-integration.md` and `references/git-planning-commit.md`.

## Capabilities

### 1. Atomic Commit Per Task

Each task in a plan produces one atomic commit:

```bash
# After completing task 1 of PLAN-1.md
git add src/auth/oauth.ts src/auth/types.ts
git commit -m "feat(auth): implement OAuth2 login endpoint

Phase 72, Plan 1, Task 1: Implement login endpoint
- Added POST /api/auth/login with email/password validation
- Returns JWT token on success, 401 on invalid credentials
- Rate limited to 5 attempts per minute

Refs: Phase-72/PLAN-1/Task-1"
```

Commit message format:
```
<type>(<scope>): <short description>

Phase <N>, Plan <M>, Task <K>: <task title>
- <change 1>
- <change 2>

Refs: Phase-<N>/PLAN-<M>/Task-<K>
```

Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `style`, `perf`.

### 2. Planning File Commits

Planning files are committed separately from code:

```bash
# After generating plans
git add .planning/phase-72/PLAN-1.md .planning/phase-72/PLAN-2.md
git commit -m "plan(phase-72): create execution plans

Phase 72: Authentication
- PLAN-1.md: OAuth2 login and token management (4 tasks, wave 1)
- PLAN-2.md: Auth middleware and role guards (3 tasks, wave 1)

Refs: Phase-72/planning"
```

Planning commit types: `plan`, `state`, `research`, `context`, `verify`, `audit`.

### 3. Commit Message Generation

Generate commit messages from task context:

```
Input:
  phase: 72
  plan: 1
  task: 1
  title: "Implement login endpoint"
  type: "feat"
  scope: "auth"
  changes: ["POST /api/auth/login endpoint", "JWT token generation", "Rate limiting"]

Output:
  "feat(auth): implement OAuth2 login endpoint

  Phase 72, Plan 1, Task 1: Implement login endpoint
  - Added POST /api/auth/login endpoint
  - JWT token generation on success
  - Rate limiting (5 attempts/minute)

  Refs: Phase-72/PLAN-1/Task-1"
```

### 4. Git Tag Creation

Create annotated tags for milestone completions:

```bash
git tag -a v1.0 -m "Milestone v1.0: MVP Launch

Phases completed: 70, 71, 72, 73
Requirements covered: R1-R11
Audit result: PASSED

Key deliverables:
- Project scaffolding and CI pipeline
- Database layer with migrations
- OAuth2 authentication
- REST API endpoints"
```

### 5. Branch Status Detection

Detect current branch state:

```json
{
  "branch": "main",
  "clean": false,
  "staged": ["src/auth/oauth.ts"],
  "unstaged": [".planning/STATE.md"],
  "untracked": ["src/auth/oauth.test.ts"],
  "ahead": 3,
  "behind": 0
}
```

### 6. Planning-Aware File Staging

Separate `.planning/` files from source code files:

```bash
# Stage code changes only
git add src/auth/oauth.ts src/auth/types.ts

# Stage planning changes only (separate commit)
git add .planning/phase-72/SUMMARY.md .planning/STATE.md
```

Rules:
- Code changes: committed with task-level commit messages
- Planning changes: committed with phase-level commit messages
- Mixed commits: never (always separate planning from code)

### 7. Commit History Analysis

Analyze commit history for progress tracking:

```
Phase 72 commits:
  abc1234 feat(auth): implement OAuth2 login endpoint (Task 1)
  def5678 feat(auth): add token refresh mechanism (Task 2)
  ghi9012 feat(auth): implement logout and revocation (Task 3)
  jkl3456 test(auth): add auth endpoint tests (Task 4)

Total: 4 commits, 12 files changed, +450 -30 lines
```

### 8. Diff Summary Generation

Generate diff summaries for SUMMARY.md:

```
Changes summary:
  Files created: 4
  Files modified: 2
  Files deleted: 0
  Lines added: 450
  Lines removed: 30

  New files:
    src/auth/oauth.ts (120 lines)
    src/auth/tokens.ts (85 lines)
    src/auth/types.ts (45 lines)
    src/middleware/auth.ts (90 lines)

  Modified files:
    src/routes/index.ts (+15 -2)
    package.json (+3 -0)
```

## Tool Use Instructions

### Creating an Atomic Commit
1. Use `Bash` to run `git status` to see current changes
2. Use `Bash` to stage only the files related to the current task: `git add <files>`
3. Generate commit message from task context
4. Use `Bash` to commit: `git commit -m "<message>"`
5. Verify commit succeeded with `git log -1`

### Creating a Planning Commit
1. Use `Bash` to identify planning file changes: `git status .planning/`
2. Stage only planning files: `git add .planning/<files>`
3. Generate planning commit message
4. Commit with planning-specific type prefix

### Creating a Milestone Tag
1. Use `Read` to load milestone audit data for tag annotation
2. Use `Bash` to create annotated tag: `git tag -a <version> -m "<annotation>"`
3. Verify tag with `git tag -l <version>`

### Checking Branch Status
1. Use `Bash` to run `git status --porcelain`
2. Use `Bash` to run `git rev-list --count HEAD..@{upstream}` for behind count
3. Use `Bash` to run `git rev-list --count @{upstream}..HEAD` for ahead count
4. Return structured status

## Process Integration

- `execute-phase.js` - Atomic commit per task during execution
- `verify-work.js` - Commit verification results and fixes
- `quick.js` - Atomic commit for quick task execution
- `debug.js` - Commit debug fixes
- `complete-milestone.js` - Create milestone git tag
- `add-tests.js` - Commit each test file atomically
- `research-phase.js` - Commit research document
- `plan-phase.js` - Commit generated plans (planning commit)

## Output Format

```json
{
  "operation": "commit|tag|status|history|diff",
  "status": "success|error",
  "commit": {
    "hash": "abc1234",
    "message": "feat(auth): implement OAuth2 login endpoint",
    "filesChanged": 3,
    "linesAdded": 120,
    "linesRemoved": 5
  },
  "tag": {
    "name": "v1.0",
    "annotation": "Milestone v1.0: MVP Launch"
  },
  "branchStatus": {
    "branch": "main",
    "clean": true,
    "ahead": 0,
    "behind": 0
  }
}
```

## Configuration

| Setting | Default | Description |
|---------|---------|-------------|
| `autoCommit` | `true` | Automatically commit after each task |
| `commitMessageFormat` | `conventional` | Commit message format (conventional/simple) |
| `separatePlanningCommits` | `true` | Separate planning from code commits |
| `signCommits` | `false` | GPG-sign commits |
| `tagPrefix` | `v` | Prefix for milestone tags |

## Error Handling

| Error | Cause | Resolution |
|-------|-------|------------|
| `Nothing to commit` | No changes to stage | Verify task made expected changes |
| `Merge conflict` | Conflicting changes in working tree | Resolve conflicts before committing |
| `Dirty working tree` | Uncommitted changes from previous task | Commit or stash before proceeding |
| `Tag already exists` | Milestone tag already created | Use `--force` or choose different tag name |
| `Detached HEAD` | Not on a branch | Checkout a branch before committing |

## Constraints

- Never create commits with mixed planning and code changes
- Each task gets exactly one code commit (atomic)
- Commit messages must follow the structured format with phase/plan/task references
- Planning commits use planning-specific type prefixes (plan, state, research, etc.)
- Tags are annotated (not lightweight) with milestone summary
- Never force-push or rewrite history on shared branches
- Always check for clean working tree before starting a new task