overkill 0.2.1__tar.gz

overkill-0.2.1/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

overkill-0.2.1/.github/workflows/test.yml

@@ -0,0 +1,33 @@
+name: Test
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Ruff check
+        run: uv run ruff check
+
+      - name: Mypy
+        run: uv run mypy src
+
+      - name: Pytest
+        run: uv run pytest

overkill-0.2.1/.gitignore

@@ -0,0 +1,35 @@
+# review-loop runtime logs (bin/../logs → repo-root /logs/)
+/logs/
+
+# Legacy log directory from previous versions
+.ai-review-logs/
+# review-loop self-hosted install
+.review-loop/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.venv/
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Testing / Coverage
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+.pytest_cache/
+test/tmp/
+
+# mypy / ruff / type checkers
+.mypy_cache/
+.ruff_cache/
+
+# Distribution / packaging
+*.whl

overkill-0.2.1/.python-version

@@ -0,0 +1 @@
+3.12

overkill-0.2.1/.refactorsuggestrc.example

@@ -0,0 +1,50 @@
+# .refactorsuggestrc — project-level configuration for refactor-suggest.sh
+# Copy this file to your project root as ".refactorsuggestrc" and customize.
+# CLI arguments always take precedence over these values.
+
+# Refactoring scope: auto | micro | module | layer | full (default: auto)
+# auto = pick largest feasible scope based on token budget at startup
+#   <75% used → module, 75-89% → micro, >=90% → error
+# SCOPE="auto"
+
+# Target branch to base the refactoring branch from (default: develop)
+# TARGET_BRANCH="develop"
+
+# Maximum analysis-fix iterations (default: unset, required via CLI)
+# MAX_LOOP=3
+
+# Maximum self-review sub-iterations per fix (default: 4, set 0 to disable)
+# MAX_SUBLOOP=4
+
+# Run analysis only, do not apply fixes (default: false)
+# DRY_RUN=false
+
+# Skip interactive confirmation for layer/full scope (default: false)
+# AUTO_APPROVE=false
+
+# Create a draft PR after completing all iterations (default: false)
+# CREATE_PR=false
+
+# Run review-loop automatically after PR creation (default: false)
+# WITH_REVIEW=false
+
+# Number of review-loop iterations when WITH_REVIEW=true (default: 4)
+# REVIEW_LOOPS=4
+
+# Path to active prompt templates (default: <script_dir>/../prompts/active)
+# PROMPTS_DIR="./custom-prompts"
+
+# ── Retry / Rate-Limit Settings ──────────────────────────────────────
+# Max total wait (seconds) for a single CLI call to recover from rate limits (default: 7200)
+# RETRY_MAX_WAIT=7200
+
+# Initial backoff delay (seconds); doubles each retry, capped at 300s (default: 30)
+# RETRY_INITIAL_WAIT=30
+
+# Pre-flight budget check scope: micro (<90%) or module (<75%) (default: module)
+# BUDGET_SCOPE="module"
+
+# ── Diagnostic Logging ──────────────────────────────────────────────
+# Save full Claude event stream (tool calls, reasoning) to .stream.jsonl files.
+# Useful for debugging missed findings. (default: false)
+# DIAGNOSTIC_LOG=false

overkill-0.2.1/.reviewlooprc.example

@@ -0,0 +1,36 @@
+# .reviewlooprc — project-level configuration for review-loop.sh
+# Copy this file to your project root as ".reviewlooprc" and customize.
+# CLI arguments always take precedence over these values.
+
+# Target branch to diff against (default: develop)
+# TARGET_BRANCH="main"
+
+# Maximum review-fix iterations (default: unset, required via CLI)
+# MAX_LOOP=5
+
+# Maximum self-review sub-iterations per fix (default: 4, set 0 to disable)
+# MAX_SUBLOOP=4
+
+# Run review only, do not fix (default: false)
+# DRY_RUN=false
+
+# Enable auto-commit of fixes (default: true)
+# AUTO_COMMIT=true
+
+# Path to active prompt templates (default: <script_dir>/../prompts/active)
+# PROMPTS_DIR="./custom-prompts"
+
+# ── Retry / Rate-Limit Settings ──────────────────────────────────────
+# Max total wait (seconds) for a single CLI call to recover from rate limits (default: 7200)
+# RETRY_MAX_WAIT=7200
+
+# Initial backoff delay (seconds); doubles each retry, capped at 300s (default: 30)
+# RETRY_INITIAL_WAIT=30
+
+# Pre-flight budget check scope: micro (<90%) or module (<75%) (default: module)
+# BUDGET_SCOPE="module"
+
+# ── Diagnostic Logging ──────────────────────────────────────────────
+# Save full Claude event stream (tool calls, reasoning) to .stream.jsonl files.
+# Useful for debugging missed findings. (default: false)
+# DIAGNOSTIC_LOG=false

overkill-0.2.1/AGENTS.md

@@ -0,0 +1,46 @@
+## Project Identity
+
+- **Repo**: `modocai/mr-overkill` (GitHub)
+- **PyPI package name**: `overkill` (pending publisher registered)
+- **Python import**: `mr_overkill` (source in `src/mr_overkill/`)
+- **CLI entrypoint**: `overkill` (subcommands: `review-loop`, `refactor-suggest`, `init`, `check-budget`)
+- **Version**: managed in `pyproject.toml` → `[project] version`
+- **CI/CD**: GitHub Actions — `publish.yml` triggers PyPI publish
+
+## Pull Request Rules
+
+Every PR must pass the review loop (`review-loop.sh --dry-run`) before merging. No exceptions. We eat our own dog food — if Mr. Overkill can't approve it, neither can you.
+
+## Branch Rules
+
+Always commit and push before ending work on any branch other than develop.
+Never commit directly to `main` or `develop`. All changes must go through branch → PR → review before merge.
+Never rebase or force-push `main` or `develop` — this destroys shared history.
+
+## PR Merge Process
+
+Before merging a PR, always fetch the target branch and check for new commits:
+
+```
+git fetch origin <target-branch>
+git log HEAD..origin/<target-branch> --oneline
+```
+
+**A) Target branch has new commits:**
+1. Merge the target branch into your feature branch (`git merge origin/<target-branch>`)
+2. Resolve conflicts if any
+3. Push the merge commit
+4. Re-run the review loop — the merged code must pass review again
+
+**B) Target branch is up to date:**
+1. Merge the PR:
+   - Feature branch → target: `gh pr merge --merge --delete-branch`
+   - `develop` → `main`: `gh pr merge --merge` (**never** `--delete-branch` — `develop` is a long-lived branch)
+2. Switch to the target branch, pull, and delete the local feature branch (if applicable)
+
+## Commit Messages
+
+Principles:
+- Write the subject in English, capturing the motivation/context of the change
+- Keep conventional commit prefixes (fix, feat, refactor, etc.)
+- Add a detailed body after a blank line if needed

overkill-0.2.1/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

overkill-0.2.1/GEMINI.md

@@ -0,0 +1 @@
+AGENTS.md

overkill-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ModocAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

overkill-0.2.1/PKG-INFO

@@ -0,0 +1,405 @@
+Metadata-Version: 2.4
+Name: overkill
+Version: 0.2.1
+Summary: AI-powered code review loop — automates Codex review + Claude fix cycles
+Project-URL: Repository, https://github.com/modocai/mr-overkill
+Project-URL: Issues, https://github.com/modocai/mr-overkill/issues
+Author: ModocAI
+License: MIT
+License-File: LICENSE
+Keywords: ai,automation,claude,code-review,codex,refactoring
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# :tophat: Mr. Overkill
+
+> **"Refactoring is not a task. It's a lifestyle."**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT) [![Token Cost](https://img.shields.io/badge/Token%20Cost-Bankrupt-red)](#) [![Efficiency](https://img.shields.io/badge/Efficiency-0%25-orange)](#) [![Over-Engineering](https://img.shields.io/badge/Over--Engineering-Max-blueviolet)](#)
+
+<img width="1024" height="1024" alt="image" src="https://github.com/user-attachments/assets/930a88d3-1224-47fc-bf5f-d9b367a8f29a" />
+
+
+**Mr. Overkill** is an automated loop that forces **Codex** (the pedantic reviewer) and **Claude** (the tired developer) into a locked room. They will not stop refactoring your code until it is "perfectly over-engineered" or your API credit runs out.
+
+## :warning: WARNING: FINANCIAL HAZARD
+
+**Do not run this script if you value your money.**
+
+This tool is designed to:
+
+1. :fire: **Burn Tokens:** It ignores "good enough" and strives for "unnecessarily complex."
+2. :money_with_wings: **Drain Wallets:** Requires OpenAI (Paid) AND Anthropic (Pro/Max) simultaneously.
+3. :infinity: **Loop Forever:** It might turn your "Hello World" into a Microservices Architecture.
+
+---
+
+## Quick Install (If you dare)
+
+```bash
+# Install the package
+pip install overkill          # or: uv tool install overkill / pipx install overkill
+
+# Initialize your project
+overkill init /path/to/your-project
+```
+
+Or use the convenience script from the source repo:
+
+```bash
+git clone --depth 1 https://github.com/modocai/mr-overkill.git /tmp/overkill \
+  && /tmp/overkill/install.sh /path/to/your-project \
+  && rm -rf /tmp/overkill
+```
+
+## :hammer_and_wrench: Prerequisites (The "Rich Dev" Starter Pack)
+
+You need these to participate in the madness:
+
+**Accounts** (yes, you need both — that's the point):
+
+- [OpenAI](https://platform.openai.com/) account (paid plan) — because free tier is for weak code
+- [Anthropic](https://console.anthropic.com/) account (Pro/Max plan or API credits) — because Claude needs to think *deeply* about your variable names
+
+**Runtime**:
+
+- [Python](https://www.python.org/) 3.12+ — for the `overkill` CLI
+- [Node.js](https://nodejs.org/) v18+ — Codex and Claude Code CLI are npm packages, so yes, you need this
+- A fast credit card — essential
+
+**CLI Tools**:
+
+```bash
+npm install -g @openai/codex        # Codex CLI
+npm install -g @anthropic-ai/claude-code  # Claude Code CLI
+```
+
+- [jq](https://jqlang.github.io/jq/) — JSON processor
+- [gh](https://cli.github.com/) — GitHub CLI (optional, for PR comments)
+- [envsubst](https://www.gnu.org/software/gettext/) — part of GNU gettext (macOS: `brew install gettext`)
+- [perl](https://www.perl.org/) — used for JSON extraction and deduplication (pre-installed on macOS and most Linux)
+- git
+
+## Quick Start
+
+```bash
+# In your project directory (after install):
+
+# Review loop — review and fix diffs against target branch
+overkill review-loop -n 3
+
+# Refactor suggest — analyze full codebase for refactoring opportunities
+overkill refactor-suggest -n 1 --dry-run
+```
+
+## Usage: overkill review-loop
+
+```
+overkill review-loop [OPTIONS]
+
+Options:
+  -t, --target <branch>    Target branch to diff against (default: develop)
+  -n, --max-loop <N>       Maximum review-fix iterations (required, unless --resume)
+  --max-subloop <N>        Maximum self-review sub-iterations per fix (default: 4)
+  --no-self-review         Disable self-review (equivalent to --max-subloop 0)
+  --dry-run                Run review only, do not fix
+  --no-auto-commit         Fix but do not commit/push (single iteration)
+  --resume                 Resume from a previously interrupted run (reuses existing logs)
+  --reviewer-backend <be>  Reviewer backend: claude|codex (default: codex)
+  --diagnostic-log         Save full Claude event stream to sidecar files
+
+Examples:
+  overkill review-loop -t main -n 3          # diff against main, max 3 loops
+  overkill review-loop -n 5                  # diff against develop, max 5 loops
+  overkill review-loop -n 1 --dry-run        # single review, no fixes
+  overkill review-loop -n 3 --no-self-review # disable self-review sub-loop
+  overkill review-loop --resume              # resume an interrupted run
+  overkill review-loop -n 2 --reviewer-backend claude  # use Claude as reviewer
+```
+
+## Usage: overkill refactor-suggest
+
+Unlike `review-loop` which reviews diffs, `refactor-suggest` analyzes the **entire codebase** for refactoring opportunities at a chosen scope level.
+
+```
+overkill refactor-suggest [OPTIONS]
+
+Options:
+  --scope <scope>          Refactoring scope: auto|micro|module|layer|full (default: auto)
+  -t, --target <branch>    Target branch to base from (default: develop)
+  -n, --max-loop <N>       Maximum analysis-fix iterations (default: 1)
+  --max-subloop <N>        Maximum self-review sub-iterations per fix (default: 4)
+  --no-self-review         Disable self-review (equivalent to --max-subloop 0)
+  --dry-run                Run analysis only, do not apply fixes
+  --no-dry-run             Force fixes even if .refactorsuggestrc sets DRY_RUN=true
+  --auto-approve           Skip interactive confirmation for layer/full scope
+  --create-pr              Create a draft PR after completing all iterations
+  --resume                 Resume from a previously interrupted run (reuses existing logs)
+  --with-review            Run review-loop after PR creation (default: 4 iterations)
+  --with-review-loops <N>  Set review-loop iteration count (implies --with-review)
+  --reviewer-backend <be>  Reviewer backend: claude|codex (default: codex)
+  --diagnostic-log         Save full Claude event stream to sidecar files
+
+Examples:
+  overkill refactor-suggest -n 3                             # auto scope (budget-aware)
+  overkill refactor-suggest --scope micro -n 3               # function/file-level fixes
+  overkill refactor-suggest --scope module -n 2 --dry-run    # analyze module duplication
+  overkill refactor-suggest --scope layer -n 1 --auto-approve  # cross-cutting concerns
+  overkill refactor-suggest --scope full -n 1 --create-pr    # architecture redesign + PR
+  overkill refactor-suggest -n 2 --with-review               # auto scope + auto review
+  overkill refactor-suggest --scope module -n 3 --with-review-loops 6 # custom review
+```
+
+## Usage: overkill init
+
+Initialize `.review-loop/` in a project directory. Safe to re-run — prompts are refreshed, user-edited configs are preserved.
+
+```
+overkill init [TARGET_DIR]   # default: current directory
+```
+
+Creates:
+
+```
+.review-loop/
+├── prompts/active/          # 10 prompt templates
+├── .reviewlooprc            # review-loop config
+├── .refactorsuggestrc       # refactor-suggest config
+├── logs/                    # runtime logs
+│   └── refactor/            # refactor-suggest logs
+└── .install-manifest        # tracks tool-owned files
+```
+
+### Scopes
+
+| Scope | What it looks for | Blast radius |
+|-------|-------------------|--------------|
+| `auto` | Budget-aware automatic selection (default) | Varies — picks the highest scope your token budget allows |
+| `micro` | Complex functions, dead code, in-file duplication | Low — single file |
+| `module` | Cross-file duplication, module boundary issues | Low-medium — within a module |
+| `layer` | Inconsistent error handling, logging, config patterns | Medium-high — across modules |
+| `full` | Wrong abstractions, inverted dependencies, layer violations | High-critical — project-wide |
+
+### How refactor-suggest works
+
+```
+1. Collect source file list (git ls-files)
+2. Reviewer (Codex or Claude) analyzes the full codebase for scope-specific refactoring opportunities
+3. (layer/full) Display refactoring plan and wait for confirmation
+4. Claude applies refactoring (two-step: opinion → execute)
+5. Claude self-reviews changes, re-fixes if needed
+6. Auto-commit & push to refactoring branch
+7. Repeat until clean or max iterations reached
+8. (--create-pr) Create draft PR
+9. (--with-review) Run review-loop on the new PR
+```
+
+Recommended workflow: start with `--dry-run` to review findings, then re-run without it to apply.
+
+## Configuration
+
+After running `overkill init`, config files live in `.review-loop/`:
+
+### .review-loop/.reviewlooprc
+
+```bash
+TARGET_BRANCH="main"
+MAX_LOOP=5
+MAX_SUBLOOP=4
+AUTO_COMMIT=true
+REVIEWER_BACKEND="codex"    # or "claude"
+PROMPTS_DIR="./custom-prompts"
+```
+
+See `.review-loop/.reviewlooprc` for all available options.
+
+### .review-loop/.refactorsuggestrc
+
+```bash
+SCOPE="auto"
+TARGET_BRANCH="develop"
+MAX_LOOP=3
+MAX_SUBLOOP=4
+# DRY_RUN: safe default — remove to apply fixes (script default: false)
+DRY_RUN=true
+AUTO_APPROVE=false
+CREATE_PR=false
+WITH_REVIEW=false
+REVIEW_LOOPS=4
+REVIEWER_BACKEND="codex"    # or "claude"
+PROMPTS_DIR="./custom-prompts"
+```
+
+## How review-loop works
+
+```
+1. Check prerequisites (git, codex, claude, jq, envsubst, target branch)
+2. Create .review-loop/logs/ directory
+3. Loop (iteration 1..N):
+   a. Generate diff: git diff $TARGET...$CURRENT
+   b. Empty diff → exit
+   c. Reviewer (Codex or Claude, via --reviewer-backend) reviews the diff → JSON with findings
+   d. No findings + "patch is correct" → exit
+   e. Claude fixes all issues (P0-P3)
+   f. Sub-loop (1..MAX_SUBLOOP):
+      - Claude self-reviews the uncommitted fixes (git diff)
+      - If clean → break
+      - Claude re-fixes based on self-review findings
+   g. Auto-commit all fixes + re-fixes to branch
+   h. Push to remote (updates PR)
+   i. Post review/fix/self-review summary as PR comment
+   j. Next iteration reviews the updated committed state
+4. Write summary to .review-loop/logs/summary.md
+```
+
+## Output Files
+
+All logs are git-ignored by default (inside `.review-loop/`).
+
+### review-loop logs (`.review-loop/logs/`)
+
+| File | Description |
+|------|-------------|
+| `review-N.json` | Codex review output for iteration N |
+| `opinion-N.md` | Claude's opinion on review findings (iteration N) |
+| `fix-N.md` | Claude fix log for iteration N |
+| `self-review-N-M.json` | Claude self-review output (iteration N, sub-iteration M) |
+| `refix-opinion-N-M.md` | Claude's opinion on self-review findings (iteration N, sub M) |
+| `refix-N-M.md` | Claude re-fix log (iteration N, sub-iteration M) |
+| `summary.md` | Final summary with status and per-iteration results |
+
+### refactor-suggest logs (`.review-loop/logs/refactor/`)
+
+| File | Description |
+|------|-------------|
+| `source-files.txt` | List of files analyzed (from `git ls-files`) |
+| `review-N.json` | Codex refactoring analysis for iteration N |
+| `opinion-N.md` | Claude's opinion on refactoring findings (iteration N) |
+| `fix-N.md` | Claude fix log for iteration N |
+| `self-review-N-M.json` | Claude self-review (iteration N, sub-iteration M) |
+| `refix-opinion-N-M.md` | Claude's opinion on self-review findings |
+| `refix-N-M.md` | Claude re-fix log (iteration N, sub-iteration M) |
+| `summary.md` | Final summary with scope, status, and per-iteration results |
+
+## Token Budget Checker
+
+The budget checker verifies Claude Code's 5-hour rate limit **before** starting expensive loops.
+
+### How it estimates usage
+
+| Mode | Data source | Accuracy |
+|------|-------------|----------|
+| **OAuth** (primary) | macOS Keychain → `security find-generic-password` → Anthropic OAuth API (`/oauth/usage`) | Exact — returns `five_hour.utilization` and `seven_day.utilization` directly from Anthropic |
+| **Local** (fallback) | `~/.claude/projects/**/*.jsonl` session files — sums `input_tokens + output_tokens + cache_creation_input_tokens + cache_read_input_tokens` from `message.usage` of assistant messages in the last 5 hours | Estimated — actual server-side limits are opaque; weekly usage (`seven_day_used_pct`) is unavailable (`null`) |
+
+**Tier detection** reads `rateLimitTier` from `~/.claude/telemetry/*.json` (field `event_data.user_attributes`). Mapping: `default` → pro, `default_claude_max_5x` → max5, `default_claude_max_20x` → max20.
+
+### Scope thresholds
+
+Go/no-go decision based on current usage percentage:
+
+| Scope | Go if used < | Typical use |
+|-------|-------------|-------------|
+| `micro` | 90% | Small single-file fix |
+| `module` | 75% | Multi-file refactoring |
+| `layer` | TBD | Cross-cutting changes |
+| `full` | TBD | Full architecture review |
+
+## Customizing Prompts
+
+Edit the templates in `.review-loop/prompts/active/`.
+
+### review-loop prompts
+
+- **`codex-review.prompt.md`** — Review prompt sent to Codex. Uses variables: `${CURRENT_BRANCH}`, `${TARGET_BRANCH}`, `${ITERATION}`.
+- **`claude-review.prompt.md`** — Review prompt for Claude reviewer (symlink to codex-review by default).
+- **`claude-fix.prompt.md`** — Opinion prompt: Claude evaluates review findings. Uses: `${REVIEW_JSON}`, `${CURRENT_BRANCH}`, `${TARGET_BRANCH}`.
+- **`claude-fix-execute.prompt.md`** — Execute prompt: tells Claude to fix based on its opinion.
+- **`claude-self-review.prompt.md`** — Self-review prompt for Claude to check its own fixes. Uses: `${REVIEW_JSON}`, `${CURRENT_BRANCH}`, `${TARGET_BRANCH}`, `${ITERATION}`.
+
+### refactor-suggest prompts
+
+Each scope has a dedicated prompt with scope-specific instructions, anti-pattern guardrails, and good/bad finding examples:
+
+- **`codex-refactor-{micro,module,layer,full}.prompt.md`** — Codex reviewer prompts per scope.
+- **`claude-refactor-{micro,module,layer,full}.prompt.md`** — Claude reviewer prompts (symlinks to codex versions by default).
+
+All refactor prompts use variables: `${TARGET_BRANCH}`, `${ITERATION}`, `${SOURCE_FILES_PATH}`.
+
+- **`claude-refactor-fix.prompt.md`** — Opinion prompt: Claude evaluates refactoring findings with scope-aware judgment. Uses: `${REVIEW_JSON}`, `${CURRENT_BRANCH}`, `${TARGET_BRANCH}`.
+- **`claude-refactor-fix-execute.prompt.md`** — Execute prompt with safety guards (syntax check, scope overflow detection, regression testing).
+
+Reference prompts (read-only originals) are in `prompts/reference/`.
+
+## Priority Levels
+
+| Level | Meaning | Action |
+|-------|---------|--------|
+| P0 | Blocking release | Fixed by Claude |
+| P1 | Urgent | Fixed by Claude |
+| P2 | Normal | Fixed by Claude |
+| P3 | Low / nice-to-have | Fixed by Claude |
+
+## Exit Conditions
+
+The loop terminates when any of these occur:
+
+- **all_clear** — No findings and overall verdict is "patch is correct"
+- **no_diff** — No changes between branches
+- **dry_run** — Review-only mode
+- **max_iterations_reached** — Hit the `-n` limit
+- **auto_commit_disabled** — `--no-auto-commit` or `AUTO_COMMIT=false`; fixes applied but not committed
+- **parse_error** — Could not parse Codex output as JSON
+
+## Uninstall
+
+```bash
+# Quick — just nuke the directory
+rm -rf .review-loop
+
+# Also remove the Python package
+pip uninstall overkill       # or: uv tool uninstall overkill / pipx uninstall overkill
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feat/my-feature`)
+3. Commit your changes
+4. Open a Pull Request against `develop`
+5. Run `overkill review-loop -n 3 --dry-run` on your PR branch — **required**. Let Mr. Overkill review your code before a human ever sees it.
+
+## Development
+
+```bash
+git clone https://github.com/modocai/mr-overkill.git
+cd mr-overkill
+uv sync                      # install dev dependencies
+uv run pytest                # run tests
+uv run ruff check src/ tests/
+uv run mypy src/
+```
+
+## Testing
+
+```bash
+# Python tests
+uv run pytest --tb=short
+
+# Bash integration tests (requires bats-core)
+brew install bats-core       # one-time setup
+bats test/                   # run all tests
+```
+
+## License
+
+[MIT](LICENSE) &copy; 2026 ModocAI