@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/figma-common/figma-setup/SKILL.md

@@ -0,0 +1,514 @@
+---
+name: figma-setup
+description: One-time environment setup for Figma-to-SwiftUI workflow. Verifies MCP connectivity, API credentials, Code Connect CLI, and FigmaRegistryUtility.
+user-invocable: true
+argument-hint: [run | status | reset | retrieve-token | save-token]
+allowed-tools: Bash, Read, Write, AskUserQuestion
+status: wip-v5
+sourced-from: upstream/figma-setup
+---
+
+# /figma-setup — Environment Setup
+
+One-time environment setup for the Figma-to-SwiftUI workflow. Run before your first `/figma` invocation, or when `/figma` reports missing prerequisites.
+
+---
+
+## Parse Input
+
+| Argument | Action |
+|----------|--------|
+| `run` (default) | Execute full setup checks |
+| `status` | Read and display marker file |
+| `reset` | Delete marker file, re-run all checks |
+| `retrieve-token` | Retrieve remote MCP OAuth token (see Token Management below) |
+| `save-token` | Save a remote MCP OAuth token to keychain (see Token Management below) |
+
+**Marker file:** `{repos.packagesContainer}/{repos.artifactsRepo}/ImplementationArtifacts/Figma/.setup-verified.json`
+
+For `status`: read and display the marker file. If it doesn't exist, tell the user to run `/figma-setup run`.
+For `reset`: delete the marker file, then execute `run`.
+
+---
+
+## Checks
+
+Execute each check in order. For each:
+1. Run the check command
+2. PASS → record result, move to next
+3. FAIL → guide user through fix, re-check
+4. User says "skip" → record as `skipped`, move to next
+
+---
+
+### CHECK 1: Git User
+
+```bash
+git config user.name
+```
+
+**PASS:** Non-empty output → store as `gitUser`.
+
+**FAIL:** Ask user for their name, then:
+```bash
+git config user.name "<NAME>"
+```
+
+---
+
+### CHECK 2: Figma Local MCP
+
+Test connectivity by calling the local MCP tool:
+
+```
+mcp__figma__get_metadata(nodeId: "0:1")
+```
+
+**PASS:** Returns data → local MCP is connected.
+
+**FAIL:** Tell the user:
+
+> To enable Figma Local MCP:
+> 1. Open **Figma Desktop** (download from https://www.figma.com/downloads/)
+> 2. Open any design file
+> 3. Press **Shift+D** to enable Dev Mode
+> 4. MCP server starts automatically on `http://127.0.0.1:3845/mcp`
+
+Ask: "Confirm when Figma Desktop is running with Dev Mode enabled, or say 'skip'."
+
+Re-check after confirmation. Record `skipped` if user skips.
+
+---
+
+### CHECK 3: Figma Remote MCP
+
+```
+mcp__figma-remote__whoami()
+```
+
+**PASS:** Returns authenticated user info.
+
+**FAIL:** Tell the user:
+
+> To enable Figma Remote MCP:
+> 1. Your editor should prompt OAuth authentication via browser
+> 2. Complete the consent flow in the browser
+> 3. Return here and confirm
+
+Ask: "Confirm when OAuth is complete, or say 'skip'."
+
+Re-check after confirmation. Record `skipped` if user skips.
+
+**CRITICAL:** At least one of CHECK 2 or CHECK 3 must pass. If BOTH are skipped → HALT:
+```
+At least one Figma MCP connection (local or remote) is required. Cannot proceed.
+```
+
+---
+
+### CHECK 3b: MCP OAuth Token for Scripts (FIGMA_MCP_TOKEN)
+
+Scripts like `remote-mcp-fetch.py` need the MCP OAuth token to call remote MCP outside of chat context. This check extracts it from Claude Code credentials and saves it to keychain.
+
+**Only run if CHECK 3 passed.** If CHECK 3 was skipped, skip this too.
+
+#### 3b-a. Check if token already exists and works
+
+```bash
+TOKEN=$(security find-generic-password -a "$USER" -s "FIGMA_MCP_TOKEN" -w 2>/dev/null) && [ -n "$TOKEN" ] && echo "TOKEN_EXISTS" || echo "TOKEN_MISSING"
+```
+
+If TOKEN_EXISTS, verify it works:
+
+```bash
+TOKEN=$(security find-generic-password -a "$USER" -s "FIGMA_MCP_TOKEN" -w 2>/dev/null) && curl -s -o /dev/null -w "%{http_code}" -X POST "https://mcp.figma.com/mcp" -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -H "Authorization: Bearer $TOKEN" -d '{"jsonrpc":"2.0","method":"initialize","params":{"capabilities":{},"clientInfo":{"name":"setup-check","version":"1.0.0"},"protocolVersion":"2025-03-26"},"id":1}'
+```
+
+- `200` → PASS, token is valid
+- `401` → token expired or invalid, proceed to 3b-b
+- Other → network issue, retry
+
+#### 3b-b. Extract from Claude Code credentials
+
+Claude Code stores MCP OAuth tokens in macOS Keychain under `Claude Code-credentials`. Extract the `figma-remote` access token:
+
+```bash
+python3 -c "
+import subprocess, os, re, json
+raw = subprocess.check_output(['security', 'find-generic-password', '-s', 'Claude Code-credentials', '-a', os.environ['USER'], '-w'], stderr=subprocess.DEVNULL).decode()
+match = re.search(r'\"figma-remote\|[^\"]+\":\{[^}]*\"accessToken\":\"([^\"]+)\"', raw)
+if match:
+    print(match.group(1))
+else:
+    print('EXTRACT_FAILED')
+"
+```
+
+- If output starts with `figu_` → valid OAuth token
+- If `EXTRACT_FAILED` → Claude Code has no figma-remote credentials
+
+#### 3b-c. If extraction succeeded — save to keychain
+
+```bash
+TOKEN="<extracted_token>" && security delete-generic-password -a "$USER" -s "FIGMA_MCP_TOKEN" >/dev/null 2>&1; security add-generic-password -a "$USER" -s "FIGMA_MCP_TOKEN" -w "$TOKEN" >/dev/null 2>&1 && echo "MCP_TOKEN_STORED" || echo "MCP_TOKEN_STORE_FAILED"
+```
+
+**IMPORTANT:** Do NOT echo the token in chat. Capture the python3 output into a variable directly:
+
+```bash
+MCP_TOKEN=$(python3 -c "
+import subprocess, os, re
+raw = subprocess.check_output(['security', 'find-generic-password', '-s', 'Claude Code-credentials', '-a', os.environ['USER'], '-w'], stderr=subprocess.DEVNULL).decode()
+match = re.search(r'\"figma-remote\|[^\\\"]+\":\{[^}]*\"accessToken\":\"([^\\\"]+)\"', raw)
+print(match.group(1) if match else '')
+" 2>/dev/null) && [ -n "$MCP_TOKEN" ] && security delete-generic-password -a "$USER" -s "FIGMA_MCP_TOKEN" >/dev/null 2>&1; security add-generic-password -a "$USER" -s "FIGMA_MCP_TOKEN" -w "$MCP_TOKEN" >/dev/null 2>&1 && echo "MCP_TOKEN_STORED" || echo "MCP_TOKEN_STORE_FAILED"
+```
+
+Then verify (repeat 3b-a verification curl).
+
+#### 3b-d. If extraction failed
+
+Tell the user:
+
+> Could not extract MCP OAuth token from Claude Code credentials.
+> This means `figma-remote` MCP has not completed OAuth yet.
+> 1. Ensure CHECK 3 passed (remote MCP whoami works)
+> 2. Re-run `/figma-setup` after completing remote MCP OAuth
+
+Record as `skipped`. Scripts will fall back to extracting at runtime (slower but functional).
+
+---
+
+### CHECK 4: Figma API Token (Secure Clipboard Flow)
+
+**IMPORTANT: The token must NEVER appear in chat. Use the clipboard flow below.**
+
+#### 4a. Check if token already exists
+
+```bash
+security find-generic-password -a "$USER" -s "FIGMA_ACCESS_TOKEN" -w >/dev/null 2>&1 && echo "TOKEN_EXISTS" || echo "TOKEN_MISSING"
+```
+
+#### 4b. If TOKEN_EXISTS — verify it works
+
+```bash
+curl -s -o /dev/null -w "%{http_code}" -H "X-Figma-Token: $(security find-generic-password -a "$USER" -s 'FIGMA_ACCESS_TOKEN' -w 2>/dev/null)" "https://api.figma.com/v1/me"
+```
+
+- `200` → PASS, token is valid
+- `403` → token expired or revoked, proceed to 4c
+- Other → network issue, retry
+
+#### 4c. If TOKEN_MISSING or expired — secure setup
+
+Tell the user:
+
+> 1. Go to **https://www.figma.com/developers/api#access-tokens**
+> 2. Click **"Get personal access token"**
+> 3. Set expiry (note: PATs are capped at 90 days max)
+> 4. **Copy the token to your clipboard** (Cmd+C)
+> 5. **Do NOT paste the token in this chat**
+> 6. Come back here and confirm
+
+Ask: "Confirm when the token is copied to your clipboard."
+
+After user confirms, run this SINGLE command:
+
+```bash
+security delete-generic-password -a "$USER" -s "FIGMA_ACCESS_TOKEN" >/dev/null 2>&1; security add-generic-password -a "$USER" -s "FIGMA_ACCESS_TOKEN" -w "$(pbpaste)" >/dev/null 2>&1 && echo "TOKEN_STORED" || echo "TOKEN_STORE_FAILED"
+```
+
+Then immediately clear clipboard:
+
+```bash
+pbcopy < /dev/null && echo "CLIPBOARD_CLEARED"
+```
+
+Then verify (repeat 4b). If still failing → HALT.
+
+---
+
+### CHECK 5: Figma API User
+
+```bash
+security find-generic-password -a "$USER" -s "FIGMA_API_USER" -w >/dev/null 2>&1 && echo "USER_EXISTS" || echo "USER_MISSING"
+```
+
+**If USER_MISSING:**
+
+Ask: "What is your Figma account email address?"
+
+After user provides email:
+
+```bash
+security delete-generic-password -a "$USER" -s "FIGMA_API_USER" >/dev/null 2>&1; security add-generic-password -a "$USER" -s "FIGMA_API_USER" -w "<EMAIL>" >/dev/null 2>&1 && echo "USER_STORED" || echo "USER_STORE_FAILED"
+```
+
+---
+
+### CHECK 6: Code Connect CLI
+
+```bash
+npx @figma/code-connect@latest --version 2>/dev/null
+```
+
+**PASS:** Returns version number (e.g., `1.4.1`).
+
+**FAIL:** Node.js/npm is required. Tell the user:
+
+> Code Connect CLI requires Node.js. Install options:
+> - Download from https://nodejs.org/ (LTS recommended)
+> - Or: `brew install node`
+>
+> Code Connect uses `npx` — no global install needed.
+
+Ask: "Confirm when Node.js is installed, or say 'skip'."
+
+Record `skipped` if user skips. Code Connect is only needed for Phase 6.
+
+---
+
+### CHECK 7: FigmaRegistryUtility
+
+```bash
+CONFIG_PATH="{repos.packagesContainer}/{project.slug}-common" && swift run --package-path "$CONFIG_PATH" FigmaRegistryUtility --help >/dev/null 2>&1 && echo "REGISTRY_OK" || echo "REGISTRY_BUILD_NEEDED"
+```
+
+**If REGISTRY_BUILD_NEEDED:**
+
+```bash
+CONFIG_PATH="{repos.packagesContainer}/{project.slug}-common" && swift build --package-path "$CONFIG_PATH" --product FigmaRegistryUtility 2>&1 | tail -5
+```
+
+If build succeeds → re-check. If build fails → HALT with the build error output.
+
+---
+
+### CHECK 8: GitHub CLI (`gh`)
+
+```bash
+gh --version 2>/dev/null
+```
+
+**PASS:** Returns version (e.g., `gh version 2.x.x`).
+
+**FAIL:** Tell the user:
+
+> GitHub CLI is required for issue management, Projects V2, and PR workflows.
+> Install: `brew install gh`
+
+Ask: "Confirm when installed, or say 'skip'."
+
+#### 8b. Authentication
+
+```bash
+gh auth status 2>&1
+```
+
+**PASS:** Shows logged in account.
+
+**FAIL:** Tell the user:
+
+> Run `gh auth login` and complete the browser flow.
+> Required scopes: `repo`, `read:org`, `project`
+
+Ask: "Confirm when authenticated."
+
+#### 8c. Project scope
+
+```bash
+gh api graphql -f query='{ viewer { login } }' 2>&1
+```
+
+If `INSUFFICIENT_SCOPES` error mentioning `project`:
+
+> Your token needs the `project` scope. Run:
+> `gh auth refresh -s project -h github.com`
+
+---
+
+### CHECK 9: Jira Token
+
+```bash
+security find-generic-password -a "$USER" -s "JIRA_TOKEN" -w >/dev/null 2>&1 && echo "TOKEN_EXISTS" || echo "TOKEN_MISSING"
+```
+
+#### 9a. If TOKEN_EXISTS — verify
+
+```bash
+curl -s -o /dev/null -w "%{http_code}" "{jira.baseUrl}/rest/api/2/myself" \
+  -H "Authorization: Bearer $(security find-generic-password -a '$USER' -s 'JIRA_TOKEN' -w 2>/dev/null)"
+```
+
+- `200` → PASS
+- `401/403` → token expired, proceed to 9b
+- Connection error → VPN not connected, record as `skipped (no VPN)`
+
+#### 9b. If TOKEN_MISSING or expired
+
+Tell the user:
+
+> Jira token is needed for `/figma-issue` Jira integration.
+> 1. Go to **{jira.baseUrl}/secure/ViewProfile.jspa** → **Personal Access Tokens**
+> 2. Create a token
+> 3. **Copy to clipboard** (Cmd+C)
+> 4. **Do NOT paste in chat**
+
+Ask: "Confirm when token is copied to clipboard."
+
+```bash
+security delete-generic-password -a "$USER" -s "JIRA_TOKEN" >/dev/null 2>&1; security add-generic-password -a "$USER" -s "JIRA_TOKEN" -w "$(pbpaste)" >/dev/null 2>&1 && echo "TOKEN_STORED" || echo "TOKEN_STORE_FAILED"
+```
+
+Clear clipboard:
+```bash
+pbcopy < /dev/null && echo "CLIPBOARD_CLEARED"
+```
+
+Verify (repeat 9a). If VPN not connected, accept as `pass (stored, not verified)`.
+
+---
+
+### CHECK 10: Confluence Token
+
+```bash
+security find-generic-password -a "$USER" -s "CONFLUENCE_TOKEN" -w >/dev/null 2>&1 && echo "TOKEN_EXISTS" || echo "TOKEN_MISSING"
+```
+
+Same flow as CHECK 9 but for Confluence:
+- Verify: `curl -s -o /dev/null -w "%{http_code}" "{confluence.baseUrl}/rest/api/content?limit=1" -H "Authorization: Bearer ..."`
+- If missing: guide user to create PAT at `{confluence.baseUrl}`
+- Clipboard flow, same as Jira
+- VPN required — if not connected, record as `skipped (no VPN)`
+
+---
+
+## Write Marker File
+
+After all checks complete, create `{repos.packagesContainer}/{repos.artifactsRepo}/ImplementationArtifacts/Figma/.setup-verified.json`:
+
+```json
+{
+  "verified": "<ISO_TIMESTAMP>",
+  "checks": {
+    "git_user": { "status": "pass", "value": "<NAME>" },
+    "figma_local_mcp": { "status": "pass|skipped" },
+    "figma_remote_mcp": { "status": "pass|skipped" },
+    "figma_mcp_token": { "status": "pass|skipped", "note": "FIGMA_MCP_TOKEN in keychain for script access" },
+    "figma_api_token": { "status": "pass|skipped" },
+    "figma_api_user": { "status": "pass|skipped" },
+    "code_connect_cli": { "status": "pass|skipped", "version": "<VERSION>" },
+    "registry_utility": { "status": "pass" },
+    "github_cli": { "status": "pass|skipped", "scopes": "repo,read:org,project" },
+    "jira_token": { "status": "pass|skipped" },
+    "confluence_token": { "status": "pass|skipped" }
+  }
+}
+```
+
+---
+
+## Token Management
+
+### `retrieve-token` — Retrieve Remote MCP OAuth Token
+
+Looks up the Figma remote MCP OAuth token (`figu_` prefix) and prints it for the user.
+
+**Resolution order:**
+
+1. **Keychain `FIGMA_MCP_TOKEN`** — the dedicated keychain entry saved by `save-token` or CHECK 3b.
+
+```bash
+security find-generic-password -a "$USER" -s "FIGMA_MCP_TOKEN" -w 2>/dev/null
+```
+
+2. **Claude Code credentials** — if not in dedicated keychain, extract from Claude Code's credential store.
+
+```bash
+python3 -c "
+import subprocess, os, re
+raw = subprocess.check_output(
+    ['security', 'find-generic-password', '-s', 'Claude Code-credentials',
+     '-a', os.environ['USER'], '-w'],
+    stderr=subprocess.DEVNULL
+).decode()
+match = re.search(r'\"figma-remote\|[^\"]+\":\{[^}]*\"accessToken\":\"([^\"]+)\"', raw)
+print(match.group(1) if match else 'NOT_FOUND')
+"
+```
+
+**Output:**
+- If found → print the token to the user
+- If `NOT_FOUND` → tell the user:
+  > No remote MCP token found. Ensure `figma-remote` MCP has completed OAuth (CHECK 3), or use `/figma-setup save-token` to store one manually.
+
+---
+
+### `save-token` — Save Remote MCP OAuth Token to Keychain
+
+Saves a provided token (or extracts from Claude Code credentials) to the dedicated `FIGMA_MCP_TOKEN` keychain entry so scripts can use it.
+
+**Flow:**
+
+1. Ask the user:
+
+> Do you want to:
+> a) **Auto-extract** from Claude Code credentials (recommended)
+> b) **Paste** a token manually (copy to clipboard first)
+
+2a. **Auto-extract:**
+
+```bash
+MCP_TOKEN=$(python3 -c "
+import subprocess, os, re
+raw = subprocess.check_output(
+    ['security', 'find-generic-password', '-s', 'Claude Code-credentials',
+     '-a', os.environ['USER'], '-w'],
+    stderr=subprocess.DEVNULL
+).decode()
+match = re.search(r'\"figma-remote\|[^\\\"]+\":\{[^}]*\"accessToken\":\"([^\\\"]+)\"', raw)
+print(match.group(1) if match else '')
+" 2>/dev/null)
+```
+
+If empty → tell user Claude Code has no figma-remote credentials, suggest completing OAuth first.
+
+2b. **Paste from clipboard:**
+
+```bash
+MCP_TOKEN=$(pbpaste)
+```
+
+Then clear clipboard: `pbcopy < /dev/null`
+
+3. **Save to keychain:**
+
+```bash
+security delete-generic-password -a "$USER" -s "FIGMA_MCP_TOKEN" >/dev/null 2>&1
+security add-generic-password -a "$USER" -s "FIGMA_MCP_TOKEN" -w "$MCP_TOKEN" >/dev/null 2>&1 && echo "TOKEN_SAVED" || echo "TOKEN_SAVE_FAILED"
+```
+
+4. **Verify** the saved token works:
+
+```bash
+TOKEN=$(security find-generic-password -a "$USER" -s "FIGMA_MCP_TOKEN" -w 2>/dev/null) && curl -s -o /dev/null -w "%{http_code}" -X POST "https://mcp.figma.com/mcp" -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -H "Authorization: Bearer $TOKEN" -d '{"jsonrpc":"2.0","method":"initialize","params":{"capabilities":{},"clientInfo":{"name":"setup-check","version":"1.0.0"},"protocolVersion":"2025-03-26"},"id":1}'
+```
+
+- `200` → print "Token saved and verified."
+- `401` → print "Token saved but verification failed (expired or invalid)."
+
+**IMPORTANT:** Do NOT echo the raw token during the save flow. Only show it during `retrieve-token`.
+
+---
+
+## Output
+
+```
+SETUP COMPLETE
+
+Checks passed: [list]
+Checks skipped: [list]
+Marker: {repos.packagesContainer}/{repos.artifactsRepo}/ImplementationArtifacts/Figma/.setup-verified.json
+
+Your environment is ready for /figma.
+```