# Refactor Council

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-smykla-skalski-sai-refactor-council`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [smykla-skalski](https://agentstack.voostack.com/s/smykla-skalski)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [smykla-skalski](https://github.com/smykla-skalski)
- **Source:** https://github.com/smykla-skalski/sai/tree/main/plugins/refactor-council/copilot-skills/refactor-council

## Install

```sh
agentstack add skill-smykla-skalski-sai-refactor-council
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Refactor Council (Copilot)

Summon seven sourced refactoring-and-architecture reviewer agents, then produce a safety-first, sequenced refactoring plan that a separate adversary agent has stress-tested. The reviewers are native Copilot custom agents bundled with this plugin; the current session agent acts as the orchestrator. The reviewers argue from the writers' actual published positions and disagree with each other on purpose - the disagreement is the value.

## The roster (7 + adversary)

Bundled as custom agents under `agents/` (namespaced, e.g. `refactor-council:fowler-refactoring-reviewer`). Registry and symptom map: [references/refactoring-catalog.md](references/refactoring-catalog.md) for the smell/refactoring vocabulary and safety discipline.

| Reviewer agent | Lens |
|---|---|
| `fowler-refactoring-reviewer` | Refactoring catalog + smells; small behavior-preserving steps; two hats; Rule of Three; Strangler Fig |
| `martin-clean-architecture-reviewer` | SOLID; Clean Architecture & the Dependency Rule; small functions; naming; frameworks/DB as details |
| `feathers-legacy-reviewer` | Legacy = code without tests; seams; characterization tests; Sprout/Wrap; get-it-under-test-first |
| `beck-tidy-first-reviewer` | Structural vs behavioral changes; tidyings; coupling/optionality economics; baby steps |
| `metz-abstraction-reviewer` | Duplication over the wrong abstraction; flocking rules; squint test; depend on stable things |
| `ousterhout-deep-module-reviewer` | Deep modules; complexity is the enemy; anti-over-decomposition; comments are load-bearing |
| `tornhill-hotspot-advisor` | Behavioral code analysis; hotspots (complexity x churn); change coupling; *where* to refactor |

After synthesis, `refactor-adversary` red-teams the findings and plan.

## Parsing the request

1. Read flags: `--no-scan`, `--no-adversary`, `--since ` (default `12.month`), `--personas ` (subset of the seven; default all seven).
2. The remaining text is the target: a path, a directory, an `@file`, or `diff` (use `git diff`). If none is resolvable, ask which file/dir/diff to review - do not invent one.

## Workflow

### Phase 1 - Setup

Resolve the target. Read [references/refactoring-catalog.md](references/refactoring-catalog.md) so you and the reviewers name smells and refactorings precisely and enforce the safety discipline in the plan.

### Phase 2 - Scan (skip if `--no-scan`)

Run the bundled scanners via shell and gather a compact evidence bundle:

- Smells: `python3 scripts/smell_scan.py  --human`
- Hotspots (git repos only): `python3 scripts/hotspots.py  --since  --human`
- Safety net: detect tests near the target (`*_test.*`, `*.test.*`, `*.spec.*`, `test/`, `tests/`, `__tests__/`). Record present / absent / partial.

The bundle (top located smells, top hotspots + coupling pairs, test-net status) is load-bearing - pass it to every reviewer. If not a git repo or history is shallow, say so and note that prioritization is weakened.

### Phase 3 - Reviewer delegation (sequential by default)

Delegate each selected reviewer through the `agent` tool, giving each: the target context, the scan evidence bundle, the Persona output contract below, and the instruction that the first line must be `##  review`.

**Default to sequential delegation - one reviewer at a time.** Copilot parallel fan-out via `/fleet` over-parallelizes and burns AI credits, and offers no reliability guarantee for an 8-agent council; sequential delegation is the reliable path here. Only fan out in parallel if the user explicitly asks, and then run small waves ( review` and contain the contract sections. Re-delegate an invalid reviewer once with the same bundle; if still invalid, continue and note the missing lens. Never surface raw reviewer envelopes or readiness text.

### Phase 4 - Synthesize (critique + plan)

Write one integrated review using the Synthesis output shape below. Surface disagreement (especially Uncle Bob vs Ousterhout on functions/comments; Uncle Bob's DRY reflex vs Metz; decomposition vs Ousterhout); do not flatten it. Include the safety-net status, a sequenced smallest-first refactoring plan (characterization-tests-first when untested; structural vs behavioral separated, two hats), and an explicit "Do NOT refactor" list (cold code, duplication cheaper than abstraction, extraction that adds complexity).

### Phase 5 - Adversarial pass (skip only if `--no-adversary`)

Delegate `refactor-adversary` with the full synthesized review (findings + plan), the target context, and the scan evidence. It returns SHIP / SHIP WITH CHANGES / HOLD plus challenged recommendations, what survived scrutiny, unsafe-as-sequenced reordering, and what the council missed. Apply the same validate-and-retry rule once.

### Phase 6 - Final output

Fold the adversary verdict in before presenting: REJECT/REORDER/WEAKEN revise the plan in place; mark "survived scrutiny" items high-confidence; add a "Risks the council missed" section; if HOLD, lead with it and do not present the contested step without the fix. Keep reviewer framing internal (see Privacy).

## Persona output contract

```
##  review

### What I see

### What concerns me

### What I'd refactor and how
 target, smallest-first>

### Safety net I'd require first

### Where I'd be wrong

```

## Synthesis output shape

```
# Refactoring review: 

## Convergence (high-confidence signals)
## Disagreement (real tradeoffs you must decide)
## Per-persona top-3
## Safety net status
## Refactoring plan (sequenced, smallest-first)
## Do NOT refactor (and why)
## Risks the council missed (from the adversary)
## Adversary verdict
```

(Same content as the Claude skill: convergence first, named disagreement, per-persona top-3 in voice, safety-net status with characterization-tests-first when untested, a sequenced behavior-preserving plan with structural vs behavioral marked, an explicit do-not-refactor list, and the adversary's caught risks and verdict.)

## Privacy / scope

The reviewer dossiers under `agents/references/` are private review aids derived from each thinker's public writing. Do not republish wholesale; keep reviewer framing internal - if a review leaves the team, restate the argument in your own voice. This is a *refactoring* council: it preserves behavior by definition, so it does not by itself verify correctness, security, or performance. The adversary partially covers those gaps; for a full audit use a staff-level or language-specific review.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [smykla-skalski](https://github.com/smykla-skalski)
- **Source:** [smykla-skalski/sai](https://github.com/smykla-skalski/sai)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-smykla-skalski-sai-refactor-council
- Seller: https://agentstack.voostack.com/s/smykla-skalski
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.