@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/figma-common/figma-cli-iterate-mend/SKILL.md

@@ -0,0 +1,498 @@
+# /figma-cli-iterate-mend — Full Mend Pipeline Orchestrator for CLI
+
+## Purpose
+
+Runs the complete Figma-to-SwiftUI **mend** pipeline for a single issue whose component already exists under `Discarded/` and must be re-implemented from scratch: pick → start → pre-flight (locate + catalog old files) → implement (phases 0-7 with selective old-file reference injection) → cleanup old files → commit. Returns a structured `ORCHESTRATOR_RESULT` block that the CLI orchestrator can parse.
+
+This skill IS the mend orchestrator. It is the union of:
+- `/figma-cli-iterate` — leaf-phase-only subagent dispatch, structured result output
+- `/figma-mend` — discarded-component location, old-file cataloging, per-phase reference injection, post-implementation cleanup
+
+**All leaf phase instructions, scripts, and references come from `.instructions/figma/figma-to-swiftui/`**. Nothing is duplicated. The only phases that differ from `/figma-cli-iterate` are:
+
+1. A pre-flight step before Phase 0 that locates and catalogs the discarded files.
+2. Every AI subagent dispatch prompt receives a `## Complementary Reference (Old Implementation)` section with phase-specific old file paths.
+3. A cleanup step after Phase 7 that deletes the old files.
+
+## Forbidden Dispatches
+
+**NEVER dispatch these as subagents — they are orchestrators that would try to dispatch further:**
+
+- `/figma-mend` (entire mend pipeline)
+- `/figma-to-swiftui` (entire regular pipeline)
+- `/figma-to-swift-ui-implement` (Phases 0-4)
+- `/figma-to-swift-ui-test` (Phase 5)
+- `/figma-to-swift-ui-code-connect` (Phase 6)
+- `/figma-to-swift-ui-wiki` (Phase 7)
+- `/figma-iteration-commit`
+- `/figma-cli-iterate`
+
+Instead, dispatch the **leaf phase instruction files** directly via the Agent tool.
+
+## Parameters
+
+```
+/figma-cli-iterate-mend #230   ← mend the component referenced by issue #230
+/figma-cli-iterate-mend         ← auto-pick the next available mend issue
+```
+
+The issue must reference a Figma node whose component exists under `Discarded/`. The pre-flight step locates it; if not found, the skill HALTs and asks the user to verify the Discarded/ catalog or fall back to `/figma-cli-iterate` for a fresh implementation.
+
+---
+
+## Constants
+
+```
+GH_REPO         = {github.componentsRepo}
+REPO_ROOT       = git repo root (auto-detect)
+COMMON          = ${REPO_ROOT}/{repos.common.path}
+UICOMPONENTS    = ${REPO_ROOT}/{repos.components.path}
+WIKI            = ${REPO_ROOT}/{repos.wiki.path}
+DISCARDED       = ${UICOMPONENTS}/Sources/UIComponents/Discarded
+TESTS           = ${UICOMPONENTS}/Tests/UIComponentsTests
+ARTIFACTS       = ${REPO_ROOT}/{repos.artifactsRepo}/ImplementationArtifacts
+PHASE_DIR       = .instructions/figma/figma-to-swiftui/phases
+REF_DIR         = .instructions/figma/figma-to-swiftui/reference
+SCRIPT_DIR      = .instructions/figma/figma-to-swiftui/scripts
+```
+
+---
+
+## STEP 0 — Pick Issue
+
+Same logic as `/figma-iterate` STEP 0. Read `.instructions/figma/figma-iterate/SKILL.md` STEP 0 for details.
+
+Extract from issue body: `componentName`, `figmaUrl`, `nodeId`, `nodeIdDash` (dash form, e.g. `517-834`), `jiraKey`, `registryName`, `figmaPage`, `acceptanceCriteria`.
+
+If the issue does NOT have a `mend` label or the body does not reference `Discarded/`, you may still proceed — the PRE-FLIGHT step below is the authoritative check for whether this is a mend candidate.
+
+---
+
+## STEP 1 — Start
+
+Run inline (not as a skill). Read `.instructions/figma/figma-to-swift-ui-start/SKILL.md` for the full procedure:
+
+1. Parse issue → extract metadata
+2. Fetch latest → checkout `develop` (main stays on develop, NO feature branch), `iteration/develop` (submodules)
+3. Create feature branches on **submodules only** (common, uicomponents)
+4. Registry lookup → `componentLocation`, `artifactPath`
+5. Save specs artifact if acceptance criteria exist
+6. Assign (GitHub + Jira)
+7. Update Projects V2 status
+
+---
+
+## STEP 2 — Pre-Flight: Locate and Catalog Old Component
+
+**Run entirely in the orchestrator — no subagents.** Uses `Grep`, `Glob`, and `Bash` directly.
+
+### PRE-1: LOCATE_OLD_COMPONENT
+
+Search for the old component under `${DISCARDED}` using these strategies in order. The first match wins.
+
+```bash
+# 1. By node ID (colon form) in any FIGMA.md under Discarded/
+grep -rl "{nodeId}" --include="FIGMA.md" "${DISCARDED}/"
+
+# 2. By node ID (dash form) in any FIGMA.md under Discarded/
+grep -rl "{nodeIdDash}" --include="FIGMA.md" "${DISCARDED}/"
+
+# 3. By node ID (colon form) in any .figma.swift under Discarded/
+grep -rl "{nodeId}" --include="*.figma.swift" "${DISCARDED}/"
+
+# 4. By component name directory match (if the issue provides one)
+find "${DISCARDED}/" -type d -name "{componentName}"
+```
+
+If no match → HALT:
+
+```
+STATUS: HALT
+PHASE: pre-flight
+GATE: LOCATE_OLD_COMPONENT
+REASON: No discarded component found for node {nodeId} under ${DISCARDED}/.
+USER_ACTION_REQUIRED: Verify the component exists under Discarded/, or run /figma-cli-iterate instead for a fresh implementation.
+```
+
+Extract:
+- `oldComponentPath` = full path to the old component directory (the directory that contains its `{Name}.swift`, `FIGMA.md`, etc.)
+- `oldComponentName` = basename of `oldComponentPath`
+
+### PRE-2: CATALOG_OLD_FILES
+
+Walk the filesystem and collect every file that belongs to the old component. Include not only the source directory but also its tests and artifacts.
+
+```bash
+# Sources
+find "{oldComponentPath}" -type f -name "*.swift"
+
+# Tests (search by old component name across all test categories)
+find "${TESTS}/Snapshot"       -type d -name "{oldComponentName}"
+find "${TESTS}/ViewInspector"  -type d -name "{oldComponentName}"
+find "${TESTS}"                -type f -name "*{oldComponentName}*"
+
+# Artifacts
+find "${ARTIFACTS}/Figma/Components"      -type d -name "{oldComponentName}"
+find "${ARTIFACTS}/Confluence"            -type d -name "{oldComponentName}"
+```
+
+Build `oldFilesCatalog` as an in-memory structure:
+
+| Key | Value |
+|---|---|
+| `sources` | list of `.swift` paths under `{oldComponentPath}` excluding `.figma.swift` |
+| `codeConnect` | list of `.figma.swift` paths under `{oldComponentPath}` |
+| `documentation` | path to `{oldComponentPath}/FIGMA.md` if present, else null |
+| `modifiers` | list of `*+Modifiers.swift` paths under `{oldComponentPath}` |
+| `tests.snapshot` | snapshot test directory path if present, else null |
+| `tests.viewInspector` | viewInspector test directory path if present, else null |
+| `tests.unit` | list of unit test file paths if present |
+| `artifacts` | old `ImplementationArtifacts/Figma/Components/.../{oldComponentName}` directory if present |
+| `confluence` | old `ImplementationArtifacts/Confluence/.../{oldComponentName}` directory if present |
+
+### PRE-3: RESOLVE_NAMES
+
+- `oldComponentName` — from PRE-1 (directory basename under `Discarded/`)
+- `newComponentName` — from the issue's `Component Name (PascalCase)` field, or from Phase 0 registry lookup if the issue does not specify
+- `nameChanged` — `true` if `oldComponentName != newComponentName`, else `false`
+
+### PRE-4: DEFERRED_CONTEXT_PERSIST
+
+Hold `oldFilesCatalog` in memory. Write `{artifactPath}/mend-context.json` immediately after Phase 0 creates `{artifactPath}/`. See STEP 3 Phase 0 subsection below.
+
+---
+
+## STEP 3 — Implement (Phases 0-7)
+
+This is the core orchestration. Run each phase by dispatching leaf subagents and scripts — **same phase dispatch table as `/figma-cli-iterate`**.
+
+### Spec Injection + Mend Injection
+
+Before dispatching any Phase 4+ subagent, check if `{artifactPath}/pass0/specs.md` exists. If it does, inject the specs as standard gates per `/figma-cli-iterate`'s rules.
+
+Additionally, **every AI subagent dispatch prompt for phases that should see old files** (see the Selective File Injection Table below) MUST append a `## Complementary Reference (Old Implementation)` section containing the relevant old file paths.
+
+### Dispatch Prompt Template (mend variant)
+
+For each leaf subagent eligible for old-file injection:
+
+```
+You are executing {Phase Name} of the Figma-to-SwiftUI workflow.
+
+## Context
+- Component: {newComponentName}
+- File Key: {fileKey}
+- Node ID: {nodeId}
+- Artifact Path: {artifactPath}
+- Component Location: {componentLocation}
+- Mode: MEND (re-implementing a discarded component)
+
+## CRITICAL SPEC GATES (only if specs exist)
+{Concrete requirements extracted from specs — phrased as mandatory instructions.}
+
+## Tool Restrictions
+{from dispatch table}
+
+## Your Instructions
+Read and STRICTLY FOLLOW your phase instructions gate-by-gate from this file:
+  {PHASE_DIR}/{instruction file}
+
+Read the return protocol from:
+  {REF_DIR}/halt-return-protocol.md
+
+## Reference Files
+{relevant reference files from the read-order table in figma-to-swiftui/SKILL.md}
+
+## Previous Phase Artifacts
+{artifact paths in read order — compact first}
+
+## Complementary Reference (Old Implementation)
+
+This component is being RE-IMPLEMENTED from Discarded/.
+Old source files (read as reference — do NOT copy verbatim):
+{list of relevant old file paths for this phase, from oldFilesCatalog via the Selective File Injection Table}
+
+Preserve domain-specific patterns from the old implementation if architecturally sound:
+- Animations, transitions, gesture handling
+- UI refinements (feathered edges, gradients, shadows)
+- Domain logic (list handling, data transformation, state management)
+- Variant mappings that were manually refined
+
+IMPORTANT: The new implementation MUST follow current workflow standards
+(macros, Configuration pattern, design tokens, naming rules). Use old code
+ONLY as reference for domain logic — not as a template for architecture.
+If the old file violates a current rule (e.g. a concrete {Name}Item struct),
+do NOT copy the violation forward.
+```
+
+### Phase Dispatch Table
+
+Same as `/figma-cli-iterate`:
+
+| Phase | Instruction | Model | Subagent? |
+|-------|-------------|-------|-----------|
+| 0 | `phase-0-init.md` | opus | Yes (leaf) |
+| 1 | `${SCRIPT_DIR}/phase1-gather.py` | N/A | No (script) |
+| 2A | `phase-2a-testing-identifiers.md` | opus | Yes (leaf) |
+| 2B | `phase-2b-localization.md` | sonnet | Yes (leaf) |
+| 2C | `phase-2c-accessibility.md` | opus | Yes (leaf) |
+| 2D | `phase-2d-analytics.md` | sonnet | Yes (leaf) |
+| 3A | `phase-3a-location.md` | sonnet | Yes (leaf) |
+| 3C | `phase-3c-nested.md` | sonnet | Yes (leaf) |
+| 3H | `phase-3h-variant-config.md` | opus | Yes (leaf) |
+| 3D | `phase-3d-patterns.md` | opus | Yes (leaf) |
+| 4A | `phase-4a-configuration.md` | opus | Yes (leaf, COMPLEX only) |
+| 4B | `phase-4b-view.md` | opus | Yes (leaf) |
+| 4C | `phase-4c-documentation.md` | sonnet | Yes (leaf) |
+| 4D | `phase-4d-preview.md` | sonnet | Yes (leaf) |
+| 4E | `phase-4e-modifiers.md` | sonnet | Yes (leaf, COMPLEX only) |
+| 5A | `phase-5a-viewinspector.md` | sonnet | Yes (leaf) |
+| 5B | `phase-5b-snapshot.md` | sonnet | Yes (leaf) |
+| 5C | `phase-5c-unit.md` | sonnet | Yes (leaf, if applicable) |
+| 6 | `phase-6-code-connect.md` | opus | Yes (leaf) |
+| 7 | `phase-7a-wiki-generate.md` | sonnet | Yes (leaf) |
+
+### Selective File Injection Table
+
+Each phase receives ONLY the relevant old files to keep context tight. Reference only, not a blanket copy.
+
+| Phase | Old files injected |
+|-------|--------------------|
+| 0 | None (standard init, but mend-context.json is written here) |
+| 1 | None (automated script — no subagent prompt) |
+| 2A | `oldFilesCatalog.documentation`, `oldFilesCatalog.sources` |
+| 2B | `oldFilesCatalog.documentation` |
+| 2C | `oldFilesCatalog.documentation`, `oldFilesCatalog.sources` |
+| 2D | `oldFilesCatalog.documentation` |
+| 3A | None |
+| 3C | `oldFilesCatalog.sources` |
+| 3H | `oldFilesCatalog.sources` (to see variant/Item classification in the old code) |
+| 3D | `oldFilesCatalog.sources`, `oldFilesCatalog.modifiers` |
+| 4A | Old Configuration and domain model files from `oldFilesCatalog.sources` |
+| 4B | ALL `oldFilesCatalog.sources` (primary reference phase) |
+| 4C | `oldFilesCatalog.documentation` |
+| 4D | `oldFilesCatalog.sources` |
+| 4E | `oldFilesCatalog.modifiers` |
+| 5A | `oldFilesCatalog.tests.viewInspector` (files if present) |
+| 5B | `oldFilesCatalog.tests.snapshot` (files if present) |
+| 5C | `oldFilesCatalog.tests.unit` (files if present) |
+| 6 | `oldFilesCatalog.codeConnect` |
+| 7 | None |
+
+### Phase Execution Flow
+
+**Phase 0**: Dispatch subagent → verify `IMPLEMENTATION_HISTORY.md` created.
+
+**Immediately after Phase 0 COMPLETE**: write `{artifactPath}/mend-context.json`:
+
+```json
+{
+  "mode": "mend",
+  "oldComponentName": "{oldComponentName}",
+  "oldComponentPath": "{oldComponentPath}",
+  "newComponentName": "{newComponentName}",
+  "nameChanged": {true|false},
+  "oldFiles": {
+    "sources":        ["{path1}", "{path2}"],
+    "codeConnect":    ["{path}"],
+    "documentation":  "{path or null}",
+    "modifiers":      ["{path}"],
+    "tests": {
+      "snapshot":      "{dirPath or null}",
+      "viewInspector": "{dirPath or null}",
+      "unit":          ["{path}"]
+    },
+    "artifacts":  "{dirPath or null}",
+    "confluence": "{dirPath or null}"
+  }
+}
+```
+
+Append to `{artifactPath}/IMPLEMENTATION_HISTORY.md`:
+
+```markdown
+## Mend Source
+- Discarded component: {oldComponentName}
+- Old path: {oldComponentPath}
+- Name changed: {true|false}
+- Old files catalogued in mend-context.json
+```
+
+**Phase 1**: Run the gather script. No dispatch prompt, no old-file injection.
+
+**Phase 2**: Exact same structure as `/figma-cli-iterate`. Wave 1 dispatches 2A + 2B + 2C in parallel; Wave 2 dispatches 2D; then `phase2-finalize.py`. Apply the injection table above for each AI subagent.
+
+**Phase 3**: Same as `/figma-cli-iterate` — Wave 1 script + 3A/3C/3H, token resolution if needed, Wave 2 (3D), Wave 3 script, spec compile, write `pass3/_index.md`. Apply the injection table.
+
+**Phase 4**: Same as `/figma-cli-iterate` — read SIMPLE/COMPLEX, Wave 1 (4B + 4C + 4A if COMPLEX), Wave 2 (4D + 4E if COMPLEX), validate, build. Apply the injection table. Phase 4B is the primary reference phase and receives ALL old source files.
+
+**Phase 5**: Same as `/figma-cli-iterate` — switch to local common, Wave 1 (5A + 5B), Wave 2 (5C if applicable), run tests sequentially, revert Package.swift. Apply the injection table — if the old tests exist they are very valuable reference for the new ones.
+
+**Phase 6**: Dispatch subagent with `oldFilesCatalog.codeConnect` injected → run `phase6-finalize.py` as safety net.
+
+**Phase 7**: Dispatch subagent. No old-file injection.
+
+---
+
+## STEP 4 — Cleanup Old Files
+
+Runs automatically after Phase 7 SUCCESS, **before** STEP 5 commit. This ensures the deletions are part of the same commit as the new implementation.
+
+### CLEANUP-1: VERIFY_NEW_IMPLEMENTATION
+
+```bash
+# New component file exists
+ls "{componentLocation}/{newComponentName}.swift"
+
+# It builds (local common swap already done in Phase 5 if needed)
+cd "${UICOMPONENTS}"
+xcodebuild -scheme UIComponents -destination 'generic/platform=iOS Simulator' build 2>&1 | grep -E "(error:|BUILD (SUCCEEDED|FAILED))" | tail
+```
+
+If the new file is missing or the build fails → HALT. Do NOT delete anything.
+
+### CLEANUP-2: DELETE_OLD_SOURCE
+
+```bash
+rm -rf "{oldComponentPath}"
+```
+
+Walk up parent directories (max 3 levels) and `rmdir` any that are now empty.
+
+### CLEANUP-3: DELETE_OLD_TESTS
+
+For each non-null entry in `oldFilesCatalog.tests`:
+
+```bash
+rm -rf "{oldFilesCatalog.tests.snapshot}"
+rm -rf "{oldFilesCatalog.tests.viewInspector}"
+# Unit tests: rm each file individually since they may not share a directory
+for f in {oldFilesCatalog.tests.unit[*]}; do rm -f "$f"; done
+```
+
+Walk up parent directories and `rmdir` any empty ones.
+
+### CLEANUP-4: DELETE_OLD_ARTIFACTS
+
+```bash
+rm -rf "{oldFilesCatalog.artifacts}"
+rm -rf "{oldFilesCatalog.confluence}"
+```
+
+### CLEANUP-5: VERIFY_BUILD_POST_DELETE
+
+```bash
+cd "${UICOMPONENTS}"
+xcodebuild -scheme UIComponents -destination 'generic/platform=iOS Simulator' build 2>&1 | grep -E "(error:|BUILD (SUCCEEDED|FAILED))" | tail
+```
+
+Since the old files lived in `Discarded/` (not in the compiled target), the delete should never break the build. If it does, HALT and report the broken references — do not attempt automatic recovery.
+
+### CLEANUP-6: UPDATE_HISTORY
+
+Append to `{artifactPath}/IMPLEMENTATION_HISTORY.md`:
+
+```markdown
+## Mend Cleanup
+- Old component: {oldComponentName} at {oldComponentPath}
+- Sources deleted: {count} files
+- Tests deleted: {count} directories/files
+- Artifacts deleted: {count} directories
+- Build verified after delete: yes
+- Date: {YYYY-MM-DD}
+```
+
+---
+
+## STEP 5 — Commit
+
+Run inline. Read `.instructions/figma/figma-iteration-commit/SKILL.md` for the full procedure. Same as `/figma-cli-iterate`:
+
+1. Rebase submodules to `iteration/develop` if on feature branch
+2. Build validation
+3. Commit to `iteration/develop` (common → uicomponents → wiki)
+4. Push with rebase-retry loop
+5. Clean up feature branches
+6. Issue housekeeping (comment, phase update, wiki link)
+7. Auto-unblock dependents
+
+The commit on the uicomponents submodule will naturally include both the new component files AND the deletions from STEP 4 — one atomic mend commit.
+
+**Commit message hint**: use `feat(uicomponents): [JIRA-KEY] mend {newComponentName} component` instead of `feat(uicomponents): [JIRA-KEY] add {newComponentName} component` so reviewers see at a glance that this replaces a Discarded/ component.
+
+---
+
+## STEP 6 — Loop
+
+Same logic as `/figma-iterate` STEP 4. If specific issue → exit after one. Otherwise → pick next mend issue.
+
+---
+
+## STEP 7 — Output Result
+
+Output EXACTLY this block as your FINAL message. Nothing else after it.
+
+### On success (per component):
+
+```
+ORCHESTRATOR_RESULT:
+  status: COMPLETE
+  mode: mend
+  issueNumber: <N>
+  componentName: <newComponentName>
+  oldComponentName: <oldComponentName>
+  nameChanged: <true|false>
+  figmaUrl: <url>
+  nodeId: <nodeId>
+  jiraKey: <key>
+  commits:
+    common: <SHA>
+    uicomponents: <SHA>
+    wiki: <SHA>
+  phases: [0, 1, 2, 3, 4, 5, 6, 7]
+  cleanup:
+    sourcesDeleted: <count>
+    testsDeleted: <count>
+    artifactsDeleted: <count>
+  testsRun: <count>
+  summary: <one-line>
+```
+
+### On failure:
+
+```
+ORCHESTRATOR_RESULT:
+  status: FAILED
+  mode: mend
+  issueNumber: <N>
+  componentName: <name>
+  failedPhase: <phase or pre-flight or cleanup>
+  reason: <exact reason>
+  suggestion: <what to fix>
+```
+
+### On full iteration completion:
+
+```
+ORCHESTRATOR_RESULT:
+  status: ITERATION_COMPLETE
+  mode: mend
+  completed:
+    - { issue: <N>, component: <name>, oldComponent: <name>, commits: { common: <SHA>, uicomponents: <SHA>, wiki: <SHA> } }
+  failed:
+    - { issue: <N>, component: <name>, phase: <phase>, reason: <reason> }
+  remaining: <count>
+```
+
+---
+
+## Error Handling
+
+- **No available issues**: Output ORCHESTRATOR_RESULT with status ITERATION_COMPLETE, empty completed/failed.
+- **Blocked issue**: Output FAILED.
+- **Pre-flight LOCATE_OLD_COMPONENT fails**: Output FAILED with phase `pre-flight` and suggest running `/figma-cli-iterate` (no mend needed).
+- **Phase HALT**: Show reason, ask user. If resolved → retry phase. If skipped → FAILED for this component, move to next.
+- **Build failure during Phase 4**: Attempt auto-fix. If unfixable → FAILED.
+- **Cleanup VERIFY_NEW_IMPLEMENTATION fails**: FAILED with phase `cleanup`. Old files are NOT deleted. New implementation must be fixed before re-running the skill with the same issue (which will resume from pre-flight — `mend-context.json` persists).
+- **3 consecutive failures**: Stop iteration.
+- **Subagents can't dispatch subagents**: This is why we dispatch only leaf phases. If a phase instruction file references dispatching subagents, ignore that — run its gates directly in the subagent.