Skip to main content

​
Boards

A board is a Kanban-style pipeline that organizes tasks into columns. Each column represents a stage in a workflow, with optional gates that control when tasks can advance.

​
How Boards Work

Boards replace the legacy task_types system with richer, project-scoped pipeline management. Every board has an ordered set of columns, and tasks move through them left-to-right. 
┌─────────┐  ┌───────┐  ┌───────────┐  ┌──────┐  ┌───────┐  ┌────────┐  ┌────┐  ┌──────┐
│ Triage  │→│ Draft │→│ Brainstorm│→│ Wish │→│ Build │→│ Review │→│ QA │→│ Ship │
└─────────┘  └───────┘  └───────────┘  └──────┘  └───────┘  └────────┘  └────┘  └──────┘
  agent       human      human+agent    human     agent       human      agent    human

​
Columns

Each column has:
PropertyDescription
nameMachine-readable identifier (e.g., build)
labelHuman-readable display name (e.g., Build)
gateWho can advance tasks: human, agent, or human+agent
actionSkill invoked when a task enters this column (e.g., /work)
auto_advanceWhether tasks auto-advance when the gate clears
rolesWhich roles can move tasks into this column
colorDisplay color (hex code)
positionColumn ordering (0-indexed)

​
Column Gates

Gates control task flow. They define who can move a task into a column:
GateMeaning
humanRequires human approval to advance
agentAn agent can auto-advance the task
human+agentEither a human or an agent can advance
When auto_advance is true and the gate is agent, the task moves forward automatically when the linked skill completes. For example, a task in build (gate: agent, action: /work) will auto-advance to review when the work skill finishes.

​
Board Templates

Templates are reusable board blueprints. Genie ships five built-in templates:
TemplateStagesUse case
softwaretriage, draft, brainstorm, wish, build, review, qa, shipFull delivery pipeline
saleslead, qualified, proposal, negotiation, closed-won, closed-lostSales pipeline
hiringsourcing, screening, interview, offer, hiredRecruitment pipeline
opsidentified, planning, in-progress, doneOperations workflow
bugtriage, draft, build, review, qa, shipBug fix pipeline
Create a board from a template (see the Board CLI reference for all commands): 
genie board create "Sprint 12" --template software

​
Projects and Boards

Boards are scoped to projects. A project can have multiple boards (e.g., one for features, one for bugs). When you set an active board with genie board use, that board becomes the default for task operations in the current repo. 
# Set active board for this repo
genie board use "Sprint 12"

# Tasks now default to this board
genie task create "Add auth" --stage build
Global boards (no project scope) are also supported for cross-project workflows.

​
Board Lifecycle

# Create from template
genie board create "Q2 Sprint" --template software --project myapp

# View columns
genie board columns "Q2 Sprint"

# Set as active
genie board use "Q2 Sprint"

# Export for sharing
genie board export "Q2 Sprint" > q2-sprint.json

# Import on another machine
genie board import --file q2-sprint.json

​
Relationship to Tasks

Tasks link to boards via board_id and track their current column via column_id. When you move a task (genie task move), the column_id and stage update together. The board’s column pipeline validates that the target stage exists.

​
Database Storage

Boards are stored in PostgreSQL:
TablePurpose
boardsBoard metadata and column definitions (JSONB)
board_templatesReusable board blueprints
tasks.board_idLinks a task to its board
tasks.column_idTracks which column the task is in

​
Best Practices

Start with a built-in template and customize columns for your workflow. The software template maps directly to Genie skills.
More than 8-10 columns creates cognitive overhead. If you need more, consider splitting into multiple boards.
Use agent gates for stages that can run autonomously (build, qa). Use human gates for stages that need judgment (review, ship).
Use genie board use to set the default. This simplifies task operations by removing the need to specify --board on every command.