Skip to content

AGENTS.md

Latest commit

 

History

History
76 lines (62 loc) · 3.33 KB

AGENTS.md

File metadata and controls

76 lines (62 loc) · 3.33 KB
Raw

Working on Watch Skill

Read this before changing anything. It is the short version of CONTRIBUTING.md and the rules in docs/DECISIONS.md.

What this project is

A local-first video layer for AI agents. It turns video into a persistent, searchable index with timestamped evidence, and closes a capture → critique → fix → proof loop over an agent's own work. Python 3.11+, MIT.

Layout

Path What lives there
src/watch_skill/ The engine. All logic.
src/watch_skill/surfaces/ MCP, CLI, REST. Thin wrappers only.
skills/ The ten agent skills. Canonical location — the skills CLI reads it.
commands/ Slash commands for the Claude Code plugin.
adapters/ Framework and harness adapters. No engine logic.
tests/ Mirrors the src/ layout.
docs/agents/ One page per supported agent, each with an honest status.

Commands

uv sync --extra all              # full dev environment
uv run pytest -m "not network"   # the offline suite — must be green
uv run ruff check .              # lint
uv run watch-skill doctor        # check the binaries the engine needs

Tests marked network hit the real internet and are excluded from the merge gate. Do not add network calls to the offline suite.

Rules that are not negotiable

  • The engine is agent-agnostic. No harness-specific branching in src/watch_skill/. That belongs in adapters/ or a skill.
  • Surfaces stay thin. MCP, CLI, and REST wrap the same functions. A behaviour that exists in one and not the others is a bug.
  • Every bug fix ships a regression test, and the test must fail against the old code. Verify that; do not assume it.
  • Index changes are forward migrations. Never rewrite history in the schema; add a migration.
  • MCP tool names are a contract. Renaming one breaks every configured agent. Add, don't rename.
  • Privacy invariants are tested in tests/test_privacy.py and listed in SECURITY.md. The video never leaves the machine; no cookies or logins; cloud speech-to-text is opt-in. Breaking one is a security bug.
  • Errors carry a fix. Every raised WatchSkillError needs a code and a sentence telling the reader what to do. tests/test_error_fix_audit.py enforces it.
  • Claims are checked. Prices live in a dated prices.json; benchmark numbers come from a recorded run; an agent page says whether it was machine-tested or only doc-verified. Do not write a claim you have not verified, and do not upgrade a status you did not earn.

Adding things

  • A vision provider: an entry in src/watch_skill/vision/registry.py. If it speaks OpenAI's /chat/completions, use _openai_compatible(...) and write no request code. Add the model defaults to health/vision_setup.py and a price to vision/prices.json — moving that file's as_of date is part of the edit.
  • An agent: start from templates/agent-adapter/. One config block, one page in docs/agents/, one validation run.
  • A skill: a directory under skills/ with a SKILL.md. The description is a trigger surface — write the phrasings a user would actually type, not a summary.

Style

Match the file you are editing. Comments explain why, never what. If a line needs a comment to say what it does, rewrite the line.