@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/figma-common/performance-swiftui/SKILL.md

@@ -0,0 +1,706 @@
+---
+name: performance-swiftui
+description: Performance-optimized Figma-to-SwiftUI workflow. Same phases as figma-to-swiftui but with model downgrades on deterministic phases, parallel Phase 6+7 execution, combined test execution, and disk-persisted elapsed time tracking. Supports --lean flag to skip testing (Phase 5) and wiki (Phase 7).
+user-invocable: true
+argument-hint: <figma-url> [--lean] | phase-<N> | status
+allowed-tools: Task, Read, Glob, Grep, Bash, Write, Edit, AskUserQuestion
+status: wip-v5
+sourced-from: upstream/performance-swiftui
+---
+
+# /performance-swiftui — Performance-Optimized Figma-to-SwiftUI Workflow
+
+> Based on `/figma-to-swiftui`. All phase instruction files, scripts, and reference docs
+> are shared from `.instructions/figma/figma-to-swiftui/`. Only the orchestrator routing,
+> model selection, turn allocation, and execution strategy differ.
+
+## Parse Arguments
+
+`$ARGUMENTS` determines the mode:
+
+| Input | Mode | Action |
+|-------|------|--------|
+| `https://www.figma.com/design/...` | **Start** | Extract fileKey + nodeId, begin Phase 0 |
+| `https://www.figma.com/design/... --lean` | **Start (lean)** | Same as Start but skip Phase 5 (testing) and Phase 7 (wiki) |
+| `phase-0` through `phase-6` | **Resume** | Read IMPLEMENTATION_HISTORY.md, dispatch that phase |
+| `phase-2a` through `phase-2d` | **Resume** | Dispatch specific Phase 2 sub-phase |
+| `phase-5a` through `phase-5d` | **Resume** | Dispatch specific Phase 5 sub-phase |
+| `phase-7` | **Resume** | Run Phase 7A (generate wiki markdown) |
+| `phase-7a` | **Resume** | Dispatch Phase 7A only (generate wiki markdown) |
+| `status` | **Status** | Read and display IMPLEMENTATION_HISTORY.md |
+
+### Lean Mode (`--lean`)
+
+When `--lean` is appended to a Figma URL, the workflow runs **Phases 0–4 + Phase 6 only**.
+Phase 5 (testing) and Phase 7 (wiki) are **skipped**.
+
+Lean mode is persisted in the `_perf_tracker.json` tracker:
+
+```json
+{
+  "lean_mode": true
+}
+```
+
+When resuming from a `phase-N` argument, read `_perf_tracker.json` to detect lean mode.
+If `lean_mode` is `true`, skip Phase 5 and Phase 7 even if explicitly requested.
+
+### URL Parsing
+
+Extract from Figma URL:
+```
+https://www.figma.com/design/{fileKey}/{fileName}?node-id={nodeId}
+```
+Convert `-` to `:` in node-id (e.g., `9419-30700` → `9419:30700`).
+
+---
+
+## Elapsed Time Tracking
+
+> **All timing, HALT, and retry data is persisted to disk after every phase.**
+> This ensures the workflow summary survives context loss, conversation cuts, and token budget exhaustion.
+
+### Tracker File
+
+All performance metrics are stored in `{artifactPath}/_perf_tracker.json`. This file is the **single source of truth** — never rely on in-memory variables for timing or reliability data.
+
+**At workflow start** (Phase 0 or first resumed phase), create/update the tracker file:
+
+```bash
+TRACKER="{artifactPath}/_perf_tracker.json"
+```
+
+Initial content (written at Phase 0 start):
+
+```json
+{
+  "workflow_start": "2026-03-18T14:30:00Z",
+  "lean_mode": false,
+  "phases": {},
+  "halt_count": 0,
+  "retry_count": 0,
+  "halt_log": []
+}
+```
+
+If `--lean` flag is active, set `"lean_mode": true`.
+
+**After every phase completes** (or HALTs/retries), update the tracker file on disk:
+
+```python
+import json, datetime
+
+tracker_path = "{artifactPath}/_perf_tracker.json"
+with open(tracker_path) as f:
+    tracker = json.load(f)
+
+# Record phase timing
+tracker["phases"]["phase_N"] = {
+    "name": "Phase N (Name)",
+    "start": "ISO-8601",
+    "end": "ISO-8601",
+    "duration_seconds": 123,
+    "status": "COMPLETE"  # or "HALT", "SKIPPED"
+}
+
+# If HALT occurred, also update:
+# tracker["halt_count"] += 1
+# tracker["halt_log"].append({"phase": "N", "gate": "...", "reason": "...", "resolution": "..."})
+
+# If retry occurred:
+# tracker["retry_count"] += 1
+
+with open(tracker_path, "w") as f:
+    json.dump(tracker, f, indent=2)
+```
+
+**CRITICAL:** The tracker file write happens IMMEDIATELY after each phase dispatch returns — before proceeding to the next phase. This is the mechanism that survives context loss.
+
+---
+
+## required PRE-READ
+
+Before dispatching any phase subagent, read:
+  .instructions/figma/figma-to-swiftui/reference/orchestrator-discipline.md
+
+These 6 rules govern orchestrator behavior. Violations have caused repeated failures. Follow them strictly.
+
+---
+
+## Phase Execution Order
+
+**Full mode (default):**
+```
+0 (Init) → 1 (Gather) → 2A → 2B → 2C → 2D → 3 (Analysis) → 4 (Implementation) → 5A → 5B → 5C → [6 + 7 parallel]
+```
+
+**Lean mode (`--lean`):**
+```
+0 (Init) → 1 (Gather) → 2A → 2B → 2C → 2D → 3 (Analysis) → 4 (Implementation) → 6 (Code Connect)
+```
+
+In lean mode, Phase 5 (testing) and Phase 7 (wiki) are **SKIPPED**. Phase 6 runs sequentially (no parallel partner).
+
+This skill dispatches Phase 2 and Phase 5 sub-phases directly — no orchestrator subagent.
+
+When `phase-7` is invoked:
+1. Dispatch `phase-7a` (generate two wiki pages: main + iOS, plus assets into wiki submodule).
+2. On COMPLETE, Phase 7 is done. No VPN required.
+3. Wiki changes are committed and pushed by the designated commit skill along with all other submodule changes.
+
+> **Confluence upload** is a separate standalone skill: `/figma-to-swift-ui-confluence-sync`.
+> It reads the wiki markdown, converts to XHTML, and uploads to Confluence (VPN required).
+
+---
+
+## Dispatch Table
+
+All instruction files are relative to the ORIGINAL skill directory: `.instructions/figma/figma-to-swiftui/`
+
+> **PERF CHANGES vs original:**
+> - Phase 0: opus→sonnet, 30→15 turns (deterministic registry lookup + mkdir)
+> - Phase 6: opus→sonnet, 30→20 turns (template-based, phase6-finalize.py is safety net)
+
+| Phase | Instruction | Model | Max Turns | Tool Restrictions |
+|-------|-------------|-------|-----------|-------------------|
+| 0 | `phases/phase-0-init.md` | **sonnet** | **15** | No Edit |
+| 1 | `phases/phase-1-gathering.md` + `scripts/phase1-gather.py` | N/A (script) | N/A | Bash only |
+| 2A | `phases/phase-2a-testing-identifiers.md` | opus | 25 | No Edit |
+| 2B | `phases/phase-2b-localization.md` | sonnet | 25 | No Edit |
+| 2C | `phases/phase-2c-accessibility.md` | opus | 25 | No Edit |
+| 2D | `phases/phase-2d-analytics.md` | sonnet | 20 | No Edit, No Bash |
+| 3A | `phases/phase-3a-location.md` | sonnet | 20 | No Edit |
+| 3C | `phases/phase-3c-nested.md` | sonnet | 20 | No Edit |
+| 3H | `phases/phase-3h-variant-config.md` | opus | 25 | No Edit |
+| 3D | `phases/phase-3d-patterns.md` | opus | 30 | No Edit |
+| 4A | `phases/phase-4a-configuration.md` | opus | 30 | ALL allowed |
+| 4B | `phases/phase-4b-view.md` | opus | 40 | ALL allowed |
+| 4C | `phases/phase-4c-documentation.md` | sonnet | 20 | ALL allowed |
+| 4D | `phases/phase-4d-preview.md` | sonnet | 20 | ALL allowed |
+| 4E | `phases/phase-4e-modifiers.md` | sonnet | 20 | ALL allowed |
+| 5A | `phases/phase-5a-viewinspector.md` | sonnet | 40 | ALL allowed |
+| 5B | `phases/phase-5b-snapshot.md` | sonnet | 40 | ALL allowed |
+| 5C | `phases/phase-5c-unit.md` | sonnet | 30 | ALL allowed |
+| 6 | `phases/phase-6-code-connect.md` | **sonnet** | **20** | No Edit |
+| 7 | `phases/phase-7a-wiki-generate.md` | sonnet | 30 | No Edit |
+
+---
+
+## Reference Files
+
+Bundled in `.instructions/figma/figma-to-swiftui/reference/`. Include relevant paths in dispatch prompts so subagents can read them.
+
+| File | Used By Phases |
+|------|----------------|
+| `reference/tools.md` | 0, 1 |
+| `reference/code-connect.md` | 6 |
+| `reference/registry.md` | 0, 3 |
+| `reference/missing-tokens.md` | 3, 4 |
+| `reference/macros.md` | 4 |
+| `reference/figma-to-swiftui-effects.md` | 4 |
+| `reference/confluence-api.md` | standalone confluence skill |
+| `reference/confluence-xhtml.md` | standalone confluence skill |
+| `reference/wiki-to-confluence-mapping.md` | standalone confluence skill |
+| `reference/accessibility.md` | 2C |
+| `reference/localization-naming.md` | 2B |
+| `reference/testing-identifiers-naming.md` | 2A |
+| `reference/analytics-events.md` | 2D |
+| `reference/viewinspector.md` | 5A |
+| `reference/snapshot-testing.md` | 5D |
+
+---
+
+## Dispatch Procedure
+
+**CRITICAL: Do NOT read phase instruction files or reference docs in the main orchestrator context. Subagents read their own instructions by path. This prevents context bloat.**
+
+For each phase in order:
+
+### 1. Build the dispatch prompt (DO NOT read instruction files)
+
+```
+You are executing {Phase Name} of the Figma-to-SwiftUI workflow.
+
+## Context
+- Component: {componentName}
+- File Key: {fileKey}
+- Node ID: {nodeId}
+- Artifact Path: {artifactPath}
+- Component Location: {componentLocation}
+- GitHub Issue: {issueNumber} (omit if not available)
+- Wiki Path: {wikiPath} (Phase 7 only — `{repos.wiki.path}`)
+- Specs: {specsPath} (if `{artifactPath}/pass0/specs.md` exists — include in Phase 3, 4 dispatch prompts as additional implementation guidance)
+
+## Tool Restrictions
+{from dispatch table — e.g., "Do NOT use the Edit tool."}
+
+## Your Instructions
+Read and STRICTLY FOLLOW your phase instructions gate-by-gate from this file:
+  .instructions/figma/figma-to-swiftui/{instruction path from dispatch table}
+
+Execute every gate sequentially. Do not skip gates.
+
+Read the return protocol from:
+  .instructions/figma/figma-to-swiftui/reference/halt-return-protocol.md
+
+## Specs (if present)
+- {artifactPath}/pass0/specs.md
+Read and incorporate specs alongside phase instructions. Both are inputs you must follow — phase instructions define methodology and coding standards, specs define acceptance criteria and design intent. Neither overrides the other.
+
+## Reference Files (read during execution if needed)
+- .instructions/figma/figma-to-swiftui/{reference path}
+
+## Previous Phase Artifacts (read in this order)
+{use the Read-Order Table below — list file PATHS only, do not embed content}
+```
+
+### 2. Dispatch
+
+**Phase 1 (script):** Run directly via Bash — no subagent needed:
+
+```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. The script exits 0 on success, 1 on failure.
+The script tries remote MCP first, falls back to local MCP automatically.
+
+**If `status` = `COMPLETE_WITH_DEFERRED`:**
+Design context was deferred (too many sublayers). All other artifacts are present.
+Do NOT ask the user — dispatch a **Phase 1 subagent** for deferred resolution:
+
+```
+Agent(
+  subagent_type: "general-purpose",
+  model: opus,
+  max_turns: 25,
+  prompt: "You are executing Phase 1 Deferred Resolution...
+    Read instructions from: .instructions/figma/figma-to-swiftui/phases/phase-1-gathering.md (Section: Deferred Resolution)
+    Read halt-return from: .instructions/figma/figma-to-swiftui/reference/halt-return-protocol.md
+    Context: componentName={componentName}, fileKey={fileKey}, nodeId={nodeId}, artifactPath={artifactPath}
+    Previous artifacts: {artifactPath}/pass1/component_properties.json, {artifactPath}/pass1/design_context_deferred.json"
+)
+```
+
+The subagent handles smart selection (classifying axes, picking representatives) and calls `phase1-gather.py --fetch-deferred`. On COMPLETE → continue to Phase 2.
+
+**All other phases:** Dispatch via Agent tool:
+
+```
+Agent(
+  subagent_type: "general-purpose",
+  model: {from dispatch table},
+  max_turns: {from dispatch table},
+  prompt: {constructed prompt from step 1}
+)
+```
+
+### 3. Parse the return
+
+> **All counters are persisted to `{artifactPath}/_perf_tracker.json` — NOT held in memory.**
+> Read the tracker file before updating, write it back immediately after. This survives context loss.
+
+**Before dispatching each phase**, record the start time in the tracker:
+
+```python
+import json, datetime
+tracker_path = "{artifactPath}/_perf_tracker.json"
+with open(tracker_path) as f:
+    tracker = json.load(f)
+tracker["phases"]["phase_N"] = {"name": "Phase N (Name)", "start": datetime.datetime.now(datetime.timezone.utc).isoformat(), "status": "in-progress"}
+with open(tracker_path, "w") as f:
+    json.dump(tracker, f, indent=2)
+```
+
+**STATUS: COMPLETE**
+→ Record gates and artifacts
+→ **Update tracker file on disk**: set phase `end`, `duration_seconds`, `status: "COMPLETE"`
+→ **Append phase timing to IMPLEMENTATION_HISTORY.md** (incremental write — see step 4)
+→ Proceed to next phase
+
+**STATUS: HALT**
+→ **Update tracker file on disk**: increment `halt_count`, append to `halt_log`
+→ Show user: GATE, REASON, USER_ACTION_REQUIRED via AskUserQuestion
+→ Options: "Fix and retry", "Skip this phase", "Abort workflow"
+→ Retry: update tracker — increment `retry_count`, set `resolution: "retry"`, re-dispatch same phase
+→ Skip: update tracker — set `resolution: "skipped"`, `status: "SKIPPED"`, proceed
+→ Abort: update tracker — set `resolution: "aborted"`, `status: "ABORTED"`, stop workflow
+
+**STATUS: NEEDS_INPUT**
+→ Show user: QUESTION, OPTIONS, SUGGESTED via AskUserQuestion
+→ Re-dispatch same phase with user decision prepended:
+  ```
+  USER_DECISION:
+    GATE: {gate-id}
+    ANSWER: {user's choice}
+  ```
+
+### 4. Update history (incremental — after EVERY phase)
+
+**After each phase completes, IMMEDIATELY write two things:**
+
+**A) Update `_perf_tracker.json`** with phase end time, duration, and status (as shown above).
+
+**B) Append a `## Phase Timing` entry to IMPLEMENTATION_HISTORY.md:**
+
+If the `## Phase Timings` section does not yet exist in IMPLEMENTATION_HISTORY.md, create it:
+
+```markdown
+## Phase Timings
+
+| Phase | Duration | Status | Timestamp |
+|-------|----------|--------|-----------|
+| Phase 0 (Init) | 0:45 | ✅ | 2026-03-18T14:30:45Z |
+```
+
+If it already exists, append a new row to the table:
+
+```markdown
+| Phase 2 (Utilities) | 4:12 | ✅ | 2026-03-18T14:35:00Z |
+```
+
+Use `✅` for COMPLETE, `⏭️` for SKIPPED, `❌` for HALT/ABORTED.
+
+Also update IMPLEMENTATION_HISTORY.md with the standard phase status, gates, and artifacts (unchanged from before).
+
+> **WHY:** This ensures timing data is on disk after every phase. If the conversation is cut or context overflows, the final summary can reconstruct everything from `_perf_tracker.json` and the IMPLEMENTATION_HISTORY.md table.
+
+---
+
+## Phase 2 Routing (inline — do NOT read phase-2-orchestrator.md)
+
+**Do NOT read `phase-2-orchestrator.md`. All routing logic is here. Subagents read their own docs.**
+
+> **UNCHANGED from original** — Phase 2 routing preserved exactly.
+
+1. **PRE-CHECK**: Read `IMPLEMENTATION_HISTORY.md` (already in context). Verify `pass1/_index.md` exists.
+2. **NORMALIZE**: Check `pass1/design_context_response.json` — if `sublayers: true` and no `response` field, concatenate `responses` values into `response` field and write back.
+3. **REGISTRY_LOOKUP**: `cd {repos.common.path} && .build/debug/FigmaRegistryUtility utility-lookup --node-id '{nodeId}'` — pass result as `registryData` context to subagents.
+4. **Wave 1 (parallel)**: Dispatch 2A + 2B + 2C as subagents (each reads its own instruction doc by path).
+5. **Wave 2**: Dispatch 2D as subagent (depends on 2A output).
+6. **FINALIZE (script)**:
+   ```bash
+   python3 .instructions/figma/figma-to-swiftui/scripts/phase2-finalize.py \
+       --artifact-path '{artifactPath}' --node-id '{nodeId}' \
+       --file-key '{fileKey}' --component-name '{componentName}'
+   ```
+   Parse stdout JSON: `{"status":"ok","testing":N,"localization":N,"accessibility":N,"analytics":N,"registry":bool}`
+7. **UPDATE HISTORY**: Append Phase 2 summary using script output counts.
+
+---
+
+## Phase 3 Routing (inline — do NOT read phase-3-orchestrator.md)
+
+**Do NOT read `phase-3-orchestrator.md`. Subagents read their own docs. Scripts handle deterministic phases.**
+
+> **UNCHANGED from original** — Phase 3 routing preserved exactly.
+
+1. **PRE-CHECK**: Verify `pass2/_index.md` exists.
+2. **NORMALIZE**: Same sublayer check as Phase 2 (skip if already normalized).
+3. **Wave 1 (parallel)**: Launch ALL simultaneously:
+   - **Scripts**: `python3 .instructions/figma/figma-to-swiftui/scripts/phase3-scripts.py wave1 --artifact-path '{artifactPath}'` (runs 3B+3E+3F, ~5s)
+   - **Subagents**: 3A (`phase-3a-location.md`, sonnet, 20 turns), 3C (`phase-3c-nested.md`, sonnet, 20 turns), 3H (`phase-3h-variant-config.md`, opus, 25 turns)
+4. **MISSING TOKEN RESOLUTION**: After Wave 1, check `pass3/02_token_mapping.md` for missing tokens (lines with "⚠️ not found"). If any exist, dispatch a subagent:
+   - **Subagent** (`general-purpose`, opus, 25 turns) — reads `reference/missing-tokens.md` for procedure, resolves each missing token by:
+     - **Typography**: Adding alias entries to `typography-registry.json` (match font size + weight to existing Swift tokens)
+     - **Colors**: Adding to `Shared/UIAssets/Colors/*.json` (source), running `swift package plugin --allow-writing-to-package-directory generate-ui-assets`, adding to `ui-token-index.json`
+     - **Variables**: Using `FigmaRegistryUtility ui-token-lookup` / `ui-token-index` to verify
+   - Pass artifact path and token mapping path as context. Subagent updates token mapping after resolution.
+   - If 0 missing tokens, skip this step entirely.
+5. **Wave 2 (parallel)**: Launch simultaneously:
+   - **Subagent**: 3D (`phase-3d-patterns.md`, opus, 30 turns) — reads 3H output (`pass3/04c_variant_config_analysis.json`)
+6. **Wave 3**: `python3 .instructions/figma/figma-to-swiftui/scripts/phase3-scripts.py 3g --artifact-path '{artifactPath}'` (depends on 3D JSON output)
+7. **COLLECT**: Verify 12 artifacts exist in `pass3/` (10 original + 2 from 3H).
+8. **SPEC (script)**: `python3 .instructions/figma/figma-to-swiftui/scripts/phase3-scripts.py spec --artifact-path '{artifactPath}'`
+9. **WRITE INDEX**: Write `pass3/_index.md` (list the 12 files + spec).
+10. **UPDATE HISTORY**: Append Phase 3 summary.
+
+---
+
+## Phase 4 Routing (inline — do NOT read phase-4-orchestrator.md)
+
+**Do NOT read `phase-4-orchestrator.md`. Subagents read their own docs. Orchestrator stays lean.**
+
+1. **PRE-CHECK**: Verify `pass3/_index.md` exists.
+2. **LOAD_SPEC**: Read `pass3/07_implementation_spec.md` and `pass3/05_complexity.md` — extract `componentLocation`, `complexity` (SIMPLE/COMPLEX).
+3. **PREPARE_DIRECTORY**: `mkdir -p {componentLocation}`. Get `gitUser` via `git config user.name`. Get `date` in DD.MM.YYYY format.
+4. **Wave 1 (parallel)**: Dispatch subagents:
+   - **4A** (`phase-4a-configuration.md`, opus, 30 turns) — **COMPLEX only** (skip if SIMPLE). Writes `{ComponentName}Configuration.swift`.
+   - **4B** (`phase-4b-view.md`, opus, 40 turns) — **ALWAYS**. Writes `{ComponentName}.swift`.
+   - **4C** (`phase-4c-documentation.md`, sonnet, 20 turns) — **ALWAYS**. Writes `FIGMA.md`.
+   - Pass to each: componentName, componentLocation, artifactPath, nodeId, fileKey, complexity, gitUser, date, issueNumber (from IMPLEMENTATION_HISTORY.md `GitHub Issue` field — extract the number after `#`).
+5. **Wave 2 (parallel)**: Dispatch subagents that depend on 4A+4B:
+   - **4D** (`phase-4d-preview.md`, sonnet, 20 turns) — appends Preview to `{ComponentName}.swift`.
+   - **4E** (`phase-4e-modifiers.md`, sonnet, 20 turns) — **COMPLEX only** (skip if SIMPLE). Writes `{ComponentName}+Modifiers.swift`.
+6. **COLLECT**: Verify `{ComponentName}.swift`, `{ComponentName}Configuration.swift` (if COMPLEX), `{ComponentName}+Modifiers.swift` (if COMPLEX), `FIGMA.md` exist.
+7. **VALIDATE**: `bash .instructions/figma/figma-to-swiftui/scripts/validate-phase4.sh "{componentLocation}" "{ComponentName}" "{artifactPath}/pass3/00_property_coverage.json"` — fix violations if any.
+8. **BUILD**: `xcodebuild build -project "$(git rev-parse --show-toplevel)/{build.xcodeproj}" -scheme {build.scheme} -destination 'generic/platform=iOS' CODE_SIGNING_ALLOWED=NO -quiet` — fix compilation errors if any.
+9. **REGISTRY FINALIZE**: After build passes, mark `status.ios.implemented` green in the component registry with a content-hashed version bump:
+   ```bash
+   python3 .instructions/figma/figma-to-swiftui/scripts/phase4-finalize.py \
+       --node-id "{nodeId}" \
+       --component-name "{ComponentName}" \
+       --source-file "{componentLocation}/{ComponentName}.swift" \
+       --platform ios
+   ```
+   Parse stdout JSON. On success (`"status": "ok"`), the registry entry now has `implemented.value: true`, `implemented.version: 1` (or bumped), and a content hash. On failure, log the error but do NOT halt — the finalize can be re-run manually or via `/figma-iteration-commit`.
+10. **UPDATE HISTORY**: Append Phase 4 summary.
+
+---
+
+## Phase 5 Routing (inline — do NOT read phase-5-orchestrator.md)
+
+> **LEAN MODE: If `lean_mode` is `true` in `_perf_tracker.json`, SKIP this entire section.**
+> Record Phase 5 as `"status": "SKIPPED"` in the tracker and append `| Phase 5 (Testing) | — | ⏭️ lean | ... |` to IMPLEMENTATION_HISTORY.md.
+> Proceed directly to Phase 6 (sequentially, not parallel with Phase 7).
+
+**Do NOT read `phase-5-orchestrator.md`. Subagents read their own docs.**
+
+> **PERF CHANGE: Combined test execution** — runs ViewInspector + Snapshot tests in a single xcodebuild invocation instead of two separate build+test cycles.
+> **PERF CHANGE: Simulator pre-warm** — boots simulator in background during test file generation to eliminate cold-start latency.
+
+1. **PRE-CHECK**: Verify Phase 4 complete (component Swift file exists at `{componentLocation}`).
+2. **SIMULATOR PRE-WARM** (parallel with Wave 1): Boot the simulator in the background before test files are written:
+   ```bash
+   xcrun simctl boot "iPhone 17 Pro" 2>/dev/null &
+   ```
+   This runs asynchronously — no need to wait. By the time test execution starts (step 4b), the simulator is ready.
+3. **Wave 1 (parallel)**: Dispatch subagents:
+   - **5A** (`phase-5a-viewinspector.md`, sonnet, 40 turns) — ViewInspector structure + accessibility tests.
+   - **5B** (`phase-5b-snapshot.md`, sonnet, 40 turns) — Snapshot tests for all Figma variants.
+4. **Wave 2 (conditional)**: **5C** (`phase-5c-unit.md`, sonnet, 30 turns) — Unit tests. Only if component has ViewModel/model logic. N/A for pure View + Configuration.
+5. **TEST EXECUTION (combined)**: Run all tests via a SINGLE xcodebuild invocation:
+   a. **Switch to local common dependency**: In `{repos.components.path}/Package.swift`, comment out the `.package(url: "...{project.slug}-common...", ...)` line and add `.package(path: "../{project.slug}-common"),` below it. This is needed because the SPM package resolves dependencies from remote git, but Phase 2 adds identifiers/keys to the local editable copy.
+   b. **Run ALL tests in a single invocation**:
+      ```bash
+      REPO_ROOT=$(git rev-parse --show-toplevel)
+      UICOMP_PKG="${REPO_ROOT}/{repos.components.path}"
+      cd "${UICOMP_PKG}" && xcodebuild test \
+        -scheme UIComponents-Package \
+        -destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
+        -only-testing:UIComponentsTests/{ComponentName}ViewInspectorTests \
+        -only-testing:UIComponentsTests/{ComponentName}SnapshotTests \
+        CODE_SIGNING_ALLOWED=NO \
+        2>&1 | tail -50
+      ```
+      This eliminates the second build+resolve cycle. Both test suites share the same build artifacts.
+      If 5C unit tests also exist, add another `-only-testing:UIComponentsTests/{ComponentName}UnitTests` to the same command.
+      All tests must pass with zero warnings on component test files. Fix deprecated `Inspectable` conformance or other warnings before proceeding.
+   c. **Revert to remote dependency**: Uncomment the original `.package(url: ...)` line and remove the `.package(path: ...)` line in `Package.swift`.
+6. **UPDATE HISTORY**: Append Phase 5 summary with test counts.
+
+---
+
+## Phase 6 + 7 Parallel Execution
+
+> **LEAN MODE:** If `lean_mode` is `true` in `_perf_tracker.json`:
+> - Run **Phase 6 only** (sequentially, after Phase 4).
+> - **SKIP Phase 7 entirely.** Record as `"status": "SKIPPED"` in the tracker and append `| Phase 7 (Wiki) | — | ⏭️ lean | ... |` to IMPLEMENTATION_HISTORY.md.
+> - Do NOT touch the wiki submodule.
+
+> **PERF CHANGE:** Phase 6 (Code Connect) and Phase 7 (Wiki Markdown generation) have NO dependency on each other. Phase 7 reads component Swift files + FIGMA.md + pass3 artifacts — all completed in Phase 4. Phase 6 publishes to Figma. Running them in parallel saves ~5-10 minutes.
+
+After Phase 5 completes (or Phase 4 in lean mode):
+
+1. **Dispatch Phase 6 + Phase 7 simultaneously as parallel subagents:**
+
+   **Phase 6 subagent:**
+   ```
+   Agent(
+     subagent_type: "general-purpose",
+     model: sonnet,
+     max_turns: 20,
+     prompt: {standard Phase 6 dispatch prompt}
+   )
+   ```
+
+   **Phase 7 subagent:**
+   ```
+   Agent(
+     subagent_type: "general-purpose",
+     model: sonnet,
+     max_turns: 30,
+     prompt: {standard Phase 7 dispatch prompt — include wikiPath in context}
+   )
+   ```
+
+2. **Wait for both to complete.** Parse both returns.
+
+3. **Phase 6 finalization** (after its subagent returns COMPLETE):
+   ```bash
+   python3 .instructions/figma/figma-to-swiftui/scripts/phase6-finalize.py \
+       --node-id '{nodeId}' \
+       --file-key '{fileKey}' \
+       --component-name '{componentName}' \
+       --platform ios
+   ```
+
+4. **Phase 7 complete:** Wiki markdown + assets written to wiki submodule. Wiki changes are committed and pushed by the designated commit skill along with all other submodule changes.
+
+> Confluence upload (XHTML generation + upload to {confluence.host}) is a separate standalone skill: `/figma-to-swift-ui-confluence-sync`. Run it independently after the main workflow completes (requires VPN).
+
+---
+
+## Read-Order Table
+
+When building the `Previous Phase Artifacts` section of the dispatch prompt, list artifacts in this order. Compact artifacts go FIRST so the subagent establishes context before large files consume the context window.
+
+Every phase must be independently operable from a clean session — all artifacts remain accessible on disk. This table is a **read-ordering preference**, not a prohibition.
+
+| Phase | Read FIRST (compact) | Read SECOND (if detail needed) |
+|-------|---------------------|-------------------------------|
+| 2A-2D | `pass1/component_summary.json` | `pass1/design_context_response.json`, `pass1/component_properties.json` |
+| 3A | `pass1/component_summary.json`, `IMPLEMENTATION_HISTORY.md` | — |
+| 3B | `pass1/component_summary.json`, `pass1/variable_defs_response.json` | `pass1/design_context_response.json` (for binding context) |
+| 3C | `pass1/component_summary.json`, `pass1/code_connect_map_response.json` | — |
+| 3D | `pass1/component_summary.json`, `pass1/component_properties.json` | `pass1/design_context_response.json`, `pass1/metadata_response.xml` |
+| 3E | `pass1/component_summary.json`, `pass1/design_context_assets.txt` | — |
+| 3F | `pass1/component_summary.json`, `pass2/utility_*.md` | `pass1/design_context_response.json` |
+| 3G | `pass1/component_summary.json`, `pass3/04b_component_architecture.md` | — |
+| 4A | `pass3/04b_component_architecture.md`, `pass3/05_complexity.md`, `pass3/00_property_coverage.json` | `pass1/component_summary.json` |
+| 4B | `pass1/component_summary.json`, `pass3/00_property_coverage.json`, `pass3/07_implementation_spec.md`, `pass3/02_token_mapping.md`, `pass3/04b_component_architecture.md`, `pass3/04_patterns.md`, `pass3/03_nested_components.md`, `pass3/08_utility_integration.md`, `pass1/screenshot.png` | `pass1/design_context_response.json` (for complex layout detail) |
+| 4C | `pass3/07_implementation_spec.md`, `pass3/04b_component_architecture.md`, `pass3/00_property_coverage.json` | `pass1/component_summary.json` |
+| 4D | `{componentLocation}/{ComponentName}.swift`, `{componentLocation}/{ComponentName}Configuration.swift` (if exists) | `pass3/04_patterns.md` |
+| 4E | `{componentLocation}/{ComponentName}Configuration.swift`, `{componentLocation}/{ComponentName}.swift` | — |
+| 6 | `pass1/component_properties.json`, `{sourceLocation}/FIGMA.md`, `{sourceLocation}/{componentName}.swift` | — |
+
+---
+
+## Resume Mode
+
+When `$ARGUMENTS` is `phase-N`:
+
+1. Find IMPLEMENTATION_HISTORY.md by searching `{repos.packagesContainer}/{repos.artifactsRepo}/ImplementationArtifacts/Figma/Components/`
+2. Read it to get: componentName, fileKey, nodeId, artifactPath, componentLocation. Derive confluencePath: replace `Figma/Components` with `Confluence` in artifactPath.
+3. Verify prerequisite phase artifacts exist
+4. Dispatch the requested phase
+
+If prerequisites are missing, HALT and inform user.
+
+---
+
+## Status Mode
+
+When `$ARGUMENTS` is `status`:
+
+1. Search for all IMPLEMENTATION_HISTORY.md files in `{repos.packagesContainer}/{repos.artifactsRepo}/ImplementationArtifacts/`
+2. For each found IMPLEMENTATION_HISTORY.md, look for a sibling `_perf_tracker.json` in the same directory.
+3. If `_perf_tracker.json` exists:
+   a. Read it and display the full timing/reliability summary (same format as Final Summary).
+   b. If IMPLEMENTATION_HISTORY.md is missing the `## Workflow Summary` section but the tracker shows all phases completed, **generate and append the summary now** — this recovers from context loss.
+4. If `_perf_tracker.json` does not exist, fall back to displaying: component name, current phase, last gate, last updated (from IMPLEMENTATION_HISTORY.md only).
+
+---
+
+## Artifact Path Resolution
+
+Use FigmaRegistryUtility to resolve component paths:
+
+```bash
+CONFIG_PATH="{repos.common.path}"
+cd "$CONFIG_PATH" && .build/debug/FigmaRegistryUtility lookup --node-id '{nodeId}'
+```
+
+Returns:
+- `suggestedComponentName` → componentName
+- `suggestedComponentLocation` → componentLocation (under UIComponents/Sources/)
+- `suggestedArtifactPath` → artifactPath: `ImplementationArtifacts/Figma/Components/{Category}/{ComponentName}/`
+
+Derive confluencePath from artifactPath: replace `Figma/Components` with `Confluence` in the artifact path string.
+
+---
+
+## Final Summary
+
+When the last phase completes (or workflow is aborted/skipped):
+
+1. **Read `{artifactPath}/_perf_tracker.json`** — this is the single source of truth for all timing and reliability data.
+2. **Read IMPLEMENTATION_HISTORY.md** `## Phase Timings` table — as a cross-check.
+3. **Compute totals** from the tracker file (not from memory).
+4. **Output the summary** to the user AND **append it to IMPLEMENTATION_HISTORY.md**.
+
+> If the orchestrator context was lost (conversation cut, token overflow) and the workflow is resumed,
+> the tracker file still has all data. The final summary can be generated from any conversation context
+> by reading `_perf_tracker.json`.
+
+### Summary Format
+
+```
+## Workflow Summary
+
+- Component: {componentName}
+- Lean Mode: {yes/no — from tracker `lean_mode` field}
+- Phases Executed: {list of completed phases — from tracker}
+- Phases Skipped: {list, if any — from tracker. In lean mode: Phase 5, Phase 7}
+- Total Elapsed Time: {HH:MM:SS} (from tracker workflow_start to last phase end)
+- Artifacts: {artifactPath}
+- Component Location: {componentLocation}
+
+### Phase Timings
+| Phase | Duration | Status |
+|-------|----------|--------|
+| Phase 0 (Init) | {elapsed} | ✅ |
+| Phase 1 (Gather) | {elapsed} | ✅ |
+| Phase 2 (Utilities) | {elapsed} | ✅ |
+| Phase 3 (Analysis) | {elapsed} | ✅ |
+| Phase 4 (Implementation) | {elapsed} | ✅ |
+| Phase 5 (Testing) | {elapsed} | ✅ |
+| Phase 6 (Code Connect) | {elapsed} | ✅ |
+| Phase 7 (Wiki Markdown) | {elapsed} | ✅ |
+| **Total** | **{total elapsed}** | |
+
+### Reliability
+- First-pass success: {phases_without_halt}/{total_phases} phases ({percentage}%)
+- HALTs: {halt_count from tracker} — {halt_log entries}
+- Retries: {retry_count from tracker}
+
+### Bottlenecks
+⚠️ Phase {N} took {actual} (expected ~{expected}) — {reason if known from halt_log, else "investigate"}
+{If no bottlenecks: "None — all phases within expected duration."}
+```
+
+**Expected Phase Durations** (used for bottleneck detection):
+
+| Phase | Expected (COMPLEX) | Expected (SIMPLE) |
+|-------|-------------------|-------------------|
+| Phase 0 | 1:00 | 1:00 |
+| Phase 1 | 0:30 | 0:30 |
+| Phase 2 | 5:30 | 4:00 |
+| Phase 3 | 9:00 | 6:00 |
+| Phase 4 | 13:00 | 7:00 |
+| Phase 5 | 12:00 | 8:00 |
+| Phase 6+7 | 3:00 | 3:00 |
+
+A phase is flagged as bottleneck when `actual_duration > 2 × expected_duration`.
+
+### Generating Summary After Context Loss
+
+If the workflow completed but the summary was never written (e.g., token budget exceeded),
+it can be reconstructed at any time by running:
+
+```
+/performance-swiftui status
+```
+
+The `status` command reads `_perf_tracker.json`, computes the summary, and appends the
+`## Workflow Summary` section to IMPLEMENTATION_HISTORY.md if it doesn't already exist.
+
+---
+
+## Performance Optimizations Applied (vs figma-to-swiftui)
+
+| Optimization | Description |
+|---|---|
+| **Phase 0 model downgrade** | opus→sonnet (deterministic registry lookup + mkdir) |
+| **Phase 6 model downgrade** | opus→sonnet (template-based, finalize script is safety net) |
+| **Combined test execution** | Single `xcodebuild test` with multiple `--only-testing:` instead of 2 separate build+test cycles |
+| **Simulator pre-warm** | Boots iOS Simulator in background during test file generation, eliminating cold-start latency |
+| **Phase 6 ∥ 7 parallelism** | Code Connect publish + Wiki Markdown generation run simultaneously |
+| **Phase 4 registry finalize** | Calls `phase4-finalize.py` after BUILD to mark `implemented: true` — was missing in original routing, caused gray implementation flags on issue board |
+| **Disk-persisted tracking** | All timing, HALT, and retry data written to `_perf_tracker.json` after every phase — survives context loss |
+| **Incremental history writes** | Phase timing rows appended to IMPLEMENTATION_HISTORY.md after each phase — no data lost if conversation cuts |
+| **Bottleneck detection** | Flags phases exceeding 2× expected duration — reconstructable from `_perf_tracker.json` at any time |