| name | git-commit |
| description | Commit discipline for any agent or human committing to this repo. Verify identity before the first commit, follow the conventional-commits format with task traceability, exclude secrets via .gitignore, attribute human and AI contributors honestly. |
| agents | ["all"] |
| sdlc_phase | implementation |
| owner | Platform Eng |
| status | active |
Git Commit Discipline
When to use
Any time an agent (or human) is about to run git commit in a worktree or the main branch. Also at project setup, before the first commit, to verify identity and .gitignore. The skill applies cross-phase — BA's SRS edits, SA's architecture edits, Dev's code changes, DevOps's deploy scripts, non-SDLC agents' report files all flow through the same commit discipline.
agents: [all] is a sentinel — this skill is registered under Cross-cutting in .claude/skills/registry.md and applies to every agent in the kit.
Inputs and outputs
- Inputs: the change to commit; the master-plan task ID (
T-NNN) it serves if applicable; the agent role making the commit; for human-contributed work, the human's name + email
- Outputs: a well-formed conventional commit in the current local worktree, with identity, traceability, and any required attribution trailers
Procedure
- Identity check (one-time per worktree). Run
git config user.email && git config user.name. If either returns empty, halt — do not commit. Tell the user to configure (see "Configuring identity" below).
.gitignore check (one-time per repo). Verify the repo has a .gitignore covering at minimum: env files, secrets, IDE artifacts, build outputs, OS files, the kit's own .tmp staging files. Use references/gitignore-template.md as the baseline.- Stage the changes.
git add <paths> — never git add . blindly. Verify with git status and git diff --cached before committing.
- Compose the commit message per
references/conventional-commits-format.md:
- Subject line:
<type>(<scope>): <description> — short, lowercase, no trailing period
- Blank line, then body (optional but encouraged for non-trivial commits)
- Blank line, then footer trailers (task ref, attribution)
- Verify message against the regex in
conventional-commits-format.md. If it doesn't match, rewrite — don't bypass with --no-verify.
- Add the task reference. Every commit made for a master-plan task should reference that task (e.g.,
Refs: T-014 in the footer, or scope-tagged like feat(billing)(T-014): …).
- Add attribution trailers where they apply (see
references/compliance-policy.md):
Co-authored-by: <name> <email> when a human's contribution shaped this commit (notably the design-human-edited Figma flow per CLAUDE.md §4)Generated-By: <agent-role> when an agent (Claude Code instance) is the primary author
- Commit.
git commit -m "..." for single-line, or git commit to open the editor for multi-line.
- Do not push or merge local worktree history. A sub-agent worktree under
.worktrees/<role>-<task-id>/ is detached and local-only. Never run git push, git pull, git merge, git rebase, or git cherry-pick from it. The Orchestrator promotes validated file content to main by path-scoped ingestion per .claude/rules/worktree-isolation.md §5.
Configuring identity
Required values:
user.email — for organizational work, prefer your corporate email domain; never use a personal email for work commitsuser.name — full name (real name, not a handle)
Commands:
git config user.email "you@example.com"
git config user.name "Your Full Name"
git config --global user.email "you@example.com"
git config --global user.name "Your Full Name"
The skill does not auto-configure on the agent's behalf — identity is a human-attested fact, not something an agent should infer. Refuse to commit if unconfigured; surface the gap.
Commit message format (summary; see reference for full spec)
<type>(<scope>): <description>
<optional body — wrap at 72 chars; multiple paragraphs OK>
<optional footer trailers — one per line>
Refs: T-NNN
Co-authored-by: <name> <email>
Generated-By: <agent-role>
<type>: feat | fix | docs | style | refactor | perf | test | chore | build | ci | revert<scope>: lowercase, dash-separated; for application work prefer area names (api, web, auth, billing, etc.) or kit areas (agents, rules, skills, hooks, docs)<description>: present-tense imperative, lowercase first letter, no period, ≤72 chars total subject line
Default subject-line regex (tighten per project as needed):
^(feat|fix|docs|style|refactor|perf|test|chore|build|ci|revert)(\([a-z0-9-]+(\)\([A-Z]-[0-9]+\))?\))?: [a-z][^.\n]{0,71}$
The optional (T-NNN) scope-tail captures the task ID directly in the subject (feat(billing)(T-014): add voucher application). Equivalent footer style: Refs: T-014 on its own line.
See references/conventional-commits-format.md for the full type catalog with descriptions, scope conventions, and worked examples (good and bad).
.gitignore essentials
Categories that must be excluded:
- Secrets:
.env* (except .env.example/.env.template/.env.sample), *.pem, *.key, *.p12, *.pfx, id_rsa*, *.crt, *.cer
- Local environment:
node_modules/, .venv/, __pycache__/, .tox/, *.pyc, .cache/
- Build artifacts:
dist/, build/, target/, bin/, out/, *.log
- IDE / editor:
.vscode/ (unless team-shared), .idea/, *.swp, .DS_Store, Thumbs.db
- Kit staging:
*.tmp, CLAUDE.md.*.tmp (the kit's awk staging files; remember to delete them after edits)
Allowlisted (always committable):
.env.example, .env.template, .env.sample — these document required env keys without leaking values- Lock files (
package-lock.json, yarn.lock, poetry.lock, go.sum, Cargo.lock) — these make builds reproducible
Full template: references/gitignore-template.md.
The privacy-check hook (.claude/hooks/privacy-check.cjs) refuses reads/writes against the secret patterns at runtime — .gitignore is the static defense layer, the hook is the dynamic one.
Compliance requirements
Identity
- Every commit has a named
user.email and user.name. No anonymous or default-tooling identities (root@..., unknown, etc.). Refuse to commit otherwise.
- For organizational work, identity should match the corporate email pattern. The skill doesn't hard-enforce this — it's a project policy line in
references/compliance-policy.md.
Attribution
- Human contributors →
Co-authored-by: trailer. Applies when a human shaped the commit beyond mere review — most notably the design-human-edited Figma flow per CLAUDE.md §4 (the human's edits are treated as co-authored, not as a reviewer correction).
- AI agents →
Generated-By: trailer. When a Claude Code sub-agent is the primary author, the commit should declare its role (Generated-By: be-dev, Generated-By: ba, etc.). Org-specific AI-authorship policy may require more (model version, prompt log reference); flagged as policy territory in the reference.
Traceability
- Every task-scoped commit references its master-plan task —
Refs: T-NNN in the footer, or via the scope-tail (T-NNN) in the subject. Commits made outside of master-plan work (kit edits, infra scripts, non-SDLC reports) reference the relevant artifact path or note Refs: none in the footer.
- Non-SDLC report commits (researcher / debugger / code-reviewer / oq-resolver outputs) reference their report path:
Refs: docs/research-reports/<topic-slug>.md.
Hygiene
- No secrets in commit history. If a secret ever lands in a commit, the secret is compromised — rotate immediately, then scrub history (
git filter-repo or BFG). Prevention is far cheaper than remediation; the .gitignore + privacy-check hook are the prevention layer.
- No PII (names, emails of users / customers, internal IDs) in commit messages. Commit history is durable and broadcasts widely; PII in
git log is a leak.
- No force-pushing to shared branches. Sub-agents do not push at all from
.worktrees/<role>-<task-id>/; those detached commits stay local and are discarded after validated file-content promotion.
Hard Rules
- Never commit with
user.email or user.name empty. If either is missing, halt and ask the user to configure.
- Never commit a message that fails the conventional-commits regex. Rewrite — never bypass with
--no-verify.
- Never commit a
.env, *.pem, *.key, or any other secret-class file. If git status shows one, stop and add it to .gitignore before continuing.
- Never include PII or customer identifiers in commit messages or commit bodies. Reference issues / tickets by ID, not by user.
- Never
git push, git pull, git merge, git rebase, or git cherry-pick from a sub-agent worktree. Local worktree commits are not integration history.
- Never use a personal email for organizational work commits.
- Every task-scoped worktree commit carries either
Refs: T-NNN (or scope-tail (T-NNN)) for master-plan work, or Refs: <artifact-path> for kit / docs work. No commits without traceability.
References
references/conventional-commits-format.md — full type catalog, scope conventions, regex variants, worked examplesreferences/gitignore-template.md — categorized .gitignore with rationale per sectionreferences/compliance-policy.md — identity / attribution / signing / residency — defaults plus areas where your organization's policy applies- CLAUDE.md §5 — Worktree isolation (where the commit happens) — moved to
.claude/rules/worktree-isolation.md §5
- CLAUDE.md §8 — Master plan task IDs for traceability — moved to
.claude/rules/master-plan-discipline.md §8
- CLAUDE.md §4 — Design lifecycle (the
design-human-edited co-authorship trigger) — moved to .claude/rules/parallel-execution.md §4
.claude/hooks/privacy-check.cjs — runtime defense against committing secrets; .gitignore is the static defense layer
