chore: add tokens studio agent and cli setup

[pomfrida]

Note

First draft. The Tokens Studio pipeline is still being explored (#5108), so this doc is a starting point, not a finished spec — we will update it as the pipeline work progresses. The dated snapshot section in TOKENS_STUDIO.md is designed to be regenerated whenever the installed CLI version changes.

Why

EDS is adopting the Tokens Studio platform for the new token pipeline (#5108), but the repo had no knowledge of it — the agent instructions only cover the legacy Figma-REST sync. This adds a cross-harness "tokens-studio" assistant so all three harnesses can help with the studio CLI, pulls, exports, and platform concepts, plus the CLI dev dependency itself so the documented setup works out of the box.

What

• documentation/agent-instructions/TOKENS_STUDIO.md — canonical playbook: platform concepts (org/project/branch/release), CLI setup in this repo, .studio.json model, command overview, a safety rubric (safe / overwrites-local / mutates-remote), and a "staying current" section instructing agents to verify against studio --help and the current docs site instead of answering from memory. Every CLI claim is verified against the installed binary (v0.1.7).
• Thin entry points per harness, following the existing canonical-docs pattern:
  • .claude/commands/tokens-studio.md → /tokens-studio
  • .github/prompts/tokens-studio.prompt.md → tokens-studio prompt
  • .opencode/agent/tokens-studio.md → tokens-studio agent (permission config asks before git branch/PR actions and remote-mutating studio commands, matching build.md)
• CLI setup: @tokens-studio/studio-cli as devDependency of eds-tokens + onlyBuiltDependencies approval in pnpm-workspace.yaml (its postinstall downloads the binary) + lockfile.
• Registrations: new section in AGENTS.md, capability-parity row in HARNESS_AUDIT.md, slash-command table in .claude/CLAUDE.md (also adds the previously missing /accessibility-audit and /audit-harnesses rows), agent table in .opencode/README.md.

The devDependency does not affect the published @equinor/eds-tokens artifact.

Review

A ten-finding self-review (CLI fact-check against the binary, cross-harness consistency, content-loss audit of reformatting, conventions/duplication) was applied in the second commit — including removing a nonexistent CLI flag the vendor docs describe but v0.1.7 lacks, and reverting unrelated Prettier reformatting so AGENTS.md/HARNESS_AUDIT.md diffs are additions-only.

[pomfrida]

@claude review

[claude]

Claude finished @pomfrida's task in 2m 24s —— View job

---

Review: docs — Tokens Studio pipeline agent

• Read the changed files
• Review the new canonical doc TOKENS_STUDIO.md
• Review harness entry points (Claude / Copilot / OpenCode)
• Check registrations (AGENTS.md, HARNESS_AUDIT.md, README tables)
• Post review

Nice piece of documentation work. The canonical-doc-plus-thin-entry-points pattern is followed exactly as the existing workflows do it, the safety rubric is thoughtful, and the "staying current / never answer from memory" framing is the right instinct for a fast-moving v0.1.x CLI. I verified the mechanics below; overall this is close to mergeable. A few things worth a look.

---

1. The doc describes the CLI as already installed — but it isn't on this branch (or main)

documentation/agent-instructions/TOKENS_STUDIO.md:26-29 ("CLI setup in this repo") is written in the present tense as established fact, and line 108 states as known repo state: "CLI installed as devDep in packages/eds-tokens, approved in onlyBuiltDependencies". I checked — neither is true on this branch:

grep studio packages/eds-tokens/package.json     → (no match)
onlyBuiltDependencies (pnpm-workspace.yaml)       → no studio entry
.studio.json                                      → not present

The parenthetical on line 108 says exploration lives on the chore/tokens-pipeline branch, which explains it — but the effect is that an agent invoked via /tokens-studio on main and told to run pnpm exec studio <command> --help from packages/eds-tokens (the instruction repeated in all three entry points and in the "staying current" section) will hit studio: command not found, contradicting the doc it was just told to trust.

Suggest scoping the present-tense claims so they don't read as "true on the default branch today" — e.g. "The CLI is being added as a devDependency of packages/eds-tokens on the chore/tokens-pipeline branch; once that lands, run it via pnpm exec studio…". The safety-rubric and platform-concept sections are fine as-is; it's only the "installed here now" framing that's ahead of reality. Fix this →

2. OpenCode permission default lets future remote-mutating commands through

.opencode/agent/tokens-studio.md:5-14 sets bash: '*': 'allow' and then enumerates the remote-mutating subcommands to ask. That covers today's surface well. But the canonical doc's own rubric (TOKENS_STUDIO.md:80) says to "treat a command as remote-mutating until --help proves otherwise" and calls out "any push-like or write-scoped command that appears in future CLI versions" — and with an allow-by-default base, a new destructive subcommand in a future CLI release would be auto-approved, not caught. The prose instruction (step 2) mitigates it, but the enforced config quietly diverges from the doc's stated posture. Worth a comment in the frontmatter noting the ask-list must be kept in sync as the CLI grows, or considering a tighter default for the studio binary specifically.

3. Minor

• Working-tree artifact (not your change): the checkout here has .claude/commands/tokens-studio.md showing as deleted in git status, but the committed blob in HEAD is correct and complete — this is a checkout artifact of the action env, not something in your PR. Flagging only so it isn't mistaken for a missing file.
• TOKENS_STUDIO.md:30 ("npm dist-tags: latest plus an rc channel") duplicates the same fact at line 89 in the version-check step. Harmless, could drop one.
• .opencode/README.md:218 inserts tokens-studio.md into the file tree with a # Primary: comment among entries otherwise labelled # Sub-agent:. The comment disambiguates it, and it's correctly in the Primary-agents table above (mode: primary matches advisor.md), so this is purely cosmetic.

Verified good ✓

• All cross-references resolve (TOKEN_SYSTEM_GUIDE.md, HARNESS_AUDIT.md); relative link depths from .claude/commands/, .opencode/agent/, .github/prompts/ all correct.
• Harness conventions match siblings: Copilot mode: agent + .prompt.md, OpenCode mode: primary, Claude command @-import.
• Registrations are complete and consistent — new row in the HARNESS_AUDIT.md capability-parity matrix, AGENTS.md section, .claude/CLAUDE.md slash-command table, .opencode/README.md table.
• The large AGENTS.md / HARNESS_AUDIT.md diffs are exactly what the PR body claims: Prettier table re-alignment plus _italic_/*italic* normalisation. No behavioural content changed.
• Docs/config only — no publishable package files touched, so no release-please impact; docs: type with no scope is correct per the repo's conventional-commits guidance.
  · docs/tokens-studio-agent