@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/scripts/sync-figma-source.sh

@@ -0,0 +1,228 @@
+#!/usr/bin/env bash
+# sync-figma-source.sh — incremental sync from the upstream figma-to-component
+# source repo into pipeline/skills/figma-ios/. Wraps import-figma-skills.sh
+# but runs it ONLY for files touched since the recorded lastCommit, preserving
+# local review progress (REVIEW_CHECKLIST.md is never overwritten).
+#
+# Trigger flow:
+#   1. Read prefs.global.figmaSource.path + .branch + .lastCommit
+#   2. `git -C <path> fetch` + check out branch
+#   3. Compute changed files since lastCommit under .instructions/figma/ and .claude/skills/
+#   4. For each changed source skill, re-run the import with --only <name>
+#   5. Append a sync note to CHANGELOG.md
+#   6. Update prefs.global.figmaSource.lastCommit + lastSyncedAt (atomic)
+#
+# Safe to re-run — placeholder transforms are idempotent. REVIEW_CHECKLIST.md
+# is preserved (never in the import output set).
+#
+# Usage:
+#   ./sync-figma-source.sh [--plan] [--dry-run] [--force-full]
+#
+#   --plan         Emit a structured JSON sync plan + human-readable summary.
+#                  Writes nothing. Use this before approving an upstream sync
+#                  so the v5 structure (local overlays, renames, figma-common
+#                  extraction) is inspected before it's touched.
+#   --dry-run      Same as --plan but just logs, no JSON artifact.
+#   --force-full   Re-import every skill (same as running import-figma-skills.sh).
+
+set -euo pipefail
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+ROOT="$(cd "$HERE/../.." && pwd)"
+PREFS_FILE="${MULTI_AGENT_PREFS:-$HOME/.claude/multi-agent-preferences.json}"
+IMPORT="$HERE/import-figma-skills.sh"
+TARGET="$ROOT/pipeline/skills/figma-ios"
+
+DRY_RUN="false"
+FORCE_FULL="false"
+PLAN="false"
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --plan)       PLAN="true"; DRY_RUN="true"; shift ;;
+    --dry-run)    DRY_RUN="true"; shift ;;
+    --force-full) FORCE_FULL="true"; shift ;;
+    *) echo "error: unknown arg '$1'" >&2; exit 1 ;;
+  esac
+done
+
+need() { command -v "$1" >/dev/null 2>&1 || { echo "error: $1 required" >&2; exit 127; }; }
+need jq
+need git
+
+if [ ! -f "$PREFS_FILE" ]; then
+  echo "error: prefs file not found at $PREFS_FILE (run /multi-agent:setup first)" >&2
+  exit 1
+fi
+
+SRC_PATH=$(jq -r '.global.figmaSource.path // empty' "$PREFS_FILE")
+SRC_BRANCH=$(jq -r '.global.figmaSource.branch // "develop"' "$PREFS_FILE")
+LAST_COMMIT=$(jq -r '.global.figmaSource.lastCommit // empty' "$PREFS_FILE")
+
+if [ -z "$SRC_PATH" ]; then
+  echo "→ figmaSource not configured in prefs — skipping sync."
+  echo "  To enable: set prefs.global.figmaSource.path to the upstream repo."
+  exit 0
+fi
+if [ ! -d "$SRC_PATH" ]; then
+  echo "error: figmaSource.path does not exist: $SRC_PATH" >&2
+  exit 1
+fi
+
+echo "→ syncing from $SRC_PATH (branch $SRC_BRANCH)"
+
+# Fetch + checkout quietly
+git -C "$SRC_PATH" fetch --quiet origin "$SRC_BRANCH" 2>/dev/null || {
+  echo "  ⚠ fetch failed, proceeding with local state"
+}
+git -C "$SRC_PATH" checkout --quiet "$SRC_BRANCH" 2>/dev/null || true
+
+NEW_COMMIT=$(git -C "$SRC_PATH" rev-parse HEAD)
+echo "  new commit: $NEW_COMMIT"
+if [ -n "$LAST_COMMIT" ]; then
+  echo "  last commit: $LAST_COMMIT"
+  if [ "$LAST_COMMIT" = "$NEW_COMMIT" ] && [ "$FORCE_FULL" != "true" ]; then
+    echo "→ already at tip — nothing to sync."
+    exit 0
+  fi
+fi
+
+# Determine which skills changed
+CHANGED_SKILLS=()
+if [ "$FORCE_FULL" = "true" ] || [ -z "$LAST_COMMIT" ]; then
+  echo "  mode: FULL (no previous lastCommit or --force-full)"
+  # Enumerate all skills under .instructions/figma/
+  while IFS= read -r d; do
+    CHANGED_SKILLS+=("$(basename "$d")")
+  done < <(find "$SRC_PATH/.instructions/figma" -maxdepth 1 -mindepth 1 -type d | sort)
+else
+  echo "  mode: INCREMENTAL (diff $LAST_COMMIT..$NEW_COMMIT)"
+  # Extract skill names from changed paths under .instructions/figma/{skill}/...
+  while IFS= read -r f; do
+    # f looks like ".instructions/figma/figma-to-swiftui/phases/phase-0-init.md"
+    name=$(echo "$f" | awk -F/ '{print $3}')
+    [ -n "$name" ] && CHANGED_SKILLS+=("$name")
+  done < <(git -C "$SRC_PATH" diff --name-only "$LAST_COMMIT..$NEW_COMMIT" -- ".instructions/figma/" 2>/dev/null || true)
+  # dedupe
+  if [ "${#CHANGED_SKILLS[@]}" -gt 0 ]; then
+    CHANGED_SKILLS=($(printf '%s\n' "${CHANGED_SKILLS[@]}" | sort -u))
+  fi
+fi
+
+if [ "${#CHANGED_SKILLS[@]}" -eq 0 ]; then
+  echo "→ no skill changes since lastCommit — updating watermark only."
+else
+  echo "  skills to sync: ${#CHANGED_SKILLS[@]}"
+  printf '    - %s\n' "${CHANGED_SKILLS[@]}"
+fi
+
+if [ "$PLAN" = "true" ]; then
+  # Emit a structured JSON plan so a reviewer (human or LLM) can inspect
+  # what will change before we touch anything. Key invariants the v5
+  # structure must preserve:
+  #   - figma-ios/ holds only 5 platform-specific skills
+  #   - figma-common/ holds everything else
+  #   - skills with `local-overlay: true` are SKIPPED on apply
+  #   - figma-android/ is untouched (no upstream source today)
+  IOS_ONLY_SET=(figma-to-component figma-component-implement figma-component-test figma-component-code-connect figma-component-wiki)
+  is_ios_only() {
+    local name="$1"
+    for o in "${IOS_ONLY_SET[@]}"; do [ "$name" = "$o" ] && return 0; done
+    return 1
+  }
+
+  PLAN_OUT="$ROOT/pipeline/scripts/.last-figma-sync-plan.json"
+  {
+    echo "{"
+    echo "  \"source\": { \"path\": \"$SRC_PATH\", \"branch\": \"$SRC_BRANCH\", \"commit\": \"$NEW_COMMIT\", \"lastCommit\": \"$LAST_COMMIT\" },"
+    echo "  \"summary\": { \"changedSkills\": ${#CHANGED_SKILLS[@]} },"
+    echo "  \"changes\": ["
+    first=1
+    for skill in "${CHANGED_SKILLS[@]}"; do
+      # Rename lookup
+      new_name=$(jq -r --arg s "$skill" '.renames[] | select(.from == $s) | .to' "$HERE/figma-placeholder-map.json")
+      [ -z "$new_name" ] && new_name="$skill"
+      # Destination tree
+      dest=$(is_ios_only "$new_name" && echo "figma-ios" || echo "figma-common")
+      # Overlay detection — if skill has local-overlay: true, it's SKIPPED on apply
+      overlay_skip="false"
+      if [ -f "$ROOT/pipeline/skills/$dest/$new_name/SKILL.md" ] && grep -q "^local-overlay: true" "$ROOT/pipeline/skills/$dest/$new_name/SKILL.md" 2>/dev/null; then
+        overlay_skip="true"
+      fi
+      [ "$first" -eq 1 ] && first=0 || echo ","
+      printf '    { "upstream": "%s", "local": "%s", "tree": "%s", "renamed": %s, "overlaySkip": %s }' \
+        "$skill" "$new_name" "$dest" "$([ "$skill" != "$new_name" ] && echo true || echo false)" "$overlay_skip"
+    done
+    echo ""
+    echo "  ],"
+    echo "  \"postActions\": ["
+    echo "    \"run \`npm run test:smoke\` — all 28 suites must stay green\","
+    echo "    \"review figma-ios/REVIEW_CHECKLIST.md for skills still WIP\","
+    echo "    \"commit with \\\"chore(sync): upstream @ $NEW_COMMIT\\\"\""
+    echo "  ]"
+    echo "}"
+  } > "$PLAN_OUT"
+
+  echo ""
+  echo "→ Plan written to: $PLAN_OUT"
+  echo "→ Summary:"
+  jq -r '
+    "  " + (.summary.changedSkills | tostring) + " skill changes since " + (.source.lastCommit // "first-sync"),
+    "",
+    "  Changes:",
+    (.changes[] | "    - " + .upstream + (if .renamed then " → " + .local else "" end) + " → " + .tree + (if .overlaySkip then "  (OVERLAY — skip on apply)" else "" end))
+  ' "$PLAN_OUT"
+  echo ""
+  echo "→ To apply: re-run without --plan:"
+  echo "    bash $0"
+  exit 0
+fi
+
+if [ "$DRY_RUN" = "true" ]; then
+  echo "→ DRY RUN — no changes written."
+  exit 0
+fi
+
+# Delegate to the importer. Current importer re-runs against all skills,
+# which is safe (idempotent transforms). When --only is added to the
+# importer (follow-up), this invocation switches to per-skill.
+if [ "${#CHANGED_SKILLS[@]}" -gt 0 ]; then
+  FIGMA_SOURCE="$SRC_PATH" bash "$IMPORT" >/dev/null
+  echo "  ✓ imported ${#CHANGED_SKILLS[@]} skills"
+fi
+
+# CHANGELOG append
+CHANGELOG="$ROOT/CHANGELOG.md"
+if [ -f "$CHANGELOG" ]; then
+  TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+  {
+    echo ""
+    echo "### Sync $(date -u +"%Y-%m-%d") (@ $NEW_COMMIT) — figma source"
+    echo ""
+    if [ "${#CHANGED_SKILLS[@]}" -eq 0 ]; then
+      echo "- no skill changes"
+    else
+      for s in "${CHANGED_SKILLS[@]}"; do
+        echo "- updated \`$s\`"
+      done
+    fi
+  } > /tmp/sync-figma-note.md
+  # Insert after "## [Unreleased]" line
+  awk -v note_file="/tmp/sync-figma-note.md" '
+    BEGIN { while ((getline line < note_file) > 0) note = note "\n" line }
+    /^## \[Unreleased\]/ && !done { print; print note; done=1; next }
+    { print }
+  ' "$CHANGELOG" > "$CHANGELOG.tmp"
+  mv "$CHANGELOG.tmp" "$CHANGELOG"
+  rm -f /tmp/sync-figma-note.md
+  echo "  ✓ CHANGELOG updated"
+fi
+
+# Update watermark (atomic rename)
+TMP=$(mktemp)
+jq --arg c "$NEW_COMMIT" --arg t "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+  '.global.figmaSource.lastCommit = $c | .global.figmaSource.lastSyncedAt = $t' \
+  "$PREFS_FILE" > "$TMP"
+mv "$TMP" "$PREFS_FILE"
+echo "  ✓ watermark updated (lastCommit=$NEW_COMMIT)"
+
+echo "→ sync complete."

package/pipeline/scripts/sync-parity-check.sh

@@ -0,0 +1,135 @@
+#!/usr/bin/env bash
+# sync-parity-check.sh — detect drift between two pipeline mirror trees.
+#
+# Use case: after editing the pipeline locally (e.g. ~/.claude/commands/multi-agent/),
+# verify that the open-source repo (~/multi-agent-pipeline/pipeline/) and the
+# Copilot mirror (~/.copilot/multi-agent/) are still byte-identical for the
+# files that should be shared.
+#
+# Why this exists:
+#   The sync-instructions skill is the official "copy from A to B" tool, but
+#   nothing currently catches drift if the user forgets to run it. This script
+#   is the watchdog — run it before committing or as part of a pre-push hook.
+#
+# Usage:
+#   sync-parity-check.sh <left-dir> <right-dir> [--ignore <regex>]...
+#
+# Examples:
+#   # Compare Claude personal copy vs. open-source repo:
+#   sync-parity-check.sh \
+#     ~/.claude/commands/multi-agent \
+#     ~/multi-agent-pipeline/pipeline/commands/multi-agent
+#
+#   # Compare Claude vs. Copilot mirrors, ignoring help.md if it intentionally
+#   # diverges:
+#   sync-parity-check.sh \
+#     ~/.claude/commands/multi-agent \
+#     ~/.copilot/multi-agent \
+#     --ignore '/help\.md$'
+#
+# Exit codes:
+#   0 — perfect parity (or only ignored files differ)
+#   1 — drift detected (lists differing + missing-from-each-side)
+#   2 — usage error
+
+set -uo pipefail
+
+if [ "$#" -lt 2 ]; then
+  echo "usage: sync-parity-check.sh <left-dir> <right-dir> [--ignore <regex>]..." >&2
+  exit 2
+fi
+
+LEFT="$1"; shift
+RIGHT="$1"; shift
+
+IGNORES=()
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --ignore)
+      IGNORES+=("$2"); shift 2 ;;
+    *)
+      echo "unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+[ -d "$LEFT"  ] || { echo "error: left dir not found: $LEFT"  >&2; exit 2; }
+[ -d "$RIGHT" ] || { echo "error: right dir not found: $RIGHT" >&2; exit 2; }
+
+# Resolve to absolute, normalized paths.
+LEFT="$(cd "$LEFT"  && pwd)"
+RIGHT="$(cd "$RIGHT" && pwd)"
+
+is_ignored() {
+  local rel="$1"
+  for pat in "${IGNORES[@]+"${IGNORES[@]}"}"; do
+    if [[ "$rel" =~ $pat ]]; then return 0; fi
+  done
+  return 1
+}
+
+# Collect file lists, relative to each root.
+LEFT_FILES=$(cd "$LEFT" && find . -type f | sort)
+RIGHT_FILES=$(cd "$RIGHT" && find . -type f | sort)
+
+# Files only on one side.
+ONLY_LEFT=$(comm -23 <(echo "$LEFT_FILES") <(echo "$RIGHT_FILES"))
+ONLY_RIGHT=$(comm -13 <(echo "$LEFT_FILES") <(echo "$RIGHT_FILES"))
+COMMON=$(comm -12 <(echo "$LEFT_FILES") <(echo "$RIGHT_FILES"))
+
+# Report and tally.
+DRIFT=0
+MISSING_RIGHT=0
+MISSING_LEFT=0
+DIFFERS=0
+IGNORED=0
+
+# Files only on the LEFT (missing from RIGHT).
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  rel="${f#./}"
+  if is_ignored "$rel"; then IGNORED=$((IGNORED+1)); continue; fi
+  echo "MISSING-FROM-RIGHT  $rel"
+  MISSING_RIGHT=$((MISSING_RIGHT+1))
+  DRIFT=1
+done <<< "$ONLY_LEFT"
+
+# Files only on the RIGHT (missing from LEFT).
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  rel="${f#./}"
+  if is_ignored "$rel"; then IGNORED=$((IGNORED+1)); continue; fi
+  echo "MISSING-FROM-LEFT   $rel"
+  MISSING_LEFT=$((MISSING_LEFT+1))
+  DRIFT=1
+done <<< "$ONLY_RIGHT"
+
+# Files present on both sides — content compare.
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  rel="${f#./}"
+  if is_ignored "$rel"; then IGNORED=$((IGNORED+1)); continue; fi
+  if ! diff -q "$LEFT/$rel" "$RIGHT/$rel" >/dev/null 2>&1; then
+    echo "DIFFERS             $rel"
+    DIFFERS=$((DIFFERS+1))
+    DRIFT=1
+  fi
+done <<< "$COMMON"
+
+echo ""
+echo "── parity summary ──"
+echo "left:               $LEFT"
+echo "right:              $RIGHT"
+echo "files differ:       $DIFFERS"
+echo "missing from right: $MISSING_RIGHT"
+echo "missing from left:  $MISSING_LEFT"
+echo "ignored:            $IGNORED"
+
+if [ "$DRIFT" -eq 0 ]; then
+  echo "result:             PARITY"
+  exit 0
+else
+  echo "result:             DRIFT"
+  echo ""
+  echo "fix: run /sync-instructions full to bring mirrors back in sync." >&2
+  exit 1
+fi

package/pipeline/scripts/test-gap-rules/android.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "stack": "android",
+  "description": "Android / Jetpack Compose / Kotlin test gap rules. Sources in *.kt; tests under app/src/test/ or app/src/androidTest/.",
+  "sourceExtensions": [".kt", ".java"],
+  "testPathSuffixes": ["Test.kt", "Tests.kt", "Test.java"],
+  "testPathContains": ["/src/test/", "/src/androidTest/", "/test/", "/tests/"],
+  "excludePathGlobs": [
+    "build/", ".gradle/", "generated/",
+    "**/BuildConfig.java", "**/R.java"
+  ],
+  "publicApiPatterns": [
+    {"id": "open_class", "regex": "\\bopen\\s+class\\s+([A-Z][A-Za-z0-9_]*)"},
+    {"id": "open_fun",   "regex": "\\bopen\\s+fun\\s+([a-z_][A-Za-z0-9_]*)"},
+    {"id": "public_fun", "regex": "^\\s*(?:public\\s+)?fun\\s+([a-z_][A-Za-z0-9_]*)"},
+    {"id": "public_class", "regex": "^\\s*(?:public\\s+)?class\\s+([A-Z][A-Za-z0-9_]*)"},
+    {"id": "jvmstatic",  "regex": "@JvmStatic\\b"},
+    {"id": "interface",  "regex": "^\\s*(?:public\\s+)?interface\\s+([A-Z][A-Za-z0-9_]*)"}
+  ],
+  "composablePatterns": [
+    {"id": "composable_fun", "regex": "@Composable\\s+(?:public\\s+|internal\\s+)?fun\\s+([A-Z][A-Za-z0-9_]*)"}
+  ],
+  "expectedTestKindsForComposable": ["compose-ui-test"],
+  "hint": "Cover @Composable functions with createComposeRule() + onNodeWithText/Tag/ContentDescription assertions; ViewModels with runTest + Turbine."
+}

package/pipeline/scripts/test-gap-rules/ios.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "stack": "ios",
+  "description": "iOS / SwiftUI / UIKit test gap rules. Source files in *.swift; tests in *Tests.swift. Snapshot/ViewInspector tests are also recognised when the source is a SwiftUI View.",
+  "sourceExtensions": [".swift"],
+  "testPathSuffixes": ["Tests.swift", "Test.swift"],
+  "testPathContains": ["/Tests/", "/UnitTests/", "/SnapshotTests/"],
+  "excludePathGlobs": [
+    "Pods/", "Carthage/", ".build/", "DerivedData/",
+    "Generated/", "Sourcery/", "_Generated.swift",
+    "Tests/Fixtures/"
+  ],
+  "publicApiPatterns": [
+    {"id": "public_func",   "regex": "\\bpublic\\s+func\\s+([A-Za-z_][A-Za-z0-9_]*)"},
+    {"id": "public_class",  "regex": "\\bpublic\\s+(?:final\\s+)?class\\s+([A-Z][A-Za-z0-9_]*)"},
+    {"id": "public_struct", "regex": "\\bpublic\\s+struct\\s+([A-Z][A-Za-z0-9_]*)"},
+    {"id": "public_enum",   "regex": "\\bpublic\\s+enum\\s+([A-Z][A-Za-z0-9_]*)"},
+    {"id": "public_proto",  "regex": "\\bpublic\\s+protocol\\s+([A-Z][A-Za-z0-9_]*)"},
+    {"id": "public_init",   "regex": "\\bpublic\\s+init\\b"},
+    {"id": "objc_export",   "regex": "@objc(?:Members)?\\s+(?:public\\s+)?(?:func|class|var)"}
+  ],
+  "swiftUiViewPatterns": [
+    {"id": "view_struct",     "regex": "struct\\s+([A-Z][A-Za-z0-9_]*)\\s*:\\s*View\\b"},
+    {"id": "config_struct",   "regex": "struct\\s+([A-Z][A-Za-z0-9_]*Configuration)\\b"}
+  ],
+  "expectedTestKindsForView": ["snapshot", "viewinspector", "unit"],
+  "snapshotPathHints": ["SnapshotTests", "__Snapshots__"],
+  "hint": "Cover with a 3-layer test (structural ViewInspector + snapshot + unit) per swiftui-qa.md."
+}

package/pipeline/scripts/test-gap-rules/node.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "stack": "node",
+  "description": "Node.js / TypeScript test gap rules. Sources in *.ts/*.tsx/*.js/*.mjs; tests in *.test.* / *.spec.* / __tests__/.",
+  "sourceExtensions": [".ts", ".tsx", ".js", ".mjs", ".cjs"],
+  "testPathSuffixes": [".test.ts", ".test.tsx", ".test.js", ".test.mjs", ".spec.ts", ".spec.tsx", ".spec.js", ".spec.mjs"],
+  "testPathContains": ["/__tests__/", "/test/", "/tests/"],
+  "excludePathGlobs": [
+    "node_modules/", "dist/", "build/", ".next/", "coverage/",
+    "*.d.ts"
+  ],
+  "publicApiPatterns": [
+    {"id": "named_export",   "regex": "^export\\s+(?:async\\s+)?(?:function|class|const|let|interface|type|enum)\\s+([A-Za-z_$][A-Za-z0-9_$]*)"},
+    {"id": "default_export", "regex": "^export\\s+default\\s+(?:async\\s+)?(?:function|class)\\s+([A-Za-z_$][A-Za-z0-9_$]*)"}
+  ],
+  "hint": "Cover named exports with vitest/jest test('<name>', ...). React components: React Testing Library (render + screen + userEvent)."
+}

package/pipeline/scripts/test-gap-rules/python.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "stack": "python",
+  "description": "Python test gap rules. Sources in *.py; tests in test_*.py / *_test.py / tests/.",
+  "sourceExtensions": [".py"],
+  "testPathSuffixes": ["_test.py"],
+  "testPathPrefixes": ["test_"],
+  "testPathContains": ["/tests/", "/test/"],
+  "excludePathGlobs": [
+    "__pycache__/", ".venv/", "venv/", ".tox/", "build/", "dist/", "*.egg-info/",
+    "**/migrations/**"
+  ],
+  "publicApiPatterns": [
+    {"id": "top_def",   "regex": "^def\\s+([a-z_][a-z0-9_]*)"},
+    {"id": "top_class", "regex": "^class\\s+([A-Z][A-Za-z0-9_]*)"},
+    {"id": "async_def", "regex": "^async\\s+def\\s+([a-z_][a-z0-9_]*)"}
+  ],
+  "hint": "Cover with pytest test_<symbol> style. Async with pytest-asyncio. Avoid name collision with private helpers (prefix _)."
+}