---
description: "Analyse the project: extract adapted best-practices, hunt real bugs + improvement areas, check upstream drift of derived skills, research the companion multi-agent-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, multi-agent-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
---

# 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 multi-agent-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", "multi-agent-toolkit", etc.)

## Flow

```
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 multi-agent-toolkit repo -> plan band E
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 /10, overall /100
Step 4:  PLAN            Merge bands A (best-practice) + B (bugs) + C (improvements) + D (drift) + E (multi-agent-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):
- **A - Best-practice**: the best field approaches, adapted so they actually fit this repo.
- **B - Bug**: real defects found in the code (correctness, security, data-loss, crashes).
- **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 multi-agent-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** 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. When `ai-analyst-toolkit` is enabled, run the first three bullets through its skills (`evidence-github`, `evidence-registry`, `signal-community`) rather than ad-hoc searching: they carry the query forms and the citation format, and they keep the evidence / signal line straight - a GitHub PR is a fact, a forum thread is one person's experience. Not enabled is a recorded no-op and the manual searches below still apply.
   - **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 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, 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):
```
| Source | Approach | Adaptation to our repo | Effort | Impact | In plan? |
|--------|----------|------------------------|--------|--------|----------|
| <repo> | <what>   | <concrete change here> | Low    | High   | Yes (P1) |
| <repo> | <what>   | does not fit: <reason> | -      | -      | No       |
```
Roll the high-impact + low/med-effort survivors into the Step 4 plan as band-A items.

## Step 0b: DRIFT  -  upstream-derived skill check

Some skills/components in this project (or in the marketplace plugins it ships) were derived from an upstream source. Upstream keeps evolving  -  it fixes bugs and adds features. This step detects upstream drift so we can decide whether to pull the improvements back.

The upstream mapping is **configuration, never hardcoded** (it can reference private sources, so it stays out of the shipped skill). Read it from `~/.claude/multi-agent-preferences.json` at `global.derivedSkillSources` (an array). Each entry:

```jsonc
{
  "label": "<human name for this derivation>",
  "localPath": "<repo-relative dir where our derived copy lives>",
  "upstreamMarketplace": "<installed marketplace name>",   // resolved under ~/.claude/plugins/cache/<marketplace>/
  "upstreamPlugin": "<plugin name>",
  "upstreamSkills": ["<skill-a>", "<skill-b>"],            // the upstream skills we took
  "derivedFromVersion": "<x.y.z>",                         // the version we last synced from
  "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, 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 (+ 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):

```
| Derivation | Our copy (localPath) | Derived-from | Upstream now | Drift | What changed upstream |
|------------|----------------------|--------------|--------------|-------|-----------------------|
| <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>", 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 hands on devices and browsers are MCP tools served by a companion repo (`multi-agent-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.

Full procedure  -  resolution (configuration first, never a hardcoded path; skip when nothing resolves or `enabled` is false), the 5 research axes, the audit command block, and the band-E output table + rules  -  lives in `$HOME/.claude/multi-agent-refs/refactor/toolkit-research.md`. Read it before running this step.

## 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:

- 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)
- package.json / Package.swift / build.gradle analysis
- dependency count (runtime vs dev)
- Is there a CI/CD pipeline? (.github/workflows/, fastlane/, Makefile)
- 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 to check |
|---|----------|---------------|
| 1 | **Architecture** | Layer separation, modularity, SOLID, dependency direction |
| 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 | **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 |
| 10 | **DevEx** | Onboarding time, script ergonomics, error messages, debug tooling |

### 2b. BUG HUNT (real defects, not scores)

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 (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. Match the bar you would apply to a third party's code.

Output (plan band B) - every confirmed defect becomes a P0/P1 item:
```
| # | Severity | File:line | Defect | Failure scenario |
|---|----------|-----------|--------|------------------|
| 1 | Blocking | src/x.ts:42 | unchecked nil deref | empty response -> crash |
```

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:

```
+---------------------+-------+
| Category            | Score |
+---------------------+-------+
| Architecture        | 9/10  |
| Code Quality        | 8/10  |
| Security            | 9/10  |
| Tests               | 7/10  |
| CI/CD               | 8/10  |
| Docs                | 7/10  |
| Performance         | 9/10  |
| Accessibility       | 6/10  |
| Dependency Mgmt     | 8/10  |
| DevEx               | 9/10  |
+---------------------+-------+
| TOTAL               | 80/100|
+---------------------+-------+
```

## 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 multi-agent-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 | 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 multi-agent-toolkit device tools | Medium |
| 6 | P2 | C | DevEx | Rename npm scripts for consistency | Low |
```

Priority levels:
- **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  -  user approval

After showing the plan, ask:

> "Found X items (P0: N, P1: M, P2: K) across bugs, best-practices, improvements, upstream drift, and multi-agent-toolkit practice. Should I start the work?"

Options:
- "Yes, do all"
- "Only P0"
- "P0 + P1 only"
- "Only bugs (band B)"
- "Only the multi-agent-toolkit (band E)"
- (the user may pick specific items)

**Never start the work without approval.**

## Step 6: IMPLEMENT

Apply the approved items one by one:

1. For each item:
   - 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
   - on success, commit

Commit format: `refactor(scope): {short description}`

## Step 7: VERIFY

```bash
# Lint
npm run lint 2>/dev/null || swift build 2>/dev/null

# Test
npm test 2>/dev/null || swift test 2>/dev/null || xcodebuild test 2>/dev/null

# Result
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 (README header, `package.json` description) match the count the server reports.

## Step 8: ASK SYNC

After every approved item is applied, ask:

> "Work is complete. Should I run /multi-agent:sync?"

Options:
- "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 set, focus on that band/category only:

| Input | Focus |
|-------|-------|
| `bugs` | Bug hunt only (band B) |
| `best-practices` | Field research + adapted plan only (band A) |
| `drift` | Upstream derived-skill drift only (band D) |
| `multi-agent-toolkit` | Companion MCP toolkit research + audit only (band E) |
| `security` | Security analysis only |
| `tests` | Test coverage and quality only |
| `performance` | Performance optimisation only |
| `docs` | Docs only |
| `ci` | CI/CD pipeline only |
| `deps` | Dependency updates only |
| (empty) | Everything (default) |