@mmerterden/multi-agent-pipeline 14.2.2 → 15.1.0

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

@@ -3,14 +3,14 @@ name: multi-agent-refactor
 language: en
 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."
 user-invocable: true
-argument-hint: 'bugs | best-practices | drift | dev-toolkit | security | tests | performance | docs | ci | deps'
+argument-hint: 'bugs | best-practices | drift | dev-toolkit | run-errors | security | tests | performance | docs | ci | deps'
 ---
 
 # Multi-Agent Refactor
 
 **One command. Best-practices + Bug hunt + Upstream drift + Dev-toolkit -> Score -> Plan -> Approval -> Develop -> Sync.**
 
-Deep-analyses the current project, extracts the global best-practices worth adopting (adapted to our stack), hunts real bugs and improvement areas, checks whether any skills we derived from an upstream source have drifted, researches the companion dev-toolkit MCP server against current MCP practice, scores everything, drafts a single prioritized plan, takes approval, applies the approved items, and asks about sync when done.
+Deep-analyses the current project, extracts the global best-practices worth adopting (adapted to our stack), hunts real bugs and improvement areas, checks whether any skills we derived from an upstream source have drifted, researches the companion dev-toolkit MCP server against current MCP practice, scores everything, drafts a single prioritized plan, asks the user for approval, applies the approved items, and asks about sync at the end.
 
 **Input**: $ARGUMENTS (optional  -  area to focus on: "security", "performance", "tests", "bugs", "best-practices", "drift", "dev-toolkit", etc.)
 
@@ -20,14 +20,15 @@ Deep-analyses the current project, extracts the global best-practices worth adop
 Step 0:  BEST-PRACTICES  Research the field, extract the best approaches, ADAPT them to our stack -> plan band A
 Step 0b: DRIFT           Check upstream-derived skills for updates we have not pulled -> plan band D
 Step 0c: DEV-TOOLKIT     Research current MCP practice + audit the companion dev-toolkit repo -> plan band E
-Step 1:  SCAN            Scan the project structure (files, LOC, dependencies, CI, tests)
+Step 0d: RUN-ERRORS      Read the local run-error ledger, rank recurring failures -> plan band F
+Step 1:  SCAN            Walk the project structure (files, LOC, dependencies, CI, tests)
 Step 2:  ANALYZE         10 categories + an explicit BUG HUNT (real defects, not just scores) -> plan bands B, C
-Step 3:  SCORE           Each category out of 10, total /100
-Step 4:  PLAN            Merge bands A (best-practice) + B (bugs) + C (improvements) + D (drift) + E (dev-toolkit)
-Step 5:  ASK             "Shall I start developing?"  -  take approval
-Step 6:  IMPLEMENT       Apply approved items in order (lint, test, commit)
-Step 7:  VERIFY          Confirm all tests + lint pass
-Step 8:  ASK SYNC        "Shall I run multi-agent-sync?"  -  take approval
+Step 3:  SCORE           Each category /10, overall /100
+Step 4:  PLAN            Merge bands A (best-practice) + B (bugs) + C (improvements) + D (drift) + E (dev-toolkit) + F (run-errors)
+Step 5:  ASK             "Start the work?"  -  wait for user approval
+Step 6:  IMPLEMENT       Apply approved items one by one (lint, test, commit)
+Step 7:  VERIFY          Confirm every test + lint passes
+Step 8:  ASK SYNC        "Run /multi-agent:sync?"  -  wait for user approval
 ```
 
 Plan bands (all five feed the single Step 4 table):
@@ -36,19 +37,24 @@ Plan bands (all five feed the single Step 4 table):
 - **C - Improvement**: quality/perf/DX gaps surfaced by the 10-category analysis.
 - **D - Drift**: upstream updates to skills we derived from an external source.
 - **E - Dev-toolkit**: current-practice gaps in the companion dev-toolkit MCP server (the pipeline's device and browser hands), applied in that repo.
+- **F - Run-errors**: recurring real failures the pipeline actually hit across past runs, read from the local run-error ledger. These are lived evidence, not speculation - a failure that recurs across users or tasks is a prioritized improvement area.
 
 ## Step 0: BEST-PRACTICES  -  research the field, adapt to us
 
 Do not copy features blindly. The goal is the best *approaches*, reshaped so they are applicable to THIS project's stack, size, and constraints.
 
-1. **Identify the domain** (read README + package/build manifests): kind of project, stack, users.
+1. **Identify the domain** of the current project (read README + package/build manifests): what kind of project is it (CLI, SDK, app, pipeline, library), what stack, who uses it.
 2. **Research the best-in-class** for that exact domain:
    - **GitHub**: search the domain terms + `stars:>50`; read the top repos' READMEs, architecture docs, CI configs, test layout.
-   - **X / Twitter**: search the domain terms + "best practices" / "we switched to" / "lesson learned"; capture what practitioners recommend right now (WebFetch/WebSearch on `x.com` / `twitter.com` threads).
+   - **X / Twitter**: search the domain terms + "best practices" / "we switched to" / "lesson learned"; capture what practitioners and tool authors actually recommend right now (WebFetch/WebSearch on `x.com` / `twitter.com` threads).
    - **Reddit**: relevant subreddits for real-world pain points and adopted patterns.
-   - **Web**: "<domain> best practices <current-year>", official style guides, platform guidance.
-3. **For each candidate approach, record**: what it is + source, the concrete benefit, the **adaptation** (exactly how it looks in OUR repo: which file/dir/script and what changes), effort (L/M/H), impact (L/M/H/Critical).
-4. **Discard** approaches that do not fit our stack/scale/constraints  -  and say WHY.
+   - **Web**: "<domain> best practices <current-year>", official style guides, and the platform's own guidance.
+3. **For each candidate approach, record**:
+   - what it is, who does it well (source link)
+   - the concrete benefit
+   - **adaptation**: exactly how it would look in OUR repo (which file/dir/script), and what has to change for it to fit  -  not a generic "add tests" but "add a flow-assertion helper in `test/helpers/`"
+   - effort (Low/Med/High) and impact (Low/Med/High/Critical)
+4. **Discard** approaches that do not fit our stack, our scale, or our constraints  -  and say WHY (so the user sees the filter working, not just the survivors).
 
 Output (plan band A):
 ```
@@ -79,21 +85,21 @@ The upstream mapping is **configuration, never hardcoded** (it can reference pri
 }
 ```
 
-**The plugin cache is a mirror, not the authority.** `~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/` holds only what the last `claude marketplace update` fetched. Treating 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.
+**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 resolves. Some upstreams keep per-plugin `plugin.json` versions deliberately unused, so reading those records a version nobody ships. One entry here was recorded at 0.7.0 from `plugin.json` while the upstream marketplace said 0.6.0 and its CHANGELOG said plainly that `plugin.json` is not used.
+**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". Never invent a source.
-2. For each entry, resolve the current upstream version, stopping at the first source that answers:
-   - **`upstreamLocalClone`** if set: read `<clone>/.claude-plugin/<upstreamVersionSource>`, and report when the clone is itself behind its remote so a stale working copy is not silently trusted.
-   - **`upstreamRepoUrl`**: read the same manifest over the API (`gh api` / `WebFetch`). A private upstream can 404 for the active account even though it exists; that is unreachable, not "no drift".
-   - **Plugin cache**: last resort. When it is the only source that answered, report **`unverified (cache only)`**, never "up to date", and add a plan item to configure `upstreamLocalClone`.
-   - If nothing is reachable, record "upstream unreachable" and move on (do not fail the run).
+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, 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, 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 (+ templates) against our `localPath` copy. Summarize what changed, ignoring entries that touch only skills outside `upstreamSkills`.
+   - 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):
 
 ```
@@ -102,40 +108,63 @@ Procedure:
 | <label>    | <path>               | 0.2.1        | 0.3.0        | YES   | <changelog + diff summary> |
 ```
 
-5. For each drifted entry, add a band-D plan item: "port upstream <plugin> <version> changes into <localPath>". Do not auto-apply  -  it goes through Step 5 approval; after porting, bump the entry's `derivedFromVersion`.
+5. For each drifted entry, add a band-D plan item: "port upstream <plugin> <version> changes into <localPath>", with the specific skills to update. Do not auto-apply upstream changes  -  they go through Step 5 approval like everything else, and after porting, bump the entry's `derivedFromVersion`.
 
 ## Step 0c: DEV-TOOLKIT  -  current MCP practice for the companion toolkit
 
-The pipeline's device and browser hands are MCP tools served by a companion repo (`dev-toolkit-mcp`), and several pipeline skills declare a minimum toolkit version. This step researches current MCP practice and audits that repo against it.
+The pipeline's hands on devices and browsers are MCP tools served by a companion repo (`dev-toolkit-mcp`): Phase 5 test, `manual-test`, `design-check` and `apple-archive-compliance` all call them, and several pipeline skills declare a minimum toolkit version (see `cross-cli-contract.md`). That repo therefore has to track the MCP field, not just its own README. This step researches what current practice is and audits the toolkit against it.
 
 **Resolution**  -  configuration first, never a hardcoded path:
 
-1. `prefs.global.devToolkit`: `{ enabled, label, localPath, mcpServerName, packageName, registry, repoUrl }`.
-2. If unset, auto-detect from the MCP registration: `mcpServers` in `~/.claude.json` (plus `projects[*].mcpServers`) and `~/.claude/settings.json`; for a stdio `node` entry take `dirname(args[0])`, and accept it only if that directory is a git repo whose `package.json` depends on `@modelcontextprotocol/sdk`.
-3. Neither resolves (or `enabled: false`) -> skip and report "no dev-toolkit configured". Never guess a path, never clone.
+1. `prefs.global.devToolkit` in `~/.claude/multi-agent-preferences.json`:
+
+```jsonc
+{
+  "enabled": true,
+  "label": "<human name>",
+  "localPath": "$HOME/<repo-dir>",              // the companion repo working copy
+  "mcpServerName": "<registered MCP server name>",
+  "packageName": "@<scope>/<package>",
+  "registry": "github-packages",                 // github-packages | npmjs | none
+  "repoUrl": "https://github.com/<owner>/<repo>"
+}
+```
+
+2. If unset, auto-detect from the MCP registration: read `mcpServers` in `~/.claude.json` (including each `projects[*].mcpServers`) and in `~/.claude/settings.json`; for a stdio entry whose command is `node`, take `dirname(args[0])`. Accept it only when that directory is a git repo whose `package.json` depends on `@modelcontextprotocol/sdk`.
+3. If neither resolves, skip this step and report "no dev-toolkit configured". Never guess a path, never clone.
+4. `enabled: false` skips the step.
 
 **Research axes**  -  a finding without a source link is not a finding:
 
 | # | Axis | Where to look | What to extract |
 |---|------|---------------|-----------------|
-| 1 | MCP protocol | spec revisions + `@modelcontextprotocol/sdk` releases | features released since the pinned SDK that the server does not use: tool annotations, `outputSchema` + structured content, resource links, progress + cancellation, `tools/list_changed`, pagination |
-| 2 | Host clients | Claude Code / Copilot CLI / Cursor / Antigravity docs | description budget, tool-count ceilings, naming, output size limits, permission ergonomics |
-| 3 | Peer servers | GitHub search on the same domain + `stars:>50` | surfaces we lack, conventions peers converged on, what to discard |
-| 4 | Wrapped tooling | `simctl`, `idb`, `adb`, `xcodebuild`, Playwright notes, Apple ITMS + review guidelines | deprecated flags in use, new capabilities worth a tool, audit rules that changed |
-| 5 | Field practice | X / Twitter, Reddit, MCP community | what server authors changed recently (transport, output-token diets, error shape) |
+| 1 | MCP protocol | spec revisions + `@modelcontextprotocol/sdk` releases | protocol features released since the pinned SDK range that the server does not use yet: tool annotations (`readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint`), `outputSchema` + structured content, resource links in results, progress + cancellation, `tools/list_changed`, pagination, elicitation |
+| 2 | Host clients | Claude Code / Copilot CLI / Cursor / Antigravity docs + release notes | per-tool description budget, tool-count ceilings, naming conventions, image and output size limits, permission / allowlist ergonomics |
+| 3 | Peer servers | GitHub search on the same domain terms + `stars:>50` | tool surfaces we lack, conventions peers converged on, and what to discard as out of scope |
+| 4 | Wrapped tooling | `xcrun simctl help`, `idb`, `adb`, `xcodebuild`, Playwright release notes, Apple ITMS + App Store Review Guidelines | deprecated flags still in use, new capabilities worth a tool, audit rules that changed |
+| 5 | Field practice | X / Twitter, Reddit, MCP community threads | what server authors actually changed recently (transport choice, output-token diets, sandboxing, error shape) |
 
-**Audit the toolkit**  -  run the checks, do not assume:
+**Audit the toolkit against the findings**  -  run the checks, do not assume:
 
 ```bash
 DT="<resolved localPath>"
-node --check "$DT/index.js"; find "$DT/tools" -name "*.js" -exec node --check {} \;
-grep -rn "console\.log(" "$DT/index.js" "$DT/tools" || echo "stdout clean"   # stdout = JSON-RPC channel
-grep -nE "[0-9]+ tools" "$DT/README.md" "$DT/package.json"                    # advertised count vs reality
-node -p "require('$DT/package.json').files.join('\n')"; ls -d "$DT"/tools/*/  # files[] covers runtime dirs
+node --check "$DT/index.js"
+find "$DT/tools" -name "*.js" -type f -exec node --check {} \;
+
+# stdout carries the JSON-RPC frames: a stray stdout write corrupts the stream
+grep -rn "console\.log(" "$DT/index.js" "$DT/tools" || echo "stdout clean"
+
+# advertised tool counts vs reality (README header + package.json description)
+grep -nE "[0-9]+ tools" "$DT/README.md" "$DT/package.json"
+
+# packaging: every runtime directory must be inside files[]
+node -p "require('$DT/package.json').files.join('\n')"
+ls -d "$DT"/tools/*/
+
 cd "$DT" && npm outdated; npm audit --omit=dev 2>/dev/null | tail -20
 ```
 
-Also check: every tool has a description + `inputSchema`; token-heavy results (screenshots, UI trees) are truncated or file-backed; failures return an error result, not a throw; `CHANGELOG.md`, CI and tests exist.
+Also check: every tool carries a description and an `inputSchema`; token-heavy results (screenshots, UI trees, logs) are truncated or written to a file path instead of inlined; failures return an error result with an actionable message instead of throwing; `engines.node` matches what the SDK needs; `CHANGELOG.md`, a CI workflow and a test harness exist.
 
 Output (plan band E):
 
@@ -143,40 +172,74 @@ Output (plan band E):
 | # | Axis | Finding | Source | Adaptation in the toolkit (file) | Effort | Impact | In plan? |
 |---|------|---------|--------|----------------------------------|--------|--------|----------|
 | 1 | Protocol | read-only tools carry no annotations | <spec link> | add `annotations` to the read-only tools in index.js | Low | Medium | Yes (P1) |
-| 2 | Peer servers | peer exposes <surface> | <repo link> | does not fit: outside the pipeline's phases | - | - | No |
+| 2 | Wrapped tooling | uses a simctl flag removed in Xcode <v> | <release notes> | switch tools/<family>/<file>.js to <new flag> | Low | High | Yes (P0) |
+| 3 | Peer servers | peer exposes <surface> | <repo link> | does not fit: outside the pipeline's phases | - | - | No |
+```
+
+Rules for this band:
+
+- Band-E work lands in the toolkit repo, never mirrored into this one. Shipping it is `/multi-agent:sync` Step 3d.
+- A finding that changes the tool surface (new / renamed / removed tool) pairs with a pipeline-side item: bump the minimum toolkit version wherever a pipeline skill declares one.
+- If the current working directory IS the toolkit repo, skip band E and let bands A/B/C cover it  -  never report the same finding twice.
+
+## Step 0d: RUN-ERRORS  -  what the pipeline actually failed on
+
+Before speculating about improvements, read what real runs already failed on. When usage logging is enabled, every terminated run appends its errors to a local ledger:
+
+```bash
+LEDGER="$HOME/.claude/logs/multi-agent/errors-ledger.jsonl"
+[ -f "$LEDGER" ] || echo "no run-error ledger yet - skip band F"
+```
+
+Each line is one run: `{ t, id, u, c, rp, ph, v, errs[] }`. The `errs[]` entries are cause tags (`<phase>:<cause>` halt reasons, `phase-<id>-failed`, `run-failed`).
+
+1. Read the ledger (best-effort; a missing or unreadable file means skip band F, not a failure).
+2. Group by error tag. For each tag compute: occurrences, distinct users affected, distinct repos, the phase it usually strikes, first + last seen, and which pipeline versions it spans (a tag that persists across versions is unfixed; one that stopped at a version is already resolved  -  do not re-raise it).
+3. Rank by `occurrences x users-affected`. A failure that recurs across users or tasks is lived evidence, not a hypothesis  -  it outranks a speculative improvement.
+4. For each surviving tag, trace it to the phase doc / script that emits that cause and propose the concrete fix.
+
+This band mirrors the admin dashboard's "Gelişim alanları" panel, but reads the local ledger so it needs no auth and works offline. If `$ARGUMENTS` names a focus area, still read the ledger  -  a recurring run error in that area is the strongest possible signal.
+
+Output (plan band F):
+
+```
+| # | Error tag | Occurrences | Users | Usual phase | Versions | Root cause (file) | Fix | In plan? |
+|---|-----------|-------------|-------|-------------|----------|-------------------|-----|----------|
+| 1 | 4:reviewer-json-invalid | 12 | 3 | 4 | 14.x-15.x | reviewer prompt lets prose leak | tighten schema instruction in phase-4-review.md | Yes (P0) |
+| 2 | phase-3-failed | 5 | 2 | 3 | 15.0.x | build step misses a stack toolchain | add preflight in phase-3-dev.md | Yes (P1) |
 ```
 
 Rules for this band:
 
-- Band-E work lands in the toolkit repo, never mirrored into this one. Shipping it is `multi-agent-sync` Step 3d.
-- A finding that changes the tool surface pairs with a pipeline-side item: bump the minimum toolkit version wherever a pipeline skill declares one.
-- If the current working directory IS the toolkit repo, skip band E and let bands A/B/C cover it.
+- The ledger is evidence of the past, not a spec. A tag that stopped recurring after a version bump is resolved  -  report it as resolved, do not add a plan item.
+- Never quote a user's identity as blame. The `u` field is for counting distinct affected users, not for naming anyone in the plan.
+- If the ledger is empty or absent, skip band F silently  -  it is additive signal, never a gate.
 
 ## Step 1: SCAN
 
 ```
-- File count, LOC (cloc or wc -l)
+- file count, LOC (cloc or wc -l)
 - package.json / Package.swift / build.gradle analysis
-- Dependency count (runtime vs dev)
+- dependency count (runtime vs dev)
 - Is there a CI/CD pipeline? (.github/workflows/, fastlane/, Makefile)
-- Is there a test setup? How many tests? Coverage?
-- Is there a linter/formatter configuration?
-- README, LICENSE, SECURITY.md, CHANGELOG.md present?
-- Git status: branch count, last commit date, tags
+- Is there test infrastructure? How many tests? Coverage?
+- Is a linter/formatter config in place?
+- Do README, LICENSE, SECURITY.md, CHANGELOG.md exist?
+- Git state: branch count, last commit date, tags
 ```
 
 ## Step 2: ANALYZE  -  10 categories + BUG HUNT
 
 ### 2a. 10 categories (quality lens)
 
-| # | Category | What is checked |
-|---|----------|-----------------|
+| # | Category | What to check |
+|---|----------|---------------|
 | 1 | **Architecture** | Layer separation, modularity, SOLID, dependency direction |
-| 2 | **Code Quality** | Naming, magic number, dead code, complexity, DRY |
-| 3 | **Security** | Hardcoded secret, input validation, Keychain, ATS, ATT |
-| 4 | **Testing** | Coverage, test pyramid, edge case, mock/stub quality |
+| 2 | **Code Quality** | Naming, magic numbers, dead code, complexity, DRY |
+| 3 | **Security** | Hardcoded secrets, input validation, Keychain, ATS, ATT |
+| 4 | **Tests** | Coverage, test pyramid, edge cases, mock/stub quality |
 | 5 | **CI/CD** | Build matrix, lint job, release automation, artifact caching |
-| 6 | **Documentation** | README quality, JSDoc/Swift doc, API docs, CHANGELOG |
+| 6 | **Docs** | README quality, JSDoc / Swift docs, API docs, CHANGELOG |
 | 7 | **Performance** | Bundle size, lazy loading, memory leaks, unnecessary re-renders |
 | 8 | **Accessibility** | a11y labels, tap targets, VoiceOver, Dynamic Type |
 | 9 | **Dependency Management** | Outdated deps, vulnerability scan, lockfile, version pinning |
@@ -186,9 +249,9 @@ Rules for this band:
 
 Category scores measure quality; they do not find the bug that ships. Run an explicit defect hunt IN ADDITION to the scoring:
 
-- Dispatch focused review agents over the highest-risk surfaces: recently changed files, error/edge-path handling, concurrency, external input parsing, resource cleanup, off-by-one boundaries.
+- Dispatch focused review agents (Agent tool, `code-reviewer` persona where available) over the highest-risk surfaces: recently changed files, error/edge-path handling, concurrency, external input parsing, resource cleanup, off-by-one boundaries.
 - For each candidate defect, record: **file:line**, the concrete failure scenario (inputs/state -> wrong output/crash), and severity.
-- **Verify before reporting**: only list a bug you can trace to a real failure path; drop the plausible-but-unprovable ones.
+- **Verify before reporting**: only list a bug you can trace to a real failure path; drop the plausible-but-unprovable ones. Match the bar you would apply to a third party's code.
 
 Output (plan band B) - every confirmed defect becomes a P0/P1 item:
 ```
@@ -201,7 +264,7 @@ Improvement areas surfaced by 2a that are not outright bugs become band-C items.
 
 ## Step 3: SCORE
 
-Each category is scored out of 10. Output format:
+Each category is scored out of 10. Output:
 
 ```
 +---------------------+-------+
@@ -210,9 +273,9 @@ Each category is scored out of 10. Output format:
 | Architecture        | 9/10  |
 | Code Quality        | 8/10  |
 | Security            | 9/10  |
-| Testing             | 7/10  |
+| Tests               | 7/10  |
 | CI/CD               | 8/10  |
-| Documentation       | 7/10  |
+| Docs                | 7/10  |
 | Performance         | 9/10  |
 | Accessibility       | 6/10  |
 | Dependency Mgmt     | 8/10  |
@@ -224,13 +287,13 @@ Each category is scored out of 10. Output format:
 
 ## Step 4: PLAN  -  one merged, prioritized table
 
-Merge all five bands into a single plan. Tag each row with its band (A best-practice / B bug / C improvement / D drift / E dev-toolkit).
+Merge all five bands into a single plan. Tag each row with its band (A best-practice / B bug / C improvement / D drift / E dev-toolkit) so the source is visible.
 
 ```
 | # | Priority | Band | Category | Item | Impact |
 |---|----------|------|----------|------|--------|
 | 1 | P0 | B | Security | Remove hardcoded API key (src/x:12) | Critical |
-| 2 | P0 | B | Testing | Fix nil-deref on empty response (src/y:42) | High |
+| 2 | P0 | B | Tests | Fix nil-deref on empty response (src/y:42) | High |
 | 3 | P1 | A | CI/CD | Adopt matrix build (adapt: .github/workflows/ci.yml) | Medium |
 | 4 | P1 | D | Skills | Port upstream <plugin> 0.3.0 fixes into <localPath> | Medium |
 | 5 | P1 | E | Toolkit | Add read-only annotations to the dev-toolkit device tools | Medium |
@@ -238,39 +301,39 @@ Merge all five bands into a single plan. Tag each row with its band (A best-prac
 ```
 
 Priority levels:
-- **P0**: Bug, security hole, broken functionality  -  fix without fail
-- **P1**: Clear quality improvement or high-value adopted best-practice / drift port  -  should be done
-- **P2**: Nice-to-have  -  if there is time
+- **P0**: bugs, security holes, broken functionality  -  must fix
+- **P1**: clear quality improvement or high-value adopted best-practice / drift port  -  should be done
+- **P2**: nice-to-have  -  if time allows
 
-## Step 5: ASK  -  approval from the user
+## Step 5: ASK  -  user approval
 
 After showing the plan, ask:
 
-> "I found X items (P0: N, P1: M, P2: K) across bugs, best-practices, improvements, upstream drift, and dev-toolkit practice. Shall I start developing?"
+> "Found X items (P0: N, P1: M, P2: K) across bugs, best-practices, improvements, upstream drift, and dev-toolkit practice. Should I start the work?"
 
 Options:
-- "Yes, do all of them"
-- "Do only the P0 ones"
-- "Do only P0 + P1"
-- "Only the bugs (band B)"
+- "Yes, do all"
+- "Only P0"
+- "P0 + P1 only"
+- "Only bugs (band B)"
 - "Only the dev-toolkit (band E)"
-- (the user can make a specific selection)
+- (the user may pick specific items)
 
-**NEVER start developing without approval.**
+**Never start the work without approval.**
 
 ## Step 6: IMPLEMENT
 
-Apply approved items in order:
+Apply the approved items one by one:
 
 1. For each item:
-   - Make the change (for band D, port the upstream diff into `localPath`, then bump that entry's `derivedFromVersion`)
-   - Band-E items are applied inside the toolkit repo, never mirrored here: edit there, re-run its gates (`node --check`, `tools/list` handshake, advertised tool count matching reality), commit there. Publishing is `multi-agent-sync` Step 3d.
-   - Run the relevant tests
-   - If successful, move to the next
-   - If it fails, revert and notify the user
+   - apply the change (for band D, port the upstream diff into `localPath`, then bump that entry's `derivedFromVersion` in preferences)
+   - band-E items are applied inside the toolkit repo, never mirrored here: edit there, re-run its gates (`node --check`, the `tools/list` handshake, advertised tool count matching reality), then commit there with that repo's own convention. Publishing is `/multi-agent:sync` Step 3d  -  do not publish from this step.
+   - run the relevant tests
+   - on success, move to the next
+   - on failure, roll back and notify the user
 2. After all changes are done:
-   - Run the full lint + test suite
-   - If successful, commit
+   - run the full lint + test suite
+   - on success, commit
 
 Commit format: `refactor(scope): {short description}`
 
@@ -288,22 +351,22 @@ echo "Lint: PASS/FAIL"
 echo "Test: PASS/FAIL (X/Y passed)"
 ```
 
-If any band-E item was applied, verify the toolkit repo too: syntax-check every file it loads, handshake the server and confirm `tools/list` still answers, and confirm the advertised tool counts match the count the server reports.
+If any band-E item was applied, verify the toolkit repo too  -  syntax check every file it loads, handshake the server and confirm `tools/list` still answers, and confirm the advertised tool counts (README header, `package.json` description) match the count the server reports.
 
 ## Step 8: ASK SYNC
 
-After all approved items are applied, ask:
+After every approved item is applied, ask:
 
-> "Development complete. Shall I run multi-agent-sync?"
+> "Work is complete. Should I run /multi-agent:sync?"
 
 Options:
-- "Yes" -> run the `/sync` command (full ecosystem sync  -  its Step 3d ships any band-E work in the toolkit repo)
-- "No" -> report and finish
-- "Only commit + push" -> push only the current repo without sync
+- "Yes" -> run the `/multi-agent:sync` command (full ecosystem sync  -  its Step 3d ships any band-E work in the toolkit repo)
+- "No" -> emit a report and stop
+- "Commit + push only" -> push the current repo without sync
 
 ## Focus filter
 
-If $ARGUMENTS is specified, focus on that band/category only:
+If $ARGUMENTS is set, focus on that band/category only:
 
 | Input | Focus |
 |-------|-------|
@@ -313,8 +376,8 @@ If $ARGUMENTS is specified, focus on that band/category only:
 | `dev-toolkit` | Companion MCP toolkit research + audit only (band E) |
 | `security` | Security analysis only |
 | `tests` | Test coverage and quality only |
-| `performance` | Performance optimization only |
-| `docs` | Documentation only |
+| `performance` | Performance optimisation only |
+| `docs` | Docs only |
 | `ci` | CI/CD pipeline only |
 | `deps` | Dependency updates only |
 | (empty) | Everything (default) |

package/pipeline/skills/shared/core/{multi-agent-ship → multi-agent-resume-local}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: multi-agent-ship
+name: multi-agent-resume-local
 language: en
 description: "Continue already-done LOCAL work through the pipeline tail: Review → Build+Test → Commit/PR → Report (technical analysis + Jira test-scenario comment). No dev phase. Use when local work is already done and only review, build, commit and reporting remain."
 user-invocable: true
 ---
 
-# multi-agent ship  -  Take Existing Branch Work Through the Pipeline Tail
+# multi-agent resume-local  -  Take Existing Branch Work Through the Pipeline Tail
 
 You already wrote (and maybe hand-tested) the change on the current branch, or committed it outside the pipeline entirely. `ship` picks up from there and runs the **pipeline tail** over that existing work in one command, without re-developing. (As of v14.0.0 the `--dev` family reviews its own output, so this is for work with no pipeline run behind it.)
 
@@ -34,10 +34,10 @@ Phases 1-3 (Analysis / Planning / Dev) are skipped by design  -  the branch's lo
 ## Input
 
 ```bash
-multi-agent ship                   # current branch vs base; Jira id from branch name
-multi-agent ship PROJ-12345      # explicit Jira id for the Phase 7 comment
-multi-agent ship --base develop     # override base branch for the diff
-multi-agent ship autopilot          # no gate prompts: auto-fix, auto-PR, auto-comment
+multi-agent resume-local                   # current branch vs base; Jira id from branch name
+multi-agent resume-local PROJ-12345      # explicit Jira id for the Phase 7 comment
+multi-agent resume-local --base develop     # override base branch for the diff
+multi-agent resume-local autopilot          # no gate prompts: auto-fix, auto-PR, auto-comment
 ```
 
 ## Notes

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

@@ -1,50 +1,117 @@
 ---
 name: multi-agent-stack
 language: en
-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: "Select the active stack(s) for this repo by enabling the matching marketplace plugin(s) in .claude/settings.json. Multi-select: pass several stacks (ios backend) or pick them in the native picker. Use when a repo's stack changed or the wrong plugins are enabled for it."
 user-invocable: true
 ---
 
-# multi-agent stack  -  Select Stack via Plugin Enablement
+# multi-agent stack  -  Select Stack(s) via Plugin Enablement
 
-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.
+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-toolkit` (accessibility audit, humanizer, Firebase) is always enabled alongside the stack plugin(s).
 
-This replaces the old `stack-swap.sh` mechanic that physically moved skill directories. No SessionStart hook, no directory shuffling - enablement is declarative, per-repo, and versioned.
+On Claude Code the marketplace plugins are the ONLY source of stack skills - nothing is copied into `~/.claude/skills` anymore. A stack that is not enabled here is simply absent from the session. Copilot CLI and Codex CLI have no plugin loader; they receive a local copy filtered to the enabled stacks at install time, which is why step 5 below offers to refresh those copies after a change.
+
+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
 
 ```bash
-multi-agent-stack                  # show which plugins are enabled here
-multi-agent-stack ios              # SwiftUI toolkit + common
-multi-agent-stack android          # Compose toolkit + common
-multi-agent-stack mobile           # iOS + Android + common
-multi-agent-stack backend          # Python / Node spec-driven toolkit + common
-multi-agent-stack frontend         # React / TSX toolkit + common
-multi-agent-stack fullstack        # frontend + backend + common
-multi-agent-stack all              # all four stack toolkits + common
+/multi-agent:stack                 # no arg → native multi-select picker (current state pre-noted)
+/multi-agent:stack ios             # SwiftUI toolkit + common
+/multi-agent:stack ios backend     # any combination, space-separated
+/multi-agent:stack android         # Compose toolkit + common
+/multi-agent:stack mobile          # alias: ios + android + common
+/multi-agent:stack backend         # Python / Node spec-driven toolkit + common
+/multi-agent:stack frontend        # React / TSX toolkit + common (alias: web)
+/multi-agent:stack fullstack       # alias: frontend + backend + common
+/multi-agent:stack all             # all four stack toolkits + common
 ```
 
 ## Stack → plugin map
 
 | Stack | Plugins enabled (all `@multi-agent-plugins`) |
 |---|---|
-| `ios` | `ai-common-engineering-toolkit`, `ai-ios-engineering-toolkit` |
-| `android` | `ai-common-engineering-toolkit`, `ai-android-engineering-toolkit` |
-| `frontend` | `ai-common-engineering-toolkit`, `ai-frontend-engineering-toolkit` |
-| `backend` | `ai-common-engineering-toolkit`, `ai-backend-toolkit` |
-| `mobile` | common + `ai-ios-engineering-toolkit` + `ai-android-engineering-toolkit` |
-| `fullstack` | common + `ai-frontend-engineering-toolkit` + `ai-backend-toolkit` |
+| `ios` | `ai-common-toolkit`, `ai-ios-toolkit` |
+| `android` | `ai-common-toolkit`, `ai-android-toolkit` |
+| `frontend` / `web` | `ai-common-toolkit`, `ai-frontend-toolkit` |
+| `backend` | `ai-common-toolkit`, `ai-backend-toolkit` |
+| `mobile` | common + `ai-ios-toolkit` + `ai-android-toolkit` |
+| `fullstack` | common + `ai-frontend-toolkit` + `ai-backend-toolkit` |
 | `all` | common + all four stack toolkits |
 
+Multiple args union their plugin sets: `ios backend` → common + iOS + backend.
+
 ## Behaviour
 
-1. **No arg → status mode.** Read `.claude/settings.json` (repo) + the global settings and print which `@multi-agent-plugins` plugins are enabled. Modify nothing.
-2. **Arg present → enable mode.** Ensure the marketplace is known (`claude marketplace add {owner}/multi-agent-plugins`), then write the matching `enabledPlugins` entries into the current repo's `.claude/settings.json`, setting the stack toolkits that don't belong to `false`. `ai-common-engineering-toolkit` is always `true`.
-3. **Unknown arg** → show the list above; do not guess.
+1. **No arg → native multi-select picker.** Read `.claude/settings.json` (repo) + `~/.claude/settings.json` (global) to learn the current state, then ask with `AskUserQuestion` (`multiSelect: true`) - NEVER a numbered text menu:
+   - `question` (in `outputLanguage`): which stacks should be active in this repo, noting the currently enabled ones
+   - `header`: "Stacks" (English, UI contract)
+   - `options` (4): `ios` / `android` / `frontend (web)` / `backend`, each `description` (in `outputLanguage`) naming the plugin it enables and marking the ones already enabled with "(currently on)" / "(şu an açık)"
+   - Map each selected label back to its canonical arg before step 2: the token before any parenthesis (`frontend (web)` → `frontend`).
+   - Empty selection or cancel → **status mode**: print the currently enabled `@multi-agent-plugins` plugins and exit without modifying anything. Status mode never runs the Implementation block below - that block is enable-mode only.
+2. **Arg(s) present → enable mode.** Accept multiple space-separated stacks. Resolve each through the alias table (`web`→`frontend`, `mobile`→`ios android`, `fullstack`→`frontend backend`, `all`→every stack), union the plugin sets, then write the **current repo's** `.claude/settings.json`.
+3. **Write rules:**
+   - every plugin in the union is set to `true`
+   - every stack toolkit **not** in the union is set to `false` (leave non-`@multi-agent-plugins` entries untouched)
+   - `ai-common-toolkit@multi-agent-plugins` is always `true`
+   - **legacy-key cleanup**: delete any `ai-*-engineering-toolkit@multi-agent-plugins` keys - those plugin names were retired by the `ai-<stack>-toolkit` rename and a stale `true` there enables a plugin that no longer exists in the marketplace
+4. **Unknown arg** → show the table above; do not guess.
+5. **Copilot/Codex refresh offer.** Their local skill copies are filtered to the enabled stacks at install time, so after a change ask (single `AskUserQuestion`, not silent): "Refresh Copilot/Codex local copies now?" - Yes runs `node <pipelineRepo>/install.js --copilot --codex`, No leaves them stale with a one-line warning naming the command to run later. Skip this question entirely when neither `~/.copilot` nor `~/.codex` exists.
+
+## Implementation
+
+```bash
+REPO_SETTINGS=".claude/settings.json"
+MP="multi-agent-plugins"
+
+# --- ensure the marketplace is known (idempotent) -------------------------
+if ! claude marketplace list 2>/dev/null | grep -q "$MP"; then
+  claude marketplace add {owner}/multi-agent-plugins 2>/dev/null \
+    || echo "note: add the marketplace once with: claude marketplace add {owner}/multi-agent-plugins"
+fi
+
+COMMON="ai-common-toolkit@${MP}"
+IOS="ai-ios-toolkit@${MP}"
+ANDROID="ai-android-toolkit@${MP}"
+FRONTEND="ai-frontend-toolkit@${MP}"
+BACKEND="ai-backend-toolkit@${MP}"
+
+# Enable-mode only: with zero args the write rules below would set every stack
+# toolkit to false (nothing but $COMMON is in $ON), silently wiping the repo's
+# selection. No args belongs to the picker / status path (Behaviour step 1).
+if [ "$#" -eq 0 ]; then
+  echo "No stack given - nothing changed. Pass stacks (ios backend ...) or use the picker."
+  exit 0
+fi
+
+# resolve every arg through the alias table, union the ON set
+ON="$COMMON"
+for ARG in "$@"; do
+  case "$ARG" in
+    ios)              ON="$ON $IOS" ;;
+    android)          ON="$ON $ANDROID" ;;
+    frontend|web)     ON="$ON $FRONTEND" ;;
+    "frontend (web)") ON="$ON $FRONTEND" ;;
+    backend)          ON="$ON $BACKEND" ;;
+    mobile)           ON="$ON $IOS $ANDROID" ;;
+    fullstack)        ON="$ON $FRONTEND $BACKEND" ;;
+    all)              ON="$ON $IOS $ANDROID $FRONTEND $BACKEND" ;;
+    *) echo "Unknown stack '$ARG'. One of: ios android mobile backend frontend web fullstack all"; exit 1 ;;
+  esac
+done
+```
+
+After resolving `$ON`, edit `.claude/settings.json` (create `{ "enabledPlugins": {} }` if absent) so that:
+- every plugin in `$ON` is set to `true`,
+- every stack toolkit **not** in `$ON` is set to `false` (leave non-`@multi-agent-plugins` entries untouched),
+- `ai-common-toolkit@multi-agent-plugins` is always `true`,
+- every `ai-*-engineering-toolkit@multi-agent-plugins` key is **deleted** (retired names).
+
+Use the Read + Edit/Write tools (JSON must stay valid). Then print the resulting `enabledPlugins` block and run step 5 (Copilot/Codex refresh offer).
 
 ## Notes
 
 - Enablement is per-repo and declarative - commit `.claude/settings.json` so teammates get the same stack.
-- Restart the conversation to pick up newly enabled plugins.
+- 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/skills/shared/core/multi-agent-store-ready/SKILL.md

@@ -37,7 +37,7 @@ doc is the contract.
 |---|---|---|
 | 1 Static | `ios_app_store_audit` 18 rules, needs an `.xcarchive` | `android_apk_audit` + `google-play-compliance` 21 rules, needs an `.aab` |
 | 2 Authoritative | `ios_testflight_validate` → `altool --validate-app`, needs credentials | `SKIPPED`  -  Play's authoritative check is server-side only and no client ships here |
-| 3 Policy | `app-store-review` skill vs repo source | `play-store-review` skill vs repo source |
+| 3 Policy | `ai-ios-toolkit:app-store-review` skill vs repo source | `ai-android-toolkit:play-store-review` skill vs repo source |
 
 Gate 2's asymmetry is reported as an asymmetry. An Android run clears at most 2 of 3
 gates and must never print `passed`. A skipped gate is never folded into the pass