Checkpoint

Overview

Create a safe, repeatable checkpoint in any git repo. This workflow is swarm-safe: it acquires a lock, validates, stages selected files, commits with strict message rules, and optionally pushes.

Principles

Automate what is unambiguous; ask when it is not.
Never switch branches or rewrite history unless explicitly instructed.
Prefer explicit file selection; avoid "stage everything" by default.
Abort if the working tree changes mid-run.

Workflow (Swarm-Safe)

1) Acquire Lock

Use a repo-local lock so multiple agents do not collide.

Lock path: .git/.checkpoint.lock/
Create the lock with an atomic mkdir. If it exists, stop and report.
Write owner.txt inside the lock with: user, host, pid, time, branch, worktree.
Only break the lock if the user explicitly says "force".

If the lock is present, show owner.txt and stop. Do not proceed unless told to force.

2) Snapshot

Record git status -sb and a diff summary.
If on master, warn and ask for confirmation before continuing.
If the working tree changes after this point, abort and report.

3) Validate

Run the repo's standard checks, but do not guess commands.

Discover validation instructions from repo docs/config (README, CONTRIBUTING, build scripts, CI notes).
If the repo does not specify validation steps, ask the user to choose or skip.
If validation fails, fix and re-run before proceeding.

4) Stage

Show the diff and ask which files to include.
Stage only the files the user confirms (explicit paths only).
Re-check git status and the diff. If anything changed unexpectedly, abort.

5) Commit

Ask for a commit message and enforce these rules (verbatim):

Subject <=42 chars (room for (#NNNN) suffix -> 50 char limit)
Imperative mood ("Add feature" not "Added feature")
Capitalize subject, no period at end
Blank line between subject and body
Body: explain what and why, wrap at 72 chars
Use backticks around filenames, paths, and code_symbols

Use the heredoc pattern:

git commit -m "$(cat <<'EOF'
<Subject line - imperative, <=42 chars>

<Body - what and why, wrapped at 72 chars>
Use `backticks` around files, paths, symbols.
EOF
)"

If commit fails:

No staged changes -> return to Stage
Hook failure -> fix, re-stage, create a NEW commit (do not amend)
Other error -> report and stop

6) Push (Optional)

Ask whether to push unless the user explicitly requested it.
If pushing: fetch first. If remote advanced or diverged, stop and ask.
Push only the current branch.

7) Confirm and Release

Summarize what happened (files staged, commit SHA, push status).
Remove the lock directory only after completion.

Notes

No PR or Graphite steps in this skill.
The lock directory is created by this workflow to prevent collisions; it is safe to remove only when no checkpoint is running.

checkpoint

Safety Notice

Copy this and send it to your AI assistant to learn