Reading OpenSpec state from outside the CLI (a handoff tool): what I rely on, and what I hope stays stable

[ECG-Rudy-Glt]

The problem I kept hitting. I work alone on about sixteen repositories, with several coding agents, and Relai itself is developed with
OpenSpec. Every new agent session started the same way:

• it re-reads the repo to find out where things stand, which is most of the cost (a single claude -p call is already about 29k tokens before it
  reads anything of yours);
• what it reads can be stale: specs and checklists say "to do" for finished work, and an agent that trusts them works on the wrong thing (your
  thread "How do you keep specs aligned with the code after implementation?" is the same worry);
• it cannot see what the other repos already provide, so it rebuilds it;
• and with parallel agents, nothing stops two from starting the same task.

What Relai does about it. A small open-source CLI (Go, one binary, no server, only git), plus an optional board:

• relai handoff: the state of one repo in a few hundred tokens, generated from files (not by an LLM): branch, recent commits, open tasks, the
  active OpenSpec changes with progress and the next unchecked task, decisions and pitfalls from a notes file.
• relai workspace: one page for every project in a folder, about 400 tokens for my 16 repos. A repo's git worktrees count as one project.
• A tiny relai.yaml per repo and relai find <capability> to check whether another project already provides something; relai discover
  proposes links between repos and a person confirms them.
• relai tidy: closes a task only when a commit on the default branch says "Closes ", never on a guess.
• RELAI-TEAM, separate and optional (self-hosted): a board over several repos reading the same files; each person or agent claims a task so
  two never start the same one. It speaks MCP. Relai never needs it.

How it reads OpenSpec (it only reads; it never writes to openspec/):

1. openspec list --json for the active changes (name, completedTasks, totalTasks, status);
2. openspec/changes/<name>/tasks.md directly: the - [ ] / - [x] lines as progress, the first unchecked one as "next";
3. openspec/changes/archive/ as "not active". When the openspec binary is missing or fails, it lists the changes from files and says so,
   instead of printing "no changes".

Two questions I could not answer from the docs.

• Are the checkbox format of tasks.md and the JSON shape of openspec list --json meant to be stable, or would you prefer another entry
  point? A versioned "next task of each active change" from the CLI would let me stop parsing Markdown.
• For several repos side by side I only added a tiny relai.yaml (id, summary, optional provides / consumes / links). If you have a
  convention for linking specs across repos, I would rather follow it than invent one.

Honest limits. I use it alone; nobody has tested it with several humans. Agents tested: Claude only, n=1 per case. On my 16 real repos the
overview plus handoff saved a median of roughly 100k tokens per task, and one case cost more. The optional board also reads Beads and plain TODO.md checklists.

Relai: https://github.com/ECG-Rudy-Glt/RELAI · RELAI-TEAM (optional board): https://github.com/ECG-Rudy-Glt/RELAI-TEAM