Commit Skill

Create commits that follow the repository's guidelines with proper versioning and changelog updates.

Workflow

Step 1: Analyze Changes

Run git status and git diff to understand:

• Which files have been modified
• Which plugins are affected
• Whether version files need updating
• Whether CHANGELOG needs updating

Step 1.5: Build Verification

When to run: If any changed files are under plugin/core/system/ or plugin/fullstack-typescript/system/ (TypeScript source).

Run npm run typecheck:plugin and verify it passes. If there are type errors, fix them before proceeding — never commit code that doesn't compile.

Skip conditions:

• No changes under plugin/core/system/ or plugin/fullstack-typescript/system/
• Changes are only to .md files, .tasks/, or non-TypeScript files

Step 2: Version Check

For each affected plugin, check if version bump is needed:

Files That REQUIRE Version Bump:

Files That Do NOT Require Version Bump (Marketplace-Level):

• Root README.md
• Root CLAUDE.md
• Root CONTRIBUTING.md
• changelog/ directory (changelog entries go in version-specific files)
• .claude/skills/ (marketplace-level skills)
• .gitignore
• .claudeignore
• plugin/tests/ (test files)

If version bump is needed, prompt for type:

• PATCH (x.x.Z): Bug fixes, small improvements
• MINOR (x.Y.0): New features, backwards compatible
• MAJOR (X.0.0): Breaking changes

Update BOTH files:

• plugin/.claude-plugin/plugin.json
• .claude-plugin/marketplace.json

Step 2.5: Manifest Validation

When to run: After updating version files, before proceeding to changelog.

If changes affect plugin/.claude-plugin/plugin.json or .claude-plugin/marketplace.json:

1. Use the manifest-validation skill to validate both manifests
2. Fix any errors before proceeding

Quick validation:

# Verify versions match
jq -r '.version' plugin/.claude-plugin/plugin.json
jq -r '.plugins[0].version' .claude-plugin/marketplace.json

Skip conditions:

• No changes to manifest files
• Version-only changes (version match is checked above)

Step 3: Changelog Check

Changelog structure:

• changelog/v{N}.md - Per-major-version files (v1.md, v2.md, v3.md, v4.md, v5.md)

Plugin changes: Format ## [x.y.z] - YYYY-MM-DD (versioned releases) Infrastructure changes: Format ## Infrastructure - YYYY-MM-DD (date-based)

Update the version-specific file (changelog/v{major}.md): Add entry at the top (after the header)

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:

• Added - New features
• Changed - Changes to existing functionality
• Enhanced - Improvements to existing features
• Fixed - Bug fixes
• Removed - Removed features

Determining the version file:

• Extract major version from new version (e.g., 5.0.2 → v5.md)
• File path: changelog/v{major}.md

Step 4: Documentation Check

When to run: If changes affect plugin functionality (commands, agents, skills, directory structure, workflows).

What to check:

1. Invoke the docs-standards agent to audit documentation against current plugin state
2. Review any inconsistencies found
3. Fix documentation issues before proceeding to commit

Documentation files to verify:

• README.md - Quick start, project structure, permissions
• docs/getting-started.md - Tutorial and structure diagrams
• docs/commands.md - Command references and examples
• docs/workflows.md - Workflow examples
• docs/agents.md - Agent descriptions
• docs/components.md - Component types

Skip conditions:

• Changes only affect test files
• Changes only affect marketplace-level skills (.claude/skills/)
• Changes only affect task management (.tasks/)
• Trivial changes (typos, formatting)

Step 5: Task Status Check

If changes involve .tasks/ or are related to a tracked task:

Use the tasks skill to ensure proper task status management. The tasks skill is authoritative for:

• Task lifecycle (inbox → speccing → planning → plan-review → implementing → reviewing → complete)
• Plan creation and approval workflows
• Automatic status transitions based on user actions

Common scenarios:

Skip conditions:

• Trivial changes (typos, formatting) don't need task tracking
• Changes already have correct task status

Step 6: Generate Commit Message

Task-context detection: Before generating the message, check if the current branch is a feature branch for a task (e.g., feature/task-19-*). If so, and the task is in 4-implementing/ or 5-reviewing/, prefix the commit message with the task reference:

Task #19: [Action] [Component]: [Description]

Version bumps on feature branches:

• During implementation: The final commit before moving to review must include the version bump and changelog entry (run Steps 2–3). Earlier implementation commits skip Steps 2–3.
• During reviewing: If the previous commit has NOT been pushed, amend it and update the changelog entry. If it HAS been pushed, create a new commit but amend the existing changelog entry in-place (update the version entry, do not create a new one). Never create a second version bump — only update the one created during implementation.

Default format (when not on a task feature branch):

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

[Optional detailed explanation]

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Actions:

• 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 (adding, completing, updating tasks in .tasks/)

Step 7: Review and Confirm

Task-only commits (all changed files are under .tasks/): Skip confirmation — proceed directly to Step 8.

All other commits: Present to the user:

• Summary of files to be committed
• Proposed commit message
• Version changes (if any)
• Changelog additions (if any)

Wait for user confirmation before proceeding.

Step 8: Execute Commit

After confirmation (or immediately for task-only commits):

1. Stage all related files (code + version files + CHANGELOG)
2. Create the commit with the generated message
3. Display commit result

Example

User: /commit

Agent: Analyzing changes...

Found changes in:
- plugin/fullstack-typescript/agents/backend-dev.md

Detected plugin: plugin (current version: 1.10.19)

Version files need updating:
- plugin/.claude-plugin/plugin.json
- .claude-plugin/marketplace.json

What type of version bump?
1. PATCH (1.10.19 → 1.10.20) - Bug fixes, small improvements
2. MINOR (1.10.19 → 1.11.0) - New features
3. MAJOR (1.10.19 → 2.0.0) - Breaking change