| name | git |
| description | Guidelines for validation, staging, amending, and commit messages. |
Git
Validate Changes
Before committing any changes, ensure that your work does not break the application and meets all quality standards.
Run the validate task just prior to commit:
task validate
Stage Changes
When staging changes, stage only the files that you have changed as part of your current stream of work
git add ./path/to/file ./path/to/file2
⚠️ Never stage changes by adding the whole directory:
git add .
Instead, if you wish to stage folders, stage those also deliberately:
git add path/to/folder
Amend Commits
If you need to update the previous commit (e.g., to squash changes or fix a mistake), append changes to the last commit:
git commit --amend
If you have already pushed, you will need to force push:
git push --force-with-lease
Write Commit Messages
Commit messages should follow the standard format:
Title
Maximally 72 characters, descriptive, using imperative mood (e.g., "Deploy changes automatically" not "Deployed changes").
Body
Maximally 72 characters, Explain why the change was made (justification), not just what changed. Use headers for structured context if applicable:
Design:
Describe the design of the change here.
Tradeoffs:
Explain any tradeoffs (performance, complexity, etc).
Justification:
Provide the reasoning for this change.
Co-author
If pair programming or crediting others, add co-authors at the end of the body:
Co-authored-by: NAME <NAME@EXAMPLE.COM>
Coding agents are pair-programmers and must credit themselves. Use a consistent format that includes both the model and the harness:
Co-authored-by: ${MODEL} <${MODEL}@${HARNESS}.agent>
- ${MODEL}: The AI model generating the commit (e.g.,
Claude, Gemini).
- ${HARNESS}: The agent harness orchestrating the session (e.g.,
pi). If no harness is present, use direct.
Examples:
Co-authored-by: Claude <claude@pi.agent>
Co-authored-by: Gemini <gemini@pi.agent>
Co-authored-by: Claude <claude@direct.agent>
Issue References
When there is a reference to an existing issue tracker (e.g., GitHub Issues, Jira, Linear, etc.), include it as a Trailer at the end of the commit message. Use Rel: when the commit is related to the issue but does not resolve it:
Rel: https://github.com/org/repo/issues/123
Use Fixes: only when you are certain the commit fully resolves the issue:
Fixes: https://github.com/org/repo/issues/123