---
name: multi-agent-refactor
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."
user-invocable: true
argument-hint: 'bugs | best-practices | drift | multi-agent-toolkit | run-errors | security | tests | performance | docs | ci | deps'
metadata:
  language: en
---

# 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  -  `backlog` runs Step 0e alone; otherwise an 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.

Rules that hold for every entry:
- The upstream mapping is **configuration, never hardcoded**: `global.derivedSkillSources` in `~/.claude/multi-agent-preferences.json`. Missing or empty -> **skip** and report "no derived-skill sources configured". Never invent a source.
- **The plugin cache is a mirror, not the authority.** Never let the cache alone produce an "up to date" verdict; report it as **`unverified (cache only)`**. An unreachable upstream is recorded as "upstream unreachable" and the run continues.
- Each drifted entry becomes a band-D plan item. Do not auto-apply upstream changes  -  they go through Step 5 approval like everything else, and after porting, bump the entry's `derivedFromVersion`.

Full procedure: `$HOME/.claude/multi-agent-refs/refactor/drift.md`. Read it when `global.derivedSkillSources` has at least one entry (entry schema, source resolution order, version manifest, comparison, band-D table).

## 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 3 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 at `$HOME/.claude/logs/multi-agent/errors-ledger.jsonl`. A missing, unreadable or empty ledger means skip band F silently  -  it is additive signal, never a gate. If `$ARGUMENTS` names a focus area, still read the ledger  -  a recurring run error in that area is the strongest possible signal. A tag that stopped recurring after a version bump is resolved: report it, do not re-raise it. Never quote a user's identity as blame.

Full procedure: `$HOME/.claude/multi-agent-refs/refactor/run-errors.md`. Read it when the ledger exists (record shape, grouping and ranking, transcript mining, band-F table).

## Step 0e: BACKLOG  -  friction this pipeline already noticed

Every other band in this command derives its findings from scratch, which is right for a sweep and has one consequence nobody chose: a friction noticed mid-task is gone by the next run unless it was fixed within the hour. Most are not, because stopping mid-task to fix them is the wrong call. So they are written down when noticed and decided here.

```bash
node "$HOME/.claude/scripts/observations.mjs" scan --status open --json
```

Exit 3 is `SCAN BROKEN`  -  files on disk, none parsed. That is a broken reader, not an empty queue: halt the band and say so rather than reporting "0 open".

Split every open observation into actionable / sibling-propagation / to-decline, and resolve the sibling surfaces mechanically with `skill-siblings.mjs`, never from memory  -  a command is authored in `commands/`, mirrored into `skills/shared/core/`, and installed again into three host trees, so a fix applied to one copy drifts from the rest with every gate still green. Output as plan band G, same table shape as the other bands.

`/multi-agent:refactor backlog` runs this band alone. The full sweep is unchanged and still includes it. Buckets, the status vocabulary, why `parked` needs a named unblocking event, and how to write an observation: `$HOME/.claude/multi-agent-refs/refactor/observations.md`.

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