> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yourhq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing

# Contributing to HQ

Thanks for wanting to help. This doc covers the contribution flow — code, templates, docs, and bug reports.

## Quick links

* [Good first issues](https://github.com/yourhq/yourhq/labels/good%20first%20issue)
* [Help wanted](https://github.com/yourhq/yourhq/labels/help%20wanted)
* [Roadmap](/getting-started/roadmap)

## Ways to contribute

1. **Agent templates** — add a new starting point for a role/persona (see below)
2. **Bug fixes** — check existing issues, open a PR
3. **UI improvements** — Next.js + Tailwind + shadcn; changes go in `apps/ui/`
4. **HQ plugins** — event-driven integrations that react to tasks, agents, knowledge, and more (see below)
5. **Source connectors** — data source integrations for knowledge sync; see `CONTRIBUTING-SOURCES.md`
6. **Documentation** — if something confused you, a doc PR will save the next person
7. **Translations** — not shipped yet, but we'll accept i18n contributions when the framework is in

## Before you start

**For small changes** (typos, obvious bugs, template tweaks): open a PR directly.

**For bigger changes**: open an issue first so we can discuss approach. We don't want you to spend days on a PR that doesn't match the project direction.

## Development setup

Prerequisites:

* Docker + Docker Compose
* Node.js 24+ (for UI development)
* A Supabase project for testing

```bash theme={null}
# Clone and set up
git clone https://github.com/yourhq/yourhq.git
cd yourhq
cp .env.example .env
# Leave Supabase empty for browser onboarding, or set env overrides for gateway-only testing

# Live-reload dev mode
docker compose -f docker-compose.yml -f docker-compose.dev.yml up
```

Edit any file under `apps/ui/` and the UI reloads automatically. Edit `gateway/entrypoint.sh` or `gateway/daemons/*` and restart the relevant service:

```bash theme={null}
docker compose restart gateway dispatcher runner
```

### Running just the UI

If you're only working on the UI:

```bash theme={null}
cd apps/ui
npm install --legacy-peer-deps
npm run dev
```

Complete browser onboarding against the local dev server, or set `HQ_CONFIG_DIR` to a local directory with compatible `workspaces.json` and `secrets.json` files. You won't have a gateway in this setup, so gateway-dependent pages will error; that's expected.

### Running just the gateway

Useful when iterating on the agent runtime without touching the UI:

```bash theme={null}
docker compose up -d gateway dispatcher runner
docker compose logs -f gateway
```

## Adding an agent template

1. Copy an existing template as a starting point:
   ```bash theme={null}
   cp -r templates/default templates/my-new-role
   ```
2. Edit `templates/my-new-role/agent.json` to match the role (name, description, team, model, etc.)
3. Customize the identity files:
   * `IDENTITY.md` — personality, voice, domain knowledge
   * `SOUL.md` — core beliefs and goals
   * `USER.md` — the owner profile template
   * `MEMORY.md` — starting memories
4. Add role-specific skills in `skills/`
5. Test: create an agent from this template in the UI, verify it behaves as expected
6. Rebuild the templates index:
   ```bash theme={null}
   node apps/ui/scripts/build-templates-index.mjs
   ```
7. Open a PR with the new template + the updated generated index

Templates live in the monorepo so they're versioned together. Breaking changes to the template format show up as PRs touching multiple templates.

## Adding an HQ plugin

HQ plugins react to workspace events (task created, agent provisioned, budget exceeded, etc.) and take action. Two types:

**Local plugins** — Python modules on the gateway with full SDK access:

1. Copy the template:
   ```bash theme={null}
   cp -r gateway/plugins/_template gateway/plugins/my-plugin
   ```
2. Edit `manifest.json` — set `id`, `name`, `hooks` (events to subscribe to), `config_schema`, and `capabilities`
3. Implement `handler.py` — subclass `BasePlugin`, implement `on_event()`
4. Test locally by restarting the gateway
5. Open a PR with the plugin directory

**Webhook plugins** — remote HTTP endpoints, no gateway code:

* Register from Settings → Plugins in the UI. No PR needed unless you want to document the integration.

For the full reference, see:

* [Plugins concept](/concepts/plugins) — architecture and design
* [Plugins guide](/guides/plugins) — step-by-step walkthrough
* [Plugin events](/reference/plugin-events) — all 16 available events
* [`gateway/plugins/CONTRIBUTING.md`](https://github.com/yourhq/yourhq/blob/main/gateway/plugins/CONTRIBUTING.md) — in-repo contributor guide

## PR checklist

Before opening a PR:

* [ ] `docker compose -f docker-compose.yml -f docker-compose.dev.yml up` still boots the stack
* [ ] `npx tsc --noEmit` passes (zero TS errors) in `apps/ui/`
* [ ] `npm run lint` passes in `apps/ui/` (warnings OK, errors fail CI)
* [ ] For gateway changes: `shellcheck gateway/entrypoint.sh gateway/scripts/*.sh` passes
* [ ] You haven't committed secrets, `.env`, or `*.pem` files
* [ ] Commit messages describe *why*, not just *what*

Open your PR against `main`. CI runs automatically. A maintainer will review within a few days.

## Code style

* **UI**: ESLint + Prettier config in `apps/ui/`. Run `npm run lint -- --fix` before committing.
* **Python**: PEP 8, no specific linter pinned yet. Keep to what's in `gateway/daemons/*.py`.
* **Shell**: shellcheck-clean. Use `set -euo pipefail` in new scripts.
* **TypeScript**: strict mode. No `any` unless there's a reason; then a comment explaining.
* **Commits**: conventional-commits style preferred but not required. One PR = one logical change.

## Architecture decisions

Before proposing big architectural changes, read:

* [Architecture](/concepts/architecture) — current system design
* [Roadmap](/getting-started/roadmap) — shipped areas and planned work
* Recent issues labeled `design`

Big changes go through an issue first. We prefer small, iterative PRs to big refactors.

## What "accepted" means

Once merged to `main`:

* Docker images get rebuilt and published to GHCR automatically
* Users who track `:latest` pick up the change on their next `docker compose pull`
* Pinned users (`v0.1.0` etc.) don't see it until we cut the next release

We don't do per-PR release notes. Significant changes get called out in the GitHub release notes when we cut a tag.

## Code of conduct

Be kind. See the [code of conduct](https://github.com/yourhq/yourhq/blob/main/CODE_OF_CONDUCT.md).

## License

By contributing, you agree that your contributions are licensed under the Apache License 2.0 (see [LICENSE](https://github.com/yourhq/yourhq/blob/main/LICENSE)).

## Questions

* General: [Discussions](https://github.com/yourhq/yourhq/discussions)
* Bug reports: [Issues](https://github.com/yourhq/yourhq/issues)
* Security: `security@yourhq.ai` — don't use issues

Thanks for helping.