AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
docs: require completed PR template; sync CONTRIBUTING architecture-docs procedure
Claudebba1cb2423fa
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.mdindex ae666faf..dcfaad1e 100644--- a/.github/CONTRIBUTING.md+++ b/.github/CONTRIBUTING.md@@ -24,6 +24,10 @@ All PRs must:3. Include tests for new behavior4. For new or modified agents: include at least 2 eval scenarios5. **Architecture docs**: verify `/architecture` reflects your change (see below)+6. **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.## Adding a New Specialist Agent@@ -41,21 +45,36 @@ Requirements:## Architecture Docs (`/architecture` page)-The `/architecture` page in the UI documents the system for the team. Parts of it are live (auto-pulled from the API) and parts are static diagrams.--**You do NOT need to update anything if you:**-- Add a new specialist agent (the Agent Council section pulls from `GET /agents` automatically)-- Add or change an API endpoint (the API Reference pulls from `GET /openapi.json` automatically)-- Add or change a workflow (the Workflows section pulls from `GET /workflows` automatically)--**You DO need to update the static diagrams in `packages/ui/src/app/architecture/page.tsx` if you:**-- Change the overall request flow (how requests move from client → API → Executive → specialists → response)-- Change the prompt caching strategy (how system blocks are built or what's in the user turn)-- Add a new integration layer (new inbound channel, new external service)-- Change the memory system architecture (new storage backend, new extraction pipeline)-- Change how the knowledge/RAG pipeline works at a structural level--These structural changes are rare and significant — they warrant a diagram update in the same PR.+The `/architecture` page in the UI is served from **static, hand-authored+content**: one `packages/core/openexecutive/architecture/prebuilt/<section_id>.json`+file per section listed in `architecture/sections.py`. Nothing on that path+calls an LLM at runtime, so nothing updates itself — if your PR changes+behavior a section describes and you don't re-author the section, the page+silently goes stale.++The deep source-of-truth notes behind the page live in+`packages/core/openexecutive/architecture/architecture-facts.yaml`.++**When your PR materially changes a documented topic, update BOTH in the same+PR**: the relevant `architecture-facts.yaml` key, and the affected+`prebuilt/<section_id>.json`. This applies equally to *changes* under an+existing topic (e.g. adding a new integration channel, changing a documented+endpoint's response shape) — not just brand-new topics. The topic → section-id+map and full procedure are in [CLAUDE.md](../CLAUDE.md#architecture-docs);+common cases:++- New or changed integration channel → `integrations`+- New workflow primitive or routing pattern → `workflows` / `agents` / `lifecycle`+- Cache layout change → `caching`+- Endpoint added/removed/renamed or response shape changed → `api`+- New top-level module under `packages/core/openexecutive/` → new `SectionSpec`+ in `architecture/sections.py`, matching entry in+ `packages/ui/src/app/architecture/page.tsx`, and a new `prebuilt/<id>.json`++Each `prebuilt/<id>.json` carries `section_id`, `title`, `markdown`, `mermaid`+(string or `null`), and `generated_at`; validate edits with+`python -m json.tool`. Pure additions to `SPECIALIST_REGISTRY` are+auto-reflected in the `agents` facts and need no YAML edit.## Prompt Changes