@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/figma-ios/figma-to-component/phases/phase-4-orchestrator.md

@@ -0,0 +1,412 @@
+# PHASE 4 — Implementation Orchestrator
+
+Orchestrates Phase 4 sub-phases: dispatches sub-agents to write Swift code, collects results.
+PREV: Phase 3 (Data Analysis)
+NEXT: Phase 5 (Testing)
+
+**Date Format:** Use `DD.MM.YYYY` format (e.g., `23.02.2026`) for file headers.
+
+---
+
+## PURPOSE
+
+Phase 4 transforms Phase 3 analysis into Swift code.
+Each sub-phase writes one file. Phase 5 (testing) consumes these files.
+
+---
+
+## PRE-CHECK: Phase 3 Complete
+
+```
+Read: {artifactPath}/IMPLEMENTATION_HISTORY.md
+Read: {artifactPath}/pass3/_index.md
+```
+
+EXTRACT:
+- `componentName`
+- `artifactPath`
+- `nodeId`
+- `fileKey`
+
+| Result | Action |
+|--------|--------|
+| Both files exist | Proceed to LOAD_SPEC |
+| Either missing | HALT |
+
+FAIL →
+```
+STATUS: HALT
+PHASE: phase-4
+GATE: PRE_CHECK
+REASON: IMPLEMENTATION_HISTORY.md or pass3/_index.md not found. Phase 3 must complete first.
+COMPLETED_GATES: []
+ARTIFACTS_CREATED: none
+USER_ACTION_REQUIRED: Run Phase 3 first.
+```
+
+---
+
+## LOAD_SPEC: Read Implementation Spec
+
+```
+Read: {artifactPath}/pass3/07_implementation_spec.md
+Read: {artifactPath}/pass3/05_complexity.md
+```
+
+EXTRACT:
+- `componentLocation` — Swift package path for the component
+- `complexity` — SIMPLE or COMPLEX
+- `filesToCreate` — list of files from the spec
+
+---
+
+## GATE 1: PREPARE_DIRECTORY
+
+### 1.1 Create directory
+
+```bash
+mkdir -p {componentLocation}
+```
+
+If directory already exists:
+
+First check if prompt contains `USER_DECISION` with gate matching `PREPARE_DIRECTORY`:
+→ If found: use the provided answer, continue execution.
+
+Otherwise:
+
+```
+STATUS: NEEDS_INPUT
+PHASE: phase-4
+GATE: PREPARE_DIRECTORY
+QUESTION: Component directory already exists. How should we proceed?
+OPTIONS:
+  1) Override (delete existing files and recreate)
+  2) Merge (update existing files, keep others)
+  3) Choose different location
+SUGGESTED: Option 2 — merge with existing.
+COMPLETED_GATES: [PRE_CHECK, LOAD_SPEC]
+CONTEXT:
+  Path: {componentLocation}
+  Contents: {list files in directory}
+```
+
+### 1.2 Get git user
+
+```bash
+git config user.name
+```
+
+Store as `gitUser` for file headers.
+
+---
+
+## ROUTING
+
+### Sub-phase inventory
+
+| Sub-phase | Skill Doc | Purpose | Required | Writes |
+|-----------|-----------|---------|----------|--------|
+| 4A | `phase-4a-configuration.md` | Configuration struct + enums | **COMPLEX only** | `{ComponentName}Configuration.swift` |
+| 4B | `phase-4b-view.md` | View struct (no preview) | **ALWAYS** | `{ComponentName}.swift` |
+| 4C | `phase-4c-documentation.md` | FIGMA.md | **ALWAYS** | `FIGMA.md` |
+| 4D | `phase-4d-preview.md` | Preview struct + #Preview | **ALWAYS** | Appends to `{ComponentName}.swift` |
+
+### Execution flow
+
+```
+PRE-CHECK + LOAD_SPEC + GATE 1
+    ↓
+┌──────────────────────────────────────────┐
+│  WAVE 1: PARALLEL DISPATCH (sub-agents)  │
+│                                          │
+│   4A — Configuration    ← if COMPLEX     │
+│   4B — View             ← ALWAYS         │
+│   4C — FIGMA.md         ← ALWAYS         │
+│                                          │
+└──────────────────────────────────────────┘
+    ↓ wait for all to complete
+    ↓
+┌──────────────────────────────────────────┐
+│  WAVE 2: SEQUENTIAL                     │
+│                                          │
+│   4D — Preview          ← ALWAYS         │
+│   (depends on 4A + 4B)                   │
+│                                          │
+└──────────────────────────────────────────┘
+    ↓
+GATE 2: COLLECT_RESULTS
+    ↓
+GATE 2.5: VALIDATE (run validation script)
+    ↓
+GATE 3: BUILD_VERIFICATION (xcodebuild)
+    ↓
+GATE 4: UPDATE_REGISTRY (phase4-finalize.py)
+    ↓
+GATE 5: UPDATE_IMPLEMENTATION_HISTORY
+    ↓
+PHASE OUTPUT
+```
+
+### Dispatch instructions
+
+**Wave 1 (parallel):** Launch 4A (if COMPLEX), 4B, 4C as sub-agents simultaneously.
+- Each reads from `pass3/` artifacts independently.
+- Each writes to `{componentLocation}/`.
+- 4A and 4B both read `pass3/04b_component_architecture.md` for the API design.
+- 4B and 4C both read `pass3/00_property_coverage.json` for property mandate verification.
+- Wait for ALL to complete before Wave 2.
+
+**Wave 2 (sequential):** Launch 4D after Wave 1 completes.
+- 4D appends `{ComponentName}Preview` struct and `#Preview` to `{ComponentName}.swift`.
+- 4D needs both Configuration (to instantiate) and View (to reference).
+
+### Skip conditions
+
+| Sub-phase | Skip when |
+|-----------|-----------|
+| 4A | Complexity = SIMPLE (≤3 properties) |
+
+If 4A is skipped, enums are defined inside the View file (4B handles this for SIMPLE components).
+
+### Dispatch context
+
+Pass these values to each sub-phase in the dispatch prompt:
+- `componentName`
+- `componentLocation`
+- `artifactPath`
+- `nodeId`
+- `fileKey`
+- `complexity` (SIMPLE/COMPLEX)
+- `gitUser`
+- `date` (current date in DD.MM.YYYY format)
+
+---
+
+## GATE 2: COLLECT_RESULTS
+
+After all sub-phases complete, verify each produced its file:
+
+```
+[ ] {componentLocation}/{ComponentName}.swift exists (Phase 4B)
+[ ] {componentLocation}/{ComponentName}Configuration.swift exists (Phase 4A — or SIMPLE skip)
+[ ] {componentLocation}/FIGMA.md exists (Phase 4C)
+```
+
+ANY missing →
+```
+STATUS: HALT
+PHASE: phase-4
+GATE: COLLECT_RESULTS
+REASON: Sub-phase file missing.
+MISSING: [list missing files]
+USER_ACTION_REQUIRED: Re-run the failed sub-phase.
+```
+
+---
+
+## GATE 2.5: VALIDATE
+
+Run the Phase 4 validation script against the generated files:
+
+```bash
+bash .instructions/figma/figma-to-swiftui/scripts/validate-phase4.sh \
+    "{componentLocation}" \
+    "{ComponentName}" \
+    "{artifactPath}/pass3/00_property_coverage.json"
+```
+
+| Result | Action |
+|--------|--------|
+| Exit 0 (PASS) | Proceed to GATE 3 |
+| Exit 1 (FAIL) | Review violations, fix, re-validate |
+
+If validation fails:
+
+```
+STATUS: HALT
+PHASE: phase-4
+GATE: VALIDATE
+REASON: Post-implementation validation failed.
+VIOLATIONS: {list from script output}
+COMPLETED_GATES: [PRE_CHECK, LOAD_SPEC, PREPARE_DIRECTORY, DISPATCH_WAVE_1, DISPATCH_WAVE_2, COLLECT_RESULTS]
+ARTIFACTS_CREATED:
+  - {componentLocation}/{ComponentName}.swift
+  - {componentLocation}/{ComponentName}Configuration.swift (if COMPLEX)
+  - {componentLocation}/FIGMA.md
+USER_ACTION_REQUIRED: Fix the violations listed above and re-run validation.
+```
+
+**Common violations and fixes:**
+- Top-level enum → Move inside View or Configuration struct
+- Hardcoded accessibility string → Use `LocalizedAccessibilityStringKey`
+- Magic number in body → Move to Constants enum or use token
+- Constants at file scope → Move inside View struct
+- IMPLEMENT property missing → Add to init or mark SKIP with reason
+- Preview struct missing → Run Phase 4D
+- RTL preview missing → Run Phase 4D (dual preview pattern)
+
+---
+
+## GATE 3: BUILD_VERIFICATION
+
+Run a full Xcode build to verify the generated code compiles without errors.
+
+### Resolve repo root
+
+```bash
+REPO_ROOT=$(git rev-parse --show-toplevel)
+```
+
+This ensures the build command works on any developer's machine regardless of where the repo is cloned.
+
+### Build command
+
+```bash
+xcodebuild build \
+    -project "${REPO_ROOT}/{build.xcodeproj}" \
+    -scheme {build.scheme} \
+    -destination 'generic/platform=iOS' \
+    CODE_SIGNING_ALLOWED=NO \
+    -quiet
+```
+
+**Why this command is portable:**
+- `git rev-parse --show-toplevel` — resolves absolute repo path on any machine, no hardcoded user paths
+- `generic/platform=iOS` — no simulator name, ID, or OS version needed. Works regardless of installed simulators
+- `CODE_SIGNING_ALLOWED=NO` — bypasses development team / provisioning profile requirements. We only need compilation verification, not a runnable binary
+- `-quiet` — suppresses build log noise, only shows errors and warnings
+
+| Result | Action |
+|--------|--------|
+| Exit 0 (PASS) | Proceed to GATE 4 |
+| Exit 1 (FAIL) | Read error output, fix compilation errors, rebuild |
+
+If build fails:
+
+```
+STATUS: HALT
+PHASE: phase-4
+GATE: BUILD_VERIFICATION
+REASON: Xcode build failed.
+BUILD_ERRORS: {error output from xcodebuild}
+COMPLETED_GATES: [PRE_CHECK, LOAD_SPEC, PREPARE_DIRECTORY, DISPATCH_WAVE_1, DISPATCH_WAVE_2, COLLECT_RESULTS, VALIDATE]
+ARTIFACTS_CREATED:
+  - {componentLocation}/{ComponentName}.swift
+  - {componentLocation}/{ComponentName}Configuration.swift (if COMPLEX)
+  - {componentLocation}/FIGMA.md
+USER_ACTION_REQUIRED: Fix the compilation errors and re-run build.
+```
+
+**Common build errors and fixes:**
+- Missing import → Add required `import` statement (UIAssetTokens, UIComponentUtilities, etc.)
+- Type mismatch → Check pass3/04b_component_architecture.md for correct types
+- Unknown token → Verify token exists in pass3/02_token_mapping.md
+- Macro expansion error → Check @GenerateConfiguredInit usage matches reference/macros.md
+- Preview init error → Ensure Preview struct has no macros (see phase-4d-preview.md WHY section)
+
+---
+
+## GATE 4: UPDATE_REGISTRY
+
+Run the Phase 4 finalize script to mark `implemented` in the component registry:
+
+```bash
+python3 .instructions/figma/figma-to-swiftui/scripts/phase4-finalize.py \
+    --node-id "{nodeId}" \
+    --component-name "{ComponentName}" \
+    --source-file "{componentLocation}/{ComponentName}.swift" \
+    --platform ios
+```
+
+| Result | Action |
+|--------|--------|
+| Exit 0, `"action": "updated"` | Registry updated — proceed |
+| Exit 0, `"action": "version_bumped"` | Content hash changed, version bumped (other flags auto-yellow) — proceed |
+| Exit 0, `"action": "already_current"` | Byte-identical re-run, no-op — proceed |
+| Exit 0, `"action": "created"` | New registry file created — proceed |
+| Exit 1 | HALT — registry update failed |
+
+**Why this matters:** This is the single source of truth for `status.ios.implemented`. The content hash prevents spurious version bumps on byte-identical re-runs; when content changes, `implemented.version` bumps and any downstream flags (`tested`, `codeConnect`, `wiki`) whose `against` is lower drop to yellow automatically. The subsequent `figma-iteration-commit` step will read this and sync the GitHub issue via `update-issue-from-registry.py`.
+
+FAIL →
+```
+STATUS: HALT
+PHASE: phase-4
+GATE: UPDATE_REGISTRY
+REASON: phase4-finalize.py failed.
+COMPLETED_GATES: [PRE_CHECK, LOAD_SPEC, PREPARE_DIRECTORY, DISPATCH_WAVE_1, DISPATCH_WAVE_2, COLLECT_RESULTS, VALIDATE, BUILD_VERIFICATION]
+ARTIFACTS_CREATED:
+  - {componentLocation}/{ComponentName}.swift
+USER_ACTION_REQUIRED: Check script error output; verify node-id and component name match the registry.
+```
+
+---
+
+## GATE 5: UPDATE_IMPLEMENTATION_HISTORY
+
+Append to `{artifactPath}/IMPLEMENTATION_HISTORY.md`:
+
+```markdown
+## Phase 4: Implementation
+
+Files Created:
+- {componentLocation}/{ComponentName}.swift
+- {componentLocation}/{ComponentName}Configuration.swift (if COMPLEX)
+- {componentLocation}/FIGMA.md
+
+Implementation:
+- Complexity: {SIMPLE/COMPLEX}
+- Tokens: {COUNT} applied
+- Constants: {COUNT} defined
+- Nested Components: {COUNT} integrated
+- Utilities: Testing IDs: {COUNT}, Localization: {COUNT}, Accessibility: {COUNT}, Analytics: {COUNT}
+- Previews: LTR + RTL (Arabic)
+- Xcode Build: ✅ PASS
+```
+
+---
+
+## VALIDATION CHECKLIST
+
+```
+[ ] Phase 3 artifacts loaded (pass3/_index.md, 07_implementation_spec.md)
+[ ] Component directory created (or merged with existing)
+[ ] Git user name retrieved
+[ ] 4A dispatched and completed (if COMPLEX) — Configuration.swift exists
+[ ] 4B dispatched and completed — View.swift exists
+[ ] 4C dispatched and completed — FIGMA.md exists
+[ ] 4D dispatched and completed — LTR + RTL Previews appended to View.swift
+[ ] validate-phase4.sh passed (no violations)
+[ ] xcodebuild passed (exit 0, no compilation errors)
+[ ] phase4-finalize.py passed (status.ios.implemented updated)
+[ ] IMPLEMENTATION_HISTORY.md updated with Phase 4 summary
+```
+
+---
+
+## SUCCESS OUTPUT
+
+```
+STATUS: COMPLETE
+PHASE: phase-4
+GATES_PASSED: [PRE_CHECK, LOAD_SPEC, PREPARE_DIRECTORY, DISPATCH_WAVE_1, DISPATCH_WAVE_2, COLLECT_RESULTS, VALIDATE, BUILD_VERIFICATION, UPDATE_REGISTRY, UPDATE_IMPLEMENTATION_HISTORY]
+ARTIFACTS_CREATED:
+  - {componentLocation}/{ComponentName}.swift (via Phase 4B + 4D)
+  - {componentLocation}/{ComponentName}Configuration.swift (via Phase 4A, if COMPLEX)
+  - {componentLocation}/FIGMA.md (via Phase 4C)
+SUMMARY: Implementation complete. {FILE_COUNT} files created at {componentLocation}. Complexity: {SIMPLE/COMPLEX}. Xcode build verified. Ready for Phase 5 testing.
+```
+
+---
+
+## REFERENCES
+
+| Topic | File |
+|-------|------|
+| Phase 4A | `phases/phase-4a-configuration.md` |
+| Phase 4B | `phases/phase-4b-view.md` |
+| Phase 4C | `phases/phase-4c-documentation.md` |
+| Phase 4D | `phases/phase-4d-preview.md` |
+| Macros Reference | `reference/macros.md` |
+| Phase 3 Analysis | `pass3/07_implementation_spec.md` |