@mmerterden/multi-agent-pipeline 11.1.0 → 11.3.0

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

@@ -1,503 +0,0 @@
----
-name: figma-cli-iterate-mend
-description: 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) →.
----
-
-# /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.