Board sync
Nexus has its own internal board and is the authority. External boards
(Plane first, Jira later) are projections kept in sync through the
BoardProvider trait.
Nexus Board Item
↓
Plane Work Item
Status mapping
| Nexus status | Plane state |
|---|---|
planned | Backlog |
ready_for_agent | Ready for Agent |
running | In Progress |
waiting_human | Need Human Review |
blocked | Blocked |
done | Done |
How sync works
- Core mutates an internal
board_itemas tasks/runs change. - It emits
nexus.board.sync.requested. - The worker's Plane sync consumer reads the event and calls the
PlaneBoardProvider(create_item,update_status,add_comment). - The mapping internal ↔ external is stored in
board_links. - Plane webhooks notify Nexus of external changes; the worker reconciles them back into the internal board.
Rate limits and resilience
Plane's REST API is documented at ~60 requests per minute per API key, so
the nexus-board-plane crate applies client-side rate limiting (governor)
and backoff. Webhook payloads are verified with HMAC (hmac + sha2).
Why a projection, not a dependency
Keeping Nexus authoritative means:
- The platform works with the internal board only (no Plane required).
- Swapping Plane for Jira is implementing one trait.
- An outage in the external board never blocks agent execution — sync catches up via replayable events.