# Contributing to <PROJECT_NAME>

> <PROJECT_DESCRIPTION>

---

## Prerequisites

<CONTRIBUTING_SETUP_NOTES>

---

## The Contribution Loop

1. **Claim** an issue in [<PROJECT_KEY> on <TRACKER_TYPE>](<TRACKER_URL>)
2. **Branch** from `<DEV_BRANCH>`:
   ```bash
   git checkout {DEV_BRANCH} && git pull
   git checkout -b feat/{PROJECT_KEY}-XXX-short-description
   ```
3. **Implement** your changes (run quality gates before pushing)
4. **Open PR** against `<DEV_BRANCH>`

---

## Branch Conventions

| Prefix    | Purpose            | Example                                   |
| --------- | ------------------ | ----------------------------------------- |
| `feat/`   | New features       | `feat/<PROJECT_KEY>-42-user-auth`         |
| `fix/`    | Bug fixes          | `fix/<PROJECT_KEY>-51-login-redirect`     |
| `hotfix/` | Production patches | `hotfix/<PROJECT_KEY>-99-session-timeout` |

All branches include the tracker issue ID for traceability.

---

## Commit Format

```
feat({PROJECT_KEY}-XXX): short description of change

Longer explanation if needed. Focus on *why*, not *what*.

Refs: {PROJECT_KEY}-XXX
```

| Type       | When                                 |
| ---------- | ------------------------------------ |
| `feat`     | New feature or capability            |
| `fix`      | Bug fix                              |
| `refactor` | Code restructure, no behavior change |
| `docs`     | Documentation only                   |
| `test`     | Test additions or fixes              |
| `chore`    | Build, CI, or tooling changes        |

---

## Quality Gates

Run these before opening a PR:

| Gate  | Backend                  | Frontend                 |
| ----- | ------------------------ | ------------------------ |
| Tests | `<TEST_COMMAND_BE>`      | `<TEST_COMMAND_FE>`      |
| Lint  | `<LINT_COMMAND_BE>`      | `<LINT_COMMAND_FE>`      |
| Types | `<TYPECHECK_COMMAND_BE>` | `<TYPECHECK_COMMAND_FE>` |

All gates must pass before merge.

---

## Pull Requests

- Target branch: `<DEV_BRANCH>`
- Title matches commit format: `feat(<PROJECT_KEY>-XXX): description`
- Link the tracker issue in the PR body
- Link the feature spec (if applicable)
- Request review from at least one team member

---

## Using ECK Skills

If this project uses [evolv-coder-kit](https://github.com/evolvconsulting/evolv-coder-kit), these slash commands streamline the workflow:

| Command                               | Purpose                                    |
| ------------------------------------- | ------------------------------------------ |
| `/<PK>:design-feature <desc>`         | Design a feature (research, design, tasks) |
| `/<PK>:dev-feature <PROJECT_KEY>-XXX` | Implement all tasks under an epic          |
| `/<PK>:dev-task <PROJECT_KEY>-XXX`    | Implement a single task (TDD)              |
| `/<PK>:validate-quality`              | Run all quality gates                      |

> Full workflow details: [development-workflow.md](development-workflow.md)

---

## Further Reading

| Document                                           | Purpose                                                 |
| -------------------------------------------------- | ------------------------------------------------------- |
| [development-workflow.md](development-workflow.md) | Two-session model, agent dispatch, full workflow spec   |
| [project-constitution.md](project-constitution.md) | Architecture principles, security, testing requirements |
| [CLAUDE.md](CLAUDE.md)                             | AI agent configuration, slash commands, hooks           |
| [docs/INDEX.md](docs/INDEX.md)                     | Documentation index (if available)                      |
