---
name: semantic-commit-autostage
description:
  Autostage the full in-scope working tree delta and commit it using Semantic Commit format when the active agent owns the complete change
  set and the user should not manually stage files.
---

# 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 that are all intended for this commit (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.
- Use it when the whole dirty tree is one work intent, or when all tracked changes are in scope and `git add -u` is explicitly chosen.
- Do not use it for agent-selected partial commits; stage the selected subset first and 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`, `--auto-fix`, `--message-out`, `--summary`, `--no-summary`, `--repo`,
    `--no-progress`, `--quiet`
  - `--auto-fix` (opt-in) normalizes machine-fixable issues before validation: wraps body lines at 100 chars (whitespace break preferred,
    codepoint hard-break for CJK / unbreakable runs), lowercases the header type / `(scope)`, uppercases the first char of `-` bullets,
    inserts a missing blank line between header and body, and drops empty lines inside the body. Over-length headers and structural header
    errors still exit `4`.

## Workflow

Rules:

- Use `git add -A` by default; use `git add -u` only when untracked files must stay uncommitted.
- Do not use this skill to choose a subset of paths from a mixed dirty tree.
- 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 switch to selective staging plus `semantic-commit`, or ask
  whether to proceed with broad autostage.
