Claude Skill

commit

Use when the user says "commit", "/commit", "save progress", or asks to land working changes on a feature or worktree branch. Grimoire working-phase posture — minimises commit count, can amend rolling Checkpoints, offers a one-time PR prompt. For pre-merge cleanup, use `/finalize

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download grimoire-rs-grimoire-.claude_skills_commit-dddf811.zip · 6 KB

Install

skills CLI npx skills add https://github.com/grimoire-rs/grimoire/tree/main/.claude/skills/commit
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install grimoire-rs-grimoire@llmmart
Git git clone https://github.com/grimoire-rs/grimoire.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole grimoire-rs/grimoire collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

/commit — Working-Phase Commit Workflow

Commit working tree during active dev on feature/worktree branch. Working phase half of Grimoire two-phase branch workflow — rebasing-phase cleanup for main lives in /finalize.

See workflow-git.md for full model: branching rules, two-phase model, Checkpoint convention, land-ready definition. Skill assumes those, implements working-phase posture on top.

Working-Phase Posture

  • Minimise commit count. Bundle freely. Amend rolling Checkpoints.
  • One concern per commit relaxed. Honest bundle message (chore(claude): bundle skill + rule + agent tweaks) beats fake one-concern narrative. /finalize split/reword later.
  • Don't badger user about splitting. Worktree branches (goat, evelynn, sion, soraka) explicitly working-phase by default. Cleanup at finalize time.

For land-ready branch contract, see "Land-Ready Definition" in workflow-git.md. That /finalize job, not /commit.

Inputs

Optional free-text arg. Treat as intent hint (e.g., fix grimoire install symlink bug), not full message — still draft final message. Flags:

  • /commit --amend — explicitly amend HEAD (bypasses Checkpoint-only safeguard)
  • /commit --pr — force PR-branch prompt even if previously declined
  • /commit --no-pr — skip + record PR skip

For rebasing-phase cleanup (squash, reword, split main..HEAD), use /finalize instead.

Workflow

1. Snapshot state (parallel batch)

  • git status --porcelain=v1 (never -uall)
  • git diff --staged and git diff --stat
  • git log -5 --oneline — recent commits + scan for stranded Checkpoint in window
  • git rev-parse --abbrev-ref HEAD — current branch
  • git rev-list --count main..HEAD 2>/dev/null — commits ahead of main
  • git config --get branch.<current>.grim-skip-pr-prompt — PR prompt already answered?
  • git log -1 --pretty=%s — HEAD itself Checkpoint?
  • gh pr view --json number,state 2>/dev/null — open PR for branch?

If working tree clean and HEAD not Checkpoint, stop with "nothing to commit".

2. Checkpoint scan (window, not just HEAD)

Look at last 5 commits for any with subject exactly Checkpoint.

Case A — HEAD itself is Checkpoint:

Two sub-cases by working tree state:

Sub-case Behavior
Dirty tree (unstaged/untracked changes exist) Auto-amend — stage all changed files by name and git commit --amend --no-edit. No question. Rolling Checkpoints absorb all active changes as union. Report what folded in.
Clean tree (no changes, Checkpoint holds accumulated work) Checkpoint itself is deliverable. Draft conventional commit message from Checkpoint diff (git diff main..HEAD), show, amend: git commit --amend -m "<drafted message>". "Finalize in place" path — user called /commit to give Checkpoint real name.

Case B — Checkpoint exists at HEAD1..HEAD5 but not HEAD (stranded): warn user. Means previous session made real work inside Checkpoint then landed other commits on top without finalizing. Offer:

Option Effect
Commit on top, leave stranded (default in working-phase) Normal commit. Stranded Checkpoint handled by /finalize before landing
Hand off to /finalize now Stop, tell user run /finalize for full rebase plan — safer than rewording one commit in isolation
Skip for now Ignore, continue

Case C — no Checkpoint in window: proceed.

3. Commit strategy

On worktree branch, prefer one of:

  1. Amend HEAD when HEAD is fresh local commit you authored (not yet touching main's reach) and new WIP clearly continuation of same concern. Ask first — amending destructive to commit hashes.
  2. New commit on top when HEAD already represents distinct concern.
  3. Start Checkpoint (git commit -m "Checkpoint") when user says "save progress" or WIP not yet coherent enough to name.

On non-worktree branch: never auto-amend. Always create new commit unless /commit --amend passed.

On main: stop. Tell user create feature branch first.

4. Draft the commit message

Follow Conventional Commits v1.0.0. See commit_reference.md for full cheat sheet and workflow-git.md for quick rules. Key points for working phase:

  • chore: for AI/tooling files (.claude/, AGENTS.md, CLAUDE.md, skills, rules, hooks, taskfiles) — keeps out of changelog
  • Imperative mood, lowercase description, no trailing period, subject ≤72 chars
  • Body explains why, not what, when non-obvious
  • Breaking: ! before colon and BREAKING CHANGE: footer
  • Never Co-Authored-By (Grimoire convention)

Working-phase bundles legitimate. If staged diff covers multiple concerns, chore(claude): bundle <what> style subject with body honestly listing clusters acceptable. Flag at body end that it will split or reword during /finalize.

Show drafted message to user for approval before committing.

5. PR-branch prompt (first time per branch only)

Skip entirely if any true:

  • git config --get branch.<current>.grim-skip-pr-prompt returns true
  • Open PR already exists for current branch
  • Current branch is fixed worktree branch (goat, evelynn, sion, soraka) — record skip, move on
  • Current branch is main — stop, tell user create feature branch first

Otherwise, AskUserQuestion:

  1. Create feature branch + PR — derive name from commit subject (e.g. feat/relative-symlinks), branch from HEAD, commit there, gh pr create with title from subject and body summary
  2. Stay on current branch — commit here. Record: git config branch.<current>.grim-skip-pr-prompt true. Never ask again unless /commit --pr
  3. Cancel — abort

6. Stage and commit

  • Stage files by name, never git add -A / .. Prevents accidentally-committed secrets and bug where pre-staged files from previous session get swept into commit whose message doesn't describe them.

  • Warn before staging anything matching .env*, *credentials*, *.pem, *.key, or token patterns; require explicit confirmation.

  • --amend must fold dirty tree into HEAD. When /commit --amend invoked and working tree has uncommitted changes, those changes must be staged and included in amend — --amend with nothing staged silently becomes message-only amend that drops user's active work. Always git add <files> before git commit --amend, even when user only asked to "amend". After amend, run git show --stat HEAD and confirm expected files appear in diff stat before reporting success.

  • Pre-commit hook (pre_commit_verification.py) blocks commits without fresh task verify. When blocks, run task verify (not --no-verify), then mark state in separate Bash call (combining with commit in one && chain does not satisfy hook):

    echo $(date +%s) > .claude/hooks/.state/commit-verified
    

    Then retry. On retry, re-run git add too — blocked Bash invocation ran nothing, not even part before &&, so staging gone if chained.

  • Commit with HEREDOC:

    git commit -m "$(cat <<'EOF'
    <type>[scope]: <description>
    
    <optional body explaining why>
    EOF
    )"
    
  • Never --no-verify, --no-gpg-sign, or any hook-skipping flags. If hook fails, fix root cause and create new commit (not --amend — previous commit stands).

  • Never push. Human decides when to push.

7. Bump plan Status Last update

After successful commit, if .claude/state/current_plan.md exists and references a plan with a ## Status block:

  • Bump Last update: line in the Status block to today's date with the new HEAD sha: - **Last update:** YYYY-MM-DD (after <sha-short>: <subject>)
  • Do NOT advance Active phase: — phase advancement is the plan author's decision (next phase entry in /hex-execute), not an automatic side-effect of commits.
  • Skip silently when no current_plan.md, no plan match, no Status block.

This keeps /next's staleness check (plan-mtime-vs-Last update) accurate without surprising the user.

8. Report

One or two sentences: commit hash, subject, whether stranded-Checkpoint case handled, whether PR opened, whether Status Last update was bumped. Nothing else.

References

  • workflow-git.md — shared branch/commit hygiene: branching model, two-phase model, Checkpoint convention, land-ready definition
  • commit_reference.md — Conventional Commits v1.0.0 cheat sheet
  • /finalize skill (../finalize/SKILL.md) — rebasing-phase sibling for cleaning main..HEAD before landing
  • AGENTS.md — worktree layout, "Landing a feature" section
Files (grimoire)
  • commit_reference.md 3.9 KB
    Loading…
  • SKILL.md 9.1 KB
    ---
    name: commit
    description: Use when the user says "commit", "/commit", "save progress", or asks to land working changes on a feature or worktree branch. Grimoire working-phase posture — minimises commit count, can amend rolling Checkpoints, offers a one-time PR prompt. For pre-merge cleanup, use `/finalize`.
    user-invocable: true
    disable-model-invocation: true
    argument-hint: "[optional context or --pr | --no-pr | --amend]"
    triggers:
      - "commit"
      - "save progress"
      - "commit my changes"
      - "commit the changes"
      - "stage and commit"
    ---
    
    # /commit — Working-Phase Commit Workflow
    
    Commit working tree during active dev on feature/worktree branch. **Working phase** half of Grimoire two-phase branch workflow — rebasing-phase cleanup for `main` lives in `/finalize`.
    
    See [workflow-git.md](../../rules/workflow-git.md) for full model: branching rules, two-phase model, Checkpoint convention, land-ready definition. Skill assumes those, implements working-phase posture on top.
    
    ## Working-Phase Posture
    
    - **Minimise commit count.** Bundle freely. Amend rolling Checkpoints.
    - **One concern per commit relaxed.** Honest bundle message (`chore(claude): bundle skill + rule + agent tweaks`) beats fake one-concern narrative. `/finalize` split/reword later.
    - **Don't badger user about splitting.** Worktree branches (`goat`, `evelynn`, `sion`, `soraka`) explicitly working-phase by default. Cleanup at finalize time.
    
    For land-ready branch contract, see "Land-Ready Definition" in [workflow-git.md](../../rules/workflow-git.md). That `/finalize` job, not `/commit`.
    
    ## Inputs
    
    Optional free-text arg. Treat as intent hint (e.g., `fix grimoire install symlink bug`), not full message — still draft final message. Flags:
    
    - `/commit --amend` — explicitly amend HEAD (bypasses Checkpoint-only safeguard)
    - `/commit --pr` — force PR-branch prompt even if previously declined
    - `/commit --no-pr` — skip + record PR skip
    
    For rebasing-phase cleanup (squash, reword, split `main..HEAD`), use `/finalize` instead.
    
    ## Workflow
    
    ### 1. Snapshot state (parallel batch)
    
    - `git status --porcelain=v1` (never `-uall`)
    - `git diff --staged` and `git diff --stat`
    - `git log -5 --oneline` — recent commits + scan for stranded `Checkpoint` in window
    - `git rev-parse --abbrev-ref HEAD` — current branch
    - `git rev-list --count main..HEAD 2>/dev/null` — commits ahead of main
    - `git config --get branch.<current>.grim-skip-pr-prompt` — PR prompt already answered?
    - `git log -1 --pretty=%s` — HEAD itself Checkpoint?
    - `gh pr view --json number,state 2>/dev/null` — open PR for branch?
    
    If working tree clean **and** HEAD not Checkpoint, stop with "nothing to commit".
    
    ### 2. Checkpoint scan (window, not just HEAD)
    
    Look at last 5 commits for any with subject exactly `Checkpoint`.
    
    **Case A — HEAD itself is `Checkpoint`**:
    
    Two sub-cases by working tree state:
    
    | Sub-case | Behavior |
    |---|---|
    | **Dirty tree** (unstaged/untracked changes exist) | **Auto-amend** — stage all changed files by name and `git commit --amend --no-edit`. No question. Rolling Checkpoints absorb all active changes as union. Report what folded in. |
    | **Clean tree** (no changes, Checkpoint holds accumulated work) | Checkpoint itself is deliverable. Draft conventional commit message from Checkpoint diff (`git diff main..HEAD`), show, amend: `git commit --amend -m "<drafted message>"`. "Finalize in place" path — user called `/commit` to give Checkpoint real name. |
    
    **Case B — `Checkpoint` exists at HEAD~1..HEAD~5 but not HEAD (stranded)**: warn user. Means previous session made real work inside Checkpoint then landed other commits on top without finalizing. Offer:
    
    | Option | Effect |
    |---|---|
    | **Commit on top, leave stranded** (default in working-phase) | Normal commit. Stranded Checkpoint handled by `/finalize` before landing |
    | **Hand off to `/finalize` now** | Stop, tell user run `/finalize` for full rebase plan — safer than rewording one commit in isolation |
    | **Skip for now** | Ignore, continue |
    
    **Case C — no Checkpoint in window**: proceed.
    
    ### 3. Commit strategy
    
    On worktree branch, prefer one of:
    
    1. **Amend HEAD** when HEAD is fresh local commit you authored (not yet touching `main`'s reach) **and** new WIP clearly continuation of same concern. Ask first — amending destructive to commit hashes.
    2. **New commit on top** when HEAD already represents distinct concern.
    3. **Start Checkpoint** (`git commit -m "Checkpoint"`) when user says "save progress" or WIP not yet coherent enough to name.
    
    On non-worktree branch: never auto-amend. Always create new commit unless `/commit --amend` passed.
    
    On `main`: stop. Tell user create feature branch first.
    
    ### 4. Draft the commit message
    
    Follow **Conventional Commits v1.0.0**. See [`commit_reference.md`](./commit_reference.md) for full cheat sheet and [workflow-git.md](../../rules/workflow-git.md) for quick rules. Key points for working phase:
    
    - `chore:` for AI/tooling files (`.claude/`, `AGENTS.md`, `CLAUDE.md`, skills, rules, hooks, taskfiles) — keeps out of changelog
    - Imperative mood, lowercase description, no trailing period, subject ≤72 chars
    - Body explains **why**, not what, when non-obvious
    - Breaking: `!` before colon **and** `BREAKING CHANGE:` footer
    - **Never** `Co-Authored-By` (Grimoire convention)
    
    **Working-phase bundles legitimate.** If staged diff covers multiple concerns, `chore(claude): bundle <what>` style subject with body honestly listing clusters acceptable. Flag at body end that it will split or reword during `/finalize`.
    
    Show drafted message to user for approval before committing.
    
    ### 5. PR-branch prompt (first time per branch only)
    
    Skip entirely if **any** true:
    
    - `git config --get branch.<current>.grim-skip-pr-prompt` returns `true`
    - Open PR already exists for current branch
    - Current branch is fixed worktree branch (`goat`, `evelynn`, `sion`, `soraka`) — record skip, move on
    - Current branch is `main` — stop, tell user create feature branch first
    
    Otherwise, `AskUserQuestion`:
    
    1. **Create feature branch + PR** — derive name from commit subject (e.g. `feat/relative-symlinks`), branch from HEAD, commit there, `gh pr create` with title from subject and body summary
    2. **Stay on current branch** — commit here. Record: `git config branch.<current>.grim-skip-pr-prompt true`. Never ask again unless `/commit --pr`
    3. **Cancel** — abort
    
    ### 6. Stage and commit
    
    - Stage files **by name**, never `git add -A` / `.`. Prevents accidentally-committed secrets **and** bug where pre-staged files from previous session get swept into commit whose message doesn't describe them.
    - Warn before staging anything matching `.env*`, `*credentials*`, `*.pem`, `*.key`, or `token` patterns; require explicit confirmation.
    - **`--amend` must fold dirty tree into HEAD.** When `/commit --amend` invoked and working tree has uncommitted changes, those changes **must** be staged and included in amend — `--amend` with nothing staged silently becomes message-only amend that drops user's active work. Always `git add <files>` before `git commit --amend`, even when user only asked to "amend". After amend, run `git show --stat HEAD` and confirm expected files appear in diff stat before reporting success.
    - Pre-commit hook (`pre_commit_verification.py`) blocks commits without fresh `task verify`. When blocks, run `task verify` (not `--no-verify`), then mark state in separate `Bash` call (combining with commit in one `&&` chain does not satisfy hook):
      ```sh
      echo $(date +%s) > .claude/hooks/.state/commit-verified
      ```
      Then retry. **On retry, re-run `git add` too** — blocked Bash invocation ran nothing, not even part before `&&`, so staging gone if chained.
    - Commit with HEREDOC:
    
      ```sh
      git commit -m "$(cat <<'EOF'
      <type>[scope]: <description>
    
      <optional body explaining why>
      EOF
      )"
      ```
    
    - **Never** `--no-verify`, `--no-gpg-sign`, or any hook-skipping flags. If hook fails, fix root cause and create **new** commit (not `--amend` — previous commit stands).
    - **Never push.** Human decides when to push.
    
    ### 7. Bump plan Status `Last update`
    
    After successful commit, if `.claude/state/current_plan.md` exists and references a plan with a `## Status` block:
    
    - Bump `Last update:` line in the Status block to today's date with the new HEAD sha:
      `- **Last update:** YYYY-MM-DD (after <sha-short>: <subject>)`
    - Do NOT advance `Active phase:` — phase advancement is the plan author's decision (next phase entry in `/hex-execute`), not an automatic side-effect of commits.
    - Skip silently when no `current_plan.md`, no plan match, no Status block.
    
    This keeps `/next`'s staleness check (plan-mtime-vs-`Last update`) accurate without surprising the user.
    
    ### 8. Report
    
    One or two sentences: commit hash, subject, whether stranded-Checkpoint case handled, whether PR opened, whether Status `Last update` was bumped. Nothing else.
    
    ## References
    
    - [workflow-git.md](../../rules/workflow-git.md) — shared branch/commit hygiene: branching model, two-phase model, Checkpoint convention, land-ready definition
    - [`commit_reference.md`](./commit_reference.md) — Conventional Commits v1.0.0 cheat sheet
    - `/finalize` skill (`../finalize/SKILL.md`) — rebasing-phase sibling for cleaning `main..HEAD` before landing
    - AGENTS.md — worktree layout, "Landing a feature" section

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.