@mmerterden/multi-agent-pipeline 8.6.2 → 10.2.0

package/pipeline/skills/figma-common/figma-iterate/SKILL.md

@@ -1,4 +1,9 @@
-# /figma-iterate — Automated Implementation Pipeline
+---
+name: figma-iterate
+description: Picks the next available component issue and runs the full pipeline end-to-end: start → implement → commit. Loops until no more issues are available or the user stops it.
+---
+
+# /figma-iterate  -  Automated Implementation Pipeline
 
 ## Purpose
 
@@ -8,7 +13,7 @@ Picks the next available component issue and runs the full pipeline end-to-end:
 
 | Parameter | Required | Default | Description |
 |-----------|----------|---------|-------------|
-| `[#N]` | No | — | Specific issue to implement. If omitted, auto-picks next available. |
+| `[#N]` | No |  -  | Specific issue to implement. If omitted, auto-picks next available. |
 | `--count <N>` | No | all | Number of components to implement before stopping. |
 
 ```
@@ -28,7 +33,7 @@ GH_REPO = {github.componentsRepo}
 
 ---
 
-## STEP 0 — Pick Next Issue
+## STEP 0  -  Pick Next Issue
 
 ### If issue number provided:
 
@@ -41,7 +46,7 @@ gh issue view <N> --repo ${GH_REPO} --json number,title,state,labels --jq '{numb
 If closed → HALT: "Issue #N is already closed."
 If has `blocked` label → HALT: "Issue #N is blocked. Unblock first with `/figma-issue unblock #N`."
 
-### If no issue number — auto-pick:
+### If no issue number  -  auto-pick:
 
 Find the next available issue: open, `component` label, not `blocked`, not assigned.
 
@@ -62,14 +67,14 @@ Print:
 
 ```
 Next available issue:
-  #<N> — <title>
+  #<N>  -  <title>
 ```
 
 Print and STOP. Wait for user confirmation or "skip" to pick next.
 
 ---
 
-## STEP 1 — Start (`/figma-to-swift-ui-start`)
+## STEP 1  -  Start (`/figma-to-swift-ui-start`)
 
 Run the start skill logic inline (not as a sub-skill invocation):
 
@@ -98,18 +103,18 @@ These 6 rules govern orchestrator behavior. Violations have caused repeated fail
 
 ---
 
-## STEP 2 — Implement (Phases 0-7)
+## STEP 2  -  Implement (Phases 0-7)
 
 Extract Figma URL from the issue body.
 
-**Orchestrate inline** — run each phase by dispatching leaf-phase subagents and scripts directly. Read the full orchestration logic from `.instructions/figma/figma-cli-iterate/SKILL.md` STEP 2.
+**Orchestrate inline**  -  run each phase by dispatching leaf-phase subagents and scripts directly. Read the full orchestration logic from `.instructions/figma/figma-cli-iterate/SKILL.md` STEP 2.
 
 **NEVER dispatch multi-phase meta-skills as subagents:**
 - `/figma-to-swiftui`, `/figma-to-swift-ui-implement`, `/figma-to-swift-ui-test`, `/figma-to-swift-ui-code-connect`, `/figma-to-swift-ui-wiki`
 
 Instead, dispatch individual phase instruction files (e.g., `phase-2a-testing-identifiers.md`, `phase-4b-view.md`) as leaf subagents.
 
-**Spec injection (Option A):** If `{artifactPath}/pass0/specs.md` exists, read specs and inject concrete requirements into each subagent dispatch prompt as CRITICAL SPEC GATES — not as a sidecar file reference.
+**Spec injection (Option A):** If `{artifactPath}/pass0/specs.md` exists, read specs and inject concrete requirements into each subagent dispatch prompt as CRITICAL SPEC GATES  -  not as a sidecar file reference.
 
 Phases 0-7:
 - Phase 0: Init (subagent, leaf)
@@ -125,11 +130,11 @@ If any phase HALTs → print the halt reason, ask user to resolve, then resume.
 
 ---
 
-## STEP 3 — Commit (`/figma-iteration-commit`)
+## STEP 3  -  Commit (`/figma-iteration-commit`)
 
 Run the iteration commit logic inline:
 
-1. Validate — build, tests, key sync, review + auto-fix
+1. Validate  -  build, tests, key sync, review + auto-fix
 2. Commit to `iteration/develop` (common → uicomponents → wiki) + PR to `develop` (main, if needed)
 3. Push each
 4. Comment on issue with commit SHAs
@@ -147,7 +152,7 @@ Committed: <ComponentName> (#N)
 
 ---
 
-## STEP 4 — Loop
+## STEP 4  -  Loop
 
 If specific issue `#N` was provided → print summary and exit (single run).
 
@@ -173,7 +178,7 @@ Before picking next, print:
 
 ---
 
-## STEP 5 — Final Summary
+## STEP 5  -  Final Summary
 
 Print at the end of the loop:
 
@@ -196,8 +201,8 @@ Remaining: N open issues
 ## Error Handling
 
 - **No available issues**: Exit cleanly with message.
-- **Blocked issue (manual pick)**: HALT — don't implement blocked components.
+- **Blocked issue (manual pick)**: HALT  -  don't implement blocked components.
 - **Phase HALT**: Show reason, ask user. If resolved → resume. If skipped → mark issue, move to next.
-- **Build/test failure in commit**: HALT — don't push broken code.
+- **Build/test failure in commit**: HALT  -  don't push broken code.
 - **3 consecutive HALTs**: Stop iteration to prevent infinite failure loops.
 - **Submodules not on iteration/develop**: Auto-checkout before starting.

package/pipeline/skills/figma-common/figma-iteration-commit/SKILL.md

@@ -1,20 +1,25 @@
-# /figma-iteration-commit — Validate & Commit to iteration/develop + PR to develop
+---
+name: figma-iteration-commit
+description: NEVER create branches on the main repo (REPO_ROOT). Do not create `iteration/develop` or any other branch on the main repo. Do not commit to the main repo.
+---
+
+# /figma-iteration-commit  -  Validate & Commit to iteration/develop + PR to develop
 
 ## Guardrails
 
-> **NEVER create branches on the main repo (REPO_ROOT).** Do not create `iteration/develop` or any other branch on the main repo. Do not commit to the main repo. This skill only commits to submodules (common, uicomponents, wiki). Main repo submodule refs are updated separately — not by this skill.
+> **NEVER create branches on the main repo (REPO_ROOT).** Do not create `iteration/develop` or any other branch on the main repo. Do not commit to the main repo. This skill only commits to submodules (common, uicomponents, wiki). Main repo submodule refs are updated separately  -  not by this skill.
 
 > **NEVER use `json.dumps()` default formatting on JSON files.** When editing JSON files (e.g., `ui-testing-identifiers.json`), preserve the existing file format. Do not reformat, re-indent, or change separators. The canonical format for `ui-testing-identifiers.json` is `" : "` (space-colon-space), not `": "`. If you must write JSON programmatically, post-process the output to match the existing format.
 
 > **NEVER manually edit `ui-testing-identifiers.json`.** Format corruption on this file is most likely caused by conflict resolution. When a rebase conflict occurs on this file:
-> 1. Check what keys we added — look at `Shared/Figma/Components/{nodeId}.json` (has the key list) or `git show HEAD:Shared/UITestingIdentifiers/ui-testing-identifiers.json`
+> 1. Check what keys we added  -  look at `Shared/Figma/Components/{nodeId}.json` (has the key list) or `git show HEAD:Shared/UITestingIdentifiers/ui-testing-identifiers.json`
 > 2. Take the remote version: `git checkout --ours Shared/UITestingIdentifiers/ui-testing-identifiers.json` (during rebase, `--ours` = upstream/remote)
-> 3. Re-add our keys via `/common-utility` (`utility-add-key`) — this writes in the correct `" : "` format
+> 3. Re-add our keys via `/common-utility` (`utility-add-key`)  -  this writes in the correct `" : "` format
 > 4. `git add Shared/UITestingIdentifiers/ui-testing-identifiers.json` + `git rebase --continue`
 >
-> Never resolve JSON conflicts by hand-editing or `json.dumps()` — it reformats the entire file.
+> Never resolve JSON conflicts by hand-editing or `json.dumps()`  -  it reformats the entire file.
 
-> **ALWAYS validate `ui-testing-identifiers.json` key count after every rebase — even when there were no conflicts.** The implement agent regenerates this file from `identifier-keys.json` only, which means an auto-merge can silently drop keys that exist on `iteration/develop` but not in the local metadata. After every rebase (or cherry-pick), before staging and continuing, run:
+> **ALWAYS validate `ui-testing-identifiers.json` key count after every rebase  -  even when there were no conflicts.** The implement agent regenerates this file from `identifier-keys.json` only, which means an auto-merge can silently drop keys that exist on `iteration/develop` but not in the local metadata. After every rebase (or cherry-pick), before staging and continuing, run:
 >
 > ```bash
 > REMOTE_KEY_COUNT=$(git show origin/iteration/develop:Shared/UITestingIdentifiers/ui-testing-identifiers.json 2>/dev/null | grep -c '".*" : "' || echo 0)
@@ -25,7 +30,7 @@
 >   echo "   Restoring from origin/iteration/develop and re-adding component keys..."
 >   git show origin/iteration/develop:Shared/UITestingIdentifiers/ui-testing-identifiers.json \
 >     > Shared/UITestingIdentifiers/ui-testing-identifiers.json
->   # Re-add our component's keys (they are in identifier-keys.json — tool will merge them in)
+>   # Re-add our component's keys (they are in identifier-keys.json  -  tool will merge them in)
 >   .build/debug/UITestingIdentifierTool generate \
 >     --config Shared/UITestingIdentifiers/Config/identifier-config.json
 >   git add Shared/UITestingIdentifiers/ui-testing-identifiers.json
@@ -35,7 +40,7 @@
 >
 > This guard runs even when `ui-testing-identifiers.json` was NOT in the conflict list. Silent key loss from auto-merge is the most common failure mode.
 
-> **ALWAYS validate Generated Swift key files after every rebase — even when there were no conflicts.** The codegen tool (`UnifiedCodeGenerationTool`) regenerates `LocalizationStringKeys.swift` and `LocalizedAccessibilityStringKeys.swift` from config JSONs that reference `Sources/Suggested/*.json` files. An auto-merge (or accepting either side during conflict resolution) can silently drop enum blocks if the suggested-key files from another developer's component are not present locally. After every rebase (or cherry-pick), before rebuilding, run:
+> **ALWAYS validate Generated Swift key files after every rebase  -  even when there were no conflicts.** The codegen tool (`UnifiedCodeGenerationTool`) regenerates `LocalizationStringKeys.swift` and `LocalizedAccessibilityStringKeys.swift` from config JSONs that reference `Sources/Suggested/*.json` files. An auto-merge (or accepting either side during conflict resolution) can silently drop enum blocks if the suggested-key files from another developer's component are not present locally. After every rebase (or cherry-pick), before rebuilding, run:
 >
 > ```bash
 > LOC_FILE="iOS/Sources/LocalizationStringKeys/Generated/LocalizationStringKeys.swift"
@@ -54,9 +59,9 @@
 > done
 > ```
 >
-> This guard runs even when the Generated files were NOT in the conflict list. Silent enum loss from auto-merge or "accept either side" resolution is a known failure mode — the rebuild script's codegen step (3.5) will re-add our component's keys on top of the restored remote file.
+> This guard runs even when the Generated files were NOT in the conflict list. Silent enum loss from auto-merge or "accept either side" resolution is a known failure mode  -  the rebuild script's codegen step (3.5) will re-add our component's keys on top of the restored remote file.
 
-> **ALWAYS validate `Sources/Suggested/*.json` file count after every rebase, cherry-pick, AND before every commit — even when there were no conflicts.** The implement agent only creates source JSONs for the current component. A rebase, cherry-pick, or `git add -A` can silently drop source JSON files belonging to OTHER components (e.g., a tool run deletes files, or a workspace reset loses them). These per-key source files are the ground truth for localization and accessibility code generation — losing them means generated code silently loses keys for other components. After every rebase (or cherry-pick), AND before every `git add -A` in the commit step, run:
+> **ALWAYS validate `Sources/Suggested/*.json` file count after every rebase, cherry-pick, AND before every commit  -  even when there were no conflicts.** The implement agent only creates source JSONs for the current component. A rebase, cherry-pick, or `git add -A` can silently drop source JSON files belonging to OTHER components (e.g., a tool run deletes files, or a workspace reset loses them). These per-key source files are the ground truth for localization and accessibility code generation  -  losing them means generated code silently loses keys for other components. After every rebase (or cherry-pick), AND before every `git add -A` in the commit step, run:
 >
 > ```bash
 > for SUGGESTED_DIR in \
@@ -83,7 +88,7 @@
 >
 > This guard catches the most dangerous form of silent data loss: source JSON files from OTHER components being deleted by the current component's pipeline. Unlike generated files (which can be rebuilt), source JSONs contain the original translations and cannot be re-derived.
 
-> **NEVER call `common-rebuild-derived-artifacts.sh` blindly after conflict resolution when `ui-testing-identifiers.json` may have been touched.** The rebuild script calls `UITestingIdentifierTool generate --swift-only` which only writes the Swift file — but the JSON may already be corrupt from a bad auto-merge. Always run the key-count integrity check BEFORE the rebuild script, and fix the JSON FIRST if the count decreased.
+> **NEVER call `common-rebuild-derived-artifacts.sh` blindly after conflict resolution when `ui-testing-identifiers.json` may have been touched.** The rebuild script calls `UITestingIdentifierTool generate --swift-only` which only writes the Swift file  -  but the JSON may already be corrupt from a bad auto-merge. Always run the key-count integrity check BEFORE the rebuild script, and fix the JSON FIRST if the count decreased.
 
 ## Conflict File Classification (common submodule)
 
@@ -99,7 +104,7 @@ When a cherry-pick or rebase conflict occurs in the common submodule, classify e
 | `Shared/UITestingIdentifiers/Metadata/*` | Accept either side | Gitignored, will regenerate |
 | `Sources/Suggested/*.json` | Our version wins | Per-key files, we created them |
 | `Shared/Figma/Components/*.json` | Our version wins | We created/modified it |
-| `Shared/UITestingIdentifiers/ui-testing-identifiers.json` | Take remote + re-add keys via tool | See Guardrails — never hand-edit |
+| `Shared/UITestingIdentifiers/ui-testing-identifiers.json` | Take remote + re-add keys via tool | See Guardrails  -  never hand-edit |
 | `Shared/UIAssets/Colors/*.json` | Take remote + manually insert new entries | Match existing format exactly |
 
 **After resolving all conflicts, ALWAYS rebuild derived artifacts:**
@@ -120,8 +125,8 @@ Validates a component implementation, commits directly to `iteration/develop` in
 
 | Parameter | Required | Default | Description |
 |-----------|----------|---------|-------------|
-| `<ComponentName>` | Yes | — | PascalCase component name |
-| `--gh` | No | — | GitHub issue number (auto-detected if on a tracked issue) |
+| `<ComponentName>` | Yes |  -  | PascalCase component name |
+| `--gh` | No |  -  | GitHub issue number (auto-detected if on a tracked issue) |
 
 ```
 /figma-iteration-commit ModalsTitle
@@ -144,7 +149,7 @@ DEFAULT_JIRA    = {jira.projectKey}-124692
 
 ---
 
-## STEP 0 — Resolve
+## STEP 0  -  Resolve
 
 1. Parse `ComponentName`. Convert to kebab-case.
 2. If `--gh` provided, read the issue to get Jira key. Otherwise search for the issue:
@@ -173,7 +178,7 @@ DEFAULT_JIRA    = {jira.projectKey}-124692
       - Reset iteration/develop to its previous state
       - Restore the feature branch from the backup
       - HALT: "Rebase broke the build. Feature branch preserved at {branch-name}."
-      - Do NOT delete the backup — leave it for manual resolution
+      - Do NOT delete the backup  -  leave it for manual resolution
    ```
 
    ```bash
@@ -198,7 +203,7 @@ DEFAULT_JIRA    = {jira.projectKey}-124692
      # Cherry-pick feature commits
      for COMMIT in ${COMMITS}; do
        git cherry-pick ${COMMIT} || {
-         # CONFLICT HANDLING — do NOT abort or delete any changes
+         # CONFLICT HANDLING  -  do NOT abort or delete any changes
          echo "⚠️  Cherry-pick conflict at ${COMMIT}."
          echo "Conflicting files:"
          CONFLICTED_FILES=$(git diff --name-only --diff-filter=U)
@@ -366,7 +371,7 @@ DEFAULT_JIRA    = {jira.projectKey}-124692
 
 ---
 
-## STEP 1 — Validate
+## STEP 1  -  Validate
 
 ### 1a. Build
 
@@ -402,7 +407,7 @@ python3 .instructions/figma/figma-to-swiftui/scripts/validate-localization-sync.
     --component "{ComponentName}"
 ```
 
-If out of sync → HALT. Regenerate with `update-*-dev` (NOT `generate-*-code` — see common-utility docs):
+If out of sync → HALT. Regenerate with `update-*-dev` (NOT `generate-*-code`  -  see common-utility docs):
 ```bash
 swift package plugin --allow-writing-to-package-directory update-localizations-dev
 swift package plugin --allow-writing-to-package-directory update-accessibility-dev
@@ -429,7 +434,7 @@ Validation: PASS / FAIL
 
 ---
 
-## STEP 2 — Detect Changes
+## STEP 2  -  Detect Changes
 
 ```bash
 HAS_COMMON=$(cd "${COMMON}" && git status --porcelain | head -1)
@@ -439,9 +444,9 @@ HAS_WIKI=$(cd "${WIKI}" && git status --porcelain | head -1)
 
 ---
 
-## STEP 3 — Commit Locally
+## STEP 3  -  Commit Locally
 
-Commit to local `iteration/develop` in submodules. Do NOT push yet — pushing happens in STEP 3b after validation confirms the build is clean.
+Commit to local `iteration/develop` in submodules. Do NOT push yet  -  pushing happens in STEP 3b after validation confirms the build is clean.
 
 ### 3a. Commit (local only)
 
@@ -500,7 +505,7 @@ Refs: ${JIRA_ISSUE}"
 
 ---
 
-### ⛔ 3a-gate — Pre-Push Approval (required HARD STOP)
+### ⛔ 3a-gate  -  Pre-Push Approval (required HARD STOP)
 
 > **Do NOT proceed to STEP 3b until the user explicitly approves.**
 > Use the `ask-questions` tool here. A silent "yes" assumption is a pipeline violation.
@@ -509,7 +514,7 @@ Refs: ${JIRA_ISSUE}"
 
 ```
 ╔══════════════════════════════════════════════════════════════════╗
-║  PRE-PUSH SUMMARY — iteration/develop                           ║
+║  PRE-PUSH SUMMARY  -  iteration/develop                           ║
 ╠══════════════════════════════════════════════════════════════════╣
 ║  common (if HAS_COMMON):                                        ║
 ║    Branch : iteration/develop                                    ║
@@ -534,7 +539,7 @@ Refs: ${JIRA_ISSUE}"
 Generate this summary with:
 
 ```bash
-# For each submodule with commits — adapt branch name per repo:
+# For each submodule with commits  -  adapt branch name per repo:
 cd ${SUBMODULE}
 echo "Ahead: $(git rev-list origin/${PUSH_BRANCH}..HEAD --count) commits"
 git log origin/${PUSH_BRANCH}..HEAD --oneline
@@ -561,7 +566,7 @@ git diff origin/${PUSH_BRANCH}..HEAD --stat | tail -1
   Run /figma-iteration-commit again when ready to push.
   ```
 
-  Then **HALT** — do not revert any local commits, do not push anything.
+  Then **HALT**  -  do not revert any local commits, do not push anything.
 
 ---
 
@@ -590,12 +595,12 @@ MAX_RETRIES=3
 for i in $(seq 1 $MAX_RETRIES); do
   git push origin ${PUSH_BRANCH} && break
 
-  echo "Push rejected — remote updated. Rebasing (attempt $i)..."
+  echo "Push rejected  -  remote updated. Rebasing (attempt $i)..."
   git fetch origin ${PUSH_BRANCH}
   git rebase origin/${PUSH_BRANCH}
 
   if [ $? -ne 0 ]; then
-    # CONFLICT HANDLING — do NOT abort or delete any changes
+    # CONFLICT HANDLING  -  do NOT abort or delete any changes
     echo "⚠️  Rebase conflict detected during push retry."
     echo "Conflicting files:"
     CONFLICTED_FILES=$(git diff --name-only --diff-filter=U)
@@ -763,7 +768,7 @@ cd ${UICOMPONENTS} && git fetch origin iteration/develop
 
 ---
 
-## STEP 4 — Issue Housekeeping
+## STEP 4  -  Issue Housekeeping
 
 ### 4a. Comment on issue
 
@@ -788,7 +793,7 @@ EOF
 Phase state is tracked per-flag in the component registry
 (`status.ios.{implemented,tested,codeConnect,wiki}`), written by the
 phase finalize scripts during STEP 2 of `/figma-cli-iterate`. The
-issue's labels and Progress table are projections of that state — no
+issue's labels and Progress table are projections of that state  -  no
 filesystem inference anymore.
 
 Run the registry sync once, after the commit succeeds:
@@ -812,7 +817,7 @@ This call is idempotent:
   lowest-numbered one with a "Duplicate of #N" comment.
 
 If the call fails (gh not authenticated, rate limit, etc.), log the
-error but don't fail the commit — the sync can always be re-run
+error but don't fail the commit  -  the sync can always be re-run
 manually or via `bulk-sync-issues.py`.
 
 ### 4c. Link wiki to issue
@@ -944,7 +949,7 @@ for comp_name in connected:
         sub_issues_added.append(f"#{sub_issue_n} ({comp_name})")
         print(f"  ✅ Linked sub-issue #{sub_issue_n} ({comp_name})")
     else:
-        # May already be linked — not a fatal error
+        # May already be linked  -  not a fatal error
         print(f"  ℹ️  Could not link #{sub_issue_n} ({comp_name}): {api_result.stderr.strip()}")
 
 if sub_issues_added:
@@ -953,12 +958,12 @@ else:
     print("No sub-issues linked (no matching open issues found).")
 ```
 
-> **Non-fatal:** If this step fails (artifact missing, gh API error, no matching issues), log and continue — it must never block the commit.
+> **Non-fatal:** If this step fails (artifact missing, gh API error, no matching issues), log and continue  -  it must never block the commit.
  
 
 ---
 
-## STEP 5 — Auto-Unblock Dependents
+## STEP 5  -  Auto-Unblock Dependents
 
 Scan all open issues with `blocked` label:
 
@@ -982,7 +987,7 @@ Print any unblocked issues.
 
 ---
 
-## STEP 6 — Summary
+## STEP 6  -  Summary
 
 ```
 Iteration Commit: ${COMPONENT_PASCAL}
@@ -995,7 +1000,7 @@ Iteration Commit: ${COMPONENT_PASCAL}
 | main | ${MAIN_SHA} | ✅ pushed / PR created |
 
 Validation: PASS
-Issue: #N — commented + phase updated
+Issue: #N  -  commented + phase updated
 Sub-issues: #X (ComponentA), #Y (ComponentB) (or "none")
 Unblocked: #M, #K (or "none")
 Jira: ${JIRA_ISSUE}
@@ -1006,9 +1011,9 @@ Jira: ${JIRA_ISSUE}
 ## Error Handling
 
 - **Submodules not on iteration/develop**: Checkout automatically (rebase-merge if commits exist).
-- **Build fails**: HALT — fix before committing.
-- **Tests fail**: HALT — fix before committing.
-- **Key sync fails**: HALT — regenerate keys first.
+- **Build fails**: HALT  -  fix before committing.
+- **Tests fail**: HALT  -  fix before committing.
+- **Key sync fails**: HALT  -  regenerate keys first.
 - **Push rejected**: Report error, do NOT force-push.
 - **No changes**: Print "Nothing to commit" and exit.
 - **Issue not found**: Commit without issue housekeeping, print warning.

package/pipeline/skills/figma-common/figma-mend/SKILL.md

@@ -8,7 +8,7 @@ status: wip-v5
 sourced-from: upstream/figma-mend
 ---
 
-# /figma-mend — Re-implement Discarded Components
+# /figma-mend  -  Re-implement Discarded Components
 
 This skill wraps the full `figma-to-swiftui` workflow (Phases 0-8) with two additions:
 1. **Pre-flight**: Locates old component in `Discarded/`, catalogs all its files
@@ -36,7 +36,7 @@ Same as figma-to-swiftui: extract `fileKey` and `nodeId`, convert `-` to `:` in
 
 ---
 
-## Pre-Flight Phase (orchestrator-level — no subagent)
+## Pre-Flight Phase (orchestrator-level  -  no subagent)
 
 Run BEFORE Phase 0. Uses Grep/Glob/Bash directly in the main orchestrator.
 
@@ -122,7 +122,7 @@ Follow the EXACT same execution order as `.instructions/figma/figma-to-swiftui/S
 
 ### Dispatch Table
 
-Use the SAME dispatch table from `.instructions/figma/figma-to-swiftui/SKILL.md` — same phases, same models, same turn limits, same tool restrictions, same phase instruction paths. Do NOT read that file — the table is reproduced here for reference:
+Use the SAME dispatch table from `.instructions/figma/figma-to-swiftui/SKILL.md`  -  same phases, same models, same turn limits, same tool restrictions, same phase instruction paths. Do NOT read that file  -  the table is reproduced here for reference:
 
 | Phase | Instruction (under figma-to-swiftui/) | Model | Max Turns | Tool Restrictions |
 |-------|---------------------------------------|-------|-----------|-------------------|
@@ -160,8 +160,8 @@ The ONLY change from figma-to-swiftui: append this section to every AI subagent
 ## Complementary Reference (Old Implementation)
 
 This component is being RE-IMPLEMENTED from Discarded/.
-Old source files (read as reference — do NOT copy verbatim):
-{list of relevant old file paths from oldFilesCatalog — see injection table below}
+Old source files (read as reference  -  do NOT copy verbatim):
+{list of relevant old file paths from oldFilesCatalog  -  see injection table below}
 
 Preserve domain-specific patterns if architecturally sound:
 - Animations, transitions, gesture handling
@@ -172,7 +172,7 @@ Preserve domain-specific patterns if architecturally sound:
 
 IMPORTANT: New implementation MUST follow current workflow standards
 (macros, Configuration pattern, design tokens). Use old code ONLY as reference
-for domain logic — not as a template for architecture.
+for domain logic  -  not as a template for architecture.
 ```
 
 ### Selective File Injection Table

package/pipeline/skills/figma-common/figma-navigation/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: figma-navigation
+description: "Navigation pattern integration for Figma-to-SwiftUI components. Guides how a component reaches other screens, tabs, or deep links without coupling to a router — headless screens that emit a typed Output, native NavigationStack/navigationDestination by default, an optional project-supplied navigation system (router + route enum + scene container) when figma-config declares one. Reach for this when a design embeds a tab bar, nav bar / back button, a push/detail affordance, or a deep-link entry point."
+user-invocable: true
+allowed-tools: Read, Glob, Grep
+status: wip-v5
+sourced-from: upstream/figma-navigation
+---
+
+# /figma-navigation  -  Navigation Pattern Integration
+
+## Purpose
+
+Consumed by the figma-to-swiftui pipeline (Phase 3D pattern detection, Phase 4B view implementation) and available for ad-hoc/vibe-coding, this skill defines how a component participates in navigation **without owning routing**. It is the navigation counterpart of `/figma-form-integration` and `/figma-price-integration`: a cross-cutting integration with a **native-SwiftUI default** and a **config-driven hook** for projects that ship their own navigation system.
+
+**Generic by design.** Nothing here assumes a specific app. The default is stock SwiftUI (`NavigationStack`, `navigationDestination`, `.toolbar`, `.sheet`). If the target project declares a custom navigation system in its `figma-config.json` (`ui.navigationSystem`), this skill routes to that system's types by name instead — same rules, project-specific vocabulary.
+
+---
+
+## Strict Rules (non-negotiable)
+
+1. **A component never names a route, a sibling screen, or a router.** A component/screen takes its arrival data as init params and emits intent through a typed **`Output`** closure (`onSelect`, `onSubmit`, `output:`). The *caller* (scene/coordinator/parent) maps each output to a navigation edge. This keeps the component reusable and testable in isolation.
+2. **No navigation side effects inside a component body.** No `NavigationLink(destination:)` hardcoding a concrete next screen, no router calls, no global singletons touched from `body`. Navigation is a caller concern expressed via the emitted output.
+3. **Selection/tab state is observable data, not an imperative bridge.** A selected tab/section is a bound value (`@Binding`/observable), written by the caller; the component reflects it. A selection set before the container mounts is simply rendered on appear  -  no cold-start race.
+4. **Deep links reduce to state and never crash.** A URL parses to a plan/value; malformed input is dropped (logged, no trap). The component is never the deep-link parser  -  it only exposes the entry state the parser can set.
+5. **Native SwiftUI is the default; a custom system is opt-in via config.** Do NOT invent a bespoke router for a project that hasn't asked for one. Only use custom navigation types when `ui.navigationSystem.mode == "custom"` is set in `figma-config.json`.
+
+---
+
+## When to Invoke This Skill
+
+Invoke when ANY of these are detected in the design or task:
+
+1. **Phase 3D  -  navigation sub-component / affordance:** a nested instance of a navigation-capable design element:
+   - Tab bar / segmented section switcher that changes the top-level view
+   - Navigation bar / header with a **back button** or close affordance
+   - A row/card whose variant implies a **push/detail** affordance (chevron, "Detaylar", disclosure)
+   - A link/button whose label implies leaving the screen ("Devam", "Tümünü gör")
+   - A deep-link entry point (the design is a landing surface reached by URL)
+2. **Phase 4B  -  View:** the view renders a back button, tab strip, or a control that should navigate.
+3. **Ad-hoc:** wiring a screen's push/pop/tab/deep-link flow outside the full pipeline.
+
+**Not navigation (false-positive guards):**
+- A segmented control that filters in-place (no screen change) → plain `Binding<Enum>`, not navigation.
+- A button that submits a form → that's `/figma-form-integration`; the *result* may navigate, but the control is a form action.
+- A modal card of data / a toast / a loading HUD → `/figma-overlays`. A bottom sheet surface → `/figma-bottom-sheets`.
+
+---
+
+## Native-first architecture (default)
+
+```
+Parent / Scene (caller)
+    |  owns NavigationStack(path:) or tab Binding, maps Output → edge
+    v
+ComponentView
+    |  init(arrivalData…, output: @escaping (Output) -> Void)
+    |  emits .selected(id) / .continue / .back  -  never routes
+    v
+(caller) path.append(route)  |  selectedTab = .x  |  present(.sheet)
+```
+
+- **Push/pop within a flow:** caller owns `NavigationStack(path:)`; component emits `Output`; caller appends a `Hashable` route; `navigationDestination(for:)` renders it.
+- **Back button:** prefer the system back button. A custom header back affordance emits `.back` (or calls `dismiss`); it renders only when there is something to pop (depth > 0 / `isPresented`).
+- **Tabs:** `TabView(selection:)` bound to an observable selection the caller owns; the component reads/writes the binding, never a global.
+- **Deep links:** caller parses URL → a `Hashable` route / tab selection and applies it to the same path/selection state the UI already uses. Component only exposes the entry state.
+- **Modal presentation of another screen:** `.sheet(item:)` / `.fullScreenCover(item:)` driven by caller state (data-driven, no `AnyView`). A *bottom sheet surface* is `/figma-bottom-sheets`; an *alert/data modal card* is `/figma-overlays`.
+
+Design tokens (spacing, colors, typography) follow `reference/ui` + the project's figma-config token patterns  -  never raw literals.
+
+## Config hook  -  project-supplied navigation system
+
+When `figma-config.json` declares:
+```jsonc
+"ui": { "navigationSystem": {
+  "mode": "custom",
+  "router": "AppRouter",            // type that dispatches routes
+  "routeEnum": "AppRoute",          // exhaustive cross-surface route enum
+  "sceneType": "SceneContent",      // headless screen container (optional)
+  "navigatorProtocol": "NavigatorProtocol"  // DI'd selection/present API (optional)
+}}
+```
+then apply the SAME rules, but express them in the project's vocabulary resolved from config (do NOT hardcode the names below  -  read them from `ui.navigationSystem`):
+
+- Wrap screen content in `{sceneType}` (headless container) instead of a bare `NavigationStack` child, when provided.
+- Screens still emit a typed `Output`; the domain coordinator maps outputs to the project's route type (`{routeEnum}`) and the `{router}` dispatches.
+- Cross-surface jumps go through the DI'd `{navigatorProtocol}` (`selectTab`, `present`), never by importing a sibling domain.
+- Deep links build the project's `{routeEnum}` case and hand it to the router's deep-link entry.
+
+If `mode` is absent or `native`, use the native-first section above. Resolve types via `tools/resource-utility` / repo grep only when the config points at real files.
+
+---
+
+## Integration with Phase 3D
+
+When Phase 3D detects a navigation affordance, record it in `04b_component_architecture.md` and classify it as an **Output**, not a route:
+
+```markdown
+## Navigation
+| Affordance | Emits | Caller maps to |
+|---|---|---|
+| Back button (header) | `.back` closure / dismiss | pop current stack |
+| Row chevron ("Detaylar") | `.selected(id)` | push detail route |
+| Tab strip | `selection: Binding<Tab>` | caller-owned tab state |
+| Deep-link landing | entry `route`/`tab` param | parser sets caller state |
+```
+
+Property classification addition:
+
+| Classification | When | Swift Pattern |
+|---|---|---|
+| Navigation output | Component has a push/select/back affordance | `output: (Output) -> Void` / `onSelect: (ID) -> Void` closure on the View |
+| Tab/selection binding | Component switches top-level content | `selection: Binding<SomeTab>` |
+| Deep-link entry | Component is a URL landing surface | plain entry `route`/`tab` param on the View/Configuration |
+
+The affordance's **label/icon copy is static Configuration content** (localized), exactly like other copy  -  only the *intent* is an Output closure.
+
+## Integration with Phase 4B
+
+- Never hardcode `NavigationLink(destination: ConcreteScreen())` inside a reusable component  -  emit the Output.
+- Prefer the system back button; a custom back affordance calls `@Environment(\.dismiss)` or emits `.back`.
+- Bind tab/selection via the caller-owned binding; never a global.
+- If `ui.navigationSystem.mode == custom`, wrap in `{sceneType}` and route via `{router}`/`{routeEnum}` per config.
+- Verify by building + running on the simulator (`reference/build-and-test` / `figma-to-component` Phase 5): the transition happens, the back button appears only after a push, deep links land on the right surface.
+
+---
+
+## When NOT to Use Navigation Integration
+- In-place filters/segmented state that never changes screen → `Binding<Enum>`.
+- Form submission → `/figma-form-integration` (the *result* may navigate; the control is a form action).
+- Toast / loading / alert / data modal → `/figma-overlays`. Bottom-sheet surface → `/figma-bottom-sheets`.
+
+## Checklist  -  Before Leaving the Skill
+```
+[ ] Component emits a typed Output for every navigation affordance  -  no hardcoded routes
+[ ] Back uses system back / dismiss / .back output; renders only when poppable
+[ ] Tab/selection is a caller-owned binding, not a global
+[ ] Deep-link entry is plain state the caller's parser can set (component never parses URLs)
+[ ] Default is native SwiftUI (NavigationStack/navigationDestination/TabView/.sheet(item:))
+[ ] Custom system used ONLY when figma-config ui.navigationSystem.mode == custom (names from config)
+[ ] Labels/icons are localized Configuration copy; only intent is a closure
+```