oswright: Instructions file for GitHub Copilot

Working on OSWright

Windows desktop automation as an MCP server. The differentiator is the perception layer: it keeps a model of the screen between actions and re-reads only what changed, instead of returning a screenshot after every step.

Read CONTRIBUTING.md first — it has the project's conventions. This file is the operational detail an agent needs on top of them.

Start here, every session

If HANDOVER.md exists in the working copy, read it before doing anything else. It is gitignored local notes — current state, what is half-finished, and which weaknesses are known — and it is the only place that carries context between sessions. This file describes the project; that one describes where the work actually is.

Before ending a session, update it: correct Current state, adjust Open threads, add anything newly learned to Landmines, and prepend a short dated entry to the Session log. A conversation that ends without updating it has lost everything it learned.

If it does not exist, the repo is being read fresh — README.md and docs/ENGINEERING_LOG.md are the way in.

Orientation

document	what it is for
README.md	what the project claims, with numbers
CONTRIBUTING.md	conventions: measurement, safety, grading, style
docs/ENGINEERING_LOG.md	why things are the way they are, and 33 recorded mistakes

When something in the code looks wrong, search ENGINEERING_LOG.md before changing it. Most of the odd-looking decisions are odd deliberately and the reason is written down.

Commands

python -m pytest tests/ -q                  # full suite, ~6 s
python -m pytest tests/ -m "not e2e" -q     # skip the ones that drive a desktop
ruff check oswright tests benchmarks        # lint, must be clean
python -m build; python -m twine check dist/*   # what the release does

Tests needing a desktop or an OCR backend skip themselves rather than fail, so the suite stays meaningful on a headless runner. A skip is not a pass — check what skipped before concluding a change is safe.