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.