@mmerterden/multi-agent-pipeline 8.6.0

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

@@ -0,0 +1,129 @@
+---
+name: figma-skip
+description: Marks a Figma component as skipped in the component registry and updates the Confluence status dashboard.
+user-invocable: true
+argument-hint: <figma-url> [--reason <reason>]
+allowed-tools: Bash, Read, Write, Edit, AskUserQuestion
+status: wip-v5
+sourced-from: upstream/figma-skip
+---
+
+# /figma-skip — Mark Component as Skipped
+
+## Parse Arguments
+
+`$ARGUMENTS` must contain a Figma URL. Optional `--reason` flag for skip reason.
+
+```
+/figma-skip https://www.figma.com/design/{fileKey}/{fileName}?node-id={nodeId}
+/figma-skip https://www.figma.com/design/{fileKey}/{fileName}?node-id={nodeId} --reason "Cursor component, not needed on mobile"
+```
+
+### URL Parsing
+
+Extract from Figma URL:
+```
+https://www.figma.com/design/{fileKey}/{fileName}?node-id={nodeId}
+```
+Convert `-` to `:` in node-id (e.g., `3-9045` → `3:9045`).
+Derive filename: `{nodeId with : replaced by -}.json` (e.g., `3-9045.json`).
+
+---
+
+## Workflow
+
+### STEP 1 — Resolve Component Name
+
+```bash
+COMMON_PATH="${REPO_ROOT}/{repos.common.path}"
+cd "${COMMON_PATH}" && .build/debug/FigmaRegistryUtility lookup --node-id '{nodeId}'
+```
+
+Extract `suggestedComponentName` from the output.
+
+If the registry file already exists at `Shared/Figma/Components/{nodeId}.json`:
+- Read it. If `"skip": true` already set → inform user "Already skipped" and exit.
+- If not skipped → ask user if they want to mark it as skipped (it may have implementation data).
+
+### STEP 2 — Create/Update Registry Entry
+
+Write `Shared/Figma/Components/{nodeId}.json`:
+
+```json
+{
+  "nodeId": "{nodeId}",
+  "componentName": {
+    "ios": "{componentName}",
+    "android": "{componentName}"
+  },
+  "skip": true,
+  "codeConnect": {
+    "ios": false,
+    "android": false
+  },
+  "confluence": {
+    "page": null,
+    "ios": null,
+    "android": null
+  },
+  "fileKey": "{fileKey}",
+  "lastUpdated": "{YYYY-MM-DD}",
+  "updatedBy": "ios",
+  "testingIdentifiers": [],
+  "localizationKeys": [],
+  "accessibilityKeys": [],
+  "analyticsEvents": []
+}
+```
+
+### STEP 3 — Regenerate Catalog
+
+```bash
+cd "${COMMON_PATH}"
+.build/debug/FigmaRegistryUtility catalog
+```
+
+### STEP 4 — Update Confluence Status Dashboard
+
+```bash
+python3 "${REPO_ROOT}/.instructions/figma/figma-to-swiftui/scripts/confluence-component-status.py"
+```
+
+This updates the global Component Implementation Status dashboard on Confluence.
+Requires VPN. If VPN unavailable, inform user and skip.
+
+### STEP 5 — Summary
+
+```
+## Skip Summary
+
+| Field | Value |
+|-------|-------|
+| Component | {componentName} |
+| Node ID | {nodeId} |
+| File Key | {fileKey} |
+| Registry | Shared/Figma/Components/{nodeId}.json |
+| Status | Skipped |
+| Reason | {reason or "Not specified"} |
+| Confluence | Updated / Skipped (no VPN) |
+```
+
+---
+
+## Batch Mode
+
+Multiple URLs can be passed space-separated:
+
+```
+/figma-skip https://...?node-id=3-9045 https://...?node-id=14-893 --reason "Cursor components"
+```
+
+Process each URL sequentially. Run catalog regeneration and Confluence update once at the end (not per component).
+
+---
+
+## Error Handling
+
+- **FigmaRegistryUtility not built**: Run `swift build --product FigmaRegistryUtility` first.
+- **Node ID not found in registry**: Create new entry (the lookup may return a suggested name even for unknown nodes).
+- **VPN unavailable**: Skip Confluence update, inform user.

package/pipeline/skills/figma-common/figma-ui-patterns/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: figma-ui-patterns
+description: "Index of reusable SwiftUI UI-pattern guides (carousels, scroll tricks, animations, shaped views like scallops, pagers, parallax, gestures). Complementary to figma-to-swiftui and to vibe-coding: when a component needs a known UI pattern, pull the matching sub-guide from this skill instead of re-deriving the technique."
+user-invocable: true
+allowed-tools: Read, Glob, Grep
+status: wip-v5
+sourced-from: upstream/figma-ui-patterns
+---
+
+# /figma-ui-patterns — UI Pattern Index
+
+## Purpose
+
+Reusable SwiftUI UI-pattern guides, indexed in one place. Each pattern lives in its own sub-markdown under `patterns/` with a self-contained recipe — API shape, SwiftUI techniques, gotchas, and a minimal reference snippet.
+
+This skill is **complementary**, not gating:
+- During **spec-driven** work (figma-to-swiftui pipeline): phases reference patterns by slug when the architecture calls for one.
+- During **vibe coding**: invoke `/figma-ui-patterns` to browse the index, then open the matching sub-guide directly.
+
+## Layout
+
+```
+.instructions/figma/figma-ui-patterns/
+├── SKILL.md                     ← this file (index + conventions)
+└── patterns/
+    ├── carousel-pager.md        ← e.g., paged horizontal carousel
+    ├── scallop-view.md          ← e.g., concave-notch shape
+    ├── parallax-scroll.md
+    ├── sticky-header.md
+    ├── scroll-driven-animation.md
+    └── <new-pattern>.md
+```
+
+Each sub-guide is a single markdown file. No deeper nesting — flat under `patterns/`.
+
+## How to Use
+
+### As a reader (implementation time)
+
+1. Run `/figma-ui-patterns` to see the index below.
+2. Open `patterns/<slug>.md` for the pattern you need.
+3. Follow the recipe. Sub-guides are self-contained — you should not need to hop between them.
+
+### As an author (adding a new pattern)
+
+1. Pick a slug: `kebab-case`, descriptive, noun-phrase (`carousel-pager`, `scallop-view`, not `how-to-carousel`).
+2. Create `patterns/<slug>.md` using the template below.
+3. Add a row to the **Index** section of this file.
+4. Keep the guide under ~200 lines. If it grows beyond that, the pattern is probably two patterns — split it.
+
+## Sub-guide Template
+
+Every `patterns/<slug>.md` MUST include these sections, in this order:
+
+```markdown
+# <Human-Readable Pattern Name>
+
+## When to Use
+One paragraph. What visual/behavioral signal in the Figma design means "this is the pattern." What it is NOT (to avoid false positives).
+
+## Minimal API
+The smallest SwiftUI surface that implements this pattern. Signature + modifier chain, no business logic.
+
+## Technique
+Step-by-step SwiftUI recipe. Which primitives (ScrollView, GeometryReader, TimelineView, matchedGeometryEffect, Canvas, Shape, etc.), in what composition, with what state.
+
+## Gotchas
+Numbered list. Common mistakes, platform quirks (iOS version gates, accessibility regressions, performance cliffs).
+
+## Reference Snippet
+One complete, compilable SwiftUI snippet — under 60 lines. Should run as-is in an Xcode preview.
+
+## Related Patterns
+Bullet list of other slugs in this skill (or in `figma-price-integration`, `coreui-forms`, etc.) that commonly co-occur or contrast with this one.
+```
+
+## Authoring Rules
+
+1. **Self-contained.** A reader opening one sub-guide should implement the pattern without hopping.
+2. **SwiftUI-first.** Prefer pure SwiftUI techniques. Drop to UIViewRepresentable only when SwiftUI cannot express the behavior — and say so in Gotchas.
+3. **Design-token aware.** Use project tokens (`.Text.textPrimary`, `.bodyRegular`, etc.) in snippets, not raw colors/fonts. Keeps examples on-brand.
+4. **No component specifics.** A pattern is generic. If your recipe references `FlightCard` or `TripSummary`, you're writing a component guide, not a pattern guide — move it to the component's wiki instead.
+5. **Validate names before committing.** For the pattern's human-readable title, run `/intent-idempotency-check` if the name isn't already obvious — UI pattern names are easy to get wrong.
+
+## Integration with figma-to-swiftui
+
+- **Phase 3D (pattern detection):** when a scroll/motion/shape signal is detected, Phase 3D names the pattern by slug and cites `.instructions/figma/figma-ui-patterns/patterns/<slug>.md` for the implementation recipe.
+- **Phase 4B (view):** the view implementer reads the sub-guide, copies the Technique + Reference Snippet, and adapts to the component's Configuration.
+- **Phase 5 (testing):** snapshot + interaction tests should cover the pattern's key visual states; the sub-guide's Gotchas list is the checklist.
+
+## Index
+
+<!-- When adding a pattern, append a row here. Keep alphabetical by slug. -->
+
+| Slug | Pattern | Status |
+|------|---------|--------|
+| `carousel-banner` | Auto-advancing paged banner — single item visible, swipe/tap paging, `CarouselGroup` indicator, configurable interval + loop + pause-on-interaction. | Ready |
+| `scalloped-vstack` | Scalloped VStack (boarding-pass silhouette) — vertical card with semicircular edge cuts + dashed perforation line between segments. `CoreUI.ScallopedVStack`. | Ready |
+
+## Anti-patterns
+
+- **Dumping ground.** This is not a place for "here's a snippet I wrote once." A pattern appears here only if it is **reusable across ≥2 real components**.
+- **Pattern-by-component.** If every component gets its own pattern file, the index stops being useful. Generalize first.
+- **Stale snippets.** If a sub-guide's snippet no longer compiles on the project's current Swift/SwiftUI version, fix or remove it — don't leave a broken recipe.

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

@@ -0,0 +1,274 @@
+---
+name: figma-utility
+description: "On-demand Figma data utility. Fetch screenshots, metadata, properties, tokens, design context, Code Connect mappings, node data, component lists, styles, file summaries, and auth status from Figma via REST API and MCP."
+user-invocable: true
+argument-hint: screenshot <url> [--output path] | metadata <url> | properties <url> | tokens <url> | context <url> | code-connect <url> | node <url> | components <url> | styles <url> | file <url> | whoami | reset-branches
+allowed-tools: Bash, Read, Write, Glob, Grep, AskUserQuestion
+status: wip-v5
+sourced-from: upstream/figma-utility
+---
+
+# /figma-utility — On-Demand Figma Data Utility
+
+## Purpose
+
+Standalone utility for querying Figma data on demand. Exposes Figma REST API and MCP capabilities as simple sub-commands. Does **not** modify any project files or affect other skills.
+
+This is a **read-only data tool** — it fetches and displays Figma data. It does NOT implement, commit, or modify code.
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| Sub-command | Yes | One of: `screenshot`, `metadata`, `properties`, `tokens`, `context`, `code-connect`, `node`, `components`, `styles`, `file`, `whoami`, `reset-branches` |
+| Figma URL | Yes (except `whoami`) | `https://www.figma.com/design/{fileKey}/...?node-id={nodeId}` |
+| `--output` | No | Save output to a file path |
+| `--scale` | No | Screenshot scale 1-4 (default: 2) |
+| `--depth` | No | Depth limit for `node` and `file` commands |
+
+```
+/figma-utility screenshot https://www.figma.com/design/abc123/?node-id=123-456
+/figma-utility screenshot https://www.figma.com/design/abc123/?node-id=123-456 --output /tmp/shot.png
+/figma-utility metadata https://www.figma.com/design/abc123/?node-id=123-456
+/figma-utility properties https://www.figma.com/design/abc123/?node-id=123-456
+/figma-utility tokens https://www.figma.com/design/abc123/?node-id=123-456
+/figma-utility context https://www.figma.com/design/abc123/?node-id=123-456
+/figma-utility code-connect https://www.figma.com/design/abc123/?node-id=123-456
+/figma-utility node https://www.figma.com/design/abc123/?node-id=123-456 --depth 2
+/figma-utility components https://www.figma.com/design/abc123/
+/figma-utility styles https://www.figma.com/design/abc123/
+/figma-utility file https://www.figma.com/design/abc123/ --depth 1
+/figma-utility whoami
+```
+
+---
+
+## Parse Arguments
+
+1. Extract the **sub-command** (first argument after `/figma-utility`).
+2. Extract the **Figma URL** (if provided).
+3. Extract any **flags**: `--output <path>`, `--scale <N>`, `--depth <N>`.
+
+### URL Parsing
+
+```
+https://www.figma.com/design/{fileKey}/{fileName}?node-id={nodeId}
+```
+Convert `-` to `:` in node-id (e.g., `123-456` -> `123:456`).
+
+---
+
+## Constants
+
+```bash
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+SCRIPT="${REPO_ROOT}/.instructions/figma/figma-utility/scripts/figma-utility.py"
+```
+
+---
+
+## Sub-Command Reference
+
+### screenshot
+Get a PNG screenshot of a Figma node.
+- **Source:** REST API (primary) -> MCP (fallback)
+- **Requires:** fileKey + nodeId
+- **Options:** `--output <path>`, `--scale 1|2|3|4`
+
+### metadata
+Get layer hierarchy as XML for a node.
+- **Source:** MCP only (`get_metadata`)
+- **Requires:** fileKey + nodeId
+- **Options:** `--output <path>`
+
+### properties
+Get component properties, variant axes, types, and defaults.
+- **Source:** REST API (`/files/{key}/nodes?ids={nodeId}`)
+- **Requires:** fileKey + nodeId
+- **Options:** `--output <path>`
+
+### tokens
+Get design tokens / variable definitions for a node.
+- **Source:** MCP (primary, `get_variable_defs`) -> REST API fallback
+- **Requires:** fileKey + nodeId
+- **Options:** `--output <path>`
+
+### context
+Get design context (generated reference code) for a node.
+- **Source:** MCP only (`get_design_context`)
+- **Requires:** fileKey + nodeId
+- **Options:** `--output <path>`
+
+### code-connect
+Get Code Connect source mappings for a node.
+- **Source:** MCP only (`get_code_connect_map`)
+- **Requires:** fileKey + nodeId
+- **Options:** `--output <path>`
+
+### node
+Get raw node data from Figma REST API.
+- **Source:** REST API (`/files/{key}/nodes?ids={nodeId}`)
+- **Requires:** fileKey + nodeId
+- **Options:** `--output <path>`, `--depth <N>`
+
+### components
+List all components in a Figma file.
+- **Source:** REST API (`/files/{key}/components`)
+- **Requires:** fileKey only (nodeId not needed)
+- **Options:** `--output <path>`
+
+### styles
+Get all styles in a Figma file.
+- **Source:** REST API (`/files/{key}/styles`)
+- **Requires:** fileKey only (nodeId not needed)
+- **Options:** `--output <path>`
+
+### file
+Get file summary: pages, last modified, version.
+- **Source:** REST API (`/files/{key}`)
+- **Requires:** fileKey only (nodeId not needed)
+- **Options:** `--output <path>` (saves full tree), `--depth <N>`
+
+### whoami
+Check MCP authentication status.
+- **Source:** MCP (`whoami` on remote, connection check on local)
+- **Requires:** Nothing
+
+### reset-branches
+Reset all repo branches (main + submodules) to their remote defaults. Discards local changes.
+- **Source:** Git
+- **Requires:** Nothing
+- **Options:** None
+
+**IMPORTANT — run as a single Bash call.** `REPO_ROOT` must be resolved once before any `cd` into submodules; if split into separate Bash calls, `git rev-parse --show-toplevel` inside a submodule returns the submodule root, not the main repo.
+
+```bash
+REPO_ROOT="$(git rev-parse --show-toplevel)" && \
+cd "${REPO_ROOT}" && git checkout develop && git fetch origin && git reset --hard origin/develop && \
+cd "${REPO_ROOT}/{repos.common.path}" && \
+  (git stash -u 2>/dev/null || true) && git checkout iteration/develop && git fetch origin && git reset --hard origin/iteration/develop && \
+cd "${REPO_ROOT}/{repos.components.path}" && \
+  (git stash -u 2>/dev/null || true) && git checkout iteration/develop && git fetch origin && git reset --hard origin/iteration/develop
+```
+
+**Output Format:**
+```
+Branches reset to remote:
+  figma:         develop → origin/develop ({sha})
+  common:        iteration/develop → origin/iteration/develop ({sha})
+  uicomponents:  iteration/develop → origin/iteration/develop ({sha})
+```
+
+---
+
+## Execution
+
+Run the Python script. Build the command from parsed arguments:
+
+```bash
+python3 "${SCRIPT}" <sub-command> \
+    --url "<figma-url>" \
+    [--output "<path>"] \
+    [--scale <N>] \
+    [--depth <N>]
+```
+
+### Examples
+
+```bash
+# Screenshot with output
+python3 "${SCRIPT}" screenshot --url "https://www.figma.com/design/abc/File?node-id=123-456" --output /tmp/screenshot.png
+
+# Metadata to stdout
+python3 "${SCRIPT}" metadata --url "https://www.figma.com/design/abc/File?node-id=123-456"
+
+# Properties saved to file
+python3 "${SCRIPT}" properties --url "https://www.figma.com/design/abc/File?node-id=123-456" --output /tmp/props.json
+
+# File summary with depth limit
+python3 "${SCRIPT}" file --url "https://www.figma.com/design/abc/File" --depth 1
+
+# Auth check
+python3 "${SCRIPT}" whoami
+```
+
+---
+
+## Output Formatting
+
+After the script runs:
+
+1. **JSON output:** Pretty-print the key fields to the user in a readable format.
+2. **XML output** (metadata): Show it as a code block.
+3. **Large output** (context, node): Summarize key points, suggest `--output` if not used.
+4. **Errors:** Show the error message and hint clearly.
+
+### Screenshot Output Format
+```
+Screenshot captured for node {nodeId}
+Source: {rest-api | mcp-local | mcp-remote}
+Saved: {output_path}  (if --output used)
+URL: {url}             (if REST API, no --output)
+```
+
+### Properties Output Format
+```
+Component: {name} ({type})
+Variants: {variantCount}
+Properties ({propertyCount}):
+  - {propName}: {type} = {defaultValue} [options: ...]
+  - ...
+```
+
+---
+
+## Data Source Matrix
+
+| Command | REST API | MCP Local | MCP Remote |
+|---------|----------|-----------|------------|
+| screenshot | primary | fallback | fallback |
+| metadata | - | primary | fallback |
+| properties | primary | - | - |
+| tokens | fallback | primary | fallback |
+| context | - | primary | fallback |
+| code-connect | - | primary | fallback |
+| node | primary | - | - |
+| components | primary | - | - |
+| styles | primary | - | - |
+| file | primary | - | - |
+| whoami | - | connection check | whoami call |
+
+---
+
+## Token Resolution
+
+Tokens are resolved automatically by the script:
+
+1. **REST API token:** `--figma-token` CLI arg > macOS Keychain `FIGMA_ACCESS_TOKEN`
+2. **MCP token:** `--mcp-token` CLI arg > Keychain `FIGMA_MCP_TOKEN` > Claude Code credentials
+
+If no tokens are found, the script reports what's missing and suggests running `/figma-setup`.
+
+---
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| No Figma URL provided | Ask user for URL |
+| Invalid sub-command | Show available commands |
+| MCP unavailable (for MCP-only commands) | Report error, suggest Figma Desktop or remote token |
+| REST API 403 | Report token issue, suggest /figma-setup |
+| REST API 404 | Report file/node not found |
+| No tokens found | Suggest /figma-setup |
+
+---
+
+## Independence
+
+This skill is **completely independent** from other Figma skills. It:
+- Has its own script (`figma-utility.py`) — no shared imports
+- Does not read or write implementation artifacts
+- Does not modify the component registry
+- Does not create branches or commits (except `reset-branches` which resets to remote)
+- Can be used alongside any other skill without conflict