@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/figma-ios/figma-to-component/phases/phase-7a-wiki-generate.md

@@ -0,0 +1,580 @@
+# PHASE 7A — Wiki Documentation: Generate Markdown
+
+Generate a single-file markdown documentation page for the wiki submodule.
+No VPN required. No Confluence knowledge needed.
+
+PREV: Phase 6 (Code Connect)
+NEXT: Phase 7B (inline — commit + push wiki repo)
+TOOL RESTRICTIONS: No Edit
+
+> **No VPN needed.** This phase writes to the local wiki submodule. The orchestrator
+> handles git commit + push in Phase 7B (inline, no subagent).
+
+---
+
+## PRE_CHECK
+
+```
+Read: {artifactPath}/IMPLEMENTATION_HISTORY.md
+Read: {componentLocation}/{componentName}.swift
+Read: {componentLocation}/FIGMA.md
+Read: {artifactPath}/pass1/screenshot.png (verify exists)
+Read: {artifactPath}/pass1/screenshots/variants.md (if exists — variant property values)
+Read: {artifactPath}/pass3/07_implementation_spec.md
+Read: {artifactPath}/pass3/08_utility_integration.md
+Read: {artifactPath}/pass3/03_nested_components.md
+Read: {artifactPath}/pass2/utility_analytics.md (if exists)
+```
+
+Also find iOS snapshot tests and reference images:
+
+```
+Glob: Tests/UIComponentsTests/Snapshot/**/{componentName}SnapshotTests.swift
+Glob: Tests/UIComponentsTests/Snapshot/**/{componentName}/__Snapshots__/{componentName}SnapshotTests/*.png
+```
+
+Read the snapshot test file to extract test names and the Swift code each test uses.
+
+Also read the per-component registry:
+
+```bash
+cd {repos.common.path} && .build/debug/FigmaRegistryUtility lookup --node-id '{nodeId}'
+```
+
+EXTRACT:
+- `componentName`, `nodeId`, `fileKey`
+- `componentLocation`, `artifactPath`
+- `complexity` (SIMPLE/COMPLEX from pass3/07)
+- `registryData` (testingIdentifiers, localizationKeys, accessibilityKeys, analyticsEvents)
+- Initializer signature (from FIGMA.md)
+- Usage examples (from FIGMA.md)
+- Nested components (from FIGMA.md / pass3/03)
+- Description, screen, section, size (from pass3/07)
+
+Derive wiki paths:
+- `wikiRoot` = `{repos.wiki.path}`
+- `wikiCategory` = derive from `artifactPath` (e.g., `DesignSystemCore`, `MobileAppComponents/Components/BottomAction`)
+- `wikiComponentPath` = `{wikiRoot}/{wikiCategory}/{componentName}`
+
+If IMPLEMENTATION_HISTORY.md, the Swift file, or FIGMA.md is missing:
+
+```
+STATUS: HALT
+PHASE: phase-7a
+GATE: PRE_CHECK
+REASON: Required artifacts not found.
+COMPLETED_GATES: []
+ARTIFACTS_CREATED: none
+USER_ACTION_REQUIRED: Ensure Phase 4 completed. Required: IMPLEMENTATION_HISTORY.md, {componentName}.swift, FIGMA.md
+```
+
+---
+
+## GATE 1: CREATE_WIKI_STRUCTURE
+
+Create output directory and copy screenshots.
+
+```bash
+mkdir -p {wikiComponentPath}/assets
+cp {artifactPath}/pass1/screenshot.png {wikiComponentPath}/assets/screenshot.png
+```
+
+If variant screenshots exist:
+
+```bash
+if [ -d "{artifactPath}/pass1/screenshots" ]; then
+    cp {artifactPath}/pass1/screenshots/*.png {wikiComponentPath}/assets/
+fi
+```
+
+If iOS snapshot test reference images exist, copy with `ios_` prefix:
+
+```bash
+# Snapshot image filenames are: test_snapshot_{mode}_{variant}.{mode}_{variant}.png
+# Extract the named part (after the dot) and prefix with ios_
+# e.g. test_snapshot_light_success.light_success.png → ios_light_success.png
+for f in __Snapshots__/{ComponentName}SnapshotTests/*.png; do
+    named=$(echo "$(basename "$f")" | sed 's/.*\.\(.*\)\.png/\1/')
+    cp "$f" {wikiComponentPath}/assets/ios_${named}.png
+done
+```
+
+List all copied assets for the ARTIFACTS_CREATED output.
+
+---
+
+## GATE 2: GENERATE_MARKDOWN
+
+Write `{wikiComponentPath}/{ComponentName}.md` using the template below.
+
+**All images use wiki syntax:** `[[/{wikiCategory}/{componentName}/assets/{filename}]]`
+
+> **CRITICAL:** GitHub Wiki `[[image.png|alt]]` syntax uses `|` for alt text.
+> Inside markdown tables, `|` is the column separator — so `[[image.png|alt]]` breaks the table.
+> **Rule:** NEVER use `|alt` in image links inside tables. Use `[[image.png]]` only.
+> Outside tables (e.g., the hero screenshot at top), `[[image.png|alt]]` is safe.
+
+### Data Mapping
+
+| Template Variable | Source |
+|-------------------|--------|
+| `{DESCRIPTION}` | Synthesize 1-line from pass3/07 overview |
+| `{FILE_KEY}`, `{NODE_ID}` | From context |
+| `{SCREEN}`, `{SECTION}`, `{SIZE}` | From pass3/07 metadata |
+| `{OVERVIEW_TEXT}` | 2-3 sentence description from pass3/07 |
+| Testing Identifiers table | `registryData.testingIdentifiers` — columns: Element (usage), Key, Value |
+| Localization Keys table | `registryData.localizationKeys` — columns: Element, Key, Default |
+| Accessibility tables | `registryData.accessibilityKeys` — Labels + Hints |
+| Analytics Events | `registryData.analyticsEvents` — element + event description |
+| Sub-Components | From FIGMA.md nested components / pass3/03 |
+| Changelog | Current date + "Initial documentation" |
+
+### Empty Section Handling
+
+- If `testingIdentifiers` is empty: `*No testing identifiers registered.*`
+- If `localizationKeys` is empty: `*No localization keys. Text content is dynamic.*`
+- If `accessibilityKeys` is empty: `*No dedicated accessibility keys.*`
+- If `analyticsEvents` is empty: `*No analytics events. No interactive elements.*`
+- If no nested components: `*No nested View components.*`
+- If no variant screenshots: show only main screenshot, skip Variants table
+
+### Markdown Template
+
+```markdown
+# {ComponentName}
+
+*{DESCRIPTION}*
+
+[[/{wikiCategory}/{componentName}/assets/screenshot.png|{ComponentName}]]
+
+[View in Figma](https://www.figma.com/design/{FILE_KEY}/?node-id={NODE_ID_DASH})
+
+**Screen:** {SCREEN}
+**Section:** {SECTION}
+**Size:** {SIZE}
+
+---
+
+## Variants
+
+| Variant | Properties | Screenshot |
+|---------|-----------|-----------|
+| {VariantName} | `{Prop}={Value}` | [[/{wikiCategory}/{componentName}/assets/{VariantName}.png]] |
+
+<!-- Use pass1/screenshots/variants.md for variant names + property values -->
+<!-- If no variant screenshots, skip this section entirely -->
+
+---
+
+## Overview
+
+{OVERVIEW_TEXT}
+
+---
+
+## Testing Identifiers
+
+*Shared across platforms*
+
+| Element | Key | Value |
+|---------|-----|-------|
+| {usage} | `{key}` | `{value}` |
+
+---
+
+## Localization Keys
+
+*Shared across platforms*
+
+| Element | Key | Default (EN) |
+|---------|-----|-------------|
+| {element} | `{key}` | {default} |
+
+---
+
+## Accessibility
+
+*Shared across platforms*
+
+### Labels
+
+| Element | Key |
+|---------|-----|
+| {element} | `{key}` |
+
+### Hints
+
+| Element | Key |
+|---------|-----|
+| {element} | `{key}` |
+
+---
+
+## Analytics Events
+
+*Shared across platforms*
+
+### {event_element}
+
+{event_description}
+
+| Property | Value |
+|----------|-------|
+| Element | {element} |
+| Identifier Key | `{identifierKey}` |
+
+---
+
+## Sub-Components
+
+| Component | Description |
+|-----------|-------------|
+| [[{SubComponentName}]] | {description} |
+
+---
+
+## Platform Implementations
+
+| Platform | Status |
+|----------|--------|
+| iOS | Implemented |
+| Android | Pending |
+
+---
+
+## iOS Implementation
+
+### Initializer
+
+<!-- IF SIMPLE: -->
+```swift
+{INIT_SIGNATURE}
+```
+
+#### Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `{param}` | `{Type}` | {default} | {description} |
+
+<!-- IF COMPLEX: -->
+```swift
+// Chain modifiers (recommended)
+{ComponentName} { /* dependency closure */ }
+    .{modifier}({value})
+
+// Configuration closure
+{ComponentName} { config in
+    config
+        .{modifier}({value})
+}
+
+// Direct configuration
+{ComponentName}(configuration: {ComponentName}Configuration(
+    {param}: {value}
+))
+```
+
+#### Configuration Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `{param}` | `{Type}` | {default} | {description} |
+
+#### Chain Modifiers
+
+Auto-generated by `@GenerateChainModifiers`.
+
+| Modifier | Type | Description |
+|----------|------|-------------|
+| `.{property}(_:)` | `{Type}` | {description} |
+
+<!-- END complexity branching -->
+
+### Usage
+
+```swift
+import UIComponents
+
+{USAGE_CODE}
+```
+
+### Testing Identifiers - iOS
+
+| Element | iOS Usage |
+|---------|-----------|
+| {element} | `.accessibilityIdentifier(.{ComponentName}.{element})` |
+
+<!-- Skip if no testing identifiers -->
+
+### Localization - iOS
+
+| Element | iOS Usage |
+|---------|-----------|
+| {element} | `Text(.{ComponentName}.{element})` |
+
+<!-- Skip if no localization keys -->
+
+### Accessibility - iOS
+
+| Element | iOS Usage |
+|---------|-----------|
+| {element} | `.accessibilityLabel(.{ComponentName}.{element})` |
+
+<!-- Skip if no accessibility keys -->
+
+### Analytics - iOS
+
+#### {event_element}
+
+**Modifier:**
+
+```swift
+{ANALYTICS_MODIFIER_CODE_FROM_PASS2}
+```
+
+**Firebase Schema:**
+
+```json
+{FIREBASE_SCHEMA_JSON}
+```
+
+<!-- Skip if no analytics events -->
+
+---
+
+## Code Connect
+
+| Property | Value |
+|----------|-------|
+| Status | Published |
+| Strategy | {CODE_CONNECT_STRATEGY} |
+| File | `{ComponentName}.figma.swift` |
+
+<!-- Strategy from pass1/component_properties.json codeConnectStrategy -->
+<!-- If Code Connect was not published (Phase 6 skipped), set Status = Pending -->
+
+---
+
+## Snapshot Tests
+
+*Reference snapshots generated by `{ComponentName}SnapshotTests`.*
+
+### {Category}
+
+| Variant | Code | Light | Dark |
+|---------|------|-------|------|
+| **{VariantName}** | `{ComponentName}({param}: .{value})` | [[/{wikiCategory}/{componentName}/assets/ios_light_{variant}.png]] | [[/{wikiCategory}/{componentName}/assets/ios_dark_{variant}.png]] |
+
+<!-- Group by test category from MARK comments in snapshot test file -->
+<!-- Code column: full init using preferred style (SIMPLE: direct init, COMPLEX: chain modifiers) -->
+<!-- Pair light/dark for same variant side by side -->
+<!-- Skip this section if no snapshot tests exist -->
+
+### RTL Variants (Arabic)
+
+| Variant | Code | Light | Dark |
+|---------|------|-------|------|
+| **{VariantName}** | `{ComponentName}({param}: "{arabicText}")` | [[/{wikiCategory}/{componentName}/assets/ios_rtl_light_{variant}.png]] | [[/{wikiCategory}/{componentName}/assets/ios_rtl_dark_{variant}.png]] |
+
+<!-- RTL snapshots use ios_rtl_ prefix. Arabic text from phase-5b Arabic Sample Text table. -->
+<!-- Skip if no RTL snapshot tests exist -->
+
+---
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| {DATE} | Initial documentation |
+```
+
+**IMPORTANT:**
+- Replace ALL template variables with actual data.
+- Remove ALL HTML comments (<!-- ... -->) from final output.
+- Include only sections that have data — skip empty optional sections entirely.
+- The `## iOS Implementation` heading is the split marker. Everything above is shared/cross-platform, everything from `## iOS Implementation` onward is iOS-specific. The standalone `/figma-to-swift-ui-confluence` skill uses this marker to split into two Confluence XHTML files.
+
+---
+
+## GATE 3: VALIDATE_MARKDOWN
+
+Run the validation script:
+
+```bash
+python3 .instructions/figma/figma-to-swiftui/scripts/validate-phase7a.py \
+    --wiki-path "{wikiComponentPath}" \
+    --component-name "{ComponentName}" \
+    --mode wiki
+```
+
+The script outputs JSON with `status`, `violations`, `warnings`, and `stats`.
+
+### What the script checks in wiki mode
+
+**{ComponentName}.md — Structure:**
+- Required sections: `## Overview`, `## Testing Identifiers`, `## Localization Keys`, `## Accessibility`, `## Analytics Events`, `## Sub-Components`, `## Platform Implementations`, `## Changelog`
+- `## iOS Implementation` marker present
+- Under iOS: `### Initializer`, `### Usage`, `### Snapshot Tests` (if snapshot assets exist)
+
+**Content integrity:**
+- No unreplaced template variables (`{ComponentName}`, `{DESCRIPTION}`, etc.)
+- No remaining template comments (`<!-- IF`, `<!-- END`, `<!-- ELSE`)
+
+**Asset reference integrity:**
+- Every `[[...assets/{filename}` reference (with or without `|alt`) has a matching file in `{wikiComponentPath}/assets/`
+- Orphan detection: files in `assets/` not referenced by markdown (warning, not failure)
+- No `|alt` inside table rows (pipe breaks table columns)
+- `screenshot.png` exists
+
+**Snapshot coverage:**
+- Every snapshot variant has both `ios_light_{variant}.png` AND `ios_dark_{variant}.png`
+- Every snapshot asset is referenced in the markdown
+- RTL: same check for `ios_rtl_light_` / `ios_rtl_dark_` pairs
+
+### On failure
+
+Fix violations, re-generate markdown, re-run validation.
+
+```
+STATUS: HALT
+PHASE: phase-7a
+GATE: VALIDATE_MARKDOWN
+REASON: Wiki markdown validation failed.
+VIOLATIONS: {violations from script JSON}
+WARNINGS: {warnings from script JSON}
+STATS: {stats from script JSON}
+COMPLETED_GATES: [PRE_CHECK, CREATE_WIKI_STRUCTURE, GENERATE_MARKDOWN]
+USER_ACTION_REQUIRED: Fix the violations listed above and re-generate the markdown.
+```
+
+---
+
+## GATE 4: UPDATE_SIDEBAR
+
+**Pre-condition**: Ensure the wiki is up-to-date before regenerating:
+```bash
+cd {wikiRoot}
+git pull origin master 2>/dev/null || true
+```
+
+The sidebar is generated deterministically from the wiki directory structure by `sidebar-generator.py`. Do NOT manually edit `_Sidebar.md`.
+
+Run the generator:
+```bash
+python3 .instructions/figma/figma-to-swiftui/scripts/sidebar-generator.py --wiki-root {wikiRoot}
+```
+
+This script scans `DesignSystemCore/`, `MobileAppComponents/`, and `VisualAssets/` folders, then produces a sorted, idempotent `_Sidebar.md`. Every run with the same directory state produces identical output — eliminating merge conflicts.
+
+**Post-validation (HARD GATE — must pass to proceed)**:
+```bash
+grep -q '\[\[{ComponentName}\]\]' {wikiRoot}/_Sidebar.md
+```
+If grep exits non-zero → HALT:
+```
+STATUS: HALT
+PHASE: phase-7a
+GATE: UPDATE_SIDEBAR
+REASON: _Sidebar.md does not contain [[{ComponentName}]] after sidebar-generator.py run.
+USER_ACTION_REQUIRED: Verify the component wiki folder exists under the correct section directory and re-run sidebar-generator.py.
+```
+Do NOT proceed to GATE 5 until this validation passes.
+
+---
+
+## GATE 5: UPDATE_STATUS_TABLE
+
+The status page is generated by `confluence-component-status.py`, not manually edited.
+Run the script to regenerate it with the newly implemented component included:
+
+```bash
+python3 .instructions/figma/figma-to-swiftui/scripts/confluence-component-status.py
+```
+
+The script reads the component index and produces `{wikiRoot}/ComponentImplementationStatus.md` with the current status of all components. The newly implemented component will appear as ✅ with a `[[wiki-link]]` automatically.
+
+---
+
+## GATE 6: UPDATE_REGISTRY
+
+Run the Phase 7 finalize script to mark `wiki` in the component registry:
+
+```bash
+python3 .instructions/figma/figma-to-swiftui/scripts/phase7-finalize.py \
+    --node-id "{nodeId}" \
+    --platform ios
+```
+
+| Result | Action |
+|--------|--------|
+| Exit 0, `"action": "updated"` | `status.ios.wiki` set green, `against = implemented.version` — proceed |
+| Exit 0, `"action": "already_current"` | Already marked against current implemented.version — 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.wiki`. The script records `against = status.ios.implemented.version` so the flag automatically drops to yellow on the next Phase 4 version bump until wiki pages are refreshed. `figma-iteration-commit` reads this and syncs the GitHub issue via `update-issue-from-registry.py`.
+
+FAIL →
+```
+STATUS: HALT
+PHASE: phase-7a
+GATE: UPDATE_REGISTRY
+REASON: phase7-finalize.py failed.
+COMPLETED_GATES: [PRE_CHECK, CREATE_WIKI_STRUCTURE, GENERATE_MARKDOWN, VALIDATE_MARKDOWN, UPDATE_SIDEBAR, UPDATE_STATUS_TABLE]
+USER_ACTION_REQUIRED: Check script error output; verify node-id matches the registry.
+```
+
+---
+
+## GATE 7: UPDATE_HISTORY
+
+Append to `{artifactPath}/IMPLEMENTATION_HISTORY.md`:
+
+```markdown
+## Phase 7A: Wiki Documentation
+- Status: Complete
+- Wiki Page: {wikiComponentPath}/{ComponentName}.md
+- Assets: {COUNT} screenshots
+- Validation: Passed
+- Sidebar: Updated
+- Status Table: Updated
+```
+
+---
+
+## VALIDATION CHECKLIST
+
+```
+[ ] {wikiComponentPath}/{ComponentName}.md exists
+[ ] {wikiComponentPath}/assets/screenshot.png exists
+[ ] Markdown has ## iOS Implementation split marker
+[ ] Main sections present: Variants, Overview, Testing IDs, Localization, Accessibility, Analytics, Sub-Components, Platform Implementations, Changelog
+[ ] iOS sections present: Initializer, Usage, Code Connect, Snapshot Tests (if snapshots exist)
+[ ] All images use wiki syntax: [[/...]]
+[ ] No image alt text (|alt) used inside markdown tables
+[ ] All template variables replaced
+[ ] No HTML comments remaining
+[ ] All referenced image filenames exist in assets/
+[ ] _Sidebar.md contains [[{ComponentName}]]
+[ ] ComponentImplementationStatus.md contains row for component
+[ ] phase7-finalize.py passed (status.ios.wiki updated)
+[ ] IMPLEMENTATION_HISTORY.md updated with Phase 7A entry
+```
+
+---
+
+## SUCCESS OUTPUT
+
+```
+STATUS: COMPLETE
+PHASE: phase-7a
+GATES_PASSED: [PRE_CHECK, CREATE_WIKI_STRUCTURE, GENERATE_MARKDOWN, VALIDATE_MARKDOWN, UPDATE_SIDEBAR, UPDATE_STATUS_TABLE, UPDATE_REGISTRY, UPDATE_HISTORY]
+ARTIFACTS_CREATED:
+  - {wikiComponentPath}/{ComponentName}.md (validated)
+  - {wikiComponentPath}/assets/ ({COUNT} screenshots)
+  - {wikiRoot}/_Sidebar.md (updated)
+  - {wikiRoot}/ComponentImplementationStatus.md (updated)
+  - {artifactPath}/IMPLEMENTATION_HISTORY.md (updated)
+SUMMARY: Wiki documentation generated. {SECTION_COUNT} sections. {SCREENSHOT_COUNT} assets. Ready for phase-7b commit+push.
+```

package/pipeline/skills/figma-ios/figma-to-component/phases/phase-8-cleanup.md

@@ -0,0 +1,51 @@
+# PHASE 8 — Cleanup
+
+Remove generated artifacts that are no longer needed after upload, to avoid bloating the codebase.
+PREV: Phase 7B (Confluence Upload)
+
+---
+
+## PRE-CHECK
+
+Read `{artifactPath}/IMPLEMENTATION_HISTORY.md`.
+
+Verify Phase 7B is complete (has "Phase 7B" section with "Status: Complete").
+
+If Phase 7B is not complete → HALT. Do not delete artifacts that haven't been uploaded yet.
+
+---
+
+## GATE 1: DELETE CONFLUENCE ARTIFACTS
+
+If `{artifactPath}/confluence/` exists AND Phase 7B is complete:
+
+Delete `{artifactPath}/confluence/` (the entire directory including `assets/`, `main.html`, `ios.html`).
+
+These are local XHTML generation artifacts. The content is live on Confluence — the local copy is only needed during Phase 7A generation and 7B upload.
+
+If confluence directory does not exist → skip (already cleaned or never generated locally).
+
+---
+
+## GATE 2: UPDATE IMPLEMENTATION HISTORY
+
+Append to `{artifactPath}/IMPLEMENTATION_HISTORY.md`:
+
+```markdown
+## Phase 8: Cleanup
+- Confluence artifacts: Deleted (uploaded in Phase 7B)
+- Date: {DD.MM.YYYY}
+```
+
+---
+
+## PHASE OUTPUT
+
+```
+STATUS: COMPLETE
+PHASE: phase-8
+GATES_PASSED: [PRE_CHECK, DELETE_CONFLUENCE_ARTIFACTS, UPDATE_HISTORY]
+DELETED:
+  - {artifactPath}/confluence/ ({size})
+SUMMARY: Cleanup complete. Removed {total_size} of generated Confluence artifacts.
+```