Boards

01What Boards are, and why

Automations need a place to record work that outlives one turn: what is open, who has it, and what it waits for. A board is that place. People and Agents read and write the same cards through one validation path.

A card can be a task, a reminder to check something later, a handover from one Agent to another, or a handover from an Agent to a person. The core is small on purpose: four coordination statuses (open, waiting, done, cancelled), one assignee, an optional person the card waits on, an optional wakeAt, a Markdown body and an append-only history. There are no dependencies, claims or relations between cards.

Lessons from the market (research of October 2026)

• Execution ledgers do not survive; work items that link to runs do. OpenClaw added a SQLite Tasks ledger with a task-flow layer, then removed all of it (“each runtime owns execution and completion”). Its Kanban Workboard plugin, with Agent assignees and links to sessions, survived.
• Derive Agent state, do not let the Agent set it. Linear makes the Agent the issue’s delegate while a person stays accountable, and derives the Agent session state (active, awaitingInput, error, …) from emitted activity.
• “Needs a human” is a state, not a product. A2A INPUT_REQUIRED, MCP input_required and the waiting-for-user states of coding agents all model it on the work item. Standalone agent-inbox products were archived or deprecated. Boards model it as waiting plus waitingOnUserId and a badge.
• Fixed generic tools plus a schema read. Notion, monday, Airtable, Jira and OpenProject expose custom fields through generic tools, a describe-schema call and server-side validation, not per-tenant tool schemas. Boards do the same, so tool lists stay stable for prompt caching.

02What it enables

Each scenario uses the same six tools, the same card, and the same wake pipeline. Only the actor and the destination change.

Industry template: a CPG commercial team

The default site ships a commercial-tasks template (“Commercial team tasks”, card key TASK) that models a category-management team in consumer goods retail. It was shaped by a fit check against a customer’s own dashboard prototype; the template itself is generic.

A typical flow: a category manager creates a card of type Losses for the Dairy direction and assigns it to a named analysis Agent. The Agent reads the template with board_get, writes its findings as a comment, fills labor_hours and to_pct, moves the card to In review, and sets it to wait on the reviewer. The reviewer replies on the card, which wakes the Agent again.

03System architecture

The split follows authorization. Chat App already owns the membership directory, Project membership and Agent grants for Skills, so it owns boards. Agent Platform owns only the wake and the execution it starts, and it never reads chainlit tables.

04Data model

Four Prisma models in the chainlit schema, with logical references only (no physical foreign keys), and three columns on one Agent Platform table. Physical checks and unique indexes hold the invariants that would otherwise need code.

Migrations: apps/chat/chainlit-datalayer/prisma/migrations/20261006130000_agent_boards, 20261007120000_board_templates (which also numbers existing cards per board), and apps/agent-platform/packages/db/migrations/0048_agent_platform_board_card_fires.sql.

05Access and authority

Boards use the shared resource_access primitive with the policy read < contribute < manage. One board has one audience; there is no per-card visibility. The place a board lives in adds implied access on top of explicit grants.

Grants go to users, teams, groups and Agents. Agent grants are agents: [{id, generation, permission}], bound to the Agent ownership generation like Skill grants, so a change of ownership invalidates them. Anything granted to an Agent can appear in any turn of that Agent, the same as its Knowledge and Skills.

Place-implied access

Per-presence reach

Rules on every surface

The signed named-Agent board context

A named Agent in a Slack room has no Chat session to borrow authority from, and it must never use the invoker’s. So Chat issues a capability that names the Agent itself.

1. Agent PlatformAdmission asks Chat to authorize

   At admission, Agent Platform calls Chat named-agent-boards:authorize. Chat signs a named-agent-boards-v1 context bound to the Agent, its ownership generation and the admission, with an expiry.

2. AgentEach tool call carries the context

   The kernel tool sends the signed context through the chat-context bridge. Chat checks the signature and the expiry.

3. Chat AppReverse confirmation

   Chat confirms with Agent Platform /v1/chat/named-agent-boards:validate that the admission is live, the same pattern as Skill reads. Schedule-card details use /v1/chat/named-agent-boards:schedules with the same context.

Workbench sessions, memory dreams and unlinked channel guests get no board context. A linked channel user who never opened Chat gets a local user row at that point, so they can be an assignee or an awaited person.

06Agent tools

Six kernel tools with fixed schemas (apps/agent-platform/packages/kernel/src/tools/chat-context/board-tools.ts). There are no per-template tools: a template is discovered at run time with board_get, so the tool list stays stable for prompt caching.

Where the tools work

07Wakes, step by step

A wake is an agent_task_fire row with trigger_kind = 'board_card'. It reuses the Absurd fire task, Chat staging, admission and delivery of schedules, but not their lifecycle, recurrence, active hours or pause-on-failure.

What starts a wake

• Assigning a card to an Agent, at once, unless wakeAt is in the future.
• A comment by the person the card waits on: the card returns to open and the assigned Agent wakes.
• A manual wake from the card by a person; it raises the card revision.
• Changing wakeAt on an assigned open card: a future time schedules a wake, clearing it wakes now.

Fire-time checks

Before staging, the fire asks Chat board-wakes:check: the card must still be open with the same assignee, the authorizing person must still hold contribute, and the Agent must still reach the board. An exact revision match is not required, so a title edit does not cancel a pending wake. Agent Platform then checks invoke, the Agent state and its ownership generation. A failed card check skips the fire (Chat records wake_skipped with the system actor); a failed Agent check fails it. Deleting an Agent cancels its live board fires.

Follow-up wakes

Bounds, payer and destination

08Templates

A template is declarative data in the site repository: typed fields, an optional stage graph with gates, a card key prefix and saved views. Core validates and renders it; nothing in a template executes code. Boards then hold stable business state as well as coordination state.

Anatomy

site-bootstrap/default/board-templates.yaml — excerpt of commercial-tasks (lines elided with # …)

boardTemplates:
  - slug: commercial-tasks
    version: "1.0"
    cardKeyPrefix: TASK
    label:
      en-US: Commercial team tasks
      ru: Задачи коммерческой команды
      pl: Zadania zespołu handlowego
      de-DE: Aufgaben des Commercial-Teams
      es: Tareas del equipo comercial
      fr-FR: Tâches de l'équipe commerciale
    # description: … (all six locales)
    access:
      all: true
    fields:
      - key: type
        type: select
        required: true
        label: {en-US: Task type, ru: Тип задачи, pl: Typ zadania, de-DE: Aufgabentyp, es: Tipo de tarea, fr-FR: Type de tâche}
        options:
          - key: losses
            color: red
            icon: trending-down
            label: {en-US: Losses, # …}
          # revenue, price_positioning, assortment, suppliers, promo, merchandising
      - key: goals
        type: multiselect
        options:
          - key: margin_growth
            color: emerald
            icon: chart-line
            attributes: {weight: 20, priority: 1, owner: Category Director}
          # loss_reduction, price_index, availability, q4_revenue, …
      - key: start
        type: datetime
        role: start
      - key: finish
        type: datetime
        role: due
      - key: labor_hours
        type: number
      - key: to_pct
        type: number
        help: {en-US: Turnover change in percent, # …}
      - key: budget
        type: money
        currency: EUR
      - key: reviewer
        type: person
    stage:
      initial: not_started
      stages:
        - key: not_started
          next: [in_progress, cancelled]
        - key: in_progress
          next: [in_review, not_started, cancelled]
        - key: in_review
          next: [done, in_progress]
          requiresFields: [labor_hours, finish]
        - key: done
          terminal: done
          next: [in_progress]
        - key: cancelled
          terminal: cancelled
          next: [not_started]
    views:
      - key: board
        kind: board
        groupBy: stage
        subGroupBy: type
        columns: [type, direction, finish, labor_hours, assignee]
      - key: table
        kind: table
        columns: [cardKey, type, direction, goals, stage, assignee, reviewer, start, finish, labor_hours, budget, to_pct, fm_pct, tr_pct]
      - key: mine
        kind: board
        groupBy: stage
        subGroupBy: type
        filter: {assignee: me}
# every field, stage and view also has a six-locale label

Identity: a stable kebab-case slug, a publisher version label, a cardKeyPrefix ([A-Z]{2,8}), a label, an optional description, and access in the site grant syntax (all, or groups and teams by !Ref). The default site also ships a simpler team-tasks template (TEAM): type, priority with a rank attribute, due date, and To do → In progress → Review → Done.

Field types

Field keys match [a-z][a-z0-9_]{0,39}. Any field can be required; after every write all required fields must have a value.

Stage graph

Write rules: one validation path

The UI routes, REST and the Agent tools all call create_board_card() and update_board_card() in chainlit/boards/board_cards.py, which validate with board_templates.py.

• A fields patch sets the keys it names; null clears a key; unknown keys and invalid values are refused.
• A card starts in the initial stage, so that stage’s requiresFields apply at creation. A create with another stageKey is a move from the initial stage.
• A move must follow next, and the target’s requiresFields must have values after the same write.
• Entering a terminal stage sets its status and clears waiting. Leaving one sets open. On a staged board, done and cancelled come only from terminal stages; a direct status change is refused with their names. In a terminal stage, status and waiting-on are read-only.
• The card dialog and the board view take these locks from one frontend helper, boardCardStatusRules(). The card form sends only the fields a person edited, so a value the form cannot show exactly (seconds of a datetime, an Agent’s value) does not change or block an unrelated save.
• History records fields_changed (before and after of changed keys) and stage_changed (from, to).

Views

At least one view; the first is the default. A board view groups by stage (or by status without a stage) and can collapse cards into subGroupBy select groups with counts. A table view lists columns: field keys plus the built-ins assignee, status, stage, cardKey and updatedAt. A view can carry a fixed filter (stages, statuses, assignee: me). The board read returns all cards; views and ad hoc filters apply on the client. There are no per-user saved views.

Import, re-import and retirement

Init step 22_ imports board-templates.yaml through POST /admin/board-templates/import as the board-templates entity, after Skills and the membership directory sync (SITE_BOOTSTRAP_IMPORT_MODE_BOARD_TEMPLATES: replace or skip). The YAML is the whole live set: the import creates, updates and retires templates. validate_board_template_definition() rejects any error with its YAML path.

Known, accepted gap: a card write that runs at the same moment as an import can still use the old definition. Imports run only at deployment.

Localization

Every label, help text and description must contain all six Chat locales: en-US, ru, pl, de-DE, es, fr-FR. The UI resolves a label the same way the backend resolves the app catalog: the exact locale (ru-RU), then its language (ru), then en-US. Agents get en-US plus the turn locale only.

FDE workflow

1. Write the template in the customer site repository

   board-templates.yaml with six-locale labels. Site Git is the only authoring path; there is no template editor in the UI.

2. Ship the procedure as Skills, and the Agents that work the board

   Skills explain the customer’s rules (“promos above the threshold need finance review”). Named-Agent profiles get the Project membership or Agent grant that lets them reach the boards.

3. Import at deployment

   just init-config runs step 22_; a refused import names the cards to migrate. Breaking changes ship with a dbmate data migration in the same change.

4. Keep enforcement where it belongs

   If a workflow must change an external system with binding checks (ERP posting, budget release), build a domain MCP service and register it in mcp-tools.yaml. That service enforces the action; the board coordinates it.

09Schedule cards and occurrences

Recurrence is Jobs. A board does not get its own recurrence engine; it gets a read-only window onto a Job, and the cards the Job’s runs create.

On the board, schedule cards sit in a Recurring section, never in task columns, and cannot be dragged. Cards of ended Jobs stay in a folded “Ended” group and can still be removed. Agents cannot link or remove schedule cards.

10Attention badge and live updates

One query, two socket events, and no notifications outside Chat.

11UI tour

Screenshots of the local demo stack (demo user, default site templates, demo data). Chat App has a Boards section in the navigation rail with the attention badge, a sidebar pane of reachable boards, and board pages; Projects and Agent pages show their default board. Select an image to open it at full size.

12Intentionally not built, and Phase 2

Owner decisions: Boards provide human-visible coordination and stable business state. They are not a binding enforcement system for external business actions. Customers are assumed to have no tracker, so the native board must be rich enough to be one.

Later, on demand

• External tracker events. For customers who keep a tracker as system of record: an external-event trigger kind on the same fire pipeline, with an authenticated source, a scoped destination (one Agent, thread or Project), event-id deduplication and live authority checks. MCP event support needs verification first.
• A first FDE vertical with a domain MCP service and an inline MCP App, to prove the enforcement boundary.
• MCP App mounts in the card panel (needs viewer-based admission), card relations, attachments, plugin packaging of templates and Skills.

13Status

After these fixes the five board test modules pass (34 tests) on the demo stack. Shipping needs a PR into the collaboration branch, CI and Dark Review.