Overwatcher

A supervisor skill for multi-agent coding workflows. Splits work into disjoint file domains, then rejects worker output that breaks its contract or fails verification.

Quick start · How it works · CLI · Examples · Contributing

Why

Unsupervised agent pipelines tend to fail in three ways:

• Drift: workers edit files outside their task and break shared config.
• Collisions: parallel workers edit the same files and create merge conflicts.
• False "done": workers report "all tests pass" after deleting assertions, adding assert True, or wrapping errors in except: pass.

Overwatcher counters each:

Quick start

1. Install CLI & Python package

# Install via pip:
pip install overwatcher-ai

# Or install directly from GitHub:
pip install git+https://github.com/FahadBinNasir/overwatcher.git

2. Install as an Agent Skill

Claude Code shown; other platforms below:

mkdir -p .claude/skills/overwatcher
cp SKILL.md .claude/skills/overwatcher/SKILL.md

Then ask your agent:

Use the overwatcher skill to refactor auth and the DB layer in parallel.

The agent acts as supervisor: it partitions the task, dispatches workers, audits each result, and returns a verification report.

How it works

flowchart TD
    A[1. Partition & contracts] --> B[2. Parallel dispatch]
    B --> C[3. Cross-examination]
    C -->|fail| D[Rejection notice]
    D --> B
    C -->|pass| E[4. Synthesis & report]

Rules

1. No trust in summaries. Output is unverified until inspected and executed.
2. Adversarial review. Look for edge cases, race conditions, leaks, and swallowed errors.
3. Disjoint ownership. Workers never touch overlapping files.
4. Reject, don't patch. Send failures back with line-numbered proof. The supervisor only patches after repeated worker failures.

Phases

1. Partition. Split the goal into 2–4 independent domains (e.g. Auth, DB, API, UI). Give each worker a contract:

• Authorized targets: exact file paths
• Acceptance criteria: deliverables and test targets
• Forbidden: mock fallbacks, leaked secrets, API breakage

2. Dispatch. Start workers concurrently with domain-specific prompts. Wait on completion signals; don't poll.

3. Cross-examine. When a worker reports done:

1. Diff: confirm changes stay inside the contract; reject mocks, boilerplate, and new dependencies. The CLI automates the file-boundary and pattern checks.
2. Build: run the project's compilers and linters (tsc --noEmit, ruff, flake8, ...).
3. Test: run the targeted tests; check that assertions are real.
4. Verdict: REJECTION NOTICE on any defect, otherwise AUDITED & VERIFIED.

4. Synthesize. Run the full regression suite, then produce the master report with logs.

Cross-examiner CLI

Run via the installed overwatcher command or directly via scripts/cross_examiner.py. It requires only Python 3.8+ and git; no LLM needed.

# Run via installed CLI:
overwatcher \
  --worker "auth_guard" \
  --domain "Authentication" \
  --allowed-files "src/core/auth.py" "tests/test_auth.py" \
  --verify-cmd "pytest tests/test_auth.py -v" \
  --repo-dir .

# Or run via standalone script:
python scripts/cross_examiner.py ...

Checks

1. Boundaries: files from git status must match an allowed glob (full path or basename, via fnmatch).
2. Diff patterns: added lines in git diff HEAD are regex-scanned for:
   • except: pass, except Exception: pass, empty catch (...) {}
   • assert True, assert 1 == 1, expect(true).toBe(true)
   • debugger, breakpoint()
3. Verify command: run in the repo; non-zero exit is a failure (last 10 output lines are reported).

Exit codes: 0 = AUDITED & VERIFIED, 1 = REJECTED (prints a rejection notice).

Limitations

• Pattern matching is regex on diff text, not AST analysis. It catches common shortcuts, not all.
• Audits the working tree against HEAD. Uncommitted changes only.
• With parallel workers in one working tree, each audit sees the others' edits as violations. Give each worker its own git worktree or branch.
• Basename matching means auth.py also matches other/dir/auth.py. Use full-path globs.
• Untracked files count toward the boundary check, but their contents are not pattern-scanned.
• --verify-cmd runs with shell=True. Pass only trusted commands.
• Linters and builds run only if you put them in --verify-cmd.

Run its tests:

python tests/test_cross_examiner.py

Platform install paths

Message formats

[OVERWATCHER REJECTION NOTICE]
Worker ID: {worker_name}
Target Domain: {domain_name}
Status: REJECTED — REWORK REQUIRED

1. Flaws Detected:
   - File: {file_path}:{line_number}
     Issue: {defect}
     Evidence: {failing_test_output_or_diff_snippet}

2. Required Remediation:
   - {instruction}

Re-submit only after passing: `{verification_command}`.

# Overwatcher Master Verification Report

## Summary
- Domains audited: 2
- Workers: 2
- Cross-examination rounds: 3
- Status: VERIFIED / ZERO REGRESSIONS

## Breakdown
| Domain | Worker | Files | Status | Evidence |
| :-- | :-- | :-- | :-- | :-- |
| Auth | auth_guard | src/core/auth.py | PASSED | 8/8 tests |
| DB | db_reliability | src/core/db.py | PASSED | 14/14 tests |

Examples

Repository layout

pyproject.toml        # PEP 517 / PEP 621 package config
SKILL.md              # skill spec
src/overwatcher/      # core Python package & CLI implementation
templates/            # contract, rejection, report templates
scripts/              # standalone wrapper script
tests/                # cross_examiner tests
examples/             # worked examples
assets/               # logo, icons, and social banner

Contributing

New audit rules, heuristics, and language support are welcome.

1. Fork and branch: git checkout -b feature/audit-rule
2. Add tests; run python tests/test_cross_examiner.py
3. Open a PR

License

MIT © 2026 Fahad Bin Nasir