figma-use: Instructions file for Codex

Development Guide

Architecture

packages/
  cli/      # Citty-based CLI, 100+ commands
  plugin/   # RPC handlers (built on-demand by CLI via esbuild)

CLI communicates directly with Figma via Chrome DevTools Protocol (CDP). No proxy server, no manual plugin installation.

Build & Test

bun install
bun run build           # Build CLI bundle
bun test                # Run integration tests

# Figma must be running with:
open -a Figma --args --remote-debugging-port=9222

Feature Completion Checklist

When implementing a new feature, ensure ALL of these are done before committing:

1. Implementation

• CLI command in packages/cli/src/commands/
• RPC handler in packages/plugin/src/rpc.ts (if needed)
• Export from packages/cli/src/commands/index.ts

2. Tests

• Add test file in packages/cli/tests/commands/
• Test happy path and edge cases
• Run bun test to verify all tests pass

3. Documentation

• CHANGELOG.md — add entry under ## [Unreleased] or new version section
• README.md — update if it's a user-facing feature
• SKILL.md — update if it changes how agents should use the tool
• REFERENCE.md — update command reference if adding/changing commands

4. Review Before Commit

bun test                        # All tests pass?
bun run build                   # Build succeeds?
git diff                        # Review all changes
git diff --cached               # Review staged changes

Adding Commands

1. Create packages/cli/src/commands/my-command.ts:

import { defineCommand } from 'citty'
import { sendCommand } from '../client.ts'
import { printResult } from '../output.ts'

export default defineCommand({
  meta: { description: 'My command' },
  args: {
    id: { type: 'string', required: true },
    json: { type: 'boolean', description: 'Output as JSON' }
  },
  async run({ args }) {
    const result = await sendCommand('my-command', { id: args.id })
    printResult(result, args.json)
  }
})