# Commit

> Smart commit, push, and npm publish with auto-splitting across domains. Creates atomic commits. Use when asked to "commit", "push changes", "publish", "save my work", or after completing implementation work. Automatically groups changes into logical commits.

- Skill: `howells/commit` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add howells/commit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/howells/commit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: howells (https://skillmd.com/u/howells)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/howells/commit

---


<arc_runtime>
Requires the full Arc bundle. Arc-owned paths (`agents/`, `references/`, `disciplines/`, `templates/`, `scripts/`, `rules/`, `skills/`) resolve from the plugin root — the directory containing `agents/` and `skills/`. Everything else is the user's repository.
</arc_runtime>

<rules_context>
**Load before committing:**

- `rules/git.md` — commit-message, husky, and lint-staged conventions this skill must respect. Its Hooks section describes repo setup (audit/launch territory), not a commit-time obligation — an unsatisfied MUST there is a note, not a task.
- `references/diff-review-checklist.md` — apply during the pre-commit review step (step 1).

</rules_context>

# Commit Changes

Commit, push, and publish changes, intelligently splitting into separate commits when changes span multiple domains.

Usage:

- `/arc:commit` - Auto-analyze and commit (may create multiple commits)
- `/arc:commit push` - Commit, push, then publish changed npm packages if present
- `/arc:commit publish` - Alias for the push-and-publish path

On the push/publish path, `/arc:commit` publishes a package whose version is already committed and not yet on the registry. `/arc:release` owns bumping versions, changelogs, and coordinated multi-package releases. Route version bumps there instead of doing them here.

The canonical order across both skills is **commit → push → publish → tag**.

Read the user's invocation: no argument means commit only; "push" or "publish" both mean the push-and-publish path.

## Inspect Current Git State

Run these commands first and read the output before deciding on a commit strategy:

```bash
git status --porcelain 2>/dev/null || echo "(no changes)"
git diff --stat 2>/dev/null | head -20 || echo "(no diff)"
git log --oneline -5 2>/dev/null || echo "(no commits)"   # style reference
```

`git status --porcelain` is the authoritative file list (the stat is a preview, and it truncates); read the contents of untracked files before judging them stray.

If there are no changes, tell the user and stop.

## Instructions

If no user response is available at any decision point, take the conservative path — exclude rather than commit, stop rather than push or publish — and report what needs a human.

### 1. Analyze Changes

Review the git state above. If you need more detail on what changed, inspect the working tree — e.g. `git diff` for unstaged changes, `git diff --staged` for staged changes, or `git diff <path>` to focus on a file. Apply `references/diff-review-checklist.md` as you read the diff so substantive defects (race conditions, trust-boundary gaps, data-safety and side-effect mistakes, stale references, test gaps, dead code, performance regressions) are caught before they land in a commit. Alongside it, scan the diff yourself for debug logs, secrets or credentials, and stray files that should not be committed. A hit blocks those lines from landing: exclude the file (or the hunk, via `git add -p`) from every commit, leave the working-tree content untouched, and report each hit. Never delete user work to make a commit clean. Never commit a suspected secret; if one may already be in history, say so — committed secrets need rotation, not just removal.

### 2. Determine Commit Strategy

**Single commit** if:

- All changes are in the same domain/area, OR
- Changes are tightly coupled (e.g., feature + its tests)

**Multiple commits** if changes span multiple unrelated domains:

- Different packages (e.g., `packages/ui`, `packages/api`)
- Different apps (e.g., `apps/web`, `apps/admin`)
- Config vs source changes
- Unrelated features or fixes

### 3. Group Files by Domain

Common groupings:

- `packages/<name>/**` - Package-specific changes
- `apps/<name>/**` - App-specific changes
- `app/**` - Route or feature changes, grouped by route/feature
- `components/**` - Shared UI changes
- `lib/**` / `utils/**` - Shared logic and helpers
- Root config files (`.eslintrc`, `turbo.json`, etc.) - Config
- `*.stories.tsx` with their component - Same commit as component
- `*.test.ts` with their source - Same commit as source

In a flat repo, group by top-level directory unless changes are coupled across them.

### 4. Create Commits

For each logical group:

1. Stage only files for that group, including untracked files that belong to the group:

   ```bash
   git add [files...]
   ```

2. Create commit with conventional message format:
   ```bash
   git commit -m "$(cat <<'EOF'
   type(scope): description
   EOF
   )"
   ```

**Commit types:**

- `feat` - New feature
- `fix` - Bug fix
- `refactor` - Code refactoring
- `chore` - Maintenance, deps, config
- `docs` - Documentation
- `test` - Tests
- `style` - Formatting, no code change
- `perf` - Performance improvement
- `ci` - CI/CD changes

**Commit message rules:**

- Use imperative mood: "add" not "added", "fix" not "fixed"
- First line under 72 characters
- Each commit should be atomic (single purpose)
- If you need "and" in the message, consider splitting the commit

After each commit, re-read `HEAD` before reporting hashes — a hook may have amended the commit.

**Repo version mechanics:** if the repo ships a version-bump script (often paired with a manifest such as `.version-bump.json`), use that script rather than editing `version` fields directly.

### 5. Handle Pre-commit Hook Failures

If TypeScript or lint errors block the commit:

Fix the root cause. A hook failure is information about the code, so anything that silences it
rather than resolving it — `--no-verify` on work you are landing (the one exception — a local WIP
commit you will amend before pushing — is `rules/git.md`'s, and never applies to this skill's
output), `as unknown as`/`as any`, `@ts-ignore`, `@ts-expect-error`, eslint-disable comments,
empty catch blocks — leaves the defect in place and the commit dishonest.

If the root cause genuinely can't be fixed here, stop and say so rather than suppressing it.

**Fixing Process:**

1. Read the error output carefully
2. Identify the exact files and line numbers with issues
3. For TypeScript errors:
   - Read the file and understand the type error
   - Fix the types properly by adding correct type annotations
   - If a type is unclear, use `unknown` and narrow it with type guards
   - Update interfaces/types as needed
4. For lint errors:
   - Read the file and understand the lint rule violation
   - Fix the code to comply with the rule properly
   - Refactor if needed to follow best practices
5. Stage the fixes with the relevant commit
6. Retry the commit
7. Repeat until all errors are resolved

### 6. Push Changes (only if `push` or `publish` argument provided)

**Skip this step** unless the user asked to "push" or "publish".

If pushing:

```bash
git push
```

If the branch has no upstream:

```bash
git push -u origin $(git branch --show-current)
```

If push fails (e.g., diverged history), report the issue - do NOT force push unless explicitly authorized.

### 7. Publish npm Packages (only if `push` or `publish` argument provided)

**Skip this step** unless the user asked to "push" or "publish".

Publish only after commits and push have succeeded — the canonical order is commit → push → publish → tag.

Detect the repo's package manager (`pnpm`, `npm`, `yarn`, `bun`) from its lockfile or `packageManager` field first, and refer to it as `<pm>` in the commands below.

**Detect candidate packages:**

- Look for changed `package.json` files and changed files under directories containing a `package.json`.
- Ignore generated directories such as `node_modules`, `dist`, `build`, `.next`, `.turbo`, and coverage output.
- A package is publishable only if `package.json` has a `name`, a `version`, and does not have `"private": true`.
- Prefer packages with a `publishConfig`, `files`, `bin`, `exports`, or an explicit package-level `prepublishOnly` / `prepare` / `build` script. If package intent is unclear, ask before publishing.

**Pre-publish checks for each candidate:**

1. Read the package's `package.json`.
2. Confirm the package has an npm package name and version.
3. Check whether that exact version is already published:

   ```bash
   npm view <package-name>@<version> version
   ```

   - If the version exists, skip publishing and report it.
   - If npm returns 404/not found, continue.
   - If npm auth/network fails, stop and report the blocker.

4. Run package-local verification when scripts exist, using `<pm>` consistently:
   - `<pm> test` if a `test` script exists
   - `<pm> build` if a `build` script exists
   - `<pm> typecheck` if a `typecheck` script exists
5. Publish from the package directory:
   ```bash
   npm publish
   ```
   Use `npm publish --access public` for scoped public packages when `publishConfig.access` is `public` or the existing package is public. Publishing itself uses `npm publish` regardless of the install-time package manager; only the verification scripts above run through `<pm>`.

**Publishing rules:**

- NEVER publish a private package.
- NEVER publish before pushing the commit containing the package version.
- NEVER bump a package version unless the user explicitly asked for a version bump.
- NEVER publish if the working tree has uncommitted files that belong to that package. When the uncommitted files are step 1's own exclusions (a quarantined secret or debug line), say that explicitly — the block is the scan working, not an oversight.
- NEVER use `--force` or delete registry versions.
- If multiple changed packages exist, publish each confirmed publishable package once.

### 8. Report Results

Tell the user:

- How many commits were created
- Summary of each commit (hash, message)
- Push status (if pushed), or remind them to push when ready
- Publish status for each package (if publish was requested): published, skipped, or blocked

## Failure Scenarios

If you cannot fix an error properly:

- Explain why the error exists
- Describe what the proper fix would require (e.g., architectural changes, missing types, etc.)
- Ask for guidance
- Do NOT commit with workarounds