# Contributing

Guidelines for contributing to this project. Adapt this file to your team's workflow.

---

## Commit Messages

This project follows [Conventional Commits](https://www.conventionalcommits.org/):

```
type(scope): description
```

### Types

| Type | When to use |
|------|-------------|
| `feat` | New feature or capability |
| `fix` | Bug fix |
| `docs` | Documentation only |
| `refactor` | Code change that neither fixes a bug nor adds a feature |
| `test` | Adding or updating tests |
| `chore` | Build, CI, dependencies, tooling |
| `style` | Formatting, whitespace (no logic change) |
| `perf` | Performance improvement |

### Scopes (optional)

Use the area of the codebase affected: `frontend`, `backend`, `api`, `auth`, `docs`, `agents`, `llm`, `infra`.

### Examples

```
feat(backend): add webhook signature verification
fix(frontend): prevent double form submission
docs(agents): update frontend-architect profile for React 19
refactor(api): extract payment logic into separate module
chore: update dependencies
```

---

## Pull Requests

1. Create a feature branch from `main`
2. Keep PRs focused — one concern per PR
3. Fill in the PR template (`.github/PULL_REQUEST_TEMPLATE.md`)
4. Ensure no secrets or credentials in the diff
5. Update relevant documentation if behavior changes
6. Request review from the appropriate owner

### Branch Naming

```
type/short-description
```

Examples: `feat/webhook-verification`, `fix/login-redirect`, `docs/update-phases`.

---

## Adding Documentation

1. Create new `.md` files under `docs/` in the appropriate subdirectory
2. Write in English
3. Include a metadata header:
   ```
   ---
   **Phase:** Phase N (Description)
   **Status:** Draft / Active / Locked
   **Owner:** Team or person
   ---
   ```
4. Update `DOCS.md` index with a link to the new file
5. Update the project structure tree in `README.md` if adding a new directory

---

## Adding Agent Profiles

1. Create a new `.md` file in `agents/`
2. Follow the structure of existing profiles (role, responsibilities, guidelines, checklist)
3. Include context7 verification instructions for version-sensitive recommendations
4. No changes to `RULES.md` needed unless the agent selection protocol changes
5. Update `DOCS.md` and `README.md` to reference the new profile

---

## Adding ADRs

1. Copy `docs/adr/0000-template.md` to `docs/adr/NNNN-title.md`
2. Fill in context, decision, consequences
3. Link the ADR in `RECOMMENDATIONS.md` section 7
4. Follow the guidelines in `docs/adr/README.md`