@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/figma-ios/figma-to-component/phases/phase-3a-location.md

@@ -0,0 +1,206 @@
+# PHASE 3A — Component Location Resolution
+
+Resolve component name, implementation path, and artifact path.
+Uses user input (priority) and registry lookup (fallback).
+
+required — always execute this phase.
+PARALLEL WITH: Phase 3B, 3C, 3D, 3E, 3F (all read from pass1/ independently)
+
+---
+
+## PRE-CHECK: Phase 1 Complete
+
+```
+Read: {artifactPath}/pass1/_index.md
+Read: {artifactPath}/IMPLEMENTATION_HISTORY.md
+```
+
+Extract: `componentName`, `artifactPath`, `nodeId`, `fileKey`.
+
+If any required file is missing:
+
+```
+STATUS: HALT
+PHASE: phase-3a
+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: RESOLVE_COMPONENT_NAME_AND_LOCATION
+
+### 1.1 Check user input
+
+```
+userProvidedName = <from user prompt or null>
+userProvidedLocation = <from user prompt or null>
+```
+
+The user may have specified a component name or implementation path in their original `/figma` prompt or in a USER_DECISION.
+
+### 1.2 Registry lookup (always run to fill gaps)
+
+```bash
+cd {repos.common.path} && .build/debug/FigmaRegistryUtility lookup --node-id '{nodeId}'
+```
+
+EXTRACT:
+- `suggestedComponentName`
+- `suggestedComponentLocation` (Swift package path)
+- `suggestedArtifactPath`
+
+| Result | Action |
+|--------|--------|
+| Returns component data | Use as fallback values |
+| Not found in registry | Continue with user-provided values only |
+| Tool error | Log warning, continue with user-provided values |
+
+### 1.3 Merge (user overrides registry)
+
+```
+# 1. Resolve the name (user beats registry).
+componentName = userProvidedName ?? suggestedComponentName
+
+# 2. Build the folder path. Take whichever location source is available,
+#    strip its last segment, and append the resolved componentName.
+#    This guarantees the folder tail always equals componentName —
+#    a name override automatically propagates into the folder.
+componentLocation = dirname(userProvidedLocation ?? suggestedComponentLocation) + "/" + componentName
+
+# 3. Artifact path is the registry-node mapping; unchanged by name override.
+artifactPath = suggestedArtifactPath ?? {existing artifactPath}
+```
+
+---
+
+## GATE 2: VALIDATE_RESOLUTION
+
+ALL THREE must be resolved:
+- `componentName` ✓
+- `componentLocation` ✓
+- `artifactPath` ✓
+
+ALSO (structural invariant): `basename(componentLocation) == componentName`.
+The last path segment of `componentLocation` MUST equal `componentName` exactly.
+If they differ, HALT with `NEEDS_INPUT` asking the user to reconcile name vs.
+location — do NOT proceed with a mismatched folder/type pair.
+
+FAIL (any missing or invariant violated) →
+
+First check if prompt contains `USER_DECISION` with gate matching `VALIDATE_RESOLUTION`:
+→ If found: use the provided values, continue execution.
+
+Otherwise:
+
+```
+STATUS: NEEDS_INPUT
+PHASE: phase-3a
+GATE: VALIDATE_RESOLUTION
+QUESTION: Cannot determine component name and/or implementation location. Please provide the missing values.
+OPTIONS:
+  1) Provide component name and location manually
+  2) Update registry with correct mapping and retry
+SUGGESTED: Option 1 — provide manually.
+COMPLETED_GATES: [PRE_CHECK, RESOLVE_COMPONENT_NAME_AND_LOCATION]
+CONTEXT:
+  From registry: name={suggestedComponentName or "not found"}, location={suggestedComponentLocation or "not found"}
+  From user: name={userProvidedName or "not provided"}, location={userProvidedLocation or "not provided"}
+  Missing: {list which values are still null}
+```
+
+---
+
+## GATE 3: CHECK_EXISTING_DIRECTORY
+
+```bash
+ls -la {componentLocation} 2>/dev/null
+```
+
+### Directory EXISTS →
+
+First check if prompt contains `USER_DECISION` with gate matching `CHECK_EXISTING_DIRECTORY`:
+→ If found: use the provided answer, continue execution.
+
+Otherwise:
+
+```
+STATUS: NEEDS_INPUT
+PHASE: phase-3a
+GATE: CHECK_EXISTING_DIRECTORY
+QUESTION: Component directory already exists. How should we proceed?
+OPTIONS:
+  1) Override existing (delete and recreate)
+  2) Choose different name
+  3) Merge with existing (update files)
+SUGGESTED: Option 3 — merge with existing. Existing files will be updated, new files added.
+COMPLETED_GATES: [PRE_CHECK, RESOLVE_COMPONENT_NAME_AND_LOCATION, VALIDATE_RESOLUTION]
+CONTEXT:
+  Path: {componentLocation}
+  Contents: {list files in directory}
+```
+
+### Directory NOT EXISTS → Proceed to GATE 4.
+
+---
+
+## GATE 4: WRITE_ARTIFACT
+
+Write `{artifactPath}/pass3/01_component_location.md`:
+
+```markdown
+# Component Location
+
+Component: {componentName}
+Generated: {ISO_DATE}
+Source: Registry lookup + user input
+
+## Resolution
+
+| Field | Value | Source |
+|-------|-------|--------|
+| Name | {componentName} | {user / registry} |
+| Location | {componentLocation} | {user / registry} |
+| Artifacts | {artifactPath} | {registry / existing} |
+| Exists | {Yes / No} | Directory check |
+| Action | {Create new / Merge / Override} | {User decision or default} |
+
+## Registry Data
+
+| Field | Value |
+|-------|-------|
+| Node ID | {nodeId} |
+| File Key | {fileKey} |
+| Registry Path | {repos.common.path}/Shared/Figma/Components/{nodeId}.json |
+| Registered | {Yes / No} |
+```
+
+---
+
+## VALIDATION CHECKLIST
+
+```
+[ ] Registry lookup performed (or warning logged if tool failed)
+[ ] componentName resolved (non-empty)
+[ ] componentLocation resolved (non-empty, valid Swift package path)
+[ ] artifactPath resolved (non-empty)
+[ ] Existing directory check performed
+[ ] If directory exists, user decision collected (NEEDS_INPUT)
+[ ] 01_component_location.md written to pass3/
+```
+
+---
+
+## SUCCESS OUTPUT
+
+```
+STATUS: COMPLETE
+PHASE: phase-3a
+GATES_PASSED: [PRE_CHECK, RESOLVE_COMPONENT_NAME_AND_LOCATION, VALIDATE_RESOLUTION, CHECK_EXISTING_DIRECTORY, WRITE_ARTIFACT]
+ARTIFACTS_CREATED:
+  - {artifactPath}/pass3/01_component_location.md
+SUMMARY: Component "{componentName}" resolved to {componentLocation}. Source: {user/registry}. Directory: {exists/new}.
+```

package/pipeline/skills/figma-ios/figma-to-component/phases/phase-3b-tokens.md

@@ -0,0 +1,235 @@
+# PHASE 3B — Variable Token Mapping
+
+Map Figma design variables to Swift design tokens.
+Translates colors, spacing, typography, and images from Figma variable names to Swift usage patterns.
+
+required — always execute this phase.
+PARALLEL WITH: Phase 3A, 3C, 3D, 3E, 3F (all read from pass1/ independently)
+
+---
+
+## PRE-CHECK: Phase 1 Complete
+
+```
+Read: {artifactPath}/pass1/_index.md
+Read: {artifactPath}/pass1/variable_defs_response.json
+Read: {artifactPath}/pass1/design_context_response.json
+Read: {artifactPath}/IMPLEMENTATION_HISTORY.md
+```
+
+Extract: `componentName`, `artifactPath`, `nodeId`.
+
+If any required file is missing:
+
+```
+STATUS: HALT
+PHASE: phase-3b
+GATE: PRE_CHECK
+REASON: Required Phase 1 artifacts missing. variable_defs_response.json or design_context_response.json not found.
+COMPLETED_GATES: []
+ARTIFACTS_CREATED: none
+USER_ACTION_REQUIRED: Run Phase 1 first to gather Figma data.
+```
+
+---
+
+## GATE 1: EXTRACT_VARIABLES
+
+INPUT: `{artifactPath}/pass1/variable_defs_response.json`
+
+Collect ALL Figma variable names referenced in the component. Variables follow Figma's slash-separated naming:
+- `Spacing/Spacing4`
+- `Background/Background`
+- `Text/text-primary`
+- `Border/border-secondary`
+- `Radius/Radius8`
+
+Also scan `design_context_response.json` for any typography styles referenced in the generated code:
+- Font names (e.g., `Small Regular/Regular`, `H6`, `Body Bold`)
+- Font weights
+- Font sizes
+
+OUTPUT: Complete list of variable names to look up.
+
+If no variables found (component uses no design tokens):
+- Write a minimal artifact noting "No variables found"
+- Proceed to WRITE_ARTIFACT
+
+---
+
+## GATE 2: BATCH_LOOKUP
+
+```bash
+cd {repos.common.path} && .build/debug/FigmaRegistryUtility ui-token-lookup --variables '{VAR1},{VAR2},{VAR3}' --json
+```
+
+For typography styles that don't appear in variable_defs, use typography-lookup:
+
+```bash
+cd {repos.common.path} && .build/debug/FigmaRegistryUtility typography-lookup --styles '{STYLE1},{STYLE2}' --json
+```
+
+OUTPUT FORMAT from ui-token-lookup: `type:path`
+- `color:.Background.background`
+- `number:.Spacing.spacing4`
+- `image:.Icons.checkCircle`
+- `font:.Typography.bodyMedium`
+
+OUTPUT FORMAT from typography-lookup:
+```
+Figma: "Small Regular/Regular"
+Swift: THYFont.smallRegular
+Size: 14.0
+Weight: regular
+Line Height: 20.0
+```
+
+---
+
+## GATE 3: MAP_TO_SWIFT_TYPES
+
+Map each resolved token to its Swift usage pattern:
+
+| Type Prefix | Swift Type | Usage Pattern | Example |
+|-------------|------------|---------------|---------|
+| `color:` | `Color` | `Color{path}` | `Color.Background.background` |
+| `number:` | Direct | `{path}` (spacing, radius, size) | `.Spacing.spacing4` |
+| `image:` | `Image` | `Image{path}` | `Image.Icons.checkCircle` |
+| `font:` | `Font` | `Font{path}` | `Font.smallRegular` |
+| `fontStyle:` | `FontStyle` | Applied via typography modifier | `.typographyStyle(.h6)` |
+
+### Typography dual usage
+
+Typography tokens have two usage modes — include BOTH in the output:
+
+**1. Typography modifier (for Text views with full style):**
+```swift
+Text("Title")
+    .typographyStyle(.h6)
+```
+
+**2. Font token (for AttributedString or manual font usage):**
+```swift
+let font = Font.h6
+```
+
+---
+
+## GATE 4: HANDLE_MISSING_TOKENS
+
+If NO tokens are missing → skip this gate, proceed directly to WRITE_ARTIFACT.
+
+If ANY variables were NOT found by ui-token-lookup or typography-lookup, HALT immediately:
+
+```
+STATUS: HALT
+PHASE: phase-3b
+GATE: HANDLE_MISSING_TOKENS
+REASON: {COUNT} design token(s) not found in the ui-token-index registry.
+COMPLETED_GATES: [PRE_CHECK, EXTRACT_VARIABLES, BATCH_LOOKUP, MAP_TO_SWIFT_TYPES]
+ARTIFACTS_CREATED: none
+USER_ACTION_REQUIRED: The following tokens must be added to the ui-token-index before continuing:
+  - {TOKEN_1}: Figma variable name, expected type={color|number|typography}
+  - {TOKEN_2}: Figma variable name, expected type={color|number|typography}
+  Reference: See reference/missing-tokens.md for adding tokens to the index.
+```
+
+First check if prompt contains `USER_DECISION` with gate matching `HANDLE_MISSING_TOKENS`:
+→ If found: use the provided answer, continue execution.
+
+---
+
+## GATE 5: WRITE_ARTIFACT
+
+Write `{artifactPath}/pass3/02_token_mapping.md`:
+
+```markdown
+# Token Mapping
+
+Component: {componentName}
+Generated: {ISO_DATE}
+Source: pass1/variable_defs_response.json, pass1/design_context_response.json
+
+## Typography
+
+| Figma Style | Token Type | Swift Modifier | Swift Font |
+|-------------|------------|----------------|------------|
+| H6 | typography | `.typographyStyle(.h6)` | `Font.h6` |
+| Small Regular/Regular | typography | `.typographyStyle(.smallRegular)` | `Font.smallRegular` |
+| Body Underline | typography | `.typographyStyle(.bodyUnderline)` | `Font.bodyUnderline` |
+
+## Colors
+
+| Figma Variable | Token Type | Swift Usage |
+|----------------|------------|-------------|
+| Text/text-primary | color | `Color.Text.textPrimary` |
+| Text/text-grey | color | `Color.Text.textGrey` |
+| Background/background | color | `Color.Background.background` |
+| Border/border-secondary | color | `Color.Border.borderSecondary` |
+
+## Spacing
+
+| Figma Variable | Token Type | Swift Token |
+|----------------|------------|-------------|
+| Spacing/Spacing4 | number | `.Spacing.spacing4` |
+| Spacing/Spacing8 | number | `.Spacing.spacing8` |
+| Spacing/Spacing16 | number | `.Spacing.spacing16` |
+
+## Radius
+
+| Figma Variable | Token Type | Swift Token |
+|----------------|------------|-------------|
+| Radius/Radius8 | number | `.Radius.radius8` |
+
+## Images / Icons
+
+| Figma Variable | Token Type | Swift Usage |
+|----------------|------------|-------------|
+| Icons/checkCircle | image | `Image.Icons.checkCircle` |
+
+## Missing Tokens
+
+| Token | Type | Resolution |
+|-------|------|------------|
+| Font/Weight/Bold700 | font | See reference/missing-tokens.md |
+
+OR: All tokens resolved.
+
+## Summary
+
+- Typography: {COUNT} mapped
+- Colors: {COUNT} mapped
+- Spacing: {COUNT} mapped
+- Radius: {COUNT} mapped
+- Images: {COUNT} mapped
+- Missing: {COUNT}
+```
+
+---
+
+## VALIDATION CHECKLIST
+
+```
+[ ] variable_defs_response.json fully scanned for variable names
+[ ] design_context_response.json scanned for typography styles
+[ ] ui-token-lookup batch executed for all variables
+[ ] typography-lookup executed for all font styles
+[ ] Each token mapped to Swift type and usage pattern
+[ ] Typography tokens include BOTH modifier and font usage
+[ ] Missing tokens documented with type and reference
+[ ] If missing tokens exist, NEEDS_INPUT returned (or USER_DECISION used)
+[ ] 02_token_mapping.md written to pass3/
+```
+
+---
+
+## SUCCESS OUTPUT
+
+```
+STATUS: COMPLETE
+PHASE: phase-3b
+GATES_PASSED: [PRE_CHECK, EXTRACT_VARIABLES, BATCH_LOOKUP, MAP_TO_SWIFT_TYPES, HANDLE_MISSING_TOKENS, WRITE_ARTIFACT]
+ARTIFACTS_CREATED:
+  - {artifactPath}/pass3/02_token_mapping.md
+SUMMARY: Token mapping: {MAPPED} mapped, {MISSING} missing. Typography: {T_COUNT}. Colors: {C_COUNT}. Spacing: {S_COUNT}.
+```

package/pipeline/skills/figma-ios/figma-to-component/phases/phase-3c-nested.md

@@ -0,0 +1,214 @@
+# PHASE 3C — Nested Component Resolution
+
+Resolve nested/child components referenced by this component.
+Reads FIGMA.md from connected components to extract init signatures and usage patterns.
+
+required — always execute this phase.
+PARALLEL WITH: Phase 3A, 3B, 3D, 3E, 3F (all read from pass1/ independently)
+
+---
+
+## PRE-CHECK: Phase 1 Complete
+
+```
+Read: {artifactPath}/pass1/_index.md
+Read: {artifactPath}/pass1/code_connect_map_response.json
+Read: {artifactPath}/pass1/design_context_response.json
+Read: {artifactPath}/IMPLEMENTATION_HISTORY.md
+```
+
+Extract: `componentName`, `artifactPath`, `nodeId`, `fileKey`.
+
+If any required file is missing:
+
+```
+STATUS: HALT
+PHASE: phase-3c
+GATE: PRE_CHECK
+REASON: Required Phase 1 artifacts missing. code_connect_map_response.json not found.
+COMPLETED_GATES: []
+ARTIFACTS_CREATED: none
+USER_ACTION_REQUIRED: Run Phase 1 first to gather Figma data.
+```
+
+---
+
+## GATE 1: EXTRACT_NESTED_COMPONENTS
+
+INPUT: `{artifactPath}/pass1/code_connect_map_response.json`
+
+The code_connect_map contains entries like:
+
+```json
+{
+  "123:456": {
+    "codeConnectSrc": "Sources/UIComponents/Components/.../TextLink/TextLink.swift",
+    "codeConnectName": "TextLink"
+  }
+}
+```
+
+EXTRACT all unique component references:
+- `componentName` (codeConnectName)
+- `sourcePath` (codeConnectSrc)
+- `nodeId` (the key)
+
+Filter OUT:
+- The current component itself (self-references)
+- Duplicate entries (same codeConnectName appearing multiple times)
+
+Also scan `design_context_response.json` for components that appear in the design but are NOT in code_connect_map:
+- Look for nested frames/groups that resemble standalone components
+- Look for instance references in the Figma design context code
+
+OUTPUT: Two lists:
+1. **Connected** — in code_connect_map with source path
+2. **Unconnected** — referenced in design but NOT in code_connect_map
+
+If NO nested components found (component is self-contained):
+- Write artifact noting "No nested components"
+- Proceed to WRITE_ARTIFACT
+
+---
+
+## GATE 2: READ_FIGMA_MD
+
+For each connected component, read its FIGMA.md to extract integration info:
+
+```
+Read: {codeConnectSrc directory}/FIGMA.md
+```
+
+For example, if codeConnectSrc is `Sources/UIComponents/Components/Buttons/TextLink/TextLink.swift`, read:
+`Sources/UIComponents/Components/Buttons/TextLink/FIGMA.md`
+
+EXTRACT from each FIGMA.md:
+- **Init signature** — the public init with parameter names and types
+- **Variant mapping** — how Figma variants map to Swift properties
+- **First usage example** — the recommended integration pattern
+
+If FIGMA.md does not exist for a connected component:
+- Read the Swift source file directly
+- Extract the public init from the source code
+- Mark as "No FIGMA.md — signature from source"
+
+---
+
+## GATE 3: HANDLE_UNCONNECTED_COMPONENTS
+
+For each component found in design_context but NOT in code_connect_map:
+
+First check if prompt contains `USER_DECISION` with gate matching `HANDLE_UNCONNECTED_COMPONENTS`:
+→ If found: use the provided answer, continue execution.
+
+If unconnected list is empty → skip this gate.
+
+Otherwise:
+
+```
+STATUS: NEEDS_INPUT
+PHASE: phase-3c
+GATE: HANDLE_UNCONNECTED_COMPONENTS
+QUESTION: {COUNT} nested component(s) not found in Code Connect. These are used in the design but have no linked implementation.
+OPTIONS:
+  1) Implement dependencies first (pause this component)
+  2) Continue without (will need manual implementation inline or stub)
+  3) These are not real dependencies — ignore them
+SUGGESTED: Option 2 — continue. Unconnected components will be documented for later implementation.
+COMPLETED_GATES: [PRE_CHECK, EXTRACT_NESTED_COMPONENTS, READ_FIGMA_MD]
+CONTEXT:
+  Unconnected components:
+  - {COMPONENT_1}: Figma node {NODE_ID}
+  - {COMPONENT_2}: Figma node {NODE_ID}
+  Connected components (working):
+  - {COMPONENT_A}: {SOURCE_PATH}
+```
+
+---
+
+## GATE 4: WRITE_ARTIFACT
+
+Write `{artifactPath}/pass3/03_nested_components.md`:
+
+```markdown
+# Nested Components
+
+Component: {componentName}
+Generated: {ISO_DATE}
+Source: pass1/code_connect_map_response.json
+
+## Connected Components
+
+| Component | Source | Init Signature |
+|-----------|--------|----------------|
+| TextLink | Sources/.../TextLink.swift | `TextLink(_ text: String, action: () -> Void)` |
+| LabelBadge | Sources/.../LabelBadge.swift | `LabelBadge(text: String, state: LabelBadge.State)` |
+
+### Usage Patterns
+
+#### TextLink
+
+```swift
+// From FIGMA.md
+TextLink("More Info") {
+    onMoreInfoTapped()
+}
+```
+
+#### LabelBadge
+
+```swift
+// From FIGMA.md
+LabelBadge(text: statusText, state: .success)
+```
+
+## Unconnected Components
+
+| Component | Figma Node | Resolution |
+|-----------|-----------|------------|
+| CustomIcon | 789:012 | Continue without — will implement inline |
+
+OR: None — all nested components are connected.
+
+## Inline Components
+
+Components that appear in the design but are too simple to be separate:
+- Divider line (1px horizontal rule)
+- Spacer elements
+
+OR: None.
+
+## Summary
+
+- Connected: {COUNT}
+- Unconnected: {COUNT}
+- Inline: {COUNT}
+```
+
+---
+
+## VALIDATION CHECKLIST
+
+```
+[ ] code_connect_map_response.json fully scanned
+[ ] design_context_response.json scanned for additional component references
+[ ] Self-references and duplicates filtered out
+[ ] FIGMA.md read for each connected component (or source file as fallback)
+[ ] Init signatures extracted for all connected components
+[ ] Usage patterns extracted where available
+[ ] Unconnected components handled (NEEDS_INPUT or empty)
+[ ] 03_nested_components.md written to pass3/
+```
+
+---
+
+## SUCCESS OUTPUT
+
+```
+STATUS: COMPLETE
+PHASE: phase-3c
+GATES_PASSED: [PRE_CHECK, EXTRACT_NESTED_COMPONENTS, READ_FIGMA_MD, HANDLE_UNCONNECTED_COMPONENTS, WRITE_ARTIFACT]
+ARTIFACTS_CREATED:
+  - {artifactPath}/pass3/03_nested_components.md
+SUMMARY: Nested components: {CONNECTED} connected, {UNCONNECTED} unconnected, {INLINE} inline.
+```