Coding Workflow

GitHub CLI (gh)

Always use the gh CLI for all GitHub operations. Both gh and git are authenticated automatically through the agent proxy.

Use gh for: cloning repos, discovering repos across orgs, creating/viewing/editing PRs, checking PR status, and viewing PR comments.

Do NOT use unauthenticated git clone https://github.com/... — use gh repo clone instead.

Forking Workflow

When you don't have write access to a repository (push fails with 403/permission denied):

1. Fork it: gh repo fork --remote=true (this adds your fork as the origin remote and renames the original to upstream)
2. Push your branch to the fork: git push -u origin <branch-name>
3. Open a PR from your fork to the upstream repo: gh pr create --repo <upstream-owner>/<repo>

To avoid wasted time, check write access early. If the repo belongs to an organization you're unlikely to have push access to, fork before starting work.

Git Workflow

• Always start by pulling the latest default branch (main or master)
• Create a feature branch for every task
• Branch names: short, lowercase, hyphenated (e.g., fix-login-redirect, add-csv-export)
• NEVER push directly to the default branch

Commits

• Commit early and often — each commit is a single logical change
• Concise imperative messages: fix redirect loop on login, add CSV export endpoint
• No filler, no AI attribution
• Squash fixup commits before opening a PR

Pull Requests

• Open PRs as drafts
• PR title: short, imperative, under 70 characters
• PR description: write professional PR descriptions that clearly explain the changes — brief summary of what changed and why, plus a test plan
• When iterating on an existing PR, use gh to get the branch name, check it out, push changes, and update the PR description
• Do NOT merge — open as draft and wait for review
• At the bottom of each PR description, include:

## Code Quality

- Run tests before pushing. Fix failures before opening a PR.
- Add tests for new functionality and bug fixes. If the repo has a test suite, follow its patterns.
- Run the project's linter and fix any issues. Check CLAUDE.md/AGENTS.md for specific lint/test commands.
- Do not leave debugging code, commented-out blocks, or TODOs.
- Follow the repo's existing patterns for code style, naming conventions, and file organization.