Git

Git

How change is recorded.

Workflow

1. Work on the branch defined for the task at hand. Never push directly to main.
2. Create new commits rather than amending. Never force-push or skip hooks without explicit permission.
3. Task PRs target their milestone branch; milestone PRs target the latest main. Work outside a milestone stays on a feature branch and PRs only when explicitly asked.

SSH agent timeouts

1. Pushes and fetches occasionally time out. The 1Password SSH agent backs the github.com-* host aliases, and it intermittently stalls — surfacing as Operation timed out on port 22, or Please make sure you have the correct access rights and the repository exists.

2. This is expected and transient. Wait and retry first. It is not a credential, permission, or connectivity fault, and it does not mean the remote, the key, or the repo is misconfigured.

3. If it persists, fall back to a token-authenticated HTTPS push or fetch, passing the URL explicitly on the command line:

   git push https://github.com/<owner>/<repo>.git HEAD:<branch>
   git fetch --prune https://github.com/<owner>/<repo>.git "+refs/heads/*:refs/remotes/origin/*"
   

   • The gh auth git-credential helper supplies the token. Never embed it in the URL — that leaks it into the reflog, config, and process list.
   • Match the active gh account to the repo owner first (gh auth switch -u <account>); the helper serves the active account's token, so a mismatch 404s on private repos.

4. The fallback is temporary and per-command. Never git remote set-url to HTTPS, never add a url.*.insteadOf rewrite, and never switch to ssh.github.com:443, regenerate keys, edit ~/.ssh/config, or re-authenticate gh. The configured SSH remote stays exactly as it is; only the single command takes the detour.

5. After an explicit-URL push, refresh the tracking refs. Pushing to a URL does not update refs/remotes/origin/*, so the branch keeps reporting "ahead" despite being pushed. Run the fetch above to make git status accurate again.

6. Commits are unaffected. Local commits already succeeded; only the push is pending. Retry the push later rather than amending, resetting, or recommitting.

Conventional Commits

1. All commit subjects follow Conventional Commits:

   <type>(<optional scope>): <imperative summary>
   

   • Allowed types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert.
   • Scopes match the affected area: the surface (home), the layer (templates, tokens, constants), or the docs (prd, docs). Omit when global.
   • Subject: ≤ 72 characters, lowercase, no trailing period.
   • Body: explain the why when the diff alone doesn't.
   • Breaking changes: ! suffix and a BREAKING CHANGE: footer for route moves, renames, or behavior changes.

Branch naming

1. Branches follow the same type vocabulary as commits:

   <type>/<short-kebab-summary>
   

   • ≤ 40 characters, lowercase, hyphen-separated.
   • Milestone and task branches carry their identifiers: feat/m02-works, feat/m02-t04-works-ledger.
   • Branches outside a milestone reference the affected area: fix/date-zoning, docs/initial-plan.

Attribution

1. No AI/agent attribution in commits, PRs, or issues: no Co-Authored-By: Claude/Codex, no "Generated with Claude Code" markers, no claude.ai/code session links.

Review

1. Read the project's own vendored skills before reviewing the diff. Skills under .claude/skills/ / .agents/skills/ are that project's actual, current standards, not generic advice; load the ones relevant to the changed files (components for a component diff, data for a constants/data change, nextjs for routing, etc.) and check the diff against what they specifically say before reaching for anything else.
2. Then apply conventional best practice: correctness, security, performance, test coverage, readability — the concerns a project's skills don't cover because they're universal rather than project-specific.
3. A skill deviation is a finding on its own, distinct from a generic style nit: name the skill and the rule it violates, not just "this looks off."
4. When a project has no vendored skills, or the change touches an area none of them cover, fall back to conventional best practice alone — don't invent a project standard that isn't written down anywhere.