Board Mod (Claude Code)

spexso-board is an optional Claude Code mod that shows the spexso backlog without leaving the session. It reads only .spexso/index.json, so it is exactly as fresh as the last spexso sync. Every skill that changes issues (brainstorm, report, tinder, finish) already runs that sync.

What you see

• Band above the prompt: ◆ spexso 3 to brainstorm · 2 ready · 1 build · 0 review. The counts are per stage::*.
• /spexso-board: a pane with the issues per stage. Each issue shows its size, priority, ⬤ when it has a worktree, and 🔒 #n when an open blocker exists.
  • [Brainstorm] on an opportunity starts /spexso-brainstorm <id>.
  • [Start] on a spec starts /spexso-start <id>.
  • [Sync] runs npx spexso sync.

Outside a spexso project (no .spexso/index.json) the mod shows nothing.

Marathon dashboard

/spexso-marathons opens a local web dashboard in your browser (the mod starts it with Node.js, which must be ≥ 22.18):

• Up next: the marathon that still needs brainstorms, with a readiness ring — or the one that is ready to start.

• The board: Backlog | one column per open marathon (spexso/ milestone) | Plan a marathon. Cards show type, stage, size, priority, blockers and worktrees; an issue in someone else's milestone is labelled in <milestone> and stays in Backlog. Filter on needs brainstorm, ready or blocked.

• Ready to start means no issue in the marathon still needs a brainstorm.

• Live: the page updates whenever .spexso/index.json changes — after spexso sync and every skill that syncs.

• Plan: drag a card from Backlog into a marathon, between marathons, or back (keyboard: the grip on a card, Space, arrows, Space). Moving an issue out of someone else's milestone asks first, because an issue has one milestone. Plan a marathon creates spexso/<name> with an optional target date; the × on a marathon closes it (its open issues show in the backlog again). Sync refreshes from GitLab.

• Every change goes through the project's own spexso CLI (node_modules/@flexso/spexso, so npm install must have run): issue update --milestone, milestone create|close, then one spexso sync that updates every open browser. A card moves at once and settles when the sync is in; a failed change puts it back and says why.

• Into Claude: Brainstorm, Start (one issue) and Start marathon send their command into the Claude session that ran /spexso-marathons — the conversation runs there, next to the dashboard. Ctrl K sends any spexso command. The top bar shows whether a session is connected and what it is doing. Without a connected session the buttons copy the command instead.

• Runs: the rail lists past and running marathons. The run screen shows a hero (elapsed, merged/total, commits, tokens, and a € cost only when .spexso/config.json sets pricing), a timeline per issue from the phase notes, tokens by agent and issue, where the work is (main, open MR or local worktree) and the log. Click an issue to focus every tile on it. A running marathon also gets a live tile on the board. Stop writes .spexso/stop through spexso stop (the marathon ends between waves; it does not go through the session, which is busy running the marathon). Needs a spexso with marathon-run (this release) and the observe hooks for timeline and tokens; see Observability.

One server runs per project, on 127.0.0.1 and a random port, recorded in .spexso/dashboard.json. It keeps running after you close the browser or Claude Code; the next /spexso-marathons reuses it. Stop it with node <plugin>/dashboard/dist/server.mjs stop --project .. The server accepts changes only from its own page: every POST needs the x-spexso-dashboard header and a JSON body, and a cross-origin Origin is refused. Only the connected session can read the commands, and only spexso-* commands that session offers can be sent.

Installing

Install spexso-board once from the Flexso plugin marketplace in Claude Code. It then works in every spexso project. The source lives in the plugin-marketplace repo under plugins/spexso-board/, not in spexso. Changes go through a merge request there with a version bump.

The mod reads the .spexso/index.json format that lib/sync.js writes (toIndexEntry, plus the top-level milestones list of open marathons). If you change that shape, update the mod too.

Not included (yet)

• needs::* counts, because the index doesn't store those labels.
• The ship and operate stages.
• Filtering.