refactor

Files (1)

• SKILL.md

SKILL.md (first lines)

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

**Scope gate (after Wave 1):**
- `site_count > 50` → warn the user: "This refactor touches N sites. Recommend scoping down with `--scope` or batching via `/parallelize`. Proceeding, but each layer will take longer."
- `test_coverage_verdict == "absent"` → hard stop: "No tests cover the affected contracts. Behavioral preservation cannot be verified. Add tests before proceeding, or explicitly confirm you accept unverified risk."
- Either agent returns `confidence: low` → surface the coverage gaps and ask the user to confirm before proceeding.

---

### Synthesize: Build the layer map (inline)

From `dependency_graph`, compute a topological sort into layers using Kahn's algorithm:
- **Layer 0** — leaf sites with no dependents (definitions that nothing imports, or sites that depend on nothing else changing first)
- **Layer N** — sites whose dependencies are all in layers 0…N-1

If the graph has cycles (rare but possible in circular-import codebases), surface them explicitly: "Cycle detected between [A, B, C]. Manual intervention required before automation can proceed." Do not continue.

---

### Wave 2 — Layer-by-layer application (sequential between layers, parallel within each layer)

For **each layer** (starting at Layer 0):

Dispatch one sub-agent per site in this layer, all in parallel, each in a worktree-isolated environment:

**Layer applicator agent** (per site, `isolation: "worktree"`)
- goal: Apply the transformation at exactly this site and verify it passes its targeted tests.
- inputs: site descriptor `{file, line_range, change_required}`, full transformation spec (target → destination), test commands that cover this site
- artifacts:
  - `site`: `{file, line_range}`
  - `status`: "green" | "red" | "skipped"
  - `diff_applied`: the exact unified diff applied (≤30 lines; truncate with `...` if longer)
  - `test_output`: truncated stdout of the targeted test run (last 20 lines)
  - `failure_reason`: populated only if `status == "red"` — the first failing assertion + the file:line where it fired
- non_goals: Do not change any file other than the one in your site descriptor. Do not run the full test suite.
- IMPORTANT: this sub-agent MAY call `edit_file` and run bash commands; `isolation: "worktree"` is required.

**Layer gate — hard stop before proceeding to the next layer:**
- All sites in this layer `status == "green"` → proceed to the next layer.
- Any site `status == "red"` → **abort the entire refactor immediately**. Do NOT apply any more changes. Surface:
  - The failing site (`file:line_range`)
  - The `diff_applied` for that site
  - The `failure_reason`
  - The current layer number and which layers (if any) already completed successfully
  - Recommendation: "Revert layer N changes manually or run `git stash` in each affected worktree, then diagnose with `/diagnose`."

---

### Wave 3 — Behavioral diff verification (after all layers green, `subagent_type: "research-agent"` or Bash-capable)

Dispatch a single behavioral-diff agent:

**Behavioral-diff agent** (`isolation: "worktree"`, Bash-capable)
- goal: Run the full test suite and compare observable behavior at the API boundary before vs. after.
- inputs: `test_commands` from the contract-extractor, plus any project-wide test command (inferred from `package.json`, `Makefile`, etc.)
- artifacts:
  - `full_suite_status`: "all-green" | "failures"
  - `failing_tests`: array of `{test_name, file, failure_reason}` (empty if all-green)
  - `behavioral_deltas`: array of `{symbol, before_behavior, after_behavior, expected: true|false}` — note only deltas, not noise
  - `unexpected_deltas`: subset of `behavioral_deltas` where `expected == false`
  - `confidence`: low | medium | high
- non_goals: Do not commit. Do not push.

**Post-Wave 3 decision:**
- `full_suite_status == "all-green"` AND `unexpected_deltas` is empty → proceed to synthesis, recommend commit.
- `full_suite_status == "failures"` OR `unexpected_deltas` is non-empty → surface the unexpected deltas for human review. Do NOT commit. Recommend: "Review unexpected behavioral changes before committing. If intentional, update tests to reflect new contracts. If not, route to `/diagnose`."

---

### Synthesis: Change report

Emit a structured change report:

```
## Refactor Report

From griffinwork40/agent-framework, Apache-2.0.

More from griffinwork40/agent-framework