Skip to main content

Boards

A board is a project. It is the unit of parallelism in Nexus: each board owns the GitHub repositories its work is built against and maps to its own external board (Taiga). Nexus runs many boards in parallel off a single shared pool of agents.

Repositories and the external board belong to the board, not the agent. Agents are generic, repo-agnostic workers; the board decides what they build.

Why boards own repositories​

Earlier, repositories were attached to each agent. That coupled an agent to one project and made running several projects at once awkward. Now:

  • A board declares one or more repositories (cloned side-by-side into a run's workspace) and an optional Taiga project to sync to.
  • An agent declares its SOUL, model, skills, memory policy, tools, and permissions — but no repositories.
  • When a task on a board is dispatched, the worker resolves the board's repositories and hands them to the runner. The same developer agent can be building bitview-backend on one run and bitview-ui on the next.

This makes the agent pool a shared resource and lets a team of agents work on bitview-ui, bitview-admin, bitview-backend, and bitview-distributor concurrently — one board each.

A board document​

A board is the projects collection (a board is a rich project):

id: proj_bitview_backend
name: bitview-backend
slug: bitview-backend
description: |        # "summary" — short context injected into every run here
  Rust + axum services for BitView. Conventional commits; 80% test coverage.
repositories:
  - url: https://github.com/bitview-so/distributor.git
    name: distributor
  - url: https://github.com/bitview-so/bitview-bot.git
    name: bot
  - url: https://github.com/bitview-so/checkpoint.git
    read_only: true   # docs reference — read, don't push
taiga_project_id: "42"  # this board syncs to Taiga project 42
FieldMeaning
repositories[]GitHub repos cloned side-by-side for every task on this board. url, optional name (dir), branch, read_only.
descriptionBoard summary — budgeted context prepended to every run's system prompt.
taiga_project_idThe numeric Taiga project this board projects to. Falls back to the global taiga integration default when unset.

Private https repos clone with the GIT_TOKEN from the agent secret.

Goals target a board​

When you create a goal you pick its board. Decomposition produces tasks on that board, each task inherits the board's repositories, and the worker mirrors items to the board's Taiga project. Multiple boards advance independently and in parallel, bounded only by the global concurrency cap.

Pull-request review workflow​

Code changes on a board land through a reviewed PR, never a direct push to main:

  1. A developer (or tester/devops) agent works on a feature branch, commits, pushes the branch, and opens a PR with the git.open_pr tool. These agents have can_open_pr but not can_merge, and the git tool blocks direct pushes to main/master for anyone without merge rights.
  2. The reviewer agent (the only role granted can_merge) finds the PR (git.list_prs), reads the diff, leaves findings via board.comment, and — only if it passes — merges with git.merge_pr. Otherwise it requests changes and does not merge.

The PR tools (git.open_pr / git.merge_pr / git.list_prs) run in the agent pod against the GitHub API using the board's GIT_TOKEN, and are available to both API and CLI backends. For a server-side hard guarantee, also enable GitHub branch protection on main (require a PR) — note that requiring an approving review needs a separate reviewer identity, since a single bot token can't approve its own PR.

Managing boards​

In the Admin UI, Boards is full CRUD: add, edit, and delete boards; for each board attach multiple GitHub repos, write a summary, and set the Taiga project id. The Kanban view then shows items per board (with a board selector), and each ticket has a comments thread that mirrors to its Taiga story.