@mmerterden/multi-agent-pipeline 12.11.0 → 13.1.0

package/pipeline/schemas/reviewer-output.schema.json

@@ -3,7 +3,7 @@
   "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/reviewer-output.schema.json",
   "version": "1.0.0",
   "title": "Multi-Agent Pipeline  -  Phase 4 reviewer output",
-  "description": "Contract for a single code-reviewer subagent's JSON output in Phase 4 Step 2. Reviewer set is CLI-aware: Claude Code dispatches 2 parallel reviewers (Opus, Sonnet); Copilot CLI dispatches 3 (GPT-5.4, Opus, Sonnet). Every reviewer must return an object matching this shape before Opus triage merges them.",
+  "description": "Contract for a single code-reviewer subagent's JSON output in Phase 4 Step 2. Reviewer set is CLI-aware: Claude Code dispatches 2 parallel reviewers (Fable, Sonnet); Copilot CLI dispatches 3 (Opus, GPT-5.4, Sonnet); Codex CLI dispatches 3 (gpt-5.6 at xhigh, gpt-5.4, gpt-5.6 at medium). Every reviewer must return an object matching this shape before Opus triage merges them.",
   "type": "object",
   "additionalProperties": false,
   "required": ["findings", "approved"],

package/pipeline/schemas/triage-output.schema.json

@@ -86,7 +86,7 @@
         "reviewerCount": {
           "type": "integer",
           "minimum": 1,
-          "description": "Reviewers dispatched this iteration (Claude Code = 2, Copilot CLI = 3)."
+          "description": "Reviewers dispatched this iteration (Claude Code = 2, Copilot CLI = 3, Codex CLI = 3)."
         },
         "verdict": {
           "type": "string",

package/pipeline/scripts/cost-table.json

@@ -32,7 +32,21 @@
       "outPerMtok": 30.0,
       "cacheReadPerMtok": 1.0,
       "modelId": "gpt-5.4",
-      "note": "Copilot CLI Reviewer 2  -  approximate; verify against OpenAI pricing page before relying on totals."
+      "note": "Copilot CLI Reviewer 2 and Codex CLI Reviewer 2  -  approximate; verify against OpenAI pricing page before relying on totals."
+    },
+    "gpt-5.6": {
+      "inPerMtok": 10.0,
+      "outPerMtok": 30.0,
+      "cacheReadPerMtok": 1.0,
+      "modelId": "gpt-5.6",
+      "note": "Codex CLI top tier  -  Reviewer 1 at xhigh effort, Reviewer 3 at medium, triage at max, and the fable/opus rungs of the Codex persona tier map. Reasoning effort changes output volume, not the per-token rate, so one entry covers every effort level. Approximate; verify against OpenAI pricing before relying on totals."
+    },
+    "gpt-5.6-terra": {
+      "inPerMtok": 1.0,
+      "outPerMtok": 5.0,
+      "cacheReadPerMtok": 0.1,
+      "modelId": "gpt-5.6-terra",
+      "note": "Codex CLI floor tier  -  speed-optimised, maps the haiku rung of the Codex persona tier map (task-clarifier). Approximate; verify against OpenAI pricing before relying on totals."
     }
   }
 }

package/pipeline/scripts/phase0-exit-gate.mjs

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+/**
+ * phase0-exit-gate.mjs  -  Phase 0 may not be marked completed until it has
+ * actually produced its own output.
+ *
+ * Why this exists. Phase 0 Step 7 says to classify the task and "persist to
+ * `agent-state.json.taskType`", and Phase 3 branches on that field to route a
+ * Figma-driven task to the component skills (`create-screen` / `create-component`
+ * in the stack plugin) instead of generic development. On a real run the tracker
+ * showed Phase 0 `completed` while the task directory held only
+ * `tracker-state.json`  -  no `agent-state.json` at all. With no `taskType`, the
+ * dispatch could not fire, so a Figma-driven screen was built as generic work: no
+ * token-compliance check, no Code Connect publish, no 14-item component review,
+ * and spacing guessed at 16 where the frame said `Spacing/12`. Half the commits on
+ * that branch were rework.
+ *
+ * A phase that reports success without its output is worse than one that fails:
+ * every later phase then reasons from a field that is not there. So this is a
+ * gate, not a lint  -  the spec already said what to write, and prose alone did
+ * not make it happen.
+ *
+ * Usage:
+ *   node phase0-exit-gate.mjs <task_id> [--input "<original user input>"] [--json]
+ *
+ * Exit codes: 0 = pass, 1 = gate failure (Phase 0 must not be closed), 2 = usage
+ *
+ * @module pipeline/scripts/phase0-exit-gate
+ */
+
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+const FIGMA_URL = /figma\.com\/(design|make|file)\//i;
+
+/** Fields that can carry the user's original request text. */
+const INPUT_TEXT_FIELDS = [
+  ["input", "summary"],
+  ["input", "raw"],
+  ["issue", "body"],
+  ["issue", "title"],
+  ["jira", "summary"],
+  ["jira", "description"],
+  ["task", "description"],
+];
+
+/**
+ * Pull a nested value without throwing on a missing branch.
+ * @param {object} obj
+ * @param {string[]} path
+ * @returns {unknown}
+ */
+function at(obj, path) {
+  return path.reduce((acc, k) => (acc && typeof acc === "object" ? acc[k] : undefined), obj);
+}
+
+/**
+ * Collect every string in the state that could hold the original request, so a
+ * Figma reference is found wherever the input parser happened to store it.
+ *
+ * @param {object} state
+ * @returns {string}
+ */
+export function inputTextOf(state) {
+  const parts = [];
+  for (const path of INPUT_TEXT_FIELDS) {
+    const v = at(state, path);
+    if (typeof v === "string") parts.push(v);
+  }
+  // evidence[].url / figmaFrames[] are where the analysis phase parks references.
+  for (const key of ["figmaFrames", "designRefs"]) {
+    const v = state[key];
+    if (Array.isArray(v)) parts.push(v.map((x) => (typeof x === "string" ? x : JSON.stringify(x))).join(" "));
+  }
+  return parts.join("\n");
+}
+
+/**
+ * Evaluate the gate against a parsed state object.
+ *
+ * Kept pure and exported so the smoke can drive it without laying down a task
+ * directory: a gate that can only be tested by reproducing a full run does not
+ * get tested.
+ *
+ * @param {object|null} state - parsed agent-state.json, or null when absent
+ * @param {string} extraInput - input text supplied on the command line
+ * @returns {{ok: boolean, failures: string[], taskType: string|undefined, figmaSeen: boolean}}
+ */
+export function evaluate(state, extraInput = "") {
+  const failures = [];
+
+  if (state === null) {
+    return {
+      ok: false,
+      failures: [
+        "agent-state.json is missing. Phase 0 owns this file; without it taskType, " +
+          "maturity, account and repo resolution are all unreadable by later phases.",
+      ],
+      taskType: undefined,
+      figmaSeen: FIGMA_URL.test(extraInput),
+    };
+  }
+
+  const taskType = typeof state.taskType === "string" ? state.taskType.trim() : "";
+  if (!taskType) {
+    failures.push(
+      "agent-state.json has no taskType. Phase 3 branches on it: without the field " +
+        "a component task is dispatched as generic development (Step 7 of phase-0-init).",
+    );
+  }
+
+  const haystack = `${inputTextOf(state)}\n${extraInput}`;
+  const figmaSeen = FIGMA_URL.test(haystack);
+
+  if (figmaSeen && taskType && taskType !== "component") {
+    failures.push(
+      `the input carries a Figma URL but taskType is "${taskType}". Step 7 rule 1 makes ` +
+        `"component" mandatory here  -  otherwise the run skips the stack plugin's ` +
+        `token-compliance check, Code Connect publish and component review.`,
+    );
+  }
+
+  // The Figma access chain records which tier answered. A component task with no
+  // recorded tier means nothing verified that the design was actually reachable,
+  // which is how a run ends up guessing spacing.
+  if (figmaSeen) {
+    const tier = at(state, ["figmaAccess", "tier"]);
+    if (tier === undefined || tier === null || tier === "") {
+      failures.push(
+        "the input carries a Figma URL but state.figmaAccess.tier is unset. The 3-tier " +
+          "access chain must record which tier answered, so a later phase can tell " +
+          "'design confirmed' from 'design never fetched'.",
+      );
+    }
+  }
+
+  return { ok: failures.length === 0, failures, taskType: taskType || undefined, figmaSeen };
+}
+
+/** @param {string} taskId */
+function statePathFor(taskId) {
+  return join(homedir(), ".claude", "logs", "multi-agent", taskId, "agent-state.json");
+}
+
+function main(argv) {
+  const args = argv.slice(2);
+  const taskId = args.find((a) => !a.startsWith("--"));
+  if (!taskId) {
+    console.error("usage: phase0-exit-gate.mjs <task_id> [--input \"<text>\"] [--json]");
+    return 2;
+  }
+  const inputIdx = args.indexOf("--input");
+  const extraInput = inputIdx >= 0 ? (args[inputIdx + 1] ?? "") : "";
+  const asJson = args.includes("--json");
+
+  const path = statePathFor(taskId);
+  let state = null;
+  if (existsSync(path)) {
+    try {
+      state = JSON.parse(readFileSync(path, "utf-8"));
+    } catch (e) {
+      console.error(`phase0-exit-gate: ${path} is not valid JSON: ${e.message}`);
+      return 1;
+    }
+  }
+
+  const result = evaluate(state, extraInput);
+
+  if (asJson) {
+    console.log(JSON.stringify({ taskId, statePath: path, ...result }, null, 2));
+  } else if (result.ok) {
+    console.log(
+      `phase0-exit-gate: PASS (taskType=${result.taskType}${result.figmaSeen ? ", figma reference present" : ""})`,
+    );
+  } else {
+    console.error("phase0-exit-gate: FAIL  -  Phase 0 must not be marked completed");
+    for (const f of result.failures) console.error(`  - ${f}`);
+    console.error(`  state: ${path}`);
+  }
+  return result.ok ? 0 : 1;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  process.exit(main(process.argv));
+}

package/pipeline/scripts/smoke-cross-cli-behavior.sh

@@ -185,11 +185,12 @@ else
 fi
 
 # ──────────────────────────────────────────────────────────────────────────
-# CLI-aware reviewer-count contract: Claude Code = 2 reviewers (Opus + Sonnet),
-# Copilot CLI = 3 (GPT-5.4 + Opus + Sonnet). Nothing in code enforces the count
-# (the orchestrator dispatches per the doc), so lock the CONTRACT here against
-# drift across the phase doc, the schema, and the consensus block.
-echo "→ reviewer-count contract (Claude=2, Copilot=3)"
+# CLI-aware reviewer-count contract: Claude Code = 2 (Fable + Sonnet), Copilot CLI
+# = 3 (Opus + GPT-5.4 + Sonnet), Codex CLI = 3 (gpt-5.6 xhigh + gpt-5.4 + gpt-5.6
+# medium). Nothing in code enforces the count (the orchestrator dispatches per the
+# doc), so lock the CONTRACT here against drift across the phase doc, the schema,
+# and the consensus block.
+echo "→ reviewer-count contract (Claude=2, Copilot=3, Codex=3)"
 # `/multi-agent:update` runs this smoke on the user's machine, where the tree is
 # ~/.claude/{schemas,multi-agent-refs} and NOT <root>/pipeline/*. Resolving the
 # root by hand here reported three phantom failures in an install, which reads as
@@ -202,16 +203,30 @@ TRSCHEMA="${MA_SCHEMAS:+$MA_SCHEMAS/triage-output.schema.json}"
 
 if [ -z "$P4" ] || [ ! -f "$P4" ]; then
   echo "  ↷ SKIP: phase-4-review.md not present in this $MA_LAYOUT layout"
-elif grep -qiE "Claude Code (dispatches|=|:) ?2|2-model" "$P4" && grep -qiE "Copilot CLI (dispatches|=|:) ?3|3-model" "$P4"; then
-  pass "phase-4-review declares Claude=2 / Copilot=3 reviewers"
+elif grep -qiE "Claude Code (dispatches|=|:) ?2|2-model" "$P4" \
+  && grep -qiE "Copilot CLI (dispatches|=|:) ?3|3-model" "$P4" \
+  && grep -qiE "Codex CLI (dispatches|=|:) ?3|Claude Code 2, Copilot CLI 3, Codex CLI 3" "$P4"; then
+  pass "phase-4-review declares Claude=2 / Copilot=3 / Codex=3 reviewers"
 else
-  fail "phase-4-review does not declare the CLI-aware reviewer count"
+  fail "phase-4-review does not declare the CLI-aware reviewer count for all three hosts"
+fi
+
+# The two Codex constraints are silent-failure shaped, so the contract has to name
+# them: a spawn without fork_turns collapses the panel onto one model, and the
+# 4-slot ceiling (orchestrator included) is why the count is 3 and not more.
+if [ -n "$P4" ] && [ -f "$P4" ]; then
+  if grep -q 'fork_turns' "$P4" && grep -qiE "concurrency|slots" "$P4"; then
+    pass "phase-4-review documents the fork_turns override rule + the concurrency ceiling"
+  else
+    fail "phase-4-review must document fork_turns and the Codex concurrency ceiling"
+  fi
 fi
 
 if [ -z "$REVSCHEMA" ] || [ ! -f "$REVSCHEMA" ]; then
   echo "  ↷ SKIP: reviewer-output.schema.json not present in this $MA_LAYOUT layout"
-elif grep -qi "Copilot CLI" "$REVSCHEMA" && grep -qi "Claude" "$REVSCHEMA"; then
-  pass "reviewer-output schema notes the CLI-aware reviewer set"
+elif grep -qi "Copilot CLI" "$REVSCHEMA" && grep -qi "Claude" "$REVSCHEMA" \
+  && grep -qi "Codex" "$REVSCHEMA"; then
+  pass "reviewer-output schema notes the CLI-aware reviewer set (all three hosts)"
 else
   fail "reviewer-output schema missing the CLI-aware note"
 fi

package/pipeline/scripts/uninstall.mjs

@@ -36,6 +36,7 @@
  */
 
 import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { execFileSync } from "child_process";
 import { join } from "path";
 import { pathToFileURL } from "url";
 import { createInterface } from "readline";
@@ -123,6 +124,54 @@ function rmIfExists(path) {
   return true;
 }
 
+/**
+ * Remove generated Codex agent TOML files, identified by the header the
+ * installer stamps on them. A user-authored `.toml` sharing a persona name is
+ * left alone - `~/.codex/agents/` is a co-owned directory.
+ *
+ * @param {string} agentsDir
+ * @returns {number} files removed
+ */
+function removeGeneratedCodexAgents(agentsDir) {
+  if (!existsSync(agentsDir)) return 0;
+  const MARKER = "# Generated by multi-agent-pipeline install --codex.";
+  let removed = 0;
+  for (const name of readdirSync(agentsDir)) {
+    if (!name.endsWith(".toml")) continue;
+    const path = join(agentsDir, name);
+    try {
+      if (!readFileSync(path, "utf-8").startsWith(MARKER)) continue;
+    } catch {
+      continue;
+    }
+    if (rmIfExists(path)) removed++;
+  }
+  if (removed > 0) console.log(`    removed ${removed} generated agent file(s) under ${agentsDir}`);
+  return removed;
+}
+
+/**
+ * Hand the dev-toolkit MCP registration back to Codex.
+ *
+ * Best-effort: a missing `codex` binary or an already-absent entry is not an
+ * uninstall failure. Never edits `config.toml` directly - Codex keeps
+ * marketplace and plugin state in the same file.
+ */
+function deregisterCodexMcpServer() {
+  if (dryRun) {
+    report("would run", "codex mcp remove dev-toolkit");
+    return;
+  }
+  try {
+    execFileSync("codex", ["mcp", "remove", "dev-toolkit"], { stdio: "pipe", timeout: 20_000 });
+    console.log("    removed: dev-toolkit MCP registration");
+  } catch {
+    console.log(
+      "    note: could not run `codex mcp remove dev-toolkit` (codex not on PATH, or not registered)",
+    );
+  }
+}
+
 /**
  * Remove every directory under `parent` whose name matches a predicate.
  * @param {string} parent
@@ -160,6 +209,32 @@ function rmMatchingFiles(parent, predicate) {
 // (v11.4.1+). Must stay in sync with INSTRUCTIONS_END_MARKER there.
 const COPILOT_END_MARKER = "<!-- multi-agent-pipeline:copilot-instructions:end -->";
 
+/**
+ * Every end marker the installers write. Both host instruction files share the
+ * same START marker but terminate with their own comment, so a single-marker
+ * lookup silently falls through to the legacy heading-bounded path - and since
+ * the managed body has no top-level heading after the first, that path treats
+ * ALL trailing user content as part of the block and deletes it.
+ */
+const MANAGED_END_MARKERS = [
+  COPILOT_END_MARKER,
+  "<!-- multi-agent-pipeline:codex-instructions:end -->",
+];
+
+/**
+ * Locate whichever managed end marker terminates this block.
+ *
+ * @param {string} fromStart - content from the start marker onward
+ * @returns {{index: number, length: number}} index -1 when none is present
+ */
+function findManagedEndMarker(fromStart) {
+  for (const marker of MANAGED_END_MARKERS) {
+    const index = fromStart.indexOf(marker);
+    if (index >= 0) return { index, length: marker.length };
+  }
+  return { index: -1, length: 0 };
+}
+
 /**
  * Legacy copilot-instructions files (written before the end marker existed)
  * have no explicit terminator. Bound the pipeline span at the next top-level
@@ -205,10 +280,10 @@ function stripManagedBlock(filePath) {
       if (idx >= 0) {
         const before = content.slice(0, idx).trimEnd();
         const fromStart = content.slice(idx);
-        const endIdx = fromStart.indexOf(COPILOT_END_MARKER);
+        const end = findManagedEndMarker(fromStart);
         const rawTrailing =
-          endIdx >= 0
-            ? fromStart.slice(endIdx + COPILOT_END_MARKER.length)
+          end.index >= 0
+            ? fromStart.slice(end.index + end.length)
             : legacyTrailingContent(fromStart);
         const trailing = rawTrailing.replace(/^[\r\n]+/, "").trimEnd();
         let remaining = before;
@@ -332,7 +407,7 @@ export async function main() {
     );
   if (forCodex)
     console.log(
-      "    - OpenAI Codex CLI (~/.codex/prompts/multi-agent.md + AGENTS.md block + config.toml mcp block)",
+      "    - Codex CLI (~/.codex: skills/multi-agent, multi-agent-refs, agents/*.toml, prompts/multi-agent.md, scripts, lib, schemas, rules, AGENTS.md block, dev-toolkit MCP entry)",
     );
   console.log("");
   if (allData) {
@@ -478,14 +553,35 @@ export async function main() {
 
   if (forCodex && HOME) {
     console.log("");
-    console.log("  [OpenAI Codex CLI  -  legacy cleanup] Removing from ~/.codex...");
+    console.log("  [Codex CLI] Removing from ~/.codex...");
     const CODEX = join(HOME, ".codex");
+
+    // Wholly pipeline-owned trees.
+    rmIfExists(join(CODEX, "multi-agent-refs"));
+    rmIfExists(join(CODEX, "scripts"));
+    rmIfExists(join(CODEX, "lib"));
+    rmIfExists(join(CODEX, "schemas"));
+    rmIfExists(join(CODEX, "rules"));
+    rmIfExists(join(CODEX, ".pipeline-version"));
+
+    // Co-owned dirs: remove only what the pipeline wrote. `skills/` holds
+    // Codex's own `.system` set plus user skills; `prompts/` and `agents/` hold
+    // user-authored files.
+    const skills = join(CODEX, "skills");
+    const n = rmMatchingDirs(
+      skills,
+      (name) => name === "multi-agent" || name.startsWith("multi-agent-"),
+    );
+    if (n > 0) console.log(`    removed ${n} skill dir(s) under ${skills}`);
     rmIfExists(join(CODEX, "prompts", "multi-agent.md"));
+    removeGeneratedCodexAgents(join(CODEX, "agents"));
+
     stripManagedBlock(join(CODEX, "AGENTS.md"));
-    if (existsSync(join(CODEX, "config.toml")))
-      console.log(
-        "    note: ~/.codex/config.toml left untouched (may hold user MCP servers)  -  remove pipeline entries manually if present",
-      );
+
+    // The MCP entry was written by `codex mcp add`, so hand it back the same
+    // way rather than editing config.toml - Codex also stores marketplace and
+    // plugin state in that file.
+    deregisterCodexMcpServer();
   }
 
   console.log("");

package/pipeline/scripts/update-check.sh

@@ -48,7 +48,8 @@ if [ -z "$LOCAL_VERSION" ]; then
 fi
 # npx-only installs have no repo clone; the installer stamps the version here.
 if [ -z "$LOCAL_VERSION" ]; then
-  for marker in "$HOME/.claude/.pipeline-version" "$HOME/.copilot/.pipeline-version"; do
+  for marker in "$HOME/.claude/.pipeline-version" "$HOME/.copilot/.pipeline-version" \
+                "$HOME/.codex/.pipeline-version"; do
     if [ -f "$marker" ]; then
       LOCAL_VERSION=$(head -1 "$marker" 2>/dev/null | tr -d '[:space:]')
       [ -n "$LOCAL_VERSION" ] && break

package/pipeline/skills/shared/core/multi-agent-dev/SKILL.md

@@ -62,3 +62,24 @@ Phase 7: Report     → Channels (Jira / Confluence / PR / Wiki)
 | Phase 5 User Test | ✅ | ✅ (same) |
 | Phase 7 channels (Jira / Confluence / PR / Wiki) | ✅ | ✅ (same) |
 | Duration | ~10-15 min | ~5-7 min |
+
+## Analysis doc supplied to a fast mode (warn before starting)
+
+The `--dev` family skips Phase 1 (Analysis) and Phase 2 (Planning) by design. So when
+the input references an analysis document  -  a Confluence URL, a local analysis file,
+or the user says "I ran analysis for this"  -  there is **no phase that turns it into a
+plan**. The doc becomes raw context for one Dev pass, and work comes out ordered by
+whatever the model read first: the bottom of the dependency chain lands, the screen
+wiring does not.
+
+Say so before starting, once, and offer the choice:
+
+```
+This mode skips Analysis and Planning, so the analysis document will not be turned
+into a task breakdown. For analysis-driven screen work, /multi-agent or
+/multi-agent:local run both phases.
+  1. Continue with --dev (doc as context only)
+  2. Switch to the full pipeline
+```
+
+Autopilot picks 1 and logs the warning rather than asking.

package/pipeline/skills/shared/core/multi-agent-dev-local/SKILL.md

@@ -34,3 +34,24 @@ Routes to the orchestrator with the `--dev --local` flags. The pipeline contract
 multi-agent-dev-local "PROJ-12345"                             # Jira
 multi-agent-dev-local "Bug: LoginView dark mode"               # Free-text
 ```
+
+## Analysis doc supplied to a fast mode (warn before starting)
+
+The `--dev` family skips Phase 1 (Analysis) and Phase 2 (Planning) by design. So when
+the input references an analysis document  -  a Confluence URL, a local analysis file,
+or the user says "I ran analysis for this"  -  there is **no phase that turns it into a
+plan**. The doc becomes raw context for one Dev pass, and work comes out ordered by
+whatever the model read first: the bottom of the dependency chain lands, the screen
+wiring does not.
+
+Say so before starting, once, and offer the choice:
+
+```
+This mode skips Analysis and Planning, so the analysis document will not be turned
+into a task breakdown. For analysis-driven screen work, /multi-agent or
+/multi-agent:local run both phases.
+  1. Continue with --dev (doc as context only)
+  2. Switch to the full pipeline
+```
+
+Autopilot picks 1 and logs the warning rather than asking.

package/pipeline/skills/shared/core/multi-agent-language/SKILL.md

@@ -17,7 +17,7 @@ Two-axis language preference for the pipeline:
 | `promptLanguage` | Interactive prompts during a pipeline run (account picker, project picker, dev-context picker, base-branch picker, branch-name picker, maturity ack, channels picker, Phase 5 test prompt, Phase 6 local-checkout prompt) | `prefs.global.promptLanguage` | **Fixed to `en`**  -  never toggled by this skill |
 | `outputLanguage` | Assistant's explanations, status updates, error messages, and pipeline-generated reports rendered to the user (NOT external payloads) | `prefs.global.outputLanguage` | Toggled by this skill |
 
-**Why promptLanguage is fixed:** Pipeline picker UI, confirmation prompts, and error messages are authored in English to keep tooling consistent across CLIs. Mixing Turkish prompts into otherwise-English skill output looks inconsistent. Only the assistant's free-form replies follow `outputLanguage`.
+**Why promptLanguage is fixed:** it governs the picker's structural chrome only  -  `AskUserQuestion` `label` (button text) and `header` (chip), host error UI, and internal contract identifiers. Those stay English so tooling reads the same across CLIs. Everything a user actually reads follows `outputLanguage`, including the picker `question` and each option's `description`, per the canonical per-field matrix in `multi-agent-refs/rules.md`. A picker whose question is English on a Turkish run is a bug, not the contract.
 
 **Always English regardless of either field**: commit messages, PR titles/bodies, Jira comments, wiki pages, reviewer/triage system prompts, agent-log.md payloads, skill-picker / confirmation / error UI exposed by the CLI host.
 
@@ -83,5 +83,5 @@ Render in the new outputLanguage:
 
 - `multi-agent-setup`  -  first-run language picker (asks only outputLanguage; promptLanguage seeded as `en`)
 - `prefs.schema.json`  -  `global.promptLanguage` (fixed `"en"`) and `global.outputLanguage`
-- Phase 5 / Phase 6  -  read promptLanguage for interactive prompts (always English)
+- Phase 5 / Phase 6  -  interactive prompts follow the per-field matrix: `question` + `description` in `outputLanguage`, `label` + `header` English
 - `multi-agent-help`  -  reads outputLanguage for its own copy

package/pipeline/skills/shared/core/multi-agent-setup/SKILL.md

@@ -15,7 +15,7 @@ Ask BEFORE anything else. The pipeline has two language fields:
 
 | Field | Controls | Configurable? |
 |---|---|---|
-| `promptLanguage` | Interactive pickers and prompts during pipeline runs (account, project, branch, channels, Phase 5/6 confirmations) | **No  -  fixed to `en`.** Picker UI is always English. |
+| `promptLanguage` | The picker's structural UI chrome only: `AskUserQuestion` `label` + `header`, host error UI, internal contract identifiers | **No  -  fixed to `en`.** Button and chip text stays English. |
 | `outputLanguage` | The assistant's non-interactive explanations, status updates, error messages, and pipeline-generated reports | Yes  -  set here, change later via `/multi-agent-language <en\|tr>` |
 
 `promptLanguage` is seeded as `"en"` and never offered to the user. External payloads (commits, PR/Jira/wiki, reviewer/triage prompts, agent-log.md) always stay English regardless.
@@ -278,6 +278,53 @@ pbcopy < /dev/null
 # ~/.claude/settings.json -> mcpServers -> figma
 ```
 
+### App Store Connect Credentials (optional, iOS only)
+
+Unlocks Gate 2 of `multi-agent-testflight-validation`  -  Apple's own
+`altool --validate-app`, the only check that sees an unregistered bundle ID, a
+profile that does not match the App Store Connect app record, or a version+build
+pair already used. Skipping is a first-class answer: the validation command still
+runs its static audit and guideline review and reports Gate 2 as `SKIPPED` with
+the reason, never as a pass.
+
+Ask (picker): **API key** / **Apple ID + app-specific password** / **Skip**.
+
+**API key**  -  needs an Admin or App Manager role in App Store Connect. Map the key
+id and issuer id as `appstore_connect_key_id` / `appstore_connect_issuer_id`. The
+private key is a FILE and never enters the credential store; it goes to one of the
+directories altool searches:
+
+```bash
+ls ~/.appstoreconnect/private_keys/AuthKey_*.p8 2>/dev/null \
+  || echo "MISSING: put AuthKey_<keyId>.p8 in ~/.appstoreconnect/private_keys/"
+```
+
+**Apple ID + app-specific password**  -  usable by **any Apple ID holder, no elevated
+role**, which is the realistic path when API-key creation is not permitted on the
+account. Lead with this option when the user says they cannot create an API key.
+The password goes into Apple's own keychain helper, which is what
+`altool -p @keychain:<item>` reads  -  never into chat, never into an argument:
+
+```bash
+# export AC_PASSWORD_ONCE in your own shell first, for this one command
+xcrun altool --store-password-in-keychain-item "<item-name>" \
+  -u "<apple-id>" -p @env:AC_PASSWORD_ONCE
+```
+
+Map only the ITEM NAME as `appstore_connect_password_item`, plus the Apple ID as
+`appstore_connect_apple_id`. The password stays in the keychain and is referenced,
+never read by the pipeline.
+
+**Multi-provider accounts.** A corporate Apple ID often belongs to several
+providers and altool fails opaquely without one. Resolve it once with
+`ios_testflight_validate({list_providers: true, ...})` and store the id under
+`prefs.projects[<key>].appStoreConnect.providerPublicId`  -  per-project, since a
+user can ship for more than one team.
+
+A credential that resolves but is rejected (401/403) follows the Expired-token
+decision (Regenerate / Use a different token / Skip and continue) rather than
+being silently dropped.
+
 ### Security Rules
 
 - Never paste tokens into terminal or chat  -  use `pbpaste` for input