semantic-commit-autostage

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.