Skip to content

AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).

docs: settle on a PR title convention

Claudebb5976b9a143
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index dcfaad1e..12c3a010 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -24,7 +24,16 @@ All PRs must:
3. Include tests for new behavior
4. For new or modified agents: include at least 2 eval scenarios
5. **Architecture docs**: verify `/architecture` reflects your change (see below)
-6. **A completed PR description using the template** — what changed, why, and
+6. **A title in the form `type(scope): what changed`**, in the imperative —
+ `fix(chat): bind the session for the whole SSE turn`. Types are `fix`,
+ `feat`, `docs`, `chore`, `refactor`, `test` and `perf` — a new specialist
+ agent is a `feat` and a new eval scenario is a `test`, so the `agent/` and
+ `eval/` branch prefixes above have no type of their own. The scope is the
+ subsystem (`chat`, `memory`, `alerts`, `ui`, `deps`, …), not a file path,
+ and is dropped only when a change genuinely spans the repo.
+ Say what changed rather than what it is about — `fix(memory): stop the
+ extractor dropping short approvals`, not `fix(memory): extractor bug`.
+7. **A completed PR description using the template** — what changed, why, and
how it works, with the checklist filled in. PRs submitted with an empty
template will be closed; you're welcome to resubmit with the sections
completed.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 55c7965a7..7c4547a8 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -4,6 +4,22 @@ See .github/CONTRIBUTING.md for the full contribution guide.
Detail belongs in the commit message, not here. Open questions belong in the
review thread.
+
+TITLE: type(scope): what changed, in the imperative.
+
+ fix(chat): bind the session for the whole SSE turn
+ feat(alerts): let the Executive clear a card from the Discuss handoff
+ docs(architecture): describe the committee review pass
+ chore(deps): bump anyio to 4.14.2
+
+Types: fix, feat, docs, chore, refactor, test, perf.
+Scope is the subsystem, not a file path — chat, memory, alerts, briefing,
+orchestrator, integrations, email, slack, ui, providers, knowledge, workflows,
+scheduler, deps. Drop it only when the change genuinely spans the repo.
+
+Say what changed, not what it is about: "fix(memory): stop the extractor
+dropping short approvals", not "fix(memory): extractor bug". Lowercase after
+the colon, no trailing period, and keep it under ~70 characters where you can.
-->
## Problem
diff --git a/CLAUDE.md b/CLAUDE.md
index 2039d27f..dfdab619 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -210,6 +210,13 @@ cd evals && python run_evals.py --scenarios scenarios/ --output results/
- Eval scenarios for new agents or prompt changes
- `ruff check` and `mypy` must pass
- Architecture docs updated per `## Architecture Docs` above (when integrations, scheduler, departments/people, caching, invariants, routing patterns, or top-level modules change)
+- PR title is `type(scope): what changed`, in the imperative — e.g.
+ `fix(chat): bind the session for the whole SSE turn`. Types: `fix`, `feat`,
+ `docs`, `chore`, `refactor`, `test`, `perf`. Scope is the subsystem
+ (`chat`, `memory`, `alerts`, `briefing`, `orchestrator`, `integrations`,
+ `ui`, `deps`, …), not a file path; drop it only when the change genuinely
+ spans the repo. Say what changed rather than what it is about, lowercase
+ after the colon, no trailing period. See `.github/PULL_REQUEST_TEMPLATE.md`.
- PR description is three sections and nothing else: **Problem**, **Approach**,
**Checklist** (see `.github/PULL_REQUEST_TEMPLATE.md`). Rationale, review
findings and alternatives go in the commit message; open questions go in the