Vibe Commit

Turn a commit from a raw diff into a reviewed, validated, readable unit of organizational memory.

Core Principles

• Write commit prose in the user's language; keep commit types, paths, commands,

code, IDs, and quotes unchanged.

• Keep required template headings, field labels, tables, commit types, and

status values exactly as shown for validator compatibility; localize placeholder prose and all human-readable explanatory content to the user's language or the source artifact's primary language.

• A commit should explain intent, change, and validation.
• Link commits to a feature spec, plan, test evidence, issue, task, CI run, or explicit user request when available.
• When work belongs to an OpenSpec change, record its change ID and current

artifact path in the available references. Do not move or archive the change.

• Review the actual diff before writing the message.
• Do not treat a spec, workflow, artifact, or docs review as a code/diff review.
• Treat vibe-review and validation as commit gates, not optional decoration.
• Keep commits scoped. Point out unrelated changes instead of bundling them silently.
• Never claim validation that was not run.
• Treat design-quality risk as part of pre-commit review when it affects safe

follow-up changes: 改动扩散, 规则重复, 理解成本, 边界不清, 空壳接口, or 绕路补丁.

• Do not commit secrets, private config, environment files, or personal data.
• Do not create a git commit when code review has blocking findings, validation

fails, sensitive files are present, or scope is mixed.

• Only create an actual git commit when the user explicitly asks for a commit.

Workflow

1. Inspect The Change

Before proposing or creating a commit:

1. Check git status --short.
2. Inspect staged and unstaged diffs for the intended files.
3. Identify related spec, issue, task, user request, plan, and test evidence.
4. Identify generated files, lockfiles, migrations, schema changes, and dist

outputs that must stay aligned.

1. Detect unrelated files, secrets, environment files, private config, IDE

metadata, generated noise, or risky changes.

1. If there is no implementation diff or PR for the intended commit, mark the

review target as Not Available and block readiness instead of claiming a code diff or PR review.

2. Perform Pre-Commit Code Review

Before writing the commit message, confirm whether a fresh applicable vibe-review result already covers the current diff.

A review is fresh and applicable only when:

• it was produced after the relevant diff was created or last changed;
• its target is code diff or PR;
• it covers the same intended files and related spec, plan, or task;
• it has no Blocking findings and its conclusion is Passed.

If no fresh applicable review exists, run or perform a vibe-review code/diff gate first, using the current diff and related spec, plan, and test evidence. Record the result in the readiness report.

If no current implementation diff or PR exists, there is no code/diff review target. Set Fresh applicable vibe-review: No, Review target: Not Available, Review conclusion: Not Available, and review performed before readiness: No. A spec, workflow, artifact, or docs review may support context, but it does not satisfy the pre-commit code/diff review gate.

Block the commit when you find:

• P0 or P1 correctness, data-loss, security, privacy, auth, permission,

migration, API compatibility, or user-visible regressions.

• Missing required generated output, schema alignment, or distribution artifacts.
• Mixed unrelated changes that should be split.
• Sensitive or local-only files staged or included.
• Changes that contradict the related spec, plan, or user request.
• Design-quality findings that create likely incorrect behavior, unsafe

follow-up changes, contract drift, or missing validation.

Non-blocking suggestions may be reported, but they do not stop commit unless they affect correctness, validation, scope, or safety.

3. Validate The Change

Use repository instructions and changed files to choose validation:

• Prefer focused tests, linters, typechecks, builds, validators, and manual QA

that directly cover the changed surface.

• Reuse existing test evidence when it is recent, relevant, and tied to the

same diff.

• Run required validators for changed skills, specs, plans, test evidence,

generated registry output, schemas, migrations, or frontend pages.

• For user-facing API error changes, require review and validation evidence for

local localized copy and absence of raw server error text or codes.

• For production code fallback or reflection-style access, require

human-approved decision evidence and focused validation before marking ready.

• If a necessary check cannot run, explain the blocker. Do not treat a skipped

required check as passing.

• Do not invent validation commands.

4. Decide Commit Readiness

The change is ready when:

• Scope is coherent.
• Intent is clear.
• Code review has no blocking findings.
• Required validation passed, or the only missing checks are explicitly

non-blocking and justified.

• No unrelated or sensitive files are included.
• Spec, issue, or task references are updated when required.

The change is blocked when:

• Code review has blocking findings.
• Required validation fails.
• Required validation was not run and the missing check can affect correctness.
• Sensitive files, private config, local IDE files, or unrelated changes would be

committed.

• The commit message would need to claim evidence that does not exist.

When blocked, stop before git commit. Output the findings, failed or missing checks, and concrete next steps.

For saved readiness reports, use [references/commit-readiness-template.md](references/commit-readiness-template.md) and validate with:

python3 skills/vibe-commit/scripts/validate_commit_readiness.py path/to/commit-readiness.md

5. Write The Commit Message

Use [references/commit-message-template.md](references/commit-message-template.md) unless the repository has a stricter convention.

Recommended structure:

feat: short summary

References:
Spec: path, issue, task, or None
Plan: path or None
Test Evidence: path, command, CI URL, or None
Review Evidence: readiness report, review summary, or None

Intent:
Why this change exists.

Change:
What changed.

Validation:
Conclusion plus the commands, checks, evidence, or explicit reason not run.

Use the first-line type as a Conventional Commit category such as feat, fix, docs, test, chore, or refactor. Do not literally write type:.

6. Commit Only When The Gate Passes

When the user explicitly asked for a commit and the readiness decision is Ready to Commit:

1. Stage only the intended files.
2. Validate the commit message draft when saved to a file.
3. Run git commit with the validated message.
4. Report the commit hash, included scope, validation evidence, and residual

risks.

Do not stage or commit unrelated local changes just because they are present.

7. Validate Saved Messages

If you save a commit message draft to a file, run:

python3 skills/vibe-commit/scripts/validate_commit_message.py path/to/commit-message.txt

Output

When the user asks for a commit or commit message, provide:

• Readiness conclusion.
• Files or scope included.
• Spec, plan, test evidence, issue, PR, or CI references.
• Code review findings.
• Validation checks and results.
• Risks, sensitive files, or unrelated changes.
• Commit message.
• Commit result when a commit was explicitly requested and the gate passed.

If the gate is blocked, do not include a final commit command. Give the user the blocking findings and the shortest path to make the change committable.

Skill Signature

Always end the final response with:

Vibe Skill Signature
Skill: vibe-commit
Status: Completed | Passed | Failed | Blocked | Partial
Next: concise next workflow step