@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/figma-ios/figma-to-component/phases/phase-0-init.md

@@ -0,0 +1,307 @@
+# PHASE 0 — Component Initialization
+
+Setup component context and create artifact directory before implementation.
+NEXT: Phase 1 (Data Gathering)
+
+---
+
+## PRE-CHECK: Setup Marker
+
+```
+Read: {repos.packagesContainer}/{repos.artifactsRepo}/ImplementationArtifacts/Figma/.setup-verified.json
+```
+
+If file does NOT exist:
+
+```
+STATUS: HALT
+PHASE: phase-0
+GATE: PRE_CHECK_SETUP
+REASON: Environment setup not completed.
+COMPLETED_GATES: []
+ARTIFACTS_CREATED: none
+USER_ACTION_REQUIRED: Run /figma-setup first to configure your environment.
+```
+
+If file exists → proceed to REBUILD_DERIVED_ARTIFACTS.
+
+---
+
+## REBUILD_DERIVED_ARTIFACTS: Rebuild Gitignored Derived Files
+
+Derived artifacts (component-catalog, ui-token-index, merged translations, etc.) are gitignored. Always rebuild to guarantee fresh data before implementation.
+
+```bash
+REPO_ROOT=$(git rev-parse --show-toplevel)
+bash "${REPO_ROOT}/.instructions/common/scripts/common-rebuild-derived-artifacts.sh"
+```
+
+If the script exits non-zero:
+
+```
+STATUS: HALT
+PHASE: phase-0
+GATE: REBUILD_DERIVED_ARTIFACTS
+REASON: Failed to rebuild derived artifacts. Check tool build errors above.
+COMPLETED_GATES: [PRE_CHECK_SETUP]
+ARTIFACTS_CREATED: none
+USER_ACTION_REQUIRED: Fix build errors in {project.slug}-common and retry.
+```
+
+If exit 0 → proceed to GATE 1.
+
+---
+
+## GATE 1: EXTRACT_NODE_ID
+
+INPUT: User provides Figma URL or node ID.
+
+```
+URL: https://figma.com/design/FILEKEY/Name?node-id=123-456
+                              ↑                    ↑
+                           fileKey              nodeId=123:456
+```
+
+Convert `-` to `:` in nodeId.
+
+PASS → Store `nodeId`, `fileKey`. Proceed to GATE 2.
+
+FAIL →
+```
+STATUS: NEEDS_INPUT
+PHASE: phase-0
+GATE: EXTRACT_NODE_ID
+QUESTION: No node ID found in user input.
+OPTIONS:
+  1) Provide Figma URL (format: https://figma.com/design/KEY/Name?node-id=X-Y)
+  2) Provide node ID directly (format: X:Y)
+SUGGESTED: Option 1 — paste the full Figma URL
+COMPLETED_GATES: [PRE_CHECK_SETUP]
+CONTEXT: A Figma URL or node ID is required to start implementation.
+```
+
+---
+
+## GATE 2: REGISTRY_LOOKUP
+
+REF: `reference/registry.md`
+
+```bash
+REPO_ROOT=$(git rev-parse --show-toplevel)
+CONFIG_PATH="${REPO_ROOT}/{repos.common.path}"
+cd "$CONFIG_PATH" && .build/debug/FigmaRegistryUtility lookup --node-id '<NODE_ID>'
+```
+
+**Important:** The utility must run from the config package directory (`cd "$CONFIG_PATH"`) because it resolves `Shared/Figma/Generated/component-registry.json` relative to CWD.
+
+PASS → Store from JSON output:
+- `suggestedComponentName`
+- `suggestedComponentLocation`
+- `suggestedArtifactPath`
+- `fileKey` (verify matches GATE 1)
+
+Proceed to GATE 3.
+
+FAIL (binary not found) →
+```bash
+swift build --package-path "$CONFIG_PATH" --product FigmaRegistryUtility
+```
+Retry GATE 2.
+
+FAIL (component not found) →
+```
+STATUS: NEEDS_INPUT
+PHASE: phase-0
+GATE: REGISTRY_LOOKUP
+QUESTION: Component with node ID <NODE_ID> not found in registry.
+OPTIONS:
+  1) Update registry first (run registry update command)
+  2) Provide component name and location manually
+  3) Check if node ID is correct
+SUGGESTED: Option 1 — registry may be outdated
+COMPLETED_GATES: [PRE_CHECK_SETUP, EXTRACT_NODE_ID]
+CONTEXT: The FigmaRegistryUtility lookup returned no results for node ID <NODE_ID>.
+```
+
+---
+
+## GATE 3: RESOLVE_OVERRIDES
+
+Resolve `componentName`, `componentLocation`, and `artifactPath` using this priority:
+
+### 3.1 Priority order
+
+| Field | Priority 1 (highest) | Priority 2 | Priority 3 (lowest) |
+|-------|---------------------|------------|---------------------|
+| `componentName` | User-provided in prompt | Suggested by registry | HALT — ask user |
+| `componentLocation` | User-provided in prompt | `suggestedComponentLocation` from registry | HALT — ask user |
+| `artifactPath` | Derived from final `componentName` if name changed | `suggestedArtifactPath` from registry | HALT — ask user |
+
+**How to detect user overrides:** Scan the user's original prompt for explicit name or location mentions:
+- `"implement as PackageBadge"` → override componentName
+- `"name: FlightCard"` → override componentName
+- `"put it in Sources/UIComponents/Booking/"` → override componentLocation
+- Any PascalCase word the user associates with the component → override componentName
+
+If user provided an override in their prompt, use it directly — do NOT ask for confirmation.
+If user did NOT provide an override, use the registry suggestion — but check for vague names first.
+
+### 3.2 Vague name detection
+
+Registry names derived from Figma layer hierarchy can be too generic. Check if `suggestedComponentName` is vague:
+
+**Vague indicators** — single common word that doesn't describe the component's purpose:
+- Generic containers: `Package`, `Card`, `Item`, `Cell`, `Row`, `View`, `Container`, `Component`, `Element`, `Block`, `Section`, `Group`, `Box`, `Wrapper`
+- Generic actions: `Button`, `Label`, `Icon`, `Badge`, `Tag`, `Chip`, `Indicator`
+- Generic layout: `Header`, `Footer`, `Content`, `Body`, `Stack`, `List`
+
+If `suggestedComponentName` matches a vague indicator (case-insensitive, exact match):
+
+```
+STATUS: NEEDS_INPUT
+PHASE: phase-0
+GATE: RESOLVE_OVERRIDES
+QUESTION: Registry suggested "{suggestedComponentName}" which is too generic. What should this component be called?
+OPTIONS:
+  1) Suggest a more descriptive name based on design context (e.g., "Package" → "PackageBadge", "Card" → "FlightCard")
+  2) User provides custom name
+SUGGESTED: Look at the Figma layer name, parent frame, and page name for context clues.
+COMPLETED_GATES: [PRE_CHECK_SETUP, EXTRACT_NODE_ID, REGISTRY_LOOKUP]
+CONTEXT:
+  Registry name: {suggestedComponentName}
+  Registry location: {suggestedComponentLocation}
+  Figma node path: {parent names from registry if available}
+```
+
+If `suggestedComponentName` is NOT vague → use it as-is.
+
+### 3.3 Store resolved values
+
+```
+componentName = <user override OR registry suggestion (after vague check)>
+componentLocation = <user override OR suggestedComponentLocation>
+artifactPath = {artifactPath} (update path suffix if componentName was overridden)
+```
+
+If `componentName` was overridden and differs from the registry name, update `artifactPath` by replacing the last path component:
+```
+Original:  .../Components/StepBar/Package
+Overridden: .../Components/StepBar/PackageBadge
+```
+
+PASS → Store `componentName`, `componentLocation`, `artifactPath`. Proceed to GATE 4.
+
+FAIL (no name resolvable) →
+```
+STATUS: NEEDS_INPUT
+PHASE: phase-0
+GATE: RESOLVE_OVERRIDES
+QUESTION: Component name could not be determined.
+OPTIONS:
+  1) Use suggested name from registry: <SUGGESTED_NAME>
+  2) Provide custom name and location
+COMPLETED_GATES: [PRE_CHECK_SETUP, EXTRACT_NODE_ID, REGISTRY_LOOKUP]
+CONTEXT: suggestedComponentName: <VALUE_OR_EMPTY>, suggestedComponentLocation: <VALUE_OR_EMPTY>
+```
+
+---
+
+## GATE 4: CREATE_ARTIFACTS
+
+Use resolved `artifactPath` from GATE 3.
+
+### 4.1 Create directory structure
+
+```bash
+mkdir -p {artifactPath}/pass1 {artifactPath}/pass2 {artifactPath}/pass3
+```
+
+### 4.2 Create IMPLEMENTATION_HISTORY.md
+
+Write `{artifactPath}/IMPLEMENTATION_HISTORY.md`:
+
+```markdown
+# <COMPONENT_NAME>
+
+## Inputs
+- Node ID: <NODE_ID>
+- File Key: <FILE_KEY>
+- Component Name: <NAME>
+- Source Location: {componentLocation}
+- Artifact Location: {artifactPath}
+- GitHub Issue: #<ISSUE_NUMBER> (https://github.com/{github.componentsRepo}/issues/<ISSUE_NUMBER>)
+- Jira: <JIRA_KEY>
+- Date: <DATE>
+
+## Decisions
+<!-- User decisions during implementation -->
+```
+
+### 4.3 Create PROMPT_HISTORY.md
+
+Write `{artifactPath}/PROMPT_HISTORY.md`:
+
+```markdown
+# <COMPONENT_NAME> Prompt History
+
+All user prompts verbatim. Sensitive data masked.
+
+## Session: <DATE>
+
+### Prompt 1
+Context: Initial Figma URL provided
+<!-- Mask: tokens → <TOKEN>, passwords → <PASSWORD>, keys → <KEY> -->
+```
+
+PASS → Proceed to GATE 5.
+
+FAIL →
+```
+STATUS: HALT
+PHASE: phase-0
+GATE: CREATE_ARTIFACTS
+REASON: Failed to create artifact directory or files.
+COMPLETED_GATES: [PRE_CHECK_SETUP, EXTRACT_NODE_ID, REGISTRY_LOOKUP, RESOLVE_OVERRIDES]
+ARTIFACTS_CREATED: none
+USER_ACTION_REQUIRED: Check file system permissions for {artifactPath}.
+```
+
+---
+
+## GATE 5: LOAD_SPECS
+
+Check if specs were saved by `/figma-to-swift-ui-start`:
+
+```bash
+ls {artifactPath}/pass0/specs.md 2>/dev/null
+```
+
+**If specs exist:** read the file and store as `implementationSpecs`. These specs will be passed to subsequent phases as additional context:
+- Phase 3 (Analysis) — informs pattern decisions
+- Phase 4 (Implementation) — constrains the init signature, defaults, and behavior
+
+Append to IMPLEMENTATION_HISTORY.md:
+```markdown
+## Specs
+- Source: pass0/specs.md
+- Loaded: <DATE>
+```
+
+**If no specs file:** continue without. No error — specs are optional.
+
+---
+
+## SUCCESS OUTPUT
+
+```
+STATUS: COMPLETE
+PHASE: phase-0
+GATES_PASSED: [PRE_CHECK_SETUP, REBUILD_DERIVED_ARTIFACTS, EXTRACT_NODE_ID, REGISTRY_LOOKUP, RESOLVE_OVERRIDES, CREATE_ARTIFACTS, LOAD_SPECS]
+ARTIFACTS_CREATED:
+  - {artifactPath}/IMPLEMENTATION_HISTORY.md
+  - {artifactPath}/PROMPT_HISTORY.md
+  - {artifactPath}/pass1/  (empty, ready for Phase 1)
+  - {artifactPath}/pass2/  (empty, ready for Phase 2)
+  - {artifactPath}/pass3/  (empty, ready for Phase 3)
+SUMMARY: Component <NAME> initialized with artifact directory at {artifactPath}
+```

package/pipeline/skills/figma-ios/figma-to-component/phases/phase-1-gathering.md

@@ -0,0 +1,119 @@
+# Phase 1 — Data Gathering
+
+## Overview
+
+Runs `phase1-gather.py` to collect all Figma data, then checks if design context was deferred due to sublayer cap.
+
+---
+
+## Step 1: Run the Script
+
+```bash
+python3 .instructions/figma/figma-to-swiftui/scripts/phase1-gather.py \
+  --file-key "{fileKey}" \
+  --node-id "{nodeId}" \
+  --artifact-path "{artifactPath}" \
+  --component-name "{componentName}"
+```
+
+Parse the JSON output from stdout.
+
+---
+
+## Step 2: Check Result
+
+### If `status` = `COMPLETE`
+
+Phase 1 is done. All artifacts are in `pass1/`. Proceed to Phase 2.
+
+### If `status` = `COMPLETE_WITH_DEFERRED`
+
+The script completed all data gathering **except** `get_design_context`, which was deferred because the component has too many sublayers (>20). Report status to orchestrator — it will dispatch a Phase 1 subagent for deferred resolution.
+
+---
+
+## Deferred Resolution
+
+**When the orchestrator dispatches you for deferred resolution, follow these steps.**
+
+### Step 1: Read Context
+
+```
+Read: {artifactPath}/pass1/component_properties.json
+Read: {artifactPath}/pass1/design_context_deferred.json
+```
+
+From `component_properties.json` extract the variant axes (properties with `type: "VARIANT"`).
+From `design_context_deferred.json` extract `sublayerIds` (node IDs) and `sublayerCount`.
+
+### Step 2: Smart Representative Selection
+
+Classify each variant axis:
+
+| Category | Examples | Action |
+|----------|----------|--------|
+| **Interaction** | `State` (Default/Hover/Pressed/Disabled), focus/hover variants | Fix to `Default` (only color/opacity changes — no structural difference) |
+| **Theme** | `Color`, `Theme`, `Mode` | Fix to first value (e.g., `Brand`) |
+| **Structural** | `Size`, `Style`, `IconDirection`, `Type`, `Layout`, everything else | **Vary** — these change layout/structure |
+
+Calculate structural combinations:
+- If <= 20: fetch all structural combinations (with interaction + theme fixed).
+- If > 20: also fix the structural axis with the most values to `Default` or its first value. Repeat until <= 20. Target: ~9-12 representatives.
+
+### Step 3: Map to Node IDs
+
+Each sublayer in Figma is a variant named like `Color=Brand, Size=Default, Style=Primary, State=Default, IconDirection=None`.
+
+The `sublayerIds` list in `design_context_deferred.json` corresponds to the children of the component set. To map selected variant combinations to node IDs:
+
+1. Read `{artifactPath}/pass1/screenshots/variants.md` — it has a table of `Variant | Node ID | File`.
+2. Match your selected combinations against the variant names.
+3. Collect the node IDs for matched variants.
+
+If `variants.md` doesn't have the mapping, use the Figma REST API or MCP `get_metadata` to resolve.
+
+### Step 4: Fetch
+
+Call the script with the selected sublayer IDs:
+
+```bash
+python3 .instructions/figma/figma-to-swiftui/scripts/phase1-gather.py \
+  --fetch-deferred \
+  --file-key "{fileKey}" \
+  --node-id "{nodeId}" \
+  --artifact-path "{artifactPath}" \
+  --component-name "{componentName}" \
+  --sublayer-ids "id1,id2,id3,..."
+```
+
+The script:
+- Fetches `get_design_context` for each sublayer ID (parallel, using its internal MCP)
+- Merges into `pass1/design_context_response.json` in the **same format** as non-deferred components
+- Sets `representativeSelection: true` with selection metadata
+- Updates `pass1/component_summary.json`
+
+Parse the JSON output from stdout.
+
+### Step 5: Update History
+
+Append to `{artifactPath}/IMPLEMENTATION_HISTORY.md`:
+
+```markdown
+- Design context: deferred → smart selection ({N} representatives)
+  - Fixed: {list fixed axes and values}
+  - Varied: {list varied axes with cross product notation}
+```
+
+### Step 6: Return
+
+Return COMPLETE with the script's output summary.
+
+### If `status` = `HALT`
+
+Script failed at a specific gate. Report the gate, reason, and user action to the orchestrator for user resolution.
+
+---
+
+## Return
+
+Return the script's JSON output as-is to the orchestrator. The orchestrator handles HALT/NEEDS_INPUT flows.

package/pipeline/skills/figma-ios/figma-to-component/phases/phase-1.5-existing-discovery.md

@@ -0,0 +1,174 @@
+# PHASE 1.5 — Existing Component Discovery
+
+Detects whether the target component is already implemented in the codebase OR already mapped via Code Connect, BEFORE Phase 2 starts greenfield generation. Without this gate, the pipeline can silently overwrite existing implementations and re-publish duplicate Code Connect mappings.
+
+PREV: Phase 1 (Data Gathering)
+NEXT: Phase 2 (Utility Integration) — only when status is `GREENFIELD_OK`
+REF: `phase-6-code-connect.md` (publish gate honors discovery output)
+
+---
+
+## ENTRY GATE
+
+| Condition | Action |
+|---|---|
+| `pass1/code_connect_map_response.json` missing | HALT — Phase 1 didn't complete cleanly |
+| All other cases | EXECUTE |
+
+---
+
+## STEP 1 — Inspect Code Connect map for self-reference
+
+INPUT: `{artifactPath}/pass1/code_connect_map_response.json`
+
+The map is a `{ nodeId: { codeConnectSrc, codeConnectName } }` lookup. The current target's nodeId may or may not appear.
+
+```python
+# Pseudocode
+target_node_id = state.issue.nodeId    # e.g. "7528:23317"
+target_name    = state.issue.componentName  # PascalCase, e.g. "MilesSmilesAccountSettingsAirlineProgramMembershipLayout"
+
+cc_map = json.load(open(f"{artifactPath}/pass1/code_connect_map_response.json"))
+
+if target_node_id in cc_map:
+    return {
+      "status": "ALREADY_MAPPED",
+      "sourcePath": cc_map[target_node_id]["codeConnectSrc"],
+      "componentName": cc_map[target_node_id]["codeConnectName"]
+    }
+```
+
+If `ALREADY_MAPPED`: the target Figma node is already wired to a code component. The pipeline does not generate a new component or republish Code Connect. It runs gap analysis instead (see Step 4).
+
+---
+
+## STEP 2 — Search the codebase for an existing source file
+
+If Step 1 returned no match, look for a file that matches the target component name. Use the project's component root (resolved from `figma-config.json` → `componentRoot` if set, else `Sources/UIComponents/Components/`).
+
+```bash
+find "$COMPONENT_ROOT" -type f -name "${target_name}.swift" 2>/dev/null | head -5
+```
+
+Three outcomes:
+
+| Files found | Status |
+|---|---|
+| 0 | `GREENFIELD_OK` — proceed to Phase 2 normally |
+| 1 | `EXISTING_SOURCE_NO_CC` — file exists but Code Connect mapping is missing |
+| 2+ | `AMBIGUOUS_SOURCE` — multiple files match; needs user disambiguation |
+
+For `EXISTING_SOURCE_NO_CC`, also check whether a sibling `.figma.swift` exists:
+
+```bash
+DIR=$(dirname "<found-file>")
+ls "$DIR/${target_name}.figma.swift" 2>/dev/null
+```
+
+If `.figma.swift` exists → the source has Code Connect locally but it was never published; offer to publish-only.
+If `.figma.swift` is absent → the source exists but is fully unconnected.
+
+---
+
+## STEP 3 — User decision (only on non-greenfield)
+
+When the orchestrator sees status `ALREADY_MAPPED`, `EXISTING_SOURCE_NO_CC`, or `AMBIGUOUS_SOURCE`, emit a `STATUS: NEEDS_INPUT` block to the parent multi-agent pipeline.
+
+### ALREADY_MAPPED
+
+```
+STATUS: NEEDS_INPUT
+PHASE: phase-1.5
+GATE: ALREADY_MAPPED
+DETECTED: {sourcePath} (already mapped to Figma node {nodeId})
+QUESTION: This Figma node is already wired to a code component. What should the pipeline do?
+OPTIONS:
+  1. Run gap analysis only (FIGMA.md / tests / wiki — fill what's missing, do NOT touch the component source)
+  2. Force regenerate (DANGER — overwrites the existing source file; only choose this if the design has materially changed)
+  3. Cancel — abort this run, no edits
+DEFAULT: 1
+```
+
+User answer feeds back to the orchestrator as a `USER_DECISION` block; on `1` set `state.discovery.status = "GAP_ANALYSIS"` and proceed to Step 4.
+
+### EXISTING_SOURCE_NO_CC
+
+```
+STATUS: NEEDS_INPUT
+PHASE: phase-1.5
+GATE: EXISTING_SOURCE_NO_CC
+DETECTED: {sourcePath} exists in the codebase but is not connected to the Figma node.
+SIBLING_FIGMA_SWIFT: {present | absent}
+QUESTION: Found an existing source file matching {target_name}. What should the pipeline do?
+OPTIONS:
+  1. Add Code Connect only — write {target_name}.figma.swift next to the source, publish it (recommended when sibling absent)
+  2. Publish-only — sibling .figma.swift already exists; just run `figma connect publish` (recommended when sibling present)
+  3. Force regenerate — overwrite the source file with a fresh greenfield generation
+  4. Cancel
+DEFAULT: 2 if sibling present, else 1
+```
+
+### AMBIGUOUS_SOURCE
+
+```
+STATUS: NEEDS_INPUT
+PHASE: phase-1.5
+GATE: AMBIGUOUS_SOURCE
+DETECTED: {N} candidates matching {target_name}.swift
+CANDIDATES: <bulleted list of paths>
+QUESTION: Pick the canonical source for this Figma node, or cancel.
+OPTIONS:
+  <one option per candidate>
+  N+1. None of the above — treat as greenfield
+  N+2. Cancel
+```
+
+---
+
+## STEP 4 — Gap analysis (only on ALREADY_MAPPED + user picked option 1)
+
+When the existing component is reused, the orchestrator still checks what's missing:
+
+```bash
+SRC_DIR=$(dirname "$sourcePath")
+[ -f "$SRC_DIR/FIGMA.md" ]              || gaps+=("FIGMA.md")
+[ -f "$SRC_DIR/${target_name}.figma.swift" ] || gaps+=("Code Connect")
+# Snapshot tests, ViewInspector tests, wiki MD, ...
+```
+
+The gap list goes into `state.discovery.gaps[]`. Phases 2/3 are SKIPPED. Phase 4–7 run only the steps that target gaps:
+
+| Gap | Phase that fills it |
+|---|---|
+| `FIGMA.md` | Phase 4c (Documentation) |
+| `Code Connect` | Phase 6 (Code Connect Publish) |
+| `Snapshot test` | Phase 5b |
+| `ViewInspector test` | Phase 5a |
+| `Wiki page` | Phase 7 |
+
+Phase 6 ENTRY GATE then sees `discovery.status === "GAP_ANALYSIS"` and `"Code Connect" in discovery.gaps` and runs publish; if Code Connect is NOT in gaps, Phase 6 is silently skipped.
+
+---
+
+## OUTPUT
+
+Phase 1.5 always writes the result to `agent-state.json`:
+
+```json
+{
+  "discovery": {
+    "status": "GREENFIELD_OK | ALREADY_MAPPED | EXISTING_SOURCE_NO_CC | AMBIGUOUS_SOURCE | GAP_ANALYSIS | CANCELLED",
+    "sourcePath": "Sources/.../Component.swift",   // when applicable
+    "siblingFigmaSwift": true | false,             // when applicable
+    "gaps": ["FIGMA.md", "Code Connect", ...]      // when applicable
+  }
+}
+```
+
+Phase 2 ENTRY GATE reads this and halts unless `status === "GREENFIELD_OK"` or the user explicitly picked "Force regenerate".
+
+---
+
+## CONSERVATIVE FALLBACK
+
+If anything in this phase fails (missing JSON, missing `find` binary, ambiguous parse), default to `GREENFIELD_OK` and log the anomaly. Better to do harmless duplicate work than to silently skip generation when the user expected it.