/commit

name: commit
description: Create a commit following repository guidelines with proper versioning and changelog updates.

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:**

| Directory/File | Description | |----------------|-------------| | `plugin/core/commands/` | All command `.md` files | | `plugin/core/skills/` | All core skill `.md` files | | `plugin/core/system/` | Core CLI system source files | | `plugin/core/permissions/` | Permission configuration | | `plugin/fullstack-typescript/agents/` | All agent `.md` files | | `plugin/fullstack-typescript/skills/` | All tech pack skill `.md` files | | `plugin/fullstack-typescript/system/` | Tech pack CLI system source files | | `plugin/fullstack-typescript/templates/` | All template files | | `plugin/.claude-plugin/` | Plugin manifest |

**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:**

| Scenario | Action | |----------|--------| | Plan created and approved | Use `/tasks plan-review N` to move task to plan-review | | Starting implementation | Use `/tasks implement N` to move task to implementing | | Implementation complete | Use `/tasks review N` to move task to reviewing | | Work fully done | Use `/tasks complete N` to mark task complete |

**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]