refactor

Sub-agent contract

/contract

Skip when: the change touches ≤3 files and no dependency ordering is required — just edit directly. Also skip when the codebase has no test coverage at all (behavioral preservation cannot be verified; ask the user to add tests first or proceed manually).

---

Triage (inline, before dispatching any sub-agent)

Parse $ARGUMENT to extract:

• Change type: rename | api-migration | pattern-standardization | layer-restructure | dependency-upgrade | other
• Target symbol / path / pattern (what is changing)
• Destination (what it becomes)
• Scope: default to the entire repo; narrow if --scope is provided

If $ARGUMENT is ambiguous on any of the above, stop and ask exactly one question.

---

Wave 1 — Scope enumeration (parallel, subagent_type: "research-agent")

Dispatch both agents simultaneously in a single response turn.

Site-finder agent

• goal: Enumerate every file and symbol that must change for the refactor to be complete and correct.
• inputs: change type, target symbol/pattern, scope glob
• artifacts:
  • sites: array of {file, line_range, site_type: "definition"|"import"|"usage"|"type-ref"|"test", change_required: string}
  • dependency_graph: for each site, which other sites must be changed first (a site depends on its callers if it exports a symbol; a definition must be changed before its imports)
  • site_count: integer
  • confidence: low | medium | high
  • coverage_gaps: what the agent couldn't search (generated files, third-party vendored code, etc.)
• non_goals: Do not apply any changes. Do not read unrelated files.
• failure_modes: If grep tooling is unavailable, return confidence: low and list what was searched manually.

Contract-extractor agent

• goal: Identify the public interfaces and test commands that verify behavioral preservation for the affected API surface.
• inputs: site list (from site-finder, passed inline if available; if not yet available, derive from change type + scope)
• artifacts:
  • contracts: array of {symbol, signature_before, exported_by, consumed_by[]}
  • test_commands: array of shell commands that SCOPE to the affected contracts — target the specific test files or a name pattern, never the whole suite (e.g., pnpm test src/auth/auth-service.test.ts or pnpm test -t "AuthService"). Under pnpm, pnpm test -- <file> drops the file arg and runs the entire suite — never emit that form.
  • test_coverage_verdict: "adequate" | "partial" | "absent"
  • confidence: low | medium | high
  • coverage_gaps: test paths not reachable by the identified commands
• non_goals: Do not run tests. Do not read unrelated files.