opensite-ai/opensite-skills / large-scale-refactor
large-scale-refactor
UnverifiedGuardrails, 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.
| File | Kind | Size |
|---|---|---|
| CONTRIBUTING.md | markdown | 1.5 KB |
| README.md | markdown | 7.7 KB |
| SKILL.md | skill md | 17.9 KB |
| agents/openai.yaml | config | 5.4 KB |
| examples/complete-workflow.md | markdown | 9.8 KB |
| examples/refactor-spec.md | markdown | 2.2 KB |
| references/activation.md | markdown | 4.9 KB |
| scripts/generate_allowlist.pyexecutable | script | 8.9 KB |
| scripts/test_verify_scope.py | script | 7.8 KB |
| scripts/verify_scope.pyexecutable | script | 7.6 KB |
| templates/change-manifest.md | markdown | 1.6 KB |
| templates/observations.md | markdown | 2.9 KB |
| templates/refactor-scope-allowlist.example | other | 5.5 KB |
| templates/session-handoff.md | markdown | 6.1 KB |
templates/refactor-scope-allowlist.example
View on GitHub# =============================================================================
# .refactor-scope-allowlist — Example with Annotations
# =============================================================================
#
# This file tells verify_scope.py which files the current refactor task is
# allowed to touch. One pattern per line. Lines beginning with '#' are
# comments and are ignored by the script.
#
# GENERATE THIS FILE automatically from your TASK_SPEC.md:
#
# python scripts/generate_allowlist.py TASK_SPEC.md
#
# Or copy this example, strip the comments, and edit manually.
#
# VERIFY compliance at any point during the refactor:
#
# python scripts/verify_scope.py # report only
# python scripts/verify_scope.py --strict # exit 1 on any violation
#
# =============================================================================
# PATTERN TYPES
# =============================================================================
#
# 1. DIRECTORY PREFIX (trailing slash required)
# -----------------------------------------------
# Matches any file whose path starts with this prefix.
# Use for entire directory trees.
#
# src/components/ matches src/components/Button.tsx
# matches src/components/forms/Input.tsx
# matches src/components/forms/deep/Nested.tsx
#
# tests/unit/ matches tests/unit/Button.test.tsx
# does NOT match tests/integration/Button.test.tsx
#
# 2. GLOB PATTERN (* wildcard)
# -----------------------------------------------
# Matched against the FULL file path AND the bare filename.
# This means *.js matches src/components/Button.js without needing **/*.js.
#
# *.js matches src/Button.js
# matches src/utils/format.js
# does NOT match src/Button.ts
#
# *.{ts,tsx} NOT supported — use two separate lines instead:
# *.ts
# *.tsx
#
# src/**/*.tsx matches src/Button.tsx
# matches src/forms/Input.tsx
# matches src/forms/deep/Nested.tsx
#
# **/__tests__/**/*.test.ts matches any .test.ts inside any __tests__ dir
#
# 3. EXACT FILE PATH
# -----------------------------------------------
# Matches one specific file only. Useful for config files that must be
# updated as part of the migration (e.g., a tsconfig.json or babel.config.js).
#
# tsconfig.json matches tsconfig.json (repo root only)
# src/index.ts matches src/index.ts (exact path)
#
# =============================================================================
# EXAMPLE: JavaScript → TypeScript Migration
# =============================================================================
# Task: Convert all .js/.jsx files in src/ to .ts/.tsx
# Files created: .ts/.tsx replacements for every .js/.jsx in src/
# Files NOT touched: config/, scripts/, public/, node_modules/, *.json
# =============================================================================
# Source directories being converted
src/components/
src/hooks/
src/utils/
src/pages/
src/lib/
src/context/
# Test files co-located with source
src/**/*.test.js
src/**/*.spec.js
src/**/*.test.jsx
src/**/*.spec.jsx
# Input file types (original .js/.jsx files being replaced)
*.js
*.jsx
# Output file types (new .ts/.tsx files being created)
# These are spec-defined outputs — acceptable new files
*.ts
*.tsx
# Root-level config files that must be updated for TypeScript support
tsconfig.json
tsconfig.build.json
babel.config.js
jest.config.js
# =============================================================================
# EXAMPLE: CSS-in-JS → CSS Modules Migration (different project layout)
# =============================================================================
# Uncomment and adapt for a different migration type:
#
# app/components/
# app/features/
# app/shared/ui/
# *.styles.ts
# *.module.css
# =============================================================================
# =============================================================================
# EXAMPLE: Rails route handler refactor
# =============================================================================
# Uncomment and adapt:
#
# app/controllers/
# app/serializers/
# spec/controllers/
# spec/requests/
# *.rb
# =============================================================================
# =============================================================================
# WHAT SHOULD NOT APPEAR IN THIS FILE
# =============================================================================
#
# Do NOT add patterns for:
#
# node_modules/ — never touched
# .git/ — never touched
# dist/ or build/ — build outputs, not source
# package.json — dependency changes require explicit approval (§ 2.4)
# package-lock.json — same
# yarn.lock — same
# Cargo.toml — same
# Gemfile — same
# *.env — environment files are never in scope
# CI/CD configs — .github/, .gitlab-ci.yml, Jenkinsfile, etc.
# Infrastructure configs — Dockerfile, fly.toml, terraform/, etc.
#
# If any of the above appear in `git diff --name-only` during the refactor,
# verify_scope.py will flag them and the agent must issue a ⏸ CHECKPOINT.
#
# =============================================================================
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |