| name | git-policy |
| description | Commit, branch, and pull request standards - conventional commits, atomic changes, branch naming, commit timing, and PR quality. Use when committing, branching, staging changes, or creating/updating a pull request. |
Git & Contribution Policy (Senior Engineering Standards)
Core Principle
- All commits and pull requests must follow professional engineering standards.
- Treat all contributions as production-grade changes.
- Follow repository contribution guidelines strictly (including external docs like CONTRIBUTING.md if present).
- This skill owns commit/branch/PR mechanics. Change-quality gating before committing is owned by code-review-policy; both apply together.
Branching & Commit Timing
- Commit or push only when the user asks for it; do not commit speculatively.
- If currently on the default/protected branch, create a topic branch before committing.
- Use descriptive branch names scoped by type (e.g. feat/, fix/, chore/).
- Keep branches focused on a single concern.
Cloning & Fetch Efficiency
- When cloning or pulling a repository, do not fetch the full history unless it is actually needed. A shallow fetch saves disk space, bandwidth, and time.
- Default to a shallow clone for one-off use (building, inspecting, running, or extracting current files):
git clone --depth=1 <url>.
- To narrow further, combine with
--single-branch (one branch only) and --no-tags (skip tag refs).
- The full history IS required (do not shallow-clone) when the task depends on it: bisecting, blame/log archaeology, rebasing/cherry-picking across many commits, generating changelogs/release notes, or any operation that walks past commits.
- A shallow clone can be deepened later if history turns out to be needed:
git fetch --unshallow (full) or git fetch --depth=<n> (more commits). Prefer this over re-cloning.
- For huge repos where you only need part of the tree, consider
--filter=blob:none (blobless partial clone) or sparse-checkout instead of a full clone.
Identity & Git Configuration Safety
- Commits and pull requests must be authored SOLELY by the local user's configured Git identity (user.name / user.email). This is non-negotiable.
- Never use an AI-managed, autogenerated, shared, or assistant-provided Git identity, and never set yourself as author or committer.
- Never add co-author or AI-attribution trailers to commit messages or PR bodies. Specifically, do NOT append "Co-Authored-By: Claude", "Co-Authored-By: ", "Generated with Claude Code", or any equivalent AI credit.
- Do not override the Git identity unless the user explicitly requests it.
- The commit/PR must read as if the user authored it; no trace of the assistant in author fields, trailers, or footers.
- Enforcement note: in Claude Code this is also disabled deterministically via settings.json (
attribution.commit / attribution.pr set to "", and includeCoAuthoredBy: false); the enigma installer sets this automatically. The rule here still applies on every runtime, settings or not.
Commit Strategy
Conventional Commit Style (Required)
- Use structured commit formats: :
Allowed types:
- feat: new features
- fix: bug fixes
- chore: maintenance tasks
- refactor: code restructuring without behavior change
- perf: performance improvements
- docs: documentation changes
- test: testing changes
- build: build system changes
- ci: CI/CD changes
Commit Emoji Convention (Ciphera Style, Default On)
- Commit subjects use a leading type emoji by default:
<emoji> <type>: <short description>.
Example: ✨ feat: add dual-provider matching.
- This is the one sanctioned exception to the global no-emoji rule: it applies ONLY to the
commit subject line. Commit bodies, PR text, code, comments, identifiers, and chat responses
stay emoji-free. Do not add more than one emoji, and place it only at the start of the subject.
- Use exactly this type-to-emoji map (do not invent others):
- ✨ feat: new features
- 🐛 fix: bug fixes
- 🔧 chore: maintenance tasks
- ♻️ refactor: code restructuring without behavior change
- ⚡ perf: performance improvements
- 📝 docs: documentation changes
- ✅ test: testing changes
- 📦 build: build system changes
- 👷 ci: CI/CD changes
- 🎨 style: formatting-only changes
- 🔒 security: security fixes or hardening
- ⏪ revert: reverting a previous commit
- Always keep a valid Conventional Commit
<type>: after the emoji; the emoji augments it, never replaces it.
- If the target repository defines its own commit convention (CONTRIBUTING.md, commitlint), follow the repo.
Opt-out
- A user can disable commit emojis. When disabled, omit the leading emoji and commit as plain
<type>: <short description>; everything else in this policy is unchanged.
- Disabled when
.enigma.json (in the repo root or the user home) contains "commitEmoji": false,
or via enigma config commit-emoji off. Re-enable with enigma config commit-emoji on.
- Check for this opt-out before composing a commit; treat commit emojis as on when no config is present.
Commit Quality Rules
- Commits must be atomic (one logical change per commit).
- Do not mix unrelated changes in a single commit.
- Commit messages must be meaningful and human-readable.
- Avoid vague messages like "fix" or "update".
Removing Leaked or Sensitive Data (Discreet-Commit Carve-Out)
Applies ONLY when remediating sensitive data the user wants removed from a repository - a
committed secret, credential, private path, internal/customer name, PII value, or an asset
rendered from one (e.g. a screenshot). For every other commit, including ordinary security
fixes and hardening, ignore this section and use the normal descriptive conventional-commit
rules above.
When such a removal is requested, FIRST present the remediation choices and let the user
decide (visibility and irreversibility are their call), then act:
- Rewrite history (
git filter-repo / BFG + force-push) - the only option that truly
removes the data. Warn that it is destructive, rewrites shared history (all later SHAs
change), needs a force-push (often to a protected branch), and that mirrors, forks,
CDN/raw caches and archives may still retain copies.
- Discreet removal commit on HEAD - delete or replace the data in a normal-looking commit.
Non-destructive and low-effort, but the data stays recoverable in older commits and
caches; it is hidden in plain sight, not erased.
Whichever path is chosen, the remediation commit (and any PR) MUST be unremarkable. A
message that announces the exposure is itself a vulnerability: it points anyone scanning the
history at exactly which commit to diff and what to look for, and - if it quotes the values -
re-leaks them permanently into the message. So, in this case only:
- Do NOT put leak, secret, credential, exposure, PII, "sensitive", "redact", "scrub" or
"hidden" in the subject or body, and do NOT use the
🔒 security type. Frame it as the
mundane, truthful surface change it also is (a chore/refactor/docs/build cleanup,
a preview refresh, an asset removal) so it blends into the surrounding history.
- NEVER reproduce the leaked values anywhere - not in the message, branch name, or PR - and
do not even name which identifiers or paths were removed.
- Keep it atomic, but if it helps the change not stand out, fold it into a plausible
neighbouring change rather than letting it sit alone as "the commit that removed something".
- The message must still be accurate about WHAT changed at the file level (never a bare
"fix"/"update"); it simply omits WHY.
Communicate the security context (what was exposed, that history and caches still hold it,
and any required credential rotation - a committed secret is burned even after deletion) to
the user in chat, NOT in the commit, PR title, or branch name.
Pull Request Engineering Standards
PR Creation Rules
- Every PR must include:
- Clear title describing the change
- Structured description of what changed and why
- Context of the problem being solved
- Any trade-offs or side effects
PR Quality Requirements
- Must be small and reviewable
- Must not include unrelated changes
- Must pass all tests before submission
- Must follow existing repository architecture and style
Automation (Commit Scripts Awareness)
- If a repository includes automation scripts (e.g. commit.sh):
- Prefer using existing scripts instead of manual commits
- Ensure scripts are executed in the correct environment (bash, git bash, WSL)
- Validate commit prefix selection before execution
Code of Conduct for Contributions
- Respect project licenses and legal constraints.
- Understand that all merged code becomes part of the project.
- Follow repository coding standards strictly.
- Be open to feedback and peer review without resistance.
Anti-AI Fingerprinting Rule
- Do not introduce patterns that reveal AI origin in commit history.
- Avoid repetitive or generic commit structures.
- Maintain natural, professional, repository-consistent commit descriptions.
PR Communication Rules
-
PR communication must assume ownership and responsibility for the changes.
-
Never refer to "the author", "the agent", "the AI", or third-person wording.
-
Use direct ownership language such as:
- "I refactored..."
- "This PR updates..."
- "I added validation..."
-
Avoid meta-commentary about the development process unless strictly relevant.
-
Do not mention:
- Internal scratch files
- AI workflows
- Temporary reasoning artifacts
- Hidden notes files
- Out-of-band debugging context
- Internal generation process
-
PR descriptions must contain only information relevant for reviewers and maintainers.
Formatting & Writing Rules
-
Prefer standard ASCII punctuation in commits, PR titles, and technical communication.
-
Avoid typographic punctuation such as "—", smart quotes, or decorative Unicode characters.
-
Use "-" instead of "—".
-
Do not use arrows (→). Use "->".
-
Avoid robotic or overly templated phrasing.
-
Keep PR communication concise, natural, and technically relevant.
-
Remove filler sections that do not help code review or maintenance.
Reviewer Notes Policy
- Reviewer notes must only include information directly useful for reviewing the change.
- Do not reference private, gitignored, local-only, or inaccessible files.
- Do not instruct reviewers to retrieve external/internal notes outside the PR unless explicitly required by repository policy.
- Avoid documenting debugging history unless it affects architecture, behavior, or future maintenance.
Safety & Final Validation
Before creating a commit or PR:
- Verify only relevant files are included
- Ensure no debug or temporary code is committed
- Ensure no secrets or sensitive data are included
- Ensure the change aligns with repository architecture
