# Atomic Git Commits in gsd-build: The Complete Format Guide

> Learn the atomic git commit format for gsd-build: type phase-plan task. This structured approach helps AI parse work history efficiently.

- Repository: [GSD/get-shit-done](https://github.com/gsd-build/get-shit-done)
- Tags: how-to-guide
- Published: 2026-02-16

---

**gsd-build enforces atomic git commits using a structured message format `{type}({phase}-{plan}): {task-name}` that enables AI agents to parse work history without reading markdown files.**

The `gsd-build/get-shit-done` repository treats every unit of work as an **atomic commit**, ensuring that each change to the codebase is isolated, traceable, and machine-readable. This convention allows Claude-powered agents and other tools to reconstruct project state directly from `git log` output rather than parsing large planning documents.

## Commit Message Format Structure

gsd-build defines four distinct commit patterns depending on the context of the work. Each pattern embeds metadata about the phase, plan, and task directly into the message header.

### Task Completion Commits

When completing a specific task within a plan, use the format:

```

{type}({phase}-{plan}): {task-name}

```

- **`type`** – Conventional commit prefix: `feat`, `fix`, `test`, `refactor`, `perf`, `chore`, or `docs`.
- **`phase`** – Two-digit phase identifier (e.g., `04`).
- **`plan`** – Plan number within that phase (e.g., `01`).
- **`task-name`** – Short, imperative description of the change.

Example from [`references/git-integration.md`](https://github.com/gsd-build/get-shit-done/blob/main/references/git-integration.md):

```bash
node ~/.claude/get-shit-done/bin/gsd-tools.cjs commit "feat(04-01): add webhook signature verification" --files src/payments/webhook.ts

```

### Planning and Documentation Commits

For phase-level documentation, milestone tracking, or metadata updates, use the `docs` scope:

```

docs({scope}): {description}

```

The `{scope}` can be a phase identifier, milestone name, or other documentation category.

Example:

```bash
node ~/.claude/get-shit-done/bin/gsd-tools.cjs commit "docs(phase-03): create authentication plans"

```

### Work-in-Progress Handoffs

When pausing work to hand off context or save state without completing a task, use the `wip` prefix:

```

wip: {phase-name} paused at task {X}/{Y}

```

This pattern signals that the commit contains incomplete work and should not be considered a finished atomic unit.

Example:

```bash
node ~/.claude/get-shit-done/bin/gsd-tools.cjs commit "wip: checkout paused at task 3/5" --files .planning/

```

### Chore Commits

For maintenance actions like removing phases or updating configuration without changing business logic:

```

chore: {action}

```

Example from [`workflows/remove-phase.md`](https://github.com/gsd-build/get-shit-done/blob/main/workflows/remove-phase.md):

```bash
node ~/.claude/get-shit-done/bin/gsd-tools.cjs commit "chore: remove phase 17 (dashboard)"

```

## Why Atomic Commits Matter in gsd-build

The atomic commit convention in `gsd-build/get-shit-done` serves three critical functions:

- **Bisectability** – Each commit isolates a single logical change, making `git bisect` and `git blame` accurate for debugging. When a regression appears, you can identify the exact task that introduced it.
- **AI Context Retrieval** – Claude sessions pull history using `git log --grep="{phase}-{plan}"`. A well-structured message lets the model retrieve the exact work without parsing large markdown files like [`PLAN.md`](https://github.com/gsd-build/get-shit-done/blob/main/PLAN.md) or [`RESEARCH.md`](https://github.com/gsd-build/get-shit-done/blob/main/RESEARCH.md).
- **Recovery and Resumption** – If a task fails, a later run can resume from the last successful atomic commit. The [`agents/gsd-executor.md`](https://github.com/gsd-build/get-shit-done/blob/main/agents/gsd-executor.md) workflow enforces this by committing after each task completion.

## Practical Code Examples

### Committing a New Feature

When adding functionality during phase 04, plan 01:

```bash
git add src/payments/webhook.ts
node ~/.claude/get-shit-done/bin/gsd-tools.cjs commit "feat(04-01): add webhook signature verification" --files src/payments/webhook.ts

```

### Adding a Failing Test (RED Phase of TDD)

```bash
git add src/__tests__/payment.test.ts
node ~/.claude/get-shit-done/bin/gsd-tools.cjs commit "test(07-02): add failing test for payment processing" --files src/__tests__/payment.test.ts

```

### Documenting a Completed Plan

```bash
node ~/.claude/get-shit-done/bin/gsd-tools.cjs commit "docs(03-02): complete product listing plan" \
  --files .planning/phases/03-product/03-02-PLAN.md .planning/phases/03-product/03-02-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md

```

## Key Reference Files

The atomic commit format is defined and enforced across these files in the `gsd-build/get-shit-done` repository:

- **[`references/git-planning-commit.md`](https://github.com/gsd-build/get-shit-done/blob/main/references/git-planning-commit.md)** – Defines the generic `docs({scope})` pattern and rules for when to skip commits.
- **[`references/git-integration.md`](https://github.com/gsd-build/get-shit-done/blob/main/references/git-integration.md)** – Details the per-task commit format (`{type}({phase}-{plan})`) and the commit-type taxonomy.
- **[`workflows/remove-phase.md`](https://github.com/gsd-build/get-shit-done/blob/main/workflows/remove-phase.md)** – Example workflow using `chore` commits to record phase removal.
- **[`workflows/quick.md`](https://github.com/gsd-build/get-shit-done/blob/main/workflows/quick.md)** – Demonstrates atomic commit guarantees for ad-hoc quick tasks.
- **[`agents/gsd-executor.md`](https://github.com/gsd-build/get-shit-done/blob/main/agents/gsd-executor.md)** – Describes how the executor agent enforces atomic task commits during plan execution.

## Summary

- **Atomic commits in gsd-build** use a structured format embedding phase and plan metadata directly in the message header.
- **Task commits** follow `{type}({phase}-{plan}): {task-name}`, while **planning commits** use `docs({scope}): {description}`.
- **Intermediate artifacts** like [`PLAN.md`](https://github.com/gsd-build/get-shit-done/blob/main/PLAN.md) or [`RESEARCH.md`](https://github.com/gsd-build/get-shit-done/blob/main/RESEARCH.md) are never committed—only outcomes are captured.
- **AI agents** rely on this format to query history via `git log --grep` without parsing markdown files.
- **Recovery** is enabled by resuming from the last successful atomic commit if a task fails.

## Frequently Asked Questions

### What is the difference between a task commit and a planning commit in gsd-build?

Task commits use the format `{type}({phase}-{plan}): {task-name}` to record actual code changes, while planning commits use `docs({scope}): {description}` to document phase-level decisions, milestones, or metadata updates. Task commits are atomic units of work, whereas planning commits capture context and strategy.

### How does gsd-build handle incomplete work or interruptions?

When pausing work without completing a task, use the `wip:` prefix followed by the phase name and task progress, such as `wip: checkout paused at task 3/5`. This signals to AI agents and other tools that the commit contains incomplete work and should not be treated as a finished atomic unit.

### Why doesn't gsd-build commit planning artifacts like PLAN.md or RESEARCH.md?

The framework only commits outcomes, not intermediate planning artifacts. Files like [`PLAN.md`](https://github.com/gsd-build/get-shit-done/blob/main/PLAN.md) or [`RESEARCH.md`](https://github.com/gsd-build/get-shit-done/blob/main/RESEARCH.md) are considered working documents that may change frequently during task execution. By committing only the final code, tests, or documentation changes, the git history remains clean and each commit represents a reversible, deployable state.

### Can I use standard Conventional Commits with gsd-build?

Yes, gsd-build extends the Conventional Commits specification by adding structured metadata in the scope field. Standard prefixes like `feat`, `fix`, `test`, `refactor`, `perf`, `chore`, and `docs` are all valid. The framework simply requires that the scope portion follows the `{phase}-{plan}` pattern for task-related commits to enable AI parsing and automated workflow recovery.