@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/figma-common/figma-price-integration/SKILL.md

@@ -0,0 +1,398 @@
+---
+name: figma-price-integration
+description: "Price pattern integration for Figma-to-SwiftUI components. Guides PriceRepresentable protocol adoption when a component displays price data."
+user-invocable: true
+allowed-tools: Read, Glob, Grep
+status: wip-v5
+sourced-from: upstream/figma-price-integration
+---
+
+# /figma-price-integration — Price Pattern Integration
+
+## Purpose
+
+This skill is consumed by other skills (Phase 3D pattern detection, Phase 4A configuration, Phase 4B view implementation) when a **price pattern** is detected in a Figma component. It defines how to model price data using the `PriceRepresentable` protocol instead of raw strings or ad-hoc models.
+
+It is also **user-invocable** for vibe-coding / ad-hoc work: whenever you are wiring up a component that displays price data outside the full figma-to-swiftui pipeline, run `/figma-price-integration` to apply the same rules.
+
+---
+
+## Strict Rules (non-negotiable)
+
+1. **Any price data MUST go through `PriceRepresentable`.** No raw `String` prices, no ad-hoc `(amount, currency)` tuples, no custom price structs that skip the protocol. This applies to:
+   - A standalone `Price` view / component instance.
+   - An `AttributedString` / `CurrencyTextRenderer` inline price inside surrounding text.
+   - Any nested `Price` sub-component detected in Figma.
+   If you see either of those two cases → PriceRepresentable, always.
+2. **Price belongs in Configuration, not View — if a Configuration exists.** When the component has a Configuration struct, the nested `Price: PriceRepresentable` type MUST be declared inside Configuration and the `price` property MUST live on Configuration. Only components with NO Configuration may nest `Price` inside the View.
+3. **The View never owns price data.** It reads `configuration.price` and renders. No raw amount/currency properties on the View when a Configuration exists.
+4. **Nested `Price` mirrors the design exactly.** The nested `Price` type declares ONLY the protocol properties the component actually uses — do not include fields the design doesn't render, and do not drop fields the design does render. The struct's shape is dictated by the design, not by developer convenience or a shared/generic price model.
+
+---
+
+## When to Invoke This Skill
+
+Invoke when ANY of these are detected:
+
+1. **Phase 3D — Layer Text Classification (section 1.5.1):** A currency code + numeric amount pair (e.g., "TRY" + "10.000")
+2. **Phase 3D — Sub-Component Integration (section 2.2):** A nested `Price` component instance
+3. **Phase 4A — Configuration:** A property group contains price-related fields (amount, currency, originalAmount, etc.)
+4. **Phase 4B — View:** The view renders price data using `Price`, `CurrencyTextRenderer`, or similar
+
+---
+
+## Architecture
+
+```
+Backend DTO
+    |
+    v
+ComponentName.Price : PriceRepresentable  (component-specific, only needed fields)
+    |
+    v  .toConfiguration()  [protocol extension, shared]
+PriceConfiguration  [internal to Price view]
+    |
+    v
+Price view renders
+```
+
+### Key Files
+
+| File | Location | Purpose |
+|------|----------|---------|
+| `PriceRepresentable.swift` | `DesignSystemCore/Price/Price/` | Protocol + `PriceSign` enum + `toConfiguration()` |
+| `PriceUIModel.swift` | `DesignSystemCore/Price/Price/` | Full conformance with all properties |
+| `PriceConfiguration.swift` | `DesignSystemCore/Price/Price/` | Internal formatted representation (not the public API) |
+| `CurrencyTextRenderer.swift` | `DesignSystemCore/Price/Price/` | AttributedString rendering for inline price text |
+
+---
+
+## The Protocol
+
+```swift
+public protocol PriceRepresentable: Sendable, Equatable {
+    var amount: Double { get }           // required
+    var currency: String { get }         // required
+    var originalAmount: Double? { get }  // default: nil
+    var saleBadgeText: String? { get }   // default: nil
+    var milesValue: Int? { get }         // default: nil
+    var sign: PriceSign? { get }         // default: nil
+    var milesDisplay: PriceConfiguration.MilesDisplay { get }  // default: .slash
+    var showPrimaryMil: Bool { get }     // default: false
+    var hideCurrency: Bool { get }       // default: false
+    var showLeadingText: Bool { get }    // default: true
+}
+```
+
+All properties except `amount` and `currency` have protocol-level defaults. Conformers only declare the properties they actually use.
+
+### PriceSign
+
+```swift
+public enum PriceSign: String, Sendable, Equatable {
+    case positive  // green, + prefix (refund, earning, credit)
+    case negative  // red, - prefix (charge, fee, deduction)
+}
+// nil = standard black text, no prefix
+```
+
+---
+
+## How to Create a Component-Specific Model
+
+**Rule: Each component defines its own nested `.Price` type conforming to `PriceRepresentable`.** The nested type exposes ONLY the properties that component accepts — no silent discard of unused props.
+
+### Step 1: Determine Which Properties the Component Needs
+
+From the Figma design, identify which price features are used:
+
+| Feature | Property | Include If... |
+|---------|----------|---------------|
+| Current price | `amount: Double`, `currency: String` | Always (required) |
+| Discount/original price | `originalAmount: Double?` | Strikethrough price visible |
+| Sale badge | `saleBadgeText: String?` | Badge like "%30" visible |
+| Miles section | `milesValue: Int?` | "/ 2000 Mil" visible |
+| Green/red sign | `sign: PriceSign?` | + or - prefix, colored text |
+| Miles display mode | `milesDisplay` | Multiple miles sections |
+| Miles-only pricing | `showPrimaryMil: Bool`, `hideCurrency: Bool` | Amount IS miles, no currency |
+| Leading label | `showLeadingText: Bool` | "Toplam Tutar" label toggleable |
+
+### Step 2: Define the Nested Type
+
+**If the component has a Configuration struct (default case):** Nest inside Configuration. The `price` property lives on Configuration, never on the View. This is strict — see Rule 2.
+
+```swift
+public struct SomeCardConfiguration: Sendable {
+    // Nested price model — only amount + currency needed
+    public struct Price: PriceRepresentable {
+        public let amount: Double
+        public let currency: String
+
+        public init(amount: Double, currency: String) {
+            self.amount = amount
+            self.currency = currency
+        }
+    }
+
+    public let title: String
+    public let price: Price?  // nil = no price section
+    // ...
+}
+```
+
+**If the component has NO Configuration (fallback only):** Nest inside the View. Use this ONLY when the component is a simple SIMPLE-tier view without a Configuration struct.
+
+```swift
+public struct SomeBadge: View {
+    public struct Price: PriceRepresentable {
+        public let amount: Double
+        public let currency: String
+
+        public init(amount: Double, currency: String) {
+            self.amount = amount
+            self.currency = currency
+        }
+    }
+
+    private let price: Price
+    // ...
+}
+```
+
+### Step 3: Use in the View
+
+**Option A — Full Price view (standalone price display):**
+
+```swift
+Price(price)          // init(_ price: some PriceRepresentable)
+    .size(.medium)    // visual modifiers chain after
+    .line(.single)
+```
+
+**Option B — Inline price in attributed text (price + surrounding text):**
+
+Use when price appears within a text sentence (e.g., "TRY 10.000 dan başlayan fiyatlarla").
+The price is NOT a standalone view — it's a styled segment inside an `AttributedString`.
+
+```swift
+// 1. Template from localization: "%@ dan başlayan fiyatlarla"
+var template = AttributedString(localized: .Component.startingFromPrice)
+template.font = .bodyRegular
+template.foregroundColor = .Text.textGrey
+
+// 2. Price as AttributedString via PriceRepresentable convenience
+let priceAttr = price.attributedString(style: CurrencyTextStyle(
+    currencyFont: .smallRegular,
+    amountFont: .smallBold,
+    color: .Text.textPrimary
+))
+
+// 3. Compose with AttributedString.format() from UIExtensions
+Text(template.format(priceAttr))
+```
+
+**This pattern must be explicitly identified during Phase 3D analysis (section 1.5.1b).**
+Check the Figma layer structure — if the price and surrounding text are in the same text layer
+with different font styles, it's inline attributed text, NOT a standalone Price view + separate Text.
+
+**Option C — CurrencyTextRenderer (standalone inline price without surrounding text):**
+
+```swift
+let config = price.toConfiguration()
+let attributed = CurrencyTextRenderer.attributedString(
+    amount: config.amount,
+    decimalPart: config.decimalPart,
+    currencyCode: config.currencyCode,
+    currencyPlacement: config.currencyPlacement,
+    style: CurrencyTextStyle(
+        currencyFont: .smallRegular,
+        amountFont: .smallBold,
+        color: .Text.textPrimary
+    )
+)
+Text(attributed)
+```
+
+**Option D — Direct formatted amount (custom rendering):**
+
+```swift
+let config = price.toConfiguration()
+// Use config.amount, config.decimalPart, config.currencyCode etc.
+// for custom layout that doesn't fit the Price view pattern
+```
+
+---
+
+## Configuration vs Style Separation
+
+**In the PriceRepresentable model (semantic/data):**
+- `sign` — backend says refund/charge
+- `milesDisplay` — business rule
+- `showPrimaryMil` — miles-only pricing
+- `hideCurrency` — miles-only mode
+- `showLeadingText` — contextual label
+
+**NOT in the model (visual, set via view modifiers):**
+- `size` — parent component decides
+- `alignment` — layout concern
+- `line` (single/double) — layout concern
+
+**Auto-resolved (not in model):**
+- `currencyPlacement` — derived from `CurrencyFormatProvider` per currency code
+
+---
+
+## Integration with Phase 3D
+
+When Phase 3D's Layer Text Classification (section 1.5.1) detects a price pattern:
+
+### Replace section 1.5.1 Output
+
+Instead of:
+```
+- amount: Double (LAYER_TEXT, IMPLEMENT)
+- currencyCode: String (LAYER_TEXT, IMPLEMENT)
+```
+
+Output:
+```
+- price: ComponentName.Price (PRICE_PATTERN, IMPLEMENT)
+  → PriceRepresentable conformance with: amount, currency
+  → Additional properties if detected: originalAmount, saleBadgeText, milesValue, sign
+```
+
+### Architecture Output (04b_component_architecture.md)
+
+In the Sub-Components section:
+```markdown
+## Sub-Components
+
+| Element | Scope | Integration |
+|---------|-------|-------------|
+| Price | {Optional/Required} | `PriceRepresentable` — nested `Price` struct with {list fields} |
+```
+
+In the Final API Design:
+```swift
+// Nested PriceRepresentable model
+public struct Price: PriceRepresentable {
+    public let amount: Double
+    public let currency: String
+    // ... only the fields this component needs
+}
+
+// In init or configuration
+public let price: Price    // required
+// OR
+public let price: Price?   // optional (nil = no price section)
+```
+
+---
+
+## Integration with Phase 4A
+
+When writing the Configuration struct for a COMPLEX component that contains price data:
+
+1. Define the nested `Price: PriceRepresentable` struct inside the Configuration
+2. Only include the properties identified in Phase 3D analysis
+3. The price property is `Price?` if the price section is boolean-gated, `Price` if always present
+4. Do NOT flatten price fields into the Configuration — keep them grouped in the nested type
+
+```swift
+@GenerateChainModifiers
+public struct SomeComponentConfiguration: Sendable {
+
+    public struct Price: PriceRepresentable {
+        public let amount: Double
+        public let currency: String
+        public let originalAmount: Double?
+
+        public init(amount: Double, currency: String, originalAmount: Double? = nil) {
+            self.amount = amount
+            self.currency = currency
+            self.originalAmount = originalAmount
+        }
+    }
+
+    public let title: String
+    public let price: Price?
+
+    public init(title: String = "", price: Price? = nil) {
+        self.title = title
+        self.price = price
+    }
+}
+```
+
+---
+
+## Integration with Phase 4B
+
+When implementing the View that renders price data:
+
+### Using the Price View
+
+```swift
+if let price = configuration.price {
+    Price(price)
+        .size(.medium)       // component decides size
+        .line(.single)       // component decides layout
+        .showLeadingText(false)  // override if needed
+}
+```
+
+### Using CurrencyTextRenderer (for inline price in text)
+
+```swift
+if let price = configuration.price {
+    let config = price.toConfiguration()
+    Text(CurrencyTextRenderer.attributedString(
+        amount: config.amount,
+        decimalPart: config.decimalPart,
+        currencyCode: config.currencyCode,
+        currencyPlacement: config.currencyPlacement,
+        style: CurrencyTextStyle(
+            currencyFont: currencyFont,
+            amountFont: amountFont,
+            color: priceColor
+        )
+    ))
+}
+```
+
+---
+
+## When NOT to Use PriceRepresentable
+
+- **Static price labels** with no real data binding (e.g., placeholder text in a design mockup)
+- **Non-currency numeric amounts** (counts, percentages, scores) — these are plain `Int`/`Double`/`String`
+- **Price data that is purely a display string** from the backend with no formatting needed — use `String` directly
+
+---
+
+## Full PriceUIModel
+
+For the core `Price` view used standalone (not inside a compound component), use `PriceUIModel` directly:
+
+```swift
+Price(PriceUIModel(amount: 12810.99, currency: "TRY",
+                   originalAmount: 14920.00, saleBadgeText: "%30"))
+    .size(.large)
+    .state(.positive)
+```
+
+`PriceUIModel` carries ALL properties. Component-specific nested types carry only what they need.
+
+---
+
+## Real-World Scenarios
+
+| Scenario | Model |
+|----------|-------|
+| Flight search result | `(amount: 12810.99, currency: "TRY")` |
+| Discounted flight | `(amount: 12810.99, currency: "TRY", originalAmount: 14920.00, saleBadgeText: "%30")` |
+| Refund confirmation | `(amount: 5000.00, currency: "TRY", sign: .positive)` |
+| Extra baggage charge | `(amount: 200.00, currency: "USD", sign: .negative)` |
+| Miles-only pricing | `(amount: 45000, currency: "TRY", showPrimaryMil: true, hideCurrency: true)` |
+| Money + miles | `(amount: 12810.99, currency: "TRY", milesValue: 2000, milesDisplay: .slash)` |
+| Price badge (lean) | `(amount: 42000, currency: "TRY")` — only 2 fields |

package/pipeline/skills/figma-common/figma-remote-mcp-auth/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: figma-remote-mcp-auth
+description: Runs Figma Remote MCP OAuth flow to obtain and store a token in macOS Keychain. Requires OAuth client credentials.
+user-invocable: true
+argument-hint: <client-id> <client-secret>
+allowed-tools: Bash, Read, AskUserQuestion
+status: wip-v5
+sourced-from: upstream/figma-remote-mcp-auth
+---
+
+# /figma-remote-mcp-auth — Figma Remote MCP OAuth Token
+
+Runs the Figma MCP OAuth flow via browser, exchanges the authorization code for an access token, verifies it, and saves it to macOS Keychain as `FIGMA_MCP_TOKEN`.
+
+---
+
+## Parse Input
+
+The skill expects two positional arguments: `<client-id>` and `<client-secret>`.
+
+| Input | Action |
+|-------|--------|
+| `<client-id> <client-secret>` | Run OAuth flow with provided credentials |
+| (no args) | Attempt auto-extraction from Claude Code credentials |
+| `--show-clients` | Show registered OAuth clients from Claude Code credentials |
+
+---
+
+## Step 1: Resolve Credentials
+
+### If both arguments provided:
+Use them directly as `CLIENT_ID` and `CLIENT_SECRET`.
+
+### If no arguments provided:
+Try auto-extraction from Claude Code credentials:
+
+```bash
+python3 .instructions/figma/figma-setup/scripts/fetch-mcp-token.py --show-clients 2>&1
+```
+
+- If clients found → use the first Figma client's `clientId` and `clientSecret`
+- If no clients found → HALT:
+
+> No OAuth client credentials provided and none found in Claude Code credentials.
+>
+> **Usage:** `/figma-remote-mcp-auth <client-id> <client-secret>`
+>
+> **To find credentials:**
+> 1. Ask a colleague who has Figma Remote MCP configured in Claude Code
+> 2. They can run: `/figma-remote-mcp-auth --show-clients`
+> 3. Share the `clientId` and `clientSecret` values
+
+---
+
+## Step 2: Run OAuth Flow
+
+```bash
+python3 .instructions/figma/figma-setup/scripts/fetch-mcp-token.py --oauth --client-id "$CLIENT_ID" --client-secret "$CLIENT_SECRET" --save-keychain --verify
+```
+
+This will:
+1. Start a local callback server on port 8923
+2. Open the browser for Figma consent
+3. Wait for the user to authorize (120s timeout)
+4. Exchange the authorization code for an access token (PKCE)
+5. Verify the token against `https://mcp.figma.com/mcp`
+6. Save the token to macOS Keychain as `FIGMA_MCP_TOKEN`
+
+**IMPORTANT:** Do NOT echo or display the token in chat. The script handles all output to stderr (logging) and stdout (token). Capture stdout but do not print it.
+
+---
+
+## Step 3: Verify Result
+
+Check script exit code:
+- `0` → Success
+- `1` → OAuth flow failed (timeout, user denied, no credentials)
+- `2` → Token verification failed (invalid token)
+- `3` → Keychain save failed
+
+### On success:
+```
+FIGMA_MCP_TOKEN stored in macOS Keychain.
+
+The token is now available for:
+- Figma-to-SwiftUI scripts (phase1-gather.py, remote-mcp-fetch.py)
+- /figma-setup CHECK 3b (will detect existing token)
+- Any tool that reads FIGMA_MCP_TOKEN from Keychain
+```
+
+### On failure:
+Display the stderr output from the script and suggest:
+- Check that Figma Desktop is not blocking the OAuth consent
+- Try a different port: add `--port 9147` if port 8923 is in use
+- Ensure the client credentials are valid
+
+---
+
+## Notes
+
+- **Token expiry**: Tokens expire when Figma revokes them or Claude Code refreshes its session. Re-run this skill to get a new token.
+- **Token portability**: The token is tied to the Figma account that consents in the browser, not to the machine. It works across devices.
+- **Security**: Client credentials are NOT stored by this skill. They must be provided each time or auto-extracted from Claude Code.
+- **Colleague onboarding**: Share the `clientId` and `clientSecret` with colleagues so they can run this skill independently.