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 |
scripts/generate_allowlist.py
View on GitHub#!/usr/bin/env python3
"""
Generate scope allowlist from a refactoring spec file.
Reads the **IN SCOPE** section of a TASK_SPEC.md (or any spec file that follows
the large-scale-refactor template) and writes a .refactor-scope-allowlist file
containing one pattern per line. The allowlist is consumed by verify_scope.py.
Supported pattern types extracted from IN SCOPE checked items:
- Glob patterns : *.js *.tsx **/*.py
- Directory paths : src/ app/routes/ lib/
- File paths : config/settings.py Cargo.toml
- Bare extensions : .js .tsx (converted to *.ext)
Usage:
python generate_allowlist.py TASK_SPEC.md
python generate_allowlist.py TASK_SPEC.md --output .refactor-scope-allowlist
python generate_allowlist.py TASK_SPEC.md --dry-run
"""
import argparse
import re
import sys
from pathlib import Path
# ---------------------------------------------------------------------------
# Extraction helpers
# ---------------------------------------------------------------------------
def _extract_patterns_from_text(raw: str) -> list[str]:
"""
Pull every usable scope pattern out of a single IN SCOPE item's text.
Returns a deduplicated list of patterns in insertion order.
"""
found: list[str] = []
# 1. Glob patterns that already contain a wildcard: *.js **/*.tsx src/**
globs = re.findall(r"[\w\-\./]*\*[\w\-\./\*]*", raw)
found.extend(globs)
# 2. Directory-or-file paths: tokens containing at least one '/'
# Covers: src/components/ app/routes/ lib/auth.py tests/
# Excludes pure prose like "No logic changes" that has no slash.
paths = re.findall(r"[\w\-\.][\w\-\./]*(?:/[\w\-\./]*)+/?", raw)
for p in paths:
# Normalise: if it ends with a word char and is clearly a directory
# segment (no extension), add a trailing slash for clarity.
if p and not p.endswith("/") and "." not in Path(p).name:
p = p + "/"
found.append(p)
# 3. Bare extensions like .js or .tsx (not already captured as a glob)
bare_ext = re.findall(r"(?<!\w)\.([\w]+)(?!\w)", raw)
for ext in bare_ext:
found.append(f"*.{ext}")
return list(dict.fromkeys(p for p in found if p)) # preserve order, deduplicate
def extract_scope_patterns(spec_content: str) -> list[str]:
"""
Parse *spec_content* and return all scope patterns from the IN SCOPE block.
Understands two formats for the section header:
**IN SCOPE** (agent may touch): ← SKILL.md template bold marker
## IN SCOPE ← plain markdown heading
The block ends at the first OUT OF SCOPE marker or the next ## heading.
Only lines that are *checked* items (``- [x]`` or ``- [X]``) contribute
patterns; unchecked items (``- [ ]``) are skipped so a partially-filled
spec doesn't produce a misleadingly small allowlist. If no checked items
are found at all, *all* bullet items in the block are used as a fallback
so a brand-new spec with empty checkboxes still produces a useful allowlist.
.. note:: Fallback mode caveat
When no checked items exist, the fallback path operates on raw
descriptive prose (e.g. "Add TypeScript type annotations, change file
extensions from .js to .ts/.tsx"). The path regex may extract spurious
patterns from prose fragments like ``.ts/.tsx`` → ``ts/``. When using
unchecked specs, run with ``--dry-run`` first to inspect output before
committing the allowlist.
"""
patterns: list[str] = []
in_scope = False
checked_lines: list[str] = []
all_bullet_lines: list[str] = []
for line in spec_content.splitlines():
# ── Detect section start ──────────────────────────────────────────
if re.search(r"\*\*IN SCOPE\*\*|^#+\s*IN SCOPE", line, re.IGNORECASE):
in_scope = True
continue
# ── Detect section end ────────────────────────────────────────────
if in_scope:
if re.search(
r"\*\*OUT OF SCOPE\*\*|^#+\s*OUT OF SCOPE|^##\s+\S",
line,
re.IGNORECASE,
):
break
# Checked item: - [x] ... or - [X] ...
checked_match = re.match(r"\s*-\s*\[[xX]\]\s*(.*)", line)
if checked_match:
raw = checked_match.group(1).strip()
checked_lines.append(raw)
all_bullet_lines.append(raw)
continue
# Unchecked item: - [ ] ...
unchecked_match = re.match(r"\s*-\s*\[\s\]\s*(.*)", line)
if unchecked_match:
all_bullet_lines.append(unchecked_match.group(1).strip())
continue
# Plain bullet (no checkbox): - File types: *.js ...
plain_match = re.match(r"\s*[-*]\s+(.*)", line)
if plain_match:
all_bullet_lines.append(plain_match.group(1).strip())
# Use checked items if any exist; fall back to all bullets otherwise.
source_lines = checked_lines if checked_lines else all_bullet_lines
for text in source_lines:
patterns.extend(_extract_patterns_from_text(text))
# Final deduplication preserving insertion order
return list(dict.fromkeys(p for p in patterns if p))
# ---------------------------------------------------------------------------
# File I/O
# ---------------------------------------------------------------------------
def read_spec_file(spec_path: str) -> str:
try:
with open(spec_path, "r", encoding="utf-8") as f:
return f.read()
except FileNotFoundError:
print(f"Error: Spec file not found: {spec_path}", file=sys.stderr)
sys.exit(1)
except OSError as e:
print(f"Error reading spec file: {e}", file=sys.stderr)
sys.exit(1)
def write_allowlist(allowlist_path: str, patterns: list[str]) -> None:
header = (
"# Refactoring Scope Allowlist\n"
"# Generated by generate_allowlist.py from refactoring spec\n"
"#\n"
"# Pattern rules (interpreted by verify_scope.py):\n"
"# src/components/ — directory prefix (trailing slash)\n"
"# *.js — glob matched against full path and basename\n"
"# config/app.py — exact file path\n"
"#\n"
"# Edit this file to adjust scope before running verify_scope.py.\n\n"
)
try:
with open(allowlist_path, "w", encoding="utf-8") as f:
f.write(header)
for pattern in sorted(set(patterns)):
if pattern:
f.write(f"{pattern}\n")
except OSError as e:
print(f"Error writing allowlist: {e}", file=sys.stderr)
sys.exit(1)
# ---------------------------------------------------------------------------
# CLI
# ---------------------------------------------------------------------------
def main() -> None:
parser = argparse.ArgumentParser(
description="Generate a .refactor-scope-allowlist from a TASK_SPEC.md file.",
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog=__doc__,
)
parser.add_argument("spec_file", help="Path to the refactoring spec (TASK_SPEC.md)")
parser.add_argument(
"--output",
default=".refactor-scope-allowlist",
help="Destination allowlist file (default: .refactor-scope-allowlist)",
)
parser.add_argument(
"--dry-run",
action="store_true",
help="Print extracted patterns without writing any file",
)
args = parser.parse_args()
print("=== Scope Allowlist Generator ===")
print(f"Spec file : {args.spec_file}")
if not args.dry_run:
print(f"Output : {args.output}")
spec_content = read_spec_file(args.spec_file)
patterns = extract_scope_patterns(spec_content)
if not patterns:
print(
"\n⚠️ No scope patterns found in spec.\n"
" Make sure the spec contains an IN SCOPE section with checked items:\n\n"
" **IN SCOPE** (agent may touch):\n"
" - [x] File types: *.js, *.jsx\n"
" - [x] Directories: src/components/, src/utils/\n",
file=sys.stderr,
)
sys.exit(1)
unique_patterns = sorted(set(patterns))
print(f"\nExtracted {len(unique_patterns)} unique pattern(s):")
for i, pattern in enumerate(unique_patterns, 1):
print(f" {i:>3}. {pattern}")
if args.dry_run:
print("\n(Dry run — no file written)")
return
write_allowlist(args.output, patterns)
print(f"\n✅ Allowlist written to: {args.output}")
# Echo back what was written
try:
content = Path(args.output).read_text(encoding="utf-8")
print("\n--- allowlist contents ---")
print(content.rstrip())
print("--- end ---")
except OSError:
pass
if __name__ == "__main__":
main()
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 |