Commit Writer

commit-writer

Generates proper conventional commit messages from staged changes.

Instructions

1. Check what's staged

``bash git diff --staged --stat `` If nothing is staged, inform the user and exit.

1. Read the actual changes

``bash git diff --staged ` If the diff is very large (>500 lines), sample key files instead: `bash git diff --staged --stat git diff --staged path/to/key/file.ts ``

1. Read recent commit history for style

``bash git log --oneline -10 git log -1 --format="%B" `` This shows the repository's commit message conventions.

1. Determine the commit type

• feat: new functionality added
• fix: bug fix
• refactor: restructuring without behavior change
• chore: tooling, config, dependencies, build setup
• docs: documentation only
• test: test additions or changes
• perf: performance improvement
• style: formatting only, no logic change

If changes span multiple types, pick the dominant one and mention others in the body.

1. Write the subject line

Format: type: short imperative summary

• Under 72 characters
• No period at the end
• Imperative mood ("add", "fix", "merge" — not "added", "fixed", "merged")
• Be specific but concise

1. Decide if body is needed

Skip the body for:

• Typo fixes
• Single small bug fixes
• Dependency bumps
• Self-explanatory one-liners

Write a full body for:

• Structural changes
• Multi-file refactors
• New features
• Anything that changes behavior
• Anything where "why" isn't obvious from "what"

1. When writing a body

Structure: ``` First paragraph: what changed and why, in plain English.

Changes:

• Group related changes logically
• Use bullet points for clarity
• Include file paths or component names

Updated:

• List modified existing features
• Explain impact on behavior

Renamed:

• Old → new mappings
• Explain why renamed

```

Breaking changes: Call out explicitly with "BREAKING CHANGE:" on its own line, followed by what breaks and how to migrate.

User context: If the user provided extra context as an argument to this skill, weave it naturally into the body rather than appending.

1. Check for unrelated changes

If staged changes span genuinely unrelated concerns (e.g., a feature plus an unrelated dependency bump), flag this:

> "These look like two unrelated changes: > 1. [feature description] > 2. [dependency/fix description] > > Want me to write one message covering both, or should we split > into separate commits?"

Wait for their answer before proceeding.

1. Show the message and confirm

Display the complete commit message in a code block, then ask:

`` Use this commit message? [Y] yes [E] edit [N] cancel ``

1. On [Y] — commit

For short messages: ``bash git commit -m "type: subject" -m "body paragraph" ``

For complex multi-paragraph bodies, write to a temp file: ``bash cat > /tmp/commit-msg.txt COMMIT_EOF git commit -F /tmp/commit-msg.txt rm /tmp/commit-msg.txt ``

1. On [E] — edit

Ask: "What should I change?" Wait for feedback, regenerate, show again.

1. On [N] — cancel

Confirm cancellation and exit without committing.

Co-Author tag

Always append this line to the commit body:

Co-Authored-By: Claude Sonnet 4.5 (1M context) 

Examples

Example 1: Feature addition

Staged changes: New authentication flow with JWT tokens

Message:

feat: add JWT-based authentication system

Replaces session cookies with JWT tokens for better scalability
and easier mobile client support. Tokens expire after 7 days
and include refresh token rotation.

Changes:
- src/auth/jwt.ts — token generation and verification
- src/middleware/auth.ts — JWT validation middleware
- src/routes/auth.ts — login/logout/refresh endpoints
- package.json — added jsonwebtoken dependency

Updated:
- User model to store refreshTokenVersion for invalidation
- API clients to include Authorization header

BREAKING CHANGE: clients must now send 'Authorization: Bearer '
header instead of relying on cookies. See migration guide in docs/auth.md.

Co-Authored-By: Claude Sonnet 4.5 (1M context) 

Example 2: Bug fix (no body needed)

Staged changes: One-line fix for null pointer

Message:

fix: prevent null pointer in user profile loader

Example 3: Refactor

Staged changes: Reorganized directory structure

Message:

refactor: move executive agents into department directories

Executives now live inside the department they steer instead of
as separate top-level folders. This reflects that an executive
is the steering layer of its org, not a standalone entity.

Changes:
- cfo/ → finance/exec/
- cmo/ → marketing/exec/
- cto/ → engineering/exec/
- cpo/ → product/exec/
- coo/ → operations/exec/
- All department agents updated with reportsTo field

Updated:
- company-os.ts schema — exec state nests under department
- router.ts — agent discovery updated for new structure
- All .md agents — corrected read/write paths

Renamed for clarity:
- product/exec/roadmap.md → product/exec/roadmap-oversight.md
- operations/exec/operations.md → operations/exec/daily-operations.md

No functional behavior change — this is structural only. All
agent logic, watch/reason/act cycles, and company.os coordination
remain the same.

Co-Authored-By: Claude Sonnet 4.5 (1M context) 

Usage

In any conversation with staged changes:

/commit-writer

Or with context:

/commit-writer This fixes the bug reported in issue #42 where users 
couldn't log in after password reset.

The skill will analyze the diff, generate the message, and walk you through confirmation before committing.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jordantplows
• Source: jordantplows/STARTUP-OS.MD
• License: MIT

Install and usage instructions live in the source repository linked above.