/commit-standards

name: commit-standards
description: Guidelines for consistent, well-documented commits in SDD projects

Commit Standards

Create consistent, well-documented commits that maintain a clear project history and changelog.

---

When This Skill Applies

**CRITICAL:** Every filesystem change should be committed before continuing to prevent data loss, especially during iterative sessions.

• User explicitly asks to commit (e.g., "commit this", "let's commit", "/commit")
• **After any filesystem change** - files created, modified, or deleted
• After completing an SDD workflow that produces artifacts:
• After `/sdd I want to initialize a new project` creates specs/plans
• After `/sdd I want to create a new feature` creates a change workflow
• After `/sdd I want to approve the spec` creates a PLAN.md
• After `/sdd I want to start implementing` completes phases
• After `/sdd I want to verify the implementation` completes a change
• Before starting a new task or switching context

---

Commit Message Format

[Action] [Component]: [Description], bump to [project version]

[Detailed explanation - same as changelog body]

Co-Authored-By: SDD Plugin vX.Y.Z

**IMPORTANT:** Always verify the **project version** with the user (appears in commit message and changelog).

Actions

| Action | Use When | |--------|----------| | Add | New feature or file | | Fix | Bug fix | | Update | Enhancement to existing feature | | Remove | Deletion | | Refactor | Code restructuring without behavior change | | Docs | Documentation only | | Tasks | Task management changes |

Examples

Add user-auth: Implement login and registration flow, bump to 1.2.0

- Token-based authentication with refresh tokens
- Registration with email verification
- Password reset flow
- Session management utilities

Co-Authored-By: SDD Plugin v5.1.0

Fix api-gateway: Resolve timeout on large payloads, bump to 1.1.1

Increased default timeout from 30s to 120s for file upload endpoints.
Added chunked transfer encoding support.

Co-Authored-By: SDD Plugin v5.1.0

Docs specs: Add user-auth change spec and plan

Created change spec and implementation plan for user authentication feature.

Co-Authored-By: SDD Plugin v5.1.0

Note: The "bump to X.Y.Z" suffix is only included when a version bump occurs.

---

Changelog Standards

Directory Structure

changelog/
├── v1.md    # All 1.x releases
├── v2.md    # All 2.x releases
├── v3.md    # All 3.x releases
└── ...

All changelog entries go in the appropriate `changelog/vN.md` file based on major version.

Entry Format

## [x.y.z] - YYYY-MM-DD

### [Category]

- **[component]**: Description of change
  - Detail 1
  - Detail 2

### Rationale

Why this change was made (for significant changes).

Categories

| Category | Use When | |----------|----------| | Added | New features | | Changed | Changes to existing functionality | | Enhanced | Improvements to existing features | | Fixed | Bug fixes | | Removed | Removed features |

Single File Update

Add the changelog entry to `changelog/vN.md` (where N is the major version).

Example: Version `5.1.0` → add entry to `changelog/v5.md`

Commit Body = Changelog Body

The detailed description in the commit message should be **identical** to the changelog entry body. Write once, use for both:

# Commit message body:
- Token-based authentication with refresh tokens
- Registration with email verification
- Password reset flow

# Changelog entry body (same content):
- **[user-auth]**: Implement login and registration flow
  - Token-based authentication with refresh tokens
  - Registration with email verification
  - Password reset flow

---

Version Bump Guidelines

Project Version Location

The project version is stored in `sdd/sdd-settings.yaml`. Delegate to the `project-settings` skill for the version location and format — it returns the `version` field from the project settings root, following semver (`MAJOR.MINOR.PATCH`).

Semver

| Type | Version Change | Use When | |------|----------------|----------| | PATCH | x.x.Z | Bug fixes, small improvements | | MINOR | x.Y.0 | New features, backwards compatible | | MAJOR | X.0.0 | Breaking changes |

When to Bump

Version bump is required when changing:

• Source code in `src/` or component directories
• Public API or contracts
• Configuration that affects behavior

Version bump is NOT required for:

• Documentation-only changes
• Test-only changes
• Development tooling changes
• Spec/plan creation (planning phase)

---

SDD-Aware Practices

Reference Change Directories

When implementing from a spec, reference the change directory:

Add user-auth: Implement login flow (changes/2026/01/user-auth)

Implements phase 1 of the user-auth change spec.

Commit at Key Points

1. **After spec/plan creation** - Preserve planning work before implementation 2. **After each implementation phase** - Capture incremental progress 3. **After completing all phases** - Mark the change as complete

Update Plan Status

When a commit completes work tracked in a plan, update the plan status:

## Status: COMPLETED

**Completed: 2026-01-29**

---

Best Practices

One Commit = One Changelog Entry

If your changes would result in multiple changelog entries, split them into separate commits.

**Wrong:**

git add . && git commit -m "Add feature A, fix bug B, refactor C"
# Results in 3 changelog entries in one commit

**Correct:**

git add feature-files && git commit -m "Add feature A"
git add bugfix-files && git commit -m "Fix bug B"
git add refactor-files && git commit -m "Refactor C"

Atomic Commits

Each commit should represent one logical change. If you can't describe the commit in one sentence, it's probably too big.

Message Style

• **Imperative mood:** "Add feature" not "Added feature"
• **Subject under 72 charac