Project Commit

Create a commit following project conventions.

Current State

• Branch: !git branch --show-current
• Staged changes: !git diff --cached --stat
• Unstaged changes: !git diff --stat
• Untracked files: !git status --short

Commit Rules

1. Detect identifier from current branch name using .claude/skills/_shared/milestone-format.sh:
   • Legacy M-format: feature/M9.16-description → M9.16 (format: M)
   • New OpenSpec change-id: feature/architecture-compliance-sweep → architecture-compliance-sweep (format: kebab)
   • The shared utility normalizes both; commit prefix uses whichever format the branch uses.
2. Stage specific files — never use git add . or git add -A (risk of committing secrets or large binaries)
3. Format commit message:
   • First line: <identifier>: Brief description (imperative mood, e.g., "Add", "Fix", "Update")
   • Blank line
   • Bullet points of specific changes
4. NO Co-Authored-By line — this is a project convention
5. Use HEREDOC for multi-line messages

Message Format

Legacy M-format branch:

M9.16: Brief imperative description

- Detail 1
- Detail 2

New OpenSpec change-id branch:

architecture-compliance-sweep: Brief imperative description

- Detail 1
- Detail 2

Process

Step 0: Doc Freshness Check

Before staging, verify core docs are current. For each issue found, fix it before proceeding:

1. current-story.md: Verify active milestone matches branch. If stale, update milestone status and progress.
2. next-prompt.md: Verify hub has pointer for current milestone. Scaffold if missing.
3. next-prompt-PREFIX-#.md: Verify file exists for branch's milestone. Scaffold if missing.
4. development-journal.md: Check today's date in first 20 lines. If stale, run /dev-journal via Agent (background).
5. insights-log.md: Verify file exists. Create if missing.
6. requirements.md: Verify current milestone has a section.

Prompt the user about insights: "Any technical insights worth logging from this session?" (optional, not blocking).

Include doc updates in the same commit as code changes — stage them alongside the code.

Step 1: Review and Stage

1. Review all changes (staged + unstaged + untracked)
2. Identify which files should be committed (ask user if unclear)
3. Stage the appropriate files by name (including any doc updates from Step 0)
4. Draft the commit message and show it to the user
5. Commit using HEREDOC format
6. Do NOT push unless explicitly asked

Commit Message Quality

Good:

• M10.3: Add photo import OCR service
• M8.4: Fix confidence routing threshold
• M7.5: Refactor service ownership pattern

Bad:

• Fixed stuff (no milestone prefix)
• M10.3: Updated files (vague)
• WIP (not descriptive)

Post-Commit

After committing, automatically run these via Agents (background) for efficiency:

1. Journal: Read the top of docs/development-journal.md — if the latest entry doesn't reference today's date or the current milestone, invoke /dev-journal via an Agent to update it
2. Insights: Ask the user if there are any unlogged technical insights from this session. If yes, invoke /log-insight via an Agent
3. Status line: Check whether the branch-keyed status file still reflects the current focus. If this commit represents a transition (phase complete, sub-task done, moving from build to review), refresh it:

bash .claude/skills/_shared/status-line.sh write "[<identifier>] <new focus>"

Typical post-commit transitions: phase 1 — scaffolding → phase 2 — wiring, or implementation → review / testing, or after the final commit ready for PR.