@mmerterden/multi-agent-pipeline 11.2.0 → 11.3.1

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

@@ -1,307 +0,0 @@
-# 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

@@ -1,119 +0,0 @@
-# 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

@@ -1,174 +0,0 @@
-# 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. "MyComponentSettingsLayout"
-
-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.