Qcommit

---
name: Qcommit
user_invocable: true
description: Use when the user says 'commit', 'push', or 'save changes'. Creates human-written commits with no Co-Authored-By, AI-style language, or emoji.
invocation_trigger: When changes are ready to be staged and committed to git.
recommendedModel: haiku
---


# Qcommit — Natural Commits

## Role
Creates natural git commits that show no trace of AI authorship, as if written directly by a human.
Actual commit work is delegated to the `Ecommit-executor` sub-agent.

## Client Adapter Compatibility

- **Claude**: delegate commit execution to `Ecommit-executor` via Agent tool.
- **Codex native**: explicitly invoke the native Codex `Ecommit-executor` agent when available.
- **Codex client adapter**: if native subagent invocation is unavailable, preserve the role contract with role-separated inline execution. The inline path must still obey the bypass-flag sequence in `agents/Ecommit-executor.md`.
- **Command rendering**: user-facing follow-up commands use the active client's prefix (`/Q...` for Claude, `$Q...` for Codex).

## Examples

```
User: "Create a commit"
→ Qcommit: stages all changes, writes natural commit message, commits

User: "commit and push"
→ Qcommit: commits + git push

User: "Save and push these changes"
→ Qcommit: commits + git push

User: "Save this"
→ Qcommit: stages + commits current changes

User: "commit this with a good message"
→ Qcommit: analyzes diff, writes conventional commit message, commits
```

## Prohibited Items (Absolute Rules)
- **Never add** `Co-Authored-By` lines
- No AI-related phrases such as `Generated by`, `Created by AI`, `Claude`, `GPT`
- No emoji usage
- No AI writing style such as "systematically", "comprehensively", "efficiently"

## Commit Message Rules

### Subject (first line)
- Starts lowercase, 70 characters or fewer
- Conventional Commits format: `type: description`
- type: `feat`, `fix`, `refactor`, `chore`, `docs`, `test`, `style`, `perf`
- Concise and specific — only "what was done"

### Body (optional)
- Separated by a blank line
- Briefly explain "why" the change was made
- Omit if unnecessary

### Examples
```
feat: add user authentication API

Implement login/signup endpoints.
Issue JWT-based token on authentication.
```

```
fix: correct order amount calculation
```

```
refactor: extract DB connection pool configuration
```

## Execution Procedure (Mandatory Delegation)

**ABSOLUTE RULE:** Do not run raw commit operations directly when the active client has an available commit executor agent.

- Claude: ALL git operations MUST be delegated to the `Ecommit-executor` agent via the Agent tool.
- Codex native: use the native `Ecommit-executor` agent when available.
- Codex inline fallback: if no native subagent invocation is available, run the Ecommit-executor protocol with role-separated inline execution and mark the fallback explicitly.

### Step 1: Delegate to Ecommit-executor
Call the `Ecommit-executor` agent through the agent adapter with the following information:
- Project path
- Whether the user requested push
- Any specific commit message hints from context

The `Ecommit-executor` agent handles everything: status check, diff analysis, commit message writing, staging, committing, and optionally pushing.

On Codex role-separated inline fallback, read `agents/Ecommit-executor.md` and execute the same
steps in the current session. Prefer the hook-owned Qcommit skill-entry capability;
only write the standalone skill-bypass flag when the installed hook lacks that
capability and blocks the commit.

### Step 2: Report Results
After the agent completes, report the commit hash and changed files to the user.

## Will
- Analyze changes and write a natural commit message
- Match the project's commit style
- Prevent staging of sensitive files

## Will Not
- Add Co-Authored-By
- Include AI-related phrases or traces
- Run git push (unless explicitly requested by the user)
- Create an empty commit when there are no changes

## Checkpoint mode (opt-in WIP commits)

When `checkpoint_mode` is enabled (opt-in — off by default), long tasks may create
lightweight **WIP checkpoint commits** so work is recoverable across sessions without
polluting final history:

- **Create**: `Qcommit --checkpoint` (or checkpoint_mode active) makes a commit with a
  `wip: <task/uuid> <short note>` subject. WIP checkpoints skip the natural-message
  polish and are explicitly marked so they are easy to find and squash.
- **Resume parse**: `Qresume` recognizes trailing `wip:` checkpoint commits on the
  branch and surfaces them as recoverable in-progress state (which task, how far).
- **Squash on finish**: before the real commit, `Qcommit --squash-wip` (or the normal
  flow when it detects trailing `wip:` commits) squashes all consecutive trailing
  `wip:` checkpoints into a single natural, AI-trace-free commit. Final history
  contains no `wip:` entries.

Checkpoint mode never pushes and never squashes across a non-WIP commit boundary.