@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/figma-common/figma-component-status-update/SKILL.md

@@ -0,0 +1,73 @@
+# /figma-to-swift-ui-status-update — Confluence Component Status Dashboard
+
+## Purpose
+
+Refreshes the global Component Implementation Status dashboard on Confluence. Reads the component catalog, registry, and sub-component graph to generate a comprehensive status page showing implementation readiness per platform.
+
+Requires VPN to {confluence.host}.
+
+## Parameters
+
+None.
+
+```
+/figma-to-swift-ui-status-update
+```
+
+---
+
+## Workflow
+
+### 1. VPN Check
+
+```bash
+curl -s --connect-timeout 5 {confluence.baseUrl} >/dev/null 2>&1 && echo "OK" || echo "NO VPN"
+```
+
+If no VPN → HALT. Ask user to connect.
+
+### 2. Run Status Dashboard Script
+
+```bash
+python3 .instructions/figma/figma-to-swiftui/scripts/confluence-component-status.py
+```
+
+This script:
+1. Reads component-catalog.json, component-index.json, sub-component-graph.json
+2. Reads all component registry JSONs from `Shared/Figma/Components/`
+3. Merges into a unified index with implementation status per platform
+4. Generates XHTML with color-coded status table
+5. Uploads to Confluence (updates in-place to avoid version bloat)
+
+The script reads the **architecture-update 4-flag status block** (`status.ios.{implemented,tested,codeConnect,wiki}`) — with fallback to legacy `codeConnect.ios` for any pre-backfill entry. Green/yellow/gray in the XHTML output is derived from `{value, against, implemented.version}`: green if `value=true` and `against >= implemented.version`, yellow if `against < implemented.version`, gray if `value=false`.
+
+### 3. Output
+
+Report the script output — total components, implemented count, and per-flag status breakdown (implemented / tested / code-connected / wiki counts).
+
+### 4. Per-component sync (optional)
+
+This skill refreshes the **global dashboard**. To sync a specific component's registry state to its GitHub issue + Projects V2 board at the same time, use:
+
+```bash
+python3 .instructions/figma/figma-to-swiftui/scripts/update-issue-from-registry.py \
+    --node-id "{nodeId}"
+```
+
+Or bulk:
+
+```bash
+python3 .instructions/figma/figma-to-swiftui/scripts/bulk-sync-issues.py
+```
+
+Bulk sync is already run by the `fix GitHub issues` job — only re-run if multiple registry entries have changed.
+
+---
+
+## Shared Resources
+
+| Resource | Description |
+|----------|-------------|
+| `scripts/confluence-component-status.py` | Dashboard generator + uploader |
+| `scripts/confluence-page-ids.json` | Confluence page ID mapping |
+| Component catalog + registry | Source data |

package/pipeline/skills/figma-common/figma-fix/SKILL.md

@@ -0,0 +1,316 @@
+# /figma-fix — Fix a Review Bug
+
+## Purpose
+
+Applies a targeted fix for a bug filed during component review (via `/figma-review`), re-runs affected pipeline phases, closes the bug sub-issue, and cleanly transitions the parent component back to **In Review** with a fresh review cycle (0/4).
+
+This skill fills the gap between `/figma-review` (which *files* bugs) and `/figma-iteration-commit` (which *syncs* state). Neither of those actually *fixes* the code.
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| Bug issue number | Yes (one of) | `#123` — the bug sub-issue filed by a reviewer |
+| Parent issue number | Alternative | `#100` — the parent component issue (lists open bugs to pick from) |
+| Figma URL | Alternative | Resolves to the component, then lists open bugs |
+
+```
+/figma-fix #456
+/figma-fix #100
+/figma-fix https://www.figma.com/design/9ipBvrtsq9HlQ175B9k0wx/?node-id=3:9872
+```
+
+---
+
+## Constants
+
+```
+GH_REPO = {github.componentsRepo}
+COMMON_PATH = {repos.common.path}
+```
+
+---
+
+## Gate 0: Resolve Bug + Component
+
+### If bug issue number provided (#N):
+
+1. Fetch the issue:
+```bash
+gh issue view <N> --repo ${GH_REPO} --json number,title,body,labels,assignees,parent
+```
+
+2. Verify it's a bug sub-issue:
+   - Must have `review-fix` or `bug` label
+   - Must have a parent issue (the component)
+
+3. Extract from parent:
+   - Node ID (from `### Node ID` section in parent body)
+   - Component name (from `### Component Name` section)
+
+### If parent issue number provided (#M):
+
+1. List open bug sub-issues:
+```bash
+gh issue list --repo ${GH_REPO} --search "parent:#<M> label:review-fix state:open" --json number,title,labels
+```
+
+2. If multiple bugs: present them and ask which to fix (or fix all sequentially).
+3. If zero bugs: HALT — "No open bugs on this component."
+
+### If Figma URL provided:
+
+1. Extract node-id, resolve via `FigmaRegistryUtility lookup`
+2. Find the matching open issue via node-id search
+3. Then follow the parent-issue path above
+
+### Resolve component paths:
+
+```bash
+cd ${COMMON_PATH}
+.build/debug/FigmaRegistryUtility lookup --node-id '{nodeId}'
+```
+
+Extract: `componentName`, `suggestedComponentLocation`, `suggestedArtifactPath`.
+
+---
+
+## Gate 1: Understand the Bug
+
+1. Read the bug sub-issue body for:
+   - Bug description
+   - Expected vs actual behavior
+   - Severity (`bug-minor` or `bug-major` label)
+
+2. Read the component source files:
+   - `{componentLocation}/{ComponentName}.swift`
+   - `{componentLocation}/{ComponentName}Configuration.swift` (if exists)
+   - `{componentLocation}/FIGMA.md`
+
+3. Read the Figma design (if MCP available) or FIGMA.md variant mapping to understand the correct behavior.
+
+4. Identify the fix — what code needs to change.
+
+---
+
+## Gate 2: Apply the Fix
+
+Edit the component source files to fix the bug. This is a **surgical edit**, not a full re-implementation.
+
+Rules:
+- Only edit files that need changing — don't rewrite the entire component
+- Follow existing code patterns (tokens, modifiers, configuration style)
+- If the fix requires new assets/tokens, use `/common-utility assets add-color` or `/common-utility assets generate`
+- If the fix requires new testing identifiers/localization/accessibility keys, use `/common-utility identifiers add` / `localization add` / `accessibility add`
+
+---
+
+## Gate 3: Build Verification
+
+```bash
+xcodebuild build \
+    -project "${REPO_ROOT}/{build.xcodeproj}" \
+    -scheme {build.scheme} \
+    -destination 'generic/platform=iOS' \
+    CODE_SIGNING_ALLOWED=NO \
+    -quiet
+```
+
+Must exit 0. If build fails, fix errors and retry.
+
+---
+
+## Gate 4: Re-run Phase 4 Finalize (version bump)
+
+The code changed, so the implementation version must 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 \
+    --no-sync
+```
+
+The `--no-sync` flag defers issue sync until Gate 7. The version bump automatically makes `tested` and `codeConnect` yellow (their `against` is now < `implemented.version`).
+
+---
+
+## Gate 5: Re-run Tests (Phase 5)
+
+Since code changed, tests must be re-run and may need updating:
+
+1. Run existing tests:
+```bash
+bash .instructions/figma/figma-to-swiftui/scripts/run-uicomponents-tests.sh \
+    --filter "{ComponentName}ViewInspectorTests"
+bash .instructions/figma/figma-to-swiftui/scripts/run-uicomponents-tests.sh \
+    --filter "{ComponentName}SnapshotTests"
+```
+
+2. If tests fail:
+   - ViewInspector failures: update test expectations to match the fix
+   - Snapshot failures: delete old snapshots, re-record with `withSnapshotTesting(record: .all)`
+
+3. After tests pass:
+```bash
+python3 .instructions/figma/figma-to-swiftui/scripts/phase5-finalize.py \
+    --node-id "{nodeId}" \
+    --platform ios \
+    --no-sync
+```
+
+---
+
+## Gate 6: Re-run Code Connect (Phase 6)
+
+If the fix changed the component's public interface or variant mapping:
+
+1. Check if `.figma.swift` needs updating:
+   - Read `{componentLocation}/{ComponentName}.figma.swift`
+   - Compare with FIGMA.md variant mapping
+   - If mapping changed → update `.figma.swift`
+   - If unchanged → skip
+
+2. If updated:
+```bash
+python3 .instructions/figma/figma-to-swiftui/scripts/phase6-finalize.py \
+    --node-id "{nodeId}" \
+    --file-key "{fileKey}" \
+    --component-name "{ComponentName}" \
+    --platform ios \
+    --no-sync
+```
+
+3. If skipped (no interface change), still re-mark codeConnect to clear the yellow:
+```bash
+python3 .instructions/figma/figma-to-swiftui/scripts/phase6-finalize.py \
+    --node-id "{nodeId}" \
+    --file-key "{fileKey}" \
+    --component-name "{ComponentName}" \
+    --platform ios \
+    --no-sync
+```
+
+---
+
+## Gate 7: Close Bug + Sync Parent
+
+### 7a. Close the bug sub-issue
+
+```bash
+gh issue close <bug_number> --repo ${GH_REPO} \
+    --comment "Fixed in $(git log -1 --format='%h') — $(git log -1 --format='%s')"
+```
+
+### 7b. Check remaining open bugs on parent
+
+```bash
+gh issue list --repo ${GH_REPO} \
+    --search "parent:#<parent_number> label:review-fix state:open" \
+    --json number
+```
+
+### 7c. If no more open bugs → remove review-fix from parent
+
+```bash
+gh issue edit <parent_number> --repo ${GH_REPO} --remove-label "review-fix"
+```
+
+### 7d. Sync parent issue to Projects V2
+
+```bash
+python3 .instructions/figma/figma-to-swiftui/scripts/update-issue-from-registry.py \
+    --node-id "{nodeId}"
+```
+
+This will:
+- Recompute flag states (all green after Gates 4-6)
+- Detect no bugfix signal (label removed + no open bugs)
+- Set Status column → **In Review**
+- Reset Review Progress → **0/4** (stale reviews from version bump)
+- Update Progress table emoji in issue body
+
+---
+
+## Gate 8: Commit
+
+Use `/figma-iteration-commit` or commit manually:
+
+```bash
+git add -A {componentLocation}/ Tests/
+git commit -m "fix({ComponentName}): <bug description summary>
+
+Fixes #<bug_number>
+Refs: <JIRA_KEY>"
+```
+
+The commit message references the bug issue number so GitHub auto-links it.
+
+---
+
+## Validation Checklist
+
+```
+[ ] Bug sub-issue identified and read
+[ ] Component source files read
+[ ] Fix applied — only changed files that needed changing
+[ ] xcodebuild build passed (exit 0)
+[ ] phase4-finalize.py ran — implementation version bumped
+[ ] Tests re-run and passing (ViewInspector + Snapshot)
+[ ] phase5-finalize.py ran — tested flag green
+[ ] Code Connect checked — .figma.swift updated if needed
+[ ] phase6-finalize.py ran — codeConnect flag green
+[ ] Bug sub-issue closed with fix commit reference
+[ ] review-fix label removed from parent (if last bug)
+[ ] update-issue-from-registry.py ran — parent synced to board
+[ ] Parent status column: In Review (not Bugfix)
+[ ] Parent review progress: 0/4 (fresh cycle)
+```
+
+---
+
+## Success Output
+
+```
+Bug fix complete: {ComponentName} — #{bug_number}
+
+| Field | Value |
+|-------|-------|
+| Bug | #{bug_number} — {bug_title} |
+| Component | {ComponentName} |
+| Fix commit | {commit_hash} |
+| Implementation version | {new_version} (bumped from {old_version}) |
+| Flags | impl: green, tested: green, cc: green, wiki: {state} |
+| Parent status | In Review (0/4) |
+| Remaining bugs | {count} open on #{parent_number} |
+
+Next: Reviewers can re-review the component at #{parent_number}.
+```
+
+---
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| Issue is not a bug (no review-fix/bug label) | HALT — not a bug issue |
+| No parent issue | HALT — orphan bug, can't resolve component |
+| Component not found via registry | HALT — check node-id |
+| Build fails after fix | Show errors, iterate |
+| Tests fail after fix | Show failures, update tests |
+| Bug close fails | Show error, ask user to close manually |
+| review-fix label removal blocked | Non-fatal — sync will still work via sub-issue count |
+| Sync fails | Non-fatal — finalize scripts already updated registry |
+
+---
+
+## Notes
+
+- This skill is **surgical** — it fixes one specific bug, not a full re-implementation
+- It always bumps `implemented.version` (Phase 4 finalize) because the code changed
+- The version bump automatically makes the old review count stale, forcing a fresh review cycle
+- Multiple bugs on the same component: run `/figma-fix` once per bug, or pass the parent issue to batch
+- The `--no-sync` flag on Gates 4-6 prevents 3 redundant sync calls — Gate 7d does a single authoritative sync
+- Works hand-in-hand with `/figma-review` (which creates bugs) and `/figma-iteration-commit` (which commits)