Speckit Checkpoint Commit
Create exactly one commit capturing the artifacts produced by the speckit phase
that just completed (specify, plan, critique, tasks, an implement chunk, review
fixes, or the final report). The opsmill orchestrators invoke this skill after
every phase so each phase is independently reviewable and revertable.
Guard rails — check these first
- Confirm you are inside a git work tree:
git rev-parse --is-inside-work-tree.
If not, warn and skip — never initialize a repository from here.
- Reject detached HEAD: if
git symbolic-ref -q HEAD fails, abort without
committing and surface the problem — a checkpoint on a detached HEAD is
unreachable the moment anything else is checked out.
- Abort during in-progress git operations: if a merge, rebase, cherry-pick,
revert, or bisect is in progress —
git status reports it, or any of
.git/MERGE_HEAD, .git/rebase-merge, .git/rebase-apply,
.git/CHERRY_PICK_HEAD, .git/REVERT_HEAD, .git/BISECT_LOG exist —
abort without committing and surface it: a commit here finalizes or
corrupts that operation.
- Hard-deny protected branches. If
git rev-parse --abbrev-ref HEAD returns
main, master, develop, dev, stable, trunk, anything under
release/ or releases/, anything matching release-*, or the remote's
default branch (git symbolic-ref refs/remotes/origin/HEAD, when set),
abort without committing and surface the problem to the
caller — the pipeline should have created a feature branch via the
before_specify hook before any phase ran.
- Soft-check the branch name. If it does not match one of the speckit
feature-branch patterns — sequential
^[0-9]{3,}- or timestamp
^[0-9]{8}-[0-9]{6}- — proceed, but flag the non-standard name
prominently in your report so the orchestrator log records it.
(Hard-blocking here would break legitimate runs on hand-named branches;
the hard guards above cover the dangerous cases.)
- Check the index before staging anything: run
git diff --cached --name-only. If it lists files that are not attributable to the phase
that just finished, abort without committing and without modifying the
index — never git reset, unstage, or otherwise touch pre-staged
entries; they are someone else's work in flight. Surface the offending
paths in your report. If the pre-staged entries are all phase-attributable
(e.g. a prior invocation staged but failed before committing), proceed and
note this in the report.
- Never push. Never amend. One new commit per invocation, nothing else.
What to stage
Stage the changes attributable to the phase that just finished:
- Preparation phases (specify / plan / critique / tasks): the feature
directory's contents. Resolve the feature directory with the canonical
resolver —
bash -c 'source .specify/scripts/bash/common.sh && get_feature_paths' — and read FEATURE_DIR from its output. If it exits
non-zero (no SPECIFY_FEATURE_DIRECTORY and no parseable
.specify/feature.json), abort without committing and without modifying
anything — never guess a directory. Also stage any files those phases
legitimately regenerate (e.g. agent context files).
- Implement chunks and review fixes: the source, test, and doc files the chunk
changed, plus its tasks.md checkbox updates.
Inspect git status --porcelain before staging, then stage explicit paths
only — name each file or directory you are committing (git add <path> ...).
Never use git add -A, git add ., or git add -u: the working tree may
carry changes the phase did not produce, and a checkpoint must never absorb
them. Stage paths exactly as git status --porcelain reports them — never
through a symlink alias (e.g. specs -> dev/specs), which git add
rejects.
If the status output lists changes that are clearly unrelated to the phase
(files the phase could not have touched), leave them unstaged and mention the
leftovers in your report.
If there is nothing to commit, say so and return — that is a success, not an error.
Commit message
- Subject: imperative "what changed", scoped to the phase, e.g.
spec: add specification for <feature>, plan: add implementation plan,
tasks: generate task breakdown, or the chunk's own summary for implement
chunks. Follow any commit conventions in the repository's AGENTS.md.
- Body: one or two lines of context at most (phase name, spec directory).
- Identify the agent per repository convention (e.g. a
Co-Authored-By: trailer).
Output
Report the created commit hash and subject (or the skip reason) back to the
caller so the orchestrator can include it in its phase log.
1---2name: speckit-checkpoint-commit-23description: Commit the artifacts produced by the speckit phase that just completed4---56# Speckit Checkpoint Commit78Create exactly one commit capturing the artifacts produced by the speckit phase9that just completed (specify, plan, critique, tasks, an implement chunk, review10fixes, or the final report). The opsmill orchestrators invoke this skill after11every phase so each phase is independently reviewable and revertable.1213## Guard rails — check these first14151. Confirm you are inside a git work tree: `git rev-parse --is-inside-work-tree`.16 If not, warn and skip — never initialize a repository from here.172. Reject detached HEAD: if `git symbolic-ref -q HEAD` fails, **abort without18 committing** and surface the problem — a checkpoint on a detached HEAD is19 unreachable the moment anything else is checked out.203. Abort during in-progress git operations: if a merge, rebase, cherry-pick,21 revert, or bisect is in progress — `git status` reports it, or any of22 `.git/MERGE_HEAD`, `.git/rebase-merge`, `.git/rebase-apply`,23 `.git/CHERRY_PICK_HEAD`, `.git/REVERT_HEAD`, `.git/BISECT_LOG` exist —24 **abort without committing** and surface it: a commit here finalizes or25 corrupts that operation.264. Hard-deny protected branches. If `git rev-parse --abbrev-ref HEAD` returns27 `main`, `master`, `develop`, `dev`, `stable`, `trunk`, anything under28 `release/` or `releases/`, anything matching `release-*`, or the remote's29 default branch (`git symbolic-ref refs/remotes/origin/HEAD`, when set),30 **abort without committing** and surface the problem to the31 caller — the pipeline should have created a feature branch via the32 `before_specify` hook before any phase ran.335. Soft-check the branch name. If it does not match one of the speckit34 feature-branch patterns — sequential `^[0-9]{3,}-` or timestamp35 `^[0-9]{8}-[0-9]{6}-` — proceed, but flag the non-standard name36 prominently in your report so the orchestrator log records it.37 (Hard-blocking here would break legitimate runs on hand-named branches;38 the hard guards above cover the dangerous cases.)396. Check the index before staging anything: run `git diff --cached40 --name-only`. If it lists files that are not attributable to the phase41 that just finished, **abort without committing and without modifying the42 index** — never `git reset`, unstage, or otherwise touch pre-staged43 entries; they are someone else's work in flight. Surface the offending44 paths in your report. If the pre-staged entries are all phase-attributable45 (e.g. a prior invocation staged but failed before committing), proceed and46 note this in the report.477. Never push. Never amend. One new commit per invocation, nothing else.4849## What to stage5051Stage the changes attributable to the phase that just finished:5253- Preparation phases (specify / plan / critique / tasks): the feature54 directory's contents. Resolve the feature directory with the canonical55 resolver — `bash -c 'source .specify/scripts/bash/common.sh &&56 get_feature_paths'` — and read `FEATURE_DIR` from its output. If it exits57 non-zero (no `SPECIFY_FEATURE_DIRECTORY` and no parseable58 `.specify/feature.json`), **abort without committing and without modifying59 anything** — never guess a directory. Also stage any files those phases60 legitimately regenerate (e.g. agent context files).61- Implement chunks and review fixes: the source, test, and doc files the chunk62 changed, plus its tasks.md checkbox updates.6364Inspect `git status --porcelain` before staging, then stage **explicit paths65only** — name each file or directory you are committing (`git add <path> ...`).66Never use `git add -A`, `git add .`, or `git add -u`: the working tree may67carry changes the phase did not produce, and a checkpoint must never absorb68them. Stage paths exactly as `git status --porcelain` reports them — never69through a symlink alias (e.g. `specs` -> `dev/specs`), which `git add`70rejects.7172If the status output lists changes that are clearly unrelated to the phase73(files the phase could not have touched), leave them unstaged and mention the74leftovers in your report.7576If there is nothing to commit, say so and return — that is a success, not an error.7778## Commit message7980- Subject: imperative "what changed", scoped to the phase, e.g.81 `spec: add specification for <feature>`, `plan: add implementation plan`,82 `tasks: generate task breakdown`, or the chunk's own summary for implement83 chunks. Follow any commit conventions in the repository's AGENTS.md.84- Body: one or two lines of context at most (phase name, spec directory).85- Identify the agent per repository convention (e.g. a `Co-Authored-By:` trailer).8687## Output8889Report the created commit hash and subject (or the skip reason) back to the90caller so the orchestrator can include it in its phase log.