# CONTRIBUTING.md — Generic Collaboration Guide

This repository is designed for human and AI contributors. Keep contributions small, clear, and verifiable.

## Contribution principles

- Prefer focused pull requests.
- Avoid unrelated refactors.
- Preserve existing behavior unless a change is explicitly requested.
- Document assumptions and tradeoffs.

## Development Commands

- **Install**: `npm install`
- **Test**: `npm test`
- **Lint**: `npm run lint`
- **Build**: `npm run build`

## Standard contribution flow

1. Sync your branch with the target base branch.
2. Read baseline guidance:
   - `AGENTS.md`
   - `CLAUDE.md`
   - `KNOWN_ISSUES.md`
3. Implement minimal changes required to solve the task.
4. Run relevant validation checks.
5. Update documentation if behavior or workflow changed.
6. Commit with a clear message.
7. Open a PR with complete context.

## Commit expectations

- Keep commits atomic and descriptive.
- Use imperative commit subjects.
- Separate mechanical renames from behavioral changes when possible.

## Pull request expectations

Each PR should include:

- **Summary**: what changed.
- **Why**: motivation/problem solved.
- **Files modified**: key files touched.
- **Validation**: exact commands run and outcomes.
- **Risks / rollback**: known risks and how to revert.

## Validation expectations

- Run checks most relevant to changed files (tests, lint, typecheck, build, scripts).
- If a check cannot run, include:
  - command attempted,
  - reason it failed or was unavailable,
  - fallback verification performed.

## Documentation and handoffs

When your work creates reusable knowledge:

- Add/update `docs/agent-handoffs/learnings/` for successful patterns.
- Add/update `docs/agent-handoffs/incidents/` for failure modes and mitigations.
- Add/update `KNOWN_ISSUES.md` for active unresolved issues.

Use filename format: `YYYY-MM-DD-short-topic.md`.

## Security and privacy

- Never commit credentials, tokens, secrets, or personal data.
- Redact sensitive values in logs and examples.
- Prefer synthetic or anonymized examples in documentation.