# Dev-Toolkit Research (refactor Step 0c)

Loaded on demand by `/multi-agent:refactor` Step 0c. The SKILL.md carries the step intro; this file is the full procedure.

**Resolution**  -  configuration first, never a hardcoded path:

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 multi-agent-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 | 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 against the findings**  -  run the checks, do not assume:

```bash
DT="<resolved localPath>"
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 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):

```
| # | 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 | 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.