@mmerterden/multi-agent-pipeline 11.2.0 → 11.3.0

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

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