Git Workflow

Git Workflow

Manage the git workflow for this project. Follow these conventions strictly.

Branch Naming

Create descriptive branch names using category prefixes:

• feat/short-description — new features
• fix/short-description — bug fixes
• refactor/short-description — code restructuring
• chore/short-description — maintenance, deps, config
• security/short-description — security fixes
• ui/short-description — UI/UX changes
• improve/short-description — improvements and optimizations

Commit Conventions

Each commit must be atomic — one logical change per commit.

Commit message format: prefix: short imperative description

Prefixes: fix:, feat:, refactor:, chore:, ci:, docs:, test:

Use feat!: or fix!: for breaking changes.

Rules:

• If this is the first commit in a batch, inspect package.json and run only the validation scripts that actually exist among build, lint, and test. If any existing required script fails, abort immediately and return the failure to the caller. Do not attempt to fix unrelated issues from inside this skill.
• One logical change per commit — do not bundle unrelated changes
• Keep the subject line under 72 characters
• No period at the end of the subject line
• Always include this trailer at the end of every commit message:

Co-authored-by: Copilot <[email protected]>

Before creating any commit, review staged changes with git diff --cached to ensure only intended changes are included.

Enforcing Atomic Commits

Do not treat "atomic commits" as a preference. Treat it as a required workflow.

Before creating any commit:

• Inspect the full working tree with git status --short and git diff --stat.
• Identify the logical change units before staging anything.
• Create a brief internal commit plan such as:
• feat: add parser support for new field
• feat: add reusable chart component
• ui: refresh dashboard layout
• Stage and commit one logical unit at a time. Prefer file-based staging when a file belongs entirely to one change; use partial staging such as git add -p when multiple logical changes share a file.
• After each staged unit, run git diff --cached and verify the staged diff matches exactly one logical change.
• If the current working tree cannot be cleanly split into atomic commits without risky manual surgery, stop and tell the caller that the changes need to be reorganized before committing.

Never create a single catch-all commit when the diff spans multiple concerns, such as:

• parser or data-shape changes mixed with UI changes
• new reusable components mixed with feature wiring
• layout/styling changes mixed with behavior changes
• review feedback fixes mixed with unrelated cleanup

If the user asks to create a PR and the branch contains uncommitted work spanning multiple logical changes, the skill must split that work into multiple commits before pushing.

If the user asks to address PR feedback, keep the fixes in one commit only when they all serve the same review-driven purpose. If feedback touches separate concerns, split it into multiple commits.

PR Creation and Updates

After all commits are ready and pushed:

• Push the branch: git push -u origin <branch-name>
• Create a PR with gh pr create
• PR body must include a summary table of all commits:

| Commit | Change |
|--------|--------|
| `fix:` description | What was fixed and why |
| `feat:` description | What was added |

When reporting success back to the user, include the branch name, relevant commit SHA(s), and PR URL.

PR Follow-Up Pushes

When a branch already has an open PR and you push additional commits:

• Read the current PR body with gh pr view --json body -q .body and use that exact content as the base for your update. Do not generate a fresh PR description from scratch.
• Push the branch updates.
• Refresh the PR description with gh pr edit so it reflects the latest state of the branch.
• Treat the PR body as a surgical update, not a full rewrite:
• preserve existing sections such as summary prose, validation steps, and other reviewer context
• update the summary table to include new commits
• remove or rewrite outdated entries when the implementation changed
• mention review feedback fixes in the description when the new commits address PR comments
• If the PR body does not already contain a summary table, add one without removing the rest of the description.
• Before running gh pr edit, verify the updated body still contains the important sections from the original PR description.

Never leave the PR description stale after pushing fixes to an existing PR.

History Rewrites

If the user explicitly asks to redo commits, split a monolithic commit, or force-push a corrected branch:

• Rebuild the branch history into atomic commits that match the conventions above.
• Use git push --force-with-lease only when the user explicitly requested rewriting remote history.
• After the push, make sure the PR description still matches the new commit set.

Post-Merge Cleanup

When told a PR is merged:

• git checkout main
• git pull origin main
• Delete the merged branch locally: git branch -d <branch-name>
• Confirm the local main is up to date