# Contributing to Brigade

Brigade is the local-first operator CLI for agent memory, handoffs, and reviewable work receipts. It grew out of [Solomon's Cookbook](https://github.com/escoffier-labs/solos-cookbook), and patches are welcome. Before you start, please skim this file so we both spend our time on the right things.

## What kinds of changes land easily

- **Bug fixes** for `brigade init`, `doctor`, `scrub`, quickstart, security scanning, or the ingester.
- **Harness / depth / include improvements**: new bootstrap content, sharper post-install notes, better defaults.
- **New harness adapters** (with doctor checks) under `src/brigade/templates/harnesses/<id>.json`.
- **Doctor checks** that catch real, observed failure modes.
- **Test coverage** for any of the above.

## What needs a conversation first

- **A new top-level harness, depth, or include.** Open an issue first describing the user story. These are the public surface and renaming or splitting them later is painful.
- **Breaking changes** to template paths, the handoff TEMPLATE.md fields, or the ingester routing rules.
- **Anything that adds a runtime dependency.** Brigade has zero runtime deps on purpose, and we want to keep it that way.

## What does not land

- Personal details, hostnames, IPs, account IDs, or live auth profiles in templates or tests. The whole point of this kit is to keep that stuff out of public repos. The `content-guard` job in CI will fail if it finds any.
- Cron jobs or hooks that post or call out to the network without explicit opt-in.
- Commits must use conventional commits. In-house commits in escoffier-labs organizations and original solomonneas repositories should include a co-author trailer for a coding agent that did substantial work. External repositories and upstream third-party PRs remain trailer-free.

## Planning artifacts

Reviewed planning docs are public and tracked: the phase plans (`docs/phase-*.md`), `docs/roadmap-completion-plan.md`, and the superpowers plans and specs under `docs/superpowers/`. They stay in the repo as a record of how the work was sequenced.

`/docs/plans/` and `/docs/specs/` are gitignored on purpose. They are scratch space for in-flight drafts that have not been reviewed for publication. When a plan there is finished and scrubbed, move it to one of the tracked locations above (or delete it).

## Local dev

```bash
git clone https://github.com/escoffier-labs/brigade.git
cd brigade
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -q
```

To smoke-test an install end-to-end the same way CI does:

```bash
target="$(mktemp -d)"
git init -q -b main "$target"
python -m brigade init --target "$target" --depth workspace --harnesses claude,codex,openclaw
python -m brigade doctor --target "$target"
```

## Pull requests

`main` is branch-protected. A dispatched session cannot supply the review artifact required by its own pull request, and GitHub enforces the gate regardless of the dispatch prompt.

The current rule set requires all of the following before a pull request can merge:

- All 22 required GitHub Actions checks pass. The checks are pinned to GitHub Actions app id 15368, and the branch must be up to date with `main`.
- A current formal `APPROVED` review exists from a non-author reviewer.
- All review conversations are resolved.
- The approval was recorded after the last push. New commits dismiss stale approvals.

The pull request author cannot approve their own pull request. `gh pr review --approve` fails with "Can not approve your own pull request" when the author and reviewer share one GitHub identity.

CodeRabbit is the current external review identity. Its green commit status is not the grading artifact because the status can be green while the formal GitHub review is still `CHANGES_REQUESTED`. The artifacts that count are a current formal non-author `APPROVED` review and all required checks passing.

Inspect the gate before attempting a merge:

```bash
gh pr checks <number> --required
gh pr view <number> --json reviewDecision,mergeStateStatus
```

`reviewDecision` reports `REVIEW_REQUIRED`, `CHANGES_REQUESTED`, or `APPROVED`. `mergeStateStatus` reports states such as `CLEAN`, `BLOCKED`, and `BEHIND`.

Those CLI fields do not expose unresolved review conversations. Separately check the pull request's **Files changed** review panel in GitHub and confirm that no conversation remains unresolved.

Dispatched sessions should open the pull request, run local verification, and push commits. After the final push, comment `@coderabbitai full review`. The `coderabbitai[bot]` identity records the formal GitHub review. Wait for its current `APPROVED` review before merging. A green CodeRabbit commit status alone does not satisfy this gate.

## Adding a harness

A harness is a manifest under `src/brigade/templates/harnesses/<id>.json` plus any template files it references. The manifest declares `role: "writer"` (gets an inbox) or `role: "reader"` (gets adapter fragments).

To add a harness:

1. Create the manifest at `src/brigade/templates/harnesses/<id>.json`.
2. Add template files under a harness-named directory, for example `src/brigade/templates/<id>/`.
3. Add the harness id to `KNOWN_HARNESSES` in `src/brigade/selection.py`.
4. Update `HARNESS_PRIORITY` if the new harness should be an owner candidate (readers usually want to land near OpenClaw/Hermes in the priority list).
5. If it is a writer, add it to `WRITER_INBOXES` in `src/brigade/selection.py` and update any writer-specific installer, doctor, or ingest tests.
6. Add the harness to the CI matrix in `.github/workflows/ci.yml`.
7. Add a row to the harness table in `README.md`.

## Adding a depth

Depths live at `src/brigade/templates/depth/<id>.json` and may use `extends` to inherit from another depth. Add the id to `KNOWN_DEPTHS` in `selection.py` and to the `--depth` choices in `src/brigade/cli/init.py`.

## Adding an include

Includes live at `src/brigade/templates/includes/<id>.json`. Add the id to `KNOWN_INCLUDES` in `selection.py`.

## Adding a doctor check

Check functions live in `src/brigade/doctor.py` and nearby command modules. Each returns structured status data where status is `OK`, `WARN`, `FAIL`, or `MANUAL`. Prefer `WARN` or `MANUAL` over `FAIL` for things the user can choose not to wire up - `FAIL` should mean "this profile is broken."

## Promoting an experimental adapter

The Hermes adapter is currently marked experimental. To graduate it (or any future experimental adapter) to "tested":

- A doctor check exists that meaningfully exercises the adapter against a real install.
- Someone has run the full init + doctor cycle on a real Hermes workspace and reported it on an issue.
- The post-install notes no longer say "experimental".

Open a PR with all three and we'll land it.

## Filing issues

Please use the templates under `.github/ISSUE_TEMPLATE/` - they exist to save you from re-typing the version and install shape every time.

For first-run setup failures, use the "Quickstart setup problem" or "Init or doctor fails" form. The most useful report is the redacted `issue_report` from:

```bash
brigade operator quickstart --target <repo> --harnesses codex --json
```

Before posting output, remove tokens, private hostnames, private repo names, private account names, and unredacted absolute paths. Good labels for setup reports are `quickstart`, `setup`, `harness`, `docs`, and `security-scan`.

The `ingester-misclassified` template is the most useful one to file early. If a handoff that should have promoted to a card got bounced (or vice versa), that is a real bug in the routing rules, not a corner case. We want to see it.

## Credits

Brigade is written and maintained by Solomon Neas. Development runs through the same multi-model seat roster the tool orchestrates, so commits sometimes carry co-author trailers for the coding agents that did substantial work on them.

## License

By contributing you agree that your contribution is licensed under the MIT License, same as the rest of the repo.