@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/figma-ios/figma-to-component/phases/phase-3e-assets.md

@@ -0,0 +1,156 @@
+# PHASE 3E — Asset Inventory
+
+Inventory downloaded assets, cross-reference with existing token registry.
+Determines which assets are new vs already exist in the project.
+
+CONDITIONAL — skip if no design_context_assets.txt exists or is empty.
+PARALLEL WITH: Phase 3A, 3B, 3C, 3D, 3F (all read from pass1/ independently)
+
+---
+
+## PRE-CHECK: Phase 1 Complete
+
+```
+Read: {artifactPath}/pass1/_index.md
+Read: {artifactPath}/IMPLEMENTATION_HISTORY.md
+```
+
+Check if asset file exists:
+
+```bash
+ls {artifactPath}/pass1/design_context_assets.txt 2>/dev/null
+```
+
+| Result | Action |
+|--------|--------|
+| File exists and non-empty | Read it, proceed to GATE 1 |
+| File missing or empty | Write placeholder artifact, return COMPLETE |
+
+```
+Read: {artifactPath}/pass1/design_context_assets.txt
+```
+
+Extract: `componentName`, `artifactPath`.
+
+If pass1/_index.md is missing:
+
+```
+STATUS: HALT
+PHASE: phase-3e
+GATE: PRE_CHECK
+REASON: Required Phase 1 artifacts missing.
+COMPLETED_GATES: []
+ARTIFACTS_CREATED: none
+USER_ACTION_REQUIRED: Run Phase 1 first to gather Figma data.
+```
+
+---
+
+## GATE 1: LIST_DOWNLOADED_ASSETS
+
+INPUT: `{artifactPath}/pass1/design_context_assets.txt`
+
+This file contains URLs of assets downloaded during Phase 1 design_context gathering.
+Each line is a URL pointing to a downloaded SVG, PNG, or other asset file.
+
+Parse each entry:
+- Extract filename
+- Determine file type (svg, png, pdf)
+- Infer usage from filename or context (icon, illustration, background)
+
+OUTPUT: List of `{ filename, type, inferredUsage }`.
+
+---
+
+## GATE 2: CHECK_EXISTING_ASSETS
+
+For each asset, check if it already exists in the project's asset registry:
+
+```bash
+cd {repos.common.path} && .build/debug/FigmaRegistryUtility ui-token-lookup --name '{ASSET_NAME}' --type image
+```
+
+| Result | Action |
+|--------|--------|
+| Found | Mark status: "Existing" — already in project, no action needed |
+| Not found | Mark status: "New" — needs to be added to asset catalog |
+| Tool error | Mark status: "Unknown" — log warning, continue |
+
+Also check if the asset exists in the UIComponents asset catalog directly:
+
+```bash
+ls Sources/UIAssets/Assets.xcassets/**/{ASSET_NAME}.imageset 2>/dev/null
+```
+
+---
+
+## GATE 3: DETERMINE_TARGET_PATHS
+
+For each NEW asset, determine where it should be placed:
+
+| Asset Type | Target Path Pattern |
+|------------|---------------------|
+| Icon (small, single-color) | `Sources/UIAssets/Assets.xcassets/Icons/{name}.imageset/` |
+| Illustration (multi-color, complex) | `Sources/UIAssets/Assets.xcassets/Illustrations/{name}.imageset/` |
+| Component-specific | `Sources/UIAssets/Assets.xcassets/Components/{componentName}/{name}.imageset/` |
+
+---
+
+## GATE 4: WRITE_ARTIFACT
+
+Write `{artifactPath}/pass3/06_assets.md`:
+
+```markdown
+# Asset Inventory
+
+Component: {componentName}
+Generated: {ISO_DATE}
+Source: pass1/design_context_assets.txt
+
+## Assets
+
+| File | Type | Usage | Status | Target Path |
+|------|------|-------|--------|-------------|
+| checkCircle.svg | icon | Check circle indicator | New | Sources/UIAssets/.../Icons/checkCircle |
+| arrowRight.svg | icon | Navigation arrow | Existing | (already in project) |
+| badge_bg.png | background | Badge background | New | Sources/UIAssets/.../Components/{componentName}/badgeBg |
+
+## Summary
+
+- Total assets: {TOTAL}
+- New (to add): {NEW_COUNT}
+- Existing (no action): {EXISTING_COUNT}
+- Unknown (check manually): {UNKNOWN_COUNT}
+
+## Action Items
+
+{For each NEW asset:}
+- [ ] Add {filename} to {targetPath}
+- [ ] Verify rendering at 1x, 2x, 3x scales
+```
+
+---
+
+## VALIDATION CHECKLIST
+
+```
+[ ] design_context_assets.txt parsed for all asset entries
+[ ] Each asset checked against token registry (ui-token-lookup)
+[ ] Each asset checked against asset catalog (file existence)
+[ ] New vs existing status determined for every asset
+[ ] Target paths assigned for all new assets
+[ ] 06_assets.md written to pass3/
+```
+
+---
+
+## SUCCESS OUTPUT
+
+```
+STATUS: COMPLETE
+PHASE: phase-3e
+GATES_PASSED: [PRE_CHECK, LIST_DOWNLOADED_ASSETS, CHECK_EXISTING_ASSETS, DETERMINE_TARGET_PATHS, WRITE_ARTIFACT]
+ARTIFACTS_CREATED:
+  - {artifactPath}/pass3/06_assets.md
+SUMMARY: Assets: {NEW_COUNT} new, {EXISTING_COUNT} existing out of {TOTAL} total.
+```

package/pipeline/skills/figma-ios/figma-to-component/phases/phase-3f-utilities.md

@@ -0,0 +1,175 @@
+# PHASE 3F — Utility Integration Summary
+
+Consolidate Phase 2 utility artifacts and map utilities to design elements.
+Cross-references testing identifiers, localization keys, accessibility keys, and analytics events
+with the actual design elements from Phase 1.
+
+required — always execute this phase.
+PARALLEL WITH: Phase 3A, 3B, 3C, 3D, 3E (all read from pass1/pass2 independently)
+
+---
+
+## PRE-CHECK: Phase 2 Complete
+
+```
+Read: {artifactPath}/pass2/_index.md
+Read: {artifactPath}/IMPLEMENTATION_HISTORY.md
+```
+
+Extract: `componentName`, `artifactPath`.
+
+Read Phase 2 utility artifacts:
+```
+Read: {artifactPath}/pass2/utility_identifiers.md
+Read: {artifactPath}/pass2/utility_localization.md
+Read: {artifactPath}/pass2/utility_accessibility.md
+Read: {artifactPath}/pass2/utility_analytics.md
+```
+
+Also read the design context for element cross-referencing:
+```
+Read: {artifactPath}/pass1/design_context_response.json
+```
+
+If pass2/_index.md is missing:
+
+```
+STATUS: HALT
+PHASE: phase-3f
+GATE: PRE_CHECK
+REASON: Phase 2 artifacts not found. pass2/_index.md missing.
+COMPLETED_GATES: []
+ARTIFACTS_CREATED: none
+USER_ACTION_REQUIRED: Run Phase 2 first.
+```
+
+---
+
+## GATE 1: EXTRACT_UTILITY_KEYS
+
+From each Phase 2 artifact, extract the key lists:
+
+### Testing Identifiers (from utility_identifiers.md)
+
+Extract table rows: `{ key, value, status, usage }`
+
+### Localization Keys (from utility_localization.md)
+
+Extract table rows: `{ key, pattern, usage }`
+- If artifact is a skip placeholder ("No localization required") → empty list
+
+### Accessibility Keys (from utility_accessibility.md)
+
+Extract table rows: `{ key, purpose, usage }`
+- If artifact is a skip placeholder or shows 0 keys (GATE 2B filtered all) → empty list
+
+### Analytics Events (from utility_analytics.md)
+
+Extract table rows: `{ element, identifierKey, event }`
+- If artifact is a skip placeholder ("No interactive elements") → empty list
+
+---
+
+## GATE 2: MAP_UTILITIES_TO_ELEMENTS
+
+Cross-reference utility keys with design_context elements to create an element-level mapping.
+This tells Phase 4 exactly which modifiers to apply to each UI element.
+
+For each visual element in design_context_response.json:
+1. Find its testing identifier (if any)
+2. Find its localization key (if any)
+3. Find its accessibility key (if any)
+4. Find its analytics event (if any)
+
+OUTPUT: Element-to-utility mapping table.
+
+---
+
+## GATE 3: WRITE_ARTIFACT
+
+Write `{artifactPath}/pass3/08_utility_integration.md`:
+
+```markdown
+# Utility Integration
+
+Component: {componentName}
+Generated: {ISO_DATE}
+Source: pass2/utility_identifiers.md, pass2/utility_localization.md, pass2/utility_accessibility.md, pass2/utility_analytics.md
+
+## Element-to-Utility Mapping
+
+| Element | Testing ID | Localization Key | Accessibility | Analytics |
+|---------|------------|------------------|---------------|-----------|
+| Title text | `.title` | `ComponentName.Title` | — | — |
+| Action button | `.actionButton` | `ComponentName.Action` | `.actionButton` | `UIInteractionButtonTapped` |
+| Card container | `.card` | — | — | `UIInteractionCardTapped` |
+| Badge | `.badge` | — | runtime label | — |
+
+## Testing Identifiers
+
+| Key | Value | Usage |
+|-----|-------|-------|
+| ComponentName.title | componentname_title | `.accessibilityIdentifier(...)` |
+| ComponentName.actionButton | componentname_action_button | `.accessibilityIdentifier(...)` |
+
+## Localization Keys
+
+| Key | Pattern | Usage |
+|-----|---------|-------|
+| ComponentName.Title | Static | `Text(.ComponentName.title)` |
+
+OR: No localization keys (dynamic text only).
+
+## Accessibility
+
+| Key | Purpose | Usage |
+|-----|---------|-------|
+| ComponentName.ActionButton | VoiceOver label for action | `.accessibilityLabel(...)` |
+
+OR: No dedicated keys — using runtime accessibility patterns.
+
+## Analytics Events
+
+| Element | Event | Implementation |
+|---------|-------|----------------|
+| Action button | `UIInteractionButtonTapped` | `.analyticsButton(id: ..., label: ..., type: .primary)` |
+
+OR: No analytics events (no interactive elements).
+
+## Summary
+
+| Category | Count |
+|----------|-------|
+| Testing Identifiers | {COUNT} |
+| Localization Keys | {COUNT} |
+| Accessibility Keys | {COUNT} |
+| Analytics Events | {COUNT} |
+```
+
+---
+
+## VALIDATION CHECKLIST
+
+```
+[ ] All Phase 2 utility artifacts read (or skip placeholders detected)
+[ ] Testing identifiers extracted from utility_identifiers.md
+[ ] Localization keys extracted from utility_localization.md
+[ ] Accessibility keys extracted from utility_accessibility.md
+[ ] Analytics events extracted from utility_analytics.md
+[ ] Element-to-utility mapping table created
+[ ] Each element has at most one entry per utility category
+[ ] 08_utility_integration.md written to pass3/
+```
+
+---
+
+## SUCCESS OUTPUT
+
+```
+STATUS: COMPLETE
+PHASE: phase-3f
+GATES_PASSED: [PRE_CHECK, EXTRACT_UTILITY_KEYS, MAP_UTILITIES_TO_ELEMENTS, WRITE_ARTIFACT]
+ARTIFACTS_CREATED:
+  - {artifactPath}/pass3/08_utility_integration.md
+SUMMARY: Utility integration: {TESTING_COUNT} testing IDs, {LOCALIZATION_COUNT} localization keys, {ACCESSIBILITY_COUNT} accessibility keys, {ANALYTICS_COUNT} analytics events mapped to design elements.
+```

package/pipeline/skills/figma-ios/figma-to-component/phases/phase-3g-property-coverage.md

@@ -0,0 +1,176 @@
+# PHASE 3G — Property Coverage Verification
+
+Verify that every Figma component property gathered in Phase 1 has been explicitly addressed by Phase 3D's architecture design. Prevents silent property drops.
+
+SEQUENTIAL — runs AFTER all parallel sub-phases (3A-3F) complete.
+DEPENDS ON: Phase 3D output (`pass3/04b_component_architecture.md`)
+
+---
+
+## PRE-CHECK: Required Artifacts
+
+```
+Read: {artifactPath}/pass1/component_summary.json
+Read: {artifactPath}/pass3/04b_component_architecture.md
+```
+
+If `component_summary.json` does not exist:
+```
+Read: {artifactPath}/pass1/component_properties.json
+```
+(Fall back to raw artifact. Extract properties manually.)
+
+If `04b_component_architecture.md` does not exist:
+
+```
+STATUS: HALT
+PHASE: phase-3g
+GATE: PRE_CHECK
+REASON: Phase 3D output (04b_component_architecture.md) not found. Phase 3D must complete first.
+COMPLETED_GATES: []
+ARTIFACTS_CREATED: none
+USER_ACTION_REQUIRED: Run Phase 3D first.
+```
+
+---
+
+## GATE 1: EXTRACT_PROPERTIES
+
+### 1.1 From component_summary.json (or component_properties.json fallback)
+
+Extract the complete list of Figma component properties:
+
+For each property, record:
+- `name` — display name (e.g., "Size", "Loyalty Type", "Icon")
+- `type` — VARIANT, BOOLEAN, TEXT, INSTANCE_SWAP
+- `figmaKey` — exact key from componentPropertyDefinitions (e.g., "Icon#1634:1")
+- `values` — possible values (for VARIANT/BOOLEAN)
+- `default` — default value
+
+**CRITICAL: Every property in componentPropertyDefinitions MUST appear in this list. No exceptions.**
+
+### 1.2 From 04b_component_architecture.md
+
+Extract the Swift API design:
+- All init parameters
+- All enum types defined
+- All configuration properties
+- Any "Not exposed" / "Internal only" notes
+
+---
+
+## GATE 2: MATCH_PROPERTIES
+
+For each Figma property from GATE 1.1, determine if it is addressed in the architecture from GATE 1.2.
+
+### Matching Rules
+
+| Figma Type | Considered "addressed" if |
+|------------|--------------------------|
+| VARIANT (enum) | Architecture defines an enum or parameter mapping these values |
+| VARIANT (bool-like, 2 values) | Architecture defines a Bool parameter or optional |
+| BOOLEAN | Architecture defines a Bool parameter, or merged into an Optional per Boolean Visibility Merge Rule |
+| TEXT | Architecture defines a String parameter |
+| INSTANCE_SWAP | Architecture defines an Image?, AnyView?, or typed view parameter, OR documents it as fixed/internal |
+
+### Status Assignment
+
+For each property, assign exactly one status:
+
+| Status | Meaning | Requires |
+|--------|---------|----------|
+| `IMPLEMENT` | Will be exposed as a Swift parameter | Swift type mapping |
+| `SKIP` | Intentionally not exposed | **Mandatory reason** |
+| `DEFER` | Deferred to future iteration | **Mandatory reason** |
+
+**SKIP reasons (valid examples):**
+- "Fixed to single value per design — not configurable by developers"
+- "Internal Figma layout property — no user-facing impact"
+- "Controlled by parent component via slot composition"
+- "Boolean merged into optional per Boolean Visibility Merge Rule"
+
+**HALT if any property cannot be assigned a status.** This means the architecture did not address it.
+
+---
+
+## GATE 3: WRITE_COVERAGE
+
+Write the property coverage file:
+
+```
+Write: {artifactPath}/pass3/00_property_coverage.json
+```
+
+### Schema
+
+```json
+{
+  "componentName": "{componentName}",
+  "generated": "{YYYY-MM-DD}",
+  "totalProperties": 0,
+  "implemented": 0,
+  "skipped": 0,
+  "deferred": 0,
+  "properties": [
+    {
+      "name": "{display name}",
+      "type": "{VARIANT|BOOLEAN|TEXT|INSTANCE_SWAP}",
+      "figmaKey": "{exact key}",
+      "status": "{IMPLEMENT|SKIP|DEFER}",
+      "swiftType": "{enum TypeName | Bool | String | Image? | ...}",
+      "reason": "{only for SKIP/DEFER — mandatory}"
+    }
+  ],
+  "unmapped": []
+}
+```
+
+### Validation
+
+- `unmapped` array MUST be empty. If any property has no status, add it to `unmapped` and HALT.
+- Every SKIP/DEFER property MUST have a non-empty `reason`.
+- `totalProperties` must equal `implemented + skipped + deferred`.
+- `swiftType` is required for IMPLEMENT, optional for SKIP/DEFER.
+
+FAIL →
+```
+STATUS: HALT
+PHASE: phase-3g
+GATE: WRITE_COVERAGE
+REASON: Properties not fully covered by architecture.
+UNMAPPED_PROPERTIES: [{list names and types}]
+COMPLETED_GATES: [PRE_CHECK, EXTRACT_PROPERTIES, MATCH_PROPERTIES]
+ARTIFACTS_CREATED: none
+USER_ACTION_REQUIRED: Options:
+  1) Update Phase 3D architecture to address missing properties
+  2) Mark properties as SKIP with explicit reason
+  3) Re-run Phase 3D
+```
+
+---
+
+## VALIDATION CHECKLIST
+
+```
+[ ] component_summary.json (or component_properties.json) read successfully
+[ ] 04b_component_architecture.md read successfully
+[ ] ALL properties from Figma extracted (count matches componentPropertyDefinitions)
+[ ] Each property assigned IMPLEMENT, SKIP, or DEFER
+[ ] Every SKIP/DEFER has a mandatory reason
+[ ] unmapped array is empty
+[ ] 00_property_coverage.json written
+[ ] Counts are consistent (total = implemented + skipped + deferred)
+```
+
+---
+
+## SUCCESS OUTPUT
+
+```
+STATUS: COMPLETE
+PHASE: phase-3g
+GATES_PASSED: [PRE_CHECK, EXTRACT_PROPERTIES, MATCH_PROPERTIES, WRITE_COVERAGE]
+ARTIFACTS_CREATED:
+  - {artifactPath}/pass3/00_property_coverage.json
+SUMMARY: Property coverage verified. {totalProperties} properties: {implemented} IMPLEMENT, {skipped} SKIP, {deferred} DEFER. Zero unmapped.
+```