Committing

Committing

Full reference: .github/COMMITTING_GUIDELINES.md (examples, git aliases, commit template). This skill is the actionable summary.

Before you commit

1. git status and git diff — know exactly what you're about to commit.
2. Stage specific files, not git add . / git add -A blind.
3. git diff --cached — review staged content one more time, scan for secrets (API keys, tokens, passwords).
4. Let hooks run. Never --no-verify, never --no-gpg-sign. If a hook fails, fix the underlying issue and re-stage — don't bypass it.

Writing the commit

• Atomic: one logical change per commit. Don't mix a feature, a fix, and a refactor in one commit.
• Message explains WHY, not WHAT — the diff already shows what changed.
• Imperative mood summary ("Add X", not "Added X"), ideally under ~50 chars, blank line, then body wrapped at ~72 chars if more explanation is needed.
• Reference issues (Fixes #123, Relates to #456) when applicable.

What never gets committed

• Secrets: API keys, tokens, passwords, private credentials.
• .env and its variants — but DO commit .env.sample (sanitized template).
• Debug code: stray console.log/print, commented-out code, debugger statements.
• Build artifacts, node_modules/, and anything covered by .github/.gitignore.template.

After the commit — run the completion gate, then follow publish authority

1. Run bash tools/check-completion.sh — all quality gates must pass before declaring work done. This is enforced by the Stop hook in .github/hooks/completion-gate.json (Copilot) and .claude/settings.json (Claude Code).

   This path is specific to the agentharness repo itself. If this skill file is symlinked/copied into a consumer project instead (the normal case — see harness-link.sh), tools/check-completion.sh does not exist there and will exit 127. Check for a generated, consumer-local completion gate first: [ -x .agentharness-bin/check ]. harness-link.sh init/update generates this wrapper automatically for link/submodule/npm modes — run bash .agentharness-bin/check in its place. It delegates to the resolved harness checkout's own enforce-profile command against this project, not the harness's. --mode copy has no live harness checkout to delegate to, so no wrapper exists there — harness-link.sh audit --json's can_mechanically_enforce field tells you up front whether a given install has one at all, rather than finding out mid-task. Either way, also run this project's own lint/type/test commands if it has any not covered by the gate. Don't silently skip verification just because the harness's own path doesn't resolve — find the equivalent for this repo.

2. Default (no publish authority): stop at the commit. Stage the commit locally, summarize what was done, and ask the user to confirm before pushing or opening a PR. Work is "done" when the user has reviewed and approved the staged changes.

3. With publish authority: push and open a PR. Publish authority is granted when .agentharness-publish-mode exists at the repo root — check with [ -f .agentharness-publish-mode ] (or test -e), never by reading its contents. The file is typically empty by design; an agent that cats it, sees nothing, and concludes "not active" has the check backwards — presence alone grants authority, content is irrelevant. harness-link.sh audit --json's publish_mode_active field already implements this correctly if you'd rather not shell out to test directly. Publish authority is also granted when the user explicitly authorizes it in the current session.

   • git push -u origin <branch> (first push) or git push (subsequent). If this fails with an SSH key error (Permission denied (publickey)) even though gh auth status shows a valid session: the remote is an SSH URL (git@github.com:...) but no SSH key is configured in this environment — a real, seen-in-practice mismatch, not a sign the push itself is wrong. Don't permanently reconfigure the remote to work around a one-off environment gap. Instead, push to an explicit HTTPS URL for this one invocation, using gh's own credentials: git push "https://github.com/$(gh repo view --json nameWithOwner -q .nameWithOwner).git" <branch>. If pushing will be a recurring need in this environment, gh auth setup-git is the durable fix (configures git's credential helper to use gh's token for HTTPS) — but that's a persistent environment change, so confirm with the user before running it, the same as any other durable configuration change.
   • gh pr create with a real title, body, and test/verification notes.
   • Work is not "done" until the PR exists, CI is green, and review comments have been addressed.

See CLAUDE.md's "Agent Workflow Completion" section for the full rules and the 📋 Completion Gate section for the gate commands.

If tests or hooks fail

Fix the underlying issue (lint error, failing test, secret detected). Don't commit broken code planning to fix it "in the next commit."