@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/schemas/figma-project-config.schema.json

@@ -0,0 +1,372 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/figma-project-config.schema.json",
+  "title": "Figma Project Configuration",
+  "description": "Per-project Figma pipeline configuration. Stored at ~/.claude/projects/{slug}/figma-config.json. Never committed. v2.0.0 introduces platform-agnostic sections (github, jira, build, teams, wiki.mode) for the v5.0.0 generic rebuild; v1.0.0 docs live in the 3.x branch.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "project"],
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "const": "2.0.0"
+    },
+    "project": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["slug"],
+      "description": "Project identification.",
+      "properties": {
+        "slug": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9\\-_]*$",
+          "description": "Unique project slug."
+        },
+        "repoOwner": { "type": "string" },
+        "repoName": { "type": "string" },
+        "baseBranch": { "type": "string", "default": "develop" },
+        "platform": {
+          "type": "string",
+          "enum": ["ios", "android", "web", "multiplatform"],
+          "default": "ios",
+          "description": "Target platform. Drives code-generation templates and test framework selection."
+        }
+      }
+    },
+    "figma": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Figma API configuration.",
+      "properties": {
+        "fileKey": { "type": "string" },
+        "patKeychainKey": {
+          "type": "string",
+          "description": "macOS Keychain item name for Figma PAT. Resolved via `security find-generic-password -s <value> -w`."
+        },
+        "mcpEnabled": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether Figma MCP server is available."
+        }
+      }
+    },
+    "github": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "GitHub configuration — repo handle + Projects V2 board metadata. Required for automatic issue + Jira triad.",
+      "properties": {
+        "repo": {
+          "type": "string",
+          "pattern": "^[^/]+/[^/]+$",
+          "description": "`{owner}/{name}` handle."
+        },
+        "org": { "type": "string" },
+        "projectV2Id": {
+          "type": ["string", "null"],
+          "description": "GitHub Projects V2 node ID (PVT_*)."
+        },
+        "projectV2Fields": {
+          "type": "object",
+          "additionalProperties": { "type": "string" },
+          "description": "Logical name → Projects V2 field ID. Common keys: status, phase, figmaPage, jira."
+        },
+        "fieldOptions": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": { "type": "string" }
+          },
+          "description": "Single-select field option mapping. Key = field logical name, inner map = option label → option ID. Commonly used for figmaPage."
+        }
+      }
+    },
+    "jira": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Jira configuration. Required for the issue → jira → wiki triad.",
+      "properties": {
+        "baseUrl": {
+          "type": "string",
+          "format": "uri",
+          "description": "Jira instance URL, e.g. https://jira.company.com."
+        },
+        "projectKey": {
+          "type": "string",
+          "pattern": "^[A-Z][A-Z0-9_]*$",
+          "description": "Jira project key, e.g. ABC."
+        },
+        "defaultIssue": {
+          "type": ["string", "null"],
+          "description": "Fallback Jira issue key for rework or unassigned work."
+        },
+        "teamFieldId": {
+          "type": ["string", "null"],
+          "description": "Custom field ID for team assignment. Discovered via `/field` API; cached here."
+        },
+        "keychainKey": {
+          "type": "string",
+          "description": "Keychain item name for Jira token. Falls back to `prefs.global.keychainMapping.jira`."
+        }
+      }
+    },
+    "confluence": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Confluence sync. Optional.",
+      "properties": {
+        "enabled": { "type": "boolean", "default": false },
+        "baseUrl": { "type": ["string", "null"], "format": "uri" },
+        "spaceKey": { "type": ["string", "null"] },
+        "parentPageId": { "type": ["string", "null"] },
+        "dashboardPageId": {
+          "type": ["string", "null"],
+          "description": "Status dashboard page ID, updated by status-page generator."
+        },
+        "keychainKey": { "type": "string" }
+      }
+    },
+    "repos": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Repository / submodule layout. Supersedes the v1 `submodules` field with role-based semantics. Paths relative to project root.",
+      "properties": {
+        "main": {
+          "type": ["object", "null"],
+          "additionalProperties": false,
+          "properties": {
+            "path": { "type": "string", "default": "." },
+            "branch": { "type": "string", "default": "develop" },
+            "role": { "type": "string", "enum": ["main"], "default": "main" }
+          }
+        },
+        "common": {
+          "type": ["object", "null"],
+          "additionalProperties": false,
+          "properties": {
+            "path": { "type": "string" },
+            "branch": { "type": "string", "default": "develop" },
+            "role": { "type": "string", "enum": ["common"], "default": "common" }
+          }
+        },
+        "components": {
+          "type": ["object", "null"],
+          "additionalProperties": false,
+          "description": "Components repo (iOS uicomponents, Android ui-components, etc).",
+          "properties": {
+            "path": { "type": "string" },
+            "branch": { "type": "string", "default": "develop" },
+            "role": { "type": "string", "enum": ["components"], "default": "components" }
+          }
+        },
+        "wiki": {
+          "type": ["object", "null"],
+          "additionalProperties": false,
+          "description": "Wiki repo when `wiki.mode = separate-repo` or `submodule`.",
+          "properties": {
+            "path": { "type": "string" },
+            "branch": { "type": "string", "default": "master" },
+            "role": { "type": "string", "enum": ["wiki"], "default": "wiki" }
+          }
+        },
+        "artifactsRepo": {
+          "type": ["string", "null"],
+          "description": "Relative path (inside packagesContainer or repo root) to the implementation-artifacts submodule/folder — holds IMPLEMENTATION_HISTORY.md and Figma/Confluence per-component trees. Null = feature disabled.",
+          "examples": ["Packages/my-ios-implementation-artifacts", "artifacts"]
+        },
+        "packagesContainer": {
+          "type": ["string", "null"],
+          "description": "Root directory under which submodule packages (components, common, wiki, artifactsRepo) are nested. Null when repos are siblings of the main repo.",
+          "examples": ["MyAppPackages", "Packages"]
+        }
+      }
+    },
+    "build": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Build configuration. Fields used depend on `project.platform`.",
+      "properties": {
+        "xcodeproj": { "type": "string", "description": "iOS only." },
+        "scheme": { "type": "string", "description": "iOS only." },
+        "destination": {
+          "type": "string",
+          "description": "iOS only. Default `generic/platform=iOS`."
+        },
+        "gradleModule": { "type": "string", "description": "Android only." },
+        "variant": { "type": "string", "description": "Android only." },
+        "buildType": { "type": "string", "description": "Android only." }
+      }
+    },
+    "artifactBasePath": {
+      "type": "string",
+      "default": "ImplementationArtifacts/Figma/Components",
+      "description": "Base path for per-component generated artifacts (specs, pass-N notes, screenshots)."
+    },
+    "tokens": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Design token mapping.",
+      "properties": {
+        "spacing": { "type": "string", "default": ".Spacing.spacing{value}" },
+        "color": { "type": "string", "default": "Color.{semantic}" },
+        "typography": { "type": "string", "default": ".typographyStyle(.{name})" },
+        "radius": { "type": "string", "default": ".CornerRadius.radius{value}" },
+        "registryPath": {
+          "type": ["string", "null"],
+          "description": "Path to token registry JSON (e.g. ui-token-registry.json)."
+        },
+        "colorsGlob": {
+          "type": ["string", "null"],
+          "description": "Glob pattern for color JSON files (e.g. Shared/UIAssets/Colors/*.json)."
+        },
+        "typographyPath": {
+          "type": ["string", "null"],
+          "description": "Path to typography JSON file."
+        }
+      }
+    },
+    "teams": {
+      "type": "array",
+      "description": "Team definitions. Each entry maps a logical team to a GitHub label and a Jira custom-field value.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["key", "label"],
+        "properties": {
+          "key": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_\\-]*$" },
+          "label": { "type": "string", "description": "GitHub label, e.g. team:core." },
+          "jiraValue": { "type": ["string", "null"] }
+        }
+      }
+    },
+    "board": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Legacy board section. Superseded by `github.projectV2*` for Projects V2 users. Retained for backward-compat with `github-labels-only` and `none` providers.",
+      "properties": {
+        "enabled": { "type": "boolean", "default": false },
+        "provider": {
+          "type": "string",
+          "enum": ["github-projects-v2", "github-labels-only", "none"],
+          "default": "none"
+        },
+        "projectId": { "type": "string" },
+        "columns": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "todo": { "type": "string", "default": "Todo" },
+            "inDevelop": { "type": "string", "default": "In Develop" },
+            "inReview": { "type": "string", "default": "In Review" },
+            "done": { "type": "string", "default": "Done" },
+            "blocked": { "type": "string", "default": "Blocked" },
+            "bugfix": { "type": "string", "default": "Bugfix" },
+            "stale": { "type": "string", "default": "Stale" }
+          }
+        },
+        "customFields": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        }
+      }
+    },
+    "registry": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Component registry configuration.",
+      "properties": {
+        "enabled": { "type": "boolean", "default": false },
+        "type": {
+          "type": "string",
+          "enum": ["swift-cli", "json-file", "none"],
+          "default": "none"
+        },
+        "cliName": { "type": "string" },
+        "packagePath": { "type": "string" },
+        "registryPath": { "type": "string" }
+      }
+    },
+    "review": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "requiredApprovals": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 10,
+          "default": 0
+        },
+        "reviewers": {
+          "type": "array",
+          "items": { "type": "string" },
+          "maxItems": 10
+        },
+        "autoAssign": { "type": "boolean", "default": false }
+      }
+    },
+    "iteration": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "branch": { "type": "string", "default": "iteration/develop" },
+        "batchSize": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 50,
+          "default": 5
+        }
+      }
+    },
+    "wiki": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Wiki generation settings. v2.0.0 introduces `mode` with four adapters; legacy v1 projects using `submodules.wiki` are migrated to `mode: submodule`.",
+      "properties": {
+        "enabled": { "type": "boolean", "default": false },
+        "mode": {
+          "type": "string",
+          "enum": ["submodule", "in-repo", "github-wiki", "separate-repo"],
+          "default": "in-repo",
+          "description": "submodule: git submodule at repos.wiki.path. in-repo: folder inside main repo (relPath). github-wiki: GitHub's wiki feature on the components repo. separate-repo: standalone clone at url."
+        },
+        "relPath": {
+          "type": ["string", "null"],
+          "description": "Used by `in-repo` mode (default `.wiki/components/`) and as fallback for other modes."
+        },
+        "url": {
+          "type": ["string", "null"],
+          "description": "Used by `separate-repo` mode — clone URL."
+        },
+        "branch": {
+          "type": ["string", "null"],
+          "description": "Branch for submodule or separate-repo mode."
+        },
+        "categoryMapping": {
+          "type": "string",
+          "enum": ["auto", "flat"],
+          "default": "auto"
+        }
+      }
+    },
+    "scripts": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "pythonPath": { "type": "string", "default": "python3" },
+        "preGather": { "type": ["string", "null"] },
+        "postCommit": { "type": ["string", "null"] }
+      }
+    },
+    "models": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "default": { "type": "string", "default": "sonnet" },
+        "complex": { "type": "string", "default": "opus" },
+        "overrides": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/pipeline/schemas/migrations/README.md

@@ -0,0 +1,73 @@
+# State + Preferences Migrations
+
+When the schema changes on breaking minor/major bumps, JSON state files
+written by the previous version must be migrated forward. This directory
+holds the transform scripts that do that job.
+
+## How It Works
+
+Each migration is a `.mjs` file named `{type}-{from}-to-{to}.mjs` where:
+
+- `type` is `state` or `prefs`
+- `from` is the version the file is expected to already be at
+- `to` is the version it will be at after running
+
+Example: `state-2.0.0-to-3.0.0.mjs` migrates `agent-state.json` from
+`schemaVersion: "2.0.0"` to `"3.0.0"`.
+
+Every migration exports a single default function:
+
+```js
+// state-2.0.0-to-3.0.0.mjs
+export default function migrate(state) {
+  // state is a parsed object conforming to the 2.0.0 schema
+  // Return a new object conforming to the 3.0.0 schema.
+  return {
+    ...state,
+    schemaVersion: "3.0.0",
+    // new field added in 3.0.0
+    newField: "default-value",
+    // ...
+  };
+}
+```
+
+## Running Migrations
+
+```bash
+# Auto-detect current version, apply the chain up to latest
+node pipeline/scripts/migrate-state.mjs \
+  /Users/me/.claude/logs/multi-agent/my-project/PROJ-123/agent-state.json
+
+# Preview what would change (no write)
+node pipeline/scripts/migrate-state.mjs --dry-run <path>
+
+# Migrate a preferences file
+node pipeline/scripts/migrate-state.mjs --type=prefs \
+  ~/.claude/multi-agent-preferences.json
+```
+
+Migrations are **always applied in order**. If a state is at 2.0.0 and the
+current schema is 4.0.0, the runner applies 2→3 then 3→4 sequentially.
+Partial chains are not allowed — all versions in between must have
+migrations committed.
+
+## Current State
+
+- `state` schema version: `2.0.0` (no migrations yet)
+- `prefs` schema version: `2.0.0` (no migrations yet)
+
+First breaking schema change will land its migration here. The pattern and
+runner are pre-wired so the change is mechanical: drop the file in, bump the
+target schema's `const`, done.
+
+## Guidelines for Authors
+
+- Keep each migration pure — no fs / network / random. Same input must produce
+  same output so replaying is idempotent.
+- Always write the `schemaVersion` in the returned object.
+- Never delete user data silently. If a field is removed, either copy it
+  into an `_archived` field or document its disappearance in the migration
+  header comment.
+- Ship a test fixture in `pipeline/schemas/migrations/fixtures/` showing
+  before/after for a realistic state.

package/pipeline/schemas/migrations/figma-config-1.0.0-to-2.0.0.mjs

@@ -0,0 +1,112 @@
+// figma-config-1.0.0-to-2.0.0.mjs
+// Migrates a v1.0.0 figma-project-config.json to the v2.0.0 shape introduced
+// in the v5.0.0 rebuild. Idempotent, atomic (callers pick up the returned
+// object and write via rename). No network calls, no filesystem side-effects.
+
+export const fromVersion = "1.0.0";
+export const toVersion = "2.0.0";
+
+export function migrate(prev) {
+  if (!prev || typeof prev !== "object") {
+    throw new Error("figma-config migration input is not an object");
+  }
+
+  // Shallow clone; we rebuild structure explicitly so the output order stays stable.
+  const next = {
+    schemaVersion: "2.0.0",
+    project: { ...(prev.project ?? {}) },
+  };
+
+  if (prev.figma) next.figma = { ...prev.figma };
+
+  // github — new top-level; may already be partially present if the user hand-edited.
+  if (prev.github) {
+    next.github = { ...prev.github };
+  }
+
+  // Board provider "github-projects-v2" → lift projectId + customFields into github.projectV2*.
+  if (prev.board?.provider === "github-projects-v2") {
+    next.github = next.github ?? {};
+    if (prev.board.projectId && !next.github.projectV2Id) {
+      next.github.projectV2Id = prev.board.projectId;
+    }
+    if (
+      prev.board.customFields &&
+      !next.github.projectV2Fields
+    ) {
+      next.github.projectV2Fields = { ...prev.board.customFields };
+    }
+  }
+  // Retain `board` for backward-compat (labels-only / none users unaffected).
+  if (prev.board) next.board = { ...prev.board };
+
+  // jira, confluence — pass through if present.
+  if (prev.jira) next.jira = { ...prev.jira };
+  if (prev.confluence) next.confluence = { ...prev.confluence };
+
+  // repos: build from legacy `submodules`. v1 shape mapped one-to-one.
+  if (prev.submodules) {
+    next.repos = next.repos ?? {};
+    if (prev.submodules.common) {
+      next.repos.common = {
+        path: prev.submodules.common.path,
+        branch: prev.submodules.common.branch ?? "develop",
+        role: "common",
+      };
+    }
+    if (prev.submodules.uicomponents) {
+      next.repos.components = {
+        path: prev.submodules.uicomponents.path,
+        branch: prev.submodules.uicomponents.branch ?? "develop",
+        role: "components",
+      };
+    }
+    if (prev.submodules.wiki) {
+      next.repos.wiki = {
+        path: prev.submodules.wiki.path,
+        branch: prev.submodules.wiki.branch ?? "master",
+        role: "wiki",
+      };
+    }
+  }
+  // If caller already wrote a v2-shaped repos, preserve it.
+  if (prev.repos) {
+    next.repos = { ...(next.repos ?? {}), ...prev.repos };
+  }
+
+  // build — new in v2; pass through if hand-added.
+  if (prev.build) next.build = { ...prev.build };
+
+  // artifactBasePath, tokens, teams — pass through.
+  if (prev.artifactBasePath) next.artifactBasePath = prev.artifactBasePath;
+  if (prev.tokens) next.tokens = { ...prev.tokens };
+  if (prev.teams) next.teams = [...prev.teams];
+
+  // registry, review, iteration, scripts, models — pass through unchanged.
+  for (const key of ["registry", "review", "iteration", "scripts", "models"]) {
+    if (prev[key]) next[key] = JSON.parse(JSON.stringify(prev[key]));
+  }
+
+  // wiki: derive v2 `mode` from v1 state.
+  // Heuristic:
+  //   - v1 `submodules.wiki` present → mode = submodule
+  //   - v1 `wiki.enabled=true` with no submodule → mode = in-repo
+  //   - else default in-repo (mode is pure metadata; safe default)
+  const v2wiki = { ...(prev.wiki ?? {}) };
+  if (!v2wiki.mode) {
+    if (prev.submodules?.wiki) {
+      v2wiki.mode = "submodule";
+      v2wiki.branch = v2wiki.branch ?? prev.submodules.wiki.branch ?? "master";
+    } else {
+      v2wiki.mode = "in-repo";
+    }
+  }
+  if (v2wiki.mode === "in-repo" && !v2wiki.relPath) {
+    v2wiki.relPath = ".wiki/components";
+  }
+  if (Object.keys(v2wiki).length > 0) next.wiki = v2wiki;
+
+  return next;
+}
+
+export default migrate;

package/pipeline/schemas/migrations/prefs-2.0.0-to-2.1.0.mjs

@@ -0,0 +1,75 @@
+/**
+ * prefs-2.0.0-to-2.1.0.mjs — preference migration (delegates to migrate-prefs.mjs)
+ *
+ * This stub satisfies the generic migrate-state.mjs runner's migration-chain
+ * discovery. The actual migration logic lives in scripts/migrate-prefs.mjs
+ * (which is richer, handles firebase consolidation, and is idempotent).
+ *
+ * @param {object} data — parsed JSON content of the preferences file
+ * @returns {object}    — migrated data with schemaVersion set to "2.1.0"
+ */
+export default function migrate(data) {
+  // Delegate to the same logic as migrate-prefs.mjs inline:
+  const out = JSON.parse(JSON.stringify(data));
+
+  out.schemaVersion = "2.1.0";
+
+  if (!out.global) out.global = {};
+
+  // gitIdentities → identities
+  if (Array.isArray(out.global.gitIdentities) && !Array.isArray(out.global.identities)) {
+    out.global.identities = out.global.gitIdentities;
+  }
+  delete out.global.gitIdentities;
+  if (!Array.isArray(out.global.identities)) out.global.identities = [];
+
+  // keychainMapping defaults (10 services)
+  const kmDefaults = {
+    jira: null, bitbucket_token: null, bitbucket_user: null, github: null,
+    confluence: null, figma: null, figma_mcp: null,
+    fortify: null, firebase: null, jenkins: null,
+  };
+  const km = out.global.keychainMapping || {};
+  for (const [k, v] of Object.entries(kmDefaults)) {
+    if (!(k in km)) km[k] = v;
+  }
+  // firebase consolidation
+  if ("firebase_sa" in km) {
+    if (km.firebase == null && km.firebase_sa != null) km.firebase = km.firebase_sa;
+    delete km.firebase_sa;
+  }
+  if ("firebase_project" in km) delete km.firebase_project;
+  // figma consolidation: figma_pat → figma, remove figma_user
+  if ("figma_pat" in km) {
+    if (km.figma == null && km.figma_pat != null) km.figma = km.figma_pat;
+    delete km.figma_pat;
+  }
+  if ("figma_user" in km) delete km.figma_user;
+  out.global.keychainMapping = km;
+
+  // v2.1.0 defaults
+  if (!out.global.platformIdentityRouting) out.global.platformIdentityRouting = {};
+  if (!Array.isArray(out.global.recentProjects)) out.global.recentProjects = [];
+  if (!out.global.recentBranches) out.global.recentBranches = {};
+  if (!Array.isArray(out.global.recentGroups)) out.global.recentGroups = [];
+  if (!out.global.serviceStatus) out.global.serviceStatus = {};
+  if (!out.global.settings) {
+    out.global.settings = {
+      branchTtlDays: 15, pushRetryMax: 5, buildRetryMax: 3,
+      serviceStatusCacheSeconds: 300, repoScanDays: 90,
+      identityRoutingEnabled: false, multiRepoEnabled: false, pushMustSucceed: true,
+    };
+  }
+  if (!out.global.triageCrossCheck) {
+    out.global.triageCrossCheck = { enabled: false, samplePct: 10, model: "sonnet", blockOnDisagreement: false };
+  }
+  if (!out.global.promptLanguage) out.global.promptLanguage = "en";
+
+  // prune obsolete
+  delete out.global.defaultPriority;
+  delete out.global.defaultIssueType;
+
+  if (!out.projects) out.projects = {};
+
+  return out;
+}