Semantic Commit

Contract

Prereqs:

• •Run inside a git work tree (or pass --repo <path> to target one explicitly).
• •git available on PATH.
• •semantic-commit available on PATH (install via brew install nils-cli).
• •git-scope is optional; default summary mode falls back to git show when unavailable.

Inputs:

• •Staged changes (git add ...) for semantic-commit staged-context.
• •Prepared commit message via stdin (preferred), --message, or --message-file for semantic-commit commit.
• •Optional target repository via --repo <path>.

Outputs:

• •semantic-commit staged-context: prints staged change context in bundle|json|patch format.
• •semantic-commit commit: validates message, optionally commits staged changes, and prints commit summary unless disabled.
• •Optional recovery file from --message-out <path>.

Exit codes:

• •0: success (including --validate-only, --dry-run, and help output).
• •1: usage or operational failure (invalid args, git command failure, hooks/conflicts, bad repo path).
• •2: no staged changes for commands that require staged input.
• •3: commit message missing/empty.
• •4: commit message validation failed.
• •5: required dependency missing (for example, git).

Failure modes:

• •Not in a git repo and no valid --repo supplied.
• •No staged changes (exit 2).
• •No message provided in automation mode (exit 3).
• •Message format invalid (exit 4).
• •git commit failure (hooks/conflicts/signing/repo state) (exit 1).
• •Summary helper unavailable (git-scope missing): warning emitted, fallback to git show.

Setup

• •Run inside the target git repo, or use --repo <path> to avoid shell cwd switching.
• •Use only the entrypoints below; they are the stable interface for agents.

Commands (only entrypoints)

• •Get staged context:
  • •semantic-commit staged-context [--format <bundle|json|patch>] [--json] [--repo <path>]
• •Commit / validate prepared message:
  • •semantic-commit commit [--message <text>|--message-file <path>] [options]
  • •Useful options: --message-out, --summary <git-scope|git-show|none>, --no-summary, --validate-only, --dry-run, --automation, --repo, --no-progress, --quiet
• •Do not call internal helpers directly; treat these commands as the only contract surface.

Workflow

Rules:

• •Never run git add in this skill; commit only what the user has already staged.
• •Build message intent from semantic-commit staged-context output only.
• •Prefer explicit --repo <path> when operating from another working directory.

Recommended flow:

1. •Run semantic-commit staged-context --format bundle (or --json if your parser expects JSON only).
2. •Draft the semantic message (type(scope): subject + optional bullet body).
3. •Run semantic-commit commit --validate-only ... before committing to catch formatting errors early.
4. •Optionally run semantic-commit commit --dry-run ... for staged/message sanity checks without creating a commit.
5. •Run semantic-commit commit ... to finalize.
6. •Capture and report exit_code, stdout, and stderr.

Follow Semantic Commit format

Use one of:

• •type(scope): subject
• •type: subject

Rules:

• •Type must be lowercase.
• •Header length must be <= 100 characters.
• •If body exists: line 2 must be blank, and every body line must start with - followed by an uppercase letter.
• •Each body line must be <= 100 characters.

Error handling matrix

• •exit 2 (no staged changes): stop and ask for staging.
• •exit 3 (message missing/empty): provide/repair --message or --message-file.
• •exit 4 (validation failed): fix header/body format first; do not commit.
• •exit 1 from commit: treat as operational failure and report stderr verbatim.
• •git-scope warning only: not fatal unless summary is explicitly required to be git-scope.

Example

semantic-commit staged-context --format json

semantic-commit commit \
  --message-file /tmp/commit-msg.txt \
  --validate-only

semantic-commit commit \
  --message-file /tmp/commit-msg.txt \
  --summary git-show

Output and clarification rules

• •On failure: include command, exit code, and stderr; do not claim success.
• •On success: include command output (commit summary) in a code block.
• •If staged context cannot disambiguate type/scope/subject, ask one concise clarification question before committing.