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

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:

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:

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:

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:

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 or 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 workflow enforces this by committing after each task completion.

Practical Code Examples

Committing a New Feature

When adding functionality during phase 04, plan 01:

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)

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

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 – Defines the generic docs({scope}) pattern and rules for when to skip commits.
• references/git-integration.md – Details the per-task commit format ({type}({phase}-{plan})) and the commit-type taxonomy.
• workflows/remove-phase.md – Example workflow using chore commits to record phase removal.
• workflows/quick.md – Demonstrates atomic commit guarantees for ad-hoc quick tasks.
• 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 or 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 or 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}