Kanban Boards
Spexso provisions three GitLab kanban boards in every target project: one for workflow progression, one for operational hygiene, and one for backlog grooming. Boards are created automatically by npx spexso init / /spexso-setup, and can be added or repaired later with /spexso-boards-init.
The three boards
1. Workflow
Stage progression — what every issue's current status is. Columns map to stage::* labels:
| Column | Label | Meaning |
|---|---|---|
| Opportunity | stage::opportunity | Idea identified, no spec yet |
| Spec | stage::spec | Spec written, ready for /spexso-start |
| Build | stage::build | Implementation in progress (worktree open) |
| Review | stage::review | Code review phase |
| Ship | stage::ship | Pipeline running through DEV/TST/PRD |
| Operate | stage::operate | Live in production |
Closed issues are hidden automatically by GitLab. The Operate column shows issues that are live but still open (e.g., awaiting manual cleanup or needs::manual-test).
2. Needs attention
Operational hygiene — what's waiting on a human. Columns map to needs::* labels:
| Column | Label | When it appears |
|---|---|---|
| Manual test | needs::manual-test | /spexso-finish merged, but a tester needs to verify before closing |
| Conflict resolution | needs::conflict-resolution | Auto-merge failed; needs manual git resolution |
| Attention | needs::attention | Marathon left this issue (3-strike build failure, etc.) |
This board is the safety net for fully autonomous runs (/spexso-marathon): anything that came out wrong shows up here.
3. Backlog grooming
Priority ranking — for refinement sessions. Columns map to priority::* labels:
| Column | Label | Meaning |
|---|---|---|
| Critical | priority::critical | Drop everything |
| High | priority::high | Address this cycle |
| Medium | priority::medium | Normal priority |
| Low | priority::low | Nice to have |
GitLab boards can't filter by stage::opportunity OR stage::spec natively, so the board shows all open issues with a priority. During grooming sessions, use the board's filter UI to scope to stage::opportunity or stage::spec.
Provisioning architecture
lib/boards.js is a stateless Node module — sister to lib/labels.js. It exports createBoards() which delegates to the tracker adapter's syncBoards (also exposed as npx spexso board sync); on GitLab that calls the REST endpoints (POST /projects/:id/boards, POST /projects/:id/boards/:id/lists). Idempotent: existing boards and columns are skipped; only missing ones get added. Spexso never deletes.
Provisioning order is binding: labels must exist before boards, because each board column needs a label_id. lib/init.js calls createLabels() before createBoards() to enforce this.
Why 3 boards (not 1 or 5)
A single board can show all workflow stages, but it can't simultaneously show "what needs human attention" (the needs::* lane) without complex filtering. Conversely, 5+ boards splinter focus — by-platform or by-type boards rarely get checked.
Three boards each have a clear job:
- Workflow = the daily view, "where is everything?"
- Needs attention = the hygiene view, "what got dropped?"
- Backlog grooming = the planning view, "what's next?"
Out of scope for v1
- Group-level boards (GitLab Free limits this to 1; not worth the design overhead vs benefit)
- Custom per-platform or per-team boards (teams can build their own in GitLab UI)
- Board sync (one-time creation only; spexso doesn't track changes after provisioning)
Related
/spexso-boards-init— standalone provisioning command. See commands.- Setup boards scenario — developer walkthrough.
lib/labels.js— the label system that boards depend on. See GitLab setup.
In Claude Code
The GitLab boards are the team view. For a developer's own view inside a session, see the Board Mod.