# AI Commit

> Runs the governed commit pipeline: auto-branches from protected, stages selectively, formats and lints, scans for secrets, gates docs, composes a conventional message, pushes. Trigger for 'commit my changes', 'save my work', 'push this to remote', 'stage these files', 'ship it'. Not for opening a PR; use /ai-pr instead. Not for branch hygiene; use /ai-branch-cleanup instead.

- Skill: `arcasilesgroup/ai-commit` (Agent Skill)
- Install (CLI): `npx skillmds@latest add arcasilesgroup/ai-commit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/arcasilesgroup/ai-commit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: arcasilesgroup (https://skillmd.com/u/arcasilesgroup)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/arcasilesgroup/ai-commit

---


# Commit Workflow

Runs the governed commit pipeline -- stage, format, lint, secret-detect, compose a conventional message, push -- honoring CLAUDE.md Don't rules (binding). Use `/ai-pr` when the goal is a pull request; see Quick Reference for invocation forms.

## Process

### 0. Auto-branch from protected

If current branch is `main`/`master`: infer type (`feat/`, `fix/`, `chore/`, `docs/`, `refactor/`), generate slug deterministically with `python3 .ai-engineering/scripts/branch_slug.py --prefix <type>` (reads spec.md frontmatter), then `git checkout -b <output>`, report new branch.

### 1. Work item context (optional)

If `.ai-engineering/specs/spec.md` frontmatter has `refs`: include work item refs as commit body trailers (`Refs: AB#101, AB#102, #45`). Only include `close_on_pr` items — never features.

### 2. Instinct consolidation

If `.ai-engineering/observations/observations.yml` exists, run `/ai-session-watch --review` to consolidate session observations before committing.

### 3. Stage changes

`git add <file1> <file2>` selectively. Use `git add -A` only when explicitly requested. Exclude generated files, secrets, large binaries.

### 4. Run gate orchestrator

```
ai-eng gate run --cache-aware --json --mode=local
```

The orchestrator runs the 2-wave collector (Wave 1 fixers serial -> Wave 2 checkers parallel) with cache-aware lookup, emitting `.ai-engineering/state/gate-findings.json` (schema v1) covering every check. After Wave 1 fixers rewrite files, the orchestrator re-stages the safe `S_pre & M_post` intersection (spec-105 D-105-09); pass `--no-auto-stage` to disable, or set `gates.pre_commit.auto_stage: false` in the manifest.

### 5. Handle gate result

- **Exit 0** -- all checks PASS or auto-fixed. Continue to Commit.
- **Exit non-zero** -- parse `gate-findings.json`, report failing checks per `rule_id` + `severity`, **STOP**. Fix root cause, re-stage, re-run `/ai-commit`. Override only when remediation is tracked elsewhere and the publish window forces it: `ai-eng risk accept-all .ai-engineering/state/gate-findings.json --justification "<reason>" --spec <spec-id> --follow-up "<plan>"` writes one DEC entry per finding with severity-default TTL (see `.ai-engineering/reference/risk-acceptance-flow.md`).

### 6. Confirm commit readiness

The documentation gate inside the orchestrator is mandatory.

See `.ai-engineering/reference/gate-policy.md` for the local fast-slice + CI authoritative split.

### 7. Commit

Compose message via `python3 .ai-engineering/scripts/commit_compose.py --type <type> [--task X.Y] --desc "<desc>"`. **`--desc` is mandatory (spec-139 M8 D-139-06)** — derive it from the current plan.md task title (`grep -m1 '^- \[ \] ' .ai-engineering/specs/plan.md`) or from staged-files / operator hint on off-chain WIP commits. The legacy `<DESC>` placeholder fallback is deprecated. Doc-gate via `python3 .ai-engineering/scripts/doc_gate.py --changed-paths "<staged>"` (exit 1 → block; CHANGELOG.md or README.md must accompany changes under `src/`, `tools/`, `.claude/skills/`).

- **With active spec**: `feat(spec-NNN): Task X.Y -- <desc>`, `fix(spec-NNN): <desc>`, `chore(spec-NNN): <desc>`.
- **Without spec**: `type(scope): description` (conventional commits, imperative mood). Valid types: `feat`, `fix`, `perf`, `refactor`, `style`, `docs`, `test`, `build`, `ci`, `chore`, `revert`.
- `--force` skips preview; otherwise preview and confirm.

### 8. Push

`git push origin <current-branch>`. Block if on `main`/`master`.

### `/commit --only`

Execute the full pipeline through Commit. Skip Push.


## Drift recovery

Exit 78 = stack drift. Run `ai-eng doctor --fix` in shell, retry. Never `--no-verify`.

## Examples

User: "commit only the spec files and don't push yet" → `/ai-commit --only .ai-engineering/specs/` stages only the named paths, runs the full pipeline (auto-branch, ruff format + lint, gitleaks scan, doc gate, conventional message) through commit, and stops before push.

## Quick Reference

| Goal | Command |
|------|---------|
| Auto-stage, format, lint, scan, commit, push | `/ai-commit` |
| Stage only named files | `/ai-commit --only path/to/file.py` |
| Provide a message hint | `/ai-commit "fix(auth): ..."` |
| Skip preview | `/ai-commit --force` |
| Stop before push | `/ai-commit --only ...` |

## Integration

Called by: user directly (off-chain, WIP-only flows). `/ai-pr` carries the same Steps 0-6 inline (single-responsibility per spec-132 T-3) — it does NOT delegate back here. Calls: `git`, `ruff`, `gitleaks`, `ai-eng spec verify --fix`. Reads: `manifest.yml`, `CLAUDE.md`. See also: `/ai-pr`, `/ai-branch-cleanup`, `/ai-resolve-conflicts`.

$ARGUMENTS