Skip to content

Commit 345b6f8

Browse files
eddimaneddiman
authored
chore(eds-core-react): add AI agent configuration files (#4373)
* chore(eds-core-react): add AI agent configuration files Add AGENTS.md and OpenCode agent definitions for AI-assisted development. * chore: update build agent to only ask for commit, push, and branch * docs: add OpenCode agents README with structure and usage guide * docs: fix agent usage instructions in OpenCode README
1 parent 267b8f4 commit 345b6f8

6 files changed

Lines changed: 675 additions & 0 deletions

File tree

‎.opencode/README.md‎

Lines changed: 223 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,223 @@
1+
# OpenCode Agents - Equinor Design System
2+
3+
This directory contains custom AI agent configurations for OpenCode in the EDS repository.
4+
5+
## Global Configuration
6+
7+
The root `AGENTS.md` file provides **global instructions** for all AI coding tools (OpenCode, Claude Code, Cursor, GitHub Copilot). It contains repository-wide conventions that apply regardless of which agent or tool is used.
8+
9+
The `.opencode/` directory contains **OpenCode-specific** agent definitions that build on top of the global instructions.
10+
11+
## Planning Mode
12+
13+
OpenCode has a **planning mode** that can be toggled with `Ctrl+L` (or `Cmd+L` on Mac). When enabled:
14+
15+
- The agent analyzes the task before making changes
16+
- Creates a structured plan with steps
17+
- Useful for complex, multi-file changes
18+
- Helps ensure all requirements are considered upfront
19+
20+
Use planning mode for larger features or refactors. Skip it for quick fixes or simple changes.
21+
22+
## Instruction Pipeline
23+
24+
OpenCode agents receive instructions from multiple sources, applied in this order:
25+
26+
```
27+
┌─────────────────────────────────────┐
28+
│ OpenCode Base Model │
29+
└─────────────────┬───────────────────┘
30+
│
31+
┌─────────────────▼───────────────────┐
32+
│ AGENTS.md │ ← Repository conventions
33+
└─────────────────┬───────────────────┘
34+
│
35+
┌─────────────────▼───────────────────┐
36+
│ .opencode/agent/<name>.md │ ← Agent-specific behavior
37+
└─────────────────┬───────────────────┘
38+
│
39+
┌─────────────────▼───────────────────┐
40+
│ .github/instructions/*.md │ ← File-pattern instructions
41+
└─────────────────────────────────────┘
42+
```
43+
44+
1. **Global instructions** - Built into OpenCode (base capabilities)
45+
2. **AGENTS.md** - Repository-level guidance for all AI tools
46+
3. **Agent-specific instructions** - `.opencode/agent/*.md` files define agent behavior
47+
4. **GitHub instructions** - `.github/instructions/*.md` applied by file pattern (e.g., `*.tsx` files get React instructions)
48+
49+
## Agent Types
50+
51+
### Primary Agents
52+
53+
Primary agents are selectable by the user and run as the main conversation agent.
54+
55+
| Agent | Description | Tools |
56+
|-------|-------------|-------|
57+
| `build` | Development agent with EDS conventions | All (asks for git commit/push/branch) |
58+
| `advisor` | Read-only architectural advice and code reviews | Read-only (no write/edit/bash) |
59+
60+
### Sub-Agents
61+
62+
Sub-agents are invoked by primary agents to perform specialized tasks. They cannot be selected directly, but must be mentioned in chat.
63+
64+
| Agent | Description | Tools |
65+
|-------|-------------|-------|
66+
| `eds-component` | Builds EDS 2.0 React components following conventions | write, edit, bash |
67+
| `figma-component` | Builds components from Figma designs with MCP token extraction | write, edit, bash |
68+
69+
## Agent Configuration
70+
71+
Each agent is defined in a markdown file in `.opencode/agent/` with YAML frontmatter:
72+
73+
```markdown
74+
---
75+
description: Short description shown in agent picker
76+
mode: primary | subagent
77+
tools:
78+
write: true | false
79+
edit: true | false
80+
bash: true | false
81+
permission:
82+
bash:
83+
'*': 'allow' | 'ask' | 'deny'
84+
'git commit*': 'ask'
85+
---
86+
87+
Agent-specific instructions go here...
88+
```
89+
90+
### Frontmatter Options
91+
92+
| Field | Description |
93+
|-------|-------------|
94+
| `description` | Shown in the agent picker UI |
95+
| `mode` | `primary` (user-selectable) or `subagent` (invoked programmatically) |
96+
| `tools` | Enable/disable tool access (write, edit, bash) |
97+
| `permission.bash` | Fine-grained bash command permissions with glob patterns |
98+
99+
### Permission Patterns
100+
101+
Control which bash commands require user approval:
102+
103+
```yaml
104+
permission:
105+
bash:
106+
'*': 'allow' # Allow all commands by default
107+
'git commit*': 'ask' # Ask before committing
108+
'git push*': 'ask' # Ask before pushing
109+
'git checkout -b*': 'ask' # Ask before creating branches
110+
'rm -rf*': 'deny' # Never allow destructive commands
111+
```
112+
113+
## Using Agents
114+
115+
### Selecting a Primary Agent
116+
117+
Press `Tab` to cycle through available primary agents. The current agent is shown in the input area.
118+
119+
### Invoking Sub-Agents
120+
121+
Sub-agents are specialized agents that handle specific tasks. Mention them with `@` to invoke:
122+
123+
```
124+
@figma-component build the Button component from this Figma link
125+
```
126+
127+
```
128+
@eds-component create a new Tooltip component
129+
```
130+
131+
When a sub-agent is invoked:
132+
1. It receives the task with its specialized instructions
133+
2. Executes with its configured tools
134+
3. Returns results back to the conversation
135+
136+
## MCP Integration
137+
138+
Some agents use [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers to access external tools. The `figma-component` agent uses Figma MCP tools:
139+
140+
| MCP Tool | Purpose |
141+
|----------|---------|
142+
| `figma_get_design_context` | Analyze component structure and layers |
143+
| `figma_get_screenshot` | Get visual reference of the design |
144+
| `figma_get_variable_defs` | Extract design tokens for each component state |
145+
146+
### MCP Workflow Example
147+
148+
```
149+
1. figma_get_design_context → Understand component structure
150+
2. figma_get_screenshot → Visual reference
151+
3. figma_get_variable_defs (Default state) → Base tokens
152+
4. figma_get_variable_defs (Hover state) → Hover tokens
153+
5. figma_get_variable_defs (Focus state) → Focus tokens
154+
6. figma_get_variable_defs (Disabled state) → Disabled tokens
155+
```
156+
157+
MCP servers are configured globally in OpenCode settings, not in this repository.
158+
159+
## Creating New Agents
160+
161+
1. Create a new file in `.opencode/agent/` with a `.md` extension
162+
2. Add YAML frontmatter with required fields
163+
3. Write agent-specific instructions in markdown
164+
4. Reference `AGENTS.md` for shared conventions
165+
166+
### Example: Test Runner Agent
167+
168+
```markdown
169+
---
170+
description: Writes and runs tests for EDS components
171+
mode: subagent
172+
tools:
173+
write: true
174+
edit: true
175+
bash: true
176+
---
177+
178+
You write tests for EDS components in `packages/eds-core-react/src/components/next/`.
179+
180+
## Test Structure
181+
182+
- Use Jest + Testing Library + jest-axe
183+
- Organize with describe blocks: Rendering, Accessibility, Behavior
184+
- Query priority: getByRole > getByLabelText > getByText > getByTestId
185+
186+
## Commands
187+
188+
\`\`\`bash
189+
pnpm run test:core-react # Run all tests
190+
pnpm test -- --testPathPattern="Name" # Run specific test
191+
\`\`\`
192+
193+
Refer to AGENTS.md for full conventions.
194+
```
195+
196+
## Relationship to Other Instruction Files
197+
198+
| File | Purpose | Scope |
199+
|------|---------|-------|
200+
| `AGENTS.md` | General AI agent guidance | All AI tools (Copilot, OpenCode, Claude) |
201+
| `.github/copilot-instructions.md` | GitHub Copilot hub | GitHub Copilot |
202+
| `.github/instructions/*.md` | File-pattern specific rules | GitHub Copilot (by `applyTo` pattern) |
203+
| `.opencode/agent/*.md` | OpenCode agent definitions | OpenCode only |
204+
205+
## Directory Structure
206+
207+
```
208+
.opencode/
209+
├── README.md # This file
210+
├── agent/
211+
│ ├── build.md # Primary: Development agent
212+
│ ├── advisor.md # Primary: Read-only advisor
213+
│ ├── eds-component.md # Sub-agent: Component builder
214+
│ └── figma-component.md # Sub-agent: Figma-to-code
215+
```
216+
217+
## Best Practices
218+
219+
1. **Keep agents focused** - Each agent should have a clear, single responsibility
220+
2. **Use sub-agents for specialization** - Complex workflows delegate to specialized sub-agents
221+
3. **Reference shared docs** - Point to `AGENTS.md` for common conventions instead of duplicating
222+
4. **Minimize permissions** - Only enable tools the agent actually needs
223+
5. **Be specific about MCP tools** - Document which MCP tools an agent expects to use

‎.opencode/agent/advisor.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
description: Provides architectural advice and code reviews for EDS without making changes
3+
mode: primary
4+
tools:
5+
write: false
6+
edit: false
7+
bash: false
8+
---
9+
10+
You are an advisor for the Equinor Design System (EDS) repository. You provide guidance without modifying files.
11+
12+
## Your Role
13+
14+
- Review code and suggest improvements
15+
- Discuss architectural decisions
16+
- Advise on component API design
17+
- Help plan new features or refactors
18+
- Answer questions about EDS patterns and conventions
19+
20+
## EDS Context
21+
22+
This is a pnpm monorepo with React component libraries. New components are developed in `/next` (`packages/eds-core-react/src/components/next/`).
23+
24+
Key packages:
25+
26+
- `@equinor/eds-core-react` - Main React component library
27+
- `@equinor/eds-core-react/next` - EDS 2.0 components (active development)
28+
- `@equinor/eds-tokens` - Design tokens and CSS variables
29+
- `@equinor/eds-icons` - Icon library
30+
31+
## Standards to Advise On
32+
33+
- WCAG 2.1 AA accessibility compliance
34+
- Vanilla CSS with BEM + `--eds-*` design tokens
35+
- Named exports only (no default exports except stories)
36+
- `forwardRef` pattern for components
37+
- Jest + Testing Library + jest-axe for tests
38+
- Conventional commits: `type(scope): description`
39+
40+
## When Reviewing
41+
42+
Focus on:
43+
44+
- Accessibility considerations
45+
- API design and prop naming
46+
- Consistency with existing EDS patterns
47+
- Performance implications
48+
- Test coverage suggestions
49+
50+
Refer to `AGENTS.md` and `.github/copilot-instructions.md` for detailed conventions.

‎.opencode/agent/build.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
description: Primary development agent with EDS conventions
3+
mode: primary
4+
permission:
5+
bash:
6+
'*': 'allow'
7+
'git commit*': 'ask'
8+
'git push*': 'ask'
9+
'git checkout -b*': 'ask'
10+
'git branch*': 'ask'
11+
'gh *': 'ask'
12+
---
13+
14+
You are a developer working on the Equinor Design System.
15+
16+
Follow AGENTS.md for conventions.

‎.opencode/agent/eds-component.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
---
2+
description: Builds EDS 2.0 React components in /next following project conventions
3+
mode: subagent
4+
tools:
5+
write: true
6+
edit: true
7+
bash: true
8+
---
9+
10+
You build EDS 2.0 components in `packages/eds-core-react/src/components/next/`.
11+
12+
## File Structure
13+
14+
```
15+
ComponentName/
16+
index.ts # Named exports only
17+
ComponentName.tsx # forwardRef component
18+
ComponentName.types.ts # Types with JSDoc
19+
componentname.css # Vanilla CSS + BEM + tokens
20+
ComponentName.test.tsx # Jest + Testing Library + jest-axe
21+
ComponentName.stories.tsx
22+
```
23+
24+
## Component Pattern
25+
26+
```typescript
27+
import { forwardRef, useId } from 'react'
28+
import type { ComponentProps } from './Component.types'
29+
import './component.css'
30+
31+
export const Component = forwardRef<HTMLElement, ComponentProps>(
32+
function Component({ className, ...rest }, ref) {
33+
const classes = ['component', className].filter(Boolean).join(' ')
34+
return <div ref={ref} className={classes} {...rest} />
35+
},
36+
)
37+
```
38+
39+
## Types Pattern
40+
41+
```typescript
42+
export type ComponentProps = {
43+
/** Description for prop */
44+
variant?: 'primary' | 'secondary'
45+
} & HTMLAttributes<HTMLElement>
46+
```
47+
48+
## CSS Pattern
49+
50+
```css
51+
.component {
52+
color: var(--eds-color-text-primary);
53+
}
54+
.component[data-variant='secondary'] {
55+
color: var(--eds-color-text-secondary);
56+
}
57+
```
58+
59+
## Test Pattern
60+
61+
Organize with `describe` blocks: Rendering, Accessibility, Behavior.
62+
63+
```typescript
64+
import { render, screen } from '@testing-library/react'
65+
import { axe } from 'jest-axe'
66+
import { Component } from '.'
67+
68+
describe('Component (next)', () => {
69+
describe('Accessibility', () => {
70+
it('passes axe', async () => {
71+
const { container } = render(<Component />)
72+
expect(await axe(container)).toHaveNoViolations()
73+
})
74+
})
75+
})
76+
```
77+
78+
## Rules
79+
80+
- No default exports (except stories)
81+
- WCAG 2.1 AA required
82+
- Use `--eds-*` design tokens
83+
- Query priority: getByRole > getByLabelText > getByText > getByTestId

0 commit comments

Comments
 (0)