arcasilesgroup 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 perrule_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. --forceskips 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