# Contributing to Katala

Thanks for your interest in contributing! Here's how we work.

## Development Flow

Katala uses an AI-assisted PR pipeline inspired by OpenClaw's `/review-pr → /prepare-pr → /merge-pr` workflow.

### For contributors (including AI agents)

1. **Pick an issue** labeled `good-first-issue` or `ralph-eligible`
2. **Create a branch**: `feat/issue-{number}-short-description` or `fix/issue-{number}-...`
3. **Implement + test**: make sure `npm run lint` and `npm run test` pass locally
4. **Open a PR** against `main` with "Closes #{number}" in the body

### What happens to your PR

Once a PR is opened:
1. **RALPH reviews it** — automated AI review, looks for correctness, security, and style
2. **RALPH prepares it** — rebases and fixes any review findings automatically
3. **Nicolas approves** — final human merge gate

You don't need to respond to RALPH's automated comments; they're self-resolving.

## Code Standards

- **Language**: TypeScript (strict mode)
- **Tests**: Vitest — add tests for any new behavior
- **Lint**: ESLint — run `npm run lint` before pushing
- **Commits**: [Conventional Commits](https://www.conventionalcommits.org/) format
  ```
  feat(scope): add something new
  fix(scope): fix something broken
  test(scope): add or update tests
  docs(scope): update documentation
  refactor(scope): refactor without behavior change
  ```

## Issue Labels

| Label | Meaning |
|---|---|
| `good-first-issue` | Small, well-scoped, great for new contributors |
| `ralph-eligible` | Picked up automatically by RALPH pipeline |
| `triage-now` | Urgent, prioritized for next RALPH cycle |
| `blocked` | Waiting on external dependency |
| `needs-discussion` | Requires design decision before implementation |

## Local Setup

```bash
git clone https://github.com/Nicolas0315/Katala.git
cd Katala
npm install
cp .env.example .env.local   # fill in required vars
npm run dev
```

## AI Agents

AI-generated PRs are welcome. If you're an AI agent:
- Use a dedicated GitHub account (not the user's personal account)
- Include `🤖 Generated by <your-agent-name>` in the PR description
- Reference the issue number in the PR title and body
- Ensure all tests pass before opening the PR

## Questions?

Open an issue or ask in the [Katala Discord](#).