@mmerterden/multi-agent-pipeline 11.1.0 → 11.3.0

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

@@ -1,93 +0,0 @@
-# Sub-Component Graph Registry
-
-Discovers which Figma components use other components as instances (sub-components).
-Produces `Shared/Figma/sub-component-graph.json` via the Figma REST API.
-
----
-
-## Script
-
-`.instructions/figma/figma-to-swiftui/scripts/figma-subcomponent-graph.py`
-
-## Output
-
-`{repos.common.path}/Shared/Figma/sub-component-graph.json`
-
-## Usage
-
-```bash
-# From repo root
-python3 .instructions/figma/figma-to-swiftui/scripts/figma-subcomponent-graph.py
-
-# Preview without API calls
-python3 .instructions/figma/figma-to-swiftui/scripts/figma-subcomponent-graph.py --dry-run
-
-# Skip Visual Assets (icons/flags  -  rarely have sub-components)
-python3 .instructions/figma/figma-to-swiftui/scripts/figma-subcomponent-graph.py --skip-assets
-
-# Verbose output
-python3 .instructions/figma/figma-to-swiftui/scripts/figma-subcomponent-graph.py --verbose
-```
-
-## Prerequisites
-
-- `FIGMA_ACCESS_TOKEN` in macOS Keychain
-- `component-catalog.json` generated (run `FigmaRegistryUtility catalog` first)
-
-## How It Works
-
-1. Reads `component-catalog.json` for the full component list + Figma URLs
-2. Groups components by Figma file key (3 files)
-3. Batch-fetches node trees via `GET /v1/files/:key/nodes?ids=...` (25 nodes/request)
-4. Walks each node subtree for `INSTANCE` children
-5. Resolves `INSTANCE.componentId` → catalog component via:
-   - Response `components` map → `componentSetId` (variant → parent set)
-   - Direct nodeId match against catalog
-   - Fallback: sanitized name match against catalog
-6. Computes reverse `usedBy` map
-7. Writes `sub-component-graph.json`
-
-## Registry Format
-
-```json
-{
-  "version": "1.0",
-  "generatedAt": "2026-02-25T...",
-  "source": "Figma REST API /files/:key/nodes",
-  "stats": {
-    "totalComponents": 2049,
-    "componentsWithSubComponents": 150,
-    "componentsUsedAsSub": 80,
-    "apiCalls": 82,
-    "errors": 0
-  },
-  "graph": {
-    "9047:386": {
-      "name": "AvatarMembership",
-      "subComponents": ["IconBrand", "LabelBadge"],
-      "usedBy": ["ProfileCard", "HeaderMenu"],
-      "unresolvedInstances": 3
-    }
-  }
-}
-```
-
-### Fields
-
-| Field | Description |
-|-------|-------------|
-| `subComponents` | Catalog component names used as INSTANCE children |
-| `usedBy` | Catalog components that use this component (reverse map) |
-| `unresolvedInstances` | Instance count that couldn't be mapped to catalog (internal/private layers) |
-
-## Consumers
-
-- `confluence-component-status.py`  -  reads graph to compute readiness (ready/blocked)
-- Phase 3C (nested components)  -  can reference graph for dependency info
-- Phase 4B (view implementation)  -  knows which sub-components to import
-
-## When to Re-run
-
-- After Figma design changes that add/remove component nesting
-- After `FigmaRegistryUtility catalog` produces a new catalog
-- One-time initial run is sufficient for current status page needs

package/pipeline/skills/figma-ios/figma-to-component/reference/testing-identifiers-naming.md

@@ -1,98 +0,0 @@
-# UITESTING IDENTIFIER NAMING
-
-Naming rules for UIComponents testing identifiers.
-
----
-
-## Format
-
-| Type | Key (PascalCase.Dot) | Value (snake_case) |
-|------|-----|-------|
-| Static | `<Component>.<Element>` | `<component>_<element>` |
-| List Item | `<Component>.Item.<Element>` | `<component>_item_<element>_%@` |
-| Variant | `<Component>.Item.<Variant>` | `<component>_item_<variant>_%@` |
-
----
-
-## Rules
-
-**Key:** PascalCase segments, dots as separators, max 5 levels
-**Value:** All lowercase, underscores as separators, max 100 chars, `%@` for dynamic params
-
----
-
-## Usage in Swift
-
-```swift
-import UITestingIdentifiers
-
-// Static
-.accessibilityIdentifier(UITestingIdentifierKey.Component.element.identifier)
-
-// Dynamic (List)
-.accessibilityIdentifier(UITestingIdentifierKey.Component.Item.label.with(index).identifier)
-
-// Multiple Parameters
-.accessibilityIdentifier(UITestingIdentifierKey.SeatMap.Seat.number.with(row, column).identifier)
-```
-
----
-
-## Common Elements
-
-| Element | Key Suffix | Description |
-|---------|------------|-------------|
-| Title | `.Title` | Main title text |
-| Subtitle | `.Subtitle` | Secondary text |
-| ActionButton | `.ActionButton` | Primary action |
-| CloseButton | `.CloseButton` | Dismiss/close |
-| Item | `.Item.<Element>` | List/grid items |
-| Header | `.Header` | Section header |
-| Footer | `.Footer` | Section footer |
-| Image | `.Image` | Image element |
-| Badge | `.Badge` | Badge/tag |
-| Link | `.Link` | Text link |
-
----
-
-## Context-Aware Identifiers
-
-Identifiers cascade via `UIIdentifierContext` EnvironmentKey. Parent views append context segments; child components automatically get prefixed identifiers.
-
-| Level | Modifier | Accumulates |
-|-------|----------|-------------|
-| Screen | `.identifierContext(.PassengerList.screen)` | `["passenger_list"]` |
-| Section | `.identifierContext(.PassengerList.search)` | `["passenger_list", "search"]` |
-| Component | `.accessibilityIdentifier(.TurkishButton.button)` | → `passenger_list_search_turkishbutton_button` |
-
-Both type-safe and raw string accepted:
-
-```swift
-.identifierContext(.PassengerList.screen)   // type-safe UITestingIdentifierKey (recommended)
-.identifierContext("passenger_list")         // raw string (fallback)
-.testIdentifier(.TurkishButton.button)      // alias for accessibilityIdentifier
-```
-
-Context keys are regular UITestingIdentifierKey entries  -  add via the tool:
-
-```bash
-UITestingIdentifierTool add --key 'PassengerList.screen' --value 'passenger_list'
-```
-
-### Rules for Context Segments
-
-- **snake_case**  -  same as identifier values
-- **Prefer type-safe keys**  -  `.identifierContext(.PassengerList.screen)` over raw strings
-- **Descriptive**  -  `passenger_list`, not `pl` or `screen1`
-- **Stable**  -  don't use indices unless necessary (use `.with()` for dynamic)
-- **No component name**  -  the component's own identifier already includes it
-
----
-
-## Validation
-
-1. Key follows PascalCase.Dot.Notation
-2. Value is snake_case
-3. Value length <= 100 characters
-4. No spaces or special characters
-5. Unique within component scope

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

@@ -1,261 +0,0 @@
-# FIGMA TOOLS REFERENCE
-
----
-
-## 1. MCP TOOLS
-
-### 1.1 Tool Inventory
-
-| Tool | Local | Remote | Purpose | Returns |
-|------|-------|--------|---------|---------|
-| `get_design_context` | yes | yes | Code generation from design node | Code + asset URLs |
-| `get_variable_defs` | yes | yes | Resolved design tokens for node | `{"tokenName": "value"}` |
-| `get_code_connect_map` | yes | yes | Component source mappings for node | `{"nodeId": {src, name}}` |
-| `add_code_connect_map` | yes | yes | Register component mapping in Figma | Success / failure |
-| `get_screenshot` | yes | yes | Visual PNG snapshot of node | PNG image |
-| `get_metadata` | yes | yes | Layer hierarchy as XML | XML (IDs, types, positions) |
-| `get_figjam` | yes | yes | FigJam board content extraction | FigJam data |
-| `create_design_system_rules` | yes | yes | Generate design system rules prompt | Rules prompt text |
-| `generate_diagram` | yes | yes | Create FigJam diagram from Mermaid | FigJam diagram URL |
-| `get_code_connect_suggestions` | yes | yes | Auto-detect mapping candidates | Candidate list |
-| `send_code_connect_mappings` | yes | yes | Batch confirm Code Connect mappings | Confirmation |
-| `generate_figma_design` | no | yes | Push web page or UI to Figma file | Figma file URL |
-| `whoami` | no | yes | Verify OAuth authentication | Authenticated user info |
-
-**Local prefix:** `mcp__figma__`  -  **Remote prefix:** `mcp__figma-remote__`
-
----
-
-### 1.2 Tool Calls  -  Local MCP
-
-**Prefix:** `mcp__figma__`
-**Endpoint:** `http://127.0.0.1:3845/mcp`
-**Requirement:** Figma Desktop running + Dev Mode enabled (Shift+D)
-**Note:** `nodeId` is optional on local  -  omit to use the currently selected node.
-
-```
-mcp__figma__get_design_context(nodeId?: "X:Y", dirForAssetWrites?: "/abs/path", forceCode?: true)
-mcp__figma__get_variable_defs(nodeId?: "X:Y")
-mcp__figma__get_code_connect_map(nodeId?: "X:Y")
-mcp__figma__add_code_connect_map(nodeId?: "X:Y", source: "path/to/File.swift", componentName: "Name", label: "SwiftUI")
-mcp__figma__get_screenshot(nodeId?: "X:Y")
-mcp__figma__get_metadata(nodeId?: "X:Y")
-mcp__figma__get_figjam(nodeId: "X:Y")
-mcp__figma__create_design_system_rules()
-mcp__figma__generate_diagram(name: "Title", mermaidSyntax: "graph LR ...")
-mcp__figma__get_code_connect_suggestions(nodeId?: "X:Y")
-mcp__figma__send_code_connect_mappings(nodeId: "X:Y", mappings: [...])
-```
-
----
-
-### 1.3 Tool Calls  -  Remote MCP
-
-**Prefix:** `mcp__figma-remote__`
-**Endpoint:** `https://mcp.figma.com/mcp`
-**Requirement:** OAuth authentication
-**Note:** `fileKey` + `nodeId` are REQUIRED on remote for all file-scoped tools.
-
-```
-mcp__figma-remote__get_design_context(fileKey: "abc", nodeId: "X:Y", forceCode?: true)
-mcp__figma-remote__get_variable_defs(fileKey: "abc", nodeId: "X:Y")
-mcp__figma-remote__get_code_connect_map(fileKey: "abc", nodeId: "X:Y")
-mcp__figma-remote__add_code_connect_map(fileKey: "abc", nodeId: "X:Y", source: "path/to/File.swift", componentName: "Name", label: "SwiftUI")
-mcp__figma-remote__get_screenshot(fileKey: "abc", nodeId: "X:Y")
-mcp__figma-remote__get_metadata(fileKey: "abc", nodeId: "X:Y")
-mcp__figma-remote__get_figjam(fileKey: "abc", nodeId: "X:Y")
-mcp__figma-remote__create_design_system_rules()
-mcp__figma-remote__generate_diagram(name: "Title", mermaidSyntax: "graph LR ...")
-mcp__figma-remote__get_code_connect_suggestions(fileKey: "abc", nodeId: "X:Y")
-mcp__figma-remote__send_code_connect_mappings(fileKey: "abc", nodeId: "X:Y", mappings: [...])
-mcp__figma-remote__generate_figma_design(outputMode: "newFile", fileName: "Name")
-mcp__figma-remote__whoami()
-```
-
----
-
-### 1.4 Parameters
-
-| Parameter | Format | Example |
-|-----------|--------|---------|
-| `nodeId` | `"X:Y"` (colon) or `"X-Y"` (hyphen) | `"123:456"` |
-| `fileKey` | Alphanumeric string from Figma URL | `"pqrs123abc"` |
-| `dirForAssetWrites` | Absolute path to `.xcassets` dir | `"/Users/me/Project/Assets.xcassets"` |
-| `forceCode` | Boolean | `true` |
-| `componentName` | PascalCase string | `"ButtonPrimary"` |
-| `source` | Relative or absolute file path | `"Sources/UIComponents/Button.swift"` |
-| `label` | Framework label string | `"SwiftUI"` |
-| `mermaidSyntax` | Mermaid.js diagram string | `"graph LR A --> B"` |
-
----
-
-### 1.5 Fallback Strategy
-
-```
-LOCAL → fails? → REMOTE → fails? → STOP (report to user, do not retry)
-```
-
-Prefer local for all active development. Use remote only when Figma Desktop is unavailable.
-
----
-
-### 1.6 Return Formats
-
-**get_design_context**
-Returns generated code + asset URLs. If response is XML instead of code, the design node is too large  -  extract sublayer `nodeId` values from the XML and call again on each sublayer.
-
-**get_variable_defs**
-```json
-{ "Spacing/Spacing8": "8", "Text/primary": "#1A1A1A", "Color/brand": "#E81932" }
-```
-
-**get_code_connect_map**
-```json
-{ "123:456": { "codeConnectSrc": "Sources/UIComponents/Button.swift", "codeConnectName": "Button" } }
-```
-Empty `{}` means no mapping registered for that node.
-
-**get_metadata**
-XML containing node IDs, layer types, names, positions, and sizes. Use to identify sublayer node IDs when `get_design_context` returns XML.
-
----
-
-### 1.7 Rate Limits (MCP Remote  -  effective November 2025)
-
-| Plan | Per Minute | Per Day |
-|------|-----------|---------|
-| Viewer / Collaborator |  -  | 6 / month total |
-| Dev / Full Pro | 15 | 200 |
-| Dev / Full Org | 20 | 200 |
-| Dev / Full Enterprise | 20 | 600 |
-
----
-
-## 2. DEVELOPER API
-
-### 2.1 Base URL + Auth
-
-```
-Base: https://api.figma.com/v1
-Header: X-Figma-Token: figd_your_token_here
-```
-
-**Retrieve token from macOS Keychain:**
-```bash
-export TOKEN=$("$HOME/.claude/lib/credential-store.sh" get \1)
-curl -H "X-Figma-Token: $TOKEN" "https://api.figma.com/v1/..."
-```
-
----
-
-### 2.2 Key Endpoints
-
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/files/:key` | GET | Full file document tree |
-| `/files/:key/nodes?ids=X:Y` | GET | Specific nodes by ID |
-| `/files/:key/images?ids=X:Y` | GET | Export node as image |
-| `/files/:key/variables/local` | GET | Local variable definitions |
-| `/files/:key/variables/published` | GET | Published variable library |
-| `/files/:key/components` | GET | All components in file |
-| `/files/:key/component_sets` | GET | All component sets in file |
-| `/files/:key/styles` | GET | All styles in file |
-
----
-
-### 2.3 Common Calls
-
-**Get specific node:**
-```bash
-curl -H "X-Figma-Token: $TOKEN" \
-  "https://api.figma.com/v1/files/FILE_KEY/nodes?ids=123:456"
-```
-
-**Export image:**
-```bash
-curl -H "X-Figma-Token: $TOKEN" \
-  "https://api.figma.com/v1/images/FILE_KEY?ids=123:456&format=png&scale=2"
-```
-
-**Get local variables:**
-```bash
-curl -H "X-Figma-Token: $TOKEN" \
-  "https://api.figma.com/v1/files/FILE_KEY/variables/local"
-```
-
----
-
-### 2.4 OAuth Scopes
-
-| Scope | Description |
-|-------|-------------|
-| `file_content:read` | Read file contents and layer data |
-| `file_metadata:read` | Read file metadata |
-| `file_variables:read` | Read variables and design tokens |
-| `file_comments:read` | Read file comments |
-| `code_connect:read` | Read Code Connect mappings |
-| `code_connect:write` | Publish Code Connect mappings (required for `figma connect publish`) |
-| `file_dev_resources:read` | Read dev resources |
-| `projects:read` | Read team projects |
-| `webhooks:write` | Manage webhooks |
-
-**Deprecated:** `files:read`  -  replace with `file_content:read` + `file_metadata:read`.
-**Note:** Personal Access Tokens (PATs) are capped at 90-day expiry.
-
----
-
-### 2.5 Error Codes
-
-| Status | Meaning | Action |
-|--------|---------|--------|
-| 200 | Success |  -  |
-| 400 | Bad request | Check parameter format |
-| 403 | Forbidden | Check token validity and scopes |
-| 404 | Not found | Check fileKey and nodeId |
-| 429 | Rate limited | Wait for `X-RateLimit-Reset` header timestamp |
-| 500 | Server error | Retry after delay |
-
----
-
-## 3. QUICK REFERENCE
-
-### 3.1 URL to IDs
-
-```
-URL format: https://figma.com/design/{fileKey}/{fileName}?node-id={int1}-{int2}
-
-Example:    https://figma.com/design/pqrs123/MyFile?node-id=123-456
-fileKey:    pqrs123
-nodeId:     123:456   (convert hyphen → colon)
-```
-
-Branch URLs: use `branchKey` (not `fileKey`) when URL contains `/branch/:branchKey/`.
-
----
-
-### 3.2 When to Use What
-
-| Need | Use |
-|------|-----|
-| Inspect design during active dev | Local MCP |
-| Register Code Connect mapping | Local MCP only |
-| Get design tokens / variables | Local or Remote MCP (get_variable_defs) |
-| Desktop not available | Remote MCP |
-| CI/CD pipeline or automation | Remote MCP or REST API |
-| Batch export images | REST API |
-| Auth debugging | Remote MCP whoami |
-| Design too large (XML response) | Drill into sublayer nodeIds |
-
----
-
-### 3.3 Troubleshooting
-
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| Connection refused (127.0.0.1:3845) | Figma Desktop not running | Open Figma Desktop, enable Dev Mode (Shift+D) |
-| 403 Forbidden | Invalid or expired token / missing scope | Verify token; check scopes; run whoami |
-| get_design_context returns XML | Node too large | Use get_metadata to find sublayer nodeIds, call on each |
-| get_code_connect_map returns `{}` | Component not registered | Use add_code_connect_map via local MCP |
-| 429 Too Many Requests | Rate limit hit | Wait for X-RateLimit-Reset timestamp |
-| generate_figma_design unavailable | Local MCP limitation | Use remote MCP only for this tool |
-| get_variable_defs returns empty | No variables bound to node | Try parent node or REST API `/files/:key/variables/local` |

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

@@ -1,147 +0,0 @@
-# VIEWINSPECTOR REFERENCE
-
-ViewInspector library for SwiftUI view hierarchy inspection and unit testing.
-
-Package: `https://github.com/nalexn/ViewInspector`
-Version: `0.10.3` (latest as of Sep 2025)
-License: MIT
-
----
-
-## FRAMEWORK SUPPORT
-
-| Framework | Supported | Notes |
-|-----------|-----------|-------|
-| XCTest | Yes | Full support, RECOMMENDED |
-| Swift Testing | Warning | Known issues with @Test (GitHub #319)  -  use XCTest |
-| Swift 6.0+ | Yes | Use `.implicitAnyView()` for implicit AnyView wrappers |
-| iOS 17+ / iOS 26 | Yes | v0.10.3 fixes accessibilityIdentifier on iOS 26 |
-
----
-
-## SETUP
-
-```swift
-import ViewInspector
-import XCTest
-
-extension MyComponent: Inspectable { }
-```
-
----
-
-## VIEW TRAVERSAL
-
-```swift
-// By type
-try view.inspect().find(ViewType.Text.self)
-try view.inspect().find(ViewType.Button.self)
-
-// By content
-try view.inspect().find(text: "Submit")
-try view.inspect().find(button: "Submit")
-
-// By accessibility identifier
-try view.inspect().find(viewWithAccessibilityIdentifier: "submit_button")
-
-// By index (Swift 6+: use .implicitAnyView())
-try view.inspect().implicitAnyView().vStack().text(0)
-```
-
----
-
-## READING VALUES
-
-```swift
-// Text content
-try text.string()
-
-// Font / Color
-try text.attributes().font()
-try text.attributes().foregroundColor()
-
-// Image name
-try image.actualImage().name()
-
-// Accessibility
-try view.accessibilityLabel().string()
-try view.accessibilityIdentifier()
-```
-
----
-
-## TRIGGERING ACTIONS
-
-```swift
-try button.tap()
-try toggle.tap()
-try textField.setInput("New Value")
-try view.callOnTapGesture()
-```
-
----
-
-## STATE TESTING
-
-```swift
-// @State
-let view = Counter()
-let button = try view.inspect().find(ViewType.Button.self)
-XCTAssertEqual(try button.labelView().text().string(), "Count: 0")
-try button.tap()
-XCTAssertEqual(try button.labelView().text().string(), "Count: 1")
-
-// @Binding
-var value = false
-let binding = Binding(get: { value }, set: { value = $0 })
-let view = ToggleView(isOn: binding)
-try view.inspect().find(ViewType.Toggle.self).tap()
-XCTAssertTrue(value)
-```
-
----
-
-## FIGMA ARTIFACT CROSS-CHECK
-
-```swift
-func testMatchesFigmaArtifact() throws {
-    let artifact = try loadFigmaArtifact(named: "MyComponent")
-    let view = MyComponent()
-
-    for expectedText in artifact.texts {
-        XCTAssertNotNil(try view.inspect().find(text: expectedText))
-    }
-    for expectedId in artifact.accessibilityIdentifiers {
-        XCTAssertNotNil(try view.inspect().find(viewWithAccessibilityIdentifier: expectedId))
-    }
-}
-```
-
----
-
-## TEST FILE STRUCTURE
-
-```
-Source: Sources/<Module>/Components/<Path>/<Component>.swift
-Test:   Tests/<Module>Tests/ViewInspector/Components/<Path>/<Component>ViewInspectorTests.swift
-```
-
-Full layout:
-```
-Tests/<Module>Tests/
-├── ViewInspector/Components/<Path>/<Component>ViewInspectorTests.swift
-├── Unit/Components/<Path>/<Component>Tests.swift
-├── FigmaArtifacts/<Component>_figma_artifact.json
-└── __Snapshots__/<Component>ViewInspectorTests/testDefaultState.1.png
-```
-
----
-
-## COMMON ISSUES
-
-| Issue | Solution |
-|-------|----------|
-| `Type is not Inspectable` | Add `extension MyView: Inspectable { }` |
-| `View not found` | Use `.implicitAnyView()` for Swift 6+ |
-| `Cannot find in ForEach` | Use `.forEach().view(Type.self, index)` |
-| `Async view not loaded` | Use `ViewHosting.host()` and wait |