| name | large-scale-refactor |
| description | Guardrails, protocols, and operating constraints for large-scale, long-running, or parallelized AI coding tasks — migrations, codebase-wide refactors, framework upgrades, and any task touching 50+ files. Prevents scope creep, context drift, silent compounding errors, and emergent behavior outside the defined task boundary. Use when refactoring across files, migrating frameworks, upgrading dependencies, replacing or renaming patterns throughout a codebase, or any task touching 50+ files.
|
| license | MIT |
| author | opensite-ai |
| version | 1.0.0 |
| tags | ["refactor","migration","long-running","multi-agent","guardrails","agentic"] |
| activation_patterns | ["refactor * across","migrate * to","upgrade * from","replace all","update every","rename * throughout","convert all","remove all instances","batch * across the codebase","files_touched_estimate >= 50"] |
large-scale-refactor
Activates when a task will touch 50+ files, run longer than one agent session, or be parallelized across instances. Once active, task scope is locked: no deviation, even for apparent related improvements.
Spec gate
No execution without a written, human-approved spec. Halt after producing the spec and await explicit approval before writing any code. In parallel mode, the spec is approved before spawning any instances; the approved spec is the canonical context injected into every instance.
Spec contents:
- Task name, date, initiator
- One concrete paragraph of what the task does
- IN SCOPE: file types, operations, directories
- OUT OF SCOPE (do not touch): styling/theming/color tokens, business logic and data transformation behavior, component structure beyond what the task requires, dependencies (beyond
@types/* for TS migrations), build/CI/deploy configs, and anything not explicitly IN SCOPE
- Decomposition into atomic, independently reviewable subtasks (each: N files, directory)
- Acceptance criteria: in-scope files at target state; tests pass or failures are pre-existing and documented; no net-new deps beyond spec; no out-of-scope files modified; one commit/PR per subtask
- Rollback plan (branch name, revert strategy)
Scope enforcement
- One job: the spec. Bugs, improvements, missing tests, perf wins, style issues not in spec — log to
OBSERVATIONS.md (file | observation | severity) and leave alone. Never act on observations.
- Substitution test before every change: "If I remove this change from the diff, does the task still fail?" If the task still succeeds without it, do not make the change.
- No emergent systems unless named in the spec: no new design/theming systems, utility libraries or helper modules, abstractions/base classes/shared components, folder reorganization, build steps/scripts/tooling, config files or env vars, test harnesses, or any file that did not exist before the task (exception: spec-defined outputs, e.g.
.ts replacing .js). If a shared utility is genuinely needed, propose it in OBSERVATIONS.md and halt for approval.
- No dependency add/remove/upgrade unless spec-listed, or a
@types/* package in a TS migration.
- 50-line rule: more than 50 lines of net-new logic for one change (excluding type annotations, renames, reformatting) means scope creep or a task needing architectural discussion. Stop, log, halt for review.
Execution
