# Contributing to Agent Orchestrator

## Dual-Repository Model

This project uses a dual-repo structure:

| Repository | License | Purpose |
|------------|---------|---------|
| `DexterFromLab/agent-orchestrator` | MIT | Community edition (open source) |
| `agents-orchestrator/agents-orchestrator` | MIT + Commercial | Commercial edition (this repo) |

Community contributions target the community repo. Commercial development happens
exclusively in this repo. The two share a common `main` branch that is synced
periodically.

## Community Contributions

All community contributions go to **DexterFromLab/agent-orchestrator**. Do not open
PRs against this repo for community features.

### How to Contribute

1. Fork the community repo at `DexterFromLab/agent-orchestrator`
2. Create a feature branch from `main`
3. Make your changes and commit using conventional commits
4. Open a pull request against `DexterFromLab/agent-orchestrator` `main`
5. Sign the CLA when prompted by the bot on your first PR
6. Address review feedback
7. Once approved, a maintainer will merge your PR

Do **not** fork or open PRs against `agents-orchestrator/agents-orchestrator` for
community contributions. That repository contains commercial code and access is
restricted.

### Contributor License Agreement (CLA)

Every community contributor must sign the CLA before their first PR is merged.
CLA signing is automated via [CLA-assistant.io](https://cla-assistant.io/) on
the community repository. The bot will prompt you on your first PR.

The CLA grants the project maintainers a perpetual, irrevocable license to use
your contribution in both the community and commercial editions. You retain full
ownership of your code. See [CLA.md](CLA.md) for the full agreement text.

## Commercial Development

Commercial features are developed only in this repository. Access is restricted
to authorized team members.

### What Content Is Commercial-Only

The following paths and markers identify commercial-only content:

| Marker | Description |
|--------|-------------|
| `agor-pro/` | Commercial feature modules |
| `src/lib/commercial/` | Commercial frontend components |
| `tests/commercial/` | Commercial test suites |
| `LICENSE-COMMERCIAL` | Commercial license file |
| `LicenseRef-Commercial` SPDX header | Any file with this header |
| `test:all:commercial` script | Commercial test runner |

This content is automatically stripped during community sync and never appears in
the community repository.

### SPDX License Headers

All commercial source files must include the following header as the first line:

```
// SPDX-License-Identifier: LicenseRef-Commercial
```

For CSS/HTML files:

```
/* SPDX-License-Identifier: LicenseRef-Commercial */
```

For Rust files:

```rust
// SPDX-License-Identifier: LicenseRef-Commercial
```

Community-shared code uses the MIT identifier:

```
// SPDX-License-Identifier: MIT
```

## Community Sync Workflow

The community repo is kept in sync with this repo via an automated workflow:

1. **Trigger**: Manual dispatch or on release tag publication
2. **Strip**: `scripts/strip-commercial.sh` removes all commercial content
3. **Verify**: Automated checks ensure no commercial references remain
4. **Push**: A sync branch is pushed to `DexterFromLab/agent-orchestrator`
5. **Merge**: A maintainer reviews and merges the sync PR

To preview what would be stripped locally:

```bash
# Dry run — shows what files would be removed (modifies working tree)
bash scripts/strip-commercial.sh
# Reset after preview
git checkout .
```

The leak-check CI workflow runs on every push and PR to `main`, verifying that no
commercial content has been accidentally committed to community-bound code.

## Branch Model

| Branch | Purpose |
|--------|---------|
| `main` | Shared with community edition. Never commit commercial code here. |
| `commercial/*` | Commercial-only features. Merged into the commercial release branch. |
| `feature/*`, `fix/*` | Standard development branches. |

### Sync Flow

The community repo's `main` is merged into this repo's `main` periodically:

```
community/main --> origin/main --> commercial branches
```

Use `make sync` to pull community changes. Never force-push `main`.

## Commit Conventions

Use [Conventional Commits](https://www.conventionalcommits.org/):

```
type(scope): description

feat(dashboard): add team analytics panel
fix(sidecar): handle timeout on agent restart
docs(api): update webhook payload reference
chore(deps): bump tauri to 2.3.1
```

Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`, `ci`, `build`.

Breaking changes use `type!:` prefix or include `BREAKING CHANGE:` in the footer.

## Testing

Both editions must pass their respective test suites before merge:

```bash
# Community tests (must always pass on main)
npm run test:all

# Commercial tests (includes commercial-specific tests)
npm run test:all:commercial
```

Do not merge a PR if either suite is red. If a community sync introduces
failures in commercial tests, fix them before merging.

## Code Review

- All PRs require at least one approval.
- Commercial PRs must be reviewed by a team member with commercial repo access.
- Verify no commercial code leaks into community-bound branches before approving.