Skip to content

Commit 57b6510

Browse files
pomfridapomfrida
authored
chore: add tokens studio agent and cli setup (#5151)
* docs: add tokens studio pipeline agent across harnesses * docs: address review findings in tokens studio agent docs - fix CLI facts against studio-cli 0.1.7: remove nonexistent 'config remove --delete-files', correct exports update/duplicate flags (--clear-config, --new-name), document exports delete --force - align entry-point safety reminders with the canonical rubric and cover shortcut aliases (studio logout) - opencode agent: add git branch/gh asks matching build.md, anchor studio permission globs, cover shortcut alias - drop transient exploration state (test project, work branch) from the snapshot section - trim legacy-pipeline restatement to a pointer at TOKEN_SYSTEM_GUIDE - list /accessibility-audit and /audit-harnesses in CLAUDE.md table - revert unrelated Prettier reformatting of AGENTS.md and HARNESS_AUDIT.md so the diff is additions-only * build: add tokens studio cli as dev dependency of eds-tokens Installs @tokens-studio/studio-cli 0.1.7 and approves its postinstall binary download in onlyBuiltDependencies, so the setup described in documentation/agent-instructions/TOKENS_STUDIO.md works from this branch onwards. * docs: address pr review follow-ups - note in the opencode agent frontmatter that the permission ask-list must track the canonical safety rubric as the CLI grows - drop duplicated npm dist-tags fact from the CLI setup section
1 parent de8a3d9 commit 57b6510

11 files changed

Lines changed: 345 additions & 22 deletions

File tree

‎.claude/CLAUDE.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,9 @@ User-invokable prompts triggered with `/command-name`.
2727
| ----------------------- | ------------------------------------- | -------------------------------------------------------- |
2828
| `/new-component` | `/new-component Button` | Scaffold a new EDS 2.0 component with all required files |
2929
| `/create-component-doc` | `/create-component-doc <raw content>` | Restructure raw content into component documentation |
30+
| `/accessibility-audit` | `/accessibility-audit <url>` | Audit a page or Storybook story against WCAG 2.1 AA |
31+
| `/audit-harnesses` | `/audit-harnesses` | Audit AI harness configs for drift across tools |
32+
| `/tokens-studio` | `/tokens-studio <task>` | Tokens Studio platform / studio CLI pipeline assistant |
3033

3134
## Hooks
3235

‎.claude/commands/tokens-studio.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Tokens Studio Pipeline Assistant
2+
3+
Help with the Tokens Studio platform and `studio` CLI task described in **$ARGUMENTS** — pulling tokens, export configurations, `.studio.json`, auth, branches/releases, or building the new token pipeline.
4+
5+
> **Canonical reference:** [`documentation/agent-instructions/TOKENS_STUDIO.md`](../../documentation/agent-instructions/TOKENS_STUDIO.md) — platform concepts, CLI setup, configuration model, command overview, safety rubric, and how to stay current. The legacy Figma-REST pipeline is documented in [`documentation/how-to/TOKEN_SYSTEM_GUIDE.md`](../../documentation/how-to/TOKEN_SYSTEM_GUIDE.md).
6+
7+
@../../documentation/agent-instructions/TOKENS_STUDIO.md
8+
9+
## Steps
10+
11+
1. Verify before asserting: run `pnpm exec studio <command> --help` from `packages/eds-tokens` for CLI questions, and fetch the relevant `documentation-v2.tokens.studio` page for platform questions — do not answer from memory alone.
12+
2. Classify every command against the safety rubric in the canonical doc before running it. Ask the user before anything the rubric classifies as remote-mutating — shortcut aliases (`studio logout` = `auth logout`) count too. `studio auth login` is interactive — the user runs it themselves.
13+
3. If the installed CLI version differs from the snapshot in the canonical doc, tell the user and offer to regenerate the snapshot section.
14+
15+
If `$ARGUMENTS` is empty, ask what the user wants to do with Tokens Studio before proceeding.

‎.github/prompts/tokens-studio.prompt.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
mode: agent
3+
description: Help with the Tokens Studio platform and studio CLI (pull, exports, config, auth, pipeline)
4+
---
5+
6+
# Tokens Studio Pipeline Assistant
7+
8+
> **Canonical reference:** [`documentation/agent-instructions/TOKENS_STUDIO.md`](../../documentation/agent-instructions/TOKENS_STUDIO.md) — platform concepts, CLI setup, configuration model, command overview, safety rubric, and how to stay current. The legacy Figma-REST pipeline is documented in [`documentation/how-to/TOKEN_SYSTEM_GUIDE.md`](../../documentation/how-to/TOKEN_SYSTEM_GUIDE.md).
9+
10+
Help with the following Tokens Studio task, following the canonical doc above: ${input:task}
11+
12+
## Steps
13+
14+
1. Verify before asserting: run `pnpm exec studio <command> --help` from `packages/eds-tokens` for CLI questions, and fetch the relevant `documentation-v2.tokens.studio` page for platform questions — do not answer from memory alone.
15+
2. Classify every command against the safety rubric in the canonical doc before running it. Ask the user before anything the rubric classifies as remote-mutating — shortcut aliases (`studio logout` = `auth logout`) count too. `studio auth login` is interactive — the user runs it themselves.
16+
3. If the installed CLI version differs from the snapshot in the canonical doc, tell the user and offer to regenerate the snapshot section.

‎.opencode/README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,7 @@ Primary agents are selectable by the user and run as the main conversation agent
5353
|-------|-------------|-------|
5454
| `build` | Development agent with EDS conventions | All (asks for git commit/push/branch) |
5555
| `advisor` | Read-only architectural advice and code reviews | Read-only (no write/edit/bash) |
56+
| `tokens-studio` | Tokens Studio pipeline assistant (studio CLI, pull, exports, config) | All (asks for git commit/push/branch, gh, and remote-mutating studio commands) |
5657

5758
### Sub-Agents
5859

@@ -214,7 +215,8 @@ Refer to AGENTS.md for full conventions.
214215
│ ├── figma-component.md # Sub-agent: Figma-to-code
215216
│ ├── accessibility-audit.md # Sub-agent: A11y auditor
216217
│ ├── component-doc.md # Sub-agent: Documentation
217-
│ └── audit-harnesses.md # Sub-agent: Harness auditor
218+
│ ├── audit-harnesses.md # Sub-agent: Harness auditor
219+
│ └── tokens-studio.md # Primary: Tokens Studio pipeline assistant
218220
```
219221

220222
## Best Practices

‎.opencode/agent/tokens-studio.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
description: Tokens Studio pipeline assistant — studio CLI, pull, exports, config, auth
3+
mode: primary
4+
# The ask-list below must be kept in sync with the safety rubric in
5+
# documentation/agent-instructions/TOKENS_STUDIO.md as the CLI grows —
6+
# with allow-by-default, a new remote-mutating subcommand in a future
7+
# CLI version is auto-approved until it is added here.
8+
permission:
9+
bash:
10+
'*': 'allow'
11+
'git commit*': 'ask'
12+
'git push*': 'ask'
13+
'git checkout -b*': 'ask'
14+
'git branch*': 'ask'
15+
'gh *': 'ask'
16+
'*studio exports create*': 'ask'
17+
'*studio exports update*': 'ask'
18+
'*studio exports delete*': 'ask'
19+
'*studio exports duplicate*': 'ask'
20+
'*studio auth logout*': 'ask'
21+
'*studio logout*': 'ask'
22+
---
23+
24+
You help build and run the Tokens Studio-based token pipeline: the `studio` CLI, `.studio.json` configuration, token pulls, export configurations, authentication, and platform concepts (branches, releases, DTCG).
25+
26+
> **Canonical reference:** [`documentation/agent-instructions/TOKENS_STUDIO.md`](../../documentation/agent-instructions/TOKENS_STUDIO.md) — platform concepts, CLI setup, configuration model, command overview, safety rubric, and how to stay current. The legacy Figma-REST pipeline is documented in [`documentation/how-to/TOKEN_SYSTEM_GUIDE.md`](../../documentation/how-to/TOKEN_SYSTEM_GUIDE.md).
27+
28+
## Flow
29+
30+
1. Verify before asserting: run `pnpm exec studio <command> --help` from `packages/eds-tokens` for CLI questions, and fetch the relevant `documentation-v2.tokens.studio` page for platform questions — do not answer from memory alone.
31+
2. Classify every command against the safety rubric in the canonical doc before running it. Commands that mutate remote state or credentials require explicit user approval — the permission config above backstops the common forms, but shortcut aliases and future commands may not match a glob, so classify against the rubric first. `studio auth login` is interactive — the user runs it themselves.
32+
3. If the installed CLI version differs from the snapshot in the canonical doc, tell the user and offer to regenerate the snapshot section.

‎AGENTS.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -412,6 +412,10 @@ For running an accessibility audit on a deployed page or Storybook story, see [`
412412

413413
Component docs live in `apps/design-system-docs/docs/components/{category}/{component}.md`. For writing or reviewing them — tone of voice, formatting (British English, no em-dashes, admonitions), section order, output template, Storybook iframes workflow, sidebar registration, verification checklist — see [`documentation/agent-instructions/COMPONENT_DOC_STYLE.md`](./documentation/agent-instructions/COMPONENT_DOC_STYLE.md). Harness entry points (`/create-component-doc` in Claude Code, the `structure_components_prompt` / `verify_components_prompt` in Copilot, the `component-doc` agent in OpenCode) all reference that doc.
414414

415+
## Tokens Studio Pipeline
416+
417+
EDS is adopting the Tokens Studio platform as the source for a new token pipeline, replacing the legacy Figma-REST sync over time. For platform concepts (organizations, projects, branches, releases), `studio` CLI setup and commands, the `.studio.json` configuration model, the safety rubric for CLI commands, and how to verify against live sources instead of answering from memory, see [`documentation/agent-instructions/TOKENS_STUDIO.md`](./documentation/agent-instructions/TOKENS_STUDIO.md). Harness entry points (`/tokens-studio` in Claude Code, the `tokens-studio` prompt in Copilot, the `tokens-studio` agent in OpenCode) all reference that doc. The legacy pipeline remains documented in [`documentation/how-to/TOKEN_SYSTEM_GUIDE.md`](./documentation/how-to/TOKEN_SYSTEM_GUIDE.md).
418+
415419
## Conventional Commits
416420

417421
```

‎documentation/agent-instructions/HARNESS_AUDIT.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,7 @@ A developer must not lose access to a workflow by switching harnesses. Build a m
8484
| Structure component doc | `/create-component-doc`| `structure_components_prompt` | `component-doc` agent |
8585
| Verify component doc | (covered by the same) | `verify_components_prompt` | (covered by the same) |
8686
| Re-sync harnesses (this audit) | `/audit-harnesses` | `audit-harnesses` prompt | `audit-harnesses` agent |
87+
| Tokens Studio pipeline | `/tokens-studio` | `tokens-studio` prompt | `tokens-studio` agent |
8788
| Read-only advisor | `.claude/rules/advisor.md` (general scope) | (none) | `advisor` primary agent |
8889

8990
Rows are *intent*, not exact filenames. If the team adds a new workflow, the row should appear in all three harnesses (or be intentionally one-harness with the reason documented). Any gap is a finding.

0 commit comments

Comments
 (0)