Menu
Guidelines for consistent, well-documented commits in SDD projects
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Orchestrates SDD project initialization — version detection, environment verification, scaffolding, and git setup.
Manage project settings in sdd/sdd-settings.yaml including component settings that drive scaffolding.
Single gateway for all core↔tech-pack interactions. Reads manifests, resolves paths, loads skills/agents, routes commands.
Manage tasks and plans using the .tasks/ directory.
Standards for authoring SDD plugin agents — frontmatter, self-containment, skill references, and no-user-interaction rules.
Standards for authoring SDD plugin commands — frontmatter, user interaction, skill/agent invocation, CLI integration, and output formatting.
| name | commit-standards |
| description | Guidelines for consistent, well-documented commits in SDD projects |
Create consistent, well-documented commits that maintain a clear project history and changelog.
CRITICAL: Every filesystem change should be committed before continuing to prevent data loss, especially during iterative sessions.
/sdd I want to initialize a new project creates specs/plans/sdd I want to create a new feature creates a change workflow/sdd I want to approve the spec creates a PLAN.md/sdd I want to start implementing completes phases/sdd I want to verify the implementation completes a change[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).
| 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 |
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/
├── 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.
## [x.y.z] - YYYY-MM-DD
### [Category]
- **[component]**: Description of change
- Detail 1
- Detail 2
### Rationale
Why this change was made (for significant changes).
| Category | Use When |
|---|---|
| Added | New features |
| Changed | Changes to existing functionality |
| Enhanced | Improvements to existing features |
| Fixed | Bug fixes |
| Removed | Removed features |
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
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
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).
| 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 |
Version bump is required when changing:
src/ or component directoriesVersion bump is NOT required for:
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.
When a commit completes work tracked in a plan, update the plan status:
## Status: COMPLETED
**Completed: 2026-01-29**
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"
Each commit should represent one logical change. If you can't describe the commit in one sentence, it's probably too big.
Before amending, check if the commit has been pushed:
git log origin/main..HEAD --oneline
Before committing, verify:
[ ] Version in sdd/sdd-settings.yaml updated (if version bump needed)
[ ] Changelog entry in changelog/vN.md
[ ] Commit body matches changelog body
[ ] All related files staged
[ ] Commit message follows format
[ ] Co-Authored-By includes SDD Plugin version
Any filesystem change? → Commit immediately to prevent data loss
Code change? → Version bump → Changelog (changelog/vN.md) → Commit
Docs only? → Changelog (changelog/vN.md) → Commit
Spec/plan? → Changelog (changelog/vN.md) → Commit
Always: Verify project version with user before committing
This skill defines no input parameters or structured output.