@mmerterden/multi-agent-pipeline 11.2.0 → 11.3.1

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

@@ -1,514 +0,0 @@
----
-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=$("$HOME/.claude/lib/credential-store.sh" get \1 2>/dev/null) && [ -n "$TOKEN" ] && echo "TOKEN_EXISTS" || echo "TOKEN_MISSING"
-```
-
-If TOKEN_EXISTS, verify it works:
-
-```bash
-TOKEN=$("$HOME/.claude/lib/credential-store.sh" get \1 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>" && "$HOME/.claude/lib/credential-store.sh" set \1 \"\2\" >/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" ] && "$HOME/.claude/lib/credential-store.sh" set \1 \"\2\" >/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
-"$HOME/.claude/lib/credential-store.sh" get \1 >/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: $("$HOME/.claude/lib/credential-store.sh" get \1 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
-"$HOME/.claude/lib/credential-store.sh" set \1 \"\2\" >/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
-"$HOME/.claude/lib/credential-store.sh" get \1 >/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
-"$HOME/.claude/lib/credential-store.sh" set \1 \"\2\" >/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
-"$HOME/.claude/lib/credential-store.sh" get \1 >/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 $("$HOME/.claude/lib/credential-store.sh" get \1 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
-"$HOME/.claude/lib/credential-store.sh" set \1 \"\2\" >/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
-"$HOME/.claude/lib/credential-store.sh" get \1 >/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
-"$HOME/.claude/lib/credential-store.sh" get \1 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
-"$HOME/.claude/lib/credential-store.sh" delete \1 >/dev/null 2>&1
-"$HOME/.claude/lib/credential-store.sh" set \1 \"\2\" >/dev/null 2>&1 && echo "TOKEN_SAVED" || echo "TOKEN_SAVE_FAILED"
-```
-
-4. **Verify** the saved token works:
-
-```bash
-TOKEN=$("$HOME/.claude/lib/credential-store.sh" get \1 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.
-```