agent-orchestrator-kit 0.1.9 → 0.1.11

package/bin/agent-orchestrator.js

@@ -26,12 +26,17 @@ const KIT_SKILL_DIRS = [
 const KIT_MANAGED_PATHS = [
   '.agents/commands',
   '.agents/rules',
+  '.agents/subagents',
   ...KIT_SKILL_DIRS.map((s) => `.agents/skills/${s}`),
-  '.github/workflows/agent-verify.yml',
-  '.gitlab/agent-verify.yml',
   'scripts/sync-local-agent-skills.sh',
 ];
 
+// CI workflow files are provider-specific and chosen once at `init --ci`.
+// `update` must only refresh them if already present — never resurrect a
+// workflow file for a provider the project doesn't use (e.g. after switching
+// from GitHub Actions to GitLab CI and deleting the GitHub workflow).
+const CI_WORKFLOW_PATHS = ['.github/workflows/agent-verify.yml', '.gitlab/agent-verify.yml'];
+
 // Opt-in AI Spec Verifier files, per CI provider. `scripts/verify-specs.sh` is
 // shared — it is stack- and CI-agnostic already.
 const GITLAB_SPEC_VERIFY_PATHS = [
@@ -55,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),
@@ -113,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;
@@ -401,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';
@@ -439,8 +598,65 @@ function printNextSteps(profile, projectDir, ci = 'github', specVerify = false)
   console.log('\n' + lines.join('\n') + '\n');
 }
 
+// Amp has no file-based custom subagents (only skills and plugin agents), but
+// it natively loads skills from .agents/skills/ with the same description-driven
+// delegation. Each .agents/subagents/<name>.md therefore gets a committed skill
+// wrapper .agents/skills/subagent-<name>/SKILL.md so subagents work in Amp with
+// zero local setup. Wrappers are regenerated on init/update/sync and stale ones
+// are removed when their source subagent is deleted.
+const AMP_SUBAGENT_SKILL_PREFIX = 'subagent-';
+
+function listAmpSubagentWrappers(projectDir) {
+  const skillsDir = join(projectDir, '.agents', 'skills');
+  if (!existsSync(skillsDir)) return [];
+  return readdirSync(skillsDir).filter((entry) => entry.startsWith(AMP_SUBAGENT_SKILL_PREFIX));
+}
+
+function generateAmpSubagentSkills(projectDir) {
+  const subagentsDir = join(projectDir, '.agents', 'subagents');
+  const skillsDir = join(projectDir, '.agents', 'skills');
+  const expected = new Set();
+
+  if (existsSync(subagentsDir)) {
+    for (const file of readdirSync(subagentsDir).filter((f) => f.endsWith('.md'))) {
+      const content = readFileSync(join(subagentsDir, file), 'utf-8');
+      const parsed = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+      const name = parsed?.[1].match(/^name:\s*(.+)$/m)?.[1]?.trim();
+      const description = parsed?.[1].match(/^description:\s*(.+)$/m)?.[1]?.trim();
+      if (!name || !description) {
+        log.warn(`skip Amp wrapper (missing name/description frontmatter): .agents/subagents/${file}`);
+        continue;
+      }
+
+      const skillName = `${AMP_SUBAGENT_SKILL_PREFIX}${name}`;
+      expected.add(skillName);
+      mkdirSync(join(skillsDir, skillName), { recursive: true });
+      const skill = [
+        '---',
+        `name: ${skillName}`,
+        `description: ${description}`,
+        '---',
+        '',
+        `<!-- AUTO-GENERATED from .agents/subagents/${file} — edit the source file, then run: npx agent-orchestrator-kit sync -->`,
+        '',
+        parsed[2].trim(),
+        '',
+      ].join('\n');
+      writeFileSync(join(skillsDir, skillName, 'SKILL.md'), skill);
+      log.ok(`.agents/skills/${skillName}/SKILL.md (Amp wrapper)`);
+    }
+  }
+
+  for (const entry of listAmpSubagentWrappers(projectDir)) {
+    if (!expected.has(entry)) {
+      rmSync(join(projectDir, '.agents', 'skills', entry), { recursive: true, force: true });
+      log.warn(`removed stale Amp wrapper: .agents/skills/${entry}`);
+    }
+  }
+}
+
 function syncAmp(projectDir) {
-  log.info('Amp Code reads .agents/ natively — no skill sync needed');
+  log.info('Amp Code reads .agents/ natively — subagents exposed via skill wrappers');
   mkdirSync(join(projectDir, '.amp'), { recursive: true });
   const ampExample = join(projectDir, '.agents', 'amp.settings.json.example');
   const ampDest = join(projectDir, '.amp', 'settings.json');
@@ -491,6 +707,7 @@ program
     if (existsSync(join(profileDir, '.agents'))) {
       copyDir(join(profileDir, '.agents'), join(projectDir, '.agents'), { overwrite: opts.force });
     }
+    generateAmpSubagentSkills(projectDir);
 
     log.title('Installing scripts/');
     copyDir(join(templateDir, 'scripts'), join(projectDir, 'scripts'), {
@@ -578,6 +795,16 @@ program
       }
     }
 
+    generateAmpSubagentSkills(projectDir);
+
+    for (const rel of CI_WORKFLOW_PATHS) {
+      const src = join(templateDir, rel);
+      const dest = join(projectDir, rel);
+      if (!existsSync(src) || !existsSync(dest)) continue;
+      copyFileSync(src, dest);
+      log.ok(rel);
+    }
+
     for (const rel of KIT_OPTIN_PATHS) {
       const src = join(templateDir, rel);
       const dest = join(projectDir, rel);
@@ -586,8 +813,17 @@ program
       log.ok(`${rel} (opt-in)`);
     }
 
+    try {
+      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
@@ -603,10 +839,20 @@ program
     const syncClaude = ['claude', 'all'].includes(opts.target);
     const syncAmpTarget = ['amp', 'all'].includes(opts.target);
 
+    generateAmpSubagentSkills(projectDir);
+
+    // Amp skill wrappers are redundant in Cursor/Claude (they get native
+    // subagents from .agents/subagents/), so exclude them from skill sync.
+    const ampWrappers = listAmpSubagentWrappers(projectDir);
+
     if (syncCursor) {
       log.info('Syncing .agents/ → .cursor/');
-      copyDir(join(projectDir, '.agents', 'skills'), join(projectDir, '.cursor', 'skills'), { overwrite: true, delete: true });
+      copyDir(join(projectDir, '.agents', 'skills'), join(projectDir, '.cursor', 'skills'), { overwrite: true, delete: true, skip: ampWrappers });
+      for (const wrapper of ampWrappers) {
+        rmSync(join(projectDir, '.cursor', 'skills', wrapper), { recursive: true, force: true });
+      }
       copyDir(join(projectDir, '.agents', 'rules'), join(projectDir, '.cursor', 'rules'), { overwrite: true, delete: true });
+      copyDir(join(projectDir, '.agents', 'subagents'), join(projectDir, '.cursor', 'agents'), { overwrite: true, delete: true });
 
       const mcpExample = join(projectDir, '.agents', 'mcp.json.example');
       const mcpDest = join(projectDir, '.mcp.json');
@@ -618,7 +864,11 @@ program
 
     if (syncClaude) {
       log.info('Syncing .agents/ → .claude/');
-      copyDir(join(projectDir, '.agents', 'skills'), join(projectDir, '.claude', 'skills'), { overwrite: true, delete: true });
+      copyDir(join(projectDir, '.agents', 'skills'), join(projectDir, '.claude', 'skills'), { overwrite: true, delete: true, skip: ampWrappers });
+      for (const wrapper of ampWrappers) {
+        rmSync(join(projectDir, '.claude', 'skills', wrapper), { recursive: true, force: true });
+      }
+      copyDir(join(projectDir, '.agents', 'subagents'), join(projectDir, '.claude', 'agents'), { overwrite: true, delete: true });
 
       const claudeMd = join(projectDir, 'CLAUDE.md');
       const claudeDir = join(projectDir, '.claude');
@@ -748,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.9",
-  "description": "Universal AI agent orchestration kit for Cursor, Claude Code, and Amp Code — spec-driven pipeline with OpenSpec integration",
+  "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",
@@ -10,6 +10,11 @@
     "openspec",
     "sdd",
     "agent-orchestration",
+    "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`.