CONTRIBUTING.md

Contributing

This project treats human and AI-agent contributions the same way: changes should be understandable, scoped, tested, and easy to review.

Before Starting

• Check the current branch.
• Check git status.
• Pull the latest remote state when working on a shared branch.
• Read README.md, AGENTS.md, SECURITY.md, docs/architecture.md, and relevant ADRs.

Change Style

• Keep behavior changes separate from unrelated refactors.
• Prefer small, reviewable commits.
• Update tests when behavior changes.
• Update docs when setup, commands, architecture, security posture, or workflows change.
• Add an ADR for project-shaping decisions.

Multi-Agent Work

• State intended file or module ownership before editing.
• Avoid overlapping edits to the same files.
• If another agent's changes are present, work with them instead of reverting them.
• Use clear commit messages so parallel work is easier to reconcile.

Testing

Before submitting or committing finished work:

• Run the relevant unit, integration, lint, typecheck, or build commands.
• Add regression coverage for bug fixes.
• Document any skipped checks and why they were skipped.

Security Review

For security-sensitive changes, check:

• Secrets are not committed.
• Inputs are validated at trust boundaries.
• Authentication and authorization behavior is explicit.
• Dependencies are necessary and reasonably maintained.
• Logs do not expose private data.

Definition Of Done

• Code is implemented.
• Tests/checks pass or documented blockers remain.
• Relevant docs are updated.
• ADRs capture important decisions.
• Changes are committed and pushed when appropriate.