# Graysurf Agent Kit Semantic Commit Autostage

> Semantic Commit (Autostage)

- Skill: `tomevault-io/graysurf-agent-kit-semantic-commit-autostage` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/graysurf-agent-kit-semantic-commit-autostage`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/graysurf-agent-kit-semantic-commit-autostage/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/graysurf-agent-kit-semantic-commit-autostage

---


# Semantic Commit (Autostage)

## Contract

Prereqs:

- Run inside a git work tree.
- `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:

- Unstaged changes in the working tree (this skill stages them via `git add`).
- Prepared commit message via `--message`, `--message-file`, or stdin (`--automation` disables stdin fallback).
- Optional target repository via `--repo <path>`.

Outputs:

- Staged changes via `git add` (`-A` or `-u`).
- `semantic-commit staged-context`: staged diff context for message generation.
- `semantic-commit commit`: validation result and commit summary (unless disabled).
- Optional recovery file from `--message-out <path>`.

Exit codes:

- `0`: success (including validate-only and dry-run checks).
- `1`: usage/operational failure (`git add`/git commit/hook/conflict/repo issues).
- `2`: no changes to stage/commit.
- `3`: commit message missing/empty.
- `4`: commit message validation failed.
- `5`: required dependency missing (for example, `git`).

Failure modes:

- Not in a git repo.
- Dirty tree includes unrelated work: `git add -A` may stage unintended files.
- `git add` failure (pathspec/permission/submodule state).
- No staged changes after autostage (`exit 2`).
- Automation mode without explicit message source (`exit 3`).
- Invalid message format (`exit 4`).
- `git commit` failure (`exit 1`).

## Setup

- Use this skill only when full autostage is intended and safe.
- If user expects review-first partial staging, switch to `semantic-commit` (non-autostage).

## Commands (only entrypoints)

- Autostage all changes: `git add -A`
- Autostage tracked-only changes: `git add -u`
- 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: `--automation`, `--validate-only`, `--dry-run`, `--message-out`, `--summary`, `--no-summary`, `--repo`, `--no-progress`,
    `--quiet`

## Workflow

Rules:

- Use `git add -A` by default; use `git add -u` only when untracked files must stay uncommitted.
- Generate the message from `semantic-commit staged-context` output only.
- For non-interactive reliability, prefer `--automation` with `--message` or `--message-file`.

Recommended flow:

1. Choose stage mode (`git add -A` or `git add -u`) and run it.
2. Run `semantic-commit staged-context --format bundle`.
3. Draft semantic message from staged context.
4. Run `semantic-commit commit --validate-only ...`.
5. Optionally run `semantic-commit commit --dry-run ...`.
6. Run `semantic-commit commit ...` for the real commit.
7. Report command, exit code, stdout, 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: blank line after header, then only `-` bullets with uppercase first letter.
- Body lines must be `<= 100` characters.

## Error handling matrix

- `exit 2`: autostage produced no commitable delta.
- `exit 3`: missing/empty message (common with `--automation` + no `--message`).
- `exit 4`: semantic format validation failed.
- `exit 1`: operational failure (`git add`/`git commit`/hook conflict); report stderr verbatim.
- `git-scope` warning only: fallback to `git show` is expected behavior.

## Output and clarification rules

- On failure: include the failing command, exit code, and key stderr.
- On success: include commit summary stdout in a code block.
- If staged context and user intent conflict (mixed unrelated changes), stop and ask whether to proceed with broad autostage.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/graysurf) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->