@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/figma-ios/figma-to-component/reference/macros.md

@@ -0,0 +1,227 @@
+# CONFIGURATION MACROS REFERENCE
+
+Macros for generating configuration boilerplate code.
+
+---
+
+## MACROS
+
+### @GenerateChainModifiers
+
+Applied to Configuration structs. Generates:
+- Private `modified()` helper
+- Chain modifier methods for each property
+- Localized variants for String properties
+
+```swift
+@GenerateChainModifiers
+public struct ComponentConfiguration {
+    public let title: String
+    public let count: Int
+    public let isEnabled: Bool
+}
+// GENERATED: .title(_), .title(localized:), .count(_), .isEnabled(_)
+```
+
+### @GenerateConfiguredInit (LEGACY — being replaced)
+
+Applied to View structs. Generates:
+- Default init with `@autoclosure` configuration
+- Configure init with closure
+- `configured()` method
+
+**NOTE:** This macro is being replaced by `@GenerateViewConfiguration` for new components. Existing components may still use it until migrated.
+
+```swift
+@GenerateConfiguredInit
+public struct Component: View {
+    private let configuration: ComponentConfiguration
+    public var body: some View { ... }
+}
+// GENERATED: init(configuration:), init(configure:), configured(_:)
+```
+
+### @GenerateViewConfiguration (NEW — preferred)
+
+Applied to View structs. Generates ONLY:
+- `configured()` method — post-init configuration transform
+
+Does NOT generate:
+- **Inits** — AI writes custom inits tailored to each component's needs
+- **View-level forwarding modifiers** — Swift macros cannot introspect types they're not attached to, so the macro cannot read Configuration struct properties. Phase 4E (AI) writes the +Modifiers file.
+
+```swift
+@GenerateViewConfiguration
+public struct Component: View {
+    private let configuration: ComponentConfiguration
+    private let action: () -> Void
+
+    // AI-written custom init — required props + closures
+    public init(title: String, action: @escaping () -> Void) {
+        self.configuration = .init(title: title)
+        self.action = action
+    }
+
+    public var body: some View { ... }
+}
+// GENERATED: configured(_:)
+// NOT GENERATED: init (AI writes), forwarding modifiers (Phase 4E writes +Modifiers.swift)
+```
+
+**Why:** `@GenerateConfiguredInit` treats config as an opaque blob — it can't distinguish required vs optional props, can't pair data+closure, and generates a configure closure init that is an anti-pattern. `@GenerateViewConfiguration` gives AI full control over init shape while the macro handles only the mechanical `configured()` boilerplate.
+
+**`configured()` is internal API.** It is used ONLY inside +Modifiers forwarding methods and paired modifiers. Consumers use the named forwarding modifiers (`.state()`, `.title()`) and paired modifiers (`.secondaryButton(title) { action }`). Never expose `configured()` in Code Connect, previews, or usage examples.
+
+---
+
+## HELPER ATTRIBUTES
+
+| Attribute | Effect |
+|-----------|--------|
+| `@IgnoreChainModifier` | Skip property from chain modifier generation |
+| `@ChainModifierName("name")` | Custom method name for property |
+| `@IgnoreLocalization` | Skip localized variant for String property |
+
+---
+
+## PROPERTY DETECTION
+
+| Property Pattern | @GenerateConfiguredInit Behavior |
+|------------------|----------------------------------|
+| `*Configuration` type | Configuration property |
+| `@Binding var x` | Dependency → `self._x = x` |
+| `@State var x` | **Skipped** |
+| `@StateObject var x` | **Skipped** |
+| `@Environment var x` | **Skipped** |
+| `@ObservedObject var x` | Dependency → `self.x = x` |
+| `let x: Type` | Dependency → `self.x = x` |
+| `let x: () -> Void` | Closure dependency → `@escaping`, placed **after** config param |
+
+### Parameter Ordering
+
+Non-closure dependencies come **before** the configuration parameter; closure dependencies come **after** it. This enables natural trailing-closure syntax:
+
+```swift
+// Generated: init(_ configure: (Config) -> Config, action: @escaping () -> Void)
+TurkishButton { config in
+    config.title("Book Now").style(.primary)
+} action: {
+    viewModel.bookNow()
+}
+```
+
+---
+
+## USAGE RULES
+
+**Simple Component (≤3 properties):** No configuration needed. Direct init parameters.
+
+**Complex Component (>3 properties):** Use Configuration struct + macros:
+
+```swift
+@GenerateChainModifiers
+public struct ComponentConfiguration {
+    public let title: String
+    public let subtitle: String?
+    public let style: Style
+
+    public init(
+        title: String = "",
+        subtitle: String? = nil,
+        style: Style = .default
+    ) { ... }
+}
+
+@GenerateViewConfiguration
+public struct Component: View {
+    private let configuration: ComponentConfiguration
+    private let action: () -> Void
+
+    // AI-written init: required props + closures
+    public init(title: String, action: @escaping () -> Void) {
+        self.configuration = .init(title: title)
+        self.action = action
+    }
+
+    public var body: some View { ... }
+}
+
+// Usage — required in init, optional via chain modifiers
+Component(title: "Hello") { doSomething() }
+    .subtitle("World")
+    .style(.primary)
+```
+
+### With Dependencies
+
+```swift
+@GenerateViewConfiguration
+public struct Component: View {
+    private var configuration: ComponentConfiguration
+    @Binding private var isExpanded: Bool
+
+    public init(title: String, isExpanded: Binding<Bool>) {
+        self.configuration = .init(title: title)
+        self._isExpanded = isExpanded
+    }
+
+    public var body: some View { ... }
+}
+```
+
+### With Paired Modifiers
+
+```swift
+@GenerateViewConfiguration
+public struct BottomActions: View {
+    private var configuration: BottomActionsConfiguration
+    private let primaryAction: () -> Void
+    private var secondaryAction: (() -> Void)?
+
+    public init(primaryButtonTitle: String, primaryAction: @escaping () -> Void) {
+        self.configuration = .init(primaryButtonTitle: primaryButtonTitle)
+        self.primaryAction = primaryAction
+    }
+
+    // Paired modifier — binds title + action atomically
+    public func secondaryButton(_ title: String, action: @escaping () -> Void) -> Self {
+        var copy = self
+        copy.configuration.secondaryButtonTitle = title
+        copy.secondaryAction = action
+        return copy
+    }
+
+    public var body: some View { ... }
+}
+
+// Usage
+BottomActions(primaryButtonTitle: "OK") { submit() }
+    .secondaryButton("Cancel") { cancel() }
+    .state(.scroll)
+```
+
+---
+
+## OPTIONAL PROPERTY PATTERN
+
+Double-optional (`T??`) for distinguishing:
+- `nil` (outer) → keep existing value
+- `.some(nil)` → explicitly set to nil
+- `.some(.some(value))` → set to value
+
+```swift
+@GenerateChainModifiers
+public struct Config {
+    public let subtitle: String?
+    // GENERATED modified(): subtitle: String?? = nil
+}
+```
+
+---
+
+## IMPORTS
+
+```swift
+import UIMacros       // @GenerateChainModifiers, @GenerateViewConfiguration (new), @GenerateConfiguredInit (legacy)
+import UILocalization // LocalizationStringKey (localized variants)
+```

package/pipeline/skills/figma-ios/figma-to-component/reference/missing-tokens.md

@@ -0,0 +1,157 @@
+# MISSING TOKEN HANDLING
+
+Resolve missing Figma tokens during component implementation.
+
+All source files are in `{project.slug}-common` (run commands from that directory).
+
+---
+
+## STEP 1: CLASSIFY THE MISSING TOKEN
+
+Missing tokens from `pass3/02_token_mapping.md` fall into two categories:
+
+| Category | What It Means | Example |
+|----------|--------------|---------|
+| **Typography alias** | Figma uses a new style name for an existing Swift token | `Caption/Regular/sm` → existing `.xSmallRegular` |
+| **Truly missing** | No Swift token exists — must be added to source | `Black White/25` color not in `Mode.json` |
+
+**How to tell:** Extract font size + weight from the design context for the missing style. Look up the existing registry — if a token with the same size + weight exists, it's an alias. If not, it's truly missing.
+
+---
+
+## STEP 2: LOOKUP EXISTING TOKENS
+
+### Typography
+```bash
+.build/debug/FigmaRegistryUtility typography-lookup --styles '<STYLE_NAMES_CSV>' --json
+```
+
+Returns per style: `{"status": "found", "swiftToken": ".h3", "fontSize": 24, "fontWeight": 600}` or `{"status": "not_found"}`
+
+### Variables (colors, spacing, radius)
+```bash
+.build/debug/FigmaRegistryUtility ui-token-lookup --variables '<TOKEN_NAMES_CSV>' --json
+```
+
+Returns: `{"Token/Name": "color:.BlackWhite.n100"}` or `{"Token/Name": null}`
+
+---
+
+## STEP 3A: RESOLVE TYPOGRAPHY ALIASES
+
+When a missing typography token maps to an existing Swift token (same font size + weight):
+
+**Add an alias entry to `Shared/Figma/Generated/typography-registry.json`:**
+
+```json
+{
+  "figmaName": "Caption/Regular/sm",
+  "swiftToken": ".xSmallRegular",
+  "alias": true,
+  "fontSize": 12,
+  "fontWeight": 400,
+  "nodeId": "<copy from target token>",
+  "fontFamily": "<copy from target token>",
+  "lineHeightPx": "<copy from target token>"
+}
+```
+
+**Match by font properties** — extract from design_context_response.json:
+
+| Font Size | Weight 400 (Regular) | Weight 600 (Bold) |
+|-----------|---------------------|-------------------|
+| 9 | `.extraMiniRegular` | `.extraMiniBold` |
+| 10 | `.miniRegular` | `.miniBold` |
+| 11 | `.captionRegular` | `.captionBold` |
+| 12 | `.xSmallRegular` | `.xSmallBold` |
+| 14 | `.smallRegular` | `.smallBold` |
+| 16 | `.bodyRegular` | `.bodyBold` |
+| 18 (w400) | `.h6Regular` | `.h6` |
+| 20 | `.h5Regular` | `.h5` |
+| 24 | `.h3Regular` | `.h3` |
+| 28 | `.h2Regular` | `.h2` |
+| 32 | — | `.h1` |
+
+**Verify after adding:**
+```bash
+.build/debug/FigmaRegistryUtility typography-lookup --styles '<NEW_ALIAS_NAME>' --json
+```
+
+---
+
+## STEP 3B: ADD TRULY MISSING TOKENS
+
+### Colors
+
+**Source file:** `Shared/UIAssets/Colors/{Catalog}.json`
+
+| Figma Prefix | Catalog File |
+|-------------|-------------|
+| `Black White/*` | `Mode.json` |
+| `Text/*` | `Alias.json` |
+| `Background/*` | `Alias.json` |
+| `Brand/*` | `Brand.json` |
+
+**Add the entry** to the appropriate group's `items` array:
+```json
+{ "name": "25", "light": "#F6F6F6", "dark": "#0A0A0A" }
+```
+
+For universal colors (same in light/dark): `{ "name": "25", "universal": "#F6F6F6" }`
+
+**Regenerate:**
+```bash
+swift package plugin --allow-writing-to-package-directory generate-ui-assets
+```
+
+This generates:
+- `iOS/Sources/UIAssets/Generated/UIAssetsGeneratedTokens.swift` (Swift enum cases)
+- Updates `Shared/Figma/Generated/ui-token-registry.json`
+
+**Update token index:**
+```bash
+.build/debug/FigmaRegistryUtility ui-token-index
+```
+
+If `ui-token-index` doesn't pick up the new token (registry not updated), add it directly to `Shared/Figma/Generated/ui-token-index.json` (sorted flat list of token strings like `"color:.BlackWhite.n25"`).
+
+### Numbers (Spacing, Radius, BorderWidth)
+
+**Source file:** `Shared/UIAssets/Numbers/Numbers.json`
+
+**Add to the appropriate group's `values` object:**
+```json
+"Spacing": {
+  "values": {
+    "Spacing2": 2,
+    "NewToken": <value>
+  }
+}
+```
+
+**Regenerate:** Same `generate-ui-assets` command + `ui-token-index`.
+
+---
+
+## STEP 4: VERIFY
+
+```bash
+# Typography
+.build/debug/FigmaRegistryUtility typography-lookup --styles '<STYLE_NAME>' --json
+
+# Variables
+.build/debug/FigmaRegistryUtility ui-token-lookup --variables '<TOKEN_NAME>' --json
+```
+
+Both must return `"status": "found"` or a non-null value.
+
+---
+
+## TYPOGRAPHY VS VARIABLE
+
+| Source | Lookup Command | Swift Usage |
+|--------|---------------|-------------|
+| `styles` in design_context | `typography-lookup` | `.typographyStyle(.h3)` |
+| `variables` in variable_defs | `ui-token-lookup` | `Color.Text.textPrimary`, `.Spacing.spacing4` |
+
+Typography styles compose variables. Use style tokens when available.

package/pipeline/skills/figma-ios/figma-to-component/reference/orchestrator-discipline.md

@@ -0,0 +1,90 @@
+# Orchestrator Discipline — Mandatory Rules for Pipeline Execution
+
+These rules apply to every orchestrator skill (`/figma-cli-iterate`, `/figma-cli-lean-iterate`, `/figma-iterate`, `/figma-to-swiftui`, `/performance-swiftui`, `/performance-tour`) and to any agent acting as an orchestrator that dispatches leaf-phase subagents.
+
+Violations of these rules have caused repeated implementation failures. Each rule exists because the opposite was done and broke things.
+
+---
+
+## Rule 1: No Pre-Decided Gate Outcomes in Subagent Prompts
+
+The dispatch prompt template specifies which variables to pass to subagents: component name, node ID, artifact path, file key, component location. Pass ONLY these context variables.
+
+Never add sections like "IMPORTANT: form integration is NOT needed" or "IMPORTANT: no UI patterns apply." Those are gate outcomes — the subagent's gates decide them, not the orchestrator. Injecting conclusions pre-decides gate outcomes and defeats the purpose of having gates.
+
+If the user provides implementation guidance (e.g., "check /figma-form-integration"), pass it as-is: "The user directed: check /figma-form-integration." Do not evaluate and dismiss it.
+
+---
+
+## Rule 2: Every Dispatch Table Row Executes — Verify Row-by-Row Before Proceeding
+
+The dispatch table lists phases with their instruction files, models, and wave groupings. Every row executes. No phase is optional unless the table explicitly marks it (e.g., "COMPLEX only" for 4A/4E — skip only if SIMPLE).
+
+After completing Wave 1, check the table for Wave 2. After Wave 2, check for remaining phases. Do not move to the next step until every phase in the current step has been dispatched and returned.
+
+Skipping Phase 4D or 4E because 4B had problems is not acceptable. Fix 4B, then dispatch 4D and 4E.
+
+Before reporting a step as complete, compare your dispatched phases against the dispatch table row-by-row:
+
+```
+[ ] Phase 0: dispatched and returned COMPLETE
+[ ] Phase 1: script executed and returned COMPLETE
+[ ] Phase 2: all sub-phases dispatched (2A, 2B, 2C, 2D) and finalize script run
+[ ] Phase 3: all sub-phases dispatched (3A, 3C, 3H, 3D) and all scripts run (wave1, 3g, spec)
+[ ] Phase 4: Wave 1 (4A + 4B + 4C) AND Wave 2 (4D + 4E if COMPLEX) dispatched
+[ ] Phase 6: dispatched and returned COMPLETE
+```
+
+If any row is unchecked, you are not done with that step.
+
+---
+
+## Rule 3: Subagent Fails — Retry, Never Take Over
+
+When a subagent times out, errors, or returns HALT:
+
+1. **Timeout**: Retry the same subagent with the same prompt. Do not write code yourself.
+2. **HALT**: Read the HALT reason. Fix the blocking issue. Retry the subagent.
+3. **Error**: Diagnose and retry.
+
+Never take over and write implementation code without reading the phase instruction file the subagent would have read. The subagent reads `phase-4b-view.md` gate-by-gate — if you skip that file and write code from assumptions, you will produce wrong output.
+
+If you must write code directly (after 2+ retries), read the phase instruction file yourself first and follow its gates.
+
+---
+
+## Rule 4: Skills Are Complementary, Not Dismissable
+
+`/figma-form-integration`, `/figma-ui-patterns`, `/figma-price-integration`, `/coreui-forms` — these skills feed INTO phases. They augment Phase 3D, Phase 4A, Phase 4B with domain-specific patterns.
+
+When the user says "check /figma-form-integration":
+- That is a directive to integrate, not a suggestion to evaluate.
+- Read the skill. Identify which phases it affects.
+- Pass the user's directive to the affected subagents as context.
+- Let the subagent's gates determine HOW it integrates, not WHETHER.
+
+Never read a complementary skill, decide it doesn't apply, and tell the subagent to skip it. The subagent's gates make that determination.
+
+---
+
+## Rule 5: Read Acceptance Criteria First, Inject as Subagent Gates
+
+If `{artifactPath}/pass0/specs.md` exists, or if the user provides acceptance criteria:
+
+1. Read the specs BEFORE dispatching Phase 4+ subagents.
+2. Extract concrete requirements.
+3. Inject them as CRITICAL SPEC GATES in the subagent prompt — per the orchestrator SKILL.md instructions.
+
+Do not skip this step. Do not assume specs are empty without checking. The orchestrator SKILL.md has an explicit "Spec Injection" section — follow it.
+
+---
+
+## Rule 6: Read the Phase .md File Before Writing Any Code
+
+If for any reason you write implementation code directly (instead of through a subagent):
+
+1. Read the phase instruction file first (`phase-4b-view.md`, `phase-4a-configuration.md`, etc.).
+2. Follow its gates in order.
+3. Apply every check and validation the file specifies.
+
+Writing code from "I've seen similar components" or "this is a common SwiftUI pattern" without reading the phase file produces code that doesn't follow project conventions — wrong init patterns, missing modifiers, hand-drawn shapes instead of real components.

package/pipeline/skills/figma-ios/figma-to-component/reference/registry.md

@@ -0,0 +1,116 @@
+# FIGMA REGISTRY TOOL
+
+Swift CLI for Figma component and token lookups.
+
+---
+
+## SETUP
+
+**Package:** `{repos.common.path}`
+
+```bash
+REPO_ROOT=$(git rev-parse --show-toplevel)
+CONFIG_PATH="${REPO_ROOT}/{repos.common.path}"
+REGISTRY="$CONFIG_PATH/.build/debug/FigmaRegistryUtility"
+```
+
+**Important:** All commands must run from the config package directory because the utility resolves `Shared/Figma/Generated/*.json` relative to CWD.
+
+```bash
+cd "$CONFIG_PATH" && $REGISTRY <command> [args]
+```
+
+If binary not found: `swift build --package-path "$CONFIG_PATH" --product FigmaRegistryUtility`
+
+---
+
+## DECISION
+
+```
+Figma URL/nodeId → lookup
+Component name   → search
+Browse pages     → list
+Style token name → style-lookup
+Local assets     → ui-token-registry
+"not found"      → update / style-update
+"command not found" → swift build --package-path "$CONFIG_PATH" --product FigmaRegistryUtility
+```
+
+---
+
+## COMMANDS
+
+### lookup
+Get component name and location from Figma nodeId.
+```bash
+$REGISTRY lookup --node-id '<NODE_ID>'
+```
+Returns: `suggestedComponentName`, `suggestedComponentLocation`, `fileKey`, `nodeId`, `name`, `pageName`
+
+### search
+Find components by name.
+```bash
+$REGISTRY search --name '<TERM>'
+```
+Returns: `[nodeId] componentName` with page info.
+
+### list
+Browse components, optionally filter by page.
+```bash
+$REGISTRY list --page '<NAME>'
+```
+
+### style-lookup
+Find design tokens (colors, typography) by name.
+```bash
+$REGISTRY style-lookup --name '<TOKEN>'
+```
+Returns: `[styleId] styleName` with type (FILL/TEXT).
+
+### ui-token-registry
+Generate local .xcassets registry. Scans `Sources/UIAssets/Resources`.
+```bash
+$REGISTRY ui-token-registry
+```
+Writes: `ui-token-registry.json`
+
+### ui-token-index
+Build searchable index from registry.
+```bash
+$REGISTRY ui-token-index
+```
+Writes: `ui-token-index.json`
+
+### ui-token-lookup
+Find local token by Figma variable name.
+```bash
+$REGISTRY ui-token-lookup --name '<FIGMA_TOKEN>'
+```
+Returns: Swift token name for use in code.
+
+### update
+Refresh component registry from Figma API.
+```bash
+FIGMA_ACCESS_TOKEN="<TOKEN>" $REGISTRY update \
+  --config Shared/Figma/figma-components-registry-config.json \
+  --output Shared/Figma/Generated
+```
+
+### style-update
+Refresh style registry from Figma API.
+```bash
+FIGMA_ACCESS_TOKEN="<TOKEN>" $REGISTRY style-update \
+  --config Shared/Figma/figma-styles-registry-config.json \
+  --output Shared/Figma/Generated
+```
+
+---
+
+## URL TO NODE ID
+
+```
+https://www.figma.com/design/9ipBvrtsq9HlQ175B9k0wx/File?node-id=9419-30700
+                                                              ↑
+                                                         9419:30700
+```
+Convert `-` to `:` in node-id.