@mmerterden/multi-agent-pipeline 14.1.1 → 14.2.2

package/pipeline/scripts/uninstall.mjs

@@ -248,6 +248,31 @@ function rmMatchingFiles(parent, predicate) {
   return count;
 }
 
+// Copilot CLI / Codex CLI have no plugin loader, so install/_plugin-skills.mjs
+// copies each stack plugin's authored skills straight into the flat skills/
+// dir (~100 dirs across a typical set of enabled plugins). None of those
+// names are in PIPELINE_CORE_SKILL_DIRS - the allowlist above only covers the
+// pipeline's OWN skills - so they were never removed on uninstall. The
+// installer now writes PLUGIN_SKILLS_MANIFEST listing exactly what it
+// delivered; read it back here rather than guessing plugin skill names.
+const PLUGIN_SKILLS_MANIFEST = ".plugin-skills-manifest.json";
+
+function rmPluginDeliveredSkills(skillsDir) {
+  const manifestPath = join(skillsDir, PLUGIN_SKILLS_MANIFEST);
+  if (!existsSync(manifestPath)) return 0;
+  let names;
+  try {
+    names = JSON.parse(readFileSync(manifestPath, "utf-8"));
+  } catch {
+    return 0;
+  }
+  if (!Array.isArray(names)) return 0;
+  const nameSet = new Set(names);
+  const count = rmMatchingDirs(skillsDir, (name) => nameSet.has(name));
+  rmIfExists(manifestPath);
+  return count;
+}
+
 // Explicit terminator install/copilot.mjs writes after the pipeline section
 // (v11.4.1+). Must stay in sync with INSTRUCTIONS_END_MARKER there.
 const COPILOT_END_MARKER = "<!-- multi-agent-pipeline:copilot-instructions:end -->";
@@ -387,13 +412,20 @@ function cleanClaudeSettings(settingsPath) {
   if (settings.hooks?.PreToolUse?.length) {
     const before = settings.hooks.PreToolUse.length;
     // Match both the current matcher ("Bash") and the dead pre-v11.4.1 one
-    // ("Bash(git commit:*)"); the pre-commit-check.sh command identifies the
-    // entry as ours either way.
+    // ("Bash(git commit:*)"); the command identifies the entry as ours either
+    // way. install/claude.mjs registers TWO PreToolUse gates this way -
+    // pre-commit-check.sh AND agent-guard.sh - and only the first was ever
+    // stripped here. After ~/.claude/scripts/ is deleted below, the
+    // agent-guard.sh entry pointed at a script that no longer existed, so
+    // every subsequent Bash call fired a hook error.
     settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
       (h) =>
         !(
           (h.matcher === "Bash" || h.matcher === "Bash(git commit:*)") &&
-          h.hooks?.some((sub) => sub.command?.includes("pre-commit-check.sh"))
+          h.hooks?.some(
+            (sub) =>
+              sub.command?.includes("pre-commit-check.sh") || sub.command?.includes("agent-guard.sh"),
+          )
         ),
     );
     if (settings.hooks.PreToolUse.length < before) touched = true;
@@ -540,10 +572,12 @@ export async function main() {
         name === "figma-to-component",
     );
     n += rmMatchingDirs(skills, (name) => PIPELINE_CORE_SKILL_DIRS.includes(name));
+    n += rmPluginDeliveredSkills(skills);
     if (n > 0) console.log(`    removed ${n} skill dir(s) under ${skills}`);
     rmIfExists(join(skills, ".skills-index.json"));
     rmIfExists(join(skills, "skills-index.md"));
     rmIfExists(join(skills, "README.md"));
+    rmIfExists(join(COP, "rules"));
     // Agent definitions are FILES; remove only the pipeline-shipped names so
     // user-authored agents survive.
     rmMatchingFiles(join(COP, "agents"), (name) => PIPELINE_AGENT_FILES.includes(name));
@@ -613,10 +647,11 @@ export async function main() {
     // Codex's own `.system` set plus user skills; `prompts/` and `agents/` hold
     // user-authored files.
     const skills = join(CODEX, "skills");
-    const n = rmMatchingDirs(
+    let n = rmMatchingDirs(
       skills,
       (name) => name === "multi-agent" || name.startsWith("multi-agent-"),
     );
+    n += rmPluginDeliveredSkills(skills);
     if (n > 0) console.log(`    removed ${n} skill dir(s) under ${skills}`);
     rmIfExists(join(CODEX, "prompts", "multi-agent.md"));
     removeGeneratedCodexAgents(join(CODEX, "agents"));

package/pipeline/scripts/update-issue-progress.sh

@@ -14,8 +14,8 @@
 #   update-issue-progress.sh <task-id>
 #
 # Inputs:
-#   $HOME/.claude/projects/{slug}/state/{taskId}/agent-state.json
-#     .issue.url, .issue.number, .repos.primary.org, .repos.primary.name
+#   $HOME/.claude/logs/multi-agent/{project}/{taskId}/agent-state.json
+#     .githubIssue.owner, .githubIssue.repo, .githubIssue.number
 #     .flags.implementation, .flags.testing, .flags.codeConnect, .flags.wiki
 #
 # Side effects:
@@ -86,11 +86,12 @@ if [ "$TASK_ID" = "--rewrite" ]; then
   exit 0
 fi
 
-# Resolve the project state directory (matches phase-tracker convention).
-STATE_GLOB="$HOME/.claude/projects/*"
+# Resolve agent-state.json. multi-repo-pipeline.sh writes it under a
+# per-project directory ($HOME/.claude/logs/multi-agent/{project}/{taskId}/)
+# - not the ~/.claude/projects/*/state/ path this used to glob, which no
+# writer in the pipeline ever populates.
 AGENT_STATE=""
-for dir in $STATE_GLOB; do
-  candidate="$dir/state/$TASK_ID/agent-state.json"
+for candidate in "$HOME"/.claude/logs/multi-agent/*/"$TASK_ID"/agent-state.json; do
   if [ -f "$candidate" ]; then
     AGENT_STATE="$candidate"
     break
@@ -102,18 +103,13 @@ if [ -z "$AGENT_STATE" ]; then
   exit 2
 fi
 
-ISSUE_URL=$(jq -r '.issue.url // empty' "$AGENT_STATE")
-ISSUE_NUM=$(jq -r '.issue.number // empty' "$AGENT_STATE")
-ORG_REPO=$(jq -r '.repos.primary.name // empty' "$AGENT_STATE")
-# Derive org/repo from URL if not present in state.
-if [ -z "$ORG_REPO" ] || ! [[ "$ORG_REPO" == */* ]]; then
-  if [[ "$ISSUE_URL" =~ github\.com/([^/]+/[^/]+)/issues/ ]]; then
-    ORG_REPO="${BASH_REMATCH[1]}"
-  fi
-fi
+# agent-state.schema.json has no `.issue`/`.repos` properties (additionalProperties
+# is false) - the real GitHub-issue coordinates live at `.githubIssue.{owner,repo,number}`.
+ISSUE_NUM=$(jq -r '.githubIssue.number // empty' "$AGENT_STATE")
+ORG_REPO=$(jq -r 'if .githubIssue then (.githubIssue.owner + "/" + .githubIssue.repo) else empty end' "$AGENT_STATE")
 
 if [ -z "$ORG_REPO" ] || [ -z "$ISSUE_NUM" ]; then
-  echo "update-issue-progress: cannot resolve org/repo or issue number from state" >&2
+  echo "update-issue-progress: no githubIssue in state for task=$TASK_ID (Jira-originated task, or issue not yet linked)" >&2
   exit 3
 fi
 

package/pipeline/scripts/worktree-finalize.sh

@@ -202,6 +202,7 @@ fi
 # copied only if present; a task that never reached Phase 4 has no triage output
 # and that is not an error.
 DEST="$LOGS_ROOT/${PROJECT:+$PROJECT/}$TASK_ID/artifacts"
+LOGS_TASK_DIR="$LOGS_ROOT/${PROJECT:+$PROJECT/}$TASK_ID"
 
 copy_one() {
   src="$rp_wt/$1"
@@ -214,7 +215,27 @@ copy_one() {
   cp -R "$src" "$DEST/$1" 2>/dev/null && SALVAGED="${SALVAGED:+$SALVAGED,}\"$1\""
 }
 
-for a in agent-state.json phase-tracker.json triage-output.json \
+# agent-state.json and the tracker state file are never written INSIDE the
+# worktree checkout - multi-repo-pipeline.sh/phase-tracker.sh write both
+# straight to $LOGS_TASK_DIR. copy_one() sourcing from $rp_wt always missed
+# them (src never existed → silent no-op), so this salvage - and the
+# worktreeRemovedAt stamp below, gated on the salvaged copy existing - never
+# actually fired for either file.
+copy_from_logs() {
+  src="$LOGS_TASK_DIR/$1"
+  [ -e "$src" ] || return 0
+  if [ "$DRY" = "1" ]; then
+    SALVAGED="${SALVAGED:+$SALVAGED,}\"$1\""
+    return 0
+  fi
+  mkdir -p "$DEST/$(dirname "$1")" 2>/dev/null
+  cp -R "$src" "$DEST/$1" 2>/dev/null && SALVAGED="${SALVAGED:+$SALVAGED,}\"$1\""
+}
+
+copy_from_logs agent-state.json
+copy_from_logs tracker-state.json
+
+for a in triage-output.json \
          .review-diff.txt .build.log .test.log .pipeline; do
   copy_one "$a"
 done
@@ -230,7 +251,7 @@ fi
 # tree. This is what keeps `--force` off the table: a refusal after this point
 # means unexpected dirt, and forcing past unexpected dirt is how work gets lost.
 DROPPED=""
-for a in agent-state.json phase-tracker.json triage-output.json \
+for a in triage-output.json \
          .review-diff.txt .build.log .test.log .pipeline; do
   [ -e "$rp_wt/$a" ] || continue
   case "$a" in

package/pipeline/skills/.skills-index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "1.0.0",
-  "skillCount": 196,
+  "skillCount": 202,
   "entries": [
     {
       "name": "accessibility-compliance-accessibility-audit",
@@ -445,7 +445,7 @@
     },
     {
       "name": "firebase",
-      "description": "You're a developer who has shipped dozens of Firebase projects. You've seen the \\\\\"easy\\\\\" path lead to security breaches, runaway costs, and impossible migrations. You know Firebase is powerful, but you also know its sharp edges. Use when integrating or reviewing Firebase: auth, Firestore, function",
+      "description": "You're a developer who has shipped dozens of Firebase projects. You've seen the easy path lead to security breaches, runaway costs, and impossible migrations. You know Firebase is powerful, but you also know its sharp edges. Use when integrating or reviewing Firebase: auth, Firestore, functions, or ",
       "platform": null,
       "group": "external",
       "triggerKeywords": [],
@@ -695,6 +695,15 @@
       "triggerPaths": [],
       "relativePath": "shared/external/live-activities/SKILL.md"
     },
+    {
+      "name": "localization-reuse-map",
+      "description": ">-",
+      "platform": null,
+      "group": "external",
+      "triggerKeywords": [],
+      "triggerPaths": [],
+      "relativePath": "shared/external/localization-reuse-map/SKILL.md"
+    },
     {
       "name": "macos-menubar-tuist-app",
       "description": "Build, refactor, or review SwiftUI macOS menubar apps that use Tuist. Use when building, refactoring or reviewing a SwiftUI macOS menubar app that uses Tuist.",
@@ -922,7 +931,7 @@
     },
     {
       "name": "multi-agent-language",
-      "description": "Toggle outputLanguage (assistant explanations). promptLanguage is fixed to English. External payloads stay English. Use when the assistant should explain itself in a different language.",
+      "description": "Toggle outputLanguage (assistant explanations, picker questions, PR/Jira/Confluence bodies). promptLanguage is fixed to English; commit messages, branch names and identifiers stay English. Use when the assistant should explain itself in a different language.",
       "platform": null,
       "group": "core",
       "triggerKeywords": [],
@@ -1100,6 +1109,15 @@
       "triggerPaths": [],
       "relativePath": "shared/core/multi-agent-status/SKILL.md"
     },
+    {
+      "name": "multi-agent-store-ready",
+      "description": "Pre-submission store readiness for a built package, iOS and Android, local-only. Three symmetric gates per platform: a static package audit, the store's own authoritative validation, and a policy review against repo source. Separate verdict per gate, a skipped gate never counted as a pass. Validates",
+      "platform": null,
+      "group": "core",
+      "triggerKeywords": [],
+      "triggerPaths": [],
+      "relativePath": "shared/core/multi-agent-store-ready/SKILL.md"
+    },
     {
       "name": "multi-agent-sync",
       "description": "One-shot sync of the entire multi-agent ecosystem: Claude Code, Copilot CLI, pipeline repo, website, and the dev-toolkit MCP server. Use when work is finished and should be propagated across Claude Code, Copilot CLI, the repos, the website and the dev-toolkit server.",
@@ -1118,9 +1136,45 @@
       "triggerPaths": [],
       "relativePath": "shared/core/multi-agent-test/SKILL.md"
     },
+    {
+      "name": "multi-agent-test-accessibility",
+      "description": "Accessibility audit on a booted simulator / emulator: VoiceOver labels, sub-44pt tap targets, contrast, traits. Alias pinning the accessibility scenario. Use when auditing a screen for assistive-technology support.",
+      "platform": null,
+      "group": "core",
+      "triggerKeywords": [],
+      "triggerPaths": [],
+      "relativePath": "shared/core/multi-agent-test-accessibility/SKILL.md"
+    },
+    {
+      "name": "multi-agent-test-dark-mode",
+      "description": "Dark mode UI test on a booted simulator / emulator: walk every screen light then dark, report contrast + colour bugs. Alias pinning the dark-mode scenario. Use when a dark-mode rendering bug is suspected.",
+      "platform": null,
+      "group": "core",
+      "triggerKeywords": [],
+      "triggerPaths": [],
+      "relativePath": "shared/core/multi-agent-test-dark-mode/SKILL.md"
+    },
+    {
+      "name": "multi-agent-test-dynamic-type",
+      "description": "Dynamic Type layout test on a booted simulator / emulator: re-walk every screen at XL through accessibility-extra-large, report truncation and clipping. Alias pinning the dynamic-type scenario. Use when checking a layout survives large text.",
+      "platform": null,
+      "group": "core",
+      "triggerKeywords": [],
+      "triggerPaths": [],
+      "relativePath": "shared/core/multi-agent-test-dynamic-type/SKILL.md"
+    },
+    {
+      "name": "multi-agent-test-screenshots",
+      "description": "App Store screenshot set from a booted simulator / emulator in a given locale, taken as an argument and defaulting to tr. Alias pinning the screenshot scenario. Use when generating store screenshots or checking a localised build renders.",
+      "platform": null,
+      "group": "core",
+      "triggerKeywords": [],
+      "triggerPaths": [],
+      "relativePath": "shared/core/multi-agent-test-screenshots/SKILL.md"
+    },
     {
       "name": "multi-agent-testflight-validation",
-      "description": "Pre-submission validation for a TestFlight / App Store build (iOS, local-only). Three gates: static archive audit, Apple's own `altool --validate-app`, and a Review-Guidelines check. ITMS codes are mapped to the rule each implies. Validates only, never uploads. Use when a build is about to go to Tes",
+      "description": "iOS-pinned alias of store-ready: same three gates on an iOS build, one implementation. Validates a TestFlight / App Store package, never uploads. Use when an iOS build is about to go to TestFlight, or a submission was rejected and you need why.",
       "platform": null,
       "group": "core",
       "triggerKeywords": [],

package/pipeline/skills/shared/README.md

@@ -2,11 +2,11 @@
 
 Single source of truth for skills delivered to both Claude Code (`~/.claude/skills/`) and Copilot CLI (`~/.copilot/skills/`) by the installer.
 
-**Total:** 196 skills (47 core + 149 external). Auto-generated by `scripts/gen-skills-index.mjs`  -  do not edit by hand.
+**Total:** 201 skills (52 core + 149 external). Auto-generated by `scripts/gen-skills-index.mjs`  -  do not edit by hand.
 
 ## Directory layout
 
-- **`core/`**  -  47 `multi-agent*` orchestration skills that are pipeline-critical. Edits here are core-code changes.
+- **`core/`**  -  52 `multi-agent*` orchestration skills that are pipeline-critical. Edits here are core-code changes.
 - **`external/`**  -  149 iOS / Android / generic skills imported from the upstream skill library. Mirrors of third-party guidance.
 - Install destination stays flat: both trees flatten into `~/.claude/skills/` and `~/.copilot/skills/`. See ADR-0006 for the rationale.
 
@@ -14,7 +14,7 @@ Source layout is logical grouping only  -  skill discovery at runtime is unchang
 
 ## Categories
 
-- [Pipeline Orchestration](#pipeline-orchestration)  -  47
+- [Pipeline Orchestration](#pipeline-orchestration)  -  52
 - [iOS / Apple Ecosystem](#ios-apple-ecosystem)  -  89
 - [Android / Kotlin](#android-kotlin)  -  13
 - [Web / Frontend](#web-frontend)  -  10
@@ -40,7 +40,6 @@ Source layout is logical grouping only  -  skill discovery at runtime is unchang
 | [`multi-agent-dev-local`](./core/multi-agent-dev-local/) | `core` | Fast mode + local  -  Init → Dev(Opus) → Review → Commit → Report, no worktree. Use when a change should be developed and reviewed on the cu |
 | [`multi-agent-dev-local-autopilot`](./core/multi-agent-dev-local-autopilot/) | `core` | Fastest + local  -  Dev(Opus) + autopilot, no worktree, zero interaction. Use when a change should be developed on the current branch with n |
 | [`multi-agent-diff-explain`](./core/multi-agent-diff-explain/) | `core` | Map Phase 4 triage findings to branch diff lines. Read-only post-hoc command, used after review to answer 'which finding lines up with which |
-| [`multi-agent-ship`](./core/multi-agent-ship/) | `core` | Continue already-done LOCAL work through the pipeline tail: Review → Build+Test → Commit/PR → Report (technical analysis + Jira test-scenari |
 | [`multi-agent-forget`](./core/multi-agent-forget/) | `core` | Remove a saved /multi-agent routine (created by /multi-agent:save): deletes its local-only command and its registry entry. Asks which one an |
 | [`multi-agent-garbage-collect`](./core/multi-agent-garbage-collect/) | `core` | Sweep leftover /tmp scratch (picker state, review diffs, channel payloads, analysis drafts) from past runs. Dry-run first; confirms before d |
 | [`multi-agent-help`](./core/multi-agent-help/) | `core` | Multi-agent pipeline usage guide  -  renders in EN or TR per prefs.global.outputLanguage (falls back to promptLanguage for backward compatib |
@@ -48,7 +47,7 @@ Source layout is logical grouping only  -  skill discovery at runtime is unchang
 | [`multi-agent-issue`](./core/multi-agent-issue/) | `core` | List unassigned GitHub issues, pick one, auto-assign, and launch the multi-agent pipeline. Use when a GitHub issue should be picked up and s |
 | [`multi-agent-jira`](./core/multi-agent-jira/) | `core` | List open Jira issues, pick one, and launch the multi-agent pipeline. Use when a Jira issue should be picked up and started without knowing  |
 | [`multi-agent-kill`](./core/multi-agent-kill/) | `core` | Stop the given task, then remove its worktree and branch. Asks for confirmation. Use when a running or stuck task should be stopped and its  |
-| [`multi-agent-language`](./core/multi-agent-language/) | `core` | Toggle outputLanguage (assistant explanations). promptLanguage is fixed to English. External payloads stay English. Use when the assistant s |
+| [`multi-agent-language`](./core/multi-agent-language/) | `core` | Toggle outputLanguage (assistant explanations, picker questions, PR/Jira/Confluence bodies). promptLanguage is fixed to English; commit mess |
 | [`multi-agent-local`](./core/multi-agent-local/) | `core` | Full pipeline in local mode  -  no worktree, runs directly on the current branch. Use when the full pipeline should run on the current branc |
 | [`multi-agent-local-autopilot`](./core/multi-agent-local-autopilot/) | `core` | Full pipeline + local + autopilot  -  no worktree, no confirmations, all 8 phases run end-to-end on the current branch. Use when the full pi |
 | [`multi-agent-log`](./core/multi-agent-log/) | `core` | Show the agent-log.md for the given task. With no ID, shows the most recent task. Use when asked what a task did, or to read its log. |
@@ -65,11 +64,17 @@ Source layout is logical grouping only  -  skill discovery at runtime is unchang
 | [`multi-agent-scan`](./core/multi-agent-scan/) | `core` | Skill security scan: walks local skill directories against a tiered pattern catalog. Use when local skill directories need checking for unsa |
 | [`multi-agent-search`](./core/multi-agent-search/) | `core` | Log search across every agent-log.md with smart ranking and filters. Optional --semantic flag queries the per-repo triage corpus. Use when s |
 | [`multi-agent-setup`](./core/multi-agent-setup/) | `core` | First-run setup wizard: keychain token discovery, Git Identity onboarding, and pipeline preparation. Use when the pipeline is being set up f |
+| [`multi-agent-ship`](./core/multi-agent-ship/) | `core` | Continue already-done LOCAL work through the pipeline tail: Review → Build+Test → Commit/PR → Report (technical analysis + Jira test-scenari |
 | [`multi-agent-stack`](./core/multi-agent-stack/) | `core` | Select the active stack for this repo by enabling the matching marketplace plugin(s) in .claude/settings.json (ios/android/mobile/backend/fr |
 | [`multi-agent-status`](./core/multi-agent-status/) | `core` | Show every multi-agent task's ID, phase, branch, and status. Use when asked what is running, or for an overview of every task. |
+| [`multi-agent-store-ready`](./core/multi-agent-store-ready/) | `core` | Pre-submission store readiness for a built package, iOS and Android, local-only. Three symmetric gates per platform: a static package audit, |
 | [`multi-agent-sync`](./core/multi-agent-sync/) | `core` | One-shot sync of the entire multi-agent ecosystem: Claude Code, Copilot CLI, pipeline repo, website, and the dev-toolkit MCP server. Use whe |
 | [`multi-agent-test`](./core/multi-agent-test/) | `core` | UI Bug Hunter  -  iOS Simulator (simctl) + Android Emulator (adb). Auto-detects platform. Screenshot + tap + analyze on the booted device. T |
-| [`multi-agent-testflight-validation`](./core/multi-agent-testflight-validation/) | `core` | Pre-submission validation for a TestFlight / App Store build (iOS, local-only). Three gates: static archive audit, Apple's own `altool --val |
+| [`multi-agent-test-accessibility`](./core/multi-agent-test-accessibility/) | `core` | Accessibility audit on a booted simulator / emulator: VoiceOver labels, sub-44pt tap targets, contrast, traits. Alias pinning the accessibil |
+| [`multi-agent-test-dark-mode`](./core/multi-agent-test-dark-mode/) | `core` | Dark mode UI test on a booted simulator / emulator: walk every screen light then dark, report contrast + colour bugs. Alias pinning the dark |
+| [`multi-agent-test-dynamic-type`](./core/multi-agent-test-dynamic-type/) | `core` | Dynamic Type layout test on a booted simulator / emulator: re-walk every screen at XL through accessibility-extra-large, report truncation a |
+| [`multi-agent-test-screenshots`](./core/multi-agent-test-screenshots/) | `core` | App Store screenshot set from a booted simulator / emulator in a given locale, taken as an argument and defaulting to tr. Alias pinning the  |
+| [`multi-agent-testflight-validation`](./core/multi-agent-testflight-validation/) | `core` | iOS-pinned alias of store-ready: same three gates on an iOS build, one implementation. Validates a TestFlight / App Store package, never upl |
 | [`multi-agent-uninstall`](./core/multi-agent-uninstall/) | `core` | Uninstall the pipeline from Claude Code + Copilot CLI. Keychain access tokens are always left untouched; --all-data also clears pipeline set |
 | [`multi-agent-update`](./core/multi-agent-update/) | `core` | Update the pipeline to the latest version: git pull, install, migrate. Use when the installed pipeline is behind and should be brought to th |
 
@@ -97,7 +102,7 @@ Source layout is logical grouping only  -  skill discovery at runtime is unchang
 | [`device-integrity`](./external/device-integrity/) | `external` | Verify device legitimacy and app integrity using DeviceCheck (DCDevice per-device bits) and App Attest (DCAppAttestService key generation, a |
 | [`energykit`](./external/energykit/) | `external` | Query grid electricity forecasts and submit load events using EnergyKit to help users optimize home electricity usage. Use when building sma |
 | [`eventkit-calendar`](./external/eventkit-calendar/) | `external` | Create, read, and manage calendar events and reminders using EventKit and EventKitUI. Use when adding events to the user's calendar, creatin |
-| [`firebase`](./external/firebase/) | `external` | You're a developer who has shipped dozens of Firebase projects. You've seen the \\"easy\\" path lead to security breaches, runaway costs, an |
+| [`firebase`](./external/firebase/) | `external` | You're a developer who has shipped dozens of Firebase projects. You've seen the easy path lead to security breaches, runaway costs, and impo |
 | [`healthkit`](./external/healthkit/) | `external` | Read, write, and query Apple Health data using HealthKit. Covers HKHealthStore authorization, sample queries, statistics queries, statistics |
 | [`hig-components-content`](./external/hig-components-content/) | `external` | Apple Human Interface Guidelines for content display components. Use when designing or reviewing how content is displayed on an Apple platfo |
 | [`hig-components-layout`](./external/hig-components-layout/) | `external` | Apple Human Interface Guidelines for layout and navigation components. Use when designing or reviewing layout and navigation on an Apple pla |

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

@@ -133,20 +133,16 @@ When `multi-agent kill [id]` is called:
 
 ---
 
-## Clear Logs
+## Clear Logs  -  superseded, redirect only
 
-When `multi-agent clear-logs` is called:
+`multi-agent clear-logs`: **do not run it.** Say it was superseded, then route to
+`multi-agent-prune-logs` (per-task logs, audit trail and metrics kept) or
+`multi-agent-garbage-collect` (`/tmp` scratch + worktree residue).
 
-1. **Confirm**: `"All task logs will be deleted (agent-log.md + agent-state.json). Worktrees and branches will be kept. Are you sure?"`
-2. **Scan**: Find all `.worktrees/PROJ-*/agent-log.md` and `agent-state.json` files
-3. **Delete**: Remove log and state files from each worktree
-4. **Do NOT reset counter**: `.worktrees/.multi-agent-counter` stays intact  -  prevents ID collision with existing worktrees
-5. **Confirm**:
-   ```
-   🧹 Logs cleared
-   Deleted: {N} agent-log.md + {N} agent-state.json
-   Worktrees & branches: untouched
-   ```
+It scanned `.worktrees/PROJ-*/`, which holds no logs  -  they live at
+`$HOME/.claude/logs/multi-agent/{project}/{task-id}/`  -  so it deleted nothing and
+reported success. The name stays as a redirect so an existing invocation still lands
+somewhere correct.
 
 ---
 
@@ -185,8 +181,8 @@ When `multi-agent purge` is called:
 
 When `multi-agent resume [id]` is called:
 
-1. **Find state file**: Scan `.worktrees/PROJ-{id}/agent-state.json`
-   - If no `id` given, find the most recent worktree with `status != "done"`
+1. **Find state file**: `$HOME/.claude/logs/multi-agent/{project}/{task-id}/agent-state.json`  -  that is where Phase 0 writes it, not inside the worktree. A task finalized by Phase 6 keeps its state at `.../{task-id}/artifacts/agent-state.json`, so look there too before reporting not-found.
+   - If no `id` given, take the most recent task dir with `status != "done"`
 2. **Read state**: Parse `agent-state.json` → determine last completed phase
 3. **Restore context**: Read `agent-log.md` for previous findings:
    - Phase 1 analysis findings → reuse in Phase 2+
@@ -397,8 +393,8 @@ Full contract: `refs/tracker-contract.md` section "TaskCreate ordering (strict)"
    git config user.name  "{identity.name}"
    git config user.email "{identity.email}"
    ```
-4. Create log file: `.worktrees/PROJ-{id}/agent-log.md` with header
-5. Create state file: `.worktrees/PROJ-{id}/agent-state.json` with:
+4. Create log file: `$HOME/.claude/logs/multi-agent/{project}/{task-id}/agent-log.md` with header
+5. Create state file: `$HOME/.claude/logs/multi-agent/{project}/{task-id}/agent-state.json` with:
    ```json
    {
      "taskId": "PROJ-12345",
@@ -589,7 +585,7 @@ Skip this sub-step if the task is NOT a component implementation (e.g., bug fix,
    ⏱️  Total: 3m 18s | Agents: 12 calls | Files: 4 changed
    📦 Commit: abc1234 | PR: #87
    📖 Wiki: {ComponentName}.md pushed to wiki master
-   📋 Full report: .worktrees/PROJ-{id}/agent-log.md
+   📋 Full report: ~/.claude/logs/multi-agent/{project}/{task-id}/agent-log.md
    ```
 3. Log: `📋 Phase 7: Report complete`
 

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

@@ -49,3 +49,7 @@ Run the task end-to-end with no confirmations.
 2. **Set the autopilot flag**  -  `"autopilot": true` in `agent-state.json`
 3. **Start the multi-agent pipeline**  -  All confirmations are skipped
 4. **On failure**  -  After 3 retries still failing → pause, ask the user
+
+## Required: outward-facing payload contracts
+
+Before writing anything outward-facing  -  PR body, Jira comment, Confluence page, closing report  -  load `$HOME/.claude/multi-agent-refs/payload-contracts.md`. It names the canonical section set for each payload, the markup dialect per surface (PR body is Markdown, Jira is wiki markup  -  mixing them is a defect), and the token/duration numbers the closing report must carry. Improvising a payload shape from memory is the most common failure of the short modes.

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

@@ -12,7 +12,7 @@ argument-hint: "[\"<free-text description>\"] [figma-url] [swagger-url]  -  all
 
 Creates exactly one Jira issue, and only after explicit approval. The issue type (Task / Bug / Story) is asked at the start of every run. No branches, no commits, no worktrees. The description comes from the type's standard template (baseline, not a mined heading set); sections auto-size  -  a conditional section renders only when its trigger is present, otherwise the heading is omitted.
 
-> **Language**: issue content (summary + description) and user-facing questions follow `prefs.global.outputLanguage`  -  intentional exception to the "external payloads stay English" default (the issue is authored for the user's team). Code identifiers and URLs stay verbatim.
+> **Language**: issue content (summary + description) and user-facing questions follow `prefs.global.outputLanguage`, like every other user-facing payload body (`rules.md` matrix). Code identifiers and URLs stay verbatim.
 
 ## Standard templates (A = always, C = conditional)
 

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

@@ -64,23 +64,10 @@ Phase 7: Report     → Channels (Jira / Confluence / PR / Wiki)
 | Phase 7 channels (Jira / Confluence / PR / Wiki) | ✅ | ✅ (same) |
 | Duration | ~10-15 min | ~7-10 min |
 
-## Analysis doc supplied to a fast mode (warn before starting)
+## Required: outward-facing payload contracts
 
-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.
+Before writing anything outward-facing  -  PR body, Jira comment, Confluence page, closing report  -  load `$HOME/.claude/multi-agent-refs/payload-contracts.md`. It names the canonical section set for each payload, the markup dialect per surface (PR body is Markdown, Jira is wiki markup  -  mixing them is a defect), and the token/duration numbers the closing report must carry. Improvising a payload shape from memory is the most common failure of the short modes.
 
-Say so before starting, once, and offer the choice:
+## Intake warnings (`--dev` family)
 
-```
-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.
+Two checks belong at the top of every `--dev` run and are specified once in `$HOME/.claude/multi-agent-refs/phases/modes.md` "Intake warnings shared by the whole `--dev` family": an analysis document supplied to a mode that skips Analysis and Planning, and a branch that already carries the work (which wants `/multi-agent:ship`, not a second Dev pass). Read that section rather than reasoning about it from scratch.

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

@@ -55,3 +55,11 @@ Phase 7: Report     → Short terminal summary
 | Confirmation (test/commit/PR) | Yes | Yes | No | **No** |
 | Review | Parallel+triage (CLI-aware) | Parallel+triage (CLI-aware) | Parallel+triage (CLI-aware) | **Parallel+triage, auto-fix** |
 | Estimated duration | ~12 min | ~7 min | ~10 min | **~5 min** |
+
+## Required: outward-facing payload contracts
+
+Before writing anything outward-facing  -  PR body, Jira comment, Confluence page, closing report  -  load `$HOME/.claude/multi-agent-refs/payload-contracts.md`. It names the canonical section set for each payload, the markup dialect per surface (PR body is Markdown, Jira is wiki markup  -  mixing them is a defect), and the token/duration numbers the closing report must carry. Improvising a payload shape from memory is the most common failure of the short modes.
+
+## Intake warnings (`--dev` family)
+
+Two checks belong at the top of every `--dev` run and are specified once in `$HOME/.claude/multi-agent-refs/phases/modes.md` "Intake warnings shared by the whole `--dev` family": an analysis document supplied to a mode that skips Analysis and Planning, and a branch that already carries the work (which wants `/multi-agent:ship`, not a second Dev pass). Read that section rather than reasoning about it from scratch.

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

@@ -21,7 +21,7 @@ Phase 7: Report     → Jira/Wiki + log + knowledge/memory
 
 ## When to use it
 
-- Quick bug fix or small feature  -  review overhead is unnecessary
+- Quick bug fix or small feature  -  analysis and planning buy nothing here
 - You're working on the current branch and don't want to switch worktrees
 - Quick bug fix or small feature  -  analysis and planning buy nothing here
 
@@ -36,23 +36,10 @@ 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.
+## Required: outward-facing payload contracts
 
-Say so before starting, once, and offer the choice:
+Before writing anything outward-facing  -  PR body, Jira comment, Confluence page, closing report  -  load `$HOME/.claude/multi-agent-refs/payload-contracts.md`. It names the canonical section set for each payload, the markup dialect per surface (PR body is Markdown, Jira is wiki markup  -  mixing them is a defect), and the token/duration numbers the closing report must carry. Improvising a payload shape from memory is the most common failure of the short modes.
 
-```
-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
-```
+## Intake warnings (`--dev` family)
 
-Autopilot picks 1 and logs the warning rather than asking.
+Two checks belong at the top of every `--dev` run and are specified once in `$HOME/.claude/multi-agent-refs/phases/modes.md` "Intake warnings shared by the whole `--dev` family": an analysis document supplied to a mode that skips Analysis and Planning, and a branch that already carries the work (which wants `/multi-agent:ship`, not a second Dev pass). Read that section rather than reasoning about it from scratch.

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

@@ -41,3 +41,11 @@ Routes to the orchestrator with the `--dev --local autopilot` flags. The pipelin
 multi-agent-dev-local-autopilot "PROJ-12345"                   # Jira
 multi-agent-dev-local-autopilot "Add retry to HomeNetworking"  # Free-text
 ```
+
+## Required: outward-facing payload contracts
+
+Before writing anything outward-facing  -  PR body, Jira comment, Confluence page, closing report  -  load `$HOME/.claude/multi-agent-refs/payload-contracts.md`. It names the canonical section set for each payload, the markup dialect per surface (PR body is Markdown, Jira is wiki markup  -  mixing them is a defect), and the token/duration numbers the closing report must carry. Improvising a payload shape from memory is the most common failure of the short modes.
+
+## Intake warnings (`--dev` family)
+
+Two checks belong at the top of every `--dev` run and are specified once in `$HOME/.claude/multi-agent-refs/phases/modes.md` "Intake warnings shared by the whole `--dev` family": an analysis document supplied to a mode that skips Analysis and Planning, and a branch that already carries the work (which wants `/multi-agent:ship`, not a second Dev pass). Read that section rather than reasoning about it from scratch.