@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/figma-ios/figma-to-component/phases/phase-2d-analytics.md

@@ -0,0 +1,352 @@
+# PHASE 2D — Analytics Events
+
+Analytics event integration using `UIComponentUtilities` view modifiers.
+REF: `reference/analytics-events.md`
+
+Execute if interactive elements exist in the component.
+DEPENDS ON: Phase 2A (uses testing identifiers as analytics event IDs)
+TOOL RESTRICTIONS: No Edit, No Bash
+NEXT: Phase 3 (Data Analysis)
+
+---
+
+## IMPLEMENTATION_MODULE
+
+Extensions: `Sources/UIComponentUtilities/Analytics/`
+- `View+Analytics.swift` - View modifiers
+- `AnalyticsContext.swift` - Context propagation
+
+---
+
+## VIEW_MODIFIERS
+
+| Modifier | Event Type | Usage |
+|----------|-----------|-------|
+| `.analyticsScreen(_:)` | `UIScreenViewed`, `UIScreenExited` | Screen lifecycle |
+| `.analyticsButton(id:label:type:)` | `UIInteractionButtonTapped` | Button taps |
+| `.analyticsCard(id:title:type:position:)` | `UIInteractionCardTapped` | Card taps |
+| `.analyticsLink(id:text:destination:type:)` | `UIInteractionLinkTapped` | Link taps |
+| `.analyticsToggle(id:label:isOn:)` | `UIInteractionToggleChanged` | Toggle changes |
+| `.analyticsTabChanged(id:selectedIndex:label:)` | `UINavigationTabChanged` | Tab selection changes |
+| `.analyticsImpression(id:type:name:position:)` | `UIVisibilityElementImpression` | Element visibility |
+| `.analyticsModal(id:name:type:)` | `UINavigationModalPresented/Dismissed` | Modal lifecycle |
+| `.analyticsError(id:type:code:message:displayType:)` | `UIErrorErrorDisplayed` | Error display |
+| `.analyticsContext(screenName:screenClass:)` | - | Context propagation |
+| `.analyticsComponent(_:)` | - | Component path |
+
+---
+
+## PARAMETER_TYPES
+
+| Modifier | Required | Optional |
+|----------|----------|----------|
+| `.analyticsButton` | id | label, type (.primary/.secondary/.tertiary/.text/.icon) |
+| `.analyticsCard` | id | title, type, position |
+| `.analyticsLink` | id | text, destination, type (.internal/.external/.deeplink/.phone/.email) |
+| `.analyticsToggle` | id, isOn | label |
+| `.analyticsTabChanged` | id, selectedIndex | label (closure `(Int) -> String?` returning tab title for given index) |
+| `.analyticsModal` | id | name, type (.sheet/.fullScreen/.popover/.alert) |
+| `.analyticsImpression` | id, type (.banner/.card/.promotion/.advertisement) | name, position |
+| `.analyticsError` | id, type (.network/.validation/.authentication/.server/.unknown) | code, message, displayType (.alert/.banner/.toast/.inline/.fullScreen) |
+
+---
+
+## PRE-CHECK: Phase 1 + Phase 2A Complete
+
+```
+Read: {artifactPath}/pass1/_index.md
+Read: {artifactPath}/pass1/design_context_response.json
+Read: {artifactPath}/pass1/component_properties.json
+Read: {artifactPath}/pass2/utility_identifiers.md    # From Phase 2A — use as event IDs
+Read: {artifactPath}/IMPLEMENTATION_HISTORY.md
+```
+
+EXTRACT:
+- `componentName`
+- `artifactPath`
+- Interactive elements from design_context
+- Testing identifiers (reuse as analytics IDs)
+
+### Registry Input (optional)
+
+The orchestrator may pass `registryData` containing pre-existing keys from `{repos.common.path}/Shared/Figma/Components/{nodeId}.json`.
+If `registryData.analyticsEvents` exists and is non-empty, use it to pre-populate the events list.
+Pre-existing events can be carried forward without re-analysis.
+
+If any required file is missing:
+
+```
+STATUS: HALT
+PHASE: phase-2d
+GATE: PRE_CHECK
+REASON: Required artifacts not found. Phase 1 and Phase 2A must complete first.
+COMPLETED_GATES: []
+ARTIFACTS_CREATED: none
+USER_ACTION_REQUIRED: Run Phase 1 and Phase 2A first.
+  - pass1/_index.md must exist (Phase 1 output)
+  - pass2/utility_identifiers.md must exist (Phase 2A output)
+```
+
+---
+
+## GATE 1: IDENTIFY_TRACKABLE_ELEMENTS
+
+Scan `design_context_response.json` and `component_properties.json` for elements matching event categories:
+
+| UI Element | Modifier | Event Type |
+|------------|----------|------------|
+| Button | `.analyticsButton(id:label:type:)` | `UIInteractionButtonTapped` |
+| Card | `.analyticsCard(id:title:type:position:)` | `UIInteractionCardTapped` |
+| Link | `.analyticsLink(id:text:destination:type:)` | `UIInteractionLinkTapped` |
+| Toggle/Switch | `.analyticsToggle(id:label:isOn:)` | `UIInteractionToggleChanged` |
+| Tab Group | `.analyticsTabChanged(id:selectedIndex:label:)` | `UINavigationTabChanged` |
+| Sheet/Modal | `.analyticsModal(id:name:type:)` | `UINavigationModalPresented/Dismissed` |
+| Banner/Promo | `.analyticsImpression(id:type:name:position:)` | `UIVisibilityElementImpression` |
+| Error Display | `.analyticsError(id:type:code:message:displayType:)` | `UIErrorErrorDisplayed` |
+| Screen Root | `.analyticsScreen(_:)` | `UIScreenViewed/Exited` |
+
+### Decision
+
+| Condition | Action |
+|-----------|--------|
+| No trackable elements found | → Skip to WRITE_ARTIFACT with "No analytics required" |
+| Has trackable elements | → Proceed to GATE 2 |
+
+---
+
+## GATE 2: MAP_EVENTS_TO_IDENTIFIERS
+
+For each trackable element, map to testing identifier from Phase 2A.
+
+**ID Source:** `UITestingIdentifierKey.{ComponentName}.{element}.description`
+
+Read `pass2/utility_identifiers.md` and match each interactive element to its corresponding testing identifier.
+
+### Modifier Mapping
+
+For each element, construct the full modifier call:
+
+| Element | Identifier Key | Modifier |
+|---------|----------------|----------|
+| Submit Button | `.submitButton` | `.analyticsButton(id: UITestingIdentifierKey.{ComponentName}.submitButton.description, label: "Submit", type: .primary)` |
+| Flight Card | `.flightCard` | `.analyticsCard(id: UITestingIdentifierKey.{ComponentName}.flightCard.description, title: route, type: "flight", position: index)` |
+| Promo Banner | `.promoBanner` | `.analyticsImpression(id: UITestingIdentifierKey.{ComponentName}.promoBanner.description, type: .banner, name: title, position: nil)` |
+
+### Registry Output Format
+
+When building the `analyticsEvents` array for `component-utilities.json`, output each event as:
+
+```json
+{
+  "element": "Submit Button",
+  "identifierKey": "ComponentName.submitButton",
+  "event": "Tracks button tap via `.analyticsButton(id:label:type:)` modifier with primary type."
+}
+```
+
+The `event` field is markdown text describing the tracked event. Each platform implements it in their own way.
+
+---
+
+## GATE 3: WRITE_ARTIFACT
+
+### JSON Sidecar (machine-readable)
+
+Write `{artifactPath}/pass2/utility_analytics.json`:
+
+```json
+{
+  "analyticsEvents": [
+    { "element": "Element name", "identifierKey": "ComponentName.element", "event": "Description of tracked event" }
+  ]
+}
+```
+
+If no analytics events needed, write `{ "analyticsEvents": [] }`.
+
+This JSON is consumed by `phase2-finalize.py` to build `component-utilities.json`. The orchestrator reads ONLY this JSON — never the markdown.
+
+### Markdown Artifact (human-readable)
+
+Write `{artifactPath}/pass2/utility_analytics.md`:
+
+```markdown
+# Analytics Events: {componentName}
+
+Generated: {ISO_DATE}
+Source: pass1/design_context_response.json, pass2/utility_identifiers.md
+
+## Summary
+- Total Events: {COUNT}
+- Modifiers: analyticsButton({N}), analyticsCard({N}), analyticsImpression({N}), etc.
+
+## Event Definitions
+
+| Element | Identifier Key | Modifier |
+|---------|----------------|----------|
+| Submit | .{ComponentName}.submitButton | .analyticsButton(id:label:type:) |
+| Card | .{ComponentName}.flightCard | .analyticsCard(id:title:type:position:) |
+| Banner | .{ComponentName}.promoBanner | .analyticsImpression(id:type:name:position:) |
+
+## Implementation
+
+import UIComponentUtilities
+
+### Screen Context (parent view)
+```swift
+ContentView()
+    .analyticsScreen("{ComponentName}")
+```
+
+### Button Tracking
+```swift
+Button("Submit") { submit() }
+    .accessibilityIdentifier(.{ComponentName}.submitButton)
+    .analyticsButton(
+        id: UITestingIdentifierKey.{ComponentName}.submitButton.description,
+        label: "Submit",
+        type: .primary
+    )
+```
+
+### Card Tracking (with position)
+```swift
+ForEach(flights.indices, id: \.self) { index in
+    FlightCard(flight: flights[index])
+        .accessibilityIdentifier(.{ComponentName}.flightCard.with(index))
+        .analyticsCard(
+            id: UITestingIdentifierKey.{ComponentName}.flightCard.with(index).description,
+            title: flights[index].route,
+            type: "flight",
+            position: index
+        )
+}
+```
+
+### Link Tracking
+```swift
+TextLink("Terms of Service")
+    .accessibilityIdentifier(.{ComponentName}.termsLink)
+    .analyticsLink(
+        id: UITestingIdentifierKey.{ComponentName}.termsLink.description,
+        text: "Terms of Service",
+        destination: "/terms",
+        type: .internal
+    )
+```
+
+### Toggle Tracking
+```swift
+Toggle("Notifications", isOn: $notificationsEnabled)
+    .accessibilityIdentifier(.{ComponentName}.notificationsToggle)
+    .analyticsToggle(
+        id: UITestingIdentifierKey.{ComponentName}.notificationsToggle.description,
+        label: "Notifications",
+        isOn: $notificationsEnabled
+    )
+```
+
+### Impression Tracking (banners, promotions)
+```swift
+PromotionBanner(promotion: promo)
+    .accessibilityIdentifier(.{ComponentName}.promoBanner)
+    .analyticsImpression(
+        id: UITestingIdentifierKey.{ComponentName}.promoBanner.description,
+        type: .banner,
+        name: promo.title,
+        position: index
+    )
+```
+
+### Tab Group Tracking
+```swift
+TabsSecondaryGroup(items: items, selectedIndex: $selectedIndex)
+    .analyticsTabChanged(
+        id: UITestingIdentifierKey.{ComponentName}.container.description,
+        selectedIndex: $selectedIndex,
+        label: { items.indices.contains($0) ? items[$0].title : nil }
+    )
+```
+
+### Modal Tracking
+```swift
+.sheet(isPresented: $showDetails) {
+    DetailsView()
+        .analyticsModal(
+            id: "flight_details",
+            name: "Flight Details",
+            type: .sheet
+        )
+}
+```
+
+### Error Tracking
+```swift
+ErrorBanner(error: networkError)
+    .analyticsError(
+        id: "network_error",
+        type: .network,
+        code: "CONN_TIMEOUT",
+        message: "Connection timed out",
+        displayType: .banner
+    )
+```
+
+### Direct Event (complex cases)
+```swift
+import AnalyticsEvents
+
+UIVisibilityPullToRefreshTriggered(
+    contentId: UITestingIdentifierKey.{ComponentName}.refreshControl.description,
+    contentType: "flights",
+    screenName: context.screenName,
+    timeSinceLastRefreshMs: nil
+).track()
+```
+```
+
+---
+
+## GATE 4: UPDATE_IMPLEMENTATION_HISTORY
+
+Append to `{artifactPath}/IMPLEMENTATION_HISTORY.md`:
+
+```markdown
+## Phase 2D: Analytics Events
+- Status: ✅ Complete
+- Artifact: pass2/utility_analytics.md
+- Events: {COUNT} ({modifiers_list})
+```
+
+---
+
+## VALIDATION CHECKLIST
+
+Before marking complete, verify:
+
+```
+[ ] Design context analyzed for interactive elements
+[ ] Testing identifiers loaded from Phase 2A (pass2/utility_identifiers.md)
+[ ] Each interactive element mapped to a view modifier (not raw events)
+[ ] Modifier parameters match the modifier's signature (required vs optional)
+[ ] IDs sourced from UITestingIdentifierKey.{Component}.{element}.description
+[ ] utility_analytics.json created (JSON sidecar for finalize script)
+[ ] utility_analytics.md created with complete implementation examples
+[ ] All 9 modifier types checked: analyticsButton, analyticsCard, analyticsLink, analyticsToggle, analyticsTabChanged, analyticsImpression, analyticsModal, analyticsError, analyticsScreen
+[ ] IMPLEMENTATION_HISTORY.md updated with Phase 2D status
+[ ] If no trackable elements: utility_analytics.md says "No analytics required"
+```
+
+---
+
+## SUCCESS OUTPUT
+
+```
+STATUS: COMPLETE
+PHASE: phase-2d
+GATES_PASSED: [PRE_CHECK, IDENTIFY_TRACKABLE_ELEMENTS, MAP_EVENTS_TO_IDENTIFIERS, WRITE_ARTIFACT, UPDATE_IMPLEMENTATION_HISTORY]
+ARTIFACTS_CREATED:
+  - {artifactPath}/pass2/utility_analytics.json
+  - {artifactPath}/pass2/utility_analytics.md
+SUMMARY: Analytics events: {COUNT} modifiers defined.
+```

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

@@ -0,0 +1,337 @@
+# PHASE 3 — Data Analysis Orchestrator
+
+Orchestrates Phase 3 sub-phases: dispatches sub-agents, collects results, writes pass3/_index.md.
+PREV: Phase 2 (Utility Integration)
+NEXT: Phase 4 (Implementation)
+
+---
+
+## PURPOSE
+
+Phase 3 is the bridge between data collection (Phases 1-2) and code generation (Phase 4).
+It transforms raw Figma artifacts into actionable analysis files that Phase 4 consumes directly.
+Each sub-phase writes one analysis file to `pass3/`. Phase 4 reads pass3/ as its sole input.
+
+---
+
+## PRE-CHECK: Phase 2 Complete
+
+```
+Read: {artifactPath}/IMPLEMENTATION_HISTORY.md
+Read: {artifactPath}/pass2/_index.md
+```
+
+EXTRACT:
+- `componentName`
+- `artifactPath`
+- `nodeId`
+- `fileKey`
+
+| Result | Action |
+|--------|--------|
+| Both files exist | Proceed to REGISTRY_LOOKUP |
+| Either missing | HALT |
+
+FAIL →
+```
+STATUS: HALT
+PHASE: phase-3
+GATE: PRE_CHECK
+REASON: IMPLEMENTATION_HISTORY.md or pass2/_index.md not found. Phase 2 must complete first.
+COMPLETED_GATES: []
+ARTIFACTS_CREATED: none
+USER_ACTION_REQUIRED: Run Phase 2 first.
+```
+
+Verify `pass3/` directory exists. If not:
+
+```bash
+mkdir -p {artifactPath}/pass3
+```
+
+---
+
+## NORMALIZE_DESIGN_CONTEXT: Handle Sublayer Format
+
+Phase 1 script may produce a sublayer format for large components. Normalize it before dispatching sub-phases so they always see a single `response` field.
+
+```
+Read: {artifactPath}/pass1/design_context_response.json
+```
+
+Check the JSON structure:
+
+| Format | Detection | Action |
+|--------|-----------|--------|
+| Normal | `sublayers` is `false` or absent | No action needed — `response` field exists |
+| Sublayer | `sublayers` is `true` | Concatenate all `responses` values (see below) |
+| Already normalized | `sublayers` is `true` AND `response` field exists | No action needed — Phase 2 already normalized |
+
+### Sublayer normalization (if not already done by Phase 2)
+
+If `sublayers: true` and no `response` field:
+
+1. Read all values from the `responses` object (keyed by node ID, e.g. `"123:456": "...code..."`)
+2. Concatenate them into a single string, separated by `\n\n// --- Sublayer: {nodeId} ---\n\n`
+3. Add a `response` field to the JSON with the concatenated string
+4. Keep the original `sublayers`, `sublayerNodeIds`, and `responses` fields intact (for traceability)
+5. Write the updated JSON back to `{artifactPath}/pass1/design_context_response.json`
+
+After normalization, all sub-phases read the `response` field as usual — no sublayer awareness needed.
+
+---
+
+## ROUTING
+
+### Sub-phase inventory
+
+| Sub-phase | Execution | Purpose | Required | Depends On |
+|-----------|-----------|---------|----------|------------|
+| 3A | **AI agent** (`phase-3a-location.md`) | Component name + path resolution | **ALWAYS** | Phase 1 (nodeId) |
+| 3B | **Script** (`scripts/phase3-scripts.py 3b`) | Figma variables → Swift tokens | **ALWAYS** | Phase 1 (variable_defs) |
+| 3C | **AI agent** (`phase-3c-nested.md`) | Nested component resolution | **ALWAYS** | Phase 1 (code_connect_map) |
+| 3D | **AI agent** (`phase-3d-patterns.md`) | Pattern detection + architecture + complexity | **ALWAYS** | Phase 1 (design_context, component_properties) |
+| 3E | **Script** (`scripts/phase3-scripts.py 3e`) | Asset inventory | If assets exist | Phase 1 (design_context_assets) |
+| 3F | **Script** (`scripts/phase3-scripts.py 3f`) | Utility integration summary | **ALWAYS** | Phase 2 (component-utilities.json) |
+| 3G | **Script** (`scripts/phase3-scripts.py 3g`) | Property coverage verification | **ALWAYS** | Phase 3D (architecture JSON output) |
+
+### Execution flow
+
+```
+PRE-CHECK
+    ↓
+NORMALIZE_DESIGN_CONTEXT
+    ↓
+┌──────────────────────────────────────────────────┐
+│  WAVE 1 — PARALLEL                               │
+│                                                  │
+│  Scripts (Bash, ~5s):                            │
+│   python3 scripts/phase3-scripts.py wave1        │
+│     → 3B Token Mapping                           │
+│     → 3E Asset Inventory                         │
+│     → 3F Utility Integration                     │
+│                                                  │
+│  AI Agents (parallel sub-agents):                │
+│   3A — Component Location          ← required   │
+│   3C — Nested Components           ← required   │
+│   3D — Patterns + Architecture     ← required   │
+│                                                  │
+└──────────────────────────────────────────────────┘
+    ↓ wait for all to complete
+    ↓
+┌──────────────────────────────────────────────────┐
+│  WAVE 2 — SEQUENTIAL (depends on 3D output)      │
+│                                                  │
+│  Script (Bash, ~1s):                             │
+│   python3 scripts/phase3-scripts.py 3g           │
+│     → 3G Property Coverage Verification          │
+│     Reads: 04b_component_architecture.json (3D)  │
+│                                                  │
+└──────────────────────────────────────────────────┘
+    ↓
+GATE 1: COLLECT_RESULTS
+    ↓
+GATE 2: WRITE_IMPLEMENTATION_SPEC
+    ↓
+GATE 3: UPDATE_IMPLEMENTATION_HISTORY
+    ↓
+GATE 4: WRITE_PASS3_INDEX
+    ↓
+PHASE OUTPUT
+```
+
+### Dispatch instructions
+
+**Wave 1 (parallel):** Launch scripts + AI agents simultaneously.
+
+Scripts (single Bash command):
+```bash
+python3 {skillPath}/scripts/phase3-scripts.py wave1 --artifact-path {artifactPath}
+```
+This runs 3B, 3E, 3F sequentially (~5-10s total). The script handles skip conditions for 3E automatically.
+
+AI Agents (sub-agents in parallel):
+- 3A, 3C, 3D — each reads from `pass1/` artifacts independently.
+- `design_context_response.json` is already normalized (flat `response` field) by NORMALIZE_DESIGN_CONTEXT.
+- Each writes its own file to `pass3/`.
+- Wait for ALL (scripts + agents) to complete before Wave 2.
+
+**Wave 2 (sequential):** Run 3G script after 3D completes.
+```bash
+python3 {skillPath}/scripts/phase3-scripts.py 3g --artifact-path {artifactPath}
+```
+- 3G reads `pass1/component_properties.json` + `pass3/04b_component_architecture.json` (from 3D).
+- 3G writes `pass3/00_property_coverage.json`.
+- Wait for 3G to complete before proceeding to GATE 1.
+
+### Skip conditions
+
+| Sub-phase | Skip when |
+|-----------|-----------|
+| 3E | No `pass1/design_context_assets.txt` exists or file is empty (handled by script — writes placeholder automatically) |
+
+---
+
+## GATE 1: COLLECT_RESULTS
+
+After all sub-phases complete, verify each produced its artifact:
+
+```
+[ ] pass3/01_component_location.md exists (Phase 3A)
+[ ] pass3/02_token_mapping.md exists (Phase 3B)
+[ ] pass3/03_nested_components.md exists (Phase 3C)
+[ ] pass3/04_patterns.md exists (Phase 3D — patterns section)
+[ ] pass3/04b_component_architecture.md exists (Phase 3D — architecture section)
+[ ] pass3/04b_component_architecture.json exists (Phase 3D — structured, for 3G script)
+[ ] pass3/05_complexity.md exists (Phase 3D — complexity section)
+[ ] pass3/06_assets.md exists (Phase 3E — or skipped placeholder)
+[ ] pass3/08_utility_integration.md exists (Phase 3F)
+[ ] pass3/00_property_coverage.json exists (Phase 3G)
+```
+
+ANY missing →
+```
+STATUS: HALT
+PHASE: phase-3
+GATE: COLLECT_RESULTS
+REASON: Sub-phase artifact missing.
+MISSING: [list missing files]
+USER_ACTION_REQUIRED: Re-run the failed sub-phase.
+```
+
+---
+
+## GATE 2: WRITE_IMPLEMENTATION_SPEC (script)
+
+**IMPORTANT:** Do NOT read pass3 sub-phase output files in the main orchestrator context. The spec script compiles everything from structured JSON files.
+
+```bash
+python3 {skillPath}/scripts/phase3-scripts.py spec --artifact-path '{artifactPath}'
+```
+
+The script reads `04b_component_architecture.json`, `00_property_coverage.json`, `pass1/component_summary.json`, and extracts counts from markdown files. It writes `pass3/07_implementation_spec.md`.
+
+| Result | Action |
+|--------|--------|
+| Exit 0 | Proceed to GATE 3 |
+| Exit 1 | HALT — missing required input files |
+
+---
+
+## GATE 3: UPDATE_IMPLEMENTATION_HISTORY
+
+Append to `{artifactPath}/IMPLEMENTATION_HISTORY.md`:
+
+```markdown
+## Phase 3: Data Analysis
+- Component Location: ✅ pass3/01_component_location.md
+- Token Mapping: ✅ pass3/02_token_mapping.md ({MAPPED} mapped, {MISSING} missing)
+- Nested Components: ✅ pass3/03_nested_components.md ({CONNECTED} connected, {UNCONNECTED} unconnected)
+- Pattern Detection: ✅ pass3/04_patterns.md
+- Component Architecture: ✅ pass3/04b_component_architecture.md
+- Complexity: {SIMPLE/COMPLEX} ({COUNT} properties)
+- Assets: ✅ pass3/06_assets.md ({NEW} new, {EXISTING} existing) | ⏭️ Skipped (no assets)
+- Implementation Spec: ✅ pass3/07_implementation_spec.md
+- Utility Integration: ✅ pass3/08_utility_integration.md
+- Property Coverage: ✅ pass3/00_property_coverage.json ({IMPLEMENTED} implement, {SKIPPED} skip, {DEFERRED} defer)
+```
+
+---
+
+## GATE 4: WRITE_PASS3_INDEX
+
+Write `{artifactPath}/pass3/_index.md`:
+
+```markdown
+# Pass 3 — Analysis Output
+
+Component: {componentName}
+Generated: {ISO_DATE}
+
+## Files
+
+| File | Description | Phase |
+|------|-------------|-------|
+| `pass3/01_component_location.md` | Component name, path, registry source | Phase 3A |
+| `pass3/02_token_mapping.md` | Figma variables → Swift tokens | Phase 3B |
+| `pass3/03_nested_components.md` | Connected/unconnected dependencies | Phase 3C |
+| `pass3/04_patterns.md` | Repeating/variant patterns, dimensions | Phase 3D |
+| `pass3/04b_component_architecture.md` | API shape, enums, configurations, list inference | Phase 3D |
+| `pass3/05_complexity.md` | SIMPLE/COMPLEX evaluation | Phase 3D |
+| `pass3/06_assets.md` | Asset inventory (new/existing) | Phase 3E |
+| `pass3/07_implementation_spec.md` | Compiled implementation blueprint | Phase 3 orchestrator |
+| `pass3/08_utility_integration.md` | Utility keys mapped to elements | Phase 3F |
+| `pass3/00_property_coverage.json` | Property coverage verification (IMPLEMENT/SKIP/DEFER) | Phase 3G |
+
+## Read Instructions
+
+Phase 4 (Implementation): read `pass3/07_implementation_spec.md` first (compiled spec).
+For details on any section, read the individual file.
+Token mapping: `pass3/02_token_mapping.md`
+API design: `pass3/04b_component_architecture.md`
+Utility integration: `pass3/08_utility_integration.md`
+```
+
+---
+
+## VALIDATION CHECKLIST
+
+```
+[ ] IMPLEMENTATION_HISTORY.md loaded from Phase 2
+[ ] design_context_response.json normalized (sublayer → flat response field, or already normalized by Phase 2)
+[ ] Scripts dispatched (wave1: 3B+3E+3F via phase3-scripts.py)
+[ ] AI agents dispatched (3A, 3C, 3D)
+[ ] All Wave 1 (scripts + agents) returned COMPLETE
+[ ] 01_component_location.md exists
+[ ] 02_token_mapping.md exists
+[ ] 03_nested_components.md exists
+[ ] 04_patterns.md exists
+[ ] 04b_component_architecture.md exists
+[ ] 05_complexity.md exists
+[ ] 06_assets.md exists (or skipped placeholder)
+[ ] 07_implementation_spec.md written by spec script (NOT by orchestrator reading files)
+[ ] 08_utility_integration.md exists
+[ ] 00_property_coverage.json exists (Phase 3G — all properties have IMPLEMENT/SKIP/DEFER status)
+[ ] IMPLEMENTATION_HISTORY.md updated with Phase 3 summary
+[ ] pass3/_index.md written listing ALL pass3 files
+```
+
+---
+
+## SUCCESS OUTPUT
+
+```
+STATUS: COMPLETE
+PHASE: phase-3
+GATES_PASSED: [PRE_CHECK, NORMALIZE_DESIGN_CONTEXT, DISPATCH_WAVE_1, DISPATCH_WAVE_2, COLLECT_RESULTS, WRITE_IMPLEMENTATION_SPEC, UPDATE_IMPLEMENTATION_HISTORY, WRITE_PASS3_INDEX]
+ARTIFACTS_CREATED:
+  - {artifactPath}/pass3/01_component_location.md (via Phase 3A — AI agent)
+  - {artifactPath}/pass3/02_token_mapping.md (via Phase 3B — script)
+  - {artifactPath}/pass3/03_nested_components.md (via Phase 3C — AI agent)
+  - {artifactPath}/pass3/04_patterns.md (via Phase 3D — AI agent)
+  - {artifactPath}/pass3/04b_component_architecture.md (via Phase 3D — AI agent)
+  - {artifactPath}/pass3/04b_component_architecture.json (via Phase 3D — AI agent)
+  - {artifactPath}/pass3/05_complexity.md (via Phase 3D — AI agent)
+  - {artifactPath}/pass3/06_assets.md (via Phase 3E — script)
+  - {artifactPath}/pass3/08_utility_integration.md (via Phase 3F — script)
+  - {artifactPath}/pass3/00_property_coverage.json (via Phase 3G — script)
+  - {artifactPath}/pass3/07_implementation_spec.md (orchestrator)
+  - {artifactPath}/pass3/_index.md
+SUMMARY: Data analysis complete. {TOTAL_FILES} analysis files created. Complexity: {SIMPLE/COMPLEX}. {MAPPED}/{TOTAL} tokens mapped. {CONNECTED}/{TOTAL} nested components connected. Ready for Phase 4.
+```
+
+---
+
+## REFERENCES
+
+| Topic | File |
+|-------|------|
+| Phase 3A | `phases/phase-3a-location.md` |
+| Phase 3B | `phases/phase-3b-tokens.md` |
+| Phase 3C | `phases/phase-3c-nested.md` |
+| Phase 3D | `phases/phase-3d-patterns.md` |
+| Phase 3E | `phases/phase-3e-assets.md` |
+| Phase 3F | `phases/phase-3f-utilities.md` |
+| Phase 3G | `phases/phase-3g-property-coverage.md` |
+| Registry Tool | `reference/registry.md` |
+| Missing Tokens | `reference/missing-tokens.md` |