@mmerterden/multi-agent-pipeline 12.6.0 → 12.7.0

package/pipeline/commands/multi-agent/manual-test/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "Switch to the active task's branch and prepare it for manual testing in Xcode. Phase 5 standalone (the UI Bug Hunter lives at /multi-agent:test)."
+description: "Switch to the active task's branch and prepare it for manual testing in Xcode. Phase 5 standalone (the UI Bug Hunter lives at /multi-agent:test). Use when a finished change needs trying by hand on a device or simulator."
 description-tr: "Aktif görevin branch'ine geçer ve Xcode'da manuel test için hazırlar. Faz 5'in bağımsız hali (UI Bug Hunter /multi-agent:test'te)."
 ---
 

package/pipeline/commands/multi-agent/prune-logs/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "Delete per-task project logs under ~/.claude/logs/multi-agent (filter by age/project/task). Audit trail + metrics are preserved. Dry-run first; confirms before deleting."
+description: "Delete per-task project logs under ~/.claude/logs/multi-agent (filter by age/project/task). Audit trail + metrics are preserved. Dry-run first; confirms before deleting. Use when task logs have built up and need trimming by age, project or task."
 description-tr: "~/.claude/logs/multi-agent altındaki görev bazlı proje loglarını siler (yaş/proje/görev filtresi). Denetim izi + metrikler korunur. Önce dry-run; silmeden önce onay alır."
 argument-hint: "[--older-than=<days>] [--project=<name>] [--task=<id>] [--yes]"
 ---

package/pipeline/commands/multi-agent/purge/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "⚠️ Wipes every worktree, branch, log, and state file. Irreversible; asks for double confirmation."
+description: "⚠️ Wipes every worktree, branch, log, and state file. Irreversible; asks for double confirmation. Use when every worktree, branch, log and state file should be wiped and the pipeline reset."
 description-tr: "⚠️ Tüm worktree, branch, log ve state dosyalarını siler. Geri alınamaz; çift onay ister."
 ---
 

package/pipeline/commands/multi-agent/refactor/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "Analyse the project: extract adapted best-practices, hunt real bugs + improvement areas, check upstream drift of derived skills, research the companion dev-toolkit MCP server against current MCP practice, draft one plan, take approval, develop, then ask whether to sync."
+description: "Analyse the project: extract adapted best-practices, hunt real bugs + improvement areas, check upstream drift of derived skills, research the companion dev-toolkit MCP server against current MCP practice, draft one plan, take approval, develop, then ask whether to sync. Use when asked to review a project for bugs, gaps or improvements, or to check whether derived skills have drifted from upstream."
 description-tr: "Projeyi analiz eder: uyarlanmış best-practice'leri çıkarır, gerçek bug + iyileştirme alanlarını avlar, türetilmiş skill'lerin upstream drift'ini kontrol eder, dev-toolkit MCP sunucusunu güncel MCP pratiklerine göre araştırır, tek plan taslağı çıkarır, onay alır, geliştirir, sonra sync isteyip istemediğini sorar."
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion, WebFetch, WebSearch
 ---
@@ -75,19 +75,27 @@ The upstream mapping is **configuration, never hardcoded** (it can reference pri
   "upstreamPlugin": "<plugin name>",
   "upstreamSkills": ["<skill-a>", "<skill-b>"],            // the upstream skills we took
   "derivedFromVersion": "<x.y.z>",                         // the version we last synced from
-  "upstreamRepoUrl": "<optional https url>"                // used only if the marketplace is not installed locally
+  "upstreamVersionSource": "marketplace.json",             // which manifest is authoritative; default marketplace.json
+  "upstreamLocalClone": "<optional path>",                 // working copy of the upstream repo, preferred over the cache
+  "upstreamRepoUrl": "<optional https url>"                // used when neither a clone nor the marketplace is available
 }
 ```
 
+**The plugin cache is a mirror, not the authority.** `~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/` only holds whatever the last `claude marketplace update` fetched. Reading it as the current upstream version is how this step reported "up to date" while the derivation was four releases behind: the cache sat at 0.2.1 and upstream was at 0.4.1. Resolve in the order below and never let the cache alone produce an "up to date" verdict.
+
+**Which manifest carries the version** is `upstreamVersionSource`, default `marketplace.json`. That is what a marketplace consumer actually resolves, and some upstreams keep per-plugin `plugin.json` versions deliberately unused - reading those records a version nobody ships. An entry here was recorded at 0.7.0 from `plugin.json` while the upstream marketplace said 0.6.0 and its CHANGELOG stated in as many words that `plugin.json` is not used.
+
 Procedure:
 1. If `global.derivedSkillSources` is missing or empty -> **skip** this step and report "no derived-skill sources configured" (nothing to check). Never invent a source.
-2. For each entry, resolve the current upstream version:
-   - **Preferred**: read the newest installed version under `~/.claude/plugins/cache/<upstreamMarketplace>/<upstreamPlugin>/*/` (its `.claude-plugin/plugin.json` `version`), plus that version's `CHANGELOG.md`.
-   - **Fallback**: if the marketplace is not installed locally and `upstreamRepoUrl` is set, `WebFetch` the upstream `plugin.json` + `CHANGELOG.md`.
-   - If neither is reachable, record the entry as "upstream unreachable" and move on (do not fail the whole run).
+2. For each entry, resolve the current upstream version, in this order, stopping at the first that answers:
+   - **`upstreamLocalClone`** if set: read `<clone>/.claude-plugin/<upstreamVersionSource>`. Also run `git -C <clone> fetch --dry-run` (or compare against `@{u}`) and say so when the clone is itself behind, so a stale working copy is not silently trusted either.
+   - **`upstreamRepoUrl`**: read the same manifest over the API (`gh api` / `WebFetch`). A private upstream can 404 for the currently active account even when the repo exists - that is an unreachable result, not a "no drift" result.
+   - **Plugin cache** under `~/.claude/plugins/cache/<upstreamMarketplace>/<upstreamPlugin>/*/`: last resort only. When the cache is the only source that answered, report the entry as **`unverified (cache only)`**, never as "up to date", and add a plan item to configure `upstreamLocalClone`.
+   - If nothing is reachable, record the entry as "upstream unreachable" and move on (do not fail the whole run).
 3. Compare the resolved upstream version to `derivedFromVersion`:
-   - equal -> "up to date" (no drift)
-   - newer -> **drift**: read the CHANGELOG entries between the two versions, and diff each `upstreamSkills` SKILL.md (+ any templates) against our `localPath` copy. Summarize what changed upstream (bug fixes, new sections, new templates, renamed inputs).
+   - equal, from an authoritative source -> "up to date" (no drift)
+   - equal, from the cache only -> "unverified (cache only)"
+   - newer -> **drift**: read the CHANGELOG entries between the two versions, and diff each `upstreamSkills` SKILL.md (+ any templates) against our `localPath` copy. Summarize what changed upstream (bug fixes, new sections, new templates, renamed inputs). Ignore changelog entries that only touch skills outside `upstreamSkills` - they are not ours to port.
 4. Emit the drift table (plan band D):
 
 ```

package/pipeline/commands/multi-agent/resume/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "Resume a stopped or failed task from the phase where it left off."
+description: "Resume a stopped or failed task from the phase where it left off. Use when a task stopped or failed and should carry on from where it left off."
 description-tr: "Durmuş veya hata almış bir görevi kaldığı fazdan devam ettirir."
 argument-hint: "[#id]  -  optional: task ID (e.g. #2). If omitted, the most recent paused task is used."
 ---
@@ -10,7 +10,7 @@ argument-hint: "[#id]  -  optional: task ID (e.g. #2). If omitted, the most rece
 
 Resume a paused or failed task from the last successful phase.
 
-> **Not the same as `/multi-agent:finish`.** `resume` continues a **tracked pipeline task** (needs its `agent-state.json`/worktree) from where it stopped. `/multi-agent:finish` takes **ad-hoc local work** on the current branch (no prior task required) and runs the pipeline tail — Review → Build+Test → PR → Jira report — over it.
+> **Not the same as `/multi-agent:finish`.** `resume` continues a **tracked pipeline task** (needs its `agent-state.json`/worktree) from where it stopped. `/multi-agent:finish` takes **ad-hoc local work** on the current branch (no prior task required) and runs the pipeline tail - Review → Build+Test → PR → Jira report - over it.
 
 ## Steps
 

package/pipeline/commands/multi-agent/review/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "Run parallel review on a branch's diff or a Pull Request: 2 models on Claude Code (Fable + Sonnet), 3 models on Copilot CLI (GPT + Opus + Sonnet). On PR input, posts per-finding inline comments and sets approve/needs-work review state."
+description: "Run parallel review on a branch's diff or a Pull Request: 2 models on Claude Code (Fable + Sonnet), 3 models on Copilot CLI (GPT + Opus + Sonnet). On PR input, posts per-finding inline comments and sets approve/needs-work review state. Use when a branch diff or a pull request needs reviewing before it merges."
 description-tr: "Bir branch diff'i veya Pull Request üzerinde paralel review koşar: Claude Code'da 2 model (Fable + Sonnet), Copilot CLI'da 3 model (GPT + Opus + Sonnet). PR girdisinde bulgu başına inline yorum atar ve approve/needs-work durumunu işaretler."
 argument-hint: "[#N | repo#N | PR-URL | branch]  -  optional: PR by number/URL, repo+number, or local branch. Supports GitHub and Bitbucket Server URLs. If omitted (interactive), open GitHub + Bitbucket PRs are listed for multi-select; autopilot falls back to the current branch."
 ---

package/pipeline/commands/multi-agent/review-issue/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "Assess whether a GitHub issue is ready for multi-agent development: fetch it, grade scope / acceptance criteria / repro / design / API / stack readiness, then (after confirm) post the gaps as an issue comment. Read-only on code."
+description: "Assess whether a GitHub issue is ready for multi-agent development: fetch it, grade scope / acceptance criteria / repro / design / API / stack readiness, then (after confirm) post the gaps as an issue comment. Read-only on code. Use when deciding whether a GitHub issue is specified well enough to hand to development."
 description-tr: "Bir GitHub issue'sunun multi-agent geliştirmeye hazır olup olmadığını değerlendirir: getirir; kapsam / kabul kriterleri / repro / tasarım / API / stack hazırlığını puanlar, sonra (onay sonrası) eksikleri issue yorumu olarak gönderir. Kodda salt-okunur."
 argument-hint: "[#N | repo#N | GitHub issue URL]  -  optional; with no argument, pick from open issues"
 ---

package/pipeline/commands/multi-agent/review-jira/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "Assess whether a Jira issue is ready for multi-agent development: fetch it, grade scope / acceptance criteria / repro / design / API / stack readiness, then (after confirm) post the gaps as a Jira comment. Read-only on code."
+description: "Assess whether a Jira issue is ready for multi-agent development: fetch it, grade scope / acceptance criteria / repro / design / API / stack readiness, then (after confirm) post the gaps as a Jira comment. Read-only on code. Use when deciding whether a Jira issue is specified well enough to hand to development."
 description-tr: "Bir Jira issue'sunun multi-agent geliştirmeye hazır olup olmadığını değerlendirir: getirir; kapsam / kabul kriterleri / repro / tasarım / API / stack hazırlığını puanlar, sonra (onay sonrası) eksikleri Jira yorumu olarak gönderir. Kodda salt-okunur."
 argument-hint: "[JIRA-KEY | Jira URL]  -  optional; with no argument, pick from your open Jira issues"
 ---

package/pipeline/commands/multi-agent/routines/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "List your saved /multi-agent routines (from /multi-agent:save) with what each one does, rendered in outputLanguage."
+description: "List your saved /multi-agent routines (from /multi-agent:save) with what each one does, rendered in outputLanguage. Use when asked which saved routines exist or what one of them does."
 description-tr: "Kaydettiğin /multi-agent rutinlerini (/multi-agent:save ile) listeler; her birinin ne yaptığını outputLanguage'e göre gösterir."
 argument-hint: ""
 allowed-tools: Bash, Read

package/pipeline/commands/multi-agent/save/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "Save a recurring job as a reusable /multi-agent:<name> command. Reviews the conversation + your CLAUDE.md for candidate routines, you pick one and name it; it is stored local-only and never synced."
+description: "Save a recurring job as a reusable /multi-agent:<name> command. Reviews the conversation + your CLAUDE.md for candidate routines, you pick one and name it; it is stored local-only and never synced. Use when a job keeps recurring and should become its own reusable command."
 description-tr: "Sık yaptığın bir işi yeniden kullanılabilir /multi-agent:<ad> komutu olarak kaydeder. Konuşmayı + CLAUDE.md'ni tarayıp aday rutinler önerir, sen seçip ad verirsin; local-only saklanır, asla sync edilmez."
 argument-hint: "[name]  -  optional command name; asked if omitted"
 allowed-tools: Bash, Read, AskUserQuestion

package/pipeline/commands/multi-agent/scan/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "Skill security scan: walks local skill directories against a tiered pattern catalog."
+description: "Skill security scan: walks local skill directories against a tiered pattern catalog. Use when local skill directories need checking for unsafe or unexpected content."
 description-tr: "Skill güvenlik taraması: yerel skill dizinlerini kademeli desen kataloğuna göre tarar."
 allowed-tools: Bash, Read
 argument-hint: "[--strict] [--threshold critical|high|medium|low] [--json] [--root PATH]"

package/pipeline/commands/multi-agent/search/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "Log search across every agent-log.md with smart ranking and filters. Optional --semantic flag queries the per-repo triage corpus."
+description: "Log search across every agent-log.md with smart ranking and filters. Optional --semantic flag queries the per-repo triage corpus. Use when something has to be found across past task logs."
 description-tr: "Tüm agent-log.md dosyalarında akıllı sıralama ve filtrelerle log araması. İsteğe bağlı --semantic bayrağı repo bazlı triyaj korpusunu sorgular."
 allowed-tools: Bash, Read
 argument-hint: "\"query\" [--project NAME] [--since 7d] [--phase N] [--semantic] [--json|--tsv]"

package/pipeline/commands/multi-agent/setup/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "First-run setup wizard: keychain token discovery, Git Identity onboarding, and pipeline preparation."
+description: "First-run setup wizard: keychain token discovery, Git Identity onboarding, and pipeline preparation. Use when the pipeline is being set up for the first time, or tokens and git identity need onboarding."
 description-tr: "İlk kurulum sihirbazı: keychain token keşfi, Git Identity kaydı ve pipeline hazırlığı."
 allowed-tools: Bash, Read, Write, AskUserQuestion, WebFetch
 ---
@@ -823,4 +823,4 @@ Stack skills ship as versioned plugins in the `{owner}/multi-agent-plugins` mark
    `ai-common-engineering-toolkit@multi-agent-plugins` is always set `true` alongside the stack plugin.
 3. Report the enabled set. To change later, run `/multi-agent:stack <ios|android|frontend|backend|...>` in the repo. Pipeline Phase 1 auto-detects the stack for its own routing regardless of enablement.
 
-The marketplace repo name (`multi-agent-plugins`) is generic; a different org points `{owner}` at its own fork — nothing in the pipeline is coupled to a specific account.
+The marketplace repo name (`multi-agent-plugins`) is generic; a different org points `{owner}` at its own fork - nothing in the pipeline is coupled to a specific account.

package/pipeline/commands/multi-agent/stack/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "Select the active stack for this repo by enabling the matching marketplace plugin(s) in .claude/settings.json (ios/android/mobile/backend/frontend/fullstack/all)."
+description: "Select the active stack for this repo by enabling the matching marketplace plugin(s) in .claude/settings.json (ios/android/mobile/backend/frontend/fullstack/all). Use when a repo's stack changed or the wrong plugins are enabled for it."
 description-tr: "Bu repo için aktif stack'i seçer: eşleşen marketplace plugin'lerini .claude/settings.json'da etkinleştirir (ios/android/mobile/backend/frontend/fullstack/all)."
 allowed-tools: Bash, Read, Edit, Write
 ---
@@ -8,7 +8,7 @@ allowed-tools: Bash, Read, Edit, Write
 
 Stack skills ship as plugins in the `{owner}/multi-agent-plugins` marketplace. Selecting a stack = **enabling the matching plugin(s)** in the current repo's `.claude/settings.json` `enabledPlugins`. The `ai-common-engineering-toolkit` (accessibility audit, humanizer, Firebase) is always enabled alongside the stack plugin.
 
-This replaces the old `stack-swap.sh` mechanic that physically moved skill directories in `~/.claude/skills/`. There is no SessionStart hook and no directory shuffling — enablement is declarative, per-repo, and versioned.
+This replaces the old `stack-swap.sh` mechanic that physically moved skill directories in `~/.claude/skills/`. There is no SessionStart hook and no directory shuffling - enablement is declarative, per-repo, and versioned.
 
 ## Usage
 
@@ -89,7 +89,7 @@ Use the Read + Edit/Write tools (JSON must stay valid). Then print the resulting
 
 ## Notes
 
-- Enablement is per-repo and declarative — commit `.claude/settings.json` so teammates get the same stack.
+- Enablement is per-repo and declarative - commit `.claude/settings.json` so teammates get the same stack.
 - Restart the conversation (or reload the window) for Claude Code to pick up newly enabled plugins.
 - Pipeline Phase 1 stack detection is independent (it reads project files); `stack` only sets which plugin skill set is active.
 - The old `stack-swap.sh` skill-dir swap has been removed; stack selection is entirely plugin enablement.

package/pipeline/commands/multi-agent/status/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "Show every multi-agent task's ID, phase, branch, and status."
+description: "Show every multi-agent task's ID, phase, branch, and status. Use when asked what is running, or for an overview of every task."
 description-tr: "Tüm multi-agent görevlerinin ID, faz, branch ve durumunu gösterir."
 ---
 

package/pipeline/commands/multi-agent/sync/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "One-shot sync of the entire multi-agent ecosystem: Claude Code, Copilot CLI, pipeline repo, website, and the dev-toolkit MCP server."
+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."
 description-tr: "Tüm multi-agent ekosisteminin tek atımlık senkronu: Claude Code, Copilot CLI, pipeline repo, website ve dev-toolkit MCP sunucusu."
 argument-hint: "[release] [dev-toolkit] [--platform=<macos|linux|windows>]"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, WebFetch
@@ -125,7 +125,7 @@ If nothing is stale → report "All targets up to date" and stop.
    - `~/.claude/CLAUDE.md`, `~/.claude/rules/`, `~/.claude/knowledge/`
    - `~/.claude/scripts/`  -  EXCEPT `pre-commit-check.sh`, `agent-guard.sh`, `agent-guard.py`, and `build-stack-plugins.mjs` (generic, synced)
    - `~/.claude/settings.json`
-   - **Any `~/.claude/commands/multi-agent/*.md` whose frontmatter has `local-only: true`** — these are user/repo-specific alias wrappers that delegate to a private marketplace plugin (e.g. corporate `ai-ios-engineering-toolkit` skills exposed as `multi-agent:<name>`). Syncing them would leak the private plugin/skill names into the public pipeline. Filter before copy: skip every source file containing `local-only: true`, and after copy assert none reached `pipeline/commands/`.
+   - **Any `~/.claude/commands/multi-agent/*.md` whose frontmatter has `local-only: true`** - these are user/repo-specific alias wrappers that delegate to a private marketplace plugin (e.g. corporate `ai-ios-engineering-toolkit` skills exposed as `multi-agent:<name>`). Syncing them would leak the private plugin/skill names into the public pipeline. Filter before copy: skip every source file containing `local-only: true`, and after copy assert none reached `pipeline/commands/`.
      ```bash
      # backstop: no local-only wrapper may exist in the synced target
      grep -rl "^local-only: true" ~/multi-agent-pipeline/pipeline/commands/ 2>/dev/null \
@@ -192,7 +192,7 @@ node "$HOME/multi-agent-pipeline/pipeline/scripts/build-stack-plugins.mjs" --dry
 node "$HOME/multi-agent-pipeline/pipeline/scripts/build-stack-plugins.mjs"
 ```
 
-**Version-based management:** the generator bumps a plugin's `version` (patch) only when its skill set actually changed. Idempotent — a no-op run bumps nothing. Consumers pick up new versions via `/multi-agent:update` (which runs `claude marketplace update multi-agent-plugins`).
+**Version-based management:** the generator bumps a plugin's `version` (patch) only when its skill set actually changed. Idempotent - a no-op run bumps nothing. Consumers pick up new versions via `/multi-agent:update` (which runs `claude marketplace update multi-agent-plugins`).
 
 **Publish (only if the generator reported bumps):**
 
@@ -207,7 +207,7 @@ if ! git diff --quiet; then
 fi
 ```
 
-Never author skills directly in the plugins repo's `knowledge/` — they will be overwritten on the next rebuild. Author in `shared/external`, then run this step.
+Never author skills directly in the plugins repo's `knowledge/` - they will be overwritten on the next rebuild. Author in `shared/external`, then run this step.
 
 ---
 
@@ -357,7 +357,7 @@ When invoked with the `release` argument:
 
 ## Sub-Command Sync (Claude Code <-> Copilot CLI Skills)
 
-This runs on the Claude <-> Copilot axis — the two CLIs the pipeline supports natively.
+This runs on the Claude <-> Copilot axis - the two CLIs the pipeline supports natively.
 
 | Claude Code | Copilot CLI |
 |-------------|-------------|

package/pipeline/commands/multi-agent/test/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "UI Bug Hunter  -  iOS Simulator (simctl) + Android Emulator (adb). Auto-detects platform. Screenshot + tap + analyze on the booted device. The Phase 5 Manual Test flow lives at /multi-agent:manual-test."
+description: "UI Bug Hunter  -  iOS Simulator (simctl) + Android Emulator (adb). Auto-detects platform. Screenshot + tap + analyze on the booted device. The Phase 5 Manual Test flow lives at /multi-agent:manual-test. Use when a running app should be driven on a simulator or emulator to hunt UI bugs."
 description-tr: "UI Bug Hunter - iOS Simulator (simctl) + Android Emulator (adb). Platformu otomatik algılar. Açık cihazda screenshot + tap + analiz. Faz 5 Manuel Test akışı /multi-agent:manual-test'te."
 argument-hint: '[scenario]  -  e.g. "dark mode" | "accessibility" | "dynamic type" | "screenshot tr" | "store-ready" | (empty = full sweep)'
 ---

package/pipeline/commands/multi-agent/uninstall/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "Uninstall the pipeline from Claude Code + Copilot CLI. Keychain access tokens are always left untouched; --all-data also clears pipeline settings and logs. Asks for double confirmation."
+description: "Uninstall the pipeline from Claude Code + Copilot CLI. Keychain access tokens are always left untouched; --all-data also clears pipeline settings and logs. Asks for double confirmation. Use when the pipeline should be removed from Claude Code and Copilot CLI."
 description-tr: "Pipeline'ı Claude Code + Copilot CLI'dan kaldırır. Keychain erişim token'larına asla dokunulmaz; --all-data ayrıca pipeline ayarlarını ve loglarını da siler. Çift onay ister."
 argument-hint: "[--dry-run] [--all-data] [--claude] [--copilot] [--target=<path>]"
 ---

package/pipeline/commands/multi-agent/update/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "Update the pipeline to the latest version: git pull, install, migrate."
+description: "Update the pipeline to the latest version: git pull, install, migrate. Use when the installed pipeline is behind and should be brought to the latest version."
 description-tr: "Pipeline'ı son sürüme günceller: git pull, install, migrate."
 allowed-tools: Bash, Read, Write, AskUserQuestion
 ---
@@ -52,13 +52,13 @@ Update the pipeline in one command. Existing preferences are preserved; only ski
    fi
    ```
 
-4c. **Prune retired adapter files** (Cursor / Antigravity / Codex / Copilot Chat were removed in v10.7.0 — the pipeline now targets Claude Code + Copilot CLI only):
+4c. **Prune retired adapter files** (Cursor / Antigravity / Codex / Copilot Chat were removed in v10.7.0 - the pipeline now targets Claude Code + Copilot CLI only):
    ```bash
    # Global Codex adapter prompt is safe to remove (no longer produced).
    rm -f "$HOME/.codex/prompts/multi-agent.md"
    echo "  -> pruned retired global Codex adapter prompt (if present)"
    # Per-project adapter files (.cursor/, .agent/, .github/copilot-instructions.md)
-   # live in your repos and are left untouched — remove them manually if you like.
+   # live in your repos and are left untouched - remove them manually if you like.
    ```
 
 5. **Migrate preferences** (if there is an old schema):

package/pipeline/eval/run-metrics-fixture.json

@@ -2,29 +2,76 @@
   "taskId": "PROJ-101",
   "status": "complete",
   "currentPhase": 7,
-  "projects": [
-    { "project": "my-ios-app", "buildStatus": { "ok": true, "attempts": 1 } }
-  ],
+  "projects": [{ "project": "my-ios-app", "buildStatus": { "ok": true, "attempts": 1 } }],
   "reviewIterations": [
     {
       "reviewers": [
-        { "reviewer": "opus", "findings": [
-          { "severity": "blocking", "file": "Auth/Session.swift", "line": 54, "issue": "token logged in plaintext", "fix": "redact" },
-          { "severity": "suggestion", "file": "Auth/Session.swift", "line": 12, "issue": "rename helper", "fix": "rename" }
-        ], "approved": false },
-        { "reviewer": "sonnet", "findings": [
-          { "severity": "important", "file": "Auth/Session.swift", "line": 70, "issue": "no migration for legacy token", "fix": "add migration" }
-        ], "approved": false }
+        {
+          "reviewer": "opus",
+          "findings": [
+            {
+              "severity": "blocking",
+              "file": "Auth/Session.swift",
+              "line": 54,
+              "issue": "token logged in plaintext",
+              "fix": "redact"
+            },
+            {
+              "severity": "suggestion",
+              "file": "Auth/Session.swift",
+              "line": 12,
+              "issue": "rename helper",
+              "fix": "rename"
+            }
+          ],
+          "approved": false
+        },
+        {
+          "reviewer": "sonnet",
+          "findings": [
+            {
+              "severity": "important",
+              "file": "Auth/Session.swift",
+              "line": 70,
+              "issue": "no migration for legacy token",
+              "fix": "add migration"
+            }
+          ],
+          "approved": false
+        }
       ],
       "triage": {
         "accepted": [
-          { "severity": "blocking", "file": "Auth/Session.swift", "line": 54, "issue": "token logged in plaintext", "fix": "redact the token in the log", "reviewer": "opus" }
+          {
+            "severity": "blocking",
+            "file": "Auth/Session.swift",
+            "line": 54,
+            "issue": "token logged in plaintext",
+            "fix": "redact the token in the log",
+            "reviewer": "opus"
+          }
         ],
         "deferred": [
-          { "finding": { "severity": "important", "file": "Auth/Session.swift", "line": 70, "issue": "no migration for legacy token" }, "reason": "follow-up PR" }
+          {
+            "finding": {
+              "severity": "important",
+              "file": "Auth/Session.swift",
+              "line": 70,
+              "issue": "no migration for legacy token"
+            },
+            "reason": "follow-up PR"
+          }
         ],
         "rejected": [
-          { "finding": { "severity": "suggestion", "file": "Auth/Session.swift", "line": 12, "issue": "rename helper" }, "reason": "style only" }
+          {
+            "finding": {
+              "severity": "suggestion",
+              "file": "Auth/Session.swift",
+              "line": 12,
+              "issue": "rename helper"
+            },
+            "reason": "style only"
+          }
         ],
         "approved": false
       }

package/pipeline/lib/account-resolver.sh

@@ -18,7 +18,7 @@
 # Output schema (per account):
 #   { id, label, prefix, providers[], tokens{}, jiraHost, bitbucketHost, isWork }
 
-set -eu
+set -euo pipefail
 
 PRETTY=0
 FILTER=""

package/pipeline/lib/channels-multi-repo.sh

@@ -15,7 +15,7 @@
 # Single-repo tasks: every subcommand falls through to the single PR / single
 # body  -  `targets` returns one entry, render-* leaves the body unchanged.
 
-set -eu
+set -euo pipefail
 
 CMD="${1:-}"
 STATE="${2:-}"

package/pipeline/lib/context-link-extractor.sh

@@ -41,7 +41,7 @@
 #   0  always  -  emits "[]" when no input or no matches; downstream readers
 #               must tolerate an empty array.
 
-set -eu
+set -euo pipefail
 
 CONTEXT_LINK_INPUT=$(cat)
 export CONTEXT_LINK_INPUT

package/pipeline/lib/credential-store.sh

@@ -25,7 +25,7 @@
 # Returns 0 on success, 1 on missing/empty value, 2 on backend missing,
 # 3 on usage error.
 
-set -eu
+set -euo pipefail
 
 detect_platform() {
   case "$(uname -s 2>/dev/null)" in

package/pipeline/lib/fetch-confluence.sh

@@ -41,7 +41,7 @@
 #   and exits 2  -  the orchestrator handles the Save Flow + retry. The script
 #   itself never prompts.
 
-set -eu
+set -euo pipefail
 
 URL=""
 HOST_OVERRIDE="${CONFLUENCE_HOST_OVERRIDE:-}"

package/pipeline/lib/fetch-crashlytics.sh

@@ -45,7 +45,7 @@
 #   orchestrator surfaces this as "fetcher unavailable, advisory only" to
 #   keep the pipeline moving.
 
-set -eu
+set -euo pipefail
 
 URL=""
 PROJECT_ID=""

package/pipeline/lib/fetch-fortify.sh

@@ -46,7 +46,7 @@
 #   High > 0       → blocking=false, reason="high-findings-warning"
 #   else           → blocking=false, reason="clean"
 
-set -eu
+set -euo pipefail
 
 URL=""
 VERSION_ID=""

package/pipeline/lib/fetch-graylog.sh

@@ -47,7 +47,7 @@
 #   4  bad usage
 #   6  host not configured (prefs.global.hosts.graylog is empty)
 
-set -eu
+set -euo pipefail
 
 TRX_ID=""
 CONV_ID=""

package/pipeline/lib/fetch-swagger.sh

@@ -42,7 +42,7 @@
 #   3  payload too large or malformed
 #   4  bad usage
 
-set -eu
+set -euo pipefail
 
 URL="${1:-}"
 [ -z "$URL" ] && { echo "usage: $0 <openapi-url>" >&2; exit 4; }

package/pipeline/lib/issue-fetcher.sh

@@ -34,7 +34,7 @@
 #   ACCOUNT_DEFAULT_REPO      fallback GitHub repo  (optional)
 #   PROMPT_LANG               tr|en  -  controls maturity.summary language (default: tr)
 
-set -eu
+set -euo pipefail
 
 INPUT="${1:-}"
 [ -z "$INPUT" ] && { echo '{"error":"input required"}'; exit 1; }

package/pipeline/lib/multi-repo-pipeline.sh

@@ -28,7 +28,7 @@
 # `bridge` writes agent-state.json v2.1.0 with projects[] populated  -  Phase 0
 # consumes this and skips its own picker steps.
 
-set -eu
+set -euo pipefail
 
 CMD="${1:-}"
 STATE="${2:-}"

package/pipeline/lib/repo-cache.sh

@@ -25,7 +25,7 @@
 #                LOCAL_SCAN_ROOTS env can override the default root list.
 #                LOCAL_SCAN_MAXDEPTH env (default 4) bounds traversal cost.
 
-set -eu
+set -euo pipefail
 
 PROVIDER="${1:-}"
 SCOPE="${2:-}"

package/pipeline/lib/submodule-detector.sh

@@ -24,7 +24,7 @@
 #   ]
 #
 
-set -eu
+set -euo pipefail
 
 MODE="local"
 TARGET="${1:-}"

package/pipeline/multi-agent-refs/component-dispatch.md

@@ -84,7 +84,7 @@ Phase 4 reviewer-skipping is **not** Phase 3's concern  -  Phase 4 decides based
 
 ## Cross-CLI behaviour (intentional divergence)
 
-Component dispatch is **no longer byte-identical across CLIs** and that is by design (see `cross-cli-contract.md` §1.1):
+Component dispatch is **no longer byte-identical across CLIs** and that is by design (see `cross-cli-contract.md` section 1.1):
 
 - **Claude Code**: dispatches to the enabled `ai-<platform>-engineering-toolkit` marketplace plugin via the Skill tool (this doc).
 - **Copilot CLI**: has no plugin loader; it continues to use its standalone `~/.copilot/skills/figma-*` skill copies (frozen fallback). Copilot's resolution + progress lines follow those local skills.