agent-orchestrator-kit 0.1.10 → 0.1.11

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to this project will be documented in this file.
 
+## [Unreleased]
+
+## [0.1.11] - 2026-07-21
+
+### Added
+- **Figma personal token setup** — local `.agents/figma.local.env` (gitignored) + committed `.agents/figma.local.env.example`
+- **`scripts/figma-mcp-launcher.cjs`** — starts `figma-developer-mcp` with token from the env file (no secret in `.mcp.json`)
+- **CLI** — `figma-setup`, `figma-status`, `figma-fetch` (REST file/nodes JSON via `X-Figma-Token`)
+- Cursor/Amp MCP examples include optional `figma` server pointing at the launcher
+- Agent rule `figma-token-setup.mdc`; setup-doctor + `/opsx:design` guidance (never ask for token in chat)
+- `orchestrator.yaml` / profiles: `mcp.optional` includes `figma` + `figma.env_file` metadata
+
+### Fixed
+- **Amp / agent PATH** — templates now document and require `npx` / `npm run` for OpenSpec and `agent-orchestrator-kit` CLIs (bare binaries often exit 127 in Amp shells)
+- Added always-apply rule `templates/.agents/rules/cli-via-npm.mdc`; updated openspec skills/commands, `AGENTS.md`, `CLAUDE.md`, `orchestrator.yaml` `cli.*` hints
+- Never recommend `openspec validate --strict` without `<name>` / `--all`
+
 ## [0.1.10] - 2026-07-15
 
 ### Added

package/README.md

@@ -15,6 +15,8 @@ explore → [design] → propose → review → apply → verify → archive
 
 Each role runs in a **separate agent session** with dedicated permissions, model hints, and handoff gates. The `openspec/changes/` folder acts as the **contract between agents** — no shared memory between sessions, only files.
 
+**Figma PAT setup (v0.1.11+)** — local `.agents/figma.local.env` + MCP launcher (token never in chat / committed MCP JSON). See [Figma token](#figma-token-optional).
+
 **Custom subagents (v0.1.10+)** ship with the kit and work in all three IDEs:
 
 | Subagent | Role |
@@ -53,11 +55,12 @@ npx agent-orchestrator-kit@latest init --profile generic --ci gitlab --spec-veri
 
 See [Installation](#installation) for profile/CI options.
 
-**🔄 Already have the kit installed? Upgrade to latest (subagents in v0.1.10+):**
+**🔄 Already have the kit installed? Upgrade to latest (Figma PAT in v0.1.11+, subagents in v0.1.10+):**
 
 ```bash
 npx agent-orchestrator-kit@latest update
 npx agent-orchestrator-kit@latest sync         # or: ./scripts/sync-local-agent-skills.sh
+npx agent-orchestrator-kit@latest figma-setup  # optional — local Figma token
 npx agent-orchestrator-kit@latest status
 ```
 
@@ -167,7 +170,7 @@ your-project/
 | OpenSpec skills | All 7 skills for `/opsx:*` workflow |
 | IDE sync | Cursor + Claude Code sync script (`--delete` semantics — removes stale skills/subagents) |
 | Subagents | `openspec-guide`, `code-writer`, `code-reviewer`, `test-writer`, `setup-doctor`, `design-implementer` — native in Cursor (`.cursor/agents/`) + Claude Code (`.claude/agents/`), exposed to Amp as auto-generated `subagent-*` skill wrappers in `.agents/skills/` |
-| CLI gates | `agent-orchestrator status` / `gate-check` — deterministic review-gate checks |
+| CLI gates | `npx agent-orchestrator-kit status` / `gate-check` — deterministic review-gate checks (always via `npx`; see `cli-via-npm.mdc`) |
 | CI | `agent-verify.yml` — GitHub (default) or GitLab fragment + `prebuild` hook, both run `gate-check` |
 | AI Spec Verifier | `spec-verify.yml` + verifier scripts — GitLab or GitHub, opt-in (`--spec-verify`) |
 | MCP templates | Memory MCP for Cursor and Amp |
@@ -190,6 +193,8 @@ Local only (not committed): `.cursor/` `.claude/` `.amp/`
 
 Amp reads `.agents/skills/` and `AGENTS.md` **natively** — no sync needed.
 
+**CLI note:** Amp shells often lack global `openspec` / `agent-orchestrator-kit` on PATH (exit 127). Agents must use `npx …` / `npm run …` — see always-apply rule `.agents/rules/cli-via-npm.mdc`.
+
 1. Install the kit → `AGENTS.md` is created automatically.
 2. Amp picks up skills from `.agents/skills/` on session start.
 3. Copy Amp MCP config (on first sync):
@@ -262,7 +267,7 @@ You can add `context: fork` to explore/review skills for isolated subagent sessi
 3. Rules are applied automatically per `alwaysApply: true`.
 4. Subagents are invoked by name in chat (e.g. "use the code-reviewer subagent on this diff") or delegated to automatically by Cursor when their `description` matches the task. Add project-specific subagents by dropping `.md` files into `.agents/subagents/` and re-running sync.
 
-**Memory MCP for Cursor** (`.mcp.json`):
+**Memory + optional Figma MCP for Cursor** (`.mcp.json`):
 
 ```json
 {
@@ -271,11 +276,17 @@ You can add `context: fork` to explore/review skills for isolated subagent sessi
       "command": "npx",
       "args": ["-y", "@modelcontextprotocol/server-memory"],
       "env": { "MEMORY_FILE_PATH": ".cursor/memory.json" }
+    },
+    "figma": {
+      "command": "node",
+      "args": ["scripts/figma-mcp-launcher.cjs"]
     }
   }
 }
 ```
 
+Token lives in `.agents/figma.local.env` — see [Figma token](#figma-token-optional).
+
 ## The Pipeline in Detail
 
 ### Role 1: Explorer — `/opsx:explore`
@@ -304,7 +315,7 @@ You can add `context: fork` to explore/review skills for isolated subagent sessi
 
 **Exit gate:**
 ```bash
-openspec validate <name> --strict --type change  # must be ✓
+npx openspec validate <name> --strict --type change  # must be ✓
 ```
 
 ```
@@ -582,6 +593,49 @@ npx frontend-agent-skills install --agent all --yes
 
 > **Migrating from `vue-cursor-skills`?** Renamed to `frontend-agent-skills` v2 — same package, old CLI alias still works.
 
+## Figma token (optional)
+
+Personal Access Token for design intake (`/opsx:design`) and the optional Framelink `figma-developer-mcp` server. **Never paste the token into AI chat.**
+
+### Setup (each developer, once)
+
+```bash
+npx agent-orchestrator-kit figma-setup
+# open .agents/figma.local.env in the IDE and set:
+# FIGMA_ACCESS_TOKEN=figd_...
+npx agent-orchestrator-kit figma-status
+```
+
+Then restart Cursor / Amp.
+
+| Path | Purpose | Git |
+|------|---------|-----|
+| `.agents/figma.local.env` | Your token (`FIGMA_ACCESS_TOKEN`) | **ignored** |
+| `.agents/figma.local.env.example` | Template | committed |
+| `scripts/figma-mcp-launcher.cjs` | Starts MCP with token from the env file | committed |
+| `.mcp.json` → `figma` | Points at the launcher (no secret inline) | committed OK |
+
+Create a token: Figma → Settings → Security → Personal access tokens (file content read as needed).
+
+### CLI
+
+```bash
+npx agent-orchestrator-kit figma-setup
+npx agent-orchestrator-kit figma-status
+npx agent-orchestrator-kit figma-fetch --url "https://www.figma.com/design/FILE_KEY/Name?node-id=1-2" \
+  --out openspec/changes/<name>/assets/figma-nodes.json
+```
+
+`figma-fetch` uses the Figma REST API (`X-Figma-Token`) and writes JSON for design-brief capture. Live Figma is for design-intake only — apply uses `design-brief.md`.
+
+### Upgrade existing projects
+
+```bash
+npx agent-orchestrator-kit@latest update
+npx agent-orchestrator-kit figma-setup
+./scripts/sync-local-agent-skills.sh
+```
+
 ## Memory MCP — Shared State Between Sessions
 
 Each role starts a fresh session. Memory MCP persists orchestration state across sessions so you don't re-explain context every time.
@@ -699,6 +753,12 @@ openspec/                # Committed — spec-driven workflow
 
 ## Changelog
 
+### 0.1.11
+- Optional **Figma personal token** setup: `.agents/figma.local.env` (gitignored) + `figma-mcp-launcher.cjs` (no secret in `.mcp.json`)
+- CLI: `figma-setup`, `figma-status`, `figma-fetch` (REST nodes/file JSON)
+- Agent rule + docs: never paste Figma tokens into chat
+- Amp PATH hardening: prefer `npx` / `npm run` for OpenSpec and kit CLIs (`cli-via-npm` rule)
+
 ### 0.1.10
 - Custom subagents (`.agents/subagents/`) synced to `.cursor/agents/` + `.claude/agents/`, exposed to Amp via auto-generated `subagent-*` skill wrappers
 - 6 default subagents: `openspec-guide`, `code-writer`, `code-reviewer`, `test-writer`, `setup-doctor`, `design-implementer`

package/bin/agent-orchestrator.js

@@ -60,7 +60,23 @@ function specVerifyPathsFor(ci) {
 const VALID_CI_PROVIDERS = ['gitlab', 'github', 'none'];
 const VERIFY_OPENSPEC_SCRIPT = 'npx openspec validate --all --strict';
 
-const GITIGNORE_LINES = ['.cursor', '.cursor/memory.json', '.amp/settings.json', '.claude'];
+const GITIGNORE_LINES = [
+  '.cursor',
+  '.cursor/memory.json',
+  '.amp/settings.json',
+  '.claude',
+  '.agents/figma.local.env',
+];
+
+const FIGMA_ENV_REL = join('.agents', 'figma.local.env');
+const FIGMA_ENV_EXAMPLE_REL = join('.agents', 'figma.local.env.example');
+const FIGMA_LAUNCHER_REL = join('scripts', 'figma-mcp-launcher.cjs');
+const FIGMA_MANAGED_PATHS = [
+  FIGMA_ENV_EXAMPLE_REL,
+  FIGMA_LAUNCHER_REL,
+  join('.agents', 'mcp.json.example'),
+  join('.agents', 'amp.settings.json.example'),
+];
 
 const log = {
   info: (msg) => console.log(pc.cyan('  →'), msg),
@@ -118,6 +134,141 @@ function mergeGitignore(projectDir, lines) {
   log.ok('.gitignore updated');
 }
 
+function parseEnvFile(filePath) {
+  if (!existsSync(filePath)) return {};
+  const values = {};
+  for (const line of readFileSync(filePath, 'utf-8').split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eq = trimmed.indexOf('=');
+    if (eq === -1) continue;
+    const key = trimmed.slice(0, eq).trim();
+    let value = trimmed.slice(eq + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    values[key] = value;
+  }
+  return values;
+}
+
+function readFigmaToken(projectDir) {
+  const envPath = join(projectDir, FIGMA_ENV_REL);
+  const values = parseEnvFile(envPath);
+  return values.FIGMA_ACCESS_TOKEN || values.FIGMA_API_KEY || '';
+}
+
+function isFigmaConfigured(projectDir) {
+  return Boolean(readFigmaToken(projectDir));
+}
+
+function ensureFigmaEnvFile(projectDir) {
+  const dest = join(projectDir, FIGMA_ENV_REL);
+  const example = join(projectDir, FIGMA_ENV_EXAMPLE_REL);
+  const kitExample = join(KIT_ROOT, 'templates', FIGMA_ENV_EXAMPLE_REL);
+
+  if (existsSync(dest)) {
+    return { created: false, path: dest };
+  }
+
+  const src = existsSync(example) ? example : kitExample;
+  if (!existsSync(src)) {
+    throw new Error(`Missing template: ${FIGMA_ENV_EXAMPLE_REL}`);
+  }
+
+  mkdirSync(dirname(dest), { recursive: true });
+  copyFileSync(src, dest);
+  return { created: true, path: dest };
+}
+
+function refreshFigmaManagedFiles(projectDir) {
+  const templateDir = join(KIT_ROOT, 'templates');
+  for (const rel of FIGMA_MANAGED_PATHS) {
+    const src = join(templateDir, rel);
+    const dest = join(projectDir, rel);
+    if (!existsSync(src)) continue;
+    mkdirSync(dirname(dest), { recursive: true });
+    copyFileSync(src, dest);
+    log.ok(rel);
+  }
+}
+
+function ensureFigmaMcpEntry(projectDir) {
+  const figmaServer = {
+    command: 'node',
+    args: ['scripts/figma-mcp-launcher.cjs'],
+  };
+
+  const cursorPath = join(projectDir, '.mcp.json');
+  if (existsSync(cursorPath)) {
+    try {
+      const cfg = JSON.parse(readFileSync(cursorPath, 'utf-8'));
+      cfg.mcpServers = cfg.mcpServers || {};
+      if (!cfg.mcpServers.figma) {
+        cfg.mcpServers.figma = figmaServer;
+        writeFileSync(cursorPath, `${JSON.stringify(cfg, null, 2)}\n`);
+        log.ok('.mcp.json ← added figma server');
+      } else {
+        log.ok('.mcp.json already has figma server');
+      }
+    } catch {
+      log.warn('.mcp.json present but invalid JSON — merge figma server manually from .agents/mcp.json.example');
+    }
+  }
+
+  const ampPath = join(projectDir, '.amp', 'settings.json');
+  if (existsSync(ampPath)) {
+    try {
+      const cfg = JSON.parse(readFileSync(ampPath, 'utf-8'));
+      cfg['amp.mcpServers'] = cfg['amp.mcpServers'] || {};
+      if (!cfg['amp.mcpServers'].figma) {
+        cfg['amp.mcpServers'].figma = figmaServer;
+        writeFileSync(ampPath, `${JSON.stringify(cfg, null, 2)}\n`);
+        log.ok('.amp/settings.json ← added figma server');
+      } else {
+        log.ok('.amp/settings.json already has figma server');
+      }
+    } catch {
+      log.warn('.amp/settings.json present but invalid JSON — merge figma server manually');
+    }
+  }
+}
+
+function parseFigmaUrl(url) {
+  try {
+    const parsed = new URL(url);
+    const parts = parsed.pathname.split('/').filter(Boolean);
+    const designIdx = parts.findIndex((p) => p === 'design' || p === 'file' || p === 'proto');
+    const fileKey = designIdx >= 0 ? parts[designIdx + 1] : '';
+    const nodeParam = parsed.searchParams.get('node-id') || '';
+    const nodeId = nodeParam ? nodeParam.replace(/-/g, ':') : '';
+    return { fileKey, nodeId };
+  } catch {
+    return { fileKey: '', nodeId: '' };
+  }
+}
+
+async function figmaApiGet(token, path) {
+  const response = await fetch(`https://api.figma.com/v1${path}`, {
+    headers: { 'X-Figma-Token': token },
+  });
+  const text = await response.text();
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    data = { err: text };
+  }
+  if (!response.ok) {
+    const message = data?.err || data?.message || response.statusText || `HTTP ${response.status}`;
+    throw new Error(String(message));
+  }
+  return data;
+}
+
 function resolveTemplate(templateName, profile) {
   const profilePath = join(KIT_ROOT, 'profiles', profile, templateName);
   if (existsSync(profilePath)) return profilePath;
@@ -406,14 +557,17 @@ function printNextSteps(profile, projectDir, ci = 'github', specVerify = false)
     lines.push(`  3. Install Vue/JS stack skills:`);
     lines.push(`     ${pc.cyan('npx frontend-agent-skills install --agent all --yes')}`);
     lines.push(`  4. MCP: copy .mcp.json (Cursor) / .amp/settings.json (Amp) from *.example files`);
-    lines.push(`  5. Start your first change:`);
+    lines.push(`  5. Optional Figma: ${pc.cyan('npx agent-orchestrator-kit figma-setup')} then paste token into ${pc.cyan('.agents/figma.local.env')} (never in chat)`);
+    lines.push(`  6. Start your first change:`);
   } else if (profile === 'mvp') {
     lines.push(`  3. For quick demos use ${pc.cyan('/opsx:quick <name>')} (propose + apply, no review gate)`);
     lines.push(`  4. MCP: copy .mcp.json (Cursor) / .amp/settings.json (Amp) from *.example files`);
-    lines.push(`  5. Start exploring:`);
+    lines.push(`  5. Optional Figma: ${pc.cyan('npx agent-orchestrator-kit figma-setup')} then paste token into ${pc.cyan('.agents/figma.local.env')} (never in chat)`);
+    lines.push(`  6. Start exploring:`);
   } else {
     lines.push(`  3. MCP: copy .mcp.json (Cursor) / .amp/settings.json (Amp) from *.example files`);
-    lines.push(`  4. Start your first change:`);
+    lines.push(`  4. Optional Figma: ${pc.cyan('npx agent-orchestrator-kit figma-setup')} then paste token into ${pc.cyan('.agents/figma.local.env')} (never in chat)`);
+    lines.push(`  5. Start your first change:`);
   }
 
   const startCmd = profile === 'mvp' ? '/opsx:quick' : '/opsx:explore';
@@ -663,8 +817,13 @@ program
       execSync(`chmod +x ${join(projectDir, 'scripts', 'sync-local-agent-skills.sh')}`);
     } catch {}
 
+    log.title('Refreshing Figma setup templates');
+    refreshFigmaManagedFiles(projectDir);
+    mergeGitignore(projectDir, GITIGNORE_LINES);
+
     log.ok(`Updated to v${KIT_VERSION}`);
     log.info('Run ./scripts/sync-local-agent-skills.sh to sync to local IDE');
+    log.info('Optional Figma: npx agent-orchestrator-kit figma-setup');
   });
 
 program
@@ -839,4 +998,118 @@ program
     }
   });
 
+program
+  .command('figma-setup')
+  .description('Create local Figma token env file (never prints the token)')
+  .action(() => {
+    const projectDir = process.cwd();
+    log.title('agent-orchestrator figma-setup');
+
+    refreshFigmaManagedFiles(projectDir);
+    mergeGitignore(projectDir, GITIGNORE_LINES);
+
+    const result = ensureFigmaEnvFile(projectDir);
+    if (result.created) {
+      log.ok(`Created ${FIGMA_ENV_REL}`);
+    } else {
+      log.ok(`${FIGMA_ENV_REL} already exists`);
+    }
+
+    ensureFigmaMcpEntry(projectDir);
+
+    if (isFigmaConfigured(projectDir)) {
+      log.ok('Figma token: configured');
+    } else {
+      log.warn('Figma token: missing — open .agents/figma.local.env and set FIGMA_ACCESS_TOKEN locally (do not paste into chat)');
+    }
+
+    log.info('Restart Cursor / Amp after saving the token');
+    log.info('Check: npx agent-orchestrator-kit figma-status');
+  });
+
+program
+  .command('figma-status')
+  .description('Report whether a local Figma token is configured (never prints the token)')
+  .action(() => {
+    const projectDir = process.cwd();
+    log.title('agent-orchestrator figma-status');
+
+    const envPath = join(projectDir, FIGMA_ENV_REL);
+    if (!existsSync(envPath)) {
+      log.err(`Figma token: not configured (missing ${FIGMA_ENV_REL})`);
+      log.info('Run: npx agent-orchestrator-kit figma-setup');
+      process.exitCode = 1;
+      return;
+    }
+
+    if (!isFigmaConfigured(projectDir)) {
+      log.err('Figma token: not configured (FIGMA_ACCESS_TOKEN is empty)');
+      log.info('Edit .agents/figma.local.env locally — never paste the token into chat');
+      process.exitCode = 1;
+      return;
+    }
+
+    log.ok('Figma token: configured');
+    if (existsSync(join(projectDir, FIGMA_LAUNCHER_REL))) {
+      log.ok(`MCP launcher: ${FIGMA_LAUNCHER_REL}`);
+    } else {
+      log.warn(`MCP launcher missing — run npx agent-orchestrator-kit update`);
+    }
+  });
+
+program
+  .command('figma-fetch')
+  .description('Fetch Figma file/nodes JSON via REST API using the local token')
+  .option('--url <url>', 'Figma design URL (file key + optional node-id)')
+  .option('--file <key>', 'Figma file key')
+  .option('--nodes <ids>', 'Comma-separated node ids (1:2 or 1-2)')
+  .option('--out <path>', 'Output JSON path', 'figma-nodes.json')
+  .action(async (opts) => {
+    const projectDir = process.cwd();
+    log.title('agent-orchestrator figma-fetch');
+
+    const token = readFigmaToken(projectDir);
+    if (!token) {
+      log.err('Figma token: not configured');
+      log.info('Run: npx agent-orchestrator-kit figma-setup');
+      process.exitCode = 1;
+      return;
+    }
+
+    let fileKey = opts.file || '';
+    let nodes = opts.nodes || '';
+    if (opts.url) {
+      const parsed = parseFigmaUrl(opts.url);
+      fileKey = fileKey || parsed.fileKey;
+      nodes = nodes || parsed.nodeId;
+    }
+
+    if (!fileKey) {
+      log.err('Missing --file <key> or --url <figma-url>');
+      process.exitCode = 1;
+      return;
+    }
+
+    const nodeIds = String(nodes || '')
+      .split(',')
+      .map((id) => id.trim())
+      .filter(Boolean)
+      .map((id) => id.replace(/-/g, ':'));
+
+    try {
+      const path = nodeIds.length
+        ? `/files/${encodeURIComponent(fileKey)}/nodes?ids=${encodeURIComponent(nodeIds.join(','))}`
+        : `/files/${encodeURIComponent(fileKey)}`;
+      log.info(nodeIds.length ? `Fetching ${nodeIds.length} node(s)…` : 'Fetching full file…');
+      const data = await figmaApiGet(token, path);
+      const outPath = join(projectDir, opts.out);
+      mkdirSync(dirname(outPath), { recursive: true });
+      writeFileSync(outPath, `${JSON.stringify(data, null, 2)}\n`);
+      log.ok(`Wrote ${opts.out}`);
+    } catch (error) {
+      log.err(`Figma API error: ${error.message}`);
+      process.exitCode = 1;
+    }
+  });
+
 program.parse();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-orchestrator-kit",
-  "version": "0.1.10",
-  "description": "Universal AI agent orchestration kit for Cursor, Claude Code, and Amp Code — spec-driven OpenSpec pipeline with cross-IDE custom subagents (openspec-guide, code-writer, code-reviewer, test-writer, setup-doctor, design-implementer)",
+  "version": "0.1.11",
+  "description": "Universal AI agent orchestration kit for Cursor, Claude Code, and Amp Code — spec-driven OpenSpec pipeline, cross-IDE subagents, and optional local Figma PAT setup (figma-setup / figma-status / figma-fetch)",
   "keywords": [
     "ai-agent",
     "cursor",
@@ -13,6 +13,8 @@
     "subagents",
     "custom-subagents",
     "design-to-code",
+    "figma",
+    "figma-mcp",
     "developer-tools"
   ],
   "author": "Maksim Shevyakov <makshc2>",

package/profiles/generic/orchestrator.yaml

@@ -52,6 +52,13 @@ memory:
 mcp:
   baseline:
     - memory
+  optional:
+    - figma
+
+figma:
+  env_file: .agents/figma.local.env
+  token_key: FIGMA_ACCESS_TOKEN
+  mcp_launcher: scripts/figma-mcp-launcher.cjs
 
 verifier:
   lint_command: ""

package/profiles/mvp/orchestrator.yaml

@@ -59,6 +59,13 @@ memory:
 mcp:
   baseline:
     - memory
+  optional:
+    - figma
+
+figma:
+  env_file: .agents/figma.local.env
+  token_key: FIGMA_ACCESS_TOKEN
+  mcp_launcher: scripts/figma-mcp-launcher.cjs
 
 verifier:
   lint_command: "npm run lint"

package/profiles/node/orchestrator.yaml

@@ -57,6 +57,13 @@ memory:
 mcp:
   baseline:
     - memory
+  optional:
+    - figma
+
+figma:
+  env_file: .agents/figma.local.env
+  token_key: FIGMA_ACCESS_TOKEN
+  mcp_launcher: scripts/figma-mcp-launcher.cjs
 
 verifier:
   lint_command: "npm run lint"

package/profiles/vue3/orchestrator.yaml

@@ -57,9 +57,15 @@ mcp:
   baseline:
     - memory
   optional:
+    - figma
     - github
     - browser
 
+figma:
+  env_file: .agents/figma.local.env
+  token_key: FIGMA_ACCESS_TOKEN
+  mcp_launcher: scripts/figma-mcp-launcher.cjs
+
 verifier:
   lint_command: "npm run lint"
   build_command: "npm run build"

package/templates/.agents/amp.settings.json.example

@@ -6,6 +6,10 @@
       "env": {
         "MEMORY_FILE_PATH": ".cursor/memory.json"
       }
+    },
+    "figma": {
+      "command": "node",
+      "args": ["scripts/figma-mcp-launcher.cjs"]
     }
   }
 }

package/templates/.agents/commands/opsx-apply.md

@@ -16,7 +16,7 @@ Implement tasks from an OpenSpec change.
    If a name is provided, use it. Otherwise:
    - Infer from conversation context if the user mentioned a change
    - Auto-select if only one active change exists
-   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+   - If ambiguous, run `npx openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
 
    Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
 
@@ -35,7 +35,7 @@ Implement tasks from an OpenSpec change.
 
 2. **Check status to understand the schema**
    ```bash
-   openspec status --change "<name>" --json
+   npx openspec status --change "<name>" --json
    ```
    Parse the JSON to understand:
    - `schemaName`: The workflow being used (e.g., "spec-driven")
@@ -45,7 +45,7 @@ Implement tasks from an OpenSpec change.
 3. **Get apply instructions**
 
    ```bash
-   openspec instructions apply --change "<name>" --json
+   npx openspec instructions apply --change "<name>" --json
    ```
 
    This returns:

package/templates/.agents/commands/opsx-archive.md

@@ -13,7 +13,7 @@ Archive a completed change in the experimental workflow.
 
 1. **If no change name provided, prompt for selection**
 
-   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+   Run `npx openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
 
    Show only active changes (not already archived).
    Include the schema used for each change if available.
@@ -22,7 +22,7 @@ Archive a completed change in the experimental workflow.
 
 2. **Check artifact completion status**
 
-   Run `openspec status --change "<name>" --json` to check artifact completion.
+   Run `npx openspec status --change "<name>" --json` to check artifact completion.
 
    Parse the JSON to understand:
    - `schemaName`: The workflow being used

package/templates/.agents/commands/opsx-design.md

@@ -18,7 +18,7 @@ Capture design into a durable brief for an OpenSpec change. One-shot intake from
 ### 1. Select the change
 
 If name provided — use it. Otherwise:
-- Run `openspec list --json` to list active changes.
+- Run `npx openspec list --json` to list active changes.
 - Auto-select if only one exists.
 - Ask the user if ambiguous.
 
@@ -28,7 +28,7 @@ Announce: "Design intake for change: **<name>**"
 
 Use the first available source; do not climb the ladder twice:
 
-1. **Figma MCP** — one pass only (`get_design_context` / screenshot / metadata). Capture everything needed immediately; never call Figma again during later apply.
+1. **Figma MCP** — one pass only (`get_design_context` / screenshot / metadata). Capture everything needed immediately; never call Figma again during later apply. If MCP fails, check `npx agent-orchestrator-kit figma-status`. If the token is missing, tell the user to run `figma-setup` and edit `.agents/figma.local.env` locally — **never ask them to paste the token into chat**. Optional REST dump: `npx agent-orchestrator-kit figma-fetch --url "<figma-url>" --out openspec/changes/<name>/assets/figma-nodes.json`.
 2. **Exported images** — PNG/SVG already in the repo or attached by the user.
 3. **Screenshots** — UI captures (desktop/mobile).
 4. **Photos** — physical mockups or whiteboard photos.

package/templates/.agents/commands/opsx-explore.md

@@ -86,7 +86,7 @@ You have full context of the OpenSpec system. Use it naturally, don't force it.
 
 At the start, quickly check what exists:
 ```bash
-openspec list --json
+npx openspec list --json
 ```
 
 This tells you:
@@ -108,7 +108,7 @@ Think freely. When insights crystallize, you might offer:
 If the user mentions a change or you detect one is relevant:
 
 1. **Resolve and read existing artifacts for context**
-   - Run `openspec status --change "<name>" --json`.
+   - Run `npx openspec status --change "<name>" --json`.
    - Use `changeRoot`, `artifactPaths`, and `actionContext` from the status JSON.
    - Read existing files from `artifactPaths.<artifact>.existingOutputPaths`.